@ac-kit/node 0.1.0

package/dist/process/spawn-process.js

@@ -0,0 +1,73 @@
+import { BYTES_PER_MIB } from "@ac-kit/core";
+import { ProcessExitWithOutputError } from "../error/process-exit-error.js";
+import { startProcess } from "./start-process.js";
+/**
+ * Runs a command to completion and returns what it printed.
+ *
+ * The one-shot form of {@link startProcess}: no handle is exposed, so streaming
+ * consumers pass `onOutput` instead of subscribing.
+ *
+ * @param command The executable to run.
+ * @param args Arguments passed to it verbatim.
+ * @param options Capture limits and everything {@link StartProcessOptions}
+ *   accepts.
+ * @returns The exit status and the captured streams.
+ * @throws {ProcessExitWithOutputError} On a non-zero exit, unless
+ *   `throwOnNonZero` is `false`.
+ * @throws {RangeError} When either stream exceeds `maxBuffer`.
+ */
+export async function spawnProcess(command, args, options) {
+    const encoding = options?.encoding ?? "utf8";
+    const maxBuffer = options?.maxBuffer ?? 8 * BYTES_PER_MIB;
+    const capture = options?.capture ?? "both";
+    const throwOnNonZero = options?.throwOnNonZero ?? true;
+    const capturesStdout = capture === "both" || capture === "stdout";
+    const capturesStderr = capture === "both" || capture === "stderr";
+    const streams = Boolean(options?.onOutput);
+    const spawned = await startProcess(command, args, {
+        ...options,
+        // An unread pipe fills and blocks the child, so nothing is piped in vain.
+        stdout: options?.stdout ?? (capturesStdout || streams ? "pipe" : "ignore"),
+        stderr: options?.stderr ?? (capturesStderr || streams ? "pipe" : "ignore"),
+    });
+    let stdout = "";
+    let stderr = "";
+    let overflowError = null;
+    const collect = (source, name, append) => {
+        if (!source) {
+            return;
+        }
+        let bytes = 0;
+        source.on("data", (chunk) => {
+            bytes += chunk.length;
+            if (bytes <= maxBuffer) {
+                append(chunk.toString(encoding));
+                return;
+            }
+            if (!overflowError) {
+                overflowError = new RangeError(`${name} maxBuffer (${maxBuffer} bytes) exceeded`);
+                spawned.kill();
+            }
+        });
+    };
+    if (capturesStdout) {
+        collect(spawned.nodeStdout_, "stdout", (text) => {
+            stdout += text;
+        });
+    }
+    if (capturesStderr) {
+        collect(spawned.nodeStderr_, "stderr", (text) => {
+            stderr += text;
+        });
+    }
+    const exit = await spawned.waitForExit();
+    options?.signal?.throwIfAborted();
+    if (overflowError) {
+        throw overflowError;
+    }
+    if (throwOnNonZero && exit.code !== 0) {
+        throw new ProcessExitWithOutputError(exit.code, exit.signal, exit.signal !== null, stdout, stderr);
+    }
+    return { ...exit, stdout, stderr };
+}
+//# sourceMappingURL=spawn-process.js.map

package/dist/process/spawn-process.js.map

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

package/dist/process/spawned-process.d.ts

