@vellumai/assistant 0.8.1 → 0.8.2

package/src/cli/commands/__tests__/changelog.test.ts

@@ -1,19 +1,28 @@
 /**
  * Tests for the `assistant changelog` CLI command.
  *
+ * Every test exercises the public CLI surface via `runCli`. Internal helpers
+ * (cache plumbing, version compare, rendering) are validated through the
+ * commands that exercise them, not via module-level test exports.
+ *
  * Coverage:
- *   - Pure helpers (compareTags, normalizeTag, stableReleases, parseLimit,
- *     renderRelease, renderList).
- *   - Cache plumbing (read returns null when missing/corrupt; write+read
- *     roundtrip; stale detection).
- *   - Cache-aware loaders (cache hit short-circuits fetch; --no-cache skips
- *     read but still writes; stale cache refetches).
- *   - GitHub error mapping (403/429 → rate-limit message; 404 → null tag).
- *   - End-to-end command actions (default = latest, --since, show, list,
- *     --json, missing tag, empty release list).
+ *   - Default action (latest stable, --since, --json).
+ *   - `show <version>` (renders, --json, 404, persists to cache).
+ *   - `list` (rows, --json, --limit/--no-cache propagation).
+ *   - Cache behavior (fresh cache short-circuits fetch; --no-cache bypass;
+ *     stale TTL refetch; cache capped at CACHE_STABLE_LIMIT stable
+ *     releases; pagination buffer absorbs drafts/prereleases).
+ *   - Error mapping (rate-limit → friendly stderr; non-zero exit).
  */
 
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
@@ -98,6 +107,18 @@ const REL_DRAFT: FakeRelease = {
   prerelease: false,
 };
 
+function stableRelease(tag: string, body = `release ${tag}`): FakeRelease {
+  return {
+    tag_name: tag,
+    name: tag,
+    body,
+    published_at: "2026-04-01T12:00:00Z",
+    html_url: `https://github.com/vellum-ai/vellum-assistant/releases/tag/${tag}`,
+    draft: false,
+    prerelease: false,
+  };
+}
+
 // ── fetch mock harness ───────────────────────────────────────────────
 
 type FetchHandler = (url: string, init?: RequestInit) => Promise<Response>;
@@ -143,25 +164,29 @@ function jsonResponse(payload: unknown, status = 200): Response {
   });
 }
 
+const cachePath = join(TMP_ROOT, "data", "changelog-cache.json");
+
+interface CacheShape {
+  fetchedAt: string;
+  recent: FakeRelease[];
+  byTag: Record<string, FakeRelease>;
+}
+
+function readCacheFile(): CacheShape | null {
+  if (!existsSync(cachePath)) return null;
+  return JSON.parse(readFileSync(cachePath, "utf-8")) as CacheShape;
+}
+
+function writeCacheFile(cache: CacheShape): void {
+  mkdirSync(join(TMP_ROOT, "data"), { recursive: true });
+  writeFileSync(cachePath, JSON.stringify(cache, null, 2));
+}
+
 // ── Import module under test (after mocks) ───────────────────────────
 
-const { registerChangelogCommand, __testing } = await import("../changelog.js");
-const {
-  compareTags,
-  normalizeTag,
-  stableReleases,
-  parseLimit,
-  renderRelease,
-  renderList,
-  readCache,
-  writeCache,
-  isStale,
-  loadReleases,
-  loadReleaseByTag,
-  getCachePath,
-} = __testing;
-
-// ── stdout / exit capture ────────────────────────────────────────────
+const { registerChangelogCommand } = await import("../changelog.js");
+
+// ── CLI driver ───────────────────────────────────────────────────────
 
 interface CapturedRun {
   stdout: string;
@@ -216,287 +241,32 @@ async function runCli(argv: string[]): Promise<CapturedRun> {
   };
 }
 
