@illuma-ai/code-sandbox 1.0.0 → 1.1.0

package/src/hooks/useRuntime.ts

@@ -3,27 +3,93 @@
  *
  * Manages the Nodepod runtime instance and exposes reactive state
  * for all UI components (progress, files, terminal output, preview URL).
+ *
+ * Supports two file sources:
+ * 1. Direct files (via `files` prop or `template` prop)
+ * 2. GitHub repo (via `github` prop) — with branch polling for hot-reload
+ *
+ * Error exposure: wires the runtime's structured error system and the
+ * preview iframe's browser error capture into a unified `errors[]` array
+ * in state, and forwards each error to the `onSandboxError` callback
+ * so the AI agent can auto-fix.
  */
 
 import { useCallback, useEffect, useRef, useState } from "react";
 import { NodepodRuntime } from "../services/runtime";
+import { GitService } from "../services/git";
 import { getTemplate } from "../templates";
 import type {
   BootProgress,
   CodeSandboxProps,
+  FileChangeStatus,
   FileMap,
+  GitHubRepo,
   RuntimeState,
+  SandboxError,
 } from "../types";
 
+/** Debug log prefix for easy filtering in DevTools */
+const DBG = "[CodeSandbox:useRuntime]";
+
+/** Default polling interval for GitHub branch changes (ms) */
+const DEFAULT_POLL_INTERVAL = 5_000;
+
+/**
+ * Compute per-file change statuses between an original and current file set.
+ *
+ * Returns only files with a non-"unchanged" status (new, modified, deleted).
+ * Files that are identical are omitted — treat missing keys as "unchanged".
+ */
+function computeFileChanges(
+  original: FileMap,
+  current: FileMap,
+): Record<string, FileChangeStatus> {
+  const changes: Record<string, FileChangeStatus> = {};
+
+  // Check current files against original
+  for (const path of Object.keys(current)) {
+    if (!(path in original)) {
+      changes[path] = "new";
+    } else if (original[path] !== current[path]) {
+      changes[path] = "modified";
+    }
+    // unchanged — omit
+  }
+
+  // Check for deleted files (in original but not in current)
+  for (const path of Object.keys(original)) {
+    if (!(path in current)) {
+      changes[path] = "deleted";
+    }
+  }
+
+  return changes;
+}
+
 /**
  * Hook that manages the full Nodepod runtime lifecycle.
  *
  * @param props - CodeSandbox component props
  * @returns Reactive runtime state + control functions
+ *
+ * @example
+ * ```tsx
+ * // Direct files
+ * const { state } = useRuntime({ files: myFiles, entryCommand: 'node server.js' });
+ *
+ * // GitHub repo with auto-polling
+ * const { state } = useRuntime({
+ *   github: { owner: 'illuma-ai', repo: 'fullstack-starter', branch: 'main' },
+ *   gitToken: 'ghp_xxx',
+ *   onSandboxError: (err) => agent.fix(err),
+ * });
+ * ```
  */
 export function useRuntime(props: CodeSandboxProps) {
   const {
     files: propFiles,
+    github,
+    gitToken,
     template,
     entryCommand: propEntryCommand,
     port: propPort,
@@ -32,10 +98,19 @@ export function useRuntime(props: CodeSandboxProps) {
     onServerReady,
     onProgress,
     onError,
+    onSandboxError,
   } = props;
 
   const runtimeRef = useRef<NodepodRuntime | null>(null);
   const bootedRef = useRef(false);
+  /** Ref for the latest onSandboxError callback (avoids stale closures) */
+  const onSandboxErrorRef = useRef(onSandboxError);
+  onSandboxErrorRef.current = onSandboxError;
+
+  /** SHA of the latest commit we've seen on the polled branch */
+  const lastCommitShaRef = useRef<string | null>(null);
+  /** Interval ID for GitHub polling */
+  const pollIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
 
   const [state, setState] = useState<RuntimeState>({
     status: "initializing",
@@ -43,13 +118,62 @@ export function useRuntime(props: CodeSandboxProps) {
     previewUrl: null,
     terminalOutput: [],
     files: {},
+    originalFiles: {},
+    fileChanges: {},
     error: null,
+    errors: [],
   });
 
   const [selectedFile, setSelectedFile] = useState<string | null>(null);
   const [openFiles, setOpenFiles] = useState<string[]>([]);
 
-  // Resolve files + entry command from props or template
+  // -------------------------------------------------------------------------
+  // Error handling — unified pipeline
+  // -------------------------------------------------------------------------
+
+  /**
+   * Handle a structured error from any source (runtime or browser).
+   *
+   * Appends to the errors array in state and forwards to onSandboxError.
+   * The runtime calls reportError for process errors; the Preview
+   * component calls handleBrowserError for iframe errors.
+   */
+  const handleSandboxError = useCallback((error: SandboxError) => {
+    setState((prev) => ({
+      ...prev,
+      errors: [...prev.errors, error],
+    }));
+    onSandboxErrorRef.current?.(error);
+  }, []);
+
+  /**
+   * Handle a browser error from the preview iframe.
+   *
+   * Called by the Preview component's onBrowserError callback.
+   * We enrich the error with source context from the runtime
+   * (if the file exists in our virtual FS) then record it.
+   */
+  const handleBrowserError = useCallback(
+    async (error: SandboxError) => {
+      const runtime = runtimeRef.current;
+      if (runtime) {
+        // reportError enriches with source context and records internally
+        await runtime.reportError(error);
+      }
+      // Also update React state
+      handleSandboxError(error);
+    },
+    [handleSandboxError],
+  );
+
+  // -------------------------------------------------------------------------
+  // Config resolution
+  // -------------------------------------------------------------------------
+
+  /**
+   * Resolve files + entry command from props or template.
+   * Returns null if using GitHub (files loaded async).
+   */
   const resolvedConfig = useCallback(() => {
     if (propFiles) {
       return {
@@ -70,131 +194,373 @@ export function useRuntime(props: CodeSandboxProps) {
       }
     }
 
+    // GitHub mode — files loaded asynchronously
+    if (github) {
+      return null;
+    }
+
     // Default: empty project
     return {
       files: {},
       entryCommand: propEntryCommand || "node server.js",
       port: propPort || 3000,
     };
-  }, [propFiles, template, propEntryCommand, propPort]);
+  }, [propFiles, template, github, propEntryCommand, propPort]);
 
-  // Boot the runtime on mount
-  useEffect(() => {
-    if (bootedRef.current) {
-      return;
-    }
-    bootedRef.current = true;
+  // -------------------------------------------------------------------------
+  // Boot helpers
+  // -------------------------------------------------------------------------
 
-    const config = resolvedConfig();
-    if (Object.keys(config.files).length === 0) {
-      return;
-    }
+  /**
+   * Boot the runtime with a resolved file set.
+   *
+   * Shared between direct-file mode and GitHub mode.
+   */
+  const bootWithFiles = useCallback(
+    (files: FileMap, entryCommand: string, port: number) => {
+      const runtime = new NodepodRuntime({
+        files,
+        entryCommand,
+        port,
+        env,
+      });
+
+      runtimeRef.current = runtime;
+
+      // Set initial files state + open the first file
+      setState((prev) => ({
+        ...prev,
+        files,
+      }));
+
+      const fileNames = Object.keys(files);
+      const entryFile =
+        fileNames.find((f) => f === "server.js") ||
+        fileNames.find((f) => f === "index.js") ||
+        fileNames.find((f) => f.endsWith(".js")) ||
+        fileNames[0];
+
+      if (entryFile) {
+        setSelectedFile(entryFile);
+        setOpenFiles([entryFile]);
+      }
+
+      // Wire progress callback
+      runtime.setProgressCallback((progress: BootProgress) => {
+        setState((prev) => ({
+          ...prev,
+          status: progress.stage,
+          progress,
+          previewUrl: runtime.getPreviewUrl(),
+          error: progress.stage === "error" ? progress.message : prev.error,
+        }));
+        onProgress?.(progress);
+        if (progress.stage === "error") {
+          onError?.(progress.message);
+        }
+      });
+
+      // Wire terminal output callback
+      runtime.setOutputCallback((line: string) => {
+        setState((prev) => ({
+          ...prev,
+          terminalOutput: [...prev.terminalOutput, line],
+        }));
+      });
+
+      // Wire server ready callback
+      runtime.setServerReadyCallback((readyPort: number, url: string) => {
+        setState((prev) => ({
+          ...prev,
+          previewUrl: url,
+          status: "ready",
+        }));
+        onServerReady?.(readyPort, url);
+      });
+
+      // Wire structured error callback
+      runtime.setErrorCallback(handleSandboxError);
+
+      // Boot
+      runtime.boot().catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        onError?.(msg);
+      });
+
+      return runtime;
+    },
+    [env, onProgress, onError, onServerReady, handleSandboxError],
+  );
+
+  // -------------------------------------------------------------------------
+  // GitHub branch polling
+  // -------------------------------------------------------------------------
+
+  /**
+   * Fetch the latest commit SHA for a branch.
+   * Used to detect when the agent pushes new commits.
+   */
+  const fetchLatestSha = useCallback(
+    async (repo: GitHubRepo, token: string): Promise<string | null> => {
+      try {
+        const { owner, repo: repoName, branch = "main" } = repo;
+        const res = await fetch(
+          `https://api.github.com/repos/${owner}/${repoName}/git/ref/heads/${branch}`,
+          {
+            headers: {
+              Authorization: `Bearer ${token}`,
+              Accept: "application/vnd.github.v3+json",
+            },
+          },
+        );
+        if (!res.ok) return null;
+        const data = await res.json();
+        return data.object?.sha ?? null;
+      } catch {
+        return null;
+      }
+    },
+    [],
+  );
+
+  /**
+   * Update files in the running sandbox when changes are detected.
+   *
+   * Writes new/changed files to Nodepod's virtual FS and restarts
+   * the server process. Deleted files are NOT removed (Nodepod FS
+   * doesn't support delete yet — they just become stale).
+   *
+   * Stores the previous file set as `originalFiles` so the diff
+   * viewer can show what changed.
+   *
+   * @param newFiles - The full new file set from the repo
+   */
+  const updateFiles = useCallback(async (newFiles: FileMap) => {
+    const runtime = runtimeRef.current;
+    if (!runtime) return;
+
+    const currentFiles = runtime.getCurrentFiles();
+    let changed = false;
 
-    const runtime = new NodepodRuntime({
-      files: config.files,
-      entryCommand: config.entryCommand,
-      port: config.port,
-      env,
-    });
+    for (const [path, content] of Object.entries(newFiles)) {
+      if (currentFiles[path] !== content) {
+        try {
+          await runtime.writeFile(path, content);
+          changed = true;
+          console.log(DBG, `updated file: ${path}`);
+        } catch (err) {
+          console.warn(DBG, `failed to write ${path}:`, err);
+        }
+      }
+    }
 
-    runtimeRef.current = runtime;
+    // Compute change status before updating state.
+    // The "original" is what we had before this update.
+    const fileChanges = computeFileChanges(currentFiles, newFiles);
 
-    // Set initial files state + open the first file
+    // Update React state with new file set + diff info
     setState((prev) => ({
       ...prev,
-      files: config.files,
+      originalFiles: currentFiles,
+      files: newFiles,
+      fileChanges,
     }));
 
-    const fileNames = Object.keys(config.files);
-    // Auto-select entry file or first file
-    const entryFile =
-      fileNames.find((f) => f === "server.js") ||
-      fileNames.find((f) => f === "index.js") ||
-      fileNames.find((f) => f.endsWith(".js")) ||
-      fileNames[0];
-
-    if (entryFile) {
-      setSelectedFile(entryFile);
-      setOpenFiles([entryFile]);
+    // Restart server if any files changed
+    if (changed) {
+      console.log(
+        DBG,
+        `files changed — restarting server (${Object.keys(fileChanges).length} files differ)`,
+      );
+      try {
+        await runtime.restart();
+      } catch (err) {
+        console.error(DBG, "restart failed:", err);
+      }
     }
+  }, []);
 
-    // Wire callbacks
-    runtime.setProgressCallback((progress: BootProgress) => {
-      setState((prev) => ({
-        ...prev,
-        status: progress.stage,
-        progress,
-        previewUrl: runtime.getPreviewUrl(),
-        error: progress.stage === "error" ? progress.message : prev.error,
-      }));
-      onProgress?.(progress);
-      if (progress.stage === "error") {
-        onError?.(progress.message);
+  /**
+   * Start polling a GitHub branch for new commits.
+   *
+   * When a new commit is detected:
+   * 1. Fetch the full file tree via GitService.cloneRepo()
+   * 2. Diff against current files
+   * 3. Write changed files to Nodepod FS
+   * 4. Restart the server
+   */
+  const startPolling = useCallback(
+    (repo: GitHubRepo, token: string) => {
+      // Stop any existing polling
+      if (pollIntervalRef.current) {
+        clearInterval(pollIntervalRef.current);
       }
-    });
 
-    runtime.setOutputCallback((line: string) => {
-      setState((prev) => ({
-        ...prev,
-        terminalOutput: [...prev.terminalOutput, line],
-      }));
-    });
+      console.log(DBG, "starting branch polling", {
+        owner: repo.owner,
+        repo: repo.repo,
+        branch: repo.branch || "main",
+        interval: DEFAULT_POLL_INTERVAL,
+      });
+
+      pollIntervalRef.current = setInterval(async () => {
+        const latestSha = await fetchLatestSha(repo, token);
+        if (!latestSha) return;
+
+        if (
+          lastCommitShaRef.current &&
+          latestSha !== lastCommitShaRef.current
+        ) {
+          console.log(DBG, "new commit detected:", latestSha);
+          lastCommitShaRef.current = latestSha;
+
+          // Fetch updated files
+          const git = new GitService(token);
+          try {
+            const newFiles = await git.cloneRepo(repo);
+            await updateFiles(newFiles);
+          } catch (err) {
+            console.error(DBG, "failed to fetch updated files:", err);
+          }
+        } else if (!lastCommitShaRef.current) {
+          // First poll — just record the SHA, don't re-fetch
+          lastCommitShaRef.current = latestSha;
+        }
+      }, DEFAULT_POLL_INTERVAL);
+    },
+    [fetchLatestSha, updateFiles],
+  );
+
+  // -------------------------------------------------------------------------
+  // Boot on mount
+  // -------------------------------------------------------------------------
+
+  useEffect(() => {
+    if (bootedRef.current) return;
+    bootedRef.current = true;
+
+    const config = resolvedConfig();
+
+    if (config) {
+      // Direct files or template — boot immediately
+      if (Object.keys(config.files).length === 0) return;
+      bootWithFiles(config.files, config.entryCommand, config.port);
+    } else if (github && gitToken) {
+      // GitHub mode — fetch files then boot, then start polling
+      const entryCommand = propEntryCommand || "node server.js";
+      const port = propPort || 3000;
 
-    runtime.setServerReadyCallback((port: number, url: string) => {
       setState((prev) => ({
         ...prev,
-        previewUrl: url,
-        status: "ready",
+        progress: {
+          stage: "initializing",
+          message: "Cloning repository from GitHub...",
+          percent: 5,
+        },
       }));
-      onServerReady?.(port, url);
-    });
 
-    // Boot
-    runtime.boot().catch((err) => {
-      const msg = err instanceof Error ? err.message : String(err);
-      onError?.(msg);
-    });
+      const git = new GitService(gitToken);
+      git
+        .cloneRepo(github, (percent, message) => {
+          setState((prev) => ({
+            ...prev,
+            progress: { stage: "initializing", message, percent },
+          }));
+        })
+        .then((files) => {
+          // Infer entry command from package.json if not provided
+          let resolvedEntryCommand = entryCommand;
+          if (!propEntryCommand && files["package.json"]) {
+            try {
+              const pkg = JSON.parse(files["package.json"]);
+              if (pkg.scripts?.start) {
+                // Convert "node server.js" style commands
+                resolvedEntryCommand = pkg.scripts.start;
+              }
+            } catch {
+              /* use default */
+            }
+          }
+
+          const runtime = bootWithFiles(files, resolvedEntryCommand, port);
+
+          // Start polling for branch changes
+          startPolling(github, gitToken);
+        })
+        .catch((err) => {
+          const msg = err instanceof Error ? err.message : String(err);
+          console.error(DBG, "GitHub clone failed:", err);
+          setState((prev) => ({
+            ...prev,
+            status: "error",
+            error: msg,
+            progress: { stage: "error", message: msg, percent: 0 },
+          }));
+          onError?.(msg);
+        });
+    }
 
     // Cleanup on unmount
     return () => {
-      runtime.teardown();
+      runtimeRef.current?.teardown();
       runtimeRef.current = null;
+      if (pollIntervalRef.current) {
+        clearInterval(pollIntervalRef.current);
+        pollIntervalRef.current = null;
+      }
     };
   }, []); // eslint-disable-line react-hooks/exhaustive-deps
 
-  // File change handler
+  // -------------------------------------------------------------------------
+  // File editing
+  // -------------------------------------------------------------------------
+
   const handleFileChange = useCallback(
     async (path: string, content: string) => {
       const runtime = runtimeRef.current;
-      if (!runtime) {
-        return;
-      }
+      if (!runtime) return;
 
-      // Write to Nodepod FS
       try {
         await runtime.writeFile(path, content);
       } catch (err) {
         console.error(`Failed to write file ${path}:`, err);
       }
 
-      // Update state
-      setState((prev) => ({
-        ...prev,
-        files: { ...prev.files, [path]: content },
-      }));
+      setState((prev) => {
+        const newFiles = { ...prev.files, [path]: content };
+        // Recompute change status for this file against originalFiles.
+        // Only update this file's status — don't recompute everything.
+        const newChanges = { ...prev.fileChanges };
+        if (!(path in prev.originalFiles)) {
+          newChanges[path] = "new";
+        } else if (prev.originalFiles[path] !== content) {
+          newChanges[path] = "modified";
+        } else {
+          // Reverted back to original — remove from changes
+          delete newChanges[path];
+        }
+
+        return {
+          ...prev,
+          files: newFiles,
+          fileChanges: newChanges,
+        };
+      });
 
       onFileChange?.(path, content);
     },
     [onFileChange],
   );
 
-  // Select a file
+  // -------------------------------------------------------------------------
+  // File selection
+  // -------------------------------------------------------------------------
+
   const handleSelectFile = useCallback((path: string) => {
     setSelectedFile(path);
     setOpenFiles((prev) => (prev.includes(path) ? prev : [...prev, path]));
   }, []);
 
-  // Close a file tab
   const handleCloseFile = useCallback(
     (path: string) => {
       setOpenFiles((prev) => {
@@ -208,16 +574,20 @@ export function useRuntime(props: CodeSandboxProps) {
     [selectedFile],
   );
 
-  // Restart the server
+  // -------------------------------------------------------------------------
+  // Server control
+  // -------------------------------------------------------------------------
+
   const restart = useCallback(async () => {
     const runtime = runtimeRef.current;
-    if (!runtime) {
-      return;
-    }
+    if (!runtime) return;
     await runtime.restart();
   }, []);
 
-  // Get changed files for git operations
+  // -------------------------------------------------------------------------
+  // Git operations
+  // -------------------------------------------------------------------------
+
   const getChangedFiles = useCallback((): FileMap => {
     return runtimeRef.current?.getChangedFiles() ?? {};
   }, []);
@@ -229,6 +599,7 @@ export function useRuntime(props: CodeSandboxProps) {
     handleFileChange,
     handleSelectFile,
     handleCloseFile,
+    handleBrowserError,
     restart,
     getChangedFiles,
     runtime: runtimeRef,

package/src/index.ts

@@ -31,6 +31,9 @@ export { getTemplate, listTemplates } from "./templates";
 export type {
   FileMap,
   FileNode,
+  FileChangeStatus,
+  SandboxError,
+  SandboxErrorCategory,
   BootStage,
   BootProgress,
   RuntimeConfig,