type-a-bin 0.1.2 → 0.1.3

package/dist/mock-bin-runtime.js

@@ -0,0 +1,293 @@
+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";
+// Shared Windows dispatch behind both entry points of a mock:
+//
+// - the trampoline launcher (native/trampoline.c) starts Node with a
+//   generated bootstrap that calls runTrampoline(), and
+// - the NODE_OPTIONS preload (mock-bin-preload) calls interceptShim()
+//   for the legacy node.exe-hardlink shims.
+//
+// This module runs inside spawned child processes — as the compiled
+// .js from the published package or as the .ts source under node's
+// native type stripping — so it must stay free of imports beyond
+// node's own modules. The registry env var name is duplicated from
+// mock-bin-env for the same reason; the two must stay in sync.
+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 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;
+// Runs a resolved command with the caller's stdio and exits with its
+// status; a failed spawn exits 127.
+const spawnAndExit = (command, args, errorPrefix) => {
+    const result = spawnSync(command, args, { stdio: "inherit" });
+    if (result.error !== undefined)
+        writeError(`${errorPrefix}: ${String(result.error)}`);
+    process.exit(result.status ?? 127);
+};
+// The real binary must not be re-intercepted by a shim preload.
+const spawnRealAndExit = (command, args) => spawnAndExit(command, args, `Error: '${command}' failed to start`);
+const runOriginalCommand = (spec, cliArgs) => {
+    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 = (invokedName, cliArgs, originalPath) => {
+    const real = findExecutable(invokedName, searchPathDirs(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, cliArgs) => {
+    const interpreterPath = resolveInterpreter(interpreter);
+    if (interpreterPath === null)
+        return fail(`Error: Interpreter '${interpreter}' not found in PATH`);
+    return spawnAndExit(interpreterPath, [entry, ...cliArgs], `Error: Interpreter '${interpreter}' failed`);
+};
+// 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.
+    }
+};
+// 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;
+};
+// Eval/print runs carry their program in execArgv, so argv[1] is
+// undefined — the shape runEntryDirectly would otherwise hijack — and a
+// helper spawned from inside a mock through the shim must run its
+// snippet untouched.
+const EVAL_FLAG = /^(?:-e|-p|--eval|--print)(?:=|$)/;
+const isEvalRun = (execArgv) => execArgv.some((arg) => EVAL_FLAG.test(arg));
+const asPath = (specifier) => specifier.startsWith("file:") ? fileURLToPath(specifier) : specifier;
+// Repositions argv to [node, entry, ...cliArgs] so the mock reads its
+// CLI arguments at process.argv.slice(2) like a real Node CLI script.
+const setArgvEntry = (entry, cliArgs) => {
+    process.argv.length = 1;
+    process.argv.push(entry, ...cliArgs);
+};
+const redirectNodeEntry = (entry, cliArgs) => {
+    // Capture the CLI entry before repositioning argv: node normalized it
+    // to an absolute path, and the redirects below must recognize it.
+    const originalEntry = process.argv[1] ?? "";
+    setArgvEntry(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 shim 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, cliArgs) => {
+    setArgvEntry(entry, cliArgs);
+    await import(pathToFileURL(entry).href);
+    // An import settles when the entry's top level finishes — before the
+    // output of a mock that defers work (timers, stdin). Node would start
+    // the REPL the moment this preload settles, so hold until the event
+    // loop drains, then exit with whatever the mock set. A mock holding
+    // the loop open on purpose (trapped signals) never drains, and so
+    // lives until it is killed.
+    await new Promise(() => process.once("beforeExit", () => process.exit(process.exitCode)));
+};
+/**
+ * Runs a node-kind mock entry as the process's main module from the
+ * trampoline bootstrap. Unlike a shim, the process already has a real
+ * main module (the bootstrap itself), so there is no REPL to avoid and
+ * no entry redirection needed. CommonJS entries load through
+ * `Module._load` with `isMain` set, so `require.main` matches a script
+ * started as `node entry.cjs`; other entries load as ESM, with tsx
+ * registered first when the target carries a loader URL.
+ */
+const runNodeEntryAsMain = async (entry, cliArgs, tsxImportUrl) => {
+    setArgvEntry(entry, cliArgs);
+    if (extname(entry).toLowerCase() === ".cjs") {
+        const moduleApi = Module;
+        moduleApi._load(entry, null, true);
+        return;
+    }
+    if (tsxImportUrl !== undefined)
+        await import(tsxImportUrl);
+    await import(pathToFileURL(entry).href);
+};
+// Dispatch shared by both entry points: a pattern miss hands the
+// invocation to the real binary, non-node targets run through their
+// interpreter, and node targets load however the entry point chooses.
+const dispatchTarget = async (target, invokedName, cliArgs, runNodeEntry) => {
+    const commandLine = `${invokedName} ${cliArgs.join(" ")}`;
+    const mocked = target.pattern === undefined ||
+        new RegExp(target.pattern).test(commandLine);
+    if (!mocked)
+        return runRealBinary(invokedName, cliArgs, target.originalPath);
+    if (target.kind !== "node")
+        return runInterpreterAndExit(target.interpreter ?? "bash", target.entry, cliArgs);
+    return runNodeEntry(target.entry, cliArgs);
+};
+// Basename without the executable extension: mock-a-bin-run-original.exe
+// and claude.exe both register under their extensionless names.
+const toInvokedName = (exePath) => basename(exePath, extname(exePath));
+/**
+ * Trampoline entry point. The native launcher starts Node as
+ * `[node, mock-bin-trampoline.cjs, <mock>.exe, ...originalArgs]`, so the
+ * invoked binary is the path in argv[2] and every argument after it is
+ * the caller's original argv — Node's option parser never sees it.
+ */
+const runTrampoline = async () => {
+    const invokedExe = process.argv[2];
+    if (invokedExe === undefined)
+        return fail("Error: type-a-bin trampoline invoked without a mock path");
+    const args = process.argv.slice(3);
+    const invokedName = toInvokedName(invokedExe);
+    const mocks = readMocks();
+    if (invokedName === HELPER_NAME)
+        return runOriginalCommand(mocks.runOriginal, args);
+    const target = mocks.targets?.[invokedName];
+    // No registry entry (e.g. a spawn through withoutMocks) must not land
+    // in a REPL or a crash: hand the invocation to the real binary.
+    if (target === undefined)
+        return runRealBinary(invokedName, args, undefined);
+    return dispatchTarget(target, invokedName, args, (entry, cliArgs) => runNodeEntryAsMain(entry, cliArgs, target.tsxImportUrl));
+};
+/**
+ * Shim entry point for the NODE_OPTIONS preload: the process itself is
+ * a hard link of node.exe named after the mocked binary, so the main
+ * entry is redirected in-process once the registry recognizes the
+ * invocation. Kept as the fallback behind the trampoline rollout.
+ */
+const interceptShim = async () => {
+    const invokedName = toInvokedName(process.argv[0] ?? "");
+    // 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)];
+    if (isEvalRun(process.execArgv))
+        return;
+    const mocks = readMocks();
+    if (invokedName === HELPER_NAME)
+        return runOriginalCommand(mocks.runOriginal, cliArgs);
+    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;
+    return dispatchTarget(target, invokedName, cliArgs, process.argv[1] === undefined ? runEntryDirectly : redirectNodeEntry);
+};
+export { interceptShim, runTrampoline, };

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

@@ -0,0 +1,4 @@
+declare const isTypeScriptFile: (file: string) => boolean;
+/** Absolute file URL of the tsx loader, or null when tsx is not installed. */
+declare const resolveTsxImportUrl: (scriptFile?: string) => string | null;
+export { isTypeScriptFile, resolveTsxImportUrl };

package/dist/mock-bin-tsx.js

@@ -0,0 +1,30 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+// A mock run through `node --import tsx` only resolves the bare `tsx`
+// specifier while its working directory sits inside the package that
+// installed tsx; a mock spawned from a temp directory loses it. The
+// loader is therefore resolved to an absolute file URL up front — the
+// POSIX mock embeds it in its exec line, the Windows shim carries it in
+// NODE_OPTIONS — from the script's own package first (workspace-local
+// installs included) and type-a-bin's own tree second (scripts written
+// to a temp directory). When neither resolves, null comes back and
+// node's native type stripping parses the script instead.
+const TS_EXTENSIONS = [".cts", ".mts", ".ts", ".tsx"];
+const isTypeScriptFile = (file) => TS_EXTENSIONS.includes(path.extname(file).toLowerCase());
+/** Absolute file URL of the tsx loader, or null when tsx is not installed. */
+const resolveTsxImportUrl = (scriptFile) => {
+    const bases = [
+        ...(scriptFile === undefined ? [] : [path.resolve(scriptFile)]),
+        import.meta.url,
+    ];
+    for (const base of bases)
+        try {
+            return pathToFileURL(createRequire(base).resolve("tsx")).href;
+        }
+        catch {
+            // tsx is not resolvable from this base — try the next one.
+        }
+    return null;
+};
+export { isTypeScriptFile, resolveTsxImportUrl };

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

@@ -1,10 +1,12 @@
 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.
+ * overloads. By default it installs copies of the trampoline launcher
+ * as `<binName>.exe` and the `mock-a-bin-run-original.exe` helper plus
+ * a generated bootstrap into a temp directory prepended to PATH, and
+ * registers the mock in the dispatch registry. Setting
+ * TYPE_A_BIN_DISABLE_TRAMPOLINE=1 (or a missing launcher) falls back to
+ * the legacy node.exe hard links with the NODE_OPTIONS preload.
  */
 declare const mockBinWindows: (binName: string, pattern: string | undefined, shebangOrOutput: string, codeOrScript: string | MockBinScriptFile | undefined) => Promise<() => void>;
 export { mockBinWindows };

package/dist/mock-bin-windows.js

@@ -1,25 +1,73 @@
-import { copyFileSync, linkSync, rmSync } from "node:fs";
+import { copyFileSync, existsSync, linkSync } 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";
+import { MOCKS_VAR } from "./mock-bin-env.js";
+import { resolveTsxImportUrl } from "./mock-bin-tsx.js";
+import { rmScratch } from "./rm-scratch.js";
 // 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";
+// mock is a copy of a tiny native trampoline (native/trampoline.c)
+// named <bin>.exe. The trampoline launches Node with a generated
+// bootstrap as the script and the invoked mock plus the original argv
+// as plain arguments — so leading flags, quotes, and line breaks reach
+// the mock verbatim instead of being parsed by Node's own CLI parser
+// (the limitation of the previous node.exe-hardlink mechanism). The
+// bootstrap dispatches through mock-bin-runtime; argv, stdin, stdout,
+// stderr, and exit codes all pass through. The registry travels in the
+// env var named by MOCKS_VAR; mock-bin-runtime keeps its own copy of
+// the name, so the two must stay in sync.
 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).
