@lovrozagar/grunt 0.3.1 → 0.3.2

package/README.md

@@ -13,8 +13,18 @@ npx @lovrozagar/grunt
 
 Same as `npx @lovrozagar/grunt init`. Merge SoT, `npm install`, `rulesync:generate`, `sync:globals:apply`, `rulesync:check`. Do not `npm test` as a consumer.
 
+`--skip-globals` skips `sync:globals:apply`. Re-init auto-skips globals when `<!-- grunt:begin -->` is in AGENTS.md/CLAUDE.md or `scripts/telemetry.mjs` exists. First init (no sentinel, no telemetry) still applies globals unless flagged.
+
 Contributors to this repo only: local `npm i && npm test`.
 
+# Version bump
+
+```
+npm i -D @lovrozagar/grunt@latest && npx @lovrozagar/grunt init
+```
+
+Owned trees/scripts refresh. Extra `.rulesync` files kept. Patches to grunt-owned files lost. Globals: first init applies; re-init auto-skips (or pass `--skip-globals`).
+
 # GOAL
 
 - synced configs across all 4/5 major cli providers (grok build, claude code, codex, gemini cli, antigravity)! Emit matrix: grok/claude/codex/antigravity (`rulesync generate`) then `emit-mcp-policy` + `emit-gemini` (`GEMINI.md`, `.gemini/agents/{id}/agent.md`; MCP `.gemini/settings.json`) + `emit-agent-shell-tools` (Claude grunt body `Bash`; other hosts `run_terminal_command`). No `-t geminicli`.

package/cli/grunt.mjs

@@ -16,6 +16,9 @@ Commands:
   check      npm run rulesync:check
   help       Show this help
   version    Print package version
+
+Flags:
+  --skip-globals  Skip sync:globals:apply (auto-skipped when already initialized)
 `
 
 function pkgVersion() {
@@ -28,7 +31,9 @@ function npmRun(script) {
 }
 
 export function start() {
-  const [cmd] = process.argv.slice(2)
+  const args = process.argv.slice(2)
+  const skipGlobals = args.includes("--skip-globals")
+  const [cmd] = args.filter((a) => a !== "--skip-globals")
   if (cmd === "help" || cmd === "--help" || cmd === "-h") {
     process.stdout.write(USAGE)
     return
@@ -38,7 +43,7 @@ export function start() {
     return
   }
   if (!cmd || cmd === "init") {
-    init(process.cwd())
+    init(process.cwd(), { skipGlobals })
     return
   }
   if (cmd === "generate") {

package/cli/grunt.test.ts

@@ -21,6 +21,9 @@ Commands:
   check      npm run rulesync:check
   help       Show this help
   version    Print package version
+
+Flags:
+  --skip-globals  Skip sync:globals:apply (auto-skipped when already initialized)
 `;
 
 const pkgRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -74,7 +77,7 @@ describe("start", () => {
     process.argv = ["node", "grunt"];
     start();
     expect(init).toHaveBeenCalledOnce();
-    expect(init).toHaveBeenCalledWith(process.cwd());
+    expect(init).toHaveBeenCalledWith(process.cwd(), { skipGlobals: false });
     expect(execFileSync).not.toHaveBeenCalled();
   });
 
