@procedures/shell 0.0.0-stage → 0.2.0

package/dist/command/processes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processes.d.ts","sourceRoot":"","sources":["../../src/command/processes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAA0B,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAEvE,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAUD,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAWD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,OAAO,CAAK;IAEpB,YAAY,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO,EAEhD;IAED,oFAAoF;IACpF,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,kBAAkB,CA+D5E;IAED,6DAA6D;IAC7D,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAG9C;IAED,+DAA+D;IAC/D,IAAI,CAAC,MAAM,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAO,GAAG,kBAAkB,EAAE,CAOtE;IAED,2FAA2F;IAC3F,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEzB;IAED,yEAAyE;IACnE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAKhE;IAED;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA0BhF;IAED;;;OAGG;IACG,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,OAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CAW9E;IAED,mFAAmF;IAC7E,OAAO,CAAC,MAAM,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAI1E;IAED,kGAAkG;IAClG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAI1B;IAED,qFAAqF;IACrF,IAAI,IAAI,MAAM,CAKb;IAED,OAAO,CAAC,UAAU;YAOJ,UAAU;CAWzB;AAED,uFAAuF;AACvF,eAAO,MAAM,SAAS,EAAE,eAAuC,CAAC"}

package/dist/command/processes.js

@@ -0,0 +1,223 @@
+/**
+ * The registry of long-running processes (deep dive WRP-4, WRP-10).
+ *
+ * Some procedures start a process and return while it runs: `vitest.watch`, `node.spawn`,
+ * `vite.dev`. Before, they started it detached and forgot it, so nothing could stop it, and it
+ * kept running after the host ended. The registry gives each process:
+ * - a record (id, pid, status, exit code), which `list` and `get` give;
+ * - a `stop` that kills the whole process tree;
+ * - the end of its output (the last 64 KiB), which also keeps its pipes from filling;
+ * - an end with the host: the host does not wait for the process, and kills it when it ends.
+ *
+ * The registry keeps the records of ended processes, up to `keepExited` of them.
+ */
+import { killTree } from "./tree-kill.js";
+import { OutputCollector } from "./output.js";
+import { startChild, startError } from "./spawn.js";
+/** The end of the output that the registry keeps for each process. */
+const OUTPUT_TAIL_BYTES = 64 * 1024;
+/** How long `stop` waits after the first kill, before it kills again with SIGKILL. */
+const STOP_GRACE_MS = 5000;
+// The CSI and OSC escape sequences of terminals (colors, styles, links)
+const ANSI = /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+/** This function removes the ANSI escape sequences from a text. */
+export function stripAnsi(text) {
+    return text.replace(ANSI, "");
+}
+export class ProcessRegistry {
+    entries = new Map();
+    keepExited;
+    counter = 0;
+    constructor(options = {}) {
+        this.keepExited = options.keepExited ?? 50;
+    }
+    /** This function starts a program and records it. The program inherits no stdin. */
+    start(command, options = {}) {
+        const child = startChild(command, options, "ignore");
+        const id = `${options.group ?? "process"}-${Date.now().toString(36)}-${++this.counter}`;
+        const info = {
+            id,
+            pid: child.pid ?? 0,
+            command,
+            args: [...(options.args ?? [])],
+            status: "running",
+            startedAt: new Date().toISOString(),
+        };
+        if (options.cwd !== undefined)
+            info.cwd = options.cwd;
+        if (options.group !== undefined)
+            info.group = options.group;
+        if (options.label !== undefined)
+            info.label = options.label;
+        const output = new OutputCollector(OUTPUT_TAIL_BYTES, "tail");
+        const watchers = new Set();
+        const changed = () => {
+            for (const watcher of [...watchers])
+                watcher();
+        };
+        child.stdout.on("data", (chunk) => {
+            output.add(chunk);
+            changed();
+        });
+        child.stderr.on("data", (chunk) => {
+            output.add(chunk);
+            changed();
+        });
+        const done = new Promise((resolve) => {
+            let finished = false;
+            const finish = () => {
+                if (finished)
+                    return;
+                finished = true;
+                info.exitedAt = new Date().toISOString();
+                resolve();
+                changed();
+                this.reap();
+            };
+            child.on("error", (error) => {
+                info.error = startError(error);
+                if (child.pid === undefined) {
+                    info.status = "error";
+                    finish();
+                }
+            });
+            child.on("close", (code, signal) => {
+                info.status = info.error ? "error" : "exited";
+                if (code !== null)
+                    info.exitCode = code;
+                if (signal)
+                    info.signal = signal;
+                finish();
+            });
+        });
+        // The host does not wait for the process: it ends when the host ends (see tree-kill.ts)
+        child.unref();
+        for (const stream of [child.stdout, child.stderr]) {
+            stream?.unref?.();
+        }
+        this.entries.set(id, { info, child, output, watchers, done });
+        this.reap();
+        return { ...info };
+    }
+    /** This function gives a copy of the record of a process. */
+    get(id) {
+        const entry = this.entries.get(id);
+        return entry ? { ...entry.info } : undefined;
+    }
+    /** This function gives copies of the records, oldest first. */
+    list(filter = {}) {
+        const result = [];
+        for (const entry of this.entries.values()) {
+            if (filter.group !== undefined && entry.info.group !== filter.group)
+                continue;
+            result.push({ ...entry.info });
+        }
+        return result;
+    }
+    /** This function gives the end of the output of a process (stdout and stderr together). */
+    output(id) {
+        return this.entries.get(id)?.output.text() ?? "";
+    }
+    /** This function waits until the process ends, then gives its record. */
+    async exited(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return undefined;
+        await entry.done;
+        return { ...entry.info };
+    }
+    /**
+     * This function waits until the output of the process matches `pattern`, and gives the match.
+     * The pattern sees the output without ANSI escape codes: a program can color its output when
+     * the environment has `FORCE_COLOR`. It rejects when the process ends first, or after
+     * `timeout` milliseconds.
+     */
+    waitFor(id, pattern, timeout = 30_000) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return Promise.reject(new Error(`No process ${id}`));
+        return new Promise((resolve, reject) => {
+            const check = () => {
+                const match = stripAnsi(entry.output.text()).match(pattern);
+                if (match) {
+                    stop();
+                    resolve(match);
+                }
+                else if (entry.info.status !== "running" || entry.info.exitedAt) {
+                    stop();
+                    const code = entry.info.exitCode ?? entry.info.signal ?? entry.info.error;
+                    reject(new Error(`Process ${id} exited (${code}) before its output matched ${pattern}`));
+                }
+            };
+            const timer = setTimeout(() => {
+                stop();
+                reject(new Error(`Timeout after ${timeout} ms: the output of process ${id} did not match ${pattern}`));
+            }, timeout);
+            const stop = () => {
+                clearTimeout(timer);
+                entry.watchers.delete(check);
+            };
+            entry.watchers.add(check);
+            check();
+        });
+    }
+    /**
+     * This function kills the process tree and waits for the end. When the process does not end
+     * within the grace time, it kills again with SIGKILL.
+     */
+    async stop(id, signal = "SIGTERM") {
+        const entry = this.entries.get(id);
+        if (!entry || entry.info.exitedAt) {
+            return entry ? this.stopResult(entry, false) : { stopped: false };
+        }
+        killTree(entry.child, signal);
+        if (!(await this.endsWithin(entry, STOP_GRACE_MS))) {
+            killTree(entry.child, "SIGKILL");
+            await this.endsWithin(entry, STOP_GRACE_MS);
+        }
+        return this.stopResult(entry, true);
+    }
+    /** This function stops every running process of the registry (or of one group). */
+    async stopAll(filter = {}) {
+        const running = this.list(filter).filter((info) => info.status === "running");
+        await Promise.all(running.map((info) => this.stop(info.id)));
+        return running.length;
+    }
+    /** This function removes the record of an ended process. It keeps the record of a running one. */
+    forget(id) {
+        const entry = this.entries.get(id);
+        if (!entry || !entry.info.exitedAt)
+            return false;
+        return this.entries.delete(id);
+    }
+    /** This function removes the oldest records of ended processes past `keepExited`. */
+    reap() {
+        const ended = [...this.entries.values()].filter((entry) => entry.info.exitedAt);
+        const excess = ended.length - this.keepExited;
+        for (let i = 0; i < excess; i++)
+            this.entries.delete(ended[i].info.id);
+        return Math.max(0, excess);
+    }
+    stopResult(entry, stopped) {
+        const result = { stopped };
+        if (entry.info.exitCode !== undefined)
+            result.exitCode = entry.info.exitCode;
+        if (entry.info.signal !== undefined)
+            result.signal = entry.info.signal;
+        return result;
+    }
+    async endsWithin(entry, ms) {
+        let timer;
+        const ended = await Promise.race([
+            entry.done.then(() => true),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), ms);
+            }),
+        ]);
+        clearTimeout(timer);
+        return ended;
+    }
+}
+/** The registry of the host process. The procedures of the wrapper packages use it. */
+export const processes = new ProcessRegistry();
+//# sourceMappingURL=processes.js.map

