@scelar/nodepod 1.0.0

package/src/engine-types.ts

@@ -0,0 +1,56 @@
+// shared types for the script engine and its execution modes
+
+import type { MemoryVolume } from './memory-volume';
+
+export interface EngineConfig {
+  cwd?: string;
+  env?: Record<string, string>;
+  onConsole?: (method: string, args: unknown[]) => void;
+  onStdout?: (data: string) => void;
+  onStderr?: (data: string) => void;
+}
+
+export interface LoadedModule {
+  id: string;
+  filename: string;
+  exports: unknown;
+  loaded: boolean;
+  children: LoadedModule[];
+  paths: string[];
+}
+
+export interface ExecutionOutcome {
+  exports: unknown;
+  module: LoadedModule;
+}
+
+// async interface implemented by all execution modes (main thread, worker, iframe)
+export interface IScriptEngine {
+  execute(code: string, filename?: string): Promise<ExecutionOutcome>;
+  runFile(filename: string): Promise<ExecutionOutcome>;
+  clearCache(): void;
+  getVolume?(): MemoryVolume;
+  terminate?(): void;
+}
+
+export interface SpawnEngineConfig extends EngineConfig {
+  // cross-origin sandbox URL for maximum isolation (prevents cookie/storage access)
+  sandboxUrl?: string;
+
+  // explicitly permit same-origin eval (required when sandboxUrl is not set)
+  allowUnsafeEval?: boolean;
+
+  // false (default) = main thread, true = Worker, 'auto' = Worker if available
+  useWorker?: boolean | 'auto';
+}
+
+// serialized MemoryVolume for transfer across boundaries
+export interface VolumeSnapshot {
+  entries: VolumeEntry[];
+}
+
+export interface VolumeEntry {
+  path: string;
+  kind: 'file' | 'directory';
+  data?: string; // base64-encoded
+}

package/src/helpers/byte-encoding.ts

@@ -0,0 +1,39 @@
+// Chunked to avoid blowing the call stack on large buffers
+const SEGMENT_SIZE = 8192;
+
+export function bytesToBase64(data: Uint8Array): string {
+  const segments: string[] = [];
+  for (let offset = 0; offset < data.length; offset += SEGMENT_SIZE) {
+    segments.push(
+      String.fromCharCode.apply(null, Array.from(data.subarray(offset, offset + SEGMENT_SIZE)))
+    );
+  }
+  return btoa(segments.join(''));
+}
+
+export function base64ToBytes(encoded: string): Uint8Array {
+  const raw = atob(encoded);
+  const result = new Uint8Array(raw.length);
+  for (let i = 0; i < raw.length; i++) {
+    result[i] = raw.charCodeAt(i);
+  }
+  return result;
+}
+
+export function bytesToHex(data: Uint8Array): string {
+  const chars = new Array(data.length);
+  for (let i = 0; i < data.length; i++) {
+    chars[i] = data[i].toString(16).padStart(2, '0');
+  }
+  return chars.join('');
+}
+
+export function bytesToLatin1(data: Uint8Array): string {
+  const segments: string[] = [];
+  for (let offset = 0; offset < data.length; offset += SEGMENT_SIZE) {
+    segments.push(
+      String.fromCharCode.apply(null, Array.from(data.subarray(offset, offset + SEGMENT_SIZE)))
+    );
+  }
+  return segments.join('');
+}

package/src/helpers/digest.ts

@@ -0,0 +1,9 @@
+// DJB2 hash for cache keys
+export function quickDigest(input: string): string {
+  let accumulator = 0;
+  for (let i = 0; i < input.length; i++) {
+    accumulator = ((accumulator << 5) - accumulator) + input.charCodeAt(i);
+    accumulator |= 0;
+  }
+  return accumulator.toString(36);
+}

package/src/helpers/event-loop.ts

