@osdlc/command-seam 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.5.0
+
+### Minor Changes
+
+- 2f3fc7c: `CommandFailed` now names the program that failed, and the sync runner flags output it stopped reading early.
+  
+  - `CommandFailed.message` includes the binary: `command failed (exit 1): git nope` instead of `command failed (exit 1): nope`. The new `binary` field holds it, and the constructor takes it as an optional third argument. `runChecked` and `runCheckedAsync` read it from the runner's new optional `binary` property. `spawnRunner`, `spawnRunnerAsync`, `asAsync` and `withDefaults` runners have it. A fake runner without `binary` keeps the old argv-only message. ([#231](https://github.com/osdlc/osdlc/issues/231))
+  - `CommandResult` has a new `outputIncomplete` flag. The sync runner sets it when the child exited but a process it started still held stdout or stderr open at `timeoutMs`. That run used to look like a success with a stray `ETIMEDOUT` in `error`. A child that passes the output cap but exits before the runner's kill lands gets the flag too, on Node or Bun. The `bun test` capture path never sets it. `exitCode` stays the child's own and `reason` stays absent, so `ran` and `runChecked` still count the run as a success. Check `outputIncomplete` when the output must be whole. ([#232](https://github.com/osdlc/osdlc/issues/232))
+  - **Breaking:** `CommandFailed.message` now starts with the binary, so code that matches on the message text sees a different string. `CommandRunner` and `AsyncCommandRunner` gain an optional public `readonly binary?: string` member, so a class that implements one of them with a private or non-string `binary` field no longer type-checks. Make the field public and a string, or rename it.
+- 2f3fc7c: Add `which(binary, opts?)`, experimental: the absolute path a spawn of `binary` would run, or `undefined`, without running it. It uses the runners' lookup rules: a name with a `/` resolves against `cwd`, a bare name is searched on `PATH`, and a match must be an executable file. `opts` takes `cwd` and `env` (merged over the parent's, as the runners take it), typed `WhichOptions`. ([#236](https://github.com/osdlc/osdlc/issues/236))
+
+## 0.4.1
+
+### Patch Changes
+
+- 4fa373f: The npm package no longer contains `smoke.mjs`. It was a check for this
+  repository's CI, not part of the API.
+
 ## 0.4.0
 
 ### Minor Changes

package/CONTRIBUTING.md

@@ -30,8 +30,9 @@ pnpm test
 ```
 
 Build before testing: the examples import the package by name, and under Node
-that name resolves to `dist/`. After a build, `pnpm run smoke` runs a short
-check of the built package under Node.
+that name resolves to `dist/`. After a build, `pnpm run smoke` runs
+`tests/smoke.mjs`, a short check of the built package under Node. It is not
+published.
 
 Other checks:
 

package/README.md

@@ -93,7 +93,7 @@ try {
   of arguments, without the binary name. The binary is fixed when you create
   the runner.
 - **Result**: what a capture runner returns: `exitCode`, `stdout`, `stderr`,
-  `neverExited`, `reason`, `signal` and `error`.
+  `neverExited`, `reason`, `signal`, `outputIncomplete` and `error`.
 - **`neverExited`**: `true` when the command never reported an exit status.
   The spawn failed, a timeout or abort killed it, a signal ended it, or the
   sync runner killed it at the output cap.
@@ -106,6 +106,10 @@ try {
   runner's 256 MB output cap). `signal` names the signal when the runner
   knows it. A timeout may pass on a retry; a spawn failure or the output cap
   will not.
+- **`outputIncomplete`**: `true` when the child exited but the runner stopped
+  reading its output early, so `stdout` and `stderr` may be cut short. The
+  exit code is real and `reason` is absent. See "`error` can come with a real
+  exit code" under Behaviour.
 - **`error`**: the runner's own message, such as a spawn error or
   `timed out after 500ms`. It is never copied into `stderr`, which holds only
   what the child wrote. `failureText` and `CommandFailed` read `error` when
@@ -345,6 +349,27 @@ const user = runJson<{ login: string }>(gh, ['api', 'user'], { env: { GH_HOST: '
 console.log(head, user.ok && user.value.login)
 ```
 
+## Finding a binary
+
+`which(binary, opts?)` returns the absolute path a spawn of `binary` would
+run, or `undefined`, without running anything. Use it to pick a tool by what
+is installed, where probing with `--version` is slow or has side effects.
+
+```ts
+import { which } from '@osdlc/command-seam'
+
+const harnesses = ['codex', 'claude', 'cursor-agent'].filter((b) => which(b) !== undefined)
+```
+
+It looks a binary up the way the runners' spawn does: a name with a `/` is
+resolved against `cwd`, a bare name is searched on `PATH`, and a match must
+be an executable file. `opts` takes `cwd` (default `process.cwd()`) and
+`env`, merged over the parent's as the runners take it, so
+`which('tool', { env: { PATH: binDir } })` checks a test's own `PATH`.
+An empty `PATH` entry means `cwd`, as it does for Node's spawn. Bun's spawn
+skips empty entries, so under Bun `which` can find a binary there that a
+spawn would not.
+
 ## Reading results
 
 Small helpers that never throw for a failed command (a programmer error,
@@ -411,14 +436,19 @@ else if (checked.reason === 'invalid') console.error(checked.message, checked.ca
 
 ## Reporting failures
 
-`CommandFailed` carries `argv` and the full `result`. Its `message` is
-`command failed (exit N): <argv>`, with argv quoted by `shellJoin`, then the
+`CommandFailed` carries `binary`, `argv` and the full `result`. Its `message`
+is `command failed (exit N): <binary> <argv>`, quoted by `shellJoin`, then the
 stderr, or the runner's `error` when the child wrote no stderr. It never
 includes stdout. Some commands explain a failure on stdout instead, such as a
 git hook that rejects a commit. `e.detail` joins both
 streams, trimmed, and drops empty ones: it is
 `failureText(e.result, { both: true })`. Show `detail` to a person.
 
+`runChecked` and `runCheckedAsync` take the binary from the runner's
+`binary` property, which `spawnRunner`, `spawnRunnerAsync`, `asAsync` and
+`withDefaults` runners have. A fake runner may leave it out; the message then
+shows the argv alone and `e.binary` is `undefined`.
+
 The message carries the full argv, so it reaches error logs and crash
 reports. Do not pass a secret, such as a token in a URL, as an argument:
 pass it through `env` or `input`.
@@ -572,6 +602,17 @@ console.log(await server.exited) // { exitCode: 0, signal: null }
   the output captured so far. The sync runner also sets `signal: 'SIGKILL'`.
   Both runners set `error`: the async runner's is `timed out after <N>ms`,
   the sync runner's is spawnSync's `ETIMEDOUT` message.
+- The sync capture runners wait for the output pipes to close, not only for
+  the child to exit. If the child exits but a process it started still holds
+  stdout or stderr, the run waits until `timeoutMs` (or, without one, until
+  that process exits). The result then has the child's own `exitCode`,
+  `outputIncomplete: true`, no `reason`, and spawnSync's `ETIMEDOUT` message
+  in `error`. Output written after the deadline is lost, and the process
+  keeps running. A run that may start background work belongs on an async
+  runner with `processGroup: true`. Under `bun test` the sync runner captures
+  through temp files instead of pipes (see Known issue: `bun test`), so it
+  returns as soon as the child exits: later output is lost without
+  `outputIncomplete` or `error`, and a test there never sees the flag.
 - The sync runners (`spawnRunner`, `runShell`, `shellRunner`) and
   `streamRunner` kill only the direct child on timeout. Processes it started
   keep running, and these runners have no option to change that. The async
@@ -614,13 +655,21 @@ console.log(await server.exited) // { exitCode: 0, signal: null }
   written, the result keeps the child's exit code. The async runner and the
   sync runner on Node put the write error in `error`. The sync runner under
   Bun does not report it.
-- **`error` can come with a real exit code.** After a failed stdin write, or
-  a child that exits right at the output cap under Bun, `exitCode` is the
-  child's own, `reason` is absent and only `error` says what went wrong.
+- **`error` can come with a real exit code.** `exitCode` is then the child's
+  own and `reason` is absent. Three cases:
+  - a failed stdin write: only `error` says what went wrong;
+  - a sync run whose child exited while a process it started held the output
+    pipes past `timeoutMs` (see Timeouts and cancellation): `outputIncomplete: true`;
+  - a child that passes the output cap but exits before the runner's kill
+    lands, on Node or Bun: `outputIncomplete: true`.
+
+  `ran` and `runChecked` go by the exit code, so they treat the last two as
+  success. Check `outputIncomplete` when the output must be whole.
 - **Output is text.** Captured output is decoded as UTF-8. The sync pipe
   path caps each stream at 256 MB and usually kills a child that passes it,
-  with `reason: 'output'`. Under Bun, a child that exits right at the cap
-  keeps its exit code and gets only `error`. The `bun test` capture path and
+  with `reason: 'output'`. A child that passes the cap but exits before the
+  kill lands keeps its exit code and gets `outputIncomplete: true` and
+  `error`. The `bun test` capture path and
   the async runner have no cap.
 
 ## Known issue: `bun test`
@@ -657,6 +706,7 @@ The experimental exports:
 - `firstLine`, `stderrOrError`
 - `runJson`, `runJsonAsync`, `parseJsonResult`, `JsonRun`, `RunJsonOptions`
 - `withDefaults`, `DefaultedRunner`
+- `which`, `WhichOptions`
 - `stopProcess`
 - `installGroupSignalForwarding`, `GroupSignalForwardingOptions`
 - `liveProcessGroups`, `forwardedSignal`, `forwardedExitCode`
@@ -678,9 +728,9 @@ are settled, and Windows support has landed, if that is feasible.
 | `mapFailed`, `mapFailedAsync`                                   | function  | Rethrow a `CommandFailed` as another error                     |
 | `catchFailed`, `catchFailedAsync`                               | function  | Turn a `CommandFailed` into a value                            |
 | `asAsync`                                                       | function  | Wrap a sync runner as an async one                             |
-| `CommandFailed`                                                 | class     | Error with `argv`, `result` and `detail`; `message` shows argv |
-| `CommandRunner`, `AsyncCommandRunner`                           | interface | Capture runner contracts                                       |
-| `CommandResult`                                                 | interface | `exitCode`, `stdout`, `stderr`, `neverExited`, `reason`, `signal`, `error` |
+| `CommandFailed`                                                 | class     | Error with `binary`, `argv`, `result` and `detail`; `message` shows the command |
+| `CommandRunner`, `AsyncCommandRunner`                           | interface | Capture runner contracts; `binary` names the program          |
+| `CommandResult`                                                 | interface | `exitCode`, `stdout`, `stderr`, `neverExited`, `reason`, `signal`, `outputIncomplete`, `error` |
 | `NeverExitedReason`                                             | type      | `'spawn' \| 'timeout' \| 'abort' \| 'signal' \| 'output'`       |
 | `CommandRunOptions`, `AsyncCommandRunOptions`                   | interface | `cwd`, `timeoutMs`, `input`, `env`; async adds `signal`, `onSpawn`, `processGroup` |
 | `EnvOverrides`                                                  | type      | `Record<string, string \| undefined>`                          |
@@ -703,6 +753,8 @@ are settled, and Windows support has landed, if that is feasible.
 | `GroupSignalForwardingOptions`                                  | interface | `signals`, `graceMs`, `exit`                                   |
 | `withDefaults`                                                  | function  | Bind default options to any runner                             |
 | `DefaultedRunner`                                               | interface | The runner `withDefaults` returns                              |
+| `which`                                                         | function  | The path a spawn of a binary would run, without running it     |
+| `WhichOptions`                                                  | interface | `cwd`, `env`                                                   |
 | `fakeRunner`                                                    | function  | `/testing`: a `CommandRunner` that answers from a table        |
 | `fakeNeverExited`                                               | function  | `/testing`: a fake answer for a run that never exited          |
 | `fakeProcess`                                                   | function  | `/testing`: a `ManagedProcessHandle` the test ends by hand     |

package/async.ts

@@ -67,6 +67,8 @@ export interface AsyncCommandRunOptions extends CommandRunOptions {
 
 /** The async form of {@link CommandRunner}: `run` returns a promise. */
 export interface AsyncCommandRunner {
+  /** The binary this runner runs, when it has one. See `CommandRunner.binary`. */
+  readonly binary?: string | undefined
   /**
    * Run the binary with `argv` (without the binary name). The promise never
    * rejects for a failed command: a non-zero exit, a missing binary, a
@@ -141,6 +143,7 @@ const ABORT_KILL_GRACE_MS = 1000
  */
 export function spawnRunnerAsync(binary: string): AsyncCommandRunner {
   return {
+    binary,
     run(argv: string[], opts: AsyncCommandRunOptions): Promise<CommandResult> {
       return new Promise((resolve) => {
         // Inside the executor, so an invalid timeoutMs (or a throw from spawn)
@@ -391,17 +394,23 @@ export async function runCheckedAsync(
   opts: AsyncCommandRunOptions,
 ): Promise<CommandResult>
 export async function runCheckedAsync<P extends unknown[]>(
-  runner: { run(argv: string[], ...opts: P): Promise<CommandResult> },
+  runner: {
+    readonly binary?: string | undefined
+    run(argv: string[], ...opts: P): Promise<CommandResult>
+  },
   argv: string[],
   ...opts: NoInfer<P>
 ): Promise<CommandResult>
 export async function runCheckedAsync(
-  runner: { run(argv: string[], ...opts: unknown[]): Promise<CommandResult> },
+  runner: {
+    readonly binary?: string | undefined
+    run(argv: string[], ...opts: unknown[]): Promise<CommandResult>
+  },
   argv: string[],
   ...opts: unknown[]
 ): Promise<CommandResult> {
   const result = await runner.run(argv, ...opts)
-  if (result.exitCode !== 0) throw new CommandFailed(argv, result)
+  if (result.exitCode !== 0) throw new CommandFailed(argv, result, runner.binary)
   return result
 }
 
@@ -416,6 +425,7 @@ export async function runCheckedAsync(
  */
 export function asAsync(runner: CommandRunner): AsyncCommandRunner {
   return {
+    ...(runner.binary === undefined ? {} : { binary: runner.binary }),
     run: async (argv, opts) => runner.run(argv, opts),
   }
 }

package/defaults.ts

@@ -24,6 +24,8 @@ export type DefaultedOptions<O, K extends keyof O> = Omit<O, K> & Partial<Pick<O
  * @experimental
  */
 export interface DefaultedRunner<Rn extends AnyRunner, K extends keyof RunOptions<Rn> = never> {
+  /** The wrapped runner's `binary`, when it has one. */
+  readonly binary?: string | undefined
   run(
     arg: Parameters<Rn['run']>[0],
     ...opts: {} extends DefaultedOptions<RunOptions<Rn>, K>
@@ -62,8 +64,12 @@ export function withDefaults<Rn extends AnyRunner, K extends keyof RunOptions<Rn
   defaults: Pick<RunOptions<Rn>, K> & Partial<RunOptions<Rn>>,
 ): DefaultedRunner<Rn, K> {
   const bound: Record<string, unknown> = { ...defaults }
-  const target = runner as unknown as { run(arg: unknown, opts: unknown): ReturnType<Rn['run']> }
+  const target = runner as unknown as {
+    binary?: unknown
+    run(arg: unknown, opts: unknown): ReturnType<Rn['run']>
+  }
   return {
+    ...(typeof target.binary === 'string' ? { binary: target.binary } : {}),
     run(arg: unknown, opts?: object) {
       const merged = { ...bound }
       for (const [key, value] of Object.entries(opts ?? {})) {

package/dist/async.d.ts

@@ -45,6 +45,8 @@ export interface AsyncCommandRunOptions extends CommandRunOptions {
 }
 /** The async form of {@link CommandRunner}: `run` returns a promise. */
 export interface AsyncCommandRunner {
+    /** The binary this runner runs, when it has one. See `CommandRunner.binary`. */
+    readonly binary?: string | undefined;
     /**
      * Run the binary with `argv` (without the binary name). The promise never
      * rejects for a failed command: a non-zero exit, a missing binary, a
@@ -108,6 +110,7 @@ export declare function spawnRunnerAsync(binary: string): AsyncCommandRunner;
  */
 export declare function runCheckedAsync(runner: AsyncCommandRunner, argv: string[], opts: AsyncCommandRunOptions): Promise<CommandResult>;
 export declare function runCheckedAsync<P extends unknown[]>(runner: {
+    readonly binary?: string | undefined;
     run(argv: string[], ...opts: P): Promise<CommandResult>;
 }, argv: string[], ...opts: NoInfer<P>): Promise<CommandResult>;
 /**

package/dist/async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../async.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH,OAAO,EACL,aAAa,EAKb,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACvB,MAAM,WAAW,CAAA;AAElB,wFAAwF;AACxF,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB;IAC/D;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;IAChC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;IAC7C;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CACnC;AAED,wEAAwE;AACxE,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CAC1E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,kBAAkB,GAAG,SAAS,GACxC,kBAAkB,CAEpB;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,CA2OnE;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAAA;AACzB,wBAAsB,eAAe,CAAC,CAAC,SAAS,OAAO,EAAE,EACvD,MAAM,EAAE;IAAE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CAAE,EACnE,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAClB,OAAO,CAAC,aAAa,CAAC,CAAA;AAWzB;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,kBAAkB,CAIjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GACxD,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAClD,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAOhB"}
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../async.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH,OAAO,EACL,aAAa,EAKb,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACvB,MAAM,WAAW,CAAA;AAElB,wFAAwF;AACxF,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB;IAC/D;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;IAChC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;IAC7C;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CACnC;AAED,wEAAwE;AACxE,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC;;;;;;OAMG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CAC1E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,kBAAkB,GAAG,SAAS,GACxC,kBAAkB,CAEpB;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,CA4OnE;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAAA;AACzB,wBAAsB,eAAe,CAAC,CAAC,SAAS,OAAO,EAAE,EACvD,MAAM,EAAE;IACN,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CACxD,EACD,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAClB,OAAO,CAAC,aAAa,CAAC,CAAA;AAczB;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,kBAAkB,CAKjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GACxD,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAClD,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAOhB"}

package/dist/async.js

@@ -69,6 +69,7 @@ const ABORT_KILL_GRACE_MS = 1000;
  */
 export function spawnRunnerAsync(binary) {
     return {
+        binary,
         run(argv, opts) {
             return new Promise((resolve) => {
                 // Inside the executor, so an invalid timeoutMs (or a throw from spawn)
@@ -308,7 +309,7 @@ export function spawnRunnerAsync(binary) {
 export async function runCheckedAsync(runner, argv, ...opts) {
     const result = await runner.run(argv, ...opts);
     if (result.exitCode !== 0)
-        throw new CommandFailed(argv, result);
+        throw new CommandFailed(argv, result, runner.binary);
     return result;
 }
 /**
@@ -322,6 +323,7 @@ export async function runCheckedAsync(runner, argv, ...opts) {
  */
 export function asAsync(runner) {
     return {
+        ...(runner.binary === undefined ? {} : { binary: runner.binary }),
         run: async (argv, opts) => runner.run(argv, opts),
     };
 }

package/dist/defaults.d.ts

@@ -20,6 +20,8 @@ export type DefaultedOptions<O, K extends keyof O> = Omit<O, K> & Partial<Pick<O
  * @experimental
  */
 export interface DefaultedRunner<Rn extends AnyRunner, K extends keyof RunOptions<Rn> = never> {
+    /** The wrapped runner's `binary`, when it has one. */
+    readonly binary?: string | undefined;
     run(arg: Parameters<Rn['run']>[0], ...opts: {} extends DefaultedOptions<RunOptions<Rn>, K> ? [opts?: DefaultedOptions<RunOptions<Rn>, K>] : [opts: DefaultedOptions<RunOptions<Rn>, K>]): ReturnType<Rn['run']>;
 }
 /**

package/dist/defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../defaults.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,kFAAkF;AAClF,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO,CAAA;CACtC;AAED,uCAAuC;AACvC,KAAK,UAAU,CAAC,EAAE,SAAS,SAAS,IAAI,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAEhE,oFAAoF;AACpF,MAAM,MAAM,gBAAgB,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AAErF;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC,SAAS,MAAM,UAAU,CAAC,EAAE,CAAC,GAAG,KAAK;IAC3F,GAAG,CACD,GAAG,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAC7B,GAAG,IAAI,EAAE,EAAE,SAAS,gBAAgB,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACnD,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAC5C,CAAC,IAAI,EAAE,gBAAgB,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAC9C,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC,SAAS,MAAM,UAAU,CAAC,EAAE,CAAC,GAAG,KAAK,EACvF,MAAM,EAAE,EAAE,EACV,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,GAC1D,eAAe,CAAC,EAAE,EAAE,CAAC,CAAC,CAgBxB"}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../defaults.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,kFAAkF;AAClF,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO,CAAA;CACtC;AAED,uCAAuC;AACvC,KAAK,UAAU,CAAC,EAAE,SAAS,SAAS,IAAI,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAEhE,oFAAoF;AACpF,MAAM,MAAM,gBAAgB,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AAErF;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC,SAAS,MAAM,UAAU,CAAC,EAAE,CAAC,GAAG,KAAK;IAC3F,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,GAAG,CACD,GAAG,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAC7B,GAAG,IAAI,EAAE,EAAE,SAAS,gBAAgB,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACnD,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAC5C,CAAC,IAAI,EAAE,gBAAgB,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAC9C,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC,SAAS,MAAM,UAAU,CAAC,EAAE,CAAC,GAAG,KAAK,EACvF,MAAM,EAAE,EAAE,EACV,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,GAC1D,eAAe,CAAC,EAAE,EAAE,CAAC,CAAC,CAoBxB"}

package/dist/defaults.js

@@ -32,6 +32,7 @@ export function withDefaults(runner, defaults) {
     const bound = { ...defaults };
     const target = runner;
     return {
+        ...(typeof target.binary === 'string' ? { binary: target.binary } : {}),
         run(arg, opts) {
             const merged = { ...bound };
             for (const [key, value] of Object.entries(opts ?? {})) {

package/dist/index.d.ts

@@ -13,6 +13,7 @@
  *   without waiting for it to finish. `stopProcess` stops it with a grace
  *   period.
  * - `withDefaults` binds default options to any of them.
+ * - `which` finds a binary on `PATH` without running it.
  *
  * The capture runners share {@link CommandResult}, {@link CommandRunOptions}
  * and {@link CommandFailed}, so one `instanceof CommandFailed` check covers
@@ -27,4 +28,5 @@ export { streamRunner, type StreamRunner, type StreamRunOptions, type StreamResu
 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';
+export { which, type WhichOptions } from './which.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EACL,WAAW,EACX,aAAa,EACb,SAAS,EACT,aAAa,EACb,UAAU,EACV,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,iBAAiB,GACvB,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,OAAO,EACP,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,GAC5B,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,WAAW,EACX,SAAS,EACT,eAAe,EACf,GAAG,EACH,OAAO,EACP,YAAY,EACZ,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,OAAO,EACZ,KAAK,cAAc,GACpB,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAElD,OAAO,EACL,QAAQ,EACR,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,YAAY,EACZ,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,4BAA4B,EAC5B,iBAAiB,EACjB,KAAK,4BAA4B,GAClC,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,WAAW,EACX,aAAa,EACb,SAAS,EACT,aAAa,EACb,UAAU,EACV,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,iBAAiB,GACvB,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,OAAO,EACP,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,GAC5B,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,WAAW,EACX,SAAS,EACT,eAAe,EACf,GAAG,EACH,OAAO,EACP,YAAY,EACZ,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,OAAO,EACZ,KAAK,cAAc,GACpB,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAElD,OAAO,EACL,QAAQ,EACR,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,YAAY,EACZ,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,4BAA4B,EAC5B,iBAAiB,EACjB,KAAK,4BAA4B,GAClC,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAElE,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -13,6 +13,7 @@
  *   without waiting for it to finish. `stopProcess` stops it with a grace
  *   period.
  * - `withDefaults` binds default options to any of them.
+ * - `which` finds a binary on `PATH` without running it.
  *
  * The capture runners share {@link CommandResult}, {@link CommandRunOptions}
  * and {@link CommandFailed}, so one `instanceof CommandFailed` check covers
@@ -27,3 +28,4 @@ export { streamRunner, } from "./stream.js";
 export { managedProcessRunner, stopProcess, } from "./process.js";
 export { forwardedExitCode, forwardedSignal, installGroupSignalForwarding, liveProcessGroups, } from "./groups.js";
 export { withDefaults } from "./defaults.js";
+export { which } from "./which.js";

package/dist/sync.d.ts

@@ -46,6 +46,26 @@ export interface CommandResult {
      * it leaves this unset there.
      */
     signal?: NodeJS.Signals | undefined;
+    /**
+     * `true` when the child exited but the runner stopped reading its output
+     * early, so `stdout` and `stderr` may be cut short. `exitCode` is the
+     * child's own, `neverExited` and `reason` are absent, and `error` says why.
+     * Absent otherwise. Two cases, both on the sync capture runner:
+     *
+     * - The child exited, but a process it started (`cmd &`, a daemon, a
+     *   postinstall script) still held stdout or stderr open when `timeoutMs`
+     *   ran out. Anything that process wrote after the deadline is lost, and it
+     *   keeps running. Without `timeoutMs` the run waits for it to exit.
+     * - The child passed the 256 MB output cap but exited before the runner's
+     *   kill landed, on Node or Bun.
+     *
+     * The `bun test` capture path writes output to files and never waits on a
+     * held pipe, so it never sets this flag.
+     *
+     * `ran` and `runChecked` go by the exit code alone, so they still count
+     * such a run as a success. Check this flag when the output must be whole.
+     */
+    outputIncomplete?: boolean | undefined;
     /**
      * The runner's own message, when it has one: a failed spawn, a timeout, an
      * abort, an `onSpawn` that threw, a refused `processGroup` run, the output
@@ -53,9 +73,8 @@ export interface CommandResult {
      * `stderr`. Absent otherwise.
      *
      * It can also be set when the child did exit: a failed stdin write (Bun's
-     * `spawnSync` does not report one), or, under Bun, a child that exits right
-     * at the output cap. `exitCode` is then the child's own and `reason` is
-     * absent.
+     * `spawnSync` does not report one), or a run with `outputIncomplete` set.
+     * `exitCode` is then the child's own and `reason` is absent.
      */
     error?: string | undefined;
 }
@@ -121,6 +140,12 @@ export type EnvOverrides = Record<string, string | undefined>;
  * ```
  */
 export interface CommandRunner {
+    /**
+     * The binary this runner runs, when it has one. `runChecked` puts it in
+     * `CommandFailed`, so the message names the program. `spawnRunner` sets
+     * it; a fake may leave it out.
+     */
+    readonly binary?: string | undefined;
     /**
      * Run the binary with `argv` (the arguments, without the binary name) and
      * wait for it to exit. Never throws for a failed command: a non-zero exit,
@@ -196,17 +221,20 @@ export declare function syncStop(proc: {
 };
 /**
  * Thrown by {@link runChecked} and `runCheckedAsync` on a non-zero exit.
- * Carries the argv and the full {@link CommandResult}, so a caller can report
- * the output without running the command again.
+ * Carries the binary, the argv and the full {@link CommandResult}, so a
+ * caller can report the output without running the command again.
  *
- * `message` is `command failed (exit N): <argv>`, with argv quoted by
+ * `message` is `command failed (exit N): <binary> <argv>`, quoted by
  * `shellJoin`, followed on a new line by the trimmed stderr, or the trimmed
  * `error` when stderr is empty. Nothing follows when both are empty. The argv
  * appears in full, so error logs and reports carry it: pass secrets through
  * `env` or `input`, not argv. Use `detail` to show a person
- * why it failed.
+ * why it failed. The binary is left out when it is not known, as for a fake
+ * runner without `binary`.
  */
 export declare class CommandFailed extends Error {
+    /** The binary that ran, when the runner reports one (see `CommandRunner.binary`). */
+    readonly binary: string | undefined;
     /** The arguments the command ran with, without the binary name. */
     readonly argv: string[];
     /** The full result of the failed run. */
@@ -231,8 +259,9 @@ export declare class CommandFailed extends Error {
     /**
      * @param argv - The arguments the command ran with.
      * @param result - The result of the failed run.
+     * @param binary - The binary that ran, when known.
      */
-    constructor(argv: string[], result: CommandResult);
+    constructor(argv: string[], result: CommandResult, binary?: string | undefined);
 }
 /**
  * Run a command and throw if it fails. Use it where the only sensible
@@ -258,6 +287,7 @@ export declare class CommandFailed extends Error {
  */
 export declare function runChecked(runner: CommandRunner, argv: string[], opts: CommandRunOptions): CommandResult;
 export declare function runChecked<P extends unknown[]>(runner: {
+    readonly binary?: string | undefined;
     run(argv: string[], ...opts: P): CommandResult;
 }, argv: string[], ...opts: NoInfer<P>): CommandResult;
 /**
@@ -283,6 +313,15 @@ export declare function mapFailed<T>(fn: () => T, mapper: (failed: CommandFailed
  * @returns What `fn` returns, or what `onFailed` returns.
  */
 export declare function catchFailed<T, R>(fn: () => T, onFailed: (failed: CommandFailed) => R): T | R;
+/**
+ * Folds a finished `spawnSync` into a {@link CommandResult}. Exported for
+ * tests.
+ */
+export declare function fromSpawnSync(proc: {
+    status: number | null;
+    signal: NodeJS.Signals | null;
+    error?: Error | undefined;
+}, stdout: string, stderr: string): CommandResult;
 /**
  * The injected runner when there is one, else `spawnRunner(binary)`.
  *

package/dist/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../sync.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../sync.ts"],"names":[],"mappings":"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"}

package/dist/sync.js

@@ -11,11 +11,12 @@
  *     exit, for callers whose only sensible response to failure is to stop.
  */
 import { spawnSync } from 'node:child_process';
-import { accessSync, constants, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { delimiter, join, resolve } from 'node:path';
+import { join } from 'node:path';
 import { shellJoin } from "./quote.js";
 import { failureText, stderrOrError } from "./result.js";
+import { which } from "./which.js";
 /**
  * `{ env }`: `process.env` merged with `opts.env`, minus any key whose
  * override is `undefined`. Always an explicit object built from the current
@@ -147,17 +148,20 @@ export function syncStop(proc) {
 }
 /**
  * Thrown by {@link runChecked} and `runCheckedAsync` on a non-zero exit.
- * Carries the argv and the full {@link CommandResult}, so a caller can report
- * the output without running the command again.
+ * Carries the binary, the argv and the full {@link CommandResult}, so a
+ * caller can report the output without running the command again.
  *
- * `message` is `command failed (exit N): <argv>`, with argv quoted by
+ * `message` is `command failed (exit N): <binary> <argv>`, quoted by
  * `shellJoin`, followed on a new line by the trimmed stderr, or the trimmed
  * `error` when stderr is empty. Nothing follows when both are empty. The argv
  * appears in full, so error logs and reports carry it: pass secrets through
  * `env` or `input`, not argv. Use `detail` to show a person
- * why it failed.
+ * why it failed. The binary is left out when it is not known, as for a fake
+ * runner without `binary`.
  */
 export class CommandFailed extends Error {
+    /** The binary that ran, when the runner reports one (see `CommandRunner.binary`). */
+    binary;
     /** The arguments the command ran with, without the binary name. */
     argv;
     /** The full result of the failed run. */
@@ -184,12 +188,15 @@ export class CommandFailed extends Error {
     /**
      * @param argv - The arguments the command ran with.
      * @param result - The result of the failed run.
+     * @param binary - The binary that ran, when known.
      */
-    constructor(argv, result) {
+    constructor(argv, result, binary) {
         const stderr = stderrOrError(result);
-        super(`command failed (exit ${result.exitCode}): ${shellJoin(argv)}` +
+        const command = binary === undefined ? argv : [binary, ...argv];
+        super(`command failed (exit ${result.exitCode}): ${shellJoin(command)}` +
             (stderr ? `\n${stderr}` : ''));
         this.name = 'CommandFailed';
+        this.binary = binary;
         this.argv = argv;
         this.result = result;
     }
@@ -197,7 +204,7 @@ export class CommandFailed extends Error {
 export function runChecked(runner, argv, ...opts) {
     const result = runner.run(argv, ...opts);
     if (result.exitCode !== 0)
-        throw new CommandFailed(argv, result);
+        throw new CommandFailed(argv, result, runner.binary);
     return result;
 }
 /**
@@ -253,39 +260,26 @@ export function catchFailed(fn, onFailed) {
 // set `NODE_ENV=test`, but they run on Node and keep the pipe path below.
 const CHILD_STDIO_CORRUPTED = process.versions['bun'] !== undefined && process.env['NODE_ENV'] === 'test';
 /**
- * Whether `binary` resolves to an executable file the way a spawn would find
- * it: a name with a `/` is taken relative to `cwd`; a bare name is looked up
- * on the child's `PATH`.
+ * Folds a finished `spawnSync` into a {@link CommandResult}. Exported for
+ * tests.
  */
-function findsExecutable(binary, cwd, path) {
-    const isExecutable = (p) => {
-        try {
-            accessSync(p, constants.X_OK);
-            return statSync(p).isFile();
-        }
-        catch {
-            return false;
-        }
-    };
-    if (binary === '')
-        return false;
-    if (binary.includes('/'))
-        return isExecutable(resolve(cwd, binary));
-    return (path ?? '/usr/bin:/bin')
-        .split(delimiter)
-        .some((dir) => isExecutable(resolve(cwd, dir, binary)));
-}
-/** Folds a finished `spawnSync` into a {@link CommandResult}. */
-function fromSpawnSync(proc, stdout, stderr) {
+export function fromSpawnSync(proc, stdout, stderr) {
+    const code = proc.error?.code;
     return {
         exitCode: proc.status ?? 1,
         // Bun reports a failed spawn with `status` undefined, not null.
         ...(proc.status == null ? { neverExited: true, ...syncStop(proc) } : {}),
+        // A real status with a timeout: the child exited, but a process it started
+        // held the pipes until the deadline. With the cap: the child passed it and
+        // exited before the kill landed.
+        ...(proc.status != null && (code === 'ETIMEDOUT' || code === 'ENOBUFS')
+            ? { outputIncomplete: true }
+            : {}),
         stdout,
         stderr,
         // `proc.error` is set for a failed spawn, a timeout, the output cap, or a
-        // failed stdin write; only the first three leave `status` null (and under
-        // Bun the cap can come with a real status too). A stdin write error can
+        // failed stdin write. The first three usually leave `status` null; when
+        // they do not, `outputIncomplete` is set above. A stdin write error can
         // come with a child that did exit, so it is kept either way.
         ...(proc.error ? { error: proc.error.message } : {}),
     };
@@ -305,7 +299,7 @@ function runViaChildRedirect(binary, argv, opts, timeoutMs) {
     // the same stand-in the pipe path reports for a failed spawn. This also
     // keeps a binary named like an option (`-a`) from reaching `exec` as one,
     // unless an executable named `-a` is on PATH.
-    if (!findsExecutable(binary, opts.cwd, env['PATH'])) {
+    if (which(binary, { cwd: opts.cwd, env: { PATH: env['PATH'] } }) === undefined) {
         return spawnFailure(`spawnSync ${binary} ENOENT`);
     }
     const dir = mkdtempSync(join(tmpdir(), 'command-seam-'));
@@ -384,6 +378,7 @@ export function resolveRunner(binary, injected) {
  */
 export function spawnRunner(binary) {
     return {
+        binary,
         run(argv, opts) {
             const timeoutMs = normalizeTimeout(opts.timeoutMs);
             const cwdMessage = cwdError(`spawnSync ${binary}`, binary, argv, opts);

package/dist/which.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `which`: find a binary on `PATH` without running it, the way the runners'
+ * spawn would find it. For code that picks a tool by what is installed;
+ * running `--version` to probe is slow for some CLIs and has side effects
+ * (update checks, telemetry) for others.
+ */
+import type { EnvOverrides } from './sync.ts';
+/**
+ * Options for {@link which}.
+ *
+ * @experimental
+ */
+export interface WhichOptions {
+    /**
+     * The folder a relative path, or a relative `PATH` entry, is resolved
+     * against, as a spawn with this `cwd` would. Default `process.cwd()`.
+     */
+    cwd?: string | undefined;
+    /**
+     * Variables merged over the parent's environment, as the runners take
+     * them. Only `PATH` is read; an `undefined` value unsets it.
+     */
+    env?: EnvOverrides | undefined;
+}
+/**
+ * The absolute path of the file a spawn of `binary` would run, or
+ * `undefined` when there is none. A name with a `/` is taken relative to
+ * `cwd`; a bare name is looked up on `PATH`, first match wins. A match must be
+ * an executable file. With `PATH` unset, it searches `/usr/bin:/bin`. An
+ * empty `PATH` entry (`PATH=''`, `a::b`, a trailing `:`) means `cwd`, as it
+ * does for Node's spawn; Bun's spawn skips empty entries, so under Bun such
+ * a match may not start. POSIX only: `PATHEXT` is not read.
+ *
+ * Never throws for a missing binary, an unreadable folder or a bad `cwd`.
+ *
+ * @param binary - A name looked up on `PATH`, or a path.
+ * @param opts - `cwd` and `env`, as the runners take them.
+ * @returns The absolute path, or `undefined`.
+ * @experimental
+ *
+ * @example
+ * ```ts
+ * const harnesses = ['codex', 'claude', 'cursor-agent'].filter((b) => which(b) !== undefined)
+ * ```
+ */
+export declare function which(binary: string, opts?: WhichOptions): string | undefined;
+//# sourceMappingURL=which.d.ts.map

package/dist/which.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"which.d.ts","sourceRoot":"","sources":["../which.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAE7C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACxB;;;OAGG;IACH,GAAG,CAAC,EAAE,YAAY,GAAG,SAAS,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,MAAM,GAAG,SAAS,CAUjF"}

package/dist/which.js

@@ -0,0 +1,53 @@
+/**
+ * `which`: find a binary on `PATH` without running it, the way the runners'
+ * spawn would find it. For code that picks a tool by what is installed;
+ * running `--version` to probe is slow for some CLIs and has side effects
+ * (update checks, telemetry) for others.
+ */
+import { accessSync, constants, statSync } from 'node:fs';
+import { delimiter, resolve } from 'node:path';
+/**
+ * The absolute path of the file a spawn of `binary` would run, or
+ * `undefined` when there is none. A name with a `/` is taken relative to
+ * `cwd`; a bare name is looked up on `PATH`, first match wins. A match must be
+ * an executable file. With `PATH` unset, it searches `/usr/bin:/bin`. An
+ * empty `PATH` entry (`PATH=''`, `a::b`, a trailing `:`) means `cwd`, as it
+ * does for Node's spawn; Bun's spawn skips empty entries, so under Bun such
+ * a match may not start. POSIX only: `PATHEXT` is not read.
+ *
+ * Never throws for a missing binary, an unreadable folder or a bad `cwd`.
+ *
+ * @param binary - A name looked up on `PATH`, or a path.
+ * @param opts - `cwd` and `env`, as the runners take them.
+ * @returns The absolute path, or `undefined`.
+ * @experimental
+ *
+ * @example
+ * ```ts
+ * const harnesses = ['codex', 'claude', 'cursor-agent'].filter((b) => which(b) !== undefined)
+ * ```
+ */
+export function which(binary, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    if (binary === '')
+        return undefined;
+    if (binary.includes('/'))
+        return executable(resolve(cwd, binary));
+    const path = opts.env !== undefined && 'PATH' in opts.env ? opts.env['PATH'] : process.env['PATH'];
+    for (const dir of (path ?? '/usr/bin:/bin').split(delimiter)) {
+        const found = executable(resolve(cwd, dir, binary));
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+/** `p` when it is an executable file, else `undefined`. */
+function executable(p) {
+    try {
+        accessSync(p, constants.X_OK);
+        return statSync(p).isFile() ? p : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/index.ts

@@ -13,6 +13,7 @@
  *   without waiting for it to finish. `stopProcess` stops it with a grace
  *   period.
  * - `withDefaults` binds default options to any of them.
+ * - `which` finds a binary on `PATH` without running it.
  *
  * The capture runners share {@link CommandResult}, {@link CommandRunOptions}
  * and {@link CommandFailed}, so one `instanceof CommandFailed` check covers
@@ -96,3 +97,5 @@ export {
 } from './groups.ts'
 
 export { withDefaults, type DefaultedRunner } from './defaults.ts'
+
+export { which, type WhichOptions } from './which.ts'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/command-seam",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Injectable subprocess runner for Node: capture, stream and managed-process runners, hard timeouts, failures as results.",
   "license": "MIT",
   "author": "SK Sizer",
@@ -49,7 +49,6 @@
   },
   "files": [
     "dist/",
-    "smoke.mjs",
     "index.ts",
     "sync.ts",
     "async.ts",
@@ -60,6 +59,7 @@
     "quote.ts",
     "shell.ts",
     "defaults.ts",
+    "which.ts",
     "testing.ts",
     "README.md",
     "CHANGELOG.md",
@@ -88,7 +88,7 @@
     "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",
+    "smoke": "node tests/smoke.mjs",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "oxlint .",

package/sync.ts

@@ -12,20 +12,13 @@
  */
 
 import { spawnSync } from 'node:child_process'
-import {
-  accessSync,
-  constants,
-  mkdtempSync,
-  readFileSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from 'node:fs'
+import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { delimiter, join, resolve } from 'node:path'
+import { join } from 'node:path'
 
 import { shellJoin } from './quote.ts'
 import { failureText, stderrOrError } from './result.ts'
+import { which } from './which.ts'
 
 /** Result of running an external command through a `CommandRunner`. */
 export interface CommandResult {
@@ -63,6 +56,26 @@ export interface CommandResult {
    * it leaves this unset there.
    */
   signal?: NodeJS.Signals | undefined
+  /**
+   * `true` when the child exited but the runner stopped reading its output
+   * early, so `stdout` and `stderr` may be cut short. `exitCode` is the
+   * child's own, `neverExited` and `reason` are absent, and `error` says why.
+   * Absent otherwise. Two cases, both on the sync capture runner:
+   *
+   * - The child exited, but a process it started (`cmd &`, a daemon, a
+   *   postinstall script) still held stdout or stderr open when `timeoutMs`
+   *   ran out. Anything that process wrote after the deadline is lost, and it
+   *   keeps running. Without `timeoutMs` the run waits for it to exit.
+   * - The child passed the 256 MB output cap but exited before the runner's
+   *   kill landed, on Node or Bun.
+   *
+   * The `bun test` capture path writes output to files and never waits on a
+   * held pipe, so it never sets this flag.
+   *
+   * `ran` and `runChecked` go by the exit code alone, so they still count
+   * such a run as a success. Check this flag when the output must be whole.
+   */
+  outputIncomplete?: boolean | undefined
   /**
    * The runner's own message, when it has one: a failed spawn, a timeout, an
    * abort, an `onSpawn` that threw, a refused `processGroup` run, the output
@@ -70,9 +83,8 @@ export interface CommandResult {
    * `stderr`. Absent otherwise.
    *
    * It can also be set when the child did exit: a failed stdin write (Bun's
-   * `spawnSync` does not report one), or, under Bun, a child that exits right
-   * at the output cap. `exitCode` is then the child's own and `reason` is
-   * absent.
+   * `spawnSync` does not report one), or a run with `outputIncomplete` set.
+   * `exitCode` is then the child's own and `reason` is absent.
    */
   error?: string | undefined
 }
@@ -146,6 +158,12 @@ export type EnvOverrides = Record<string, string | undefined>
  * ```
  */
 export interface CommandRunner {
+  /**
+   * The binary this runner runs, when it has one. `runChecked` puts it in
+   * `CommandFailed`, so the message names the program. `spawnRunner` sets
+   * it; a fake may leave it out.
+   */
+  readonly binary?: string | undefined
   /**
    * Run the binary with `argv` (the arguments, without the binary name) and
    * wait for it to exit. Never throws for a failed command: a non-zero exit,
@@ -295,17 +313,20 @@ export function syncStop(proc: { error?: Error | undefined; signal: NodeJS.Signa
 
 /**
  * Thrown by {@link runChecked} and `runCheckedAsync` on a non-zero exit.
- * Carries the argv and the full {@link CommandResult}, so a caller can report
- * the output without running the command again.
+ * Carries the binary, the argv and the full {@link CommandResult}, so a
+ * caller can report the output without running the command again.
  *
- * `message` is `command failed (exit N): <argv>`, with argv quoted by
+ * `message` is `command failed (exit N): <binary> <argv>`, quoted by
  * `shellJoin`, followed on a new line by the trimmed stderr, or the trimmed
  * `error` when stderr is empty. Nothing follows when both are empty. The argv
  * appears in full, so error logs and reports carry it: pass secrets through
  * `env` or `input`, not argv. Use `detail` to show a person
- * why it failed.
+ * why it failed. The binary is left out when it is not known, as for a fake
+ * runner without `binary`.
  */
 export class CommandFailed extends Error {
+  /** The binary that ran, when the runner reports one (see `CommandRunner.binary`). */
+  readonly binary: string | undefined
   /** The arguments the command ran with, without the binary name. */
   readonly argv: string[]
   /** The full result of the failed run. */
@@ -334,14 +355,17 @@ export class CommandFailed extends Error {
   /**
    * @param argv - The arguments the command ran with.
    * @param result - The result of the failed run.
+   * @param binary - The binary that ran, when known.
    */
-  constructor(argv: string[], result: CommandResult) {
+  constructor(argv: string[], result: CommandResult, binary?: string | undefined) {
     const stderr = stderrOrError(result)
+    const command = binary === undefined ? argv : [binary, ...argv]
     super(
-      `command failed (exit ${result.exitCode}): ${shellJoin(argv)}` +
+      `command failed (exit ${result.exitCode}): ${shellJoin(command)}` +
         (stderr ? `\n${stderr}` : ''),
     )
     this.name = 'CommandFailed'
+    this.binary = binary
     this.argv = argv
     this.result = result
   }
@@ -375,17 +399,20 @@ export function runChecked(
   opts: CommandRunOptions,
 ): CommandResult
 export function runChecked<P extends unknown[]>(
-  runner: { run(argv: string[], ...opts: P): CommandResult },
+  runner: { readonly binary?: string | undefined; run(argv: string[], ...opts: P): CommandResult },
   argv: string[],
   ...opts: NoInfer<P>
 ): CommandResult
 export function runChecked(
-  runner: { run(argv: string[], ...opts: unknown[]): CommandResult },
+  runner: {
+    readonly binary?: string | undefined
+    run(argv: string[], ...opts: unknown[]): CommandResult
+  },
   argv: string[],
   ...opts: unknown[]
 ): CommandResult {
   const result = runner.run(argv, ...opts)
-  if (result.exitCode !== 0) throw new CommandFailed(argv, result)
+  if (result.exitCode !== 0) throw new CommandFailed(argv, result, runner.binary)
   return result
 }
 
@@ -442,41 +469,30 @@ const CHILD_STDIO_CORRUPTED =
   process.versions['bun'] !== undefined && process.env['NODE_ENV'] === 'test'
 
 /**
- * Whether `binary` resolves to an executable file the way a spawn would find
- * it: a name with a `/` is taken relative to `cwd`; a bare name is looked up
- * on the child's `PATH`.
+ * Folds a finished `spawnSync` into a {@link CommandResult}. Exported for
+ * tests.
  */
-function findsExecutable(binary: string, cwd: string, path: string | undefined): boolean {
-  const isExecutable = (p: string): boolean => {
-    try {
-      accessSync(p, constants.X_OK)
-      return statSync(p).isFile()
-    } catch {
-      return false
-    }
-  }
-  if (binary === '') return false
-  if (binary.includes('/')) return isExecutable(resolve(cwd, binary))
-  return (path ?? '/usr/bin:/bin')
-    .split(delimiter)
-    .some((dir) => isExecutable(resolve(cwd, dir, binary)))
-}
-
-/** Folds a finished `spawnSync` into a {@link CommandResult}. */
-function fromSpawnSync(
+export function fromSpawnSync(
   proc: { status: number | null; signal: NodeJS.Signals | null; error?: Error | undefined },
   stdout: string,
   stderr: string,
 ): CommandResult {
+  const code = (proc.error as NodeJS.ErrnoException | undefined)?.code
   return {
     exitCode: proc.status ?? 1,
     // Bun reports a failed spawn with `status` undefined, not null.
     ...(proc.status == null ? { neverExited: true as const, ...syncStop(proc) } : {}),
+    // A real status with a timeout: the child exited, but a process it started
+    // held the pipes until the deadline. With the cap: the child passed it and
+    // exited before the kill landed.
+    ...(proc.status != null && (code === 'ETIMEDOUT' || code === 'ENOBUFS')
+      ? { outputIncomplete: true as const }
+      : {}),
     stdout,
     stderr,
     // `proc.error` is set for a failed spawn, a timeout, the output cap, or a
-    // failed stdin write; only the first three leave `status` null (and under
-    // Bun the cap can come with a real status too). A stdin write error can
+    // failed stdin write. The first three usually leave `status` null; when
+    // they do not, `outputIncomplete` is set above. A stdin write error can
     // come with a child that did exit, so it is kept either way.
     ...(proc.error ? { error: proc.error.message } : {}),
   }
@@ -502,7 +518,7 @@ function runViaChildRedirect(
   // the same stand-in the pipe path reports for a failed spawn. This also
   // keeps a binary named like an option (`-a`) from reaching `exec` as one,
   // unless an executable named `-a` is on PATH.
-  if (!findsExecutable(binary, opts.cwd, env['PATH'])) {
+  if (which(binary, { cwd: opts.cwd, env: { PATH: env['PATH'] } }) === undefined) {
     return spawnFailure(`spawnSync ${binary} ENOENT`)
   }
   const dir = mkdtempSync(join(tmpdir(), 'command-seam-'))
@@ -584,6 +600,7 @@ export function resolveRunner(binary: string, injected?: CommandRunner | undefin
  */
 export function spawnRunner(binary: string): CommandRunner {
   return {
+    binary,
     run(argv: string[], opts: CommandRunOptions): CommandResult {
       const timeoutMs = normalizeTimeout(opts.timeoutMs)
       const cwdMessage = cwdError(`spawnSync ${binary}`, binary, argv, opts)

package/which.ts

@@ -0,0 +1,72 @@
+/**
+ * `which`: find a binary on `PATH` without running it, the way the runners'
+ * spawn would find it. For code that picks a tool by what is installed;
+ * running `--version` to probe is slow for some CLIs and has side effects
+ * (update checks, telemetry) for others.
+ */
+
+import { accessSync, constants, statSync } from 'node:fs'
+import { delimiter, resolve } from 'node:path'
+
+import type { EnvOverrides } from './sync.ts'
+
+/**
+ * Options for {@link which}.
+ *
+ * @experimental
+ */
+export interface WhichOptions {
+  /**
+   * The folder a relative path, or a relative `PATH` entry, is resolved
+   * against, as a spawn with this `cwd` would. Default `process.cwd()`.
+   */
+  cwd?: string | undefined
+  /**
+   * Variables merged over the parent's environment, as the runners take
+   * them. Only `PATH` is read; an `undefined` value unsets it.
+   */
+  env?: EnvOverrides | undefined
+}
+
+/**
+ * The absolute path of the file a spawn of `binary` would run, or
+ * `undefined` when there is none. A name with a `/` is taken relative to
+ * `cwd`; a bare name is looked up on `PATH`, first match wins. A match must be
+ * an executable file. With `PATH` unset, it searches `/usr/bin:/bin`. An
+ * empty `PATH` entry (`PATH=''`, `a::b`, a trailing `:`) means `cwd`, as it
+ * does for Node's spawn; Bun's spawn skips empty entries, so under Bun such
+ * a match may not start. POSIX only: `PATHEXT` is not read.
+ *
+ * Never throws for a missing binary, an unreadable folder or a bad `cwd`.
+ *
+ * @param binary - A name looked up on `PATH`, or a path.
+ * @param opts - `cwd` and `env`, as the runners take them.
+ * @returns The absolute path, or `undefined`.
+ * @experimental
+ *
+ * @example
+ * ```ts
+ * const harnesses = ['codex', 'claude', 'cursor-agent'].filter((b) => which(b) !== undefined)
+ * ```
+ */
+export function which(binary: string, opts: WhichOptions = {}): string | undefined {
+  const cwd = opts.cwd ?? process.cwd()
+  if (binary === '') return undefined
+  if (binary.includes('/')) return executable(resolve(cwd, binary))
+  const path = opts.env !== undefined && 'PATH' in opts.env ? opts.env['PATH'] : process.env['PATH']
+  for (const dir of (path ?? '/usr/bin:/bin').split(delimiter)) {
+    const found = executable(resolve(cwd, dir, binary))
+    if (found !== undefined) return found
+  }
+  return undefined
+}
+
+/** `p` when it is an executable file, else `undefined`. */
+function executable(p: string): string | undefined {
+  try {
+    accessSync(p, constants.X_OK)
+    return statSync(p).isFile() ? p : undefined
+  } catch {
+    return undefined
+  }
+}

package/smoke.mjs

@@ -1,61 +0,0 @@
-// Runs the BUILT package under Node, which no other check does: `bun test`
-// resolves the `bun` export condition to the TypeScript sources, so dist/ is
-// compiled and never executed. A broken emit — an unrewritten `.ts` import, a
-// dependency with no dist/ of its own — passes every other gate and fails on
-// the consumer's machine.
-//
-// Deliberately not a test-runner suite: it must run from the extracted
-// snapshot with only `dist/` and production dependencies present.
-
-import { strict as assert } from 'node:assert'
-import { spawnRunner, runChecked, CommandFailed, asAsync, withDefaults } from './dist/index.js'
-import { fakeProcess, fakeRunner } from './dist/testing.js'
-
-const runner = spawnRunner('node')
-const ok = runner.run(['-e', "process.stdout.write('hi')"], { cwd: process.cwd() })
-assert.equal(ok.exitCode, 0)
-assert.equal(ok.stdout, 'hi')
-
-const bad = runner.run(['-e', "process.stderr.write('boom'); process.exit(3)"], {
-  cwd: process.cwd(),
-})
-assert.equal(bad.exitCode, 3)
-assert.match(bad.stderr, /boom/)
-
-// `run` never throws; `runChecked` does.
-assert.throws(
-  () => runChecked(runner, ['-e', 'process.exit(1)'], { cwd: process.cwd() }),
-  (e) => e instanceof CommandFailed && e.argv.length === 2,
-)
-
-// detail joins both streams, empty ones dropped — the reason it exists is a
-// command that explains itself on stdout while git reports failure on stderr.
-const both = new CommandFailed(['x'], { exitCode: 1, stdout: 'why\n', stderr: 'what\n' })
-assert.equal(both.detail, 'what\nwhy')
-assert.equal(new CommandFailed(['x'], { exitCode: 1, stdout: 'only\n', stderr: '' }).detail, 'only')
-
-// env merges over the parent environment.
-const withEnv = runner.run(['-e', "process.stdout.write(process.env.SMOKE_VAR ?? '')"], {
-  cwd: process.cwd(),
-  env: { SMOKE_VAR: 'set' },
-})
-assert.equal(withEnv.stdout, 'set')
-
-const async = asAsync(runner)
-const viaAsync = await async.run(['-e', "process.stdout.write('async')"], { cwd: process.cwd() })
-assert.equal(viaAsync.stdout, 'async')
-
-// An invalid timeoutMs is a caller error.
-assert.throws(() => runner.run(['-e', ''], { cwd: process.cwd(), timeoutMs: 0 }), RangeError)
-
-const bound = withDefaults(runner, { cwd: process.cwd() })
-assert.equal(bound.run(['-e', "process.stdout.write('bound')"]).stdout, 'bound')
-
-// The /testing entry point, built.
-const fake = fakeRunner({ 'rev-parse HEAD': { stdout: 'abc\n' } })
-assert.equal(runChecked(fake.runner, ['rev-parse', 'HEAD'], { cwd: '/' }).stdout, 'abc\n')
-const proc = fakeProcess()
-proc.kill()
-assert.equal((await proc.exited).reason, 'abort')
-
-console.log('command-seam smoke: OK')