@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/sync/nightly-jobs.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import { context } from "../fixtures/release-context.ts";
+import { nightly } from "./nightly.ts";
+import type { SyncContext } from "./outputs.ts";
+
+/** The nightly.yml text for `shards`, `secrets` and a root manifest with or without `test:live`. */
+function render(shards: number, secrets: string[] = [], live = false): string {
+  const base = context(["release"], live ? { scripts: { "test:live": "vitest run -c live.config.ts" } } : {});
+  const ctx: SyncContext = { ...base, config: { ...base.config, nightly: { shards, secrets } } };
+  const [output] = nightly(ctx).outputs;
+  if (output?.kind !== "file") throw new Error("no nightly.yml");
+  return output.content;
+}
+
+const liveJob = (text: string) => text.slice(text.indexOf("  live:"));
+
+describe("nightly jobs", () => {
+  it("fans the mutate job out over every shard of the config", () => {
+    const text = render(8);
+    expect(text).toContain("name: mutate (${{ matrix.shard }}/8)");
+    expect(text).toContain("shard: [1, 2, 3, 4, 5, 6, 7, 8]");
+    expect(text).toContain('run: bun repo mutate --shard "$SHARD/8" --report "mutation-$SHARD.json"');
+  });
+
+  it("names each upload by its shard and downloads by the same prefix", () => {
+    const text = render(3);
+    expect(text).toContain("name: mutation-${{ matrix.shard }}\n          path: mutation-${{ matrix.shard }}.json");
+    expect(text).toContain("pattern: mutation-*\n          merge-multiple: true");
+  });
+});
+
+describe("nightly live job", () => {
+  it("has no live job without a test:live script, secrets or not", () => {
+    expect(render(1)).not.toContain("live");
+    expect(render(1, ["API_TOKEN"])).not.toContain("live");
+  });
+
+  it("adds a live job with a 40-minute limit that runs test:live", () => {
+    const job = liveJob(render(1, [], true));
+    expect(job).toContain("timeout-minutes: 40");
+    expect(job).toContain("      - run: bun run test:live\n");
+    expect(job).not.toContain("env:");
+    expect(job).not.toContain("needs:");
+  });
+
+  it("maps each secret by name in the live job's env, never inside run", () => {
+    const job = liveJob(render(1, ["API_TOKEN", "OTHER_KEY"], true));
+    expect(job).toContain(
+      "    env:\n      API_TOKEN: ${{ secrets.API_TOKEN }}\n      OTHER_KEY: ${{ secrets.OTHER_KEY }}\n",
+    );
+    expect(job).not.toMatch(/run:.*secrets/);
+  });
+
+  it("never triggers on a push or a pull request", () => {
+    expect(render(1)).not.toMatch(/push|pull_request/);
+  });
+
+  it("pins every action to a full commit SHA", () => {
+    const uses = render(2, [], true).match(/uses: \S+/g) ?? [];
+    expect(uses.length).toBeGreaterThan(0);
+    for (const line of uses) expect(line).toMatch(/@[0-9a-f]{40}$/);
+  });
+});

package/cli/sync/nightly.constants.ts

