sandlot 0.1.0

package/src/sandbox.ts

@@ -0,0 +1,402 @@
+import { Bash, defineCommand } from "just-bash/browser";
+import { IndexedDbFs, type IndexedDbFsOptions } from "./fs";
+import { initBundler, type BundleResult } from "./bundler";
+import { createDefaultCommands, type CommandDeps } from "./commands";
+import { getDefaultResources, type SharedResources } from "./shared-resources";
+
+// 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 type { RunContext, RunOptions, RunResult } from "./commands";
+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";
+
+/**
+ * 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);
+      });
+    });
+  }
+}
+
+/**
+ * Options for creating a sandbox environment
+ */
+export interface SandboxOptions {
+  /**
+   * Options for the IndexedDB filesystem
+   */
+  fsOptions?: IndexedDbFsOptions;
+
+  /**
+   * Path to tsconfig.json in the virtual filesystem.
+   * Default: "/tsconfig.json"
+   */
+  tsconfigPath?: string;
+
+  /**
+   * Shared resources (lib files, bundler).
+   * If not provided, uses the default singleton resources.
+   * 
+   * Provide this to share resources across multiple sandboxes,
+   * or to use custom TypeScript libs.
+   */
+  resources?: SharedResources;
+
+  /**
+   * Callback invoked when a build succeeds.
+   * Receives the bundle result with the compiled code.
+   * Use this to dynamically import the bundle or halt the agent.
+   */
+  onBuild?: (result: BundleResult) => void | Promise<void>;
+
+  /**
+   * Additional custom commands to add to the bash environment
+   */
+  customCommands?: ReturnType<typeof defineCommand>[];
+
+  /**
+   * 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.
+   * 
+   * This solves the "multiple React instances" problem by allowing dynamic
+   * components to share the same React instance as the host application.
+   * 
+   * @example
+   * ```ts
+   * // Host setup
+   * import * as React from 'react';
+   * import * as ReactDOM from 'react-dom/client';
+   * import { registerSharedModules } from 'sandlot';
+   * 
+   * registerSharedModules({
+   *   'react': React,
+   *   'react-dom/client': ReactDOM,
+   * });
+   * 
+   * // Create sandbox with shared modules
+   * const sandbox = await createInMemorySandbox({
+   *   sharedModules: ['react', 'react-dom/client'],
+   * });
+   * ```
+   */
+  sharedModules?: string[];
+}
+
+/**
+ * The sandbox environment containing the filesystem and bash shell
+ */
+export interface Sandbox {
+  /**
+   * The virtual filesystem (IndexedDB-backed)
+   */
+  fs: IndexedDbFs;
+
+  /**
+   * The just-bash shell environment
+   */
+  bash: Bash;
+
+  /**
+   * Check if there are unsaved changes in the filesystem.
+   * 
+   * @example
+   * ```ts
+   * await sandbox.bash.exec('echo "hello" > /test.txt');
+   * console.log(sandbox.isDirty()); // true
+   * await sandbox.save();
+   * console.log(sandbox.isDirty()); // false
+   * ```
+   */
+  isDirty(): boolean;
+
+  /**
+   * Save the filesystem to IndexedDB.
+   * 
+   * @returns true if saved, false if nothing to save or in-memory only
+   */
+  save(): Promise<boolean>;
+
+  /**
+   * Close all resources (filesystem, etc.)
+   */
+  close(): void;
+
+  /**
+   * Subscribe to build events. Called whenever a build succeeds.
+   * Returns an unsubscribe function.
+   * 
+   * Use this to capture the bundle result when build succeeds.
+   * The callback receives the BundleResult with the compiled code.
+   * 
+   * @example
+   * ```ts
+   * let bundle: BundleResult | null = null;
+   * 
+   * const sandbox = await createInMemorySandbox({
+   *   onBuild: (result) => {
+   *     bundle = result;
+   *     console.log('Built:', result.code.length, 'bytes');
+   *   },
+   * });
+   * 
+   * // ... agent writes files and calls build ...
+   * 
+   * // After successful build, bundle is available
+   * console.log(bundle?.code);
+   * ```
+   */
+  onBuild(callback: (result: BundleResult) => void | Promise<void>): () => void;
+}
+
+/**
+ * Create an in-browser agent sandbox with a virtual filesystem, TypeScript
+ * type checking, and bundling capabilities.
+ *
+ * The sandbox provides a just-bash shell with custom commands:
+ * - `tsc [entry]` - Type check the project
+ * - `build [entry] [options]` - Build the project (runs typecheck first)
+ *
+ * Build options:
+ * - `--output, -o <path>` - Output path (default: /dist/bundle.js)
+ * - `--format, -f <esm|iife|cjs>` - Output format (default: esm)
+ * - `--minify, -m` - Enable minification
+ * - `--skip-typecheck, -s` - Skip type checking
+ *
+ * @example
+ * ```ts
+ * let bundleResult: BundleResult | null = null;
+ * 
+ * const sandbox = await createSandbox({
+ *   fsOptions: {
+ *     dbName: "my-project",
+ *     initialFiles: {
+ *       "/src/index.ts": "export const hello = 'world';",
+ *       "/tsconfig.json": JSON.stringify({
+ *         compilerOptions: { target: "ES2020", strict: true }
+ *       }),
+ *     },
+ *   },
+ *   onBuild: (result) => {
+ *     bundleResult = result;
+ *     // Could also: dynamically import, halt agent, etc.
+ *   },
+ * });
+ *
+ * // Use bash commands
+ * await sandbox.bash.exec('echo "console.log(1);" > /src/index.ts');
+ *
+ * // Type check
+ * const tscResult = await sandbox.bash.exec("tsc");
+ * console.log(tscResult.stdout);
+ *
+ * // Build (includes typecheck, triggers onBuild callback)
+ * const buildResult = await sandbox.bash.exec("build");
+ * console.log(buildResult.stdout);
+ * console.log(bundleResult?.code); // The compiled bundle
+ *
+ * // Save to IndexedDB
+ * await sandbox.save();
+ *
+ * // Clean up
+ * sandbox.close();
+ * ```
+ */
+export async function createSandbox(options: SandboxOptions = {}): Promise<Sandbox> {
+  const {
+    fsOptions = {},
+    tsconfigPath = "/tsconfig.json",
+    resources: providedResources,
+    onBuild: onBuildCallback,
+    customCommands = [],
+    sharedModules,
+  } = options;
+
+  // Start parallel initialization tasks
+  const fsPromise = IndexedDbFs.create(fsOptions);
+
+  // Determine which resources to use:
+  // 1. Provided resources (preferred)
+  // 2. Default resources singleton
+  const resourcesPromise = providedResources
+    ? Promise.resolve(providedResources)
+    : getDefaultResources();
+
+  const bundlerPromise = initBundler();
+
+  // Wait for all initialization
+  const [fs, resources] = await Promise.all([fsPromise, resourcesPromise, bundlerPromise]);
+
+  // Extract lib files and types cache from resources
+  const libFiles = resources.libFiles;
+  const typesCache = resources.typesCache;
+
+  // Create build event emitter
+  const buildEmitter = new BuildEmitter();
+
+  // If a callback was provided in options, subscribe it
+  if (onBuildCallback) {
+    buildEmitter.on(onBuildCallback);
+  }
+
+  // Create commands using the extracted factories
+  // Commands emit to the build emitter
+  const commandDeps: CommandDeps = {
+    fs,
+    libFiles,
+    tsconfigPath,
+    onBuild: buildEmitter.emit,
+    typesCache,
+    sharedModules,
+  };
+  const defaultCommands = createDefaultCommands(commandDeps);
+
+  // Create bash environment with the custom filesystem
+  const bash = new Bash({
+    fs,
+    cwd: "/",
+    customCommands: [...defaultCommands, ...customCommands],
+  });
+
+  return {
+    fs,
+    bash,
+    isDirty: () => fs.isDirty(),
+    save: () => fs.save(),
+    close: () => fs.close(),
+    onBuild: (callback) => buildEmitter.on(callback),
+  };
+}
+
+/**
+ * Create an in-memory sandbox (no IndexedDB persistence).
+ * Useful for testing or temporary workspaces.
+ */
+export async function createInMemorySandbox(
+  options: Omit<SandboxOptions, "fsOptions"> & {
+    initialFiles?: Record<string, string>;
+  } = {}
+): Promise<Sandbox> {
+  const {
+    initialFiles,
+    tsconfigPath = "/tsconfig.json",
+    resources: providedResources,
+    onBuild: onBuildCallback,
+    customCommands = [],
+    sharedModules,
+  } = options;
+
+  // Determine which resources to use
+  const resourcesPromise = providedResources
+    ? Promise.resolve(providedResources)
+    : getDefaultResources();
+
+  const bundlerPromise = initBundler();
+
+  // Create in-memory filesystem synchronously
+  const fs = IndexedDbFs.createInMemory({ initialFiles });
+
+  // Wait for resources and bundler
+  const [resources] = await Promise.all([resourcesPromise, bundlerPromise]);
+
+  // Extract lib files and types cache from resources
+  const libFiles = resources.libFiles;
+  const typesCache = resources.typesCache;
+
+  // Create build event emitter
+  const buildEmitter = new BuildEmitter();
+
+  // If a callback was provided in options, subscribe it
+  if (onBuildCallback) {
+    buildEmitter.on(onBuildCallback);
+  }
+
+  // Create commands using the extracted factories
+  // Commands emit to the build emitter
+  const commandDeps: CommandDeps = {
+    fs,
+    libFiles,
+    tsconfigPath,
+    onBuild: buildEmitter.emit,
+    typesCache,
+    sharedModules,
+  };
+  const defaultCommands = createDefaultCommands(commandDeps);
+
+  // Create bash environment with the custom filesystem
+  const bash = new Bash({
+    fs,
+    cwd: "/",
+    customCommands: [...defaultCommands, ...customCommands],
+  });
+
+  return {
+    fs,
+    bash,
+    isDirty: () => fs.isDirty(),
+    save: () => Promise.resolve(false), // No persistence for in-memory
+    close: () => { }, // No resources to close
+    onBuild: (callback) => buildEmitter.on(callback),
+  };
+}