package/dist/command/processes.js.map

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

package/dist/command/run.d.ts

@@ -0,0 +1,48 @@
+/**
+ * runCommand: run a program to its end and give its output (roadmap 2.2).
+ *
+ * This is the one way the wrapper packages run a program. Each wrapper had its own way: shell
+ * strings (`docker`, `pnpm`), synchronous calls that blocked the event loop and ignored the
+ * signal (`git`, `cue`), and `spawn` calls that killed only the direct child.
+ */
+import { type SpawnOptions } from "./spawn.js";
+export interface CommandOptions extends SpawnOptions {
+    /** Text or bytes to write to stdin. Without it, stdin is empty (the program reads its end at once). */
+    input?: string | Buffer | undefined;
+    /** After this many milliseconds, the process tree is killed. */
+    timeout?: number | undefined;
+    /** When the signal aborts, the process tree is killed. An aborted signal starts nothing. */
+    signal?: AbortSignal | undefined;
+    /** The most bytes kept of each output stream (default: 64 MiB). */
+    maxOutputBytes?: number | undefined;
+    /** Past the limit, keep the first bytes ("head", the default) or the last bytes ("tail"). */
+    keep?: "head" | "tail" | undefined;
+    /** The encoding of the output (default: utf8). */
+    encoding?: BufferEncoding | undefined;
+}
+export interface CommandResult {
+    /** The exit code. It is 1 when the process ended on a signal or did not start. */
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    /** True when the exit code is 0. */
+    success: boolean;
+    /** The time from the start to the end, in milliseconds. */
+    duration: number;
+    /** The signal that ended the process. When the helper killed the tree, it is "SIGTERM". */
+    signal?: string;
+    /** True when the timeout killed the process. */
+    timedOut?: boolean;
+    /** True when the signal aborted the command. */
+    aborted?: boolean;
+    /** Present when an output stream was longer than `maxOutputBytes`: which one lost bytes. */
+    truncated?: {
+        stdout: boolean;
+        stderr: boolean;
+    };
+    /** The error that kept the program from starting, for example `spawn x ENOENT`. */
+    error?: string;
+}
+/** This function runs `command` with `options.args`. It does not throw: a failure is in the result. */
+export declare function runCommand(command: string, options?: CommandOptions): Promise<CommandResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/command/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/command/run.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAA0B,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAEvE,MAAM,WAAW,cAAe,SAAQ,YAAY;IAClD,uGAAuG;IACvG,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACpC,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,4FAA4F;IAC5F,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACjC,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,6FAA6F;IAC7F,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACnC,kDAAkD;IAClD,QAAQ,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4FAA4F;IAC5F,SAAS,CAAC,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IACjD,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,uGAAuG;AACvG,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CA6EhG"}

