claudeup 4.36.0 → 4.37.0

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;
+	}
+}

package/src/services/marketplace-catalog.ts

@@ -0,0 +1,95 @@
+/**
+ * marketplace-catalog.ts — the catalog shape and its parser, transport-agnostic.
+ *
+ * A marketplace catalog can arrive two ways: over HTTP from
+ * raw.githubusercontent.com (`marketplace-fetcher.ts`) or out of a git remote ref
+ * (`marketplace-catalog-git.ts`). Both must produce byte-identical results — a
+ * catalog that parsed differently depending on how it was fetched would make
+ * version comparisons depend on the transport, which is the same class of bug as
+ * the one that made a failed fetch read as "up to date".
+ *
+ * This module exists so the two transports share one parser without importing
+ * each other. The fetcher needs the git reader as a fallback and the git reader
+ * needs the parser, so putting the parser in either one would make them mutually
+ * dependent.
+ */
+
+import type { PluginRelease } from "../types/index.js";
+import { normalizeReleases } from "./plugin-releases.js";
+
+export interface MarketplacePlugin {
+	name: string;
+	version: string | null;
+	description: string;
+	category?: string;
+	author?: { name: string; email?: string };
+	homepage?: string;
+	tags?: string[];
+	releases?: PluginRelease[];
+}
+
+// Session-level cache for each marketplace's declared version (from
+// marketplace.json's top-level `metadata.version`), so the TUI can surface a
+// marketplace's version without re-fetching. Only populated for marketplaces that
+// actually declare one.
+const marketplaceVersionCache = new Map<string, string>();
+
+export function clearMarketplaceVersionCache(): void {
+	marketplaceVersionCache.clear();
+}
+
+/**
+ * Returns the version a marketplace declared in its `metadata.version`, if one
+ * was seen during a successful read this session. Returns `undefined` for
+ * marketplaces that declare no version (or haven't been read yet).
+ */
+export function getMarketplaceVersion(
+	marketplaceName: string,
+): string | undefined {
+	return marketplaceVersionCache.get(marketplaceName);
+}
+
+interface RawPlugin {
+	name: string;
+	version?: string | null;
+	description?: string;
+	category?: string;
+	author?: { name: string; email?: string };
+	homepage?: string;
+	tags?: string[];
+	releases?: unknown;
+}
+
+/** Parse a `marketplace.json` payload into plugin entries. */
+export function normalizeCatalogJson(
+	marketplaceName: string,
+	raw: unknown,
+): MarketplacePlugin[] {
+	const data = (raw ?? {}) as {
+		plugins?: RawPlugin[];
+		metadata?: { version?: string };
+	};
+	const plugins: MarketplacePlugin[] = [];
+
+	const version = data.metadata?.version;
+	if (typeof version === "string" && version.length > 0) {
+		marketplaceVersionCache.set(marketplaceName, version);
+	}
+
+	if (data.plugins && Array.isArray(data.plugins)) {
+		for (const plugin of data.plugins) {
+			plugins.push({
+				name: plugin.name,
+				version: plugin.version || null,
+				description: plugin.description || "",
+				category: plugin.category,
+				author: plugin.author,
+				homepage: plugin.homepage,
+				tags: plugin.tags,
+				releases: normalizeReleases(plugin.releases),
+			});
+		}
+	}
+
+	return plugins;
+}