@illuma-ai/code-sandbox 1.1.0 → 1.2.1

package/src/types.ts

@@ -2,7 +2,7 @@
  * @illuma-ai/code-sandbox — Type definitions
  *
  * Core types for the browser-native code sandbox.
- * Covers file maps, runtime states, git operations, and component props.
+ * Covers file maps, runtime states, imperative handle, and component props.
  */
 
 // ---------------------------------------------------------------------------
@@ -138,11 +138,9 @@ export interface RuntimeState {
   files: FileMap;
   /**
    * Baseline file snapshot — the files as they were before the latest
-   * update (initial load, or the version before the last GitHub poll).
-   *
-   * Used by the diff viewer to show what changed. Empty on first load
-   * (everything is "new"), populated after the first file update
-   * (GitHub poll, updateFiles, etc.).
+   * update (via updateFiles). Used by the diff viewer to show what changed.
+   * Empty on first load (everything is "new"), populated after the first
+   * file update.
    */
   originalFiles: FileMap;
   /**
@@ -163,53 +161,117 @@ export interface RuntimeState {
 }
 
 // ---------------------------------------------------------------------------
-// Git (GitHub API integration)
+// Imperative Handle
 // ---------------------------------------------------------------------------
 
-export interface GitHubRepo {
-  owner: string;
-  repo: string;
-  branch?: string; // default: 'main'
-  path?: string; // subdirectory to clone (default: root)
-}
+/**
+ * Imperative handle exposed by CodeSandbox via React.forwardRef.
+ *
+ * This is the primary API for host applications (like Ranger) to
+ * control the sandbox programmatically. The sandbox is a "dumb renderer"
+ * — the host pushes files in and reads state out.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<CodeSandboxHandle>(null);
+ *
+ * // Push files from any source
+ * ref.current?.updateFiles(fileMap);
+ *
+ * // Push a single file (e.g., agent modified one file)
+ * ref.current?.updateFile('server.js', newContent);
+ *
+ * // Read current state
+ * const files = ref.current?.getFiles();
+ * const changes = ref.current?.getChangedFiles();
+ * const errors = ref.current?.getErrors();
+ * ```
+ */
+export interface CodeSandboxHandle {
+  /**
+   * Replace the entire file set. Diffs against current files, writes only
+   * changed files to Nodepod FS, and restarts the server if anything changed.
+   *
+   * The previous file set becomes `originalFiles` for diff tracking.
+   *
+   * @param files - Complete new file set
+   * @param options - Optional: restartServer (default true)
+   */
+  updateFiles: (
+    files: FileMap,
+    options?: { restartServer?: boolean },
+  ) => Promise<void>;
 
-export interface GitCommitRequest {
-  owner: string;
-  repo: string;
-  /** Branch to create for the commit */
-  branch: string;
-  /** Base branch to fork from (default: 'main') */
-  baseBranch?: string;
-  /** Map of file paths to new contents (only changed files) */
-  changes: FileMap;
-  /** Commit message */
-  message: string;
-}
+  /**
+   * Update a single file. Writes to Nodepod FS and updates state.
+   * Does NOT restart the server — call `restart()` manually if needed,
+   * or use `updateFiles()` for bulk updates with auto-restart.
+   *
+   * @param path - File path (e.g., "server.js", "public/index.html")
+   * @param content - New file content
+   */
+  updateFile: (path: string, content: string) => Promise<void>;
 
-export interface GitPRRequest extends GitCommitRequest {
-  /** PR title */
-  title: string;
-  /** PR body/description */
-  body?: string;
-}
+  /**
+   * Force restart the server process. Kills the current process
+   * and re-runs the entry command.
+   */
+  restart: () => Promise<void>;
 
-export interface GitPRResult {
-  number: number;
-  url: string;
-  branch: string;
+  /**
+   * Get the current file map (all files including edits).
+   */
+  getFiles: () => FileMap;
+
+  /**
+   * Get only files that have been modified relative to originalFiles.
+   * Returns a FileMap containing only the changed files.
+   */
+  getChangedFiles: () => FileMap;
+
+  /**
+   * Get the per-file change status map (new/modified/deleted).
+   * Missing keys should be treated as "unchanged".
+   */
+  getFileChanges: () => Record<string, FileChangeStatus>;
+
+  /**
+   * Get all structured errors collected during this session.
+   */
+  getErrors: () => SandboxError[];
+
+  /**
+   * Get the current runtime state snapshot.
+   */
+  getState: () => RuntimeState;
 }
 
 // ---------------------------------------------------------------------------
 // Component Props
 // ---------------------------------------------------------------------------
 
+/**
+ * Props for the CodeSandbox component.
+ *
+ * The sandbox is a pure renderer — it receives files via props and
+ * exposes an imperative handle for programmatic updates. It does NOT
+ * interact with any storage backend directly.
+ *
+ * File sources (for initial load, pick ONE):
+ * - `files` — pass a FileMap directly
+ * - `template` — use a built-in template name (e.g., "fullstack-starter")
+ *
+ * For live updates after mount, use the imperative handle:
+ * ```tsx
+ * const ref = useRef<CodeSandboxHandle>(null);
+ * <CodeSandbox ref={ref} files={initialFiles} />
+ * // Later:
+ * ref.current.updateFiles(newFiles);
+ * ```
+ */
 export interface CodeSandboxProps {
-  /** Pass files directly */
+  /** Pass files directly (from any source) */
   files?: FileMap;
-  /** OR load from GitHub */
-  github?: GitHubRepo;
-  /** GitHub personal access token (for private repos and write-back) */
-  gitToken?: string;
   /** OR use a built-in template name */
   template?: string;
   /** Command to start the dev server (default inferred from package.json or template) */
@@ -220,9 +282,9 @@ export interface CodeSandboxProps {
   env?: Record<string, string>;
 
   // Callbacks
-  /** Fires when a file is modified in the editor */
+  /** Fires when a file is modified in the editor by the user */
   onFileChange?: (path: string, content: string) => void;
-  /** Fires when the dev server is ready */
+  /** Fires when the dev server is ready (initial boot or after restart) */
   onServerReady?: (port: number, url: string) => void;
   /** Fires on boot progress changes */
   onProgress?: (progress: BootProgress) => void;
@@ -238,6 +300,12 @@ export interface CodeSandboxProps {
    * Max 2 auto-fix attempts per error is recommended (see Ranger pattern).
    */
   onSandboxError?: (error: SandboxError) => void;
+  /**
+   * Fires after updateFiles() completes (files written + server restarted).
+   * Useful for the host to know when the sandbox has finished processing
+   * a file push.
+   */
+  onFilesUpdated?: (fileChanges: Record<string, FileChangeStatus>) => void;
 
   // Layout
   /** CSS class name for the root element */

package/dist/services/git.d.ts

@@ -1,57 +0,0 @@
-/**
- * GitService — GitHub API integration for loading and saving project files.
- *
- * Flow:
- * - Clone: GET repo tree → GET file contents → return FileMap
- * - Commit: POST branch → PUT files → POST PR
- *
- * All operations use the GitHub REST API (no git CLI needed).
- * Works entirely in the browser — no server required.
- */
-import type { FileMap, GitCommitRequest, GitHubRepo, GitPRRequest, GitPRResult } from "../types";
-/**
- * GitHub API service for cloning repos and creating PRs.
- *
- * @example
- * ```ts
- * const git = new GitService('ghp_xxxxx');
- * const files = await git.cloneRepo({ owner: 'user', repo: 'my-app' });
- * // ... user edits files ...
- * const pr = await git.createPR({
- *   owner: 'user', repo: 'my-app',
- *   branch: 'sandbox/changes', changes: editedFiles,
- *   message: 'Update from sandbox', title: 'Sandbox changes',
- * });
- * ```
- */
-export declare class GitService {
-    private token;
-    constructor(token: string);
-    /**
-     * Clone a GitHub repository into a flat file map.
-     *
-     * Uses the Git Trees API for a single request to get the full file listing,
-     * then fetches text file contents in parallel batches.
-     *
-     * @param repo - GitHub repository coordinates
-     * @param onProgress - Optional progress callback (0-100)
-     * @returns FileMap of path → content
-     */
-    cloneRepo(repo: GitHubRepo, onProgress?: (percent: number, message: string) => void): Promise<FileMap>;
-    /**
-     * Create a new branch with file changes and open a pull request.
-     *
-     * Steps:
-     * 1. Get the base branch's HEAD SHA
-     * 2. Create a new branch from that SHA
-     * 3. For each changed file, update its contents on the new branch
-     * 4. Create a pull request
-     */
-    createPR(request: GitPRRequest): Promise<GitPRResult>;
-    /**
-     * Commit changes without creating a PR.
-     */
-    commit(request: GitCommitRequest): Promise<string>;
-    /** Fetch with auth headers */
-    private fetch;
-}

package/src/services/git.ts

@@ -1,415 +0,0 @@
-/**
- * GitService — GitHub API integration for loading and saving project files.
- *
- * Flow:
- * - Clone: GET repo tree → GET file contents → return FileMap
- * - Commit: POST branch → PUT files → POST PR
- *
- * All operations use the GitHub REST API (no git CLI needed).
- * Works entirely in the browser — no server required.
- */
-
-import type {
-  FileMap,
-  GitCommitRequest,
-  GitHubRepo,
-  GitPRRequest,
-  GitPRResult,
-} from "../types";
-
-const GITHUB_API = "https://api.github.com";
-
-/** File extensions to treat as text (others are skipped) */
-const TEXT_EXTENSIONS = new Set([
-  ".js",
-  ".jsx",
-  ".ts",
-  ".tsx",
-  ".json",
-  ".html",
-  ".htm",
-  ".css",
-  ".scss",
-  ".sass",
-  ".less",
-  ".md",
-  ".mdx",
-  ".txt",
-  ".yml",
-  ".yaml",
-  ".toml",
-  ".xml",
-  ".svg",
-  ".env",
-  ".gitignore",
-  ".eslintrc",
-  ".prettierrc",
-  ".sh",
-  ".bash",
-  ".zsh",
-  ".py",
-  ".rb",
-  ".go",
-  ".rs",
-  ".java",
-  ".kt",
-  ".c",
-  ".cpp",
-  ".h",
-  ".hpp",
-  ".cs",
-  ".php",
-  ".sql",
-  ".graphql",
-  ".lock",
-  ".mjs",
-  ".cjs",
-  ".mts",
-  ".cts",
-  ".vue",
-  ".svelte",
-  ".astro",
-]);
-
-/** Directories to skip when cloning */
-const SKIP_DIRS = new Set([
-  "node_modules",
-  ".git",
-  "dist",
-  "build",
-  ".next",
-  ".cache",
-  "__pycache__",
-  ".venv",
-  "venv",
-  "coverage",
-  ".nyc_output",
-]);
-
-/** Max file size to fetch (skip large files) */
-const MAX_FILE_SIZE = 500_000; // 500KB
-
-/**
- * GitHub API service for cloning repos and creating PRs.
- *
- * @example
- * ```ts
- * const git = new GitService('ghp_xxxxx');
- * const files = await git.cloneRepo({ owner: 'user', repo: 'my-app' });
- * // ... user edits files ...
- * const pr = await git.createPR({
- *   owner: 'user', repo: 'my-app',
- *   branch: 'sandbox/changes', changes: editedFiles,
- *   message: 'Update from sandbox', title: 'Sandbox changes',
- * });
- * ```
- */
-export class GitService {
-  private token: string;
-
-  constructor(token: string) {
-    this.token = token;
-  }
-
-  // -------------------------------------------------------------------------
-  // Clone: fetch repo files as a FileMap
-  // -------------------------------------------------------------------------
-
-  /**
-   * Clone a GitHub repository into a flat file map.
-   *
-   * Uses the Git Trees API for a single request to get the full file listing,
-   * then fetches text file contents in parallel batches.
-   *
-   * @param repo - GitHub repository coordinates
-   * @param onProgress - Optional progress callback (0-100)
-   * @returns FileMap of path → content
-   */
-  async cloneRepo(
-    repo: GitHubRepo,
-    onProgress?: (percent: number, message: string) => void,
-  ): Promise<FileMap> {
-    const { owner, repo: repoName, branch = "main", path: subPath } = repo;
-
-    onProgress?.(5, "Fetching repository structure...");
-
-    // 1. Get the tree (recursive) for the branch
-    const treeUrl = `${GITHUB_API}/repos/${owner}/${repoName}/git/trees/${branch}?recursive=1`;
-    const treeRes = await this.fetch(treeUrl);
-    const treeData = await treeRes.json();
-
-    if (!treeData.tree) {
-      throw new Error(
-        `Failed to fetch repo tree: ${treeData.message || "Unknown error"}`,
-      );
-    }
-
-    // 2. Filter to text files, skip large/binary/excluded dirs
-    const filesToFetch: Array<{ path: string; sha: string; size: number }> = [];
-
-    for (const item of treeData.tree) {
-      if (item.type !== "blob") {
-        continue;
-      }
-
-      // Apply subPath filter if specified
-      if (subPath && !item.path.startsWith(subPath)) {
-        continue;
-      }
-
-      // Skip excluded directories
-      const parts = item.path.split("/");
-      if (parts.some((p: string) => SKIP_DIRS.has(p))) {
-        continue;
-      }
-
-      // Skip files that are too large
-      if (item.size > MAX_FILE_SIZE) {
-        continue;
-      }
-
-      // Only include text files
-      const ext = "." + item.path.split(".").pop()?.toLowerCase();
-      const basename = parts[parts.length - 1];
-      // Include files with known extensions, dotfiles, or extensionless config files
-      if (
-        TEXT_EXTENSIONS.has(ext) ||
-        basename.startsWith(".") ||
-        !basename.includes(".")
-      ) {
-        filesToFetch.push({ path: item.path, sha: item.sha, size: item.size });
-      }
-    }
-
-    onProgress?.(15, `Found ${filesToFetch.length} files to fetch...`);
-
-    // 3. Fetch file contents in parallel batches
-    const files: FileMap = {};
-    const batchSize = 20;
-
-    for (let i = 0; i < filesToFetch.length; i += batchSize) {
-      const batch = filesToFetch.slice(i, i + batchSize);
-
-      const results = await Promise.all(
-        batch.map(async (file) => {
-          try {
-            const contentUrl = `${GITHUB_API}/repos/${owner}/${repoName}/contents/${file.path}?ref=${branch}`;
-            const res = await this.fetch(contentUrl);
-            const data = await res.json();
-
-            if (data.encoding === "base64" && data.content) {
-              const content = atob(data.content.replace(/\n/g, ""));
-              // Strip subPath prefix if specified
-              const relativePath = subPath
-                ? file.path.replace(new RegExp(`^${subPath}/?`), "")
-                : file.path;
-              return { path: relativePath, content };
-            }
-            return null;
-          } catch {
-            return null;
-          }
-        }),
-      );
-
-      for (const result of results) {
-        if (result) {
-          files[result.path] = result.content;
-        }
-      }
-
-      const percent =
-        15 + Math.round(((i + batch.length) / filesToFetch.length) * 80);
-      onProgress?.(
-        percent,
-        `Fetching files... (${Math.min(i + batchSize, filesToFetch.length)}/${filesToFetch.length})`,
-      );
-    }
-
-    onProgress?.(100, `Loaded ${Object.keys(files).length} files`);
-
-    return files;
-  }
-
-  // -------------------------------------------------------------------------
-  // Commit + PR: write changes back to GitHub
-  // -------------------------------------------------------------------------
-
-  /**
-   * Create a new branch with file changes and open a pull request.
-   *
-   * Steps:
-   * 1. Get the base branch's HEAD SHA
-   * 2. Create a new branch from that SHA
-   * 3. For each changed file, update its contents on the new branch
-   * 4. Create a pull request
-   */
-  async createPR(request: GitPRRequest): Promise<GitPRResult> {
-    const {
-      owner,
-      repo,
-      branch,
-      baseBranch = "main",
-      changes,
-      message,
-      title,
-      body,
-    } = request;
-
-    // 1. Get base branch HEAD SHA
-    const refRes = await this.fetch(
-      `${GITHUB_API}/repos/${owner}/${repo}/git/ref/heads/${baseBranch}`,
-    );
-    const refData = await refRes.json();
-    const baseSha = refData.object.sha;
-
-    // 2. Create new branch
-    await this.fetch(`${GITHUB_API}/repos/${owner}/${repo}/git/refs`, {
-      method: "POST",
-      body: JSON.stringify({
-        ref: `refs/heads/${branch}`,
-        sha: baseSha,
-      }),
-    });
-
-    // 3. Commit each changed file
-    for (const [path, content] of Object.entries(changes)) {
-      // Get current file SHA (if it exists)
-      let fileSha: string | undefined;
-      try {
-        const fileRes = await this.fetch(
-          `${GITHUB_API}/repos/${owner}/${repo}/contents/${path}?ref=${branch}`,
-        );
-        const fileData = await fileRes.json();
-        fileSha = fileData.sha;
-      } catch {
-        // File doesn't exist yet — that's fine, we'll create it
-      }
-
-      await this.fetch(
-        `${GITHUB_API}/repos/${owner}/${repo}/contents/${path}`,
-        {
-          method: "PUT",
-          body: JSON.stringify({
-            message,
-            content: btoa(content),
-            branch,
-            ...(fileSha ? { sha: fileSha } : {}),
-          }),
-        },
-      );
-    }
-
-    // 4. Create pull request
-    const prRes = await this.fetch(
-      `${GITHUB_API}/repos/${owner}/${repo}/pulls`,
-      {
-        method: "POST",
-        body: JSON.stringify({
-          title,
-          body:
-            body ||
-            `Changes from code sandbox.\n\nModified files:\n${Object.keys(
-              changes,
-            )
-              .map((p) => `- ${p}`)
-              .join("\n")}`,
-          head: branch,
-          base: baseBranch,
-        }),
-      },
-    );
-
-    const prData = await prRes.json();
-
-    return {
-      number: prData.number,
-      url: prData.html_url,
-      branch,
-    };
-  }
-
-  /**
-   * Commit changes without creating a PR.
-   */
-  async commit(request: GitCommitRequest): Promise<string> {
-    const {
-      owner,
-      repo,
-      branch,
-      baseBranch = "main",
-      changes,
-      message,
-    } = request;
-
-    // Get base SHA
-    const refRes = await this.fetch(
-      `${GITHUB_API}/repos/${owner}/${repo}/git/ref/heads/${baseBranch}`,
-    );
-    const refData = await refRes.json();
-    const baseSha = refData.object.sha;
-
-    // Create branch (may already exist)
-    try {
-      await this.fetch(`${GITHUB_API}/repos/${owner}/${repo}/git/refs`, {
-        method: "POST",
-        body: JSON.stringify({ ref: `refs/heads/${branch}`, sha: baseSha }),
-      });
-    } catch {
-      // Branch already exists — continue
-    }
-
-    // Commit files
-    for (const [path, content] of Object.entries(changes)) {
-      let fileSha: string | undefined;
-      try {
-        const fileRes = await this.fetch(
-          `${GITHUB_API}/repos/${owner}/${repo}/contents/${path}?ref=${branch}`,
-        );
-        const fileData = await fileRes.json();
-        fileSha = fileData.sha;
-      } catch {
-        // New file
-      }
-
-      await this.fetch(
-        `${GITHUB_API}/repos/${owner}/${repo}/contents/${path}`,
-        {
-          method: "PUT",
-          body: JSON.stringify({
-            message,
-            content: btoa(content),
-            branch,
-            ...(fileSha ? { sha: fileSha } : {}),
-          }),
-        },
-      );
-    }
-
-    return branch;
-  }
-
-  // -------------------------------------------------------------------------
-  // Private
-  // -------------------------------------------------------------------------
-
-  /** Fetch with auth headers */
-  private async fetch(url: string, init?: RequestInit): Promise<Response> {
-    const res = await fetch(url, {
-      ...init,
-      headers: {
-        Authorization: `Bearer ${this.token}`,
-        Accept: "application/vnd.github.v3+json",
-        "Content-Type": "application/json",
-        ...(init?.headers || {}),
-      },
-    });
-
-    if (!res.ok) {
-      const body = await res.text();
-      throw new Error(`GitHub API error ${res.status}: ${body}`);
-    }
-
-    return res;
-  }
-}