claudeup 4.37.0 → 4.38.0

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

@@ -0,0 +1,545 @@
+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 CommunityStyle,
+	type CommunityStyleSource,
+} from "../data/community-styles.js";
+import type {
+	StyleFetchResponse,
+	StyleFetcher,
+} from "../services/community-fetcher.js";
+import {
+	MAX_STYLE_BYTES,
+	fetchCommunityStyle,
+	fetchSource,
+	resetCommunityApiHeadroom,
+	resolveCommitPin,
+} from "../services/community-styles.js";
+import { resetGitHubBudget } from "../services/github-budget.js";
+import { splitFrontmatter } from "../services/styles-manager.js";
+
+// NOTHING here touches the network. `StyleFetcher` is a REQUIRED argument on
+// every exported function in the service, so a test cannot reach GitHub by
+// forgetting to stub — omitting the fetcher is a type error, not a silent live
+// call. That is the entire reason the port exists.
+
+let dir: string;
+
+beforeEach(async () => {
+	dir = await mkdtemp(join(tmpdir(), "claudeup-community-"));
+	resetGitHubBudget();
+	resetCommunityApiHeadroom();
+});
+afterEach(async () => {
+	await rm(dir, { recursive: true, force: true });
+	resetGitHubBudget();
+	resetCommunityApiHeadroom();
+});
+
+const source: CommunityStyleSource = COMMUNITY_SOURCES[0];
+
+const style: CommunityStyle = {
+	id: "attention-span--spartan",
+	sourceId: "attention-span",
+	path: "output-styles/spartan.md",
+	displayName: "Spartan",
+	summary: "Blunt and answer-first.",
+};
+
+/** The exact shape research.md captured from the real repo. */
+const UPSTREAM = [
+	"---",
+	"name: Spartan",
+	"description: Blunt Spartan mode for ADHD. Answer-first, arrow points, zero warmth or filler.",
+	"keep-coding-instructions: true",
+	"---",
+	"",
+	"# Spartan",
+	"",
+	"- Answer first.",
+	"",
+].join("\n");
+
+interface FakeCall {
+	url: string;
+	etag?: string | null;
+}
+
+/** A fetcher that records what it was asked and replies from a script. */
+function fake(replies: Array<Partial<StyleFetchResponse> | (() => never)>): {
+	fetcher: StyleFetcher;
+	calls: FakeCall[];
+} {
+	const calls: FakeCall[] = [];
+	let index = 0;
+	const fetcher: StyleFetcher = async (url, opts) => {
+		calls.push({ url, etag: opts?.etag });
+		const reply = replies[Math.min(index++, replies.length - 1)];
+		if (typeof reply === "function") reply();
+		return {
+			status: 200,
+			body: UPSTREAM,
+			etag: null,
+			contentType: "text/plain; charset=utf-8",
+			headers: new Headers(),
+			...(reply as Partial<StyleFetchResponse>),
+		};
+	};
+	return { fetcher, calls };
+}
+
+async function fetchOne(
+	replies: Array<Partial<StyleFetchResponse> | (() => never)>,
+	over: Partial<Parameters<typeof fetchCommunityStyle>[0]> = {},
+) {
+	const { fetcher, calls } = fake(replies);
+	const result = await fetchCommunityStyle({
+		style,
+		source,
+		fetcher,
+		cacheDir: dir,
+		commit: "b860c9f8f3c7",
+		now: Date.parse("2026-08-18T12:00:00"),
+		...over,
+	});
+	return { result, calls };
+}
+
+describe("a successful fetch", () => {
+	test("writes the file and stamps the full provenance set", async () => {
+		const { result } = await fetchOne([{}]);
+		expect(result.outcome).toBe("written");
+		if (result.outcome !== "written") return;
+
+		const { frontmatter } = splitFrontmatter(
+			await fs.readFile(result.file.path, "utf8"),
+		);
+		expect(frontmatter.name).toBe("attention-span--spartan");
+		expect(frontmatter["community-source"]).toBe("alexgreensh/attention-span");
+		expect(frontmatter["community-path"]).toBe("output-styles/spartan.md");
+		expect(frontmatter["community-ref"]).toBe("HEAD");
+		expect(frontmatter["community-commit"]).toBe("b860c9f8f3c7");
+		expect(frontmatter["community-sha256"]).toMatch(/^sha256:[0-9a-f]{64}$/);
+		expect(frontmatter["community-fetched"]).toBe("2026-08-18");
+		expect(frontmatter["community-licence"]).toBe("AGPL-3.0");
+		expect(frontmatter["community-author"]).toBe("alexgreensh");
+	});
+
+	test("names the file after the coordinate, flat, in the cache directory", async () => {
+		const { result } = await fetchOne([{}]);
+		if (result.outcome !== "written") throw new Error("expected a write");
+		expect(result.file.path).toBe(join(dir, "attention-span--spartan.md"));
+	});
+
+	test("forces keep-coding-instructions even when upstream turned it off", async () => {
+		// A style about how to COMMUNICATE has no business switching off how to
+		// write code, and a third-party file is exactly where that would arrive.
+		const hostile = UPSTREAM.replace(
+			"keep-coding-instructions: true",
+			"keep-coding-instructions: false",
+		);
+		const { result } = await fetchOne([{ body: hostile }]);
+		if (result.outcome !== "written") throw new Error("expected a write");
+		const { frontmatter } = splitFrontmatter(
+			await fs.readFile(result.file.path, "utf8"),
+		);
+		expect(frontmatter["keep-coding-instructions"]).toBe("true");
+	});
+
+	test("drops every upstream key we did not ask for", async () => {
+		// Frontmatter is rewritten, not passed through. This also blocks any
+		// future harness-recognised key we have not heard of yet.
+		const extra = UPSTREAM.replace(
+			"keep-coding-instructions: true",
+			"keep-coding-instructions: true\nsome-future-harness-key: dangerous\nmodel: opus",
+		);
+		const { result } = await fetchOne([{ body: extra }]);
+		if (result.outcome !== "written") throw new Error("expected a write");
+		const written = await fs.readFile(result.file.path, "utf8");
+		expect(written).not.toContain("some-future-harness-key");
+		expect(splitFrontmatter(written).frontmatter.model).toBeUndefined();
+	});
+
+	test("keeps upstream's description, quoted so its colon cannot break the YAML", async () => {
+		const colon = UPSTREAM.replace(
+			"description: Blunt Spartan mode for ADHD. Answer-first, arrow points, zero warmth or filler.",
+			"description: Spartan: blunt, answer-first",
+		);
+		const { result } = await fetchOne([{ body: colon }]);
+		if (result.outcome !== "written") throw new Error("expected a write");
+		const written = await fs.readFile(result.file.path, "utf8");
+		expect(written).toContain('description: "Spartan: blunt, answer-first"');
+		expect(splitFrontmatter(written).frontmatter.description).toBe(
+			"Spartan: blunt, answer-first",
+		);
+	});
+
+	test("carries the body through verbatim", async () => {
+		const { result } = await fetchOne([{}]);
+		if (result.outcome !== "written") throw new Error("expected a write");
+		const { body } = splitFrontmatter(
+			await fs.readFile(result.file.path, "utf8"),
+		);
+		expect(body).toContain("- Answer first.");
+	});
+
+	test("hashes the RAW UPSTREAM bytes, not our rewritten copy", async () => {
+		// The staleness check compares this against a fresh raw fetch. Hashing what
+		// we wrote would mean it never matched and every style read as changed
+		// forever.
+		const { createHash } = await import("node:crypto");
+		const expected = `sha256:${createHash("sha256").update(UPSTREAM).digest("hex")}`;
+		const { result } = await fetchOne([{}]);
+		if (result.outcome !== "written") throw new Error("expected a write");
+		expect(result.file.sha256).toBe(expected);
+	});
+
+	test("stamps unknown rather than lying when no pin was resolved", async () => {
+		const { result } = await fetchOne([{}], { commit: null });
+		if (result.outcome !== "written") throw new Error("expected a write");
+		const { frontmatter } = splitFrontmatter(
+			await fs.readFile(result.file.path, "utf8"),
+		);
+		expect(frontmatter["community-commit"]).toBe("unknown");
+	});
+
+	test("leaves no temp file behind", async () => {
+		await fetchOne([{}]);
+		const entries = await fs.readdir(dir);
+		expect(entries).toEqual(["attention-span--spartan.md"]);
+	});
+});
+
+describe("failures write nothing", () => {
+	const noFile = async () => {
+		expect(await fs.pathExists(join(dir, "attention-span--spartan.md"))).toBe(
+			false,
+		);
+	};
+
+	test("404 blames claudeup's registry, not the user", async () => {
+		const { result } = await fetchOne([
+			{ status: 404, body: "404: Not Found" },
+		]);
+		expect(result.outcome).toBe("failed");
+		if (result.outcome !== "failed") return;
+		expect(result.failure.kind).toBe("not-found");
+		expect(result.failure.detail).toContain("claudeup's registry entry");
+		await noFile();
+	});
+
+	test("429 records a cooldown and writes nothing", async () => {
+		const { result } = await fetchOne([
+			{
+				status: 429,
+				body: "",
+				headers: new Headers({ "retry-after": "120" }),
+			},
+		]);
+		expect(result.outcome).toBe("failed");
+		if (result.outcome !== "failed") return;
+		expect(result.failure.kind).toBe("rate-limited");
+		// Against the INJECTED clock, not Date.now(). The service computes
+		// retryAt from the `now` the harness passes in; comparing that to the
+		// real clock made this a time bomb that went red once wall-clock time
+		// passed the fixture's noon-plus-120s. retry-after: 120 → exactly +120s.
+		expect(result.failure.retryAt).toBe(
+			Date.parse("2026-08-18T12:00:00") + 120_000,
+		);
+		await noFile();
+	});
+
+	test("a recorded cooldown stops the NEXT attempt before it leaves the process", async () => {
+		await fetchOne([
+			{ status: 429, body: "", headers: new Headers({ "retry-after": "120" }) },
+		]);
+		const { result, calls } = await fetchOne([{}]);
+		expect(result.outcome).toBe("failed");
+		// The point of sharing github-budget rather than forking it: a known limit
+		// is not rediscovered by spending another request against it.
+		expect(calls).toHaveLength(0);
+	});
+
+	test("a body over 64 KiB is rejected, with the real size in the message", async () => {
+		const huge = `${UPSTREAM}\n${"x".repeat(MAX_STYLE_BYTES)}`;
+		const { result } = await fetchOne([{ body: huge }]);
+		expect(result.outcome).toBe("failed");
+		if (result.outcome !== "failed") return;
+		expect(result.failure.kind).toBe("too-large");
+		expect(result.failure.detail).toMatch(/KiB/);
+		await noFile();
+	});
+
+	test("a file with no frontmatter is not an output style", async () => {
+		const { result } = await fetchOne([
+			{ body: "# Just a heading\n\nWords.\n" },
+		]);
+		expect(result.outcome).toBe("failed");
+		if (result.outcome !== "failed") return;
+		expect(result.failure.kind).toBe("invalid");
+		await noFile();
+	});
+
+	test("a file with frontmatter but no body is not an output style", async () => {
+		const { result } = await fetchOne([{ body: "---\nname: x\n---\n\n" }]);
+		expect(result.outcome).toBe("failed");
+		if (result.outcome !== "failed") return;
+		expect(result.failure.kind).toBe("invalid");
+		await noFile();
+	});
+
+	test("an HTML response is rejected on content-type", async () => {
+		// The shape a captive portal or a redirect to a login page produces.
+		const { result } = await fetchOne([
+			{ body: "<html>sign in</html>", contentType: "text/html" },
+		]);
+		expect(result.outcome).toBe("failed");
+		if (result.outcome !== "failed") return;
+		expect(result.failure.kind).toBe("invalid");
+		await noFile();
+	});
+
+	test("any other non-2xx reports the status", async () => {
+		const { result } = await fetchOne([{ status: 500, body: "" }]);
+		expect(result.outcome).toBe("failed");
+		if (result.outcome !== "failed") return;
+		expect(result.failure.kind).toBe("http");
+		expect(result.failure.httpStatus).toBe(500);
+	});
+
+	test("304 leaves the existing file untouched", async () => {
+		await fetchOne([{}]);
+		const before = await fs.readFile(
+			join(dir, "attention-span--spartan.md"),
+			"utf8",
+		);
+		const { result } = await fetchOne([{ status: 304, body: "" }], {
+			etag: 'W/"abc"',
+		});
+		expect(result.outcome).toBe("unchanged");
+		expect(
+			await fs.readFile(join(dir, "attention-span--spartan.md"), "utf8"),
+		).toBe(before);
+	});
+});
+
+describe("thrown errors are classified on the code, never on the message", () => {
+	const thrower = (error: unknown) => () => {
+		throw error;
+	};
+
+	test("ENOTFOUND names MagicDNS, because that is what it usually is here", async () => {
+		// A generic "network error" sends the user to GitHub's status page. A
+		// split-DNS resolver hijacking raw.githubusercontent.com looks identical
+		// and has cost real time on this machine before.
+		const error = new TypeError("fetch failed");
+		(error as { cause?: unknown }).cause = { code: "ENOTFOUND" };
+		const { result } = await fetchOne([thrower(error)]);
+		expect(result.outcome).toBe("failed");
+		if (result.outcome !== "failed") return;
+		expect(result.failure.kind).toBe("dns");
+		expect(result.failure.detail).toContain("MagicDNS");
+		expect(result.failure.detail).toContain("dig raw.githubusercontent.com");
+	});
+
+	test("EAI_AGAIN is the same hazard", async () => {
+		const error = new TypeError("fetch failed");
+		(error as { cause?: unknown }).cause = { code: "EAI_AGAIN" };
+		const { result } = await fetchOne([thrower(error)]);
+		if (result.outcome !== "failed") throw new Error("expected a failure");
+		expect(result.failure.kind).toBe("dns");
+	});
+
+	test("no route reads as offline, and says the cache still works", async () => {
+		const error = new TypeError("fetch failed");
+		(error as { cause?: unknown }).cause = { code: "ENETUNREACH" };
+		const { result } = await fetchOne([thrower(error)]);
+		if (result.outcome !== "failed") throw new Error("expected a failure");
+		expect(result.failure.kind).toBe("offline");
+		expect(result.failure.detail).toContain("already fetched still work");
+	});
+
+	test("a timeout names the host rather than blaming the network", async () => {
+		const error = new Error("The operation timed out.");
+		error.name = "TimeoutError";
+		const { result } = await fetchOne([thrower(error)]);
+		if (result.outcome !== "failed") throw new Error("expected a failure");
+		expect(result.failure.kind).toBe("timeout");
+		expect(result.failure.detail).toContain("raw.githubusercontent.com");
+	});
+
+	test("an unclassified throw is reported as such, not guessed at", async () => {
+		const { result } = await fetchOne([thrower(new Error("something odd"))]);
+		if (result.outcome !== "failed") throw new Error("expected a failure");
+		expect(result.failure.kind).toBe("network");
+		expect(result.failure.detail).toContain("something odd");
+	});
+});
+
+describe("coordinate validation happens before any I/O", () => {
+	test("a traversing path throws WITHOUT calling the fetcher", async () => {
+		const { fetcher, calls } = fake([{}]);
+		await expect(
+			fetchCommunityStyle({
+				style: { ...style, path: "output-styles/../../../etc/passwd.md" },
+				source,
+				fetcher,
+				cacheDir: dir,
+			}),
+		).rejects.toThrow(/invalid/);
+		// The assertion that matters: a bad coordinate never becomes a URL.
+		expect(calls).toHaveLength(0);
+	});
+
+	test("a malformed repo throws WITHOUT calling the fetcher", async () => {
+		const { fetcher, calls } = fake([{}]);
+		await expect(
+			fetchCommunityStyle({
+				style,
+				source: { ...source, repo: "not a repo" },
+				fetcher,
+				cacheDir: dir,
+			}),
+		).rejects.toThrow(/invalid/);
+		expect(calls).toHaveLength(0);
+	});
+
+	test("the thrown message names the entry, so the bug is findable", async () => {
+		const { fetcher } = fake([{}]);
+		await expect(
+			fetchCommunityStyle({
+				style: { ...style, path: "README.md" },
+				source,
+				fetcher,
+				cacheDir: dir,
+			}),
+		).rejects.toThrow(/attention-span--spartan/);
+	});
+});
+
+describe("the commit pin", () => {
+	const commitsBody = JSON.stringify([
+		{ sha: "b860c9f8f3c7a1b2c3d4e5f60718293a4b5c6d7e" },
+	]);
+
+	test("resolves a short sha from one API call", async () => {
+		const { fetcher, calls } = fake([
+			{ body: commitsBody, contentType: "application/json" },
+		]);
+		const pin = await resolveCommitPin({ source, fetcher });
+		expect(pin.commit).toBe("b860c9f8f3c7");
+		expect(calls).toHaveLength(1);
+		expect(calls[0].url).toContain(
+			"api.github.com/repos/alexgreensh/attention-span/commits",
+		);
+		expect(calls[0].url).toContain("per_page=1");
+	});
+
+	test("a failed pin never blocks the fetch — the raw content is free", async () => {
+		const { fetcher } = fake([{ status: 500, body: "" }]);
+		const pin = await resolveCommitPin({ source, fetcher });
+		expect(pin.commit).toBeNull();
+		expect(pin.reason).toBeTruthy();
+	});
+
+	test("stops spending API budget once the machine's reserve is reached", async () => {
+		// claudeup must not be the tool that exhausts a machine-wide 60/hr limit
+		// and breaks `gh` for the next hour to fill in one display field.
+		const { fetcher, calls } = fake([
+			{
+				body: commitsBody,
+				headers: new Headers({ "x-ratelimit-remaining": "3" }),
+			},
+		]);
+		expect((await resolveCommitPin({ source, fetcher })).commit).toBe(
+			"b860c9f8f3c7",
+		);
+		const second = await resolveCommitPin({ source, fetcher });
+		expect(second.commit).toBeNull();
+		expect(second.reason).toMatch(/budget/);
+		// One call made, the second refused before it left the process.
+		expect(calls).toHaveLength(1);
+	});
+
+	test("a rate-limited pin is reported as unknown, never as resolved", async () => {
+		const { fetcher } = fake([
+			{
+				status: 403,
+				body: "",
+				headers: new Headers({ "x-ratelimit-remaining": "0" }),
+			},
+		]);
+		const pin = await resolveCommitPin({ source, fetcher });
+		expect(pin.commit).toBeNull();
+		expect(pin.reason).toMatch(/rate limit/i);
+	});
+
+	test("a response with no commits yields no pin rather than a bogus one", async () => {
+		const { fetcher } = fake([{ body: "[]" }]);
+		expect((await resolveCommitPin({ source, fetcher })).commit).toBeNull();
+	});
+});
+
+describe("fetchSource", () => {
+	test("spends ONE API call for the whole batch, whatever its size", async () => {
+		// The budget design in one assertion: 22 styles across 5 repos costs 5 API
+		// calls, not 22. Per-style pinning would exhaust the hourly limit on first
+		// use.
+		const commitsBody = JSON.stringify([{ sha: "0123456789abcdef" }]);
+		const { fetcher, calls } = fake([
+			{ body: commitsBody },
+			{ body: UPSTREAM },
+			{ body: UPSTREAM },
+			{ body: UPSTREAM },
+		]);
+		const styles = ["spartan", "rundown", "attention-kind"].map((slug) => ({
+			...style,
+			id: `attention-span--${slug}`,
+			path: `output-styles/${slug}.md`,
+		}));
+
+		const result = await fetchSource({
+			source,
+			styles,
+			fetcher,
+			cacheDir: dir,
+		});
+
+		expect(result.pin.commit).toBe("0123456789ab");
+		expect(
+			calls.filter((call) => call.url.includes("api.github.com")),
+		).toHaveLength(1);
+		expect(result.results.every((r) => r.result.outcome === "written")).toBe(
+			true,
+		);
+		expect((await fs.readdir(dir)).sort()).toEqual([
+			"attention-span--attention-kind.md",
+			"attention-span--rundown.md",
+			"attention-span--spartan.md",
+		]);
+	});
+
+	test("every style in the batch carries the batch's pin", async () => {
+		const { fetcher } = fake([
+			{ body: JSON.stringify([{ sha: "0123456789abcdef" }]) },
+			{ body: UPSTREAM },
+			{ body: UPSTREAM },
+		]);
+		const styles = ["spartan", "rundown"].map((slug) => ({
+			...style,
+			id: `attention-span--${slug}`,
+			path: `output-styles/${slug}.md`,
+		}));
+		await fetchSource({ source, styles, fetcher, cacheDir: dir });
+		for (const slug of ["spartan", "rundown"]) {
+			const { frontmatter } = splitFrontmatter(
+				await fs.readFile(join(dir, `attention-span--${slug}.md`), "utf8"),
+			);
+			expect(frontmatter["community-commit"]).toBe("0123456789ab");
+		}
+	});
+});