claudeup 4.37.0 → 4.38.0

package/src/__tests__/community-staleness.test.ts

@@ -0,0 +1,722 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import fs from "fs-extra";
+import {
+	COMMUNITY_SOURCES,
+	type CommunityStyleSource,
+	resolveCommunityStyle,
+} from "../data/community-styles.js";
+import {
+	readCommunityChecks,
+	resetCatalogCacheMemo,
+	writeCommunityCheck,
+} from "../services/catalog-cache-store.js";
+import type {
+	StyleFetchResponse,
+	StyleFetcher,
+} from "../services/community-fetcher.js";
+import {
+	COMMUNITY_CHECK_TTL_MS,
+	acceptPendingUpdate,
+	cachePathFor,
+	checkAllSources,
+	checkSourceForUpdates,
+	countChangedLines,
+	describeCommunityFailure,
+	fetchCommunityStyle,
+	fetchCommunityStyles,
+	pendingPathFor,
+	readCommunityStatuses,
+	resetCommunityApiHeadroom,
+} from "../services/community-styles.js";
+import { resetGitHubBudget } from "../services/github-budget.js";
+import { splitFrontmatter } from "../services/styles-manager.js";
+
+// NOTHING here touches the network. Every entry point takes the `StyleFetcher`
+// port as a REQUIRED argument, so omitting it is a type error rather than a
+// silent live call — which is the whole reason the port exists.
+
+let dir: string;
+let configDir: string;
+let previousConfigDir: string | undefined;
+
+const NOW = Date.parse("2026-08-18T12:00:00Z");
+
+beforeEach(async () => {
+	dir = await mkdtemp(join(tmpdir(), "claudeup-staleness-"));
+	configDir = join(dir, "config");
+	previousConfigDir = process.env.CLAUDE_CONFIG_DIR;
+	process.env.CLAUDE_CONFIG_DIR = configDir;
+	resetCatalogCacheMemo();
+	resetGitHubBudget();
+	resetCommunityApiHeadroom();
+});
+
+afterEach(async () => {
+	// `github-budget` persists cooldowns WRITE-BEHIND — `recordSuccess` fires a
+	// lock-and-write it deliberately does not await, so its many synchronous call
+	// sites stay synchronous. Deleting the config directory out from under that
+	// in-flight write produces an ENOENT warning from the lock release. Draining
+	// first keeps the suite's output honest; it is not papering over a race, the
+	// write-behind is the documented design.
+	await new Promise((resolve) => setTimeout(resolve, 20));
+	await rm(dir, { recursive: true, force: true });
+	// biome-ignore lint/performance/noDelete: absence is the intent, not a shortcut
+	if (previousConfigDir === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+	else process.env.CLAUDE_CONFIG_DIR = previousConfigDir;
+	resetCatalogCacheMemo();
+	resetGitHubBudget();
+	resetCommunityApiHeadroom();
+});
+
+const source: CommunityStyleSource = COMMUNITY_SOURCES[0];
+const STYLE_ID = "attention-span--spartan";
+// biome-ignore lint/style/noNonNullAssertion: a registry entry the tests pin
+const style = resolveCommunityStyle(STYLE_ID)!.style;
+
+function upstreamText(body: string): string {
+	return [
+		"---",
+		"name: Spartan",
+		"description: Blunt.",
+		"---",
+		"",
+		body,
+		"",
+	].join("\n");
+}
+
+const ORIGINAL = upstreamText("- Answer first.\n- No filler.");
+const CHANGED = upstreamText("- Answer first.\n- No filler.\n- No warmth.");
+
+interface Recorder {
+	fetcher: StyleFetcher;
+	urls: string[];
+	apiCalls: () => number;
+	rawCalls: () => number;
+}
+
+/**
+ * A fetcher that answers by HOST, because the two hosts are the whole point:
+ * `api.github.com` resolves the pin and is the scarce budget, and
+ * `raw.githubusercontent.com` serves the bytes and costs nothing.
+ */
+function recorder(opts: {
+	commit?: string;
+	raw?: string | (() => Partial<StyleFetchResponse>);
+	apiStatus?: number;
+	apiHeaders?: Headers;
+}): Recorder {
+	const urls: string[] = [];
+	const fetcher: StyleFetcher = async (url) => {
+		urls.push(url);
+		const base = {
+			etag: null,
+			contentType: "text/plain; charset=utf-8",
+			headers: new Headers(),
+		};
+		if (new URL(url).hostname === "api.github.com") {
+			return {
+				...base,
+				status: opts.apiStatus ?? 200,
+				body: JSON.stringify([{ sha: opts.commit ?? "aaaaaaaaaaaa" }]),
+				headers: opts.apiHeaders ?? new Headers(),
+			};
+		}
+		const raw = typeof opts.raw === "function" ? opts.raw() : undefined;
+		return { ...base, status: 200, body: opts.raw ?? ORIGINAL, ...raw };
+	};
+	const host = (name: string) => () =>
+		urls.filter((u) => new URL(u).hostname === name).length;
+	return {
+		fetcher,
+		urls,
+		apiCalls: host("api.github.com"),
+		rawCalls: host("raw.githubusercontent.com"),
+	};
+}
+
+/** Put a fetched style on disk the same way the real fetch path would. */
+async function install(body = ORIGINAL): Promise<string> {
+	const { fetcher } = recorder({ raw: body });
+	const result = await fetchCommunityStyle({
+		style,
+		source,
+		fetcher,
+		cacheDir: dir,
+		commit: "aaaaaaaaaaaa",
+		now: NOW,
+	});
+	if (result.outcome !== "written")
+		throw new Error("fixture failed to install");
+	return result.file.sha256;
+}
+
+describe("phase A — one API call per repo answers the common case", () => {
+	test("an unchanged directory head reports up-to-date with NO raw fetches", async () => {
+		const sha256 = await install();
+		await writeCommunityCheck(source.id, {
+			checkedAt: NOW - 2 * COMMUNITY_CHECK_TTL_MS,
+			dirHeadSha: "aaaaaaaaaaaa",
+			styles: { [STYLE_ID]: { sha256 } },
+		});
+
+		const probe = recorder({ commit: "aaaaaaaaaaaa" });
+		const result = await checkSourceForUpdates({
+			source,
+			cached: [{ id: STYLE_ID, sha256 }],
+			fetcher: probe.fetcher,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+
+		expect(result.statuses[STYLE_ID].state).toBe("up-to-date");
+		expect(result.apiCalls).toBe(1);
+		expect(probe.apiCalls()).toBe(1);
+		// The inversion that makes the design affordable: nothing in the directory
+		// moved, so nothing in it can have changed, so no file is downloaded.
+		expect(probe.rawCalls()).toBe(0);
+	});
+
+	test("a moved directory drills into each style with FREE raw fetches", async () => {
+		const sha256 = await install();
+		await writeCommunityCheck(source.id, {
+			checkedAt: NOW - 2 * COMMUNITY_CHECK_TTL_MS,
+			dirHeadSha: "aaaaaaaaaaaa",
+			styles: { [STYLE_ID]: { sha256 } },
+		});
+
+		const probe = recorder({ commit: "bbbbbbbbbbbb", raw: CHANGED });
+		const result = await checkSourceForUpdates({
+			source,
+			cached: [{ id: STYLE_ID, sha256 }],
+			fetcher: probe.fetcher,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+
+		expect(result.statuses[STYLE_ID].state).toBe("update-available");
+		// Still ONE API call. Phase B spends raw budget, which is free.
+		expect(probe.apiCalls()).toBe(1);
+		expect(probe.rawCalls()).toBe(1);
+	});
+
+	test("a directory that moved for another file leaves this one up to date", async () => {
+		const sha256 = await install();
+		await writeCommunityCheck(source.id, {
+			checkedAt: NOW,
+			dirHeadSha: "aaaaaaaaaaaa",
+			styles: { [STYLE_ID]: { sha256 } },
+		});
+
+		const probe = recorder({ commit: "cccccccccccc", raw: ORIGINAL });
+		const result = await checkSourceForUpdates({
+			source,
+			cached: [{ id: STYLE_ID, sha256 }],
+			fetcher: probe.fetcher,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+
+		expect(result.statuses[STYLE_ID].state).toBe("up-to-date");
+		// The download is removed, so no pending update is left that is
+		// byte-identical to what is already installed.
+		expect(await fs.pathExists(pendingPathFor(dir, STYLE_ID))).toBe(false);
+	});
+});
+
+describe("phase B — an update is downloaded, never installed", () => {
+	test("the new bytes land in .pending and the live file is untouched", async () => {
+		const sha256 = await install();
+		const live = cachePathFor(dir, STYLE_ID);
+		const before = await fs.readFile(live, "utf8");
+
+		const probe = recorder({ commit: "bbbbbbbbbbbb", raw: CHANGED });
+		await checkSourceForUpdates({
+			source,
+			cached: [{ id: STYLE_ID, sha256 }],
+			fetcher: probe.fetcher,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+
+		expect(await fs.readFile(live, "utf8")).toBe(before);
+		const pending = pendingPathFor(dir, STYLE_ID);
+		expect(await fs.pathExists(pending)).toBe(true);
+		expect(await fs.readFile(pending, "utf8")).toContain("No warmth");
+	});
+
+	test(".pending is a SUBDIRECTORY, so style discovery cannot see it", async () => {
+		// `markdownFiles` does not recurse, which is why the cache is flat and the
+		// pending area is nested — invisible by construction rather than by a
+		// filter someone could later drop.
+		const sha256 = await install();
+		const probe = recorder({ commit: "bbbbbbbbbbbb", raw: CHANGED });
+		await checkSourceForUpdates({
+			source,
+			cached: [{ id: STYLE_ID, sha256 }],
+			fetcher: probe.fetcher,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+		const top = (await fs.readdir(dir)).filter((n) => n.endsWith(".md"));
+		expect(top).toEqual([`${STYLE_ID}.md`]);
+	});
+
+	test("reports how many lines changed, over bodies rather than frontmatter", async () => {
+		const sha256 = await install();
+		const probe = recorder({ commit: "bbbbbbbbbbbb", raw: CHANGED });
+		const result = await checkSourceForUpdates({
+			source,
+			cached: [{ id: STYLE_ID, sha256 }],
+			fetcher: probe.fetcher,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+		// One line added. `community-fetched` and `community-commit` differ on
+		// every fetch, so counting frontmatter would report a change for a style
+		// whose words are identical.
+		expect(result.statuses[STYLE_ID].changedLines).toBe(1);
+	});
+
+	test("accepting an update installs the bytes the diff was shown for", async () => {
+		const sha256 = await install();
+		const probe = recorder({ commit: "bbbbbbbbbbbb", raw: CHANGED });
+		await checkSourceForUpdates({
+			source,
+			cached: [{ id: STYLE_ID, sha256 }],
+			fetcher: probe.fetcher,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+
+		const accepted = await acceptPendingUpdate({ cacheDir: dir, id: STYLE_ID });
+		expect(accepted.outcome).toBe("accepted");
+		expect(await fs.readFile(cachePathFor(dir, STYLE_ID), "utf8")).toContain(
+			"No warmth",
+		);
+		// A rename, not a re-fetch: nothing goes back to the network, so the user
+		// gets the text they were shown, not whatever upstream serves a second later.
+		expect(await fs.pathExists(pendingPathFor(dir, STYLE_ID))).toBe(false);
+
+		// The store now records the accepted bytes, so the next check compares
+		// against what is actually installed.
+		const checks = await readCommunityChecks();
+		expect(checks[source.id].styles[STYLE_ID].pendingSha256).toBeUndefined();
+		const { frontmatter } = splitFrontmatter(
+			await fs.readFile(cachePathFor(dir, STYLE_ID), "utf8"),
+		);
+		expect(checks[source.id].styles[STYLE_ID].sha256).toBe(
+			frontmatter["community-sha256"],
+		);
+	});
+
+	test("accepting with nothing pending is a no-op, not an error", async () => {
+		await install();
+		const result = await acceptPendingUpdate({ cacheDir: dir, id: STYLE_ID });
+		expect(result.outcome).toBe("none");
+	});
+
+	test("a re-fetch supersedes a waiting update instead of leaving it behind", async () => {
+		// Otherwise the row keeps advertising "(new)" for an update the user has
+		// already taken by another route, and the panel is lying about disk.
+		const sha256 = await install();
+		const check = recorder({ commit: "bbbbbbbbbbbb", raw: CHANGED });
+		await checkSourceForUpdates({
+			source,
+			cached: [{ id: STYLE_ID, sha256 }],
+			fetcher: check.fetcher,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+		expect((await readCommunityStatuses(NOW))[STYLE_ID].state).toBe(
+			"update-available",
+		);
+
+		const refetch = recorder({ commit: "bbbbbbbbbbbb", raw: CHANGED });
+		await fetchCommunityStyles({
+			ids: [STYLE_ID],
+			fetcher: refetch.fetcher,
+			cacheDir: dir,
+			now: NOW,
+		});
+
+		expect(await fs.pathExists(pendingPathFor(dir, STYLE_ID))).toBe(false);
+		expect((await readCommunityStatuses(NOW))[STYLE_ID].state).not.toBe(
+			"update-available",
+		);
+	});
+});
+
+describe("an incomplete check is not recorded as a complete one", () => {
+	test("a failed drilldown does not advance the directory sha", async () => {
+		// The fail-open this closes: recording the new head after a failed phase B
+		// would make the NEXT phase A short-circuit on "nothing moved", and a style
+		// whose bytes were never compared would start reading as up to date on the
+		// strength of a check that failed.
+		const sha256 = await install();
+		await writeCommunityCheck(source.id, {
+			checkedAt: NOW - 2 * COMMUNITY_CHECK_TTL_MS,
+			dirHeadSha: "aaaaaaaaaaaa",
+			styles: { [STYLE_ID]: { sha256 } },
+		});
+
+		const failing: StyleFetcher = async (url) => {
+			if (new URL(url).hostname === "api.github.com") {
+				return {
+					status: 200,
+					body: JSON.stringify([{ sha: "bbbbbbbbbbbb" }]),
+					etag: null,
+					contentType: "application/json",
+					headers: new Headers(),
+				};
+			}
+			throw Object.assign(new Error("fetch failed"), { code: "ENETUNREACH" });
+		};
+
+		const result = await checkSourceForUpdates({
+			source,
+			cached: [{ id: STYLE_ID, sha256 }],
+			fetcher: failing,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+		expect(result.statuses[STYLE_ID].state).toBe("unknown");
+
+		const stored = (await readCommunityChecks())[source.id];
+		expect(stored.dirHeadSha).toBe("aaaaaaaaaaaa");
+		// And the style itself is not recorded, so nothing can infer a pass for it.
+		expect(stored.styles[STYLE_ID]).toBeUndefined();
+		expect((await readCommunityStatuses(NOW))[STYLE_ID]).toBeUndefined();
+	});
+});
+
+describe("fail closed — a check that could not look never says up to date", () => {
+	test("a rate-limited phase A yields unknown with the reason", async () => {
+		const sha256 = await install();
+		await writeCommunityCheck(source.id, {
+			checkedAt: NOW,
+			dirHeadSha: "aaaaaaaaaaaa",
+			styles: { [STYLE_ID]: { sha256 } },
+		});
+
+		const probe = recorder({
+			apiStatus: 429,
+			apiHeaders: new Headers({ "retry-after": "240" }),
+		});
+		const result = await checkSourceForUpdates({
+			source,
+			cached: [{ id: STYLE_ID, sha256 }],
+			fetcher: probe.fetcher,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+
+		const status = result.statuses[STYLE_ID];
+		expect(status.state).toBe("unknown");
+		expect(status.state).not.toBe("up-to-date");
+		expect(status.detail).toMatch(/rate limit/i);
+		// No raw drilldown either — a check that could not establish the premise
+		// does not spend the other host's budget guessing.
+		expect(probe.rawCalls()).toBe(0);
+	});
+
+	test("an offline phase A yields unknown, not a quiet pass", async () => {
+		const sha256 = await install();
+		const fetcher: StyleFetcher = async () => {
+			throw Object.assign(new Error("fetch failed"), { code: "ENETUNREACH" });
+		};
+		const result = await checkSourceForUpdates({
+			source,
+			cached: [{ id: STYLE_ID, sha256 }],
+			fetcher,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+		expect(result.statuses[STYLE_ID].state).toBe("unknown");
+		expect(result.statuses[STYLE_ID].detail).toMatch(/no network/);
+	});
+
+	test("a copy with no content hash reports unknown rather than guessing", async () => {
+		const probe = recorder({ commit: "bbbbbbbbbbbb" });
+		const result = await checkSourceForUpdates({
+			source,
+			cached: [{ id: STYLE_ID, sha256: null }],
+			fetcher: probe.fetcher,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+		expect(result.statuses[STYLE_ID].state).toBe("unknown");
+		expect(result.statuses[STYLE_ID].detail).toMatch(/no content hash/);
+	});
+
+	test("a recorded pass DECAYS to unknown once it ages past the TTL", async () => {
+		// The fail-closed clause applied to time. Evidence about three days ago is
+		// not evidence about now, and continuing to render "up to date" from it
+		// would be the quiet lie this design exists to avoid.
+		await writeCommunityCheck(source.id, {
+			checkedAt: NOW - COMMUNITY_CHECK_TTL_MS - 1,
+			dirHeadSha: "aaaaaaaaaaaa",
+			styles: { [STYLE_ID]: { sha256: "sha256:x" } },
+		});
+		const stale = await readCommunityStatuses(NOW);
+		expect(stale[STYLE_ID].state).toBe("unknown");
+
+		resetCatalogCacheMemo();
+		await writeCommunityCheck(source.id, {
+			checkedAt: NOW - 1000,
+			dirHeadSha: "aaaaaaaaaaaa",
+			styles: { [STYLE_ID]: { sha256: "sha256:x" } },
+		});
+		const fresh = await readCommunityStatuses(NOW);
+		expect(fresh[STYLE_ID].state).toBe("up-to-date");
+	});
+
+	test("a pending update survives the TTL — a downloaded file is a fact", async () => {
+		await writeCommunityCheck(source.id, {
+			checkedAt: NOW - 10 * COMMUNITY_CHECK_TTL_MS,
+			dirHeadSha: "aaaaaaaaaaaa",
+			styles: {
+				[STYLE_ID]: {
+					sha256: "sha256:x",
+					pendingSha256: "sha256:y",
+					pendingLines: 12,
+				},
+			},
+		});
+		const statuses = await readCommunityStatuses(NOW);
+		expect(statuses[STYLE_ID].state).toBe("update-available");
+		expect(statuses[STYLE_ID].changedLines).toBe(12);
+	});
+
+	test("a style never checked reports not checked", async () => {
+		expect((await readCommunityStatuses(NOW))[STYLE_ID]).toBeUndefined();
+	});
+});
+
+describe("the TTL decides whether a check goes to the network at all", () => {
+	test("a fresh check is served from the store with zero calls", async () => {
+		const sha256 = await install();
+		await writeCommunityCheck(source.id, {
+			checkedAt: NOW - 1000,
+			dirHeadSha: "aaaaaaaaaaaa",
+			styles: { [STYLE_ID]: { sha256 } },
+		});
+
+		const probe = recorder({ commit: "bbbbbbbbbbbb" });
+		const result = await checkSourceForUpdates({
+			source,
+			cached: [{ id: STYLE_ID, sha256 }],
+			fetcher: probe.fetcher,
+			cacheDir: dir,
+			now: NOW,
+		});
+		expect(result.apiCalls).toBe(0);
+		expect(probe.urls).toEqual([]);
+		expect(result.statuses[STYLE_ID].state).toBe("up-to-date");
+	});
+
+	test("an expired check re-checks", async () => {
+		const sha256 = await install();
+		await writeCommunityCheck(source.id, {
+			checkedAt: NOW - COMMUNITY_CHECK_TTL_MS - 1,
+			dirHeadSha: "aaaaaaaaaaaa",
+			styles: { [STYLE_ID]: { sha256 } },
+		});
+
+		const probe = recorder({ commit: "aaaaaaaaaaaa" });
+		const result = await checkSourceForUpdates({
+			source,
+			cached: [{ id: STYLE_ID, sha256 }],
+			fetcher: probe.fetcher,
+			cacheDir: dir,
+			now: NOW,
+		});
+		expect(result.apiCalls).toBe(1);
+	});
+
+	test("an explicit u forces a check inside the TTL", async () => {
+		const sha256 = await install();
+		await writeCommunityCheck(source.id, {
+			checkedAt: NOW - 1000,
+			dirHeadSha: "aaaaaaaaaaaa",
+			styles: { [STYLE_ID]: { sha256 } },
+		});
+		const probe = recorder({ commit: "aaaaaaaaaaaa" });
+		await checkSourceForUpdates({
+			source,
+			cached: [{ id: STYLE_ID, sha256 }],
+			fetcher: probe.fetcher,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+		expect(probe.apiCalls()).toBe(1);
+	});
+
+	test("a repo with nothing cached costs nothing at all", async () => {
+		const probe = recorder({});
+		const result = await checkSourceForUpdates({
+			source,
+			cached: [],
+			fetcher: probe.fetcher,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+		expect(result.apiCalls).toBe(0);
+		expect(probe.urls).toEqual([]);
+	});
+});
+
+describe("the budget, which is the binding constraint", () => {
+	test("a five-repo sweep makes exactly five API calls", async () => {
+		// The regression this pins: 57 per-style API calls would exhaust the
+		// machine's 60/hr unauthenticated budget on first use and break `gh` for
+		// everything else on the box. The cost must be a function of REPOS.
+		const oneEach = [
+			"attention-span--spartan",
+			"claude-mods--executive",
+			"lej-output-fixer--scannable",
+			"hesreallyhim--zen-master",
+			"nattergabriel--socratic",
+		];
+		for (const id of oneEach) {
+			// biome-ignore lint/style/noNonNullAssertion: ids pinned from the registry
+			const sourceId = resolveCommunityStyle(id)!.source.id;
+			await writeCommunityCheck(sourceId, {
+				checkedAt: NOW - 2 * COMMUNITY_CHECK_TTL_MS,
+				dirHeadSha: "aaaaaaaaaaaa",
+				styles: { [id]: { sha256: "sha256:x" } },
+			});
+		}
+
+		const probe = recorder({ commit: "aaaaaaaaaaaa" });
+		const result = await checkAllSources({
+			cached: oneEach.map((id) => ({ id, sha256: "sha256:x" })),
+			fetcher: probe.fetcher,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+
+		expect(result.apiCalls).toBe(5);
+		expect(probe.apiCalls()).toBe(5);
+		expect(probe.rawCalls()).toBe(0);
+	});
+
+	test("many styles from ONE repo still cost one API call", async () => {
+		const ids = [
+			"attention-span--spartan",
+			"attention-span--rundown",
+			"attention-span--attention-kind",
+		];
+		await writeCommunityCheck(source.id, {
+			checkedAt: NOW - 2 * COMMUNITY_CHECK_TTL_MS,
+			dirHeadSha: "aaaaaaaaaaaa",
+			styles: Object.fromEntries(ids.map((id) => [id, { sha256: "sha256:x" }])),
+		});
+
+		const probe = recorder({ commit: "aaaaaaaaaaaa" });
+		const result = await checkAllSources({
+			cached: ids.map((id) => ({ id, sha256: "sha256:x" })),
+			fetcher: probe.fetcher,
+			cacheDir: dir,
+			now: NOW,
+			force: true,
+		});
+		expect(result.apiCalls).toBe(1);
+		expect(Object.keys(result.statuses).sort()).toEqual([...ids].sort());
+	});
+});
+
+describe("countChangedLines", () => {
+	test("is zero for identical text", () => {
+		expect(countChangedLines("a\nb\nc", "a\nb\nc")).toBe(0);
+	});
+
+	test("counts one insertion as one", () => {
+		expect(countChangedLines("a\nb", "a\nb\nc")).toBe(1);
+	});
+
+	test("counts one deletion as one", () => {
+		expect(countChangedLines("a\nb\nc", "a\nc")).toBe(1);
+	});
+
+	test("counts a modified line as a deletion plus an insertion", () => {
+		expect(countChangedLines("a\nb\nc", "a\nB\nc")).toBe(2);
+	});
+
+	test("a reordering does not report every line as changed", () => {
+		// The reason this is an LCS rather than a length difference: the number is
+		// shown to the user as the reason to accept an update, and inflating it
+		// teaches them to stop reading it.
+		expect(countChangedLines("a\nb\nc\nd", "b\na\nc\nd")).toBe(2);
+	});
+});
+
+describe("describeCommunityFailure", () => {
+	test("names an escape hatch for a rate limit", () => {
+		expect(
+			describeCommunityFailure(
+				{ kind: "rate-limited", detail: "GitHub rate limit resets in 4m" },
+				"Spartan",
+			),
+		).toMatch(/GITHUB_TOKEN/);
+	});
+
+	test("a 404 blames claudeup, because it IS our bug", () => {
+		// The set of fetchable coordinates is a constant in a reviewed commit, so a
+		// missing file means our registry entry went stale. Telling the user "not
+		// found" would send them looking for something they cannot fix.
+		expect(
+			describeCommunityFailure(
+				{
+					kind: "not-found",
+					detail: "claudeup's registry entry is out of date",
+				},
+				"Spartan",
+			),
+		).toMatch(/claudeup/);
+	});
+
+	test("a DNS failure stands alone so the diagnosis is not truncated", () => {
+		const detail = "Could not resolve raw.githubusercontent.com. MagicDNS…";
+		expect(describeCommunityFailure({ kind: "dns", detail }, "Spartan")).toBe(
+			detail,
+		);
+	});
+
+	test("every kind produces its own sentence, and all mention the style", () => {
+		const kinds = [
+			"offline",
+			"timeout",
+			"too-large",
+			"invalid",
+			"http",
+			"network",
+		] as const;
+		const messages = kinds.map((kind) =>
+			describeCommunityFailure(
+				{ kind, detail: `detail for ${kind}` },
+				"Spartan",
+			),
+		);
+		expect(new Set(messages).size).toBe(kinds.length);
+		for (const message of messages) expect(message).toContain("Spartan");
+	});
+});