nx 23.3.0-beta.2 → 23.3.0-beta.4

package/dist/src/command-line/migrate/agentic/master/invocations.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.masterInvariant = masterInvariant;
+exports.masterBootstrapPrompt = masterBootstrapPrompt;
+exports.buildMasterInvocation = buildMasterInvocation;
+const definitions_1 = require("../definitions");
+// One line with no `%`: the Windows shim refuses line breaks and the pinned
+// text is what its command-line budget is measured against.
+function masterInvariant(ctx) {
+    return `You are driving Nx migrate run ${ctx.runId}. Its state lives on disk and is owned by nx migrate; never infer its progress from this conversation. Whenever you are unsure what to do, after a compaction or restart, and after you finish any piece of work, run \`${ctx.reconcileCommand}\` and follow the step block it returns. The run's contract is the runbook at ${ctx.runbookPath}; re-read it whenever a step block says so. When a step block reports the run complete, tell the user the outcome, then create the file ${ctx.sentinelPath} as your last action; nx closes this session once it exists.`;
+}
+function masterBootstrapPrompt(ctx) {
+    return `Read the runbook at ${ctx.runbookPath} in full, then run \`${ctx.reconcileCommand}\` and follow the step block it returns.`;
+}
+const OPENCODE_AGENT_NAME = 'nx-migrate';
+// Keyed by agent id so a new agent fails to compile until it gets a builder.
+const builders = {
+    'claude-code': (ctx) => {
+        const allowedTools = (0, definitions_1.claudeCodeHandoffAllowedTools)(ctx.runId);
+        return {
+            // `--allowedTools` is variadic: the non-variadic flag between it and
+            // the positional prompt keeps the prompt from being read as a rule.
+            args: [
+                ...(allowedTools ? ['--allowedTools', allowedTools] : []),
+                '--append-system-prompt',
+                masterInvariant(ctx),
+                masterBootstrapPrompt(ctx),
+            ],
+        };
+    },
+    codex: (ctx) => ({
+        args: [
+            '-c',
+            `developer_instructions=${(0, definitions_1.encodeTomlString)(masterInvariant(ctx))}`,
+            masterBootstrapPrompt(ctx),
+        ],
+    }),
+    opencode: (ctx) => ({
+        args: [
+            '--agent',
+            OPENCODE_AGENT_NAME,
+            '--prompt',
+            masterBootstrapPrompt(ctx),
+        ],
+        env: {
+            OPENCODE_CONFIG_CONTENT: JSON.stringify({
+                agent: { [OPENCODE_AGENT_NAME]: { prompt: masterInvariant(ctx) } },
+            }),
+        },
+    }),
+};
+function buildMasterInvocation(agentId, ctx) {
+    return builders[agentId](ctx);
+}

package/dist/src/command-line/migrate/agentic/master/run-master-session.d.ts

@@ -0,0 +1,12 @@
+import { type RunOrchestratorInitInput } from '../../run';
+import type { DetectedInstalledAgent } from '../types';
+export interface RunMasterSessionInput extends Omit<RunOrchestratorInitInput, 'emitAgentInstructions'> {
+    agent: DetectedInstalledAgent;
+}
+/**
+ * Starts (or resumes) an orchestrated run and hands it to one agent session
+ * that drives it through `--run-id` reconciles. Run state is the only
+ * authority on the outcome: the exit code follows what run.json says once the
+ * session ends, not what the agent process returned.
+ */
+export declare function runMasterSession(input: RunMasterSessionInput): Promise<number | undefined>;

