@kabmo-labs/kabmo 0.7.0 → 0.9.0

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

@@ -0,0 +1,200 @@
+/**
+ * How each native shell's release asset is NAMED, and what version it declares.
+ *
+ * Split from `shell-release.ts` because that file owns the two READS (the REST
+ * API and the public-pages fallback) and this one owns the naming rules, and
+ * because the repo's ceiling is 350 lines per file — the two concerns together
+ * crossed it.
+ *
+ * The naming is the load-bearing half: 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, so a parser that read the tag would compare a server
+ * version against a shell version.
+ */
+
+import type { ShellArch } from '@/shared/lib/updates/shell-arch';
+import type { ShellKind } from '@/shared/lib/updates/shell-ua';
+
+/**
+ * One shell's asset scheme, plus the spelling it carried BEFORE the rename.
+ *
+ * ONE scheme for every shell in the project — `<App>-<version>-<platform>…`:
+ * `Kabmo-0.5.0-android.apk`, `Kabmo-0.1.0-ios.ipa`, and the desktop trio's
+ * `Kabmo-0.2.0-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`).
+ *
+ * The desktop entries match on the segment AFTER the version rather than on the
+ * whole name, because one release carries several files per platform
+ * (`-mac-arm64.zip` and `-mac-arm64.dmg`, four Linux formats, two arches). Any
+ * one of them answers the same version, which is all `pattern` is for.
+ *
+ * WHICH file the console hands back is a second question, and `selfUpdate` is
+ * the answer: a desktop shell that knows its architecture installs one exact
+ * artifact, and a probe that does not know it still gets the release page. Both
+ * live in this table so the route, the pages fallback and the tests read one
+ * spelling.
+ *
+ * **`legacy` is not dead code.** These names are PARSED to answer "is a newer
+ * shell published", and every release already on GitHub carries the old mobile
+ * 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 desktop trio has no
+ * legacy spelling: they were born under the current scheme.
+ */
+export interface AssetScheme {
+  /** The whole-name pattern for the mobile pair, the segment for the desktops. */
+  pattern: RegExp;
+  /** The prefix that marks the CURRENT scheme, for "prefer the new spelling". */
+  current: RegExp;
+  /** The old mobile spelling, or null for a shell that never had one. */
+  legacy: { prefix: string; extension: string } | null;
+  /**
+   * Whether the payload's `url` should be the artifact itself. True for the
+   * mobile pair, whose artifact is the same file on every device.
+   */
+  directDownload: boolean;
+  /**
+   * The ONE file a desktop shell installs ITSELF from, per architecture.
+   *
+   * `null` for the mobile pair: an APK is installed by `PackageInstaller` and an
+   * IPA cannot be installed at all, so neither is this shell's own business.
+   *
+   * The desktop entry is deliberately narrower than `pattern`: one release
+   * carries several files per platform (`.zip` and `.dmg`, `.tar.gz`/`.deb`/
+   * `.rpm`/`.AppImage`), and only ONE of each is something the shell can install
+   * without a human opening it. The choice is stated here rather than at the
+   * call site so the route, the pages fallback and the tests cannot disagree
+   * about which file "the update" means.
+   */
+  selfUpdate: SelfUpdateScheme | null;
+}
+
+/**
+ * How one desktop shell's self-update artifact is named.
+ *
+ * `pattern` captures the version AND the architecture, because the two answers
+ * come from the same string: the version is what the console compares against
+ * the installed build, and the architecture is what makes this file the right
+ * one for the machine asking.
+ */
+export interface SelfUpdateScheme {
+  /** `Kabmo-<version>-<platform>-<arch><suffix>` → `[name, version, arch]`. */
+  pattern: RegExp;
+  /** How each canonical arch is spelled in the ASSET name. */
+  assetArch: Record<ShellArch, string>;
+}
+
+const VERSION = String.raw`(\d+\.\d+\.\d+)`;
+
+/** `arm64`/`x64` as macOS and Windows spell them. */
+const SAME_ARCH: Record<ShellArch, string> = { arm64: 'arm64', x64: 'x64' };
+
+/** Linux says `x86_64` where the other two say `x64`. */
+const LINUX_ARCH: Record<ShellArch, string> = { arm64: 'arm64', x64: 'x86_64' };
+
+export const SHELL_ASSETS: Record<ShellKind, AssetScheme> = {
+  android: {
+    pattern: new RegExp(`^Kabmo-${VERSION}-android\\.apk$`),
+    current: /^Kabmo-\d/,
+    legacy: { prefix: 'kabmo-android-v', extension: '.apk' },
+    directDownload: true,
+    selfUpdate: null,
+  },
+  ios: {
+    pattern: new RegExp(`^Kabmo-${VERSION}-ios\\.ipa$`),
+    current: /^Kabmo-\d/,
+    legacy: { prefix: 'kabmo-ios-v', extension: '.ipa' },
+    directDownload: true,
+    selfUpdate: null,
+  },
+  macos: {
+    pattern: new RegExp(`^Kabmo-${VERSION}-mac-`),
+    current: /^Kabmo-\d/,
+    legacy: null,
+    directDownload: false,
+    // The `.zip`, not the `.dmg`: `ditto -x -k` extracts it without mounting a
+    // volume, and the shell has to be able to do that with no human present.
+    // Both shapes are published; only one is installable by the app itself.
+    selfUpdate: {
+      pattern: new RegExp(`^Kabmo-${VERSION}-mac-(arm64|x64)\\.zip$`),
+      assetArch: SAME_ARCH,
+    },
+  },
+  windows: {
+    pattern: new RegExp(`^Kabmo-${VERSION}-win-`),
+    current: /^Kabmo-\d/,
+    legacy: null,
+    directDownload: false,
+    // The INSTALLER, not the `.zip`-shaped publish output: Inno already owns the
+    // upgrade semantics (a stable `AppId` is what makes an install an upgrade
+    // rather than a second copy), and `/CLOSEAPPLICATIONS` is how it replaces a
+    // running exe.
+    selfUpdate: {
+      pattern: new RegExp(`^Kabmo-${VERSION}-win-(arm64|x64)-setup\\.exe$`),
+      assetArch: SAME_ARCH,
+    },
+  },
+  linux: {
+    pattern: new RegExp(`^Kabmo-${VERSION}-linux-`),
+    current: /^Kabmo-\d/,
+    legacy: null,
+    directDownload: false,
+    // The AppImage, and only it: `.deb`/`.rpm` need root and a package manager,
+    // so a shell cannot install them — it says so instead. An AppImage is ONE
+    // file the shell can replace atomically and re-exec.
+    selfUpdate: {
+      pattern: new RegExp(`^Kabmo-${VERSION}-linux-(arm64|x86_64)\\.AppImage$`),
+      assetArch: LINUX_ARCH,
+    },
+  },
+};
+
+/**
+ * The self-update artifact for one architecture, if this name is it.
+ *
+ * Null for a shell that has no self-update, for an arch it does not publish, and
+ * for every other file in the release (a `.dmg`, a `.deb`, the OTHER
+ * architecture's build). Callers treat null as "not the file this machine
+ * installs", which is why the route falls back to the release page rather than
+ * guessing.
+ */
+export function selfUpdateArtifact(
+  kind: ShellKind,
+  arch: ShellArch,
+  name: string,
+): { version: string } | null {
+  const scheme = SHELL_ASSETS[kind].selfUpdate;
+  if (!scheme) return null;
+
+  const match = scheme.pattern.exec(name);
+  if (!match) return null;
+  // The captured arch is compared against the ASSET spelling, so a Linux build
+  // reporting `x64` matches `…-linux-x86_64.AppImage` and nothing else.
+  if (match[2] !== scheme.assetArch[arch]) return null;
+  return { version: match[1] ?? '' };
+}
+
+/**
+ * `Kabmo-0.5.0-android.apk` → `0.5.0`, the `.ipa` twin, every desktop spelling,
+ * plus the legacy `kabmo-android-v0.5.0.apk` the older releases still carry.
+ */
+export function versionFromAssetName(kind: ShellKind, name: string): string | null {
+  const scheme = SHELL_ASSETS[kind];
+
+  const current = scheme.pattern.exec(name);
+  if (current) return current[1] ?? null;
+
+  // Legacy: `kabmo-android-v<version>.apk`. Kept for the releases already
+  // published; no new release writes it.
+  const legacy = scheme.legacy;
+  if (legacy && name.startsWith(legacy.prefix) && name.endsWith(legacy.extension)) {
+    const middle = name.slice(legacy.prefix.length, -legacy.extension.length);
+    const version = middle.startsWith('v') ? middle.slice(1) : middle;
+    return /^\d+\.\d+\.\d+$/.test(version) ? version : null;
+  }
+
+  return null;
+}

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

