sandlot 0.1.2 → 0.1.4

package/src/commands/types.ts

@@ -0,0 +1,172 @@
+/**
+ * Types and utilities for sandbox bash commands.
+ */
+
+import type { IFileSystem } from "just-bash/browser";
+import type { BundleResult } from "../bundler";
+import type { TypesCache } from "../packages";
+
+/**
+ * The result of a successful build, including the bundle and loaded module.
+ */
+export interface BuildOutput {
+  /**
+   * The compiled bundle (code, metadata, etc.)
+   */
+  bundle: BundleResult;
+
+  /**
+   * The loaded module exports.
+   * If validation was provided, this is the validated module.
+   */
+  module: Record<string, unknown>;
+}
+
+/**
+ * Validation function type for module validation.
+ * Takes the raw module exports and returns validated exports (or throws).
+ */
+export type ValidateFn = (module: Record<string, unknown>) => Record<string, unknown>;
+
+/**
+ * Dependencies required by command factories
+ */
+export interface CommandDeps {
+  /**
+   * The virtual filesystem to operate on
+   */
+  fs: IFileSystem;
+
+  /**
+   * Pre-loaded TypeScript lib files for type checking
+   */
+  libFiles: Map<string, string>;
+
+  /**
+   * Path to tsconfig.json in the virtual filesystem
+   */
+  tsconfigPath: string;
+
+  /**
+   * Callback invoked when a build succeeds (after loading and validation).
+   */
+  onBuild?: (result: BuildOutput) => void | Promise<void>;
+
+  /**
+   * Getter for the current validation function.
+   * Called during build to check if validation should be performed.
+   */
+  getValidation?: () => ValidateFn | null;
+
+  /**
+   * Cache for package type definitions.
+   * When provided, avoids redundant network fetches for packages
+   * that have already been installed in other sandboxes.
+   */
+  typesCache?: TypesCache;
+
+  /**
+   * Options for the `run` command
+   */
+  runOptions?: RunOptions;
+
+  /**
+   * Module IDs that should be resolved from the host's SharedModuleRegistry
+   * instead of esm.sh CDN. The host must have registered these modules.
+   * 
+   * Example: ['react', 'react-dom/client']
+   */
+  sharedModules?: string[];
+}
+
+/**
+ * Runtime context passed to the `main()` function when code is executed.
+ * This provides sandboxed code with access to sandbox capabilities.
+ */
+export interface RunContext {
+  /**
+   * The virtual filesystem - read/write files within the sandbox
+   */
+  fs: IFileSystem;
+
+  /**
+   * Environment variables (configurable per-sandbox)
+   */
+  env: Record<string, string>;
+
+  /**
+   * Command-line arguments passed to `run`
+   */
+  args: string[];
+
+  /**
+   * Explicit logging function (alternative to console.log)
+   */
+  log: (...args: unknown[]) => void;
+
+  /**
+   * Explicit error logging function (alternative to console.error)
+   */
+  error: (...args: unknown[]) => void;
+}
+
+/**
+ * Options for configuring the `run` command behavior
+ */
+export interface RunOptions {
+  /**
+   * Environment variables available via ctx.env
+   */
+  env?: Record<string, string>;
+
+  /**
+   * Maximum execution time in milliseconds (default: 30000 = 30s)
+   * Set to 0 to disable timeout.
+   */
+  timeout?: number;
+
+  /**
+   * Whether to skip type checking before running (default: false)
+   */
+  skipTypecheck?: boolean;
+}
+
+/**
+ * Result of running code via the `run` command
+ */
+export interface RunResult {
+  /**
+   * Captured console output (log, warn, error)
+   */
+  logs: string[];
+
+  /**
+   * Return value from main() if present
+   */
+  returnValue?: unknown;
+
+  /**
+   * Execution time in milliseconds
+   */
+  executionTimeMs: number;
+}
+
+/**
+ * Format esbuild messages (warnings/errors) for display
+ */
+export function formatEsbuildMessages(
+  messages: { text: string; location?: { file?: string; line?: number; column?: number } | null }[]
+): string {
+  if (messages.length === 0) return "";
+
+  return messages
+    .map((msg) => {
+      if (msg.location) {
+        const { file, line, column } = msg.location;
+        const loc = file ? `${file}${line ? `:${line}` : ""}${column ? `:${column}` : ""}` : "";
+        return loc ? `${loc}: ${msg.text}` : msg.text;
+      }
+      return msg.text;
+    })
+    .join("\n");
+}

