sandlot 0.2.0 → 0.2.2

package/src/commands/index.ts

@@ -12,7 +12,12 @@
 import { defineCommand, type CommandContext } from "just-bash/browser";
 import type { SandboxRef } from "./types";
 export type { SandboxRef } from "./types";
-export { formatSize, formatDiagnostics, formatBundleErrors } from "./types";
+export {
+  formatSize,
+  formatDiagnostics,
+  formatBundleErrors,
+  formatBuildFailure,
+} from "./types";
 
 /**
  * Create the main `sandlot` command with all subcommands.
@@ -96,7 +101,12 @@ Examples:
 // Build
 // =============================================================================
 
-import { formatSize, formatDiagnostics, formatBundleErrors } from "./types";
+import {
+  formatSize,
+  formatDiagnostics,
+  formatBundleErrors,
+  formatBuildFailure,
+} from "./types";
 
 async function handleBuild(sandboxRef: SandboxRef, args: (string | undefined)[]) {
   let entryPoint: string | undefined;
@@ -150,37 +160,9 @@ Examples:
 
   // Handle build failure
   if (!result.success) {
-    let stderr = `Build failed`;
-
-    switch (result.phase) {
-      case "entry":
-        stderr = `Build failed: ${result.message}\n`;
-        break;
-
-      case "typecheck":
-        if (result.diagnostics) {
-          const errors = result.diagnostics.filter((d) => d.severity === "error");
-          stderr = `Build failed: Type check errors\n\n${formatDiagnostics(errors)}\n`;
-        } else {
-          stderr = `Build failed: Type check errors\n`;
-        }
-        break;
-
-      case "bundle":
-        if (result.bundleErrors && result.bundleErrors.length > 0) {
-          stderr = `Build failed: Bundle errors\n\n${formatBundleErrors(result.bundleErrors)}\n`;
-        } else {
-          stderr = `Build failed: Bundle error\n`;
-        }
-        break;
-
-      default:
-        stderr = `Build failed: Unknown error\n`;
-    }
-
     return {
       stdout: "",
-      stderr,
+      stderr: formatBuildFailure(result),
       exitCode: 1,
     };
   }
@@ -249,16 +231,16 @@ Examples:
       const formatted = formatDiagnostics(errors);
       return {
         stdout: "",
-        stderr: `Type check failed:\n${formatted}\n`,
+        stderr: `Type check failed\n\n${formatted}\n`,
         exitCode: 1,
       };
     }
 
     const warnings = result.diagnostics.filter((d) => d.severity === "warning");
-    let output = `Type check passed.\n`;
+    let output = `Type check passed\n`;
 
     if (warnings.length > 0) {
-      output += `\nWarnings:\n${formatDiagnostics(warnings)}\n`;
+      output += `\nWarnings:\n\n${formatDiagnostics(warnings)}\n`;
     }
 
     return {
@@ -458,13 +440,9 @@ Examples:
     if (!result.success) {
       let stderr = "";
 
-      // Build failure
+      // Build failure - use the shared formatter
       if (result.buildFailure) {
-        stderr = `Run failed: Build error in ${result.buildFailure.phase} phase`;
-        if (result.buildFailure.message) {
-          stderr += `\n${result.buildFailure.message}`;
-        }
-        stderr += "\n";
+        stderr = formatBuildFailure(result.buildFailure, "Run failed");
       } else {
         // Execution failure
         stderr = `Run failed: ${result.error ?? "Unknown error"}\n`;

package/src/commands/types.ts

@@ -10,6 +10,7 @@ import type {
   InstallResult,
   UninstallResult,
   BuildResult,
+  BuildFailureDetails,
   TypecheckResult,
   SandboxBuildOptions,
   SandboxTypecheckOptions,
@@ -106,3 +107,38 @@ export function formatBundleErrors(errors: BundleError[]): string {
     })
     .join("\n\n");
 }
+
+/**
+ * Format a build failure for shell output.
+ * Used by both build and run commands for consistent error formatting.
+ *
+ * @param failure - The build failure details
+ * @param prefix - Optional prefix for the error message (default: "Build failed")
+ */
+export function formatBuildFailure(
+  failure: BuildFailureDetails,
+  prefix = "Build failed"
+): string {
+  switch (failure.phase) {
+    case "entry":
+      return `${prefix}: ${failure.message}\n`;
+
+    case "typecheck":
+      if (failure.diagnostics && failure.diagnostics.length > 0) {
+        const errors = failure.diagnostics.filter((d) => d.severity === "error");
+        if (errors.length > 0) {
+          return `${prefix}: Type check errors\n\n${formatDiagnostics(errors)}\n`;
+        }
+      }
+      return `${prefix}: Type check errors\n`;
+
+    case "bundle":
+      if (failure.bundleErrors && failure.bundleErrors.length > 0) {
+        return `${prefix}: Bundle errors\n\n${formatBundleErrors(failure.bundleErrors)}\n`;
+      }
+      return `${prefix}: Bundle error\n`;
+
+    default:
+      return `${prefix}: Unknown error\n`;
+  }
+}

