@geml/geml 1.7.1 → 1.7.3

package/README.md

@@ -24,7 +24,8 @@ print("hi")
 - **Addressable** — every block can be named: an `#id`, or a content address for
   the ones nobody named; `geml get` / `geml set '<selector>'`
   read or patch one section without re-emitting the whole file (on this repo's
-  own spec, ~**66× less context** than shipping the whole document).
+  own spec, ~**120× less context** than shipping the whole document — the block
+  is ~590 chars whatever the document grows to).
 - **Verifiable** — references are checked at build time (a dangling `#id` is an
   error, not a silent dead link), and the parser emits a document-model JSON
   with a `diagnostics` array, so agents and CI get a structured pass/fail signal.
@@ -96,15 +97,20 @@ Every command reads a file path, or `-` for stdin. Exit codes: `0` ok ·
 ```sh
 geml doc.geml                       # document-model JSON (default --to json)
 geml doc.geml --to md|html|geml     # convert; geml notes.md -> GEML
+geml list   doc.geml                # CALL FIRST: every block, its address, kind, line range
+geml find   "text" doc.geml|dir     # search block CONTENT -> file<TAB>address; exit 1 = no hit
 geml get    doc.geml ['<selector>'] # list addressable blocks, or print what the selector matches
-geml set    doc.geml '<selector>' [--head|--body] [--in F[#src]]   # replace ONE block's content
+geml get    doc.geml '#sec' --intro # a section cuts three ways: --head | --intro | --body
+geml set    doc.geml '<selector>' [--head|--intro|--body] [--in F[#src]]   # replace ONE block's content
+geml replace doc.geml OLD NEW [--within '<selector>']   # EXPERIMENTAL: literal swap, checked and reported
 geml add    doc.geml (--append|--before #id|--after #id) [--in F[#src]]   # insert a fragment
 geml delete doc.geml '#id' ['#id2' …]     # remove one or more blocks
 geml rename doc.geml '#old' '#new'        # rename an id + every reference to it
 geml revert doc.geml '#id' [--rev -1]     # undo a block: splice / resurrect / remove
 geml check  doc.geml [--root <dir>]       # validate only: diagnostics + exit code (--json for the array)
 geml history <save|get|restore|verify> doc.geml [...]   # .gemlhistory version sidecar (get = list revisions, or print one)
-geml codemap <build|verify|render|serve|refresh|find|mcp>      # your codebase's call graph as GEML docs
+geml codemap <build|verify|render|serve|refresh|find>   # your codebase's call graph as GEML docs
+geml mcp    --root <dir> [--graph <dir>]  # serve documents (+ the code graph) over MCP
 geml --help | --version             # --version --json prints {"parser","spec"}
 ```
 
@@ -126,9 +132,31 @@ The agent loop: `geml get` a block → `set`/`add`/`delete`/`rename` it →
 
 `get` answers with N contents when N match (document order, count on stderr);
 `set` writes ONE block, so a selector matching several is refused (exit 2) with
-the unique address of each candidate. `--head` is the head line, `--body` the
-body; both round-trip — `geml get f X --body | geml set f X --body` leaves the
-file byte-identical.
+the unique address of each candidate. A section cuts three ways: `--head` is the
+heading line, `--intro` its opening region — everything under it up to its first
+subheading — and `--body` everything under it, so `--body` always contains
+`--intro`, and equals it when the section has no subheading. All three
+round-trip — `geml get f X --body | geml set f X --body` leaves the file
+byte-identical — and `--intro` is how a section's opening is edited without
+pulling its subsections into context. A block has no intro; asking for one is a
+usage error rather than a quiet fall back to the body.
+
+`replace` is the cheap path when the exact old text is already known and nothing
+needs reading — a version string in six places, a term renamed. It is the one
+operation where GEML can beat `sed` outright rather than imitate it: the same
+two short strings, but the result is re-parsed before it lands, the blocks it
+touched are named back to you, and it is in `.gemlhistory` to revert. It swaps a
+LITERAL, never a pattern, and refuses a swap that would rename an id — that is
+`geml rename`, which fixes the references too. **It is EXPERIMENTAL and may be
+withdrawn**; build nothing on it that cannot change.
+
+A write is refused when it would break the document, never merely because it
+removes something. A replacement that drops blocks is carried out and the
+dropped blocks are named on stderr — unnamed ones counted, references left
+dangling reported — with `geml revert` as the way back. That is the same stance
+`delete` takes, so removing content has one rule rather than two, and no region
+becomes uneditable because something inside it happens to carry an id. The
+round trip above drops nothing: the blocks came back in the text you sent.
 
 A `@<hex>` **content address** is the first 8 hex of the SHA-256 of the block's
 own text (line endings normalized to LF, no trailing newline), with `~1`, `~2`…
