@kabmo-labs/kabmo 0.7.0 → 0.8.0

package/src/server/lib/panels/sync.server.ts

@@ -12,14 +12,22 @@
  * on the old copy. Nothing else would ever notice: the install is a directory of
  * ordinary files, and the scan has no notion of a store version.
  *
- * The sync runs at boot, after the listener is up, and it is VERSION-GATED — the
- * store copy is written over the install only when its manifest version is
- * strictly newer. That is what makes the pass safe to run unconditionally: a
- * user's plugin that happens to share an id with a store entry but was installed
- * from a git URL carries no `.git` ONLY if it was copied by hand, and a
- * hand-copied directory keeps working because its version is compared rather
- * than its provenance. A plugin installed from a git URL is skipped outright,
- * because the store's copy is not its source of truth.
+ * The sync runs at boot, after the listener is up. For an install KABMO WROTE —
+ * one carrying a baseline — the store's TREE is the gate, not its version: the
+ * copy is written whenever the two tracked trees differ, in either direction.
+ * A version gate cannot be the whole answer, and believing it was is what left
+ * every bundled plugin un-updatable after the product rename: that release
+ * rewrote the store's files and reset every bundled version to `0.0.1`, so the
+ * store was never "newer" than the install and the pass skipped forever —
+ * measured on a real install, where the only way to get the new code was to
+ * remove the plugin and install it again. Content is also the honest test for a
+ * shipped fix that forgot its bump.
+ *
+ * A directory with NO baseline is of unknown provenance (hand-copied, or
+ * installed by a build that predates the baseline), so it keeps the conservative
+ * version gate: a copy the user made themselves must not be replaced by a store
+ * entry that merely shares its id. A git clone is skipped outright, because the
+ * store's copy is not its source of truth.
  *
  * The install's `node_modules` and `dist` are left alone until the copy lands:
  * the sync copies the store's SOURCES, then rebuilds, exactly as an install
@@ -36,14 +44,21 @@ import { readPluginManifest, subdirectories } from '@/server/lib/panels/files.se
 import { toManifest } from '@/server/lib/panels/manifest';
 import { buildPanelPlugin } from '@/server/lib/panels/build.server';
 import { readGitOrigin } from '@/server/lib/panels/git-clone.server';
-import { changedPaths, hashTrackedFiles } from '@/server/lib/panels/local-edits.server';
-import { readBaseline, clearBaseline, writeBaseline, writeBlockedSync } from '@/server/lib/panels/baseline.server';
+import { baselineDescribesInstall, changedPaths, hashTrackedFiles, type TrackedFileHashes } from '@/server/lib/panels/local-edits.server';
+import { readBaseline, writeBaseline, writeBlockedSync } from '@/server/lib/panels/baseline.server';
 import { emitRealtimeSignal } from '@/server/lib/realtime/signals.server';
 
 export interface BundledSyncOutcome {
   pluginId: string;
   from: string;
   to: string;
+  /**
+   * True when the store's files changed but its manifest version did not.
+   *
+   * The common case after a shipped fix whose bump was missed, and the reason
+   * the gate is content: reporting it as `1.0.0 → 1.0.0` reads as a no-op.
+   */
+  contentOnly?: boolean;
   /** A rebuild that failed after the files were replaced. */
   warning?: string;
 }
