feat: Initial migration system [DRAFT]

bin.ts

@@ -21,6 +21,11 @@
 import type { CloudRegion, WizardOptions } from './src/utils/types';
 import { runWizard } from './src/run';
 import { runEventSetupWizard } from './src/nextjs/event-setup';
+import {
+  runMigrationWizard,
+  getAvailableMigrationProviders,
+  type MigrationOptions,
+} from './src/migrate';
 import {
   readEnvironment,
   isNonInteractiveEnvironment,
@@ -126,24 +131,24 @@
       });
     },
     (argv) => {
       const finalArgs = {
         ...argv,
         ...readEnvironment(),
       } as any;
 
       let resolvedInstallDir: string;
       if (finalArgs.installDir) {
         if (path.isAbsolute(finalArgs.installDir)) {
           resolvedInstallDir = finalArgs.installDir;
         } else {
           resolvedInstallDir = path.join(process.cwd(), finalArgs.installDir);
         }
       } else {
         resolvedInstallDir = process.cwd();
       }
 
       const wizardOptions: WizardOptions = {
         debug: finalArgs.debug ?? false,
         installDir: resolvedInstallDir,
         cloudRegion: finalArgs.region as CloudRegion | undefined,
         default: finalArgs.default ?? false,
@@ -155,6 +160,62 @@
       void runEventSetupWizard(wizardOptions);
     },
   )
