@danielsimonjr/mathts-workbook 0.1.7 → 0.2.0

package/dist/cli.js

@@ -1,107 +1,1678 @@
 #!/usr/bin/env node
 import {
+  SCHEMA_VERSION,
+  Session,
+  VERSION,
+  addCell,
+  buildDependencyGraph,
+  capabilitiesInfo,
   createExecutor,
-  parseWorkbook
-} from "./chunk-L7UWFWMV.js";
+  describeData,
+  detectCycles,
+  editCell,
+  formatResult,
+  handleRequest,
+  importWorkbook,
+  listFunctions,
+  moveCell,
+  parseWorkbook,
+  parseYamlHardened,
+  removeCell,
+  renameCell,
+  serializeWorkbook,
+  setMetadata,
+  stripOutputs,
+  toDOT,
+  toMermaid,
+  writeFileAtomic
+} from "./chunk-TS2WDJ7W.js";
 
 // src/cli.ts
+import { readFileSync, writeFileSync, lstatSync, realpathSync } from "fs";
+import { pathToFileURL } from "url";
+import { basename } from "path";
+import { createInterface } from "readline";
+import * as mathFunctions from "@danielsimonjr/mathts-functions";
+
+// src/html.ts
+import { mathMLDocument, mathMLError } from "@danielsimonjr/mathts-expression";
+
+// src/markdown.ts
+function esc(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function sanitizeHrefRaw(href) {
+  const h = href.trim();
+  let probe = h.replace(/&amp;/g, "&");
+  try {
+    probe = decodeURIComponent(probe);
+  } catch {
+  }
+  probe = probe.trim().toLowerCase();
+  if (probe.startsWith("//")) return null;
+  if (probe.startsWith("http://") || probe.startsWith("https://") || probe.startsWith("mailto:"))
+    return h;
+  if (probe.startsWith("/") || probe.startsWith("./") || probe.startsWith("../") || probe.startsWith("#"))
+    return h;
+  if (/^[a-z][a-z0-9+.-]*:/.test(probe)) return null;
+  return null;
+}
+function sanitizeHref(href) {
+  const raw = sanitizeHrefRaw(href);
+  return raw === null ? null : raw.replace(/"/g, "&quot;");
+}
+function inline(escaped) {
+  let s = escaped.replace(/`([^`]+)`/g, (_m, code) => `<code>${code}</code>`);
+  s = s.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+  s = s.replace(/\*([^*]+)\*/g, "<em>$1</em>");
+  s = s.replace(/\[([^\]]*)\]\(([^)\s]+)\)/g, (_m, text, href) => {
+    const safe = sanitizeHref(href);
+    return safe ? `<a href="${safe}">${text}</a>` : text;
+  });
+  return s;
+}
+var HR = /^ {0,3}(-{3,}|\*{3,}|_{3,})\s*$/;
+var HEADING = /^(#{1,6})\s+(.*)$/;
+var UL = /^\s*[-*+]\s+/;
+var OL = /^\s*\d+\.\s+/;
+function isBlockStart(line2) {
+  return line2.trim() === "" || /^```/.test(line2.trim()) || HEADING.test(line2) || UL.test(line2) || OL.test(line2) || HR.test(line2);
+}
+function markdownToHtml(src) {
+  if (!src) return "";
+  const lines = src.replace(/\r\n?/g, "\n").split("\n");
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line2 = lines[i];
+    if (/^```/.test(line2.trim())) {
+      const buf = [];
+      i++;
+      while (i < lines.length && !/^```/.test(lines[i].trim())) {
+        buf.push(lines[i]);
+        i++;
+      }
+      i++;
+      out.push(`<pre><code>${esc(buf.join("\n"))}</code></pre>`);
+      continue;
+    }
+    if (line2.trim() === "") {
+      i++;
+      continue;
+    }
+    if (HR.test(line2)) {
+      out.push("<hr>");
+      i++;
+      continue;
+    }
+    const h = HEADING.exec(line2);
+    if (h) {
+      const lvl = h[1].length;
+      out.push(`<h${lvl}>${inline(esc(h[2].trim()))}</h${lvl}>`);
+      i++;
+      continue;
+    }
+    if (UL.test(line2)) {
+      const items = [];
+      while (i < lines.length && UL.test(lines[i])) {
+        items.push(`<li>${inline(esc(lines[i].replace(UL, "")))}</li>`);
+        i++;
+      }
+      out.push(`<ul>${items.join("")}</ul>`);
+      continue;
+    }
+    if (OL.test(line2)) {
+      const items = [];
+      while (i < lines.length && OL.test(lines[i])) {
+        items.push(`<li>${inline(esc(lines[i].replace(OL, "")))}</li>`);
+        i++;
+      }
+      out.push(`<ol>${items.join("")}</ol>`);
+      continue;
+    }
+    const para = [];
+    while (i < lines.length && !isBlockStart(lines[i])) {
+      para.push(lines[i]);
+      i++;
+    }
+    out.push(`<p>${inline(esc(para.join(" ")))}</p>`);
+  }
+  return out.join("\n");
+}
+function texEscape(s) {
+  return s.replace(/[\\&%$#_{}~^]/g, (c) => {
+    switch (c) {
+      case "\\":
+        return "\\textbackslash{}";
+      case "~":
+        return "\\textasciitilde{}";
+      case "^":
+        return "\\textasciicircum{}";
+      default:
+        return `\\${c}`;
+    }
+  });
+}
+function escapeInlineNonLink(text) {
+  let s = texEscape(text);
+  s = s.replace(/`([^`]+)`/g, (_m, code) => `\\texttt{${code}}`);
+  s = s.replace(/\*\*([^*]+)\*\*/g, "\\textbf{$1}");
+  s = s.replace(/\*([^*]+)\*/g, "\\emph{$1}");
+  return s;
+}
+function inlineTex(text) {
+  const linkRe = /\[([^\]]*)\]\(([^)\s]+)\)/g;
+  let out = "";
+  let last = 0;
+  let m;
+  while ((m = linkRe.exec(text)) !== null) {
+    out += escapeInlineNonLink(text.slice(last, m.index));
+    const raw = sanitizeHrefRaw(m[2]);
+    out += raw ? `\\href{${texEscape(raw)}}{${escapeInlineNonLink(m[1])}}` : escapeInlineNonLink(m[1]);
+    last = linkRe.lastIndex;
+  }
+  out += escapeInlineNonLink(text.slice(last));
+  return out;
+}
+function markdownToTex(src) {
+  if (!src) return "";
+  const lines = src.replace(/\r\n?/g, "\n").split("\n");
+  const out = [];
+  let i = 0;
+  const SEC = ["\\section*", "\\subsection*", "\\subsubsection*", "\\paragraph"];
+  while (i < lines.length) {
+    const line2 = lines[i];
+    if (/^```/.test(line2.trim())) {
+      const buf = [];
+      i++;
+      while (i < lines.length && !/^```/.test(lines[i].trim())) {
+        buf.push(lines[i]);
+        i++;
+      }
+      i++;
+      out.push(`\\begin{lstlisting}
+${buf.join("\n")}
+\\end{lstlisting}`);
+      continue;
+    }
+    if (line2.trim() === "") {
+      i++;
+      continue;
+    }
+    if (HR.test(line2)) {
+      out.push("\\par\\noindent\\rule{\\linewidth}{0.4pt}\\par");
+      i++;
+      continue;
+    }
+    const h = HEADING.exec(line2);
+    if (h) {
+      const lvl = Math.min(h[1].length, 4);
+      out.push(`${SEC[lvl - 1]}{${inlineTex(h[2].trim())}}`);
+      i++;
+      continue;
+    }
+    if (UL.test(line2)) {
+      const items = [];
+      while (i < lines.length && UL.test(lines[i])) {
+        items.push(`  \\item ${inlineTex(lines[i].replace(UL, ""))}`);
+        i++;
+      }
+      out.push(`\\begin{itemize}
+${items.join("\n")}
+\\end{itemize}`);
+      continue;
+    }
+    if (OL.test(line2)) {
+      const items = [];
+      while (i < lines.length && OL.test(lines[i])) {
+        items.push(`  \\item ${inlineTex(lines[i].replace(OL, ""))}`);
+        i++;
+      }
+      out.push(`\\begin{enumerate}
+${items.join("\n")}
+\\end{enumerate}`);
+      continue;
+    }
+    const para = [];
+    while (i < lines.length && !isBlockStart(lines[i])) {
+      para.push(lines[i]);
+      i++;
+    }
+    out.push(inlineTex(para.join(" ")));
+  }
+  return out.join("\n\n");
+}
+
+// src/html.ts
+function esc2(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function renderEquation(content, parse3) {
+  let math;
+  if (!parse3) {
+    math = mathMLError(content);
+  } else {
+    try {
+      math = mathMLDocument(parse3(content));
+    } catch {
+      math = mathMLError(content);
+    }
+  }
+  return `<figure class="cell cell-eq">${math}</figure>`;
+}
+function renderCell(cell, parse3) {
+  const cap = cell.id ? `<figcaption>${esc2(cell.id)}</figcaption>` : "";
+  switch (cell.type) {
+    case "markdown":
+      return `<section class="cell cell-md">${markdownToHtml(cell.content)}</section>`;
+    case "equation":
+      return renderEquation(cell.content, parse3);
+    case "code": {
+      const src = `<pre class="src"><code>${esc2(cell.content)}</code></pre>`;
+      let res = "";
+      if (cell.error !== void 0) res = `<div class="cell-error">${esc2(cell.error)}</div>`;
+      else if (cell.output !== void 0)
+        res = `<div class="cell-output">${esc2(cell.output)}</div>`;
+      return `<figure class="cell cell-code">${cap}${src}${res}</figure>`;
+    }
+    case "test": {
+      const err = cell.error;
+      let badge;
+      let cls;
+      if (err !== void 0) {
+        badge = "\u26A0";
+        cls = "err";
+      } else if (cell.passed === true) {
+        badge = "\u2713";
+        cls = "pass";
+      } else if (cell.passed === false) {
+        badge = "\u2717";
+        cls = "fail";
+      } else {
+        badge = "\u25CB";
+        cls = "nrun";
+      }
+      const note = err !== void 0 ? ` <span class="note">${esc2(err)}</span>` : "";
+      return `<figure class="cell cell-test ${cls}"><span class="badge">${badge}</span> <code>${esc2(cell.content)}</code>${note}</figure>`;
+    }
+    case "data": {
+      const val = cell.error !== void 0 ? esc2(cell.error) : esc2(cell.output ?? "");
+      return `<figure class="cell cell-data">${cap}<pre><code>${val}</code></pre></figure>`;
+    }
+    case "chart": {
+      const note = cell.note ? `<p class="note">\u26A0 ${esc2(cell.note)}</p>` : "";
+      return `<figure class="cell cell-chart">${cap}${cell.chartSvg ?? '<p class="note">no chart</p>'}${note}</figure>`;
+    }
+    default:
+      return `<figure class="cell"><pre><code>${esc2(cell.content)}</code></pre></figure>`;
+  }
+}
+function toCSS() {
+  return [
+    ":root{--fg:#1a1a2e;--muted:#5a5a72;--bg:#fff;--code-bg:#f4f4f8;--border:#e0e0ea;--accent:#2a4d8f;--pass:#1a7f37;--fail:#cf222e;}",
+    "*{box-sizing:border-box}",
+    "body{margin:0;color:var(--fg);background:var(--bg);font:16px/1.6 system-ui,-apple-system,Segoe UI,Roboto,sans-serif}",
+    "main{max-width:48rem;margin:0 auto;padding:2rem 1.25rem}",
+    "header{border-bottom:2px solid var(--border);margin-bottom:1.5rem;padding-bottom:1rem}",
+    ".doc-title{margin:0 0 .25rem;font-size:1.9rem}",
+    ".doc-meta,.doc-desc{color:var(--muted);margin:.15rem 0}",
+    ".tag{display:inline-block;background:var(--code-bg);border:1px solid var(--border);border-radius:1rem;padding:.05rem .55rem;font-size:.8rem;margin-right:.3rem}",
+    ".cell{margin:1.1rem 0}",
+    "h1,h2,h3,h4{line-height:1.25}",
+    "code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}",
+    "pre{background:var(--code-bg);border:1px solid var(--border);border-radius:6px;padding:.7rem .9rem;overflow:auto}",
+    ".cell-code{border-left:3px solid var(--accent);padding-left:.9rem}",
+    ".cell-code figcaption{color:var(--muted);font-size:.8rem;font-family:ui-monospace,monospace;margin-bottom:.2rem}",
+    ".cell-output{background:#fafaff;border:1px solid var(--border);border-radius:6px;padding:.5rem .9rem;margin-top:.4rem;white-space:pre-wrap}",
+    ".cell-error{background:#fff0f0;border:1px solid #f3c0c0;color:var(--fail);border-radius:6px;padding:.5rem .9rem;margin-top:.4rem}",
+    ".cell-eq{text-align:center;margin:1.3rem 0}",
+    "math{font-size:1.15rem}",
+    ".cell-test{display:flex;align-items:center;gap:.5rem;font-size:.95rem}",
+    ".cell-test .badge{font-weight:700;width:1.4rem;height:1.4rem;display:inline-flex;align-items:center;justify-content:center;border-radius:50%;color:#fff}",
+    ".cell-test.pass .badge{background:var(--pass)}",
+    ".cell-test.fail .badge{background:var(--fail)}",
+    ".cell-test.err .badge{background:#9a6700}",
+    ".cell-test.nrun .badge{background:#8a8a9a}",
+    ".cell-test .note{color:var(--fail);font-size:.85rem}",
+    ".cell-chart{text-align:center}",
+    ".note{color:var(--muted)}"
+  ].join("");
+}
+function toHTML(doc, options = {}) {
+  const title = doc.title ?? "Workbook";
+  const headerBits = [`<h1 class="doc-title">${esc2(title)}</h1>`];
+  if (doc.author) headerBits.push(`<p class="doc-meta">by ${esc2(doc.author)}</p>`);
+  if (doc.description) headerBits.push(`<p class="doc-desc">${esc2(doc.description)}</p>`);
+  if (doc.tags && doc.tags.length) {
+    headerBits.push(
+      `<p class="doc-tags">${doc.tags.map((t) => `<span class="tag">${esc2(t)}</span>`).join("")}</p>`
+    );
+  }
+  const body = doc.cells.map((c) => renderCell(c, options.parse)).join("\n");
+  return [
+    "<!doctype html>",
+    '<html lang="en">',
+    "<head>",
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    `<title>${esc2(title)}</title>`,
+    `<style>${toCSS()}</style>`,
+    "</head>",
+    "<body>",
+    "<main>",
+    `<header>${headerBits.join("")}</header>`,
+    body,
+    "</main>",
+    "</body>",
+    "</html>"
+  ].join("\n");
+}
+
+// src/tex.ts
+var PREAMBLE = [
+  "\\documentclass{article}",
+  "\\usepackage{amsmath}",
+  "\\usepackage{tikz}",
+  "\\usepackage{listings}",
+  "\\usepackage{xcolor}",
+  "\\usepackage[margin=1in]{geometry}",
+  "\\usepackage{hyperref}"
+].join("\n");
+function renderEquationTex(content, parse3) {
+  if (parse3) {
+    try {
+      const node = parse3(content);
+      return `\\[ ${node.toTex()} \\]`;
+    } catch {
+    }
+  }
+  return `\\texttt{${texEscape(content)}}`;
+}
+function renderCellTex(cell, parse3) {
+  switch (cell.type) {
+    case "markdown":
+      return markdownToTex(cell.content);
+    case "equation":
+      return renderEquationTex(cell.content, parse3);
+    case "code": {
+      const cap = cell.id ? `\\textit{${texEscape(cell.id)}}\\\\
+` : "";
+      const src = `\\begin{lstlisting}
+${cell.content}
+\\end{lstlisting}`;
+      let res = "";
+      if (cell.error !== void 0)
+        res = `
+
+\\textcolor{red}{\\texttt{${texEscape(cell.error)}}}`;
+      else if (cell.output !== void 0)
+        res = `
+
+\\begin{verbatim}
+${cell.output}
+\\end{verbatim}`;
+      return `${cap}${src}${res}`;
+    }
+    case "test": {
+      const label = `\\texttt{${texEscape(cell.content)}}`;
+      if (cell.error !== void 0)
+        return `\\textcolor{orange}{[ERROR]} ${label} --- ${texEscape(cell.error)}`;
+      if (cell.passed === true) return `\\textcolor{green!60!black}{[PASS]} ${label}`;
+      if (cell.passed === false) return `\\textcolor{red}{[FAIL]} ${label}`;
+      return `\\textcolor{gray}{[NOT RUN]} ${label}`;
+    }
+    case "data": {
+      const val = cell.error !== void 0 ? cell.error : cell.output ?? "";
+      const cap = cell.id ? `\\textit{${texEscape(cell.id)}}\\\\
+` : "";
+      return `${cap}\\begin{verbatim}
+${val}
+\\end{verbatim}`;
+    }
+    case "chart": {
+      const chart = cell.chartTikz ?? "% no chart";
+      const note = cell.note ? `
+
+\\textit{${texEscape(cell.note)}}` : "";
+      return `\\begin{center}
+${chart}
+\\end{center}${note}`;
+    }
+    default:
+      return `\\begin{verbatim}
+${cell.content}
+\\end{verbatim}`;
+  }
+}
+function toTeX(doc, options = {}) {
+  const body = doc.cells.map((c) => renderCellTex(c, options.parse)).join("\n\n");
+  if (options.fragment) return body;
+  const meta = [];
+  if (doc.title) meta.push(`\\title{${texEscape(doc.title)}}`);
+  if (doc.author) meta.push(`\\author{${texEscape(doc.author)}}`);
+  const maketitle = doc.title ? "\\maketitle\n" : "";
+  return [PREAMBLE, ...meta, "\\begin{document}", `${maketitle}${body}`, "\\end{document}"].join(
+    "\n"
+  );
+}
+
+// src/pdf.ts
+import { latexToPdf } from "@danielsimonjr/mathts-plot/render";
+function toPDF(doc, outPath, options = {}) {
+  const { parse: parse3, ...renderOpts } = options;
+  return latexToPdf(toTeX(doc, { parse: parse3, fragment: false }), outPath, renderOpts);
+}
+
+// src/svg.ts
+import { line, scatter, bar } from "@danielsimonjr/mathts-plot";
+function coerce(v) {
+  if (typeof v === "number") return v;
+  if (typeof v === "bigint") return Number(v);
+  const u = v;
+  if (u && typeof u.toNumeric === "function") {
+    try {
+      return Number(u.toNumeric());
+    } catch {
+      return NaN;
+    }
+  }
+  return Number(v);
+}
+function toNums(raw) {
+  let arr = raw;
+  const m = raw;
+  if (m && typeof m.toArray === "function") {
+    try {
+      arr = m.toArray();
+    } catch {
+      arr = raw;
+    }
+  }
+  return Array.isArray(arr) ? arr.flat(Infinity).map(coerce) : [];
+}
+function renderChart(spec, xRaw, yRaw, format = "svg") {
+  const xs = toNums(xRaw);
+  const ys = toNums(yRaw);
+  const opts = format === "tikz" ? {
+    title: spec.title,
+    xLabel: spec.xLabel,
+    yLabel: spec.yLabel,
+    format: "tikz",
+    tikz: { standalone: false }
+  } : { title: spec.title, xLabel: spec.xLabel, yLabel: spec.yLabel };
+  if (spec.type === "scatter") return scatter(xs, ys, opts);
+  if (spec.type === "bar") return bar(xs, ys, opts);
+  return line(xs, ys, opts);
+}
+
+// src/cli.ts
+var parse2 = mathFunctions.parse;
 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)
+  mtsw run <file> [-c <id>] [-v] [--json] [--write]
+                                            Execute a workbook (or one cell + its
+                                            deps with -c/--cell). -v: events,
+                                            --json: machine output, --write: persist
+                                            outputs back to the file.
+  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
+  mtsw strip <file> [-w|--write]            Strip outputs (stdout, or -w to rewrite)
+  mtsw new <name> [-t basic|empty|chart] [--empty] [-o <path>] [--force]
+                                            Scaffold a new workbook (-o for any path)
+  mtsw import [<file>] [-o out.mtsw] [--json]
+                                            Build a .mtsw from a JSON/YAML doc
+                                            ({metadata,cells:[{id,type,content,dependsOn}]};
+                                            file or stdin; stdout if no -o)
+  mtsw capabilities [--json]                Engine version + feature flags
+  mtsw templates [--json]                   List scaffold templates
+  mtsw cell <verb> <file> ...               Edit cells (atomic, in-place):
+      cell add <file> --type <t> --id <id> [--content <s> | --content-file <p|->]
+                                  [--depends-on a,b] [--before|--after <id> | --at <n>]
+      cell edit <file> <id> [--content <s> | --content-file <p|->] [--type <t>] [--depends-on a,b]
+      cell rm <file> <id> [--force]         (--force detaches dependents)
+      cell move <file> <id> (--before|--after <id> | --at <n>)
+      cell rename <file> <oldId> <newId>
+      (any cell verb accepts --json and --dry-run)
+  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]
+                                            Render to a self-contained HTML or LaTeX
+                                            document (MathML/TikZ equations + charts,
+                                            no external deps), or emit the executed
+                                            run report as JSON. --fragment (tex only)
+                                            omits the preamble for \\input; --no-run is
+                                            incompatible with --format json.
+  mtsw serve [<file>]                        JSON-RPC over stdio (persistent session
+                                            w/ streaming events + incremental run)
 
 Options:
   -h, --help     Show this help
-  -v, --verbose  Verbose output
   -V, --version  Show version
+
+Notes:
+  --json output is a single envelope on stdout: { schemaVersion, command, ok,
+  data, problems }. The envelope is emitted even on failure; exit code mirrors
+  'ok' (GUI clients should read 'ok', not the exit code).
+  Writes (run --write, strip -w, new) are atomic but drop YAML comments / key
+  order. Dependency scope is direct-only (non-transitive); cell ids must be
+  valid identifiers ([A-Za-z_][A-Za-z0-9_]*).
+`.trimStart();
+function jsonEnvelope(command, ok, data, problems = []) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  const replacer = (_key, value) => {
+    if (typeof value === "bigint") return `${value}n`;
+    if (value !== null && typeof value === "object") {
+      if (seen.has(value)) return "[Circular]";
+      seen.add(value);
+    }
+    return value;
+  };
+  return JSON.stringify(
+    { schemaVersion: SCHEMA_VERSION, command, ok, data, problems: problems ?? [] },
+    replacer,
+    2
+  );
+}
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "-f",
+  "--format",
+  "-t",
+  "--template",
+  "-c",
+  "--cell",
+  "--id",
+  "--content",
+  "--content-file",
+  "--depends-on",
+  "--before",
+  "--after",
+  "--at",
+  "--title",
+  "--author",
+  "--description",
+  "--tags",
+  "-o",
+  "--output"
+]);
+function firstPositional(args) {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (VALUE_FLAGS.has(arg)) {
+      i++;
+      continue;
+    }
+    if (!arg.startsWith("-")) return arg;
+  }
+  return void 0;
+}
+function flagValue(args, flag) {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : void 0;
+}
+function readFile(file) {
+  try {
+    return { content: readFileSync(file, "utf-8") };
+  } catch (error) {
+    return {
+      error: `Cannot read file '${file}': ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+}
+var BASIC_TEMPLATE = `version: "1.0"
+metadata:
+  title: "<NAME>"
+runtime:
+  engine: mathts
+  execution: reactive
+cells:
+  - markdown: |
+      # <NAME>
+
+      A new MathTS workbook. Edit the cells, then run:
+      mtsw run <NAME>.mtsw
+    id: intro
+
+  - code: "1 + 1"
+    id: example
+
+  - test: "example == 2"
+    id: checkExample
+    depends_on: [example]
 `;
-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);
+function bullets(items) {
+  return items.map((item) => `  - ${item}`).join("\n");
+}
+function statusMark(status) {
+  return status === "success" || status === "pass" ? "\u2713" : "\u2717";
+}
+function humanCellLine(cell) {
+  const mark = statusMark(cell.status);
+  const body = cell.status === "error" || cell.status === "fail" ? cell.error ?? "(failed)" : formatResult(cell.output);
+  return `${mark} ${cell.id} (${cell.type}): ${body}`;
+}
+function failureSummary(cells) {
+  const failures = cells.filter((c) => c.status === "error" || c.status === "fail");
+  if (failures.length === 0) return "";
+  return `${failures.length} cell(s) failed:
+${bullets(failures.map((c) => `${c.id}: ${c.error ?? "(failed)"}`))}`;
+}
+function errMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function applyResults(workbook, results) {
+  for (const result of results) {
+    const cell = workbook.cells.find((c) => c.id === result.id);
+    if (!cell) continue;
+    cell.output = result.output;
+    cell.error = result.error;
   }
 }
+function jsonCells(cells) {
+  return cells.map((c) => ({
+    id: c.id,
+    type: c.type,
+    status: c.status,
+    output: c.output ?? null,
+    error: c.error ?? null
+  }));
+}
+function failureList(cells) {
+  return cells.filter((c) => c.status === "error" || c.status === "fail").map((c) => `${c.id}: ${c.error ?? "(failed)"}`);
+}
 async function runCommand(args) {
-  const file = args[0];
+  const json = args.includes("--json");
+  const fail = (problems2, data = null) => json ? { stdout: jsonEnvelope("run", false, data, problems2), stderr: "", exitCode: 1 } : { stdout: "", stderr: problems2.join("\n"), exitCode: 1 };
+  const file = firstPositional(args);
   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();
+    return json ? fail(["Usage: mtsw run <file> [-c <id>] [-v] [--json] [--write]"]) : {
+      stdout: "",
+      stderr: "Usage: mtsw run <file> [-c <id>] [-v] [--json] [--write]",
+      exitCode: 1
+    };
   }
+  const read = readFile(file);
+  if (read.error) return fail([read.error]);
+  const parsed = parseWorkbook(read.content);
+  if (!parsed.success) {
+    const problems2 = parsed.errors ?? [];
+    return json ? fail(problems2, { cells: [] }) : {
+      stdout: "",
+      stderr: `Parse errors:
+${bullets(problems2)}`,
+      exitCode: 1
+    };
+  }
+  const cellId = flagValue(args, "-c") ?? flagValue(args, "--cell");
+  if (cellId !== void 0 && !parsed.workbook.cells.some((c) => c.id === cellId)) {
+    return json ? fail([`No such cell: '${cellId}'`], { cells: [] }) : {
+      stdout: "",
+      stderr: `No such cell: '${cellId}'`,
+      exitCode: 1
+    };
+  }
+  const verbose = args.includes("-v") || args.includes("--verbose");
+  const executor = createExecutor(parsed.workbook);
+  const events = [];
+  if (verbose) {
+    executor.on((event) => events.push(`[${event.type}] ${event.cellId ?? ""}`.trimEnd()));
+  }
+  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")) {
+    applyResults(parsed.workbook, report.cells);
+    try {
+      writeFileAtomic(file, serializeWorkbook(parsed.workbook));
+    } catch (error) {
+      return fail([`Failed to write '${file}': ${errMessage(error)}`], {
+        cells: jsonCells(report.cells)
+      });
+    }
+    if (json) {
+      const stdout2 = jsonEnvelope(
+        "run",
+        report.ok,
+        { cells: jsonCells(report.cells), written: file },
+        problems
+      );
+      return { stdout: stdout2, stderr: "", exitCode: report.ok ? 0 : 1 };
+    }
+    return {
+      stdout: "",
+      stderr: [`Updated ${file}`, humanFailures].filter(Boolean).join("\n"),
+      exitCode: report.ok ? 0 : 1
+    };
+  }
+  if (json) {
+    const stdout2 = jsonEnvelope("run", report.ok, { cells: jsonCells(report.cells) }, problems);
+    return { stdout: stdout2, stderr: "", exitCode: report.ok ? 0 : 1 };
+  }
+  const body = report.cells.map(humanCellLine).join("\n");
+  const stdout = verbose && events.length > 0 ? `${events.join("\n")}
+
+${body}` : body;
+  return { stdout, stderr: humanFailures, exitCode: report.ok ? 0 : 1 };
+}
+function validateChartSpecs(workbook) {
+  const problems = [];
+  const ids = new Set(workbook.cells.map((c) => c.id));
+  for (const cell of workbook.cells) {
+    if (cell.type !== "visualization") continue;
+    let spec;
+    try {
+      spec = parseYamlHardened(cell.content);
+    } catch (error) {
+      problems.push(`Cell "${cell.id}": invalid chart spec (${errMessage(error)})`);
+      continue;
+    }
+    if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+      problems.push(`Cell "${cell.id}": chart spec must be a mapping with type/x/y`);
+      continue;
+    }
+    const s = spec;
+    if (s.type !== void 0 && !["line", "scatter", "bar"].includes(String(s.type))) {
+      problems.push(`Cell "${cell.id}": chart type must be line|scatter|bar`);
+    }
+    for (const axis of ["x", "y"]) {
+      const a = s[axis];
+      if (!a || typeof a !== "object") {
+        problems.push(`Cell "${cell.id}": chart "${axis}" must be a mapping with a "data" field`);
+        continue;
+      }
+      const data = a.data;
+      if (data === void 0) {
+        problems.push(`Cell "${cell.id}": chart ${axis}.data is required`);
+      } else if (typeof data === "string" && !ids.has(data)) {
+        problems.push(`Cell "${cell.id}": chart ${axis}.data references unknown cell "${data}"`);
+      }
+    }
+  }
+  return problems;
 }
-async function validateCommand(args) {
-  const file = args[0];
+function computeProblems(parsed) {
+  const problems = [...parsed.errors ?? []];
+  if (parsed.success && parsed.workbook) {
+    const graph = buildDependencyGraph(parsed.workbook.cells);
+    for (const cycle of detectCycles(graph)) {
+      problems.push(`Dependency cycle: ${cycle.join(" -> ")}`);
+    }
+    problems.push(...validateChartSpecs(parsed.workbook));
+  }
+  return problems;
+}
+function validateCommand(args) {
+  const json = args.includes("--json");
+  const file = firstPositional(args);
+  if (!file) {
+    return json ? {
+      stdout: jsonEnvelope("validate", false, null, ["Usage: mtsw validate <file>"]),
+      stderr: "",
+      exitCode: 1
+    } : { stdout: "", stderr: "Usage: mtsw validate <file>", exitCode: 1 };
+  }
+  const read = readFile(file);
+  if (read.error) {
+    return json ? { stdout: jsonEnvelope("validate", false, null, [read.error]), stderr: "", exitCode: 1 } : { stdout: "", stderr: read.error, exitCode: 1 };
+  }
+  const parsed = parseWorkbook(read.content);
+  const problems = computeProblems(parsed);
+  const ok = problems.length === 0;
+  const cellCount = parsed.workbook ? parsed.workbook.cells.length : 0;
+  if (json) {
+    return {
+      stdout: jsonEnvelope("validate", ok, { cellCount }, problems),
+      stderr: "",
+      exitCode: ok ? 0 : 1
+    };
+  }
+  if (ok) {
+    return { stdout: `OK: '${file}' is valid (${cellCount} cell(s))`, stderr: "", exitCode: 0 };
+  }
+  return { stdout: "", stderr: `Invalid workbook:
+${bullets(problems)}`, exitCode: 1 };
+}
+function describeCommand(args) {
+  const json = args.includes("--json");
+  const file = firstPositional(args);
   if (!file) {
-    console.error("Usage: mtsw validate <file>");
-    process.exit(1);
+    return json ? {
+      stdout: jsonEnvelope("describe", false, null, ["Usage: mtsw describe <file>"]),
+      stderr: "",
+      exitCode: 1
+    } : { stdout: "", stderr: "Usage: mtsw describe <file>", exitCode: 1 };
+  }
+  const read = readFile(file);
+  if (read.error) {
+    return json ? { stdout: jsonEnvelope("describe", false, null, [read.error]), stderr: "", exitCode: 1 } : { stdout: "", stderr: read.error, exitCode: 1 };
+  }
+  const parsed = parseWorkbook(read.content);
+  const problems = computeProblems(parsed);
+  const ok = parsed.success && problems.length === 0;
+  const data = describeData(parsed.workbook);
+  const cells = data.cells;
+  if (json) {
+    return {
+      stdout: jsonEnvelope("describe", ok, data, problems),
+      stderr: "",
+      exitCode: ok ? 0 : 1
+    };
+  }
+  if (!parsed.success) {
+    return { stdout: "", stderr: `Parse errors:
+${bullets(problems)}`, exitCode: 1 };
+  }
+  const byType = cells.reduce((acc, c) => {
+    acc[c.type] = (acc[c.type] ?? 0) + 1;
+    return acc;
+  }, {});
+  const summary = [
+    `${data.metadata.title ?? "(untitled)"} \u2014 ${cells.length} cell(s)`,
+    ...Object.entries(byType).map(([t, n]) => `  ${t}: ${n}`),
+    problems.length ? `${problems.length} problem(s)` : "no problems"
+  ].join("\n");
+  return { stdout: summary, stderr: "", exitCode: ok ? 0 : 1 };
+}
+function capabilitiesCommand(args) {
+  const data = capabilitiesInfo();
+  if (args.includes("--json")) {
+    return { stdout: jsonEnvelope("capabilities", true, data, []), stderr: "", exitCode: 0 };
+  }
+  const lines = [
+    `mtsw ${data.version} (schema ${SCHEMA_VERSION.major}.${SCHEMA_VERSION.minor})`,
+    `supported cells: ${data.cellTypes.supported.join(", ")}`,
+    `deferred cells: ${data.cellTypes.deferred.join(", ")}`,
+    `commands: ${data.commands.join(", ")}`
+  ];
+  return { stdout: lines.join("\n"), stderr: "", exitCode: 0 };
+}
+function templatesCommand(args) {
+  const templates = Object.entries(TEMPLATES).map(([name, t]) => ({
+    name,
+    description: t.description
+  }));
+  if (args.includes("--json")) {
+    return { stdout: jsonEnvelope("templates", true, { templates }, []), stderr: "", exitCode: 0 };
+  }
+  return {
+    stdout: templates.map((t) => `${t.name} - ${t.description}`).join("\n"),
+    stderr: "",
+    exitCode: 0
+  };
+}
+function functionsCommand(args) {
+  const data = listFunctions();
+  if (args.includes("--json")) {
+    return { stdout: jsonEnvelope("functions", true, data, []), stderr: "", exitCode: 0 };
+  }
+  const lines = [
+    `functions (${data.functions.length}): ${data.functions.join(", ")}`,
+    `constants (${data.constants.length}): ${data.constants.join(", ")}`
+  ];
+  return { stdout: lines.join("\n"), stderr: "", exitCode: 0 };
+}
+function metaCommand(args) {
+  const json = args.includes("--json");
+  const fail = (problems) => json ? { stdout: jsonEnvelope("meta", false, null, problems), stderr: "", exitCode: 1 } : { stdout: "", stderr: problems.join("\n"), exitCode: 1 };
+  const verb = args[0];
+  if (verb !== "get" && verb !== "set") return fail(["Usage: mtsw meta <get|set> <file> ..."]);
+  const vargs = args.slice(1);
+  const file = positionals(vargs)[0];
+  if (!file) return fail([`Usage: mtsw meta ${verb} <file> ...`]);
+  const read = readFile(file);
+  if (read.error) return fail([read.error]);
+  const parsed = parseWorkbook(read.content);
+  if (!parsed.success) return fail(parsed.errors ?? ["Parse error"]);
+  const wb = parsed.workbook;
+  if (verb === "get") {
+    if (json)
+      return { stdout: jsonEnvelope("meta", true, wb.metadata, []), stderr: "", exitCode: 0 };
+    const lines = Object.entries(wb.metadata).map(
+      ([k, v]) => `${k}: ${Array.isArray(v) ? v.join(", ") : String(v)}`
+    );
+    return { stdout: lines.join("\n") || "(no metadata)", stderr: "", exitCode: 0 };
+  }
+  const changes = {};
+  const title = flagValue(vargs, "--title");
+  if (title !== void 0) changes.title = title;
+  const author = flagValue(vargs, "--author");
+  if (author !== void 0) changes.author = author;
+  const description = flagValue(vargs, "--description");
+  if (description !== void 0) changes.description = description;
+  const tags = flagValue(vargs, "--tags");
+  if (tags !== void 0)
+    changes.tags = tags.split(",").map((s) => s.trim()).filter(Boolean);
+  if (Object.keys(changes).length === 0) {
+    return fail(["meta set requires at least one of --title/--author/--description/--tags"]);
+  }
+  let next;
+  try {
+    next = setMetadata(wb, changes);
+  } catch (error) {
+    return fail([errMessage(error)]);
+  }
+  try {
+    writeFileAtomic(file, serializeWorkbook(next));
+  } catch (error) {
+    return fail([`Failed to write '${file}': ${errMessage(error)}`]);
+  }
+  if (json)
+    return { stdout: jsonEnvelope("meta", true, next.metadata, []), stderr: "", exitCode: 0 };
+  return { stdout: "", stderr: `Updated metadata in ${file}`, exitCode: 0 };
+}
+function buildRenderDoc(workbook, byId, format = "svg") {
+  const lookup = (ref) => {
+    if (typeof ref !== "string") return ref;
+    return byId?.get(ref)?.output ?? workbook.cells.find((c) => c.id === ref)?.output;
+  };
+  const cells = workbook.cells.map((c) => {
+    const rc = { type: c.type, content: c.content, id: c.id };
+    if (c.type === "markdown" || c.type === "equation") return rc;
+    if (c.type === "visualization") {
+      rc.type = "chart";
+      try {
+        const spec = parseYamlHardened(c.content);
+        const rendered = renderChart(
+          { type: spec?.type, title: spec?.title, xLabel: spec?.x?.label, yLabel: spec?.y?.label },
+          lookup(spec?.x?.data),
+          lookup(spec?.y?.data),
+          format
+        );
+        if (format === "tikz") rc.chartTikz = rendered;
+        else rc.chartSvg = rendered;
+        const unresolved = [];
+        for (const ref of [spec?.x?.data, spec?.y?.data]) {
+          if (typeof ref !== "string") continue;
+          if (byId) {
+            const r2 = byId.get(ref);
+            if (!r2 || r2.status === "error" || r2.status === "fail") unresolved.push(ref);
+          } else if (workbook.cells.find((x) => x.id === ref)?.output === void 0) {
+            unresolved.push(ref);
+          }
+        }
+        if (unresolved.length > 0) {
+          rc.note = `chart data did not resolve: ${unresolved.join(", ")}${byId ? "" : " (try without --no-run)"}`;
+        }
+      } catch (error2) {
+        const placeholder = renderChart({}, [], [], format);
+        if (format === "tikz") rc.chartTikz = placeholder;
+        else rc.chartSvg = placeholder;
+        rc.note = `invalid chart spec: ${errMessage(error2)}`;
+      }
+      return rc;
+    }
+    const r = byId?.get(c.id);
+    const status = r?.status;
+    const output = r ? r.output : c.output;
+    const error = r ? r.error : c.error;
+    if (c.type === "test") {
+      if (status === "error") rc.error = error ?? "error";
+      else if (status !== void 0) rc.passed = status === "pass";
+      else if (typeof output === "boolean") rc.passed = output;
+      return rc;
+    }
+    if (status === "error" || status === "fail" || status === void 0 && error !== void 0) {
+      rc.error = error ?? "error";
+    } else if (output !== void 0) {
+      rc.output = formatResult(output);
+    }
+    return rc;
+  });
+  return {
+    title: workbook.metadata.title,
+    author: workbook.metadata.author,
+    description: workbook.metadata.description,
+    tags: workbook.metadata.tags,
+    cells
+  };
+}
+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)`]);
+  }
+  const file = firstPositional(args);
+  if (!file)
+    return fail([
+      "Usage: mtsw export <file> [--format html|tex|json|pdf] [--fragment] [-o out] [--no-run]"
+    ]);
+  const read = readFile(file);
+  if (read.error) return fail([read.error]);
+  const parsed = parseWorkbook(read.content);
+  if (!parsed.success) return fail(parsed.errors ?? ["Parse error"]);
+  const workbook = parsed.workbook;
+  let byId = null;
+  let report = null;
+  if (!args.includes("--no-run")) {
+    report = await createExecutor(workbook).runReport();
+    const fatal = report.cells.find((r) => r.id === "(workbook)");
+    if (fatal) return fail([fatal.error ?? "workbook run failed"]);
+    byId = new Map(report.cells.map((r) => [r.id, r]));
+  }
+  if (format === "json") {
+    if (!report) {
+      return fail(["--format json requires running the notebook (remove --no-run)"]);
+    }
+    const payload = {
+      ok: report.ok,
+      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
+      }))
+    };
+    const jsonStr = JSON.stringify(payload, null, 2);
+    const outPath2 = flagValue(args, "-o") ?? flagValue(args, "--output");
+    if (outPath2) {
+      try {
+        writeFileAtomic(outPath2, jsonStr);
+      } catch (error) {
+        return fail([`Failed to write '${outPath2}': ${errMessage(error)}`]);
+      }
+      if (json)
+        return {
+          stdout: jsonEnvelope(
+            "export",
+            true,
+            { path: outPath2, bytes: Buffer.byteLength(jsonStr) },
+            []
+          ),
+          stderr: "",
+          exitCode: 0
+        };
+      return {
+        stdout: "",
+        stderr: `Exported ${file} -> ${outPath2} (${Buffer.byteLength(jsonStr)} bytes)`,
+        exitCode: 0
+      };
+    }
+    return { stdout: jsonStr, stderr: "", exitCode: 0 };
+  }
+  if (format === "pdf") {
+    const outPath2 = flagValue(args, "-o") ?? flagValue(args, "--output");
+    if (!outPath2) return fail(["--format pdf requires an output path: -o <file.pdf>"]);
+    try {
+      await toPDF(buildRenderDoc(workbook, byId, "tikz"), outPath2, { parse: parse2 });
+    } catch (error) {
+      return fail([`PDF export failed: ${errMessage(error)}`]);
+    }
+    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 bytes = Buffer.byteLength(rendered, "utf-8");
+  const outPath = flagValue(args, "-o") ?? flagValue(args, "--output");
+  if (outPath) {
+    try {
+      writeFileAtomic(outPath, rendered);
+    } catch (error) {
+      return fail([`Failed to write '${outPath}': ${errMessage(error)}`]);
+    }
+    if (json)
+      return {
+        stdout: jsonEnvelope("export", true, { path: outPath, bytes }, []),
+        stderr: "",
+        exitCode: 0
+      };
+    return { stdout: "", stderr: `Exported ${file} -> ${outPath} (${bytes} bytes)`, exitCode: 0 };
+  }
+  if (json) return { stdout: jsonEnvelope("export", true, { bytes }, []), stderr: "", exitCode: 0 };
+  return { stdout: rendered, stderr: "", exitCode: 0 };
+}
+function runServer(input = process.stdin, output = process.stdout) {
+  const session = new Session();
+  const rl = createInterface({ input, crlfDelay: Infinity });
+  const write = (obj) => {
+    output.write(`${JSON.stringify(obj)}
+`);
+  };
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      process.removeListener("SIGINT", finish);
+      process.removeListener("SIGTERM", finish);
+      rl.close();
+      resolve();
+    };
+    const processLine = async (line2) => {
+      if (done) return;
+      const text = line2.trim();
+      if (!text) return;
+      let request;
+      try {
+        request = JSON.parse(text);
+      } catch {
+        write({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+        return;
+      }
+      if (Array.isArray(request)) {
+        write({
+          jsonrpc: "2.0",
+          id: null,
+          error: { code: -32600, message: "Batch requests are not supported" }
+        });
+        return;
+      }
+      try {
+        const { response, events, shutdown } = await handleRequest(
+          session,
+          request
+        );
+        for (const event of events) write(event);
+        write(response);
+        if (shutdown) finish();
+      } catch (error) {
+        write({
+          jsonrpc: "2.0",
+          id: null,
+          error: { code: -32603, message: error instanceof Error ? error.message : String(error) }
+        });
+      }
+    };
+    let queue = Promise.resolve();
+    rl.on("line", (line2) => {
+      queue = queue.then(() => processLine(line2));
+    });
+    rl.on("close", () => {
+      void queue.then(finish);
+    });
+    process.once("SIGINT", finish);
+    process.once("SIGTERM", finish);
+  });
+}
+async function serveCommand() {
+  await runServer();
+  return { stdout: "", stderr: "", exitCode: 0 };
+}
+function graphCommand(args) {
+  if (args.includes("--json")) {
+    return {
+      stdout: jsonEnvelope("graph", false, null, [
+        "graph has no --json output; use `describe --json` for structured graph data"
+      ]),
+      stderr: "",
+      exitCode: 1
+    };
+  }
+  const file = firstPositional(args);
+  if (!file) {
+    return { stdout: "", stderr: "Usage: mtsw graph <file> [-f mermaid|dot]", exitCode: 1 };
+  }
+  const read = readFile(file);
+  if (read.error) return { stdout: "", stderr: read.error, exitCode: 1 };
+  const parsed = parseWorkbook(read.content);
+  if (!parsed.success) {
+    return { stdout: "", stderr: `Parse errors:
+${bullets(parsed.errors ?? [])}`, exitCode: 1 };
   }
-  console.log(`Validating: ${file}`);
+  const graph = buildDependencyGraph(parsed.workbook.cells);
+  if (flagValue(args, "-f") === "mermaid" || flagValue(args, "--format") === "mermaid") {
+    return { stdout: toMermaid(graph), stderr: "", exitCode: 0 };
+  }
+  if (flagValue(args, "-f") === "dot" || flagValue(args, "--format") === "dot") {
+    return { stdout: toDOT(graph), stderr: "", exitCode: 0 };
+  }
+  const lines = [...graph.nodes].map(([id, node]) => `${id}: [${node.dependencies.join(", ")}]`);
+  return { stdout: lines.join("\n"), stderr: "", exitCode: 0 };
 }
