@osdlc/command-seam 0.0.0-stage → 0.4.0

package/dist/result.js

@@ -0,0 +1,219 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function ran(result) {
+    return result.neverExited !== true && result.exitCode === 0;
+}
+/**
+ * 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 function stderrOrError(result) {
+    return result.stderr.trim() || (result.error?.trim() ?? '');
+}
+/**
+ * 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 function failureText(result, opts = {}) {
+    const stderr = stderrOrError(result);
+    const stdout = result.stdout.trim();
+    if (opts.both === true)
+        return [stderr, stdout].filter(Boolean).join('\n');
+    return stderr || stdout || `exit ${result.exitCode}`;
+}
+/**
+ * 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 function firstLine(text, fallback = '') {
+    return (text
+        .split('\n')
+        .map((l) => l.trim())
+        .find((l) => l !== '') ?? fallback);
+}
+/**
+ * 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 function parseJsonResult(result, opts = {}) {
+    const okExitCodes = opts.okExitCodes ?? [0];
+    if (result.neverExited === true || !okExitCodes.includes(result.exitCode)) {
+        return { ok: false, reason: 'failed', message: failureText(result), result };
+    }
+    const parsed = tryParse(result.stdout, opts.tolerateLeadingLog === true);
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            reason: 'unparseable',
+            message: `stdout is not JSON: ${parsed.error}`,
+            result,
+        };
+    }
+    if (opts.parse === undefined)
+        return { ok: true, value: parsed.value, result };
+    let value;
+    try {
+        value = opts.parse(parsed.value);
+    }
+    catch (e) {
+        const why = e instanceof Error ? e.message : String(e);
+        return {
+            ok: false,
+            reason: 'invalid',
+            message: `stdout JSON was rejected: ${why}`,
+            cause: e,
+            result,
+        };
+    }
+    if (isThenable(value)) {
+        // An async `parse` (such as `parseAsync`): its verdict would arrive too
+        // late, so say so, and keep its rejection from going unhandled.
+        value.then(undefined, () => { });
+        return {
+            ok: false,
+            reason: 'invalid',
+            message: 'stdout JSON was rejected: parse returned a promise; it must be sync',
+            cause: value,
+            result,
+        };
+    }
+    return { ok: true, value, result };
+}
+function isThenable(v) {
+    return ((typeof v === 'object' || typeof v === 'function') &&
+        v !== null &&
+        typeof v.then === 'function');
+}
+function tryParse(stdout, tolerateLeadingLog) {
+    try {
+        return { ok: true, value: JSON.parse(stdout) };
+    }
+    catch (e) {
+        const start = tolerateLeadingLog ? jsonStart(stdout) : -1;
+        if (start > 0) {
+            try {
+                return { ok: true, value: JSON.parse(stdout.slice(start)) };
+            }
+            catch {
+                // Report the whole-stdout error below.
+            }
+        }
+        return { ok: false, error: e.message };
+    }
+}
+/**
+ * Where the JSON starts for `tolerateLeadingLog`: the line starting with `{` or
+ * `[` whose brackets stay open until the last bracket in stdout closes them.
+ * Only that line's suffix can parse, so stdout is parsed once more at most.
+ * A JSON string holds no raw line break, so string state resets at each one.
+ * `-1` when no line qualifies.
+ */
+function jsonStart(stdout) {
+    // The bracket depth after each bracket outside a string, in order.
+    const depths = [];
+    // Each candidate line: where it starts, its first bracket's index in
+    // `depths`, and the depth before that bracket.
+    const lines = [];
+    let depth = 0;
+    let inString = false;
+    for (let i = 0; i < stdout.length; i++) {
+        const c = stdout[i];
+        if (c === '\n' || c === '\r') {
+            inString = false;
+        }
+        else if (inString) {
+            if (c === '"')
+                inString = false;
+            else if (c === '\\' && stdout[i + 1] !== '\n' && stdout[i + 1] !== '\r')
+                i++;
+        }
+        else if (c === '"') {
+            inString = true;
+        }
+        else if (c === '{' || c === '[') {
+            const prev = stdout[i - 1];
+            if (prev === '\n' || prev === '\r')
+                lines.push({ at: i, first: depths.length, before: depth });
+            depths.push(++depth);
+        }
+        else if (c === '}' || c === ']') {
+            depths.push(--depth);
+        }
+    }
+    const end = depths.at(-1);
+    // The lowest depth from each bracket on, leaving out the last bracket.
+    let low = Infinity;
+    let next = depths.length - 2;
+    for (let k = lines.length - 1; k >= 0; k--) {
+        const { at, first, before } = lines[k];
+        for (; next >= first; next--)
+            low = Math.min(low, depths[next]);
+        if (before === end && low > before)
+            return at;
+    }
+    return -1;
+}
+export function runJson(runner, argv, ...opts) {
+    const { run, json } = splitJsonOptions(opts);
+    return parseJsonResult(runner.run(argv, ...run), json);
+}
+export async function runJsonAsync(runner, argv, ...opts) {
+    const { run, json } = splitJsonOptions(opts);
+    return parseJsonResult(await runner.run(argv, ...run), json);
+}
+/** Split `runJson`'s options into the runner's and the parse step's. */
+function splitJsonOptions(opts) {
+    if (opts[0] === undefined)
+        return { run: [], json: {} };
+    const { tolerateLeadingLog, parse, okExitCodes, ...run } = opts[0];
+    return { run: [run], json: { tolerateLeadingLog, parse, okExitCodes } };
+}

