@illuma-ai/code-sandbox 1.0.0

package/src/types.ts

@@ -0,0 +1,179 @@
+/**
+ * @illuma-ai/code-sandbox — Type definitions
+ *
+ * Core types for the browser-native code sandbox.
+ * Covers file maps, runtime states, git operations, and component props.
+ */
+
+// ---------------------------------------------------------------------------
+// File System
+// ---------------------------------------------------------------------------
+
+/** A flat map of file paths to their string contents */
+export type FileMap = Record<string, string>;
+
+/** Represents a single file or directory node in the tree */
+export interface FileNode {
+  name: string;
+  path: string;
+  type: "file" | "directory";
+  children?: FileNode[];
+}
+
+// ---------------------------------------------------------------------------
+// Runtime (Nodepod lifecycle)
+// ---------------------------------------------------------------------------
+
+/** Boot stages shown during the loading animation */
+export type BootStage =
+  | "initializing" // Nodepod.boot() in progress
+  | "writing-files" // Writing project files to virtual FS
+  | "installing" // npm install running
+  | "starting" // Entry command executing (e.g., node server.js)
+  | "ready" // Server is listening, preview iframe can load
+  | "error"; // Something failed
+
+export interface BootProgress {
+  stage: BootStage;
+  message: string;
+  /** 0-100 percent, approximate */
+  percent: number;
+}
+
+/** Configuration for the Nodepod runtime */
+export interface RuntimeConfig {
+  /** Project files to write into the virtual filesystem */
+  files: FileMap;
+  /** Command to start the dev server, e.g. "node server.js" */
+  entryCommand: string;
+  /** Working directory inside Nodepod (default: "/app") */
+  workdir?: string;
+  /** Environment variables passed to processes */
+  env?: Record<string, string>;
+  /** Port to watch for server readiness (default: 3000) */
+  port?: number;
+}
+
+/** State exposed by the runtime to UI components */
+export interface RuntimeState {
+  status: BootStage;
+  progress: BootProgress;
+  /** URL for the preview iframe once server is ready, e.g. "/__virtual__/3000/" */
+  previewUrl: string | null;
+  /** All terminal output lines (stdout + stderr) */
+  terminalOutput: string[];
+  /** Current files in the virtual FS (may differ from original after edits) */
+  files: FileMap;
+  /** Error message if status is 'error' */
+  error: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Git (GitHub API integration)
+// ---------------------------------------------------------------------------
+
+export interface GitHubRepo {
+  owner: string;
+  repo: string;
+  branch?: string; // default: 'main'
+  path?: string; // subdirectory to clone (default: root)
+}
+
+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;
+}
+
+export interface GitPRRequest extends GitCommitRequest {
+  /** PR title */
+  title: string;
+  /** PR body/description */
+  body?: string;
+}
+
+export interface GitPRResult {
+  number: number;
+  url: string;
+  branch: string;
+}
+
+// ---------------------------------------------------------------------------
+// Component Props
+// ---------------------------------------------------------------------------
+
+export interface CodeSandboxProps {
+  /** Pass files directly */
+  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) */
+  entryCommand?: string;
+  /** Port the server listens on (default: 3000) */
+  port?: number;
+  /** Environment variables */
+  env?: Record<string, string>;
+
+  // Callbacks
+  /** Fires when a file is modified in the editor */
+  onFileChange?: (path: string, content: string) => void;
+  /** Fires when the dev server is ready */
+  onServerReady?: (port: number, url: string) => void;
+  /** Fires on boot progress changes */
+  onProgress?: (progress: BootProgress) => void;
+  /** Fires on errors */
+  onError?: (error: string) => void;
+
+  // Layout
+  /** CSS class name for the root element */
+  className?: string;
+  /** Height of the sandbox (default: '100vh') */
+  height?: string;
+}
+
+export interface FileTreeProps {
+  files: FileNode[];
+  selectedFile: string | null;
+  onSelectFile: (path: string) => void;
+  onCreateFile?: (path: string) => void;
+  onCreateFolder?: (path: string) => void;
+  onDeleteFile?: (path: string) => void;
+  onRenameFile?: (oldPath: string, newPath: string) => void;
+}
+
+export interface CodeEditorProps {
+  files: FileMap;
+  activeFile: string | null;
+  openFiles: string[];
+  onSelectFile: (path: string) => void;
+  onCloseFile: (path: string) => void;
+  onFileChange: (path: string, content: string) => void;
+  readOnly?: boolean;
+}
+
+export interface TerminalProps {
+  output: string[];
+  className?: string;
+}
+
+export interface PreviewProps {
+  url: string | null;
+  className?: string;
+  onRefresh?: () => void;
+}
+
+export interface BootOverlayProps {
+  progress: BootProgress;
+  className?: string;
+}