package/dist/src/command-line/migrate/agentic/master/run-master-session.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMasterSession = runMasterSession;
+const output_1 = require("../../../../utils/output");
+const migrate_analytics_1 = require("../../migrate-analytics");
+const run_1 = require("../../run");
+const spawn_master_1 = require("./spawn-master");
+/**
+ * Starts (or resumes) an orchestrated run and hands it to one agent session
+ * that drives it through `--run-id` reconciles. Run state is the only
+ * authority on the outcome: the exit code follows what run.json says once the
+ * session ends, not what the agent process returned.
+ */
+async function runMasterSession(input) {
+    const { agent, ...init } = input;
+    const ready = await (0, run_1.runOrchestratorInit)({
+        ...init,
+        emitAgentInstructions: false,
+    });
+    if (ready.kind === 'refused') {
+        return;
+    }
+    const { runId, runRoot, runbookPath, reconcileCommand } = ready;
+    // Not rendered: the gate env var and the migrations path would have to be
+    // reproduced, and the same command carries both.
+    const resumeHint = 'Run the same nx migrate command again to resume it.';
+    output_1.output.log({
+        title: `Starting ${agent.displayName} to drive migrate run ${runId}.`,
+    });
+    const session = await (0, spawn_master_1.spawnMasterSession)({
+        agent,
+        runRoot,
+        runId,
+        runbookPath,
+        reconcileCommand,
+        policy: {
+            createCommits: init.createCommits,
+            skipInstall: init.skipInstall,
+        },
+    });
+    if (session.kind === 'spawn-failed') {
+        output_1.output.error({
+            title: `Could not start ${agent.displayName}: ${session.error.message}`,
+            bodyLines: [`Migrate run ${runId} is still active. ${resumeHint}`],
+        });
+        (0, migrate_analytics_1.reportMigrateRunError)({ code: 'agentic', error: session.error });
+        return 1;
+    }
+    if (session.kind === 'broker-failed') {
+        // The broker itself reads run.json, so its failure can mean the state is
+        // unreadable; the read below decides whether a resume is safe to offer.
+        output_1.output.error({
+            title: `Closed the ${agent.displayName} session: a step's request could not be answered (${session.error.message}).`,
+        });
+        (0, migrate_analytics_1.reportMigrateRunError)({ code: 'agentic', error: session.error });
+    }
+    let state;
+    try {
+        state = (0, run_1.readRunState)((0, run_1.runDir)(runRoot, runId));
+    }
+    catch (error) {
+        // No resume hint: run discovery skips a directory whose run.json is
+        // missing, so a rerun could start a second run over the same plan.
+        output_1.output.error({
+            title: `Nx could not determine whether migrate run ${runId} completed.`,
+            bodyLines: [error instanceof Error ? error.message : String(error)],
+        });
+        return 1;
+    }
+    switch (state.status) {
+        case 'active':
+            output_1.output.warn({
+                title: `Migrate run ${runId} is still active. ${resumeHint}`,
+            });
+            return 1;
+        case 'completed': {
+            const applied = state.steps.filter((s) => s.status === 'succeeded').length;
+            const skipped = state.steps.filter((s) => s.status === 'skipped').length;
+            output_1.output.log({
+                title: `Migrate run ${runId} is complete.`,
+                bodyLines: [`  applied: ${applied}`, `  skipped: ${skipped}`],
+            });
+            for (const lines of (0, run_1.completionWarnings)(runRoot, runId, state)) {
+                output_1.output.warn({ title: lines[0], bodyLines: lines.slice(1) });
+            }
+            (0, migrate_analytics_1.reportMigrateRunComplete)({
+                agenticOutcome: 'enabled',
+                agentUsed: agent.id,
+                migrationCount: state.steps.length,
+                appliedCount: applied,
+            });
+            return;
+        }
+        default: {
+            const unhandled = state.status;
+            throw new Error(`Unhandled migrate run status: ${unhandled}`);
+        }
+    }
+}

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

@@ -0,0 +1,31 @@
+import { type MigrateRunPolicy } from '../../run';
+import type { DetectedInstalledAgent } from '../types';
+export interface SpawnMasterSessionInput {
+    agent: DetectedInstalledAgent;
+    runRoot: string;
+    runId: string;
+    runbookPath: string;
+    reconcileCommand: string;
+    policy: MigrateRunPolicy;
+    sentinelPollIntervalMs?: number;
+    gracefulExitMs?: number;
+    forceKillWaitMs?: number;
+}
+export type SpawnMasterSessionResult = {
+    kind: 'exited';
+} | {
+    kind: 'spawn-failed';
+    error: Error;
+} | {
+    kind: 'broker-failed';
+    error: Error;
+};
+/**
+ * Spawns the agent once, with the run's pinned invariant and bootstrap prompt,
+ * and waits for the session to end, closing it once the agent writes the
+ * session-complete sentinel. Meanwhile it answers the install and commit
+ * requests the steps the agent runs hand out of its sandbox. Every failure
+ * before the process starts is returned as `spawn-failed`; what the session
+ * did is read from run state by the caller, never from the exit code.
+ */
+export declare function spawnMasterSession(input: SpawnMasterSessionInput): Promise<SpawnMasterSessionResult>;

