first-base 2.0.2 → 3.0.1

package/.node-version

@@ -1 +1 @@
-v24.13.0
+v24.14.1

package/.npm-version

@@ -1 +1 @@
-11.6.2
+11.11.0

package/README.md

@@ -183,3 +183,8 @@ The only things that changed between 1.x and 2.0 are:
   - Linux arm64 and x86_64
   - macOS arm64 and x86_64
   - Windows arm64 and x86_64
+
+## Upgrading from 2.x
+
+- The type definitions for `RunContext.write` and `RunContext.kill` were narrowed slightly. The runtime behavior of those methods didn't change.
+- `RunContext.debug()` is deprecated (but not removed). Use `spawn` option `debug: true` instead.

package/dist/find-root-dir.d.ts

@@ -0,0 +1 @@
+export declare function findRootDir(startingDir: string): string;

package/dist/find-root-dir.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findRootDir = findRootDir;
+const fs_1 = __importDefault(require("fs"));
+const nice_path_1 = require("nice-path");
+const strongRootDirIndicators = [".git", ".hg"];
+const weakRootDirIndicators = ["package-lock.json", ".gitignore", ".hgignore"];
+const veryWeakRootDirIndicators = ["package.json", "README.md"];
+function hasFile(dir, filename) {
+    const fullPath = dir.concat(filename).toString();
+    try {
+        return fs_1.default.existsSync(fullPath);
+    }
+    catch (err) {
+        return false;
+    }
+}
+function findRootDir(startingDir) {
+    const start = new nice_path_1.Path(startingDir).normalize();
+    const searchDirs = [start];
+    let currentPath = start.replaceLast([]);
+    while (currentPath.segments.length > 0) {
+        searchDirs.push(currentPath);
+        currentPath = currentPath.replaceLast([]);
+    }
+    for (const dir of searchDirs) {
+        for (const indicator of strongRootDirIndicators) {
+            if (hasFile(dir, indicator)) {
+                return dir.toString();
+            }
+        }
+    }
+    for (const dir of searchDirs) {
+        for (const indicator of weakRootDirIndicators) {
+            if (hasFile(dir, indicator)) {
+                return dir.toString();
+            }
+        }
+    }
+    for (const dir of searchDirs) {
+        for (const indicator of veryWeakRootDirIndicators) {
+            if (hasFile(dir, indicator)) {
+                return dir.toString();
+            }
+        }
+    }
+    return start.toString();
+}

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+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 };

package/dist/index.js

@@ -0,0 +1,297 @@
+"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");
+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;
+                }
+                debugLog("NOTE: 'exit' event doesn't resolve completion. Waiting for 'close' event.");
+            });
+            debugLog("using 'on' method to listen for child close event");
+            child.on("close", (code) => {
+                debugLog("'close' 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/index.js.flow

@@ -0,0 +1,43 @@
+// @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;

package/dist/sanitizers.d.ts

@@ -0,0 +1 @@
+export declare const sanitizers: Array<(str: string) => string>;

package/dist/sanitizers.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizers = void 0;
+const strip_ansi_1 = __importDefault(require("strip-ansi"));
+const find_root_dir_1 = require("./find-root-dir");
+function escapeRegex(str) {
+    return str.replace(/[/\-\\^$*+?.()|[\]{}]/g, "\\$&");
+}
+const replaceRootDir = Object.assign(function _replaceRootDir(str) {
+    const here = process.cwd();
+    const rootDir = replaceRootDir.cache.get(here) || (0, find_root_dir_1.findRootDir)(here);
+    replaceRootDir.cache.set(here, rootDir);
+    return str.replace(new RegExp(escapeRegex(rootDir), "g"), "<rootDir>");
+}, {
+    cache: new Map(),
+});
+exports.sanitizers = [
+    strip_ansi_1.default,
+    replaceRootDir,
+    function replaceCwd(str) {
+        return str.replace(new RegExp(escapeRegex(process.cwd()), "g"), "<cwd>");
+    },
+    function collapseStackTrace(str) {
+        return (str
+            // replace stack trace lines with a single "at somewhere" line
+            // explanation of regexp:
+            //   newline, optional ansi escape, zero or more whitespace(s), "at",
+            //   whitespace(s), several non-newline characters... and that whole
+            //   thing can happen more than once
+            .replaceAll(/(?:\n(?:\x1B\[\d+m)?(\s*)at\s+[^\n]+)+/g, "\n$1at somewhere"));
+    },
+    function omitThrowLineNumber(str) {
+        // omit line number from eg. "<rootDir>/dist/match.js:57\n\t\t\t\tthrow"
+        return str.replaceAll(/(\.js):\d+(\s+throw)/g, "$1$2");
+    },
+];

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "first-base",
-  "version": "2.0.2",
+  "version": "3.0.1",
   "description": "Integration testing for CLI applications",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/suchipi/first-base.git"
@@ -15,22 +16,13 @@
     "strip-ansi": "^5.0.0"
   },
   "devDependencies": {
-    "@babel/cli": "^7.28.6",
-    "@babel/core": "^7.29.0",
-    "@babel/preset-env": "^7.29.0",
-    "babel-core": "^7.0.0-bridge.0",
-    "babel-jest": "^30.2.0",
-    "eslint": "^8.56.0",
-    "eslint-config-unobtrusive": "^1.2.5",
-    "eslint-plugin-import": "^2.29.1",
-    "jest": "^30.2.0",
-    "prettier": "^3.8.1"
+    "@types/node": "^22.0.0",
+    "prettier": "^3.8.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
   },
   "scripts": {
-    "build": "mkdir -p dist; rm -rf dist/*; babel src --out-dir dist && cp src/index.js.flow dist/ && cp src/index.d.ts dist/",
-    "test": "jest"
-  },
-  "jest": {
-    "prettierPath": null
+    "build": "mkdir -p dist; rm -rf dist/*; tsc && rm -f dist/*.test.js dist/*.test.d.ts && cp src/index.js.flow dist/",
+    "test": "vitest run"
   }
 }

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "include": ["src/**/*.ts"],
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"],
+
+    // need this because @lydell/node-pty/package.json specifies "types" field
+    // but its "exports" field doesn't have "types".
+    //
+    // We can remove this after this is merged: https://github.com/lydell/node-pty/pull/15
+    "moduleResolution": "Node10",
+    "ignoreDeprecations": "6.0"
+  }
+}