sandlot 0.1.2 → 0.1.3

package/dist/internal.js

@@ -675,16 +675,18 @@ var GLOBAL_KEY = "__sandlot_shared_modules__";
 
 class SharedModuleRegistry {
   modules = new Map;
+  exportNames = new Map;
   constructor() {
     globalThis[GLOBAL_KEY] = this;
   }
   register(moduleId, module) {
     this.modules.set(moduleId, module);
+    this.exportNames.set(moduleId, introspectExports(module));
     return this;
   }
   registerAll(modules) {
     for (const [id, mod] of Object.entries(modules)) {
-      this.modules.set(id, mod);
+      this.register(id, mod);
     }
     return this;
   }
@@ -705,13 +707,44 @@ class SharedModuleRegistry {
   list() {
     return [...this.modules.keys()];
   }
+  getExportNames(moduleId) {
+    return this.exportNames.get(moduleId) ?? [];
+  }
   clear() {
     this.modules.clear();
+    this.exportNames.clear();
   }
   get size() {
     return this.modules.size;
   }
 }
+function introspectExports(module) {
+  if (module === null || module === undefined) {
+    return [];
+  }
+  if (typeof module !== "object" && typeof module !== "function") {
+    return [];
+  }
+  const exports = [];
+  for (const key of Object.keys(module)) {
+    if (isValidIdentifier(key)) {
+      exports.push(key);
+    }
+  }
+  return exports;
+}
+function isValidIdentifier(name) {
+  if (name.length === 0)
+    return false;
+  if (!/^[a-zA-Z_$]/.test(name))
+    return false;
+  if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name))
+    return false;
+  const reserved = ["default", "class", "function", "var", "let", "const", "import", "export"];
+  if (reserved.includes(name))
+    return false;
+  return true;
+}
 var defaultRegistry = null;
 function getSharedModuleRegistry() {
   if (!defaultRegistry) {
@@ -731,6 +764,9 @@ function unregisterSharedModule(moduleId) {
 function clearSharedModules() {
   getSharedModuleRegistry().clear();
 }
+function getSharedModuleExports(moduleId) {
+  return getSharedModuleRegistry().getExportNames(moduleId);
+}
 function getSharedModuleRuntimeCode(moduleId) {
   return `
 (function() {
@@ -745,7 +781,21 @@ function getSharedModuleRuntimeCode(moduleId) {
 })()
 `.trim();
 }
-// src/commands.ts
+// src/commands/types.ts
+function formatEsbuildMessages(messages) {
+  if (messages.length === 0)
+    return "";
+  return messages.map((msg) => {
+    if (msg.location) {
+      const { file, line, column } = msg.location;
+      const loc = file ? `${file}${line ? `:${line}` : ""}${column ? `:${column}` : ""}` : "";
+      return loc ? `${loc}: ${msg.text}` : msg.text;
+    }
+    return msg.text;
+  }).join(`
+`);
+}
+// src/commands/compile.ts
 import { defineCommand } from "just-bash/browser";
 
 // src/typechecker.ts
@@ -1262,55 +1312,12 @@ ${generateNamedExports(args.path)}
   };
 }
 function generateNamedExports(moduleId) {
-  const knownExports = {
-    react: [
-      "useState",
-      "useEffect",
-      "useContext",
-      "useReducer",
-      "useCallback",
-      "useMemo",
-      "useRef",
-      "useImperativeHandle",
-      "useLayoutEffect",
-      "useDebugValue",
-      "useDeferredValue",
-      "useTransition",
-      "useId",
-      "useSyncExternalStore",
-      "useInsertionEffect",
-      "useOptimistic",
-      "useActionState",
-      "createElement",
-      "cloneElement",
-      "createContext",
-      "forwardRef",
-      "lazy",
-      "memo",
-      "startTransition",
-      "Children",
-      "Component",
-      "PureComponent",
-      "Fragment",
-      "Profiler",
-      "StrictMode",
-      "Suspense",
-      "version",
-      "isValidElement"
-    ],
-    "react-dom": ["createPortal", "flushSync", "version"],
-    "react-dom/client": ["createRoot", "hydrateRoot"],
-    "react-dom/server": ["renderToString", "renderToStaticMarkup", "renderToPipeableStream"]
-  };
-  const exports = knownExports[moduleId];
-  if (!exports) {
-    return `
-// Dynamic re-export for unknown module
-export const __moduleProxy__ = __sandlot_mod__;
-`;
-  }
-  return exports.map((name) => `export const ${name} = __sandlot_mod__.${name};`).join(`
+  const exports = getSharedModuleExports(moduleId);
+  if (exports.length > 0) {
+    return exports.map((name) => `export const ${name} = __sandlot_mod__.${name};`).join(`
 `);
+  }
+  return `// No exports discovered for "${moduleId}" - use default import or call registerSharedModules() first`;
 }
 async function bundle(options) {
   await initBundler();
@@ -1353,7 +1360,8 @@ async function bundle(options) {
     globalName,
     target,
     external,
-    plugins: [plugin]
+    plugins: [plugin],
+    jsx: "automatic"
   });
   const code = result.outputFiles?.[0]?.text ?? "";
   return {
@@ -1376,20 +1384,7 @@ async function bundleAndImport(options) {
   }
 }
 
-// src/commands.ts
-function formatEsbuildMessages(messages) {
-  if (messages.length === 0)
-    return "";
-  return messages.map((msg) => {
-    if (msg.location) {
-      const { file, line, column } = msg.location;
-      const loc = file ? `${file}${line ? `:${line}` : ""}${column ? `:${column}` : ""}` : "";
-      return loc ? `${loc}: ${msg.text}` : msg.text;
-    }
-    return msg.text;
-  }).join(`
-`);
-}
+// src/commands/compile.ts
 function createTscCommand(deps) {
   const { fs, libFiles, tsconfigPath } = deps;
   return defineCommand("tsc", async (args, _ctx) => {
@@ -1454,7 +1449,7 @@ ${formatDiagnosticsForAgent(result.diagnostics.filter((d) => d.category === "war
   });
 }
 function createBuildCommand(deps) {
-  const { fs, libFiles, tsconfigPath, onBuild, sharedModules } = deps;
+  const { fs, libFiles, tsconfigPath, onBuild, getValidation, sharedModules } = deps;
   return defineCommand("build", async (args, _ctx) => {
     let entryPoint = null;
     let skipTypecheck = false;
@@ -1526,8 +1521,39 @@ ${formatted}
         minify,
         sharedModules
       });
+      let loadedModule;
+      try {
+        loadedModule = await loadModule(bundleResult);
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        return {
+          stdout: "",
+          stderr: `Build failed: Module failed to load.
+
+${errorMessage}
+`,
+          exitCode: 1
+        };
+      }
+      const validateFn = getValidation?.();
+      let validatedModule = loadedModule;
+      if (validateFn) {
+        try {
+          validatedModule = validateFn(loadedModule);
+        } catch (err) {
+          const errorMessage = err instanceof Error ? err.message : String(err);
+          return {
+            stdout: "",
+            stderr: `Build failed: Validation error.
+
+${errorMessage}
+`,
+            exitCode: 1
+          };
+        }
+      }
       if (onBuild) {
-        await onBuild(bundleResult);
+        await onBuild({ bundle: bundleResult, module: validatedModule });
       }
       let output = `Build successful!
 `;
@@ -1543,6 +1569,15 @@ ${formatted}
       }
       output += `Bundled: ${bundleResult.includedFiles.length} file(s)
 `;
+      const exportNames = Object.keys(loadedModule).filter((k) => !k.startsWith("__"));
+      if (exportNames.length > 0) {
+        output += `Exports: ${exportNames.join(", ")}
+`;
+      }
+      if (validateFn) {
+        output += `Validation: passed
+`;
+      }
       if (bundleResult.warnings.length > 0) {
         output += `
 Build warnings:
@@ -1574,9 +1609,11 @@ ${formatDiagnosticsForAgent(warnings)}
     }
   });
 }
+// src/commands/packages.ts
+import { defineCommand as defineCommand2 } from "just-bash/browser";
 function createInstallCommand(deps) {
   const { fs, typesCache } = deps;
-  return defineCommand("install", async (args, _ctx) => {
+  return defineCommand2("install", async (args, _ctx) => {
     if (args.length === 0) {
       return {
         stdout: "",
@@ -1630,7 +1667,7 @@ Examples:
 }
 function createUninstallCommand(deps) {
   const { fs } = deps;
-  return defineCommand("uninstall", async (args, _ctx) => {
+  return defineCommand2("uninstall", async (args, _ctx) => {
     if (args.length === 0) {
       return {
         stdout: "",
@@ -1675,7 +1712,7 @@ function createUninstallCommand(deps) {
 }
 function createListCommand(deps) {
   const { fs } = deps;
-  return defineCommand("list", async (_args, _ctx) => {
+  return defineCommand2("list", async (_args, _ctx) => {
     try {
       const packages = await listPackages(fs);
       if (packages.length === 0) {
@@ -1705,9 +1742,11 @@ function createListCommand(deps) {
     }
   });
 }
+// src/commands/run.ts
+import { defineCommand as defineCommand3 } from "just-bash/browser";
 function createRunCommand(deps) {
   const { fs, libFiles, tsconfigPath, runOptions = {}, sharedModules } = deps;
-  return defineCommand("run", async (args, _ctx) => {
+  return defineCommand3("run", async (args, _ctx) => {
     let entryPoint = null;
     let skipTypecheck = runOptions.skipTypecheck ?? false;
     let timeout = runOptions.timeout ?? 30000;
@@ -1884,6 +1923,7 @@ ${err.stack}` : "";
     }
   });
 }
+// src/commands/index.ts
 function createDefaultCommands(deps) {
   return [
     createTscCommand(deps),
@@ -1897,9 +1937,7 @@ function createDefaultCommands(deps) {
 // src/build-emitter.ts
 class BuildEmitter {
   listeners = new Set;
-  lastResult = null;
   emit = async (result) => {
-    this.lastResult = result;
     const promises = [];
     for (const listener of this.listeners) {
       const ret = listener(result);
@@ -1915,20 +1953,6 @@ class BuildEmitter {
       this.listeners.delete(callback);
     };
   }
-  waitFor() {
-    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 {
   revokeModuleUrl,

package/dist/runner.d.ts

@@ -0,0 +1,314 @@
+/**
+ * High-level runner for sandbox-based agent workflows.
+ *
+ * Provides simple wrappers that handle sandbox creation and build result capture,
+ * letting the caller focus on their agent logic.
+ */
+import { type Sandbox, type SandboxOptions } from "./sandbox";
+import type { BundleResult } from "./bundler";
+/**
+ * Options for building with a sandbox (one-off usage).
+ */
+export interface BuildWithSandboxOptions<T> {
+    /**
+     * Existing sandbox to use. If not provided, a new sandbox is created.
+     *
+     * Use this when you want to:
+     * - Reuse a sandbox across multiple builds
+     * - Pre-configure the sandbox with specific files or settings
+     * - Share a sandbox between different operations
+     *
+     * @example
+     * ```ts
+     * const sandbox = await createSandbox({
+     *   initialFiles: { '/src/index.ts': 'export const x = 1;' },
+     * });
+     *
+     * const result = await buildWithSandbox({
+     *   sandbox,
+     *   build: async (sb) => { ... },
+     * });
+     * ```
+     */
+    sandbox?: Sandbox;
+    /**
+     * Options for creating a new sandbox (only used if `sandbox` is not provided).
+     *
+     * @example
+     * ```ts
+     * const result = await buildWithSandbox({
+     *   sandboxOptions: {
+     *     initialFiles: { '/src/index.ts': 'export const x = 1;' },
+     *     sharedModules: ['react', 'react-dom/client'],
+     *   },
+     *   build: async (sandbox) => { ... },
+     * });
+     * ```
+     */
+    sandboxOptions?: SandboxOptions;
+    /**
+     * The function to run with the sandbox.
+     *
+     * This receives the sandbox and can do anything with it—run bash commands,
+     * write files, execute an agent loop, etc.
+     *
+     * The return value becomes `result` in the output.
+     *
+     * @example
+     * ```ts
+     * const { result, bundle } = await buildWithSandbox({
+     *   build: async (sandbox) => {
+     *     await sandbox.bash.exec('echo "hello" > /test.txt');
+     *     const buildResult = await sandbox.bash.exec('build /src/index.ts');
+     *     return { buildExitCode: buildResult.exitCode };
+     *   },
+     * });
+     * ```
+     */
+    build: (sandbox: Sandbox) => Promise<T>;
+}
+/**
+ * Result of building with a sandbox.
+ */
+export interface BuildResult<T> {
+    /**
+     * Whatever the `build` function returned, or `undefined` if it threw.
+     */
+    result: T | undefined;
+    /**
+     * The error thrown by the `build` function, or `null` if it succeeded.
+     *
+     * When an error occurs, the bundle and module may still be available
+     * if a build succeeded before the error was thrown.
+     */
+    error: Error | null;
+    /**
+     * The last successful build result, or null if no build succeeded.
+     *
+     * This captures the bundle from any successful `build` command executed
+     * during the run. If multiple builds succeed, this contains the last one.
+     *
+     * **Important**: This is available even if the `build` function threw an error,
+     * as long as a build succeeded before the error occurred.
+     */
+    bundle: BundleResult | null;
+    /**
+     * The loaded module exports, or null if no bundle or loading failed.
+     *
+     * When a build succeeds, the bundle is automatically loaded and the
+     * exports are available here. Use type assertions or runtime checks
+     * to access specific exports.
+     *
+     * @example
+     * ```ts
+     * const run = await buildWithSandbox({ build: myAgent });
+     *
+     * if (run.module) {
+     *   const App = run.module.App as React.ComponentType;
+     *   return <App />;
+     * }
+     * ```
+     */
+    module: Record<string, unknown> | null;
+    /**
+     * Error that occurred while loading the module, or null if loading succeeded.
+     *
+     * This is separate from `error` (agent error) to distinguish:
+     * - Agent failed → `error` is set, `module` may still be available
+     * - Agent succeeded but load failed → `moduleError` is set
+     * - No bundle produced → both `module` and `moduleError` are null
+     */
+    moduleError: Error | null;
+    /**
+     * The sandbox that was used.
+     *
+     * Useful when the wrapper created an ephemeral sandbox—you can inspect
+     * its state, save it, or reuse it for another build.
+     */
+    sandbox: Sandbox;
+}
+/**
+ * Build with a sandbox, automatically capturing build results.
+ *
+ * This is the recommended way to use sandlot for one-off builds. It:
+ * 1. Creates a sandbox (or uses one you provide)
+ * 2. Sets up build result capture
+ * 3. Runs your function
+ * 4. Returns everything: your result, the bundle (if any), and the sandbox
+ *
+ * For reusable agent workflows, see `createBuilder()` which wraps this
+ * function and adds prompt support.
+ *
+ * The caller handles their own timeout/cancellation logic—this wrapper
+ * stays minimal and doesn't impose opinions on error handling.
+ *
+ * @example Basic usage with an agent
+ * ```ts
+ * import { buildWithSandbox } from 'sandlot';
+ *
+ * const run = await buildWithSandbox({
+ *   build: async (sandbox) => {
+ *     const agent = new MyAgent({
+ *       tools: {
+ *         bash: (command: string) => sandbox.bash.exec(command),
+ *       },
+ *     });
+ *
+ *     return agent.run('Create a React component that shows "Hello"');
+ *   },
+ * });
+ *
+ * // Module is auto-loaded if build succeeded
+ * if (run.module) {
+ *   const App = run.module.App as React.ComponentType;
+ *   return <App />;
+ * }
+ * ```
+ *
+ * @example Handling all failure modes
+ * ```ts
+ * const run = await buildWithSandbox({
+ *   build: async (sandbox) => myAgent.run('...'),
+ * });
+ *
+ * // Check what happened
+ * if (run.error) {
+ *   console.log('Agent failed:', run.error.message);
+ * }
+ * if (run.moduleError) {
+ *   console.log('Module failed to load:', run.moduleError.message);
+ * }
+ *
+ * // Module available even if agent errored (if build succeeded first)
+ * if (run.module) {
+ *   const App = run.module.App as React.ComponentType;
+ *   return <App />;
+ * }
+ *
+ * // No module - check why
+ * if (!run.bundle) {
+ *   console.log('No build was produced');
+ * }
+ * ```
+ */
+export declare function buildWithSandbox<T>(options: BuildWithSandboxOptions<T>): Promise<BuildResult<T>>;
+/**
+ * Options for creating a reusable builder function.
+ */
+export interface CreateBuilderOptions<T> {
+    /**
+     * Existing sandbox to reuse across all calls.
+     *
+     * When provided, the same sandbox is used for every call to the returned
+     * builder function. Files and state persist between runs—useful for
+     * iterative workflows where you want to build on previous work.
+     *
+     * @example
+     * ```ts
+     * const sandbox = await createSandbox({
+     *   initialFiles: { '/src/utils.ts': 'export const PI = 3.14;' },
+     * });
+     *
+     * const runAgent = createBuilder({
+     *   sandbox, // Reused across all calls
+     *   build: async (sb, prompt) => myAgent.run(sb, prompt),
+     * });
+     *
+     * await runAgent("Create a circle component"); // Uses existing utils.ts
+     * await runAgent("Add a square component");    // Still has circle + utils
+     * ```
+     */
+    sandbox?: Sandbox;
+    /**
+     * Options for creating fresh sandboxes (only used if `sandbox` is not provided).
+     *
+     * Each call to the returned builder function creates a new sandbox with
+     * these options. Use this when you want isolated runs.
+     *
+     * @example
+     * ```ts
+     * const runAgent = createBuilder({
+     *   sandboxOptions: {
+     *     sharedModules: ['react', 'react-dom/client'],
+     *   },
+     *   build: async (sandbox, prompt) => myAgent.run(sandbox, prompt),
+     * });
+     *
+     * // Each call gets a fresh sandbox
+     * await runAgent("Create a counter");  // Fresh sandbox
+     * await runAgent("Create a todo list"); // Another fresh sandbox
+     * ```
+     */
+    sandboxOptions?: SandboxOptions;
+    /**
+     * The function to build with the sandbox and prompt.
+     *
+     * This receives the sandbox and the prompt string, and should return
+     * whatever result your agent produces.
+     *
+     * @example
+     * ```ts
+     * const runAgent = createBuilder({
+     *   build: async (sandbox, prompt) => {
+     *     const agent = new MyAgent({
+     *       tools: { bash: sandbox.bash.exec },
+     *     });
+     *     return agent.run(prompt);
+     *   },
+     * });
+     * ```
+     */
+    build: (sandbox: Sandbox, prompt: string) => Promise<T>;
+}
+/**
+ * Create a reusable builder function for running prompts in a sandbox.
+ *
+ * This wraps `buildWithSandbox()` to create a convenient function that
+ * just takes a prompt. Define your agent logic once, then call it with
+ * different prompts.
+ *
+ * **Sandbox behavior:**
+ * - If you provide `sandbox`: The same sandbox is reused for every call
+ *   (files persist, good for iteration)
+ * - If you provide `sandboxOptions` (or nothing): A fresh sandbox is created
+ *   for each call (isolated runs)
+ *
+ * @example Basic usage
+ * ```ts
+ * import { createBuilder } from 'sandlot';
+ *
+ * const runAgent = createBuilder({
+ *   sandboxOptions: { sharedModules: ['react', 'react-dom/client'] },
+ *   build: async (sandbox, prompt) => {
+ *     const agent = new MyAgent({ tools: { bash: sandbox.bash.exec } });
+ *     return agent.run(prompt);
+ *   },
+ * });
+ *
+ * // Use it multiple times with different prompts
+ * const result1 = await runAgent("Create a counter component");
+ * const result2 = await runAgent("Create a todo list");
+ *
+ * if (result1.module?.App) {
+ *   const Counter = result1.module.App as React.ComponentType;
+ * }
+ * ```
+ *
+ * @example Iterative workflow with shared sandbox
+ * ```ts
+ * const sandbox = await createSandbox();
+ *
+ * const runAgent = createBuilder({
+ *   sandbox, // Same sandbox for all calls
+ *   build: async (sb, prompt) => myAgent.run(sb, prompt),
+ * });
+ *
+ * // First prompt creates initial component
+ * await runAgent("Create a button component");
+ *
+ * // Second prompt can build on the first
+ * await runAgent("Add a click counter to the button");
+ * ```
+ */
+export declare function createBuilder<T>(options: CreateBuilderOptions<T>): (prompt: string) => Promise<BuildResult<T>>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAiB,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C;;GAEG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B;;OAEG;IACH,MAAM,EAAE,CAAC,GAAG,SAAS,CAAC;IAEtB;;;;;OAKG;IACH,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAEpB;;;;;;;;OAQG;IACH,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAE5B;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAEvC;;;;;;;OAOG;IACH,WAAW,EAAE,KAAK,GAAG,IAAI,CAAC;IAE1B;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAsCzB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC/B,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAW7C"}