@@ -0,0 +1,96 @@
+// Event loop ref-counting, mirroring Node.js/libuv semantics.
+// Process stays alive while refCount > 0 (servers, readline, child procs).
+// Supports both global mode and per-ProcessContext mode.
+
+import type { ProcessContext } from "../threading/process-context";
+import { getActiveContext } from "../threading/process-context";
+
+/* ---- Global state (fallback when no ProcessContext) ---- */
+
+let _refCount = 0;
+const _drainListeners = new Set<() => void>();
+
+function effectiveDrainListeners(): Set<() => void> {
+  const ctx = getActiveContext();
+  return ctx?.drainListeners ?? _drainListeners;
+}
+
+/* ---- Public API ---- */
+
+export function addDrainListener(cb: () => void): () => void {
+  const listeners = effectiveDrainListeners();
+  listeners.add(cb);
+  return () => listeners.delete(cb);
+}
+
+export function notifyDrain(): void {
+  const ctx = getActiveContext();
+  if (ctx) {
+    for (const cb of ctx.drainListeners) cb();
+  }
+  // Always notify global too (ProcessManager observers)
+  for (const cb of _drainListeners) cb();
+}
+
+export function ref(): void {
+  const ctx = getActiveContext();
+  if (ctx) {
+    ctx.refCount++;
+  } else {
+    _refCount++;
+  }
+}
+
+export function unref(): void {
+  const ctx = getActiveContext();
+  if (ctx) {
+    if (ctx.refCount > 0) ctx.refCount--;
+  } else {
+    if (_refCount > 0) _refCount--;
+  }
+  notifyDrain();
+}
+
+export function getRefCount(): number {
+  const ctx = getActiveContext();
+  return ctx ? ctx.refCount : _refCount;
+}
+
+export function setRefCount(n: number): void {
+  const ctx = getActiveContext();
+  if (ctx) {
+    ctx.refCount = n;
+  } else {
+    _refCount = n;
+  }
+}
+
+export function resetRefCount(): void {
+  const ctx = getActiveContext();
+  if (ctx) {
+    ctx.refCount = 0;
+  } else {
+    _refCount = 0;
+  }
+}
+
+/* ---- Context-specific API ---- */
+
+export function refCtx(ctx: ProcessContext): void {
+  ctx.refCount++;
+}
+
+export function unrefCtx(ctx: ProcessContext): void {
+  if (ctx.refCount > 0) ctx.refCount--;
+  for (const cb of ctx.drainListeners) cb();
+  for (const cb of _drainListeners) cb();
+}
+
+export function getRefCountCtx(ctx: ProcessContext): number {
+  return ctx.refCount;
+}
+
+export function addDrainListenerCtx(ctx: ProcessContext, cb: () => void): () => void {
+  ctx.drainListeners.add(cb);
+  return () => ctx.drainListeners.delete(cb);
+}

package/src/helpers/wasm-cache.ts

