@geml/geml 1.7.0 → 1.7.2

package/dist/selector.js

@@ -20,8 +20,15 @@ import { createHash } from "node:crypto";
 export function sha8(text) {
     return createHash("sha256").update(Buffer.from(text, "utf8")).digest("hex").slice(0, 8);
 }
-const FENCE_SEL = /^={3,}[ \t]*([A-Za-z][A-Za-z0-9_-]*)[ \t]*(@[0-9a-fA-F]{1,}(?:~\d+)?)?[ \t]*(\{.*\})?[ \t]*$/;
+// Each optional part carries its OWN trailing whitespace. Written flat —
+// `…[ \t]*(@…)?[ \t]*(\{.*\})?[ \t]*$` — three runs competed for the same tabs
+// and the engine tried every way to divide them: `=== note` plus 8k tabs and
+// one stray byte took 84 SECONDS. Nested, each absent part leaves exactly one
+// run and the match is immediate. Same language: 150k random strings, identical
+// groups. (Mirrors geml.ts's FENCE_OPEN, which had the same shape.)
+const FENCE_SEL = /^={3,}[ \t]*([A-Za-z][A-Za-z0-9_-]*)[ \t]*(?:(@[0-9a-fA-F]{1,}(?:~\d+)?)[ \t]*)?(?:(\{.*\})[ \t]*)?$/;
 const BARE_AT = /^@([0-9a-fA-F]+)(?:~(\d+))?$/;
+const BARE_LINE = /^[Ll](\d+)(?:-(\d+))?$/;
 // Parse selector TEXT. Never touches a document: every form is decided by
 // lexis alone, which is also what keeps the two selector namespaces on
 // `history get <file> <rev> <selector>` from overlapping (history design §10.2).
@@ -53,6 +60,19 @@ export function parseSelector(raw, attrsIdOf) {
         }
         return { form: "type", type };
     }
+    // Checked before the id fallthrough, so a bare `L27` is a position. An id
+    // that really is spelled `L27` keeps its explicit key form, `#L27` — the
+    // same "short form for the common case, key form always available" rule
+    // `@<hex>` already relies on.
+    const line = s.match(BARE_LINE);
+    if (line) {
+        const from = Number(line[1]);
+        const to = line[2] !== undefined ? Number(line[2]) : from;
+        // Reject rather than clamp: `L0` and `L10-5` are typos, and a selector that
+        // silently means something else is worse than one that refuses.
+        if (from >= 1 && to >= from)
+            return { form: "line", from, to };
+    }
     // Anything else is an id or a pasted heading line; the caller resolves it.
     return { form: "id", raw: s };
 }