-async function graphCommand(args) {
-  const file = args[0];
+function stripCommand(args) {
+  const file = firstPositional(args);
   if (!file) {
-    console.error("Usage: mtsw graph <file>");
-    process.exit(1);
+    return { stdout: "", stderr: "Usage: mtsw strip <file> [-w|--write]", exitCode: 1 };
+  }
+  const read = readFile(file);
+  if (read.error) return { stdout: "", stderr: read.error, exitCode: 1 };
+  const parsed = parseWorkbook(read.content);
+  if (!parsed.success) {
+    return { stdout: "", stderr: `Parse errors:
+${bullets(parsed.errors ?? [])}`, exitCode: 1 };
+  }
+  const yaml = serializeWorkbook(stripOutputs(parsed.workbook));
+  if (args.includes("-w") || args.includes("--write")) {
+    try {
+      writeFileAtomic(file, yaml);
+    } catch (error) {
+      return { stdout: "", stderr: `Failed to write '${file}': ${errMessage(error)}`, exitCode: 1 };
+    }
+    return { stdout: "", stderr: `Stripped outputs -> ${file}`, exitCode: 0 };
+  }
+  return { stdout: yaml, stderr: "", exitCode: 0 };
+}
+var EMPTY_TEMPLATE = `version: "1.0"
+metadata:
+  title: "<NAME>"
+runtime:
+  engine: mathts
+  execution: reactive
+cells: []
+`;
+var CHART_TEMPLATE = `version: "1.0"
+metadata:
+  title: "<NAME>"
+runtime:
+  engine: mathts
+  execution: reactive
+cells:
+  - data: "[1, 2, 3, 4]"
+    id: xs
+
+  - data: "[1, 4, 9, 16]"
+    id: ys
+
+  - visualization: |
+      type: line
+      title: "Sample chart"
+      x: { label: "x", data: xs }
+      y: { label: "y", data: ys }
+    id: chart
+    depends_on: [xs, ys]
+`;
+var TEMPLATES = {
+  basic: {
+    content: BASIC_TEMPLATE,
+    description: "Markdown intro + a code cell + a passing test cell"
+  },
+  empty: { content: EMPTY_TEMPLATE, description: "A blank workbook (no cells)" },
+  chart: {
+    content: CHART_TEMPLATE,
+    description: "A line chart over two data cells (visualization example)"
   }
-  console.log(`Dependency graph for: ${file}`);
+};
+var RESERVED_DEVICE_NAMES = /* @__PURE__ */ new Set([
+  "CON",
+  "PRN",
+  "AUX",
+  "NUL",
+  ...Array.from({ length: 9 }, (_unused, i) => `COM${i + 1}`),
+  ...Array.from({ length: 9 }, (_unused, i) => `LPT${i + 1}`)
+]);
+function newCommand(args) {
+  const outPath = flagValue(args, "-o") ?? flagValue(args, "--output");
+  const name = firstPositional(args);
+  const templateName = args.includes("--empty") ? "empty" : flagValue(args, "-t") ?? flagValue(args, "--template") ?? "basic";
+  const template = TEMPLATES[templateName];
+  if (!template) {
+    return {
+      stdout: "",
+      stderr: `Unknown template '${templateName}'. Available: ${Object.keys(TEMPLATES).join(", ")}`,
+      exitCode: 1
+    };
+  }
+  let target;
+  let bare;
+  if (outPath) {
+    target = outPath.endsWith(".mtsw") ? outPath : `${outPath}.mtsw`;
+    bare = basename(target).slice(0, -".mtsw".length);
+  } else {
+    if (!name) {
+      return {
+        stdout: "",
+        stderr: "Usage: mtsw new <name> [-t basic|empty|chart] [--empty] [-o <path>] [--force]",
+        exitCode: 1
+      };
+    }
+    if (!/^[A-Za-z0-9._-]+$/.test(name)) {
+      return {
+        stdout: "",
+        stderr: `Invalid name '${name}': must be a bare filename \u2014 or use -o <path> for an explicit location`,
+        exitCode: 1
+      };
+    }
+    bare = name.endsWith(".mtsw") ? name.slice(0, -".mtsw".length) : name;
+    if (bare === "" || bare === "." || bare === ".." || RESERVED_DEVICE_NAMES.has(bare.toUpperCase())) {
+      return { stdout: "", stderr: `Invalid name '${name}'`, exitCode: 1 };
+    }
+    target = `${bare}.mtsw`;
+  }
+  const content = template.content.replace(/<NAME>/g, bare);
+  const force = args.includes("--force");
+  try {
+    if (force) {
+      try {
+        if (lstatSync(target).isSymbolicLink()) {
+          return { stdout: "", stderr: `Refusing to overwrite symlink '${target}'`, exitCode: 1 };
+        }
+      } catch {
+      }
+      writeFileAtomic(target, content);
+    } else {
+      writeFileSync(target, content, { encoding: "utf-8", flag: "wx" });
+    }
+  } catch (error) {
+    const e = error;
+    if (e.code === "EEXIST") {
+      return {
+        stdout: "",
+        stderr: `File '${target}' already exists (use --force to overwrite)`,
+        exitCode: 1
+      };
+    }
+    return {
+      stdout: "",
+      stderr: `Failed to create '${target}': ${errMessage(error)}`,
+      exitCode: 1
+    };
+  }
+  return { stdout: `Created ${target}`, stderr: "", exitCode: 0 };
+}
+function importCommand(args) {
+  const json = args.includes("--json");
+  const fail = (problems) => json ? { stdout: jsonEnvelope("import", false, null, problems), stderr: "", exitCode: 1 } : { stdout: "", stderr: problems.join("\n"), exitCode: 1 };
+  const file = firstPositional(args);
+  let input;
+  if (!file || file === "-") {
+    if (process.stdin.isTTY) return fail(["Provide an input file, or pipe JSON/YAML to stdin"]);
+    try {
+      input = readFileSync(0, "utf-8");
+    } catch (error) {
+      return fail([`Failed to read stdin: ${errMessage(error)}`]);
+    }
+  } else {
+    const read = readFile(file);
+    if (read.error) return fail([read.error]);
+    input = read.content;
+  }
+  const result = importWorkbook(input);
+  if (!result.success || !result.workbook) return fail(result.errors ?? ["Import failed"]);
+  const content = serializeWorkbook(result.workbook);
+  const count = result.workbook.cells.length;
+  const outPath = flagValue(args, "-o") ?? flagValue(args, "--output");
+  if (outPath) {
+    try {
+      writeFileAtomic(outPath, content);
+    } catch (error) {
+      return fail([`Failed to write '${outPath}': ${errMessage(error)}`]);
+    }
+    if (json)
+      return {
+        stdout: jsonEnvelope("import", true, { path: outPath, cells: count }, []),
+        stderr: "",
+        exitCode: 0
+      };
+    return { stdout: "", stderr: `Imported ${count} cell(s) -> ${outPath}`, exitCode: 0 };
+  }
+  if (json)
+    return {
+      stdout: jsonEnvelope("import", true, { content, cells: count }, []),
+      stderr: "",
+      exitCode: 0
+    };
+  return { stdout: content, stderr: "", exitCode: 0 };
+}
+function positionals(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (VALUE_FLAGS.has(a)) {
+      i++;
+      continue;
+    }
+    if (!a.startsWith("-")) out.push(a);
+  }
+  return out;
+}
+function parseDependsOn(args) {
+  const value = flagValue(args, "--depends-on");
+  if (value === void 0) return void 0;
+  return [
+    ...new Set(
+      value.split(",").map((s) => s.trim()).filter(Boolean)
+    )
+  ];
 }
