sandlot 0.1.4 → 0.2.1

package/src/commands/types.ts

@@ -1,172 +1,144 @@
 /**
- * Types and utilities for sandbox bash commands.
+ * Types and utilities for v2 sandbox bash commands.
+ *
+ * Commands wrap the sandbox's direct methods to provide a shell interface.
+ * This ensures consistency between `sandbox.build()` and `sandbox.exec('sandlot build')`.
  */
 
-import type { IFileSystem } from "just-bash/browser";
-import type { BundleResult } from "../bundler";
-import type { TypesCache } from "../packages";
+import type {
+  Filesystem,
+  InstallResult,
+  UninstallResult,
+  BuildResult,
+  BuildFailureDetails,
+  TypecheckResult,
+  SandboxBuildOptions,
+  SandboxTypecheckOptions,
+  RunOptions,
+  RunResult,
+  BundleError,
+  Diagnostic,
+} from "../types";
 
 /**
- * The result of a successful build, including the bundle and loaded module.
+ * Reference to sandbox methods that commands can call.
+ *
+ * Commands receive this interface rather than raw dependencies,
+ * ensuring they use the same logic as direct API calls.
  */
-export interface BuildOutput {
-  /**
-   * The compiled bundle (code, metadata, etc.)
-   */
-  bundle: BundleResult;
-
-  /**
-   * The loaded module exports.
-   * If validation was provided, this is the validated module.
-   */
-  module: Record<string, unknown>;
-}
+export interface SandboxRef {
+  /** The virtual filesystem */
+  readonly fs: Filesystem;
 
-/**
- * Validation function type for module validation.
- * Takes the raw module exports and returns validated exports (or throws).
- */
-export type ValidateFn = (module: Record<string, unknown>) => Record<string, unknown>;
+  /** Install a package */
+  install(packageSpec: string): Promise<InstallResult>;
 
-/**
- * Dependencies required by command factories
- */
-export interface CommandDeps {
-  /**
-   * The virtual filesystem to operate on
-   */
-  fs: IFileSystem;
-
-  /**
-   * Pre-loaded TypeScript lib files for type checking
-   */
-  libFiles: Map<string, string>;
-
-  /**
-   * Path to tsconfig.json in the virtual filesystem
-   */
-  tsconfigPath: string;
-
-  /**
-   * Callback invoked when a build succeeds (after loading and validation).
-   */
-  onBuild?: (result: BuildOutput) => void | Promise<void>;
-
-  /**
-   * Getter for the current validation function.
-   * Called during build to check if validation should be performed.
-   */
-  getValidation?: () => ValidateFn | null;
-
-  /**
-   * Cache for package type definitions.
-   * When provided, avoids redundant network fetches for packages
-   * that have already been installed in other sandboxes.
-   */
-  typesCache?: TypesCache;
-
-  /**
-   * Options for the `run` command
-   */
-  runOptions?: RunOptions;
-
-  /**
-   * Module IDs that should be resolved from the host's SharedModuleRegistry
-   * instead of esm.sh CDN. The host must have registered these modules.
-   * 
-   * Example: ['react', 'react-dom/client']
-   */
-  sharedModules?: string[];
+  /** Uninstall a package */
+  uninstall(packageName: string): Promise<UninstallResult>;
+
+  /** Build the project */
+  build(options?: SandboxBuildOptions): Promise<BuildResult>;
+
+  /** Type check the project */
+  typecheck(options?: SandboxTypecheckOptions): Promise<TypecheckResult>;
+
+  /** Run code (build + execute) */
+  run(options?: RunOptions): Promise<RunResult>;
 }
 
 /**
- * Runtime context passed to the `main()` function when code is executed.
- * This provides sandboxed code with access to sandbox capabilities.
+ * Format a file size in bytes to a human-readable string
  */
-export interface RunContext {
-  /**
-   * The virtual filesystem - read/write files within the sandbox
-   */
-  fs: IFileSystem;
-
-  /**
-   * Environment variables (configurable per-sandbox)
-   */
-  env: Record<string, string>;
-
-  /**
-   * Command-line arguments passed to `run`
-   */
-  args: string[];
-
-  /**
-   * Explicit logging function (alternative to console.log)
-   */
-  log: (...args: unknown[]) => void;
-
-  /**
-   * Explicit error logging function (alternative to console.error)
-   */
-  error: (...args: unknown[]) => void;
+export function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
 }
 
 /**
- * Options for configuring the `run` command behavior
+ * Format diagnostics for shell output
  */
-export interface RunOptions {
-  /**
-   * Environment variables available via ctx.env
-   */
-  env?: Record<string, string>;
-
-  /**
-   * Maximum execution time in milliseconds (default: 30000 = 30s)
-   * Set to 0 to disable timeout.
-   */
-  timeout?: number;
-
-  /**
-   * Whether to skip type checking before running (default: false)
-   */
-  skipTypecheck?: boolean;
+export function formatDiagnostics(diagnostics: Diagnostic[]): string {
+  if (diagnostics.length === 0) return "";
+
+  return diagnostics
+    .map((d) => {
+      const severity = d.severity.toUpperCase();
+      if (d.file) {
+        const loc = `${d.file}${d.line ? `:${d.line}` : ""}${d.column ? `:${d.column}` : ""}`;
+        return `${severity}: ${loc}: ${d.message}`;
+      }
+      return `${severity}: ${d.message}`;
+    })
+    .join("\n");
 }
 
 /**
- * Result of running code via the `run` command
+ * Format bundle errors for shell output
  */
-export interface RunResult {
-  /**
-   * Captured console output (log, warn, error)
-   */
-  logs: string[];
-
-  /**
-   * Return value from main() if present
-   */
-  returnValue?: unknown;
-
-  /**
-   * Execution time in milliseconds
-   */
-  executionTimeMs: number;
+export function formatBundleErrors(errors: BundleError[]): string {
+  if (errors.length === 0) return "";
+
+  return errors
+    .map((e) => {
+      let output = "";
+
+      // Location header
+      if (e.location) {
+        const loc = `${e.location.file}:${e.location.line}${e.location.column ? `:${e.location.column}` : ""}`;
+        output += `ERROR: ${loc}: ${e.text}`;
+
+        // Show source line if available
+        if (e.location.lineText) {
+          output += `\n    ${e.location.line} | ${e.location.lineText}`;
+          // Add caret pointing to column
+          if (e.location.column) {
+            const padding = " ".repeat(
+              String(e.location.line).length + 3 + e.location.column - 1
+            );
+            output += `\n${padding}^`;
+          }
+        }
+      } else {
+        output += `ERROR: ${e.text}`;
+      }
+
+      return output;
+    })
+    .join("\n\n");
 }
 
 /**
- * Format esbuild messages (warnings/errors) for display
+ * 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 formatEsbuildMessages(
-  messages: { text: string; location?: { file?: string; line?: number; column?: number } | null }[]
+export function formatBuildFailure(
+  failure: BuildFailureDetails,
+  prefix = "Build failed"
 ): string {
-  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;
+  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 msg.text;
-    })
-    .join("\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`;
+  }
 }