nx 23.2.0-beta.7 → 23.2.0-beta.8

package/dist/src/command-line/migrate/run/util.js

@@ -1,16 +1,148 @@
 "use strict";
 // Internal to run/: deliberately not re-exported from ./index.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.nowIso = nowIso;
+exports.depsHash = depsHash;
+exports.installDepsChangedSinceDispense = installDepsChangedSinceDispense;
+exports.recordInstallLanded = recordInstallLanded;
+exports.isPidAlive = isPidAlive;
+exports.summarizeError = summarizeError;
+exports.warnCommitFailed = warnCommitFailed;
 exports.pmExecPrefix = pmExecPrefix;
+exports.pmInstallCommand = pmInstallCommand;
+const crypto_1 = require("crypto");
 const package_manager_1 = require("../../../utils/package-manager");
-const cachedPmExecPrefix = new Map();
+const execute_migration_1 = require("../execute-migration");
+const state_lock_1 = require("./state-lock");
+const agent_output_1 = require("./agent-output");
+function nowIso() {
+    return new Date().toISOString();
+}
+/**
+ * Fingerprints the workspace dependencies so a step can persist what they
+ * looked like and a later actor can still tell whether the migration changed
+ * them. Hashed rather than stored verbatim to keep run.json small; the value
+ * is only ever compared for equality.
+ *
+ * `null` means the probe itself failed. Callers must not read that as
+ * "unchanged": the value is persisted and compared across processes, so a
+ * failed read on either end would otherwise silently skip an install that was
+ * needed.
+ */
+function depsHash(root) {
+    const deps = (0, execute_migration_1.readPackageJsonDeps)(root);
+    return deps === null ? null : (0, crypto_1.createHash)('sha256').update(deps).digest('hex');
+}
+/**
+ * Installs when the workspace dependencies differ from the step's recorded
+ * baseline, so a prompt applied by another actor, or a retry that only has the
+ * commit left to do, still installs what the changes need. Comparing against
+ * the persisted baseline is what makes that possible: by the time either runs,
+ * the edits are already on disk, so a snapshot taken here would see them as
+ * the starting point and never detect a change.
+ *
+ * The baseline is re-pointed at the current dependencies once the install
+ * lands, so the next actor to compare does not install the same change again.
+ *
+ * Every probe failure installs, on either end of the comparison. A step whose
+ * dispense-time probe failed has no baseline, which says the dependencies it
+ * started from are unknown rather than unchanged, and skipping there would
+ * strand the change with nothing left to detect it.
+ */
+async function installDepsChangedSinceDispense(root, dir, step, skipInstall, rerunCommand) {
+    const current = depsHash(root);
+    if (current !== null && current === step.depsHashAtDispense)
+        return;
+    if (skipInstall) {
+        (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
+        return;
+    }
+    await (0, execute_migration_1.runInstall)(root, 'post-migration', rerunCommand);
+    recordInstallLanded(root, dir, step.id);
+}
+/**
+ * Records what an install that just landed means for the run: the installing
+ * step's dependency baseline moves to what is now on disk, and every step's
+ * install-failure mark clears.
+ *
+ * The baseline has to move, or the next actor to compare (the prompt fold, a
+ * retry, the step's own commit) reads the step's own edits as an unapplied
+ * change and pays a second full install. The marks clear because the package
+ * manager installs the whole workspace package.json, so this install also
+ * covers the dependency edits of every earlier step that failed to install its
+ * own.
+ *
+ * A failed probe leaves the baseline alone: an install that runs twice costs
+ * time, one that never runs leaves the workspace inconsistent with its
+ * package.json.
+ *
+ * Never throws. It runs inside callers that treat a throw as "the install
+ * failed", and the install has already succeeded by then. A run state this
+ * cannot read or write is a real problem, but it is reported by the next
+ * mandatory write rather than misattributed here, and the only cost of losing
+ * this one is a redundant install later.
+ */
+function recordInstallLanded(root, dir, stepId) {
+    const hash = depsHash(root);
+    try {
+        (0, state_lock_1.updateRunState)(dir, (fresh) => {
+            const baselineMoves = fresh.steps.some((s) => s.id === stepId && hash !== null && s.depsHashAtDispense !== hash);
+            if (!baselineMoves && !fresh.steps.some((s) => s.installFailed)) {
+                return null;
+            }
+            return {
+                ...fresh,
+                steps: fresh.steps.map(({ installFailed, ...s }) => s.id === stepId && baselineMoves
+                    ? { ...s, depsHashAtDispense: hash }
+                    : s),
+            };
+        });
+    }
+    catch {
+        // See above: the install already succeeded, so a state failure here must
+        // not be reported as an install failure.
+    }
+}
+// ESRCH means the process is gone; EPERM means it exists but isn't ours (alive).
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+// The agent reads this to decide retry-vs-skip, so keep it to the error's
+// first line and bound the length rather than dumping a multi-line stack.
+function summarizeError(e) {
+    const message = e instanceof Error ? e.message : String(e);
+    const firstLine = message.split('\n')[0].trim();
+    return firstLine.length > 200 ? `${firstLine.slice(0, 197)}...` : firstLine;
+}
+// The commit helper reports its own failures via the result status and logs
+// the details itself; `cause` is set only when the attempt threw instead
+// (the pre-commit dependency install), which nothing else has logged.
+function warnCommitFailed(name, cause) {
+    const causeText = cause === undefined ? '' : ` (${summarizeError(cause)})`;
+    (0, agent_output_1.warnToAgent)({
+        title: `The commit for ${name} could not be created${causeText}; its changes remain in the working tree for a later commit to absorb.`,
+    });
+}
+const cachedPmCommands = new Map();
 // getPackageManagerCommand can shell out to detect a version, so cache the
 // result per root.
-function pmExecPrefix(root) {
-    let prefix = cachedPmExecPrefix.get(root);
-    if (prefix === undefined) {
-        prefix = (0, package_manager_1.getPackageManagerCommand)((0, package_manager_1.detectPackageManager)(root), root).exec;
-        cachedPmExecPrefix.set(root, prefix);
+function pmCommands(root) {
+    let commands = cachedPmCommands.get(root);
+    if (commands === undefined) {
+        commands = (0, package_manager_1.getPackageManagerCommand)((0, package_manager_1.detectPackageManager)(root), root);
+        cachedPmCommands.set(root, commands);
     }
-    return prefix;
+    return commands;
+}
+function pmExecPrefix(root) {
+    return pmCommands(root).exec;
+}
+function pmInstallCommand(root) {
+    return pmCommands(root).install;
 }

package/dist/src/command-line/migrate/run/worker.d.ts

@@ -2,6 +2,7 @@ import { type AgenticArg } from '../agentic/select';
 export interface RunSingleMigrationWorkerInput {
     root: string;
     runMigration: string;
+    runId?: string;
     /** The raw `--agentic` value; resolved here against the environment. */
     agentic: AgenticArg;
     validate: boolean | undefined;

package/dist/src/command-line/migrate/run/worker.js

@@ -3,16 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runSingleMigrationWorker = runSingleMigrationWorker;
 const fs_1 = require("fs");
 const path_1 = require("path");
-const configuration_1 = require("../../../config/configuration");
 const git_utils_1 = require("../../../utils/git-utils");
-const command_line_utils_1 = require("../../../utils/command-line-utils");
 const fileutils_1 = require("../../../utils/fileutils");
 const installation_directory_1 = require("../../../utils/installation-directory");
-const logger_1 = require("../../../utils/logger");
-const output_1 = require("../../../utils/output");
 const package_json_1 = require("../../../utils/package-json");
+const inception_1 = require("../agentic/inception");
 const print_dropped_agent_context_1 = require("../agentic/print-dropped-agent-context");
 const select_1 = require("../agentic/select");
+const types_1 = require("../agentic/types");
 const command_object_1 = require("../command-object");
 const execute_migration_1 = require("../execute-migration");
 const migrate_analytics_1 = require("../migrate-analytics");
@@ -20,10 +18,22 @@ const migrate_commits_1 = require("../migrate-commits");
 const migrate_output_1 = require("../migrate-output");
 const migration_shape_1 = require("../migration-shape");
 const safe_prompt_1 = require("../safe-prompt");
+const run_state_1 = require("./run-state");
+const run_id_1 = require("./run-id");
+const state_machine_1 = require("./state-machine");
+const state_lock_1 = require("./state-lock");
 const util_1 = require("./util");
+const text_1 = require("../text");
+const agent_output_1 = require("./agent-output");
 async function runSingleMigrationWorker(input) {
-    const { root, runMigration, commitPrefix, interactive, skipInstall, isVerbose, } = input;
-    const { migrations, source } = readMigrationsSource(root);
+    const { root, runMigration, runId, commitPrefix, interactive, skipInstall, isVerbose, } = input;
+    // The worker is a second CLI entry point: the run id reaches runDir() (where
+    // join resolves '..'), so validate it up front exactly as the orchestrator
+    // does before it trusts a run id.
+    if (runId !== undefined && !run_id_1.RUN_ID_SAFE.test(runId)) {
+        throw new Error(`Invalid run id '${runId}'.`);
+    }
+    const { migrations, source } = readMigrationsSource(root, runId);
     const migration = resolveMigration(migrations, runMigration, source);
     (0, migrate_analytics_1.reportMigrateSingleMigrationInvocation)({
         migrationType: (0, migration_shape_1.isPromptOnlyMigration)(migration)
@@ -31,7 +41,16 @@ async function runSingleMigrationWorker(input) {
             : (0, migration_shape_1.isHybridMigration)(migration)
                 ? 'hybrid'
                 : 'generator',
+        orchestrated: !!runId,
     });
+    if (runId) {
+        // A recorded run takes its commit config from run.json and is driven by
+        // the outer agent, so the standalone resolution below doesn't apply. That
+        // includes the default-branch confirmation: the run decided once, at init,
+        // whether to commit, and asking again would re-prompt on every step.
+        await runRecorded(root, runId, migration, skipInstall, isVerbose);
+        return;
+    }
     let agentic;
     try {
         agentic = await (0, select_1.resolveAgentic)({
@@ -46,7 +65,7 @@ async function runSingleMigrationWorker(input) {
     }
     const resolved = (0, migrate_commits_1.resolveCreateCommits)({
         createCommits: input.createCommits,
-        agenticKind: agentic.kind,
+        mode: agentic.kind,
         isGitRepo: (0, git_utils_1.isGitRepository)(root),
         commitPrefixIsCustom: commitPrefix !== command_object_1.DEFAULT_MIGRATION_COMMIT_PREFIX,
     });
@@ -54,27 +73,13 @@ async function runSingleMigrationWorker(input) {
         throw new Error(resolved.error);
     }
     if (resolved.warning) {
-        output_1.output.warn({ title: resolved.warning });
+        (0, agent_output_1.warnToAgent)({ title: resolved.warning });
     }
     const createCommits = resolved.effective;
-    if (createCommits && (0, safe_prompt_1.canPrompt)(interactive)) {
-        const currentBranch = (0, git_utils_1.getGitCurrentBranch)(root);
-        // `getBaseRef` may carry an `origin/` prefix (set by the CI-workflow
-        // generator); compare against the local branch name.
-        const defaultBranch = (0, command_line_utils_1.getBaseRef)((0, configuration_1.readNxJson)(root)).replace(/^origin\//, '');
-        const proceed = await (0, migrate_commits_1.confirmCommitsOnDefaultBranch)({
-            currentBranch,
-            defaultBranch,
-        });
-        if (!proceed) {
-            output_1.output.log({
-                title: `Skipped running the migration to avoid committing to the default branch '${currentBranch}'.`,
-                bodyLines: [
-                    'Switch to a different branch and re-run, or re-run and confirm to proceed.',
-                ],
-            });
-            return;
-        }
+    if (createCommits &&
+        (0, safe_prompt_1.canPrompt)(interactive) &&
+        !(await (0, migrate_commits_1.confirmMigrationCommitsOnDefaultBranch)(root, 'running the migration'))) {
+        return;
     }
     await runStandalone(root, migration, {
         agentic,
@@ -89,7 +94,33 @@ async function runSingleMigrationWorker(input) {
         isVerbose,
     });
 }
-function readMigrationsSource(root) {
+function readMigrationsSource(root, runId) {
+    if (runId) {
+        const dir = (0, run_state_1.runDir)(root, runId);
+        // A missing run.json would surface a raw ENOENT from readRunState's
+        // readFileSync; report it the way the orchestrator does instead, down to
+        // carrying no remediation: starting a run is a separate, gated entry point,
+        // and `--run-migrations` would run the whole plan in process instead.
+        if (!(0, run_state_1.hasRunState)(dir)) {
+            throw new Error(`No migrate run '${runId}' was found under ${types_1.MIGRATE_RUNS_RELATIVE_DIR}.`);
+        }
+        // Version refusal (NewerRunStateFormatError) propagates.
+        const state = (0, run_state_1.readRunState)(dir);
+        const round = (0, state_machine_1.latestRound)(state);
+        if (!round) {
+            throw new Error(`The migrate run '${runId}' has no recorded plan, so there is no migration to run.`);
+        }
+        // Safe to join and to name in the error below only because the read
+        // refuses any planSnapshot that is not a bare `plan-<round>.json`.
+        const planPath = (0, path_1.join)(dir, round.planSnapshot);
+        if (!(0, fs_1.existsSync)(planPath)) {
+            throw new Error(`The plan snapshot '${round.planSnapshot}' for migrate run '${runId}' doesn't exist, can't run the migration.`);
+        }
+        return {
+            migrations: readPlanMigrations(planPath),
+            source: round.planSnapshot,
+        };
+    }
     const migrationsPath = (0, path_1.join)(root, 'migrations.json');
     if (!(0, fs_1.existsSync)(migrationsPath)) {
         throw new Error(`File 'migrations.json' doesn't exist, can't run the migration. Run \`${(0, util_1.pmExecPrefix)(root)} nx migrate\` to generate it first.`);
@@ -121,6 +152,32 @@ function resolveMigration(migrations, id, source) {
 }
 async function runStandalone(root, migration, opts) {
     const { agentic, createCommits, commitPrefix, skipInstall, isVerbose } = opts;
+    // Standalone never writes run state. Warn (don't block) when an orchestrated
+    // run is active so the user knows this execution won't be recorded into it.
+    // A newer-nx run dir must not hard-block this stateless path (the fail-closed
+    // refusal in run-state.ts targets run-starting callers); tolerate it and skip
+    // the warning. A failed scan can't block it either, but gets a warning of its
+    // own: an active run may exist that this execution silently won't record into.
+    let active;
+    try {
+        active = (0, run_state_1.findActiveRun)(root).active;
+    }
+    catch (e) {
+        if (!(e instanceof run_state_1.NewerRunStateFormatError)) {
+            (0, agent_output_1.warnToAgent)({
+                title: `Could not check for an active migrate run: ${e instanceof Error ? e.message : e}`,
+            });
+        }
+        active = null;
+    }
+    if (active) {
+        (0, agent_output_1.warnToAgent)({
+            title: `This migration won't be recorded into the active migrate run '${active.runId}'.`,
+            bodyLines: [
+                `Pass --run-id=${active.runId} to record it into that run instead.`,
+            ],
+        });
+    }
     if ((0, migration_shape_1.isPromptOnlyMigration)(migration)) {
         if (agentic.kind !== 'enabled') {
             // No agent to apply the prompt, so nothing runs: no checkpoint, no
@@ -266,8 +323,220 @@ async function runStandalone(root, migration, opts) {
         }, resolvedCollection);
     }
 }
-// The handoff and run-step machinery is `require`d here so this module pulls
-// it in only when agentic is enabled.
+async function runRecorded(root, runId, migration, skipInstall, isVerbose) {
+    const dir = (0, run_state_1.runDir)(root, runId);
+    // Version refusal (NewerRunStateFormatError) propagates.
+    let state = (0, run_state_1.readRunState)(dir);
+    // A recorded run never resolves the agentic flow (the outer agent drives
+    // it); prompts are emitted for that agent or printed for a user hand-running
+    // the dispensed command.
+    const agenticKind = (0, inception_1.isInsideAgent)()
+        ? 'inside-agent'
+        : 'disabled';
+    const migrationId = `${migration.package}:${migration.name}`;
+    // The plan was read from the latest round's snapshot, so only that round's
+    // step may match; a same-id step from an older round must not.
+    const latest = (0, state_machine_1.latestRound)(state);
+    const step = state.steps.find((s) => s.migrationId === migrationId && s.roundIndex === latest?.index);
+    if (!step) {
+        throw new Error(`The migrate run '${runId}' has no step for migration '${migrationId}'.`);
+    }
+    // Validated against the fresh disk state: a second worker racing the same
+    // dispensed step reads 'running' here and aborts before the engine runs.
+    state = transition(dir, {
+        type: 'start',
+        stepId: step.id,
+        pid: process.pid,
+        startedAt: (0, util_1.nowIso)(),
+    });
+    // A prior attempt's generator half already ran, so this attempt must not
+    // reapply it against a tree that already holds its changes: a hybrid
+    // re-emits only its prompt, and a plain generator step has nothing left to
+    // do but the install and commit its previous attempt failed on.
+    // Read from the state the start transition returned: a delayed invocation
+    // may have claimed a later attempt whose flag its entry snapshot predates.
+    const startedStep = state.steps.find((s) => s.id === step.id);
+    const generatorAlreadyCompleted = startedStep.generatorCompleted === true;
+    // The run records its own install policy because dispensed worker commands
+    // are re-invoked by the loop and never carry the user's flags; an explicit
+    // --skip-install on this invocation still applies on top of it.
+    const effectiveSkipInstall = state.skipInstall === true || skipInstall;
+    let outcome;
+    try {
+        if ((0, migration_shape_1.isPromptOnlyMigration)(migration) ||
+            (generatorAlreadyCompleted && (0, migration_shape_1.isHybridMigration)(migration))) {
+            emitOrPrintPrompt(root, migration, agenticKind);
+        }
+        else if (generatorAlreadyCompleted) {
+            state = await finishCompletedGenerator(dir, root, state, startedStep, migration, effectiveSkipInstall, runId);
+            outcome = buildOutcome([], [], 'The generator ran in an earlier attempt; this attempt completed its install and commit.', root);
+        }
+        else {
+            const installer = new execute_migration_1.ChangedDepInstaller(root, effectiveSkipInstall, `${(0, execute_migration_1.formatSingleMigrationRerunCommand)(migrationId)} --run-id=${runId}`);
+            // Read once; the run and the hybrid documentation resolution share it.
+            const resolvedCollection = (0, execute_migration_1.readMigrationCollection)(migration.package, root);
+            const { changes, nextSteps, agentContext, logs, madeChanges } = await (0, execute_migration_1.runNxOrAngularMigration)(root, migration, isVerbose, (0, migration_shape_1.isHybridMigration)(migration), resolvedCollection);
+            // Recorded before the commit is attempted: from here on the changes are
+            // in the tree, so a failed install or commit must leave a retry with
+            // only those left to do rather than running the generator again.
+            state = transition(dir, {
+                type: 'markGeneratorCompleted',
+                stepId: step.id,
+            });
+            if (!(0, migration_shape_1.isHybridMigration)(migration)) {
+                forwardDroppedAgentContext(migration, agentContext, agenticKind);
+            }
+            const install = () => recordingInstallFailure(dir, step.id, () => installer.installDepsIfChanged());
+            // Commits follow the run config, not CLI flags, and only when the
+            // generator changed something: a no-op step must not create a commit (nor
+            // a ledger entry) that absorbs prior pending diffs under its name.
+            if (state.createCommits && madeChanges) {
+                state = await commitStepChanges(dir, root, state, step, migration, install);
+            }
+            else {
+                await install();
+            }
+            if (installer.skippedInstall) {
+                (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
+            }
+            else if (installer.installed) {
+                (0, util_1.recordInstallLanded)(root, dir, step.id);
+            }
+            printNextSteps(migration, nextSteps);
+            if ((0, migration_shape_1.isHybridMigration)(migration)) {
+                emitOrPrintPrompt(root, migration, agenticKind, {
+                    logs,
+                    changes,
+                    agentContext,
+                }, resolvedCollection);
+            }
+            else {
+                outcome = buildOutcome(changes, nextSteps, migration.description, root);
+            }
+        }
+    }
+    catch (e) {
+        // The failed-step dispense surfaces this so the agent can decide
+        // retry-vs-skip; carry the error's first line, not a full stack.
+        transition(dir, {
+            type: 'fail',
+            stepId: step.id,
+            finishedAt: (0, util_1.nowIso)(),
+            outcome: { summary: (0, util_1.summarizeError)(e) },
+        });
+        throw e;
+    }
+    // A prompt half (prompt-only, or the prompt phase of a hybrid) is applied by
+    // a separate actor, so the step parks in awaiting-prompt-outcome and this
+    // process exits successfully.
+    if ((0, migration_shape_1.isPromptOnlyMigration)(migration) || (0, migration_shape_1.isHybridMigration)(migration)) {
+        transition(dir, {
+            type: 'awaitPromptOutcome',
+            stepId: step.id,
+            finishedAt: (0, util_1.nowIso)(),
+        });
+        return;
+    }
+    transition(dir, {
+        type: 'succeed',
+        stepId: step.id,
+        finishedAt: (0, util_1.nowIso)(),
+        ...(outcome ? { outcome } : {}),
+    });
+}
+// Applies a step event to the freshest on-disk state under the lock, writes it,
+// and returns it. Reading fresh is what makes a racing worker's 'start' see the
+// step already 'running' and abort. An illegal transition (e.g. a step that was
+// never dispensed) fails with the state machine's own reason.
+function transition(dir, event) {
+    return (0, state_lock_1.updateRunState)(dir, (fresh) => {
+        const result = (0, state_machine_1.applyStepEvent)(fresh, event);
+        if (result.kind === 'error') {
+            throw new Error(`Cannot record this migration into the run: ${result.reason}`);
+        }
+        return result.state;
+    });
+}
+// Records a dependency install failure on the step before letting it fail the
+// attempt. The 'failed' status says this attempt did not finish, not that the
+// workspace's dependencies are missing, and the two part ways as soon as the
+// agent skips the step or a later step's commit absorbs its diff: either one
+// completes the run with node_modules stale and nothing left to warn about.
+async function recordingInstallFailure(dir, stepId, install) {
+    try {
+        return await install();
+    }
+    catch (e) {
+        (0, state_lock_1.updateRunState)(dir, (fresh) => (0, state_machine_1.markInstallFailed)(fresh, stepId));
+        throw e;
+    }
+}
+// Finishes a step whose generator ran in an earlier attempt that then failed
+// on the install or the commit. The generator's changes are already in the
+// tree, so only those two are left, and the install compares against the
+// step's persisted baseline rather than against what that generator wrote.
+async function finishCompletedGenerator(dir, root, state, step, migration, skipInstall, runId) {
+    const migrationId = `${migration.package}:${migration.name}`;
+    const installDeps = () => recordingInstallFailure(dir, step.id, () => (0, util_1.installDepsChangedSinceDispense)(root, dir, step, skipInstall, `${(0, execute_migration_1.formatSingleMigrationRerunCommand)(migrationId)} --run-id=${runId}`));
+    if (!state.createCommits) {
+        await installDeps();
+        return state;
+    }
+    return commitStepChanges(dir, root, state, step, migration, installDeps);
+}
+// Installs what the step changed, commits it, and records the result in the
+// ledger, shared by a step's first attempt and by one that only has the commit
+// left to do. The absorbed step ids are computed before the commit so the
+// ledger entry and the commit body name the same ones.
+async function commitStepChanges(dir, root, state, step, migration, installDeps) {
+    const absorbedStepIds = (0, state_machine_1.uncoveredFailedStepIds)(state).filter((id) => id !== step.id);
+    let result;
+    try {
+        result = await (0, migrate_commits_1.commitMigrationIfRequested)(root, migration, true, state.commitPrefix, installDeps, (0, state_machine_1.stepsToPendingMigrations)(state, absorbedStepIds));
+    }
+    catch (commitError) {
+        // A post-migration install failure leaves the diff uncommitted; record the
+        // debt so only a landed entry can cover it.
+        appendCommit(dir, { kind: 'failed', stepIds: [step.id] });
+        throw commitError;
+    }
+    if (result.status === 'failed') {
+        (0, util_1.warnCommitFailed)(migration.name);
+    }
+    const entry = (0, state_machine_1.commitResultToLedgerEntry)(result, step.id, absorbedStepIds);
+    return entry ? appendCommit(dir, entry) : state;
+}
+// Appends a ledger entry to the freshest on-disk state under the lock. The git
+// commit itself already ran outside the lock; only this pure append is locked.
+function appendCommit(dir, entry) {
+    return (0, state_lock_1.updateRunState)(dir, (fresh) => ({
+        ...fresh,
+        commits: [...fresh.commits, entry],
+    }));
+}
+function buildOutcome(changes, nextSteps, description, root) {
+    const outcome = {};
+    if (changes.length > 0) {
+        outcome.fileChanges = changes.map((c) => c.path);
+    }
+    // Non-git repos have no HEAD; omit rather than record a placeholder.
+    const gitRefAfter = (0, git_utils_1.getLatestCommitSha)(root);
+    if (gitRefAfter) {
+        outcome.gitRefAfter = gitRefAfter;
+    }
+    if (nextSteps.length > 0) {
+        outcome.nextSteps = nextSteps;
+    }
+    if (description) {
+        outcome.summary = description;
+    }
+    return outcome;
+}
+// Only `run-step` is actually deferred by these requires, and it is the one
+// worth deferring: it pulls in the prompt builders, which nothing but an
+// enabled agentic flow needs. The other two are loaded either way, since the
+// `run/` barrel every caller comes through re-exports `orchestrator.ts`, which
+// imports both statically.
 async function prepareAgenticRun(root, migration, agentic, effectiveCreateCommits, commitPrefix) {
     const { applyAgenticHandoffGitignoreFallback } = require('../agentic/handoff-gitignore');
     const { packageJson: nxPackageJson } = (0, package_json_1.readModulePackageJson)('nx', (0, installation_directory_1.getNxRequirePaths)(root));
@@ -324,9 +593,9 @@ function forwardDroppedAgentContext(migration, agentContext, agenticKind) {
 function printNextSteps(migration, nextSteps) {
     if (nextSteps.length === 0)
         return;
-    output_1.output.log({
+    (0, agent_output_1.logToAgent)({
         title: `Next steps for ${migration.package}: ${migration.name}`,
-        bodyLines: nextSteps.map((line) => `- ${line}`),
+        bodyLines: nextSteps.map((line) => `- ${(0, text_1.singleLine)(line)}`),
     });
 }
 function emitOrPrintPrompt(root, migration, agenticKind, impl, resolvedCollection) {
@@ -353,18 +622,10 @@ function emitPromptForOuterAgent(migrationId, promptPath, documentationPath, imp
                 : {}),
         };
     }
-    // A raw `<` in a migration-authored string could forge the closing tag; the
-    // JSON unicode escape removes every one and keeps the payload valid JSON.
-    const json = JSON.stringify(payload, null, 2).replace(/</g, '\\u003c');
-    const block = [
-        `The following prompt-based migration was not applied automatically. Apply it to this workspace, then continue.`,
-        ``,
-        `<nx_migrate_prompt migration="${(0, print_dropped_agent_context_1.escapeXmlAttr)(migrationId)}">`,
-        json,
-        `</nx_migrate_prompt>`,
-    ].join('\n');
-    // Bare newline pair frames the block so adjacent stdout doesn't run into it.
-    process.stdout.write(`\n${block}\n\n`);
+    (0, agent_output_1.logToAgent)({
+        title: `The following prompt-based migration was not applied automatically. Apply it to this workspace, then continue.`,
+    });
+    (0, agent_output_1.emitPromptBlock)(migrationId, payload);
 }
 function printPromptForUser(root, migration, promptPath, documentationPath) {
     const bodyLines = [];
@@ -394,7 +655,7 @@ function printPromptForUser(root, migration, promptPath, documentationPath) {
         }
         bodyLines.push('', 'Review the instructions above and apply them manually.');
     }
-    output_1.output.log({
+    (0, agent_output_1.logToAgent)({
         title: `Prompt-based migration ${migration.package}: ${migration.name} must be applied manually`,
         bodyLines,
     });
@@ -413,7 +674,9 @@ function resolveDocumentationPath(root, migration, resolvedCollection) {
         // An unreadable collection is reported through the warning below.
     }
     if (!documentationPath) {
-        logger_1.logger.warn(`Could not resolve the "documentation" file "${migration.documentation}" declared for migration "${migration.package}: ${migration.name}". It will be skipped.`);
+        (0, agent_output_1.warnToAgent)({
+            title: `Could not resolve the "documentation" file "${migration.documentation}" declared for migration "${migration.package}: ${migration.name}". It will be skipped.`,
+        });
     }
     return documentationPath;
 }

package/dist/src/command-line/migrate/safe-prompt.d.ts

@@ -1,33 +1,21 @@
-import { prompt as enquirerPrompt } from 'enquirer';
+import { Choice } from '../../utils/prompt-helpers';
 /**
  * Whether `nx migrate` may show interactive prompts: requires a TTY on stdin,
  * not running in CI, and the user not having passed `--no-interactive`.
  */
 export declare function canPrompt(interactive: boolean | undefined): boolean;
 /**
- * Drop-in replacement for enquirer's `prompt()` that hardens cancel
- * handling for every interactive prompt under `nx migrate`.
- *
- * Why: enquirer's built-in cancel path (`Prompt.cancel` → `close` →
- * `keypress.js` `off` → `readline.pause`) races on `Interface.pause()`
- * when triggered more than once in quick succession (mashed Ctrl+C),
- * throwing `ERR_USE_AFTER_CLOSE` from an unhandled async chain that
- * `await prompt(...)` cannot catch.
- *
- * In raw mode, Ctrl+C does NOT generate a SIGINT signal (the kernel's
- * `ISIG` flag is cleared while enquirer's keypress listener is active);
- * instead the 0x03 byte flows through `combos.js` and dispatches the
- * `cancel` action. So a `process.on('SIGINT', ...)` handler is the wrong
- * mechanism here — it never fires.
- *
- * The right hook is enquirer's per-prompt `options.cancel` override. When
- * present, `Prompt.keypress` (lib/prompt.js:42) calls our handler INSTEAD
- * of `this.cancel`, so enquirer's broken cleanup never runs. Both Ctrl+C
- * (byte 0x03) and Esc map to the `cancel` action, so this single override
- * covers both paths.
- *
- * The handler emits a single-line notice via `output.warn` and exits with
- * POSIX status 130 (128 + SIGINT). Synchronous exit is correct here: the
- * user explicitly asked to abort, there's no recovery state to preserve.
+ * Yes/no question for `nx migrate`, aborting the run if the user cancels.
  */
-export declare function migratePrompt<T = any>(questions: Parameters<typeof enquirerPrompt>[0]): Promise<T>;
+export declare function migrateConfirm(options: {
+    message: string;
+    initial?: boolean;
+}): Promise<boolean>;
+/**
+ * Single-choice question for `nx migrate`, aborting the run if the user cancels.
+ */
+export declare function migrateChoice<T extends string>(options: {
+    message: string;
+    choices: Choice<T>[];
+    initial?: T;
+}): Promise<T>;