@illuma-ai/code-sandbox 1.1.0 → 1.2.1

package/src/hooks/useRuntime.ts

@@ -4,9 +4,9 @@
  * 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
+ * The sandbox is a pure renderer — it receives files via props (initial
+ * load) and via the imperative handle (updateFiles/updateFile for live
+ * updates). It does NOT interact with any storage backend directly.
  *
  * Error exposure: wires the runtime's structured error system and the
  * preview iframe's browser error capture into a unified `errors[]` array
@@ -16,14 +16,12 @@
 
 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";
@@ -31,9 +29,6 @@ import type {
 /** 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.
  *
@@ -69,27 +64,27 @@ function computeFileChanges(
 /**
  * Hook that manages the full Nodepod runtime lifecycle.
  *
+ * The sandbox is a pure renderer — it receives files via props or the
+ * imperative handle. No polling, no storage backends.
+ *
  * @param props - CodeSandbox component props
- * @returns Reactive runtime state + control functions
+ * @returns Reactive runtime state + control functions + imperative methods
  *
  * @example
  * ```tsx
- * // Direct files
- * const { state } = useRuntime({ files: myFiles, entryCommand: 'node server.js' });
+ * // Direct files (fetched from any source by the host app)
+ * const runtime = useRuntime({ files: myFiles, entryCommand: 'node server.js' });
+ *
+ * // Later, push updated files from the host:
+ * await runtime.updateFiles(newFiles);
  *
- * // 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),
- * });
+ * // Or update a single file:
+ * await runtime.updateFile('server.js', newContent);
  * ```
  */
 export function useRuntime(props: CodeSandboxProps) {
   const {
     files: propFiles,
-    github,
-    gitToken,
     template,
     entryCommand: propEntryCommand,
     port: propPort,
@@ -99,6 +94,7 @@ export function useRuntime(props: CodeSandboxProps) {
     onProgress,
     onError,
     onSandboxError,
+    onFilesUpdated,
   } = props;
 
   const runtimeRef = useRef<NodepodRuntime | null>(null);
@@ -107,10 +103,9 @@ export function useRuntime(props: CodeSandboxProps) {
   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);
+  /** Ref for latest onFilesUpdated callback */
+  const onFilesUpdatedRef = useRef(onFilesUpdated);
+  onFilesUpdatedRef.current = onFilesUpdated;
 
   const [state, setState] = useState<RuntimeState>({
     status: "initializing",
@@ -172,13 +167,24 @@ export function useRuntime(props: CodeSandboxProps) {
 
   /**
    * Resolve files + entry command from props or template.
-   * Returns null if using GitHub (files loaded async).
    */
   const resolvedConfig = useCallback(() => {
-    if (propFiles) {
+    if (propFiles && Object.keys(propFiles).length > 0) {
+      // Infer entry command from package.json if not provided
+      let entryCommand = propEntryCommand || "node server.js";
+      if (!propEntryCommand && propFiles["package.json"]) {
+        try {
+          const pkg = JSON.parse(propFiles["package.json"]);
+          if (pkg.scripts?.start) {
+            entryCommand = pkg.scripts.start;
+          }
+        } catch {
+          /* use default */
+        }
+      }
       return {
         files: propFiles,
-        entryCommand: propEntryCommand || "node server.js",
+        entryCommand,
         port: propPort || 3000,
       };
     }
@@ -194,18 +200,9 @@ 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, github, propEntryCommand, propPort]);
+    // No files provided — return null (sandbox waits for updateFiles)
+    return null;
+  }, [propFiles, template, propEntryCommand, propPort]);
 
   // -------------------------------------------------------------------------
   // Boot helpers
@@ -213,8 +210,6 @@ export function useRuntime(props: CodeSandboxProps) {
 
   /**
    * 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) => {
@@ -293,143 +288,145 @@ export function useRuntime(props: CodeSandboxProps) {
   );
 
   // -------------------------------------------------------------------------
-  // GitHub branch polling
+  // Imperative file update methods
   // -------------------------------------------------------------------------
 
   /**
-   * 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.
+   * Push a complete new file set into the sandbox.
    *
-   * 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).
+   * Diffs against current files, writes only changed files to Nodepod FS,
+   * and restarts the server if anything changed (unless restartServer=false).
    *
-   * Stores the previous file set as `originalFiles` so the diff
-   * viewer can show what changed.
+   * The previous file set becomes `originalFiles` for diff tracking.
    *
-   * @param newFiles - The full new file set from the repo
+   * Called by the imperative handle's updateFiles() method.
+   * Also usable as the initial boot path when files arrive asynchronously
+   * (e.g., host fetches from a remote source, then calls updateFiles).
    */
-  const updateFiles = useCallback(async (newFiles: FileMap) => {
-    const runtime = runtimeRef.current;
-    if (!runtime) return;
+  const updateFiles = useCallback(
+    async (newFiles: FileMap, options?: { restartServer?: boolean }) => {
+      const shouldRestart = options?.restartServer !== false;
+      const runtime = runtimeRef.current;
 
-    const currentFiles = runtime.getCurrentFiles();
-    let changed = false;
+      // If runtime hasn't booted yet, boot with these files
+      if (!runtime) {
+        if (bootedRef.current) {
+          console.warn(
+            DBG,
+            "updateFiles called but runtime is gone (already torn down)",
+          );
+          return;
+        }
+        bootedRef.current = true;
 
-    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);
+        // Infer entry command from package.json
+        let entryCommand = propEntryCommand || "node server.js";
+        if (!propEntryCommand && newFiles["package.json"]) {
+          try {
+            const pkg = JSON.parse(newFiles["package.json"]);
+            if (pkg.scripts?.start) {
+              entryCommand = pkg.scripts.start;
+            }
+          } catch {
+            /* use default */
+          }
         }
+        const port = propPort || 3000;
+
+        bootWithFiles(newFiles, entryCommand, port);
+        return;
       }
-    }
 
-    // Compute change status before updating state.
-    // The "original" is what we had before this update.
-    const fileChanges = computeFileChanges(currentFiles, newFiles);
+      // Runtime exists — diff and write changed files
+      const currentFiles = runtime.getCurrentFiles();
+      let changed = false;
 
-    // Update React state with new file set + diff info
-    setState((prev) => ({
-      ...prev,
-      originalFiles: currentFiles,
-      files: newFiles,
-      fileChanges,
-    }));
+      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);
+          }
+        }
+      }
 
-    // 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);
+      // Compute change status — "original" is what we had before this update
+      const fileChanges = computeFileChanges(currentFiles, newFiles);
+
+      // Update React state with new file set + diff info
+      setState((prev) => ({
+        ...prev,
+        originalFiles: currentFiles,
+        files: newFiles,
+        fileChanges,
+      }));
+
+      // Restart server if any files changed
+      if (changed && shouldRestart) {
+        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);
+        }
       }
-    }
-  }, []);
+
+      // Notify host that files have been processed
+      onFilesUpdatedRef.current?.(fileChanges);
+    },
+    [propEntryCommand, propPort, bootWithFiles],
+  );
 
   /**
-   * Start polling a GitHub branch for new commits.
+   * Push a single file update into the sandbox.
+   *
+   * Writes to Nodepod FS and updates React state. Does NOT restart
+   * the server — use restart() if needed, or updateFiles() for bulk
+   * updates with auto-restart.
    *
-   * 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
+   * This is the same path as editor edits, but callable imperatively
+   * (e.g., when the agent modifies a single file).
    */