@@ -82,7 +85,18 @@ describe("start", () => {
     process.argv = ["node", "grunt", "init"];
     start();
     expect(init).toHaveBeenCalledOnce();
-    expect(init).toHaveBeenCalledWith(process.cwd());
+    expect(init).toHaveBeenCalledWith(process.cwd(), { skipGlobals: false });
+  });
+
+  it.each([
+    ["node", "grunt", "--skip-globals"],
+    ["node", "grunt", "init", "--skip-globals"],
+    ["node", "grunt", "--skip-globals", "init"],
+  ])("passes skipGlobals when argv is %s", (...argv) => {
+    process.argv = argv;
+    start();
+    expect(init).toHaveBeenCalledOnce();
+    expect(init).toHaveBeenCalledWith(process.cwd(), { skipGlobals: true });
   });
 
   it("generate npm-runs rulesync:generate", () => {

package/cli/init.mjs

@@ -58,7 +58,22 @@ export function mergeGitignore(dest) {
   fs.appendFileSync(gi, `${prefix}.tmp/\n`)
 }
 
-export function mergeGuardedMarkdown(dest, pkgRoot, file) {
+function destHasGruntSentinel(dest) {
+  return GUARDED_MD_FILES.some((file) => {
+    const p = path.join(dest, file)
+    return fs.existsSync(p) && fs.readFileSync(p, "utf8").includes(SENTINEL_BEGIN)
+  })
+}
+
+function destAlreadyInited(dest) {
+  return (
+    fs.existsSync(path.join(dest, "scripts", "telemetry.mjs")) ||
+    fs.existsSync(path.join(dest, ".grok", "hooks", "orchestrate-parent.js")) ||
+    fs.existsSync(path.join(dest, ".rulesync"))
+  )
+}
+
+export function mergeGuardedMarkdown(dest, pkgRoot, file, { alreadyInited = false } = {}) {
   const src = path.join(pkgRoot, file)
   const d = path.join(dest, file)
   if (samePath(src, d)) return
@@ -73,6 +88,7 @@ export function mergeGuardedMarkdown(dest, pkgRoot, file) {
   const hasSentinel = [SENTINEL_BEGIN, SENTINEL_END].every((marker) => destText.includes(marker))
 
   if (!hasSentinel) {
+    if (alreadyInited) return "skipped-side-file"
     const gruntFile = file.replace(/\.md$/, ".grunt.md")
     fs.writeFileSync(path.join(dest, gruntFile), srcText)
     console.log(`${file} exists without grunt sentinel; wrote ${gruntFile} instead (original untouched)`)
@@ -139,6 +155,42 @@ export function mergeClaudeSettings(destRoot, pkgRoot) {
   fs.writeFileSync(destPath, `${JSON.stringify(destSettings, null, 2)}\n`)
 }
 
+function looksGruntOwnedPrefix(prefix) {
+  return /rulesync|sync:globals|^npm run /.test(prefix)
+}
+
+function commandCount(script) {
+  return script.split(/\s*(?:&&|;)\s*/).filter(Boolean).length
+}
+
+function extraOwnedSuffix(cur, newSrc) {
+  const nNew = commandCount(newSrc)
+  const nCur = commandCount(cur)
+  if (nCur <= nNew) return null
+  let completed = 1
+  const re = / &&| ;|&&/g
+  let m
+  while ((m = re.exec(cur))) {
+    if (completed === nNew) {
+      const prefix = cur.slice(0, m.index)
+      if (!looksGruntOwnedPrefix(prefix)) return null
+      return cur.slice(m.index)
+    }
+    completed++
+  }
+  return null
+}
+
+function mergeScriptValue(name, newSrc, cur) {
+  if (cur == null) return newSrc
+  if (cur.startsWith(newSrc)) return cur
+  const suffix = extraOwnedSuffix(cur, newSrc)
+  if (suffix != null) return newSrc + suffix
+  if (looksGruntOwnedPrefix(cur)) return newSrc
+  console.warn(`script \`${name}\` left untouched (unrelated customization)`)
+  return cur
+}
+
 export function mergePackageJson(dest, pkgRoot) {
   const destPath = path.join(dest, "package.json")
   let destPkg = {}
@@ -151,7 +203,7 @@ export function mergePackageJson(dest, pkgRoot) {
   destPkg.scripts = { ...(destPkg.scripts || {}) }
   for (const [k, v] of Object.entries(srcPkg.scripts || {})) {
     if (k === "test") continue
-    destPkg.scripts[k] = v
+    destPkg.scripts[k] = mergeScriptValue(k, v, destPkg.scripts[k])
   }
   destPkg.devDependencies = { ...(destPkg.devDependencies || {}) }
   destPkg.devDependencies["smol-toml"] = srcPkg.devDependencies["smol-toml"]
@@ -161,9 +213,12 @@ export function mergePackageJson(dest, pkgRoot) {
   fs.writeFileSync(destPath, `${JSON.stringify(destPkg, null, 2)}\n`)
 }
 
-export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileSync } = {}) {
+export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileSync, skipGlobals = false } = {}) {
   dest = path.resolve(dest)
   const pkgRoot = path.resolve(pkgRootOpt ?? PKG_ROOT)
+  const alreadyInited = destAlreadyInited(dest)
+  const skipGlobalsApply =
+    skipGlobals || destHasGruntSentinel(dest) || fs.existsSync(path.join(dest, "scripts", "telemetry.mjs"))
 
   for (const dir of COPY_DIRS) {
     const src = path.join(pkgRoot, dir)
@@ -182,8 +237,14 @@ export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileS
     }
   }
 
+  let skippedSideFile = false
   for (const file of GUARDED_MD_FILES) {
-    mergeGuardedMarkdown(dest, pkgRoot, file)
+    if (mergeGuardedMarkdown(dest, pkgRoot, file, { alreadyInited }) === "skipped-side-file") {
+      skippedSideFile = true
+    }
+  }
+  if (skippedSideFile) {
+    console.log("AGENTS.md/CLAUDE.md lack markers and were left alone")
   }
 
   fs.mkdirSync(path.join(dest, "scripts"), { recursive: true })
@@ -207,6 +268,8 @@ export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileS
   mergePackageJson(dest, pkgRoot)
   exec("npm", ["install"], { cwd: dest, stdio: "inherit" })
   exec("npm", ["run", "rulesync:generate"], { cwd: dest, stdio: "inherit" })
-  exec("npm", ["run", "sync:globals:apply"], { cwd: dest, stdio: "inherit" })
+  if (!skipGlobalsApply) {
+    exec("npm", ["run", "sync:globals:apply"], { cwd: dest, stdio: "inherit" })
+  }
   exec("npm", ["run", "rulesync:check"], { cwd: dest, stdio: "inherit" })
 }

package/cli/init.test.ts

@@ -415,13 +415,170 @@ describe("mergePackageJson", () => {
     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("a");
+    expect(out.scripts.alpha).toBe("old");
     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");
   });
 
+  it("preserves dest suffix after an upgraded grunt script prefix", () => {
+    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-suffix-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: {
+          "rulesync:generate": "rulesync generate -t foo && node scripts/codex-sync.mjs",
+        },
+      }),
+    );
+    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 && node scripts/codex-sync.mjs",
+    );
+  });
+
+  it("preserves suffix after a multi-command grunt script upgrade", () => {
+    const pkgRoot = stubPkgRoot({
+      name: "fixture-pkg",
+      scripts: {
+        "rulesync:generate": "rulesync generate -t bar && node scripts/emit.mjs",
+      },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-multi-suffix-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: {
+          "rulesync:generate":
+            "rulesync generate -t foo && node scripts/emit.mjs && node scripts/codex-sync.mjs",
+        },
+      }),
+    );
+    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 && node scripts/emit.mjs && node scripts/codex-sync.mjs",
+    );
+  });
+
+  it("does not treat a non-owned prefix plus extra && as a grunt suffix", () => {
+    const pkgRoot = stubPkgRoot({
+      name: "fixture-pkg",
+      scripts: { alpha: "a" },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-nonowned-suffix-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({ scripts: { alpha: "echo custom && extra" } }),
+    );
+    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.alpha).toBe("echo custom && extra");
+    expect(warnSpy).toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it("falls through suffix scan when extra commands use bare semicolons", () => {
+    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-semi-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: { "rulesync:generate": "echo custom;echo extra" },
+      }),
+    );
+    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["rulesync:generate"]).toBe("echo custom;echo extra");
+    expect(warnSpy).toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it("keeps dest when dest script already equals src", () => {
+    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-equal-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({ scripts: { "rulesync:generate": "rulesync generate -t bar" } }),
+    );
+    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");
+  });
+
+  it("keeps dest when it already starts with the new src value plus suffix", () => {
+    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-prefix-");
+    const cur = "rulesync generate -t bar && node scripts/codex-sync.mjs";
+    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);
+  });
+
+  it("keeps unrelated custom script values and dest-only keys, warns on skip", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("pj-unrelated-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: { alpha: "echo custom", foo: "bar", test: "jest" },
+      }),
+    );
+    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.alpha).toBe("echo custom");
+    expect(out.scripts.foo).toBe("bar");
+    expect(out.scripts.test).toBe("jest");
+    expect(out.scripts.zeta).toBe("z");
+    expect(warnSpy.mock.calls.some((c) => String(c[0]).includes("alpha") && String(c[0]).includes("untouched"))).toBe(
+      true,
+    );
+    warnSpy.mockRestore();
+  });
+
+  it("replaces a grunt-owned script with no suffix", () => {
+    const pkgRoot = stubPkgRoot({
+      name: "fixture-pkg",
+      scripts: { "rulesync:generate": "rulesync generate -t bar", "sync:globals:apply": "node scripts/sync-global-settings.mjs --apply" },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-owned-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: { "rulesync:generate": "rulesync generate -t foo" },
+      }),
+    );
+    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");
+  });
+
   it("early return when name is @lovrozagar/grunt", () => {
     const pkgRoot = stubPkgRoot();
     const dest = tmp("pj-self-");
@@ -562,4 +719,85 @@ describe("init", () => {
       ["run", "rulesync:check"],
     ]);
   });
