@alchemy.run/node-utils 0.0.2 → 0.0.4

package/lib/foreground-child.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Run a child process in the foreground: proxy signals to it, forward stdio,
+ * bridge IPC, and exit with the child's code/signal. A watchdog process
+ * ensures the child is killed if the parent dies unexpectedly.
+ *
+ * Adapted from `foreground-child@4.0.3` (© Isaac Z. Schlueter et al.):
+ *   https://github.com/tapjs/foreground-child
+ * Licensed under the Blue Oak Model License 1.0.0:
+ *   https://blueoakcouncil.org/license/1.0.0
+ *
+ * The behavioral additions on top of upstream are:
+ *   1. Optional `stderrFilter` — upstream hardcodes `stdio = [0, 1, 2]`,
+ *      which makes intercepting child stderr impossible without forking.
+ *      When `stderrFilter` is provided, the child's stderr is piped,
+ *      line-buffered, and each line is passed through the filter
+ *      (return `false` to drop, `true` to forward).
+ *   2. Uses the in-tree {@link exitHook} instead of `signal-exit`, so this
+ *      package has no external runtime dependencies.
+ *
+ * Everything else — signal proxying, the watchdog, IPC bridging, exit-code
+ * forwarding — is preserved verbatim from upstream.
+ */
+import { type ChildProcess } from "node:child_process";
+type SyncCleanupResult = void | undefined | null | boolean | number | string | NodeJS.Signals;
+export type CleanupResult = SyncCleanupResult | Promise<SyncCleanupResult>;
+export interface ForegroundChildOptions {
+    /**
+     * Line-level filter for the child's stderr. Return `true` to forward the
+     * line to the parent's stderr, `false` to drop it. When omitted, the
+     * child's stderr is inherited directly (no buffering, no filtering).
+     */
+    stderrFilter?: (line: string) => boolean;
+    /**
+     * Called when the child closes. May return:
+     *   - `false` — suppress propagation of the child's exit
+     *   - `number` — override the parent's exit code
+     *   - `string` (a signal name) — kill the parent with that signal
+     *   - `void` / `undefined` — propagate the child's code/signal verbatim
+     * Async (Promise-returning) cleanup is supported.
+     */
+    cleanup?: (code: number | null, signal: NodeJS.Signals | null, extra: {
+        watchdogPid: number | undefined;
+    }) => CleanupResult;
+}
+/**
+ * Run `program` with `args` as a foreground child of the current process.
+ *
+ * Signals received by the parent are proxied to the child, the child's stdio
+ * is connected to the parent's (with optional stderr filtering via
+ * {@link ForegroundChildOptions.stderrFilter}), IPC messages are bridged in
+ * both directions, and the parent exits with the child's exit code or
+ * signal. A watchdog subprocess ensures the child is force-killed if the
+ * parent dies unexpectedly.
+ */
+export declare function foregroundChild(program: string, args: ReadonlyArray<string>, opts?: ForegroundChildOptions): ChildProcess;
+export {};
+//# sourceMappingURL=foreground-child.d.ts.map

package/lib/foreground-child.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foreground-child.d.ts","sourceRoot":"","sources":["../src/foreground-child.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,KAAK,YAAY,EAAS,MAAM,oBAAoB,CAAC;AAgF9D,KAAK,iBAAiB,GAClB,IAAI,GACJ,SAAS,GACT,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,MAAM,CAAC,OAAO,CAAC;AAEnB,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAE3E,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CACR,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,EAC7B,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,KACvC,aAAa,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,EAC3B,IAAI,GAAE,sBAA2B,GAChC,YAAY,CA6Fd"}

package/lib/foreground-child.js

