@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/sync/trees.ts

@@ -0,0 +1,280 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { SKILL_PACKS } from "../config.ts";
+import { emitAgentShellTools } from "../scripts/emit-agent-shell-tools.ts";
+import { emitMcpPolicy } from "../scripts/emit-mcp-policy.ts";
+import { expandHookCommand } from "../scripts/hook-command.ts";
+import { applyUnion } from "../scripts/hooks-union.ts";
+import { WORKSPACE_SKILLS_REL, STOCK_SKILLS_REL, listSkillDirNames } from "../scripts/skill-conflicts.ts";
+import { renderTasks } from "../scripts/vscode-tasks.ts";
+import { renderHooks } from "./agents/hooks.ts";
+import { renderRules, type RuleFile } from "./agents/rules.ts";
+import { loadSources, type Sources } from "./agents/sources.ts";
+import { renderSubagents } from "./agents/subagents.ts";
+import { listedFiles } from "./git-files.ts";
+import { isHostOutput } from "./hosts.ts";
+import type { Output, SyncContext } from "./outputs.ts";
+import { repoDirProblems } from "./repo-dir.ts";
+import { isSelfName, stockRoot } from "./stock.ts";
+
+/** The outputs, or every problem found, one per entry. */
+export type TreesResult = { ok: true; outputs: Output[] } | { ok: false; errors: string[] };
+
+/** Several source problems at once, so a render reports each instead of the first. */
+class Problems extends Error {
+  readonly problems: string[];
+
+  constructor(problems: string[]) {
+    super(problems.join("\n"));
+    this.problems = problems;
+  }
+}
+
+const STAGE_DIR_REL = ".repo/tmp";
+const STAGE_PREFIX = "stage-";
+const CLAUDE_SETTINGS_REL = ".claude/settings.json";
+const CLAUDE_OVERLAY_REL = ".repo/settings/claude.json";
+const MCP_REL = ".mcp.json";
+const MCP_OVERLAY_REL = ".repo/mcp.json";
+const CLAUDE_BASE_REL = "agents/settings/claude.json";
+const TASKS_REL = ".vscode/tasks.json";
+const OVERLAY_SKILLS_REL = ".repo/skills";
+/** Each stock dir of static grok files, and the tree dir it is copied to. */
+const STATIC_ROOTS = [
+  ["agents/grok/roles", ".grok/roles"],
+  ["agents/grok/hooks", ".grok/hooks"],
+] as const;
+
+/** `over` onto `base`: objects merge key by key, lists append what they lack, anything else is replaced. */
+function mergeSettings(base: unknown, over: unknown): unknown {
+  if (Array.isArray(base) && Array.isArray(over)) {
+    return [...base, ...over.filter((item) => !base.some((have) => isDeepStrictEqual(have, item)))];
+  }
+  if (isObject(base) && isObject(over)) {
+    const merged: Record<string, unknown> = { ...base };
+    for (const [key, value] of Object.entries(over))
+      merged[key] = key in base ? mergeSettings(base[key], value) : value;
+    return merged;
+  }
+  return over;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Throws the step's error, so one handler reports a failed emit step like a failed generator. */
+function must(step: string, result: { ok: boolean; error?: string }): void {
+  if (!result.ok) throw new Error(`${step}: ${result.error}`);
+}
+
+/** Every file under `dir`, as POSIX paths relative to it. */
+function filesUnder(dir: string): string[] {
+  return fs
+    .readdirSync(dir, { recursive: true, encoding: "utf8" })
+    .map((rel) => rel.replaceAll("\\", "/"))
+    .filter((rel) => fs.statSync(path.join(dir, rel)).isFile());
+}
+
+/** The stock files no generator writes: grok's roles and hook configs. */
+function staticFiles(stock: string): Map<string, string> {
+  const files = new Map<string, string>();
+  for (const [from, to] of STATIC_ROOTS) {
+    for (const rel of filesUnder(path.join(stock, from))) {
+      const text = fs.readFileSync(path.join(stock, from, rel), "utf8");
+      files.set(
+        `${to}/${rel}`,
+        text.replace(
+          /("command": )("repo hook [\w-]+")/g,
+          (_, key, value) => key + JSON.stringify(expandHookCommand(String(JSON.parse(value)))),
+        ),
+      );
+    }
+  }
+  return files;
+}
+
+function posix(rel: string): string {
+  return rel.split(path.sep).join("/");
+}
+
+/** The skill links for `hosts`: `.agents/skills` for codex and antigravity, `.claude/skills` for claude. */
+function skillLinks(ctx: SyncContext, stock: string, self: boolean): Output[] {
+  const { hosts, skills } = ctx.config.agents;
+  const own = self ? [] : listSkillDirNames(path.join(ctx.root, OVERLAY_SKILLS_REL));
+  const optional = new Set<string>(SKILL_PACKS.filter((pack) => !skills.includes(pack)));
+  const stockNames = listSkillDirNames(path.join(stock, STOCK_SKILLS_REL)).filter((name) => !optional.has(name));
+  const names = [...new Set([...stockNames, ...own])].sort();
+  const sourceOf = (name: string) =>
+    own.includes(name) ? path.join(ctx.root, OVERLAY_SKILLS_REL, name) : path.join(stock, STOCK_SKILLS_REL, name);
+  const agentsDir = hosts.includes("codex") || hosts.includes("antigravity");
+  const links: Output[] = [];
+  const add = (dir: string, name: string, target: string) =>
+    links.push({ kind: "link", path: `${dir}/${name}`, target, tracked: self, managed: "whole" });
+  for (const name of names) {
+    if (agentsDir)
+      add(WORKSPACE_SKILLS_REL, name, posix(path.relative(path.join(ctx.root, WORKSPACE_SKILLS_REL), sourceOf(name))));
+    if (hosts.includes("claude")) {
+      const target =
+        agentsDir && !self
+          ? `../../${WORKSPACE_SKILLS_REL}/${name}`
+          : posix(path.relative(path.join(ctx.root, ".claude/skills"), sourceOf(name)));
+      add(".claude/skills", name, target);
+    }
+  }
+  return [...links, ...packageSkillLinks(ctx, self)];
+}
+
+/**
+ * Each workspace package's own skills, linked straight to `<pkg>/.repo/skills/<name>` from the dirs its hosts read:
+ * `<pkg>/.claude/skills` for claude (which names them `/<pkg>:<name>`), `<pkg>/.agents/skills` for codex and antigravity.
+ */
+function packageSkillLinks(ctx: SyncContext, self: boolean): Output[] {
+  const { hosts } = ctx.config.agents;
+  const agentsDir = hosts.includes("codex") || hosts.includes("antigravity");
+  const dirs = [...(hosts.includes("claude") ? [".claude/skills"] : []), ...(agentsDir ? [".agents/skills"] : [])];
+  return ctx.workspace.packages.flatMap(({ dir }) =>
+    listSkillDirNames(path.join(ctx.root, dir, OVERLAY_SKILLS_REL)).flatMap((name): Output[] =>
+      dirs.map((host) => ({
+        kind: "link",
+        path: `${dir}/${host}/${name}`,
+        target: `../../${OVERLAY_SKILLS_REL}/${name}`,
+        tracked: self,
+        managed: "whole",
+      })),
+    ),
+  );
+}
+
+/**
+ * The rule files of the root and of every workspace package, each scope rendered on its own so no package rule folds
+ * into the root `AGENTS.md`, and one problem line for each path two scopes plan.
+ */
+function renderScopes(ctx: SyncContext, sources: Sources): { files: Map<string, string>; clashes: string[] } {
+  const { hosts } = ctx.config.agents;
+  const planned = new Map<string, RuleFile>();
+  const clashes: string[] = [];
+  for (const scope of ["", ...ctx.workspace.packages.map((pkg) => pkg.dir)]) {
+    for (const [rel, file] of renderRules(sources.rules, hosts, scope)) {
+      const first = planned.get(rel);
+      if (first === undefined) planned.set(rel, file);
+      else clashes.push(`${rel}: planned by ${first.source} and ${file.source}; rename one`);
+    }
+  }
+  return { files: new Map([...planned].map(([rel, file]) => [rel, file.text])), clashes };
+}
+
+/** Deep-merges the overlay file `overlayRel` (when it exists) over the staged JSON file `rel`. */
+function mergeOverlay(ctx: SyncContext, stage: string, rel: string, overlayRel: string): void {
+  const overlay = ctx.read(overlayRel);
+  if (overlay === null) return;
+  let own: unknown;
+  try {
+    own = JSON.parse(overlay);
+  } catch (error) {
+    throw new Error(`${overlayRel}: ${(error as Error).message}`);
+  }
+  if (!isObject(own)) throw new Error(`${overlayRel}: must be a JSON object`);
+  const file = path.join(stage, rel);
+  const base: unknown = JSON.parse(fs.readFileSync(file, "utf8"));
+  fs.writeFileSync(file, `${JSON.stringify(mergeSettings(base, own), null, 2)}\n`);
+}
+
+/** Fills the stage: rules, subagents and hooks, the emit steps, the claude overlay and the static files; returns its files. */
+function fillStage(
+  ctx: SyncContext,
+  stage: string,
+  stock: string,
+  sources: Sources,
+  rules: Map<string, string>,
+): Map<string, string> {
+  const { hosts } = ctx.config.agents;
+  const claudeBase = fs.readFileSync(path.join(stock, CLAUDE_BASE_REL), "utf8");
+  const generated = [rules, renderSubagents(sources, hosts), renderHooks(sources, hosts, claudeBase)];
+  for (const [rel, text] of generated.flatMap((files) => [...files])) {
+    fs.mkdirSync(path.dirname(path.join(stage, rel)), { recursive: true });
+    fs.writeFileSync(path.join(stage, rel), text);
+  }
+
+  must("mcp policy", emitMcpPolicy({ workspaceRoot: stage, sourceRoot: stock, consumerRoot: ctx.root }));
+  if (hosts.includes("claude")) {
+    must("scout tools", emitAgentShellTools({ workspaceRoot: stage, sourceRoot: stock }));
+  }
+  must("hooks", applyUnion({ workspaceRoot: stage, sourceRoot: stock, consumerRoot: ctx.root }));
+
+  if (hosts.includes("claude")) {
+    mergeOverlay(ctx, stage, CLAUDE_SETTINGS_REL, CLAUDE_OVERLAY_REL);
+    mergeOverlay(ctx, stage, MCP_REL, MCP_OVERLAY_REL);
+  }
+
+  const files = new Map<string, string>();
+  for (const rel of filesUnder(stage)) files.set(rel, fs.readFileSync(path.join(stage, rel), "utf8"));
+  if (hosts.includes("grok")) for (const [rel, text] of staticFiles(stock)) files.set(rel, text);
+  return files;
+}
+
+/**
+ * Every generated agent tree for the enabled hosts as outputs, built in a fresh `.repo/tmp/stage-*` dir (removed again) from
+ * the stock package plus the `.repo/` overlay. Nothing outside the stage is written. In a consumer the trees are
+ * ignored (`tracked: false`); in this repo they are the committed trees; `.vscode/tasks.json` is committed in both.
+ */
+export function renderTrees(ctx: SyncContext): TreesResult {
+  const { hosts } = ctx.config.agents;
+  if (hosts.length === 0) return { ok: true, outputs: [] };
+  const self = isSelfName(ctx.workspace.manifest.name);
+  const stock = self ? ctx.root : stockRoot(ctx.root);
+  if (!fs.existsSync(path.join(stock, "agents"))) {
+    return {
+      ok: false,
+      errors: [`${path.relative(ctx.root, stock).split(path.sep).join("/")} is missing; run \`bun install\``],
+    };
+  }
+
+  // One stage per call: processes rendering the same root at once (parallel test files, two syncs) must not clear each other's.
+  fs.mkdirSync(path.join(ctx.root, STAGE_DIR_REL), { recursive: true });
+  const stage = fs.mkdtempSync(path.join(ctx.root, STAGE_DIR_REL, STAGE_PREFIX));
+  let result: TreesResult;
+  try {
+    result = { ok: true, outputs: assemble(ctx, stage, stock, self) };
+  } catch (error) {
+    result = { ok: false, errors: error instanceof Problems ? error.problems : [(error as Error).message] };
+  }
+  fs.rmSync(stage, { recursive: true, force: true });
+  return result;
+}
+
+/** The stage's host files, the skill links and the tasks file, sorted by path. */
+function assemble(ctx: SyncContext, stage: string, stock: string, self: boolean): Output[] {
+  const { hosts } = ctx.config.agents;
+  const outputs: Output[] = [];
+  const packages = ctx.workspace.packages.map((pkg) => pkg.dir);
+  const { sources, problems: loadProblems } = loadSources({
+    stockRoot: stock,
+    consumerRoot: self ? null : ctx.root,
+    packages,
+  });
+  // The checks run on the docs that loaded, so one bad file does not hide the problems of the others.
+  const rules = renderScopes(ctx, sources);
+  const problems = [
+    ...repoDirProblems(ctx.root, {
+      sources,
+      stock,
+      listed: listedFiles(ctx.root, []),
+      skills: ctx.config.agents.skills,
+      packages,
+    }),
+    ...loadProblems,
+    ...rules.clashes,
+  ];
+  if (problems.length > 0) throw new Problems(problems);
+  const files = fillStage(ctx, stage, stock, sources, rules.files);
+  for (const [rel, content] of files) {
+    if (isHostOutput(hosts, rel)) outputs.push({ kind: "file", path: rel, content, tracked: self, managed: "whole" });
+  }
+  outputs.push(...skillLinks(ctx, stock, self));
+  const tasks = renderTasks(ctx.root, ctx.read(TASKS_REL));
+  if (!tasks.ok) throw new Error(tasks.error);
+  outputs.push({ kind: "file", path: TASKS_REL, content: tasks.text, tracked: true, managed: "whole" });
+  return outputs.sort((a, b) => Number(a.path > b.path) - Number(a.path < b.path));
+}

package/cli/sync/validate.test.ts

@@ -0,0 +1,299 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+import { readGoldens, renderFixtureTrees } from "../../dev/capture-tree-goldens.ts";
+import { loadConfig } from "../config.ts";
+import { computeOutputs } from "../sync.ts";
+import type { Output } from "./outputs.ts";
+import { OXFMT_CONFIG, OXLINT_CONFIG, validateOutputs } from "./validate.ts";
+import { readWorkspace } from "./workspace.ts";
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const SLOW = 60_000;
+
+const tmpDirs: string[] = [];
+afterEach(() => {
+  for (const dir of tmpDirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function tmpRoot(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-validate-"));
+  tmpDirs.push(dir);
+  return dir;
+}
+
+const file = (p: string, content: string): Output => ({
+  kind: "file",
+  path: p,
+  content,
+  tracked: true,
+  managed: "whole",
+});
+const link = (p: string, target: string): Output => ({
+  kind: "link",
+  path: p,
+  target,
+  tracked: true,
+  managed: "whole",
+});
+const AGENT = "---\nname: scout\ndescription: Facts only.\n---\nBody\n";
+
+describe("file formats", () => {
+  it("accepts well-formed json, toml, markdown and text", () => {
+    const root = tmpRoot();
+    const outputs = [
+      file(".vscode/tasks.json", "{}\n"),
+      file("knip.json", "{}\n"),
+      file("bunfig.toml", '[install]\nlinker = "hoisted"\n'),
+      file("AGENTS.md", "# Plain markdown\n"),
+      file("references/INDEX.md", "---\n---\nEmpty frontmatter\n"),
+      file(".gitignore", "anything\n"),
+      file(".claude/agents/scout.md", AGENT),
+      file(".claude/agents/crlf.md", "---\r\nname: a\r\ndescription: b\r\n---\r\nBody\r\n"),
+    ];
+    expect(validateOutputs(root, outputs)).toEqual([]);
+  });
+
+  it("reports bad JSON with the parser's message", () => {
+    const lines = validateOutputs(tmpRoot(), [file(".vscode/tasks.json", "{ nope")]);
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toMatch(/^\.vscode\/tasks\.json: invalid JSON: /);
+    expect(validateOutputs(tmpRoot(), [file("knip.json", "{ nope")])[0]).toMatch(/^knip\.json: invalid JSON: /);
+  });
+
+  it("accepts a commented JSONC settings file with a trailing comma, and a .gitattributes and ci.yml as text", () => {
+    const text = '// editor\n{\n  /* mine */ "editor.tabSize": 2,\n  "files.readonlyInclude": { "a": true, },\n}\n';
+    expect(
+      validateOutputs(tmpRoot(), [
+        file(".vscode/settings.json", text),
+        file(".gitattributes", "* text=auto\n"),
+        file(".github/workflows/ci.yml", "name: ci\n"),
+        file(".github/workflows/release.yml", "name: release\n"),
+      ]),
+    ).toEqual([]);
+  });
+
+  it("reports bad JSONC with the parser's error code and offset", () => {
+    expect(validateOutputs(tmpRoot(), [file(".vscode/settings.json", '{ "a": }')])).toEqual([
+      ".vscode/settings.json: invalid JSONC: ValueExpected at offset 7",
+    ]);
+  });
+
+  it("reports bad TOML with the parser's message", () => {
+    const lines = validateOutputs(tmpRoot(), [file("bunfig.toml", "[install\nx = ")]);
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toMatch(/^bunfig\.toml: invalid TOML: /);
+  });
+
+  it("reports bad YAML frontmatter", () => {
+    const lines = validateOutputs(tmpRoot(), [file("AGENTS.md", "---\nname: [unclosed\n---\nBody\n")]);
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toMatch(/^AGENTS\.md: invalid frontmatter: /);
+  });
+
+  it("reports frontmatter that is not closed", () => {
+    expect(validateOutputs(tmpRoot(), [file("AGENTS.md", "---\nname: a\nBody\n")])).toEqual([
+      "AGENTS.md: invalid frontmatter: no closing ---",
+    ]);
+  });
+
+  it("reports frontmatter that is not a mapping", () => {
+    expect(validateOutputs(tmpRoot(), [file("AGENTS.md", "---\n- a\n- b\n---\nBody\n")])).toEqual([
+      "AGENTS.md: invalid frontmatter: must be a mapping",
+    ]);
+  });
+
+  it("checks agent frontmatter against its schema", () => {
+    const lines = validateOutputs(tmpRoot(), [
+      file(".cursor/agents/a.md", "---\nname: a\n---\nBody\n"),
+      file(".grok/agents/b.md", "No frontmatter at all\n"),
+    ]);
+    expect(lines).toEqual([
+      ".cursor/agents/a.md: description: Invalid input: expected string, received undefined",
+      ".grok/agents/b.md: name: Invalid input: expected string, received undefined",
+      ".grok/agents/b.md: description: Invalid input: expected string, received undefined",
+    ]);
+  });
+
+  it("reports a schema miss with its dotted path and zod's message", () => {
+    const settings = JSON.stringify({ hooks: { PreToolUse: "x" } });
+    expect(validateOutputs(tmpRoot(), [file(".claude/settings.json", settings)])).toEqual([
+      ".claude/settings.json: hooks.PreToolUse: Invalid input: expected array, received string",
+    ]);
+  });
+
+  it("reports a schema miss at the top level without a dotted path", () => {
+    expect(validateOutputs(tmpRoot(), [file(".mcp.json", "[]")])).toEqual([
+      ".mcp.json: Invalid input: expected object, received array",
+    ]);
+  });
+
+  it("reports indexes in a dotted path", () => {
+    const settings = JSON.stringify({ hooks: { Stop: [{ hooks: [{ command: 1 }] }] } });
+    const lines = validateOutputs(tmpRoot(), [file(".claude/settings.json", settings)]);
+    expect(lines).toContain(
+      ".claude/settings.json: hooks.Stop.0.hooks.0.type: Invalid input: expected string, received undefined",
+    );
+  });
+
+  it("accepts keys the host may add", () => {
+    const hooks = {
+      hooks: { Stop: [{ future: 1, hooks: [{ type: "prompt", prompt: "x", timeout: 5, extra: true }] }] },
+      other: 1,
+    };
+    const outputs = [
+      file(".claude/settings.json", JSON.stringify({ ...hooks, permissions: { deny: ["x"], allow: [] } })),
+      file(".codex/hooks.json", JSON.stringify(hooks)),
+      file(
+        ".cursor/hooks.json",
+        JSON.stringify({ version: 1, hooks: { stop: [{ type: "command", command: "x", matcher: "y", extra: 1 }] } }),
+      ),
+      file(
+        ".agents/hooks.json",
+        JSON.stringify({ rulesync: { Stop: [{ command: "x" }, { matcher: "m", hooks: [{ type: "command" }] }] } }),
+      ),
+      file(".agents/mcp_config.json", JSON.stringify({ mcpServers: { a: { command: "x" } } })),
+      file(".grok/hooks/rtk.json", JSON.stringify(hooks)),
+    ];
+    expect(validateOutputs(tmpRoot(), outputs)).toEqual([]);
+  });
+
+  it("accepts the empty hook files the generators emit", () => {
+    const outputs = [
+      file(".agents/hooks.json", "{}"),
+      file(".grok/hooks/rulesync.json", '{"hooks":{}}'),
+      file(".mcp.json", '{"mcpServers":{}}'),
+    ];
+    expect(validateOutputs(tmpRoot(), outputs)).toEqual([]);
+  });
+
+  it("refuses a file path with no registered format", () => {
+    expect(validateOutputs(tmpRoot(), [file("docs/x.yaml", "a: 1\n")])).toEqual([
+      "docs/x.yaml: no output format registered; add it to cli/sync/validate.ts",
+    ]);
+  });
+
+  it("reports every problem, in output order", () => {
+    const lines = validateOutputs(tmpRoot(), [file("b.yaml", ""), file(".vscode/tasks.json", "{"), file("a.yaml", "")]);
+    expect(lines.map((line) => line.split(":")[0])).toEqual(["b.yaml", ".vscode/tasks.json", "a.yaml"]);
+  });
+});
+
+describe("the standards configs", () => {
+  /** The top-level keys the pinned tool's shipped JSON schema allows. */
+  function shippedKeys(tool: "oxlint" | "oxfmt"): string[] {
+    const dir = path.dirname(Bun.resolveSync(`${tool}/package.json`, import.meta.dirname));
+    const schema = JSON.parse(fs.readFileSync(path.join(dir, "configuration_schema.json"), "utf8")) as {
+      properties: Record<string, unknown>;
+    };
+    return Object.keys(schema.properties).sort();
+  }
+
+  it("checks each config against every top-level key its tool allows, and only those", () => {
+    expect(Object.keys(OXLINT_CONFIG.shape).sort()).toEqual(shippedKeys("oxlint"));
+    expect(Object.keys(OXFMT_CONFIG.shape).sort()).toEqual(shippedKeys("oxfmt"));
+  });
+
+  it("accepts a commented oxfmt config and a plain oxlint config", () => {
+    const outputs = [
+      file(".oxlintrc.json", JSON.stringify({ plugins: ["eslint"], rules: { "eslint/no-console": ["error", {}] } })),
+      file(".oxfmtrc.jsonc", '// generated\n{ "printWidth": 120, "ignorePatterns": ["/a"], }\n'),
+    ];
+    expect(validateOutputs(tmpRoot(), outputs)).toEqual([]);
+  });
+
+  it("refuses a key neither tool knows", () => {
+    const lines = validateOutputs(tmpRoot(), [
+      file(".oxlintrc.json", '{ "rulez": {} }'),
+      file(".oxfmtrc.jsonc", '{ "width": 120 }'),
+    ]);
+    expect(lines).toHaveLength(2);
+    expect(lines[0]).toMatch(/^\.oxlintrc\.json: .*"rulez"/);
+    expect(lines[1]).toMatch(/^\.oxfmtrc\.jsonc: .*"width"/);
+  });
+});
+
+describe("links", () => {
+  it("accepts a link to a path on disk, relative or absolute", () => {
+    const root = tmpRoot();
+    fs.mkdirSync(path.join(root, "agents/skills/ask"), { recursive: true });
+    const outputs = [
+      link(".agents/skills/ask", "../../agents/skills/ask"),
+      link(".agents/skills/abs", path.join(root, "agents/skills/ask")),
+    ];
+    expect(validateOutputs(root, outputs)).toEqual([]);
+  });
+
+  it("reports a dangling link", () => {
+    expect(validateOutputs(tmpRoot(), [link(".agents/skills/ask", "../../agents/skills/ask")])).toEqual([
+      ".agents/skills/ask: link target ../../agents/skills/ask does not exist",
+    ]);
+  });
+
+  it("reports a link that leaves the repo for a missing path", () => {
+    const lines = validateOutputs(tmpRoot(), [link("a/b", "../../../no-such-dir-workerstack")]);
+    expect(lines).toEqual(["a/b: link target ../../../no-such-dir-workerstack does not exist"]);
+  });
+
+  it("follows a link whose target is another planned link into an existing dir", () => {
+    const root = tmpRoot();
+    fs.mkdirSync(path.join(root, ".repo/skills/x"), { recursive: true });
+    const outputs = [
+      link(".claude/skills/x", "../../.agents/skills/x"),
+      link(".agents/skills/x", "../../.repo/skills/x"),
+    ];
+    expect(validateOutputs(root, outputs)).toEqual([]);
+    expect(validateOutputs(root, [...outputs].reverse())).toEqual([]);
+  });
+
+  it("reports a chain of planned links that ends in nothing", () => {
+    const outputs = [
+      link(".claude/skills/x", "../../.agents/skills/x"),
+      link(".agents/skills/x", "../../.repo/skills/x"),
+    ];
+    expect(validateOutputs(tmpRoot(), outputs)).toEqual([
+      ".claude/skills/x: link target ../../.agents/skills/x does not exist",
+      ".agents/skills/x: link target ../../.repo/skills/x does not exist",
+    ]);
+  });
+
+  it("reports planned links that point at each other", () => {
+    const outputs = [link("a", "b"), link("b", "a")];
+    expect(validateOutputs(tmpRoot(), outputs)).toEqual([
+      "a: link target b does not exist",
+      "b: link target a does not exist",
+    ]);
+  });
+
+  it("accepts a link into a planned dir that is not on disk yet", () => {
+    const outputs = [link(".claude/skills/x", "../../.codex/agents"), file(".codex/agents/a.toml", 'name = "a"\n')];
+    expect(validateOutputs(tmpRoot(), outputs)).toEqual([]);
+  });
+
+  it("checks files against the formats it is given", () => {
+    const formats = [{ match: () => true, format: "text" as const }];
+    expect(validateOutputs(tmpRoot(), [file("docs/x.yaml", "a: 1\n")], formats)).toEqual([]);
+  });
+});
+
+describe("registered formats", () => {
+  it("accepts every output of the golden consumer fixture", { timeout: SLOW }, async () => {
+    const rendered = await renderFixtureTrees();
+    expect([...rendered.keys()]).toEqual([...readGoldens().keys()]);
+    const outputs = [...rendered].map(([rel, content]) => file(rel, content));
+    expect(outputs.length).toBeGreaterThan(30);
+    expect(validateOutputs(tmpRoot(), outputs)).toEqual([]);
+  });
+
+  it("accepts every output this repo plans", { timeout: SLOW }, async () => {
+    const config = await loadConfig(REPO_ROOT);
+    const workspace = readWorkspace(REPO_ROOT);
+    if (!config.ok || !workspace.ok) throw new Error("this repo's config or workspace did not load");
+    const planned = computeOutputs(REPO_ROOT, config.config, workspace.workspace);
+    if (!planned.ok) throw new Error(planned.errors.join("\n"));
+    expect(planned.outputs.length).toBeGreaterThan(100);
+    expect(validateOutputs(REPO_ROOT, planned.outputs)).toEqual([]);
+  });
+});