@ohos-ports/nx 23.3.0-beta.2 → 24.0.2-beta.0

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

@@ -1,14 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveAgentic = resolveAgentic;
-exports.resolveShouldRunValidation = resolveShouldRunValidation;
+exports.idProblemLines = idProblemLines;
+exports.dropUnsupportedAgent = dropUnsupportedAgent;
 const fs_1 = require("fs");
 const jsonc_parser_1 = require("jsonc-parser");
 const path_1 = require("path");
+const native_1 = require("../../../native");
 const output_1 = require("../../../utils/output");
 const workspace_root_1 = require("../../../utils/workspace-root");
 const migrate_analytics_1 = require("../migrate-analytics");
 const safe_prompt_1 = require("../safe-prompt");
+const text_1 = require("../text");
 const detect_installed_1 = require("./detect-installed");
 const inception_1 = require("./inception");
 const definitions_1 = require("./definitions");
@@ -56,12 +59,39 @@ async function resolveAgentic(input) {
     }
     return { kind: 'enabled', selectedAgent: selected };
 }
+const ID_PROBLEM_LABELS = {
+    'not-shell-safe': 'not shell-safe',
+    duplicate: 'listed more than once',
+};
+function idProblemLines(problems) {
+    return problems.map(({ id, problem }) => `- ${(0, text_1.singleLine)(id)} (${ID_PROBLEM_LABELS[problem]})`);
+}
 /**
- * No warning when `--validate` is passed with the agentic flow off: validation
- * requires an active agent session by definition.
+ * Drops an enabled agent, with a warning, where the orchestrator that drives
+ * it cannot run: under the WASM build, and for migration ids an orchestrated
+ * run cannot take.
  */
