fix(transpile): always run esbuild's child on the editor's own runtime

esbuild-wasm spawns `node <bin/esbuild>` via a bare PATH lookup, so an absent or
present-but-broken `node` (a stale nvm/mise shim - the reported case) kills its
initialize-once service for the session. Point `node` at process.execPath before esbuild
spawns, unconditionally (a broken shim defeats an "only when missing" guard), mirroring
child_process.fork. Verified: with a broken `node` on PATH esbuild dies before and works after;
transpiler suite green.

Author: burner1024

docs/changelog.md

@@ -27,7 +27,7 @@
 
 ### Transpilers
 
-- Fixed: transpiling a multi-file TSSL/TBAF/TD source (one that uses `import`) needed a separate Node.js install on the system `PATH` and failed on editors that ship their own runtime instead of a `node` binary. The bundler now falls back to the editor's own runtime, the same way the built-in SSL compiler already does.
+- Fixed: transpiling a multi-file TSSL/TBAF/TD source (one that uses `import`) relied on the system `PATH` `node`, so it broke on editors that ship their own runtime instead of a `node` binary AND in environments with a broken `node` shim (stale nvm/mise/asdf). The bundler now always uses the editor's own runtime, the same way the built-in SSL compiler does, so a missing or broken `PATH` `node` no longer affects it.
 
 ### Performance
 

transpilers/common/esbuild-utils.ts

@@ -23,10 +23,9 @@ let esbuildInitialized = false;
  * Native esbuild (used by CLI via alias) doesn't need initialize().
  * esbuild-wasm (used by LSP server) requires it.
  *
