@kabmo-labs/kabmo 0.5.3 → 0.6.0

package/src/client/hooks/ui/updates/android-download.ts

@@ -1,143 +0,0 @@
-/**
- * What the sidebar should offer for the Android shell, and why.
- *
- * Two DIFFERENT offers, from two different facts:
- *
- * - **`update`** — this page is running inside the APK (`shellVersion` from the
- *   bootstrap) and a newer one is published. An up-to-date app offers nothing:
- *   a button that downloads the build already installed is worse than no button.
- * - **`install`** — this page is an Android BROWSER (Chrome, Brave, Firefox) and
- *   an APK is published. The reader may not know a native shell exists, and
- *   telling them is the whole point of the offer; there is no installed version
- *   to compare against, so the newest published one is what it names.
- *
- * A desktop browser gets neither: `isAndroid` is false, an APK cannot be
- * installed there, and the app's own update badge already covers the server.
- *
- * The probe is lazy: it runs only on an Android device, never on a desktop, so a
- * console that can never show the button makes no request for it.
- */
-
-import { useEffect, useState } from 'preact/hooks';
-import { isNewer } from '@/shared/lib/updates/semver';
-
-/** Which offer this is — the two carry different wording. */
-export type AndroidOfferKind = 'update' | 'install';
-
-export interface AndroidDownload {
-  /** The asset to download. */
-  url: string;
-  /** The version that asset ships. */
-  latest: string;
-  /** The release page, for a "what changed" link. */
-  releaseUrl: string | null;
-  /** An update to an installed APK, or a first install from a browser. */
-  kind: AndroidOfferKind;
-}
-
-interface ReleasePayload {
-  url?: unknown;
-  latest?: unknown;
-  releaseUrl?: unknown;
-}
-
-/**
- * Read the release payload defensively.
- *
- * The route answers `{url: null, latest: null, releaseUrl: null}` on a failed
- * probe, so a shape check that only looks at the version would offer a button
- * with no link.
- */
-export function parseAndroidRelease(payload: unknown): Omit<AndroidDownload, 'kind'> | null {
-  if (typeof payload !== 'object' || payload === null) return null;
-  const body = payload as ReleasePayload;
-  if (typeof body.url !== 'string' || !body.url) return null;
-  if (typeof body.latest !== 'string' || !body.latest) return null;
-  return {
-    url: body.url,
-    latest: body.latest,
-    releaseUrl: typeof body.releaseUrl === 'string' ? body.releaseUrl : null,
-  };
-}
-
-/**
- * The offer, or null.
- *
- * `shellVersion` is null in every browser — that is what makes the two branches
- * mutually exclusive — and `isAndroid` is the wider fact that admits a browser
- * ON ANDROID. Both come from the bootstrap rather than a client-side UA sniff:
- * the server already parsed them for the very request that served the page.
- *
- * An `install` needs no version comparison, because nothing is installed. It
- * does require a published APK: `release` being null is a failed probe, and a
- * button the console cannot back with a link must not appear.
- */
-export function shouldOfferAndroidDownload(
-  shellVersion: string | null | undefined,
-  isAndroid: boolean | null | undefined,
-  release: Omit<AndroidDownload, 'kind'> | null,
-): AndroidDownload | null {
-  if (!release) return null;
-
-  // Inside the APK: an update, and only when one exists.
-  if (shellVersion) {
-    return isNewer(release.latest, shellVersion) ? { ...release, kind: 'update' } : null;
-  }
-
-  // A browser on an Android device: the app is something to install.
-  if (isAndroid) return { ...release, kind: 'install' };
-
-  return null;
-}
-
-/**
- * The wording of the offer, in one place.
- *
- * Both layouts draw this control and they must say the same thing: an installed
- * app that is behind is an UPDATE, and a browser on Android is an INSTALL —
- * "Download" for both would leave a first-time reader unsure whether they
- * already have the app. The version is in the label because the asset is a
- * specific build, not "the app".
- */
-export function androidDownloadLabel(download: AndroidDownload): string {
-  const verb = download.kind === 'update' ? 'Update' : 'Install';
-  return `${verb} Kabmo ${download.latest} for Android`;
-}
-
-/**
- * Fetch the published APK and decide what to offer.
- *
- * `fetchImpl` is a seam for the tests: the cases that matter (no release, a
- * failed probe, a version equal to the installed one) cannot be produced by a
- * live GitHub call.
- */
-export function useAndroidDownload(
-  shellVersion: string | null | undefined,
-  isAndroid: boolean | null | undefined,
-  fetchImpl: typeof fetch = fetch,
-): AndroidDownload | null {
-  const [release, setRelease] = useState<Omit<AndroidDownload, 'kind'> | null>(null);
-  const wanted = Boolean(shellVersion) || Boolean(isAndroid);
-
-  useEffect(() => {
-    if (!wanted) return;
-
-    let cancelled = false;
-    void (async () => {
-      try {
-        const response = await fetchImpl('/api/updates/android');
-        if (!response.ok) return;
-        const payload: unknown = await response.json();
-        if (!cancelled) setRelease(parseAndroidRelease(payload));
-      } catch {
-        // A probe that cannot answer is a button that must not appear.
-      }
-    })();
-
-    return () => {
-      cancelled = true;
-    };
-  }, [wanted, fetchImpl]);
-
-  return shouldOfferAndroidDownload(shellVersion, isAndroid, release);
-}

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

