claudeup 4.36.0 → 4.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeup",
-  "version": "4.36.0",
+  "version": "4.38.0",
   "description": "TUI tool for managing Claude Code plugins, MCPs, and configuration",
   "type": "module",
   "main": "src/main.tsx",
@@ -64,8 +64,8 @@
     "typescript": "^5.6.3"
   },
   "optionalDependencies": {
-    "claudeup-darwin-arm64": "4.36.0",
-    "claudeup-darwin-x64": "4.36.0",
-    "claudeup-linux-x64": "4.36.0"
+    "claudeup-darwin-arm64": "4.38.0",
+    "claudeup-darwin-x64": "4.38.0",
+    "claudeup-linux-x64": "4.38.0"
   }
 }

package/scripts/verify-community-registry.ts

@@ -0,0 +1,272 @@
+#!/usr/bin/env bun
+/**
+ * verify-community-registry.ts — the gate between a proposed community style
+ * entry and a committed one.
+ *
+ * This is NOT a test. It hits the real network, it is run by a human who is
+ * curating the registry, and it must never run in CI: it would burn the shared
+ * 60/hr `api.github.com` budget on every push and then fail on GitHub's rate
+ * limit rather than on our bug, which is the worst possible signal.
+ *
+ * Two modes:
+ *
+ *   --discover                  list the real `.md` blobs and their upstream
+ *   --discover <repo> <dir>     `name`, for every registry source or for one
+ *                               candidate repo. Prints a paste-ready registry
+ *                               block. NEVER hand-write a path from a README:
+ *                               a wrong path is a 404 the user sees, and the
+ *                               error text blames claudeup for it, correctly.
+ *
+ *   --check                     re-fetch every committed entry and report 404s,
+ *                               size outliers and unparseable files. Run this
+ *                               before committing a registry change.
+ *
+ * Cost: `--discover` spends ONE api.github.com call per repo (a recursive git
+ * tree), then reads names over raw.githubusercontent.com, which costs nothing.
+ * `--check` spends zero API budget.
+ */
+
+import { parseArgs } from "node:util";
+import {
+	COMMUNITY_SOURCES,
+	COMMUNITY_STYLES,
+	type CommunityStyleSource,
+	coordinateProblem,
+	rawUrlFor,
+} from "../src/data/community-styles.js";
+import { githubFetcher } from "../src/services/community-fetcher.js";
+import { MAX_STYLE_BYTES } from "../src/services/community-styles.js";
+import { splitFrontmatter } from "../src/services/styles-manager.js";
+
+interface DiscoveredFile {
+	path: string;
+	/** Upstream's own `name`, or the basename when the file declares none. */
+	displayName: string;
+	description: string;
+	bytes: number;
+}
+
+/** `attention-span/output-styles/zen-master.md` -> `zen-master`. */
+function slugFromPath(filePath: string): string {
+	return (filePath.split("/").pop() ?? filePath).replace(/\.md$/, "");
+}
+
+async function discover(
+	repo: string,
+	dir: string,
+	ref: string,
+): Promise<DiscoveredFile[]> {
+	// ONE API call for the whole repo. Asking per-directory would cost one call
+	// per level and tell us less.
+	const treeUrl = `https://api.github.com/repos/${repo}/git/trees/${ref}?recursive=1`;
+	const tree = await githubFetcher(treeUrl, {
+		accept: "application/vnd.github+json",
+	});
+	if (tree.status !== 200) {
+		throw new Error(
+			`${repo}: HTTP ${tree.status} listing the git tree${
+				tree.status === 403 || tree.status === 429
+					? " (rate limited — wait, or export GITHUB_TOKEN)"
+					: ""
+			}`,
+		);
+	}
+	const parsed = JSON.parse(tree.body) as {
+		truncated?: boolean;
+		tree?: Array<{ path?: string; type?: string }>;
+	};
+	if (parsed.truncated) {
+		console.warn(
+			`  ! ${repo}: git tree was truncated by GitHub — list is partial`,
+		);
+	}
+
+	const prefix = `${dir}/`;
+	const paths = (parsed.tree ?? [])
+		.filter(
+			(entry) =>
+				entry.type === "blob" &&
+				typeof entry.path === "string" &&
+				entry.path.startsWith(prefix) &&
+				entry.path.endsWith(".md") &&
+				// One directory deep only: the cache is flat and a nested style would
+				// need a slug that is not a plain basename.
+				!entry.path.slice(prefix.length).includes("/"),
+		)
+		.map((entry) => entry.path as string)
+		.sort();
+
+	const files: DiscoveredFile[] = [];
+	for (const filePath of paths) {
+		// raw.githubusercontent.com costs no API budget, so reading every file to
+		// get its real `name` is free. This is the only way to get a displayName
+		// that is upstream's own rather than one we invented from a filename.
+		const raw = await githubFetcher(
+			`https://raw.githubusercontent.com/${repo}/${ref}/${filePath}`,
+		);
+		if (raw.status !== 200) {
+			console.warn(`  ! ${filePath}: HTTP ${raw.status}`);
+			continue;
+		}
+		const { frontmatter } = splitFrontmatter(raw.body);
+		files.push({
+			path: filePath,
+			displayName: frontmatter.name || slugFromPath(filePath),
+			description: frontmatter.description || "",
+			bytes: Buffer.byteLength(raw.body, "utf8"),
+		});
+	}
+	return files;
+}
+
+function printDiscovered(
+	sourceId: string,
+	repo: string,
+	files: DiscoveredFile[],
+): void {
+	console.log(`\n${repo} — ${files.length} style file(s)`);
+	console.log("─".repeat(72));
+	for (const file of files) {
+		const flag = file.bytes > MAX_STYLE_BYTES ? "  ** OVER 64 KiB **" : "";
+		console.log(
+			`  {\n\t\tid: "${sourceId}--${slugFromPath(file.path)}",\n\t\tsourceId: "${sourceId}",\n\t\tpath: "${file.path}",\n\t\tdisplayName: ${JSON.stringify(file.displayName)},\n\t\tsummary: ${JSON.stringify(file.description.slice(0, 100))},\n\t},${flag}`,
+		);
+	}
+}
+
+async function runDiscover(repo?: string, dir?: string): Promise<number> {
+	const targets: Array<{ id: string; repo: string; dir: string; ref: string }> =
+		repo && dir
+			? [{ id: repo.split("/")[1] ?? repo, repo, dir, ref: "HEAD" }]
+			: COMMUNITY_SOURCES.map((source: CommunityStyleSource) => ({
+					id: source.id,
+					repo: source.repo,
+					dir: source.dir,
+					ref: source.ref,
+				}));
+
+	let failures = 0;
+	for (const target of targets) {
+		try {
+			const files = await discover(target.repo, target.dir, target.ref);
+			printDiscovered(target.id, target.repo, files);
+			if (files.length === 0) {
+				// The rule that keeps `caveman` and `humanizer` out: zero style files
+				// means there is nothing to import, whatever the star count says.
+				console.log(
+					"  (no style files — this repo must NOT get a registry entry)",
+				);
+			}
+		} catch (error) {
+			failures++;
+			console.error(
+				`  ! ${target.repo}: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+	return failures;
+}
+
+async function runCheck(): Promise<number> {
+	let problems = 0;
+	console.log(
+		`Checking ${COMMUNITY_STYLES.length} entries across ${COMMUNITY_SOURCES.length} sources — zero API budget.\n`,
+	);
+
+	for (const style of COMMUNITY_STYLES) {
+		const source = COMMUNITY_SOURCES.find((s) => s.id === style.sourceId);
+		if (!source) {
+			console.error(
+				`✗ ${style.id}: sourceId "${style.sourceId}" resolves to nothing`,
+			);
+			problems++;
+			continue;
+		}
+		const coordinate = coordinateProblem(style, source);
+		if (coordinate) {
+			console.error(`✗ ${style.id}: ${coordinate}`);
+			problems++;
+			continue;
+		}
+
+		const response = await githubFetcher(rawUrlFor(style, source));
+		if (response.status !== 200) {
+			console.error(
+				`✗ ${style.id}: HTTP ${response.status} — ${rawUrlFor(style, source)}`,
+			);
+			problems++;
+			continue;
+		}
+		const bytes = Buffer.byteLength(response.body, "utf8");
+		if (bytes > MAX_STYLE_BYTES) {
+			console.error(`✗ ${style.id}: ${bytes} bytes exceeds the 64 KiB cap`);
+			problems++;
+			continue;
+		}
+		const { frontmatter, body } = splitFrontmatter(response.body);
+		if (Object.keys(frontmatter).length === 0 || body.trim().length === 0) {
+			console.error(
+				`✗ ${style.id}: not a valid output style (no frontmatter or no body)`,
+			);
+			problems++;
+			continue;
+		}
+		// Advisory, not a failure: upstream is free to rename a style, and the
+		// coordinate id is deliberately independent of it. But a drifted
+		// displayName is what the user reads, so it is worth seeing.
+		const upstreamName = frontmatter.name;
+		const drift =
+			upstreamName && upstreamName !== style.displayName
+				? `  (upstream name is now "${upstreamName}", registry says "${style.displayName}")`
+				: "";
+		console.log(
+			`✓ ${style.id.padEnd(38)} ${String(bytes).padStart(6)} B${drift}`,
+		);
+	}
+
+	console.log(
+		problems === 0
+			? "\nRegistry is clean — safe to commit."
+			: `\n${problems} problem(s). Do NOT commit until they are fixed.`,
+	);
+	return problems;
+}
+
+async function main(): Promise<number> {
+	const { values, positionals } = parseArgs({
+		args: process.argv.slice(2),
+		options: {
+			discover: { type: "boolean", default: false },
+			check: { type: "boolean", default: false },
+		},
+		allowPositionals: true,
+	});
+
+	if (!values.discover && !values.check) {
+		console.error(
+			"usage: bun scripts/verify-community-registry.ts --discover [<repo> <dir>]\n" +
+				"       bun scripts/verify-community-registry.ts --check",
+		);
+		return 1;
+	}
+
+	let problems = 0;
+	if (values.discover) {
+		problems += await runDiscover(positionals[0], positionals[1]);
+	}
+	if (values.check) {
+		problems += await runCheck();
+	}
+	return problems === 0 ? 0 : 1;
+}
+
+if (import.meta.main) {
+	main()
+		.then((code) => process.exit(code))
+		.catch((error) => {
+			console.error(
+				`error: ${error instanceof Error ? error.message : String(error)}`,
+			);
+			process.exit(1);
+		});
+}

package/src/__tests__/catalog-cache-store.test.ts

@@ -0,0 +1,271 @@
+import {
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+} from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  CATALOG_TTL_MS,
+  clearCachedCatalogs,
+  clearStoredCooldown,
+  readCachedCatalog,
+  readStoredCooldowns,
+  resetCatalogCacheMemo,
+  writeCachedCatalog,
+  writeStoredCooldown,
+} from "../services/catalog-cache-store";
+import {
+  cooldownFor,
+  hydrateGitHubBudget,
+  recordRateLimit,
+  resetGitHubBudget,
+} from "../services/github-budget";
+import type { MarketplacePlugin } from "../services/marketplace-catalog";
+
+/**
+ * These cover the cross-LAUNCH behaviour, which is the only kind that matters for
+ * a TUI. Measured before this store existed, two consecutive processes:
+ *
+ *   [process-1] 6 HTTP requests in 13.32s
+ *   [process-2] 6 HTTP requests in 13.01s
+ *
+ * Every cache was a module-level Map, so a relaunch re-fetched all six catalogs —
+ * and, worse, forgot that the previous launch had just been rate-limited and spent
+ * six more requests rediscovering it.
+ *
+ * A fresh module registry is the closest a unit test gets to a fresh process, so
+ * `resetGitHubBudget()` + `resetCatalogCacheMemo()` stand in for a relaunch: they
+ * drop all in-memory state while leaving the file on disk.
+ */
+
+let configDir: string;
+let prevConfigDir: string | undefined;
+
+const NOW = 1_786_980_000_000;
+
+function plugin(name: string, version: string): MarketplacePlugin {
+  return { name, version, description: "" };
+}
+
+beforeEach(() => {
+  configDir = fs.mkdtempSync(path.join(os.tmpdir(), "catalog-cache-"));
+  prevConfigDir = process.env.CLAUDE_CONFIG_DIR;
+  process.env.CLAUDE_CONFIG_DIR = configDir;
+  resetCatalogCacheMemo();
+  resetGitHubBudget();
+});
+
+afterEach(() => {
+  if (prevConfigDir === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+  else process.env.CLAUDE_CONFIG_DIR = prevConfigDir;
+  fs.rmSync(configDir, { recursive: true, force: true });
+});
+
+describe("catalog cache — survives a relaunch", () => {
+  it("serves a catalog written by a previous process", async () => {
+    await writeCachedCatalog("magus", [plugin("terminal", "4.1.6")], "remote");
+
+    // Stand in for a relaunch: in-memory state gone, file intact.
+    resetCatalogCacheMemo();
+
+    const cached = await readCachedCatalog("magus");
+    expect(cached).not.toBeNull();
+    expect(cached?.plugins).toHaveLength(1);
+    expect(cached?.plugins[0]?.version).toBe("4.1.6");
+    expect(cached?.source).toBe("remote");
+  });
+
+  it("keeps the source, so a cached answer is still labelled honestly", async () => {
+    // A `remote-git` answer stays `remote-git` after a round trip through disk.
+    // Flattening it to "cached" would lose the authoritative/unverified
+    // distinction the whole fix rests on.
+    await writeCachedCatalog("magus", [plugin("dev", "4.0.1")], "remote-git");
+    resetCatalogCacheMemo();
+    expect((await readCachedCatalog("magus"))?.source).toBe("remote-git");
+  });
+
+  it("expires once past the TTL", async () => {
+    await writeCachedCatalog(
+      "magus",
+      [plugin("terminal", "4.1.6")],
+      "remote",
+      NOW,
+    );
+    resetCatalogCacheMemo();
+
+    expect(await readCachedCatalog("magus", NOW + CATALOG_TTL_MS - 1000)).not.toBeNull();
+    expect(await readCachedCatalog("magus", NOW + CATALOG_TTL_MS + 1000)).toBeNull();
+  });
+
+  it("ignores an entry stamped in the future", async () => {
+    // A clock that jumped backwards must not pin a cache entry forever.
+    await writeCachedCatalog("magus", [plugin("dev", "4.0.1")], "remote", NOW);
+    resetCatalogCacheMemo();
+    expect(await readCachedCatalog("magus", NOW - 60_000)).toBeNull();
+  });
+
+  it("never caches an empty catalog", async () => {
+    // An empty list is indistinguishable from an unclassified failure. Caching it
+    // would serve "this marketplace has no plugins" for an hour — the original bug
+    // with a longer memory.
+    await writeCachedCatalog("magus", [], "remote");
+    resetCatalogCacheMemo();
+    expect(await readCachedCatalog("magus")).toBeNull();
+  });
+
+  it("is dropped by an explicit refresh", async () => {
+    await writeCachedCatalog("magus", [plugin("terminal", "4.1.6")], "remote");
+    await clearCachedCatalogs();
+    resetCatalogCacheMemo();
+    expect(await readCachedCatalog("magus")).toBeNull();
+  });
+
+  it("survives a corrupt cache file instead of throwing", async () => {
+    fs.writeFileSync(
+      path.join(configDir, "claudeup-catalog-cache.json"),
+      "{ not json",
+    );
+    resetCatalogCacheMemo();
+    expect(await readCachedCatalog("magus")).toBeNull();
+
+    // And it must recover: a bad file cannot poison later writes.
+    await writeCachedCatalog("magus", [plugin("dev", "4.0.1")], "remote");
+    resetCatalogCacheMemo();
+    expect(await readCachedCatalog("magus")).not.toBeNull();
+  });
+});
+
+describe("rate-limit cooldown — survives a relaunch", () => {
+  /**
+   * Anchored to the real clock, not the fixed NOW the catalog tests use.
+   * `hydrateGitHubBudget()` takes no clock parameter — it filters expired entries
+   * against `Date.now()`, exactly as it does in production — so a cooldown stamped
+   * relative to a fixed past NOW would be discarded as expired before the
+   * assertion ever ran.
+   */
+  let base: number;
+  beforeEach(() => {
+    base = Date.now();
+  });
+
+  /** Let a write-behind cooldown reach disk. */
+  const flush = () => new Promise((r) => setTimeout(r, 80));
+
+  // Only this block triggers write-behind, so only this block pays for draining
+  // it. Held here rather than in the outer afterEach so the catalog tests — which
+  // await every write — are not each charged the delay too.
+  afterEach(flush);
+
+  it("is still in force in the next process", async () => {
+    // THE defect this store exists to fix. Without persistence, launch two fired
+    // six more doomed requests at a host it had already been refused by.
+    recordRateLimit("raw.githubusercontent.com", new Headers(), base);
+    await flush();
+
+    resetGitHubBudget();
+    resetCatalogCacheMemo();
+    expect(cooldownFor("raw.githubusercontent.com", base)).toBeNull(); // memory only
+
+    await hydrateGitHubBudget();
+    const restored = cooldownFor("raw.githubusercontent.com", base);
+    expect(restored).not.toBeNull();
+    expect(restored?.until).toBeGreaterThan(base);
+  });
+
+  it("keeps escalating the backoff across relaunches", async () => {
+    // Without the strike count surviving, every relaunch restarts the backoff at
+    // 30s — so a tool that is relaunched often never actually backs off, which is
+    // the behaviour that got the IP rate-limited in the first place.
+    //
+    // Written as one strike per launch, which is the real shape: a launch makes its
+    // requests, learns it is limited once, and exits.
+    const first = recordRateLimit("raw.githubusercontent.com", undefined, base);
+    expect(first.strikes).toBe(1);
+    await flush();
+
+    resetGitHubBudget();
+    resetCatalogCacheMemo();
+    await hydrateGitHubBudget();
+
+    const second = recordRateLimit("raw.githubusercontent.com", undefined, base);
+    expect(second.strikes).toBe(2);
+    expect(second.until).toBeGreaterThan(first.until);
+    await flush();
+
+    resetGitHubBudget();
+    resetCatalogCacheMemo();
+    await hydrateGitHubBudget();
+
+    const third = recordRateLimit("raw.githubusercontent.com", undefined, base);
+    expect(third.strikes).toBe(3);
+    expect(third.until).toBeGreaterThan(second.until);
+  });
+
+  it("preserves whether the timing was GitHub's or ours", async () => {
+    // `exact` decides between "resets in 4m" and "next attempt in 4m". Losing it
+    // across a relaunch would make the UI state a claim GitHub never made.
+    recordRateLimit(
+      "api.github.com",
+      new Headers({ "retry-after": "600" }),
+      base,
+    );
+    await flush();
+
+    resetGitHubBudget();
+    await hydrateGitHubBudget();
+    expect(cooldownFor("api.github.com", base)?.exact).toBe(true);
+  });
+
+  it("drops an expired cooldown rather than restoring it", async () => {
+    await writeStoredCooldown("raw.githubusercontent.com", {
+      until: NOW - 1000,
+      exact: false,
+      strikes: 4,
+    });
+    resetCatalogCacheMemo();
+
+    // Expired entries are not returned, so a stale strike count from yesterday
+    // cannot make today's first failure back off for ten minutes.
+    expect(Object.keys(await readStoredCooldowns(NOW))).toEqual([]);
+  });
+
+  it("is cleared for a host that recovers", async () => {
+    await writeStoredCooldown("raw.githubusercontent.com", {
+      until: NOW + 60_000,
+      exact: false,
+      strikes: 1,
+    });
+    await clearStoredCooldown("raw.githubusercontent.com");
+    resetCatalogCacheMemo();
+    expect(Object.keys(await readStoredCooldowns(NOW))).toEqual([]);
+  });
+
+  it("keeps catalogs when only the cooldown is cleared, and vice versa", async () => {
+    // They share one file; a write to either must not clobber the other.
+    await writeCachedCatalog("magus", [plugin("dev", "4.0.1")], "remote");
+    await writeStoredCooldown("raw.githubusercontent.com", {
+      until: NOW + 60_000,
+      exact: false,
+      strikes: 1,
+    });
+
+    await clearStoredCooldown("raw.githubusercontent.com");
+    resetCatalogCacheMemo();
+    expect(await readCachedCatalog("magus")).not.toBeNull();
+
+    await writeStoredCooldown("raw.githubusercontent.com", {
+      until: NOW + 60_000,
+      exact: false,
+      strikes: 1,
+    });
+    await clearCachedCatalogs();
+    resetCatalogCacheMemo();
+    expect(Object.keys(await readStoredCooldowns(NOW))).toEqual([
+      "raw.githubusercontent.com",
+    ]);
+  });
+});