@crewhaus/tool-proc 0.7.0

package/dist/safe-path.js

@@ -0,0 +1,165 @@
+import { existsSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
+import * as path from "node:path";
+/**
+ * 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
+ * only sound once the symlinks are out of the way.
+ */
+export function isInsideRoot(candidate, root) {
+    return candidate === root || candidate.startsWith(`${root}${path.sep}`);
+}
+/**
+ * True when the NAME exists, whether or not it leads anywhere.
+ *
+ * `existsSync` follows symlinks, so it answers false for a link whose target
+ * is missing — and a missing target is exactly the case that matters here: a
+ * dangling link is still a door. A walk that probes with it strides straight
+ * past the link, treats it as a plain missing leaf, pushes the name onto the
+ * tail and re-appends it to the realpath'd parent, so containment is decided
+ * on a path the link does not actually lead to. Probing with `lstat` — a
+ * dangling link is a NAME that exists — keeps that name in the part of the
+ * path that gets RESOLVED rather than in the "does not exist yet" tail that
+ * is appended to the root verbatim.
+ */
+function nameExists(p) {
+    try {
+        lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where `target` would actually land, with every symlink on the way already
+ * followed — including one whose own target does not exist yet.
+ *
+ * `realpathSync` gives up with ENOENT on a dangling link, which would leave
+ * that link unresolved and let it stand in for a plain missing file. So the
+ * deepest ancestor that exists as a name is resolved, a dangling one is
+ * followed a hop by hand, and the components that do not exist are appended.
+ * The result is the path an `open` would reach, which is the only path worth
+ * checking containment against.
+ *
+ * Throws if the chain cannot be followed at all; `resolveSafe`'s catch turns
+ * that into a refusal, so an unresolvable path fails closed.
+ */
+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;
+    }
+    let probeReal;
+    try {
+        probeReal = realpathSync(probe);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        // The name is there but `realpath` cannot finish it: a symlink with a
+        // missing target. `readlinkSync` throws EINVAL on anything else, which
+        // fails closed. Recursing (rather than returning the raw target) is what
+        // resolves an absolute target such as /var/folders/... to its real
+        // /private/var/... form, so a legitimate in-workspace dangling link is
+        // not wrongly refused.
+        const link = readlinkSync(probe);
+        // A RELATIVE target resolves against the directory that actually CONTAINS
+        // the link, which is not the link's lexical parent when that parent is
+        // itself reached through a symlink. `<root>/dirlink/x -> ../y` with
+        // `dirlink` pointing out of the root lands at `<elsewhere>/y`, but
+        // measured from the lexical parent it reads as `<root>/y` and would be
+        // admitted; the mirror case wrongly refuses an in-root link. So the
+        // parent is made real first. An absolute target ignores the base.
+        const base = realpathSync(path.dirname(probe));
+        probeReal = resolveLocation(path.resolve(base, link), depth + 1);
+    }
+    return tail.length > 0 ? path.join(probeReal, ...tail) : probeReal;
+}
+/**
+ * Re-check, at the moment of use, that a path resolved earlier still lives
+ * inside the root.
+ *
+ * `resolveSafe` can only resolve the symlinks that exist when it is called.
+ * A path that does not exist at all is admitted on the strength of its
+ * parent, and a link planted or swapped AFTER that call was never seen. A
+ * tool that polls a path for seconds or minutes — `WaitForFile` does exactly
+ * that — would happily report on the target once somebody creates it outside
+ * the root, so every poll asks again.
+ *
+ * (An outward DANGLING link is refused up front now, because `resolveSafe`
+ * follows it by hand rather than mistaking it for a missing file. This
+ * remains the guard for everything that only becomes a symlink later.)
+ *
+ * Returns `"absent"` when nothing is there yet (which is not an escape — it
+ * is the condition `WaitForFile` may be waiting for), `"inside"` when the
+ * real path is contained, and `"escaped"` when it is not.
+ */
+export function recheckContainment(target, root = process.cwd()) {
+    let rootReal;
+    try {
+        rootReal = realpathSync(path.resolve(root));
+    }
+    catch {
+        return "escaped";
+    }
+    let real;
+    try {
+        real = realpathSync(target);
+    }
+    catch {
+        // Nothing (or a dangling link) is there: there is no target to escape
+        // to yet, and the caller reads this as "absent".
+        return "absent";
+    }
+    return isInsideRoot(real, rootReal) ? "inside" : "escaped";
+}
+export function resolveSafe(toolName, rel, root = process.cwd()) {
+    const refusal = (why) => ({
+        ok: false,
+        message: `[${toolName} error] refused path "${rel}": ${why}. Paths must stay inside the workspace root.`,
+    });
+    const rootResolved = path.resolve(root);
+    const abs = path.resolve(rootResolved, rel);
+    if (!isInsideRoot(abs, rootResolved)) {
+        return refusal("it resolves outside the workspace root");
+    }
+    try {
+        const rootReal = realpathSync(rootResolved);
+        // The leaf may not exist yet (a wait can watch for a file's creation),
+        // so `resolveLocation` walks up to the deepest ancestor that exists as a
+        // NAME and re-appends the tail. "As a name" rather than "exists": a
+        // symlink whose target is missing is still followed by whatever opens
+        // this path later, so it is resolved here too.
+        const real = resolveLocation(abs);
+        if (!isInsideRoot(real, rootReal)) {
+            return refusal("a symlink on it leads outside the workspace root");
+        }
+        return { ok: true, path: real };
+    }
+    catch {
+        return refusal("it could not be resolved");
+    }
+}
+/**
+ * Containment for a directory that must already exist (a command's cwd).
+ *
+ * `existsSync` is the right probe HERE, unlike in the walk above: a cwd has
+ * to be a directory the OS can actually chdir into, so a name that leads
+ * nowhere is useless and following the link is exactly what is wanted.
+ */
+export function resolveSafeDir(toolName, rel, root) {
+    const resolved = resolveSafe(toolName, rel, root);
+    if (!resolved.ok)
+        return resolved;
+    if (!existsSync(resolved.path)) {
+        return { ok: false, message: `[${toolName} error] directory "${rel}" does not exist.` };
+    }
+    return resolved;
+}

package/dist/spawn.d.ts

@@ -0,0 +1,28 @@
+export type RunOutcome = {
+    readonly argv: readonly string[];
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly stdoutTruncated: boolean;
+    readonly stderrTruncated: boolean;
+    readonly timedOut: boolean;
+    readonly durationMs: number;
+    /** Set when the command could not be started at all (e.g. no such file). */
+    readonly spawnError?: string;
+    /**
+     * Set when the child outlived even the SIGKILL grace and was left behind:
+     * the result is what had been captured by then, and `exitCode` is unknown.
+     */
+    readonly abandoned?: boolean;
+};
+export type RunOptions = {
+    readonly cwd: string;
+    readonly env: Record<string, string>;
+    readonly stdin?: string;
+    readonly timeoutMs: number;
+    readonly maxOutputChars: number;
+    readonly signal?: AbortSignal;
+};
+export declare function runOnce(argv: readonly string[], options: RunOptions): Promise<RunOutcome>;
+/** A deadline-aware sleep: resolves early (and reports it) when aborted. */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/spawn.js

@@ -0,0 +1,156 @@
+import { capText } from "./lib/format";
+/**
+ * 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.
+ *   - both streams are capped, so one chatty command cannot fill a context
+ *     window.
+ */
+/** Grace between the deadline's SIGTERM and the SIGKILL that follows it. */
+const KILL_GRACE_MS = 2_000;
+/**
+ * A process that forks a grandchild keeps the pipe's write end open after
+ * the child itself is gone, so reading to EOF can outlive the process. Give
+ * each stream a bounded drain window and move on with what arrived.
+ */
+const DRAIN_GRACE_MS = 500;
+/**
+ * After the SIGKILL, how long to keep waiting for the child to be reaped
+ * before returning without it.
+ *
+ * SIGKILL cannot be caught, but it cannot interrupt a process wedged in an
+ * uninterruptible kernel wait either — a stalled NFS read, a wayward driver.
+ * `proc.exited` then never resolves, and every other bound in this file is
+ * downstream of that await, so the whole call hangs with no deadline left to
+ * save it. This is the last bound: past it the tool reports what it has and
+ * lets go. (There is no portable way to put a process into that state, so
+ * this is the one guarantee here with no test behind it.)
+ */
+const REAP_GRACE_MS = 1_000;
+export async function runOnce(argv, options) {
+    const started = performance.now();
+    const elapsed = () => Math.round(performance.now() - started);
+    let proc;
+    try {
+        proc = Bun.spawn([...argv], {
+            cwd: options.cwd,
+            env: options.env,
+            stdin: options.stdin === undefined ? "ignore" : new TextEncoder().encode(options.stdin),
+            stdout: "pipe",
+            stderr: "pipe",
+            ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        });
+    }
+    catch (err) {
+        return {
+            argv,
+            exitCode: -1,
+            stdout: "",
+            stderr: "",
+            stdoutTruncated: false,
+            stderrTruncated: false,
+            timedOut: false,
+            durationMs: elapsed(),
+            spawnError: err instanceof Error ? err.message : String(err),
+        };
+    }
+    let timedOut = false;
+    let reapGiveUp;
+    const term = setTimeout(() => {
+        timedOut = true;
+        try {
+            proc.kill("SIGTERM");
+        }
+        catch {
+            // Already gone between the timer firing and the signal.
+        }
+    }, options.timeoutMs);
+    const hardKill = setTimeout(() => {
+        try {
+            proc.kill("SIGKILL");
+        }
+        catch {
+            // Already gone.
+        }
+    }, options.timeoutMs + KILL_GRACE_MS);
+    try {
+        // The spread options above widen Bun's stdio inference, so name the
+        // piped shape explicitly rather than let the union leak outward.
+        // `.catch` is attached HERE, not after the race: the loser of the race
+        // below stays pending, and a stream torn down with the killed process
+        // would otherwise reject with nobody listening — an unhandled rejection
+        // that takes down the harness rather than the command that caused it.
+        const stdoutText = new Response(proc.stdout)
+            .text()
+            .catch(() => "");
+        const stderrText = new Response(proc.stderr)
+            .text()
+            .catch(() => "");
+        const abandonedMarker = Symbol("abandoned");
+        const reaped = await Promise.race([
+            proc.exited,
+            new Promise((resolve) => {
+                reapGiveUp = setTimeout(() => resolve(abandonedMarker), options.timeoutMs + KILL_GRACE_MS + REAP_GRACE_MS);
+            }),
+        ]);
+        const abandoned = reaped === abandonedMarker;
+        const exitCode = abandoned ? -1 : reaped;
+        const drainFallback = () => new Promise((resolve) => setTimeout(() => resolve(""), DRAIN_GRACE_MS));
+        const [rawOut, rawErr] = await Promise.all([
+            Promise.race([stdoutText, drainFallback()]),
+            Promise.race([stderrText, drainFallback()]),
+        ]);
+        const out = capText(rawOut, options.maxOutputChars);
+        const err = capText(rawErr, options.maxOutputChars);
+        return {
+            argv,
+            exitCode,
+            stdout: out.text,
+            stderr: err.text,
+            stdoutTruncated: out.truncated,
+            stderrTruncated: err.truncated,
+            timedOut: timedOut || abandoned,
+            durationMs: elapsed(),
+            ...(abandoned ? { abandoned: true } : {}),
+        };
+    }
+    finally {
+        clearTimeout(term);
+        clearTimeout(hardKill);
+        // Unconditional: left running, this one would hold the event loop open
+        // for the whole timeout on every command that finished in a millisecond.
+        if (reapGiveUp !== undefined)
+            clearTimeout(reapGiveUp);
+    }
+}
+/** A deadline-aware sleep: resolves early (and reports it) when aborted. */
+export function sleep(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    // An ALREADY-aborted signal never fires `abort` again, so without this an
+    // abort that landed a moment before the call would still cost the full
+    // sleep — the one wait in the package that could outlive its own deadline.
+    if (signal?.aborted === true)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            resolve();
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@crewhaus/tool-proc",
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Deterministic process tools: background processes, log tailing, port and file waits, and retry with backoff",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.7.0",
+    "@crewhaus/tool-builder": "0.7.0",
+    "@crewhaus/tool-catalog": "0.7.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@crewhaus/tool-executor": "workspace:*"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-proc"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-proc#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+}