claudeup 4.36.0 → 4.38.0

package/src/services/catalog-cache-store.ts

@@ -0,0 +1,312 @@
+/**
+ * catalog-cache-store.ts — the catalog cache and the rate-limit cooldown, on disk.
+ *
+ * Why on disk
+ * -----------
+ * Every cache in this area used to be a module-level `Map`, which for a TUI means
+ * "cleared on every launch". Measured 2026-08-17, two consecutive processes:
+ *
+ *   [process-1] 6 HTTP requests in 13.32s
+ *   [process-2] 6 HTTP requests in 13.01s
+ *
+ * So each launch re-fetched all six catalogs, and the second process had no idea
+ * the first had just been rate-limited — it spent six more requests rediscovering
+ * that. On some endpoints a rejected request extends the penalty, so an in-memory
+ * cooldown is not merely useless across launches, it is counterproductive.
+ *
+ * Persisting the cooldown is the more important half. A stale catalog costs the
+ * user a version number that is an hour old; re-firing six doomed requests on
+ * every launch costs them the ability to check at all.
+ *
+ * Trade-off, stated
+ * -----------------
+ * A cached catalog means a release published inside the TTL is not visible yet.
+ * That is why the TTL is short, why `r` forces a real refetch, and why the age is
+ * available for display. A cache the user cannot see through or override would be
+ * the same trap as a frozen clone.
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { claudeConfigDirOrNull } from "../utils/config-dir.js";
+import { withFileLock } from "../utils/file-locking.js";
+import type { MarketplacePlugin } from "./marketplace-catalog.js";
+
+/**
+ * How long a cached catalog is served before we ask again.
+ *
+ * Matches the hour that `update-cache.ts` already uses for its own check, so the
+ * tool has one refresh rhythm rather than two.
+ */
+export const CATALOG_TTL_MS = 60 * 60 * 1000;
+
+interface StoredCatalog {
+	fetchedAt: number;
+	/** Which transport answered — carried so the UI can still say "unverified". */
+	source: string;
+	plugins: MarketplacePlugin[];
+}
+
+interface StoredCooldown {
+	until: number;
+	exact: boolean;
+	strikes: number;
+}
+
+/**
+ * What the last upstream check learned about one community-styles repository.
+ *
+ * Lives here rather than in a fourth cache file so it inherits this store's file
+ * lock, atomic write and CLAUDE_CONFIG_DIR test isolation — and, more to the
+ * point, so it sits beside the rate-limit cooldowns it is budgeted against.
+ *
+ * `dirHeadSha` is the pivot of the two-phase check: one API call per REPO
+ * answers "did anything in its styles directory move", and only a repo that
+ * moved is drilled into with free raw fetches. Per-style API calls would spend
+ * the machine's whole hourly budget on first use.
+ */
+export interface StoredCommunityCheck {
+	/** Wall-clock ms of the last successful phase A. Drives the 24h TTL. */
+	checkedAt: number;
+	/** Latest commit touching the repo's styles directory, as of that check. */
+	dirHeadSha: string;
+	/** Per coordinate id: the bytes we hold, and any update sitting in .pending/. */
+	styles: Record<
+		string,
+		{
+			sha256: string;
+			pendingSha256?: string;
+			/** Changed-line count of that pending update, so it survives a restart. */
+			pendingLines?: number;
+		}
+	>;
+}
+
+interface StoreShape {
+	version: 1;
+	catalogs: Record<string, StoredCatalog>;
+	cooldowns: Record<string, StoredCooldown>;
+	communityStyles: Record<string, StoredCommunityCheck>;
+}
+
+const EMPTY: StoreShape = {
+	version: 1,
+	catalogs: {},
+	cooldowns: {},
+	communityStyles: {},
+};
+
+/**
+ * Resolved per call, honouring CLAUDE_CONFIG_DIR — same reasoning as
+ * content-drift.ts and marketplace-catalog-git.ts.
+ *
+ * Null when a test has not chosen a config dir, which makes this whole store inert
+ * rather than letting an unisolated test read the operator's live cooldown and
+ * decide its own outcome from it. See utils/config-dir.ts.
+ */
+function storePath(): string | null {
+	const configDir = claudeConfigDirOrNull();
+	if (!configDir) return null;
+	return path.join(configDir, "claudeup-catalog-cache.json");
+}
+
+/**
+ * Read-through memo for this process. The disk file is the cross-launch cache;
+ * this just avoids re-reading and re-parsing it on every lookup within one run.
+ */
+let memo: { path: string; data: StoreShape } | null = null;
+
+async function load(): Promise<StoreShape> {
+	const file = storePath();
+	if (!file)
+		return { version: 1, catalogs: {}, cooldowns: {}, communityStyles: {} };
+	if (memo?.path === file) return memo.data;
+	try {
+		const parsed = JSON.parse(await fs.readFile(file, "utf-8")) as StoreShape;
+		// A cache from a future/unknown layout is discarded rather than migrated:
+		// it is regenerable by definition, so guessing at it buys nothing.
+		const data = parsed?.version === 1 ? parsed : { ...EMPTY };
+		data.catalogs ??= {};
+		data.cooldowns ??= {};
+		// Absent in every file written before community styles existed, so this
+		// default is the migration — an upgrade must not read as a corrupt cache.
+		data.communityStyles ??= {};
+		memo = { path: file, data };
+		return data;
+	} catch {
+		// Absent or corrupt. A cache must never be a failure mode — start empty.
+		const data: StoreShape = {
+			...EMPTY,
+			catalogs: {},
+			cooldowns: {},
+			communityStyles: {},
+		};
+		memo = { path: file, data };
+		return data;
+	}
+}
+
+/**
+ * Apply a mutation and persist it.
+ *
+ * Locked and re-read inside the lock, because two claudeup processes can be open
+ * at once and a blind read-modify-write would drop the other's cooldown — exactly
+ * the record we most need to keep.
+ */
+async function mutate(fn: (data: StoreShape) => void): Promise<void> {
+	const file = storePath();
+	if (!file) return;
+	try {
+		await fs.mkdir(path.dirname(file), { recursive: true });
+		await withFileLock(file, async () => {
+			let onDisk: StoreShape;
+			try {
+				const parsed = JSON.parse(
+					await fs.readFile(file, "utf-8"),
+				) as StoreShape;
+				// Every section is named explicitly: a key omitted here is silently
+				// dropped on the next write of any OTHER section.
+				onDisk =
+					parsed?.version === 1
+						? {
+								version: 1,
+								catalogs: parsed.catalogs ?? {},
+								cooldowns: parsed.cooldowns ?? {},
+								communityStyles: parsed.communityStyles ?? {},
+							}
+						: { version: 1, catalogs: {}, cooldowns: {}, communityStyles: {} };
+			} catch {
+				onDisk = {
+					version: 1,
+					catalogs: {},
+					cooldowns: {},
+					communityStyles: {},
+				};
+			}
+			fn(onDisk);
+			// Temp + rename, so a crash mid-write cannot leave a half-written file
+			// that the next launch has to treat as corrupt.
+			const tmp = `${file}.${process.pid}.tmp`;
+			await fs.writeFile(tmp, JSON.stringify(onDisk), "utf-8");
+			await fs.rename(tmp, file);
+			memo = { path: file, data: onDisk };
+		});
+	} catch {
+		// Never let a cache write break the run. Worst case we re-fetch next time.
+	}
+}
+
+// ─── Catalogs ────────────────────────────────────────────────────────────────
+
+export interface CachedCatalog {
+	plugins: MarketplacePlugin[];
+	source: string;
+	/** Milliseconds since it was fetched — for display, and for the TTL test. */
+	ageMs: number;
+}
+
+/** A cached catalog for this marketplace, if one is present and still fresh. */
+export async function readCachedCatalog(
+	marketplace: string,
+	now: number = Date.now(),
+): Promise<CachedCatalog | null> {
+	const data = await load();
+	const entry = data.catalogs[marketplace];
+	if (!entry) return null;
+	const ageMs = now - entry.fetchedAt;
+	if (ageMs < 0 || ageMs > CATALOG_TTL_MS) return null;
+	return { plugins: entry.plugins, source: entry.source, ageMs };
+}
+
+export async function writeCachedCatalog(
+	marketplace: string,
+	plugins: MarketplacePlugin[],
+	source: string,
+	now: number = Date.now(),
+): Promise<void> {
+	// An empty catalog is never worth caching: it is indistinguishable from a
+	// failure we did not classify, and serving it would resurrect the original bug.
+	if (plugins.length === 0) return;
+	await mutate((data) => {
+		data.catalogs[marketplace] = { fetchedAt: now, source, plugins };
+	});
+}
+
+/** Drop every cached catalog. Backs the explicit refresh (`r`). */
+export async function clearCachedCatalogs(): Promise<void> {
+	await mutate((data) => {
+		data.catalogs = {};
+	});
+}
+
+// ─── Cooldowns ───────────────────────────────────────────────────────────────
+
+export async function readStoredCooldowns(
+	now: number = Date.now(),
+): Promise<Record<string, StoredCooldown>> {
+	const data = await load();
+	const live: Record<string, StoredCooldown> = {};
+	for (const [host, cooldown] of Object.entries(data.cooldowns)) {
+		// Expired entries are dropped on read rather than persisted forever. The
+		// strike count goes with them: a cooldown that lapsed a day ago should not
+		// make today's first failure back off for ten minutes.
+		if (cooldown.until > now) live[host] = cooldown;
+	}
+	return live;
+}
+
+export async function writeStoredCooldown(
+	host: string,
+	cooldown: StoredCooldown,
+): Promise<void> {
+	await mutate((data) => {
+		data.cooldowns[host] = cooldown;
+	});
+}
+
+export async function clearStoredCooldown(host: string): Promise<void> {
+	await mutate((data) => {
+		delete data.cooldowns[host];
+	});
+}
+
+// ─── Community style checks ──────────────────────────────────────────────────
+
+/**
+ * Every recorded upstream check, keyed by community source id.
+ *
+ * Deliberately NOT expired on read, unlike cooldowns. An expired cooldown means
+ * "you may call again"; an expired CHECK still carries the shas we compare
+ * against, and only its `checkedAt` has gone stale. Dropping it would throw away
+ * the one thing that makes the next check cheap, and would make a 25-hour-old
+ * result indistinguishable from never having looked. Freshness is judged by the
+ * reader, which is what lets an expired check present as `unknown` rather than
+ * as up to date.
+ */
+export async function readCommunityChecks(): Promise<
+	Record<string, StoredCommunityCheck>
+> {
+	return { ...(await load()).communityStyles };
+}
+
+export async function writeCommunityCheck(
+	sourceId: string,
+	check: StoredCommunityCheck,
+): Promise<void> {
+	await mutate((data) => {
+		data.communityStyles ??= {};
+		data.communityStyles[sourceId] = check;
+	});
+}
+
+/** Drop every recorded check. Backs an explicit refresh. */
+export async function clearCommunityChecks(): Promise<void> {
+	await mutate((data) => {
+		data.communityStyles = {};
+	});
+}
+
+/** Test seam: forget this process's memo so the next read hits disk. */
+export function resetCatalogCacheMemo(): void {
+	memo = null;
+}

