@hs-x/cli 0.2.7 → 0.3.6

package/dist/commands/migrate.js

@@ -3,11 +3,12 @@ import * as Command from '@effect/cli/Command';
 import * as Options from '@effect/cli/Options';
 import { FileSystem, Path } from '@effect/platform';
 import { generateLegacyCardProject, generateMigratedHsxProject, } from '@hs-x/codegen';
-import { classifyMigrationInput, detectMigrationSource, planCutover, validateProject } from '@hs-x/validator';
+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 { isInteractive, promptSelect } from '../prompt.js';
+import { discoverLocalProjects } from '../local-project-picker.js';
+import { BACK, isInteractive, promptConfirm, promptSelect, promptText, } from '../prompt.js';
 import { Cwd } from '../services/cwd.js';
 import { HubSpotDevClient } from '../services/hubspot-dev-client.js';
 import { Reporter } from '../services/reporter.js';
@@ -48,21 +49,44 @@ function renderMigrationReport(data) {
     return `${lines.join('\n')}\n`;
 }
 function migrationNextSteps(result) {
+    const hasNonCardComponents = result.detected.some((kind) => kind !== 'classic-crm-card' && kind !== 'project-card');
+    const generateCommand = hasNonCardComponents
+        ? '`hs-x migrate run <path> --out <dir>`'
+        : '`hs-x migrate cards <path> --project <dir>`';
     if (result.manualWork.length > 0) {
         return [
-            'Resolve human-review findings before running `hs-x migrate cards`.',
+            `Resolve human-review findings before running ${generateCommand}.`,
             result.cloudflareRequired
                 ? 'Plan Cloudflare runtime requirements before deploy.'
                 : 'Confirm HubSpot-only replacement card targets before deploy.',
         ];
     }
     return [
-        'Run `hs-x migrate cards <path> --project <dir>` to generate the replacement App Card project.',
+        `Run ${generateCommand} to generate the replacement project.`,
         result.cloudflareRequired
             ? 'Run `hs-x connect cloudflare` before deploy.'
             : 'Use `hs-x deploy --hubspot-only` once HubSpot upload is wired.',
     ];
 }
