sandlot 0.1.1 → 0.1.3

package/src/fs.ts

@@ -23,9 +23,12 @@ interface ReadFileOptions {
 }
 
 /**
- * Options for writing files
+ * Options for writing files.
+ * Note: In this browser-based filesystem, content is stored as-is.
+ * The encoding option is accepted for API compatibility but not used.
  */
 interface WriteFileOptions {
+  /** Accepted for API compatibility but not used - content is stored as-is */
   encoding?: BufferEncoding;
 }
 
@@ -45,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>();
 
@@ -136,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",
@@ -151,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) });
-    }
-
-    await this.promisifyTransaction(tx);
-    this.dirty = false;
-    return true;
-  }
-
-  /**
-   * Reload entries from IndexedDB, discarding unsaved changes
-   */
-  async reload(): Promise<void> {
-    if (!this.db) {
-      return;
+      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}`;
+        }
+      }
     }
-
-    this.entries = await IndexedDbFs.loadEntries(this.db);
-    this.dirty = false;
-  }
-
-  /**
-   * Check if there are unsaved changes
-   */
-  isDirty(): boolean {
-    return this.dirty;
+    
+    return files;
   }
 
   /**
@@ -217,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(
@@ -276,7 +236,7 @@ export class IndexedDbFs implements IFileSystem {
   async writeFile(
     path: string,
     content: FileContent,
-    options?: WriteFileOptions | BufferEncoding
+    _options?: WriteFileOptions | BufferEncoding
   ): Promise<void> {
     const normalizedPath = this.normalizePath(path);
     this.checkSizeLimit(content);
@@ -293,7 +253,6 @@ export class IndexedDbFs implements IFileSystem {
       mode: existing?.mode ?? DEFAULT_FILE_MODE,
       mtime: new Date(),
     });
-    this.dirty = true;
   }
 
   async appendFile(
@@ -372,7 +331,6 @@ export class IndexedDbFs implements IFileSystem {
       mode: DEFAULT_DIR_MODE,
       mtime: new Date(),
     });
-    this.dirty = true;
   }
 
   async readdir(path: string): Promise<string[]> {
@@ -461,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> {
@@ -494,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> {
@@ -529,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 {
@@ -568,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> {
@@ -586,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> {
@@ -613,7 +564,6 @@ export class IndexedDbFs implements IFileSystem {
       mode: entry.mode,
       mtime: new Date(),
     });
-    this.dirty = true;
   }
 
   async readlink(path: string): Promise<string> {
@@ -677,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 {
@@ -715,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 {
@@ -815,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)
@@ -830,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);
@@ -843,93 +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();
-    });
-  }
 }
 
 /**
- * Factory function matching the FileSystemFactory type
+ * Create an in-memory filesystem.
+ * 
+ * @param initialFiles - Optional initial files to populate the filesystem
+ * @returns A new Filesystem instance
  */
-export function createIndexedDbFs(initialFiles?: InitialFiles): IFileSystem {
-  // For sync factory usage, return in-memory version
-  // Use IndexedDbFs.create() for async with persistence
-  return IndexedDbFs.createInMemory({ initialFiles });
+export function createFilesystem(options?: FilesystemOptions): Filesystem {
+  return Filesystem.create(options);
 }
+

package/src/index.ts

@@ -1,3 +1,20 @@
+// =============================================================================
+// Browser polyfills - inject before anything else loads
+// =============================================================================
+
+// Some dependencies (like just-bash) reference Node.js globals.
+// Provide shims so they work in the browser without user configuration.
+if (typeof window !== "undefined" && typeof globalThis.process === "undefined") {
+  (globalThis as Record<string, unknown>).process = {
+    env: {},
+    platform: "browser",
+    version: "v20.0.0",
+    browser: true,
+    cwd: () => "/",
+    nextTick: (fn: () => void) => setTimeout(fn, 0),
+  };
+}
+
 // =============================================================================
 // CORE API - Most users only need these
 // =============================================================================
@@ -8,19 +25,23 @@
 
 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)
@@ -51,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";
 
@@ -114,9 +136,9 @@ export {
 // -----------------------------------------------------------------------------
 
 export {
-  IndexedDbFs,
-  createIndexedDbFs,
-  type IndexedDbFsOptions,
+  Filesystem,
+  createFilesystem,
+  type FilesystemOptions,
 } from "./fs";
 
 export type { IFileSystem, FsEntry } from "just-bash/browser";
@@ -146,4 +168,4 @@ export {
   type RunContext,
   type RunOptions,
   type RunResult,
-} from "./commands";
+} from "./commands/index";

package/src/internal.ts

@@ -112,5 +112,8 @@ export { formatEsbuildMessages } from "./commands";
 // BuildEmitter (for custom build event handling)
 // =============================================================================
 
-// Note: BuildEmitter is currently defined inline in sandbox.ts and sandbox-manager.ts
-// If needed externally, it should be extracted to a separate module.
+/**
+ * Build event emitter for sandbox environments.
+ * Use this for custom build event handling in advanced use cases.
+ */
+export { BuildEmitter } from "./build-emitter";