nx 23.0.0-beta.2 → 23.0.0-beta.21

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

@@ -0,0 +1,8 @@
+interface MigrationShape {
+    prompt?: string;
+    implementation?: string;
+    factory?: string;
+}
+export declare function isPromptOnlyMigration(m: MigrationShape): boolean;
+export declare function isHybridMigration(m: MigrationShape): boolean;
+export {};

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

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPromptOnlyMigration = isPromptOnlyMigration;
+exports.isHybridMigration = isHybridMigration;
+function hasDeterministicImplementation(m) {
+    return !!(m.implementation || m.factory);
+}
+function isPromptOnlyMigration(m) {
+    return !!m.prompt && !hasDeterministicImplementation(m);
+}
+function isHybridMigration(m) {
+    return !!m.prompt && hasDeterministicImplementation(m);
+}

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

@@ -0,0 +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: MigrateMode;
+    options: {
+        multiMajorMode?: MultiMajorMode;
+    };
+    targetPackage: string;
+    targetVersion: string;
+}): Promise<MultiMajorResult>;

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

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MULTI_MAJOR_MODE_FLAG = void 0;
+exports.maybePromptOrWarnMultiMajorMigration = maybePromptOrWarnMultiMajorMigration;
+const safe_prompt_1 = require("./safe-prompt");
+const semver_1 = require("semver");
+const is_ci_1 = require("../../utils/is-ci");
+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 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.
+async function resolveLatestStableInMajor(packageName, majorVersion) {
+    try {
+        const resolved = await (0, package_manager_1.resolvePackageVersionUsingRegistry)(packageName, `^${majorVersion}.0.0`);
+        return (0, semver_1.valid)(resolved) ? resolved : null;
+    }
+    catch {
+        return null;
+    }
+}
+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 ${INCREMENTAL_UPDATE_GUIDE_URL}`,
+];
+function warnMultiMajorMigration(targetPackage, installed, target) {
+    output_1.output.warn({
+        title: multiMajorHeader(targetPackage, installed, target),
+        bodyLines: [
+            ...multiMajorBodyLines,
+            `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}).`,
+    });
+}
+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.
+// At least one of `latestInCurrent`/`latestInNext` must be present.
+async function promptMultiMajorMigration(args) {
+    const choices = [];
+    let recommendedMarked = false;
+    if (args.latestInCurrent) {
+        choices.push({
+            name: args.latestInCurrent,
+            message: `Migrate to ${args.targetPackage}@${args.latestInCurrent} (latest in current major) [recommended]`,
+        });
+        recommendedMarked = true;
+    }
+    if (args.latestInNext) {
+        choices.push({
+            name: args.latestInNext,
+            message: `Migrate to ${args.targetPackage}@${args.latestInNext} (next major)${recommendedMarked ? '' : ' [recommended]'}`,
+        });
+    }
+    choices.push({
+        name: args.target,
+        message: `Migrate directly to ${args.targetPackage}@${args.target}`,
+    });
+    output_1.output.log({
+        title: multiMajorHeader(args.targetPackage, args.installed, args.target),
+        bodyLines: multiMajorBodyLines,
+    });
+    const { chosen } = await (0, safe_prompt_1.migratePrompt)({
+        type: 'select',
+        name: 'chosen',
+        message: 'How would you like to proceed?',
+        choices,
+    });
+    return chosen;
+}
+// Flag wins over env var; only the two literal values are honoured.
+function resolveMultiMajorMode(options) {
+    if (options.multiMajorMode === 'direct' ||
+        options.multiMajorMode === 'gradual') {
+        return options.multiMajorMode;
+    }
+    const env = process.env[MULTI_MAJOR_MODE_ENV];
+    if (env === 'direct' || env === 'gradual')
+        return env;
+    return undefined;
+}
+async function maybePromptOrWarnMultiMajorMigration(args) {
+    const { mode, options, targetPackage } = args;
+    let { targetVersion } = args;
+    if (mode === 'third-party')
+        return { chosen: targetVersion };
+    const multiMajorMode = resolveMultiMajorMode(options);
+    if (multiMajorMode === 'direct')
+        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
+    // when they appear standalone or after `@`. Resolve here so the remaining
+    // semver gates (and the subsequent walk) see a concrete version.
+    if (version_utils_1.DIST_TAGS.includes(targetVersion)) {
+        try {
+            targetVersion = await (0, version_utils_1.normalizeVersionWithTagCheck)(targetPackage, targetVersion);
+        }
+        catch {
+            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, version_utils_1.isLegacyEra)(targetVersion)) {
+        return { chosen: targetVersion };
+    }
+    const installed = (0, installed_nx_version_1.getInstalledNxVersion)();
+    if (!installed || !(0, semver_1.valid)(installed))
+        return { chosen: targetVersion };
+    // Legacy-era installs are out of scope for the multi-major check.
+    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 { 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 look up incremental migration options.
+    if (!interactive && multiMajorMode !== 'gradual') {
+        warnMultiMajorMigration(targetPackage, installed, 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 incremental step.
+    const showCurrent = latestInCurrent &&
+        (0, semver_1.gt)(latestInCurrent, installed) &&
+        (0, semver_1.minor)(latestInCurrent) > (0, semver_1.minor)(installed)
+        ? latestInCurrent
+        : null;
+    if (multiMajorMode === 'gradual') {
+        const step = showCurrent ?? latestInNext;
+        if (step) {
+            logGradualStep(targetPackage, step, targetVersion);
+            return { chosen: step, originalTarget: targetVersion, gradual: true };
+        }
+        // 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)) {
+        const chosen = await promptMultiMajorMigration({
+            targetPackage,
+            installed,
+            target: targetVersion,
+            latestInCurrent: showCurrent,
+            latestInNext,
+        });
+        return chosen !== targetVersion
+            ? { chosen, originalTarget: targetVersion }
+            : { chosen };
+    }
+    warnMultiMajorMigration(targetPackage, installed, targetVersion);
+    return { chosen: targetVersion };
+}

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

@@ -0,0 +1,31 @@
+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;
+/**
+ * Thrown when the markdown prompt file referenced by a migration cannot be
+ * resolved.
+ */
+export declare class PromptResolutionError extends Error {
+    readonly promptPath: string;
+    readonly migrationsDir: string;
+    constructor(promptPath: string, migrationsDir: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Resolves a migration prompt file path to an absolute path. Prompt paths are
+ * plain markdown files referenced relative to the directory containing the
+ * `migrations.json` - unlike schemas, they are not resolved through package
+ * exports or `require.resolve`. The path must stay within the migrations
+ * directory and point at an existing file.
+ */
+export declare function resolvePrompt(promptPath: string, migrationsDir: string): string;
+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,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromptResolutionError = exports.AI_MIGRATIONS_DIR = void 0;
+exports.promptContentKey = promptContentKey;
+exports.validateMigrationEntries = validateMigrationEntries;
+exports.resolvePrompt = resolvePrompt;
+exports.extractPromptFilesFromTarball = extractPromptFilesFromTarball;
+exports.readPromptFilesFromInstall = readPromptFilesFromInstall;
+exports.writePromptMigrationFiles = writePromptMigrationFiles;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const tar_1 = require("../../utils/tar");
+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 isPromptPathWithinMigrationsDir(migrationsDir, promptRelPath) {
+    const rel = (0, path_1.relative)(migrationsDir, (0, path_1.join)(migrationsDir, promptRelPath));
+    return !((0, path_1.isAbsolute)(promptRelPath) ||
+        rel === '..' ||
+        rel.startsWith(`..${path_1.sep}`) ||
+        rel.startsWith(`..${path_1.posix.sep}`));
+}
+function assertPromptPathWithinMigrationsDir(migrationsDir, promptRelPath, packageName, packageVersion) {
+    if (!isPromptPathWithinMigrationsDir(migrationsDir, promptRelPath)) {
+        throw new Error(`Invalid prompt path "${promptRelPath}" in package "${packageName}@${packageVersion}": prompt paths must be relative and resolve within the package's migrations directory.`);
+    }
+}
+/**
+ * Thrown when the markdown prompt file referenced by a migration cannot be
+ * resolved.
+ */
+class PromptResolutionError extends Error {
+    constructor(promptPath, migrationsDir, options) {
+        super(`Could not resolve prompt "${promptPath}" from "${migrationsDir}".`, options);
+        this.promptPath = promptPath;
+        this.migrationsDir = migrationsDir;
+        this.name = 'PromptResolutionError';
+    }
+}
+exports.PromptResolutionError = PromptResolutionError;
+/**
+ * Resolves a migration prompt file path to an absolute path. Prompt paths are
+ * plain markdown files referenced relative to the directory containing the
+ * `migrations.json` - unlike schemas, they are not resolved through package
+ * exports or `require.resolve`. The path must stay within the migrations
+ * directory and point at an existing file.
+ */
+function resolvePrompt(promptPath, migrationsDir) {
+    if (!isPromptPathWithinMigrationsDir(migrationsDir, promptPath)) {
+        throw new PromptResolutionError(promptPath, migrationsDir);
+    }
+    const resolvedPath = (0, path_1.join)(migrationsDir, promptPath);
+    if (!(0, fs_1.existsSync)(resolvedPath)) {
+        throw new PromptResolutionError(promptPath, migrationsDir);
+    }
+    return resolvedPath;
+}
+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, tar_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;
+}