+
+  it("--skip-globals skips sync:globals:apply", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-skip-globals-");
+    const exec = vi.fn();
+    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"]],
+    ]);
+  });
+
+  it("auto-skip globals when telemetry.mjs exists", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-auto-tel-");
+    fs.mkdirSync(path.join(dest, "scripts"), { recursive: true });
+    fs.writeFileSync(path.join(dest, "scripts", "telemetry.mjs"), "existing");
+    const exec = vi.fn();
+    init(dest, { pkgRoot, execFileSync: exec });
+    expect(exec.mock.calls.map((c) => c[1])).toEqual([
+      ["install"],
+      ["run", "rulesync:generate"],
+      ["run", "rulesync:check"],
+    ]);
+  });
+
+  it("auto-skip globals when AGENTS.md already has a grunt sentinel", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-auto-sent-");
+    fs.writeFileSync(
+      path.join(dest, "AGENTS.md"),
+      "<!-- grunt:begin -->\nold\n<!-- grunt:end -->\n",
+    );
+    const exec = vi.fn();
+    init(dest, { pkgRoot, execFileSync: exec });
+    expect(exec.mock.calls.map((c) => c[1])).toEqual([
+      ["install"],
+      ["run", "rulesync:generate"],
+      ["run", "rulesync:check"],
+    ]);
+  });
+
+  it("re-run without sentinel does not create/overwrite *.grunt.md", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-rerun-nosent-");
+    fs.writeFileSync(path.join(dest, "CLAUDE.md"), "hand-written consumer doc\n");
+    fs.writeFileSync(path.join(dest, "AGENTS.md"), "hand-written consumer doc\n");
+    fs.mkdirSync(path.join(dest, "scripts"), { recursive: true });
+    fs.writeFileSync(path.join(dest, "scripts", "telemetry.mjs"), "existing");
+    fs.writeFileSync(path.join(dest, "CLAUDE.grunt.md"), "stale side");
+    const exec = vi.fn();
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    init(dest, { pkgRoot, execFileSync: exec });
+    expect(fs.readFileSync(path.join(dest, "CLAUDE.md"), "utf8")).toBe("hand-written consumer doc\n");
+    expect(fs.readFileSync(path.join(dest, "AGENTS.md"), "utf8")).toBe("hand-written consumer doc\n");
+    expect(fs.readFileSync(path.join(dest, "CLAUDE.grunt.md"), "utf8")).toBe("stale side");
+    expect(fs.existsSync(path.join(dest, "AGENTS.grunt.md"))).toBe(false);
+    expect(logSpy.mock.calls.filter((c) => String(c[0]).includes("lack markers"))).toHaveLength(1);
+    logSpy.mockRestore();
+  });
+
+  it("first init without sentinel still creates *.grunt.md", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-first-nosent-");
+    fs.writeFileSync(path.join(dest, "CLAUDE.md"), "hand-written consumer doc\n");
+    fs.writeFileSync(path.join(dest, "AGENTS.md"), "hand-written consumer doc\n");
+    const exec = vi.fn();
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    init(dest, { pkgRoot, execFileSync: exec });
+    expect(fs.readFileSync(path.join(dest, "CLAUDE.md"), "utf8")).toBe("hand-written consumer doc\n");
+    expect(fs.readFileSync(path.join(dest, "CLAUDE.grunt.md"), "utf8")).toBe("CLAUDE.md content");
+    expect(fs.readFileSync(path.join(dest, "AGENTS.grunt.md"), "utf8")).toBe("AGENTS.md content");
+    expect(exec.mock.calls.map((c) => c[1])).toEqual([
+      ["install"],
+      ["run", "rulesync:generate"],
+      ["run", "sync:globals:apply"],
+      ["run", "rulesync:check"],
+    ]);
+    logSpy.mockRestore();
+  });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovrozagar/grunt",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Multi-agent orchestrator SoT \u2014 deep-merge rulesync trees, product scripts, and generate pipeline into a consumer repo",
   "keywords": [
     "agents",