@hs-x/cli 0.1.3 → 0.2.1

package/dist/commands/migrate.js

@@ -1,174 +1,15 @@
-import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
-import { basename, dirname, join, resolve } from 'node:path';
 import * as Args from '@effect/cli/Args';
 import * as Command from '@effect/cli/Command';
 import * as Options from '@effect/cli/Options';
 import { FileSystem, Path } from '@effect/platform';
-import { generateLegacyCardProject } from '@hs-x/codegen';
-import { classifyMigrationInput, validateProject } from '@hs-x/validator';
+import { generateLegacyCardProject, generateMigratedHsxProject, } from '@hs-x/codegen';
+import { classifyMigrationInput, detectMigrationSource, planCutover, validateProject } from '@hs-x/validator';
 import { Effect, Option } from 'effect';
 import { cliError, exitWith } from '../cli-error.js';
 import { accountIdOption, controlPlaneUrlOption, cwdOption, jsonOption, runHandler, userIdOption, } from '../cli/kit.js';
-import { createDeployHubSpotDeveloperClient } from '../hubspot-developer-client.js';
-import { emitHelp } from '../help.js';
-import { createReporter } from '../reporter/index.js';
 import { Cwd } from '../services/cwd.js';
 import { HubSpotDevClient } from '../services/hubspot-dev-client.js';
 import { Reporter } from '../services/reporter.js';