+  .command(
+    'migrate',
+    'Migrate from another analytics provider to PostHog',
+    (yargs) => {
+      const availableProviders = getAvailableMigrationProviders();
+      return yargs
+        .options({
+          'install-dir': {
+            describe:
+              'Directory to run the migration in\nenv: POSTHOG_WIZARD_INSTALL_DIR',
+            type: 'string',
+          },
+          'force-install': {
+            default: false,
+            describe:
+              'Force install packages even if peer dependency checks fail\nenv: POSTHOG_WIZARD_FORCE_INSTALL',
+            type: 'boolean',
+          },
+          from: {
+            describe: 'Analytics provider to migrate from',
+            choices: availableProviders,
+            default: 'amplitude',
+            type: 'string',
+          },
+        });
+    },
+    (argv) => {
+      const finalArgs = {
+        ...argv,
+        ...readEnvironment(),
+      } as any;
+
+      let resolvedInstallDir: string;
+      if (finalArgs.installDir) {
+        if (path.isAbsolute(finalArgs.installDir)) {
+          resolvedInstallDir = finalArgs.installDir;
+        } else {
+          resolvedInstallDir = path.join(process.cwd(), finalArgs.installDir);
+        }
+      } else {
+        resolvedInstallDir = process.cwd();
+      }
+
+      const migrationOptions: MigrationOptions = {
+        debug: finalArgs.debug ?? false,
+        installDir: resolvedInstallDir,
+        cloudRegion: finalArgs.region as CloudRegion | undefined,
+        default: finalArgs.default ?? false,
+        signup: finalArgs.signup ?? false,
+        forceInstall: finalArgs.forceInstall ?? false,
+        localMcp: finalArgs.localMcp ?? false,
+      };
+
+      void runMigrationWizard(migrationOptions, finalArgs.from as string);
+    },
+  )
   .command('mcp <command>', 'MCP server management commands', (yargs) => {
     return yargs
       .command(

e2e-tests/fixtures/18c11dda2ee4cd5c20c337d23dd61387.json

@@ -1,3 +1,3 @@
 {
-  "newContent": "import { StrictMode } from 'react'\nimport { createRoot } from 'react-dom/client'\nimport { PostHogProvider } from 'posthog-js/react'\nimport './index.css'\nimport App from './App.tsx'\n\ncreateRoot(document.getElementById('root')!).render(\n  <StrictMode>\n    <PostHogProvider\n      apiKey={import.meta.env.VITE_PUBLIC_POSTHOG_KEY}\n      options={{\n        api_host: import.meta.env.VITE_PUBLIC_POSTHOG_HOST,\n        defaults: '2025-05-24',\n        capture_exceptions: true,\n        debug: import.meta.env.MODE === 'development',\n      }}\n    >\n      <App />\n    </PostHogProvider>\n  </StrictMode>,\n)\n"
+  "newContent": "import { StrictMode } from 'react'\nimport { createRoot } from 'react-dom/client'\nimport posthog from 'posthog-js'\nimport { PostHogProvider } from 'posthog-js/react'\nimport './index.css'\nimport App from './App.tsx'\n\nposthog.init(import.meta.env.VITE_PUBLIC_POSTHOG_KEY, {\n  api_host: import.meta.env.VITE_PUBLIC_POSTHOG_HOST,\n  defaults: '2025-05-24',\n  capture_exceptions: true,\n  debug: import.meta.env.MODE === 'development',\n});\n\ncreateRoot(document.getElementById('root')!).render(\n  <StrictMode>\n    <PostHogProvider client={posthog}>\n      <App />\n    </PostHogProvider>\n  </StrictMode>,\n)\n"
 }

src/lib/constants.ts

@@ -6,6 +6,19 @@ export enum Integration {
   astro = 'astro',
 }
 
+export enum MigrationSource {
+  amplitude = 'amplitude',
+}
+
+export function getMigrationSourceDescription(source: MigrationSource): string {
+  switch (source) {
+    case MigrationSource.amplitude:
+      return 'Amplitude';
+    default:
+      throw new Error(`Unknown migration source ${source}`);
+  }
+}
+
 export enum FeatureFlagDefinition {
   NextV2 = 'wizard-next-v2',
 }

src/lib/prompts.ts

@@ -79,3 +79,82 @@ Here are the files that have not been changed yet:
 Below is the current file contents:
 {file_content}`,
 });
+
+export const migrationFilterFilesPromptTemplate = new PromptTemplate({
+  inputVariables: [
+    'documentation',
+    'file_list',
+    'source_sdk',
+    'integration_rules',
+  ],
+  template: `You are a PostHog migration wizard, a master AI programming assistant that migrates projects from {source_sdk} to PostHog.
+Given the following list of file paths from a project, determine which files contain {source_sdk} code that needs to be migrated to PostHog.
+
+- Look for files that import or use {source_sdk} SDK
+- Look for files that initialize {source_sdk}
+- Look for files that track events with {source_sdk}
+- Look for files that identify users with {source_sdk}
+- Look for configuration files that may reference {source_sdk}
+
+You should return all files that contain {source_sdk} code that needs to be migrated. Return them in the order you would like to see them processed.
+
+Rules:
+- Only return files that actually contain {source_sdk} code or references
+- Do not return files that don't use {source_sdk}
+- If you are unsure, return the file, since it's better to have more files than less
+- Include any configuration or initialization files
+{integration_rules}
+
+Migration documentation:
+{documentation}
+
+All current files in the repository:
+
+{file_list}`,
+});
+
+export const migrationGenerateFileChangesPromptTemplate = new PromptTemplate({
+  inputVariables: [
+    'file_content',
+    'documentation',
+    'file_path',
+    'changed_files',
+    'unchanged_files',
+    'source_sdk',
+    'integration_rules',
+  ],
+  template: `You are a PostHog migration wizard, a master AI programming assistant that migrates projects from {source_sdk} to PostHog.
+
+Your task is to migrate the file from {source_sdk} to PostHog according to the migration documentation.
+Do not return a diff — you should return the complete updated file content.
+
+Rules:
+- Replace ALL {source_sdk} imports with PostHog imports
+- Replace ALL {source_sdk} initialization code with PostHog initialization
+- Replace ALL {source_sdk} tracking calls with PostHog equivalents
+- Replace ALL {source_sdk} identify calls with PostHog equivalents
+- Remove ALL {source_sdk}-specific code that has no PostHog equivalent
+- Preserve the existing code formatting and style
+- Make sure to remove any unused {source_sdk} imports after migration
+- If the file has no {source_sdk} code after review, return it unchanged
+{integration_rules}
+
+
+CONTEXT
+---
+
+Migration documentation from {source_sdk} to PostHog:
+{documentation}
+
+The file you are updating is:
+{file_path}
+
+Here are the changes you have already made to the project:
+{changed_files}
+
+Here are the files that have not been changed yet:
+{unchanged_files}
+
+Below is the current file contents:
+{file_content}`,
+});

src/migrate/index.ts

@@ -0,0 +1,40 @@
+export {
+  runMigrationWizard,
+  checkAndOfferMigration,
+  detectProviderInstallation,
+  getAllInstalledProviderPackages,
+} from './migration-wizard';
+
+export type {
+  MigrationProviderConfig,
+  InstalledPackage,
+  MigrationOptions,
+  MigrationDocsOptions,
+  MigrationContext,
+  MigrationOutroOptions,
+} from './types';
+
+export {
+  getMigrationProvider,
+  getAvailableMigrationProviders,
+  migrationProviders,
+  amplitudeProvider,
+} from './providers';
+
+export { AMPLITUDE_PACKAGES } from './providers/amplitude';
+
+import { runMigrationWizard, checkAndOfferMigration } from './migration-wizard';
+import type { MigrationOptions } from './types';
+import type { WizardOptions } from '../utils/types';
+
+export async function runAmplitudeMigrationWizard(
+  options: MigrationOptions,
+): Promise<void> {
+  return runMigrationWizard(options, 'amplitude');
+}
+
+export async function checkAndOfferAmplitudeMigration(
+  options: WizardOptions,
+): Promise<boolean> {
+  return checkAndOfferMigration(options, 'amplitude');
+}