@osdlc/command-seam 0.0.0-stage → 0.4.0

package/dist/testing.js

@@ -0,0 +1,173 @@
+/**
+ * `@osdlc/command-seam/testing`: fakes for tests, kept out of the main
+ * entry so production code never imports them.
+ *
+ * - `fakeRunner` answers capture-runner calls from a table and records them.
+ * - `fakeNeverExited` builds the result of a run that never exited.
+ * - `fakeProcess` is a managed-process handle the test ends by hand.
+ */
+import { signalName, } from "./process.js";
+import { asAsync } from "./async.js";
+import { shellQuote } from "./quote.js";
+/**
+ * A fake {@link CommandRunner} that answers from a table and records every
+ * call.
+ *
+ * `answers` maps an argv to the result fields that differ from a clean
+ * empty run: `{ exitCode: 0, stdout: '', stderr: '' }`. The key is each
+ * argument quoted with `shellQuote`, joined with single spaces: a plain
+ * argument stays as it is, and one with a space or a shell character is
+ * single-quoted, so `['-m', 'a b']` is `-m 'a b'` and cannot match
+ * `['-m', 'a', 'b']`. It can also be a function of the call; return
+ * `undefined` for no answer.
+ *
+ * A call with no answer reports a failed spawn, as a missing binary would:
+ * `exitCode: 1`, `neverExited: true`, `reason: 'spawn'`, and
+ * `fakeRunner: no answer for: <key>` in `error`, where `<key>` is the table
+ * key that would answer it. So `ran()` is false and `runChecked` throws.
+ * Code that reads a failed run as an answer may still go on, so assert on
+ * `calls` to be sure every call was expected.
+ *
+ * Through `asyncRunner`, `signal` and `processGroup` are recorded but do
+ * nothing, and `onSpawn` is never called.
+ *
+ * @param answers - Results by argv, or a function that picks one.
+ * @returns The runner, the same fake as an async runner, and the list of
+ * calls they received.
+ *
+ * @example
+ * ```ts
+ * const { runner, calls } = fakeRunner({ 'rev-parse --short HEAD': { stdout: 'abc\n' } })
+ * runner.run(['rev-parse', '--short', 'HEAD'], { cwd: '/repo' }).stdout // 'abc\n'
+ * calls[0]?.opts.cwd // '/repo'
+ * ```
+ *
+ * @experimental
+ */
+export function fakeRunner(answers) {
+    const calls = [];
+    const lookup = typeof answers === 'function'
+        ? answers
+        : (argv) => {
+            const key = keyOf(argv);
+            return Object.hasOwn(answers, key) ? answers[key] : undefined;
+        };
+    const runner = {
+        run(argv, opts) {
+            calls.push({ argv: [...argv], opts: { ...opts } });
+            const answer = lookup(argv, opts);
+            if (answer !== undefined)
+                return { exitCode: 0, stdout: '', stderr: '', ...answer };
+            const error = `fakeRunner: no answer for: ${keyOf(argv)}`;
+            return { exitCode: 1, stdout: '', stderr: '', neverExited: true, reason: 'spawn', error };
+        },
+    };
+    return { runner, asyncRunner: asAsync(runner), calls };
+}
+/**
+ * A `fakeRunner` table key. Not `shellJoin`: argv here has no binary name, so
+ * a first argument with `=` (such as `--git-dir=/r`) is not a command name
+ * and needs no quotes.
+ */
+function keyOf(argv) {
+    return argv.map(shellQuote).join(' ');
+}
+/**
+ * A fake answer for a run that never exited, with the fields the real
+ * runners set together for `reason`: `exitCode: 1`, `neverExited: true`,
+ * `reason`, `error: 'fake: <reason>'`, and `signal` where the sync runner
+ * sets one (`SIGKILL` for `timeout` and `output`, `SIGTERM` for `signal`).
+ * A death by a signal from elsewhere has no `error`, as on the real runners.
+ * `fields` override any of these, such as the `signal` or the `error`.
+ *
+ * @param reason - Why the run never exited.
+ * @param fields - Fields to set over the defaults.
+ * @returns An answer for `fakeRunner`.
+ *
+ * @example
+ * ```ts
+ * const { runner } = fakeRunner({ 'fetch origin': fakeNeverExited('timeout') })
+ * runner.run(['fetch', 'origin'], { cwd: '/repo' }).reason // 'timeout'
+ * ```
+ *
+ * @experimental
+ */
+export function fakeNeverExited(reason, fields = {}) {
+    const signal = NEVER_EXITED_SIGNAL[reason];
+    return {
+        exitCode: 1,
+        neverExited: true,
+        reason,
+        ...(signal === undefined ? {} : { signal }),
+        ...(reason === 'signal' ? {} : { error: `fake: ${reason}` }),
+        ...fields,
+    };
+}
+/** The signal the sync runner reports for each reason, where it reports one. */
+const NEVER_EXITED_SIGNAL = {
+    spawn: undefined,
+    timeout: 'SIGKILL',
+    abort: undefined,
+    signal: 'SIGTERM',
+    output: 'SIGKILL',
+};
+/**
+ * A fake {@link ManagedProcessHandle}: it starts nothing, and `exited`
+ * settles when the test calls `exit()`, or when the code under test calls
+ * `kill()` (see `exitOnKill`).
+ *
+ * @param opts - The pid, and which signals sent through `kill()` end the process.
+ * @returns The handle, with `exit()`, the signals sent and a runner that
+ * serves it.
+ *
+ * @example
+ * ```ts
+ * const proc = fakeProcess()
+ * const server = proc.runner.run(['server.js'], { cwd: '.' })
+ * proc.exit({ exitCode: 0 })
+ * await server.exited // { exitCode: 0, signal: null }
+ * ```
+ *
+ * @experimental
+ */
+export function fakeProcess(opts = {}) {
+    const pid = opts.pid ?? 4242;
+    const exitOnKill = opts.exitOnKill ?? true;
+    let settle = () => { };
+    let settled = false;
+    const exited = new Promise((resolve) => (settle = resolve));
+    const exit = (result = {}) => {
+        if (settled)
+            return;
+        settled = true;
+        settle({ exitCode: 0, signal: null, ...result });
+    };
+    const signals = [];
+    const calls = [];
+    const proc = {
+        pid,
+        exited,
+        kill(signal = 'SIGTERM') {
+            signals.push(signal);
+            const name = typeof signal === 'number' ? signalName(signal) : signal;
+            // Signal 0 (a probe) and unknown numbers end nothing.
+            if (name === undefined)
+                return;
+            if (exitOnKill === false)
+                return;
+            if (exitOnKill !== true && !exitOnKill.includes(name))
+                return;
+            exit({ exitCode: 1, signal: name, neverExited: true, reason: 'abort' });
+        },
+        exit,
+        signals,
+        calls,
+        runner: {
+            run(argv, runOpts) {
+                calls.push({ argv: [...argv], opts: { ...runOpts } });
+                return proc;
+            },
+        },
+    };
+    return proc;
+}

