@ohos-ports/nx 23.2.1-beta.0 → 23.3.0-beta.0

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

@@ -0,0 +1,251 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAgentic = resolveAgentic;
+exports.resolveShouldRunValidation = resolveShouldRunValidation;
+const fs_1 = require("fs");
+const jsonc_parser_1 = require("jsonc-parser");
+const path_1 = require("path");
+const output_1 = require("../../../utils/output");
+const workspace_root_1 = require("../../../utils/workspace-root");
+const migrate_analytics_1 = require("../migrate-analytics");
+const safe_prompt_1 = require("../safe-prompt");
+const detect_installed_1 = require("./detect-installed");
+const inception_1 = require("./inception");
+const definitions_1 = require("./definitions");
+const INSTALL_SUPPORTED_AGENTS_HINT = [
+    'Install one of the supported agents and re-run the migration:',
+    ...definitions_1.AGENT_DEFINITIONS.map((def) => `  - ${def.displayName}`),
+];
+/**
+ * Callers resolve this once per run-phase invocation and reuse the result for
+ * every migration it covers.
+ */
+async function resolveAgentic(input) {
+    if ((0, inception_1.isInsideAgent)()) {
+        output_1.output.log({
+            title: input.agentic === true || typeof input.agentic === 'string'
+                ? 'Agentic flow skipped: nx detected this run is invoked from inside an AI agent — the outer agent drives the migration. The explicit --agentic flag is ignored in this context.'
+                : 'Agentic flow skipped: nx detected this run is invoked from inside an AI agent.',
+        });
+        return { kind: 'inside-agent' };
+    }
+    const isInteractive = !!process.stdin.isTTY &&
+        !!process.stdout.isTTY &&
+        input.interactive !== false;
+    // Skip detection for the one case where the result is unused: explicit
+    // `--agentic=false`. For every other path (explicit enable, explicit id, or
+    // undefined-with-prompt) we either need the detection result to pick/verify
+    // an agent or to decide whether the up-front prompt is even worth asking.
+    if (input.agentic === false) {
+        return { kind: 'disabled' };
+    }
+    const detected = await (0, detect_installed_1.detectInstalledAgents)(definitions_1.AGENT_DEFINITIONS);
+    const { enabled, explicitId, persist } = await resolveFlag(input, isInteractive, detected);
+    if (!enabled) {
+        if (persist === false) {
+            persistAgenticChoice(false);
+        }
+        return { kind: 'disabled' };
+    }
+    const selected = await selectAgent(detected, explicitId, isInteractive);
+    if (persist === true) {
+        persistAgenticChoice(true);
+    }
+    else if (persist === 'pin') {
+        persistAgenticChoice(selected.id);
+    }
+    return { kind: 'enabled', selectedAgent: selected };
+}
+/**
+ * No warning when `--validate` is passed with the agentic flow off: validation
+ * requires an active agent session by definition.
+ */
+function resolveShouldRunValidation(args) {
+    return args.validate !== false && args.agenticKind === 'enabled';
+}
+async function resolveFlag(input, isInteractive, detected) {
+    if (input.agentic === true) {
+        if (!isInteractive) {
+            warnAgenticInteractiveOnly();
+            return { enabled: false };
+        }
+        return { enabled: true };
+    }
+    if (typeof input.agentic === 'string') {
+        if (!isInteractive) {
+            warnAgenticInteractiveOnly();
+            return { enabled: false };
+        }
+        return { enabled: true, explicitId: input.agentic };
+    }
+    // undefined — fire the up-front prompt only when we have a TTY, something
+    // agentic-eligible is queued, and at least one agent is installed. Without
+    // an installed agent the user can't say "Yes" meaningfully — asking would
+    // walk them into a dead end.
+    if (!isInteractive) {
+        return { enabled: false };
+    }
+    if (!input.migrations.some((m) => !!m.prompt)) {
+        return { enabled: false };
+    }
+    if (detected.length === 0) {
+        return { enabled: false };
+    }
+    return firePromptForAgentic(input.migrations, detected);
+}
+function requireInteractiveOrAbort(isInteractive) {
+    if (isInteractive)
+        return;
+    output_1.output.error({
+        title: 'The agentic flow is interactive-only in this release.',
+        bodyLines: [
+            'Re-run in an interactive terminal, or pass `--agentic=false` to skip the agentic flow.',
+        ],
+    });
+    throw new Error('Agentic flow requires an interactive terminal.');
+}
+function warnAgenticInteractiveOnly() {
+    output_1.output.warn({
+        title: 'Skipping the agentic flow: it is interactive-only in this release and this run is non-interactive.',
+        bodyLines: [
+            'Continuing the migration without the agentic flow. Re-run in an interactive terminal to use it.',
+        ],
+    });
+}
+async function firePromptForAgentic(migrations, detected) {
+    // The apply hint assumes at least one prompt-bearing migration is queued. If
+    // we later extend the prompt to fire for generator-only runs (validation-
+    // only), the hint needs to branch.
+    const promptCount = migrations.filter((m) => !!m.prompt).length;
+    const applyHint = `Apply ${promptCount} prompt migration${promptCount === 1 ? '' : 's'} and validate generator output with an AI agent`;
+    const skipHint = `Skip prompts and run generators without AI validation`;
+    const rememberHint = `Saved to nx.json so Nx won't ask again`;
+    // The pin-vs-flexible distinction only matters when more than one agent is
+    // installed. With a single agent, "always" simply persists `true` and the
+    // pin option is dropped.
+    const multipleAgents = detected.length > 1;
+    const pinChoice = multipleAgents
+        ? [
+            {
+                value: 'yes-pin',
+                label: 'Yes, always with the same agent',
+                hint: rememberHint,
+            },
+        ]
+        : [];
+    const choices = [
+        {
+            value: 'yes-once',
+            label: 'Yes, just this time',
+            hint: applyHint,
+        },
+        {
+            value: 'yes-flex',
+            label: multipleAgents
+                ? "Yes, always (I'll pick the agent each run)"
+                : 'Yes, always',
+            hint: rememberHint,
+        },
+        ...pinChoice,
+        { value: 'no-once', label: 'No, just this time', hint: skipHint },
+        { value: 'no-never', label: 'No, never', hint: rememberHint },
+    ];
+    // Blank line keeps the prompt from gluing to the previous `npm install`
+    // output or any earlier orchestrator line.
+    console.log();
+    // Each choice's hint renders beside it, so the description no longer needs a
+    // footer that tracks the cursor.
+    const choice = await (0, safe_prompt_1.migrateChoice)({
+        message: 'Enable the agentic flow?',
+        choices,
+    });
+    (0, migrate_analytics_1.reportMigratePrompt)('agentic', choice);
+    switch (choice) {
+        case 'yes-once':
+            return { enabled: true };
+        case 'yes-flex':
+            return { enabled: true, persist: true };
+        case 'yes-pin':
+            return { enabled: true, persist: 'pin' };
+        case 'no-never':
+            return { enabled: false, persist: false };
+        case 'no-once':
+        default:
+            return { enabled: false };
+    }
+}
+// Persists the user's agentic choice to `nx.json` so the up-front prompt is
+// skipped on future runs. Edits the raw file in place via jsonc-parser, so it
+// touches only the `migrate.agentic` key and preserves comments, formatting,
+// and any `extends` preset (the prompt fires mid-migration, so a silent
+// reformat would be surprising). Never throws - a failed write only costs the
+// user the prompt again next time.
+function persistAgenticChoice(value) {
+    const nxJsonPath = (0, path_1.join)(workspace_root_1.workspaceRoot, 'nx.json');
+    if (!(0, fs_1.existsSync)(nxJsonPath)) {
+        output_1.output.warn({
+            title: `Could not save your agentic choice: no nx.json found at the workspace root.`,
+        });
+        return;
+    }
+    try {
+        const content = (0, fs_1.readFileSync)(nxJsonPath, 'utf-8');
+        const edits = (0, jsonc_parser_1.modify)(content, ['migrate', 'agentic'], value, {
+            formattingOptions: { insertSpaces: true, tabSize: 2 },
+        });
+        (0, fs_1.writeFileSync)(nxJsonPath, (0, jsonc_parser_1.applyEdits)(content, edits));
+        output_1.output.log({
+            title: `Saved your choice to nx.json (migrate.agentic = ${JSON.stringify(value)}). Nx won't ask again.`,
+        });
+    }
+    catch (e) {
+        output_1.output.warn({
+            title: `Could not save your agentic choice to nx.json: ${e instanceof Error ? e.message : String(e)}`,
+        });
+    }
+}
+async function selectAgent(detected, explicitId, isInteractive) {
+    if (explicitId) {
+        const match = detected.find((d) => d.id === explicitId);
+        if (match) {
+            return match;
+        }
+        // The requested agent isn't installed. Rather than aborting the migration,
+        // warn and fall through to resolve from the agents that ARE installed
+        // (pick when 2+, auto-select the only one, error only when none exist).
+        if (detected.length > 0) {
+            output_1.output.warn({
+                title: `The requested agent "${explicitId}" is not installed; using the installed agent(s) instead.`,
+                bodyLines: [
+                    'Currently installed agents:',
+                    ...detected.map((d) => `  - ${d.displayName} (${d.id})`),
+                ],
+            });
+        }
+    }
+    if (detected.length === 0) {
+        output_1.output.error({
+            title: 'Agentic flow was enabled, but no supported AI agent is installed on this machine.',
+            bodyLines: INSTALL_SUPPORTED_AGENTS_HINT,
+        });
+        throw new Error('No installed AI agent available.');
+    }
+    if (detected.length === 1) {
+        const only = detected[0];
+        output_1.output.log({
+            title: `Using ${only.displayName} for the agentic flow.`,
+        });
+        return only;
+    }
+    // 2+ detected. The picker only fires interactively. We've already required
+    // a TTY before resolving an enabled state, so this is defense-in-depth.
+    requireInteractiveOrAbort(isInteractive);
+    // Blank line keeps the prompt from gluing to the preceding output.
+    console.log();
+    const id = await (0, safe_prompt_1.migrateChoice)({
+        message: 'Multiple AI agents detected. Which one should Nx use?',
+        choices: detected.map((d) => ({ value: d.id, label: d.displayName })),
+    });
+    (0, migrate_analytics_1.reportMigratePrompt)('agent_select', id);
+    return detected.find((d) => d.id === id);
+}

