nx 23.0.0-beta.21 → 23.0.0-beta.23

package/dist/plugins/package-json.js

@@ -22,7 +22,7 @@ function writeCache() {
 }
 const plugin = {
     name: 'nx-all-package-jsons-plugin',
-    createNodesV2: [
+    createNodes: [
         '*/**/package.json',
         (configFiles, options, context) => {
             const cache = readPackageJsonConfigurationCache();

package/dist/src/adapter/angular-json.d.ts

@@ -1,7 +1,7 @@
 import { ProjectsConfigurations } from '../config/workspace-json-project-json';
-import { NxPluginV2 } from '../project-graph/plugins';
+import { NxPlugin } from '../project-graph/plugins';
 export declare const NX_ANGULAR_JSON_PLUGIN_NAME = "nx-angular-json-plugin";
-export declare const NxAngularJsonPlugin: NxPluginV2;
+export declare const NxAngularJsonPlugin: NxPlugin;
 export default NxAngularJsonPlugin;
 export declare function shouldMergeAngularProjects(root: string, includeProjectsFromAngularJson: boolean): boolean;
 export declare function isAngularPluginInstalled(): boolean;

package/dist/src/adapter/angular-json.js

@@ -25,7 +25,6 @@ const createNodes = [
 exports.NxAngularJsonPlugin = {
     name: exports.NX_ANGULAR_JSON_PLUGIN_NAME,
     createNodes,
-    createNodesV2: createNodes,
 };
 exports.default = exports.NxAngularJsonPlugin;
 function shouldMergeAngularProjects(root, includeProjectsFromAngularJson) {

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/ai/set-up-ai-agents/set-up-ai-agents.js

@@ -12,6 +12,7 @@ const generate_files_1 = require("../../generators/utils/generate-files");
 const json_1 = require("../../generators/utils/json");
 const native_1 = require("../../native");
 const package_json_1 = require("../../utils/package-json");
+const package_manager_1 = require("../../utils/package-manager");
 const ignore_1 = require("../../utils/ignore");
 const provenance_1 = require("../../utils/provenance");
 const workspace_root_1 = require("../../utils/workspace-root");
@@ -48,7 +49,7 @@ async function setupAiAgentsGenerator(tree, options, inner = false) {
     }
     try {
         await (0, provenance_1.ensurePackageHasProvenance)('nx', normalizedOptions.packageVersion);
-        const { tempDir, cleanup } = (0, package_json_1.installPackageToTmp)('nx', normalizedOptions.packageVersion);
+        const { tempDir, cleanup } = (0, package_json_1.installPackageToTmp)('nx', normalizedOptions.packageVersion, (0, package_manager_1.detectPackageManager)(tree.root));
         let modulePath = (0, path_1.join)(tempDir, 'node_modules', 'nx', 'src/ai/set-up-ai-agents/set-up-ai-agents.js');
         const module = await (0, handle_import_1.handleImport)(modulePath);
         const setupAiAgentsGeneratorResult = await module.setupAiAgentsGenerator(tree, normalizedOptions, true);

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

@@ -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');
+        const packageInstallResults = (0, devkit_internals_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/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/graph/graph.js

@@ -172,7 +172,7 @@ async function generateGraph(args, affectedProjects) {
                 });
             }
             output_1.output.warn({
-                title: `${errors?.length > 1 ? `${errors.length} errors` : `An error`} occured while processing the project graph. Showing partial graph.`,
+                title: `${errors?.length > 1 ? `${errors.length} errors` : `An error`} occurred while processing the project graph. Showing partial graph.`,
             });
         }
     }

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

@@ -42,7 +42,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');
+        const packageInstallResults = (0, devkit_internals_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/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', {
@@ -68,14 +90,14 @@ function withMigrationOptions(yargs) {
         default: false,
     })
         .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'.",
+        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. The 'first-party' and 'third-party' modes are only available on Nx v23+: 'third-party' requires the workspace to already be on v23+, and 'first-party' requires migrating from v22+ into a v23+ target. 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;