package/dist/shell.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The shell runner: the one place in this package that runs a shell string.
+ *
+ * Every other runner passes argv straight to a binary, so nothing is parsed
+ * as shell. A configured command such as `bun install --filter '@x/y'` or
+ * `a && b` is a shell string by nature, and it runs as `sh -c -- <verb>`.
+ * Keeping that call in one place makes shell use easy to find and audit, and
+ * keeps the invocation the same everywhere.
+ *
+ * Built on the capture runners, so it uses their types
+ * ({@link CommandResult}, {@link CommandRunOptions}, `CommandFailed`) and
+ * their timeout, env and stdin handling.
+ */
+import { type AsyncCommandRunner, type AsyncCommandRunOptions } from './async.ts';
+import { type CommandResult, type CommandRunner, type CommandRunOptions } from './sync.ts';
+/**
+ * Positional parameters for the verb. They ride as separate argv entries,
+ * never spliced into the string, so they are inert data.
+ */
+export interface ShellPositionals {
+    /** Sets `$0`, the name the script sees for itself, used in its error messages. Default `sh`. */
+    scriptName?: string | undefined;
+    /** Visible to the script as `$1`, `$2`, … */
+    args?: readonly string[] | undefined;
+}
+/** {@link CommandRunOptions} plus {@link ShellPositionals}. */
+export interface ShellRunOptions extends CommandRunOptions, ShellPositionals {
+}
+/** {@link ShellPositionals} plus the async runner's options. */
+export interface AsyncShellRunOptions extends AsyncCommandRunOptions, ShellPositionals {
+}
+/** Runs a shell string. `verb` is interpreted by `sh`, so quote data with `shellQuote`. */
+export interface ShellRunner {
+    run(verb: string, opts: ShellRunOptions): CommandResult;
+}
+/**
+ * The async version of {@link ShellRunner}.
+ *
+ * @experimental
+ */
+export interface AsyncShellRunner {
+    run(verb: string, opts: AsyncShellRunOptions): Promise<CommandResult>;
+}
+/**
+ * A {@link ShellRunner} over `sh`. Pass `sh` to run through a different
+ * {@link CommandRunner}, such as a test fake. An invalid `timeoutMs` throws
+ * before `sh` is called, as it does on the capture runners.
+ *
+ * @param sh - The runner that receives `['-c', '--', verb]`, then
+ * `scriptName` and `args` when given. Defaults to `spawnRunner('sh')`.
+ */
+export declare function shellRunner(sh?: CommandRunner): ShellRunner;
+/**
+ * The async version of {@link shellRunner}. Wrap a sync fake with `asAsync`
+ * to pass it in. An invalid `timeoutMs` rejects before `sh` is called.
+ *
+ * @param sh - The runner that receives `['-c', '--', verb]`, then
+ * `scriptName` and `args` when given. Defaults to `spawnRunnerAsync('sh')`.
+ * @experimental
+ */
+export declare function shellRunnerAsync(sh?: AsyncCommandRunner): AsyncShellRunner;
+/**
+ * Run `verb` once through `sh -c --` and capture the result. Needs `sh` on
+ * `PATH`. Never throws for a failed command, like `spawnRunner`; programmer
+ * errors such as an invalid `timeoutMs` throw.
+ *
+ * @param verb - A shell string. Quote any data in it with `shellQuote`, or
+ * pass it through `args`.
+ * @param opts - The capture options plus `scriptName` (`$0`) and `args` (`$1`…).
+ * @returns The captured result.
+ *
+ * @example
+ * ```ts
+ * const r = runShell('ls "$1" | wc -l', { cwd: '.', args: ['my dir'] })
+ * console.log(r.stdout.trim())
+ * ```
+ */
+export declare function runShell(verb: string, opts: ShellRunOptions): CommandResult;
+/**
+ * The async version of {@link runShell}. Never rejects for a failed command;
+ * rejects for programmer errors such as an invalid `timeoutMs`.
+ */
+export declare function runShellAsync(verb: string, opts: AsyncShellRunOptions): Promise<CommandResult>;
+//# sourceMappingURL=shell.d.ts.map