@@ -0,0 +1,133 @@
+// WASM compilation cache. Browsers block sync WebAssembly.Module() for large
+// buffers on the main thread, so we either precompile in the background or
+// offload to a worker where there's no size limit.
+
+const PRECOMPILE_THRESHOLD = 4 * 1024 * 1024; // 4 MB
+
+type CacheEntry = {
+  promise: Promise<WebAssembly.Module>;
+  module: WebAssembly.Module | null;
+};
+
+// Keyed by byte length -- good enough since multiple same-size .wasm files are rare
+const sizeCache = new Map<number, CacheEntry>();
+
+function actualByteLength(bytes: BufferSource): number {
+  if (bytes instanceof ArrayBuffer) return bytes.byteLength;
+  return (bytes as ArrayBufferView).byteLength;
+}
+
+function toUint8(bytes: Uint8Array | ArrayBuffer): Uint8Array {
+  if (bytes instanceof ArrayBuffer) return new Uint8Array(bytes);
+  if (
+    bytes.byteOffset !== 0 ||
+    bytes.byteLength !== (bytes.buffer as ArrayBuffer).byteLength
+  ) {
+    return new Uint8Array(
+      bytes.buffer as ArrayBuffer,
+      bytes.byteOffset,
+      bytes.byteLength,
+    );
+  }
+  return bytes;
+}
+
+function toArrayBuffer(bytes: Uint8Array | ArrayBuffer): ArrayBuffer {
+  if (bytes instanceof ArrayBuffer) return bytes;
+  return bytes.buffer.slice(
+    bytes.byteOffset,
+    bytes.byteOffset + bytes.byteLength,
+  ) as ArrayBuffer;
+}
+
+// Call as early as possible (e.g. when writing .wasm to VFS)
+export function precompileWasm(bytes: Uint8Array | ArrayBuffer): void {
+  if (typeof WebAssembly === "undefined") return;
+
+  const len = bytes instanceof ArrayBuffer ? bytes.byteLength : bytes.byteLength;
+  if (len < PRECOMPILE_THRESHOLD) return;
+  if (sizeCache.has(len)) return;
+
+  const view = toUint8(bytes);
+  const entry: CacheEntry = {
+    promise: WebAssembly.compile(view as BufferSource),
+    module: null,
+  };
+  entry.promise.then(
+    (m) => { entry.module = m; },
+    () => {},
+  );
+  sizeCache.set(len, entry);
+}
+
+export function getCachedModule(bytes: BufferSource): WebAssembly.Module | null {
+  const len = actualByteLength(bytes);
+  const entry = sizeCache.get(len);
+  if (entry?.module) return entry.module;
+  return null;
+}
+
+// Worker-based compilation (no size limit in workers)
+let _workerUrl: string | null = null;
+
+function getWorkerUrl(): string {
+  if (_workerUrl) return _workerUrl;
+  const code = `
+    self.onmessage = function(e) {
+      try {
+        var mod = new WebAssembly.Module(e.data.bytes);
+        self.postMessage({ ok: true, module: mod });
+      } catch (err) {
+        self.postMessage({ ok: false, error: err.message });
+      }
+    };
+  `;
+  _workerUrl = URL.createObjectURL(
+    new Blob([code], { type: "application/javascript" }),
+  );
+  return _workerUrl;
+}
+
+export function compileWasmInWorker(
+  bytes: Uint8Array | ArrayBuffer,
+): Promise<WebAssembly.Module> {
+  return new Promise((resolve, reject) => {
+    try {
+      const worker = new Worker(getWorkerUrl());
+      worker.onmessage = (e: MessageEvent) => {
+        worker.terminate();
+        if (e.data.ok) {
+          const len = bytes instanceof ArrayBuffer ? bytes.byteLength : bytes.byteLength;
+          const entry = sizeCache.get(len);
+          if (entry) {
+            entry.module = e.data.module;
+          } else {
+            sizeCache.set(len, {
+              promise: Promise.resolve(e.data.module),
+              module: e.data.module,
+            });
+          }
+          resolve(e.data.module);
+        } else {
+          reject(new Error(e.data.error));
+        }
+      };
+      worker.onerror = (e) => {
+        worker.terminate();
+        reject(new Error(e.message || "Worker compilation failed"));
+      };
+      const ab = toArrayBuffer(bytes);
+      worker.postMessage({ bytes: ab }, [ab]);
+    } catch (e) {
+      // No workers -- fall back to async compile
+      const view = toUint8(bytes instanceof ArrayBuffer ? new Uint8Array(bytes) : bytes);
+      WebAssembly.compile(view as BufferSource).then(resolve, reject);
+    }
+  });
+}
+
+export function needsAsyncCompile(bytes: BufferSource): boolean {
+  return actualByteLength(bytes) >= PRECOMPILE_THRESHOLD;
+}
+
+export { PRECOMPILE_THRESHOLD };

package/src/iframe-sandbox.ts

