@bygghammar/cms-platform 0.92.2 → 0.94.0

package/CHANGELOG.md

@@ -8,6 +8,99 @@ matches `package.json` exactly. See
 Versions 0.1.0 through 0.78.0 predate this repository and were reconstructed
 from the published npm tarballs.
 
+## 0.94.0
+
+- **The version screen shows what is actually deployed and installed.**
+  `/admin/version`, now "Version & modules", no longer labels the site's
+  `package.json` version as the "CMS build". It shows:
+  - the release identity from the runtime `APP_VERSION` (falling back to
+    `VITE_PUBLIC_APP_VERSION`, the values the health check reports), short,
+    in full and with a copy control, or "Unknown";
+  - the build time, labelled as such, and a deployment time only when the
+    host supplies real evidence; otherwise "Not recorded";
+  - the installed CMS package and module packages: installed and declared
+    versions, publication dates, the newest version in their channel and an
+    advisory status;
+  - every module from the module table, with its enabled status read from
+    the same saved settings as Site settings. A loading or failed settings
+    read is shown as such, never as the compiled defaults;
+  - recent CMS releases, and the packaged schema figures labelled as package
+    facts rather than a check of the live database.
+
+  The screen never changes settings.
+- **Update policy.** Versions are compared by semver precedence, not as
+  strings or by publication date.
+  - A release install follows stable releases.
+  - A prerelease install follows its prerelease line (`0.2.0-m7`) and is
+    reported as "Prerelease installed", not "Up to date".
+  - Unknown, malformed, unpublished or ahead-of-registry versions, and any
+    case without a registry answer, are never "Up to date".
+- **Registry reads are bounded and server-side.** `admin/registry-metadata`
+  looks up only the allowlisted first-party packages (the CMS package plus
+  packages named by modules) in the public npm registry:
+  - anonymous, refusing redirects, with a 5 s timeout and an 8 MiB cap;
+  - a 15-minute cache, and at most one attempt per package per minute,
+    manual "Check again" included;
+  - shared in-flight requests.
+
+  `fetchPlatformReleases` now goes through the same client.
+- **Failed checks are never shown as current.**
+  - When a later registry attempt fails, the last good answer stays on
+    screen marked "Not re-verified", with its success and failure times.
+  - A package that has never been checked successfully says so.
+  - A failed "Check again" or re-read shows an alert and keeps the last
+    answer, marked as not re-verified, without the raw error.
+  - The next successful answer clears these notices.
+- **New contract pieces (additive):**
+  - in `admin/version-core`: `buildVersionReport`, `readReleaseIdentity`,
+    `readEnvironment`, `readInstalledPackages`, `releasesFromReport`,
+    `FIRST_PARTY_PACKAGES` and `platformRegistryClient`;
+  - the `./admin/version-report` export: report types,
+    `evaluatePackageUpdate` and `summarizeUpdates`;
+  - an optional `package` field on `CmsModuleDefinition` (Popups declares
+    `@bygghammar/lightweight-popup`);
+  - `status` from `useResolvedSiteConfig()`;
+  - optional `report`, `modules`, `latestCheckFailed` and `onRefresh` props
+    on `VersionView`.
+
+  A host whose `getSystemVersion` still returns only `{ build, releases }`
+  keeps rendering, with the release shown as unknown and no update check.
+- **Host side:**
+  - protect `getSystemVersion` with the site's auth middleware and
+    `assertStaff`;
+  - accept `{ refresh?: boolean }` and pass it to `buildVersionReport`;
+  - inject the installed package list as the `packages` build constant
+    (`[{ name, installed, declared, requiredByCms }]`, read from
+    `node_modules` at build time).
+
+  Voyara's adoption does all three.
+
+## 0.93.0
+
+- **Breaking for callers of `responsiveImage`, and for transparent images in
+  browsers without WebP:** responsive images now display as WebP only.
+  `responsiveImage` used to derive a `-fallback.png` for every responsive WebP
+  and `FocalImage` rendered it as the `<img src>`; the optimizer writes that
+  PNG only for transparent uploads, so opaque images carried a missing object
+  that crawlers and browsers without WebP requested. `FocalImage` now renders
+  the stored URL as `src` with the WebP widths as `srcSet`, and uses
+  `<picture>` only for art direction. `ResponsiveImage.fallbackSrc` is
+  deprecated and never set. Transparent uploads still get their PNG copy, but
+  responsive page markup does not serve it, so a browser without WebP support
+  does not receive it, even when the upload generated one. **Host side:** drop
+  any branch that reads `fallbackSrc`; it is now always undefined (Voyara's
+  site hero has one).
+- Eager responsive images are now preloaded by React's server renderer,
+  because they are no longer inside a `<picture>`.
+- Fix review-image uploads. The browser prepared five WebP widths (including
+  2560) while the server accepts exactly four (480, 768, 1200, 1920), so every
+  review upload was rejected before storage. Review images are now prepared at
+  the four review widths. The upload help text now says what happens:
+  proportions are usually kept, a very tall image may be cropped at the top
+  and bottom to the 2400px height limit, and no PNG copy is made.
+- Upload and re-upload help text no longer promises a PNG fallback; review
+  image uploads never made one.
+
 ## 0.92.2
 
 - Fix rich-text attribute escaping. `sanitizeHtml` read attribute values as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.92.2",
