first-base 3.0.0 → 4.0.0

package/dist/all-inflight-run-contexts.d.ts

@@ -0,0 +1,2 @@
+import type { RunContext } from "./run-context";
+export declare const allInflightRunContexts: Set<RunContext>;

package/dist/all-inflight-run-contexts.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allInflightRunContexts = void 0;
+exports.allInflightRunContexts = new Set();

package/dist/awaitable-buffer.d.ts

@@ -0,0 +1,14 @@
+export type AwaitableBufferRequest = {
+    value: string | RegExp;
+    resolve: () => void;
+    reject: (error: Error) => void;
+};
+export declare class AwaitableBuffer {
+    private _content;
+    private _requests;
+    request(value: string | RegExp): Promise<void>;
+    addContent(data: string): void;
+    private _check;
+    clearContent(): void;
+    cancelRequests(errorMaker: (request: AwaitableBufferRequest) => Error): void;
+}

package/dist/awaitable-buffer.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AwaitableBuffer = void 0;
+const defer_1 = __importDefault(require("@suchipi/defer"));
+const strip_ansi_1 = __importDefault(require("strip-ansi"));
+class AwaitableBuffer {
+    _content = "";
+    _requests = new Set();
+    request(value) {
+        const defer = new defer_1.default();
+        const request = {
+            value,
+            resolve: () => {
+                this._requests.delete(request);
+                defer.resolve();
+            },
+            reject: (error) => {
+                this._requests.delete(request);
+                defer.reject(error);
+            },
+        };
+        this._requests.add(request);
+        this._check();
+        return defer.promise;
+    }
+    addContent(data) {
+        this._content += data;
+        this._check();
+    }
+    _check() {
+        for (const request of this._requests) {
+            if (typeof request.value === "string") {
+                if ((0, strip_ansi_1.default)(this._content).indexOf(request.value) != -1) {
+                    request.resolve();
+                }
+            }
+            else if (request.value instanceof RegExp) {
+                if (request.value.test((0, strip_ansi_1.default)(this._content))) {
+                    request.resolve();
+                }
+            }
+        }
+    }
+    clearContent() {
+        this._content = "";
+    }
+    cancelRequests(errorMaker) {
+        for (const request of this._requests) {
+            request.reject(errorMaker(request));
+        }
+    }
+}
+exports.AwaitableBuffer = AwaitableBuffer;

package/dist/index.d.ts

@@ -1,44 +1,5 @@
-import { sanitizers } from "./sanitizers";
-export type Options = {
-    cwd?: string;
-    env?: {
-        [varName: string]: string | undefined;
-    };
-    argv0?: string;
-    detached?: boolean;
-    uid?: number;
-    gid?: number;
-    shell?: boolean | string;
-    windowsVerbatimArguments?: boolean;
-    windowsHide?: boolean;
-    pty?: boolean;
-    debug?: boolean;
-};
-export type RunContext = {
-    result: {
-        stdout: string;
-        stderr: string;
-        code: null | number;
-        error: null | Error;
-    };
-    cleanResult(): {
-        stdout: string;
-        stderr: string;
-        code: null | number;
-        error: null | Error;
-    };
-    completion: Promise<void>;
-    /** @deprecated pass `debug: true` as an option to {@link spawn} instead. */
-    debug(): RunContext;
-    outputContains(value: string | RegExp): Promise<void>;
-    clearOutputContainsBuffer(): void;
-    write(data: string | Buffer): void;
-    close(stream: "stdin" | "stdout" | "stderr"): void;
-    kill(signal?: NodeJS.Signals): void;
-};
-declare const allInflightRunContexts: Set<RunContext>;
-declare function spawn(cmd: string): RunContext;
-declare function spawn(cmd: string, args: Array<string>): RunContext;
-declare function spawn(cmd: string, options: Options): RunContext;
-declare function spawn(cmd: string, args: Array<string>, options: Options): RunContext;
-export { spawn, sanitizers, allInflightRunContexts };
+export { spawn } from "./spawn";
+export type { SpawnOptions as Options } from "./spawn-options";
+export { allInflightRunContexts } from "./all-inflight-run-contexts";
+export { sanitizers, type ReplaceRootDir as ReplaceRootDirSanitizer, } from "./sanitizers";
+export type { RunContext, NonPtyRunContext, PtyRunContext, NonPtyRunContextResult, PtyRunContextResult, } from "./run-context";

