@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/sync/golden.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest";
+import { readGoldens, renderFixtureTrees } from "../../dev/capture-tree-goldens.ts";
+
+// One render spawns rulesync three times, about 2.5s each on a CI runner.
+const RENDER_TIMEOUT = 60_000;
+
+// Regenerate only with `bun dev/capture-tree-goldens.ts`; a diff here is a byte a host would read differently.
+describe("agent trees of the consumer fixture over the frozen stock", { timeout: RENDER_TIMEOUT }, () => {
+  it("render exactly the golden files, byte for byte", async () => {
+    const rendered = await renderFixtureTrees();
+    const goldens = readGoldens();
+    expect([...rendered.keys()]).toEqual([...goldens.keys()]);
+    for (const [rel, content] of goldens) expect(rendered.get(rel), rel).toBe(content);
+  });
+});

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

@@ -0,0 +1,99 @@
+import { execFileSync } 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 { markHooksExecutable } from "./standards.ts";
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const dir of dirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+const git = (cwd: string, ...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" });
+/** What the user's own `git add -A` does to the temp repo. */
+const stageAll = (root: string) => git(root, "add", "-A");
+
+/** A repo like a Windows checkout: git cannot see file modes, so a new file is added as 100644. */
+function windowsLikeRepo(): string {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "hooks-mode-")));
+  dirs.push(root);
+  git(root, "init", "-q", "-b", "main");
+  git(root, "config", "core.fileMode", "false");
+  fs.mkdirSync(path.join(root, ".githooks"));
+  for (const name of ["commit-msg", "pre-commit"]) fs.writeFileSync(path.join(root, ".githooks", name), "#!/bin/sh\n");
+  return root;
+}
+
+const modes = (root: string) => git(root, "ls-files", "-s", ".githooks").replaceAll(/ \w+ 0/g, "");
+
+it("on win32 marks the hooks 100755 in the index, and a later git add -A keeps it", () => {
+  const root = windowsLikeRepo();
+  const result = markHooksExecutable(root, "win32");
+  expect(result.warnings).toEqual([]);
+  expect(result.done).toHaveLength(1);
+  stageAll(root);
+  expect(modes(root)).toBe("100755\t.githooks/commit-msg\n100755\t.githooks/pre-commit\n");
+  expect(markHooksExecutable(root, "win32")).toEqual({ done: [], warnings: [] });
+});
+
+it("on win32 fixes a hook already tracked as 100644 without restaging its content", () => {
+  const root = windowsLikeRepo();
+  stageAll(root);
+  expect(modes(root)).toBe("100644\t.githooks/commit-msg\n100644\t.githooks/pre-commit\n");
+  fs.writeFileSync(path.join(root, ".githooks", "pre-commit"), "#!/bin/sh\nedited\n");
+  markHooksExecutable(root, "win32");
+  expect(modes(root)).toBe("100755\t.githooks/commit-msg\n100755\t.githooks/pre-commit\n");
+  expect(git(root, "diff", "--name-only")).toBe(".githooks/pre-commit\n");
+});
+
+it("does nothing off win32", () => {
+  const root = windowsLikeRepo();
+  expect(markHooksExecutable(root, "linux")).toEqual({ done: [], warnings: [] });
+  expect(git(root, "ls-files", ".githooks")).toBe("");
+});
+
+type Reply = { status: number | null; stdout: string; stderr: string };
+const reply = (status: number | null, stdout = "", stderr = ""): Reply => ({ status, stdout, stderr });
+
+/** A git runner answering `answers` by the first argument, recording each call's arguments. */
+function fakeGit(root: string, answers: Record<string, Reply>) {
+  const calls: string[][] = [];
+  const run = (_cwd: string, args: readonly string[]): Reply => {
+    calls.push([...args]);
+    return answers[args[0] ?? ""] ?? reply(0, `${root}\n`);
+  };
+  return { run, calls };
+}
+
+it("does nothing when git cannot name the top level, names another one, or cannot list the hooks", () => {
+  const root = windowsLikeRepo();
+  const broken = fakeGit(root, { "rev-parse": reply(128, "", "not a repo") });
+  expect(markHooksExecutable(root, "win32", broken.run)).toEqual({ done: [], warnings: [] });
+  const elsewhere = fakeGit(root, { "rev-parse": reply(0, `${os.tmpdir()}\n`) });
+  expect(markHooksExecutable(root, "win32", elsewhere.run)).toEqual({ done: [], warnings: [] });
+  const unlisted = fakeGit(root, { "ls-files": reply(1) });
+  expect(markHooksExecutable(root, "win32", unlisted.run)).toEqual({ done: [], warnings: [] });
+  expect(unlisted.calls.some((args) => args[0] === "update-index")).toBe(false);
+});
+
+it("stages a hook the index lacks with --add, one it holds by its staged blob, and skips a missing file", () => {
+  const root = windowsLikeRepo();
+  fs.rmSync(path.join(root, ".githooks", "pre-commit"));
+  const fake = fakeGit(root, { "ls-files": reply(0, "garbage\n100644 abc123 0\t.githooks/other\n") });
+  const first = markHooksExecutable(root, "win32", fake.run);
+  expect(first.done).toEqual(["marked .githooks/commit-msg executable in the index"]);
+  expect(fake.calls.at(-1)).toEqual(["update-index", "--add", "--chmod=+x", "--", ".githooks/commit-msg"]);
+  const tracked = fakeGit(root, { "ls-files": reply(0, "100644 abc123 0\t.githooks/commit-msg\n") });
+  markHooksExecutable(root, "win32", tracked.run);
+  expect(tracked.calls.at(-1)).toEqual(["update-index", "--cacheinfo", "100755,abc123,.githooks/commit-msg"]);
+});
+
+it("warns with git's reason when it cannot mark a hook", () => {
+  const root = windowsLikeRepo();
+  const fake = fakeGit(root, { "update-index": reply(128, "", "index.lock exists\n") });
+  expect(markHooksExecutable(root, "win32", fake.run)).toEqual({
+    done: [],
+    warnings: ["cannot mark the git hooks executable: index.lock exists"],
+  });
+});