- * esbuild-wasm's Node build spawns `node <bin/esbuild>` via a PATH lookup, which fails on a
- * host with no `node` on PATH (VS Code/VSCodium ship an Electron runtime, not `node`). Point
- * `node` at the extension host's own runtime first, the way the sslc compiler's fork does -
- * see node-runtime.ts. A no-op when a real `node` is already resolvable.
+ * esbuild-wasm spawns `node <bin/esbuild>` via a bare PATH lookup; ensureNodeOnPath points `node`
+ * at the extension host's own runtime first (see node-runtime.ts), so an absent or broken PATH
+ * `node` can't break bundling.
  */
 async function ensureEsbuild(): Promise<void> {
     if (esbuildInitialized) return;

transpilers/common/node-runtime.ts

@@ -1,117 +1,59 @@
 /**
- * Make esbuild-wasm's child-process spawn find a Node runtime on hosts that have none.
+ * Force esbuild-wasm's child spawn to use the extension host's own Node runtime.
  *
- * esbuild-wasm's Node build never runs the WASM in-process - `initialize` rejects the
- * `wasmModule` option outside the browser - so every bundle spawns `node <bin/esbuild>`
- * via a bare PATH lookup (esbuild-wasm lib/main.js). VS Code and VSCodium ship an Electron
- * runtime, not a `node` binary on PATH, so a user without a system Node install hits
- * `spawn node ENOENT` and the bundler dies. The built-in sslc compiler avoids this by using
- * child_process.fork, which launches process.execPath (the extension host's own runtime)
- * rather than resolving "node". We cannot change esbuild's spawn, but we can make "node"
- * resolve to process.execPath by pointing PATH at it - applied ONLY when "node" is not
- * already resolvable, so a host that already has Node is left untouched (zero regression).
- *
- * Extension-wide invariant (this module is its documented home): every child Node process
- * launches via process.execPath - the runtime already executing our code - never a bare
- * "node" PATH lookup the host may not satisfy. sslc gets this from child_process.fork's
- * default (server/src/sslc/ssl_compiler.ts); esbuild's dep-internal spawn gets it from
- * ensureNodeOnPath below.
+ * esbuild-wasm's Node build can't run the WASM in-process, so it spawns `node <bin/esbuild>` via a
+ * bare PATH lookup. That trusts whatever "node" PATH resolves to - which may be absent (an editor
+ * ships its own runtime) or a broken shim (stale nvm/mise), and either way the child dies and
+ * permanently kills esbuild's initialize-once service. We point "node" at process.execPath before
+ * esbuild spawns - unconditionally, since a present-but-broken shim defeats an "only when missing"
+ * guard. Mirrors child_process.fork's default and is the home of that invariant; sslc relies on
+ * fork directly (server/src/sslc/ssl_compiler.ts).
  */
 
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 
-/** A decision about how to make `node` resolve; pure, so it is unit-testable. */
-export type NodeShimPlan =
-    | { readonly kind: "none" }
-    | { readonly kind: "prepend-dir"; readonly dir: string }
-    | { readonly kind: "shim"; readonly filename: string; readonly contents: string; readonly mode: number };
+/** A `node` shim to write into an isolated dir that is then prepended to PATH. Pure, so testable. */
+export interface NodeShim {
+    readonly filename: string;
+    readonly contents: string;
+    readonly mode: number;
+}
 
 /**
- * Decide how to expose `node` for esbuild's child spawn given the host runtime.
- *
- * - Node already on PATH -> nothing to do.
- * - The runtime binary is itself named `node`/`node.exe` (code-server, plain Node hosts)
- *   -> prepend its directory to PATH; no file needs writing.
- * - Otherwise it is an Electron runtime (VS Code/VSCodium desktop) -> write a tiny `node`
- *   shim that re-execs it with ELECTRON_RUN_AS_NODE=1 so it behaves as plain Node.
+ * Build a `node` shim that re-execs process.execPath. `ELECTRON_RUN_AS_NODE=1` makes an Electron
+ * editor binary behave as Node; a real `node` execPath ignores it, so one shape serves both.
  */
-export function planNodeShim(input: {
-    readonly hasNode: boolean;
-    readonly execPath: string;
-    readonly platform: NodeJS.Platform;
-}): NodeShimPlan {
-    if (input.hasNode) return { kind: "none" };
-
-    // Parse execPath with the target platform's path rules, not the host's - this function
-    // is pure and unit-tested cross-platform, so a Windows path must split on backslashes
-    // even when the test runs on Linux.
-    const p = input.platform === "win32" ? path.win32 : path.posix;
-    const base = p.basename(input.execPath).toLowerCase();
-    if (base === "node" || base === "node.exe") {
-        return { kind: "prepend-dir", dir: p.dirname(input.execPath) };
-    }
-
+export function planNodeShim(input: { readonly execPath: string; readonly platform: NodeJS.Platform }): NodeShim {
     if (input.platform === "win32") {
         return {
-            kind: "shim",
             filename: "node.cmd",
             contents: `@echo off\r\nset ELECTRON_RUN_AS_NODE=1\r\n"${input.execPath}" %*\r\n`,
             mode: 0o755,
         };
     }
     return {
-        kind: "shim",
         filename: "node",
         contents: `#!/bin/sh\nELECTRON_RUN_AS_NODE=1 exec "${input.execPath}" "$@"\n`,
         mode: 0o755,
     };
 }
 
-/** True when a `node` executable is resolvable on the current PATH. */
-function nodeResolvesOnPath(): boolean {
-    const names = process.platform === "win32" ? ["node.exe", "node.cmd", "node.bat"] : ["node"];
-    for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
-        if (!dir) continue;
-        for (const name of names) {
-            try {
-                fs.accessSync(path.join(dir, name), fs.constants.X_OK);
-                return true;
-            } catch {
-                // not here; keep looking
-            }
-        }
-    }
-    return false;
-}
-
 let nodePathEnsured = false;
 
 /**
- * Idempotently make `node` resolvable for esbuild's child spawn (see module header).
- * Safe to call repeatedly; a no-op once done or when the host already has Node.
+ * Idempotently prepend an isolated `node` -> process.execPath shim to PATH so esbuild's child uses
+ * our runtime, never PATH's `node`. Isolated dir so it shadows only `node`. No-op after the first call.
  */
 export function ensureNodeOnPath(): void {
     if (nodePathEnsured) return;
     nodePathEnsured = true;
 
-    const plan = planNodeShim({
-        hasNode: nodeResolvesOnPath(),
-        execPath: process.execPath,
-        platform: process.platform,
-    });
-
-    if (plan.kind === "none") return;
-
-    let dir: string;
-    if (plan.kind === "prepend-dir") {
-        dir = plan.dir;
-    } else {
-        dir = fs.mkdtempSync(path.join(os.tmpdir(), "bgforge-node-"));
-        const shim = path.join(dir, plan.filename);
-        fs.writeFileSync(shim, plan.contents);
-        fs.chmodSync(shim, plan.mode);
-    }
+    const shim = planNodeShim({ execPath: process.execPath, platform: process.platform });
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bgforge-node-"));
+    const shimPath = path.join(dir, shim.filename);
+    fs.writeFileSync(shimPath, shim.contents);
+    fs.chmodSync(shimPath, shim.mode);
     process.env.PATH = dir + path.delimiter + (process.env.PATH ?? "");
 }

transpilers/test/node-runtime.test.ts

@@ -1,57 +1,30 @@
 import { describe, expect, test } from "vitest";
 import { planNodeShim } from "../common/node-runtime";
 
-// esbuild-wasm's Node build spawns `node <bin/esbuild>` via a bare PATH lookup. planNodeShim
-// decides how to make "node" resolve to the host's actual runtime (process.execPath) when the
-// host has no `node` on PATH - mirroring what child_process.fork does for the sslc compiler.
+// esbuild-wasm's Node build spawns `node <bin/esbuild>` via a bare PATH lookup. planNodeShim builds
+// a `node` shim that re-execs process.execPath, so esbuild uses the extension host's own runtime
+// unconditionally - immune to a PATH `node` that is absent OR present-but-broken (a stale shim).
 describe("planNodeShim", () => {
-    test("no-op when node already resolves on PATH", () => {
-        const plan = planNodeShim({ hasNode: true, execPath: "/usr/bin/node", platform: "linux" });
-        expect(plan).toEqual({ kind: "none" });
+    test("Unix: a `node` shim that re-execs execPath in Node mode", () => {
+        const shim = planNodeShim({ execPath: "/opt/vscodium/codium", platform: "linux" });
+        expect(shim.filename).toBe("node");
+        expect(shim.mode).toBe(0o755);
+        expect(shim.contents).toContain("#!/bin/sh");
+        // ELECTRON_RUN_AS_NODE makes an Electron execPath behave as node; a real node ignores it.
+        expect(shim.contents).toContain("ELECTRON_RUN_AS_NODE=1");
+        expect(shim.contents).toContain('exec "/opt/vscodium/codium" "$@"');
     });
 
-    test("prepends the runtime dir when the runtime binary is itself named node (code-server, plain node)", () => {
-        const plan = planNodeShim({
-            hasNode: false,
-            execPath: "/opt/code-server/lib/node",
-            platform: "linux",
-        });
-        expect(plan).toEqual({ kind: "prepend-dir", dir: "/opt/code-server/lib" });
+    test("Unix: the same shim shape serves a plain-node execPath (code-server)", () => {
+        const shim = planNodeShim({ execPath: "/opt/code-server/lib/node", platform: "linux" });
+        expect(shim.filename).toBe("node");
+        expect(shim.contents).toContain('exec "/opt/code-server/lib/node" "$@"');
     });
 
-    test("treats node.exe basename as a node runtime on Windows", () => {
-        const plan = planNodeShim({
-            hasNode: false,
-            execPath: "C:\\Program Files\\nodejs\\node.exe",
-            platform: "win32",
-        });
-        expect(plan).toEqual({ kind: "prepend-dir", dir: "C:\\Program Files\\nodejs" });
-    });
-
-    test("writes a node shim that re-execs an Electron runtime in node mode (Linux desktop)", () => {
-        const plan = planNodeShim({
-            hasNode: false,
-            execPath: "/opt/vscodium/codium",
-            platform: "linux",
-        });
-        expect(plan.kind).toBe("shim");
-        if (plan.kind !== "shim") return;
-        expect(plan.filename).toBe("node");
-        expect(plan.contents).toContain("ELECTRON_RUN_AS_NODE=1");
-        expect(plan.contents).toContain('exec "/opt/vscodium/codium"');
-        expect(plan.mode).toBe(0o755);
-    });
-
-    test("writes a node.cmd shim for an Electron runtime on Windows", () => {
-        const plan = planNodeShim({
-            hasNode: false,
-            execPath: "C:\\Program Files\\VSCodium\\VSCodium.exe",
-            platform: "win32",
-        });
-        expect(plan.kind).toBe("shim");
-        if (plan.kind !== "shim") return;
-        expect(plan.filename).toBe("node.cmd");
-        expect(plan.contents).toContain("ELECTRON_RUN_AS_NODE=1");
-        expect(plan.contents).toContain("VSCodium.exe");
+    test("Windows: a node.cmd shim that re-execs execPath in Node mode", () => {
+        const shim = planNodeShim({ execPath: "C:\\Program Files\\VSCodium\\VSCodium.exe", platform: "win32" });
+        expect(shim.filename).toBe("node.cmd");
+        expect(shim.contents).toContain("set ELECTRON_RUN_AS_NODE=1");
+        expect(shim.contents).toContain('"C:\\Program Files\\VSCodium\\VSCodium.exe" %*');
     });
 });