sandlot 0.1.2 → 0.1.4

package/README.md

@@ -1,472 +1,233 @@
 # Sandlot
 
-A browser-based TypeScript sandbox for AI agent-driven code generation.
-
-Sandlot provides a complete in-browser development environment with a virtual filesystem, TypeScript type checking, esbuild bundling, and npm package management—all without a server.
-
-## Features
-
-- **Virtual Filesystem** - In-memory or IndexedDB-backed file storage
-- **TypeScript Type Checking** - Full type checking
-- **esbuild Bundling** - Fast bundling with automatic npm import handling via esbuild-wasm
-- **Package Management** - Install npm packages via esm.sh CDN
-- **Bash Shell** - Familiar command interface (`tsc`, `build`, `install`, etc.) via just-bash
+Browser-based TypeScript sandbox with esbuild bundling and type checking. Designed for AI agent workflows where code needs to be written, validated, and executed in real-time, all in the browser.
 
 ## Installation
 
 ```bash
 npm install sandlot
-# or
-bun add sandlot
 ```
 
 ## Quick Start
 
 ```typescript
-import { createSandbox, loadModule } from "sandlot";
-
-// Create a sandbox
-const sandbox = await createSandbox({
-  fsOptions: {
-    initialFiles: {
-      "/tsconfig.json": JSON.stringify({
-        compilerOptions: { target: "ES2020", module: "ESNext", strict: true },
-      }),
-    },
+import { createBuilder, registerSharedModules } from "sandlot";
+import * as React from "react";
+
+// Share React with dynamic code to avoid duplicate instances
+registerSharedModules({ react: React });
+
+// Create a reusable builder
+const runAgent = createBuilder({
+  sandboxOptions: { sharedModules: ["react"] },
+  build: async (sandbox, prompt) => {
+    // Your agent logic here - execute commands via sandbox.bash.exec()
+    await sandbox.bash.exec(
+      'echo "export const App = () => <div>Hello</div>" > /src/index.tsx',
+    );
+    await sandbox.bash.exec("build /src/index.tsx");
   },
 });
 
-// Write code
-await sandbox.fs.writeFile(
-  "/src/index.ts",
-  `export function greet(name: string) {
-    return \`Hello, \${name}!\`;
-  }`,
-);
-
-// Capture build result via callback
-let bundle: BundleResult | null = null;
-const unsubscribe = sandbox.onBuild((result) => {
-  bundle = result;
-});
-
-// Build
-const result = await sandbox.bash.exec("build /src/index.ts");
-unsubscribe();
+// Run with a prompt
+const result = await runAgent("Create a counter component");
 