+// The Node executable to launch, recorded when the mock is installed
+// and read by the native trampoline (which also owns its name).
+const NODE_EXE_VAR = "TYPE_A_BIN_NODE_EXE";
+// Temporary escape hatch: set to "1" to force the legacy node.exe
+// hard-link shims plus the NODE_OPTIONS preload while the trampoline
+// rollout is validated. Removed once both Windows architectures are
+// covered.
+const DISABLE_TRAMPOLINE_VAR = "TYPE_A_BIN_DISABLE_TRAMPOLINE";
+const TRAMPOLINE_NAME = "type-a-bin-trampoline.exe";
+const BOOTSTRAP_NAME = "mock-bin-trampoline.cjs";
+// The dispatch module ships next to this one: mock-bin-runtime.js in
+// the published dist build, mock-bin-runtime.ts when running from
+// source (node's native type stripping loads the .ts form in child
+// processes).
 const ownPath = fileURLToPath(import.meta.url);
+const runtimeUrl = pathToFileURL(path.join(path.dirname(ownPath), `mock-bin-runtime${path.extname(ownPath)}`)).href;
+// The preload ships the same way and remains the fallback mechanism.
 const preloadPath = path.join(path.dirname(ownPath), `mock-bin-preload${path.extname(ownPath)}`);
