@iterant/site-runtime 3.4.0 → 3.6.0

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.4.0._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.6.0._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "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/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"
@@ -58,6 +77,31 @@ export type DatabaseQuery = {
 
 export type DatabaseRow = Record<string, string | number | null>;
 
+/**
+ * Where a rendered row came from, carried on the row so the visual editor can
+ * find the element again (epic DBX, decision DBX-D20). It rides a NON-enumerable
+ * `__db` slot: invisible to `JSON.stringify`, to `Object.keys`, and to every
+ * template that spreads or iterates the row, so nothing accidentally renders it.
+ */
+export type DbProvenance = {
+  table: string;
+  id: string;
+  /** Whether the published site shows this row. The preview channel projects it
+   *  per row (`_live`); a draft reads `false`. */
+  live: boolean;
+};
+
+/** The property that carries {@link DbProvenance}, hidden from enumeration. */
+const PROVENANCE_KEY = "__db";
+
+/** The attributes {@link dbAttrs} writes onto a DB-bound element. */
+export type DbAttrs = {
+  "data-db-table": string;
+  "data-db-row": string;
+  "data-db-col": string;
+  "data-db-draft"?: "";
+};
+
 export type DatabaseResult = {
   rows: DatabaseRow[];
   /** Every row matching the query, not just this page. */
@@ -73,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") {
@@ -93,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;
 }
 
@@ -108,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,
@@ -151,5 +227,129 @@ export async function readDatabase(
   if (!Array.isArray(page.rows)) {
     return warn(`"${table}" answered without rows`, body);
   }
-  return { rows: page.rows, total: Number(page.total ?? page.rows.length) };
+  return {
+    rows: page.rows.map((row) => withProvenance(row, table)),
+    total: Number(page.total ?? page.rows.length),
+  };
+}
+
+/**
+ * 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`.
+ *
+ * The preview-read channel returns `_id` and a computed `_live` flag; the public
+ * production read (C6) is published-only and carries neither, so this leaves a
+ * production row untouched. The `_live` flag is lifted OFF the row into the
+ * hidden slot so no template can render it; `_id` stays where a `systemColumns`
+ * grant may legitimately want it. The slot is non-enumerable, so a row that
+ * spreads or serializes looks exactly as it did before.
+ */
+function withProvenance(row: DatabaseRow, table: string): DatabaseRow {
+  const id = row._id;
+  if (id === undefined || id === null) return row;
+  const { _live, ...rest } = row;
+  const provenance: DbProvenance = {
+    table,
+    id: String(id),
+    live: _live === undefined ? true : _live !== 0,
+  };
+  Object.defineProperty(rest, PROVENANCE_KEY, {
+    value: provenance,
+    enumerable: false,
+    writable: false,
+    configurable: true,
+  });
+  return rest;
+}
+
+function provenanceOf(row: DatabaseRow): DbProvenance | undefined {
+  return (row as { [PROVENANCE_KEY]?: DbProvenance })[PROVENANCE_KEY];
+}
+
+/**
+ * The `data-db-*` attributes that make a DB-bound element self-describing, spread
+ * onto the element where the value is interpolated:
+ *
+ * ```astro
+ * <h1 {...dbAttrs(article, "title")}>{article.title}</h1>
+ * ```
+ *
+ * The visual editor reads these to map a click back to a table, row, and column
+ * (dbx-31). A draft row (its `_live` is false) also gets `data-db-draft`, which
+ * the preview marks so a screenshot cannot be mistaken for the live page.
+ *
+ * Returns `{}` in a production build (`import.meta.env.PROD`) and when the row
+ * carries no provenance, so published HTML ships with no annotations and no row
+ * ids. Preview only, by default (fork F1).
+ */
+export function dbAttrs(
+  row: DatabaseRow,
+  column: string,
+): DbAttrs | Record<string, never> {
+  if (import.meta.env.PROD) return {};
+  const provenance = provenanceOf(row);
+  if (!provenance) return {};
+  const attrs: DbAttrs = {
+    "data-db-table": provenance.table,
+    "data-db-row": provenance.id,
+    "data-db-col": column,
+  };
+  if (provenance.live === false) attrs["data-db-draft"] = "";
+  return attrs;
 }

package/src/lib/locales.ts

@@ -25,9 +25,11 @@ export const DEFAULT_LOCALE = "en";
  * `chrome.pt-br` → {base:"chrome", locale:"pt-br"}. Base names never contain
  * dots, so any well-formed lowercased locale suffix IS a sibling id.
  *
- * KEEP IN SYNC with `apps/agent-mvp/src/locales.ts#parseEntryId` — the agent
- * writes the sibling ids the site reads back (out-of-workspace duplication,
- * same pattern as the special-input mirrors).
+ * The agent-side counterpart is
+ * `apps/agent-flue/src/product/localization.ts#parseEntryId`: the agent writes
+ * the sibling ids the site reads back (out-of-workspace duplication). KEEP THE
+ * LOCALE SEGMENT GRAMMAR IN SYNC with its LOCALE_SEGMENT_PATTERN; the two
+ * differ only on ids whose suffix fails that grammar.
  */
 export function parseEntryId(id: string): { base: string; locale?: string } {
   const dot = id.indexOf(".");
@@ -42,8 +44,8 @@ export function parseEntryId(id: string): { base: string; locale?: string } {
  * Canonical BCP-47 casing for a locale (`pt-br` → `pt-BR`, `ES` → `es`):
  * language subtag lowercased, 4-alpha script subtags Titlecased, other
  * subtags uppercased. Files/routes use the lowercased segment; this casing is
- * for the `<html lang>` attribute and hreflang values (starter 2.9.0). KEEP IN
- * SYNC with `apps/agent-mvp/src/locales.ts#normalizeBcp47`.
+ * for the `<html lang>` attribute and hreflang values (starter 2.9.0). This is
+ * the single implementation; the agent side never renders lang attributes.
  */
 export function normalizeBcp47(locale: string): string {
   const raw = locale.trim().replace(/_/g, "-");