package/dist/index.js

@@ -1,289 +1,9 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.allInflightRunContexts = exports.sanitizers = void 0;
-exports.spawn = spawn;
-const child_process_1 = require("child_process");
-const strip_ansi_1 = __importDefault(require("strip-ansi"));
-const sanitizers_1 = require("./sanitizers");
+exports.sanitizers = exports.allInflightRunContexts = exports.spawn = void 0;
+var spawn_1 = require("./spawn");
+Object.defineProperty(exports, "spawn", { enumerable: true, get: function () { return spawn_1.spawn; } });
+var all_inflight_run_contexts_1 = require("./all-inflight-run-contexts");
+Object.defineProperty(exports, "allInflightRunContexts", { enumerable: true, get: function () { return all_inflight_run_contexts_1.allInflightRunContexts; } });
+var sanitizers_1 = require("./sanitizers");
 Object.defineProperty(exports, "sanitizers", { enumerable: true, get: function () { return sanitizers_1.sanitizers; } });
-const allInflightRunContexts = new Set();
-exports.allInflightRunContexts = allInflightRunContexts;
-function spawn(cmd, argsOrOptions, passedOptions) {
-    let args;
-    let options;
-    if (Array.isArray(argsOrOptions)) {
-        args = argsOrOptions;
-    }
-    else if (typeof argsOrOptions === "object") {
-        options = argsOrOptions;
-    }
-    if (passedOptions && !options) {
-        options = passedOptions;
-    }
-    if (!args) {
-        args = [];
-    }
-    if (!options) {
-        options = {};
-    }
-    let child;
-    let stdin;
-    let stdout;
-    let stderr;
-    let unreffable = null;
-    let running;
-    let debug = options.debug ?? false;
-    let outputContainsBuffer = "";
-    let pendingOutputContainsRequests = new Set();
-    const disposables = [];
-    const debugLog = (...msg) => {
-        if (debug) {
-            console.log(...msg);
-        }
-    };
-    const runContext = {
-        result: {
-            // All of the stdout and stderr the process has written so far.
-            stdout: "",
-            stderr: "",
-            // Exit status code, if the process has finished.
-            code: null,
-            // if the process errored out, this will be the Error
-            error: null,
-        },
-        // Return a version of result which has had the string sanitizers run on it
-        cleanResult() {
-            return Object.assign({}, runContext.result, {
-                stdout: sanitizers_1.sanitizers.reduce((str, transformFn) => transformFn(str), runContext.result.stdout),
-                stderr: sanitizers_1.sanitizers.reduce((str, transformFn) => transformFn(str), runContext.result.stderr),
-            });
-        },
-        // Promise that gets resolved when the child process completes.
-        // Actual value gets filled in below.
-        completion: Promise.resolve(),
-        debug() {
-            debug = true;
-            return this;
-        },
-        // Returns a Promise that resolves once the child process output
-        // (combined stdout and stderr) contains the passed string or
-        // matches the passed RegExp. Ignores ansi control characters.
-        outputContains(value) {
-            debugLog(`Waiting for output to contain ${JSON.stringify(value)}...`);
-            return new Promise((resolve, reject) => {
-                const request = { value, resolve: undefined, reject: undefined };
-                request.resolve = () => {
-                    pendingOutputContainsRequests.delete(request);
-                    resolve();
-                };
-                request.reject = (error) => {
-                    pendingOutputContainsRequests.delete(request);
-                    reject(error);
-                };
-                pendingOutputContainsRequests.add(request);
-            });
-        },
-        clearOutputContainsBuffer() {
-            outputContainsBuffer = "";
-        },
-        // Call this function to write into stdin.
-        write(data) {
-            stdin.write(data);
-        },
-        // Call this function to close stdin, stdout, or stderr.
-        close(stream) {
-            switch (String(stream).toLowerCase()) {
-                case "stdin": {
-                    if ("end" in stdin) {
-                        stdin.end();
-                    }
-                    break;
-                }
-                case "stdout": {
-                    if ("destroy" in stdout) {
-                        stdout.destroy();
-                    }
-                    break;
-                }
-                case "stderr": {
-                    if (stderr != null && "destroy" in stderr) {
-                        stderr.destroy();
-                    }
-                    break;
-                }
-                default: {
-                    throw new Error(`Invalid stream name: '${stream}'. Valid names are 'stdin', 'stdout', or 'stderr'.`);
-                }
-            }
-        },
-        // Call this function to send a signal to the child process.
-        // You can pass "SIGTERM", "SIGKILL", etc. Defaults to "SIGINT".
-        kill(signal = "SIGINT") {
-            if (running) {
-                child.kill(signal);
-            }
-            if (unreffable != null) {
-                unreffable.unref();
-            }
-        },
-    };
-    if (options.pty) {
-        debugLog("pty option was true; using node-pty");
-        const ptySpawn = require("@lydell/node-pty").spawn;
-        const ptyChild = ptySpawn(cmd, args, options);
-        child = ptyChild;
-        stdin = ptyChild;
-        stdout = ptyChild;
-        stderr = null; // no way to tell between stdout and stderr with pty
-        // no unreffable equivalent on ptyChild
-    }
-    else {
-        debugLog("pty option was NOT true; using child_process");
-        const nonPtyChild = (0, child_process_1.spawn)(cmd, args, options);
-        child = nonPtyChild;
-        stdin = nonPtyChild.stdin;
-        stdout = nonPtyChild.stdout;
-        stderr = nonPtyChild.stderr;
-        unreffable = nonPtyChild;
-    }
-    running = true;
-    allInflightRunContexts.add(runContext);
-    if ("on" in child) {
-        debugLog("using 'on' method to listen for child spawn event");
-        child.on("spawn", () => {
-            debugLog("'spawn' event");
-        });
-    }
-    else {
-        debugLog("child had no 'on' method, so child spawn event listener wasn't set up");
-    }
-    const checkForPendingOutputRequestsToResolve = () => {
-        pendingOutputContainsRequests.forEach((request) => {
-            if (typeof request.value === "string") {
-                if ((0, strip_ansi_1.default)(outputContainsBuffer).indexOf(request.value) != -1) {
-                    request.resolve();
-                }
-            }
-            else if (request.value instanceof RegExp) {
-                if (request.value.test((0, strip_ansi_1.default)(outputContainsBuffer))) {
-                    request.resolve();
-                }
-            }
-        });
-    };
-    if ("setEncoding" in stdout) {
-        debugLog("setting stdout encoding to utf-8");
-        stdout.setEncoding("utf-8");
-    }
-    else {
-        debugLog("not setting stdout encoding because the setEncoding method was not present");
-    }
-    const handleStdoutData = (data) => {
-        runContext.result.stdout += data;
-        outputContainsBuffer += data;
-        debugLog(`STDOUT: ${data.toString()}`);
-        checkForPendingOutputRequestsToResolve();
-    };
-    if ("onData" in stdout) {
-        debugLog("using 'onData' method to listen for stdout data event");
-        // the pty instance returned by node-pty
-        // requires attaching handlers differently
-        stdout.onData(handleStdoutData);
-    }
-    else {
-        debugLog("using 'on' method to listen for stdout data event");
-        stdout.on("data", handleStdoutData);
-    }
-    if (stderr) {
-        debugLog("setting stderr encoding to utf-8");
-        stderr.setEncoding("utf-8");
-        // this is never a pty instance,
-        // so we don't need to deal with onData here:
-        debugLog("using 'on' method to listen for stderr data event");
-        stderr.on("data", (data) => {
-            runContext.result.stderr += data;
-            outputContainsBuffer += data;
-            debugLog(`STDERR: ${data.toString()}`);
-            checkForPendingOutputRequestsToResolve();
-        });
-    }
-    else {
-        debugLog("stderr isn't present (pty mixes stdout and stderr together), so not setting encoding or setting up data event listener for stderr");
-    }
-    runContext.completion = new Promise((resolve) => {
-        let hasFinished = false;
-        const finish = (reason) => {
-            debugLog("in finish", runContext.result);
-            if (hasFinished) {
-                debugLog("finish called more than once; ignoring");
-            }
-            else {
-                running = false;
-                allInflightRunContexts.delete(runContext);
-                resolve();
-                for (const request of pendingOutputContainsRequests) {
-                    request.reject(new Error(`Child process ${reason} before its output contained the requested content: ${request.value}`));
-                }
-                for (const disposable of disposables) {
-                    disposable.dispose();
-                }
-                hasFinished = true;
-            }
-        };
-        if ("on" in child) {
-            debugLog("using 'on' method to listen for child close event");
-            child.on("close", (code, signal) => {
-                debugLog("'close' event", { code, signal });
-                if (code != null) {
-                    runContext.result.code = code;
-                }
-            });
-        }
-        else {
-            debugLog("child had no 'on' method, so child close event listener wasn't set up");
-        }
-        if ("onExit" in child) {
-            debugLog("using 'onExit' method to listen for child exit event");
-            const disposable = child.onExit(({ exitCode, signal }) => {
-                debugLog("onExit", { exitCode, signal });
-                if (exitCode != null) {
-                    runContext.result.code = exitCode;
-                }
-                finish("exited");
-            });
-            disposables.push(disposable);
-        }
-        else {
-            debugLog("using 'on' method to listen for child exit event");
-            child.on("exit", (code) => {
-                debugLog("'exit' event", { code });
-                if (code != null) {
-                    runContext.result.code = code;
-                }
-                finish("exited");
-            });
-        }
-        if ("on" in child) {
-            debugLog("using 'on' method to listen for child error event");
-            child.on("error", (error) => {
-                debugLog("'error' event", { error });
-                if (typeof error === "object" &&
-                    error !== null &&
-                    error.code === "EIO") {
-                    // not real; process is about to exit
-                    debugLog("Ignoring spurious EIO error:", error);
-                    return;
-                }
-                runContext.result.error = error;
-                finish("errored");
-            });
-        }
-        else {
-            debugLog("child had no 'on' method, so child error event listener wasn't set up");
-        }
-    });
-    return runContext;
-}

