@kabmo-labs/kabmo 0.7.0 → 0.8.0

package/src/server/lib/updates/shell-pages.ts

@@ -0,0 +1,145 @@
+/**
+ * The PUBLIC release pages, for when the GitHub API is unavailable.
+ *
+ * Split from `shell-release.ts` because it is a second, independent read: the API
+ * path parses JSON, this one parses an Atom feed and an HTML fragment, and the two
+ * share nothing but the asset-naming rules in `shell-assets`.
+ *
+ * ## Why it exists
+ *
+ * The REST API is unauthenticated at 60 requests an hour **per source IP** — and
+ * on a mobile network that IP is shared with an entire carrier NAT. Measured on
+ * the author's machine: `remaining: 0`, so the probe answered `null` and the
+ * console drew no update button for an APK two versions behind the published one.
+ * A missing button is indistinguishable from "you are up to date", which is why
+ * that failed silently for as long as it did.
+ *
+ * `github.com/<repo>/releases.atom` is a plain Atom feed of published releases
+ * (newest first) and `github.com/<repo>/releases/expanded_assets/<tag>` is the
+ * HTML fragment the release page itself loads. Both are served without an API
+ * budget — verified live: 200 on both, and the fragment carries every asset link.
+ */
+
+import { REPO } from '@/server/lib/updates/release-url';
+import { SHELL_ASSETS, versionFromAssetName } from '@/server/lib/updates/shell-assets';
+import type { ShellKind } from '@/shared/lib/updates/shell-ua';
+
+/** How many tags to walk before giving up. */
+const PAGE_SCAN = 6;
+
+/** A tag from the Atom feed, with the release page it names. */
+export interface ReleaseTag {
+  name: string;
+  url: string | null;
+}
+
+/** One asset found in a release's fragment. */
+export interface PageAsset {
+  name: string;
+  downloadUrl: string;
+}
+
+/**
+ * What the pages read concluded.
+ *
+ * THREE cases, not two, because "the feed could not be read" and "the feed was
+ * read and carries no artifact of this shell" are different facts: the first
+ * keeps the last good answer, the second is a cacheable empty result. Collapsing
+ * them makes a momentary outage look like "no update published", which is the
+ * same silence the API path's `null` exists to avoid.
+ */
+export type PagesResult =
+  | { kind: 'found'; asset: PageAsset; releaseUrl: string | null }
+  | { kind: 'none' }
+  | { kind: 'unreachable' };
+
+/**
+ * The newest tag that carries this shell's artifact.
+ *
+ * The FIRST tag with a matching asset wins, because the feed is newest-first and
+ * a release that carries no artifact of this shell (a `kabmo-sdk/v*` package
+ * release, which the pipeline publishes before the app) must not stop the walk.
+ */
+export async function findAssetInPages(
+  kind: ShellKind,
+  fetchImpl: typeof fetch,
+  headers: Record<string, string>,
+): Promise<PagesResult> {
+  const feed = await fetchImpl(`https://github.com/${REPO}/releases.atom`, {
+    headers: { accept: 'application/atom+xml, text/xml', ...headers },
+  });
+  if (!feed.ok) return { kind: 'unreachable' };
+
+  const tags = releaseTags(await feed.text());
+  if (tags.length === 0) return { kind: 'none' };
+
+  for (const tag of tags.slice(0, PAGE_SCAN)) {
+    const page = await fetchImpl(
+      `https://github.com/${REPO}/releases/expanded_assets/${encodeURIComponent(tag.name)}`,
+      { headers: { accept: 'text/html', ...headers } },
+    );
+    if (!page.ok) continue;
+
+    const asset = shellAssetFromPage(kind, await page.text());
+    if (!asset) continue;
+
+    return { kind: 'found', asset, releaseUrl: tag.url };
+  }
+
+  return { kind: 'none' };
+}
+
+/**
+ * The feed's entries, in the order GitHub lists them (newest first).
+ *
+ * Parsed with two regexes rather than an XML parser: the feed is a fixed shape
+ * GitHub emits, and a dependency for two fields would be the larger risk. The
+ * entity decode covers the one escape that appears in practice.
+ */
+export function releaseTags(xml: string): ReleaseTag[] {
+  const tags: ReleaseTag[] = [];
+  const entries = xml.split('<entry>').slice(1);
+
+  for (const entry of entries) {
+    const title = /<title>([^<]*)<\/title>/.exec(entry)?.[1];
+    if (!title) continue;
+    const href = /<link[^>]*rel="alternate"[^>]*href="([^"]+)"/.exec(entry)?.[1] ?? null;
+    tags.push({ name: decodeEntities(title.trim()), url: href ? decodeEntities(href) : null });
+  }
+
+  return tags;
+}
+
+/**
+ * The asset links inside a release's `expanded_assets` fragment.
+ *
+ * The name is read out of the DOWNLOAD URL rather than the link's text: the
+ * fragment wraps it in a `<span class="text-bold">` whose markup has changed
+ * before, while the URL is the release's own path and carries the same name.
+ *
+ * The CURRENT naming scheme wins over the legacy one, for the reason
+ * `shell-release`'s API path documents: a release carrying both spellings must
+ * not resolve to the older version.
+ */
+export function shellAssetFromPage(kind: ShellKind, html: string): PageAsset | null {
+  const found: PageAsset[] = [];
+  const pattern = /href="(\/[^"]+\/releases\/download\/[^"]+)"/g;
+
+  for (const match of html.matchAll(pattern)) {
+    const path = decodeEntities(match[1] ?? '');
+    const name = decodeURIComponent(path.slice(path.lastIndexOf('/') + 1));
+    if (versionFromAssetName(kind, name) !== null) found.push({ name, downloadUrl: `https://github.com${path}` });
+  }
+
+  return found.find((asset) => SHELL_ASSETS[kind].current.test(asset.name)) ?? found[0] ?? null;
+}
+
+/** The entities that appear in a feed title or a link. */
+function decodeEntities(text: string): string {
+  return text
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, '&');
+}