@@ -0,0 +1,48 @@
+import { CI_HEADER, DOWNLOAD, UPLOAD } from "./release.constants.ts";
+
+/** The generated header, which must be the first line of a nightly.yml sync owns. */
+export const NIGHTLY_HEADER: string = CI_HEADER;
+export const NIGHTLY_PATH: string = ".github/workflows/nightly.yml";
+export const LIVE_SCRIPT: string = "test:live";
+/** A mutation shard runs about 30 to 40 minutes on 8 shards; one shard is the whole run. */
+export const MUTATE_TIMEOUT_MINUTES: number = 180;
+/** The report a shard writes, named by its number; the floors job downloads them all by the prefix. */
+const REPORT_PREFIX: string = "mutation-";
+const REPORTS_DIR: string = "reports";
+
+/** The workflow text before the jobs: name, triggers, concurrency and permissions. */
+export const PREAMBLE: string = `name: nightly
+
+on:
+  schedule:
+    - cron: "0 3 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: nightly
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:`;
+
+/** The mutate job's steps after the install; `%TOTAL%` is the shard count. */
+export const MUTATE_STEPS: string = `      - name: Mutate this shard
+        env:
+          SHARD: \${{ matrix.shard }}
+        run: bun repo mutate --shard "$SHARD/%TOTAL%" --report "${REPORT_PREFIX}$SHARD.json"
+      - uses: ${UPLOAD}
+        if: always()
+        with:
+          name: ${REPORT_PREFIX}\${{ matrix.shard }}
+          path: ${REPORT_PREFIX}\${{ matrix.shard }}.json
+          if-no-files-found: error`;
+
+/** The floors job's steps after the install: every shard's report is downloaded into one directory and scored. */
+export const FLOORS_STEPS: string = `      - uses: ${DOWNLOAD}
+        with:
+          pattern: ${REPORT_PREFIX}*
+          merge-multiple: true
+          path: ${REPORTS_DIR}
+      - run: bun repo mutate check ${REPORTS_DIR}`;

package/cli/sync/nightly.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import { HEADER, context } from "../fixtures/release-context.ts";
+import { GENERATORS } from "./outputs.ts";
+import { nightly } from "./nightly.ts";
+
+const PATH = ".github/workflows/nightly.yml";
+const CHECKOUT = "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1";
+const SETUP_BUN = "oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0";
+const UPLOAD = "actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2";
+const DOWNLOAD = "actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2";
+
+const ONE_SHARD = `${HEADER}
+name: nightly
+
+on:
+  schedule:
+    - cron: "0 3 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: nightly
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  mutate:
+    name: mutate (\${{ matrix.shard }}/1)
+    runs-on: ubuntu-latest
+    timeout-minutes: 180
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1]
+    steps:
+      - uses: ${CHECKOUT}
+      - uses: ${SETUP_BUN}
+        with:
+          bun-version-file: package.json
+      - run: bun install --frozen-lockfile
+      - name: Mutate this shard
+        env:
+          SHARD: \${{ matrix.shard }}
+        run: bun repo mutate --shard "$SHARD/1" --report "mutation-$SHARD.json"
+      - uses: ${UPLOAD}
+        if: always()
+        with:
+          name: mutation-\${{ matrix.shard }}
+          path: mutation-\${{ matrix.shard }}.json
+          if-no-files-found: error
+
+  mutate-floors:
+    name: mutate-floors
+    needs: mutate
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: ${CHECKOUT}
+      - uses: ${SETUP_BUN}
+        with:
+          bun-version-file: package.json
+      - run: bun install --frozen-lockfile
+      - uses: ${DOWNLOAD}
+        with:
+          pattern: mutation-*
+          merge-multiple: true
+          path: reports
+      - run: bun repo mutate check reports
+`;
+
+describe("nightly", () => {
+  it("is a generator", () => {
+    expect(GENERATORS).toContain(nightly);
+  });
+
+  it("writes nothing with the pack off", () => {
+    expect(nightly(context(["agents", "standards", "docs"]))).toEqual({ outputs: [], errors: [] });
+  });
+
+  it("writes the whole nightly.yml for one shard and no live script", () => {
+    expect(nightly(context(["release"]))).toEqual({
+      outputs: [{ kind: "file", path: PATH, content: ONE_SHARD, tracked: true, managed: "whole" }],
+      errors: [],
+    });
+  });
+
+  it("rewrites a nightly.yml that has the generated header on its first line", () => {
+    const result = nightly(context(["release"], {}, { [PATH]: `${HEADER}\nname: old\n` }));
+    expect(result.errors).toEqual([]);
+    expect(result.outputs).toHaveLength(1);
+  });
+
+  it("refuses a hand-written nightly.yml", () => {
+    expect(nightly(context(["release"], {}, { [PATH]: "name: nightly\n" }))).toEqual({
+      outputs: [],
+      errors: [".github/workflows/nightly.yml is hand-written; delete it so repo sync can own it"],
+    });
+  });
+});

