@crewhaus/tool-proc 0.7.0 → 0.8.1

package/dist/lib/format.js

@@ -3,6 +3,7 @@
  * reads the filesystem or looks at a clock, so the behaviour that these
  * back can be unit-tested without a world.
  */
+import { compileUserRegex } from "@crewhaus/tool-safety/regex";
 /**
  * Cap a captured stream to a character budget, keeping BOTH ends.
  *
@@ -37,88 +38,37 @@ export function formatArgv(argv) {
 /**
  * Compile a caller-supplied regular expression, refusing the shapes behind
  * catastrophic backtracking. The pattern reaches us from a model, and a
- * waiting tool applies it repeatedly to a growing buffer, so an exponential
- * pattern would pin a core for the whole deadline.
+ * waiting tool applies it repeatedly to a growing buffer.
+ *
+ * The screen is @crewhaus/tool-safety's `compileUserRegex`, the one every
+ * tool shares (C079). 0.7.0 kept a scanner here that counted only `*` and
+ * `+` inside a group, so `(\w{1,})*$`, `(\w{1,64})*$` and `(\w\w?)*$`
+ * passed it and JavaScriptCore then gave up on them — a false "no match"
+ * after pinning the event loop. The shared screen models `{n,m}` and `?`
+ * too, accepts a repetition only when each pass ends in exactly one place,
+ * and is fuzzed; it also admits safe alternations the old scanner refused
+ * wholesale, such as `(a|b)*`. WaitForOutput still runs the match in the
+ * regex worker under a deadline: the screen is the second layer, not the
+ * first.
  */
 export function compileSafePattern(source, flags) {
-    if (source.length > 1_000) {
-        return { ok: false, message: `pattern is ${source.length} characters, over the 1000 limit` };
-    }
-    const risk = backtrackingRisk(source);
-    if (risk === "nested-quantifier") {
-        return {
-            ok: false,
-            message: "pattern nests one quantifier inside another, which can backtrack exponentially",
-        };
-    }
-    if (risk === "quantified-alternation") {
-        return {
-            ok: false,
-            message: "pattern quantifies a group containing an alternation, e.g. (a|a)*, which can backtrack exponentially — quantify a character class instead",
-        };
-    }
-    try {
-        return { ok: true, regex: new RegExp(source, flags) };
-    }
-    catch (err) {
-        return { ok: false, message: `invalid regex: ${err.message}` };
-    }
-}
-function backtrackingRisk(source) {
-    let depth = 0;
-    let nested = false;
-    let quantifiedAlternation = false;
-    const quantifiedAt = [];
-    const alternationAt = [];
-    for (let i = 0; i < source.length; i++) {
-        const ch = source[i];
-        if (ch === "\\") {
-            i++;
-            continue;
-        }
-        if (ch === "[") {
-            while (i < source.length && source[i] !== "]") {
-                if (source[i] === "\\")
-                    i++;
-                i++;
-            }
-            continue;
-        }
-        if (ch === "(") {
-            depth++;
-            quantifiedAt[depth] = false;
-            alternationAt[depth] = false;
-            continue;
-        }
-        if (ch === "|") {
-            if (depth > 0)
-                alternationAt[depth] = true;
-            continue;
-        }
-        if (ch === ")") {
-            const next = source[i + 1];
-            if (next === "*" || next === "+" || next === "{" || next === "?") {
-                // This group is itself quantified. `?` cannot repeat, so it only
-                // carries an inner quantifier outward; `*`, `+` and `{n,}` repeat,
-                // which is what turns an overlapping alternation catastrophic.
-                if (quantifiedAt[depth] === true && next !== "?")
-                    nested = true;
-                if (alternationAt[depth] === true && next !== "?")
-                    quantifiedAlternation = true;
-                if (depth > 1)
-                    quantifiedAt[depth - 1] = true;
-            }
-            depth = Math.max(0, depth - 1);
-            continue;
-        }
-        if (ch === "*" || ch === "+") {
-            if (depth > 0)
-                quantifiedAt[depth] = true;
-        }
+    const compiled = compileUserRegex(source, flags);
+    if (compiled.ok)
+        return compiled;
+    switch (compiled.code) {
+        case "nested-quantifier":
+            return {
+                ok: false,
+                message: `pattern nests one quantifier inside another, which can backtrack exponentially: ${compiled.reason}`,
+            };
+        case "overlapping-alternation":
+            return {
+                ok: false,
+                message: `pattern repeats an alternation whose branches can match the same text, e.g. (a|a)*, which can backtrack exponentially: ${compiled.reason}`,
+            };
+        case "invalid-syntax":
+            return { ok: false, message: `invalid regex: ${compiled.reason}` };
+        default:
+            return { ok: false, message: compiled.reason };
     }
-    if (nested)
-        return "nested-quantifier";
-    if (quantifiedAlternation)
-        return "quantified-alternation";
-    return "none";
 }

package/dist/lib/which.d.ts

@@ -0,0 +1,17 @@
+/** The platform CommandExists resolves for. */
+export declare function hostPlatform(): NodeJS.Platform;
+/** Test seam: pretend to be another platform; `undefined` restores the real one. */
+export declare function _setPlatform(platform: NodeJS.Platform | undefined): void;
+/** Windows' default when PATHEXT is unset. */
+export declare const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+export type PathSearch = {
+    /** The first match, or null. */
+    readonly path: string | null;
+    /** How many PATH entries were searched. */
+    readonly searchedDirs: number;
+};
+export declare function searchPath(name: string, options: {
+    readonly pathValue: string;
+    readonly platform: NodeJS.Platform;
+    readonly pathext?: string | undefined;
+}): PathSearch;

package/dist/lib/which.js

@@ -0,0 +1,80 @@
+/**
+ * Where a bare program name resolves on PATH — the question CommandExists
+ * answers — by the platform's own rule (C125).
+ *
+ * POSIX: each PATH directory in order, the first regular file with the name
+ * that is executable. Windows: an installed program is `git.exe` or
+ * `npm.cmd`, and the shell and Bun.spawn both find it by its bare name
+ * through PATHEXT. 0.7.0 probed only the bare name, so on Windows every
+ * program was "not found" while RunCommand could run it. Here, on win32,
+ * PATH is split on `;` (a quoted entry unquoted), and each directory is
+ * tried in order for the name as given when its extension is already one of
+ * PATHEXT's, then for the name plus each PATHEXT extension in PATHEXT's
+ * order. Existence and being a regular file is enough there: Windows has no
+ * execute bit to check.
+ *
+ * The platform is a parameter, read through `hostPlatform()` (with a test
+ * seam) so the Windows rule is exercised on a Linux or macOS CI runner.
+ */
+import { accessSync, constants as fsConstants, statSync } from "node:fs";
+import * as path from "node:path";
+let platformOverride;
+/** The platform CommandExists resolves for. */
+export function hostPlatform() {
+    return platformOverride ?? process.platform;
+}
+/** Test seam: pretend to be another platform; `undefined` restores the real one. */
+export function _setPlatform(platform) {
+    platformOverride = platform;
+}
+/** Windows' default when PATHEXT is unset. */
+export const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+export function searchPath(name, options) {
+    const windows = options.platform === "win32";
+    const dirs = options.pathValue
+        .split(windows ? ";" : ":")
+        .map((d) => (windows ? d.trim().replace(/^"(.*)"$/, "$1") : d))
+        .filter((d) => d !== "");
+    const candidates = windows ? windowsCandidates(name, options.pathext) : [name];
+    for (const dir of dirs) {
+        for (const candidate of candidates) {
+            // The HOST join: on a real Windows host this is path.win32 already.
+            const full = path.join(dir, candidate);
+            if (isProgram(full, windows))
+                return { path: full, searchedDirs: dirs.length };
+        }
+    }
+    return { path: null, searchedDirs: dirs.length };
+}
+/** The spellings Windows would try for `name`, in order. */
+function windowsCandidates(name, pathext) {
+    const exts = (pathext === undefined || pathext.trim() === "" ? DEFAULT_PATHEXT : pathext)
+        .split(";")
+        .map((e) => e.trim())
+        .filter((e) => e.startsWith(".") && e.length > 1);
+    const lowered = exts.map((e) => e.toLowerCase());
+    const out = [];
+    const own = path.extname(name).toLowerCase();
+    if (own !== "" && lowered.includes(own))
+        out.push(name);
+    for (const [i, ext] of exts.entries()) {
+        // Both spellings: Windows matches case-insensitively, a case-sensitive
+        // filesystem (a test on Linux, a WSL mount) does not.
+        out.push(`${name}${lowered[i]}`);
+        if (ext !== lowered[i])
+            out.push(`${name}${ext}`);
+    }
+    return [...new Set(out)];
+}
+function isProgram(full, windows) {
+    try {
+        if (!statSync(full).isFile())
+            return false;
+        if (!windows)
+            accessSync(full, fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/registry.d.ts

@@ -30,6 +30,16 @@ export type BgProc = {
     stdoutReturned: number;
     stderrReturned: number;
     status: BgStatus;
+    /**
+     * Each pipe has reached its end, so `stdout` (or `stderr`) holds all the
+     * process will ever print there. This can lag `status`: the exit and a
+     * pipe's last bytes reach the parent as separate events, and a process it
+     * started that shares a pipe can keep it open after it is gone.
+     */
+    stdoutEnded: boolean;
+    stderrEnded: boolean;
+    /** Both pipes have reached their end. */
+    outputEnded: boolean;
     exitCode: number | null;
     readonly startedAt: number;
     exitedAt: number | null;
@@ -55,6 +65,35 @@ export declare function getProc(id: string): BgProc | undefined;
 export declare function listProcs(): BgProc[];
 export declare function reapProc(id: string): boolean;
 export declare function markKilled(bg: BgProc): void;
+/** The output a watch reads: one stream, or both. */
+export type WatchedStream = "stdout" | "stderr" | "both";
+/**
+ * Whether a process has finished as far as a watch of `stream` goes: the
+ * next look at that output is the last one worth taking.
+ *
+ * An exited process has finished once the watched pipe has ended too. The
+ * exit can reach the parent before the line printed just ahead of it, and a
+ * process it started can still hold the pipe and print. Only the watched
+ * pipe counts: one that holds just the other pipe cannot print on this one.
+ *
+ * A stopped one has finished once its own exit has been seen (`exitCode` is
+ * set then, to a number even for a death by signal), whatever its pipes are
+ * doing. Until then it is still running, whatever ProcessStop asked of it.
+ * ProcessStop signals the process alone, so one it started (a script running
+ * a server without `exec`) can hold the pipes for as long as it runs, and a
+ * wait on them would run to its deadline. The cost is the one 0.7.0 had: a
+ * line a stopped process prints as it goes, such as a SIGTERM handler's last
+ * words, can reach the parent after its exit and be missed. Stopping the
+ * whole process group would let the pipes decide here too.
+ */
+export declare function watchFinished(bg: Pick<BgProc, "status" | "exitCode" | "stdoutEnded" | "stderrEnded" | "outputEnded">, stream: WatchedStream): boolean;
 /** Test-only: kill every live process and empty the table, including the id
  *  counter, so each test file starts from the same state. */
 export declare function __resetRegistryForTest(): void;
+/**
+ * Test-only: {@link __resetRegistryForTest}, then wait (at most `timeoutMs`)
+ * until every process it knew of has exited. A test removes its workspace
+ * after this, and on Windows a directory that is a live process's cwd cannot
+ * be removed (EBUSY), while a kill there returns before the process is gone.
+ */
+export declare function __stopAllForTest(timeoutMs?: number): Promise<void>;

package/dist/registry.js

@@ -117,6 +117,9 @@ export function startBackground(argv, options) {
         stdoutReturned: 0,
         stderrReturned: 0,
         status: "running",
+        stdoutEnded: false,
+        stderrEnded: false,
+        outputEnded: false,
         exitCode: null,
         startedAt: Date.now(),
         exitedAt: null,
@@ -124,8 +127,16 @@ export function startBackground(argv, options) {
     };
     procs.set(id, bg);
     // Fire and forget: the tool returns while the process keeps running.
-    void pump(spawned.stdout, (t) => append(bg, "stdout", t));
-    void pump(spawned.stderr, (t) => append(bg, "stderr", t));
+    void Promise.all([
+        pump(spawned.stdout, (t) => append(bg, "stdout", t)).then(() => {
+            bg.stdoutEnded = true;
+        }),
+        pump(spawned.stderr, (t) => append(bg, "stderr", t)).then(() => {
+            bg.stderrEnded = true;
+        }),
+    ]).then(() => {
+        bg.outputEnded = true;
+    });
     void spawned.exited.then((code) => {
         if (bg.status === "running")
             bg.status = "exited";
@@ -155,6 +166,36 @@ export function markKilled(bg) {
         bg.exitedAt = Date.now();
     }
 }
+/**
+ * Whether a process has finished as far as a watch of `stream` goes: the
+ * next look at that output is the last one worth taking.
+ *
+ * An exited process has finished once the watched pipe has ended too. The
+ * exit can reach the parent before the line printed just ahead of it, and a
+ * process it started can still hold the pipe and print. Only the watched
+ * pipe counts: one that holds just the other pipe cannot print on this one.
+ *
+ * A stopped one has finished once its own exit has been seen (`exitCode` is
+ * set then, to a number even for a death by signal), whatever its pipes are
+ * doing. Until then it is still running, whatever ProcessStop asked of it.
+ * ProcessStop signals the process alone, so one it started (a script running
+ * a server without `exec`) can hold the pipes for as long as it runs, and a
+ * wait on them would run to its deadline. The cost is the one 0.7.0 had: a
+ * line a stopped process prints as it goes, such as a SIGTERM handler's last
+ * words, can reach the parent after its exit and be missed. Stopping the
+ * whole process group would let the pipes decide here too.
+ */
+export function watchFinished(bg, stream) {
+    if (bg.status === "running")
+        return false;
+    if (bg.status === "killed")
+        return bg.exitCode !== null;
+    if (stream === "stdout")
+        return bg.stdoutEnded;
+    if (stream === "stderr")
+        return bg.stderrEnded;
+    return bg.outputEnded;
+}
 /** Test-only: kill every live process and empty the table, including the id
  *  counter, so each test file starts from the same state. */
 export function __resetRegistryForTest() {
@@ -171,3 +212,26 @@ export function __resetRegistryForTest() {
     procs.clear();
     nextId = 1;
 }
+/**
+ * Test-only: {@link __resetRegistryForTest}, then wait (at most `timeoutMs`)
+ * until every process it knew of has exited. A test removes its workspace
+ * after this, and on Windows a directory that is a live process's cwd cannot
+ * be removed (EBUSY), while a kill there returns before the process is gone.
+ */
+export async function __stopAllForTest(timeoutMs = 5_000) {
+    const exits = [...procs.values()].map((bg) => bg.proc.exited);
+    __resetRegistryForTest();
+    let timer;
+    try {
+        await Promise.race([
+            Promise.all(exits),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}

package/dist/safe-path.d.ts

@@ -20,6 +20,17 @@ export type SafePath = {
     readonly ok: false;
     readonly message: string;
 };
+/**
+ * The longest path this resolves, in UTF-16 code units; a longer one is
+ * refused before it is walked. Nothing that long can be opened or created:
+ * PATH_MAX is 1,024 bytes on macOS and 4,096 on Linux, Windows stops at
+ * 32,767 UTF-16 units, and a path's UTF-8 form is never shorter than its
+ * UTF-16 one. The limit is twice that because the part of a path that exists
+ * is itself under PATH_MAX, so the part that does not is over PATH_MAX on its
+ * own: no spelling of the place reaches it, not even one through a symlink
+ * that shortens the part that exists.
+ */
+export declare const MAX_PATH_CHARS: number;
 /**
  * Is `candidate` the root itself, or something beneath it? Both arguments
  * must already be REAL paths — this is a string containment test, and it is

package/dist/safe-path.js

@@ -1,5 +1,24 @@
 import { existsSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
 import * as path from "node:path";
+/**
+ * The longest path this resolves, in UTF-16 code units; a longer one is
+ * refused before it is walked. Nothing that long can be opened or created:
+ * PATH_MAX is 1,024 bytes on macOS and 4,096 on Linux, Windows stops at
+ * 32,767 UTF-16 units, and a path's UTF-8 form is never shorter than its
+ * UTF-16 one. The limit is twice that because the part of a path that exists
+ * is itself under PATH_MAX, so the part that does not is over PATH_MAX on its
+ * own: no spelling of the place reaches it, not even one through a symlink
+ * that shortens the part that exists.
+ */
+export const MAX_PATH_CHARS = 2 * (process.platform === "darwin" ? 1_024 : process.platform === "win32" ? 32_767 : 4_096);
+/** A path as a refusal quotes it: whole, unless it is past {@link MAX_PATH_CHARS}. */
+function shownPath(given) {
+    return given.length > MAX_PATH_CHARS ? `${given.slice(0, 64)}…` : given;
+}
+/** Why a path past {@link MAX_PATH_CHARS} is refused: its length and the limit. */
+function tooLong(abs) {
+    return `it is ${abs.length} characters once resolved, over the ${MAX_PATH_CHARS}-character limit: no path that long can be opened or created`;
+}
 /**
  * Is `candidate` the root itself, or something beneath it? Both arguments
  * must already be REAL paths — this is a string containment test, and it is
@@ -47,15 +66,7 @@ function nameExists(p) {
 function resolveLocation(target, depth = 0) {
     if (depth > 40)
         throw new Error(`symlink chain at "${target}" is too long to resolve`);
-    let probe = target;
-    const tail = [];
-    while (!nameExists(probe)) {
-        tail.unshift(path.basename(probe));
-        const parent = path.dirname(probe);
-        if (parent === probe)
-            break; // reached the filesystem root
-        probe = parent;
-    }
+    const { probe, tail } = deepestName(target);
     let probeReal;
     try {
         probeReal = realpathSync(probe);
@@ -80,7 +91,41 @@ function resolveLocation(target, depth = 0) {
         const base = realpathSync(path.dirname(probe));
         probeReal = resolveLocation(path.resolve(base, link), depth + 1);
     }
-    return tail.length > 0 ? path.join(probeReal, ...tail) : probeReal;
+    // One string, not one argument per name: Bun's `path.join` keeps only
+    // (argument count mod 65,536) of its arguments.
+    return tail.length > 0 ? path.join(probeReal, tail) : probeReal;
+}
+/**
+ * `target`, an absolute path, split where its deepest prefix that exists as
+ * a NAME ends: that prefix, and the names below it, which do not exist, as
+ * one string ("" when `target` itself exists). This is `path.dirname` and
+ * `path.basename` worked by index on `target` itself: handing them each
+ * shorter prefix in turn copied the rest of the path once per missing name,
+ * the square of a count the caller picks.
+ */
+function deepestName(target) {
+    const top = path.parse(target).root.length;
+    const isSep = (i) => target[i] === "/" || target[i] === path.sep;
+    let probe = target;
+    let start = target.length;
+    let stop = -1;
+    while (!nameExists(probe)) {
+        // `path.basename(probe)` is `target.slice(start, end)`, and
+        // `path.dirname(probe)` is `target.slice(0, up)`.
+        let end = probe.length;
+        while (end > top && isSep(end - 1))
+            end--;
+        if (stop < 0)
+            stop = end;
+        start = end;
+        while (start > top && !isSep(start - 1))
+            start--;
+        const up = start > top ? start - 1 : top;
+        if (up === probe.length)
+            break; // reached the filesystem root
+        probe = target.slice(0, up);
+    }
+    return { probe, tail: stop < 0 ? "" : target.slice(start, stop) };
 }
 /**
  * Re-check, at the moment of use, that a path resolved earlier still lives
@@ -130,6 +175,13 @@ export function resolveSafe(toolName, rel, root = process.cwd()) {
     if (!isInsideRoot(abs, rootResolved)) {
         return refusal("it resolves outside the workspace root");
     }
+    // Longer than any path can be: refused before the walk below reads it.
+    if (abs.length > MAX_PATH_CHARS) {
+        return {
+            ok: false,
+            message: `[${toolName} error] refused path "${shownPath(rel)}": ${tooLong(abs)}.`,
+        };
+    }
     try {
         const rootReal = realpathSync(rootResolved);
         // The leaf may not exist yet (a wait can watch for a file's creation),

package/dist/spawn.d.ts

@@ -1,3 +1,36 @@
+/**
+ * The one place this package starts a child process.
+ *
+ * Everything that runs a command — RunCommand, RunPipeline, Retry and the
+ * background family — goes through here so a single set of rules holds:
+ *
+ *   - argv is passed to the OS as an ARRAY. There is no shell anywhere in
+ *     this package, so a filename with a space or a `$(...)` in it is an
+ *     argument and never a command.
+ *   - stdin is `ignore` unless the caller supplied it, so a command that
+ *     reads stdin gets EOF immediately instead of hanging on a terminal
+ *     that is not there.
+ *   - every run has a deadline: SIGTERM on expiry, SIGKILL after a short
+ *     grace period for a child that ignores the first signal. The child
+ *     leads its own process group and the deadline (or an abort) signals the
+ *     whole group, so a `cmd &` it started cannot outlive the timeout.
+ *   - the child runs in a SESSION of its own (spawnBounded's detached spawn,
+ *     setsid), so it has no controlling terminal. That is deliberate, and a
+ *     change from 0.7.0: a model-run command cannot read the operator's
+ *     keystrokes from /dev/tty (the answers typed into the harness's own
+ *     approval prompt), cannot push input into that terminal (TIOCSTI), and
+ *     a `sudo`/`ssh`/`gpg` prompt fails at once instead of waiting on a
+ *     terminal the model cannot see. Bun has no "own process group but keep
+ *     the terminal" spawn, and the group is what makes the deadline real.
+ *     The background family (ProcessStart) keeps 0.7.0's spawn.
+ *   - both streams are capped AS THEY ARE READ (C078). The foreground run is
+ *     @crewhaus/tool-safety's `spawnBounded`: memory is bounded by the cap,
+ *     not by what the child prints, and the reader keeps draining past the
+ *     cap so a child never blocks on a full pipe.
+ *   - output a grandchild still holds open after the child exits is read for
+ *     a bounded grace, then reading stops and the stream is cancelled: the
+ *     result keeps what arrived and says `outputIncomplete`, never "".
+ */
 export type RunOutcome = {
     readonly argv: readonly string[];
     readonly exitCode: number;
@@ -14,6 +47,12 @@ export type RunOutcome = {
      * the result is what had been captured by then, and `exitCode` is unknown.
      */
     readonly abandoned?: boolean;
+    /**
+     * Set when reading stopped before a stream ended: the child exited but a
+     * process it started still held its output open past the drain grace. The
+     * text is what arrived by then — possibly all of it, possibly not.
+     */
+    readonly outputIncomplete?: boolean;
 };
 export type RunOptions = {
     readonly cwd: string;