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

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

@@ -4,13 +4,16 @@ exports.getNgCompatLayer = exports.MigrationImplementationMissingError = exports
 exports.readPackageMigrationConfig = readPackageMigrationConfig;
 exports.runInstall = runInstall;
 exports.isNpmPeerDepsError = isNpmPeerDepsError;
+exports.formatSingleMigrationRerunCommand = formatSingleMigrationRerunCommand;
 exports.logNpmPeerDepsError = logNpmPeerDepsError;
+exports.logSkippedPostMigrationInstall = logSkippedPostMigrationInstall;
 exports.runNxOrAngularMigration = runNxOrAngularMigration;
 exports.getStringifiedPackageJsonDeps = getStringifiedPackageJsonDeps;
 exports.runNxMigration = runNxMigration;
 exports.parseMigrationReturn = parseMigrationReturn;
 exports.filterStrings = filterStrings;
 exports.readMigrationCollection = readMigrationCollection;
+exports.resolveDocumentationFileToWorkspacePath = resolveDocumentationFileToWorkspacePath;
 exports.getImplementationPath = getImplementationPath;
 exports.isAngularMigration = isAngularMigration;
 const tslib_1 = require("tslib");
@@ -27,6 +30,7 @@ const package_manager_1 = require("../../utils/package-manager");
 const output_1 = require("../../utils/output");
 const fs_1 = require("fs");
 const installation_directory_1 = require("../../utils/installation-directory");
+const shell_quoting_1 = require("../../utils/shell-quoting");
 const project_graph_1 = require("../../project-graph/project-graph");
 const version_utils_1 = require("./version-utils");
 function readPackageMigrationConfig(packageName, dir) {
@@ -55,7 +59,7 @@ function readPackageMigrationConfig(packageName, dir) {
         };
     }
 }
