@iterant/site-runtime 3.3.0 → 3.5.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.3.0._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.5.0._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 
@@ -259,6 +259,37 @@ additive platform-side field can never fail an already-pinned repo's build.
 "The one `@source` line" below does not grow: the component ships no utility
 classes, only a scoped style block on the data attribute.
 
+### Reading the brand Database (3.4.0)
+
+A page can render rows the customer maintains in the brand Database, read at
+request time:
+
+```ts
+import { readDatabase } from "@iterant/site-runtime/database";
+
+const { rows, total } = await readDatabase("articles", {
+  sort: [{ column: "published_at", dir: "desc" }],
+  limit: 20,
+});
+```
+
+Server side only (a page's frontmatter, an SSR route). The site holds no
+database binding and writes no SQL: it names a table and the platform decides
+what that means. A table is invisible until the platform grants it site read,
+and the grant carries the filter that says which rows are public (a blog
+publishes `status = published`) plus an optional list of readable fields. A
+narrower `filter` here can only narrow that further. The platform's own row
+columns (`_id`, `_created_at`, `_updated_at`, `_v`) are not part of a grant
+unless it says so, so a page that keys rows by `_id` needs the grant to publish
+it; without that they are neither readable, filterable nor sortable.
+
+Nothing is configured in the repo. A published site gets the endpoint and the
+token from the platform-generated publish gate; `astro dev` gets them from
+`ITERANT_SITE_DB_URL` and `ITERANT_SITE_DB_TOKEN`, which the platform sets on
+the dev server. A site with neither, an ungranted table and an unreachable
+platform all read as `{rows: [], total: 0}` with a console warning: a listing
+that renders empty beats a build that dies on a database blip.
+
 ### Choosing a shell (3.2.0)
 
 A repo may own more than one frame. A replicated site whose second page carried

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.3.0",
+  "version": "3.5.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": {
@@ -31,6 +31,7 @@
     "!scripts/check-fixture.mjs",
     "!scripts/check-packed.mjs",
     "!scripts/generate-kit-table.mjs",
+    "!scripts/packed-content.mjs",
     "!src/lib/__fixtures__"
   ],
   "exports": {
@@ -38,6 +39,7 @@
     "./content": "./src/content/collections.ts",
     "./content/schema": "./src/content/schema.ts",
     "./content-values": "./src/lib/content-values.ts",
+    "./database": "./src/lib/database.ts",
     "./markdown": "./src/lib/markdown.ts",
     "./locales": "./src/lib/locales.ts",
     "./hreflang": "./src/lib/hreflang.ts",
@@ -112,8 +114,6 @@
     "@types/node": "24.3.1",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
-    "@workspace/eslint-config": "workspace:*",
-    "@workspace/typescript-config": "workspace:*",
     "typescript": "5.9.2",
     "vitest": "^4.0.13",
     "wrangler": "^4.107.0"

package/src/index.ts

@@ -12,6 +12,7 @@ export * from "./lib/bespoke-pages";
 export * from "./lib/chrome-schemas";
 export * from "./lib/content-paths";
 export * from "./lib/content-values";
+export * from "./lib/database";
 export * from "./lib/hreflang";
 export * from "./lib/locales";
 export * from "./version";

package/src/lib/database.ts

@@ -0,0 +1,247 @@
+// Reading the brand's Database from a page, at request time (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
+// what that means: the table has to carry a `site_read` grant, the grant's
+// filters are added server side, and its column allowlist is what comes back.
+// So a page cannot read a draft by asking differently, and nothing here needs to
+// know how the data is stored.
+//
+// Where the endpoint and token come from: the publish gate, a module the
+// 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.
+//
+// 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.
+
+const GLOBAL_KEY = "__ITERANT_SITE_DB__";
+
+const URL_ENV = "ITERANT_SITE_DB_URL";
+
+const TOKEN_ENV = "ITERANT_SITE_DB_TOKEN";
+
+/** How long one read may take before the page renders without it. */
+const TIMEOUT_MS = 10_000;
+
+export type DatabaseFilterOp =
+  | "eq"
+  | "ne"
+  | "contains"
+  | "gt"
+  | "lt"
+  | "isnull";
+
+export type DatabaseFilter = {
+  column: string;
+  op: DatabaseFilterOp;
+  value?: string | number | boolean | null;
+};
+
+export type DatabaseSort = {
+  column: string;
+  dir: "asc" | "desc";
+};
+
+export type DatabaseQuery = {
+  /** Columns to read. Omitted means every column the grant allows. */
+  select?: string[];
+  /** Narrows the granted rows further. It can never widen them. */
+  filter?: DatabaseFilter[];
+  sort?: DatabaseSort[];
+  /** Rows per page, up to the platform's own ceiling of 200. */
+  limit?: number;
+  offset?: number;
+};
+
+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. */
+  total: number;
+};
+
+type SiteDatabaseHandoff = {
+  /** The complete read endpoint, brand and all. The site never assembles a
+   *  platform URL of its own. */
+  url: string;
+  token: string;
+};
+
+const EMPTY: DatabaseResult = { rows: [], total: 0 };
+
+function fromEnvironment(): SiteDatabaseHandoff | null {
+  const environment = (
+    globalThis as { process?: { env?: Record<string, string | undefined> } }
+  ).process?.env;
+  const url = environment?.[URL_ENV];
+  const token = environment?.[TOKEN_ENV];
+  return url && token ? { url, token } : null;
+}
+
+function handoff(): SiteDatabaseHandoff | null {
+  const baked = (globalThis as Record<string, unknown>)[GLOBAL_KEY];
+  if (baked && typeof baked === "object") {
+    const { url, token } = baked as Partial<SiteDatabaseHandoff>;
+    if (typeof url === "string" && typeof token === "string") {
+      return { url, token };
+    }
+  }
+  return fromEnvironment();
+}
+
+function warn(message: string, detail?: unknown): DatabaseResult {
+  console.warn(`[site-runtime] readDatabase: ${message}`, detail ?? "");
+  return EMPTY;
+}
+
+/**
+ * Read rows of one granted table.
+ *
+ * ```ts
+ * const { rows } = await readDatabase("articles", {
+ *   sort: [{ column: "published_at", dir: "desc" }],
+ *   limit: 20,
+ * });
+ * ```
+ *
+ * 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.
+ */
+export async function readDatabase(
+  table: string,
+  query: DatabaseQuery = {},
+): Promise<DatabaseResult> {
+  const pair = handoff();
+  if (!pair) {
+    return warn(
+      `no database is connected to this site, so "${table}" read as empty. ` +
+        `A published site gets its connection from the publish gate; ` +
+        `a dev server gets it from ${URL_ENV} and ${TOKEN_ENV}.`,
+    );
+  }
+  let response: Response;
+  try {
+    response = await fetch(pair.url, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${pair.token}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ table, ...query }),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (error) {
+    return warn(`"${table}" could not be reached`, error);
+  }
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    return warn(`"${table}" answered ${response.status}`, detail.slice(0, 400));
+  }
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch (error) {
+    return warn(`"${table}" answered with a body that is not JSON`, error);
+  }
+  const page = body as Partial<DatabaseResult>;
+  if (!Array.isArray(page.rows)) {
+    return warn(`"${table}" answered without rows`, body);
+  }
+  return {
+    rows: page.rows.map((row) => withProvenance(row, table)),
+    total: Number(page.total ?? page.rows.length),
+  };
+}
+
+/**
+ * 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, "-");