nx 23.0.0-beta.11 → 23.0.0-beta.12

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>;

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

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MULTI_MAJOR_MODE_FLAG = void 0;
 exports.maybePromptOrWarnMultiMajorMigration = maybePromptOrWarnMultiMajorMigration;
 const enquirer_1 = require("enquirer");
 const semver_1 = require("semver");
@@ -8,7 +9,8 @@ const installed_nx_version_1 = require("../../utils/installed-nx-version");
 const output_1 = require("../../utils/output");
 const package_manager_1 = require("../../utils/package-manager");
 const version_utils_1 = require("./version-utils");
-const STEPWISE_DOC_URL = 'https://nx.dev/docs/guides/tips-n-tricks/advanced-update#one-major-version-at-a-time-small-steps';
+const INCREMENTAL_UPDATE_GUIDE_URL = 'https://nx.dev/docs/guides/tips-n-tricks/advanced-update#one-major-version-at-a-time-small-steps';
+exports.MULTI_MAJOR_MODE_FLAG = '--multi-major-mode';
 const MULTI_MAJOR_MODE_ENV = 'NX_MULTI_MAJOR_MODE';
 // Caret-major (`^X.0.0`) excludes prereleases per semver, so
 // `resolvePackageVersionUsingRegistry` returns the highest stable in major X.
