sandlot 0.1.1 → 0.1.3

package/src/bundler.ts

@@ -1,7 +1,32 @@
 import type { IFileSystem } from "just-bash/browser";
-import * as esbuild from "esbuild-wasm";
+import type * as EsbuildTypes from "esbuild-wasm";
 import { getPackageManifest, resolveToEsmUrl } from "./packages";
-import { getSharedModuleRuntimeCode } from "./shared-modules";
+import { getSharedModuleRuntimeCode, getSharedModuleExports } from "./shared-modules";
+
+// Lazily loaded esbuild module - loaded from CDN to avoid bundler issues
+let esbuild: typeof EsbuildTypes | null = null;
+
+async function getEsbuild(): Promise<typeof EsbuildTypes> {
+  if (esbuild) return esbuild;
+
+  // Load esbuild-wasm from esm.sh CDN to avoid bundler transformation issues
+  // esm.sh provides proper ESM wrappers for npm packages
+  const cdnUrl = `https://esm.sh/esbuild-wasm@${ESBUILD_VERSION}`;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const mod: any = await import(/* @vite-ignore */ cdnUrl);
+
+  // esm.sh typically provides both default and named exports
+  esbuild = mod.default ?? mod;
+
+  // Verify we have the initialize function
+  if (typeof esbuild?.initialize !== 'function') {
+    console.error('esbuild-wasm module structure:', mod);
+    throw new Error('Failed to load esbuild-wasm: initialize function not found');
+  }
+
+  return esbuild;
+}
 
 /**
  * How to handle npm package imports (bare imports like "react").
@@ -96,7 +121,7 @@ export interface BundleResult {
   /**
    * Any warnings from esbuild
    */
-  warnings: esbuild.Message[];
+  warnings: EsbuildTypes.Message[];
 
   /**
    * List of files that were included in the bundle
@@ -104,6 +129,11 @@ export interface BundleResult {
   includedFiles: string[];
 }
 
+/**
+ * esbuild-wasm version - MUST match the version in package.json dependencies
+ */
+const ESBUILD_VERSION = "0.27.2";
+
 // Track initialization state
 let initialized = false;
 let initPromise: Promise<void> | null = null;
@@ -112,9 +142,27 @@ let initPromise: Promise<void> | null = null;
  * Get the esbuild-wasm binary URL based on the installed version
  */
 function getWasmUrl(): string {
-  // Use unpkg CDN to fetch the WASM binary matching our installed version
-  const version = "0.27.2"; // Match installed version
-  return `https://unpkg.com/esbuild-wasm@${version}/esbuild.wasm`;
+  return `https://unpkg.com/esbuild-wasm@${ESBUILD_VERSION}/esbuild.wasm`;
+}
+
+/**
+ * Check if the browser environment supports cross-origin isolation.
+ * This is needed for SharedArrayBuffer which esbuild-wasm may use.
+ */
+function checkCrossOriginIsolation(): void {
+  if (typeof window === "undefined") return; // Not in browser
+
+  // crossOriginIsolated is true when COOP/COEP headers are set correctly
+  if (!window.crossOriginIsolated) {
+    console.warn(
+      "[sandlot] Cross-origin isolation is not enabled. " +
+      "esbuild-wasm may have reduced performance or fail on some browsers.\n" +
+      "To enable, add these headers to your dev server:\n" +
+      "  Cross-Origin-Embedder-Policy: require-corp\n" +
+      "  Cross-Origin-Opener-Policy: same-origin\n" +
+      "In Vite, add a plugin to configureServer. See sandlot README for details."
+    );
+  }
 }
 
 /**
@@ -129,9 +177,14 @@ export async function initBundler(): Promise<void> {
     return;
   }
 
-  initPromise = esbuild.initialize({
-    wasmURL: getWasmUrl(),
-  });
+  checkCrossOriginIsolation();
+
+  initPromise = (async () => {
+    const es = await getEsbuild();
+    await es.initialize({
+      wasmURL: getWasmUrl(),
+    });
+  })();
 
   await initPromise;
   initialized = true;
@@ -147,7 +200,7 @@ function isBareImport(path: string): boolean {
 /**
  * Get the appropriate loader based on file extension
  */