package/dist/src/command-line/migrate/agentic/master/spawn-master.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnMasterSession = spawnMasterSession;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const logger_1 = require("../../../../utils/logger");
+const output_1 = require("../../../../utils/output");
+const migrate_output_1 = require("../../migrate-output");
+const run_1 = require("../../run");
+const close_agent_session_1 = require("../close-agent-session");
+const handoff_1 = require("../handoff");
+const terminal_repair_1 = require("../terminal-repair");
+const windows_cmd_1 = require("../windows-cmd");
+const invocations_1 = require("./invocations");
+// The wrapper's local re-exec sets the first two for its own hop and the user
+// sets the third to reach this path; inherited, they would change install or
+// routing behavior for every `nx migrate` the agent runs.
+const STRIPPED_ENV_VARS = [
+    'NX_MIGRATE_SKIP_INSTALL',
+    'NX_MIGRATE_USE_LOCAL',
+    'NX_MIGRATE_ORCHESTRATOR',
+];
+// Under handoffs/ so claude's run-scoped Edit rule already admits the write;
+// nothing lists that directory. The nonce keeps a sentinel left by an earlier
+// session of the same run from closing this one.
+function sessionCompleteSentinel(runRoot, runId, nonce) {
+    return (0, path_1.join)((0, run_1.runHandoffsDir)((0, run_1.runDir)(runRoot, runId)), `session-complete-${nonce}`);
+}
+/**
+ * Spawns the agent once, with the run's pinned invariant and bootstrap prompt,
+ * and waits for the session to end, closing it once the agent writes the
+ * session-complete sentinel. Meanwhile it answers the install and commit
+ * requests the steps the agent runs hand out of its sandbox. Every failure
+ * before the process starts is returned as `spawn-failed`; what the session
+ * did is read from run state by the caller, never from the exit code.
+ */
+async function spawnMasterSession(input) {
+    const { agent, runRoot, runId, runbookPath, reconcileCommand, policy, sentinelPollIntervalMs = 500, gracefulExitMs = close_agent_session_1.AGENT_GRACEFUL_EXIT_MS, forceKillWaitMs = close_agent_session_1.FORCE_KILL_WAIT_MS, } = input;
+    let sentinelPath;
+    let child;
+    let broker;
+    try {
+        // Locked before the agent exists: a step must never find the lock free
+        // while its parent is alive.
+        broker = new run_1.MigrateCommitBroker(runRoot, (0, run_1.runDir)(runRoot, runId), reconcileCommand, policy);
+        sentinelPath = sessionCompleteSentinel(runRoot, runId, broker.nonce);
+        const spec = (0, invocations_1.buildMasterInvocation)(agent.id, {
+            runId,
+            reconcileCommand,
+            runbookPath: prosePath(runRoot, runbookPath),
+            sentinelPath: prosePath(runRoot, sentinelPath),
+        });
+        const env = { ...process.env, ...spec.env };
+        for (const name of STRIPPED_ENV_VARS) {
+            delete env[name];
+        }
+        env[run_1.BROKER_ENV_VAR] = broker.nonce;
+        const adapted = (0, windows_cmd_1.adaptSpawnForWindowsShim)(agent.binary, spec.args, {
+            stdio: 'inherit',
+            cwd: runRoot,
+            env,
+            windowsHide: true,
+        });
+        assertWithinWindowsCommandLineBudget(adapted, agent, runId);
+        // A symlink here would send the agent's write and the poll below elsewhere.
+        const handoffsDir = (0, path_1.dirname)(sentinelPath);
+        (0, handoff_1.ensureRunSubdir)(handoffsDir, () => new Error(`Migrate run ${runId} has something other than a directory at ${handoffsDir}; remove it and try again.`));
+        // Local alias so `@nx/workspace-require-windows-hide` can track the
+        // options as an Identifier.
+        const spawnOptions = adapted.options;
+        child = (0, child_process_1.spawn)(adapted.binary, adapted.args, spawnOptions);
+    }
+    catch (error) {
+        broker?.close();
+        return { kind: 'spawn-failed', error: toError(error) };
+    }
+    // Ctrl+C belongs to the agent from the moment it exists.
+    const swallowSigint = () => { };
+    process.on('SIGINT', swallowSigint);
+    const sentinelWatch = new AbortController();
+    let brokerFailure;
+    // Settles when the poll aborts and the request in flight is answered, or
+    // early when a request could not be answered at all.
+    const brokerDone = serviceBrokerUntilAborted(broker, sentinelPollIntervalMs, sentinelWatch.signal).catch((error) => {
+        brokerFailure = toError(error);
+    });
+    let started = false;
+    try {
+        const exitPromise = (0, close_agent_session_1.waitForExit)(child);
+        // The usual missing-binary failure is an `error` event with no `exit`
+        // (ENOENT after detection); before `spawn` it is a failure to start, not
+        // a session that ended.
+        const spawnError = await new Promise((resolve) => {
+            child.once('spawn', () => resolve(null));
+            child.once('error', (error) => resolve(error));
+        });
+        if (spawnError) {
+            return { kind: 'spawn-failed', error: spawnError };
+        }
+        started = true;
+        let exit = {};
+        const winner = await Promise.race([
+            exitPromise.then((info) => {
+                exit = info;
+                return 'exit';
+            }),
+            waitForFile(sentinelPath, sentinelPollIntervalMs, sentinelWatch.signal).then(() => 'sentinel'),
+            brokerDone.then(() => 'broker-failed'),
+        ]);
+        if (winner !== 'exit') {
+            await (0, close_agent_session_1.closeAgentSession)(child, exitPromise, gracefulExitMs, forceKillWaitMs);
+            // The close can return on `exitCode` while `waitForExit` is still in
+            // its merge window; bounded so a stuck child cannot hold the run.
+            await (0, close_agent_session_1.raceWithTimeout)(exitPromise, forceKillWaitMs);
+        }
+        if (winner === 'sentinel') {
+            // Hygiene only; run state decides the outcome, not this removal.
+            try {
+                (0, fs_1.rmSync)(sentinelPath, { force: true });
+            }
+            catch (error) {
+                logger_1.logger.verbose(`Could not remove ${sentinelPath}: ${toError(error).message}`);
+            }
+        }
+        logger_1.logger.verbose(`${agent.displayName} session ended (code: ${exit.code ?? 'none'}, signal: ${exit.signal ?? 'none'}${exit.error ? `, error: ${exit.error.message}` : ''}).`);
+    }
+    finally {
+        sentinelWatch.abort();
+        // With the agent gone, the terminal is restored before the wait: an
+        // agent that left it raw would keep a Ctrl+C from reaching the operation
+        // in flight as a signal.
+        const exited = child.exitCode !== null || child.signalCode !== null;
+        if (started && exited) {
+            restoreTerminal();
+            warnOperationInFlight(broker);
+        }
+        // The request in flight settles before the lock is released.
+        await brokerDone;
+        broker.close();
+        process.removeListener('SIGINT', swallowSigint);
+        if (started && !exited)
+            restoreTerminal();
+    }
+    return brokerFailure
+        ? { kind: 'broker-failed', error: brokerFailure }
+        : { kind: 'exited' };
+}
+function restoreTerminal() {
+    (0, terminal_repair_1.restoreTermiosAfterAgent)();
+    (0, migrate_output_1.resetSgrAfterAgent)();
+}
+// With the agent gone a Ctrl+C reaches the operation's child process, and
+// nothing else tells the user one is still running.
+function warnOperationInFlight(broker) {
+    const request = broker.requestInFlight;
+    if (!request)
+        return;
+    output_1.output.warn({
+        title: `Still running ${(0, run_1.treeOperationLabel)(request)} for this migrate run. Press Ctrl+C to end it; the run can be resumed afterwards.`,
+    });
+}
+async function serviceBrokerUntilAborted(broker, intervalMs, signal) {
+    while (!signal.aborted) {
+        await broker.service();
+        await delayUnlessAborted(intervalMs, signal);
+    }
+}
+function delayUnlessAborted(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+// Workspace-relative with forward slashes on every platform: prose the agent
+// reads, not a shell path.
+function prosePath(runRoot, path) {
+    return (0, path_1.relative)(runRoot, path).split(path_1.sep).join('/');
+}
+// Never settles after an abort; the race it feeds has settled by then.
+function waitForFile(path, intervalMs, signal) {
+    return new Promise((resolve) => {
+        let timer;
+        const tick = () => {
+            if (signal.aborted)
+                return;
+            if ((0, fs_1.existsSync)(path)) {
+                resolve();
+                return;
+            }
+            timer = setTimeout(tick, intervalMs);
+        };
+        signal.addEventListener('abort', () => clearTimeout(timer), { once: true });
+        timer = setTimeout(tick, intervalMs);
+    });
+}
+function assertWithinWindowsCommandLineBudget(adapted, agent, runId) {
+    if ((0, windows_cmd_1.withinCommandLineBudget)(adapted)) {
+        return;
+    }
+    throw new Error(`Launching ${agent.displayName} needs a ${adapted.commandLineLength}-character command line. cmd.exe runs at most ${windows_cmd_1.WINDOWS_COMMAND_LINE_LIMIT} characters, and nx stops at ${windows_cmd_1.WINDOWS_COMMAND_LINE_BUDGET} to leave room for what it cannot measure from here. ` +
+        `What varies is the cmd.exe path (${adapted.binary.length} characters), the agent path (${agent.binary.length} characters) and the run id (${runId.length} characters); shorten one of them.`);
+}

package/dist/src/command-line/migrate/agentic/prompts/fragments.js

@@ -8,6 +8,7 @@ exports.renderHandoffShapeLines = renderHandoffShapeLines;
 exports.renderAuthorScopeRuleLines = renderAuthorScopeRuleLines;
 exports.renderValidationScopeRuleLines = renderValidationScopeRuleLines;
 const format_command_1 = require("../format-command");
+const types_1 = require("../types");
 function renderNxInvocationNote(packageManager, nxInvocation) {
     return `Use \`${packageManager}\` for any package-manager invocation in this workspace. To invoke nx, use \`${nxInvocation} ...\`. Do not default to a different package manager based on your own preference.`;
 }
@@ -29,6 +30,7 @@ function renderAuthorScopeRuleLines(pmExec, format) {
         `- Do not refactor or update dependencies beyond what the migration prompt directs, and do not reformat files you did not change.`,
         renderFormatRule(pmExec, format),
         `- Do not modify files outside the workspace root.`,
+        `- Do not edit anything under \`${types_1.MIGRATE_RUNS_RELATIVE_DIR}\` except the handoff file you are asked to write.`,
         `- Do not run \`nx\` commands that mutate workspace state (\`nx migrate\`, \`nx reset\`, \`nx format:write\`, \`nx run-many\`, generators, etc.). Read-only inspection (\`nx show\`, \`nx graph --file\`, reading files) is fine.`,
         `- If the migration instructions are unclear, internally inconsistent, or conflict with the current workspace state, ask the user for direction (see the handoff contract). Do not guess.`,
     ];
@@ -65,6 +67,7 @@ function renderValidationScopeRuleLines() {
         `- You may apply minor fixes only when the issue lies within the scope of what this migration intended to accomplish (e.g. a missing import the generator's template should have produced, a type annotation the template missed). Do not refactor, do not modify unrelated functionality, do not extend the migration's scope, do not touch code the migration was not concerned with. If you are unsure whether a fix is in scope, report it in \`summary\` instead of applying.`,
         `- Do not run other \`nx\` commands that mutate workspace state (\`nx migrate\`, \`nx reset\`, generators, etc.).`,
         `- Do not modify files outside the workspace root.`,
+        `- Do not edit anything under \`${types_1.MIGRATE_RUNS_RELATIVE_DIR}\` except the handoff file you are asked to write.`,
         `- If validation finds blocking issues you cannot resolve within scope: apply every fix you can within scope, then report the unresolved findings to the user and ask how to proceed (see the handoff contract). Do not guess.`,
     ];
 }

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

@@ -1,4 +1,3 @@
-import { SpawnOptions } from 'child_process';
 import { AgentDefinition, DetectedInstalledAgent, HandoffOutcome, InvocationContext } from './types';
 export interface RunAgenticArgs {
     detected: DetectedInstalledAgent;
@@ -20,23 +19,3 @@ export interface RunAgenticArgs {
  * the handoff file (or the user when the file is missing).
  */
 export declare function runAgentic(args: RunAgenticArgs): Promise<HandoffOutcome>;
-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;
-}
-/**
- * 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;