@kabmo-labs/kabmo 0.7.0 → 0.9.0

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

@@ -1,208 +1,220 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
 /**
  * Which published native-shell artifact a browser or an installed shell should
  * download, and whether the installed one is behind.
  *
- * Neither shell is an npm package (see `.github/workflows/publish-android.yml`
- * and `publish-ios.yml`), so the npm probe that answers for the app and for
- * `omp` cannot answer here. The only record of a published shell is a GitHub
- * release asset, which means one unauthenticated REST read of the release LIST —
- * not `/releases/latest`, which answers the newest release of ANY kind (see
- * `fetchShellRelease`).
+ * No shell is an npm package (see `.github/workflows/publish-{android,ios,macos,
+ * windows,linux}.yml`), so the npm probe that answers for the app and for `omp`
+ * cannot answer here. The only record of a published shell is a GitHub release
+ * asset.
+ *
+ * ## Two reads, because one of them has a quota
  *
- * ONE module for both shells, because the question is identical and only the
- * asset naming differs. Two copies is how one of them starts reading the release
- * tag, or caching under a slot the other overwrites.
+ * The REST API is the precise read and the FIRST one tried. It is also
+ * unauthenticated at 60 requests an hour **per source IP**, and a phone on mobile
+ * data shares that IP with an entire carrier NAT — so `shell-pages` is the second
+ * path, and it is why the button appears at all on a bad day. See that module's
+ * own comment for the measured failure.
  *
- * Two facts travel back, and they answer different questions:
+ * ## What travels back
  *
- * - `url` is the asset to download. It is resolved from the release's OWN asset
- *   list rather than built as `releases/latest/download/<name>`, because that
- *   path needs the asset name to match exactly and the name carries the shell's
- *   version (`Kabmo-0.5.0-android.apk`) — a name built here would be a second
- *   copy of the workflow's naming rule, and the first release that renames it
- *   404s.
- * - `latest` is the version that asset ships, read from the asset name. The
- *   release TAG cannot be used: the artifact is attached to the app's release,
- *   whose tag names the SERVER version, and the two move independently.
+ * - `url` is what to download. For the mobile pair it is the artifact itself (an
+ *   APK the shell installs, an IPA the release page explains). For the DESKTOP
+ *   trio it is the artifact when the caller reported its ARCHITECTURE, and the
+ *   release page otherwise: every desktop artifact is per-architecture, and a
+ *   console served to another machine cannot guess. Naming the wrong arch's file
+ *   would hand half the readers a build that will not launch.
+ * - `direct` says which of the two `url` is, so the client knows whether the
+ *   offer can be installed from inside the shell.
+ * - `latest` is the version that asset ships, read from the asset NAME (see
+ *   `shell-assets`). The release TAG cannot be used: the artifact is attached to
+ *   the app's release, whose tag names the SERVER version.
  *
- * Failure is a normal answer here (`null`), never a throw: an offline box 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.
+ * Failure is a normal answer here (`null`), never a throw: an offline box must
+ * not take the sidebar down, and a button that appears because a probe failed
+ * would offer a download that does not exist.
  */
 
 import { REPO } from '@/server/lib/updates/release-url';
+import {
+  cacheSlot,
+  CACHE_MS,
+  githubApiBase,
+  gitHubHeaders,
+  shellCacheKey,
+} from '@/server/lib/updates/shell-cache';
+import { SHELL_ASSETS, selfUpdateArtifact, versionFromAssetName } from '@/server/lib/updates/shell-assets';
+import { findAssetInPages } from '@/server/lib/updates/shell-pages';
+import type { ShellArch } from '@/shared/lib/updates/shell-arch';
 import type { ShellKind } from '@/shared/lib/updates/shell-ua';
 
+/**
+ * The test seam for the process-wide answer cache, re-exported here because this
+ * module is what owns the answers. The cache itself lives next door (`shell-cache`)
+ * so its key — shell AND architecture — is stated in one place.
+ */
+export { resetShellReleaseCache } from '@/server/lib/updates/shell-cache';
+
 /** One published shell artifact, as the console needs it. */
 export interface ShellRelease {
-  /** Asset download URL, or null when the release carries no artifact. */
+  /** Asset download URL, or the release page for a per-arch desktop build. */
   url: string | null;
-  /** Version the asset name declares (`v1.2.3` → `1.2.3`), or null. */
+  /** Version the asset name declares (`Kabmo-1.2.3-android.apk` → `1.2.3`). */
   latest: string | null;
   /** The release page, for a "what changed" link. */
   releaseUrl: string | null;
+  /**
+   * True when `url` names the artifact itself rather than the release page.
+   *
+   * This is what tells the console whether the offer can be INSTALLED from
+   * inside the shell. It is true for the mobile pair (one file for every
+   * device) and for a desktop shell that reported its architecture — and false
+   * for a desktop probe without one, which still gets the page that lists every
+   * architecture.
+   */
+  direct: boolean;
 }
 
