@danielsimonjr/mathts-workbook 0.2.0 → 0.3.0

package/dist/cli.js

@@ -4,28 +4,31 @@ import {
   Session,
   VERSION,
   addCell,
-  buildDependencyGraph,
   capabilitiesInfo,
-  createExecutor,
   describeData,
-  detectCycles,
   editCell,
-  formatResult,
   handleRequest,
-  importWorkbook,
   listFunctions,
   moveCell,
-  parseWorkbook,
-  parseYamlHardened,
   removeCell,
   renameCell,
-  serializeWorkbook,
+  runWorkbookWithTimeout,
   setMetadata,
+  writeFileAtomic
+} from "./chunk-TMVFG3I3.js";
+import {
+  buildDependencyGraph,
+  createExecutor,
+  detectCycles,
+  formatResult,
+  importWorkbook,
+  parseWorkbook,
+  parseYamlHardened,
+  serializeWorkbook,
   stripOutputs,
   toDOT,
-  toMermaid,
-  writeFileAtomic
-} from "./chunk-TS2WDJ7W.js";
+  toMermaid
+} from "./chunk-3KTM2DZC.js";
 
 // src/cli.ts
 import { readFileSync, writeFileSync, lstatSync, realpathSync } from "fs";
@@ -463,6 +466,85 @@ function toPDF(doc, outPath, options = {}) {
   return latexToPdf(toTeX(doc, { parse: parse3, fragment: false }), outPath, renderOpts);
 }
 
+// src/ipynb.ts
+function toSourceLines(content) {
+  if (content === "") return [];
+  const lines = content.split("\n");
+  return lines.map((line2, i) => i < lines.length - 1 ? `${line2}
+` : line2);
+}
+function textData(text) {
+  return { "text/plain": toSourceLines(text) };
+}
+function renderCodeCell(cell, counter) {
+  const outputs = [];
+  let executionCount = null;
+  if (cell.error !== void 0) {
+    outputs.push({
+      output_type: "error",
+      ename: "Error",
+      evalue: cell.error,
+      traceback: [cell.error]
+    });
+  } else if (cell.type === "chart") {
+    if (cell.chartSvg !== void 0) {
+      outputs.push({
+        output_type: "display_data",
+        data: { "image/svg+xml": toSourceLines(cell.chartSvg), "text/plain": ["<chart>"] },
+        metadata: {}
+      });
+    }
+  } else if (cell.type === "test" && cell.passed !== void 0) {
+    executionCount = counter.n++;
+    outputs.push({
+      output_type: "execute_result",
+      data: textData(cell.passed ? "true" : "false"),
+      metadata: {},
+      execution_count: executionCount
+    });
+  } else if (cell.output !== void 0) {
+    executionCount = counter.n++;
+    outputs.push({
+      output_type: "execute_result",
+      data: textData(cell.output),
+      metadata: {},
+      execution_count: executionCount
+    });
+  }
+  return {
+    cell_type: "code",
+    source: toSourceLines(cell.content),
+    metadata: {},
+    execution_count: executionCount,
+    outputs
+  };
+}
+function renderIpynbCell(cell, counter) {
+  if (cell.type === "markdown") {
+    return { cell_type: "markdown", source: toSourceLines(cell.content), metadata: {} };
+  }
+  return renderCodeCell(cell, counter);
+}
+function toIpynb(doc) {
+  const counter = { n: 1 };
+  const cells = doc.cells.map((cell) => renderIpynbCell(cell, counter));
+  const mathts = {};
+  if (doc.title !== void 0) mathts.title = doc.title;
+  if (doc.author !== void 0) mathts.author = doc.author;
+  if (doc.description !== void 0) mathts.description = doc.description;
+  if (doc.tags !== void 0) mathts.tags = doc.tags;
+  const notebook = {
+    nbformat: 4,
+    nbformat_minor: 5,
+    metadata: {
+      mathts,
+      language_info: { name: "mathts", file_extension: ".mtsw" }
+    },
+    cells
+  };
+  return JSON.stringify(notebook, null, 2);
+}
+
 // src/svg.ts
 import { line, scatter, bar } from "@danielsimonjr/mathts-plot";
 function coerce(v) {
@@ -511,11 +593,15 @@ var HELP = `
 mtsw - MathTS Workbook CLI
 
 Usage:
-  mtsw run <file> [-c <id>] [-v] [--json] [--write]
+  mtsw run <file> [-c <id>] [-v] [--json] [--write] [--timeout <ms>]
                                             Execute a workbook (or one cell + its
                                             deps with -c/--cell). -v: events,
                                             --json: machine output, --write: persist
-                                            outputs back to the file.
+                                            outputs back to the file. --timeout runs
+                                            the whole workbook in a worker thread and
+                                            kills it (WorkbookTimeoutError) if it
+                                            exceeds the budget \u2014 a runaway cell can't
+                                            hang the process. Incompatible with -c/-v.
   mtsw describe <file> [--json]             Structured document model (cells, graph)
   mtsw validate <file> [--json]             Validate structure (ids, deps, cycles)
   mtsw graph <file> [-f mermaid|dot]        Print the dependency graph
@@ -539,10 +625,12 @@ Usage:
   mtsw functions [--json]                    List functions/constants cells can call
   mtsw meta get <file> [--json]             Show workbook metadata
   mtsw meta set <file> [--title s] [--author s] [--description s] [--tags a,b]
-  mtsw export <file> [--format html|tex|json] [--fragment] [-o out] [--no-run]
+  mtsw export <file> [--format html|tex|json|pdf|ipynb] [--fragment] [-o out] [--no-run]
                                             Render to a self-contained HTML or LaTeX
                                             document (MathML/TikZ equations + charts,
-                                            no external deps), or emit the executed
+                                            no external deps), a Jupyter notebook
+                                            (nbformat v4, default extension .ipynb), a
+                                            PDF (requires -o), or emit the executed
                                             run report as JSON. --fragment (tex only)
                                             omits the preamble for \\input; --no-run is
                                             incompatible with --format json.
@@ -584,6 +672,7 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "--template",
   "-c",
   "--cell",
+  "--timeout",
   "--id",
   "--content",
   "--content-file",
@@ -714,13 +803,32 @@ ${bullets(problems2)}`,
       exitCode: 1
     };
   }
