@geml/geml 1.4.2 → 1.4.3

package/dist/geml.js

@@ -5,9 +5,10 @@
 // `meta` data block, ATX headings, lists and paragraphs, the attribute object
 // with §4 value typing, and a document-model JSON serialization.
 //
-// M2: inline parsing of flow blocks (§5 — emphasis/strong/strike, code, math,
-// media embeds, links, auto-references, footnotes) and build-time reference
-// validation (§8 — unique ids, resolvable internal/cross-document references).
+// M2: inline parsing of unfenced blocks (§5 — emphasis/strong/strike, code,
+// math, media embeds, links, auto-references, footnotes) and build-time
+// reference validation (§8 — unique ids, resolvable internal/cross-document
+// references).
 import { readFileSync, writeFileSync, realpathSync, statSync, existsSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -15,6 +16,7 @@ import { spawnSync } from "node:child_process";
 import { commit, restore, verify, listRevisions, resolveContent, firstChangedContent } from "./history.js";
 import { renderHtml } from "./render-html.js";
 import { normalizeBlockId } from "./block-edit.js";
+import { normalizeSource } from "./diagnostics.js";
 import { coerce, parseAttrs } from "./attrs.js";
 import { META_REF_SRC, parseInline } from "./inline.js";
 import { parseTable } from "./table.js";
@@ -34,6 +36,9 @@ export { gemlToMd } from "./to-md.js";
 function reLit(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+// Re-exported from ./diagnostics.js so that `Diagnostic` stays importable from
+// the package root. The catalogue of codes lives there (spec Appendix A).
+export { SEVERITY } from "./diagnostics.js";
 // Type registry: which body mode each typed block uses. Unknown types are a
 // warning and fall back to `raw` (forward compatibility, §3/§8).
 const REGISTRY = {
@@ -127,7 +132,7 @@ function interpolate(text, line, ctx) {
                 if (ctx.meta.has(key))
                     out += ctx.meta.get(key);
                 else {
-                    ctx.diags.push({ severity: "error", message: `unknown metadata reference \`{{${key}}}\``, line });
+                    ctx.diags.push({ severity: "error", code: "unknown-metadata-reference", message: `unknown metadata reference \`{{${key}}}\``, line });
                     out += m[0];
                 }
                 i = META_REF.lastIndex;
@@ -142,7 +147,7 @@ function interpolate(text, line, ctx) {
 // Register a block id, flagging duplicates as errors (§4: ids unique per doc).
 function registerId(ctx, id, line) {
     if (ctx.ids.has(id)) {
-        ctx.diags.push({ severity: "error", message: `duplicate id \`#${id}\` (first defined at line ${ctx.ids.get(id)})`, line });
+        ctx.diags.push({ severity: "error", code: "duplicate-id", message: `duplicate id \`#${id}\` (first defined at line ${ctx.ids.get(id)})`, line });
     }
     else {
         ctx.ids.set(id, line);
@@ -212,7 +217,7 @@ function parseList(lines, i, base, ctx) {
                 // rather than building a model that overflows the renderer (DoS). One
                 // diagnostic per over-deep list; content is preserved, just flattened.
                 if (!tooDeep) {
-                    ctx.diags.push({ severity: "error", message: `list nesting too deep (max ${MAX_NESTING})`, line: base + i + 1 });
+                    ctx.diags.push({ severity: "error", code: "list-nesting-too-deep", message: `list nesting too deep (max ${MAX_NESTING})`, line: base + i + 1 });
                     tooDeep = true;
                 }
                 cur = top.list;
@@ -298,11 +303,11 @@ function scanBlocks(lines, base, ctx, depth = 0) {
             }
             if (!closed) {
                 const how = attrs.id !== undefined ? `${"=".repeat(openLen)} or \`=== #${attrs.id}\`` : "=".repeat(openLen);
-                diags.push({ severity: "error", message: `unterminated \`${type}\` block (no matching ${how})`, line: openLineNo });
+                diags.push({ severity: "error", code: "unterminated-block", message: `unterminated \`${type}\` block (no matching ${how})`, line: openLineNo });
             }
             let mode = REGISTRY[type];
             if (mode === undefined) {
-                diags.push({ severity: "warning", message: `unknown block type \`${type}\`; body kept as raw`, line: openLineNo });
+                diags.push({ severity: "warning", code: "unknown-block-type", message: `unknown block type \`${type}\`; body kept as raw`, line: openLineNo });
                 mode = "raw";
             }
             const block = {
@@ -326,7 +331,7 @@ function scanBlocks(lines, base, ctx, depth = 0) {
                     // Refuse to recurse past the cap: emit a diagnostic and keep the body
                     // as raw so the parser returns cleanly instead of overflowing the
                     // call stack on a pathologically nested document (DoS).
-                    diags.push({ severity: "error", message: `block nesting too deep (max ${MAX_NESTING}); body kept as raw`, line: openLineNo });
+                    diags.push({ severity: "error", code: "block-nesting-too-deep", message: `block nesting too deep (max ${MAX_NESTING}); body kept as raw`, line: openLineNo });
                     block.raw = body;
                 }
                 else {
@@ -356,7 +361,7 @@ function scanBlocks(lines, base, ctx, depth = 0) {
                         // §7: native chart — resolved in a second pass (data=#id may be
                         // defined later in the document).
                         if (body.length > 0 && body.some((l) => l.trim() !== "")) {
-                            diags.push({ severity: "warning", message: "geml-chart body is ignored; the chart spec lives in attributes", line: openLineNo });
+                            diags.push({ severity: "warning", code: "ignored-diagram-body", message: "geml-chart body is ignored; the chart spec lives in attributes", line: openLineNo });
                         }
                         (ctx.charts ??= []).push({ block, line: openLineNo });
                     }
@@ -366,18 +371,18 @@ function scanBlocks(lines, base, ctx, depth = 0) {
                         // ("view config travels with the data"). Body is empty.
                         const src = attrs.attrs["src"];
                         if (typeof src !== "string" || src === "") {
-                            diags.push({ severity: "warning", message: "geml-code-graph: missing `src=` (nothing to render)", line: openLineNo });
+                            diags.push({ severity: "warning", code: "code-graph-missing-src", message: "geml-code-graph: missing `src=` (nothing to render)", line: openLineNo });
                         }
                         else if (ctx.resolveDoc && ctx.resolveDoc(src) === null) {
-                            diags.push({ severity: "warning", message: `geml-code-graph: cannot resolve document \`${src}\``, line: openLineNo });
+                            diags.push({ severity: "warning", code: "code-graph-unresolvable-document", message: `geml-code-graph: cannot resolve document \`${src}\``, line: openLineNo });
                         }
                         if (body.length > 0 && body.some((l) => l.trim() !== "")) {
-                            diags.push({ severity: "warning", message: "geml-code-graph body is ignored; the embed is configured by `src=` alone", line: openLineNo });
+                            diags.push({ severity: "warning", code: "ignored-diagram-body", message: "geml-code-graph body is ignored; the embed is configured by `src=` alone", line: openLineNo });
                         }
                     }
                     else if (typeof fmt === "string" && !DIAGRAM_RENDERERS.has(fmt)) {
                         // §7: warn on a diagram format with no registered renderer.
-                        diags.push({ severity: "warning", message: `no registered renderer for diagram format \`${fmt}\`; body kept raw`, line: openLineNo });
+                        diags.push({ severity: "warning", code: "unknown-diagram-format", message: `no registered renderer for diagram format \`${fmt}\`; body kept raw`, line: openLineNo });
                     }
                 }
             }
@@ -445,7 +450,7 @@ function parseData(lines) {
 // resolving `other.geml#id` references.
 function gatherIds(source) {
     const ctx = { diags: [], ids: new Map(), refs: [], meta: new Map() };
-    scanBlocks(source.replace(/\r\n?/g, "\n").split("\n"), 0, ctx);
+    scanBlocks(normalizeSource(source).split("\n"), 0, ctx);
     return new Set(ctx.ids.keys());
 }
 // Pre-scan for `=== meta` blocks (at any fence depth) and merge their
@@ -477,14 +482,14 @@ function validateRefs(ctx, opts) {
             if (!ref.doc)
                 continue;
             if (!opts.resolveDoc) {
-                ctx.diags.push({ severity: "warning", message: `cross-document reference \`${ref.doc}${ref.anchor ? "#" + ref.anchor : ""}\` not checked (no document resolver)`, line: ref.line });
+                ctx.diags.push({ severity: "warning", code: "unchecked-cross-document-reference", message: `cross-document reference \`${ref.doc}${ref.anchor ? "#" + ref.anchor : ""}\` not checked (no document resolver)`, line: ref.line });
                 continue;
             }
             let ids = docIds.get(ref.doc);
             if (ids === undefined) {
                 const src = opts.resolveDoc(ref.doc);
                 if (src === null) {
-                    ctx.diags.push({ severity: "error", message: `cannot resolve document \`${ref.doc}\``, line: ref.line });
+                    ctx.diags.push({ severity: "error", code: "unresolvable-document", message: `cannot resolve document \`${ref.doc}\``, line: ref.line });
                     docIds.set(ref.doc, new Set());
                     continue;
                 }
@@ -492,14 +497,16 @@ function validateRefs(ctx, opts) {
                 docIds.set(ref.doc, ids);
             }
             if (ref.anchor !== undefined && !ids.has(ref.anchor)) {
-                ctx.diags.push({ severity: "error", message: `unresolved reference \`${ref.doc}#${ref.anchor}\``, line: ref.line });
+                ctx.diags.push({ severity: "error", code: "unresolved-cross-document-reference", message: `unresolved reference \`${ref.doc}#${ref.anchor}\``, line: ref.line });
             }
             continue;
         }
         // internal, autoref, footnote — anchor must be a known id in this document.
         if (ref.anchor !== undefined && !ctx.ids.has(ref.anchor)) {
-            const what = ref.kind === "footnote" ? `footnote \`[^${ref.anchor}]\`` : `reference \`#${ref.anchor}\``;
-            ctx.diags.push({ severity: "error", message: `unresolved ${what}`, line: ref.line });
+            const footnote = ref.kind === "footnote";
+            const what = footnote ? `footnote \`[^${ref.anchor}]\`` : `reference \`#${ref.anchor}\``;
+            const code = footnote ? "unresolved-footnote" : "unresolved-reference";
+            ctx.diags.push({ severity: "error", code, message: `unresolved ${what}`, line: ref.line });
         }
     }
 }
@@ -510,13 +517,15 @@ function resolveCharts(ctx) {
         const ref = typeof block.attrs["data"] === "string" ? block.attrs["data"] : "";
         const id = ref.replace(/^#/, "");
         if (id === "") {
-            ctx.diags.push({ severity: "error", message: "geml-chart: missing `data=#id`", line });
+            ctx.diags.push({ severity: "error", code: "chart-missing-data", message: "geml-chart: missing `data=#id`", line });
             continue;
         }
         const table = ctx.tables?.get(id);
         if (!table) {
-            const what = ctx.ids.has(id) ? `data target \`#${id}\` is not a table` : `unresolved reference \`#${id}\``;
-            ctx.diags.push({ severity: "error", message: `geml-chart: ${what}`, line });
+            const known = ctx.ids.has(id);
+            const what = known ? `data target \`#${id}\` is not a table` : `unresolved reference \`#${id}\``;
+            const code = known ? "chart-data-not-a-table" : "unresolved-reference";
+            ctx.diags.push({ severity: "error", code, message: `geml-chart: ${what}`, line });
             continue;
         }
         if (table.src !== undefined) {
@@ -533,7 +542,7 @@ function resolveCharts(ctx) {
     }
 }
 export function parse(source, opts = {}) {
-    const lines = source.replace(/\r\n?/g, "\n").split("\n");
+    const lines = normalizeSource(source).split("\n");
     const ctx = { diags: [], ids: new Map(), refs: [], meta: collectMeta(lines), resolveDoc: opts.resolveDoc };
     const children = scanBlocks(lines, 0, ctx);
     resolveCharts(ctx);
@@ -644,7 +653,7 @@ function collectSpans(lines, base, out, ctx, depth = 0) {
 // with the physical lines produced by splitLines(source).
 export function blockSpans(source) {
     const out = new Map();
-    const lines = source.replace(/\r\n?/g, "\n").split("\n");
+    const lines = normalizeSource(source).split("\n");
     // Inert context: heading auto-ids slug the interpolated text (parser parity);
     // its diagnostics are discarded — the span scan never reports.
     const ctx = { diags: [], ids: new Map(), refs: [], meta: collectMeta(lines) };
@@ -728,48 +737,50 @@ function parseStamp(s) {
     return new Date(Date.UTC(+y, +mo - 1, +d, +h, +mi, +se));
 }
 const VERSION = "1.0"; // GEML spec version this CLI targets
-const PARSER_VERSION = "1.4.2"; // reference implementation; keep in sync with package.json
-const USAGE = `geml — GEML reference CLI
-
-Usage:
-  geml <file.geml|-> [--to <fmt>] [--from <fmt>] [-o out]   transform a document (default: --to json)
-                                             <fmt>: json | html | md | geml
-                                               --to md    -> Markdown (lossy)
-                                               --to html  -> self-contained HTML
-                                               --to geml  -> canonical re-format
-                                               --to json  -> document-model JSON (default)
-                                             A Markdown input converts the other way:
-                                               geml notes.md            -> GEML
-                                             --from overrides the input format (any input):
-                                               geml notes.txt --from md    treat as Markdown
-                                               geml - --from md            read Markdown on stdin
-  geml get    <file.geml|-> [#id] [--json] [--head]   with #id: print that block
-                                             (a heading id = its whole section; --head = head line;
-                                             --json = model node). Without #id: list all addressable
-                                             ids (--json = array).
-  geml set    <file.geml|-> #id [--head|--body] [--in f[#src]|-] [-o f]   replace ONE block by id
-                                             (--in F takes F's block #id, F#src takes #src, else stdin raw;
-                                              default = whole block · --head = head line · --body = body)
-  geml add    <file.geml|-> (--append | --before #id | --after #id) [--in f[#src]|-] [-o f]   insert a fragment
-                                             (1+ blocks and/or prose; content keeps its own ids, a clash is refused)
-  geml delete <file.geml|-> #id [#id2 …] [-o f]   remove one or more blocks
-                                             (a missing id is skipped; a dangling reference is a warning, not a refusal)
-  geml rename <file.geml|-> #old #new [-o f]   rename an id and every reference to it (id-boundary safe)
-  geml revert <file.geml> #id [--rev <sel>] [--head]   undo one block to a past revision (splice / resurrect / remove)
-                                             (sel: -N | latest | id-prefix; default -1)
-  geml check  <file.geml|-> [--root d] [--json]   validate only: diagnostics + exit code
-                                             (--root widens cross-doc refs to dir d, e.g. the repo root)
-  geml history <commit|verify|show|restore|log> <file.geml> [...]   .gemlhistory version sidecar
-  geml codemap <build|verify|render|serve|refresh|find|mcp> [...]   code-graph toolkit (alias: codegraph)
-  geml --help | --version [--json]
-
-Use '-' as the file to read from stdin.
-Mutations (set/add/delete/rename) write the whole updated document in place for a
-file, or to stdout for '-' input; -o redirects it (-o - = stdout).
-Exit codes:
-  0 ok
-  1 document/operation error
-  2 command usage error.
+const PARSER_VERSION = "1.4.3"; // reference implementation; keep in sync with package.json
+const USAGE = `geml — GEML reference CLI
+
+Usage:
+  geml <file.geml|-> [--to <fmt>] [--from <fmt>] [-o out]   transform a document (default: --to json)
+                                             --to  <output>: json | html | md | geml
+                                               --to md    -> Markdown (lossy)
+                                               --to html  -> self-contained HTML
+                                               --to geml  -> canonical re-format
+                                               --to json  -> document-model JSON (default)
+                                             --from <input>: geml | md | json   (overrides extension; html is output-only)
+                                               geml notes.md                -> GEML   (md inferred from extension)
+                                               geml model.json --to geml    -> GEML   (round-trips a prior --to json)
+                                               geml - --from md             read Markdown on stdin
+  geml get    <file.geml|-> [#id] [--json] [--head]   with #id: print that block
+                                             (a heading id = its whole section; --head = head line;
+                                             --json = model node). Without #id: list all addressable
+                                             ids (--json = array).
+  geml set    <file.geml|-> #id [--head|--body] [--in f[#src]|-] [-o f]   replace ONE block by id
+                                             (--in F takes F's block #id, F#src takes #src, else stdin raw;
+                                              default = whole block · --head = head line · --body = body)
+  geml add    <file.geml|-> (--append | --before #id | --after #id) [--in f[#src]|-] [-o f]   insert a fragment
+                                             (1+ blocks and/or prose; content keeps its own ids, a clash is refused)
+  geml delete <file.geml|-> #id [#id2 …] [-o f]   remove one or more blocks
+                                             (a missing id is skipped; a dangling reference is a warning, not a refusal)
+  geml rename <file.geml|-> #old #new [-o f]   rename an id and every reference to it (id-boundary safe)
+  geml revert <file.geml> #id [--rev <sel>] [--head]   undo one block to a past revision (splice / resurrect / remove)
+                                             (sel: 0 | -N | id-prefix | changed; default -1)
+  geml check  <file.geml|-> [--root d] [--json]   validate only: diagnostics + exit code
+                                             (--root widens cross-doc refs to dir d, e.g. the repo root)
+  geml history <commit|verify|show|restore|log> <file.geml> [...]   .gemlhistory version sidecar
+  geml codemap <build|verify|render|serve|refresh|find|mcp> [...]   code-graph toolkit (alias: codegraph)
+  geml mcp    --workspace <dir> [--no-history]   serve document CRUD over MCP (stdio)
+                                             (9 tools: list/read/check/history + write/add/delete/rename/revert;
+                                              every write is validated before it reaches disk)
+  geml --help | --version [--json]
+
+Use '-' as the file to read from stdin.
+Mutations (set/add/delete/rename) write the whole updated document in place for a
+file, or to stdout for '-' input; -o redirects it (-o - = stdout).
+Exit codes:
+  0 ok
+  1 document/operation error
+  2 command usage error.
 `;
 // One-line usage for each subcommand — the single source for both the error
 // shown on misuse and the `<cmd> --help` text.
@@ -780,17 +791,32 @@ const SUBHELP = {
     delete: "usage: geml delete <file.geml|-> #id [#id2 …] [-o out.geml]  (remove one or more blocks; a missing id is skipped with a note, not an error; a reference left dangling is a warning, not a refusal — delete never fails on a live reference)",
     rename: "usage: geml rename <file.geml|-> #old #new [-o out.geml]  (rewrite an id's declaration AND every reference — [[#id]], [text](#id), chart data=#id, footnote [^id] — id-boundary safe, skipping raw block bodies; #new must be free; refused if it breaks the doc)",
     check: "usage: geml check <file.geml|-> [--root <dir>] [--json]  (--root: resolve cross-doc refs within <dir> instead of the file's own directory)",
-    revert: "usage: geml revert <file.geml> #id [--rev <sel>] [--changed] [--append|--before #x|--after #x] [--head] [--dry-run] [-o out]  (reconcile #id to a revision: splice / resurrect / remove; sel: -N | latest | id-prefix; default -1)",
+    revert: "usage: geml revert <file.geml> #id [--rev <sel>] [--append|--before #x|--after #x] [--head] [--dry-run] [-o out]  (reconcile #id to a revision: splice / resurrect / remove; sel: 0 | -N | id-prefix | changed; default -1)",
     history: "usage: geml history <commit|verify|show|restore|log> <file.geml> [...]",
-    codemap: `usage: geml codemap build  [--root <repo>]   # auto-detect languages, run the indexer(s), and merge into one codemap (--root defaults to the current directory)
-       geml codemap build  (--db <graph.db> | --adapter joern|scip --raw <in>)+ [--root <repo>] [--out .geml-code-graph] [--container module|dir|file] [--lang <JAVASRC|NEWC|…>] [--joern <path>] [--history [-m msg]]
-       geml codemap verify [dir]                 geml check + profile reference checks
-       geml codemap render [dir]                 every doc -> sibling .html (open index.html from disk)
-       geml codemap serve  [dir] [--port 8140] [--watch] [--background|--stop]   live viewer: pages render from .geml on request; --watch re-runs the recipe when sources change
-       geml codemap refresh [dir] [--force] [--commit] [--background|--hook]   re-run the recorded build recipe (_index/refresh.json); --commit lands it as its own commit
-       geml codemap find <name> [dir]            locate a symbol by substring name -> doc#id + src (stdout, no browser)
-       geml codemap mcp                          stdio MCP server (GEML_GRAPH_DIR or graph_dir arg)
+    codemap: `usage: geml codemap build  [--root <repo>]   # auto-detect languages, run the indexer(s), and merge into one codemap (--root defaults to the current directory)
+       geml codemap build  (--db <graph.db> | --adapter joern|scip --raw <in>)+ [--root <repo>] [--out .geml-code-graph] [--container module|dir|file] [--lang <JAVASRC|NEWC|…>] [--joern <path>] [--history [-m msg]]
+       geml codemap verify [dir]                 geml check + profile reference checks
+       geml codemap render [dir]                 every doc -> sibling .html (open index.html from disk)
+       geml codemap serve  [dir] [--port 8140] [--watch] [--background|--stop]   live viewer: pages render from .geml on request; --watch re-runs the recipe when sources change
+       geml codemap refresh [dir] [--force] [--commit] [--background|--hook]   re-run the recorded build recipe (_index/refresh.json); --commit lands it as its own commit
+       geml codemap find <name> [dir]            locate a symbol by substring name -> doc#id + src (stdout, no browser)
+       geml codemap mcp                          stdio MCP server (GEML_GRAPH_DIR or graph_dir arg)
        (<dir> for verify/render/serve/refresh/find defaults to ./.geml-code-graph; codegraph and code-graph are accepted as aliases of codemap)`,
+    mcp: `usage: geml mcp --workspace <dir> [--no-history]
+
+  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).
+  Nine tools: geml_list_ids · geml_read_block · geml_check · geml_history_log
+              geml_write_block · geml_add_block · geml_delete_block
+              geml_rename_id · geml_revert_block
+
+  --workspace <dir>   REQUIRED. Root holding the .geml documents. Every path a
+                      client names is confined here; a client cannot widen it.
+  --no-history        Skip the .gemlhistory commit taken before each write
+                      (default: commit, so geml_revert_block always has a
+                      revision to undo to).
+
+  Register with a client:
+    claude mcp add geml-docs -- geml mcp --workspace /abs/path/to/docs`,
 };
 // Set from argv at dispatch time; when true, errors are emitted as a JSON
 // envelope so an agent that standardizes on --json never has to parse text.
@@ -805,6 +831,19 @@ function fail(msg, code = 2) {
         console.error(`error: ${msg}`);
     process.exit(code);
 }
+// Refuse a mutation whose RESULT would be broken (the pre-write check every
+// mutation runs). Prose mode is the long-standing wording: the first error,
+// phrased by the call site. `--json` additionally carries the FULL diagnostic
+// list with the stable codes of spec Appendix A, so a programmatic caller —
+// `geml mcp` above all — reports what actually broke instead of re-parsing
+// English out of stderr.
+function refuseBroken(prose, errs) {
+    if (jsonMode) {
+        console.error(JSON.stringify({ error: prose, code: 1, diagnostics: errs }));
+        process.exit(1);
+    }
+    fail(prose, 1);
+}
 // Read a file, or stdin when the path is "-". On failure emit a clean error.
 function readInput(file) {
     try {
@@ -968,10 +1007,10 @@ function runHistory(args) {
             console.log(`restored ${file} to ${rev}`);
         }
         else if (sub === "log") {
-            // Newest-first, with the `--to` selector for each row in the first column
-            // (`latest` for the tip, then `-1`, `-2`, …) so the output is copy-paste.
+            // Newest-first, with the `--rev` selector for each row in the first column
+            // (`0` for the tip, then `-1`, `-2`, …) so the output is copy-paste.
             for (const r of listRevisions(historyPath)) {
-                const sel = r.current ? "latest" : `-${r.offset}`;
+                const sel = r.current ? "0" : `-${r.offset}`;
                 console.log(`${sel.padEnd(7)} ${r.id}  ${r.author ?? "-"}  ${r.summary ?? ""}`.replace(/\s+$/, ""));
             }
         }
@@ -994,21 +1033,24 @@ function runTransform(argv) {
     // silent fall-through to the default — flag() would return undefined and we
     // must not quietly ignore it.
     if (argv.includes("--from") && fromRaw === undefined)
-        fail("--from needs a format (geml | md)", 2);
+        fail("--from needs a format (geml | md | json)", 2);
     if (argv.includes("--to") && toRaw === undefined)
         fail("--to needs a format (json | html | md | geml)", 2);
     // Input format: an explicit --from wins (for any input, file or stdin), else
     // the file extension, else GEML (covers .geml, unknown extensions, and stdin).
     let inFmt;
     if (fromRaw !== undefined) {
-        if (fromRaw !== "geml" && fromRaw !== "md") {
-            fail(`--from: unknown input format '${fromRaw}' (want geml | md)`, 2);
+        if (fromRaw !== "geml" && fromRaw !== "md" && fromRaw !== "json") {
+            fail(`--from: unknown input format '${fromRaw}' (want geml | md | json)`, 2);
         }
         inFmt = fromRaw;
     }
     else if (/\.(md|markdown)$/i.test(file)) {
         inFmt = "md";
     }
+    else if (/\.json$/i.test(file)) {
+        inFmt = "json";
+    }
     else {
         inFmt = "geml";
     }
@@ -1021,7 +1063,7 @@ function runTransform(argv) {
         outFmt = toRaw;
     }
     else {
-        outFmt = inFmt === "md" ? "geml" : "json";
+        outFmt = inFmt === "geml" ? "json" : "geml"; // geml->json; md/json->geml
     }
     const src = readInput(file);
     // md -> geml is a direct projection, not a parse/serialize round-trip: emit
@@ -1037,7 +1079,10 @@ function runTransform(argv) {
     // project it to the target.
     let notes = [];
     let doc;
-    if (inFmt === "md") {
+    if (inFmt === "json") {
+        doc = loadModelJson(src, file); // the inverse of `--to json`
+    }
+    else if (inFmt === "md") {
         const conv = mdToGeml(src);
         notes = conv.notes;
         doc = parse(conv.geml, { resolveDoc: resolverFor(file) });
@@ -1076,6 +1121,28 @@ function runTransform(argv) {
     if (doc.diagnostics.some((d) => d.severity === "error"))
         process.exit(1);
 }
+// Load a document-model JSON (the exact output of `--to json`) back into a
+// Document, so `--from json --to geml` is the inverse of a prior `--to json`.
+// The model is trusted as-is — no re-parse — so a clean round-trip is byte-stable
+// with `--to geml`. Anything that is not a document model is refused, and any
+// carried diagnostics are preserved (so a broken doc's JSON stays flagged).
+function loadModelJson(src, file) {
+    let obj;
+    try {
+        obj = JSON.parse(src);
+    }
+    catch (e) {
+        fail(`--from json: ${file === "-" ? "stdin" : file} is not valid JSON (${e.message})`, 1);
+    }
+    const d = obj;
+    if (!d || typeof d !== "object" || d.kind !== "document" || !Array.isArray(d.children)) {
+        fail(`--from json: not a GEML document-model JSON (expected {"kind":"document","children":[…]})`, 1);
+    }
+    const doc = d;
+    if (!Array.isArray(doc.diagnostics))
+        doc.diagnostics = [];
+    return doc;
+}
 // Write to `-o out` (with a `wrote` note on stderr) or to stdout.
 function writeOut(text, out) {
     if (out) {
@@ -1412,7 +1479,7 @@ function insertFragment(source, lines, at, fragment, file) {
     const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
     if (errs.length) {
         const first = errs[0];
-        fail(`adding the content would break the document: ${first.message} (line ${first.line}); not written`, 1);
+        refuseBroken(`adding the content would break the document: ${first.message} (line ${first.line}); not written`, errs);
     }
     const now = new Set(reparsed.ids);
     const dropped = beforeIds.find((x) => !now.has(x));
@@ -1489,7 +1556,7 @@ function runRename(args) {
         const hp = historyPathFor(file);
         if (existsSync(hp)) {
             try {
-                if (blockSpans(resolveContent(hp, "latest").text).has(oldId)) {
+                if (blockSpans(resolveContent(hp, "0").text).has(oldId)) {
                     console.error(`warning: #${oldId} has history; revert across this rename is not tracked — see docs`);
                 }
             }
@@ -1501,7 +1568,7 @@ function runRename(args) {
     const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
     if (errs.length) {
         const e = errs[0];
-        fail(`rename would break the document: ${e.message} (line ${e.line}); not written`, 1);
+        refuseBroken(`rename would break the document: ${e.message} (line ${e.line}); not written`, errs);
     }
     if (!reparsed.ids.includes(newId))
         fail(`rename did not produce #${newId}; not written`, 1);
@@ -1663,7 +1730,7 @@ function spliceBlock(source, id, replacement, file, headOnly = false, guardCount
     const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
     if (errs.length) {
         const first = errs[0];
-        fail(`replacement would break the document: ${first.message} (line ${first.line}); not written`, 1);
+        refuseBroken(`replacement would break the document: ${first.message} (line ${first.line}); not written`, errs);
     }
     const now = new Set(reparsed.ids);
     if (!now.has(id))
@@ -1685,19 +1752,26 @@ function spliceBlock(source, id, replacement, file, headOnly = false, guardCount
     }
     return updated;
 }
-// `geml revert <file.geml> #id [--rev <sel>] [--changed] [--dry-run] [-o out] [--history PATH]`
+// `geml revert <file.geml> #id [--rev <sel>] [--dry-run] [-o out] [--history PATH]`
 // Restore ONE block to a past revision's version — a targeted, guarded splice
-// that leaves the rest of the document untouched. <sel> (default `-1`): `-N` (N
-// revisions back from current), `latest`, or an id prefix/suffix. `--changed`
-// skips revisions that never touched the block, landing on its previous
-// *distinct* version. `--dry-run` prints what would be spliced in, writing
-// nothing. Writes in place by default (revert is a mutation); `-o` redirects.
+// that leaves the rest of the document untouched. <sel> (default `-1`): `0` (the
+// tip), `-N` (N revisions back), an id prefix/suffix, or `changed` — a content
+// selector that skips revisions which never touched the block, landing on its
+// previous *distinct* version. `--dry-run` prints what would be spliced in,
+// writing nothing. Writes in place by default (revert is a mutation); `-o` redirects.
 function runRevert(args) {
-    const changed = args.includes("--changed");
     const dryRun = args.includes("--dry-run");
     const headOnly = args.includes("--head");
     const out = flag(args, "-o") ?? flag(args, "--out");
     const to = flag(args, "--rev") ?? "-1";
+    // `--rev changed` is a CONTENT selector, not a position: skip commits that
+    // never touched this block, landing on its previous *distinct* version. It is
+    // just a `--rev` value, so it cannot conflict with a positional `-N`.
+    const changed = to === "changed";
+    // The former standalone `--changed` flag is now this value; refuse the old
+    // spelling loudly rather than silently ignoring it (and reverting to -1).
+    if (args.includes("--changed"))
+        fail("--changed is now `--rev changed`", 2);
     const before = flag(args, "--before");
     const after = flag(args, "--after");
     const append = args.includes("--append");
@@ -1753,12 +1827,19 @@ function runRevert(args) {
     };
     // Reconcile #id between now and revision R across the four presence cells.
     if (curBlock === undefined && oldBlock === undefined) {
-        fail(`\`${id}\` exists in neither the document nor ${target.id} (try --changed)`, 1);
+        fail(`\`${id}\` exists in neither the document nor ${target.id} (try --rev changed)`, 1);
     }
     // both present -> SPLICE (undo set)
     if (curBlock !== undefined && oldBlock !== undefined) {
         if (oldBlock === curBlock) {
-            console.error(`#${id} is unchanged at ${target.id}; nothing to revert${changed ? "" : " (try --rev -2, or --changed)"}`);
+            console.error(`#${id} is unchanged at ${target.id}; nothing to revert${changed ? "" : " (try --rev -2, or --rev changed)"}`);
+            // A no-op still has to PRODUCE the document when an output destination was
+            // asked for: `-o` means "write the result somewhere", and the result of a
+            // no-op revert is the unchanged document. Returning silently here left
+            // `-o -` consumers with exit 0 and empty stdout, which reads as "success,
+            // and the document is now empty".
+            if (out !== undefined)
+                emit(source, `#${id} unchanged`);
             return;
         }
         if (dryRun) {
@@ -1824,7 +1905,7 @@ function runRevert(args) {
     const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
     if (errs.length) {
         const first = errs[0];
-        fail(`removing #${id} would break the document: ${first.message} (line ${first.line}); not written`, 1);
+        refuseBroken(`removing #${id} would break the document: ${first.message} (line ${first.line}); not written`, errs);
     }
     const now = new Set(reparsed.ids);
     const dropped = beforeIds.find((x) => x !== id && !now.has(x));
@@ -1893,6 +1974,15 @@ function runCodemap(args) {
     const r = spawnSync(process.execPath, [mod, ...args.slice(1)], { stdio: "inherit" });
     process.exit(r.status ?? 1);
 }
+// geml mcp: the document-CRUD MCP server. Runs as a child's MAIN module for the
+// same reason `codemap mcp` does — it owns stdin/stdout for the whole session
+// (the stdio transport), and dispatching by spawn keeps this module free of a
+// runtime import cycle (mcp.js imports the parser from here).
+function runMcp(args) {
+    const mod = join(dirname(fileURLToPath(import.meta.url)), "mcp.js");
+    const r = spawnSync(process.execPath, [mod, ...args], { stdio: "inherit" });
+    process.exit(r.status ?? 1);
+}
 // npm's unix bin shim is a symlink named plain `geml`, so detect "run as a
 // CLI" by resolving argv[1] to its real path, not by its spelling.
 const entry = (() => {
@@ -1962,6 +2052,9 @@ if (entry && (entry === fileURLToPath(import.meta.url) || entry.endsWith("geml.t
     else if (cmd === "codemap") {
         runCodemap(argv.slice(1));
     }
+    else if (cmd === "mcp") {
+        runMcp(argv.slice(1));
+    }
     else if (cmd !== "-" && !/[.\/\\]/.test(cmd)) {
         // A bare word that is neither a known command nor a path is almost always
         // a mistyped command — say so, don't try to read it as a file. (The

package/dist/history.d.ts

@@ -70,6 +70,16 @@ export declare function listRevisions(historyPath: string): RevisionInfo[];
 /** Resolve a revision selector to its id + reconstructed full text. Selectors:
  *  `-N` (N revisions back from current; `-0` is the tip), `latest`/`current`, or
  *  an unambiguous id prefix/suffix (the same forms `restore` accepts). */
+/** Resolve a revision selector to its id, for EVERY command that takes one.
+ *
+ *  There is exactly one selector grammar — `0` (the tip), `-N` (N revisions
+ *  back), or an unambiguous revision id (prefix, suffix, or exact) — and it is
+ *  the grammar `history log` prints in its first column, so its output is
+ *  copy-pasteable into `revert --rev`, `history show`, and `history restore`
+ *  alike. Keeping this in one function is what makes that true: it used to be
+ *  written twice, and the copy in `restore` never grew the `0`/`-N` arm, so the
+ *  selectors `history log` advertised were rejected by `history show`. */
+export declare function resolveRevision(h: History, selector: string): string;
 export declare function resolveContent(historyPath: string, selector: string): {
     id: string;
     text: string;