@ebowwa/sandbox 0.1.1

package/src/core/types.ts

@@ -0,0 +1,528 @@
+/**
+ * Core Types for @ebowwa/sandbox
+ *
+ * Composable primitives for multi-language sandboxed execution.
+ * Each type is designed to be independently usable.
+ */
+
+// ============================================
+// LANGUAGE & FORMAT TYPES
+// ============================================
+
+/** Supported input languages/formats */
+export type Language =
+  | "wasm"           // Pre-compiled WASM bytes
+  | "javascript"     // JavaScript
+  | "typescript"     // TypeScript
+  | "assemblyscript" // AssemblyScript (TS-like)
+  | "python"         // Python (via Pyodide/RustPython WASM)
+  | "json"           // JSON data
+  | "markdown"       // Markdown (documentation cells)
+  | "custom";        // Custom DSL (via registered compiler)
+
+/** Language capability flags */
+export interface LanguageCapabilities {
+  supportsREPL: boolean;
+  supportsState: boolean;      // Can maintain state between cells
+  requiresCompilation: boolean;
+  hasGarbageCollection: boolean;
+  canImportModules: boolean;
+  canAccessFS: boolean;
+  canAccessNetwork: boolean;
+}
+
+// ============================================
+// PERMISSION TYPES (Composable)
+// ============================================
+
+/** Permission level - escalating access */
+export type PermissionLevel =
+  | "isolated"    // Completely sandboxed, no I/O
+  | "readonly"    // Read-only filesystem
+  | "network"     // Network + read-only fs
+  | "filesystem"  // Full filesystem + network
+  | "admin"       // Admin capabilities
+  | "sudo";       // Root/sudo access (DANGEROUS)
+
+/** Individual permission flags - composable */
+export interface Permissions {
+  fs?: FileSystemPermission;
+  network?: NetworkPermission;
+  env?: EnvironmentPermission;
+  process?: ProcessPermission;
+  memory?: {
+    maxBytes?: number;
+  };
+  cpu?: CpuPermission;
+}
+
+/** Filesystem permission */
+export interface FileSystemPermission {
+  read?: boolean;
+  write?: boolean;
+  delete?: boolean;
+  allowedPaths?: string[];
+  deniedPaths?: string[];
+}
+
+/** Network permission */
+export interface NetworkPermission {
+  outbound?: boolean;
+  inbound?: boolean;
+  allowedHosts?: string[];
+  deniedHosts?: string[];
+}
+
+/** Environment permission */
+export interface EnvironmentPermission {
+  read?: boolean;
+  write?: boolean;
+  allowedKeys?: string[];
+}
+
+/** Process permission */
+export interface ProcessPermission {
+  spawn?: boolean;
+  allowedCommands?: string[];
+}
+
+/** CPU permission */
+export interface CpuPermission {
+  maxPercent?: number;
+  maxTimeMs?: number;
+}
+
+/** Convert permission level to permissions object */
+export function permissionsFromLevel(level: PermissionLevel): Permissions {
+  switch (level) {
+    case "isolated":
+      return {};
+    case "readonly":
+      return { fs: { read: true } };
+    case "network":
+      return { fs: { read: true }, network: { outbound: true } };
+    case "filesystem":
+      return {
+        fs: { read: true, write: true, delete: true },
+        network: { outbound: true, inbound: true }
+      };
+    case "admin":
+      return {
+        fs: { read: true, write: true, delete: true },
+        network: { outbound: true, inbound: true },
+        env: { read: true, write: true },
+        process: { spawn: true }
+      };
+    case "sudo":
+      return {
+        fs: { read: true, write: true, delete: true },
+        network: { outbound: true, inbound: true },
+        env: { read: true, write: true },
+        process: { spawn: true }
+      };
+  }
+}
+
+// ============================================
+// RESOURCE LIMITS (Composable)
+// ============================================
+
+/** Resource limits for execution */
+export interface Limits {
+  /** Memory limit (bytes or string like "64MB") */
+  memory?: number | string;
+  /** Execution timeout (ms or string like "5s") */
+  timeout?: number | string;
+  /** CPU time limit (ms) */
+  cpuTime?: number;
+  /** Max WASM instructions (gas/fuel) */
+  maxInstructions?: number;
+  /** Max output size (bytes) */
+  maxOutputSize?: number;
+  /** Max call stack depth */
+  maxStackDepth?: number;
+  /** Network bandwidth limits */
+  network?: {
+    maxBandwidth?: string;
+    maxConnections?: number;
+  };
+  /** Filesystem limits */
+  filesystem?: {
+    maxFileSize?: string;
+    maxTotalSize?: string;
+    maxOpenFiles?: number;
+  };
+}
+
+/** Parse memory string to bytes */
+export function parseMemory(mem: number | string | undefined): number {
+  if (mem === undefined) return 16 * 1024 * 1024; // 16MB default
+  if (typeof mem === "number") return mem;
+  const match = mem.match(/^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)?$/i);
+  if (!match) return 16 * 1024 * 1024;
+  const [, num, unit] = match;
+  const multipliers: Record<string, number> = {
+    b: 1, kb: 1024, mb: 1024 ** 2, gb: 1024 ** 3
+  };
+  return Math.floor(parseFloat(num) * (multipliers[unit?.toLowerCase() ?? "b"] ?? 1));
+}
+
+/** Parse time string to milliseconds */
+export function parseTime(time: number | string | undefined): number {
+  if (time === undefined) return 30000; // 30s default
+  if (typeof time === "number") return time;
+  const match = time.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h)?$/i);
+  if (!match) return 30000;
+  const [, num, unit] = match;
+  const multipliers: Record<string, number> = {
+    ms: 1, s: 1000, m: 60000, h: 3600000
+  };
+  return Math.floor(parseFloat(num) * (multipliers[unit?.toLowerCase() ?? "ms"] ?? 1));
+}
+
+// ============================================
+// EXECUTION TYPES
+// ============================================
+
+/** Code cell for notebook/repl execution */
+export interface Cell {
+  id: string;
+  language: Language;
+  source: string;
+  metadata?: Record<string, unknown>;
+}
+
+/** Result from another cell (for imports) */
+export interface CellResult {
+  success: boolean;
+  value?: unknown;
+  error?: { message: string; type: string };
+  exports?: Map<string, unknown>;
+}
+
+/** Execution context passed to runtimes */
+export interface ExecutionContext {
+  cellId: string;
+  permissions: Permissions;
+  limits: Limits;
+  environment: Record<string, string>;
+  workingDirectory?: string;
+  /** Shared state from previous cells */
+  state?: Map<string, unknown>;
+  /** Imports from other cells */
+  imports?: Map<string, CellResult>;
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+}
+
+/** Execution options */
+export interface ExecutionOptions {
+  entrypoint?: string;
+  args?: unknown[];
+  input?: unknown;
+  timeout?: number;
+  signal?: AbortSignal;
+  /** Pass state from previous execution */
+  state?: Map<string, unknown>;
+}
+
+/** Result of cell/execution */
+export interface ExecutionResult<T = unknown> {
+  /** Execution succeeded */
+  success: boolean;
+  /** Return value */
+  value?: T;
+  /** Error if failed */
+  error?: ExecutionError;
+  /** Execution metrics */
+  metrics: ExecutionMetrics;
+  /** Captured output */
+  output: {
+    stdout: string[];
+    stderr: string[];
+    displays: DisplayOutput[];  // For rich output (images, HTML, etc.)
+  };
+  /** State to pass to next cells */
+  state?: Map<string, unknown>;
+  /** Exports for other cells to import */
+  exports?: Map<string, unknown>;
+}
+
+/** Error during execution */
+export interface ExecutionError {
+  message: string;
+  stack?: string;
+  type: "compile" | "runtime" | "permission" | "limit" | "timeout" | "cancel";
+  language?: Language;
+  line?: number;
+  column?: number;
+}
+
+/** Execution metrics */
+export interface ExecutionMetrics {
+  /** Wall clock time in ms */
+  duration: number;
+  /** Memory used in bytes */
+  memoryUsed: number;
+  /** CPU time in ms */
+  cpuTime?: number;
+  /** WASM instructions executed */
+  instructionsExecuted?: number;
+  /** Bytes received over network */
+  networkIn?: number;
+  /** Bytes sent over network */
+  networkOut?: number;
+}
+
+/** Rich display output (Jupyter-style) */
+export interface DisplayOutput {
+  type: "text" | "html" | "image" | "json" | "markdown" | "javascript";
+  data: string | Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+}
+
+// ============================================
+// COMPILER INTERFACE
+// ============================================
+
+/** Compiler: Language → WASM */
+export interface Compiler {
+  /** Language this compiler handles */
+  language: Language;
+  /** Check if code is valid for this language */
+  validate(code: string): Promise<{ valid: boolean; error?: string }>;
+  /** Compile source to WASM bytes */
+  compile(code: string, options: CompileOptions): Promise<Uint8Array>;
+  /** Check if compiler is available */
+  isAvailable(): Promise<boolean>;
+}
+
+/** Compilation options */
+export interface CompileOptions {
+  permissions: Permissions;
+  limits: Limits;
+  optimize?: boolean;
+  /** Additional compiler-specific options */
+  extra?: Record<string, unknown>;
+}
+
+// ============================================
+// RUNTIME INTERFACE
+// ============================================
+
+/** Runtime: WASM → Execution */
+export interface Runtime {
+  /** Runtime name */
+  name: string;
+  /** Initialize runtime */
+  init(): Promise<void>;
+  /** Check if runtime is available */
+  isAvailable(): Promise<boolean>;
+  /** Execute WASM bytes */
+  execute(
+    wasmBytes: Uint8Array,
+    options: ExecutionOptions,
+    context: ExecutionContext
+  ): Promise<ExecutionResult>;
+  /** Terminate runtime and cleanup */
+  terminate(): Promise<void>;
+}
+
+// ============================================
+// KERNEL INTERFACE (REPL/Notebook)
+// ============================================
+
+/** Kernel: Language-specific execution session */
+export interface Kernel {
+  /** Language this kernel handles */
+  language: Language;
+  /** Kernel display name */
+  displayName: string;
+  /** Initialize kernel */
+  start(): Promise<void>;
+  /** Check if kernel is running */
+  isRunning(): boolean;
+  /** Execute code in kernel */
+  execute(code: string, options?: ExecutionOptions): Promise<ExecutionResult>;
+  /** Complete code at position (autocomplete) */
+  complete(code: string, position: number): Promise<CompletionResult>;
+  /** Inspect object at position */
+  inspect(code: string, position: number): Promise<InspectResult>;
+  /** Get current kernel state */
+  getState(): Map<string, unknown>;
+  /** Restart kernel (clear state) */
+  restart(): Promise<void>;
+  /** Shutdown kernel */
+  shutdown(): Promise<void>;
+}
+
+/** Autocomplete result */
+export interface CompletionResult {
+  matches: string[];
+  cursorStart: number;
+  cursorEnd: number;
+  metadata?: Record<string, unknown>;
+}
+
+/** Inspect result (hover/tooltip) */
+export interface InspectResult {
+  found: boolean;
+  details?: {
+    type: string;
+    documentation?: string;
+    signature?: string;
+  };
+}
+
+// ============================================
+// NOTEBOOK INTERFACE
+// ============================================
+
+/** Notebook: Multi-cell, multi-language document */
+export interface Notebook {
+  id: string;
+  cells: Cell[];
+  metadata: NotebookMetadata;
+  /** Execute cells in order */
+  runAll(options?: NotebookRunOptions): Promise<NotebookResult[]>;
+  /** Execute single cell */
+  runCell(cellId: string, options?: ExecutionOptions): Promise<NotebookResult>;
+  /** Execute cells from index */
+  runFrom(startIndex: number): Promise<NotebookResult[]>;
+  /** Add cell */
+  addCell(cell: Omit<Cell, "id">): Cell;
+  /** Remove cell */
+  removeCell(cellId: string): void;
+  /** Move cell */
+  moveCell(cellId: string, newIndex: number): void;
+  /** Get cell by id */
+  getCell(cellId: string): Cell | undefined;
+  /** Export to format */
+  export(format: "ipynb" | "json" | "markdown"): string;
+}
+
+/** Notebook metadata */
+export interface NotebookMetadata {
+  name: string;
+  language?: Language;  // Default language
+  kernelspec?: {
+    name: string;
+    display_name: string;
+    language: string;
+  };
+  created: Date;
+  modified: Date;
+  tags?: string[];
+}
+
+/** Notebook run options */
+export interface NotebookRunOptions {
+  /** Stop on first error */
+  stopOnError?: boolean;
+  /** Parallel execution where possible */
+  parallel?: boolean;
+  /** Continue from last successful cell */
+  continueFrom?: string;
+}
+
+/** Result of notebook cell execution */
+export interface NotebookResult {
+  cellId: string;
+  executionCount: number;
+  result: ExecutionResult;
+  timestamp: Date;
+}
+
+// ============================================
+// SESSION INTERFACE
+// ============================================
+
+/** Session: Stateful execution context */
+export interface Session {
+  id: string;
+  /** Get active kernel for language */
+  getKernel(language: Language): Kernel | undefined;
+  /** Start a kernel for language */
+  startKernel(language: Language): Promise<Kernel>;
+  /** Execute code (auto-selects kernel) */
+  execute(code: string, language: Language, options?: ExecutionOptions): Promise<ExecutionResult>;
+  /** Get shared state across all kernels */
+  getSharedState(): Map<string, unknown>;
+  /** Set shared state */
+  setSharedState(key: string, value: unknown): void;
+  /** Register language compiler */
+  registerCompiler(compiler: Compiler): void;
+  /** Register runtime */
+  registerRuntime(runtime: Runtime): void;
+  /** Shutdown session */
+  shutdown(): Promise<void>;
+}
+
+// ============================================
+// POLYGLOT / MULTI-LANGUAGE
+// ============================================
+
+/** Polyglot cell - code that can run in multiple languages */
+export interface PolyglotCell {
+  id: string;
+  variants: Map<Language, string>;  // Same logic, different languages
+  preferredLanguage?: Language;
+}
+
+/** Bridge for passing data between languages */
+export interface LanguageBridge {
+  from: Language;
+  to: Language;
+  /** Serialize value from source language */
+  serialize(value: unknown): Uint8Array;
+  /** Deserialize value in target language */
+  deserialize(bytes: Uint8Array): unknown;
+  /** Can these types be bridged? */
+  canBridge(type: string): boolean;
+}
+
+// ============================================
+// SANDBOX (MAIN INTERFACE)
+// ============================================
+
+/** Main Sandbox interface - combines all primitives */
+export interface Sandbox {
+  /** Create a session for interactive use */
+  createSession(options?: SessionOptions): Session;
+  /** Create a notebook */
+  createNotebook(options?: NotebookOptions): Notebook;
+  /** Quick execute (isolated, no state) */
+  execute(
+    code: string,
+    language: Language,
+    options?: SandboxOptions
+  ): Promise<ExecutionResult>;
+  /** Quick execute with preset */
+  quick(
+    code: string,
+    preset?: "isolated" | "trusted" | "admin"
+  ): Promise<ExecutionResult>;
+}
+
+/** Sandbox configuration */
+export interface SandboxOptions {
+  permissions?: PermissionLevel | Permissions;
+  limits?: Limits;
+  language?: Language;
+  environment?: Record<string, string>;
+  workingDirectory?: string;
+}
+
+/** Session options */
+export interface SessionOptions extends SandboxOptions {
+  /** Languages to pre-warm kernels for */
+  languages?: Language[];
+  /** Enable shared memory between kernels */
+  sharedMemory?: boolean;
+}
+
+/** Notebook options */
+export interface NotebookOptions extends SandboxOptions {
+  name?: string;
+  defaultLanguage?: Language;
+}