+  const timeoutStr = flagValue(args, "--timeout");
   const verbose = args.includes("-v") || args.includes("--verbose");
-  const executor = createExecutor(parsed.workbook);
+  let report;
   const events = [];
-  if (verbose) {
-    executor.on((event) => events.push(`[${event.type}] ${event.cellId ?? ""}`.trimEnd()));
+  if (timeoutStr !== void 0) {
+    const timeoutMs = Number(timeoutStr);
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      return fail([`--timeout must be a positive number of milliseconds (got '${timeoutStr}')`]);
+    }
+    if (cellId !== void 0 || verbose) {
+      return fail([
+        "--timeout does not support -c/--cell or -v/--verbose (it runs the whole workbook, in a worker, to completion or termination)"
+      ]);
+    }
+    try {
+      report = await runWorkbookWithTimeout(read.content, { timeoutMs });
+    } catch (error) {
+      return fail([error instanceof Error ? error.message : String(error)], { cells: [] });
+    }
+  } else {
+    const executor = createExecutor(parsed.workbook);
+    if (verbose) {
+      executor.on((event) => events.push(`[${event.type}] ${event.cellId ?? ""}`.trimEnd()));
+    }
+    report = await executor.runReport(cellId !== void 0 ? { only: cellId } : {});
   }