@@ -1,138 +0,0 @@
-/**
- * @license
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { beforeEach, describe, expect, test } from 'bun:test';
-
-import {
-  fetchAndroidRelease,
-  resetAndroidReleaseCache,
-  versionFromAssetName,
-} from '@/server/lib/updates/android-release';
-
-/**
- * The asset name is the only place the APK'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 an APK version.
- */
-describe('versionFromAssetName', () => {
-  test('reads the version the release workflow writes', () => {
-    expect(versionFromAssetName('kabmo-android-v1.2.3.apk')).toBe('1.2.3');
-  });
-
-  test('accepts a hand-uploaded name without the v', () => {
-    expect(versionFromAssetName('kabmo-android-1.2.3.apk')).toBe('1.2.3');
-  });
-
-  test('ignores anything that is not the APK', () => {
-    expect(versionFromAssetName('kabmo-android-v1.2.3.apk.zip')).toBeNull();
-    expect(versionFromAssetName('source.tar.gz')).toBeNull();
-    expect(versionFromAssetName('kabmo-android-latest.apk')).toBeNull();
-    expect(versionFromAssetName('')).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) => {
-    calls.push(String(input));
-    return {
-      ok,
-      json: async () => body,
-    } as Response;
-  }) as unknown as typeof fetch;
-  return { impl, calls };
-}
-
-describe('fetchAndroidRelease', () => {
-  // The cache is process-wide (see `resetAndroidReleaseCache`), so every case
-  // starts from a cold one or it reads the previous case's answer.
-  beforeEach(() => resetAndroidReleaseCache());
-
-  test('picks the APK asset and its version', async () => {
-    const { impl } = stubFetch([
-      {
-        html_url: 'https://github.com/kabmo-labs/kabmo/releases/tag/v9.9.9',
-        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',
-          },
-        ],
-      },
-    ]);
-
-    const release = await fetchAndroidRelease(impl);
-    expect(release).toEqual({
-      url: 'https://x/kabmo-android-v1.2.3.apk',
-      latest: '1.2.3',
-      releaseUrl: 'https://github.com/kabmo-labs/kabmo/releases/tag/v9.9.9',
-    });
-  });
-
-  test('skips a newer release that carries no APK', async () => {
-    // This is the shape that broke the button: `release.yml` releases the npm
-    // packages FIRST, so `kabmo-sdk/v0.0.2` is newer than the app release that
-    // holds the APK. Asking `/releases/latest` answered the package release and
-    // the button vanished while the APK sat one entry below.
-    const { impl } = stubFetch([
-      { html_url: 'https://x/kabmo-sdk', assets: [{ name: 'source.tar.gz' }] },
-      { 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' }],
-      },
-    ]);
-
-    expect(await fetchAndroidRelease(impl)).toEqual({
-      url: 'https://x/a.apk',
-      latest: '0.3.0',
-      releaseUrl: 'https://x/app',
-    });
-  });
-
-  test('skips drafts and prereleases', async () => {
-    const { impl } = stubFetch([
-      {
-        draft: true,
-        html_url: 'https://x/draft',
-        assets: [{ name: 'kabmo-android-v9.9.9.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' }],
-      },
-      {
-        html_url: 'https://x/app',
-        assets: [{ name: 'kabmo-android-v0.3.0.apk', browser_download_url: 'https://x/a.apk' }],
-      },
-    ]);
-
-    expect((await fetchAndroidRelease(impl))?.latest).toBe('0.3.0');
-  });
-
-  test('answers null for a list with no APK anywhere', async () => {
-    const { impl } = stubFetch([
-      { html_url: 'https://x', assets: [{ name: 'notes.md' }] },
-      { html_url: 'https://y', assets: [] },
-    ]);
-    expect(await fetchAndroidRelease(impl)).toEqual({ url: null, latest: null, releaseUrl: null });
-  });
-
-  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);
-    expect(await fetchAndroidRelease(impl)).toBeNull();
-  });
-
-  test('answers null when the body is malformed', async () => {
-    const { impl } = stubFetch({ assets: 'nope' });
-    expect(await fetchAndroidRelease(impl)).toBeNull();
-  });
-});

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