@@ -0,0 +1,141 @@
+// executes code in a cross-origin iframe for maximum browser isolation
+
+import type { MemoryVolume } from './memory-volume';
+import type { IScriptEngine, ExecutionOutcome, EngineConfig, VolumeSnapshot } from './engine-types';
+
+interface CrossOriginMessage {
+  type: 'init' | 'execute' | 'runFile' | 'clearCache' | 'syncFile' | 'ready' | 'result' | 'error' | 'console';
+  id?: string;
+  code?: string;
+  filename?: string;
+  snapshot?: VolumeSnapshot;
+  config?: EngineConfig;
+  result?: ExecutionOutcome;
+  error?: string;
+  path?: string;
+  content?: string | null;
+  consoleMethod?: string;
+  consoleArgs?: unknown[];
+}
+
+export class IframeSandbox implements IScriptEngine {
+  private frame: HTMLIFrameElement;
+  private targetOrigin: string;
+  private vol: MemoryVolume;
+  private cfg: EngineConfig;
+  private ready: Promise<void>;
+  private pendingCalls = new Map<string, { resolve: (r: ExecutionOutcome) => void; reject: (e: Error) => void }>();
+  private nextId = 0;
+  private onFileChange: ((p: string, c: string) => void) | null = null;
+  private onFileDelete: ((p: string) => void) | null = null;
+  private onMessage: ((e: MessageEvent) => void) | null = null;
+
+  constructor(sandboxUrl: string, vol: MemoryVolume, cfg: EngineConfig = {}) {
+    this.targetOrigin = new URL(sandboxUrl).origin;
+    this.vol = vol;
+    this.cfg = cfg;
+
+    this.frame = document.createElement('iframe');
+    this.frame.src = sandboxUrl;
+    this.frame.style.display = 'none';
+    // @ts-expect-error - credentialless attribute may not exist in types
+    this.frame.credentialless = true;
+    this.frame.setAttribute('credentialless', '');
+    document.body.appendChild(this.frame);
+
+    this.bindMessageHandler();
+    this.ready = this.awaitReady().then(() => this.sendInit());
+    this.attachVolumeSync();
+  }
+
+  private bindMessageHandler(): void {
+    this.onMessage = (event: MessageEvent) => {
+      if (event.origin !== this.targetOrigin) return;
+      const msg = event.data as CrossOriginMessage;
+
+      if (msg.type === 'result' && msg.id) {
+        const pending = this.pendingCalls.get(msg.id);
+        if (pending && msg.result) { pending.resolve(msg.result); this.pendingCalls.delete(msg.id); }
+      } else if (msg.type === 'error' && msg.id) {
+        const pending = this.pendingCalls.get(msg.id);
+        if (pending) { pending.reject(new Error(msg.error || 'Sandbox error')); this.pendingCalls.delete(msg.id); }
+      } else if (msg.type === 'console' && this.cfg.onConsole) {
+        this.cfg.onConsole(msg.consoleMethod || 'log', msg.consoleArgs || []);
+      }
+    };
+    window.addEventListener('message', this.onMessage);
+  }
+
+  private awaitReady(): Promise<void> {
+    return new Promise(resolve => {
+      const handler = (event: MessageEvent) => {
+        if (event.origin !== this.targetOrigin) return;
+        if ((event.data as CrossOriginMessage).type === 'ready') {
+          window.removeEventListener('message', handler);
+          resolve();
+        }
+      };
+      window.addEventListener('message', handler);
+    });
+  }
+
+  private async sendInit(): Promise<void> {
+    const msg: CrossOriginMessage = {
+      type: 'init',
+      snapshot: this.vol.toSnapshot(),
+      config: { cwd: this.cfg.cwd, env: this.cfg.env },
+    };
+    this.frame.contentWindow?.postMessage(msg, this.targetOrigin);
+  }
+
+  private attachVolumeSync(): void {
+    this.onFileChange = (path, content) => {
+      this.frame.contentWindow?.postMessage({ type: 'syncFile', path, content } as CrossOriginMessage, this.targetOrigin);
+    };
+    this.vol.on('change', this.onFileChange);
+
+    this.onFileDelete = (path) => {
+      this.frame.contentWindow?.postMessage({ type: 'syncFile', path, content: null } as CrossOriginMessage, this.targetOrigin);
+    };
+    this.vol.on('delete', this.onFileDelete);
+  }
+
+  private dispatch(msg: CrossOriginMessage): Promise<ExecutionOutcome> {
+    return new Promise((resolve, reject) => {
+      const id = String(this.nextId++);
+      this.pendingCalls.set(id, { resolve, reject });
+      this.frame.contentWindow?.postMessage({ ...msg, id }, this.targetOrigin);
+      setTimeout(() => {
+        if (this.pendingCalls.has(id)) {
+          this.pendingCalls.delete(id);
+          reject(new Error('Sandbox execution timeout'));
+        }
+      }, 60000);
+    });
+  }
+
+  async execute(code: string, filename?: string): Promise<ExecutionOutcome> {
+    await this.ready;
+    return this.dispatch({ type: 'execute', code, filename });
+  }
+
+  async runFile(filename: string): Promise<ExecutionOutcome> {
+    await this.ready;
+    return this.dispatch({ type: 'runFile', filename });
+  }
+
+  clearCache(): void {
+    this.frame.contentWindow?.postMessage({ type: 'clearCache' } as CrossOriginMessage, this.targetOrigin);
+  }
+
+  getVolume(): MemoryVolume { return this.vol; }
+
+  terminate(): void {
+    if (this.onFileChange) this.vol.off('change', this.onFileChange);
+    if (this.onFileDelete) this.vol.off('delete', this.onFileDelete);
+    if (this.onMessage) window.removeEventListener('message', this.onMessage);
+    this.frame.remove();
+    for (const [, { reject }] of this.pendingCalls) reject(new Error('Sandbox terminated'));
+    this.pendingCalls.clear();
+  }
+}