-  const report = await executor.runReport(cellId !== void 0 ? { only: cellId } : {});
   const problems = report.ok ? [] : failureList(report.cells);
   const humanFailures = report.ok ? "" : failureSummary(report.cells);
   if (args.includes("--write")) {
@@ -1033,13 +1141,13 @@ async function exportCommand(args) {
   const json = args.includes("--json");
   const fail = (problems) => json ? { stdout: jsonEnvelope("export", false, null, problems), stderr: "", exitCode: 1 } : { stdout: "", stderr: problems.join("\n"), exitCode: 1 };
   const format = flagValue(args, "--format") ?? "html";
-  if (format !== "html" && format !== "tex" && format !== "json" && format !== "pdf") {
-    return fail([`Unknown format '${format}' (supported: html, tex, json, pdf)`]);
+  if (format !== "html" && format !== "tex" && format !== "json" && format !== "pdf" && format !== "ipynb") {
+    return fail([`Unknown format '${format}' (supported: html, tex, json, pdf, ipynb)`]);
   }
   const file = firstPositional(args);
   if (!file)
     return fail([
-      "Usage: mtsw export <file> [--format html|tex|json|pdf] [--fragment] [-o out] [--no-run]"
+      "Usage: mtsw export <file> [--format html|tex|json|pdf|ipynb] [--fragment] [-o out] [--no-run]"
     ]);
   const read = readFile(file);
   if (read.error) return fail([read.error]);
@@ -1106,7 +1214,7 @@ async function exportCommand(args) {
     return json ? { stdout: jsonEnvelope("export", true, { path: outPath2 }, []), stderr: "", exitCode: 0 } : { stdout: "", stderr: `Exported ${file} -> ${outPath2}`, exitCode: 0 };
   }
   const fragment = args.includes("--fragment");
-  const rendered = format === "tex" ? toTeX(buildRenderDoc(workbook, byId, "tikz"), { parse: parse2, fragment }) : toHTML(buildRenderDoc(workbook, byId), { parse: parse2 });
+  const rendered = format === "tex" ? toTeX(buildRenderDoc(workbook, byId, "tikz"), { parse: parse2, fragment }) : format === "ipynb" ? toIpynb(buildRenderDoc(workbook, byId)) : toHTML(buildRenderDoc(workbook, byId), { parse: parse2 });
   const bytes = Buffer.byteLength(rendered, "utf-8");
   const outPath = flagValue(args, "-o") ?? flagValue(args, "--output");
   if (outPath) {

package/dist/index.d.ts

@@ -432,4 +432,53 @@ interface HandleResult {
 }
 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 };
+/**
+ * Shared message/result shapes between `timeout-runner.ts` (the coordinator,
+ * running on the caller's thread) and `run-worker.ts` (the `worker_threads`
+ * entry point that actually executes the workbook). Kept in its own module so
+ * neither side needs to import the other's runtime code — the worker script
+ * stays a minimal, independently loadable entry point.
+ *
+ * Cell outputs are pre-formatted to strings (via `formatResult`) before they
+ * cross the worker boundary: `postMessage` uses the structured-clone
+ * algorithm, which cannot faithfully reproduce engine class instances
+ * (Complex, matrices, BigNumber, …) — it either drops their prototype or
+ * throws. Formatting to a string in the worker (the same rendering every
+ * other report consumer already uses) sidesteps that entirely.
+ */
+
+/** A `CellResult` with its output pre-formatted to a string (or absent). */
+interface SerializedCellResult {
+    id: string;
+    type: CellResult['type'];
+    status: CellResult['status'];
+    output?: string;
+    error?: string;
+}
+/** A `RunResult` whose cells are `SerializedCellResult`s. */
+interface SerializedRunResult {
+    cells: SerializedCellResult[];
+    ok: boolean;
+}
+
+interface RunWorkbookWithTimeoutOptions {
+    /** Wall-clock budget in milliseconds. Exceeding it terminates the worker. */
+    timeoutMs: number;
+}
+/** Thrown when a workbook run is terminated for exceeding its time budget. */
+declare class WorkbookTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Run a workbook's `.mtsw` source to completion (a continue-on-error report,
+ * like `runReport()`) inside a worker thread, killing that worker if it
+ * exceeds `timeoutMs`. The worker is ALWAYS terminated before this promise
+ * settles — on timeout, on success, and on error — so no handle is left open
+ * keeping the process alive.
+ *
+ * @throws {WorkbookTimeoutError} if the run is terminated for exceeding the budget.
+ */
+declare function runWorkbookWithTimeout(source: string, options: RunWorkbookWithTimeoutOptions): Promise<SerializedRunResult>;
+
+export { type Cell, type CellPosition, type CellResult, type CellType, type ExecutionMode, type ParseResult, type RemoveResult, type RunResult, type RunWorkbookWithTimeoutOptions, type RuntimeConfig, SCHEMA_VERSION, type SerializedCellResult, type SerializedRunResult, Session, VERSION, type Workbook, type WorkbookEvent, WorkbookExecutor, type WorkbookMetadata, WorkbookTimeoutError, addCell, buildDependencyGraph, createExecutor, detectCellType, detectCycles, editCell, formatResult, getAncestors, getDependents, handleRequest, moveCell, parseWorkbook, removeCell, renameCell, runWorkbookWithTimeout, serializeWorkbook, setMetadata, stripOutputs, toMermaid, topologicalSort };

package/dist/index.js

@@ -2,32 +2,37 @@ import {
   SCHEMA_VERSION,
   Session,
   VERSION,
-  WorkbookExecutor,
+  WorkbookTimeoutError,
   addCell,
+  editCell,
+  handleRequest,
+  moveCell,
+  removeCell,
+  renameCell,
+  runWorkbookWithTimeout,
+  setMetadata
+} from "./chunk-TMVFG3I3.js";
+import {
+  WorkbookExecutor,
   buildDependencyGraph,
   createExecutor,
   detectCellType,
   detectCycles,
-  editCell,
   formatResult,
   getAncestors,
   getDependents,
-  handleRequest,
-  moveCell,
   parseWorkbook,
-  removeCell,
-  renameCell,
   serializeWorkbook,
-  setMetadata,
   stripOutputs,
   toMermaid,
   topologicalSort
-} from "./chunk-TS2WDJ7W.js";
+} from "./chunk-3KTM2DZC.js";
 export {
   SCHEMA_VERSION,
   Session,
   VERSION,
   WorkbookExecutor,
+  WorkbookTimeoutError,
   addCell,
   buildDependencyGraph,
   createExecutor,
@@ -42,6 +47,7 @@ export {
   parseWorkbook,
   removeCell,
   renameCell,
+  runWorkbookWithTimeout,
   serializeWorkbook,
   setMetadata,
   stripOutputs,

package/dist/run-worker.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/run-worker.js

@@ -0,0 +1,39 @@
+import {
+  createExecutor,
+  formatResult,
+  parseWorkbook
+} from "./chunk-3KTM2DZC.js";
+
+// src/run-worker.ts
+import { parentPort, workerData } from "worker_threads";
+async function main() {
+  const port = parentPort;
+  if (!port) {
+    throw new Error("run-worker.js must be run as a worker_threads Worker");
+  }
+  let message;
+  try {
+    const { source } = workerData;
+    const parsed = parseWorkbook(source);
+    if (!parsed.success || !parsed.workbook) {
+      message = {
+        ok: false,
+        error: `Parse error: ${(parsed.errors ?? []).join("; ") || "invalid workbook"}`
+      };
+    } else {
+      const report = await createExecutor(parsed.workbook).runReport();
+      const cells = report.cells.map((c) => ({
+        id: c.id,
+        type: c.type,
+        status: c.status,
+        output: c.output === void 0 ? void 0 : formatResult(c.output),
+        error: c.error
+      }));
+      message = { ok: true, report: { ok: report.ok, cells } };
+    }
+  } catch (error) {
+    message = { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+  port.postMessage(message);
+}
+void main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielsimonjr/mathts-workbook",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Scientific workbook runtime for MathTS (.mtsw format)",
   "author": "Daniel Simon Jr.",
   "license": "MIT",
@@ -22,8 +22,8 @@
     "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",
+    "build": "tsup src/index.ts src/cli.ts src/run-worker.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/cli.ts src/run-worker.ts --format esm --dts --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -31,7 +31,7 @@
     "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"
+    "build:prod": "tsup src/index.ts src/cli.ts src/run-worker.ts --format esm --dts --clean --minify --treeshake"
   },
   "dependencies": {
     "@danielsimonjr/mathts-core": "^0.10.0",