@illuma-ai/code-sandbox 1.0.0

package/src/services/runtime.ts

@@ -0,0 +1,536 @@
+/**
+ * NodepodRuntime — Manages the full lifecycle of a Nodepod sandbox.
+ *
+ * Flow: boot → write files → npm install → run entry command → track changes
+ *
+ * This is the core service that bridges project files and the browser runtime.
+ * It is framework-agnostic (no React) — consumed by the useRuntime hook.
+ */
+
+import { Nodepod } from "@illuma-ai/nodepod";
+import type { NodepodProcess } from "@illuma-ai/nodepod";
+import type { BootProgress, BootStage, FileMap, RuntimeConfig } from "../types";
+
+/** Callback type for progress updates */
+type ProgressCallback = (progress: BootProgress) => void;
+/** Callback type for terminal output lines */
+type OutputCallback = (line: string) => void;
+/** Callback type for server ready */
+type ServerReadyCallback = (port: number, url: string) => void;
+
+/** Debug log prefix for easy filtering in DevTools console */
+const DBG = "[CodeSandbox:Runtime]";
+
+/**
+ * Manages the Nodepod runtime lifecycle.
+ *
+ * Responsibilities:
+ * - Boot Nodepod with COOP/COEP-compatible service worker
+ * - Write project files into the virtual filesystem
+ * - Install npm dependencies from package.json
+ * - Start the entry command (e.g., "node server.js")
+ * - Track file modifications for git diffing
+ * - Provide preview URL for the iframe
+ */
+export class NodepodRuntime {
+  private nodepod: Nodepod | null = null;
+  private serverProcess: NodepodProcess | null = null;
+  private config: RuntimeConfig;
+  private originalFiles: FileMap = {};
+  private currentFiles: FileMap = {};
+  private terminalOutput: string[] = [];
+  private status: BootStage = "initializing";
+  private error: string | null = null;
+  private previewUrl: string | null = null;
+
+  // Callbacks
+  private onProgress: ProgressCallback | null = null;
+  private onOutput: OutputCallback | null = null;
+  private onServerReady: ServerReadyCallback | null = null;
+
+  constructor(config: RuntimeConfig) {
+    this.config = {
+      workdir: "/app",
+      port: 3000,
+      ...config,
+    };
+    console.log(DBG, "constructor", {
+      workdir: this.config.workdir,
+      port: this.config.port,
+      entryCommand: this.config.entryCommand,
+      fileCount: Object.keys(this.config.files).length,
+      files: Object.keys(this.config.files),
+    });
+  }
+
+  /** Register a progress callback */
+  setProgressCallback(cb: ProgressCallback): void {
+    this.onProgress = cb;
+  }
+
+  /** Register a terminal output callback */
+  setOutputCallback(cb: OutputCallback): void {
+    this.onOutput = cb;
+  }
+
+  /** Register a server ready callback */
+  setServerReadyCallback(cb: ServerReadyCallback): void {
+    this.onServerReady = cb;
+  }
+
+  /** Get the current preview URL (null if server not ready) */
+  getPreviewUrl(): string | null {
+    return this.previewUrl;
+  }
+
+  /** Get current status */
+  getStatus(): BootStage {
+    return this.status;
+  }
+
+  /** Get all terminal output */
+  getTerminalOutput(): string[] {
+    return [...this.terminalOutput];
+  }
+
+  /** Get current files (with edits applied) */
+  getCurrentFiles(): FileMap {
+    return { ...this.currentFiles };
+  }
+
+  /** Get the original files (as loaded, before any edits) */
+  getOriginalFiles(): FileMap {
+    return { ...this.originalFiles };
+  }
+
+  /** Get only the files that have been modified since loading */
+  getChangedFiles(): FileMap {
+    const changes: FileMap = {};
+    for (const [path, content] of Object.entries(this.currentFiles)) {
+      if (this.originalFiles[path] !== content) {
+        changes[path] = content;
+      }
+    }
+    return changes;
+  }
+
+  /** Get the error message if status is 'error' */
+  getError(): string | null {
+    return this.error;
+  }
+
+  // -------------------------------------------------------------------------
+  // Lifecycle
+  // -------------------------------------------------------------------------
+
+  /**
+   * Boot the runtime: initialize Nodepod → write files → install → start server.
+   *
+   * This is the main entry point. Call this once.
+   * The progress callback will fire at each stage.
+   */
+  async boot(): Promise<void> {
+    const t0 = performance.now();
+    console.log(DBG, "boot() started");
+
+    try {
+      // Stage 1: Initialize Nodepod
+      this.emitProgress("initializing", "Booting runtime environment...", 5);
+
+      const port = this.config.port ?? 3000;
+      console.log(DBG, "boot: calling Nodepod.boot()", {
+        swUrl: "/__sw__.js",
+        workdir: this.config.workdir,
+        port,
+      });
+
+      // Check preconditions Nodepod will check
+      console.log(
+        DBG,
+        "boot: SharedArrayBuffer available?",
+        typeof SharedArrayBuffer !== "undefined",
+      );
+      console.log(
+        DBG,
+        "boot: Worker available?",
+        typeof Worker !== "undefined",
+      );
+
+      const tBoot = performance.now();
+      this.nodepod = await Nodepod.boot({
+        swUrl: "/__sw__.js",
+        workdir: this.config.workdir,
+        env: this.config.env,
+        onServerReady: (readyPort: number, url: string) => {
+          console.log(DBG, "onServerReady fired!", {
+            readyPort,
+            url,
+            expectedPort: port,
+          });
+          if (readyPort === port) {
+            this.previewUrl = this.rewritePreviewUrl(url);
+            console.log(DBG, "previewUrl set to:", this.previewUrl);
+            this.emitProgress("ready", "Application is running", 100);
+            this.onServerReady?.(readyPort, this.previewUrl);
+          }
+        },
+      });
+      console.log(
+        DBG,
+        `boot: Nodepod.boot() completed in ${(performance.now() - tBoot).toFixed(0)}ms`,
+      );
+
+      this.emitProgress("initializing", "Runtime environment ready", 15);
+
+      // Stage 2: Write project files
+      this.emitProgress("writing-files", "Writing project files...", 20);
+      const tFiles = performance.now();
+      await this.writeFiles(this.config.files);
+      console.log(
+        DBG,
+        `boot: writeFiles completed in ${(performance.now() - tFiles).toFixed(0)}ms`,
+      );
+      this.emitProgress(
+        "writing-files",
+        `Wrote ${Object.keys(this.config.files).length} files`,
+        35,
+      );
+
+      // Verify files were actually written
+      try {
+        const workdir = this.config.workdir ?? "/app";
+        const testFile = Object.keys(this.config.files)[0];
+        if (testFile) {
+          const fullPath = testFile.startsWith("/")
+            ? testFile
+            : `${workdir}/${testFile}`;
+          const exists = await this.nodepod.fs.exists(fullPath);
+          console.log(DBG, `boot: verify file "${fullPath}" exists:`, exists);
+          if (exists) {
+            const content = await this.nodepod.fs.readFile(fullPath, "utf-8");
+            console.log(
+              DBG,
+              `boot: verify file "${fullPath}" has ${content.length} chars`,
+            );
+          }
+        }
+      } catch (verifyErr) {
+        console.warn(DBG, "boot: file verification failed:", verifyErr);
+      }
+
+      // Stage 3: Install dependencies (if package.json exists)
+      if (this.config.files["package.json"]) {
+        this.emitProgress("installing", "Installing dependencies...", 40);
+        const tInstall = performance.now();
+        await this.installDependencies();
+        console.log(
+          DBG,
+          `boot: installDependencies completed in ${(performance.now() - tInstall).toFixed(0)}ms`,
+        );
+        this.emitProgress("installing", "Dependencies installed", 70);
+      } else {
+        console.log(DBG, "boot: no package.json found, skipping install");
+      }
+
+      // Stage 4: Start the entry command
+      this.emitProgress("starting", "Starting application...", 75);
+      const tStart = performance.now();
+      await this.startServer();
+      console.log(
+        DBG,
+        `boot: startServer returned in ${(performance.now() - tStart).toFixed(0)}ms`,
+      );
+      console.log(
+        DBG,
+        `boot: total elapsed ${(performance.now() - t0).toFixed(0)}ms, status=${this.status}`,
+      );
+
+      // Note: 'ready' is emitted by the onServerReady callback above.
+      // If the server doesn't register a port (e.g., non-HTTP scripts),
+      // we mark ready after a short delay.
+      // Also poll more aggressively: check at 1s, 3s, 5s, 10s
+      const fallbackDelays = [1000, 3000, 5000, 10000];
+      for (const delay of fallbackDelays) {
+        setTimeout(() => {
+          if (this.status === "starting") {
+            // Check if we got a preview URL via port registration
+            const url = this.nodepod?.port(port);
+            console.log(
+              DBG,
+              `boot: fallback check @${delay}ms, port(${port}) =`,
+              url,
+              "status =",
+              this.status,
+            );
+            if (url) {
+              this.previewUrl = this.rewritePreviewUrl(url);
+              console.log(DBG, "fallback: previewUrl set to:", this.previewUrl);
+              this.emitProgress("ready", "Application is running", 100);
+              this.onServerReady?.(port, this.previewUrl);
+            } else if (delay === fallbackDelays[fallbackDelays.length - 1]) {
+              // Last check - report failure
+              console.error(
+                DBG,
+                "boot: server never became ready after 10s. Process state:",
+                {
+                  processExited: this.serverProcess?.exited,
+                  previewUrl: this.previewUrl,
+                  status: this.status,
+                },
+              );
+              this.appendOutput(
+                "[system] Server did not start within 10 seconds. Check the logs above for errors.",
+              );
+            }
+          }
+        }, delay);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(DBG, "boot: FATAL ERROR:", err);
+      this.error = message;
+      this.emitProgress("error", `Error: ${message}`, 0);
+      throw err;
+    }
+  }
+
+  /**
+   * Write a single file to the virtual filesystem.
+   * Used for editor changes after boot.
+   */
+  async writeFile(path: string, content: string): Promise<void> {
+    if (!this.nodepod) {
+      throw new Error("Runtime not booted");
+    }
+
+    const fullPath = this.resolvePath(path);
+    await this.nodepod.fs.writeFile(fullPath, content);
+    this.currentFiles[path] = content;
+  }
+
+  /**
+   * Read a file from the virtual filesystem.
+   */
+  async readFile(path: string): Promise<string> {
+    if (!this.nodepod) {
+      throw new Error("Runtime not booted");
+    }
+    const fullPath = this.resolvePath(path);
+    return await this.nodepod.fs.readFile(fullPath, "utf-8");
+  }
+
+  /**
+   * Restart the server process.
+   * Kills the current process and re-runs the entry command.
+   */
+  async restart(): Promise<void> {
+    if (this.serverProcess && !this.serverProcess.exited) {
+      this.serverProcess.kill();
+      // Wait for the process to exit
+      await this.serverProcess.completion.catch(() => {});
+    }
+    this.previewUrl = null;
+    this.emitProgress("starting", "Restarting application...", 75);
+    await this.startServer();
+  }
+
+  /**
+   * Tear down the runtime.
+   * Kills all processes and releases resources.
+   */
+  teardown(): void {
+    if (this.serverProcess && !this.serverProcess.exited) {
+      this.serverProcess.kill();
+    }
+    this.nodepod?.teardown();
+    this.nodepod = null;
+    this.serverProcess = null;
+    this.previewUrl = null;
+    this.status = "initializing";
+    this.terminalOutput = [];
+  }
+
+  /** Get raw Nodepod instance for advanced usage */
+  getNodepod(): Nodepod | null {
+    return this.nodepod;
+  }
+
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
+
+  /**
+   * Rewrite a Nodepod virtual server URL to use /__preview__/ instead of /__virtual__/.
+   *
+   * WHY: Nodepod's serverUrl() returns /__virtual__/{port} URLs, but the
+   * Service Worker only tracks iframe client IDs for /__preview__/{port}
+   * navigations. Without client tracking, subresource requests (JS, CSS,
+   * API calls) from the preview iframe are NOT intercepted by the SW —
+   * they fall through to the real dev server and 404.
+   */
+  private rewritePreviewUrl(url: string): string {
+    return url.replace("/__virtual__/", "/__preview__/");
+  }
+
+  /** Resolve a relative path against the workdir */
+  private resolvePath(relativePath: string): string {
+    const workdir = this.config.workdir ?? "/app";
+    // Normalize: remove leading ./ and ensure proper path joining
+    const clean = relativePath.replace(/^\.\//, "");
+    if (clean.startsWith("/")) {
+      return clean;
+    }
+    return `${workdir}/${clean}`;
+  }
+
+  /** Write all project files to the virtual filesystem */
+  private async writeFiles(files: FileMap): Promise<void> {
+    if (!this.nodepod) {
+      return;
+    }
+
+    // Store originals for change tracking
+    this.originalFiles = { ...files };
+    this.currentFiles = { ...files };
+
+    // Write files in parallel batches of 10
+    const entries = Object.entries(files);
+    const batchSize = 10;
+
+    for (let i = 0; i < entries.length; i += batchSize) {
+      const batch = entries.slice(i, i + batchSize);
+      await Promise.all(
+        batch.map(([path, content]) => {
+          const fullPath = this.resolvePath(path);
+          return this.nodepod!.fs.writeFile(fullPath, content);
+        }),
+      );
+
+      // Update progress within the writing-files stage
+      const percent = 20 + Math.round((i / entries.length) * 15);
+      this.emitProgress(
+        "writing-files",
+        `Writing files... (${Math.min(i + batchSize, entries.length)}/${entries.length})`,
+        percent,
+      );
+    }
+  }
+
+  /**
+   * Install npm dependencies by spawning `npm install` in Nodepod.
+   *
+   * Nodepod's DependencyInstaller handles this internally via its
+   * package registry. We spawn `node -e` with a require to trigger it,
+   * or use the built-in npm install mechanism.
+   */
+  private async installDependencies(): Promise<void> {
+    if (!this.nodepod) {
+      return;
+    }
+
+    const workdir = this.config.workdir ?? "/app";
+
+    try {
+      // Parse package.json to find dependencies
+      const pkgJsonContent = this.config.files["package.json"];
+      if (!pkgJsonContent) {
+        return;
+      }
+
+      const pkgJson = JSON.parse(pkgJsonContent);
+      const deps = {
+        ...(pkgJson.dependencies || {}),
+        ...(pkgJson.devDependencies || {}),
+      };
+
+      const depNames = Object.keys(deps);
+      if (depNames.length === 0) {
+        return;
+      }
+
+      this.appendOutput(`Installing ${depNames.length} dependencies...`);
+
+      // Use Nodepod's built-in package installer for each dependency
+      for (let i = 0; i < depNames.length; i++) {
+        const dep = depNames[i];
+        const version = deps[dep];
+        const specifier = version
+          ? `${dep}@${version.replace(/[\^~>=<]/g, "")}`
+          : dep;
+
+        try {
+          await this.nodepod.packages.install(specifier);
+          this.appendOutput(`  ✓ ${dep}`);
+        } catch (err) {
+          this.appendOutput(
+            `  ✗ ${dep}: ${err instanceof Error ? err.message : err}`,
+          );
+        }
+
+        // Update progress
+        const percent = 40 + Math.round((i / depNames.length) * 30);
+        this.emitProgress(
+          "installing",
+          `Installing ${dep}... (${i + 1}/${depNames.length})`,
+          percent,
+        );
+      }
+
+      this.appendOutput("Dependencies installed.");
+    } catch (err) {
+      this.appendOutput(`Warning: Could not parse package.json: ${err}`);
+    }
+  }
+
+  /** Start the entry command (e.g., "node server.js") */
+  private async startServer(): Promise<void> {
+    if (!this.nodepod) {
+      return;
+    }
+
+    const workdir = this.config.workdir ?? "/app";
+    const command = this.config.entryCommand;
+
+    // Parse the command: "node server.js" → cmd="node", args=["server.js"]
+    const parts = command.split(/\s+/);
+    const cmd = parts[0];
+    const args = parts.slice(1);
+
+    this.appendOutput(`\n$ ${command}`);
+
+    this.serverProcess = await this.nodepod.spawn(cmd, args, { cwd: workdir });
+
+    this.serverProcess.on("output", (chunk: string) => {
+      this.appendOutput(chunk);
+    });
+
+    this.serverProcess.on("error", (chunk: string) => {
+      this.appendOutput(`[stderr] ${chunk}`);
+    });
+
+    this.serverProcess.on("exit", (code: number) => {
+      this.appendOutput(`\nProcess exited with code ${code}`);
+      if (code !== 0 && this.status !== "ready") {
+        this.error = `Process exited with code ${code}`;
+        this.emitProgress("error", `Process exited with code ${code}`, 0);
+      }
+    });
+  }
+
+  /** Emit a progress update */
+  private emitProgress(
+    stage: BootStage,
+    message: string,
+    percent: number,
+  ): void {
+    this.status = stage;
+    const progress: BootProgress = { stage, message, percent };
+    this.onProgress?.(progress);
+  }
+
+  /** Append a line to terminal output */
+  private appendOutput(line: string): void {
+    this.terminalOutput.push(line);
+    this.onOutput?.(line);
+  }
+}

package/src/styles.css

@@ -0,0 +1,24 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* Code Sandbox CSS custom properties — overridable by consumers */
+:root {
+  --sb-bg: #1e1e1e;
+  --sb-bg-alt: #252526;
+  --sb-bg-hover: #2a2d2e;
+  --sb-bg-active: #37373d;
+  --sb-sidebar: #252526;
+  --sb-editor: #1e1e1e;
+  --sb-terminal: #1e1e1e;
+  --sb-preview: #ffffff;
+  --sb-border: #3c3c3c;
+  --sb-text: #cccccc;
+  --sb-text-muted: #858585;
+  --sb-text-active: #ffffff;
+  --sb-accent: #007acc;
+  --sb-accent-hover: #1a8ad4;
+  --sb-success: #4ec9b0;
+  --sb-warning: #cca700;
+  --sb-error: #f44747;
+}