package/cli/sync/nightly.ts

@@ -0,0 +1,75 @@
+import { lines } from "../scripts/managed-text.ts";
+import type { Generator, SyncContext } from "./outputs.ts";
+import {
+  FLOORS_STEPS,
+  LIVE_SCRIPT,
+  MUTATE_STEPS,
+  MUTATE_TIMEOUT_MINUTES,
+  NIGHTLY_HEADER,
+  NIGHTLY_PATH,
+  PREAMBLE,
+} from "./nightly.constants.ts";
+import { hasScript } from "./release.ts";
+import {
+  CHECKOUT_STEP,
+  INSTALL_STEP,
+  SETUP_BUN_STEP,
+  SLOW_TIMEOUT_MINUTES,
+  TEST_TIMEOUT_MINUTES,
+} from "./release.constants.ts";
+
+const SETUP = [CHECKOUT_STEP, SETUP_BUN_STEP, INSTALL_STEP];
+
+const mutateJob = (total: number) =>
+  [
+    "  mutate:",
+    "    name: mutate (${{ matrix.shard }}/" + `${total})`,
+    "    runs-on: ubuntu-latest",
+    `    timeout-minutes: ${MUTATE_TIMEOUT_MINUTES}`,
+    "    strategy:",
+    "      fail-fast: false",
+    "      matrix:",
+    `        shard: [${Array.from({ length: total }, (_, at) => at + 1).join(", ")}]`,
+    "    steps:",
+    ...SETUP,
+    MUTATE_STEPS.replace("%TOTAL%", String(total)),
+  ].join("\n");
+
+const floorsJob = () =>
+  [
+    "  mutate-floors:",
+    "    name: mutate-floors",
+    "    needs: mutate",
+    "    runs-on: ubuntu-latest",
+    `    timeout-minutes: ${TEST_TIMEOUT_MINUTES}`,
+    "    steps:",
+    ...SETUP,
+    FLOORS_STEPS,
+  ].join("\n");
+
+/** The live job: each secret is mapped by name from the repository's secrets, in `env` and nowhere else. */
+const liveJob = (secrets: readonly string[]) =>
+  [
+    "  live:",
+    "    name: live",
+    "    runs-on: ubuntu-latest",
+    `    timeout-minutes: ${SLOW_TIMEOUT_MINUTES}`,
+    ...(secrets.length > 0 ? ["    env:", ...secrets.map((name) => `      ${name}: \${{ secrets.${name} }}`)] : []),
+    "    steps:",
+    ...SETUP,
+    `      - run: bun run ${LIVE_SCRIPT}`,
+  ].join("\n");
+
+/** Under the release pack, the tracked, whole-file `.github/workflows/nightly.yml`; a hand-written one is refused. */
+export const nightly: Generator = (ctx: SyncContext) => {
+  if (!ctx.config.packs.includes("release")) return { outputs: [], errors: [] };
+  const existing = ctx.read(NIGHTLY_PATH);
+  if (existing !== null && lines(existing)[0] !== NIGHTLY_HEADER) {
+    return { outputs: [], errors: [`${NIGHTLY_PATH} is hand-written; delete it so repo sync can own it`] };
+  }
+  const { shards, secrets } = ctx.config.nightly;
+  const live = hasScript(ctx, LIVE_SCRIPT) ? [liveJob(secrets)] : [];
+  const jobs = [mutateJob(shards), floorsJob(), ...live];
+  const content = `${NIGHTLY_HEADER}\n${PREAMBLE}\n${jobs.join("\n\n")}\n`;
+  return { outputs: [{ kind: "file", path: NIGHTLY_PATH, content, tracked: true, managed: "whole" }], errors: [] };
+};

package/cli/sync/outputs.test.ts

