@danielsimonjr/mathts-workbook 0.1.8 → 0.3.0

package/dist/chunk-TMVFG3I3.js

@@ -0,0 +1,581 @@
+import {
+  SUPPORTED_CELL_TYPES,
+  WorkbookExecutor,
+  buildDependencyGraph,
+  detectCycles,
+  getAncestors,
+  getDependents,
+  isValidIdentifier,
+  parseWorkbook,
+  serializeWorkbook
+} from "./chunk-3KTM2DZC.js";
+
+// src/fs-atomic.ts
+import { writeFileSync, renameSync, unlinkSync } from "fs";
+var counter = 0;
+function writeFileAtomic(file, content) {
+  const tmp = `${file}.${process.pid}.${counter++}.tmp`;
+  writeFileSync(tmp, content, { encoding: "utf-8", flag: "wx" });
+  try {
+    renameSync(tmp, file);
+  } catch (error) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+    }
+    throw error;
+  }
+}
+
+// src/edit.ts
+function cloneWorkbook(wb) {
+  return {
+    ...wb,
+    metadata: { ...wb.metadata },
+    runtime: { ...wb.runtime },
+    cells: wb.cells.map((c) => ({
+      ...c,
+      ...c.dependsOn ? { dependsOn: [...c.dependsOn] } : {},
+      ...c.metadata ? { metadata: { ...c.metadata } } : {}
+    }))
+  };
+}
+function assertSupportedType(type) {
+  if (!SUPPORTED_CELL_TYPES.includes(type)) {
+    throw new Error(`Unsupported cell type '${type}' (supported: ${SUPPORTED_CELL_TYPES.join(", ")})`);
+  }
+}
+function indexOfCell(wb, id) {
+  const i = wb.cells.findIndex((c) => c.id === id);
+  if (i < 0) throw new Error(`No such cell: '${id}'`);
+  return i;
+}
+function validateDeps(wb, dependsOn, selfId) {
+  const ids = new Set(wb.cells.map((c) => c.id));
+  for (const dep of dependsOn) {
+    if (dep === selfId) throw new Error(`Cell '${selfId}' cannot depend on itself`);
+    if (!ids.has(dep)) {
+      throw new Error(`depends_on references unknown cell '${dep}'`);
+    }
+  }
+  return dependsOn;
+}
+function assertNoNewCycle(before, after) {
+  if (detectCycles(buildDependencyGraph(before.cells)).length > 0) return;
+  const cycles = detectCycles(buildDependencyGraph(after.cells));
+  if (cycles.length > 0) {
+    throw new Error(
+      `Operation would create a dependency cycle: ${cycles.map((c) => c.join(" -> ")).join("; ")}`
+    );
+  }
+}
+function clearResult(cell) {
+  delete cell.output;
+  delete cell.error;
+}
+function resolveInsertIndex(wb, position) {
+  if (!position) return wb.cells.length;
+  if (position.at !== void 0) {
+    if (!Number.isInteger(position.at) || position.at < 0 || position.at > wb.cells.length) {
+      throw new Error(`--at ${position.at} out of range (0..${wb.cells.length})`);
+    }
+    return position.at;
+  }
+  if (position.before !== void 0) {
+    const i = wb.cells.findIndex((c) => c.id === position.before);
+    if (i < 0) throw new Error(`--before: no such cell '${position.before}'`);
+    return i;
+  }
+  if (position.after !== void 0) {
+    const i = wb.cells.findIndex((c) => c.id === position.after);
+    if (i < 0) throw new Error(`--after: no such cell '${position.after}'`);
+    return i + 1;
+  }
+  return wb.cells.length;
+}
+function addCell(wb, spec, position) {
+  if (!isValidIdentifier(spec.id)) {
+    throw new Error(`Invalid cell id '${spec.id}': must be an identifier ([A-Za-z_][A-Za-z0-9_]*)`);
+  }
+  if (wb.cells.some((c) => c.id === spec.id)) {
+    throw new Error(`Duplicate cell id '${spec.id}'`);
+  }
+  assertSupportedType(spec.type);
+  const next = cloneWorkbook(wb);
+  const cell = { id: spec.id, type: spec.type, content: spec.content ?? "" };
+  const deps = spec.dependsOn ? validateDeps(next, spec.dependsOn, spec.id) : void 0;
+  if (deps && deps.length > 0) cell.dependsOn = deps;
+  next.cells.splice(resolveInsertIndex(next, position), 0, cell);
+  assertNoNewCycle(wb, next);
+  return next;
+}
+function editCell(wb, id, changes) {
+  const next = cloneWorkbook(wb);
+  const cell = next.cells[indexOfCell(next, id)];
+  let touched = false;
+  if (changes.type !== void 0) {
+    assertSupportedType(changes.type);
+    cell.type = changes.type;
+    touched = true;
+  }
+  if (changes.content !== void 0) {
+    cell.content = changes.content;
+    touched = true;
+  }
+  if (changes.dependsOn !== void 0) {
+    const deps = validateDeps(next, changes.dependsOn, id);
+    if (deps.length > 0) cell.dependsOn = deps;
+    else delete cell.dependsOn;
+    touched = true;
+  }
+  if (touched) clearResult(cell);
+  if (changes.dependsOn !== void 0) assertNoNewCycle(wb, next);
+  return next;
+}
+function removeCell(wb, id, options) {
+  const next = cloneWorkbook(wb);
+  indexOfCell(next, id);
+  const dependents = next.cells.filter((c) => (c.dependsOn ?? []).includes(id)).map((c) => c.id);
+  if (dependents.length > 0 && !options?.force) {
+    throw new Error(`Cell '${id}' has dependents: ${dependents.join(", ")} (use --force to remove and detach)`);
+  }
+  const changedCells = [];
+  for (const c of next.cells) {
+    if (c.dependsOn?.includes(id)) {
+      c.dependsOn = c.dependsOn.filter((d) => d !== id);
+      if (c.dependsOn.length === 0) delete c.dependsOn;
+      clearResult(c);
+      changedCells.push(c.id);
+    }
+  }
+  next.cells = next.cells.filter((c) => c.id !== id);
+  return { workbook: next, changedCells };
+}
+function moveCell(wb, id, position) {
+  if (position.before === id || position.after === id) return cloneWorkbook(wb);
+  const next = cloneWorkbook(wb);
+  const from = indexOfCell(next, id);
+  const [cell] = next.cells.splice(from, 1);
+  next.cells.splice(resolveInsertIndex(next, position), 0, cell);
+  return next;
+}
+function renameCell(wb, oldId, newId) {
+  if (oldId === newId) return cloneWorkbook(wb);
+  const next = cloneWorkbook(wb);
+  const cell = next.cells[indexOfCell(next, oldId)];
+  if (!isValidIdentifier(newId)) {
+    throw new Error(`Invalid cell id '${newId}': must be an identifier ([A-Za-z_][A-Za-z0-9_]*)`);
+  }
+  if (next.cells.some((c) => c.id === newId)) {
+    throw new Error(`Duplicate cell id '${newId}'`);
+  }
+  cell.id = newId;
+  const reference = new RegExp(`\\b${oldId}\\b`, "g");
+  for (const c of next.cells) {
+    if (c.dependsOn?.includes(oldId)) {
+      c.dependsOn = c.dependsOn.map((d) => d === oldId ? newId : d);
+      c.content = c.content.replace(reference, newId);
+    }
+  }
+  return next;
+}
+function setMetadata(wb, changes) {
+  const next = cloneWorkbook(wb);
+  if (changes.title !== void 0) next.metadata.title = changes.title;
+  if (changes.author !== void 0) next.metadata.author = changes.author;
+  if (changes.description !== void 0) next.metadata.description = changes.description;
+  if (changes.tags !== void 0) next.metadata.tags = changes.tags;
+  return next;
+}
+
+// src/session.ts
+import { readFileSync } from "fs";
+function canonicalCell(cell) {
+  const meta = cell.metadata ?? {};
+  const sortedMeta = {};
+  for (const key of Object.keys(meta).sort()) sortedMeta[key] = meta[key];
+  return JSON.stringify([cell.type, cell.content, cell.dependsOn ?? [], sortedMeta]);
+}
+var Session = class {
+  workbook = null;
+  path = null;
+  dirty = false;
+  cache = /* @__PURE__ */ new Map();
+  stale = /* @__PURE__ */ new Set();
+  require() {
+    if (!this.workbook) throw new Error("No workbook open");
+    return this.workbook;
+  }
+  /** A cell has a usable, up-to-date result (the basis for "not stale"). */
+  hasValidResult(id) {
+    const r = this.cache.get(id);
+    return r !== void 0 && (r.status === "success" || r.status === "pass");
+  }
+  /** Load a workbook file into the session. Refuses to discard unsaved edits. */
+  open(path, options) {
+    if (this.dirty && !options?.force) {
+      throw new Error("Workbook has unsaved changes (open with force to discard)");
+    }
+    const content = readFileSync(path, "utf-8");
+    const parsed = parseWorkbook(content);
+    if (!parsed.success) {
+      throw new Error(`Parse errors: ${(parsed.errors ?? []).join("; ")}`);
+    }
+    this.workbook = parsed.workbook;
+    this.path = path;
+    this.cache.clear();
+    this.stale = new Set(this.workbook.cells.map((c) => c.id));
+    this.dirty = false;
+  }
+  /** Replace the workbook and recompute the stale set by diffing old vs new. */
+  commit(next) {
+    const old = this.require();
+    const oldCanonical = new Map(old.cells.map((c) => [c.id, canonicalCell(c)]));
+    const changed = /* @__PURE__ */ new Set();
+    for (const cell of next.cells) {
+      const prev = oldCanonical.get(cell.id);
+      if (prev === void 0 || prev !== canonicalCell(cell)) changed.add(cell.id);
+    }
+    const graph = buildDependencyGraph(next.cells);
+    const affected = new Set(changed);
+    for (const id of changed) {
+      for (const dep of getDependents(graph, id)) affected.add(dep);
+    }
+    const survivingIds = new Set(next.cells.map((c) => c.id));
+    for (const id of [...this.cache.keys()]) {
+      if (!survivingIds.has(id) || affected.has(id)) this.cache.delete(id);
+    }
+    this.stale = new Set(next.cells.map((c) => c.id).filter((id) => !this.hasValidResult(id)));
+    this.workbook = next;
+    this.dirty = true;
+  }
+  // --- Edits (each is atomic: the pure op throws before any state change) ---
+  addCell(spec, position) {
+    this.commit(addCell(this.require(), spec, position));
+  }
+  editCell(id, changes) {
+    this.commit(editCell(this.require(), id, changes));
+  }
+  removeCell(id, options) {
+    const result = removeCell(this.require(), id, options);
+    this.commit(result.workbook);
+    return result.changedCells;
+  }
+  moveCell(id, position) {
+    this.commit(moveCell(this.require(), id, position));
+  }
+  renameCell(oldId, newId) {
+    this.commit(renameCell(this.require(), oldId, newId));
+  }
+  setMetadata(changes) {
+    this.commit(setMetadata(this.require(), changes));
+  }
+  /**
+   * 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.
+   */
+  async run(only) {
+    const wb = this.require();
+    const graph = buildDependencyGraph(wb.cells);
+    const target = only ? new Set(getAncestors(graph, only)) : new Set(wb.cells.map((c) => c.id));
+    const toRun = new Set([...this.stale].filter((id) => target.has(id)));
+    const executor = new WorkbookExecutor(wb);
+    const seed = /* @__PURE__ */ new Map();
+    for (const [id, res] of this.cache) {
+      if (res.status === "success" || res.status === "pass") {
+        seed.set(id, res.output);
+      }
+    }
+    executor.seedOutputs(seed);
+    const events = [];
+    executor.on((e) => events.push({ type: e.type, cellId: e.cellId, error: e.error }));
+    const report = await executor.runReport({ only, runIds: toRun });
+    if (!report.ok && report.cells.some((c) => c.id === "(workbook)")) {
+      return { result: report, events };
+    }
+    for (const cr of report.cells) {
+      this.cache.set(cr.id, cr);
+      if (cr.status === "success" || cr.status === "pass") this.stale.delete(cr.id);
+    }
+    const ordered = graph.executionOrder.filter((id) => target.has(id));
+    const cells = ordered.map((id) => this.cache.get(id)).filter((c) => c !== void 0);
+    const ok = cells.every((c) => c.status === "success" || c.status === "pass");
+    return { result: { cells, ok }, events };
+  }
+  /** The set of cells awaiting (re-)execution. */
+  staleIds() {
+    return [...this.stale];
+  }
+  /** Serialize the current workbook and write it atomically. */
+  save(path) {
+    const wb = this.require();
+    const target = path ?? this.path;
+    if (!target) throw new Error("No path to save to");
+    writeFileAtomic(target, serializeWorkbook(wb));
+    this.path = target;
+    this.dirty = false;
+    return target;
+  }
+};
+
+// src/contract.ts
+var SCHEMA_VERSION = { major: 1, minor: 0 };
+var VERSION = "0.1.0";
+var COMMAND_NAMES = [
+  "run",
+  "describe",
+  "validate",
+  "graph",
+  "strip",
+  "new",
+  "capabilities",
+  "templates",
+  "cell",
+  "serve",
+  "functions",
+  "meta",
+  "import",
+  "export"
+];
+
+// src/introspect.ts
+import * as mathFunctions from "@danielsimonjr/mathts-functions";
+var functionsCache;
+function listFunctions() {
+  if (functionsCache) return functionsCache;
+  const functions = [];
+  const constants = [];
+  for (const [name, value] of Object.entries(mathFunctions)) {
+    if (typeof value === "function") functions.push(name);
+    else if (value !== null && typeof value !== "object") constants.push(name);
+  }
+  functionsCache = { functions: functions.sort(), constants: constants.sort() };
+  return functionsCache;
+}
+var CELL_SCHEMAS = {
+  code: "MathTS expression; the cell output is its evaluated value",
+  markdown: "Markdown text (rendered to HTML on export)",
+  equation: "MathTS expression syntax, rendered to MathML on export (display-only)",
+  test: "Boolean MathTS expression; true = pass, false = fail",
+  data: "A YAML/JSON literal value (e.g. a numeric array)",
+  visualization: "YAML chart spec: { type: line|scatter|bar, title?, x: {label?, data}, y: {label?, data} }; data = a dependency cell id (numeric array) or an inline array"
+};
+function capabilitiesInfo() {
+  return {
+    name: "mtsw",
+    version: VERSION,
+    schemaVersion: SCHEMA_VERSION,
+    cellTypes: {
+      supported: [...SUPPORTED_CELL_TYPES],
+      deferred: ["tensor", "export"]
+    },
+    cellSchemas: CELL_SCHEMAS,
+    commands: [...COMMAND_NAMES],
+    features: {
+      json: true,
+      write: true,
+      runCell: true,
+      editCell: true,
+      serve: true,
+      incremental: true,
+      functions: true,
+      import: true,
+      export: true
+    }
+  };
+}
+
+// src/doc.ts
+function describeData(wb) {
+  const cells = (wb?.cells ?? []).map((c) => ({
+    id: c.id,
+    type: c.type,
+    content: c.content,
+    dependsOn: c.dependsOn ?? [],
+    metadata: c.metadata ?? {},
+    output: c.output ?? null,
+    error: c.error ?? null
+  }));
+  const graph = wb ? buildDependencyGraph(wb.cells) : void 0;
+  const edges = graph ? [...graph.nodes].flatMap(([id, node]) => node.dependencies.map((dep) => ({ from: dep, to: id }))) : [];
+  const cycles = graph ? detectCycles(graph) : [];
+  return {
+    version: wb?.version ?? "1.0",
+    metadata: wb?.metadata ?? {},
+    runtime: wb?.runtime ?? { engine: "mathts", execution: "reactive" },
+    cells,
+    graph: { edges, cycles }
+  };
+}
+
+// src/rpc.ts
+var CODE = {
+  PARSE: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL: -32603
+};
+function str(value) {
+  return typeof value === "string" ? value : void 0;
+}
+async function handleRequest(session, request) {
+  const id = request && request.id !== void 0 ? request.id : null;
+  const ok = (result, events = [], shutdown = false) => ({
+    response: { jsonrpc: "2.0", id, result },
+    events,
+    shutdown
+  });
+  const fail = (code, message) => ({
+    response: { jsonrpc: "2.0", id, error: { code, message } },
+    events: [],
+    shutdown: false
+  });
+  if (!request || typeof request.method !== "string") {
+    return fail(CODE.INVALID_REQUEST, "Invalid request: missing method");
+  }
+  const p = request.params ?? {};
+  const doc = () => describeData(session.workbook ?? void 0);
+  try {
+    switch (request.method) {
+      case "open": {
+        const path = str(p.path);
+        if (path === void 0) return fail(CODE.INVALID_PARAMS, "open requires params.path");
+        session.open(path, { force: p.force === true });
+        return ok({ path: session.path, ...doc() });
+      }
+      case "describe":
+        return ok(doc());
+      case "validate": {
+        const d = doc();
+        const problems = d.graph.cycles.map((c) => `Dependency cycle: ${c.join(" -> ")}`);
+        return ok({ ok: problems.length === 0, problems, cellCount: d.cells.length });
+      }
+      case "graph":
+        return ok(doc().graph);
+      case "run": {
+        const { result, events } = await session.run(str(p.only));
+        const evts = events.map((e) => ({
+          jsonrpc: "2.0",
+          method: "cell/event",
+          params: { type: e.type, cellId: e.cellId, error: e.error }
+        }));
+        return ok(result, evts);
+      }
+      case "cell/add":
+        session.addCell(
+          {
+            id: str(p.id) ?? "",
+            type: str(p.type) ?? "",
+            content: str(p.content),
+            dependsOn: Array.isArray(p.dependsOn) ? p.dependsOn : void 0
+          },
+          p.position
+        );
+        return ok(doc());
+      case "cell/edit":
+        session.editCell(str(p.id) ?? "", {
+          content: str(p.content),
+          type: str(p.type),
+          dependsOn: Array.isArray(p.dependsOn) ? p.dependsOn : void 0
+        });
+        return ok(doc());
+      case "cell/rm": {
+        const changedCells = session.removeCell(str(p.id) ?? "", { force: p.force === true });
+        return ok({ changedCells, ...doc() });
+      }
+      case "cell/move":
+        session.moveCell(str(p.id) ?? "", p.position ?? {});
+        return ok(doc());
+      case "cell/rename":
+        session.renameCell(str(p.oldId) ?? "", str(p.newId) ?? "");
+        return ok(doc());
+      case "meta/get":
+        return ok(session.workbook?.metadata ?? {});
+      case "meta/set":
+        session.setMetadata({
+          title: str(p.title),
+          author: str(p.author),
+          description: str(p.description),
+          tags: Array.isArray(p.tags) ? p.tags : void 0
+        });
+        return ok(session.workbook?.metadata ?? {});
+      case "save":
+        return ok({ path: session.save(str(p.path)) });
+      case "capabilities":
+        return ok(capabilitiesInfo());
+      case "functions":
+        return ok(listFunctions());
+      case "shutdown":
+        return ok({ ok: true }, [], true);
+      default:
+        return fail(CODE.METHOD_NOT_FOUND, `Method not found: ${request.method}`);
+    }
+  } catch (error) {
+    return fail(CODE.INTERNAL, error instanceof Error ? error.message : String(error));
+  }
+}
+
+// src/timeout-runner.ts
+import { Worker } from "worker_threads";
+var WorkbookTimeoutError = class extends Error {
+  timeoutMs;
+  constructor(timeoutMs) {
+    super(`workbook execution exceeded ${timeoutMs}ms and was terminated`);
+    this.name = "WorkbookTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+function runWorkbookWithTimeout(source, options) {
+  const { timeoutMs } = options;
+  const workerUrl = new URL("./run-worker.js", import.meta.url);
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(workerUrl, { workerData: { source } });
+    let settled = false;
+    const finish = (fn) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      void worker.terminate().catch(() => {
+      });
+      fn();
+    };
+    const timer = setTimeout(() => {
+      finish(() => reject(new WorkbookTimeoutError(timeoutMs)));
+    }, timeoutMs);
+    worker.once("message", (msg) => {
+      finish(() => {
+        if (msg.ok) resolve(msg.report);
+        else reject(new Error(msg.error));
+      });
+    });
+    worker.once("error", (error) => {
+      finish(() => reject(error));
+    });
+    worker.once("exit", (code) => {
+      finish(
+        () => reject(new Error(`workbook worker exited with code ${code} before returning a result`))
+      );
+    });
+  });
+}
+
+export {
+  writeFileAtomic,
+  addCell,
+  editCell,
+  removeCell,
+  moveCell,
+  renameCell,
+  setMetadata,
+  Session,
+  SCHEMA_VERSION,
+  VERSION,
+  listFunctions,
+  capabilitiesInfo,
+  describeData,
+  handleRequest,
+  WorkbookTimeoutError,
+  runWorkbookWithTimeout
+};

