@crewhaus/tool-proc 0.7.0 → 0.8.0

package/dist/spawn.js

@@ -1,57 +1,75 @@
-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;
+import { constants } from "node:os";
+import { spawnBounded } from "@crewhaus/tool-safety/streams";
+/** No UTF-16 code unit takes more than three bytes of UTF-8. */
+const BYTES_PER_CHAR = 3;
+const utf8Bytes = (text) => Buffer.byteLength(text, "utf8");
+/** `text` cut to at most `chars` UTF-16 units from the front, never mid-pair. */
+function headChars(text, chars) {
+    if (text.length <= chars)
+        return text;
+    const cut = text.slice(0, chars);
+    const last = cut.charCodeAt(cut.length - 1);
+    return last >= 0xd800 && last <= 0xdbff ? cut.slice(0, -1) : cut;
+}
+/** `text` cut to at most `chars` UTF-16 units from the end, never mid-pair. */
+function tailChars(text, chars) {
+    if (chars <= 0)
+        return "";
+    if (text.length <= chars)
+        return text;
+    const cut = text.slice(text.length - chars);
+    const first = cut.charCodeAt(0);
+    return first >= 0xdc00 && first <= 0xdfff ? cut.slice(1) : cut;
+}
 /**
- * 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.)
+ * One stream, capped to `maxChars`: its head and its tail — a command's head
+ * says what it started doing, its tail how it ended — with a marker stating
+ * exactly how many BYTES were dropped between them. Bytes, because the part
+ * past the byte budget was counted as it streamed past and never decoded.
  */
-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 } : {}),
-        });
+function capStream(head, tail, truncated, omittedBytes, maxChars) {
+    const headRoom = Math.floor(maxChars / 2);
+    const tailRoom = maxChars - headRoom;
+    if (!truncated) {
+        if (head.length <= maxChars)
+            return { text: head, truncated: false };
+        const h = headChars(head, headRoom);
+        const t = tailChars(head, tailRoom);
+        const dropped = utf8Bytes(head) - utf8Bytes(h) - utf8Bytes(t);
+        return { text: `${h}\n...[${dropped} bytes dropped]...\n${t}`, truncated: true };
+    }
+    const h = headChars(head, headRoom);
+    const whole = tail ?? "";
+    const t = tailChars(whole, tailRoom);
+    const dropped = omittedBytes + (utf8Bytes(head) - utf8Bytes(h)) + (utf8Bytes(whole) - utf8Bytes(t));
+    return { text: `${h}\n...[${dropped} bytes dropped]...\n${t}`, truncated: true };
+}
+/** The exit status a shell would report: 128 + the signal's number for a signalled child. */
+function exitStatus(r) {
+    if (r.exitCode !== null)
+        return r.exitCode;
+    if (r.signal !== null) {
+        const n = constants.signals[r.signal];
+        if (n !== undefined)
+            return 128 + n;
     }
-    catch (err) {
+    return -1;
+}
+export async function runOnce(argv, options) {
+    const max = Math.max(0, options.maxOutputChars);
+    const tailRoom = max - Math.floor(max / 2);
+    const r = await spawnBounded({
+        cmd: argv,
+        cwd: options.cwd,
+        env: options.env,
+        ...(options.stdin !== undefined ? { stdin: options.stdin } : {}),
+        timeoutMs: options.timeoutMs,
+        maxStdoutBytes: max * BYTES_PER_CHAR,
+        maxStderrBytes: max * BYTES_PER_CHAR,
+        tailBytes: tailRoom * BYTES_PER_CHAR,
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+    });
+    if (r.spawnError !== undefined) {
         return {
             argv,
             exitCode: -1,
@@ -60,78 +78,24 @@ export async function runOnce(argv, options) {
             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 } : {}),
+            durationMs: r.durationMs,
+            spawnError: r.spawnError,
         };
     }
-    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);
-    }
+    const out = capStream(r.stdout, r.stdoutTail, r.stdoutTruncated, r.stdoutOmittedBytes, max);
+    const err = capStream(r.stderr, r.stderrTail, r.stderrTruncated, r.stderrOmittedBytes, max);
+    return {
+        argv,
+        exitCode: r.abandoned ? -1 : exitStatus(r),
+        stdout: out.text,
+        stderr: err.text,
+        stdoutTruncated: out.truncated,
+        stderrTruncated: err.truncated,
+        timedOut: r.timedOut || r.abandoned,
+        durationMs: r.durationMs,
+        ...(r.abandoned ? { abandoned: true } : {}),
+        ...(r.outputComplete ? {} : { outputIncomplete: true }),
+    };
 }
 /** A deadline-aware sleep: resolves early (and reports it) when aborted. */
 export function sleep(ms, signal) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/tool-proc",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Deterministic process tools: background processes, log tailing, port and file waits, and retry with backoff",
   "main": "dist/index.js",
@@ -8,16 +8,18 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./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",
+    "@crewhaus/errors": "0.8.0",
+    "@crewhaus/tool-builder": "0.8.0",
+    "@crewhaus/tool-catalog": "0.8.0",
+    "@crewhaus/tool-safety": "0.8.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
@@ -41,5 +43,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"],
+  "engines": {
+    "bun": ">=1.3.14"
+  }
 }