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

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");
@@ -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);
@@ -476,17 +477,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 +585,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 +595,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 +604,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 +667,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 +703,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 +1160,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 +1191,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}`);
         }
     }
@@ -2024,6 +2086,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 +2145,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 +2155,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 +2277,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 +2299,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 +2309,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 +2332,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 +2519,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 +2566,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 +2601,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;

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

@@ -0,0 +1,65 @@
+"use strict";
+// Internal to run/: deliberately not re-exported from ./index.
+//
+// The single writer for everything an orchestrated run puts on stdout. Human
+// lines and the `<nx_migrate_*>` blocks the driving agent parses share that one
+// stream, so a value carrying its own line break could open a forged block.
+//
+// Two boundaries: a thrown error leaves through handleErrors, which prints it
+// outside this guarantee; and migration code is not contained at all (nx
+// `require`s and runs it in process), so the guarantee is that data cannot
+// corrupt the framing, nothing more.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeLines = safeLines;
+exports.logToAgent = logToAgent;
+exports.warnToAgent = warnToAgent;
+exports.emitStepBlock = emitStepBlock;
+exports.emitPromptBlock = emitPromptBlock;
+const output_1 = require("../../../utils/output");
+const print_dropped_agent_context_1 = require("../agentic/print-dropped-agent-context");
+const text_1 = require("../text");
+/**
+ * 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.
+ */
+function safeLines(lines) {
+    return lines.map(text_1.singleLine);
+}
+function safe(message) {
+    return {
+        title: (0, text_1.singleLine)(message.title),
+        bodyLines: safeLines(message.bodyLines ?? []),
+    };
+}
+function logToAgent(message) {
+    output_1.output.log(safe(message));
+}
+function warnToAgent(message) {
+    output_1.output.warn(safe(message));
+}
+/**
+ * Serializes a block payload. `<` becomes its JSON unicode escape so a raw one
+ * in a value cannot forge the closing tag, and the result stays valid JSON for
+ * the agent to parse.
+ */
+function blockPayload(payload) {
+    return JSON.stringify(payload, null, 2).replace(/</g, '\\u003c');
+}
+// A bare newline pair frames the block so adjacent stdout cannot run into it.
+function writeBlock(tag, attrs, json) {
+    const attrText = attrs
+        .map(([name, value]) => ` ${name}="${(0, print_dropped_agent_context_1.escapeXmlAttr)((0, text_1.singleLine)(value))}"`)
+        .join('');
+    process.stdout.write(`\n<${tag}${attrText}>\n${json}\n</${tag}>\n\n`);
+}
+function emitStepBlock(runId, stepId, action, payload) {
+    writeBlock('nx_migrate_step', [
+        ['run-id', runId],
+        ['step', stepId],
+        ['action', action],
+    ], blockPayload(payload));
+}
+function emitPromptBlock(migrationId, payload) {
+    writeBlock('nx_migrate_prompt', [['migration', migrationId]], blockPayload(payload));
+}

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

@@ -1,2 +1,9 @@
+export { CURRENT_RUN_STATE_FORMAT_VERSION, NewerRunStateFormatError, migrateRunsDir, runDir, readRunState, writeRunState, findActiveRun, createRun, } from './run-state';
+export type { MigrateRunStatus, MigrateRunRound, MigrateStepStatus, PromptOutcomeStatus, MigrateStepOutcome, MigrateStepPromptOutcome, MigrateStep, MigrateCommitKind, MigrateCommitLedgerEntry, MigrateRunAnalytics, MigrateRunState, } from './run-state';
+export { applyStepEvent, hasPendingCommitDebt } from './state-machine';
+export type { StepAction, StepEvent, ApplyStepEventResult, } from './state-machine';
+export { createRunId, computePlanHash } from './run-id';
 export { runSingleMigrationWorker } from './worker';
 export type { RunSingleMigrationWorkerInput } from './worker';
+export { runOrchestratorInit, runOrchestratorReconcile } from './orchestrator';
+export type { RunOrchestratorInitInput, RunOrchestratorReconcileInput, } from './orchestrator';

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

@@ -1,5 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runSingleMigrationWorker = void 0;
+exports.runOrchestratorReconcile = exports.runOrchestratorInit = exports.runSingleMigrationWorker = exports.computePlanHash = exports.createRunId = exports.hasPendingCommitDebt = exports.applyStepEvent = exports.createRun = exports.findActiveRun = exports.writeRunState = exports.readRunState = exports.runDir = exports.migrateRunsDir = exports.NewerRunStateFormatError = exports.CURRENT_RUN_STATE_FORMAT_VERSION = void 0;
+var run_state_1 = require("./run-state");
+Object.defineProperty(exports, "CURRENT_RUN_STATE_FORMAT_VERSION", { enumerable: true, get: function () { return run_state_1.CURRENT_RUN_STATE_FORMAT_VERSION; } });
+Object.defineProperty(exports, "NewerRunStateFormatError", { enumerable: true, get: function () { return run_state_1.NewerRunStateFormatError; } });
+Object.defineProperty(exports, "migrateRunsDir", { enumerable: true, get: function () { return run_state_1.migrateRunsDir; } });
+Object.defineProperty(exports, "runDir", { enumerable: true, get: function () { return run_state_1.runDir; } });
+Object.defineProperty(exports, "readRunState", { enumerable: true, get: function () { return run_state_1.readRunState; } });
+Object.defineProperty(exports, "writeRunState", { enumerable: true, get: function () { return run_state_1.writeRunState; } });
+Object.defineProperty(exports, "findActiveRun", { enumerable: true, get: function () { return run_state_1.findActiveRun; } });
+Object.defineProperty(exports, "createRun", { enumerable: true, get: function () { return run_state_1.createRun; } });
+var state_machine_1 = require("./state-machine");
+Object.defineProperty(exports, "applyStepEvent", { enumerable: true, get: function () { return state_machine_1.applyStepEvent; } });
+Object.defineProperty(exports, "hasPendingCommitDebt", { enumerable: true, get: function () { return state_machine_1.hasPendingCommitDebt; } });
+var run_id_1 = require("./run-id");
+Object.defineProperty(exports, "createRunId", { enumerable: true, get: function () { return run_id_1.createRunId; } });
+Object.defineProperty(exports, "computePlanHash", { enumerable: true, get: function () { return run_id_1.computePlanHash; } });
 var worker_1 = require("./worker");
 Object.defineProperty(exports, "runSingleMigrationWorker", { enumerable: true, get: function () { return worker_1.runSingleMigrationWorker; } });
+var orchestrator_1 = require("./orchestrator");
+Object.defineProperty(exports, "runOrchestratorInit", { enumerable: true, get: function () { return orchestrator_1.runOrchestratorInit; } });
+Object.defineProperty(exports, "runOrchestratorReconcile", { enumerable: true, get: function () { return orchestrator_1.runOrchestratorReconcile; } });

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

@@ -0,0 +1,20 @@
+import { type StepAction } from './state-machine';
+import { type PlannedMigration } from '../migration-shape';
+export interface RunOrchestratorInitInput {
+    root: string;
+    migrationsJson: {
+        migrations?: PlannedMigration[];
+        [k: string]: unknown;
+    };
+    createCommits: boolean;
+    commitPrefix: string;
+    skipInstall: boolean;
+    installedNxVersion: string;
+}
+export interface RunOrchestratorReconcileInput {
+    root: string;
+    runId: string;
+    stepAction?: StepAction;
+}
+export declare function runOrchestratorInit(input: RunOrchestratorInitInput): Promise<void>;
+export declare function runOrchestratorReconcile(input: RunOrchestratorReconcileInput): Promise<void>;