fix(transpile): resolve esbuild's child node to the editor's own runtime

esbuild-wasm's Node build never runs the WASM in-process (initialize rejects wasmModule
outside the browser), and our bundler relies on esbuild's JS plugin API, so bundling a
multi-file source must spawn `node <bin/esbuild>` as a service child. That spawn is a bare
PATH lookup for "node", which fails on hosts that ship an Electron runtime rather than a
node binary (VS Code/VSCodium): spawn node ENOENT, surfaced as the transpiler's
"service is no longer running".

The built-in sslc compiler already avoids this by using child_process.fork, which launches
process.execPath. Mirror that: before initializing esbuild, make "node" resolve to the
extension host's own runtime - prepend its directory when the runtime binary is itself
named node (code-server, plain node hosts), or write a small node shim that re-execs an
Electron runtime with ELECTRON_RUN_AS_NODE=1. Applied only when no node is already
resolvable, so a host that has node is left untouched (no regression).

Verified: with node stripped from PATH, esbuild.build fails with spawn ENOENT before this
change and succeeds after; the full transpiler suite (41 tests) stays green.

Author: burner1024

docs/changelog.md

@@ -25,6 +25,10 @@
 - Fixed: dropped several phantom TP2 keywords the grammar never matched, and corrected highlighting of the real ones.
 - Fixed: the WeiDU D formatter was not idempotent when a `~string~` immediately followed a keyword.
 
+### 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.
+
 ### Performance
 
 - Fixed: on large mod workspaces the language server could use excessive memory while indexing at startup. It now skips `node_modules` and dotfile directories and limits how many files it reads at once.

transpilers/common/esbuild-utils.ts

@@ -14,16 +14,23 @@ import {
     expandEnumPropertyAccess,
     enumTransformPlugin,
 } from "./enum-transform";
+import { ensureNodeOnPath } from "./node-runtime";
 
 let esbuildInitialized = false;
 
 /**
  * Initialize esbuild (singleton, safe to call multiple times).
  * 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.
  */
 async function ensureEsbuild(): Promise<void> {
     if (esbuildInitialized) return;
+    ensureNodeOnPath();
     if (typeof esbuild.initialize === "function") {
         await esbuild.initialize({});
     }

transpilers/common/node-runtime.ts

@@ -0,0 +1,111 @@
+/**
+ * Make esbuild-wasm's child-process spawn find a Node runtime on hosts that have none.
+ *
+ * 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).
+ */
+
+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 };
+
+/**
+ * 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.
+ */
+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) };
+    }
+
+    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.
+ */
+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);
+    }
+    process.env.PATH = dir + path.delimiter + (process.env.PATH ?? "");
+}

transpilers/test/node-runtime.test.ts

@@ -0,0 +1,57 @@
+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.
+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("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("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");
+    });
+});