@danielsimonjr/mathts-workbook 0.1.8 → 0.2.0

package/dist/index.d.ts

@@ -68,6 +68,23 @@ interface WorkbookEvent {
     error?: string;
     timestamp: number;
 }
+/**
+ * Result of executing a single cell in a run report.
+ */
+interface CellResult {
+    id: string;
+    type: CellType;
+    status: 'success' | 'error' | 'pass' | 'fail';
+    output?: unknown;
+    error?: string;
+}
+/**
+ * Aggregated result of running an entire workbook (continue-on-error).
+ */
+interface RunResult {
+    cells: CellResult[];
+    ok: boolean;
+}
 /**
  * Dependency graph node
  */
@@ -89,13 +106,23 @@ interface DependencyGraph {
  */
 
 /**
- * Parse a workbook from YAML content
+ * Detect cell type from YAML keys (first match by precedence).
+ */
+declare function detectCellType(cell: Record<string, unknown>): CellType;
+/**
+ * Parse a workbook from YAML content.
  */
 declare function parseWorkbook(content: string): ParseResult;
 /**
- * Serialize a workbook to YAML
+ * Serialize a workbook to YAML that round-trips through {@link parseWorkbook}.
+ *
+ * Structural fidelity (version/metadata/runtime/cells: id/type/content/dependsOn/
+ * metadata) is exact. Persisted `output` values are best-effort: plain
+ * primitives/arrays/objects round-trip exactly (the YAML serializer quotes
+ * scalars that would otherwise re-type); exotic class instances serialize to
+ * their plain shape. Throws only on a structurally invalid workbook.
  */
-declare function serializeWorkbook(_workbook: Workbook): string;
+declare function serializeWorkbook(workbook: Workbook): string;
 /**
  * Strip outputs from workbook (for git)
  */
@@ -117,6 +144,24 @@ 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[];
+/**
+ * All transitive dependencies of `id` plus `id` itself (its ancestor closure).
+ * Used to run a single cell together with everything it needs. Cycle-safe via
+ * a visited set; returns `[]` if `id` is not in the graph.
+ */
+declare function getAncestors(graph: DependencyGraph, id: string): string[];
+/**
+ * Render the dependency graph as a Mermaid `graph TD` diagram.
+ *
+ * Cell ids are validated identifiers (`[A-Za-z_][A-Za-z0-9_]*`), so they are
+ * safe to use verbatim as both the node id and its quoted label — Mermaid
+ * syntax injection is impossible and no cell content appears in the output.
+ */
+declare function toMermaid(graph: DependencyGraph): string;
+/**
+ * Detect circular dependencies
+ */
+declare function detectCycles(graph: DependencyGraph): string[][];
 
 /**
  * Workbook executor
@@ -155,20 +200,56 @@ declare class WorkbookExecutor {
      * Execute a single cell
      */
     private executeCell;
+    /**
+     * Build the evaluation scope from a cell's DIRECT dependency outputs.
+     *
+     * Dependency outputs are injected as named variables keyed by the
+     * dependency's cell id, so a cell can reference an earlier cell's result by
+     * that id. Injection is non-transitive: only ids in `cell.dependsOn` are
+     * injected (a dependency's own dependencies are not). An output of
+     * `undefined` (cell never ran) is skipped, so the reference fails loudly.
+     */
+    private buildScope;
     /**
      * Execute a code cell by evaluating its content as a MathTS expression.
      *
-     * Dependency outputs are injected as named variables in the evaluation
-     * scope, so a cell can reference the result of an earlier cell by its id.
      * Evaluation goes through the MathTS expression engine — property and
      * method access route through the expression sandbox, so this does not
      * have the arbitrary-code-execution exposure of the `Function` constructor.
      */
     private executeCode;
     /**
-     * Execute a data cell — parse its content as YAML (a superset of JSON).
+     * Execute a test cell: evaluate its assertion expression in the dependency
+     * scope. The result must be a boolean — `runReport` classifies `true` as a
+     * pass and `false` as a fail. A non-boolean result is a usage error (a test
+     * that doesn't assert), surfaced via throw like any other evaluation error.
+     */
+    private executeTest;
+    /**
+     * Execute a data cell — parse its content as YAML (a superset of JSON) using
+     * the same hardened options + prototype-pollution guard as the document
+     * parser, so both YAML entry points are consistent.
      */
     private executeData;
+    /**
+     * Run every cell in dependency order and return a structured report.
+     *
+     * Unlike {@link runAll} (the event-stream API, which throws on the first cell
+     * error), `runReport` is the headless/report API: it is **continue-on-error**
+     * (one failing cell does not abort the rest) and never throws on a cell
+     * failure. A dependency cycle is refused up front. Test cells are classified
+     * as `pass`/`fail`/`error`; all other cells as `success`/`error`.
+     */
+    /**
+     * Seed the output cache (for incremental session runs): non-stale cells'
+     * outputs are provided so downstream cells can read them as scope without
+     * re-execution. Replaces any existing cached outputs.
+     */
+    seedOutputs(entries: Map<string, unknown>): void;
+    runReport(options?: {
+        only?: string;
+        runIds?: Set<string>;
+    }): Promise<RunResult>;
     /**
      * Get output from a previous cell
      */
@@ -180,10 +261,175 @@ declare class WorkbookExecutor {
 declare function createExecutor(workbook: Workbook): WorkbookExecutor;
 
 /**
- * @danielsimonjr/mathts-workbook - Scientific workbook runtime
- * @packageDocumentation
+ * Human-readable rendering of cell results for terminal output.
+ *
+ * `formatResult` is called inside the executor's continue-on-error loop, so it
+ * MUST NOT throw — circular references, BigInt, and unserializable values all
+ * fall back to safe markers rather than crashing the run.
+ */
+declare function formatResult(value: unknown): string;
+
+/**
+ * Pure, immutable cell-mutation operations on a Workbook.
+ *
+ * Every op returns a NEW workbook (the input is never mutated) and enforces the
+ * runnable-valid invariants — unique + identifier-safe ids, supported cell
+ * types, existing `depends_on` references, no self-dependency, and no dependency
+ * cycle. An op that would break an invariant throws; callers must not write the
+ * file on a throw.
  */
 
+interface CellPosition {
+    before?: string;
+    after?: string;
+    at?: number;
+}
+interface RemoveResult {
+    workbook: Workbook;
+    /** Cells whose `depends_on` was edited to detach the removed cell (force). */
+    changedCells: string[];
+}
+declare function addCell(wb: Workbook, spec: {
+    id: string;
+    type: CellType;
+    content?: string;
+    dependsOn?: string[];
+}, position?: CellPosition): Workbook;
+declare function editCell(wb: Workbook, id: string, changes: {
+    content?: string;
+    type?: CellType;
+    dependsOn?: string[];
+}): Workbook;
+declare function removeCell(wb: Workbook, id: string, options?: {
+    force?: boolean;
+}): RemoveResult;
+declare function moveCell(wb: Workbook, id: string, position: CellPosition): Workbook;
+declare function renameCell(wb: Workbook, oldId: string, newId: string): Workbook;
+/** Update workbook-level metadata fields (only the provided ones). */
+declare function setMetadata(wb: Workbook, changes: {
+    title?: string;
+    author?: string;
+    description?: string;
+    tags?: string[];
+}): Workbook;
+
+/**
+ * Machine-contract constants shared by the CLI and the public API.
+ *
+ * `SCHEMA_VERSION` is the version of the `--json` envelope shape. Clients
+ * negotiate with the rule: ignore unknown fields when `major` matches; refuse
+ * on a `major` mismatch. Additive fields bump `minor`; breaking changes bump
+ * `major`.
+ */
+declare const SCHEMA_VERSION: {
+    readonly major: 1;
+    readonly minor: 0;
+};
+/** Package/engine version reported by `--version`, `capabilities`, and serve. */
 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 };
+/**
+ * In-memory editing/execution session for a single workbook — the stateful
+ * core behind `mtsw serve`. Holds the workbook, a per-cell result cache, and a
+ * stale set so a `run` only re-executes what an edit invalidated.
+ *
+ * File I/O is limited to `open`/`save`; everything else is in-memory. Edits are
+ * not persisted until `save`.
+ */
+
+declare class Session {
+    workbook: Workbook | null;
+    path: string | null;
+    dirty: boolean;
+    private cache;
+    private stale;
+    private require;
+    /** A cell has a usable, up-to-date result (the basis for "not stale"). */
+    private hasValidResult;
+    /** Load a workbook file into the session. Refuses to discard unsaved edits. */
+    open(path: string, options?: {
+        force?: boolean;
+    }): void;
+    /** Replace the workbook and recompute the stale set by diffing old vs new. */
+    private commit;
+    addCell(spec: {
+        id: string;
+        type: CellType;
+        content?: string;
+        dependsOn?: string[];
+    }, position?: CellPosition): void;
+    editCell(id: string, changes: {
+        content?: string;
+        type?: CellType;
+        dependsOn?: string[];
+    }): void;
+    removeCell(id: string, options?: {
+        force?: boolean;
+    }): string[];
+    moveCell(id: string, position: CellPosition): void;
+    renameCell(oldId: string, newId: string): void;
+    setMetadata(changes: {
+        title?: string;
+        author?: string;
+        description?: string;
+        tags?: string[];
+    }): void;
+    /**
+     * Incremental run: execute only stale cells in the target set (`only` + its
+     * ancestors, or the whole workbook), reusing cached outputs for the rest.
+     * Returns the merged report over the target plus the streamed events.
+     */
+    run(only?: string): Promise<{
+        result: RunResult;
+        events: WorkbookEventLite[];
+    }>;
+    /** The set of cells awaiting (re-)execution. */
+    staleIds(): string[];
+    /** Serialize the current workbook and write it atomically. */
+    save(path?: string): string;
+}
+/** Slimmed event for streaming (avoids leaking timestamps / handler internals). */
+interface WorkbookEventLite {
+    type: string;
+    cellId?: string;
+    error?: string;
+}
+
+/**
+ * Pure JSON-RPC 2.0 router for `mtsw serve`. `handleRequest(session, request)`
+ * maps a request to a Session call and returns the response plus any streamed
+ * `cell/event` notifications — no stdio, so the protocol logic is unit-testable.
+ */
+
+interface JsonRpcRequest {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: string;
+    params?: Record<string, unknown>;
+}
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+interface JsonRpcEvent {
+    jsonrpc: '2.0';
+    method: 'cell/event';
+    params: {
+        type: string;
+        cellId?: string;
+        error?: string;
+    };
+}
+interface HandleResult {
+    response: JsonRpcResponse;
+    events: JsonRpcEvent[];
+    shutdown: boolean;
+}
+declare function handleRequest(session: Session, request: JsonRpcRequest): Promise<HandleResult>;
+
+export { type Cell, type CellPosition, type CellResult, type CellType, type ExecutionMode, type ParseResult, type RemoveResult, type RunResult, type RuntimeConfig, SCHEMA_VERSION, Session, VERSION, type Workbook, type WorkbookEvent, WorkbookExecutor, type WorkbookMetadata, addCell, buildDependencyGraph, createExecutor, detectCellType, detectCycles, editCell, formatResult, getAncestors, getDependents, handleRequest, moveCell, parseWorkbook, removeCell, renameCell, serializeWorkbook, setMetadata, stripOutputs, toMermaid, topologicalSort };

package/dist/index.js

@@ -1,22 +1,50 @@
 import {
+  SCHEMA_VERSION,
+  Session,
   VERSION,
   WorkbookExecutor,
+  addCell,
   buildDependencyGraph,
   createExecutor,
+  detectCellType,
+  detectCycles,
+  editCell,
+  formatResult,
+  getAncestors,
   getDependents,
+  handleRequest,
+  moveCell,
   parseWorkbook,
+  removeCell,
+  renameCell,
   serializeWorkbook,
+  setMetadata,
   stripOutputs,
+  toMermaid,
   topologicalSort
-} from "./chunk-L7UWFWMV.js";
+} from "./chunk-TS2WDJ7W.js";
 export {
+  SCHEMA_VERSION,
+  Session,
   VERSION,
   WorkbookExecutor,
+  addCell,
   buildDependencyGraph,
   createExecutor,
+  detectCellType,
+  detectCycles,
+  editCell,
+  formatResult,
+  getAncestors,
   getDependents,
+  handleRequest,
+  moveCell,
   parseWorkbook,
+  removeCell,
+  renameCell,
   serializeWorkbook,
+  setMetadata,
   stripOutputs,
+  toMermaid,
   topologicalSort
 };

package/package.json

@@ -1,62 +1,64 @@
-{
-  "name": "@danielsimonjr/mathts-workbook",
-  "version": "0.1.8",
-  "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": "^0.1.4",
-    "@danielsimonjr/mathts-functions": "^0.2.7",
-    "yaml": "^2.3.0"
-  },
-  "devDependencies": {
-    "@types/node": "^25.5.2",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^4.1.5"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/danielsimonjr/mathts",
-    "directory": "workbook"
-  },
-  "keywords": [
-    "notebook",
-    "workbook",
-    "scientific-computing",
-    "reactive",
-    "yaml"
-  ]
-}
+{
+  "name": "@danielsimonjr/mathts-workbook",
+  "version": "0.2.0",
+  "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": "^0.10.0",
+    "@danielsimonjr/mathts-expression": "^0.6.4",
+    "@danielsimonjr/mathts-functions": "^0.42.0",
+    "@danielsimonjr/mathts-plot": "^0.3.26",
+    "yaml": "^2.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/danielsimonjr/mathts",
+    "directory": "workbook"
+  },
+  "keywords": [
+    "notebook",
+    "workbook",
+    "scientific-computing",
+    "reactive",
+    "yaml"
+  ]
+}