@osdlc/command-seam 0.0.0-stage → 0.4.0

package/package.json

@@ -1,6 +1,97 @@
 {
   "name": "@osdlc/command-seam",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.0",
+  "description": "Injectable subprocess runner for Node: capture, stream and managed-process runners, hard timeouts, failures as results.",
+  "license": "MIT",
+  "author": "SK Sizer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/osdlc/osdlc.git",
+    "directory": "packages/ts/command-seam"
+  },
+  "homepage": "https://github.com/osdlc/osdlc/tree/main/packages/ts/command-seam#readme",
+  "bugs": "https://github.com/osdlc/osdlc/issues",
+  "keywords": [
+    "subprocess",
+    "spawn",
+    "exec",
+    "child-process",
+    "timeout",
+    "dependency-injection",
+    "test-seam",
+    "testing",
+    "mock",
+    "cli",
+    "process-group",
+    "abort",
+    "stdio",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "bun": "./index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "bun": "./testing.ts",
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "smoke.mjs",
+    "index.ts",
+    "sync.ts",
+    "async.ts",
+    "result.ts",
+    "stream.ts",
+    "process.ts",
+    "groups.ts",
+    "quote.ts",
+    "shell.ts",
+    "defaults.ts",
+    "testing.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md"
+  ],
+  "peerDependencies": {
+    "@types/node": "*"
+  },
+  "peerDependenciesMeta": {
+    "@types/node": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.14",
+    "@types/node": "^26.1.0",
+    "oxlint": "^1.65.0",
+    "prettier": "3.9.6",
+    "typescript": "~6.0.3",
+    "@osdlc/prettier-config": "^0.2.3",
+    "@osdlc/tsconfig": "^0.3.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "test": "bun test",
+    "smoke": "node smoke.mjs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "oxlint .",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.build.json --noEmit"
+  }
 }

package/process.ts

