claudeup 4.35.1 → 4.37.0

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

@@ -0,0 +1,218 @@
+/**
+ * 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;
+}
+
+interface StoreShape {
+	version: 1;
+	catalogs: Record<string, StoredCatalog>;
+	cooldowns: Record<string, StoredCooldown>;
+}
+
+const EMPTY: StoreShape = { version: 1, catalogs: {}, cooldowns: {} };
+
+/**
+ * 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: {} };
+	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 ??= {};
+		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: {} };
+		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;
+				onDisk =
+					parsed?.version === 1
+						? { version: 1, catalogs: parsed.catalogs ?? {}, cooldowns: parsed.cooldowns ?? {} }
+						: { version: 1, catalogs: {}, cooldowns: {} };
+			} catch {
+				onDisk = { version: 1, catalogs: {}, cooldowns: {} };
+			}
+			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];
+	});
+}
+
+/** Test seam: forget this process's memo so the next read hits disk. */
+export function resetCatalogCacheMemo(): void {
+	memo = null;
+}

package/src/services/github-budget.ts

@@ -0,0 +1,274 @@
+/**
+ * github-budget.ts — one place that knows when we are allowed to call GitHub.
+ *
+ * claudeup talks to two GitHub hosts from several services, and they enforce
+ * separate budgets:
+ *
+ *   api.github.com            60 req/hr unauthenticated, and it TELLS you:
+ *                             x-ratelimit-remaining / x-ratelimit-reset / retry-after
+ *   raw.githubusercontent.com rate-limited too, and it tells you NOTHING —
+ *                             measured 2026-08-17: a 429 carried no retry-after
+ *                             and no x-ratelimit-* header, only a request id.
+ *
+ * That asymmetry is the whole design problem. For one host we can state exactly
+ * when the window reopens; for the other any specific time would be invented. So
+ * a cooldown records WHERE its timing came from, and the UI says "resets in 4m"
+ * only when GitHub actually said so, and "next attempt in 30s" — our own
+ * schedule, honestly labelled — when it did not.
+ *
+ * Two jobs:
+ *  1. Stop sending requests that are already known to fail. Every service shares
+ *     one bucket per host, so the skills screen's raw fetches and the plugin
+ *     catalog fetches must share one gate — otherwise each rediscovers the limit
+ *     by burning more attempts against it.
+ *  2. Report when the next attempt is due, so the UI can show a countdown and
+ *     retry itself instead of asking the user to guess.
+ */
+
+import {
+	clearStoredCooldown,
+	readStoredCooldowns,
+	writeStoredCooldown,
+} from "./catalog-cache-store.js";
+
+/** Hosts we gate. Anything else is not budgeted. */
+export type GitHubHost = "api.github.com" | "raw.githubusercontent.com";
+
+export interface Cooldown {
+	host: GitHubHost;
+	/** Wall-clock ms when the next attempt is allowed. */
+	until: number;
+	/**
+	 * True when `until` came from GitHub's own `retry-after` /
+	 * `x-ratelimit-reset`. False when we derived it from backoff because the
+	 * response carried no timing — the distinction the UI must not blur.
+	 */
+	exact: boolean;
+	/** Consecutive rate-limited responses, driving the backoff. */
+	strikes: number;
+}
+
+const cooldowns = new Map<GitHubHost, Cooldown>();
+
+/**
+ * Load cooldowns recorded by a previous launch.
+ *
+ * Without this the gate is per-process, which for a TUI means per-launch, which
+ * means useless: two consecutive processes each spent six requests rediscovering
+ * the same rate limit. Memoised, so callers may await it unconditionally.
+ */
+let hydrated: Promise<void> | null = null;
+
+export function hydrateGitHubBudget(): Promise<void> {
+	hydrated ??= (async () => {
+		try {
+			const stored = await readStoredCooldowns();
+			for (const [host, cooldown] of Object.entries(stored)) {
+				if (host !== "api.github.com" && host !== "raw.githubusercontent.com") {
+					continue;
+				}
+				// A cooldown already known in this process wins: it is newer.
+				if (cooldowns.has(host)) continue;
+				cooldowns.set(host, { host, ...cooldown });
+			}
+		} catch {
+			// A cache that cannot be read must not stop us making requests.
+		}
+	})();
+	return hydrated;
+}
+
+/**
+ * Backoff for hosts that give no retry timing. Deliberately coarse: a rate limit
+ * measured in minutes is not escaped by retrying in one second, and each wasted
+ * attempt can extend the penalty.
+ */
+const BACKOFF_MS = [30_000, 60_000, 120_000, 300_000, 600_000];
+
+/** Cap on a server-provided window we will honour, so a bad header cannot wedge the UI. */
+const MAX_EXACT_WAIT_MS = 60 * 60_000;
+
+export function hostOf(url: string): GitHubHost | null {
+	try {
+		const { hostname } = new URL(url);
+		if (hostname === "api.github.com") return "api.github.com";
+		if (hostname === "raw.githubusercontent.com")
+			return "raw.githubusercontent.com";
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Parse GitHub's retry timing, if the response carries any.
+ *
+ * `retry-after` is delta-seconds or an HTTP date (RFC 9110). `x-ratelimit-reset`
+ * is epoch SECONDS, not ms — treating it as ms yields a date in 1970 and a
+ * cooldown that expires instantly, which reads as "not rate limited".
+ */
+function parseRetryTiming(headers: Headers, now: number): number | null {
+	const retryAfter = headers.get("retry-after");
+	if (retryAfter) {
+		const seconds = Number(retryAfter);
+		if (Number.isFinite(seconds) && seconds >= 0) {
+			return now + seconds * 1000;
+		}
+		const asDate = Date.parse(retryAfter);
+		if (Number.isFinite(asDate)) return asDate;
+	}
+
+	const reset = headers.get("x-ratelimit-reset");
+	if (reset) {
+		const epochSeconds = Number(reset);
+		if (Number.isFinite(epochSeconds) && epochSeconds > 0) {
+			return epochSeconds * 1000;
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Record a rate-limited response and return the resulting cooldown.
+ *
+ * Call this for 429 and for 403, which is how GitHub reports an exhausted
+ * unauthenticated budget on the REST API.
+ */
+export function recordRateLimit(
+	host: GitHubHost,
+	headers?: Headers,
+	now: number = Date.now(),
+): Cooldown {
+	const strikes = (cooldowns.get(host)?.strikes ?? 0) + 1;
+
+	const fromHeader = headers ? parseRetryTiming(headers, now) : null;
+	if (fromHeader !== null && fromHeader > now) {
+		const cooldown: Cooldown = {
+			host,
+			until: Math.min(fromHeader, now + MAX_EXACT_WAIT_MS),
+			exact: true,
+			strikes,
+		};
+		cooldowns.set(host, cooldown);
+		persist(cooldown);
+		return cooldown;
+	}
+
+	const step = BACKOFF_MS[Math.min(strikes - 1, BACKOFF_MS.length - 1)];
+	const cooldown: Cooldown = {
+		host,
+		// No jitter: this is a single-user desktop tool, not a fleet stampeding
+		// one endpoint. A predictable countdown is worth more here than spread.
+		until: now + (step ?? 30_000),
+		exact: false,
+		strikes,
+	};
+	cooldowns.set(host, cooldown);
+	persist(cooldown);
+	return cooldown;
+}
+
+/**
+ * Write-behind, so `recordRateLimit` stays synchronous for its many call sites.
+ *
+ * Fire-and-forget is acceptable here and only here: losing one cooldown write
+ * degrades to the old behaviour (one wasted request next launch), whereas making
+ * every caller async to guarantee it would spread `await` through the fetch path
+ * for no proportional gain.
+ */
+function persist(cooldown: Cooldown): void {
+	void writeStoredCooldown(cooldown.host, {
+		until: cooldown.until,
+		exact: cooldown.exact,
+		strikes: cooldown.strikes,
+	});
+}
+
+/**
+ * A successful response clears the host's cooldown and its accumulated strikes.
+ *
+ * Resetting strikes matters: without it, one bad afternoon leaves the backoff
+ * pinned at ten minutes for the rest of the session even though requests are
+ * succeeding again.
+ */
+export function recordSuccess(host: GitHubHost): void {
+	cooldowns.delete(host);
+	void clearStoredCooldown(host);
+}
+
+/**
+ * Also worth recording: the budget is nearly spent. Lets a caller stop before it
+ * trips the limit rather than after. Only api.github.com reports this.
+ */
+export function remainingFromHeaders(headers: Headers): number | null {
+	const remaining = headers.get("x-ratelimit-remaining");
+	if (!remaining) return null;
+	const n = Number(remaining);
+	return Number.isFinite(n) ? n : null;
+}
+
+/** The active cooldown for a host, or null when calls are allowed. */
+export function cooldownFor(
+	host: GitHubHost,
+	now: number = Date.now(),
+): Cooldown | null {
+	const cooldown = cooldowns.get(host);
+	if (!cooldown) return null;
+	if (cooldown.until <= now) {
+		// Expired. Keep the strike count — it is what makes repeated failures back
+		// off further — but stop blocking.
+		cooldowns.set(host, { ...cooldown, until: now });
+		return null;
+	}
+	return cooldown;
+}
+
+/** Milliseconds until the next attempt is allowed. 0 when allowed now. */
+export function waitMs(host: GitHubHost, now: number = Date.now()): number {
+	const cooldown = cooldownFor(host, now);
+	return cooldown ? cooldown.until - now : 0;
+}
+
+/** Every host currently in cooldown, soonest first. */
+export function activeCooldowns(now: number = Date.now()): Cooldown[] {
+	const active: Cooldown[] = [];
+	for (const host of cooldowns.keys()) {
+		const cooldown = cooldownFor(host, now);
+		if (cooldown) active.push(cooldown);
+	}
+	return active.sort((a, b) => a.until - b.until);
+}
+
+/** Human countdown: "45s", "4m", "1h 12m". */
+export function formatWait(ms: number): string {
+	const totalSeconds = Math.max(0, Math.ceil(ms / 1000));
+	if (totalSeconds < 60) return `${totalSeconds}s`;
+	const minutes = Math.ceil(totalSeconds / 60);
+	if (minutes < 60) return `${minutes}m`;
+	const hours = Math.floor(minutes / 60);
+	return `${hours}h ${minutes % 60}m`;
+}
+
+/**
+ * How to describe a cooldown to the user.
+ *
+ * The two phrasings are not interchangeable. "resets in 4m" is a claim about
+ * GitHub's state and is only sayable when GitHub sent the timing;
+ * "next attempt in 30s" is a claim about our own schedule and is always sayable.
+ */
+export function describeCooldown(
+	cooldown: Cooldown,
+	now: number = Date.now(),
+): string {
+	const wait = formatWait(cooldown.until - now);
+	return cooldown.exact
+		? `GitHub rate limit resets in ${wait}`
+		: `GitHub rate limit — next attempt in ${wait}`;
+}
+
+/** Test seam only. Clears in-memory state and the hydration memo, not the file. */
+export function resetGitHubBudget(): void {
+	cooldowns.clear();
+	hydrated = null;
+}

package/src/services/marketplace-catalog-git.ts

@@ -0,0 +1,170 @@
+/**
+ * marketplace-catalog-git.ts — read a marketplace's CURRENT catalog over git,
+ * without touching the checked-out clone.
+ *
+ * Why this exists
+ * ---------------
+ * `autoUpdate: false` is deliberate policy here: plugins are not updated
+ * automatically, the UI merely shows that an update is available. That freezes the
+ * clone at `~/.claude/plugins/marketplaces/<name>`, which is correct — the clone
+ * is the INSTALL SOURCE, and pinning it is the point.
+ *
+ * The mistake was using that same frozen clone as the CATALOG — the answer to
+ * "what version exists upstream". Those are two different jobs riding one
+ * artifact, and pinning the first silently blinded the second: the clone said
+ * terminal 4.1.4, the installed copy was 4.1.4, so the screen reported up to date
+ * while 4.2.0 had shipped.
+ *
+ * `git fetch` updates `refs/remotes/origin/*` and nothing else. The working tree
+ * does not move, HEAD does not move, so installs stay pinned exactly as the policy
+ * intends — and `git show origin/<branch>:.claude-plugin/marketplace.json` then
+ * reads the real upstream catalog. Verified 2026-08-17 against the magus clone:
+ * catalog read as 9.0.3 / terminal 4.2.0 while HEAD stayed at c45ddee.
+ *
+ * It also sidesteps the reason the HTTP path was failing. `raw.githubusercontent.com`
+ * was returning 429; git talks the smart-transport protocol over SSH or HTTPS and
+ * draws on neither that bucket nor the REST budget. So the version check keeps
+ * working precisely when the HTTP catalog cannot.
+ */
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { claudeConfigDirOrNull } from "../utils/config-dir.js";
+import {
+	normalizeCatalogJson,
+	type MarketplacePlugin,
+} from "./marketplace-catalog.js";
+
+/** Network reach; a wedged fetch must never hold up the screen. */
+const FETCH_TIMEOUT_MS = 15_000;
+/** Local object reads are fast or broken. */
+const LOCAL_TIMEOUT_MS = 5_000;
+
+/**
+ * Resolved per call, honouring CLAUDE_CONFIG_DIR — the same override Claude Code
+ * uses, and the same approach content-drift.ts takes for the same directory.
+ *
+ * Returns null when a test has not chosen a config dir, so an unisolated test
+ * cannot make this function perform a live `git fetch` against the operator's real
+ * marketplace clones. See utils/config-dir.ts.
+ */
+function cloneDir(name: string): string | null {
+	const configDir = claudeConfigDirOrNull();
+	if (!configDir) return null;
+	return path.join(configDir, "plugins", "marketplaces", name);
+}
+
+function git(
+	cwd: string,
+	args: string[],
+	timeoutMs: number,
+): Promise<{ ok: boolean; out: string }> {
+	return new Promise((resolve) => {
+		const child = spawn("git", args, {
+			cwd,
+			stdio: ["ignore", "pipe", "ignore"],
+			timeout: timeoutMs,
+			killSignal: "SIGKILL",
+			env: {
+				...process.env,
+				// Never let git stop for credentials: this runs inside a TUI with no
+				// way to answer a prompt, and a private marketplace we cannot read
+				// should degrade to "unknown", not hang the screen forever.
+				GIT_TERMINAL_PROMPT: "0",
+				GIT_ASKPASS: "echo",
+				SSH_ASKPASS: "echo",
+			},
+		});
+		let out = "";
+		child.stdout.on("data", (d: Buffer | string) => {
+			out += String(d);
+		});
+		child.on("error", () => resolve({ ok: false, out: "" }));
+		child.on("close", (code: number | null) =>
+			resolve({ ok: code === 0, out }),
+		);
+	});
+}
+
+/**
+ * Session cache. A catalog cannot change under us mid-session unless the user
+ * explicitly refreshes, and each miss costs a network round trip per marketplace.
+ */
+const catalogCache = new Map<string, MarketplacePlugin[] | null>();
+
+export function clearGitCatalogCache(): void {
+	catalogCache.clear();
+}
+
+/** The branch `origin/HEAD` points at, falling back to `main`. */
+async function defaultBranch(dir: string): Promise<string> {
+	const ref = await git(
+		dir,
+		["symbolic-ref", "--short", "refs/remotes/origin/HEAD"],
+		LOCAL_TIMEOUT_MS,
+	);
+	const name = ref.out.trim();
+	// "origin/main" → "main"
+	if (ref.ok && name.startsWith("origin/")) return name.slice("origin/".length);
+	return "main";
+}
+
+/**
+ * The marketplace's upstream catalog, or null when it cannot be read honestly.
+ *
+ * Null covers: no clone on disk, not a git repo, no reachable remote, fetch
+ * refused, or a catalog that does not parse. Every one of those must stay
+ * distinguishable from "an empty catalog" — collapsing them is the bug this
+ * module was written to help fix.
+ */
+export async function readCatalogFromRemote(
+	marketplaceName: string,
+): Promise<MarketplacePlugin[] | null> {
+	if (catalogCache.has(marketplaceName)) {
+		return catalogCache.get(marketplaceName) ?? null;
+	}
+
+	const dir = cloneDir(marketplaceName);
+	if (!dir || !fs.existsSync(path.join(dir, ".git"))) {
+		catalogCache.set(marketplaceName, null);
+		return null;
+	}
+
+	const branch = await defaultBranch(dir);
+
+	// Refs only. No merge, no checkout, no working-tree change — this is what
+	// makes the read compatible with `autoUpdate: false`.
+	const fetched = await git(
+		dir,
+		["fetch", "--quiet", "origin", branch],
+		FETCH_TIMEOUT_MS,
+	);
+	if (!fetched.ok) {
+		// A failed fetch may still leave a usable-but-older origin ref from a
+		// previous fetch. That is strictly better than the working tree, but it is
+		// not current, so it is not offered here — the caller's clone fallback
+		// already covers "possibly stale", and labels it as such.
+		catalogCache.set(marketplaceName, null);
+		return null;
+	}
+
+	const shown = await git(
+		dir,
+		["show", `origin/${branch}:.claude-plugin/marketplace.json`],
+		LOCAL_TIMEOUT_MS,
+	);
+	if (!shown.ok) {
+		catalogCache.set(marketplaceName, null);
+		return null;
+	}
+
+	try {
+		const plugins = normalizeCatalogJson(marketplaceName, JSON.parse(shown.out));
+		catalogCache.set(marketplaceName, plugins);
+		return plugins;
+	} catch {
+		catalogCache.set(marketplaceName, null);
+		return null;
+	}
+}