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

package/dist/groups.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Live process groups, and forwarding of termination signals to them.
+ *
+ * A child started with `processGroup: true` leads its own group and no longer
+ * receives the terminal's Ctrl-C. When the host is then killed by `SIGINT`,
+ * `SIGTERM` or `SIGHUP`, the child and everything it started would be orphaned
+ * (ppid 1). The runners register each such group here, and
+ * {@link installGroupSignalForwarding} makes the host kill them when it is
+ * signalled. A group stays registered until it is empty. Once its run has
+ * settled, the host's normal exit leaves what is left of it running, such as a
+ * daemon; a forwarded signal still kills it.
+ *
+ * Once a signal has been forwarded and this module owns the exit, the host is
+ * stopping: the runners refuse to start a new group, and
+ * {@link forwardedSignal} tells the host's own code to stop.
+ *
+ * The signal listeners exist only while a group is starting or registered. A
+ * JS listener replaces the default "terminate" action and runs only when the
+ * event loop turns, so keeping one armed would make a host blocked in a sync
+ * spawn ignore a signal it would otherwise die from.
+ */
+/**
+ * Options for {@link installGroupSignalForwarding}.
+ *
+ * @experimental
+ */
+export interface GroupSignalForwardingOptions {
+    /** Signals to forward. Default `SIGINT`, `SIGTERM` and `SIGHUP`. */
+    signals?: readonly NodeJS.Signals[] | undefined;
+    /**
+     * How long the groups have between `SIGTERM` and `SIGKILL`, in ms. Default
+     * 1000: long enough for git to remove its lock files.
+     */
+    graceMs?: number | undefined;
+    /**
+     * Called to end the process, with `128 + signal number`. Default: set
+     * `process.exitCode` and let the event loop drain, so piped stdout is not
+     * truncated, then `process.exit` after 500 ms if handles still hold the loop.
+     * Tests replace it.
+     */
+    exit?: ((code: number) => void) | undefined;
+}
+/**
+ * Register a group leader. The returned function unregisters it; call it once
+ * the group is gone so a reused pid is never signalled. Registering the first
+ * group arms the signal listeners (when forwarding is installed); removing the
+ * last disarms them.
+ *
+ * @internal
+ */
+export declare function trackGroup(pid: number): () => void;
+/**
+ * Start a group leader with `start` and register it. The listeners are armed
+ * before `start` runs: the child can print, and the host be signalled, before
+ * `spawn` returns, and a signal that comes before the listeners would kill the
+ * host by default and orphan the group. `untrack` is `undefined` when the
+ * child got no pid.
+ *
+ * @internal
+ */
+export declare function spawnTrackedGroup<C extends {
+    readonly pid?: number | undefined;
+}>(start: () => C): {
+    child: C;
+    untrack: (() => void) | undefined;
+};
+/**
+ * Mark the run of the group led by `pid` as settled: the host's exit no longer
+ * kills what is left of the group. A forwarded signal still does. A runner
+ * does not call this for a group it is stopping itself.
+ *
+ * @internal
+ */
+export declare function settleGroup(pid: number): void;
+/**
+ * Why a new group must not start, or `undefined` when it may. The runners call
+ * this before they spawn with `processGroup: true`.
+ *
+ * @internal
+ */
+export declare function groupStartRefusal(): string | undefined;
+/**
+ * Run `release` once the group led by `pid` has no member: now if it is
+ * already empty, else polled on an unref'd timer.
+ *
+ * Unref'd on purpose: a ref'd poll would keep the host alive for as long as a
+ * member the group left behind. On a Bun version where an unref'd timer does
+ * not fire (see `async.ts`), the entry stays registered. The listeners then
+ * stay armed and a signal still kills that member, which is the safe side.
+ *
+ * @internal
+ */
+export declare function releaseWhenEmpty(pid: number, release: () => void): void;
+/**
+ * True while the group led by `pid` still has a member.
+ *
+ * @internal
+ */
+export declare function groupExists(pid: number): boolean;
+/**
+ * The pids of the live process groups started with `processGroup: true`.
+ *
+ * @experimental
+ */
+export declare function liveProcessGroups(): number[];
+/**
+ * The signal the host was sent and forwarded to its groups, or `undefined`
+ * while none has been. Set only when forwarding owns the exit, that is, the
+ * host has no listener of its own for that signal. Once set, the host is
+ * stopping: a loop that runs one command after another should check it and
+ * stop, and the runners refuse to start a new `processGroup` run. The
+ * uninstall function clears it.
+ *
+ * @experimental
+ */
+export declare function forwardedSignal(): NodeJS.Signals | undefined;
+/**
+ * The exit code for {@link forwardedSignal}: `128 + signal number`, or
+ * `undefined` while no signal has been forwarded. A host that sets its own
+ * exit code after its work returns keeps this one over it:
+ * `process.exitCode = forwardedExitCode() ?? code`.
+ *
+ * @experimental
+ */
+export declare function forwardedExitCode(): number | undefined;
+/**
+ * Enable forwarding of termination signals to live process groups.
+ *
+ * While at least one group started with `processGroup: true` is live, `SIGINT`,
+ * `SIGTERM` and `SIGHUP` send `SIGTERM` to every registered group, then
+ * `SIGKILL` to those still registered after `graceMs`, then end the process
+ * with `128 + signal number`, the shell convention. A second signal during the
+ * grace, or any later one, skips straight to `SIGKILL` and the exit. From the
+ * first signal on, {@link forwardedSignal} returns it and the runners refuse
+ * to start a new `processGroup` run, until the uninstall function resets
+ * that. A `process` `exit` handler, armed with the listeners, also `SIGKILL`s
+ * every group whose run is still in flight, so a host that exits first does
+ * not leave one behind. A member that a settled run left behind, such as a
+ * daemon, outlives the host's exit; a forwarded signal still kills it.
+ *
+ * The listeners are attached just before the first group starts and removed
+ * when the last one goes, so a host with no live group keeps each signal's default
+ * action. If the host has its own listener for the signal (`process.once`
+ * counts too), the groups still
+ * get `SIGTERM` at once and `SIGKILL` after `graceMs` (or on `exit`, if
+ * sooner and the run is in flight), but that listener keeps the exit, and later runs are not refused.
+ * Calling it again while installed is a no-op returning the same
+ * uninstall function. `SIGKILL` of the host cannot be caught and still orphans
+ * its groups. POSIX only; a no-op on Windows.
+ *
+ * @returns A function that removes the forwarding.
+ * @experimental
+ */
+export declare function installGroupSignalForwarding(opts?: GroupSignalForwardingOptions): () => void;
+//# sourceMappingURL=groups.d.ts.map