package/src/shared-modules.ts

@@ -0,0 +1,210 @@
+/**
+ * Shared Module Registry for Sandlot
+ * 
+ * Allows host applications to register their module instances (like React)
+ * so that dynamically bundled code can use the same instances instead of
+ * loading separate copies from esm.sh CDN.
+ * 
+ * This solves the "multiple React instances" problem where hooks fail
+ * because the host and dynamic code use different React copies.
+ * 
+ * @example
+ * ```ts
+ * // Host application setup
+ * import * as React from 'react';
+ * import * as ReactDOM from 'react-dom/client';
+ * import { registerSharedModules } from 'sandlot';
+ * 
+ * registerSharedModules({
+ *   'react': React,
+ *   'react-dom/client': ReactDOM,
+ * });
+ * 
+ * // Now create sandbox with sharedModules option
+ * const sandbox = await createInMemorySandbox({
+ *   sharedModules: ['react', 'react-dom/client'],
+ * });
+ * ```
+ */
+
+/**
+ * Global key used to expose the registry for dynamic bundles
+ */
+const GLOBAL_KEY = '__sandlot_shared_modules__';
+
+/**
+ * Registry for sharing host modules with dynamic bundles.
+ * Modules registered here will be used instead of esm.sh CDN
+ * when the sandbox is configured with matching sharedModules.
+ */
+export class SharedModuleRegistry {
+  private modules = new Map<string, unknown>();
+
+  constructor() {
+    // Make available globally for dynamic imports
+    (globalThis as Record<string, unknown>)[GLOBAL_KEY] = this;
+  }
+
+  /**
+   * Register a module to be shared with dynamic bundles
+   * 
+   * @param moduleId - The import specifier (e.g., 'react', 'react-dom/client')
+   * @param module - The module's exports object
+   * @returns this for chaining
+   */
+  register(moduleId: string, module: unknown): this {
+    this.modules.set(moduleId, module);
+    return this;
+  }
+
+  /**
+   * Register multiple modules at once
+   * 
+   * @param modules - Object mapping module IDs to their exports
+   * @returns this for chaining
+   */
+  registerAll(modules: Record<string, unknown>): this {
+    for (const [id, mod] of Object.entries(modules)) {
+      this.modules.set(id, mod);
+    }
+    return this;
+  }
+
+  /**
+   * Unregister a previously registered module
+   * 
+   * @param moduleId - The import specifier to remove
+   * @returns true if the module was registered and removed
+   */
+  unregister(moduleId: string): boolean {
+    return this.modules.delete(moduleId);
+  }
+
+  /**
+   * Get a registered module (used by dynamic bundles at runtime)
+   * 
+   * @param moduleId - The import specifier
+   * @returns The registered module exports
+   * @throws Error if the module is not registered
+   */
+  get(moduleId: string): unknown {
+    const mod = this.modules.get(moduleId);
+    if (mod === undefined && !this.modules.has(moduleId)) {
+      const available = this.list();
+      throw new Error(
+        `Shared module "${moduleId}" not registered. ` +
+        `Available: ${available.length > 0 ? available.join(', ') : '(none)'}. ` +
+        `Call registerSharedModules({ '${moduleId}': ... }) in your host application.`
+      );
+    }
+    return mod;
+  }
+
+  /**
+   * Check if a module is registered
+   * 
+   * @param moduleId - The import specifier to check
+   */
+  has(moduleId: string): boolean {
+    return this.modules.has(moduleId);
+  }
+
+  /**
+   * Get list of all registered module IDs
+   */
+  list(): string[] {
+    return [...this.modules.keys()];
+  }
+
+  /**
+   * Clear all registrations
+   */
+  clear(): void {
+    this.modules.clear();
+  }
+
+  /**
+   * Get the number of registered modules
+   */
+  get size(): number {
+    return this.modules.size;
+  }
+}
+
+// Singleton instance
+let defaultRegistry: SharedModuleRegistry | null = null;
+
+/**
+ * Get the default shared module registry.
+ * Creates it if it doesn't exist.
+ */
+export function getSharedModuleRegistry(): SharedModuleRegistry {
+  if (!defaultRegistry) {
+    defaultRegistry = new SharedModuleRegistry();
+  }
+  return defaultRegistry;
+}
+
+/**
+ * Check if a shared module registry exists on globalThis
+ */
+export function hasSharedModuleRegistry(): boolean {
+  return GLOBAL_KEY in globalThis;
+}
+
+/**
+ * Convenience function to register modules with the default registry.
+ * 
+ * @param modules - Object mapping module IDs to their exports
+ * 
+ * @example
+ * ```ts
+ * import * as React from 'react';
+ * import * as ReactDOM from 'react-dom/client';
+ * import { registerSharedModules } from 'sandlot';
+ * 
+ * registerSharedModules({
+ *   'react': React,
+ *   'react-dom/client': ReactDOM,
+ * });
+ * ```
+ */
+export function registerSharedModules(modules: Record<string, unknown>): void {
+  getSharedModuleRegistry().registerAll(modules);
+}
+
+/**
+ * Convenience function to unregister a module from the default registry.
+ * 
+ * @param moduleId - The import specifier to remove
+ * @returns true if the module was registered and removed
+ */
+export function unregisterSharedModule(moduleId: string): boolean {
+  return getSharedModuleRegistry().unregister(moduleId);
+}
+
+/**
+ * Clear all shared modules from the default registry.
+ */
+export function clearSharedModules(): void {
+  getSharedModuleRegistry().clear();
+}
+
+/**
+ * Generate the runtime code that dynamic bundles use to access shared modules.
+ * This is injected into bundles when they import from shared modules.
+ */
+export function getSharedModuleRuntimeCode(moduleId: string): string {
+  return `
+(function() {
+  var registry = globalThis["${GLOBAL_KEY}"];
+  if (!registry) {
+    throw new Error(
+      'Sandlot SharedModuleRegistry not found. ' +
+      'Call registerSharedModules() in your host application before loading dynamic modules.'
+    );
+  }
+  return registry.get(${JSON.stringify(moduleId)});
+})()
+`.trim();
+}