sandlot 0.1.4 → 0.2.1

package/src/sandbox.ts

@@ -1,398 +0,0 @@
-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 {
-  /**
-   * 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)
-   */
-  maxFilesystemSize?: number;
-
-  /**
-   * 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 build output with the bundle and loaded module.
-   *
-   * For agent workflows, prefer using `createBuilder()` which handles
-   * build capture automatically.
-   */
-  onBuild?: (result: BuildOutput) => 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.
-   *
-   * 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 (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>;
-}
-
-/**
- * The sandbox environment containing the filesystem and bash shell
- */
-export interface Sandbox {
-  /**
-   * The virtual filesystem
-   */
-  fs: Filesystem;
-
-  /**
-   * The just-bash shell environment
-   */
-  bash: Bash;
-
-  /**
-   * 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
-   * // 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;
-   * ```
-   */
-  lastBuild: BuildOutput | null;
-
-  /**
-   * 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));
-   * 
-   * // Later, restore the sandbox
-   * const saved = JSON.parse(localStorage.getItem('my-project'));
-   * const sandbox2 = await createSandbox({ initialFiles: saved.files });
-   * ```
-   */
-  getState(): SandboxState;
-
-  /**
-   * 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;
-   * }
-   * ```
-   */
-  onBuild(callback: (result: BuildOutput) => void | Promise<void>): () => void;
-
-  /**
-   * 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
-   * sandbox.setValidation((mod) => {
-   *   if (!mod.App) throw new Error("Must export App component");
-   *   return { App: mod.App as React.ComponentType };
-   * });
-   *
-   * // Now build will fail if App is missing
-   * await sandbox.bash.exec('build /src/index.ts');
-   * ```
-   */
-  setValidation(fn: ValidateFn): void;
-
-  /**
-   * Clear the validation function.
-   * After calling this, builds will not perform validation.
-   */
-  clearValidation(): 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)
- * - `install <pkg>` - Install npm packages
- * - `uninstall <pkg>` - Remove packages
- * - `list` - List installed packages
- * - `run <entry>` - Run a script
- *
- * Build options:
- * - `--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({
- *   initialFiles: {
- *     '/src/index.ts': 'export const hello = "world";',
- *     '/tsconfig.json': JSON.stringify({
- *       compilerOptions: { target: 'ES2020', strict: true }
- *     }),
- *   },
- *   onBuild: (result) => {
- *     bundleResult = result;
- *   },
- * });
- *
- * // Use bash commands
- * await sandbox.bash.exec('echo "console.log(1);" > /src/index.ts');
- *
- * // Type check
- * 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 /src/index.ts');
- * console.log(buildResult.stdout);
- * console.log(bundleResult?.code); // The compiled bundle
- *
- * // Save state for later
- * const state = sandbox.getState();
- * localStorage.setItem('my-project', JSON.stringify(state));
- * ```
- */
-export async function createSandbox(options: SandboxOptions = {}): Promise<Sandbox> {
-  const {
-    initialFiles,
-    maxFilesystemSize,
-    tsconfigPath = "/tsconfig.json",
-    resources: providedResources,
-    onBuild: onBuildCallback,
-    customCommands = [],
-    sharedModules,
-    bashOptions = {},
-  } = options;
-
-  // Create filesystem (synchronous)
-  const fs = Filesystem.create({
-    initialFiles,
-    maxSizeBytes: maxFilesystemSize,
-  });
-
-  // Load shared resources and bundler in parallel
-  const resourcesPromise = providedResources
-    ? Promise.resolve(providedResources)
-    : getDefaultResources();
-
-  const bundlerPromise = initBundler();
-
-  // 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);
-  }
-
-  // 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,
-    customCommands: [...defaultCommands, ...customCommands],
-  });
-
-  return {
-    fs,
-    bash,
-    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

@@ -1,280 +0,0 @@
-/**
- * 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 createSandbox({
- *   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>();
-  private exportNames = new Map<string, string[]>();
-
-  constructor() {
-    // Make available globally for dynamic imports
-    (globalThis as Record<string, unknown>)[GLOBAL_KEY] = this;
-  }
-
-  /**
-   * 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
-   * @returns this for chaining
-   */
-  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.
-   * 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.register(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()];
-  }
-
-  /**
-   * 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();
-  }
-
-  /**
-   * Get the number of registered modules
-   */
-  get size(): number {
-    return this.modules.size;
-  }
-}
-
-/**
- * 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;
-
-/**
- * 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();
-}
-
-/**
- * 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.
- */
-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();
-}