@@ -1,183 +0,0 @@
-/**
- * Which Android APK a browser should download, and whether this one is behind.
- *
- * The APK is NOT an npm package (see `.github/workflows/publish-android.yml`), so
- * the npm probe that answers for the app and for `omp` cannot answer here. The
- * only record of a published APK 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 `fetchAndroidRelease`).
- *
- * Two facts travel back, and they answer different questions:
- *
- * - `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 tag
- *   (`kabmo-android-v1.2.3.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 APK is attached to the app's release, whose
- *   tag names the SERVER version, and the two move independently.
- *
- * 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.
- */
-
-import { REPO } from '@/server/lib/updates/release-url';
-
-/** One published APK, as the console needs it. */
-export interface AndroidRelease {
-  /** Asset download URL, or null when the release carries no APK. */
-  url: string | null;
-  /** Version the asset name declares (`v1.2.3` → `1.2.3`), or null. */
-  latest: string | null;
-  /** The release page, for a "what changed" link. */
-  releaseUrl: string | null;
-}
-
-/** The asset-name prefix the release workflow writes. */
-const ASSET_PREFIX = 'kabmo-android-';
-
-/**
- * `kabmo-android-v1.2.3.apk` → `1.2.3`.
- *
- * The `v` is optional because a hand-uploaded asset may omit it, and a version
- * that cannot be read is not evidence of an update — the caller treats null as
- * "no new version".
- */
-export function versionFromAssetName(name: string): string | null {
-  if (!name.startsWith(ASSET_PREFIX) || !name.endsWith('.apk')) return null;
-  const middle = name.slice(ASSET_PREFIX.length, -'.apk'.length);
-  const version = middle.startsWith('v') ? middle.slice(1) : middle;
-  return /^\d+\.\d+\.\d+/.test(version) ? version : null;
-}
-
-/**
- * The newest release that actually carries an APK.
- *
- * 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 → app` in `release.yml`),
- * so their `kabmo-sdk/v*` / `kabmo-ui/v*` releases are newer than the app
- * release that carries the APK. `@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, 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.
- */
-export async function fetchAndroidRelease(fetchImpl: typeof fetch = fetch): Promise<AndroidRelease | null> {
-  const cache = cacheSlot();
-  const now = Date.now();
-  if (cache.entry && now - cache.at < CACHE_MS) return cache.entry;
-
-  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',
-      },
-    });
-    if (!response.ok) return cache.entry ?? 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 APK", and the caller would
-    // cache that mistake for five minutes.
-    if (!Array.isArray(body)) return cache.entry ?? null;
-
-    // Drafts are not published and prereleases are not what a console offers an
-    // installed app — the same two the `latest` endpoint excluded.
-    const published = body.filter(
-      (entry): entry is Record<string, unknown> =>
-        entry !== null && typeof entry === 'object' && entry.draft !== true && entry.prerelease !== true,
-    );
-
-    const release = published
-      .map((entry) => ({ entry, asset: apkAsset(entry.assets) }))
-      .find((candidate) => candidate.asset !== null);
-
-    if (!release?.asset) {
-      const fallback: AndroidRelease = { url: null, latest: null, releaseUrl: null };
-      cache.entry = fallback;
-      cache.at = now;
-      return fallback;
-    }
-
-    const resolved: AndroidRelease = {
-      url: typeof release.asset.browser_download_url === 'string' ? release.asset.browser_download_url : null,
-      latest: versionFromAssetName(String(release.asset.name)),
-      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;
-  }
-}
-
-/** How many releases to look back through for the APK. */
-const RELEASE_SCAN = 20;
-
-/** The first asset of a release that names an APK, or null. */
-function apkAsset(assets: unknown): Record<string, unknown> | null {
-  if (!Array.isArray(assets)) return null;
-
-  for (const entry of assets) {
-    if (entry === null || typeof entry !== 'object') continue;
-    const asset = entry as Record<string, unknown>;
-    if (typeof asset.name === 'string' && versionFromAssetName(asset.name) !== null) return asset;
-  }
-
-  return null;
-}
-
-const CACHE_MS = 5 * 60_000;
-
-/**
- * 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.
- */
-function githubApiBase(): string {
-  const configured = Bun.env.KABMO_GITHUB_API ?? '';
-  return configured.trim().replace(/\/+$/, '') || 'https://api.github.com';
-}
-
-interface CacheSlot {
-  entry: AndroidRelease | null;
-  at: number;
-}
-
-function cacheSlot(): CacheSlot {
-  const host = globalThis as typeof globalThis & { __kabmoAndroidRelease?: CacheSlot };
-  host.__kabmoAndroidRelease ??= { entry: null, at: 0 };
-  return host.__kabmoAndroidRelease;
-}
-
-/**
- * Drop the cached answer.
- *
- * The cache lives on `globalThis` so `bun --hot` cannot orphan it, which also
- * means it outlives a test file: without this 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). Production has no
- * caller; it exists because the cache is process-wide by design.
- */
-export function resetAndroidReleaseCache(): void {
-  cacheSlot().entry = null;
-  cacheSlot().at = 0;
-}