sandlot 0.1.0

package/README.md

@@ -0,0 +1,616 @@
+# Sandlot
+
+A browser-based TypeScript sandbox for AI agent-driven code generation.
+
+San dy 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
+- **React Integration** - Share your React instance with dynamic components
+
+## 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 },
+      }),
+    },
+  },
+});
+
+// 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();
+
+if (result.exitCode === 0 && bundle) {
+  const mod = await loadModule<{ greet: (name: string) => string }>(bundle);
+  console.log(mod.greet("World")); // "Hello, World!"
+}
+
+sandbox.close();
+```
+
+## Sandbox API
+
+The Sandbox API provides direct access to the filesystem and bash shell.
+
+### Creating a Sandbox
+
+```typescript
+import { createSandbox, createInMemorySandbox } from "sandlot";
+
+// 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
+
+```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);
+
+// Build (entry point required) - capture result via onBuild callback
+let bundleResult: BundleResult | null = null;
+const unsubscribe = sandbox.onBuild((result) => {
+  bundleResult = result;
+});
+
+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:
+  --skip-typecheck, -s    Skip type checking
+  --minify, -m            Enable minification
+  --format, -f <format>   Output format: esm (default), iife, cjs
+```
+
+### Sandbox Events
+
+```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();
+```
+
+> **Note:** The `onBuild` callback is invoked synchronously during successful builds.
+> Use it to capture the `BundleResult` for loading modules.
+
+### Sandbox Manager
+
+For managing multiple sandboxes with shared resources:
+
+```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[];
+}
+```
+
+---
+
+## React Integration
+
+Sandlot solves the "multiple React instances" problem by letting dynamic components use your host application's React.
+
+### Setup
+
+```typescript
+import * as React from "react";
+import * as ReactDOM from "react-dom/client";
+import { registerSharedModules, createSandbox } from "sandlot";
+import { DynamicMount } from "sandlot/react";
+
+// Register your React instances (do this once at app startup)
+registerSharedModules({
+  react: React,
+  "react-dom/client": ReactDOM,
+});
+```
+
+### Generating React Components
+
+```typescript
+import { createSandbox, loadModule, BundleResult } from "sandlot";
+
+const sandbox = await createSandbox({
+  fsOptions: {
+    initialFiles: {
+      "/tsconfig.json": JSON.stringify({
+        compilerOptions: {
+          target: "ES2020",
+          module: "ESNext",
+          jsx: "react-jsx",
+          strict: true,
+        },
+      }),
+    },
+  },
+  sharedModules: ["react", "react-dom/client"],
+});
+
+// Install React types for TypeScript compilation
+// (sharedModules provides runtime React, but types are still needed)
+await sandbox.bash.exec("install react react-dom");
+
+await sandbox.fs.writeFile(
+  "/src/index.tsx",
+  `
+  import React, { useState } from "react";
+  import { createRoot } from "react-dom/client";
+
+  function Counter() {
+    const [count, setCount] = useState(0);
+    return (
+      <button onClick={() => setCount(c => c + 1)}>
+        Count: {count}
+      </button>
+    );
+  }
+
+  export function render(container: HTMLElement) {
+    const root = createRoot(container);
+    root.render(<Counter />);
+    return () => root.unmount();
+  }
+  `,
+);
+
+// Capture build result
+let bundle: BundleResult | null = null;
+const unsubscribe = sandbox.onBuild((result) => {
+  bundle = result;
+});
+
+const buildResult = await sandbox.bash.exec("build /src/index.tsx");
+unsubscribe();
+
+if (buildResult.exitCode === 0 && bundle) {
+  // Load the module and call render
+  const mod = await loadModule<{ render: (el: HTMLElement) => () => void }>(
+    bundle,
+  );
+  // mod.render is ready to use
+}
+
+sandbox.close();
+```
+
+### Rendering Dynamic Components
+
+Use `DynamicMount` to render the generated component:
+
+```tsx
+import { DynamicMount } from "sandlot/react";
+
+function App() {
+  const [module, setModule] = useState(null);
+
+  const generate = async () => {
+    // ... build with sandbox, capture bundle via onBuild ...
+    setModule(bundle);
+  };
+
+  return (
+    <div>
+      <button onClick={generate}>Generate</button>
+      <DynamicMount
+        module={module}
+        props={{ name: "World" }}
+        fallback={<div>Click to generate...</div>}
+        onMount={() => console.log("Mounted")}
+        onError={(err) => console.error(err)}
+      />
+    </div>
+  );
+}
+```
+
+### Using the Hook
+
+For more control, use `useDynamicComponent`:
+
+```tsx
+import { useDynamicComponent } from "sandlot/react";
+
+function App() {
+  const { containerRef, isMounted, error, unmount } = useDynamicComponent(
+    module,
+    { name: "World" },
+  );
+
+  return (
+    <div>
+      <div ref={containerRef} />
+      {isMounted && <button onClick={unmount}>Remove</button>}
+      {error && <div>Error: {error.message}</div>}
+    </div>
+  );
+}
+```
+
+### Render Function Pattern
+
+Dynamic components must export a `render` function:
+
+```typescript
+export function render(container: HTMLElement, props?: MyProps) {
+  const root = createRoot(container);
+  root.render(<MyComponent {...props} />);
+  return () => root.unmount(); // Cleanup function
+}
+```
+
+---
+
+## Package Management
+
+Sandlot installs packages via esm.sh CDN and fetches TypeScript type definitions.
+
+### Installing Packages
+
+```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
+```
+
+---
+
+## Loading Modules
+
+After building, use loaders to access the compiled code:
+
+```typescript
+import { loadModule, loadExport, loadDefault } from "sandlot";
+
+// Load all exports
+const mod = await loadModule<{ add: Function; multiply: Function }>(
+  result.bundle,
+);
+
+// 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"
+});
+
+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
+});
+
+if (result.hasErrors) {
+  // Human-readable format
+  console.log(formatDiagnostics(result.diagnostics));
+
+  // Agent-friendly format
+  console.log(formatDiagnosticsForAgent(result.diagnostics));
+}
+```
+
+### Custom Filesystem
+
+```typescript
+import { createIndexedDbFs, IndexedDbFs } from "sandlot";
+
+// Persistent filesystem
+const fs = await createIndexedDbFs({
+  dbName: "my-project",
+  initialFiles: { "/README.md": "# Hello" },
+  maxSizeBytes: 50 * 1024 * 1024, // 50MB limit
+});
+
+// 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();
+```
+
+### Shared Resources
+
+Share TypeScript libs and bundler across multiple sandboxes:
+
+```typescript
+import { createSharedResources, getDefaultResources } from "sandlot";
+
+// Create custom resources
+const resources = await createSharedResources({
+  libs: ["ES2022", "DOM", "DOM.Iterable"],
+});
+
+// Use with sandbox
+const sandbox = await createSandbox({
+  resources,
+});
+
+// Or use the default singleton
+const defaultResources = await getDefaultResources();
+```
+
+---
+
+## TypeScript Configuration
+
+Sandlot respects your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"]
+  }
+}
+```
+
+Supported 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
+
+---
+
+## API Reference
+
+### Exports from `sandlot`
+
+```typescript
+// Sandbox API
+export { createSandbox, createInMemorySandbox } from "sandlot";
+export { SandboxManager, createSandboxManager } from "sandlot";
+
+// Module Loading
+export { loadModule, loadExport, loadDefault } from "sandlot";
+export { getExportNames, hasExport } from "sandlot";
+
+// Shared Modules
+export { registerSharedModules, clearSharedModules } from "sandlot";
+
+// Types
+export type { Sandbox, SandboxOptions } from "sandlot";
+export type { BundleResult, TypecheckResult } from "sandlot";
+```
+
+### Exports from `sandlot/react`
+
+```typescript
+export { DynamicMount, useDynamicComponent } from "sandlot/react";
+export { generateRenderFunction, REACT_RENDER_TEMPLATE } from "sandlot/react";
+export type { DynamicRenderModule, DynamicMountProps } from "sandlot/react";
+```
+
+---
+
+## Requirements
+
+- Modern browser with ES2020 support
+- IndexedDB (for persistent filesystems)
+- WebAssembly (for esbuild)
+
+## License
+
+MIT