nx 23.0.0-beta.21 → 23.0.0-beta.22

package/dist/src/adapter/compat.d.ts

@@ -1,2 +1,2 @@
 export declare const allowedProjectExtensions: readonly ["tags", "implicitDependencies", "configFilePath", "$schema", "generators", "namedInputs", "name", "files", "root", "sourceRoot", "projectType", "release", "includedScripts", "metadata", "owners", "nxCloudImplicitDependencies"];
-export declare const allowedWorkspaceExtensions: readonly ["$schema", "implicitDependencies", "affected", "defaultBase", "tasksRunnerOptions", "workspaceLayout", "plugins", "targetDefaults", "files", "generators", "namedInputs", "extends", "cli", "pluginsConfig", "defaultProject", "installation", "release", "nxCloudAccessToken", "nxCloudId", "nxCloudUrl", "nxCloudEncryptionKey", "parallel", "cacheDirectory", "useDaemonProcess", "useInferencePlugins", "neverConnectToCloud", "analytics", "sync", "useLegacyCache", "maxCacheSize", "tui", "owners"];
+export declare const allowedWorkspaceExtensions: readonly ["$schema", "implicitDependencies", "affected", "defaultBase", "tasksRunnerOptions", "workspaceLayout", "plugins", "targetDefaults", "files", "generators", "namedInputs", "extends", "cli", "pluginsConfig", "defaultProject", "installation", "release", "nxCloudAccessToken", "nxCloudId", "nxCloudUrl", "nxCloudEncryptionKey", "parallel", "cacheDirectory", "useDaemonProcess", "useInferencePlugins", "neverConnectToCloud", "analytics", "sync", "migrate", "useLegacyCache", "maxCacheSize", "tui", "owners"];

package/dist/src/adapter/compat.js

@@ -66,6 +66,7 @@ exports.allowedWorkspaceExtensions = [
     'neverConnectToCloud',
     'analytics',
     'sync',
+    'migrate',
     'useLegacyCache',
     'maxCacheSize',
     'tui',

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

@@ -356,19 +356,19 @@ exports.examples = {
             description: 'Prints the specified + inferred configuration for `my-app:build`',
         },
         {
-            command: 'show target my-app:build inputs',
+            command: 'show target inputs my-app:build',
             description: 'Prints the resolved inputs for `my-app:build`',
         },
         {
-            command: 'show target my-app:build inputs --check packages/my-app/index.html',
+            command: 'show target inputs my-app:build --check packages/my-app/index.html',
             description: 'Checks if `packages/my-app/index.html` is an input for `my-app:build`',
         },
         {
-            command: 'show target my-app:build outputs',
+            command: 'show target outputs my-app:build',
             description: 'Prints the outputs detected on disk for `my-app:build`',
         },
         {
-            command: 'show target my-app:build outputs --check packages/my-app/dist/index.html',
+            command: 'show target outputs my-app:build --check packages/my-app/dist/index.html',
             description: 'Checks if `packages/my-app/dist/index.html` is an output for `my-app:build`',
         },
     ],

package/dist/src/command-line/migrate/agentic/prompts/generic-validation.d.ts