@@ -0,0 +1,102 @@
+import type { ChildProcess } from "node:child_process";
+import { Readable } from "node:stream";
+import { EventDispatcherMapBase, type EventDispatcherSubscribeOptions, type EventDispatcherWaitOptions, type IEventDispatcherMap } from "@ac-kit/async";
+import { type Callable } from "@ac-kit/core";
+export type ProcessOutputStream = "stdout" | "stderr";
+export type ProcessExit = {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    durationMs: number;
+};
+export type SpawnedProcessEvents = {
+    /** One line of the child's output, with its terminator stripped. */
+    output: [stream: ProcessOutputStream, line: string];
+};
+/** Time a terminated child gets to exit before it is killed outright. */
+export declare const DEFAULT_PROCESS_GRACE_MS = 5000;
+export type SpawnedProcessOptions = {
+    /** Grace period before {@link SpawnedProcess.terminate} escalates. */
+    readonly graceMs?: number | null;
+    /**
+     * The child leads its own process group, so signals address the group rather
+     * than the child alone.
+     */
+    readonly detached?: boolean | null;
+};
+/**
+ * A running child process: its output as events, its exit as an awaitable, and
+ * a two-stage termination.
+ *
+ * Obtained from `startProcess` or `forkProcess`, both of which resolve only
+ * once the child has actually spawned — so a handle always has a `pid`, and a
+ * spawn failure surfaces as a rejection there rather than later on the handle.
+ *
+ * Line splitting is attached on the first `output` subscription, so a caller
+ * that only wants the exit status never pays for it.
+ */
+export declare class SpawnedProcess<TEvents extends SpawnedProcessEvents & Record<PropertyKey, unknown[]> = SpawnedProcessEvents> extends EventDispatcherMapBase<TEvents> implements IEventDispatcherMap<TEvents>, AsyncDisposable {
+    protected readonly child: ChildProcess;
+    private readonly startedAt;
+    private readonly exited;
+    private readonly outputDrained;
+    private outputAttached;
+    private webStdout;
+    private webStderr;
+    private terminating;
+    private killTimer;
+    private readonly graceMs;
+    private readonly detached;
+    constructor(child: ChildProcess, startedAt: number, options?: SpawnedProcessOptions);
+    get pid(): number | undefined;
+    /** The child's standard output, `null` unless it was piped. */
+    get stdout(): ReadableStream<Uint8Array> | null;
+    /** The child's standard error, `null` unless it was piped. */
+    get stderr(): ReadableStream<Uint8Array> | null;
+    /** @internal Node stream behind {@link stdout}, for in-package buffering. */
+    get nodeStdout_(): Readable | null;
+    /** @internal Node stream behind {@link stderr}, for in-package buffering. */
+    get nodeStderr_(): Readable | null;
+    subscribe<K extends keyof TEvents>(event: K, listener: Callable<TEvents[K]>, options?: EventDispatcherSubscribeOptions): Callable | null;
+    wait<K extends keyof TEvents>(event: K, options?: EventDispatcherWaitOptions<TEvents[K]>): Promise<TEvents[K]>;
+    /**
+     * Resolves once the child has exited, immediately if it already has.
+     *
+     * @param signal Abandons the wait; the child is left running.
+     * @returns The exit code, terminating signal and wall-clock duration.
+     */
+    waitForExit(signal?: AbortSignal | null): Promise<ProcessExit>;
+    /**
+     * Sends `SIGTERM`, then `SIGKILL` if the child is still alive after
+     * `graceMs`. Idempotent: concurrent and repeated calls share one escalation.
+     *
+     * @param graceMs Overrides the grace period given at spawn time.
+     * @returns The child's exit, once it has happened.
+     */
+    terminate(graceMs?: number): Promise<ProcessExit>;
+    /**
+     * Sends one signal and returns, with no escalation — for signals that mean
+     * something to the child other than "shut down".
+     *
+     * @param signal Defaults to `SIGTERM`.
+     * @returns Whether the signal was delivered.
+     */
+    kill(signal?: NodeJS.Signals): boolean;
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * A detached child leads its own group, so the negated pid reaches whatever
+     * it spawned too — otherwise a grandchild outlives the run, reparented to
+     * init with nothing left pointing at it.
+     */
+    private signalProcess;
+    protected attachOutput(): void;
+    /**
+     * Adapts by listening rather than by `Readable.toWeb`, which would lock the
+     * source: every consumer here is one more `data` listener on the same stream.
+     * No backpressure — the child's output is drained as fast as it arrives.
+     */
+    private toWebStream;
+    private attachOutputFor;
+    private pipeOutput;
+    private waitForClose;
+}
+//# sourceMappingURL=spawned-process.d.ts.map

