@bygghammar/cms-platform 0.92.2 → 0.94.0

package/src/admin/version-core.ts

@@ -1,10 +1,23 @@
 /**
- * Build metadata and platform release history for the version screen.
+ * Build metadata, release identity and package update checks for the version
+ * screen — the server half.
  *
  * The build constants are injected by the site's Vite config (they must be, the
- * values only exist at build time); reading them defensively and fetching the
- * package's published releases is identical everywhere, so it lives here.
+ * values only exist at build time); reading them defensively, reading the
+ * release identity from the runtime, and comparing installed first-party
+ * packages with the public registry is identical everywhere, so it lives here.
+ * The data contract and update policy are in `./version-report`.
  */
+import { CMS_MODULE_LIST } from "../config/modules";
+import { createRegistryClient, type RegistryClient } from "./registry-metadata";
+import { isPrerelease, parseSemver } from "./semver";
+import {
+  evaluatePackageUpdate,
+  type PackageReport,
+  type ReleaseHistoryEntry,
+  type ReleaseIdentity,
+  type VersionReport,
+} from "./version-report";
 
 export type BuildInfo = {
   appVersion: string;
@@ -25,12 +38,22 @@ export type BuildConstants = {
   buildTime?: unknown;
   platformVersion?: unknown;
   platformRange?: unknown;
+  /**
+   * Installed first-party packages, read by the host build from its installed
+   * dependency tree: `[{ name, installed, declared, requiredByCms }]`.
+   */
+  packages?: unknown;
 };
 
 const text = (value: unknown, fallback: string): string =>
   typeof value === "string" && value ? value : fallback;
 
-/** Normalize the injected build constants into a complete `BuildInfo`. */
+/**
+ * Normalize the injected build constants into a complete `BuildInfo`.
+ *
+ * Kept for hosts that still read the original shape. Its fallbacks fill gaps
+ * with placeholders, so the version screen itself reads `buildVersionReport`.
+ */
 export function readBuildInfoFrom(constants: BuildConstants): BuildInfo {
   return {
     appVersion: text(constants.appVersion, "0.0.0"),
@@ -43,34 +66,219 @@ export function readBuildInfoFrom(constants: BuildConstants): BuildInfo {
 /** The npm package name of the shared CMS platform. */
 export const PLATFORM_PACKAGE = "@bygghammar/cms-platform";
 
+/**
+ * Every package the server may look up in the public registry: the CMS
+ * package and the first-party packages modules declare. Fixed in code; a
+ * request can never add to it.
+ */
+export const FIRST_PARTY_PACKAGES: readonly string[] = [
+  PLATFORM_PACKAGE,
+  ...new Set(CMS_MODULE_LIST.flatMap((m) => (m.package ? [m.package] : []))),
+];
+
+let sharedClient: RegistryClient | null = null;
+
+/** The process-wide registry client, created on first use. */
+export function platformRegistryClient(): RegistryClient {
+  sharedClient ??= createRegistryClient({ allowlist: FIRST_PARTY_PACKAGES });
+  return sharedClient;
+}
+
+type Env = Record<string, string | undefined>;
+
+const COMMIT_SHA = /^[0-9a-f]{40}$/;
+const RELEASE_LABEL = /^[0-9A-Za-z][0-9A-Za-z._-]{0,63}$/;
+
+/**
+ * The deployed release, from the same runtime variables the health endpoint
+ * reports (`APP_VERSION`, then `VITE_PUBLIC_APP_VERSION`). The site's
+ * `package.json` version is not a release identity and is never used here.
+ */
+export function readReleaseIdentity(env: Env = process.env): ReleaseIdentity {
+  for (const source of ["APP_VERSION", "VITE_PUBLIC_APP_VERSION"]) {
+    const raw = (env[source] ?? "").trim();
+    if (!raw || raw.toLowerCase() === "unknown") continue;
+    if (COMMIT_SHA.test(raw)) return { value: raw, kind: "commit", source, unrecognized: false };
+    if (RELEASE_LABEL.test(raw)) return { value: raw, kind: "label", source, unrecognized: false };
+    return { value: null, kind: null, source, unrecognized: true };
+  }
+  return { value: null, kind: null, source: null, unrecognized: false };
+}
+
+/**
+ * The environment name (`SITE_ENV`) and public hostname (`SITE_URL`), each only
+ * when it has a plain, expected form. Nothing else from the environment is read.
+ */
+export function readEnvironment(env: Env = process.env): VersionReport["environment"] {
+  const rawName = (env["SITE_ENV"] ?? "").trim().toLowerCase();
+  const name = /^[a-z][a-z0-9_-]{0,31}$/.test(rawName) ? rawName : null;
+  let origin: string | null = null;
+  try {
+    const url = new URL((env["SITE_URL"] ?? "").trim());
+    if (url.protocol === "https:" || url.protocol === "http:") origin = url.hostname || null;
+  } catch {
+    origin = null;
+  }
+  return { name, origin };
+}
+
+function stringOrNull(value: unknown, max = 128): string | null {
+  return typeof value === "string" && value.trim() && value.length <= max ? value.trim() : null;
+}
+
+function isoOrNull(value: unknown): string | null {
+  if (typeof value !== "string" || !value) return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
+}
+
+type InstalledEntry = {
+  installed: string | null;
+  declared: string | null;
+  requiredByCms: string | null;
+};
+
+/** The injected package list, keyed by name, allowlisted packages only. */
+export function readInstalledPackages(constants: BuildConstants): Map<string, InstalledEntry> {
+  const out = new Map<string, InstalledEntry>();
+  if (Array.isArray(constants.packages)) {
+    for (const item of constants.packages as unknown[]) {
+      if (typeof item !== "object" || item === null) continue;
+      const rec = item as Record<string, unknown>;
+      const name = rec["name"];
+      if (typeof name !== "string" || !FIRST_PARTY_PACKAGES.includes(name)) continue;
+      out.set(name, {
+        installed: stringOrNull(rec["installed"]),
+        declared: stringOrNull(rec["declared"]),
+        requiredByCms: stringOrNull(rec["requiredByCms"]),
+      });
+    }
+  }
+  // Hosts built before the package list existed still inject the CMS version.
+  if (!out.has(PLATFORM_PACKAGE)) {
+    const version = stringOrNull(constants.platformVersion);
+    out.set(PLATFORM_PACKAGE, {
+      installed: version === "unknown" ? null : version,
+      declared: stringOrNull(constants.platformRange) === "unknown" ? null : stringOrNull(constants.platformRange),
+      requiredByCms: null,
+    });
+  }
+  return out;
+}
+
+export type VersionReportOptions = {
+  constants: BuildConstants;
+  /** Runtime environment; defaults to `process.env`. */
+  env?: Env;
+  /** Ask the registry again now, subject to the client's minimum interval. */
+  refresh?: boolean;
+  /**
+   * When this release went live — only from real evidence the host holds.
+   * Omit when nothing records it; the screen then says it was not recorded.
+   */
+  deployedAt?: string | null;
+  /** How many recent CMS publications to list. Default 5. */
+  historyLimit?: number;
+  registry?: RegistryClient;
+  now?: () => Date;
+};
+
+/** Assemble the version screen's report. Never throws for registry trouble. */
+export async function buildVersionReport(options: VersionReportOptions): Promise<VersionReport> {
+  const registry = options.registry ?? platformRegistryClient();
+  const now = options.now ?? (() => new Date());
+  const installed = readInstalledPackages(options.constants);
+
+  const rows: { name: string; role: PackageReport["role"] }[] = [
+    { name: PLATFORM_PACKAGE, role: "cms" },
+    ...FIRST_PARTY_PACKAGES.filter((n) => n !== PLATFORM_PACKAGE).map((name) => ({
+      name,
+      role: "module" as const,
+    })),
+  ];
+
+  const lookups = await Promise.all(
+    rows.map((row) => registry.lookup(row.name, { refresh: options.refresh === true })),
+  );
+
+  const packages: PackageReport[] = rows.map((row, i) => {
+    const entry = installed.get(row.name);
+    const lookup = lookups[i]!;
+    return {
+      name: row.name,
+      role: row.role,
+      installed: entry?.installed ?? null,
+      declared: entry?.declared ?? null,
+      requiredByCms: row.role === "module" ? (entry?.requiredByCms ?? null) : null,
+      registry: lookup.check,
+      update: evaluatePackageUpdate(entry?.installed ?? null, lookup.metadata),
+    };
+  });
+
+  const cms = packages[0]!;
+  const cmsMetadata = lookups[0]!.metadata;
+  const cmsInstalled = parseSemver(cms.installed);
+  const releaseHistory: ReleaseHistoryEntry[] = cmsMetadata
+    ? Object.entries(cmsMetadata.versions)
+        .filter(([, v]) => v.publishedAt !== null)
+        .map(([version, v]) => {
+          const sv = parseSemver(version);
+          return {
+            version,
+            publishedAt: v.publishedAt,
+            prerelease: sv ? isPrerelease(sv) : false,
+            current: cmsInstalled !== null && cmsInstalled.version === version,
+          };
+        })
+        .sort((a, b) => ((a.publishedAt ?? "") < (b.publishedAt ?? "") ? 1 : -1))
+        .slice(0, options.historyLimit ?? 5)
+    : [];
+
+  const nextAttempts = rows
+    .map((row) => registry.nextAttemptAt(row.name))
+    .filter((t): t is number => t !== null);
+
+  return {
+    schemaVersion: 1,
+    generatedAt: now().toISOString(),
+    release: readReleaseIdentity(options.env),
+    environment: readEnvironment(options.env),
+    builtAt: isoOrNull(options.constants.buildTime),
+    deployedAt: isoOrNull(options.deployedAt),
+    packages,
+    releaseHistory,
+    nextCheckAllowedAt: nextAttempts.length ? new Date(Math.max(...nextAttempts)).toISOString() : null,
+  };
+}
+
+/** The legacy release list, derived from a report's history (newest publication first). */
+export function releasesFromReport(report: VersionReport, limit = 3): PlatformRelease[] {
+  return report.releaseHistory.slice(0, limit).map((r) => ({
+    version: r.version,
+    publishedAt: r.publishedAt,
+    current: r.current,
+  }));
+}
+
 /**
  * The most recent published platform releases, newest first.
  *
  * Network failures are not an error worth surfacing on an information screen —
- * the screen still shows the running version from the build constants.
+ * the screen still shows the running version from the build constants. Reads
+ * through the shared bounded, cached registry client.
  */
 export async function fetchPlatformReleases(
   currentVersion: string,
   limit = 3,
 ): Promise<PlatformRelease[]> {
-  try {
-    const res = await fetch(
-      `https://registry.npmjs.org/${PLATFORM_PACKAGE.replace("/", "%2F")}`,
-      { headers: { accept: "application/json" } },
-    );
-    if (!res.ok) return [];
-    const json = (await res.json()) as { time?: Record<string, string> };
-    const time = json.time ?? {};
-    return Object.entries(time)
-      .filter(([v]) => v !== "created" && v !== "modified")
-      .map(([version, publishedAt]) => ({
-        version,
-        publishedAt,
-        current: version === currentVersion,
-      }))
-      .sort((a, b) => (a.publishedAt < b.publishedAt ? 1 : -1))
-      .slice(0, limit);
-  } catch {
-    return [];
-  }
+  const { metadata } = await platformRegistryClient().lookup(PLATFORM_PACKAGE);
+  if (!metadata) return [];
+  return Object.entries(metadata.versions)
+    .map(([version, v]) => ({
+      version,
+      publishedAt: v.publishedAt,
+      current: version === currentVersion,
+    }))
+    .sort((a, b) => ((a.publishedAt ?? "") < (b.publishedAt ?? "") ? 1 : -1))
+    .slice(0, limit);
 }

package/src/admin/version-report.ts

@@ -0,0 +1,295 @@
+/**
+ * The version screen's data contract, and the update policy it is judged by.
+ *
+ * Neutral on purpose: the server builds a `VersionReport` (see `version-core`)
+ * and the backoffice renders it, so the types and the pure decisions live here,
+ * in a module both sides may import. Nothing in this file reads the network,
+ * the environment or the database.
+ *
+ * Update policy, stated once:
+ *
+ * - Versions are ordered by semver precedence, never as strings and never by
+ *   publication date.
+ * - A release install (`0.93.0`) follows the **stable** channel: the newest
+ *   published, non-deprecated release version. Prereleases never count as
+ *   updates for it, whatever their dist-tag.
+ * - A prerelease install (`0.2.0-m7.9`) follows its **prerelease line**: the
+ *   same `major.minor.patch` and first prerelease identifier (`0.2.0-m7`).
+ *   Being the newest of that line is reported as "prerelease installed", not
+ *   "up to date". A newer stable release, if one exists, is reported beside it
+ *   as advisory information, never as the line's update.
+ * - An installed version the registry does not list is "not published" or
+ *   "ahead of registry"; an unknown or unparseable installed version, or no
+ *   registry answer at all, is never called up to date.
+ */
+import { compareSemver, isPrerelease, parseSemver, prereleaseLine, type SemVer } from "./semver";
+
+/** One published version, as the registry describes it. */
+export type RegistryVersion = {
+  readonly publishedAt: string | null;
+  readonly deprecated: boolean;
+};
+
+/** The subset of registry metadata the version screen uses. */
+export type RegistryMetadata = {
+  readonly distTags: Readonly<Record<string, string>>;
+  /** Keyed by normalized version (`major.minor.patch[-prerelease]`). */
+  readonly versions: Readonly<Record<string, RegistryVersion>>;
+};
+
+/** Fixed, non-sensitive reasons a registry lookup did not produce metadata. */
+export type RegistryError =
+  | "timeout"
+  | "network"
+  | "http"
+  | "not-found"
+  | "malformed"
+  | "too-large"
+  | "not-allowed";
+
+/**
+ * `fresh`: the most recent attempt succeeded, within the cache lifetime.
+ * `stale`: an older successful answer is being shown, because the most recent
+ * attempt failed (see `error`) or the answer outlived the cache lifetime; it is
+ * cached, not re-verified. `unavailable`: no successful answer is held.
+ */
+export type RegistryCheckState = "fresh" | "stale" | "unavailable";
+
+export type RegistryCheck = {
+  readonly state: RegistryCheckState;
+  /** When the registry last answered with usable metadata (ISO 8601). */
+  readonly lastSuccessAt: string | null;
+  /** When the most recent lookup was attempted, successful or not (ISO 8601). */
+  readonly lastAttemptAt: string | null;
+  /** Why the most recent attempt failed, if it did. */
+  readonly error: RegistryError | null;
+};
+
+export type UpdateStatus =
+  | "up-to-date"
+  | "update-available"
+  | "prerelease-current"
+  | "check-unavailable"
+  | "not-published"
+  | "ahead-of-registry"
+  | "installed-unknown"
+  | "installed-invalid";
+
+export type UpdateChannel = { kind: "stable" } | { kind: "prerelease"; line: string };
+
+export type PublishedVersion = { version: string; publishedAt: string | null };
+
+export type PackageUpdate = {
+  readonly status: UpdateStatus;
+  readonly channel: UpdateChannel | null;
+  /** Publication date of the installed version, when the registry lists it. */
+  readonly installedPublishedAt: string | null;
+  readonly installedDeprecated: boolean;
+  /** Newest published, non-deprecated version in the installed version's channel. */
+  readonly latestInChannel: PublishedVersion | null;
+  /** For a prerelease install: the newest stable release newer than it. Advisory only. */
+  readonly newerStable: PublishedVersion | null;
+  /** Registry dist-tags that currently point at the installed version. */
+  readonly installedTags: readonly string[];
+};
+
+export type PackageRole = "cms" | "module";
+
+/** One first-party package as installed in this build, with its registry verdict. */
+export type PackageReport = {
+  readonly name: string;
+  readonly role: PackageRole;
+  /** Exact version in the build's installed dependency tree. */
+  readonly installed: string | null;
+  /** What the site's own manifest declares for it (a range or exact version). */
+  readonly declared: string | null;
+  /** The range the installed CMS package declares for it, for module packages. */
+  readonly requiredByCms: string | null;
+  readonly registry: RegistryCheck;
+  readonly update: PackageUpdate;
+};
+
+export type ReleaseIdentity = {
+  /** The deployed release, e.g. a full commit SHA. `null` when not reported. */
+  readonly value: string | null;
+  readonly kind: "commit" | "label" | null;
+  /** The runtime variable it was read from. */
+  readonly source: string | null;
+  /** True when a value was present but not in a recognised format (it is not echoed). */
+  readonly unrecognized: boolean;
+};
+
+export type ReleaseHistoryEntry = {
+  readonly version: string;
+  readonly publishedAt: string | null;
+  readonly prerelease: boolean;
+  readonly current: boolean;
+};
+
+export type VersionReport = {
+  readonly schemaVersion: 1;
+  /** When the server assembled this report (ISO 8601). */
+  readonly generatedAt: string;
+  readonly release: ReleaseIdentity;
+  readonly environment: { readonly name: string | null; readonly origin: string | null };
+  /** When the server bundle was built. Not a deployment time. */
+  readonly builtAt: string | null;
+  /** When this release went live, only if the host has real evidence of it. */
+  readonly deployedAt: string | null;
+  /** The CMS package first, then module packages. */
+  readonly packages: readonly PackageReport[];
+  /** Recent CMS package publications, newest publication first. */
+  readonly releaseHistory: readonly ReleaseHistoryEntry[];
+  /** The earliest time a manual "check again" will reach the registry (ISO 8601). */
+  readonly nextCheckAllowedAt: string | null;
+};
+
+type Published = { sv: SemVer; info: RegistryVersion };
+
+function maxOf(list: readonly Published[]): Published | null {
+  let best: Published | null = null;
+  for (const p of list) if (!best || compareSemver(p.sv, best.sv) > 0) best = p;
+  return best;
+}
+
+function asPublished(p: Published | null): PublishedVersion | null {
+  return p ? { version: p.sv.version, publishedAt: p.info.publishedAt } : null;
+}
+
+function inChannel(sv: SemVer, channel: UpdateChannel): boolean {
+  return channel.kind === "stable" ? !isPrerelease(sv) : prereleaseLine(sv) === channel.line;
+}
+
+const EMPTY_UPDATE = {
+  channel: null,
+  installedPublishedAt: null,
+  installedDeprecated: false,
+  latestInChannel: null,
+  newerStable: null,
+  installedTags: [],
+} as const;
+
+/** Judge one installed version against registry metadata, by the policy above. */
+export function evaluatePackageUpdate(
+  installedRaw: string | null | undefined,
+  metadata: RegistryMetadata | null | undefined,
+): PackageUpdate {
+  if (!installedRaw) return { ...EMPTY_UPDATE, status: "installed-unknown" };
+  const installed = parseSemver(installedRaw);
+  if (!installed) return { ...EMPTY_UPDATE, status: "installed-invalid" };
+
+  const line = prereleaseLine(installed);
+  const channel: UpdateChannel = line ? { kind: "prerelease", line } : { kind: "stable" };
+  if (!metadata) return { ...EMPTY_UPDATE, channel, status: "check-unavailable" };
+
+  const published: Published[] = [];
+  for (const [key, info] of Object.entries(metadata.versions)) {
+    const sv = parseSemver(key);
+    if (sv) published.push({ sv, info });
+  }
+  const own = published.find((p) => compareSemver(p.sv, installed) === 0) ?? null;
+  const live = published.filter((p) => !p.info.deprecated);
+  const latest = maxOf(live.filter((p) => inChannel(p.sv, channel)));
+  const installedTags = Object.entries(metadata.distTags)
+    .filter(([, v]) => {
+      const sv = parseSemver(v);
+      return sv !== null && compareSemver(sv, installed) === 0;
+    })
+    .map(([tag]) => tag)
+    .sort();
+  const newerStable =
+    channel.kind === "prerelease"
+      ? maxOf(live.filter((p) => !isPrerelease(p.sv) && compareSemver(p.sv, installed) > 0))
+      : null;
+
+  const common = {
+    channel,
+    installedPublishedAt: own?.info.publishedAt ?? null,
+    installedDeprecated: own?.info.deprecated ?? false,
+    latestInChannel: asPublished(latest),
+    newerStable: asPublished(newerStable),
+    installedTags,
+  };
+
+  if (!own) {
+    // Not in the registry: a local or unpublished build. It is "ahead" only
+    // when it is newer than everything published in its channel (or, with an
+    // empty channel, than everything published at all).
+    const reference = latest ?? maxOf(published);
+    const ahead = reference !== null && compareSemver(installed, reference.sv) > 0;
+    return { ...common, status: ahead ? "ahead-of-registry" : "not-published" };
+  }
+  if (latest && compareSemver(installed, latest.sv) < 0) {
+    return { ...common, status: "update-available" };
+  }
+  return { ...common, status: channel.kind === "stable" ? "up-to-date" : "prerelease-current" };
+}
+
+/** Statuses that should draw an administrator's attention beyond "an update exists". */
+const ATTENTION: ReadonlySet<UpdateStatus> = new Set([
+  "not-published",
+  "ahead-of-registry",
+  "installed-unknown",
+  "installed-invalid",
+]);
+
+export type UpdateSummaryKind =
+  | "updates-available"
+  | "attention"
+  | "up-to-date"
+  | "partial"
+  | "unavailable";
+
+export type UpdateSummary = {
+  readonly kind: UpdateSummaryKind;
+  readonly updates: readonly string[];
+  readonly prereleases: readonly string[];
+  readonly attention: readonly string[];
+  readonly unavailable: readonly string[];
+  /** Oldest "last successful check" across the packages, when every one has one. */
+  readonly checkedAt: string | null;
+  /** True when any package's registry answer is cached rather than current. */
+  readonly stale: boolean;
+  /** Packages whose most recent registry attempt failed. */
+  readonly failed: readonly string[];
+  /**
+   * True only when every package has a fresh answer from a successful most
+   * recent attempt. A verdict built on cached answers is not verified.
+   */
+  readonly verified: boolean;
+};
+
+/** One overall verdict for the summary banner. */
+export function summarizeUpdates(packages: readonly PackageReport[]): UpdateSummary {
+  const updates: string[] = [];
+  const prereleases: string[] = [];
+  const attention: string[] = [];
+  const unavailable: string[] = [];
+  for (const p of packages) {
+    const s = p.update.status;
+    if (s === "update-available") updates.push(p.name);
+    if (s === "prerelease-current" || (s === "update-available" && p.update.channel?.kind === "prerelease"))
+      prereleases.push(p.name);
+    if (ATTENTION.has(s) || p.update.installedDeprecated) attention.push(p.name);
+    if (s === "check-unavailable") unavailable.push(p.name);
+  }
+  const successes = packages.map((p) => p.registry.lastSuccessAt);
+  const checkedAt =
+    packages.length > 0 && successes.every((t): t is string => typeof t === "string")
+      ? successes.reduce((a, b) => (a < b ? a : b))
+      : null;
+  const stale = packages.some((p) => p.registry.state === "stale");
+  const failed = packages.filter((p) => p.registry.error !== null).map((p) => p.name);
+  const verified =
+    packages.length > 0 &&
+    packages.every((p) => p.registry.state === "fresh" && p.registry.error === null);
+
+  let kind: UpdateSummaryKind;
+  if (packages.length === 0 || unavailable.length === packages.length) kind = "unavailable";
+  else if (updates.length > 0) kind = "updates-available";
+  else if (attention.length > 0) kind = "attention";
+  else if (unavailable.length > 0) kind = "partial";
+  else kind = "up-to-date";
+
+  return { kind, updates, prereleases, attention, unavailable, checkedAt, stale, failed, verified };
+}