@@ -0,0 +1,270 @@
+/**
+ * The managed-process runner: start a long-running child and get a handle to
+ * it, for a process the caller watches and stops rather than waits on.
+ *
+ * Every other runner in this package waits for the child to exit
+ * (synchronously or through a promise) and reports how it went. This one
+ * returns as soon as the child exists, so the caller can do other work while
+ * it runs: enforce its own timeout, respond to signals, stop it later.
+ */
+
+import { spawn } from 'node:child_process'
+import { constants } from 'node:os'
+
+import { groupStartRefusal, releaseWhenEmpty, settleGroup, spawnTrackedGroup } from './groups.ts'
+import { cwdError, mergedEnv, timerMs, type EnvOverrides, type NeverExitedReason } from './sync.ts'
+
+/** Per-call options for a {@link ManagedProcessRunner}. */
+export interface ManagedProcessRunOptions {
+  /** Working directory for the child. */
+  cwd: string
+  /**
+   * Variables merged over the parent's environment. An `undefined` value
+   * removes that variable from the child's environment.
+   */
+  env?: EnvOverrides | undefined
+  /**
+   * Run the child as its own process-group leader. {@link
+   * ManagedProcessHandle.kill} then signals the whole group instead of just
+   * the direct child, so processes the child started die with it. The group
+   * no longer gets the terminal's Ctrl-C. POSIX only.
+   * `installGroupSignalForwarding` kills live groups when the host is
+   * signalled, and once it is stopping the host, a new group run is refused
+   * (`reason: 'abort'`, pid `-1`).
+   */
+  processGroup?: boolean | undefined
+  /**
+   * Let the parent exit while the child runs: the child's handle stops
+   * holding the parent's event loop open. Meant for a `processGroup` child
+   * that is supposed to outlive the call that started it (a loop tick that
+   * starts a run and returns); {@link ManagedProcessHandle.exited} then only
+   * settles while the parent is still alive. An `unref`'d group is not tracked
+   * by `installGroupSignalForwarding`: a signal to the parent does not reach it,
+   * and the parent's exit does not `SIGKILL` it.
+   */
+  unref?: boolean | undefined
+}
+
+/** How a managed process ended. */
+export interface ManagedProcessExit {
+  /** The child's exit code, or `1` when it never reported one (see `neverExited`). */
+  exitCode: number
+  /** The signal that ended the child, or `null` when it exited on its own or never started. */
+  signal: NodeJS.Signals | null
+  /**
+   * No exit code was reported: the spawn failed (e.g. a missing binary) or a
+   * signal killed the process (see `signal`). Same meaning as
+   * `CommandResult.neverExited`.
+   */
+  neverExited?: boolean | undefined
+  /**
+   * Why no exit code was reported. Set whenever `neverExited` is, absent
+   * otherwise. `spawn`: the process never started (see `error`). `abort`: a
+   * signal ended it after the caller's own `kill()`, or a `processGroup` run
+   * was refused because signal forwarding is stopping the host (it never
+   * started; see `error`). `signal`: a signal from
+   * elsewhere ended it. There is no `timeout` or `output`: this runner has
+   * neither a timeout nor captured output.
+   */
+  reason?: Exclude<NeverExitedReason, 'timeout' | 'output'> | undefined
+  /**
+   * The spawn error's message, such as `spawn node ENOENT`, when `reason` is
+   * `spawn`, or the refusal message for a refused `processGroup` run.
+   */
+  error?: string | undefined
+}
+
+/** A running child: its pid, a way to kill it, and a promise settling once it's gone. */
+export interface ManagedProcessHandle {
+  /** The child's pid, or `-1` when it could not be spawned at all. */
+  readonly pid: number
+  /**
+   * Send `signal` (default `SIGTERM`) to the child, or to its whole process
+   * group when started with `processGroup: true`. Does nothing when `pid` is
+   * `-1`. Without `processGroup`, it also does nothing once the child has
+   * exited, so a reused pid is never signalled. With `processGroup`, it still
+   * signals any member of the group that is left. If the process dies of a
+   * signal sent here, `exited` reports `reason: 'abort'`. A signal the child
+   * handles and survives does not count: a later death by another signal is
+   * `'signal'`.
+   */
+  kill(signal?: NodeJS.Signals | number): void
+  /** Settles once the child is gone, including when the spawn failed. Never rejects. */
+  readonly exited: Promise<ManagedProcessExit>
+}
+
+/** Starts a long-running process and returns a handle instead of waiting for it. */
+export interface ManagedProcessRunner {
+  /**
+   * Start the binary with `argv` (without the binary name) and return at
+   * once. A failed spawn is reported through `exited`, not thrown. A NUL
+   * byte in argv or env is a programmer error and throws.
+   */
+  run(argv: string[], opts: ManagedProcessRunOptions): ManagedProcessHandle
+}
+
+/**
+ * The default {@link ManagedProcessRunner}: starts `binary` with `spawn`.
+ * Stdio is always inherited, so the child's output reaches the terminal. It
+ * does not capture output and has no timeout of its own.
+ *
+ * @param binary - A name looked up on `PATH`, or a path.
+ * @returns A runner for that binary.
+ *
+ * @example
+ * ```ts
+ * const server = managedProcessRunner('node').run(['server.js'], {
+ *   cwd: '.',
+ *   processGroup: true,
+ * })
+ * setTimeout(() => server.kill(), 5_000)
+ * const { exitCode, signal } = await server.exited
+ * ```
+ */
+export function managedProcessRunner(binary: string): ManagedProcessRunner {
+  return {
+    run(argv: string[], opts: ManagedProcessRunOptions): ManagedProcessHandle {
+      const cwdMessage = cwdError(`spawn ${binary}`, binary, argv, opts)
+      if (cwdMessage !== undefined) {
+        return { pid: -1, kill: () => {}, exited: Promise.resolve(spawnExit(cwdMessage)) }
+      }
+      const group = opts.processGroup === true
+      const refusal = group ? groupStartRefusal() : undefined
+      if (refusal !== undefined) {
+        return { pid: -1, kill: () => {}, exited: Promise.resolve(refusedExit(refusal)) }
+      }
+      const start = () =>
+        spawn(binary, argv, {
+          cwd: opts.cwd,
+          detached: group,
+          stdio: 'inherit',
+          ...mergedEnv(opts),
+        })
+      // An `unref`'d group is meant to outlive the host, so forwarding must not reap it.
+      const { child, untrack: untrackGroup } =
+        group && opts.unref !== true
+          ? spawnTrackedGroup(start)
+          : { child: start(), untrack: undefined }
+      const pid = child.pid ?? -1
+      if (opts.unref === true) child.unref()
+      // The signals `kill()` has sent. A death by one of them is the caller's
+      // own stop; a death by any other signal came from elsewhere.
+      const sent = new Set<NodeJS.Signals>()
+
+      const exited = new Promise<ManagedProcessExit>((resolve) => {
+        let settled = false
+        const finish = (result: ManagedProcessExit): void => {
+          if (settled) return
+          settled = true
+          resolve(result)
+        }
+        // A spawn failure (e.g. ENOENT): no exit was ever reported.
+        child.on('error', (err) => {
+          untrackGroup?.()
+          finish(spawnExit(err.message))
+        })
+        child.on('exit', (code, signal) => {
+          // The leader is gone but the group may not be: stay registered until
+          // no member is left, so a signal to the host still reaches the rest.
+          // Unless `kill()` is stopping it, the host's exit leaves it running.
+          if (untrackGroup !== undefined) {
+            if (sent.size === 0) settleGroup(pid)
+            releaseWhenEmpty(pid, untrackGroup)
+          }
+          finish({
+            exitCode: code ?? 1,
+            signal,
+            ...(code === null
+              ? {
+                  neverExited: true as const,
+                  reason:
+                    signal !== null && sent.has(signal) ? ('abort' as const) : ('signal' as const),
+                }
+              : {}),
+          })
+        })
+      })
+
+      return {
+        pid,
+        kill(signal: NodeJS.Signals | number = 'SIGTERM'): void {
+          if (pid === -1) return
+          try {
+            // A negative pid signals the whole process group — see
+            // `processGroup`'s doc above. The direct child goes through
+            // `child.kill`, which does nothing once the child has been
+            // reaped, so a reused pid is never signalled.
+            const delivered = group ? process.kill(-pid, signal) : child.kill(signal)
+            const name = typeof signal === 'number' ? signalName(signal) : signal
+            if (delivered && name !== undefined) sent.add(name)
+          } catch {
+            // Already gone — nothing to reap.
+          }
+        },
+        exited,
+      }
+    },
+  }
+}
+
+/**
+ * Stop a managed process: send `SIGTERM`, wait up to `graceMs` for it to
+ * exit, then send `SIGKILL`. A plain `kill()` sends one signal, so a process
+ * that ignores `SIGTERM` would leave `await handle.exited` waiting forever.
+ *
+ * Works with any {@link ManagedProcessHandle}, fakes included. It waits for
+ * the handle's own process only: with `processGroup`, a group member that
+ * outlives the leader is not sent `SIGKILL`.
+ *
+ * @param handle - The process to stop.
+ * @param opts - `graceMs`: how long to wait after `SIGTERM`. Default `5_000`.
+ * `0` sends `SIGKILL` right after `SIGTERM`; `Infinity` never sends it. A
+ * value above 2^31 - 1, the largest timer delay, is clamped to it. A
+ * negative value or `NaN` rejects with `RangeError`, a non-number with
+ * `TypeError`.
+ * @returns How the process ended. `reason` is `'abort'` when one of the two
+ * signals ended it.
+ *
+ * @example
+ * ```ts
+ * const server = managedProcessRunner('node').run(['server.js'], { cwd: '.' })
+ * const exit = await stopProcess(server, { graceMs: 2_000 })
+ * ```
+ *
+ * @experimental
+ */
+export async function stopProcess(
+  handle: ManagedProcessHandle,
+  opts: { graceMs?: number | undefined } = {},
+): Promise<ManagedProcessExit> {
+  const graceMs = timerMs('graceMs', opts.graceMs ?? 5_000, 'zero')
+  handle.kill()
+  if (graceMs === undefined) return handle.exited
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const grace = new Promise<undefined>((resolve) => {
+    timer = setTimeout(resolve, graceMs, undefined)
+  })
+  const exit = await Promise.race([handle.exited, grace])
+  clearTimeout(timer)
+  if (exit !== undefined) return exit
+  handle.kill('SIGKILL')
+  return handle.exited
+}
+
+/** The exit of a `processGroup` run refused because signal forwarding is stopping the host. */
+function refusedExit(error: string): ManagedProcessExit {
+  return { exitCode: 1, signal: null, neverExited: true, reason: 'abort', error }
+}
+
+/** The exit of a process that never started. */
+function spawnExit(error: string): ManagedProcessExit {
+  return { exitCode: 1, signal: null, neverExited: true, reason: 'spawn', error }
+}
+
+/** The name of signal number `n`, or `undefined` for 0 (a probe) and unknown numbers. */
+export function signalName(n: number): NodeJS.Signals | undefined {
+  for (const [name, value] of Object.entries(constants.signals)) {
+    if (value === n) return name as NodeJS.Signals
+  }
+  return undefined
+}

package/quote.ts

@@ -0,0 +1,31 @@
+/**
+ * POSIX shell quoting, for a command line printed for a person to paste or
+ * passed to `sh -c`. The argv runners never need it: they pass argv straight
+ * to the binary.
+ */
+
+/** Characters no POSIX shell treats specially. Same set as Python's `shlex.quote`. */
+const INERT = /^[A-Za-z0-9_@%+=:,./-]+$/
+
+/**
+ * `word` as one shell word: unquoted when it holds only characters no POSIX
+ * shell treats specially (letters, digits and `_@%+=:,./-`), single-quoted
+ * otherwise.
+ */
+export function shellQuote(word: string): string {
+  if (INERT.test(word)) return word
+  return quoted(word)
+}
+
+/**
+ * `argv` as one shell command line. A first word containing `=` is always
+ * quoted: bare, the shell would read it as a variable assignment, not a
+ * command.
+ */
+export function shellJoin(argv: readonly string[]): string {
+  return argv.map((w, i) => (i === 0 && w.includes('=') ? quoted(w) : shellQuote(w))).join(' ')
+}
+
+function quoted(word: string): string {
+  return `'${word.replaceAll("'", `'\\''`)}'`
+}