sandlot 0.1.4 → 0.2.0

package/src/index.ts

@@ -1,171 +1,136 @@
 // =============================================================================
-// Browser polyfills - inject before anything else loads
+// Sandlot v2 - Core Entry Point
 // =============================================================================
-
-// 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),
-  };
-}
-
-// =============================================================================
-// CORE API - Most users only need these
+//
+// This module exports the core interfaces and factory function.
+// It is context-agnostic - no browser or Node.js specific code.
+//
+// For context-specific implementations, import from:
+//   - "sandlot/browser" - Browser implementations (esbuild-wasm, etc.)
+//   - "sandlot/node"    - Node/Bun implementations (native esbuild, etc.)
+//
 // =============================================================================
 
 // -----------------------------------------------------------------------------
-// Sandbox API
-// -----------------------------------------------------------------------------
-
-export {
-  createSandbox,
-  type Sandbox,
-  type SandboxOptions,
-  type SandboxState,
-  type SandboxBashOptions,
-} from "./sandbox";
-
-// -----------------------------------------------------------------------------
-// Builder (recommended for agent workflows)
+// Factory Function
 // -----------------------------------------------------------------------------
 
-export {
-  createBuilder,
-  type BuildResult,
-  type CreateBuilderOptions,
-  type BuildCallOptions,
-  type BuilderFn,
-} from "./builder";
+export { createSandlot } from "./core/sandlot";
 
 // -----------------------------------------------------------------------------
-// Module Loading (use after build to get exports)
+// Filesystem
 // -----------------------------------------------------------------------------
 
 export {
-  loadModule,
-  loadExport,
-  loadDefault,
-  getExportNames,
-  hasExport,
-  ModuleLoadError,
-  ExportNotFoundError,
-} from "./loader";
-
-// -----------------------------------------------------------------------------
-// Shared Modules (for React/library sharing with host)
-// -----------------------------------------------------------------------------
-
-export {
-  registerSharedModules,
-  unregisterSharedModule,
-  clearSharedModules,
-} from "./shared-modules";
-
-// -----------------------------------------------------------------------------
-// Common Types
-// -----------------------------------------------------------------------------
-
-export type { BundleResult } from "./bundler";
-export type { BuildOutput, ValidateFn } from "./commands/types";
-export type { TypecheckResult, Diagnostic } from "./typechecker";
-export type { PackageManifest, InstallResult } from "./packages";
-
-
-// =============================================================================
-// ADVANCED API - For power users and custom integrations
-// =============================================================================
+  Filesystem,
+  createFilesystem,
+  wrapFilesystemForJustBash,
+} from "./core/fs";
+export type { FilesystemOptions } from "./core/fs";
 
 // -----------------------------------------------------------------------------
-// Direct Bundler Access
+// Shared Module Registry
 // -----------------------------------------------------------------------------
 
 export {
-  initBundler,
-  bundle,
-  bundleToUrl,
-  bundleAndImport,
-  type BundleOptions,
-  type NpmImportsMode,
-} from "./bundler";
+  SharedModuleRegistry,
+  createSharedModuleRegistry,
+} from "./core/shared-module-registry";
 
 // -----------------------------------------------------------------------------
-// Direct Typechecker Access
+// Commands (for extending the shell with custom commands)
 // -----------------------------------------------------------------------------
 
 export {
-  typecheck,
+  createSandlotCommand,
+  createDefaultCommands,
+  formatSize,
   formatDiagnostics,
-  formatDiagnosticsForAgent,
-  type TypecheckOptions,
-} from "./typechecker";
-
-// -----------------------------------------------------------------------------
-// Package Management
-// -----------------------------------------------------------------------------
-
-export {
-  installPackage,
-  uninstallPackage,
-  listPackages,
-  getPackageManifest,
-  type InstallOptions,
-} from "./packages";
-
-// -----------------------------------------------------------------------------
-// Shared Resources (for custom resource management)
-// -----------------------------------------------------------------------------
-
-export {
-  createSharedResources,
-  getDefaultResources,
-  clearDefaultResources,
-  hasDefaultResources,
-  type SharedResourcesOptions,
-  type SharedResources,
-  type TypesCache,
-} from "./shared-resources";
+  formatBundleErrors,
+} from "./commands";
+export type { SandboxRef } from "./commands";
 
 // -----------------------------------------------------------------------------
-// Filesystem (for custom VFS usage)
+// Typechecker (platform-independent, fetches TS libs from CDN)
 // -----------------------------------------------------------------------------
 
-export {
-  Filesystem,
-  createFilesystem,
-  type FilesystemOptions,
-} from "./fs";
-
-export type { IFileSystem, FsEntry } from "just-bash/browser";
+export { Typechecker, createTypechecker } from "./core/typechecker";
+export type { TypecheckerOptions } from "./core/typechecker";
 
 // -----------------------------------------------------------------------------
