claudeup 4.37.0 → 4.38.0

package/src/services/community-styles.ts

@@ -0,0 +1,1194 @@
+/**
+ * community-styles.ts — fetching a curated third-party output style.
+ *
+ * ## The shape of the thing
+ *
+ * The registry (`src/data/community-styles.ts`) holds coordinates. This module
+ * turns a coordinate into a file in `~/.claude/claudeup/community-styles/`,
+ * stamped with where it came from. Nothing here runs without an explicit user
+ * action, and `loadStyles()` never calls into it — that function runs on every
+ * screen render and makes zero network calls in every phase of this feature.
+ *
+ * ## Two hosts, two budgets
+ *
+ * `raw.githubusercontent.com` serves the style text, needs no auth, and costs
+ * nothing against the API rate limit. `api.github.com` resolves the commit pin
+ * and is the scarce host: 60 requests an hour, unauthenticated, shared by every
+ * process on the machine — `gh`, the skills screen, the marketplace catalogue.
+ * So the pin is resolved ONCE PER REPO, not once per style, and is abandoned
+ * (stamped `unknown`) rather than allowed to exhaust a budget claudeup does not
+ * own. A missing pin never blocks a fetch: the raw content is free and the user
+ * asked for the style.
+ *
+ * Rate-limit state is `github-budget.ts`, unchanged and unforked. It already
+ * gates both hosts, persists cooldowns across launches, and knows that one host
+ * states when the window reopens and the other states nothing.
+ *
+ * ## What is validated, and what is not
+ *
+ * Validated: the coordinate (ours, so a failure throws — it is a bug in a
+ * commit, not a user error), the content type, a 64 KiB ceiling, a non-empty
+ * frontmatter-plus-body parse, and the frontmatter itself, which is REWRITTEN
+ * rather than passed through.
+ *
+ * Not validated: the body. It is arbitrary third-party instruction text that
+ * becomes part of the system prompt when the user applies it. We cannot detect
+ * prompt injection in it and will not pretend to. What bounds it is stated
+ * plainly elsewhere: an explicit action to fetch, a visible diff before any
+ * update is accepted, a pin so a repo that turns malicious later cannot change
+ * what is already on disk, and the integrity block that `composeStyleFile`
+ * appends to every composition.
+ */
+
+import { createHash } from "node:crypto";
+import path from "node:path";
+import fs from "fs-extra";
+import {
+	COMMUNITY_SOURCES,
+	type CommunityStyle,
+	type CommunityStyleSource,
+	coordinateProblem,
+	rawUrlFor,
+	resolveCommunityStyle,
+} from "../data/community-styles.js";
+import {
+	type StoredCommunityCheck,
+	readCommunityChecks,
+	writeCommunityCheck,
+} from "./catalog-cache-store.js";
+import type { StyleFetcher } from "./community-fetcher.js";
+import {
+	type Cooldown,
+	cooldownFor,
+	describeCooldown,
+	hydrateGitHubBudget,
+	recordRateLimit,
+	recordSuccess,
+	remainingFromHeaders,
+} from "./github-budget.js";
+import { splitFrontmatter } from "./styles-manager.js";
+
+// ─── Limits ──────────────────────────────────────────────────────────────────
+
+/**
+ * 64 KiB. Every byte of a style body is re-sent on every single request for as
+ * long as it is applied, so a 5 MB "style" would not be a broken download — it
+ * would be a silent, permanent tax on the user's context window. The rejection
+ * message reports the actual size, because "too large" without a number tells
+ * the user nothing about whether it is marginal or absurd.
+ */
+export const MAX_STYLE_BYTES = 64 * 1024;
+
+/**
+ * Stop spending `api.github.com` budget with fewer than this many requests
+ * left. claudeup must not be the tool that exhausts a machine-wide limit and
+ * breaks `gh` for the next hour to save the user from reading `unknown` in one
+ * field.
+ */
+export const API_RESERVE = 10;
+
+// ─── Errors ──────────────────────────────────────────────────────────────────
+
+/**
+ * Kinds mirror `marketplace-fetcher.ts`'s so the two read alike, plus the two
+ * this feature needs: `too-large` and `dns`.
+ */
+export type CommunityFetchErrorKind =
+	| "rate-limited"
+	| "not-found"
+	| "dns"
+	| "offline"
+	| "timeout"
+	| "too-large"
+	| "invalid"
+	| "http"
+	/** Residual: reached the network stack, failed in a way we did not classify. */
+	| "network";
+
+export interface CommunityFetchFailure {
+	kind: CommunityFetchErrorKind;
+	/** Short, user-facing reason. Rendered verbatim. */
+	detail: string;
+	httpStatus?: number;
+	/** Wall-clock ms when a retry is due, for rate limits. */
+	retryAt?: number;
+}
+
+/**
+ * A 404 is reported as OUR bug, deliberately.
+ *
+ * The set of fetchable coordinates is a constant in a reviewed commit, so a
+ * missing file means the registry entry is stale — the file was renamed or
+ * moved upstream. Telling the user "not found" would invite them to go looking
+ * for something they cannot fix.
+ */
+const NOT_FOUND_DETAIL =
+	"claudeup's registry entry for this style is out of date — the file moved or was renamed upstream. Please report it.";
+
+/**
+ * Called out by name because it has cost real time on this machine before.
+ *
+ * Tailscale MagicDNS can hijack resolution of `raw.githubusercontent.com`,
+ * producing a failure that looks exactly like "GitHub is down" and is not. A
+ * generic "network error" here sends the user to check GitHub's status page.
+ */
+const DNS_DETAIL = (host: string) =>
+	`Could not resolve ${host}. A VPN or split-DNS resolver can hijack this hostname — Tailscale MagicDNS is a known cause. Check with \`dig ${host}\`; quitting Tailscale or adding an /etc/hosts override clears it.`;
+
+/** Resolution failures. Distinguished from "no route" — see DNS_DETAIL. */
+const DNS_CODES = new Set([
+	"ENOTFOUND",
+	"EAI_AGAIN",
+	"EAI_NODATA",
+	"EAI_NONAME",
+	"ERR_TLS_CERT_ALTNAME_INVALID",
+]);
+
+/** This machine has no route at all, as opposed to GitHub misbehaving. */
+const OFFLINE_CODES = new Set([
+	"ENETUNREACH",
+	"ENETDOWN",
+	"EHOSTUNREACH",
+	"ECONNREFUSED",
+]);
+
+/**
+ * Classify on the error's `code`, walking the `cause` chain, never on message
+ * text. `fetch` wraps the real error in a bare `TypeError: fetch failed`, and
+ * matching on that string breaks the moment a runtime rewords it.
+ */
+function errorCode(error: unknown): string | null {
+	let current: unknown = error;
+	for (let depth = 0; depth < 6 && current; depth++) {
+		const code = (current as { code?: unknown }).code;
+		if (typeof code === "string") return code;
+		current = (current as { cause?: unknown }).cause;
+	}
+	return null;
+}
+
+function classifyThrown(error: unknown, host: string): CommunityFetchFailure {
+	const name = (error as { name?: string } | null)?.name;
+	if (name === "TimeoutError" || name === "AbortError") {
+		return { kind: "timeout", detail: `${host} did not respond in 10s` };
+	}
+	const code = errorCode(error);
+	if (code && DNS_CODES.has(code)) {
+		return { kind: "dns", detail: DNS_DETAIL(host) };
+	}
+	if (code && OFFLINE_CODES.has(code)) {
+		return {
+			kind: "offline",
+			detail:
+				"no network — the styles you already fetched still work, and still compose",
+		};
+	}
+	const message = error instanceof Error ? error.message : String(error);
+	return { kind: "network", detail: `${host}: ${message}` };
+}
+
+function rateLimited(
+	cooldown: Cooldown,
+	status?: number,
+): CommunityFetchFailure {
+	return {
+		kind: "rate-limited",
+		detail: describeCooldown(cooldown),
+		httpStatus: status,
+		retryAt: cooldown.until,
+	};
+}
+
+// ─── The API budget, as seen by this feature ─────────────────────────────────
+
+/**
+ * Last `x-ratelimit-remaining` we were told, or null if we have not asked.
+ *
+ * Module state rather than a parameter because the reserve is a property of the
+ * MACHINE's shared budget, not of one batch: a five-repo sweep must stop after
+ * the call that takes it under the line, not rediscover the limit five times.
+ */
+let lastKnownApiRemaining: number | null = null;
+
+/** Test seam, and what an explicit refresh should call. */
+export function resetCommunityApiHeadroom(): void {
+	lastKnownApiRemaining = null;
+}
+
+/** What we last heard about the shared `api.github.com` budget. */
+export function apiRemaining(): number | null {
+	return lastKnownApiRemaining;
+}
+
+export interface CommitPin {
+	/** Short sha, or null when we could not resolve one. Never blocks a fetch. */
+	commit: string | null;
+	/** Why it is null, for the detail panel. Absent on success. */
+	reason?: string;
+}
+
+/**
+ * Resolve a repo's styles directory to the latest commit that touched it.
+ *
+ * ONE API call for a whole batch. The content of any file in that directory at
+ * branch head is identical to its content at that commit, so this is a correct
+ * and reproducible pin for every style in the repo — verified in the design
+ * spike, where a sha-addressed fetch was byte-identical to a branch fetch.
+ */
+export async function resolveCommitPin(args: {
+	source: CommunityStyleSource;
+	fetcher: StyleFetcher;
+	now?: number;
+}): Promise<CommitPin> {
+	const { source, fetcher } = args;
+	const host = "api.github.com" as const;
+
+	if (lastKnownApiRemaining !== null && lastKnownApiRemaining < API_RESERVE) {
+		return {
+			commit: null,
+			reason: `GitHub API budget nearly spent (${lastKnownApiRemaining} left) — holding the rest back for other tools`,
+		};
+	}
+
+	await hydrateGitHubBudget();
+	const cooling = cooldownFor(host, args.now);
+	if (cooling)
+		return { commit: null, reason: describeCooldown(cooling, args.now) };
+
+	const query = new URLSearchParams({ per_page: "1", path: source.dir });
+	const url = `https://${host}/repos/${source.repo}/commits?${query}`;
+
+	try {
+		const response = await fetcher(url, {
+			accept: "application/vnd.github+json",
+		});
+
+		const remaining = remainingFromHeaders(response.headers);
+		if (remaining !== null) lastKnownApiRemaining = remaining;
+
+		if (response.status === 429 || response.status === 403) {
+			const cooldown = recordRateLimit(host, response.headers, args.now);
+			return { commit: null, reason: describeCooldown(cooldown, args.now) };
+		}
+		if (response.status !== 200) {
+			return {
+				commit: null,
+				reason: `HTTP ${response.status} resolving the commit pin`,
+			};
+		}
+
+		recordSuccess(host);
+		const parsed = JSON.parse(response.body) as Array<{ sha?: unknown }>;
+		const sha = Array.isArray(parsed) ? parsed[0]?.sha : undefined;
+		if (typeof sha !== "string" || !/^[0-9a-f]{7,40}$/.test(sha)) {
+			return {
+				commit: null,
+				reason: "GitHub returned no commit for this path",
+			};
+		}
+		return { commit: sha.slice(0, 12) };
+	} catch (error) {
+		return { commit: null, reason: classifyThrown(error, host).detail };
+	}
+}
+
+// ─── Fetching a style ────────────────────────────────────────────────────────
+
+export interface FetchedCommunityStyleFile {
+	/** Coordinate id, e.g. `attention-span--spartan`. */
+	id: string;
+	/** Where it was written. */
+	path: string;
+	/** `sha256:<64 hex>` over the RAW UPSTREAM BYTES — see the note in `write`. */
+	sha256: string;
+	/** Short commit sha, or null when the pin could not be resolved. */
+	commit: string | null;
+	/** Upstream's own description, kept verbatim. */
+	description: string;
+	bytes: number;
+}
+
+export type CommunityFetchResult =
+	| { outcome: "written"; file: FetchedCommunityStyleFile }
+	/** 304: upstream says our copy is current. Nothing was rewritten. */
+	| { outcome: "unchanged"; path: string }
+	| { outcome: "failed"; failure: CommunityFetchFailure };
+
+export interface FetchCommunityStyleArgs {
+	style: CommunityStyle;
+	source: CommunityStyleSource;
+	/** Required, never defaulted — that is what stops a test reaching GitHub. */
+	fetcher: StyleFetcher;
+	/** Resolved cache directory. Callers get it from `communityCacheDirOrNull`. */
+	cacheDir: string;
+	/** Resolved once per batch by `resolveCommitPin`. */
+	commit?: string | null;
+	/** Conditional GET, for the staleness path. */
+	etag?: string | null;
+	now?: number;
+}
+
+/**
+ * Fetch one style and write it into the cache directory.
+ *
+ * Throws only for a bad coordinate, which is our data and therefore our bug.
+ * Everything a user or a network can cause comes back as a classified failure,
+ * because a thrown error at a keypress is a stack trace and a classified one is
+ * a sentence.
+ */
+export async function fetchCommunityStyle(
+	args: FetchCommunityStyleArgs,
+): Promise<CommunityFetchResult> {
+	const { style, source, fetcher, cacheDir } = args;
+
+	// Before ANY I/O. A `..` reaching the URL builder would be both an SSRF and
+	// a traversal in the destination filename.
+	const problem = coordinateProblem(style, source);
+	if (problem) {
+		throw new Error(
+			`community registry entry "${style.id}" is invalid: ${problem}`,
+		);
+	}
+
+	const host = "raw.githubusercontent.com" as const;
+	await hydrateGitHubBudget();
+	const cooling = cooldownFor(host, args.now);
+	if (cooling) return { outcome: "failed", failure: rateLimited(cooling) };
+
+	const url = rawUrlFor(style, source);
+	let response: Awaited<ReturnType<StyleFetcher>>;
+	try {
+		response = await fetcher(url, { etag: args.etag });
+	} catch (error) {
+		return { outcome: "failed", failure: classifyThrown(error, host) };
+	}
+
+	if (response.status === 304) {
+		return { outcome: "unchanged", path: cachePathFor(cacheDir, style.id) };
+	}
+	if (response.status === 429 || response.status === 403) {
+		const cooldown = recordRateLimit(host, response.headers, args.now);
+		return {
+			outcome: "failed",
+			failure: rateLimited(cooldown, response.status),
+		};
+	}
+	if (response.status === 404) {
+		return {
+			outcome: "failed",
+			failure: { kind: "not-found", detail: NOT_FOUND_DETAIL, httpStatus: 404 },
+		};
+	}
+	if (response.status < 200 || response.status >= 300) {
+		return {
+			outcome: "failed",
+			failure: {
+				kind: "http",
+				detail: `HTTP ${response.status} from ${host}`,
+				httpStatus: response.status,
+			},
+		};
+	}
+
+	// Absent content-type is not an error — a fake omits it and raw.github always
+	// sends one. Present-and-wrong is: it means we asked for the wrong thing.
+	if (response.contentType && !response.contentType.includes("text/plain")) {
+		return {
+			outcome: "failed",
+			failure: {
+				kind: "invalid",
+				detail: `unexpected content-type "${response.contentType}" — expected text/plain`,
+			},
+		};
+	}
+
+	const bytes = Buffer.byteLength(response.body, "utf8");
+	if (bytes > MAX_STYLE_BYTES) {
+		return {
+			outcome: "failed",
+			failure: {
+				kind: "too-large",
+				detail: `${describeBytes(bytes)} exceeds the ${describeBytes(MAX_STYLE_BYTES)} limit — a style this size would be re-sent on every request`,
+			},
+		};
+	}
+
+	const { frontmatter, body } = splitFrontmatter(response.body);
+	if (Object.keys(frontmatter).length === 0 || body.trim().length === 0) {
+		return {
+			outcome: "failed",
+			failure: {
+				kind: "invalid",
+				detail:
+					"upstream file is not a valid output style — it has no frontmatter, or no body",
+			},
+		};
+	}
+
+	recordSuccess(host);
+
+	const file = await writeCachedStyle({
+		cacheDir,
+		style,
+		source,
+		upstream: response.body,
+		description: frontmatter.description ?? "",
+		body,
+		commit: args.commit ?? null,
+		now: args.now,
+	});
+	return { outcome: "written", file };
+}
+
+export interface FetchSourceResult {
+	source: CommunityStyleSource;
+	pin: CommitPin;
+	results: Array<{ style: CommunityStyle; result: CommunityFetchResult }>;
+}
+
+/**
+ * Fetch one or more styles from a single repo.
+ *
+ * The batch exists for the pin: one `api.github.com` call serves every style in
+ * the repo, which is the difference between ~8% of the machine's hourly budget
+ * and all of it.
+ */
+export async function fetchSource(args: {
+	source: CommunityStyleSource;
+	styles: CommunityStyle[];
+	fetcher: StyleFetcher;
+	cacheDir: string;
+	now?: number;
+}): Promise<FetchSourceResult> {
+	const pin = await resolveCommitPin({
+		source: args.source,
+		fetcher: args.fetcher,
+		now: args.now,
+	});
+
+	const results: FetchSourceResult["results"] = [];
+	for (const style of args.styles) {
+		results.push({
+			style,
+			result: await fetchCommunityStyle({
+				style,
+				source: args.source,
+				fetcher: args.fetcher,
+				cacheDir: args.cacheDir,
+				commit: pin.commit,
+				now: args.now,
+			}),
+		});
+	}
+	return { source: args.source, pin, results };
+}
+
+// ─── Writing ─────────────────────────────────────────────────────────────────
+
+/** `<sourceId>--<slug>.md`, flat. The id is already filename-safe; see §2.1. */
+export function cachePathFor(cacheDir: string, id: string): string {
+	return path.join(cacheDir, `${id}.md`);
+}
+
+function describeBytes(bytes: number): string {
+	return bytes < 1024 ? `${bytes} B` : `${Math.round(bytes / 1024)} KiB`;
+}
+
+/**
+ * Emit a value that survives `splitFrontmatter`'s round trip.
+ *
+ * Always quoted: an upstream description routinely carries `: `, which YAML
+ * reads as a nested mapping, and the frontmatter then fails to parse. Newlines
+ * are collapsed because the parser is line-based — a multi-line value would
+ * silently truncate at the first newline and leave the rest as a stray key.
+ */
+function yamlScalar(value: string): string {
+	const flat = value.replace(/\s+/g, " ").trim();
+	return `"${flat.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/** Local date, matching `fileDate()` — the user reads this against their own calendar. */
+function localDate(now: number): string {
+	const date = new Date(now);
+	const pad = (n: number) => String(n).padStart(2, "0");
+	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+async function writeCachedStyle(args: {
+	cacheDir: string;
+	style: CommunityStyle;
+	source: CommunityStyleSource;
+	/** The bytes as served, for the content hash. */
+	upstream: string;
+	description: string;
+	body: string;
+	commit: string | null;
+	now?: number;
+}): Promise<FetchedCommunityStyleFile> {
+	const { cacheDir, style, source, body } = args;
+	const now = args.now ?? Date.now();
+
+	// Hashed over the RAW UPSTREAM BYTES, not over what we write. The staleness
+	// check compares this against a fresh raw fetch; hashing our rewritten copy
+	// would mean it never matched and every style read as changed forever.
+	const sha256 = `sha256:${createHash("sha256").update(args.upstream).digest("hex")}`;
+
+	// Upstream frontmatter is REWRITTEN, not passed through. We keep exactly one
+	// upstream value — `description` — and force `keep-coding-instructions`.
+	// A style that set it false would strip Claude Code's coding-discipline
+	// block; `composeStyleFile` already forces the key on the composed file, so
+	// this is defence in depth, and it also drops any harness-recognised key we
+	// have not heard of yet.
+	const lines = [
+		"---",
+		`name: ${style.id}`,
+		`description: ${yamlScalar(args.description)}`,
+		"keep-coding-instructions: true",
+		// THE marker. Classification is by this key, never by directory — a copy
+		// the user moves into ~/.claude/output-styles/ still says where the words
+		// came from.
+		`community-source: ${source.repo}`,
+		`community-path: ${style.path}`,
+		`community-ref: ${source.ref}`,
+		`community-commit: ${args.commit ?? "unknown"}`,
+		`community-sha256: ${sha256}`,
+		`community-fetched: ${localDate(now)}`,
+		`community-licence: ${source.licence ?? "unlicensed"}`,
+		`community-author: ${source.author}`,
+		"---",
+		"",
+		body,
+		"",
+	];
+	const contents = `${lines
+		.join("\n")
+		.replace(/\n{3,}/g, "\n\n")
+		.trimEnd()}\n`;
+
+	const file = cachePathFor(cacheDir, style.id);
+	await fs.ensureDir(cacheDir);
+	// Temp + rename, same as catalog-cache-store: a crash mid-write must not
+	// leave a half-written style that the next load reads as a valid one.
+	const tmp = `${file}.${process.pid}.tmp`;
+	await fs.writeFile(tmp, contents, "utf8");
+	await fs.rename(tmp, file);
+
+	return {
+		id: style.id,
+		path: file,
+		sha256,
+		commit: args.commit ?? null,
+		description: args.description,
+		bytes: Buffer.byteLength(contents, "utf8"),
+	};
+}
+
+// ─── Fetching a set of styles ────────────────────────────────────────────────
+
+export interface FetchManyResult {
+	written: FetchedCommunityStyleFile[];
+	unchanged: string[];
+	failed: Array<{ id: string; label: string; failure: CommunityFetchFailure }>;
+	/** Coordinate ids that name no registry entry. Ours to fix, so they are named. */
+	unknown: string[];
+}
+
+/**
+ * Fetch every named coordinate, grouped so each repo costs ONE api.github.com
+ * call.
+ *
+ * The grouping is the whole point and is easy to lose: fetching twenty-two
+ * styles one at a time would resolve twenty-two pins and spend a third of the
+ * machine's hourly budget, where five batched pins spend 8%.
+ */
+export async function fetchCommunityStyles(args: {
+	/** Coordinate ids WITHOUT the `community:` prefix. */
+	ids: string[];
+	fetcher: StyleFetcher;
+	cacheDir: string;
+	now?: number;
+}): Promise<FetchManyResult> {
+	const out: FetchManyResult = {
+		written: [],
+		unchanged: [],
+		failed: [],
+		unknown: [],
+	};
+
+	const bySource = new Map<
+		string,
+		{ source: CommunityStyleSource; styles: CommunityStyle[] }
+	>();
+	for (const id of args.ids) {
+		const resolved = resolveCommunityStyle(id);
+		if (!resolved) {
+			out.unknown.push(id);
+			continue;
+		}
+		const group = bySource.get(resolved.source.id) ?? {
+			source: resolved.source,
+			styles: [],
+		};
+		group.styles.push(resolved.style);
+		bySource.set(resolved.source.id, group);
+	}
+
+	for (const { source, styles } of bySource.values()) {
+		const batch = await fetchSource({
+			source,
+			styles,
+			fetcher: args.fetcher,
+			cacheDir: args.cacheDir,
+			now: args.now,
+		});
+		for (const { style, result } of batch.results) {
+			if (result.outcome === "written") {
+				out.written.push(result.file);
+				// A re-fetch supersedes any update that was waiting to be accepted:
+				// the live file now holds the current bytes. Leaving the pending
+				// file and its store entry behind would keep the row advertising
+				// "(new)" for an update the user has already taken.
+				await discardPending(args.cacheDir, style.id, result.file.sha256);
+			} else if (result.outcome === "unchanged") out.unchanged.push(style.id);
+			else {
+				out.failed.push({
+					id: style.id,
+					label: style.displayName,
+					failure: result.failure,
+				});
+			}
+		}
+	}
+
+	return out;
+}
+
+/**
+ * Drop a waiting update and record the bytes now installed.
+ *
+ * Called after a direct fetch, which is the case the store cannot infer: the
+ * file on disk changed without a check running, so the recorded sha and any
+ * pending marker are both out of date the instant the write lands.
+ */
+async function discardPending(
+	cacheDir: string,
+	id: string,
+	sha256: string,
+): Promise<void> {
+	await fs.remove(pendingPathFor(cacheDir, id));
+	const resolved = resolveCommunityStyle(id);
+	if (!resolved) return;
+	const check = (await readCommunityChecks())[resolved.source.id];
+	if (!check) return;
+	check.styles[id] = { sha256 };
+	await writeCommunityCheck(resolved.source.id, check);
+}
+
+/**
+ * The one line to show a user when a fetch failed.
+ *
+ * Per KIND, not one generic wrapper, because the kinds differ in who has to do
+ * something about it: a 404 is our registry being wrong, a rate limit has a
+ * documented escape hatch, a DNS failure is usually a VPN on this machine, and
+ * `too-large` / `invalid` are refusals rather than failures. Collapsing them to
+ * "could not fetch X" would throw all of that away at the exact moment the user
+ * needs it.
+ */
+export function describeCommunityFailure(
+	failure: CommunityFetchFailure,
+	label: string,
+): string {
+	switch (failure.kind) {
+		case "rate-limited":
+			return `${label} not fetched — ${failure.detail}. Set GITHUB_TOKEN to raise the limit.`;
+		case "not-found":
+			// Reads as our bug because it is one: the coordinate set is a constant in
+			// a reviewed commit, so a 404 means the registry entry went stale.
+			return `${label}: ${failure.detail}`;
+		case "dns":
+			// Stands alone: the detail is three sentences of diagnosis, and a label
+			// in front of it would push the useful half off a one-row status line.
+			return failure.detail;
+		case "offline":
+			return `${label} not fetched — ${failure.detail}`;
+		case "timeout":
+			return `${label} not fetched — ${failure.detail}`;
+		case "too-large":
+			return `${label} refused — ${failure.detail}`;
+		case "invalid":
+			return `${label} refused — ${failure.detail}`;
+		case "http":
+			return `${label} not fetched — ${failure.detail}`;
+		case "network":
+			return `${label} not fetched — ${failure.detail}`;
+	}
+}
+
+// ─── Staleness: advisory, two-phase, never automatic ─────────────────────────
+
+/**
+ * 24 hours, matching image-generate's staleness precedent in the root CLAUDE.md.
+ *
+ * The TTL is not only a "when to re-check" rule — it is also a "how long may we
+ * keep SAYING up-to-date" rule. A check from three days ago is evidence about
+ * three days ago, so past this window a recorded pass degrades to `unknown`
+ * rather than continuing to assert currency. See `statusFromStore`.
+ */
+export const COMMUNITY_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+
+export type CommunityUpstreamState =
+	/** Verified current: phase A sha matched, or phase B bytes were identical. */
+	| "up-to-date"
+	/** Phase B found different bytes. They are in `.pending/`, not installed. */
+	| "update-available"
+	/** Never checked, TTL expired, rate-limited, offline, or any error. */
+	| "unknown";
+
+export interface CommunityUpstreamStatus {
+	state: CommunityUpstreamState;
+	/** One line, rendered verbatim. For `unknown` this is the REASON. */
+	detail: string;
+	/** Wall-clock ms of the check this came from, or null if there was none. */
+	checkedAt: number | null;
+	/** Lines that differ between the installed copy and the pending one. */
+	changedLines?: number;
+}
+
+/** Downloaded-but-not-accepted updates. A subdirectory, so discovery skips it. */
+export function pendingDirFor(cacheDir: string): string {
+	return path.join(cacheDir, ".pending");
+}
+
+export function pendingPathFor(cacheDir: string, id: string): string {
+	return cachePathFor(pendingDirFor(cacheDir), id);
+}
+
+/**
+ * Insertions plus deletions between two texts, by line.
+ *
+ * A real LCS rather than a length difference, because the number is shown to the
+ * user as the reason to accept or refuse an update, and "12 lines changed" for a
+ * reordering that changed nothing would be an invitation to stop trusting it.
+ * Bounded: past a million cell pairs the DP is abandoned for the cheap estimate,
+ * which cannot happen for a file capped at 64 KiB but keeps the function safe if
+ * that cap ever moves.
+ */
+export function countChangedLines(before: string, after: string): number {
+	const a = before.split("\n");
+	const b = after.split("\n");
+	if (a.length * b.length > 1_000_000) {
+		return Math.abs(a.length - b.length) + Math.min(a.length, b.length);
+	}
+
+	// Trim the common head and tail first: edits cluster, and this usually leaves
+	// the DP a few lines instead of a few hundred.
+	let head = 0;
+	while (head < a.length && head < b.length && a[head] === b[head]) head++;
+	let tail = 0;
+	while (
+		tail < a.length - head &&
+		tail < b.length - head &&
+		a[a.length - 1 - tail] === b[b.length - 1 - tail]
+	) {
+		tail++;
+	}
+	const left = a.slice(head, a.length - tail);
+	const right = b.slice(head, b.length - tail);
+	if (left.length === 0 || right.length === 0) {
+		return left.length + right.length;
+	}
+
+	const table: number[][] = Array.from({ length: left.length + 1 }, () =>
+		new Array<number>(right.length + 1).fill(0),
+	);
+	for (let i = 1; i <= left.length; i++) {
+		for (let j = 1; j <= right.length; j++) {
+			table[i][j] =
+				left[i - 1] === right[j - 1]
+					? table[i - 1][j - 1] + 1
+					: Math.max(table[i - 1][j], table[i][j - 1]);
+		}
+	}
+	const common = table[left.length][right.length];
+	return left.length - common + (right.length - common);
+}
+
+/** A cached style as the checker needs it: an id and the bytes we hold. */
+export interface CachedCommunityStyle {
+	/** Coordinate id, `attention-span--spartan`. */
+	id: string;
+	/** `sha256:…` from the file's own frontmatter, or null if it carries none. */
+	sha256: string | null;
+}
+
+/**
+ * What the store alone can say about one style, with no network call.
+ *
+ * `up-to-date` is the only state with an expiry. A pending update is a FILE on
+ * disk — a fact, not an inference — so it keeps reporting `update-available`
+ * however old the check was. Currency is the claim that decays, and letting a
+ * three-day-old pass keep asserting it is exactly the fail-closed clause this
+ * design exists to honour.
+ */
+function statusFromStore(
+	check: StoredCommunityCheck | undefined,
+	id: string,
+	now: number,
+): CommunityUpstreamStatus {
+	const entry = check?.styles[id];
+	if (!check || !entry) {
+		return { state: "unknown", detail: "not checked", checkedAt: null };
+	}
+	if (entry.pendingSha256) {
+		return {
+			state: "update-available",
+			detail: `newer version available — ${entry.pendingLines ?? 0} lines changed, press f to accept`,
+			checkedAt: check.checkedAt,
+			changedLines: entry.pendingLines ?? 0,
+		};
+	}
+	if (now - check.checkedAt > COMMUNITY_CHECK_TTL_MS) {
+		return {
+			state: "unknown",
+			detail: "not checked in the last 24h — press u",
+			checkedAt: check.checkedAt,
+		};
+	}
+	return {
+		state: "up-to-date",
+		detail: "up to date",
+		checkedAt: check.checkedAt,
+	};
+}
+
+/**
+ * Every recorded status, keyed by coordinate id. Reads the store, nothing else.
+ *
+ * This is what the screen renders. It makes no network call in any phase, which
+ * is what keeps the update advisory an advisory: nothing is checked because a
+ * panel was drawn.
+ */
+export async function readCommunityStatuses(
+	now: number = Date.now(),
+): Promise<Record<string, CommunityUpstreamStatus>> {
+	const checks = await readCommunityChecks();
+	const out: Record<string, CommunityUpstreamStatus> = {};
+	for (const check of Object.values(checks)) {
+		for (const id of Object.keys(check.styles)) {
+			out[id] = statusFromStore(check, id, now);
+		}
+	}
+	return out;
+}
+
+export interface CheckSourceResult {
+	source: CommunityStyleSource;
+	statuses: Record<string, CommunityUpstreamStatus>;
+	/** api.github.com calls this check actually made: 1, or 0 when served by TTL. */
+	apiCalls: number;
+}
+
+/**
+ * Ask whether a repo's cached styles have moved. Advisory, never automatic.
+ *
+ * Two phases, priced deliberately:
+ *
+ *   A  one `GET /repos/{repo}/commits?path={dir}` for the WHOLE repo — did
+ *      anything in its styles directory move since we last looked?
+ *   B  only for a repo that moved: a free raw GET per cached style, sha256
+ *      compared against the bytes we hold.
+ *
+ * Fifty-seven per-style API calls would exhaust the machine's shared hourly
+ * budget on first use and break `gh` for everything else on the box. Five
+ * per-repo calls plus free raw drilldown costs about 8% of it.
+ *
+ * Phase B DOWNLOADS into `.pending/` and stops. Installing it silently would put
+ * new third-party words into the system prompt of a style that is already
+ * applied — which is why "never silently re-fetch" is a security property here
+ * and not a UX preference.
+ */
+export async function checkSourceForUpdates(args: {
+	source: CommunityStyleSource;
+	cached: CachedCommunityStyle[];
+	fetcher: StyleFetcher;
+	cacheDir: string;
+	now?: number;
+	/** Skip the TTL. `u` and `U` are explicit requests, so they always force. */
+	force?: boolean;
+}): Promise<CheckSourceResult> {
+	const { source, cached, fetcher, cacheDir } = args;
+	const now = args.now ?? Date.now();
+	const statuses: Record<string, CommunityUpstreamStatus> = {};
+
+	if (cached.length === 0) return { source, statuses, apiCalls: 0 };
+
+	const stored = (await readCommunityChecks())[source.id];
+
+	if (
+		!args.force &&
+		stored &&
+		now - stored.checkedAt <= COMMUNITY_CHECK_TTL_MS
+	) {
+		for (const style of cached) {
+			statuses[style.id] = statusFromStore(stored, style.id, now);
+		}
+		return { source, statuses, apiCalls: 0 };
+	}
+
+	// ── Phase A ──────────────────────────────────────────────────────────────
+	const pin = await resolveCommitPin({ source, fetcher, now });
+	if (!pin.commit) {
+		// FAIL CLOSED. A rate limit, an offline box or a budget reserve produces
+		// `unknown` with the reason — never a quiet "up to date", which is the one
+		// answer we are not entitled to give when we could not look.
+		for (const style of cached) {
+			statuses[style.id] = {
+				state: "unknown",
+				detail: pin.reason ?? "could not reach GitHub",
+				checkedAt: stored?.checkedAt ?? null,
+			};
+		}
+		return { source, statuses, apiCalls: 1 };
+	}
+
+	if (stored && stored.dirHeadSha === pin.commit) {
+		// Nothing in the directory moved, so nothing in it can have changed. This
+		// is the branch that makes the whole design affordable — the common case
+		// costs one API call for the repo and no raw fetches at all.
+		const next: StoredCommunityCheck = {
+			checkedAt: now,
+			dirHeadSha: pin.commit,
+			styles: { ...stored.styles },
+		};
+		await writeCommunityCheck(source.id, next);
+		for (const style of cached) {
+			statuses[style.id] = statusFromStore(next, style.id, now);
+		}
+		return { source, statuses, apiCalls: 1 };
+	}
+
+	// ── Phase B ──────────────────────────────────────────────────────────────
+	const pendingDir = pendingDirFor(cacheDir);
+	const nextStyles: StoredCommunityCheck["styles"] = {};
+	/**
+	 * False once any style in this batch could not be verified.
+	 *
+	 * An incomplete check must not be RECORDED as a complete one. If it were, the
+	 * new `dirHeadSha` would be stored, the next phase A would 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.
+	 */
+	let complete = true;
+
+	for (const entry of cached) {
+		const resolved = resolveCommunityStyle(entry.id);
+		if (!resolved) {
+			// Fetched before the entry was retired, or from a registry we no longer
+			// ship. There is no coordinate to re-fetch, so there is nothing to say.
+			statuses[entry.id] = {
+				state: "unknown",
+				detail: "no longer in claudeup's registry — this copy still works",
+				checkedAt: stored?.checkedAt ?? null,
+			};
+			// Not a failure of the check: there is no coordinate, so there is
+			// nothing this check could ever have told us about it.
+			continue;
+		}
+		if (!entry.sha256) {
+			statuses[entry.id] = {
+				state: "unknown",
+				detail: "this copy records no content hash — press f to re-fetch it",
+				checkedAt: stored?.checkedAt ?? null,
+			};
+			continue;
+		}
+
+		// Deliberately the same call the fetch path uses, writing into `.pending/`
+		// rather than over the live file. Reimplementing the download here would
+		// fork the validation, the frontmatter rewriting and the error taxonomy —
+		// three things that must not differ between "fetch" and "check for a
+		// newer fetch".
+		const result = await fetchCommunityStyle({
+			style: resolved.style,
+			source,
+			fetcher,
+			cacheDir: pendingDir,
+			commit: pin.commit,
+			now,
+		});
+
+		if (result.outcome === "failed") {
+			statuses[entry.id] = {
+				state: "unknown",
+				detail: describeCommunityFailure(
+					result.failure,
+					resolved.style.displayName,
+				),
+				checkedAt: stored?.checkedAt ?? null,
+			};
+			// Left OUT of the recorded styles, so the next check cannot infer a pass
+			// for it from the directory sha alone.
+			complete = false;
+			continue;
+		}
+		if (result.outcome === "unchanged") {
+			statuses[entry.id] = {
+				state: "up-to-date",
+				detail: "up to date",
+				checkedAt: now,
+			};
+			nextStyles[entry.id] = { sha256: entry.sha256 };
+			continue;
+		}
+
+		if (result.file.sha256 === entry.sha256) {
+			// The directory moved but this file did not — a commit touching one of
+			// the repo's other styles. Remove the download; keeping it would leave a
+			// pending update that is byte-identical to what is installed.
+			await fs.remove(result.file.path);
+			statuses[entry.id] = {
+				state: "up-to-date",
+				detail: "up to date",
+				checkedAt: now,
+			};
+			nextStyles[entry.id] = { sha256: entry.sha256 };
+			continue;
+		}
+
+		const changedLines = await diffAgainstInstalled(
+			cachePathFor(cacheDir, entry.id),
+			result.file.path,
+		);
+		nextStyles[entry.id] = {
+			sha256: entry.sha256,
+			pendingSha256: result.file.sha256,
+			pendingLines: changedLines,
+		};
+		statuses[entry.id] = {
+			state: "update-available",
+			detail: `newer version available — ${changedLines} lines changed, press f to accept`,
+			checkedAt: now,
+			changedLines,
+		};
+	}
+
+	await writeCommunityCheck(source.id, {
+		checkedAt: now,
+		// An incomplete pass keeps the OLD directory sha — or none, if there was
+		// none — so the next check drills in again instead of short-circuiting on
+		// a head we never finished verifying against.
+		dirHeadSha: complete ? pin.commit : (stored?.dirHeadSha ?? ""),
+		styles: nextStyles,
+	});
+
+	return { source, statuses, apiCalls: 1 };
+}
+
+/** Lines differing between the installed copy and a pending one. 0 if unreadable. */
+async function diffAgainstInstalled(
+	installed: string,
+	pending: string,
+): Promise<number> {
+	try {
+		const [before, after] = await Promise.all([
+			fs.readFile(installed, "utf8"),
+			fs.readFile(pending, "utf8"),
+		]);
+		// Bodies only. The frontmatter differs on every fetch — `community-fetched`
+		// and `community-commit` change whether or not a single word did — so
+		// counting it would report "3 lines changed" for an identical style.
+		return countChangedLines(
+			splitFrontmatter(before).body,
+			splitFrontmatter(after).body,
+		);
+	} catch {
+		return 0;
+	}
+}
+
+export interface CheckAllResult {
+	statuses: Record<string, CommunityUpstreamStatus>;
+	/** Total api.github.com calls. At most one per repo with a cached style. */
+	apiCalls: number;
+}
+
+/**
+ * Check every repo that has at least one cached style.
+ *
+ * At most five API calls today, and at most one per repo however many styles the
+ * registry grows to — the cost is a function of REPOS, which is the property the
+ * whole two-phase design is protecting.
+ */
+export async function checkAllSources(args: {
+	cached: CachedCommunityStyle[];
+	fetcher: StyleFetcher;
+	cacheDir: string;
+	now?: number;
+	force?: boolean;
+}): Promise<CheckAllResult> {
+	const bySource = new Map<string, CachedCommunityStyle[]>();
+	for (const entry of args.cached) {
+		const resolved = resolveCommunityStyle(entry.id);
+		if (!resolved) continue;
+		const group = bySource.get(resolved.source.id) ?? [];
+		group.push(entry);
+		bySource.set(resolved.source.id, group);
+	}
+
+	const statuses: Record<string, CommunityUpstreamStatus> = {};
+	let apiCalls = 0;
+	for (const [sourceId, cached] of bySource) {
+		const source = COMMUNITY_SOURCES.find((s) => s.id === sourceId);
+		if (!source) continue;
+		const result = await checkSourceForUpdates({
+			source,
+			cached,
+			fetcher: args.fetcher,
+			cacheDir: args.cacheDir,
+			now: args.now,
+			force: args.force,
+		});
+		Object.assign(statuses, result.statuses);
+		apiCalls += result.apiCalls;
+	}
+	return { statuses, apiCalls };
+}
+
+export type AcceptPendingResult =
+	| { outcome: "accepted"; path: string }
+	| { outcome: "none" };
+
+/**
+ * Install a downloaded update over the copy in use.
+ *
+ * The one place in this feature that changes the bytes of a style that may be
+ * applied right now, and it happens only on a keypress with a changed-line count
+ * already on screen. A rename, not a re-fetch: the user accepts the text they
+ * were shown the diff for, not whatever upstream serves a second later.
+ */
+export async function acceptPendingUpdate(args: {
+	cacheDir: string;
+	/** Coordinate id, without the `community:` prefix. */
+	id: string;
+}): Promise<AcceptPendingResult> {
+	const pending = pendingPathFor(args.cacheDir, args.id);
+	if (!(await fs.pathExists(pending))) return { outcome: "none" };
+
+	const live = cachePathFor(args.cacheDir, args.id);
+	const { frontmatter } = splitFrontmatter(await fs.readFile(pending, "utf8"));
+	await fs.move(pending, live, { overwrite: true });
+
+	const resolved = resolveCommunityStyle(args.id);
+	if (resolved) {
+		const checks = await readCommunityChecks();
+		const check = checks[resolved.source.id];
+		if (check) {
+			check.styles[args.id] = {
+				sha256: frontmatter["community-sha256"] ?? "",
+			};
+			await writeCommunityCheck(resolved.source.id, check);
+		}
+	}
+
+	return { outcome: "accepted", path: live };
+}