@geml/geml 1.0.0 → 1.3.2

package/dist/geml.js

@@ -8,19 +8,21 @@
 // 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).
-import { readFileSync, writeFileSync } from "node:fs";
-import { basename, dirname, resolve as resolvePath } from "node:path";
-import { commit, restore, verify } from "./history.js";
-import { renderHtml } from "./render.js";
+import { readFileSync, writeFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { commit, restore, verify, listRevisions, resolveContent, firstChangedContent } from "./history.js";
+import { renderHtml } from "./render-html.js";
 import { coerce, parseAttrs } from "./attrs.js";
-import { parseInline } from "./inline.js";
+import { META_REF_SRC, parseInline } from "./inline.js";
 import { parseTable } from "./table.js";
 import { buildChart } from "./chart.js";
 import { mdToGeml } from "./from-md.js";
 import { serialize } from "./serialize.js";
 import { gemlToMd } from "./to-md.js";
 export { mdToGeml } from "./from-md.js";
-export { renderHtml } from "./render.js";
+export { renderHtml } from "./render-html.js";
 export { serialize } from "./serialize.js";
 export { gemlToMd } from "./to-md.js";
 // Type registry: which body mode each typed block uses. Unknown types are a
@@ -32,18 +34,23 @@ const REGISTRY = {
     table: "raw", // structured table parsing lands in M3
     output: "raw", // captured result of a code block (stored, never executed)
     note: "flow",
-    aside: "flow",
+    text: "flow", // addressable prose container: an id/attrs for a run of flow, no callout chrome
     meta: "data",
 };
 // §7: built-in diagram renderer registry. Unknown formats are a warning (the
 // processor keeps the body raw rather than interpreting it).
-const DIAGRAM_RENDERERS = new Set(["mermaid", "graphviz", "dot", "d2", "plantuml", "geml-chart"]);
+const DIAGRAM_RENDERERS = new Set(["mermaid", "graphviz", "dot", "d2", "plantuml", "geml-chart", "geml-code-graph"]);
 // ---------------------------------------------------------------------------
 // Lexical helpers
 // ---------------------------------------------------------------------------
 const FENCE_OPEN = /^(={3,})[ \t]+([A-Za-z][A-Za-z0-9_-]*)[ \t]*(\{.*\})?[ \t]*$/;
 const HEADING = /^(#{1,6})[ \t]+(.*?)[ \t]*(\{[^}]*\})?[ \t]*$/;
 const LIST_ITEM = /^[ \t]*(?:[-*]|\d+\.)[ \t]+(.*)$/;
+// Maximum block/list nesting depth the recursive-descent scanner will build
+// before emitting a diagnostic instead of recursing further. Guards parse()
+// (scanBlocks / parseList) and, in step, the renderer against a deeply nested
+// document overflowing the call stack (DoS). 256 is far past any real document.
+const MAX_NESTING = 256;
 function isCloseFence(line, openLen) {
     const t = line.replace(/\s+$/, "");
     return /^=+$/.test(t) && t.length === openLen;
@@ -61,15 +68,67 @@ function slug(text) {
 // ---------------------------------------------------------------------------
 // §4: substitute `{{key}}` in flow text with the matching `=== meta` value.
 // An unknown key is a build error (single-source-of-truth, fail loudly).
+// The scan mirrors the §5.3(1) verbatim atoms: a `{{key}}` inside a code span
+// or inline math is left untouched (so GEML prose can document this very
+// syntax), and a backslash-escaped character can neither open a span nor a
+// `{{…}}` reference — `\{{key}}` renders as the literal text `{{key}}`.
+const META_REF = new RegExp(META_REF_SRC, "y");
 function interpolate(text, line, ctx) {
     if (!text.includes("{{"))
         return text;
-    return text.replace(/\{\{\s*([A-Za-z_][A-Za-z0-9_-]*)\s*\}\}/g, (full, key) => {
-        if (ctx.meta.has(key))
-            return ctx.meta.get(key);
-        ctx.diags.push({ severity: "error", message: `unknown metadata reference \`{{${key}}}\``, line });
-        return full;
-    });
+    let out = "";
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        if (c === "\\" && i + 1 < text.length) {
+            out += c + text[i + 1];
+            i += 2;
+            continue;
+        }
+        if (c === "`") {
+            let n = 0;
+            while (text[i + n] === "`")
+                n++;
+            const close = text.indexOf("`".repeat(n), i + n);
+            if (close >= 0) {
+                out += text.slice(i, close + n);
+                i = close + n;
+                continue;
+            }
+            out += text.slice(i, i + n); // unclosed run: literal, keep scanning
+            i += n;
+            continue;
+        }
+        if (c === "$") {
+            const close = text.indexOf("$", i + 1);
+            if (close > i + 1) {
+                out += text.slice(i, close + 1);
+                i = close + 1;
+                continue;
+            }
+            out += c;
+            i++;
+            continue;
+        }
+        if (c === "{" && text[i + 1] === "{") {
+            META_REF.lastIndex = i;
+            const m = META_REF.exec(text);
+            if (m) {
+                const key = m[1];
+                if (ctx.meta.has(key))
+                    out += ctx.meta.get(key);
+                else {
+                    ctx.diags.push({ severity: "error", message: `unknown metadata reference \`{{${key}}}\``, line });
+                    out += m[0];
+                }
+                i = META_REF.lastIndex;
+                continue;
+            }
+        }
+        out += c;
+        i++;
+    }
+    return out;
 }
 // Register a block id, flagging duplicates as errors (§4: ids unique per doc).
 function registerId(ctx, id, line) {
@@ -121,6 +180,7 @@ function parseList(lines, i, base, ctx) {
     const root = mkList(matchMarker(lines[i]));
     const stack = [{ list: root, indent: matchMarker(lines[i]).indent }];
     let prevBlank = false;
+    let tooDeep = false;
     while (i < lines.length) {
         if (lines[i].trim() === "") {
             prevBlank = true;
@@ -138,11 +198,28 @@ function parseList(lines, i, base, ctx) {
             const parent = top.list.items[top.list.items.length - 1];
             if (!parent)
                 break; // deeper indent with no parent item: defensive stop
-            cur = mkList(mk);
-            (parent.children ??= []).push(cur);
-            stack.push({ list: cur, indent: mk.indent });
+            if (stack.length >= MAX_NESTING) {
+                // Refuse to nest deeper than the cap: keep the item at the current level
+                // 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 });
+                    tooDeep = true;
+                }
+                cur = top.list;
+            }
+            else {
+                cur = mkList(mk);
+                (parent.children ??= []).push(cur);
+                stack.push({ list: cur, indent: mk.indent });
+            }
         }
         else {
+            // §5: a change of marker type (bullet ↔ ordered) at the same level ends
+            // this list; scanBlocks then opens a fresh one at this marker. Without it,
+            // `- a` then `1. b` would merge into one mis-typed list (CommonMark §5.3).
+            if (mk.ordered !== top.list.ordered)
+                break;
             cur = top.list;
         }
         if (prevBlank && cur.items.length > 0)
@@ -153,7 +230,7 @@ function parseList(lines, i, base, ctx) {
     }
     return { block: root, next: i };
 }
-function scanBlocks(lines, base, ctx) {
+function scanBlocks(lines, base, ctx, depth = 0) {
     const blocks = [];
     const diags = ctx.diags;
     let i = 0;
@@ -236,7 +313,16 @@ function scanBlocks(lines, base, ctx) {
                     ctx.refs.push({ kind: "internal", anchor: of.slice(1), line: openLineNo });
             }
             if (mode === "flow") {
-                block.children = scanBlocks(body, base + i + 1, ctx);
+                if (depth >= MAX_NESTING) {
+                    // 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 });
+                    block.raw = body;
+                }
+                else {
+                    block.children = scanBlocks(body, base + i + 1, ctx, depth + 1);
+                }
             }
             else if (mode === "data") {
                 block.data = parseData(body);
@@ -265,6 +351,21 @@ function scanBlocks(lines, base, ctx) {
                         }
                         (ctx.charts ??= []).push({ block, line: openLineNo });
                     }
+                    else if (fmt === "geml-code-graph") {
+                        // Code-graph embed (GEP-0003): the ONLY attribute is src=, pointing
+                        // at a codemap document; roots/depth come from that document's meta
+                        // ("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 });
+                        }
+                        else if (ctx.resolveDoc && ctx.resolveDoc(src) === null) {
+                            diags.push({ severity: "warning", 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 });
+                        }
+                    }
                     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 });
@@ -424,12 +525,182 @@ function resolveCharts(ctx) {
 }
 export function parse(source, opts = {}) {
     const lines = source.replace(/\r\n?/g, "\n").split("\n");
-    const ctx = { diags: [], ids: new Map(), refs: [], meta: collectMeta(lines) };
+    const ctx = { diags: [], ids: new Map(), refs: [], meta: collectMeta(lines), resolveDoc: opts.resolveDoc };
     const children = scanBlocks(lines, 0, ctx);
     resolveCharts(ctx);
     validateRefs(ctx, opts);
     return { kind: "document", children, ids: [...ctx.ids.keys()], diagnostics: ctx.diags };
 }
+// The id that a fence/heading line defines, matching how scanBlocks derives it
+// (parseAttrs for the attribute object; heading text slug when no explicit id).
+// The slug MUST come from the INTERPOLATED text — scanBlocks slugs after
+// interpolate(), so `# {{title}} Setup` registers the substituted slug; slugging
+// the raw text here would create a phantom id the parser never registered and
+// make the real one unaddressable. `ctx` is an inert context carrying the
+// document's meta (diagnostics are discarded — spans never report).
+function idOfHeading(braces, text, line, ctx) {
+    return (braces ? parseAttrs(braces).id : undefined) ?? slug(interpolate(text, line, ctx));
+}
+// The matching close of the fence opened at lines[i] (equal-length run, or the
+// labeled `=== #id` close when the block carries an id): the index just past
+// the close line, and whether one was found — an unterminated block runs to
+// the end of the scope.
+function fenceClose(lines, i, open) {
+    const openLen = open[1].length;
+    const id = open[3] ? parseAttrs(open[3]).id : undefined;
+    const labeled = id !== undefined ? new RegExp(`^={3,}[ \\t]+#${id}[ \\t]*$`) : null;
+    for (let j = i + 1; j < lines.length; j++) {
+        if (isCloseFence(lines[j], openLen) || (labeled && labeled.test(lines[j])))
+            return { end: j + 1, closed: true };
+    }
+    return { end: lines.length, closed: false };
+}
+// A heading's span covers its whole SECTION: the heading line through the line
+// just before the next heading of same-or-higher level (fewer-or-equal `#`) in
+// the current scope, or end-of-scope. Fenced blocks are skipped whole — a `#`
+// line inside a `=== code` body is content, never a boundary.
+function sectionEnd(lines, i, level) {
+    let j = i + 1;
+    while (j < lines.length) {
+        const open = FENCE_OPEN.exec(lines[j]);
+        if (open) {
+            j = fenceClose(lines, j, open).end;
+            continue;
+        }
+        const h = HEADING.exec(lines[j]);
+        if (h && h[1].length <= level)
+            return j;
+        j++;
+    }
+    return lines.length;
+}
+// Walk `lines` exactly as scanBlocks does — same fence close rules (equal-length
+// or labeled `=== #id`), same flow-only recursion via REGISTRY — recording the
+// source span of every addressable id (typed block, heading, footnote def).
+// First definition wins, mirroring ctx.ids (a duplicate id is a build error, so
+// `get`/`set` operate on the one the parser actually registered). `base` is the
+// absolute line offset of this slice within the whole document.
+function collectSpans(lines, base, out, ctx, depth = 0) {
+    const add = (id, start, end) => {
+        if (!out.has(id))
+            out.set(id, { start, end });
+    };
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.trim() === "") {
+            i++;
+            continue;
+        }
+        const fndef = /^\[\^([^\]]+)\]:[ \t]?(.*)$/.exec(line);
+        if (fndef) {
+            add(fndef[1].trim(), base + i, base + i + 1);
+            i++;
+            continue;
+        }
+        if (/^[ \t]*%%/.test(line)) {
+            i++;
+            continue;
+        } // hidden line: no id
+        const open = FENCE_OPEN.exec(line);
+        if (open) {
+            const type = open[2];
+            const id = open[3] ? parseAttrs(open[3]).id : undefined;
+            const { end, closed } = fenceClose(lines, i, open);
+            if (id !== undefined)
+                add(id, base + i, base + end);
+            // Only a flow body is scanned for nested blocks (raw/data bodies are
+            // opaque), so an id inside a `code` body is *not* addressable — exactly
+            // the parser's contract.
+            if ((REGISTRY[type] ?? "raw") === "flow" && depth < MAX_NESTING) {
+                collectSpans(lines.slice(i + 1, closed ? end - 1 : end), base + i + 1, out, ctx, depth + 1);
+            }
+            i = end;
+            continue;
+        }
+        const h = HEADING.exec(line);
+        if (h) {
+            // Section span (heading through its prose and nested blocks). The walk
+            // still advances one line at a time so every nested id inside the
+            // section registers its own span — spans intentionally OVERLAP: #sec
+            // contains #code, and each remains addressable on its own.
+            add(idOfHeading(h[3], h[2], base + i + 1, ctx), base + i, base + sectionEnd(lines, i, h[1].length));
+            i++;
+            continue;
+        }
+        i++;
+    }
+}
+// Map every addressable id in `source` to its source span. Line indices align
+// 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");
+    // 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) };
+    collectSpans(lines, 0, out, ctx);
+    return out;
+}
+// Split into physical lines while *keeping* each line's terminator, so
+// join("") is byte-exact and slicing by span never rewrites line endings.
+// A line ends at `\n` or at a LONE `\r` (old-Mac style) — the same boundaries
+// the span scan's `\r\n?` -> `\n` normalization sees, so span indices always
+// address the same lines the parser counted.
+function splitLines(source) {
+    return source.split(/(?<=\n|\r(?!\n))/);
+}
+// `--head`: narrow any id's span to its HEAD line — the single declaring line
+// (a heading's `# … {#id}` line, a typed block's opening fence, a footnote's
+// `[^id]:` line). The head is by construction the FIRST line of the span, so
+// the narrowing is parse-free and needs no type check. Main use: `set --head`
+// edits a block's attributes (caption/compute/lang/…) without re-sending its
+// body, or renames a heading without rewriting its section.
+function narrowToHead(span) {
+    return { start: span.start, end: span.start + 1 };
+}
+// Depth-first search for the document-model node carrying `id`, descending into
+// flow-block children (and list-item children) so a nested id is found too.
+// Returns the containing sibling array and index, not just the node: the model
+// is FLAT — a heading does not own its section; the section's prose and blocks
+// are its FOLLOWING SIBLINGS — so a section consumer needs the array.
+function findBlockSite(blocks, id) {
+    for (let i = 0; i < blocks.length; i++) {
+        const b = blocks[i];
+        if ((b.kind === "heading" || b.kind === "block") && b.id === id)
+            return { siblings: blocks, index: i };
+        if (b.kind === "block" && b.children) {
+            const hit = findBlockSite(b.children, id);
+            if (hit)
+                return hit;
+        }
+        if (b.kind === "list") {
+            for (const it of b.items) {
+                if (it.children) {
+                    const hit = findBlockSite(it.children, id);
+                    if (hit)
+                        return hit;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+// Model-side section boundary: within one sibling array, the section opened by
+// the heading at index k runs to the next sibling heading of same-or-higher
+// level, or the array end. This is the SAME rule sectionEnd() applies to raw
+// source lines (where skipping fenced bodies makes "next heading" well-defined)
+// — the two sides must stay in lockstep; the get-set suite pins their parity
+// (ids covered by the raw slice == ids covered by the --json envelope).
+function sectionEndIndex(siblings, k) {
+    const level = siblings[k].level;
+    for (let m = k + 1; m < siblings.length; m++) {
+        const b = siblings[m];
+        if (b.kind === "heading" && b.level <= level)
+            return m;
+    }
+    return siblings.length;
+}
 // ---------------------------------------------------------------------------
 // CLI
 // ---------------------------------------------------------------------------
@@ -447,42 +718,66 @@ function parseStamp(s) {
     const [, y, mo, d, h, mi, se] = m;
     return new Date(Date.UTC(+y, +mo - 1, +d, +h, +mi, +se));
 }
-const VERSION = "1.0-draft"; // GEML spec version this CLI targets
-const PARSER_VERSION = "1.0.0"; // reference implementation; keep in sync with package.json
-const USAGE = `geml — GEML reference CLI
-
-Usage:
-  geml <file.geml|->                         parse -> document-model JSON (stdout)
-  geml check <file.geml|-> [--json]          validate only: diagnostics + exit code
-  geml render <file.geml|-> [-o out.html]    render to one self-contained HTML file
-  geml fmt <file.geml|-> [-o out.geml]       re-serialize to canonical GEML
-  geml convert <file.md|-> [-o out.geml]     Markdown -> GEML
-  geml export <file.geml|-> [-o out.md]      GEML -> Markdown (lossy)
-  geml history <commit|verify|show|restore> <file.geml> [...]
-  geml --help | --version [--json]
-
-Use '-' as the file to read from stdin.
-Exit codes: 0 ok · 1 document/operation error · 2 usage error.`;
+const VERSION = "1.0"; // GEML spec version this CLI targets
+const PARSER_VERSION = "1.3.2"; // reference implementation; keep in sync with package.json
+const USAGE = `geml — GEML reference CLI
+
+Usage:
+  geml <file.geml|->                         parse -> document-model JSON (stdout)
+  geml get <file.geml|-> #id [--json][--head]  print ONE block by id (a heading id = its section;
+                                             --head narrows any id to its head line; --json = model node)
+  geml set <file.geml|-> #id [--from f][-o f][--head] replace ONE block by id (new content: --from/stdin)
+  geml revert <file.geml> #id [--to <sel>][--head] restore ONE block to a past revision (sel: -N|latest|id)
+  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 render <file.geml|-> [-o out.html]    render to one self-contained HTML file
+  geml fmt <file.geml|-> [-o out.geml]       re-serialize to canonical GEML
+  geml convert <file.md|-> [-o out.geml]     Markdown -> GEML
+  geml export <file.geml|-> [-o out.md]      GEML -> Markdown (lossy)
+  geml history <commit|verify|show|restore|log> <file.geml> [...]
+  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.
+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.
 const SUBHELP = {
-    check: "usage: geml check <file.geml|-> [--json]",
+    get: "usage: geml get <file.geml|-> #id [--json] [--head]  (a heading id = its whole section; --head narrows any id to its head line)",
+    set: "usage: geml set <file.geml|-> #id [--from FILE] [-o out.geml] [--head]",
+    check: "usage: geml check <file.geml|-> [--root <dir>] [--json]  (--root: resolve cross-doc refs within <dir> instead of the file's own directory)",
     render: "usage: geml render <file.geml|-> [-o out.html]",
     convert: "usage: geml convert <file.md|-> [-o out.geml]",
     export: "usage: geml export <file.geml|-> [-o out.md]",
     fmt: "usage: geml fmt <file.geml|-> [-o out.geml]",
-    history: "usage: geml history <commit|verify|show|restore> <file.geml> [...]",
+    revert: "usage: geml revert <file.geml> #id [--to <sel>] [--changed] [--dry-run] [-o out] [--head]  (sel: -N | latest | id-prefix; 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)
+       (<dir> for verify/render/serve/refresh/find defaults to ./.geml-code-graph; codegraph and code-graph are accepted as aliases of codemap)`,
 };
 // 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.
 let jsonMode = false;
-// Clean one-line error + non-zero exit — never a raw Node stack trace.
-function fail(msg) {
+// Clean one-line error + non-zero exit — never a raw Node stack trace. `code`
+// is the process exit status: 2 for a usage error (the default), 1 for a
+// document/operation error. `--json` wraps it in the same {error, code} envelope.
+function fail(msg, code = 2) {
     if (jsonMode)
-        console.error(JSON.stringify({ error: msg, code: 2 }));
+        console.error(JSON.stringify({ error: msg, code }));
     else
         console.error(`error: ${msg}`);
-    process.exit(2);
+    process.exit(code);
 }
 // Read a file, or stdin when the path is "-". On failure emit a clean error.
 function readInput(file) {
@@ -493,12 +788,66 @@ function readInput(file) {
         fail(file === "-" ? "cannot read stdin" : `cannot read ${file}`);
     }
 }
-// A cross-document resolver rooted at the input's directory (cwd for stdin).
-function resolverFor(file) {
-    const baseDir = file === "-" ? "." : dirname(file);
+// A cross-document resolver rooted at the input's directory (cwd for stdin),
+// CONFINED to that directory's subtree. A reference that resolves outside the
+// base — via a `..` escape, an absolute path, or (on Windows) a different drive
+// — is refused (returns null, i.e. an unresolvable ref) so a crafted document
+// cannot turn `geml check`/parse into an arbitrary local-file read oracle. §8.
+//
+// A purely LEXICAL check is not enough: a symlink that sits lexically inside the
+// subtree but points to `../../outside.geml` passes `path.relative` yet reads an
+// external target. So after the cheap lexical gate we resolve BOTH the base and
+// the target through `realpathSync` (following every symlink component) and
+// re-check that the REAL target still lies within the REAL base subtree before
+// reading. A target that does not exist makes `realpathSync` throw — handled as
+// an ordinary unresolvable ref (null), never a crash.
+//
+// `root` (CLI `--root`, an explicit per-invocation user grant — never
+// document-controlled) widens the confinement base from the input's own
+// directory to an ancestor the user names, so repo-relative `../` references
+// between sibling directories can be checked. It moves WHERE the boundary
+// stands, never whether it is enforced: both gates below run against the
+// widened base, so escapes past the root are refused exactly as above. The
+// viewer/web surfaces never pass a root — their boundary is unchanged.
+function resolverFor(file, root) {
+    const dirAbs = resolvePath(file === "-" ? "." : dirname(file));
+    const baseAbs = root === undefined ? dirAbs : resolvePath(root);
+    // Canonicalise the base once. If the base itself cannot be realpath'd, no
+    // cross-doc ref can be safely confined — resolve nothing.
+    let realBase = null;
+    try {
+        realBase = realpathSync(baseAbs);
+    }
+    catch {
+        realBase = null;
+    }
+    const outside = (from, to) => {
+        const rel = relative(from, to);
+        return rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel);
+    };
     return (d) => {
+        if (realBase === null)
+            return null;
+        // References resolve FROM the document's own directory; the gates below
+        // confine them to the (possibly widened) base.
+        const targetAbs = resolvePath(dirAbs, d);
+        // Cheap lexical gate: reject an obvious `..`/absolute/other-drive escape
+        // before touching the filesystem.
+        if (outside(baseAbs, targetAbs))
+            return null;
+        // Real (symlink-resolved) gate: a symlink pointing out of the subtree
+        // resolves to a real path outside `realBase` and is refused here.
+        let realTarget;
+        try {
+            realTarget = realpathSync(targetAbs);
+        }
+        catch {
+            return null;
+        }
+        if (outside(realBase, realTarget))
+            return null;
         try {
-            return readFileSync(resolvePath(baseDir, d), "utf8");
+            return readFileSync(realTarget, "utf8");
         }
         catch {
             return null;
@@ -509,10 +858,22 @@ function resolverFor(file) {
 // dump (cheap for agents). `--json` prints the diagnostics array for machines.
 function runCheck(args) {
     const json = args.includes("--json");
-    const file = args.find((a) => a === "-" || !a.startsWith("-"));
+    const root = flag(args, "--root");
+    const file = args.find((a) => a === "-" || (!a.startsWith("-") && a !== root));
     if (!file)
         fail(SUBHELP.check);
-    const doc = parse(readInput(file), { resolveDoc: resolverFor(file) });
+    // A mistyped --root must be a usage error (exit 2), not a wall of misleading
+    // "cannot resolve document" errors from a resolver confined to nothing.
+    if (root !== undefined) {
+        let isDir = false;
+        try {
+            isDir = statSync(root).isDirectory();
+        }
+        catch { /* missing -> not a dir */ }
+        if (!isDir)
+            fail(`--root ${root} is not a directory`);
+    }
+    const doc = parse(readInput(file), { resolveDoc: resolverFor(file, root) });
     if (json) {
         console.log(JSON.stringify(doc.diagnostics, null, 2));
     }
@@ -580,6 +941,14 @@ function runHistory(args) {
             restore({ historyPath, gemlPath: file, revision: rev, write: true, force: args.includes("--force") });
             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.
+            for (const r of listRevisions(historyPath)) {
+                const sel = r.current ? "latest" : `-${r.offset}`;
+                console.log(`${sel.padEnd(7)} ${r.id}  ${r.author ?? "-"}  ${r.summary ?? ""}`.replace(/\s+$/, ""));
+            }
+        }
         else {
             fail(`unknown history subcommand: ${sub}. Run 'geml --help'.`);
         }
@@ -638,7 +1007,12 @@ function runRender(args) {
     if (!file)
         fail(SUBHELP.render);
     const doc = parse(readInput(file), { resolveDoc: resolverFor(file) });
-    const html = renderHtml(doc, { source: file === "-" ? "stdin" : basename(file) });
+    const html = renderHtml(doc, {
+        source: file === "-" ? "stdin" : basename(file),
+        // geml-code-graph embeds load + parse sibling codemap documents on demand.
+        loadDoc: resolverFor(file),
+        parseDoc: (s) => parse(s),
+    });
     if (out) {
         writeFileSync(out, html);
         console.error(`wrote ${out}`);
@@ -673,10 +1047,272 @@ function runFmt(args) {
     if (doc.diagnostics.some((d) => d.severity === "error"))
         process.exit(1);
 }
-const entry = process.argv[1] ?? "";
-if (entry.endsWith("geml.js") || entry.endsWith("geml.ts")) {
+// Positional args (a file, an id) are the non-flag tokens that aren't the value
+// of a value-taking flag. `-` (stdin) is a positional, not a flag. An id may be
+// written `#id` or `id`; a leading `-` never begins an id, so this stays
+// unambiguous. `valued` lists the flags that consume the following token.
+function positionals(args, valued) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (valued.includes(a)) {
+            i++;
+            continue;
+        } // skip the flag *and* its value
+        if (a === "-") {
+            out.push(a);
+            continue;
+        }
+        if (a.startsWith("-"))
+            continue; // a bare flag (e.g. --json)
+        out.push(a);
+    }
+    return out;
+}
+// `geml get <file.geml|-> #id [--json]` — print ONE block, addressed by id,
+// without loading the rest of the document into context. Default output is the
+// block's exact source bytes: a typed block's full `=== … ===` span, a
+// footnote's line, or — for a heading — its whole SECTION (heading line through
+// the line before the next same-or-higher heading). `--json` covers the same
+// content: a block/footnote id prints its document-model node; a heading id
+// prints a section envelope `{kind:"section", id, level, blocks:[heading,
+// …siblings up to the boundary]}`.
+function runGet(args) {
+    const json = args.includes("--json");
+    const headOnly = args.includes("--head");
+    const [file, rawId] = positionals(args, []);
+    if (!file || !rawId)
+        fail(SUBHELP.get);
+    const id = rawId.replace(/^#/, "");
+    const source = readInput(file);
+    if (json) {
+        // The model node(s) — same shapes `geml <file>` emits. Parsing is needed
+        // to resolve the tree (and nested-block ids), but only the target prints.
+        const doc = parse(source, { resolveDoc: resolverFor(file) });
+        const site = findBlockSite(doc.children, id);
+        if (!site)
+            fail(`no block with id \`${id}\``, 1);
+        const block = site.siblings[site.index];
+        // `--head` on a heading suppresses the section envelope (the lone heading
+        // node IS the head). On a block/footnote id there is nothing finer than
+        // the single node — the model has no sub-node for "just the fence line" —
+        // so --head refines only the RAW output there.
+        if (block.kind === "heading" && !headOnly) {
+            // A heading id addresses its SECTION, so `--json` covers the same
+            // content as the raw span: a self-describing envelope whose blocks[0]
+            // is the heading node followed by its siblings up to the boundary.
+            // `kind: "section"` lets a consumer branch — a block/footnote id still
+            // yields the single model node (the model itself stays flat).
+            const end = sectionEndIndex(site.siblings, site.index);
+            console.log(JSON.stringify({ kind: "section", id: block.id, level: block.level, blocks: site.siblings.slice(site.index, end) }, null, 2));
+            return;
+        }
+        console.log(JSON.stringify(block, null, 2));
+        return;
+    }
+    // Raw: slice the source span byte-for-byte. No parse required, so `get` still
+    // returns the exact bytes even if the document has diagnostics elsewhere.
+    const found = blockSpans(source).get(id);
+    if (!found)
+        fail(`no block with id \`${id}\``, 1);
+    const span = headOnly ? narrowToHead(found) : found;
+    process.stdout.write(splitLines(source).slice(span.start, span.end).join(""));
+}
+// `geml set <file.geml|-> #id [--from FILE] [-o out]` — replace ONLY that
+// block's source span with new content (from --from or stdin), preserving every
+// other byte. Prints the full updated document, or writes in place with -o. The
+// splice is re-parsed and rejected if it broke the doc: `set` never writes a
+// corrupt file.
+function runSet(args) {
+    const out = flag(args, "-o") ?? flag(args, "--out");
+    const from = flag(args, "--from");
+    const headOnly = args.includes("--head");
+    const [file, rawId] = positionals(args, ["-o", "--out", "--from"]);
+    if (!file || !rawId)
+        fail(SUBHELP.set);
+    const id = rawId.replace(/^#/, "");
+    // Both the document and the replacement can't come from stdin. Reject that up
+    // front — before consuming stdin — so the document read below is unambiguous.
+    if (file === "-" && from === undefined) {
+        fail("reading the document from stdin needs --from for the new content", 2);
+    }
+    const source = readInput(file);
+    // New content: an explicit --from file, else stdin.
+    let replacement;
+    if (from !== undefined) {
+        replacement = readInput(from);
+    }
+    else {
+        replacement = readInput("-");
+        if (replacement === "")
+            fail("no replacement content (use --from FILE or pipe it on stdin)", 1);
+    }
+    const updated = spliceBlock(source, id, replacement, file, headOnly);
+    if (out) {
+        writeFileSync(out, updated);
+        console.error(`wrote ${out}`);
+    }
+    else
+        process.stdout.write(updated);
+}
+// Replace block #id's source span in `source` with `replacement`, preserving
+// every other byte, and GUARD the result: the re-parse must be error-free, #id
+// must survive, and no other pre-existing id may vanish (a malformed replacement
+// can silently swallow a neighbour). Returns the updated document text; on any
+// violation it calls fail() and never returns a corrupt document. Shared by
+// `set` and `revert`.
+function spliceBlock(source, id, replacement, file, headOnly = false) {
+    const found = blockSpans(source).get(id);
+    if (!found)
+        fail(`no block with id \`${id}\``, 1);
+    const beforeIds = parse(source, { resolveDoc: resolverFor(file) }).ids;
+    // Keep the bytes before and after the target span exactly; give the new block
+    // a single trailing newline so the following block still starts on its own
+    // line (unless it is the file's last line, which may legitimately lack one).
+    const orig = splitLines(source);
+    // `--head`: splice only the id's head line; everything below stays
+    // byte-identical. The guard below still applies — the replacement must
+    // re-declare `{#id}` and, for a typed block, keep the fence pairing intact
+    // (an opening line that no longer matches the untouched close fence breaks
+    // the re-parse), or the splice is refused.
+    const span = headOnly ? narrowToHead(found) : found;
+    const before = orig.slice(0, span.start);
+    const after = orig.slice(span.end);
+    let inject = replacement.replace(/\r\n?/g, "\n");
+    const lastLine = span.end >= orig.length;
+    if (!inject.endsWith("\n") && !lastLine)
+        inject += "\n";
+    const updated = before.join("") + inject + after.join("");
+    // Re-parse and refuse a broken result. A parse error or a duplicate id both
+    // surface as error diagnostics (registerId flags dups); one check covers both.
+    // Then require the target id to survive, and — because a malformed replacement
+    // can swallow a neighbour — that every other pre-existing id survives too.
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    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);
+    }
+    const now = new Set(reparsed.ids);
+    if (!now.has(id))
+        fail(`replacement removes id \`${id}\`; not written`, 1);
+    const dropped = beforeIds.find((x) => x !== id && !now.has(x));
+    if (dropped !== undefined) {
+        fail(`replacement would drop block \`#${dropped}\` (malformed content?); not written`, 1);
+    }
+    return updated;
+}
+// `geml revert <file.geml> #id [--to <sel>] [--changed] [--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.
+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, "--to") ?? "-1";
+    const [file, rawId] = positionals(args, ["--to", "--history", "-o", "--out"]);
+    if (!file || !rawId)
+        fail(SUBHELP.revert);
+    if (file === "-")
+        fail("revert needs a real file (it reads that file's .gemlhistory)", 2);
+    const id = rawId.replace(/^#/, "");
+    const historyPath = flag(args, "--history") ?? historyPathFor(file);
+    const source = readInput(file);
+    const found = blockSpans(source).get(id);
+    if (!found)
+        fail(`no block with id \`${id}\` in ${file}`, 1);
+    const curSpan = headOnly ? narrowToHead(found) : found;
+    const curBlock = splitLines(source).slice(curSpan.start, curSpan.end).join("");
+    // Extract block #id's source from a reconstructed revision (undefined if the
+    // block did not exist there). Under `--head`, extract only the head line.
+    const pick = (text) => {
+        const s = blockSpans(text).get(id);
+        if (!s)
+            return undefined;
+        const span = headOnly ? narrowToHead(s) : s;
+        return splitLines(text).slice(span.start, span.end).join("");
+    };
+    // Resolve the source revision, formatting any history-layer error cleanly.
+    const target = (() => {
+        try {
+            if (changed) {
+                const found = firstChangedContent(historyPath, curBlock, pick);
+                if (!found)
+                    fail(`no earlier revision changes \`${id}\``, 1);
+                return found;
+            }
+            return resolveContent(historyPath, to);
+        }
+        catch (e) {
+            fail(historyError(e, file, historyPath), 1);
+        }
+    })();
+    const oldBlock = pick(target.text);
+    if (oldBlock === undefined)
+        fail(`block \`${id}\` does not exist at revision ${target.id}`, 1);
+    if (oldBlock === curBlock) {
+        console.error(`#${id} is unchanged at ${target.id}; nothing to revert${changed ? "" : " (try --to -2, or --changed)"}`);
+        return;
+    }
+    if (dryRun) {
+        console.error(`would revert #${id} to ${target.id}:`);
+        process.stdout.write(oldBlock.endsWith("\n") ? oldBlock : oldBlock + "\n");
+        return;
+    }
+    const updated = spliceBlock(source, id, oldBlock, file, headOnly);
+    const dest = out ?? file;
+    writeFileSync(dest, updated);
+    console.error(`reverted #${id} to ${target.id}${dest === file ? "" : ` -> ${dest}`}`);
+}
+// geml codemap <sub>: the code-graph toolkit ships as plain scripts in the
+// package's codemap/ directory (they are argv-driven programs, some
+// long-running like `serve`) — dispatch = run the script in a child node
+// with the remaining arguments, propagating the exit code.
+function runCodemap(args) {
+    const scripts = {
+        build: "build.mjs",
+        verify: "verify.mjs",
+        render: "render-all.mjs",
+        serve: "serve.mjs",
+        refresh: "refresh.mjs",
+        find: "find.mjs",
+        mcp: "mcp-server.mjs",
+    };
+    const sub = args[0] ?? "";
+    const script = scripts[sub];
+    if (!script)
+        fail(`unknown codemap subcommand '${sub}'.\n${SUBHELP.codemap}`);
+    const mod = join(dirname(fileURLToPath(import.meta.url)), "..", "codemap", script);
+    const r = spawnSync(process.execPath, [mod, ...args.slice(1)], { 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 = (() => {
+    const argv1 = process.argv[1];
+    if (!argv1)
+        return "";
+    try {
+        return realpathSync(argv1);
+    }
+    catch {
+        return argv1;
+    }
+})();
+// `entry` must be non-empty: in a browser bundle both sides degenerate to ""
+// (esbuild defines process.argv=[] and import.meta.url="", and the node-stub's
+// fileURLToPath is String()), which would run the CLI at import time and crash
+// the page. A real CLI invocation always has argv[1].
+if (entry && (entry === fileURLToPath(import.meta.url) || entry.endsWith("geml.ts"))) {
     const argv = process.argv.slice(2);
-    const cmd = argv[0];
+    // The on-disk artifact is `.geml-code-graph/`, so people reconstruct the
+    // command from the directory name — accept those spellings as `codemap`.
+    const cmd = argv[0] === "codegraph" || argv[0] === "code-graph" ? "codemap" : argv[0];
     jsonMode = argv.includes("--json");
     const rest = argv.slice(1);
     if (cmd === "--help" || cmd === "-h") {
@@ -697,6 +1333,15 @@ if (entry.endsWith("geml.js") || entry.endsWith("geml.ts")) {
         // stdout, exit 0 — never the `error:`-prefixed exit-2 path.
         console.log(SUBHELP[cmd]);
     }
+    else if (cmd === "get") {
+        runGet(argv.slice(1));
+    }
+    else if (cmd === "set") {
+        runSet(argv.slice(1));
+    }
+    else if (cmd === "revert") {
+        runRevert(argv.slice(1));
+    }
     else if (cmd === "history") {
         runHistory(argv.slice(1));
     }
@@ -715,6 +1360,9 @@ if (entry.endsWith("geml.js") || entry.endsWith("geml.ts")) {
     else if (cmd === "check") {
         runCheck(argv.slice(1));
     }
+    else if (cmd === "codemap") {
+        runCodemap(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.