@ebowwa/sandbox 0.1.1

package/src/core/cell.ts

@@ -0,0 +1,439 @@
+/**
+ * Cell Primitive
+ *
+ * Represents a single unit of executable code.
+ * Cells can be combined into notebooks for sequential execution.
+ */
+
+import type {
+  Cell,
+  Language,
+  ExecutionResult,
+  ExecutionOptions,
+  ExecutionContext,
+  Permissions,
+  Limits,
+  DisplayOutput,
+} from "./types.js";
+import type { CompileResult } from "./compiler.js";
+import { v4 as uuid } from "uuid";
+
+/**
+ * Cell metadata
+ */
+export interface CellMetadata {
+  /** Cell display order */
+  index?: number;
+  /** Cell is collapsed */
+  collapsed?: boolean;
+  /** Cell execution count */
+  executionCount?: number;
+  /** Tags for organization */
+  tags?: string[];
+  /** Custom metadata */
+  [key: string]: unknown;
+}
+
+/**
+ * Cell execution state
+ */
+export type CellState =
+  | "idle"
+  | "queued"
+  | "running"
+  | "success"
+  | "error"
+  | "cancelled";
+
+/**
+ * Extended cell with execution tracking
+ */
+export interface ExecutableCell extends Cell {
+  /** Current state */
+  state: CellState;
+  /** Last execution result */
+  result?: ExecutionResult;
+  /** Execution count (notebook-style) */
+  executionCount?: number;
+  /** Last execution timestamp */
+  lastRun?: Date;
+  /** Dependencies on other cells */
+  dependencies?: string[];
+  /** Exports from this cell */
+  exports?: string[];
+}
+
+/**
+ * Cell Builder
+ *
+ * Fluent API for creating cells.
+ */
+export class CellBuilder {
+  private id = uuid();
+  private language: Language = "javascript";
+  private source = "";
+  private metadata: CellMetadata = {};
+
+  setId(id: string): this {
+    this.id = id;
+    return this;
+  }
+
+  setLanguage(lang: Language): this {
+    this.language = lang;
+    return this;
+  }
+
+  setSource(code: string): this {
+    this.source = code;
+    return this;
+  }
+
+  addMetadata(key: string, value: unknown): this {
+    this.metadata[key] = value;
+    return this;
+  }
+
+  setIndex(index: number): this {
+    this.metadata.index = index;
+    return this;
+  }
+
+  addTag(tag: string): this {
+    this.metadata.tags = [...(this.metadata.tags ?? []), tag];
+    return this;
+  }
+
+  build(): Cell {
+    return {
+      id: this.id,
+      language: this.language,
+      source: this.source,
+      metadata: Object.keys(this.metadata).length > 0 ? this.metadata : undefined,
+    };
+  }
+
+  buildExecutable(): ExecutableCell {
+    return {
+      ...this.build(),
+      state: "idle",
+    };
+  }
+}
+
+/**
+ * Cell Executor
+ *
+ * Handles execution of individual cells.
+ */
+export class CellExecutor {
+  constructor(
+    private compileFn: (cell: Cell) => Promise<CompileResult>,
+    private executeFn: (
+      compiled: CompileResult,
+      context: ExecutionContext
+    ) => Promise<ExecutionResult>
+  ) {}
+
+  /**
+   * Execute a cell
+   */
+  async execute(
+    cell: ExecutableCell,
+    context: ExecutionContext
+  ): Promise<ExecutionResult> {
+    cell.state = "running";
+    cell.lastRun = new Date();
+
+    try {
+      // Compile the cell
+      const compiled = await this.compileFn(cell);
+
+      // Execute
+      const result = await this.executeFn(compiled, context);
+
+      // Update cell state
+      cell.state = result.success ? "success" : "error";
+      cell.result = result;
+      cell.executionCount = (cell.executionCount ?? 0) + 1;
+
+      return result;
+    } catch (error) {
+      const result: ExecutionResult = {
+        success: false,
+        error: {
+          message: error instanceof Error ? error.message : String(error),
+          type: "runtime",
+        },
+        metrics: {
+          duration: 0,
+          memoryUsed: 0,
+        },
+        output: { stdout: [], stderr: [], displays: [] },
+      };
+
+      cell.state = "error";
+      cell.result = result;
+
+      return result;
+    }
+  }
+}
+
+/**
+ * Cell Registry
+ *
+ * Tracks cells and their relationships.
+ */
+export class CellRegistry {
+  private cells = new Map<string, ExecutableCell>();
+  private dependencies = new Map<string, Set<string>>();
+  private dependents = new Map<string, Set<string>>();
+
+  /**
+   * Add a cell
+   */
+  add(cell: ExecutableCell): void {
+    this.cells.set(cell.id, cell);
+
+    // Track dependencies
+    if (cell.dependencies) {
+      for (const depId of cell.dependencies) {
+        this.addDependency(cell.id, depId);
+      }
+    }
+  }
+
+  /**
+   * Get a cell by ID
+   */
+  get(id: string): ExecutableCell | undefined {
+    return this.cells.get(id);
+  }
+
+  /**
+   * Remove a cell
+   */
+  remove(id: string): void {
+    const cell = this.cells.get(id);
+    if (!cell) return;
+
+    // Clean up dependencies
+    const deps = this.dependencies.get(id);
+    if (deps) {
+      for (const depId of deps) {
+        this.dependents.get(depId)?.delete(id);
+      }
+    }
+
+    // Clean up dependents
+    const dependents = this.dependents.get(id);
+    if (dependents) {
+      for (const dependentId of dependents) {
+        this.dependencies.get(dependentId)?.delete(id);
+      }
+    }
+
+    this.cells.delete(id);
+    this.dependencies.delete(id);
+    this.dependents.delete(id);
+  }
+
+  /**
+   * Get all cells
+   */
+  getAll(): ExecutableCell[] {
+    return Array.from(this.cells.values());
+  }
+
+  /**
+   * Get cells by language
+   */
+  getByLanguage(language: Language): ExecutableCell[] {
+    return this.getAll().filter(c => c.language === language);
+  }
+
+  /**
+   * Get cells by state
+   */
+  getByState(state: CellState): ExecutableCell[] {
+    return this.getAll().filter(c => c.state === state);
+  }
+
+  /**
+   * Add dependency between cells
+   */
+  addDependency(cellId: string, dependsOn: string): void {
+    if (!this.dependencies.has(cellId)) {
+      this.dependencies.set(cellId, new Set());
+    }
+    this.dependencies.get(cellId)!.add(dependsOn);
+
+    if (!this.dependents.has(dependsOn)) {
+      this.dependents.set(dependsOn, new Set());
+    }
+    this.dependents.get(dependsOn)!.add(cellId);
+  }
+
+  /**
+   * Get dependencies of a cell
+   */
+  getDependencies(cellId: string): string[] {
+    return Array.from(this.dependencies.get(cellId) ?? []);
+  }
+
+  /**
+   * Get dependents of a cell (cells that depend on this one)
+   */
+  getDependents(cellId: string): string[] {
+    return Array.from(this.dependents.get(cellId) ?? []);
+  }
+
+  /**
+   * Get execution order (topological sort)
+   */
+  getExecutionOrder(): string[] {
+    const order: string[] = [];
+    const visited = new Set<string>();
+    const visiting = new Set<string>();
+
+    const visit = (id: string) => {
+      if (visited.has(id)) return;
+      if (visiting.has(id)) {
+        throw new Error(`Circular dependency detected involving cell: ${id}`);
+      }
+
+      visiting.add(id);
+
+      const deps = this.dependencies.get(id);
+      if (deps) {
+        for (const dep of deps) {
+          visit(dep);
+        }
+      }
+
+      visiting.delete(id);
+      visited.add(id);
+      order.push(id);
+    };
+
+    for (const id of this.cells.keys()) {
+      visit(id);
+    }
+
+    return order;
+  }
+
+  /**
+   * Check if cell has circular dependencies
+   */
+  hasCircularDependency(cellId: string): boolean {
+    try {
+      this.getExecutionOrder();
+      return false;
+    } catch {
+      return true;
+    }
+  }
+
+  /**
+   * Get cells that need re-execution after a cell changes
+   */
+  getCellsToReexecute(cellId: string): string[] {
+    const toReexecute: string[] = [];
+    const visited = new Set<string>();
+
+    const collect = (id: string) => {
+      if (visited.has(id)) return;
+      visited.add(id);
+      toReexecute.push(id);
+
+      const dependents = this.dependents.get(id);
+      if (dependents) {
+        for (const dependent of dependents) {
+          collect(dependent);
+        }
+      }
+    };
+
+    collect(cellId);
+    return toReexecute.slice(1); // Exclude the original cell
+  }
+
+  /**
+   * Clear all cells
+   */
+  clear(): void {
+    this.cells.clear();
+    this.dependencies.clear();
+    this.dependents.clear();
+  }
+
+  /**
+   * Get count
+   */
+  get count(): number {
+    return this.cells.size;
+  }
+}
+
+/**
+ * Create a simple cell
+ */
+export function createCell(
+  language: Language,
+  source: string,
+  options?: {
+    id?: string;
+    metadata?: CellMetadata;
+    dependencies?: string[];
+  }
+): ExecutableCell {
+  return {
+    id: options?.id ?? uuid(),
+    language,
+    source,
+    metadata: options?.metadata,
+    dependencies: options?.dependencies,
+    state: "idle",
+  };
+}
+
+/**
+ * Create cells from code blocks
+ */
+export function createCellsFromMarkdown(
+  markdown: string,
+  defaultLanguage: Language = "javascript"
+): ExecutableCell[] {
+  const cells: ExecutableCell[] = [];
+  const codeBlockRegex = /```(\w+)?\n([\s\S]*?)```/g;
+  let match;
+  let index = 0;
+
+  while ((match = codeBlockRegex.exec(markdown)) !== null) {
+    const lang = (match[1] as Language) ?? defaultLanguage;
+    const source = match[2].trim();
+
+    cells.push(
+      createCell(lang, source, {
+        metadata: { index: index++ },
+      })
+    );
+  }
+
+  return cells;
+}
+
+/**
+ * Convert cells to markdown
+ */
+export function cellsToMarkdown(cells: ExecutableCell[]): string {
+  return cells
+    .sort((a, b) => ((a.metadata?.index as number) ?? 0) - ((b.metadata?.index as number) ?? 0))
+    .map(cell => {
+      const lang = cell.language === "javascript" ? "js" : cell.language;
+      return `\`\`\`${lang}\n${cell.source}\n\`\`\``;
+    })
+    .join("\n\n");
+}