@@ -81,9 +96,13 @@ async function manifestVersion(dir: string): Promise<string | null> {
  * that says otherwise. When the store has no `dist`, nothing is removed and the
  * rebuild regenerates it from the new sources.
  */
-async function replaceFromStore(source: string, destination: string): Promise<void> {
+async function replaceFromStore(
+  source: string,
+  destination: string,
+  knownInstallFiles?: TrackedFileHashes,
+): Promise<void> {
   const storeFiles = await hashTrackedFiles(source);
-  const installFiles = await hashTrackedFiles(destination);
+  const installFiles = knownInstallFiles ?? (await hashTrackedFiles(destination));
   for (const path of Object.keys(installFiles)) {
     if (path in storeFiles) continue;
     await rm(join(destination, path), { force: true });
@@ -100,7 +119,49 @@ async function replaceFromStore(source: string, destination: string): Promise<vo
 }
 
 /**
- * Bring every installed bundled plugin up to the store's version.
+ * Write the store's copy over an install and rebuild it.
+ *
+ * Shared by the boot pass and the override, because everything after the gate is
+ * identical and the parts that matter are the ones a second copy gets wrong: the
+ * replacement is a MIRROR, the manifest is re-read from what landed, and the
+ * baseline is re-taken AFTER the build so the next pass compares against the
+ * tree this one produced.
+ */
+async function applyStoreCopy(
+  pluginId: string,
+  storeDir: string,
+  destination: string,
+  from: string,
+  to: string,
+  installFiles: TrackedFileHashes,
+): Promise<{ outcome: BundledSyncOutcome } | { error: string }> {
+  await replaceFromStore(storeDir, destination, installFiles);
+
+  const read = await readPluginManifest(destination);
+  const manifest = read.kind === 'manifest' ? toManifest(read.value, destination) : null;
+  if (!manifest || 'error' in manifest) return { error: 'the store copy has no valid manifest' };
+
+  const build = await buildPanelPlugin(destination, manifest);
+  invalidatePanelScan();
+  // The new files are the baseline now — taken AFTER the build so the tree the
+  // next pass compares against is the one this pass produced.
+  await writeBaseline(pluginId, await hashTrackedFiles(destination));
+  await writeBlockedSync(pluginId, null);
+  return {
+    outcome: {
+      pluginId,
+      from,
+      to,
+      // The store changed but its manifest version did not. Naming it keeps a
+      // `1.0.0 → 1.0.0` line from reading as a no-op when a real fix landed.
+      ...(from === to ? { contentOnly: true } : {}),
+      ...(build.status === 'failed' ? { warning: build.reason ?? 'the plugin did not build' } : {}),
+    },
+  };
+}
+
+/**
+ * Bring every installed bundled plugin up to the store's copy.
  *
  * Never throws: one plugin that cannot be replaced must not stop the others, and
  * a failure is reported per plugin. Returns what actually moved.
@@ -132,9 +193,10 @@ export async function syncBundledPlugins(): Promise<{
     try {
       const storeVersion = await manifestVersion(join(storeRoot, pluginId));
       const installedVersion = await manifestVersion(destination);
-      if (!storeVersion || !installedVersion || !isNewer(storeVersion, installedVersion)) {
-        // Nothing to apply, so any earlier refusal no longer describes anything
-        // the user has to act on.
+      // A manifest that cannot be read on either side means there is no
+      // comparison to make at all — the scan reports it, and the sync leaves the
+      // directory alone rather than guessing which side is wrong.
+      if (!storeVersion || !installedVersion) {
         await writeBlockedSync(pluginId, null);
         continue;
       }
@@ -143,9 +205,48 @@ export async function syncBundledPlugins(): Promise<{
       // differs from it is the user's. A plugin with no baseline predates this
       // check (or was installed by an older build), and running is the only
       // useful answer: refusing would freeze it forever with no way to say why.
-      const baseline = await readBaseline(pluginId);
-      if (baseline) {
-        const changed = changedPaths(baseline, await hashTrackedFiles(destination));
+      //
+      // PROVENANCE and EVIDENCE are separate answers. A recorded baseline is what
+      // proves Kabmo wrote this directory, so the content gate below applies
+      // either way; only a baseline that still DESCRIBES the install may say a
+      // file is the user's — see `baselineDescribesInstall`. Obeying a stale one
+      // is what made the update unrecoverable: the rename rewrote every bundled
+      // file while an older baseline was recorded, so every path read as the
+      // user's edit and the only way out was removing the plugin.
+      const recorded = await readBaseline(pluginId);
+      const installFiles = await hashTrackedFiles(destination);
+      const storeFiles = await hashTrackedFiles(join(storeRoot, pluginId));
+      const trusted = recorded !== null && baselineDescribesInstall(recorded, installFiles, storeFiles);
+
+      // WHICH GATE APPLIES IS DECIDED BY PROVENANCE, and the two answer
+      // different questions:
+      //
+      // - A directory Kabmo wrote is compared by CONTENT. The store's tree is
+      //   the source of truth for it, so any difference is an update — including
+      //   a fix shipped without a version bump, and including the case that made
+      //   this a bug: the product rename rewrote every bundled file AND reset the
+      //   versions to 0.0.1, so a version gate could never see the store as
+      //   newer and the plugin was stuck until it was removed and reinstalled
+      //   (measured on a real install).
+      // - A directory with no recorded baseline is of unknown provenance, so the
+      //   conservative version gate stays: a hand-copied directory that happens
+      //   to share a store id must not be overwritten by a store entry that is
+      //   merely newer than it.
+      const contentDiffers = changedPaths(installFiles, storeFiles).length > 0;
+      const versionIsNewer = isNewer(storeVersion, installedVersion);
+      const shouldApply = recorded ? contentDiffers : versionIsNewer;
+      if (!shouldApply) {
+        // Nothing to apply, so any earlier refusal no longer describes anything
+        // the user has to act on.
+        await writeBlockedSync(pluginId, null);
+        // A stale baseline is replaced by what is on disk, so the next release's
+        // update compares against reality rather than against history.
+        if (recorded && !trusted) await writeBaseline(pluginId, installFiles);
+        continue;
+      }
+
+      if (trusted) {
+        const changed = changedPaths(recorded, installFiles);
         if (changed.length > 0) {
           blocked.push({ pluginId, from: installedVersion, to: storeVersion, changed });
           await writeBlockedSync(pluginId, { at: Date.now(), changed });
@@ -153,26 +254,19 @@ export async function syncBundledPlugins(): Promise<{
         }
       }
 
-      await replaceFromStore(join(storeRoot, pluginId), destination);
-
-      const read = await readPluginManifest(destination);
-      const manifest = read.kind === 'manifest' ? toManifest(read.value, destination) : null;
-      if (!manifest || 'error' in manifest) {
-        failed.push({ pluginId, error: 'the store copy has no valid manifest' });
+      const applied = await applyStoreCopy(
+        pluginId,
+        join(storeRoot, pluginId),
+        destination,
+        installedVersion,
+        storeVersion,
+        installFiles,
+      );
+      if ('error' in applied) {
+        failed.push({ pluginId, error: applied.error });
         continue;
       }
-      const build = await buildPanelPlugin(destination, manifest);
-      invalidatePanelScan();
-      // The new files are the baseline now — taken AFTER the build so the tree
-      // the next pass compares against is the one this pass produced.
-      await writeBaseline(pluginId, await hashTrackedFiles(destination));
-      await writeBlockedSync(pluginId, null);
-      updated.push({
-        pluginId,
-        from: installedVersion,
-        to: storeVersion,
-        ...(build.status === 'failed' ? { warning: build.reason ?? 'the plugin did not build' } : {}),
-      });
+      updated.push(applied.outcome);
     } catch (error) {
       failed.push({ pluginId, error: error instanceof Error ? error.message : String(error) });
     }
@@ -187,9 +281,11 @@ export async function syncBundledPlugins(): Promise<{
  *
  * The escape hatch for a refusal: the user has seen which files differ and asked
  * for the store's copy anyway, which is the only way past a baseline Kabmo
- * cannot reconcile. The baseline is dropped first, so the pass that follows takes
- * the store's files and re-records what it wrote — the same end state a clean
- * install reaches.
+ * cannot reconcile. It applies the copy DIRECTLY rather than clearing the
+ * baseline and re-running the pass: a cleared baseline makes the plugin read as
+ * "unknown provenance", which is exactly the state the conservative version gate
+ * governs — so the override silently became a no-op whenever the store's version
+ * was not newer, which is the case it most often exists for.
  *
  * Deliberately addressed by id and refusing anything that is not a bundled
  * install: this must never be a way to overwrite a git clone.
@@ -201,12 +297,21 @@ export async function forceSyncBundledPlugin(pluginId: string): Promise<{ ok: bo
   if (!(await pathExists(destination))) return { ok: false, error: `${pluginId} is not installed.` };
   if (await readGitOrigin(destination)) return { ok: false, error: `${pluginId} is a git clone; its own Update is the way to change it.` };
 
-  await clearBaseline(pluginId);
-  await writeBlockedSync(pluginId, null);
-  const result = await syncBundledPlugins();
-  const failed = result.failed.find((entry) => entry.pluginId === pluginId);
-  if (failed) return { ok: false, error: failed.error };
-  const outcome = result.updated.find((entry) => entry.pluginId === pluginId);
-  if (!outcome) return { ok: false, error: `${pluginId} is already at the store's version.` };
-  return { ok: true, ...(outcome.warning ? { warning: outcome.warning } : {}) };
+  const from = (await manifestVersion(destination)) ?? 'unknown';
+  const to = (await manifestVersion(storeDir)) ?? 'unknown';
+  try {
+    const applied = await applyStoreCopy(
+      pluginId,
+      storeDir,
+      destination,
+      from,
+      to,
+      await hashTrackedFiles(destination),
+    );
+    if ('error' in applied) return { ok: false, error: applied.error };
+    emitRealtimeSignal('panels-changed');
+    return { ok: true, ...(applied.outcome.warning ? { warning: applied.outcome.warning } : {}) };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
 }

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

@@ -0,0 +1,114 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { versionFromAssetName } from '@/server/lib/updates/shell-assets';
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+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 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();
+  });
+
+  /**
+   * The desktop trio, one entry each.
+   *
+   * A desktop release carries SEVERAL files per platform (two arches × two
+   * macOS shapes, four Linux formats), so the match is on the segment after the
+   * version rather than the whole name: any one of them answers the same
+   * version, and the download the console offers is the release page.
+   */
+  test('reads every desktop spelling, and only its own platform', () => {
+    for (const name of ['Kabmo-0.2.0-mac-arm64.zip', 'Kabmo-0.2.0-mac-x64.dmg']) {
+      expect(versionFromAssetName('macos', name), name).toBe('0.2.0');
+      expect(versionFromAssetName('windows', name), name).toBeNull();
+      expect(versionFromAssetName('linux', name), name).toBeNull();
+    }
+    for (const name of ['Kabmo-0.2.0-win-x64-setup.exe', 'Kabmo-0.2.0-win-arm64-setup.exe']) {
+      expect(versionFromAssetName('windows', name), name).toBe('0.2.0');
+      expect(versionFromAssetName('macos', name), name).toBeNull();
+    }
+    for (const name of [
+      'Kabmo-0.2.0-linux-x86_64.tar.gz',
+      'Kabmo-0.2.0-linux-arm64.tar.gz',
+      'Kabmo-0.2.0-linux-amd64.deb',
+      'Kabmo-0.2.0-linux-arm64.rpm',
+      'Kabmo-0.2.0-linux-x86_64.AppImage',
+    ]) {
+      expect(versionFromAssetName('linux', name), name).toBe('0.2.0');
+      expect(versionFromAssetName('macos', name), name).toBeNull();
+    }
+  });
+
+  test('a desktop shell reads no mobile asset, and vice versa', () => {
+    // The `Kabmo-` prefix is shared by all five, so a scheme that matched on the
+    // prefix alone would offer an APK to a Mac.
+    expect(versionFromAssetName('macos', 'Kabmo-0.6.0-android.apk')).toBeNull();
+    expect(versionFromAssetName('windows', 'Kabmo-0.2.0-ios.ipa')).toBeNull();
+    expect(versionFromAssetName('linux', 'Kabmo-0.6.0-android.apk')).toBeNull();
+    expect(versionFromAssetName('android', 'Kabmo-0.2.0-linux-x86_64.tar.gz')).toBeNull();
+    expect(versionFromAssetName('ios', 'Kabmo-0.2.0-win-x64-setup.exe')).toBeNull();
+  });
+});

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

@@ -0,0 +1,109 @@
+/**
+ * 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 { 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, and the download is the release page.
+ *
+ * **`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. False for a
+   * per-arch desktop build, where the release page is the only honest link.
+   */
+  directDownload: boolean;
+}
+
+const VERSION = String.raw`(\d+\.\d+\.\d+)`;
+
+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,
+  },
+  ios: {
+    pattern: new RegExp(`^Kabmo-${VERSION}-ios\\.ipa$`),
+    current: /^Kabmo-\d/,
+    legacy: { prefix: 'kabmo-ios-v', extension: '.ipa' },
+    directDownload: true,
+  },
+  macos: {
+    pattern: new RegExp(`^Kabmo-${VERSION}-mac-`),
+    current: /^Kabmo-\d/,
+    legacy: null,
+    directDownload: false,
+  },
+  windows: {
+    pattern: new RegExp(`^Kabmo-${VERSION}-win-`),
+    current: /^Kabmo-\d/,
+    legacy: null,
+    directDownload: false,
+  },
+  linux: {
+    pattern: new RegExp(`^Kabmo-${VERSION}-linux-`),
+    current: /^Kabmo-\d/,
+    legacy: null,
+    directDownload: false,
+  },
+};
+
+/**
+ * `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-pages.test.ts

@@ -0,0 +1,156 @@
+/**
+ * @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',
+    });
+    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', 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',
+    });
+  });
+
+  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 });
+  });
+
+  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([]);
+  });
+});