@lovrozagar/grunt 0.6.2 → 0.8.0

package/cli/init.mjs

@@ -16,6 +16,15 @@ import {
   remergeGuardedRoots,
   withGuardedCheckInteriors,
 } from "../scripts/guarded-md.mjs"
+import {
+  PACKAGE_MANAGERS,
+  UNKNOWN_PACKAGE_MANAGER,
+  detectPackageManager,
+  installArgs,
+  isPackageManager,
+  runScriptArgs,
+} from "../scripts/package-manager.mjs"
+import { LAW_REL, emitMaps } from "../scripts/emit-maps.mjs"
 
 export {
   GUARDED_ROOT_FILES,
@@ -44,11 +53,13 @@ export const PRODUCT_SCRIPTS = [
   "guarded-md.mjs",
   "guarded-roots.mjs",
   "emit-mcp-policy.mjs",
+  "folder-map.mjs",
   "gate-fat-tools.mjs",
   "hooks-union.mjs",
   "pipeline.mjs",
   "grunt-job.mjs",
   "parse-need.mjs",
+  "package-manager.mjs",
   "persist-handoff.mjs",
   "persist-implementation.mjs",
   "persist-tmp.mjs",
@@ -56,6 +67,7 @@ export const PRODUCT_SCRIPTS = [
   "purge-global-mcps.mjs",
   "scrub-spawn-prompt.mjs",
   "scrub-text-lib.mjs",
+  "session-map.mjs",
   "sync-global-settings.mjs",
   "browser.mjs",
   "speak.mjs",
@@ -70,6 +82,9 @@ export const PRODUCT_SCRIPTS = [
 ]
 
 const COPY_DIRS = [".rulesync", ".grok", ".codex", ".claude", ".agents"]
+/** Generated on dest from the dest tree (grunt refs + consumer extras). Never stamp the package copies. */
+export const GENERATED_MAP_FILES = new Set(["INDEX.md", "skills-map.md", "refs-map.md"])
+const COPY_ROOT_IF_MISSING = [".mcp.json"]
 export const RETIRED_SKILLS = ["parent", "solo", "cascade"]
 export const RETIRED_AGENTS = ["implementer", "thinker"]
 /** Cumulative. Dest `scripts/<name>` deleted on init/upgrade even if no longer shipped. */
@@ -99,6 +114,7 @@ export const RESERVED_SKILLS = [
   "listen",
   "pickup",
   "speak",
+  "su",
   "tmp",
   "write-plan",
 ]
@@ -116,9 +132,9 @@ const AGENT_MIRROR_DIRS = [
   [".codex", "agents"],
 ]
 const GUARDED_MD_FILES = ["AGENTS.md", "CLAUDE.md"]
-// .mcp.json is intentionally not copied here: scripts/emit-mcp-policy.mjs
-// (run via consumer `grunt:rulesync:generate`, see mergeClaudeSettings ordering) owns and
-// merges it, so a plain-copy would just be clobbered/redundant.
+// .mcp.json: copy when dest is missing so first init has a root file. emit-mcp-policy
+// (generate) still owns the merge from .rulesync/mcp-policy.jsonc.
+export const GRUNT_PACKAGE = "@lovrozagar/grunt"
 export const GRUNT_NPM_PREFIX = "grunt:"
 export function toGruntScriptName(k) {
   return k.startsWith(GRUNT_NPM_PREFIX) ? k : `${GRUNT_NPM_PREFIX}${k}`
@@ -130,7 +146,12 @@ export const LAUNCH_SCRIPTS = {
   gemini: "gemini --yolo",
   grok: "grok --yolo",
 }
-const OWNED_HOOK_FILES = ["scrub-spawn-prompt.mjs", "gate-fat-tools.mjs", "orchestrate-parent.js"]
+const OWNED_HOOK_FILES = [
+  "scrub-spawn-prompt.mjs",
+  "gate-fat-tools.mjs",
+  "orchestrate-parent.js",
+  "session-map.mjs",
+]
 
 function sortKeys(obj) {
   return Object.fromEntries(Object.keys(obj).sort().map((k) => [k, obj[k]]))
@@ -279,7 +300,7 @@ export function mergeClaudeSettings(destRoot, pkgRoot) {
 }
 
 function looksGruntOwnedPrefix(prefix) {
-  return /rulesync|sync:globals|^npm run |guarded-roots\.mjs|hooks-union\.mjs|doctor\.mjs|sync-global-settings\.mjs|check-globals\.mjs|purge-global-mcps\.mjs/.test(
+  return /rulesync|sync:globals|^(?:npm|yarn|pnpm|bun) run |guarded-roots\.mjs|hooks-union\.mjs|doctor\.mjs|sync-global-settings\.mjs|check-globals\.mjs|purge-global-mcps\.mjs/.test(
     prefix,
   )
 }
@@ -317,24 +338,47 @@ function mergeScriptValue(newSrc, cur) {
   return newSrc
 }
 
-function rewriteNpmRunRefs(scripts, srcKeys) {
+function rewritePackageManagerRunRefs(scripts, srcKeys) {
   const keys = srcKeys
     .filter((k) => k !== toGruntScriptName(k))
     .sort((a, b) => b.length - a.length)
   if (!keys.length) return
+  const pm = PACKAGE_MANAGERS.join("|")
   for (const name of Object.keys(scripts)) {
     let val = scripts[name]
     if (typeof val !== "string") continue
     for (const k of keys) {
       val = val.replace(
-        new RegExp(`npm run ${escapeRe(k)}(?=$|\\s|;|&)`, "g"),
-        `npm run ${toGruntScriptName(k)}`,
+        new RegExp(`(${pm}) run ${escapeRe(k)}(?=$|\\s|;|&)`, "g"),
+        `$1 run ${toGruntScriptName(k)}`,
       )
     }
     scripts[name] = val
   }
 }
 
+export function placeGruntDevDependency(destPkg, srcPkg) {
+  const deps =
+    destPkg.dependencies && typeof destPkg.dependencies === "object"
+      ? destPkg.dependencies
+      : null
+  destPkg.devDependencies = { ...(destPkg.devDependencies || {}) }
+  const fromDep = deps?.[GRUNT_PACKAGE]
+  const fromDev = destPkg.devDependencies[GRUNT_PACKAGE]
+  if (fromDep != null && deps) {
+    delete destPkg.dependencies[GRUNT_PACKAGE]
+    if (fromDev == null) destPkg.devDependencies[GRUNT_PACKAGE] = fromDep
+    if (Object.keys(destPkg.dependencies).length === 0) delete destPkg.dependencies
+  }
+  if (
+    destPkg.devDependencies[GRUNT_PACKAGE] == null &&
+    srcPkg?.name === GRUNT_PACKAGE &&
+    srcPkg.version
+  ) {
+    destPkg.devDependencies[GRUNT_PACKAGE] = srcPkg.version
+  }
+}
+
 export function mergePackageJson(dest, pkgRoot) {
   const destPath = path.join(dest, "package.json")
   let destPkg = {}
@@ -377,18 +421,47 @@ export function mergePackageJson(dest, pkgRoot) {
     const staleKey = `grunt:yolo:${k}`
     if (destPkg.scripts[staleKey] === v) delete destPkg.scripts[staleKey]
   }
-  rewriteNpmRunRefs(destPkg.scripts, srcKeys)
+  rewritePackageManagerRunRefs(destPkg.scripts, srcKeys)
   destPkg.devDependencies = { ...(destPkg.devDependencies || {}) }
   destPkg.devDependencies["smol-toml"] = srcPkg.devDependencies["smol-toml"]
   destPkg.devDependencies["rulesync"] = srcPkg.devDependencies["rulesync"]
   const clack = srcPkg.dependencies?.["@clack/prompts"]
   if (clack) destPkg.devDependencies["@clack/prompts"] = clack
+  placeGruntDevDependency(destPkg, srcPkg)
   destPkg.scripts = sortKeys(destPkg.scripts)
   destPkg.devDependencies = sortKeys(destPkg.devDependencies)
   fs.writeFileSync(destPath, `${JSON.stringify(destPkg, null, 2)}\n`)
 }
 
-export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileSync, skipGlobals = false, applyGlobals, onPhase } = {}) {
+function copyRootIfMissing(dest, pkgRoot) {
+  for (const file of COPY_ROOT_IF_MISSING) {
+    const src = path.join(pkgRoot, file)
+    const d = path.join(dest, file)
+    if (!fs.existsSync(src) || fs.existsSync(d)) continue
+    fs.copyFileSync(src, d)
+  }
+}
+
+function emitDestMaps(dest) {
+  if (!fs.existsSync(path.join(dest, LAW_REL))) return
+  const maps = emitMaps({ workspaceRoot: dest })
+  if (!maps.ok) throw new Error(maps.error || "emit-maps failed")
+}
+
+export function resolveInitPackageManager(dest, { packageManager, env = process.env } = {}) {
+  if (packageManager) {
+    const name = String(packageManager).toLowerCase()
+    if (!isPackageManager(name)) {
+      throw new Error(UNKNOWN_PACKAGE_MANAGER)
+    }
+    return name
+  }
+  const detected = detectPackageManager({ cwd: dest, env })
+  if (!detected.manager) throw new Error(UNKNOWN_PACKAGE_MANAGER)
+  return detected.manager
+}
+
+export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileSync, skipGlobals = false, applyGlobals, onPhase, packageManager, env = process.env } = {}) {
   dest = path.resolve(dest)
   const pkgRoot = path.resolve(pkgRootOpt ?? PKG_ROOT)
   const skipGlobalsApply =
@@ -429,6 +502,12 @@ export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileS
           filter: (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)),
+        })
       } else {
         fs.cpSync(src, d, { recursive: true, force: true })
       }
@@ -453,26 +532,31 @@ export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileS
     fs.mkdirSync(path.join(dest, ".tmp"), { recursive: true })
     mergeGitignore(dest)
 
-    if (!self) mergePackageJson(dest, pkgRoot)
+    if (!self) {
+      mergePackageJson(dest, pkgRoot)
+      copyRootIfMissing(dest, pkgRoot)
+      emitDestMaps(dest)
+    }
   })
 
   // Self-skip: file/dir merge + .tmp + gitignore only. No package.json merge,