package/dist/src/command-line/migrate/run-migration-process.js

@@ -1,4 +1,5 @@
-const { runNxOrAngularMigration } = require('./migrate');
+const { runNxOrAngularMigration, ChangedDepInstaller } = require('./migrate');
+const { commitMigrationIfRequested } = require('./migrate-commits');
 const { execSync } = require('child_process');
 
 async function runMigrationProcess() {
@@ -33,16 +34,37 @@ async function runMigrationProcess() {
       windowsHide: true,
     }).trim();
 
+    // Snapshot package.json deps now so we can detect post-migration drift
+    // and run a single install, whether commits are on or off.
+    const installer = new ChangedDepInstaller(workspacePath);
+    const installDepsIfChanged = () => installer.installDepsIfChanged();
+
     const { changes: fileChanges, nextSteps } = await runNxOrAngularMigration(
       workspacePath,
       migration,
-      false,
-      configuration.createCommits,
-      configuration.commitPrefix,
-      undefined,
-      true
+      false
     );
 
+    if (configuration.createCommits) {
+      const commitResult = await commitMigrationIfRequested(
+        workspacePath,
+        migration,
+        true,
+        configuration.commitPrefix,
+        installDepsIfChanged
+      );
+      if (commitResult.status === 'failed') {
+        // Single-migration UI child surfaces the failure via stdout (logged
+        // inside commitMigrationIfRequested) and continues with success-
+        // with-warning. The executor's absorption flow does not apply here:
+        // there is no later migration that could pick up this migration's
+        // diff, so the working tree is left in its post-migration state
+        // for the user to commit or revert through the UI.
+      }
+    } else {
+      await installDepsIfChanged();
+    }
+
     const gitRefAfter = execSync('git rev-parse HEAD', {
       cwd: workspacePath,
       encoding: 'utf-8',

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

@@ -0,0 +1,28 @@
+import { prompt as enquirerPrompt } from 'enquirer';
+/**
+ * Drop-in replacement for enquirer's `prompt()` that hardens cancel
+ * handling for every interactive prompt under `nx migrate`.
+ *
+ * Why: enquirer's built-in cancel path (`Prompt.cancel` → `close` →
+ * `keypress.js` `off` → `readline.pause`) races on `Interface.pause()`
+ * when triggered more than once in quick succession (mashed Ctrl+C),
+ * throwing `ERR_USE_AFTER_CLOSE` from an unhandled async chain that
+ * `await prompt(...)` cannot catch.
+ *
+ * In raw mode, Ctrl+C does NOT generate a SIGINT signal (the kernel's
+ * `ISIG` flag is cleared while enquirer's keypress listener is active);
+ * instead the 0x03 byte flows through `combos.js` and dispatches the
+ * `cancel` action. So a `process.on('SIGINT', ...)` handler is the wrong
+ * mechanism here — it never fires.
+ *
+ * The right hook is enquirer's per-prompt `options.cancel` override. When
+ * present, `Prompt.keypress` (lib/prompt.js:42) calls our handler INSTEAD
+ * of `this.cancel`, so enquirer's broken cleanup never runs. Both Ctrl+C
+ * (byte 0x03) and Esc map to the `cancel` action, so this single override
+ * covers both paths.
+ *
+ * The handler emits a single-line notice via `output.warn` and exits with
+ * POSIX status 130 (128 + SIGINT). Synchronous exit is correct here: the
+ * user explicitly asked to abort, there's no recovery state to preserve.
+ */
+export declare function migratePrompt<T = any>(questions: Parameters<typeof enquirerPrompt>[0]): Promise<T>;

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

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migratePrompt = migratePrompt;
+const enquirer_1 = require("enquirer");
+const output_1 = require("../../utils/output");
+/**
+ * Drop-in replacement for enquirer's `prompt()` that hardens cancel
+ * handling for every interactive prompt under `nx migrate`.
+ *
+ * Why: enquirer's built-in cancel path (`Prompt.cancel` → `close` →
+ * `keypress.js` `off` → `readline.pause`) races on `Interface.pause()`
+ * when triggered more than once in quick succession (mashed Ctrl+C),
+ * throwing `ERR_USE_AFTER_CLOSE` from an unhandled async chain that
+ * `await prompt(...)` cannot catch.
+ *
+ * In raw mode, Ctrl+C does NOT generate a SIGINT signal (the kernel's
+ * `ISIG` flag is cleared while enquirer's keypress listener is active);
+ * instead the 0x03 byte flows through `combos.js` and dispatches the
+ * `cancel` action. So a `process.on('SIGINT', ...)` handler is the wrong
+ * mechanism here — it never fires.
+ *
+ * The right hook is enquirer's per-prompt `options.cancel` override. When
+ * present, `Prompt.keypress` (lib/prompt.js:42) calls our handler INSTEAD
+ * of `this.cancel`, so enquirer's broken cleanup never runs. Both Ctrl+C
+ * (byte 0x03) and Esc map to the `cancel` action, so this single override
+ * covers both paths.
+ *
+ * The handler emits a single-line notice via `output.warn` and exits with
+ * POSIX status 130 (128 + SIGINT). Synchronous exit is correct here: the
+ * user explicitly asked to abort, there's no recovery state to preserve.
+ */
+async function migratePrompt(questions) {
+    const cancel = () => {
+        // `\n\r` → next line at column 0 (enquirer left the TTY in raw mode,
+        //   so a bare LF would not carry an implicit CR).
+        // `\x1B[J` → clear from cursor to end of screen. Wipes enquirer's
+        //   leftover choice / input rendering below the row where we'll
+        //   write our message so the exit output isn't shadowed by orphaned
+        //   prompt fragments.
+        process.stdout.write('\n\r\x1B[J');
+        output_1.output.warn({ title: 'nx migrate interrupted by user.' });
+        process.exit(130);
+    };
+    const withCancel = (q) => ({ ...q, cancel });
+    const injected = Array.isArray(questions)
+        ? questions.map(withCancel)
+        : withCancel(questions);
+    return (await (0, enquirer_1.prompt)(injected));
+}

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

@@ -0,0 +1,11 @@
+import type { PackageJsonUpdateForPackage as PackageUpdate } from '../../config/misc-interfaces';
+import type { PackageJson } from '../../utils/package-json';
+/**
+ * Drop entries from `packageUpdates` that would either downgrade the package
+ * (move resolved version backward) or rewrite a specifier that is already
+ * exactly pinned to the resolved version (a no-op write). Keep genuine
+ * upgrades and narrowing rewrites where the user's range covers a version
+ * lower than what's resolved (the migrator's traditional "lock to recommended
+ * exact pin" behavior).
+ */
+export declare function filterDowngradedUpdates(packageUpdates: Record<string, PackageUpdate>, packageJson: PackageJson | null, getInstalledVersion: (packageName: string) => string | null): Record<string, PackageUpdate>;

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

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterDowngradedUpdates = filterDowngradedUpdates;
+const semver_1 = require("semver");
+const version_utils_1 = require("./version-utils");
+/**
+ * Drop entries from `packageUpdates` that would either downgrade the package
+ * (move resolved version backward) or rewrite a specifier that is already
+ * exactly pinned to the resolved version (a no-op write). Keep genuine
+ * upgrades and narrowing rewrites where the user's range covers a version
+ * lower than what's resolved (the migrator's traditional "lock to recommended
+ * exact pin" behavior).
+ */
+function filterDowngradedUpdates(packageUpdates, packageJson, getInstalledVersion) {
+    const result = {};
+    for (const [name, update] of Object.entries(packageUpdates)) {
+        const resolved = getInstalledVersion(name);
+        if (!resolved) {
+            // Not installed; let downstream logic decide whether to add it.
+            result[name] = update;
+            continue;
+        }
+        const proposed = (0, version_utils_1.normalizeVersion)(update.version);
+        const resolvedNorm = (0, version_utils_1.normalizeVersion)(resolved);
+        if ((0, semver_1.gt)(proposed, resolvedNorm)) {
+            result[name] = update;
+            continue;
+        }
+        if ((0, semver_1.lt)(proposed, resolvedNorm)) {
+            continue;
+        }
+        // proposed === resolved: keep when narrowing a looser specifier to an
+        // exact pin; drop when the specifier is already exact at resolved.
+        const specifier = packageJson?.dependencies?.[name] ?? packageJson?.devDependencies?.[name];
+        if (!specifier) {
+            continue;
+        }
+        const floor = (0, semver_1.minVersion)(specifier);
+        if (floor && (0, semver_1.lt)(floor.version, resolvedNorm)) {
+            result[name] = update;
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,6 @@
+export declare const DIST_TAGS: readonly ["latest", "next", "canary"];
+export type DistTag = (typeof DIST_TAGS)[number];
+export declare function isLegacyEra(targetVersion: string): boolean;
+export declare function normalizeVersion(version: string): string;
+export declare function normalizeVersionWithTagCheck(pkg: string, version: string): Promise<string>;
+export declare function isNxEquivalentTarget(targetPackage: string, targetVersion: string): boolean;

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

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIST_TAGS = void 0;
+exports.isLegacyEra = isLegacyEra;
+exports.normalizeVersion = normalizeVersion;
+exports.normalizeVersionWithTagCheck = normalizeVersionWithTagCheck;
+exports.isNxEquivalentTarget = isNxEquivalentTarget;
+const semver_1 = require("semver");
+const package_manager_1 = require("../../utils/package-manager");
+exports.DIST_TAGS = ['latest', 'next', 'canary'];
+const LEGACY_ERA_BOUNDARY = '14.0.0-beta.0';
+// Pre-14 (legacy) installs used `@nrwl/workspace` as the canonical Nx package.
+// Non-semver values (e.g. dist-tags or the literal `'latest'` sentinel before
+// tag resolution) are treated as modern era.
+function isLegacyEra(targetVersion) {
+    return (0, semver_1.valid)(targetVersion) && (0, semver_1.lt)(targetVersion, LEGACY_ERA_BOUNDARY);
+}
+function normalizeVersion(version) {
+    const [semver, ...prereleaseTagParts] = version.split('-');
+    // Handle versions like 1.0.0-beta-next.2
+    const prereleaseTag = prereleaseTagParts.join('-');
+    const [major, minor, patch] = semver.split('.');
+    const newSemver = `${major || 0}.${minor || 0}.${patch || 0}`;
+    const newVersion = prereleaseTag
+        ? `${newSemver}-${prereleaseTag}`
+        : newSemver;
+    const withoutPatch = `${major || 0}.${minor || 0}.0`;
+    const withoutPatchAndMinor = `${major || 0}.0.0`;
+    const variationsToCheck = [
+        newVersion,
+        newSemver,
+        withoutPatch,
+        withoutPatchAndMinor,
+    ];
+    for (const variation of variationsToCheck) {
+        try {
+            if ((0, semver_1.gt)(variation, '0.0.0')) {
+                return variation;
+            }
+        }
+        catch { }
+    }
+    return '0.0.0';
+}
+async function normalizeVersionWithTagCheck(pkg, version) {
+    // Treat non-parseable inputs (e.g. dist-tags like `latest`/`next`) as
+    // registry references and resolve them. Throws on registry failure;
+    // callers that need to tolerate registry outages must wrap.
+    if (version && !(0, semver_1.parse)(version)) {
+        return (0, package_manager_1.resolvePackageVersionUsingRegistry)(pkg, version);
+    }
+    return normalizeVersion(version);
+}
+function isNxEquivalentTarget(targetPackage, targetVersion) {
+    if (isLegacyEra(targetVersion)) {
+        return targetPackage === '@nrwl/workspace';
+    }
+    return targetPackage === 'nx' || targetPackage === '@nx/workspace';
+}