sandlot 0.1.2 → 0.1.3

package/src/sandbox-manager.ts

@@ -1,409 +0,0 @@
-/**
- * SandboxManager - Manages shared resources for multiple concurrent sandboxes.
- *
- * When running many sandboxes concurrently (e.g., for multiple AI agents),
- * this manager ensures heavy resources are loaded once and shared:
- *
- * - TypeScript lib files (~5MB) - loaded once, shared across all sandboxes
- * - esbuild WASM (~10MB) - already singleton, but pre-initialized here
- *
- * Usage:
- * ```ts
- * const manager = await createSandboxManager();
- *
- * // Create multiple sandboxes - all share the same libs and bundler
- * const sandbox1 = await manager.createSandbox({ ... });
- * const sandbox2 = await manager.createSandbox({ ... });
- *
- * // ... use sandboxes ...
- *
- * // Clean up
- * manager.destroyAll();
- * ```
- */
-
-import { Bash, defineCommand } from "just-bash/browser";
-import { IndexedDbFs, type IndexedDbFsOptions } from "./fs";
-import { type BundleResult } from "./bundler";
-import { getDefaultBrowserLibs } from "./ts-libs";
-import {
-  createSharedResources,
-  type SharedResources,
-  type SharedResourcesOptions,
-} from "./shared-resources";
-import { createDefaultCommands, type CommandDeps } from "./commands";
-import { BuildEmitter } from "./build-emitter";
-import type { Sandbox } from "./sandbox";
-
-/**
- * Options for creating a sandbox via the manager
- */
-export interface ManagedSandboxOptions {
-  /**
-   * Unique identifier for this sandbox.
-   * 
-   * Also used as the IndexedDB database name if `fsOptions.dbName` is not provided
-   * and `inMemory` is false. If both are provided, `fsOptions.dbName` takes precedence.
-   * 
-   * @default Auto-generated as "sandbox-1", "sandbox-2", etc.
-   */
-  id?: string;
-
-  /**
-   * Options for the IndexedDB filesystem.
-   * 
-   * Note: `fsOptions.dbName` takes precedence over `id` for the database name.
-   * If neither is provided, the auto-generated `id` is used.
-   */
-  fsOptions?: IndexedDbFsOptions;
-
-  /**
-   * Initial files to populate the filesystem with
-   */
-  initialFiles?: Record<string, string>;
-
-  /**
-   * Path to tsconfig.json in the virtual filesystem.
-   * Default: "/tsconfig.json"
-   */
-  tsconfigPath?: string;
-
-  /**
-   * Callback invoked when a build succeeds.
-   * Receives the bundle result with the compiled code.
-   */
-  onBuild?: (result: BundleResult) => void | Promise<void>;
-
-  /**
-   * Additional custom commands to add to the bash environment
-   */
-  customCommands?: ReturnType<typeof defineCommand>[];
-
-  /**
-   * If true, use in-memory filesystem only (no IndexedDB persistence).
-   * Default: true
-   */
-  inMemory?: boolean;
-
-  /**
-   * Module IDs that should be resolved from the host's SharedModuleRegistry
-   * instead of esm.sh CDN. Overrides manager-level sharedModules for this sandbox.
-   * 
-   * @see SandboxOptions.sharedModules for full documentation
-   */
-  sharedModules?: string[];
-}
-
-/**
- * A sandbox instance managed by the SandboxManager.
- * 
- * Extends the base Sandbox interface with an `id` property for
- * identification within the manager. This ensures ManagedSandbox
- * has full feature parity with Sandbox.
- */
-export interface ManagedSandbox extends Sandbox {
-  /**
-   * Unique identifier for this sandbox within the manager.
-   */
-  id: string;
-}
-
-/**
- * Statistics about the sandbox manager
- */
-export interface SandboxManagerStats {
-  /**
-   * Whether shared resources have been initialized
-   */
-  initialized: boolean;
-
-  /**
-   * Number of currently active sandboxes
-   */
-  activeSandboxes: number;
-
-  /**
-   * Number of TypeScript lib files loaded
-   */
-  libFilesCount: number;
-
-  /**
-   * IDs of active sandboxes
-   */
-  sandboxIds: string[];
-}
-
-/**
- * Options for creating a SandboxManager
- */
-export interface SandboxManagerOptions extends SharedResourcesOptions {
-  /**
-   * TypeScript libs to load. Defaults to browser libs (ES2020 + DOM).
-   */
-  libs?: string[];
-
-  /**
-   * Default shared modules for all sandboxes created by this manager.
-   * Individual sandboxes can override with their own sharedModules option.
-   * 
-   * Module IDs that should be resolved from the host's SharedModuleRegistry
-   * instead of esm.sh CDN. The host must have registered these modules
-   * using `registerSharedModules()` before loading dynamic code.
-   * 
-   * @example
-   * ```ts
-   * const manager = await createSandboxManager({
-   *   sharedModules: ['react', 'react-dom/client'],
-   * });
-   * ```
-   */
-  sharedModules?: string[];
-}
-
-/**
- * Manager for creating and managing multiple sandboxes with shared resources.
- */
-export class SandboxManager {
-  private resources: SharedResources | null = null;
-  private sandboxes: Map<string, ManagedSandbox> = new Map();
-  private initialized = false;
-  private initPromise: Promise<void> | null = null;
-  private nextId = 1;
-  private options: SandboxManagerOptions;
-
-  constructor(options: SandboxManagerOptions = {}) {
-    this.options = {
-      libs: options.libs ?? getDefaultBrowserLibs(),
-      ...options,
-    };
-  }
-
-  /**
-   * Initialize shared resources (libs and bundler).
-   * Called automatically on first sandbox creation, but can be called
-   * explicitly to pre-warm.
-   */
-  async initialize(): Promise<void> {
-    if (this.initialized) return;
-
-    if (this.initPromise) {
-      await this.initPromise;
-      return;
-    }
-
-    this.initPromise = this.doInitialize();
-    await this.initPromise;
-    this.initialized = true;
-  }
-
-  private async doInitialize(): Promise<void> {
-    this.resources = await createSharedResources({
-      libs: this.options.libs,
-      skipLibs: this.options.skipLibs,
-      skipBundler: this.options.skipBundler,
-    });
-  }
-
-  /**
-   * Create a new managed sandbox.
-   * Shares TypeScript libs and bundler with all other sandboxes.
-   */
-  async createSandbox(options: ManagedSandboxOptions = {}): Promise<ManagedSandbox> {
-    // Ensure resources are initialized
-    await this.initialize();
-
-    const {
-      id = `sandbox-${this.nextId++}`,
-      fsOptions = {},
-      initialFiles,
-      tsconfigPath = "/tsconfig.json",
-      onBuild,
-      customCommands = [],
-      inMemory = true,
-      sharedModules = this.options.sharedModules,
-    } = options;
-
-    // Create filesystem
-    let fs: IndexedDbFs;
-    if (inMemory) {
-      fs = IndexedDbFs.createInMemory({
-        initialFiles,
-        maxSizeBytes: fsOptions.maxSizeBytes,
-      });
-    } else {
-      fs = await IndexedDbFs.create({
-        dbName: fsOptions.dbName ?? id,
-        initialFiles,
-        maxSizeBytes: fsOptions.maxSizeBytes,
-      });
-    }
-
-    // Create build event emitter
-    const buildEmitter = new BuildEmitter();
-
-    // If a callback was provided in options, subscribe it
-    if (onBuild) {
-      buildEmitter.on(onBuild);
-    }
-
-    // Create commands using shared resources
-    const commandDeps: CommandDeps = {
-      fs,
-      libFiles: this.resources!.libFiles,
-      tsconfigPath,
-      onBuild: buildEmitter.emit,
-      typesCache: this.resources!.typesCache,
-      sharedModules,
-    };
-    const defaultCommands = createDefaultCommands(commandDeps);
-
-    // Create bash environment
-    const bash = new Bash({
-      fs,
-      cwd: "/",
-      customCommands: [...defaultCommands, ...customCommands],
-    });
-
-    const sandbox: ManagedSandbox = {
-      id,
-      fs,
-      bash,
-      isDirty: () => fs.isDirty(),
-      save: () => fs.save(),
-      close: () => {
-        fs.close();
-        this.sandboxes.delete(id);
-      },
-      onBuild: (callback) => buildEmitter.on(callback),
-    };
-
-    this.sandboxes.set(id, sandbox);
-    return sandbox;
-  }
-
-  /**
-   * Get a sandbox by ID
-   */
-  getSandbox(id: string): ManagedSandbox | undefined {
-    return this.sandboxes.get(id);
-  }
-
-  /**
-   * Get all active sandboxes
-   */
-  getAllSandboxes(): ManagedSandbox[] {
-    return Array.from(this.sandboxes.values());
-  }
-
-  /**
-   * Close a specific sandbox
-   */
-  closeSandbox(id: string): boolean {
-    const sandbox = this.sandboxes.get(id);
-    if (sandbox) {
-      sandbox.close();
-      return true;
-    }
-    return false;
-  }
-
-  /**
-   * Close all sandboxes and release resources
-   */
-  destroyAll(): void {
-    for (const sandbox of this.sandboxes.values()) {
-      sandbox.fs.close();
-    }
-    this.sandboxes.clear();
-  }
-
-  /**
-   * Save all sandboxes that have unsaved changes.
-   * 
-   * @returns Map of sandbox ID to save result (true if saved, false if nothing to save)
-   * 
-   * @example
-   * ```ts
-   * const results = await manager.saveAll();
-   * for (const [id, saved] of results) {
-   *   console.log(`${id}: ${saved ? 'saved' : 'no changes'}`);
-   * }
-   * ```
-   */
-  async saveAll(): Promise<Map<string, boolean>> {
-    const results = new Map<string, boolean>();
-    for (const [id, sandbox] of this.sandboxes) {
-      const saved = await sandbox.save();
-      results.set(id, saved);
-    }
-    return results;
-  }
-
-  /**
-   * Get IDs of sandboxes with unsaved changes.
-   * 
-   * @example
-   * ```ts
-   * const dirtyIds = manager.getDirtySandboxes();
-   * if (dirtyIds.length > 0) {
-   *   console.log('Unsaved sandboxes:', dirtyIds.join(', '));
-   * }
-   * ```
-   */
-  getDirtySandboxes(): string[] {
-    return Array.from(this.sandboxes.entries())
-      .filter(([_, sandbox]) => sandbox.isDirty())
-      .map(([id]) => id);
-  }
-
-  /**
-   * Get statistics about the manager
-   */
-  getStats(): SandboxManagerStats {
-    return {
-      initialized: this.initialized,
-      activeSandboxes: this.sandboxes.size,
-      libFilesCount: this.resources?.libFiles.size ?? 0,
-      sandboxIds: Array.from(this.sandboxes.keys()),
-    };
-  }
-
-  /**
-   * Get the shared resources (for advanced use cases)
-   */
-  getResources(): SharedResources | null {
-    return this.resources;
-  }
-}
-
-/**
- * Create a new SandboxManager instance.
- *
- * @example
- * ```ts
- * const manager = await createSandboxManager();
- *
- * // Create multiple sandboxes concurrently
- * const [sandbox1, sandbox2] = await Promise.all([
- *   manager.createSandbox({ id: "agent-1", initialFiles: { ... } }),
- *   manager.createSandbox({ id: "agent-2", initialFiles: { ... } }),
- * ]);
- *
- * // Run operations in parallel
- * const [result1, result2] = await Promise.all([
- *   sandbox1.bash.exec("build"),
- *   sandbox2.bash.exec("build"),
- * ]);
- *
- * // Clean up
- * manager.destroyAll();
- * ```
- */
-export async function createSandboxManager(
-  options: SandboxManagerOptions = {}
-): Promise<SandboxManager> {
-  const manager = new SandboxManager(options);
-  await manager.initialize();
-  return manager;
-}
-