package/src/fs.ts

@@ -48,85 +48,54 @@ const DEFAULT_SYMLINK_MODE = 0o777;
 const DEFAULT_MAX_SIZE_BYTES = 50 * 1024 * 1024; // 50MB default limit
 
 /**
- * Options for creating an IndexedDbFs instance
+ * Options for creating a Filesystem instance
  */
-export interface IndexedDbFsOptions {
-  /** Database name in IndexedDB */
-  dbName?: string;
+export interface FilesystemOptions {
   /** Maximum total size in bytes (default: 50MB) */
   maxSizeBytes?: number;
-  /** Initial files to populate (only used if DB is empty) */
+  /** Initial files to populate */
   initialFiles?: InitialFiles;
 }
 
 /**
- * In-memory filesystem with IndexedDB persistence.
- * All operations are fast (in-memory), persistence is manual via save().
+ * In-memory virtual filesystem for sandlot sandboxes.
+ * 
+ * All operations are synchronous in-memory. Use `getFiles()` to export
+ * the current state for persistence, and `initialFiles` to restore.
+ * 
+ * @example
+ * ```ts
+ * // Create filesystem
+ * const fs = Filesystem.create({ initialFiles: { '/src/index.ts': 'export const x = 1;' } });
+ * 
+ * // Use filesystem
+ * await fs.writeFile('/src/app.ts', 'console.log("hello")');
+ * 
+ * // Export for persistence
+ * const files = fs.getFiles();
+ * localStorage.setItem('my-project', JSON.stringify(files));
+ * 
+ * // Later, restore
+ * const saved = JSON.parse(localStorage.getItem('my-project'));
+ * const fs2 = Filesystem.create({ initialFiles: saved });
+ * ```
  */
-export class IndexedDbFs implements IFileSystem {
+export class Filesystem implements IFileSystem {
   private entries: Map<string, FsEntry>;
-  private db: IDBDatabase | null = null;
-  private dbName: string;
   private maxSizeBytes: number;
-  private dirty = false;
 
   private constructor(
     entries: Map<string, FsEntry>,
-    db: IDBDatabase | null,
-    dbName: string,
     maxSizeBytes: number
   ) {
     this.entries = entries;
-    this.db = db;
-    this.dbName = dbName;
     this.maxSizeBytes = maxSizeBytes;
   }
 
   /**
-   * Create and initialize a new IndexedDbFs instance
+   * Create a new Filesystem instance
    */
-  static async create(options: IndexedDbFsOptions = {}): Promise<IndexedDbFs> {
-    const dbName = options.dbName ?? "sandlot-fs";
-    const maxSizeBytes = options.maxSizeBytes ?? DEFAULT_MAX_SIZE_BYTES;
-
-    const db = await IndexedDbFs.openDatabase(dbName);
-    const entries = await IndexedDbFs.loadEntries(db);
-
-    // If empty and initialFiles provided, populate
-    if (entries.size === 0) {
-      // Always ensure root exists
-      entries.set("/", {
-        type: "directory",
-        mode: DEFAULT_DIR_MODE,
-        mtime: new Date(),
-      });
-
-      if (options.initialFiles) {
-        for (const [path, value] of Object.entries(options.initialFiles)) {
-          const normalizedPath = IndexedDbFs.normalizePath(path);
-          const init = IndexedDbFs.parseFileInit(value);
-
-          // Ensure parent directories exist
-          IndexedDbFs.ensureParentDirs(entries, normalizedPath);
-
-          entries.set(normalizedPath, {
-            type: "file",
-            content: init.content,
-            mode: init.mode ?? DEFAULT_FILE_MODE,
-            mtime: init.mtime ?? new Date(),
-          });
-        }
-      }
-    }
-
-    const fs = new IndexedDbFs(entries, db, dbName, maxSizeBytes);
-    return fs;
-  }
-
-  /**
-   * Create an in-memory only instance (no IndexedDB)
-   */
-  static createInMemory(options: Omit<IndexedDbFsOptions, "dbName"> = {}): IndexedDbFs {
+  static create(options: FilesystemOptions = {}): Filesystem {
     const maxSizeBytes = options.maxSizeBytes ?? DEFAULT_MAX_SIZE_BYTES;
     const entries = new Map<string, FsEntry>();
 
@@ -139,11 +108,11 @@ export class IndexedDbFs implements IFileSystem {
 
     if (options.initialFiles) {
       for (const [path, value] of Object.entries(options.initialFiles)) {
-        const normalizedPath = IndexedDbFs.normalizePath(path);
-        const init = IndexedDbFs.parseFileInit(value);
+        const normalizedPath = Filesystem.normalizePath(path);
+        const init = Filesystem.parseFileInit(value);
 
         // Ensure parent directories exist
-        IndexedDbFs.ensureParentDirs(entries, normalizedPath);
+        Filesystem.ensureParentDirs(entries, normalizedPath);
 
         entries.set(normalizedPath, {
           type: "file",
@@ -154,52 +123,50 @@ export class IndexedDbFs implements IFileSystem {
       }
     }
 
-    return new IndexedDbFs(entries, null, "", maxSizeBytes);
+    return new Filesystem(entries, maxSizeBytes);
   }
 
-  // ============ Persistence Methods ============
+  // ============ State Export ============
 
   /**
-   * Save all entries to IndexedDB
-   * @returns true if saved, false if no db or not dirty
+   * Get all files as a serializable object.
+   * 
+   * Returns a Record<string, string> that can be JSON-serialized and
+   * used as `initialFiles` when creating a new filesystem.
+   * 
+   * Note: Only includes files, not directories (directories are
+   * automatically created from file paths). Binary files are 
+   * base64-encoded with a `data:` prefix.
+   * 
+   * @example
+   * ```ts
+   * const files = fs.getFiles();
+   * // { '/src/index.ts': 'export const x = 1;', '/package.json': '{"name":"app"}' }
+   * 
+   * // Persist however you want
+   * localStorage.setItem('project', JSON.stringify(files));
+   * 
+   * // Restore later
+   * const saved = JSON.parse(localStorage.getItem('project'));
+   * const fs2 = Filesystem.create({ initialFiles: saved });
+   * ```
    */
-  async save(): Promise<boolean> {
-    if (!this.db || !this.dirty) {
-      return false;
-    }
-
-    const tx = this.db.transaction("entries", "readwrite");
-    const store = tx.objectStore("entries");
-
-    // Clear and rewrite all entries
-    await this.promisifyRequest(store.clear());
-
+  getFiles(): Record<string, string> {
+    const files: Record<string, string> = {};
+    
     for (const [path, entry] of this.entries) {
-      store.put({ path, entry: this.serializeEntry(entry) });
+      if (entry.type === "file") {
+        if (typeof entry.content === "string") {
+          files[path] = entry.content;
+        } else {
+          // Binary content - base64 encode with data URI prefix
+          const base64 = this.encodeBase64(entry.content);
+          files[path] = `data:application/octet-stream;base64,${base64}`;
+        }
+      }
     }
-
-    await this.promisifyTransaction(tx);
-    this.dirty = false;
-    return true;
-  }
-
-  /**
-   * Reload entries from IndexedDB, discarding unsaved changes
-   */
-  async reload(): Promise<void> {
-    if (!this.db) {
-      return;
-    }
-
-    this.entries = await IndexedDbFs.loadEntries(this.db);
-    this.dirty = false;
-  }
-
-  /**
-   * Check if there are unsaved changes
-   */
-  isDirty(): boolean {
-    return this.dirty;
+    
+    return files;
   }
 
   /**
@@ -220,16 +187,6 @@ export class IndexedDbFs implements IFileSystem {
     return size;
   }
 
-  /**
-   * Close the database connection
-   */
-  close(): void {
-    if (this.db) {
-      this.db.close();
-      this.db = null;
-    }
-  }
-
   // ============ IFileSystem Implementation ============
 
   async readFile(
@@ -296,7 +253,6 @@ export class IndexedDbFs implements IFileSystem {
       mode: existing?.mode ?? DEFAULT_FILE_MODE,
       mtime: new Date(),
     });
-    this.dirty = true;
   }
 
   async appendFile(
@@ -375,7 +331,6 @@ export class IndexedDbFs implements IFileSystem {
       mode: DEFAULT_DIR_MODE,
       mtime: new Date(),
     });
-    this.dirty = true;
   }
 
   async readdir(path: string): Promise<string[]> {
@@ -464,7 +419,6 @@ export class IndexedDbFs implements IFileSystem {
     }
 
     this.entries.delete(normalizedPath);
-    this.dirty = true;
   }
 
   async cp(src: string, dest: string, options?: CpOptions): Promise<void> {
@@ -497,8 +451,6 @@ export class IndexedDbFs implements IFileSystem {
       this.ensureParentDirs(destPath);
       this.entries.set(destPath, this.cloneEntry(entry));
     }
-
-    this.dirty = true;
   }
 
   async mv(src: string, dest: string): Promise<void> {
@@ -532,8 +484,6 @@ export class IndexedDbFs implements IFileSystem {
       this.entries.delete(srcPath);
       this.entries.set(destPath, entry);
     }
-
-    this.dirty = true;
   }
 
   resolvePath(base: string, path: string): string {
@@ -571,7 +521,6 @@ export class IndexedDbFs implements IFileSystem {
 
     entry.mode = mode;
     entry.mtime = new Date();
-    this.dirty = true;
   }
 
   async symlink(target: string, linkPath: string): Promise<void> {
@@ -589,7 +538,6 @@ export class IndexedDbFs implements IFileSystem {
       mode: DEFAULT_SYMLINK_MODE,
       mtime: new Date(),
     });
-    this.dirty = true;
   }
 
   async link(existingPath: string, newPath: string): Promise<void> {
@@ -616,7 +564,6 @@ export class IndexedDbFs implements IFileSystem {
       mode: entry.mode,
       mtime: new Date(),
     });
-    this.dirty = true;
   }
 
   async readlink(path: string): Promise<string> {
@@ -680,13 +627,12 @@ export class IndexedDbFs implements IFileSystem {
 
     // Update mtime (atime is ignored as per interface docs, kept for API compatibility)
     entry.mtime = mtime;
-    this.dirty = true;
   }
 
   // ============ Private Helpers ============
 
   private normalizePath(path: string): string {
-    return IndexedDbFs.normalizePath(path);
+    return Filesystem.normalizePath(path);
   }
 
   private static normalizePath(path: string): string {
@@ -718,8 +664,7 @@ export class IndexedDbFs implements IFileSystem {
   }
 
   private ensureParentDirs(path: string): void {
-    IndexedDbFs.ensureParentDirs(this.entries, path);
-    this.dirty = true;
+    Filesystem.ensureParentDirs(this.entries, path);
   }
 
   private static ensureParentDirs(entries: Map<string, FsEntry>, path: string): void {
@@ -818,11 +763,7 @@ export class IndexedDbFs implements IFileSystem {
       return new TextDecoder("utf-8").decode(buffer);
     }
     if (encoding === "base64") {
-      let binary = "";
-      for (let i = 0; i < buffer.byteLength; i++) {
-        binary += String.fromCharCode(buffer[i]!);
-      }
-      return btoa(binary);
+      return this.encodeBase64(buffer);
     }
     if (encoding === "hex") {
       return Array.from(buffer)
@@ -833,6 +774,14 @@ export class IndexedDbFs implements IFileSystem {
     return new TextDecoder("utf-8").decode(buffer);
   }
 
+  private encodeBase64(buffer: Uint8Array): string {
+    let binary = "";
+    for (let i = 0; i < buffer.byteLength; i++) {
+      binary += String.fromCharCode(buffer[i]!);
+    }
+    return btoa(binary);
+  }
+
   private concatBuffers(a: Uint8Array, b: Uint8Array): Uint8Array {
     const result = new Uint8Array(a.byteLength + b.byteLength);
     result.set(a, 0);
@@ -846,103 +795,15 @@ export class IndexedDbFs implements IFileSystem {
     }
     return value;
   }
-
-  // ============ IndexedDB Helpers ============
-
-  private static openDatabase(dbName: string): Promise<IDBDatabase> {
-    return new Promise((resolve, reject) => {
-      const request = indexedDB.open(dbName, 1);
-
-      request.onerror = () => reject(request.error);
-      request.onsuccess = () => resolve(request.result);
-
-      request.onupgradeneeded = (event) => {
-        const db = (event.target as IDBOpenDBRequest).result;
-        if (!db.objectStoreNames.contains("entries")) {
-          db.createObjectStore("entries", { keyPath: "path" });
-        }
-      };
-    });
-  }
-
-  private static async loadEntries(db: IDBDatabase): Promise<Map<string, FsEntry>> {
-    const tx = db.transaction("entries", "readonly");
-    const store = tx.objectStore("entries");
-
-    return new Promise((resolve, reject) => {
-      const request = store.getAll();
-      request.onerror = () => reject(request.error);
-      request.onsuccess = () => {
-        const entries = new Map<string, FsEntry>();
-        for (const record of request.result) {
-          entries.set(record.path, IndexedDbFs.deserializeEntry(record.entry));
-        }
-        resolve(entries);
-      };
-    });
-  }
-
-  private serializeEntry(entry: FsEntry): object {
-    if (entry.type === "file" && entry.content instanceof Uint8Array) {
-      return {
-        ...entry,
-        content: Array.from(entry.content),
-        contentType: "uint8array",
-        mtime: entry.mtime.toISOString(),
-      };
-    }
-    return {
-      ...entry,
-      mtime: entry.mtime.toISOString(),
-    };
-  }
-
-  private static deserializeEntry(data: any): FsEntry {
-    const mtime = new Date(data.mtime);
-
-    if (data.type === "file") {
-      let content = data.content;
-      if (data.contentType === "uint8array" && Array.isArray(content)) {
-        content = new Uint8Array(content);
-      }
-      return { type: "file", content, mode: data.mode, mtime };
-    }
-    if (data.type === "symlink") {
-      return { type: "symlink", target: data.target, mode: data.mode, mtime };
-    }
-    return { type: "directory", mode: data.mode, mtime };
-  }
-
-  private promisifyRequest<T>(request: IDBRequest<T>): Promise<T> {
-    return new Promise((resolve, reject) => {
-      request.onerror = () => reject(request.error);
-      request.onsuccess = () => resolve(request.result);
-    });
-  }
-
-  private promisifyTransaction(tx: IDBTransaction): Promise<void> {
-    return new Promise((resolve, reject) => {
-      tx.onerror = () => reject(tx.error);
-      tx.oncomplete = () => resolve();
-    });
-  }
 }
 
 /**
- * Synchronous factory function for creating an in-memory filesystem.
- * 
- * Note: For IndexedDB-backed persistence, use `IndexedDbFs.create()` instead.
- * This function exists for compatibility with sync factory patterns.
+ * Create an in-memory filesystem.
  * 
  * @param initialFiles - Optional initial files to populate the filesystem
- * @returns An in-memory filesystem (no persistence)
+ * @returns A new Filesystem instance
  */
-export function createInMemoryFs(initialFiles?: InitialFiles): IFileSystem {
-  return IndexedDbFs.createInMemory({ initialFiles });
+export function createFilesystem(options?: FilesystemOptions): Filesystem {
+  return Filesystem.create(options);
 }
 
-/**
- * @deprecated Use `createInMemoryFs` for in-memory filesystems or 
- * `IndexedDbFs.create()` for IndexedDB-backed persistence.
- */
-export const createIndexedDbFs = createInMemoryFs;

package/src/index.ts

@@ -25,19 +25,23 @@ if (typeof window !== "undefined" && typeof globalThis.process === "undefined")
 
 export {
   createSandbox,
-  createInMemorySandbox,
   type Sandbox,
   type SandboxOptions,
+  type SandboxState,
+  type SandboxBashOptions,
 } from "./sandbox";
 
+// -----------------------------------------------------------------------------
+// Builder (recommended for agent workflows)
+// -----------------------------------------------------------------------------
+
 export {
-  SandboxManager,
-  createSandboxManager,
-  type ManagedSandbox,
-  type ManagedSandboxOptions,
-  type SandboxManagerStats,
-  type SandboxManagerOptions,
-} from "./sandbox-manager";
+  createBuilder,
+  type BuildResult,
+  type CreateBuilderOptions,
+  type BuildCallOptions,
+  type BuilderFn,
+} from "./builder";
 
 // -----------------------------------------------------------------------------
 // Module Loading (use after build to get exports)
@@ -68,6 +72,7 @@ export {
 // -----------------------------------------------------------------------------
 
 export type { BundleResult } from "./bundler";
+export type { BuildOutput, ValidateFn } from "./commands/types";
 export type { TypecheckResult, Diagnostic } from "./typechecker";
 export type { PackageManifest, InstallResult } from "./packages";
 
@@ -131,9 +136,9 @@ export {
 // -----------------------------------------------------------------------------
 
 export {
-  IndexedDbFs,
-  createInMemoryFs,
-  type IndexedDbFsOptions,
+  Filesystem,
+  createFilesystem,
+  type FilesystemOptions,
 } from "./fs";
 
 export type { IFileSystem, FsEntry } from "just-bash/browser";
@@ -163,4 +168,4 @@ export {
   type RunContext,
   type RunOptions,
   type RunResult,
-} from "./commands";
+} from "./commands/index";