@danielsimonjr/mathts-workbook 0.1.1

package/README.md

@@ -0,0 +1,121 @@
+# @danielsimonjr/mathts-workbook
+
+Scientific workbook runtime for MathTS with reactive YAML-based notebooks (`.mtsw` format).
+
+## Installation
+
+```bash
+npm install @danielsimonjr/mathts-workbook
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Run a workbook
+mtsw run example.mtsw
+
+# Run specific cell
+mtsw run example.mtsw -c compute
+
+# Watch for changes
+mtsw watch example.mtsw
+
+# Validate structure
+mtsw validate example.mtsw
+
+# Show dependency graph
+mtsw graph example.mtsw
+
+# Create from template
+mtsw new my-workbook -t tensor-physics
+
+# Export
+mtsw export example.mtsw -f html
+```
+
+### Programmatic API
+
+```typescript
+import { parseWorkbook, createExecutor } from '@danielsimonjr/mathts-workbook';
+
+const content = `
+version: "1.0"
+metadata:
+  title: "My Workbook"
+runtime:
+  engine: mathts
+  execution: reactive
+cells:
+  - code: |
+      const x = 42;
+      export { x };
+    id: compute
+`;
+
+const result = parseWorkbook(content);
+if (result.success && result.workbook) {
+  const executor = createExecutor(result.workbook);
+
+  executor.on((event) => {
+    console.log(event.type, event.cellId);
+  });
+
+  await executor.runAll();
+}
+```
+
+## Workbook Format (.mtsw)
+
+```yaml
+version: "1.0"
+metadata:
+  title: "Matrix Analysis"
+  author: "Your Name"
+
+runtime:
+  engine: mathts
+  execution: reactive  # reactive | sequential | manual
+
+cells:
+  - markdown: |
+      # Introduction
+    id: intro
+
+  - code: |
+      import { Matrix } from '@danielsimonjr/mathts-matrix';
+      const A = Matrix.random(3, 3);
+      export { A };
+    id: create-matrix
+
+  - code: |
+      import { A } from '#create-matrix';
+      const det = A.determinant();
+      console.log('Determinant:', det);
+    id: compute
+    depends_on: [create-matrix]
+```
+
+## Cell Types
+
+| Type | Description |
+|------|-------------|
+| `markdown` | Documentation with LaTeX math |
+| `code` | TypeScript/JavaScript execution |
+| `tensor` | Einstein notation for tensor math |
+| `equation` | LaTeX equations with labels |
+| `visualization` | Three.js/D3/Plotly rendering |
+| `data` | YAML/JSON/CSV data |
+| `test` | Assertions with timeout |
+| `export` | Publication output |
+
+## Execution Modes
+
+- **reactive** - Auto-rerun when dependencies change
+- **sequential** - Top-to-bottom execution
+- **manual** - Explicit trigger only
+
+## License
+
+MIT

package/dist/chunk-64JBL36K.js