package/dist/command/run.js

@@ -0,0 +1,89 @@
+/**
+ * runCommand: run a program to its end and give its output (roadmap 2.2).
+ *
+ * This is the one way the wrapper packages run a program. Each wrapper had its own way: shell
+ * strings (`docker`, `pnpm`), synchronous calls that blocked the event loop and ignored the
+ * signal (`git`, `cue`), and `spawn` calls that killed only the direct child.
+ */
+import { killTree } from "./tree-kill.js";
+import { DEFAULT_MAX_OUTPUT_BYTES, OutputCollector } from "./output.js";
+import { startChild, startError } from "./spawn.js";
+/** This function runs `command` with `options.args`. It does not throw: a failure is in the result. */
+export function runCommand(command, options = {}) {
+    const started = Date.now();
+    if (options.signal?.aborted) {
+        return Promise.resolve({ exitCode: 1, stdout: "", stderr: "", success: false, duration: 0, aborted: true });
+    }
+    const encoding = options.encoding ?? "utf8";
+    const limit = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    const stdout = new OutputCollector(limit, options.keep);
+    const stderr = new OutputCollector(limit, options.keep);
+    return new Promise((resolve) => {
+        const child = startChild(command, options, options.input !== undefined ? "pipe" : "ignore");
+        let timedOut = false;
+        let aborted = false;
+        let settled = false;
+        const timer = options.timeout !== undefined
+            ? setTimeout(() => {
+                timedOut = true;
+                killTree(child);
+            }, options.timeout)
+            : undefined;
+        const onAbort = () => {
+            aborted = true;
+            killTree(child);
+        };
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+            resolve(result);
+        };
+        child.stdout.on("data", (chunk) => stdout.add(chunk));
+        child.stderr.on("data", (chunk) => stderr.add(chunk));
+        if (options.input !== undefined) {
+            // A program that ends before it reads its input closes the pipe: that is not an error here
+            child.stdin.on("error", () => { });
+            child.stdin.end(options.input);
+        }
+        child.on("error", (error) => {
+            // The program did not start: no "close" follows
+            if (child.pid === undefined) {
+                finish({
+                    exitCode: 1,
+                    stdout: "",
+                    stderr: startError(error),
+                    success: false,
+                    duration: Date.now() - started,
+                    error: startError(error),
+                });
+            }
+        });
+        child.on("close", (code, signal) => {
+            const result = {
+                exitCode: code ?? 1,
+                stdout: stdout.text(encoding),
+                stderr: stderr.text(encoding),
+                success: code === 0 && !timedOut && !aborted,
+                duration: Date.now() - started,
+            };
+            // On Windows, taskkill ends the process with an exit code and no signal
+            const endSignal = signal ?? (timedOut || aborted ? "SIGTERM" : undefined);
+            if (endSignal)
+                result.signal = endSignal;
+            if (timedOut)
+                result.timedOut = true;
+            if (aborted)
+                result.aborted = true;
+            if (stdout.truncated || stderr.truncated) {
+                result.truncated = { stdout: stdout.truncated, stderr: stderr.truncated };
+            }
+            finish(result);
+        });
+    });
+}
+//# sourceMappingURL=run.js.map

