feat: [US-008] - [Fix bridge bootstrap so NodeRuntime works outside vitest]

Author: NathanFlurry

packages/core/isolate-runtime/src/inject/require-setup.ts

@@ -323,7 +323,9 @@
         }
 
         if (name === 'crypto') {
-          var _runtimeRequire = typeof require === 'function' ? require : globalThis.require;
+          // Avoid bare `require` here so built dist bundles don't rewrite it to
+          // an ESM helper that throws before the sandbox installs globalThis.require.
+          var _runtimeRequire = globalThis.require;
           var _streamModule = _runtimeRequire && _runtimeRequire('stream');
           var _utilModule = _runtimeRequire && _runtimeRequire('util');
           var _Transform = _streamModule && _streamModule.Transform;

packages/core/src/generated/isolate-runtime.ts

@@ -47,6 +47,8 @@ import {
 	HOST_BRIDGE_GLOBAL_KEYS,
 } from "./bridge-contract.js";
 import {
+	AF_INET,
+	SOCK_STREAM,
 	mkdir,
 	FDTableManager,
 	O_RDONLY,
@@ -1881,9 +1883,6 @@ function buildKernelSocketBridgeHandlers(
 	socketTable: import("@secure-exec/core").SocketTable,
 	pid: number,
 ): NetSocketBridgeResult {
-	const {
-		AF_INET, SOCK_STREAM,
-	} = require("@secure-exec/core") as typeof import("@secure-exec/core");
 	const handlers: BridgeHandlers = {};
 	const K = HOST_BRIDGE_GLOBAL_KEYS;
 
@@ -3365,10 +3364,6 @@ export function buildNetworkBridgeHandlers(deps: NetworkBridgeDeps): NetworkBrid
 
 		return (async () => {
 			try {
-				const {
-					AF_INET, SOCK_STREAM,
-				} = require("@secure-exec/core") as typeof import("@secure-exec/core");
-
 				const host = normalizeLoopbackHostname(options.hostname);
 				debugHttpBridge("listen start", options.serverId, host, options.port ?? 0);
 				const listenSocketId = socketTable.create(AF_INET, SOCK_STREAM, 0, pid);

packages/nodejs/src/bridge-handlers.ts

@@ -0,0 +1,102 @@
+import { execFile } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+import { describe, expect, it } from "vitest";
+
+const execFileAsync = promisify(execFile);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const WORKSPACE_ROOT = resolve(__dirname, "../../../../..");
+const DIST_INDEX_URL = pathToFileURL(
+	resolve(WORKSPACE_ROOT, "packages/secure-exec/dist/index.js"),
+).href;
+
+async function runStandaloneScript(source: string): Promise<string> {
+	const { stdout, stderr } = await execFileAsync(
+		"node",
+		["--input-type=module", "-e", source],
+		{
+			cwd: WORKSPACE_ROOT,
+			timeout: 30_000,
+		},
+	);
+
+	expect(stderr).toBe("");
+	return stdout.trim();
+}
+
+describe("standalone dist bootstrap", () => {
+	it("supports runtime.exec and kernel.spawn outside vitest transforms", async () => {
+		const stdout = await runStandaloneScript(`
+			import {
+				NodeRuntime,
+				createInMemoryFileSystem,
+				createKernel,
+				createNodeDriver,
+				createNodeRuntime,
+				createNodeRuntimeDriverFactory,
+			} from ${JSON.stringify(DIST_INDEX_URL)};
+
+			const stdio = [];
+			const runtime = new NodeRuntime({
+				onStdio: (event) => {
+					if (event.channel === "stdout") {
+						stdio.push(event.message);
+					}
+				},
+				systemDriver: createNodeDriver(),
+				runtimeDriverFactory: createNodeRuntimeDriverFactory(),
+			});
+
+			const execResult = await runtime.exec(
+				'console.log("hello"); const fs = require("node:fs"); console.log(typeof fs.readFileSync);',
+			);
+
+			const kernel = createKernel({ filesystem: createInMemoryFileSystem() });
+			await kernel.mount(createNodeRuntime());
+
+			const kernelStdout = [];
+			const proc = kernel.spawn("node", ["-e", 'console.log(1)'], {
+				onStdout: (chunk) => kernelStdout.push(new TextDecoder().decode(chunk)),
+			});
+			const kernelCode = await proc.wait();
+
+			await runtime.terminate();
+			await kernel.dispose();
+
+			const result = JSON.stringify({
+				execCode: execResult.code,
+				execErrorMessage: execResult.errorMessage,
+				stdio,
+				kernelCode,
+				kernelStdout: kernelStdout.join(""),
+			});
+
+			await new Promise((resolve, reject) => {
+				process.stdout.write(result, (error) => {
+					if (error) {
+						reject(error);
+						return;
+					}
+					resolve();
+				});
+			});
+			process.exit(0);
+		`);
+
+		const result = JSON.parse(stdout) as {
+			execCode: number;
+			execErrorMessage?: string;
+			stdio: string[];
+			kernelCode: number;
+			kernelStdout: string;
+		};
+
+		expect(result.execCode).toBe(0);
+		expect(result.execErrorMessage).toBeUndefined();
+		expect(result.stdio.join("")).toContain("hello");
+		expect(result.stdio.join("")).toContain("function");
+		expect(result.kernelCode).toBe(0);
+		expect(result.kernelStdout).toContain("1");
+	}, 30_000);
+});

packages/secure-exec/tests/runtime-driver/node/standalone-dist-smoke.test.ts

@@ -155,7 +155,7 @@
         "Typecheck passes"
       ],
       "priority": 8,
-      "passes": false,
+      "passes": true,
       "notes": "RELEASE BLOCKER. The bridge IIFE that injects CJS globals crashes during bootstrap when run outside vitest. Even `1+1` fails because the bootstrap itself references require. The vitest transform pipeline does something (likely TypeScript path resolution or module format handling) that makes it work. Check packages/core/src/generated/isolate-runtime.ts and how it's loaded by the runtime driver."
     },
     {

scripts/ralph/prd.json

@@ -6,6 +6,7 @@
 - When the session cipher bridge is unavailable, crypto constructor-time validation still has to happen eagerly through the one-shot host bridge; otherwise Node conformance misses `createCipheriv()`/`createDecipheriv()` throw-on-construction cases
 - `bridge-initial-globals.ts` intentionally removes `SharedArrayBuffer`; when vendored conformance files hard-require it, classify the expectation as a `security-constraint` instead of treating the failure as a crypto implementation bug
 - When a crypto/node-conformance expectation reason looks stale, temporarily remove just that entry and rerun the exact vendored file filter; the runner prints the real sandbox stderr, which is often a missing fixture or error-shape mismatch rather than the older bridge-gap guess
+- Host-side ESM packages in `packages/nodejs/src/` cannot use bare `require(...)`; standalone `dist/` execution runs them as real ESM, so bridge helpers must use static imports or `createRequire()`
 - Conformance tests live in packages/secure-exec/tests/node-conformance/ — vendored Node.js v22.14.0 test/parallel/
 - Runner is packages/secure-exec/tests/node-conformance/runner.test.ts — run with: pnpm vitest run packages/secure-exec/tests/node-conformance/runner.test.ts
 - Expectations are in packages/secure-exec/tests/node-conformance/expectations.json — each entry has expected (pass/fail/skip), reason, category
@@ -94,3 +95,12 @@
   - The vendored runner is the quickest way to verify expectation accuracy: removing one entry and rerunning the exact file gives a concrete stderr snippet that can be copied into the reason.
   - Module-overlay drift still shows up in conformance as missing APIs like `require('crypto').randomUUID` and `crypto.hkdf`, even when related globals or bridge handlers exist elsewhere.
 ---
+## [2026-03-25 04:26 PDT] - US-008
+- Implemented the standalone bootstrap fix by removing the last dist-broken bare `require` paths from both the isolate bootstrap and the host bridge handlers, so `NodeRuntime.exec()` and kernel-managed `node` processes work from the built `packages/secure-exec/dist/index.js` entrypoint.
+- Added a dist-based regression smoke test that spawns a real host `node --input-type=module` process, verifies `runtime.exec()` emits `hello` and supports `require("node:fs")`, and verifies `kernel.spawn("node", ["-e", "console.log(1)"])` captures stdout.
+- Files changed: `packages/core/isolate-runtime/src/inject/require-setup.ts`, `packages/core/src/generated/isolate-runtime.ts`, `packages/nodejs/src/bridge-handlers.ts`, `packages/secure-exec/tests/runtime-driver/node/standalone-dist-smoke.test.ts`, `scripts/ralph/prd.json`, `scripts/ralph/progress.txt`
+- **Learnings for future iterations:**
+  - Standalone `dist/` verification has to exercise the built package from a real host `node` process; vitest-importing source files can hide ESM-only failures in host bridge code.
+  - `packages/nodejs/src/bridge-handlers.ts` runs on the host as ESM, so any leftover `require("@secure-exec/core")` calls will only fail once the published-style `dist/` path is used.
+  - When a spawned verification script only needs to report pass/fail state, explicitly flushing stdout and exiting keeps the smoke test focused on bootstrap behavior instead of shared-runtime process lifetime.
+---