@geml/geml 1.1.1 → 1.3.2

package/README.md

@@ -7,11 +7,13 @@
 
 # @geml/geml
 
-Reference parser, validator, renderer, and CLI for **GEML** — the General
-Expressive Markup Language: a plain-text document format that stays legible to
-people and reliable for machines. Every kind of structured content — code,
-tables, diagrams, math, callouts, metadata — is carried on **one** primitive,
-the typed block:
+The reference parser, validator, renderer, and CLI for **GEML** (General
+Expressive Markup Language) — **one format, two readers.** People and AI agents
+co-write the same document: plain text that stays legible for people, and
+**addressable, verifiable, and versioned** for machines.
+
+Every kind of structured content — code, tables, diagrams, math, callouts,
+metadata — rides on **one** primitive, the typed block:
 
 ```
 === code {#hello lang=python}
@@ -19,9 +21,18 @@ print("hi")
 ===
 ```
 
-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 `diagnostics`, so
-agents and CI get a structured pass/fail signal.
+- **Addressable** — every block has an `#id`; `geml get` / `geml set '#id'`
+  read or patch one section without re-emitting the whole file (on this repo's
+  own spec, ~**31× less context** than shipping the whole document).
+- **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.
+- **Versioned** — `geml history` and `geml revert` snapshot and rewind
+  revisions over a plain-text `.gemlhistory` sidecar.
+
+Try the format in the [playground](https://geml-spec.github.io/geml/playground/)
+— no install. Full pitch, spec, and format comparison live in the
+[repository](https://github.com/geml-spec/geml).
 
 ## Install
 
@@ -31,7 +42,7 @@ npm install -g @geml/geml   # global CLI — installs the `geml` command
 npm install @geml/geml      # library + local bin
 ```
 
-Requires Node ≥ 18.
+Requires Node ≥ 22.
 
 ## CLI
 
@@ -39,18 +50,37 @@ Every command reads a file path, or `-` for stdin. Exit codes: `0` ok ·
 `1` document/operation error · `2` usage error.
 
 ```sh
+geml get    file.geml '#id'      # print ONE block by id — a heading id yields its whole section
+geml set    file.geml '#id' --from new.geml  # replace just that block; re-parsed, refused if it breaks the doc
 geml check  file.geml            # validate only: diagnostics + exit code
 geml check --json file.geml      # machine-readable: diagnostics array (or {"error":…} on IO failure)
 geml        file.geml            # full document-model JSON
+geml history <commit|verify|show|restore|log> file.geml [...]   # .gemlhistory version sidecar
+geml revert file.geml '#id' [--to -1]  # roll ONE block back to an earlier revision (-N | latest | id)
 geml render file.geml -o out.html  # one self-contained, interactive HTML file
 geml export file.geml -o out.md    # project to GitHub-Flavored Markdown (lossy; notes on stderr)
 geml convert in.md     -o out.geml # Markdown -> GEML
 geml fmt    file.geml            # canonical re-format (idempotent)
-geml history <commit|verify|show|restore> file.geml [...]   # .gemlhistory sidecar
+geml codemap <build|verify|render|serve|refresh|find|mcp>  # your codebase's call graph as GEML docs
 geml --help | --version          # --version --json prints {"parser","spec"}
 ```
 
-The agent loop: write `.geml` → `geml check` → fix on non-zero → done.
+The agent loop: `geml get` a block → edit it → `geml set` (guarded splice) →
+`geml check` → `geml history commit` — small, precise, verifiable edits.
+
+A **heading's** `#id` addresses its whole **section** — the heading line through
+the line before the next heading of the same-or-higher level — so the prose
+under a heading is block-editable with no extra syntax.
+Spans overlap: blocks nested in the section keep their own ids, and a `set` on
+the section that drops one of them is refused by the guard. `get --json` on a
+heading covers the same content as the raw span: a section envelope
+`{kind:"section", id, level, blocks:[heading, …its section's blocks]}` (a
+block/footnote id still prints its single model node). `--head` narrows
+`get`/`set`/`revert` to ANY id's head line — a heading's line, or a typed
+block's opening fence line, so an agent renames a heading or edits a block's
+attributes (caption, compute, …) without touching the body. Convention: keep
+the document title in `=== meta` (`title = "…"`), not an H1 — a lone top-level
+`#` section is the whole document, the telltale that it is really a title.
 
 ## Library
 

package/codemap/adapters/crg.mjs

@@ -21,6 +21,17 @@ const EDGE_KIND = {
 
 export function extract({ db: dbPath, root }) {
   const db = new DatabaseSync(dbPath);
+  try {
+    return extractFrom(db, root);
+  } finally {
+    // Always release the handle: an open DatabaseSync keeps graph.db locked for
+    // the process lifetime, so on Windows the caller cannot delete or replace
+    // it (EPERM). try/finally closes it even if extraction throws.
+    db.close();
+  }
+}
+
+function extractFrom(db, root) {
   const rootFs = root.replace(/\\/g, "/").replace(/\/?$/, "/");
   const rel = (p) => {
     p = String(p).replace(/\\/g, "/");