@lovrozagar/grunt 0.9.4 → 0.10.0

package/scripts/board.mjs

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+/**
+ * Machine-local live agent board. One JSON file per session under ~/.grunt/board/.
+ * A read prints lines whose host process is still alive and deletes the rest.
+ * Fail-open: a probe or IO error skips the write and prints nothing.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const WORK_CAP = 80;
+const MAX_WALK = 4;
+const SHELLS = new Set(["sh", "bash", "dash", "zsh", "ash", "busybox", "cmd", "powershell", "pwsh"]);
+
+function field(value) {
+  const s = String(value ?? "").replace(/\s+/g, "-").trim();
+  return s || "-";
+}
+
+function oneLine(value, cap) {
+  const s = String(value ?? "").replace(/\s+/g, " ").trim();
+  const cut = cap ? s.slice(0, cap).trim() : s;
+  return cut || "-";
+}
+
+function commBase(comm) {
+  const base = String(comm || "").split(/[/\\]/).pop() || "";
+  return base.replace(/\.exe$/i, "").toLowerCase();
+}
+
+function safe(value) {
+  return field(value).replace(/[^\w.@+-]/g, "_") || "-";
+}
+
+export function formatLine(row) {
+  return [
+    field(row.time),
+    field(row.provider),
+    field(row.model),
+    field(row.effort),
+    field(row.session),
+    oneLine(row.cwd),
+    oneLine(row.work, WORK_CAP),
+  ].join(" ");
+}
+
+export function boardHome(env = process.env) {
+  return env.GRUNT_BOARD_HOME || os.homedir();
+}
+
+export function boardDir(home) {
+  return path.join(home, ".grunt", "board");
+}
+
+function rowPath(dir, provider, session) {
+  return path.join(dir, `${safe(provider)}-${safe(session)}.json`);
+}
+
+function readRow(file) {
+  try {
+    const row = JSON.parse(fs.readFileSync(file, "utf8"));
+    return row && typeof row === "object" ? row : null;
+  } catch {
+    return null;
+  }
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try {
+    fs.chmodSync(dir, 0o700);
+  } catch {
+    // Windows cannot always chmod a directory.
+  }
+}
+
+function atomicWrite(file, text) {
+  const tmp = `${file}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+  fs.writeFileSync(tmp, text, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    // Windows cannot always chmod a file.
+  }
+}
+
+export function readBootId({ readFile = fs.readFileSync, platform = process.platform } = {}) {
+  if (platform !== "linux") return "-";
+  try {
+    return String(readFile("/proc/sys/kernel/random/boot_id", "utf8")).trim() || "-";
+  } catch {
+    return "-";
+  }
+}
+
+/** Linux /proc/pid/stat. Field 22 is starttime. comm sits between the first "(" and the last ")". */
+export function parseProcStat(text) {
+  const s = String(text ?? "");
+  const end = s.lastIndexOf(")");
+  const open = s.indexOf("(");
+  if (open < 0 || end < open) return null;
+  const comm = s.slice(open + 1, end);
+  const rest = s.slice(end + 1).trim().split(/\s+/);
+  if (rest.length < 20) return null;
+  const ppid = Number(rest[1]);
+  if (!rest[19] || !Number.isFinite(ppid)) return null;
+  return { comm, state: rest[0], ppid, start: rest[19] };
+}
+
+export function probeProcess(pid, deps = {}) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 1) return null;
+  const platform = deps.platform || process.platform;
+  const readFile = deps.readFile || fs.readFileSync;
+  const spawn = deps.spawn || spawnSync;
+  if (platform === "linux") {
+    try {
+      const parsed = parseProcStat(readFile(`/proc/${n}/stat`, "utf8"));
+      if (!parsed || parsed.state === "Z") return null;
+      return { pid: n, start: parsed.start, comm: parsed.comm, ppid: parsed.ppid };
+    } catch {
+      return null;
+    }
+  }
+  if (platform === "darwin") {
+    const r = spawn("ps", ["-o", "ppid=,lstart=,comm=", "-p", String(n)], { encoding: "utf8" });
+    if (!r || r.status !== 0) return null;
+    const line = String(r.stdout || "").trim();
+    const m = line.match(/^(\d+)\s+([A-Za-z]{3}\s+[A-Za-z]{3}\s+\d+\s+\d{2}:\d{2}:\d{2}\s+\d{4})\s+(\S+)\s*$/);
+    if (!m) return null;
+    return { pid: n, start: m[2], comm: commBase(m[3]), ppid: Number(m[1]) };
+  }
+  if (platform === "win32") {
+    const script = [
+      `$p = Get-CimInstance Win32_Process -Filter "ProcessId=${n}"`,
+      "if (-not $p) { exit 1 }",
+      "$p.ParentProcessId",
+      "$p.Name",
+      "$p.CreationDate.ToUniversalTime().ToString('o')",
+    ].join("; ");
+    const r = spawn("powershell.exe", ["-NoProfile", "-Command", script], { encoding: "utf8" });
+    if (!r || r.status !== 0) return null;
+    const parts = String(r.stdout || "").trim().split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+    if (parts.length < 3) return null;
+    const ppid = Number(parts[0]);
+    if (!Number.isFinite(ppid) || !parts[2]) return null;
+    return { pid: n, start: parts[2], comm: parts[1], ppid };
+  }
+  return null;
+}
+
+export function hostIdentity({ pid = process.pid, probe = probeProcess } = {}) {
+  let current = probe(pid)?.ppid;
+  for (let i = 0; i < MAX_WALK && current && current > 1; i++) {
+    const info = probe(current);
+    if (!info || !(info.pid > 1) || info.start == null || info.start === "") return null;
+    const name = commBase(info.comm);
+    if (!SHELLS.has(name)) return { pid: info.pid, start: String(info.start) };
+    if (!(info.ppid > 1) || info.ppid === current) return null;
+    current = info.ppid;
+  }
+  return null;
+}
+
+export function rowAlive(row, { boot, probe = probeProcess } = {}) {
+  if (!row || row.pid == null || row.start == null || row.start === "") return false;
+  if (String(row.boot ?? "") !== String(boot ?? "")) return false;
+  let info;
+  try {
+    info = probe(row.pid);
+  } catch {
+    return false;
+  }
+  if (!info || info.start == null || info.start === "") return false;
+  return String(info.start) === String(row.start);
+}
+
+export function sweep({ home, boot, probe = probeProcess } = {}) {
+  const dir = boardDir(home);
+  if (!fs.existsSync(dir)) return [];
+  const kept = [];
+  for (const name of fs.readdirSync(dir)) {
+    const file = path.join(dir, name);
+    if (!name.endsWith(".json")) continue;
+    const row = readRow(file);
+    if (!row || !rowAlive(row, { boot, probe })) {
+      fs.rmSync(file, { force: true });
+      continue;
+    }
+    kept.push(row);
+  }
+  kept.sort((a, b) => String(a.time).localeCompare(String(b.time)));
+  return kept;
+}
+
+function nextWork(prev, opts) {
+  if (opts.forceWork) return { work: oneLine(opts.work, WORK_CAP), sticky: true };
+  if (prev?.sticky && prev.work) return { work: String(prev.work), sticky: true };
+  if (opts.work != null && String(opts.work).trim()) return { work: oneLine(opts.work, WORK_CAP), sticky: false };
+  if (prev?.work) return { work: String(prev.work), sticky: false };
+  return { work: "active", sticky: false };
+}
+
+export function note(opts = {}) {
+  const session = String(opts.session ?? "").trim();
+  if (!session || session === "default") return null;
+  if (opts.pid == null || opts.start == null || opts.start === "") return null;
+  const home = opts.home ?? boardHome(opts.env);
+  const dir = boardDir(home);
+  ensureDir(dir);
+  const provider = field(opts.provider);
+  const file = rowPath(dir, provider, session);
+  const prev = readRow(file);
+  const chosen = nextWork(prev, opts);
+  const row = {
+    time: opts.now instanceof Date ? opts.now.toISOString().replace(/\.\d{3}Z$/, "Z") : opts.now ? String(opts.now) : new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+    provider,
+    model: opts.model == null || String(opts.model).trim() === "" ? "-" : String(opts.model),
+    effort: opts.effort == null || String(opts.effort).trim() === "" ? "-" : String(opts.effort),
+    session,
+    cwd: oneLine(opts.cwd),
+    work: chosen.work,
+    sticky: chosen.sticky,
+    pid: Number(opts.pid),
+    start: String(opts.start),
+    boot: String(opts.boot ?? ""),
+  };
+  atomicWrite(file, `${JSON.stringify(row)}\n`);
+  sweep({ home, boot: row.boot, probe: opts.probe });
+  if (!fs.existsSync(file)) return null;
+  return row;
+}
+
+export function lines(opts = {}) {
+  const home = opts.home ?? boardHome(opts.env);
+  const boot = opts.boot ?? readBootId();
+  return sweep({ home, boot, probe: opts.probe }).map(formatLine);
+}
+
+export function digest(opts = {}) {
+  const home = opts.home ?? boardHome(opts.env);
+  const boot = opts.boot ?? readBootId();
+  const selfP = field(opts.provider);
+  const selfS = field(opts.session);
+  return sweep({ home, boot, probe: opts.probe })
+    .filter((row) => !(field(row.provider) === selfP && field(row.session) === selfS))
+    .sort((a, b) => String(b.time).localeCompare(String(a.time)))
+    .slice(0, opts.cap ?? 8)
+    .map(formatLine)
+    .join("\n");
+}
+
+function providerOf(data, env) {
+  if (env.GRUNT_BOARD_PROVIDER) return env.GRUNT_BOARD_PROVIDER;
+  if (env.GROK_WORKSPACE_ROOT || env.GROK_SESSION_ID || env.GROK_HOOK_EVENT) return "grok";
+  if (env.CLAUDE_PROJECT_DIR) return "claude";
+  if (data && data.model) return "codex";
+  return "-";
+}
+
+function modelOf(data) {
+  if (!data || data.model == null || String(data.model).trim() === "") return "-";
+  return String(data.model);
+}
+
+function effortOf(data, env) {
+  const level = data && data.effort && typeof data.effort === "object" ? data.effort.level : data?.effort;
+  if (level != null && String(level).trim() !== "") return String(level);
+  if (env.CLAUDE_EFFORT && String(env.CLAUDE_EFFORT).trim() !== "") return String(env.CLAUDE_EFFORT);
+  return "-";
+}
+
+function sessionOf(data, env) {
+  const value = (data && (data.session_id || data.sessionId)) || env.GROK_SESSION_ID || "";
+  return String(value).trim();
+}
+
+function cwdOf(data, env) {
+  return (
+    env.GROK_WORKSPACE_ROOT ||
+    (data && (data.workspaceRoot || data.workspace_root || data.cwd)) ||
+    env.CLAUDE_PROJECT_DIR ||
+    process.cwd()
+  );
+}
+
+function promptOf(data) {
+  if (!data || typeof data !== "object") return "";
+  return String(data.prompt ?? data.userPrompt ?? data.user_prompt ?? "");
+}
+
+export function recordHook(data, env = process.env, deps = {}) {
+  try {
+    const session = sessionOf(data, env);
+    if (!session || session === "default") return null;
+    const ident = deps.identity || hostIdentity({ probe: deps.probe || probeProcess });
+    if (!ident) return null;
+    const boot = deps.boot || readBootId();
+    return note({
+      home: boardHome(env),
+      env,
+      provider: providerOf(data, env),
+      model: modelOf(data),
+      effort: effortOf(data, env),
+      session,
+      cwd: cwdOf(data, env),
+      work: promptOf(data),
+      pid: ident.pid,
+      start: ident.start,
+      boot,
+      now: deps.now,
+      probe: deps.probe,
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function otherLines(data, env = process.env, deps = {}) {
+  try {
+    return digest({
+      home: boardHome(env),
+      env,
+      provider: providerOf(data, env),
+      session: sessionOf(data, env),
+      boot: deps.boot || readBootId(),
+      probe: deps.probe,
+    });
+  } catch {
+    return "";
+  }
+}
+
+function parseArgs(argv) {
+  const out = { set: false, work: null, home: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "set") out.set = true;
+    else if (arg === "--work") out.work = argv[++i] ?? "";
+    else if (arg.startsWith("--work=")) out.work = arg.slice("--work=".length);
+    else if (arg === "--home") out.home = argv[++i] ?? "";
+    else if (arg.startsWith("--home=")) out.home = arg.slice("--home=".length);
+  }
+  return out;
+}
+
+function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const env = { ...process.env };
+    if (args.home) env.GRUNT_BOARD_HOME = args.home;
+    const home = boardHome(env);
+    if (args.set) {
+      const ident = hostIdentity();
+      if (!ident) return 0;
+      const provider = providerOf({}, env);
+      const session =
+        env.GRUNT_BOARD_SESSION || env.GROK_SESSION_ID || env.CLAUDE_SESSION_ID || String(ident.pid);
+      note({
+        home,
+        env,
+        provider: provider === "-" ? "antigravity" : provider,
+        model: "-",
+        effort: env.CLAUDE_EFFORT || "-",
+        session,
+        cwd: cwdOf({}, env),
+        work: args.work ?? "",
+        forceWork: true,
+        pid: ident.pid,
+        start: ident.start,
+        boot: readBootId(),
+      });
+      return 0;
+    }
+    const printed = lines({ home, env });
+    if (printed.length) process.stdout.write(`${printed.join("\n")}\n`);
+    return 0;
+  } catch {
+    return 0;
+  }
+}
+
+const thisFile = fileURLToPath(import.meta.url);
+const invoked = process.argv[1] ? path.resolve(process.argv[1]) : "";
+if (invoked === thisFile || import.meta.url === pathToFileURL(invoked).href) {
+  process.exit(main());
+}

package/scripts/doctor.mjs

@@ -16,6 +16,7 @@ import {
   detectPackageManager,
   runScriptLine,
 } from "./package-manager.mjs";
+import { selectedPacks } from "./feature-packs.mjs";
 
 export const CHROMIUM_BINS = [
   "chromium",
@@ -229,6 +230,19 @@ function isFile(abs) {
   }
 }
 
+export function jevDoctorStatus({ env = process.env, home = os.homedir() } = {}) {
+  if (String(env.TYPESAFE_API_KEY || "").trim()) return { ok: true, extra: "env" };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(home, ".grunt", "jev.json"), "utf8"));
+    if (String(parsed && parsed.apiKey ? parsed.apiKey : "").trim()) {
+      return { ok: true, extra: "config" };
+    }
+  } catch {
+    /* absent */
+  }
+  return { ok: false, extra: "" };
+}
+
 export function speakDoctorStatus({ env = process.env, home = os.homedir() } = {}) {
   const names = [];
   if (String(env.ELEVENLABS_API_KEY || "").trim()) names.push("elevenlabs");
@@ -377,20 +391,31 @@ export function runDoctor({
   lines.push(rulesync ? row("rulesync", "ok", rulesync) : row("rulesync", "missing"));
   lines.push(lightpanda ? row("lightpanda", "ok", lightpanda) : row("lightpanda", "missing"));
   lines.push(chromium ? row("chromium", "ok", chromium) : row("chromium", "missing"));
+  const enabled = new Set(selectedPacks(cwd));
   lines.push(gh ? row("gh", "ok", gh) : row("gh", "missing (optional)"));
-  lines.push(clasp ? row("clasp", "ok", clasp) : row("clasp", "missing (optional)"));
-  const workspace = workspaceDoctorStatus({ home });
-  lines.push(
-    workspace.ok
-      ? row("google-workspace", "ok", workspace.extra)
-      : row("google-workspace", "missing (optional)"),
-  );
-  lines.push(ffmpeg ? row("ffmpeg", "ok", ffmpeg) : row("ffmpeg", "missing (optional)"));
-  lines.push(
-    whisperCli ? row("whisper-cli", "ok", whisperCli) : row("whisper-cli", "missing (optional)"),
-  );
-  const speak = speakDoctorStatus({ env, home });
-  lines.push(speak.ok ? row("speak", "ok", speak.extra) : row("speak", "missing (optional)"));
+  if (enabled.has("clasp")) {
+    lines.push(clasp ? row("clasp", "ok", clasp) : row("clasp", "missing (optional)"));
+  }
+  if (enabled.has("google-workspace")) {
+    const workspace = workspaceDoctorStatus({ home });
+    lines.push(
+      workspace.ok
+        ? row("google-workspace", "ok", workspace.extra)
+        : row("google-workspace", "missing (optional)"),
+    );
+  }
+  if (enabled.has("listen")) {
+    lines.push(ffmpeg ? row("ffmpeg", "ok", ffmpeg) : row("ffmpeg", "missing (optional)"));
+    lines.push(
+      whisperCli ? row("whisper-cli", "ok", whisperCli) : row("whisper-cli", "missing (optional)"),
+    );
+  }
+  if (enabled.has("speak")) {
+    const speak = speakDoctorStatus({ env, home });
+    lines.push(speak.ok ? row("speak", "ok", speak.extra) : row("speak", "missing (optional)"));
+  }
+  const jev = jevDoctorStatus({ env, home });
+  lines.push(jev.ok ? row("jev", "ok", jev.extra) : row("jev", "missing (optional)"));
 
   const missingRequired = REQUIRED.filter((k) => (k === "node" ? !nodeOk : !found[k]));
   if (!pmOk) missingRequired.push("package-manager");
@@ -444,7 +469,17 @@ export function runDoctor({
   return { code: missingRequired.length || missingMaps.length ? 1 : 0, stdout, stderr: "" };
 }
 
-function main() {
+/** Load dest `scripts/lib/env.mjs` `loadEnv` when that file exists next to this script. */
+export async function loadOptionalConsumerEnv(baseHref = import.meta.url) {
+  const file = fileURLToPath(new URL("./lib/env.mjs", baseHref));
+  if (!fs.existsSync(file)) return false;
+  const { loadEnv } = await import(pathToFileURL(file).href);
+  if (typeof loadEnv === "function") loadEnv();
+  return true;
+}
+
+async function main() {
+  await loadOptionalConsumerEnv();
   const r = runDoctor();
   if (r.stdout) process.stdout.write(r.stdout);
   if (r.stderr) process.stderr.write(r.stderr);
@@ -454,5 +489,8 @@ function main() {
 const thisFile = fileURLToPath(import.meta.url);
 const invoked = process.argv[1] ? path.resolve(process.argv[1]) : "";
 if (invoked === thisFile || import.meta.url === pathToFileURL(invoked).href) {
-  main();
+  main().catch((err) => {
+    process.stderr.write((err && err.message ? err.message : String(err)) + "\n");
+    process.exit(1);
+  });
 }

package/scripts/feature-packs.mjs

@@ -0,0 +1,123 @@
+/** Optional installer packs. The npm package still ships them. Init writes only the selected ones. */
+import fs from "node:fs";
+import path from "node:path";
+
+export const FEATURES_REL = ".rulesync/grunt.features.jsonc";
+
+export const OPTIONAL_PACKS = [
+  { name: "google-workspace", skill: "google-workspace", ref: "google-workspace.md", script: "google-workspace.mjs" },
+  { name: "listen", skill: "listen", ref: "listen.md", script: "listen.mjs" },
+  { name: "speak", skill: "speak", ref: "speak.md", script: "speak.mjs" },
+  { name: "clasp", skill: "clasp", ref: "clasp.md", script: "" },
+];
+
+export const PACK_OPTIONS = OPTIONAL_PACKS.map((pack) => ({ value: pack.name, label: pack.name }));
+
+const SKILL_DIRS = [".rulesync/skills", ".grok/skills", ".claude/skills", ".agents/skills"];
+
+function partsOf(rel) {
+  return String(rel || "").split(/[/\\]/).filter((part) => part && part !== ".");
+}
+
+function knownSet() {
+  return new Set(OPTIONAL_PACKS.map((pack) => pack.name));
+}
+
+function inTableOrder(names) {
+  const on = new Set(names);
+  return OPTIONAL_PACKS.map((pack) => pack.name).filter((name) => on.has(name));
+}
+
+export function normalizePacks(list) {
+  const known = knownSet();
+  const seen = [];
+  for (const raw of list || []) {
+    const name = String(raw || "").trim();
+    if (!name || seen.includes(name)) continue;
+    if (!known.has(name)) throw new Error(`unknown pack ${name}`);
+    seen.push(name);
+  }
+  return inTableOrder(seen);
+}
+
+export function parsePacksFlag(value) {
+  const text = String(value ?? "").trim();
+  if (!text || text === "none") return [];
+  return normalizePacks(text.split(","));
+}
+
+function stripJsonc(text) {
+  return String(text)
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/^\s*\/\/.*$/gm, "");
+}
+
+/** null when the file is missing. Bad JSON or an empty list is `{ packs: [] }`. */
+export function readPacks(dest) {
+  const abs = path.join(dest, FEATURES_REL);
+  if (!fs.existsSync(abs)) return null;
+  try {
+    const data = JSON.parse(stripJsonc(fs.readFileSync(abs, "utf8")));
+    const raw = Array.isArray(data?.packs) ? data.packs : [];
+    const known = knownSet();
+    return { packs: inTableOrder(raw.map((name) => String(name).trim()).filter((name) => known.has(name))) };
+  } catch {
+    return { packs: [] };
+  }
+}
+
+export function selectedPacks(dest) {
+  const saved = readPacks(dest);
+  return saved ? saved.packs : [];
+}
+
+export function writePacks(dest, packs) {
+  const selected = normalizePacks(packs);
+  const abs = path.join(dest, FEATURES_REL);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, `${JSON.stringify({ packs: selected }, null, 2)}\n`);
+}
+
+/** An array, including `[]`, is an answer. Otherwise use the saved file, or nothing. */
+export function resolvePackSelection(dest, packs) {
+  if (Array.isArray(packs)) return { packs: normalizePacks(packs), answered: true };
+  const saved = readPacks(dest);
+  if (saved) return { packs: saved.packs, answered: false };
+  return { packs: [], answered: false };
+}
+
+export function isUnselectedPackPath(rel, selected) {
+  const on = selected instanceof Set ? selected : new Set(selected || []);
+  const parts = partsOf(rel);
+  if (parts.length >= 3 && parts[1] === "skills") {
+    const pack = OPTIONAL_PACKS.find((item) => item.skill === parts[2]);
+    if (pack && !on.has(pack.name)) return true;
+  }
+  if (parts[0] === ".rulesync" && parts[1] === "reference" && parts.length >= 3) {
+    const pack = OPTIONAL_PACKS.find((item) => item.ref === parts[2]);
+    if (pack && !on.has(pack.name)) return true;
+  }
+  return false;
+}
+
+export function unselectedPackRels(selected) {
+  const on = selected instanceof Set ? selected : new Set(selected || []);
+  const rels = [];
+  for (const pack of OPTIONAL_PACKS) {
+    if (on.has(pack.name)) continue;
+    for (const dir of SKILL_DIRS) rels.push(`${dir}/${pack.skill}`);
+    if (pack.ref) rels.push(`.rulesync/reference/${pack.ref}`);
+    if (pack.script) rels.push(`scripts/${pack.script}`);
+  }
+  return rels;
+}
+
+export function unselectedRefNames(selected) {
+  const on = selected instanceof Set ? selected : new Set(selected || []);
+  return new Set(OPTIONAL_PACKS.filter((pack) => pack.ref && !on.has(pack.name)).map((pack) => pack.ref));
+}
+
+export function unselectedScriptNames(selected) {
+  const on = selected instanceof Set ? selected : new Set(selected || []);
+  return new Set(OPTIONAL_PACKS.filter((pack) => pack.script && !on.has(pack.name)).map((pack) => pack.script));
+}

package/scripts/guarded-md.mjs

@@ -111,6 +111,34 @@ export function mergeGuardedContent(existingText, gruntBody) {
   return composeGuardedMarkdown(gruntBody, user, nl);
 }
 
+/** `##` blocks in `existing` whose titles are not in `incoming`. */
+export function extraH2Sections(existing, incoming) {
+  const incomingTitles = new Set(
+    [...String(incoming ?? "").matchAll(/^## (.+)$/gm)].map((m) => m[1].trim()),
+  );
+  const text = String(existing ?? "").replace(/\r\n/g, "\n");
+  const matches = [...text.matchAll(/^## /gm)];
+  if (!matches.length) return "";
+  const chunks = [];
+  for (let i = 0; i < matches.length; i++) {
+    const start = matches[i].index;
+    const end = i + 1 < matches.length ? matches[i + 1].index : text.length;
+    const block = text.slice(start, end).replace(/(?:\n)+$/, "");
+    const title = block.match(/^## (.+)$/m)?.[1].trim();
+    if (title && !incomingTitles.has(title)) chunks.push(block);
+  }
+  return chunks.join("\n\n");
+}
+
+/** Grunt body plus consumer-only `##` sections. No sentinels (INDEX inlines law.md). */
+export function mergeReferenceMarkdown(existing, incoming) {
+  const src = String(incoming ?? "");
+  const extras = extraH2Sections(existing ?? "", src);
+  const base = src.replace(/(?:\r?\n)+$/, "");
+  if (!extras.trim()) return `${base}\n`;
+  return `${base}\n\n${extras.replace(/(?:\n)+$/, "")}\n`;
+}
+
 export function writeMergedGuardedFile(destPath, gruntBody) {
   if (!fs.existsSync(destPath)) {
     fs.writeFileSync(destPath, mergeGuardedContent("", gruntBody));