@dbx-tools/core 0.9.69 → 0.9.71

package/src/exec.ts

@@ -49,13 +49,21 @@ import {
   spawn as nodeSpawn,
   spawnSync as nodeSpawnSync,
 } from "node:child_process";
+import { readdir, readFile } from "node:fs/promises";
 import * as readline from "node:readline";
 import { Readable } from "node:stream";
+import { text } from "node:stream/consumers";
 import { finished } from "node:stream/promises";
 
 /** Shell-compatible exit code returned when an executable cannot be found. */
 export const COMMAND_NOT_FOUND_EXIT_CODE = 127;
 
+const DEFAULT_GRACEFUL_TIMEOUT_MS = 10_000;
+const DEFAULT_FORCE_TIMEOUT_MS = 4_000;
+const DEFAULT_KILL_POLL_INTERVAL_MS = 100;
+const WINDOWS_PROCESS_SNAPSHOT_SCRIPT =
+  "Get-CimInstance Win32_Process | ForEach-Object { '{0} {1} {2}' -f $_.ProcessId, $_.ParentProcessId, $_.CreationDate.ToFileTimeUtc() }";
+
 /** Stdio mode for a subprocess fd. */
 export type ExecStdio = "inherit" | "pipe" | "ignore";
 
@@ -114,17 +122,16 @@ export type ExecResult = {
  * This is additive - the object still satisfies `Promise<ExecResult>`, so every
  * existing `await spawn(...)` / `spawn(...).then(...)` caller is unchanged. What
  * is new is that the same value is the live child: callers that want to supervise
- * it (read `.pid`, `.kill(signal)`, listen for `exit`) can, without a second
- * spawn. `@dbx-tools/appkit`'s `bindProcess` consumes exactly this - one code path
- * supervises both a bare `ChildProcess` (e.g. portr) and a `spawn()` result.
+ * it can read `.pid`, call `.kill(signal)`, and listen for `exit` without a
+ * second spawn.
  *
  * @example Await it (unchanged)
  * const { stdout } = await spawn("git", ["rev-parse", "HEAD"], { stdout: "capture" });
  *
  * @example Supervise it
  * const proc = spawn("bun", ["src/server.ts"]);
- * ctx.bindProcess(proc);            // live handle
- * const { exitCode } = await proc;  // still a promise
+ * const shutdown = () => kill(proc);
+ * const { exitCode } = await proc;
  */
 export type ChildProcessResult = ChildProcess & Promise<ExecResult>;
 
@@ -144,6 +151,20 @@ export type ExecOptions = Omit<SpawnOptions, "stdio"> & {
   trim?: boolean;
 };
 
+/** Graceful and forced shutdown policy for {@link kill}. */
+export interface KillOptions {
+  /** Signal sent to the snapshotted process tree. `false` skips this phase. Defaults to `SIGTERM`. */
+  gracefulSignal?: NodeJS.Signals | false;
+  /** Time to wait for graceful shutdown. Defaults to 10 seconds. */
+  gracefulTimeoutMs?: number;
+  /** Signal sent to survivors. `false` disables forced termination. Defaults to `SIGKILL`. */
+  forceSignal?: NodeJS.Signals | false;
+  /** Time to poll and force newly discovered descendants. Defaults to 4 seconds. */
+  forceTimeoutMs?: number;
+  /** Interval used to refresh and poll the process tree. Defaults to 100 milliseconds. */
+  pollIntervalMs?: number;
+}
+
 /** Stdio mode for {@link spawnSync} (no per-line callbacks). */
 export type SyncExecStdio = ExecStdio | "capture";
 
@@ -187,6 +208,19 @@ interface ParsedSpawnArgs<T extends SpawnOptions> {
   options?: T;
 }
 
+/** One operating-system process captured before tree shutdown begins. */
+interface ProcessSnapshotEntry {
+  pid: number;
+  parentPid: number;
+  identity: string;
+}
+
+/** Current retained processes plus descendants first observed by one refresh. */
+interface RefreshedProcessTree {
+  processes: ProcessSnapshotEntry[];
+  discovered: ProcessSnapshotEntry[];
+}
+
 function parseSpawnArgs<T extends SpawnOptions>(input: SpawnArgs<T>): ParsedSpawnArgs<T> {
   let [value, ...values] = input;
   const [command, ...commandArgs] = shlex(value!);
@@ -271,6 +305,258 @@ function isCommandNotFoundError(error: unknown): error is NodeJS.ErrnoException
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
 
+/** Return whether a process operation failed because the PID no longer exists. */
+function isMissingProcessError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error && error.code === "ESRCH";
+}
+
+/** Validate a finite non-negative timeout. */
+function timeoutValue(value: number, name: string): number {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`${name} must be a finite non-negative number`);
+  }
+  return value;
+}
+
+/** Validate a finite positive polling interval. */
+function pollIntervalValue(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError("pollIntervalMs must be a finite positive number");
+  }
+  return value;
+}
+
+/** Parse the common `pid parentPid identity` process-snapshot format. */
+function parseProcessSnapshot(lines: readonly string[]): ProcessSnapshotEntry[] {
+  const snapshot: ProcessSnapshotEntry[] = [];
+  for (const line of lines) {
+    const match = /^\s*(\d+)\s+(\d+)(?:\s+(.+?))?\s*$/.exec(line);
+    const identity = match?.[3]?.trim();
+    if (!match || !identity) continue;
+    snapshot.push({
+      pid: Number.parseInt(match[1]!, 10),
+      parentPid: Number.parseInt(match[2]!, 10),
+      identity,
+    });
+  }
+  return snapshot;
+}
+
+/** Return whether a `/proc` record disappeared or is inaccessible during a snapshot. */
+function isUnavailableProcRecord(error: unknown): error is NodeJS.ErrnoException {
+  if (!(error instanceof Error) || !("code" in error)) return false;
+  return error.code === "ENOENT" || error.code === "EACCES" || error.code === "EPERM";
+}
+
+/** Parse Linux `/proc/<pid>/stat` parent PID and exact process-start ticks. */
+function parseLinuxProcessStat(pid: number, stat: string): ProcessSnapshotEntry | undefined {
+  const commandEnd = stat.lastIndexOf(")");
+  if (commandEnd < 0) return undefined;
+  const fields = stat
+    .slice(commandEnd + 1)
+    .trim()
+    .split(/\s+/);
+  const parentPid = Number.parseInt(fields[1]!, 10);
+  const startTicks = fields[19];
+  if (!Number.isSafeInteger(parentPid) || !startTicks) return undefined;
+  return { pid, parentPid, identity: startTicks };
+}
+
+/** Capture Linux process identities from `/proc` without second-level truncation. */
+async function linuxProcessSnapshot(): Promise<ProcessSnapshotEntry[]> {
+  const directories = await readdir("/proc", { withFileTypes: true });
+  const entries = await Promise.all(
+    directories
+      .filter((entry) => entry.isDirectory() && /^\d+$/.test(entry.name))
+      .map(async (entry): Promise<ProcessSnapshotEntry | undefined> => {
+        const pid = Number.parseInt(entry.name, 10);
+        try {
+          return parseLinuxProcessStat(pid, await readFile(`/proc/${entry.name}/stat`, "utf8"));
+        } catch (error) {
+          if (isUnavailableProcRecord(error)) return undefined;
+          throw error;
+        }
+      }),
+  );
+  return entries.filter((entry): entry is ProcessSnapshotEntry => entry !== undefined);
+}
+
+/**
+ * Capture the current PID, parent PID, and process-start identity table.
+ *
+ * Linux reads exact start ticks from `/proc`. Windows uses the built-in
+ * PowerShell CIM provider. macOS and other POSIX platforms combine `ps`
+ * process start time and executable name.
+ */
+async function processSnapshot(): Promise<ProcessSnapshotEntry[]> {
+  if (process.platform === "linux") return linuxProcessSnapshot();
+
+  const command = process.platform === "win32" ? "powershell.exe" : "ps";
+  const args =
+    process.platform === "win32"
+      ? ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", WINDOWS_PROCESS_SNAPSHOT_SCRIPT]
+      : ["-A", "-o", "pid=", "-o", "ppid=", "-o", "lstart=", "-o", "comm="];
+  const proc = nodeSpawn(command, args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+  const stdout = text(proc.stdout!);
+  const stderr = text(proc.stderr!);
+  const [exitCode, stdoutText, stderrText] = await Promise.all([waitForExit(proc), stdout, stderr]);
+  if (exitCode !== 0) {
+    throw new Error(
+      `${commandLabel(command, args)} failed (exit ${exitCode})${
+        stderrText ? `: ${stderrText.trim()}` : ""
+      }`,
+    );
+  }
+  return parseProcessSnapshot(linesFromCapturedOutput(stdoutText));
+}
+
+/** Group a process snapshot by parent PID. */
+function processChildren(
+  snapshot: readonly ProcessSnapshotEntry[],
+): Map<number, ProcessSnapshotEntry[]> {
+  const children = new Map<number, ProcessSnapshotEntry[]>();
+  for (const entry of snapshot) {
+    const siblings = children.get(entry.parentPid) ?? [];
+    siblings.push(entry);
+    children.set(entry.parentPid, siblings);
+  }
+  return children;
+}
+
+/** Select one snapshotted process tree in descendant-first signal order. */
+function processTree(
+  snapshot: readonly ProcessSnapshotEntry[],
+  rootPid: number,
+): ProcessSnapshotEntry[] {
+  const root = snapshot.find((entry) => entry.pid === rootPid);
+  if (!root) throw new Error(`Unable to identify child process ${rootPid}`);
+
+  const children = processChildren(snapshot);
+  const tree: ProcessSnapshotEntry[] = [];
+  const visited = new Set<number>([rootPid]);
+  const appendDescendants = (parentPid: number): void => {
+    for (const child of children.get(parentPid) ?? []) {
+      if (visited.has(child.pid)) continue;
+      visited.add(child.pid);
+      appendDescendants(child.pid);
+      tree.push(child);
+    }
+  };
+  appendDescendants(rootPid);
+  tree.push(root);
+  return tree;
+}
+
+/** Return whether two snapshots identify the same process lifetime. */
+function sameProcess(previous: ProcessSnapshotEntry, current: ProcessSnapshotEntry): boolean {
+  return previous.identity === current.identity;
+}
+
+/**
+ * Refresh retained process identities and merge descendants created after the
+ * initial snapshot.
+ */
+function refreshProcessTree(
+  retained: Map<number, ProcessSnapshotEntry>,
+  snapshot: readonly ProcessSnapshotEntry[],
+): RefreshedProcessTree {
+  const currentByPid = new Map(snapshot.map((entry) => [entry.pid, entry]));
+  const children = processChildren(snapshot);
+  const processes = new Map<number, ProcessSnapshotEntry>();
+  const discovered: ProcessSnapshotEntry[] = [];
+  const queue: ProcessSnapshotEntry[] = [];
+
+  for (const previous of retained.values()) {
+    const current = currentByPid.get(previous.pid);
+    if (!current || !sameProcess(previous, current)) continue;
+    retained.set(current.pid, current);
+    processes.set(current.pid, current);
+    queue.push(current);
+  }
+
+  const visited = new Set(processes.keys());
+  for (let index = 0; index < queue.length; index += 1) {
+    const parent = queue[index]!;
+    for (const child of children.get(parent.pid) ?? []) {
+      const previous = retained.get(child.pid);
+      if (!previous || !sameProcess(previous, child)) {
+        retained.set(child.pid, child);
+        discovered.push(child);
+      }
+      processes.set(child.pid, child);
+      if (visited.has(child.pid)) continue;
+      visited.add(child.pid);
+      queue.push(child);
+    }
+  }
+
+  return { processes: [...processes.values()], discovered };
+}
+
+/** Build the per-lifetime key used to prevent repeated signals after PID reuse. */
+function processIdentity(entry: ProcessSnapshotEntry): string {
+  return `${entry.pid}:${entry.identity}`;
+}
+
+/** Signal each process identity once, ignoring PIDs that already exited. */
+function signalProcesses(
+  processes: readonly ProcessSnapshotEntry[],
+  signal: NodeJS.Signals,
+  signaled: Set<string>,
+): void {
+  const errors: unknown[] = [];
+  for (const entry of processes) {
+    const identity = processIdentity(entry);
+    if (signaled.has(identity)) continue;
+    signaled.add(identity);
+    try {
+      process.kill(entry.pid, signal);
+    } catch (error) {
+      if (!isMissingProcessError(error)) errors.push(error);
+    }
+  }
+  if (errors.length > 0) {
+    throw new AggregateError(errors, `Failed to send ${signal} to the complete process tree`);
+  }
+}
+
+/** Pause without detaching the shutdown operation from the event loop. */
+function delay(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+/**
+ * Poll refreshed process snapshots until the retained tree exits or the
+ * timeout elapses. Descendants created during shutdown are retained and receive
+ * the current shutdown signal once.
+ */
+async function waitForProcessTreeExit(
+  retained: Map<number, ProcessSnapshotEntry>,
+  initialProcesses: readonly ProcessSnapshotEntry[],
+  signal: NodeJS.Signals,
+  signaled: Set<string>,
+  timeoutMs: number,
+  pollIntervalMs: number,
+): Promise<ProcessSnapshotEntry[]> {
+  let survivors = [...initialProcesses];
+  const deadline = Date.now() + timeoutMs;
+  while (survivors.length > 0) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs > 0) await delay(Math.min(pollIntervalMs, remainingMs));
+
+    const refreshed = refreshProcessTree(retained, await processSnapshot());
+    if (refreshed.discovered.length > 0) {
+      signalProcesses(refreshed.discovered, signal, signaled);
+    }
+    survivors = refreshed.processes;
+    if (Date.now() >= deadline) break;
+  }
+  return survivors;
+}
+
 /**
  * Build the object returned from {@link spawn} with live line arrays and lazy
  * trimmed `stdout` / `stderr` getters derived from those lines.
@@ -530,6 +816,92 @@ function linesFromCapturedOutput(output: string): string[] {
   return output.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
 }
 
+/**
+ * Stop a child process and descendants discovered through operating-system
+ * process snapshots.
+ *
+ * The initial tree is retained before signaling so descendants remain
+ * targetable after their parent exits or they are reparented. Polling refreshes
+ * the process table, merges newly created descendants, and sends each one the
+ * active shutdown signal once. Either phase can be disabled for graceful-only
+ * or force-only termination. macOS and other POSIX platforms use `ps`; Windows
+ * uses the built-in PowerShell CIM process provider.
+ *
+ * Windows does not implement POSIX signal semantics. Node terminates processes
+ * unconditionally for supported signals there, including `SIGTERM`.
+ *
+ * @param child - Root child process whose snapshotted tree should stop
+ * @param options - Graceful signal, force signal, timeout, and polling policy
+ * @throws When the process table cannot be captured, a signal cannot be sent,
+ * or identity-matched processes remain after the final enabled phase
+ */
+export async function kill(child: ChildProcess, options: KillOptions = {}): Promise<void> {
+  if (child.pid === undefined || child.exitCode !== null || child.signalCode !== null) {
+    return;
+  }
+
+  const gracefulTimeoutMs = timeoutValue(
+    options.gracefulTimeoutMs ?? DEFAULT_GRACEFUL_TIMEOUT_MS,
+    "gracefulTimeoutMs",
+  );
+  const forceTimeoutMs = timeoutValue(
+    options.forceTimeoutMs ?? DEFAULT_FORCE_TIMEOUT_MS,
+    "forceTimeoutMs",
+  );
+  const pollIntervalMs = pollIntervalValue(options.pollIntervalMs ?? DEFAULT_KILL_POLL_INTERVAL_MS);
+  const snapshot = await processSnapshot();
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  const tree = processTree(snapshot, child.pid);
+  const retained = new Map(tree.map((entry) => [entry.pid, entry]));
+  const gracefulSignal = options.gracefulSignal === undefined ? "SIGTERM" : options.gracefulSignal;
+  const forceSignal = options.forceSignal === undefined ? "SIGKILL" : options.forceSignal;
+  if (gracefulSignal === false && forceSignal === false) {
+    throw new Error("At least one process-tree termination signal must be enabled");
+  }
+
+  let forceTargets = tree;
+  if (gracefulSignal !== false) {
+    const gracefulSignaled = new Set<string>();
+    signalProcesses(tree, gracefulSignal, gracefulSignaled);
+    forceTargets = await waitForProcessTreeExit(
+      retained,
+      tree,
+      gracefulSignal,
+      gracefulSignaled,
+      gracefulTimeoutMs,
+      pollIntervalMs,
+    );
+  }
+  if (forceTargets.length === 0) return;
+  if (forceSignal === false) {
+    if (gracefulSignal === false) {
+      throw new Error("At least one process-tree termination signal must be enabled");
+    }
+    throw processTerminationError(gracefulSignal, forceTargets);
+  }
+
+  const forceSignaled = new Set<string>();
+  signalProcesses(forceTargets, forceSignal, forceSignaled);
+  const forcedSurvivors = await waitForProcessTreeExit(
+    retained,
+    forceTargets,
+    forceSignal,
+    forceSignaled,
+    forceTimeoutMs,
+    pollIntervalMs,
+  );
+  if (forcedSurvivors.length > 0) throw processTerminationError(forceSignal, forcedSurvivors);
+}
+
+function processTerminationError(
+  signal: NodeJS.Signals,
+  processes: readonly ProcessSnapshotEntry[],
+): Error {
+  return new Error(
+    `Processes did not terminate after ${signal}: ${processes.map((entry) => entry.pid).join(", ")}`,
+  );
+}
+
 /**
  * Spawn a subprocess. Returns the LIVE child handle that is ALSO a
  * `Promise<ExecResult>` resolving on exit - see {@link ChildProcessResult}.
@@ -539,7 +911,7 @@ function linesFromCapturedOutput(output: string): string[] {
  * or rejects (spawn error other than a missing executable, or `check` on non-zero
  * exit). Existing `await spawn(...)` callers are unaffected. The handle half lets a
  * caller supervise the process (`.pid`, `.kill(signal)`, `exit` event) without a
- * second spawn - e.g. `@dbx-tools/appkit`'s `bindProcess`.
+ * second spawn.
  *
  * @param command - Executable to run (resolved on `PATH` when `shell` is set on options)
  * @param args - Arguments passed verbatim to the executable