sandlot 0.1.2 → 0.1.4

package/src/sandbox.ts

@@ -1,18 +1,41 @@
-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";
 import { BuildEmitter } from "./build-emitter";
+import { installPackage, parseImportPath } from "./packages";
+
+/**
+ * Options that can be passed through to the just-bash Bash constructor.
+ * Excludes options that sandlot controls internally (fs, customCommands, files, cwd).
+ * The working directory is always root (/).
+ */
+export type SandboxBashOptions = Omit<BashOptions, 'fs' | 'customCommands' | 'files' | 'cwd'>;
 
 /**
  * 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.
@@ -31,10 +54,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
@@ -45,29 +70,63 @@ 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`, `files`, and `cwd` are controlled by sandlot
+   * and cannot be overridden here. The working directory is always root (/).
+   * 
+   * @example
+   * ```ts
+   * const sandbox = await createSandbox({
+   *   bashOptions: {
+   *     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>;
 }
 
 /**
@@ -75,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
@@ -85,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.
    * 
-   * @returns true if saved, false if nothing to save or in-memory only
+   * @example
+   * ```ts
+   * // Save sandbox state
+   * const state = sandbox.getState();
+   * localStorage.setItem('my-project', JSON.stringify(state));
+   * 
+   * // 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;
 }
 
 /**
@@ -143,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
@@ -155,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.
  *   },
  * });
  *
@@ -174,155 +271,128 @@ 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);
-
-  // 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 {
+  // Create filesystem (synchronous)
+  const fs = Filesystem.create({
     initialFiles,
-    tsconfigPath = "/tsconfig.json",
-    resources: providedResources,
-    onBuild: onBuildCallback,
-    customCommands = [],
-    sharedModules,
-  } = options;
+    maxSizeBytes: maxFilesystemSize,
+  });
 
-  // Determine which resources to use
+  // Load shared resources and bundler in parallel
   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
+  // 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;
 
+  // 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);
+    }
+
+    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 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,
   };
   const defaultCommands = createDefaultCommands(commandDeps);
 
   // Create bash environment with the custom filesystem
+  // Always start in root directory (/) for consistent behavior
   const bash = new Bash({
+    ...bashOptions,
+    cwd: '/',
     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;
+    },
   };
 }
+

package/src/shared-modules.ts

@@ -21,7 +21,7 @@
  * });
  * 
  * // Now create sandbox with sharedModules option
- * const sandbox = await createInMemorySandbox({
+ * const sandbox = await createSandbox({
  *   sharedModules: ['react', 'react-dom/client'],
  * });
  * ```
@@ -39,6 +39,7 @@ const GLOBAL_KEY = '__sandlot_shared_modules__';
  */
 export class SharedModuleRegistry {
   private modules = new Map<string, unknown>();
+  private exportNames = new Map<string, string[]>();
 
   constructor() {
     // Make available globally for dynamic imports
@@ -46,7 +47,8 @@ export class SharedModuleRegistry {
   }
 
   /**
-   * Register a module to be shared with dynamic bundles
+   * Register a module to be shared with dynamic bundles.
+   * Automatically introspects the module to discover its exports.
    * 
    * @param moduleId - The import specifier (e.g., 'react', 'react-dom/client')
    * @param module - The module's exports object
@@ -54,18 +56,21 @@ export class SharedModuleRegistry {
    */
   register(moduleId: string, module: unknown): this {
     this.modules.set(moduleId, module);
+    // Introspect the module to get its export names
+    this.exportNames.set(moduleId, introspectExports(module));
     return this;
   }
 
   /**
-   * Register multiple modules at once
+   * Register multiple modules at once.
+   * Automatically introspects each module to discover its exports.
    * 
    * @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);
+      this.register(id, mod);
     }
     return this;
   }
@@ -116,11 +121,23 @@ export class SharedModuleRegistry {
     return [...this.modules.keys()];
   }
 
+  /**
+   * Get the export names for a registered module.
+   * These were discovered by introspecting the module at registration time.
+   * 
+   * @param moduleId - The import specifier
+   * @returns Array of export names, or empty array if not registered
+   */
+  getExportNames(moduleId: string): string[] {
+    return this.exportNames.get(moduleId) ?? [];
+  }
+
   /**
    * Clear all registrations
    */
   clear(): void {
     this.modules.clear();
+    this.exportNames.clear();
   }
 
   /**
@@ -131,6 +148,48 @@ export class SharedModuleRegistry {
   }
 }
 
+/**
+ * Introspect a module to discover its export names.
+ * Filters out non-identifier keys and internal properties.
+ */
+function introspectExports(module: unknown): string[] {
+  if (module === null || module === undefined) {
+    return [];
+  }
+
+  if (typeof module !== 'object' && typeof module !== 'function') {
+    return [];
+  }
+
+  const exports: string[] = [];
+  
+  // Get own enumerable properties
+  for (const key of Object.keys(module as object)) {
+    // Filter out non-valid JavaScript identifiers
+    if (isValidIdentifier(key)) {
+      exports.push(key);
+    }
+  }
+
+  return exports;
+}
+
+/**
+ * Check if a string is a valid JavaScript identifier.
+ * Used to filter out keys that can't be used as named exports.
+ */
+function isValidIdentifier(name: string): boolean {
+  if (name.length === 0) return false;
+  // Must start with letter, underscore, or $
+  if (!/^[a-zA-Z_$]/.test(name)) return false;
+  // Rest must be alphanumeric, underscore, or $
+  if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name)) return false;
+  // Exclude reserved words that would cause issues
+  const reserved = ['default', 'class', 'function', 'var', 'let', 'const', 'import', 'export'];
+  if (reserved.includes(name)) return false;
+  return true;
+}
+
 // Singleton instance
 let defaultRegistry: SharedModuleRegistry | null = null;
 
@@ -190,6 +249,17 @@ export function clearSharedModules(): void {
   getSharedModuleRegistry().clear();
 }
 
+/**
+ * Get the export names for a registered shared module.
+ * Used by the bundler to generate proper re-export statements.
+ * 
+ * @param moduleId - The import specifier
+ * @returns Array of export names, or empty array if not registered
+ */
+export function getSharedModuleExports(moduleId: string): string[] {
+  return getSharedModuleRegistry().getExportNames(moduleId);
+}
+
 /**
  * Generate the runtime code that dynamic bundles use to access shared modules.
  * This is injected into bundles when they import from shared modules.

package/src/shared-resources.ts

@@ -6,9 +6,6 @@
  * - esbuild WASM (~10MB) - singleton bundler initialization
  * - Types cache - avoids redundant network fetches when multiple sandboxes
  *   install the same packages
- *
- * This module consolidates what was previously scattered across
- * sandbox.ts and sandbox-manager.ts into a single source of truth.
  */
 
 import { fetchAndCacheLibs, getDefaultBrowserLibs } from "./ts-libs";