package/dist/run-context.d.ts

@@ -0,0 +1,94 @@
+export type PtyRunContextResult = {
+    /** All of the output the process has written so far (pty mode combines stdout and stderr). */
+    output: string;
+    /** Exit status code, if the process has finished. */
+    code: null | number;
+    /** If the process errored out (ie. failed to spawn, etc), this will be the Error. */
+    error: null | Error;
+};
+export type PtyRunContext = {
+    /** Outputs of the running or completed process. */
+    result: PtyRunContextResult;
+    /** Returns a version of {@link PtyRunContext["result"]} with all the {@link sanitizers} run over it. */
+    cleanResult(): PtyRunContextResult;
+    /**
+     * Resolves after the node-pty process's "onExit" callback is called.
+     */
+    completion: Promise<void>;
+    /**
+     * Returns a Promise that resolves once the child process output
+     * (combined stdout and stderr) contains the passed string or
+     * matches the passed RegExp. Ignores ansi control characters.
+     */
+    outputContains(value: string | RegExp): Promise<void>;
+    /**
+     * Call this to reset the buffer used by the process's `outputContains`
+     * tracking. This is needed if you want to wait for the same output to appear
+     * a second time.
+     */
+    clearOutputContainsBuffer(): void;
+    /** Call this to write to the child's stdin. */
+    write(data: string | Buffer): void;
+    /**
+     * Call this function to send a signal to the child process.
+     * You can pass "SIGTERM", "SIGKILL", etc. Defaults to "SIGINT".
+     */
+    kill(signal?: NodeJS.Signals): void;
+    /** Indicates that the process was spawned in a pseudo-tty. */
+    pty: true;
+};
+export type NonPtyRunContextResult = {
+    /** All of the stdout the process has written so far. */
+    stdout: string;
+    /** All of the stderr the process has written so far. */
+    stderr: string;
+    /** Exit status code, if the process has finished. */
+    code: null | number;
+    /** If the process errored out (ie. failed to spawn, etc), this will be the Error. */
+    error: null | Error;
+};
+export type NonPtyRunContext = {
+    /** Outputs of the running or completed process. */
+    result: NonPtyRunContextResult;
+    /** Returns a version of {@link NonPtyRunContext["result"]} with all the {@link sanitizers} run over it. */
+    cleanResult(): NonPtyRunContextResult;
+    /**
+     * Resolves after the child process has emitted its "exit" event AND its
+     * "close" event.
+     */
+    completion: Promise<void>;
+    /**
+     * Resolves after the first time the child process emits the corresponding
+     * event.
+     */
+    eventFired(eventName: "spawn"): Promise<void>;
+    eventFired(eventName: "error"): Promise<Error & {
+        code?: string;
+    }>;
+    eventFired(eventName: "exit"): Promise<[code: number | null, signal: NodeJS.Signals | null]>;
+    eventFired(eventName: "close"): Promise<[code: number | null, signal: NodeJS.Signals | null]>;
+    /**
+     * Returns a Promise that resolves once the child process output
+     * (combined stdout and stderr) contains the passed string or
+     * matches the passed RegExp. Ignores ansi control characters.
+     */
+    outputContains(value: string | RegExp): Promise<void>;
+    /**
+     * Call this to reset the buffer used by the process's `outputContains`
+     * tracking. This is needed if you want to wait for the same output to appear
+     * a second time.
+     */
+    clearOutputContainsBuffer(): void;
+    /** Call this to write to the child's stdin. */
+    write(data: string | Buffer): void;
+    /** Call this to close one of the child process's stdio streams. */
+    close(stream: "stdin" | "stdout" | "stderr"): void;
+    /**
+     * Call this function to send a signal to the child process.
+     * You can pass "SIGTERM", "SIGKILL", etc. Defaults to "SIGINT".
+     */
+    kill(signal?: NodeJS.Signals): void;
+    /** Indicates that the process was NOT spawned in a pseudo-tty. */
+    pty: false;
+};
+export type RunContext<IsPty extends boolean = boolean> = IsPty extends true ? PtyRunContext : IsPty extends false ? NonPtyRunContext : PtyRunContext | NonPtyRunContext;