package/dist/process/spawned-process.d.ts.map

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

package/dist/process/spawned-process.js

@@ -0,0 +1,226 @@
+import { createInterface } from "node:readline";
+import { EventDispatcherMapBase, } from "@ac-kit/async";
+import { Timer } from "@ac-kit/core";
+/** Time a terminated child gets to exit before it is killed outright. */
+export const DEFAULT_PROCESS_GRACE_MS = 5000;
+/**
+ * A running child process: its output as events, its exit as an awaitable, and
+ * a two-stage termination.
+ *
+ * Obtained from `startProcess` or `forkProcess`, both of which resolve only
+ * once the child has actually spawned — so a handle always has a `pid`, and a
+ * spawn failure surfaces as a rejection there rather than later on the handle.
+ *
+ * Line splitting is attached on the first `output` subscription, so a caller
+ * that only wants the exit status never pays for it.
+ */
+export class SpawnedProcess extends EventDispatcherMapBase {
+    child;
+    startedAt;
+    exited;
+    outputDrained = [];
+    outputAttached = false;
+    webStdout = null;
+    webStderr = null;
+    terminating = null;
+    killTimer = null;
+    graceMs;
+    detached;
+    constructor(child, startedAt, options) {
+        super();
+        this.child = child;
+        this.startedAt = startedAt;
+        this.graceMs = options?.graceMs ?? DEFAULT_PROCESS_GRACE_MS;
+        this.detached = options?.detached ?? false;
+        // Post-spawn errors (a failed kill, a broken channel) must not become an
+        // unhandled 'error'; `close` still fires and settles the exit.
+        child.on("error", () => { });
+        this.exited = this.waitForClose();
+    }
+    get pid() {
+        return this.child.pid;
+    }
+    /** The child's standard output, `null` unless it was piped. */
+    get stdout() {
+        this.webStdout ??= this.toWebStream(this.child.stdout);
+        return this.webStdout;
+    }
+    /** The child's standard error, `null` unless it was piped. */
+    get stderr() {
+        this.webStderr ??= this.toWebStream(this.child.stderr);
+        return this.webStderr;
+    }
+    /** @internal Node stream behind {@link stdout}, for in-package buffering. */
+    get nodeStdout_() {
+        return this.child.stdout;
+    }
+    /** @internal Node stream behind {@link stderr}, for in-package buffering. */
+    get nodeStderr_() {
+        return this.child.stderr;
+    }
+    subscribe(event, listener, options) {
+        this.attachOutputFor(event);
+        return super.subscribe(event, listener, options);
+    }
+    wait(event, options) {
+        this.attachOutputFor(event);
+        return super.wait(event, options);
+    }
+    /**
+     * Resolves once the child has exited, immediately if it already has.
+     *
+     * @param signal Abandons the wait; the child is left running.
+     * @returns The exit code, terminating signal and wall-clock duration.
+     */
+    waitForExit(signal) {
+        if (!signal) {
+            return this.exited;
+        }
+        // Rejects rather than throws: the signature promises a promise.
+        if (signal.aborted) {
+            return Promise.reject(signal.reason);
+        }
+        return new Promise((resolve, reject) => {
+            const onAbort = () => reject(signal.reason);
+            signal.addEventListener("abort", onAbort, { once: true });
+            void this.exited.then((exit) => {
+                signal.removeEventListener("abort", onAbort);
+                resolve(exit);
+            });
+        });
+    }
+    /**
+     * Sends `SIGTERM`, then `SIGKILL` if the child is still alive after
+     * `graceMs`. Idempotent: concurrent and repeated calls share one escalation.
+     *
+     * @param graceMs Overrides the grace period given at spawn time.
+     * @returns The child's exit, once it has happened.
+     */
+    terminate(graceMs) {
+        if (this.terminating) {
+            return this.terminating;
+        }
+        this.terminating = this.exited;
+        if (this.child.exitCode === null && this.child.signalCode === null) {
+            this.signalProcess("SIGTERM");
+            this.killTimer = new Timer(() => this.signalProcess("SIGKILL"), graceMs ?? this.graceMs);
+            this.killTimer.start();
+        }
+        return this.terminating;
+    }
+    /**
+     * Sends one signal and returns, with no escalation — for signals that mean
+     * something to the child other than "shut down".
+     *
+     * @param signal Defaults to `SIGTERM`.
+     * @returns Whether the signal was delivered.
+     */
+    kill(signal = "SIGTERM") {
+        return this.signalProcess(signal);
+    }
+    async [Symbol.asyncDispose]() {
+        await this.terminate();
+    }
+    /**
+     * A detached child leads its own group, so the negated pid reaches whatever
+     * it spawned too — otherwise a grandchild outlives the run, reparented to
+     * init with nothing left pointing at it.
+     */
+    signalProcess(signal) {
+        const pid = this.child.pid;
+        if (pid === undefined ||
+            this.child.exitCode !== null ||
+            this.child.signalCode !== null) {
+            return false;
+        }
+        // Windows has no process groups; `detached` only opens a console there.
+        if (!this.detached || process.platform === "win32") {
+            return this.child.kill(signal);
+        }
+        try {
+            process.kill(-pid, signal);
+            return true;
+        }
+        catch {
+            // Already gone between the liveness check and the signal.
+            return false;
+        }
+    }
+    attachOutput() {
+        if (this.outputAttached) {
+            return;
+        }
+        this.outputAttached = true;
+        this.pipeOutput("stdout", this.child.stdout);
+        this.pipeOutput("stderr", this.child.stderr);
+    }
+    /**
+     * Adapts by listening rather than by `Readable.toWeb`, which would lock the
+     * source: every consumer here is one more `data` listener on the same stream.
+     * No backpressure — the child's output is drained as fast as it arrives.
+     */
+    toWebStream(source) {
+        if (!source) {
+            return null;
+        }
+        let live = true;
+        let onData = null;
+        return new ReadableStream({
+            start(controller) {
+                onData = (chunk) => {
+                    if (live) {
+                        controller.enqueue(chunk);
+                    }
+                };
+                source.on("data", onData);
+                source.once("end", () => {
+                    if (live) {
+                        live = false;
+                        controller.close();
+                    }
+                });
+                source.once("error", (error) => {
+                    if (live) {
+                        live = false;
+                        controller.error(error);
+                    }
+                });
+            },
+            cancel() {
+                live = false;
+                if (onData) {
+                    source.off("data", onData);
+                    onData = null;
+                }
+            },
+        });
+    }
+    attachOutputFor(event) {
+        if (event === "output") {
+            this.attachOutput();
+        }
+    }
+    pipeOutput(stream, source) {
+        if (!source) {
+            return;
+        }
+        const lines = createInterface({ input: source });
+        lines.on("line", (line) => {
+            this.dispatch("output", [stream, line]);
+        });
+        // `close` on the child can beat readline's final line out of the door.
+        this.outputDrained.push(new Promise((resolve) => lines.once("close", () => resolve())));
+    }
+    async waitForClose() {
+        const [code, signal] = await new Promise((resolve) => {
+            this.child.once("close", (closeCode, closeSignal) => resolve([closeCode, closeSignal]));
+        });
+        if (this.killTimer) {
+            this.killTimer.cancel();
+            this.killTimer = null;
+        }
+        await Promise.allSettled(this.outputDrained);
+        return { code, signal, durationMs: Date.now() - this.startedAt };
+    }
+}
+//# sourceMappingURL=spawned-process.js.map

