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

package/dist/process.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 { 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 declare function managedProcessRunner(binary: string): ManagedProcessRunner;
+/**
+ * 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 declare function stopProcess(handle: ManagedProcessHandle, opts?: {
+    graceMs?: number | undefined;
+}): Promise<ManagedProcessExit>;
+/** The name of signal number `n`, or `undefined` for 0 (a probe) and unknown numbers. */
+export declare function signalName(n: number): NodeJS.Signals | undefined;
+//# sourceMappingURL=process.d.ts.map

package/dist/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../process.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EAAgC,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAEnG,2DAA2D;AAC3D,MAAM,WAAW,wBAAwB;IACvC,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,GAAG,CAAC,EAAE,YAAY,GAAG,SAAS,CAAA;IAC9B;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAClC;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC5B;AAED,mCAAmC;AACnC,MAAM,WAAW,kBAAkB;IACjC,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAA;IAChB,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;IAC7B;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACjC;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,EAAE,SAAS,GAAG,QAAQ,CAAC,GAAG,SAAS,CAAA;IACrE;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC3B;AAED,yFAAyF;AACzF,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB;;;;;;;;;OASG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,GAAG,IAAI,CAAA;IAC5C,sFAAsF;IACtF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAA;CAC7C;AAED,oFAAoF;AACpF,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,wBAAwB,GAAG,oBAAoB,CAAA;CAC1E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,CAoFzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,oBAAoB,EAC5B,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAO,GAC1C,OAAO,CAAC,kBAAkB,CAAC,CAa7B;AAYD,yFAAyF;AACzF,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,GAAG,SAAS,CAKhE"}

package/dist/process.js

@@ -0,0 +1,175 @@
+/**
+ * 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.js";
+import { cwdError, mergedEnv, timerMs } from "./sync.js";
+/**
+ * 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) {
+    return {
+        run(argv, opts) {
+            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();
+            const exited = new Promise((resolve) => {
+                let settled = false;
+                const finish = (result) => {
+                    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,
+                                reason: signal !== null && sent.has(signal) ? 'abort' : 'signal',
+                            }
+                            : {}),
+                    });
+                });
+            });
+            return {
+                pid,
+                kill(signal = 'SIGTERM') {
+                    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, opts = {}) {
+    const graceMs = timerMs('graceMs', opts.graceMs ?? 5_000, 'zero');
+    handle.kill();
+    if (graceMs === undefined)
+        return handle.exited;
+    let timer;
+    const grace = new Promise((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) {
+    return { exitCode: 1, signal: null, neverExited: true, reason: 'abort', error };
+}
+/** The exit of a process that never started. */
+function spawnExit(error) {
+    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) {
+    for (const [name, value] of Object.entries(constants.signals)) {
+        if (value === n)
+            return name;
+    }
+    return undefined;
+}

package/dist/process.test.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=process.test.d.ts.map

package/dist/process.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.test.d.ts","sourceRoot":"","sources":["../process.test.ts"],"names":[],"mappings":""}

package/dist/process.test.js

@@ -0,0 +1 @@
+"use strict";

package/dist/quote.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+/**
+ * `word` as one shell word: unquoted when it holds only characters no POSIX
+ * shell treats specially (letters, digits and `_@%+=:,./-`), single-quoted
+ * otherwise.
+ */
+export declare function shellQuote(word: string): string;
+/**
+ * `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 declare function shellJoin(argv: readonly string[]): string;
+//# sourceMappingURL=quote.d.ts.map

package/dist/quote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quote.d.ts","sourceRoot":"","sources":["../quote.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG/C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEzD"}

package/dist/quote.js

@@ -0,0 +1,28 @@
+/**
+ * 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) {
+    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) {
+    return argv.map((w, i) => (i === 0 && w.includes('=') ? quoted(w) : shellQuote(w))).join(' ');
+}
+function quoted(word) {
+    return `'${word.replaceAll("'", `'\\''`)}'`;
+}

package/dist/result.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Helpers for reading a {@link CommandResult}: did it run and succeed, what
+ * to tell a person, and its stdout as JSON.
+ *
+ * None of them throw for a failed command: a failure stays a value the
+ * caller reads. Use `runChecked` when stopping on failure is the only
+ * sensible response.
+ */
+import type { AsyncCommandRunner, AsyncCommandRunOptions } from './async.ts';
+import type { CommandResult, CommandRunner, CommandRunOptions } from './sync.ts';
+/**
+ * Whether the process started and exited 0. `exitCode` alone is not enough:
+ * a spawn failure, timeout or abort reports a stand-in `1`, and a caller that
+ * reads exit codes as answers must rule that out first.
+ *
+ * Takes any runner's result: a `CommandResult`, a `StreamResult` or a
+ * `ManagedProcessExit`.
+ *
+ * @returns `true` when `neverExited` is not set and `exitCode` is 0.
+ */
+export declare function ran(result: {
+    exitCode: number;
+    neverExited?: boolean | undefined;
+}): boolean;
+/**
+ * The child's trimmed stderr, else the runner's trimmed `error` (a failed
+ * spawn, a timeout, an abort), else `''`. Use it where a failure message reads
+ * stderr: since the runner's message is only in `error`, reading `stderr`
+ * alone shows nothing when the command never ran.
+ *
+ * @param result - A run's result.
+ * @returns The text, trimmed; `''` when both are empty.
+ * @experimental
+ *
+ * @example
+ * ```ts
+ * const r = spawnRunner('git').run(['fetch'], { cwd: '.' })
+ * if (!ran(r)) console.error(`fetch failed: ${stderrOrError(r)}`)
+ * ```
+ */
+export declare function stderrOrError(result: Pick<CommandResult, 'stderr' | 'error'>): string;
+/** Options for {@link failureText}. */
+export interface FailureTextOptions {
+    /**
+     * Return both streams instead of one: trimmed stderr (or the runner's
+     * `error`, when the child wrote no stderr) and trimmed stdout,
+     * newline-joined, empty ones dropped. Empty when stderr, `error` and stdout
+     * are all empty; there is no `exit N` fallback. This is what `CommandFailed.detail`
+     * returns. Use it when both halves matter, such as a git hook that rejects
+     * a commit: git's own error is on stderr, the hook's reason on stdout.
+     */
+    both?: boolean | undefined;
+}
+/**
+ * The failure text to show a person. By default it picks one stream, which
+ * suits a one-line message: trimmed stderr, else the runner's trimmed
+ * `error` (a failed spawn, a timeout), else trimmed stdout (some commands
+ * explain a failure there), else `exit N`. With `both: true` it
+ * joins both streams (see {@link FailureTextOptions.both}).
+ *
+ * @param result - The result of a failed run.
+ * @param opts - `both: true` to join both streams.
+ * @returns The message. Non-empty unless `both` is set and there is no text
+ * at all.
+ */
+export declare function failureText(result: Pick<CommandResult, 'exitCode' | 'stdout' | 'stderr' | 'error'>, opts?: FailureTextOptions): string;
+/**
+ * The first non-blank line of `text`, trimmed; `fallback` when there is
+ * none. For short diagnostics from multi-line tool output.
+ *
+ * @param text - Usually `stdout` or `stderr`.
+ * @param fallback - Returned when every line is blank. Defaults to `''`.
+ * @experimental
+ */
+export declare function firstLine(text: string, fallback?: string): string;
+/**
+ * Outcome of {@link runJson}: a parsed value, or why there is none. Two
+ * fields are named `reason`: `j.reason` says why there is no value (`failed`,
+ * `unparseable` or `invalid`), and `j.result.reason` says why the command
+ * never finished, when it did not (see `NeverExitedReason`).
+ *
+ * @experimental
+ */
+export type JsonRun<T> = {
+    ok: true;
+    value: T;
+    result: CommandResult;
+} | {
+    ok: false;
+    /**
+     * `failed`: did not run, or exited with a code not in `okExitCodes`.
+     * `unparseable`: exited with an accepted code, and stdout was not JSON.
+     */
+    reason: 'failed' | 'unparseable';
+    /** A human-readable explanation (the failure text, or the parse error). */
+    message: string;
+    result: CommandResult;
+} | {
+    ok: false;
+    /** `invalid`: stdout was JSON, and the `parse` option threw for it. */
+    reason: 'invalid';
+    /** `stdout JSON was rejected: ` and the thrown error's message. */
+    message: string;
+    /** What `parse` threw, such as a schema library's error with its issue list. */
+    cause: unknown;
+    result: CommandResult;
+};
+/**
+ * Options for {@link runJson}, apart from `parse`, which is typed by the
+ * value it returns. A value typed `RunJsonOptions` leaves `T` to the caller.
+ *
+ * @experimental
+ */
+export interface RunJsonOptions {
+    /**
+     * Skip leading non-JSON output (log lines, banners). The JSON is the rest of
+     * stdout from the first line (after `\n` or `\r`) that starts with `{` or
+     * `[` and parses to the end, so a `[INFO] ...` prefix is skipped too.
+     * Trailing output is not handled. Off by default: strict `JSON.parse` of
+     * the whole stdout.
+     */
+    tolerateLeadingLog?: boolean | undefined;
+    /**
+     * Exit codes that count as an answer, for a tool that prints JSON and
+     * exits non-zero on purpose (`npm outdated --json` exits 1 when anything is
+     * outdated). Default `[0]`. List `0` too if it still counts. A run that
+     * never exited is `failed` whatever its stand-in code. Output from an
+     * accepted non-zero exit must still parse, so pass a `parse` that rejects
+     * the tool's own error output.
+     */
+    okExitCodes?: readonly number[] | undefined;
+}
+/** The `parse` option of `runJson` and its siblings. `T` is what it returns. */
+interface ParseOption<T> {
+    /**
+     * Check the parsed value and return it typed, such as a schema's `parse`.
+     * A throw makes the outcome `invalid`. It must be sync: a returned promise
+     * is also `invalid`. Without it, `T` is the caller's claim and is not
+     * checked.
+     */
+    parse?: ((value: unknown) => T) | undefined;
+}
+/** Options with an optional `parse`. */
+type JsonOptions<T> = RunJsonOptions & ParseOption<T>;
+/**
+ * Parse a finished run's stdout as JSON, if it ran and exited with a code in
+ * `okExitCodes` (default `[0]`). Without the `parse` option, `T` is the
+ * caller's claim about the shape and is not checked; pass `parse` when the
+ * producer is not trusted. Never throws.
+ *
+ * @param result - A finished run.
+ * @param opts - Parse options.
+ * @returns `{ ok: true, value }`, or `{ ok: false, reason, message }` with
+ * `reason` `failed` (did not run, or exited with a code not accepted),
+ * `unparseable`, or `invalid` (`parse` threw; `cause` holds what it threw).
+ * @experimental
+ */
+export declare function parseJsonResult<T = unknown>(result: CommandResult, opts?: JsonOptions<T>): JsonRun<T>;
+/**
+ * The runner's options tuple, `[opts]` or `[opts?]`, with the `runJson`
+ * options added. A conditional rather than a mapped type, so `T` can be inferred
+ * from `parse`; `NoInfer` keeps `P` inferred from the runner alone.
+ */
+type WithJsonOptions<P extends unknown[], T> = P extends [opts: infer O] ? [opts: NoInfer<O> & JsonOptions<T>] : P extends [opts?: infer O] ? [opts?: NoInfer<O> & JsonOptions<T>] : never;
+/**
+ * Run a command with a sync runner and parse its stdout as JSON
+ * ({@link parseJsonResult}). Never throws for a failed command; a programmer
+ * error, such as an invalid `timeoutMs`, throws. With the `parse` option,
+ * `T` is what `parse` returns.
+ *
+ * Takes the runner's own options, so 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 and {@link RunJsonOptions}.
+ * @returns A {@link JsonRun}: the parsed value, or why there is none.
+ *
+ * @example
+ * ```ts
+ * const gh = spawnRunner('gh')
+ * const r = runJson<{ login: string }>(gh, ['api', 'user'], { cwd: '.' })
+ * if (r.ok) console.log(r.value.login)
+ * else console.error(r.message)
+ * ```
+ *
+ * @experimental
+ */
+export declare function runJson<T = unknown>(runner: CommandRunner, argv: string[], opts: CommandRunOptions & JsonOptions<T>): JsonRun<T>;
+export declare function runJson<T = unknown>(runner: {
+    run(argv: string[]): CommandResult;
+}, argv: string[], opts?: Partial<CommandRunOptions> & JsonOptions<T>): JsonRun<T>;
+export declare function runJson<T = unknown, P extends unknown[] = [opts: CommandRunOptions]>(runner: {
+    run(argv: string[], ...opts: P): CommandResult;
+}, argv: string[], ...opts: WithJsonOptions<P, T>): JsonRun<T>;
+/**
+ * The async version of {@link runJson}. Never rejects for a failed command;
+ * a programmer error, such as an invalid `timeoutMs`, rejects. `parse` is
+ * sync, as in `runJson`.
+ *
+ * @experimental
+ */
+export declare function runJsonAsync<T = unknown>(runner: AsyncCommandRunner, argv: string[], opts: AsyncCommandRunOptions & JsonOptions<T>): Promise<JsonRun<T>>;
+export declare function runJsonAsync<T = unknown>(runner: {
+    run(argv: string[]): Promise<CommandResult>;
+}, argv: string[], opts?: Partial<AsyncCommandRunOptions> & JsonOptions<T>): Promise<JsonRun<T>>;
+export declare function runJsonAsync<T = unknown, P extends unknown[] = [opts: AsyncCommandRunOptions]>(runner: {
+    run(argv: string[], ...opts: P): Promise<CommandResult>;
+}, argv: string[], ...opts: WithJsonOptions<P, T>): Promise<JsonRun<T>>;
+export {};
+//# sourceMappingURL=result.d.ts.map

package/dist/result.d.ts.map

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