+function countMatches(contents, pattern) {
+    return [...contents.matchAll(pattern)].length;
+}
+function migrationOutstandingWork(files) {
+    let todoMarkers = 0;
+    let frontendServerlessCalls = 0;
+    const hasCompatibilityShim = files['src/app/cards/_hsx-migration-run-serverless.ts'] !== undefined;
+    for (const [file, contents] of Object.entries(files)) {
+        todoMarkers += countMatches(contents, /TODO\(migration\)/g);
+        if (!hasCompatibilityShim && file.startsWith('src/app/cards/') && /\.(?:t|j)sx?$/.test(file)) {
+            frontendServerlessCalls += countMatches(contents, /\brunServerlessFunction\s*\(/g);
+        }
+    }
+    return {
+        todoMarkers,
+        frontendServerlessCalls,
+        total: todoMarkers + frontendServerlessCalls,
+    };
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null;
 }
@@ -73,6 +97,15 @@ 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.
 
+Guided mode:
+  hs-x migrate                                      In a terminal, choose a local project, live app, or cutover plan
+
+The guided journey discovers hsproject.json and migration.json sources beneath
+a workspace, inspects the selected source, previews its output, and asks for
+confirmation (default No) before writing. It generates a test dupe only: it
+never deploys or executes cutover. Press Esc to go back or Ctrl+C to cancel.
+For CI, JSON, JSON-stream, or redirected input, use an explicit command below.
+
 Commands:
   hs-x migrate run [path] [--out <dir>] [--json]   Detect, classify, and generate the dupe (the one command)
   hs-x migrate pull [--app-id <id>] [--json]       Pull a live app's definition into migration.json (no --app-id: pick from a list)
@@ -85,6 +118,69 @@ Commands:
 Run hs-x migrate <subcommand> --help for details on each step.
 `;
 }
+const liveMigratePromptDeps = {
+    isInteractive,
+    select: (options) => promptSelect({ ...options, allowBack: true }),
+    text: (options) => promptText({ ...options, allowBack: true }),
+    confirm: (options) => promptConfirm({ ...options, allowBack: true }),
+};
+/** Prompt-only seam: the root journey can be tested without filesystem or network effects. */
+export async function selectMigrateJourney(deps = liveMigratePromptDeps) {
+    const selected = await deps.select({
+        message: 'Where are you migrating from?',
+        options: [
+            {
+                value: 'local',
+                label: 'Local legacy project',
+                description: 'Inspect source on disk and generate a test dupe',
+            },
+            {
+                value: 'live',
+                label: 'Live HubSpot app',
+                description: 'Choose an app, pull migration.json, then generate a test dupe',
+            },
+            {
+                value: 'cutover',
+                label: 'Plan cutover',
+                description: 'Plan the in-place cutover, or --execute the one-way migration',
+            },
+        ],
+    });
+    return selected === BACK ? undefined : selected;
+}
+export async function confirmMigrateWrite(message, deps = liveMigratePromptDeps) {
+    const confirmed = await deps.confirm({ message, default: false, allowBack: true });
+    if (confirmed === BACK)
+        return 'back';
+    return confirmed === true ? 'proceed' : 'cancel';
+}
+/**
+ * Discover legacy migration sources beneath a workspace. `null` means no
+ * marker was found (callers retain their existing `.` fallback); undefined is
+ * prompt cancellation, and BACK returns to the preceding guided menu.
+ */
+export async function selectLocalMigrationSource(root, deps = liveMigratePromptDeps) {
+    const projects = await discoverLocalProjects({
+        root,
+        markers: ['hsproject.json', 'migration.json'],
+    });
+    const direct = projects.find((project) => project.relativePath === '.');
+    if (direct)
+        return '.';
+    if (projects.length === 0)
+        return null;
+    if (projects.length === 1)
+        return projects[0]?.relativePath ?? null;
+    return await deps.select({
+        message: 'Which local legacy project?',
+        options: projects.map((project) => ({
+            value: project.relativePath,
+            label: project.name,
+            description: `${project.relativePath} · ${project.marker}`,
+        })),
+        allowBack: true,
+    });
+}
 export function migrateSubcommandHelpText(sub) {
     switch (sub) {
         case 'run':
@@ -100,7 +196,8 @@ 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)
+  path                      Legacy source. When omitted, terminals discover
+                            workspace sources; scripts use the current directory.
 
 Flags:
   --out <dir>               Output directory (default: migrated-app)
@@ -123,26 +220,35 @@ HSX_HUBSPOT_DEVELOPER_ACCOUNT_ID).
 Flags:
   --app-id <id>             HubSpot app id (omit to pick interactively)
   --app-name <name>         Override the app name recorded in migration.json
-  --out <file>              Output file (default: migration.json)
+  --out <file>              Output file (default: migration.json; existing files are never overwritten)
   --cwd <dir>               Resolve paths relative to <dir>
   --json                    Emit JSON result (requires --app-id)
 `;
         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\`.
+Plan or perform the in-place cutover of the ORIGINAL app 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.
+Bare, it prints the DRY-RUN plan: the ordered steps, the one-way door (no
+downgrade from 2026.03), and every open decision (external receivers,
+endpoint contracts, marketplace listing) that gates execution.
+
+With --execute it performs the cutover, once no open decisions remain. It is
+a ONE-WAY change, so it asks you to type the project name to confirm (or pass
+--yes in automation; a non-TTY run without --yes is refused). 2025.2 sources
+take the config-only path (platformVersion bump + in-place re-upload, rolled
+back if the build fails); 2023.2/2025.1 sources run HubSpot's interactive
+\`hs project migrate\`, which needs a terminal to answer its feature prompts.
 
 Arguments:
-  path                      The ORIGINAL legacy source (default: current directory)
+  path                      The ORIGINAL legacy source. When omitted, terminals
+                            discover workspace sources; scripts use the current directory.
 
 Flags:
+  --execute                 Perform the cutover (default: dry-run plan only)
+  --yes                     Skip the type-to-confirm prompt (automation)
   --json                    Emit the plan as JSON
   --cwd <dir>               Resolve paths relative to <dir>
 `;
@@ -154,8 +260,8 @@ 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
+  path                      A project directory (hsproject.json tree), a
+                            migration.json file, or a directory containing one
 
 Flags:
   --cwd <dir>               Resolve <path> relative to <dir>
@@ -170,8 +276,8 @@ 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
+  path                      A project directory (hsproject.json tree), a
+                            migration.json file, or a directory containing one
 
 Flags:
   --cwd <dir>               Resolve <path> relative to <dir>
@@ -185,8 +291,8 @@ 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
+  path                      A project directory (hsproject.json tree), a
+                            migration.json file, or a directory containing one
 
 Flags:
   --project <dir>           Output directory (default: migrated-app)
@@ -238,7 +344,9 @@ function readMigrationInputEff(path) {
     return Effect.gen(function* () {
         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)}`)));
+        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));
@@ -258,7 +366,9 @@ function readMigrationInputEff(path) {
             }
         }
         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)}`)));