package/dist/process/spawned-process.js.map

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

package/dist/process/start-process.d.ts

@@ -0,0 +1,54 @@
+import { Callable } from "@ac-kit/core";
+import { type ProcessOutputStream, SpawnedProcess } from "./spawned-process.js";
+/** What the child does with one of its standard streams. */
+export type ProcessStdio = "pipe" | "inherit" | "ignore";
+export type StartProcessOptions = {
+    /**
+     * Runs the command through a shell, so redirection and piping work and
+     * arguments are **not** escaped. Only ever pass a trusted command line.
+     */
+    readonly shell?: boolean | string | null;
+    readonly cwd?: string | null;
+    readonly env?: NodeJS.ProcessEnv | null;
+    /** Aborting terminates the child. */
+    readonly signal?: AbortSignal | null;
+    /** Written to the child's stdin, which is then closed. */
+    readonly input?: string | Uint8Array | null;
+    /** Default `"pipe"`, which is what `output` events are read from. */
+    readonly stdout?: ProcessStdio | null;
+    /** Default `"pipe"`. */
+    readonly stderr?: ProcessStdio | null;
+    /**
+     * Makes the child lead its own process group, so `terminate`, `kill` and an
+     * aborted signal reach everything it spawns rather than the child alone.
+     */
+    readonly detached?: boolean | null;
+    /** Pre-subscribed before the child can write anything. */
+    readonly onOutput?: Callable<[
+        stream: ProcessOutputStream,
+        line: string
+    ]> | null;
+    /** Grace period before `terminate` escalates to `SIGKILL`. Default 5000. */
+    readonly graceMs?: number | null;
+};
+/**
+ * Spawns a command and resolves once it is running.
+ *
+ * Nothing in `args` can be interpreted as a command unless `shell` is set, so
+ * the default form is safe with untrusted arguments.
+ *
+ * @example
+ * 	```ts
+ * 	await using child = await startProcess("tail", ["-f", "app.log"]);
+ * 	child.subscribe("output", (_stream, line) => console.log(line));
+ * 	```;
+ *
+ * @param command The executable to run.
+ * @param args Arguments passed to it verbatim.
+ * @param options Streams, environment, cancellation. See
+ *   {@link StartProcessOptions}.
+ * @returns A handle over the running child.
+ * @throws When the command cannot be spawned.
+ */
+export declare function startProcess(command: string, args?: readonly string[], options?: StartProcessOptions): Promise<SpawnedProcess>;
+//# sourceMappingURL=start-process.d.ts.map

