feat(updates): a bundle says which core it needs, and is refused when it is below

The core, the Admin UI and the Player are three artefacts on three release
cadences, each behind its own button, pressed in whatever order somebody
chooses. Nothing related them. A console built against endpoints this core
does not have installed onto it without a word, and the result is not an
error anyone sees — a page that renders and then quietly 404s.

Two mechanisms, with different jobs.

The channel decides the ordinary case. Web bundles had none: both the fetch
scripts and the in-place update used `releases/latest/download/...`, and that
endpoint never resolves to a prerelease — so a beta bundle could not reach a
beta install at all, and every UI change had to ship as a stable release that
then also landed on installs still running 3.1.0. Bundles now follow the
channel of the core serving them, with stables still eligible behind the
prereleases, because these repos may publish none. Within the channel the
newest release whose `minCore` this core satisfies wins, so an install on an
older core receives the last bundle built for it rather than a dead button.
Release manifests are published beside the tarball so that choice costs one
small JSON per candidate instead of a download.

`minCore` is the backstop. Each bundle states the oldest core that can serve
it, and the update preflight reads it out of the staging directory before the
swap — nothing has moved yet, so a refusal costs nothing and rolls nothing
back. 409 rather than 500: the install was declined, the previous bundle is
untouched, and the fix is to update the core first.

Both fields are open on unknowns. A bundle that states no minimum is every
bundle released before today, and a core reporting `dev` is a working copy;
neither may be gated.

Alongside:

- `shared/semver.ts` replaces a comparator that split on `[.-]` and so read
  `4.0.0` as older than its own `4.0.0-beta.21`. Harmless while it only
  ordered speaker builds; wrong the moment it decides an install, and this
  project has spent its whole 4.0 cycle on prereleases.
- `/info` reports both bundles with whether they fit, added beside `player`
  rather than replacing it: an Admin UI older than this server has to keep
  reading what it always read. It also reports what this core asks of its
  bundles, which cannot be enforced — a console too old to serve is already
  the one rendering the page — only said.
- The prerelease lookup swallowed nothing, so a repo answering 404 would have
  rejected under the shared `Promise.all` and nulled every version in the
  batch. It now propagates only a refusal, which is what tells the cache to
  keep what it knew.
- One listing per repo answers both "newest release" and "newest prerelease",
  so covering three repos instead of one costs no more of the hourly budget
  than before.

Author: rudyberends

package.json

@@ -8,6 +8,10 @@
     "url": "git+https://github.com/sonn-audio/core.git"
   },
   "main": "dist/server.js",
+  "sonn": {
+    "minAdminUi": null,
+    "minPlayer": null
+  },
   "_moduleAliases": {
     "@": "dist"
   },

scripts/bundleCompat.mjs

