@geml/geml 1.1.1 → 1.3.2

package/codemap/find.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// geml codemap find <name> [codemap-dir]
+//
+// Locate a function/class by (substring, case-insensitive) name in a built
+// codemap. Prints each candidate as  <name> \t <doc>#<id> \t <src>  — the
+// document + block id to open, and the true source location. NO browser: pure
+// stdout, so it pipes/greps. `dir` defaults to ./.geml-code-graph.
+//
+// Same index the MCP `resolve_name` tool and the viewer search box use
+// (_index/name-lookup.json); a name with several rows is real ambiguity
+// (overloads / same short name across classes) — every candidate is printed.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+// `find x | head` closes stdout after a few lines — that is normal pipe
+// usage, not an error (POSIX would kill us silently with SIGPIPE; Windows
+// node surfaces it as an EPIPE error event): exit quietly instead of
+// crashing with an unhandled-error stack trace.
+process.stdout.on("error", (e) => { if (e.code === "EPIPE") process.exit(0); throw e; });
+
+const args = process.argv.slice(2);
+if (!args.length || args[0] === "--help" || args[0] === "-h") {
+  console.error("usage: geml codemap find <name> [codemap-dir]   # locate a symbol by substring name (dir defaults to ./.geml-code-graph)");
+  process.exit(args.length ? 0 : 2);
+}
+const query = args[0];
+const dir = args[1] || ".geml-code-graph";
+const lookupPath = join(dir, "_index", "name-lookup.json");
+if (!existsSync(lookupPath)) {
+  console.error(`no name-lookup at ${lookupPath} — build the codemap first (geml codemap build)`);
+  process.exit(1);
+}
+const lookup = JSON.parse(readFileSync(lookupPath, "utf8"));
+const q = query.toLowerCase();
+const names = Object.keys(lookup).filter((n) => n.toLowerCase().includes(q)).sort();
+if (!names.length) { console.error(`no symbol matching "${query}"`); process.exit(1); }
+
+// src= lives on the block header line in the doc; read each doc once, index by id.
+const docCache = new Map(); // doc -> Map(id -> src)
+const srcOf = (doc, id) => {
+  if (!docCache.has(doc)) {
+    const map = new Map();
+    try {
+      const text = readFileSync(join(dir, doc), "utf8");
+      // src= may be quoted or a bare token (path#Lx-y, no spaces).
+      const re = /\{#([A-Za-z0-9._-]+)\b[^}]*?\bsrc=(?:"([^"]+)"|([^\s}]+))/g;
+      let m;
+      while ((m = re.exec(text))) map.set(m[1], m[2] || m[3]);
+    } catch { /* doc unreadable — skip src */ }
+    docCache.set(doc, map);
+  }
+  return docCache.get(doc).get(id) || "";
+};
+
+let n = 0;
+for (const name of names) {
+  for (const c of lookup[name]) {
+    const src = srcOf(c.doc, c.id);
+    process.stdout.write(`${name}\t${c.doc}#${c.id}${src ? `\t${src}` : ""}\n`);
+    n++;
+  }
+}
+console.error(`\n${n} match(es) for "${query}" across ${names.length} name(s).`);

package/codemap/foldings.mjs

@@ -0,0 +1,110 @@
+// foldings.geml — the visible, human-owned config for codemap ceremony folding.
+// GEML (dogfooded; the viewer renders it): a meta header, three bullet-list
+// sections (fold-prefixes / source-roots / test-roots) and an options section.
+// Read via the bundled parser; group-id shared-prefix stripping stays
+// algorithmic (only its on/off toggle lives here).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "../dist/geml.js";
+import { deriveFoldLayers, DEFAULT_SOURCE_ROOTS, DEFAULT_TEST_ROOTS, LANG_FOLD_PREFIXES } from "./normalize.mjs";
+
+const SECTIONS = { "fold-prefixes": "foldPrefixes", "source-roots": "sourceRoots", "test-roots": "testRoots", "module-roots": "moduleRoots" };
+// Plain text of a bullet-list item. GEML list items carry `.text`; fall back to
+// joining inline `.value`s if a build ever changes that shape.
+const itemText = (it) => (typeof it.text === "string" ? it.text : (it.inlines ?? []).map((n) => n.value ?? "").join("")).trim();
+
+export function parseFoldings(text) {
+  const doc = parse(text);
+  // A malformed hand-edit must fail LOUDLY, not silently drop every rule: the
+  // caller (loadOrSeedFoldings) catches this and falls back to the defaults.
+  // An intentionally empty file carries NO error diagnostics and yields empty
+  // sections — the "fold nothing" off-switch, a deliberately different outcome.
+  const errs = doc.diagnostics.filter((d) => d.severity === "error");
+  if (errs.length) throw new Error(`invalid GEML in foldings config: ${errs[0].message} (line ${errs[0].line})`);
+  const cfg = { foldPrefixes: [], sourceRoots: [], testRoots: [], moduleRoots: [], stripSharedPrefix: true };
+  let section = null;
+  for (const b of doc.children) {
+    if (b.kind === "heading") { section = b.text.trim().toLowerCase(); continue; }
+    if (b.kind !== "list") continue;
+    const items = b.items.map(itemText).filter(Boolean);
+    if (Object.hasOwn(SECTIONS, section)) cfg[SECTIONS[section]] = items;
+    else if (section === "options") {
+      for (const it of items) {
+        const m = it.match(/^strip-shared-prefix\s*:\s*(on|off|true|false)$/i);
+        if (m) cfg.stripSharedPrefix = /^(on|true)$/i.test(m[1]);
+      }
+    }
+  }
+  return cfg;
+}
+
+export function serializeFoldings(cfg) {
+  const list = (xs) => xs.map((x) => `- ${x}`).join("\n");
+  return [
+    "=== meta",
+    'title = "codemap foldings"',
+    "===",
+    "",
+    "Ceremony folded out of module display names. Seeded on first build; edit",
+    "freely — build never rewrites this. The shared package prefix (group-ids",
+    "like com/acme/app) is stripped automatically and needs no entry here; set",
+    "strip-shared-prefix to off under Options to disable it.",
+    "",
+    "Add a directory under module-roots to force it to display as its own",
+    "module — for a submodule a build tool declares centrally but whose folder",
+    "carries no manifest, or any layout the detector cannot see.",
+    "",
+    "## fold-prefixes",
+    "",
+    list(cfg.foldPrefixes),
+    "",
+    "## source-roots",
+    "",
+    list(cfg.sourceRoots),
+    "",
+    "## test-roots",
+    "",
+    list(cfg.testRoots),
+    "",
+    "## module-roots",
+    "",
+    list(cfg.moduleRoots ?? []),
+    "",
+    "## options",
+    "",
+    `- strip-shared-prefix: ${cfg.stripSharedPrefix ? "on" : "off"}`,
+    "",
+  ].join("\n");
+}
+
+// Seeded config for a first build: structural fold-layers (above-root
+// ceremony dirs, derived from the discovered module roots) unioned with
+// known per-language ceremony (Cargo's `crates/`). Source/test roots always
+// start from the same global defaults — the human edits foldings.geml from
+// there; the build never rewrites it once it exists.
+export function defaultFoldings({ moduleRoots, languages }) {
+  const langPrefixes = (languages ?? []).flatMap((l) => LANG_FOLD_PREFIXES[l] ?? []);
+  const foldPrefixes = [...new Set([...deriveFoldLayers(moduleRoots ?? []), ...langPrefixes])].sort();
+  return { foldPrefixes, sourceRoots: [...DEFAULT_SOURCE_ROOTS], testRoots: [...DEFAULT_TEST_ROOTS], moduleRoots: [], stripSharedPrefix: true };
+}
+
+// Read <outDir>/_index/foldings.geml, or seed it on first build. Write-once:
+// an existing file is the human's — we read it and never rewrite it (the
+// refresh.json contract). A missing or unreadable file never crashes the
+// build: seed/fall back to defaults and say so. Returns { config, seeded }.
+export function loadOrSeedFoldings({ outDir, moduleRoots, languages }) {
+  const path = join(outDir, "_index", "foldings.geml");
+  if (existsSync(path)) {
+    try { return { config: parseFoldings(readFileSync(path, "utf8")), seeded: false }; }
+    catch (e) {
+      console.error(`warning: ignoring ${path} (${e.message}) — using default foldings; fix the file to re-enable your edits.`);
+      return { config: defaultFoldings({ moduleRoots, languages }), seeded: false };
+    }
+  }
+  const config = defaultFoldings({ moduleRoots, languages });
+  try {
+    mkdirSync(join(outDir, "_index"), { recursive: true });
+    writeFileSync(path, serializeFoldings(config));
+  } catch (e) { console.error(`warning: could not seed ${path} (${e.message}).`); }
+  return { config, seeded: true };
+}

package/codemap/mcp-server.mjs

@@ -11,9 +11,13 @@
 //   claude mcp add geml-code-graph -e GEML_GRAPH_DIR=/abs/path/to/graph \
 //     -- geml codemap mcp
 // The graph dir comes from GEML_GRAPH_DIR or a per-call `graph_dir` argument.
-import { readFileSync, existsSync } from "node:fs";
-import { join, resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+//
+// The dispatch is exported (and the stdio wiring below is main-module guarded)
+// so the test suite can drive it in-process; the CLI dispatcher always runs
+// this file as a child's MAIN module, where nothing changes.
+import { readFileSync, existsSync, realpathSync } from "node:fs";
+import { join, resolve, dirname, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { createInterface } from "node:readline";
 
 // blockSpans from the reference parser (its CLI entry is guarded, so importing
@@ -26,18 +30,31 @@ if (!existsSync(parserPath)) {
 const { blockSpans } = await import(`file://${parserPath.replace(/\\/g, "/")}`);
 const splitLines = (s) => s.split(/(?<=\n)/);
 
-const graphDirOf = (args) => resolve(args?.graph_dir ?? process.env.GEML_GRAPH_DIR ?? ".geml-code-graph");
+export const graphDirOf = (args) => resolve(args?.graph_dir ?? process.env.GEML_GRAPH_DIR ?? ".geml-code-graph");
 
-const readBlock = (graphDir, doc, id) => {
+export const readBlock = (graphDir, doc, id) => {
   const p = join(graphDir, doc);
-  if (!existsSync(p)) throw new Error(`no such document: ${doc} (graph dir: ${graphDir})`);
-  const source = readFileSync(p, "utf8");
+  // Confine `doc` to the graph dir. `doc` is client-supplied, so a value like
+  // ../../../etc/hosts joins OUT of the dir; realpathSync canonicalizes both
+  // sides (also defeating symlink escapes and normalizing Windows casing) and
+  // we verify the real doc path stays within the real graph dir. A missing
+  // file makes realpathSync throw — that is the normal "no such document"
+  // miss. (graph_dir itself is intentionally client-chosen — the server is
+  // pointed at a graph — so only the doc path is confined, to that dir.)
+  let realDir;
+  try { realDir = realpathSync(graphDir); } catch { realDir = resolve(graphDir); }
+  let realP;
+  try { realP = realpathSync(p); } catch { throw new Error(`no such document: ${doc} (graph dir: ${graphDir})`); }
+  if (realP !== realDir && !realP.startsWith(realDir + sep)) {
+    throw new Error(`document escapes the graph dir: ${doc} (graph dir: ${graphDir})`);
+  }
+  const source = readFileSync(realP, "utf8");
   const span = blockSpans(source).get(id.replace(/^#/, ""));
   if (!span) throw new Error(`no block with id \`${id}\` in ${doc}`);
   return splitLines(source).slice(span.start, span.end).join("");
 };
 
-const TOOLS = [
+export const TOOLS = [
   {
     name: "resolve_name",
     description: "Find a function/class by name in the code graph. Returns candidate anchors with the document and block id to open. Multiple candidates = real ambiguity (overloads/same name) — inspect each, never assume.",
@@ -94,8 +111,14 @@ const TOOLS = [
       }
       if (!args.id) return table;
       const id = args.id.replace(/^#/, "");
+      // `id` is client-supplied and goes straight into a RegExp: escape every
+      // regex metacharacter so it matches LITERALLY (an id like `.*` or a
+      // catastrophic-backtracking pattern can neither widen the match nor cause
+      // ReDoS — the pattern is a fixed string wrapped in `,\s*#…\s*,`).
+      const escId = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const re = new RegExp(`,\\s*#${escId}\\s*,`);
       const lines = table.split("\n");
-      const hits = lines.filter((l, i) => i < 2 || new RegExp(`,\\s*#${id}\\s*,`).test(l));
+      const hits = lines.filter((l, i) => i < 2 || re.test(l));
       return hits.length > 2 ? hits.join("\n")
         : `no resolved callers of #${id} in ${args.doc} (blind spots live in the #unresolved table)`;
     },
@@ -103,11 +126,11 @@ const TOOLS = [
 ];
 
 // ---- newline-delimited JSON-RPC 2.0 over stdio ----
-const reply = (id, result) => process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
-const replyError = (id, code, message) =>
-  process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }) + "\n");
-
-createInterface({ input: process.stdin }).on("line", (line) => {
+// One frame in, zero or one frame out via `write` (stdout in production).
+export function handleLine(line, write = (s) => process.stdout.write(s)) {
+  const reply = (id, result) => write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
+  const replyError = (id, code, message) =>
+    write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }) + "\n");
   line = line.trim();
   if (!line) return;
   let msg;
@@ -140,4 +163,10 @@ createInterface({ input: process.stdin }).on("line", (line) => {
   } catch (e) {
     if (id !== undefined) replyError(id, -32603, String(e?.message ?? e));
   }
-});
+}
+
+// Auto-run only as a MAIN module (the CLI dispatcher spawns this file as a
+// child's entry script) — an in-process `import` stays inert.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  createInterface({ input: process.stdin }).on("line", (line) => handleLine(line));
+}

package/codemap/recipe-trust.mjs

@@ -0,0 +1,103 @@
+// Shared TRUST GATE for codemap recipes (security fix C2 — RCE).
+//
+// A codemap's _index/refresh.json is COMMITTED DATA whose `steps[]` are run
+// through a shell by `geml codemap refresh` (spawnSync(step,{shell:true})).
+// Cloning a hostile repo and running `geml codemap refresh` — which the
+// geml-code-graph skill, `serve --watch`, and a PostToolUse hook all trigger —
+// would otherwise execute arbitrary commands. The old "up-to-date" guard is
+// bypassable and does not gate execution.
+//
+// The fix content-addresses each recipe (a stable fingerprint of its steps)
+// and records which fingerprints the user has EXPLICITLY approved in a store
+// kept OUTSIDE any repo (so a repo can never pre-approve itself). refresh
+// refuses to execute a recipe whose fingerprint is not in the store; build
+// auto-trusts the recipe it just authored (the user ran it locally).
+//
+// Trust gates WHO may run a recipe. Security fix R2-1 additionally changed HOW
+// steps are stored: a step is now a STRUCTURED object { cwd?, env?, argv:[...] }
+// so attacker-controllable paths are never interpolated into a shell string at
+// rest, and refresh executes them without an attacker-influenced command line.
+// The fingerprint below canonicalizes that structured form.
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+
+export const RECIPE_VERSION = 1;   // on-disk step schema; bump ONLY on a real format change
+
+// Canonicalize ONE recipe step for fingerprinting. Since security fix R2-1 a
+// step is a STRUCTURED object { cwd?, env?, argv:[...] } (no shell string is
+// ever stored). We emit a FIXED key order (cwd, env, argv), env keys SORTED so
+// the fingerprint is independent of how the env map was built, and every value
+// coerced to a string. Anything that is NOT a structured step (a legacy
+// pre-R2-1 shell string, or a malformed entry) coerces to its String() form, so
+// pre-existing string recipes keep the EXACT fingerprint they had before this
+// change (backward compatible), while structured recipes get a stable identity.
+function canonicalStep(step) {
+  if (step && typeof step === "object" && Array.isArray(step.argv)) {
+    const out = {};
+    if (step.cwd != null) out.cwd = String(step.cwd);
+    if (step.env && typeof step.env === "object") {
+      const env = {};
+      for (const k of Object.keys(step.env).sort()) env[k] = String(step.env[k]);
+      out.env = env;
+    }
+    out.argv = step.argv.map((a) => String(a));
+    return out;
+  }
+  return String(step);
+}
+
+// Fingerprint = sha256 over a canonical JSON of {root, steps}. build (when it
+// records refresh.json) and refresh (when it is about to run it) both call
+// this on the same parsed recipe object, so they agree exactly. `root` is
+// included because it is the base dir every step runs under — the same steps
+// under a different root are a different execution and deserve a different
+// identity. Deterministic: fixed key order, canonicalized steps, no timestamps.
+export function recipeFingerprint(recipe) {
+  const steps = Array.isArray(recipe?.steps) ? recipe.steps.map(canonicalStep) : [];
+  const root = recipe?.root == null ? "" : String(recipe.root);
+  const canonical = JSON.stringify({ root, steps });
+  return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+
+// Where the trust store lives — NEVER inside a repo. GEML_TRUST_STORE is an
+// explicit override (test isolation / unusual homes). Otherwise it sits under
+// the XDG config dir, falling back to ~/.config/geml, which is a sane
+// cross-platform home (on Windows homedir() is C:\Users\<name>).
+export function trustStorePath() {
+  if (process.env.GEML_TRUST_STORE) return process.env.GEML_TRUST_STORE;
+  const cfgHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(cfgHome, "geml", "trusted-recipes.json");
+}
+
+// Read the store DEFENSIVELY: a missing, unreadable, or malformed store means
+// "nothing is trusted". A broken store must never silently trust a recipe.
+export function readTrustStore() {
+  try {
+    const obj = JSON.parse(readFileSync(trustStorePath(), "utf8"));
+    if (obj && typeof obj === "object" && obj.recipes && typeof obj.recipes === "object") {
+      return { version: obj.version || 1, recipes: obj.recipes };
+    }
+  } catch { /* missing / unreadable / malformed: treat as empty */ }
+  return { version: 1, recipes: {} };
+}
+
+// True only when this exact recipe fingerprint has been approved.
+export function isRecipeTrusted(fingerprint) {
+  const store = readTrustStore();
+  return Object.prototype.hasOwnProperty.call(store.recipes, fingerprint);
+}
+
+// Record a fingerprint as trusted, MERGING into any existing store (never
+// clobbering other approvals). Creates parent dirs. Returns the store path.
+// THROWS on write failure: a caller that meant to trust must learn it did NOT,
+// rather than proceed on the false belief that the recipe is now safe.
+export function trustRecipe(fingerprint, graphDir) {
+  const store = readTrustStore();
+  store.recipes[fingerprint] = { graphDir: graphDir ? String(graphDir) : undefined, addedAt: Date.now() };
+  const p = trustStorePath();
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(store, null, 2) + "\n");
+  return p;
+}

package/codemap/refresh.mjs

@@ -36,6 +36,7 @@ import { readFileSync, existsSync, appendFileSync, openSync, closeSync } from "n
 import { join, resolve, relative } from "node:path";
 import { spawnSync, spawn } from "node:child_process";
 import { isSourcePath } from "./detect.mjs";
+import { recipeFingerprint, isRecipeTrusted, trustRecipe, trustStorePath, RECIPE_VERSION } from "./recipe-trust.mjs";
 
 const args = process.argv.slice(2);
 const hookMode = args.includes("--hook");
@@ -45,8 +46,11 @@ const background = args.includes("--background");
 // naming, new emit shape) changes the OUTPUT for the same code.
 const force = args.includes("--force");
 const autoCommit = args.includes("--commit");
+// --trust: approve THIS recipe (by fingerprint) so refresh will run it. The
+// gate below refuses any recipe whose fingerprint is not in the trust store.
+const trustFlag = args.includes("--trust");
 if (args.includes("--help")) {
-  console.error("usage: geml codemap refresh [codemap-dir] [--force] [--commit] [--background|--hook]   (dir defaults to ./.geml-code-graph)");
+  console.error("usage: geml codemap refresh [codemap-dir] [--trust] [--force] [--commit] [--background|--hook]   (dir defaults to ./.geml-code-graph)");
   process.exit(2);
 }
 const dir = args.find((a) => !a.startsWith("--")) || ".geml-code-graph";
@@ -60,6 +64,87 @@ if (!existsSync(cfgPath)) {
   process.exit(1);
 }
 
+// Parse the recipe UP FRONT: its fingerprint drives the TRUST GATE (security
+// fix C2). refresh.json is committed data whose steps run through a shell, so
+// an untrusted recipe must never reach the exec loop on ANY path — the
+// foreground run, the --hook/--background re-spawn, or serve --watch (which
+// spawns this script). See codemap/recipe-trust.mjs.
+let cfg;
+try { cfg = JSON.parse(readFileSync(cfgPath, "utf8")); }
+catch (e) {
+  if (hookMode) process.exit(0); // a broken recipe must not block a commit
+  console.error(`error: cannot parse recipe ${cfgPath}: ${e.message}`);
+  process.exit(1);
+}
+const steps = cfg.steps ?? [];
+const fingerprint = recipeFingerprint(cfg);
+let trusted = isRecipeTrusted(fingerprint);
+
+// --- structured-step execution (security fix R2-1) --------------------------
+// A recipe step is a structured object { cwd?, env?, argv:[...] }. We run argv
+// WITHOUT ever concatenating an attacker-controllable value into a shell
+// string (the R2-1 RCE was a recorded `cd <dir-name> && …` string run under a
+// shell, where <dir-name> was attacker-chosen).
+//   POSIX: spawn the program directly (shell:false) — no shell, no injection.
+//   win32: npx.cmd / geml.cmd / rust-analyzer / joern.bat are .cmd/.bat shims
+//     that modern Node refuses to spawn with shell:false (EINVAL), so we go
+//     through cmd.exe. Node does NOT escape args under shell:true — it only
+//     concatenates them (DEP0190) — so we build the command line ourselves and
+//     quote EACH argv element: the program via q (a bare launcher name stays
+//     bare so its .cmd shim's %~dp0 resolves against the shim dir; a spaced
+//     full path is quoted), every argument via shq (ALWAYS double-quoted, so
+//     cmd.exe treats & | < > ( ) ^ and whitespace as literal). An injected
+//     metachar inside a dir-name argument is therefore inert.
+const q = (s) => (/[\s"]/.test(String(s)) ? `"${String(s).replace(/"/g, '\\"')}"` : String(s));
+const shq = (s) => `"${String(s).replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1')}"`;
+// Human-readable render of a step for the log / refusal message — DISPLAY ONLY,
+// never executed. Falls back to String() for a stale (non-structured) step.
+const renderStep = (s) => {
+  if (!s || typeof s !== "object" || !Array.isArray(s.argv)) return String(s);
+  const parts = [];
+  if (s.cwd && s.cwd !== ".") parts.push(`cd ${s.cwd} &&`);
+  if (s.env) for (const [k, v] of Object.entries(s.env)) parts.push(`${k}=${v}`);
+  parts.push(...s.argv.map(String));
+  return parts.join(" ");
+};
+// A step is executable only when it is a structured object with a non-empty
+// argv array. Anything else is a stale pre-R2-1 shell string (or malformed);
+// it must be REFUSED, never run as a shell string.
+const isStructuredStep = (s) => !!s && typeof s === "object" && Array.isArray(s.argv) && s.argv.length > 0;
+
+// --trust: record this exact recipe as approved (content-addressed), then
+// proceed. Recorded in the PARENT so every downstream path — including a
+// detached --hook/--background child that re-runs this script — sees it as
+// trusted via the persistent store. Fail LOUDLY if the store cannot be
+// written: a caller that asked to trust must not be told it worked and then
+// silently keep refusing.
+if (trustFlag) {
+  if (trusted) {
+    console.error(`codemap refresh: recipe already trusted (${fingerprint.slice(0, 12)})`);
+  } else {
+    let where;
+    try { where = trustRecipe(fingerprint, cmDir); }
+    catch (e) {
+      console.error(`codemap refresh: FAILED to record trust in ${trustStorePath()}: ${e.message}`);
+      process.exit(1);
+    }
+    console.error(`codemap refresh: recipe trusted (${fingerprint.slice(0, 12)}) — recorded in ${where}`);
+    trusted = true;
+  }
+}
+
+// The refusal: show the exact steps that WOULD run so the user can review
+// them, then how to approve. Non-zero exit so the skill/automation notices and
+// surfaces it rather than silently doing nothing.
+const refuseUntrusted = () => {
+  console.error(`codemap refresh: REFUSING to run an untrusted recipe (${cfgPath})`);
+  console.error(`  fingerprint: ${fingerprint}`);
+  console.error("  steps that would run:");
+  for (const s of steps) console.error(`    $ ${renderStep(s)}`);
+  console.error("this codemap recipe is not trusted; review the steps above and re-run with");
+  console.error("--trust to approve, or run `geml codemap build` to regenerate it.");
+};
+
 if (hookMode) {
   // PostToolUse payload on stdin; only a git commit warrants a refresh.
   let cmd = "";
@@ -68,13 +153,24 @@ if (hookMode) {
 }
 
 if (hookMode || background) {
+  // Never launch an exec child for an untrusted recipe. An empty recipe execs
+  // nothing, so it is not gated. --hook is automatic and must not block the
+  // commit: warn and no-op (exit 0). An explicit --background run surfaces the
+  // refusal with a non-zero exit.
+  if (steps.length && !trusted) {
+    if (hookMode) {
+      console.error(`codemap refresh: recipe not trusted — skipping (review it, then run \`geml codemap refresh ${dir} --trust\`)`);
+      process.exit(0);
+    }
+    refuseUntrusted();
+    process.exit(3);
+  }
   const child = spawn(process.execPath, [process.argv[1], cmDir, ...(force ? ["--force"] : []), ...(autoCommit ? ["--commit"] : [])], { detached: true, stdio: "ignore" });
   child.unref();
   console.error(`codemap refresh: running in background (log: ${logPath})`);
   process.exit(0);
 }
 
-const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
 const root = resolve(cmDir, cfg.root ?? "..");
 let head;
 try {
@@ -112,25 +208,74 @@ if (!force && head && builtFrom) {
   }
 }
 
+// TRUST GATE (foreground exec path). Reached only when the recipe is about to
+// RUN its steps — after the up-to-date / no-source-change skips above, which
+// never exec and so need no gate. This gate is INDEPENDENT of those checks, so
+// forging index.geml's `commit` (or removing git) to force a rebuild cannot
+// bypass it: it only changes which skip is taken, never whether an untrusted
+// recipe may exec. An empty recipe execs nothing and is not gated.
+if (steps.length && !trusted) {
+  refuseUntrusted();
+  process.exit(3);
+}
+
+// VERSION GATE. The on-disk step schema is versioned (RECIPE_VERSION): refuse a
+// recipe recorded in any other format so a FUTURE format change is cleanly
+// detected and the user is pointed at `geml codemap build` to regenerate it. A
+// pre-versioning recipe (no `version` at all) is likewise refused. This judges
+// the STANDALONE schema version, never the parser/`generator` version — the
+// parser bumps every patch release, so using it here would force a full
+// re-index of every project on each release. Reached only on the exec path
+// (after the skips above, which never run steps).
+if (cfg.version !== RECIPE_VERSION) {
+  console.error(`codemap refresh: REFUSING — recipe format out of date (${cfgPath})`);
+  console.error(`  recorded format: v${cfg.version ?? "(pre-versioning)"}; this geml expects v${RECIPE_VERSION}`);
+  console.error("re-run `geml codemap build` to regenerate refresh.json.");
+  process.exit(1);
+}
+// STRUCTURE GUARD (the R2-1 invariant). Even a current-version recipe must not
+// hand a non-structured step to the exec loop: a legacy shell STRING run through
+// a shell is the exact RCE R2-1 closed. Refuse any step that is not a
+// { argv: [...] } object rather than execute it.
+const badIdx = steps.findIndex((s) => !isStructuredStep(s));
+if (badIdx >= 0) {
+  console.error(`codemap refresh: REFUSING — step ${badIdx + 1} is not a { argv: [...] } step (${cfgPath})`);
+  console.error("re-run `geml codemap build` to regenerate refresh.json.");
+  process.exit(1);
+}
+
 appendFileSync(logPath, `\n[${new Date().toISOString()}] refresh @ ${head ?? "no-git"}\n`);
-for (const step of cfg.steps ?? []) {
-  appendFileSync(logPath, `$ ${step}\n`);
+for (const step of steps) {
+  appendFileSync(logPath, `$ ${renderStep(step)}\n`);
+  // Per-step cwd (relative to the project root, forward-slash) and env, merged
+  // over the current environment. Both may hold attacker-controlled dir names —
+  // they ride as a real cwd PATH / discrete argv elements, never shell syntax.
+  const stepCwd = resolve(root, step.cwd || ".");
+  const stepEnv = step.env ? { ...process.env, ...step.env } : process.env;
+  const argv = step.argv.map(String);
   // Stream the step's output STRAIGHT into the log file. Capturing it in
   // memory (spawnSync + encoding) hits the default 1MB maxBuffer — Joern's
   // INFO firehose blew it and the child got killed mid-export (exit null).
   // A file descriptor has no such limit, and the log tails live.
   const fd = openSync(logPath, "a");
-  const r = spawnSync(step, { shell: true, cwd: root, stdio: ["ignore", fd, fd] });
+  const r = process.platform === "win32"
+    // win32: build ONE pre-escaped command line (each element quoted so no arg
+    // can inject), run it through cmd.exe for the .cmd/.bat launchers.
+    ? spawnSync([q(argv[0]), ...argv.slice(1).map(shq)].join(" "),
+      { shell: true, cwd: stepCwd, env: stepEnv, stdio: ["ignore", fd, fd] })
+    // POSIX: exec the program directly with an args array — no shell involved.
+    : spawnSync(argv[0], argv.slice(1),
+      { shell: false, cwd: stepCwd, env: stepEnv, stdio: ["ignore", fd, fd] });
   closeSync(fd);
   if (r.status !== 0) {
     const why = r.status ?? r.signal ?? r.error?.message ?? "killed";
     appendFileSync(logPath, `FAILED (exit ${why})\n`);
-    console.error(`codemap refresh: step failed (exit ${why}): ${step}\n  log: ${logPath}`);
+    console.error(`codemap refresh: step failed (exit ${why}): ${renderStep(step)}\n  log: ${logPath}`);
     process.exit(1);
   }
 }
 appendFileSync(logPath, "ok\n");
-console.error(`codemap refresh: done${head ? ` @ ${head.slice(0, 10)}` : ""} (${(cfg.steps ?? []).length} step(s))`);
+console.error(`codemap refresh: done${head ? ` @ ${head.slice(0, 10)}` : ""} (${steps.length} step(s))`);
 
 // --commit: land the refreshed codemap as its own follow-up commit so it
 // rides the next push with the code. Guards: HEAD must not have moved while
@@ -144,9 +289,14 @@ if (autoCommit && head) {
     console.error(`codemap refresh: not auto-committing (${merging ? "merge in progress" : "HEAD moved during the refresh"}) — refreshed files left in the working tree`);
   } else {
     const rel = relative(root, cmDir).replace(/\\/g, "/") || ".";
+    // Exclude-pathspec prefix: empty when the codemap IS the repo root. A `./`
+    // prefix (what `${rel}/…` yields at rel=".") is rejected by some git
+    // versions inside `:(exclude)…`, silently un-excluding the logs or failing
+    // the commit — so build `_index/…` bare at root, `<rel>/_index/…` in a subdir.
+    const relPrefix = rel === "." ? "" : `${rel}/`;
     // Runtime noise in _index (refresh/serve logs, serve.pid) never belongs in
     // the commit — and this very run appends to refresh.log after committing.
-    const spec = ["--", rel, `:(exclude)${rel}/_index/refresh.log`, `:(exclude)${rel}/_index/serve.log`, `:(exclude)${rel}/_index/serve.pid`];
+    const spec = ["--", rel, `:(exclude)${relPrefix}_index/refresh.log`, `:(exclude)${relPrefix}_index/serve.log`, `:(exclude)${relPrefix}_index/serve.pid`];
     g("add", "-A", ...spec); // new pages need staging; pathspec keeps it surgical
     const c = g("commit", "-m", `chore(codemap): refresh for ${head.slice(0, 7)}`, ...spec);
     if (c.status === 0) {