package/cli/sync/hosts.ts

@@ -0,0 +1,28 @@
+import type { Host } from "../config.ts";
+
+/** What one host owns: the root-relative path prefixes its tree is written under. */
+export type HostTree = { owns: readonly string[] };
+
+/** The one table of which host owns which dirs; trees, the git files and prune all read it. */
+export const HOST_TREES: Record<Host, HostTree> = {
+  claude: { owns: [".claude/"] },
+  codex: { owns: [".codex/", ".agents/skills/"] },
+  antigravity: { owns: [".agents/"] },
+  grok: { owns: [".grok/"] },
+  cursor: { owns: [".cursor/"] },
+};
+
+/** The agent instructions file; every host reads it. */
+const AGENTS_FILE = "AGENTS.md";
+/** The file a package keeps for claude, which holds only the pointer line. */
+const CLAUDE_FILE = "CLAUDE.md";
+/** The MCP server list Claude reads. */
+const MCP_FILE = ".mcp.json";
+
+/** Whether a generated root-relative path (a package's `AGENTS.md` and `CLAUDE.md` included) belongs to one of `hosts`; any other path is not a host output. */
+export function isHostOutput(hosts: readonly Host[], rel: string): boolean {
+  if (rel === AGENTS_FILE || rel.endsWith(`/${AGENTS_FILE}`)) return hosts.length > 0;
+  if (rel.endsWith(`/${CLAUDE_FILE}`)) return hosts.includes("claude");
+  if (rel === MCP_FILE) return hosts.includes("claude");
+  return hosts.some((host) => HOST_TREES[host].owns.some((prefix) => rel.startsWith(prefix)));
+}

package/cli/sync/knip-config.constants.ts

@@ -0,0 +1,4 @@
+/** The schema the generated knip config points editors at. */
+export const KNIP_SCHEMA_URL = "https://unpkg.com/knip@6/schema.json";
+/** The spaces the generated knip config is indented by. */
+export const KNIP_JSON_INDENT = 2;

package/cli/sync/knip-config.test.ts