package/dist/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAoB,KAAK,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,YAAY,CAAA;AACnG,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACvB,MAAM,WAAW,CAAA;AAElB;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gGAAgG;IAChG,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,6CAA6C;IAC7C,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;CACrC;AAED,+DAA+D;AAC/D,MAAM,WAAW,eAAgB,SAAQ,iBAAiB,EAAE,gBAAgB;CAAG;AAE/E,gEAAgE;AAChE,MAAM,WAAW,oBAAqB,SAAQ,sBAAsB,EAAE,gBAAgB;CAAG;AAEzF,2FAA2F;AAC3F,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,aAAa,CAAA;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CACtE;AAgBD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,EAAE,GAAE,aAAiC,GAAG,WAAW,CAO9E;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,GAAE,kBAA2C,GAC9C,gBAAgB,CAOlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,aAAa,CAE3E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CAE9F"}

package/dist/shell.js

@@ -0,0 +1,83 @@
+/**
+ * The shell runner: the one place in this package that runs a shell string.
+ *
+ * Every other runner passes argv straight to a binary, so nothing is parsed
+ * as shell. A configured command such as `bun install --filter '@x/y'` or
+ * `a && b` is a shell string by nature, and it runs as `sh -c -- <verb>`.
+ * Keeping that call in one place makes shell use easy to find and audit, and
+ * keeps the invocation the same everywhere.
+ *
+ * Built on the capture runners, so it uses their types
+ * ({@link CommandResult}, {@link CommandRunOptions}, `CommandFailed`) and
+ * their timeout, env and stdin handling.
+ */
+import { spawnRunnerAsync } from "./async.js";
+import { normalizeTimeout, spawnRunner, } from "./sync.js";
+/**
+ * The `sh -c -- <verb>` argv; `$0`/`$1…` are appended only when given. The
+ * `--` keeps a verb that starts with `-` or `+` from being read as an option.
+ */
+function shellArgv(verb, scriptName, args) {
+    const rest = args ?? [];
+    if (scriptName === undefined && rest.length === 0)
+        return ['-c', '--', verb];
+    return ['-c', '--', verb, scriptName ?? 'sh', ...rest];
+}
+/**
+ * A {@link ShellRunner} over `sh`. Pass `sh` to run through a different
+ * {@link CommandRunner}, such as a test fake. An invalid `timeoutMs` throws
+ * before `sh` is called, as it does on the capture runners.
+ *
+ * @param sh - The runner that receives `['-c', '--', verb]`, then
+ * `scriptName` and `args` when given. Defaults to `spawnRunner('sh')`.
+ */
+export function shellRunner(sh = spawnRunner('sh')) {
+    return {
+        run: (verb, { scriptName, args, ...opts }) => {
+            normalizeTimeout(opts.timeoutMs);
+            return sh.run(shellArgv(verb, scriptName, args), opts);
+        },
+    };
+}
+/**
+ * The async version of {@link shellRunner}. Wrap a sync fake with `asAsync`
+ * to pass it in. An invalid `timeoutMs` rejects before `sh` is called.
+ *
+ * @param sh - The runner that receives `['-c', '--', verb]`, then
+ * `scriptName` and `args` when given. Defaults to `spawnRunnerAsync('sh')`.
+ * @experimental
+ */
+export function shellRunnerAsync(sh = spawnRunnerAsync('sh')) {
+    return {
+        run: async (verb, { scriptName, args, ...opts }) => {
+            normalizeTimeout(opts.timeoutMs);
+            return sh.run(shellArgv(verb, scriptName, args), opts);
+        },
+    };
+}
+/**
+ * Run `verb` once through `sh -c --` and capture the result. Needs `sh` on
+ * `PATH`. Never throws for a failed command, like `spawnRunner`; programmer
+ * errors such as an invalid `timeoutMs` throw.
+ *
+ * @param verb - A shell string. Quote any data in it with `shellQuote`, or
+ * pass it through `args`.
+ * @param opts - The capture options plus `scriptName` (`$0`) and `args` (`$1`…).
+ * @returns The captured result.
+ *
+ * @example
+ * ```ts
+ * const r = runShell('ls "$1" | wc -l', { cwd: '.', args: ['my dir'] })
+ * console.log(r.stdout.trim())
+ * ```
+ */
+export function runShell(verb, opts) {
+    return shellRunner().run(verb, opts);
+}
+/**
+ * The async version of {@link runShell}. Never rejects for a failed command;
+ * rejects for programmer errors such as an invalid `timeoutMs`.
+ */
+export function runShellAsync(verb, opts) {
+    return shellRunnerAsync().run(verb, opts);
+}