-// ── Pure helpers ─────────────────────────────────────────────────────
-
-describe("changelog helpers", () => {
-  describe("compareTags", () => {
-    test("equal tags compare as 0", () => {
-      expect(compareTags("v0.8.0", "v0.8.0")).toBe(0);
-    });
-    test("higher major beats lower", () => {
-      expect(compareTags("v1.0.0", "v0.99.99")).toBeGreaterThan(0);
-    });
-    test("higher patch beats lower", () => {
-      expect(compareTags("v0.8.1", "v0.8.0")).toBeGreaterThan(0);
-    });
-    test("accepts inputs without the v prefix", () => {
-      expect(compareTags("0.8.1", "v0.8.0")).toBeGreaterThan(0);
-      expect(compareTags("0.7.0", "0.8.0")).toBeLessThan(0);
-    });
-    test("missing patch parts default to 0", () => {
-      expect(compareTags("v0.8", "v0.8.0")).toBe(0);
-      expect(compareTags("v0.8.1", "v0.8")).toBeGreaterThan(0);
-    });
-  });
-
-  describe("normalizeTag", () => {
-    test("adds v prefix when missing", () => {
-      expect(normalizeTag("0.8.0")).toBe("v0.8.0");
-    });
-    test("leaves v prefix untouched", () => {
-      expect(normalizeTag("v0.8.0")).toBe("v0.8.0");
-    });
-  });
-
-  describe("stableReleases", () => {
-    test("drops drafts and prereleases", () => {
-      const filtered = stableReleases([
-        REL_080,
-        REL_080_RC,
-        REL_DRAFT,
-        REL_079,
-      ]);
-      expect(filtered.map((r) => r.tag_name)).toEqual(["v0.8.0", "v0.7.9"]);
-    });
-    test("preserves order of the stable subset", () => {
-      const filtered = stableReleases([REL_079, REL_080]);
-      expect(filtered.map((r) => r.tag_name)).toEqual(["v0.7.9", "v0.8.0"]);
-    });
-  });
-
-  describe("parseLimit", () => {
-    test("falls back when input is missing", () => {
-      expect(parseLimit(undefined, 30)).toBe(30);
-    });
-    test("falls back on garbage input", () => {
-      expect(parseLimit("not-a-number", 30)).toBe(30);
-    });
-    test("falls back when input is zero or negative", () => {
-      expect(parseLimit("0", 30)).toBe(30);
-      expect(parseLimit("-5", 30)).toBe(30);
-    });
-    test("clamps to the upper bound of 100", () => {
-      expect(parseLimit("999", 30)).toBe(100);
-    });
-    test("accepts valid values", () => {
-      expect(parseLimit("42", 30)).toBe(42);
-    });
-  });
-
-  describe("renderRelease", () => {
-    test("includes heading, date, html url, and body", () => {
-      const rendered = renderRelease(REL_080);
-      expect(rendered).toContain("# v0.8.0 — Tavily");
-      expect(rendered).toContain("Published: 2026-05-10");
-      expect(rendered).toContain(REL_080.html_url);
-      expect(rendered).toContain("Tavily web search");
-    });
-    test("falls back to tag when name is empty", () => {
-      const rendered = renderRelease({ ...REL_080, name: "" });
-      expect(rendered).toContain("# v0.8.0");
-    });
-    test("placeholder when body is empty", () => {
-      const rendered = renderRelease({ ...REL_080, body: "   " });
-      expect(rendered).toContain("(no release body)");
-    });
-  });
-
-  describe("renderList", () => {
-    test("formats one row per release", () => {
-      const rendered = renderList([REL_080, REL_079]);
-      const lines = rendered.split("\n");
-      expect(lines).toHaveLength(2);
-      expect(lines[0]).toContain("v0.8.0");
-      expect(lines[0]).toContain("2026-05-10");
-      expect(lines[1]).toContain("v0.7.9");
-    });
-    test("handles empty input", () => {
-      expect(renderList([])).toBe("No releases found.");
-    });
-  });
-});
-
-// ── Cache plumbing ───────────────────────────────────────────────────
-
-describe("changelog cache", () => {
-  test("cache path lives under the workspace data dir", () => {
-    expect(getCachePath()).toBe(join(TMP_ROOT, "data", "changelog-cache.json"));
-  });
-
-  test("readCache returns null when the file is missing", () => {
-    expect(readCache()).toBeNull();
-  });
-
-  test("write + read roundtrip", () => {
-    const store = {
-      fetchedAt: new Date().toISOString(),
-      releases: [REL_080, REL_079],
-    };
-    writeCache(store);
-    const loaded = readCache();
-    expect(loaded).not.toBeNull();
-    expect(loaded?.releases.map((r) => r.tag_name)).toEqual([
-      "v0.8.0",
-      "v0.7.9",
-    ]);
-  });
-
-  test("readCache returns null on corrupt JSON", () => {
-    writeCache({ fetchedAt: new Date().toISOString(), releases: [REL_080] });
-    // Re-write garbage on top of the cache file.
-    writeFileSync(getCachePath(), "{not valid json");
-    expect(readCache()).toBeNull();
-  });
-
-  test("readCache returns null when shape is wrong", () => {
-    mkdirSync(join(TMP_ROOT, "data"), { recursive: true });
-    writeFileSync(getCachePath(), JSON.stringify({ foo: "bar" }));
-    expect(readCache()).toBeNull();
-  });
-
-  test("isStale flags caches older than the TTL", () => {
-    const fresh = { fetchedAt: new Date().toISOString(), releases: [] };
-    expect(isStale(fresh)).toBe(false);
-    const old = {
-      fetchedAt: new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString(),
-      releases: [],
-    };
-    expect(isStale(old)).toBe(true);
-  });
-
-  test("isStale treats unparseable timestamps as stale", () => {
-    expect(isStale({ fetchedAt: "not-a-date", releases: [] })).toBe(true);
-  });
-});
-
-// ── Cache-aware loaders ──────────────────────────────────────────────
-
-describe("loadReleases", () => {
-  test("returns cached releases when fresh and big enough", async () => {
-    writeCache({
-      fetchedAt: new Date().toISOString(),
-      releases: [REL_080, REL_079],
-    });
-    fetchHandler = async () => jsonResponse([]);
-    const result = await loadReleases({ noCache: false, limit: 2 });
-    expect(result.map((r) => r.tag_name)).toEqual(["v0.8.0", "v0.7.9"]);
-    expect(fetchCalls).toHaveLength(0);
-  });
-
-  test("fetches from GitHub when cache is missing", async () => {
-    fetchHandler = async () => jsonResponse([REL_080, REL_079]);
-    const result = await loadReleases({ noCache: false, limit: 30 });
-    expect(result.map((r) => r.tag_name)).toEqual(["v0.8.0", "v0.7.9"]);
-    expect(fetchCalls).toHaveLength(1);
-    expect(fetchCalls[0]).toContain(
-      "https://api.github.com/repos/vellum-ai/vellum-assistant/releases",
-    );
-    // Cache should now be populated.
-    expect(readCache()?.releases).toHaveLength(2);
-  });
-
-  test("--no-cache forces a refetch", async () => {
-    writeCache({
-      fetchedAt: new Date().toISOString(),
-      releases: [REL_080, REL_079],
-    });
-    fetchHandler = async () => jsonResponse([REL_080]);
-    const result = await loadReleases({ noCache: true, limit: 30 });
-    expect(result.map((r) => r.tag_name)).toEqual(["v0.8.0"]);
-    expect(fetchCalls).toHaveLength(1);
-  });
-
-  test("stale cache triggers a refetch", async () => {
-    writeCache({
-      fetchedAt: new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString(),
-      releases: [REL_079],
-    });
-    fetchHandler = async () => jsonResponse([REL_080, REL_079]);
-    const result = await loadReleases({ noCache: false, limit: 30 });
-    expect(result.map((r) => r.tag_name)).toEqual(["v0.8.0", "v0.7.9"]);
-    expect(fetchCalls).toHaveLength(1);
-  });
-
-  test("cache with fewer entries than the requested limit triggers a refetch", async () => {
-    writeCache({
-      fetchedAt: new Date().toISOString(),
-      releases: [REL_080],
-    });
-    fetchHandler = async () => jsonResponse([REL_080, REL_079]);
-    const result = await loadReleases({ noCache: false, limit: 2 });
-    expect(result).toHaveLength(2);
-    expect(fetchCalls).toHaveLength(1);
-  });
-
-  test("maps 403 to a rate-limit message", async () => {
-    fetchHandler = async () => new Response("rate limit", { status: 403 });
-    await expect(loadReleases({ noCache: true, limit: 30 })).rejects.toThrow(
-      /rate limit/i,
-    );
-  });
-});
-
-describe("loadReleaseByTag", () => {
-  test("returns from cache when the tag is present", async () => {
-    writeCache({
-      fetchedAt: new Date().toISOString(),
-      releases: [REL_080, REL_079],
-    });
-    fetchHandler = async () => jsonResponse({}, 500);
-    const found = await loadReleaseByTag("v0.8.0", { noCache: false });
-    expect(found?.tag_name).toBe("v0.8.0");
-    expect(fetchCalls).toHaveLength(0);
-  });
-
-  test("falls through to fetch when the tag is missing from cache", async () => {
-    writeCache({
-      fetchedAt: new Date().toISOString(),
-      releases: [REL_080],
-    });
-    fetchHandler = async () => jsonResponse(REL_079);
-    const found = await loadReleaseByTag("v0.7.9", { noCache: false });
-    expect(found?.tag_name).toBe("v0.7.9");
-    expect(fetchCalls).toHaveLength(1);
-    expect(fetchCalls[0]).toContain("/tags/v0.7.9");
-  });
-
-  test("--no-cache always fetches", async () => {
-    writeCache({
-      fetchedAt: new Date().toISOString(),
-      releases: [REL_080],
-    });
-    fetchHandler = async () => jsonResponse(REL_080);
-    await loadReleaseByTag("v0.8.0", { noCache: true });
-    expect(fetchCalls).toHaveLength(1);
-  });
-
-  test("returns null on 404", async () => {
-    fetchHandler = async () => new Response("not found", { status: 404 });
-    const found = await loadReleaseByTag("v99.99.99", { noCache: true });
-    expect(found).toBeNull();
-  });
-});
-
-// ── End-to-end command surface ───────────────────────────────────────
+// ── Default action ───────────────────────────────────────────────────
 