-function runInstall(nxWorkspaceRoot, phase = 'pre-migration') {
+function runInstall(nxWorkspaceRoot, phase = 'pre-migration', rerunCommand) {
     const cwd = nxWorkspaceRoot ?? process.cwd();
     const packageManager = (0, package_manager_1.detectPackageManager)(cwd);
     const pmCommands = (0, package_manager_1.getPackageManagerCommand)(packageManager, cwd);
@@ -92,7 +96,7 @@ function runInstall(nxWorkspaceRoot, phase = 'pre-migration') {
                     // (CLI migrate, `nx repair`, single-migration runner, etc.) surfaces
                     // it consistently. Top-level callers catch `NpmPeerDepsInstallError`
                     // and return a non-zero exit code without re-logging.
-                    logNpmPeerDepsError(phase);
+                    logNpmPeerDepsError(phase, rerunCommand);
                     reject(new NpmPeerDepsInstallError());
                     return;
                 }
@@ -124,7 +128,20 @@ function isNpmPeerDepsError(stderr) {
         lowerStderr.includes('could not resolve dependency') ||
         lowerStderr.includes('conflicting peer dependency'));
 }
-function logNpmPeerDepsError(phase) {
+// The single-migration rerun command lands in copyable guidance (see
+// `logNpmPeerDepsError` below), so quote ids a shell would split or expand.
+// Single quotes stay literal in POSIX shells and PowerShell alike; double
+// quotes would leave $-expansion active in both. The embedded-quote escape is
+// the POSIX '\'' sequence, the one character PowerShell disagrees on (it wants
+// ''). cmd.exe is knowingly not covered: it does not group on single quotes,
+// and no quoting suppresses its %VAR% expansion.
+function formatSingleMigrationRerunCommand(migrationId) {
+    const id = (0, shell_quoting_1.needsShellQuoting)(migrationId)
+        ? `'${migrationId.replace(/'/g, String.raw `'\''`)}'`
+        : migrationId;
+    return `nx migrate --run-migration=${id}`;
+}
+function logNpmPeerDepsError(phase, rerunCommand = 'nx migrate --run-migrations') {
     const peerDepsResolutionSteps = [
         'Recommended approaches (in order of preference):',
         '',
@@ -138,7 +155,7 @@ function logNpmPeerDepsError(phase) {
     ];
     const manualInstallHint = [
         'If you installed the dependencies manually, pass "--skip-install" to avoid re-installing them:',
-        '   nx migrate --run-migrations --skip-install',
+        `   ${rerunCommand} --skip-install`,
     ];
     if (phase === 'pre-migration') {
         output_1.output.error({
@@ -146,8 +163,8 @@ function logNpmPeerDepsError(phase) {
             bodyLines: [
                 ...peerDepsResolutionSteps,
                 '',
-                'Once the conflicts are resolved, re-run the migrations:',
-                '   nx migrate --run-migrations',
+                'Once the conflicts are resolved, re-run the migration command:',
+                `   ${rerunCommand}`,
                 '',
                 ...manualInstallHint,
             ],
@@ -160,18 +177,27 @@ function logNpmPeerDepsError(phase) {
                 ...peerDepsResolutionSteps,
                 '',
                 'Once the conflicts are resolved, run "npm install" to install the updated dependencies.',
-                'If the migration was interrupted before completing, re-run the remaining migrations:',
-                '   nx migrate --run-migrations',
+                'If the migration run was interrupted before completing, re-run it:',
+                `   ${rerunCommand}`,
                 '',
                 ...manualInstallHint,
             ],
         });
     }
 }
+function logSkippedPostMigrationInstall(root) {
+    const packageManager = (0, package_manager_1.detectPackageManager)(root);
+    const installCommand = (0, package_manager_1.getPackageManagerCommand)(packageManager, root).install;
+    output_1.output.warn({
+        title: 'Migrations updated your dependencies, but the install was skipped',
+        bodyLines: [`Run "${installCommand}" to install the updated dependencies.`],
+    });
+}
 class ChangedDepInstaller {
-    constructor(root, shouldSkipInstall = false) {
+    constructor(root, shouldSkipInstall = false, rerunCommand) {
         this.root = root;
         this.shouldSkipInstall = shouldSkipInstall;
+        this.rerunCommand = rerunCommand;
         this._skippedInstall = false;
         this.initialDeps = getStringifiedPackageJsonDeps(root);
     }
@@ -185,7 +211,7 @@ class ChangedDepInstaller {
                 this._skippedInstall = true;
             }
             else {
-                await runInstall(this.root, 'post-migration');
+                await runInstall(this.root, 'post-migration', this.rerunCommand);
             }
         }
         this.initialDeps = currentDeps;
@@ -197,6 +223,8 @@ async function runNxOrAngularMigration(root, migration, isVerbose, captureGenera
     let changes = [];
     let nextSteps = [];
     let agentContext = [];
+    // Angular schematics have no return channel, so they can never waive it.
+    let skipAgentic = false;
     let logs = '';
     // Angular's `ngResult.changes` is synthesized from the schematic's
     // DryRunEvent stream so Nx and Angular paths can share commit/validation
@@ -204,7 +232,8 @@ async function runNxOrAngularMigration(root, migration, isVerbose, captureGenera
     let madeChanges = false;
     logger_1.logger.info(pc.dim('→ Running generator…'));
     if (!isAngularMigration(collection, migration.name)) {
-        ({ nextSteps, changes, agentContext, logs } = await runNxMigration(root, collectionPath, collection, migration.name, migration.version, captureGeneratorOutput));
+        ({ nextSteps, changes, agentContext, skipAgentic, logs } =
+            await runNxMigration(root, collectionPath, collection, migration.name, migration.version, captureGeneratorOutput));
         madeChanges = changes.length > 0;
         logger_1.logger.info(`Ran ${migration.name} from ${migration.package}`);
         if (migration.description) {
@@ -213,7 +242,14 @@ async function runNxOrAngularMigration(root, migration, isVerbose, captureGenera
         logger_1.logger.info('');
         if (!madeChanges) {
             logger_1.logger.info(`No changes were made\n`);
-            return { changes, nextSteps, agentContext, logs, madeChanges };
+            return {
+                changes,
+                nextSteps,
+                agentContext,
+                skipAgentic,
+                logs,
+                madeChanges,
+            };
         }
         logger_1.logger.info('Changes:');
         (0, tree_1.printChanges)(changes, '  ');
@@ -233,13 +269,20 @@ async function runNxOrAngularMigration(root, migration, isVerbose, captureGenera
         logger_1.logger.info('');
         if (!madeChanges) {
             logger_1.logger.info(`No changes were made\n`);
-            return { changes, nextSteps, agentContext, logs, madeChanges };
+            return {
+                changes,
+                nextSteps,
+                agentContext,
+                skipAgentic,
+                logs,
+                madeChanges,
+            };
         }
         logger_1.logger.info('Changes:');
         ngResult.loggingQueue.forEach((log) => logger_1.logger.info('  ' + log));
         logger_1.logger.info('');
     }
-    return { changes, nextSteps, agentContext, logs, madeChanges };
+    return { changes, nextSteps, agentContext, skipAgentic, logs, madeChanges };
 }
 function getStringifiedPackageJsonDeps(root) {
     try {
@@ -265,25 +308,31 @@ async function runNxMigration(root, collectionPath, collection, name, migrationV
     else {
         result = await fn(host, {});
     }
-    const { nextSteps, agentContext } = parseMigrationReturn(result);
+    const { nextSteps, agentContext, skipAgentic } = parseMigrationReturn(result);
     host.lock();
     const changes = host.listChanges();
     (0, tree_1.flushChanges)(root, changes);
-    return { changes, nextSteps, agentContext, logs };
+    return { changes, nextSteps, agentContext, skipAgentic, logs };
 }
 function parseMigrationReturn(value) {
     if (Array.isArray(value)) {
-        return { nextSteps: filterStrings(value), agentContext: [] };
+        return {
+            nextSteps: filterStrings(value),
+            agentContext: [],
+            skipAgentic: false,
+        };
     }
     if (value && typeof value === 'object') {
         const obj = value;
         return {
             nextSteps: filterStrings(obj.nextSteps),
             agentContext: filterStrings(obj.agentContext),
+            // Strict, so a truthy non-boolean can't opt a migration out of its AI step.
+            skipAgentic: obj.skipAgentic === true,
         };
     }
     // Catches `void`, mistakenly-returned generator callbacks, malformed values.
-    return { nextSteps: [], agentContext: [] };
+    return { nextSteps: [], agentContext: [], skipAgentic: false };
 }
 // Bucket-level tolerance: a single non-string entry shouldn't discard the
 // whole `nextSteps` / `agentContext` array. Migration authors occasionally
@@ -303,6 +352,21 @@ function readMigrationCollection(packageName, root) {
         collectionPath,
     };
 }
+// Workspace-relative because the agent runs with cwd at the workspace root;
+// absolute only for layouts that resolve outside it (hoisted/symlinked).
+function resolveDocumentationFileToWorkspacePath(root, migrationsDir, documentation) {
+    let documentationFile;
+    try {
+        documentationFile = require.resolve(documentation, {
+            paths: [migrationsDir],
+        });
+    }
+    catch {
+        return undefined;
+    }
+    const relativePath = (0, path_1.relative)(root, documentationFile);
+    return relativePath.startsWith('..') ? documentationFile : relativePath;
+}
 function getImplementationPath(collection, collectionPath, name, migrationVersion) {
     const g = collection.generators?.[name] || collection.schematics?.[name];
     if (!g) {

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

@@ -67,5 +67,12 @@ export declare function reportMigrateRunError(opts: {
     migrationCount?: number;
     error?: unknown;
 }): void;
+/**
+ * Counts invocations, not completions: emitted as soon as the migration id
+ * resolves, while the worker can still stop before running anything.
+ */
+export declare function reportMigrateSingleMigrationInvocation(opts: {
+    migrationType: 'generator' | 'prompt' | 'hybrid';
+}): 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

@@ -11,6 +11,7 @@ exports.reportMigrateRunStart = reportMigrateRunStart;
 exports.hasMigrateRunStarted = hasMigrateRunStarted;
 exports.reportMigrateRunComplete = reportMigrateRunComplete;
 exports.reportMigrateRunError = reportMigrateRunError;
+exports.reportMigrateSingleMigrationInvocation = reportMigrateSingleMigrationInvocation;
 exports.computeMajorsCrossed = computeMajorsCrossed;
 exports.safeReport = safeReport;
 const semver_1 = require("semver");
@@ -180,6 +181,19 @@ function reportMigrateRunError(opts) {
         });
     });
 }
+/**
+ * Counts invocations, not completions: emitted as soon as the migration id
+ * resolves, while the worker can still stop before running anything.
+ */
+function reportMigrateSingleMigrationInvocation(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_single_migration_invocation', {
+            [analytics_1.customDimensions.promptChoice]: opts.migrationType,
+        });
+    });
+}
 // `_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,3 +1,4 @@
+import type { ResolvedAgentic } from './agentic/types';
 /**
  * Discriminated result for `commitMigrationIfRequested`. Distinguishes the
  * shapes the executor needs to react to:
@@ -23,21 +24,20 @@ export type CommitResult = {
     status: 'disabled';
 };
 /**
- * Creates a per-migration commit when `shouldCreateCommits` is true.
+ * `pendingMigrations` are listed in the commit body so a `git log -p` reader
+ * can see which earlier migrations' diffs this commit absorbed (their own
+ * commits failed and `git add -A` picked their working-tree state up too).
  *
- * When `pendingMigrations` is non-empty, the commit message body lists
- * those entries so a reader of `git log -p` can see which prior migrations'
- * diffs were absorbed into this commit (because their own commits failed and
- * `git add -A` here captured their working-tree state too). Each entry is
- * rendered as `<package>: <name>` for unambiguous attribution across
- * packages.
+ * 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.
  */
 export declare function commitMigrationIfRequested(root: string, migration: {
     name: string;
 }, shouldCreateCommits: boolean, commitPrefix: string, installDepsIfChanged: () => Promise<void>, pendingMigrations?: ReadonlyArray<{
     package: string;
     name: string;
-}>): Promise<CommitResult>;
+}>, failureGuidance?: string): 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
@@ -48,3 +48,27 @@ export declare function commitMigrationIfRequested(root: string, migration: {
  * 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;
+    agenticKind: ResolvedAgentic['kind'];
+    isGitRepo: boolean;
+    commitPrefixIsCustom?: boolean;
+}): {
+    effective: boolean;
+    agenticHasDiffContext: boolean;
+    warning?: string;
+    error?: string;
+};
+/**
+ * Callers gate this on commits being effective and on prompting being
+ * possible, so non-interactive runs (CI, `--no-interactive`) never reach here.
+ */
+export declare function confirmCommitsOnDefaultBranch(args: {
+    currentBranch: string | null;
+    defaultBranch: string | null;
+}): Promise<boolean>;

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

@@ -2,22 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.commitMigrationIfRequested = commitMigrationIfRequested;
 exports.commitCheckpointBeforeMigrations = commitCheckpointBeforeMigrations;
+exports.resolveCreateCommits = resolveCreateCommits;
+exports.confirmCommitsOnDefaultBranch = confirmCommitsOnDefaultBranch;
 const tslib_1 = require("tslib");
 const pc = tslib_1.__importStar(require("picocolors"));
 const git_utils_1 = require("../../utils/git-utils");
 const logger_1 = require("../../utils/logger");
 const output_1 = require("../../utils/output");
+const safe_prompt_1 = require("./safe-prompt");
 /**
- * Creates a per-migration commit when `shouldCreateCommits` is true.
+ * `pendingMigrations` are listed in the commit body so a `git log -p` reader
+ * can see which earlier migrations' diffs this commit absorbed (their own
+ * commits failed and `git add -A` picked their working-tree state up too).
  *
- * When `pendingMigrations` is non-empty, the commit message body lists
- * those entries so a reader of `git log -p` can see which prior migrations'
- * diffs were absorbed into this commit (because their own commits failed and
- * `git add -A` here captured their working-tree state too). Each entry is
- * rendered as `<package>: <name>` for unambiguous attribution across
- * packages.
+ * 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.
  */
-async function commitMigrationIfRequested(root, migration, shouldCreateCommits, commitPrefix, installDepsIfChanged, pendingMigrations = []) {
+async function commitMigrationIfRequested(root, migration, shouldCreateCommits, commitPrefix, installDepsIfChanged, pendingMigrations = [], failureGuidance = 'The next successful commit will absorb it and reference this migration in its body; if no later commit lands, the end-of-run output will list this migration so you can commit or revert manually.') {
     if (!shouldCreateCommits)
         return { status: 'disabled' };
     await installDepsIfChanged();
@@ -39,7 +41,7 @@ async function commitMigrationIfRequested(root, migration, shouldCreateCommits,
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
-        logger_1.logger.info(pc.red(`Could not create a commit for ${migration.name}:\n${reason}\nThe migration's diff remains in the working tree; inspect with \`git status\` / \`git diff\` to review. The next successful commit will absorb it and reference this migration in its body; if no later commit lands, the end-of-run output will list this migration so you can commit or revert manually.`));
+        logger_1.logger.info(pc.red(`Could not create a commit for ${migration.name}:\n${reason}\nThe migration's diff remains in the working tree; inspect with \`git status\` / \`git diff\` to review. ${failureGuidance}`));
         return { status: 'failed', reason };
     }
 }
@@ -100,3 +102,69 @@ function commitCheckpointBeforeMigrations(root, commitPrefix) {
         });
     }
 }
