@iterant/site-runtime 3.5.0 → 3.6.1

package/docs/runtime-contract.md

@@ -50,7 +50,7 @@ runtime and says so.
 
 <!-- generated: available libraries -->
 
-_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.5.0._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.6.1._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.5.0",
+  "version": "3.6.1",
   "type": "module",
   "description": "The platform layer every Iterant brand site runs on: content grammar, collection schemas, SEO head and JSON-LD, layout core, Astro config preset, dev integrations and the verify gates.",
   "scripts": {

package/scripts/scan-bespoke-siblings.mjs

@@ -19,12 +19,29 @@
  *      the shape the catch-all's pickPageExport (src/lib/bespoke-pages.ts)
  *      resolves.
  *
- * For every NON-DRAFT bespoke base entry, this asserts (1) against the built
- * manifest and (2) by importing the built client entry itself. Draft bespoke
- * pages are exempt: drafts never publish, their siblings are never advertised
- * (hreflang/sitemap), and the stock `not-found` page is a draft that
- * deliberately lives outside the `<base>/page.tsx` convention (404.astro
- * renders it). Publishing a bespoke page puts it in scope on the next verify.
+ * For every NON-DRAFT bespoke base entry THAT HAS a locale sibling file
+ * (`<base>.<locale>.json`, draft or not: a draft sibling still renders in a
+ * preview), this asserts (1) against the built manifest and (2) by importing
+ * the built client entry itself. Draft bespoke pages are exempt: drafts never
+ * publish, their siblings are never advertised (hreflang/sitemap), and the
+ * stock `not-found` page is a draft that deliberately lives outside the
+ * `<base>/page.tsx` convention (404.astro renders it). Publishing a bespoke
+ * page puts it in scope on the next verify.
+ *
+ * Scoping to bases-with-siblings (3.6.1) loses nothing: the hazard cannot
+ * materialize without a sibling, a sibling only comes into existence through
+ * a save, and every save runs this gate, so a base picks up the full check
+ * the moment its first sibling lands. Before that, a pre-convention bespoke
+ * page (every pre-3.6 blog) must not block a same-major runtime bump over a
+ * feature the repo does not use.
+ *
+ * A base whose sibling route is SHADOWED is also out of scope (3.6.1): when
+ * `src/pages/[locale]/<base>.astro` exists (`index.astro` for the `home`
+ * base), Astro's route priority sends `/es` to that explicit route, never to
+ * the catch-all, so the catch-all hydration contract this gate asserts does
+ * not serve the sibling at all. Replica-era repos localize exactly this way.
+ * The shadowing route's own hydration is `astro build`'s concern, like every
+ * other explicit route.
  *
  * It also pins the Astro runtime contract the catch-all relies on: the island
  * renderer must keep accepting `client:component-path` /
@@ -37,7 +54,7 @@
  * weaken this script.
  */
 
-import { readdir, readFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { exit } from "node:process";
@@ -51,41 +68,34 @@ const CONVENTIONS =
 /** @type {string[]} */
 const problems = [];
 
-// ---- SF-pin: the Astro runtime directive contract --------------------------
-
-const hydrationJs = join(
-  process.cwd(),
-  "node_modules/astro/dist/runtime/server/hydration.js",
-);
-const hydrationSrc = await readFile(hydrationJs, "utf8").catch(() => "");
-for (const directive of ["client:component-path", "client:component-export"]) {
-  if (!hydrationSrc.includes(`case "${directive}"`)) {
-    problems.push(
-      `astro runtime contract changed: ${hydrationJs} no longer handles ` +
-        `"${directive}" as a prop. Bespoke locale siblings hydrate through ` +
-        `exactly that escape hatch (src/pages/[...slug].astro) — re-verify ` +
-        `sibling hydration against this Astro version before shipping.`,
-    );
-  }
-}
-
-// ---- SF1+SF2: every non-draft bespoke base ---------------------------------
+// ---- SF1+SF2: every non-draft bespoke base with a sibling ------------------
 
-/** Non-draft bespoke base entry ids (`home`), never locale siblings. */
-async function bespokeBases() {
+/**
+ * Non-draft bespoke base entry ids (`home`), never locale siblings, plus the
+ * set of base ids that have at least one sibling file. Sibling presence
+ * counts by filename alone (`home.es.json` -> `home`): a sibling's own draft
+ * flag or parse failure does not excuse its base, because the sibling still
+ * renders in a preview.
+ */
+async function bespokeInventory() {
   const pagesDir = join(process.cwd(), "src/content/pages");
   /** @type {string[]} */
   const bases = [];
+  /** @type {Set<string>} */
+  const siblingBases = new Set();
   /** @type {string[]} */
   let names = [];
   try {
     names = await readdir(pagesDir);
   } catch {
-    return bases; // no pages dir — astro check owns that failure
+    return { bases, siblingBases }; // no pages dir: astro check owns that failure
   }
   for (const name of names.filter((n) => n.endsWith(".json")).sort()) {
     const id = name.replace(/\.json$/, "");
-    if (id.includes(".")) continue; // locale sibling — guarded via its base
+    if (id.includes(".")) {
+      siblingBases.add(id.slice(0, id.indexOf(".")));
+      continue; // locale sibling: guarded via its base
+    }
     /** @type {{ mode?: string; draft?: boolean }} */
     let entry;
     try {
@@ -95,7 +105,21 @@ async function bespokeBases() {
     }
     if (entry.mode === "bespoke" && entry.draft !== true) bases.push(id);
   }
-  return bases;
+  return { bases, siblingBases };
+}
+
+/**
+ * Whether an explicit locale route shadows this base's siblings. Astro sends
+ * `/es` (and `/es/<base>`) to `src/pages/[locale]/index.astro` (respectively
+ * `[locale]/<base>.astro`) before any rest-param catch-all, so when that file
+ * exists the sibling never renders through the catch-all this gate asserts.
+ */
+async function siblingRouteShadowed(base) {
+  const file = base === "home" ? "index.astro" : `${base}.astro`;
+  return stat(join(process.cwd(), "src/pages/[locale]", file)).then(
+    (s) => s.isFile(),
+    () => false,
+  );
 }
 
 /**
@@ -133,8 +157,37 @@ async function builtEntryModules() {
   return null;
 }
 
-const bases = await bespokeBases();
-if (bases.length > 0 && problems.length === 0) {
+const inventory = await bespokeInventory();
+/** @type {string[]} */
+const bases = [];
+for (const base of inventory.bases) {
+  if (!inventory.siblingBases.has(base)) continue;
+  if (await siblingRouteShadowed(base)) continue;
+  bases.push(base);
+}
+// Nothing can hydrate through the escape hatch: the first sibling arrives via
+// a save, and every save re-runs this gate, so exiting here defers nothing.
+if (bases.length === 0) exit(0);
+
+// ---- SF-pin: the Astro runtime directive contract --------------------------
+
+const hydrationJs = join(
+  process.cwd(),
+  "node_modules/astro/dist/runtime/server/hydration.js",
+);
+const hydrationSrc = await readFile(hydrationJs, "utf8").catch(() => "");
+for (const directive of ["client:component-path", "client:component-export"]) {
+  if (!hydrationSrc.includes(`case "${directive}"`)) {
+    problems.push(
+      `astro runtime contract changed: ${hydrationJs} no longer handles ` +
+        `"${directive}" as a prop. Bespoke locale siblings hydrate through ` +
+        `exactly that escape hatch (src/pages/[...slug].astro): re-verify ` +
+        `sibling hydration against this Astro version before shipping.`,
+    );
+  }
+}
+
+if (problems.length === 0) {
   const entryModules = await builtEntryModules();
   if (!entryModules) {
     problems.push(

package/src/lib/database.ts

@@ -1,5 +1,4 @@
-// Reading the brand's Database from a page, at request time (epic DBX, decision
-// DBX-D11).
+// Reading the brand's Database from a page (epic DBX, decision DBX-D11).
 //
 // A published site holds no database binding and composes no SQL. It asks the
 // platform's public read route for rows of ONE table, and the platform decides
@@ -12,10 +11,21 @@
 // platform generates on every publish and puts in front of Astro's entry. It
 // assigns them to `globalThis.__ITERANT_SITE_DB__` at module scope. In `astro
 // dev` there is no gate, so the pair arrives as environment variables instead.
+// A prerendered route reads while the site BUILDS, before that gate is even
+// generated, so the publish pipeline puts the pair in `.dev.vars` beside the
+// wrangler config and it reaches the render as environment variables too.
 //
 // Every failure answers with no rows and a console warning, never a throw: a
-// listing that renders empty is a page the customer can still see, and a build
-// that fails on a database blip is not.
+// listing that renders empty is a page the customer can still see, and a
+// request that fails on a database blip is not.
+//
+// That contract inverts at BAKE time. A prerendered route reads once, during
+// the publish build, and whatever it read is served until the next publish, so
+// an empty answer there is not a transient blank list but a blog that stays
+// empty for days. The publish build therefore sets `ITERANT_SITE_DB_STRICT=1`
+// and every failure below throws instead, killing the build at its cause. The
+// deployed runtime and the dev server never set it, so their behavior is
+// unchanged.
 
 const GLOBAL_KEY = "__ITERANT_SITE_DB__";
 
@@ -23,9 +33,18 @@ const URL_ENV = "ITERANT_SITE_DB_URL";
 
 const TOKEN_ENV = "ITERANT_SITE_DB_TOKEN";
 
+const STRICT_ENV = "ITERANT_SITE_DB_STRICT";
+
 /** How long one read may take before the page renders without it. */
 const TIMEOUT_MS = 10_000;
 
+/** The platform's own ceiling on `limit`, and so the pager's page size. */
+const MAX_LIMIT = 200;
+
+/** The platform refuses an `offset` past this, so `MAX_LIMIT` rows after it is
+ *  the last row {@link readDatabaseAll} can reach. */
+const MAX_OFFSET = 100_000;
+
 export type DatabaseFilterOp =
   | "eq"
   | "ne"
@@ -98,15 +117,29 @@ type SiteDatabaseHandoff = {
 
 const EMPTY: DatabaseResult = { rows: [], total: 0 };
 
-function fromEnvironment(): SiteDatabaseHandoff | null {
-  const environment = (
+function environment(): Record<string, string | undefined> | undefined {
+  return (
     globalThis as { process?: { env?: Record<string, string | undefined> } }
   ).process?.env;
-  const url = environment?.[URL_ENV];
-  const token = environment?.[TOKEN_ENV];
+}
+
+function fromEnvironment(): SiteDatabaseHandoff | null {
+  const url = environment()?.[URL_ENV];
+  const token = environment()?.[TOKEN_ENV];
   return url && token ? { url, token } : null;
 }
 
+/**
+ * Whether a failed read must kill the process instead of rendering empty.
+ *
+ * Read from the environment only, never from the global handoff: the handoff is
+ * what a DEPLOYED site carries, and a deployed site is exactly where the
+ * never-throw contract still holds.
+ */
+function strict(): boolean {
+  return environment()?.[STRICT_ENV] === "1";
+}
+
 function handoff(): SiteDatabaseHandoff | null {
   const baked = (globalThis as Record<string, unknown>)[GLOBAL_KEY];
   if (baked && typeof baked === "object") {
@@ -118,8 +151,25 @@ function handoff(): SiteDatabaseHandoff | null {
   return fromEnvironment();
 }
 
+function detailOf(detail: unknown): string {
+  if (detail instanceof Error) return detail.message;
+  if (typeof detail === "string") return detail;
+  return JSON.stringify(detail) ?? String(detail);
+}
+
+/** Say a read did not work, the way this environment wants it said. */
+function report(message: string, detail?: unknown): void {
+  const line = `[site-runtime] ${message}`;
+  if (strict()) {
+    throw new Error(
+      detail === undefined ? line : `${line} ${detailOf(detail)}`,
+    );
+  }
+  console.warn(line, detail ?? "");
+}
+
 function warn(message: string, detail?: unknown): DatabaseResult {
-  console.warn(`[site-runtime] readDatabase: ${message}`, detail ?? "");
+  report(`readDatabase: ${message}`, detail);
   return EMPTY;
 }
 
@@ -133,8 +183,9 @@ function warn(message: string, detail?: unknown): DatabaseResult {
  * });
  * ```
  *
- * Call it in a page's frontmatter (server side). The rows are read on every
- * request, so publishing a row shows it on the next page load with no rebuild.
+ * Call it in a page's frontmatter (server side). On a prerendered route the read
+ * happens once, at publish time, and the site shows those rows until the next
+ * publish; on an SSR route it happens per request.
  */
 export async function readDatabase(
   table: string,
@@ -182,6 +233,63 @@ export async function readDatabase(
   };
 }
 
+/**
+ * Every row a query matches, not just the first page of it.
+ *
+ * ```ts
+ * export async function getStaticPaths() {
+ *   const { rows } = await readDatabaseAll("articles", { select: ["slug"] });
+ *   return rows.map((row) => ({ params: { slug: String(row.slug) } }));
+ * }
+ * ```
+ *
+ * This is the enumeration a `getStaticPaths` needs, and the reason it exists is
+ * that a plain {@link readDatabase} answers at most {@link MAX_LIMIT} rows and
+ * says so only in `total`. A blog of 300 articles would bake its first 200 and
+ * look complete. Paging here is not an optimization; it is the difference
+ * between a whole blog and a silently truncated one.
+ *
+ * Any `limit` or `offset` on the query is ignored; `filter`, `sort` and `select`
+ * are carried on every page.
+ */
+export async function readDatabaseAll(
+  table: string,
+  query: DatabaseQuery = {},
+): Promise<DatabaseResult> {
+  const { limit: _limit, offset: _offset, ...shared } = query;
+  const rows: DatabaseRow[] = [];
+  let total = 0;
+  for (let offset = 0; ; offset += MAX_LIMIT) {
+    const page = await readDatabase(table, {
+      ...shared,
+      limit: MAX_LIMIT,
+      offset,
+    });
+    // No rows means the end of the table, or a page that failed and rendered
+    // empty under the never-throw contract. Its `total` is not the table's, and
+    // adopting it would answer with rows already read alongside a total of
+    // none, which is a shape no caller can act on.
+    if (page.rows.length === 0) break;
+    rows.push(...page.rows);
+    // The first page's count is the snapshot the rest of the walk is measured
+    // against. A total that is not a real number (a route answering `"many"`)
+    // would compare false forever and walk to the offset ceiling, so an
+    // unusable one falls back to what actually arrived.
+    if (offset === 0) {
+      total = Number.isFinite(page.total) ? page.total : rows.length;
+    }
+    if (rows.length >= total) break;
+    if (offset + MAX_LIMIT > MAX_OFFSET) {
+      report(
+        `readDatabaseAll: "${table}" holds ${total} rows, past the ${MAX_OFFSET + MAX_LIMIT} ` +
+          `that offset paging reaches, so ${rows.length} of them were read.`,
+      );
+      break;
+    }
+  }
+  return { rows, total };
+}
+
 /**
  * Attach {@link DbProvenance} to a row that carries a system `_id`.
  *