type-a-bin 0.1.0

package/dist/index.js

@@ -0,0 +1 @@
+export { mockBin, } from "./mock-bin.js";

package/dist/mock-bin-preload.d.ts

@@ -0,0 +1,21 @@
+interface MockTarget {
+    /** "node" redirects the main entry in-process; "spawn" runs a script. */
+    kind: "node" | "spawn";
+    /** Absolute path of the mock script to run. */
+    entry: string;
+    /** Interpreter name for "spawn" targets (e.g. "bash", "python"). */
+    interpreter?: string;
+    /** Regex source; only matching commands run the mock. */
+    pattern?: string;
+    /** PATH snapshot from before this mock was installed. */
+    originalPath?: string;
+}
+interface RunOriginalTarget {
+    binName: string;
+    originalPath: string;
+}
+interface MocksEnv {
+    targets?: Record<string, MockTarget>;
+    runOriginal?: RunOriginalTarget;
+}
+export type { MocksEnv, MockTarget };

package/dist/mock-bin-preload.js

@@ -0,0 +1,221 @@
+import { spawnSync } from "node:child_process";
+import { statSync } from "node:fs";
+import Module, { createRequire, registerHooks } from "node:module";
+import { basename, delimiter, extname, join, relative } from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { threadId } from "node:worker_threads";
+// Loaded through `NODE_OPTIONS --import` into every Node process a test
+// spawns while Windows mocks are active. A mock binary is a hard link of
+// node.exe renamed <bin>.exe, so the command line ("status", "--porcelain",
+// ...) is not a real module. This preload swaps the shim's main entry for
+// the mock script named in TYPE_A_BIN_MOCKS — argv, stdin, stdout, stderr,
+// and exit codes all pass through unchanged.
+const MOCKS_VAR = "TYPE_A_BIN_MOCKS";
+const HELPER_NAME = "mock-a-bin-run-original";
+const PATH_EXTENSIONS = ["", ".exe", ".cmd", ".bat", ".com"];
+const TS_EXTENSIONS = [".cts", ".mts", ".ts", ".tsx"];
+const BASH_LIKE_INTERPRETERS = ["bash", "dash", "ksh", "sh", "zsh"];
+const readMocks = () => {
+    try {
+        return JSON.parse(process.env[MOCKS_VAR] ?? "{}");
+    }
+    catch {
+        return {};
+    }
+};
+const mocks = readMocks();
+const invokedName = basename(process.argv[0] ?? "", extname(process.argv[0] ?? ""));
+// Node rewrites the CLI entry in argv[1] to an absolute path before
+// preloads run, losing the argument as the caller typed it. Recover it
+// relative to the working directory when possible, so mocks, patterns,
+// and spawned interpreters see "pr" instead of "C:\repo\pr".
+const denormalizeEntry = (entry) => {
+    const relativePath = relative(process.cwd(), entry);
+    if (relativePath === "" || relativePath.startsWith(".."))
+        return entry;
+    return relativePath;
+};
+// The shim's whole command line after the exe are CLI arguments: unlike
+// a Node script there is no "entry" consuming the first positional.
+const cliArgs = process.argv.length === 1
+    ? []
+    : [denormalizeEntry(process.argv[1] ?? ""), ...process.argv.slice(2)];
+const writeError = (message) => {
+    process.stderr.write(`${message}\n`);
+};
+// Lookup failures exit 127, matching the POSIX mock scripts.
+const fail = (message) => {
+    writeError(message);
+    process.exit(127);
+};
+const isFile = (candidate) => {
+    try {
+        return statSync(candidate).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+const searchPathDirs = (originalPath) => (originalPath ?? process.env.PATH ?? "")
+    .split(delimiter)
+    .filter((dir) => dir !== "" && !dir.includes("mock-bin-"));
+const pathCandidates = (name, dirs) => {
+    const candidates = [];
+    for (const dir of dirs)
+        for (const extension of PATH_EXTENSIONS) {
+            const candidate = join(dir, `${name}${extension}`);
+            if (isFile(candidate))
+                candidates.push(candidate);
+        }
+    return candidates;
+};
+const findExecutable = (name, dirs) => pathCandidates(name, dirs)[0] ?? null;
+const spawnRealAndExit = (command, args) => {
+    // The real binary must not be re-intercepted by this preload.
+    delete process.env[MOCKS_VAR];
+    const result = spawnSync(command, args, { stdio: "inherit" });
+    if (result.error !== undefined)
+        writeError(`Error: '${command}' failed to start: ${String(result.error)}`);
+    process.exit(result.status ?? 127);
+};
+const runOriginalCommand = (spec) => {
+    if (spec === undefined)
+        return fail(`Error: ${HELPER_NAME} used outside a mockBin context`);
+    const real = findExecutable(spec.binName, searchPathDirs(spec.originalPath));
+    if (real === null)
+        return fail(`Error: Original '${spec.binName}' command not found in PATH`);
+    return spawnRealAndExit(real, cliArgs);
+};
+const runRealBinary = (target) => {
+    const real = findExecutable(invokedName, searchPathDirs(target.originalPath));
+    if (real === null)
+        return fail(`Error: Real binary '${invokedName}' not found in PATH`);
+    return spawnRealAndExit(real, cliArgs);
+};
+// WSL's bash launcher lives in the Windows system directories; it cannot
+// run Windows-path scripts, so bash-like interpreters prefer a native
+// shell (e.g. Git for Windows) and fall back to well-known Git installs.
+const isWslLauncher = (candidate) => {
+    const lower = candidate.toLowerCase();
+    return (lower.includes("\\windows\\system32\\") || lower.includes("\\windowsapps\\"));
+};
+const gitBashCandidates = () => {
+    const roots = [
+        process.env.ProgramFiles ?? "",
+        process.env["ProgramFiles(x86)"] ?? "",
+        join(process.env.LOCALAPPDATA ?? "", "Programs"),
+    ];
+    const locations = [];
+    for (const root of roots)
+        if (root !== "") {
+            locations.push(join(root, "Git", "bin", "bash.exe"));
+            locations.push(join(root, "Git", "usr", "bin", "bash.exe"));
+        }
+    return locations;
+};
+const resolveInterpreter = (interpreter) => {
+    const dirs = (process.env.PATH ?? "")
+        .split(delimiter)
+        .filter((dir) => dir !== "");
+    const candidates = pathCandidates(interpreter, dirs);
+    if (BASH_LIKE_INTERPRETERS.includes(interpreter)) {
+        const native = candidates.find((candidate) => !isWslLauncher(candidate));
+        if (native !== undefined)
+            return native;
+        for (const location of gitBashCandidates())
+            if (isFile(location))
+                return location;
+    }
+    return candidates[0] ?? null;
+};
+const runInterpreterAndExit = (interpreter, entry) => {
+    const interpreterPath = resolveInterpreter(interpreter);
+    if (interpreterPath === null)
+        return fail(`Error: Interpreter '${interpreter}' not found in PATH`);
+    const result = spawnSync(interpreterPath, [entry, ...cliArgs], {
+        stdio: "inherit",
+    });
+    if (result.error !== undefined)
+        writeError(`Error: Interpreter '${interpreter}' failed: ${String(result.error)}`);
+    process.exit(result.status ?? 127);
+};
+const asPath = (specifier) => specifier.startsWith("file:") ? fileURLToPath(specifier) : specifier;
+// tsx registers its CommonJS hooks from a separate entry point; load it
+// lazily so non-TypeScript mocks never require the tsx package.
+const loadTsxCommonJs = (entry) => {
+    if (!TS_EXTENSIONS.includes(extname(entry).toLowerCase()))
+        return;
+    try {
+        createRequire(import.meta.url)("tsx/cjs");
+    }
+    catch {
+        // tsx is not installed: node's native type stripping applies instead.
+    }
+};
+const redirectNodeEntry = (entry) => {
+    // Node normalizes the CLI entry to an absolute path in argv[1] before
+    // preloads run. Capture it, then reposition argv so the mock sees the
+    // CLI arguments at process.argv.slice(2) like a real Node CLI script.
+    const originalEntry = process.argv[1] ?? "";
+    process.argv.length = 1;
+    process.argv.push(entry, ...cliArgs);
+    // ESM main entry: resolve hooks see the main module with no parent URL,
+    // so redirect that one resolution to the mock script. The tsx loader
+    // (registered before this preload in NODE_OPTIONS) transforms .ts
+    // entries as part of the same resolve chain.
+    registerHooks({
+        resolve: (specifier, context, nextResolve) => {
+            if (context.parentURL == null && asPath(specifier) === originalEntry)
+                return nextResolve(pathToFileURL(entry).href, context);
+            return nextResolve(specifier, context);
+        },
+    });
+    // CommonJS main entry: Module._load receives the CLI entry with isMain
+    // set — load the mock through the CommonJS loader instead.
+    const moduleApi = Module;
+    const originalLoad = moduleApi._load;
+    moduleApi._load = (request, parent, isMain) => {
+        if (isMain && request === originalEntry) {
+            moduleApi._load = originalLoad;
+            loadTsxCommonJs(entry);
+            return originalLoad(entry, null, true);
+        }
+        return originalLoad(request, parent, isMain);
+    };
+};
+// A spawn with no CLI arguments leaves node without an entry (the REPL
+// would start), so the mock module is imported directly instead.
+const runEntryDirectly = async (entry) => {
+    process.argv.length = 1;
+    process.argv.push(entry, ...cliArgs);
+    await import(pathToFileURL(entry).href);
+    process.exit(process.exitCode);
+};
+const intercept = async () => {
+    if (invokedName === HELPER_NAME)
+        return runOriginalCommand(mocks.runOriginal);
+    const target = mocks.targets?.[invokedName];
+    if (target === undefined)
+        return;
+    // A process whose CLI entry is a real file is not a shim: mock scripts
+    // spawned through process.execPath (tsx's esbuild service, `node -e`
+    // helpers) inherit the shim exe's name, but their entry exists on disk
+    // while a shim's "subcommand" entry never does.
+    if (isFile(process.argv[1] ?? ""))
+        return;
+    const commandLine = `${invokedName} ${cliArgs.join(" ")}`;
+    const mocked = target.pattern === undefined ||
+        new RegExp(target.pattern).test(commandLine);
+    if (!mocked)
+        return runRealBinary(target);
+    if (target.kind !== "node")
+        return runInterpreterAndExit(target.interpreter ?? "bash", target.entry);
+    if (process.argv[1] === undefined)
+        return runEntryDirectly(target.entry);
+    return redirectNodeEntry(target.entry);
+};
+// Only a shim's own main thread may intercept: loaders such as tsx spawn
+// workers whose entry-point load must pass through untouched.
+if (process.env[MOCKS_VAR] !== undefined && threadId === 0)
+    await intercept();

package/dist/mock-bin-windows.d.ts

@@ -0,0 +1,10 @@
+import type { MockBinScriptFile } from "./mock-bin.js";
+/**
+ * Windows implementation of `mockBin`; see mock-bin.ts for the public
+ * overloads. Installs `<binName>.exe` (a hard link of node.exe) and the
+ * `mock-a-bin-run-original.exe` helper into a temp directory prepended
+ * to PATH, registers the mock in the preload's registry, and extends
+ * NODE_OPTIONS with the preload import.
+ */
+declare const mockBinWindows: (binName: string, pattern: string | undefined, shebangOrOutput: string, codeOrScript: string | MockBinScriptFile | undefined) => Promise<() => void>;
+export { mockBinWindows };

package/dist/mock-bin-windows.js

@@ -0,0 +1,182 @@
+import { copyFileSync, linkSync, rmSync } from "node:fs";
+import { mkdtemp, stat, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+// Windows twin of the POSIX mockBin: PATH interception needs a real
+// executable there (node refuses to spawn .cmd/.bat shims without a
+// shell, and an extensionless #! script cannot execute at all). Each
+// mock is a hard link of node.exe named <bin>.exe, and a preload
+// (mock-bin-preload) registered through NODE_OPTIONS turns a spawn of
+// that exe into the mock script — argv, stdin, stdout, stderr, and exit
+// codes all pass through. The registry the preload reads (and its env
+// var name) must stay in sync with mock-bin-preload.
+const MOCKS_VAR = "TYPE_A_BIN_MOCKS";
+const HELPER_NAME = "mock-a-bin-run-original";
+// The preload ships next to this module: mock-bin-preload.js in the
+// published dist build, mock-bin-preload.ts when running from source
+// (node's native type stripping loads the .ts form in child processes).
+const ownPath = fileURLToPath(import.meta.url);
+const preloadPath = path.join(path.dirname(ownPath), `mock-bin-preload${path.extname(ownPath)}`);
+const readMocks = () => {
+    try {
+        return JSON.parse(process.env[MOCKS_VAR] ?? "{}");
+    }
+    catch {
+        return {};
+    }
+};
+const restoreEnv = (name, previous) => {
+    if (previous === undefined)
+        delete process.env[name];
+    else
+        process.env[name] = previous;
+};
+/** Hard links node.exe as `destination`, copying across volume boundaries. */
+const linkNodeExecutable = (destination) => {
+    try {
+        linkSync(process.execPath, destination);
+    }
+    catch {
+        // Different volume than the node install: fall back to a real copy.
+        copyFileSync(process.execPath, destination);
+    }
+};
+/**
+ * Splits an interpreter string into words, accepting both a bare name
+ * ("bash"), a full shebang ("#!/usr/bin/env bash"), or an absolute
+ * shebang path ("#!/bin/bash").
+ */
+const toInterpreterWords = (shebang) => shebang
+    .replace(/^#!\s*/, "")
+    .replace(/^\/(?:usr\/)?bin\/env\s+/, "")
+    .trim()
+    .split(/\s+/)
+    .filter((word) => word !== "");
+const basenameWithoutExecutableExtension = (word) => path.basename(word).replace(/\.(?:bat|cmd|com|exe)$/iu, "");
+const isNodeInterpreter = (words) => basenameWithoutExecutableExtension(words[0] ?? "").toLowerCase() === "node";
+const interpreterExecutableName = (word) => word === undefined ? "bash" : basenameWithoutExecutableExtension(word);
+const usesTsx = (words) => words.some((word) => word === "tsx" || word.startsWith("tsx/"));
+const resolveTsxImportUrl = () => {
+    try {
+        return pathToFileURL(createRequire(import.meta.url).resolve("tsx")).href;
+    }
+    catch {
+        throw new Error("mockBin: the interpreter requires the tsx package, but tsx is not " +
+            "installed. Add tsx to your devDependencies to mock through node " +
+            "--import tsx on Windows.");
+    }
+};
+const toShebangLine = (interpreter) => interpreter.startsWith("#!") ? interpreter : `#!/usr/bin/env ${interpreter}`;
+/**
+ * Builds the CommonJS mock for the output shorthand. bash `echo` expands
+ * positional parameters, so the Node twin expands `$1`..`$9`, `$*`, and
+ * `$@` from the command line to keep the shorthand's behaviour aligned.
+ */
+const echoScript = (output) => `
+const args = process.argv.slice(2);
+const expand = (text) =>
+  text
+    .replace(/\\$[@*]/g, args.join(" "))
+    .replace(/\\$(\\d)/g, (_, digit) => args[Number(digit) - 1] ?? "");
+console.log(expand(${JSON.stringify(output)}));
+`;
+const assertScriptFile = async (file) => {
+    const stats = await stat(file).catch(() => null);
+    if (!stats?.isFile())
+        throw new Error(`mockBin: script file not found: ${file}`);
+};
+/**
+ * Windows implementation of `mockBin`; see mock-bin.ts for the public
+ * overloads. Installs `<binName>.exe` (a hard link of node.exe) and the
+ * `mock-a-bin-run-original.exe` helper into a temp directory prepended
+ * to PATH, registers the mock in the preload's registry, and extends
+ * NODE_OPTIONS with the preload import.
+ */
+const mockBinWindows = async (binName, pattern, shebangOrOutput, codeOrScript) => {
+    if (typeof codeOrScript === "object")
+        await assertScriptFile(codeOrScript.file);
+    const originalPath = process.env.PATH ?? "";
+    const previousNodeOptions = process.env.NODE_OPTIONS;
+    const previousMocks = process.env[MOCKS_VAR];
+    // A binName already carrying .exe stays a valid executable name while
+    // the registry key matches the shim's argv[0] basename.
+    const binBase = binName.replace(/\.exe$/iu, "");
+    const tempDir = await mkdtemp(path.join(tmpdir(), "mock-bin-"));
+    linkNodeExecutable(path.join(tempDir, `${binBase}.exe`));
+    linkNodeExecutable(path.join(tempDir, `${HELPER_NAME}.exe`));
+    const words = codeOrScript === undefined ? ["node"] : toInterpreterWords(shebangOrOutput);
+    const isNodeMock = codeOrScript === undefined || isNodeInterpreter(words);
+    const interpreter = isNodeMock
+        ? undefined
+        : interpreterExecutableName(words[0]);
+    let entry;
+    if (typeof codeOrScript === "object") {
+        // Script files keep their real extension, so extension-aware loaders
+        // (e.g. node --import tsx) parse them.
+        entry = path.resolve(codeOrScript.file);
+    }
+    else if (isNodeMock) {
+        // Inline code runs as CommonJS, matching the extensionless scripts
+        // the POSIX implementation writes (node parses those as CommonJS).
+        entry = path.join(tempDir, `${binBase}-mock.cjs`);
+        const code = codeOrScript ?? echoScript(shebangOrOutput);
+        await writeFile(entry, `${code}\n`);
+    }
+    else {
+        entry = path.join(tempDir, `${binBase}-mock.sh`);
+        await writeFile(entry, `${toShebangLine(shebangOrOutput)}\n${codeOrScript}\n`);
+    }
+    const target = {
+        kind: isNodeMock ? "node" : "spawn",
+        entry,
+        ...(interpreter === undefined ? {} : { interpreter }),
+        ...(pattern ? { pattern } : {}),
+        originalPath,
+    };
+    const mocks = readMocks();
+    process.env[MOCKS_VAR] = JSON.stringify({
+        ...mocks,
+        targets: { ...mocks.targets, [binBase]: target },
+        runOriginal: { binName: binBase, originalPath },
+    });
+    // The preload rides along after the tsx loader when the interpreter
+    // names it, so .ts entries resolve through tsx's ESM hooks in the
+    // same resolve chain that redirects the shim entry.
+    const imports = [
+        ...(isNodeMock && usesTsx(words)
+            ? [`--import ${resolveTsxImportUrl()}`]
+            : []),
+        `--import ${pathToFileURL(preloadPath).href}`,
+    ];
+    process.env.NODE_OPTIONS =
+        previousNodeOptions === undefined || previousNodeOptions === ""
+            ? imports.join(" ")
+            : `${imports.join(" ")} ${previousNodeOptions}`;
+    process.env.PATH = `${tempDir}${path.delimiter}${originalPath}`;
+    return () => {
+        if (originalPath === "")
+            delete process.env.PATH;
+        else
+            process.env.PATH = originalPath;
+        restoreEnv("NODE_OPTIONS", previousNodeOptions);
+        restoreEnv(MOCKS_VAR, previousMocks);
+        try {
+            // Windows can transiently deny deleting files a just-exited
+            // process still holds (the shim exes), so rmSync's retry options
+            // cover that.
+            rmSync(tempDir, {
+                recursive: true,
+                force: true,
+                maxRetries: 40,
+                retryDelay: 250,
+            });
+        }
+        catch (error) {
+            console.warn(`Warning: Failed to remove mock-bin temp directory ${tempDir}: ${String(error)}`);
+        }
+    };
+};
+export { mockBinWindows };

package/dist/mock-bin.d.ts

@@ -0,0 +1,64 @@
+type MockBinCleanup = () => void;
+interface MockBinConfig {
+    /** The name of the binary to mock (e.g., "gh", "git") */
+    binName: string;
+    /** Optional regex pattern. Only commands matching it are mocked. */
+    pattern?: string;
+}
+interface MockBinScriptFile {
+    /**
+     * Script executed when the mock runs. The file keeps its real
+     * extension, so extension-aware loaders (e.g. `node --import tsx`)
+     * parse it — embedding the source inline fails because the mock
+     * binary is written to an extensionless temp file.
+     */
+    file: string;
+}
+/**
+ * Creates a mock executable that replaces a real binary on the PATH.
+ *
+ * The mock script can call `mock-a-bin-run-original` to execute the
+ * original command, enabling conditional mocking where some subcommands
+ * are mocked while others pass through to the real binary.
+ *
+ * There are three calling conventions:
+ *
+ * 1. **Output shorthand** — pass the plain text the mock should print.
+ *    The interpreter defaults to `bash` and the output is echoed.
+ * 2. **Full script** — pass an interpreter (`shebang`) and arbitrary
+ *    script `code` to run when the mock binary is invoked.
+ * 3. **Script file** — pass an interpreter (`shebang`) and a
+ *    `{ file }` object pointing at a script on disk. The file keeps its
+ *    own extension, so extension-aware loaders work (e.g.
+ *    `node --import tsx` with a `.ts` file).
+ *
+ * @param binNameOrConfig - Binary name or a config object with `binName`
+ *   and an optional `pattern`
+ * @returns A cleanup function that restores the original PATH
+ *
+ * @example
+ * ```ts
+ * // Output shorthand
+ * const cleanup = await mockBin("gh", "mocked!!")
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Full script
+ * const cleanup = await mockBin("gh", "bash", 'echo "mocked!!"')
+ * // ... run your tests ...
+ * cleanup() // Restore original PATH
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Script file (keeps its extension, so tsx transforms it)
+ * const cleanup = await mockBin("dragon", "node --import tsx", {
+ *   file: "./src/tests/hoard-script.ts",
+ * })
+ * ```
+ */
+declare function mockBin(binNameOrConfig: string | MockBinConfig, output: string): Promise<MockBinCleanup>;
+declare function mockBin(binNameOrConfig: string | MockBinConfig, shebang: string, code: string): Promise<MockBinCleanup>;
+declare function mockBin(binNameOrConfig: string | MockBinConfig, shebang: string, script: MockBinScriptFile): Promise<MockBinCleanup>;
+export { type MockBinCleanup, type MockBinConfig, type MockBinScriptFile, mockBin, };

package/dist/mock-bin.js

@@ -0,0 +1,147 @@
+import { rmSync } from "node:fs";
+import { chmod, mkdtemp, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { mockBinWindows } from "./mock-bin-windows.js";
+/**
+ * Finds the path to a binary within the given PATH directories.
+ *
+ * @param binName - The name of the binary to find
+ * @param pathDirs - Array of directories to search in
+ * @returns The full path to the binary, or null if not found
+ */
+const findBinaryInPath = async (binName, pathDirs) => {
+    for (const dir of pathDirs) {
+        if (!dir)
+            continue;
+        const binaryPath = path.join(dir, binName);
+        try {
+            const stats = await stat(binaryPath);
+            if (stats.isFile())
+                return binaryPath;
+        }
+        catch {
+            // File doesn't exist, continue searching
+        }
+    }
+    return null;
+};
+/** Wraps a bare interpreter in a `#!/usr/bin/env …` shebang line. */
+const toShebangLine = (interpreter) => interpreter.startsWith("#!") ? interpreter : `#!/usr/bin/env ${interpreter}`;
+/**
+ * Validates the script file exists, then builds an `exec` wrapper that
+ * delegates to it through the given interpreter. The file keeps its real
+ * extension so extension-aware loaders (e.g. tsx) parse it.
+ */
+const resolveScriptFile = async (shebang, { file }) => {
+    const resolvedFile = path.resolve(file);
+    const stats = await stat(resolvedFile).catch(() => null);
+    if (!stats?.isFile()) {
+        throw new Error(`mockBin: script file not found: ${file}`);
+    }
+    // Accept either a bare interpreter ("node --import tsx") or a full
+    // shebang line ("#!/usr/bin/env node"); strip "#!" for the exec line.
+    const interpreter = shebang.startsWith("#!")
+        ? shebang.slice(2).trim()
+        : shebang;
+    return {
+        shebang: "#!/bin/sh",
+        body: `exec ${interpreter} "${resolvedFile}" "$@"`,
+    };
+};
+/**
+ * Resolves the shebang and body for inline code or the output shorthand.
+ * With no `code`, `shebangOrOutput` is echoed via bash.
+ */
+const resolveInlineCode = (shebangOrOutput, code) => {
+    const shebang = code === undefined ? "bash" : shebangOrOutput;
+    const body = code ?? `echo "${shebangOrOutput}"`;
+    return { shebang: toShebangLine(shebang), body };
+};
+async function mockBin(binNameOrConfig, shebangOrOutput, codeOrScript) {
+    const config = typeof binNameOrConfig === "string"
+        ? { binName: binNameOrConfig }
+        : binNameOrConfig;
+    const { binName, pattern } = config;
+    // Windows needs a real .exe on the PATH plus a NODE_OPTIONS preload
+    // that redirects the shim's entry to the mock script; everything else
+    // (pattern handling, cleanup contract) behaves the same.
+    if (process.platform === "win32")
+        return mockBinWindows(binName, pattern, shebangOrOutput, codeOrScript);
+    const originalPath = process.env.PATH ?? "";
+    const pathSeparator = path.delimiter;
+    const tempDir = await mkdtemp(path.join(tmpdir(), "mock-bin-"));
+    const mockScriptPath = path.join(tempDir, binName);
+    const runOriginalBinaryPath = path.join(tempDir, "mock-a-bin-run-original");
+    // Create the 'mock-a-bin-run-original' helper binary. The user's mock
+    // script can call it to delegate back to the real binary.
+    const runOriginalScript = `#!/bin/bash
+# This binary finds and executes the original command
+# It's called when the mock script decides to delegate to the real binary
+
+# Restore original PATH to find the real binary
+export PATH="${originalPath}"
+
+# Find the original binary (excluding our temp directory)
+ORIGINAL_BIN=$(command -v "${binName}" 2>/dev/null)
+
+if [ -n "$ORIGINAL_BIN" ]; then
+  # Execute the original binary with all arguments
+  exec "$ORIGINAL_BIN" "$@"
+else
+  echo "Error: Original '${binName}' command not found in PATH" >&2
+  exit 127
+fi
+`;
+    await writeFile(runOriginalBinaryPath, runOriginalScript);
+    await chmod(runOriginalBinaryPath, 0o755);
+    const { shebang, body } = typeof codeOrScript === "object"
+        ? await resolveScriptFile(shebangOrOutput, codeOrScript)
+        : resolveInlineCode(shebangOrOutput, codeOrScript);
+    // When a pattern is given, wrap the body so only matching commands
+    // are mocked; everything else is delegated to the real binary.
+    let userScriptContent;
+    if (pattern) {
+        const pathsWithoutTemp = originalPath
+            .split(pathSeparator)
+            .filter((p) => p && !p.includes("mock-bin-"));
+        const realBinaryPath = await findBinaryInPath(binName, pathsWithoutTemp);
+        userScriptContent = `${shebang}
+# Construct the full command with arguments
+FULL_COMMAND="${binName} $*"
+
+# Check if the command matches the pattern
+if echo "$FULL_COMMAND" | grep -qE '${pattern}'; then
+  # Pattern matches - execute mock code
+${body}
+else
+  # Pattern doesn't match - execute the real binary
+  ${realBinaryPath ? `exec "${realBinaryPath}" "$@"` : `echo "Error: Real binary '${binName}' not found in PATH" >&2; exit 127`}
+fi
+`;
+    }
+    else {
+        userScriptContent = `${shebang}\n${body}\n`;
+    }
+    // Write the mock script directly to the binary path so it replaces the
+    // real binary on the PATH (no wrapper indirection needed: the shebang
+    // selects the interpreter).
+    await writeFile(mockScriptPath, userScriptContent);
+    await chmod(mockScriptPath, 0o755);
+    // Prepend the temp directory to PATH so the mock takes precedence.
+    process.env.PATH = `${tempDir}${pathSeparator}${originalPath}`;
+    return () => {
+        if (originalPath)
+            process.env.PATH = originalPath;
+        else
+            delete process.env.PATH;
+        try {
+            rmSync(tempDir, { recursive: true });
+        }
+        catch (error) {
+            // Ignore cleanup errors - temp dir will be cleaned up eventually
+            console.warn(`Warning: Failed to remove mock-bin temp directory ${tempDir}: ${String(error)}`);
+        }
+    };
+}
+export { mockBin, };