type-a-bin 0.1.2 → 0.1.3

package/dist/mock-bin.d.ts

@@ -1,3 +1,4 @@
+import type { MockBinBehaviour, MockBinHandle } from "./mock-bin-behaviour.js";
 type MockBinCleanup = () => void;
 interface MockBinConfig {
     /** The name of the binary to mock (e.g., "gh", "git") */
@@ -21,16 +22,25 @@ interface MockBinScriptFile {
  * original command, enabling conditional mocking where some subcommands
  * are mocked while others pass through to the real binary.
  *
- * There are three calling conventions:
+ * There are five 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
+ * 3. **Script-file shorthand** — pass only a `{ file }` object and the
+ *    interpreter is picked from the file's extension: TypeScript runs
+ *    through the tsx loader (resolved to an absolute URL so the mock
+ *    works from any working directory), `.js` through node, and `.sh`
+ *    through bash.
+ * 4. **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).
+ * 5. **Scripted behaviour** — pass a `MockBinBehaviour` object instead
+ *    of a script. The mock records every invocation on the returned
+ *    handle's `calls`, and the object scripts the output, exit code and
+ *    timing without writing a script at all.
  *
  * @param binNameOrConfig - Binary name or a config object with `binName`
  *   and an optional `pattern`
@@ -52,13 +62,31 @@ interface MockBinScriptFile {
  *
  * @example
  * ```ts
- * // Script file (keeps its extension, so tsx transforms it)
+ * // Script-file shorthand (the extension picks the interpreter)
+ * const cleanup = await mockBin("dragon", {
+ *   file: "./src/tests/hoard-script.ts", // → node --import <absolute tsx>
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Script file with an explicit interpreter (keeps its extension)
  * const cleanup = await mockBin("dragon", "node --import tsx", {
  *   file: "./src/tests/hoard-script.ts",
  * })
  * ```
+ *
+ * @example
+ * ```ts
+ * // Scripted behaviour, with the invocations recorded
+ * const mock = await mockBin("gh", { stdout: ["#1", "#2"], exitCode: 1 })
+ * expect(mock.calls[0]?.args).toEqual(["pr", "list"])
+ * mock() // The handle is the cleanup function
+ * ```
  */
 declare function mockBin(binNameOrConfig: string | MockBinConfig, output: string): Promise<MockBinCleanup>;
+declare function mockBin(binNameOrConfig: string | MockBinConfig, script: MockBinScriptFile): Promise<MockBinCleanup>;
+declare function mockBin(binNameOrConfig: string | MockBinConfig, behaviour: MockBinBehaviour): Promise<MockBinHandle>;
 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

@@ -1,8 +1,10 @@
-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 { prepareBehaviour, withCalls } from "./mock-bin-behaviour.js";
+import { isTypeScriptFile, resolveTsxImportUrl } from "./mock-bin-tsx.js";
 import { mockBinWindows } from "./mock-bin-windows.js";
+import { rmScratch } from "./rm-scratch.js";
 /**
  * Finds the path to a binary within the given PATH directories.
  *
@@ -28,16 +30,20 @@ const findBinaryInPath = async (binName, pathDirs) => {
 };
 /** Wraps a bare interpreter in a `#!/usr/bin/env …` shebang line. */
 const toShebangLine = (interpreter) => interpreter.startsWith("#!") ? interpreter : `#!/usr/bin/env ${interpreter}`;
+const resolveExistingFile = async (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}`);
+    return resolvedFile;
+};
 /**
  * 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}`);
+    const resolvedFile = await resolveExistingFile(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("#!")
@@ -48,6 +54,33 @@ const resolveScriptFile = async (shebang, { file }) => {
         body: `exec ${interpreter} "${resolvedFile}" "$@"`,
     };
 };
+/** Discriminates the script-file shorthand from a behaviour object. */
+const isScriptFile = (value) => typeof value === "object" &&
+    "file" in value &&
+    typeof value.file === "string";
+/**
+ * Picks the interpreter for the script-file shorthand from the file's
+ * extension: TypeScript runs through the tsx loader resolved to an
+ * absolute file URL — so the mock works from any working directory —
+ * `.js` through node, `.sh` through bash. Anything else must name its
+ * interpreter explicitly.
+ */
+const scriptFileInterpreter = async (script) => {
+    const resolvedFile = await resolveExistingFile(script.file);
+    if (isTypeScriptFile(resolvedFile)) {
+        const tsxImportUrl = resolveTsxImportUrl(resolvedFile);
+        // Without tsx, node's native type stripping still parses erasable
+        // TypeScript.
+        return tsxImportUrl === null ? "node" : `node --import ${tsxImportUrl}`;
+    }
+    const extension = path.extname(resolvedFile).toLowerCase();
+    if ([".cjs", ".js", ".mjs"].includes(extension))
+        return "node";
+    if (extension === ".sh")
+        return "bash";
+    throw new Error(`mockBin: no interpreter known for '${extension || "no extension"}' script files; pass one explicitly, e.g. ` +
+        `mockBin(bin, "node", { file })`);
+};
 /**
  * Resolves the shebang and body for inline code or the output shorthand.
  * With no `code`, `shebangOrOutput` is echoed via bash.
@@ -62,6 +95,17 @@ async function mockBin(binNameOrConfig, shebangOrOutput, codeOrScript) {
         ? { binName: binNameOrConfig }
         : binNameOrConfig;
     const { binName, pattern } = config;
+    // Script-file shorthand: pick the interpreter, then take the explicit
+    // interpreter + script-file path.
+    if (isScriptFile(shebangOrOutput))
+        return mockBin(config, await scriptFileInterpreter(shebangOrOutput), shebangOrOutput);
+    // A scripted behaviour compiles to a node mock that carries its own
+    // pattern check, so it installs through the ordinary inline-code path
+    // on both platforms and only the call recorder is layered on top.
+    if (typeof shebangOrOutput === "object") {
+        const { code, recordDir } = await prepareBehaviour(binName, pattern, shebangOrOutput);
+        return withCalls(await mockBin(binName, "node", code), recordDir);
+    }
     // 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.
@@ -134,13 +178,7 @@ fi
             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)}`);
-        }
+        rmScratch(tempDir);
     };
 }
 export { mockBin, };

package/dist/rm-scratch.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Removes a scratch directory tree without ever throwing. Deletion is
+ * retried because Windows — and busy filesystems generally — can
+ * transiently deny removing files a just-exited process still holds;
+ * a removal that still fails warns, since an unclean temp directory
+ * beats failing a suite that passed.
+ *
+ * @param dir - Directory to remove; missing paths are fine (`force`)
+ */
+declare const rmScratch: (dir: string) => void;
+export { rmScratch };

package/dist/rm-scratch.js

@@ -0,0 +1,25 @@
+import { rmSync } from "node:fs";
+const RM_OPTIONS = {
+    recursive: true,
+    force: true,
+    maxRetries: 40,
+    retryDelay: 250,
+};
+/**
+ * Removes a scratch directory tree without ever throwing. Deletion is
+ * retried because Windows — and busy filesystems generally — can
+ * transiently deny removing files a just-exited process still holds;
+ * a removal that still fails warns, since an unclean temp directory
+ * beats failing a suite that passed.
+ *
+ * @param dir - Directory to remove; missing paths are fine (`force`)
+ */
+const rmScratch = (dir) => {
+    try {
+        rmSync(dir, RM_OPTIONS);
+    }
+    catch (err) {
+        console.error(`warning: could not remove ${dir}: ${String(err)}`);
+    }
+};
+export { rmScratch };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "type-a-bin",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Mock any executable binary for testing in Node.js",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,7 @@
     "node": "==26"
   },
   "scripts": {
-    "build:lib": "del-cli dist && tsc && del-cli dist/tests",
+    "build:lib": "del-cli dist && tsc && del-cli dist/tests && node scripts/copy-native.mjs",
     "build": "pnpm build:lib && pnpm -r build",
     "format": "ts-canon format",
     "lint": "ts-canon lint",