-  // npm install, or generate/sync/check (would mutate this package in-place).
+  // install, or generate/sync/check (would mutate this package in-place).
   if (self) return
 
-  const runNpm = (name, args) => {
+  const pm = resolveInitPackageManager(dest, { packageManager, env })
+  const runPm = (name, args) => {
     onPhase?.(name, "start")
     onPhase?.(name, "stop")
-    exec("npm", args, { cwd: dest, stdio: "inherit" })
+    exec(pm, args, { cwd: dest, stdio: "inherit" })
   }
-  runNpm("install", ["install"])
+  runPm("install", installArgs(pm))
   const guardedSnap = snapshotGuardedRoots(dest)
-  runNpm("generate", ["run", toGruntScriptName("rulesync:generate")])
+  runPm("generate", runScriptArgs(pm, toGruntScriptName("rulesync:generate")))
   remergeGuardedRoots(dest, guardedSnap)
   if (!skipGlobalsApply) {
-    runNpm("sync-globals", ["run", toGruntScriptName("sync:globals:apply")])
+    runPm("sync-globals", runScriptArgs(pm, toGruntScriptName("sync:globals:apply")))
   }
   withGuardedCheckInteriors(dest, () => {
-    runNpm("check", ["run", toGruntScriptName("rulesync:check")])
+    runPm("check", runScriptArgs(pm, toGruntScriptName("rulesync:check")))
   })
 }

