@scelar/nodepod 1.0.0

package/src/sdk/nodepod.ts

@@ -0,0 +1,509 @@
+import { MemoryVolume } from "../memory-volume";
+import { ScriptEngine } from "../script-engine";
+import { DependencyInstaller } from "../packages/installer";
+import { RequestProxy, getProxyInstance, type IVirtualServer } from "../request-proxy";
+import type { VolumeSnapshot } from "../engine-types";
+import { Buffer } from "../polyfills/buffer";
+import type {
+  NodepodOptions,
+  TerminalOptions,
+  Snapshot,
+  SpawnOptions,
+} from "./types";
+import { NodepodFS } from "./nodepod-fs";
+import { NodepodProcess } from "./nodepod-process";
+import { NodepodTerminal } from "./nodepod-terminal";
+import { ProcessManager } from "../threading/process-manager";
+import type { ProcessHandle } from "../threading/process-handle";
+import { VFSBridge } from "../threading/vfs-bridge";
+import { isSharedArrayBufferAvailable, SharedVFSController } from "../threading/shared-vfs";
+import { SyncChannelController } from "../threading/sync-channel";
+
+// Lazy-load child_process so the shell doesn't get pulled in at import time
+let _shellMod: typeof import("../polyfills/child_process") | null = null;
+async function getShellMod() {
+  if (!_shellMod) _shellMod = await import("../polyfills/child_process");
+  return _shellMod;
+}
+
+export class Nodepod {
+  readonly fs: NodepodFS;
+
+  private _volume: MemoryVolume;
+  private _engine: ScriptEngine;
+  private _packages: DependencyInstaller;
+  private _proxy: RequestProxy;
+  private _cwd: string;
+
+  private _processManager: ProcessManager;
+  private _vfsBridge: VFSBridge;
+  private _sharedVFS: SharedVFSController | null = null;
+  private _syncChannel: SyncChannelController | null = null;
+  private _unwatchVFS: (() => void) | null = null;
+
+  /* ---- Construction (use Nodepod.boot()) ---- */
+
+  private constructor(
+    volume: MemoryVolume,
+    engine: ScriptEngine,
+    packages: DependencyInstaller,
+    proxy: RequestProxy,
+    cwd: string,
+  ) {
+    this._volume = volume;
+    this._engine = engine;
+    this._packages = packages;
+    this._proxy = proxy;
+    this._cwd = cwd;
+    this.fs = new NodepodFS(volume);
+    this._processManager = new ProcessManager(volume);
+    this._vfsBridge = new VFSBridge(volume);
+
+    this._vfsBridge.setBroadcaster((path, content, excludePid) => {
+      const isDirectory = content !== null && content.byteLength === 0;
+      this._processManager.broadcastVFSChange(path, content, isDirectory, excludePid);
+    });
+
+    this._processManager.setVFSBridge(this._vfsBridge);
+
+    // VFS watcher broadcasts main-thread file changes to workers (needed for HMR)
+    this._unwatchVFS = this._vfsBridge.watch();
+
+    if (isSharedArrayBufferAvailable()) {
+      try {
+        this._sharedVFS = new SharedVFSController();
+        this._processManager.setSharedBuffer(this._sharedVFS.buffer);
+        this._vfsBridge.setSharedVFS(this._sharedVFS);
+      } catch (e) {
+        // COOP/COEP headers probably missing
+      }
+
+      try {
+        this._syncChannel = new SyncChannelController();
+        this._processManager.setSyncBuffer(this._syncChannel.buffer);
+      } catch (e) {
+        // SyncChannel init failed
+      }
+    }
+
+    // Bridge worker HTTP servers to the RequestProxy for preview URLs
+    this._processManager.on("server-listen", (_pid: number, port: number, _hostname: string) => {
+      const proxyServer: IVirtualServer = {
+        listening: true,
+        address: () => ({ port, address: "0.0.0.0", family: "IPv4" }),
+        dispatchRequest: async (method, url, headers, body) => {
+          const bodyStr = body ? (typeof body === "string" ? body : body.toString("utf8")) : null;
+          const result = await this._processManager.dispatchHttpRequest(
+            port, method, url, headers, bodyStr,
+          );
+          return {
+            statusCode: result.statusCode,
+            statusMessage: result.statusMessage,
+            headers: result.headers,
+            body: Buffer.from(result.body),
+          };
+        },
+      };
+      this._proxy.register(proxyServer, port);
+    });
+
+    this._processManager.on("server-close", (_pid: number, port: number) => {
+      this._proxy.unregister(port);
+    });
+
+    this._proxy.setProcessManager(this._processManager);
+  }
+
+  /* ---- Static factory ---- */
+
+  static async boot(opts: NodepodOptions = {}): Promise<Nodepod> {
+    if (typeof Worker === "undefined") {
+      throw new Error("[Nodepod] Web Workers are required. Nodepod cannot run without Web Worker support.");
+    }
+    if (typeof SharedArrayBuffer === "undefined") {
+      throw new Error("[Nodepod] SharedArrayBuffer is required. Ensure Cross-Origin-Isolation headers are set (Cross-Origin-Opener-Policy: same-origin, Cross-Origin-Embedder-Policy: credentialless).");
+    }
+
+    const cwd = opts.workdir ?? "/";
+    const volume = new MemoryVolume();
+    const engine = new ScriptEngine(volume, {
+      cwd,
+      env: opts.env,
+    });
+    const packages = new DependencyInstaller(volume);
+    const proxy = getProxyInstance({
+      onServerReady: opts.onServerReady,
+    });
+
+    const nodepod = new Nodepod(volume, engine, packages, proxy, cwd);
+
+    if (opts.files) {
+      for (const [path, content] of Object.entries(opts.files)) {
+        const dir = path.substring(0, path.lastIndexOf("/")) || "/";
+        if (dir !== "/" && !volume.existsSync(dir)) {
+          volume.mkdirSync(dir, { recursive: true });
+        }
+        volume.writeFileSync(path, content as any);
+      }
+    }
+
+    if (cwd !== "/" && !volume.existsSync(cwd)) {
+      volume.mkdirSync(cwd, { recursive: true });
+    }
+
+    for (const dir of ["/tmp", "/home"]) {
+      if (!volume.existsSync(dir)) {
+        volume.mkdirSync(dir, { recursive: true });
+      }
+    }
+
+    const shell = await getShellMod();
+    shell.initShellExec(volume, { cwd, env: opts.env });
+
+    if (
+      opts.swUrl &&
+      typeof navigator !== "undefined" &&
+      "serviceWorker" in navigator
+    ) {
+      try {
+        await proxy.initServiceWorker({ swUrl: opts.swUrl });
+        // Watermark is on by default — only disable if explicitly set to false
+        if (opts.watermark === false) {
+          proxy.setWatermark(false);
+        }
+      } catch (e) {
+        // SW registration failed, non-fatal
+      }
+    }
+
+    return nodepod;
+  }
+
+  /* ---- spawn() ---- */
+
+  // Each spawn gets a dedicated worker with its own engine + shell
+  async spawn(
+    cmd: string,
+    args?: string[],
+    opts?: SpawnOptions,
+  ): Promise<NodepodProcess> {
+    const proc = new NodepodProcess();
+    const execCwd = opts?.cwd ?? this._cwd;
+
+    const handle = this._processManager.spawn({
+      command: cmd,
+      args: args ?? [],
+      cwd: execCwd,
+      env: opts?.env ?? {},
+    });
+
+    handle.on("stdout", (data: string) => {
+      if (!proc.exited) proc._pushStdout(data);
+    });
+
+    handle.on("stderr", (data: string) => {
+      if (!proc.exited) proc._pushStderr(data);
+    });
+
+    handle.on("exit", (exitCode: number) => {
+      if (!proc.exited) proc._finish(exitCode);
+    });
+
+    handle.on("worker-error", (message: string) => {
+      if (!proc.exited) {
+        proc._pushStderr(`Worker error: ${message}\n`);
+        proc._finish(1);
+      }
+    });
+
+    proc._setSendStdin((data: string) => handle.sendStdin(data));
+    proc._setKillFn(() => handle.kill("SIGINT"));
+
+    if (opts?.signal) {
+      opts.signal.addEventListener("abort", () => {
+        handle.kill("SIGINT");
+      }, { once: true });
+    }
+
+    await new Promise<void>((resolve) => {
+      if (handle.state === "running") {
+        resolve();
+      } else {
+        handle.on("ready", () => resolve());
+      }
+    });
+
+    const isNodeCmd = cmd === "node" && args?.length;
+    if (isNodeCmd) {
+      const filePath = this._resolveCommand(cmd, args);
+      handle.exec({
+        type: "exec",
+        filePath,
+        args: args ?? [],
+        cwd: execCwd,
+        env: opts?.env,
+        isShell: false,
+      });
+    } else {
+      const fullCmd = args?.length ? `${cmd} ${args.join(" ")}` : cmd;
+      handle.exec({
+        type: "exec",
+        filePath: "",
+        args: args ?? [],
+        cwd: execCwd,
+        env: opts?.env,
+        isShell: true,
+        shellCommand: fullCmd,
+      });
+    }
+
+    return proc;
+  }
+
+  private _resolveCommand(cmd: string, args?: string[]): string {
+    if (cmd === "node" && args?.length) {
+      const filePath = args[0];
+      if (filePath.startsWith("/")) return filePath;
+      return `${this._cwd}/${filePath}`.replace(/\/+/g, "/");
+    }
+    return cmd;
+  }
+
+  /* ---- createTerminal() ---- */
+
+  createTerminal(opts: TerminalOptions): NodepodTerminal {
+    const terminal = new NodepodTerminal(opts);
+    terminal.setCwd(this._cwd);
+
+    let activeAbort: AbortController | null = null;
+    let currentSendStdin: ((data: string) => void) | null = null;
+    let activeCommandId = 0;
+    const nextCommandId = () => { activeCommandId = (activeCommandId + 1) % Number.MAX_SAFE_INTEGER; return activeCommandId; };
+    let isStdinRaw = false;
+
+    // Persistent shell worker -- reused across commands so VFS state persists
+    // and we skip the ~1s worker creation overhead per command
+    let shellHandle: ProcessHandle | null = null;
+    let shellReady: Promise<void> | null = null;
+
+    const ensureShellWorker = (): Promise<void> => {
+      if (shellHandle && shellHandle.state !== "exited") {
+        return shellReady!;
+      }
+      shellHandle = this._processManager.spawn({
+        command: "shell",
+        args: [],
+        cwd: this._cwd,
+        env: {},
+      });
+      shellReady = new Promise<void>((resolve) => {
+        if (shellHandle!.state === "running") {
+          resolve();
+        } else {
+          shellHandle!.on("ready", () => resolve());
+        }
+      });
+
+      shellHandle.on("cwd-change", (cwd: string) => {
+        this._cwd = cwd;
+        terminal.setCwd(cwd);
+      });
+
+      shellHandle.on("stdin-raw-status", (raw: boolean) => {
+        isStdinRaw = raw;
+      });
+
+      // Worker died -- next command will spawn a fresh one
+      shellHandle.on("exit", () => {
+        shellHandle = null;
+        shellReady = null;
+      });
+
+      return shellReady;
+    };
+
+    terminal._wireExecution({
+      onCommand: async (cmd: string) => {
+        const myAbort = new AbortController();
+        activeAbort = myAbort;
+        const myCommandId = nextCommandId();
+
+        let streamed = false;
+        let wroteNewline = false;
+
+        function ensureNewline() {
+          if (!wroteNewline) {
+            wroteNewline = true;
+            terminal.write("\r\n");
+          }
+        }
+
+        // Ensure persistent shell worker is running
+        await ensureShellWorker();
+        const handle = shellHandle!;
+
+        // Ignore output from previous commands or before exec is sent (stale child output)
+        let execSent = false;
+        const onStdout = (data: string) => {
+          if (myCommandId !== activeCommandId) return;
+          if (!execSent) return;
+          streamed = true;
+          ensureNewline();
+          terminal._writeOutput(data);
+        };
+        const onStderr = (data: string) => {
+          if (myCommandId !== activeCommandId) return;
+          if (!execSent) return;
+          streamed = true;
+          ensureNewline();
+          terminal._writeOutput(data, true);
+        };
+
+        handle.on("stdout", onStdout);
+        handle.on("stderr", onStderr);
+
+        currentSendStdin = (data: string) => handle.sendStdin(data);
+
+        // PM.kill() recursively kills descendants + cleans up server ports
+        myAbort.signal.addEventListener("abort", () => {
+          this._processManager.kill(handle.pid, "SIGINT");
+        }, { once: true });
+
+        handle.exec({
+          type: "exec",
+          filePath: "",
+          args: [],
+          cwd: this._cwd,
+          isShell: true,
+          shellCommand: cmd,
+          persistent: true,
+        });
+        execSent = true;
+
+        return new Promise<void>((resolve) => {
+          const cleanup = () => {
+            handle.removeListener("shell-done", onDone);
+            handle.removeListener("exit", onExit);
+            handle.removeListener("stdout", onStdout);
+            handle.removeListener("stderr", onStderr);
+          };
+
+          const onDone = (exitCode: number, stdout: string, stderr: string) => {
+            cleanup();
+            const isStale = myCommandId !== activeCommandId;
+            if (!isStale) {
+              currentSendStdin = null;
+            }
+
+            const aborted = myAbort.signal.aborted;
+
+            if (!aborted && !streamed && !isStale) {
+              const outStr = String(stdout ?? "");
+              const errStr = String(stderr ?? "");
+              if (outStr || errStr) ensureNewline();
+              if (outStr) terminal._writeOutput(outStr);
+              if (errStr) terminal._writeOutput(errStr, true);
+            }
+
+            if (activeAbort === myAbort) activeAbort = null;
+
+            if (!aborted && !isStale) {
+              if (!wroteNewline) terminal.write("\r\n");
+              terminal._setRunning(false);
+              terminal._writePrompt();
+            }
+            resolve();
+          };
+
+          const onExit = (exitCode: number, stdout: string, stderr: string) => {
+            cleanup();
+            const isStale = myCommandId !== activeCommandId;
+            if (!isStale) currentSendStdin = null;
+            const aborted = myAbort.signal.aborted;
+            if (!aborted && !streamed && !isStale) {
+              const outStr = String(stdout ?? "");
+              const errStr = String(stderr ?? "");
+              if (outStr || errStr) ensureNewline();
+              if (outStr) terminal._writeOutput(outStr);
+              if (errStr) terminal._writeOutput(errStr, true);
+            }
+            if (activeAbort === myAbort) activeAbort = null;
+            if (!aborted && !isStale) {
+              if (!wroteNewline) terminal.write("\r\n");
+              terminal._setRunning(false);
+              terminal._writePrompt();
+            }
+            resolve();
+          };
+
+          handle.on("shell-done", onDone);
+          handle.on("exit", onExit);
+        });
+      },
+
+      getSendStdin: () => currentSendStdin,
+      getIsStdinRaw: () => isStdinRaw,
+      getActiveAbort: () => activeAbort,
+      setActiveAbort: (ac) => {
+        activeAbort = ac;
+      },
+    });
+
+    return terminal;
+  }
+
+  /* ---- setPreviewScript() ---- */
+
+  // Inject a script into every preview iframe before any page content loads.
+  // Useful for setting up a communication bridge between the main window and
+  // the preview iframe, injecting polyfills, analytics, etc.
+  async setPreviewScript(script: string): Promise<void> {
+    this._proxy.setPreviewScript(script);
+  }
+
+  async clearPreviewScript(): Promise<void> {
+    this._proxy.setPreviewScript(null);
+  }
+
+  /* ---- port() ---- */
+
+  // Returns the preview URL for a server on this port, or null
+  port(num: number): string | null {
+    if (this._proxy.activePorts().includes(num)) {
+      return this._proxy.serverUrl(num);
+    }
+    return null;
+  }
+
+  /* ---- snapshot / restore ---- */
+
+  snapshot(): Snapshot {
+    return this._volume.toSnapshot();
+  }
+
+  restore(snapshot: Snapshot): void {
+    // No clearAll on MemoryVolume, so just swap the internal tree
+    const fresh = MemoryVolume.fromSnapshot(snapshot);
+    (this._volume as any).tree = (fresh as any).tree;
+  }
+
+  /* ---- teardown ---- */
+
+  teardown(): void {
+    if (this._unwatchVFS) {
+      this._unwatchVFS();
+      this._unwatchVFS = null;
+    }
+    this._engine.clearCache();
+    this._processManager.teardown();
+  }
+
+  /* ---- Escape hatches ---- */
+
+  get volume(): MemoryVolume { return this._volume; }
+  get engine(): ScriptEngine { return this._engine; }
+  get packages(): DependencyInstaller { return this._packages; }
+  get proxy(): RequestProxy { return this._proxy; }
+  get processManager(): ProcessManager { return this._processManager; }
+  get cwd(): string { return this._cwd; }
+}