package/dist/command/run.js.map

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

package/dist/command/spawn.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Start a child process the one way the helpers allow: an argument list, no shell, no window.
+ */
+import { type ChildProcess } from "node:child_process";
+export interface SpawnOptions {
+    /** The arguments. Each one goes to the program as it is: no shell reads it. */
+    args?: readonly string[] | undefined;
+    /** The working directory (default: the current directory of the host). */
+    cwd?: string | undefined;
+    /** Environment variables to add to the environment of the host. */
+    env?: Record<string, string | undefined> | undefined;
+    /**
+     * On Windows, pass the arguments without quotes. Only `shell.exec` sets it, for the command
+     * line of `cmd.exe`.
+     */
+    windowsVerbatimArguments?: boolean | undefined;
+}
+/**
+ * This function starts `command` with `shell: false` and `windowsHide`. On POSIX the child gets
+ * its own process group, so `killTree` reaches its descendants. The child is recorded until it
+ * ends, so the end of the host kills it.
+ */
+export declare function startChild(command: string, options: SpawnOptions, stdin: "pipe" | "ignore"): ChildProcess;
+/** The text of an error that kept a program from starting, for example `spawn x ENOENT`. */
+export declare function startError(error: unknown): string;
+//# sourceMappingURL=spawn.d.ts.map

package/dist/command/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../src/command/spawn.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG9D,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACrC,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;IACrD;;;OAGG;IACH,wBAAwB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,YAAY,CAYzG;AAED,4FAA4F;AAC5F,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEjD"}

package/dist/command/spawn.js

