@geml/geml 1.7.1 → 1.7.3

package/package.json

@@ -1,67 +1,67 @@
-{
-  "name": "@geml/geml",
-  "version": "1.7.1",
-  "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.3",
+  "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,50 @@ 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 replace file.geml OLD NEW        # EXPERIMENTAL literal swap; --within '#id' to narrow
 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.
+
+When the exact old text is already known and nothing needs reading — a version
+string in six places, a renamed term — `geml replace` is the cheap path, and the
+one to prefer over dropping to `sed`: 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 (use `geml rename`, which fixes the references
+too). **It is EXPERIMENTAL and may be withdrawn** — reach for it, but do not
+build anything 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 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,17 @@ 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 replace file.geml OLD NEW        # EXPERIMENTAL, may be withdrawn: literal swap, checked and
+                                      # reported; --within '#id' or '=== type' narrows the scope
 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