@osdlc/command-seam 0.0.0-stage → 0.0.1-stage

package/dist/sync.d.ts

@@ -0,0 +1,311 @@
+/**
+ * The synchronous capture runner: the {@link CommandRunner} interface and its
+ * `spawnSync`-backed default, {@link spawnRunner}. Code that runs commands
+ * takes a `CommandRunner`; tests pass a fake. Live output and long-lived
+ * processes have their own runners (`stream.ts`, `process.ts`).
+ *
+ * Two ways to call it, like zod's `safeParse` and `parse`:
+ *   - `runner.run(...)` never throws for a failed command; the caller reads
+ *     `exitCode`.
+ *   - `runChecked(runner, ...)` throws {@link CommandFailed} on a non-zero
+ *     exit, for callers whose only sensible response to failure is to stop.
+ */
+/** Result of running an external command through a `CommandRunner`. */
+export interface CommandResult {
+    /** The child's exit code, or `1` when it never reported one (see `neverExited`). */
+    exitCode: number;
+    /** Everything the child wrote to stdout, decoded as UTF-8. */
+    stdout: string;
+    /**
+     * Everything the child wrote to stderr, decoded as UTF-8. Only the child's
+     * output: the runner's own message, such as a failed spawn or a timeout, is
+     * in `error`. `failureText` reads both.
+     */
+    stderr: string;
+    /**
+     * `true` when the child never reported an exit status: the spawn failed, a
+     * timeout or an abort killed it, a signal took it down, or the sync runner
+     * killed it at the output cap. `exitCode` is
+     * then a stand-in `1`, not the command's answer. Absent otherwise.
+     *
+     * Check this before reading an exit code as an answer. `grep` exits 1 for
+     * "no matches" and `git config --get` exits 1 for an unset key; without
+     * this check, a binary missing from `PATH` reads as a confident "no".
+     * `reason` says which of those causes it was.
+     */
+    neverExited?: boolean | undefined;
+    /**
+     * Why the child never reported an exit status. Set whenever `neverExited`
+     * is, absent otherwise. See {@link NeverExitedReason}.
+     */
+    reason?: NeverExitedReason | undefined;
+    /**
+     * The signal that ended the child, when the runner knows it: always for
+     * `reason: 'signal'`, and for a sync `'timeout'` or `'output'` (`SIGKILL`).
+     * The async runner settles a timeout or abort before the child is gone, so
+     * it leaves this unset there.
+     */
+    signal?: NodeJS.Signals | 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
+     * cap, or a failed write to the child's stdin. It is never copied into
+     * `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.
+     */
+    error?: string | undefined;
+}
+/**
+ * Why a child never reported an exit status (`neverExited: true`):
+ *
+ * - `spawn`: it never started: a missing binary, no permission, a bad `cwd`.
+ *   Retrying will not help.
+ * - `timeout`: `timeoutMs` ran out and the runner killed it.
+ * - `abort`: the caller stopped it: an `AbortSignal` (async runner), an
+ *   `onSpawn` that threw, or `kill()` on a managed process. Or a
+ *   `processGroup` run was refused because signal forwarding is stopping the
+ *   host; it never started, and `error` carries the refusal message.
+ * - `signal`: a signal from elsewhere ended it.
+ * - `output`: the sync runner killed it for passing its 256 MB output cap
+ *   (`spawnSync`'s `ENOBUFS`). The same run will fail the same way. The async
+ *   runner has no cap, and the `bun test` capture path writes to files, so
+ *   neither reports this.
+ */
+export type NeverExitedReason = 'spawn' | 'timeout' | 'abort' | 'signal' | 'output';
+/** Per-call options for a {@link CommandRunner}. */
+export interface CommandRunOptions {
+    /** Working directory for the child. Required: the runner has no default. */
+    cwd: string;
+    /**
+     * Kill the child with `SIGKILL` after this many milliseconds. The result
+     * then has a non-zero `exitCode`, `neverExited: true` and
+     * `reason: 'timeout'`.
+     *
+     * The same rule on every runner: `undefined` and `Infinity` mean no cap,
+     * and a fraction rounds up (`1.2` is `2`). A value above 2^31 - 1 (about
+     * 24.8 days), the largest timer delay, is clamped to it. `0`, a negative
+     * value and `NaN` are a caller error: `RangeError`, thrown by the sync
+     * runners and rejected by the async ones. A value that is not a number is
+     * a `TypeError`, the same way.
+     *
+     * The sync runners (`spawnRunner`, `runShell`, `shellRunner`) and
+     * `streamRunner` kill the direct child only. Processes it started keep
+     * running. Only the async runners (`spawnRunnerAsync`, `runShellAsync`,
+     * `shellRunnerAsync`) can kill the whole process group, with
+     * `processGroup`.
+     */
+    timeoutMs?: number | undefined;
+    /** Text written to the child's stdin. Stdin is closed after it, or at once when omitted. */
+    input?: string | undefined;
+    /**
+     * Variables merged over the parent's environment. An `undefined` value
+     * removes that variable from the child's environment.
+     */
+    env?: EnvOverrides | undefined;
+}
+/** Env vars to set on a child, merged over the parent's; an `undefined` value unsets that var. */
+export type EnvOverrides = Record<string, string | undefined>;
+/**
+ * Runs one external binary (`git`, `gh`, …) and captures its output. Code that
+ * shells out takes one of these; tests pass a fake.
+ *
+ * @example
+ * ```ts
+ * const fake: CommandRunner = {
+ *   run: (argv) => ({ exitCode: 0, stdout: `ran ${argv.join(' ')}`, stderr: '' }),
+ * }
+ * ```
+ */
+export interface CommandRunner {
+    /**
+     * 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,
+     * a missing binary or a timeout all come back as a {@link CommandResult}.
+     * Programmer errors throw: an invalid `timeoutMs` (see its doc) or a NUL
+     * byte in argv or env.
+     */
+    run(argv: string[], opts: CommandRunOptions): CommandResult;
+}
+/**
+ * `{ env }`: `process.env` merged with `opts.env`, minus any key whose
+ * override is `undefined`. Always an explicit object built from the current
+ * `process.env` at call time — never `undefined`, never an omitted key, and
+ * never `process.env` handed through verbatim either.
+ *
+ * Node's `child_process.spawnSync` inherits live `process.env` whether
+ * `env` is omitted, `undefined`, or `process.env` itself. Bun's does not:
+ * all three instead take a snapshot — of exactly when is unclear, but
+ * empirically it misses anything set on `process.env` after the process
+ * started, even as the very first spawn — so a test that points an env var
+ * at a fresh temp dir right before spawning would silently see the real,
+ * unwritten default instead. Only spreading `process.env`'s current
+ * key/values into a brand-new plain object at the call site sidesteps
+ * whatever Bun is snapshotting.
+ */
+export declare function mergedEnv(opts: Pick<CommandRunOptions, 'env'>): {
+    env: NodeJS.ProcessEnv;
+};
+/**
+ * `timeoutMs` as every runner applies it: `undefined` for no cap, else a whole
+ * number of milliseconds, at most {@link MAX_TIMER_MS}. See
+ * {@link CommandRunOptions.timeoutMs}.
+ *
+ * @throws `TypeError` for a value that is not a number.
+ * @throws `RangeError` for `0`, a negative value or `NaN`.
+ */
+export declare function normalizeTimeout(timeoutMs: number | undefined): number | undefined;
+/**
+ * A delay option as a timer takes it: `undefined` for `Infinity`, else a whole
+ * number of milliseconds, at most {@link MAX_TIMER_MS}. `min` says whether `0`
+ * is allowed. `name` is the option's name, for the error message.
+ *
+ * @throws `TypeError` for a value that is not a number.
+ * @throws `RangeError` for a value below `min`, or `NaN`.
+ */
+export declare function timerMs(name: string, ms: number, min: 'positive' | 'zero'): number | undefined;
+/**
+ * A spawn error message when `cwd` is missing or not a directory, else
+ * `undefined`. Checked before spawning: a spawn reports a missing `cwd` as
+ * `spawn <binary> ENOENT`, which reads as a missing binary, and Node's async
+ * `spawn` throws for a `cwd` that is a file.
+ *
+ * @param spawnName - The message prefix: `spawn` or `spawnSync`, then the binary.
+ * @throws `TypeError` for a NUL byte in `binary`, `argv` or `opts.env`, as the
+ * spawn would, so a bad `cwd` does not hide it.
+ */
+export declare function cwdError(spawnName: string, binary: string, argv: readonly string[], opts: {
+    cwd: string;
+    env?: EnvOverrides | undefined;
+}): string | undefined;
+/** The stand-in result for a child that never started. */
+export declare function spawnFailure(message: string): CommandResult;
+/**
+ * How a `spawnSync` that reported no exit status ended. Shared by the sync
+ * capture and streaming runners.
+ */
+export declare function syncStop(proc: {
+    error?: Error | undefined;
+    signal: NodeJS.Signals | null;
+}): {
+    reason: Exclude<NeverExitedReason, 'abort'>;
+    signal?: NodeJS.Signals;
+};
+/**
+ * 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.
+ *
+ * `message` is `command failed (exit N): <argv>`, with 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.
+ */
+export declare class CommandFailed extends Error {
+    /** The arguments the command ran with, without the binary name. */
+    readonly argv: string[];
+    /** The full result of the failed run. */
+    readonly result: CommandResult;
+    /**
+     * The failure text to show a human: both streams, trimmed, newline-joined,
+     * empty ones dropped, with the runner's `error` standing in for an empty
+     * stderr. Empty when there is no text at all. The same as
+     * `failureText(e.result, { both: true })`.
+     *
+     * `message` interpolates stderr only, and several commands write the
+     * sentence that explains the failure to stdout instead — a rejecting git
+     * hook, `git commit` on a clean tree, `git apply --check`. Read this rather
+     * than picking a stream at the call site.
+     *
+     * Both are joined rather than one preferred, because a rejecting hook is
+     * the case where both carry a distinct half: git's own "commit failed" on
+     * stderr, the hook's reason on stdout. Preferring either drops the half
+     * the reader needs.
+     */
+    get detail(): string;
+    /**
+     * @param argv - The arguments the command ran with.
+     * @param result - The result of the failed run.
+     */
+    constructor(argv: string[], result: CommandResult);
+}
+/**
+ * Run a command and throw if it fails. Use it where the only sensible
+ * response to failure is to stop, instead of writing
+ * `if (r.exitCode !== 0) throw` after each `run`.
+ *
+ * Takes any runner whose `run` returns a {@link CommandResult}, with that
+ * runner's own options: a `withDefaults` runner needs only the options it
+ * did not bind.
+ *
+ * @param runner - Runs the command; pass a fake in tests.
+ * @param argv - Arguments, without the binary name.
+ * @param opts - Per-call options, as `runner.run` takes them.
+ * @returns The result, when `exitCode` is 0.
+ * @throws {@link CommandFailed} when `exitCode` is not 0, including a missing
+ * binary or a timeout.
+ *
+ * @example
+ * ```ts
+ * const git = spawnRunner('git')
+ * const head = runChecked(git, ['rev-parse', 'HEAD'], { cwd: '.' }).stdout.trim()
+ * ```
+ */
+export declare function runChecked(runner: CommandRunner, argv: string[], opts: CommandRunOptions): CommandResult;
+export declare function runChecked<P extends unknown[]>(runner: {
+    run(argv: string[], ...opts: P): CommandResult;
+}, argv: string[], ...opts: NoInfer<P>): CommandResult;
+/**
+ * Run `fn`; if it throws {@link CommandFailed}, throw `mapper(e)` instead.
+ * Any other error propagates untouched, as does `fn`'s return value. Replaces
+ * `catch (e) { if (e instanceof CommandFailed) throw new X(...); throw e }`.
+ *
+ * `mapper` may have side effects (print the output, say) before returning the
+ * error to throw. Async version: `mapFailedAsync`.
+ *
+ * @param fn - The code to run, usually a `runChecked` call.
+ * @param mapper - Turns the failure into the error to throw.
+ * @returns What `fn` returns.
+ * @throws The error `mapper` returns, when `fn` throws `CommandFailed`.
+ */
+export declare function mapFailed<T>(fn: () => T, mapper: (failed: CommandFailed) => Error): T;
+/**
+ * Run `fn`; if it throws {@link CommandFailed}, return `onFailed(e)` instead.
+ * Any other error propagates untouched. Async version: `catchFailedAsync`.
+ *
+ * @param fn - The code to run, usually a `runChecked` call.
+ * @param onFailed - Turns the failure into a value.
+ * @returns What `fn` returns, or what `onFailed` returns.
+ */
+export declare function catchFailed<T, R>(fn: () => T, onFailed: (failed: CommandFailed) => R): T | R;
+/**
+ * The injected runner when there is one, else `spawnRunner(binary)`.
+ *
+ * @param binary - The binary for the default runner.
+ * @param injected - A runner to use instead, such as a test fake.
+ */
+export declare function resolveRunner(binary: string, injected?: CommandRunner | undefined): CommandRunner;
+/**
+ * The default {@link CommandRunner}: runs `binary` with `spawnSync`, so each
+ * call blocks until the child exits. On timeout the child gets `SIGKILL`.
+ * Captured output is capped at 256 MB per stream. Under `bun test` (the Bun
+ * runtime with `NODE_ENV=test`) it captures through `/bin/sh` and temp files
+ * instead of pipes (see `runViaChildRedirect`).
+ *
+ * @param binary - A name looked up on `PATH`, or a path.
+ * @returns A runner for that binary.
+ *
+ * @example
+ * ```ts
+ * const git = spawnRunner('git')
+ * const r = git.run(['status', '--porcelain'], { cwd: '.', timeoutMs: 10_000 })
+ * if (r.exitCode === 0) console.log(r.stdout)
+ * ```
+ */
+export declare function spawnRunner(binary: string): CommandRunner;
+//# sourceMappingURL=sync.d.ts.map

package/dist/sync.d.ts.map

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