package/dist/cli.d.ts

@@ -1 +1,40 @@
 #!/usr/bin/env node
+/**
+ * MathTS Workbook CLI
+ *
+ * Command handlers are pure functions returning `{ stdout, stderr, exitCode }`
+ * (no direct console / process.exit) so they can be unit-tested. The thin
+ * `main()` at the bottom wires them to the real streams, and only runs when
+ * this file is the process entry point.
+ */
+interface CommandResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+declare function runCommand(args: string[]): Promise<CommandResult>;
+declare function validateCommand(args: string[]): CommandResult;
+declare function describeCommand(args: string[]): CommandResult;
+declare function capabilitiesCommand(args: string[]): CommandResult;
+declare function templatesCommand(args: string[]): CommandResult;
+declare function functionsCommand(args: string[]): CommandResult;
+declare function metaCommand(args: string[]): CommandResult;
+declare function exportCommand(args: string[]): Promise<CommandResult>;
+/**
+ * Run the JSON-RPC-over-stdio server loop until `shutdown`, stdin EOF, or a
+ * termination signal. NDJSON via readline (chunked-input / CRLF safe). Events
+ * for a run are flushed before that run's response (not mid-run in v1).
+ */
+declare function runServer(input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Promise<void>;
+declare function serveCommand(): Promise<CommandResult>;
+declare function graphCommand(args: string[]): CommandResult;
+declare function stripCommand(args: string[]): CommandResult;
+declare function newCommand(args: string[]): CommandResult;
+declare function importCommand(args: string[]): CommandResult;
+declare function cellCommand(args: string[]): CommandResult;
+/**
+ * Route argv to a command handler. Pure — returns a CommandResult.
+ */
+declare function dispatch(argv: string[]): Promise<CommandResult>;
+
+export { type CommandResult, capabilitiesCommand, cellCommand, describeCommand, dispatch, exportCommand, functionsCommand, graphCommand, importCommand, metaCommand, newCommand, runCommand, runServer, serveCommand, stripCommand, templatesCommand, validateCommand };