package/src/index.ts

@@ -0,0 +1,192 @@
+// nodepod - browser-native Node.js runtime environment
+
+export { MemoryVolume } from "./memory-volume";
+export type {
+  VolumeNode,
+  FileStat,
+  FileWatchHandle,
+  WatchCallback,
+  WatchEventKind,
+  SystemError,
+} from "./memory-volume";
+export { ScriptEngine, executeCode } from "./script-engine";
+export type { ModuleRecord, EngineOptions, ResolverFn } from "./script-engine";
+export { spawnEngine, WorkerSandbox, IframeSandbox, spawnProcessWorkerEngine, ProcessWorkerAdapter } from "./engine-factory";
+export type {
+  IScriptEngine,
+  ExecutionOutcome,
+  SpawnEngineConfig,
+  EngineConfig,
+  VolumeSnapshot,
+} from "./engine-types";
+export {
+  generateSandboxDeployment,
+  getSandboxPageHtml,
+  getSandboxHostingConfig,
+  SANDBOX_DEPLOYMENT_GUIDE,
+} from "./isolation-helpers";
+export { buildFileSystemBridge } from "./polyfills/fs";
+export type { FsBridge } from "./polyfills/fs";
+export { buildProcessEnv } from "./polyfills/process";
+export type { ProcessObject, ProcessEnvVars } from "./polyfills/process";
+export * as path from "./polyfills/path";
+export * as http from "./polyfills/http";
+export * as net from "./polyfills/net";
+export * as events from "./polyfills/events";
+export * as stream from "./polyfills/stream";
+export * as url from "./polyfills/url";
+export * as querystring from "./polyfills/querystring";
+export * as util from "./polyfills/util";
+export * as npm from "./packages/installer";
+export { DependencyInstaller, install } from "./packages/installer";
+export { RequestProxy, getProxyInstance, resetProxy } from "./request-proxy";
+export type { ProxyOptions, ServiceWorkerConfig } from "./request-proxy";
+export * as chokidar from "./polyfills/chokidar";
+export * as ws from "./polyfills/ws";
+export * as fsevents from "./polyfills/fsevents";
+export * as readdirp from "./polyfills/readdirp";
+export * as module from "./polyfills/module";
+export * as perf_hooks from "./polyfills/perf_hooks";
+export * as worker_threads from "./polyfills/worker_threads";
+export * as esbuild from "./polyfills/esbuild";
+export * as rollup from "./polyfills/rollup";
+export * as assert from "./polyfills/assert";
+
+import { MemoryVolume } from "./memory-volume";
+import { ScriptEngine, EngineOptions } from "./script-engine";
+import { DependencyInstaller } from "./packages/installer";
+import { RequestProxy, getProxyInstance } from "./request-proxy";
+// lazy-load child_process to avoid pulling in the shell at module load time
+let _shellMod: typeof import("./polyfills/child_process") | null = null;
+async function getShellMod() {
+  if (!_shellMod) _shellMod = await import("./polyfills/child_process");
+  return _shellMod;
+}
+
+export interface CommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface CommandOptions {
+  cwd?: string;
+  onStdout?: (data: string) => void;
+  onStderr?: (data: string) => void;
+  signal?: AbortSignal;
+}
+
+export interface WorkspaceConfig extends EngineOptions {
+  baseUrl?: string;
+  onServerReady?: (port: number, url: string) => void;
+}
+
+// create a fully-wired workspace (volume + engine + packages + proxy)
+export function createWorkspace(config?: WorkspaceConfig): {
+  volume: MemoryVolume;
+  engine: ScriptEngine;
+  packages: DependencyInstaller;
+  proxy: RequestProxy;
+  execute: (code: string, filename?: string) => { exports: unknown };
+  runFile: (filename: string) => { exports: unknown };
+  run: (command: string, options?: CommandOptions) => Promise<CommandResult>;
+  sendInput: (data: string) => Promise<void>;
+  createREPL: () => { eval: (code: string) => unknown };
+  on: (event: string, listener: (...args: unknown[]) => void) => void;
+} {
+  const volume = new MemoryVolume();
+  const engine = new ScriptEngine(volume, config);
+  const packages = new DependencyInstaller(volume);
+  const proxy = getProxyInstance({
+    baseUrl: config?.baseUrl,
+    onServerReady: config?.onServerReady,
+  });
+
+  // init shell lazily (SDK path uses Nodepod.boot() instead)
+  getShellMod().then((mod) => mod.initShellExec(volume, { cwd: config?.cwd }));
+
+  return {
+    volume,
+    engine,
+    packages,
+    proxy,
+    execute: (code: string, filename?: string) =>
+      engine.execute(code, filename),
+    runFile: (filename: string) => engine.runFile(filename),
+    run: async (
+      command: string,
+      runOpts?: CommandOptions,
+    ): Promise<CommandResult> => {
+      if (runOpts?.signal?.aborted) {
+        return { stdout: "", stderr: "", exitCode: 130 };
+      }
+
+      const shell = await getShellMod();
+      const hasStreaming =
+        runOpts?.onStdout || runOpts?.onStderr || runOpts?.signal;
+      if (hasStreaming) {
+        shell.setStreamingCallbacks({
+          onStdout: runOpts?.onStdout,
+          onStderr: runOpts?.onStderr,
+          signal: runOpts?.signal,
+        });
+      }
+
+      return new Promise((resolve) => {
+        shell.exec(command, { cwd: runOpts?.cwd }, (error, stdout, stderr) => {
+          if (hasStreaming) shell.clearStreamingCallbacks();
+          resolve({
+            stdout: String(stdout),
+            stderr: String(stderr),
+            exitCode: error ? ((error as any).code ?? 1) : 0,
+          });
+        });
+      });
+    },
+    sendInput: async (data: string) => {
+      const shell = await getShellMod();
+      shell.sendStdin(data);
+    },
+    createREPL: () => engine.createREPL(),
+    on: (event: string, listener: (...args: unknown[]) => void) => {
+      proxy.on(event, listener);
+    },
+  };
+}
+
+export default createWorkspace;
+
+/* ---- SDK (clean public API) ---- */
+
+export { Nodepod } from "./sdk/nodepod";
+export { NodepodTerminal } from "./sdk/nodepod-terminal";
+export { NodepodProcess } from "./sdk/nodepod-process";
+export { NodepodFS } from "./sdk/nodepod-fs";
+export type {
+  NodepodOptions,
+  TerminalOptions,
+  TerminalTheme,
+  StatResult,
+  Snapshot,
+  SpawnOptions,
+} from "./sdk/types";
+
+/* ---- Threading / Worker Infrastructure ---- */
+
+export { ProcessManager } from "./threading/process-manager";
+export { ProcessHandle } from "./threading/process-handle";
+export type { ProcessState } from "./threading/process-handle";
+export { VFSBridge } from "./threading/vfs-bridge";
+export { WorkerVFS } from "./threading/worker-vfs";
+export { SyncChannelController, SyncChannelWorker } from "./threading/sync-channel";
+export { SharedVFSController, SharedVFSReader, isSharedArrayBufferAvailable } from "./threading/shared-vfs";
+export { createProcessContext, getActiveContext, setActiveContext } from "./threading/process-context";
+export type { ProcessContext, ProcessWriter, ProcessReader, OpenFileEntry } from "./threading/process-context";
+export type {
+  VFSBinarySnapshot,
+  VFSSnapshotEntry,
+  SpawnConfig,
+  ProcessInfo,
+  MainToWorkerMessage,
+  WorkerToMainMessage,
+} from "./threading/worker-protocol";