-/**
- * How each shell's asset is named by its publish workflow, plus the prefix it
- * carried BEFORE the rename.
- *
- * ONE scheme for every shell in the project — `<App>-<version>-<platform>.<ext>`:
- * `Kabmo-0.5.0-android.apk`, `Kabmo-0.1.0-ios.ipa`, and the desktop trio's
- * `Kabmo-0.1.2-mac-arm64.dmg` / `-win-x64-setup.exe` / `-linux-x86_64.tar.gz`.
- * The mobile pair carries no architecture because neither artifact is per-arch:
- * the APK is one universal build (the shell is pure Kotlin with no native
- * libraries, so there is nothing to split), and the IPA contains only the device
- * slice (`arm64-apple-ios`). A `-arm64` in those names would claim a distinction
- * that does not exist and would make the parser look for a second artifact.
- *
- * **`legacyPrefix` is not dead code.** These names are PARSED to answer "is a
- * newer shell published", and every release already on GitHub carries the old
- * spelling. Dropping it would make the console answer "no update" for an
- * installed shell the moment this ships — silently, because a name that does not
- * match reads exactly like a release with no artifact. The probe tries the
- * current prefix first, then the old one; new releases only ever write the
- * current one.
- */
-export const SHELL_ASSETS: Record<
-  ShellKind,
-  { prefix: string; extension: string; legacyPrefix: string; legacyExtension: string }
-> = {
-  android: {
-    prefix: 'Kabmo-',
-    extension: '-android.apk',
-    legacyPrefix: 'kabmo-android-v',
-    legacyExtension: '.apk',
-  },
-  ios: { prefix: 'Kabmo-', extension: '-ios.ipa', legacyPrefix: 'kabmo-ios-v', legacyExtension: '.ipa' },
-};
-
-/**
- * `Kabmo-0.5.0-android.apk` → `0.5.0` (and the `.ipa` twin), plus the legacy
- * `kabmo-android-v0.5.0.apk` spelling every published release still carries.
- *
- * The version is the MIDDLE of the name in the current scheme and the TAIL of the
- * legacy one, so the two are parsed by different rules rather than by one that
- * tries to cover both.
- */
-export function versionFromAssetName(kind: ShellKind, name: string): string | null {
-  const { prefix, extension, legacyPrefix, legacyExtension } = SHELL_ASSETS[kind];
-
-  // Current: `<prefix><version><extension>`, where the prefix is the app's name
-  // and the extension names the platform.
-  if (name.startsWith(prefix) && name.endsWith(extension)) {
-    const middle = name.slice(prefix.length, -extension.length);
-    if (/^\d+\.\d+\.\d+$/.test(middle)) return middle;
-  }
-
-  // Legacy: `kabmo-android-v<version>.apk`. Kept for the releases already
-  // published; no new release writes it.
-  if (name.startsWith(legacyPrefix) && name.endsWith(legacyExtension)) {
-    const middle = name.slice(legacyPrefix.length, -legacyExtension.length);
-    const version = middle.startsWith('v') ? middle.slice(1) : middle;
-    return /^\d+\.\d+\.\d+$/.test(version) ? version : null;
-  }
-
-  return null;
-}
+/** The answer a probe gives when it found nothing: a valid result, not an error. */
+const EMPTY_RELEASE: ShellRelease = { url: null, latest: null, releaseUrl: null, direct: false };
 
 /**
  * The newest release that actually carries this shell's artifact.
  *
  * NOT `/releases/latest`, which answers the newest release of ANY kind. This
- * repository publishes three artifacts from one push, and the packages are
- * released FIRST (`packages → marketplace → android → apk-build → app` in
+ * repository publishes several artifacts from one push, and the packages are
+ * released FIRST (`packages → marketplace → android → … → app` in
  * `release.yml`), so their `kabmo-sdk/v*` / `kabmo-ui/v*` releases are newer
- * than the app release that carries the shell. `@semantic-release/github` runs
+ * than the app release that carries the shells. `@semantic-release/github` runs
  * in both pipelines, so those are real releases — measured against a stub that
- * answered a package release: `/releases/latest` produced
- * `{url: null, latest: null}` and the sidebar's button disappeared even though
- * the APK sat on the release directly below.
+ * answered a package release: `/releases/latest` produced `{url: null, …}` and
+ * the sidebar's button disappeared even though the APK sat on the release
+ * directly below.
+ *
+ * `arch` is what a DESKTOP shell reports about its own machine, and it is the
+ * difference between "here is the page, pick your build" and "here is your
+ * installer". It is the THIRD parameter so every existing caller — including
+ * every test, which passes `fetchImpl` — keeps its shape.
  *
- * One request per shell, cached for five minutes on `globalThis` for the same
+ * Cached for five minutes on `globalThis` (see `shell-cache`) 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.
+ * module while the cache it would otherwise hold lives on.
  */
 export async function fetchShellRelease(
   kind: ShellKind,
   fetchImpl: typeof fetch = fetch,
+  arch: ShellArch | null = null,
 ): Promise<ShellRelease | null> {
-  const cache = cacheSlot(kind);
+  const cache = cacheSlot<ShellRelease>(shellCacheKey(kind, arch));
   const now = Date.now();
   if (cache.entry && now - cache.at < CACHE_MS) return cache.entry;
 
+  const headers = gitHubHeaders();
+  const resolved =
+    (await readFromApi(kind, arch, fetchImpl, headers)) ??
+    (await readFromPages(kind, arch, fetchImpl, headers));
+  if (!resolved) return cache.entry ?? null;
+
+  cache.entry = resolved;
+  cache.at = now;
+  return resolved;
+}
+
+/** How many releases to look back through for the artifact. */
+const RELEASE_SCAN = 20;
+
+/**
+ * The REST read, or null when it did not answer with a usable release list.
+ *
+ * A non-2xx is not an error to report — it is the quota, and the caller has a
+ * second path.
+ */
+async function readFromApi(
+  kind: ShellKind,
+  arch: ShellArch | null,
+  fetchImpl: typeof fetch,
+  headers: Record<string, string>,
+): Promise<ShellRelease | null> {
   try {
     const response = await fetchImpl(`${githubApiBase()}/repos/${REPO}/releases?per_page=${RELEASE_SCAN}`, {
-      headers: {
-        accept: 'application/vnd.github+json',
-        // GitHub rejects a request with no User-Agent.
-        'user-agent': 'kabmo-console',
-      },
+      headers: { accept: 'application/vnd.github+json', ...headers },
     });
-    if (!response.ok) return cache.entry ?? null;
+    if (!response.ok) return null;
 
     const body = (await response.json()) as unknown;
     // A body that is not the release list is a failed probe, not an empty
-    // repository: answering `{url: null, latest: null}` here would be
-    // indistinguishable from "no release carries an artifact", and the caller
-    // would cache that mistake for five minutes.
-    if (!Array.isArray(body)) return cache.entry ?? null;
+    // repository: answering `{url: null, …}` here would be indistinguishable
+    // from "no release carries an artifact".
+    if (!Array.isArray(body)) return null;
 
     // Drafts are not published and prereleases are not what a console offers an
-    // installed shell — the same two the `latest` endpoint excluded.
+    // installed shell.
     const published = body.filter(
       (entry): entry is Record<string, unknown> =>
         entry !== null && typeof entry === 'object' && entry.draft !== true && entry.prerelease !== true,
     );
 
     const release = published
-      .map((entry) => ({ entry, asset: shellAsset(kind, entry.assets) }))
+      .map((entry) => ({ entry, asset: shellAsset(kind, arch, entry.assets) }))
       .find((candidate) => candidate.asset !== null);
 
-    if (!release?.asset) {
-      const fallback: ShellRelease = { url: null, latest: null, releaseUrl: null };
-      cache.entry = fallback;
-      cache.at = now;
-      return fallback;
-    }
+    if (!release?.asset) return EMPTY_RELEASE;
 
-    const resolved: ShellRelease = {
-      url: typeof release.asset.browser_download_url === 'string' ? release.asset.browser_download_url : null,
-      latest: versionFromAssetName(kind, String(release.asset.name)),
+    return resolvedRelease(kind, arch, {
+      name: String(release.asset.name),
+      downloadUrl:
+        typeof release.asset.browser_download_url === 'string' ? release.asset.browser_download_url : null,
       releaseUrl: typeof release.entry.html_url === 'string' ? release.entry.html_url : null,
-    };
-
-    cache.entry = resolved;
-    cache.at = now;
-    return resolved;
+    });
   } catch {
-    // Keep the last good answer rather than replacing it with a failure: a
-    // momentary outage must not remove a download button that was valid.
-    return cache.entry ?? null;
+    return null;
   }
 }
 