-async function newCommand(args) {
-  const name = args[0];
-  if (!name) {
-    console.error("Usage: mtsw new <name>");
-    process.exit(1);
+function parsePosition(args) {
+  const before = flagValue(args, "--before");
+  if (before !== void 0) return { before };
+  const after = flagValue(args, "--after");
+  if (after !== void 0) return { after };
+  const at = flagValue(args, "--at");
+  if (at !== void 0) {
+    const n = Number(at);
+    if (!Number.isInteger(n)) throw new Error(`--at must be an integer (got '${at}')`);
+    return { at: n };
   }
-  console.log(`Creating new workbook: ${name}.mtsw`);
+  return void 0;
+}
+function resolveContent(args) {
+  const inline2 = flagValue(args, "--content");
+  const fromFile = flagValue(args, "--content-file");
+  if (inline2 !== void 0 && fromFile !== void 0) {
+    return { error: "Use only one of --content / --content-file" };
+  }
+  if (inline2 !== void 0) return { content: inline2 };
+  if (fromFile !== void 0) {
+    if (fromFile === "-") {
+      if (process.stdin.isTTY) {
+        return {
+          error: "No piped input for --content-file - (pipe content via stdin, or use --content)"
+        };
+      }
+      try {
+        return { content: readFileSync(0, "utf-8") };
+      } catch (error) {
+        return { error: `Cannot read stdin: ${errMessage(error)}` };
+      }
+    }
+    const r = readFile(fromFile);
+    return r.error ? { error: r.error } : { content: r.content };
+  }
+  return {};
+}
+var CELL_VERBS = ["add", "edit", "rm", "move", "rename"];
+function cellCommand(args) {
+  const json = args.includes("--json");
+  const fail = (problems) => json ? { stdout: jsonEnvelope("cell", false, null, problems), stderr: "", exitCode: 1 } : { stdout: "", stderr: problems.join("\n"), exitCode: 1 };
+  const verb = args[0];
+  if (!verb || !CELL_VERBS.includes(verb)) {
+    return fail([`Usage: mtsw cell <${CELL_VERBS.join("|")}> <file> ...`]);
+  }
+  const vargs = args.slice(1);
+  const pos = positionals(vargs);
+  const file = pos[0];
+  if (!file) return fail([`Usage: mtsw cell ${verb} <file> ...`]);
+  const read = readFile(file);
+  if (read.error) return fail([read.error]);
+  const parsed = parseWorkbook(read.content);
+  if (!parsed.success) return fail(parsed.errors ?? ["Parse error"]);
+  const wb = parsed.workbook;
+  let result;
+  let changedCells = [];
+  try {
+    switch (verb) {
+      case "add": {
+        const id = flagValue(vargs, "--id");
+        const type = flagValue(vargs, "--type") ?? flagValue(vargs, "-t");
+        if (!id) return fail(["cell add requires --id"]);
+        if (!type) return fail(["cell add requires --type"]);
+        const content = resolveContent(vargs);
+        if (content.error) return fail([content.error]);
+        result = addCell(
+          wb,
+          {
+            id,
+            type,
+            content: content.content,
+            dependsOn: parseDependsOn(vargs)
+          },
+          parsePosition(vargs)
+        );
+        break;
+      }
+      case "edit": {
+        const id = pos[1];
+        if (!id) return fail(["cell edit requires <id>"]);
+        const content = resolveContent(vargs);
+        if (content.error) return fail([content.error]);
+        const type = flagValue(vargs, "--type") ?? flagValue(vargs, "-t");
+        const deps = parseDependsOn(vargs);
+        const changes = {};
+        if (content.content !== void 0) changes.content = content.content;
+        if (type !== void 0) changes.type = type;
+        if (deps !== void 0) changes.dependsOn = deps;
+        result = editCell(wb, id, changes);
+        break;
+      }
+      case "rm": {
+        const id = pos[1];
+        if (!id) return fail(["cell rm requires <id>"]);
+        const removed = removeCell(wb, id, { force: vargs.includes("--force") });
+        result = removed.workbook;
+        changedCells = removed.changedCells;
+        break;
+      }
+      case "move": {
+        const id = pos[1];
+        if (!id) return fail(["cell move requires <id>"]);
+        const position = parsePosition(vargs);
+        if (!position) return fail(["cell move requires --before/--after/--at"]);
+        result = moveCell(wb, id, position);
+        break;
+      }
+      case "rename": {
+        const oldId = pos[1];
+        const newId = pos[2];
+        if (!oldId || !newId) return fail(["cell rename requires <oldId> <newId>"]);
+        result = renameCell(wb, oldId, newId);
+        break;
+      }
+      default:
+        return fail([`Unknown cell verb: ${verb}`]);
+    }
+  } catch (error) {
+    return fail([errMessage(error)]);
+  }
+  const after = serializeWorkbook(result);
+  const changed = after !== serializeWorkbook(wb);
+  if (vargs.includes("--dry-run")) {
+    if (json) {
+      const data = {
+        dryRun: true,
+        changed,
+        content: after,
+        ...changedCells.length ? { changedCells } : {}
+      };
+      return { stdout: jsonEnvelope("cell", true, data, []), stderr: "", exitCode: 0 };
+    }
+    return { stdout: after, stderr: "", exitCode: 0 };
+  }
+  if (changed) {
+    try {
+      writeFileAtomic(file, after);
+    } catch (error) {
+      return fail([`Failed to write '${file}': ${errMessage(error)}`]);
+    }
+  }
+  if (json) {
+    const data = {
+      changed,
+      ...changedCells.length ? { changedCells } : {},
+      ...describeData(result)
+    };
+    return { stdout: jsonEnvelope("cell", true, data, []), stderr: "", exitCode: 0 };
+  }
+  const note = changed ? `Updated ${file}` : `No change (${file})`;
+  const detached = changedCells.length ? `
+Detached from: ${changedCells.join(", ")}` : "";
+  return { stdout: "", stderr: note + detached, exitCode: 0 };
+}
+async function dispatch(argv) {
+  if (argv.length === 0 || argv.includes("-h") || argv.includes("--help")) {
+    return { stdout: HELP, stderr: "", exitCode: 0 };
+  }
+  if (argv.includes("-V") || argv.includes("--version")) {
+    return { stdout: `mtsw version ${VERSION}`, stderr: "", exitCode: 0 };
+  }
+  const [command, ...rest] = argv;
+  try {
+    switch (command) {
+      case "run":
+        return await runCommand(rest);
+      case "validate":
+        return validateCommand(rest);
+      case "graph":
+        return graphCommand(rest);
+      case "describe":
+        return describeCommand(rest);
+      case "strip":
+        return stripCommand(rest);
+      case "new":
+        return newCommand(rest);
+      case "capabilities":
+        return capabilitiesCommand(rest);
+      case "templates":
+        return templatesCommand(rest);
+      case "cell":
+        return cellCommand(rest);
+      case "functions":
+        return functionsCommand(rest);
+      case "meta":
+        return metaCommand(rest);
+      case "import":
+        return importCommand(rest);
+      case "export":
+        return exportCommand(rest);
+      case "serve":
+        return serveCommand();
+      default:
+        return { stdout: "", stderr: `Unknown command: ${command}
+${HELP}`, exitCode: 1 };
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (rest.includes("--json")) {
+      return {
+        stdout: jsonEnvelope(command, false, null, [`Internal error: ${message}`]),
+        stderr: "",
+        exitCode: 1
+      };
+    }
+    return { stdout: "", stderr: `Internal error: ${message}`, exitCode: 1 };
+  }
+}
+async function main() {
+  const result = await dispatch(process.argv.slice(2));
+  if (result.stdout) process.stdout.write(`${result.stdout}
+`);
+  if (result.stderr) process.stderr.write(`${result.stderr}
+`);
+  process.exit(result.exitCode);
+}
+function isEntryPoint() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+  } catch {
+    return import.meta.url === pathToFileURL(entry).href;
+  }
+}
+if (isEntryPoint()) {
+  void main();
 }
-main().catch((error) => {
-  console.error("Error:", error);
-  process.exit(1);
-});
+export {
+  capabilitiesCommand,
+  cellCommand,
+  describeCommand,
+  dispatch,
+  exportCommand,
+  functionsCommand,
+  graphCommand,
+  importCommand,
+  metaCommand,
+  newCommand,
+  runCommand,
+  runServer,
+  serveCommand,
+  stripCommand,
+  templatesCommand,
+  validateCommand
+};