@@ -0,0 +1,351 @@
+import { BASE_CONFIG } from "../fixtures/base-config.ts";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import type { Pack } from "../config.ts";
+import type { Host } from "../config.ts";
+import { nightly } from "./nightly.ts";
+import { release } from "./release.ts";
+import { releaseWorkflow } from "./release-workflow.ts";
+import { bunfig, GENERATORS, index, lessons, trees, type Output, type SyncContext } from "./outputs.ts";
+import type { PackageJson, WorkspacePackage } from "./workspace.ts";
+
+const BUNFIG = '# Generated by repo sync. Do not edit.\n[install]\nlinker = "hoisted"\nauto = "disable"\n';
+
+type Fixture = {
+  hosts?: Host[];
+  packs?: Pack[];
+  manifest?: PackageJson;
+  packages?: WorkspacePackage[];
+  files?: Record<string, string>;
+};
+
+/** A sync context over in-memory files; `read` sees only `files`. */
+function context({
+  hosts = [],
+  packs = ["agents", "docs"],
+  manifest = {},
+  packages = [],
+  files = {},
+}: Fixture = {}): SyncContext {
+  return {
+    root: "/repo",
+    config: {
+      packs,
+      agents: { hosts, skills: [] },
+      ...BASE_CONFIG,
+    },
+    workspace: { root: "/repo", manifest, packages },
+    read: (rel) => files[rel] ?? null,
+  };
+}
+
+/** The text of a file output. */
+function contentOf(output: Output | undefined): string | undefined {
+  return output?.kind === "file" ? output.content : undefined;
+}
+
+const API: WorkspacePackage = { dir: "packages/api", manifest: { name: "@acme/api" } };
+const WEB: WorkspacePackage = { dir: "apps/web", manifest: { name: "web" } };
+const PACKAGE_INDEXES = {
+  "packages/api/references/INDEX.md": "\n\n# API worker\n\nMore.\n",
+  "apps/web/references/INDEX.md": "Web app\r\n",
+};
+const PACKAGES_SECTION =
+  "<!-- repo:packages -->\n" +
+  "- [web](../apps/web/references/INDEX.md): Web app\n" +
+  "- [@acme/api](../packages/api/references/INDEX.md): API worker\n" +
+  "<!-- /repo:packages -->";
+const REPO_STACK =
+  "<!-- repo:stack -->\n" +
+  "- [@workerstack/repo](../node_modules/@workerstack/repo/references/INDEX.md)\n" +
+  "<!-- /repo:stack -->";
+const EMPTY_STACK = "<!-- repo:stack -->\n<!-- /repo:stack -->";
+
+describe("GENERATORS", () => {
+  it("runs bunfig, index, lessons, trees, release, nightly and the release workflow in that order", () => {
+    expect(GENERATORS).toEqual([bunfig, index, lessons, trees, release, nightly, releaseWorkflow]);
+  });
+});
+
+describe("bunfig", () => {
+  it("writes the generated bunfig.toml when none exists", () => {
+    expect(bunfig(context())).toEqual({
+      outputs: [{ kind: "file", path: "bunfig.toml", content: BUNFIG, tracked: true, managed: "whole" }],
+      errors: [],
+    });
+  });
+
+  it("returns the same content when the file is current", () => {
+    expect(bunfig(context({ files: { "bunfig.toml": BUNFIG } }))).toEqual({
+      outputs: [{ kind: "file", path: "bunfig.toml", content: BUNFIG, tracked: true, managed: "whole" }],
+      errors: [],
+    });
+  });
+
+  it("owns a stale file that still starts with the generated header", () => {
+    const stale = '# Generated by repo sync. Do not edit.\r\n[install]\r\nlinker = "isolated"\r\n';
+    expect(bunfig(context({ files: { "bunfig.toml": stale } })).outputs).toEqual([
+      { kind: "file", path: "bunfig.toml", content: BUNFIG, tracked: true, managed: "whole" },
+    ]);
+  });
+
+  it("refuses a hand-written bunfig.toml", () => {
+    expect(bunfig(context({ files: { "bunfig.toml": '[test]\nroot = "x"\n' } }))).toEqual({
+      outputs: [],
+      errors: ["bunfig.toml is hand-written; delete it so repo sync can own it"],
+    });
+  });
+});
+
+describe("trees", () => {
+  it("writes nothing without the agents pack, whatever the hosts", () => {
+    expect(trees(context({ hosts: ["claude"], packs: ["docs"] }))).toEqual({ outputs: [], errors: [] });
+    expect(trees(context({ hosts: ["claude"], packs: [] }))).toEqual({ outputs: [], errors: [] });
+  });
+
+  it("writes nothing with the agents pack and no hosts", () => {
+    expect(trees(context())).toEqual({ outputs: [], errors: [] });
+  });
+
+  it("turns a failed render into one error", () => {
+    const result = trees(context({ hosts: ["claude"] }));
+    expect(result.outputs).toEqual([]);
+    expect(result.errors).toEqual([expect.stringContaining("bun install")]);
+  });
+});
+
+describe("lessons", () => {
+  /** A real root with a lessons dir, so the pack alone decides whether the index is written. */
+  const withLessonsDir = (packs: Pack[]) => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-lessons-"));
+    try {
+      fs.mkdirSync(path.join(root, ".repo", "lessons"), { recursive: true });
+      return lessons({ ...context({ packs }), root });
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  };
+
+  it("writes nothing without the agents pack", () => {
+    expect(withLessonsDir(["docs"])).toEqual({ outputs: [], errors: [] });
+    expect(withLessonsDir([])).toEqual({ outputs: [], errors: [] });
+  });
+
+  it("writes the lessons index with the agents pack", () => {
+    expect(withLessonsDir(["agents"]).outputs.map((o) => o.path)).toEqual([".repo/lessons/INDEX.md"]);
+  });
+});
+
+describe("index", () => {
+  const STACK_ROOT: PackageJson = { dependencies: { "@workerstack/repo": "^1.0.0" } };
+
+  it("does nothing when the docs pack is off", () => {
+    expect(index(context({ packs: ["agents"], packages: [API], files: {} }))).toEqual({ outputs: [], errors: [] });
+  });
+
+  it("creates the file with both sections when it is missing, then each package INDEX with an empty deps section", () => {
+    const ctx = context({ manifest: STACK_ROOT, packages: [WEB, API], files: PACKAGE_INDEXES });
+    const block = (path: string, content: string): Output => ({
+      kind: "file",
+      path,
+      content,
+      tracked: true,
+      managed: "block",
+    });
+    expect(index(ctx)).toEqual({
+      outputs: [
+        block("references/INDEX.md", `# References\n\n${PACKAGES_SECTION}\n\n${REPO_STACK}\n`),
+        block("apps/web/references/INDEX.md", "Web app\n\n<!-- repo:deps -->\n<!-- /repo:deps -->\n"),
+        block(
+          "packages/api/references/INDEX.md",
+          "\n\n# API worker\n\nMore.\n\n<!-- repo:deps -->\n<!-- /repo:deps -->\n",
+        ),
+      ],
+      errors: [],
+    });
+  });
+
+  it("writes no packages section in a single-package repo, and keeps empty stack markers", () => {
+    expect(index(context()).outputs).toEqual([
+      {
+        kind: "file",
+        path: "references/INDEX.md",
+        content: `# References\n\n${EMPTY_STACK}\n`,
+        tracked: true,
+        managed: "block",
+      },
+    ]);
+  });
+
+  it("replaces present sections in place and keeps the hand-written text around them", () => {
+    const text =
+      "# Docs\n\nIntro.\n\n<!-- repo:packages -->\n- stale\n<!-- /repo:packages -->\n\nMiddle.\n\n" +
+      "<!-- repo:stack -->\n- stale\n<!-- /repo:stack -->\n\nFooter.\n";
+    const ctx = context({
+      manifest: STACK_ROOT,
+      packages: [WEB, API],
+      files: { ...PACKAGE_INDEXES, "references/INDEX.md": text },
+    });
+    expect(index(ctx).outputs.slice(0, 1)).toEqual([
+      {
+        kind: "file",
+        path: "references/INDEX.md",
+        content: `# Docs\n\nIntro.\n\n${PACKAGES_SECTION}\n\nMiddle.\n\n${REPO_STACK}\n\nFooter.\n`,
+        tracked: true,
+        managed: "block",
+      },
+    ]);
+  });
+
+  it("appends absent sections at the end after a blank line", () => {
+    const ctx = context({
+      manifest: STACK_ROOT,
+      packages: [WEB, API],
+      files: { ...PACKAGE_INDEXES, "references/INDEX.md": "# Docs\n\nHand-written." },
+    });
+    expect(index(ctx).outputs.slice(0, 1)).toEqual([
+      {
+        kind: "file",
+        path: "references/INDEX.md",
+        content: `# Docs\n\nHand-written.\n\n${PACKAGES_SECTION}\n\n${REPO_STACK}\n`,
+        tracked: true,
+        managed: "block",
+      },
+    ]);
+  });
+
+  it("describes a package by its first non-empty INDEX line and links it by name, else by dir", () => {
+    const ctx = context({
+      packages: [
+        { dir: "libs/blank", manifest: { name: "" } },
+        { dir: "libs/heading", manifest: { name: "heading" } },
+      ],
+      files: { "libs/blank/references/INDEX.md": "\n  \n", "libs/heading/references/INDEX.md": "  ## Sub  \n# Top\n" },
+    });
+    expect(contentOf(index(ctx).outputs[0])).toContain(
+      "<!-- repo:packages -->\n" +
+        "- [libs/blank](../libs/blank/references/INDEX.md)\n" +
+        "- [heading](../libs/heading/references/INDEX.md): ## Sub\n" +
+        "<!-- /repo:packages -->\n",
+    );
+  });
+
+  it("fails naming each workspace package that has no references/INDEX.md", () => {
+    const ctx = context({ packages: [WEB, API], files: {} });
+    expect(index(ctx)).toEqual({
+      outputs: [],
+      errors: [
+        "apps/web has no references/INDEX.md; every workspace package needs one",
+        "packages/api has no references/INDEX.md; every workspace package needs one",
+      ],
+    });
+  });
+
+  it("lists every @workerstack/* dependency of the root and packages once, sorted", () => {
+    const ctx = context({
+      manifest: {
+        dependencies: { "@workerstack/repo": "^1.0.0", zod: "^4.0.0" },
+        devDependencies: { "@workerstack/lint": "^1.0.0" },
+      },
+      packages: [
+        {
+          dir: "packages/api",
+          manifest: {
+            peerDependencies: { "@workerstack/worker": "^1.0.0", "@workerstack/repo": "^1.0.0" },
+            optionalDependencies: { "@workerstack/ai": "^1.0.0", "@workerstackx/no": "1.0.0" },
+          },
+        },
+      ],
+      files: { "packages/api/references/INDEX.md": "API\n" },
+    });
+    const link = (name: string) => `- [${name}](../node_modules/${name}/references/INDEX.md)\n`;
+    expect(contentOf(index(ctx).outputs[0])).toContain(
+      "<!-- repo:stack -->\n" +
+        link("@workerstack/ai") +
+        link("@workerstack/lint") +
+        link("@workerstack/repo") +
+        link("@workerstack/worker") +
+        "<!-- /repo:stack -->\n",
+    );
+  });
+
+  it("fails on a section opener with no closer", () => {
+    const ctx = context({ files: { "references/INDEX.md": "# Docs\n\n<!-- repo:stack -->\n- stale\n" } });
+    expect(index(ctx)).toEqual({
+      outputs: [],
+      errors: ['references/INDEX.md: "<!-- repo:stack -->" has no closing "<!-- /repo:stack -->"'],
+    });
+  });
+
+  it("reports a missing package INDEX and an unclosed section together", () => {
+    const ctx = context({ packages: [API], files: { "references/INDEX.md": "<!-- repo:packages -->\n" } });
+    expect(index(ctx).errors).toEqual([
+      "packages/api has no references/INDEX.md; every workspace package needs one",
+      'references/INDEX.md: "<!-- repo:packages -->" has no closing "<!-- /repo:packages -->"',
+    ]);
+  });
+});
+
+describe("index repo:deps", () => {
+  const pkg = (dir: string, name: string, deps: Partial<PackageJson> = {}): WorkspacePackage => ({
+    dir,
+    manifest: { name, ...deps },
+  });
+  const WEB_PKG = pkg("packages/web", "@acme/web", {
+    dependencies: { "@acme/api": "1.0.0", react: "19.0.0", "@workerstack/ui": "1.0.0" },
+    devDependencies: { "@acme/core": "1.0.0", "@workerstack/lint": "1.0.0", "@workerstack/shared": "1.0.0" },
+    peerDependencies: { "@acme/api": "1.0.0" },
+    optionalDependencies: { "@workerstack/ai": "1.0.0" },
+  });
+  const files = {
+    "packages/web/references/INDEX.md": "# Web\n",
+    "packages/api/references/INDEX.md": "# Api\n",
+    "packages/core/references/INDEX.md": "# Core\n",
+    "packages/shared/references/INDEX.md": "# Shared\n",
+  };
+  const packages = [
+    WEB_PKG,
+    pkg("packages/api", "@acme/api"),
+    pkg("packages/core", "@acme/core"),
+    pkg("packages/shared", "@workerstack/shared"),
+  ];
+  const depsOf = (rel: string, ctx = context({ packages, files })) => {
+    const content = contentOf(index(ctx).outputs.find((o) => o.path === rel));
+    return content?.split("<!-- repo:deps -->\n")[1]?.split("<!-- /repo:deps -->")[0];
+  };
+
+  it("links the INDEX of each workspace dependency first, then each other @workerstack/* one, both sorted and deduped", () => {
+    expect(depsOf("packages/web/references/INDEX.md")).toBe(
+      "- [@acme/api](../../api/references/INDEX.md)\n" +
+        "- [@acme/core](../../core/references/INDEX.md)\n" +
+        "- [@workerstack/shared](../../shared/references/INDEX.md)\n" +
+        "- [@workerstack/ai](../../../node_modules/@workerstack/ai/references/INDEX.md)\n" +
+        "- [@workerstack/lint](../../../node_modules/@workerstack/lint/references/INDEX.md)\n" +
+        "- [@workerstack/ui](../../../node_modules/@workerstack/ui/references/INDEX.md)\n",
+    );
+  });
+
+  it("gives a package with no such dependency an empty section, and replaces a stale one in place", () => {
+    expect(depsOf("packages/api/references/INDEX.md")).toBe("");
+    const stale = {
+      ...files,
+      "packages/web/references/INDEX.md": "# Web\n\n<!-- repo:deps -->\n- stale\n<!-- /repo:deps -->\n\nTail.\n",
+    };
+    const content = contentOf(
+      index(context({ packages, files: stale })).outputs.find((o) => o.path === "packages/web/references/INDEX.md"),
+    );
+    expect(content).toMatch(/^# Web\n\n<!-- repo:deps -->\n- \[@acme\/api\]/);
+    expect(content).toMatch(/<!-- \/repo:deps -->\n\nTail\.\n$/);
+    expect(content).not.toContain("stale");
+  });
+
+  it("fails on an unclosed deps section in a package INDEX", () => {
+    const broken = { ...files, "packages/api/references/INDEX.md": "# Api\n<!-- repo:deps -->\n" };
+    expect(index(context({ packages, files: broken }))).toEqual({
+      outputs: [],
+      errors: ['packages/api/references/INDEX.md: "<!-- repo:deps -->" has no closing "<!-- /repo:deps -->"'],
+    });
+  });
+});