nx 23.2.0-beta.4 → 23.2.0-beta.6

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

@@ -3,6 +3,14 @@ interface MigrationShape {
     implementation?: string;
     factory?: string;
 }
+/** A migration entry as written into the plan (migrations.json). */
+export interface PlannedMigration extends MigrationShape {
+    package: string;
+    name: string;
+    version: string;
+    description?: string;
+    documentation?: string;
+}
 export declare function isPromptOnlyMigration(m: MigrationShape): boolean;
 export declare function isHybridMigration(m: MigrationShape): boolean;
 export {};

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

@@ -0,0 +1,2 @@
+export { runSingleMigrationWorker } from './worker';
+export type { RunSingleMigrationWorkerInput } from './worker';

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

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSingleMigrationWorker = void 0;
+var worker_1 = require("./worker");
+Object.defineProperty(exports, "runSingleMigrationWorker", { enumerable: true, get: function () { return worker_1.runSingleMigrationWorker; } });

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

@@ -0,0 +1 @@
+export declare function pmExecPrefix(root: string): string;

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

@@ -0,0 +1,16 @@
+"use strict";
+// Internal to run/: deliberately not re-exported from ./index.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pmExecPrefix = pmExecPrefix;
+const package_manager_1 = require("../../../utils/package-manager");
+const cachedPmExecPrefix = new Map();
+// getPackageManagerCommand can shell out to detect a version, so cache the
+// result per root.
+function pmExecPrefix(root) {
+    let prefix = cachedPmExecPrefix.get(root);
+    if (prefix === undefined) {
+        prefix = (0, package_manager_1.getPackageManagerCommand)((0, package_manager_1.detectPackageManager)(root), root).exec;
+        cachedPmExecPrefix.set(root, prefix);
+    }
+    return prefix;
+}

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

@@ -0,0 +1,15 @@
+import { type AgenticArg } from '../agentic/select';
+export interface RunSingleMigrationWorkerInput {
+    root: string;
+    runMigration: string;
+    /** The raw `--agentic` value; resolved here against the environment. */
+    agentic: AgenticArg;
+    validate: boolean | undefined;
+    /** The requested value; the effective value is resolved here against the agentic kind. */
+    createCommits: boolean | undefined;
+    commitPrefix: string;
+    interactive: boolean | undefined;
+    skipInstall: boolean;
+    isVerbose: boolean;
+}
+export declare function runSingleMigrationWorker(input: RunSingleMigrationWorkerInput): Promise<void>;

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