package/dist/process/start-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-process.d.ts","sourceRoot":"","sources":["../../src/process/start-process.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,OAAO,EAAE,KAAK,mBAAmB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEhF,4DAA4D;AAC5D,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEzD,MAAM,MAAM,mBAAmB,GAAG;IACjC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;IAEzC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC;IAExC,qCAAqC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAErC,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IAE5C,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAEtC,wBAAwB;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAEtC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAEnC,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAC3B;QAAC,MAAM,EAAE,mBAAmB;QAAE,IAAI,EAAE,MAAM;KAAC,CAC3C,GAAG,IAAI,CAAC;IAET,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,CAAC,EAAE,mBAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAyDzB"}

package/dist/process/start-process.js

@@ -0,0 +1,73 @@
+import { spawn } from "node:child_process";
+import { SpawnedProcess } from "./spawned-process.js";
+/**
+ * Spawns a command and resolves once it is running.
+ *
+ * Nothing in `args` can be interpreted as a command unless `shell` is set, so
+ * the default form is safe with untrusted arguments.
+ *
+ * @example
+ * 	```ts
+ * 	await using child = await startProcess("tail", ["-f", "app.log"]);
+ * 	child.subscribe("output", (_stream, line) => console.log(line));
+ * 	```;
+ *
+ * @param command The executable to run.
+ * @param args Arguments passed to it verbatim.
+ * @param options Streams, environment, cancellation. See
+ *   {@link StartProcessOptions}.
+ * @returns A handle over the running child.
+ * @throws When the command cannot be spawned.
+ */
+export async function startProcess(command, args, options) {
+    const startedAt = performance.now();
+    const child = spawn(command, args ? [...args] : [], {
+        shell: options?.shell ?? false,
+        cwd: options?.cwd ?? undefined,
+        env: options?.env ?? undefined,
+        detached: options?.detached ?? false,
+        stdio: [
+            options?.input !== undefined && options?.input !== null
+                ? "pipe"
+                : "ignore",
+            options?.stdout ?? "pipe",
+            options?.stderr ?? "pipe",
+        ],
+    });
+    // Attached before anything can await: an abort signal fires 'error' on the
+    // next tick, which would go unhandled during the gap below.
+    child.on("error", () => { });
+    await new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("spawn", () => {
+            child.removeListener("error", reject);
+            resolve();
+        });
+    });
+    const spawned = new SpawnedProcess(child, startedAt, {
+        graceMs: options?.graceMs,
+        detached: options?.detached,
+    });
+    const onOutput = options?.onOutput;
+    if (onOutput) {
+        spawned.subscribe("output", onOutput);
+    }
+    if (options?.input) {
+        // A child that never reads stdin makes this write emit its own error.
+        child.stdin?.on("error", () => { });
+        child.stdin?.end(options.input);
+    }
+    // Wired here rather than handed to `spawn`, whose own handling signals the
+    // child alone and never escalates.
+    const signal = options?.signal;
+    if (signal?.aborted === true) {
+        void spawned.terminate();
+    }
+    else {
+        signal?.addEventListener("abort", () => void spawned.terminate(), {
+            once: true,
+        });
+    }
+    return spawned;
+}
+//# sourceMappingURL=start-process.js.map