package/src/server/lib/updates/shell-release.test.ts

@@ -5,75 +5,16 @@
 
 import { beforeEach, describe, expect, test } from 'bun:test';
 
-import { fetchShellRelease, resetShellReleaseCache, versionFromAssetName } from '@/server/lib/updates/shell-release';
+import { fetchShellRelease, resetShellReleaseCache } from '@/server/lib/updates/shell-release';
 
 /**
- * The asset name is the only place a shell artifact's version exists: the
- * release TAG names the SERVER version, and the two move independently. A parser
- * that read the tag would compare a server version against a shell version.
+ * A fetch double that answers one body, and counts its calls.
  *
- * Both shells are pinned here, because they share the parser and differ only by
- * prefix/extension — the shape that silently accepts the other shell's asset.
+ * `text()` is provided as well as `json()`: the public-pages fallback reads Atom
+ * and HTML, and a stub that only answered `json()` would throw inside it and make
+ * a broken parse look like a clean "no release" — the exact confusion these
+ * tests exist to prevent.
  */
-describe('versionFromAssetName', () => {
-  test('reads the version the release workflows write', () => {
-    expect(versionFromAssetName('android', 'Kabmo-0.5.0-android.apk')).toBe('0.5.0');
-    expect(versionFromAssetName('ios', 'Kabmo-0.1.0-ios.ipa')).toBe('0.1.0');
-  });
-
-  /**
-   * The old spelling is still READ, and that is not sentiment.
-   *
-   * These names are the only record of a published shell, and every release
-   * already on GitHub carries `kabmo-android-v<v>.apk`. A parser that only knew
-   * the new scheme would answer "no update" for an installed shell the moment
-   * this shipped — silently, because a name that does not match reads exactly
-   * like a release with no artifact.
-   */
-  test('still reads the legacy spelling every published release carries', () => {
-    expect(versionFromAssetName('android', 'kabmo-android-v0.5.0.apk')).toBe('0.5.0');
-    expect(versionFromAssetName('ios', 'kabmo-ios-v0.1.0.ipa')).toBe('0.1.0');
-  });
-
-  test('ignores anything that is not that shell’s artifact', () => {
-    expect(versionFromAssetName('android', 'Kabmo-1.2.3-android.apk.zip')).toBeNull();
-    expect(versionFromAssetName('android', 'source.tar.gz')).toBeNull();
-    expect(versionFromAssetName('android', 'Kabmo-latest-android.apk')).toBeNull();
-    expect(versionFromAssetName('android', 'Kabmo--android.apk')).toBeNull();
-    expect(versionFromAssetName('android', '')).toBeNull();
-  });
-
-  /**
-   * The desktop assets share the `Kabmo-` prefix, so the EXTENSION is what keeps
-   * them out. A probe that matched on the prefix alone would offer a Mac `.dmg`
-   * to an Android phone.
-   */
-  test('does not read a desktop asset as a mobile one', () => {
-    for (const name of [
-      'Kabmo-0.1.2-mac-arm64.zip',
-      'Kabmo-0.1.2-mac-arm64.dmg',
-      'Kabmo-0.1.0-win-x64-setup.exe',
-      'Kabmo-0.1.0-linux-x86_64.tar.gz',
-      'Kabmo-0.1.0-linux-amd64.deb',
-      'Kabmo-0.1.0-linux-x86_64.AppImage',
-    ]) {
-      expect(versionFromAssetName('android', name), name).toBeNull();
-      expect(versionFromAssetName('ios', name), name).toBeNull();
-    }
-  });
-
-  test('does not accept one shell’s asset for the other', () => {
-    // The two probes read the SAME release list, so a parser that ignored the
-    // kind would let an iOS probe answer with the APK (and offer an `.apk` to an
-    // iPhone).
-    expect(versionFromAssetName('ios', 'Kabmo-0.5.0-android.apk')).toBeNull();
-    expect(versionFromAssetName('android', 'Kabmo-0.1.0-ios.ipa')).toBeNull();
-    expect(versionFromAssetName('ios', 'kabmo-android-v1.2.3.apk')).toBeNull();
-    expect(versionFromAssetName('android', 'kabmo-ios-v1.2.3.ipa')).toBeNull();
-  });
-});
-
-/** A fetch double that answers one body, and counts its calls. */
 function stubFetch(body: unknown, ok = true) {
   const calls: string[] = [];
   const impl = (async (input: string | URL | Request) => {
@@ -81,11 +22,45 @@ function stubFetch(body: unknown, ok = true) {
     return {
       ok,
       json: async () => body,
+      text: async () => (typeof body === 'string' ? body : JSON.stringify(body)),
     } as Response;
   }) as unknown as typeof fetch;
   return { impl, calls };
 }
 
+/**
+ * A double that routes by URL, for the two-path probe.
+ *
+ * `api` answers the REST read (or fails, which is what a spent quota does) and
+ * `pages` answers the Atom feed and each release's asset fragment. Returning
+ * `null` for a route means "this request fails", which is how the fallback is
+ * entered at all.
+ */
+function routedFetch(routes: {
+  api?: unknown;
+  atom?: string;
+  assets?: Record<string, string>;
+}) {
+  const calls: string[] = [];
+  const impl = (async (input: string | URL | Request) => {
+    const url = String(input);
+    calls.push(url);
+
+    if (url.includes('/repos/')) {
+      if (routes.api === undefined) return { ok: false, json: async () => ({}), text: async () => '' } as Response;
+      return { ok: true, json: async () => routes.api, text: async () => JSON.stringify(routes.api) } as Response;
+    }
+    if (url.endsWith('/releases.atom')) {
+      const body = routes.atom ?? '';
+      return { ok: Boolean(routes.atom), json: async () => ({}), text: async () => body } as Response;
+    }
+    const tag = url.slice(url.lastIndexOf('/') + 1);
+    const body = routes.assets?.[decodeURIComponent(tag)];
+    return { ok: body !== undefined, json: async () => ({}), text: async () => body ?? '' } as Response;
+  }) as unknown as typeof fetch;
+  return { impl, calls };
+}
+
 describe('fetchShellRelease', () => {
   // The cache is process-wide (see `resetShellReleaseCache`), so every case
   // starts from a cold one or it reads the previous case's answer.
@@ -241,15 +216,45 @@ describe('fetchShellRelease', () => {
   });
 
   test('answers null when the probe fails', async () => {
-    // An offline box or a rate-limited GitHub must not take the sidebar down,
-    // and a failure must not be read as "no newer version" either — it is
-    // simply no offer.
-    const { impl } = stubFetch({}, false);
+    // An offline box must not take the sidebar down, and a failure must not be
+    // read as "no newer version" either — it is simply no offer. BOTH paths are
+    // down here: the API refuses and the feed is unreachable, which is the only
+    // shape that means "cannot ask" rather than "nothing published".
+    const { impl } = routedFetch({});
     expect(await fetchShellRelease('android', impl)).toBeNull();
   });
 
   test('answers null when the body is malformed', async () => {
-    const { impl } = stubFetch({ assets: 'nope' });
+    // The API answers 200 with something that is not a release list, and the
+    // feed is unreachable — the API's answer is a failed probe, not an empty
+    // repository.
+    const { impl } = routedFetch({ api: { assets: 'nope' } });
     expect(await fetchShellRelease('android', impl)).toBeNull();
   });
+
+  /**
+   * The desktop trio reads the same release list and answers the RELEASE PAGE.
+   *
+   * Every desktop artifact is per-architecture, and this server cannot know which
+   * architecture the window asking is running on — it may be a remote console on
+   * another machine. Naming one arch's file would hand half the readers a build
+   * that will not launch, so the link is the page that lists all of them.
+   */
+  test('a desktop probe answers the release page, never one architecture', async () => {
+    const { impl } = stubFetch([
+      {
+        html_url: 'https://x/app',
+        assets: [
+          { name: 'Kabmo-0.2.0-mac-arm64.zip', browser_download_url: 'https://x/mac-arm.zip' },
+          { name: 'Kabmo-0.2.0-mac-x64.dmg', browser_download_url: 'https://x/mac-x64.dmg' },
+        ],
+      },
+    ]);
+
+    expect(await fetchShellRelease('macos', impl)).toEqual({
+      url: 'https://x/app',
+      latest: '0.2.0',
+      releaseUrl: 'https://x/app',
+    });
+  });
 });

package/src/server/lib/updates/shell-release.ts

@@ -2,128 +2,68 @@
  * Which published native-shell artifact a browser or an installed shell should
  * download, and whether the installed one is behind.
  *
- * Neither shell is an npm package (see `.github/workflows/publish-android.yml`
- * and `publish-ios.yml`), so the npm probe that answers for the app and for
- * `omp` cannot answer here. The only record of a published shell is a GitHub
- * release asset, which means one unauthenticated REST read of the release LIST —
- * not `/releases/latest`, which answers the newest release of ANY kind (see
- * `fetchShellRelease`).
+ * No shell is an npm package (see `.github/workflows/publish-{android,ios,macos,
+ * windows,linux}.yml`), so the npm probe that answers for the app and for `omp`
+ * cannot answer here. The only record of a published shell is a GitHub release
+ * asset.
  *
- * ONE module for both shells, because the question is identical and only the
- * asset naming differs. Two copies is how one of them starts reading the release
- * tag, or caching under a slot the other overwrites.
+ * ## Two reads, because one of them has a quota
  *
- * Two facts travel back, and they answer different questions:
+ * The REST API is the precise read and the FIRST one tried. It is also
+ * unauthenticated at 60 requests an hour **per source IP**, and a phone on mobile
+ * data shares that IP with an entire carrier NAT — so `shell-pages` is the second
+ * path, and it is why the button appears at all on a bad day. See that module's
+ * own comment for the measured failure.
  *
- * - `url` is the asset to download. It is resolved from the release's OWN asset
- *   list rather than built as `releases/latest/download/<name>`, because that
- *   path needs the asset name to match exactly and the name carries the shell's
- *   version (`Kabmo-0.5.0-android.apk`) — a name built here would be a second
- *   copy of the workflow's naming rule, and the first release that renames it
- *   404s.
- * - `latest` is the version that asset ships, read from the asset name. The
- *   release TAG cannot be used: the artifact is attached to the app's release,
- *   whose tag names the SERVER version, and the two move independently.
+ * ## What travels back
  *
- * Failure is a normal answer here (`null`), never a throw: an offline box or a
- * rate-limited GitHub must not take the sidebar down, and a button that appears
- * because a probe failed would offer a download that does not exist.
+ * - `url` is what to download. For the mobile pair it is the artifact itself (an
+ *   APK the shell installs, an IPA the release page explains). For the DESKTOP
+ *   trio it is the RELEASE PAGE, deliberately: every desktop artifact is
+ *   per-architecture (`Kabmo-0.2.0-mac-arm64.zip`), and this server cannot know
+ *   which architecture the window asking is running on — it may be a remote
+ *   console on another machine entirely. Naming one arch's file would hand half
+ *   the readers a build that will not launch.
+ * - `latest` is the version that asset ships, read from the asset NAME (see
+ *   `shell-assets`). The release TAG cannot be used: the artifact is attached to
+ *   the app's release, whose tag names the SERVER version.
+ *
+ * Failure is a normal answer here (`null`), never a throw: an offline box must
+ * not take the sidebar down, and a button that appears because a probe failed
+ * would offer a download that does not exist.
  */
 
 import { REPO } from '@/server/lib/updates/release-url';
+import { SHELL_ASSETS, versionFromAssetName } from '@/server/lib/updates/shell-assets';
+import { findAssetInPages } from '@/server/lib/updates/shell-pages';
 import type { ShellKind } from '@/shared/lib/updates/shell-ua';
 
 /** One published shell artifact, as the console needs it. */
 export interface ShellRelease {
-  /** Asset download URL, or null when the release carries no artifact. */
+  /** Asset download URL, or the release page for a per-arch desktop build. */
   url: string | null;
-  /** Version the asset name declares (`v1.2.3` → `1.2.3`), or null. */
+  /** Version the asset name declares (`Kabmo-1.2.3-android.apk` → `1.2.3`). */
   latest: string | null;
   /** The release page, for a "what changed" link. */
   releaseUrl: string | null;
 }
 
-/**
- * How each shell's asset is named by its publish workflow, plus the prefix it
- * carried BEFORE the rename.
- *
- * ONE scheme for every shell in the project — `<App>-<version>-<platform>.<ext>`:
- * `Kabmo-0.5.0-android.apk`, `Kabmo-0.1.0-ios.ipa`, and the desktop trio's
- * `Kabmo-0.1.2-mac-arm64.dmg` / `-win-x64-setup.exe` / `-linux-x86_64.tar.gz`.
- * The mobile pair carries no architecture because neither artifact is per-arch:
- * the APK is one universal build (the shell is pure Kotlin with no native
- * libraries, so there is nothing to split), and the IPA contains only the device
- * slice (`arm64-apple-ios`). A `-arm64` in those names would claim a distinction
- * that does not exist and would make the parser look for a second artifact.
- *
- * **`legacyPrefix` is not dead code.** These names are PARSED to answer "is a
- * newer shell published", and every release already on GitHub carries the old
- * spelling. Dropping it would make the console answer "no update" for an
- * installed shell the moment this ships — silently, because a name that does not
- * match reads exactly like a release with no artifact. The probe tries the
- * current prefix first, then the old one; new releases only ever write the
- * current one.
- */
-export const SHELL_ASSETS: Record<
-  ShellKind,
-  { prefix: string; extension: string; legacyPrefix: string; legacyExtension: string }
-> = {
-  android: {
-    prefix: 'Kabmo-',
-    extension: '-android.apk',
-    legacyPrefix: 'kabmo-android-v',
-    legacyExtension: '.apk',
-  },
-  ios: { prefix: 'Kabmo-', extension: '-ios.ipa', legacyPrefix: 'kabmo-ios-v', legacyExtension: '.ipa' },
-};
-
-/**
- * `Kabmo-0.5.0-android.apk` → `0.5.0` (and the `.ipa` twin), plus the legacy
- * `kabmo-android-v0.5.0.apk` spelling every published release still carries.
- *
- * The version is the MIDDLE of the name in the current scheme and the TAIL of the
- * legacy one, so the two are parsed by different rules rather than by one that
- * tries to cover both.
- */
-export function versionFromAssetName(kind: ShellKind, name: string): string | null {
-  const { prefix, extension, legacyPrefix, legacyExtension } = SHELL_ASSETS[kind];
-
-  // Current: `<prefix><version><extension>`, where the prefix is the app's name
-  // and the extension names the platform.
-  if (name.startsWith(prefix) && name.endsWith(extension)) {
-    const middle = name.slice(prefix.length, -extension.length);
-    if (/^\d+\.\d+\.\d+$/.test(middle)) return middle;
-  }
-
-  // Legacy: `kabmo-android-v<version>.apk`. Kept for the releases already
-  // published; no new release writes it.
-  if (name.startsWith(legacyPrefix) && name.endsWith(legacyExtension)) {
-    const middle = name.slice(legacyPrefix.length, -legacyExtension.length);
-    const version = middle.startsWith('v') ? middle.slice(1) : middle;
-    return /^\d+\.\d+\.\d+$/.test(version) ? version : null;
-  }
-
-  return null;
-}
-
 /**
  * The newest release that actually carries this shell's artifact.
  *
  * NOT `/releases/latest`, which answers the newest release of ANY kind. This
- * repository publishes three artifacts from one push, and the packages are
- * released FIRST (`packages → marketplace → android → apk-build → app` in
+ * repository publishes several artifacts from one push, and the packages are
+ * released FIRST (`packages → marketplace → android → … → app` in
  * `release.yml`), so their `kabmo-sdk/v*` / `kabmo-ui/v*` releases are newer
- * than the app release that carries the shell. `@semantic-release/github` runs
+ * than the app release that carries the shells. `@semantic-release/github` runs
  * in both pipelines, so those are real releases — measured against a stub that
  * answered a package release: `/releases/latest` produced
  * `{url: null, latest: null}` and the sidebar's button disappeared even though
  * the APK sat on the release directly below.
  *
- * One request per shell, cached for five minutes on `globalThis` for the same
- * reason the database handle is anchored there: `bun --hot` re-evaluates this
- * module while the cache it would otherwise hold lives on. GitHub allows 60
- * unauthenticated reads an hour per address, and the sidebar asks on every
- * mount.
+ * Cached for five minutes on `globalThis` for the same reason the database
+ * handle is anchored there: `bun --hot` re-evaluates this module while the cache
+ * it would otherwise hold lives on.
  */
 export async function fetchShellRelease(
   kind: ShellKind,
@@ -133,25 +73,44 @@ export async function fetchShellRelease(
   const now = Date.now();
   if (cache.entry && now - cache.at < CACHE_MS) return cache.entry;
 
+  const headers = gitHubHeaders();
+  const resolved =
+    (await readFromApi(kind, fetchImpl, headers)) ?? (await readFromPages(kind, fetchImpl, headers));
+  if (!resolved) return cache.entry ?? null;
+
+  cache.entry = resolved;
+  cache.at = now;
+  return resolved;
+}
+
+/** How many releases to look back through for the artifact. */
+const RELEASE_SCAN = 20;
+
+/**
+ * The REST read, or null when it did not answer with a usable release list.
+ *
+ * A non-2xx is not an error to report — it is the quota, and the caller has a
+ * second path.
+ */
+async function readFromApi(
+  kind: ShellKind,
+  fetchImpl: typeof fetch,
+  headers: Record<string, string>,
+): Promise<ShellRelease | null> {
   try {
     const response = await fetchImpl(`${githubApiBase()}/repos/${REPO}/releases?per_page=${RELEASE_SCAN}`, {
-      headers: {
-        accept: 'application/vnd.github+json',
-        // GitHub rejects a request with no User-Agent.
-        'user-agent': 'kabmo-console',
-      },
+      headers: { accept: 'application/vnd.github+json', ...headers },
     });
-    if (!response.ok) return cache.entry ?? null;
+    if (!response.ok) return null;
 
     const body = (await response.json()) as unknown;
     // A body that is not the release list is a failed probe, not an empty
     // repository: answering `{url: null, latest: null}` here would be
-    // indistinguishable from "no release carries an artifact", and the caller
-    // would cache that mistake for five minutes.
-    if (!Array.isArray(body)) return cache.entry ?? null;
+    // indistinguishable from "no release carries an artifact".
+    if (!Array.isArray(body)) return null;
 
     // Drafts are not published and prereleases are not what a console offers an
-    // installed shell — the same two the `latest` endpoint excluded.
+    // installed shell.
     const published = body.filter(
       (entry): entry is Record<string, unknown> =>
         entry !== null && typeof entry === 'object' && entry.draft !== true && entry.prerelease !== true,
@@ -161,31 +120,34 @@ export async function fetchShellRelease(
       .map((entry) => ({ entry, asset: shellAsset(kind, entry.assets) }))
       .find((candidate) => candidate.asset !== null);
 
-    if (!release?.asset) {
-      const fallback: ShellRelease = { url: null, latest: null, releaseUrl: null };
-      cache.entry = fallback;
-      cache.at = now;
-      return fallback;
-    }
+    if (!release?.asset) return { url: null, latest: null, releaseUrl: null };
 
-    const resolved: ShellRelease = {
-      url: typeof release.asset.browser_download_url === 'string' ? release.asset.browser_download_url : null,
-      latest: versionFromAssetName(kind, String(release.asset.name)),
+    return resolvedRelease(kind, {
+      name: String(release.asset.name),
+      downloadUrl:
+        typeof release.asset.browser_download_url === 'string' ? release.asset.browser_download_url : null,
       releaseUrl: typeof release.entry.html_url === 'string' ? release.entry.html_url : null,
-    };
-
-    cache.entry = resolved;
-    cache.at = now;
-    return resolved;
+    });
   } catch {
-    // Keep the last good answer rather than replacing it with a failure: a
-    // momentary outage must not remove a download button that was valid.
-    return cache.entry ?? null;
+    return null;
   }
 }
 
-/** How many releases to look back through for the artifact. */
-const RELEASE_SCAN = 20;
+/** The public-pages read, wrapped so a failure is the caller's `null`. */
+async function readFromPages(
+  kind: ShellKind,
+  fetchImpl: typeof fetch,
+  headers: Record<string, string>,
+): Promise<ShellRelease | null> {
+  try {
+    const found = await findAssetInPages(kind, fetchImpl, headers);
+    if (found.kind === 'unreachable') return null;
+    if (found.kind === 'none') return { url: null, latest: null, releaseUrl: null };
+    return resolvedRelease(kind, { ...found.asset, releaseUrl: found.releaseUrl });
+  } catch {
+    return null;
+  }
+}
 
 /**
  * The asset of a release that names this shell's artifact, or null.
@@ -198,9 +160,6 @@ const RELEASE_SCAN = 20;
  * `kabmo-android-v0.4.0.apk` and `Kabmo-0.6.0-android.apk` answered `0.4.0`,
  * i.e. the console offered an update to a version it already had and hid the
  * newer one.
- *
- * Both schemes are still ACCEPTED (a release with only the old spelling must
- * keep working), so the preference is a second pass rather than a filter.
  */
 function shellAsset(kind: ShellKind, assets: unknown): Record<string, unknown> | null {
   if (!Array.isArray(assets)) return null;
@@ -213,15 +172,21 @@ function shellAsset(kind: ShellKind, assets: unknown): Record<string, unknown> |
       versionFromAssetName(kind, String((entry as Record<string, unknown>).name)) !== null,
   );
 
-  const { prefix, extension } = SHELL_ASSETS[kind];
-  return (
-    named.find((asset) => {
-      const name = String(asset.name);
-      return name.startsWith(prefix) && name.endsWith(extension);
-    }) ??
-    named[0] ??
-    null
-  );
+  return named.find((asset) => SHELL_ASSETS[kind].current.test(String(asset.name))) ?? named[0] ?? null;
+}
+
+/** Turn one resolved asset into the payload, applying the per-kind link rule. */
+function resolvedRelease(
+  kind: ShellKind,
+  asset: { name: string; downloadUrl: string | null; releaseUrl: string | null },
+): ShellRelease {
+  return {
+    // A per-arch desktop build cannot be named from here — see the module
+    // comment — so the link is the page that lists every architecture.
+    url: SHELL_ASSETS[kind].directDownload ? asset.downloadUrl : asset.releaseUrl,
+    latest: versionFromAssetName(kind, asset.name),
+    releaseUrl: asset.releaseUrl,
+  };
 }
 
 const CACHE_MS = 5 * 60_000;
@@ -239,6 +204,25 @@ function githubApiBase(): string {
   return configured.trim().replace(/\/+$/, '') || 'https://api.github.com';
 }
 
+/**
+ * A token, when the operator has one, which lifts the API quota from 60 an hour
+ * to 5000 — the difference between the precise read working on a shared address
+ * and falling through to the pages every time.
+ *
+ * Read from the environment rather than a setting: it is a deployment fact, it
+ * must never reach the browser, and `kabmo serve` already passes its own
+ * environment through.
+ */
+function gitHubHeaders(): Record<string, string> {
+  const token = (Bun.env.KABMO_GITHUB_TOKEN ?? Bun.env.GITHUB_TOKEN ?? '').trim();
+  const headers: Record<string, string> = {
+    // GitHub rejects a request with no User-Agent.
+    'user-agent': 'kabmo-console',
+  };
+  if (token) headers.authorization = `Bearer ${token}`;
+  return headers;
+}
+
 interface CacheSlot {
   entry: ShellRelease | null;
   at: number;