-function getLoader(path: string): esbuild.Loader {
+function getLoader(path: string): EsbuildTypes.Loader {
   const ext = path.split(".").pop()?.toLowerCase();
   switch (ext) {
     case "ts":
@@ -207,7 +260,7 @@ function matchesSharedModule(importPath: string, sharedModuleIds: Set<string>):
 /**
  * Create an esbuild plugin that reads from a virtual filesystem
  */
-function createVfsPlugin(options: VfsPluginOptions): esbuild.Plugin {
+function createVfsPlugin(options: VfsPluginOptions): EsbuildTypes.Plugin {
   const {
     fs,
     entryPoint,
@@ -303,27 +356,14 @@ function createVfsPlugin(options: VfsPluginOptions): esbuild.Plugin {
 
       // Load shared modules from the registry
       build.onLoad({ filter: /.*/, namespace: "sandlot-shared" }, (args) => {
-        // Generate code that looks up the module from the global registry
-        const contents = `export default ${getSharedModuleRuntimeCode(args.path)};
-export * from ${JSON.stringify(args.path)};
-// Re-export all named exports by importing from registry
-const __mod__ = ${getSharedModuleRuntimeCode(args.path)};
-for (const __k__ in __mod__) {
-  if (__k__ !== 'default') Object.defineProperty(exports, __k__, { 
-    enumerable: true, 
-    get: function() { return __mod__[__k__]; } 
-  });
-}`;
-
-        // For ESM format, we need a different approach
-        // Generate a simple module that re-exports from registry
-        const esmContents = `
+        // Generate ESM code that re-exports from the shared module registry
+        const contents = `
 const __sandlot_mod__ = ${getSharedModuleRuntimeCode(args.path)};
 export default __sandlot_mod__.default ?? __sandlot_mod__;
 ${generateNamedExports(args.path)}
 `;
         return {
-          contents: esmContents.trim(),
+          contents: contents.trim(),
           loader: 'js'
         };
       });
@@ -349,39 +389,26 @@ ${generateNamedExports(args.path)}
 }
 
 /**
- * Generate named export statements for common React exports.
- * This is a pragmatic approach - for full generality, we'd need to
- * introspect the actual module, but that's not possible at build time.
+ * Generate named export statements for shared modules.
+ * 
+ * Uses dynamically discovered exports from the SharedModuleRegistry,
+ * which are populated when registerSharedModules() is called.
+ * 
+ * If the module wasn't registered (or has no enumerable exports),
+ * returns a comment - named imports won't work but default import will.
  */
 function generateNamedExports(moduleId: string): string {
-  // Common exports for well-known modules
-  const knownExports: Record<string, string[]> = {
-    '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 = getSharedModuleExports(moduleId);
 
-  const exports = knownExports[moduleId];
-  if (!exports) {
-    // For unknown modules, generate a proxy that re-exports everything
-    return `
-// Dynamic re-export for unknown module
-export const __moduleProxy__ = __sandlot_mod__;
-`;
+  if (exports.length > 0) {
+    return exports
+      .map(name => `export const ${name} = __sandlot_mod__.${name};`)
+      .join('\n');
   }
 
-  return exports
-    .map(name => `export const ${name} = __sandlot_mod__.${name};`)
-    .join('\n');
+  // Module not registered or has no enumerable exports
+  // Default import will still work: import foo from 'module'
+  return `// No exports discovered for "${moduleId}" - use default import or call registerSharedModules() first`;
 }
 
 /**
@@ -389,7 +416,7 @@ export const __moduleProxy__ = __sandlot_mod__;
  *
  * @example
  * ```ts
- * const fs = IndexedDbFs.createInMemory({
+ * const fs = Filesystem.create({
  *   initialFiles: {
  *     "/src/index.ts": "export const hello = 'world';",
  *     "/src/utils.ts": "export function add(a: number, b: number) { return a + b; }",
@@ -445,7 +472,8 @@ export async function bundle(options: BundleOptions): Promise<BundleResult> {
     sharedModuleIds,
   });
 
-  const result = await esbuild.build({
+  const es = await getEsbuild();
+  const result = await es.build({
     entryPoints: [normalizedEntry],
     bundle: true,
     write: false,
@@ -456,6 +484,7 @@ export async function bundle(options: BundleOptions): Promise<BundleResult> {
     target,
     external,
     plugins: [plugin],
+    jsx: "automatic",
   });
 
   const code = result.outputFiles?.[0]?.text ?? "";

package/src/commands/compile.ts

@@ -0,0 +1,236 @@
+/**
+ * Compile-related commands: tsc and build
+ */
+
+import { defineCommand, type CommandContext } from "just-bash/browser";
+import { typecheck, formatDiagnosticsForAgent, type TypecheckResult } from "../typechecker";
+import { bundle } from "../bundler";
+import { loadModule } from "../loader";
+import { type CommandDeps, formatEsbuildMessages } from "./types";
+
+/**
+ * Create the `tsc` command for type checking
+ */
+export function createTscCommand(deps: CommandDeps) {
+  const { fs, libFiles, tsconfigPath } = deps;
+
+  return defineCommand("tsc", async (args, _ctx: CommandContext) => {
+    const entryPoint = args[0];
+    if (!entryPoint) {
+      return {
+        stdout: "",
+        stderr: `Usage: tsc <entry-point>\n\nExample: tsc /src/index.ts\n`,
+        exitCode: 1,
+      };
+    }
+
+    try {
+      // Check if entry point exists
+      if (!(await fs.exists(entryPoint))) {
+        return {
+          stdout: "",
+          stderr: `Error: Entry point not found: ${entryPoint}\n`,
+          exitCode: 1,
+        };
+      }
+
+      const result = await typecheck({
+        fs,
+        entryPoint,
+        tsconfigPath,
+        libFiles,
+      });
+
+      if (result.hasErrors) {
+        const formatted = formatDiagnosticsForAgent(result.diagnostics);
+        return {
+          stdout: "",
+          stderr: formatted + "\n",
+          exitCode: 1,
+        };
+      }
+
+      const checkedCount = result.checkedFiles.length;
+      const warningCount = result.diagnostics.filter((d) => d.category === "warning").length;
+
+      let output = `Type check passed. Checked ${checkedCount} file(s).\n`;
+      if (warningCount > 0) {
+        output += `\nWarnings:\n${formatDiagnosticsForAgent(result.diagnostics.filter((d) => d.category === "warning"))}\n`;
+      }
+
+      return {
+        stdout: output,
+        stderr: "",
+        exitCode: 0,
+      };
+    } catch (err) {
+      return {
+        stdout: "",
+        stderr: `Type check failed: ${err instanceof Error ? err.message : String(err)}\n`,
+        exitCode: 1,
+      };
+    }
+  });
+}
+
+/**
+ * Create the `build` command for bundling (with automatic type checking)
+ */
+export function createBuildCommand(deps: CommandDeps) {
+  const { fs, libFiles, tsconfigPath, onBuild, getValidation, sharedModules } = deps;
+
+  return defineCommand("build", async (args, _ctx: CommandContext) => {
+    // Parse arguments
+    let entryPoint: string | null = null;
+    let skipTypecheck = false;
+    let minify = false;
+    let format: "esm" | "iife" | "cjs" = "esm";
+
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === "--skip-typecheck" || arg === "-s") {
+        skipTypecheck = true;
+      } else if (arg === "--minify" || arg === "-m") {
+        minify = true;
+      } else if ((arg === "--format" || arg === "-f") && args[i + 1]) {
+        const f = args[++i]!.toLowerCase();
+        if (f === "esm" || f === "iife" || f === "cjs") {
+          format = f;
+        }
+      } else if (!arg!.startsWith("-")) {
+        entryPoint = arg!;
+      }
+    }
+
+    // Entry point is required
+    if (!entryPoint) {
+      return {
+        stdout: "",
+        stderr: `Usage: build <entry-point> [options]\n\nOptions:\n  --skip-typecheck, -s  Skip type checking\n  --minify, -m          Minify output\n  --format, -f <fmt>    Output format (esm|iife|cjs)\n\nExample: build /src/index.ts\n`,
+        exitCode: 1,
+      };
+    }
+
+    try {
+      // Check if entry point exists
+      if (!(await fs.exists(entryPoint))) {
+        return {
+          stdout: "",
+          stderr: `Error: Entry point not found: ${entryPoint}\n`,
+          exitCode: 1,
+        };
+      }
+
+      // Step 1: Type check (unless skipped)
+      let typecheckResult: TypecheckResult | null = null;
+      if (!skipTypecheck) {
+        typecheckResult = await typecheck({
+          fs,
+          entryPoint,
+          tsconfigPath,
+          libFiles,
+        });
+
+        if (typecheckResult.hasErrors) {
+          const formatted = formatDiagnosticsForAgent(typecheckResult.diagnostics);
+          return {
+            stdout: "",
+            stderr: `Build failed: Type errors found.\n\n${formatted}\n`,
+            exitCode: 1,
+          };
+        }
+      }
+
+      // Step 2: Bundle
+      const bundleResult = await bundle({
+        fs,
+        entryPoint,
+        format,
+        minify,
+        sharedModules,
+      });
+
+      // Step 3: Load module
+      let loadedModule: Record<string, unknown>;
+      try {
+        loadedModule = await loadModule<Record<string, unknown>>(bundleResult);
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        return {
+          stdout: "",
+          stderr: `Build failed: Module failed to load.\n\n${errorMessage}\n`,
+          exitCode: 1,
+        };
+      }
+
+      // Step 4: Validate (if validation function is set)
+      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.\n\n${errorMessage}\n`,
+            exitCode: 1,
+          };
+        }
+      }
+
+      // Invoke callback with build output (bundle + validated module)
+      if (onBuild) {
+        await onBuild({ bundle: bundleResult, module: validatedModule });
+      }
+
+      // Build success message
+      let output = `Build successful!\n`;
+      output += `Entry: ${entryPoint}\n`;
+      output += `Format: ${format}\n`;
+      output += `Size: ${(bundleResult.code.length / 1024).toFixed(2)} KB\n`;
+
+      if (typecheckResult) {
+        output += `Type checked: ${typecheckResult.checkedFiles.length} file(s)\n`;
+      }
+
+      output += `Bundled: ${bundleResult.includedFiles.length} file(s)\n`;
+
+      // Show exports for visibility
+      const exportNames = Object.keys(loadedModule).filter((k) => !k.startsWith("__"));
+      if (exportNames.length > 0) {
+        output += `Exports: ${exportNames.join(", ")}\n`;
+      }
+
+      if (validateFn) {
+        output += `Validation: passed\n`;
+      }
+
+      // Include warnings if any
+      if (bundleResult.warnings.length > 0) {
+        output += `\nBuild warnings:\n${formatEsbuildMessages(bundleResult.warnings)}\n`;
+      }
+
+      if (typecheckResult) {
+        const warnings = typecheckResult.diagnostics.filter((d) => d.category === "warning");
+        if (warnings.length > 0) {
+          output += `\nType warnings:\n${formatDiagnosticsForAgent(warnings)}\n`;
+        }
+      }
+
+      return {
+        stdout: output,
+        stderr: "",
+        exitCode: 0,
+      };
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      return {
+        stdout: "",
+        stderr: `Build failed: ${errorMessage}\n`,
+        exitCode: 1,
+      };
+    }
+  });
+}

package/src/commands/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Command factories for sandbox bash environments.
+ *
+ * Pure factories that create commands for type checking, bundling,
+ * package management, and code execution.
+ * No global state - all dependencies are passed in explicitly.
+ */
+
+// Types and utilities
+export {
+  type CommandDeps,
+  type BuildOutput,
+  type ValidateFn,
+  type RunContext,
+  type RunOptions,
+  type RunResult,
+  formatEsbuildMessages,
+} from "./types";
+
+// Compile commands (tsc, build)
+export { createTscCommand, createBuildCommand } from "./compile";
+
+// Package management commands (install, uninstall, list)
+export {
+  createInstallCommand,
+  createUninstallCommand,
+  createListCommand,
+} from "./packages";
+
+// Run command
+export { createRunCommand } from "./run";
+
+// Re-import for createDefaultCommands
+import type { CommandDeps } from "./types";
+import { createTscCommand, createBuildCommand } from "./compile";
+import { createInstallCommand, createUninstallCommand, createListCommand } from "./packages";
+import { createRunCommand } from "./run";
+
+/**
+ * Create all default sandbox commands
+ */
+export function createDefaultCommands(deps: CommandDeps) {
+  return [
+    createTscCommand(deps),
+    createBuildCommand(deps),
+    createRunCommand(deps),
+    createInstallCommand(deps),
+    createUninstallCommand(deps),
+    createListCommand(deps),
+  ];
+}

package/src/commands/packages.ts

@@ -0,0 +1,154 @@
+/**
+ * Package management commands: install, uninstall, list
+ */
+
+import { defineCommand, type CommandContext } from "just-bash/browser";
+import { installPackage, uninstallPackage, listPackages } from "../packages";
+import type { CommandDeps } from "./types";
+
+/**
+ * Create the `install` command for adding packages from npm
+ */
+export function createInstallCommand(deps: CommandDeps) {
+  const { fs, typesCache } = deps;
+
+  return defineCommand("install", async (args, _ctx: CommandContext) => {
+    if (args.length === 0) {
+      return {
+        stdout: "",
+        stderr: "Usage: install <package>[@version] [...packages]\n\nExamples:\n  install react\n  install lodash@4.17.21\n  install @tanstack/react-query@5\n",
+        exitCode: 1,
+      };
+    }
+
+    const results: string[] = [];
+    let hasError = false;
+
+    for (const packageSpec of args) {
+      try {
+        const result = await installPackage(fs, packageSpec!, { cache: typesCache });
+
+        let status = `+ ${result.name}@${result.version}`;
+        if (result.typesInstalled) {
+          status += ` (${result.typeFilesCount} type file${result.typeFilesCount !== 1 ? "s" : ""})`;
+          if (result.fromCache) {
+            status += " [cached]";
+          }
+        } else if (result.typesError) {
+          status += ` (no types: ${result.typesError})`;
+        }
+        results.push(status);
+      } catch (err) {
+        hasError = true;
+        const message = err instanceof Error ? err.message : String(err);
+        results.push(`x ${packageSpec}: ${message}`);
+      }
+    }
+
+    const output = results.join("\n") + "\n";
+
+    if (hasError) {
+      return {
+        stdout: "",
+        stderr: output,
+        exitCode: 1,
+      };
+    }
+
+    return {
+      stdout: output,
+      stderr: "",
+      exitCode: 0,
+    };
+  });
+}
+
+/**
+ * Create the `uninstall` command for removing packages
+ */
+export function createUninstallCommand(deps: CommandDeps) {
+  const { fs } = deps;
+
+  return defineCommand("uninstall", async (args, _ctx: CommandContext) => {
+    if (args.length === 0) {
+      return {
+        stdout: "",
+        stderr: "Usage: uninstall <package> [...packages]\n",
+        exitCode: 1,
+      };
+    }
+
+    const results: string[] = [];
+    let hasError = false;
+
+    for (const packageName of args) {
+      try {
+        const removed = await uninstallPackage(fs, packageName!);
+        if (removed) {
+          results.push(`- ${packageName}`);
+        } else {
+          results.push(`x ${packageName}: not installed`);
+          hasError = true;
+        }
+      } catch (err) {
+        hasError = true;
+        const message = err instanceof Error ? err.message : String(err);
+        results.push(`x ${packageName}: ${message}`);
+      }
+    }
+
+    const output = results.join("\n") + "\n";
+
+    if (hasError) {
+      return {
+        stdout: "",
+        stderr: output,
+        exitCode: 1,
+      };
+    }
+
+    return {
+      stdout: output,
+      stderr: "",
+      exitCode: 0,
+    };
+  });
+}
+
+/**
+ * Create the `list` command (alias: `ls`) for showing installed packages
+ */
+export function createListCommand(deps: CommandDeps) {
+  const { fs } = deps;
+
+  return defineCommand("list", async (_args, _ctx: CommandContext) => {
+    try {
+      const packages = await listPackages(fs);
+
+      if (packages.length === 0) {
+        return {
+          stdout: "No packages installed.\n",
+          stderr: "",
+          exitCode: 0,
+        };
+      }
+
+      const output = packages
+        .map((pkg) => `${pkg.name}@${pkg.version}`)
+        .join("\n") + "\n";
+
+      return {
+        stdout: output,
+        stderr: "",
+        exitCode: 0,
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        stdout: "",
+        stderr: `Failed to list packages: ${message}\n`,
+        exitCode: 1,
+      };
+    }
+  });
+}