@@ -0,0 +1,28 @@
+/**
+ * Start a child process the one way the helpers allow: an argument list, no shell, no window.
+ */
+import { spawn } from "node:child_process";
+import { OWN_PROCESS_GROUP, track } from "./tree-kill.js";
+/**
+ * This function starts `command` with `shell: false` and `windowsHide`. On POSIX the child gets
+ * its own process group, so `killTree` reaches its descendants. The child is recorded until it
+ * ends, so the end of the host kills it.
+ */
+export function startChild(command, options, stdin) {
+    const child = spawn(command, [...(options.args ?? [])], {
+        cwd: options.cwd,
+        env: options.env ? { ...process.env, ...options.env } : process.env,
+        shell: false,
+        windowsHide: true,
+        detached: OWN_PROCESS_GROUP,
+        stdio: [stdin, "pipe", "pipe"],
+        ...(options.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
+    });
+    track(child);
+    return child;
+}
+/** The text of an error that kept a program from starting, for example `spawn x ENOENT`. */
+export function startError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=spawn.js.map

package/dist/command/spawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.js","sourceRoot":"","sources":["../../src/command/spawn.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,EAAqB,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAgB1D;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,OAAqB,EAAE,KAAwB;IACzF,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE;QACtD,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG;QACnE,KAAK,EAAE,KAAK;QACZ,WAAW,EAAE,IAAI;QACjB,QAAQ,EAAE,iBAAiB;QAC3B,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC;QAC9B,GAAG,CAAC,OAAO,CAAC,wBAAwB,CAAC,CAAC,CAAC,EAAE,wBAAwB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChF,CAAC,CAAC;IACH,KAAK,CAAC,KAAK,CAAC,CAAC;IACb,OAAO,KAAK,CAAC;AACf,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC"}

package/dist/command/stream.d.ts

@@ -0,0 +1,42 @@
+/**
+ * streamCommand: run a program and give each output line while it runs.
+ *
+ * The queue between the program and the reader has a limit (deep dive WRP-9). When the queue
+ * is full, the helper stops reading the pipes of the program. The pipes fill, and the program
+ * waits in its next write. When the reader takes items again, the helper reads again. Before,
+ * the queue had no limit: a program with a large output filled the memory of the host.
+ */
+import { type SpawnOptions } from "./spawn.js";
+/** One item of a stream: an output line, or the exit of the program (the last item). */
+export type CommandStreamItem = {
+    type: "stdout" | "stderr";
+    line: string;
+} | {
+    type: "exit";
+    exitCode: number;
+    duration: number;
+    signal?: string;
+    timedOut?: boolean;
+    aborted?: boolean;
+};
+export interface StreamCommandOptions extends SpawnOptions {
+    /** Text or bytes to write to stdin. Without it, stdin is empty. */
+    input?: string | Buffer | undefined;
+    /** After this many milliseconds, the process tree is killed. */
+    timeout?: number | undefined;
+    /** When the signal aborts, the process tree is killed. */
+    signal?: AbortSignal | undefined;
+    /** The most items that wait for the reader before the helper stops reading (default: 1000). */
+    highWaterMark?: number | undefined;
+    /** A longer line arrives in parts of this many characters (default: 1 MiB). */
+    maxLineLength?: number | undefined;
+    /** The encoding of the output (default: utf8). */
+    encoding?: BufferEncoding | undefined;
+}
+/**
+ * This function runs `command` and yields each line of stdout and stderr, then one exit item.
+ * When the reader stops early, or the signal aborts, the process tree is killed. A program that
+ * cannot start makes the generator throw.
+ */
+export declare function streamCommand(command: string, options?: StreamCommandOptions): AsyncGenerator<CommandStreamItem, void, undefined>;
+//# sourceMappingURL=stream.d.ts.map

package/dist/command/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/command/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAE3D,wFAAwF;AACxF,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3C;IACE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEN,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACpC,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,0DAA0D;IAC1D,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACjC,+FAA+F;IAC/F,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,kDAAkD;IAClD,QAAQ,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CACvC;AAKD;;;;GAIG;AACH,wBAAuB,aAAa,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,cAAc,CAAC,iBAAiB,EAAE,IAAI,EAAE,SAAS,CAAC,CAsIpD"}