package/dist/run-context.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/sanitizers.d.ts

@@ -1 +1,19 @@
+export interface ReplaceRootDir {
+    (str: string): string;
+    /**
+     * If you want to bypass the builtin "find root dir" logic used by the
+     * replaceRootDir sanitizer, you can run:
+     *
+     * ```ts
+     * const replaceRootDir = sanitizers.find(fn => fn.name === "replaceRootDir");
+     * replaceRootDir.cache.set(process.cwd(), "/home/me/my-project");
+     * ```
+     *
+     * If `process.cwd()` changes during the course of a test run, you'll need to
+     * add cache entries for the other locations, too. If that's too inconvenient,
+     * you're welcome to remove replaceRootDir from the sanitizers array and
+     * optionally replace it with your own implementation.
+     */
+    cache: Map<string, string>;
+}
 export declare const sanitizers: Array<(str: string) => string>;

package/dist/sanitizers.js

@@ -17,6 +17,13 @@ const replaceRootDir = Object.assign(function _replaceRootDir(str) {
 }, {
     cache: new Map(),
 });
+// Minifier protection so the above documented code snippet remains possible
+Object.defineProperty(replaceRootDir, "name", {
+    configurable: true,
+    enumerable: false,
+    writable: false,
+    value: "replaceRootDir",
+});
 exports.sanitizers = [
     strip_ansi_1.default,
     replaceRootDir,

package/dist/spawn-non-pty.d.ts

@@ -0,0 +1,3 @@
+import type { NonPtyRunContext } from "./run-context";
+import type { SpawnOptions } from "./spawn-options";
+export declare function spawnNonPty(cmd: string, args: Array<string>, options: SpawnOptions, debugLog: (...msg: Array<any>) => void): NonPtyRunContext;

package/dist/spawn-non-pty.js

@@ -0,0 +1,170 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnNonPty = spawnNonPty;
+const child_process_1 = require("child_process");
+const defer_1 = __importDefault(require("@suchipi/defer"));
+const sanitizers_1 = require("./sanitizers");
+const all_inflight_run_contexts_1 = require("./all-inflight-run-contexts");
+const awaitable_buffer_1 = require("./awaitable-buffer");
+function spawnNonPty(cmd, args, options, debugLog) {
+    debugLog("in spawnNonPtyRunContext");
+    let child;
+    let stdin;
+    let stdout;
+    let stderr;
+    let running;
+    const outputBuffer = new awaitable_buffer_1.AwaitableBuffer();
+    const eventDefers = {
+        exit: new defer_1.default(),
+        error: new defer_1.default(),
+        spawn: new defer_1.default(),
+        close: new defer_1.default(),
+    };
+    const runContext = {
+        pty: false,
+        result: {
+            stdout: "",
+            stderr: "",
+            code: null,
+            error: null,
+        },
+        cleanResult() {
+            return {
+                ...runContext.result,
+                stdout: sanitizers_1.sanitizers.reduce((str, transformFn) => transformFn(str), runContext.result.stdout),
+                stderr: sanitizers_1.sanitizers.reduce((str, transformFn) => transformFn(str), runContext.result.stderr),
+            };
+        },
+        // Placeholder; real value gets filled in below.
+        completion: Promise.resolve(),
+        outputContains(value) {
+            debugLog(`Waiting for output to contain ${typeof value === "string" ? JSON.stringify(value) : String(value)}...`);
+            return outputBuffer.request(value);
+        },
+        eventFired(eventName) {
+            const defer = eventDefers[eventName];
+            if (defer != null) {
+                return defer.promise;
+            }
+            throw new Error(`Invalid event name: ${JSON.stringify(eventName)}`);
+        },
+        clearOutputContainsBuffer() {
+            outputBuffer.clearContent();
+        },
+        write(data) {
+            stdin.write(data);
+        },
+        close(stream) {
+            switch (String(stream).toLowerCase()) {
+                case "stdin": {
+                    if ("end" in stdin) {
+                        stdin.end();
+                    }
+                    break;
+                }
+                case "stdout": {
+                    stdout.destroy();
+                    break;
+                }
+                case "stderr": {
+                    stderr.destroy();
+                    break;
+                }
+                default: {
+                    throw new Error(`Invalid stream name: '${stream}'. Valid names are 'stdin', 'stdout', or 'stderr'.`);
+                }
+            }
+        },
+        kill(signal = "SIGINT") {
+            if (running) {
+                child.kill(signal);
+            }
+            child.unref();
+        },
+    };
+    child = (0, child_process_1.spawn)(cmd, args, options);
+    stdin = child.stdin;
+    stdout = child.stdout;
+    stderr = child.stderr;
+    running = true;
+    all_inflight_run_contexts_1.allInflightRunContexts.add(runContext);
+    debugLog("setting up spawn event listener");
+    child.on("spawn", () => {
+        debugLog("'spawn' event");
+        eventDefers.spawn?.resolve();
+    });
+    debugLog("setting stdout encoding to utf-8");
+    stdout.setEncoding("utf-8");
+    debugLog("setting up stdout data event listener");
+    stdout.on("data", (data) => {
+        debugLog("STDOUT: ", data);
+        runContext.result.stdout += data;
+        outputBuffer.addContent(data);
+    });
+    debugLog("setting stderr encoding to utf-8");
+    stderr.setEncoding("utf-8");
+    debugLog("setting up stderr data event listener");
+    stderr.on("data", (data) => {
+        debugLog("STDERR: ", data);
+        runContext.result.stderr += data;
+        outputBuffer.addContent(data);
+    });
+    const completionDefer = new defer_1.default();
+    let hasClosed = false;
+    let hasExited = false;
+    const endings = {
+        complete: () => {
+            running = false;
+            all_inflight_run_contexts_1.allInflightRunContexts.delete(runContext);
+            completionDefer.resolve();
+            outputBuffer.cancelRequests((request) => new Error(`Child process closed and exited before its output contained the requested content: ${request.value}`));
+        },
+        fail: (error) => {
+            running = false;
+            runContext.result.error = error;
+            all_inflight_run_contexts_1.allInflightRunContexts.delete(runContext);
+            completionDefer.reject(error);
+            outputBuffer.cancelRequests((request) => new Error(`Child process errored before its output contained the requested content: ${request.value}`));
+        },
+    };
+    debugLog("setting up child close event listener");
+    child.on("close", (code, signal) => {
+        debugLog("'close' event", { code, signal });
+        hasClosed = true;
+        eventDefers.close?.resolve([code, signal]);
+        if (code != null && runContext.result.code == null) {
+            runContext.result.code = code;
+        }
+        if (hasExited) {
+            endings.complete();
+        }
+    });
+    debugLog("setting up child exit event listener");
+    child.on("exit", (code, signal) => {
+        debugLog("'exit' event", { code });
+        hasExited = true;
+        eventDefers.exit.resolve([code, signal]);
+        if (code != null && runContext.result.code == null) {
+            runContext.result.code = code;
+        }
+        if (hasClosed) {
+            endings.complete();
+        }
+    });
+    debugLog("setting up child error event listener");
+    child.on("error", (error) => {
+        debugLog("'error' event", { error });
+        eventDefers.error?.resolve(error);
+        if (typeof error === "object" && error !== null && error.code === "EIO") {
+            // not real; process is about to exit
+            debugLog("Ignoring spurious EIO error:", error);
+            return;
+        }
+        endings.fail(error);
+    });
+    runContext.completion = completionDefer.promise;
+    return runContext;
+}

package/dist/spawn-options.d.ts

@@ -0,0 +1,15 @@
+export type SpawnOptions = {
+    cwd?: string;
+    env?: {
+        [varName: string]: string | undefined;
+    };
+    argv0?: string;
+    detached?: boolean;
+    uid?: number;
+    gid?: number;
+    shell?: boolean | string;
+    windowsVerbatimArguments?: boolean;
+    windowsHide?: boolean;
+    pty?: boolean;
+    debug?: boolean;
+};

package/dist/spawn-options.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/spawn-pty.d.ts

@@ -0,0 +1,3 @@
+import type { PtyRunContext } from "./run-context";
+import type { SpawnOptions } from "./spawn-options";
+export declare function spawnPty(cmd: string, args: Array<string>, options: SpawnOptions, debugLog: (...msg: Array<any>) => void): PtyRunContext;

package/dist/spawn-pty.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnPty = spawnPty;
+const defer_1 = __importDefault(require("@suchipi/defer"));
+const sanitizers_1 = require("./sanitizers");
+const all_inflight_run_contexts_1 = require("./all-inflight-run-contexts");
+const awaitable_buffer_1 = require("./awaitable-buffer");
+function spawnPty(cmd, args, options, debugLog) {
+    debugLog("in spawnPtyRunContext");
+    let child;
+    let running;
+    const outputBuffer = new awaitable_buffer_1.AwaitableBuffer();
+    const disposables = [];
+    const runContext = {
+        pty: true,
+        result: {
+            output: "",
+            code: null,
+            error: null,
+        },
+        cleanResult() {
+            return {
+                ...runContext.result,
+                output: sanitizers_1.sanitizers.reduce((str, transformFn) => transformFn(str), runContext.result.output),
+            };
+        },
+        // Placeholder; actual value gets filled in below.
+        completion: Promise.resolve(),
+        outputContains(value) {
+            debugLog(`Waiting for output to contain ${typeof value === "string" ? JSON.stringify(value) : String(value)}...`);
+            return outputBuffer.request(value);
+        },
+        clearOutputContainsBuffer() {
+            outputBuffer.clearContent();
+        },
+        write(data) {
+            child.write(data);
+        },
+        kill(signal = "SIGINT") {
+            if (running) {
+                child.kill(signal);
+            }
+        },
+    };
+    const ptySpawn = require("@lydell/node-pty").spawn;
+    const ptyChild = ptySpawn(cmd, args, options);
+    child = ptyChild;
+    running = true;
+    all_inflight_run_contexts_1.allInflightRunContexts.add(runContext);
+    debugLog("using 'onData' method to listen for child data event");
+    disposables.push(child.onData((data) => {
+        debugLog(`OUTPUT: ${data.toString()}`);
+        runContext.result.output += data;
+        outputBuffer.addContent(data);
+    }));
+    const completionDefer = new defer_1.default();
+    debugLog("using 'onExit' method to listen for child exit event");
+    disposables.push(child.onExit(({ exitCode, signal }) => {
+        debugLog("onExit", { exitCode, signal });
+        if (exitCode != null) {
+            runContext.result.code = exitCode;
+        }
+        running = false;
+        all_inflight_run_contexts_1.allInflightRunContexts.delete(runContext);
+        for (const disposable of disposables) {
+            disposable.dispose();
+        }
+        completionDefer.resolve();
+        outputBuffer.cancelRequests((request) => new Error(`Child process exited before its output contained the requested content: ${request.value}`));
+    }));
+    runContext.completion = completionDefer.promise;
+    return runContext;
+}

package/dist/spawn.d.ts

@@ -0,0 +1,18 @@
+import type { NonPtyRunContext, PtyRunContext } from "./run-context";
+import type { SpawnOptions } from "./spawn-options";
+/**
+ * Start a child process and return a {@link RunContext} object to interact with
+ * it. Function signature is the same as child_process spawn, except you can
+ * pass `pty: true` in options to run the process in a psuedo-tty, and
+ * `debug: true` to enable debug output.
+ */
+export declare function spawn(cmd: string): NonPtyRunContext;
+export declare function spawn(cmd: string, args: Array<string>): NonPtyRunContext;
+export declare function spawn(cmd: string, options: SpawnOptions & {
+    pty: true;
+}): PtyRunContext;
+export declare function spawn(cmd: string, options: SpawnOptions): NonPtyRunContext;
+export declare function spawn(cmd: string, args: Array<string>, options: SpawnOptions & {
+    pty: true;
+}): PtyRunContext;
+export declare function spawn(cmd: string, args: Array<string>, options: SpawnOptions): NonPtyRunContext;

package/dist/spawn.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawn = spawn;
+const spawn_non_pty_1 = require("./spawn-non-pty");
+const spawn_pty_1 = require("./spawn-pty");
+function spawn(cmd, argsOrOptions, passedOptions) {
+    let args;
+    let options;
+    if (Array.isArray(argsOrOptions)) {
+        args = argsOrOptions;
+    }
+    else if (typeof argsOrOptions === "object") {
+        options = argsOrOptions;
+    }
+    if (passedOptions && !options) {
+        options = passedOptions;
+    }
+    if (!args) {
+        args = [];
+    }
+    if (!options) {
+        options = {};
+    }
+    const debug = options.debug ?? false;
+    const debugLog = (...msg) => {
+        if (debug) {
+            console.log(...msg);
+        }
+    };
+    if (options.pty) {
+        return (0, spawn_pty_1.spawnPty)(cmd, args, options, debugLog);
+    }
+    else {
+        return (0, spawn_non_pty_1.spawnNonPty)(cmd, args, options, debugLog);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "first-base",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Integration testing for CLI applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,6 +12,7 @@
   "license": "MIT",
   "dependencies": {
     "@lydell/node-pty": "^1.2.0-beta.3",
+    "@suchipi/defer": "^1.0.0",
     "nice-path": "^3.2.2",
     "strip-ansi": "^5.0.0"
   },
@@ -22,7 +23,7 @@
     "vitest": "^4.1.2"
   },
   "scripts": {
-    "build": "mkdir -p dist; rm -rf dist/*; tsc && rm -f dist/*.test.js dist/*.test.d.ts && cp src/index.js.flow dist/",
+    "build": "mkdir -p dist; rm -rf dist/*; tsc && rm -f dist/*.test.js dist/*.test.d.ts",
     "test": "vitest run"
   }
 }

package/dist/index.js.flow

@@ -1,43 +0,0 @@
-// @flow
-export type Options = {
-  cwd?: ?string,
-  env?: ?{ [varName: string]: string | undefined },
-  argv0?: ?string,
-  detached?: ?boolean,
-  uid?: ?number,
-  gid?: ?number,
-  shell?: ?boolean | string,
-  windowsVerbatimArguments?: ?boolean,
-  windowsHide?: ?boolean,
-  pty?: ?boolean,
-  debug?: ?boolean,
-};
-
-export type RunContext = {
-  result: {
-    stdout: string,
-    stderr: string,
-    code: null | number,
-    error: null | Error,
-  },
-  completion: Promise<void>,
-  debug(): RunContext,
-  outputContains(value: string | RegExp): Promise<void>,
-  clearOutputContainsBuffer(): void,
-  write(data: string | Buffer): void,
-  close(stream: "stdin" | "stdout" | "stderr"): void,
-  kill(signal?: string): void,
-};
-
-interface Exports {
-  spawn(cmd: string): RunContext;
-  spawn(cmd: string, args: Array<string>): RunContext;
-  spawn(cmd: string, options: Options): RunContext;
-  spawn(cmd: string, args: Array<string>, options: Options): RunContext;
-
-  sanitizers: Array<(str: string) => string>;
-
-  allInflightRunContexts: Set<RunContext>;
-}
-
-declare module.exports: Exports;