@@ -0,0 +1,419 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSingleMigrationWorker = runSingleMigrationWorker;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const configuration_1 = require("../../../config/configuration");
+const git_utils_1 = require("../../../utils/git-utils");
+const command_line_utils_1 = require("../../../utils/command-line-utils");
+const fileutils_1 = require("../../../utils/fileutils");
+const installation_directory_1 = require("../../../utils/installation-directory");
+const logger_1 = require("../../../utils/logger");
+const output_1 = require("../../../utils/output");
+const package_json_1 = require("../../../utils/package-json");
+const print_dropped_agent_context_1 = require("../agentic/print-dropped-agent-context");
+const select_1 = require("../agentic/select");
+const command_object_1 = require("../command-object");
+const execute_migration_1 = require("../execute-migration");
+const migrate_analytics_1 = require("../migrate-analytics");
+const migrate_commits_1 = require("../migrate-commits");
+const migrate_output_1 = require("../migrate-output");
+const migration_shape_1 = require("../migration-shape");
+const safe_prompt_1 = require("../safe-prompt");
+const util_1 = require("./util");
+async function runSingleMigrationWorker(input) {
+    const { root, runMigration, commitPrefix, interactive, skipInstall, isVerbose, } = input;
+    const { migrations, source } = readMigrationsSource(root);
+    const migration = resolveMigration(migrations, runMigration, source);
+    (0, migrate_analytics_1.reportMigrateSingleMigrationInvocation)({
+        migrationType: (0, migration_shape_1.isPromptOnlyMigration)(migration)
+            ? 'prompt'
+            : (0, migration_shape_1.isHybridMigration)(migration)
+                ? 'hybrid'
+                : 'generator',
+    });
+    let agentic;
+    try {
+        agentic = await (0, select_1.resolveAgentic)({
+            agentic: input.agentic,
+            migrations: [migration],
+            interactive,
+        });
+    }
+    catch (e) {
+        (0, migrate_analytics_1.reportMigrateRunError)({ code: 'agentic', error: e });
+        throw e;
+    }
+    const resolved = (0, migrate_commits_1.resolveCreateCommits)({
+        createCommits: input.createCommits,
+        agenticKind: agentic.kind,
+        isGitRepo: (0, git_utils_1.isGitRepository)(root),
+        commitPrefixIsCustom: commitPrefix !== command_object_1.DEFAULT_MIGRATION_COMMIT_PREFIX,
+    });
+    if (resolved.error) {
+        throw new Error(resolved.error);
+    }
+    if (resolved.warning) {
+        output_1.output.warn({ title: resolved.warning });
+    }
+    const createCommits = resolved.effective;
+    if (createCommits && (0, safe_prompt_1.canPrompt)(interactive)) {
+        const currentBranch = (0, git_utils_1.getGitCurrentBranch)(root);
+        // `getBaseRef` may carry an `origin/` prefix (set by the CI-workflow
+        // generator); compare against the local branch name.
+        const defaultBranch = (0, command_line_utils_1.getBaseRef)((0, configuration_1.readNxJson)(root)).replace(/^origin\//, '');
+        const proceed = await (0, migrate_commits_1.confirmCommitsOnDefaultBranch)({
+            currentBranch,
+            defaultBranch,
+        });
+        if (!proceed) {
+            output_1.output.log({
+                title: `Skipped running the migration to avoid committing to the default branch '${currentBranch}'.`,
+                bodyLines: [
+                    'Switch to a different branch and re-run, or re-run and confirm to proceed.',
+                ],
+            });
+            return;
+        }
+    }
+    await runStandalone(root, migration, {
+        agentic,
+        createCommits,
+        agenticHasDiffContext: resolved.agenticHasDiffContext,
+        shouldRunValidation: (0, select_1.resolveShouldRunValidation)({
+            validate: input.validate,
+            agenticKind: agentic.kind,
+        }),
+        commitPrefix,
+        skipInstall,
+        isVerbose,
+    });
+}
+function readMigrationsSource(root) {
+    const migrationsPath = (0, path_1.join)(root, 'migrations.json');
+    if (!(0, fs_1.existsSync)(migrationsPath)) {
+        throw new Error(`File 'migrations.json' doesn't exist, can't run the migration. Run \`${(0, util_1.pmExecPrefix)(root)} nx migrate\` to generate it first.`);
+    }
+    return {
+        migrations: readPlanMigrations(migrationsPath),
+        source: 'migrations.json',
+    };
+}
+function readPlanMigrations(path) {
+    return ((0, fileutils_1.readJsonFile)(path).migrations ?? []);
+}
+function resolveMigration(migrations, id, source) {
+    // Split on the first ':' only, so a name that itself contains one survives.
+    const colon = id.indexOf(':');
+    const matches = colon === -1
+        ? migrations.filter((m) => m.name === id)
+        : migrations.filter((m) => m.package === id.slice(0, colon) && m.name === id.slice(colon + 1));
+    if (matches.length === 0) {
+        throw new Error(`No migration matching '${id}' was found in ${source}.`);
+    }
+    if (matches.length > 1) {
+        throw new Error([
+            `More than one migration matches '${id}' in ${source}. Re-run with the full '<package>:<name>' id:`,
+            ...matches.map((m) => `  - ${m.package}:${m.name}`),
+        ].join('\n'));
+    }
+    return matches[0];
+}
+async function runStandalone(root, migration, opts) {
+    const { agentic, createCommits, commitPrefix, skipInstall, isVerbose } = opts;
+    if ((0, migration_shape_1.isPromptOnlyMigration)(migration)) {
+        if (agentic.kind !== 'enabled') {
+            // No agent to apply the prompt, so nothing runs: no checkpoint, no
+            // commit.
+            emitOrPrintPrompt(root, migration, agentic.kind);
+            return;
+        }
+        // Checkpoint pre-existing working-tree state first, or the migration
+        // commit's `git add -A` folds it in.
+        if (createCommits) {
+            (0, migrate_commits_1.commitCheckpointBeforeMigrations)(root, commitPrefix);
+        }
+        const agenticRun = await prepareAgenticRun(root, migration, agentic, createCommits, commitPrefix);
+        const installer = new execute_migration_1.ChangedDepInstaller(root, skipInstall, (0, execute_migration_1.formatSingleMigrationRerunCommand)(`${migration.package}:${migration.name}`));
+        const installDepsIfChanged = () => installer.installDepsIfChanged();
+        const stepResult = await runAgenticStep(agenticRun, {
+            root,
+            migration,
+            installDepsIfChanged,
+            documentationPath: resolveDocumentationPath(root, migration),
+        });
+        await commitAndLogAgenticOutcome({
+            root,
+            migration,
+            createCommits,
+            commitPrefix,
+            installDepsIfChanged,
+            successLabel: 'Applied',
+            stepResult,
+        });
+        if (installer.skippedInstall) {
+            (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
+        }
+        return;
+    }
+    if (createCommits) {
+        (0, migrate_commits_1.commitCheckpointBeforeMigrations)(root, commitPrefix);
+    }
+    const agenticRun = agentic.kind === 'enabled'
+        ? await prepareAgenticRun(root, migration, agentic, createCommits, commitPrefix)
+        : undefined;
+    const installer = new execute_migration_1.ChangedDepInstaller(root, skipInstall, (0, execute_migration_1.formatSingleMigrationRerunCommand)(`${migration.package}:${migration.name}`));
+    const installDepsIfChanged = () => installer.installDepsIfChanged();
+    const validationRun = agenticRun && opts.shouldRunValidation ? agenticRun : undefined;
+    const resolvedCollection = (0, execute_migration_1.readMigrationCollection)(migration.package, root);
+    const { changes, nextSteps, agentContext, skipAgentic, logs, madeChanges } = await (0, execute_migration_1.runNxOrAngularMigration)(root, migration, isVerbose, (0, migration_shape_1.isHybridMigration)(migration) || !!validationRun, resolvedCollection);
+    // Whether an AI step was on the table for `skipAgentic` to waive. A hybrid
+    // owes its prompt in every agentic mode; a generator-only migration owes
+    // only the validation pass, and only where one would have run.
+    const validationApplies = !!validationRun && changes.length > 0;
+    const waivedAgenticStep = skipAgentic && ((0, migration_shape_1.isHybridMigration)(migration) || validationApplies);
+    if ((0, migration_shape_1.isHybridMigration)(migration) && agenticRun && !skipAgentic) {
+        // The prompt half may need the deps the generator half added, so install
+        // before the agent runs.
+        await installDepsIfChanged();
+        const stepResult = await runAgenticStep(agenticRun, {
+            root,
+            migration,
+            installDepsIfChanged,
+            documentationPath: resolveDocumentationPath(root, migration, resolvedCollection),
+            implContext: {
+                logs,
+                changes,
+                agentContext,
+                // No prior migrations run here, so unlike the classic loop there is no
+                // pending-commit debt to suppress the git-inspect context for.
+                hasDiffContext: opts.agenticHasDiffContext,
+            },
+        });
+        await commitAndLogAgenticOutcome({
+            root,
+            migration,
+            createCommits,
+            commitPrefix,
+            installDepsIfChanged,
+            successLabel: 'Applied',
+            stepResult,
+        });
+        if (installer.skippedInstall) {
+            (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
+        }
+        printNextSteps(migration, nextSteps);
+        return;
+    }
+    if (validationApplies && !skipAgentic) {
+        // Commit after validation: a failed validation throws, leaving the changes
+        // in the working tree for review.
+        await installDepsIfChanged();
+        const stepResult = await runAgenticStep(validationRun, {
+            root,
+            migration,
+            installDepsIfChanged,
+            documentationPath: resolveDocumentationPath(root, migration, resolvedCollection),
+            implContext: {
+                logs,
+                changes,
+                agentContext,
+                hasDiffContext: opts.agenticHasDiffContext,
+            },
+            mode: 'generic-validation',
+        });
+        await commitAndLogAgenticOutcome({
+            root,
+            migration,
+            createCommits,
+            commitPrefix,
+            installDepsIfChanged,
+            successLabel: 'Validation passed',
+            stepResult,
+        });
+        if (installer.skippedInstall) {
+            (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
+        }
+        printNextSteps(migration, nextSteps);
+        return;
+    }
+    if (waivedAgenticStep) {
+        (0, migrate_output_1.logWaivedAgenticStep)(migration, agentContext);
+    }
+    else if (!(0, migration_shape_1.isHybridMigration)(migration)) {
+        forwardDroppedAgentContext(migration, agentContext, agentic.kind);
+    }
+    // A no-op migration must not build a commit whose `git add -A` absorbs
+    // unrelated pending diffs under its name. The commit path installs deps
+    // itself, so the else branch does it here instead.
+    if (createCommits && madeChanges) {
+        await attemptStandaloneCommit(root, migration, createCommits, commitPrefix, installDepsIfChanged);
+    }
+    else {
+        await installer.installDepsIfChanged();
+    }
+    if (installer.skippedInstall) {
+        (0, execute_migration_1.logSkippedPostMigrationInstall)(root);
+    }
+    printNextSteps(migration, nextSteps);
+    // A waived prompt is not deferred, so it gets no hand-off to an outer agent
+    // and no "apply this manually" block for the user either.
+    if ((0, migration_shape_1.isHybridMigration)(migration) && !skipAgentic) {
+        emitOrPrintPrompt(root, migration, agentic.kind, {
+            logs,
+            changes,
+            agentContext,
+        }, resolvedCollection);
+    }
+}
+// The handoff and run-step machinery is `require`d here so this module pulls
+// it in only when agentic is enabled.
+async function prepareAgenticRun(root, migration, agentic, effectiveCreateCommits, commitPrefix) {
+    const { applyAgenticHandoffGitignoreFallback } = require('../agentic/handoff-gitignore');
+    const { packageJson: nxPackageJson } = (0, package_json_1.readModulePackageJson)('nx', (0, installation_directory_1.getNxRequirePaths)(root));
+    await applyAgenticHandoffGitignoreFallback({
+        migrations: [migration],
+        installedNxVersion: nxPackageJson.version,
+        effectiveCreateCommits,
+        commitPrefix,
+        root,
+    });
+    const { initRunDir, resolveAgenticRunId } = require('../agentic/handoff');
+    const { runAgenticPromptStep } = require('../agentic/run-step');
+    return {
+        agentic,
+        runDir: initRunDir(root, resolveAgenticRunId([migration])),
+        runStep: runAgenticPromptStep,
+    };
+}
+async function runAgenticStep(agenticRun, input) {
+    try {
+        return await agenticRun.runStep({
+            ...input,
+            agentic: agenticRun.agentic,
+            runDir: agenticRun.runDir,
+        });
+    }
+    catch (e) {
+        (0, migrate_analytics_1.reportMigrateRunError)({
+            code: 'agentic',
+            migrationPackage: input.migration.package,
+            migrationName: input.migration.name,
+            error: e,
+        });
+        throw e;
+    }
+}
+// A standalone run has no later commit or end-of-run recap to absorb a failed
+// commit's diff, so it passes its own guidance instead of the default.
+// `commitMigrationIfRequested` logs a failed commit itself with that guidance.
+function attemptStandaloneCommit(root, migration, createCommits, commitPrefix, installDepsIfChanged) {
+    return (0, migrate_commits_1.commitMigrationIfRequested)(root, migration, createCommits, commitPrefix, installDepsIfChanged, [], 'Commit or revert the changes manually.');
+}
+async function commitAndLogAgenticOutcome(args) {
+    const commit = await attemptStandaloneCommit(args.root, args.migration, args.createCommits, args.commitPrefix, args.installDepsIfChanged);
+    (0, migrate_output_1.logAgenticSuccessOutcome)(args.stepResult.ambiguous ? 'Marked complete by user' : args.successLabel, commit.status === 'committed' ? commit.sha : null, args.stepResult.summary);
+}
+// Hybrids are excluded by the caller: their `agentContext` rides in the
+// prompt payload instead.
+function forwardDroppedAgentContext(migration, agentContext, agenticKind) {
+    if (agentContext.length > 0 && agenticKind === 'inside-agent') {
+        (0, print_dropped_agent_context_1.printDroppedAgentContextForOuterAgent)({ migration, agentContext });
+    }
+}
+function printNextSteps(migration, nextSteps) {
+    if (nextSteps.length === 0)
+        return;
+    output_1.output.log({
+        title: `Next steps for ${migration.package}: ${migration.name}`,
+        bodyLines: nextSteps.map((line) => `- ${line}`),
+    });
+}
+function emitOrPrintPrompt(root, migration, agenticKind, impl, resolvedCollection) {
+    const migrationId = `${migration.package}:${migration.name}`;
+    const promptPath = migration.prompt;
+    const documentationPath = resolveDocumentationPath(root, migration, resolvedCollection);
+    if (agenticKind === 'inside-agent') {
+        emitPromptForOuterAgent(migrationId, promptPath, documentationPath, impl);
+    }
+    else {
+        printPromptForUser(root, migration, promptPath, documentationPath);
+    }
+}
+function emitPromptForOuterAgent(migrationId, promptPath, documentationPath, impl) {
+    const payload = { migrationId, prompt: promptPath };
+    if (documentationPath)
+        payload.documentationPath = documentationPath;
+    if (impl) {
+        payload.impl = {
+            logs: impl.logs,
+            changes: impl.changes.map((c) => ({ type: c.type, path: c.path })),
+            ...(impl.agentContext.length > 0
+                ? { agentContext: impl.agentContext }
+                : {}),
+        };
+    }
+    // A raw `<` in a migration-authored string could forge the closing tag; the
+    // JSON unicode escape removes every one and keeps the payload valid JSON.
+    const json = JSON.stringify(payload, null, 2).replace(/</g, '\\u003c');
+    const block = [
+        `The following prompt-based migration was not applied automatically. Apply it to this workspace, then continue.`,
+        ``,
+        `<nx_migrate_prompt migration="${(0, print_dropped_agent_context_1.escapeXmlAttr)(migrationId)}">`,
+        json,
+        `</nx_migrate_prompt>`,
+    ].join('\n');
+    // Bare newline pair frames the block so adjacent stdout doesn't run into it.
+    process.stdout.write(`\n${block}\n\n`);
+}
+function printPromptForUser(root, migration, promptPath, documentationPath) {
+    const bodyLines = [];
+    if (promptPath)
+        bodyLines.push(`Instructions file: ${promptPath}`);
+    if (documentationPath)
+        bodyLines.push(`Documentation: ${documentationPath}`);
+    let content = '';
+    let readErrorCode;
+    if (promptPath) {
+        try {
+            content = (0, fs_1.readFileSync)((0, path_1.join)(root, promptPath), 'utf-8');
+        }
+        catch (e) {
+            const err = e;
+            readErrorCode = err.code ?? err.message;
+        }
+    }
+    if (readErrorCode) {
+        // Point at the file and error code: the generic "review the instructions
+        // above" copy would sit under an empty body.
+        bodyLines.push('', `The instructions file '${promptPath}' could not be read (${readErrorCode}). Open it manually and apply the instructions.`);
+    }
+    else {
+        if (content) {
+            bodyLines.push('', ...content.split('\n'));
+        }
+        bodyLines.push('', 'Review the instructions above and apply them manually.');
+    }
+    output_1.output.log({
+        title: `Prompt-based migration ${migration.package}: ${migration.name} must be applied manually`,
+        bodyLines,
+    });
+}
+// Non-fatal: documentation is supplementary, so a failure warns and the
+// prompt still runs without it.
+function resolveDocumentationPath(root, migration, resolvedCollection) {
+    if (!migration.documentation)
+        return undefined;
+    let documentationPath;
+    try {
+        const { collectionPath } = resolvedCollection ?? (0, execute_migration_1.readMigrationCollection)(migration.package, root);
+        documentationPath = (0, execute_migration_1.resolveDocumentationFileToWorkspacePath)(root, (0, path_1.dirname)(collectionPath), migration.documentation);
+    }
+    catch {
+        // An unreadable collection is reported through the warning below.
+    }
+    if (!documentationPath) {
+        logger_1.logger.warn(`Could not resolve the "documentation" file "${migration.documentation}" declared for migration "${migration.package}: ${migration.name}". It will be skipped.`);
+    }
+    return documentationPath;
+}

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

@@ -39,11 +39,11 @@ async function runMigrationProcess() {
     const installer = new ChangedDepInstaller(workspacePath);
     const installDepsIfChanged = () => installer.installDepsIfChanged();
 
-    const { changes: fileChanges, nextSteps } = await runNxOrAngularMigration(
-      workspacePath,
-      migration,
-      false
-    );
+    const {
+      changes: fileChanges,
+      nextSteps,
+      skipAgentic,
+    } = await runNxOrAngularMigration(workspacePath, migration, false);
 
     if (configuration.createCommits) {
       const commitResult = await commitMigrationIfRequested(
@@ -81,6 +81,7 @@ async function runMigrationProcess() {
         })),
         gitRefAfter,
         nextSteps,
+        skipAgentic,
       })
     );
 

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

@@ -0,0 +1,16 @@
+interface SortableMigration {
+    package: string;
+    name: string;
+    version: string;
+}
+/**
+ * Sorts in place (like `Array.prototype.sort`) and returns the same array.
+ *
+ * `hoistHandoffGitignore` is set for agentic runs, which write scratch under
+ * `.nx/migrate-runs`; see `agentic/handoff-gitignore.ts` for why the v23
+ * gitignore migration must run first there.
+ */
+export declare function sortMigrations<T extends SortableMigration>(migrations: T[], opts: {
+    hoistHandoffGitignore: boolean;
+}): T[];
+export {};

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

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortMigrations = sortMigrations;
+const semver_1 = require("semver");
+const types_1 = require("./agentic/types");
+const version_utils_1 = require("./version-utils");
+/**
+ * Sorts in place (like `Array.prototype.sort`) and returns the same array.
+ *
+ * `hoistHandoffGitignore` is set for agentic runs, which write scratch under
+ * `.nx/migrate-runs`; see `agentic/handoff-gitignore.ts` for why the v23
+ * gitignore migration must run first there.
+ */
+function sortMigrations(migrations, opts) {
+    return migrations.sort((a, b) => {
+        if (opts.hoistHandoffGitignore) {
+            if ((0, types_1.isHandoffGitignoreMigration)(a))
+                return -1;
+            if ((0, types_1.isHandoffGitignoreMigration)(b))
+                return 1;
+        }
+        if (a.name === '15-7-0-split-configuration-into-project-json-files') {
+            return -1;
+        }
+        if (b.name === '15-7-0-split-configuration-into-project-json-files') {
+            return 1;
+        }
+        return (0, semver_1.lt)((0, version_utils_1.normalizeVersion)(a.version), (0, version_utils_1.normalizeVersion)(b.version))
+            ? -1
+            : 1;
+    });
+}

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

@@ -0,0 +1,58 @@
+export declare const NEW_MIGRATE_FLAGS_FLOOR = "23.2.0";
+export declare const NEW_MIGRATE_FLAGS: readonly ['--run-migration', '--runMigration'];
+/**
+ * Matches an exact token or `<flag>=<value>`. The `=` matters: a bare
+ * `startsWith` would also match `--run-migrations` (trailing s).
+ */
+export declare function findNewMigrateFlag(argv: string[]): string | undefined;
+/**
+ * Guard A (local side, before hop A). The current nx knows the new flags, but
+ * the temp CLI 'nx migrate' is about to install may be older and would
+ * silently drop them. Decides where a new-flag invocation runs:
+ *
+ * - No new flag in `argv`, or the temp CLI version resolves at or above the
+ *   feature floor: 'temp-cli', the normal temp-installation path.
+ * - The temp CLI resolves below the floor, or resolution fails (a registry
+ *   error, or a minimum-release-age violation that a temp install must not
+ *   bypass): 'local-nx', provided the workspace-local nx can take the flags.
+ *   The local nx qualifies when it is the exact version running this code
+ *   (it parsed the flag, so it supports it regardless of the floor) or is at
+ *   or above the floor. An unreadable local version throws: the hand-off's
+ *   spawn normally lands on the very install this read verifies, and a
+ *   layout where the version cannot be read gives no such assurance, so
+ *   handing off blind could run a below-floor nx that silently drops the
+ *   flag.
+ * - Neither side is capable: throw with remediation.
+ *
+ * An explicit NX_MIGRATE_CLI_VERSION pinned below the floor throws instead of
+ * silently overriding the user's pin with the local fallback.
+ *
+ * `cliVersionSpec` is NX_MIGRATE_CLI_VERSION when set, else 'latest'.
+ */
+export declare function resolveNewMigrateFlagsRunTarget(options: {
+    argv: string[];
+    cliVersionSpec: string;
+    fromEnvOverride: boolean;
+    ownNxVersion: string;
+    resolveVersion: (spec: string) => Promise<string>;
+    readLocalNxVersion: () => string | undefined;
+}): Promise<'temp-cli' | 'local-nx'>;
+/**
+ * Guard B (temp side, before hop B). The temp CLI knows the new flags, but the
+ * workspace-local nx it is about to hand off to may be older and would silently
+ * drop them.
+ *
+ * A workspace pinned to a feature-carrying 23.2.0 prerelease is refused here
+ * too: published prereleases that predate the feature cannot be told apart by
+ * version alone. Guard A's same-version bypass does not apply on this side
+ * because the invoking nx's version is not forwarded across hop A; the
+ * refusal names the workspace update that resolves it.
+ *
+ * `readLocalNxVersion` returning undefined does not block: the hand-off then
+ * resolves nx as it always does, which may fail visibly or land on another nx
+ * the package manager locates.
+ */
+export declare function assertWorkspaceNxSupportsNewMigrateFlags(options: {
+    argv: string[];
+    readLocalNxVersion: () => string | undefined;
+}): void;