nx 23.2.0-beta.7 → 23.2.0-beta.9

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

@@ -9,7 +9,7 @@ exports.createFetcher = createFetcher;
 exports.generateMigrationsJsonAndUpdatePackageJson = generateMigrationsJsonAndUpdatePackageJson;
 exports.formatSkippedPromptsNextStep = formatSkippedPromptsNextStep;
 exports.executeMigrations = executeMigrations;
-exports.isSingleMigrationInvocation = isSingleMigrationInvocation;
+exports.isRunPhaseInvocation = isRunPhaseInvocation;
 exports.migrate = migrate;
 exports.readLocalNxVersion = readLocalNxVersion;
 exports.runMigration = runMigration;
@@ -31,7 +31,6 @@ const write_formatted_json_file_1 = require("../../utils/write-formatted-json-fi
 const shell_quoting_1 = require("../../utils/shell-quoting");
 const logger_1 = require("../../utils/logger");
 const git_utils_1 = require("../../utils/git-utils");
-const command_line_utils_1 = require("../../utils/command-line-utils");
 const package_json_1 = require("../../utils/package-json");
 const package_manager_1 = require("../../utils/package-manager");
 const errors_1 = require("../../utils/min-release-age/errors");
@@ -48,7 +47,7 @@ const configuration_1 = require("../../config/configuration");
 const child_process_2 = require("../../utils/child-process");
 const client_1 = require("../../daemon/client/client");
 const nx_cloud_utils_1 = require("../../utils/nx-cloud-utils");
-const format_changed_files_with_prettier_if_available_1 = require("../../generators/internal-utils/format-changed-files-with-prettier-if-available");
+const format_changed_files_1 = require("../../generators/internal-utils/format-changed-files");
 const provenance_1 = require("../../utils/provenance");
 const catalog_1 = require("../../utils/catalog");
 const migrate_analytics_1 = require("./migrate-analytics");
@@ -66,7 +65,9 @@ Object.defineProperty(exports, "filterDowngradedUpdates", { enumerable: true, ge
 const version_utils_1 = require("./version-utils");
 Object.defineProperty(exports, "normalizeVersion", { enumerable: true, get: function () { return version_utils_1.normalizeVersion; } });
 const execute_migration_1 = require("./execute-migration");
+const step_actions_1 = require("./step-actions");
 const sort_migrations_1 = require("./sort-migrations");
+const inception_1 = require("./agentic/inception");
 const version_skew_guard_1 = require("./version-skew-guard");
 const versions_1 = require("../../utils/versions");
 tslib_1.__exportStar(require("./execute-migration"), exports);
@@ -112,6 +113,8 @@ class Migrator {
         this.packageUpdates = {};
         this.collectedVersions = {};
         this.promptAnswers = {};
+        this.pendingPackageJsonUpdates = new Map();
+        this.appliedPackageJsonUpdates = new Set();
         if ((opts.include === 'required' || opts.include === 'optional') &&
             !opts.requiredPackages) {
             throw new Error(`Error: 'requiredPackages' is required when 'include' is '${opts.include}'.`);
@@ -139,6 +142,7 @@ class Migrator {
             version: targetVersion,
             addToPackageJson: false,
         });
+        await this.applyPendingPackageJsonUpdates();
         this.applyIncludeFilter();
         const { migrations, promptContents } = await this.createMigrateJson();
         return {
@@ -184,29 +188,66 @@ class Migrator {
         for (const packageToCheck of packagesToCheck) {
             const filteredUpdates = {};
             for (const [packageUpdateKey, packageUpdate] of Object.entries(packageToCheck.updates)) {
-                if (this.areRequirementsMet(packageUpdate.requires) &&
-                    !this.areIncompatiblePackagesPresent(packageUpdate.incompatibleWith) &&
-                    (!this.interactive ||
-                        (await this.runPackageJsonUpdatesConfirmationPrompt(packageUpdate, packageUpdateKey, packageToCheck.package)))) {
-                    const updateEntries = Object.entries(packageUpdate.packages);
-                    // Validate all up front so invalid metadata fails fast, before any
-                    // resolution does I/O.
-                    for (const [name, update] of updateEntries) {
-                        this.validatePackageUpdateVersion(packageToCheck.package, name, update);
-                    }
-                    // Resolve serially: resolution can prompt (pnpm strict cooldown) and
-                    // append to minimumReleaseAgeExclude, so a serial loop avoids
-                    // overlapping prompts and keeps packageUpdates ordering stable.
-                    for (const [name, update] of updateEntries) {
-                        const resolvedUpdate = {
-                            ...update,
-                            version: await this.resolveVersionForCascade(name, update.version),
-                        };
-                        filteredUpdates[name] = resolvedUpdate;
-                        this.packageUpdates[name] = resolvedUpdate;
-                    }
+                Object.assign(filteredUpdates, await this.applyPackageJsonUpdate(packageToCheck.package, packageUpdateKey, packageUpdate));
+            }
+            await Promise.all(Object.entries(filteredUpdates).map(([name, update]) => this.buildPackageJsonUpdates(name, update)));
+        }
+    }
+    async applyPackageJsonUpdate(sourcePackage, packageUpdateKey, packageUpdate) {
+        const appliedKey = JSON.stringify([sourcePackage, packageUpdateKey]);
+        if (this.appliedPackageJsonUpdates.has(appliedKey)) {
+            this.pendingPackageJsonUpdates.delete(appliedKey);
+            return {};
+        }
+        if (!this.areRequirementsMet(packageUpdate.requires) ||
+            this.areIncompatiblePackagesPresent(packageUpdate.incompatibleWith)) {
+            this.pendingPackageJsonUpdates.set(appliedKey, {
+                package: sourcePackage,
+                key: packageUpdateKey,
+                update: packageUpdate,
+            });
+            return {};
+        }
+        this.pendingPackageJsonUpdates.delete(appliedKey);
+        if (this.interactive &&
+            !(await this.runPackageJsonUpdatesConfirmationPrompt(packageUpdate, packageUpdateKey, sourcePackage))) {
+            return {};
+        }
+        this.appliedPackageJsonUpdates.add(appliedKey);
+        const updateEntries = Object.entries(packageUpdate.packages);
+        // Validate all up front so invalid metadata fails fast, before any
+        // resolution does I/O.
+        for (const [name, update] of updateEntries) {
+            this.validatePackageUpdateVersion(sourcePackage, name, update);
+        }
+        const filteredUpdates = {};
+        // Resolve serially: resolution can prompt (pnpm strict cooldown) and append
+        // to minimumReleaseAgeExclude, so a serial loop avoids overlapping prompts
+        // and keeps packageUpdates ordering stable.
+        for (const [name, update] of updateEntries) {
+            const resolvedUpdate = {
+                ...update,
+                version: await this.resolveVersionForCascade(name, update.version),
+            };
+            this.addPackageUpdate(name, resolvedUpdate);
+            filteredUpdates[name] = this.packageUpdates[name];
+        }
+        return filteredUpdates;
+    }
+    async applyPendingPackageJsonUpdates() {
+        while (this.pendingPackageJsonUpdates.size) {
+            let applied = false;
+            const filteredUpdates = {};
+            for (const pending of [...this.pendingPackageJsonUpdates.values()]) {
+                const updates = await this.applyPackageJsonUpdate(pending.package, pending.key, pending.update);
+                if (Object.keys(updates).length) {
+                    applied = true;
+                    Object.assign(filteredUpdates, updates);
                 }
             }
+            if (!applied) {
+                return;
+            }
             await Promise.all(Object.entries(filteredUpdates).map(([name, update]) => this.buildPackageJsonUpdates(name, update)));
         }
     }
@@ -410,7 +451,7 @@ class Migrator {
     }
     addPackageUpdate(name, packageUpdate) {
         if (!this.packageUpdates[name] ||
-            this.gt(packageUpdate.version, this.packageUpdates[name].version)) {
+            !this.lt(packageUpdate.version, this.packageUpdates[name].version)) {
             this.packageUpdates[name] = packageUpdate;
         }
     }
@@ -476,17 +517,14 @@ class Migrator {
             // a same prompt was already answered, skip
             return Promise.resolve(false);
         }
-        const promptConfig = {
-            name: 'shouldApply',
-            type: 'confirm',
-            message: packageUpdate['x-prompt'],
+        // No footer slot, so the docs link is appended to the message.
+        const detailsLink = packageName.startsWith('@nx/')
+            ? pc.dim(`\n  View migration details at https://nx.dev/nx-api/${packageName.replace('@nx/', '')}#${packageUpdateKey.replace(/[-\.]/g, '')}packageupdates`)
+            : '';
+        return await (0, safe_prompt_1.migrateConfirm)({
+            message: `${packageUpdate['x-prompt']}${detailsLink}`,
             initial: true,
-        };
-        if (packageName.startsWith('@nx/')) {
-            // @ts-expect-error -- enquirer types aren't correct, footer does exist
-            promptConfig.footer = () => pc.dim(`  View migration details at https://nx.dev/nx-api/${packageName.replace('@nx/', '')}#${packageUpdateKey.replace(/[-\.]/g, '')}packageupdates`);
-        }
-        return await (0, safe_prompt_1.migratePrompt)([promptConfig]).then(({ shouldApply }) => {
+        }).then((shouldApply) => {
             this.promptAnswers[promptKey] = shouldApply;
             if (!shouldApply &&
                 (!this.minVersionWithSkippedUpdates ||
@@ -587,8 +625,8 @@ async function resolveInclude(include, context, configuredInclude) {
     }
     const choices = [
         {
-            name: 'required',
-            message: 'Required only (the target package and the packages it ships with)',
+            value: 'required',
+            label: 'Required only (the target package and the packages it ships with)',
         },
     ];
     // `--interactive` keeps the legacy x-prompt flow, which the `optional` value
@@ -597,8 +635,8 @@ async function resolveInclude(include, context, configuredInclude) {
         !context.hasExcludeAppliedMigrations &&
         context.interactive !== true) {
         choices.push({
-            name: 'optional',
-            message: 'Optional only (the dependency updates those packages recommend)',
+            value: 'optional',
+            label: 'Optional only (the dependency updates those packages recommend)',
         });
     }
     if (!(0, safe_prompt_1.canPrompt)(context.interactive)) {
@@ -606,12 +644,10 @@ async function resolveInclude(include, context, configuredInclude) {
         return 'all';
     }
     choices.push({
-        name: 'all',
-        message: 'All (required and optional)',
+        value: 'all',
+        label: 'All (required and optional)',
     });
-    const { include: selected } = await (0, safe_prompt_1.migratePrompt)({
-        type: 'select',
-        name: 'include',
+    const selected = await (0, safe_prompt_1.migrateChoice)({
         message: 'Which packages would you like to migrate?',
         choices,
     });
@@ -671,10 +707,25 @@ async function parseTargetPackageAndVersion(args) {
     return { targetPackage: args, targetVersion: 'latest' };
 }
 async function parseMigrationsOptions(options, fetch) {
+    // A run recorded or reconciled via `--run-id` is driven by the outer agent;
+    // spawning another agent from it would double-drive the run. Only the
+    // explicit "on" values conflict; the nx.json default is ignored for
+    // `--run-id` invocations instead.
+    if (options.runId !== undefined &&
+        options.agentic !== undefined &&
+        options.agentic !== false) {
+        throw new Error(`Error: '--agentic' cannot be combined with '--run-id'.`);
+    }
     if (options.runMigration !== undefined) {
         if (options.runMigration === '') {
             throw new Error(`Error: '--run-migration' requires a migration id, e.g. '--run-migration=@nx/js:my-migration'.`);
         }
+        if (options.runId === '') {
+            throw new Error(`Error: '--run-id' requires the id of the migrate run to record into.`);
+        }
+        if (options.stepAction !== undefined) {
+            throw new Error(`Error: '--step-action' cannot be combined with '--run-migration'. It applies to an orchestrated reconcile ('--run-id' without '--run-migration').`);
+        }
         if (options.runMigrations !== undefined) {
             throw new Error(`Error: '--run-migration' (run a single migration) cannot be combined with '--run-migrations' (run the whole migrations file).`);
         }
@@ -692,11 +743,39 @@ async function parseMigrationsOptions(options, fetch) {
         return {
             type: 'runSingleMigration',
             runMigration: options.runMigration,
+            runId: options.runId,
             agentic: options.agentic,
             validate: options.validate,
             interactive: options.interactive,
         };
     }
+    if (options.runId !== undefined) {
+        // Empty '--run-id' is an error on every path.
+        if (options.runId === '') {
+            throw new Error(`Error: '--run-id' requires the id of the migrate run to record into.`);
+        }
+        if (options.runMigrations !== undefined) {
+            throw new Error(`Error: '--run-id' (reconcile an orchestrated run) cannot be combined with '--run-migrations' (run the whole migrations file).`);
+        }
+        // A bare '--run-id' reconciles the run it names. Ungated, unlike init:
+        // the id has to name a run directory that exists, and only a gated init
+        // ever creates one.
+        // yargs' choices already reject bad CLI values; this guards programmatic
+        // callers, where silently dropping the action would reconcile without it.
+        if (options.stepAction !== undefined && !(0, step_actions_1.isStepAction)(options.stepAction)) {
+            throw new Error(`Error: '--step-action' must be one of ${step_actions_1.STEP_ACTIONS.join(', ')}.`);
+        }
+        return {
+            type: 'orchestratorReconcile',
+            runId: options.runId,
+            ...(options.stepAction !== undefined
+                ? { stepAction: options.stepAction }
+                : {}),
+        };
+    }
+    if (options.stepAction !== undefined) {
+        throw new Error(`Error: '--step-action' requires '--run-id'.`);
+    }
     if (options.runMigrations === '') {
         options.runMigrations = 'migrations.json';
     }
@@ -1121,8 +1200,30 @@ async function getPackageMigrationsUsingRegistry(packageName, packageVersion) {
     // try to obtain the migrations from the registry directly
     return await downloadPackageMigrationsFromRegistry(packageName, packageVersion, migrationsConfig);
 }
+// Matched exactly: a hostname that merely contains one of these is a different
+// registry. registry.yarnpkg.com is npmjs' CNAME, so it serves the same
+// metadata; the two loopback literals are the spellings of a local registry
+// that the substring below cannot reach, since neither contains "localhost".
+const FULL_METADATA_REGISTRIES = [
+    'registry.npmjs.org',
+    'registry.yarnpkg.com',
+    '127.0.0.1',
+    '[::1]',
+];
+// Matched as substrings, since neither names a single host: a local registry
+// can sit on a subdomain of localhost, and an Artifactory instance is
+// identified only by that word appearing somewhere in its hostname.
+const FULL_METADATA_REGISTRY_MARKERS = [
+    'localhost',
+    'artifactory',
+];
 async function getPackageMigrationsConfigFromRegistry(packageName, packageVersion) {
-    const result = await (0, package_manager_1.packageRegistryView)(packageName, packageVersion, 'nx-migrations ng-update dist --json');
+    const result = await (0, package_manager_1.packageRegistryView)(packageName, packageVersion, [
+        'nx-migrations',
+        'ng-update',
+        'dist',
+        '--json',
+    ]);
     if (!result) {
         return null;
     }
@@ -1130,9 +1231,10 @@ async function getPackageMigrationsConfigFromRegistry(packageName, packageVersio
     if (!json['nx-migrations'] && !json['ng-update']) {
         const registry = new node_url_1.URL('dist' in json ? json.dist.tarball : json.tarball)
             .hostname;
-        // Registries other than npmjs and the local registry may not support full metadata via npm view
-        // so throw error so that fetcher falls back to getting config via install
-        if (!['registry.npmjs.org', 'localhost', 'artifactory'].some((v) => registry.includes(v))) {
+        // Other registries may not support full metadata via npm view; throw to
+        // trigger the install fallback.
+        if (!FULL_METADATA_REGISTRIES.includes(registry) &&
+            !FULL_METADATA_REGISTRY_MARKERS.some((v) => registry.includes(v))) {
             throw new Error(`Getting migration config from registry is not supported from ${registry}`);
         }
     }
@@ -1325,7 +1427,7 @@ async function formatCatalogDefinitionFiles(manager, root) {
             content: (0, fs_1.readFileSync)(absolutePath, 'utf-8'),
         };
     });
-    const results = await (0, format_changed_files_with_prettier_if_available_1.formatFilesWithPrettierIfAvailable)(catalogDefinitionFiles.map(({ path, content }) => ({ path, content })), root, { silent: true });
+    const results = await (0, format_changed_files_1.formatFileContents)(catalogDefinitionFiles.map(({ path, content }) => ({ path, content })), root, { silent: true });
     for (const { path, absolutePath, content } of catalogDefinitionFiles) {
         (0, fs_1.writeFileSync)(absolutePath, results.has(path) ? results.get(path) : content, { encoding: 'utf-8' });
     }
@@ -2024,6 +2126,46 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
     }
     const migrationsJson = (0, fileutils_1.readJsonFile)((0, path_1.join)(root, opts.runMigrations));
     const migrations = migrationsJson.migrations;
+    // An outer agent drives the loop, so hand off to the orchestrator instead of
+    // the classic loop: init either starts a fresh run or resumes an already-
+    // active one. `--run-id` reconciles are dispatched separately and never
+    // reach here.
+    if (process.env.NX_MIGRATE_ORCHESTRATOR === 'true' && (0, inception_1.isInsideAgent)()) {
+        // Orchestrated runs are agent-driven, so commits default on exactly as they
+        // do under `--agentic=enabled`; the orchestrator replaces `resolveAgentic`.
+        const { effective: effectiveCreateCommits, warning: createCommitsWarning, error: createCommitsError, } = (0, migrate_commits_1.resolveCreateCommits)({
+            createCommits: shouldCreateCommits,
+            mode: 'orchestrated',
+            isGitRepo: (0, git_utils_1.isGitRepository)(root),
+            commitPrefixIsCustom: commitPrefix !== command_object_1.DEFAULT_MIGRATION_COMMIT_PREFIX,
+        });
+        if (createCommitsError) {
+            throw new Error(createCommitsError);
+        }
+        if (createCommitsWarning) {
+            output_1.output.warn({ title: createCommitsWarning });
+        }
+        // The run commits on the user's behalf across many invocations, so the
+        // default-branch confirmation belongs here, once, before any of them.
+        if (effectiveCreateCommits &&
+            (0, safe_prompt_1.canPrompt)(opts.interactive) &&
+            !(await (0, migrate_commits_1.confirmMigrationCommitsOnDefaultBranch)(root, 'running migrations'))) {
+            return;
+        }
+        const { packageJson: orchestratorNxPackageJson } = (0, package_json_1.readModulePackageJson)('nx', (0, installation_directory_1.getNxRequirePaths)(root));
+        const { runOrchestratorInit } = require('./run');
+        return await runOrchestratorInit({
+            root,
+            migrationsJson,
+            createCommits: effectiveCreateCommits,
+            commitPrefix,
+            // The flag only, never NX_MIGRATE_SKIP_INSTALL: the wrapper's local
+            // re-exec sets that env var for its own hop, and it says nothing about
+            // what the user asked for.
+            skipInstall: shouldSkipInstall,
+            installedNxVersion: orchestratorNxPackageJson.version,
+        });
+    }
     (0, migrate_analytics_1.reportMigrateRunStart)({
         createCommits: shouldCreateCommits ?? false,
         migrationCount: migrations.length,
@@ -2043,7 +2185,7 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
     }
     const { effective: effectiveCreateCommits, agenticHasDiffContext, warning: createCommitsWarning, error: createCommitsError, } = (0, migrate_commits_1.resolveCreateCommits)({
         createCommits: shouldCreateCommits,
-        agenticKind: agentic.kind,
+        mode: agentic.kind,
         isGitRepo: (0, git_utils_1.isGitRepository)(root),
         commitPrefixIsCustom: commitPrefix !== command_object_1.DEFAULT_MIGRATION_COMMIT_PREFIX,
     });
@@ -2053,24 +2195,10 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
     if (createCommitsWarning) {
         output_1.output.warn({ title: createCommitsWarning });
     }
-    if (effectiveCreateCommits && (0, safe_prompt_1.canPrompt)(opts.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 migrations 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 (effectiveCreateCommits &&
+        (0, safe_prompt_1.canPrompt)(opts.interactive) &&
+        !(await (0, migrate_commits_1.confirmMigrationCommitsOnDefaultBranch)(root, 'running migrations'))) {
+        return;
     }
     const shouldRunValidation = resolveShouldRunValidation({
         validate: opts.validate,
@@ -2189,17 +2317,21 @@ async function runMigrations(root, opts, args, isVerbose, shouldCreateCommits, c
         appliedCount,
     });
 }
-function isSingleMigrationInvocation(args) {
-    return args.runMigration !== undefined;
+function isRunPhaseInvocation(args) {
+    return (args.runMigration !== undefined ||
+        args.runId !== undefined ||
+        args.stepAction !== undefined);
 }
 async function migrate(root, args, rawArgs) {
     await client_1.daemonClient.stop();
     return (0, handle_errors_1.handleErrors)(process.env.NX_VERBOSE_LOGGING === 'true', async () => {
         const mergedArgs = (0, migrate_config_1.applyNxJsonMigrateDefaults)(args, (0, configuration_1.readNxJson)().migrate);
-        // A single-migration invocation resolves its commit config downstream via
-        // resolveCreateCommits, so this assert must not fire for it.
-        const singleMigration = isSingleMigrationInvocation(mergedArgs);
-        if (!singleMigration) {
+        // Run-phase invocations resolve their commit config downstream (run.json
+        // for recorded runs, resolveCreateCommits for standalone), so this assert
+        // must not fire for them; otherwise an nx.json prefix the whole-file run
+        // legitimately uses would wedge every dispensed command.
+        const runPhase = isRunPhaseInvocation(mergedArgs);
+        if (!runPhase) {
             (0, migrate_config_1.assertCommitPrefixHasCommits)(mergedArgs);
         }
         // One fetcher (registry-first, install fallback) shared by the `--include`
@@ -2207,8 +2339,8 @@ async function migrate(root, args, rawArgs) {
         // at most once per package/version.
         const fetch = createFetcher((0, package_manager_1.getPackageManagerCommand)());
         // `--run-migrations` without a value parses as '', so only undefined (and
-        // no single-migration flag) means the generate phase.
-        const isGenerateInvocation = mergedArgs['runMigrations'] === undefined && !singleMigration;
+        // no run-phase flag) means the generate phase.
+        const isGenerateInvocation = mergedArgs['runMigrations'] === undefined && !runPhase;
         let opts;
         try {
             opts = await parseMigrationsOptions(mergedArgs, fetch);
@@ -2217,7 +2349,7 @@ async function migrate(root, args, rawArgs) {
             if (isGenerateInvocation) {
                 (0, migrate_analytics_1.reportMigrateGenerateError)('resolve_version', e);
             }
-            else if (singleMigration) {
+            else if (runPhase) {
                 (0, migrate_analytics_1.reportMigrateRunError)({ code: 'other', error: e });
             }
             throw e;
@@ -2240,6 +2372,8 @@ async function migrate(root, args, rawArgs) {
                     (0, migrate_analytics_1.reportMigrateRunError)({ code: 'other', error: e });
                     throw e;
                 }
+            case 'orchestratorReconcile':
+                return await runOrchestratorReconcileFromCli(root, opts, rawArgs);
             case 'runMigrations':
                 try {
                     return await runMigrations(root, opts, rawArgs, mergedArgs['verbose'], mergedArgs['createCommits'], mergedArgs['commitPrefix'] ?? command_object_1.DEFAULT_MIGRATION_COMMIT_PREFIX, mergedArgs['skipInstall']);
@@ -2425,11 +2559,37 @@ function readNxVersionFromNodeModules(searchPaths) {
     }
     return undefined;
 }
+// Mirrors the local-nx hand-off of the other run paths so a reconcile always
+// executes against the workspace-local nx that owns the run state, never the
+// temp installation. Reconciles only read state and commit, so no install.
+async function runOrchestratorReconcileFromCli(root, opts, args) {
+    if (!__dirname.startsWith(workspace_root_1.workspaceRoot)) {
+        // The workspace-local nx we are about to hand off to must be new enough to
+        // understand the new flags we forward to it.
+        (0, version_skew_guard_1.assertWorkspaceNxSupportsNewMigrateFlags)({
+            argv: args,
+            readLocalNxVersion: () => readLocalNxVersion(root),
+        });
+        return handOffToLocalNx(args);
+    }
+    const { runOrchestratorReconcile } = require('./run');
+    return runOrchestratorReconcile({
+        root,
+        runId: opts.runId,
+        stepAction: opts.stepAction,
+    });
+}
 // Keeps `--run-migration` behaving like `--run-migrations` when invoked from
 // a temp `nx@latest` install: same pre-install, same local-nx hand-off.
 async function runSingleMigrationFromCli(root, opts, args, mergedArgs) {
     const shouldSkipInstall = mergedArgs['skipInstall'] ?? false;
-    if (!shouldSkipInstall && !process.env.NX_MIGRATE_SKIP_INSTALL) {
+    // A recorded execution skips the pre-install: the run carries its own
+    // install policy and its worker installs what the migration changed, so
+    // paying for a full install ahead of every dispensed command would be
+    // redundant.
+    if (opts.runId === undefined &&
+        !shouldSkipInstall &&
+        !process.env.NX_MIGRATE_SKIP_INSTALL) {
         await (0, execute_migration_1.runInstall)(undefined, 'pre-migration', (0, execute_migration_1.formatSingleMigrationRerunCommand)(opts.runMigration));
     }
     if (!__dirname.startsWith(workspace_root_1.workspaceRoot)) {
@@ -2446,13 +2606,15 @@ async function runSingleMigrationFromCli(root, opts, args, mergedArgs) {
         return handOffToLocalNx(args);
     }
     // The worker resolves the agentic flow, the effective commit config, and
-    // the default-branch confirmation itself; hand it the raw flags.
+    // the default-branch confirmation itself; hand it the raw flags. Recorded
+    // runs (--run-id) take their commit config from run.json instead.
     // Lazy-load run/ so plain migrate and repair runs don't pay for the agentic
     // selection chain its barrel pulls in eagerly.
     const { runSingleMigrationWorker } = require('./run');
     await runSingleMigrationWorker({
         root,
         runMigration: opts.runMigration,
+        runId: opts.runId,
         agentic: opts.agentic,
         validate: opts.validate,
         createCommits: mergedArgs['createCommits'],
@@ -2479,7 +2641,8 @@ async function runMigration() {
         const runLocalMigrate = () => runOrReturnExitCode(() => (0, child_process_2.runNxArgvSync)(['_migrate', ...forwardedArgv], {
             stdio: ['inherit', 'inherit', 'inherit'],
         }));
-        if (process.env.NX_USE_LOCAL !== 'true' &&
+        if (!(0, version_skew_guard_1.targetsExistingRun)(process.argv.slice(3)) &&
+            process.env.NX_USE_LOCAL !== 'true' &&
             process.env.NX_MIGRATE_USE_LOCAL === undefined) {
             // The version spec mirrors nxCliPath's; keep the two in sync.
             const cliVersionSpec = process.env.NX_MIGRATE_CLI_VERSION || 'latest';

package/dist/src/command-line/migrate/multi-major.js

@@ -63,32 +63,29 @@ async function promptMultiMajorMigration(args) {
     let recommendedMarked = false;
     if (args.latestInCurrent) {
         choices.push({
-            name: args.latestInCurrent,
-            message: `Migrate to ${args.targetPackage}@${args.latestInCurrent} (latest in current major) [recommended]`,
+            value: args.latestInCurrent,
+            label: `Migrate to ${args.targetPackage}@${args.latestInCurrent} (latest in current major) [recommended]`,
         });
         recommendedMarked = true;
     }
     if (args.latestInNext) {
         choices.push({
-            name: args.latestInNext,
-            message: `Migrate to ${args.targetPackage}@${args.latestInNext} (next major)${recommendedMarked ? '' : ' [recommended]'}`,
+            value: args.latestInNext,
+            label: `Migrate to ${args.targetPackage}@${args.latestInNext} (next major)${recommendedMarked ? '' : ' [recommended]'}`,
         });
     }
     choices.push({
-        name: args.target,
-        message: `Migrate directly to ${args.targetPackage}@${args.target}`,
+        value: args.target,
+        label: `Migrate directly to ${args.targetPackage}@${args.target}`,
     });
     output_1.output.log({
         title: multiMajorHeader(args.targetPackage, args.installed, args.target),
         bodyLines: multiMajorBodyLines,
     });
-    const { chosen } = await (0, safe_prompt_1.migratePrompt)({
-        type: 'select',
-        name: 'chosen',
+    return (0, safe_prompt_1.migrateChoice)({
         message: 'How would you like to proceed?',
         choices,
     });
-    return chosen;
 }
 // Flag wins over env var; only the two literal values are honoured.
 function resolveMultiMajorMode(options) {

package/dist/src/command-line/migrate/resolve-package-version.js

@@ -198,14 +198,10 @@ async function handleViolation(packageName, error, policy) {
     const blockedLine = `  ${packageName}@${resolved.version} (published ${formatPublishAge(resolved.publishedAt)})`;
     // pnpm prompts once for the whole run; remember an approval for later picks.
     if (!strictApprovalGranted) {
-        const { approved } = await (0, safe_prompt_1.migratePrompt)([
-            {
-                name: 'approved',
-                type: 'confirm',
-                initial: false,
-                message: `The following version does not meet the ${policy.sourceDescription} constraint:\n${blockedLine}\nInstall anyway and add it to minimumReleaseAgeExclude in pnpm-workspace.yaml?`,
-            },
-        ]);
+        const approved = await (0, safe_prompt_1.migrateConfirm)({
+            initial: false,
+            message: `The following version does not meet the ${policy.sourceDescription} constraint:\n${blockedLine}\nInstall anyway and add it to minimumReleaseAgeExclude in pnpm-workspace.yaml?`,
+        });
         if (!approved) {
             // Deny must surface as a violation: migrate.ts only rethrows
             // MinReleaseAgeViolationError, so a plain Error would silently fall back

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

@@ -0,0 +1,20 @@
+/**
+ * Lines are kept unjoined all the way here on purpose. Joining them and
+ * splitting them back turns an injected break into its own entry before this
+ * module sees it, indistinguishable from a line the caller meant to write, and
+ * nothing downstream can undo that.
+ */
+export interface AgentMessage {
+    title: string;
+    bodyLines?: string[];
+}
+/**
+ * The safe form of a set of lines. Exported so a caller that needs the same
+ * text twice, once for a human and once inside a block payload, derives both
+ * from one array instead of sanitizing one copy and not the other.
+ */
+export declare function safeLines(lines: readonly string[]): string[];
+export declare function logToAgent(message: AgentMessage): void;
+export declare function warnToAgent(message: AgentMessage): void;
+export declare function emitStepBlock(runId: string, stepId: string, action: string, payload: object): void;
+export declare function emitPromptBlock(migrationId: string, payload: object): void;