package/dist/src/command-line/migrate/agentic/terminal-repair.d.ts

@@ -0,0 +1 @@
+export declare function restoreTermiosAfterAgent(): void;

package/dist/src/command-line/migrate/agentic/terminal-repair.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.restoreTermiosAfterAgent = restoreTermiosAfterAgent;
+const child_process_1 = require("child_process");
+function restoreTermiosAfterAgent() {
+    if (process.platform === 'win32')
+        return;
+    if (!process.stdin.isTTY)
+        return;
+    try {
+        // Not setRawMode(false): it short-circuits when libuv's per-handle mode
+        // is already NORMAL, even after the agent changed termios out-of-band.
+        // `stty sane` goes through the kernel instead.
+        (0, child_process_1.execSync)('stty sane < /dev/tty', {
+            stdio: ['ignore', 'ignore', 'ignore'],
+            windowsHide: true,
+        });
+        // Carriage-return + clear to end of screen, to wipe any agent TUI
+        // cells below our row that subsequent log lines won't overwrite
+        // (e.g. a status footer past where our text wraps).
+        process.stdout.write('\r\x1B[J');
+    }
+    catch {
+        // Best-effort: if stty isn't on PATH or /dev/tty isn't accessible, the
+        // worst case is the pre-existing staircase + cell-bleed output.
+    }
+}

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