@@ -0,0 +1,201 @@
+/**
+ * Run a child process in the foreground: proxy signals to it, forward stdio,
+ * bridge IPC, and exit with the child's code/signal. A watchdog process
+ * ensures the child is killed if the parent dies unexpectedly.
+ *
+ * Adapted from `foreground-child@4.0.3` (© Isaac Z. Schlueter et al.):
+ *   https://github.com/tapjs/foreground-child
+ * Licensed under the Blue Oak Model License 1.0.0:
+ *   https://blueoakcouncil.org/license/1.0.0
+ *
+ * The behavioral additions on top of upstream are:
+ *   1. Optional `stderrFilter` — upstream hardcodes `stdio = [0, 1, 2]`,
+ *      which makes intercepting child stderr impossible without forking.
+ *      When `stderrFilter` is provided, the child's stderr is piped,
+ *      line-buffered, and each line is passed through the filter
+ *      (return `false` to drop, `true` to forward).
+ *   2. Uses the in-tree {@link exitHook} instead of `signal-exit`, so this
+ *      package has no external runtime dependencies.
+ *
+ * Everything else — signal proxying, the watchdog, IPC bridging, exit-code
+ * forwarding — is preserved verbatim from upstream.
+ */
+import { spawn } from "node:child_process";
+import constants from "node:constants";
+import { exitHook } from "./exit-hook.js";
+const allSignals = Object.keys(constants).filter((k) => k.startsWith("SIG") && k !== "SIGPROF" && k !== "SIGKILL");
+function proxySignals(child) {
+    const listeners = new Map();
+    for (const sig of allSignals) {
+        const listener = () => {
+            try {
+                child.kill(sig);
+            }
+            catch (_) { }
+        };
+        try {
+            process.on(sig, listener);
+            listeners.set(sig, listener);
+        }
+        catch (_) { }
+    }
+    const unproxy = () => {
+        for (const [sig, listener] of listeners) {
+            process.removeListener(sig, listener);
+        }
+    };
+    child.on("exit", unproxy);
+    return unproxy;
+}
+const watchdogCode = String.raw `
+const pid = parseInt(process.argv[1], 10)
+process.title = 'node (foreground-child watchdog pid=' + pid + ')'
+if (!isNaN(pid)) {
+  let barked = false
+  const interval = setInterval(() => {}, 60000)
+  const bark = () => {
+    clearInterval(interval)
+    if (barked) return
+    barked = true
+    process.removeListener('SIGHUP', bark)
+    setTimeout(() => {
+      try {
+        process.kill(pid, 'SIGKILL')
+        setTimeout(() => process.exit(), 200)
+      } catch (_) {}
+    }, 500)
+  }
+  process.on('SIGHUP', bark)
+}
+`;
+function watchdog(child) {
+    let dogExited = false;
+    const dog = spawn(process.execPath, ["-e", watchdogCode, String(child.pid)], {
+        stdio: ["ignore", "ignore", "pipe"],
+    });
+    dog.on("exit", () => {
+        dogExited = true;
+    });
+    dog.stderr?.pipe(process.stderr, { end: false });
+    child.on("exit", () => {
+        if (!dogExited)
+            dog.kill("SIGKILL");
+    });
+    process.on("exit", () => {
+        if (!dogExited)
+            dog.kill("SIGKILL");
+    });
+    return dog;
+}
+function isPromise(o) {
+    return (!!o &&
+        typeof o === "object" &&
+        typeof o.then === "function");
+}
+/**
+ * Run `program` with `args` as a foreground child of the current process.
+ *
+ * Signals received by the parent are proxied to the child, the child's stdio
+ * is connected to the parent's (with optional stderr filtering via
+ * {@link ForegroundChildOptions.stderrFilter}), IPC messages are bridged in
+ * both directions, and the parent exits with the child's exit code or
+ * signal. A watchdog subprocess ensures the child is force-killed if the
+ * parent dies unexpectedly.
+ */
+export function foregroundChild(program, args, opts = {}) {
+    const { stderrFilter, cleanup = () => { } } = opts;
+    const stdio = stderrFilter
+        ? [0, 1, "pipe"]
+        : [0, 1, 2];
+    if (process.send)
+        stdio.push("ipc");
+    const child = spawn(program, args, { stdio });
+    if (stderrFilter && child.stderr) {
+        let buf = "";
+        child.stderr.on("data", (chunk) => {
+            buf += chunk.toString();
+            let nl;
+            while ((nl = buf.search(/\r?\n/)) !== -1) {
+                const eol = buf.startsWith("\r\n", nl) ? 2 : 1;
+                const line = buf.slice(0, nl + eol);
+                buf = buf.slice(nl + eol);
+                if (stderrFilter(line))
+                    process.stderr.write(line);
+            }
+        });
+        child.stderr.on("end", () => {
+            if (buf && stderrFilter(buf))
+                process.stderr.write(buf);
+        });
+    }
+    const childHangup = () => {
+        try {
+            child.kill("SIGHUP");
+        }
+        catch (_) {
+            child.kill("SIGTERM");
+        }
+    };
+    const removeOnExit = exitHook(childHangup);
+    proxySignals(child);
+    const dog = watchdog(child);
+    let done = false;
+    dog.on("close", (code, signal) => {
+        if (done)
+            return;
+        child.kill("SIGKILL");
+        throw new Error("foreground-child watchdog process died unexpectedly!", {
+            cause: {
+                pid: dog.pid,
+                code,
+                signal,
+                watchedProcess: { cmd: program, args, pid: child.pid },
+            },
+        });
+    });
+    child.on("close", async (code, signal) => {
+        if (done)
+            return;
+        done = true;
+        const result = cleanup(code, signal, { watchdogPid: dog.pid });
+        const res = isPromise(result) ? await result : result;
+        removeOnExit();
+        if (res === false)
+            return;
+        let finalCode = code;
+        let finalSignal = signal;
+        if (typeof res === "string") {
+            finalSignal = res;
+            finalCode = null;
+        }
+        else if (typeof res === "number") {
+            finalCode = res;
+            finalSignal = null;
+        }
+        if (finalSignal) {
+            setTimeout(() => { }, 2000);
+            try {
+                process.kill(process.pid, finalSignal);
+            }
+            catch (_) {
+                process.kill(process.pid, "SIGTERM");
+            }
+        }
+        else {
+            process.exit(finalCode ?? 0);
+        }
+    });
+    if (process.send) {
+        process.removeAllListeners("message");
+        child.on("message", (message, sendHandle) => {
+            process.send?.(message, sendHandle);
+        });
+        process.on("message", (message, sendHandle) => {
+            if (message === null)
+                return;
+            child.send(message, sendHandle);
+        });
+    }
+    return child;
+}
+//# sourceMappingURL=foreground-child.js.map