+/**
+ * Locates the checked-in trampoline launcher for this platform: the
+ * copy under `dist/native` in the published package first, the source
+ * checkout's `native/bin` second (tests running before a build). Both
+ * supported Windows architectures ship prebuilt; anything else falls
+ * back to the legacy shims.
+ */
+const trampolineSourcePath = () => {
+    if (process.platform !== "win32")
+        return null;
+    if (process.arch !== "x64" && process.arch !== "arm64")
+        return null;
+    const ownDir = path.dirname(ownPath);
+    const candidates = [
+        path.join(ownDir, "native", "win32", process.arch, TRAMPOLINE_NAME),
+        path.join(path.dirname(ownDir), "native", "bin", "win32", process.arch, TRAMPOLINE_NAME),
+    ];
+    return candidates.find((candidate) => existsSync(candidate)) ?? null;
+};
+/**
+ * The bootstrap the native trampoline runs: Node's main module, whose
+ * only job is handing the invoked mock and the original argv to the
+ * shared dispatch in mock-bin-runtime.
+ */
+const bootstrapCode = (url) => `// Generated by type-a-bin: the Windows trampoline launcher starts\n` +
+    `// Node with this script, passing the invoked mock and the original\n` +
+    `// argv as plain arguments.\n` +
+    `import(${JSON.stringify(url)}).then((runtime) =>\n` +
+    `  runtime.runTrampoline(),\n);\n`;
 const readMocks = () => {
     try {
         return JSON.parse(process.env[MOCKS_VAR] ?? "{}");
@@ -58,15 +106,19 @@ const toInterpreterWords = (shebang) => shebang
 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 = () => {
+// A `--import` word names tsx when it is the bare package ("tsx",
+// "tsx/cjs") or a file URL resolving into it — the script-file
+// shorthand embeds an absolute loader URL.
+const isTsxImport = (word) => {
+    if (word === "tsx" || word.startsWith("tsx/"))
+        return true;
+    if (!word.startsWith("file:"))
+        return false;
     try {
-        return pathToFileURL(createRequire(import.meta.url).resolve("tsx")).href;
+        return fileURLToPath(word).split(/[\\/]/).includes("tsx");
     }
     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.");
+        return false;
     }
 };
 const toShebangLine = (interpreter) => interpreter.startsWith("#!") ? interpreter : `#!/usr/bin/env ${interpreter}`;
@@ -88,12 +140,48 @@ const assertScriptFile = async (file) => {
     if (!stats?.isFile())
         throw new Error(`mockBin: script file not found: ${file}`);
 };
+/** Copies the trampoline launcher into the mock directory. */
+const installTrampoline = async (tempDir, binBase, source) => {
+    copyFileSync(source, path.join(tempDir, `${binBase}.exe`));
+    copyFileSync(source, path.join(tempDir, `${HELPER_NAME}.exe`));
+    await writeFile(path.join(tempDir, BOOTSTRAP_NAME), bootstrapCode(runtimeUrl));
+};
+/**
+ * Writes the mock's entry script into the mock directory and returns
+ * its path. Script files keep their real extension so extension-aware
+ * loaders (e.g. node --import tsx) parse them; inline node code runs as
+ * CommonJS, matching the extensionless scripts the POSIX implementation
+ * writes; other interpreters get a shebang script.
+ */
+const writeMockEntry = async (tempDir, binBase, shebangOrOutput, codeOrScript, isNodeMock) => {
+    if (typeof codeOrScript === "object")
+        return path.resolve(codeOrScript.file);
+    if (isNodeMock) {
+        const entry = path.join(tempDir, `${binBase}-mock.cjs`);
+        const code = codeOrScript ?? echoScript(shebangOrOutput);
+        await writeFile(entry, `${code}\n`);
+        return entry;
+    }
+    const entry = path.join(tempDir, `${binBase}-mock.sh`);
+    await writeFile(entry, `${toShebangLine(shebangOrOutput)}\n${codeOrScript}\n`);
+    return entry;
+};
+// Prepends --import flags ahead of a previous NODE_OPTIONS value so
+// the preload chain runs first in spawned processes.
+const importsAheadOf = (imports, previous) => {
+    const prepended = imports.join(" ");
+    return previous === undefined || previous === ""
+        ? prepended
+        : `${prepended} ${previous}`;
+};
 /**
  * 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.
+ * overloads. By default it installs copies of the trampoline launcher
+ * as `<binName>.exe` and the `mock-a-bin-run-original.exe` helper plus
+ * a generated bootstrap into a temp directory prepended to PATH, and
+ * registers the mock in the dispatch registry. Setting
+ * TYPE_A_BIN_DISABLE_TRAMPOLINE=1 (or a missing launcher) falls back to
+ * the legacy node.exe hard links with the NODE_OPTIONS preload.
  */
 const mockBinWindows = async (binName, pattern, shebangOrOutput, codeOrScript) => {
     if (typeof codeOrScript === "object")
@@ -101,39 +189,39 @@ const mockBinWindows = async (binName, pattern, shebangOrOutput, codeOrScript) =
     const originalPath = process.env.PATH ?? "";
     const previousNodeOptions = process.env.NODE_OPTIONS;
     const previousMocks = process.env[MOCKS_VAR];
+    const previousNodeExe = process.env[NODE_EXE_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 trampolineSource = process.env[DISABLE_TRAMPOLINE_VAR] === "1" ? null : trampolineSourcePath();
+    // The null case falls back to the legacy node.exe hard links.
+    if (trampolineSource !== null)
+        await installTrampoline(tempDir, binBase, trampolineSource);
+    else {
+        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 entry = await writeMockEntry(tempDir, binBase, shebangOrOutput, codeOrScript, isNodeMock);
+    // The tsx loader is resolved to an absolute file URL up front: the
+    // trampoline bootstrap imports it before a .ts entry, and the legacy
+    // NODE_OPTIONS chain carries it ahead of the preload. Without tsx,
+    // node's native type stripping applies.
+    const scriptFile = typeof codeOrScript === "object" ? codeOrScript.file : undefined;
+    const tsxImportUrl = isNodeMock && words.some(isTsxImport)
+        ? resolveTsxImportUrl(scriptFile)
+        : null;
     const target = {
         kind: isNodeMock ? "node" : "spawn",
         entry,
         ...(interpreter === undefined ? {} : { interpreter }),
         ...(pattern ? { pattern } : {}),
+        ...(tsxImportUrl === null ? {} : { tsxImportUrl }),
         originalPath,
     };
     const mocks = readMocks();
@@ -142,19 +230,13 @@ const mockBinWindows = async (binName, pattern, shebangOrOutput, codeOrScript) =
         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}`;
+    if (trampolineSource !== null)
+        process.env[NODE_EXE_VAR] = process.execPath;
+    else
+        process.env.NODE_OPTIONS = importsAheadOf([
+            ...(tsxImportUrl === null ? [] : [`--import ${tsxImportUrl}`]),
+            `--import ${pathToFileURL(preloadPath).href}`,
+        ], previousNodeOptions);
     process.env.PATH = `${tempDir}${path.delimiter}${originalPath}`;
     return () => {
         if (originalPath === "")
@@ -163,20 +245,8 @@ const mockBinWindows = async (binName, pattern, shebangOrOutput, codeOrScript) =
             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)}`);
-        }
+        restoreEnv(NODE_EXE_VAR, previousNodeExe);
+        rmScratch(tempDir);
     };
 };
 export { mockBinWindows };