-// TypeScript Library Utilities
+// Types Resolver (platform-independent, works anywhere with fetch)
 // -----------------------------------------------------------------------------
 
 export {
-  getDefaultBrowserLibs,
-  fetchAndCacheLibs,
-} from "./ts-libs";
-
-// -----------------------------------------------------------------------------
-// Command Factories (for custom sandbox commands)
-// -----------------------------------------------------------------------------
-
-export {
-  createTscCommand,
-  createBuildCommand,
-  createInstallCommand,
-  createUninstallCommand,
-  createListCommand,
-  createRunCommand,
-  createDefaultCommands,
-  type CommandDeps,
-  type RunContext,
-  type RunOptions,
-  type RunResult,
-} from "./commands/index";
+  EsmTypesResolver,
+  InMemoryTypesCache,
+} from "./core/esm-types-resolver";
+export type {
+  EsmTypesResolverOptions,
+  ResolvedTypes,
+  ITypesCache,
+} from "./core/esm-types-resolver";
+
+// -----------------------------------------------------------------------------
+// Types - Interfaces
+// -----------------------------------------------------------------------------
+
+export type {
+  // Core interfaces (for implementing your own)
+  IBundler,
+  ITypechecker,
+  ITypesResolver,
+  ISharedModuleRegistry,
+  IExecutor,
+
+  // Main API types
+  Sandlot,
+  SandlotOptions,
+  Sandbox,
+  SandboxOptions,
+  SandboxState,
+
+  // Build types
+  BuildPhase,
+  BuildResult,
+  BuildSuccess,
+  BuildFailure,
+  SandboxBuildOptions,
+
+  // Install/Uninstall types
+  InstallResult,
+  UninstallResult,
+
+  // Typecheck types
+  SandboxTypecheckOptions,
+
+  // Run types
+  RunOptions,
+  RunResult,
+
+  // Executor types
+  ExecuteOptions,
+  ExecuteResult,
+
+  // Bundler types
+  BundleOptions,
+  BundleResult,
+  BundleSuccess,
+  BundleFailure,
+  BundleWarning,
+  BundleError,
+  BundleLocation,
+
+  // Typechecker types
+  TypecheckOptions,
+  TypecheckResult,
+  Diagnostic,
+
+  // Shell execution types
+  ExecResult,
+
+  // Filesystem types
+  IFileSystem,
+  FsEntry,
+  FsStat,
+} from "./types";

package/src/node/bundler.ts

