create-astroid 0.9.2 → 0.11.0

package/into.mjs

@@ -0,0 +1,203 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// `create-astroid --into <path>`: one app scaffolded into a repository that
+// already holds one. The pure half of it, a module of its own so the test suite
+// can import it without running the scaffolder: which workspace globs cover a
+// path, how to add one, the root scripts, and the Workers Builds settings.
+//
+// Every edit here is text, not a parse and re-serialize. These are files a
+// person owns, with their comments and their formatting, and an edit that
+// rewrote the whole file to add one line would bury that line in a diff nobody
+// reads.
+
+/**
+ * Template-relative paths that belong to the repository rather than an app.
+ * `--into` never writes them into the app; each is written at the root only
+ * when the root has none.
+ */
+export const INTO_REPOSITORY_FILES = [
+  "pnpm-workspace.yaml",
+  "_gitignore",
+  "_github/workflows/ci.yml",
+  "docs/ARCHITECTURE.md",
+  "docs/DECISIONS.md",
+  "docs/RUNBOOK.md",
+];
+
+/**
+ * Why a path can't be scaffolded into, or null when it can. The path goes into
+ * root scripts and a workspace glob unquoted, so it's held to characters that
+ * need no quoting in either.
+ */
+export function intoPathProblem(path) {
+  if (!path || path === ".")
+    return "--into needs a path inside the repository, such as workers/order";
+  if (path.startsWith("..") || path.startsWith("/")) {
+    return `--into path "${path}" is outside the repository`;
+  }
+  if (!/^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/.test(path)) {
+    return `--into path "${path}" may use only letters, digits, ".", "_", "-", and "/"`;
+  }
+  return null;
+}
+
+/** A workspace glob as a regular expression over a POSIX path. */
+function globToRegExp(glob) {
+  const clean = glob.replace(/^\.\//, "").replace(/\/+$/, "");
+  let source = "";
+  for (let i = 0; i < clean.length; i++) {
+    const c = clean[i];
+    if (c === "*" && clean[i + 1] === "*") {
+      source += ".*";
+      i++;
+    } else if (c === "*") source += "[^/]*";
+    else if (c === "?") source += "[^/]";
+    else source += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${source}$`);
+}
+
+/**
+ * The `packages` list of a pnpm-workspace.yaml, or null when it has none. Reads
+ * the two shapes pnpm's own docs use, a block list and a flow list.
+ */
+export function workspacePackages(yaml) {
+  const lines = yaml.split("\n");
+  const at = lines.findIndex((line) => /^packages\s*:/.test(line));
+  if (at === -1) return null;
+  const unquote = (s) => s.trim().replace(/^["']|["']$/g, "");
+  const rest = lines[at]
+    .replace(/^packages\s*:/, "")
+    .replace(/\s+#.*$/, "")
+    .trim();
+  if (rest.startsWith("[")) {
+    return rest
+      .replace(/^\[|\]$/g, "")
+      .split(",")
+      .map(unquote)
+      .filter(Boolean);
+  }
+  const items = [];
+  for (const line of lines.slice(at + 1)) {
+    if (/^\s*(#.*)?$/.test(line)) continue;
+    const item = line.match(/^\s+-\s*(.+?)\s*(#.*)?$/);
+    if (!item) break;
+    items.push(unquote(item[1]));
+  }
+  return items;
+}
+
+/** Whether a workspace's `packages` globs already include `path`. */
+export function workspaceCovers(patterns, path) {
+  const matches = (glob) => globToRegExp(glob).test(path);
+  const included = patterns.filter((p) => !p.startsWith("!")).some(matches);
+  const excluded = patterns.filter((p) => p.startsWith("!")).some((p) => matches(p.slice(1)));
+  return included && !excluded;
+}
+
+/**
+ * The workspace file with `path` added to its `packages`, the same text when
+ * a glob already covers it, or null when the list is in a shape this can't
+ * edit safely (the caller then asks for it by hand).
+ */
+export function addWorkspacePackage(yaml, path) {
+  const patterns = workspacePackages(yaml);
+  if (patterns && workspaceCovers(patterns, path)) return yaml;
+  const lines = yaml.split("\n");
+
+  if (patterns === null) {
+    // No list yet. Insert one before the first top-level key, and before the
+    // comment that introduces that key, so the comment stays with it.
+    let at = lines.findIndex((line) => /^[A-Za-z]/.test(line));
+    if (at === -1) at = lines.length;
+    while (at > 0 && lines[at - 1].startsWith("#")) at--;
+    const block = [
+      "# The workspace. pnpm always includes the root project; each app",
+      "# `create-astroid --into` scaffolds is listed here.",
+      "packages:",
+      `  - ${path}`,
+      "",
+    ];
+    return [...lines.slice(0, at), ...block, ...lines.slice(at)].join("\n");
+  }
+
+  const at = lines.findIndex((line) => /^packages\s*:/.test(line));
+  const rest = lines[at].replace(/^packages\s*:/, "").trim();
+  if (rest.startsWith("[")) {
+    // A flow list with no comment after it is one line to rewrite; anything
+    // fancier is left to a person.
+    if (!/^\[[^\]]*\]$/.test(rest)) return null;
+    const inner = rest.slice(1, -1).trim();
+    lines[at] = `packages: [${inner ? `${inner}, ` : ""}${JSON.stringify(path)}]`;
+    return lines.join("\n");
+  }
+  if (rest && !rest.startsWith("#")) return null;
+
+  // A block list: append after its last item, at its indentation.
+  let last = at;
+  let indent = "  ";
+  for (let i = at + 1; i < lines.length; i++) {
+    if (/^\s*(#.*)?$/.test(lines[i])) continue;
+    const item = lines[i].match(/^(\s+)-/);
+    if (!item) break;
+    last = i;
+    indent = item[1];
+  }
+  lines.splice(last + 1, 0, `${indent}- ${path}`);
+  return lines.join("\n");
+}
+
+/** The name an app's root scripts are namespaced by: its directory's name. */
+export function intoScriptName(path) {
+  return path
+    .split("/")
+    .pop()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-");
+}
+
+/** The root scripts that run one app's commands from the repository root. */
+export function intoRootScripts(name, path) {
+  const inApp = `pnpm --dir ${path}`;
+  return {
+    [`dev:${name}`]: `${inApp} run dev`,
+    [`build:${name}`]: `${inApp} run build`,
+    [`doctor:${name}`]: `${inApp} run doctor`,
+    [`ship:${name}:production`]: `${inApp} exec astroid ship production`,
+    [`ship:${name}:preview`]: `${inApp} exec astroid ship preview`,
+  };
+}
+
+/**
+ * The root package.json's scripts with the app's added, never replacing one
+ * that exists: `skipped` names each that was already taken, so the caller can
+ * say so rather than overwrite someone's script.
+ */
+export function mergeRootScripts(existing, scripts) {
+  const merged = { ...existing };
+  const added = [];
+  const skipped = [];
+  for (const [name, command] of Object.entries(scripts)) {
+    if (name in merged) skipped.push(name);
+    else {
+      merged[name] = command;
+      added.push(name);
+    }
+  }
+  return { scripts: merged, added, skipped };
+}
+
+/**
+ * The settings of the new app's Workers Builds project. A second app is a
+ * second project, building from its own directory and deploying through
+ * `astroid ship`, so the deploy steps stay in the repository.
+ */
+export function workersBuildsSettings(path) {
+  return [
+    ["Root directory", path],
+    ["Build command", "pnpm run build"],
+    ["Deploy command", "pnpm exec astroid ship production"],
+    ["Non-production branch deploy command", "pnpm exec astroid ship preview"],
+    ["Production branch", "deploy/production"],
+  ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astroid",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "description": "Scaffold a new Astroid site — an editable, multi-editor Astro app on Cloudflare Workers — in one command.",
   "keywords": [
     "astro",
@@ -23,6 +23,7 @@
   },
   "files": [
     "index.mjs",
+    "into.mjs",
     "template",
     "toolkit-ranges.mjs"
   ],
@@ -32,10 +33,10 @@
   },
   "dependencies": {
     "@better-auth/passkey": "^1.7.2",
-    "@louise-toolkit/astro": "^0.5.0",
-    "astroidjs": "0.18.0",
+    "@louise-toolkit/astro": "^0.6.0",
+    "astroidjs": "0.20.0",
     "better-auth": "^1.7.2",
-    "louise-toolkit": "^0.36.0"
+    "louise-toolkit": "^0.37.0"
   },
   "engines": {
     "node": ">=26.0.0"

package/template/README.md

@@ -84,15 +84,17 @@ There are no passwords and no editor list in env to keep in sync.
    bar** appears with **Settings** and **Done**.
 3. The home page's **title and body are editable in place**—click into them and
    type. Edits stage a **draft**; **Publish** (in the edit bar) promotes it live.
-   **Settings** opens the drawer: **Pages** (create/edit other pages), **Media**,
+   **Settings** opens the drawer: **Pages** (create/edit other pages, each served
+   at its slug once published, such as `/about`), **Media**,
    **Settings** (brand, nav, contact, SEO), and **Users** (invite/remove editors).
    **Done** leaves edit mode.
 
 Inline editing uses Astroid's [`<Editable>`](https://github.com/bowenlabs/louise-toolkit)
-primitive (`src/pages/index.astro`): it stamps the `data-louise-*` markers only in
-edit mode, so the public HTML stays clean. Wrap any page field in `<Editable
-collection="pages" key={page.id} field="…">` and pass `versionedPageId` to make it
-editable. Body HTML is sanitized on every save.
+primitive (`src/pages/index.astro` for the home page, `src/pages/[...slug].astro`
+for every other page, both reading through `src/lib/pages.ts`): it stamps the
+`data-louise-*` markers only in edit mode, so the public HTML stays clean. Wrap
+any page field in `<Editable collection="pages" key={page.row.id} field="…">` and
+pass `versionedPageId` to make it editable. Body HTML is sanitized on every save.
 
 ## Redeploy
 

package/template/_app/README.md

@@ -0,0 +1,62 @@
+# __BRAND_NAME__
+
+An app on Cloudflare Workers with no pages to edit, scaffolded with
+[Astroid](https://docs.astroidjs.org) (Astro + Louise Toolkit) in its
+editor-free shape (`editor: false`).
+
+It has no Louise editor: no sign-in for editors, no content tables, no media
+library. Its settings, if it reads any, belong to a site that has an editor, and
+that site stays the only place they're edited. What Astroid still generates
+here is the rate limiter, the Content-Security-Policy, the security headers,
+the public status route, and whatever modules the config switches on: a
+customer portal, an installable app (PWA), or commerce.
+
+The whole shape lives in one typed config, [`astroid.config.ts`](./astroid.config.ts).
+`src/schema.ts`, `src/worker.ts`, and `src/middleware.ts` are **generated** from
+it (they carry a "do not hand-edit" banner). Run `pnpm generate` after any
+config change, or use `pnpm dev` and `pnpm build`, which regenerate first.
+
+## Develop
+
+```sh
+pnpm install
+cp .env.example .dev.vars   # local secrets for `astro dev`
+pnpm dev                    # astroid dev: regenerate, then astro dev
+```
+
+## The API
+
+The web app is the first client of a versioned JSON API under `/api/v1`
+(`src/pages/api/v1/`). A native client later calls the same routes, so each
+one answers JSON, reads its input from the body or the URL, and needs no
+browser-only header. The middleware rate-limits every POST under `/api/v1`.
+
+## Deploy
+
+Astroid wrote `wrangler.jsonc` with placeholder binding ids:
+
+```sh
+pnpm astroid provision   # create the D1 database and the RL namespace, filling in their ids
+pnpm run doctor          # validate config, bindings, and generated-file freshness
+pnpm astroid ship production
+```
+
+### Sharing another app's database
+
+To read tables another app owns, such as its `site_settings`, bind its D1
+database by id in `wrangler.jsonc` and set `deploy: { migrations: false }` in
+`astroid.config.ts`. One app owns a database's schema: this one then applies no
+migrations, and an additive migration in the other app ships in a release
+before this app's code reads it.
+
+## Layout
+
+| Path | What |
+| --- | --- |
+| `astroid.config.ts` | The one typed config. |
+| `src/schema.ts` · `src/worker.ts` · `src/middleware.ts` | **Generated**—don't hand-edit. |
+| `src/schema.site.ts` | This app's own Drizzle tables, if it has any. |
+| `wrangler.jsonc` | Yours to edit—real binding ids, routes, secrets. |
+| `src/pages/api/v1/` | The versioned JSON API. |
+| `src/pages/` · `src/components/` · `src/layouts/` | Your Astro app. |
+| `docs/` | ARCHITECTURE · RUNBOOK · DECISIONS—stubs to fill in as you go. |

package/template/_app/_env.example

@@ -0,0 +1,12 @@
+# Local dev secrets (wrangler reads .dev.vars; copy this there for `astro dev`).
+# In production these are set with `wrangler secret put`, NOT committed.
+#
+# Astroid's convention: an unprovisioned secret leaves its feature DORMANT, never
+# broken. A secret that is empty, or still holds the DUMMY_REPLACE_ME sentinel,
+# reads as "not configured", so a fresh clone boots and runs with no external
+# accounts at all. Replace a value to switch that feature on.
+#
+# This app has no editor, so it needs no editor sign-in secrets. Anything below
+# belongs to a module your config switched on.
+__ASTROID_APP_SECRETS__
+__ASTROID_MODULE_SECRETS__

package/template/_app/astro.config.mjs

@@ -0,0 +1,37 @@
+// @ts-check
+import cloudflare from "@astrojs/cloudflare";
+import { cacheCloudflare } from "@astrojs/cloudflare/cache";
+import solid from "@astrojs/solid-js";
+import tailwindcss from "@tailwindcss/vite";
+import { ASTROID_VITE_BUILD, astroidSecurity } from "astroidjs/astro";
+import { defineConfig } from "astro/config";
+import astroidConfig from "./astroid.config.ts";
+
+// SSR (`output: server`) because an app answers per request: its JSON API under
+// /api/v1, and pages that read live data. Solid islands for the interactive UI.
+// Tailwind v4 + daisyUI drive the theme (src/styles/site.css). Cloudflare
+// *bindings* are read via `import { env } from "cloudflare:workers"` (typed in
+// src/env.d.ts), so there is no astro:env schema here.
+export default defineConfig({
+  site: "__SITE_URL__",
+  output: "server",
+  adapter: cloudflare(),
+  integrations: [solid()],
+  vite: {
+    plugins: [tailwindcss()],
+    build: { ...ASTROID_VITE_BUILD },
+  },
+  // Route caching (ADR 0004). This provider is what turns `Astro.cache.set(...)`
+  // into a `Cloudflare-CDN-Cache-Control` header, which the generated worker's
+  // `withEdgeCache` layer reads as its "store this" signal and then strips, so
+  // Cloudflare's own cookie-blind edge cache never sees it. Nothing is cached
+  // unless a route opts in, and a route that reads a signed-in customer never
+  // should.
+  cache: { provider: cacheCloudflare() },
+  // Content-Security-Policy, composed by Astroid from your config: the origins
+  // your modules need (a commerce provider's card SDK) plus the hash of Solid's
+  // hydration bootstrap. Astro owns `script-src`, so avoid is:inline and
+  // define:vars scripts, which can't be hashed and would be blocked. Need
+  // another origin? Add it to `security.cspOrigins` in astroid.config.ts.
+  security: astroidSecurity(astroidConfig),
+});

package/template/_app/src/env.d.ts

@@ -0,0 +1,33 @@
+/// <reference path="../.astro/types.d.ts" />
+/// <reference types="astro/client" />
+/// <reference types="@cloudflare/workers-types" />
+
+// The Cloudflare bindings this app's Worker exposes (wrangler.jsonc), read via
+// `import { env } from "cloudflare:workers"`. An app with no editor binds only
+// what it uses. Add a binding here when you add one to wrangler.jsonc (a KV
+// namespace for a cache, a Queue, a Durable Object).
+type CloudflareEnv = {
+  /** D1: this app's own tables, or the database of the app that owns the schema. */
+  DB: D1Database;
+  /** The app's public origin, declared in wrangler.jsonc `vars`. */
+  SITE_URL: string;
+  /** KV: the security rate limiter. */
+  RL: KVNamespace;
+  /** Static assets (bound by the @astrojs/cloudflare adapter). */
+  ASSETS: Fetcher;__ASTROID_ENV_BINDINGS__
+};
+
+// `env` from `cloudflare:workers` is typed as the augmentable `Cloudflare.Env`.
+declare namespace Cloudflare {
+  interface Env extends CloudflareEnv {}
+}
+
+// Middleware sets these; bindings themselves come from `cloudflare:workers`.
+declare namespace App {
+  interface Locals {
+    /** Always null: this app has no editor, so no request resolves to one. */
+    editor: null;
+    /** Always false, for the same reason. The shared middleware still sets it. */
+    editMode: boolean;__ASTROID_PORTAL_LOCALS__
+  }
+}

package/template/_app/src/layouts/App.astro

@@ -0,0 +1,49 @@
+---
+// The base HTML shell. This app has no editor, so there's no settings row it
+// owns and no edit mode: the head comes from astroid.config.ts, and a page
+// overrides the title or description through props.
+//
+// Reading another app's settings (opening hours, a tagline) is a query against
+// its table: import `siteSettings` from "louise-toolkit/db" where you need it.
+import Credit from "astroidjs/components/Credit.astro";
+import Seo from "astroidjs/components/Seo.astro";
+import astroidConfig from "../../astroid.config.js";
+import "../styles/site.css";
+
+interface Props {
+  title?: string;
+  description?: string;
+  /** Keep this page out of search indexes (account, order status). */
+  noindex?: boolean;
+}
+
+const { title, description, noindex } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en" data-theme="light">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <Seo
+      settings={{ siteName: astroidConfig.theme.name }}
+      title={title}
+      description={description}
+      noindex={noindex}
+      titleTemplate={astroidConfig.seo?.titleTemplate}
+      twitterHandle={astroidConfig.seo?.twitterHandle}
+      locale={astroidConfig.seo?.locale}
+    />
+  </head>
+  <body class="min-h-screen bg-base-100 text-base-content">
+    <slot />
+    {
+      /* The agency credit, when astroid.config.ts sets `credit`. */
+      astroidConfig.credit && (
+        <footer class="mx-auto flex max-w-6xl justify-center px-6 py-8">
+          <Credit config={astroidConfig} />
+        </footer>
+      )
+    }
+  </body>
+</html>

package/template/_app/src/pages/api/v1/index.ts

@@ -0,0 +1,22 @@
+// GET /api/v1—the root of this app's versioned JSON API.
+//
+// Every route the app's clients call lives under /api/v1: the web app first,
+// and a native client later against the same routes. So each one answers JSON,
+// reads its input from the body or the URL (never an HTML form post), and
+// needs no browser-only header. A breaking change is a new prefix, /api/v2,
+// beside this one, because a native client on a customer's phone updates on
+// its own schedule.
+//
+// The generated middleware rate-limits every POST under /api/v1 per client IP.
+// Add a tighter rule for one route with `security.rateRules` in
+// astroid.config.ts.
+import type { APIRoute } from "astro";
+import astroidConfig from "../../../../astroid.config.js";
+
+export const prerender = false;
+
+export const GET: APIRoute = () =>
+  Response.json(
+    { name: astroidConfig.theme.name, version: "v1" },
+    { headers: { "cache-control": "no-store" } },
+  );

package/template/_app/src/pages/index.astro

@@ -0,0 +1,18 @@
+---
+// The app's first screen. Replace it with yours. It reads its data from the
+// same versioned JSON API a native client would call (src/pages/api/v1/), so
+// the web app stays that API's first client rather than a special case.
+import App from "../layouts/App.astro";
+
+export const prerender = false;
+---
+
+<App>
+  <main class="mx-auto flex min-h-screen max-w-xl flex-col justify-center gap-4 px-6 py-16">
+    <h1 class="text-4xl font-bold">__BRAND_NAME__</h1>
+    <p class="text-base-content/70">
+      This app has no pages to edit. Build its screens here, and its API under
+      <code>/api/v1</code>.
+    </p>
+  </main>
+</App>

package/template/_app/src/pages/sitemap.xml.ts

@@ -0,0 +1,24 @@
+// sitemap.xml—the app's public screens. Scaffolded once and yours to edit: add
+// each screen a search engine should find to `entries`.
+//
+// It doesn't read a `pages` table, even when this app shares a database with a
+// site that has one: those pages are served from the site's origin, not this
+// app's. `astroidSitemapXml` drops anything matching the config's noindex
+// prefixes, so this file and robots.txt can never disagree.
+import type { APIRoute } from "astro";
+import { astroidSitemapXml, type SitemapEntry } from "astroidjs";
+import astroidConfig from "../../astroid.config.js";
+
+export const prerender = false;
+
+export const GET: APIRoute = (context) => {
+  const origin = new URL(context.request.url).origin;
+  const entries: SitemapEntry[] = [{ path: "/" }];
+
+  return new Response(astroidSitemapXml(astroidConfig, entries, { origin }), {
+    headers: {
+      "content-type": "application/xml; charset=utf-8",
+      "cache-control": "public, max-age=3600",
+    },
+  });
+};

package/template/src/layouts/Site.astro

@@ -6,6 +6,7 @@
 // description, and OG image, and a page overrides any of them via props.
 // <StructuredData> emits the schema.org graph (business + WebSite), with the
 // business `@type` chosen from your archetype.
+import Credit from "astroidjs/components/Credit.astro";
 import Seo from "astroidjs/components/Seo.astro";
 import StructuredData from "astroidjs/components/StructuredData.astro";
 import { env } from "cloudflare:workers";
@@ -96,6 +97,15 @@ const settings = {
   </head>
   <body class="min-h-screen bg-base-100 text-base-content" data-edit-mode={editMode ? "" : undefined}>
     <slot />
+    {
+      /* The agency credit, when astroid.config.ts sets `credit`. A site with
+         its own footer can move <Credit config={astroidConfig} /> into it. */
+      astroidConfig.credit && (
+        <footer class="mx-auto flex max-w-6xl justify-center px-6 py-8">
+          <Credit config={astroidConfig} />
+        </footer>
+      )
+    }
     <LouiseEdit versionedPageId={versionedPageId} sections={sections} />
     {
       /* Real-visitor Core Web Vitals. A static file from public/, so it is

package/template/src/lib/pages.ts

@@ -0,0 +1,118 @@
+// Read one `pages` row for rendering. The home page and the catch-all page route
+// both call this, so every page renders the same way: a visitor sees the live
+// row, and an editor in edit mode sees the latest pending draft laid over it, so
+// in-progress edits resume across reloads.
+import { isPageLive } from "louise-toolkit/content";
+
+/** The columns a page render reads. */
+export interface PageRow {
+  id: number;
+  slug: string;
+  /** The on-page H1. The head's <title> comes from `seo_title`, else this. */
+  title: string;
+  body: string | null;
+  /** The page-builder array, stored as a JSON string in D1. */
+  sections: string | null;
+  status: string | null;
+  seo_title: string | null;
+  seo_description: string | null;
+  og_image: string | null;
+  noindex: number | null;
+}
+
+/** What a page renders: its row, plus the title, body, and sections to show. */
+export interface RenderedPage {
+  row: PageRow;
+  title: string;
+  body: string;
+  sections: unknown[];
+}
+
+interface ReadPageOptions {
+  /** Edit mode shows every page, live or not, with its pending draft. */
+  editMode: boolean;
+  /**
+   * Show a visitor only a live page (`status = 'published'`). Default `true`.
+   * The home page passes `false`, so an unpublished home keeps rendering
+   * rather than turning the site's front door into a 404.
+   */
+  requireLive?: boolean;
+}
+
+// `sections` is a JSON string in D1. Bad JSON is a render-time non-event: the
+// page falls back to its prose body rather than failing on one malformed row.
+function parseSections(raw: unknown): unknown[] {
+  if (Array.isArray(raw)) return raw;
+  if (typeof raw !== "string" || !raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The page at `slug`, or `null` when there's none a visitor may see (or no
+ * database yet, before provisioning). A `null` is a 404, and the middleware's
+ * `redirectFor` then answers a renamed page's old URL with a redirect.
+ */
+export async function readPage(
+  db: D1Database,
+  slug: string,
+  { editMode, requireLive = true }: ReadPageOptions,
+): Promise<RenderedPage | null> {
+  let row: PageRow | null = null;
+  try {
+    row = await db
+      .prepare(
+        "SELECT id, slug, title, body, sections, status, seo_title, seo_description, og_image, noindex FROM pages WHERE slug = ?",
+      )
+      .bind(slug)
+      .first<PageRow>();
+  } catch {
+    // No DB binding yet (pre-provision).
+    return null;
+  }
+  if (!row) return null;
+  // The toolkit's one definition of "a visitor can see it" (ADR 0021).
+  if (!editMode && requireLive && !isPageLive({ status: row.status ?? undefined })) return null;
+
+  const page: RenderedPage = {
+    row,
+    title: row.title,
+    body: row.body ?? "",
+    sections: parseSections(row.sections),
+  };
+  if (!editMode) return page;
+
+  // The latest PENDING draft: newer than every version ever published. An
+  // older draft is superseded, since a publish already moved past it, so it
+  // must not come back just because it's the newest row marked `draft`.
+  try {
+    const draft = await db
+      .prepare(
+        "SELECT version_data FROM pages_versions WHERE parent_id = ?1 AND status = 'draft'" +
+          " AND id > COALESCE((SELECT MAX(id) FROM pages_versions WHERE parent_id = ?1 AND status = 'published'), 0)" +
+          " ORDER BY id DESC LIMIT 1",
+      )
+      .bind(row.id)
+      .first<{ version_data: string }>();
+    if (draft?.version_data) {
+      const d = JSON.parse(draft.version_data) as {
+        title?: unknown;
+        body?: unknown;
+        sections?: unknown;
+      };
+      if (typeof d.title === "string") page.title = d.title;
+      if (typeof d.body === "string") page.body = d.body;
+      // Sections stage as drafts like any other field, so edit mode renders the
+      // draft's array; otherwise section edits would vanish on reload while
+      // title edits survive.
+      if (d.sections !== undefined) page.sections = parseSections(d.sections);
+    }
+  } catch {
+    // Non-fatal: fall back to the live row.
+  }
+  return page;
+}