-  const startPolling = useCallback(
-    (repo: GitHubRepo, token: string) => {
-      // Stop any existing polling
-      if (pollIntervalRef.current) {
-        clearInterval(pollIntervalRef.current);
-      }
-
-      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;
+  const updateFile = useCallback(async (path: string, content: string) => {
+    const runtime = runtimeRef.current;
+    if (!runtime) {
+      console.warn(
+        DBG,
+        "updateFile called but runtime not ready. Use updateFiles() for initial load.",
+      );
+      return;
+    }
 
-        if (
-          lastCommitShaRef.current &&
-          latestSha !== lastCommitShaRef.current
-        ) {
-          console.log(DBG, "new commit detected:", latestSha);
-          lastCommitShaRef.current = latestSha;
+    try {
+      await runtime.writeFile(path, content);
+    } catch (err) {
+      console.error(`Failed to write file ${path}:`, err);
+    }
 
-          // 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],
-  );
+    setState((prev) => {
+      const newFiles = { ...prev.files, [path]: content };
+      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,
+      };
+    });
+  }, []);
 
   // -------------------------------------------------------------------------
   // Boot on mount
@@ -437,82 +434,27 @@ export function useRuntime(props: CodeSandboxProps) {
 
   useEffect(() => {
     if (bootedRef.current) return;
-    bootedRef.current = true;
 
     const config = resolvedConfig();
 
     if (config) {
       // Direct files or template — boot immediately
+      bootedRef.current = true;
       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;
-
-      setState((prev) => ({
-        ...prev,
-        progress: {
-          stage: "initializing",
-          message: "Cloning repository from GitHub...",
-          percent: 5,
-        },
-      }));
-
-      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);
-        });
     }
+    // If no config (no files, no template), sandbox waits for
+    // updateFiles() to be called via the imperative handle.
 
     // Cleanup on unmount
     return () => {
       runtimeRef.current?.teardown();
       runtimeRef.current = null;
-      if (pollIntervalRef.current) {
-        clearInterval(pollIntervalRef.current);
-        pollIntervalRef.current = null;
-      }
     };
   }, []); // eslint-disable-line react-hooks/exhaustive-deps
 
   // -------------------------------------------------------------------------