-/** How many releases to look back through for the artifact. */
-const RELEASE_SCAN = 20;
+/** The public-pages read, wrapped so a failure is the caller's `null`. */
+async function readFromPages(
+  kind: ShellKind,
+  arch: ShellArch | null,
+  fetchImpl: typeof fetch,
+  headers: Record<string, string>,
+): Promise<ShellRelease | null> {
+  try {
+    const found = await findAssetInPages(kind, fetchImpl, headers, arch);
+    if (found.kind === 'unreachable') return null;
+    if (found.kind === 'none') return EMPTY_RELEASE;
+    return resolvedRelease(kind, arch, { ...found.asset, releaseUrl: found.releaseUrl });
+  } catch {
+    return null;
+  }
+}
 
 /**
  * The asset of a release that names this shell's artifact, or null.
  *
- * The CURRENT scheme wins over the legacy one, and that is not cosmetic. A
- * release that carries both — which happens the moment a rename lands and
- * `--clobber` has not yet replaced the old asset, or a hand-upload adds one
- * beside the other — would otherwise resolve to whichever the asset list
- * happened to order first. Measured: a release holding both
- * `kabmo-android-v0.4.0.apk` and `Kabmo-0.6.0-android.apk` answered `0.4.0`,
- * i.e. the console offered an update to a version it already had and hid the
- * newer one.
+ * Two questions, in this order:
  *
- * Both schemes are still ACCEPTED (a release with only the old spelling must
- * keep working), so the preference is a second pass rather than a filter.
+ * 1. **Does an architecture match?** When the caller named one, the only
+ *    acceptable asset is the file that machine installs (`selfUpdateArtifact`).
+ *    Everything else in the release — the other architecture, the `.dmg`, a
+ *    `.deb` — is skipped, and the next release is tried.
+ * 2. **Which spelling?** The CURRENT scheme wins over the legacy one, and that
+ *    is not cosmetic. A release that carries both — which happens the moment a
+ *    rename lands and `--clobber` has not yet replaced the old asset, or a
+ *    hand-upload adds one beside the other — would otherwise resolve to
+ *    whichever the asset list happened to order first. Measured: a release
+ *    holding both `kabmo-android-v0.4.0.apk` and `Kabmo-0.6.0-android.apk`
+ *    answered `0.4.0`, i.e. the console offered an update to a version it
+ *    already had and hid the newer one.
  */
