@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/sync/agents/hooks.ts

@@ -0,0 +1,401 @@
+/**
+ * The four hook files, from the merged `hooks.jsonc`: `.claude/settings.json`, `.codex/hooks.json`,
+ * `.agents/hooks.json` and `.cursor/hooks.json`, in the shapes rulesync 43.7.0 wrote. Grok's hook configs are
+ * static stock files. Each host sees the shared events it supports in source order, then its own override block
+ * (`claudecode`, `codexcli`, `antigravity-cli`, `cursor`): a same event is replaced in place, new ones go last.
+ * `D:<n>` cites a line of rulesync 43.7.0's bundled `dist/import-*.js`.
+ */
+import type { Host } from "../../config.ts";
+import { expandHookCommand } from "../../scripts/hook-command.ts";
+import type { Sources } from "./sources.ts";
+
+type Json = Record<string, unknown>;
+type Def = Json;
+type Group = { matcher?: string; hooks: Json[] };
+
+/** Canonical event to Claude event, D:6011-6044; also the events Claude supports. */
+const CLAUDE_EVENTS: Record<string, string> = {
+  sessionStart: "SessionStart",
+  sessionEnd: "SessionEnd",
+  preToolUse: "PreToolUse",
+  postToolUse: "PostToolUse",
+  beforeSubmitPrompt: "UserPromptSubmit",
+  stop: "Stop",
+  subagentStop: "SubagentStop",
+  preCompact: "PreCompact",
+  permissionRequest: "PermissionRequest",
+  notification: "Notification",
+  setup: "Setup",
+  worktreeCreate: "WorktreeCreate",
+  worktreeRemove: "WorktreeRemove",
+  messageDisplay: "MessageDisplay",
+  instructionsLoaded: "InstructionsLoaded",
+  userPromptExpansion: "UserPromptExpansion",
+  postToolUseFailure: "PostToolUseFailure",
+  postToolBatch: "PostToolBatch",
+  permissionDenied: "PermissionDenied",
+  subagentStart: "SubagentStart",
+  taskCreated: "TaskCreated",
+  taskCompleted: "TaskCompleted",
+  stopFailure: "StopFailure",
+  teammateIdle: "TeammateIdle",
+  configChange: "ConfigChange",
+  cwdChanged: "CwdChanged",
+  fileChanged: "FileChanged",
+  directoryAdded: "DirectoryAdded",
+  postCompact: "PostCompact",
+  elicitation: "Elicitation",
+  elicitationResult: "ElicitationResult",
+  preModelSwitch: "PreModelSwitch",
+  postModelSwitch: "PostModelSwitch",
+};
+/** D:6525-6540. */
+const CODEX_EVENTS: Record<string, string> = {
+  sessionStart: "SessionStart",
+  sessionEnd: "SessionEnd",
+  preToolUse: "PreToolUse",
+  postToolUse: "PostToolUse",
+  beforeSubmitPrompt: "UserPromptSubmit",
+  stop: "Stop",
+  stopCancelled: "Interrupt",
+  permissionRequest: "PermissionRequest",
+  subagentStart: "SubagentStart",
+  subagentStop: "SubagentStop",
+  preCompact: "PreCompact",
+  postCompact: "PostCompact",
+  preModelInvocation: "PreModelRequest",
+  postModelInvocation: "PostModelRequest",
+};
+/** D:6135-6142. */
+const ANTIGRAVITY_EVENTS: Record<string, string> = {
+  sessionStart: "SessionStart",
+  preToolUse: "PreToolUse",
+  postToolUse: "PostToolUse",
+  preModelInvocation: "PreInvocation",
+  postModelInvocation: "PostInvocation",
+  stop: "Stop",
+};
+/** D:6162-6184: cursor keeps the canonical names. */
+const CURSOR_EVENTS = Object.fromEntries(
+  [
+    "sessionStart",
+    "sessionEnd",
+    "preToolUse",
+    "postToolUse",
+    "beforeSubmitPrompt",
+    "stop",
+    "subagentStop",
+    "preCompact",
+    "postToolUseFailure",
+    "subagentStart",
+    "beforeShellExecution",
+    "afterShellExecution",
+    "beforeMCPExecution",
+    "afterMCPExecution",
+    "beforeReadFile",
+    "afterFileEdit",
+    "afterAgentResponse",
+    "afterAgentThought",
+    "beforeTabFileRead",
+    "afterTabFileEdit",
+    "workspaceOpen",
+  ].map((event) => [event, event]),
+);
+/** Whole matcher tokens Antigravity names differently, D:54345-54351. */
+const ANTIGRAVITY_TOOLS: Record<string, string> = {
+  Bash: "run_command",
+  Read: "(?:read_file|view_file)",
+  Write: "(?:write_file|write_to_file)",
+  Edit: "(?:edit_file|replace_file_content)",
+  WebSearch: "search_web",
+};
+/** A name token outside escapes and character classes, D:52398. */
+const MATCHER_TOKEN = /\\.|\[(?:\\.|[^\]\\])*\]|(?<=^|[^\w\\]|\\\w)[A-Za-z_]\w*(?!\w)/gs;
+const CURSOR_TYPES = new Set(["command", "prompt"]);
+const CLAUDE_SCHEMA = "https://json.schemastore.org/claude-code-settings.json";
+
+/** How one matcher-group host converts a definition (the converter configs at D:55604-55631, D:56372-56378, D:54389-54398). */
+/**
+ * One passthrough field (D:53298-53339): written when valid for its kind (D:53378-53385, `isStringArray` D:4415),
+ * and only on command hooks when `commandOnly`. `onFailure` is claude's keyword field (D:55667-55678, D:53527-53572):
+ * `failClosed: true` becomes `onFailure: "block"` on command and http hooks, except on the events claude ignores
+ * it on and on command hooks that set `async` or `asyncRewake`.
+ */
+type Passthrough =
+  | { key: string; kind: "boolean" | "number" | "string" | "array"; commandOnly?: true }
+  | { key: "onFailure"; kind: "keyword" };
+
+const VALID: Record<Exclude<Passthrough["kind"], "keyword">, (value: unknown) => boolean> = {
+  boolean: (value) => typeof value === "boolean",
+  number: (value) => Number.isFinite(value),
+  string: (value) => typeof value === "string" && value !== "",
+  array: (value) => Array.isArray(value) && value.every((item) => typeof item === "string"),
+};
+const ON_FAILURE_IGNORED = new Set(["stop", "subagentStop", "taskCompleted", "teammateIdle"]);
+
+interface Target {
+  overrideKey: string;
+  names: Record<string, string>;
+  /** Events whose groups carry no matcher; translation is skipped there too (D:53195, D:53796). */
+  noMatcher: ReadonlySet<string>;
+  /** Hook types written; others are skipped (D:53520, D:53681). */
+  types: ReadonlySet<string>;
+  command?: (command: string, def: Def) => string;
+  /** Hook fields copied through, in the order rulesync writes them, ahead of `type` (D:53582-53640). */
+  passthrough: readonly Passthrough[];
+  matcher?: (matcher: string) => string;
+  /** Whether prompt and agent hooks carry `model` (D:55632 `emitsPromptModel`). */
+  promptModel: boolean;
+  /** Whether `name` and `description` are written (codex `passthroughFields`, D:56378). */
+  named: boolean;
+}
+
+const CLAUDE: Target = {
+  overrideKey: "claudecode",
+  names: CLAUDE_EVENTS,
+  noMatcher: new Set([
+    "worktreeCreate",
+    "worktreeRemove",
+    "messageDisplay",
+    "postToolBatch",
+    "taskCreated",
+    "taskCompleted",
+    "teammateIdle",
+    "cwdChanged",
+    "beforeSubmitPrompt",
+    "stop",
+  ]),
+  types: new Set(["command", "prompt", "http", "mcp_tool", "agent"]),
+  command: prefixProjectDir,
+  // D:55633-55684, in emit order: booleans, keyword, strings, arrays.
+  passthrough: [
+    { key: "once", kind: "boolean" },
+    { key: "async", kind: "boolean", commandOnly: true },
+    { key: "asyncRewake", kind: "boolean", commandOnly: true },
+    { key: "continueOnBlock", kind: "boolean" },
+    { key: "onFailure", kind: "keyword" },
+    { key: "if", kind: "string" },
+    { key: "statusMessage", kind: "string" },
+    { key: "shell", kind: "string", commandOnly: true },
+    { key: "args", kind: "array", commandOnly: true },
+  ],
+  promptModel: true,
+  named: false,
+};
+const CODEX: Target = {
+  overrideKey: "codexcli",
+  names: CODEX_EVENTS,
+  noMatcher: new Set(),
+  types: new Set(["command", "mcp_tool"]),
+  // D:56377-56394, in emit order: booleans, numbers, strings.
+  passthrough: [
+    { key: "async", kind: "boolean", commandOnly: true },
+    { key: "additionalContextLimit", kind: "number", commandOnly: true },
+    { key: "commandWindows", kind: "string", commandOnly: true },
+    { key: "statusMessage", kind: "string" },
+  ],
+  promptModel: false,
+  named: true,
+};
+/** D:54322-54327; these events are also written as bare handler lists (D:54405-54410). */
+const ANTIGRAVITY_NO_MATCHER = new Set(["sessionStart", "preModelInvocation", "postModelInvocation", "stop"]);
+const ANTIGRAVITY_FLAT = new Set([...ANTIGRAVITY_NO_MATCHER].map((event) => ANTIGRAVITY_EVENTS[event]));
+const ANTIGRAVITY: Target = {
+  overrideKey: "antigravity-cli",
+  names: ANTIGRAVITY_EVENTS,
+  noMatcher: ANTIGRAVITY_NO_MATCHER,
+  types: new Set(["command"]),
+  passthrough: [],
+  matcher: (matcher) =>
+    matcher.replace(MATCHER_TOKEN, (token) =>
+      Object.hasOwn(ANTIGRAVITY_TOOLS, token) ? ANTIGRAVITY_TOOLS[token]! : token,
+    ),
+  promptModel: false,
+  named: false,
+};
+
+/** Path to text for each enabled host's hook file; `claudeBase` is the stock `agents/settings/claude.json`. */
+export function renderHooks(sources: Sources, hosts: readonly Host[], claudeBase: string): Map<string, string> {
+  const config = sources.hooks.value;
+  const files = new Map<string, string>();
+  if (hosts.includes("claude")) {
+    files.set(".claude/settings.json", text(claudeSettings(claudeBase, toolHooks(config, CLAUDE))));
+  }
+  if (hosts.includes("codex"))
+    files.set(".codex/hooks.json", text({ hooks: filterCodexHandlers(toolHooks(config, CODEX)) }));
+  if (hosts.includes("antigravity")) {
+    const flat = Object.entries(toolHooks(config, ANTIGRAVITY)).map(([event, groups]) => [
+      event,
+      ANTIGRAVITY_FLAT.has(event) ? groups.flatMap((group) => group.hooks) : groups,
+    ]);
+    files.set(".agents/hooks.json", text(flat.length === 0 ? {} : { rulesync: Object.fromEntries(flat) }));
+  }
+  if (hosts.includes("cursor"))
+    files.set(".cursor/hooks.json", text({ version: config.version ?? 1, hooks: cursorHooks(config) }));
+  return files;
+}
+
+function text(value: unknown): string {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+/** The host's name for an event; an override event it has none for keeps its own (`lookupOwn … ?? eventName`, D:53765-53768). */
+function nameOf(names: Record<string, string>, event: string): string {
+  return Object.hasOwn(names, event) ? names[event]! : event;
+}
+
+/** Shared events the host names, in source order, then `{...shared, ...override}`; overrides are unfiltered (D:53170-53178). */
+function effectiveEvents(config: Json, overrideKey: string, names: Record<string, string>): [string, Def[]][] {
+  const shared = Object.entries((config.hooks as Record<string, Def[]> | undefined) ?? {}).filter(([event]) =>
+    Object.hasOwn(names, event),
+  );
+  const override = (config[overrideKey] as { hooks?: Record<string, Def[]> } | undefined)?.hooks ?? {};
+  return Object.entries({ ...Object.fromEntries(shared), ...override });
+}
+
+/**
+ * Per event, defs grouped by (translated) matcher in first-appearance order (D:53186-53215): `{matcher, hooks}`,
+ * or `{hooks}` when the matcher is empty or the event takes none. Groups left without a writable hook, and events
+ * left without a group, are dropped (D:53756-53800).
+ */
+function toolHooks(config: Json, target: Target): Record<string, Group[]> {
+  const out: Record<string, Group[]> = {};
+  for (const [event, defs] of effectiveEvents(config, target.overrideKey, target.names)) {
+    const noMatcher = target.noMatcher.has(event);
+    const groups = new Map<string, Def[]>();
+    for (const def of defs) {
+      const raw = (def.matcher as string | undefined) ?? "";
+      const matcher = raw === "" || noMatcher || target.matcher === undefined ? raw : target.matcher(raw);
+      groups.set(matcher, [...(groups.get(matcher) ?? []), def]);
+    }
+    const entries: Group[] = [];
+    for (const [matcher, group] of groups) {
+      const hooks = group
+        .filter((def) => target.types.has((def.type as string | undefined) ?? "command"))
+        .map((def) => hookObject(def, event, target));
+      if (hooks.length === 0) continue;
+      entries.push(matcher === "" || noMatcher ? { hooks } : { matcher, hooks });
+    }
+    if (entries.length > 0) out[nameOf(target.names, event)] = entries;
+  }
+  return out;
+}
+
+/**
+ * Passthrough fields, `type`, `command`, `timeout`, `prompt`, the type's payload, then codex's `name`/`description`
+ * (D:53698-53735, D:53598-53612).
+ */
+function hookObject(def: Def, event: string, target: Target): Json {
+  const type = (def.type as string | undefined) ?? "command";
+  const source = typeof def.command === "string" ? expandHookCommand(def.command) : def.command;
+  const command = typeof source === "string" && target.command !== undefined ? target.command(source, def) : source;
+  const payload: Record<string, readonly string[]> = {
+    http: ["url", "headers", "allowedEnvVars"],
+    mcp_tool: ["server", "tool", "input"],
+    prompt: target.promptModel ? ["model"] : [],
+    agent: target.promptModel ? ["model"] : [],
+  };
+  const fields = {
+    ...passthroughFields(def, type, event, target),
+    type,
+    command,
+    timeout: def.timeout,
+    prompt: def.prompt,
+  } as Json;
+  for (const key of [...(payload[type] ?? []), ...(target.named ? ["name", "description"] : [])])
+    fields[key] = def[key];
+  return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined && value !== null));
+}
+
+function passthroughFields(def: Def, type: string, event: string, target: Target): Json {
+  const out: Json = {};
+  for (const field of target.passthrough) {
+    if (field.kind === "keyword") {
+      const blocked = type === "command" && (def.async === true || def.asyncRewake === true);
+      const applies = (type === "command" || type === "http") && !ON_FAILURE_IGNORED.has(event) && !blocked;
+      if (def.failClosed === true && applies) out.onFailure = "block";
+    } else if (VALID[field.kind](def[field.key]) && (field.commandOnly !== true || type === "command")) {
+      out[field.key] = def[field.key];
+    }
+  }
+  return out;
+}
+
+/**
+ * Deliberate divergence from rulesync: only a leading `./` (optionally quoted) gets the project dir; script
+ * operands later in the command are left alone. A shell command gets `"$CLAUDE_PROJECT_DIR"/`; an exec-form
+ * hook (`args` is an array) gets `${CLAUDE_PROJECT_DIR}/` with the surrounding quotes stripped (D:53245-53266).
+ */
+function prefixProjectDir(command: string, def: Def): string {
+  const lead = /^(['"]?)\.\/(.*)$/s.exec(command);
+  if (lead === null) return command;
+  const relative = `${lead[1]}${lead[2]}`;
+  if (!Array.isArray(def.args)) return `"$CLAUDE_PROJECT_DIR"/${relative}`;
+  return `\${CLAUDE_PROJECT_DIR}/${relative.replace(/^(["'])(.*)\1$/, "$2").replace(/^["']/, "")}`;
+}
+
+/** Why Codex would refuse a handler, or undefined (`describeRejectedHandler`, D:56419-56429). */
+function codexRejects(hook: Json): boolean {
+  const { timeout } = hook;
+  if (timeout !== undefined && !(Number.isSafeInteger(timeout) && (timeout as number) >= 0)) return true;
+  if (hook.type !== "mcp_tool") return false;
+  return (
+    [hook.server, hook.tool].some((value) => typeof value !== "string" || value === "") || containsNull(hook.input)
+  );
+}
+
+function containsNull(value: unknown): boolean {
+  if (value === null) return true;
+  return typeof value === "object" && Object.values(value as object).some(containsNull);
+}
+
+/** Drops handlers Codex rejects, then emptied groups and events (`filterCodexHandlers`, D:56436-56462). */
+function filterCodexHandlers(hooks: Record<string, Group[]>): Record<string, Group[]> {
+  const out: Record<string, Group[]> = {};
+  for (const [event, groups] of Object.entries(hooks)) {
+    const kept = groups
+      .map((group) => ({ ...group, hooks: group.hooks.filter((hook) => !codexRejects(hook)) }))
+      .filter((group) => group.hooks.length > 0);
+    if (kept.length > 0) out[event] = kept;
+  }
+  return out;
+}
+
+/** The stock settings with `hooks` replaced in place (else appended) and `$schema` first when missing. */
+function claudeSettings(base: string, hooks: Json): Json {
+  const settings: Json = { ...(JSON.parse(base) as Json), hooks };
+  return "$schema" in settings ? settings : { $schema: CLAUDE_SCHEMA, ...settings };
+}
+
+/**
+ * Cursor's flat entries, no grouping (D:57912-57936): command and prompt handlers only, `type` only when the
+ * source has one, `model` only on prompt handlers; events left empty are dropped.
+ */
+function cursorHooks(config: Json): Json {
+  const out: Json = {};
+  for (const [event, defs] of effectiveEvents(config, "cursor", CURSOR_EVENTS)) {
+    const mapped = defs
+      .filter((def) => CURSOR_TYPES.has((def.type as string | undefined) ?? "command"))
+      .map((def) => {
+        const { type, command, timeout, loop_limit, matcher, prompt, model, failClosed } = def;
+        const entry = {
+          type,
+          command: typeof command === "string" ? expandHookCommand(command) : command,
+          timeout,
+          loop_limit,
+          matcher,
+          prompt,
+          model: type === "prompt" ? model : undefined,
+          failClosed,
+        };
+        // `loop_limit` alone is written when null.
+        return Object.fromEntries(
+          Object.entries(entry).filter(
+            ([key, value]) => value !== undefined && (value !== null || key === "loop_limit"),
+          ),
+        );
+      });
+    if (mapped.length > 0) out[nameOf(CURSOR_EVENTS, event)] = mapped;
+  }
+  return out;
+}

package/cli/sync/agents/rules.test.ts

@@ -0,0 +1,229 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { HOSTS, type Host } from "../../config.ts";
+import { readGoldens } from "../../../dev/capture-tree-goldens.ts";
+import { renderRules } from "./rules.ts";
+import { renderSubagents } from "./subagents.ts";
+import { type Doc, type Sources, loadSources } from "./sources.ts";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+const FIXTURES = path.join(ROOT, "cli", "sync", "fixtures");
+
+const isRulesPath = (rel: string) =>
+  rel === "AGENTS.md" ||
+  rel.startsWith(".agents/rules/") ||
+  rel.startsWith(".claude/rules/") ||
+  rel.startsWith(".grok/rules/");
+
+function fixtureSources(): Sources {
+  return loadSources({
+    stockRoot: path.join(FIXTURES, "consumer-stock"),
+    consumerRoot: path.join(FIXTURES, "consumer"),
+    packages: [],
+  }).sources;
+}
+
+function rule(file: string, data: Record<string, unknown>, body: string, dir = ".repo"): Doc {
+  return {
+    rel: `${dir}/rules/${file}`,
+    file,
+    origin: dir === "agents" ? "stock" : "repo",
+    scope: "",
+    data: { description: "d", ...data },
+    body,
+  };
+}
+
+function sourcesOf(rules: Doc[]): Sources {
+  return { rules, subagents: [], hooks: { rel: "agents/hooks.jsonc", value: {} } };
+}
+
+/** The text of every file `renderRules` plans for the root scope, or for `scope`. */
+function renderText(sources: Sources, hosts: readonly Host[], scope = ""): Map<string, string> {
+  return new Map([...renderRules(sources.rules, hosts, scope)].map(([rel, file]) => [rel, file.text]));
+}
+
+const BASE = rule("overview.md", {}, "Base body.", "agents");
+const SCOPED = rule("testing.md", { paths: ["src/**", "lib/**"] }, "Test body.");
+
+describe("renderRules", () => {
+  it("matches the consumer fixture goldens byte for byte, path set included", () => {
+    const goldens = new Map([...readGoldens()].filter(([rel]) => isRulesPath(rel)));
+    const out = renderText(fixtureSources(), HOSTS);
+    expect([...out.keys()].sort()).toEqual([...goldens.keys()].sort());
+    for (const [rel, text] of goldens) expect(out.get(rel), rel).toBe(text);
+  });
+
+  it("renders this repo's committed AGENTS.md from its stock alone", () => {
+    const out = renderText(loadSources({ stockRoot: ROOT, consumerRoot: null, packages: [] }).sources, HOSTS);
+    expect(out.get("AGENTS.md")).toBe(fs.readFileSync(path.join(ROOT, "AGENTS.md"), "utf8"));
+  });
+
+  it("emits nothing with no host on", () => {
+    expect(renderText(fixtureSources(), []).size).toBe(0);
+  });
+
+  it("folds pathless rules into AGENTS.md in source order and writes no file for them", () => {
+    const out = renderText(sourcesOf([BASE, rule("b.md", {}, "B."), rule("a.md", {}, "A.")]), HOSTS);
+    expect([...out.keys()]).toEqual(["AGENTS.md"]);
+    expect(out.get("AGENTS.md")).toBe("Base body.\n\nB.\n\nA.\n");
+  });
+
+  it.each([[["**/*"]], [["*"]], [[]]])("treats paths %j as pathless", (paths) => {
+    const out = renderText(sourcesOf([BASE, rule("p.md", { paths }, "P.")]), HOSTS);
+    expect([...out.keys()]).toEqual(["AGENTS.md"]);
+    expect(out.get("AGENTS.md")).toBe("Base body.\n\nP.\n");
+  });
+
+  it("renders a path rule for claude with a paths list and nothing else", () => {
+    const out = renderText(
+      sourcesOf([BASE, rule("testing.md", { paths: ["src/**", "lib/**"], overrides: "x" }, "Test body.")]),
+      ["claude"],
+    );
+    expect(out.get(".claude/rules/testing.md")).toBe("---\npaths:\n  - src/**\n  - lib/**\n---\nTest body.\n");
+    expect([...out.keys()].sort()).toEqual([".claude/rules/testing.md", "AGENTS.md"]);
+  });
+
+  it("renders a path rule for antigravity as a glob trigger", () => {
+    const out = renderText(sourcesOf([BASE, SCOPED]), ["antigravity"]);
+    expect(out.get(".agents/rules/testing.md")).toBe("---\ntrigger: glob\nglobs: src/**,lib/**\n---\nTest body.\n");
+    expect([...out.keys()].sort()).toEqual([".agents/rules/testing.md", "AGENTS.md"]);
+  });
+
+  it("keeps nested rule paths", () => {
+    const out = renderText(sourcesOf([BASE, rule("x/y.md", { paths: ["x/**"] }, "Y.")]), ["claude", "antigravity"]);
+    expect(out.has(".claude/rules/x/y.md")).toBe(true);
+    expect(out.has(".agents/rules/x/y.md")).toBe(true);
+  });
+
+  it.each<Host>(["codex", "grok", "cursor"])(
+    "lists a path rule in AGENTS.md when %s is on, without a rule file",
+    (host) => {
+      const out = renderText(sourcesOf([BASE, SCOPED]), [host]);
+      expect([...out.keys()]).toEqual(["AGENTS.md"]);
+      expect(out.get("AGENTS.md")).toBe(
+        "Base body.\n\n## Rules by path\n- `src/** lib/**`: read `.repo/rules/testing.md`\n",
+      );
+    },
+  );
+
+  it("points a stock path rule into the installed package", () => {
+    const stock = rule("style.md", { paths: ["**/*.ts"] }, "S.", "agents");
+    const out = renderText(sourcesOf([BASE, stock]), ["codex"]);
+    expect(out.get("AGENTS.md")).toContain(
+      "- `**/*.ts`: read `node_modules/@workerstack/repo/agents/rules/style.md`\n",
+    );
+  });
+
+  it("leaves the pointer list out when only claude or antigravity is on", () => {
+    for (const host of ["claude", "antigravity"] as const) {
+      expect(renderText(sourcesOf([BASE, SCOPED]), [host]).get("AGENTS.md")).toBe("Base body.\n");
+    }
+  });
+
+  it("leaves the pointer list out when no rule has paths", () => {
+    expect(renderText(sourcesOf([BASE]), ["codex"]).get("AGENTS.md")).toBe("Base body.\n");
+  });
+
+  it("writes no .grok/rules for any host set", () => {
+    expect([...renderText(sourcesOf([BASE, SCOPED]), HOSTS).keys()].filter((rel) => rel.startsWith(".grok/"))).toEqual(
+      [],
+    );
+  });
+
+  it("lists every path rule once, in source order", () => {
+    const out = renderText(sourcesOf([BASE, SCOPED, rule("b.md", { paths: ["b/**"] }, "B.")]), HOSTS);
+    const list = out.get("AGENTS.md")!.split("## Rules by path\n")[1]!;
+    expect(list).toBe("- `src/** lib/**`: read `.repo/rules/testing.md`\n- `b/**`: read `.repo/rules/b.md`\n");
+  });
+});
+
+describe("overrides in rendered output", () => {
+  it("is stripped from every host's subagent file", () => {
+    const scout: Doc = {
+      rel: ".repo/subagents/scout.md",
+      file: "scout.md",
+      origin: "repo",
+      scope: "",
+      data: { name: "scout", description: "Scout.", overrides: "scout" },
+      body: "Body.",
+    };
+    const out = renderSubagents({ ...sourcesOf([]), subagents: [scout] }, HOSTS);
+    expect(out.size).toBe(HOSTS.length);
+    for (const [rel, text] of out) expect(text, rel).not.toContain("overrides");
+  });
+});
+
+describe("renderRules for a package scope", () => {
+  const WEB = "packages/web";
+  const pkgRule = (file: string, data: Record<string, unknown>, body: string): Doc => ({
+    rel: `${WEB}/.repo/rules/${file}`,
+    file,
+    origin: "repo",
+    scope: WEB,
+    data: { description: "d", ...data },
+    body,
+  });
+  const POINTER = "Start at references/INDEX.md in this package.";
+  const COMPONENTS = pkgRule("components.md", {}, "Components live in src/components and use the ui kit.");
+  const API = pkgRule("api.md", { paths: ["src/api/**"] }, "Api body.");
+  const sources = sourcesOf([BASE, SCOPED, COMPONENTS, API]);
+
+  it("writes the package AGENTS.md: the pointer line, its pathless rules, then a pointer per path rule", () => {
+    const out = renderText(sources, ["codex"], WEB);
+    expect(out.get(`${WEB}/AGENTS.md`)).toBe(
+      `${POINTER}\n\nComponents live in src/components and use the ui kit.\n\n## Rules by path\n- \`packages/web/src/api/**\`: read \`packages/web/.repo/rules/api.md\`\n`,
+    );
+    expect([...out.keys()]).toEqual([`${WEB}/AGENTS.md`]);
+  });
+
+  it("leaves the pointer list out when no host that needs it is on, and the root AGENTS.md has no package rule", () => {
+    expect(renderText(sources, ["claude"], WEB).get(`${WEB}/AGENTS.md`)).toBe(
+      `${POINTER}\n\nComponents live in src/components and use the ui kit.\n`,
+    );
+    const root = renderText(sources, HOSTS, "");
+    for (const [rel, text] of root) expect(`${rel}\n${text}`, rel).not.toMatch(/Components live|packages\/web/);
+  });
+
+  it("writes CLAUDE.md with the pointer line alone, only when claude is on", () => {
+    expect(renderText(sources, ["claude"], WEB).get(`${WEB}/CLAUDE.md`)).toBe(`${POINTER}\n`);
+    expect(renderText(sources, ["codex", "antigravity", "grok", "cursor"], WEB).has(`${WEB}/CLAUDE.md`)).toBe(false);
+  });
+
+  it("renders every package rule for claude under its dir, a pathless one scoped to the whole package", () => {
+    const out = renderText(sources, ["claude"], WEB);
+    expect(out.get(".claude/rules/packages/web/components.md")).toBe(
+      "---\npaths:\n  - packages/web/**\n---\nComponents live in src/components and use the ui kit.\n",
+    );
+    expect(out.get(".claude/rules/packages/web/api.md")).toBe(
+      "---\npaths:\n  - packages/web/src/api/**\n---\nApi body.\n",
+    );
+  });
+
+  it("renders every package rule for antigravity under its dir as a glob trigger", () => {
+    const out = renderText(pkgSources(), ["antigravity"], WEB);
+    expect(out.get(".agents/rules/packages/web/components.md")).toBe(
+      "---\ntrigger: glob\nglobs: packages/web/**\n---\nComponents live in src/components and use the ui kit.\n",
+    );
+    expect(out.get(".agents/rules/packages/web/multi.md")).toBe(
+      "---\ntrigger: glob\nglobs: packages/web/a/**,packages/web/b/**\n---\nM.\n",
+    );
+    expect(out.has(`${WEB}/CLAUDE.md`)).toBe(false);
+  });
+
+  function pkgSources(): Sources {
+    return sourcesOf([COMPONENTS, pkgRule("multi.md", { paths: ["a/**", "b/**"] }, "M.")]);
+  }
+
+  it("names the rule file's source, and renders a package without rules as the pointer line", () => {
+    const rendered = renderRules(sources.rules, ["claude"], WEB);
+    expect(rendered.get(".claude/rules/packages/web/api.md")?.source).toBe(`${WEB}/.repo/rules/api.md`);
+    expect(renderText(sources, ["claude"], "packages/empty").get("packages/empty/AGENTS.md")).toBe(`${POINTER}\n`);
+  });
+
+  it("emits nothing with no host on", () => {
+    expect(renderRules(sources.rules, [], WEB).size).toBe(0);
+  });
+});