package/dist/stream.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The streaming runner: the {@link StreamRunner} interface and its
+ * `spawnSync`-backed default, {@link streamRunner}.
+ *
+ * Use it for a command whose output a person must see live: a build, a test
+ * run, or an interactive program. The capture runners would hold all output
+ * until the child exited. Options are {@link CommandRunOptions} without
+ * `input`, since stdin is inherited, not piped. Code takes a `StreamRunner`
+ * the same way it takes a `CommandRunner`, and tests pass a fake. Mixed stdio
+ * (say, a child's stdout sent to the parent's stderr) is out of scope; call
+ * `child_process` directly for that.
+ *
+ * There is no async version: `run` blocks until the child exits, as
+ * `spawnRunner` does.
+ */
+import { type CommandRunOptions, type NeverExitedReason } from './sync.ts';
+/**
+ * Per-call options for a {@link StreamRunner}. Same as {@link
+ * CommandRunOptions} minus `input`: stdin is inherited from the parent
+ * process, not fed programmatically, so there is nothing to write to.
+ */
+export type StreamRunOptions = Omit<CommandRunOptions, 'input'>;
+/**
+ * Result of a streamed run. There is no output to report, since it went
+ * straight to the inherited stdio; only how the child ended.
+ */
+export interface StreamResult {
+    /** The child's exit code, or `1` when it never reported one (see `neverExited`). */
+    exitCode: number;
+    /**
+     * The child never reported an exit status: the spawn failed, the timeout
+     * killed it, or a signal took it down. Same meaning as
+     * `CommandResult.neverExited`. A message is also written to the parent's
+     * stderr.
+     */
+    neverExited?: boolean | undefined;
+    /**
+     * Why the child never reported an exit status: `spawn`, `timeout` or
+     * `signal` (a streamed run cannot be aborted, and its output is not
+     * captured, so there is no cap). Set whenever `neverExited`
+     * is, absent otherwise.
+     */
+    reason?: Exclude<NeverExitedReason, 'abort' | 'output'> | undefined;
+    /**
+     * The signal that ended the child, for `reason: 'signal'` and
+     * `reason: 'timeout'` (`SIGKILL`).
+     */
+    signal?: NodeJS.Signals | undefined;
+    /**
+     * The runner's error message when the spawn failed or the timeout fired,
+     * such as `spawnSync npm ENOENT`. The same text is written to the parent's
+     * stderr.
+     */
+    error?: string | undefined;
+}
+/** Runs a binary with inherited stdio instead of capturing it. */
+export interface StreamRunner {
+    /**
+     * Run the binary with `argv` (without the binary name) and wait for it to
+     * exit. Never throws for a failed command. Programmer errors throw: an
+     * invalid `timeoutMs` (see `CommandRunOptions.timeoutMs`) or a NUL byte in
+     * argv or env.
+     */
+    run(argv: string[], opts: StreamRunOptions): StreamResult;
+}
+/**
+ * The default {@link StreamRunner}: runs `binary` with `spawnSync` and
+ * `stdio: 'inherit'`, so the child's prompts, progress and output reach the
+ * terminal directly. It behaves like a direct `spawnSync` call, but code
+ * takes it as a parameter, so tests can pass a fake. On timeout the direct
+ * child gets `SIGKILL`. Processes it started keep running: this runner has
+ * no `processGroup` option.
+ *
+ * When the spawn fails, the timeout fires or a signal ends the child, a
+ * message is written to the parent's stderr, since there is no captured
+ * stderr to carry it. The result says why in `reason`, and carries the spawn
+ * or timeout message in `error`.
+ *
+ * @param binary - A name looked up on `PATH`, or a path.
+ * @returns A runner for that binary.
+ *
+ * @example
+ * ```ts
+ * const npm = streamRunner('npm')
+ * const { exitCode } = npm.run(['run', 'build'], { cwd: '.' })
+ * process.exitCode = exitCode
+ * ```
+ */
+export declare function streamRunner(binary: string): StreamRunner;
+//# sourceMappingURL=stream.d.ts.map

