sandlot 0.1.3 → 0.2.0

package/src/browser/bundler.ts

@@ -0,0 +1,294 @@
+/**
+ * Browser bundler implementation using esbuild-wasm.
+ *
+ * This module handles WASM initialization and provides a bundler that
+ * works entirely in the browser.
+ */
+
+import type * as EsbuildTypes from "esbuild-wasm";
+import type {
+  IBundler,
+  BundleOptions,
+  BundleResult,
+  BundleWarning,
+  BundleError,
+} from "../types";
+import {
+  createVfsPlugin,
+  isEsbuildBuildFailure,
+  convertEsbuildMessage,
+} from "../core/bundler-utils";
+
+/**
+ * esbuild-wasm version - should match what's in package.json
+ */
+const ESBUILD_VERSION = "0.27.2";
+
+// =============================================================================
+// Global Singleton for esbuild-wasm initialization
+// =============================================================================
+// esbuild-wasm can only be initialized once per page. We track this globally
+// so multiple EsbuildWasmBundler instances can share the same initialization.
+
+interface EsbuildGlobalState {
+  esbuild: typeof EsbuildTypes | null;
+  initialized: boolean;
+  initPromise: Promise<void> | null;
+}
+
+const GLOBAL_KEY = "__sandlot_esbuild__";
+
+function getGlobalState(): EsbuildGlobalState {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const g = globalThis as any;
+  if (!g[GLOBAL_KEY]) {
+    g[GLOBAL_KEY] = {
+      esbuild: null,
+      initialized: false,
+      initPromise: null,
+    };
+  }
+  return g[GLOBAL_KEY];
+}
+
+export interface EsbuildWasmBundlerOptions {
+  /**
+   * URL to the esbuild WASM file.
+   * @default "https://unpkg.com/esbuild-wasm@{version}/esbuild.wasm"
+   */
+  wasmUrl?: string;
+
+  /**
+   * URL to load esbuild-wasm module from.
+   * @default "https://esm.sh/esbuild-wasm@{version}"
+   */
+  esbuildUrl?: string;
+
+  /**
+   * Base URL for CDN imports.
+   * npm imports like "lodash" are rewritten to "{cdnBaseUrl}/lodash@{version}".
+   * @default "https://esm.sh"
+   */
+  cdnBaseUrl?: string;
+
+  /**
+   * Whether to initialize immediately on construction.
+   * If false, initialization happens lazily on first bundle() call.
+   * @default false
+   */
+  eagerInit?: boolean;
+}
+
+/**
+ * Browser bundler implementation using esbuild-wasm.
+ *
+ * Handles WASM initialization internally. The first bundle() call
+ * will wait for initialization if not already complete.
+ *
+ * @example
+ * ```ts
+ * const bundler = new EsbuildWasmBundler();
+ * await bundler.initialize();
+ *
+ * const result = await bundler.bundle({
+ *   fs: myFilesystem,
+ *   entryPoint: "/src/index.ts",
+ * });
+ * ```
+ */
+export class EsbuildWasmBundler implements IBundler {
+  private options: EsbuildWasmBundlerOptions;
+
+  constructor(options: EsbuildWasmBundlerOptions = {}) {
+    this.options = {
+      cdnBaseUrl: "https://esm.sh",
+      ...options,
+    };
+
+    if (options.eagerInit) {
+      this.initialize();
+    }
+  }
+
+  /**
+   * Initialize the esbuild WASM module.
+   * Called automatically on first bundle() if not already initialized.
+   *
+   * Uses a global singleton pattern since esbuild-wasm can only be
+   * initialized once per page.
+   */
+  async initialize(): Promise<void> {
+    const state = getGlobalState();
+
+    // Already initialized globally
+    if (state.initialized && state.esbuild) {
+      return;
+    }
+
+    // Another instance is initializing - wait for it
+    if (state.initPromise) {
+      await state.initPromise;
+      return;
+    }
+
+    // We're the first - do the initialization
+    state.initPromise = this.doInitialize(state);
+    await state.initPromise;
+  }
+
+  private async doInitialize(state: EsbuildGlobalState): Promise<void> {
+    // Check for cross-origin isolation (needed for SharedArrayBuffer)
+    this.checkCrossOriginIsolation();
+
+    // Load esbuild-wasm from CDN
+    const esbuildUrl =
+      this.options.esbuildUrl ?? `https://esm.sh/esbuild-wasm@${ESBUILD_VERSION}`;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mod: any = await import(/* @vite-ignore */ esbuildUrl);
+    const esbuild = mod.default ?? mod;
+
+    if (typeof esbuild?.initialize !== "function") {
+      throw new Error(
+        "Failed to load esbuild-wasm: initialize function not found"
+      );
+    }
+
+    // Initialize with WASM binary
+    const wasmUrl =
+      this.options.wasmUrl ??
+      `https://unpkg.com/esbuild-wasm@${ESBUILD_VERSION}/esbuild.wasm`;
+
+    await esbuild.initialize({ wasmURL: wasmUrl });
+
+    // Store in global state
+    state.esbuild = esbuild;
+    state.initialized = true;
+  }
+
+  /**
+   * Get the initialized esbuild instance.
+   */
+  private getEsbuild(): typeof EsbuildTypes {
+    const state = getGlobalState();
+    if (!state.esbuild) {
+      throw new Error("esbuild not initialized - call initialize() first");
+    }
+    return state.esbuild;
+  }
+
+  private checkCrossOriginIsolation(): void {
+    if (typeof window === "undefined") return;
+
+    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 server:\n" +
+        "  Cross-Origin-Embedder-Policy: require-corp\n" +
+        "  Cross-Origin-Opener-Policy: same-origin"
+      );
+    }
+  }
+
+  async bundle(options: BundleOptions): Promise<BundleResult> {
+    await this.initialize();
+
+    const esbuild = this.getEsbuild();
+
+    const {
+      fs,
+      entryPoint,
+      installedPackages = {},
+      sharedModules = [],
+      sharedModuleRegistry,
+      external = [],
+      format = "esm",
+      minify = false,
+      sourcemap = false,
+      target = ["es2020"],
+    } = options;
+
+    // Normalize entry point to absolute path
+    const normalizedEntry = entryPoint.startsWith("/")
+      ? entryPoint
+      : `/${entryPoint}`;
+
+    // Verify entry point exists
+    if (!fs.exists(normalizedEntry)) {
+      return {
+        success: false,
+        errors: [{ text: `Entry point not found: ${normalizedEntry}` }],
+        warnings: [],
+      };
+    }
+
+    // Track files included in the bundle
+    const includedFiles = new Set<string>();
+
+    // Create the VFS plugin
+    const plugin = createVfsPlugin({
+      fs,
+      entryPoint: normalizedEntry,
+      installedPackages,
+      sharedModules: new Set(sharedModules),
+      sharedModuleRegistry: sharedModuleRegistry ?? null,
+      cdnBaseUrl: this.options.cdnBaseUrl!,
+      includedFiles,
+    });
+
+    try {
+      // Run esbuild
+      const result = await esbuild.build({
+        entryPoints: [normalizedEntry],
+        bundle: true,
+        write: false,
+        format,
+        minify,
+        sourcemap: sourcemap ? "inline" : false,
+        target,
+        external,
+        // Cast to esbuild's Plugin type since our minimal interface is compatible
+        plugins: [plugin as EsbuildTypes.Plugin],
+        jsx: "automatic",
+      });
+
+      const code = result.outputFiles?.[0]?.text ?? "";
+
+      // Convert esbuild warnings to our format
+      const warnings: BundleWarning[] = result.warnings.map((w) =>
+        convertEsbuildMessage(w)
+      );
+
+      return {
+        success: true,
+        code,
+        warnings,
+        includedFiles: Array.from(includedFiles),
+      };
+    } catch (err) {
+      // esbuild throws BuildFailure with .errors array
+      if (isEsbuildBuildFailure(err)) {
+        const errors: BundleError[] = err.errors.map((e) =>
+          convertEsbuildMessage(e)
+        );
+        const warnings: BundleWarning[] = err.warnings.map((w) =>
+          convertEsbuildMessage(w)
+        );
+        return {
+          success: false,
+          errors,
+          warnings,
+        };
+      }
+
+      // Unknown error - wrap it
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        success: false,
+        errors: [{ text: message }],
+        warnings: [],
+      };
+    }
+  }
+}