+        const contents = yield* fs
+            .readFileString(file)
+            .pipe(Effect.mapError((cause) => cliError('HSX_E_INTERNAL', `Could not read ${file}: ${String(cause)}`)));
         return yield* Effect.try({
             try: () => JSON.parse(contents),
             catch: (cause) => cliError('HSX_E_INPUT_BAD_JSON', `Invalid JSON in ${file}: ${String(cause)}`),
@@ -272,9 +382,30 @@ function writeProjectFilesEff(root, files) {
         const pathSvc = yield* Path.Path;
         for (const [file, contents] of Object.entries(files)) {
             const target = pathSvc.join(root, file);
-            yield* fs.makeDirectory(pathSvc.dirname(target), { recursive: true }).pipe(Effect.mapError((cause) => cliError('HSX_E_INTERNAL', `Could not create directory for ${target}: ${String(cause)}`)));
-            yield* fs.writeFileString(target, contents, { flag: 'wx' }).pipe(Effect.mapError((cause) => cliError('HSX_E_INTERNAL', `Could not write ${target}: ${String(cause)}`)));
+            yield* fs
+                .makeDirectory(pathSvc.dirname(target), { recursive: true })
+                .pipe(Effect.mapError((cause) => cliError('HSX_E_INTERNAL', `Could not create directory for ${target}: ${String(cause)}`)));
+            yield* fs
+                .writeFileString(target, contents, { flag: 'wx' })
+                .pipe(Effect.mapError((cause) => cliError('HSX_E_INTERNAL', `Could not write ${target}: ${String(cause)}`)));
+        }
+    });
+}
+function resolveMigrationCommandPath(input) {
+    return Effect.gen(function* () {
+        if (Option.isSome(input.path))
+            return input.path.value;
+        const cwd = yield* Cwd;
+        const reporter = yield* Reporter;
+        const root = Option.getOrElse(input.cwd, () => cwd);
+        if (input.json || reporter.mode === 'ndjson' || !isInteractive())
+            return '.';
+        const selected = yield* Effect.promise(() => selectLocalMigrationSource(root));
+        if (selected === undefined || selected === BACK) {
+            yield* reporter.info('Cancelled.');
+            return yield* Effect.fail(exitWith(130));
         }
+        return selected ?? '.';
     });
 }
 function migrateInspectBody(opts) {
@@ -435,12 +566,14 @@ function migrateRunBody(opts) {
         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 outstandingWork = migrationOutstandingWork(generated.files);
         const response = {
             ok: validation.ok,
             command: 'migrate run',
             outputRoot,
             createdFiles: Object.keys(generated.files).sort(),
             inspect: result,
+            outstandingWork,
             validation,
         };
         if (opts.json) {
@@ -450,9 +583,16 @@ function migrateRunBody(opts) {
             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)
+            const scaffoldedStubs = result.automatable.filter((finding) => finding.code === 'serverless.app-function.portable');
+            const portedAutomatically = result.automatable.filter((finding) => finding.code !== 'serverless.app-function.portable');
+            if (portedAutomatically.length > 0) {
+                yield* reporter.info('Ported automatically:');
+                for (const finding of portedAutomatically)
+                    yield* reporter.info(`  - ${finding.message}`);
+            }
+            if (scaffoldedStubs.length > 0) {
+                yield* reporter.info('Scaffolded (stub — port body):');
+                for (const finding of scaffoldedStubs)
                     yield* reporter.info(`  - ${finding.message}`);
             }
             if (result.manualWork.length > 0) {
@@ -471,11 +611,22 @@ function migrateRunBody(opts) {
                     yield* reporter.error(d.code ?? 'diagnostic', d.message ?? JSON.stringify(d));
                 }
             }
+            if (outstandingWork.total > 0) {
+                yield* reporter.info('');
+                yield* reporter.info(`Outstanding migration work: ${outstandingWork.todoMarkers} TODO marker(s), ${outstandingWork.frontendServerlessCalls} frontend serverless call(s) (${outstandingWork.total} total).`);
+                yield* reporter.info('The dupe is scaffolded for testing; it is not production-ready yet.');
+            }
             yield* reporter.info('');
             yield* reporter.info('Next steps:');
             yield* reporter.info(`  cd ${pathSvc.relative(root, outputRoot) || '.'} && bun install`);
+            if (opts.guided) {
+                yield* reporter.info('  hs-x check        # validate the generated project again after edits');
+            }
             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');
+            if (opts.guided && opts.originalSource) {
+                yield* reporter.info(`  hs-x migrate cutover ${opts.originalSource}  # review the dry-run cutover plan`);
+            }
             yield* reporter.done(validation.ok ? 'Migrated' : 'Failed', validation.ok ? 0 : 1);
         }
         if (!validation.ok) {
@@ -570,7 +721,7 @@ function swapCardsArgv(opts) {
         argv.push('--user-id', opts.userId.value);
     return argv;
 }
-const migrateRunPathArg = Args.text({ name: 'path' }).pipe(Args.withDefault('.'));
+const migrateRunPathArg = Args.text({ name: 'path' }).pipe(Args.optional);
 const migrateOutOption = Options.text('out').pipe(Options.optional);
 /**
  * `hs-x migrate cutover [path]` — DRY-RUN ONLY today (locked decision #2:
@@ -579,43 +730,134 @@ const migrateOutOption = Options.text('out').pipe(Options.optional);
  * in place, plus the open decisions gating execution.
  */
 /**
- * Cutover EXECUTE (2026-06-10 authorization): may run ONLY against net-new
- * throwaway apps on the owner's developer account 46993937 — never client
- * apps. 2025.2 sources execute the config-only path (platformVersion bump +
- * in-place re-upload of the ORIGINAL tree, same app id). 2023.2/2025.1
- * (`hs project migrate` semantics) stay gated until that API path is
- * grounded and rehearsed.
+ * Not every open decision blocks an in-place cutover. Cutover re-uploads the
+ * SAME source under a new platform version (2025.2), or runs HubSpot's own
+ * `hs project migrate` (2023.2/2025.1), so "keep forwarding?" / "confirm this
+ * surface" findings are advisory — surfaced, then covered by the type-to-confirm.
+ * Only findings that mean the source is missing something required (a URL,
+ * entrypoint, or label) or carries an unsupported/empty component genuinely
+ * block: those can't be resolved by proceeding.
+ */
+function isBlockingCutoverDecision(code) {
+    return (code === 'migration.input.unsupported' ||
+        code.startsWith('component.unsupported.') ||
+        code.endsWith('.missing') ||
+        code.endsWith('.empty'));
+}
+/**
+ * `confirmCutover` — the human checkpoint. Cutover is a one-way, in-place
+ * change to the ORIGINAL app, so execution requires the operator to type the
+ * project name back (or pass --yes in automation). It never runs unattended by
+ * default: a non-TTY run without --yes is refused rather than assumed.
+ */
+function confirmCutover(input) {
+    const { reporter, projectName, yes } = input;
+    return Effect.gen(function* () {
+        if (yes) {
+            yield* reporter.info(`--yes: skipping the type-to-confirm for "${projectName}".`);
+            return;
+        }
+        if (!isInteractive()) {
+            return yield* Effect.fail(cliError('HSX_E_CUTOVER_CONFIRM_REQUIRED', 'Cutover is a one-way, in-place change to the original app. Re-run in an interactive terminal to confirm, or pass --yes to skip the prompt in automation.'));
+        }
+        yield* reporter.info(`ONE-WAY: "${projectName}" cannot downgrade from 2026.03 after cutover.`);
+        const answer = yield* Effect.tryPromise({
+            try: () => promptText({ message: 'Type the project name to confirm cutover' }),
+            catch: () => cliError('HSX_E_INTERNAL', 'Could not read confirmation input.'),
+        });
+        if (answer === undefined || answer.trim() !== projectName) {
+            return yield* Effect.fail(cliError('HSX_E_CUTOVER_CONFIRM_MISMATCH', `Confirmation "${answer?.trim() ?? ''}" did not match the project name "${projectName}". Cutover aborted; nothing changed.`));
+        }
+    });
+}
+/**
+ * Cutover EXECUTE: migrates the ORIGINAL app in place to 2026.03, keeping its
+ * app id, installs, OAuth grants, and listing — a one-way door. Gated by (1) no
+ * open decisions in the plan, (2) an explicit human confirmation (type the
+ * project name, or --yes), and (3) a supported source era:
+ *   • 2025.2 — config-only: bump platformVersion → 2026.03 and re-upload in
+ *     place (rolled back if the build fails).
+ *   • 2023.2 / 2025.1 — HubSpot's own interactive `hs project migrate` (needs a
+ *     real terminal to answer its feature-confirmation prompts).
+ * Non-project legacy apps (`hs app migrate`) are out of scope for cutover.
  */
-const CUTOVER_REHEARSAL_DEVELOPER_ACCOUNT = '46993937';
 function executeCutover(input) {
     const { opts, sourcePath, reporter } = input;
     return Effect.gen(function* () {
         const fs = yield* FileSystem.FileSystem;
         const developerAccountId = process.env.HSX_HUBSPOT_DEVELOPER_ACCOUNT_ID ?? '';
-        if (developerAccountId !== CUTOVER_REHEARSAL_DEVELOPER_ACCOUNT) {
-            return yield* Effect.fail(cliError('HSX_E_CUTOVER_EXECUTE_GATED', `Cutover execution is authorized only for throwaway apps on developer account ${CUTOVER_REHEARSAL_DEVELOPER_ACCOUNT} (got ${developerAccountId || 'none'}). Real-app cutover needs an explicit per-app human go.`));
-        }
         const detected = yield* Effect.tryPromise({
             try: () => detectMigrationSource(sourcePath),
             catch: (cause) => cliError('HSX_E_INTERNAL', `Could not inspect ${sourcePath}: ${String(cause)}`),
         });
         const classification = classifyMigrationInput(detected.input);
         const plan = planCutover(detected, classification);
-        if (plan.openDecisions.length > 0) {
-            return yield* Effect.fail(cliError('HSX_E_CUTOVER_EXECUTE_GATED', `${plan.openDecisions.length} open decision(s) gate execution: ${plan.openDecisions
+        const blockingDecisions = plan.openDecisions.filter((decision) => isBlockingCutoverDecision(decision.code));
+        const advisoryDecisions = plan.openDecisions.filter((decision) => !isBlockingCutoverDecision(decision.code));
+        if (blockingDecisions.length > 0) {
+            return yield* Effect.fail(cliError('HSX_E_CUTOVER_EXECUTE_GATED', `${blockingDecisions.length} blocking decision(s) prevent cutover: ${blockingDecisions
                 .map((decision) => decision.code)
-                .join(', ')}. Resolve them, re-run the dry-run, then execute.`));
+                .join(', ')}. The source is missing something cutover needs (a URL, entrypoint, or label) or carries an unsupported component — fix it in the source, re-run the dry-run, then execute.`));
         }
-        if (plan.sourceVersion !== '2025.2') {
-            return yield* Effect.fail(cliError('HSX_E_CUTOVER_EXECUTE_GATED', `Execute currently supports the 2025.2 config-only path; ${plan.sourceVersion} sources go through \`hs project migrate\` semantics, which stay human-driven until that leg is rehearsed.`));
+        // Advisory findings don't block an in-place cutover; surface them so the
+        // operator sees exactly what they're acknowledging at the confirm prompt.
+        for (const decision of advisoryDecisions) {
+            yield* reporter.info(`advisory [${decision.code}]: ${decision.message}`);
         }
-        // 2025.2 config-only execute: bump platformVersion IN PLACE, re-upload
-        // the original tree (same project name => same app id), watch the build.
+        // Cutover execute operates on the ORIGINAL project tree.
         const projectConfigPath = `${sourcePath}/hsproject.json`;
         const rawProject = yield* fs
             .readFileString(projectConfigPath)
-            .pipe(Effect.mapError(() => cliError('HSX_E_INTERNAL', `Could not read ${projectConfigPath}.`)));
+            .pipe(Effect.mapError(() => cliError('HSX_E_CUTOVER_EXECUTE_GATED', `Cutover execute needs the original project tree (hsproject.json) at ${sourcePath}; a migration.json input alone is not enough. Point at the ORIGINAL legacy app's source.`)));
         const projectJson = JSON.parse(rawProject);
+        const projectName = typeof projectJson.name === 'string' && projectJson.name.length > 0
+            ? projectJson.name
+            : 'migrated-app';
+        const yes = opts.yes ?? false;
+        // 2023.2 / 2025.1 → HubSpot's own interactive `hs project migrate`. It
+        // prompts to confirm the features it migrates, so it needs a real terminal;
+        // HS-X gates entry, then hands the wheel to HubSpot's CLI (inherited stdio).
+        if (plan.sourceVersion === '2023.2' || plan.sourceVersion === '2025.1') {
+            if (!isInteractive()) {
+                return yield* Effect.fail(cliError('HSX_E_CUTOVER_CONFIRM_REQUIRED', `Cutover for a ${plan.sourceVersion} project runs HubSpot's interactive \`hs project migrate\`, which prompts to confirm the features it migrates. Run it in an interactive terminal — --yes skips HS-X's own confirmation but cannot answer HubSpot's prompts.`));
+            }
+            yield* confirmCutover({ reporter, projectName, yes });
+            yield* reporter.info("Running HubSpot's project migration in place (hs project migrate → 2026.03). Answer its feature prompts to complete the one-way migration…");
+            const migrateExit = yield* Effect.tryPromise({
+                try: async () => {
+                    const proc = Bun.spawn({
+                        cmd: [
+                            'hs',
+                            'project',
+                            'migrate',
+                            '--platform-version',
+                            '2026.03',
+                            ...(developerAccountId.length > 0 ? ['--account', developerAccountId] : []),
+                        ],
+                        cwd: sourcePath,
+                        env: { ...process.env },
+                        stdin: 'inherit',
+                        stdout: 'inherit',
+                        stderr: 'inherit',
+                    });
+                    return await proc.exited;
+                },
+                catch: (cause) => cliError('HSX_E_CUTOVER_EXECUTE_FAILED', `Could not run \`hs project migrate\` (${String(cause)}). Cutover drives HubSpot's own CLI — install it (npm i -g @hubspot/cli) and authenticate (hs accounts auth).`),
+            });
+            if (migrateExit !== 0) {
+                return yield* Effect.fail(cliError('HSX_E_CUTOVER_EXECUTE_FAILED', `\`hs project migrate\` exited ${migrateExit}; the original app was not migrated (a failed or cancelled migration leaves your project as HubSpot found it).`));
+            }
+            yield* reporter.info(`Original ${plan.sourceVersion} app migrated to 2026.03 — app id, installs, and OAuth grants preserved.`);
+            yield* reporter.info('Note: serverless env vars declared via serverless.json `environment` are not migrated automatically — redefine them as secrets with `hs secret add`.');
+            yield* reporter.info('Next: verify capabilities, then deprecate/delete the dupe.');
+            return yield* reporter.done('Cutover executed');
+        }
+        if (plan.sourceVersion !== '2025.2') {
+            return yield* Effect.fail(cliError('HSX_E_CUTOVER_EXECUTE_GATED', `Cutover execute covers project-based 2023.2, 2025.1, and 2025.2 sources; this source resolves to "${plan.sourceVersion}". A non-project legacy app migrates with HubSpot's own interactive \`hs app migrate\`, which cutover does not wrap.`));
+        }
+        // 2025.2 config-only execute: bump platformVersion IN PLACE, re-upload
+        // the original tree (same project name => same app id), watch the build.
+        yield* confirmCutover({ reporter, projectName, yes });
         const previousVersion = projectJson.platformVersion;
         projectJson.platformVersion = '2026.03';
         yield* fs
@@ -646,8 +888,7 @@ function executeCutover(input) {
             catch: (cause) => cliError('HSX_E_CUTOVER_EXECUTE_FAILED', `Could not run \`hs project upload\` (${String(cause)}). Cutover drives HubSpot's own CLI — install it (npm i -g @hubspot/cli) and authenticate (hs accounts auth).`),
         });
         const uploadOutput = `${result.stdout}\n${result.stderr}`;
-        const buildLine = /Build #(\d+) succeeded/.exec(uploadOutput) ??
-            /Built [\w-]+ #(\d+)/.exec(uploadOutput);
+        const buildLine = /Build #(\d+) succeeded/.exec(uploadOutput) ?? /Built [\w-]+ #(\d+)/.exec(uploadOutput);
         if (result.exitCode !== 0 || !buildLine) {
             // Roll the version bump back so a failed execute leaves the tree as found.
             projectJson.platformVersion = previousVersion;
@@ -693,31 +934,29 @@ function migrateCutoverBody(opts) {
                 continue;
             yield* reporter.info(`${phase.toUpperCase()}:`);
             for (const step of phaseSteps) {
-                yield* reporter.info(`  - ${step.title}${step.gatedBy ? `  [gated: ${step.gatedBy}]` : ''}`);
+                const tag = step.gatedBy
+                    ? `  [${isBlockingCutoverDecision(step.gatedBy) ? 'blocks' : 'confirm'}: ${step.gatedBy}]`
+                    : '';
+                yield* reporter.info(`  - ${step.title}${tag}`);
                 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.`);
+            const blockingCount = plan.openDecisions.filter((decision) => isBlockingCutoverDecision(decision.code)).length;
+            yield* reporter.info(blockingCount > 0
+                ? `${blockingCount} of ${plan.openDecisions.length} decision(s) BLOCK execution (missing/unsupported) — fix them in the source, then re-run with --execute. The rest are advisory confirmations.`
+                : `${plan.openDecisions.length} advisory decision(s) to confirm; none block. Re-run with --execute to perform the one-way, in-place cutover — you confirm by typing the project name (or pass --yes in automation).`);
         }
         else {
-            yield* reporter.info('No open decisions. Execution still requires an explicit human go (see LAUNCH-PLAN NEEDS HUMAN).');
+            yield* reporter.info('No open decisions. Re-run with --execute to perform the one-way, in-place cutover — you confirm by typing the project name (or pass --yes in automation).');
         }
         yield* reporter.done('Planned');
     });
 }
 const migrateExecuteOption = Options.boolean('execute').pipe(Options.withDefault(false));
-const migrateCutoverPathArg = Args.text({ name: 'path' }).pipe(Args.withDefault('.'));
-/**
- * `hs-x migrate pull --app-id <id>` — live-app pull (locked decision #4,
- * live half): fetch a UI-configured legacy app's definition via HubSpot
- * APIs (PAK auth) and write the migration.json input the classifier and
- * generator already consume. Endpoints grounded 2026-06-10:
- * cards GET /crm/extensions/cards-dev/2026-03/{appId}; webhooks
- * GET /webhooks/v3/{appId}/settings + /subscriptions; workflow actions
- * GET /automation/v4/actions/{appId}.
- */
+const migrateYesOption = Options.boolean('yes').pipe(Options.withDefault(false));
+const migrateCutoverPathArg = Args.text({ name: 'path' }).pipe(Args.optional);
 function migratePullBody(opts) {
     return Effect.gen(function* () {
         const cwd = yield* Cwd;
@@ -725,6 +964,11 @@ function migratePullBody(opts) {
         const fs = yield* FileSystem.FileSystem;
         const reporter = yield* Reporter;
         const root = Option.getOrElse(opts.cwd, () => cwd);
+        const outPath = pathSvc.resolve(root, opts.out);
+        const outputExists = yield* fs.exists(outPath).pipe(Effect.orElseSucceed(() => false));
+        if (outputExists) {
+            return yield* Effect.fail(cliError('HSX_E_INPUT_BAD_FIELD', `${outPath} already exists; refusing to overwrite migration input. Choose another file with --out <file> or move the existing file.`));
+        }
         const personalAccessKey = process.env.HSX_HUBSPOT_PAK;
         const portalId = process.env.HSX_HUBSPOT_DEVELOPER_ACCOUNT_ID;
         if (!personalAccessKey || !portalId) {
@@ -820,10 +1064,11 @@ function migratePullBody(opts) {
             },
             catch: (cause) => cliError('HSX_E_INTERNAL', `Live pull failed: ${cause instanceof Error ? cause.message : String(cause)}`),
         });
+        const appName = Option.getOrElse(opts.appName, () => pickedAppName ?? `app-${appId}`);
         const input = {
             legacyApp: {
                 appId,
-                name: Option.getOrElse(opts.appName, () => pickedAppName ?? `app-${appId}`),
+                name: appName,
                 portalId,
             },
         };
@@ -831,8 +1076,8 @@ function migratePullBody(opts) {
         const cardResults = isRecord(pulled.cards) && Array.isArray(pulled.cards.results)
             ? pulled.cards.results.filter(isRecord)
             : [];
-        if (cardResults.length > 0) {
-            const card = cardResults[0];
+        const card = cardResults[0];
+        if (card) {
             const title = isRecord(card.title) ? '' : String(card.title ?? '');
             const fetchData = isRecord(card.fetch) ? card.fetch : {};
             input.legacyCard = {
@@ -885,21 +1130,24 @@ function migratePullBody(opts) {
             }));
             detected.push(`workflow actions ×${actionResults.length}`);
         }
-        const outPath = pathSvc.resolve(root, opts.out);
         yield* fs
-            .writeFileString(outPath, `${JSON.stringify(input, null, 2)}\n`)
-            .pipe(Effect.mapError(() => cliError('HSX_E_INTERNAL', `Could not write ${outPath}.`)));
+            .writeFileString(outPath, `${JSON.stringify(input, null, 2)}\n`, { flag: 'wx' })
+            .pipe(Effect.mapError(() => cliError('HSX_E_INTERNAL', `Could not create ${outPath}; it may already exist. Choose another file with --out <file>.`)));
+        const result = { appId, appName, outPath };
         if (opts.json) {
             yield* reporter.raw(`${JSON.stringify({ ok: true, command: 'migrate pull', appId, out: outPath, detected }, null, 2)}\n`);
-            return;
+            return result;
         }
         yield* reporter.header(`pulled app ${appId}`);
         for (const warning of pulled.warnings) {
             yield* reporter.info(`note: ${warning}`);
         }
-        yield* reporter.info(detected.length > 0 ? `Detected: ${detected.join(', ')}` : 'Nothing portable detected on this app.');
+        yield* reporter.info(detected.length > 0
+            ? `Detected: ${detected.join(', ')}`
+            : 'Nothing portable detected on this app.');
         yield* reporter.info(`Wrote ${outPath} — next: hs-x migrate run ${pathSvc.relative(cwd, outPath) || opts.out}`);
         yield* reporter.done('Pulled');
+        return result;
     });
 }
 /**
@@ -944,6 +1192,173 @@ async function fetchMigratableApps(accessToken, portalId) {
     }
     return out;
 }
+function migrateCancelled(reporter) {
+    return Effect.gen(function* () {
+        yield* reporter.info('Cancelled.');
+        return yield* Effect.fail(exitWith(130));
+    });
+}
+function renderGuidedPreview(input, sourcePath, outputPath) {
+    const classification = classifyMigrationInput(input);
+    let files = 0;
+    try {
+        files = Object.keys(generateMigratedHsxProject(input).files).length;
+    }
+    catch {
+        // The existing run body owns the detailed generation failure. The preview
+        // still gives the user the classification before asking for consent.
+    }
+    return `${renderMigrationInspect(classification).trimEnd()}\nPreview: generate ${files || 'no'} file${files === 1 ? '' : 's'} from ${sourcePath} into ${outputPath}.`;
+}
+function migrateRootBody(opts, deps = liveMigratePromptDeps) {
+    return Effect.gen(function* () {
+        const cwd = yield* Cwd;
+        const pathSvc = yield* Path.Path;
+        const fs = yield* FileSystem.FileSystem;
+        const reporter = yield* Reporter;
+        if (opts.json || reporter.mode === 'ndjson' || !deps.isInteractive()) {
+            return yield* Effect.fail(cliError('HSX_E_INPUT_MISSING_VALUE', 'Bare `hs-x migrate` is a terminal guide. For automation use `hs-x migrate run <path> --out <dir>`, `hs-x migrate pull --app-id <id> --out <file>`, or `hs-x migrate cutover <path>`.'));
+        }
+        const root = Option.getOrElse(opts.cwd, () => cwd);
+        yield* reporter.banner;
+        yield* reporter.header('guided migration');
+        for (;;) {
+            const journey = yield* Effect.promise(() => selectMigrateJourney(deps));
+            if (!journey)
+                return yield* migrateCancelled(reporter);
+            if (journey === 'cutover') {
+                const suggestedSource = yield* Effect.promise(() => selectLocalMigrationSource(root, deps));
+                if (suggestedSource === BACK)
+                    continue;
+                if (suggestedSource === undefined)
+                    return yield* migrateCancelled(reporter);
+                const source = yield* Effect.promise(() => deps.text({
+                    message: 'Original legacy source',
+                    default: suggestedSource ?? '.',
+                    allowBack: true,
+                }));
+                if (source === BACK)
+                    continue;
+                if (source === undefined)
+                    return yield* migrateCancelled(reporter);
+                return yield* migrateCutoverBody({
+                    path: source,
+                    cwd: Option.some(root),
+                    json: false,
+                    execute: false,
+                    yes: false,
+                });
+            }
+            if (journey === 'live') {
+                let pullOut = 'migration.json';
+                for (;;) {
+                    const answer = yield* Effect.promise(() => deps.text({
+                        message: 'Save the pulled migration input as',
+                        default: pullOut,
+                        allowBack: true,
+                    }));
+                    if (answer === BACK)
+                        break;
+                    if (answer === undefined)
+                        return yield* migrateCancelled(reporter);
+                    pullOut = answer;
+                    const pullPath = pathSvc.resolve(root, pullOut);
+                    if (yield* fs.exists(pullPath).pipe(Effect.orElseSucceed(() => false))) {
+                        yield* reporter.warn('HSX_E_INPUT_BAD_FIELD', `${pullPath} already exists. Choose another file; HS-X never overwrites migration input.`);
+                        continue;
+                    }
+                    yield* reporter.info(`Preview: choose an eligible app from HubSpot and write its portable definition to ${pullPath}.`);
+                    const pullConfirmed = yield* Effect.promise(() => confirmMigrateWrite('Pull the live app and write this migration input?', deps));
+                    if (pullConfirmed === 'back')
+                        continue;
+                    if (pullConfirmed !== 'proceed')
+                        return yield* migrateCancelled(reporter);
+                    const pulled = yield* migratePullBody({
+                        appId: Option.none(),
+                        appName: Option.none(),
+                        out: pullOut,
+                        cwd: Option.some(root),
+                        json: false,
+                    });
+                    const input = yield* readMigrationInputEff(pulled.outPath);
+                    let output = 'migrated-app';
+                    for (;;) {
+                        const outputAnswer = yield* Effect.promise(() => deps.text({
+                            message: 'Generate the test dupe in',
+                            default: output,
+                            allowBack: true,
+                        }));
+                        if (outputAnswer === BACK)
+                            continue;
+                        if (outputAnswer === undefined)
+                            return yield* migrateCancelled(reporter);
+                        output = outputAnswer;
+                        const outputPath = pathSvc.resolve(root, output);
+                        yield* reporter.block(renderGuidedPreview(input, pulled.outPath, outputPath));
+                        const generateConfirmed = yield* Effect.promise(() => confirmMigrateWrite('Generate and validate this test dupe?', deps));
+                        if (generateConfirmed === 'back')
+                            continue;
+                        if (generateConfirmed !== 'proceed')
+                            return yield* migrateCancelled(reporter);
+                        return yield* migrateRunBody({
+                            path: pulled.outPath,
+                            out: Option.some(output),
+                            cwd: Option.some(root),
+                            json: false,
+                            guided: true,
+                            originalSource: pulled.outPath,
+                        });
+                    }
+                }
+                continue;
+            }
+            const suggestedSource = yield* Effect.promise(() => selectLocalMigrationSource(root, deps));
+            if (suggestedSource === BACK)
+                continue;
+            if (suggestedSource === undefined)
+                return yield* migrateCancelled(reporter);
+            let source = suggestedSource ?? '.';
+            for (;;) {
+                const sourceAnswer = yield* Effect.promise(() => deps.text({ message: 'Local legacy source', default: source, allowBack: true }));
+                if (sourceAnswer === BACK)
+                    break;
+                if (sourceAnswer === undefined)
+                    return yield* migrateCancelled(reporter);
+                source = sourceAnswer;
+                const sourcePath = pathSvc.resolve(root, source);
+                const input = yield* readMigrationInputEff(sourcePath);
+                let output = 'migrated-app';
+                for (;;) {
+                    const outputAnswer = yield* Effect.promise(() => deps.text({
+                        message: 'Generate the test dupe in',
+                        default: output,
+                        allowBack: true,
+                    }));
+                    if (outputAnswer === BACK)
+                        break;
+                    if (outputAnswer === undefined)
+                        return yield* migrateCancelled(reporter);
+                    output = outputAnswer;
+                    const outputPath = pathSvc.resolve(root, output);
+                    yield* reporter.block(renderGuidedPreview(input, sourcePath, outputPath));
+                    const confirmed = yield* Effect.promise(() => confirmMigrateWrite('Generate and validate this test dupe?', deps));
+                    if (confirmed === 'back')
+                        continue;
+                    if (confirmed !== 'proceed')
+                        return yield* migrateCancelled(reporter);
+                    return yield* migrateRunBody({
+                        path: source,
+                        out: Option.some(output),
+                        cwd: Option.some(root),
+                        json: false,
+                        guided: true,
+                        originalSource: source,
+                    });
+                }
+            }
+        }
+    });
+}
 const migratePullAppIdOption = Options.text('app-id').pipe(Options.optional);
 const migratePullNameOption = Options.text('app-name').pipe(Options.optional);
 const migratePullOutOption = Options.text('out').pipe(Options.withDefault('migration.json'));
@@ -953,10 +1368,22 @@ const migratePullCmd = Command.make('pull', {
     out: migratePullOutOption,
     cwd: cwdOption,
     json: jsonOption,
-}, (opts) => runHandler('migrate', { json: opts.json }, migratePullBody(opts)));
-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([
+}, (opts) => runHandler('migrate', { json: opts.json }, Effect.asVoid(migratePullBody(opts))));
+const migrateCutoverCmd = Command.make('cutover', {
+    path: migrateCutoverPathArg,
+    cwd: cwdOption,
+    json: jsonOption,
+    execute: migrateExecuteOption,
+    yes: migrateYesOption,
+}, (opts) => runHandler('migrate', { json: opts.json }, Effect.gen(function* () {
+    const path = yield* resolveMigrationCommandPath(opts);
+    yield* migrateCutoverBody({ ...opts, path });
+})));
+const migrateRunCmd = Command.make('run', { path: migrateRunPathArg, out: migrateOutOption, cwd: cwdOption, json: jsonOption }, (opts) => runHandler('migrate', { json: opts.json }, Effect.gen(function* () {
+    const path = yield* resolveMigrationCommandPath(opts);
+    yield* migrateRunBody({ ...opts, path });
+})));
+export const migrateCmd = Command.make('migrate', { cwd: cwdOption, json: jsonOption }, (opts) => runHandler('migrate', { json: opts.json }, migrateRootBody(opts))).pipe(Command.withSubcommands([
     migrateRunCmd,
     migratePullCmd,
     migrateCutoverCmd,