-export async function migrateCommand({ argv, cwd, json, }) {
-    const subcommand = argv[1] ?? 'help';
-    if (subcommand !== 'inspect' &&
-        subcommand !== 'cards' &&
-        subcommand !== 'report' &&
-        subcommand !== 'swap-cards') {
-        emitHelp(migrateHelpText(), json);
-        return { exitCode: subcommand === 'help' ? 0 : 1 };
-    }
-    if (subcommand === 'swap-cards') {
-        return await migrateSwapCardsCommand({ argv, json });
-    }
-    const target = argv.find((arg, index) => index > 1 && !arg.startsWith('-'));
-    if (!target) {
-        throw new Error(`Usage: hs-x migrate ${subcommand} <path> [--json]`);
-    }
-    const input = await readMigrationInput(resolve(cwd, target));
-    const result = classifyMigrationInput(input);
-    if (subcommand === 'report') {
-        const response = {
-            ok: true,
-            command: 'migrate report',
-            summary: {
-                detected: result.detected,
-                automatable: result.automatable.length,
-                humanReview: result.manualWork.length,
-                cloudflareRequired: result.cloudflareRequired,
-                canGenerateCards: result.manualWork.length === 0,
-            },
-            inspect: result,
-            nextSteps: migrationNextSteps(result),
-        };
-        if (json) {
-            process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
-        }
-        else {
-            process.stdout.write(renderMigrationReport(response));
-        }
-        return { exitCode: 0 };
-    }
-    if (subcommand === 'inspect') {
-        const response = { ok: true, command: 'migrate inspect', ...result };
-        if (json) {
-            process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
-        }
-        else {
-            process.stdout.write(renderMigrationInspect(response));
-        }
-        return { exitCode: result.manualWork.length === 0 ? 0 : 1 };
-    }
-    if (result.manualWork.length > 0 || !isLegacyCardMigrationInput(input)) {
-        const response = { ok: false, command: 'migrate cards', ...result };
-        if (json) {
-            process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
-        }
-        else {
-            process.stdout.write(renderMigrationInspect(response));
-        }
-        return { exitCode: 1 };
-    }
-    const outputRoot = resolve(cwd, resolveFlag(argv, '--project') ?? 'migrated-app');
-    const generated = generateLegacyCardProject(input);
-    await writeProjectFiles(outputRoot, generated.files);
-    const validation = await validateProject({ root: outputRoot });
-    const response = {
-        ok: validation.ok,
-        command: 'migrate cards',
-        outputRoot,
-        createdFiles: Object.keys(generated.files).sort(),
-        inspect: result,
-        validation,
-    };
-    if (json) {
-        process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
-    }
-    else {
-        const reporter = createReporter({ command: 'migrate cards', argv });
-        reporter.header(basename(outputRoot));
-        reporter
-            .step('Generated migrated App Card project')
-            .ok(`${response.createdFiles.length} files  ${outputRoot}`);
-        for (const file of response.createdFiles)
-            reporter.info(file);
-        if (validation.ok) {
-            reporter.step('Validation').ok();
-        }
-        else {
-            reporter.step('Validation').fail(`${validation.diagnostics.length} issue(s)`);
-            for (const d of validation.diagnostics) {
-                const code = d.code ?? 'diagnostic';
-                const msg = d.message ?? JSON.stringify(d);
-                reporter.error(code, msg);
-            }
-        }
-        reporter.done(validation.ok ? 'Migrated' : 'Failed', validation.ok ? 0 : 1);
-    }
-    return { exitCode: validation.ok ? 0 : 1 };
-}
-async function migrateSwapCardsCommand({ argv, json, }) {
-    const appId = readRequiredNumberFlag(argv, '--app-id');
-    const legacyCrmCardId = resolveFlag(argv, '--legacy-card-id');
-    const replacementAppCardId = resolveFlag(argv, '--replacement-card-id');
-    if (!legacyCrmCardId) {
-        throw new Error('--legacy-card-id is required.');
-    }
-    if (!replacementAppCardId) {
-        throw new Error('--replacement-card-id is required.');
-    }
-    const local = argv.includes('--local-hubspot');
-    const client = await createDeployHubSpotDeveloperClient({
-        argv,
-        local,
-        allowedOperations: ['hubspot-migration-read', 'hubspot-card-view-swap'],
-    });
-    const apps = await client.migrations.listApps();
-    const helpDeskAppCardId = resolveFlag(argv, '--helpdesk-card-id');
-    const swapRequest = helpDeskAppCardId === undefined
-        ? { appId, legacyCrmCardId, replacementAppCardId }
-        : { appId, legacyCrmCardId, replacementAppCardId, helpDeskAppCardId };
-    const swap = await client.migrations.migrateCardViews(swapRequest);
-    const response = {
-        ok: true,
-        command: 'migrate swap-cards',
-        appId,
-        legacyCrmCardId,
-        replacementAppCardId,
-        ...(helpDeskAppCardId === undefined ? {} : { helpDeskAppCardId }),
-        migrationApps: apps,
-        swap,
-    };
-    if (json) {
-        process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
-    }
-    else {
-        const reporter = createReporter({ command: 'migrate swap-cards', argv });
-        reporter.header(legacyCrmCardId);
-        reporter.step('Migrated legacy CRM card').ok(`-> App Card ${replacementAppCardId}`);
-        reporter.done('Swapped');
-    }
-    return { exitCode: 0 };
-}
-async function readMigrationInput(path) {
-    const stats = await stat(path);
-    const file = stats.isDirectory() ? join(path, 'migration.json') : path;
-    const contents = await readFile(file, 'utf8');
-    return JSON.parse(contents);
-}
-async function writeProjectFiles(root, files) {
-    for (const [file, contents] of Object.entries(files)) {
-        const path = join(root, file);
-        await mkdir(dirname(path), { recursive: true });
-        await writeFile(path, contents, { flag: 'wx' });
-    }
-}
 function isLegacyCardMigrationInput(value) {
     if (!isRecord(value) || !isRecord(value.legacyApp) || !isRecord(value.legacyCard)) {
         return false;
@@ -221,50 +62,140 @@ function migrationNextSteps(result) {
             : 'Use `hs-x deploy --hubspot-only` once HubSpot upload is wired.',
     ];
 }
-function readRequiredNumberFlag(argv, flag) {
-    const value = resolveFlag(argv, flag);
-    if (!value) {
-        throw new Error(`${flag} is required.`);
-    }
-    return readPositiveInteger(value, flag);
-}
-function readPositiveInteger(value, label) {
-    const parsed = Number.parseInt(value, 10);
-    if (!Number.isInteger(parsed) || parsed <= 0) {
-        throw new Error(`${label} must be a positive integer.`);
-    }
-    return parsed;
-}
-function isFlagValue(value) {
-    return value !== undefined && value.length > 0 && !value.startsWith('-');
-}
-function resolveFlag(argv, flag) {
-    const index = argv.indexOf(flag);
-    if (index !== -1) {
-        const next = argv[index + 1];
-        if (isFlagValue(next))
-            return next;
-    }
-    const prefix = `${flag}=`;
-    const found = argv.find((arg) => arg.startsWith(prefix));
-    if (!found)
-        return undefined;
-    const value = found.slice(prefix.length);
-    return value.length > 0 ? value : undefined;
-}
 function isRecord(value) {
     return typeof value === 'object' && value !== null;
 }
 export function migrateHelpText() {
     return `hs-x migrate
 
+Migrate a legacy HubSpot app (2023.2 / 2025.1 / 2025.2) to a 2026.03 HS-X
+project. The generated project is a NET-NEW dupe for testing in \`hs-x dev\`;
+your original app keeps running untouched until cutover.
+
 Commands:
-  hs-x migrate inspect <path> [--json]  Classify a legacy migration input
-  hs-x migrate report <path> [--json]   Summarize migration readiness
+  hs-x migrate run [path] [--out <dir>] [--json]   Detect, classify, and generate the dupe (the one command)
+  hs-x migrate cutover [path] [--json]             Dry-run plan: what cutover changes on the ORIGINAL app
+  hs-x migrate inspect <path> [--json]             Classify a legacy migration input
+  hs-x migrate report <path> [--json]              Summarize migration readiness
   hs-x migrate cards <path> [--project <dir>] [--json]
   hs-x migrate swap-cards --app-id <id> --legacy-card-id <id> --replacement-card-id <id> [--helpdesk-card-id <id>] [--local-hubspot] [--json]
+
+Run hs-x migrate <subcommand> --help for details on each step.
 `;
 }
+export function migrateSubcommandHelpText(sub) {
+    switch (sub) {
+        case 'run':
+            return `hs-x migrate run [path]
+
+The one-command migration: detect the legacy source (a project tree with
+hsproject.json, or a migration.json input), classify every component, and
+generate a NET-NEW 2026.03 HS-X project (the dupe) from everything portable —
+app cards, serverless functions, webhook subscriptions, workflow actions.
+
+Pieces needing a human decision (external receivers, endpoint URL contracts)
+are listed with doc links; they gate CUTOVER, not the dupe — test it in
+\`hs-x dev\` first. Re-run safely after resolving findings.
+
+Arguments:
+  path                      Legacy source (default: current directory)
+
+Flags:
+  --out <dir>               Output directory (default: migrated-app)
+  --cwd <dir>               Resolve paths relative to <dir>
+  --json                    Emit JSON result
+
+Exits 1 only when nothing portable could be generated or validation fails.
+`;
+        case 'cutover':
+            return `hs-x migrate cutover [path]
+
+Print the DRY-RUN cutover plan: the ordered steps that migrate the ORIGINAL
+app in place to 2026.03 — keeping its app id, installs, OAuth grants, and
+listing — once the dupe has proven the migration in \`hs-x dev\`.
+
+The plan is honest about the one-way door (no downgrade from 2026.03) and
+lists every open decision (external receivers, endpoint contracts,
+marketplace listing) that gates execution. Execution itself never runs
+without an explicit human go; --execute is refused in this build.
+
+Arguments:
+  path                      The ORIGINAL legacy source (default: current directory)
+
+Flags:
+  --json                    Emit the plan as JSON
+  --cwd <dir>               Resolve paths relative to <dir>
+`;
+        case 'inspect':
+            return `hs-x migrate inspect <path>
+
+Classify a legacy migration input: which findings HS-X can migrate
+automatically, which need human review, and whether the replacement app needs
+the Cloudflare runtime.
+
+Arguments:
+  path                      Migration input JSON file, or a directory
+                            containing migration.json
+
+Flags:
+  --cwd <dir>               Resolve <path> relative to <dir>
+  --json                    Emit JSON result
+
+Exits 1 when human-review findings remain (so CI can gate on it).
+`;
+        case 'report':
+            return `hs-x migrate report <path>
+
+Summarize migration readiness: detected features, automatable vs human-review
+finding counts, runtime requirements, and suggested next steps.
+
+Arguments:
+  path                      Migration input JSON file, or a directory
+                            containing migration.json
+
+Flags:
+  --cwd <dir>               Resolve <path> relative to <dir>
+  --json                    Emit JSON result
+`;
+        case 'cards':
+            return `hs-x migrate cards <path>
+
+Generate a replacement App Card project from a legacy CRM card migration
+input, then validate the generated project. Fails (exit 1) if the input still
+has human-review findings — resolve those first (see hs-x migrate inspect).
+
+Arguments:
+  path                      Migration input JSON file, or a directory
+                            containing migration.json
+
+Flags:
+  --project <dir>           Output directory (default: migrated-app)
+  --cwd <dir>               Resolve paths relative to <dir>
+  --json                    Emit JSON result
+`;
+        case 'swap-cards':
+            return `hs-x migrate swap-cards
+
+Swap a live legacy CRM card for its replacement App Card via the HubSpot
+developer API.
+
+Flags:
+  --app-id <id>             HubSpot app id (required)
+  --legacy-card-id <id>     Legacy CRM card to retire (required)
+  --replacement-card-id <id>  App Card that replaces it (required)
+  --helpdesk-card-id <id>   Optional help-desk App Card variant
+  --local-hubspot           Use the local HubSpot mock
+  --json                    Emit JSON result
+
+Advanced:
+  --control-plane-url <u>   Override control plane (HSX_CONTROL_PLANE_URL)
+  --account-id <id>         HS-X account for lease/credential discovery
+  --user-id <id>            Attribution for control-plane records
+`;
+        default:
+            return undefined;
+    }
+}
 // ─── Native @effect/cli command (Phase 4) ───────────────────────────────────
 // Subcommands inspect/report/cards (project analysis; fs lifted onto
 // `@effect/platform` FileSystem/Path) + swap-cards (HubSpot developer client via
@@ -288,6 +219,24 @@ function readMigrationInputEff(path) {
         const fs = yield* FileSystem.FileSystem;
         const pathSvc = yield* Path.Path;
         const info = yield* fs.stat(path).pipe(Effect.mapError((cause) => cliError('HSX_E_INTERNAL', `Could not read ${path}: ${String(cause)}`)));
+        if (info.type === 'Directory') {
+            const fixture = pathSvc.join(path, 'migration.json');
+            const hasFixture = yield* fs.exists(fixture).pipe(Effect.orElseSucceed(() => false));
+            if (!hasFixture) {
+                // Locked decision #4 (local-source half): a legacy PROJECT tree —
+                // hsproject.json names the platform version; component configs
+                // (serverless.json, webhooks/workflow-action hsmeta) assemble into
+                // the classifier input via detectMigrationSource.
+                const detected = yield* Effect.tryPromise({
+                    try: () => detectMigrationSource(path),
+                    catch: (cause) => cliError('HSX_E_INTERNAL', `Could not inspect ${path}: ${String(cause)}`),
+                });
+                if (detected.entry === 'unknown') {
+                    return yield* Effect.fail(cliError('HSX_E_INPUT_BAD_FIELD', `${path} has no migration.json and no hsproject.json — nothing to migrate. Point at a legacy project root or a migration input file.`));
+                }
+                return detected.input;
+            }
+        }
         const file = info.type === 'Directory' ? pathSvc.join(path, 'migration.json') : path;
         const contents = yield* fs.readFileString(file).pipe(Effect.mapError((cause) => cliError('HSX_E_INTERNAL', `Could not read ${file}: ${String(cause)}`)));
         return yield* Effect.try({
@@ -308,22 +257,20 @@ function writeProjectFilesEff(root, files) {
         }
     });
 }
-function writeStdout(text) {
-    return Effect.sync(() => process.stdout.write(text));
-}
 function migrateInspectBody(opts) {
     return Effect.gen(function* () {
         const cwd = yield* Cwd;
         const pathSvc = yield* Path.Path;
+        const reporter = yield* Reporter;
         const root = Option.getOrElse(opts.cwd, () => cwd);
         const input = yield* readMigrationInputEff(pathSvc.resolve(root, opts.path));
         const result = classifyMigrationInput(input);
         const response = { ok: true, command: 'migrate inspect', ...result };
         if (opts.json) {
-            yield* writeStdout(`${JSON.stringify(response, null, 2)}\n`);
+            yield* reporter.raw(`${JSON.stringify(response, null, 2)}\n`);
         }
         else {
-            yield* writeStdout(renderMigrationInspect(response));
+            yield* reporter.raw(renderMigrationInspect(response));
         }
         if (result.manualWork.length > 0) {
             return yield* Effect.fail(exitWith(1));
@@ -334,6 +281,7 @@ function migrateReportBody(opts) {
     return Effect.gen(function* () {
         const cwd = yield* Cwd;
         const pathSvc = yield* Path.Path;
+        const reporter = yield* Reporter;
         const root = Option.getOrElse(opts.cwd, () => cwd);
         const input = yield* readMigrationInputEff(pathSvc.resolve(root, opts.path));
         const result = classifyMigrationInput(input);
@@ -351,10 +299,10 @@ function migrateReportBody(opts) {
             nextSteps: migrationNextSteps(result),
         };
         if (opts.json) {
-            yield* writeStdout(`${JSON.stringify(response, null, 2)}\n`);
+            yield* reporter.raw(`${JSON.stringify(response, null, 2)}\n`);
         }
         else {
-            yield* writeStdout(renderMigrationReport(response));
+            yield* reporter.raw(renderMigrationReport(response));
         }
     });
 }
@@ -369,10 +317,10 @@ function migrateCardsBody(opts) {
         if (result.manualWork.length > 0 || !isLegacyCardMigrationInput(input)) {
             const response = { ok: false, command: 'migrate cards', ...result };
             if (opts.json) {
-                yield* writeStdout(`${JSON.stringify(response, null, 2)}\n`);
+                yield* reporter.raw(`${JSON.stringify(response, null, 2)}\n`);
             }
             else {
-                yield* writeStdout(renderMigrationInspect(response));
+                yield* reporter.raw(renderMigrationInspect(response));
             }
             return yield* Effect.fail(exitWith(1));
         }
@@ -389,7 +337,7 @@ function migrateCardsBody(opts) {
             validation,
         };
         if (opts.json) {
-            yield* writeStdout(`${JSON.stringify(response, null, 2)}\n`);
+            yield* reporter.raw(`${JSON.stringify(response, null, 2)}\n`);
         }
         else {
             yield* reporter.header(pathSvc.basename(outputRoot));
@@ -417,6 +365,104 @@ function migrateCardsBody(opts) {
         }
     });
 }
+/**
+ * The one-command flow (launch headline): detect → classify → generate the
+ * dupe project from every PORTABLE piece → report skipped pieces and
+ * pre-cutover decisions → guided next step into `hs-x dev`. Decision-type
+ * findings (forwarding/url-contract) never block dupe generation — the dupe
+ * is a testbed (locked decision #2); they gate CUTOVER, which is a separate
+ * command. Exit 1 only when nothing portable could be generated.
+ */
+function migrateRunBody(opts) {
+    return Effect.gen(function* () {
+        const cwd = yield* Cwd;
+        const pathSvc = yield* Path.Path;
+        const reporter = yield* Reporter;
+        const root = Option.getOrElse(opts.cwd, () => cwd);
+        const sourcePath = pathSvc.resolve(root, opts.path);
+        const input = yield* readMigrationInputEff(sourcePath);
+        const result = classifyMigrationInput(input);
+        let generated;
+        let generationError;
+        try {
+            generated = generateMigratedHsxProject(input);
+        }
+        catch (error) {
+            generationError = error instanceof Error ? error.message : String(error);
+        }
+        const hasCapabilities = generated !== undefined &&
+            Object.keys(generated.files).some((file) => file.startsWith('src/workers/') || file.includes('/cards/'));
+        if (!generated || !hasCapabilities) {
+            const response = {
+                ok: false,
+                command: 'migrate run',
+                ...result,
+                ...(generationError ? { error: generationError } : {}),
+            };
+            if (opts.json) {
+                yield* reporter.raw(`${JSON.stringify(response, null, 2)}\n`);
+            }
+            else {
+                yield* reporter.raw(renderMigrationInspect(response));
+                yield* reporter.error('HSX_E_MIGRATE_NOTHING_PORTABLE', generationError ?? 'No portable components detected in this source.', {
+                    hint: 'Resolve the findings above, then re-run `hs-x migrate run`.',
+                    docs_url: 'https://hs-x.dev/docs/guides/migrate',
+                });
+                yield* reporter.done(undefined, 1);
+            }
+            return yield* Effect.fail(exitWith(1));
+        }
+        const outputRoot = pathSvc.resolve(root, Option.getOrUndefined(opts.out) ?? 'migrated-app');
+        yield* writeProjectFilesEff(outputRoot, generated.files);
+        const validation = yield* Effect.promise(() => validateProject({ root: outputRoot }));
+        const response = {
+            ok: validation.ok,
+            command: 'migrate run',
+            outputRoot,
+            createdFiles: Object.keys(generated.files).sort(),
+            inspect: result,
+            validation,
+        };
+        if (opts.json) {
+            yield* reporter.raw(`${JSON.stringify(response, null, 2)}\n`);
+        }
+        else {
+            yield* reporter.header(pathSvc.basename(outputRoot));
+            const genStep = yield* reporter.step('Generated migrated HS-X project (the dupe)');
+            yield* genStep.ok(`${response.createdFiles.length} files  ${outputRoot}`);
+            if (result.automatable.length > 0) {
+                yield* reporter.info(`Ported automatically:`);
+                for (const finding of result.automatable)
+                    yield* reporter.info(`  - ${finding.message}`);
+            }
+            if (result.manualWork.length > 0) {
+                yield* reporter.info('Decisions before cutover (the dupe is a testbed; these do not block it):');
+                for (const finding of result.manualWork) {
+                    yield* reporter.info(`  - [${finding.code}] ${finding.message}  docs: https://hs-x.dev/docs/guides/migrate#${finding.code.replace(/\./g, '-')}`);
+                }
+            }
+            const vStep = yield* reporter.step('Validation');
+            if (validation.ok) {
+                yield* vStep.ok();
+            }
+            else {
+                yield* vStep.fail(`${validation.diagnostics.length} issue(s)`);
+                for (const d of validation.diagnostics) {
+                    yield* reporter.error(d.code ?? 'diagnostic', d.message ?? JSON.stringify(d));
+                }
+            }
+            yield* reporter.info('');
+            yield* reporter.info('Next steps:');
+            yield* reporter.info(`  cd ${pathSvc.relative(root, outputRoot) || '.'} && bun install`);
+            yield* reporter.info('  hs-x dev          # test every migrated capability locally');
+            yield* reporter.info('  hs-x deploy       # upload the dupe as a NET-NEW app when ready');
+            yield* reporter.done(validation.ok ? 'Migrated' : 'Failed', validation.ok ? 0 : 1);
+        }
+        if (!validation.ok) {
+            return yield* Effect.fail(exitWith(1));
+        }
+    });
+}
 function migrateSwapCardsBody(opts, argv) {
     return Effect.gen(function* () {
         const reporter = yield* Reporter;
@@ -451,7 +497,7 @@ function migrateSwapCardsBody(opts, argv) {
             swap,
         };
         if (opts.json) {
-            yield* writeStdout(`${JSON.stringify(response, null, 2)}\n`);
+            yield* reporter.raw(`${JSON.stringify(response, null, 2)}\n`);
         }
         else {
             yield* reporter.header(legacyCrmCardId);
@@ -504,7 +550,67 @@ function swapCardsArgv(opts) {
         argv.push('--user-id', opts.userId.value);
     return argv;
 }
+const migrateRunPathArg = Args.text({ name: 'path' }).pipe(Args.withDefault('.'));
+const migrateOutOption = Options.text('out').pipe(Options.optional);
+/**
+ * `hs-x migrate cutover [path]` — DRY-RUN ONLY today (locked decision #2:
+ * cutover never executes against a real app without explicit human go).
+ * Prints the ordered plan of what cutover will change on the ORIGINAL app,
+ * in place, plus the open decisions gating execution.
+ */
+function migrateCutoverBody(opts) {
+    return Effect.gen(function* () {
+        const cwd = yield* Cwd;
+        const pathSvc = yield* Path.Path;
+        const reporter = yield* Reporter;
+        const root = Option.getOrElse(opts.cwd, () => cwd);
+        const sourcePath = pathSvc.resolve(root, opts.path);
+        if (opts.execute) {
+            return yield* Effect.fail(cliError('HSX_E_CUTOVER_EXECUTE_GATED', 'Cutover execution against a real app requires an explicit human go and is not enabled in this build.'));
+        }
+        const detected = yield* Effect.tryPromise({
+            try: () => detectMigrationSource(sourcePath),
+            catch: (cause) => cliError('HSX_E_INTERNAL', `Could not inspect ${sourcePath}: ${String(cause)}`),
+        });
+        if (detected.entry === 'unknown') {
+            return yield* Effect.fail(cliError('HSX_E_INPUT_BAD_FIELD', `${sourcePath} has no migration.json and no hsproject.json — nothing to plan. Point at the ORIGINAL legacy app's source.`));
+        }
+        const classification = classifyMigrationInput(detected.input);
+        const plan = planCutover(detected, classification);
+        if (opts.json) {
+            yield* reporter.raw(`${JSON.stringify({ ok: true, command: 'migrate cutover', mode: 'dry-run', ...plan }, null, 2)}\n`);
+            return;
+        }
+        yield* reporter.header(`cutover plan (dry-run) — ${plan.sourceVersion} source`);
+        yield* reporter.info('ONE-WAY: the original app cannot downgrade from 2026.03 after cutover.');
+        yield* reporter.info('');
+        for (const phase of ['preflight', 'in-place', 'post']) {
+            const phaseSteps = plan.steps.filter((step) => step.phase === phase);
+            if (phaseSteps.length === 0)
+                continue;
+            yield* reporter.info(`${phase.toUpperCase()}:`);
+            for (const step of phaseSteps) {
+                yield* reporter.info(`  - ${step.title}${step.gatedBy ? `  [gated: ${step.gatedBy}]` : ''}`);
+                yield* reporter.info(`      ${step.detail}`);
+            }
+            yield* reporter.info('');
+        }
+        if (plan.openDecisions.length > 0) {
+            yield* reporter.info(`${plan.openDecisions.length} open decision(s) gate execution — resolve them, re-run this plan, then request execution.`);
+        }
+        else {
+            yield* reporter.info('No open decisions. Execution still requires an explicit human go (see LAUNCH-PLAN NEEDS HUMAN).');
+        }
+        yield* reporter.done('Planned');
+    });
+}
+const migrateExecuteOption = Options.boolean('execute').pipe(Options.withDefault(false));
+const migrateCutoverPathArg = Args.text({ name: 'path' }).pipe(Args.withDefault('.'));
+const migrateCutoverCmd = Command.make('cutover', { path: migrateCutoverPathArg, cwd: cwdOption, json: jsonOption, execute: migrateExecuteOption }, (opts) => runHandler('migrate', { json: opts.json }, migrateCutoverBody(opts)));
+const migrateRunCmd = Command.make('run', { path: migrateRunPathArg, out: migrateOutOption, cwd: cwdOption, json: jsonOption }, (opts) => runHandler('migrate', { json: opts.json }, migrateRunBody(opts)));
 export const migrateCmd = Command.make('migrate').pipe(Command.withSubcommands([
+    migrateRunCmd,
+    migrateCutoverCmd,
     migrateInspectCmd,
     migrateReportCmd,
     migrateCardsCmd,