@@ -0,0 +1,147 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { z } from "zod";
+import type { KnipIgnore } from "../knip-schema.ts";
+import { KNIP_CONFIG_PATH, KNIP_UNIGNORED_GLOB, knipConfig } from "./knip-config.ts";
+import type { PackageJson, Workspace } from "./workspace.ts";
+
+const temps: string[] = [];
+afterEach(() => {
+  for (const dir of temps.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+/** A temp root holding the empty `files`, and a workspace of its manifest and packages. */
+function workspace(manifest: PackageJson, packages: Workspace["packages"], files: string[] = []): Workspace {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-knip-config-"));
+  temps.push(root);
+  for (const rel of files) {
+    fs.mkdirSync(path.dirname(path.join(root, rel)), { recursive: true });
+    fs.writeFileSync(path.join(root, rel), "");
+  }
+  return { root, manifest, packages };
+}
+
+const generated = z.looseObject({ workspaces: z.record(z.string(), z.unknown()) });
+/** The generated config, parsed. */
+const parsed = (ws: Workspace, ignores: readonly KnipIgnore[] = []) =>
+  generated.parse(JSON.parse(knipConfig(ws, ignores)));
+
+const SCHEMA = "https://unpkg.com/knip@6/schema.json";
+const FIXTURES = ["**/fixtures/**"];
+const DEFAULT_ENTRIES = [
+  "{index,cli,main}.{js,mjs,cjs,jsx,ts,tsx,mts,cts}!",
+  "src/{index,cli,main}.{js,mjs,cjs,jsx,ts,tsx,mts,cts}!",
+];
+const RULES = [
+  ...["files", "dependencies", "devDependencies", "optionalPeerDependencies", "unlisted", "binaries"],
+  ...["unresolved", "exports", "nsExports", "types", "nsTypes", "enumMembers", "namespaceMembers"],
+  ...["duplicates", "catalog", "catalogReferences", "cycles"],
+];
+
+describe("the generated knip config: shape", () => {
+  it("names its path and the unignored copies it makes", () => {
+    expect([KNIP_CONFIG_PATH, KNIP_UNIGNORED_GLOB]).toEqual(["knip.json", "knip.unignored-*.json"]);
+  });
+
+  it("points at the schema and turns every rule to error", () => {
+    expect(parsed(workspace({}, []))).toMatchObject({
+      $schema: SCHEMA,
+      rules: Object.fromEntries(RULES.map((rule) => [rule, "error"])),
+    });
+  });
+
+  it("is one root workspace for a single package, with workerstack.config.ts as an entry and fixtures ignored", () => {
+    expect(parsed(workspace({}, []))).toMatchObject({
+      workspaces: {
+        ".": { entry: [...DEFAULT_ENTRIES, "workerstack.config.ts"], ignore: FIXTURES, ignoreBinaries: [] },
+      },
+    });
+  });
+
+  it("adds a workspace per package dir, without workerstack.config.ts, and ends with a newline", () => {
+    const ws = workspace({}, [
+      { dir: "packages/api", manifest: {} },
+      { dir: "packages/web", manifest: {} },
+    ]);
+    const { workspaces } = parsed(ws);
+    expect(Object.keys(workspaces)).toEqual([".", "packages/api", "packages/web"]);
+    expect(workspaces).toMatchObject({
+      "packages/api": { entry: DEFAULT_ENTRIES, ignore: FIXTURES, ignoreBinaries: [] },
+    });
+    expect(knipConfig(ws, []).endsWith("}\n")).toBe(true);
+  });
+});
+
+describe("the generated knip config: vitest", () => {
+  it("makes every vitest config present an entry and a vitest config of its workspace", () => {
+    const ws = workspace(
+      {},
+      [{ dir: "packages/api", manifest: {} }],
+      ["vitest.config.ts", "vitest.e2e.config.ts", "vite.config.ts", "packages/api/vitest.unit.config.mts"],
+    );
+    expect(parsed(ws)).toMatchObject({
+      workspaces: {
+        ".": {
+          entry: [...DEFAULT_ENTRIES, "workerstack.config.ts", "vitest.config.ts", "vitest.e2e.config.ts"],
+          vitest: { config: ["vitest.config.ts", "vitest.e2e.config.ts"] },
+        },
+        "packages/api": {
+          entry: [...DEFAULT_ENTRIES, "vitest.unit.config.mts"],
+          vitest: { config: ["vitest.unit.config.mts"] },
+        },
+      },
+    });
+  });
+
+  it("leaves the vitest plugin alone where no vitest config is", () => {
+    expect(parsed(workspace({}, []))).not.toHaveProperty(["workspaces", ".", "vitest"]);
+  });
+});
+
+describe("the generated knip config: bins", () => {
+  it("ignores the binaries a workspace's own manifest declares, as a map or a path, and no other's", () => {
+    const ws = workspace({ bin: { repo: "./bin/repo.ts", other: "./bin/o.ts" } }, [
+      { dir: "packages/a", manifest: { name: "@scope/a", bin: "./bin.ts" } },
+      { dir: "packages/b", manifest: { bin: "./bin.ts" } },
+      { dir: "packages/c", manifest: { name: "c" } },
+    ]);
+    expect(parsed(ws)).toMatchObject({
+      workspaces: {
+        ".": { ignoreBinaries: ["repo", "other"] },
+        "packages/a": { ignoreBinaries: ["a"] },
+        "packages/b": { ignoreBinaries: [] },
+        "packages/c": { ignoreBinaries: [] },
+      },
+    });
+  });
+});
+
+describe("the generated knip config: ignores", () => {
+  it("maps ignores to ignoreFiles, ignoreDependencies and ignoreBinaries on the root alone", () => {
+    const ws = workspace({ bin: { repo: "./bin/repo.ts" } }, [{ dir: "packages/a", manifest: {} }]);
+    const config = parsed(ws, [
+      { file: "src/old.ts", reason: "loaded by name" },
+      { dependency: "oxlint", reason: "spawned by path" },
+      { binary: "tsc", reason: "run by a hook" },
+    ]);
+    expect(config).toMatchObject({
+      workspaces: {
+        ".": {
+          ignoreFiles: ["src/old.ts"],
+          ignoreDependencies: ["@workerstack/repo", "oxlint"],
+          ignoreBinaries: ["repo", "tsc"],
+        },
+      },
+    });
+    expect(config).not.toHaveProperty(["workspaces", "packages/a", "ignoreFiles"]);
+  });
+
+  it("writes no ignoreFiles for no ignores, and always ignores this package's own name as a dependency", () => {
+    const config = parsed(workspace({}, [{ dir: "packages/a", manifest: {} }]));
+    expect(config).not.toHaveProperty(["workspaces", ".", "ignoreFiles"]);
+    expect(config).toMatchObject({ workspaces: { ".": { ignoreDependencies: ["@workerstack/repo"] } } });
+    expect(config).not.toHaveProperty(["workspaces", "packages/a", "ignoreDependencies"]);
+  });
+});

package/cli/sync/knip-config.ts

@@ -0,0 +1,108 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CONFIG_FILE } from "../config.ts";
+import type { KnipIgnore } from "../knip-schema.ts";
+import { isRecord } from "../lint/manifest.ts";
+import { KNIP_JSON_INDENT, KNIP_SCHEMA_URL } from "./knip-config.constants.ts";
+import { FIXTURES } from "./oxlint-config.ts";
+import { PACKAGE_NAME } from "./stock.ts";
+import type { PackageJson, Workspace, WorkspacePackage } from "./workspace.ts";
+
+/** The generated config sync writes at the root. */
+export const KNIP_CONFIG_PATH = "knip.json";
+/** The ignore-free copies `repo check` writes beside it for one run, each named for its process. */
+export const KNIP_UNIGNORED_GLOB = "knip.unignored-*.json";
+const ROOT = ".";
+const VITEST_CONFIGS = "vitest*.config.*";
+
+/** Every issue type knip 6.43.0 reports: each is an error, so none passes unseen. */
+const RULES = [
+  "files",
+  "dependencies",
+  "devDependencies",
+  "optionalPeerDependencies",
+  "unlisted",
+  "binaries",
+  "unresolved",
+  "exports",
+  "nsExports",
+  "types",
+  "nsTypes",
+  "enumMembers",
+  "namespaceMembers",
+  "duplicates",
+  "catalog",
+  "catalogReferences",
+  "cycles",
+] as const;
+
+/** The command names a manifest's `bin` makes: its keys, or the unscoped package name when `bin` is one path. */
+function binNames(manifest: PackageJson): string[] {
+  if (isRecord(manifest.bin)) return Object.keys(manifest.bin);
+  if (typeof manifest.bin !== "string" || manifest.name === undefined) return [];
+  return [path.posix.basename(manifest.name)];
+}
+
+/** The `vitest*.config.*` files directly in `dir`, sorted. */
+function vitestConfigs(root: string, dir: string): string[] {
+  return fs.globSync(VITEST_CONFIGS, { cwd: path.join(root, dir) }).sort();
+}
+
+/** Knip's own default entries: an explicit `entry` replaces them, so every workspace lists them again. */
+const DEFAULT_ENTRIES = [
+  "{index,cli,main}.{js,mjs,cjs,jsx,ts,tsx,mts,cts}!",
+  "src/{index,cli,main}.{js,mjs,cjs,jsx,ts,tsx,mts,cts}!",
+];
+
+type WorkspaceConfig = {
+  entry: string[];
+  vitest?: { config: string[] };
+  ignore: string[];
+  ignoreBinaries: string[];
+  ignoreFiles?: string[];
+  ignoreDependencies?: string[];
+};
+
+/** The entry, vitest and bin settings of one workspace; `extraEntry` is what only its kind adds. */
+function workspaceConfig(root: string, pkg: WorkspacePackage, extraEntry: string[]): WorkspaceConfig {
+  const { dir, manifest } = pkg;
+  const configs = vitestConfigs(root, dir);
+  return {
+    entry: [...DEFAULT_ENTRIES, ...extraEntry, ...configs],
+    ...(configs.length > 0 ? { vitest: { config: configs } } : {}),
+    ignore: [FIXTURES],
+    ignoreBinaries: binNames(manifest),
+  };
+}
+
+/** The root workspace: its own settings and the `ignores`, each as the list knip takes for its kind. */
+function rootConfig(workspace: Workspace, ignores: readonly KnipIgnore[]): WorkspaceConfig {
+  const base = workspaceConfig(workspace.root, { dir: ROOT, manifest: workspace.manifest }, [CONFIG_FILE]);
+  const files = ignores.flatMap((ignore) => ("file" in ignore ? [ignore.file] : []));
+  const dependencies = ignores.flatMap((ignore) => ("dependency" in ignore ? [ignore.dependency] : []));
+  const binaries = ignores.flatMap((ignore) => ("binary" in ignore ? [ignore.binary] : []));
+  return {
+    ...base,
+    ignoreBinaries: [...base.ignoreBinaries, ...binaries],
+    ...(files.length > 0 ? { ignoreFiles: files } : {}),
+    // The generated git hooks run this package's bin, which knip cannot see.
+    ignoreDependencies: [PACKAGE_NAME, ...dependencies],
+  };
+}
+
+/**
+ * The knip config of a workspace: every rule an error, each package dir a workspace of knip's default entries and its own (the root also
+ * `workerstack.config.ts`), the vitest configs present read by knip's vitest plugin, fixtures ignored, a workspace's
+ * own bins not reported, and the root carrying `ignores`. `repo check` passes none for its ignore-free run.
+ */
+export function knipConfig(workspace: Workspace, ignores: readonly KnipIgnore[]): string {
+  const config = {
+    $schema: KNIP_SCHEMA_URL,
+    rules: Object.fromEntries(RULES.map((rule) => [rule, "error"])),
+    workspaces: {
+      [ROOT]: rootConfig(workspace, ignores),
+      ...Object.fromEntries(workspace.packages.map((pkg) => [pkg.dir, workspaceConfig(workspace.root, pkg, [])])),
+    },
+  };
+  return `${JSON.stringify(config, null, KNIP_JSON_INDENT)}\n`;
+}

package/cli/sync/manifest.test.ts

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { MANIFEST_REL, normalizeRel, prunePaths, readManifest, renderManifest } from "./manifest.ts";
+
+const temps: string[] = [];
+afterEach(() => {
+  for (const dir of temps.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function rootWith(manifest: string | null): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-manifest-"));
+  temps.push(root);
+  if (manifest !== null) {
+    fs.mkdirSync(path.join(root, ".repo/tmp"), { recursive: true });
+    fs.writeFileSync(path.join(root, MANIFEST_REL), manifest);
+  }
+  return root;
+}
+
+describe("readManifest", () => {
+  it("reads a valid manifest", () => {
+    expect(readManifest(rootWith('{"version":1,"paths":["a","b/c"]}'))).toEqual({ version: 1, paths: ["a", "b/c"] });
+  });
+
+  it.each([
+    null,
+    "{",
+    "null",
+    "[]",
+    '{"version":2,"paths":[]}',
+    '{"version":1,"paths":"a"}',
+    '{"version":1,"paths":[1]}',
+  ])("reads %j as empty", (text) => {
+    expect(readManifest(rootWith(text))).toEqual({ version: 1, paths: [] });
+  });
+});
+
+describe("renderManifest", () => {
+  it("sorts and dedupes so equal sets give equal bytes", () => {
+    expect(renderManifest(["b", "a", "b"])).toBe(renderManifest(["a", "b"]));
+    expect(JSON.parse(renderManifest(["b", "a"]))).toEqual({ version: 1, paths: ["a", "b"] });
+    expect(renderManifest([]).endsWith("\n")).toBe(true);
+  });
+});
+
+describe("normalizeRel", () => {
+  it.each([
+    ["a/b", "/r", "a/b"],
+    ["a\\b\\c", "/r", "a/b/c"],
+    [".\\a//b/./c", "/r", "a/b/c"],
+    ["/r/a/b", "/r", "a/b"],
+    ["\\r\\a\\b", "/r", "a/b"],
+    ["C:\\Users\\x\\repo\\.claude\\a", "C:\\Users\\x\\repo", ".claude/a"],
+    ["c:/users/X/REPO/a", "C:\\Users\\x\\repo\\", "a"],
+    ["/R/a", "/r", null],
+    ["/other/a", "/r", null],
+    ["C:\\other\\a", "C:\\Users\\x\\repo", null],
+    ["C:\\Users\\x\\repo", "C:\\Users\\x\\repo", null],
+    ["../a", "/r", null],
+    ["a\\..\\..\\b", "/r", null],
+    ["", "/r", null],
+    ["./", "/r", null],
+  ])("%j under %j is %j", (raw, root, expected) => {
+    expect(normalizeRel(raw, root)).toBe(expected);
+  });
+});
+
+describe("prunePaths", () => {
+  it("returns the sorted, normalized paths no output names", () => {
+    const prev = {
+      version: 1 as const,
+      paths: ["b", ".\\a\\x", "C:\\repo\\a\\y", "C:\\repo\\keep", "keep", "../out", "C:\\else\\z"],
+    };
+    expect(prunePaths(prev, ["keep"], "C:\\repo")).toEqual(["a/x", "a/y", "b"]);
+  });
+});

package/cli/sync/manifest.ts

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/** The root-relative paths sync wrote last run, tracked or not; only these are ever pruned. */
+export const MANIFEST_REL = ".repo/tmp/sync.json";
+
+export type Manifest = { version: 1; paths: string[] };
+
+/** The manifest on disk; a missing, unreadable or invalid one reads as empty, so nothing is pruned. */
+export function readManifest(root: string): Manifest {
+  try {
+    const data: unknown = JSON.parse(fs.readFileSync(path.join(root, MANIFEST_REL), "utf8"));
+    if (typeof data === "object" && data !== null) {
+      const { version, paths } = data as { version?: unknown; paths?: unknown };
+      if (version === 1 && Array.isArray(paths) && paths.every((entry) => typeof entry === "string")) {
+        return { version: 1, paths: paths as string[] };
+      }
+    }
+  } catch {
+    // falls through to the empty manifest
+  }
+  return { version: 1, paths: [] };
+}
+
+/** The manifest file text for `paths`: deduped and sorted, so equal sets give equal bytes. */
+export function renderManifest(paths: readonly string[]): string {
+  const manifest: Manifest = { version: 1, paths: [...new Set(paths)].sort() };
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+/**
+ * One root-relative POSIX spelling of `raw`: backslashes become `/`, `./` and doubled separators go, and an
+ * absolute path under `root` (either spelling, drive letter case-insensitive) is made relative. Null for a path
+ * that is empty, outside `root` or climbs with `..`, so such a path is never matched, written or pruned.
+ */
+export function normalizeRel(raw: string, root: string): string | null {
+  const slash = (text: string) => text.replaceAll("\\", "/").replace(/\/+/g, "/");
+  let rel = slash(raw);
+  if (/^[A-Za-z]:\//.test(rel) || rel.startsWith("/")) {
+    const base = `${slash(root).replace(/\/$/, "")}/`;
+    const drive = /^[A-Za-z]:/.test(base);
+    const head = rel.slice(0, base.length);
+    if (drive ? head.toLowerCase() !== base.toLowerCase() : head !== base) return null;
+    rel = rel.slice(base.length);
+  }
+  const parts = rel.split("/").filter((part) => part !== "" && part !== ".");
+  if (parts.length === 0 || parts.includes("..")) return null;
+  return parts.join("/");
+}
+
+/** The normalized paths of `prev` that no output names; `outputPaths` must already be normalized. */
+export function prunePaths(prev: Manifest, outputPaths: Iterable<string>, root: string): string[] {
+  const keep = new Set(outputPaths);
+  const stale = new Set<string>();
+  for (const raw of prev.paths) {
+    const rel = normalizeRel(raw, root);
+    if (rel !== null && !keep.has(rel)) stale.add(rel);
+  }
+  return [...stale].sort();
+}