@@ -0,0 +1,194 @@
+/**
+ * Node/Bun/Deno bundler implementation using native esbuild.
+ *
+ * This is significantly faster than esbuild-wasm as it uses the native
+ * esbuild binary instead of WebAssembly.
+ */
+
+import type * as EsbuildTypes from "esbuild";
+import type {
+  IBundler,
+  BundleOptions,
+  BundleResult,
+  BundleWarning,
+  BundleError,
+} from "../types";
+import {
+  createVfsPlugin,
+  isEsbuildBuildFailure,
+  convertEsbuildMessage,
+} from "../core/bundler-utils";
+
+export interface EsbuildNativeBundlerOptions {
+  /**
+   * Base URL for CDN imports.
+   * npm imports like "lodash" are rewritten to "{cdnBaseUrl}/lodash@{version}".
+   * @default "https://esm.sh"
+   */
+  cdnBaseUrl?: string;
+}
+
+/**
+ * Bundler implementation using native esbuild.
+ *
+ * Uses the native esbuild binary for maximum performance.
+ * Works with Node.js, Bun, and Deno.
+ *
+ * @example
+ * ```ts
+ * const bundler = new EsbuildNativeBundler();
+ *
+ * const result = await bundler.bundle({
+ *   fs: myFilesystem,
+ *   entryPoint: "/src/index.ts",
+ * });
+ * ```
+ */
+export class EsbuildNativeBundler implements IBundler {
+  private options: EsbuildNativeBundlerOptions;
+  private esbuild: typeof EsbuildTypes | null = null;
+
+  constructor(options: EsbuildNativeBundlerOptions = {}) {
+    this.options = {
+      cdnBaseUrl: "https://esm.sh",
+      ...options,
+    };
+  }
+
+  /**
+   * Initialize the bundler by loading native esbuild.
+   * Called automatically on first bundle() if not already initialized.
+   */
+  async initialize(): Promise<void> {
+    if (this.esbuild) {
+      return;
+    }
+
+    // Dynamic import of native esbuild
+    // This works in Node.js, Bun, and Deno
+    this.esbuild = await import("esbuild");
+  }
+
+  private getEsbuild(): typeof EsbuildTypes {
+    if (!this.esbuild) {
+      throw new Error("esbuild not initialized - call initialize() first");
+    }
+    return this.esbuild;
+  }
+
+  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 - native 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 native 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 a native esbuild bundler.
+ */
+export function createEsbuildNativeBundler(
+  options?: EsbuildNativeBundlerOptions
+): EsbuildNativeBundler {
+  return new EsbuildNativeBundler(options);
+}

package/src/node/executor.ts

@@ -0,0 +1,87 @@
+/**
+ * Node/Bun/Deno executor implementation.
+ *
+ * Executes bundled JavaScript code using temp files and dynamic import.
+ * This provides basic execution without full isolation.
+ *
+ * For isolated execution, consider using Node's vm module or worker threads.
+ */
+
+import type { IExecutor } from "../types";
+import { createBasicExecutor, type BasicExecutorOptions } from "../core/executor";
+import { writeFileSync, unlinkSync, mkdtempSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+/**
+ * Options for creating a NodeExecutor.
+ */
+export type NodeExecutorOptions = BasicExecutorOptions;
+
+/**
+ * Load a module from code using a temp file.
+ * This works in Node.js, Bun, and Deno, and properly supports HTTP imports.
+ */
+async function loadModuleFromTempFile(code: string): Promise<Record<string, unknown>> {
+  // Create a temp directory and file
+  const tempDir = mkdtempSync(join(tmpdir(), "sandlot-"));
+  const tempFile = join(tempDir, `module-${Date.now()}.mjs`);
+  
+  try {
+    // Write the code to a temp file
+    writeFileSync(tempFile, code, "utf-8");
+    
+    // Import from the temp file - this allows HTTP imports to work
+    // Use file:// URL for cross-platform compatibility
+    const fileUrl = `file://${tempFile}`;
+    return await import(/* @vite-ignore */ fileUrl);
+  } finally {
+    // Clean up temp file
+    try {
+      unlinkSync(tempFile);
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+/**
+ * Executor that runs code in Node.js/Bun/Deno.
+ *
+ * Uses data URLs with dynamic import for execution.
+ * This approach works across Node.js, Bun, and Deno.
+ *
+ * WARNING: This executor provides NO isolation. The executed code has
+ * full access to the process environment, file system, and network.
+ * Only use for trusted code.
+ *
+ * @example
+ * ```ts
+ * const executor = createNodeExecutor();
+ * const result = await executor.execute(bundledCode, {
+ *   entryExport: 'main',
+ *   context: { args: ['--verbose'] },
+ *   timeout: 5000,
+ * });
+ * console.log(result.logs);
+ * ```
+ */
+export class NodeExecutor implements IExecutor {
+  private executor: IExecutor;
+
+  constructor(options: NodeExecutorOptions = {}) {
+    this.executor = createBasicExecutor(loadModuleFromTempFile, options);
+  }
+
+  execute: IExecutor["execute"] = (...args) => this.executor.execute(...args);
+}
+
+/**
+ * Create a Node executor.
+ *
+ * @param options - Executor options
+ * @returns A new NodeExecutor instance
+ */
+export function createNodeExecutor(options?: NodeExecutorOptions): NodeExecutor {
+  return new NodeExecutor(options);
+}

package/src/node/index.ts

@@ -0,0 +1,39 @@
+// =============================================================================
+// Sandlot v2 - Node/Bun/Deno Entry Point
+// =============================================================================
+//
+// Server-side implementations for Sandlot.
+// Uses native esbuild for bundling (much faster than esbuild-wasm).
+//
+// Note: The Typechecker and EsmTypesResolver are platform-independent and
+// exported from the main "sandlot" entry point.
+//
+// =============================================================================
+
+// -----------------------------------------------------------------------------
+// Bundler (node-specific: uses native esbuild)
+// -----------------------------------------------------------------------------
+
+export { EsbuildNativeBundler, createEsbuildNativeBundler } from "./bundler";
+export type { EsbuildNativeBundlerOptions } from "./bundler";
+
+// -----------------------------------------------------------------------------
+// Typechecker (platform-agnostic: re-exported for convenience)
+// -----------------------------------------------------------------------------
+
+export { Typechecker, createTypechecker } from "../core/typechecker";
+export type { TypecheckerOptions } from "../core/typechecker";
+
+// -----------------------------------------------------------------------------
+// Executor (node-specific: uses data URLs)
+// -----------------------------------------------------------------------------
+
+export { NodeExecutor, createNodeExecutor } from "./executor";
+export type { NodeExecutorOptions } from "./executor";
+
+// -----------------------------------------------------------------------------
+// Convenience Preset
+// -----------------------------------------------------------------------------
+
+export { createNodeSandlot } from "./preset";
+export type { CreateNodeSandlotOptions } from "./preset";