package/src/browser/executor.ts

@@ -0,0 +1,71 @@
+/**
+ * Main thread executor for browser environments.
+ *
+ * This executor runs code directly in the main thread. It provides no
+ * isolation from the host environment - use only for trusted code.
+ *
+ * For untrusted code, consider using a Worker or iframe-based executor
+ * that provides proper sandboxing.
+ */
+
+import type { IExecutor } from "../types";
+import { createBasicExecutor, type BasicExecutorOptions } from "../core/executor";
+
+/**
+ * Options for creating a MainThreadExecutor.
+ */
+export type MainThreadExecutorOptions = BasicExecutorOptions;
+
+/**
+ * Load a module from code using a Blob URL.
+ * The URL is revoked after import to avoid memory leaks.
+ */
+async function loadModuleFromBlobUrl(code: string): Promise<Record<string, unknown>> {
+  const blob = new Blob([code], { type: "application/javascript" });
+  const url = URL.createObjectURL(blob);
+  try {
+    return await import(/* @vite-ignore */ url);
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+/**
+ * Executor that runs code in the main browser thread.
+ *
+ * WARNING: This executor provides NO isolation. The executed code has
+ * full access to the page's DOM, global variables, and network.
+ * Only use for trusted code (e.g., code you're developing).
+ *
+ * @example
+ * ```ts
+ * const executor = createMainThreadExecutor();
+ * const result = await executor.execute(bundledCode, {
+ *   entryExport: 'main',
+ *   context: { args: ['--verbose'] },
+ *   timeout: 5000,
+ * });
+ * console.log(result.logs);
+ * ```
+ */
+export class MainThreadExecutor implements IExecutor {
+  private executor: IExecutor;
+
+  constructor(options: MainThreadExecutorOptions = {}) {
+    this.executor = createBasicExecutor(loadModuleFromBlobUrl, options);
+  }
+
+  execute: IExecutor["execute"] = (...args) => this.executor.execute(...args);
+}
+
+/**
+ * Create a main thread executor.
+ *
+ * @param options - Executor options
+ * @returns A new MainThreadExecutor instance
+ */
+export function createMainThreadExecutor(
+  options?: MainThreadExecutorOptions
+): MainThreadExecutor {
+  return new MainThreadExecutor(options);
+}

package/src/browser/index.ts

@@ -0,0 +1,57 @@
+// =============================================================================
+// Sandlot v2 - Browser Entry Point
+// =============================================================================
+//
+// Browser-specific implementations for Sandlot.
+// Uses esbuild-wasm for bundling.
+//
+// Note: EsmTypesResolver is platform-independent and exported from the main
+// "sandlot" entry point, not from "sandlot/browser".
+//
+// =============================================================================
+
+// =============================================================================
+// Browser Polyfills - inject before anything else loads
+// =============================================================================
+//
+// Some dependencies (like just-bash) reference Node.js globals.
+// Provide shims so they work in the browser without user configuration.
+//
+if (typeof window !== "undefined" && typeof globalThis.process === "undefined") {
+  (globalThis as Record<string, unknown>).process = {
+    env: {},
+    platform: "browser",
+    version: "v20.0.0",
+    browser: true,
+    cwd: () => "/",
+    nextTick: (fn: () => void) => setTimeout(fn, 0),
+  };
+}
+
+// -----------------------------------------------------------------------------
+// Typechecker (platform-agnostic: re-exported for convenience)
+// -----------------------------------------------------------------------------
+
+export { Typechecker, createTypechecker } from "../core/typechecker";
+export type { TypecheckerOptions } from "../core/typechecker";
+
+// -----------------------------------------------------------------------------
+// Bundler (browser-specific: uses esbuild-wasm)
+// -----------------------------------------------------------------------------
+
+export { EsbuildWasmBundler } from "./bundler";
+export type { EsbuildWasmBundlerOptions } from "./bundler";
+
+// -----------------------------------------------------------------------------
+// Executor (browser-specific: runs in main thread)
+// -----------------------------------------------------------------------------
+
+export { MainThreadExecutor, createMainThreadExecutor } from "./executor";
+export type { MainThreadExecutorOptions } from "./executor";
+
+// -----------------------------------------------------------------------------
+// Convenience Preset
+// -----------------------------------------------------------------------------
+
+export { createBrowserSandlot } from "./preset";
+export type { CreateBrowserSandlotOptions } from "./preset";

package/src/browser/preset.ts

@@ -0,0 +1,179 @@
+import { createSandlot } from "../core/sandlot";
+import {
+  EsmTypesResolver,
+  type EsmTypesResolverOptions,
+} from "../core/esm-types-resolver";
+import type { Sandlot, SandlotOptions } from "../types";
+import { EsbuildWasmBundler, type EsbuildWasmBundlerOptions } from "./bundler";
+import {
+  Typechecker,
+  type TypecheckerOptions,
+} from "../core/typechecker";
+import {
+  MainThreadExecutor,
+  type MainThreadExecutorOptions,
+} from "./executor";
+
+export interface CreateBrowserSandlotOptions
+  extends Omit<SandlotOptions, "bundler" | "typechecker" | "typesResolver" | "executor"> {
+  /**
+   * Custom bundler options, or a pre-configured bundler instance.
+   */
+  bundler?: EsbuildWasmBundlerOptions | SandlotOptions["bundler"];
+
+  /**
+   * Custom typechecker options, or a pre-configured typechecker instance.
+   * Set to `false` to disable type checking.
+   */
+  typechecker?:
+  | TypecheckerOptions
+  | SandlotOptions["typechecker"]
+  | false;
+
+  /**
+   * Custom types resolver options, or a pre-configured resolver instance.
+   * Set to `false` to disable type resolution.
+   */
+  typesResolver?:
+  | EsmTypesResolverOptions
+  | SandlotOptions["typesResolver"]
+  | false;
+
+  /**
+   * Custom executor options, or a pre-configured executor instance.
+   * Set to `false` to disable execution (sandbox.run() will throw).
+   * Defaults to MainThreadExecutor.
+   */
+  executor?:
+  | MainThreadExecutorOptions
+  | SandlotOptions["executor"]
+  | false;
+}
+
+/**
+ * Create a Sandlot instance pre-configured for browser environments.
+ *
+ * This is a convenience function that sets up sensible defaults:
+ * - EsbuildWasmBundler for bundling
+ * - Typechecker for type checking
+ * - FetchTypesResolver for npm type resolution
+ *
+ * @example Basic usage
+ * ```ts
+ * const sandlot = await createBrowserSandlot();
+ * const sandbox = await sandlot.createSandbox();
+ * ```
+ *
+ * @example With shared modules
+ * ```ts
+ * import React from "react";
+ * import ReactDOM from "react-dom/client";
+ *
+ * const sandlot = await createBrowserSandlot({
+ *   sharedModules: {
+ *     react: React,
+ *     "react-dom/client": ReactDOM,
+ *   },
+ * });
+ * ```
+ *
+ * @example Disable type checking for faster builds
+ * ```ts
+ * const sandlot = await createBrowserSandlot({
+ *   typechecker: false,
+ * });
+ * ```
+ */
+export async function createBrowserSandlot(
+  options: CreateBrowserSandlotOptions = {}
+): Promise<Sandlot> {
+  const { bundler, typechecker, typesResolver, executor, ...rest } = options;
+
+  // Create or use provided bundler
+  const bundlerInstance = isBundler(bundler)
+    ? bundler
+    : new EsbuildWasmBundler(bundler as EsbuildWasmBundlerOptions | undefined);
+
+  // Initialize bundler (loads WASM)
+  await bundlerInstance.initialize();
+
+  // Create or use provided typechecker
+  const typecheckerInstance =
+    typechecker === false
+      ? undefined
+      : isTypechecker(typechecker)
+        ? typechecker
+        : new Typechecker(
+          typechecker as TypecheckerOptions | undefined
+        );
+
+  // Create or use provided types resolver
+  const typesResolverInstance =
+    typesResolver === false
+      ? undefined
+      : isTypesResolver(typesResolver)
+        ? typesResolver
+        : new EsmTypesResolver(
+          typesResolver as EsmTypesResolverOptions | undefined
+        );
+
+  // Create or use provided executor (defaults to MainThreadExecutor)
+  const executorInstance =
+    executor === false
+      ? undefined
+      : isExecutor(executor)
+        ? executor
+        : new MainThreadExecutor(
+          executor as MainThreadExecutorOptions | undefined
+        );
+
+  return createSandlot({
+    ...rest,
+    bundler: bundlerInstance,
+    typechecker: typecheckerInstance,
+    typesResolver: typesResolverInstance,
+    executor: executorInstance,
+  });
+}
+
+// Type guards for detecting pre-configured instances
+
+function isBundler(
+  value: unknown
+): value is SandlotOptions["bundler"] & { initialize(): Promise<void> } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "bundle" in value &&
+    typeof (value as { bundle: unknown }).bundle === "function"
+  );
+}
+
+function isTypechecker(value: unknown): value is SandlotOptions["typechecker"] {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "typecheck" in value &&
+    typeof (value as { typecheck: unknown }).typecheck === "function"
+  );
+}
+
+function isTypesResolver(
+  value: unknown
+): value is SandlotOptions["typesResolver"] {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "resolveTypes" in value &&
+    typeof (value as { resolveTypes: unknown }).resolveTypes === "function"
+  );
+}
+
+function isExecutor(value: unknown): value is SandlotOptions["executor"] {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "execute" in value &&
+    typeof (value as { execute: unknown }).execute === "function"
+  );
+}