@prismatic-io/lux 0.0.1

package/src/core/exec.ts

@@ -0,0 +1,263 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { launchProcess, processTreeFor } from "./platform-process.js";
+
+/**
+ * The single spawn primitive every Lux subprocess flows through — one tested
+ * place for the whole lifecycle instead of per-call-site subsets.
+ *
+ * Guarantees:
+ * - **Process-group kill.** The child is spawned `detached`, so a timeout
+ *   signals the whole group and reaps grandchildren, not just the direct
+ *   child.
+ * - **Escalation.** SIGTERM first; a child still alive after `killGraceMs`
+ *   gets SIGKILL, so a signal-ignoring process can't hang the run.
+ * - **Bounded memory.** stdout/stderr stop accumulating past `maxBuffer`.
+ * - **Settles once.** A missing binary (`error`) and a normal/killed exit
+ *   (`close`) both resolve/reject exactly one time.
+ * - **EPIPE-safe stdin.** Writing `input` to a child that already closed
+ *   its read end is swallowed, not thrown as an unhandled error.
+ */
+
+export type ExecOptions = {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  /** Run through `/bin/sh -c`. Off by default; only `command-exits-zero` opts in. */
+  shell?: boolean;
+  /** Wall-clock cap. On expiry the group is signalled and `timedOut` is set. */
+  timeoutMs?: number;
+  /** Grace between SIGTERM and SIGKILL after a timeout. Default 5s. */
+  killGraceMs?: number;
+  /** Written to stdin then the stream is closed. Omit to leave stdin closed. */
+  input?: string;
+  /**
+   * Cap on retained stdout/stderr characters (each). Default 10M. Truncation
+   * slices at exactly `maxBuffer` characters, which can split a surrogate pair.
+   */
+  maxBuffer?: number;
+  /**
+   * Aborting terminates the process group like a timeout does (SIGTERM, then
+   * SIGKILL after `killGraceMs`). The promise still resolves normally via
+   * `close`; callers see the kill in the result's `signal`.
+   */
+  signal?: AbortSignal;
+};
+
+export type ExecResult = {
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  stdout: string;
+  stderr: string;
+  stdoutTruncated: boolean;
+  stderrTruncated: boolean;
+  durationMs: number;
+  /** The timeout fired during the run; the exit itself may have another cause. */
+  timedOut: boolean;
+};
+
+export type ManagedProcessOptions = {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  shell?: boolean;
+  /** Grace between the process-group SIGTERM and SIGKILL. Default 5s. */
+  killGraceMs?: number;
+  /** Aborting terminates the process group. */
+  signal?: AbortSignal;
+};
+
+export type ManagedProcessExit = {
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+};
+
+export type ManagedProcess = {
+  child: ChildProcessWithoutNullStreams;
+  /** Resolves only after the OS has accepted the spawn; rejects on spawn failure. */
+  spawned: Promise<void>;
+  /** Resolves after the child and its stdio handles have closed. */
+  exited: Promise<ManagedProcessExit>;
+  /** Idempotently terminates the whole process group and waits for closure. */
+  terminate: () => Promise<ManagedProcessExit>;
+  /** Immediately terminates the complete process tree. */
+  forceTerminate: () => Promise<void>;
+};
+
+/**
+ * Spawn an interactive process behind the same tree-lifecycle boundary as
+ * `exec()`. The caller owns the streams; this primitive owns the process group.
+ */
+export const spawnManagedProcess = (
+  command: string,
+  args: string[] = [],
+  opts: ManagedProcessOptions = {},
+): ManagedProcess => {
+  const child = launchProcess(command, args, {
+    ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+    ...(opts.env === undefined ? {} : { env: opts.env }),
+    ...(opts.shell === undefined ? {} : { shell: opts.shell }),
+  });
+  const tree = processTreeFor(child);
+  child.stdin.on("error", () => {});
+
+  let spawnSettled = false;
+  const spawned = new Promise<void>((resolve, reject) => {
+    child.once("spawn", () => {
+      spawnSettled = true;
+      resolve();
+    });
+    child.once("error", (err) => {
+      if (spawnSettled) return;
+      spawnSettled = true;
+      reject(new Error(`failed to spawn '${command}': ${err.message}`, { cause: err }));
+    });
+  });
+
+  let resolveExit: (result: ManagedProcessExit) => void = () => {};
+  const exited = new Promise<ManagedProcessExit>((resolve) => {
+    resolveExit = resolve;
+  });
+  let killTimer: NodeJS.Timeout | undefined;
+  let abortSignal = opts.signal;
+  let termination: Promise<ManagedProcessExit> | undefined;
+  let closed = false;
+  let leaderExited = false;
+
+  const scheduleEscalation = (): void => {
+    killTimer ??= setTimeout(() => {
+      if (!leaderExited || tree.canReapAfterLeaderExit) void tree.forceTerminate();
+      // A process that created a new session can escape the group while
+      // retaining inherited descriptors. Stop waiting on those descriptors
+      // after the group escalation has completed.
+      child.stdout.destroy();
+      child.stderr.destroy();
+    }, opts.killGraceMs ?? 5_000);
+  };
+
+  const terminate = (): Promise<ManagedProcessExit> => {
+    if (termination) return termination;
+    if (closed) return exited;
+    tree.terminate();
+    scheduleEscalation();
+    termination = exited;
+    return termination;
+  };
+
+  const onAbort = (): void => {
+    void terminate();
+  };
+  if (abortSignal?.aborted) onAbort();
+  else abortSignal?.addEventListener("abort", onAbort, { once: true });
+
+  child.once("exit", () => {
+    leaderExited = true;
+    // POSIX group IDs remain addressable after the leader exits. Windows PIDs
+    // may already have been reused, so its adapter only kills while the owned
+    // leader is alive.
+    if (tree.canReapAfterLeaderExit) void tree.forceTerminate();
+    // Killing the group closes inherited pipes. A descendant that deliberately
+    // escaped the group cannot be signalled, so bound how long its descriptors
+    // can delay process settlement.
+    scheduleEscalation();
+  });
+  child.once("close", (exitCode, signal) => {
+    closed = true;
+    if (killTimer) clearTimeout(killTimer);
+    abortSignal?.removeEventListener("abort", onAbort);
+    abortSignal = undefined;
+    resolveExit({ exitCode, signal });
+  });
+
+  const forceTerminate = (): Promise<void> =>
+    leaderExited && !tree.canReapAfterLeaderExit ? Promise.resolve() : tree.forceTerminate();
+
+  return { child, spawned, exited, terminate, forceTerminate };
+};
+
+export const exec = (
+  command: string,
+  args: string[] = [],
+  opts: ExecOptions = {},
+): Promise<ExecResult> =>
+  new Promise((resolve, reject) => {
+    const start = Date.now();
+    const maxBuffer = opts.maxBuffer ?? 10_000_000;
+    let stdout = "";
+    let stderr = "";
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
+    let timedOut = false;
+    let settled = false;
+
+    const managed = spawnManagedProcess(command, args, {
+      shell: opts.shell ?? false,
+      ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+      ...(opts.env === undefined ? {} : { env: opts.env }),
+      ...(opts.killGraceMs === undefined ? {} : { killGraceMs: opts.killGraceMs }),
+      ...(opts.signal === undefined ? {} : { signal: opts.signal }),
+    });
+    const { child } = managed;
+
+    const terminate = (): void => {
+      void managed.terminate();
+    };
+    const timer =
+      opts.timeoutMs === undefined
+        ? undefined
+        : setTimeout(() => {
+            timedOut = true;
+            terminate();
+          }, opts.timeoutMs);
+
+    const cleanup = (): void => {
+      if (timer) clearTimeout(timer);
+    };
+
+    // setEncoding buffers a multibyte character straddling a pipe-chunk
+    // boundary; decoding each Buffer independently would mangle it to U+FFFD.
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    // Keep draining the pipe after the cap so the child never stalls on
+    // backpressure; we simply stop retaining what we won't report.
+    const append = (buf: string, chunk: string): { text: string; truncated: boolean } => ({
+      text: buf.length >= maxBuffer ? buf : (buf + chunk).slice(0, maxBuffer),
+      truncated: buf.length + chunk.length > maxBuffer,
+    });
+    child.stdout?.on("data", (c: string) => {
+      const appended = append(stdout, c);
+      stdout = appended.text;
+      stdoutTruncated ||= appended.truncated;
+    });
+    child.stderr?.on("data", (c: string) => {
+      const appended = append(stderr, c);
+      stderr = appended.text;
+      stderrTruncated ||= appended.truncated;
+    });
+
+    void managed.spawned.catch((err: unknown) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(err);
+    });
+
+    void managed.exited.then(({ exitCode, signal }) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve({
+        exitCode,
+        signal,
+        stdout,
+        stderr,
+        stdoutTruncated,
+        stderrTruncated,
+        durationMs: Date.now() - start,
+        timedOut,
+      });
+    });
+
+    if (opts.input !== undefined) {
+      // If the child exits before draining a large prompt the write hits a
+      // broken pipe; swallow it so it doesn't surface as an uncaught error.
+      child.stdin.end(opts.input);
+    } else child.stdin.end();
+  });