package/cli/init.test.ts

@@ -4,6 +4,18 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { afterEach, describe, expect, it, vi } from "vitest";
+
+const emitMaps = vi.hoisted(() => vi.fn());
+const actualEmitMaps = vi.hoisted(() => ({ fn: null as null | ((...args: unknown[]) => unknown) }));
+
+vi.mock("../scripts/emit-maps.mjs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../scripts/emit-maps.mjs")>();
+  actualEmitMaps.fn = actual.emitMaps;
+  emitMaps.mockImplementation((...args: unknown[]) =>
+    actual.emitMaps(...(args as Parameters<typeof actual.emitMaps>)),
+  );
+  return { ...actual, emitMaps };
+});
 import {
   MAX_GUARDED_MARKDOWN_BYTES,
   PRODUCT_SCRIPTS,
@@ -28,7 +40,10 @@ import {
   mergeGitignore,
   mergeGuardedContent,
   mergeGuardedMarkdown,
+  GENERATED_MAP_FILES,
+  GRUNT_PACKAGE,
   mergePackageJson,
+  placeGruntDevDependency,
   remergeGuardedRoots,
   samePath,
   shouldAutoSkipGlobals,
@@ -37,6 +52,7 @@ import {
   withGuardedCheckInteriors,
   writeMergedGuardedFile,
 } from "./init.mjs";
+import { UNKNOWN_PACKAGE_MANAGER } from "../scripts/package-manager.mjs";
 import { runGuardedRoots } from "../scripts/guarded-roots.mjs";
 
 const tmpDirs: string[] = [];
@@ -44,6 +60,10 @@ afterEach(() => {
   for (const d of tmpDirs.splice(0)) {
     fs.rmSync(d, { recursive: true, force: true });
   }
+  emitMaps.mockReset();
+  emitMaps.mockImplementation((...args: unknown[]) =>
+    (actualEmitMaps.fn as (...a: unknown[]) => unknown)(...args),
+  );
 });
 
 function tmp(prefix: string) {
@@ -62,6 +82,17 @@ const SRC_CLAUDE_SETTINGS = {
     deny: ["Agent(Explore)", "Agent(orchestrator)", "mcp__*"],
   },
   hooks: {
+    SessionStart: [
+      {
+        hooks: [
+          {
+            type: "command",
+            command: 'node "${ROOT}/scripts/session-map.mjs"',
+            timeout: 5,
+          },
+        ],
+      },
+    ],
     PreToolUse: [
       {
         matcher: "spawn",
@@ -1408,6 +1439,113 @@ describe("mergePackageJson", () => {
     expect(out.scripts.check).toBe("npm run grunt:rulesync:check && npm run rulesync:check:raw");
   });
 
+  it("rewrites yarn/pnpm/bun run refs the same way as npm run", () => {
+    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-pm-rewrite-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: {
+          "rulesync:check": "node ./scripts/guarded-roots.mjs check",
+          check: "pnpm run rulesync:check && yarn run rulesync:check && bun run rulesync:check",
+        },
+      }),
+    );
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts.check).toBe(
+      "pnpm run grunt:rulesync:check && yarn run grunt:rulesync:check && bun run grunt:rulesync:check",
+    );
+  });
+
+  it("moves @lovrozagar/grunt from dependencies to devDependencies", () => {
+    const pkgRoot = stubPkgRoot({
+      name: GRUNT_PACKAGE,
+      version: "0.6.2",
+      scripts: { "rulesync:generate": "gen" },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-grunt-dep-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        name: "app",
+        dependencies: { [GRUNT_PACKAGE]: "0.6.2", lodash: "4" },
+        scripts: {},
+      }),
+    );
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.dependencies).toEqual({ lodash: "4" });
+    expect(out.devDependencies[GRUNT_PACKAGE]).toBe("0.6.2");
+  });
+
+  it("drops empty dependencies after moving grunt", () => {
+    const pkgRoot = stubPkgRoot({
+      name: GRUNT_PACKAGE,
+      version: "0.7.0",
+      scripts: {},
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-grunt-onlydep-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({ dependencies: { [GRUNT_PACKAGE]: "0.6.2" } }),
+    );
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.dependencies).toBeUndefined();
+    expect(out.devDependencies[GRUNT_PACKAGE]).toBe("0.6.2");
+  });
+
+  it("adds missing grunt as a devDependency from the running package version", () => {
+    const pkgRoot = stubPkgRoot({
+      name: GRUNT_PACKAGE,
+      version: "0.7.0",
+      scripts: {},
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-grunt-add-");
+    fs.writeFileSync(path.join(dest, "package.json"), JSON.stringify({ name: "app" }));
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.devDependencies[GRUNT_PACKAGE]).toBe("0.7.0");
+  });
+
+  it("keeps an existing grunt devDependency version", () => {
+    const pkgRoot = stubPkgRoot({
+      name: GRUNT_PACKAGE,
+      version: "0.7.0",
+      scripts: {},
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-grunt-keep-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        devDependencies: { [GRUNT_PACKAGE]: "^0.6.2" },
+        dependencies: { [GRUNT_PACKAGE]: "0.6.2" },
+      }),
+    );
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.dependencies).toBeUndefined();
+    expect(out.devDependencies[GRUNT_PACKAGE]).toBe("^0.6.2");
+  });
+
+  it("placeGruntDevDependency is a no-op when src is not grunt", () => {
+    const destPkg: { dependencies?: Record<string, string>; devDependencies?: Record<string, string> } = {
+      dependencies: { lodash: "4" },
+    };
+    placeGruntDevDependency(destPkg, { name: "fixture-pkg", version: "1.0.0" });
+    expect(destPkg.dependencies).toEqual({ lodash: "4" });
+    expect(destPkg.devDependencies?.[GRUNT_PACKAGE]).toBeUndefined();
+  });
+
   it("skips non-string dest scripts when rewriting npm run refs", () => {
     const pkgRoot = stubPkgRoot({
       name: "fixture-pkg",
@@ -1526,7 +1664,7 @@ describe("init", () => {
     const pkgRoot = stubPkgRoot();
     const dest = tmp("grunt-dest-");
     const exec = vi.fn();
-    init(dest, { pkgRoot, execFileSync: exec });
+    init(dest, { pkgRoot, execFileSync: exec, packageManager: "npm" });
 
     for (const d of COPY_DIRS) {
       if (d === ".claude") continue;
@@ -1601,6 +1739,24 @@ describe("init", () => {
     expect(settings.permissions.deny).toContain("mcp__*");
   });
 
+  it("re-init replaces a prior grunt session-map SessionStart group instead of duplicating it", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-rerun-map-");
+    fs.mkdirSync(path.join(dest, ".claude"), { recursive: true });
+    const mapGroup = {
+      hooks: [{ type: "command", command: 'node "$X/scripts/session-map.mjs"', timeout: 5 }],
+    };
+    fs.writeFileSync(
+      path.join(dest, ".claude", "settings.json"),
+      JSON.stringify({ permissions: {}, hooks: { SessionStart: [mapGroup] } }),
+    );
+    init(dest, { pkgRoot, execFileSync: vi.fn() });
+    const settings = JSON.parse(
+      fs.readFileSync(path.join(dest, ".claude", "settings.json"), "utf8"),
+    );
+    expect(settings.hooks.SessionStart).toEqual(SRC_CLAUDE_SETTINGS.hooks.SessionStart);
+  });
+
   it("omitted execFileSync uses default; self-skip never invokes it", () => {
     const pkgRoot = stubPkgRoot();
     init(pkgRoot, { pkgRoot });
@@ -1645,6 +1801,7 @@ describe("init", () => {
       "listen",
       "pickup",
       "speak",
+      "su",
       "tmp",
       "write-plan",
     ]);
@@ -1741,7 +1898,7 @@ describe("init", () => {
     const pkgRoot = stubPkgRoot();
     const dest = tmp("grunt-skip-globals-");
     const exec = vi.fn();
-    init(dest, { pkgRoot, execFileSync: exec, skipGlobals: true });
+    init(dest, { pkgRoot, execFileSync: exec, skipGlobals: true, packageManager: "npm" });
     expect(exec.mock.calls.map((c) => [c[0], c[1]])).toEqual([
       ["npm", ["install"]],
       ["npm", ["run", "grunt:rulesync:generate"]],
@@ -1879,6 +2036,128 @@ describe("init", () => {
     expect(claude.split("<!-- grunt:end -->")).toHaveLength(2);
   });
 
+  it("pnpm-lock.yaml dest installs with pnpm even if invocation is npm", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-pnpm-");
+    fs.writeFileSync(path.join(dest, "pnpm-lock.yaml"), "lockfileVersion: 9\n");
+    const exec = vi.fn();
+    init(dest, {
+      pkgRoot,
+      execFileSync: exec,
+      env: { npm_config_user_agent: "npm/10.0.0 node/v22" },
+    });
+    expect(exec.mock.calls.map((c) => [c[0], c[1]])).toEqual([
+      ["pnpm", ["install"]],
+      ["pnpm", ["run", "grunt:rulesync:generate"]],
+      ["pnpm", ["run", "grunt:sync:globals:apply"]],
+      ["pnpm", ["run", "grunt:rulesync:check"]],
+    ]);
+  });
+
+  it("packageManager option wins over dest lockfile", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-pm-opt-");
+    fs.writeFileSync(path.join(dest, "yarn.lock"), "");
+    const exec = vi.fn();
+    init(dest, { pkgRoot, execFileSync: exec, packageManager: "bun" });
+    expect(exec.mock.calls[0][0]).toBe("bun");
+  });
+
+  it("unknown manager throws and does not exec", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-pm-unknown-");
+    const exec = vi.fn();
+    expect(() =>
+      init(dest, { pkgRoot, execFileSync: exec, env: {}, packageManager: undefined }),
+    ).toThrow(UNKNOWN_PACKAGE_MANAGER);
+    expect(exec).not.toHaveBeenCalled();
+  });
+
+  it("invalid packageManager option throws", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-pm-bad-");
+    const exec = vi.fn();
+    expect(() => init(dest, { pkgRoot, execFileSync: exec, packageManager: "deno" })).toThrow(
+      UNKNOWN_PACKAGE_MANAGER,
+    );
+    expect(exec).not.toHaveBeenCalled();
+  });
+
+  it("yarn.lock dest uses yarn run args without npm --", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-yarn-");
+    fs.writeFileSync(path.join(dest, "yarn.lock"), "");
+    const exec = vi.fn();
+    init(dest, { pkgRoot, execFileSync: exec, skipGlobals: true, env: {} });
+    expect(exec.mock.calls.map((c) => [c[0], c[1]])).toEqual([
+      ["yarn", ["install"]],
+      ["yarn", ["run", "grunt:rulesync:generate"]],
+      ["yarn", ["run", "grunt:rulesync:check"]],
+    ]);
+  });
+
+  it("merges dest refs into INDEX and writes .mcp.json when missing", () => {
+    const dest = tmp("grunt-maps-merge-");
+    fs.mkdirSync(path.join(dest, ".rulesync", "reference"), { recursive: true });
+    fs.writeFileSync(
+      path.join(dest, ".rulesync", "reference", "stripe.md"),
+      "# Stripe\n\nConsumer stripe payments ref.\n",
+    );
+    const exec = vi.fn();
+    init(dest, { execFileSync: exec, skipGlobals: true, packageManager: "npm" });
+    expect(GENERATED_MAP_FILES.has("INDEX.md")).toBe(true);
+    const index = fs.readFileSync(path.join(dest, ".rulesync", "reference", "INDEX.md"), "utf8");
+    expect(index).toMatch(/stripe\.md/);
+    expect(index).toMatch(/Consumer stripe payments ref/);
+    expect(index).toMatch(/browser\.md/);
+    const refsMap = fs.readFileSync(path.join(dest, ".rulesync", "reference", "refs-map.md"), "utf8");
+    expect(refsMap).toMatch(/stripe\.md/);
+    expect(fs.existsSync(path.join(dest, ".mcp.json"))).toBe(true);
+    expect(JSON.parse(fs.readFileSync(path.join(dest, ".mcp.json"), "utf8"))).toEqual({
+      mcpServers: {},
+    });
+  });
+
+  it("keeps dest .mcp.json when already present", () => {
+    const dest = tmp("grunt-mcp-keep-");
+    fs.writeFileSync(
+      path.join(dest, ".mcp.json"),
+      `${JSON.stringify({ mcpServers: { tasks: { command: "npx" } } }, null, 2)}\n`,
+    );
+    init(dest, { execFileSync: vi.fn(), skipGlobals: true, packageManager: "npm" });
+    expect(JSON.parse(fs.readFileSync(path.join(dest, ".mcp.json"), "utf8"))).toEqual({
+      mcpServers: { tasks: { command: "npx" } },
+    });
+  });
+
+  it("throws when dest emit-maps fails", () => {
+    emitMaps.mockReturnValue({ ok: false, error: "maps boom" });
+    const dest = tmp("grunt-maps-fail-");
+    expect(() =>
+      init(dest, { execFileSync: vi.fn(), skipGlobals: true, packageManager: "npm" }),
+    ).toThrow("maps boom");
+    emitMaps.mockReturnValue({ ok: false });
+    const dest2 = tmp("grunt-maps-fail2-");
+    expect(() =>
+      init(dest2, { execFileSync: vi.fn(), skipGlobals: true, packageManager: "npm" }),
+    ).toThrow("emit-maps failed");
+  });
+
+  it("does not stamp package INDEX over dest; re-emits union", () => {
+    const dest = tmp("grunt-index-keep-");
+    fs.mkdirSync(path.join(dest, ".rulesync", "reference"), { recursive: true });
+    fs.writeFileSync(path.join(dest, ".rulesync", "reference", "owned.md"), "# Owned\n\nDest-only.\n");
+    fs.writeFileSync(
+      path.join(dest, ".rulesync", "reference", "INDEX.md"),
+      "stale grunt-only index\n",
+    );
+    init(dest, { execFileSync: vi.fn(), skipGlobals: true, packageManager: "npm" });
+    const index = fs.readFileSync(path.join(dest, ".rulesync", "reference", "INDEX.md"), "utf8");
+    expect(index).not.toBe("stale grunt-only index\n");
+    expect(index).toMatch(/owned\.md/);
+    expect(index).toMatch(/browser\.md/);
+  });
+
   it("onPhase merge then npm phases stop before exec", () => {
     const pkgRoot = stubPkgRoot();
     const dest = tmp("grunt-onphase-");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovrozagar/grunt",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "Multi-agent orchestrator SoT — deep-merge rulesync trees, product scripts, and generate pipeline into a consumer repo",
   "keywords": [
     "agents",
@@ -31,11 +31,13 @@
     "scripts/guarded-md.mjs",
     "scripts/guarded-roots.mjs",
     "scripts/emit-mcp-policy.mjs",
+    "scripts/folder-map.mjs",
     "scripts/gate-fat-tools.mjs",
     "scripts/hooks-union.mjs",
     "scripts/pipeline.mjs",
     "scripts/grunt-job.mjs",
     "scripts/parse-need.mjs",
+    "scripts/package-manager.mjs",
     "scripts/persist-handoff.mjs",
     "scripts/persist-implementation.mjs",
     "scripts/persist-tmp.mjs",
@@ -43,6 +45,7 @@
     "scripts/purge-global-mcps.mjs",
     "scripts/scrub-spawn-prompt.mjs",
     "scripts/scrub-text-lib.mjs",
+    "scripts/session-map.mjs",
     "scripts/sync-global-settings.mjs",
     "scripts/browser.mjs",
     "scripts/speak.mjs",

package/scripts/check-globals.mjs

@@ -4,8 +4,15 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { parse as parseToml } from "smol-toml";
+import { detectPackageManager, runScriptLine } from "./package-manager.mjs";
 
-const APPLY_HINT = "npm run sync:globals:apply";
+function applyHint(workspaceRoot) {
+  const { manager } = detectPackageManager({
+    cwd: workspaceRoot || process.cwd(),
+    env: process.env,
+  });
+  return runScriptLine(manager, "sync:globals:apply");
+}
 const PROJECT_REL = ".grok/config.toml";
 const HOME_REL = ".grok/config.toml";
 
@@ -33,16 +40,17 @@ function parseTomlFile(abs, label) {
 export function checkGlobals({ home, workspaceRoot } = {}) {
   const homeDir = home || process.env.HOME;
   const ws = workspaceRoot || process.cwd();
+  const hint = applyHint(ws);
   if (!homeDir) {
-    return { ok: false, error: `HOME required; ${APPLY_HINT}` };
+    return { ok: false, error: `HOME required; ${hint}` };
   }
   const homeConfig = path.resolve(homeDir, HOME_REL);
   const homeParsed = parseTomlFile(homeConfig, "home ~/.grok/config.toml");
   if (!homeParsed.ok) {
     if (homeParsed.missing) {
-      return { ok: false, error: `missing ~/.grok/config.toml; ${APPLY_HINT}` };
+      return { ok: false, error: `missing ~/.grok/config.toml; ${hint}` };
     }
-    return { ok: false, error: `${homeParsed.error}; ${APPLY_HINT}` };
+    return { ok: false, error: `${homeParsed.error}; ${hint}` };
   }
   const agentName = homeParsed.value.agent && homeParsed.value.agent.name;
   const compaction =
@@ -50,7 +58,7 @@ export function checkGlobals({ home, workspaceRoot } = {}) {
   if (agentName !== "orchestrator" || compaction !== true) {
     return {
       ok: false,
-      error: `home [agent].name must be orchestrator and [features].two_pass_compaction must be true; ${APPLY_HINT}`,
+      error: `home [agent].name must be orchestrator and [features].two_pass_compaction must be true; ${hint}`,
     };
   }