@depup/nx 23.2.1-depup.7 → 23.3.0-depup.0

package/dist/src/command-line/migrate/agentic/close-agent-session.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FORCE_KILL_WAIT_MS = exports.AGENT_GRACEFUL_EXIT_MS = void 0;
+exports.waitForExit = waitForExit;
+exports.closeAgentSession = closeAgentSession;
+exports.raceWithTimeout = raceWithTimeout;
+const child_process_1 = require("child_process");
+exports.AGENT_GRACEFUL_EXIT_MS = 5_000;
+// Safety bound after force-kill. SIGKILL normally reaps in microseconds;
+// the bound exists for uninterruptible kernel calls or taskkill returning
+// before the process actually exits.
+exports.FORCE_KILL_WAIT_MS = 500;
+// Merge window so a paired exit + error both land in one ExitInfo. On
+// error-only paths like spawn ENOENT, where Node fires error but never exit,
+// this timer is the only settlement mechanism.
+const EXIT_MERGE_WINDOW_MS = 10;
+function waitForExit(child) {
+    return new Promise((resolve) => {
+        const info = {};
+        let pending = null;
+        let settled = false;
+        const settle = () => {
+            if (settled)
+                return;
+            settled = true;
+            if (pending)
+                clearTimeout(pending);
+            resolve(info);
+        };
+        const onFirst = () => {
+            if (settled || pending)
+                return;
+            pending = setTimeout(settle, EXIT_MERGE_WINDOW_MS);
+        };
+        child.on('exit', (code, signal) => {
+            info.code = code;
+            info.signal = signal;
+            onFirst();
+        });
+        child.on('error', (error) => {
+            info.error = error;
+            onFirst();
+        });
+    });
+}
+/**
+ * Stops a running agent process.
+ *
+ * POSIX: SIGINT, then SIGKILL after a bounded wait. SIGTERM is skipped so a
+ * child that ignored the first graceful signal does not get a second one.
+ *
+ * Windows: `taskkill /T /F`. `child.kill` is a `TerminateProcess` call whatever
+ * the signal name, which on the `cmd.exe` shim path would kill the shim and
+ * orphan the agent. `taskkill` failures are swallowed.
+ */
+async function closeAgentSession(child, exitPromise, gracefulExitMs, forceKillWaitMs) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    if (process.platform === 'win32') {
+        await forceKillWindowsTree(child, exitPromise, forceKillWaitMs);
+        return;
+    }
+    try {
+        child.kill('SIGINT');
+    }
+    catch {
+        // child already gone between the check above and here
+        return;
+    }
+    let escalation;
+    try {
+        await Promise.race([
+            exitPromise,
+            new Promise((resolve) => {
+                escalation = setTimeout(resolve, gracefulExitMs);
+            }),
+        ]);
+    }
+    finally {
+        if (escalation)
+            clearTimeout(escalation);
+    }
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    try {
+        child.kill('SIGKILL');
+    }
+    catch {
+        /* child already gone */
+    }
+    await raceWithTimeout(exitPromise, forceKillWaitMs);
+}
+async function forceKillWindowsTree(child, exitPromise, forceKillWaitMs) {
+    const pid = child.pid;
+    // No pid means spawn itself failed, which the guard in `closeAgentSession`
+    // normally short-circuits. Without one there is nothing to taskkill.
+    if (pid !== undefined) {
+        try {
+            (0, child_process_1.execSync)(`taskkill /T /F /PID ${pid}`, {
+                stdio: 'ignore',
+                windowsHide: true,
+                // Bound so a hung Windows shell can't block the orchestrator.
+                timeout: 2_000,
+            });
+        }
+        catch {
+            /* taskkill missing, pid already dead, or timed out */
+        }
+    }
+    await raceWithTimeout(exitPromise, forceKillWaitMs);
+}
+async function raceWithTimeout(promise, timeoutMs) {
+    let timer;
+    try {
+        await Promise.race([
+            promise,
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

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

@@ -1,5 +1,29 @@
 import { AgentDefinition, AgentId } from './types';
+/**
+ * Pre-authorizes the handoff write. Claude Code's default permission mode
+ * asks before a file write it has no allow rule for, so without this every
+ * step ends on an approval prompt for Nx's own handoff scratch.
+ *
+ * The rule reaches one run's handoffs and nothing else. Its own run
+ * directory also holds state Nx wrote and reads back, and the sibling
+ * directories belong to other runs, including an orchestrated run whose
+ * handoffs decide how its steps settle. `Edit` is the only tool name file
+ * rules are matched against, and it covers creating the file as well as
+ * correcting one already written. Prefix-less patterns resolve against the
+ * session cwd, which every caller pins to the workspace root.
+ *
+ * Returns null for a name it cannot express, which costs the approval prompt
+ * this exists to avoid. That beats widening the rule, and nothing narrower is
+ * available: Claude Code has no escape for a literal path.
+ */
+export declare function claudeCodeHandoffAllowedTools(runDirName: string): string | null;
 export declare const claudeCodeDefinition: AgentDefinition;
+/**
+ * Encodes a single-line TOML string for codex overrides. Codex treats a parse
+ * failure as literal text instead of reporting it, so the result is parsed
+ * back before it reaches the command line.
+ */
+export declare function encodeTomlString(value: string): string;
 export declare const codexDefinition: AgentDefinition;
 export declare const opencodeDefinition: AgentDefinition;
 export declare const AGENT_DEFINITIONS: readonly AgentDefinition[];

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

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AGENT_DEFINITIONS = exports.opencodeDefinition = exports.codexDefinition = exports.claudeCodeDefinition = void 0;
+exports.claudeCodeHandoffAllowedTools = claudeCodeHandoffAllowedTools;
+exports.encodeTomlString = encodeTomlString;
 exports.getAgentDefinition = getAgentDefinition;
 const os_1 = require("os");
 const path_1 = require("path");
+const smol_toml_1 = require("smol-toml");
 const types_1 = require("./types");
 // --- Claude Code ---------------------------------------------------------
 function claudeCodeWellKnownPaths() {
@@ -34,7 +37,7 @@ const RULE_SAFE_RUN_DIR_NAME = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
  * handoffs decide how its steps settle. `Edit` is the only tool name file
  * rules are matched against, and it covers creating the file as well as
  * correcting one already written. Prefix-less patterns resolve against the
- * session cwd, pinned to the workspace root below.
+ * session cwd, which every caller pins to the workspace root.
  *
  * Returns null for a name it cannot express, which costs the approval prompt
  * this exists to avoid. That beats widening the rule, and nothing narrower is
@@ -49,15 +52,14 @@ function claudeCodeHandoffAllowedTools(runDirName) {
 function claudeCodeBuildInteractive(ctx) {
     const allowedTools = claudeCodeHandoffAllowedTools(ctx.runDirName);
     return {
-        // `--allowedTools` is variadic (space/comma separated): a positional
-        // placed right after its value gets swallowed as another rule. The rules
-        // must stay in one comma-joined element with a non-variadic flag
-        // (`--system-prompt`) between them and the user prompt.
+        // `--allowedTools` is variadic, so a positional right after it is read as
+        // another rule: keep the rules in one comma-joined element and a flag
+        // between them and the instructions pointer.
         args: [
             ...(allowedTools ? ['--allowedTools', allowedTools] : []),
-            '--system-prompt',
-            ctx.systemContext,
-            ctx.userPrompt,
+            '--system-prompt-file',
+            ctx.systemPromptFilePath,
+            ctx.instructionsPointer,
         ],
         cwd: ctx.workspaceRoot,
     };
@@ -74,14 +76,42 @@ function codexWellKnownPaths() {
     return [];
 }
 // No handoff permission flag: codex's default sandbox already allows writes
-// inside the cwd tree without prompting, and a user-hardened read-only config
-// is a deliberate choice we don't override.
+// inside the cwd tree (`.git` excepted), and a user-hardened read-only config
+// is theirs to keep.
+//
+// `-c model_instructions_file` replaces codex's built-in instructions rather
+// than adding this context to them, so the context stays on the command line,
+// reduced rather than the full prompt.
 function codexBuildInteractive(ctx) {
     return {
-        args: ['-c', `developer_instructions=${ctx.systemContext}`, ctx.userPrompt],
+        args: [
+            '-c',
+            `developer_instructions=${encodeTomlString(ctx.inlineSystemContext)}`,
+            ctx.instructionsPointer,
+        ],
         cwd: ctx.workspaceRoot,
     };
 }
+/**
+ * Encodes a single-line TOML string for codex overrides. Codex treats a parse
+ * failure as literal text instead of reporting it, so the result is parsed
+ * back before it reaches the command line.
+ */
+function encodeTomlString(value) {
+    // JSON escapes every control TOML rejects except DEL, which it leaves raw.
+    const encoded = JSON.stringify(value).replace(/\x7f/g, '\\u007F');
+    let decoded;
+    try {
+        decoded = (0, smol_toml_1.parse)(`value = ${encoded}`).value;
+    }
+    catch (err) {
+        throw new Error(`Could not encode the agent's system context as TOML for OpenAI Codex: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    if (decoded !== value) {
+        throw new Error(`Encoding the agent's system context as TOML for OpenAI Codex did not round-trip; refusing to run the agent on altered instructions.`);
+    }
+    return encoded;
+}
 exports.codexDefinition = {
     id: 'codex',
     displayName: 'OpenAI Codex',
@@ -110,25 +140,54 @@ function opencodeWellKnownPaths() {
     return candidates;
 }
 // No handoff permission config: opencode's `edit` permission defaults to
-// allow, and injecting one would clobber (not merge with) a user's own
-// permission patterns.
+// allow, and injecting one would clobber a user's own patterns rather than
+// merge with them.
+//
+// The config travels through OPENCODE_CONFIG_CONTENT rather than
+// OPENCODE_CONFIG. Both merge with the user's own config, but the runner
+// spreads `env` over `process.env`, so the latter would overwrite a value the
+// user had set.
 function opencodeBuildInteractive(ctx) {
-    const config = {
-        agent: {
-            [OPENCODE_TRANSIENT_AGENT_NAME]: { prompt: ctx.systemContext },
-        },
-    };
     return {
         args: [
             '--agent',
             OPENCODE_TRANSIENT_AGENT_NAME,
             '--prompt',
-            ctx.userPrompt,
+            ctx.instructionsPointer,
         ],
-        env: { OPENCODE_CONFIG_CONTENT: JSON.stringify(config) },
+        env: { OPENCODE_CONFIG_CONTENT: opencodeConfigContent(ctx) },
         cwd: ctx.workspaceRoot,
     };
 }
+/**
+ * Escapes inline prompt patterns before opencode's pre-JSON substitution pass.
+ * Excludes generator instructions from the config; cmd.exe drops inherited
+ * variables longer than 8191 characters.
+ */
+function opencodeConfigContent(ctx) {
+    // Windows separators become `/`, which its APIs accept just as well.
+    // Elsewhere a `\` belongs to the file name.
+    const filePath = process.platform === 'win32'
+        ? ctx.systemPromptFilePath.replace(/\\/g, '/')
+        : ctx.systemPromptFilePath;
+    const prompt = isSubstitutionSafePath(filePath)
+        ? JSON.stringify(`{file:${filePath}}`)
+        : // `\u007b` starts no pattern and JSON decodes it back to `{`, so the
+            // prompt survives expansion whatever the workspace path put in it.
+            JSON.stringify(ctx.systemPrompt).replace(/\{/g, '\\u007b');
+    // Assembled rather than serialized whole: `JSON.stringify` over the object
+    // would re-escape the backslashes the `\u007b` encoding introduced.
+    return `{"agent":{${JSON.stringify(OPENCODE_TRANSIENT_AGENT_NAME)}:{"prompt":${prompt}}}}`;
+}
+/**
+ * Whether opencode would read back the path nx wrote. A `}` closes the
+ * reference early, and a character JSON escapes arrives escaped. Braces are
+ * rejected wholesale rather than matched against `{env:` and `{file:`, since a
+ * pattern opening inside the path swallows the reference's closing brace.
+ */
+function isSubstitutionSafePath(filePath) {
+    return (!/[{}]/.test(filePath) && JSON.stringify(filePath).slice(1, -1) === filePath);
+}
 exports.opencodeDefinition = {
     id: 'opencode',
     displayName: 'OpenCode',

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

@@ -0,0 +1,14 @@
+import { FormatterType } from '../../../utils/formatters';
+/**
+ * The command the agent runs over the files it changed, with a `<paths>`
+ * placeholder. `--` keeps a path that starts with `-` from being read as an
+ * option.
+ */
+export declare function formatCommandFor(formatter: FormatterType, pmExec: string): string;
+/**
+ * Resolved per dispense so a migration's formatter change takes effect; the
+ * scope rules name the replacement commands for the step that made it. `null`
+ * when no formatter is configured or its binary cannot be resolved: under npm
+ * the command would otherwise make `npx` download it.
+ */
+export declare function resolveFormatCommand(root: string, pmExec: string): string | null;

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

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCommandFor = formatCommandFor;
+exports.resolveFormatCommand = resolveFormatCommand;
+const formatters_1 = require("../../../utils/formatters");
+/**
+ * The command the agent runs over the files it changed, with a `<paths>`
+ * placeholder. `--` keeps a path that starts with `-` from being read as an
+ * option.
+ */
+function formatCommandFor(formatter, pmExec) {
+    switch (formatter) {
+        case 'prettier':
+            // --ignore-unknown skips files prettier has no parser for.
+            return `${pmExec} prettier --write --ignore-unknown -- <paths>`;
+        case 'oxfmt':
+            // oxfmt exits 2 when every path was skipped; the flag makes that
+            // success. Unlike prettier it skips unparseable files on its own.
+            return `${pmExec} oxfmt --no-error-on-unmatched-pattern -- <paths>`;
+        default: {
+            const unhandled = formatter;
+            throw new Error(`Unhandled formatter: ${unhandled}`);
+        }
+    }
+}
+/**
+ * Resolved per dispense so a migration's formatter change takes effect; the
+ * scope rules name the replacement commands for the step that made it. `null`
+ * when no formatter is configured or its binary cannot be resolved: under npm
+ * the command would otherwise make `npx` download it.
+ */
+function resolveFormatCommand(root, pmExec) {
+    const formatter = (0, formatters_1.detectFormatter)(root);
+    if (formatter === null) {
+        return null;
+    }
+    try {
+        formatters_1.resolveFormatterBin[formatter]();
+    }
+    catch {
+        return null;
+    }
+    return formatCommandFor(formatter, pmExec);
+}

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

@@ -1,8 +1,8 @@
 /**
  * Both the agentic runner and the orchestrator write per-run scratch under
- * `.nx/migrate-runs/<run-id>/`: handoff files in both cases, plus the durable
- * run state and its plan snapshots for the orchestrator. The v23 migration
- * `23-0-0-add-migrate-runs-to-git-ignore` adds `.nx/migrate-runs` to
+ * `.nx/migrate-runs/<run-id>/`: handoff and prompt files in both cases, plus
+ * the durable run state and its plan snapshots for the orchestrator. The v23
+ * migration `23-0-0-add-migrate-runs-to-git-ignore` adds `.nx/migrate-runs` to
  * `.gitignore`; in its declared slot (typically late) earlier per-migration
  * commits would absorb the scratch into the user-visible diff.
  *

package/dist/src/command-line/migrate/agentic/handoff-gitignore.js

@@ -11,9 +11,9 @@ const logger_1 = require("../../../utils/logger");
 const types_1 = require("./types");
 /**
  * Both the agentic runner and the orchestrator write per-run scratch under
- * `.nx/migrate-runs/<run-id>/`: handoff files in both cases, plus the durable
- * run state and its plan snapshots for the orchestrator. The v23 migration
- * `23-0-0-add-migrate-runs-to-git-ignore` adds `.nx/migrate-runs` to
+ * `.nx/migrate-runs/<run-id>/`: handoff and prompt files in both cases, plus
+ * the durable run state and its plan snapshots for the orchestrator. The v23
+ * migration `23-0-0-add-migrate-runs-to-git-ignore` adds `.nx/migrate-runs` to
  * `.gitignore`; in its declared slot (typically late) earlier per-migration
  * commits would absorb the scratch into the user-visible diff.
  *

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

@@ -1,3 +1,4 @@
+import { type BigIntStats } from 'fs';
 import { HandoffFile } from './types';
 /** Returns the run directory for a given workspace + run id (target version). */
 export declare function runDirPath(workspaceRoot: string, runId: string): string;
@@ -19,19 +20,17 @@ export declare function mkdirSafely(dir: string, purpose: string): void;
  * inspection.
  */
 export declare function initRunDir(workspaceRoot: string, runId: string): string;
-/**
- * Absolute path of the handoff file for a migration step within a run, under
- * the run directory's `handoffs/` subtree: the pre-authorized write scope
- * stops there, so a handoff placed anywhere else costs an approval prompt.
- * The package's scope (if any) becomes a real subdirectory so the package name
- * stays readable; two packages can ship a migration with the same name without
- * colliding because they land in different package subdirectories. Each
- * segment is sanitized so the path is always writable on every platform.
- */
+export declare function truncateUtf8(value: string, maxBytes: number): string;
 export declare function stepHandoffPath(runDir: string, migration: {
     package: string;
     name: string;
 }): string;
+/** Handoff path for a run step. No hash needed: step ids are unique within the run. */
+export declare function runStepHandoffPath(runDir: string, stepId: string): string;
+export declare function stepPromptsDir(runDir: string, migration: {
+    package: string;
+    name: string;
+}): string;
 export type HandoffReadFailureReason = 'missing' | 'read-error' | 'parse-error' | 'shape-mismatch';
 export type HandoffReadResult = {
     ok: true;
@@ -42,19 +41,53 @@ export type HandoffReadResult = {
     detail?: string;
 };
 /**
- * Reads and validates a handoff file written by an agent. Returns a tagged
- * result so callers (the in-loop poller and the post-exit resolver) can
- * distinguish "file not yet written" from "file written but garbage" — the
- * latter is surfaced to the user instead of being collapsed into the same
- * generic ambiguous-outcome prompt.
+ * `lstat`, not `stat`: a symlink in the handoffs dir's place would send every
+ * handoff read and removal wherever it points.
+ */
+export declare function handoffsDirState(handoffsDir: string): 'directory' | 'missing' | 'other';
+/**
+ * Non-recursive mkdir: the run dir exists, and a symlink created after the
+ * missing-path check fails with EEXIST instead of being followed.
+ */
+export declare function ensureRunSubdir(dir: string, notADirectory: () => Error): void;
+/**
+ * Thrown by {@link readInspectedFile} when the opened descriptor is not the
+ * file the caller's lstat described: a symlink followed on Windows, or an
+ * atomic replacement between the lstat and the open.
+ */
+export declare class FileReplacedDuringReadError extends Error {
+}
+/**
+ * Reads the file `stat` describes, refusing a symlink swapped in after the
+ * caller's lstat: O_NOFOLLOW fails the open with ELOOP, and O_NONBLOCK keeps a
+ * planted FIFO from blocking it. Windows has neither flag, so there the inode
+ * comparison is what catches a followed symlink. It does not guard against an
+ * unlink and recreate reusing the inode number. Read errors propagate: a file
+ * the agent cannot read must not pass.
+ */
+export declare function readInspectedFile(filePath: string, stat: BigIntStats, replacedMessage: string): string;
+/**
+ * Reads a file its owner publishes atomically (tmp + rename), with
+ * {@link readInspectedFile}'s refusal of a symlink or FIFO but tolerant of the
+ * publish: a rename swaps the inode between the lstat and the open, read as a
+ * replacement, so re-lstat and retry to read the new file. A pre-existing
+ * symlink or FIFO fails the isFile check before any open; a file that keeps
+ * changing past the retry budget is refused. Throws `notRegularMessage` for a
+ * non-regular file; ENOENT and ELOOP propagate.
+ */
+export declare function readAtomicallyPublishedFile(filePath: string, notRegularMessage: string): string;
+/**
+ * Splits "not written yet" from "written but garbage" so callers can surface a
+ * malformed handoff instead of collapsing it into the generic
+ * ambiguous-outcome prompt.
  */
-export declare function readHandoffWithReason(filePath: string): HandoffReadResult;
+export declare function readHandoffWithReason(filePath: string, handoffsDir: string): HandoffReadResult;
 /**
  * Convenience wrapper preserving the original null-on-any-failure contract.
  * Used by the polling loop (`waitForValidHandoff`) where every failure mode
  * is "keep waiting" — the file may be missing, mid-write, or being rewritten.
  */
-export declare function readHandoff(filePath: string): HandoffFile | null;
+export declare function readHandoff(filePath: string, handoffsDir: string): HandoffFile | null;
 /**
  * Polls for a valid handoff file. Resolves once `readHandoff` accepts the
  * file's contents. Used to detect when the agent has finished its work so the
@@ -63,7 +96,7 @@ export declare function readHandoff(filePath: string): HandoffFile | null;
  *
  * Rejects with the abort reason when `options.signal` is aborted.
  */
-export declare function waitForValidHandoff(handoffFilePath: string, options?: {
+export declare function waitForValidHandoff(handoffFilePath: string, handoffsDir: string, options?: {
     intervalMs?: number;
     signal?: AbortSignal;
 }): Promise<void>;