package/dist/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAKL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,WAAW,CAAA;AAElB;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAA;AAE/D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACjC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,EAAE,OAAO,GAAG,QAAQ,CAAC,GAAG,SAAS,CAAA;IACnE;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,SAAS,CAAA;IACnC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC3B;AAED,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAAA;CAC1D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CA+BzD"}

package/dist/stream.js

@@ -0,0 +1,73 @@
+/**
+ * The streaming runner: the {@link StreamRunner} interface and its
+ * `spawnSync`-backed default, {@link streamRunner}.
+ *
+ * Use it for a command whose output a person must see live: a build, a test
+ * run, or an interactive program. The capture runners would hold all output
+ * until the child exited. Options are {@link CommandRunOptions} without
+ * `input`, since stdin is inherited, not piped. Code takes a `StreamRunner`
+ * the same way it takes a `CommandRunner`, and tests pass a fake. Mixed stdio
+ * (say, a child's stdout sent to the parent's stderr) is out of scope; call
+ * `child_process` directly for that.
+ *
+ * There is no async version: `run` blocks until the child exits, as
+ * `spawnRunner` does.
+ */
+import { spawnSync } from 'node:child_process';
+import { cwdError, mergedEnv, normalizeTimeout, syncStop, } from "./sync.js";
+/**
+ * The default {@link StreamRunner}: runs `binary` with `spawnSync` and
+ * `stdio: 'inherit'`, so the child's prompts, progress and output reach the
+ * terminal directly. It behaves like a direct `spawnSync` call, but code
+ * takes it as a parameter, so tests can pass a fake. On timeout the direct
+ * child gets `SIGKILL`. Processes it started keep running: this runner has
+ * no `processGroup` option.
+ *
+ * When the spawn fails, the timeout fires or a signal ends the child, a
+ * message is written to the parent's stderr, since there is no captured
+ * stderr to carry it. The result says why in `reason`, and carries the spawn
+ * or timeout message in `error`.
+ *
+ * @param binary - A name looked up on `PATH`, or a path.
+ * @returns A runner for that binary.
+ *
+ * @example
+ * ```ts
+ * const npm = streamRunner('npm')
+ * const { exitCode } = npm.run(['run', 'build'], { cwd: '.' })
+ * process.exitCode = exitCode
+ * ```
+ */
+export function streamRunner(binary) {
+    return {
+        run(argv, opts) {
+            const timeout = normalizeTimeout(opts.timeoutMs);
+            const cwdMessage = cwdError(`spawnSync ${binary}`, binary, argv, opts);
+            if (cwdMessage !== undefined) {
+                process.stderr.write(`${cwdMessage}\n`);
+                return { exitCode: 1, neverExited: true, reason: 'spawn', error: cwdMessage };
+            }
+            const proc = spawnSync(binary, argv, {
+                cwd: opts.cwd,
+                stdio: 'inherit',
+                timeout,
+                // See `sync.ts`'s `runViaChildRedirect`: the default SIGTERM is not a
+                // hard cap.
+                killSignal: 'SIGKILL',
+                ...mergedEnv(opts),
+            });
+            // `spawnSync` reports a stop as a missing `status` (null, or undefined
+            // under Bun for a failed spawn), with `error` and `signal` saying why.
+            if (proc.status != null)
+                return { exitCode: proc.status };
+            // Output is inherited, not buffered, so the output cap cannot apply.
+            const stop = syncStop(proc);
+            if (proc.error !== undefined) {
+                process.stderr.write(`${proc.error.message}\n`);
+                return { exitCode: 1, neverExited: true, ...stop, error: proc.error.message };
+            }
+            process.stderr.write(`${binary} was killed by ${proc.signal}\n`);
+            return { exitCode: 1, neverExited: true, ...stop };
+        },
+    };
+}