package/groups.ts

@@ -0,0 +1,360 @@
+/**
+ * Live process groups, and forwarding of termination signals to them.
+ *
+ * A child started with `processGroup: true` leads its own group and no longer
+ * receives the terminal's Ctrl-C. When the host is then killed by `SIGINT`,
+ * `SIGTERM` or `SIGHUP`, the child and everything it started would be orphaned
+ * (ppid 1). The runners register each such group here, and
+ * {@link installGroupSignalForwarding} makes the host kill them when it is
+ * signalled. A group stays registered until it is empty. Once its run has
+ * settled, the host's normal exit leaves what is left of it running, such as a
+ * daemon; a forwarded signal still kills it.
+ *
+ * Once a signal has been forwarded and this module owns the exit, the host is
+ * stopping: the runners refuse to start a new group, and
+ * {@link forwardedSignal} tells the host's own code to stop.
+ *
+ * The signal listeners exist only while a group is starting or registered. A
+ * JS listener replaces the default "terminate" action and runs only when the
+ * event loop turns, so keeping one armed would make a host blocked in a sync
+ * spawn ignore a signal it would otherwise die from.
+ */
+
+import { constants } from 'node:os'
+
+const osSignals = constants.signals as Record<string, number>
+
+/** Live group leaders, in start order, and whether each one's run has settled. */
+const live = new Map<number, { settled: boolean }>()
+/** Group spawns in progress: the listeners are armed before their pid is known. */
+let spawning = 0
+
+/**
+ * Options for {@link installGroupSignalForwarding}.
+ *
+ * @experimental
+ */
+export interface GroupSignalForwardingOptions {
+  /** Signals to forward. Default `SIGINT`, `SIGTERM` and `SIGHUP`. */
+  signals?: readonly NodeJS.Signals[] | undefined
+  /**
+   * How long the groups have between `SIGTERM` and `SIGKILL`, in ms. Default
+   * 1000: long enough for git to remove its lock files.
+   */
+  graceMs?: number | undefined
+  /**
+   * Called to end the process, with `128 + signal number`. Default: set
+   * `process.exitCode` and let the event loop drain, so piped stdout is not
+   * truncated, then `process.exit` after 500 ms if handles still hold the loop.
+   * Tests replace it.
+   */
+  exit?: ((code: number) => void) | undefined
+}
+
+const DEFAULT_SIGNALS: readonly NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGHUP']
+const POLL_MS = 25
+
+interface Config {
+  signals: readonly NodeJS.Signals[]
+  graceMs: number
+  exit: (code: number) => void
+}
+
+/** Set while forwarding is installed. */
+let config: Config | undefined
+/** Set while the listeners are attached: forwarding installed and a group starting or live. */
+let armed: { off: () => void } | undefined
+/**
+ * The first signal forwarded since install whose exit this module owns (the
+ * host has no listener of its own for it). Cleared only by uninstall.
+ */
+let forwarded: NodeJS.Signals | undefined
+/** Set while a graceful kill is waiting out its grace. */
+let killing = false
+/** A repeat signal already sent `SIGKILL`: the graceful kill stops waiting. */
+let escalated = false
+
+/**
+ * Register a group leader. The returned function unregisters it; call it once
+ * the group is gone so a reused pid is never signalled. Registering the first
+ * group arms the signal listeners (when forwarding is installed); removing the
+ * last disarms them.
+ *
+ * @internal
+ */
+export function trackGroup(pid: number): () => void {
+  live.set(pid, { settled: false })
+  arm()
+  return () => {
+    live.delete(pid)
+    disarmIfIdle()
+  }
+}
+
+/**
+ * Start a group leader with `start` and register it. The listeners are armed
+ * before `start` runs: the child can print, and the host be signalled, before
+ * `spawn` returns, and a signal that comes before the listeners would kill the
+ * host by default and orphan the group. `untrack` is `undefined` when the
+ * child got no pid.
+ *
+ * @internal
+ */
+export function spawnTrackedGroup<C extends { readonly pid?: number | undefined }>(
+  start: () => C,
+): { child: C; untrack: (() => void) | undefined } {
+  spawning += 1
+  arm()
+  try {
+    const child = start()
+    return { child, untrack: child.pid === undefined ? undefined : trackGroup(child.pid) }
+  } finally {
+    spawning -= 1
+    disarmIfIdle()
+  }
+}
+
+/**
+ * Mark the run of the group led by `pid` as settled: the host's exit no longer
+ * kills what is left of the group. A forwarded signal still does. A runner
+ * does not call this for a group it is stopping itself.
+ *
+ * @internal
+ */
+export function settleGroup(pid: number): void {
+  const entry = live.get(pid)
+  if (entry !== undefined) entry.settled = true
+}
+
+/**
+ * Why a new group must not start, or `undefined` when it may. The runners call
+ * this before they spawn with `processGroup: true`.
+ *
+ * @internal
+ */
+export function groupStartRefusal(): string | undefined {
+  if (forwarded === undefined) return undefined
+  return `not started: the host got ${forwarded} and is stopping`
+}
+
+/**
+ * Run `release` once the group led by `pid` has no member: now if it is
+ * already empty, else polled on an unref'd timer.
+ *
+ * Unref'd on purpose: a ref'd poll would keep the host alive for as long as a
+ * member the group left behind. On a Bun version where an unref'd timer does
+ * not fire (see `async.ts`), the entry stays registered. The listeners then
+ * stay armed and a signal still kills that member, which is the safe side.
+ *
+ * @internal
+ */
+export function releaseWhenEmpty(pid: number, release: () => void): void {
+  if (!groupExists(pid)) {
+    release()
+    return
+  }
+  const timer = setInterval(() => {
+    if (groupExists(pid)) return
+    clearInterval(timer)
+    release()
+  }, 250)
+  timer.unref()
+}
+
+/**
+ * True while the group led by `pid` still has a member.
+ *
+ * @internal
+ */
+export function groupExists(pid: number): boolean {
+  try {
+    process.kill(-pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Send `sig` to the group led by `pid`, only while it is registered. */
+function signalGroup(pid: number, sig: NodeJS.Signals): void {
+  if (!live.has(pid)) return
+  try {
+    process.kill(-pid, sig)
+  } catch {
+    // Already gone.
+  }
+}
+
+/**
+ * The pids of the live process groups started with `processGroup: true`.
+ *
+ * @experimental
+ */
+export function liveProcessGroups(): number[] {
+  return [...live.keys()]
+}
+
+/**
+ * The signal the host was sent and forwarded to its groups, or `undefined`
+ * while none has been. Set only when forwarding owns the exit, that is, the
+ * host has no listener of its own for that signal. Once set, the host is
+ * stopping: a loop that runs one command after another should check it and
+ * stop, and the runners refuse to start a new `processGroup` run. The
+ * uninstall function clears it.
+ *
+ * @experimental
+ */
+export function forwardedSignal(): NodeJS.Signals | undefined {
+  return forwarded
+}
+
+/**
+ * The exit code for {@link forwardedSignal}: `128 + signal number`, or
+ * `undefined` while no signal has been forwarded. A host that sets its own
+ * exit code after its work returns keeps this one over it:
+ * `process.exitCode = forwardedExitCode() ?? code`.
+ *
+ * @experimental
+ */
+export function forwardedExitCode(): number | undefined {
+  return forwarded === undefined ? undefined : 128 + signalNumber(forwarded)
+}
+
+function arm(): void {
+  if (config === undefined || armed !== undefined || (live.size === 0 && spawning === 0)) return
+  const { signals, graceMs, exit } = config
+  const onExit = () => {
+    // The host is going away: nothing async runs after this, so end every group
+    // whose run is still in flight now. A settled run's leftovers stay.
+    for (const [pid, { settled }] of live) if (!settled) signalGroup(pid, 'SIGKILL')
+  }
+  const handlers = signals.map((sig) => {
+    const handler = () => {
+      const code = 128 + signalNumber(sig)
+      if (forwarded !== undefined || killing) {
+        // A repeat signal: stop waiting.
+        escalated = true
+        for (const pid of live.keys()) signalGroup(pid, 'SIGKILL')
+        if (!othersListen(sig)) exit(code)
+        return
+      }
+      // A host listener owns the exit and may keep running (a REPL cancelling
+      // a job, a daemon reloading on SIGHUP): kill the groups, but do not
+      // refuse later runs.
+      const othersOwnExit = othersListen(sig)
+      if (!othersOwnExit) forwarded = sig
+      killing = true
+      escalated = false
+      void killAll(graceMs).then(() => {
+        killing = false
+        if (!escalated && !othersOwnExit) exit(code)
+      })
+    }
+    // First in line: Node and Bun drop a host's `process.once` wrapper before
+    // calling it, so a handler that ran later would not count that listener.
+    process.prependListener(sig, handler)
+    return [sig, handler] as const
+  })
+  process.on('exit', onExit)
+  armed = {
+    off: () => {
+      for (const [sig, handler] of handlers) process.off(sig, handler)
+      process.off('exit', onExit)
+    },
+  }
+}
+
+function disarm(): void {
+  armed?.off()
+  armed = undefined
+}
+
+function disarmIfIdle(): void {
+  if (live.size === 0 && spawning === 0) disarm()
+}
+
+/** Another listener than ours is attached for `sig`: it owns the exit. */
+function othersListen(sig: NodeJS.Signals): boolean {
+  return process.listenerCount(sig) > 1
+}
+
+/**
+ * Enable forwarding of termination signals to live process groups.
+ *
+ * While at least one group started with `processGroup: true` is live, `SIGINT`,
+ * `SIGTERM` and `SIGHUP` send `SIGTERM` to every registered group, then
+ * `SIGKILL` to those still registered after `graceMs`, then end the process
+ * with `128 + signal number`, the shell convention. A second signal during the
+ * grace, or any later one, skips straight to `SIGKILL` and the exit. From the
+ * first signal on, {@link forwardedSignal} returns it and the runners refuse
+ * to start a new `processGroup` run, until the uninstall function resets
+ * that. A `process` `exit` handler, armed with the listeners, also `SIGKILL`s
+ * every group whose run is still in flight, so a host that exits first does
+ * not leave one behind. A member that a settled run left behind, such as a
+ * daemon, outlives the host's exit; a forwarded signal still kills it.
+ *
+ * The listeners are attached just before the first group starts and removed
+ * when the last one goes, so a host with no live group keeps each signal's default
+ * action. If the host has its own listener for the signal (`process.once`
+ * counts too), the groups still
+ * get `SIGTERM` at once and `SIGKILL` after `graceMs` (or on `exit`, if
+ * sooner and the run is in flight), but that listener keeps the exit, and later runs are not refused.
+ * Calling it again while installed is a no-op returning the same
+ * uninstall function. `SIGKILL` of the host cannot be caught and still orphans
+ * its groups. POSIX only; a no-op on Windows.
+ *
+ * @returns A function that removes the forwarding.
+ * @experimental
+ */
+export function installGroupSignalForwarding(opts: GroupSignalForwardingOptions = {}): () => void {
+  if (process.platform === 'win32') return () => {}
+  if (config !== undefined) return uninstall
+  config = {
+    signals: opts.signals ?? DEFAULT_SIGNALS,
+    graceMs: opts.graceMs ?? 1000,
+    exit: opts.exit ?? defaultExit,
+  }
+  arm()
+  return uninstall
+}
+
+function uninstall(): void {
+  disarm()
+  config = undefined
+  forwarded = undefined
+  killing = false
+  escalated = false
+}
+
+/**
+ * Set the exit code and let output drain; force the exit after 500 ms. Not
+ * unref'd: an unref'd timer does not reliably fire on every Bun version, and
+ * holding the loop for 500 ms after a signal is cheap.
+ */
+function defaultExit(code: number): void {
+  process.exitCode = code
+  setTimeout(() => process.exit(code), 500)
+}
+
+/**
+ * `SIGTERM` every registered group, wait up to `graceMs` for them to go, then
+ * `SIGKILL` those still registered. Stops early when `escalated` says a repeat
+ * signal already did the kill.
+ */
+async function killAll(graceMs: number): Promise<void> {
+  // Drop entries whose group is already empty, so a stale pid is never signalled.
+  for (const pid of liveProcessGroups()) if (!groupExists(pid)) live.delete(pid)
+  for (const pid of liveProcessGroups()) signalGroup(pid, 'SIGTERM')
+  const deadline = performance.now() + graceMs
+  while (!escalated && performance.now() < deadline) {
+    if (!liveProcessGroups().some(groupExists)) return
+    await new Promise((res) => setTimeout(res, POLL_MS))
+  }
+  if (escalated) return
+  for (const pid of liveProcessGroups()) if (groupExists(pid)) signalGroup(pid, 'SIGKILL')
+}
+
+function signalNumber(sig: NodeJS.Signals): number {
+  const n = osSignals[sig]
+  return typeof n === 'number' ? n : 15
+}

package/index.ts

@@ -0,0 +1,98 @@
+/**
+ * `@osdlc/command-seam`: run external commands through a small interface
+ * that tests can replace.
+ *
+ * A runner is an object with a `run` method. Code that needs a command takes
+ * a runner as a parameter. Production passes a real one; tests pass a fake.
+ *
+ * - `spawnRunner` / `spawnRunnerAsync` capture a finished run's output
+ *   ({@link CommandResult}).
+ * - `runShell` / `shellRunner` run a shell string through `sh -c --`.
+ * - `streamRunner` runs with inherited stdio, so output appears live.
+ * - `managedProcessRunner` starts a process and returns a handle to it
+ *   without waiting for it to finish. `stopProcess` stops it with a grace
+ *   period.
+ * - `withDefaults` binds default options to any of them.
+ *
+ * The capture runners share {@link CommandResult}, {@link CommandRunOptions}
+ * and {@link CommandFailed}, so one `instanceof CommandFailed` check covers
+ * the sync and async forms.
+ */
+
+export {
+  catchFailed,
+  CommandFailed,
+  mapFailed,
+  resolveRunner,
+  runChecked,
+  spawnRunner,
+  type CommandResult,
+  type CommandRunner,
+  type CommandRunOptions,
+  type EnvOverrides,
+  type NeverExitedReason,
+} from './sync.ts'
+
+export {
+  asAsync,
+  catchFailedAsync,
+  mapFailedAsync,
+  resolveRunnerAsync,
+  runCheckedAsync,
+  spawnRunnerAsync,
+  type AsyncCommandRunner,
+  type AsyncCommandRunOptions,
+} from './async.ts'
+
+export {
+  failureText,
+  firstLine,
+  parseJsonResult,
+  ran,
+  runJson,
+  runJsonAsync,
+  stderrOrError,
+  type FailureTextOptions,
+  type JsonRun,
+  type RunJsonOptions,
+} from './result.ts'
+
+export { shellJoin, shellQuote } from './quote.ts'
+
+export {
+  runShell,
+  runShellAsync,
+  shellRunner,
+  shellRunnerAsync,
+  type AsyncShellRunner,
+  type AsyncShellRunOptions,
+  type ShellRunner,
+  type ShellPositionals,
+  type ShellRunOptions,
+} from './shell.ts'
+
+export {
+  streamRunner,
+  type StreamRunner,
+  type StreamRunOptions,
+  type StreamResult,
+} from './stream.ts'
+
+export {
+  managedProcessRunner,
+  stopProcess,
+  type ManagedProcessRunner,
+  type ManagedProcessHandle,
+  type ManagedProcessRunOptions,
+  type ManagedProcessExit,
+} from './process.ts'
+
+export {
+  forwardedExitCode,
+  forwardedSignal,
+  installGroupSignalForwarding,
+  liveProcessGroups,
+  type GroupSignalForwardingOptions,
+} from './groups.ts'
+
+export { withDefaults, type DefaultedRunner } from './defaults.ts'