Skip to content
sdlc

Injectable subprocess seam

State: open/verified · Kind: module · Audience: system

Summary

Section titled “Summary”
  • One injectable run-and-capture contract for shelling out to external binaries, in a sync and an async door, so production wires a real spawn while tests inject a fake.
  • Neither door throws on command failure by default: a missing binary, a timeout kill, or an abort degrades to a non-zero exitCode rather than an exception.

Statement

Section titled “Statement”

@sksizer/command-seam is the one contract every TypeScript call site in the repo uses to run and capture an external command’s output, replacing raw child_process spawns. It exposes a synchronous door (spawnRunner/runChecked) for one-shot CLI calls and an asynchronous door (spawnRunnerAsync/runCheckedAsync) for long-lived processes and concurrent fan-out, sharing one CommandResult/CommandRunOptions/CommandFailed vocabulary so a caller can move between them without relearning the contract. solutions/ontological/lib/util/command.ts re-exports it as the app’s single import point, and it underlies @sksizer/easy-git, @sksizer/easy-gh, @sksizer/detect-runners, and packages/ts/repo-cleaner.

What it provides

Section titled “What it provides”
  • A CommandRunner/AsyncCommandRunner interface that decouples ‘shell out’ from the code that needs it, so tests inject fakes instead of touching the real process.
  • A hard, in-process timeoutMs cap enforced with an explicit timer and SIGKILL, immune to a killed child’s surviving grandchild holding stdio pipes open.
  • Failure flattened into CommandResult/CommandFailed rather than thrown, with neverExited distinguishing the seam’s own stand-in exit code from the command’s real one.
  • asAsync(syncRunner) to view a sync runner through the async door so one recording fake serves both test suites.

Underlying implementation

Section titled “Underlying implementation”
  • packages/ts/command-seam (published as @sksizer/command-seam)
  • solutions/ontological/lib/util/command.ts (single re-export point for the app)

Locations

Section titled “Locations”
  • packages/ts/command-seam/
  • packages/ts/command-seam/sync.ts
  • packages/ts/command-seam/async.ts
  • solutions/ontological/lib/util/command.ts

← Back to Capabilities