+/**
+ * `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.
+ */
+function resolveCreateCommits(args) {
+    const { createCommits, agenticKind, isGitRepo, commitPrefixIsCustom } = args;
+    if (createCommits === true && !isGitRepo) {
+        return {
+            effective: false,
+            agenticHasDiffContext: false,
+            error: '`--create-commits` requires a git repository. Run `git init` first, or omit the flag.',
+        };
+    }
+    if (agenticKind === 'enabled') {
+        if (createCommits === false) {
+            return {
+                effective: false,
+                agenticHasDiffContext: false,
+                warning: "--no-create-commits was passed alongside --agentic. Without per-migration commits, the agent can't isolate the current migration's changes from earlier migrations in this run. Drop --no-create-commits for accurate per-migration review." +
+                    (commitPrefixIsCustom
+                        ? ' Note: the custom --commit-prefix value will have no effect because commits are disabled.'
+                        : ''),
+            };
+        }
+        // Not an error like the explicit `--create-commits` branch above: the
+        // agentic default was never asked for, so degrade instead.
+        if (!isGitRepo) {
+            return {
+                effective: false,
+                agenticHasDiffContext: false,
+                warning: '`--agentic` enables per-migration commits by default, but the workspace is not a git repository. Continuing without commits, so the agent will not receive per-file diff context. Run `git init` to enable.' +
+                    (commitPrefixIsCustom
+                        ? ' The custom --commit-prefix value will have no effect.'
+                        : ''),
+            };
+        }
+        return { effective: true, agenticHasDiffContext: true };
+    }
+    return {
+        effective: createCommits === true,
+        agenticHasDiffContext: false,
+        warning: commitPrefixIsCustom && createCommits !== true
+            ? 'A custom migrate commit prefix is configured, but commits are not enabled for this run, so it has no effect. Set `migrate.createCommits` to `true` (or pass `--create-commits`) to create a commit per migration.'
+            : undefined,
+    };
+}
+/**
+ * Callers gate this on commits being effective and on prompting being
+ * possible, so non-interactive runs (CI, `--no-interactive`) never reach here.
+ */
+async function confirmCommitsOnDefaultBranch(args) {
+    const { currentBranch, defaultBranch } = args;
+    if (!currentBranch || !defaultBranch || currentBranch !== defaultBranch) {
+        return true;
+    }
+    const { proceed } = await (0, safe_prompt_1.migratePrompt)([
+        {
+            name: 'proceed',
+            type: 'confirm',
+            message: `You're on the default branch '${currentBranch}'. nx migrate will create a commit for each migration on this branch. Continue?`,
+            initial: false,
+        },
+    ]);
+    return proceed;
+}

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