@@ -0,0 +1,105 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The shell-release answer cache, and where the GitHub reads go.
+ *
+ * Split from `shell-release.ts` for two reasons that are not cosmetic.
+ *
+ * 1. **The key is per SHELL AND per ARCHITECTURE.** A desktop shell asks for the
+ *    artifact of its own machine, so a single per-kind slot would answer an
+ *    arm64 window with the x64 installer the moment both hit one console — and
+ *    the console is routinely shared by a whole team.
+ * 2. **The cache outlives a test file.** It lives on `globalThis` so `bun --hot`
+ *    cannot orphan it, which is also why `resetShellReleaseCache` exists: without
+ *    that seam the second case in a suite reads the first case's answer and
+ *    passes for the wrong reason (measured — the "malformed body" case returned
+ *    the previous test's release).
+ */
+
+import type { ShellArch } from '@/shared/lib/updates/shell-arch';
+import type { ShellKind } from '@/shared/lib/updates/shell-ua';
+
+/** How long an answer is reused. */
+export const CACHE_MS = 5 * 60_000;
+
+/** One shell's (and, for a desktop, one architecture's) cached answer. */
+export interface CacheSlot<T> {
+  entry: T | null;
+  at: number;
+}
+
+type ShellCacheHost = typeof globalThis & {
+  __kabmoShellRelease?: Record<string, CacheSlot<unknown>>;
+};
+
+/**
+ * The cache key for one question.
+ *
+ * The arch is part of the KEY rather than a field on the value, so a stale entry
+ * can never be read by the wrong machine: a miss is a miss, and there is no
+ * comparison left to get wrong.
+ */
+export function shellCacheKey(kind: ShellKind, arch: ShellArch | null): string {
+  return arch ? `${kind}:${arch}` : kind;
+}
+
+/** The cache slot for one key, created on first use. */
+export function cacheSlot<T>(key: string): CacheSlot<T> {
+  const host = globalThis as ShellCacheHost;
+  host.__kabmoShellRelease ??= {};
+  host.__kabmoShellRelease[key] ??= { entry: null, at: 0 };
+  return host.__kabmoShellRelease[key] as CacheSlot<T>;
+}
+
+/**
+ * Drop the cached answer for one shell (or every shell, with no argument).
+ *
+ * Production has no caller; it is the test seam described above.
+ */
+export function resetShellReleaseCache(kind?: ShellKind): void {
+  const host = globalThis as ShellCacheHost;
+  if (!kind) {
+    host.__kabmoShellRelease = {};
+    return;
+  }
+  const prefix = `${kind}:`;
+  const slots = host.__kabmoShellRelease ?? {};
+  for (const key of Object.keys(slots)) {
+    if (key === kind || key.startsWith(prefix)) delete slots[key];
+  }
+}
+
+/**
+ * Where the release read goes.
+ *
+ * Overridable for the same reason the npm probe honours `NPM_CONFIG_REGISTRY`: a
+ * test and a rehearsal need to exercise the real parsing against a stub instead
+ * of a live GitHub call, and hardcoding the host makes that impossible without
+ * intercepting `fetch` globally.
+ */
+export function githubApiBase(): string {
+  const configured = Bun.env.KABMO_GITHUB_API ?? '';
+  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.
+ */
+export 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;
+}

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

@@ -0,0 +1,187 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { beforeEach, describe, expect, test } from 'bun:test';
+
+import { fetchShellRelease, resetShellReleaseCache } from '@/server/lib/updates/shell-release';
+import { releaseTags } from '@/server/lib/updates/shell-pages';
+
+
+/**
+ * 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
+ * the pages answer the Atom feed and each release's asset fragment. Returning
+ * `undefined` 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 };
+}
+
+/**
+ * The public-pages fallback, and the reason it exists.
+ *
+ * The REST read is unauthenticated at 60 requests an hour per source IP, and on a
+ * mobile network that IP is a carrier NAT shared with an entire subscriber base.
+ * 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 being indistinguishable from "you are up to
+ * date". These cases pin the second path, which is what the report needed.
+ */
+describe('the fallback when the API is unavailable', () => {
+  beforeEach(() => resetShellReleaseCache());
+
+  const ATOM = `<?xml version="1.0" encoding="UTF-8"?>
+<feed xmlns="http://www.w3.org/2005/Atom">
+  <title>Release notes from kabmo</title>
+  <entry>
+    <id>tag:github.com,2008:Repository/1/v0.7.0</id>
+    <link rel="alternate" type="text/html" href="https://github.com/kabmo-labs/kabmo/releases/tag/v0.7.0"/>
+    <title>v0.7.0</title>
+  </entry>
+  <entry>
+    <link rel="alternate" type="text/html" href="https://github.com/kabmo-labs/kabmo/releases/tag/kabmo-sdk/v0.1.0"/>
+    <title>kabmo-sdk/v0.1.0</title>
+  </entry>
+  <entry>
+    <link rel="alternate" type="text/html" href="https://github.com/kabmo-labs/kabmo/releases/tag/v0.6.1"/>
+    <title>v0.6.1</title>
+  </entry>
+</feed>`;
+
+  /** The fragment GitHub's release page loads, trimmed to its asset links. */
+  const ASSETS_V070 = `
+<div class="Box">
+  <li><a href="/kabmo-labs/kabmo/releases/download/v0.7.0/Kabmo-0.6.0-android.apk"><span class="text-bold">Kabmo-0.6.0-android.apk</span></a></li>
+  <li><a href="/kabmo-labs/kabmo/releases/download/v0.7.0/Kabmo-0.2.0-mac-arm64.zip"><span class="text-bold">Kabmo-0.2.0-mac-arm64.zip</span></a></li>
+</div>`;
+
+  test('resolves the APK when the API read is refused', async () => {
+    // `api: undefined` is a spent quota: the route answers 403 with a body that
+    // is not a release list.
+    const { impl, calls } = routedFetch({ atom: ATOM, assets: { 'v0.7.0': ASSETS_V070 } });
+
+    expect(await fetchShellRelease('android', impl)).toEqual({
+      url: 'https://github.com/kabmo-labs/kabmo/releases/download/v0.7.0/Kabmo-0.6.0-android.apk',
+      latest: '0.6.0',
+      releaseUrl: 'https://github.com/kabmo-labs/kabmo/releases/tag/v0.7.0',
+      direct: true,
+    });
+    expect(calls.some((url) => url.includes('/repos/'))).toBe(true);
+    expect(calls.some((url) => url.endsWith('/releases.atom'))).toBe(true);
+  });
+
+  test('walks past a release that carries no artifact of this shell', async () => {
+    // The packages are released FIRST, so the newest tag is often a
+    // `kabmo-sdk/v*` release with no shell in it — the same shape that made
+    // `/releases/latest` wrong.
+    const { impl } = routedFetch({
+      atom: ATOM,
+      assets: { 'kabmo-sdk/v0.1.0': '<div>no assets</div>', 'v0.7.0': ASSETS_V070 },
+    });
+
+    expect((await fetchShellRelease('android', impl))?.latest).toBe('0.6.0');
+  });
+
+  test('answers the release page for a desktop shell with no arch', async () => {
+    const { impl } = routedFetch({ atom: ATOM, assets: { 'v0.7.0': ASSETS_V070 } });
+
+    expect(await fetchShellRelease('macos', impl)).toEqual({
+      url: 'https://github.com/kabmo-labs/kabmo/releases/tag/v0.7.0',
+      latest: '0.2.0',
+      releaseUrl: 'https://github.com/kabmo-labs/kabmo/releases/tag/v0.7.0',
+      direct: false,
+    });
+  });
+
+  test('answers that arch’s own artifact when the fragment lists it', async () => {
+    // The pages fallback carries the same arch rule as the API read: a desktop
+    // shell that named its machine gets that machine's installer, and a build it
+    // does not publish is never substituted.
+    const { impl } = routedFetch({ atom: ATOM, assets: { 'v0.7.0': ASSETS_V070 } });
+
+    expect(await fetchShellRelease('macos', impl, 'arm64')).toEqual({
+      url: 'https://github.com/kabmo-labs/kabmo/releases/download/v0.7.0/Kabmo-0.2.0-mac-arm64.zip',
+      latest: '0.2.0',
+      releaseUrl: 'https://github.com/kabmo-labs/kabmo/releases/tag/v0.7.0',
+      direct: true,
+    });
+
+    // x64 is not in the fragment, so the page is the answer rather than the
+    // arm64 file.
+    const again = routedFetch({ atom: ATOM, assets: { 'v0.7.0': ASSETS_V070 } });
+    expect(await fetchShellRelease('macos', again.impl, 'x64')).toEqual({
+      url: 'https://github.com/kabmo-labs/kabmo/releases/tag/v0.7.0',
+      latest: '0.2.0',
+      releaseUrl: 'https://github.com/kabmo-labs/kabmo/releases/tag/v0.7.0',
+      direct: false,
+    });
+  });
+
+  test('a release with no artifact anywhere answers empty, not null', async () => {
+    // "The read worked and there is nothing" and "the read failed" must stay
+    // distinguishable: the first is cacheable and the second keeps the last good
+    // answer.
+    const { impl } = routedFetch({ atom: ATOM, assets: { 'v0.7.0': '<div></div>' } });
+    expect(await fetchShellRelease('android', impl)).toEqual({
+      url: null,
+      latest: null,
+      releaseUrl: null,
+      direct: false,
+    });
+  });
+
+  test('an unreachable feed answers null rather than an empty result', async () => {
+    const { impl } = routedFetch({});
+    expect(await fetchShellRelease('android', impl)).toBeNull();
+  });
+
+  test('the API answer wins when it works, so the fallback costs nothing', async () => {
+    const { impl, calls } = routedFetch({
+      api: [
+        {
+          html_url: 'https://x/api',
+          assets: [{ name: 'Kabmo-1.0.0-android.apk', browser_download_url: 'https://x/a.apk' }],
+        },
+      ],
+      atom: ATOM,
+      assets: { 'v0.7.0': ASSETS_V070 },
+    });
+
+    expect((await fetchShellRelease('android', impl))?.latest).toBe('1.0.0');
+    expect(calls.some((url) => url.endsWith('/releases.atom'))).toBe(false);
+  });
+
+  test('releaseTags reads the feed in order, with each page', () => {
+    expect(releaseTags(ATOM)).toEqual([
+      { name: 'v0.7.0', url: 'https://github.com/kabmo-labs/kabmo/releases/tag/v0.7.0' },
+      { name: 'kabmo-sdk/v0.1.0', url: 'https://github.com/kabmo-labs/kabmo/releases/tag/kabmo-sdk/v0.1.0' },
+      { name: 'v0.6.1', url: 'https://github.com/kabmo-labs/kabmo/releases/tag/v0.6.1' },
+    ]);
+    expect(releaseTags('')).toEqual([]);
+  });
+});

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

@@ -0,0 +1,157 @@
+/**
+ * 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, selfUpdateArtifact, versionFromAssetName } from '@/server/lib/updates/shell-assets';
+import type { ShellArch } from '@/shared/lib/updates/shell-arch';
+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>,
+  arch: ShellArch | null = null,
+): 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(), arch);
+    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, arch: ShellArch | null = null): PageAsset | null {
+  const found: PageAsset[] = [];
+
+  for (const match of html.matchAll(ASSET_HREF)) {
+    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}` });
+  }
+
+  // The architecture decides FIRST, for the reason the API path documents: a
+  // desktop shell that named its own machine must not be handed the other
+  // architecture's installer just because the fragment lists it first.
+  if (arch) {
+    const exact = found.find((asset) => selfUpdateArtifact(kind, arch, asset.name) !== null);
+    if (exact) return exact;
+  }
+
+  return found.find((asset) => SHELL_ASSETS[kind].current.test(asset.name)) ?? found[0] ?? null;
+}
+
+/** One asset link in a release fragment. Stated once: the loop and the regex must agree. */
+const ASSET_HREF = /href="(\/[^"]+\/releases\/download\/[^"]+)"/g;
+
+/** 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, '&');
+}