@@ -0,0 +1,273 @@
+// src/parser.ts
+function parseWorkbook(content) {
+  try {
+    const errors = [];
+    const warnings = [];
+    if (!content.trim()) {
+      return {
+        success: false,
+        errors: ["Empty workbook content"]
+      };
+    }
+    const workbook = {
+      version: "1.0",
+      metadata: {
+        title: "Untitled Workbook"
+      },
+      runtime: {
+        engine: "mathts",
+        execution: "reactive"
+      },
+      cells: []
+    };
+    if (warnings.length > 0 || errors.length > 0) {
+      return {
+        success: errors.length === 0,
+        workbook: errors.length === 0 ? workbook : void 0,
+        errors: errors.length > 0 ? errors : void 0,
+        warnings: warnings.length > 0 ? warnings : void 0
+      };
+    }
+    return {
+      success: true,
+      workbook
+    };
+  } catch (error) {
+    return {
+      success: false,
+      errors: [`Parse error: ${error instanceof Error ? error.message : String(error)}`]
+    };
+  }
+}
+function serializeWorkbook(_workbook) {
+  throw new Error("serializeWorkbook not yet implemented");
+}
+function stripOutputs(workbook) {
+  return {
+    ...workbook,
+    cells: workbook.cells.map((cell) => ({
+      ...cell,
+      output: void 0,
+      error: void 0
+    }))
+  };
+}
+
+// src/graph.ts
+function buildDependencyGraph(cells) {
+  const nodes = /* @__PURE__ */ new Map();
+  for (const cell of cells) {
+    nodes.set(cell.id, {
+      id: cell.id,
+      dependencies: cell.dependsOn ?? [],
+      dependents: []
+    });
+  }
+  for (const cell of cells) {
+    for (const depId of cell.dependsOn ?? []) {
+      const depNode = nodes.get(depId);
+      if (depNode) {
+        depNode.dependents.push(cell.id);
+      }
+    }
+  }
+  const executionOrder = topologicalSort(nodes);
+  return { nodes, executionOrder };
+}
+function topologicalSort(nodes) {
+  const visited = /* @__PURE__ */ new Set();
+  const result = [];
+  function visit(id) {
+    if (visited.has(id)) return;
+    visited.add(id);
+    const node = nodes.get(id);
+    if (node) {
+      for (const depId of node.dependencies) {
+        visit(depId);
+      }
+    }
+    result.push(id);
+  }
+  for (const id of nodes.keys()) {
+    visit(id);
+  }
+  return result;
+}
+function getDependents(graph, cellId) {
+  const result = [];
+  const visited = /* @__PURE__ */ new Set();
+  function collect(id) {
+    const node = graph.nodes.get(id);
+    if (!node) return;
+    for (const depId of node.dependents) {
+      if (!visited.has(depId)) {
+        visited.add(depId);
+        result.push(depId);
+        collect(depId);
+      }
+    }
+  }
+  collect(cellId);
+  return result;
+}
+
+// src/executor.ts
+var WorkbookExecutor = class {
+  workbook;
+  graph;
+  outputs = /* @__PURE__ */ new Map();
+  handlers = [];
+  constructor(workbook) {
+    this.workbook = workbook;
+    this.graph = buildDependencyGraph(workbook.cells);
+  }
+  /**
+   * Subscribe to execution events
+   */
+  on(handler) {
+    this.handlers.push(handler);
+    return () => {
+      const index = this.handlers.indexOf(handler);
+      if (index >= 0) {
+        this.handlers.splice(index, 1);
+      }
+    };
+  }
+  /**
+   * Emit an event to all handlers
+   */
+  emit(event) {
+    for (const handler of this.handlers) {
+      handler(event);
+    }
+  }
+  /**
+   * Run all cells in order
+   */
+  async runAll() {
+    for (const cellId of this.graph.executionOrder) {
+      await this.runCell(cellId);
+    }
+    this.emit({
+      type: "workbook:complete",
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Run a specific cell
+   */
+  async runCell(cellId) {
+    const cell = this.workbook.cells.find((c) => c.id === cellId);
+    if (!cell) {
+      throw new Error(`Cell not found: ${cellId}`);
+    }
+    this.emit({
+      type: "cell:start",
+      cellId,
+      timestamp: Date.now()
+    });
+    try {
+      const output = await this.executeCell(cell);
+      this.outputs.set(cellId, output);
+      this.emit({
+        type: "cell:success",
+        cellId,
+        output,
+        timestamp: Date.now()
+      });
+      if (this.workbook.runtime.execution === "reactive") {
+        const dependents = getDependents(this.graph, cellId);
+        for (const depId of dependents) {
+          this.emit({
+            type: "cell:stale",
+            cellId: depId,
+            timestamp: Date.now()
+          });
+        }
+      }
+      return output;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.emit({
+        type: "cell:error",
+        cellId,
+        error: errorMessage,
+        timestamp: Date.now()
+      });
+      throw error;
+    }
+  }
+  /**
+   * Execute a single cell
+   */
+  async executeCell(cell) {
+    switch (cell.type) {
+      case "code":
+        return this.executeCode(cell);
+      case "markdown":
+        return cell.content;
+      // Markdown is pass-through
+      case "data":
+        return this.executeData(cell);
+      default:
+        throw new Error(`Unsupported cell type: ${cell.type}`);
+    }
+  }
+  /**
+   * Execute a code cell by evaluating its content with scope from dependency outputs.
+   *
+   * Uses the Function constructor to evaluate expressions. Cell dependencies
+   * are injected as named variables in the evaluation scope, allowing cells
+   * to reference outputs of earlier cells by their id.
+   */
+  async executeCode(cell) {
+    const scope = {};
+    if (cell.dependsOn) {
+      for (const depId of cell.dependsOn) {
+        const output = this.outputs.get(depId);
+        if (output !== void 0) {
+          scope[depId] = output;
+        }
+      }
+    }
+    const scopeKeys = Object.keys(scope);
+    const scopeValues = scopeKeys.map((k) => scope[k]);
+    try {
+      const fn = new Function(...scopeKeys, `return (${cell.content});`);
+      return fn(...scopeValues);
+    } catch {
+      const fn = new Function(...scopeKeys, cell.content);
+      return fn(...scopeValues);
+    }
+  }
+  /**
+   * Execute a data cell
+   */
+  async executeData(cell) {
+    return cell.content;
+  }
+  /**
+   * Get output from a previous cell
+   */
+  getOutput(cellId) {
+    return this.outputs.get(cellId);
+  }
+};
+function createExecutor(workbook) {
+  return new WorkbookExecutor(workbook);
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+
+export {
+  parseWorkbook,
+  serializeWorkbook,
+  stripOutputs,
+  buildDependencyGraph,
+  topologicalSort,
+  getDependents,
+  WorkbookExecutor,
+  createExecutor,
+  VERSION
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import {
+  createExecutor,
+  parseWorkbook
+} from "./chunk-64JBL36K.js";
+
+// src/cli.ts
+var HELP = `
+mtsw - MathTS Workbook CLI
+
+Usage:
+  mtsw run <file>              Execute a workbook
+  mtsw run <file> -c <cell>    Run specific cell
+  mtsw run <file> -v           Verbose output
+  mtsw watch <file>            Watch and re-run on changes
+  mtsw validate <file>         Validate workbook structure
+  mtsw graph <file>            Show dependency graph
+  mtsw graph <file> -f mermaid Export as Mermaid diagram
+  mtsw strip <file>            Strip outputs (for git)
+  mtsw new <name>              Create new workbook
+  mtsw new <name> -t <template> Use template (basic|tensor-physics|data-science)
+  mtsw export <file> -f <fmt>  Export to format (html|pdf|ipynb|latex)
+
+Options:
+  -h, --help     Show this help
+  -v, --verbose  Verbose output
+  -V, --version  Show version
+`;
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args.includes("-h") || args.includes("--help")) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  if (args.includes("-V") || args.includes("--version")) {
+    console.log("mtsw version 0.1.0");
+    process.exit(0);
+  }
+  const command = args[0];
+  switch (command) {
+    case "run":
+      await runCommand(args.slice(1));
+      break;
+    case "validate":
+      await validateCommand(args.slice(1));
+      break;
+    case "graph":
+      await graphCommand(args.slice(1));
+      break;
+    case "new":
+      await newCommand(args.slice(1));
+      break;
+    default:
+      console.error(`Unknown command: ${command}`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+async function runCommand(args) {
+  const file = args[0];
+  if (!file) {
+    console.error("Usage: mtsw run <file>");
+    process.exit(1);
+  }
+  console.log(`Running workbook: ${file}`);
+  const content = "";
+  const result = parseWorkbook(content);
+  if (!result.success) {
+    console.error("Parse errors:", result.errors);
+    process.exit(1);
+  }
+  if (result.workbook) {
+    const executor = createExecutor(result.workbook);
+    executor.on((event) => {
+      console.log(`[${event.type}] ${event.cellId ?? ""}`);
+    });
+    await executor.runAll();
+  }
+}
+async function validateCommand(args) {
+  const file = args[0];
+  if (!file) {
+    console.error("Usage: mtsw validate <file>");
+    process.exit(1);
+  }
+  console.log(`Validating: ${file}`);
+}
+async function graphCommand(args) {
+  const file = args[0];
+  if (!file) {
+    console.error("Usage: mtsw graph <file>");
+    process.exit(1);
+  }
+  console.log(`Dependency graph for: ${file}`);
+}
+async function newCommand(args) {
+  const name = args[0];
+  if (!name) {
+    console.error("Usage: mtsw new <name>");
+    process.exit(1);
+  }
+  console.log(`Creating new workbook: ${name}.mtsw`);
+}
+main().catch((error) => {
+  console.error("Error:", error);
+  process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Workbook type definitions
+ */
+/**
+ * Supported cell types
+ */
+type CellType = 'markdown' | 'code' | 'tensor' | 'equation' | 'visualization' | 'data' | 'test' | 'export';
+/**
+ * Execution modes
+ */
+type ExecutionMode = 'reactive' | 'sequential' | 'manual';
+/**
+ * Workbook metadata
+ */
+interface WorkbookMetadata {
+    title?: string;
+    author?: string;
+    description?: string;
+    tags?: string[];
+    created?: string;
+    modified?: string;
+}
+/**
+ * Runtime configuration
+ */
+interface RuntimeConfig {
+    engine: 'mathts' | 'custom';
+    execution: ExecutionMode;
+    timeout?: number;
+}
+/**
+ * Individual cell in a workbook
+ */
+interface Cell {
+    id: string;
+    type: CellType;
+    content: string;
+    dependsOn?: string[];
+    output?: unknown;
+    error?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Complete workbook structure
+ */
+interface Workbook {
+    version: string;
+    metadata: WorkbookMetadata;
+    runtime: RuntimeConfig;
+    cells: Cell[];
+}
+/**
+ * Parse result with validation
+ */
+interface ParseResult {
+    success: boolean;
+    workbook?: Workbook;
+    errors?: string[];
+    warnings?: string[];
+}
+/**
+ * Workbook execution events
+ */
+interface WorkbookEvent {
+    type: 'cell:start' | 'cell:success' | 'cell:error' | 'cell:stale' | 'workbook:complete';
+    cellId?: string;
+    output?: unknown;
+    error?: string;
+    timestamp: number;
+}
+/**
+ * Dependency graph node
+ */
+interface DependencyNode {
+    id: string;
+    dependencies: string[];
+    dependents: string[];
+}
+/**
+ * Dependency graph
+ */
+interface DependencyGraph {
+    nodes: Map<string, DependencyNode>;
+    executionOrder: string[];
+}
+
+/**
+ * Workbook YAML parser
+ */
+
+/**
+ * Parse a workbook from YAML content
+ */
+declare function parseWorkbook(content: string): ParseResult;
+/**
+ * Serialize a workbook to YAML
+ */
+declare function serializeWorkbook(_workbook: Workbook): string;
+/**
+ * Strip outputs from workbook (for git)
+ */
+declare function stripOutputs(workbook: Workbook): Workbook;
+
+/**
+ * Dependency graph management
+ */
+
+/**
+ * Build dependency graph from cells
+ */
+declare function buildDependencyGraph(cells: Cell[]): DependencyGraph;
+/**
+ * Topological sort for execution order
+ */
+declare function topologicalSort(nodes: Map<string, DependencyNode>): string[];
+/**
+ * Get all cells that depend on a given cell
+ */
+declare function getDependents(graph: DependencyGraph, cellId: string): string[];
+
+/**
+ * Workbook executor
+ */
+
+/**
+ * Event handler type
+ */
+type EventHandler = (event: WorkbookEvent) => void;
+/**
+ * Workbook executor with reactive execution support
+ */
+declare class WorkbookExecutor {
+    private workbook;
+    private graph;
+    private outputs;
+    private handlers;
+    constructor(workbook: Workbook);
+    /**
+     * Subscribe to execution events
+     */
+    on(handler: EventHandler): () => void;
+    /**
+     * Emit an event to all handlers
+     */
+    private emit;
+    /**
+     * Run all cells in order
+     */
+    runAll(): Promise<void>;
+    /**
+     * Run a specific cell
+     */
+    runCell(cellId: string): Promise<unknown>;
+    /**
+     * Execute a single cell
+     */
+    private executeCell;
+    /**
+     * Execute a code cell by evaluating its content with scope from dependency outputs.
+     *
+     * Uses the Function constructor to evaluate expressions. Cell dependencies
+     * are injected as named variables in the evaluation scope, allowing cells
+     * to reference outputs of earlier cells by their id.
+     */
+    private executeCode;
+    /**
+     * Execute a data cell
+     */
+    private executeData;
+    /**
+     * Get output from a previous cell
+     */
+    getOutput(cellId: string): unknown;
+}
+/**
+ * Create an executor for a workbook
+ */
+declare function createExecutor(workbook: Workbook): WorkbookExecutor;
+
+/**
+ * @danielsimonjr/mathts-workbook - Scientific workbook runtime
+ * @packageDocumentation
+ */
+
+declare const VERSION = "0.1.0";
+
+export { type Cell, type CellType, type ExecutionMode, type ParseResult, type RuntimeConfig, VERSION, type Workbook, type WorkbookEvent, WorkbookExecutor, type WorkbookMetadata, buildDependencyGraph, createExecutor, getDependents, parseWorkbook, serializeWorkbook, stripOutputs, topologicalSort };

package/dist/index.js

@@ -0,0 +1,22 @@
+import {
+  VERSION,
+  WorkbookExecutor,
+  buildDependencyGraph,
+  createExecutor,
+  getDependents,
+  parseWorkbook,
+  serializeWorkbook,
+  stripOutputs,
+  topologicalSort
+} from "./chunk-64JBL36K.js";
+export {
+  VERSION,
+  WorkbookExecutor,
+  buildDependencyGraph,
+  createExecutor,
+  getDependents,
+  parseWorkbook,
+  serializeWorkbook,
+  stripOutputs,
+  topologicalSort
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@danielsimonjr/mathts-workbook",
+  "version": "0.1.1",
+  "description": "Scientific workbook runtime for MathTS (.mtsw format)",
+  "author": "Daniel Simon Jr.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "mtsw": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/cli.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "clean": "rm -rf dist",
+    "build:prod": "tsup src/index.ts src/cli.ts --format esm --dts --clean --minify --treeshake"
+  },
+  "dependencies": {
+    "@danielsimonjr/mathts-core": "*",
+    "yaml": "^2.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/danielsimonjr/mathts",
+    "directory": "packages/workbook"
+  },
+  "keywords": [
+    "notebook",
+    "workbook",
+    "scientific-computing",
+    "reactive",
+    "yaml"
+  ]
+}