@lovrozagar/grunt 0.8.3 → 0.9.2

package/.grok/hooks/rtk-grok.js

@@ -4,9 +4,8 @@
 Fail-open: parse error, missing rtk, timeout, no rewrite → empty stdout, exit 0.
 Keep the full toolInput (Grok needs `description`); only replace `command`.
 */
-"use strict";
-
-const { spawnSync } = require("node:child_process");
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
 
 const RTK_TIMEOUT_MS = 3000;
 
@@ -108,7 +107,6 @@ function rewrite(cmd) {
 
 /** Read one JSON value (Python json.load): stop when parseable, do not wait for EOF. */
 function readJsonValue() {
-  const fs = require("node:fs");
   let buf = Buffer.alloc(0);
   const tmp = Buffer.alloc(8192);
   for (;;) {

package/.rulesync/rules/overview.md

@@ -8,7 +8,7 @@ targets:
 globs:
   - "**/*"
 ---
-You are the session agent. Do the work. Use en-US unless asked. Write concise complete sentences with natural grammar. Skip filler and fluff. Ship optimal solutions only; rewrite if not. Flag blockers. Do not monkey-patch. Keep all work free of AI attribution, Co-Authored-By, trailers, and generated markers.
+You are the session agent. Do the work. Use en-US unless asked. Write concise complete sentences with natural grammar. Skip filler and fluff. Ship optimal solutions only; rewrite if not. Flag blockers. Do not monkey-patch. When advising, recommend the optimal choice based on research, data, and reasoning, not the user's preference. Change it only for new evidence or a flaw found in it. Pushback or a leading question is not a reason to switch; keep the recommendation and explain why. Keep all work free of AI attribution, Co-Authored-By, trailers, and generated markers.
 
 Size first. Straight shot: do it. Else read `.rulesync/reference/scope.md`.
 Default `/auto`: keep going; ask on blockers. `/ask`: one step, then ask.

package/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- grunt:begin -->
-You are the session agent. Do the work. Use en-US unless asked. Write concise complete sentences with natural grammar. Skip filler and fluff. Ship optimal solutions only; rewrite if not. Flag blockers. Do not monkey-patch. Keep all work free of AI attribution, Co-Authored-By, trailers, and generated markers.
+You are the session agent. Do the work. Use en-US unless asked. Write concise complete sentences with natural grammar. Skip filler and fluff. Ship optimal solutions only; rewrite if not. Flag blockers. Do not monkey-patch. When advising, recommend the optimal choice based on research, data, and reasoning, not the user's preference. Change it only for new evidence or a flaw found in it. Pushback or a leading question is not a reason to switch; keep the recommendation and explain why. Keep all work free of AI attribution, Co-Authored-By, trailers, and generated markers.
 
 Size first. Straight shot: do it. Else read `.rulesync/reference/scope.md`.
 Default `/auto`: keep going; ask on blockers. `/ask`: one step, then ask.

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-10-04
+
+### Fixed
+
+- 0.9.0 was tagged but not published because CI failed the 100% coverage gate on `cli/self-update.mjs`. 0.9.1 ships the 0.9.0 changes
+
+## [0.9.0] - 2026-10-04
+
+### Added
+
+- `grunt upgrade` updates grunt itself: it checks the registry, installs the newer `@lovrozagar/grunt` as a devDependency with the detected package manager, and re-runs with the new bin. `--no-self-update` opts out; offline falls back to the running version
+- Root rule: recommend the optimal choice from research, data, and reasoning, and change it only for new evidence or a found flaw, not for pushback or a leading question
+
 ## [0.8.3] - 2026-10-03
 
 ### Changed

package/README.md

@@ -84,7 +84,7 @@ Rulesync schema doctor is separate: `grunt:rulesync:doctor` (or SoT `rulesync:do
 - `purge-mcps` → run `grunt:purge:global-mcps` (dry-run); `--apply` → `grunt:purge:global-mcps:apply`
 - `doctor` → run `grunt:doctor` (`grunt doctor` / `node scripts/doctor.mjs` stay). Rulesync schema: `grunt:rulesync:doctor`
 - `setup` → run `grunt:setup` (`node scripts/setup.mjs`) — handheld speak / listen / google-workspace / browser. TTY walks each; flags for non-TTY keys/`--creds`
-- `upgrade` → same merge as init for an already-inited repo: copy owned trees/scripts, prune retired grunt-owned names, print reserved skill names
+- `upgrade` → install the latest grunt as a devDependency and re-run with it, then the same merge as init for an already-inited repo: copy owned trees/scripts, prune retired grunt-owned names, print reserved skill names
 - `map [dir]` → code-only folder map (`scripts/folder-map.mjs`); no package manager needed. See [Folder map](#folder-map)
 - `help`
 - `version`
@@ -92,6 +92,7 @@ Rulesync schema doctor is separate: `grunt:rulesync:doctor` (or SoT `rulesync:do
 ### Flags
 
 - `--skip-globals` — skip `sync:globals:apply` on init
+- `--no-self-update` — `upgrade` keeps the installed grunt version
 - `--yes` / `-y` / `--non-interactive` — no TTY menu; default command still `init`. Not `--apply`
 - `--apply` — write for `sync-globals` / `purge-mcps`
 - `--host <id>` — `sync-globals --host <id>`
@@ -116,12 +117,14 @@ Rulesync schema doctor is separate: `grunt:rulesync:doctor` (or SoT `rulesync:do
 Already-inited consumer (0.5.x → 0.6, and later):
 
 ```
-npm i -D @lovrozagar/grunt@latest && npm exec grunt upgrade
-pnpm add -D @lovrozagar/grunt@latest && pnpm exec grunt upgrade
-yarn add -D @lovrozagar/grunt@latest && yarn grunt upgrade
-bun add -D @lovrozagar/grunt@latest && bunx grunt upgrade
+npm exec grunt upgrade
+pnpm exec grunt upgrade
+yarn grunt upgrade
+bunx grunt upgrade
 ```
 
+`upgrade` checks the registry (`npm_config_registry`, else npmjs) for the latest `@lovrozagar/grunt`. When it is newer than the running copy, `upgrade` adds it as a devDependency with the detected package manager (`-w` at a pnpm workspace root), then re-runs the same command with the installed bin so the merge uses the new package. Offline or a failed check prints one warning and upgrades with the running version. `--no-self-update` skips the check. The grunt repo itself and local builds newer than the registry never self-update.
+
 `upgrade` is init plus a reserved-names print. Same merge, prune, and globals-skip rules as Init. New skills/scripts appear because they are in the package copy list. Dropped grunt-owned files disappear only if they are on the retired lists (or a reserved skill this package no longer ships). Do not expect a blind dest-dir mirror-delete; that would wipe consumer extras.
 
 ## Agents

package/bin/grunt.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { start } from "../cli/grunt.mjs"
 
-start().catch(() => {
+start().catch((err) => {
+  process.stderr.write(`grunt: ${err?.message ?? err}\n`)
   process.exit(1)
 })

package/cli/grunt.mjs

@@ -1,9 +1,10 @@
-import { execFileSync } from "node:child_process"
+import { execFileSync } from "./spawn.mjs"
 import { readFileSync } from "node:fs"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
 import { destAlreadyInited, init, RESERVED_SKILLS, toGruntScriptName } from "./init.mjs"
 import { confirm, isInteractive, select, spinner } from "./prompt.mjs"
+import { selfUpdate } from "./self-update.mjs"
 import {
   PACKAGE_MANAGER_ASK,
   PACKAGE_MANAGER_OPTIONS,
@@ -28,13 +29,14 @@ Commands:
   purge-mcps    run grunt:purge:global-mcps (dry-run; --apply to write)
   doctor        run grunt:doctor
   setup         run grunt:setup — handheld keys/OAuth (speak, listen, google-workspace, browser)
-  upgrade       Re-init: copy owned files, prune retired grunt-owned names, print reserved skills
+  upgrade       Self-update to the latest grunt, then re-init: copy owned files, prune retired names, print reserved skills
   map [dir]     Code-only folder map (git-tracked, no files); dir for depth
   help          Show this help
   version       Print package version
 
 Flags:
   --skip-globals     Skip sync:globals:apply (auto-skipped when already initialized)
+  --no-self-update   upgrade: keep the installed grunt version
   --yes, -y          Non-interactive (not --apply)
   --non-interactive  Same as --yes
   --apply            Write for sync-globals / purge-mcps
@@ -86,6 +88,7 @@ function pmValueOk(v) {
 
 export function parseArgv(argv) {
   let skipGlobals = false
+  let noSelfUpdate = false
   let apply = false
   let host
   let hostError = false
@@ -98,6 +101,10 @@ export function parseArgv(argv) {
       skipGlobals = true
       continue
     }
+    if (a === "--no-self-update") {
+      noSelfUpdate = true
+      continue
+    }
     if (YES_FLAGS.has(a)) continue
     if (a === "--apply") {
       apply = true
@@ -136,7 +143,17 @@ export function parseArgv(argv) {
     }
     positionals.push(a)
   }
-  return { cmd: positionals[0], args: positionals.slice(1), skipGlobals, apply, host, hostError, pm, pmError }
+  return {
+    cmd: positionals[0],
+    args: positionals.slice(1),
+    skipGlobals,
+    noSelfUpdate,
+    apply,
+    host,
+    hostError,
+    pm,
+    pmError,
+  }
 }
 
 function hostExtra(host) {
@@ -238,6 +255,19 @@ async function dispatch(cmd, flags, interactive, pm) {
     return
   }
   if (cmd === "upgrade") {
+    if (!flags.noSelfUpdate) {
+      const updated = await selfUpdate({
+        cwd: process.cwd(),
+        pkgRoot: PKG_ROOT,
+        currentVersion: pkgVersion(),
+        pm,
+        argv: process.argv.slice(2),
+      })
+      if (updated.reexeced) {
+        process.exitCode = updated.status
+        return
+      }
+    }
     await runInit(process.cwd(), {
       skipGlobals: flags.skipGlobals,
       interactive: false,

package/cli/grunt.test.ts

@@ -19,6 +19,7 @@ const spinner = vi.hoisted(() =>
   vi.fn(() => ({ start: vi.fn(), stop: vi.fn() })),
 );
 const bailIfCancel = vi.hoisted(() => vi.fn((v) => v));
+const selfUpdate = vi.hoisted(() => vi.fn(async () => ({ reexeced: false })));
 const mapCommand = vi.hoisted(() => vi.fn((_cwd: string, dir: string) => `map:${dir}\n`));
 
 vi.mock("./init.mjs", () => ({
@@ -29,7 +30,8 @@ vi.mock("./init.mjs", () => ({
   RESERVED_SKILLS: ["browser", "tmp", "write-plan"],
   GRUNT_NPM_PREFIX: "grunt:",
 }));
-vi.mock("node:child_process", () => ({ execFileSync }));
+vi.mock("./spawn.mjs", () => ({ execFileSync }));
+vi.mock("./self-update.mjs", () => ({ selfUpdate }));
 vi.mock("../scripts/folder-map.mjs", () => ({ mapCommand }));
 vi.mock("../scripts/package-manager.mjs", async (importOriginal) => {
   const actual = await importOriginal<typeof import("../scripts/package-manager.mjs")>();
@@ -67,13 +69,14 @@ Commands:
   purge-mcps    run grunt:purge:global-mcps (dry-run; --apply to write)
   doctor        run grunt:doctor
   setup         run grunt:setup — handheld keys/OAuth (speak, listen, google-workspace, browser)
-  upgrade       Re-init: copy owned files, prune retired grunt-owned names, print reserved skills
+  upgrade       Self-update to the latest grunt, then re-init: copy owned files, prune retired names, print reserved skills
   map [dir]     Code-only folder map (git-tracked, no files); dir for depth
   help          Show this help
   version       Print package version
 
 Flags:
   --skip-globals     Skip sync:globals:apply (auto-skipped when already initialized)
+  --no-self-update   upgrade: keep the installed grunt version
   --yes, -y          Non-interactive (not --apply)
   --non-interactive  Same as --yes
   --apply            Write for sync-globals / purge-mcps
@@ -108,6 +111,8 @@ describe("start", () => {
     shouldAutoSkipGlobals.mockReset();
     shouldAutoSkipGlobals.mockReturnValue(false);
     execFileSync.mockReset();
+    selfUpdate.mockReset();
+    selfUpdate.mockResolvedValue({ reexeced: false });
     detectPackageManager.mockReset();
     detectPackageManager.mockImplementation((...args: unknown[]) =>
       (actualDetect.fn as (...a: unknown[]) => unknown)(...args),
@@ -322,6 +327,38 @@ describe("start", () => {
     });
     expect(chunks.join("")).toBe("reserved: browser tmp write-plan\n");
     expect(select).not.toHaveBeenCalled();
+    expect(selfUpdate).toHaveBeenCalledOnce();
+    expect(selfUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        cwd: process.cwd(),
+        pkgRoot,
+        currentVersion: version,
+        pm: "npm",
+        argv: ["upgrade"],
+      }),
+    );
+  });
+
+  it("upgrade stops after a self-update re-exec and keeps its exit code", async () => {
+    process.argv = ["node", "grunt", "upgrade"];
+    selfUpdate.mockResolvedValue({ reexeced: true, status: 2 });
+    await start();
+    expect(init).not.toHaveBeenCalled();
+    expect(chunks.join("")).toBe("");
+    expect(process.exitCode).toBe(2);
+  });
+
+  it("upgrade --no-self-update skips the self-update", async () => {
+    process.argv = ["node", "grunt", "upgrade", "--no-self-update"];
+    await start();
+    expect(selfUpdate).not.toHaveBeenCalled();
+    expect(init).toHaveBeenCalledOnce();
+  });
+
+  it("other commands never self-update", async () => {
+    process.argv = ["node", "grunt", "doctor"];
+    await start();
+    expect(selfUpdate).not.toHaveBeenCalled();
   });
 
   it("map prints the folder map without a package manager", async () => {
@@ -598,6 +635,17 @@ describe("parseArgv --host", () => {
   });
 });
 
+describe("parseArgv --no-self-update", () => {
+  it("sets the flag without a positional", () => {
+    expect(parseArgv(["upgrade", "--no-self-update"])).toMatchObject({
+      cmd: "upgrade",
+      args: [],
+      noSelfUpdate: true,
+    });
+    expect(parseArgv(["upgrade"])).toMatchObject({ noSelfUpdate: false });
+  });
+});
+
 describe("parseArgv --pm", () => {
   it("pair and equals", () => {
     expect(parseArgv(["generate", "--pm", "PNPM"])).toMatchObject({

package/cli/init.mjs

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process"
+import { execFileSync } from "./spawn.mjs"
 import fs from "node:fs"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
@@ -53,6 +53,7 @@ export const PRODUCT_SCRIPTS = [
   "guarded-md.mjs",
   "guarded-roots.mjs",
   "emit-mcp-policy.mjs",
+  "jsonc.mjs",
   "folder-map.mjs",
   "gate-fat-tools.mjs",
   "hooks-union.mjs",
@@ -286,7 +287,8 @@ export function mergeClaudeSettings(destRoot, pkgRoot) {
         merged.push(item)
       }
     }
-    destPerms[key] = merged
+    // No empty list the source never had, so a re-init does not rewrite the file.
+    if (merged.length || key in destPerms) destPerms[key] = merged
   }
   destSettings.permissions = destPerms
 
@@ -433,6 +435,21 @@ export function mergePackageJson(dest, pkgRoot) {
   fs.writeFileSync(destPath, `${JSON.stringify(destPkg, null, 2)}\n`)
 }
 
+/**
+ * Recursive overwrite copy on readdir/readFile/writeFile. Not fs.cpSync: it runs in
+ * native code, so Yarn PnP (`yarn dlx`, package inside a zip) cannot serve it.
+ */
+export function copyTree(src, dest, filter = () => true) {
+  if (!filter(src)) return
+  const st = fs.statSync(src)
+  if (st.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true })
+    for (const name of fs.readdirSync(src)) copyTree(path.join(src, name), path.join(dest, name), filter)
+    return
+  }
+  fs.writeFileSync(dest, fs.readFileSync(src), { mode: st.mode })
+}
+
 function copyRootIfMissing(dest, pkgRoot) {
   for (const file of COPY_ROOT_IF_MISSING) {
     const src = path.join(pkgRoot, file)
@@ -496,20 +513,12 @@ export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileS
       fs.mkdirSync(d, { recursive: true })
       if (samePath(src, d)) continue
       if (dir === ".claude") {
-        fs.cpSync(src, d, {
-          recursive: true,
-          force: true,
-          filter: (s) => path.basename(s) !== "settings.json",
-        })
+        copyTree(src, d, (s) => path.basename(s) !== "settings.json")
         mergeClaudeSettings(dest, pkgRoot)
       } else if (dir === ".rulesync") {
-        fs.cpSync(src, d, {
-          recursive: true,
-          force: true,
-          filter: (s) => !GENERATED_MAP_FILES.has(path.basename(s)),
-        })
+        copyTree(src, d, (s) => !GENERATED_MAP_FILES.has(path.basename(s)))
       } else {
-        fs.cpSync(src, d, { recursive: true, force: true })
+        copyTree(src, d)
       }
     }
 
@@ -524,9 +533,7 @@ export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileS
       const src = path.join(pkgRoot, "scripts", name)
       const d = path.join(dest, "scripts", name)
       if (samePath(src, d)) continue
-      const st = fs.statSync(src)
-      if (st.isDirectory()) fs.cpSync(src, d, { recursive: true, force: true })
-      else fs.copyFileSync(src, d)
+      copyTree(src, d)
     }
 
     fs.mkdirSync(path.join(dest, ".tmp"), { recursive: true })

package/cli/init.test.ts

@@ -20,6 +20,7 @@ import {
   MAX_GUARDED_MARKDOWN_BYTES,
   PRODUCT_SCRIPTS,
   composeGuardedMarkdown,
+  copyTree,
   destAlreadyInited,
   extractGruntBody,
   extractUserMarkdown,
@@ -835,6 +836,36 @@ describe("snapshot/remerge guarded roots", () => {
   });
 });
 
+describe("copyTree", () => {
+  it("copies nested files, overwrites existing ones, and honors the filter", () => {
+    const src = tmp("copytree-src-");
+    fs.mkdirSync(path.join(src, "a", "b"), { recursive: true });
+    fs.writeFileSync(path.join(src, "a", "b", "keep.txt"), "new");
+    fs.writeFileSync(path.join(src, "a", "skip.txt"), "skip");
+    fs.writeFileSync(path.join(src, "top.txt"), "top");
+    const dest = tmp("copytree-dest-");
+    fs.mkdirSync(path.join(dest, "a", "b"), { recursive: true });
+    fs.writeFileSync(path.join(dest, "a", "b", "keep.txt"), "old");
+    fs.writeFileSync(path.join(dest, "mine.txt"), "mine");
+
+    copyTree(src, dest, (s) => path.basename(s) !== "skip.txt");
+
+    expect(fs.readFileSync(path.join(dest, "a", "b", "keep.txt"), "utf8")).toBe("new");
+    expect(fs.readFileSync(path.join(dest, "top.txt"), "utf8")).toBe("top");
+    expect(fs.existsSync(path.join(dest, "a", "skip.txt"))).toBe(false);
+    expect(fs.readFileSync(path.join(dest, "mine.txt"), "utf8")).toBe("mine");
+  });
+
+  it("never calls fs.cpSync (Yarn PnP zips cannot serve it)", () => {
+    const cp = vi.spyOn(fs, "cpSync");
+    const src = tmp("copytree-nocp-");
+    fs.writeFileSync(path.join(src, "f.txt"), "x");
+    copyTree(src, tmp("copytree-nocp-dest-"));
+    expect(cp).not.toHaveBeenCalled();
+    cp.mockRestore();
+  });
+});
+
 describe("mergeClaudeSettings", () => {
   it("dest .claude/settings.json absent: plain copy", () => {
     const pkgRoot = stubPkgRoot();
@@ -846,6 +877,30 @@ describe("mergeClaudeSettings", () => {
     expect(out).toEqual(SRC_CLAUDE_SETTINGS);
   });
 
+  it("re-merge is a byte-for-byte no-op (no empty allow added)", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-idempotent-");
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const settingsPath = path.join(destRoot, ".claude", "settings.json");
+    const first = fs.readFileSync(settingsPath, "utf8");
+    mergeClaudeSettings(destRoot, pkgRoot);
+    expect(fs.readFileSync(settingsPath, "utf8")).toBe(first);
+    expect(JSON.parse(first).permissions).not.toHaveProperty("allow");
+  });
+
+  it("keeps an empty allow list the consumer wrote", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-empty-allow-");
+    fs.mkdirSync(path.join(destRoot, ".claude"), { recursive: true });
+    fs.writeFileSync(
+      path.join(destRoot, ".claude", "settings.json"),
+      JSON.stringify({ permissions: { allow: [] } }),
+    );
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(destRoot, ".claude", "settings.json"), "utf8"));
+    expect(out.permissions.allow).toEqual([]);
+  });
+
   it("malformed dest JSON throws with the path in the message", () => {
     const pkgRoot = stubPkgRoot();
     const destRoot = tmp("settings-malformed-");
@@ -2263,6 +2318,8 @@ const PARENT_IMPORT_RE =
   /(?:from\s+|import\s*\(\s*)["'`](\.\.[^"'`]*)["'`]/g;
 const RELATIVE_IMPORT_RE =
   /(?:from\s+|import\s*\(\s*)["'`](\.[^"'`]+)["'`]/g;
+const ANY_IMPORT_RE =
+  /^\s*(?:import|export)\b[\w\s{},*$]*?(?:\bfrom\s*)?["'`]([^"'`]+)["'`]|\bimport\s*\(\s*["'`]([^"'`]+)["'`]/gm;
 
 function relativeSpecs(text: string, re: RegExp) {
   const out: string[] = [];
@@ -2280,6 +2337,29 @@ describe("product scripts are consumer-safe", () => {
     }
   });
 
+  it("bin graph imports only builtins and runtime dependencies (bunx/npx skip devDependencies)", () => {
+    const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"));
+    const runtime = new Set(Object.keys(pkg.dependencies ?? {}));
+    const seen = new Set<string>();
+    const bad: string[] = [];
+    const walk = (file: string) => {
+      if (seen.has(file)) return;
+      seen.add(file);
+      const text = fs.readFileSync(file, "utf8");
+      for (const m of text.matchAll(ANY_IMPORT_RE)) {
+        const spec = m[1] ?? m[2];
+        if (spec.startsWith(".")) walk(path.resolve(path.dirname(file), spec));
+        else if (!spec.startsWith("node:")) {
+          const name = spec.startsWith("@") ? spec.split("/").slice(0, 2).join("/") : spec.split("/")[0];
+          if (!runtime.has(name)) bad.push(`${path.relative(PKG_ROOT, file)} -> ${spec}`);
+        }
+      }
+    };
+    walk(path.join(PKG_ROOT, "bin", "grunt.js"));
+    expect(seen.has(path.join(PKG_ROOT, "scripts", "folder-map.mjs"))).toBe(true);
+    expect(bad).toEqual([]);
+  });
+
   it("do not parent-import (from or import()) — init copies scripts/ only", () => {
     for (const name of PRODUCT_FILES) {
       const text = fs.readFileSync(path.join(PKG_ROOT, "scripts", name), "utf8");

package/cli/self-update.mjs

@@ -0,0 +1,97 @@
+import { spawnSync } from "./spawn.mjs"
+import fs from "node:fs"
+import path from "node:path"
+import { GRUNT_PACKAGE, samePath } from "./init.mjs"
+import { addDevArgs } from "../scripts/package-manager.mjs"
+
+/** Set on the re-execed child so it never self-updates again. */
+export const REEXEC_ENV = "GRUNT_SELF_UPDATED"
+const DEFAULT_REGISTRY = "https://registry.npmjs.org"
+const TIMEOUT_MS = 5000
+const VERSION_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/
+
+function parseVersion(v) {
+  const m = VERSION_RE.exec(String(v).trim())
+  if (!m) return null
+  return { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ?? null }
+}
+
+/** -1 | 0 | 1. A prerelease sorts below its release. */
+export function compareVersions(a, b) {
+  const pa = parseVersion(a)
+  const pb = parseVersion(b)
+  for (let i = 0; i < 3; i++) {
+    if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] < pb.nums[i] ? -1 : 1
+  }
+  if (pa.pre === pb.pre) return 0
+  if (pa.pre == null) return 1
+  if (pb.pre == null) return -1
+  return pa.pre < pb.pre ? -1 : 1
+}
+
+/** Latest dist-tag version, or null when the registry is unreachable or answers junk. */
+export async function fetchLatestVersion({ fetch = globalThis.fetch, env = process.env } = {}) {
+  const base = String(env.npm_config_registry || DEFAULT_REGISTRY).replace(/\/+$/, "")
+  const url = `${base}/${GRUNT_PACKAGE.replace("/", "%2f")}/latest`
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) })
+    if (!res.ok) return null
+    const { version } = await res.json()
+    return parseVersion(version) ? version : null
+  } catch {
+    return null
+  }
+}
+
+function warn(m) {
+  process.stderr.write(`${m}\n`)
+}
+
+/**
+ * Install the latest grunt as a devDependency, then re-run the same command with the
+ * installed bin so the merge uses the new package. Returns `{ reexeced, status? }`.
+ */
+export async function selfUpdate({
+  cwd,
+  pkgRoot,
+  currentVersion,
+  pm,
+  argv,
+  env = process.env,
+  fetch = globalThis.fetch,
+  run = spawnSync,
+  log = warn,
+}) {
+  if (env[REEXEC_ENV]) return { reexeced: false }
+  if (samePath(cwd, pkgRoot)) return { reexeced: false }
+
+  const latest = await fetchLatestVersion({ fetch, env })
+  if (!latest) {
+    log(`grunt: could not check the registry for updates; upgrading with ${currentVersion}`)
+    return { reexeced: false }
+  }
+  if (compareVersions(currentVersion, latest) >= 0) return { reexeced: false }
+
+  log(`grunt: updating ${currentVersion} -> ${latest}`)
+  const install = run(pm, addDevArgs(pm, `${GRUNT_PACKAGE}@${latest}`, { cwd }), {
+    cwd,
+    stdio: "inherit",
+  })
+  if (install.error || install.status !== 0) {
+    throw new Error(`grunt: ${pm} install of ${GRUNT_PACKAGE}@${latest} failed`)
+  }
+
+  const bin = path.join(cwd, "node_modules", GRUNT_PACKAGE, "bin", "grunt.js")
+  const opts = { cwd, stdio: "inherit", env: { ...env, [REEXEC_ENV]: "1" } }
+  let child
+  if (fs.existsSync(bin)) {
+    child = run(process.execPath, [bin, ...argv], opts)
+  } else if (fs.existsSync(path.join(cwd, ".pnp.cjs"))) {
+    // Yarn Plug'n'Play has no node_modules; yarn resolves the bin from the updated .pnp.cjs.
+    child = run("yarn", ["grunt", ...argv], opts)
+  } else {
+    log(`grunt: ${bin} not found after install; upgrading with ${currentVersion}`)
+    return { reexeced: false }
+  }
+  return { reexeced: true, status: child.status ?? 1 }
+}

package/cli/self-update.test.ts

@@ -0,0 +1,208 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  REEXEC_ENV,
+  compareVersions,
+  fetchLatestVersion,
+  selfUpdate,
+} from "./self-update.mjs";
+
+const tmpDirs: string[] = [];
+afterEach(() => {
+  for (const d of tmpDirs.splice(0)) {
+    fs.rmSync(d, { recursive: true, force: true });
+  }
+});
+
+function tmp(prefix: string) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  tmpDirs.push(dir);
+  return dir;
+}
+
+function okFetch(body: unknown, status = 200) {
+  return vi.fn(async () => ({
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  }));
+}
+
+function installedBin(cwd: string) {
+  const bin = path.join(cwd, "node_modules", "@lovrozagar", "grunt", "bin", "grunt.js");
+  fs.mkdirSync(path.dirname(bin), { recursive: true });
+  fs.writeFileSync(bin, "");
+  return bin;
+}
+
+describe("compareVersions", () => {
+  it("orders major, minor, patch numerically", () => {
+    expect(compareVersions("0.8.3", "0.8.4")).toBe(-1);
+    expect(compareVersions("0.9.0", "0.8.10")).toBe(1);
+    expect(compareVersions("1.0.0", "0.99.99")).toBe(1);
+    expect(compareVersions("0.8.10", "0.8.9")).toBe(1);
+    expect(compareVersions("0.8.3", "0.8.3")).toBe(0);
+  });
+
+  it("sorts a prerelease below its release", () => {
+    expect(compareVersions("1.0.0-beta.1", "1.0.0")).toBe(-1);
+    expect(compareVersions("1.0.0", "1.0.0-beta.1")).toBe(1);
+    expect(compareVersions("1.0.0-beta.2", "1.0.0-beta.1")).toBe(1);
+    expect(compareVersions("1.0.0-beta.1", "1.0.0-beta.2")).toBe(-1);
+  });
+});
+
+describe("fetchLatestVersion", () => {
+  it("reads the latest dist-tag from the default registry", async () => {
+    const fetch = okFetch({ version: "0.9.0" });
+    expect(await fetchLatestVersion({ fetch, env: {} })).toBe("0.9.0");
+    expect(fetch.mock.calls[0][0]).toBe(
+      "https://registry.npmjs.org/@lovrozagar%2fgrunt/latest",
+    );
+  });
+
+  it("honors npm_config_registry", async () => {
+    const fetch = okFetch({ version: "0.9.0" });
+    await fetchLatestVersion({ fetch, env: { npm_config_registry: "https://r.example/npm/" } });
+    expect(fetch.mock.calls[0][0]).toBe("https://r.example/npm/@lovrozagar%2fgrunt/latest");
+  });
+
+  it("returns null on non-200, bad JSON, bad version, or a thrown fetch", async () => {
+    expect(await fetchLatestVersion({ fetch: okFetch({}, 404), env: {} })).toBeNull();
+    const badJson = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => {
+        throw new SyntaxError("bad");
+      },
+    }));
+    expect(await fetchLatestVersion({ fetch: badJson, env: {} })).toBeNull();
+    expect(await fetchLatestVersion({ fetch: okFetch({ version: "latest" }), env: {} })).toBeNull();
+    const aborted = vi.fn(async () => {
+      throw new DOMException("timeout", "TimeoutError");
+    });
+    expect(await fetchLatestVersion({ fetch: aborted, env: {} })).toBeNull();
+  });
+});
+
+describe("selfUpdate", () => {
+  function setup({
+    latest = "0.9.0" as string | null,
+    current = "0.8.3",
+    env = {} as Record<string, string>,
+    withBin = true,
+    runStatus = 0 as number | null,
+  } = {}) {
+    const cwd = tmp("grunt-self-update-");
+    const pkgRoot = tmp("grunt-pkg-");
+    const fetch = latest == null ? okFetch({}, 500) : okFetch({ version: latest });
+    const run = vi.fn((_cmd: string, args: string[]) => {
+      if (args[0] === "install" || args[0] === "add") {
+        if (withBin) installedBin(cwd);
+        return { status: 0 };
+      }
+      return { status: runStatus };
+    });
+    const log = vi.fn();
+    const opts = {
+      cwd,
+      pkgRoot,
+      currentVersion: current,
+      pm: "bun",
+      argv: ["upgrade", "--skip-globals"],
+      env,
+      fetch,
+      run,
+      log,
+    };
+    return { opts, fetch, run, log, cwd };
+  }
+
+  it("skips when already re-execed", async () => {
+    const { opts, fetch, run } = setup({ env: { [REEXEC_ENV]: "1" } });
+    expect(await selfUpdate(opts)).toEqual({ reexeced: false });
+    expect(fetch).not.toHaveBeenCalled();
+    expect(run).not.toHaveBeenCalled();
+  });
+
+  it("skips inside the grunt package itself", async () => {
+    const { opts, fetch } = setup();
+    expect(await selfUpdate({ ...opts, pkgRoot: opts.cwd })).toEqual({ reexeced: false });
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("skips when current is latest or newer", async () => {
+    for (const current of ["0.9.0", "0.10.0"]) {
+      const { opts, run } = setup({ current });
+      expect(await selfUpdate(opts)).toEqual({ reexeced: false });
+      expect(run).not.toHaveBeenCalled();
+    }
+  });
+
+  it("warns and continues when the registry check fails", async () => {
+    const { opts, run, log } = setup({ latest: null });
+    expect(await selfUpdate(opts)).toEqual({ reexeced: false });
+    expect(run).not.toHaveBeenCalled();
+    expect(log.mock.calls[0][0]).toMatch(/could not check/);
+  });
+
+  it("installs latest then re-execs the installed bin", async () => {
+    const { opts, run, cwd } = setup({ runStatus: 3 });
+    expect(await selfUpdate(opts)).toEqual({ reexeced: true, status: 3 });
+    expect(run.mock.calls[0][0]).toBe("bun");
+    expect(run.mock.calls[0][1]).toEqual(["add", "-D", "@lovrozagar/grunt@0.9.0"]);
+    expect(run.mock.calls[0][2]).toMatchObject({ cwd, stdio: "inherit" });
+    const [cmd, args, o] = run.mock.calls[1];
+    expect(cmd).toBe(process.execPath);
+    expect(fs.realpathSync(args[0])).toBe(
+      fs.realpathSync(path.join(cwd, "node_modules", "@lovrozagar", "grunt", "bin", "grunt.js")),
+    );
+    expect(args.slice(1)).toEqual(["upgrade", "--skip-globals"]);
+    expect(o).toMatchObject({ cwd, stdio: "inherit" });
+    expect(o.env[REEXEC_ENV]).toBe("1");
+  });
+
+  it("reports exit 1 when the re-execed child dies without a status", async () => {
+    const { opts } = setup({ runStatus: null });
+    expect(await selfUpdate(opts)).toEqual({ reexeced: true, status: 1 });
+  });
+
+  it("logs to stderr by default", async () => {
+    const { opts } = setup({ latest: null });
+    const write = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    try {
+      const { log: _log, ...rest } = opts;
+      await selfUpdate(rest);
+      expect(String(write.mock.calls[0][0])).toMatch(/could not check.*\n$/);
+    } finally {
+      write.mockRestore();
+    }
+  });
+
+  it("throws when the install fails", async () => {
+    const { opts } = setup();
+    const run = vi.fn(() => ({ status: 1 }));
+    await expect(selfUpdate({ ...opts, run })).rejects.toThrow(/install/);
+  });
+
+  it("re-execs through yarn under Plug'n'Play (no node_modules)", async () => {
+    const { opts, run, log, cwd } = setup({ withBin: false, runStatus: 0 });
+    fs.writeFileSync(path.join(cwd, ".pnp.cjs"), "");
+    expect(await selfUpdate(opts)).toEqual({ reexeced: true, status: 0 });
+    const [cmd, args, o] = run.mock.calls[1];
+    expect(cmd).toBe("yarn");
+    expect(args).toEqual(["grunt", "upgrade", "--skip-globals"]);
+    expect(o).toMatchObject({ cwd, stdio: "inherit" });
+    expect(o.env[REEXEC_ENV]).toBe("1");
+    expect(log).toHaveBeenCalledTimes(1);
+  });
+
+  it("warns and continues when the installed bin is missing", async () => {
+    const { opts, run, log } = setup({ withBin: false });
+    expect(await selfUpdate(opts)).toEqual({ reexeced: false });
+    expect(run).toHaveBeenCalledOnce();
+    expect(log.mock.calls.at(-1)?.[0]).toMatch(/not found/);
+  });
+});

package/cli/spawn.mjs

@@ -0,0 +1,20 @@
+import crossSpawn from "cross-spawn"
+
+/**
+ * child_process twins for starting package managers. On Windows npm, pnpm, and yarn are
+ * .cmd shims that child_process cannot start without a shell (spawnSync npm ENOENT);
+ * cross-spawn resolves and escapes them. Elsewhere it is plain spawnSync.
+ */
+export function spawnSync(cmd, args, opts) {
+  return crossSpawn.sync(cmd, args, opts)
+}
+
+/** execFileSync semantics: throw unless the command exits 0. */
+export function execFileSync(cmd, args, opts) {
+  const r = spawnSync(cmd, args, opts)
+  if (r.error) throw r.error
+  if (r.status !== 0) {
+    throw new Error(`${cmd} ${args.join(" ")} exited with ${r.status ?? r.signal}`)
+  }
+  return r.stdout
+}

package/cli/spawn.test.ts

@@ -0,0 +1,34 @@
+import crossSpawn from "cross-spawn";
+import { describe, expect, it, vi } from "vitest";
+import { execFileSync, spawnSync } from "./spawn.mjs";
+
+const node = process.execPath;
+
+describe("spawnSync", () => {
+  it("returns status and output like child_process.spawnSync", () => {
+    const r = spawnSync(node, ["-e", "process.stdout.write('hi'); process.exit(3)"], { encoding: "utf8" });
+    expect(r.status).toBe(3);
+    expect(r.stdout).toBe("hi");
+  });
+});
+
+describe("execFileSync", () => {
+  it("returns stdout on exit 0", () => {
+    expect(execFileSync(node, ["-e", "process.stdout.write('ok')"], { encoding: "utf8" })).toBe("ok");
+  });
+
+  it("throws with the exit code on a nonzero exit", () => {
+    expect(() => execFileSync(node, ["-e", "process.exit(2)"], {})).toThrow(/exited with 2$/);
+  });
+
+  // Mocked: Windows has no signals, so a real kill reports an exit code there.
+  it("throws with the signal when the child is killed", () => {
+    const sync = vi.spyOn(crossSpawn, "sync").mockReturnValueOnce({ status: null, signal: "SIGTERM" } as never);
+    expect(() => execFileSync("npm", ["install"], {})).toThrow(/^npm install exited with SIGTERM$/);
+    sync.mockRestore();
+  });
+
+  it("throws the spawn error for a missing command", () => {
+    expect(() => execFileSync("grunt-no-such-command-e2e", [], {})).toThrow(/ENOENT/);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovrozagar/grunt",
-  "version": "0.8.3",
+  "version": "0.9.2",
   "description": "Multi-agent orchestrator SoT — deep-merge rulesync trees, product scripts, and generate pipeline into a consumer repo",
   "keywords": [
     "agents",
@@ -31,6 +31,7 @@
     "scripts/guarded-md.mjs",
     "scripts/guarded-roots.mjs",
     "scripts/emit-mcp-policy.mjs",
+    "scripts/jsonc.mjs",
     "scripts/folder-map.mjs",
     "scripts/gate-fat-tools.mjs",
     "scripts/hooks-union.mjs",
@@ -74,7 +75,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@clack/prompts": "^0.11.0"
+    "@clack/prompts": "^0.11.0",
+    "cross-spawn": "^7.0.6"
   },
   "scripts": {
     "rulesync:generate": "node ./scripts/guarded-roots.mjs generate",
@@ -95,14 +97,17 @@
     "codex": "codex --dangerously-bypass-approvals-and-sandbox",
     "gemini": "gemini --yolo",
     "grok": "grok --yolo",
-    "test": "vitest run --coverage"
+    "test": "vitest run --coverage",
+    "test:e2e": "vitest run -c vitest.e2e.config.ts"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",
     "@vitest/coverage-v8": "^3.2.7",
     "rulesync": "16.17.0",
     "smol-toml": "^1.8.0",
+    "tar": "^7.5.22",
     "typescript": "^5.9.3",
+    "verdaccio": "^6.10.5",
     "vitest": "^3.2.7"
   },
   "engines": {

package/scripts/emit-mcp-policy.mjs

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { stripJsonc } from "./jsonc.mjs";
 
 export const POLICY_REL = ".rulesync/mcp-policy.jsonc";
 const GROK_REL = ".grok/config.toml";
@@ -22,12 +23,6 @@ function isPlainObject(v) {
   return v != null && typeof v === "object" && !Array.isArray(v) && !(v instanceof Date);
 }
 
-export function stripJsonc(text) {
-  return String(text ?? "")
-    .replace(/\/\*[\s\S]*?\*\//g, "")
-    .replace(/\/\/.*$/gm, "");
-}
-
 export function parseArgv(argv) {
   const args = Array.isArray(argv) ? argv : [];
   let check = false;

package/scripts/folder-map.mjs

@@ -15,7 +15,7 @@ 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";
+import { stripJsonc } from "./jsonc.mjs";
 
 export const DEFAULTS = Object.freeze({
   budget: 5000,

package/scripts/jsonc.mjs

@@ -0,0 +1,7 @@
+/** Dependency-free JSONC helpers. The published CLI imports this, so keep it to node builtins. */
+
+export function stripJsonc(text) {
+  return String(text ?? "")
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/\/\/.*$/gm, "");
+}

package/scripts/package-manager.mjs

@@ -138,6 +138,15 @@ export function installArgs(_pm) {
   return ["install"];
 }
 
+/** Add `spec` as a devDependency. pnpm needs `-w` at a workspace root. */
+export function addDevArgs(pm, spec, { cwd = "" } = {}) {
+  if (pm === "npm") return ["install", "-D", spec];
+  if (pm === "pnpm" && isFile(path.join(cwd, "pnpm-workspace.yaml"))) {
+    return ["add", "-D", "-w", spec];
+  }
+  return ["add", "-D", spec];
+}
+
 export function runScriptArgs(pm, script, extra = []) {
   if (!extra.length) return ["run", script];
   if (pm === "npm") return ["run", script, "--", ...extra];