package/src/global.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Global type declarations for @ebowwa/sandbox
+ */
+
+// WebAssembly types (for environments without DOM lib)
+declare namespace WebAssembly {
+  interface Module {}
+  interface Instance {
+    exports: Exports;
+  }
+  interface Exports extends Record<string, Function | Memory | Table | Global> {}
+  interface Memory {
+    buffer: ArrayBuffer;
+    grow(pages: number): number;
+  }
+  interface Table {
+    length: number;
+    get(index: number): Function | null;
+    set(index: number, value: Function | null): void;
+    grow(delta: number): number;
+  }
+  interface Global {
+    value: any;
+    valueOf(): any;
+  }
+  interface CompileError extends Error {}
+  interface RuntimeError extends Error {}
+  interface ModuleExportDescriptor {
+    name: string;
+    kind: string;
+  }
+  interface ModuleImportDescriptor {
+    module: string;
+    name: string;
+    kind: string;
+  }
+
+  function validate(bytes: BufferSource): boolean;
+  function compile(bytes: BufferSource): Promise<Module>;
+  function instantiate(bytes: BufferSource, importObject?: Imports): Promise<Instance>;
+  function instantiate(module: Module, importObject?: Imports): Promise<Instance>;
+
+  namespace Module {
+    function exports(module: Module): ModuleExportDescriptor[];
+    function imports(module: Module): ModuleImportDescriptor[];
+    function customSections(module: Module, sectionName: string): ArrayBuffer[];
+  }
+}
+
+// Missing CellResult type - alias to ExecutionResult for now
+export interface CellResult {
+  success: boolean;
+  value?: unknown;
+  error?: {
+    message: string;
+    type: string;
+  };
+  exports?: Map<string, unknown>;
+}