-function shellAsset(kind: ShellKind, assets: unknown): Record<string, unknown> | null {
+function shellAsset(
+  kind: ShellKind,
+  arch: ShellArch | null,
+  assets: unknown,
+): Record<string, unknown> | null {
   if (!Array.isArray(assets)) return null;
 
   const named = assets.filter(
@@ -213,70 +225,38 @@ function shellAsset(kind: ShellKind, assets: unknown): Record<string, unknown> |
       versionFromAssetName(kind, String((entry as Record<string, unknown>).name)) !== null,
   );
 
-  const { prefix, extension } = SHELL_ASSETS[kind];
-  return (
-    named.find((asset) => {
-      const name = String(asset.name);
-      return name.startsWith(prefix) && name.endsWith(extension);
-    }) ??
-    named[0] ??
-    null
-  );
-}
-
-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';
-}
+  if (arch) {
+    const exact = named.find(
+      (asset) => selfUpdateArtifact(kind, arch, String(asset.name)) !== null,
+    );
+    if (exact) return exact;
+  }
 
-interface CacheSlot {
-  entry: ShellRelease | null;
-  at: number;
+  return named.find((asset) => SHELL_ASSETS[kind].current.test(String(asset.name))) ?? named[0] ?? null;
 }
 
-type ShellCacheHost = typeof globalThis & {
-  __kabmoShellRelease?: Partial<Record<ShellKind, CacheSlot>>;
-};
-
 /**
- * The cache slot for one shell.
+ * Turn one resolved asset into the payload.
  *
- * PER SHELL, not one shared slot: both probes read the same release list but
- * resolve different assets, so one slot would make the second shell answer with
- * the first one's artifact.
+ * `direct` is derived from the SAME decision that chose the asset: an arch was
+ * named and the asset is that arch's self-update file. Deriving it separately —
+ * from `directDownload`, or from the platform — is how the client ends up
+ * offering an install for a release page.
  */