package/src/sdk/types.ts

@@ -0,0 +1,70 @@
+import type { VolumeSnapshot } from "../engine-types";
+
+/* ---- Boot options ---- */
+
+export interface NodepodOptions {
+  files?: Record<string, string | Uint8Array>;
+  env?: Record<string, string>;
+  workdir?: string;
+  swUrl?: string;
+  onServerReady?: (port: number, url: string) => void;
+  /** Show a small "nodepod" watermark link in preview iframes. Defaults to true. */
+  watermark?: boolean;
+}
+
+/* ---- Terminal ---- */
+
+export interface TerminalTheme {
+  background?: string;
+  foreground?: string;
+  cursor?: string;
+  selectionBackground?: string;
+  black?: string;
+  red?: string;
+  green?: string;
+  yellow?: string;
+  blue?: string;
+  magenta?: string;
+  cyan?: string;
+  white?: string;
+  brightBlack?: string;
+  brightRed?: string;
+  brightGreen?: string;
+  brightYellow?: string;
+  brightBlue?: string;
+  brightMagenta?: string;
+  brightCyan?: string;
+  brightWhite?: string;
+}
+
+export interface TerminalOptions {
+  // xterm.js classes are peer deps, passed in as constructors
+  Terminal: any;
+  FitAddon?: any;
+  WebglAddon?: any;
+  theme?: TerminalTheme;
+  fontSize?: number;
+  fontFamily?: string;
+  prompt?: (cwd: string) => string;
+}
+
+/* ---- Filesystem ---- */
+
+export interface StatResult {
+  isFile: boolean;
+  isDirectory: boolean;
+  size: number;
+  mtime: number;
+}
+
+/* ---- Snapshot ---- */
+
+export type Snapshot = VolumeSnapshot;
+
+/* ---- Spawn ---- */
+
+export interface SpawnOptions {
+  cwd?: string;
+  env?: Record<string, string>;
+  signal?: AbortSignal;
+}

