nx 23.0.0-beta.11 → 23.0.0-beta.13

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

@@ -378,7 +378,7 @@ exports.examples = {
             description: 'Watch the "app" project and echo the project name and the files that changed',
         },
         {
-            command: 'watch --projects=app1,app2 --includeDependentProjects -- echo \\$NX_PROJECT_NAME',
+            command: 'watch --projects=app1,app2 --includeDependencies -- echo \\$NX_PROJECT_NAME',
             description: 'Watch "app1" and "app2" and echo the project name whenever a specified project or its dependencies change',
         },
         {

package/dist/src/command-line/init/implementation/angular/standalone-workspace.js

@@ -54,29 +54,26 @@ function createNxJson(repoRoot, angularJson, cacheableOperations, { eslintProjec
                 : []),
         ].filter(Boolean),
     };
-    nxJson.targetDefaults ??= {};
+    const defaults = Array.isArray(nxJson.targetDefaults)
+        ? [...nxJson.targetDefaults]
+        : [];
     if (workspaceTargets.includes('build')) {
-        nxJson.targetDefaults.build = {
-            ...nxJson.targetDefaults.build,
+        (0, utils_1.upsertTargetDefaultEntry)(defaults, 'build', {
             dependsOn: ['^build'],
             inputs: ['production', '^production'],
-        };
+        });
     }
     if (workspaceTargets.includes('server')) {
-        nxJson.targetDefaults.server = {
-            ...nxJson.targetDefaults.server,
+        (0, utils_1.upsertTargetDefaultEntry)(defaults, 'server', {
             inputs: ['production', '^production'],
-        };
+        });
     }
     if (workspaceTargets.includes('test')) {
         const inputs = ['default', '^production'];
         if ((0, fileutils_1.fileExists)((0, node_path_1.join)(repoRoot, 'karma.conf.js'))) {
             inputs.push('{workspaceRoot}/karma.conf.js');
         }
-        nxJson.targetDefaults.test = {
-            ...nxJson.targetDefaults.test,
-            inputs,
-        };
+        (0, utils_1.upsertTargetDefaultEntry)(defaults, 'test', { inputs });
     }
     if (workspaceTargets.includes('lint')) {
         const inputs = ['default'];
@@ -86,16 +83,15 @@ function createNxJson(repoRoot, angularJson, cacheableOperations, { eslintProjec
         if ((0, fileutils_1.fileExists)((0, node_path_1.join)(repoRoot, 'eslint.config.cjs'))) {
             inputs.push('{workspaceRoot}/eslint.config.cjs');
         }
-        nxJson.targetDefaults.lint = {
-            ...nxJson.targetDefaults.lint,
-            inputs,
-        };
+        (0, utils_1.upsertTargetDefaultEntry)(defaults, 'lint', { inputs });
     }
     if (workspaceTargets.includes('e2e')) {
-        nxJson.targetDefaults.e2e = {
-            ...nxJson.targetDefaults.e2e,
+        (0, utils_1.upsertTargetDefaultEntry)(defaults, 'e2e', {
             inputs: ['default', '^production'],
-        };
+        });
+    }
+    if (defaults.length > 0) {
+        nxJson.targetDefaults = defaults;
     }
     (0, fileutils_1.writeJsonFile)((0, node_path_1.join)(repoRoot, 'nx.json'), nxJson);
 }

package/dist/src/command-line/init/implementation/utils.d.ts

@@ -1,9 +1,15 @@
-import { NxJsonConfiguration } from '../../../config/nx-json';
+import { NxJsonConfiguration, TargetDefaultEntry } from '../../../config/nx-json';
 import { PackageJson } from '../../../utils/package-json';
 import { PackageManagerCommands } from '../../../utils/package-manager';
 export declare function createNxJsonFile(repoRoot: string, topologicalTargets: string[], cacheableOperations: string[], scriptOutputs: {
     [name: string]: string;
 }): void;
+/**
+ * Locate-by-target upsert against an in-memory `targetDefaults` array.
+ * Used by `nx init` code paths that operate on raw JSON before a Tree
+ * exists — generators should use `upsertTargetDefault` from devkit instead.
+ */
+export declare function upsertTargetDefaultEntry(entries: TargetDefaultEntry[], target: string, patch: Partial<TargetDefaultEntry>): void;
 export declare function createNxJsonFromTurboJson(turboJson: Record<string, any>): NxJsonConfiguration;
 export declare function addDepsToPackageJson(repoRoot: string, additionalPackages?: string[]): void;
 export declare function updateGitIgnore(root: string): void;

package/dist/src/command-line/init/implementation/utils.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createNxJsonFile = createNxJsonFile;
+exports.upsertTargetDefaultEntry = upsertTargetDefaultEntry;
 exports.createNxJsonFromTurboJson = createNxJsonFromTurboJson;
 exports.addDepsToPackageJson = addDepsToPackageJson;
 exports.updateGitIgnore = updateGitIgnore;
@@ -34,27 +35,37 @@ function createNxJsonFile(repoRoot, topologicalTargets, cacheableOperations, scr
     }
     catch { }
     nxJson.$schema = './node_modules/nx/schemas/nx-schema.json';
-    nxJson.targetDefaults ??= {};
+    const entries = Array.isArray(nxJson.targetDefaults)
+        ? [...nxJson.targetDefaults]
+        : [];
     if (topologicalTargets.length > 0) {
         for (const scriptName of topologicalTargets) {
-            nxJson.targetDefaults[scriptName] ??= {};
-            nxJson.targetDefaults[scriptName] = { dependsOn: [`^${scriptName}`] };
+            upsertTargetDefaultEntry(entries, scriptName, {
+                dependsOn: [`^${scriptName}`],
+            });
         }
     }
     for (const [scriptName, output] of Object.entries(scriptOutputs)) {
         if (!output) {
             continue;
         }
-        nxJson.targetDefaults[scriptName] ??= {};
-        nxJson.targetDefaults[scriptName].outputs = [`{projectRoot}/${output}`];
+        upsertTargetDefaultEntry(entries, scriptName, {
+            outputs: [`{projectRoot}/${output}`],
+        });
     }
     for (const target of cacheableOperations) {
-        nxJson.targetDefaults[target] ??= {};
-        nxJson.targetDefaults[target].cache ??= true;
+        const existing = findUnfilteredTargetEntry(entries, target);
+        if (existing)
+            existing.cache ??= true;
+        else
+            entries.push({ target, cache: true });
     }
-    if (Object.keys(nxJson.targetDefaults).length === 0) {
+    if (entries.length === 0) {
         delete nxJson.targetDefaults;
     }
+    else {
+        nxJson.targetDefaults = entries;
+    }
     const defaultBase = (0, deduce_default_base_1.deduceDefaultBase)();
     // Do not add defaultBase if it is inferred to be the Nx default value of main
     if (defaultBase !== 'main') {
@@ -62,6 +73,21 @@ function createNxJsonFile(repoRoot, topologicalTargets, cacheableOperations, scr
     }
     (0, fileutils_1.writeJsonFile)(nxJsonPath, nxJson);
 }
+/**
+ * Locate-by-target upsert against an in-memory `targetDefaults` array.
+ * Used by `nx init` code paths that operate on raw JSON before a Tree
+ * exists — generators should use `upsertTargetDefault` from devkit instead.
+ */
+function upsertTargetDefaultEntry(entries, target, patch) {
+    const existing = findUnfilteredTargetEntry(entries, target);
+    if (existing)
+        Object.assign(existing, patch, { target });
+    else
+        entries.push({ ...patch, target });
+}
+function findUnfilteredTargetEntry(entries, target) {
+    return entries.find((e) => e.target === target && e.projects === undefined && e.plugin === undefined);
+}
 function createNxJsonFromTurboJson(turboJson) {
     const nxJson = {
         $schema: './node_modules/nx/schemas/nx-schema.json',
@@ -88,20 +114,20 @@ function createNxJsonFromTurboJson(turboJson) {
     }
     // Handle task configurations
     if (turboJson.tasks) {
-        nxJson.targetDefaults = {};
+        const entries = [];
         for (const [taskName, taskConfig] of Object.entries(turboJson.tasks)) {
             // Skip project-specific tasks (containing #)
             if (taskName.includes('#'))
                 continue;
             const config = taskConfig;
-            nxJson.targetDefaults[taskName] = {};
+            const entry = { target: taskName };
             // Handle dependsOn
             if (config.dependsOn?.length > 0) {
-                nxJson.targetDefaults[taskName].dependsOn = config.dependsOn;
+                entry.dependsOn = config.dependsOn;
             }
             // Handle inputs
             if (config.inputs?.length > 0) {
-                nxJson.targetDefaults[taskName].inputs = config.inputs
+                entry.inputs = config.inputs
                     .map((input) => {
                     if (input === '$TURBO_DEFAULT$') {
                         return '{projectRoot}/**/*';
@@ -124,7 +150,7 @@ function createNxJsonFromTurboJson(turboJson) {
             }
             // Handle outputs
             if (config.outputs?.length > 0) {
-                nxJson.targetDefaults[taskName].outputs = config.outputs.map((output) => {
+                entry.outputs = config.outputs.map((output) => {
                     // Don't add projectRoot if it's already there
                     if (output.startsWith('{projectRoot}/'))
                         return output;
@@ -136,7 +162,11 @@ function createNxJsonFromTurboJson(turboJson) {
                 });
             }
             // Handle cache setting - true by default in Turbo
-            nxJson.targetDefaults[taskName].cache = config.cache !== false;
+            entry.cache = config.cache !== false;
+            entries.push(entry);
+        }
+        if (entries.length > 0) {
+            nxJson.targetDefaults = entries;
         }
     }
     /**

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

@@ -68,7 +68,7 @@ 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. Defaults to 'all' (or prompts in an interactive terminal when targeting Nx).",
+        describe: "Restrict which packages to migrate. Only applies when migrating Nx itself. 'first-party' processes only Nx and its plugins (the target package plus its nx.packageGroup); 'third-party' processes only the third-party dependencies referenced by Nx packageJsonUpdates entries, catching up on any updates that may have been skipped previously; 'all' processes everything. When targeting Nx in an interactive terminal, prompts for the value if not provided; otherwise defaults to 'all'.",
         type: 'string',
         choices: ['first-party', 'third-party', 'all'],
     })

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

@@ -2,11 +2,14 @@ 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 { type MultiMajorMode } from './multi-major';
 import { filterDowngradedUpdates } from './update-filters';
 import { normalizeVersion } from './version-utils';
 export { normalizeVersion };
 export interface ResolvedMigrationConfiguration extends MigrationsJson {
     packageGroup?: ArrayPackageGroup;
+    /** Prompt file contents keyed by the `prompt` value as it appears on the migration entry. */
+    resolvedPromptFiles?: Record<string, string>;
 }
 type CommandFailure = {
     message?: string;
@@ -14,6 +17,7 @@ type CommandFailure = {
     stdout?: string | Buffer;
 };
 export declare function formatCommandFailure(command: string, error: CommandFailure): string;
+export type MigrateMode = 'first-party' | 'third-party' | 'all';
 export interface MigratorOptions {
     packageJson?: PackageJson;
     nxInstallation?: NxJsonConfiguration['installation'];
@@ -33,7 +37,7 @@ export interface MigratorOptions {
      * - 'third-party' keeps only packages NOT in `firstPartyPackages`
      * - 'all' / undefined keeps all packages (no filtering)
      */
-    mode?: 'first-party' | 'third-party' | 'all';
+    mode?: MigrateMode;
     /** First-party package names used by `mode` for filtering. */
     firstPartyPackages?: ReadonlySet<string>;
 }
@@ -55,6 +59,8 @@ export declare class Migrator {
     constructor(opts: MigratorOptions);
     private fetchMigrationConfig;
     migrate(targetPackage: string, targetVersion: string): Promise<{
+        minVersionWithSkippedUpdates: string;
+        promptContents?: Record<string, string>;
         packageUpdates: Record<string, PackageUpdate>;
         migrations: {
             package: string;
@@ -63,9 +69,9 @@ export declare class Migrator {
             description?: string;
             implementation?: string;
             factory?: string;
+            prompt?: string;
             requires?: Record<string, string>;
         }[];
-        minVersionWithSkippedUpdates: string;
     }>;
     private createMigrateJson;
     private buildPackageJsonUpdates;
@@ -106,10 +112,10 @@ export declare class Migrator {
  * walking the cascade.
  */
 export declare function resolveCanonicalNxPackage(targetVersion: string): 'nx' | '@nrwl/workspace';
-export declare function resolveMode(mode: 'first-party' | 'third-party' | 'all' | undefined, targetPackage: string, targetVersion: string, context?: {
+export declare function resolveMode(mode: MigrateMode | undefined, targetPackage: string, targetVersion: string, context?: {
     hasFrom: boolean;
     hasExcludeAppliedMigrations: boolean;
-}): Promise<'first-party' | 'third-party' | 'all'>;
+}): Promise<MigrateMode>;
 type GenerateMigrations = {
     type: 'generateMigrations';
     targetPackage: string;
@@ -122,7 +128,19 @@ type GenerateMigrations = {
     };
     interactive?: boolean;
     excludeAppliedMigrations?: boolean;
-    mode: 'first-party' | 'third-party' | 'all';
+    mode: MigrateMode;
+    /**
+     * Set when multi-major redirected `targetVersion` to an incremental step
+     * (gradual mode or the interactive prompt picking a smaller jump). Holds
+     * the concrete resolved target so Next Steps can suggest re-running toward
+     * it.
+     */
+    originalTargetVersion?: string;
+    /**
+     * The `--multi-major-mode` value to propagate to a continuation command,
+     * or undefined to omit it. See `MultiMajorResult.gradual` for when it's set.
+     */
+    multiMajorMode?: MultiMajorMode;
 };
 type RunMigrations = {
     type: 'runMigrations';

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

@@ -48,6 +48,7 @@ const format_changed_files_with_prettier_if_available_1 = require("../../generat
 const provenance_1 = require("../../utils/provenance");
 const catalog_1 = require("../../utils/catalog");
 const multi_major_1 = require("./multi-major");
+const prompt_files_1 = require("./prompt-files");
 const update_filters_1 = require("./update-filters");
 Object.defineProperty(exports, "filterDowngradedUpdates", { enumerable: true, get: function () { return update_filters_1.filterDowngradedUpdates; } });
 const version_utils_1 = require("./version-utils");
@@ -122,14 +123,16 @@ class Migrator {
             addToPackageJson: false,
         });
         this.applyModeFilter();
-        const migrations = await this.createMigrateJson();
+        const { migrations, promptContents } = await this.createMigrateJson();
         return {
             packageUpdates: this.packageUpdates,
             migrations,
+            ...(Object.keys(promptContents).length > 0 ? { promptContents } : {}),
             minVersionWithSkippedUpdates: this.minVersionWithSkippedUpdates,
         };
     }
     async createMigrateJson() {
+        const promptContents = {};
         const migrations = await Promise.all(Object.keys(this.packageUpdates).map(async (packageName) => {
             if (this.packageUpdates[packageName].ignoreMigrations) {
                 return [];
@@ -138,10 +141,15 @@ class Migrator {
             if (currentVersion === null)
                 return [];
             const { version } = this.packageUpdates[packageName];
-            const { generators } = await this.fetchMigrationConfig(packageName, version);
-            if (!generators)
+            const { generators: migrationEntries, resolvedPromptFiles } = await this.fetchMigrationConfig(packageName, version);
+            if (!migrationEntries)
                 return [];
-            return Object.entries(generators)
+            if (resolvedPromptFiles) {
+                for (const [promptPath, content] of Object.entries(resolvedPromptFiles)) {
+                    promptContents[(0, prompt_files_1.promptContentKey)(packageName, promptPath)] = content;
+                }
+            }
+            return Object.entries(migrationEntries)
                 .filter(([, migration]) => migration.version &&
                 this.gt(migration.version, currentVersion) &&
                 this.lte(migration.version, version) &&
@@ -152,7 +160,7 @@ class Migrator {
                 name: migrationName,
             }));
         }));
-        return migrations.flat();
+        return { migrations: migrations.flat(), promptContents };
     }
     async buildPackageJsonUpdates(targetPackage, target) {
         const packagesToCheck = await this.populatePackageJsonUpdatesAndGetPackagesToCheck(targetPackage, target);
@@ -250,7 +258,7 @@ class Migrator {
         if (ignorePackageGroup) {
             return [];
         }
-        const packageGroup = packageName === '@nrwl/workspace' && (0, semver_1.lt)(targetVersion, '14.0.0-beta.0')
+        const packageGroup = packageName === '@nrwl/workspace' && (0, version_utils_1.isLegacyEra)(targetVersion)
             ? LEGACY_NRWL_PACKAGE_GROUP
             : (migrationConfig.packageGroup ?? []);
         let packageGroupOrder = [];
@@ -503,9 +511,7 @@ function resolveFirstPartyPackages(targetPackage, packageGroup) {
  * walking the cascade.
  */
 function resolveCanonicalNxPackage(targetVersion) {
-    return (0, semver_1.valid)(targetVersion) && (0, semver_1.lt)(targetVersion, '14.0.0-beta.0')
-        ? '@nrwl/workspace'
-        : 'nx';
+    return (0, version_utils_1.isLegacyEra)(targetVersion) ? '@nrwl/workspace' : 'nx';
 }
 async function resolveMode(mode, targetPackage, targetVersion, context = {
     hasFrom: false,
@@ -588,9 +594,9 @@ async function parseTargetPackageAndVersion(args) {
         // on the registry
         const targetVersion = await (0, version_utils_1.normalizeVersionWithTagCheck)('nx', args);
         const isDistTag = version_utils_1.DIST_TAGS.includes(args);
-        const targetPackage = !isDistTag && (0, semver_1.lt)(targetVersion, '14.0.0-beta.0')
-            ? '@nrwl/workspace'
-            : 'nx';
+        const targetPackage = isDistTag
+            ? 'nx'
+            : resolveCanonicalNxPackage(targetVersion);
         return { targetPackage, targetVersion };
     }
     return { targetPackage: args, targetVersion: 'latest' };
@@ -602,6 +608,9 @@ async function parseMigrationsOptions(options) {
     if (options.mode && options.runMigrations) {
         throw new Error(`Error: '--mode' cannot be combined with '--run-migrations'.`);
     }
+    if (options.multiMajorMode && options.runMigrations) {
+        throw new Error(`Error: '--multi-major-mode' cannot be combined with '--run-migrations'.`);
+    }
     if (options.runMigrations) {
         return {
             type: 'runMigrations',
@@ -625,12 +634,13 @@ async function parseMigrationsOptions(options) {
     // Spec §10: prompt or warn when crossing more than one major boundary.
     // Each major's metadata may have pruned migrations from much-older versions,
     // so jumping multiple majors at once can silently skip migrations.
-    targetVersion = await (0, multi_major_1.maybePromptOrWarnMultiMajorMigration)({
+    const multiMajorResult = await (0, multi_major_1.maybePromptOrWarnMultiMajorMigration)({
         mode,
         options,
         targetPackage,
         targetVersion,
     });
+    targetVersion = multiMajorResult.chosen;
     if (mode === 'third-party') {
         assertThirdPartyTargetBounds({
             targetPackage,
@@ -648,6 +658,8 @@ async function parseMigrationsOptions(options) {
         interactive: options.interactive,
         excludeAppliedMigrations: options.excludeAppliedMigrations,
         mode,
+        originalTargetVersion: multiMajorResult.originalTarget,
+        multiMajorMode: multiMajorResult.gradual ? 'gradual' : undefined,
     };
 }
 function assertThirdPartyModeFlagCompatibility(options) {
@@ -708,7 +720,7 @@ async function resolveTargetAndMode(args) {
         targetVersion = 'latest';
     }
     if (options.mode && !(0, version_utils_1.isNxEquivalentTarget)(targetPackage, targetVersion)) {
-        const isLegacy = (0, semver_1.valid)(targetVersion) && (0, semver_1.lt)(targetVersion, '14.0.0-beta.0');
+        const isLegacy = (0, version_utils_1.isLegacyEra)(targetVersion);
         const validTargets = isLegacy
             ? `'@nrwl/workspace'`
             : `'nx' or '@nx/workspace'`;
@@ -767,10 +779,10 @@ function assertThirdPartyTargetBounds(args) {
 function resolveInstalledCanonical() {
     const installedNx = (0, installed_nx_version_1.getInstalledNxVersion)();
     if (installedNx) {
-        if ((0, semver_1.lt)(installedNx, '14.0.0-beta.0')) {
-            return { canonical: '@nrwl/workspace', version: installedNx };
-        }
-        return { canonical: 'nx', version: installedNx };
+        return {
+            canonical: resolveCanonicalNxPackage(installedNx),
+            version: installedNx,
+        };
     }
     const installedLegacy = (0, installed_nx_version_1.getInstalledLegacyNrwlWorkspaceVersion)();
     if (installedLegacy) {
@@ -923,11 +935,22 @@ async function downloadPackageMigrationsFromRegistry(packageName, packageVersion
     let result;
     try {
         const { tarballPath } = await (0, package_manager_1.packageRegistryPack)(dir, packageName, packageVersion);
-        const migrations = await (0, fileutils_1.extractFileFromTarball)((0, path_1.join)(dir, tarballPath), (0, path_2.joinPathFragments)('package', migrationsFilePath), (0, path_1.join)(dir, migrationsFilePath)).then((path) => (0, fileutils_1.readJsonFile)(path));
-        result = { ...migrations, packageGroup, version: packageVersion };
-    }
-    catch {
-        throw new Error(`Failed to find migrations file "${migrationsFilePath}" in package "${packageName}@${packageVersion}".`);
+        const fullTarballPath = (0, path_1.join)(dir, tarballPath);
+        let migrations;
+        try {
+            migrations = await (0, fileutils_1.extractFileFromTarball)(fullTarballPath, (0, path_2.joinPathFragments)('package', migrationsFilePath), (0, path_1.join)(dir, migrationsFilePath)).then((path) => (0, fileutils_1.readJsonFile)(path));
+        }
+        catch {
+            throw new Error(`Failed to find migrations file "${migrationsFilePath}" in package "${packageName}@${packageVersion}".`);
+        }
+        (0, prompt_files_1.validateMigrationEntries)(packageName, packageVersion, migrations);
+        const resolvedPromptFiles = await (0, prompt_files_1.extractPromptFilesFromTarball)(packageName, packageVersion, migrations, migrationsFilePath, fullTarballPath, dir);
+        result = {
+            ...migrations,
+            packageGroup,
+            version: packageVersion,
+            ...(resolvedPromptFiles ? { resolvedPromptFiles } : {}),
+        };
     }
     finally {
         await cleanup();
@@ -981,10 +1004,18 @@ async function getPackageMigrationsUsingInstallImpl(packageName, packageVersion)
         });
         const { migrations: migrationsFilePath, packageGroup, packageJson, } = readPackageMigrationConfig(packageName, dir);
         let migrations = undefined;
+        let resolvedPromptFiles;
         if (migrationsFilePath) {
             migrations = (0, fileutils_1.readJsonFile)(migrationsFilePath);
-        }
-        result = { ...migrations, packageGroup, version: packageJson.version };
+            (0, prompt_files_1.validateMigrationEntries)(packageName, packageVersion, migrations);
+            resolvedPromptFiles = await (0, prompt_files_1.readPromptFilesFromInstall)(packageName, packageVersion, migrations, migrationsFilePath);
+        }
+        result = {
+            ...migrations,
+            packageGroup,
+            version: packageJson.version,
+            ...(resolvedPromptFiles ? { resolvedPromptFiles } : {}),
+        };
     }
     catch (e) {
         const pmc = (0, package_manager_1.getPackageManagerCommand)((0, package_manager_1.detectPackageManager)(dir), dir);
@@ -1191,8 +1222,7 @@ async function generateMigrationsJsonAndUpdatePackageJson(root, opts) {
             // `LEGACY_NRWL_PACKAGE_GROUP` for that case, and the post-build
             // third-party filter must mirror that set or first-party `@nrwl/*`
             // plugins slip past it.
-            const packageGroup = sourcePackage === '@nrwl/workspace' &&
-                (0, semver_1.lt)(opts.targetVersion, '14.0.0-beta.0')
+            const packageGroup = sourcePackage === '@nrwl/workspace' && (0, version_utils_1.isLegacyEra)(opts.targetVersion)
                 ? LEGACY_NRWL_PACKAGE_GROUP
                 : rootMetadata.packageGroup;
             firstPartyPackages = resolveFirstPartyPackages(sourcePackage, packageGroup);
@@ -1210,7 +1240,7 @@ async function generateMigrationsJsonAndUpdatePackageJson(root, opts) {
             mode,
             firstPartyPackages,
         });
-        const { migrations, packageUpdates, minVersionWithSkippedUpdates } = await migrator.migrate(walkedTargetPackage, opts.targetVersion);
+        const { migrations, packageUpdates, promptContents, minVersionWithSkippedUpdates, } = await migrator.migrate(walkedTargetPackage, opts.targetVersion);
         // The cascade collects packageJsonUpdates entries against the cascade
         // root's installed version, but inner per-package pins are only gated
         // against the in-flight cascade tally — not against each inner package's
@@ -1221,6 +1251,7 @@ async function generateMigrationsJsonAndUpdatePackageJson(root, opts) {
         const writableUpdates = (0, update_filters_1.filterDowngradedUpdates)(packageUpdates, originalPackageJson, installedPackageVersions);
         const wrotePackageJson = await updatePackageJson(root, writableUpdates);
         const wroteNxJsonInstallation = await updateInstallationDetails(root, writableUpdates);
+        const promptMigrationFiles = (0, prompt_files_1.writePromptMigrationFiles)(root, migrations, promptContents ?? {}, packageUpdates[walkedTargetPackage].version);
         if (migrations.length > 0) {
             await createMigrationsFile(root, [
                 ...addSplitConfigurationMigrationIfAvailable(from, writableUpdates),
@@ -1258,6 +1289,11 @@ async function generateMigrationsJsonAndUpdatePackageJson(root, opts) {
                 migrations.length > 0
                     ? `- migrations.json has been generated.`
                     : `- There are no migrations to run, so migrations.json has not been created.`,
+                ...(promptMigrationFiles.length > 0
+                    ? [
+                        `- ${promptMigrationFiles.length} AI migration prompt(s) have been written to ${prompt_files_1.AI_MIGRATIONS_DIR}/.`,
+                    ]
+                    : []),
             ],
         });
         try {
@@ -1291,9 +1327,21 @@ async function generateMigrationsJsonAndUpdatePackageJson(root, opts) {
             ]
             : [
                 `- Make sure package.json changes make sense and then run '${pmc.install}',`,
+                ...(promptMigrationFiles.length > 0
+                    ? [
+                        `- Review and tweak the AI migration prompts in ${prompt_files_1.AI_MIGRATIONS_DIR}/ as needed.`,
+                    ]
+                    : []),
                 ...(migrations.length > 0
                     ? [`- Run '${pmc.exec} nx migrate --run-migrations'`]
                     : []),
+                ...(opts.originalTargetVersion
+                    ? [
+                        `- After applying these migrations, run '${pmc.exec} nx migrate ${opts.targetPackage}@${opts.originalTargetVersion} --mode=${opts.mode}${opts.multiMajorMode === 'gradual'
+                            ? ` ${multi_major_1.MULTI_MAJOR_MODE_FLAG}=gradual`
+                            : ''}' to continue toward your original target.`,
+                    ]
+                    : []),
                 ...(opts.interactive && minVersionWithSkippedUpdates
                     ? [
                         `- You opted out of some migrations for now. Write the following command down somewhere to apply these migrations later:`,

package/dist/src/command-line/migrate/multi-major.d.ts

@@ -1,9 +1,30 @@
+import type { MigrateMode } from './migrate';
+export declare const MULTI_MAJOR_MODE_FLAG = "--multi-major-mode";
 export type MultiMajorMode = 'direct' | 'gradual';
+/**
+ * Result of running the multi-major check.
+ *
+ * - `chosen`: the version to actually migrate to (always concrete semver when
+ *   the function ran past the dist-tag resolution; otherwise the input value).
+ * - `originalTarget`: set only when an actual redirect happened (gradual mode
+ *   auto-picked a smaller step, OR the interactive prompt returned a version
+ *   different from the resolved target). Holds the concrete resolved target
+ *   so callers can suggest re-running toward it.
+ * - `gradual`: set only when the redirect came from gradual mode (flag or
+ *   env). Tells callers it's safe to propagate `--multi-major-mode=gradual`
+ *   to a continuation command; left unset when the redirect came from the
+ *   interactive prompt so the user isn't silently locked into gradual.
+ */
+export type MultiMajorResult = {
+    chosen: string;
+    originalTarget?: string;
+    gradual?: boolean;
+};
 export declare function maybePromptOrWarnMultiMajorMigration(args: {
-    mode: 'first-party' | 'third-party' | 'all';
+    mode: MigrateMode;
     options: {
         multiMajorMode?: MultiMajorMode;
     };
     targetPackage: string;
     targetVersion: string;
-}): Promise<string>;
+}): Promise<MultiMajorResult>;