nx 23.0.0-beta.24 → 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. Only supported when migrating to Nx versions lower than v23',
+            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/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");
@@ -116,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. Not supported when migrating to Nx v23 or later: use '--mode' to choose which packages to migrate.",
+        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.d.ts

@@ -2,6 +2,7 @@ import { MigrationsJson, PackageJsonUpdateForPackage as PackageUpdate } from '..
 import { NxJsonConfiguration } from '../../config/nx-json';
 import { FileChange } from '../../generators/tree';
 import { ArrayPackageGroup, PackageJson } from '../../utils/package-json';
+import { PackageManagerCommands } from '../../utils/package-manager';
 import { type MultiMajorMode } from './multi-major';
 import type { AgenticArg } from './agentic/select';
 import type { ResolvedAgentic } from './agentic/types';
@@ -11,6 +12,8 @@ import { normalizeVersion } from './version-utils';
 export { normalizeVersion };
 export interface ResolvedMigrationConfiguration extends MigrationsJson {
     packageGroup?: ArrayPackageGroup;
+    /** Mirrors the package's `nx-migrations`/`ng-update` `supportsOptionalUpdates` flag. */
+    supportsOptionalUpdates?: boolean;
     /** Prompt file contents keyed by the `prompt` value as it appears on the migration entry. */
     resolvedPromptFiles?: Record<string, string>;
 }
@@ -20,7 +23,7 @@ type CommandFailure = {
     stdout?: string | Buffer;
 };
 export declare function formatCommandFailure(command: string, error: CommandFailure): string;
-export type MigrateMode = 'first-party' | 'third-party' | 'all';
+export type MigrateInclude = 'required' | 'optional' | 'all';
 export interface MigratorOptions {
     packageJson?: PackageJson;
     nxInstallation?: NxJsonConfiguration['installation'];
@@ -36,13 +39,13 @@ export interface MigratorOptions {
     excludeAppliedMigrations?: boolean;
     /**
      * Restricts `packageJsonUpdates` filtering based on the value:
-     * - 'first-party' keeps only packages in `firstPartyPackages`
-     * - 'third-party' keeps only packages NOT in `firstPartyPackages`
+     * - 'required' keeps only packages in `requiredPackages`
+     * - 'optional' keeps only packages NOT in `requiredPackages`
      * - 'all' / undefined keeps all packages (no filtering)
      */
-    mode?: MigrateMode;
-    /** First-party package names used by `mode` for filtering. */
-    firstPartyPackages?: ReadonlySet<string>;
+    include?: MigrateInclude;
+    /** Packages in the `required` partition; `include` filters against this set. */
+    requiredPackages?: ReadonlySet<string>;
 }
 export declare class Migrator {
     private readonly packageJson?;
@@ -52,8 +55,8 @@ export declare class Migrator {
     private readonly to;
     private readonly interactive;
     private readonly excludeAppliedMigrations;
-    private readonly mode;
-    private readonly firstPartyPackages;
+    private readonly include;
+    private readonly requiredPackages;
     private readonly packageUpdates;
     private readonly collectedVersions;
     private readonly promptAnswers;
@@ -92,7 +95,7 @@ export declare class Migrator {
     private getPackageJsonUpdatesFromPackageGroup;
     private filterPackageJsonUpdates;
     private shouldExcludePackage;
-    private applyModeFilter;
+    private applyIncludeFilter;
     private shouldApplyPackageUpdate;
     private validatePackageUpdateVersion;
     private addPackageUpdate;
@@ -112,17 +115,14 @@ export declare class Migrator {
  * The canonical Nx package for a given target version: `@nrwl/workspace` for
  * legacy (`< 14.0.0-beta.0`), `nx` otherwise. Non-semver inputs (e.g. the
  * literal `'latest'` sentinel before tag resolution) resolve to modern era.
- * Used by `--mode=third-party` to silently swap `@nx/workspace` → `nx` when
- * walking the cascade.
  */
 export declare function resolveCanonicalNxPackage(targetVersion: string): 'nx' | '@nrwl/workspace';
-export declare function resolveMode(mode: MigrateMode | undefined, targetPackage: string, targetVersion: string, context?: {
+export declare function resolveInclude(include: MigrateInclude | undefined, context: {
     hasFrom: boolean;
     hasExcludeAppliedMigrations: boolean;
-    installedMajor?: number | null;
-    isV23Plus?: boolean;
     interactive?: boolean;
-}, configuredMode?: MigrateMode): Promise<MigrateMode>;
+    targetSupportsOptionalUpdates: boolean;
+}, configuredInclude?: MigrateInclude): Promise<MigrateInclude>;
 type GenerateMigrations = {
     type: 'generateMigrations';
     targetPackage: string;
@@ -135,7 +135,7 @@ type GenerateMigrations = {
     };
     interactive?: boolean;
     excludeAppliedMigrations?: boolean;
-    mode: MigrateMode;
+    include: MigrateInclude;
     /**
      * Set when multi-major redirected `targetVersion` to an incremental step
      * (gradual mode or the interactive prompt picking a smaller jump). Holds
@@ -159,7 +159,8 @@ type RunMigrations = {
 };
 export declare function parseMigrationsOptions(options: {
     [k: string]: any;
-}): Promise<GenerateMigrations | RunMigrations>;
+}, fetch?: MigratorOptions['fetch']): Promise<GenerateMigrations | RunMigrations>;
+export declare function createFetcher(pmc: PackageManagerCommands): (packageName: string, packageVersion: string) => Promise<ResolvedMigrationConfiguration>;
 export { filterDowngradedUpdates };
 /**
  * Detects npm peer-dependency resolution failures. Keyed on the `ERESOLVE`