claudeup 4.35.1 → 4.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeup",
-  "version": "4.35.1",
+  "version": "4.37.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.35.1",
-    "claudeup-darwin-x64": "4.35.1",
-    "claudeup-linux-x64": "4.35.1"
+    "claudeup-darwin-arm64": "4.37.0",
+    "claudeup-darwin-x64": "4.37.0",
+    "claudeup-linux-x64": "4.37.0"
   }
 }

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",
+    ]);
+  });
+});

package/src/__tests__/catalog-notice.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect } from "bun:test";
+import { buildCatalogNoticeText } from "../ui/adapters/catalogNotice";
+import type { MarketplaceFetchFailure } from "../services/marketplace-fetcher";
+
+/**
+ * The banner is the only thing standing between the user and a screen that
+ * silently claims every plugin is up to date. So it has three obligations:
+ * appear whenever a check did not actually happen, stay silent when it did or
+ * when the state is intended, and stay legible either way.
+ *
+ * "Stay silent when intended" is not politeness. `autoUpdate: false` and a clone
+ * behind its remote are deliberate policy here — plugins are not auto-updated.
+ * An earlier version warned about both and suggested the command that would undo
+ * the policy, which trains the user to ignore the line.
+ */
+
+const NOW = 1_786_980_000_000;
+
+function failure(
+  marketplace: string,
+  kind: MarketplaceFetchFailure["kind"] = "rate-limited",
+  retryAt?: number,
+): MarketplaceFetchFailure {
+  return { marketplace, kind, detail: `${kind} detail`, retryAt };
+}
+
+describe("buildCatalogNoticeText", () => {
+  it("says nothing when every catalog was actually checked", () => {
+    // The negative control. A banner that is always on carries no information.
+    expect(
+      buildCatalogNoticeText({
+        failures: [],
+        unverifiedPlugins: 0,
+        width: 120,
+        now: NOW,
+      }),
+    ).toBeNull();
+  });
+
+  it("names the reason, because it determines what the user should do", () => {
+    const rate = buildCatalogNoticeText({
+      failures: [failure("magus")],
+      unverifiedPlugins: 3,
+      width: 120,
+      now: NOW,
+    });
+    expect(rate).toContain("GitHub rate limit");
+
+    const slow = buildCatalogNoticeText({
+      failures: [failure("magus", "timeout")],
+      unverifiedPlugins: 3,
+      width: 120,
+      now: NOW,
+    });
+    expect(slow).toContain("GitHub timed out");
+  });
+
+  it("names one or two failing marketplaces but only counts many", () => {
+    const few = buildCatalogNoticeText({
+      failures: [failure("magus"), failure("magus-alpha")],
+      unverifiedPlugins: 0,
+      width: 160,
+      now: NOW,
+    });
+    expect(few).toContain("magus-alpha");
+
+    const many = buildCatalogNoticeText({
+      failures: ["a", "b", "c", "d", "e", "f"].map((n) => failure(n)),
+      unverifiedPlugins: 0,
+      width: 160,
+      now: NOW,
+    });
+    expect(many).toContain("6 catalogs unchecked");
+  });
+
+  it("counts down to the retry instead of saying 'later'", () => {
+    // Answering "when can I try again" is the point. Guessing costs another
+    // request against the very limit the user is waiting out.
+    const line = buildCatalogNoticeText({
+      failures: [failure("magus", "rate-limited", NOW + 240_000)],
+      unverifiedPlugins: 17,
+      width: 160,
+      now: NOW,
+    }) as string;
+    expect(line).toContain("retrying in 4m");
+  });
+
+  it("uses the soonest retry when several catalogs are waiting", () => {
+    const line = buildCatalogNoticeText({
+      failures: [
+        failure("magus", "rate-limited", NOW + 600_000),
+        failure("magus-alpha", "rate-limited", NOW + 45_000),
+      ],
+      unverifiedPlugins: 2,
+      width: 160,
+      now: NOW,
+    }) as string;
+    expect(line).toContain("retrying in 45s");
+  });
+
+  it("falls back to the manual hint when no retry time is known", () => {
+    // raw.githubusercontent.com sends no retry-after, so for some failures there
+    // is genuinely no time to show. Inventing one would be worse than omitting it.
+    const line = buildCatalogNoticeText({
+      failures: [failure("magus", "network")],
+      unverifiedPlugins: 1,
+      width: 160,
+      now: NOW,
+    }) as string;
+    expect(line).toContain("r to retry");
+    expect(line).not.toContain("retrying in");
+  });
+
+  it("ignores a retry time that has already passed", () => {
+    const line = buildCatalogNoticeText({
+      failures: [failure("magus", "rate-limited", NOW - 5_000)],
+      unverifiedPlugins: 1,
+      width: 160,
+      now: NOW,
+    }) as string;
+    expect(line).toContain("r to retry");
+  });
+
+  it("keeps a retry affordance at every width, however narrow", () => {
+    const failures = ["a", "b", "c", "d", "e", "f"].map((n) =>
+      failure(n, "rate-limited", NOW + 90_000),
+    );
+    for (const width of [40, 60, 80, 100, 120, 200]) {
+      const line = buildCatalogNoticeText({
+        failures,
+        unverifiedPlugins: 331,
+        width,
+        now: NOW,
+      }) as string;
+      expect(line).not.toBeNull();
+      expect(line).toContain("retrying in");
+    }
+  });
+
+  it("never renders wider than the pane", () => {
+    const failures = ["a", "b", "c", "d", "e", "f"].map((n) =>
+      failure(n, "rate-limited", NOW + 90_000),
+    );
+    for (const width of [40, 60, 80, 100, 120, 200]) {
+      const line = buildCatalogNoticeText({
+        failures,
+        unverifiedPlugins: 331,
+        width,
+        now: NOW,
+      }) as string;
+      // +1 for `⚠` rendering double-width while String.length counts it once.
+      expect(line.length + 1).toBeLessThanOrEqual(width);
+    }
+  });
+});

