@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/server/lib/tray/tray.test.ts

@@ -0,0 +1,225 @@
+// The tray's decision layer: the login entry it registers, and the config a host
+// reads.
+//
+// Pure content builders, on purpose. The plist a LaunchAgent reads, the
+// `.desktop` file a freedesktop session reads and the Run value Windows stores
+// are all strings, so they can be asserted without touching a real
+// `~/Library/LaunchAgents`, a real `reg.exe` or a real session. What IS verified
+// against the OS lives in the smoke runs recorded in AGENTS.md.
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  installAutostart,
+  isAutostartInstalled,
+  renderDesktopEntry,
+  renderLaunchAgent,
+  renderWindowsRunValue,
+  removeLegacyAutostart,
+  uninstallAutostart,
+} from '@/server/lib/tray/autostart';
+import { buildLoginEntryArgv } from '@/server/lib/tray/entry';
+import { buildTrayConfig, trayUrl } from '@/server/lib/tray/config';
+import { buildMenuModel, menuPayload } from '@/server/lib/tray/host/linux.js';
+
+describe('buildLoginEntryArgv', () => {
+  const base = { bun: '/bun', cli: '/pkg/src/cli/kabmo.js', port: 3000, host: '127.0.0.1', tray: true, tls: false, lan: false };
+
+  // The load-bearing rule: launchd reaps a job's process tree when the job's
+  // program exits, so a detached `serve` (which returns as soon as the health
+  // check passes) left nothing running. The entry must hold the CLI open.
+  test('runs serve in the foreground, so the job does not exit', () => {
+    const argv = buildLoginEntryArgv(base);
+    expect(argv).toEqual(['/bun', '/pkg/src/cli/kabmo.js', 'serve', '--foreground', '--prod', '--port', '3000', '--host', '127.0.0.1', '--tray']);
+  });
+
+  test('pins the mode, since a login entry has no shell to export NODE_ENV', () => {
+    expect(buildLoginEntryArgv(base)).toContain('--prod');
+  });
+
+  test('carries the tray choice, so --startup alone starts without an icon', () => {
+    const withoutIcon = buildLoginEntryArgv({ ...base, tray: false });
+    expect(withoutIcon).not.toContain('--tray');
+    expect(withoutIcon).toContain('serve');
+  });
+
+  test('expresses --lan as an explicit address, not a flag', () => {
+    const lan = buildLoginEntryArgv({ ...base, lan: true, host: '0.0.0.0' });
+    expect(lan).toContain('0.0.0.0');
+    expect(lan).not.toContain('--lan');
+  });
+
+  test('carries --tls when the registering invocation served over TLS', () => {
+    expect(buildLoginEntryArgv({ ...base, tls: true })).toContain('--tls');
+  });
+});
+
+describe('renderLaunchAgent', () => {
+  test('runs at load, and never restarts a server the user stopped', () => {
+    const plist = renderLaunchAgent({ argv: ['/bun', '/cli.js', 'serve'], logFile: '/log' });
+    expect(plist).toContain('<key>RunAtLoad</key>');
+    // `KeepAlive` would restart a server the user stopped on purpose.
+    expect(plist).not.toContain('<key>KeepAlive</key>');
+  });
+
+  test('escapes an argument that would break the XML', () => {
+    const plist = renderLaunchAgent({ argv: ['/opt/a&b/<c>.js'], logFile: '/log' });
+    expect(plist).toContain('<string>/opt/a&amp;b/&lt;c&gt;.js</string>');
+  });
+});
+
+describe('renderDesktopEntry', () => {
+  test('quotes a path containing a space and leaves a plain one alone', () => {
+    const entry = renderDesktopEntry({ argv: ['/usr/bin/bun', '/home/a b/cli.js', 'serve'], port: 3000 });
+    expect(entry).toContain('Exec=/usr/bin/bun "/home/a b/cli.js" serve');
+    expect(entry).toContain('X-GNOME-Autostart-enabled=true');
+  });
+});
+
+describe('renderWindowsRunValue', () => {
+  test('quotes only the arguments that need it', () => {
+    const value = renderWindowsRunValue(['C:\\a b\\bun.exe', 'C:\\c\\cli.js', 'serve']);
+    expect(value).toBe('"C:\\a b\\bun.exe" C:\\c\\cli.js serve');
+  });
+});
+
+describe('trayUrl', () => {
+  test('resolves a bind-any address to loopback, and keeps the scheme', () => {
+    expect(trayUrl(3000, '0.0.0.0', false)).toBe('http://127.0.0.1:3000');
+    expect(trayUrl(3000, '127.0.0.1', true)).toBe('https://127.0.0.1:3000');
+    // A `--tls` server answers nothing on HTTP, so the scheme has to be carried.
+    expect(trayUrl(3000, 'localhost', true)).toBe('https://127.0.0.1:3000');
+  });
+});
+
+describe('buildTrayConfig', () => {
+  test('resolves the CLI entry without a `..` segment in it', () => {
+    const config = buildTrayConfig({
+      pkgRoot: process.cwd(),
+      port: 3999,
+      host: '127.0.0.1',
+      tls: false,
+      dataDir: '/data',
+      bun: '/bun',
+      icon: join(process.cwd(), 'public', 'icon-192x192.png'),
+      pidFile: '/data/tray/host/tray-3999.pid',
+      loginInstalled: false,
+    });
+    expect(config.cli).toContain(join('src', 'cli', 'kabmo.js'));
+    expect(config.cli).not.toContain('..');
+    expect(config.url).toBe('http://127.0.0.1:3999');
+    expect(config.logFile).toBe('/data/logs/kabmo-3999.log');
+    expect(config.loginInstalled).toBe(false);
+  });
+});
+
+describe('linux host menu', () => {
+  const config = { loginInstalled: false, url: 'http://127.0.0.1:3999', logFile: '/log' };
+
+  test('the login row names the way it will go', () => {
+    const off = buildMenuModel(config).find((row) => row.id === 'login');
+    expect(off?.title).toBe('Start at Login');
+    const on = buildMenuModel({ ...config, loginInstalled: true }).find((row) => row.id === 'login');
+    expect(on?.title).toBe('Disable Start at Login');
+  });
+
+  // yad and zenity split the menu on `!` and `|`, so a label carrying either
+  // would silently truncate the row.
+  test('a label cannot break the menu separators', () => {
+    const payload = menuPayload([{ id: 'login', title: 'Start | Stop!Server' }, { separator: true }, { id: 'quit', title: 'Quit Kabmo' }]);
+    const parts = payload.split('|');
+    expect(parts[0]).toContain('Start   Stop Server!action:login');
+    expect(parts[2]).toContain('Quit Kabmo!action:quit');
+  });
+});
+
+describe('autostart filesystem round trip', () => {
+  // Exercised against a temp XDG root: the real install was verified separately,
+  // and a test that wrote into the developer's own `~/.config/autostart` would be
+  // a test that installed something on every run. HOME is not enough —
+  // `os.homedir()` is resolved once at process start on macOS, so changing it
+  // mid-run left the write pointing at the developer's real home.
+  test('writes, reports and removes an entry', async () => {
+    const home = await mkdtemp(join(tmpdir(), 'kabmo-autostart-'));
+    const before = process.env.XDG_CONFIG_HOME;
+    process.env.XDG_CONFIG_HOME = home;
+    try {
+      expect(isAutostartInstalled({ platform: 'linux' })).toBe(false);
+      const written = installAutostart({
+        platform: 'linux',
+        argv: ['/bun', '/cli.js', 'serve', '--foreground'],
+        port: 3999,
+        logFile: `${home}/data/tray.log`,
+      });
+      expect(written.path).toContain('autostart');
+      expect(isAutostartInstalled({ platform: 'linux' })).toBe(true);
+      const content = await readFile(written.path as string, 'utf8');
+      expect(content).toContain('Exec=/bun /cli.js serve --foreground');
+      expect(uninstallAutostart({ platform: 'linux' })).toBe(true);
+      expect(isAutostartInstalled({ platform: 'linux' })).toBe(false);
+    } finally {
+      if (before === undefined) delete process.env.XDG_CONFIG_HOME;
+      else process.env.XDG_CONFIG_HOME = before;
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('a pre-rename login entry is removed', () => {
+  // It names `src/cli/ompchamber.js`, which this release does not ship: left in
+  // place it fails at every login, and `--no-startup` removes only the current
+  // entry, so nothing else could ever reach it.
+  test('removes the old XDG entry and reports where it was', async () => {
+    // `XDG_CONFIG_HOME`, not HOME: `os.homedir()` is resolved once at process
+    // start on macOS, so changing HOME mid-run would leave the function reading
+    // the developer's real home — and the test writing into it.
+    const home = await mkdtemp(join(tmpdir(), 'kabmo-autostart-legacy-'));
+    const before = process.env.XDG_CONFIG_HOME;
+    process.env.XDG_CONFIG_HOME = home;
+    try {
+      // The expected path is spelled the way the SOURCE spells it, with `/`:
+      // these are Linux XDG paths, and `join()` would hand back `\` on a
+      // Windows runner — the test then failed on the separator rather than on
+      // whether the entry was removed. `installAutostart` writes through the
+      // same builder, so a real Linux host sees `/` either way.
+      const dir = `${home}/autostart`;
+      await mkdir(dir, { recursive: true });
+      const legacy = `${dir}/ompchamber-tray.desktop`;
+      await writeFile(legacy, '[Desktop Entry]\nName=OMPChamber\n');
+
+      expect(removeLegacyAutostart({ platform: 'linux' })).toBe(legacy);
+      expect(existsSync(legacy)).toBe(false);
+      // Idempotent: a second run has nothing to remove.
+      expect(removeLegacyAutostart({ platform: 'linux' })).toBeNull();
+    } finally {
+      if (before === undefined) delete process.env.XDG_CONFIG_HOME;
+      else process.env.XDG_CONFIG_HOME = before;
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('the login entry carries a credential PATH, never the secret', () => {
+  const base = { bun: '/bun', cli: '/pkg/src/cli/kabmo.js', port: 3000, host: '127.0.0.1', tray: true, tls: false, lan: false };
+
+  // A plist is mode 0644 and outlives the run that wrote it, so a password in
+  // its argv is published to every user on the machine — measured: the value
+  // appeared verbatim in the CLI's own `ps` line. The entry therefore names a
+  // FILE (0600, beside auth.json) and the CLI reads it on the way in.
+  test('names the credential file when the registering run had a password', () => {
+    const argv = buildLoginEntryArgv({ ...base, credentialPath: '/data/autostart-credential' });
+    expect(argv).toContain('--ui-password-file');
+    expect(argv[argv.indexOf('--ui-password-file') + 1]).toBe('/data/autostart-credential');
+    // The secret itself must not be representable here at all.
+    expect(argv.some((value) => value === '--ui-password')).toBe(false);
+  });
+
+  test('omits the flag when there is no stored credential', () => {
+    expect(buildLoginEntryArgv(base)).not.toContain('--ui-password-file');
+    expect(buildLoginEntryArgv({ ...base, credentialPath: null })).not.toContain('--ui-password-file');
+  });
+});

package/src/server/lib/updates/apply.ts

@@ -0,0 +1,93 @@
+/**
+ * Applies a requested update. oh-my-pi is updated through the omp binary;
+ * Kabmo through the shared self-update engine, which replaces the running
+ * install in place (bun global install, or git fast-forward + rebuild).
+ *
+ * Neither branch restarts anything: this module only reports what happened.
+ * The caller decides, because the console has to flush the result to the
+ * browser BEFORE the process that is serving it goes away.
+ */
+
+import { updateKabmo } from '@/server/lib/updates/install';
+import { applyOmpUpdate } from '@/server/lib/updates/omp';
+import { withUpdateSlot } from '@/server/lib/updates/single-flight';
+import { recycleStandbyProcesses } from '@/server/lib/omp/session/standby.server';
+import type { InstalledCopy } from '@/server/lib/updates/installed-cli';
+import type { UpdateApplyResult, UpdateTarget } from '@/shared/types/updates';
+
+/** A stage label or a line of command output, as the update produces it. */
+export interface UpdateProgressHooks {
+  onLine?: (chunk: string) => void;
+  onStage?: (label: string) => void;
+}
+
+/**
+ * `updated` is what the caller needs to decide about a restart: an "already up
+ * to date" answer is a success that must not bounce a healthy server.
+ */
+export interface AppliedUpdate {
+  result: UpdateApplyResult;
+  updated: boolean;
+  /**
+   * The copy this run left on disk, when it knows. The restart that follows
+   * launches THIS one — the running process's own directory is the build the
+   * update just replaced, which is how a rename came back as the old product.
+   */
+  installed?: InstalledCopy | null;
+}
+
+/**
+ * Runs one update, and refuses to start while another holds the slot — see
+ * `single-flight.ts` for why the console cannot be the gate. The refusal is
+ * thrown, not returned as a result: it is the caller's decision whether that is
+ * a 409 before the work starts or a failure frame inside it.
+ */
+export async function applyUpdate(target: UpdateTarget, hooks: UpdateProgressHooks = {}): Promise<AppliedUpdate> {
+  return withUpdateSlot(target, async () => {
+    if (target === 'omp') {
+      try {
+        const { output, updated } = await applyOmpUpdate({ onLine: hooks.onLine });
+        // A replaced binary leaves every standby process on the old build, and
+        // nothing else would ever notice: the utility pool answers the provider
+        // and model lists for up to five minutes and a prewarmed session host
+        // waits for the next send. Recycled only when the install actually
+        // moved — an "already up to date" run must not bounce a warm pool.
+        if (updated) await recycleStandbyProcesses();
+        return {
+          result: { success: true, target: 'omp', manual: false, message: updated ? 'oh-my-pi updated' : 'oh-my-pi is already up to date', output },
+          updated,
+        };
+      } catch (err) {
+        return {
+          result: {
+            success: false,
+            target: 'omp',
+            manual: false,
+            message: err instanceof Error ? err.message : 'Failed to update oh-my-pi',
+          },
+          updated: false,
+        };
+      }
+    }
+
+    if (target === 'kabmo') {
+      const result = await updateKabmo({ onLine: hooks.onLine, onStage: hooks.onStage });
+      return {
+        result: {
+          success: result.success,
+          target: 'kabmo',
+          manual: result.manual,
+          message: result.message,
+          output: result.output || undefined,
+        },
+        updated: result.updated,
+        installed: result.installed,
+      };
+    }
+
+    return {
+      result: { success: false, target, manual: true, message: 'Unknown update target' },
+      updated: false,
+    };
+  });
+}

package/src/server/lib/updates/changelog-file.ts

@@ -0,0 +1,122 @@
+/**
+ * The release notes behind the "What's new" popup, read from the repository's
+ * own `CHANGELOG.md`.
+ *
+ * That file IS the release notes: `release.config.mjs` writes each
+ * `## [x.y.z] — YYYY-MM-DD` section from the Conventional Commits of the release
+ * and posts the same prose as the GitHub release body, so reading the file gives
+ * the identical text without asking the Releases API for it — no 60-per-hour
+ * unauthenticated limit, no `GITHUB_TOKEN`, and no dependency on the release
+ * pipeline having created a release object for the tag.
+ *
+ * Sections are parsed by heading, so the popup's range is decided by the versions
+ * the changelog itself names: newest first, each with its date and body. The
+ * heading's own compare link is dropped rather than rendered — the popup draws
+ * the heading itself and links each section to that version's release page.
+ */
+
+import { releaseTagUrl, REPO } from '@/server/lib/updates/release-url';
+import type { ReleaseNote } from '@/shared/types/updates';
+
+/**
+ * The changelog as served, on the branch the releases are cut from.
+ *
+ * The VERSION range comes from npm (see ./npm) — that is the channel an install
+ * moves to. The NOTES come from this file, and each section links to that
+ * version's GitHub release page, which is where the same prose is published for
+ * a reader to follow.
+ */
+export const CHANGELOG_URL = `https://raw.githubusercontent.com/${REPO}/HEAD/CHANGELOG.md`;
+
+/** How long a read is reused. The file changes on release, not on read. */
+const TTL_MS = 60_000;
+
+/** A hung CDN must not hold the popup open. */
+const TIMEOUT_MS = 10_000;
+
+/**
+ * A release heading, in both spellings the file carries:
+ *
+ *     ## [3.14.0](https://…/compare/v3.13.1...v3.14.0) — 2026-10-04
+ *     ## [0.5.0] — 2026-09-21
+ *
+ * The `### Added` subheadings below it do not match, and neither does the
+ * `[0.5.0]: https://…` reference block at the file's tail.
+ */
+const SECTION_HEADING = /^##\s+\[?v?(\d[\w.-]*)\]?(?:\([^)]*\))?\s*(?:[—–-]\s*(\d{4}-\d{2}-\d{2}))?\s*$/;
+
+/** `[0.5.0]: https://…` — the link definitions the changelog ends with. */
+const REFERENCE_DEFINITION = /^\[[^\]]+\]:\s/;
+
+/**
+ * Every release section in the file, newest first (file order). A heading whose
+ * body is empty is kept — a version that shipped without notes is still a
+ * version, and the popup words the empty case.
+ *
+ * The parse STOPS at the trailing reference block: those lines are link
+ * definitions, not notes, and without the guard they rendered as the last
+ * section's body.
+ */
+export function parseChangelogSections(markdown: string): ReleaseNote[] {
+  const notes: ReleaseNote[] = [];
+  let version: string | null = null;
+  let date: string | null = null;
+  let body: string[] = [];
+
+  const flush = () => {
+    if (version === null) return;
+    notes.push({ version, date, url: releaseTagUrl(version), body: body.join('\n').trim() });
+  };
+
+  for (const raw of markdown.split('\n')) {
+    const line = raw.trimEnd();
+    if (REFERENCE_DEFINITION.test(line.trim())) {
+      flush();
+      version = null;
+      body = [];
+      continue;
+    }
+    if (line.startsWith('## ')) {
+      flush();
+      const match = SECTION_HEADING.exec(line.trim());
+      version = match?.[1] ?? null;
+      date = match?.[2] ?? null;
+      body = [];
+      continue;
+    }
+    if (version !== null) body.push(line);
+  }
+  flush();
+
+  return notes;
+}
+
+/** The parsed sections, cached on `globalThis` for the same reason the database is. */
+interface ChangelogCache {
+  notes: ReleaseNote[];
+  at: number;
+}
+
+const cacheSlot = globalThis as typeof globalThis & { __kabmoChangelogCache?: ChangelogCache };
+
+/** Never throws: an unreadable changelog is an empty list, and the caller words it. */
+export async function fetchChangelogNotes(force = false): Promise<ReleaseNote[]> {
+  const cached = cacheSlot.__kabmoChangelogCache;
+  if (!force && cached && Date.now() - cached.at < TTL_MS) return cached.notes;
+
+  let notes: ReleaseNote[] = [];
+  try {
+    const response = await fetch(CHANGELOG_URL, {
+      headers: { 'User-Agent': 'kabmo' },
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (response.ok) notes = parseChangelogSections(await response.text());
+  } catch {
+    // Reported as an empty list; the popup says the notes could not be fetched.
+  }
+
+  // An empty read is not cached: a transient failure would otherwise pin "no
+  // release notes" for a minute and hide a real update.
+  if (notes.length > 0) cacheSlot.__kabmoChangelogCache = { notes, at: Date.now() };
+  return notes;
+}

package/src/server/lib/updates/changelog.test.ts

@@ -0,0 +1,213 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The release range behind the "What's new" popup: the section parser that reads
+ * it out of the repository's `CHANGELOG.md`, and the range/cap math that decides
+ * what a user actually sees.
+ *
+ * The parser is pinned against the real heading spellings — `## [3.14.0](compare)
+ * — 2026-10-04`, the older `## [0.5.0] — 2026-09-21`, a plain `## v3.13.0` — plus
+ * the `[0.5.0]: https://…` reference block the file ends with, which is a link
+ * definition and must not read as the last section's body.
+ *
+ * The range rules are the ones a real repository exercises: a version behind by
+ * one release, by many, a dev build that is not in the list, and a local build
+ * newer than the published one. A release equal to the installed version must NOT
+ * appear (that is the "already current" decision), a release newer than the
+ * published `latest` must not either, and the caps must trim the OLDEST sections
+ * while never emptying the list — "showing 12 of 29" is only honest if the newest
+ * are the ones kept.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+
+import { MAX_NOTES_BYTES, MAX_VERSIONS, capReleaseNotes, selectReleaseRange } from '@/server/lib/updates/changelog';
+import { CHANGELOG_URL, fetchChangelogNotes, parseChangelogSections } from '@/server/lib/updates/changelog-file';
+import { releaseTagUrl } from '@/server/lib/updates/release-url';
+import type { ReleaseNote } from '@/shared/types/updates';
+
+/** The runner's own fetch, reached through `Bun` so a stub leaked onto the global cannot be mistaken for it. */
+const originalFetch = Bun.fetch;
+
+const note = (version: string, body = '', date: string | null = null): ReleaseNote => ({
+  version,
+  date,
+  url: releaseTagUrl(version),
+  body,
+});
+
+/** A changelog fixture shaped like the repository's own file. */
+const CHANGELOG = [
+  '# Changelog',
+  '',
+  'All notable changes to Kabmo are documented in this file.',
+  '',
+  '## [3.14.0](https://github.com/kabmo-labs/kabmo/compare/v3.13.1...v3.14.0) — 2026-10-04',
+  '',
+  '### Added',
+  '',
+  '* **agent:** route a peer-owned session through its instance',
+  '',
+  '### Fixed',
+  '',
+  '* **chat:** stop listing a sent turn twice in the timeline rail',
+  '',
+  '## [3.13.1](https://github.com/kabmo-labs/kabmo/compare/v3.13.0...v3.13.1) — 2026-10-03',
+  '',
+  '### Fixed',
+  '',
+  '* **sidebar:** stop the run spinner and name a new session at send time',
+  '',
+  '## v3.13.0',
+  '',
+  'A heading without a compare link or a date.',
+  '',
+  '[3.14.0]: https://github.com/kabmo-labs/kabmo/compare/v3.13.1...v3.14.0',
+  '[3.13.1]: https://github.com/kabmo-labs/kabmo/compare/v3.13.0...v3.13.1',
+  '',
+].join('\n');
+
+describe('parseChangelogSections', () => {
+  test('reads each release heading with its date and body', () => {
+    const notes = parseChangelogSections(CHANGELOG);
+    expect(notes.map((entry) => entry.version)).toEqual(['3.14.0', '3.13.1', '3.13.0']);
+    expect(notes[0]!.date).toBe('2026-10-04');
+    expect(notes[0]!.body).toBe('### Added\n\n* **agent:** route a peer-owned session through its instance\n\n### Fixed\n\n* **chat:** stop listing a sent turn twice in the timeline rail');
+    expect(notes[0]!.url).toBe('https://github.com/kabmo-labs/kabmo/releases/tag/v3.14.0');
+  });
+
+  test('accepts a plain heading with neither link nor date', () => {
+    const notes = parseChangelogSections(CHANGELOG);
+    expect(notes[2]).toMatchObject({ version: '3.13.0', date: null, body: 'A heading without a compare link or a date.' });
+  });
+
+  test('the tail reference block is not body text', () => {
+    // `[3.14.0]: https://…` is a link definition, not notes; without the guard
+    // it rendered as the last section's body.
+    const notes = parseChangelogSections(CHANGELOG);
+    expect(notes[2]!.body).not.toContain('[3.13.1]:');
+  });
+
+  test('a file with no release sections yields nothing', () => {
+    expect(parseChangelogSections('# Changelog\n\nProse only.\n')).toEqual([]);
+  });
+
+  test('an empty section is kept — a version shipped without notes is still a version', () => {
+    const notes = parseChangelogSections('## [1.0.0] — 2026-01-01\n\n## [0.9.0] — 2025-12-01\n\n* something\n');
+    expect(notes.map((entry) => entry.version)).toEqual(['1.0.0', '0.9.0']);
+    expect(notes[0]!.body).toBe('');
+  });
+});
+
+describe('fetchChangelogNotes', () => {
+  let urls: string[] = [];
+  let body = CHANGELOG;
+  let status = 200;
+
+  beforeEach(() => {
+    delete (globalThis as typeof globalThis & { __kabmoChangelogCache?: unknown }).__kabmoChangelogCache;
+    urls = [];
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      urls.push(String(input));
+      return new Response(body, { status, headers: { 'content-type': 'text/markdown' } });
+    }) as typeof fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    delete (globalThis as typeof globalThis & { __kabmoChangelogCache?: unknown }).__kabmoChangelogCache;
+  });
+
+  test('reads the repository changelog and parses it', async () => {
+    const notes = await fetchChangelogNotes();
+    expect(urls[0]).toBe(CHANGELOG_URL);
+    expect(notes[0]!.version).toBe('3.14.0');
+  });
+
+  test('a repeat read inside the TTL is served from the cache', async () => {
+    await fetchChangelogNotes();
+    await fetchChangelogNotes();
+    expect(urls).toHaveLength(1);
+  });
+
+  test('force bypasses a warm cache', async () => {
+    await fetchChangelogNotes();
+    await fetchChangelogNotes(true);
+    expect(urls).toHaveLength(2);
+  });
+
+  test('a failed read is an empty list, not a throw, and is not cached', async () => {
+    status = 500;
+    expect(await fetchChangelogNotes()).toEqual([]);
+    expect(await fetchChangelogNotes()).toEqual([]);
+    expect(urls).toHaveLength(2);
+  });
+});
+
+describe('selectReleaseRange', () => {
+  const releases = [note('3.14.0'), note('3.13.1'), note('3.13.0'), note('3.12.1'), note('3.12.0')];
+
+  test('with no latest there is nothing to announce', () => {
+    expect(selectReleaseRange([note('1.0.0')], '0.5.0', null)).toEqual([]);
+  });
+
+  test('keeps releases above the installed version and up to latest, newest first', () => {
+    const range = selectReleaseRange(releases, '3.12.1', '3.14.0');
+    expect(range.map((entry) => entry.version)).toEqual(['3.14.0', '3.13.1', '3.13.0']);
+  });
+
+  test('the installed version itself is excluded — the already-current decision', () => {
+    expect(selectReleaseRange([note('3.14.0')], '3.14.0', '3.14.0')).toEqual([]);
+  });
+
+  test('ignores anything newer than the target release', () => {
+    expect(selectReleaseRange([note('3.15.0'), ...releases], '3.12.1', '3.14.0').map((entry) => entry.version)).toEqual([
+      '3.14.0',
+      '3.13.1',
+      '3.13.0',
+    ]);
+  });
+
+  test('with no readable installed version the range is the latest release alone', () => {
+    expect(selectReleaseRange(releases, null, '3.13.1').map((entry) => entry.version)).toEqual(['3.13.1']);
+  });
+
+  test('a pre-release version compares by its numeric core', () => {
+    expect(selectReleaseRange([note('3.15.0-beta.1')], '3.14.0', '3.15.0').map((entry) => entry.version)).toEqual(['3.15.0-beta.1']);
+  });
+
+  test('a blank or non-numeric version is dropped', () => {
+    expect(selectReleaseRange([note(''), note('nightly')], null, '3.14.0')).toEqual([]);
+  });
+});
+
+describe('capReleaseNotes', () => {
+  test('under both caps nothing is trimmed', () => {
+    const notes = [note('2.0.0', 'x'.repeat(10)), note('1.9.0', 'y'.repeat(10))];
+    expect(capReleaseNotes(notes)).toEqual({ versions: notes, truncated: false });
+  });
+
+  test('more than MAX_VERSIONS sections keeps the newest and reports truncation', () => {
+    const notes = Array.from({ length: MAX_VERSIONS + 1 }, (_, i) => note(`1.0.${i}`));
+    const { versions, truncated } = capReleaseNotes(notes);
+    expect(versions).toHaveLength(MAX_VERSIONS);
+    expect(versions[0]).toBe(notes[0]!);
+    expect(truncated).toBe(true);
+  });
+
+  test('the byte budget drops the oldest sections', () => {
+    const notes = [note('3.0.0', 'a'.repeat(60_000)), note('2.0.0', 'b'.repeat(60_000)), note('1.0.0', 'c'.repeat(60_000))];
+    const { versions, truncated } = capReleaseNotes(notes);
+    expect(versions.map((entry) => entry.version)).toEqual(['3.0.0', '2.0.0']);
+    expect(truncated).toBe(true);
+  });
+
+  test('a single oversized section is still kept — the list is never emptied', () => {
+    const { versions, truncated } = capReleaseNotes([note('1.0.0', 'z'.repeat(MAX_NOTES_BYTES + 1))]);
+    expect(versions).toHaveLength(1);
+    expect(truncated).toBe(false);
+  });
+});