package/src/services/community-fetcher.ts

@@ -0,0 +1,90 @@
+/**
+ * community-fetcher.ts — the one thing in the community-styles feature that
+ * knows `fetch` exists.
+ *
+ * ## Why a port at all
+ *
+ * Exactly one boundary gets an interface: the network. The domain here is thin,
+ * and an interface-per-class reflex would be waste — so there is no Strategy
+ * registry, no adapter factory, and nothing else in the feature is abstracted.
+ * The gain is the one the constraints demand: no test can reach GitHub, because
+ * every exported function in `community-styles.ts` takes a `StyleFetcher` as a
+ * REQUIRED argument. Omitting it is a type error, not a forgotten mock.
+ *
+ * ## Why it does not speak `Response`
+ *
+ * The classic way a port leaks its adapter. A `Response` drags in streaming
+ * semantics, a body that can only be read once, and a `fetch`-shaped mental
+ * model into every test fake. `{ status, body, etag }` is what the caller
+ * actually uses.
+ *
+ * `headers` is the one deliberate exception. `github-budget.ts` parses
+ * `retry-after` / `x-ratelimit-reset` / `x-ratelimit-remaining` itself, and it
+ * is the module that knows the two hosts differ in what they report. Re-deriving
+ * that here would fork the rate-limit logic, which is precisely what §5.3 of the
+ * design forbids. A fake supplies `new Headers({...})`, which is a standard
+ * built-in, not a fetch import.
+ */
+
+/** What the application needs from an HTTP response. Never a `Response`. */
+export interface StyleFetchResponse {
+	status: number;
+	/** Empty for a 304 and for any status with no body. */
+	body: string;
+	etag: string | null;
+	contentType: string | null;
+	/** Handed to `github-budget` unchanged — see the header note. */
+	headers: Headers;
+}
+
+export type StyleFetcher = (
+	url: string,
+	opts?: { etag?: string | null; timeoutMs?: number; accept?: string },
+) => Promise<StyleFetchResponse>;
+
+/**
+ * 10s, matching `marketplace-fetcher.ts`. A style is a few kilobytes over a CDN
+ * — measured at ~340ms — so anything past ten seconds is a broken route rather
+ * than a slow one, and the user is waiting on a keypress they just made.
+ */
+export const FETCH_TIMEOUT_MS = 10_000;
+
+/**
+ * The real adapter. Wraps global `fetch` and nothing more: no retry, no
+ * classification, no budget check. Those are policy and belong in the service,
+ * where they can be tested without a network.
+ *
+ * Sends `GITHUB_TOKEN` / `GITHUB_PERSONAL_ACCESS_TOKEN` to `api.github.com`
+ * ONLY — exactly as `skills-manager.ts` already does. The token raises that
+ * host's 60/hr unauthenticated budget to 5000/hr and is the documented escape
+ * hatch when the advisory says the budget is spent. It is never sent to
+ * `raw.githubusercontent.com`, which needs no auth and would receive a
+ * credential it has no business seeing.
+ */
+export const githubFetcher: StyleFetcher = async (url, opts = {}) => {
+	const headers: Record<string, string> = {
+		accept: opts.accept ?? "text/plain, */*",
+		"user-agent": "claudeup",
+	};
+	if (opts.etag) headers["if-none-match"] = opts.etag;
+
+	if (new URL(url).hostname === "api.github.com") {
+		const token =
+			process.env.GITHUB_TOKEN || process.env.GITHUB_PERSONAL_ACCESS_TOKEN;
+		if (token) headers.authorization = `Bearer ${token}`;
+	}
+
+	const response = await fetch(url, {
+		headers,
+		signal: AbortSignal.timeout(opts.timeoutMs ?? FETCH_TIMEOUT_MS),
+	});
+
+	return {
+		status: response.status,
+		// 304 carries no body; reading it is still safe and yields "".
+		body: response.status === 304 ? "" : await response.text(),
+		etag: response.headers.get("etag"),
+		contentType: response.headers.get("content-type"),
+		headers: response.headers,
+	};
+};