nx 23.2.0-beta.4 → 23.2.0-beta.6

package/dist/bin/nx.js

@@ -209,6 +209,7 @@ function resolveNx(workspace) {
 function isNxCloudCommand(command) {
     const nxCloudCommands = [
         'start-ci-run',
+        'start-nx-agents',
         'start-agent',
         'stop-all-agents',
         'complete-ci-run',

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

@@ -49,6 +49,7 @@ async function affected(command, args, extraTargetDependencies = {}, extraOption
                 }
                 else {
                     const status = await (0, run_command_1.runCommand)(projectsWithTarget, projectGraph, { nxJson }, nxArgs, overrides, null, extraTargetDependencies, extraOptions);
+                    await output_1.output.drain();
                     process.exit(status);
                 }
                 break;

package/dist/src/command-line/configure-ai-agents/configure-ai-agents.js

@@ -11,7 +11,7 @@ const constants_1 = require("../../ai/constants");
 const detect_ai_agent_1 = require("../../ai/detect-ai-agent");
 const utils_1 = require("../../ai/utils");
 const client_1 = require("../../daemon/client/client");
-const devkit_internals_1 = require("../../devkit-internals");
+const package_json_1 = require("../../utils/package-json");
 const output_1 = require("../../utils/output");
 const package_manager_1 = require("../../utils/package-manager");
 const provenance_1 = require("../../utils/provenance");
@@ -44,7 +44,7 @@ async function configureAiAgentsHandler(args, inner = false) {
     let cleanup;
     try {
         await (0, provenance_1.ensurePackageHasProvenance)('nx', 'latest');
-        const packageInstallResults = (0, devkit_internals_1.installPackageToTmp)('nx', 'latest', (0, package_manager_1.detectPackageManager)(workspace_root_1.workspaceRoot));
+        const packageInstallResults = (0, package_json_1.installPackageToTmp)('nx', 'latest', (0, package_manager_1.detectPackageManager)(workspace_root_1.workspaceRoot));
         cleanup = packageInstallResults.cleanup;
         let modulePath = require.resolve('nx/src/command-line/configure-ai-agents/configure-ai-agents.js', { paths: [packageInstallResults.tempDir] });
         const module = await (0, handle_import_1.handleImport)(modulePath);

package/dist/src/command-line/init/init-v2.js

@@ -11,6 +11,7 @@ const nx_json_1 = require("../../config/nx-json");
 const fileutils_1 = require("../../utils/fileutils");
 const get_package_name_from_import_path_1 = require("../../utils/get-package-name-from-import-path");
 const output_1 = require("../../utils/output");
+const package_json_1 = require("../../utils/package-json");
 const package_manager_1 = require("../../utils/package-manager");
 const versions_1 = require("../../utils/versions");
 const workspace_context_1 = require("../../utils/workspace-context");
@@ -26,7 +27,6 @@ const angular_1 = require("./implementation/angular");
 const add_nx_scripts_1 = require("./implementation/dot-nx/add-nx-scripts");
 const utils_1 = require("./implementation/utils");
 const provenance_1 = require("../../utils/provenance");
-const devkit_internals_1 = require("../../devkit-internals");
 const handle_import_1 = require("../../utils/handle-import");
 const native_1 = require("../../native");
 const detect_ai_agent_1 = require("../../ai/detect-ai-agent");
@@ -43,7 +43,7 @@ async function initHandler(options, inner = false) {
     let cleanup;
     try {
         await (0, provenance_1.ensurePackageHasProvenance)('nx', 'latest');
-        const packageInstallResults = (0, devkit_internals_1.installPackageToTmp)('nx', 'latest', (0, package_manager_2.detectPackageManager)(process.cwd()));
+        const packageInstallResults = (0, package_json_1.installPackageToTmp)('nx', 'latest', (0, package_manager_2.detectPackageManager)(process.cwd()));
         cleanup = packageInstallResults.cleanup;
         let modulePath = require.resolve('nx/src/command-line/init/init-v2.js', {
             paths: [packageInstallResults.tempDir],

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

@@ -4,7 +4,7 @@ exports.AGENT_DEFINITIONS = exports.opencodeDefinition = exports.codexDefinition
 exports.getAgentDefinition = getAgentDefinition;
 const os_1 = require("os");
 const path_1 = require("path");
-const handoff_1 = require("./handoff");
+const types_1 = require("./types");
 // --- Claude Code ---------------------------------------------------------
 function claudeCodeWellKnownPaths() {
     if (process.platform === 'win32') {
@@ -18,7 +18,7 @@ function claudeCodeWellKnownPaths() {
 // ends with an approval prompt for nx's own handoff scratch. Prefix-less
 // patterns resolve against the session cwd (pinned to the workspace root
 // below); `Edit` covers corrections to an already-written handoff.
-const CLAUDE_CODE_HANDOFF_ALLOWED_TOOLS = `Write(${handoff_1.MIGRATE_RUNS_RELATIVE_DIR}/**),Edit(${handoff_1.MIGRATE_RUNS_RELATIVE_DIR}/**)`;
+const CLAUDE_CODE_HANDOFF_ALLOWED_TOOLS = `Write(${types_1.MIGRATE_RUNS_RELATIVE_DIR}/**),Edit(${types_1.MIGRATE_RUNS_RELATIVE_DIR}/**)`;
 function claudeCodeBuildInteractive(ctx) {
     return {
         // `--allowedTools` is variadic (space/comma separated): a positional

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

@@ -1,31 +1,27 @@
-export declare function isHandoffGitignoreMigration(m: {
-    package: string;
-    name: string;
-}): boolean;
 /**
  * Under `--agentic`, the runner writes per-run scratch under
  * `.nx/migrate-runs/<run-id>/`. The v23 migration
  * `23-0-0-add-migrate-runs-to-git-ignore` adds `.nx/migrate-runs` to
- * `.gitignore`; without intervention it would run in its declared slot
- * (typically late), so earlier per-migration commits would absorb the
- * scratch into the user-visible diff.
+ * `.gitignore`; in its declared slot (typically late) earlier per-migration
+ * commits would absorb the scratch into the user-visible diff.
  *
  * Two paths cover the leak, with no overlap:
  *
- *   1. HOIST — handled by the sort comparator in `executeMigrations`. When
- *      the v23 migration is in the queue, it sorts to position 0 and runs
- *      first via the normal migration runner (with its own log line and
- *      commit). Fully traceable in `git log`.
+ *   1. HOIST: `sortMigrations`, which `executeMigrations` applies, sorts the
+ *      v23 migration to position 0 when it is in the queue, so it runs first
+ *      through the normal runner with its own log line and commit. A
+ *      single-migration worker run needs no hoisting: the requested migration
+ *      is the entire queue.
  *
- *   2. INLINE FALLBACK — this function. When the migration is NOT in the
- *      queue AND the highest target version is < v23 (intra-pre-v23
- *      `--agentic` run), the migration won't run at all. Apply its body
- *      inline against an `FsTree` and commit it as a standalone preflight
- *      commit (or leave in the working tree under `--no-create-commits`).
+ *   2. INLINE FALLBACK, this function. When the migration is NOT in the queue
+ *      AND the highest target version is < v23 (intra-pre-v23 `--agentic`
+ *      run) it will never run, so apply its body inline against an `FsTree`
+ *      and commit it as a standalone preflight commit (or leave it in the
+ *      working tree under `--no-create-commits`).
  *
- * When the migration is not in the queue AND target >= v23, the user is
- * past v23 already. They had the entry historically; if it's gone, that's
- * a conscious removal we respect.
+ * Not in the queue AND target >= v23 means the user is already past v23. They
+ * had the entry historically; if it is gone, that is a conscious removal we
+ * respect.
  */
 export declare function applyAgenticHandoffGitignoreFallback({ migrations, installedNxVersion, effectiveCreateCommits, commitPrefix, root, }: {
     migrations: ReadonlyArray<{

package/dist/src/command-line/migrate/agentic/handoff-gitignore.js

@@ -1,6 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isHandoffGitignoreMigration = isHandoffGitignoreMigration;
 exports.applyAgenticHandoffGitignoreFallback = applyAgenticHandoffGitignoreFallback;
 const tslib_1 = require("tslib");
 const semver_1 = require("semver");
@@ -9,47 +8,36 @@ const add_migrate_runs_to_git_ignore_1 = tslib_1.__importDefault(require("../../
 const tree_1 = require("../../../generators/tree");
 const git_utils_1 = require("../../../utils/git-utils");
 const logger_1 = require("../../../utils/logger");
-/**
- * Composite identity of the v23 migration that adds `.nx/migrate-runs` to
- * `.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.
- */
-const HANDOFF_GITIGNORE_MIGRATION_PACKAGE = 'nx';
-const HANDOFF_GITIGNORE_MIGRATION_NAME = '23-0-0-add-migrate-runs-to-git-ignore';
-function isHandoffGitignoreMigration(m) {
-    return (m.package === HANDOFF_GITIGNORE_MIGRATION_PACKAGE &&
-        m.name === HANDOFF_GITIGNORE_MIGRATION_NAME);
-}
+const types_1 = require("./types");
 /**
  * Under `--agentic`, the runner writes per-run scratch under
  * `.nx/migrate-runs/<run-id>/`. The v23 migration
  * `23-0-0-add-migrate-runs-to-git-ignore` adds `.nx/migrate-runs` to
- * `.gitignore`; without intervention it would run in its declared slot
- * (typically late), so earlier per-migration commits would absorb the
- * scratch into the user-visible diff.
+ * `.gitignore`; in its declared slot (typically late) earlier per-migration
+ * commits would absorb the scratch into the user-visible diff.
  *
  * Two paths cover the leak, with no overlap:
  *
- *   1. HOIST — handled by the sort comparator in `executeMigrations`. When
- *      the v23 migration is in the queue, it sorts to position 0 and runs
- *      first via the normal migration runner (with its own log line and
- *      commit). Fully traceable in `git log`.
+ *   1. HOIST: `sortMigrations`, which `executeMigrations` applies, sorts the
+ *      v23 migration to position 0 when it is in the queue, so it runs first
+ *      through the normal runner with its own log line and commit. A
+ *      single-migration worker run needs no hoisting: the requested migration
+ *      is the entire queue.
  *
- *   2. INLINE FALLBACK — this function. When the migration is NOT in the
- *      queue AND the highest target version is < v23 (intra-pre-v23
- *      `--agentic` run), the migration won't run at all. Apply its body
- *      inline against an `FsTree` and commit it as a standalone preflight
- *      commit (or leave in the working tree under `--no-create-commits`).
+ *   2. INLINE FALLBACK, this function. When the migration is NOT in the queue
+ *      AND the highest target version is < v23 (intra-pre-v23 `--agentic`
+ *      run) it will never run, so apply its body inline against an `FsTree`
+ *      and commit it as a standalone preflight commit (or leave it in the
+ *      working tree under `--no-create-commits`).
  *
- * When the migration is not in the queue AND target >= v23, the user is
- * past v23 already. They had the entry historically; if it's gone, that's
- * a conscious removal we respect.
+ * Not in the queue AND target >= v23 means the user is already past v23. They
+ * had the entry historically; if it is gone, that is a conscious removal we
+ * respect.
  */
 async function applyAgenticHandoffGitignoreFallback({ migrations, installedNxVersion, effectiveCreateCommits, commitPrefix, root, }) {
-    if (migrations.some(isHandoffGitignoreMigration)) {
-        // The hoist path handles this via the sort comparator.
+    if (migrations.some(types_1.isHandoffGitignoreMigration)) {
+        // The queue runs it itself: hoisted to the front by the sort comparator
+        // in a full run, or as the single requested migration in a worker run.
         return;
     }
     if ((0, semver_1.major)(installedNxVersion) >= 23) {

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

@@ -1,12 +1,10 @@
 import { HandoffFile } from './types';
-/**
- * Workspace-relative directory holding all migrate-run scratch (handoff
- * files). Shared with the agent permission rules in `definitions.ts` so the
- * pre-authorized write scope can't drift from the actual layout.
- */
-export declare const MIGRATE_RUNS_RELATIVE_DIR = ".nx/migrate-runs";
 /** Returns the run directory for a given workspace + run id (target version). */
 export declare function runDirPath(workspaceRoot: string, runId: string): string;
+/** The version-derived run id: the highest target version in the plan. */
+export declare function resolveAgenticRunId(migrations: ReadonlyArray<{
+    version: string;
+}>): string;
 /**
  * `mkdir -p` with a contextual error wrapper. Without this, the raw
  * ENOSPC/EACCES/EROFS surfaces with no indication of which directory the

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

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MIGRATE_RUNS_RELATIVE_DIR = void 0;
 exports.runDirPath = runDirPath;
+exports.resolveAgenticRunId = resolveAgenticRunId;
 exports.mkdirSafely = mkdirSafely;
 exports.initRunDir = initRunDir;
 exports.stepHandoffPath = stepHandoffPath;
@@ -10,15 +10,16 @@ exports.readHandoff = readHandoff;
 exports.waitForValidHandoff = waitForValidHandoff;
 const fs_1 = require("fs");
 const path_1 = require("path");
-/**
- * Workspace-relative directory holding all migrate-run scratch (handoff
- * files). Shared with the agent permission rules in `definitions.ts` so the
- * pre-authorized write scope can't drift from the actual layout.
- */
-exports.MIGRATE_RUNS_RELATIVE_DIR = '.nx/migrate-runs';
+const semver_1 = require("semver");
+const version_utils_1 = require("../version-utils");
+const types_1 = require("./types");
 /** Returns the run directory for a given workspace + run id (target version). */
 function runDirPath(workspaceRoot, runId) {
-    return (0, path_1.join)(workspaceRoot, exports.MIGRATE_RUNS_RELATIVE_DIR, runId);
+    return (0, path_1.join)(workspaceRoot, types_1.MIGRATE_RUNS_RELATIVE_DIR, runId);
+}
+/** The version-derived run id: the highest target version in the plan. */
+function resolveAgenticRunId(migrations) {
+    return (0, semver_1.rsort)(migrations.map((m) => (0, version_utils_1.normalizeVersion)(m.version)))[0];
 }
 /**
  * `mkdir -p` with a contextual error wrapper. Without this, the raw

package/dist/src/command-line/migrate/agentic/print-dropped-agent-context.d.ts

@@ -1,15 +1,3 @@
-/**
- * Surfaces a migration's `agentContext` to stdout in an XML-tagged block so an
- * outer AI agent driving `nx migrate` can ingest the hints when no inner agent
- * step ran to consume them.
- *
- * Used only when `agentic.kind === 'inside-agent'`. Under `enabled`, the inner
- * step consumes `agentContext` via the prompt builders. Under `disabled` the
- * run is human-driven and printing agent-targeted context would only add noise.
- *
- * The label format is unambiguous so the outer agent can locate the block
- * within the mixed stdout stream (logger output, migration progress, etc.).
- */
 export interface DroppedAgentContextInput {
     migration: {
         package: string;
@@ -19,4 +7,11 @@ export interface DroppedAgentContextInput {
     agentContext: string[];
 }
 export declare function formatDroppedAgentContextForOuterAgent(input: DroppedAgentContextInput): string;
+export declare function escapeXmlAttr(value: string): string;
+/**
+ * Both the classic loop and the single-migration worker call this only under
+ * `agentic.kind === 'inside-agent'`. Under `enabled` the inner agent step
+ * consumes `agentContext` through the prompt builders; under `disabled` the
+ * run is human-driven and agent-targeted context is only noise.
+ */
 export declare function printDroppedAgentContextForOuterAgent(input: DroppedAgentContextInput): void;

package/dist/src/command-line/migrate/agentic/print-dropped-agent-context.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatDroppedAgentContextForOuterAgent = formatDroppedAgentContextForOuterAgent;
+exports.escapeXmlAttr = escapeXmlAttr;
 exports.printDroppedAgentContextForOuterAgent = printDroppedAgentContextForOuterAgent;
 const shared_rendering_1 = require("./prompts/shared-rendering");
 function formatDroppedAgentContextForOuterAgent(input) {
@@ -40,6 +41,12 @@ function escapeXmlAttr(value) {
         .replace(/"/g, '"')
         .replace(/'/g, ''');
 }
+/**
+ * Both the classic loop and the single-migration worker call this only under
+ * `agentic.kind === 'inside-agent'`. Under `enabled` the inner agent step
+ * consumes `agentContext` through the prompt builders; under `disabled` the
+ * run is human-driven and agent-targeted context is only noise.
+ */
 function printDroppedAgentContextForOuterAgent(input) {
     const block = formatDroppedAgentContextForOuterAgent(input);
     if (block) {

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

@@ -22,6 +22,16 @@ export interface AgenticStepResult {
      */
     ambiguous: boolean;
 }
+/**
+ * `runStep` travels in the context rather than being imported by its call
+ * sites, so this module loads only where the context is built, behind an
+ * agentic-enabled gate.
+ */
+export interface AgenticRunContext {
+    agentic: EnabledResolvedAgentic;
+    runDir: string;
+    runStep: typeof runAgenticPromptStep;
+}
 export interface RunAgenticPromptStepInput {
     root: string;
     migration: {

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

@@ -10,7 +10,15 @@ export interface ResolveAgenticInput {
     interactive?: boolean;
 }
 /**
- * Resolves the agentic state for a `--run-migrations` invocation. Runs once,
- * before the migration loop, and its result is cached for every entry.
+ * Callers resolve this once per run-phase invocation and reuse the result for
+ * every migration it covers.
  */
 export declare function resolveAgentic(input: ResolveAgenticInput): Promise<ResolvedAgentic>;
+/**
+ * No warning when `--validate` is passed with the agentic flow off: validation
+ * requires an active agent session by definition.
+ */
+export declare function resolveShouldRunValidation(args: {
+    validate: boolean | undefined;
+    agenticKind: ResolvedAgentic['kind'];
+}): boolean;

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveAgentic = resolveAgentic;
+exports.resolveShouldRunValidation = resolveShouldRunValidation;
 const tslib_1 = require("tslib");
 const fs_1 = require("fs");
 const jsonc_parser_1 = require("jsonc-parser");
@@ -18,8 +19,8 @@ const INSTALL_SUPPORTED_AGENTS_HINT = [
     ...definitions_1.AGENT_DEFINITIONS.map((def) => `  - ${def.displayName}`),
 ];
 /**
- * Resolves the agentic state for a `--run-migrations` invocation. Runs once,
- * before the migration loop, and its result is cached for every entry.
+ * Callers resolve this once per run-phase invocation and reuse the result for
+ * every migration it covers.
  */
 async function resolveAgentic(input) {
     if ((0, inception_1.isInsideAgent)()) {
@@ -57,6 +58,13 @@ async function resolveAgentic(input) {
     }
     return { kind: 'enabled', selectedAgent: selected };
 }
+/**
+ * No warning when `--validate` is passed with the agentic flow off: validation
+ * requires an active agent session by definition.
+ */
+function resolveShouldRunValidation(args) {
+    return args.validate !== false && args.agenticKind === 'enabled';
+}
 async function resolveFlag(input, isInteractive, detected) {
     if (input.agentic === true) {
         if (!isInteractive) {

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

@@ -1,5 +1,18 @@
 import type { AgentId } from './cli-args';
 export type { AgentId };
+/**
+ * Workspace-relative directory holding all migrate-run scratch (handoff
+ * files). Shared by the run-dir layout in `handoff.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.
+ */
+export declare const MIGRATE_RUNS_RELATIVE_DIR = ".nx/migrate-runs";
+export declare function isHandoffGitignoreMigration(m: {
+    package: string;
+    name: string;
+}): boolean;
 /**
  * A coding agent that was found on the user's machine, ready to be spawned.
  *
@@ -78,11 +91,12 @@ export type HandoffOutcome = {
     causeSummary?: string[];
 };
 /**
- * Result of the up-front resolution phase that runs once per `--run-migrations`
- * invocation, before the migration loop. Cached and consulted for every entry.
+ * Result of the up-front resolution phase, run once per run-phase invocation
+ * and applied to every migration it covers.
  *
  * - `inside-agent`: nx detected it is itself running inside another agent;
- *   every agentic step is skipped and prompt migrations go to `nextSteps`.
+ *   every agentic step is skipped and prompt migrations are surfaced for the
+ *   outer agent to apply.
  * - `disabled`: the user opted out (explicit `--agentic=false`, declined the
  *   up-front prompt, or non-TTY without the flag).
  * - `enabled`: the agentic flow runs and `selectedAgent` is the agent it

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

@@ -1,2 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIGRATE_RUNS_RELATIVE_DIR = void 0;
+exports.isHandoffGitignoreMigration = isHandoffGitignoreMigration;
+/**
+ * Workspace-relative directory holding all migrate-run scratch (handoff
+ * files). Shared by the run-dir layout in `handoff.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.
+ */
+exports.MIGRATE_RUNS_RELATIVE_DIR = '.nx/migrate-runs';
+/**
+ * Composite identity of the v23 migration that adds `.nx/migrate-runs` to
+ * `.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.
+ */
+const HANDOFF_GITIGNORE_MIGRATION_PACKAGE = 'nx';
+const HANDOFF_GITIGNORE_MIGRATION_NAME = '23-0-0-add-migrate-runs-to-git-ignore';
+function isHandoffGitignoreMigration(m) {
+    return (m.package === HANDOFF_GITIGNORE_MIGRATION_PACKAGE &&
+        m.name === HANDOFF_GITIGNORE_MIGRATION_NAME);
+}

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

@@ -17,6 +17,7 @@ export type MultiMajorMode = (typeof MULTI_MAJOR_MODES)[number];
 export interface MigrateArgs {
     packageAndVersion?: string;
     runMigrations?: string;
+    runMigration?: string;
     include?: MigrateInclude;
     /**
      * nx.json `migrate.include` default. Consumed by `resolveInclude` only when the
@@ -30,6 +31,8 @@ export interface MigrateArgs {
     commitPrefix?: string;
     agentic?: AgenticArg;
     validate?: boolean;
+    ifExists?: boolean;
+    interactive?: boolean;
     [key: string]: any;
 }
 /**

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

@@ -10,7 +10,8 @@ exports.yargsMigrateCommand = {
     command: 'migrate [packageAndVersion]',
     describe: `Creates a migrations file or runs migrations from the migrations file.
   - Migrate packages and create migrations.json (e.g., nx migrate @nx/workspace@latest)
-  - Run migrations (e.g., nx migrate --run-migrations=migrations.json). Use flag --if-exists to run migrations only if the migrations file exists.`,
+  - Run migrations (e.g., nx migrate --run-migrations=migrations.json). Use flag --if-exists to run migrations only if the migrations file exists.
+  - Run a single migration from migrations.json by id (e.g., nx migrate --run-migration=@nx/js:my-migration).`,
     builder: (yargs) => (0, documentation_1.linkToNxDevAndExamples)(withMigrationOptions(yargs), 'migrate'),
     handler: async () => process.exit(await (await (0, handle_import_1.handleImport)('./migrate.js', __dirname)).runMigration()),
 };
@@ -51,6 +52,10 @@ function withMigrationOptions(yargs) {
         .option('runMigrations', {
         describe: `Execute migrations from a file (when the file isn't provided, execute migrations from migrations.json).`,
         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.",
+        type: 'string',
     })
         .option('ifExists', {
         describe: `Run migrations only if the migrations file exists, if not continues successfully.`,

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

@@ -6,7 +6,7 @@ interface PackageMigrationConfig extends NxMigrationsConfiguration {
     packageGroup: ArrayPackageGroup;
 }
 export declare function readPackageMigrationConfig(packageName: string, dir: string): PackageMigrationConfig;
-export declare function runInstall(nxWorkspaceRoot?: string, phase?: MigrationInstallPhase): Promise<void>;
+export declare function runInstall(nxWorkspaceRoot?: string, phase?: MigrationInstallPhase, rerunCommand?: string): Promise<void>;
 export type MigrationInstallPhase = 'pre-migration' | 'post-migration';
 export declare class NpmPeerDepsInstallError extends Error {
     constructor();
@@ -19,13 +19,16 @@ export declare class NpmPeerDepsInstallError extends Error {
  * captured output.
  */
 export declare function isNpmPeerDepsError(stderr: string): boolean;
-export declare function logNpmPeerDepsError(phase: MigrationInstallPhase): void;
+export declare function formatSingleMigrationRerunCommand(migrationId: string): string;
+export declare function logNpmPeerDepsError(phase: MigrationInstallPhase, rerunCommand?: string): void;
+export declare function logSkippedPostMigrationInstall(root: string): void;
 export declare class ChangedDepInstaller {
     private readonly root;
     private readonly shouldSkipInstall;
+    private readonly rerunCommand?;
     private initialDeps;
     private _skippedInstall;
-    constructor(root: string, shouldSkipInstall?: boolean);
+    constructor(root: string, shouldSkipInstall?: boolean, rerunCommand?: string);
     get skippedInstall(): boolean;
     installDepsIfChanged(): Promise<void>;
 }
@@ -34,13 +37,11 @@ export declare function runNxOrAngularMigration(root: string, migration: {
     name: string;
     description?: string;
     version: string;
-}, isVerbose: boolean, captureGeneratorOutput?: boolean, resolvedCollection?: {
-    collection: MigrationsJson;
-    collectionPath: string;
-}): Promise<{
+}, isVerbose: boolean, captureGeneratorOutput?: boolean, resolvedCollection?: ResolvedMigrationCollection): Promise<{
     changes: FileChange[];
     nextSteps: string[];
     agentContext: string[];
+    skipAgentic: boolean;
     logs: string;
     madeChanges: boolean;
 }>;
@@ -49,17 +50,21 @@ export declare function runNxMigration(root: string, collectionPath: string, col
     changes: FileChange[];
     nextSteps: string[];
     agentContext: string[];
+    skipAgentic: boolean;
     logs: string;
 }>;
 export declare function parseMigrationReturn(value: unknown): {
     nextSteps: string[];
     agentContext: string[];
+    skipAgentic: boolean;
 };
 export declare function filterStrings(value: unknown): string[];
-export declare function readMigrationCollection(packageName: string, root: string): {
+export interface ResolvedMigrationCollection {
     collection: MigrationsJson;
     collectionPath: string;
-};
+}
+export declare function readMigrationCollection(packageName: string, root: string): ResolvedMigrationCollection;
+export declare function resolveDocumentationFileToWorkspacePath(root: string, migrationsDir: string, documentation: string): string | undefined;
 export declare function getImplementationPath(collection: MigrationsJson, collectionPath: string, name: string, migrationVersion?: string): {
     path: string;
     fnSymbol: string;