package/dist/groups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups.d.ts","sourceRoot":"","sources":["../groups.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAWH;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,oEAAoE;IACpE,OAAO,CAAC,EAAE,SAAS,MAAM,CAAC,OAAO,EAAE,GAAG,SAAS,CAAA;IAC/C;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;CAC5C;AAyBD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,IAAI,CAOlD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EAC/E,KAAK,EAAE,MAAM,CAAC,GACb;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAA;CAAE,CAUjD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAG7C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAGtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAWvE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOhD;AAYD;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAAC,OAAO,GAAG,SAAS,CAE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD;AA4DD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,GAAE,4BAAiC,GAAG,MAAM,IAAI,CAUhG"}

package/dist/groups.js

@@ -0,0 +1,331 @@
+/**
+ * Live process groups, and forwarding of termination signals to them.
+ *
+ * A child started with `processGroup: true` leads its own group and no longer
+ * receives the terminal's Ctrl-C. When the host is then killed by `SIGINT`,
+ * `SIGTERM` or `SIGHUP`, the child and everything it started would be orphaned
+ * (ppid 1). The runners register each such group here, and
+ * {@link installGroupSignalForwarding} makes the host kill them when it is
+ * signalled. A group stays registered until it is empty. Once its run has
+ * settled, the host's normal exit leaves what is left of it running, such as a
+ * daemon; a forwarded signal still kills it.
+ *
+ * Once a signal has been forwarded and this module owns the exit, the host is
+ * stopping: the runners refuse to start a new group, and
+ * {@link forwardedSignal} tells the host's own code to stop.
+ *
+ * The signal listeners exist only while a group is starting or registered. A
+ * JS listener replaces the default "terminate" action and runs only when the
+ * event loop turns, so keeping one armed would make a host blocked in a sync
+ * spawn ignore a signal it would otherwise die from.
+ */
+import { constants } from 'node:os';
+const osSignals = constants.signals;
+/** Live group leaders, in start order, and whether each one's run has settled. */
+const live = new Map();
+/** Group spawns in progress: the listeners are armed before their pid is known. */
+let spawning = 0;
+const DEFAULT_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+const POLL_MS = 25;
+/** Set while forwarding is installed. */
+let config;
+/** Set while the listeners are attached: forwarding installed and a group starting or live. */
+let armed;
+/**
+ * The first signal forwarded since install whose exit this module owns (the
+ * host has no listener of its own for it). Cleared only by uninstall.
+ */
+let forwarded;
+/** Set while a graceful kill is waiting out its grace. */
+let killing = false;
+/** A repeat signal already sent `SIGKILL`: the graceful kill stops waiting. */
+let escalated = false;
+/**
+ * Register a group leader. The returned function unregisters it; call it once
+ * the group is gone so a reused pid is never signalled. Registering the first
+ * group arms the signal listeners (when forwarding is installed); removing the
+ * last disarms them.
+ *
+ * @internal
+ */
+export function trackGroup(pid) {
+    live.set(pid, { settled: false });
+    arm();
+    return () => {
+        live.delete(pid);
+        disarmIfIdle();
+    };
+}
+/**
+ * Start a group leader with `start` and register it. The listeners are armed
+ * before `start` runs: the child can print, and the host be signalled, before
+ * `spawn` returns, and a signal that comes before the listeners would kill the
+ * host by default and orphan the group. `untrack` is `undefined` when the
+ * child got no pid.
+ *
+ * @internal
+ */
+export function spawnTrackedGroup(start) {
+    spawning += 1;
+    arm();
+    try {
+        const child = start();
+        return { child, untrack: child.pid === undefined ? undefined : trackGroup(child.pid) };
+    }
+    finally {
+        spawning -= 1;
+        disarmIfIdle();
+    }
+}
+/**
+ * Mark the run of the group led by `pid` as settled: the host's exit no longer
+ * kills what is left of the group. A forwarded signal still does. A runner
+ * does not call this for a group it is stopping itself.
+ *
+ * @internal
+ */
+export function settleGroup(pid) {
+    const entry = live.get(pid);
+    if (entry !== undefined)
+        entry.settled = true;
+}
+/**
+ * Why a new group must not start, or `undefined` when it may. The runners call
+ * this before they spawn with `processGroup: true`.
+ *
+ * @internal
+ */
+export function groupStartRefusal() {
+    if (forwarded === undefined)
+        return undefined;
+    return `not started: the host got ${forwarded} and is stopping`;
+}
+/**
+ * Run `release` once the group led by `pid` has no member: now if it is
+ * already empty, else polled on an unref'd timer.
+ *
+ * Unref'd on purpose: a ref'd poll would keep the host alive for as long as a
+ * member the group left behind. On a Bun version where an unref'd timer does
+ * not fire (see `async.ts`), the entry stays registered. The listeners then
+ * stay armed and a signal still kills that member, which is the safe side.
+ *
+ * @internal
+ */
+export function releaseWhenEmpty(pid, release) {
+    if (!groupExists(pid)) {
+        release();
+        return;
+    }
+    const timer = setInterval(() => {
+        if (groupExists(pid))
+            return;
+        clearInterval(timer);
+        release();
+    }, 250);
+    timer.unref();
+}
+/**
+ * True while the group led by `pid` still has a member.
+ *
+ * @internal
+ */
+export function groupExists(pid) {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Send `sig` to the group led by `pid`, only while it is registered. */
+function signalGroup(pid, sig) {
+    if (!live.has(pid))
+        return;
+    try {
+        process.kill(-pid, sig);
+    }
+    catch {
+        // Already gone.
+    }
+}
+/**
+ * The pids of the live process groups started with `processGroup: true`.
+ *
+ * @experimental
+ */
+export function liveProcessGroups() {
+    return [...live.keys()];
+}
+/**
+ * The signal the host was sent and forwarded to its groups, or `undefined`
+ * while none has been. Set only when forwarding owns the exit, that is, the
+ * host has no listener of its own for that signal. Once set, the host is
+ * stopping: a loop that runs one command after another should check it and
+ * stop, and the runners refuse to start a new `processGroup` run. The
+ * uninstall function clears it.
+ *
+ * @experimental
+ */
+export function forwardedSignal() {
+    return forwarded;
+}
+/**
+ * The exit code for {@link forwardedSignal}: `128 + signal number`, or
+ * `undefined` while no signal has been forwarded. A host that sets its own
+ * exit code after its work returns keeps this one over it:
+ * `process.exitCode = forwardedExitCode() ?? code`.
+ *
+ * @experimental
+ */
+export function forwardedExitCode() {
+    return forwarded === undefined ? undefined : 128 + signalNumber(forwarded);
+}
+function arm() {
+    if (config === undefined || armed !== undefined || (live.size === 0 && spawning === 0))
+        return;
+    const { signals, graceMs, exit } = config;
+    const onExit = () => {
+        // The host is going away: nothing async runs after this, so end every group
+        // whose run is still in flight now. A settled run's leftovers stay.
+        for (const [pid, { settled }] of live)
+            if (!settled)
+                signalGroup(pid, 'SIGKILL');
+    };
+    const handlers = signals.map((sig) => {
+        const handler = () => {
+            const code = 128 + signalNumber(sig);
+            if (forwarded !== undefined || killing) {
+                // A repeat signal: stop waiting.
+                escalated = true;
+                for (const pid of live.keys())
+                    signalGroup(pid, 'SIGKILL');
+                if (!othersListen(sig))
+                    exit(code);
+                return;
+            }
+            // A host listener owns the exit and may keep running (a REPL cancelling
+            // a job, a daemon reloading on SIGHUP): kill the groups, but do not
+            // refuse later runs.
+            const othersOwnExit = othersListen(sig);
+            if (!othersOwnExit)
+                forwarded = sig;
+            killing = true;
+            escalated = false;
+            void killAll(graceMs).then(() => {
+                killing = false;
+                if (!escalated && !othersOwnExit)
+                    exit(code);
+            });
+        };
+        // First in line: Node and Bun drop a host's `process.once` wrapper before
+        // calling it, so a handler that ran later would not count that listener.
+        process.prependListener(sig, handler);
+        return [sig, handler];
+    });
+    process.on('exit', onExit);
+    armed = {
+        off: () => {
+            for (const [sig, handler] of handlers)
+                process.off(sig, handler);
+            process.off('exit', onExit);
+        },
+    };
+}
+function disarm() {
+    armed?.off();
+    armed = undefined;
+}
+function disarmIfIdle() {
+    if (live.size === 0 && spawning === 0)
+        disarm();
+}
+/** Another listener than ours is attached for `sig`: it owns the exit. */
+function othersListen(sig) {
+    return process.listenerCount(sig) > 1;
+}
+/**
+ * Enable forwarding of termination signals to live process groups.
+ *
+ * While at least one group started with `processGroup: true` is live, `SIGINT`,
+ * `SIGTERM` and `SIGHUP` send `SIGTERM` to every registered group, then
+ * `SIGKILL` to those still registered after `graceMs`, then end the process
+ * with `128 + signal number`, the shell convention. A second signal during the
+ * grace, or any later one, skips straight to `SIGKILL` and the exit. From the
+ * first signal on, {@link forwardedSignal} returns it and the runners refuse
+ * to start a new `processGroup` run, until the uninstall function resets
+ * that. A `process` `exit` handler, armed with the listeners, also `SIGKILL`s
+ * every group whose run is still in flight, so a host that exits first does
+ * not leave one behind. A member that a settled run left behind, such as a
+ * daemon, outlives the host's exit; a forwarded signal still kills it.
+ *
+ * The listeners are attached just before the first group starts and removed
+ * when the last one goes, so a host with no live group keeps each signal's default
+ * action. If the host has its own listener for the signal (`process.once`
+ * counts too), the groups still
+ * get `SIGTERM` at once and `SIGKILL` after `graceMs` (or on `exit`, if
+ * sooner and the run is in flight), but that listener keeps the exit, and later runs are not refused.
+ * Calling it again while installed is a no-op returning the same
+ * uninstall function. `SIGKILL` of the host cannot be caught and still orphans
+ * its groups. POSIX only; a no-op on Windows.
+ *
+ * @returns A function that removes the forwarding.
+ * @experimental
+ */
+export function installGroupSignalForwarding(opts = {}) {
+    if (process.platform === 'win32')
+        return () => { };
+    if (config !== undefined)
+        return uninstall;
+    config = {
+        signals: opts.signals ?? DEFAULT_SIGNALS,
+        graceMs: opts.graceMs ?? 1000,
+        exit: opts.exit ?? defaultExit,
+    };
+    arm();
+    return uninstall;
+}
+function uninstall() {
+    disarm();
+    config = undefined;
+    forwarded = undefined;
+    killing = false;
+    escalated = false;
+}
+/**
+ * Set the exit code and let output drain; force the exit after 500 ms. Not
+ * unref'd: an unref'd timer does not reliably fire on every Bun version, and
+ * holding the loop for 500 ms after a signal is cheap.
+ */
+function defaultExit(code) {
+    process.exitCode = code;
+    setTimeout(() => process.exit(code), 500);
+}
+/**
+ * `SIGTERM` every registered group, wait up to `graceMs` for them to go, then
+ * `SIGKILL` those still registered. Stops early when `escalated` says a repeat
+ * signal already did the kill.
+ */
+async function killAll(graceMs) {
+    // Drop entries whose group is already empty, so a stale pid is never signalled.
+    for (const pid of liveProcessGroups())
+        if (!groupExists(pid))
+            live.delete(pid);
+    for (const pid of liveProcessGroups())
+        signalGroup(pid, 'SIGTERM');
+    const deadline = performance.now() + graceMs;
+    while (!escalated && performance.now() < deadline) {
+        if (!liveProcessGroups().some(groupExists))
+            return;
+        await new Promise((res) => setTimeout(res, POLL_MS));
+    }
+    if (escalated)
+        return;
+    for (const pid of liveProcessGroups())
+        if (groupExists(pid))
+            signalGroup(pid, 'SIGKILL');
+}
+function signalNumber(sig) {
+    const n = osSignals[sig];
+    return typeof n === 'number' ? n : 15;
+}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `@osdlc/command-seam`: run external commands through a small interface
+ * that tests can replace.
+ *
+ * A runner is an object with a `run` method. Code that needs a command takes
+ * a runner as a parameter. Production passes a real one; tests pass a fake.
+ *
+ * - `spawnRunner` / `spawnRunnerAsync` capture a finished run's output
+ *   ({@link CommandResult}).
+ * - `runShell` / `shellRunner` run a shell string through `sh -c --`.
+ * - `streamRunner` runs with inherited stdio, so output appears live.
+ * - `managedProcessRunner` starts a process and returns a handle to it
+ *   without waiting for it to finish. `stopProcess` stops it with a grace
+ *   period.
+ * - `withDefaults` binds default options to any of them.
+ *
+ * The capture runners share {@link CommandResult}, {@link CommandRunOptions}
+ * and {@link CommandFailed}, so one `instanceof CommandFailed` check covers
+ * the sync and async forms.
+ */
+export { catchFailed, CommandFailed, mapFailed, resolveRunner, runChecked, spawnRunner, type CommandResult, type CommandRunner, type CommandRunOptions, type EnvOverrides, type NeverExitedReason, } from './sync.ts';
+export { asAsync, catchFailedAsync, mapFailedAsync, resolveRunnerAsync, runCheckedAsync, spawnRunnerAsync, type AsyncCommandRunner, type AsyncCommandRunOptions, } from './async.ts';
+export { failureText, firstLine, parseJsonResult, ran, runJson, runJsonAsync, stderrOrError, type FailureTextOptions, type JsonRun, type RunJsonOptions, } from './result.ts';
+export { shellJoin, shellQuote } from './quote.ts';
+export { runShell, runShellAsync, shellRunner, shellRunnerAsync, type AsyncShellRunner, type AsyncShellRunOptions, type ShellRunner, type ShellPositionals, type ShellRunOptions, } from './shell.ts';
+export { streamRunner, type StreamRunner, type StreamRunOptions, type StreamResult, } from './stream.ts';
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,29 @@
+/**
+ * `@osdlc/command-seam`: run external commands through a small interface
+ * that tests can replace.
+ *
+ * A runner is an object with a `run` method. Code that needs a command takes
+ * a runner as a parameter. Production passes a real one; tests pass a fake.
+ *
+ * - `spawnRunner` / `spawnRunnerAsync` capture a finished run's output
+ *   ({@link CommandResult}).
+ * - `runShell` / `shellRunner` run a shell string through `sh -c --`.
+ * - `streamRunner` runs with inherited stdio, so output appears live.
+ * - `managedProcessRunner` starts a process and returns a handle to it
+ *   without waiting for it to finish. `stopProcess` stops it with a grace
+ *   period.
+ * - `withDefaults` binds default options to any of them.
+ *
+ * The capture runners share {@link CommandResult}, {@link CommandRunOptions}
+ * and {@link CommandFailed}, so one `instanceof CommandFailed` check covers
+ * the sync and async forms.
+ */
+export { catchFailed, CommandFailed, mapFailed, resolveRunner, runChecked, spawnRunner, } from "./sync.js";
+export { asAsync, catchFailedAsync, mapFailedAsync, resolveRunnerAsync, runCheckedAsync, spawnRunnerAsync, } from "./async.js";
+export { failureText, firstLine, parseJsonResult, ran, runJson, runJsonAsync, stderrOrError, } from "./result.js";
+export { shellJoin, shellQuote } from "./quote.js";
+export { runShell, runShellAsync, shellRunner, shellRunnerAsync, } from "./shell.js";
+export { streamRunner, } from "./stream.js";
+export { managedProcessRunner, stopProcess, } from "./process.js";
+export { forwardedExitCode, forwardedSignal, installGroupSignalForwarding, liveProcessGroups, } from "./groups.js";
+export { withDefaults } from "./defaults.js";