-if (result.exitCode === 0 && bundle) {
-  const mod = await loadModule<{ greet: (name: string) => string }>(bundle);
-  console.log(mod.greet("World")); // "Hello, World!"
+if (result.module?.App) {
+  // Use the generated component
+  const App = result.module.App as React.ComponentType;
 }
-
-sandbox.close();
 ```
 
-## Sandbox API
-
-The Sandbox API provides direct access to the filesystem and bash shell.
+## Builder API
 
-### Creating a Sandbox
+The `createBuilder()` function is the primary API for agent workflows. It handles sandbox lifecycle, build capture, validation, and cancellation.
 
-```typescript
-import { createSandbox, createInMemorySandbox } from "sandlot";
+### `createBuilder(options)`
 
-// Persistent sandbox (IndexedDB-backed)
-const sandbox = await createSandbox({
-  fsOptions: {
-    dbName: "my-project",
-    initialFiles: {
-      "/src/index.ts": "export const x = 1;",
-    },
-  },
-});
-
-// In-memory sandbox (no persistence)
-const memSandbox = await createInMemorySandbox({
-  initialFiles: {
-    "/src/index.ts": "export const x = 1;",
-  },
-});
-```
-
-### Using Bash Commands
+Returns a reusable builder function that can be called with different prompts.
 
 ```typescript
-// Write files using bash
-await sandbox.bash.exec('echo "export const x = 1;" > /src/index.ts');
-
-// Type check (entry point required)
-const tscResult = await sandbox.bash.exec("tsc /src/index.ts");
-console.log(tscResult.stdout);
+const runAgent = createBuilder<T>({
+  // Sandbox configuration (pick one)
+  sandbox?: Sandbox,           // Reuse an existing sandbox (state persists between calls)
+  sandboxOptions?: SandboxOptions, // Create fresh sandbox per call (isolated runs)
 
-// Build (entry point required) - capture result via onBuild callback
-let bundleResult: BundleResult | null = null;
-const unsubscribe = sandbox.onBuild((result) => {
-  bundleResult = result;
+  // Your agent logic
+  build: (sandbox: Sandbox, prompt: string) => Promise<T>,
 });
-
-const buildCmd = await sandbox.bash.exec("build /src/index.ts");
-if (buildCmd.exitCode === 0 && bundleResult) {
-  console.log(bundleResult.code); // Compiled JavaScript
-}
-unsubscribe();
-
-// Install packages
-await sandbox.bash.exec("install react lodash@4.17.21");
-
-// List installed packages
-const listResult = await sandbox.bash.exec("list");
-console.log(listResult.stdout);
-
-// Run code (entry point required)
-await sandbox.bash.exec("run /src/script.ts");
 ```
 
-### Build Command Options
-
-```bash
-build <entry> [options]
-
-Arguments:
-  entry                   Entry point file (required, e.g., /src/index.ts)
+#### Options
 
-Options:
-  --skip-typecheck, -s    Skip type checking
-  --minify, -m            Enable minification
-  --format, -f <format>   Output format: esm (default), iife, cjs
-```
+| Option           | Type                              | Description                                             |
+| ---------------- | --------------------------------- | ------------------------------------------------------- |
+| `sandbox`        | `Sandbox`                         | Existing sandbox to reuse. Files persist between calls. |
+| `sandboxOptions` | `SandboxOptions`                  | Options for creating fresh sandboxes per call.          |
+| `build`          | `(sandbox, prompt) => Promise<T>` | Your agent logic. Receives the sandbox and prompt.      |
 
-### Sandbox Events
+### Calling the Builder
 
 ```typescript
-// Subscribe to build events to capture build results
-let bundleResult: BundleResult | null = null;
-const unsubscribe = sandbox.onBuild((result) => {
-  bundleResult = result;
-  console.log("Build completed:", result.code.length, "bytes");
-});
-
-// Build with entry point (required)
-const buildCmd = await sandbox.bash.exec("build /src/index.ts");
-if (buildCmd.exitCode !== 0) {
-  console.error("Build failed:", buildCmd.stderr);
-} else if (bundleResult) {
-  console.log(bundleResult.code);
-}
-unsubscribe();
-
-// Check for unsaved changes
-if (sandbox.isDirty()) {
-  await sandbox.save(); // Persist to IndexedDB
-}
-
-// Clean up
-sandbox.close();
+const result = await runAgent(prompt, options?);
 ```
 
-> **Note:** The `onBuild` callback is invoked synchronously during successful builds.
-> Use it to capture the `BundleResult` for loading modules.
+#### Call Options
 
-### Sandbox Manager
+| Option     | Type            | Description                                                     |
+| ---------- | --------------- | --------------------------------------------------------------- |
+| `validate` | `(module) => M` | Validate exports during build. Errors are visible to the agent. |
+| `timeout`  | `number`        | Max time in ms. Throws `AbortError` if exceeded.                |
+| `signal`   | `AbortSignal`   | For external cancellation.                                      |
 
-For managing multiple sandboxes with shared resources:
+#### Result
 
 ```typescript
-import { createSandboxManager } from "sandlot";
-
-const manager = await createSandboxManager({
-  sharedModules: ["react", "react-dom/client"],
-});
-
-// Create multiple sandboxes - they share TypeScript libs and bundler
-const sandbox1 = await manager.createSandbox({ id: "agent-1" });
-const sandbox2 = await manager.createSandbox({ id: "agent-2" });
-
-// Run operations in parallel
-await Promise.all([sandbox1.bash.exec("build"), sandbox2.bash.exec("build")]);
-
-// Save all with unsaved changes
-await manager.saveAll();
-
-// Get dirty sandbox IDs
-const unsaved = manager.getDirtySandboxes();
-
-// Clean up
-manager.destroyAll();
-```
-
-### Sandbox Options
-
-```typescript
-interface SandboxOptions {
-  // Filesystem configuration
-  fsOptions?: {
-    dbName?: string; // IndexedDB database name
-    initialFiles?: Record<string, string>;
-    maxSizeBytes?: number; // Filesystem size limit
-  };
-
-  // Build configuration
-  tsconfigPath?: string; // Default: "/tsconfig.json"
-
-  // Module sharing (see React Integration)
-  sharedModules?: string[];
-
-  // Build callback - use to capture successful build results
-  onBuild?: (result: BundleResult) => void | Promise<void>;
-
-  // Custom bash commands
-  customCommands?: Command[];
+interface BuildResult<T, M> {
+  result: T | undefined; // Return value from your build function
+  error: Error | null; // Error if build function threw
+  bundle: BundleResult | null; // The compiled JavaScript bundle
+  module: M | null; // Loaded module exports (validated if validate provided)
+  sandbox: Sandbox; // The sandbox used (for inspection or reuse)
 }
 ```
 
----
-
-## Package Management
+### Validation
 
-Sandlot installs packages via esm.sh CDN and fetches TypeScript type definitions.
-
-### Installing Packages
+Validation runs as part of the `build` command. If it throws, the build fails and the agent sees the error, allowing it to fix the code and retry.
 
 ```typescript
-// Via bash
-await sandbox.bash.exec("install lodash date-fns@3.0.0");
-
-// Via direct API
-import { installPackage } from "sandlot";
-await installPackage(fs, "lodash@4.17.21");
-```
-
-### How It Works
-
-1. Resolves package version from esm.sh CDN
-2. Fetches TypeScript type definitions
-3. Stores types in `/node_modules/<package>/`
-4. Updates `/package.json` with installed version
-5. At bundle time, imports are rewritten to esm.sh URLs
-
-### Package Commands
-
-```bash
-install <package>[@version] [...]   # Install packages
-uninstall <package> [...]           # Remove packages
-list                                # Show installed packages
+const result = await runAgent("Create a counter", {
+  validate: (mod) => {
+    if (typeof mod.App !== "function") {
+      throw new Error("Must export an App component");
+    }
+    return { App: mod.App as React.ComponentType };
+  },
+});
+// result.module is typed as { App: React.ComponentType } | null
 ```
 
----
-
-## Loading Modules
-
-After building, use loaders to access the compiled code:
+With Zod:
 
 ```typescript
-import { loadModule, loadExport, loadDefault } from "sandlot";
-
-// Load all exports
-const mod = await loadModule<{ add: Function; multiply: Function }>(
-  result.bundle,
-);
+import { z } from "zod";
 
-// Load a specific export
-const add = await loadExport<(a: number, b: number) => number>(
-  result.bundle,
-  "add",
-);
-
-// Load default export
-const Calculator = await loadDefault<typeof Calculator>(result.bundle);
-
-// Check what's exported
-const names = await getExportNames(result.bundle); // ["add", "multiply", "default"]
-const hasAdd = await hasExport(result.bundle, "add"); // true
-```
-
----
-
-## Advanced Usage
-
-### Direct Bundler Access
-
-```typescript
-import { bundle, initBundler } from "sandlot";
-
-// Pre-warm the bundler (optional)
-await initBundler();
-
-const result = await bundle({
-  fs: myFilesystem,
-  entryPoint: "/src/index.ts",
-  format: "esm", // "esm" | "iife" | "cjs"
-  minify: false,
-  sourcemap: false,
-  sharedModules: ["react"],
-  npmImports: "cdn", // "cdn" | "external" | "bundle"
+const Schema = z.object({
+  App: z.custom<React.ComponentType>((v) => typeof v === "function"),
+  initialCount: z.number().optional(),
 });
 
-console.log(result.code);
-console.log(result.warnings);
-console.log(result.includedFiles);
-```
-
-### Direct Type Checking
-
-```typescript
-import {
-  typecheck,
-  formatDiagnostics,
-  formatDiagnosticsForAgent,
-} from "sandlot";
-
-const result = await typecheck({
-  fs: myFilesystem,
-  entryPoint: "/src/index.ts",
-  tsconfigPath: "/tsconfig.json",
-  libFiles: myLibFiles, // Map of lib name to content
+const result = await runAgent("Create a counter", {
+  validate: (mod) => Schema.parse(mod),
 });
-
-if (result.hasErrors) {
-  // Human-readable format
-  console.log(formatDiagnostics(result.diagnostics));
-
-  // Agent-friendly format
-  console.log(formatDiagnosticsForAgent(result.diagnostics));
-}
 ```
 
-### Custom Filesystem
+### Cancellation
 
 ```typescript
-import { createIndexedDbFs, IndexedDbFs } from "sandlot";
+const controller = new AbortController();
 
-// Persistent filesystem
-const fs = await createIndexedDbFs({
-  dbName: "my-project",
-  initialFiles: { "/README.md": "# Hello" },
-  maxSizeBytes: 50 * 1024 * 1024, // 50MB limit
+const promise = runAgent("Create a dashboard", {
+  signal: controller.signal,
+  timeout: 60_000, // 1 minute
 });
 
-// In-memory filesystem
-const memFs = IndexedDbFs.createInMemory({
-  initialFiles: { "/README.md": "# Hello" },
-});
-
-// File operations
-await fs.writeFile("/src/index.ts", "export const x = 1;");
-const content = await fs.readFile("/src/index.ts");
-const exists = await fs.exists("/src/index.ts");
-await fs.mkdir("/src/utils", { recursive: true });
-await fs.rm("/src/old.ts");
-
-// Persistence
-if (fs.isDirty()) {
-  await fs.save();
-}
-
-fs.close();
+// Cancel on user action
+cancelButton.onclick = () => controller.abort();
 ```
 
-### Shared Resources
+## Sandbox API
 
-Share TypeScript libs and bundler across multiple sandboxes:
+For lower-level control, use `createSandbox()` directly.
 
 ```typescript
-import { createSharedResources, getDefaultResources } from "sandlot";
-
-// Create custom resources
-const resources = await createSharedResources({
-  libs: ["ES2022", "DOM", "DOM.Iterable"],
-});
+import { createSandbox } from "sandlot";
 
-// Use with sandbox
 const sandbox = await createSandbox({
-  resources,
+  initialFiles: {
+    "/src/index.ts": "export const x = 1;",
+    "/tsconfig.json": JSON.stringify({ compilerOptions: { strict: true } }),
+  },
+  sharedModules: ["react", "react-dom/client"],
+  onBuild: (result) => console.log("Build succeeded:", result),
 });
 
-// Or use the default singleton
-const defaultResources = await getDefaultResources();
-```
-
----
-
-## TypeScript Configuration
-
-Sandlot respects your `tsconfig.json`:
+// Execute shell commands
+await sandbox.bash.exec("tsc /src/index.ts"); // Type check
+await sandbox.bash.exec("build /src/index.ts"); // Bundle
+await sandbox.bash.exec("install lodash"); // Install package
+await sandbox.bash.exec("list"); // List packages
 
-```json
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "jsx": "react-jsx",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "lib": ["ES2020", "DOM", "DOM.Iterable"]
-  }
+// Access the last successful build
+if (sandbox.lastBuild) {
+  const { bundle, module } = sandbox.lastBuild;
 }
+
+// Serialize state for persistence
+const state = sandbox.getState();
+localStorage.setItem("project", JSON.stringify(state));
 ```
 
-Supported options:
+### Sandbox Options
 
-- `target`: ES5 through ESNext
-- `module`: CommonJS, ES2015, ES2020, ESNext, Node16, NodeNext
-- `moduleResolution`: Classic, Node, Node16, NodeNext, Bundler
-- `jsx`: preserve, react, react-jsx, react-jsxdev, react-native
-- `strict`, `noImplicitAny`, `strictNullChecks`
-- `esModuleInterop`, `allowJs`, `resolveJsonModule`
-- `lib`: Array of lib names
+| Option          | Type                     | Description                                         |
+| --------------- | ------------------------ | --------------------------------------------------- |
+| `initialFiles`  | `Record<string, string>` | Files to populate the filesystem with.              |
+| `sharedModules` | `string[]`               | Modules to resolve from host (e.g., `['react']`).   |
+| `tsconfigPath`  | `string`                 | Path to tsconfig.json (default: `/tsconfig.json`).  |
+| `onBuild`       | `(result) => void`       | Callback when a build succeeds.                     |
+| `bashOptions`   | `SandboxBashOptions`     | Options for the just-bash shell (env, limits).      |
 
----
+## Shell Commands
 
-## API Reference
+The sandbox provides these built-in commands:
 
-### Exports from `sandlot`
+| Command                   | Description                         |
+| ------------------------- | ----------------------------------- |
+| `tsc [entry]`             | Type check (uses tsconfig.json)     |
+| `build [entry] [options]` | Bundle (runs typecheck first)       |
+| `install <pkg>`           | Install npm package (fetches types) |
+| `uninstall <pkg>`         | Remove package                      |
+| `list`                    | List installed packages             |
+| `run <entry>`             | Execute a script                    |
 
-```typescript
-// Sandbox API
-export { createSandbox, createInMemorySandbox } from "sandlot";
-export { SandboxManager, createSandboxManager } from "sandlot";
+Build options: `--format <esm\|iife\|cjs>`, `--minify`, `--skip-typecheck`
 
-// Module Loading
-export { loadModule, loadExport, loadDefault } from "sandlot";
-export { getExportNames, hasExport } from "sandlot";
+## Shared Modules
 
-// Shared Modules
-export { registerSharedModules, clearSharedModules } from "sandlot";
-
-// Types
-export type { Sandbox, SandboxOptions } from "sandlot";
-export type { BundleResult, TypecheckResult } from "sandlot";
-```
-
-### Exports from `sandlot/react`
+To avoid duplicate library instances (important for React context/hooks), register shared modules before creating sandboxes:
 
 ```typescript
-export { DynamicMount, useDynamicComponent } from "sandlot/react";
-export { generateRenderFunction, REACT_RENDER_TEMPLATE } from "sandlot/react";
-export type { DynamicRenderModule, DynamicMountProps } from "sandlot/react";
+import { registerSharedModules } from "sandlot";
+import * as React from "react";
+import * as ReactDOM from "react-dom/client";
+
+registerSharedModules({
+  react: React,
+  "react-dom/client": ReactDOM,
+});
 ```
 
----
+Then include them in `sharedModules` when creating a sandbox.
 
-## Framework Setup
+## Cross-Origin Isolation
 
-### Vite
+For optimal esbuild-wasm performance, enable cross-origin isolation by adding these headers to your dev server:
 
-For optimal performance, add cross-origin isolation headers to enable SharedArrayBuffer:
+```
+Cross-Origin-Embedder-Policy: require-corp
+Cross-Origin-Opener-Policy: same-origin
+```
 
-```typescript
-// vite.config.ts
-import { defineConfig } from "vite";
+In Vite:
 
+```typescript
 export default defineConfig({
   plugins: [
-    // Add COOP/COEP headers for SharedArrayBuffer (recommended for esbuild-wasm)
     {
-      name: "cross-origin-isolation",
+      name: "isolation",
       configureServer: (server) => {
-        server.middlewares.use((_req, res, next) => {
+        server.middlewares.use((_, res, next) => {
           res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
           res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
           next();
@@ -477,37 +238,6 @@ export default defineConfig({
 });
 ```
 
-> **Note:** Without these headers, sandlot will still work but may have reduced performance.
-> The console will show a warning if cross-origin isolation is not enabled.
-
-### Next.js
-
-Add headers in `next.config.js`:
-
-```javascript
-module.exports = {
-  async headers() {
-    return [
-      {
-        source: "/(.*)",
-        headers: [
-          { key: "Cross-Origin-Embedder-Policy", value: "require-corp" },
-          { key: "Cross-Origin-Opener-Policy", value: "same-origin" },
-        ],
-      },
-    ];
-  },
-};
-```
-
----
-
-## Requirements
-
-- Modern browser with ES2020 support
-- IndexedDB (for persistent filesystems)
-- WebAssembly (for esbuild)
-
 ## License
 
 MIT