-function cacheSlot(kind: ShellKind): CacheSlot {
-  const host = globalThis as ShellCacheHost;
-  host.__kabmoShellRelease ??= {};
-  host.__kabmoShellRelease[kind] ??= { entry: null, at: 0 };
-  return host.__kabmoShellRelease[kind] as CacheSlot;
-}
+function resolvedRelease(
+  kind: ShellKind,
+  arch: ShellArch | null,
+  asset: { name: string; downloadUrl: string | null; releaseUrl: string | null },
+): ShellRelease {
+  const installable = arch !== null && selfUpdateArtifact(kind, arch, asset.name) !== null;
+  const direct = SHELL_ASSETS[kind].directDownload || installable;
 
-/**
- * Drop the cached answer for one shell (or every shell, with no argument).
- *
- * 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 resetShellReleaseCache(kind?: ShellKind): void {
-  const host = globalThis as ShellCacheHost;
-  if (!kind) {
-    host.__kabmoShellRelease = {};
-    return;
-  }
-  host.__kabmoShellRelease ??= {};
-  host.__kabmoShellRelease[kind] = { entry: null, at: 0 };
+  return {
+    // A per-arch desktop build cannot be named without an architecture — see
+    // the module comment — so the link is the page that lists every one.
+    url: direct ? asset.downloadUrl : asset.releaseUrl,
+    latest: versionFromAssetName(kind, asset.name),
+    releaseUrl: asset.releaseUrl,
+    direct: direct && asset.downloadUrl !== null,
+  };
 }

package/src/server/routes/fs/action-create.test.ts

@@ -6,12 +6,12 @@
 /**
  * The Files panel's "New file" branch.
  *
- * Two rules are load-bearing and neither is visible from the happy path: the
- * name may not carry a path separator (the folder is named by `path`, and a
- * separator would turn a name into an arbitrary write under the root), and an
- * existing file is REFUSED rather than truncated. The second one is the one a
- * naive `Bun.write` gets wrong: `Bun.write` creates or truncates, so a name
- * that collides with a real file would silently blank it.
+ * Two rules are load-bearing and neither is visible from the happy path. The
+ * name may carry SEGMENTS (that is the nested-path grammar, and its refusals
+ * live in `action-nested.test.ts`), and an existing file is REFUSED rather
+ * than truncated — the second is the one a naive `Bun.write` gets wrong:
+ * `Bun.write` creates or truncates, so a name that collides with a real file
+ * would silently blank it.
  */
 
 import { afterEach, describe, expect, test } from 'bun:test';
@@ -34,7 +34,10 @@ async function create(folderPath: string, name: string) {
   form.append('path', folderPath);
   form.append('name', name);
   const res = await action({ request: new Request('http://localhost/api/fs/action', { method: 'POST', body: form }) } as never);
-  return { status: res.status, body: (await res.json()) as { success?: boolean; path?: string; error?: string } };
+  return {
+    status: res.status,
+    body: (await res.json()) as { success?: boolean; kind?: string; path?: string; error?: string },
+  };
 }
 
 describe('fs create', () => {
@@ -43,7 +46,7 @@ describe('fs create', () => {
     const { status, body } = await create('tmp-create-probe', 'notes.md');
 
     expect(status).toBe(200);
-    expect(body).toEqual({ success: true, path: 'tmp-create-probe/notes.md' });
+    expect(body).toEqual({ success: true, kind: 'file', path: 'tmp-create-probe/notes.md' });
     expect(fs.readFileSync(path.join(DIR, 'notes.md'), 'utf8')).toBe('');
   });
 
@@ -67,12 +70,14 @@ describe('fs create', () => {
     expect(fs.readFileSync(path.join(DIR, 'keep.txt'), 'utf8')).toBe('important');
   });
 
-  test('refuses a name carrying a path separator', async () => {
+  test('a path separator is a NESTED path, and `..` is still refused', async () => {
     fs.mkdirSync(DIR, { recursive: true });
-    for (const name of ['../escape.txt', 'sub/escape.txt', 'sub\\escape.txt']) {
-      const { status } = await create('tmp-create-probe', name);
-      expect(status).toBe(400);
-    }
+    // A forward or back separator names a nested destination, which the dialog
+    // is for — the escape itself is the `..` segment, and that stays refused.
+    expect((await create('tmp-create-probe', 'sub/inside.txt')).status).toBe(200);
+    expect((await create('tmp-create-probe', 'sub\\also-inside.txt')).status).toBe(200);
+    expect((await create('tmp-create-probe', '../escape.txt')).status).toBe(400);
+    expect(fs.existsSync(path.join(DIR, 'sub/inside.txt'))).toBe(true);
     expect(fs.existsSync(path.join(process.cwd(), 'escape.txt'))).toBe(false);
   });