chore: migrate cross-boundary relative imports to path aliases

bin.ts

@@ -3,9 +3,9 @@
 
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
-import { VERSION } from './src/lib/version.js';
+import { VERSION } from '@lib/version';
 
 const WIZARD_VERSION = VERSION;
 
 const NODE_VERSION_RANGE = '>=18.17.0';
 
@@ -19,16 +19,16 @@
   process.exit(1);
 }
 
-import { isNonInteractiveEnvironment } from './src/utils/environment';
-import { getUI, setUI } from './src/ui';
-import { LoggingUI } from './src/ui/logging-ui';
+import { isNonInteractiveEnvironment } from '@utils/environment';
+import { getUI, setUI } from '@ui';
+import { LoggingUI } from '@ui/logging-ui';
 import {
   getSubcommandPrograms,
   Program,
-} from './src/lib/programs/program-registry';
-import type { ProgramConfig } from './src/lib/programs/program-step';
-import type { WizardSession } from './src/lib/wizard-session';
-import { POSTHOG_DOCS_URL } from './src/lib/constants';
+} from '@lib/programs/program-registry';
+import type { ProgramConfig } from '@lib/programs/program-step';
+import type { WizardSession } from '@lib/wizard-session';
+import { POSTHOG_DOCS_URL } from '@lib/constants';
 import { runtimeEnv } from '@env';
 
 // Test mock server — only loaded when NODE_ENV is 'test'.
@@ -258,7 +258,7 @@
             getUI().intro('PostHog Wizard');
             try {
               const { provisionNewAccount } = await import(
-                './src/utils/provisioning.js'
+                '@utils/provisioning'
               );
               const signupRegion = (options.region as string).toUpperCase() as
                 | 'US'
@@ -298,14 +298,14 @@
           }
 
           const { posthogIntegrationConfig } = await import(
-            './src/lib/programs/posthog-integration/index.js'
+            '@lib/programs/posthog-integration/index'
           );
-          const { FRAMEWORK_REGISTRY } = await import('./src/lib/registry.js');
+          const { FRAMEWORK_REGISTRY } = await import('@lib/registry');
           const { detectFramework, gatherFrameworkContext } = await import(
-            './src/lib/detection/index.js'
+            '@lib/detection/index'
           );
-          const { analytics } = await import('./src/utils/analytics.js');
-          const { wizardAbort } = await import('./src/utils/wizard-abort.js');
+          const { analytics } = await import('@utils/analytics');
+          const { wizardAbort } = await import('@utils/wizard-abort');
 
           // preRun: honor --integration, else auto-detect, then gather
           // framework context. Bypasses onReady hooks by design.