@@ -24,23 +26,30 @@ async function resolveLatestStableInMajor(packageName, majorVersion) {
 const multiMajorHeader = (pkg, installed, target) => `Migrating across multiple major versions: ${pkg}@${installed} → ${pkg}@${target}.`;
 const multiMajorBodyLines = [
     `The recommended process is to update one major version at a time, in small steps.`,
-    `See ${STEPWISE_DOC_URL}`,
+    `See ${INCREMENTAL_UPDATE_GUIDE_URL}`,
 ];
 function warnMultiMajorMigration(targetPackage, installed, target) {
     output_1.output.warn({
         title: multiMajorHeader(targetPackage, installed, target),
         bodyLines: [
             ...multiMajorBodyLines,
-            `Pass --multi-major-mode=direct (or =gradual) or set ${MULTI_MAJOR_MODE_ENV} to silence this warning.`,
+            `Pass ${exports.MULTI_MAJOR_MODE_FLAG}=direct (or =gradual) or set ${MULTI_MAJOR_MODE_ENV} to silence this warning.`,
         ],
     });
 }
 function logGradualStep(targetPackage, step, target) {
+    // Status-only announcement. The follow-up instruction ("re-run `nx migrate`
+    // to continue toward the original target") lives in the Next Steps block at
+    // the end of the run, where it's adjacent to the other re-run guidance and
+    // not scrolled out of view by the migration output.
     output_1.output.log({
         title: `Migrating to ${targetPackage}@${step} (one step toward ${targetPackage}@${target}).`,
-        bodyLines: [
-            `Re-run \`nx migrate\` after this completes to continue toward ${targetPackage}@${target}.`,
-        ],
+    });
+}
+function warnGradualUnavailable(targetPackage, target, reason) {
+    output_1.output.warn({
+        title: `Could not look up incremental migration options for ${exports.MULTI_MAJOR_MODE_FLAG}=gradual. Proceeding directly to ${targetPackage}@${target}.`,
+        bodyLines: [reason],
     });
 }
 // Returns the chosen target version. Caller replaces `targetVersion` with it.
@@ -92,12 +101,13 @@ async function maybePromptOrWarnMultiMajorMigration(args) {
     const { mode, options, targetPackage } = args;
     let { targetVersion } = args;
     if (mode === 'third-party')
-        return targetVersion;
+        return { chosen: targetVersion };
     const multiMajorMode = resolveMultiMajorMode(options);
     if (multiMajorMode === 'direct')
-        return targetVersion;
-    if (!(0, version_utils_1.isNxEquivalentTarget)(targetPackage, targetVersion))
-        return targetVersion;
+        return { chosen: targetVersion };
+    if (!(0, version_utils_1.isNxEquivalentTarget)(targetPackage, targetVersion)) {
+        return { chosen: targetVersion };
+    }
     // Bare-package-name positionals (e.g. `nx migrate nx`, `nx migrate
     // @nx/workspace`) leave `targetVersion` as the literal `'latest'` because
     // `parseTargetPackageAndVersion` only resolves dist-tags via the registry
@@ -108,35 +118,38 @@ async function maybePromptOrWarnMultiMajorMigration(args) {
             targetVersion = await (0, version_utils_1.normalizeVersionWithTagCheck)(targetPackage, targetVersion);
         }
         catch {
-            return targetVersion;
+            if (multiMajorMode === 'gradual') {
+                warnGradualUnavailable(targetPackage, targetVersion, `Failed to resolve the '${targetVersion}' dist-tag against the registry.`);
+            }
+            return { chosen: targetVersion };
         }
     }
-    if (!(0, semver_1.valid)(targetVersion) || (0, semver_1.lt)(targetVersion, '14.0.0-beta.0')) {
-        return targetVersion;
+    if (!(0, semver_1.valid)(targetVersion) || (0, version_utils_1.isLegacyEra)(targetVersion)) {
+        return { chosen: targetVersion };
     }
     const installed = (0, installed_nx_version_1.getInstalledNxVersion)();
     if (!installed || !(0, semver_1.valid)(installed))
-        return targetVersion;
+        return { chosen: targetVersion };
     // Legacy-era installs are out of scope for the multi-major check.
-    if ((0, semver_1.lt)(installed, '14.0.0-beta.0'))
-        return targetVersion;
+    if ((0, version_utils_1.isLegacyEra)(installed))
+        return { chosen: targetVersion };
     const installedMajor = (0, semver_1.major)(installed);
-    if ((0, semver_1.major)(targetVersion) - installedMajor < 2)
-        return targetVersion;
+    if ((0, semver_1.major)(targetVersion) - installedMajor < 2) {
+        return { chosen: targetVersion };
+    }
     const interactive = !!process.stdin.isTTY && !(0, is_ci_1.isCI)();
     // Non-TTY without gradual opt-in stays on the warn-only path; avoid the
-    // registry round-trip used to resolve stepwise options.
+    // registry round-trip used to look up incremental migration options.
     if (!interactive && multiMajorMode !== 'gradual') {
         warnMultiMajorMigration(targetPackage, installed, targetVersion);
-        return targetVersion;
+        return { chosen: targetVersion };
     }
     const [latestInCurrent, latestInNext] = await Promise.all([
         resolveLatestStableInMajor(targetPackage, installedMajor),
         resolveLatestStableInMajor(targetPackage, installedMajor + 1),
     ]);
     // Only suggest the current-major latest when there's at least a minor
-    // delta — a same-minor patch bump isn't a meaningful "step" in stepwise
-    // migration framing.
+    // delta — a same-minor patch bump isn't a meaningful incremental step.
     const showCurrent = latestInCurrent &&
         (0, semver_1.gt)(latestInCurrent, installed) &&
         (0, semver_1.minor)(latestInCurrent) > (0, semver_1.minor)(installed)
@@ -146,21 +159,27 @@ async function maybePromptOrWarnMultiMajorMigration(args) {
         const step = showCurrent ?? latestInNext;
         if (step) {
             logGradualStep(targetPackage, step, targetVersion);
-            return step;
+            return { chosen: step, originalTarget: targetVersion, gradual: true };
         }
-        // No stepwise option resolved → the requested target is effectively the
-        // stepwise pick. Honour `gradual` silently.
-        return targetVersion;
+        // Registry returned no eligible incremental version (or the lookup
+        // failed); without a step to land on, gradual silently degrades to direct.
+        // Surface that explicitly so the safety rail the user opted into isn't
+        // invisibly disabled.
+        warnGradualUnavailable(targetPackage, targetVersion, `Could not find an eligible version in major ${installedMajor} or ${installedMajor + 1} (registry lookup returned no result or failed).`);
+        return { chosen: targetVersion };
     }
     if (interactive && (showCurrent || latestInNext)) {
-        return promptMultiMajorMigration({
+        const chosen = await promptMultiMajorMigration({
             targetPackage,
             installed,
             target: targetVersion,
             latestInCurrent: showCurrent,
             latestInNext,
         });
+        return chosen !== targetVersion
+            ? { chosen, originalTarget: targetVersion }
+            : { chosen };
     }
     warnMultiMajorMigration(targetPackage, installed, targetVersion);
-    return targetVersion;
+    return { chosen: targetVersion };
 }

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

@@ -0,0 +1,12 @@
+import { MigrationsJson } from '../../config/misc-interfaces';
+export declare const AI_MIGRATIONS_DIR: string;
+export declare function promptContentKey(packageName: string, promptRelPath: string): string;
+export declare function validateMigrationEntries(packageName: string, packageVersion: string, migrations: MigrationsJson): void;
+export declare function extractPromptFilesFromTarball(packageName: string, packageVersion: string, migrations: MigrationsJson, migrationsFilePath: string, fullTarballPath: string, destDir: string): Promise<Record<string, string> | undefined>;
+export declare function readPromptFilesFromInstall(packageName: string, packageVersion: string, migrations: MigrationsJson, migrationsFilePath: string): Promise<Record<string, string> | undefined>;
+export declare function writePromptMigrationFiles(root: string, migrations: {
+    package: string;
+    name: string;
+    version: string;
+    prompt?: string;
+}[], promptContents: Record<string, string>, targetVersion: string): string[];

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

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AI_MIGRATIONS_DIR = void 0;
+exports.promptContentKey = promptContentKey;
+exports.validateMigrationEntries = validateMigrationEntries;
+exports.extractPromptFilesFromTarball = extractPromptFilesFromTarball;
+exports.readPromptFilesFromInstall = readPromptFilesFromInstall;
+exports.writePromptMigrationFiles = writePromptMigrationFiles;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const fileutils_1 = require("../../utils/fileutils");
+const path_2 = require("../../utils/path");
+exports.AI_MIGRATIONS_DIR = (0, path_2.joinPathFragments)('tools', 'ai-migrations');
+function promptContentKey(packageName, promptRelPath) {
+    return `${packageName}::${promptRelPath}`;
+}
+function* iterateMigrationEntries(migrations) {
+    const merged = { ...migrations.schematics, ...migrations.generators };
+    yield* Object.entries(merged);
+}
+function validateMigrationEntries(packageName, packageVersion, migrations) {
+    for (const [migrationName, entry] of iterateMigrationEntries(migrations)) {
+        if (!entry.implementation && !entry.factory && !entry.prompt) {
+            throw new Error(`Invalid migration "${migrationName}" in package "${packageName}@${packageVersion}": migration entries must have at least one of "implementation", "factory", or "prompt".`);
+        }
+    }
+}
+async function resolvePromptFiles(packageName, packageVersion, migrations, migrationsDir, resolveContent) {
+    const resolvedPromptFiles = {};
+    for (const [migrationName, entry] of iterateMigrationEntries(migrations)) {
+        if (!entry.prompt || resolvedPromptFiles[entry.prompt] !== undefined) {
+            continue;
+        }
+        assertPromptPathWithinMigrationsDir(migrationsDir, entry.prompt, packageName, packageVersion);
+        try {
+            resolvedPromptFiles[entry.prompt] = await resolveContent(entry.prompt);
+        }
+        catch (e) {
+            throw new Error(`Could not find prompt file "${entry.prompt}" for migration "${migrationName}" in package "${packageName}@${packageVersion}".`, { cause: e });
+        }
+    }
+    return Object.keys(resolvedPromptFiles).length > 0
+        ? resolvedPromptFiles
+        : undefined;
+}
+function assertPromptPathWithinMigrationsDir(migrationsDir, promptRelPath, packageName, packageVersion) {
+    const rel = (0, path_1.relative)(migrationsDir, (0, path_1.join)(migrationsDir, promptRelPath));
+    if ((0, path_1.isAbsolute)(promptRelPath) ||
+        rel === '..' ||
+        rel.startsWith(`..${path_1.sep}`) ||
+        rel.startsWith(`..${path_1.posix.sep}`)) {
+        throw new Error(`Invalid prompt path "${promptRelPath}" in package "${packageName}@${packageVersion}": prompt paths must be relative and resolve within the package's migrations directory.`);
+    }
+}
+function extractPromptFilesFromTarball(packageName, packageVersion, migrations, migrationsFilePath, fullTarballPath, destDir) {
+    const migrationsDir = (0, path_1.dirname)(migrationsFilePath);
+    return resolvePromptFiles(packageName, packageVersion, migrations, migrationsDir, async (promptRelPath) => {
+        const promptInTarball = (0, path_2.joinPathFragments)('package', migrationsDir, promptRelPath);
+        const promptDest = (0, path_1.join)(destDir, migrationsDir, promptRelPath);
+        await (0, fileutils_1.extractFileFromTarball)(fullTarballPath, promptInTarball, promptDest);
+        return (0, fs_1.readFileSync)(promptDest, 'utf-8');
+    });
+}
+function readPromptFilesFromInstall(packageName, packageVersion, migrations, migrationsFilePath) {
+    const migrationsDir = (0, path_1.dirname)(migrationsFilePath);
+    return resolvePromptFiles(packageName, packageVersion, migrations, migrationsDir, (promptRelPath) => (0, fs_1.readFileSync)((0, path_1.join)(migrationsDir, promptRelPath), 'utf-8'));
+}
+function writePromptMigrationFiles(root, migrations, promptContents, targetVersion) {
+    const sourceToChosen = new Map();
+    const result = [];
+    for (const migration of migrations) {
+        if (!migration.prompt)
+            continue;
+        const sourceKey = promptContentKey(migration.package, migration.prompt);
+        const content = promptContents[sourceKey];
+        if (content === undefined)
+            continue;
+        const cached = sourceToChosen.get(sourceKey);
+        if (cached !== undefined) {
+            migration.prompt = cached;
+            continue;
+        }
+        const baseName = path_1.posix.basename(migration.prompt);
+        const ext = path_1.posix.extname(baseName);
+        const stem = ext ? baseName.slice(0, -ext.length) : baseName;
+        const destDir = (0, path_2.joinPathFragments)(exports.AI_MIGRATIONS_DIR, migration.package, targetVersion);
+        let chosenPath;
+        for (let n = 0;; n++) {
+            const candidate = (0, path_2.joinPathFragments)(destDir, n === 0 ? baseName : `${stem}-${n}${ext}`);
+            const absCandidate = (0, path_1.join)(root, candidate);
+            if (!(0, fs_1.existsSync)(absCandidate)) {
+                (0, fs_1.mkdirSync)((0, path_1.dirname)(absCandidate), { recursive: true });
+                (0, fs_1.writeFileSync)(absCandidate, content);
+                result.push(candidate);
+                chosenPath = candidate;
+                break;
+            }
+            if ((0, fs_1.readFileSync)(absCandidate, 'utf-8') === content) {
+                chosenPath = candidate;
+                break;
+            }
+        }
+        sourceToChosen.set(sourceKey, chosenPath);
+        migration.prompt = chosenPath;
+    }
+    return result;
+}