@@ -6,6 +6,11 @@ export interface GenericValidationPromptContext {
     description?: string;
     /** Absolute path the agent must write its handoff file to. */
     handoffFileAbsolutePath: string;
+    /**
+     * Path to the migration's documentation file, if any - workspace-relative,
+     * or absolute when it resolves outside the workspace.
+     */
+    documentationPath?: string;
     /** Context captured from the deterministic generator phase. */
     impl: {
         /** Raw output from the generator (devkit logger + console). */

package/dist/src/command-line/migrate/agentic/prompts/generic-validation.js

@@ -29,6 +29,7 @@ function buildGenericValidationUserPrompt(ctx) {
         `You are validating the output of an Nx migration's deterministic generator phase. The generator has already run; inspect what it produced, verify the workspace is in a consistent state for what this migration intended to accomplish, apply any minor in-scope fixes the generator should have produced cleanly, and report findings.`,
         ...(0, shared_rendering_1.renderMigrationBlock)(ctx),
     ];
+    lines.push(...(0, shared_rendering_1.renderMigrationDocumentationBlock)(ctx.documentationPath));
     const logs = (0, shared_rendering_1.escapeXmlBody)((0, shared_rendering_1.stripAnsi)(ctx.impl.logs ?? '').trim());
     lines.push(...(0, shared_rendering_1.renderGeneratorOutputBlock)(logs));
     if (!ctx.impl.hasDiffContext && ctx.impl.changes.length > 0) {

package/dist/src/command-line/migrate/agentic/prompts/hybrid-prompt-migration.d.ts

@@ -8,6 +8,11 @@ export interface HybridPromptMigrationContext {
     promptPath: string;
     /** Absolute path the agent must write its handoff file to. */
     handoffFileAbsolutePath: string;
+    /**
+     * Path to the migration's documentation file, if any - workspace-relative,
+     * or absolute when it resolves outside the workspace.
+     */
+    documentationPath?: string;
     /** Context captured from the deterministic generator phase. */
     impl?: {
         /** Raw output from the generator (devkit logger + console). */

package/dist/src/command-line/migrate/agentic/prompts/hybrid-prompt-migration.js

@@ -20,6 +20,7 @@ function buildHybridPromptUserPrompt(ctx) {
         `Complete the AI-driven step that follows the generator phase of a two-phase Nx migration. The deterministic generator phase has already run; the sections below summarize what it did. The step may apply additional changes, verify the generator's output, or both — follow the instructions file.`,
         ...(0, shared_rendering_1.renderMigrationBlock)(ctx),
     ];
+    lines.push(...(0, shared_rendering_1.renderMigrationDocumentationBlock)(ctx.documentationPath));
     const logs = (0, shared_rendering_1.escapeXmlBody)((0, shared_rendering_1.stripAnsi)(ctx.impl?.logs ?? '').trim());
     const agentContext = (0, shared_rendering_1.filterNonEmptyStrings)(ctx.impl?.agentContext ?? []);
     const hasDiffContext = !!ctx.impl?.hasDiffContext;

package/dist/src/command-line/migrate/agentic/prompts/prompt-migration.d.ts

@@ -7,6 +7,11 @@ export interface PromptMigrationContext {
     promptPath: string;
     /** Absolute path the agent must write its handoff file to. */
     handoffFileAbsolutePath: string;
+    /**
+     * Path to the migration's documentation file, if any - workspace-relative,
+     * or absolute when it resolves outside the workspace.
+     */
+    documentationPath?: string;
 }
 /**
  * Builds the first user-facing message for a prompt-migration step.

package/dist/src/command-line/migrate/agentic/prompts/prompt-migration.js

@@ -16,6 +16,7 @@ function buildPromptMigrationUserPrompt(ctx) {
     const lines = [
         `Apply one prompt-based migration to this Nx workspace.`,
         ...(0, shared_rendering_1.renderMigrationBlock)(ctx),
+        ...(0, shared_rendering_1.renderMigrationDocumentationBlock)(ctx.documentationPath),
         ``,
         `<instructions_file>${(0, shared_rendering_1.escapeXmlBody)(ctx.promptPath)}</instructions_file>`,
         ``,

package/dist/src/command-line/migrate/agentic/prompts/shared-rendering.d.ts

@@ -16,3 +16,4 @@ export interface MigrationBlockContext {
 export declare function renderMigrationBlock(ctx: MigrationBlockContext): string[];
 export declare function renderHandoffPathFooter(handoffFileAbsolutePath: string): string[];
 export declare function renderAdvisoryContext(note: string, entries: string[]): string[];
+export declare function renderMigrationDocumentationBlock(documentationPath: string | undefined): string[];

package/dist/src/command-line/migrate/agentic/prompts/shared-rendering.js

@@ -11,6 +11,7 @@ exports.renderGeneratorOutputBlock = renderGeneratorOutputBlock;
 exports.renderMigrationBlock = renderMigrationBlock;
 exports.renderHandoffPathFooter = renderHandoffPathFooter;
 exports.renderAdvisoryContext = renderAdvisoryContext;
+exports.renderMigrationDocumentationBlock = renderMigrationDocumentationBlock;
 function renderFileEntry(change) {
     return `[${change.type}] ${change.path}`;
 }
@@ -128,3 +129,17 @@ function renderAdvisoryContext(note, entries) {
         `</advisory_context>`,
     ];
 }
+// Points the agent at the migration's documentation file (reference, not
+// instructions). Returns `[]` when there's no doc so callers can spread without
+// guarding; the path is escaped like other user-authored values interpolated
+// into the prompt.
+function renderMigrationDocumentationBlock(documentationPath) {
+    if (!documentationPath)
+        return [];
+    return [
+        ``,
+        `<migration_documentation note="reference: documents what this migration does; read this file if you need more context on its intent, not as instructions">`,
+        escapeXmlBody(documentationPath),
+        `</migration_documentation>`,
+    ];
+}

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

@@ -31,6 +31,13 @@ export interface RunAgenticPromptStepInput {
         description?: string;
         prompt?: string;
     };
+    /**
+     * Path to the migration's documentation file, resolved by the orchestrator -
+     * workspace-relative, or absolute when the file resolves outside the
+     * workspace. Omitted when the migration declares no `documentation` or it
+     * can't be resolved.
+     */
+    documentationPath?: string;
     agentic: EnabledResolvedAgentic;
     runDir: string;
     installDepsIfChanged: () => Promise<void>;

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

@@ -27,7 +27,7 @@ const runner_1 = require("./runner");
  * the file free of cross-imports with the orchestrator.
  */
 async function runAgenticPromptStep(input) {
-    const { root, migration, agentic, runDir, installDepsIfChanged, implContext, mode = 'author', } = input;
+    const { root, migration, agentic, runDir, installDepsIfChanged, implContext, documentationPath, mode = 'author', } = input;
     const handoffFilePath = (0, handoff_1.stepHandoffPath)(runDir, migration);
     // The system prompt tells the agent the parent dir exists, so the agent
     // doesn't defensively `mkdir -p` (which triggers a workspace-permission
@@ -52,6 +52,7 @@ async function runAgenticPromptStep(input) {
             version: migration.version,
             description: migration.description,
             handoffFileAbsolutePath: handoffFilePath,
+            documentationPath,
             impl: implContext,
         });
     }
@@ -63,6 +64,7 @@ async function runAgenticPromptStep(input) {
             description: migration.description,
             promptPath: migration.prompt,
             handoffFileAbsolutePath: handoffFilePath,
+            documentationPath,
         };
         userPrompt = implContext
             ? (0, hybrid_prompt_migration_1.buildHybridPromptUserPrompt)({ ...promptCtx, impl: implContext })

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

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveAgentic = resolveAgentic;
+const fs_1 = require("fs");
+const jsonc_parser_1 = require("jsonc-parser");
+const path_1 = require("path");
 const output_1 = require("../../../utils/output");
+const workspace_root_1 = require("../../../utils/workspace-root");
 const safe_prompt_1 = require("../safe-prompt");
 const detect_installed_1 = require("./detect-installed");
 const inception_1 = require("./inception");
@@ -32,20 +36,35 @@ async function resolveAgentic(input) {
         return { kind: 'disabled' };
     }
     const detected = await (0, detect_installed_1.detectInstalledAgents)(definitions_1.AGENT_DEFINITIONS);
-    const { enabled, explicitId } = await resolveFlag(input, isInteractive, detected);
+    const { enabled, explicitId, persist } = await resolveFlag(input, isInteractive, detected);
     if (!enabled) {
+        if (persist === false) {
+            persistAgenticChoice(false);
+        }
         return { kind: 'disabled' };
     }
     const selected = await selectAgent(detected, explicitId, isInteractive);
+    if (persist === true) {
+        persistAgenticChoice(true);
+    }
+    else if (persist === 'pin') {
+        persistAgenticChoice(selected.id);
+    }
     return { kind: 'enabled', selectedAgent: selected };
 }
 async function resolveFlag(input, isInteractive, detected) {
     if (input.agentic === true) {
-        requireInteractiveOrAbort(isInteractive);
+        if (!isInteractive) {
+            warnAgenticInteractiveOnly();
+            return { enabled: false };
+        }
         return { enabled: true };
     }
     if (typeof input.agentic === 'string') {
-        requireInteractiveOrAbort(isInteractive);
+        if (!isInteractive) {
+            warnAgenticInteractiveOnly();
+            return { enabled: false };
+        }
         return { enabled: true, explicitId: input.agentic };
     }
     // undefined — fire the up-front prompt only when we have a TTY, something
@@ -61,7 +80,7 @@ async function resolveFlag(input, isInteractive, detected) {
     if (detected.length === 0) {
         return { enabled: false };
     }
-    return { enabled: await firePromptForAgentic(input.migrations) };
+    return firePromptForAgentic(input.migrations, detected);
 }
 function requireInteractiveOrAbort(isInteractive) {
     if (isInteractive)
@@ -74,29 +93,102 @@ function requireInteractiveOrAbort(isInteractive) {
     });
     throw new Error('Agentic flow requires an interactive terminal.');
 }
-async function firePromptForAgentic(migrations) {
-    // The "Yes"/"No" hints below assume at least one prompt-bearing migration is
-    // queued. If we later extend the prompt to fire for generator-only runs
-    // (validation-only), the hints need to branch.
+function warnAgenticInteractiveOnly() {
+    output_1.output.warn({
+        title: 'Skipping the agentic flow: it is interactive-only in this release and this is a non-interactive terminal.',
+        bodyLines: [
+            'Continuing the migration without the agentic flow. Re-run in an interactive terminal to use it.',
+        ],
+    });
+}
+async function firePromptForAgentic(migrations, detected) {
+    // The apply hint assumes at least one prompt-bearing migration is queued. If
+    // we later extend the prompt to fire for generator-only runs (validation-
+    // only), the hint needs to branch.
     const promptCount = migrations.filter((m) => !!m.prompt).length;
-    const yesHint = `Apply ${promptCount} prompt migration${promptCount === 1 ? '' : 's'} and validate generator output with an AI agent`;
-    const noHint = `Skip prompts and run generators without AI validation`;
+    const applyHint = `Apply ${promptCount} prompt migration${promptCount === 1 ? '' : 's'} and validate generator output with an AI agent`;
+    const skipHint = `Skip prompts and run generators without AI validation`;
+    const rememberHint = `Saved to nx.json so Nx won't ask again`;
+    // The pin-vs-flexible distinction only matters when more than one agent is
+    // installed. With a single agent, "always" simply persists `true` and the
+    // pin option is dropped.
+    const multipleAgents = detected.length > 1;
+    const choices = [
+        { name: 'yes-once', message: 'Yes, just this time', hint: applyHint },
+        {
+            name: 'yes-flex',
+            message: multipleAgents
+                ? "Yes, always (I'll pick the agent each run)"
+                : 'Yes, always',
+            hint: rememberHint,
+        },
+        ...(multipleAgents
+            ? [
+                {
+                    name: 'yes-pin',
+                    message: 'Yes, always with the same agent',
+                    hint: rememberHint,
+                },
+            ]
+            : []),
+        { name: 'no-once', message: 'No, just this time', hint: skipHint },
+        { name: 'no-never', message: 'No, never', hint: rememberHint },
+    ];
     // Blank line keeps the prompt from gluing to the previous `npm install`
     // output or any earlier orchestrator line.
     console.log();
     // `as any` because enquirer's TS types lag the runtime (per-choice `hint`
-    // and `value` are supported but not in the .d.ts).
+    // is supported but not in the .d.ts).
     const response = await (0, safe_prompt_1.migratePrompt)({
-        name: 'enable',
-        type: 'autocomplete',
+        name: 'choice',
+        type: 'select',
         message: 'Enable the agentic flow?',
-        choices: [
-            { name: 'yes', message: 'Yes', hint: yesHint },
-            { name: 'no', message: 'No', hint: noHint },
-        ],
+        choices,
         initial: 0,
     });
-    return response.enable === 'yes';
+    switch (response.choice) {
+        case 'yes-once':
+            return { enabled: true };
+        case 'yes-flex':
+            return { enabled: true, persist: true };
+        case 'yes-pin':
+            return { enabled: true, persist: 'pin' };
+        case 'no-never':
+            return { enabled: false, persist: false };
+        case 'no-once':
+        default:
+            return { enabled: false };
+    }
+}
+// Persists the user's agentic choice to `nx.json` so the up-front prompt is
+// skipped on future runs. Edits the raw file in place via jsonc-parser, so it
+// touches only the `migrate.agentic` key and preserves comments, formatting,
+// and any `extends` preset (the prompt fires mid-migration, so a silent
+// reformat would be surprising). Never throws - a failed write only costs the
+// user the prompt again next time.
+function persistAgenticChoice(value) {
+    const nxJsonPath = (0, path_1.join)(workspace_root_1.workspaceRoot, 'nx.json');
+    if (!(0, fs_1.existsSync)(nxJsonPath)) {
+        output_1.output.warn({
+            title: `Could not save your agentic choice: no nx.json found at the workspace root.`,
+        });
+        return;
+    }
+    try {
+        const content = (0, fs_1.readFileSync)(nxJsonPath, 'utf-8');
+        const edits = (0, jsonc_parser_1.modify)(content, ['migrate', 'agentic'], value, {
+            formattingOptions: { insertSpaces: true, tabSize: 2 },
+        });
+        (0, fs_1.writeFileSync)(nxJsonPath, (0, jsonc_parser_1.applyEdits)(content, edits));
+        output_1.output.log({
+            title: `Saved your choice to nx.json (migrate.agentic = ${JSON.stringify(value)}). Nx won't ask again.`,
+        });
+    }
+    catch (e) {
+        output_1.output.warn({
+            title: `Could not save your agentic choice to nx.json: ${e instanceof Error ? e.message : String(e)}`,
+        });
+    }
 }
 async function selectAgent(detected, explicitId, isInteractive) {
     if (explicitId) {
@@ -104,22 +196,18 @@ async function selectAgent(detected, explicitId, isInteractive) {
         if (match) {
             return match;
         }
-        if (detected.length === 0) {
-            output_1.output.error({
-                title: `The agent "${explicitId}" was requested via --agentic but no supported AI agent is installed on this machine.`,
-                bodyLines: INSTALL_SUPPORTED_AGENTS_HINT,
+        // The requested agent isn't installed. Rather than aborting the migration,
+        // warn and fall through to resolve from the agents that ARE installed
+        // (pick when 2+, auto-select the only one, error only when none exist).
+        if (detected.length > 0) {
+            output_1.output.warn({
+                title: `The requested agent "${explicitId}" is not installed; using the installed agent(s) instead.`,
+                bodyLines: [
+                    'Currently installed agents:',
+                    ...detected.map((d) => `  - ${d.displayName} (${d.id})`),
+                ],
             });
-            throw new Error(`The requested agent "${explicitId}" is not installed.`);
         }
-        output_1.output.error({
-            title: `The agent "${explicitId}" was requested via --agentic but is not installed.`,
-            bodyLines: [
-                'Install the requested agent and re-run, or pass --agentic without an explicit agent to choose from installed ones.',
-                'Currently installed agents:',
-                ...detected.map((d) => `  - ${d.displayName} (${d.id})`),
-            ],
-        });
-        throw new Error(`The requested agent "${explicitId}" is not installed.`);
     }
     if (detected.length === 0) {
         output_1.output.error({

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

@@ -1,4 +1,46 @@
 import { CommandModule } from 'yargs';
+import type { AgenticArg } from './agentic/select';
 export declare const yargsMigrateCommand: CommandModule;
 export declare const yargsInternalMigrateCommand: CommandModule;
 export declare const DEFAULT_MIGRATION_COMMIT_PREFIX = "chore: [nx migration] ";
+/** Allowed values for `--mode` / `migrate.mode`. */
+export declare const MIGRATE_MODES: readonly ["first-party", "third-party", "all"];
+export type MigrateMode = (typeof MIGRATE_MODES)[number];
+/** Allowed values for `--multi-major-mode` / `migrate.multiMajorMode`. */
+export declare const MULTI_MAJOR_MODES: readonly ["direct", "gradual"];
+export type MultiMajorMode = (typeof MULTI_MAJOR_MODES)[number];
+/**
+ * The `nx migrate` args bag. Types the keys the nx.json overlay and the
+ * commit-prefix invariant read/write; the index signature keeps the rest of
+ * the yargs args flowing through untouched.
+ */
+export interface MigrateArgs {
+    packageAndVersion?: string;
+    runMigrations?: string;
+    mode?: MigrateMode;
+    /**
+     * nx.json `migrate.mode` default. Consumed by `resolveMode` only when the
+     * target is Nx itself; kept separate from `mode` so it is never mistaken for
+     * an explicit `--mode` (which would hard-fail for non-Nx targets).
+     */
+    modeFromConfig?: MigrateMode;
+    multiMajorMode?: MultiMajorMode;
+    createCommits?: boolean;
+    commitPrefix?: string;
+    agentic?: AgenticArg;
+    validate?: boolean;
+    [key: string]: any;
+}
+/**
+ * Whether a custom commit prefix would be silently ignored: commits aren't
+ * enabled and the agentic flow can't enable them either. Shared by the yargs
+ * `.check()` (CLI args) and the nx.json overlay (merged args) so the rule lives
+ * in one place. `agentic` may flip commits on by default, so a configured
+ * agentic value (other than `false`, and not paired with `--no-create-commits`)
+ * keeps the prefix in play.
+ */
+export declare function customCommitPrefixHasNoEffect(args: {
+    createCommits: boolean | undefined;
+    commitPrefix: string | undefined;
+    agentic: unknown;
+}): boolean;

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_MIGRATION_COMMIT_PREFIX = exports.yargsInternalMigrateCommand = exports.yargsMigrateCommand = void 0;
+exports.MULTI_MAJOR_MODES = exports.MIGRATE_MODES = exports.DEFAULT_MIGRATION_COMMIT_PREFIX = exports.yargsInternalMigrateCommand = exports.yargsMigrateCommand = void 0;
+exports.customCommitPrefixHasNoEffect = customCommitPrefixHasNoEffect;
 const handle_import_1 = require("../../utils/handle-import");
 const documentation_1 = require("../yargs-utils/documentation");
 const shared_options_1 = require("../yargs-utils/shared-options");
@@ -20,6 +21,27 @@ exports.yargsInternalMigrateCommand = {
     handler: async (args) => process.exit(await (await (0, handle_import_1.handleImport)('./migrate.js', __dirname)).migrate(process.cwd(), args, process.argv.slice(3))),
 };
 exports.DEFAULT_MIGRATION_COMMIT_PREFIX = 'chore: [nx migration] ';
+/** Allowed values for `--mode` / `migrate.mode`. */
+exports.MIGRATE_MODES = ['first-party', 'third-party', 'all'];
+/** Allowed values for `--multi-major-mode` / `migrate.multiMajorMode`. */
+exports.MULTI_MAJOR_MODES = ['direct', 'gradual'];
+/**
+ * Whether a custom commit prefix would be silently ignored: commits aren't
+ * enabled and the agentic flow can't enable them either. Shared by the yargs
+ * `.check()` (CLI args) and the nx.json overlay (merged args) so the rule lives
+ * in one place. `agentic` may flip commits on by default, so a configured
+ * agentic value (other than `false`, and not paired with `--no-create-commits`)
+ * keeps the prefix in play.
+ */
+function customCommitPrefixHasNoEffect(args) {
+    const agenticMayEnableCommits = args.agentic !== undefined &&
+        args.agentic !== false &&
+        args.createCommits !== false;
+    return (args.createCommits !== true &&
+        !agenticMayEnableCommits &&
+        args.commitPrefix !== undefined &&
+        args.commitPrefix !== exports.DEFAULT_MIGRATION_COMMIT_PREFIX);
+}
 function withMigrationOptions(yargs) {
     return (0, shared_options_1.withVerbose)(yargs)
         .positional('packageAndVersion', {
@@ -70,12 +92,12 @@ function withMigrationOptions(yargs) {
         .option('mode', {
         describe: "Restrict which packages to migrate. Only applies when migrating Nx itself. 'first-party' processes only Nx and its plugins (the target package plus its nx.packageGroup); 'third-party' processes only the third-party dependencies referenced by Nx packageJsonUpdates entries, catching up on any updates that may have been skipped previously; 'all' processes everything. When targeting Nx in an interactive terminal, prompts for the value if not provided; otherwise defaults to 'all'.",
         type: 'string',
-        choices: ['first-party', 'third-party', 'all'],
+        choices: exports.MIGRATE_MODES,
     })
         .option('multiMajorMode', {
         describe: "Skip the multi-major migration prompt/warning and pick how to handle the jump. 'direct' migrates straight to the requested target. 'gradual' migrates to the smallest recommended step (re-run `nx migrate` to continue toward the original target). Equivalent env var: NX_MULTI_MAJOR_MODE=direct|gradual.",
         type: 'string',
-        choices: ['direct', 'gradual'],
+        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.',
@@ -86,10 +108,18 @@ function withMigrationOptions(yargs) {
         type: 'boolean',
     })
         .check(({ createCommits, commitPrefix, from, excludeAppliedMigrations, mode, agentic, }) => {
-        const agenticMayEnableCommits = agentic !== undefined && agentic !== false && createCommits !== false;
-        if (createCommits !== true &&
-            !agenticMayEnableCommits &&
-            commitPrefix !== exports.DEFAULT_MIGRATION_COMMIT_PREFIX) {
+        // Only an explicit `--no-create-commits` is decidable here, before the
+        // nx.json overlay runs: an explicit `false` can't be rescued by nx.json
+        // (the CLI flag wins, and the agentic flow can't enable commits when
+        // they're explicitly off). When `createCommits` is undefined, nx.json
+        // may still enable commits, so defer to the post-overlay
+        // `assertCommitPrefixHasCommits` check.
+        if (createCommits === false &&
+            customCommitPrefixHasNoEffect({
+                createCommits,
+                commitPrefix,
+                agentic,
+            })) {
             throw new Error('Error: Providing a custom commit prefix requires --create-commits to be enabled');
         }
         if (excludeAppliedMigrations && !from && mode !== 'third-party') {

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

@@ -0,0 +1,27 @@
+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.
+ *
+ * Phase-aware: generate-only options (`mode`, `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`.
+ *
+ * `mode` is carried as `modeFromConfig` rather than `mode` so it is never
+ * mistaken for an explicit `--mode`: `resolveMode` applies it only when the
+ * target is Nx itself, leaving `nx migrate <non-nx-pkg>` unaffected.
+ */
+export declare function applyNxJsonMigrateDefaults(args: MigrateArgs, migrateConfig: NxMigrateConfiguration | undefined, env?: NodeJS.ProcessEnv): MigrateArgs;
+/**
+ * The single authority for the "a custom commit prefix needs commits enabled"
+ * invariant. Run it against the final merged args (after
+ * `applyNxJsonMigrateDefaults`): the yargs `.check()` only sees the CLI args,
+ * but nx.json may enable commits via `createCommits` or `agentic`. The CLI
+ * `.check()` only fast-fails the unrescuable explicit `--no-create-commits`
+ * case; everything else is decided here.
+ */
+export declare function assertCommitPrefixHasCommits(merged: MigrateArgs): void;

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

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyNxJsonMigrateDefaults = applyNxJsonMigrateDefaults;
+exports.assertCommitPrefixHasCommits = assertCommitPrefixHasCommits;
+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.
+ *
+ * Phase-aware: generate-only options (`mode`, `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`.
+ *
+ * `mode` is carried as `modeFromConfig` rather than `mode` so it is never
+ * mistaken for an explicit `--mode`: `resolveMode` applies it only when the
+ * target is Nx itself, leaving `nx migrate <non-nx-pkg>` unaffected.
+ */
+function applyNxJsonMigrateDefaults(args, migrateConfig, env = process.env) {
+    if (!migrateConfig) {
+        return args;
+    }
+    const merged = { ...args };
+    // `--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) {
+        if (merged.createCommits === undefined &&
+            migrateConfig.createCommits !== undefined) {
+            assertType(migrateConfig.createCommits, 'boolean', 'createCommits');
+            merged.createCommits = migrateConfig.createCommits;
+        }
+        // `commitPrefix` carries a yargs default, so the default value is
+        // indistinguishable from "not provided" - treat it as not provided so
+        // nx.json can override it.
+        if ((merged.commitPrefix === undefined ||
+            merged.commitPrefix === command_object_1.DEFAULT_MIGRATION_COMMIT_PREFIX) &&
+            migrateConfig.commitPrefix !== undefined) {
+            assertType(migrateConfig.commitPrefix, 'string', 'commitPrefix');
+            merged.commitPrefix = migrateConfig.commitPrefix;
+        }
+        if (merged.agentic === undefined && migrateConfig.agentic !== undefined) {
+            assertValidAgentic(migrateConfig.agentic);
+            merged.agentic = (0, cli_args_1.coerceAgenticArg)(migrateConfig.agentic);
+        }
+        if (merged.validate === undefined && migrateConfig.validate !== undefined) {
+            assertType(migrateConfig.validate, 'boolean', 'validate');
+            merged.validate = migrateConfig.validate;
+        }
+    }
+    else {
+        if (merged.mode === undefined && migrateConfig.mode !== undefined) {
+            assertOneOf(migrateConfig.mode, command_object_1.MIGRATE_MODES, 'mode');
+            merged.modeFromConfig = migrateConfig.mode;
+        }
+        // The NX_MULTI_MAJOR_MODE env var is an established per-invocation override,
+        // so it takes precedence over nx.json (CLI flag > env > nx.json > default).
+        if (merged.multiMajorMode === undefined &&
+            !env[MULTI_MAJOR_MODE_ENV] &&
+            migrateConfig.multiMajorMode !== undefined) {
+            assertOneOf(migrateConfig.multiMajorMode, command_object_1.MULTI_MAJOR_MODES, 'multiMajorMode');
+            merged.multiMajorMode = migrateConfig.multiMajorMode;
+        }
+    }
+    return merged;
+}
+function assertOneOf(value, allowed, field) {
+    if (!allowed.includes(value)) {
+        throw new Error(`Error: Invalid nx.json migrate.${field} "${value}". Allowed: ${allowed.join(', ')}.`);
+    }
+}
+function assertType(value, type, field) {
+    if (typeof value !== type) {
+        throw new Error(`Error: Invalid nx.json migrate.${field} ${JSON.stringify(value)}. Expected a ${type}.`);
+    }
+}
+function assertValidAgentic(agentic) {
+    if (typeof agentic === 'boolean') {
+        return;
+    }
+    if (typeof agentic !== 'string' ||
+        !cli_args_1.AGENT_IDS.includes(agentic)) {
+        throw new Error(`Error: Invalid nx.json migrate.agentic "${agentic}". Allowed: ${cli_args_1.AGENT_IDS.join(', ')}, true, false.`);
+    }
+}
+/**
+ * The single authority for the "a custom commit prefix needs commits enabled"
+ * invariant. Run it against the final merged args (after
+ * `applyNxJsonMigrateDefaults`): the yargs `.check()` only sees the CLI args,
+ * but nx.json may enable commits via `createCommits` or `agentic`. The CLI
+ * `.check()` only fast-fails the unrescuable explicit `--no-create-commits`
+ * case; everything else is decided here.
+ */
+function assertCommitPrefixHasCommits(merged) {
+    const { createCommits, commitPrefix, agentic } = merged;
+    if ((0, command_object_1.customCommitPrefixHasNoEffect)({ createCommits, commitPrefix, agentic })) {
+        throw new Error('Error: A custom migrate commit prefix requires commits to be enabled. Set `migrate.createCommits` to `true` in nx.json or pass `--create-commits`.');
+    }
+}