@@ -0,0 +1,147 @@
+import type { AgentId } from './cli-args';
+export type { AgentId };
+/**
+ * Workspace-relative directory holding all migrate-run scratch: a run
+ * directory per run id. Shared by the run-dir layout in `handoff.ts` and the
+ * agent permission rules in `definitions.ts` so the pre-authorized write scope
+ * can't drift from the actual layout. It lives here so `definitions.ts`,
+ * loaded whenever the agentic flow is resolved, doesn't pull in the handoff
+ * runtime for the path alone.
+ */
+export declare const MIGRATE_RUNS_RELATIVE_DIR = ".nx/migrate-runs";
+/**
+ * The one subtree of a run directory an agent writes; everything beside it is
+ * state Nx owns, so the pre-authorized write scope stops here. Handoff names
+ * derive from step ids or package and migration names, so flattening them into
+ * the run dir would leave Nx no name it could safely add.
+ */
+export declare const HANDOFFS_DIR_NAME = "handoffs";
+/**
+ * Sibling subtree holding the per-step prompt files Nx writes for the agent
+ * to read. They stay out of `handoffs/`, which is the agent's to write.
+ */
+export declare const PROMPTS_DIR_NAME = "prompts";
+export declare function isHandoffGitignoreMigration(m: {
+    package: string;
+    name: string;
+}): boolean;
+/**
+ * A coding agent that was found on the user's machine, ready to be spawned.
+ *
+ * Produced by `detect-installed.ts`. The `binary` is an absolute path so the
+ * runner can spawn it directly without re-resolving against PATH.
+ */
+export interface DetectedInstalledAgent {
+    id: AgentId;
+    displayName: string;
+    binary: string;
+    source: 'path' | 'well-known';
+}
+/**
+ * Inputs the runner provides when asking an agent definition to build its
+ * spawn arguments. Kept minimal — agent-specific quirks (e.g. transient agent
+ * name for OpenCode) are encoded inside the definition, not here.
+ *
+ * Both prompts are written to disk (see `instruction-files.ts`) and reached
+ * through `systemPromptFilePath` / `instructionsPointer`. The inline fields
+ * below are the exception, for agents that cannot be pointed at a file.
+ */
+export interface InvocationContext {
+    /** Absolute path of the file holding the step's system prompt. */
+    systemPromptFilePath: string;
+    /** Verbatim system prompt, only for a step with no file-loading path. */
+    systemPrompt: string;
+    /** Single-line command-line text pointing the agent at its instructions. */
+    instructionsPointer: string;
+    /** Inline handoff contract and pointer to `systemPromptFilePath`. */
+    inlineSystemContext: string;
+    /** Shorter `inlineSystemContext`, substituted on Windows shim overflow. */
+    inlineSystemContextFallback: string;
+    workspaceRoot: string;
+    /**
+     * Name of the run directory under `MIGRATE_RUNS_RELATIVE_DIR` holding this
+     * invocation's handoff. A workspace can carry several run directories at
+     * once, so a definition that pre-authorizes the handoff write narrows it to
+     * this one: the others belong to runs this invocation is not executing.
+     */
+    runDirName: string;
+}
+/**
+ * What an agent definition returns from `buildInteractive`. The runner combines
+ * this with the detected binary path to actually spawn.
+ */
+export interface InvocationSpec {
+    args: string[];
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+}
+/**
+ * Static description of an agent the migrate command knows how to dispatch to.
+ */
+export interface AgentDefinition {
+    id: AgentId;
+    displayName: string;
+    /** Binary names to probe via `which` (PATHEXT handled by `which` on Windows). */
+    binaryNames: string[];
+    /** Absolute paths to probe as a fallback when PATH lookup misses. */
+    wellKnownPaths(): string[];
+    buildInteractive(ctx: InvocationContext): InvocationSpec;
+}
+/**
+ * Output of the agent's handoff file, written at the end of an agentic step.
+ * The two locked fields drive the failure-handling matrix in the design doc;
+ * extra fields are tolerated and surfaced via `extras`.
+ */
+export interface HandoffFile {
+    status: 'success' | 'failed';
+    summary: string;
+    extras?: Record<string, unknown>;
+}
+/**
+ * Outcome the runner reports back to the migrate orchestrator after a single
+ * agentic step. The four kinds mirror the (a)/(b)/(c) matrix plus the user's
+ * choice when (c) fires.
+ *
+ * `ambiguous-abort.causeSummary`: pre-rendered explanation lines. Populated
+ * when Ctrl+C bypasses the ambiguous prompt (so the cause was never shown
+ * inline) and forwarded so the caller can surface it. Omitted when the user
+ * chose "abort" at the prompt — the cause was already shown there.
+ */
+export type HandoffOutcome = {
+    kind: 'success';
+    summary: string;
+    extras?: Record<string, unknown>;
+} | {
+    kind: 'failed';
+    summary: string;
+    extras?: Record<string, unknown>;
+} | {
+    kind: 'ambiguous-continue';
+} | {
+    kind: 'ambiguous-abort';
+    causeSummary?: string[];
+};
+/**
+ * Result of the up-front resolution phase, run once per run-phase invocation
+ * and applied to every migration it covers.
+ *
+ * - `inside-agent`: nx detected it is itself running inside another agent;
+ *   every agentic step is skipped and prompt migrations are surfaced for the
+ *   outer agent to apply.
+ * - `disabled`: the user opted out (explicit `--agentic=false`, declined the
+ *   up-front prompt, or non-TTY without the flag).
+ * - `enabled`: the agentic flow runs and `selectedAgent` is the agent it
+ *   dispatches to.
+ */
+export type ResolvedAgentic = {
+    kind: 'inside-agent';
+} | {
+    kind: 'disabled';
+} | {
+    kind: 'enabled';
+    selectedAgent: DetectedInstalledAgent;
+};
+/** The `enabled` variant, useful for narrowed function signatures. */
+export type EnabledResolvedAgentic = Extract<ResolvedAgentic, {
+    kind: 'enabled';
+}>;

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

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPTS_DIR_NAME = exports.HANDOFFS_DIR_NAME = exports.MIGRATE_RUNS_RELATIVE_DIR = void 0;
+exports.isHandoffGitignoreMigration = isHandoffGitignoreMigration;
+/**
+ * Workspace-relative directory holding all migrate-run scratch: a run
+ * directory per run id. Shared by the run-dir layout in `handoff.ts` and the
+ * agent permission rules in `definitions.ts` so the pre-authorized write scope
+ * can't drift from the actual layout. It lives here so `definitions.ts`,
+ * loaded whenever the agentic flow is resolved, doesn't pull in the handoff
+ * runtime for the path alone.
+ */
+exports.MIGRATE_RUNS_RELATIVE_DIR = '.nx/migrate-runs';
+/**
+ * The one subtree of a run directory an agent writes; everything beside it is
+ * state Nx owns, so the pre-authorized write scope stops here. Handoff names
+ * derive from step ids or package and migration names, so flattening them into
+ * the run dir would leave Nx no name it could safely add.
+ */
+exports.HANDOFFS_DIR_NAME = 'handoffs';
+/**
+ * Sibling subtree holding the per-step prompt files Nx writes for the agent
+ * to read. They stay out of `handoffs/`, which is the agent's to write.
+ */
+exports.PROMPTS_DIR_NAME = 'prompts';
+/**
+ * Composite identity of the v23 migration that adds `.nx/migrate-runs` to
+ * `.gitignore`. Hard-coded because the agentic preflight is a deliberate
+ * one-off coupling: this exact migration owns the entry that keeps
+ * `.nx/migrate-runs/<run-id>/...` scratch out of per-migration commits. If
+ * the migration is ever renamed, this entry must move with it. It lives here
+ * rather than in `handoff-gitignore.ts` so `sortMigrations`' hoist check
+ * doesn't load that module's migration-execution machinery.
+ */
+const HANDOFF_GITIGNORE_MIGRATION_PACKAGE = 'nx';
+const HANDOFF_GITIGNORE_MIGRATION_NAME = '23-0-0-add-migrate-runs-to-git-ignore';
+function isHandoffGitignoreMigration(m) {
+    return (m.package === HANDOFF_GITIGNORE_MIGRATION_PACKAGE &&
+        m.name === HANDOFF_GITIGNORE_MIGRATION_NAME);
+}