-describe("changelog command", () => {
-  test("default action shows the latest stable release", async () => {
+describe("assistant changelog (default action)", () => {
+  test("shows the latest stable release, filtering drafts and prereleases", async () => {
     fetchHandler = async () =>
       jsonResponse([REL_DRAFT, REL_080_RC, REL_080, REL_079]);
     const result = await runCli(["changelog"]);
     expect(result.exitCode).toBe(0);
     expect(result.stdout).toContain("# v0.8.0 — Tavily");
+    expect(result.stdout).toContain("Published: 2026-05-10");
+    expect(result.stdout).toContain(REL_080.html_url);
+    expect(result.stdout).toContain("Tavily web search");
     expect(result.stdout).not.toContain("draft");
     expect(result.stdout).not.toContain("rc.1");
   });
 
+  test("--json emits the latest release as a JSON object", async () => {
+    fetchHandler = async () => jsonResponse([REL_080, REL_079]);
+    const result = await runCli(["changelog", "--json"]);
+    expect(result.exitCode).toBe(0);
+    const parsed = JSON.parse(result.stdout) as { tag_name: string };
+    expect(parsed.tag_name).toBe("v0.8.0");
+  });
+
   test("--since concatenates every newer stable release, newest first", async () => {
-    const REL_081 = {
-      ...REL_080,
-      tag_name: "v0.8.1",
-      name: "v0.8.1",
-      body: "patch notes",
-    };
+    const REL_081 = stableRelease("v0.8.1", "patch notes");
     fetchHandler = async () => jsonResponse([REL_081, REL_080, REL_079]);
     const result = await runCli(["changelog", "--since", "0.7.9"]);
     expect(result.exitCode).toBe(0);
@@ -507,43 +277,117 @@ describe("changelog command", () => {
     expect(result.stdout).not.toContain("v0.7.9");
   });
 
-  test("--since with no newer releases prints an empty-state line", async () => {
+  test("--since accepts a tag with or without a v prefix", async () => {
     fetchHandler = async () => jsonResponse([REL_080, REL_079]);
-    const result = await runCli(["changelog", "--since", "1.0.0"]);
+    const result = await runCli(["changelog", "--since", "v0.7.9"]);
     expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("v0.8.0");
   });
 
-  test("--json with default action emits the latest release as JSON", async () => {
+  test("--since with no newer releases exits 0 and emits no release bodies", async () => {
     fetchHandler = async () => jsonResponse([REL_080, REL_079]);
-    const result = await runCli(["changelog", "--json"]);
+    const result = await runCli(["changelog", "--since", "1.0.0"]);
     expect(result.exitCode).toBe(0);
-    const parsed = JSON.parse(result.stdout) as { tag_name: string };
-    expect(parsed.tag_name).toBe("v0.8.0");
+    expect(result.stdout).not.toContain("Published:");
+  });
+
+  test("--since --json emits an empty releases array when nothing matches", async () => {
+    fetchHandler = async () => jsonResponse([REL_080]);
+    const result = await runCli(["changelog", "--since", "1.0.0", "--json"]);
+    expect(result.exitCode).toBe(0);
+    const parsed = JSON.parse(result.stdout) as { releases: unknown[] };
+    expect(parsed.releases).toEqual([]);
   });
 
-  test("show <version> prints the named release", async () => {
+  test("empty release list (after stable filter) exits non-zero", async () => {
+    fetchHandler = async () => jsonResponse([REL_080_RC, REL_DRAFT]);
+    const result = await runCli(["changelog"]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("No releases found");
+  });
+});
+
+// ── show <version> ───────────────────────────────────────────────────
+
+describe("assistant changelog show <version>", () => {
+  test("prints the named release", async () => {
     fetchHandler = async () => jsonResponse(REL_080);
     const result = await runCli(["changelog", "show", "0.8.0"]);
     expect(result.exitCode).toBe(0);
     expect(result.stdout).toContain("# v0.8.0 — Tavily");
+    expect(fetchCalls[0]).toContain("/releases/tags/v0.8.0");
   });
 
-  test("show <version> with no match exits non-zero", async () => {
+  test("accepts a v-prefixed input", async () => {
+    fetchHandler = async () => jsonResponse(REL_080);
+    const result = await runCli(["changelog", "show", "v0.8.0"]);
+    expect(result.exitCode).toBe(0);
+    expect(fetchCalls[0]).toContain("/releases/tags/v0.8.0");
+  });
+
+  test("--json forwards through the parent into the show subcommand", async () => {
+    fetchHandler = async () => jsonResponse(REL_080);
+    const result = await runCli(["changelog", "show", "0.8.0", "--json"]);
+    expect(result.exitCode).toBe(0);
+    const parsed = JSON.parse(result.stdout) as { tag_name: string };
+    expect(parsed.tag_name).toBe("v0.8.0");
+  });
+
+  test("404 surfaces a friendly stderr and exits non-zero", async () => {
     fetchHandler = async () => new Response("not found", { status: 404 });
     const result = await runCli(["changelog", "show", "99.99.99"]);
     expect(result.exitCode).toBe(1);
     expect(result.stderr).toContain("No release found");
   });
 
-  test("list prints rows of tag/date/name", async () => {
-    fetchHandler = async () => jsonResponse([REL_080, REL_079]);
+  test("persists a fetched tag into the cache so the next call short-circuits", async () => {
+    let callCount = 0;
+    fetchHandler = async () => {
+      callCount += 1;
+      return jsonResponse(REL_079);
+    };
+
+    const first = await runCli(["changelog", "show", "0.7.9"]);
+    expect(first.exitCode).toBe(0);
+    expect(callCount).toBe(1);
+
+    const cached = readCacheFile();
+    expect(cached?.byTag["v0.7.9"]?.tag_name).toBe("v0.7.9");
+
+    const second = await runCli(["changelog", "show", "0.7.9"]);
+    expect(second.exitCode).toBe(0);
+    expect(callCount).toBe(1); // no extra fetch
+  });
+
+  test("--no-cache skips the cached entry and refetches", async () => {
+    writeCacheFile({
+      fetchedAt: new Date().toISOString(),
+      recent: [],
+      byTag: { "v0.8.0": REL_080 },
+    });
+    fetchHandler = async () => jsonResponse(REL_080);
+    const result = await runCli(["changelog", "show", "0.8.0", "--no-cache"]);
+    expect(result.exitCode).toBe(0);
+    expect(fetchCalls).toHaveLength(1);
+  });
+});
+
+// ── list ──────────────────────────────────────────────────────────────
+
+describe("assistant changelog list", () => {
+  test("prints one row per stable release", async () => {
+    fetchHandler = async () =>
+      jsonResponse([REL_080_RC, REL_080, REL_DRAFT, REL_079]);
     const result = await runCli(["changelog", "list"]);
     expect(result.exitCode).toBe(0);
-    expect(result.stdout).toContain("v0.8.0");
-    expect(result.stdout).toContain("v0.7.9");
+    const lines = result.stdout.trim().split("\n");
+    expect(lines).toHaveLength(2);
+    expect(lines[0]).toContain("v0.8.0");
+    expect(lines[0]).toContain("2026-05-10");
+    expect(lines[1]).toContain("v0.7.9");
   });
 
-  test("list --json emits a releases array", async () => {
+  test("--json emits a releases array", async () => {
     fetchHandler = async () => jsonResponse([REL_080, REL_079]);
     const result = await runCli(["changelog", "list", "--json"]);
     expect(result.exitCode).toBe(0);
@@ -556,9 +400,9 @@ describe("changelog command", () => {
     ]);
   });
 
-  test("list --no-cache --json --limit 5 forwards parent flags into the subcommand", async () => {
+  test("--no-cache --json --limit forwards parent flags into the subcommand", async () => {
     fetchHandler = async () =>
-      jsonResponse([REL_080, REL_079, { ...REL_079, tag_name: "v0.7.8" }]);
+      jsonResponse([REL_080, REL_079, stableRelease("v0.7.8")]);
     const result = await runCli([
       "changelog",
       "list",
@@ -572,22 +416,163 @@ describe("changelog command", () => {
       releases: Array<{ tag_name: string }>;
     };
     expect(parsed.releases.length).toBeGreaterThan(0);
-    expect(fetchCalls[0]).toContain("per_page=5");
+    // Even with --limit 5, the page-size buffer absorbs drafts/prereleases.
+    expect(fetchCalls[0]).toMatch(/per_page=\d+/);
   });
+});
 
-  test("show <version> --json forwards --json from parent into the show subcommand", async () => {
-    fetchHandler = async () => jsonResponse(REL_080);
-    const result = await runCli(["changelog", "show", "0.8.0", "--json"]);
+// ── Cache behavior ───────────────────────────────────────────────────
+
+describe("assistant changelog cache", () => {
+  test("second invocation reuses a fresh cache without re-fetching", async () => {
+    let callCount = 0;
+    fetchHandler = async () => {
+      callCount += 1;
+      return jsonResponse([REL_080, REL_079]);
+    };
+    await runCli(["changelog"]);
+    expect(callCount).toBe(1);
+
+    await runCli(["changelog"]);
+    // Second call should hit the rolling-recent cache: latest is still
+    // populated and not stale, and we only need 1 entry for the default
+    // action.
+    expect(callCount).toBe(1);
+  });
+
+  test("--no-cache forces a refetch even with a fresh cache", async () => {
+    writeCacheFile({
+      fetchedAt: new Date().toISOString(),
+      recent: [REL_080, REL_079],
+      byTag: { "v0.8.0": REL_080, "v0.7.9": REL_079 },
+    });
+    let callCount = 0;
+    fetchHandler = async () => {
+      callCount += 1;
+      return jsonResponse([REL_080, REL_079]);
+    };
+    const result = await runCli(["changelog", "--no-cache"]);
     expect(result.exitCode).toBe(0);
-    const parsed = JSON.parse(result.stdout) as { tag_name: string };
-    expect(parsed.tag_name).toBe("v0.8.0");
+    expect(callCount).toBe(1);
   });
 
-  test("rate-limit error surfaces a friendly message", async () => {
+  test("stale cache (older than TTL) triggers a refetch", async () => {
+    writeCacheFile({
+      fetchedAt: new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString(),
+      recent: [REL_079],
+      byTag: { "v0.7.9": REL_079 },
+    });
+    let callCount = 0;
+    fetchHandler = async () => {
+      callCount += 1;
+      return jsonResponse([REL_080, REL_079]);
+    };
+    await runCli(["changelog"]);
+    expect(callCount).toBe(1);
+  });
+
+  test("corrupt cache JSON is treated as a miss", async () => {
+    mkdirSync(join(TMP_ROOT, "data"), { recursive: true });
+    writeFileSync(cachePath, "{not valid json");
+    let callCount = 0;
+    fetchHandler = async () => {
+      callCount += 1;
+      return jsonResponse([REL_080]);
+    };
+    await runCli(["changelog"]);
+    expect(callCount).toBe(1);
+  });
+
+  test("rolling cache is capped at 5 stable releases regardless of fetched count", async () => {
+    const stables = [
+      stableRelease("v0.9.0"),
+      stableRelease("v0.8.9"),
+      stableRelease("v0.8.8"),
+      stableRelease("v0.8.7"),
+      stableRelease("v0.8.6"),
+      stableRelease("v0.8.5"),
+      stableRelease("v0.8.4"),
+      stableRelease("v0.8.3"),
+    ];
+    fetchHandler = async () => jsonResponse(stables);
+    await runCli(["changelog", "list", "--limit", "8"]);
+
+    const cached = readCacheFile();
+    expect(cached?.recent.length).toBe(5);
+    expect(cached?.recent.map((r) => r.tag_name)).toEqual([
+      "v0.9.0",
+      "v0.8.9",
+      "v0.8.8",
+      "v0.8.7",
+      "v0.8.6",
+    ]);
+  });
+
+  test("page-size buffer absorbs drafts/prereleases so a small --limit still surfaces stable releases", async () => {
+    // First page is mostly noise — drafts and prereleases — followed by
+    // stable releases. With a hardcoded per_page=limit the small budget
+    // would be eaten by noise. The buffer keeps stable releases visible.
+    const noise = Array.from({ length: 10 }, (_, i) => ({
+      ...REL_DRAFT,
+      tag_name: `v9.9.${i}`,
+    }));
+    fetchHandler = async () => jsonResponse([...noise, REL_080, REL_079]);
+    const result = await runCli([
+      "changelog",
+      "list",
+      "--limit",
+      "2",
+      "--json",
+    ]);
+    expect(result.exitCode).toBe(0);
+    const parsed = JSON.parse(result.stdout) as {
+      releases: Array<{ tag_name: string }>;
+    };
+    expect(parsed.releases.map((r) => r.tag_name)).toEqual([
+      "v0.8.0",
+      "v0.7.9",
+    ]);
+  });
+
+  test("--limit larger than cached count refetches to satisfy the request", async () => {
+    writeCacheFile({
+      fetchedAt: new Date().toISOString(),
+      recent: [REL_080],
+      byTag: { "v0.8.0": REL_080 },
+    });
+    let callCount = 0;
+    fetchHandler = async () => {
+      callCount += 1;
+      return jsonResponse([REL_080, REL_079]);
+    };
+    await runCli(["changelog", "list", "--limit", "10"]);
+    expect(callCount).toBe(1);
+  });
+});
+
+// ── Errors ───────────────────────────────────────────────────────────
+
+describe("assistant changelog errors", () => {
+  test("403 rate-limit response surfaces a friendly stderr", async () => {
     fetchHandler = async () =>
       new Response("rate limit exceeded", { status: 403 });
     const result = await runCli(["changelog", "--no-cache"]);
     expect(result.exitCode).toBe(1);
     expect(result.stderr).toMatch(/rate limit/i);
   });
+
+  test("429 rate-limit response also surfaces the friendly message", async () => {
+    fetchHandler = async () =>
+      new Response("too many requests", { status: 429 });
+    const result = await runCli(["changelog", "--no-cache"]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toMatch(/rate limit/i);
+  });
+
+  test("500 from GitHub surfaces the status code", async () => {
+    fetchHandler = async () => new Response("server is sad", { status: 500 });
+    const result = await runCli(["changelog", "--no-cache"]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("500");
+  });
 });