@lovrozagar/grunt 0.5.0 → 0.5.2

package/cli/init.test.ts

@@ -1,16 +1,21 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   MAX_GUARDED_MARKDOWN_BYTES,
   composeGuardedMarkdown,
   destAlreadyInited,
   extractGruntBody,
+  extractUserMarkdown,
   GUARDED_ROOT_FILES,
+  SENTINEL_BEGIN,
+  SENTINEL_END,
   guardedMarkdownDrift,
   healGuardedRootFile,
   init,
+  LAUNCH_SCRIPTS,
   mergeClaudeSettings,
   mergeGitignore,
   mergeGuardedContent,
@@ -20,10 +25,12 @@ import {
   samePath,
   shouldAutoSkipGlobals,
   snapshotGuardedRoots,
+  toGruntScriptName,
   withGuardedCheckInteriors,
   writeMergedGuardedFile,
 } from "./init.mjs";
 import { runGuardedRoots } from "../scripts/guarded-roots.mjs";
+import { stripJsonc } from "../scripts/grunt-config.mjs";
 
 const tmpDirs: string[] = [];
 afterEach(() => {
@@ -39,6 +46,12 @@ function tmp(prefix: string) {
 }
 
 const COPY_DIRS = [".rulesync", ".grok", ".codex", ".claude", ".agents"];
+const GRUNT_CONFIG_REL = path.join(".rulesync", "grunt.config.jsonc");
+const GRUNT_CONFIG_DEFAULTS = {
+  version: 1,
+  leftoverGate: "ask",
+  spawnMode: "cascade",
+};
 const GUARDED_MD_FILES = ["AGENTS.md", "CLAUDE.md"];
 const PRODUCT_FILES = [
   "check-globals.mjs",
@@ -51,8 +64,10 @@ const PRODUCT_FILES = [
   "hooks-union.mjs",
   "pipeline.mjs",
   "grunt-job.mjs",
+  "grunt-config.mjs",
   "parse-need.mjs",
   "persist-handoff.mjs",
+  "persist-tmp.mjs",
   "persist-plan.mjs",
   "purge-global-mcps.mjs",
   "scrub-spawn-prompt.mjs",
@@ -103,6 +118,12 @@ const SRC_CLAUDE_SETTINGS = {
   enabledMcpjsonServers: [],
 };
 
+function readGruntConfig(root: string) {
+  const p = path.join(root, GRUNT_CONFIG_REL);
+  expect(fs.existsSync(p)).toBe(true);
+  return JSON.parse(stripJsonc(fs.readFileSync(p, "utf8")));
+}
+
 function stubPkgRoot(pkg: Record<string, unknown> = {
   name: "fixture-pkg",
   scripts: {
@@ -122,6 +143,10 @@ function stubPkgRoot(pkg: Record<string, unknown> = {
     fs.mkdirSync(path.join(root, d));
     fs.writeFileSync(path.join(root, d, "marker"), d);
   }
+  fs.writeFileSync(
+    path.join(root, GRUNT_CONFIG_REL),
+    `${JSON.stringify(GRUNT_CONFIG_DEFAULTS, null, 2)}\n`,
+  );
   fs.writeFileSync(
     path.join(root, ".claude", "settings.json"),
     `${JSON.stringify(SRC_CLAUDE_SETTINGS, null, 2)}\n`,
@@ -290,6 +315,67 @@ describe("mergeGuardedMarkdown", () => {
     );
   });
 
+  it("already-guarded package src stays begin=1 end=1", () => {
+    const pkgRoot = stubPkgRoot();
+    fs.writeFileSync(
+      path.join(pkgRoot, "CLAUDE.md"),
+      "<!-- grunt:begin -->\nCLAUDE.md content\n<!-- grunt:end -->\n",
+    );
+    const dest = tmp("md-wrapped-src-");
+    mergeGuardedMarkdown(dest, pkgRoot, "CLAUDE.md");
+    const out = fs.readFileSync(path.join(dest, "CLAUDE.md"), "utf8");
+    expect(out).toBe("<!-- grunt:begin -->\nCLAUDE.md content\n<!-- grunt:end -->\n");
+    expect(out.split("<!-- grunt:begin -->")).toHaveLength(2);
+    expect(out.split("<!-- grunt:end -->")).toHaveLength(2);
+  });
+
+  it("merge heals dest with trailing orphan grunt:end", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("md-orphan-end-");
+    fs.writeFileSync(
+      path.join(dest, "CLAUDE.md"),
+      "<!-- grunt:begin -->\nold\n<!-- grunt:end -->\n<!-- grunt:end -->\n",
+    );
+    mergeGuardedMarkdown(dest, pkgRoot, "CLAUDE.md");
+    const out = fs.readFileSync(path.join(dest, "CLAUDE.md"), "utf8");
+    expect(out).toBe("<!-- grunt:begin -->\nCLAUDE.md content\n<!-- grunt:end -->\n");
+    expect(out.split("<!-- grunt:end -->")).toHaveLength(2);
+  });
+
+  it("dest stacked researcher shape heals to exactly one pair", () => {
+    const pkgRoot = stubPkgRoot();
+    fs.writeFileSync(
+      path.join(pkgRoot, "CLAUDE.md"),
+      "<!-- grunt:begin -->\nCLAUDE.md content\n<!-- grunt:end -->\n",
+    );
+    const dest = tmp("md-stacked-");
+    fs.writeFileSync(
+      path.join(dest, "CLAUDE.md"),
+      "<!-- grunt:begin -->\n<!-- grunt:begin -->\nBODY\n<!-- grunt:end -->\n<!-- grunt:end -->\n",
+    );
+    mergeGuardedMarkdown(dest, pkgRoot, "CLAUDE.md");
+    const out = fs.readFileSync(path.join(dest, "CLAUDE.md"), "utf8");
+    expect(out).toBe("<!-- grunt:begin -->\nCLAUDE.md content\n<!-- grunt:end -->\n");
+    expect(out.split("<!-- grunt:begin -->")).toHaveLength(2);
+    expect(out.split("<!-- grunt:end -->")).toHaveLength(2);
+  });
+
+  it("dest stacked keeps user prefix/suffix outside the pair", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("md-stacked-user-");
+    fs.writeFileSync(
+      path.join(dest, "CLAUDE.md"),
+      "prefix\n<!-- grunt:begin -->\n<!-- grunt:begin -->\nBODY\n<!-- grunt:end -->\n<!-- grunt:end -->\nsuffix\n",
+    );
+    mergeGuardedMarkdown(dest, pkgRoot, "CLAUDE.md");
+    const out = fs.readFileSync(path.join(dest, "CLAUDE.md"), "utf8");
+    expect(out).toBe(
+      "<!-- grunt:begin -->\nCLAUDE.md content\n<!-- grunt:end -->\nprefix\nsuffix\n",
+    );
+    expect(out.split("<!-- grunt:begin -->")).toHaveLength(2);
+    expect(out.split("<!-- grunt:end -->")).toHaveLength(2);
+  });
+
   it("does not fuzzy-dedupe unmarked protocol-looking user text", () => {
     const pkgRoot = stubPkgRoot();
     const dest = tmp("md-proto-");
@@ -363,6 +449,23 @@ describe("snapshot/remerge guarded roots", () => {
     );
   });
 
+  it("remerge after wrapped-src merge+generate does not reattach orphan end", () => {
+    const pkgRoot = stubPkgRoot();
+    fs.writeFileSync(
+      path.join(pkgRoot, "AGENTS.md"),
+      "<!-- grunt:begin -->\nAGENTS.md content\n<!-- grunt:end -->\n",
+    );
+    const dest = tmp("snap-wrap-src-");
+    mergeGuardedMarkdown(dest, pkgRoot, "AGENTS.md");
+    const snap = snapshotGuardedRoots(dest);
+    fs.writeFileSync(path.join(dest, "AGENTS.md"), "generated agents\n");
+    remergeGuardedRoots(dest, snap);
+    const out = fs.readFileSync(path.join(dest, "AGENTS.md"), "utf8");
+    expect(out).toBe("<!-- grunt:begin -->\ngenerated agents\n<!-- grunt:end -->\n");
+    expect(out.split("<!-- grunt:begin -->")).toHaveLength(2);
+    expect(out.split("<!-- grunt:end -->")).toHaveLength(2);
+  });
+
   it("withGuardedCheckInteriors is restored even if check throws", () => {
     const dest = tmp("check-int-");
     const live =
@@ -378,6 +481,22 @@ describe("snapshot/remerge guarded roots", () => {
   });
 
   it("compose/extract/drift/write helpers cover remaining branches", () => {
+    expect(
+      extractUserMarkdown(
+        "<!-- grunt:begin -->\nbody\n<!-- grunt:end -->\n<!-- grunt:end -->\n",
+      ),
+    ).toBe("");
+    expect(
+      extractUserMarkdown(
+        "<!-- grunt:begin -->\nbody\n<!-- grunt:end -->\nkeep\n<!-- grunt:end -->\n",
+      ),
+    ).toBe("keep\n");
+    expect(
+      composeGuardedMarkdown(
+        "<!-- grunt:begin -->\nbody\n<!-- grunt:end -->\n",
+        "<!-- grunt:end -->\n",
+      ),
+    ).toBe("<!-- grunt:begin -->\nbody\n<!-- grunt:end -->\n");
     expect(composeGuardedMarkdown("body", null)).toBe(
       "<!-- grunt:begin -->\nbody\n<!-- grunt:end -->\n",
     );
@@ -402,7 +521,9 @@ describe("snapshot/remerge guarded roots", () => {
     expect(mergeGuardedContent("keep\n", "g\r\n")).toBe(
       "<!-- grunt:begin -->\ng\n<!-- grunt:end -->\nkeep\n",
     );
-    expect(mergeGuardedContent("<!-- grunt:begin --> only", "g")).toContain("only");
+    expect(mergeGuardedContent("<!-- grunt:begin --> only", "g")).toBe(
+      "<!-- grunt:begin -->\ng\n<!-- grunt:end -->\n",
+    );
     const dest = tmp("md-helpers-");
     const missing = path.join(dest, "nope.md");
     expect(guardedMarkdownDrift(missing, "g")).toBe(true);
@@ -423,6 +544,73 @@ describe("snapshot/remerge guarded roots", () => {
     expect(writeMergedGuardedFile(huge, "g")).toBe("aborted-unsafe");
   });
 
+  it("unclosed begin unwraps interior; inline orphan end is stripped", () => {
+    expect(extractGruntBody("<!-- grunt:begin -->\nhello")).toBe("hello");
+    const composed = composeGuardedMarkdown("<!-- grunt:begin -->\nhello", "");
+    expect(composed).toBe("<!-- grunt:begin -->\nhello\n<!-- grunt:end -->\n");
+    expect(composed.split(SENTINEL_BEGIN)).toHaveLength(2);
+    expect(composed.split(SENTINEL_END)).toHaveLength(2);
+    expect(composed).not.toContain(`${SENTINEL_BEGIN}\n${SENTINEL_BEGIN}`);
+    expect(mergeGuardedContent("note\n<!-- grunt:begin -->\nstale", "new")).toBe(
+      "<!-- grunt:begin -->\nnew\n<!-- grunt:end -->\nnote\n",
+    );
+    expect(extractUserMarkdown("keep <!-- grunt:end --> me")).not.toContain(SENTINEL_END);
+    expect(extractUserMarkdown("keep <!-- grunt:end --> me")).toBe("keep  me");
+    expect(extractUserMarkdown("keep\n<!-- grunt:end -->\nme")).toBe("keep\nme");
+    expect(extractUserMarkdown("keep\n  <!-- grunt:end -->  \nme")).toBe("keep\nme");
+    expect(extractGruntBody("<!-- grunt:begin -->\r\nhello")).toBe("hello");
+    expect(extractGruntBody("<!-- grunt:begin -->")).toBe("");
+    const emptyWrap = composeGuardedMarkdown("<!-- grunt:begin -->", "");
+    expect(emptyWrap.split(SENTINEL_BEGIN)).toHaveLength(2);
+    expect(emptyWrap).toBe("<!-- grunt:begin -->\n\n<!-- grunt:end -->\n");
+    const mixed =
+      "<!-- grunt:begin -->\nok\n<!-- grunt:end -->\nuser bit\n<!-- grunt:begin -->\nstale";
+    expect(extractGruntBody(mixed)).toBe("ok");
+    expect(extractUserMarkdown(mixed)).toBe("user bit\n");
+    expect(
+      composeGuardedMarkdown("<!-- grunt:begin -->\nbody\n<!-- grunt:end -->\n", ""),
+    ).toBe("<!-- grunt:begin -->\nbody\n<!-- grunt:end -->\n");
+  });
+
+  it("extract/compose peel stacked dest and trailing orphan end", () => {
+    const stacked =
+      "<!-- grunt:begin -->\n<!-- grunt:begin -->\nBODY\n<!-- grunt:end -->\n<!-- grunt:end -->\n";
+    expect(extractGruntBody(stacked)).toBe("BODY");
+    const stackedOut = composeGuardedMarkdown(stacked, "");
+    expect(stackedOut).toBe("<!-- grunt:begin -->\nBODY\n<!-- grunt:end -->\n");
+    expect(stackedOut.split(SENTINEL_BEGIN)).toHaveLength(2);
+    expect(stackedOut.split(SENTINEL_END)).toHaveLength(2);
+    expect(composeGuardedMarkdown("BODY\n<!-- grunt:end -->\n", "")).toBe(
+      "<!-- grunt:begin -->\nBODY\n<!-- grunt:end -->\n",
+    );
+    expect(extractGruntBody("BODY\n\n<!-- grunt:end -->")).toBe("BODY");
+    expect(mergeGuardedContent(stacked, "SRC")).toBe(
+      "<!-- grunt:begin -->\nSRC\n<!-- grunt:end -->\n",
+    );
+    expect(mergeGuardedContent("keep\n<!-- grunt:end -->\n", "SRC")).toBe(
+      "<!-- grunt:begin -->\nSRC\n<!-- grunt:end -->\nkeep\n",
+    );
+    expect(
+      extractGruntBody("<!-- grunt:begin --> \nBODY\n<!-- grunt:end --> \n"),
+    ).toBe("BODY");
+    expect(
+      extractGruntBody("  <!-- grunt:begin -->\nBODY\n  <!-- grunt:end -->\n"),
+    ).toBe("BODY");
+    expect(extractGruntBody("<!-- grunt:begin -->\n<!-- grunt:end -->")).toBe("");
+    expect(
+      extractGruntBody(
+        "<!-- grunt:begin -->\nsee <!-- grunt:end --> here\n<!-- grunt:end -->\n",
+      ),
+    ).toBe("see <!-- grunt:end --> here");
+    const midLine =
+      "<!-- grunt:begin -->\nBODY\n<!-- grunt:end -->\nstill user\n<!-- grunt:end -->\n";
+    expect(extractGruntBody(midLine)).toBe("BODY");
+    expect(extractUserMarkdown(midLine)).toBe("still user\n");
+    expect(composeGuardedMarkdown(extractGruntBody(midLine) ?? "", extractUserMarkdown(midLine))).toBe(
+      "<!-- grunt:begin -->\nBODY\n<!-- grunt:end -->\nstill user\n",
+    );
+  });
+
   it("remerge restores unsafe, missing, binary current, and created files", () => {
     const dest = tmp("remerge-edges-");
     const agents = path.join(dest, "AGENTS.md");
@@ -786,6 +974,13 @@ describe("mergeClaudeSettings", () => {
   });
 });
 
+describe("toGruntScriptName", () => {
+  it("prefixes unprefixed keys and does not double-prefix", () => {
+    expect(toGruntScriptName("rulesync:generate")).toBe("grunt:rulesync:generate");
+    expect(toGruntScriptName("grunt:doctor")).toBe("grunt:doctor");
+  });
+});
+
 describe("mergePackageJson", () => {
   it("creates {} dest and merges scripts skipping test, injects deps, sorts keys", () => {
     const pkgRoot = stubPkgRoot();
@@ -793,11 +988,25 @@ describe("mergePackageJson", () => {
     mergePackageJson(dest, pkgRoot);
     const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
     expect(out.scripts).toEqual({
-      alpha: "a",
-      "rulesync:generate": "gen",
-      zeta: "z",
+      "grunt:alpha": "a",
+      "grunt:antigravity": LAUNCH_SCRIPTS.antigravity,
+      "grunt:claude": LAUNCH_SCRIPTS.claude,
+      "grunt:codex": LAUNCH_SCRIPTS.codex,
+      "grunt:gemini": LAUNCH_SCRIPTS.gemini,
+      "grunt:grok": LAUNCH_SCRIPTS.grok,
+      "grunt:rulesync:generate": "gen",
+      "grunt:zeta": "z",
     });
-    expect(Object.keys(out.scripts)).toEqual(["alpha", "rulesync:generate", "zeta"]);
+    expect(Object.keys(out.scripts)).toEqual([
+      "grunt:alpha",
+      "grunt:antigravity",
+      "grunt:claude",
+      "grunt:codex",
+      "grunt:gemini",
+      "grunt:grok",
+      "grunt:rulesync:generate",
+      "grunt:zeta",
+    ]);
     expect(out.devDependencies).toEqual({
       rulesync: "latest",
       "smol-toml": "^1.8.0",
@@ -817,14 +1026,21 @@ describe("mergePackageJson", () => {
         devDependencies: { lodash: "4" },
       }),
     );
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
     mergePackageJson(dest, pkgRoot);
     const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
     expect(out.scripts.test).toBe("jest");
     expect(out.scripts.alpha).toBe("old");
+    expect(out.scripts["grunt:alpha"]).toBe("a");
+    expect(out.scripts["grunt:zeta"]).toBe("z");
     expect(out.scripts.foo).toBe("bar");
     expect(out.devDependencies.lodash).toBe("4");
     expect(out.devDependencies["smol-toml"]).toBe("^1.8.0");
     expect(out.devDependencies.rulesync).toBe("latest");
+    expect(warnSpy.mock.calls.some((c) => String(c[0]).includes("alpha") && String(c[0]).includes("untouched"))).toBe(
+      true,
+    );
+    warnSpy.mockRestore();
   });
 
   it("preserves dest suffix after an upgraded grunt script prefix", () => {
@@ -844,9 +1060,10 @@ describe("mergePackageJson", () => {
     );
     mergePackageJson(dest, pkgRoot);
     const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
-    expect(out.scripts["rulesync:generate"]).toBe(
+    expect(out.scripts["grunt:rulesync:generate"]).toBe(
       "rulesync generate -t bar && node scripts/codex-sync.mjs",
     );
+    expect(out.scripts["rulesync:generate"]).toBeUndefined();
   });
 
   it("preserves suffix after a multi-command grunt script upgrade", () => {
@@ -869,7 +1086,7 @@ describe("mergePackageJson", () => {
     );
     mergePackageJson(dest, pkgRoot);
     const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
-    expect(out.scripts["rulesync:generate"]).toBe(
+    expect(out.scripts["grunt:rulesync:generate"]).toBe(
       "rulesync generate -t bar && node scripts/emit.mjs && node scripts/codex-sync.mjs",
     );
   });
@@ -889,6 +1106,7 @@ describe("mergePackageJson", () => {
     mergePackageJson(dest, pkgRoot);
     const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
     expect(out.scripts.alpha).toBe("echo custom && extra");
+    expect(out.scripts["grunt:alpha"]).toBe("a");
     expect(warnSpy).toHaveBeenCalled();
     warnSpy.mockRestore();
   });
@@ -910,6 +1128,7 @@ describe("mergePackageJson", () => {
     mergePackageJson(dest, pkgRoot);
     const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
     expect(out.scripts["rulesync:generate"]).toBe("echo custom;echo extra");
+    expect(out.scripts["grunt:rulesync:generate"]).toBe("rulesync generate -t bar");
     expect(warnSpy).toHaveBeenCalled();
     warnSpy.mockRestore();
   });
@@ -927,7 +1146,8 @@ describe("mergePackageJson", () => {
     );
     mergePackageJson(dest, pkgRoot);
     const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
-    expect(out.scripts["rulesync:generate"]).toBe("rulesync generate -t bar");
+    expect(out.scripts["grunt:rulesync:generate"]).toBe("rulesync generate -t bar");
+    expect(out.scripts["rulesync:generate"]).toBeUndefined();
   });
 
   it("keeps dest when it already starts with the new src value plus suffix", () => {
@@ -941,7 +1161,8 @@ describe("mergePackageJson", () => {
     fs.writeFileSync(path.join(dest, "package.json"), JSON.stringify({ scripts: { "rulesync:generate": cur } }));
     mergePackageJson(dest, pkgRoot);
     const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
-    expect(out.scripts["rulesync:generate"]).toBe(cur);
+    expect(out.scripts["grunt:rulesync:generate"]).toBe(cur);
+    expect(out.scripts["rulesync:generate"]).toBeUndefined();
   });
 
   it("keeps unrelated custom script values and dest-only keys, warns on skip", () => {
@@ -957,9 +1178,11 @@ describe("mergePackageJson", () => {
     mergePackageJson(dest, pkgRoot);
     const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
     expect(out.scripts.alpha).toBe("echo custom");
+    expect(out.scripts["grunt:alpha"]).toBe("a");
     expect(out.scripts.foo).toBe("bar");
     expect(out.scripts.test).toBe("jest");
-    expect(out.scripts.zeta).toBe("z");
+    expect(out.scripts["grunt:zeta"]).toBe("z");
+    expect(out.scripts.zeta).toBeUndefined();
     expect(warnSpy.mock.calls.some((c) => String(c[0]).includes("alpha") && String(c[0]).includes("untouched"))).toBe(
       true,
     );
@@ -980,7 +1203,8 @@ describe("mergePackageJson", () => {
     const dest = tmp("pj-raw-src-");
     mergePackageJson(dest, pkgRoot);
     const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
-    expect(out.scripts["rulesync:generate"]).toBe("node ./scripts/guarded-roots.mjs generate");
+    expect(out.scripts["grunt:rulesync:generate"]).toBe("node ./scripts/guarded-roots.mjs generate");
+    expect(out.scripts["rulesync:generate"]).toBeUndefined();
     expect(out.scripts["rulesync:generate:raw"]).toBeUndefined();
     expect(out.scripts["rulesync:check:raw"]).toBeUndefined();
     expect(out.scripts["rulesync:watch:raw"]).toBeUndefined();
@@ -1001,7 +1225,7 @@ describe("mergePackageJson", () => {
     );
     mergePackageJson(dest, pkgRoot);
     const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
-    expect(out.scripts["rulesync:generate"]).toBe("node ./scripts/guarded-roots.mjs generate");
+    expect(out.scripts["grunt:rulesync:generate"]).toBe("node ./scripts/guarded-roots.mjs generate");
     expect(out.scripts["rulesync:generate:raw"]).toBe("echo consumer-raw");
   });
 
@@ -1020,7 +1244,9 @@ describe("mergePackageJson", () => {
     );
     mergePackageJson(dest, pkgRoot);
     const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
-    expect(out.scripts["rulesync:generate"]).toBe("rulesync generate -t bar");
+    expect(out.scripts["grunt:rulesync:generate"]).toBe("rulesync generate -t bar");
+    expect(out.scripts["grunt:sync:globals:apply"]).toBe("node scripts/sync-global-settings.mjs --apply");
+    expect(out.scripts["rulesync:generate"]).toBeUndefined();
   });
 
   it("early return when name is @lovrozagar/grunt", () => {
@@ -1040,9 +1266,257 @@ describe("mergePackageJson", () => {
     const dest = tmp("pj-noscripts-");
     mergePackageJson(dest, pkgRoot);
     const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
-    expect(out.scripts).toEqual({});
+    expect(out.scripts).toEqual({
+      "grunt:antigravity": LAUNCH_SCRIPTS.antigravity,
+      "grunt:claude": LAUNCH_SCRIPTS.claude,
+      "grunt:codex": LAUNCH_SCRIPTS.codex,
+      "grunt:gemini": LAUNCH_SCRIPTS.gemini,
+      "grunt:grok": LAUNCH_SCRIPTS.grok,
+    });
     expect(out.devDependencies).toEqual({ rulesync: "2", "smol-toml": "1" });
   });
+
+  it("golden autorun-apps: suffix keep, doctor move, check npm run rewrite, old keys gone", () => {
+    const pkgRoot = stubPkgRoot({
+      name: "fixture-pkg",
+      scripts: {
+        "rulesync:generate": "node ./scripts/guarded-roots.mjs generate",
+        "rulesync:watch": "node ./scripts/guarded-roots.mjs watch",
+        "rulesync:check": "node ./scripts/guarded-roots.mjs check",
+        "hooks:union": "node scripts/hooks-union.mjs",
+        "hooks:check": "node scripts/hooks-union.mjs --check",
+        doctor: "node ./scripts/doctor.mjs",
+        "rulesync:doctor": "rulesync doctor",
+        "sync:globals": "node scripts/sync-global-settings.mjs",
+        "sync:globals:check": "node scripts/check-globals.mjs",
+        "sync:globals:apply": "node scripts/sync-global-settings.mjs --apply",
+        "purge:global-mcps": "node scripts/purge-global-mcps.mjs",
+        "purge:global-mcps:apply": "node scripts/purge-global-mcps.mjs --apply",
+        test: "vitest run --coverage",
+      },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-autorun-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: {
+          "apps:doctor": "node scripts/audit.mjs",
+          "apps:mental-model:viewer:build":
+            "npm --prefix scripts/excalidraw/viewer install && npm --prefix scripts/excalidraw/viewer run build",
+          check:
+            "node scripts/portability-check.mjs && npm run rulesync:check && npm run lint && npm test && node scripts/media-fixtures.mjs --check",
+          "codex:sync": "node scripts/codex-sync.mjs",
+          doctor: "node ./scripts/doctor.mjs",
+          "hooks:check": "node scripts/hooks-union.mjs --check",
+          "hooks:union": "node scripts/hooks-union.mjs",
+          lint: "eslint scripts tests eslint.config.mjs",
+          "purge:global-mcps": "node scripts/purge-global-mcps.mjs",
+          "purge:global-mcps:apply": "node scripts/purge-global-mcps.mjs --apply",
+          "rulesync:check": "node ./scripts/guarded-roots.mjs check && node scripts/codex-sync.mjs --check",
+          "rulesync:doctor": "rulesync doctor",
+          "rulesync:generate": "node ./scripts/guarded-roots.mjs generate && node scripts/codex-sync.mjs",
+          "rulesync:watch": "node ./scripts/guarded-roots.mjs watch",
+          "sync:globals": "node scripts/sync-global-settings.mjs",
+          "sync:globals:apply": "node scripts/sync-global-settings.mjs --apply",
+          "sync:globals:check": "node scripts/check-globals.mjs",
+          test: "node scripts/run-tests.mjs",
+        },
+      }),
+    );
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["grunt:rulesync:generate"]).toBe(
+      "node ./scripts/guarded-roots.mjs generate && node scripts/codex-sync.mjs",
+    );
+    expect(out.scripts["grunt:rulesync:check"]).toBe(
+      "node ./scripts/guarded-roots.mjs check && node scripts/codex-sync.mjs --check",
+    );
+    expect(out.scripts["grunt:rulesync:watch"]).toBe("node ./scripts/guarded-roots.mjs watch");
+    expect(out.scripts["grunt:rulesync:doctor"]).toBe("rulesync doctor");
+    expect(out.scripts["grunt:hooks:union"]).toBe("node scripts/hooks-union.mjs");
+    expect(out.scripts["grunt:hooks:check"]).toBe("node scripts/hooks-union.mjs --check");
+    expect(out.scripts["grunt:sync:globals"]).toBe("node scripts/sync-global-settings.mjs");
+    expect(out.scripts["grunt:sync:globals:apply"]).toBe("node scripts/sync-global-settings.mjs --apply");
+    expect(out.scripts["grunt:sync:globals:check"]).toBe("node scripts/check-globals.mjs");
+    expect(out.scripts["grunt:purge:global-mcps"]).toBe("node scripts/purge-global-mcps.mjs");
+    expect(out.scripts["grunt:purge:global-mcps:apply"]).toBe("node scripts/purge-global-mcps.mjs --apply");
+    expect(out.scripts["grunt:doctor"]).toBe("node ./scripts/doctor.mjs");
+    expect(out.scripts.doctor).toBeUndefined();
+    expect(out.scripts["rulesync:generate"]).toBeUndefined();
+    expect(out.scripts["rulesync:check"]).toBeUndefined();
+    expect(out.scripts["rulesync:watch"]).toBeUndefined();
+    expect(out.scripts["hooks:union"]).toBeUndefined();
+    expect(out.scripts["sync:globals"]).toBeUndefined();
+    expect(out.scripts.check).toBe(
+      "node scripts/portability-check.mjs && npm run grunt:rulesync:check && npm run lint && npm test && node scripts/media-fixtures.mjs --check",
+    );
+    expect(out.scripts["apps:doctor"]).toBe("node scripts/audit.mjs");
+    expect(out.scripts["codex:sync"]).toBe("node scripts/codex-sync.mjs");
+    expect(out.scripts.lint).toBe("eslint scripts tests eslint.config.mjs");
+    expect(out.scripts.test).toBe("node scripts/run-tests.mjs");
+  });
+
+  it("leaves custom doctor and writes grunt:doctor from SoT", () => {
+    const pkgRoot = stubPkgRoot({
+      name: "fixture-pkg",
+      scripts: { doctor: "node ./scripts/doctor.mjs" },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-custom-doctor-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({ scripts: { doctor: "node scripts/audit.mjs" } }),
+    );
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts.doctor).toBe("node scripts/audit.mjs");
+    expect(out.scripts["grunt:doctor"]).toBe("node ./scripts/doctor.mjs");
+    expect(warnSpy).toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it("merges destKey when both prefixed and owned legacy exist, deletes legacy", () => {
+    const pkgRoot = stubPkgRoot({
+      name: "fixture-pkg",
+      scripts: { "rulesync:generate": "rulesync generate -t bar" },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-both-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: {
+          "rulesync:generate": "rulesync generate -t foo && node scripts/codex-sync.mjs",
+          "grunt:rulesync:generate": "rulesync generate -t old && node scripts/other.mjs",
+        },
+      }),
+    );
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["grunt:rulesync:generate"]).toBe(
+      "rulesync generate -t bar && node scripts/other.mjs",
+    );
+    expect(out.scripts["rulesync:generate"]).toBeUndefined();
+  });
+
+  it("does not rewrite npm run rulesync:check:raw when only rulesync:check migrated", () => {
+    const pkgRoot = stubPkgRoot({
+      name: "fixture-pkg",
+      scripts: { "rulesync:check": "node ./scripts/guarded-roots.mjs check" },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-raw-rewrite-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: {
+          "rulesync:check": "node ./scripts/guarded-roots.mjs check",
+          "rulesync:check:raw": "echo consumer-raw",
+          check: "npm run rulesync:check && npm run rulesync:check:raw",
+        },
+      }),
+    );
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["grunt:rulesync:check"]).toBe("node ./scripts/guarded-roots.mjs check");
+    expect(out.scripts["rulesync:check"]).toBeUndefined();
+    expect(out.scripts["rulesync:check:raw"]).toBe("echo consumer-raw");
+    expect(out.scripts.check).toBe("npm run grunt:rulesync:check && npm run rulesync:check:raw");
+  });
+
+  it("skips non-string dest scripts when rewriting npm run refs", () => {
+    const pkgRoot = stubPkgRoot({
+      name: "fixture-pkg",
+      scripts: { "rulesync:check": "node ./scripts/guarded-roots.mjs check" },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-nonstr-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: {
+          extra: 1,
+          check: "npm run rulesync:check",
+        },
+      }),
+    );
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts.extra).toBe(1);
+    expect(out.scripts.check).toBe("npm run grunt:rulesync:check");
+    expect(out.scripts["grunt:rulesync:check"]).toBe("node ./scripts/guarded-roots.mjs check");
+  });
+
+  it("emits grunt:claude into a consumer package.json", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("pj-launch-emit-");
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["grunt:claude"]).toBe(LAUNCH_SCRIPTS.claude);
+  });
+
+  it("leaves a consumer's bare claude launcher untouched, no warn emitted", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("pj-consumer-claude-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({ scripts: { claude: "npm run build && claude" } }),
+    );
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts.claude).toBe("npm run build && claude");
+    expect(out.scripts["grunt:claude"]).toBe(LAUNCH_SCRIPTS.claude);
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("does not rewrite npm run claude inside a consumer script", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("pj-npmrun-claude-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: { claude: "npm run build && claude", start: "npm run claude" },
+      }),
+    );
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts.start).toBe("npm run claude");
+  });
+
+  it("purges a stale grunt:yolo:claude with the exact old value; an edited variant survives", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("pj-purge-stale-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: {
+          "grunt:yolo:claude": LAUNCH_SCRIPTS.claude,
+          "grunt:yolo:codex": `${LAUNCH_SCRIPTS.codex} --extra`,
+        },
+      }),
+    );
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["grunt:yolo:claude"]).toBeUndefined();
+    expect(out.scripts["grunt:claude"]).toBe(LAUNCH_SCRIPTS.claude);
+    expect(out.scripts["grunt:yolo:codex"]).toBe(`${LAUNCH_SCRIPTS.codex} --extra`);
+  });
+
+  it("drift: every bare launcher key in grunt's package.json equals LAUNCH_SCRIPTS[key]", () => {
+    const pkg = JSON.parse(
+      fs.readFileSync(
+        path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"),
+        "utf8",
+      ),
+    );
+    for (const [k, v] of Object.entries(LAUNCH_SCRIPTS)) {
+      expect(pkg.scripts[k]).toBe(v);
+    }
+  });
 });
 
 describe("init", () => {
@@ -1076,6 +1550,9 @@ describe("init", () => {
       if (d === ".claude") continue;
       expect(fs.readFileSync(path.join(dest, d, "marker"), "utf8")).toBe(d);
     }
+    expect(readGruntConfig(dest)).toEqual(GRUNT_CONFIG_DEFAULTS);
+    expect(PRODUCT_FILES).toContain("grunt-config.mjs");
+    expect(fs.statSync(path.join(dest, "scripts", "grunt-config.mjs")).isFile()).toBe(true);
     expect(fs.readFileSync(path.join(dest, ".claude", "marker"), "utf8")).toBe(".claude");
     const settings = JSON.parse(
       fs.readFileSync(path.join(dest, ".claude", "settings.json"), "utf8"),
@@ -1103,9 +1580,9 @@ describe("init", () => {
 
     expect(exec.mock.calls.map((c) => [c[0], c[1]])).toEqual([
       ["npm", ["install"]],
-      ["npm", ["run", "rulesync:generate"]],
-      ["npm", ["run", "sync:globals:apply"]],
-      ["npm", ["run", "rulesync:check"]],
+      ["npm", ["run", "grunt:rulesync:generate"]],
+      ["npm", ["run", "grunt:sync:globals:apply"]],
+      ["npm", ["run", "grunt:rulesync:check"]],
     ]);
     for (const call of exec.mock.calls) {
       expect(call[2]).toEqual({ cwd: dest, stdio: "inherit" });
@@ -1154,13 +1631,21 @@ describe("init", () => {
     const exec = vi.fn();
     init(dest, { execFileSync: exec });
     expect(fs.existsSync(path.join(dest, "AGENTS.md"))).toBe(true);
+    const agents = fs.readFileSync(path.join(dest, "AGENTS.md"), "utf8");
+    const claude = fs.readFileSync(path.join(dest, "CLAUDE.md"), "utf8");
+    expect(agents.split("<!-- grunt:begin -->")).toHaveLength(2);
+    expect(agents.split("<!-- grunt:end -->")).toHaveLength(2);
+    expect(claude.split("<!-- grunt:begin -->")).toHaveLength(2);
+    expect(claude.split("<!-- grunt:end -->")).toHaveLength(2);
     expect(fs.existsSync(path.join(dest, "scripts", "scrub-text"))).toBe(true);
+    expect(fs.existsSync(path.join(dest, "scripts", "grunt-config.mjs"))).toBe(true);
     expect(fs.existsSync(path.join(dest, ".claude", "settings.json"))).toBe(true);
+    expect(readGruntConfig(dest)).toEqual(GRUNT_CONFIG_DEFAULTS);
     expect(exec.mock.calls.map((c) => c[1])).toEqual([
       ["install"],
-      ["run", "rulesync:generate"],
-      ["run", "sync:globals:apply"],
-      ["run", "rulesync:check"],
+      ["run", "grunt:rulesync:generate"],
+      ["run", "grunt:sync:globals:apply"],
+      ["run", "grunt:rulesync:check"],
     ]);
   });
 
@@ -1171,8 +1656,8 @@ describe("init", () => {
     init(dest, { pkgRoot, execFileSync: exec, skipGlobals: true });
     expect(exec.mock.calls.map((c) => [c[0], c[1]])).toEqual([
       ["npm", ["install"]],
-      ["npm", ["run", "rulesync:generate"]],
-      ["npm", ["run", "rulesync:check"]],
+      ["npm", ["run", "grunt:rulesync:generate"]],
+      ["npm", ["run", "grunt:rulesync:check"]],
     ]);
   });
 
@@ -1187,9 +1672,9 @@ describe("init", () => {
     init(dest, { pkgRoot, execFileSync: exec, applyGlobals: true });
     expect(exec.mock.calls.map((c) => c[1])).toEqual([
       ["install"],
-      ["run", "rulesync:generate"],
-      ["run", "sync:globals:apply"],
-      ["run", "rulesync:check"],
+      ["run", "grunt:rulesync:generate"],
+      ["run", "grunt:sync:globals:apply"],
+      ["run", "grunt:rulesync:check"],
     ]);
   });
 
@@ -1204,8 +1689,8 @@ describe("init", () => {
     init(dest, { pkgRoot, execFileSync: exec });
     expect(exec.mock.calls.map((c) => c[1])).toEqual([
       ["install"],
-      ["run", "rulesync:generate"],
-      ["run", "rulesync:check"],
+      ["run", "grunt:rulesync:generate"],
+      ["run", "grunt:rulesync:check"],
     ]);
   });
 
@@ -1242,9 +1727,9 @@ describe("init", () => {
     expect(fs.existsSync(path.join(dest, "AGENTS.grunt.md"))).toBe(false);
     expect(exec.mock.calls.map((c) => c[1])).toEqual([
       ["install"],
-      ["run", "rulesync:generate"],
-      ["run", "sync:globals:apply"],
-      ["run", "rulesync:check"],
+      ["run", "grunt:rulesync:generate"],
+      ["run", "grunt:sync:globals:apply"],
+      ["run", "grunt:rulesync:check"],
     ]);
   });
 
@@ -1255,7 +1740,7 @@ describe("init", () => {
     fs.writeFileSync(path.join(dest, "CLAUDE.md"), "consumer claude\n");
     fs.writeFileSync(path.join(dest, "GEMINI.md"), "consumer gemini\n");
     const exec = vi.fn((_cmd, args) => {
-      if (Array.isArray(args) && args.includes("rulesync:generate")) {
+      if (Array.isArray(args) && args.includes("grunt:rulesync:generate")) {
         fs.writeFileSync(path.join(dest, "AGENTS.md"), "generated agents\n");
         fs.writeFileSync(path.join(dest, "CLAUDE.md"), "generated claude\n");
         fs.writeFileSync(path.join(dest, "GEMINI.md"), "@AGENTS.md\n");
@@ -1280,6 +1765,32 @@ describe("init", () => {
     );
   });
 
+  it("wrapped package src + generate clobber stays begin=1 end=1", () => {
+    const pkgRoot = stubPkgRoot();
+    for (const f of GUARDED_MD_FILES) {
+      fs.writeFileSync(
+        path.join(pkgRoot, f),
+        `<!-- grunt:begin -->\n${f} content\n<!-- grunt:end -->\n`,
+      );
+    }
+    const dest = tmp("grunt-wrap-gen-");
+    const exec = vi.fn((_cmd, args) => {
+      if (Array.isArray(args) && args.includes("grunt:rulesync:generate")) {
+        fs.writeFileSync(path.join(dest, "AGENTS.md"), "generated agents\n");
+        fs.writeFileSync(path.join(dest, "CLAUDE.md"), "generated claude\n");
+      }
+    });
+    init(dest, { pkgRoot, execFileSync: exec });
+    const agents = fs.readFileSync(path.join(dest, "AGENTS.md"), "utf8");
+    const claude = fs.readFileSync(path.join(dest, "CLAUDE.md"), "utf8");
+    expect(agents).toBe("<!-- grunt:begin -->\ngenerated agents\n<!-- grunt:end -->\n");
+    expect(claude).toBe("<!-- grunt:begin -->\ngenerated claude\n<!-- grunt:end -->\n");
+    expect(agents.split("<!-- grunt:begin -->")).toHaveLength(2);
+    expect(agents.split("<!-- grunt:end -->")).toHaveLength(2);
+    expect(claude.split("<!-- grunt:begin -->")).toHaveLength(2);
+    expect(claude.split("<!-- grunt:end -->")).toHaveLength(2);
+  });
+
   it("onPhase merge then npm phases stop before exec", () => {
     const pkgRoot = stubPkgRoot();
     const dest = tmp("grunt-onphase-");
@@ -1300,9 +1811,9 @@ describe("init", () => {
     ]);
     expect(exec.mock.calls.map((c) => c[1])).toEqual([
       ["install"],
-      ["run", "rulesync:generate"],
-      ["run", "sync:globals:apply"],
-      ["run", "rulesync:check"],
+      ["run", "grunt:rulesync:generate"],
+      ["run", "grunt:sync:globals:apply"],
+      ["run", "grunt:rulesync:check"],
     ]);
   });