-function resolveShouldRunValidation(args) {
-    return args.validate !== false && args.agenticKind === 'enabled';
+function dropUnsupportedAgent(agentic, idProblems) {
+    if (agentic.kind !== 'enabled')
+        return agentic;
+    if (native_1.IS_WASM) {
+        output_1.output.warn({
+            title: 'Skipping the agentic flow: it needs the native nx binary, and this run loaded the WASM build.',
+            bodyLines: ['Continuing the migration without the agentic flow.'],
+        });
+        return { kind: 'disabled' };
+    }
+    if (idProblems.length > 0) {
+        output_1.output.warn({
+            title: 'Skipping the agentic flow: it needs each migration id to be shell-safe (letters, digits and @/:._-) and listed once, and these are not:',
+            bodyLines: [
+                ...idProblemLines(idProblems),
+                'Continuing the migration without the agentic flow. Generators still run. Prompt-only migrations and the prompt part of hybrid migrations are skipped and listed as next steps, and no AI validation runs.',
+            ],
+        });
+        return { kind: 'disabled' };
+    }
+    return agentic;
 }
 async function resolveFlag(input, isInteractive, detected) {
     if (input.agentic === true) {
@@ -97,7 +127,7 @@ function requireInteractiveOrAbort(isInteractive) {
     if (isInteractive)
         return;
     output_1.output.error({
-        title: 'The agentic flow is interactive-only in this release.',
+        title: 'The agentic flow needs an interactive terminal.',
         bodyLines: [
             'Re-run in an interactive terminal, or pass `--agentic=false` to skip the agentic flow.',
         ],
@@ -106,9 +136,9 @@ function requireInteractiveOrAbort(isInteractive) {
 }
 function warnAgenticInteractiveOnly() {
     output_1.output.warn({
-        title: 'Skipping the agentic flow: it is interactive-only in this release and this run is non-interactive.',
+        title: 'Skipping the agentic flow: the agent session needs an interactive terminal, and this run is non-interactive.',
         bodyLines: [
-            'Continuing the migration without the agentic flow. Re-run in an interactive terminal to use it.',
+            'Continuing without the agentic flow. Generators still run, prompt-based changes are left for you to apply, and no AI validation runs. Re-run in an interactive terminal to use the agentic flow.',
         ],
     });
 }

package/dist/src/command-line/migrate/agentic/types.d.ts

@@ -2,18 +2,18 @@ import type { AgentId } from './cli-args';
 export type { AgentId };
 /**
  * Workspace-relative directory holding all migrate-run scratch: a run
- * directory per run id. Shared by the run-dir layout in `handoff.ts` and the
+ * directory per run id. Shared by the run-dir layout in `run-state.ts` and the
  * agent permission rules in `definitions.ts` so the pre-authorized write scope
  * can't drift from the actual layout. It lives here so `definitions.ts`,
- * loaded whenever the agentic flow is resolved, doesn't pull in the handoff
- * runtime for the path alone.
+ * loaded whenever the agentic flow is resolved, doesn't pull in the run state
+ * module for the path alone.
  */
 export declare const MIGRATE_RUNS_RELATIVE_DIR = ".nx/migrate-runs";
 /**
  * The one subtree of a run directory an agent writes; everything beside it is
  * state Nx owns, so the pre-authorized write scope stops here. Handoff names
- * derive from step ids or package and migration names, so flattening them into
- * the run dir would leave Nx no name it could safely add.
+ * derive from step ids, so flattening them into the run dir would leave Nx no
+ * name it could safely add.
  */
 export declare const HANDOFFS_DIR_NAME = "handoffs";
 /**
@@ -29,7 +29,7 @@ export declare function isHandoffGitignoreMigration(m: {
  * A coding agent that was found on the user's machine, ready to be spawned.
  *
  * Produced by `detect-installed.ts`. The `binary` is an absolute path so the
- * runner can spawn it directly without re-resolving against PATH.
+ * master session can spawn it directly without re-resolving against PATH.
  */
 export interface DetectedInstalledAgent {
     id: AgentId;
@@ -38,37 +38,8 @@ export interface DetectedInstalledAgent {
     source: 'path' | 'well-known';
 }
 /**
- * Inputs the runner provides when asking an agent definition to build its
- * spawn arguments. Kept minimal — agent-specific quirks (e.g. transient agent
- * name for OpenCode) are encoded inside the definition, not here.
- *
- * Both prompts are written to disk (see `instruction-files.ts`) and reached
- * through `systemPromptFilePath` / `instructionsPointer`. The inline fields
- * below are the exception, for agents that cannot be pointed at a file.
- */
-export interface InvocationContext {
-    /** Absolute path of the file holding the step's system prompt. */
-    systemPromptFilePath: string;
-    /** Verbatim system prompt, only for a step with no file-loading path. */
-    systemPrompt: string;
-    /** Single-line command-line text pointing the agent at its instructions. */
-    instructionsPointer: string;
-    /** Inline handoff contract and pointer to `systemPromptFilePath`. */
-    inlineSystemContext: string;
-    /** Shorter `inlineSystemContext`, substituted on Windows shim overflow. */
-    inlineSystemContextFallback: string;
-    workspaceRoot: string;
-    /**
-     * Name of the run directory under `MIGRATE_RUNS_RELATIVE_DIR` holding this
-     * invocation's handoff. A workspace can carry several run directories at
-     * once, so a definition that pre-authorizes the handoff write narrows it to
-     * this one: the others belong to runs this invocation is not executing.
-     */
-    runDirName: string;
-}
-/**
- * What an agent definition returns from `buildInteractive`. The runner combines
- * this with the detected binary path to actually spawn.
+ * What a master invocation builder returns. The master session combines this
+ * with the detected binary path to actually spawn.
  */
 export interface InvocationSpec {
     args: string[];
@@ -85,42 +56,16 @@ export interface AgentDefinition {
     binaryNames: string[];
     /** Absolute paths to probe as a fallback when PATH lookup misses. */
     wellKnownPaths(): string[];
-    buildInteractive(ctx: InvocationContext): InvocationSpec;
 }
 /**
  * Output of the agent's handoff file, written at the end of an agentic step.
- * The two locked fields drive the failure-handling matrix in the design doc;
- * extra fields are tolerated and surfaced via `extras`.
+ * Extra fields are tolerated and surfaced via `extras`.
  */
 export interface HandoffFile {
     status: 'success' | 'failed';
     summary: string;
     extras?: Record<string, unknown>;
 }
-/**
- * Outcome the runner reports back to the migrate orchestrator after a single
- * agentic step. The four kinds mirror the (a)/(b)/(c) matrix plus the user's
- * choice when (c) fires.
- *
- * `ambiguous-abort.causeSummary`: pre-rendered explanation lines. Populated
- * when Ctrl+C bypasses the ambiguous prompt (so the cause was never shown
- * inline) and forwarded so the caller can surface it. Omitted when the user
- * chose "abort" at the prompt — the cause was already shown there.
- */
-export type HandoffOutcome = {
-    kind: 'success';
-    summary: string;
-    extras?: Record<string, unknown>;
-} | {
-    kind: 'failed';
-    summary: string;
-    extras?: Record<string, unknown>;
-} | {
-    kind: 'ambiguous-continue';
-} | {
-    kind: 'ambiguous-abort';
-    causeSummary?: string[];
-};
 /**
  * Result of the up-front resolution phase, run once per run-phase invocation
  * and applied to every migration it covers.
@@ -141,7 +86,3 @@ export type ResolvedAgentic = {
     kind: 'enabled';
     selectedAgent: DetectedInstalledAgent;
 };
-/** The `enabled` variant, useful for narrowed function signatures. */
-export type EnabledResolvedAgentic = Extract<ResolvedAgentic, {
-    kind: 'enabled';
-}>;

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

@@ -4,18 +4,18 @@ exports.PROMPTS_DIR_NAME = exports.HANDOFFS_DIR_NAME = exports.MIGRATE_RUNS_RELA
 exports.isHandoffGitignoreMigration = isHandoffGitignoreMigration;
 /**
  * Workspace-relative directory holding all migrate-run scratch: a run
- * directory per run id. Shared by the run-dir layout in `handoff.ts` and the
+ * directory per run id. Shared by the run-dir layout in `run-state.ts` and the
  * agent permission rules in `definitions.ts` so the pre-authorized write scope
  * can't drift from the actual layout. It lives here so `definitions.ts`,
- * loaded whenever the agentic flow is resolved, doesn't pull in the handoff
- * runtime for the path alone.
+ * loaded whenever the agentic flow is resolved, doesn't pull in the run state
+ * module for the path alone.
  */
 exports.MIGRATE_RUNS_RELATIVE_DIR = '.nx/migrate-runs';
 /**
  * The one subtree of a run directory an agent writes; everything beside it is
  * state Nx owns, so the pre-authorized write scope stops here. Handoff names
- * derive from step ids or package and migration names, so flattening them into
- * the run dir would leave Nx no name it could safely add.
+ * derive from step ids, so flattening them into the run dir would leave Nx no
+ * name it could safely add.
  */
 exports.HANDOFFS_DIR_NAME = 'handoffs';
 /**
@@ -28,9 +28,7 @@ exports.PROMPTS_DIR_NAME = 'prompts';
  * `.gitignore`. Hard-coded because the agentic preflight is a deliberate
  * one-off coupling: this exact migration owns the entry that keeps
  * `.nx/migrate-runs/<run-id>/...` scratch out of per-migration commits. If
- * the migration is ever renamed, this entry must move with it. It lives here
- * rather than in `handoff-gitignore.ts` so `sortMigrations`' hoist check
- * doesn't load that module's migration-execution machinery.
+ * the migration is ever renamed, this entry must move with it.
  */
 const HANDOFF_GITIGNORE_MIGRATION_PACKAGE = 'nx';
 const HANDOFF_GITIGNORE_MIGRATION_NAME = '23-0-0-add-migrate-runs-to-git-ignore';

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

@@ -55,14 +55,12 @@ function withMigrationOptions(yargs) {
         type: 'string',
     })
         .option('runMigration', {
-        describe: "Run a single migration from migrations.json by id. The id is '<package>:<name>'; a bare '<name>' is accepted when it matches exactly one migration. A name that contains ':' must use the full '<package>:<name>' form.",
+        describe: "Run a single migration from migrations.json by id. The id is '<package>:<name>'; a bare '<name>' is accepted when it matches exactly one migration. A name that contains ':' must use the full '<package>:<name>' form. With an AI agent, nx runs the migration's generator itself, when it has one, and starts the agent only when the migration leaves a prompt to apply or changes to review. Refuses to start while another nx migrate process is working on a run.",
         type: 'string',
     })
         .option('runId', {
-        // Hidden with the orchestrator itself.
-        describe: 'The orchestrated migrate run to record a single migration into, to continue with --run-migrations, or to reconcile when given alone.',
+        describe: "The id of a migrate run, as nx prints it. With --run-migrations: continue that run, or replace it with --start-fresh. The AI agent driving a run also passes it with --run-migration to record a migration into the run, and alone to record a step's outcome and get the next step.",
         type: 'string',
-        hidden: true,
     })
         .option('stepAction', {
         describe: 'How an orchestrated reconcile resolves its single failed or died step.',
@@ -71,9 +69,8 @@ function withMigrationOptions(yargs) {
         hidden: true,
     })
         .option('startFresh', {
-        describe: 'With --run-migrations and --run-id=<id> under the orchestrator: delete the record of the active migrate run the id names and start a new run over the whole plan. Migrations the deleted run applied stay applied.',
+        describe: 'With --run-migrations and --run-id=<id>: delete the record of the active migrate run the id names, then run the whole plan again, as a new run when orchestrated. Migrations the deleted run applied stay applied.',
         type: 'boolean',
-        hidden: true,
     })
         .option('ifExists', {
         describe: `Run migrations only if the migrations file exists, if not continues successfully.`,
@@ -123,17 +120,16 @@ function withMigrationOptions(yargs) {
         choices: exports.MULTI_MAJOR_MODES,
     })
         .option('agentic', {
-        describe: 'Enable the agentic flow for prompt-based migrations and AI-driven review. Pass `--agentic=<agent>` to pin a specific agent (claude-code, codex, or opencode). Pass `--agentic=false` or `--no-agentic` to disable.',
+        describe: 'Use an AI agent to apply prompt-based migrations and review the results. With --run-migrations, one agent session drives the whole run. With --run-migration, the session covers that one migration. Pass `--agentic=<agent>` to pin a specific agent (claude-code, codex, or opencode). Pass `--agentic=false` or `--no-agentic` to disable it. Inside an AI agent, disabling it stops nx from asking that agent to review the changes of generator-only migrations. Migration prompts still go to that agent.',
         coerce: cli_args_1.coerceAgenticArg,
     })
         .option('validate', {
-        describe: 'When `--agentic` resolves to an enabled agent, run agent-driven validation after generator-only migrations that have no `prompt:` field. Defaults to on; pass `--no-validate` to opt out. Has no effect when `--agentic` is disabled, when running inside an outer agent, or when running non-interactively without an explicit agent.',
+        describe: 'Have the AI agent driving the run review the changes of generator-only migrations (those with no `prompt:` field). On by default; pass `--no-validate` to opt out. A continued run keeps the setting it started with. Has no effect when no agent drives the run. With --run-migration inside an AI agent, it controls whether nx prints review instructions for that agent. `--agentic=false` turns them off too.',
         type: 'boolean',
     })
         .option('finalValidation', {
-        describe: 'With --run-migrations under the orchestrator: end the run with an agent validation pass over the whole workspace once every migration has run. On by default; pass --no-final-validation to opt out.',
+        describe: 'With --run-migrations, when an AI agent drives the run: once every migration has run, the agent checks that the projects the run touched still lint, build, and pass their unit tests. On by default; pass --no-final-validation to opt out. A continued run keeps the setting it started with.',
         type: 'boolean',
-        hidden: true,
     })
         .check(({ createCommits, commitPrefix, from, excludeAppliedMigrations, include, agentic, }) => {
         // Only an explicit `--no-create-commits` is decidable here, before the

package/dist/src/command-line/migrate/execute-migration.d.ts

@@ -9,8 +9,8 @@ interface PackageMigrationConfig extends NxMigrationsConfiguration {
 export declare function readPackageMigrationConfig(packageName: string, dir: string): PackageMigrationConfig;
 /**
  * With a `sink`, stdin is ignored and stdout and stderr are collected for a
- * caller sharing the terminal. On POSIX the child stays in nx's process
- * group. Without a sink, the install owns the terminal.
+ * caller sharing the terminal, and the install runs without the terminal (see
+ * `spawnWithoutTerminal`). Without a sink, the install owns the terminal.
  */
 export declare function runInstall(nxWorkspaceRoot?: string, phase?: MigrationInstallPhase, rerunCommand?: string, sink?: MigrateOutputSink): Promise<void>;
 export type MigrationInstallPhase = 'pre-migration' | 'post-migration';
@@ -59,10 +59,10 @@ export declare function runNxOrAngularMigration(root: string, migration: {
     madeChanges: boolean;
 }>;
 /**
- * The workspace's declared dependencies, serialized for equality comparison,
- * or `null` when package.json could not be read or parsed. Callers that
- * persist the value across processes need that distinction: an unreadable
- * package.json is not an empty dependency set.
+ * The workspace's declared dependencies, catalogs included, serialized for
+ * equality comparison, or `null` when package.json could not be read or
+ * parsed. Callers that persist the value across processes need that
+ * distinction: an unreadable package.json is not an empty dependency set.
  */
 export declare function readPackageJsonDeps(root: string): string | null;
 export declare function getStringifiedPackageJsonDeps(root: string): string;

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

@@ -25,6 +25,7 @@ const path_1 = require("path");
 const semver_1 = require("semver");
 const handle_import_1 = require("../../utils/handle-import");
 const tree_1 = require("../../generators/tree");
+const catalog_1 = require("../../utils/catalog");
 const fileutils_1 = require("../../utils/fileutils");
 const logger_1 = require("../../utils/logger");
 const text_1 = require("./text");
@@ -33,6 +34,7 @@ const package_manager_1 = require("../../utils/package-manager");
 const fs_1 = require("fs");
 const installation_directory_1 = require("../../utils/installation-directory");
 const shell_quoting_1 = require("../../utils/shell-quoting");
+const spawn_without_terminal_1 = require("../../utils/spawn-without-terminal");
 const project_graph_1 = require("../../project-graph/project-graph");
 const version_utils_1 = require("./version-utils");
 const deferred_output_1 = require("./deferred-output");
@@ -64,8 +66,8 @@ function readPackageMigrationConfig(packageName, dir) {
 }
 /**
  * With a `sink`, stdin is ignored and stdout and stderr are collected for a
- * caller sharing the terminal. On POSIX the child stays in nx's process
- * group. Without a sink, the install owns the terminal.
+ * caller sharing the terminal, and the install runs without the terminal (see
+ * `spawnWithoutTerminal`). Without a sink, the install owns the terminal.
  */
 function runInstall(nxWorkspaceRoot, phase = 'pre-migration', rerunCommand, sink) {
     const cwd = nxWorkspaceRoot ?? process.cwd();
@@ -81,14 +83,21 @@ function runInstall(nxWorkspaceRoot, phase = 'pre-migration', rerunCommand, sink
         // Without a sink it is mirrored live and other package managers inherit
         // stderr directly, since their output is not inspected.
         const shouldCaptureStderr = packageManager === 'npm';
-        const child = (0, child_process_1.spawn)(installCommand, {
-            shell: true,
-            stdio: sink
-                ? ['ignore', 'pipe', 'pipe']
-                : ['inherit', 'inherit', shouldCaptureStderr ? 'pipe' : 'inherit'],
-            windowsHide: true,
-            cwd,
-        });
+        const child = sink
+            ? (0, spawn_without_terminal_1.spawnWithoutTerminal)(installCommand, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                cwd,
+            })
+            : (0, child_process_1.spawn)(installCommand, {
+                shell: true,
+                stdio: [
+                    'inherit',
+                    'inherit',
+                    shouldCaptureStderr ? 'pipe' : 'inherit',
+                ],
+                windowsHide: true,
+                cwd,
+            });
         // Decoded per stream: a chunk boundary can split a multi-byte character,
         // and a sequence still incomplete at the end is what `end()` returns.
         const stdoutText = new string_decoder_1.StringDecoder('utf8');
@@ -334,15 +343,16 @@ async function runNxOrAngularMigration(root, migration, isVerbose, captureGenera
     return { changes, nextSteps, agentContext, skipAgentic, logs, madeChanges };
 }
 /**
- * The workspace's declared dependencies, serialized for equality comparison,
- * or `null` when package.json could not be read or parsed. Callers that
- * persist the value across processes need that distinction: an unreadable
- * package.json is not an empty dependency set.
+ * The workspace's declared dependencies, catalogs included, serialized for
+ * equality comparison, or `null` when package.json could not be read or
+ * parsed. Callers that persist the value across processes need that
+ * distinction: an unreadable package.json is not an empty dependency set.
  */
 function readPackageJsonDeps(root) {
     try {
         const { dependencies, devDependencies } = (0, fileutils_1.readJsonFile)((0, path_1.join)(root, 'package.json'));
-        return JSON.stringify([dependencies, devDependencies]);
+        const catalogs = (0, catalog_1.getCatalogManager)(root)?.getCatalogDefinitions(root);
+        return JSON.stringify([dependencies, devDependencies, catalogs]);
     }
     catch {
         return null;

package/dist/src/command-line/migrate/migrate-analytics.d.ts

@@ -13,11 +13,11 @@ export type MigratePromptChoices = {
     multi_major: 'direct' | 'latest-in-current' | 'latest-in-next';
     agentic: 'yes-once' | 'yes-flex' | 'yes-pin' | 'no-once' | 'no-never';
     agent_select: string;
-    ambiguous_agent_outcome: 'abort' | 'continue';
 };
 export type MigratePromptName = keyof MigratePromptChoices;
 export type MigrateGenerateErrorCode = 'resolve_version' | 'fetch_migrations' | 'package_updates';
 export type MigrateRunErrorCode = 'npm_install' | 'migration_exec' | 'agentic' | 'other';
+export type MigrateRunStopReason = 'existing_run' | 'declined_commits' | 'aborted' | 'runbook_missing';
 export declare function setMigrateInclude(include: MigrateInclude): void;
 export declare function setMigrateIncludeSource(source: MigrateIncludeSource): void;
 export declare function classifyMigrateFetchFallback(error: unknown): MigrateFetchFallbackReason;
@@ -60,6 +60,11 @@ export declare function reportMigrateRunComplete(opts: {
     migrationCount: number;
     appliedCount: number;
 }): void;
+/**
+ * Closes a `migrate_run_start` whose invocation stopped before running any
+ * migration.
+ */
+export declare function reportMigrateRunStopped(reason: MigrateRunStopReason): void;
 export declare function reportMigrateRunError(opts: {
     code: MigrateRunErrorCode;
     migrationPackage?: string;
@@ -127,5 +132,17 @@ export declare function reportMigrateSingleMigrationInvocation(opts: {
     migrationType: 'generator' | 'prompt' | 'hybrid';
     orchestrated: boolean;
 }): void;
+/**
+ * Closes a `--run-migration` run that had an agent selected. `agentUsed` is
+ * set only when the agent started: a migration that left it no work
+ * completes without one.
+ */
+export declare function reportMigrateSingleMigrationComplete(opts: {
+    agentUsed?: string;
+}): void;
+/** The agent session of a `--run-migration` run ended with the migration unfinished. */
+export declare function reportMigrateSingleMigrationAbandoned(opts: {
+    agentUsed: string;
+}): void;
 export declare function computeMajorsCrossed(installed: string | null | undefined, target: string | null | undefined): number | undefined;
 export declare function safeReport(emit: () => void): void;

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

@@ -10,6 +10,7 @@ exports.reportMigrateGenerateError = reportMigrateGenerateError;
 exports.reportMigrateRunStart = reportMigrateRunStart;
 exports.hasMigrateRunStarted = hasMigrateRunStarted;
 exports.reportMigrateRunComplete = reportMigrateRunComplete;
+exports.reportMigrateRunStopped = reportMigrateRunStopped;
 exports.reportMigrateRunError = reportMigrateRunError;
 exports.reportMigrateOrchestratorInit = reportMigrateOrchestratorInit;
 exports.reportMigrateOrchestratorDispense = reportMigrateOrchestratorDispense;
@@ -19,6 +20,8 @@ exports.reportMigrateOrchestratorAbandoned = reportMigrateOrchestratorAbandoned;
 exports.reportMigrateOrchestratorResume = reportMigrateOrchestratorResume;
 exports.reportMigrateOrchestratorExistingRun = reportMigrateOrchestratorExistingRun;
 exports.reportMigrateSingleMigrationInvocation = reportMigrateSingleMigrationInvocation;
+exports.reportMigrateSingleMigrationComplete = reportMigrateSingleMigrationComplete;
+exports.reportMigrateSingleMigrationAbandoned = reportMigrateSingleMigrationAbandoned;
 exports.computeMajorsCrossed = computeMajorsCrossed;
 exports.safeReport = safeReport;
 const semver_1 = require("semver");
@@ -165,6 +168,17 @@ function reportMigrateRunComplete(opts) {
         });
     });
 }
+/**
+ * Closes a `migrate_run_start` whose invocation stopped before running any
+ * migration.
+ */
+function reportMigrateRunStopped(reason) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)(`migrate_run_stopped_${reason}`);
+    });
+}
 function reportMigrateRunError(opts) {
     safeReport(() => {
         if (!analytics_1.customDimensions || runErrorRecorded)
@@ -305,6 +319,30 @@ function reportMigrateSingleMigrationInvocation(opts) {
         });
     });
 }
+/**
+ * Closes a `--run-migration` run that had an agent selected. `agentUsed` is
+ * set only when the agent started: a migration that left it no work
+ * completes without one.
+ */
+function reportMigrateSingleMigrationComplete(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_single_migration_complete', {
+            [analytics_1.customDimensions.agentUsed]: opts.agentUsed,
+        });
+    });
+}
+/** The agent session of a `--run-migration` run ended with the migration unfinished. */
+function reportMigrateSingleMigrationAbandoned(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_single_migration_abandoned', {
+            [analytics_1.customDimensions.agentUsed]: opts.agentUsed,
+        });
+    });
+}
 // `_migrate` runs either from a temp install of the latest CLI or from the
 // workspace-local installation; same signal as the run-phase re-dispatch
 // check in migrate.ts.

package/dist/src/command-line/migrate/migrate-commits.d.ts

@@ -1,5 +1,19 @@
+import { type WorkingTreeStatus } from '../../utils/git-utils';
 import type { ResolvedAgentic } from './agentic/types';
 import { type MigrateOutputSink } from './deferred-output';
+/** Workspace-relative paths nx migrate writes for itself. */
+export declare const MIGRATE_OWNED_PATHS: string[];
+/**
+ * The scratch state is excluded even when git ignores it, since its ignore
+ * rule can go missing mid-run.
+ */
+export declare function migrateCommitExcludes(root: string): string[];
+export declare function migrateTreeStatus(root: string): WorkingTreeStatus;
+/**
+ * What becomes of a failed commit's changes: a later migration step's commit
+ * takes them in, or, with no later step, the user commits or reverts them.
+ */
+export type CommitFailureRecovery = 'later-step' | 'manual';
 /**
  * Discriminated result for `commitMigrationIfRequested`. Distinguishes the
  * shapes the executor needs to react to:
@@ -28,31 +42,30 @@ export type CommitResult = {
  * can see which earlier migrations' diffs this commit absorbed (their own
  * commits failed and `git add -A` picked their working-tree state up too).
  *
- * The default `failureGuidance` describes the classic loop's absorb-and-recap
- * behavior; a caller with no later commit or recap to absorb the diff (the
- * standalone single-migration worker) passes its own.
+ * `recovery` picks the failure guidance: the default describes the classic
+ * loop's absorb-and-recap behavior, and a caller with no later migration step
+ * (a `--run-migration` run) passes 'manual'.
+ *
+ * A `sink` collects the output for a caller sharing the terminal with an
+ * agent, and the commit then runs without the terminal.
  */
 export declare function commitMigrationIfRequested(root: string, migration: {
     name: string;
 }, shouldCreateCommits: boolean, commitPrefix: string, installDepsIfChanged: () => Promise<void>, pendingMigrations?: ReadonlyArray<{
     package: string;
     name: string;
-}>, failureGuidance?: string, out?: MigrateOutputSink): Promise<CommitResult>;
+}>, recovery?: CommitFailureRecovery, sink?: MigrateOutputSink): Promise<CommitResult>;
 /**
- * Commits any pre-existing working-tree state into a dedicated "checkpoint"
- * commit before the first migration runs. Without this, the first migration's
- * commit would absorb whatever was already pending — most commonly the
- * package.json edit `nx migrate latest` produces and the lockfile churn from
- * the orchestrator's `npm install --ignore-scripts` step — and migration 1's
- * validation would see that mixed in with the generator output. No-op when
- * the working tree is already clean.
+ * Commits pre-existing working-tree state, except what `migrateCommitExcludes`
+ * leaves out, into a dedicated "checkpoint" commit before the first migration
+ * runs. Without this, the first migration's commit would absorb whatever was
+ * already pending (most commonly the package.json edit `nx migrate latest`
+ * produces and the lockfile churn from the orchestrator's
+ * `npm install --ignore-scripts` step), and migration 1's validation would see
+ * that mixed in with the generator output. No-op when the working tree is
+ * already clean.
  */
 export declare function commitCheckpointBeforeMigrations(root: string, commitPrefix: string): void;
-/**
- * `agenticHasDiffContext` gates the agent prompt: without per-migration commits
- * to isolate a migration's diff, the prompt embeds a file list instead of
- * pointing at git.
- */
 export declare function resolveCreateCommits(args: {
     createCommits: boolean | undefined;
     mode: ResolvedAgentic['kind'] | 'orchestrated';
@@ -60,7 +73,6 @@ export declare function resolveCreateCommits(args: {
     commitPrefixIsCustom?: boolean;
 }): {
     effective: boolean;
-    agenticHasDiffContext: boolean;
     warning?: string;
     error?: string;
 };