@ebowwa/sandbox 0.1.1

package/src/session/notebook.ts

@@ -0,0 +1,635 @@
+/**
+ * Notebook Primitive
+ *
+ * Multi-cell, multi-language document with sequential execution.
+ * Jupyter-style notebook with cell dependencies and state sharing.
+ */
+
+import type {
+  Language,
+  Notebook,
+  NotebookMetadata,
+  NotebookRunOptions,
+  NotebookResult,
+  Cell,
+  ExecutionResult,
+  ExecutionOptions,
+  Permissions,
+  Limits,
+} from "../core/types.js";
+import { CellRegistry, CellBuilder } from "../core/cell.js";
+import type { ExecutableCell, CellState } from "../core/cell.js";
+import { BaseKernel, KernelManager } from "./kernel.js";
+import type { KernelOptions } from "./kernel.js";
+import { createPermissions } from "../core/permissions.js";
+import { v4 as uuid } from "uuid";
+
+/**
+ * Notebook options
+ */
+export interface NotebookOptions {
+  /** Notebook ID */
+  id?: string;
+  /** Notebook name */
+  name?: string;
+  /** Default language */
+  defaultLanguage?: Language;
+  /** Initial cells */
+  cells?: Cell[];
+  /** Permissions */
+  permissions?: Permissions;
+  /** Resource limits */
+  limits?: Limits;
+  /** Kernel manager to use */
+  kernelManager?: KernelManager;
+  /** Kernel factory */
+  kernelFactory?: (language: Language) => Promise<BaseKernel>;
+}
+
+/**
+ * Notebook state
+ */
+export type NotebookState =
+  | "idle"
+  | "running"
+  | "error"
+  | "cancelled";
+
+/**
+ * Notebook events
+ */
+export interface NotebookEvents {
+  onCellStart?: (cellId: string, cell: ExecutableCell) => void;
+  onCellComplete?: (cellId: string, result: ExecutionResult) => void;
+  onCellError?: (cellId: string, error: Error) => void;
+  onNotebookComplete?: (results: NotebookResult[]) => void;
+  onNotebookError?: (error: Error) => void;
+  onProgress?: (completed: number, total: number) => void;
+}
+
+/**
+ * Base Notebook Implementation
+ */
+export class BaseNotebook implements Notebook {
+  readonly id: string;
+  readonly metadata: NotebookMetadata;
+
+  private registry: CellRegistry;
+  private kernelManager: KernelManager;
+  private kernelFactory?: (language: Language) => Promise<BaseKernel>;
+  private kernels = new Map<Language, BaseKernel>();
+  private permissions: Permissions;
+  private limits: Limits;
+  private state: NotebookState = "idle";
+  private executionCount = 0;
+  private events: NotebookEvents = {};
+  private abortController?: AbortController;
+
+  constructor(options: NotebookOptions) {
+    this.id = options.id ?? uuid();
+    this.registry = new CellRegistry();
+    this.kernelManager = options.kernelManager ?? new KernelManager();
+    this.kernelFactory = options.kernelFactory;
+    this.permissions = options.permissions ?? {};
+    this.limits = options.limits ?? {};
+
+    this.metadata = {
+      name: options.name ?? "Untitled",
+      language: options.defaultLanguage ?? "javascript",
+      created: new Date(),
+      modified: new Date(),
+    };
+
+    // Add initial cells
+    if (options.cells) {
+      for (const cell of options.cells) {
+        this.addCell(cell);
+      }
+    }
+  }
+
+  /**
+   * Get current state
+   */
+  getState(): NotebookState {
+    return this.state;
+  }
+
+  /**
+   * Set event handlers
+   */
+  setEvents(events: NotebookEvents): void {
+    this.events = { ...this.events, ...events };
+  }
+
+  /**
+   * Get all cells
+   */
+  get cells(): ExecutableCell[] {
+    return this.registry.getAll();
+  }
+
+  /**
+   * Add cell
+   */
+  addCell(cell: Omit<Cell, "id">): Cell {
+    const executableCell: ExecutableCell = {
+      ...cell,
+      id: uuid(),
+      state: "idle",
+      metadata: {
+        ...cell.metadata,
+        index: this.registry.count,
+      },
+    };
+
+    this.registry.add(executableCell);
+    this.metadata.modified = new Date();
+
+    return executableCell;
+  }
+
+  /**
+   * Remove cell
+   */
+  removeCell(cellId: string): void {
+    this.registry.remove(cellId);
+    this.metadata.modified = new Date();
+  }
+
+  /**
+   * Move cell
+   */
+  moveCell(cellId: string, newIndex: number): void {
+    const cell = this.registry.get(cellId);
+    if (!cell) return;
+
+    cell.metadata = { ...cell.metadata, index: newIndex };
+    this.metadata.modified = new Date();
+  }
+
+  /**
+   * Get cell by ID
+   */
+  getCell(cellId: string): Cell | undefined {
+    return this.registry.get(cellId);
+  }
+
+  /**
+   * Update cell source
+   */
+  updateCell(cellId: string, source: string): void {
+    const cell = this.registry.get(cellId);
+    if (!cell) return;
+
+    cell.source = source;
+    cell.state = "idle"; // Reset state on edit
+    cell.result = undefined;
+    this.metadata.modified = new Date();
+  }
+
+  /**
+   * Get or create kernel for language
+   */
+  private async getKernel(language: Language): Promise<BaseKernel> {
+    let kernel = this.kernels.get(language);
+
+    if (!kernel) {
+      if (this.kernelFactory) {
+        kernel = await this.kernelFactory(language);
+      } else {
+        // Create a basic kernel - would need proper compiler/runtime
+        throw new Error(`No kernel available for language: ${language}`);
+      }
+
+      this.kernels.set(language, kernel);
+    }
+
+    return kernel;
+  }
+
+  /**
+   * Execute all cells
+   */
+  async runAll(options?: NotebookRunOptions): Promise<NotebookResult[]> {
+    if (this.state === "running") {
+      throw new Error("Notebook is already running");
+    }
+
+    this.state = "running";
+    this.abortController = new AbortController();
+    const results: NotebookResult[] = [];
+    const executionOrder = this.registry.getExecutionOrder();
+    const total = executionOrder.length;
+    let completed = 0;
+
+    // Find start index
+    let startIndex = 0;
+    if (options?.continueFrom) {
+      startIndex = executionOrder.indexOf(options.continueFrom);
+      if (startIndex === -1) startIndex = 0;
+    }
+
+    try {
+      for (let i = startIndex; i < executionOrder.length; i++) {
+        // Check for abort
+        if (this.abortController.signal.aborted) {
+          this.state = "cancelled";
+          break;
+        }
+
+        const cellId = executionOrder[i];
+        const result = await this.runCell(cellId, {
+          signal: this.abortController.signal,
+        });
+
+        results.push(result);
+        completed++;
+        this.events.onProgress?.(completed, total);
+
+        // Stop on error
+        if (!result.result.success && options?.stopOnError !== false) {
+          this.state = "error";
+          break;
+        }
+      }
+
+      if (this.state === "running") {
+        this.state = "idle";
+      }
+
+      this.events.onNotebookComplete?.(results);
+      return results;
+    } catch (error) {
+      this.state = "error";
+      this.events.onNotebookError?.(error instanceof Error ? error : new Error(String(error)));
+      throw error;
+    }
+  }
+
+  /**
+   * Execute single cell
+   */
+  async runCell(
+    cellId: string,
+    options?: ExecutionOptions
+  ): Promise<NotebookResult> {
+    const cell = this.registry.get(cellId);
+    if (!cell) {
+      throw new Error(`Cell not found: ${cellId}`);
+    }
+
+    cell.state = "queued";
+    this.events.onCellStart?.(cellId, cell);
+
+    try {
+      // Get kernel for language
+      const kernel = await this.getKernel(cell.language);
+
+      // Execute
+      cell.state = "running";
+      const result = await kernel.execute(cell.source, options);
+
+      // Update cell
+      cell.result = result;
+      cell.state = result.success ? "success" : "error";
+      cell.executionCount = ++this.executionCount;
+      cell.lastRun = new Date();
+
+      this.events.onCellComplete?.(cellId, result);
+
+      return {
+        cellId,
+        executionCount: cell.executionCount,
+        result,
+        timestamp: new Date(),
+      };
+    } catch (error) {
+      cell.state = "error";
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.events.onCellError?.(cellId, err);
+
+      const result: ExecutionResult = {
+        success: false,
+        error: {
+          message: err.message,
+          type: "runtime",
+        },
+        metrics: { duration: 0, memoryUsed: 0 },
+        output: { stdout: [], stderr: [], displays: [] },
+      };
+
+      cell.result = result;
+
+      return {
+        cellId,
+        executionCount: ++this.executionCount,
+        result,
+        timestamp: new Date(),
+      };
+    }
+  }
+
+  /**
+   * Execute cells from index
+   */
+  async runFrom(startIndex: number): Promise<NotebookResult[]> {
+    const cells = this.registry
+      .getAll()
+      .sort((a, b) => ((a.metadata?.index as number) ?? 0) - ((b.metadata?.index as number) ?? 0));
+
+    if (startIndex >= cells.length) {
+      return [];
+    }
+
+    const startCell = cells[startIndex];
+    return this.runAll({ continueFrom: startCell.id });
+  }
+
+  /**
+   * Run cells that depend on a changed cell
+   */
+  async runDependents(cellId: string): Promise<NotebookResult[]> {
+    const toReexecute = this.registry.getCellsToReexecute(cellId);
+    const results: NotebookResult[] = [];
+
+    for (const depId of toReexecute) {
+      const result = await this.runCell(depId);
+      results.push(result);
+
+      if (!result.result.success) {
+        break;
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Cancel execution
+   */
+  cancel(): void {
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+  }
+
+  /**
+   * Clear all cell outputs
+   */
+  clearOutputs(): void {
+    for (const cell of this.registry.getAll()) {
+      cell.result = undefined;
+      cell.state = "idle";
+    }
+    this.executionCount = 0;
+  }
+
+  /**
+   * Restart all kernels
+   */
+  async restart(): Promise<void> {
+    for (const kernel of this.kernels.values()) {
+      await kernel.restart();
+    }
+    this.clearOutputs();
+  }
+
+  /**
+   * Export notebook
+   */
+  export(format: "ipynb" | "json" | "markdown"): string {
+    switch (format) {
+      case "ipynb":
+        return this.toIpynb();
+      case "json":
+        return this.toJson();
+      case "markdown":
+        return this.toMarkdown();
+    }
+  }
+
+  /**
+   * Import notebook
+   */
+  static import(data: string, format: "ipynb" | "json" | "markdown"): BaseNotebook {
+    switch (format) {
+      case "ipynb":
+        return BaseNotebook.fromIpynb(data);
+      case "json":
+        return BaseNotebook.fromJson(data);
+      case "markdown":
+        return BaseNotebook.fromMarkdown(data);
+    }
+  }
+
+  /**
+   * Export to Jupyter format
+   */
+  private toIpynb(): string {
+    const cells = this.registry.getAll().sort(
+      (a, b) => ((a.metadata?.index as number) ?? 0) - ((b.metadata?.index as number) ?? 0)
+    );
+
+    const ipynb = {
+      nbformat: 4,
+      nbformat_minor: 5,
+      metadata: {
+        kernelspec: {
+          display_name: this.metadata.name,
+          language: this.metadata.language,
+          name: this.metadata.language,
+        },
+        language_info: {
+          name: this.metadata.language,
+        },
+      },
+      cells: cells.map(cell => ({
+        id: cell.id,
+        cell_type: "code",
+        metadata: cell.metadata ?? {},
+        source: cell.source.split("\n"),
+        execution_count: cell.executionCount ?? null,
+        outputs: this.cellToOutputs(cell),
+      })),
+    };
+
+    return JSON.stringify(ipynb, null, 2);
+  }
+
+  /**
+   * Export to JSON
+   */
+  private toJson(): string {
+    return JSON.stringify({
+      id: this.id,
+      metadata: this.metadata,
+      cells: this.registry.getAll(),
+    }, null, 2);
+  }
+
+  /**
+   * Export to Markdown
+   */
+  private toMarkdown(): string {
+    const cells = this.registry.getAll().sort(
+      (a, b) => ((a.metadata?.index as number) ?? 0) - ((b.metadata?.index as number) ?? 0)
+    );
+
+    const lines: string[] = [
+      `# ${this.metadata.name}`,
+      "",
+      `> Language: ${this.metadata.language}`,
+      `> Created: ${this.metadata.created.toISOString()}`,
+      "",
+    ];
+
+    for (const cell of cells) {
+      const lang = cell.language === "javascript" ? "js" : cell.language;
+      lines.push(`\`\`\`${lang}`);
+      lines.push(cell.source);
+      lines.push("```");
+      lines.push("");
+
+      if (cell.result) {
+        if (cell.result.output.stdout.length > 0) {
+          lines.push("**Output:**");
+          lines.push("```");
+          lines.push(...cell.result.output.stdout);
+          lines.push("```");
+          lines.push("");
+        }
+      }
+    }
+
+    return lines.join("\n");
+  }
+
+  /**
+   * Import from Jupyter format
+   */
+  static fromIpynb(data: string): BaseNotebook {
+    const ipynb = JSON.parse(data);
+    const cells: Cell[] = [];
+
+    for (const cell of ipynb.cells ?? []) {
+      if (cell.cell_type === "code") {
+        cells.push({
+          id: cell.id ?? uuid(),
+          language: (ipynb.metadata?.language_info?.name as Language) ?? "python",
+          source: Array.isArray(cell.source)
+            ? cell.source.join("\n")
+            : cell.source,
+          metadata: cell.metadata,
+        });
+      }
+    }
+
+    return new BaseNotebook({
+      name: ipynb.metadata?.kernelspec?.display_name ?? "Imported Notebook",
+      defaultLanguage: ipynb.metadata?.language_info?.name,
+      cells,
+    });
+  }
+
+  /**
+   * Import from JSON
+   */
+  static fromJson(data: string): BaseNotebook {
+    const obj = JSON.parse(data);
+
+    return new BaseNotebook({
+      id: obj.id,
+      name: obj.metadata?.name,
+      defaultLanguage: obj.metadata?.language,
+      cells: obj.cells,
+    });
+  }
+
+  /**
+   * Import from Markdown
+   */
+  static fromMarkdown(data: string): BaseNotebook {
+    const cells: ExecutableCell[] = [];
+    const codeBlockRegex = /```(\w+)?\n([\s\S]*?)```/g;
+    let match;
+    let index = 0;
+
+    // Extract title
+    const titleMatch = data.match(/^#\s+(.+)$/m);
+    const name = titleMatch ? titleMatch[1] : "Imported Notebook";
+
+    while ((match = codeBlockRegex.exec(data)) !== null) {
+      const lang = (match[1] as Language) ?? "javascript";
+      const source = match[2].trim();
+
+      cells.push({
+        id: uuid(),
+        language: lang,
+        source,
+        state: "idle",
+        metadata: { index: index++ },
+      });
+    }
+
+    const notebook = new BaseNotebook({ name, cells });
+    return notebook;
+  }
+
+  /**
+   * Convert cell outputs to Jupyter format
+   */
+  private cellToOutputs(cell: ExecutableCell): unknown[] {
+    const outputs: unknown[] = [];
+
+    if (!cell.result) return outputs;
+
+    // stdout
+    if (cell.result.output.stdout.length > 0) {
+      outputs.push({
+        output_type: "stream",
+        name: "stdout",
+        text: cell.result.output.stdout,
+      });
+    }
+
+    // stderr
+    if (cell.result.output.stderr.length > 0) {
+      outputs.push({
+        output_type: "stream",
+        name: "stderr",
+        text: cell.result.output.stderr,
+      });
+    }
+
+    // displays
+    for (const display of cell.result.output.displays) {
+      outputs.push({
+        output_type: "execute_result" as const,
+        data: {
+          [`text/${display.type}`]: display.data,
+        },
+        execution_count: cell.executionCount,
+      });
+    }
+
+    // error
+    if (cell.result.error) {
+      outputs.push({
+        output_type: "error",
+        ename: cell.result.error.type,
+        evalue: cell.result.error.message,
+        traceback: [cell.result.error.stack ?? ""],
+      });
+    }
+
+    return outputs;
+  }
+}
+
+/**
+ * Create a notebook
+ */
+export function createNotebook(options: NotebookOptions): BaseNotebook {
+  return new BaseNotebook(options);
+}