package/dist/process/start-process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-process.js","sourceRoot":"","sources":["../../src/process/start-process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAI3C,OAAO,EAA4B,cAAc,EAAE,MAAM,sBAAsB,CAAC;AA2ChF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,OAAe,EACf,IAAwB,EACxB,OAA6B;IAE7B,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAEpC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE;QACnD,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK;QAC9B,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,SAAS;QAC9B,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,SAAS;QAC9B,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,KAAK;QACpC,KAAK,EAAE;YACN,OAAO,EAAE,KAAK,KAAK,SAAS,IAAI,OAAO,EAAE,KAAK,KAAK,IAAI;gBACtD,CAAC,CAAC,MAAM;gBACR,CAAC,CAAC,QAAQ;YACX,OAAO,EAAE,MAAM,IAAI,MAAM;YACzB,OAAO,EAAE,MAAM,IAAI,MAAM;SACzB;KACD,CAAC,CAAC;IAEH,2EAA2E;IAC3E,4DAA4D;IAC5D,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAE5B,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;YACxB,KAAK,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACtC,OAAO,EAAE,CAAC;QACX,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,IAAI,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE;QACpD,OAAO,EAAE,OAAO,EAAE,OAAO;QACzB,QAAQ,EAAE,OAAO,EAAE,QAAQ;KAC3B,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,CAAC;IACnC,IAAI,QAAQ,EAAE,CAAC;QACd,OAAO,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,OAAO,EAAE,KAAK,EAAE,CAAC;QACpB,sEAAsE;QACtE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACnC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IAED,2EAA2E;IAC3E,mCAAmC;IACnC,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAC/B,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;QAC9B,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC;IAC1B,CAAC;SAAM,CAAC;QACP,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,SAAS,EAAE,EAAE;YACjE,IAAI,EAAE,IAAI;SACV,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC;AAChB,CAAC"}

package/dist/shell/escape-command-arg.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Escape a string to be safely used as a shell argument, using the rules of the
+ * current platform.
+ *
+ * @param expr The string to escape
+ * @returns The escaped string
+ */
+export declare const escapeCommandArg: (expr: string) => string;
+//# sourceMappingURL=escape-command-arg.d.ts.map