-  // File editing
+  // File editing (from the CodeEditor UI)
   // -------------------------------------------------------------------------
 
   const handleFileChange = useCallback(
@@ -585,13 +527,30 @@ export function useRuntime(props: CodeSandboxProps) {
   }, []);
 
   // -------------------------------------------------------------------------
-  // Git operations
+  // State readers (for imperative handle)
   // -------------------------------------------------------------------------
 
+  const getFiles = useCallback((): FileMap => {
+    return runtimeRef.current?.getCurrentFiles() ?? {};
+  }, []);
+
   const getChangedFiles = useCallback((): FileMap => {
     return runtimeRef.current?.getChangedFiles() ?? {};
   }, []);
 
+  const getFileChanges = useCallback((): Record<string, FileChangeStatus> => {
+    // Read from React state since it's the source of truth for changes
+    return state.fileChanges;
+  }, [state.fileChanges]);
+
+  const getErrors = useCallback((): SandboxError[] => {
+    return state.errors;
+  }, [state.errors]);
+
+  const getState = useCallback((): RuntimeState => {
+    return state;
+  }, [state]);
+
   return {
     state,
     selectedFile,
@@ -601,7 +560,14 @@ export function useRuntime(props: CodeSandboxProps) {
     handleCloseFile,
     handleBrowserError,
     restart,
+    // Imperative methods (exposed via handle)
+    updateFiles,
+    updateFile,
+    getFiles,
     getChangedFiles,
+    getFileChanges,
+    getErrors,
+    getState,
     runtime: runtimeRef,
   };
 }

package/src/index.ts

@@ -19,7 +19,6 @@ export type { WorkbenchView } from "./components/ViewSlider";
 
 // Services
 export { NodepodRuntime } from "./services/runtime";
-export { GitService } from "./services/git";
 
 // Hooks
 export { useRuntime } from "./hooks/useRuntime";
@@ -38,11 +37,8 @@ export type {
   BootProgress,
   RuntimeConfig,
   RuntimeState,
-  GitHubRepo,
-  GitCommitRequest,
-  GitPRRequest,
-  GitPRResult,
   CodeSandboxProps,
+  CodeSandboxHandle,
   FileTreeProps,
   CodeEditorProps,
   TerminalProps,

package/src/services/runtime.ts

@@ -38,7 +38,7 @@ const DBG = "[CodeSandbox:Runtime]";
  * - 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
+ * - Track file modifications for diffing
  * - Provide preview URL for the iframe
  */
 export class NodepodRuntime {