sandlot 0.1.1 → 0.1.3

package/src/sandbox.ts

@@ -1,92 +1,40 @@
-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 { Bash, defineCommand, type BashOptions } from "just-bash/browser";
+import { Filesystem, type FilesystemOptions } from "./fs";
+import { initBundler } from "./bundler";
+import { createDefaultCommands, type CommandDeps, type BuildOutput, type ValidateFn } 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";
+import { BuildEmitter } from "./build-emitter";
+import { installPackage, parseImportPath } from "./packages";
 
 /**
- * Simple typed event emitter for build results.
- * Caches the last result so waitFor() can be called after build completes.
+ * Options that can be passed through to the just-bash Bash constructor.
+ * Excludes options that sandlot controls internally (fs, customCommands, files).
  */
-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);
-      });
-    });
-  }
-}
+export type SandboxBashOptions = Omit<BashOptions, 'fs' | 'customCommands' | 'files'>;
 
 /**
  * Options for creating a sandbox environment
  */
 export interface SandboxOptions {
   /**
-   * Options for the IndexedDB filesystem
+   * Initial files to populate the filesystem with.
+   * 
+   * @example
+   * ```ts
+   * const sandbox = await createSandbox({
+   *   initialFiles: {
+   *     '/src/index.ts': 'export const x = 1;',
+   *     '/tsconfig.json': JSON.stringify({ compilerOptions: { strict: true } }),
+   *   },
+   * });
+   * ```
+   */
+  initialFiles?: Record<string, string>;
+
+  /**
+   * Maximum filesystem size in bytes (default: 50MB)
    */
-  fsOptions?: IndexedDbFsOptions;
+  maxFilesystemSize?: number;
 
   /**
    * Path to tsconfig.json in the virtual filesystem.
@@ -105,10 +53,12 @@ export interface SandboxOptions {
 
   /**
    * 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.
+   * Receives the build output with the bundle and loaded module.
+   *
+   * For agent workflows, prefer using `createBuilder()` which handles
+   * build capture automatically.
    */
-  onBuild?: (result: BundleResult) => void | Promise<void>;
+  onBuild?: (result: BuildOutput) => void | Promise<void>;
 
   /**
    * Additional custom commands to add to the bash environment
@@ -119,29 +69,64 @@ export interface SandboxOptions {
    * 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.
-   * 
+   *
+   * Type definitions are automatically installed for these modules so that
+   * TypeScript can typecheck code that imports them.
+   *
    * @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({
+   *
+   * // Create sandbox with shared modules (types auto-installed)
+   * const sandbox = await createSandbox({
    *   sharedModules: ['react', 'react-dom/client'],
    * });
    * ```
    */
   sharedModules?: string[];
+
+  /**
+   * Options passed through to the just-bash Bash constructor.
+   * Use this to configure environment variables, execution limits, 
+   * network access, logging, and other bash-level settings.
+   * 
+   * Note: `fs`, `customCommands`, and `files` are controlled by sandlot
+   * and cannot be overridden here.
+   * 
+   * @example
+   * ```ts
+   * const sandbox = await createSandbox({
+   *   bashOptions: {
+   *     cwd: '/src',
+   *     env: { NODE_ENV: 'development' },
+   *     executionLimits: { maxCommandCount: 1000 },
+   *   },
+   * });
+   * ```
+   */
+  bashOptions?: SandboxBashOptions;
+}
+
+/**
+ * Sandbox state that can be serialized for persistence.
+ */
+export interface SandboxState {
+  /**
+   * All files in the filesystem as path -> content mapping.
+   * Can be passed as `initialFiles` when creating a new sandbox.
+   */
+  files: Record<string, string>;
 }
 
 /**
@@ -149,9 +134,9 @@ export interface SandboxOptions {
  */
 export interface Sandbox {
   /**
-   * The virtual filesystem (IndexedDB-backed)
+   * The virtual filesystem
    */
-  fs: IndexedDbFs;
+  fs: Filesystem;
 
   /**
    * The just-bash shell environment
@@ -159,55 +144,94 @@ export interface Sandbox {
   bash: Bash;
 
   /**
-   * Check if there are unsaved changes in the filesystem.
-   * 
+   * The last successful build output, or null if no build has succeeded yet.
+   *
+   * This is updated automatically whenever a `build` command succeeds.
+   * Contains both the bundle and the loaded (and validated, if applicable) module.
+   *
    * @example
    * ```ts
-   * await sandbox.bash.exec('echo "hello" > /test.txt');
-   * console.log(sandbox.isDirty()); // true
-   * await sandbox.save();
-   * console.log(sandbox.isDirty()); // false
+   * // Agent loop pattern
+   * while (!sandbox.lastBuild) {
+   *   const response = await agent.step();
+   *   await sandbox.bash.exec(response.command);
+   * }
+   * // Build succeeded, sandbox.lastBuild contains bundle + module
+   * const App = sandbox.lastBuild.module.App;
    * ```
    */
-  isDirty(): boolean;
+  lastBuild: BuildOutput | null;
 
   /**
-   * Save the filesystem to IndexedDB.
+   * Get the current sandbox state for persistence.
+   * 
+   * Returns a serializable object containing all files that can be
+   * JSON-serialized and used to restore the sandbox later.
+   * 
+   * @example
+   * ```ts
+   * // Save sandbox state
+   * const state = sandbox.getState();
+   * localStorage.setItem('my-project', JSON.stringify(state));
    * 
-   * @returns true if saved, false if nothing to save or in-memory only
+   * // Later, restore the sandbox
+   * const saved = JSON.parse(localStorage.getItem('my-project'));
+   * const sandbox2 = await createSandbox({ initialFiles: saved.files });
+   * ```
    */
-  save(): Promise<boolean>;
+  getState(): SandboxState;
 
   /**
-   * Close all resources (filesystem, etc.)
+   * Subscribe to build events. Called whenever a build succeeds.
+   * Returns an unsubscribe function.
+   *
+   * For agent workflows, prefer using `createBuilder()` which handles
+   * build capture automatically. Use `onBuild` directly when you need
+   * more control over the subscription lifecycle.
+   *
+   * @example
+   * ```ts
+   * let lastBuild: BuildOutput | null = null;
+   * const unsubscribe = sandbox.onBuild((result) => {
+   *   lastBuild = result;
+   * });
+   *
+   * await sandbox.bash.exec('build /src/index.ts');
+   * unsubscribe();
+   *
+   * if (lastBuild) {
+   *   const App = lastBuild.module.App as React.ComponentType;
+   * }
+   * ```
    */
-  close(): void;
+  onBuild(callback: (result: BuildOutput) => void | Promise<void>): () => 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.
-   * 
+   * Set a validation function for the build command.
+   *
+   * When set, the build command will run this function after loading
+   * the module. If validation throws, the build fails and the agent
+   * sees the error. If validation passes, the validated module is
+   * available in the build output.
+   *
    * @example
    * ```ts
-   * let bundle: BundleResult | null = null;
-   * 
-   * const sandbox = await createInMemorySandbox({
-   *   onBuild: (result) => {
-   *     bundle = result;
-   *     console.log('Built:', result.code.length, 'bytes');
-   *   },
+   * sandbox.setValidation((mod) => {
+   *   if (!mod.App) throw new Error("Must export App component");
+   *   return { App: mod.App as React.ComponentType };
    * });
-   * 
-   * // ... agent writes files and calls build ...
-   * 
-   * // After successful build, bundle is available
-   * console.log(bundle?.code);
+   *
+   * // Now build will fail if App is missing
+   * await sandbox.bash.exec('build /src/index.ts');
    * ```
    */
-  onBuild(callback: (result: BundleResult) => void | Promise<void>): () => void;
+  setValidation(fn: ValidateFn): void;
+
+  /**
+   * Clear the validation function.
+   * After calling this, builds will not perform validation.
+   */
+  clearValidation(): void;
 }
 
 /**
@@ -217,9 +241,12 @@ export interface Sandbox {
  * 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)
+ * - `install <pkg>` - Install npm packages
+ * - `uninstall <pkg>` - Remove packages
+ * - `list` - List installed packages
+ * - `run <entry>` - Run a script
  *
  * 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
@@ -229,18 +256,14 @@ export interface Sandbox {
  * 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 }
- *       }),
- *     },
+ *   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.
  *   },
  * });
  *
@@ -248,137 +271,100 @@ export interface Sandbox {
  * await sandbox.bash.exec('echo "console.log(1);" > /src/index.ts');
  *
  * // Type check
- * const tscResult = await sandbox.bash.exec("tsc");
+ * const tscResult = await sandbox.bash.exec('tsc /src/index.ts');
  * console.log(tscResult.stdout);
  *
  * // Build (includes typecheck, triggers onBuild callback)
- * const buildResult = await sandbox.bash.exec("build");
+ * const buildResult = await sandbox.bash.exec('build /src/index.ts');
  * console.log(buildResult.stdout);
  * console.log(bundleResult?.code); // The compiled bundle
  *
- * // Save to IndexedDB
- * await sandbox.save();
- *
- * // Clean up
- * sandbox.close();
+ * // Save state for later
+ * const state = sandbox.getState();
+ * localStorage.setItem('my-project', JSON.stringify(state));
  * ```
  */
 export async function createSandbox(options: SandboxOptions = {}): Promise<Sandbox> {
   const {
-    fsOptions = {},
+    initialFiles,
+    maxFilesystemSize,
     tsconfigPath = "/tsconfig.json",
     resources: providedResources,
     onBuild: onBuildCallback,
     customCommands = [],
     sharedModules,
+    bashOptions = {},
   } = options;
 
-  // Start parallel initialization tasks
-  const fsPromise = IndexedDbFs.create(fsOptions);
+  // Create filesystem (synchronous)
+  const fs = Filesystem.create({
+    initialFiles,
+    maxSizeBytes: maxFilesystemSize,
+  });
 
-  // Determine which resources to use:
-  // 1. Provided resources (preferred)
-  // 2. Default resources singleton
+  // Load shared resources and bundler in parallel
   const resourcesPromise = providedResources
     ? Promise.resolve(providedResources)
     : getDefaultResources();
 
   const bundlerPromise = initBundler();
 
-  // Wait for all initialization
-  const [fs, resources] = await Promise.all([fsPromise, resourcesPromise, bundlerPromise]);
+  // Wait for async initialization
+  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();
+  // Auto-install types for shared modules so TypeScript can typecheck them
+  // Only install base packages, not subpath exports (e.g., "react" not "react/jsx-runtime")
+  // Subpath types are fetched automatically when the base package is installed
+  if (sharedModules && sharedModules.length > 0) {
+    // Extract unique base package names
+    const basePackages = new Set<string>();
+    for (const moduleId of sharedModules) {
+      const { packageName } = parseImportPath(moduleId);
+      basePackages.add(packageName);
+    }
 
-  // If a callback was provided in options, subscribe it
-  if (onBuildCallback) {
-    buildEmitter.on(onBuildCallback);
+    await Promise.all(
+      Array.from(basePackages).map(async (packageName) => {
+        try {
+          // Install the package to get its type definitions
+          // The runtime will use the shared module, but we need types for typechecking
+          await installPackage(fs, packageName, { cache: typesCache });
+        } catch (err) {
+          // Log but don't fail - module might not have types available
+          console.warn(`[sandlot] Failed to install types for shared module "${packageName}":`, err);
+        }
+      })
+    );
   }
 
-  // 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();
 
+  // Track the last successful build
+  let lastBuild: BuildOutput | null = null;
+  buildEmitter.on((result) => {
+    lastBuild = result;
+  });
+
   // 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
+  // Validation function (can be set/cleared dynamically)
+  let validationFn: ValidateFn | null = null;
+
+  // Create commands
   const commandDeps: CommandDeps = {
     fs,
     libFiles,
     tsconfigPath,
     onBuild: buildEmitter.emit,
+    getValidation: () => validationFn,
     typesCache,
     sharedModules,
   };
@@ -386,17 +372,25 @@ export async function createInMemorySandbox(
 
   // Create bash environment with the custom filesystem
   const bash = new Bash({
+    ...bashOptions,
     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
+    get lastBuild() {
+      return lastBuild;
+    },
+    getState: () => ({ files: fs.getFiles() }),
     onBuild: (callback) => buildEmitter.on(callback),
+    setValidation: (fn: ValidateFn) => {
+      validationFn = fn;
+    },
+    clearValidation: () => {
+      validationFn = null;
+    },
   };
 }
+