package/dist/shell/escape-command-arg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-command-arg.d.ts","sourceRoot":"","sources":["../../src/shell/escape-command-arg.ts"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAGtB,CAAC"}

package/dist/shell/escape-command-arg.js

@@ -0,0 +1,13 @@
+import { platform as processPlatform } from "node:process";
+import { escapePosixShCommandArg, escapeWin32CmdCommandArg, } from "@ac-kit/core";
+/**
+ * Escape a string to be safely used as a shell argument, using the rules of the
+ * current platform.
+ *
+ * @param expr The string to escape
+ * @returns The escaped string
+ */
+export const escapeCommandArg = processPlatform === "win32"
+    ? escapeWin32CmdCommandArg
+    : escapePosixShCommandArg;
+//# sourceMappingURL=escape-command-arg.js.map

package/dist/shell/escape-command-arg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-command-arg.js","sourceRoot":"","sources":["../../src/shell/escape-command-arg.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,eAAe,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,EACN,uBAAuB,EACvB,wBAAwB,GACxB,MAAM,cAAc,CAAC;AAEtB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAC5B,eAAe,KAAK,OAAO;IAC1B,CAAC,CAAC,wBAAwB;IAC1B,CAAC,CAAC,uBAAuB,CAAC"}

package/dist/shell/escape-command.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Escapes any characters in a string that might be used to trick a shell
+ * command into executing arbitrary commands, using the rules of the current
+ * platform.
+ *
+ * @param cmd The command to escape
+ * @returns The escaped command
+ */
+export declare const escapeCommand: (cmd: string) => string;
+//# sourceMappingURL=escape-command.d.ts.map

package/dist/shell/escape-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-command.d.ts","sourceRoot":"","sources":["../../src/shell/escape-command.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAC8B,CAAC"}

package/dist/shell/escape-command.js

@@ -0,0 +1,12 @@
+import { platform as processPlatform } from "node:process";
+import { escapePosixShCommand, escapeWin32CmdCommand } from "@ac-kit/core";
+/**
+ * Escapes any characters in a string that might be used to trick a shell
+ * command into executing arbitrary commands, using the rules of the current
+ * platform.
+ *
+ * @param cmd The command to escape
+ * @returns The escaped command
+ */
+export const escapeCommand = processPlatform === "win32" ? escapeWin32CmdCommand : escapePosixShCommand;
+//# sourceMappingURL=escape-command.js.map

package/dist/shell/escape-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-command.js","sourceRoot":"","sources":["../../src/shell/escape-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,eAAe,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE3E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GACzB,eAAe,KAAK,OAAO,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,oBAAoB,CAAC"}

package/dist/stream/non-closing-writable-stream.d.ts

@@ -0,0 +1,14 @@
+import { Writable } from "node:stream";
+/**
+ * Create a `WritableStream<string>` that wraps a Node `Writable` but never
+ * closes it.
+ *
+ * `Writable.toWeb(stream).getWriter().close()` ends the underlying stream,
+ * which never resolves for `process.stdout`/`process.stderr` on a TTY (a
+ * well-known Node limitation — closing a WHATWG-wrapped TTY writable hangs
+ * forever, reproduced with nothing more than `Writable.toWeb(process.stdout)` +
+ * `writer.close()`). Use this instead of `Writable.toWeb` directly for any
+ * stream whose lifecycle isn't the caller's to end.
+ */
+export declare function nonClosingWritableStream(stream: Writable): WritableStream<string>;
+//# sourceMappingURL=non-closing-writable-stream.d.ts.map

package/dist/stream/non-closing-writable-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"non-closing-writable-stream.d.ts","sourceRoot":"","sources":["../../src/stream/non-closing-writable-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACvC,MAAM,EAAE,QAAQ,GACd,cAAc,CAAC,MAAM,CAAC,CAOxB"}