@@ -1,20 +1,19 @@
 import type { NxMigrateConfiguration } from '../../config/nx-json';
 import { type MigrateArgs } from './command-object';
 /**
- * Overlays `nx.json` `migrate` defaults onto the raw `nx migrate` CLI args so a
- * CLI flag always wins, then `nx.json`, then the built-in default. Returns a new
- * args object; the input is not mutated.
+ * Overlays `nx.json` `migrate` defaults onto the raw CLI args: a CLI flag wins,
+ * then `nx.json`, then the built-in default. Returns a new args object; the
+ * input is not mutated.
  *
- * Phase-aware: generate-only options (`include`, `multiMajorMode`) are applied only
- * when not running migrations; run-only options (`createCommits`,
- * `commitPrefix`, `agentic`, `validate`) only when running migrations. This
- * mirrors where each option is consumed and avoids tripping the "cannot be
- * combined with --run-migrations" guards in `parseMigrationsOptions`.
+ * Phase-aware so each option is only filled where it is consumed, and so a
+ * config value never trips the mutually-exclusive-flag guards in
+ * `parseMigrationsOptions`: `include` and `multiMajorMode` in the generate
+ * phase only, `agentic` / `validate` / `createCommits` / `commitPrefix` when
+ * running the whole migrations file or a single migration.
  *
- * `include` is carried as `includeFromConfig` rather than `include` so it is never
- * mistaken for an explicit `--include`: `resolveInclude` applies it only when the
- * resolved target supports optional updates, leaving targets that don't opt in
- * unaffected.
+ * `include` is carried as `includeFromConfig` so it is never mistaken for an
+ * explicit `--include`: `resolveInclude` applies it only when the resolved
+ * target supports optional updates.
  */
 export declare function applyNxJsonMigrateDefaults(args: MigrateArgs, migrateConfig: NxMigrateConfiguration | undefined, env?: NodeJS.ProcessEnv): MigrateArgs;
 /**

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

@@ -6,20 +6,19 @@ const cli_args_1 = require("./agentic/cli-args");
 const command_object_1 = require("./command-object");
 const MULTI_MAJOR_MODE_ENV = 'NX_MULTI_MAJOR_MODE';
 /**
- * Overlays `nx.json` `migrate` defaults onto the raw `nx migrate` CLI args so a
- * CLI flag always wins, then `nx.json`, then the built-in default. Returns a new
- * args object; the input is not mutated.
+ * Overlays `nx.json` `migrate` defaults onto the raw CLI args: a CLI flag wins,
+ * then `nx.json`, then the built-in default. Returns a new args object; the
+ * input is not mutated.
  *
- * Phase-aware: generate-only options (`include`, `multiMajorMode`) are applied only
- * when not running migrations; run-only options (`createCommits`,
- * `commitPrefix`, `agentic`, `validate`) only when running migrations. This
- * mirrors where each option is consumed and avoids tripping the "cannot be
- * combined with --run-migrations" guards in `parseMigrationsOptions`.
+ * Phase-aware so each option is only filled where it is consumed, and so a
+ * config value never trips the mutually-exclusive-flag guards in
+ * `parseMigrationsOptions`: `include` and `multiMajorMode` in the generate
+ * phase only, `agentic` / `validate` / `createCommits` / `commitPrefix` when
+ * running the whole migrations file or a single migration.
  *
- * `include` is carried as `includeFromConfig` rather than `include` so it is never
- * mistaken for an explicit `--include`: `resolveInclude` applies it only when the
- * resolved target supports optional updates, leaving targets that don't opt in
- * unaffected.
+ * `include` is carried as `includeFromConfig` so it is never mistaken for an
+ * explicit `--include`: `resolveInclude` applies it only when the resolved
+ * target supports optional updates.
  */
 function applyNxJsonMigrateDefaults(args, migrateConfig, env = process.env) {
     if (!migrateConfig) {
@@ -29,7 +28,8 @@ function applyNxJsonMigrateDefaults(args, migrateConfig, env = process.env) {
     // `--run-migrations` with no value is normalized to '' by yargs, so a defined
     // (even empty-string) value means we're in the run-migrations phase.
     const isRunMigrations = merged.runMigrations !== undefined;
-    if (isRunMigrations) {
+    const isSingleMigration = merged.runMigration !== undefined;
+    if (isRunMigrations || isSingleMigration) {
         if (merged.createCommits === undefined &&
             migrateConfig.createCommits !== undefined) {
             assertType(migrateConfig.createCommits, 'boolean', 'createCommits');
@@ -53,7 +53,7 @@ function applyNxJsonMigrateDefaults(args, migrateConfig, env = process.env) {
             merged.validate = migrateConfig.validate;
         }
     }
-    else {
+    if (!isRunMigrations && !isSingleMigration) {
         if (merged.include === undefined && migrateConfig.include !== undefined) {
             assertOneOf(migrateConfig.include, command_object_1.MIGRATE_INCLUDE_VALUES, 'include');
             merged.includeFromConfig = migrateConfig.include;

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

@@ -1,11 +1,10 @@
 /**
- * Presentation layer for `nx migrate --run-migrations`. Pure helpers — every
- * function maps (state) → (terminal output or string lines). Shared visual
- * vocabulary across the migrate run:
- *   `→` start  ·  `✓` success  ·  `✗` failure  ·  `↷` skipped  ·  `ℹ` info  ·  `─` boundary
+ * Pure presentation helpers for the migrate run phase (`--run-migrations` and
+ * the single-migration worker). Shared glyph vocabulary:
+ *   `→` start, `✓` success, `✗` failure, `↷` skipped, `ℹ` info, `─` boundary
  *
  * Inputs are typed structurally (e.g. `{ name: string }[]`) so this module
- * stays decoupled from `ExecutableMigration` and the executor in migrate.ts.
+ * stays decoupled from the migration executor in migrate.ts.
  */
 /**
  * Some agent TUIs (codex, opencode) don't fully reset their cursor / SGR state
@@ -24,6 +23,22 @@ export declare function logMigrationBoundary(index: number, total: number, pkg:
  *   ✓ <label>[ (<sha>)]: <summary>
  */
 export declare function logAgenticSuccessOutcome(label: string, sha: string | null, summary: string): void;
+/**
+ * Logs the skip line for a migration that waived its AI step through
+ * `skipAgentic`, plus a verbose note for any `agentContext` the waiver
+ * dropped. A hybrid waives its paired prompt; a generator-only migration
+ * waives the validation pass, so callers must reach here only once they know
+ * one was on the table. Under `inside-agent` only a hybrid can, so the
+ * hand-off dropped alongside is always a prompt's; a waived generator-only
+ * migration keeps its own. The note is author-facing, hence `--verbose`.
+ */
+export declare function logWaivedAgenticStep(migration: {
+    package: string;
+    name: string;
+    prompt?: string;
+    implementation?: string;
+    factory?: string;
+}, agentContext: string[]): void;
 /**
  * Per-migration outcome record consumed by the failure recap. One entry is
  * appended per iteration that returned without throwing; the failing migration
@@ -80,6 +95,13 @@ export type CommitState = {
  * means the migration threw before completing — the executor's catch block
  * records it so the recap can list it under retained-state alongside any
  * other migrations whose commits never landed.
+ *
+ * `waivedAgenticStep` is set when the migration returned `skipAgentic: true`
+ * and something was actually waived: a hybrid's prompt, which is owed in every
+ * agentic mode, or a generator-only migration's validation step, only when it
+ * would have run. Recorded here rather than counted in the executor so the
+ * success tally and the failure recap derive the same number from the same
+ * records instead of threading a counter through both.
  */
 export type MigrationOutcome = {
     migration: {
@@ -89,6 +111,7 @@ export type MigrationOutcome = {
     status: 'completed';
     kind: MigrationOutcomeKind;
     commit: CommitState;
+    waivedAgenticStep?: boolean;
 } | {
     migration: {
         package: string;
@@ -106,6 +129,18 @@ export type MigrationOutcome = {
  * counted because the absorbing commit's record already contributes one.
  */
 export declare function countLandedCommits(outcomes: ReadonlyArray<MigrationOutcome>): number;
+/**
+ * Counts the migrations that waived the AI step they would otherwise have
+ * run. Shared by the success tally and the failure recap so the two can't
+ * report different numbers.
+ */
+export declare function countWaivedAgenticSteps(outcomes: ReadonlyArray<MigrationOutcome>): number;
+/**
+ * The recap phrase for waived AI steps. "not needed" rather than
+ * "skipped"/"deferred", which both recaps reserve for work the user still
+ * owes.
+ */
+export declare function formatWaivedAgenticSteps(count: number): string;
 /**
  * Migrations whose own commit attempt failed and whose diff was never
  * absorbed by a later commit. Surfaces what the user has to commit or
@@ -144,17 +179,20 @@ export declare function logFailureRecap(opts: {
  * emitting a misleading `0 prompt migrations skipped.` line.
  *
  * Rule (kept coherent across every scenario):
- * - When at least one migration was applied: `<N> migrations applied, <K> commits created[, <D> prompt migrations <skipped|deferred>]`.
+ * - When at least one migration was applied: `<N> migrations applied, <K> commits created[, <D> prompt migrations <skipped|deferred>][, <W> AI steps not needed]`.
  *   The `<K> commits created` part stays even at 0 — it tells the reader work
  *   was applied but not committed (the J4/J8 information made explicit).
  * - When zero migrations were applied but some prompt halves were
- *   skipped/deferred: `<D> prompt migrations <skipped|deferred>` only.
+ *   skipped/deferred: `<D> prompt migrations <skipped|deferred>` only. Waiving
+ *   never adds to `skippedPromptsCount`, so `appliedCount` is non-zero whenever
+ *   `waivedAgenticStepsCount` is, and this branch can't be reached with one.
  * - When zero of either: no body line.
  */
 export declare function buildTallyBodyLine(opts: {
     appliedCount: number;
     committedShasCount: number;
     skippedPromptsCount: number;
+    waivedAgenticStepsCount: number;
     insideAgent: boolean;
 }): string | null;
 /**