sandlot 0.1.0

package/src/sandbox-manager.ts

@@ -0,0 +1,490 @@
+/**
+ * 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 type { Sandbox } from "./sandbox";
+
+/**
+ * Simple typed event emitter for build results.
+ * Caches the last result so waitFor() can be called after build completes.
+ */
+class BuildEmitter {
+  private listeners = new Set<(result: BundleResult) => void | Promise<void>>();
+  private lastResult: BundleResult | null = null;
+
+  /**
+   * Emit a build result to all listeners and cache it
+   */
+  emit = async (result: BundleResult): Promise<void> => {
+    this.lastResult = result;
+    const promises: Promise<void>[] = [];
+    for (const listener of this.listeners) {
+      const ret = listener(result);
+      if (ret instanceof Promise) {
+        promises.push(ret);
+      }
+    }
+    await Promise.all(promises);
+  };
+
+  /**
+   * Subscribe to build events. Returns an unsubscribe function.
+   */
+  on(callback: (result: BundleResult) => void | Promise<void>): () => void {
+    this.listeners.add(callback);
+    return () => {
+      this.listeners.delete(callback);
+    };
+  }
+
+  /**
+   * Get the last build result, or wait for the next one if none exists.
+   * Clears the cached result after returning, so subsequent calls wait for new builds.
+   */
+  waitFor(): Promise<BundleResult> {
+    if (this.lastResult) {
+      const result = this.lastResult;
+      this.lastResult = null;
+      return Promise.resolve(result);
+    }
+    return new Promise((resolve) => {
+      const unsub = this.on((result) => {
+        unsub();
+        this.lastResult = null;
+        resolve(result);
+      });
+    });
+  }
+}
+
+// Re-export for convenience
+export type { BundleResult } from "./bundler";
+export type { TypecheckResult } from "./typechecker";
+export type { SharedResources, TypesCache } from "./shared-resources";
+export type { PackageManifest, InstallResult } from "./packages";
+export { installPackage, uninstallPackage, listPackages, getPackageManifest } from "./packages";
+export { InMemoryTypesCache } from "./shared-resources";
+
+// Loader utilities
+export {
+  loadModule,
+  loadExport,
+  loadDefault,
+  getExportNames,
+  hasExport,
+  createModuleUrl,
+  revokeModuleUrl,
+  ModuleLoadError,
+  ExportNotFoundError,
+} from "./loader";
+
+/**
+ * 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;
+  }
+
+  /**
+   * Get the shared lib files (for advanced use cases)
+   * @deprecated Use getResources().libFiles instead
+   */
+  getLibFiles(): Map<string, string> {
+    return this.resources?.libFiles ?? new Map();
+  }
+}
+
+/**
+ * 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;
+}
+