+  "version": "0.94.0",
   "description": "Shared CMS platform: blocks, block types, i18n core, UI primitives and design-token contract used by every Bygghammar/Voyara site.",
   "type": "module",
   "sideEffects": [
@@ -186,6 +186,7 @@
     "./site/public-origin": "./src/site/public-origin.ts",
     "./site/font-bundle": "./src/site/font-bundle.ts",
     "./admin/version-core": "./src/admin/version-core.ts",
+    "./admin/version-report": "./src/admin/version-report.ts",
     "./config/package-owned-modules": "./src/config/package-owned-modules.ts",
     "./modules": "./src/modules/index.ts",
     "./popups/host": "./src/popups/host.ts",

package/src/admin/module-inventory.ts

@@ -0,0 +1,67 @@
+/**
+ * The version screen's module list, derived from the module table.
+ *
+ * Every module is listed, enabled or not: switching a module off in Site
+ * settings hides it, it does not remove its code from the build. Whether it is
+ * on comes from the same saved settings the Settings screen and the sidebar
+ * read. Until that read has succeeded, the status is "checking" or
+ * "unavailable" — never the compiled default presented as the live answer.
+ */
+import { CMS_MODULE_LIST, type CmsModuleKey } from "../config/modules";
+import type { PackageReport } from "./version-report";
+
+/** The state of the saved-settings read the enabled flags come from. */
+export type ModuleSettingsRead =
+  | { readonly state: "loading" }
+  | { readonly state: "error" }
+  | {
+      readonly state: "ready";
+      readonly features: Readonly<Partial<Record<CmsModuleKey, boolean>>>;
+      /** True when a later re-read failed and these values are from an earlier one. */
+      readonly stale?: boolean;
+    };
+
+export type ModuleEnabledState = "enabled" | "disabled" | "checking" | "unavailable";
+
+export type ModuleInventoryRow = {
+  readonly key: CmsModuleKey;
+  readonly label: string;
+  readonly description: string | null;
+  readonly enabled: ModuleEnabledState;
+  /** True when `enabled` comes from an earlier successful read. */
+  readonly enabledStale: boolean;
+  /** Installed CMS package version the module ships inside, when known. */
+  readonly cmsVersion: string | null;
+  /** The separately published package the module is built on, if any. */
+  readonly packageName: string | null;
+  /** That package's report, when the host supplied one. */
+  readonly package: PackageReport | null;
+};
+
+/** One row per module, in module-table order. */
+export function moduleInventory(
+  settings: ModuleSettingsRead,
+  packages: readonly PackageReport[] | null | undefined,
+  cmsVersion: string | null | undefined,
+): ModuleInventoryRow[] {
+  return CMS_MODULE_LIST.map((m) => {
+    let enabled: ModuleEnabledState;
+    if (settings.state === "loading") enabled = "checking";
+    else if (settings.state === "error") enabled = "unavailable";
+    else {
+      const value = settings.features[m.key];
+      enabled = value === true ? "enabled" : value === false ? "disabled" : "unavailable";
+    }
+    const packageName = m.package ?? null;
+    return {
+      key: m.key,
+      label: m.label,
+      description: m.description ?? null,
+      enabled,
+      enabledStale: settings.state === "ready" && settings.stale === true,
+      cmsVersion: cmsVersion ?? null,
+      packageName,
+      package: packageName ? (packages?.find((p) => p.name === packageName) ?? null) : null,
+    };
+  });
+}

package/src/admin/registry-metadata.ts

@@ -0,0 +1,256 @@
+/**
+ * Bounded, cached reads of public npm registry metadata — server side only.
+ *
+ * The version screen compares installed first-party packages with what has
+ * been published. That comparison must never be able to hurt the page or the
+ * server, so every read here is:
+ *
+ * - **allowlisted**: only package names the caller fixed at construction are
+ *   looked up; the URL is built here from the fixed registry origin, never from
+ *   request input. Anything else answers `not-allowed` without a request.
+ * - **anonymous**: no credentials, tokens or cookies are sent, and redirects are
+ *   refused so the request cannot be bounced elsewhere.
+ * - **bounded**: a timeout covers the whole response, and bodies over a size
+ *   cap are abandoned.
+ * - **cached**: a successful answer is reused for `freshForMs`; after any
+ *   attempt, successful or not, the registry is not asked again for that
+ *   package for `retryAfterMs`, even when a manual refresh is requested.
+ *   Concurrent callers share one request.
+ * - **failure-tolerant**: a failed read keeps serving the last good answer as
+ *   `stale` (cached, not re-verified) with the failure's fixed reason code —
+ *   never the registry's own text — until a later attempt succeeds.
+ */
+import { parseSemver } from "./semver";
+import type {
+  RegistryCheck,
+  RegistryError,
+  RegistryMetadata,
+  RegistryVersion,
+} from "./version-report";
+
+/** The only registry this module talks to. */
+export const NPM_REGISTRY_ORIGIN = "https://registry.npmjs.org";
+
+/** Scoped npm package names only (`@scope/name`), lower case. */
+const PACKAGE_NAME = /^@[a-z0-9][a-z0-9._-]{0,63}\/[a-z0-9][a-z0-9._-]{0,127}$/;
+
+export type RegistryLookup = {
+  readonly metadata: RegistryMetadata | null;
+  readonly check: RegistryCheck;
+};
+
+export type RegistryClientOptions = {
+  /** Exact package names that may be looked up. */
+  readonly allowlist: readonly string[];
+  /** Injected for tests; defaults to the global `fetch` at call time. */
+  readonly fetch?: (input: string, init: RequestInit) => Promise<Response>;
+  /** Injected for tests; milliseconds since the epoch. */
+  readonly now?: () => number;
+  /** How long a successful answer counts as fresh. Default 15 minutes. */
+  readonly freshForMs?: number;
+  /** Minimum time between two attempts for one package. Default 60 seconds. */
+  readonly retryAfterMs?: number;
+  /** Timeout for one request, body included. Default 5 seconds. */
+  readonly timeoutMs?: number;
+  /** Largest response body accepted. Default 8 MiB. */
+  readonly maxBytes?: number;
+};
+
+export type RegistryClient = {
+  lookup(name: string, options?: { refresh?: boolean }): Promise<RegistryLookup>;
+  /** When the next attempt for `name` may reach the registry (epoch ms), or null if now. */
+  nextAttemptAt(name: string): number | null;
+};
+
+/** The registry URL for a scoped package (`@scope%2Fname`). */
+export function registryUrl(name: string): string {
+  return `${NPM_REGISTRY_ORIGIN}/${name.replace("/", "%2F")}`;
+}
+
+function iso(ms: number | null | undefined): string | null {
+  return typeof ms === "number" && Number.isFinite(ms) ? new Date(ms).toISOString() : null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Reduce a registry document to the fields the screen uses, or `null` when it
+ * does not have the expected shape. Versions that are not valid semver are
+ * dropped; a document with no usable version at all is malformed.
+ */
+export function parseRegistryDocument(doc: unknown): RegistryMetadata | null {
+  if (!isRecord(doc) || !isRecord(doc["versions"])) return null;
+  const time = isRecord(doc["time"]) ? doc["time"] : {};
+  const rawTags = isRecord(doc["dist-tags"]) ? doc["dist-tags"] : {};
+
+  const versions: Record<string, RegistryVersion> = {};
+  for (const [key, entry] of Object.entries(doc["versions"])) {
+    const sv = parseSemver(key);
+    if (!sv) continue;
+    const stamp = time[key];
+    const ms = typeof stamp === "string" ? Date.parse(stamp) : Number.NaN;
+    const deprecated = isRecord(entry) && typeof entry["deprecated"] === "string";
+    versions[sv.version] = {
+      publishedAt: Number.isFinite(ms) ? new Date(ms).toISOString() : null,
+      deprecated: deprecated && (entry["deprecated"] as string).length > 0,
+    };
+  }
+  if (Object.keys(versions).length === 0) return null;
+
+  const distTags: Record<string, string> = {};
+  for (const [tag, value] of Object.entries(rawTags)) {
+    const sv = parseSemver(value);
+    if (sv && /^[A-Za-z0-9._-]{1,64}$/.test(tag)) distTags[tag] = sv.version;
+  }
+  return { distTags, versions };
+}
+
+async function readBounded(res: Response, maxBytes: number): Promise<string | null> {
+  const declared = Number(res.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    await res.body?.cancel().catch(() => {});
+    return null;
+  }
+  if (!res.body) {
+    const text = await res.text();
+    return new TextEncoder().encode(text).byteLength > maxBytes ? null : text;
+  }
+  const reader = res.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel().catch(() => {});
+      return null;
+    }
+    chunks.push(value);
+  }
+  const all = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    all.set(c, offset);
+    offset += c.byteLength;
+  }
+  return new TextDecoder().decode(all);
+}
+
+/** Create a registry client. One per process is the intended use. */
+export function createRegistryClient(options: RegistryClientOptions): RegistryClient {
+  const allowed = new Set(options.allowlist.filter((n) => PACKAGE_NAME.test(n)));
+  const now = options.now ?? (() => Date.now());
+  const freshForMs = options.freshForMs ?? 15 * 60_000;
+  const retryAfterMs = options.retryAfterMs ?? 60_000;
+  const timeoutMs = options.timeoutMs ?? 5_000;
+  const maxBytes = options.maxBytes ?? 8 * 1024 * 1024;
+
+  const good = new Map<string, { metadata: RegistryMetadata; at: number }>();
+  const attempts = new Map<string, { at: number; error: RegistryError | null }>();
+  const inflight = new Map<string, Promise<void>>();
+
+  async function attempt(name: string): Promise<void> {
+    const startedAt = now();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let error: RegistryError | null = null;
+    try {
+      const doFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+      const res = await doFetch(registryUrl(name), {
+        method: "GET",
+        headers: { accept: "application/json" },
+        redirect: "error",
+        credentials: "omit",
+        signal: controller.signal,
+      });
+      if (res.status === 404) {
+        error = "not-found";
+        await res.body?.cancel().catch(() => {});
+      } else if (!res.ok) {
+        error = "http";
+        await res.body?.cancel().catch(() => {});
+      } else {
+        const text = await readBounded(res, maxBytes);
+        if (text === null) {
+          error = "too-large";
+        } else {
+          let doc: unknown;
+          try {
+            doc = JSON.parse(text);
+          } catch {
+            doc = undefined;
+          }
+          const metadata = parseRegistryDocument(doc);
+          if (metadata) good.set(name, { metadata, at: startedAt });
+          else error = "malformed";
+        }
+      }
+    } catch {
+      error = controller.signal.aborted ? "timeout" : "network";
+    } finally {
+      clearTimeout(timer);
+    }
+    attempts.set(name, { at: startedAt, error });
+  }
+
+  function snapshot(name: string): RegistryLookup {
+    const hit = good.get(name);
+    const last = attempts.get(name);
+    // Fresh only when the most recent attempt is the successful one and it is
+    // within the lifetime. A newer failed attempt leaves the last good answer
+    // in place, but as cached and unverified, never as current.
+    const latestFailed = last !== undefined && last.error !== null;
+    const state = !hit
+      ? "unavailable"
+      : latestFailed || now() - hit.at >= freshForMs
+        ? "stale"
+        : "fresh";
+    return {
+      metadata: hit?.metadata ?? null,
+      check: {
+        state,
+        lastSuccessAt: iso(hit?.at),
+        lastAttemptAt: iso(last?.at),
+        error: last?.error ?? null,
+      },
+    };
+  }
+
+  function nextAttemptAt(name: string): number | null {
+    const last = attempts.get(name);
+    if (!last) return null;
+    const next = last.at + retryAfterMs;
+    return next > now() ? next : null;
+  }
+
+  return {
+    nextAttemptAt,
+    async lookup(name, { refresh = false } = {}) {
+      if (!allowed.has(name)) {
+        return {
+          metadata: null,
+          check: { state: "unavailable", lastSuccessAt: null, lastAttemptAt: null, error: "not-allowed" },
+        };
+      }
+      const hit = good.get(name);
+      const fresh = hit !== undefined && now() - hit.at < freshForMs;
+      const throttled = nextAttemptAt(name) !== null;
+      if (!throttled && (refresh || !fresh)) {
+        let pending = inflight.get(name);
+        if (!pending) {
+          pending = attempt(name).finally(() => inflight.delete(name));
+          inflight.set(name, pending);
+        }
+        await pending;
+      } else {
+        // Someone else may be mid-request; share its answer rather than a stale one.
+        const pending = inflight.get(name);
+        if (pending) await pending;
+      }
+      return snapshot(name);
+    },
+  };
+}

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])}`;
+}