@@ -218,9 +246,13 @@ Add to your `claude_desktop_config.json`:
 ### Claude Code / CLI Clients
 Run the following command to add the server:
 ```sh
-/mcp add npx -y @geml/geml@latest mcp --root /absolute/path/to/your/docs
+claude mcp add geml -- npx -y @geml/geml@latest mcp --root /absolute/path/to/your/docs
 ```
 
+With a code graph under `--root` (`geml codemap build`), the same server also
+serves four read-only `geml_codemap_*` tools. Every tool and option:
+[`docs/mcp-guide.md`](https://github.com/geml-spec/geml/blob/main/docs/mcp-guide.md).
+
 ## Library
 
 ```js
@@ -243,6 +275,11 @@ Full normative spec, history-sidecar spec, and format comparison live in the
 [repository](https://github.com/geml-spec/geml). The spec is itself
 written in GEML (`GEML-spec.geml`) and parsed clean on every test run.
 
+What changed between releases:
+[`CHANGELOG.md`](https://github.com/geml-spec/geml/blob/main/CHANGELOG.md).
+The parser and the specification version independently — `geml --version --json`
+prints both.
+
 ## License
 
 MIT.

package/codemap/build.mjs

@@ -513,6 +513,12 @@ console.error(
   + `${stats.containers} containers (${stats.written} of ${stats.docs} files written), `
   + `${(stats.bytes / 1048576).toFixed(2)} MB -> ${outDir}`,
 );
+// A build that deletes files says which ones. Silence here is how the orphans
+// accumulated in the first place — name them, so a rename that drops a whole
+// naming scheme is visible in the log rather than three renamings later.
+if (stats.pruned?.length) {
+  console.error(`  pruned ${stats.pruned.length} document(s) no longer produced: ${stats.pruned.join(", ")}`);
+}
 
 // --history: snapshot every changed document into its .gemlhistory sidecar —
 // the graph's own architectural history (geml history get / revert per node).

package/codemap/emit.mjs

@@ -13,7 +13,7 @@
 // Emission is deterministic: stable sort orders everywhere; a file is only
 // written when its bytes changed (mtime = "what a change touched").
 import { createHash } from "node:crypto";
-import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync, existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { dirname, join, posix } from "node:path";
 import { buildNormalizer } from "./normalize.mjs";
 
@@ -461,10 +461,40 @@ export function emit({ symbols, edges, outDir, buildDir, repoName, container = "
     if (!existsSync(p) || readFileSync(p, "utf8") !== content) writeFileSync(p, content);
   }
 
+  // ---- prune documents this build no longer produces ----
+  // A container that stops yielding symbols simply gets no document; without
+  // this, the one written by an earlier build stays behind describing code that
+  // is gone. Those orphans are not inert: `geml check` reads their `src=` line
+  // ranges and fails the build-time reference check, which is how nine of them
+  // — across two renamings of the naming scheme — went unnoticed until one
+  // orphan's source file happened to SHRINK past its recorded line numbers.
+  //
+  // `allDocs` is the authoritative set: every .geml this run emitted, written
+  // or byte-identical. Anything else at the top level of outDir is an orphan.
+  // Two guards keep this from eating a file it does not own: only the top level
+  // is scanned (never _index/, _build/, or any subtree), and a candidate must
+  // carry the generated-document marker `resolution-default` in its head — a
+  // hand-placed .geml parked in the directory is left alone.
+  const pruned = [];
+  const keep = new Set(allDocs);
+  let present = [];
+  try { present = readdirSync(outDir); } catch { present = []; }
+  for (const f of present) {
+    if (!f.endsWith(".geml") || keep.has(f)) continue;
+    const p = join(outDir, f);
+    try {
+      if (!statSync(p).isFile()) continue;
+      if (!/^===\s*meta\b[\s\S]*?\bresolution-default\s*=/.test(readFileSync(p, "utf8").slice(0, 2000))) continue;
+      unlinkSync(p);
+      pruned.push(f);
+    } catch { /* unreadable or already gone — not this build's problem */ }
+  }
+
   return {
     ...stats,
     allDocs,
     writtenDocs,
+    pruned,
     containers: containers.size,
     symbols: symbols.length,
     methods: methods.length,

package/codemap/render-all.mjs

@@ -8,7 +8,7 @@
 // graph area (nested frame), so the whole map is browsable offline — this is
 // the "copy the folder to someone" mode. For a live view that never goes
 // stale, use `geml codemap serve` instead.
-import { readdirSync, readFileSync, writeFileSync, realpathSync } from "node:fs";
+import { readdirSync, readFileSync, writeFileSync, realpathSync, unlinkSync } from "node:fs";
 import { join, basename, sep, resolve as resolvePath } from "node:path";
 import { parse, renderHtml } from "../dist/geml.js";
 
@@ -73,5 +73,18 @@ for (const f of files) {
     console.error(`render: ${f}: ${e.message}`);
   }
 }
+// Each tool prunes what it owns: build removes the documents it no longer
+// produces, and this removes the pages whose document is gone. An orphan page
+// is worse than a stale one — it is unreachable from index.html yet still
+// served, so a copied folder ships a page describing deleted code with no way
+// to notice. Only a `<base>.html` whose `<base>.geml` is absent qualifies, so
+// nothing that has a document behind it is ever touched.
+const prunedPages = [];
+for (const f of files) {
+  if (!f.endsWith(".html")) continue;
+  if (files.includes(f.replace(/\.html$/, ".geml"))) continue;
+  try { unlinkSync(join(dir, f)); prunedPages.push(f); } catch { /* already gone */ }
+}
 console.error(`rendered ${n} page(s) -> ${dir}${failed.length ? `; FAILED: ${failed.join(", ")}` : ""}`);
+if (prunedPages.length) console.error(`  pruned ${prunedPages.length} orphan page(s): ${prunedPages.join(", ")}`);
 process.exit(failed.length ? 1 : 0);

package/dist/block-edit.js

@@ -25,6 +25,20 @@ function splitLines(source) {
 function stripEnding(line) {
     return line.replace(/(\r\n|\r|\n)$/, "");
 }
+// A local mirror of geml.ts's trimSpaceTabEnd — geml.ts already imports THIS
+// module (normalizeBlockId), so importing back would close a cycle. Linear on
+// purpose: `/[ \t]+$/` restarts the run at every index inside a run that never
+// reaches the end of the line, which is quadratic in the line's length.
+function trimSpaceTabEnd(s) {
+    let i = s.length;
+    while (i > 0) {
+        const c = s.charCodeAt(i - 1);
+        if (c !== 0x20 && c !== 0x09)
+            break;
+        i--;
+    }
+    return i === s.length ? s : s.slice(0, i);
+}
 // Rewrite the id inside a `{…}` attribute block to `#newId`, keeping the braces
 // and every other class/attr byte. If no id is present, insert `#newId` as the
 // first token. The id token sits at a token boundary (`{` or whitespace) and
@@ -98,7 +112,7 @@ export function normalizeBlockId(blockSrc, newId) {
         const openLen = /^=+/.exec(f[1])[0].length;
         for (let j = hi + 1; j < lines.length; j++) {
             const ct = stripEnding(lines[j]);
-            const trimmed = ct.replace(/[ \t]+$/, "");
+            const trimmed = trimSpaceTabEnd(ct);
             if (/^=+$/.test(trimmed) && trimmed.length === openLen)
                 break; // plain close: done
             const cm = /^(={3,}[ \t]+#)([^\s}]+)([ \t]*)$/.exec(ct);

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};