package/dist/src/command-line/migrate/agentic/windows-cmd.d.ts

@@ -0,0 +1,33 @@
+import type { SpawnOptions } from 'child_process';
+export declare function quoteCmdArg(arg: string): string;
+export declare function caretEscape(quoted: string): string;
+/**
+ * Stops cmd.exe expanding `%VAR%` inside an argument. A caret cannot escape
+ * `%`, since expansion runs before caret processing, so each `%` becomes
+ * `%%cd:~,%`: `%cd:~,%` is a zero-length substring of a built-in and expands to
+ * nothing, leaving the leading `%`. Runs after the caret passes so the `,` it
+ * introduces stays uncareted, which the substring syntax requires.
+ */
+export declare function neutralizePercent(escaped: string): string;
+export declare const WINDOWS_COMMAND_LINE_LIMIT = 8191;
+export declare const WINDOWS_COMMAND_LINE_BUDGET: number;
+export interface AdaptedSpawn {
+    binary: string;
+    args: string[];
+    options: SpawnOptions;
+    /**
+     * Length of the command line Windows will receive. Set only on the `cmd.exe`
+     * wrapper path.
+     */
+    commandLineLength?: number;
+}
+export declare function withinCommandLineBudget(adapted: AdaptedSpawn): boolean;
+/**
+ * Node's `spawn` cannot directly execute `.cmd` / `.bat` shims on Windows;
+ * `which` resolves to those when an agent was installed via npm. Wrap them in
+ * a `cmd.exe /c` invocation with `windowsVerbatimArguments` so quoting follows
+ * the cmd.exe convention rather than Node's default cooking.
+ *
+ * On non-Windows or for non-shim binaries this is a passthrough.
+ */
+export declare function adaptSpawnForWindowsShim(binary: string, args: readonly string[], options: SpawnOptions): AdaptedSpawn;