@@ -0,0 +1,114 @@
+/**
+ * The build-time half of the bundle compatibility check.
+ *
+ * `fetch:admin` and `fetch:player` pull whatever release the bundle repos call latest, into
+ * a core checked out at whatever version it happens to be. Nothing compared the two, so a
+ * console built against endpoints this core does not have could be baked straight into a
+ * release image — the one place a mismatch is fully preventable, and the one where it is
+ * hardest to notice afterwards.
+ *
+ * Deliberately a hard failure rather than a warning. The asymmetry is what makes that safe:
+ * it can only fire when the *bundle* is ahead of the core being built, never when the core
+ * is ahead of the bundle, so an ordinary release — core moves first, bundles follow — never
+ * sees it. `SONN_SKIP_BUNDLE_COMPAT=1` is there for the deliberate exception.
+ *
+ * A plain `.mjs` duplicate of `src/shared/semver.ts` on purpose: these scripts run before
+ * `tsc` has produced `dist/`, so they cannot import the compiled module they mirror. The
+ * behaviour is pinned on the TypeScript side by `tests/bundleCompat.test.ts`.
+ */
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+
+function parseVersion(input) {
+  const trimmed = String(input ?? '').trim().replace(/^v/i, '');
+  if (!trimmed) return null;
+  const [withoutBuild] = trimmed.split('+', 1);
+  const [core, pre] = (withoutBuild ?? '').split('-', 2);
+  const parts = (core ?? '').split('.').map((part) => Number.parseInt(part.replace(/\D+.*$/, ''), 10));
+  if (parts.length === 0 || parts.some((part) => Number.isNaN(part))) return null;
+  while (parts.length < 3) parts.push(0);
+  return { parts, prerelease: pre ? pre.trim() : null };
+}
+
+function comparePrerelease(a, b) {
+  if (!a && !b) return 0;
+  if (!a) return 1;
+  if (!b) return -1;
+  const left = a.split('.');
+  const right = b.split('.');
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const l = left[i];
+    const r = right[i];
+    if (l === undefined) return -1;
+    if (r === undefined) return 1;
+    if (l === r) continue;
+    const lNum = /^\d+$/.test(l);
+    const rNum = /^\d+$/.test(r);
+    if (lNum && rNum) {
+      if (Number(l) < Number(r)) return -1;
+      if (Number(l) > Number(r)) return 1;
+      continue;
+    }
+    if (lNum && !rNum) return -1;
+    if (!lNum && rNum) return 1;
+    return l < r ? -1 : 1;
+  }
+  return 0;
+}
+
+export function compareVersions(a, b) {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  if (!left || !right) return 0;
+  for (let i = 0; i < Math.max(left.parts.length, right.parts.length); i += 1) {
+    const l = left.parts[i] ?? 0;
+    const r = right.parts[i] ?? 0;
+    if (l < r) return -1;
+    if (l > r) return 1;
+  }
+  return comparePrerelease(left.prerelease, right.prerelease);
+}
+
+/** Open on both unknowns: a bundle that states nothing, and a core that cannot be read. */
+export function satisfiesMin(running, minimum) {
+  const min = String(minimum ?? '').trim();
+  const have = String(running ?? '').trim();
+  if (!min || !have) return true;
+  if (!parseVersion(min) || !parseVersion(have)) return true;
+  return compareVersions(have, min) >= 0;
+}
+
+export async function readCoreVersion(cwd) {
+  try {
+    const pkg = JSON.parse(await fs.readFile(join(cwd, 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Throws when the bundle now sitting in `dir` needs a newer core than this one.
+ *
+ * Reads the manifest the bundle build emits; a directory without one is a release from
+ * before manifests existed and passes, which is what keeps this from breaking every
+ * existing install the day it lands.
+ */
+export async function assertBundleFitsCore(dir, coreVersion, label) {
+  if ((process.env.SONN_SKIP_BUNDLE_COMPAT ?? '').trim() === '1') return;
+  let manifest;
+  try {
+    manifest = JSON.parse(await fs.readFile(join(dir, 'version.json'), 'utf8'));
+  } catch {
+    return;
+  }
+  const minCore = typeof manifest?.minCore === 'string' ? manifest.minCore.trim() : '';
+  if (!minCore || satisfiesMin(coreVersion, minCore)) return;
+
+  const version = typeof manifest?.version === 'string' ? manifest.version : 'unknown';
+  throw new Error(
+    `${label} ${version} requires server core ${minCore}, but this checkout is ${coreVersion}.\n` +
+      `       Pin an older bundle (e.g. ADMINUI_RELEASE / PLAYER_RELEASE=vX.Y.Z), bump the core,\n` +
+      `       or set SONN_SKIP_BUNDLE_COMPAT=1 if you know this pairing is fine.`,
+  );
+}

scripts/fetch-admin-dist.mjs

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { spawn } from 'node:child_process';
 import https from 'node:https';
+import { assertBundleFitsCore, readCoreVersion } from './bundleCompat.mjs';
 
 const repo = 'sonn-audio/adminui';
 const assetName = 'admin-dist.tgz';
@@ -103,3 +104,7 @@ if (await hasLocalAdminUi()) {
   await extract(archivePath, targetDir);
   await fs.rm(archivePath, { force: true });
 }
+
+// After both paths, because a checked-in UI can outrun this core exactly as a downloaded
+// one can — and the local build is the case where it happens during development.
+await assertBundleFitsCore(targetDir, await readCoreVersion(process.cwd()), 'admin ui');

scripts/fetch-player-dist.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { pipeline } from 'node:stream/promises';
 import { spawn } from 'node:child_process';
 import https from 'node:https';
+import { assertBundleFitsCore, readCoreVersion } from './bundleCompat.mjs';
 
 const comingSoonHtml = join(dirname(fileURLToPath(import.meta.url)), 'player-coming-soon.html');
 
@@ -114,3 +115,9 @@ if (await hasLocalPlayer()) {
     await fs.copyFile(comingSoonHtml, join(targetDir, 'index.html'));
   }
 }
+
+// Outside the catch above on purpose. That fallback answers "there is no player to install",
+// and an incompatible one is a different thing: quietly swapping it for a placeholder would
+// turn a fixable version mismatch into a build that ships without a player and says so once,
+// in a warning nobody reads. The placeholder itself carries no manifest, so it passes here.
+await assertBundleFitsCore(targetDir, await readCoreVersion(process.cwd()), 'player');