@kabmo-labs/kabmo 0.6.1 → 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,44 +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-android-v1.2.3.apk')).toBe('1.2.3');
-    expect(versionFromAssetName('ios', 'kabmo-ios-v1.2.3.ipa')).toBe('1.2.3');
-  });
-
-  test('accepts a hand-uploaded name without the v', () => {
-    expect(versionFromAssetName('android', 'kabmo-android-1.2.3.apk')).toBe('1.2.3');
-    expect(versionFromAssetName('ios', 'kabmo-ios-1.2.3.ipa')).toBe('1.2.3');
-  });
-
-  test('ignores anything that is not that shell’s artifact', () => {
-    expect(versionFromAssetName('android', 'kabmo-android-v1.2.3.apk.zip')).toBeNull();
-    expect(versionFromAssetName('android', 'source.tar.gz')).toBeNull();
-    expect(versionFromAssetName('android', 'kabmo-android-latest.apk')).toBeNull();
-    expect(versionFromAssetName('android', '')).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-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) => {
@@ -50,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.
@@ -67,15 +73,15 @@ describe('fetchShellRelease', () => {
         assets: [
           { name: 'source.tar.gz', browser_download_url: 'https://x/src.tgz' },
           {
-            name: 'kabmo-android-v1.2.3.apk',
-            browser_download_url: 'https://x/kabmo-android-v1.2.3.apk',
+            name: 'Kabmo-1.2.3-android.apk',
+            browser_download_url: 'https://x/Kabmo-1.2.3-android.apk',
           },
         ],
       },
     ]);
 
     expect(await fetchShellRelease('android', impl)).toEqual({
-      url: 'https://x/kabmo-android-v1.2.3.apk',
+      url: 'https://x/Kabmo-1.2.3-android.apk',
       latest: '1.2.3',
       releaseUrl: 'https://github.com/kabmo-labs/kabmo/releases/tag/v9.9.9',
     });
@@ -86,8 +92,8 @@ describe('fetchShellRelease', () => {
       {
         html_url: 'https://x/app',
         assets: [
-          { name: 'kabmo-android-v0.9.0.apk', browser_download_url: 'https://x/a.apk' },
-          { name: 'kabmo-ios-v0.4.0.ipa', browser_download_url: 'https://x/i.ipa' },
+          { name: 'Kabmo-0.9.0-android.apk', browser_download_url: 'https://x/a.apk' },
+          { name: 'Kabmo-0.4.0-ios.ipa', browser_download_url: 'https://x/i.ipa' },
         ],
       },
     ]);
@@ -99,14 +105,54 @@ describe('fetchShellRelease', () => {
     });
   });
 
+  /**
+   * A release that carries BOTH spellings must answer with the current one.
+   *
+   * That state is real: a rename lands, and the previous release's asset stays
+   * beside the new one until `--clobber` replaces it (or a hand-upload adds
+   * one). Measured before the fix: a release holding both
+   * `kabmo-android-v0.4.0.apk` and `Kabmo-0.6.0-android.apk` answered `0.4.0` —
+   * the console offered an update to the version the user already had, and hid
+   * the newer one.
+   */
+  test('prefers the current scheme when a release carries both', async () => {
+    const { impl } = stubFetch([
+      {
+        html_url: 'https://x/r',
+        assets: [
+          { name: 'kabmo-android-v0.4.0.apk', browser_download_url: 'https://x/old.apk' },
+          { name: 'Kabmo-0.6.0-android.apk', browser_download_url: 'https://x/new.apk' },
+        ],
+      },
+    ]);
+
+    expect(await fetchShellRelease('android', impl)).toEqual({
+      url: 'https://x/new.apk',
+      latest: '0.6.0',
+      releaseUrl: 'https://x/r',
+    });
+  });
+
+  /** A release carrying ONLY the old spelling must keep answering. */
+  test('still resolves a release that only has the legacy spelling', async () => {
+    const { impl } = stubFetch([
+      {
+        html_url: 'https://x/r2',
+        assets: [{ name: 'kabmo-android-v0.4.0.apk', browser_download_url: 'https://x/old.apk' }],
+      },
+    ]);
+
+    expect((await fetchShellRelease('android', impl))?.latest).toBe('0.4.0');
+  });
+
   test('the two shells cache separately', async () => {
     // One shared slot would make the second probe answer with the first one's
     // artifact — the release list is the same read, the asset is not.
     const release = {
       html_url: 'https://x/app',
       assets: [
-        { name: 'kabmo-android-v1.0.0.apk', browser_download_url: 'https://x/a.apk' },
-        { name: 'kabmo-ios-v2.0.0.ipa', browser_download_url: 'https://x/i.ipa' },
+        { name: 'Kabmo-1.0.0-android.apk', browser_download_url: 'https://x/a.apk' },
+        { name: 'Kabmo-2.0.0-ios.ipa', browser_download_url: 'https://x/i.ipa' },
       ],
     };
     expect((await fetchShellRelease('android', stubFetch([release]).impl))?.latest).toBe('1.0.0');
@@ -129,7 +175,7 @@ describe('fetchShellRelease', () => {
       { html_url: 'https://x/kabmo-ui', assets: [] },
       {
         html_url: 'https://x/app',
-        assets: [{ name: 'kabmo-android-v0.3.0.apk', browser_download_url: 'https://x/a.apk' }],
+        assets: [{ name: 'Kabmo-0.3.0-android.apk', browser_download_url: 'https://x/a.apk' }],
       },
     ]);
 
@@ -145,16 +191,16 @@ describe('fetchShellRelease', () => {
       {
         draft: true,
         html_url: 'https://x/draft',
-        assets: [{ name: 'kabmo-android-v9.9.9.apk', browser_download_url: 'https://x/draft.apk' }],
+        assets: [{ name: 'Kabmo-9.9.9-android.apk', browser_download_url: 'https://x/draft.apk' }],
       },
       {
         prerelease: true,
         html_url: 'https://x/pre',
-        assets: [{ name: 'kabmo-android-v8.0.0.apk', browser_download_url: 'https://x/pre.apk' }],
+        assets: [{ name: 'Kabmo-8.0.0-android.apk', browser_download_url: 'https://x/pre.apk' }],
       },
       {
         html_url: 'https://x/app',
-        assets: [{ name: 'kabmo-android-v0.3.0.apk', browser_download_url: 'https://x/a.apk' }],
+        assets: [{ name: 'Kabmo-0.3.0-android.apk', browser_download_url: 'https://x/a.apk' }],
       },
     ]);
 
@@ -170,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',
+    });
+  });
 });