package/dist/src/command-line/migrate/agentic/windows-cmd.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WINDOWS_COMMAND_LINE_BUDGET = exports.WINDOWS_COMMAND_LINE_LIMIT = void 0;
+exports.quoteCmdArg = quoteCmdArg;
+exports.caretEscape = caretEscape;
+exports.neutralizePercent = neutralizePercent;
+exports.withinCommandLineBudget = withinCommandLineBudget;
+exports.adaptSpawnForWindowsShim = adaptSpawnForWindowsShim;
+const path_1 = require("path");
+// Backslash-escape embedded quotes per MS C runtime convention, then wrap in
+// quotes. Callers caret-escape cmd.exe metacharacters on top.
+function quoteCmdArg(arg) {
+    return `"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1')}"`;
+}
+const CMD_META_CHARS = /([()\][!^"`<>&|;, ])/g;
+function caretEscape(quoted) {
+    return quoted.replace(CMD_META_CHARS, '^$1');
+}
+/**
+ * Stops cmd.exe expanding `%VAR%` inside an argument. A caret cannot escape
+ * `%`, since expansion runs before caret processing, so each `%` becomes
+ * `%%cd:~,%`: `%cd:~,%` is a zero-length substring of a built-in and expands to
+ * nothing, leaving the leading `%`. Runs after the caret passes so the `,` it
+ * introduces stays uncareted, which the substring syntax requires.
+ */
+function neutralizePercent(escaped) {
+    return escaped.replace(/%/g, '%%cd:~,%');
+}
+// "The maximum length of the string that you can use at the command prompt is
+// 8191 characters".
+// https://learn.microsoft.com/troubleshoot/windows-client/shell-experience/command-line-string-limitation
+exports.WINDOWS_COMMAND_LINE_LIMIT = 8191;
+// Absorbs cmd.exe's own accounting of the string, which cannot be measured
+// from here.
+const WINDOWS_COMMAND_LINE_RESERVE = 1000;
+exports.WINDOWS_COMMAND_LINE_BUDGET = exports.WINDOWS_COMMAND_LINE_LIMIT - WINDOWS_COMMAND_LINE_RESERVE;
+function withinCommandLineBudget(adapted) {
+    return (adapted.commandLineLength === undefined ||
+        adapted.commandLineLength <= exports.WINDOWS_COMMAND_LINE_BUDGET);
+}
+/**
+ * Node's `spawn` cannot directly execute `.cmd` / `.bat` shims on Windows;
+ * `which` resolves to those when an agent was installed via npm. Wrap them in
+ * a `cmd.exe /c` invocation with `windowsVerbatimArguments` so quoting follows
+ * the cmd.exe convention rather than Node's default cooking.
+ *
+ * On non-Windows or for non-shim binaries this is a passthrough.
+ */
+function adaptSpawnForWindowsShim(binary, args, options) {
+    if (process.platform !== 'win32') {
+        return { binary, args: [...args], options };
+    }
+    const ext = (0, path_1.extname)(binary).toLowerCase();
+    if (ext !== '.cmd' && ext !== '.bat') {
+        return { binary, args: [...args], options };
+    }
+    assertNoLineBreaks(binary, args);
+    const cmdLine = [escapeCmdCommand(binary), ...args.map(escapeCmdArg)].join(' ');
+    const comspec = process.env.comspec || 'cmd.exe';
+    // Both modes are set rather than inherited, since a machine-wide registry
+    // setting can flip either: `/e:on` for the `%cd:~,%` substring, `/v:off` so a
+    // `!` stays literal. The outer quotes stop `cmd.exe /c` stripping the inner
+    // ones around the binary path.
+    const cmdArgs = ['/e:on', '/v:off', '/d', '/s', '/c', `"${cmdLine}"`];
+    return {
+        binary: comspec,
+        args: cmdArgs,
+        options: { ...options, windowsVerbatimArguments: true },
+        // `windowsVerbatimArguments` makes the command line the argv joined by
+        // single spaces, so this is what CreateProcess and then cmd.exe see.
+        commandLineLength: [comspec, ...cmdArgs].join(' ').length,
+    };
+}
+// No escaping reproduces a line break on the other side, and cmd.exe truncates
+// the command line at it, so the call is refused.
+function assertNoLineBreaks(binary, args) {
+    const offending = [binary, ...args].find((value) => /[\r\n]/.test(value));
+    if (offending !== undefined) {
+        throw new Error(`Cannot pass a multi-line argument to "${binary}" on Windows: cmd.exe truncates the command line at the line break. Offending argument: ${JSON.stringify(offending.slice(0, 120))}`);
+    }
+}
+function escapeCmdArg(arg) {
+    return neutralizePercent(caretEscape(quoteCmdArg(arg)));
+}
+// cmd.exe parses the command portion twice, so it is caret-escaped twice.
+function escapeCmdCommand(arg) {
+    return neutralizePercent(caretEscape(caretEscape(quoteCmdArg(arg))));
+}

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

@@ -0,0 +1,55 @@
+import { CommandModule } from 'yargs';
+import type { AgenticArg } from './agentic/select';
+import { type StepAction } from './step-actions';
+export declare const yargsMigrateCommand: CommandModule;
+export declare const yargsInternalMigrateCommand: CommandModule;
+export declare const DEFAULT_MIGRATION_COMMIT_PREFIX = "chore: [nx migration] ";
+/** Allowed values for `--include` / `migrate.include`. */
+export declare const MIGRATE_INCLUDE_VALUES: readonly ['required', 'optional', 'all'];
+export type MigrateInclude = (typeof MIGRATE_INCLUDE_VALUES)[number];
+/** Allowed values for `--multi-major-mode` / `migrate.multiMajorMode`. */
+export declare const MULTI_MAJOR_MODES: readonly ['direct', 'gradual'];
+export type MultiMajorMode = (typeof MULTI_MAJOR_MODES)[number];
+/**
+ * The `nx migrate` args bag. Types the keys the nx.json overlay and the
+ * commit-prefix invariant read/write; the index signature keeps the rest of
+ * the yargs args flowing through untouched.
+ */
+export interface MigrateArgs {
+    packageAndVersion?: string;
+    runMigrations?: string;
+    runMigration?: string;
+    runId?: string;
+    stepAction?: StepAction;
+    startFresh?: boolean;
+    include?: MigrateInclude;
+    /**
+     * nx.json `migrate.include` default. Consumed by `resolveInclude` only when the
+     * resolved target supports optional updates; kept separate from `include` so it is never
+     * mistaken for an explicit `--include` (which hard-fails when the target does
+     * not support optional updates).
+     */
+    includeFromConfig?: MigrateInclude;
+    multiMajorMode?: MultiMajorMode;
+    createCommits?: boolean;
+    commitPrefix?: string;
+    agentic?: AgenticArg;
+    validate?: boolean;
+    finalValidation?: boolean;
+    ifExists?: boolean;
+    interactive?: boolean;
+    [key: string]: any;
+}
+/**
+ * Whether a custom commit prefix would be silently ignored: commits aren't
+ * enabled and the agentic flow can't enable them either. Shared by the yargs
+ * `.check()` (CLI args) and the nx.json overlay (merged args) so the rule lives
+ * in one place. `agentic` may flip commits on by default, so a configured
+ * agentic value (other than `false`, and not paired with `--no-create-commits`)
+ * keeps the prefix in play.
+ */
+export declare function customCommitPrefixHasNoEffect(args: {
+    createCommits: boolean | undefined;
+    commitPrefix: string | undefined;
+    agentic: unknown;
+}): boolean;