package/src/core/executor.ts

@@ -68,23 +68,18 @@ export function createBasicExecutor(
 
       const captureLog = (...args: unknown[]) => {
         logs.push(formatArgs(...args));
-        originalConsole.log.apply(console, args);
       };
       const captureWarn = (...args: unknown[]) => {
         logs.push(`[warn] ${formatArgs(...args)}`);
-        originalConsole.warn.apply(console, args);
       };
       const captureError = (...args: unknown[]) => {
         logs.push(`[error] ${formatArgs(...args)}`);
-        originalConsole.error.apply(console, args);
       };
       const captureInfo = (...args: unknown[]) => {
         logs.push(`[info] ${formatArgs(...args)}`);
-        originalConsole.info.apply(console, args);
       };
       const captureDebug = (...args: unknown[]) => {
         logs.push(`[debug] ${formatArgs(...args)}`);
-        originalConsole.debug.apply(console, args);
       };
 
       const restoreConsole = () => {
@@ -125,13 +120,19 @@ export function createBasicExecutor(
 
         // Execute with optional timeout
         if (timeout > 0) {
+          let timeoutId: ReturnType<typeof setTimeout> | undefined;
           const timeoutPromise = new Promise<never>((_, reject) => {
-            setTimeout(
+            timeoutId = setTimeout(
               () => reject(new Error(`Execution timed out after ${timeout}ms`)),
               timeout
             );
           });
-          await Promise.race([executeExport(), timeoutPromise]);
+          try {
+            await Promise.race([executeExport(), timeoutPromise]);
+          } finally {
+            // Clear the timeout to allow the process to exit
+            if (timeoutId) clearTimeout(timeoutId);
+          }
         } else {
           await executeExport();
         }

package/src/core/sandbox.ts

@@ -513,6 +513,9 @@ export async function createSandboxImpl(
         buildFailure: {
           phase: buildResult.phase,
           message: buildResult.message,
+          diagnostics: buildResult.diagnostics,
+          bundleErrors: buildResult.bundleErrors,
+          bundleWarnings: buildResult.bundleWarnings,
         },
       };
     }

package/src/core/sandlot.ts

@@ -73,5 +73,12 @@ export function createSandlot(options: SandlotOptions): Sandlot {
     get sharedModules(): ISharedModuleRegistry | null {
       return sharedModuleRegistry;
     },
+
+    async dispose(): Promise<void> {
+      // Dispose of the bundler if it has a dispose method
+      if (bundler.dispose) {
+        await bundler.dispose();
+      }
+    },
   };
 }

package/src/core/typechecker.ts

@@ -418,10 +418,12 @@ function parseTsConfig(
       configPath
     );
 
-    if (parsed.errors.length > 0) {
+    // Filter out "no inputs found" error (TS18003) - we pass entry points explicitly
+    const relevantErrors = parsed.errors.filter((e) => e.code !== 18003);
+    if (relevantErrors.length > 0) {
       console.warn(
         "[typechecker] tsconfig parse errors:",
-        parsed.errors.map((e) => e.messageText)
+        relevantErrors.map((e) => e.messageText)
       );
     }
 

package/src/index.ts

@@ -47,6 +47,7 @@ export {
   formatSize,
   formatDiagnostics,
   formatBundleErrors,
+  formatBuildFailure,
 } from "./commands";
 export type { SandboxRef } from "./commands";
 
@@ -95,6 +96,7 @@ export type {
   BuildResult,
   BuildSuccess,
   BuildFailure,
+  BuildFailureDetails,
   SandboxBuildOptions,
 
   // Install/Uninstall types

package/src/node/bundler.ts

@@ -76,6 +76,17 @@ export class EsbuildNativeBundler implements IBundler {
     return this.esbuild;
   }
 
+  /**
+   * Dispose of the esbuild service.
+   * This stops the esbuild child process and allows the Node.js process to exit.
+   */
+  async dispose(): Promise<void> {
+    if (this.esbuild) {
+      await this.esbuild.stop();
+      this.esbuild = null;
+    }
+  }
+
   async bundle(options: BundleOptions): Promise<BundleResult> {
     await this.initialize();
 

package/src/node/index.ts

@@ -17,6 +17,16 @@
 export { EsbuildNativeBundler, createEsbuildNativeBundler } from "./bundler";
 export type { EsbuildNativeBundlerOptions } from "./bundler";
 
+// -----------------------------------------------------------------------------
+// WASM Bundler (for testing consistency with browser bundler)
+// -----------------------------------------------------------------------------
+
+export {
+  EsbuildWasmNodeBundler,
+  createEsbuildWasmNodeBundler,
+} from "./wasm-bundler";
+export type { EsbuildWasmNodeBundlerOptions } from "./wasm-bundler";
+
 // -----------------------------------------------------------------------------
 // Typechecker (platform-agnostic: re-exported for convenience)
 // -----------------------------------------------------------------------------

package/src/node/preset.ts

@@ -5,6 +5,10 @@ import {
 } from "../core/esm-types-resolver";
 import type { Sandlot, SandlotOptions } from "../types";
 import { EsbuildNativeBundler, type EsbuildNativeBundlerOptions } from "./bundler";
+import {
+  EsbuildWasmNodeBundler,
+  type EsbuildWasmNodeBundlerOptions,
+} from "./wasm-bundler";
 import {
   Typechecker,
   type TypecheckerOptions,
@@ -18,8 +22,17 @@ export interface CreateNodeSandlotOptions
   extends Omit<SandlotOptions, "bundler" | "typechecker" | "typesResolver" | "executor"> {
   /**
    * Custom bundler options, or a pre-configured bundler instance.
+   *
+   * Set to `"wasm"` to use the WASM bundler (for testing consistency with browser).
+   * You can also pass `{ wasm: true, ...options }` for WASM bundler with custom options.
+   *
+   * @default EsbuildNativeBundler (fastest, uses native esbuild binary)
    */
-  bundler?: EsbuildNativeBundlerOptions | SandlotOptions["bundler"];
+  bundler?:
+    | EsbuildNativeBundlerOptions
+    | (EsbuildWasmNodeBundlerOptions & { wasm: true })
+    | SandlotOptions["bundler"]
+    | "wasm";
 
   /**
    * Custom typechecker options, or a pre-configured typechecker instance.
@@ -82,6 +95,13 @@ export interface CreateNodeSandlotOptions
  *   typechecker: false,
  * });
  * ```
+ *
+ * @example Use WASM bundler for testing consistency with browser
+ * ```ts
+ * const sandlot = await createNodeSandlot({
+ *   bundler: "wasm",
+ * });
+ * ```
  */
 export async function createNodeSandlot(
   options: CreateNodeSandlotOptions = {}
@@ -89,11 +109,9 @@ export async function createNodeSandlot(
   const { bundler, typechecker, typesResolver, executor, ...rest } = options;
 
   // Create or use provided bundler
-  const bundlerInstance = isBundler(bundler)
-    ? bundler
-    : new EsbuildNativeBundler(bundler as EsbuildNativeBundlerOptions | undefined);
+  const bundlerInstance = createBundlerInstance(bundler);
 
-  // Initialize bundler (loads native esbuild)
+  // Initialize bundler (loads native esbuild or WASM)
   await bundlerInstance.initialize();
 
   // Create or use provided typechecker
@@ -135,6 +153,42 @@ export async function createNodeSandlot(
   });
 }
 
+// Helper to create bundler instance based on options
+
+function createBundlerInstance(
+  bundler: CreateNodeSandlotOptions["bundler"]
+): (EsbuildNativeBundler | EsbuildWasmNodeBundler) & { initialize(): Promise<void> } {
+  // Already a bundler instance
+  if (isBundler(bundler)) {
+    return bundler as (EsbuildNativeBundler | EsbuildWasmNodeBundler) & { initialize(): Promise<void> };
+  }
+
+  // String shorthand for WASM bundler
+  if (bundler === "wasm") {
+    return new EsbuildWasmNodeBundler();
+  }
+
+  // Object with wasm: true flag
+  if (isWasmBundlerOptions(bundler)) {
+    const { wasm: _, ...wasmOptions } = bundler;
+    return new EsbuildWasmNodeBundler(wasmOptions);
+  }
+
+  // Default: native bundler (fastest)
+  return new EsbuildNativeBundler(bundler as EsbuildNativeBundlerOptions | undefined);
+}
+
+function isWasmBundlerOptions(
+  value: unknown
+): value is EsbuildWasmNodeBundlerOptions & { wasm: true } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "wasm" in value &&
+    (value as { wasm: unknown }).wasm === true
+  );
+}
+
 // Type guards for detecting pre-configured instances
 
 function isBundler(

package/src/node/wasm-bundler.ts

@@ -0,0 +1,299 @@
+/**
+ * Node/Bun/Deno bundler implementation using esbuild-wasm.
+ *
+ * This bundler uses the same WebAssembly-based esbuild as the browser bundler,
+ * but runs in Node.js/Bun/Deno environments. It's primarily useful for:
+ *
+ * 1. Testing consistency with the browser bundler
+ * 2. Ensuring identical import resolution behavior
+ * 3. Validating that bundled output matches between browser and server
+ *
+ * For production use, prefer EsbuildNativeBundler which is ~3-5x faster.
+ */
+
+import type * as EsbuildTypes from "esbuild-wasm";
+import type {
+  IBundler,
+  BundleOptions,
+  BundleResult,
+  BundleWarning,
+  BundleError,
+} from "../types";
+import {
+  createVfsPlugin,
+  isEsbuildBuildFailure,
+  convertEsbuildMessage,
+} from "../core/bundler-utils";
+
+// =============================================================================
+// Global Singleton for esbuild-wasm initialization
+// =============================================================================
+// esbuild-wasm can only be initialized once per process. We track this globally
+// so multiple EsbuildWasmNodeBundler instances can share the same initialization.
+
+interface EsbuildGlobalState {
+  esbuild: typeof EsbuildTypes | null;
+  initialized: boolean;
+  initPromise: Promise<void> | null;
+}
+
+// Use a different key than the browser bundler to avoid conflicts if both
+// are somehow loaded in the same environment (e.g., during SSR)
+const GLOBAL_KEY = "__sandlot_esbuild_wasm_node__";
+
+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 EsbuildWasmNodeBundlerOptions {
+  /**
+   * Base URL for CDN imports.
+   * npm imports like "lodash" are rewritten to "{cdnBaseUrl}/lodash@{version}".
+   * @default "https://esm.sh"
+   */
+  cdnBaseUrl?: string;
+}
+
+/**
+ * Bundler implementation using esbuild-wasm for Node.js/Bun/Deno.
+ *
+ * Uses the same WebAssembly-based esbuild as the browser bundler,
+ * making it ideal for testing consistency between browser and server builds.
+ *
+ * @example
+ * ```ts
+ * const bundler = new EsbuildWasmNodeBundler();
+ * await bundler.initialize();
+ *
+ * const result = await bundler.bundle({
+ *   fs: myFilesystem,
+ *   entryPoint: "/src/index.ts",
+ * });
+ * ```
+ *
+ * @example Testing consistency with native bundler
+ * ```ts
+ * const native = new EsbuildNativeBundler();
+ * const wasm = new EsbuildWasmNodeBundler();
+ *
+ * await native.initialize();
+ * await wasm.initialize();
+ *
+ * const nativeResult = await native.bundle(options);
+ * const wasmResult = await wasm.bundle(options);
+ *
+ * // Results should be equivalent (modulo minor formatting differences)
+ * ```
+ */
+export class EsbuildWasmNodeBundler implements IBundler {
+  private options: EsbuildWasmNodeBundlerOptions;
+
+  constructor(options: EsbuildWasmNodeBundlerOptions = {}) {
+    this.options = {
+      cdnBaseUrl: "https://esm.sh",
+      ...options,
+    };
+  }
+
+  /**
+   * 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 process.
+   */
+  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> {
+    // Import esbuild-wasm from node_modules
+    const esbuild = await import("esbuild-wasm");
+
+    if (typeof esbuild?.initialize !== "function") {
+      throw new Error(
+        "Failed to load esbuild-wasm: initialize function not found"
+      );
+    }
+
+    // In Node.js/Bun/Deno, esbuild-wasm automatically loads the WASM
+    // from node_modules without needing a wasmURL option.
+    // The wasmURL option is only for browsers.
+    await esbuild.initialize({});
+
+    // 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;
+  }
+
+  /**
+   * Dispose of the esbuild WASM service.
+   * This stops the esbuild service and allows the process to exit.
+   * 
+   * Note: Since esbuild-wasm uses a global singleton, this affects all
+   * instances. After dispose(), you'll need to create a new bundler.
+   */
+  async dispose(): Promise<void> {
+    const state = getGlobalState();
+    if (state.esbuild) {
+      await state.esbuild.stop();
+      state.esbuild = null;
+      state.initialized = false;
+      state.initPromise = null;
+    }
+  }
+
+  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
+    // Note: bundleCdnImports is true for Node/Bun because they cannot
+    // resolve HTTP imports at runtime - esbuild will fetch and bundle them
+    const plugin = createVfsPlugin({
+      fs,
+      entryPoint: normalizedEntry,
+      installedPackages,
+      sharedModules: new Set(sharedModules),
+      sharedModuleRegistry: sharedModuleRegistry ?? null,
+      cdnBaseUrl: this.options.cdnBaseUrl!,
+      includedFiles,
+      bundleCdnImports: true,
+    });
+
+    try {
+      // Run esbuild
+      // Note: We do NOT mark http/https as external here because Node/Bun
+      // cannot resolve HTTP imports at runtime. Instead, bundleCdnImports: true
+      // tells the VFS plugin to let esbuild fetch and bundle CDN imports.
+      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: [],
+      };
+    }
+  }
+}
+
+/**
+ * Create an esbuild-wasm bundler for Node.js/Bun/Deno.
+ *
+ * This is primarily useful for testing consistency with the browser bundler.
+ * For production use, prefer createEsbuildNativeBundler() which is ~3-5x faster.
+ */
+export function createEsbuildWasmNodeBundler(
+  options?: EsbuildWasmNodeBundlerOptions
+): EsbuildWasmNodeBundler {
+  return new EsbuildWasmNodeBundler(options);
+}