@lovrozagar/grunt 0.6.2 → 0.8.0

package/scripts/doctor.mjs

@@ -11,6 +11,11 @@ import {
   findSkillContentConflicts,
   formatSkillConflictWarn,
 } from "./skill-conflicts.mjs";
+import {
+  PACKAGE_MANAGERS,
+  detectPackageManager,
+  runScriptLine,
+} from "./package-manager.mjs";
 
 export const CHROMIUM_BINS = [
   "chromium",
@@ -28,8 +33,7 @@ const RTK_CURL =
   "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh";
 const RTK_DOCS = "https://www.rtk-ai.app/docs/getting-started/installation/";
 const LP_INSTALL_SH = "curl -fsSL https://pkg.lightpanda.io/install.sh | bash";
-const RULESYNC_SCHEMA = "rulesync schema doctor: npm run rulesync:doctor";
-const REQUIRED = ["node", "npm", "git", "rtk", "rulesync", "lightpanda", "chromium"];
+const REQUIRED = ["node", "git", "rtk", "rulesync", "lightpanda", "chromium"];
 export const REQUIRED_MAP_FILES = [
   { name: "INDEX.md", rel: ".rulesync/reference/INDEX.md" },
   { name: "skills-map.md", rel: ".rulesync/reference/skills-map.md" },
@@ -127,7 +131,7 @@ function lookupChromium(pathEnv, platform) {
 
 export function installHints(id, platform = process.platform) {
   if (id === "all") {
-    const keys = ["node", "npm", "git", "rtk", "rulesync", "lightpanda", "chromium"];
+    const keys = ["node", "package-manager", "git", "rtk", "rulesync", "lightpanda", "chromium"];
     return keys.flatMap((k) => installHints(k, platform));
   }
   if (id === "node") {
@@ -139,6 +143,22 @@ export function installHints(id, platform = process.platform) {
   if (id === "npm") {
     return ["npm ships with Node ≥22", NODE_URL];
   }
+  if (id === "yarn") {
+    return ["corepack enable", "npm i -g yarn", "https://yarnpkg.com/getting-started/install"];
+  }
+  if (id === "pnpm") {
+    return ["corepack enable", "npm i -g pnpm", "https://pnpm.io/installation"];
+  }
+  if (id === "bun") {
+    return ["curl -fsSL https://bun.sh/install | bash", "https://bun.sh"];
+  }
+  if (id === "package-manager") {
+    return [
+      "npm ships with Node ≥22",
+      "corepack enable (yarn / pnpm)",
+      "curl -fsSL https://bun.sh/install | bash",
+    ];
+  }
   if (id === "git") {
     if (platform === "win32") return ["winget install Git.Git"];
     if (platform === "darwin") return ["brew install git"];
@@ -151,7 +171,13 @@ export function installHints(id, platform = process.platform) {
     return [RTK_CURL, "brew install rtk"];
   }
   if (id === "rulesync") {
-    return ["npm i -D rulesync", "npx"];
+    return [
+      "npm i -D rulesync",
+      "yarn add -D rulesync",
+      "pnpm add -D rulesync",
+      "bun add -D rulesync",
+      "npx",
+    ];
   }
   if (id === "lightpanda") {
     if (platform === "win32") {
@@ -296,7 +322,17 @@ export function runDoctor({
   const major = nodeMajor(ver);
   const nodeOk = Boolean(nodeBin) && major >= 22;
 
-  const npm = whichBin("npm", pathEnv, platform);
+  const pmBins = Object.fromEntries(
+    PACKAGE_MANAGERS.map((name) => [name, whichBin(name, pathEnv, platform)]),
+  );
+  const detectedPm = detectPackageManager({ cwd, env });
+  const wantedPm = detectedPm.manager
+    ? [detectedPm.manager]
+    : detectedPm.candidates?.length
+      ? detectedPm.candidates
+      : PACKAGE_MANAGERS;
+  const presentPm = wantedPm.filter((name) => pmBins[name]);
+  const pmOk = presentPm.length > 0;
   const git = whichBin("git", pathEnv, platform);
   const rtk = whichBin("rtk", nmPath, platform);
   const rulesync = whichBin("rulesync", nmPath, platform);
@@ -310,7 +346,6 @@ export function runDoctor({
 
   const found = {
     node: nodeOk ? nodeBin : "",
-    npm,
     git,
     rtk,
     rulesync,
@@ -326,7 +361,17 @@ export function runDoctor({
   } else {
     lines.push(row("node", "missing"));
   }
-  lines.push(npm ? row("npm", "ok", npm) : row("npm", "missing"));
+  if (pmOk) {
+    lines.push(
+      row(
+        "package-manager",
+        "ok",
+        presentPm.map((name) => `${name} (${pmBins[name]})`).join(", "),
+      ),
+    );
+  } else {
+    lines.push(row("package-manager", "missing", wantedPm.join(" | ")));
+  }
   lines.push(git ? row("git", "ok", git) : row("git", "missing"));
   lines.push(rtk ? row("rtk", "ok", rtk) : row("rtk", "missing"));
   lines.push(rulesync ? row("rulesync", "ok", rulesync) : row("rulesync", "missing"));
@@ -348,15 +393,20 @@ export function runDoctor({
   lines.push(speak.ok ? row("speak", "ok", speak.extra) : row("speak", "missing (optional)"));
 
   const missingRequired = REQUIRED.filter((k) => (k === "node" ? !nodeOk : !found[k]));
+  if (!pmOk) missingRequired.push("package-manager");
   if (missingRequired.length) {
     lines.push("");
     lines.push("install (print-only; not run):");
     const seen = new Set();
     for (const k of missingRequired) {
-      for (const h of installHints(k, platform)) {
-        if (seen.has(h)) continue;
-        seen.add(h);
-        lines.push(h);
+      const hintIds =
+        k === "package-manager" && wantedPm.length === 1 ? wantedPm : [k];
+      for (const id of hintIds) {
+        for (const h of installHints(id, platform)) {
+          if (seen.has(h)) continue;
+          seen.add(h);
+          lines.push(h);
+        }
       }
     }
   }
@@ -389,7 +439,7 @@ export function runDoctor({
   }
 
   lines.push("");
-  lines.push(RULESYNC_SCHEMA);
+  lines.push(`rulesync schema doctor: ${runScriptLine(detectedPm.manager, "rulesync:doctor")}`);
   const stdout = `${lines.join("\n")}\n`;
   return { code: missingRequired.length || missingMaps.length ? 1 : 0, stdout, stderr: "" };
 }

package/scripts/folder-map.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+/**
+ * Code-only folder map for agents. Folders, never files.
+ *
+ * Source: git ls-files (tracked + untracked, gitignore applied). A folder is
+ * shown when it or a descendant holds a code file and no segment is skipped.
+ * Package roots (package.json, go.mod, Cargo.toml, pyproject.toml) carry
+ * `# name  path`. Single-child chains collapse; plain leaf dirs fold at foldAt.
+ *
+ *   node scripts/folder-map.mjs [dir]
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { stripJsonc } from "./emit-mcp-policy.mjs";
+
+export const DEFAULTS = Object.freeze({
+  budget: 5000,
+  depthCap: 6,
+  foldAt: 12,
+  codeExt: ["ts", "tsx", "js", "jsx", "mjs", "cjs", "py", "go", "rs", "sql", "vue", "svelte", "astro"],
+  skip: [
+    "_gen", "gen", "generated", "dist", "build", "assets", "static", "public",
+    "fixtures", "__fixtures__", "__snapshots__", "__mocks__", "testdata",
+    "vendor", "migrations", "locales", "i18n",
+  ],
+  include: [],
+  exclude: [],
+});
+
+export const CONFIG_REL = ".rulesync/grunt.map.jsonc";
+const MANIFESTS = ["package.json", "go.mod", "Cargo.toml", "pyproject.toml"];
+
+/** DEFAULTS merged with known keys from CONFIG_REL; bad file → defaults + warn. */
+export function loadMapConfig(root, warn = (m) => process.stderr.write(`${m}\n`)) {
+  const abs = path.join(root, CONFIG_REL);
+  if (!fs.existsSync(abs)) return { ...DEFAULTS };
+  let raw;
+  try {
+    raw = JSON.parse(stripJsonc(fs.readFileSync(abs, "utf8")));
+  } catch (err) {
+    warn(`grunt map: ignoring ${CONFIG_REL}: ${err.message}`);
+    return { ...DEFAULTS };
+  }
+  const out = { ...DEFAULTS };
+  for (const [k, v] of Object.entries(raw || {})) {
+    if (!(k in DEFAULTS)) continue;
+    const ok = Array.isArray(DEFAULTS[k])
+      ? Array.isArray(v) && v.every((x) => typeof x === "string")
+      : Number.isFinite(v) && v > 0;
+    if (ok) out[k] = v;
+    else warn(`grunt map: ignoring ${CONFIG_REL} key ${k}`);
+  }
+  return out;
+}
+
+function git(args, cwd) {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+  return r.status === 0 ? r.stdout : null;
+}
+
+/** Repo top and cwd-relative prefix, or null outside git. */
+export function repoRoot(cwd) {
+  const top = git(["rev-parse", "--show-toplevel"], cwd);
+  return top ? top.trim() : null;
+}
+
+/** Tracked + untracked-unignored files, repo-relative, posix. */
+export function listFiles(root) {
+  const out = git(["ls-files", "-z", "--cached", "--others", "--exclude-standard"], root);
+  if (out == null) return null;
+  return [...new Set(out.split("\0").filter(Boolean))];
+}
+
+/** `*` = one segment, `**` = any depth; matches the dir and everything under it. */
+function globRe(glob) {
+  const body = String(glob)
+    .replace(/\/+$/, "")
+    .split("**")
+    .map((part) => part.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*"))
+    .join(".*");
+  return new RegExp(`^${body}(/|$)`);
+}
+
+function packageName(root, dir, manifest) {
+  try {
+    const text = fs.readFileSync(path.join(root, dir, manifest), "utf8");
+    if (manifest === "package.json") return JSON.parse(text).name || "";
+    if (manifest === "go.mod") return (text.match(/^module\s+(\S+)/m) || [])[1] || "";
+    return (text.match(/^name\s*=\s*"([^"]+)"/m) || [])[1] || "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Raw tree from file paths. Node: { name, path, kids: Map, own, pkg }.
+ * `own` = holds a kept file directly. `pkg` is the package name ("" when
+ * unnamed) on package roots, else null.
+ */
+export function buildTree(root, files, opts = {}) {
+  const o = { ...DEFAULTS, ...opts };
+  const code = new RegExp(`\\.(${o.codeExt.join("|")})$`);
+  const skip = new Set(o.skip);
+  const include = o.include.map(globRe);
+  const exclude = o.exclude.map(globRe);
+  const manifests = new Map();
+  for (const f of files) {
+    const base = path.posix.basename(f);
+    if (MANIFESTS.includes(base) && !manifests.has(path.posix.dirname(f))) {
+      manifests.set(path.posix.dirname(f), base);
+    }
+  }
+  const top = { name: "", path: "", kids: new Map(), own: false, pkg: null };
+  for (const f of files) {
+    const dir = path.posix.dirname(f);
+    if (dir === ".") continue;
+    if (exclude.some((re) => re.test(dir))) continue;
+    const forced = include.some((re) => re.test(dir));
+    const segs = dir.split("/");
+    if (!forced) {
+      if (!code.test(f)) continue;
+      if (segs.some((s) => s.startsWith(".") || skip.has(s))) continue;
+    }
+    let node = top;
+    for (const s of segs) {
+      let next = node.kids.get(s);
+      if (!next) {
+        const p = node.path ? `${node.path}/${s}` : s;
+        const m = manifests.get(p);
+        next = { name: s, path: p, kids: new Map(), own: false, pkg: m ? packageName(root, p, m) : null };
+        node.kids.set(s, next);
+      }
+      node = next;
+    }
+    node.own = true;
+  }
+  return top;
+}
+
+/**
+ * Display tree: chains collapsed, leaf dirs folded.
+ * Row: { kind: "dir"|"fold", label, path, pkg, kids: Row[] }.
+ */
+export function displayRows(node, opts = {}) {
+  const o = { ...DEFAULTS, ...opts };
+  const names = [...node.kids.keys()].sort();
+  const leaves = names.filter((n) => {
+    const k = node.kids.get(n);
+    return k.kids.size === 0 && k.pkg == null;
+  });
+  const folded = leaves.length >= o.foldAt ? new Set(leaves) : new Set();
+  const rows = [];
+  if (folded.size) {
+    rows.push({ kind: "fold", label: leaves, path: node.path, pkg: null, kids: [] });
+  }
+  for (const n of names) {
+    if (folded.has(n)) continue;
+    let k = node.kids.get(n);
+    let label = n;
+    // Collapse pass-through dirs only; a dir with its own code stays a row.
+    while (k.kids.size === 1 && k.pkg == null && !k.own) {
+      const [only] = k.kids.values();
+      label = `${label}/${only.name}`;
+      k = only;
+    }
+    rows.push({ kind: "dir", label, path: k.path, pkg: k.pkg, kids: displayRows(k, o) });
+  }
+  return rows;
+}
+
+export function rowText(row, depth, { more = false, base = "" } = {}) {
+  const pad = "  ".repeat(depth);
+  if (row.kind === "fold") {
+    const shown = row.label.slice(0, 6).join(", ");
+    return `${pad}(${row.label.length} leaf dirs: ${shown}${row.label.length > 6 ? ", …" : ""})`;
+  }
+  const full = base ? `${base}/${row.path}` : row.path;
+  let line = `${pad}${row.label}/`;
+  if (row.pkg != null) line += row.pkg ? `  # ${row.pkg}  ${full}` : `  # ${full}`;
+  if (more) line += "  …";
+  return line;
+}
+
+export function tokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Pick rows under the budget, breadth-first by display level.
+ *
+ * Level 0 always shows. Each deeper level is one unit per top-level subtree:
+ * a subtree's rows at that level show together or not at all, so a parent's
+ * kids are never half-listed. Cost is exact in chars: a row with kids is
+ * charged its `…` marker until its kids land. When a level does
+ * not fit, cheapest subtrees take an equal share first; a subtree that misses
+ * its share stops expanding. Rows past depthCap (from the nearest package
+ * root) never expand.
+ */
+function selectRows(rows, o, base) {
+  const levels = [];
+  const visit = (list, depth, top, pkgDepth) => {
+    for (const row of list) {
+      const rel = row.pkg != null ? 0 : pkgDepth;
+      row.top = top ?? row;
+      row.capped = row.kids.length > 0 && rel >= o.depthCap;
+      row.shown = false;
+      (levels[depth] ||= []).push(row);
+      if (!row.capped) visit(row.kids, depth + 1, row.top, rel + 1);
+    }
+  };
+  visit(rows, 0, null, 1);
+  const cost = (row, depth, more) => rowText(row, depth, { more, base }).length + 1;
+  const pointer = (row, depth) => cost(row, depth, true) - cost(row, depth, false);
+  const charge = (row, depth) => cost(row, depth, row.kids.length > 0);
+
+  let used = 0;
+  for (const row of levels[0] || []) {
+    row.shown = true;
+    used += charge(row, 0);
+  }
+  const limit = o.budget * 4;
+  let active = new Set(levels[0] || []);
+  for (let d = 1; d < levels.length && active.size; d++) {
+    const units = new Map();
+    for (const row of levels[d]) {
+      if (!active.has(row.top)) continue;
+      const u = units.get(row.top) || { rows: [], parents: new Set(), cost: 0 };
+      u.rows.push(row);
+      u.cost += charge(row, d);
+      units.set(row.top, u);
+    }
+    for (const row of levels[d - 1]) {
+      const u = units.get(row.top);
+      if (u && row.shown && row.kids.length && !row.capped) u.cost -= pointer(row, d - 1);
+    }
+    const next = new Set();
+    let left = limit - used;
+    const order = [...units.entries()].sort((a, b) => a[1].cost - b[1].cost);
+    order.forEach(([top, u], i) => {
+      const share = left / (order.length - i);
+      if (u.cost > share) return;
+      for (const row of u.rows) row.shown = true;
+      left -= u.cost;
+      used += u.cost;
+      next.add(top);
+    });
+    active = next;
+  }
+  const lines = [];
+  const walk = (list, depth) => {
+    for (const row of list) {
+      if (!row.shown) continue;
+      const open = row.kids.length > 0 && row.kids.some((k) => k.shown);
+      lines.push(rowText(row, depth, { more: row.kids.length > 0 && !open, base }));
+      if (open) walk(row.kids, depth + 1);
+    }
+  };
+  walk(rows, 0);
+  return lines;
+}
+
+/**
+ * Map text for `root` (any dir inside a git repo), scoped to `dir` when set.
+ * Returns { text, rows, tokens } or null outside git.
+ */
+export function folderMap({ root, dir = "", ...opts } = {}) {
+  const top = repoRoot(root);
+  if (!top) return null;
+  const files = listFiles(top);
+  if (!files) return null;
+  const o = { ...loadMapConfig(top), ...opts };
+  const scope = dir ? path.relative(top, path.resolve(root, dir)).split(path.sep).join("/") : "";
+  const scoped = scope
+    ? files.filter((f) => f.startsWith(`${scope}/`)).map((f) => f.slice(scope.length + 1))
+    : files;
+  const tree = buildTree(scope ? path.join(top, scope) : top, scoped, o);
+  const lines = selectRows(displayRows(tree, o), o, scope);
+  const text = lines.length ? `${lines.join("\n")}\n` : "";
+  return { text, rows: lines.length, tokens: tokens(text) };
+}
+
+/** Text for `grunt map [dir]` / `node scripts/folder-map.mjs [dir]` run from `cwd`. */
+export function mapCommand(cwd, dir = "") {
+  const out = folderMap({ root: cwd, dir });
+  if (!out) return "grunt map: not a git repository\n";
+  return out.text || "grunt map: no code folders\n";
+}
+
+function main() {
+  process.stdout.write(mapCommand(process.cwd(), process.argv[2] || ""));
+  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/gate-fat-tools.mjs

@@ -190,9 +190,10 @@ export function pathIsDenied(p) {
   return n.split("/").some((seg) => DENY_PATH_SEGMENTS.has(seg));
 }
 
+/** Top-level "block" is the only legacy deny Claude/Codex validate; allow = empty stdout. */
 export function denyResponse(reason) {
   return {
-    decision: "deny",
+    decision: "block",
     reason,
     hookSpecificOutput: {
       hookEventName: "PreToolUse",
@@ -341,8 +342,9 @@ export function rewriteScratchWrite(filePath, workspaceRoot) {
   return null;
 }
 
-function quoteQuery(q) {
-  return `"${String(q).replace(/"/g, '\\"')}"`;
+/** POSIX single-quote so `, $, and \ stay literal. */
+export function quoteQuery(q) {
+  return `'${String(q).replace(/'/g, "'\\''")}'`;
 }
 
 export function gruntJobCommand(workspaceRoot, args) {
@@ -702,13 +704,15 @@ export function processFatTools(data) {
       }
       return { type: "deny", reason: REASON_DENYLIST };
     }
-    if (BASH_DUMP_CMDS.test(cmd) && !alreadyRtk(cmd)) {
+    // grunt-job and rtk take one plain command; compound shell passes through.
+    const compound = SHELL_META.test(cmd);
+    if (BASH_DUMP_CMDS.test(cmd) && !alreadyRtk(cmd) && !compound) {
       const job = BASH_SEARCH.test(cmd) ? "search" : "exec";
       const q = cmd.replace(/^\s*(rtk\s+)?/, "").trim();
       next.command = gruntJobCommand(ws, `--job ${job} --query ${quoteQuery(q)}`);
       return { type: "rewrite", updatedInput: next };
     }
-    if (BASH_TREE.test(cmd) && !alreadyRtk(cmd)) {
+    if (BASH_TREE.test(cmd) && !alreadyRtk(cmd) && !compound) {
       next.command = `rtk ${cmd.trim()}`;
       return { type: "rewrite", updatedInput: next };
     }

package/scripts/hooks-union.mjs

@@ -6,6 +6,8 @@
  * Claude/Codex native event is UserPromptSubmit (mapped from SoT beforeSubmitPrompt).
  * Antigravity has neither beforeSubmitPrompt nor subagentStop.
  * Grok SessionStart stays empty on orchestrate-parent.json.
+ * Grunt SessionStart: session-map.mjs (folder map) when shipped, first in the group;
+ * Claude/Codex only (rulesync emits no Antigravity sessionStart).
  *
  * Consumer extras (if those scripts exist): SessionStart, check-behind,
  * validate+sim. Path deny from consumer `.rulesync/permissions.json`.
@@ -30,6 +32,9 @@ export const SCRUB =
   'node "${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/scrub-spawn-prompt.mjs"';
 export const GATE_FAT =
   'node "${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/gate-fat-tools.mjs"';
+export const MAP =
+  'node "${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/session-map.mjs"';
+const MAP_NEEDLE = "session-map.mjs";
 
 export const AUTORUN_NEEDLES = [
   "daily-pull-check.mjs",
@@ -173,8 +178,14 @@ function desiredPre(root) {
   return pre;
 }
 
-function desiredSession(root) {
+function mapNeedles(root) {
+  return hasScript(root, MAP_NEEDLE) ? [MAP_NEEDLE] : [];
+}
+
+/** `map: false` for hosts rulesync emits no sessionStart for (Antigravity). */
+function desiredSession(root, { map = true } = {}) {
   const hooks = [];
+  if (map && hasScript(root, MAP_NEEDLE)) hooks.push(hookCmd(MAP, 5));
   if (hasScript(root, "daily-pull-check.mjs")) hooks.push(hookCmd(PULL));
   if (hasScript(root, "rtk-check.mjs")) hooks.push(hookCmd(RTK));
   if (hasScript(root, "daily-fleet-check.mjs")) hooks.push(hookCmd(FLEET));
@@ -264,7 +275,7 @@ function applyAgents(root) {
   const live = loadJson(abs);
   const rulesync = isPlainObject(live.rulesync) ? { ...live.rulesync } : {};
   rulesync.PreToolUse = upsertGroups(rulesync.PreToolUse, desiredPre(root));
-  const session = desiredSession(root);
+  const session = desiredSession(root, { map: false });
   if (session) {
     rulesync.SessionStart = [{ matcher: ".*", hooks: session[0].hooks }];
   }
@@ -320,12 +331,12 @@ export function checkUnion(opts = {}) {
     {
       id: "claude",
       path: ".claude/settings.json",
-      needles: [...GRUNT_NEEDLES, ...autorun, ...loadConsumerDeny(root)],
+      needles: [...GRUNT_NEEDLES, ...mapNeedles(root), ...autorun, ...loadConsumerDeny(root)],
     },
     {
       id: "codex",
       path: ".codex/hooks.json",
-      needles: [...GRUNT_NEEDLES, ...autorun],
+      needles: [...GRUNT_NEEDLES, ...mapNeedles(root), ...autorun],
     },
     {
       id: "agents",