@lovrozagar/grunt 0.4.2 → 0.5.0

package/scripts/emit-maps.mjs

@@ -0,0 +1,422 @@
+#!/usr/bin/env node
+/** Emit INDEX (aggregate) + skills-map/refs-map slices from one skills+refs scan; law.md is a hand slice. */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { splitFrontmatter } from "./emit-agent-shell-tools.mjs";
+
+export const INDEX_REL = ".rulesync/reference/INDEX.md";
+export const SKILLS_MAP_REL = ".rulesync/reference/skills-map.md";
+export const REFS_MAP_REL = ".rulesync/reference/refs-map.md";
+export const LAW_REL = ".rulesync/reference/law.md";
+const SKILLS_REL = ".rulesync/skills";
+const REFS_REL = ".rulesync/reference";
+const PACKAGED_SKILLS_REL = path.join("node_modules", "@lovrozagar", "grunt", ".rulesync", "skills");
+const BANNER = "<!-- Generated by emit-maps.mjs. Do not hand-edit. -->\n";
+const DESC_MAX = 120;
+const HUGE_BYTES = 512 * 1024;
+const SKIP_REF_NAMES = new Set(["skills-map.md", "refs-map.md", "INDEX.md"]);
+
+export function parseArgv(argv) {
+  const args = Array.isArray(argv) ? argv : [];
+  let check = false;
+  for (const a of args) {
+    if (a === "--check") {
+      check = true;
+      continue;
+    }
+    return { ok: false, error: `unknown flag: ${a}` };
+  }
+  return { ok: true, check };
+}
+
+function unquoteYaml(raw) {
+  const s = String(raw).trim();
+  if (s.length >= 2 && s[0] === '"' && s[s.length - 1] === '"') {
+    try {
+      return JSON.parse(s);
+    } catch {
+      return s.slice(1, -1);
+    }
+  }
+  if (s.length >= 2 && s[0] === "'" && s[s.length - 1] === "'") {
+    return s.slice(1, -1).replace(/''/g, "'");
+  }
+  return s;
+}
+
+function parseFlowSeq(s) {
+  const t = String(s).trim();
+  if (!t.startsWith("[") || !t.endsWith("]")) return null;
+  const inner = t.slice(1, -1).trim();
+  if (!inner) return [];
+  return inner.split(",").map((x) => unquoteYaml(x.trim())).filter((x) => x !== "");
+}
+
+function indentOf(line) {
+  const m = String(line).match(/^[ \t]*/);
+  return m ? m[0].length : 0;
+}
+
+function parseYamlDoc(fm) {
+  const lines = String(fm).split(/\r?\n/);
+  let i = 0;
+  function parseBlock(baseIndent) {
+    const obj = {};
+    while (i < lines.length) {
+      const line = lines[i];
+      if (!line.trim() || /^\s*#/.test(line)) {
+        i += 1;
+        continue;
+      }
+      const ind = indentOf(line);
+      if (ind < baseIndent) break;
+      if (baseIndent > 0 && ind > baseIndent) break;
+      const trimmed = line.trim();
+      const km = trimmed.match(/^([^:#\s][^:]*):\s*(.*?)\s*$/);
+      if (!km) {
+        i += 1;
+        continue;
+      }
+      const key = km[1].trim();
+      const val = km[2];
+      i += 1;
+      if (val === ">" || val === "|") {
+        const parts = [];
+        while (i < lines.length) {
+          const n = lines[i];
+          if (!n.trim()) {
+            parts.push("");
+            i += 1;
+            continue;
+          }
+          if (indentOf(n) <= ind) break;
+          parts.push(n.trim());
+          i += 1;
+        }
+        obj[key] = parts.filter(Boolean).join(" ");
+        continue;
+      }
+      if (val === "") {
+        if (i < lines.length && indentOf(lines[i]) > ind) {
+          const next = lines[i].trim();
+          if (next.startsWith("- ")) {
+            const arr = [];
+            while (i < lines.length && indentOf(lines[i]) > ind && lines[i].trim().startsWith("- ")) {
+              arr.push(unquoteYaml(lines[i].trim().replace(/^- /, "")));
+              i += 1;
+            }
+            obj[key] = arr;
+          } else {
+            obj[key] = parseBlock(indentOf(lines[i]));
+          }
+        } else {
+          obj[key] = {};
+        }
+        continue;
+      }
+      const seq = parseFlowSeq(val);
+      obj[key] = seq != null ? seq : unquoteYaml(val);
+    }
+    return obj;
+  }
+  return parseBlock(0);
+}
+
+function oneLine(s, max = DESC_MAX) {
+  const t = String(s ?? "").replace(/\s+/g, " ").trim();
+  if (t.length <= max) return t;
+  return `${t.slice(0, Math.max(0, max - 1)).trimEnd()}…`;
+}
+
+function cell(s) {
+  return oneLine(s).replace(/\|/g, "\\|");
+}
+
+function readText(abs) {
+  try {
+    return fs.readFileSync(abs, "utf8");
+  } catch (err) {
+    if (err && err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+function lstat(abs) {
+  try {
+    return fs.lstatSync(abs);
+  } catch (err) {
+    if (err && err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+function posixRel(...parts) {
+  return parts.join("/").replace(/\\/g, "/");
+}
+
+function mapRefs(parsed) {
+  if (Array.isArray(parsed["map.refs"])) return parsed["map.refs"].map(String);
+  if (typeof parsed["map.refs"] === "string" && parsed["map.refs"]) return [parsed["map.refs"]];
+  const m = parsed.map;
+  if (m && Array.isArray(m.refs)) return m.refs.map(String);
+  if (m && typeof m.refs === "string" && m.refs) return [m.refs];
+  return [];
+}
+
+function scalarTask(v) {
+  return typeof v === "string" && v !== "" ? v : "";
+}
+
+function mapTask(parsed) {
+  const dotted = scalarTask(parsed["map.task"]);
+  if (dotted) return dotted;
+  const m = parsed.map;
+  if (m && typeof m === "object" && !Array.isArray(m)) return scalarTask(m.task);
+  return "";
+}
+
+function tagsOf(parsed) {
+  if (Array.isArray(parsed.tags)) return parsed.tags.map(String);
+  if (typeof parsed.tags === "string" && parsed.tags) {
+    const seq = parseFlowSeq(parsed.tags);
+    if (seq) return seq.map(String);
+    return [parsed.tags];
+  }
+  return [];
+}
+
+function firstH1(body) {
+  const m = String(body).match(/^#\s+(.+?)\s*$/m);
+  return m ? m[1].replace(/\s+#+\s*$/, "").trim() : "";
+}
+
+function firstSummary(body) {
+  const lines = String(body).split(/\r?\n/);
+  let pastH1 = false;
+  for (const line of lines) {
+    const t = line.trim();
+    if (!pastH1) {
+      if (/^#\s+/.test(t)) pastH1 = true;
+      continue;
+    }
+    if (!t) continue;
+    if (/^#/.test(t) || /^```/.test(t) || /^<!--/.test(t) || /^---/.test(t)) continue;
+    return oneLine(t);
+  }
+  return "";
+}
+
+function parseMarkdown(raw) {
+  const src = String(raw ?? "");
+  const split = splitFrontmatter(src);
+  if (!split.ok) return { parsed: {}, body: src };
+  return { parsed: parseYamlDoc(split.fm), body: split.body };
+}
+
+function listSkillDirs(ws) {
+  const root = path.join(ws, SKILLS_REL);
+  let names;
+  try {
+    names = fs.readdirSync(root, { withFileTypes: true });
+  } catch (err) {
+    if (err && err.code === "ENOENT") return [];
+    throw err;
+  }
+  const out = [];
+  for (const ent of names) {
+    if (!ent.isDirectory() || ent.name.startsWith(".")) continue;
+    const skillAbs = path.join(root, ent.name, "SKILL.md");
+    const st = lstat(skillAbs);
+    if (st && st.isFile()) out.push({ name: ent.name, abs: skillAbs });
+  }
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}
+
+function walkRefMd(dir, relBase, acc) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err && err.code === "ENOENT") return acc;
+    throw err;
+  }
+  for (const ent of entries) {
+    if (ent.name.startsWith(".")) continue;
+    const abs = path.join(dir, ent.name);
+    const rel = relBase ? posixRel(relBase, ent.name) : posixRel(REFS_REL, ent.name);
+    if (ent.isDirectory()) {
+      walkRefMd(abs, rel, acc);
+      continue;
+    }
+    if (!ent.isFile() || !ent.name.endsWith(".md")) continue;
+    if (SKIP_REF_NAMES.has(ent.name)) continue;
+    acc.push({ abs, rel });
+  }
+  return acc;
+}
+
+function packagedSkillExists(ws, name) {
+  const abs = path.join(ws, PACKAGED_SKILLS_REL, name, "SKILL.md");
+  const st = lstat(abs);
+  return Boolean(st && st.isFile());
+}
+
+function skillFields(ws, skill) {
+  const raw = readText(skill.abs);
+  if (raw == null) return null;
+  const { parsed, body } = parseMarkdown(raw);
+  const name = parsed.name != null && parsed.name !== "" ? String(parsed.name) : skill.name;
+  const descSrc =
+    parsed.description != null && parsed.description !== "" ? parsed.description : firstSummary(body);
+  const commandPath = parsed.commandPath != null ? String(parsed.commandPath) : "";
+  const refs = mapRefs(parsed).join(", ");
+  const task = mapTask(parsed);
+  const origin = packagedSkillExists(ws, skill.name) ? "grunt" : "local";
+  return { name, origin, descSrc, commandPath, refs, task };
+}
+
+function skillRowFromFields(f) {
+  return `| ${cell(f.name)} | ${cell(f.origin)} | ${cell(f.descSrc)} | ${cell(f.task)} | ${cell(f.commandPath)} | ${cell(f.refs)} |`;
+}
+
+function refRow(file) {
+  const st = lstat(file.abs);
+  if (!st || !st.isFile()) return null;
+  const fallbackTitle = path.basename(file.rel, ".md");
+  if (st.size > HUGE_BYTES) {
+    return `| ${cell(file.rel)} | ${cell(fallbackTitle)} |  |  |`;
+  }
+  const raw = readText(file.abs);
+  if (raw == null || raw.includes("\0")) {
+    return `| ${cell(file.rel)} | ${cell(fallbackTitle)} |  |  |`;
+  }
+  const { parsed, body } = parseMarkdown(raw);
+  const title = firstH1(body) || fallbackTitle;
+  const tags = tagsOf(parsed).join(", ");
+  const summary = firstSummary(body);
+  return `| ${cell(file.rel)} | ${cell(title)} | ${cell(tags)} | ${cell(summary)} |`;
+}
+
+function skillsTable(rows) {
+  return [
+    "| name | origin | description | task | commandPath | refs |",
+    "| --- | --- | --- | --- | --- | --- |",
+    ...rows,
+  ].join("\n");
+}
+
+function refsTable(rows) {
+  return [
+    "| path | title | tags | summary |",
+    "| --- | --- | --- | --- |",
+    ...rows,
+  ].join("\n");
+}
+
+function renderSkillsMap(rows) {
+  return `${BANNER}\n# Skills map\n\n${skillsTable(rows)}\n`;
+}
+
+function renderRefsMap(rows) {
+  return `${BANNER}\n# Refs map\n\n${refsTable(rows)}\n`;
+}
+
+function readLawBody(ws) {
+  const abs = path.join(ws, LAW_REL);
+  const st = lstat(abs);
+  if (!st || !st.isFile()) {
+    return { ok: false, error: `missing: ${LAW_REL}` };
+  }
+  const raw = readText(abs);
+  if (raw == null) {
+    return { ok: false, error: `missing: ${LAW_REL}` };
+  }
+  const { body } = parseMarkdown(raw);
+  return { ok: true, body: String(body ?? "").replace(/^\uFEFF/, "").replace(/\s+$/, "") };
+}
+
+function renderIndex(lawBody, skillRows, refRows) {
+  return `${BANNER}\n${lawBody}\n\n# Skills\n\n${skillsTable(skillRows)}\n\n# Refs\n\n${refsTable(refRows)}\n`;
+}
+
+function desiredFiles(ws) {
+  const law = readLawBody(ws);
+  if (!law.ok) return law;
+  const fields = listSkillDirs(ws).map((s) => skillFields(ws, s)).filter(Boolean);
+  const skills = fields.map((f) => skillRowFromFields(f));
+  const refs = walkRefMd(path.join(ws, REFS_REL), "", [])
+    .sort((a, b) => a.rel.localeCompare(b.rel))
+    .map(refRow)
+    .filter(Boolean);
+  return {
+    ok: true,
+    files: [
+      { rel: INDEX_REL, text: renderIndex(law.body, skills, refs) },
+      { rel: SKILLS_MAP_REL, text: renderSkillsMap(skills) },
+      { rel: REFS_MAP_REL, text: renderRefsMap(refs) },
+    ],
+  };
+}
+
+export function emitMaps({ workspaceRoot, check = false } = {}) {
+  const ws = workspaceRoot || process.cwd();
+  const rulesync = path.join(ws, ".rulesync");
+  const st = lstat(rulesync);
+  if (!st || !st.isDirectory()) {
+    return { ok: true, check, skipped: true };
+  }
+
+  const desired = desiredFiles(ws);
+  if (!desired.ok) {
+    return { ok: false, check, error: desired.error };
+  }
+  const files = desired.files;
+  if (check) {
+    const drift = [];
+    for (const f of files) {
+      const disk = readText(path.join(ws, f.rel));
+      if (disk !== f.text) drift.push(f.rel);
+    }
+    if (drift.length) {
+      return { ok: false, check: true, error: `drift: ${drift.join(", ")}`, drift };
+    }
+    return { ok: true, check: true, drift: [] };
+  }
+
+  for (const f of files) {
+    const abs = path.join(ws, f.rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, f.text);
+  }
+  return { ok: true, check: false };
+}
+
+function main() {
+  try {
+    const parsed = parseArgv(process.argv.slice(2));
+    if (!parsed.ok) {
+      process.stderr.write((parsed.error || "invalid argv") + "\n");
+      return 1;
+    }
+    const result = emitMaps({
+      workspaceRoot: process.cwd(),
+      check: parsed.check,
+    });
+    if (!result.ok) {
+      process.stderr.write((result.error || "emit failed") + "\n");
+      return 1;
+    }
+    return 0;
+  } catch (err) {
+    process.stderr.write(String(err && err.message ? err.message : err) + "\n");
+    return 1;
+  }
+}
+
+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/guarded-roots.mjs

@@ -11,10 +11,7 @@ import {
   snapshotGuardedRoots,
   withGuardedCheckInteriors,
 } from "../cli/init.mjs";
-
-const GENERATE_RAW = "rulesync:generate:raw";
-const CHECK_RAW = "rulesync:check:raw";
-const WATCH_RAW = "rulesync:watch:raw";
+import { runPipeline } from "./pipeline.mjs";
 
 export function attachGuardedRootWatchers(cwd, heal) {
   const w = fs.watch(cwd, (_event, filename) => {
@@ -36,7 +33,7 @@ export function runGuardedRoots(mode, { cwd = process.cwd(), exec = execSync, at
   if (mode === "generate") {
     const snap = snapshotGuardedRoots(cwd);
     try {
-      exec(`npm run ${GENERATE_RAW}`, { cwd, stdio: "inherit", shell: true });
+      runPipeline("generate", { cwd, exec });
     } finally {
       remergeGuardedRoots(cwd, snap);
     }
@@ -44,7 +41,7 @@ export function runGuardedRoots(mode, { cwd = process.cwd(), exec = execSync, at
   }
   if (mode === "check") {
     withGuardedCheckInteriors(cwd, () => {
-      exec(`npm run ${CHECK_RAW}`, { cwd, stdio: "inherit", shell: true });
+      runPipeline("check", { cwd, exec });
     });
     return;
   }
@@ -54,7 +51,7 @@ export function runGuardedRoots(mode, { cwd = process.cwd(), exec = execSync, at
     const attach = attachWatchers || ((opts) => attachGuardedRootWatchers(opts.cwd, opts.heal));
     const stop = attach({ cwd, snap, heal });
     try {
-      exec(`npm run ${WATCH_RAW}`, { cwd, stdio: "inherit", shell: true });
+      runPipeline("watch", { cwd, exec });
     } finally {
       try {
         stop?.();

package/scripts/pipeline.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/** Inner generate/check/watch chain. Called by guarded-roots; not a public npm script. */
+import { execSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const COMMANDS = {
+  generate: [
+    "rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,subagents,skills",
+    "rulesync generate -t claudecode,codexcli,antigravity-cli -f hooks",
+    "node scripts/emit-mcp-policy.mjs",
+    "node scripts/emit-gemini.mjs",
+    "node scripts/emit-agent-shell-tools.mjs",
+    "node scripts/emit-maps.mjs",
+    "node scripts/hooks-union.mjs",
+  ],
+  check: [
+    "rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,skills --check",
+    "rulesync generate -t codexcli,antigravity-cli,grokcli -f subagents --check",
+    "rulesync generate -t claudecode,codexcli,antigravity-cli -f hooks --check",
+    "node scripts/emit-mcp-policy.mjs --check",
+    "node scripts/emit-gemini.mjs --check",
+    "node scripts/emit-agent-shell-tools.mjs --check",
+    "node scripts/emit-maps.mjs --check",
+    "node scripts/check-globals.mjs",
+    "node scripts/hooks-union.mjs --check",
+  ],
+  watch: [
+    "node scripts/emit-mcp-policy.mjs",
+    "node scripts/emit-gemini.mjs",
+    "node scripts/emit-agent-shell-tools.mjs",
+    "rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,subagents,skills --watch",
+  ],
+};
+
+export function envWithLocalBin(cwd, env = process.env) {
+  const binDir = path.join(cwd, "node_modules", ".bin");
+  const merged = { ...env };
+  const key = Object.keys(merged).find((k) => k.toLowerCase() === "path") || "PATH";
+  merged[key] = `${binDir}${path.delimiter}${merged[key] || ""}`;
+  return merged;
+}
+
+export function runPipeline(mode, { cwd = process.cwd(), exec = execSync } = {}) {
+  const cmds = COMMANDS[mode];
+  if (!cmds) {
+    throw new Error("usage: pipeline.mjs generate|check|watch");
+  }
+  const env = envWithLocalBin(cwd);
+  for (const cmd of cmds) {
+    exec(cmd, { cwd, stdio: "inherit", shell: true, env });
+  }
+}
+
+function main() {
+  try {
+    runPipeline(process.argv[2] || "");
+    return 0;
+  } catch (err) {
+    process.stderr.write((err && err.message ? err.message : String(err)) + "\n");
+    return 1;
+  }
+}
+
+const thisFile = fileURLToPath(import.meta.url);
+const invoked = process.argv[1] ? path.resolve(process.argv[1]) : "";
+if (invoked === thisFile) process.exit(main());

package/scripts/skill-conflicts.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/** Workspace vs packaged grunt skill content conflicts (warn-only). */
+import fs from "node:fs";
+import path from "node:path";
+
+export const WORKSPACE_SKILLS_REL = ".rulesync/skills";
+export const PACKAGED_SKILLS_REL = path.join(
+  "node_modules",
+  "@lovrozagar",
+  "grunt",
+  ".rulesync",
+  "skills",
+);
+
+export function listSkillDirNames(skillsRoot) {
+  let entries;
+  try {
+    entries = fs.readdirSync(skillsRoot, { withFileTypes: true });
+  } catch (err) {
+    if (err && err.code === "ENOENT") return [];
+    throw err;
+  }
+  const out = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory() || ent.name.startsWith(".")) continue;
+    const skillMd = path.join(skillsRoot, ent.name, "SKILL.md");
+    try {
+      if (!fs.statSync(skillMd).isFile()) continue;
+    } catch {
+      continue;
+    }
+    out.push(ent.name);
+  }
+  out.sort((a, b) => a.localeCompare(b));
+  return out;
+}
+
+function readSkillMd(skillsRoot, name) {
+  const abs = path.join(skillsRoot, name, "SKILL.md");
+  try {
+    return fs.readFileSync(abs);
+  } catch {
+    return null;
+  }
+}
+
+/** Names in both trees whose SKILL.md bytes differ. */
+export function findSkillContentConflicts({ workspaceSkillsDir, packagedSkillsDir } = {}) {
+  if (!workspaceSkillsDir || !packagedSkillsDir) return [];
+  const packaged = listSkillDirNames(packagedSkillsDir);
+  if (!packaged.length) return [];
+  const conflicts = [];
+  for (const name of packaged) {
+    const ws = readSkillMd(workspaceSkillsDir, name);
+    if (ws == null) continue;
+    const pkg = readSkillMd(packagedSkillsDir, name);
+    if (pkg == null) continue;
+    if (Buffer.compare(ws, pkg) !== 0) {
+      conflicts.push({
+        name,
+        workspacePath: path.join(workspaceSkillsDir, name, "SKILL.md"),
+        packagedPath: path.join(packagedSkillsDir, name, "SKILL.md"),
+      });
+    }
+  }
+  return conflicts;
+}
+
+export function formatSkillConflictWarn(name) {
+  return `skill \`${name}\` differs from packaged grunt; re-init overwrites`;
+}