nx 23.0.0-beta.23 → 23.0.0-beta.25

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

@@ -273,7 +273,7 @@ exports.examples = {
         },
         {
             command: 'migrate latest --interactive',
-            description: 'Collect package updates and migrations in interactive mode. In this mode, the user will be prompted whether to apply any optional package update and migration',
+            description: "Collect package updates and migrations in interactive mode. In this mode, the user will be prompted whether to apply any optional package update and migration. Deprecated and slated for removal in Nx v24. Use '--include' instead.",
         },
         {
             command: 'migrate latest --from=nx@14.5.0 --exclude-applied-migrations',

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

@@ -4,6 +4,7 @@ exports.AGENT_DEFINITIONS = exports.opencodeDefinition = exports.codexDefinition
 exports.getAgentDefinition = getAgentDefinition;
 const os_1 = require("os");
 const path_1 = require("path");
+const handoff_1 = require("./handoff");
 // --- Claude Code ---------------------------------------------------------
 function claudeCodeWellKnownPaths() {
     if (process.platform === 'win32') {
@@ -12,9 +13,25 @@ function claudeCodeWellKnownPaths() {
     }
     return [(0, path_1.join)((0, os_1.homedir)(), '.claude', 'local', 'claude')];
 }
+// Pre-authorizes the handoff write: Claude Code's default permission mode
+// asks before file writes it has no allow rule for, so without this each step
+// ends with an approval prompt for nx's own handoff scratch. Prefix-less
+// patterns resolve against the session cwd (pinned to the workspace root
+// below); `Edit` covers corrections to an already-written handoff.
+const CLAUDE_CODE_HANDOFF_ALLOWED_TOOLS = `Write(${handoff_1.MIGRATE_RUNS_RELATIVE_DIR}/**),Edit(${handoff_1.MIGRATE_RUNS_RELATIVE_DIR}/**)`;
 function claudeCodeBuildInteractive(ctx) {
     return {
-        args: ['--system-prompt', ctx.systemContext, ctx.userPrompt],
+        // `--allowedTools` is variadic (space/comma separated): a positional
+        // placed right after its value gets swallowed as another rule. The rules
+        // must stay in one comma-joined element with a non-variadic flag
+        // (`--system-prompt`) between them and the user prompt.
+        args: [
+            '--allowedTools',
+            CLAUDE_CODE_HANDOFF_ALLOWED_TOOLS,
+            '--system-prompt',
+            ctx.systemContext,
+            ctx.userPrompt,
+        ],
         cwd: ctx.workspaceRoot,
     };
 }
@@ -29,6 +46,9 @@ exports.claudeCodeDefinition = {
 function codexWellKnownPaths() {
     return [];
 }
+// No handoff permission flag: codex's default sandbox already allows writes
+// inside the cwd tree without prompting, and a user-hardened read-only config
+// is a deliberate choice we don't override.
 function codexBuildInteractive(ctx) {
     return {
         args: ['-c', `developer_instructions=${ctx.systemContext}`, ctx.userPrompt],
@@ -62,6 +82,9 @@ function opencodeWellKnownPaths() {
     candidates.push((0, path_1.join)(home, '.opencode', 'bin', 'opencode'));
     return candidates;
 }
+// No handoff permission config: opencode's `edit` permission defaults to
+// allow, and injecting one would clobber (not merge with) a user's own
+// permission patterns.
 function opencodeBuildInteractive(ctx) {
     const config = {
         agent: {

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

@@ -1,4 +1,10 @@
 import { HandoffFile } from './types';
+/**
+ * Workspace-relative directory holding all migrate-run scratch (handoff
+ * files). Shared with the agent permission rules in `definitions.ts` so the
+ * pre-authorized write scope can't drift from the actual layout.
+ */
+export declare const MIGRATE_RUNS_RELATIVE_DIR = ".nx/migrate-runs";
 /** Returns the run directory for a given workspace + run id (target version). */
 export declare function runDirPath(workspaceRoot: string, runId: string): string;
 /**

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

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIGRATE_RUNS_RELATIVE_DIR = void 0;
 exports.runDirPath = runDirPath;
 exports.mkdirSafely = mkdirSafely;
 exports.initRunDir = initRunDir;
@@ -9,9 +10,15 @@ exports.readHandoff = readHandoff;
 exports.waitForValidHandoff = waitForValidHandoff;
 const fs_1 = require("fs");
 const path_1 = require("path");
+/**
+ * Workspace-relative directory holding all migrate-run scratch (handoff
+ * files). Shared with the agent permission rules in `definitions.ts` so the
+ * pre-authorized write scope can't drift from the actual layout.
+ */
+exports.MIGRATE_RUNS_RELATIVE_DIR = '.nx/migrate-runs';
 /** Returns the run directory for a given workspace + run id (target version). */
 function runDirPath(workspaceRoot, runId) {
-    return (0, path_1.join)(workspaceRoot, '.nx', 'migrate-runs', runId);
+    return (0, path_1.join)(workspaceRoot, exports.MIGRATE_RUNS_RELATIVE_DIR, runId);
 }
 /**
  * `mkdir -p` with a contextual error wrapper. Without this, the raw

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

@@ -42,7 +42,7 @@ function buildGenericValidationUserPrompt(ctx) {
     const firstStep = ctx.impl.hasDiffContext
         ? `1. Inspect this migration's changes. ${(0, shared_rendering_1.renderGitInspectInstruction)()} Resolve each affected path to its owning Nx project via \`nx show project <name>\` (or by reading the project's \`project.json\` / \`package.json\`) to discover which targets each project actually defines — do not assume \`typecheck\` / \`test\` / \`lint\` exist. If no typecheck-equivalent exists, \`build\` is an acceptable substitute.`
         : `1. Resolve each path in <files_changed> to its owning Nx project. Use \`nx show project <name>\` (or read the project's \`project.json\` / \`package.json\`) to discover which targets each project actually defines — do not assume \`typecheck\` / \`test\` / \`lint\` exist. If no typecheck-equivalent exists, \`build\` is an acceptable substitute.`;
-    lines.push(``, `<validation_instructions>`, firstStep, `2. Pick the smallest relevant subset of available targets to verify the change. Prefer \`nx affected -t <target>\` (or \`nx run <project>:<target>\` for a single project). When many small projects are affected, you may use \`nx run-many -t <target> -p <project1>,<project2>\` with the project list derived from the changed files. Unscoped \`nx run-many\` (no \`-p\`) is forbidden.`, `3. If a verification surfaces an issue the migration should have produced cleanly (e.g. a missing import, a type annotation the generator's template missed), you may apply a minor in-scope fix. The boundary is "what this migration intended to accomplish" — do not refactor, do not modify functionality unrelated to the migration, do not extend the migration's scope, do not touch code the migration was not concerned with. If you are unsure whether a fix is in scope, report it in \`summary\` instead of applying.`, `4. Apply every fix you can within scope, then write your handoff. On \`status: "success"\`, summarize what you verified and any fixes you applied. On \`status: "failed"\`, enumerate the unresolved findings in \`summary\` so the user can address them; no commit will be created from a failed run, so the generator's changes and your partial fixes will sit uncommitted in the working tree for the user to review.`, `</validation_instructions>`, ``, `Once you finish, write your handoff JSON to:`, ...(0, shared_rendering_1.renderHandoffPathFooter)(ctx.handoffFileAbsolutePath));
+    lines.push(``, `<validation_instructions>`, firstStep, `2. Pick the smallest relevant subset of available targets to verify the change. Prefer \`nx affected -t <target>\` (or \`nx run <project>:<target>\` for a single project). When many small projects are affected, you may use \`nx run-many -t <target> -p <project1>,<project2>\` with the project list derived from the changed files. Unscoped \`nx run-many\` (no \`-p\`) is forbidden.`, `3. If a verification surfaces an issue the migration should have produced cleanly (e.g. a missing import, a type annotation the generator's template missed), you may apply a minor in-scope fix. The boundary is "what this migration intended to accomplish" — do not refactor, do not modify functionality unrelated to the migration, do not extend the migration's scope, do not touch code the migration was not concerned with. If you are unsure whether a fix is in scope, report it in \`summary\` instead of applying.`, `4. Apply every fix you can within scope, then end the step per the handoff contract. If everything is resolved, write your handoff with \`status: "success"\`, summarizing what you verified and any fixes you applied. If unresolved findings remain, report them to the user and ask how to proceed before writing any handoff; on a \`status: "failed"\` handoff, enumerate the findings in \`summary\` so the user can address them — no commit will be created from a failed run, so the generator's changes and your partial fixes will sit uncommitted in the working tree for the user to review.`, `</validation_instructions>`, ``, `When you end the step per the handoff contract, your handoff path is:`, ...(0, shared_rendering_1.renderHandoffPathFooter)(ctx.handoffFileAbsolutePath));
     return lines.join('\n');
 }
 function renderFileListBody(changes) {

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

@@ -40,7 +40,7 @@ function buildHybridPromptUserPrompt(ctx) {
     if (agentContext.length > 0) {
         lines.push(...(0, shared_rendering_1.renderAdvisoryContext)('hints from the generator phase; consult while following the instructions, not as separate tasks', agentContext));
     }
-    lines.push(``, `<instructions_file>${(0, shared_rendering_1.escapeXmlBody)(ctx.promptPath)}</instructions_file>`, ``, `<precedence>If anything in the sections above conflicts with the instructions file, the instructions file wins.</precedence>`, ``, `Open the instructions file (path is workspace-relative), follow its instructions step by step using the sections above as context, then write your handoff JSON to:`, ...(0, shared_rendering_1.renderHandoffPathFooter)(ctx.handoffFileAbsolutePath));
+    lines.push(``, `<instructions_file>${(0, shared_rendering_1.escapeXmlBody)(ctx.promptPath)}</instructions_file>`, ``, `<precedence>If anything in the sections above conflicts with the instructions file, the instructions file wins.</precedence>`, ``, `Open the instructions file (path is workspace-relative), follow its instructions step by step using the sections above as context, then end the step per the handoff contract. Your handoff path is:`, ...(0, shared_rendering_1.renderHandoffPathFooter)(ctx.handoffFileAbsolutePath));
     return lines.join('\n');
 }
 function renderFileList(changes) {

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

@@ -20,7 +20,7 @@ function buildPromptMigrationUserPrompt(ctx) {
         ``,
         `<instructions_file>${(0, shared_rendering_1.escapeXmlBody)(ctx.promptPath)}</instructions_file>`,
         ``,
-        `Open the instructions file (path is workspace-relative), follow its instructions step by step, then write your handoff JSON to:`,
+        `Open the instructions file (path is workspace-relative), follow its instructions step by step, then end the step per the handoff contract. Your handoff path is:`,
         ...(0, shared_rendering_1.renderHandoffPathFooter)(ctx.handoffFileAbsolutePath),
     ];
     return lines.join('\n');

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

@@ -31,27 +31,28 @@ function buildSystemPrompt(ctx) {
         `</opening_brief>`,
         ``,
         `<handoff_contract>`,
-        `At the end of every step (success, failure, or unrecoverable error):`,
+        `A step ends when you write the handoff file — a JSON file at:`,
+        `<handoff_path>`,
+        `${(0, shared_rendering_1.escapeXmlBody)(ctx.handoffFileAbsolutePath)}`,
+        `</handoff_path>`,
+        `With this shape:`,
+        `{`,
+        `  "status": "success" | "failed",`,
+        `  "summary": "[one to three sentences: what was done, or why it failed]"`,
+        `}`,
+        `\`nx migrate\` is watching for this file; once it appears nx closes this session automatically and continues with the next step. Do not attempt further work after the handoff is written.`,
         ``,
-        `1. Summarize what you did or why you couldn't in one or two sentences. Then note that writing the handoff file next will close this session and \`nx migrate\` will continue with the next step. Offer the user a chance to ask follow-up questions or redirect before you write — if they have none, proceed with the write.`,
-        `2. Write a JSON file at:`,
-        `   <handoff_path>`,
-        `   ${(0, shared_rendering_1.escapeXmlBody)(ctx.handoffFileAbsolutePath)}`,
-        `   </handoff_path>`,
-        `   With this shape:`,
-        `   {`,
-        `     "status": "success" | "failed",`,
-        `     "summary": "[one to three sentences: what was done, or why it failed]"`,
-        `   }`,
-        `3. You're done. \`nx migrate\` is watching for the handoff file; once it appears nx closes this session automatically and continues with the next step. Do not attempt further work after the handoff is written.`,
+        `How to end the step:`,
+        `1. Success — the step is fully applied (or validation passed): state a one-or-two-sentence summary of what you did and, in the same turn, write the handoff file with \`status: "success"\`. Do not pause for confirmation before the write — it is pre-authorized.`,
+        `2. You need direction — the instructions are unclear, the workspace state conflicts with what they assume, or a decision isn't yours to make: do not write the handoff file. Ask the user and continue based on their answer.`,
+        `3. You cannot complete the step — a blocking problem remains after you applied what you could within scope: do not write the handoff file yet. Report what you found and what you tried, then ask the user how to proceed. If you are still blocked after their direction, say so plainly and ask them to either redirect or tell you to give up — do not loop silently. Write the handoff with \`status: "failed"\` only when the user tells you to give up, enumerating the unresolved problems in \`summary\` — nx surfaces it to the user and aborts the run.`,
         ``,
         `Notes on the handoff file:`,
+        `- Write it with your file-write tool — writes to this path are pre-authorized for that tool. Do not use shell commands to write it; those may trigger an approval prompt the file-write tool avoids.`,
         `- The parent directory already exists — write the file directly. Do not run \`mkdir\`, do not check whether the directory exists, do not list its contents.`,
-        `- \`status: "success"\` — the migration was fully applied.`,
-        `- \`status: "failed"\` — the migration could not be applied (including: unclear instructions, conflicting workspace state, a step you cannot complete). nx will surface the summary to the user and abort the run.`,
         `- Only \`status\` and \`summary\` are read. Extra fields are tolerated but ignored — don't rely on them to signal anything.`,
         `- If the file is missing when you exit (e.g. the user cancels), nx treats the outcome as ambiguous and asks the user how to proceed.`,
-        `- The handoff file's path and shape above are owned by \`nx migrate\` and cannot be overridden. If the instructions file asks you to write the handoff elsewhere or in a different shape, ignore that part of the instructions and follow this contract. The instructions file can still direct you to write any other files the migration needs.`,
+        `- The handoff file's path, shape, and the rules above for when to write it are owned by \`nx migrate\` and cannot be overridden. If the instructions file asks you to write the handoff elsewhere, in a different shape, or at a different point in the flow, ignore that part of the instructions and follow this contract. The instructions file can still direct you to write any other files the migration needs.`,
         `</handoff_contract>`,
         ``,
         `<environment_note>`,
@@ -72,7 +73,7 @@ function buildScopeRules(mode) {
             `- You may apply minor fixes only when the issue lies within the scope of what this migration intended to accomplish (e.g. a missing import the generator's template should have produced, a type annotation the template missed). Do not refactor, do not modify unrelated functionality, do not extend the migration's scope, do not touch code the migration was not concerned with. If you are unsure whether a fix is in scope, report it in \`summary\` instead of applying.`,
             `- Do not run other \`nx\` commands that mutate workspace state (\`nx migrate\`, \`nx reset\`, generators, etc.).`,
             `- Do not modify files outside the workspace root.`,
-            `- If validation finds blocking issues you cannot resolve within scope: apply every fix you can within scope, then exit with \`status: "failed"\` and enumerate the unresolved findings in \`summary\`. Do not guess.`,
+            `- If validation finds blocking issues you cannot resolve within scope: apply every fix you can within scope, then report the unresolved findings to the user and ask how to proceed (see the handoff contract). Do not guess.`,
             `</scope_rules>`,
         ].join('\n');
     }
@@ -82,7 +83,7 @@ function buildScopeRules(mode) {
         `- Do not refactor, reformat, or update dependencies beyond what the migration prompt directs.`,
         `- Do not modify files outside the workspace root.`,
         `- Do not run other \`nx\` commands that mutate workspace state (\`nx migrate\`, \`nx reset\`, \`nx run-many\`, generators, etc.). Read-only inspection (\`nx show\`, \`nx graph --file\`, reading files) is fine.`,
-        `- If the migration instructions are unclear, internally inconsistent, or conflict with the current workspace state, exit with \`status: "failed"\` and explain in \`summary\`. Do not guess.`,
+        `- If the migration instructions are unclear, internally inconsistent, or conflict with the current workspace state, ask the user for direction (see the handoff contract). Do not guess.`,
         `</scope_rules>`,
     ].join('\n');
 }

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

@@ -6,6 +6,8 @@ export interface ResolveAgenticInput {
     migrations: ReadonlyArray<{
         prompt?: string;
     }>;
+    /** The `--interactive` flag; `false` (`--no-interactive`) disables all prompting. */
+    interactive?: boolean;
 }
 /**
  * Resolves the agentic state for a `--run-migrations` invocation. Runs once,

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

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveAgentic = resolveAgentic;
+const tslib_1 = require("tslib");
 const fs_1 = require("fs");
 const jsonc_parser_1 = require("jsonc-parser");
 const path_1 = require("path");
+const pc = tslib_1.__importStar(require("picocolors"));
 const output_1 = require("../../../utils/output");
 const workspace_root_1 = require("../../../utils/workspace-root");
 const safe_prompt_1 = require("../safe-prompt");
@@ -27,7 +29,9 @@ async function resolveAgentic(input) {
         });
         return { kind: 'inside-agent' };
     }
-    const isInteractive = !!process.stdin.isTTY && !!process.stdout.isTTY;
+    const isInteractive = !!process.stdin.isTTY &&
+        !!process.stdout.isTTY &&
+        input.interactive !== false;
     // Skip detection for the one case where the result is unused: explicit
     // `--agentic=false`. For every other path (explicit enable, explicit id, or
     // undefined-with-prompt) we either need the detection result to pick/verify
@@ -95,7 +99,7 @@ function requireInteractiveOrAbort(isInteractive) {
 }
 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.',
+        title: 'Skipping the agentic flow: it is interactive-only in this release and this run is non-interactive.',
         bodyLines: [
             'Continuing the migration without the agentic flow. Re-run in an interactive terminal to use it.',
         ],
@@ -114,37 +118,44 @@ async function firePromptForAgentic(migrations, detected) {
     // pin option is dropped.
     const multipleAgents = detected.length > 1;
     const choices = [
-        { name: 'yes-once', message: 'Yes, just this time', hint: applyHint },
+        {
+            name: 'yes-once',
+            message: 'Yes, just this time',
+            description: applyHint,
+        },
         {
             name: 'yes-flex',
             message: multipleAgents
                 ? "Yes, always (I'll pick the agent each run)"
                 : 'Yes, always',
-            hint: rememberHint,
+            description: rememberHint,
         },
         ...(multipleAgents
             ? [
                 {
                     name: 'yes-pin',
                     message: 'Yes, always with the same agent',
-                    hint: rememberHint,
+                    description: rememberHint,
                 },
             ]
             : []),
-        { name: 'no-once', message: 'No, just this time', hint: skipHint },
-        { name: 'no-never', message: 'No, never', hint: rememberHint },
+        { name: 'no-once', message: 'No, just this time', description: skipHint },
+        { name: 'no-never', message: 'No, never', description: 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`
-    // is supported but not in the .d.ts).
+    // `as any`: `footer` and per-choice `description` aren't in enquirer's .d.ts.
     const response = await (0, safe_prompt_1.migratePrompt)({
         name: 'choice',
         type: 'select',
         message: 'Enable the agentic flow?',
         choices,
         initial: 0,
+        footer: function () {
+            const focused = this.focused;
+            return focused?.description ? pc.dim(`  ${focused.description}`) : '';
+        },
     });
     switch (response.choice) {
         case 'yes-once':

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

@@ -3,9 +3,9 @@ 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 `--include` / `migrate.include`. */
+export declare const MIGRATE_INCLUDE_VALUES: readonly ["required", "optional", "all"];
+export type MigrateInclude = (typeof MIGRATE_INCLUDE_VALUES)[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];
@@ -17,13 +17,14 @@ export type MultiMajorMode = (typeof MULTI_MAJOR_MODES)[number];
 export interface MigrateArgs {
     packageAndVersion?: string;
     runMigrations?: string;
-    mode?: MigrateMode;
+    include?: MigrateInclude;
     /**
-     * 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).
+     * nx.json `migrate.include` default. Consumed by `resolveInclude` only when the
+     * resolved target supports optional updates; kept separate from `include` so it is never
+     * mistaken for an explicit `--include` (which hard-fails when the target does
+     * not support optional updates).
      */
-    modeFromConfig?: MigrateMode;
+    includeFromConfig?: MigrateInclude;
     multiMajorMode?: MultiMajorMode;
     createCommits?: boolean;
     commitPrefix?: string;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MULTI_MAJOR_MODES = exports.MIGRATE_MODES = exports.DEFAULT_MIGRATION_COMMIT_PREFIX = exports.yargsInternalMigrateCommand = exports.yargsMigrateCommand = void 0;
+exports.MULTI_MAJOR_MODES = exports.MIGRATE_INCLUDE_VALUES = 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");
@@ -21,8 +21,8 @@ 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 `--include` / `migrate.include`. */
+exports.MIGRATE_INCLUDE_VALUES = ['required', 'optional', 'all'];
 /** Allowed values for `--multi-major-mode` / `migrate.multiMajorMode`. */
 exports.MULTI_MAJOR_MODES = ['direct', 'gradual'];
 /**
@@ -76,7 +76,7 @@ function withMigrationOptions(yargs) {
         default: exports.DEFAULT_MIGRATION_COMMIT_PREFIX,
     })
         .option('interactive', {
-        describe: 'Enable prompts to confirm whether to collect optional package updates and migrations.',
+        describe: "Enable confirmation prompts for collecting optional package updates and migrations. Deprecated and slated for removal in Nx v24. Use '--include' instead. The flag stays valid for other interactive prompts.",
         type: 'boolean',
     })
         .option('excludeAppliedMigrations', {
@@ -89,10 +89,10 @@ function withMigrationOptions(yargs) {
         type: 'boolean',
         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. 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'.",
+        .option('include', {
+        describe: "Restrict which packages to migrate. Only applies when the target package supports optional updates. 'required' processes only the target package and the related packages it ships with; 'optional' processes only the optional dependency updates those packages recommend, catching up on any that may have been skipped previously; 'all' processes everything. When the target supports optional updates in an interactive terminal, prompts for the value if not provided; otherwise defaults to 'all'.",
         type: 'string',
-        choices: exports.MIGRATE_MODES,
+        choices: exports.MIGRATE_INCLUDE_VALUES,
     })
         .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.",
@@ -107,7 +107,7 @@ function withMigrationOptions(yargs) {
         describe: 'When `--agentic` resolves to an enabled agent, run agent-driven validation after generator-only migrations that have no `prompt:` field. Defaults to on; pass `--no-validate` to opt out. Has no effect when `--agentic` is disabled, when running inside an outer agent, or when running non-interactively without an explicit agent.',
         type: 'boolean',
     })
-        .check(({ createCommits, commitPrefix, from, excludeAppliedMigrations, mode, agentic, }) => {
+        .check(({ createCommits, commitPrefix, from, excludeAppliedMigrations, include, agentic, }) => {
         // 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
@@ -122,7 +122,7 @@ function withMigrationOptions(yargs) {
             })) {
             throw new Error('Error: Providing a custom commit prefix requires --create-commits to be enabled');
         }
-        if (excludeAppliedMigrations && !from && mode !== 'third-party') {
+        if (excludeAppliedMigrations && !from && include !== 'optional') {
             throw new Error('Error: Excluding migrations that should have been previously applied requires --from to be set');
         }
         if (typeof agentic === 'string' &&

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

@@ -5,15 +5,16 @@ import { type MigrateArgs } from './command-object';
  * 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
+ * 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`.
  *
- * `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.
+ * `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.
  */
 export declare function applyNxJsonMigrateDefaults(args: MigrateArgs, migrateConfig: NxMigrateConfiguration | undefined, env?: NodeJS.ProcessEnv): MigrateArgs;
 /**

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

@@ -10,15 +10,16 @@ const MULTI_MAJOR_MODE_ENV = 'NX_MULTI_MAJOR_MODE';
  * 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
+ * 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`.
  *
- * `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.
+ * `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.
  */
 function applyNxJsonMigrateDefaults(args, migrateConfig, env = process.env) {
     if (!migrateConfig) {
@@ -53,9 +54,9 @@ function applyNxJsonMigrateDefaults(args, migrateConfig, env = process.env) {
         }
     }
     else {
-        if (merged.mode === undefined && migrateConfig.mode !== undefined) {
-            assertOneOf(migrateConfig.mode, command_object_1.MIGRATE_MODES, 'mode');
-            merged.modeFromConfig = migrateConfig.mode;
+        if (merged.include === undefined && migrateConfig.include !== undefined) {
+            assertOneOf(migrateConfig.include, command_object_1.MIGRATE_INCLUDE_VALUES, 'include');
+            merged.includeFromConfig = migrateConfig.include;
         }
         // 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).

package/dist/src/command-line/migrate/migrate-ui-api.d.ts

@@ -1,5 +1,7 @@
 import type { MigrationDetailsWithId } from '../../config/misc-interfaces';
 import type { FileChange } from '../../generators/tree';
+import { isHybridMigration, isPromptOnlyMigration } from './migrate';
+export { isPromptOnlyMigration, isHybridMigration };
 export type MigrationsJsonMetadata = {
     completedMigrations?: Record<string, SuccessfulMigration | FailedMigration | SkippedMigration | StoppedMigration>;
     runningMigrations?: string[];
@@ -16,6 +18,7 @@ export type SuccessfulMigration = {
     changedFiles: Omit<FileChange, 'content'>[];
     ref: string;
     nextSteps?: string[];
+    acknowledgedPrompt?: boolean;
 };
 export type FailedMigration = {
     type: 'failed';
@@ -72,5 +75,14 @@ export declare function addStoppedMigration(id: string, error: string): (migrati
 };
 export declare function readMigrationsJsonMetadata(workspacePath: string): MigrationsJsonMetadata;
 export declare function undoMigration(workspacePath: string, id: string): (migrationsJsonMetadata: MigrationsJsonMetadata) => MigrationsJsonMetadata;
+/**
+ * Records that the user has confirmed completion of a prompt-bearing
+ * migration's AI prompt phase. Dispatches by shape so callers (the webview
+ * event handler in Nx Console) don't need to know which is which:
+ *  - prompt-only: records success directly (no spawn, no process lifecycle).
+ *  - hybrid: persists the `acknowledgedPrompt` flag on the existing
+ *    successful record from the generator phase.
+ */
+export declare function acknowledgeMigrationPrompt(workspacePath: string, migration: MigrationDetailsWithId): void;
 export declare function killMigrationProcess(migrationId: string, workspacePath?: string): boolean;
 export declare function stopMigration(migrationId: string): (migrationsJsonMetadata: MigrationsJsonMetadata) => MigrationsJsonMetadata;

package/dist/src/command-line/migrate/migrate-ui-api.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHybridMigration = exports.isPromptOnlyMigration = void 0;
 exports.recordInitialMigrationMetadata = recordInitialMigrationMetadata;
 exports.finishMigrationProcess = finishMigrationProcess;
 exports.runSingleMigration = runSingleMigration;
@@ -12,12 +13,15 @@ exports.addSkippedMigration = addSkippedMigration;
 exports.addStoppedMigration = addStoppedMigration;
 exports.readMigrationsJsonMetadata = readMigrationsJsonMetadata;
 exports.undoMigration = undoMigration;
+exports.acknowledgeMigrationPrompt = acknowledgeMigrationPrompt;
 exports.killMigrationProcess = killMigrationProcess;
 exports.stopMigration = stopMigration;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const migrate_1 = require("./migrate");
+Object.defineProperty(exports, "isHybridMigration", { enumerable: true, get: function () { return migrate_1.isHybridMigration; } });
+Object.defineProperty(exports, "isPromptOnlyMigration", { enumerable: true, get: function () { return migrate_1.isPromptOnlyMigration; } });
 let currentMigrationProcess = null;
 let currentMigrationId = null;
 let migrationCancelled = false;
@@ -79,6 +83,14 @@ async function runSingleMigration(workspacePath, migration, configuration) {
         currentMigrationId = migration.id;
         migrationCancelled = false;
         modifyMigrationsJsonMetadata(workspacePath, addRunningMigration(migration.id));
+        // Prompt-only migrations have no deterministic implementation to spawn.
+        // The state-machine's auto-run hits this branch; the manual Mark-as-
+        // Completed path calls `recordPromptOnlySuccess` directly so it stays out
+        // of the process-tracking lifecycle.
+        if ((0, migrate_1.isPromptOnlyMigration)(migration)) {
+            recordPromptOnlySuccess(workspacePath, migration);
+            return;
+        }
         const gitRefBefore = (0, child_process_1.execSync)('git rev-parse HEAD', {
             cwd: workspacePath,
             encoding: 'utf-8',
@@ -192,6 +204,13 @@ async function runSingleMigration(workspacePath, migration, configuration) {
     }
 }
 async function getImplementationPath(workspacePath, migration) {
+    // Prompt-only migrations have no implementation — the "source" the user
+    // wants to see is the prompt file itself. Resolving via the regular
+    // implementation lookup would throw because both `implementation` and
+    // `factory` are unset.
+    if ((0, migrate_1.isPromptOnlyMigration)(migration)) {
+        return (0, path_1.join)(workspacePath, migration.prompt);
+    }
     const { collection, collectionPath } = (0, migrate_1.readMigrationCollection)(migration.package, workspacePath);
     const { path } = (0, migrate_1.getImplementationPath)(collection, collectionPath, migration.name);
     return path;
@@ -208,6 +227,11 @@ function addSuccessfulMigration(id, fileChanges, ref, nextSteps) {
         if (!copied.completedMigrations) {
             copied.completedMigrations = {};
         }
+        // Carry forward a previously-set acknowledgedPrompt so any caller that
+        // re-records a successful entry for the same id (no current trigger; this
+        // is defensive against future paths) cannot silently drop the user's ack.
+        const existing = copied.completedMigrations[id];
+        const acknowledgedPrompt = existing?.type === 'successful' && existing.acknowledgedPrompt;
         copied.completedMigrations = {
             ...copied.completedMigrations,
             [id]: {
@@ -216,6 +240,7 @@ function addSuccessfulMigration(id, fileChanges, ref, nextSteps) {
                 changedFiles: fileChanges,
                 ref,
                 nextSteps,
+                ...(acknowledgedPrompt && { acknowledgedPrompt: true }),
             },
         };
         return copied;
@@ -312,17 +337,61 @@ function undoMigration(workspacePath, id) {
         const existing = migrationsJsonMetadata.completedMigrations[id];
         if (existing.type !== 'successful')
             throw new Error(`undoMigration called on unsuccessful migration: ${id}`);
-        (0, child_process_1.execSync)(`git reset --hard ${existing.ref}^`, {
-            cwd: workspacePath,
-            encoding: 'utf-8',
-            windowsHide: true,
-        });
+        // No-changes successful entries (prompt-only short-circuit, generators
+        // that ran but produced no diff) have no migration commit to roll back;
+        // `existing.ref` is the unmodified HEAD at run time, so `ref^` would
+        // reset past unrelated history. Only flip the metadata to skipped.
+        if (existing.changedFiles.length > 0) {
+            (0, child_process_1.execSync)(`git reset --hard ${existing.ref}^`, {
+                cwd: workspacePath,
+                encoding: 'utf-8',
+                windowsHide: true,
+            });
+        }
         migrationsJsonMetadata.completedMigrations[id] = {
             type: 'skipped',
         };
         return migrationsJsonMetadata;
     };
 }
+/**
+ * Records that the user has confirmed completion of a prompt-bearing
+ * migration's AI prompt phase. Dispatches by shape so callers (the webview
+ * event handler in Nx Console) don't need to know which is which:
+ *  - prompt-only: records success directly (no spawn, no process lifecycle).
+ *  - hybrid: persists the `acknowledgedPrompt` flag on the existing
+ *    successful record from the generator phase.
+ */
+function acknowledgeMigrationPrompt(workspacePath, migration) {
+    if ((0, migrate_1.isPromptOnlyMigration)(migration)) {
+        recordPromptOnlySuccess(workspacePath, migration);
+        return;
+    }
+    modifyMigrationsJsonMetadata(workspacePath, (metadata) => {
+        const existing = metadata.completedMigrations?.[migration.id];
+        if (!existing || existing.type !== 'successful') {
+            return metadata;
+        }
+        metadata.completedMigrations = {
+            ...metadata.completedMigrations,
+            [migration.id]: { ...existing, acknowledgedPrompt: true },
+        };
+        return metadata;
+    });
+}
+// Writes a successful record for a prompt-only migration without touching the
+// process-lifecycle tracking that `runSingleMigration` manages — safe to call
+// from `acknowledgeMigrationPrompt` while another migration may be running.
+// The prompt-path reminder is rendered by the UI from `migration.prompt`, so
+// no next step is recorded here.
+function recordPromptOnlySuccess(workspacePath, migration) {
+    const ref = (0, child_process_1.execSync)('git rev-parse HEAD', {
+        cwd: workspacePath,
+        encoding: 'utf-8',
+        windowsHide: true,
+    }).trim();
+    modifyMigrationsJsonMetadata(workspacePath, addSuccessfulMigration(migration.id, [], ref, []));
+}
 function killMigrationProcess(migrationId, workspacePath) {
     try {
         if (workspacePath) {