@bygghammar/cms-platform 0.93.0 → 0.95.0

package/src/admin/semver.ts

@@ -0,0 +1,111 @@
+/**
+ * Semantic Versioning 2.0.0 parsing and precedence.
+ *
+ * Package versions are compared by semver precedence, never as strings and
+ * never by publication date: `0.10.0` is newer than `0.9.0`, and a prerelease
+ * published after a stable release is not thereby newer than it. Build metadata
+ * (`+…`) is ignored for precedence, as the specification requires.
+ *
+ * Deliberately small and dependency-free: the version screen only needs to
+ * parse exact versions and order them. Ranges (`^1.2.0`, `>=0.2.0-m7.8`) are not
+ * evaluated here; they are shown to people as declared, not resolved.
+ */
+
+export type SemVer = {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+  /** Dot-separated prerelease identifiers; empty for a release version. */
+  readonly prerelease: readonly (string | number)[];
+  /** The normalized `major.minor.patch[-prerelease]`, without build metadata. */
+  readonly version: string;
+};
+
+const NUMERIC = /^(0|[1-9]\d*)$/;
+const IDENTIFIER = /^[0-9A-Za-z-]+$/;
+const PATTERN =
+  /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/;
+
+/** Parse an exact version. Returns `null` for anything that is not valid semver. */
+export function parseSemver(input: unknown): SemVer | null {
+  if (typeof input !== "string") return null;
+  const value = input.trim();
+  if (value.length === 0 || value.length > 256) return null;
+  const match = PATTERN.exec(value);
+  if (!match) return null;
+  const [, major, minor, patch, pre, build] = match;
+  const nums = [major, minor, patch].map(Number);
+  if (nums.some((n) => !Number.isSafeInteger(n))) return null;
+
+  const prerelease: (string | number)[] = [];
+  if (pre !== undefined) {
+    for (const part of pre.split(".")) {
+      if (!IDENTIFIER.test(part)) return null;
+      if (/^\d+$/.test(part)) {
+        // Numeric identifiers must not have leading zeroes.
+        if (!NUMERIC.test(part)) return null;
+        const n = Number(part);
+        if (!Number.isSafeInteger(n)) return null;
+        prerelease.push(n);
+      } else {
+        prerelease.push(part);
+      }
+    }
+  }
+  if (build !== undefined && build.split(".").some((part) => !IDENTIFIER.test(part))) return null;
+
+  const [ma, mi, pa] = nums as [number, number, number];
+  return {
+    major: ma,
+    minor: mi,
+    patch: pa,
+    prerelease,
+    version: `${ma}.${mi}.${pa}${prerelease.length ? `-${prerelease.join(".")}` : ""}`,
+  };
+}
+
+function compareIdentifiers(a: string | number, b: string | number): number {
+  const an = typeof a === "number";
+  const bn = typeof b === "number";
+  if (an && bn) return a === b ? 0 : a < b ? -1 : 1;
+  // Numeric identifiers always have lower precedence than alphanumeric ones.
+  if (an) return -1;
+  if (bn) return 1;
+  return a === b ? 0 : a < b ? -1 : 1;
+}
+
+/** Semver precedence: negative when `a` is older than `b`, positive when newer. */
+export function compareSemver(a: SemVer, b: SemVer): number {
+  if (a.major !== b.major) return a.major < b.major ? -1 : 1;
+  if (a.minor !== b.minor) return a.minor < b.minor ? -1 : 1;
+  if (a.patch !== b.patch) return a.patch < b.patch ? -1 : 1;
+  const ap = a.prerelease;
+  const bp = b.prerelease;
+  // A release version has higher precedence than any of its prereleases.
+  if (ap.length === 0 || bp.length === 0) {
+    if (ap.length === bp.length) return 0;
+    return ap.length === 0 ? 1 : -1;
+  }
+  for (let i = 0; i < Math.max(ap.length, bp.length); i += 1) {
+    if (i >= ap.length) return -1;
+    if (i >= bp.length) return 1;
+    const c = compareIdentifiers(ap[i] as string | number, bp[i] as string | number);
+    if (c !== 0) return c;
+  }
+  return 0;
+}
+
+/** True when the version carries prerelease identifiers (`1.0.0-rc.1`). */
+export function isPrerelease(version: SemVer): boolean {
+  return version.prerelease.length > 0;
+}
+
+/**
+ * The prerelease line a version belongs to: its `major.minor.patch` and first
+ * prerelease identifier, for example `0.2.0-m7` for `0.2.0-m7.9`. `null` for a
+ * release version.
+ */
+export function prereleaseLine(version: SemVer): string | null {
+  if (!isPrerelease(version)) return null;
+  return `${version.major}.${version.minor}.${version.patch}-${String(version.prerelease[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);
 }