package/lib/foreground-child.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"foreground-child.js","sourceRoot":"","sources":["../src/foreground-child.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./exit-hook.ts";
+export * from "./foreground-child.ts";
 export * from "./ignore.ts";
 export * from "./lockfile-async.ts";
 export * from "./retry.ts";

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}

package/lib/index.js

@@ -1,4 +1,5 @@
 export * from "./exit-hook.js";
+export * from "./foreground-child.js";
 export * from "./ignore.js";
 export * from "./lockfile-async.js";
 export * from "./retry.js";

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alchemy.run/node-utils",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "author": "Sam Goodwin (sam@alchemy.run)",
   "repository": {
     "type": "git",
@@ -16,6 +16,26 @@
       "bun": "./src/index.ts",
       "types": "./lib/index.d.ts",
       "default": "./lib/index.js"
+    },
+    "./exit-hook": {
+      "bun": "./src/exit-hook.ts",
+      "types": "./lib/exit-hook.d.ts",
+      "default": "./lib/exit-hook.js"
+    },
+    "./ignore": {
+      "bun": "./src/ignore.ts",
+      "types": "./lib/ignore.d.ts",
+      "default": "./lib/ignore.js"
+    },
+    "./lockfile": {
+      "bun": "./src/lockfile-async.ts",
+      "types": "./lib/lockfile-async.d.ts",
+      "default": "./lib/lockfile-async.js"
+    },
+    "./retry": {
+      "bun": "./src/retry.ts",
+      "types": "./lib/retry.d.ts",
+      "default": "./lib/retry.js"
     }
   },
   "scripts": {

package/src/foreground-child.ts

@@ -0,0 +1,243 @@
+/**
+ * Run a child process in the foreground: proxy signals to it, forward stdio,
+ * bridge IPC, and exit with the child's code/signal. A watchdog process
+ * ensures the child is killed if the parent dies unexpectedly.
+ *
+ * Adapted from `foreground-child@4.0.3` (© Isaac Z. Schlueter et al.):
+ *   https://github.com/tapjs/foreground-child
+ * Licensed under the Blue Oak Model License 1.0.0:
+ *   https://blueoakcouncil.org/license/1.0.0
+ *
+ * The behavioral additions on top of upstream are:
+ *   1. Optional `stderrFilter` — upstream hardcodes `stdio = [0, 1, 2]`,
+ *      which makes intercepting child stderr impossible without forking.
+ *      When `stderrFilter` is provided, the child's stderr is piped,
+ *      line-buffered, and each line is passed through the filter
+ *      (return `false` to drop, `true` to forward).
+ *   2. Uses the in-tree {@link exitHook} instead of `signal-exit`, so this
+ *      package has no external runtime dependencies.
+ *
+ * Everything else — signal proxying, the watchdog, IPC bridging, exit-code
+ * forwarding — is preserved verbatim from upstream.
+ */
+import { type ChildProcess, spawn } from "node:child_process";
+import constants from "node:constants";
+import { exitHook } from "./exit-hook.ts";
+
+type Signal = NodeJS.Signals;
+
+const allSignals = Object.keys(constants).filter(
+  (k) => k.startsWith("SIG") && k !== "SIGPROF" && k !== "SIGKILL",
+) as Signal[];
+
+function proxySignals(child: ChildProcess): () => void {
+  const listeners = new Map<Signal, () => void>();
+  for (const sig of allSignals) {
+    const listener = (): void => {
+      try {
+        child.kill(sig);
+      } catch (_) {}
+    };
+    try {
+      process.on(sig, listener);
+      listeners.set(sig, listener);
+    } catch (_) {}
+  }
+  const unproxy = (): void => {
+    for (const [sig, listener] of listeners) {
+      process.removeListener(sig, listener);
+    }
+  };
+  child.on("exit", unproxy);
+  return unproxy;
+}
+
+const watchdogCode = String.raw`
+const pid = parseInt(process.argv[1], 10)
+process.title = 'node (foreground-child watchdog pid=' + pid + ')'
+if (!isNaN(pid)) {
+  let barked = false
+  const interval = setInterval(() => {}, 60000)
+  const bark = () => {
+    clearInterval(interval)
+    if (barked) return
+    barked = true
+    process.removeListener('SIGHUP', bark)
+    setTimeout(() => {
+      try {
+        process.kill(pid, 'SIGKILL')
+        setTimeout(() => process.exit(), 200)
+      } catch (_) {}
+    }, 500)
+  }
+  process.on('SIGHUP', bark)
+}
+`;
+
+function watchdog(child: ChildProcess): ChildProcess {
+  let dogExited = false;
+  const dog = spawn(process.execPath, ["-e", watchdogCode, String(child.pid)], {
+    stdio: ["ignore", "ignore", "pipe"],
+  });
+  dog.on("exit", () => {
+    dogExited = true;
+  });
+  dog.stderr?.pipe(process.stderr, { end: false });
+  child.on("exit", () => {
+    if (!dogExited) dog.kill("SIGKILL");
+  });
+  process.on("exit", () => {
+    if (!dogExited) dog.kill("SIGKILL");
+  });
+  return dog;
+}
+
+function isPromise<T>(o: unknown): o is Promise<T> {
+  return (
+    !!o &&
+    typeof o === "object" &&
+    typeof (o as { then?: unknown }).then === "function"
+  );
+}
+
+type SyncCleanupResult =
+  | void
+  | undefined
+  | null
+  | boolean
+  | number
+  | string
+  | NodeJS.Signals;
+
+export type CleanupResult = SyncCleanupResult | Promise<SyncCleanupResult>;
+
+export interface ForegroundChildOptions {
+  /**
+   * Line-level filter for the child's stderr. Return `true` to forward the
+   * line to the parent's stderr, `false` to drop it. When omitted, the
+   * child's stderr is inherited directly (no buffering, no filtering).
+   */
+  stderrFilter?: (line: string) => boolean;
+  /**
+   * Called when the child closes. May return:
+   *   - `false` — suppress propagation of the child's exit
+   *   - `number` — override the parent's exit code
+   *   - `string` (a signal name) — kill the parent with that signal
+   *   - `void` / `undefined` — propagate the child's code/signal verbatim
+   * Async (Promise-returning) cleanup is supported.
+   */
+  cleanup?: (
+    code: number | null,
+    signal: NodeJS.Signals | null,
+    extra: { watchdogPid: number | undefined },
+  ) => CleanupResult;
+}
+
+/**
+ * Run `program` with `args` as a foreground child of the current process.
+ *
+ * Signals received by the parent are proxied to the child, the child's stdio
+ * is connected to the parent's (with optional stderr filtering via
+ * {@link ForegroundChildOptions.stderrFilter}), IPC messages are bridged in
+ * both directions, and the parent exits with the child's exit code or
+ * signal. A watchdog subprocess ensures the child is force-killed if the
+ * parent dies unexpectedly.
+ */
+export function foregroundChild(
+  program: string,
+  args: ReadonlyArray<string>,
+  opts: ForegroundChildOptions = {},
+): ChildProcess {
+  const { stderrFilter, cleanup = (): void => {} } = opts;
+
+  const stdio: Array<"pipe" | "ignore" | "inherit" | number> = stderrFilter
+    ? [0, 1, "pipe"]
+    : [0, 1, 2];
+  if (process.send) stdio.push("ipc" as unknown as number);
+
+  const child = spawn(program, args as string[], { stdio });
+
+  if (stderrFilter && child.stderr) {
+    let buf = "";
+    child.stderr.on("data", (chunk: Buffer | string) => {
+      buf += chunk.toString();
+      let nl: number;
+      while ((nl = buf.search(/\r?\n/)) !== -1) {
+        const eol = buf.startsWith("\r\n", nl) ? 2 : 1;
+        const line = buf.slice(0, nl + eol);
+        buf = buf.slice(nl + eol);
+        if (stderrFilter(line)) process.stderr.write(line);
+      }
+    });
+    child.stderr.on("end", () => {
+      if (buf && stderrFilter(buf)) process.stderr.write(buf);
+    });
+  }
+
+  const childHangup = (): void => {
+    try {
+      child.kill("SIGHUP");
+    } catch (_) {
+      child.kill("SIGTERM");
+    }
+  };
+  const removeOnExit = exitHook(childHangup);
+
+  proxySignals(child);
+  const dog = watchdog(child);
+
+  let done = false;
+  dog.on("close", (code, signal) => {
+    if (done) return;
+    child.kill("SIGKILL");
+    throw new Error("foreground-child watchdog process died unexpectedly!", {
+      cause: {
+        pid: dog.pid,
+        code,
+        signal,
+        watchedProcess: { cmd: program, args, pid: child.pid },
+      },
+    });
+  });
+
+  child.on("close", async (code, signal) => {
+    if (done) return;
+    done = true;
+    const result = cleanup(code, signal, { watchdogPid: dog.pid });
+    const res = isPromise<SyncCleanupResult>(result) ? await result : result;
+    removeOnExit();
+    if (res === false) return;
+    let finalCode: number | null = code;
+    let finalSignal: NodeJS.Signals | null = signal;
+    if (typeof res === "string") {
+      finalSignal = res as NodeJS.Signals;
+      finalCode = null;
+    } else if (typeof res === "number") {
+      finalCode = res;
+      finalSignal = null;
+    }
+    if (finalSignal) {
+      setTimeout(() => {}, 2000);
+      try {
+        process.kill(process.pid, finalSignal);
+      } catch (_) {
+        process.kill(process.pid, "SIGTERM");
+      }
+    } else {
+      process.exit(finalCode ?? 0);
+    }
+  });
+
+  if (process.send) {
+    process.removeAllListeners("message");
+    child.on("message", (message, sendHandle) => {
+      process.send?.(message, sendHandle);
+    });
+    process.on("message", (message, sendHandle) => {
+      if (message === null) return;
+      child.send(message, sendHandle);
+    });
+  }
+
+  return child;
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./exit-hook.ts";
+export * from "./foreground-child.ts";
 export * from "./ignore.ts";
 export * from "./lockfile-async.ts";
 export * from "./retry.ts";