package/src/shell/commands/bun.ts

@@ -0,0 +1,121 @@
+import type { ShellCommand } from "../shell-types";
+import type { PmDeps } from "./pm-types";
+import { VERSIONS } from "../../constants/config";
+
+const A_RESET = "\x1b[0m";
+const A_BOLD = "\x1b[1m";
+const A_DIM = "\x1b[2m";
+const A_GREEN = "\x1b[32m";
+const A_CYAN = "\x1b[36m";
+
+export function createBunCommand(deps: PmDeps): ShellCommand {
+  return {
+    name: "bun",
+    async execute(params, ctx) {
+      if (!deps.hasFile("/"))
+        return { stdout: "", stderr: "Volume unavailable\n", exitCode: 1 };
+
+      const sub = params[0];
+      if (!sub || sub === "help" || sub === "--help") {
+        return {
+          stdout:
+            `${A_BOLD}Bun${A_RESET} is a fast JavaScript runtime, package manager, and bundler.\n\n` +
+            `${A_DIM}Usage:${A_RESET} bun <command> [...flags] [...args]\n\n` +
+            `${A_BOLD}Commands:${A_RESET}\n` +
+            `  ${A_CYAN}run${A_RESET}       ${A_DIM}Run a package.json script or file${A_RESET}\n` +
+            `  ${A_CYAN}install${A_RESET}   ${A_DIM}Install dependencies from package.json${A_RESET}\n` +
+            `  ${A_CYAN}add${A_RESET}       ${A_DIM}Add a dependency${A_RESET}\n` +
+            `  ${A_CYAN}remove${A_RESET}    ${A_DIM}Remove a dependency${A_RESET}\n` +
+            `  ${A_CYAN}init${A_RESET}      ${A_DIM}Start an empty Bun project${A_RESET}\n` +
+            `  ${A_CYAN}create${A_RESET}    ${A_DIM}Create a new project from a template${A_RESET}\n` +
+            `  ${A_CYAN}test${A_RESET}      ${A_DIM}Run unit tests${A_RESET}\n` +
+            `  ${A_CYAN}x${A_RESET}         ${A_DIM}Execute a package binary (bunx)${A_RESET}\n` +
+            `  ${A_CYAN}pm${A_RESET}        ${A_DIM}Package manager utilities${A_RESET}\n`,
+          stderr: "",
+          exitCode: 0,
+        };
+      }
+
+      switch (sub) {
+        case "run":
+          if (
+            params[1] &&
+            (params[1].endsWith(".js") ||
+              params[1].endsWith(".ts") ||
+              params[1].endsWith(".mjs") ||
+              params[1].endsWith(".tsx") ||
+              params[1].endsWith(".jsx"))
+          ) {
+            return deps.executeNodeBinary(params[1], params.slice(2), ctx);
+          }
+          return deps.runScript(params.slice(1), ctx);
+        case "start":
+          return deps.runScript(["start"], ctx);
+        case "test":
+        case "t":
+          return deps.runScript(["test"], ctx);
+        case "install":
+        case "i":
+          return deps.installPackages(params.slice(1), ctx, "bun");
+        case "add":
+          return deps.installPackages(params.slice(1), ctx, "bun");
+        case "remove":
+        case "rm":
+          return deps.uninstallPackages(params.slice(1), ctx, "bun");
+        case "x":
+          return deps.npxExecute(params.slice(1), ctx);
+        case "init":
+        case "create":
+          return deps.npmInitOrCreate(params.slice(1), sub, ctx);
+        case "pm": {
+          const pmSub = params[1];
+          if (pmSub === "ls" || pmSub === "list")
+            return deps.listPackages(ctx, "bun");
+          if (pmSub === "cache")
+            return { stdout: "Cache path: /tmp/bun-cache\n", stderr: "", exitCode: 0 };
+          return {
+            stdout: `${A_DIM}bun pm: available subcommands: ls, cache${A_RESET}\n`,
+            stderr: "",
+            exitCode: 0,
+          };
+        }
+        case "version":
+        case "-v":
+        case "--version":
+          return { stdout: VERSIONS.BUN + "\n", stderr: "", exitCode: 0 };
+        case "upgrade":
+          return {
+            stdout: `${A_GREEN}Bun is already up to date.${A_RESET}\n`,
+            stderr: "",
+            exitCode: 0,
+          };
+        default: {
+          // bare `bun <file>` runs it directly, otherwise treat as script
+          if (params[0] && !params[0].startsWith("-")) {
+            const filePath = params[0].startsWith("/")
+              ? params[0]
+              : `${ctx.cwd}/${params[0]}`.replace(/\/+/g, "/");
+            if (deps.hasFile(filePath)) {
+              return deps.executeNodeBinary(params[0], params.slice(1), ctx);
+            }
+            return deps.runScript(params, ctx);
+          }
+          return {
+            stdout: "",
+            stderr: `error: unknown command "${sub}"\n`,
+            exitCode: 1,
+          };
+        }
+      }
+    },
+  };
+}
+
+export function createBunxCommand(deps: PmDeps): ShellCommand {
+  return {
+    name: "bunx",
+    async execute(params, ctx) {
+      return deps.npxExecute(params, ctx);
+    },
+  };
+}