@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/sync/fixtures/maps/golden/INDEX.md

@@ -0,0 +1,22 @@
+# Index
+
+Essay-style INDEX must not appear as a catalog row.
+
+<!-- repo:skills -->
+| name | origin | description | task | commandPath | refs |
+| --- | --- | --- | --- | --- | --- |
+| alpha | local | Alpha skill one-liner. | alpha-work | scripts/alpha.mjs | cascade.md, alpha.md |
+| beta | repo | Beta folded description that should collapse to one line. |  |  |  |
+<!-- /repo:skills -->
+
+Hand text between sections stays.
+
+<!-- repo:refs -->
+| path | title | tags | summary |
+| --- | --- | --- | --- |
+| node_modules/@workerstack/repo/references/alpha.md | Alpha | alpha | First sentence of alpha ref. |
+| node_modules/@workerstack/repo/references/nested/beta.md | Beta nested | beta | Nested beta summary line. |
+<!-- /repo:refs -->
+
+<!-- repo:stack -->
+<!-- /repo:stack -->

package/cli/sync/git-files.test.ts

@@ -0,0 +1,340 @@
+import { BASE_CONFIG } from "../fixtures/base-config.ts";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parse } from "jsonc-parser";
+import { describe, expect, it } from "vitest";
+import { readGoldens } from "../../dev/capture-tree-goldens.ts";
+import { HOSTS, type Host } from "../config.ts";
+import { gitFiles, listedFiles, untrackedEntries } from "./git-files.ts";
+import { HOST_TREES } from "./hosts.ts";
+import type { Managed, Output, SyncContext } from "./outputs.ts";
+
+const IGNORE_HEAD = "# >>> @workerstack/repo (generated by repo sync)\n.tmp/\n.worktrees/\n.repo/tmp/\ncoverage/\n";
+const IGNORE_END = "# <<< @workerstack/repo\n";
+const ATTR_HEAD = "# >>> @workerstack/repo (generated by repo sync)\n* text=auto eol=lf\n";
+
+type Fixture = { hosts?: Host[]; name?: string; files?: Record<string, string> };
+
+function context({ hosts = [], name = "app", files = {} }: Fixture = {}): SyncContext {
+  return {
+    root: "/repo",
+    config: {
+      packs: ["agents"],
+      agents: { hosts, skills: [] },
+      ...BASE_CONFIG,
+    },
+    workspace: { root: "/repo", manifest: { name }, packages: [] },
+    read: (rel) => files[rel] ?? null,
+  };
+}
+
+const file = (path: string, tracked: boolean, managed: Managed = "whole"): Output => ({
+  kind: "file",
+  path,
+  content: `${path}\n`,
+  tracked,
+  managed,
+});
+const link = (path: string, tracked: boolean): Output => ({
+  kind: "link",
+  path,
+  target: "elsewhere",
+  tracked,
+  managed: "whole",
+});
+
+/** What the trees generator plans for `hosts`: AGENTS.md, .mcp.json and a file in each dir the hosts own, none committed. */
+function treeOutputs(hosts: readonly Host[], tracked: boolean): Output[] {
+  const dirs = hosts.flatMap((host) => HOST_TREES[host].owns);
+  return [
+    ...(hosts.length > 0 ? [file("AGENTS.md", tracked)] : []),
+    ...(hosts.includes("claude") ? [file(".mcp.json", tracked)] : []),
+    ...dirs.map((dir) => file(`${dir}config.toml`, tracked)),
+    ...dirs.map((dir) => link(`${dir}skills-link`, tracked)),
+  ];
+}
+
+const outputOf = (outputs: Output[], rel: string): string => {
+  const found = outputs.find((output) => output.path === rel);
+  if (found?.kind !== "file") throw new Error(`no file output ${rel}`);
+  return found.content;
+};
+const run = (fixture: Fixture, outputs: Output[]) => gitFiles(context(fixture), outputs);
+const gitignoreOf = (fixture: Fixture, outputs: Output[]) => outputOf(run(fixture, outputs).outputs, ".gitignore");
+const gitattributesOf = (fixture: Fixture, outputs: Output[]) =>
+  outputOf(run(fixture, outputs).outputs, ".gitattributes");
+const settingsOf = (fixture: Fixture, outputs: Output[]) =>
+  outputOf(run(fixture, outputs).outputs, ".vscode/settings.json");
+const readonlyOf = (text: string): string[] =>
+  Object.keys((parse(text) as Record<string, Record<string, boolean>>)["files.readonlyInclude"] ?? {});
+const block = (...entries: string[]) => `${IGNORE_HEAD}${["node_modules/", ...entries].join("\n")}\n${IGNORE_END}`;
+
+describe("the gitignore block", () => {
+  it("lists AGENTS.md, .mcp.json and every host dir for the untracked trees of all hosts", () => {
+    expect(gitignoreOf({ hosts: [...HOSTS] }, treeOutputs(HOSTS, false))).toBe(
+      block("AGENTS.md", ".mcp.json", ".agents/", ".claude/", ".codex/", ".cursor/", ".grok/"),
+    );
+  });
+
+  it("lists only what the enabled hosts own, a parent dir covering its children", () => {
+    expect(gitignoreOf({ hosts: ["claude"] }, treeOutputs(["claude"], false))).toBe(
+      block("AGENTS.md", ".mcp.json", ".claude/"),
+    );
+    expect(gitignoreOf({ hosts: ["codex"] }, treeOutputs(["codex"], false))).toBe(
+      block("AGENTS.md", ".agents/skills/", ".codex/"),
+    );
+    const both: Host[] = ["codex", "antigravity"];
+    expect(gitignoreOf({ hosts: both }, treeOutputs(both, false))).toBe(block("AGENTS.md", ".agents/", ".codex/"));
+  });
+
+  it("lists an untracked output outside every host dir by its exact path, and an untracked link by its dir", () => {
+    const outputs = [file("generated/out.txt", false), link(".claude/skills/ask", false)];
+    expect(gitignoreOf({ hosts: ["claude"] }, outputs)).toBe(block("generated/out.txt", ".claude/"));
+  });
+
+  it("ignores the vitest preset's report directory, so lint does not scan generated coverage reports", () => {
+    const hosts: Host[] = ["claude"];
+    expect(gitignoreOf({ name: "@workerstack/repo", hosts }, treeOutputs(hosts, true)).split("\n")).toContain(
+      "coverage/",
+    );
+  });
+
+  it("lists nothing untracked for this repo, whose trees are committed, and keeps its own dependency line outside", () => {
+    const self = { name: "@workerstack/repo", hosts: ["claude", "codex"] as Host[] };
+    expect(gitignoreOf(self, treeOutputs(self.hosts, true))).toBe(`${IGNORE_HEAD}${IGNORE_END}`);
+  });
+
+  it("lists no tracked output and no block output, tracked or not", () => {
+    const outputs = [
+      file("bunfig.toml", true),
+      file("references/INDEX.md", false, "block"),
+      file(".gitattributes", false, "block"),
+    ];
+    expect(gitignoreOf({ hosts: ["claude"] }, outputs)).toBe(block());
+  });
+
+  it("writes the block alone when .gitignore is missing, empty or blank", () => {
+    for (const files of [{}, { ".gitignore": "" }, { ".gitignore": "\n\n" }] as Record<string, string>[])
+      expect(gitignoreOf({ files }, [])).toBe(block());
+  });
+
+  it("appends the block after one blank line, adding a missing trailing newline first", () => {
+    expect(gitignoreOf({ files: { ".gitignore": "dist" } }, [])).toBe(`dist\n\n${block()}`);
+    expect(gitignoreOf({ files: { ".gitignore": "node_modules/\n.tmp/\n\n\n" } }, [])).toBe(
+      `node_modules/\n.tmp/\n\n${block()}`,
+    );
+  });
+
+  it("replaces the block in place, matching the begin marker by prefix and keeping the text around it", () => {
+    const text = "dist/\n# >>> @workerstack/repo (old label)\n.cache/\n# <<< @workerstack/repo\n\n.env\n";
+    expect(gitignoreOf({ files: { ".gitignore": text } }, [])).toBe(`dist/\n${block()}\n.env\n`);
+  });
+
+  it("leaves a current .gitignore byte-identical and does not take a longer marker for the begin marker", () => {
+    const current = `dist/\n\n${block()}`;
+    expect(gitignoreOf({ files: { ".gitignore": current } }, [])).toBe(current);
+    const longer = "# >>> @workerstack/repository\n";
+    expect(gitignoreOf({ files: { ".gitignore": longer } }, [])).toBe(`${longer}\n${block()}`);
+  });
+
+  it("fails on a begin marker with no closing marker, for .gitignore and .gitattributes alike", () => {
+    const open = "# >>> @workerstack/repo (generated by repo sync)\n.tmp/\n";
+    const result = run({ files: { ".gitignore": open, ".gitattributes": open } }, []);
+    expect(result.errors).toEqual([
+      '.gitignore: "# >>> @workerstack/repo" has no closing "# <<< @workerstack/repo"',
+      '.gitattributes: "# >>> @workerstack/repo" has no closing "# <<< @workerstack/repo"',
+    ]);
+    expect(result.outputs.map((output) => output.path)).toEqual([".vscode/settings.json"]);
+  });
+});
+
+describe("untrackedEntries", () => {
+  it("is what the gitignore block lists for the outputs, without the base lines", () => {
+    expect(untrackedEntries(["claude"], treeOutputs(["claude"], false))).toEqual([
+      "AGENTS.md",
+      ".mcp.json",
+      ".claude/",
+    ]);
+    expect(untrackedEntries(["claude"], treeOutputs(["claude"], true))).toEqual([]);
+    expect(untrackedEntries([], [file("AGENTS.md", false)])).toEqual(["AGENTS.md"]);
+  });
+
+  it("adds the pattern of knip's ignore-free copies beside knip.json, sorted among the files", () => {
+    const outputs = [file("AGENTS.md", false), file("knip.json", false), file(".oxlintrc.json", false)];
+    expect(untrackedEntries([], outputs)).toEqual([
+      "AGENTS.md",
+      "knip.json",
+      "knip.unignored-*.json",
+      ".oxlintrc.json",
+      ".oxlintrc.unskipped-*.json",
+    ]);
+  });
+});
+
+describe("the gitattributes block", () => {
+  it("sets LF and marks every tracked whole file output, sorted, with no link, untracked or block output", () => {
+    const outputs = [
+      file("bunfig.toml", true),
+      file("AGENTS.md", true),
+      file(".agents/agents/implementer-deep.md", true),
+      link(".claude/skills/ask", true),
+      file(".claude/settings.json", false),
+      file("references/INDEX.md", true, "block"),
+      file(".gitignore", true, "block"),
+    ];
+    expect(gitattributesOf({}, outputs)).toBe(
+      `${ATTR_HEAD}.agents/agents/implementer-deep.md linguist-generated\nAGENTS.md linguist-generated\nbunfig.toml linguist-generated\n${IGNORE_END}`,
+    );
+  });
+
+  it("sets LF alone when nothing is tracked, as in a consumer whose only tracked output is a block", () => {
+    expect(gitattributesOf({ hosts: ["claude"] }, treeOutputs(["claude"], false))).toBe(`${ATTR_HEAD}${IGNORE_END}`);
+  });
+
+  it("keeps the user's lines outside the block and replaces the block in place", () => {
+    const text = `*.png binary\n\n${ATTR_HEAD}stale linguist-generated\n${IGNORE_END}\n*.lock -diff\n`;
+    expect(gitattributesOf({ files: { ".gitattributes": text } }, [file("bunfig.toml", true)])).toBe(
+      `*.png binary\n\n${ATTR_HEAD}bunfig.toml linguist-generated\n${IGNORE_END}\n*.lock -diff\n`,
+    );
+  });
+});
+
+describe("files.readonlyInclude in .vscode/settings.json", () => {
+  const OUTPUTS = [file("bunfig.toml", true), file(".claude/settings.json", false), link(".claude/skills/ask", false)];
+
+  it("creates the file with the exact path of every whole file output, sorted, and no link", () => {
+    expect(settingsOf({}, OUTPUTS)).toBe(
+      '{\n  "files.readonlyInclude": {\n    ".claude/settings.json": true,\n    "bunfig.toml": true\n  }\n}\n',
+    );
+    expect(settingsOf({ files: { ".vscode/settings.json": " \n" } }, OUTPUTS)).toBe(settingsOf({}, OUTPUTS));
+  });
+
+  it("leaves out block outputs and does not lock a user file inside a generated dir", () => {
+    const outputs = [
+      ...OUTPUTS,
+      file(".gitignore", true, "block"),
+      file(".vscode/settings.json", true, "block"),
+      file("references/INDEX.md", true, "block"),
+    ];
+    expect(readonlyOf(settingsOf({}, outputs))).toEqual([".claude/settings.json", "bunfig.toml"]);
+    expect(readonlyOf(settingsOf({}, outputs))).not.toContain(".claude");
+    expect(readonlyOf(settingsOf({}, outputs))).not.toContain(".claude/mine.md");
+  });
+
+  it("adds the map to a commented file and keeps every other key and comment byte for byte", () => {
+    const before = '// my editor\n{\n  "editor.tabSize": 4, // wide\n\t/* keep */ "files.autoSave": "off",\n}\n';
+    const after = settingsOf({ files: { ".vscode/settings.json": before } }, OUTPUTS);
+    expect(after.startsWith("// my editor\n{\n")).toBe(true);
+    expect(after.endsWith('\n  "editor.tabSize": 4, // wide\n\t/* keep */ "files.autoSave": "off",\n}\n')).toBe(true);
+    expect(readonlyOf(after)).toEqual([".claude/settings.json", "bunfig.toml"]);
+    expect(parse(after)).toMatchObject({ "editor.tabSize": 4, "files.autoSave": "off" });
+  });
+
+  it("replaces a map of the user's own, and keeps the keys around it as written", () => {
+    const before =
+      '{\n  // lock\n  "files.readonlyInclude": { "mine.txt": true, "bunfig.toml": false },\n  "editor.tabSize": 2 /* last */\n}\n';
+    const after = settingsOf({ files: { ".vscode/settings.json": before } }, OUTPUTS);
+    expect(readonlyOf(after)).toEqual([".claude/settings.json", "bunfig.toml"]);
+    expect(parse(after)["files.readonlyInclude"]["bunfig.toml"]).toBe(true);
+    expect(after.startsWith("{\n  // lock\n  ")).toBe(true);
+    expect(after.endsWith('"editor.tabSize": 2 /* last */\n}\n')).toBe(true);
+  });
+
+  it("is stable: a second pass over its own output changes nothing", () => {
+    const first = settingsOf({ files: { ".vscode/settings.json": '{\n  // c\n  "a": 1\n}\n' } }, OUTPUTS);
+    expect(settingsOf({ files: { ".vscode/settings.json": first } }, OUTPUTS)).toBe(first);
+    const replaced = settingsOf(
+      { files: { ".vscode/settings.json": '{"files.readonlyInclude": {"x": true}}' } },
+      OUTPUTS,
+    );
+    expect(settingsOf({ files: { ".vscode/settings.json": replaced } }, OUTPUTS)).toBe(replaced);
+  });
+
+  it("keeps CRLF line endings of a file that uses them", () => {
+    const after = settingsOf({ files: { ".vscode/settings.json": '{\r\n  "a": 1\r\n}\r\n' } }, OUTPUTS);
+    expect(after.replaceAll("\r\n", "")).not.toContain("\n");
+  });
+
+  it("writes an empty map when there is no whole output", () => {
+    expect(settingsOf({}, [])).toBe('{\n  "files.readonlyInclude": {}\n}\n');
+  });
+
+  it("refuses a file that is not valid JSONC, naming the error and offset, and one that is no object", () => {
+    expect(run({ files: { ".vscode/settings.json": '{ "a": }' } }, []).errors).toEqual([
+      ".vscode/settings.json: invalid JSONC: ValueExpected at offset 7",
+    ]);
+    for (const text of ["[]", "1", "null"]) {
+      expect(run({ files: { ".vscode/settings.json": text } }, []).errors).toEqual([
+        ".vscode/settings.json: must hold a JSON object",
+      ]);
+    }
+  });
+});
+
+describe("the golden fixture's outputs", () => {
+  const goldens = [...readGoldens().keys()];
+  const outputs = goldens.map((rel) => file(rel, false));
+
+  it("are ignored by host dir, read-only by exact path, and marked generated by none (a consumer commits none)", () => {
+    const fixture = { hosts: [...HOSTS] };
+    expect(gitignoreOf(fixture, outputs)).toBe(
+      block("AGENTS.md", ".mcp.json", ".agents/", ".claude/", ".codex/", ".cursor/", ".grok/"),
+    );
+    expect(readonlyOf(settingsOf(fixture, outputs))).toEqual([...goldens].sort());
+    expect(gitattributesOf(fixture, outputs)).toBe(`${ATTR_HEAD}${IGNORE_END}`);
+  });
+
+  it("are marked generated one line each when the repo commits them", () => {
+    const tracked = goldens.map((rel) => file(rel, true));
+    const lines = gitattributesOf({ hosts: [...HOSTS] }, tracked).split("\n");
+    expect(lines.filter((line) => line.endsWith(" linguist-generated"))).toEqual(
+      [...goldens].sort().map((rel) => `${rel} linguist-generated`),
+    );
+  });
+});
+
+describe("listedFiles", () => {
+  it("lists tracked and untracked files git does not ignore, with extra ignore lines applied, sorted", () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-listed-"));
+    try {
+      execFileSync("git", ["init", "-q"], { cwd: root });
+      for (const rel of ["b.ts", "a/x.ts", "skip/y.ts", "ignored.log"]) {
+        fs.mkdirSync(path.dirname(path.join(root, rel)), { recursive: true });
+        fs.writeFileSync(path.join(root, rel), "x");
+      }
+      fs.writeFileSync(path.join(root, ".gitignore"), "*.log\n");
+      expect(listedFiles(root, ["skip/"])).toEqual([".gitignore", "a/x.ts", "b.ts"]);
+      expect(listedFiles(path.join(root, "missing"), [])).toBeNull();
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("package outputs", () => {
+  const packageOutputs = (tracked: boolean): Output[] => [
+    file("packages/web/AGENTS.md", tracked),
+    file("packages/web/CLAUDE.md", tracked),
+    link("packages/web/.claude/skills/deploy", tracked),
+    file(".claude/rules/packages/web/x.md", tracked),
+  ];
+
+  it("lists each untracked package output by its exact path, beside the collapsed host dir", () => {
+    expect(gitignoreOf({ hosts: ["claude"] }, packageOutputs(false))).toBe(
+      `${IGNORE_HEAD}node_modules/\npackages/web/.claude/skills/deploy\npackages/web/AGENTS.md\npackages/web/CLAUDE.md\n.claude/\n${IGNORE_END}`,
+    );
+  });
+
+  it("marks tracked package files generated and read-only by exact path, and ignores nothing", () => {
+    const outputs = packageOutputs(true);
+    expect(gitignoreOf({ name: "@workerstack/repo", hosts: ["claude"] }, outputs)).toBe(`${IGNORE_HEAD}${IGNORE_END}`);
+    expect(gitattributesOf({}, outputs)).toContain(
+      "packages/web/AGENTS.md linguist-generated\npackages/web/CLAUDE.md linguist-generated\n",
+    );
+    const readonly = parse(settingsOf({}, outputs))["files.readonlyInclude"] as Record<string, boolean>;
+    expect(readonly["packages/web/AGENTS.md"]).toBe(true);
+    expect(readonly["packages/web/CLAUDE.md"]).toBe(true);
+  });
+});

package/cli/sync/git-files.ts

@@ -0,0 +1,197 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { applyEdits, modify, parse, printParseErrorCode, type ParseError } from "jsonc-parser";
+import type { Host } from "../config.ts";
+import { mergeBlock } from "../scripts/managed-text.ts";
+import { HOST_TREES } from "./hosts.ts";
+import type { Output, SyncContext } from "./outputs.ts";
+import { KNIP_CONFIG_PATH, KNIP_UNIGNORED_GLOB } from "./knip-config.ts";
+import { OXLINT_CONFIG_PATH, UNSKIPPED_CONFIG_GLOB } from "./oxlint-config.ts";
+import { isSelfName } from "./stock.ts";
+import type { Workspace } from "./workspace.ts";
+
+/** What a pass over the generators' outputs returns: more outputs, or the errors that stopped it. */
+export type PostPass = (ctx: SyncContext, outputs: readonly Output[]) => { outputs: Output[]; errors: string[] };
+
+type FileOutput = Extract<Output, { kind: "file" }>;
+type Result = { outputs: Output[]; errors: string[] };
+
+const GITIGNORE_PATH = ".gitignore";
+const GITATTRIBUTES_PATH = ".gitattributes";
+const SETTINGS_PATH = ".vscode/settings.json";
+/** Every path the git files pass plans, for a pass that runs before it and must name them. */
+export const GIT_FILE_PATHS: readonly string[] = [GITIGNORE_PATH, GITATTRIBUTES_PATH, SETTINGS_PATH];
+const BLOCK_BEGIN = "# >>> @workerstack/repo";
+const BLOCK_END = "# <<< @workerstack/repo";
+const IGNORE_BASE = [".tmp/", ".worktrees/", ".repo/tmp/", "coverage/"];
+const DEPENDENCY_DIR = `${"node"}_modules/`;
+const ATTRIBUTES_BASE = "* text=auto eol=lf";
+const READONLY_KEY = "files.readonlyInclude";
+
+const byPath = (a: string, b: string) => Number(a > b) - Number(a < b);
+/** Sorts a leading dot away, so `AGENTS.md` stays before `.mcp.json` as the gitignore block always listed them. */
+const byName = (a: string, b: string) => byPath(a.replace(/^\./, ""), b.replace(/^\./, ""));
+
+/** The file outputs sync owns whole, which the user never writes into. */
+function wholeFiles(outputs: readonly Output[]): FileOutput[] {
+  return outputs.flatMap((output) => (output.kind === "file" && output.managed === "whole" ? [output] : []));
+}
+
+/**
+ * What git must ignore for the untracked whole outputs: an output under a dir an enabled host owns collapses to
+ * the outermost such dir, any other is listed as its exact path, and the oxlint and knip configs bring the
+ * pattern of their one-run copies. Files first, then dirs, each sorted.
+ */
+export function untrackedEntries(hosts: readonly Host[], outputs: readonly Output[]): string[] {
+  const owned = hosts.flatMap((host) => HOST_TREES[host].owns).sort((a, b) => a.length - b.length);
+  const entries = new Set<string>();
+  for (const output of outputs) {
+    if (output.tracked || output.managed !== "whole") continue;
+    entries.add(owned.find((dir) => output.path.startsWith(dir)) ?? output.path);
+  }
+  // `repo check` writes a skip-free copy beside the oxlint config for one run.
+  if (entries.has(OXLINT_CONFIG_PATH)) entries.add(UNSKIPPED_CONFIG_GLOB);
+  // `repo check` writes an ignore-free copy beside the knip config for one run.
+  if (entries.has(KNIP_CONFIG_PATH)) entries.add(KNIP_UNIGNORED_GLOB);
+  const all = [...entries];
+  return [
+    ...all.filter((entry) => !entry.endsWith("/")).sort(byName),
+    ...all.filter((entry) => entry.endsWith("/")).sort(byPath),
+  ];
+}
+
+/**
+ * The post-pass over the generators' outputs: the managed blocks of `.gitignore` and `.gitattributes`, and
+ * `files.readonlyInclude` in `.vscode/settings.json`. Block outputs are left out of all three.
+ */
+export const gitFiles: PostPass = (ctx, outputs) => {
+  const results = [gitignore(ctx, outputs), gitattributes(ctx, outputs), settings(ctx, outputs)];
+  return { outputs: results.flatMap((result) => result.outputs), errors: results.flatMap((result) => result.errors) };
+};
+
+/** A block output in `rel`: sync's `body` between the markers, the rest of the file as the user wrote it. */
+function blockFile(ctx: SyncContext, rel: string, body: string[]): Result {
+  const merged = mergeBlock(ctx.read(rel) ?? "", BLOCK_BEGIN, BLOCK_END, body.join("\n"));
+  if (!merged.ok) return { outputs: [], errors: [`${rel}: ${merged.error}`] };
+  return { outputs: [{ kind: "file", path: rel, content: merged.text, tracked: true, managed: "block" }], errors: [] };
+}
+
+/**
+ * The lines of the managed `.gitignore` block: the base entries, the dependency dir and what the untracked outputs
+ * need. This repo keeps its own dependency line outside the block and commits its trees, so its untracked list is empty.
+ */
+export function ignoreBlockLines(
+  name: string | undefined,
+  hosts: readonly Host[],
+  outputs: readonly Output[],
+): string[] {
+  const dependencies = isSelfName(name) ? [] : [DEPENDENCY_DIR];
+  return [...IGNORE_BASE, ...dependencies, ...untrackedEntries(hosts, outputs)];
+}
+
+function gitignore(ctx: SyncContext, outputs: readonly Output[]): Result {
+  return blockFile(
+    ctx,
+    GITIGNORE_PATH,
+    ignoreBlockLines(ctx.workspace.manifest.name, ctx.config.agents.hosts, outputs),
+  );
+}
+
+function gitattributes(ctx: SyncContext, outputs: readonly Output[]): Result {
+  const generated = wholeFiles(outputs)
+    .filter((output) => output.tracked)
+    .map((output) => output.path)
+    .sort(byPath);
+  return blockFile(ctx, GITATTRIBUTES_PATH, [ATTRIBUTES_BASE, ...generated.map((rel) => `${rel} linguist-generated`)]);
+}
+
+/** `files.readonlyInclude` set to every whole file output; the settings file's other keys and comments stay as written. */
+function settings(ctx: SyncContext, outputs: readonly Output[]): Result {
+  const existing = ctx.read(SETTINGS_PATH);
+  const fresh = (existing ?? "").trim() === "";
+  const text = fresh ? "{}" : (existing as string);
+  const problems: ParseError[] = [];
+  const value: unknown = parse(text, problems, { allowTrailingComma: true });
+  if (problems.length > 0) {
+    const { error, offset } = problems[0] as ParseError;
+    return {
+      outputs: [],
+      errors: [`${SETTINGS_PATH}: invalid JSONC: ${printParseErrorCode(error)} at offset ${offset}`],
+    };
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { outputs: [], errors: [`${SETTINGS_PATH}: must hold a JSON object`] };
+  }
+  const readonly = Object.fromEntries(
+    wholeFiles(outputs)
+      .map((output) => output.path)
+      .sort(byPath)
+      .map((rel) => [rel, true]),
+  );
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  // Inserted first, the new key leaves every neighbour's whitespace as written; appended, its formatting would rewrite the last one's.
+  const options = { formattingOptions: { insertSpaces: true, tabSize: 2, eol }, getInsertionIndex: () => 0 };
+  const edited = applyEdits(text, modify(text, [READONLY_KEY], readonly, options));
+  return {
+    outputs: [
+      {
+        kind: "file",
+        path: SETTINGS_PATH,
+        content: fresh ? `${edited}${eol}` : edited,
+        tracked: true,
+        managed: "block",
+      },
+    ],
+    errors: [],
+  };
+}
+
+/**
+ * Every file git sees under `root` (tracked, or untracked and not ignored) as sorted POSIX paths, with the
+ * `extraIgnores` lines applied on top of the ignore files already there. A deleted tracked file stays in the index,
+ * so it is listed too. Null outside a git repo or when git fails.
+ */
+export function listedFiles(root: string, extraIgnores: readonly string[]): string[] | null {
+  try {
+    const listed = execFileSync(
+      "git",
+      ["ls-files", "--cached", "--others", "--exclude-standard", ...extraIgnores.flatMap((line) => ["-x", line]), "-z"],
+      {
+        cwd: root,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      },
+    );
+    // An unmerged path is listed once per stage.
+    return [...new Set(listed.split("\0").filter((rel) => rel !== ""))].sort(byPath);
+  } catch {
+    return null;
+  }
+}
+
+const NESTED_IGNORE = "ignore rules live in the root .gitignore (or a public package's own); move them there";
+const NPM_IGNORE = 'npm reads package.json "files"; delete it';
+
+/**
+ * One `path: reason` line per ignore file git sees (tracked, or untracked and not ignored) that sync refuses: a
+ * `.gitignore` below the root outside a public package's root (its package.json lacks `"private": true`), and any
+ * `.npmignore`. `ignored` are the lines of the `.gitignore` block sync is about to write, which git applies on top of
+ * the ignore files already there, so a new repo is not judged by what its first sync would ignore. None outside a
+ * git repo or when git fails.
+ */
+export function strayIgnoreFiles(root: string, workspace: Workspace, ignored: readonly string[]): string[] {
+  const listed = listedFiles(root, ignored);
+  if (listed === null) return [];
+  const publicRoots = new Set(workspace.packages.filter((pkg) => pkg.manifest.private !== true).map((pkg) => pkg.dir));
+  const lines: string[] = [];
+  for (const rel of listed) {
+    const name = path.posix.basename(rel);
+    const nested =
+      name === ".gitignore" && path.posix.dirname(rel) !== "." && !publicRoots.has(path.posix.dirname(rel));
+    if ((name === ".npmignore" || nested) && fs.existsSync(path.join(root, rel))) {
+      lines.push(`${rel}: ${name === ".npmignore" ? NPM_IGNORE : NESTED_IGNORE}`);
+    }
+  }
+  return lines;
+}

package/cli/sync/git-hooks.test.ts

@@ -0,0 +1,94 @@
+import { BASE_CONFIG } from "../fixtures/base-config.ts";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, expect, it } from "vitest";
+import type { Output, SyncContext } from "./outputs.ts";
+import { runGit, standards } from "./standards.ts";
+import { readEnv } from "../env.ts";
+
+/** The git hooks the standards pass plans, and the git runner behind `core.hooksPath`. */
+const temps: string[] = [];
+afterEach(() => {
+  for (const dir of temps.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function tempDir(): string {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-githook-")));
+  temps.push(dir);
+  return dir;
+}
+
+function context(packs: SyncContext["config"]["packs"], read: SyncContext["read"] = () => null): SyncContext {
+  return {
+    root: "/repo",
+    config: {
+      packs,
+      agents: { hosts: [], skills: [] },
+      ...BASE_CONFIG,
+    },
+    workspace: { root: "/repo", manifest: { name: "app" }, packages: [] },
+    read,
+  };
+}
+
+const hooks = (ctx: SyncContext): Output[] =>
+  standards(ctx, []).outputs.filter((output) => output.path.startsWith(".githooks/"));
+
+/** Runs a planned hook with `sh` at a top level that holds a fake bin, the way git runs it, with an agent env set. */
+function runHook(name: string, ...args: string[]) {
+  const root = tempDir();
+  fs.mkdirSync(path.join(root, "node_modules", ".bin"), { recursive: true });
+  fs.writeFileSync(path.join(root, "node_modules", ".bin", "repo"), '#!/bin/sh\necho "repo $@"\n', { mode: 0o755 });
+  const hook = hooks(context(["standards"])).find((output) => output.path === `.githooks/${name}`);
+  if (hook?.kind !== "file") throw new Error(`no hook ${name}`);
+  fs.writeFileSync(path.join(root, "hook"), hook.content);
+  const env = { PATH: readEnv().PATH, CLAUDE_PROJECT_DIR: "/nowhere" };
+  return spawnSync("sh", ["hook", ...args], { cwd: root, env, encoding: "utf8" });
+}
+
+it("plans pre-commit and commit-msg as tracked, executable files sync owns, and none without the pack", () => {
+  const shapes = hooks(context(["standards"])).map((output) => ({
+    path: output.path,
+    tracked: output.tracked,
+    managed: output.managed,
+    executable: output.kind === "file" && output.executable === true,
+  }));
+  expect(shapes).toEqual([
+    { path: ".githooks/commit-msg", tracked: true, managed: "whole", executable: true },
+    { path: ".githooks/pre-commit", tracked: true, managed: "whole", executable: true },
+  ]);
+  expect(hooks(context(["agents", "docs"]))).toEqual([]);
+});
+
+it("pre-commit runs repo turn --staged from the bin of the checkout git runs it in", () => {
+  const r = runHook("pre-commit");
+  expect(r.stderr).toBe("");
+  expect(r.stdout).toBe("repo turn --staged\n");
+});
+
+it("commit-msg runs repo commit-msg on the message file git passes", () => {
+  expect(runHook("commit-msg", ".git/COMMIT_EDITMSG").stdout).toBe("repo commit-msg .git/COMMIT_EDITMSG\n");
+});
+
+it("refuses a hand-written hook at either path, and replaces one it generated", () => {
+  const at = (text: string) => (rel: string) => (rel === ".githooks/pre-commit" ? text : null);
+  expect(standards(context(["standards"], at("#!/bin/sh\nnpx lint-staged\n")), [])).toEqual({
+    outputs: [],
+    errors: [".githooks/pre-commit is hand-written; delete it so repo sync can own it"],
+  });
+  const generated = at("#!/bin/sh\n# Generated by repo sync. Do not edit.\nold\n");
+  expect(standards(context(["standards"], generated), []).errors).toEqual([]);
+});
+
+it("runGit returns git's output, or a null status with the reason when git cannot start", () => {
+  const root = tempDir();
+  const version = runGit(root, ["--version"]);
+  expect(version.status).toBe(0);
+  expect(version.stdout).toMatch(/^git version /);
+  expect(runGit(root, ["hash-object", "--stdin"], "x").stdout).toBe("c1b0730e0133447badcfd47fd144e254807b06e1\n");
+  const missing = runGit(path.join(root, "missing"), ["--version"]);
+  expect(missing).toMatchObject({ status: null, stdout: "" });
+  expect(missing.stderr).toMatch(/ENOENT/);
+});