@@ -362,15 +362,15 @@
         // Playground mode: launch the TUI primitives playground
         void (async () => {
           const { startPlayground } = await import(
-            './src/ui/tui/playground/start-playground.js'
+            '@ui/tui/playground/start-playground'
           );
           (startPlayground as (version: string) => void)(WIZARD_VERSION);
         })();
       } else if (options.skill) {
         // Run a specific skill by ID
         void (async () => {
           const { createSkillProgram } = await import(
-            './src/lib/programs/agent-skill/index.js'
+            '@lib/programs/agent-skill/index'
           );
           const skillId = options.skill as string;
           const config = createSkillProgram({
@@ -392,7 +392,7 @@
         // Same codepath as `npx @posthog/wizard integrate`.
         void (async () => {
           const { posthogIntegrationConfig } = await import(
-            './src/lib/programs/posthog-integration/index.js'
+            '@lib/programs/posthog-integration/index'
           );
           runWizard(posthogIntegrationConfig, options);
         })();
@@ -432,18 +432,18 @@
             .filter(Boolean);
           void (async () => {
             const { readApiKeyFromEnv } = await import(
-              './src/utils/env-api-key.js'
+              '@utils/env-api-key'
             );
             const apiKey =
               (options.apiKey as string | undefined) || readApiKeyFromEnv();
 
             try {
-              const { startTUI } = await import('./src/ui/tui/start-tui.js');
+              const { startTUI } = await import('@ui/tui/start-tui');
               const { buildSession } = await import(
-                './src/lib/wizard-session.js'
+                '@lib/wizard-session'
               );
 
               const tui = startTUI(WIZARD_VERSION, Program.McpAdd);
               const session = buildSession({
                 debug: options.debug,
                 localMcp: options.local,
@@ -455,7 +455,7 @@
               // TUI unavailable — fallback to logging
               setUI(new LoggingUI());
               const { addMCPServerToClientsStep } = await import(
-                './src/steps/add-mcp-server-to-clients/index.js'
+                '@steps/add-mcp-server-to-clients/index'
               );
               await addMCPServerToClientsStep({
                 local: options.local,
@@ -483,12 +483,12 @@
           const options = { ...argv };
           void (async () => {
             try {
-              const { startTUI } = await import('./src/ui/tui/start-tui.js');
+              const { startTUI } = await import('@ui/tui/start-tui');
               const { buildSession } = await import(
-                './src/lib/wizard-session.js'
+                '@lib/wizard-session'
               );
 
               const tui = startTUI(WIZARD_VERSION, Program.McpRemove);
               const session = buildSession({
                 debug: options.debug,
                 localMcp: options.local,
@@ -498,7 +498,7 @@
               // TUI unavailable — fallback to logging
               setUI(new LoggingUI());
               const { removeMCPServerFromClientsStep } = await import(
-                './src/steps/add-mcp-server-to-clients/index.js'
+                '@steps/add-mcp-server-to-clients/index'
               );
               await removeMCPServerFromClientsStep({
                 local: options.local,
@@ -558,7 +558,7 @@
     void (async () => {
       try {
         const { provisionNewAccount } = await import(
-          './src/utils/provisioning.js'
+          '@utils/provisioning'
         );
         if (!jsonMode) {
           getUI().log.info(`Provisioning account for ${email} in ${region}...`);
@@ -598,7 +598,7 @@
 // ── Skill-based program subcommands (derived from registry) ─────────
 for (const programConfig of getSubcommandPrograms()) {
   cli.command(
     programConfig.command!,
     programConfig.description,
     (y) =>
       y.options({
@@ -638,18 +638,18 @@
     try {
       const installDir = (options.installDir as string) || process.cwd();
 
-      const { startTUI } = await import('./src/ui/tui/start-tui.js');
-      const { buildSession } = await import('./src/lib/wizard-session.js');
-      const { TaskStreamPush } = await import('./src/lib/task-stream/index.js');
+      const { startTUI } = await import('@ui/tui/start-tui');
+      const { buildSession } = await import('@lib/wizard-session');
+      const { TaskStreamPush } = await import('@lib/task-stream/index');
       const { FileDestination } = await import(
-        './src/lib/task-stream/destinations/file.js'
+        '@lib/task-stream/destinations/file'
       );
       const { PostHogDestination } = await import(
-        './src/lib/task-stream/destinations/posthog.js'
+        '@lib/task-stream/destinations/posthog'
       );
-      const { analytics } = await import('./src/utils/analytics.js');
+      const { analytics } = await import('@utils/analytics');
 
       const tui = startTUI(WIZARD_VERSION, config.id as any);
 
       const session = buildSession({
         debug: options.debug as boolean | undefined,
@@ -662,7 +662,7 @@
         projectId: options.projectId as string | undefined,
         email: options.email as string | undefined,
         menu: options.menu as boolean | undefined,
         integration: options.integration as any,
         benchmark: options.benchmark as boolean | undefined,
         yaraReport: options.yaraReport as boolean | undefined,
       });
@@ -691,7 +691,7 @@
 
       if (skipAgent) {
         const { getOrAskForProjectData } = await import(
-          './src/utils/setup-utils.js'
+          '@utils/setup-utils'
         );
         const { projectApiKey, host, accessToken, projectId } =
           await getOrAskForProjectData({
@@ -707,7 +707,7 @@
           projectId,
         });
       } else {
-        const { runAgent } = await import('./src/lib/agent/agent-runner.js');
+        const { runAgent } = await import('@lib/agent/agent-runner');
         await runAgent(config, tui.store.session);
       }
 
@@ -774,14 +774,14 @@
 
   void (async () => {
     const path = await import('path');
-    const { buildSession } = await import('./src/lib/wizard-session.js');
-    const { readEnvironment } = await import('./src/utils/environment.js');
-    const { readApiKeyFromEnv } = await import('./src/utils/env-api-key.js');
+    const { buildSession } = await import('@lib/wizard-session');
+    const { readEnvironment } = await import('@utils/environment');
+    const { readApiKeyFromEnv } = await import('@utils/env-api-key');
     const { configureLogFileFromEnvironment, logToFile } = await import(
-      './src/utils/debug.js'
+      '@utils/debug'
     );
     const { wizardAbort, WizardError } = await import(
-      './src/utils/wizard-abort.js'
+      '@utils/wizard-abort'
     );
 
     configureLogFileFromEnvironment();
@@ -857,7 +857,7 @@
         }
       }
 
-      const { runAgent } = await import('./src/lib/agent/agent-runner.js');
+      const { runAgent } = await import('@lib/agent/agent-runner');
       await runAgent(config, session);
     } catch (error) {
       const errorMessage =

package.json

@@ -156,7 +156,9 @@
       "^@env$": "<rootDir>/src/env.ts",
       "^@lib/(.*)$": "<rootDir>/src/lib/$1",
       "^@utils/(.*)$": "<rootDir>/src/utils/$1",
+      "^@ui$": "<rootDir>/src/ui/index.ts",
       "^@ui/(.*)$": "<rootDir>/src/ui/$1",
+      "^@steps$": "<rootDir>/src/steps/index.ts",
       "^@steps/(.*)$": "<rootDir>/src/steps/$1",
       "^@frameworks/(.*)$": "<rootDir>/src/frameworks/$1",
       "^(\\.{1,2}/.*)\\.js$": "$1"

src/__tests__/package-json.test.ts

@@ -7,7 +7,7 @@ import {
   hasPackageInstalled,
   findInstalledPackageFromList,
   type PackageDotJson,
-} from '../utils/package-json';
+} from '@utils/package-json';
 
 describe('getPackageVersion', () => {
   it('returns version from dependencies', () => {

src/__tests__/wizard-abort.test.ts

@@ -4,8 +4,8 @@ import {
   WizardError,
   registerCleanup,
   clearCleanup,
-} from '../utils/wizard-abort';
-import { analytics } from '../utils/analytics';
+} from '@utils/wizard-abort';
+import { analytics } from '@utils/analytics';
 
 jest.mock('../utils/analytics');
 jest.mock('../ui', () => ({
@@ -184,7 +184,7 @@ describe('abort() delegates to wizardAbort()', () => {
   });
 
   it('abort() calls wizardAbort with message and exitCode', async () => {
-    const { abort } = await import('../utils/setup-utils.js');
+    const { abort } = await import('@utils/setup-utils');
 
     await expect(abort('Test abort', 3)).rejects.toThrow('process.exit called');
 
@@ -195,7 +195,7 @@ describe('abort() delegates to wizardAbort()', () => {
   });
 
   it('abort() uses defaults when called with no args', async () => {
-    const { abort } = await import('../utils/setup-utils.js');
+    const { abort } = await import('@utils/setup-utils');
 
     await expect(abort()).rejects.toThrow('process.exit called');
 

src/frameworks/android/android-wizard-agent.ts

@@ -1,7 +1,7 @@
 /* Android (Kotlin) wizard using posthog-agent with PostHog MCP */
-import type { WizardOptions } from '../../utils/types';
-import type { FrameworkConfig } from '../../lib/framework-config';
-import { Integration } from '../../lib/constants';
+import type { WizardOptions } from '@utils/types';
+import type { FrameworkConfig } from '@lib/framework-config';
+import { Integration } from '@lib/constants';
 import fg from 'fast-glob';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -10,7 +10,7 @@ import {
   getKotlinVersionBucket,
   getMinSdkVersion,
 } from './utils';
-import { gradlePackageManager } from '../../lib/detection/package-manager';
+import { gradlePackageManager } from '@lib/detection/package-manager';
 
 type AndroidContext = {
   kotlinVersion?: string;

src/frameworks/android/utils.ts

@@ -1,5 +1,5 @@
-import type { WizardOptions } from '../../utils/types';
-import { createVersionBucket } from '../../utils/semver';
+import type { WizardOptions } from '@utils/types';
+import { createVersionBucket } from '@utils/semver';
 import fg from 'fast-glob';
 import * as fs from 'node:fs';
 import * as path from 'node:path';

src/frameworks/angular/angular-wizard-agent.ts

@@ -1,15 +1,15 @@
 /* Angular wizard using posthog-agent with PostHog MCP */
-import type { WizardOptions } from '../../utils/types';
-import type { FrameworkConfig } from '../../lib/framework-config';
-import { detectNodePackageManagers } from '../../lib/detection/package-manager';
-import { Integration } from '../../lib/constants';
+import type { WizardOptions } from '@utils/types';
+import type { FrameworkConfig } from '@lib/framework-config';
+import { detectNodePackageManagers } from '@lib/detection/package-manager';
+import { Integration } from '@lib/constants';
 import {
   getPackageVersion,
   getInstalledPackageVersion,
   hasPackageInstalled,
   type PackageDotJson,
-} from '../../utils/package-json';
-import { tryGetPackageJson } from '../../utils/setup-utils';
+} from '@utils/package-json';
+import { tryGetPackageJson } from '@utils/setup-utils';
 import { getAngularVersionBucket } from './utils';
 
 type AngularContext = Record<string, unknown>;

src/frameworks/angular/utils.ts

@@ -1,4 +1,4 @@
-import { createVersionBucket } from '../../utils/semver';
+import { createVersionBucket } from '@utils/semver';
 
 /**
  * Get Angular version bucket for analytics

src/frameworks/astro/astro-wizard-agent.ts

@@ -1,16 +1,16 @@
 /* Astro wizard using posthog-agent with PostHog MCP */
-import type { WizardOptions } from '../../utils/types';
-import type { FrameworkConfig } from '../../lib/framework-config';
-import { detectNodePackageManagers } from '../../lib/detection/package-manager';
-import { Integration } from '../../lib/constants';
+import type { WizardOptions } from '@utils/types';
+import type { FrameworkConfig } from '@lib/framework-config';
+import { detectNodePackageManagers } from '@lib/detection/package-manager';
+import { Integration } from '@lib/constants';
 import {
   getPackageVersion,
   getInstalledPackageVersion,
   hasPackageInstalled,
   type PackageDotJson,
-} from '../../utils/package-json';
-import { tryGetPackageJson } from '../../utils/setup-utils';
-import { getUI } from '../../ui';
+} from '@utils/package-json';
+import { tryGetPackageJson } from '@utils/setup-utils';
+import { getUI } from '@ui';
 import {
   getAstroRenderingMode,
   getAstroVersionBucket,

src/frameworks/astro/utils.ts

@@ -1,8 +1,8 @@
 import fg from 'fast-glob';
 import fs from 'fs/promises';
 import path from 'path';
-import type { WizardOptions } from '../../utils/types';
-import { createVersionBucket } from '../../utils/semver';
+import type { WizardOptions } from '@utils/types';
+import { createVersionBucket } from '@utils/semver';
 
 export const getAstroVersionBucket = createVersionBucket();
 

src/frameworks/django/django-wizard-agent.ts

@@ -1,9 +1,9 @@
 /* Django wizard using posthog-agent with PostHog MCP */
-import type { WizardOptions } from '../../utils/types';
-import type { FrameworkConfig } from '../../lib/framework-config';
-import { PYTHON_PACKAGE_INSTALLATION } from '../../lib/framework-config';
-import { detectPythonPackageManagers } from '../../lib/detection/package-manager';
-import { Integration } from '../../lib/constants';
+import type { WizardOptions } from '@utils/types';
+import type { FrameworkConfig } from '@lib/framework-config';
+import { PYTHON_PACKAGE_INSTALLATION } from '@lib/framework-config';
+import { detectPythonPackageManagers } from '@lib/detection/package-manager';
+import { Integration } from '@lib/constants';
 import fg from 'fast-glob';
 import * as fs from 'node:fs';
 import * as path from 'node:path';

src/frameworks/django/utils.ts

@@ -1,7 +1,7 @@
 import fg from 'fast-glob';
-import { getUI } from '../../ui';
-import type { WizardOptions } from '../../utils/types';
-import { createVersionBucket } from '../../utils/semver';
+import { getUI } from '@ui';
+import type { WizardOptions } from '@utils/types';
+import { createVersionBucket } from '@utils/semver';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 

src/frameworks/fastapi/fastapi-wizard-agent.ts

@@ -1,9 +1,9 @@
 /* FastAPI wizard using posthog-agent with PostHog MCP */
-import type { WizardOptions } from '../../utils/types';
-import type { FrameworkConfig } from '../../lib/framework-config';
-import { PYTHON_PACKAGE_INSTALLATION } from '../../lib/framework-config';
-import { detectPythonPackageManagers } from '../../lib/detection/package-manager';
-import { Integration } from '../../lib/constants';
+import type { WizardOptions } from '@utils/types';
+import type { FrameworkConfig } from '@lib/framework-config';
+import { PYTHON_PACKAGE_INSTALLATION } from '@lib/framework-config';
+import { detectPythonPackageManagers } from '@lib/detection/package-manager';
+import { Integration } from '@lib/constants';
 import {
   getFastAPIVersion,
   getFastAPIProjectType,