package/src/core/compiler.ts

@@ -0,0 +1,250 @@
+/**
+ * Compiler Primitive
+ *
+ * Transforms source code to executable format (typically WASM).
+ * Composable: mix and match compilers for different languages.
+ */
+
+import type { Language, Permissions, Limits } from "./types.js";
+
+/** Compiler result */
+export interface CompileResult {
+  /** Compiled WASM bytes */
+  wasmBytes: Uint8Array;
+  /** Original source code (for interpreted languages) */
+  source?: string;
+  /** Source map for debugging */
+  sourceMap?: string;
+  /** Exported functions */
+  exports: string[];
+  /** Imported functions needed */
+  imports: ImportDefinition[];
+  /** Memory requirements */
+  memoryRequirements?: {
+    initial: number;  // Pages
+    maximum?: number; // Pages
+  };
+}
+
+/** Import definition */
+export interface ImportDefinition {
+  module: string;
+  name: string;
+  type: "function" | "memory" | "global" | "table";
+  signature?: string;
+}
+
+/** Compiler options */
+export interface CompilerOptions {
+  /** Optimize output */
+  optimize?: boolean;
+  /** Debug info */
+  debug?: boolean;
+  /** Source map */
+  sourceMap?: boolean;
+  /** Target WASM features */
+  features?: {
+    simd?: boolean;
+    threads?: boolean;
+    referenceTypes?: boolean;
+    bulkMemory?: boolean;
+  };
+  /** Additional compiler-specific options */
+  extra?: Record<string, unknown>;
+}
+
+/** Base compiler interface */
+export interface ICompiler {
+  /** Language this compiler handles */
+  readonly language: Language;
+
+  /** Check if this compiler is available */
+  isAvailable(): Promise<boolean>;
+
+  /** Check if code syntax is valid */
+  validate(source: string): Promise<{ valid: boolean; error?: string }>;
+
+  /** Compile source to WASM */
+  compile(
+    source: string,
+    permissions: Permissions,
+    limits: Limits,
+    options?: CompilerOptions
+  ): Promise<CompileResult>;
+
+  /** Get language capabilities */
+  getCapabilities(): LanguageCapabilities;
+}
+
+/** Language capabilities */
+export interface LanguageCapabilities {
+  /** Supports REPL-style execution */
+  repl: boolean;
+  /** Can maintain state between executions */
+  stateful: boolean;
+  /** Requires compilation step */
+  compiled: boolean;
+  /** Has garbage collection */
+  gc: boolean;
+  /** Can import external modules */
+  imports: boolean;
+  /** Supports async/await */
+  async: boolean;
+}
+
+/**
+ * Base Compiler class
+ *
+ * Extend this to create language-specific compilers.
+ */
+export abstract class BaseCompiler implements ICompiler {
+  abstract readonly language: Language;
+
+  async isAvailable(): Promise<boolean> {
+    return true; // Override if compiler needs external tools
+  }
+
+  async validate(_source: string): Promise<{ valid: boolean; error?: string }> {
+    return { valid: true }; // Override for language-specific validation
+  }
+
+  abstract compile(
+    source: string,
+    permissions: Permissions,
+    limits: Limits,
+    options?: CompilerOptions
+  ): Promise<CompileResult>;
+
+  getCapabilities(): LanguageCapabilities {
+    return {
+      repl: false,
+      stateful: false,
+      compiled: true,
+      gc: false,
+      imports: false,
+      async: false,
+    };
+  }
+}
+
+/**
+ * WASM Passthrough Compiler
+ *
+ * Treats already-compiled WASM as "compiled".
+ * Used when source is already WASM bytes.
+ */
+export class WasmCompiler extends BaseCompiler {
+  readonly language = "wasm" as const;
+
+  async validate(source: string | Uint8Array): Promise<{ valid: boolean; error?: string }> {
+    try {
+      const bytes = typeof source === "string"
+        ? new TextEncoder().encode(source)
+        : source;
+
+      // Check WASM magic number
+      if (bytes[0] !== 0x00 || bytes[1] !== 0x61 || bytes[2] !== 0x73 || bytes[3] !== 0x6D) {
+        return { valid: false, error: "Invalid WASM magic number" };
+      }
+
+      // Use WebAssembly.validate
+      const valid = WebAssembly.validate(bytes);
+      return { valid };
+    } catch (error) {
+      return { valid: false, error: String(error) };
+    }
+  }
+
+  async compile(
+    source: string | Uint8Array,
+    _permissions: Permissions,
+    _limits: Limits,
+    _options?: CompilerOptions
+  ): Promise<CompileResult> {
+    const wasmBytes = typeof source === "string"
+      ? new TextEncoder().encode(source)
+      : source;
+
+    // Extract exports from module
+    const module = await WebAssembly.compile(wasmBytes);
+    const exports = WebAssembly.Module.exports(module).map(e => e.name);
+    const imports = WebAssembly.Module.imports(module).map(i => ({
+      module: i.module,
+      name: i.name,
+      type: i.kind as "function" | "memory" | "global" | "table",
+    }));
+
+    return {
+      wasmBytes,
+      exports,
+      imports,
+    };
+  }
+
+  getCapabilities(): LanguageCapabilities {
+    return {
+      repl: false,
+      stateful: true,
+      compiled: true,
+      gc: false,
+      imports: true,
+      async: true,
+    };
+  }
+}
+
+/**
+ * Compiler Registry
+ *
+ * Manages available compilers and routes code to the right one.
+ */
+export class CompilerRegistry {
+  private compilers = new Map<Language, ICompiler>();
+
+  register(compiler: ICompiler): void {
+    this.compilers.set(compiler.language, compiler);
+  }
+
+  get(language: Language): ICompiler | undefined {
+    return this.compilers.get(language);
+  }
+
+  has(language: Language): boolean {
+    return this.compilers.has(language);
+  }
+
+  async getAvailable(): Promise<Language[]> {
+    const available: Language[] = [];
+    for (const [lang, compiler] of this.compilers) {
+      if (await compiler.isAvailable()) {
+        available.push(lang);
+      }
+    }
+    return available;
+  }
+
+  async compile(
+    source: string | Uint8Array,
+    language: Language,
+    permissions: Permissions,
+    limits: Limits,
+    options?: CompilerOptions
+  ): Promise<CompileResult> {
+    const compiler = this.compilers.get(language);
+    if (!compiler) {
+      throw new Error(`No compiler registered for language: ${language}`);
+    }
+
+    if (!(await compiler.isAvailable())) {
+      throw new Error(`Compiler for ${language} is not available`);
+    }
+
+    return (compiler as unknown as {
+      compile: (src: string | Uint8Array, perms: Permissions, lim: Limits, opts?: CompilerOptions) => Promise<CompileResult>;
+    }).compile(source, permissions, limits, options);
+  }
+}
+
+// Default registry with built-in compilers
+export const defaultCompilerRegistry = new CompilerRegistry();
+defaultCompilerRegistry.register(new WasmCompiler());