package/src/__tests__/github-budget.test.ts

@@ -0,0 +1,200 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import {
+  activeCooldowns,
+  cooldownFor,
+  describeCooldown,
+  formatWait,
+  hostOf,
+  recordRateLimit,
+  recordSuccess,
+  remainingFromHeaders,
+  resetGitHubBudget,
+  waitMs,
+} from "../services/github-budget";
+
+/**
+ * The design hinges on one measured asymmetry (2026-08-17):
+ *
+ *   api.github.com            429/403 carries x-ratelimit-reset and retry-after
+ *   raw.githubusercontent.com 429 carries NEITHER — only a request id and a date
+ *
+ * So the module must be able to say "resets in 4m" when GitHub said so, and must
+ * NOT say it otherwise. Fabricating a reset time would be the same sin as the
+ * original bug: reporting a guess as a fact.
+ */
+
+const NOW = 1_786_980_000_000;
+
+beforeEach(() => {
+  resetGitHubBudget();
+});
+
+describe("hostOf", () => {
+  it("recognises the two budgeted hosts and nothing else", () => {
+    expect(hostOf("https://api.github.com/repos/x/y")).toBe("api.github.com");
+    expect(hostOf("https://raw.githubusercontent.com/x/y/main/f.json")).toBe(
+      "raw.githubusercontent.com",
+    );
+    expect(hostOf("https://github.com/x/y")).toBeNull();
+    expect(hostOf("not a url")).toBeNull();
+  });
+});
+
+describe("recordRateLimit — exact timing when GitHub provides it", () => {
+  it("honours retry-after in seconds", () => {
+    const cooldown = recordRateLimit(
+      "api.github.com",
+      new Headers({ "retry-after": "120" }),
+      NOW,
+    );
+    expect(cooldown.exact).toBe(true);
+    expect(cooldown.until).toBe(NOW + 120_000);
+    expect(describeCooldown(cooldown, NOW)).toBe(
+      "GitHub rate limit resets in 2m",
+    );
+  });
+
+  it("honours retry-after as an HTTP date", () => {
+    const when = new Date(NOW + 300_000).toUTCString();
+    const cooldown = recordRateLimit(
+      "api.github.com",
+      new Headers({ "retry-after": when }),
+      NOW,
+    );
+    expect(cooldown.exact).toBe(true);
+    // UTCString drops sub-second precision, so allow a second of slack.
+    expect(Math.abs(cooldown.until - (NOW + 300_000))).toBeLessThanOrEqual(1000);
+  });
+
+  it("reads x-ratelimit-reset as epoch SECONDS, not milliseconds", () => {
+    // Treating it as ms lands in 1970, so the cooldown expires instantly and the
+    // UI reports "not rate limited" while GitHub is still refusing every call.
+    const resetEpochSeconds = Math.floor(NOW / 1000) + 600;
+    const cooldown = recordRateLimit(
+      "api.github.com",
+      new Headers({ "x-ratelimit-reset": String(resetEpochSeconds) }),
+      NOW,
+    );
+    expect(cooldown.exact).toBe(true);
+    expect(cooldown.until).toBe(resetEpochSeconds * 1000);
+    expect(waitMs("api.github.com", NOW)).toBeGreaterThan(0);
+  });
+
+  it("caps an implausible server window so a bad header cannot wedge the UI", () => {
+    const cooldown = recordRateLimit(
+      "api.github.com",
+      new Headers({ "retry-after": String(60 * 60 * 24 * 30) }),
+      NOW,
+    );
+    expect(cooldown.until - NOW).toBeLessThanOrEqual(60 * 60_000);
+  });
+});
+
+describe("recordRateLimit — backoff when GitHub provides nothing", () => {
+  it("does not claim a reset time it was never told", () => {
+    // This is the raw.githubusercontent.com case, measured: a bare 429.
+    const cooldown = recordRateLimit(
+      "raw.githubusercontent.com",
+      new Headers(),
+      NOW,
+    );
+    expect(cooldown.exact).toBe(false);
+    expect(describeCooldown(cooldown, NOW)).toContain("next attempt in");
+    expect(describeCooldown(cooldown, NOW)).not.toContain("resets in");
+  });
+
+  it("backs off further on each consecutive failure", () => {
+    const first = recordRateLimit("raw.githubusercontent.com", undefined, NOW);
+    const second = recordRateLimit("raw.githubusercontent.com", undefined, NOW);
+    const third = recordRateLimit("raw.githubusercontent.com", undefined, NOW);
+    expect(second.until).toBeGreaterThan(first.until);
+    expect(third.until).toBeGreaterThan(second.until);
+    expect(third.strikes).toBe(3);
+  });
+
+  it("ignores a retry-after that is garbage or already past", () => {
+    const garbage = recordRateLimit(
+      "raw.githubusercontent.com",
+      new Headers({ "retry-after": "soon-ish" }),
+      NOW,
+    );
+    expect(garbage.exact).toBe(false);
+    expect(garbage.until).toBeGreaterThan(NOW);
+  });
+});
+
+describe("the gate", () => {
+  it("blocks while cooling and clears when the window passes", () => {
+    const cooldown = recordRateLimit(
+      "raw.githubusercontent.com",
+      undefined,
+      NOW,
+    );
+    expect(cooldownFor("raw.githubusercontent.com", NOW)).not.toBeNull();
+    expect(
+      cooldownFor("raw.githubusercontent.com", cooldown.until + 1),
+    ).toBeNull();
+    expect(waitMs("raw.githubusercontent.com", cooldown.until + 1)).toBe(0);
+  });
+
+  it("keeps the two hosts on separate budgets", () => {
+    // They are separate buckets upstream. Blocking raw because the API is
+    // exhausted would stop work that would have succeeded.
+    recordRateLimit("api.github.com", new Headers({ "retry-after": "60" }), NOW);
+    expect(cooldownFor("api.github.com", NOW)).not.toBeNull();
+    expect(cooldownFor("raw.githubusercontent.com", NOW)).toBeNull();
+  });
+
+  it("clears the cooldown and the strike count on success", () => {
+    // Without resetting strikes, one bad afternoon pins the backoff at ten
+    // minutes for the rest of the session even though calls are succeeding.
+    recordRateLimit("raw.githubusercontent.com", undefined, NOW);
+    recordRateLimit("raw.githubusercontent.com", undefined, NOW);
+    recordSuccess("raw.githubusercontent.com");
+    expect(cooldownFor("raw.githubusercontent.com", NOW)).toBeNull();
+
+    const afterRecovery = recordRateLimit(
+      "raw.githubusercontent.com",
+      undefined,
+      NOW,
+    );
+    expect(afterRecovery.strikes).toBe(1);
+  });
+
+  it("lists active cooldowns soonest first", () => {
+    recordRateLimit(
+      "api.github.com",
+      new Headers({ "retry-after": "600" }),
+      NOW,
+    );
+    recordRateLimit(
+      "raw.githubusercontent.com",
+      new Headers({ "retry-after": "30" }),
+      NOW,
+    );
+    const active = activeCooldowns(NOW);
+    expect(active.map((c) => c.host)).toEqual([
+      "raw.githubusercontent.com",
+      "api.github.com",
+    ]);
+  });
+});
+
+describe("remainingFromHeaders", () => {
+  it("reads the budget so a caller can stop before tripping the limit", () => {
+    expect(
+      remainingFromHeaders(new Headers({ "x-ratelimit-remaining": "51" })),
+    ).toBe(51);
+    expect(remainingFromHeaders(new Headers())).toBeNull();
+  });
+});
+
+describe("formatWait", () => {
+  it("reads naturally at every scale", () => {
+    expect(formatWait(0)).toBe("0s");
+    expect(formatWait(45_000)).toBe("45s");
+    expect(formatWait(90_000)).toBe("2m");
+    expect(formatWait(3_600_000)).toBe("1h 0m");
+    expect(formatWait(4_320_000)).toBe("1h 12m");
+  });
+});