@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/sync.test.ts

@@ -0,0 +1,1495 @@
+import { BASE_CONFIG } from "./fixtures/base-config.ts";
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { CONFIG_FILE } from "./config.ts";
+import { aliasOf, linkText, removeAlias } from "../dev/test-paths.ts";
+import { gitFiles, type PostPass } from "./sync/git-files.ts";
+import { MANIFEST_REL, renderManifest } from "./sync/manifest.ts";
+import { standards } from "./sync/standards.ts";
+import { fileURLToPath } from "node:url";
+import { bunfig, index, type Generator, type Output, type SyncContext } from "./sync/outputs.ts";
+import { planSync, runSync, type SyncDeps } from "./sync.ts";
+import type { FormatEntry } from "./sync/validate.ts";
+import { writeOutput } from "./sync/write.ts";
+
+const NO_AGENTS = { hosts: [], skills: [] };
+
+const BUNFIG = '# Generated by repo sync. Do not edit.\n[install]\nlinker = "hoisted"\nauto = "disable"\n';
+const GITIGNORE =
+  "# >>> @workerstack/repo (generated by repo sync)\n.tmp/\n.worktrees/\n.repo/tmp/\ncoverage/\nnode_modules/\n# <<< @workerstack/repo\n";
+const GITATTRIBUTES =
+  "# >>> @workerstack/repo (generated by repo sync)\n* text=auto eol=lf\nbunfig.toml linguist-generated\n# <<< @workerstack/repo\n";
+const SETTINGS = '{\n  "files.readonlyInclude": {\n    "bunfig.toml": true\n  }\n}\n';
+const INDEX =
+  "# References\n" +
+  "\n" +
+  "<!-- repo:packages -->\n" +
+  "- [@acme/api](../packages/api/references/INDEX.md): API worker\n" +
+  "<!-- /repo:packages -->\n" +
+  "\n" +
+  "<!-- repo:stack -->\n" +
+  "- [@workerstack/repo](../node_modules/@workerstack/repo/references/INDEX.md)\n" +
+  "<!-- /repo:stack -->\n";
+const OUTPUTS = [
+  "bunfig.toml",
+  "references/INDEX.md",
+  "packages/api/references/INDEX.md",
+  ".gitignore",
+  ".gitattributes",
+  ".vscode/settings.json",
+];
+const OLD = new Date("2020-01-01T00:00:00Z");
+
+const temps: string[] = [];
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  for (const dir of temps.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function tempDir(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-sync-"));
+  temps.push(dir);
+  return dir;
+}
+
+function write(root: string, rel: string, text: string): void {
+  const file = path.join(root, rel);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+}
+
+function read(root: string, rel: string): string {
+  return fs.readFileSync(path.join(root, rel), "utf8");
+}
+
+/** Every file under `root`, root-relative, with its bytes. */
+function snapshot(root: string): Record<string, string> {
+  const files: Record<string, string> = {};
+  for (const rel of fs.readdirSync(root, { recursive: true, encoding: "utf8" }).sort()) {
+    const file = path.join(root, rel);
+    if (fs.statSync(file).isFile()) files[rel.replaceAll("\\", "/")] = fs.readFileSync(file, "latin1");
+  }
+  return files;
+}
+
+/** A temp workspace repo with the docs pack, one package and a `@workerstack/repo` dependency. */
+function fixture(config = 'export default { packs: ["agents", "docs"], agents: { hosts: ["claude"] } }\n'): string {
+  const root = tempDir();
+  write(root, CONFIG_FILE, config);
+  write(
+    root,
+    "package.json",
+    JSON.stringify({ name: "fixture", workspaces: ["packages/*"], devDependencies: { "@workerstack/repo": "^1.0.0" } }),
+  );
+  write(root, "packages/api/package.json", JSON.stringify({ name: "@acme/api" }));
+  write(root, "packages/api/references/INDEX.md", "# API worker\n");
+  return root;
+}
+
+/** Runs `repo sync` in `cwd`, capturing what it prints. */
+async function sync(cwd: string, ...args: string[]) {
+  return syncWith(cwd, { generators: [bunfig, index], post: [gitFiles] }, ...args);
+}
+
+/** No post-passes, so a test with its own generators sees only their outputs. */
+const noPost: readonly PostPass[] = [];
+
+async function syncWith(cwd: string, deps: SyncDeps, ...args: string[]) {
+  const out: string[] = [];
+  const err: string[] = [];
+  const code = await runSync(
+    args,
+    { cwd, stdout: (s) => out.push(s), stderr: (s) => err.push(s) },
+    { post: noPost, ...deps },
+  );
+  return { code, stdout: out.join(""), stderr: err.join("") };
+}
+
+function mtimes(root: string): number[] {
+  return OUTPUTS.map((rel) => fs.statSync(path.join(root, rel)).mtimeMs);
+}
+
+function age(root: string): void {
+  for (const rel of OUTPUTS) fs.utimesSync(path.join(root, rel), OLD, OLD);
+}
+
+describe("runSync", () => {
+  it("writes every output under the root on the first run, then reports up to date without touching them", async () => {
+    const root = fixture();
+
+    expect(await sync(root)).toEqual({
+      code: 0,
+      stdout:
+        "repo sync: wrote bunfig.toml, references/INDEX.md, packages/api/references/INDEX.md, .gitignore, .gitattributes, .vscode/settings.json\n",
+      stderr: "",
+    });
+    expect(read(root, "bunfig.toml")).toBe(BUNFIG);
+    expect(read(root, ".gitignore")).toBe(GITIGNORE);
+    expect(read(root, ".gitattributes")).toBe(GITATTRIBUTES);
+    expect(read(root, ".vscode/settings.json")).toBe(SETTINGS);
+    expect(read(root, "references/INDEX.md")).toBe(INDEX);
+
+    age(root);
+    const before = mtimes(root);
+    expect(await sync(root)).toEqual({ code: 0, stdout: "repo sync: up to date\n", stderr: "" });
+    expect(mtimes(root)).toEqual(before);
+  });
+
+  it("refuses a config without the agents pack in this repo, whose trees are the stock source, and touches nothing", async () => {
+    const root = fixture('export default { packs: ["docs"] }\n');
+    write(root, "package.json", JSON.stringify({ name: "@workerstack/repo" }));
+    write(root, ".claude/skills/ask/SKILL.md", "stock\n");
+    expect(await sync(root)).toEqual({
+      code: 1,
+      stdout: "",
+      stderr:
+        'repo sync: workerstack.config.ts: this repo ships the agent trees as its stock source; keep "agents" in packs\nrepo sync: nothing written\n',
+    });
+    expect(read(root, ".claude/skills/ask/SKILL.md")).toBe("stock\n");
+    expect(fs.existsSync(path.join(root, "bunfig.toml"))).toBe(false);
+  });
+
+  it("finds the root from a nested cwd and writes there", async () => {
+    const root = fixture();
+    expect((await sync(path.join(root, "packages", "api"))).code).toBe(0);
+    expect(read(root, "bunfig.toml")).toBe(BUNFIG);
+    expect(fs.existsSync(path.join(root, "packages", "api", "bunfig.toml"))).toBe(false);
+  });
+
+  it("rewrites only the files that drifted and leaves no temp files", async () => {
+    const root = fixture();
+    await sync(root);
+    write(root, "bunfig.toml", `${BUNFIG}x\n`);
+    age(root);
+    const [, ...kept] = mtimes(root);
+
+    expect(await sync(root)).toEqual({ code: 0, stdout: "repo sync: wrote bunfig.toml\n", stderr: "" });
+    expect(read(root, "bunfig.toml")).toBe(BUNFIG);
+    expect(mtimes(root).slice(1)).toEqual(kept);
+    expect(fs.readdirSync(root).filter((name) => name.includes(".tmp"))).toEqual([]);
+  });
+
+  it("keeps the hand-written text around the managed parts", async () => {
+    const root = fixture();
+    write(root, ".gitignore", "node_modules/\n.tmp/\n");
+    write(root, "references/INDEX.md", "# Docs\n\nHand-written.\n");
+    await sync(root);
+    expect(read(root, ".gitignore")).toBe(`node_modules/\n.tmp/\n\n${GITIGNORE}`);
+    expect(read(root, "references/INDEX.md")).toBe(`# Docs\n\nHand-written.\n${INDEX.slice("# References\n".length)}`);
+  });
+
+  it("treats a file whose bytes differ only in line endings as drifted", async () => {
+    const root = fixture();
+    await sync(root);
+    write(root, "bunfig.toml", BUNFIG.replaceAll("\n", "\r\n"));
+    expect(await sync(root, "--check")).toEqual({
+      code: 1,
+      stdout: "",
+      stderr: "repo sync: bunfig.toml is out of date; run `bun repo sync`\n",
+    });
+  });
+
+  it("--check reports up to date and exits 0 when nothing drifted", async () => {
+    const root = fixture();
+    await sync(root);
+    expect(await sync(root, "--check")).toEqual({ code: 0, stdout: "repo sync: up to date\n", stderr: "" });
+  });
+
+  it("--check names every stale file, exits 1 and writes nothing", async () => {
+    const root = fixture();
+    write(root, "bunfig.toml", `${BUNFIG}x\n`);
+    const before = snapshot(root);
+
+    expect(await sync(root, "--check")).toEqual({
+      code: 1,
+      stdout: "",
+      stderr:
+        "repo sync: bunfig.toml is out of date; run `bun repo sync`\n" +
+        "repo sync: references/INDEX.md is out of date; run `bun repo sync`\n" +
+        "repo sync: packages/api/references/INDEX.md is out of date; run `bun repo sync`\n" +
+        "repo sync: .gitignore is out of date; run `bun repo sync`\n" +
+        "repo sync: .gitattributes is out of date; run `bun repo sync`\n" +
+        "repo sync: .vscode/settings.json is out of date; run `bun repo sync`\n",
+    });
+    expect(snapshot(root)).toEqual(before);
+  });
+
+  it("a config error exits 1 and leaves every file byte-identical", async () => {
+    const root = fixture("export default { pakcs: [] }\n");
+    write(root, "bunfig.toml", `${BUNFIG}x\n`);
+    write(root, ".gitignore", "node_modules/\n");
+    const before = snapshot(root);
+
+    expect(await sync(root)).toEqual({
+      code: 1,
+      stdout: "",
+      stderr: 'repo sync: workerstack.config.ts: unknown key "pakcs"\nrepo sync: nothing written\n',
+    });
+    expect(snapshot(root)).toEqual(before);
+  });
+
+  it("a generator error exits 1 and writes none of the valid outputs", async () => {
+    const root = fixture();
+    write(root, "bunfig.toml", `${BUNFIG}x\n`);
+    write(root, "references/INDEX.md", "# References\n\n<!-- repo:stack -->\n");
+    const before = snapshot(root);
+
+    expect(await sync(root)).toEqual({
+      code: 1,
+      stdout: "",
+      stderr:
+        'repo sync: references/INDEX.md: "<!-- repo:stack -->" has no closing "<!-- /repo:stack -->"\nrepo sync: nothing written\n',
+    });
+    expect(snapshot(root)).toEqual(before);
+  });
+
+  it("a workspace error exits 1 and writes nothing", async () => {
+    const root = fixture();
+    write(root, "packages/api/package.json", "{");
+    const before = snapshot(root);
+
+    const result = await sync(root);
+    expect(result.code).toBe(1);
+    expect(result.stdout).toBe("");
+    expect(result.stderr).toMatch(
+      /^repo sync: packages\/api\/package\.json: not valid JSON: .+\nrepo sync: nothing written\n$/,
+    );
+    expect(snapshot(root)).toEqual(before);
+  });
+
+  it("reports a file it cannot read instead of treating it as missing", async () => {
+    const root = fixture();
+    write(root, "references/INDEX.md/stray.txt", "a directory where the index belongs\n");
+    const before = snapshot(root);
+
+    const result = await sync(root);
+    expect(result.code).toBe(1);
+    expect(result.stdout).toBe("");
+    expect(result.stderr).toMatch(
+      /^repo sync: references\/INDEX\.md: cannot read: EISDIR\b.*\nrepo sync: nothing written\n$/,
+    );
+    expect(snapshot(root)).toEqual(before);
+  });
+
+  it("reports a failed write, removes its temp file and exits 1", async () => {
+    const root = fixture();
+    const rename = vi.spyOn(fs, "renameSync").mockImplementationOnce(() => {
+      throw Object.assign(new Error("EACCES: permission denied, rename"), { code: "EACCES" });
+    });
+
+    expect(await sync(root)).toEqual({
+      code: 1,
+      stdout: "",
+      stderr:
+        "repo sync: bunfig.toml: cannot write: EACCES: permission denied, rename; restored 0 outputs, nothing changed\n",
+    });
+    expect(rename).toHaveBeenCalledOnce();
+    expect(fs.readdirSync(root).sort()).toEqual([CONFIG_FILE, "package.json", "packages"].sort());
+  });
+
+  it("--postinstall prints an error and exits 0", async () => {
+    const root = fixture("export default { pakcs: [] }\n");
+    expect(await sync(root, "--postinstall")).toEqual({
+      code: 0,
+      stdout: "",
+      stderr: 'repo sync: workerstack.config.ts: unknown key "pakcs"\nrepo sync: nothing written\n',
+    });
+    expect(fs.existsSync(path.join(root, "bunfig.toml"))).toBe(false);
+  });
+
+  it("--postinstall writes like a plain run when there is no error", async () => {
+    const root = fixture();
+    expect(await sync(root, "--postinstall")).toEqual({
+      code: 0,
+      stdout:
+        "repo sync: wrote bunfig.toml, references/INDEX.md, packages/api/references/INDEX.md, .gitignore, .gitattributes, .vscode/settings.json\n",
+      stderr: "",
+    });
+  });
+
+  it("says to run repo init when no config exists in cwd or any parent", async () => {
+    const cwd = tempDir();
+    expect(await sync(cwd)).toEqual({
+      code: 1,
+      stdout: "",
+      stderr: `repo sync: no workerstack.config.ts in ${cwd} or any parent; run \`bun repo init\`\n`,
+    });
+    expect(fs.readdirSync(cwd)).toEqual([]);
+    expect((await sync(cwd, "--postinstall")).code).toBe(0);
+  });
+
+  it("produces identical bytes across runs and roots", async () => {
+    const first = fixture();
+    const second = fixture();
+    await sync(first);
+    const once = snapshot(first);
+    await sync(first);
+    await sync(second);
+    expect(snapshot(first)).toEqual(once);
+    expect(snapshot(second)).toEqual(once);
+  });
+
+  it.each([
+    [["--force"], "repo sync: unknown flag --force; use --check or --postinstall\n"],
+    [["extra"], "repo sync: unknown flag extra; use --check or --postinstall\n"],
+    [["--check", "--postinstall"], "repo sync: use --check or --postinstall, not both\n"],
+  ])("%j is a usage error that exits 1 and writes nothing", async (args, stderr) => {
+    const root = fixture();
+    const before = snapshot(root);
+    expect(await sync(root, ...args)).toEqual({ code: 1, stdout: "", stderr });
+    expect(snapshot(root)).toEqual(before);
+  });
+});
+
+describe("planSync", () => {
+  it("runs every generator in order and concatenates outputs and errors", () => {
+    const files: Record<string, string> = {
+      "bunfig.toml": "[test]\n",
+      ".gitignore": "# >>> @workerstack/repo\n",
+    };
+    const plan = planSync({
+      root: "/repo",
+      config: { packs: ["docs"], agents: NO_AGENTS, ...BASE_CONFIG },
+      workspace: { root: "/repo", manifest: {}, packages: [] },
+      read: (rel) => files[rel] ?? null,
+    });
+    // The git files pass runs after the generators, over what they produced, even when one of them failed.
+    expect(plan.outputs.map((output) => output.path)).toEqual([
+      "references/INDEX.md",
+      ".gitattributes",
+      ".vscode/settings.json",
+    ]);
+    expect(plan.errors).toEqual([
+      "bunfig.toml is hand-written; delete it so repo sync can own it",
+      '.gitignore: "# >>> @workerstack/repo" has no closing "# <<< @workerstack/repo"',
+    ]);
+  });
+
+  it("runs the given post-passes in order, each over the outputs planned before it, and reports one that throws", () => {
+    const ctx: SyncContext = {
+      root: "/repo",
+      config: { packs: ["docs"], agents: NO_AGENTS, ...BASE_CONFIG },
+      workspace: { root: "/repo", manifest: {}, packages: [] },
+      read: () => null,
+    };
+    const ok: Generator = () => ({ outputs: [file("a.txt")], errors: [] });
+    const seen: string[][] = [];
+    const adding =
+      (rel: string): PostPass =>
+      (_ctx, outputs) => {
+        seen.push(outputs.map((output) => output.path));
+        return { outputs: [file(rel)], errors: [] };
+      };
+    expect(planSync(ctx, [ok], [adding("b.txt"), adding("c.txt")]).outputs.map((output) => output.path)).toEqual([
+      "a.txt",
+      "b.txt",
+      "c.txt",
+    ]);
+    expect(seen).toEqual([["a.txt"], ["a.txt", "b.txt"]]);
+    const boom = () => {
+      throw new Error("post failed");
+    };
+    expect(planSync(ctx, [ok], [boom])).toEqual({ outputs: [file("a.txt")], errors: ["post failed"] });
+  });
+
+  it("reports a generator that throws as an error and keeps running the others", () => {
+    const boom: Generator = () => {
+      throw new Error("EACCES: cannot read x");
+    };
+    const ok: Generator = () => ({ outputs: [file("a.txt")], errors: [] });
+    const plan = planSync(
+      {
+        root: "/repo",
+        config: { packs: ["docs"], agents: NO_AGENTS, ...BASE_CONFIG },
+        workspace: { root: "/repo", manifest: {}, packages: [] },
+        read: () => null,
+      },
+      [boom, ok],
+      noPost,
+    );
+    expect(plan).toEqual({ outputs: [file("a.txt")], errors: ["EACCES: cannot read x"] });
+  });
+
+  it("refuses two outputs with one path, naming the generators that planned them", () => {
+    const first: Generator = () => ({ outputs: [file("a.txt"), file("b.txt")], errors: [] });
+    const second: Generator = () => ({ outputs: [file("a.txt", "other\n")], errors: [] });
+    const plan = planSync(
+      {
+        root: "/repo",
+        config: { packs: ["docs"], agents: NO_AGENTS, ...BASE_CONFIG },
+        workspace: { root: "/repo", manifest: {}, packages: [] },
+        read: () => null,
+      },
+      [first, second],
+      noPost,
+    );
+    expect(plan.errors).toEqual(["a.txt: planned by first and second; rename one"]);
+  });
+
+  it("plans every output for a clean repo", () => {
+    const plan = planSync({
+      root: "/repo",
+      config: { packs: ["docs"], agents: NO_AGENTS, ...BASE_CONFIG },
+      workspace: { root: "/repo", manifest: {}, packages: [] },
+      read: () => null,
+    });
+    expect(plan.errors).toEqual([]);
+    expect(plan.outputs.map((output) => output.path)).toEqual(OUTPUTS.filter((rel) => !rel.startsWith("packages/")));
+  });
+});
+
+const file = (path: string, content = `${path}\n`): Output => ({
+  kind: "file",
+  path,
+  content,
+  tracked: false,
+  managed: "whole",
+});
+const link = (path: string, target: string): Output => ({
+  kind: "link",
+  path,
+  target,
+  tracked: false,
+  managed: "whole",
+});
+/** A generator that returns exactly `outputs`, replacing the real ones. */
+const generating = (...outputs: Output[]): Generator[] => [() => ({ outputs, errors: [] })];
+/** The same, with every path accepted as text, so these tests need not name registered formats. */
+const only = (...outputs: Output[]): { generators: Generator[]; formats: FormatEntry[] } => ({
+  generators: generating(...outputs),
+  formats: [{ match: () => true, format: "text" }],
+});
+
+describe("a config rewritten between two runs in one process", () => {
+  it("is read again, so the second run converges on the new config", async () => {
+    const root = fixture('export default { packs: ["agents"], agents: { hosts: ["claude"] } }\n');
+    const hosts: Generator = (ctx) => ({ outputs: [file("hosts.txt", ctx.config.agents.hosts.join(","))], errors: [] });
+    const deps = { generators: [hosts], formats: [{ match: () => true, format: "text" as const }] };
+    expect((await syncWith(root, deps)).code).toBe(0);
+    expect(read(root, "hosts.txt")).toBe("claude");
+
+    write(root, CONFIG_FILE, 'export default { packs: ["agents"], agents: { hosts: ["codex"] } }\n');
+    expect(await syncWith(root, deps, "--check")).toMatchObject({
+      code: 1,
+      stderr: expect.stringContaining("hosts.txt is out of date"),
+    });
+    expect((await syncWith(root, deps)).code).toBe(0);
+    expect(read(root, "hosts.txt")).toBe("codex");
+    expect(await syncWith(root, deps, "--check")).toEqual({ code: 0, stdout: "repo sync: up to date\n", stderr: "" });
+  });
+});
+
+const manifestPaths = (root: string): string[] => (JSON.parse(read(root, MANIFEST_REL)) as { paths: string[] }).paths;
+const exists = (root: string, rel: string): boolean => {
+  try {
+    fs.lstatSync(path.join(root, rel));
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+describe("runSync link outputs", () => {
+  it("creates a link, keeps it while current and replaces it when it points elsewhere", async () => {
+    const root = fixture();
+    fs.mkdirSync(path.join(root, "store/a"), { recursive: true });
+    fs.mkdirSync(path.join(root, "store/b"), { recursive: true });
+    const symlink = vi.spyOn(fs, "symlinkSync");
+
+    const deps = only(link("tree/skill", "../store/a"));
+    expect(await syncWith(root, deps)).toEqual({ code: 0, stdout: "repo sync: wrote tree/skill\n", stderr: "" });
+    expect(linkText(path.join(root, "tree/skill"))).toBe("../store/a");
+    expect(symlink).toHaveBeenCalledTimes(1);
+
+    expect(await syncWith(root, deps)).toEqual({ code: 0, stdout: "repo sync: up to date\n", stderr: "" });
+    expect(symlink).toHaveBeenCalledTimes(1);
+
+    expect((await syncWith(root, only(link("tree/skill", "../store/b")))).code).toBe(0);
+    expect(linkText(path.join(root, "tree/skill"))).toBe("../store/b");
+    expect(symlink).toHaveBeenCalledTimes(2);
+  });
+
+  it("keeps a link whose text is exactly the planned target", async () => {
+    const root = fixture();
+    fs.mkdirSync(path.join(root, "store"));
+    fs.mkdirSync(path.join(root, "tree"));
+    // A junction needs no privilege on win32 and is a plain symlink elsewhere, so the posix check runs on every OS.
+    fs.symlinkSync(path.join(root, "store"), path.join(root, "tree/skill"), "junction");
+    const text = fs.readlinkSync(path.join(root, "tree/skill"));
+    await syncWith(root, { ...only(link("tree/skill", text)), platform: "linux" });
+    const symlink = vi.spyOn(fs, "symlinkSync");
+    expect(await syncWith(root, { ...only(link("tree/skill", text)), platform: "linux" })).toEqual({
+      code: 0,
+      stdout: "repo sync: up to date\n",
+      stderr: "",
+    });
+    expect(symlink).not.toHaveBeenCalled();
+  });
+
+  it("replaces a real file that stands where a link belongs", async () => {
+    const root = fixture();
+    fs.mkdirSync(path.join(root, "store"));
+    write(root, "tree/skill", "old\n");
+    expect((await syncWith(root, only(link("tree/skill", "../store")))).code).toBe(0);
+    expect(fs.lstatSync(path.join(root, "tree/skill")).isSymbolicLink()).toBe(true);
+  });
+
+  it("makes a junction with an absolute target on win32", async () => {
+    const root = fixture();
+    fs.mkdirSync(path.join(root, "store"));
+    const symlink = vi.spyOn(fs, "symlinkSync");
+    await syncWith(root, { ...only(link("tree/skill", "../store")), platform: "win32" });
+    expect(symlink).toHaveBeenCalledWith(path.join(root, "store"), path.join(root, "tree/skill"), "junction");
+  });
+
+  // A win32 junction holds an absolute target, so there a link is matched by the path it names (the next test).
+  it.skipIf(process.platform === "win32")(
+    "rewrites a link whose text differs, even when it resolves to the same directory",
+    async () => {
+      const root = fixture();
+      const store = path.join(root, "store");
+      fs.mkdirSync(store);
+      const alias = aliasOf(store);
+      try {
+        expect((await syncWith(root, only(link("tree/skill", alias)))).code).toBe(0);
+        expect(await syncWith(root, only(link("tree/skill", store)))).toEqual({
+          code: 0,
+          stdout: "repo sync: wrote tree/skill\n",
+          stderr: "",
+        });
+        expect(fs.readlinkSync(path.join(root, "tree/skill"))).toBe(store);
+      } finally {
+        removeAlias(alias);
+      }
+    },
+  );
+
+  it("on win32 treats a target whose parent dirs are spelled another way as the same directory", async () => {
+    const root = fixture();
+    const store = path.join(root, "store");
+    fs.mkdirSync(store);
+    const alias = aliasOf(root);
+    try {
+      expect(
+        (await syncWith(root, { ...only(link("tree/skill", path.join(alias, "store"))), platform: "win32" })).code,
+      ).toBe(0);
+      const symlink = vi.spyOn(fs, "symlinkSync");
+      expect(await syncWith(root, { ...only(link("tree/skill", store)), platform: "win32" })).toEqual({
+        code: 0,
+        stdout: "repo sync: up to date\n",
+        stderr: "",
+      });
+      expect(symlink).not.toHaveBeenCalled();
+    } finally {
+      removeAlias(alias);
+    }
+  });
+
+  // A posix symlink on win32 needs a privilege the junction does not, so win32 runs only its own platform.
+  const platforms = process.platform === "win32" ? (["win32"] as const) : (["linux", "win32"] as const);
+  it.each(platforms)(
+    "on %s rewrites a link that reaches the target only through another generated link, so pruning that link leaves none dangling",
+    async (platform) => {
+      const root = fixture();
+      fs.mkdirSync(path.join(root, "store/x"), { recursive: true });
+      const through = [link(".agents/skills/x", "../../store/x"), link(".claude/skills/x", "../../.agents/skills/x")];
+      expect((await syncWith(root, { generators: [() => ({ outputs: through, errors: [] })], platform })).code).toBe(0);
+
+      const direct = await syncWith(root, { ...only(link(".claude/skills/x", "../../store/x")), platform });
+      expect(direct.code).toBe(0);
+      expect(direct.stdout).toBe("repo sync: wrote .claude/skills/x; removed .agents/skills/x\n");
+      expect(linkText(path.join(root, ".claude/skills/x"))).toBe("../../store/x");
+      expect(fs.existsSync(path.join(root, ".claude/skills/x"))).toBe(true);
+      expect(exists(root, ".agents")).toBe(false);
+    },
+  );
+
+  it("reports a failed link and exits 1", async () => {
+    const root = fixture();
+    fs.mkdirSync(path.join(root, "store"));
+    vi.spyOn(fs, "symlinkSync").mockImplementationOnce(() => {
+      throw new Error("EPERM: operation not permitted, symlink");
+    });
+    // Injected, so the posix link call runs on win32 too; the mock keeps it from needing the symlink privilege.
+    expect(await syncWith(root, { ...only(link("tree/skill", "../store")), platform: "linux" })).toEqual({
+      code: 1,
+      stdout: "",
+      stderr:
+        "repo sync: tree/skill: cannot write: EPERM: operation not permitted, symlink; restored 0 outputs, nothing changed\n",
+    });
+  });
+});
+
+describe("runSync file writes", () => {
+  it("reports a failed write even when its temp file cannot be removed", async () => {
+    const root = fixture();
+    vi.spyOn(fs, "renameSync").mockImplementationOnce(() => {
+      throw new Error("EPERM: operation not permitted, rename");
+    });
+    vi.spyOn(fs, "rmSync").mockImplementationOnce(() => {
+      throw new Error("EBUSY: resource busy");
+    });
+    expect(await syncWith(root, only(file("a.txt")))).toEqual({
+      code: 1,
+      stdout: "",
+      stderr:
+        "repo sync: a.txt: cannot write: EPERM: operation not permitted, rename; restored 0 outputs, nothing changed\n",
+    });
+  });
+});
+
+describe("runSync manifest and prune", () => {
+  it("removes a path the last run wrote and no output names now, with its empty parent dirs", async () => {
+    const root = fixture();
+    fs.mkdirSync(path.join(root, "store"));
+    await syncWith(
+      root,
+      only(file("keep.txt"), file("gone.txt"), file("deep/er/file.txt"), link("links/skill", "../store")),
+    );
+    expect(manifestPaths(root)).toEqual(["deep/er/file.txt", "gone.txt", "keep.txt", "links/skill"]);
+    write(root, "deep/other.txt", "mine\n");
+    write(root, "unlisted.txt", "mine\n");
+    write(root, "unlisted/dir/a.txt", "mine\n");
+
+    expect(await syncWith(root, only(file("keep.txt")))).toEqual({
+      code: 0,
+      stdout: "repo sync: removed deep/er/file.txt, gone.txt, links/skill\n",
+      stderr: "",
+    });
+    expect(exists(root, "gone.txt")).toBe(false);
+    expect(exists(root, "links/skill")).toBe(false);
+    expect(exists(root, "links")).toBe(false);
+    expect(exists(root, "deep/er")).toBe(false);
+    expect(read(root, "deep/other.txt")).toBe("mine\n");
+    expect(read(root, "unlisted.txt")).toBe("mine\n");
+    expect(read(root, "unlisted/dir/a.txt")).toBe("mine\n");
+    expect(fs.existsSync(path.join(root, "store"))).toBe(true);
+    expect(manifestPaths(root)).toEqual(["keep.txt"]);
+  });
+
+  it("reports a path it cannot remove, exits 1 and keeps the old manifest", async () => {
+    const root = fixture();
+    await syncWith(root, only(file("a.txt"), file("b.txt")));
+    vi.spyOn(fs, "rmSync").mockImplementationOnce(() => {
+      throw new Error("EBUSY: resource busy");
+    });
+    expect(await syncWith(root, only(file("a.txt")))).toEqual({
+      code: 1,
+      stdout: "",
+      stderr: "repo sync: b.txt: cannot remove: EBUSY: resource busy; restored 0 outputs, nothing changed\n",
+    });
+    expect(manifestPaths(root)).toEqual(["a.txt", "b.txt"]);
+  });
+
+  it("reports a manifest it cannot write", async () => {
+    const root = fixture();
+    write(root, ".repo", "not a directory\n");
+    expect(await syncWith(root, only())).toMatchObject({ code: 1, stdout: "" });
+  });
+
+  it("never removes a path that is not in the manifest", async () => {
+    const root = fixture();
+    write(root, "stale.txt", "mine\n");
+    await syncWith(root, only(file("a.txt")));
+    expect(read(root, "stale.txt")).toBe("mine\n");
+  });
+
+  it("skips a manifest path that is already gone and a real directory standing in its place", async () => {
+    const root = fixture();
+    write(root, MANIFEST_REL, JSON.stringify({ version: 1, paths: ["missing.txt", "adir"] }));
+    write(root, "adir/inner.txt", "mine\n");
+    expect(await syncWith(root, only(file("a.txt")))).toEqual({
+      code: 0,
+      stdout: "repo sync: wrote a.txt\n",
+      stderr: "",
+    });
+    expect(read(root, "adir/inner.txt")).toBe("mine\n");
+  });
+
+  it("reads a missing, invalid or foreign manifest as empty", async () => {
+    for (const text of ["{", "[]", "null", '{"version":2,"paths":[]}', '{"version":1,"paths":[1]}', '{"version":1}']) {
+      const root = fixture();
+      write(root, MANIFEST_REL, text);
+      write(root, "old.txt", "mine\n");
+      expect((await syncWith(root, only(file("a.txt")))).code).toBe(0);
+      expect(read(root, "old.txt")).toBe("mine\n");
+      expect(manifestPaths(root)).toEqual(["a.txt"]);
+    }
+  });
+
+  it("writes the manifest after every output and prune, and not at all when a write fails", async () => {
+    const root = fixture();
+    const order: string[] = [];
+    const deps = {
+      ...only(file("a.txt"), file("b.txt")),
+      writeOutput: (r: string, output: Output, platform: NodeJS.Platform) => {
+        order.push(`${output.path}:${exists(root, MANIFEST_REL)}`);
+        return writeOutput(r, output, platform);
+      },
+    };
+    await syncWith(root, deps);
+    expect(order).toEqual(["a.txt:false", "b.txt:false"]);
+    expect(exists(root, MANIFEST_REL)).toBe(true);
+
+    const fresh = fixture();
+    const failing = { ...only(file("a.txt")), writeOutput: () => "disk full" };
+    expect((await syncWith(fresh, failing)).code).toBe(1);
+    expect(exists(fresh, MANIFEST_REL)).toBe(false);
+  });
+
+  it("restores every earlier output when a later write fails, and converges on the next run", async () => {
+    const root = fixture();
+    await syncWith(root, only(file("old.txt")));
+    write(root, "a.txt", "mine, drifted\n");
+    const before = snapshot(root);
+    const next = only(file("a.txt"), file("b.txt"), file("c/d.txt"));
+    let calls = 0;
+    const crashing = {
+      ...next,
+      writeOutput: (r: string, output: Output, platform: NodeJS.Platform) =>
+        ++calls === 3 ? "EACCES: permission denied" : writeOutput(r, output, platform),
+    };
+    expect(await syncWith(root, crashing)).toEqual({
+      code: 1,
+      stdout: "",
+      stderr: "repo sync: c/d.txt: cannot write: EACCES: permission denied; restored 2 outputs, nothing changed\n",
+    });
+    expect(snapshot(root)).toEqual(before);
+    expect(exists(root, "c")).toBe(false);
+    expect(manifestPaths(root)).toEqual(["old.txt"]);
+
+    expect(await syncWith(root, next)).toEqual({
+      code: 0,
+      stdout: "repo sync: wrote a.txt, b.txt, c/d.txt; removed old.txt\n",
+      stderr: "",
+    });
+    expect(exists(root, "old.txt")).toBe(false);
+    expect(manifestPaths(root)).toEqual(["a.txt", "b.txt", "c/d.txt"]);
+    expect(await syncWith(root, next)).toEqual({ code: 0, stdout: "repo sync: up to date\n", stderr: "" });
+  });
+
+  it("matches a manifest's backslash and absolute spellings to outputs and never prunes a foreign path", async () => {
+    const root = fixture();
+    const winRoot = root.replaceAll("/", "\\");
+    // A drive path is a plain file name inside the repo on posix and a real path outside it on win32.
+    const foreign =
+      process.platform === "win32" ? path.join(`${root}-foreign`, "a", "foreign.txt") : "C:\\other\\a\\foreign.txt";
+    const foreignAbs = process.platform === "win32" ? foreign : path.join(root, foreign);
+    temps.push(`${root}-foreign`);
+    write(root, "a/keep.txt", "keep\n");
+    write(root, "a/old.txt", "old\n");
+    write(path.dirname(foreignAbs), path.basename(foreignAbs), "mine\n");
+    write(path.dirname(root), `${path.basename(root)}-outside.txt`, "mine\n");
+    temps.push(`${root}-outside.txt`);
+    write(
+      root,
+      MANIFEST_REL,
+      JSON.stringify({
+        version: 1,
+        paths: [`${winRoot}\\a\\keep.txt`, ".\\a\\old.txt", foreign, `..\\${path.basename(root)}-outside.txt`, ""],
+      }),
+    );
+
+    expect((await syncWith(root, only(file("a/keep.txt", "keep\n")))).code).toBe(0);
+    expect(read(root, "a/keep.txt")).toBe("keep\n");
+    expect(exists(root, "a/old.txt")).toBe(false);
+    expect(fs.readFileSync(foreignAbs, "utf8")).toBe("mine\n");
+    expect(fs.readFileSync(`${root}-outside.txt`, "utf8")).toBe("mine\n");
+    expect(manifestPaths(root)).toEqual(["a/keep.txt"]);
+  });
+});
+
+describe("runSync output paths", () => {
+  it("rejects an output outside the repo before writing anything", async () => {
+    const root = fixture();
+    expect(await syncWith(root, only(file("a.txt"), file("../escape.txt")))).toEqual({
+      code: 1,
+      stdout: "",
+      stderr: "repo sync: ../escape.txt: not a path inside the repo\nrepo sync: nothing written\n",
+    });
+    expect(exists(root, "a.txt")).toBe(false);
+  });
+});
+
+describe("runSync --check with the manifest", () => {
+  it("names a missing output, a changed one and a prunable one, and writes nothing", async () => {
+    const root = fixture();
+    await syncWith(root, only(file("changed.txt"), file("gone.txt"), file("missing.txt")));
+    write(root, "changed.txt", "edited\n");
+    fs.rmSync(path.join(root, "missing.txt"));
+    const before = snapshot(root);
+
+    expect(await syncWith(root, only(file("changed.txt"), file("missing.txt"), file("fresh.txt")), "--check")).toEqual({
+      code: 1,
+      stdout: "",
+      stderr:
+        "repo sync: changed.txt is out of date; run `bun repo sync`\n" +
+        "repo sync: missing.txt is out of date; run `bun repo sync`\n" +
+        "repo sync: fresh.txt is out of date; run `bun repo sync`\n" +
+        "repo sync: gone.txt is stale and would be removed; run `bun repo sync`\n",
+    });
+    expect(snapshot(root)).toEqual(before);
+  });
+
+  it("fails on a link that is missing or wrong and passes once it is current", async () => {
+    const root = fixture();
+    fs.mkdirSync(path.join(root, "store"));
+    const deps = only(link("l", "store"));
+    expect((await syncWith(root, deps, "--check")).code).toBe(1);
+    await syncWith(root, deps);
+    expect(await syncWith(root, deps, "--check")).toEqual({ code: 0, stdout: "repo sync: up to date\n", stderr: "" });
+  });
+});
+
+describe("runSync summary", () => {
+  it("groups outputs that share a top dir and keeps single files by name", async () => {
+    const root = fixture();
+    const outputs = [file("a.md"), file(".claude/x"), file(".claude/y/z"), file("docs/one.md"), file(".claude/w")];
+    expect((await syncWith(root, only(...outputs))).stdout).toBe("repo sync: wrote a.md, .claude/ (3), docs/one.md\n");
+    expect((await syncWith(root, only())).stdout).toBe("repo sync: removed .claude/ (3), a.md, docs/one.md\n");
+  });
+});
+
+/** A claude settings overlay whose PreToolUse is a string, the example in the plan. */
+const BAD_OVERLAY = JSON.stringify({ hooks: { PreToolUse: "x" } });
+const SCHEMA_LINE =
+  "repo sync: .claude/settings.json: hooks.PreToolUse: Invalid input: expected array, received string\n";
+const settings = (text: string): Generator[] =>
+  generating({ kind: "file", path: ".claude/settings.json", content: text, tracked: false, managed: "whole" });
+
+describe("runSync output validation", () => {
+  it("names a schema miss with its dotted path, writes nothing and exits 1", async () => {
+    const root = fixture();
+    const before = snapshot(root);
+    const result = await syncWith(root, {
+      generators: [...generating(file("bunfig.toml", BUNFIG)), ...settings(BAD_OVERLAY)],
+    });
+    expect(result).toEqual({ code: 1, stdout: "", stderr: `${SCHEMA_LINE}repo sync: nothing written\n` });
+    expect(snapshot(root)).toEqual(before);
+  });
+
+  it("--check reports the same line and exits 1 without a nothing-written line", async () => {
+    const root = fixture();
+    const result = await syncWith(root, { generators: settings(BAD_OVERLAY) }, "--check");
+    expect(result).toEqual({ code: 1, stdout: "", stderr: SCHEMA_LINE });
+  });
+
+  it("--postinstall prints the lines and exits 0", async () => {
+    const root = fixture();
+    const result = await syncWith(root, { generators: settings(BAD_OVERLAY) }, "--postinstall");
+    expect(result).toEqual({ code: 0, stdout: "", stderr: `${SCHEMA_LINE}repo sync: nothing written\n` });
+  });
+
+  it("refuses an output path with no registered format", async () => {
+    const root = fixture();
+    const before = snapshot(root);
+    const result = await syncWith(root, { generators: generating(file("docs/x.yaml", "a: 1\n")) });
+    expect(result).toEqual({
+      code: 1,
+      stdout: "",
+      stderr:
+        "repo sync: docs/x.yaml: no output format registered; add it to cli/sync/validate.ts\nrepo sync: nothing written\n",
+    });
+    expect(snapshot(root)).toEqual(before);
+  });
+
+  it("accepts a valid overlay result", async () => {
+    const root = fixture();
+    const good = JSON.stringify({ hooks: { PreToolUse: [] } });
+    expect((await syncWith(root, { generators: settings(good) })).code).toBe(0);
+    expect(read(root, ".claude/settings.json")).toBe(good);
+  });
+
+  it("refuses a link that points nowhere", async () => {
+    const root = fixture();
+    const result = await syncWith(root, {
+      generators: generating(link(".claude/skills/ask", "../../.agents/skills/ask")),
+    });
+    expect(result.stderr).toBe(
+      "repo sync: .claude/skills/ask: link target ../../.agents/skills/ask does not exist\nrepo sync: nothing written\n",
+    );
+  });
+
+  it("refuses a real dir where a skill link goes and writes nothing", async () => {
+    // Only this repo skips adoption, which would otherwise move the dir to .repo/skills.
+    const root = fixture();
+    write(root, "package.json", JSON.stringify({ name: "@workerstack/repo" }));
+    write(root, ".claude/skills/ask/SKILL.md", "mine\n");
+    fs.mkdirSync(path.join(root, ".agents/skills/ask"), { recursive: true });
+    const before = snapshot(root);
+    const outputs = generating(file("bunfig.toml", BUNFIG), link(".claude/skills/ask", "../../.agents/skills/ask"));
+    expect(await syncWith(root, { generators: outputs })).toEqual({
+      code: 1,
+      stdout: "",
+      stderr:
+        "repo sync: .claude/skills/ask is a folder where sync puts a link; move it to .repo/skills/ask\nrepo sync: nothing written\n",
+    });
+    expect(snapshot(root)).toEqual(before);
+  });
+
+  it("restores everything when a write fails on the manifest", async () => {
+    const root = fixture();
+    await syncWith(root, only(file("old.txt")));
+    const before = snapshot(root);
+    const real = fs.renameSync;
+    vi.spyOn(fs, "renameSync").mockImplementation((from, to) => {
+      if (String(to).endsWith("sync.json")) throw new Error("EACCES: permission denied, rename");
+      return real(from, to);
+    });
+    const result = await syncWith(root, only(file("a.txt")));
+    expect(result).toEqual({
+      code: 1,
+      stdout: "",
+      stderr:
+        "repo sync: .repo/tmp/sync.json: cannot write: EACCES: permission denied, rename; restored 2 outputs, nothing changed\n",
+    });
+    vi.restoreAllMocks();
+    expect(snapshot(root)).toEqual(before);
+  });
+
+  it("--check still names a hand edit as out of date", async () => {
+    const root = fixture();
+    await sync(root);
+    write(root, "bunfig.toml", `${BUNFIG}# hand edit\n`);
+    expect(await sync(root, "--check")).toEqual({
+      code: 1,
+      stdout: "",
+      stderr: "repo sync: bunfig.toml is out of date; run `bun repo sync`\n",
+    });
+  });
+});
+
+describe("stray ignore files", () => {
+  const NESTED = "ignore rules live in the root .gitignore (or a public package's own); move them there";
+  const NPM = 'npm reads package.json "files"; delete it';
+  const NOTHING = "repo sync: nothing written\n";
+  const DEPS = "node" + "_modules";
+
+  /** The sync fixture as a git repo with a private package `packages/web` beside the public `packages/api`. */
+  function repoWith(files: Record<string, string>, { git = true } = {}): string {
+    const root = fixture();
+    write(root, "packages/web/package.json", JSON.stringify({ name: "web", private: true }));
+    write(root, "packages/web/references/INDEX.md", "# Web\n");
+    for (const [rel, text] of Object.entries(files)) write(root, rel, text);
+    if (git) execFileSync("git", ["init", "-q"], { cwd: root });
+    return root;
+  }
+
+  it("fails on a .gitignore in a private package and in src/, naming each, and writes nothing", async () => {
+    const root = repoWith({ "packages/web/.gitignore": "dist\n", "src/.gitignore": "x\n" });
+    const before = snapshot(root);
+    expect(await sync(root)).toEqual({
+      code: 1,
+      stdout: "",
+      stderr: `repo sync: packages/web/.gitignore: ${NESTED}\n` + `repo sync: src/.gitignore: ${NESTED}\n` + NOTHING,
+    });
+    expect(snapshot(root)).toEqual(before);
+    expect(exists(root, MANIFEST_REL)).toBe(false);
+  });
+
+  it("passes a .gitignore at the root and at a public package root", async () => {
+    const root = repoWith({ "packages/api/.gitignore": "dist\n" });
+    expect((await sync(root)).code).toBe(0);
+  });
+
+  it("fails on any .npmignore, at the root, in a public package and in a private one", async () => {
+    const root = repoWith({ ".npmignore": "a\n", "packages/api/.npmignore": "a\n", "packages/web/.npmignore": "a\n" });
+    expect(await sync(root)).toEqual({
+      code: 1,
+      stdout: "",
+      stderr:
+        `repo sync: .npmignore: ${NPM}\n` +
+        `repo sync: packages/api/.npmignore: ${NPM}\n` +
+        `repo sync: packages/web/.npmignore: ${NPM}\n` +
+        NOTHING,
+    });
+  });
+
+  it("scans nothing outside a git repo", async () => {
+    const root = repoWith({ "src/.gitignore": "x\n", ".npmignore": "a\n" }, { git: false });
+    expect((await sync(root)).code).toBe(0);
+  });
+
+  it("scans nothing when git fails", async () => {
+    const root = repoWith({ "src/.gitignore": "x\n" }, { git: false });
+    write(root, "." + "git", "not a repository\n");
+    expect((await sync(root)).code).toBe(0);
+  });
+
+  it("does not scan what git ignores, such as dependencies and an ignored dir", async () => {
+    const root = repoWith({
+      ".gitignore": `ignored/\n${DEPS}/\n`,
+      [`${DEPS}/pkg/.npmignore`]: "a\n",
+      "ignored/.gitignore": "x\n",
+    });
+    expect((await sync(root)).code).toBe(0);
+  });
+
+  it("scans the repo as git sees it once sync has written the .gitignore block, so a new repo is not deadlocked", async () => {
+    const root = repoWith({
+      [`${DEPS}/x/.npmignore`]: "a\n",
+      ".worktrees/w/.gitignore": "x\n",
+      ".tmp/t/.gitignore": "x\n",
+    });
+    expect(fs.existsSync(path.join(root, ".gitignore"))).toBe(false);
+    expect((await sync(root)).code).toBe(0);
+    expect(read(root, ".gitignore")).toContain(`${DEPS}/\n`);
+  });
+
+  it("does not report a tracked file that was deleted", async () => {
+    const root = repoWith({ "src/.gitignore": "x\n" });
+    execFileSync("git", ["add", "src/.gitignore"], { cwd: root });
+    fs.rmSync(path.join(root, "src/.gitignore"));
+    expect((await sync(root)).code).toBe(0);
+  });
+
+  it("--check fails too, without the closing line", async () => {
+    const root = repoWith({ "src/.gitignore": "x\n" });
+    expect(await sync(root, "--check")).toEqual({
+      code: 1,
+      stdout: "",
+      stderr: `repo sync: src/.gitignore: ${NESTED}\n`,
+    });
+  });
+
+  it("--postinstall prints the lines and exits 0, writing nothing", async () => {
+    const root = repoWith({ "src/.gitignore": "x\n" });
+    const before = snapshot(root);
+    expect(await sync(root, "--postinstall")).toEqual({
+      code: 0,
+      stdout: "",
+      stderr: `repo sync: src/.gitignore: ${NESTED}\n` + NOTHING,
+    });
+    expect(snapshot(root)).toEqual(before);
+  });
+
+  it("lists a stray file before an invalid output's problem", async () => {
+    const root = repoWith({ "src/.gitignore": "x\n" });
+    const bad = { generators: generating(file("bad.json")), formats: [{ match: () => true, format: "json" as const }] };
+    const result = await syncWith(root, bad);
+    expect(result.code).toBe(1);
+    expect(result.stderr.split("\n").slice(0, 2)).toEqual([
+      `repo sync: src/.gitignore: ${NESTED}`,
+      expect.stringMatching(/^repo sync: bad\.json: invalid JSON/),
+    ]);
+    expect(result.stderr.endsWith(NOTHING)).toBe(true);
+  });
+});
+
+describe("runSync from an old-format consumer", { timeout: 120_000 }, () => {
+  const SELF_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const OVERVIEW = '---\nroot: true\ntargets: ["*"]\nglobs: ["**/*"]\n---\n# Mine\n\nOur overview.\n';
+  const TESTING = '---\nroot: false\ntargets: ["*"]\nglobs:\n  - src/**\n---\n# Testing\n\nRun the tests.\n';
+
+  /** A consumer on the stock package whose rules still carry root, targets and globs, with a `.grok/rules` file an earlier sync wrote. */
+  function oldConsumer(): string {
+    const root = tempDir();
+    write(root, CONFIG_FILE, 'export default { packs: ["agents"], agents: { hosts: ["claude", "grok"] } }\n');
+    write(root, "package.json", JSON.stringify({ name: "fixture" }));
+    fs.mkdirSync(path.join(root, "node_modules", "@workerstack"), { recursive: true });
+    fs.symlinkSync(SELF_ROOT, path.join(root, "node_modules", "@workerstack", "repo"), "dir");
+    write(root, ".repo/rules/overview.md", OVERVIEW);
+    write(root, ".repo/rules/testing.md", TESTING);
+    write(root, ".grok/rules/testing.md", "Run the tests.\n");
+    write(root, MANIFEST_REL, renderManifest([".grok/rules/testing.md"]));
+    return root;
+  }
+
+  const real = (cwd: string, ...args: string[]) => syncWith(cwd, {}, ...args);
+
+  /** Every file outside the linked package dir, with its bytes. */
+  function files(root: string, dir = ""): Record<string, string> {
+    const found: Record<string, string> = {};
+    for (const entry of fs.readdirSync(path.join(root, dir), { withFileTypes: true })) {
+      const rel = dir === "" ? entry.name : `${dir}/${entry.name}`;
+      if (rel === "node_modules") continue;
+      if (entry.isSymbolicLink()) found[rel] = `-> ${fs.readlinkSync(path.join(root, rel))}`;
+      else if (entry.isDirectory()) Object.assign(found, files(root, rel));
+      else found[rel] = fs.readFileSync(path.join(root, rel), "utf8");
+    }
+    return found;
+  }
+
+  it("prints the rewrite and mark lines, then the summary with the removed .grok/rules file", async () => {
+    const root = oldConsumer();
+    const result = await real(root);
+    expect(result.stderr).toBe("");
+    expect(result.code).toBe(0);
+    const lines = result.stdout.split("\n");
+    expect(lines.slice(0, 3)).toEqual([
+      "repo sync: rewrote .repo/rules/overview.md frontmatter (description added, root, targets and globs dropped)",
+      "repo sync: marked .repo/rules/overview.md with overrides: overview (it replaces the stock rule)",
+      "repo sync: rewrote .repo/rules/testing.md frontmatter (description added, globs → paths, root and targets dropped)",
+    ]);
+    expect(lines[3]).toMatch(/^repo sync: wrote .*AGENTS\.md.*; removed .*\.grok\/rules\/testing\.md/);
+    expect(read(root, ".repo/rules/overview.md")).toBe(
+      "---\ndescription: Mine\noverrides: overview\n---\n# Mine\n\nOur overview.\n",
+    );
+    expect(read(root, ".claude/rules/testing.md")).toBe("---\npaths:\n  - src/**\n---\n# Testing\n\nRun the tests.\n");
+    expect(read(root, "AGENTS.md")).toContain("- `src/**`: read `.repo/rules/testing.md`");
+    expect(fs.existsSync(path.join(root, ".grok/rules/testing.md"))).toBe(false);
+  });
+
+  it("converges: a second sync and --check have nothing to do", async () => {
+    const root = oldConsumer();
+    await real(root);
+    const before = files(root);
+    expect(await real(root)).toEqual({ code: 0, stdout: "repo sync: up to date\n", stderr: "" });
+    expect(await real(root, "--check")).toEqual({ code: 0, stdout: "repo sync: up to date\n", stderr: "" });
+    expect(files(root)).toEqual(before);
+  });
+
+  it("--check counts the upgrade as migration steps and writes nothing", async () => {
+    const root = oldConsumer();
+    const before = files(root);
+    expect(await real(root, "--check")).toEqual({
+      code: 1,
+      stdout: "",
+      stderr: "repo sync: 2 migration steps pending; run `bun repo sync`\n",
+    });
+    expect(files(root)).toEqual(before);
+  });
+
+  it("--check prints the problems without a nothing-written line", async () => {
+    const root = oldConsumer();
+    write(root, ".repo/rules/overview.md", "---\ndescription: new\n---\nB\n");
+    write(root, ".repo/rules/testing.md", "---\ndescription: t\n---\nB\n");
+    expect(await real(root, "--check")).toEqual({
+      code: 1,
+      stdout: "",
+      stderr:
+        "repo sync: .repo/rules/overview.md: a stock rule has this name; add `overrides: overview` or rename it\n",
+    });
+  });
+
+  it("--check says step, not steps, for a single pending upgrade", async () => {
+    const root = oldConsumer();
+    write(root, ".repo/rules/testing.md", "---\ndescription: t\n---\nB\n");
+    expect((await real(root, "--check")).stderr).toBe("repo sync: 1 migration step pending; run `bun repo sync`\n");
+  });
+
+  it("reports an upgrade that cannot write, and leaves the rule as it was", async () => {
+    const root = oldConsumer();
+    vi.spyOn(fs, "renameSync").mockImplementationOnce(() => {
+      throw Object.assign(new Error("EACCES: permission denied, rename"), { code: "EACCES" });
+    });
+    const result = await real(root);
+    expect(result.code).toBe(1);
+    expect(result.stderr).toBe("repo sync: EACCES: permission denied, rename\n");
+    expect(read(root, ".repo/rules/overview.md")).toBe(OVERVIEW);
+  });
+
+  it("prints one line per problem when new rules clash with stock or name nothing", async () => {
+    const root = oldConsumer();
+    write(root, ".repo/rules/overview.md", "---\ndescription: new\n---\nB\n");
+    write(root, ".repo/rules/testing.md", "---\ndescription: t\noverrides: nope\n---\nB\n");
+    write(root, ".repo/rules/bad.md", "no fence\n");
+    const before = files(root);
+    const result = await real(root);
+    expect(result.code).toBe(1);
+    expect(result.stdout).toBe("");
+    expect(result.stderr).toBe(
+      [
+        "repo sync: .repo/rules/bad.md: missing frontmatter (start the file with a --- block)",
+        "repo sync: .repo/rules/overview.md: a stock rule has this name; add `overrides: overview` or rename it",
+        'repo sync: .repo/rules/testing.md: overrides "nope" but no stock rule has that name',
+        "repo sync: nothing written",
+        "",
+      ].join("\n"),
+    );
+    expect(files(root)).toEqual(before);
+  });
+});
+
+describe("runSync over a .repo that breaks the closed layout", { timeout: 120_000 }, () => {
+  const SELF_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const ALLOWED =
+    "rules/, subagents/, skills/, lessons/, tmp/, global-settings/, settings/claude.json, hooks.jsonc, mcp-policy.jsonc, permissions.json, mcp.json, map.jsonc, lint-baseline.json (read by repo turn and repo check)";
+  const LINES = [
+    `.repo/notes.md: not part of .repo; allowed: ${ALLOWED}; explanations go in references/`,
+    ".repo/scripts/: nothing reads it; move what you need out of .repo and delete it",
+    '.repo/skills/deploy/SKILL.md: name "ship" must equal the folder name "deploy"',
+    ".repo/skills/deploy/SKILL.md: link ./steps.md does not exist",
+    '.repo/rules/api.md: paths "srv/**" matches no file',
+    '.repo/rules/x.md: unknown frontmatter key "colour"; use description, paths, overrides',
+  ]
+    .map((line) => `repo sync: ${line}\n`)
+    .join("");
+  const NOTHING = "repo sync: nothing written\n";
+
+  function broken(): string {
+    const root = tempDir();
+    write(root, CONFIG_FILE, 'export default { packs: ["agents"], agents: { hosts: ["claude"] } }\n');
+    write(root, "package.json", JSON.stringify({ name: "fixture" }));
+    const scope = path.join(root, "node" + "_modules", "@workerstack");
+    fs.mkdirSync(scope, { recursive: true });
+    fs.symlinkSync(SELF_ROOT, path.join(scope, "repo"), "dir");
+    write(root, ".repo/notes.md", "mine\n");
+    write(root, ".repo/scripts/x.ts", "export {}\n");
+    write(root, ".repo/skills/deploy/SKILL.md", "---\nname: ship\ndescription: d\n---\nSee [steps](./steps.md).\n");
+    write(root, ".repo/rules/api.md", '---\ndescription: d\npaths: ["srv/**"]\n---\nApi.\n');
+    write(root, ".repo/rules/x.md", "---\ndescription: d\ncolour: red\n---\nX.\n");
+    execFileSync("git", ["init", "-q"], { cwd: root });
+    return root;
+  }
+  const real = (cwd: string, ...args: string[]) => syncWith(cwd, {}, ...args);
+  /** Every file outside the linked package dir and the repo's own metadata, with its bytes. */
+  function tree(root: string, dir = ""): Record<string, string> {
+    const found: Record<string, string> = {};
+    for (const entry of fs.readdirSync(path.join(root, dir), { withFileTypes: true })) {
+      const rel = dir === "" ? entry.name : `${dir}/${entry.name}`;
+      if (rel === "node" + "_modules" || rel === "." + "git") continue;
+      if (entry.isDirectory()) Object.assign(found, tree(root, rel));
+      else found[rel] = fs.readFileSync(path.join(root, rel), "utf8");
+    }
+    return found;
+  }
+
+  it("prints every problem in one refusal with nothing written, and exits 1", async () => {
+    const root = broken();
+    const before = tree(root);
+    expect(await real(root)).toEqual({ code: 1, stdout: "", stderr: LINES + NOTHING });
+    expect(tree(root)).toEqual(before);
+  });
+
+  it("--check prints the same lines without nothing written, and exits 1", async () => {
+    const root = broken();
+    const before = tree(root);
+    expect(await real(root, "--check")).toEqual({ code: 1, stdout: "", stderr: LINES });
+    expect(tree(root)).toEqual(before);
+  });
+
+  it("--postinstall prints the lines and exits 0", async () => {
+    const result = await real(broken(), "--postinstall");
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe(LINES + NOTHING);
+  });
+});
+
+describe("runSync over a two-package workspace", { timeout: 120_000 }, () => {
+  const SELF_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const rule = (extra: string, body: string) => `---\ndescription: d\n${extra}---\n${body}\n`;
+
+  function workspace(extra: Record<string, string> = {}): string {
+    const root = tempDir();
+    write(root, CONFIG_FILE, 'export default { packs: ["agents", "docs"], agents: { hosts: ["claude", "codex"] } }\n');
+    write(root, "package.json", JSON.stringify({ name: "fixture", workspaces: ["packages/*"] }));
+    const scope = path.join(root, "node" + "_modules", "@workerstack");
+    fs.mkdirSync(scope, { recursive: true });
+    fs.symlinkSync(SELF_ROOT, path.join(scope, "repo"), "dir");
+    write(
+      root,
+      "packages/web/package.json",
+      JSON.stringify({ name: "@acme/web", dependencies: { "@acme/api": "1.0.0", "@workerstack/ui": "1.0.0" } }),
+    );
+    write(root, "packages/web/references/INDEX.md", "# Web\n");
+    write(root, "packages/api/package.json", JSON.stringify({ name: "@acme/api" }));
+    write(root, "packages/api/references/INDEX.md", "# Api\n");
+    write(root, "packages/web/src/api/a.ts", "export {}\n");
+    write(
+      root,
+      "packages/web/.repo/rules/components.md",
+      rule("", "Components live in src/components and use the ui kit."),
+    );
+    write(root, "packages/web/.repo/rules/api.md", rule("paths:\n  - src/api/**\n", "Api."));
+    write(
+      root,
+      "packages/web/.repo/skills/deploy/SKILL.md",
+      "---\nname: deploy\ndescription: Ships web.\n---\nDeploy.\n",
+    );
+    for (const [rel, text] of Object.entries(extra)) write(root, rel, text);
+    execFileSync("git", ["init", "-q"], { cwd: root });
+    return root;
+  }
+  const real = (cwd: string, ...args: string[]) => syncWith(cwd, { post: [gitFiles] }, ...args);
+
+  it("writes the package files, links and deps, ignores them, and is then clean", async () => {
+    const root = workspace();
+    expect((await real(root)).code).toBe(0);
+    expect(read(root, "packages/web/AGENTS.md")).toBe(
+      "Start at references/INDEX.md in this package.\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(read(root, "packages/web/CLAUDE.md")).toBe("Start at references/INDEX.md in this package.\n");
+    expect(read(root, ".claude/rules/packages/web/components.md")).toBe(
+      "---\npaths:\n  - packages/web/**\n---\nComponents live in src/components and use the ui kit.\n",
+    );
+    expect(linkText(path.join(root, "packages/web/.claude/skills/deploy"))).toBe("../../.repo/skills/deploy");
+    expect(linkText(path.join(root, "packages/web/.agents/skills/deploy"))).toBe("../../.repo/skills/deploy");
+    expect(read(root, "AGENTS.md")).not.toContain("Components live");
+    expect(read(root, "packages/web/references/INDEX.md")).toBe(
+      "# Web\n\n<!-- repo:deps -->\n- [@acme/api](../../api/references/INDEX.md)\n" +
+        "- [@workerstack/ui](../../../node_modules/@workerstack/ui/references/INDEX.md)\n<!-- /repo:deps -->\n",
+    );
+    const ignored = execFileSync(
+      "git",
+      [
+        "check-ignore",
+        "packages/web/AGENTS.md",
+        "packages/web/CLAUDE.md",
+        "packages/web/.claude/skills/deploy",
+        "packages/web/.agents/skills/deploy",
+        "packages/api/AGENTS.md",
+      ],
+      { cwd: root, encoding: "utf8" },
+    );
+    expect(ignored.split("\n").filter(Boolean)).toHaveLength(5);
+    expect(await real(root, "--check")).toEqual({ code: 0, stdout: "repo sync: up to date\n", stderr: "" });
+  });
+
+  it("prints every package refusal in one go with nothing written", async () => {
+    const root = workspace({
+      "packages/web/.repo/lessons/a.md": "x\n",
+      "packages/web/.repo/rules/x.md": rule('paths:\n  - "../api/**"\n', "X."),
+      "packages/web/.repo/rules/y.md": rule("overrides: overview\n", "Y."),
+      ".repo/rules/packages/web/x.md": rule("paths:\n  - packages/**\n", "Clash."),
+    });
+    expect(await real(root)).toEqual({
+      code: 1,
+      stdout: "",
+      stderr:
+        "repo sync: packages/web/.repo/lessons/: a package .repo holds only rules/ and skills/; lessons live in the root .repo\n" +
+        'repo sync: packages/web/.repo/rules/x.md: paths "../api/**" leaves the package; scope it inside packages/web\n' +
+        "repo sync: packages/web/.repo/rules/y.md: overrides has no meaning in a package rule; remove it\n" +
+        "repo sync: .claude/rules/packages/web/x.md: planned by .repo/rules/packages/web/x.md and packages/web/.repo/rules/x.md; rename one\n" +
+        "repo sync: nothing written\n",
+    });
+    expect(fs.existsSync(path.join(root, "packages/web/AGENTS.md"))).toBe(false);
+  });
+});
+
+const hooksGit = (cwd: string, ...args: string[]) => spawnSync("git", args, { cwd, encoding: "utf8" });
+const hooksPath = (root: string) => hooksGit(root, "config", "--local", "--get", "core.hooksPath").stdout.trim();
+/**
+ * A temp git repo with `packs`, its git kept from the user's global config by an empty one of its own, which
+ * `global` writes to.
+ */
+function hooksRepo(packs = '["standards"]') {
+  const root = fs.realpathSync(tempDir());
+  const globalConfig = path.join(tempDir(), "global.gitconfig");
+  fs.writeFileSync(globalConfig, "");
+  vi.stubEnv("GIT_CONFIG_GLOBAL", globalConfig);
+  hooksGit(root, "init", "-q");
+  write(root, "package.json", JSON.stringify({ name: "app" }));
+  write(root, CONFIG_FILE, `export default { packs: ${packs} }\n`);
+  return { root, global: (text: string) => fs.writeFileSync(globalConfig, text) };
+}
+const syncHooks = (root: string, ...args: string[]) => syncWith(root, { generators: [], post: [standards] }, ...args);
+const foreign = (value: string, scope = "") =>
+  `repo sync: core.hooksPath is ${value}, so repo's hooks never run; unset it (git config ${scope}--unset core.hooksPath) and sync again\n`;
+const UP_TO_DATE = { code: 0, stdout: "repo sync: up to date\n", stderr: "" };
+
+describe("runSync core.hooksPath", () => {
+  it("points core.hooksPath at the hooks when it is unset, then leaves it", async () => {
+    const { root } = hooksRepo();
+    expect((await syncHooks(root)).stdout).toMatch(
+      /; set core\.hooksPath to \.githooks(?:; marked .* executable in the index)?\n$/,
+    );
+    expect(hooksPath(root)).toBe(".githooks");
+    expect(await syncHooks(root)).toEqual(UP_TO_DATE);
+    hooksGit(root, "config", "--unset", "core.hooksPath");
+    expect((await syncHooks(root, "--postinstall")).stdout).toBe("repo sync: set core.hooksPath to .githooks\n");
+    expect(hooksPath(root)).toBe(".githooks");
+  });
+
+  it("reports a foreign value on every run and changes nothing", async () => {
+    const { root } = hooksRepo();
+    hooksGit(root, "config", "core.hooksPath", ".husky");
+    const reported = { code: 0, stdout: expect.any(String) as unknown, stderr: foreign(".husky") };
+    expect(await syncHooks(root)).toEqual(reported);
+    expect(await syncHooks(root, "--postinstall")).toEqual(reported);
+    expect(hooksPath(root)).toBe(".husky");
+  });
+});
+
+describe("runSync core.hooksPath with the pack off", () => {
+  it("unsets only its own value", async () => {
+    const { root } = hooksRepo("[]");
+    hooksGit(root, "config", "core.hooksPath", ".githooks");
+    expect(await syncHooks(root)).toEqual({ code: 0, stdout: "repo sync: unset core.hooksPath\n", stderr: "" });
+    expect(hooksGit(root, "config", "--local", "--get", "core.hooksPath").status).toBe(1);
+    hooksGit(root, "config", "core.hooksPath", ".husky");
+    expect(await syncHooks(root)).toEqual(UP_TO_DATE);
+    expect(hooksPath(root)).toBe(".husky");
+  });
+
+  it("leaves its own value alone when it comes from another scope than the repo's", async () => {
+    const { root, global } = hooksRepo("[]");
+    global("[core]\n\thooksPath = .githooks\n");
+    expect(await syncHooks(root)).toEqual(UP_TO_DATE);
+  });
+});
+
+describe("runSync core.hooksPath where it does not apply", () => {
+  it("--check never reads or writes it", async () => {
+    const { root } = hooksRepo();
+    await syncHooks(root);
+    hooksGit(root, "config", "--unset", "core.hooksPath");
+    expect(await syncHooks(root, "--check")).toEqual(UP_TO_DATE);
+    hooksGit(root, "config", "core.hooksPath", ".husky");
+    expect(await syncHooks(root, "--check")).toEqual(UP_TO_DATE);
+    expect(hooksPath(root)).toBe(".husky");
+  });
+
+  it("leaves the config of a repo it is nested in, whose toplevel is not the sync root", async () => {
+    const { root: outer } = hooksRepo("[]");
+    hooksGit(outer, "config", "core.hooksPath", ".githooks");
+    const inner = path.join(outer, "inner");
+    write(inner, "package.json", JSON.stringify({ name: "inner" }));
+    write(inner, CONFIG_FILE, "export default { packs: [] }\n");
+    expect(await syncHooks(inner)).toEqual(UP_TO_DATE);
+    expect(hooksPath(outer)).toBe(".githooks");
+  });
+});
+
+describe("runSync core.hooksPath messages", () => {
+  it("names the scope that holds a foreign value", async () => {
+    const { root, global } = hooksRepo();
+    global("[core]\n\thooksPath = ~/hooks\n");
+    expect((await syncHooks(root)).stderr).toBe(foreign("~/hooks", "--global "));
+  });
+
+  it("says when git cannot set it, and tries again on the next run", async () => {
+    const { root } = hooksRepo();
+    const fake = (_root: string, args: readonly string[]) => {
+      if (args[0] === "rev-parse") return { status: 0, stdout: `${root}\n`, stderr: "" };
+      if (args.includes("--get")) return { status: 1, stdout: "", stderr: "" };
+      return { status: 255, stdout: "", stderr: "error: could not lock config file\n" };
+    };
+    const result = await syncWith(root, { generators: [], post: [standards], git: fake });
+    expect(result).toMatchObject({
+      code: 0,
+      stderr: "repo sync: cannot set core.hooksPath to .githooks: error: could not lock config file\n",
+    });
+    expect((await syncHooks(root)).stdout).toMatch(
+      /^repo sync: set core\.hooksPath to \.githooks(?:; marked .* executable in the index)?\n$/,
+    );
+  });
+});
+
+describe("runSync hook modes", () => {
+  // The next test covers win32, which has no execute bits to lose.
+  it.skipIf(process.platform === "win32")(
+    "rewrites a hook that lost its execute bits, which --check reports",
+    async () => {
+      const { root } = hooksRepo();
+      await syncHooks(root);
+      fs.chmodSync(path.join(root, ".githooks/pre-commit"), 0o644);
+      const stale = "repo sync: .githooks/pre-commit is out of date; run `bun repo sync`\n";
+      expect((await syncHooks(root, "--check")).stderr).toBe(stale);
+      await syncHooks(root);
+      expect(fs.statSync(path.join(root, ".githooks/pre-commit")).mode & 0o777).toBe(0o755);
+    },
+  );
+
+  it("does not compare execute bits on win32, which has none", async () => {
+    const { root } = hooksRepo();
+    await syncHooks(root);
+    fs.chmodSync(path.join(root, ".githooks/pre-commit"), 0o644);
+    const win32 = { generators: [], post: [standards], platform: "win32" as const };
+    expect(await syncWith(root, win32, "--check")).toEqual(UP_TO_DATE);
+  });
+});