@@ -104,6 +124,26 @@ export function matchContent(sel, all) {
 export function discoveryHint(where) {
     return ` — run \`geml get ${where}\` to list every addressable block`;
 }
+// Match a position selector: the SMALLEST unit that fully contains the range.
+// "Smallest" is what makes this ≤1 match instead of N. Spans nest — a heading's
+// span covers its whole section, so line 30 of the comparison doc sits inside
+// both `#capability-matrix` (L25-65) and `#caps` (L27-58) — and returning both
+// would emit the inner block twice, once alone and once inside its section.
+// The innermost is also the answer the question actually wants: a line number
+// arrived from grep or a stack trace, and the caller means "the thing I have to
+// edit", which is never the enclosing chapter.
+export function matchLine(sel, all) {
+    let best;
+    for (const a of all) {
+        const start = a.unit.span.start + 1; // spans are 0-based; selectors are 1-based, as the listing prints them
+        const end = a.unit.span.end;
+        if (start > sel.from || end < sel.to)
+            continue; // must FULLY contain the range
+        if (best === undefined || end - start < best.span.end - (best.span.start + 1))
+            best = a.unit;
+    }
+    return best;
+}
 // Match a type filter: every block of that type in document order. Blocks that
 // carry an id are INCLUDED — the selector says nothing about ids, so filtering
 // by whether one is present would be a rule nobody wrote down (§2).

package/dist/to-md.js

@@ -48,10 +48,32 @@ function inline(n) {
 function seq(ns) {
     return ns.map(inline).join("");
 }
+// Escape a `|` so GFM keeps it inside the cell instead of splitting the row.
+// GFM resolves backslash escapes in a row BEFORE it splits on `|`, so a
+// backslash run sitting right in front of our escape would eat it: a code span
+// holding `a\|b` became `a\\|b`, which reads as a literal backslash followed by
+// an UNescaped pipe — a spurious cell break. Double any such run first, then
+// escape the pipe. Runs already produced by escText (`\\` for a literal
+// backslash) survive this unchanged, so pre-rendered Markdown stays intact.
+//
+// The backslash run is matched as `\\+\|?` — one ATOMIC token, run and pipe
+// together — not as `(\\*)\|`. The latter is quadratic: on a cell holding a
+// long run of backslashes and no pipe, the engine matches the run from every
+// index in it and fails at the required `|` each time. Here the greedy `\\+`
+// takes the whole run in one match and the trailing `\|?` is optional, so
+// nothing backtracks and each character is visited once.
+function escPipe(s) {
+    return s.replace(/\\+\|?|\|/g, (m) => {
+        if (m.charAt(m.length - 1) !== "|")
+            return m; // a run with no pipe after it
+        const bs = m.slice(0, -1); // the run that would otherwise eat our escape
+        return bs + bs + "\\|";
+    });
+}
 // Inline text for a table cell: render inlines, then neutralise the two bytes
 // that would break a GFM cell.
 function cellText(c) {
-    return seq(c.inlines).replace(/\|/g, "\\|").replace(/\n/g, " ");
+    return escPipe(seq(c.inlines)).replace(/\n/g, " ");
 }
 // ---------------------------------------------------------------------------
 // Tables
@@ -72,7 +94,7 @@ function tableToMd(t, notes) {
     const lines = [];
     if (t.caption)
         lines.push(`*${t.caption}*`, "");
-    lines.push(`| ${cols.map((c) => c.replace(/\|/g, "\\|")).join(" | ")} |`);
+    lines.push(`| ${cols.map(escPipe).join(" | ")} |`);
     lines.push(`| ${cols.map((_, i) => sep(t.align[i])).join(" | ")} |`);
     const pad = (cells) => {
         while (cells.length < cols.length)

package/package.json

@@ -1,67 +1,67 @@
-{
-  "name": "@geml/geml",
-  "version": "1.7.0",
-  "mcpName": "io.github.geml-spec/geml",
-  "publishConfig": {
-    "access": "public"
-  },
-  "description": "CLI and parser for GEML, a plain-text document format where every block has an id — so an AI patches one block instead of rewriting the file; edits, reference checks and rollbacks are all per block. Ships an MCP server.",
-  "type": "module",
-  "bin": {
-    "geml": "dist/geml.js"
-  },
-  "main": "dist/geml.js",
-  "types": "dist/geml.d.ts",
-  "files": [
-    "dist",
-    "codemap",
-    "skill",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=22"
-  },
-  "keywords": [
-    "geml",
-    "general expressive markup language",
-    "mcp",
-    "mcp-server",
-    "markup",
-    "markdown",
-    "parser",
-    "cli",
-    "document",
-    "typed-block",
-    "ai",
-    "agent",
-    "llm",
-    "addressable",
-    "versioning",
-    "docs",
-    "code-graph"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/geml-spec/geml.git",
-    "directory": "geml-parser"
-  },
-  "homepage": "https://github.com/geml-spec/geml#readme",
-  "bugs": {
-    "url": "https://github.com/geml-spec/geml/issues"
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "tsc && node test/all.mjs",
-    "parse": "node dist/geml.js",
-    "coverage": "tsc && c8 --all --include=dist/**/*.js --include=codemap/**/*.mjs --reporter=text --reporter=text-summary node test/all.mjs",
-    "coverage:check": "tsc && c8 --all --include=dist/**/*.js --include=codemap/**/*.mjs --check-coverage --lines 95 --statements 95 --functions 95 --branches 95 node test/all.mjs",
-    "prepublishOnly": "npm run build"
-  },
-  "license": "MIT",
-  "devDependencies": {
-    "@types/node": "^22.19.21",
-    "c8": "^10.1.3",
-    "typescript": "^5.9.3"
-  }
-}
+{
+  "name": "@geml/geml",
+  "version": "1.7.2",
+  "mcpName": "io.github.geml-spec/geml",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "CLI and parser for GEML, a plain-text document format where every block has an id — so an AI patches one block instead of rewriting the file; edits, reference checks and rollbacks are all per block. Ships an MCP server.",
+  "type": "module",
+  "bin": {
+    "geml": "dist/cli.js"
+  },
+  "main": "dist/geml.js",
+  "types": "dist/geml.d.ts",
+  "files": [
+    "dist",
+    "codemap",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "geml",
+    "general expressive markup language",
+    "mcp",
+    "mcp-server",
+    "markup",
+    "markdown",
+    "parser",
+    "cli",
+    "document",
+    "typed-block",
+    "ai",
+    "agent",
+    "llm",
+    "addressable",
+    "versioning",
+    "docs",
+    "code-graph"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/geml-spec/geml.git",
+    "directory": "geml-parser"
+  },
+  "homepage": "https://github.com/geml-spec/geml#readme",
+  "bugs": {
+    "url": "https://github.com/geml-spec/geml/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node test/all.mjs",
+    "parse": "node dist/geml.js",
+    "coverage": "tsc && c8 --all --include=dist/**/*.js --include=codemap/**/*.mjs --reporter=text --reporter=text-summary node test/all.mjs",
+    "coverage:check": "tsc && c8 --all --include=dist/**/*.js --include=codemap/**/*.mjs --check-coverage --lines 95 --statements 95 --functions 95 --branches 95 node test/all.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.19.21",
+    "c8": "^10.1.3",
+    "typescript": "^5.9.3"
+  }
+}

package/skill/SKILL.md

@@ -50,15 +50,40 @@ Inside the geml-spec repo prefer the local build:
 `node geml-parser/dist/geml.js <args>`. If no parser is reachable, follow the
 golden rules and validate once it is.
 
+`geml skill install` sets all of this up user-global, and installs this text
+into whatever other agent tools it detects — a tool's directory has to be there
+already; none is ever created for you. `--dry-run` shows what it would do.
+
 ## Work blockwise (agent editing)
 
 ```sh
+geml list    file.geml                # CALL THIS FIRST — every block, its address, kind, lines
+geml find    "text" file.geml|dir     # search block CONTENT -> file<TAB>address (exit 1 = no hit)
 geml get     file.geml '#id'          # read ONE block (a heading id = its whole section)
 geml set     file.geml '#id' --in f   # replace ONE block (re-parsed; never writes a broken doc)
 geml history save file.geml -m "…"    # snapshot to .gemlhistory after each meaningful edit
 geml revert  file.geml '#id'          # roll ONE block back (--rev -2 | changed | <rev-id>)
 ```
 
+Address a block, never a line range: `#id` · `'## Heading'` (its whole section)
+· `'=== type'` · `@<hex>` (no id) · `L27` or `L27-58` (the smallest block holding
+those lines — how a line number from an editor, a linter or a diff hunk becomes
+an address). `list` and `find` print addresses that paste straight into the
+others, so neither `grep` nor a line count is needed to locate anything.
+
+Any section can be cut three ways, on `get` and `set` alike: `--head` (the
+heading line), `--intro` (what it says before its first subheading — empty when
+one follows immediately, the whole body when none does), `--body` (everything
+under it, so it always contains the intro). `--intro` is how you edit a
+section's opening without pulling its subsections into context, and setting an
+empty one writes an opening where the section had none.
+
+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 NAMED on
+stderr — unnamed blocks included — with `geml revert` as the way back. Read,
+edit, write back, and nothing is dropped, because `get` handed those blocks to
+you. Send content that omits them only when removing them is the point.
+
 ## Full reference — pull ONE section, not the whole file
 
 `references/authoring.geml` (under this skill's base directory) holds the

package/skill/references/authoring.geml

@@ -214,10 +214,15 @@ All commands accept `-` to read from stdin.
 
 === code {#cli-verbs lang=sh}
 geml file.geml                        # document-model JSON (default --to json)
-geml get     file.geml                # list every addressable block + address (--json = array)
+geml list    file.geml                # CALL FIRST: every block, its address, kind, line range
+geml find    "text" file.geml|dir     # search block CONTENT -> file<TAB>address; exit 1 = no hit
+geml get     file.geml                # same listing as `list` (the no-selector default)
 geml get     file.geml '#id'          # print ONE block (raw span; --json = model node)
 geml get     file.geml '=== note'     # every block of a type; '@a3f9c1d2' = a block with no #id
+geml get     file.geml 'L27-58'       # position: the smallest block holding those lines
+geml get     file.geml '#sec' --intro # a section cut three ways: --head | --intro | --body
 geml set     file.geml '#id' --in f   # replace ONE block (guarded: re-parsed, never writes broken)
+geml set     file.geml '#sec' --intro # replace just the opening; the subsections stay put
 geml add     file.geml --after '#id' --in f   # insert a fragment (keeps its own ids)
 geml delete  file.geml '#id' ['#id2']         # remove one or more blocks
 geml rename  file.geml '#old' '#new'          # rename an id AND every reference to it