@michaelthielemann/kestrel 2.0.0 → 2.1.0

package/layers/public/server/utils/llms-full.ts

@@ -0,0 +1,125 @@
+import type { CollectionDef, FieldDef } from '../../../core/server/utils/defineCollection'
+import { fieldIs } from '../../../core/server/utils/defineCollection'
+import { getBlock } from '../../../fields/server/utils/defineBlock'
+import { resolveRichtextLinks } from '../../../fields/app/utils/richtext-links'
+import { escapeMarkdownBlock, richtextToMarkdown } from './richtext-markdown'
+
+/** One published page rendered in full: what `llms.txt` links to, plus the body it links to. */
+export interface LlmsFullPage {
+  title: string
+  url: string
+  description?: string
+  /** Markdown; already heading-shifted to nest under the page's own `###`. */
+  body: string
+}
+
+/** A titled group of pages — one `## heading` block, mirroring `llms.txt`'s sections. */
+export interface LlmsFullSection {
+  heading: string
+  pages: LlmsFullPage[]
+}
+
+/** Pages sit at `###`, so a body's own `<h1>` has to start at `####` to keep the outline valid. */
+export const LLMS_FULL_HEADING_OFFSET = 3
+
+// Same defence as `llms.txt`: a title, heading or description is editor-authored text, and a newline in
+// it would forge a second document line — here, a heading that invents a page.
+const oneLine = (s: string): string => s.replace(/\s+/g, ' ').trim()
+
+/**
+ * Render an `llms-full.txt` (the long form of https://llmstxt.org): the site header, then every
+ * published, indexable page's full Markdown body under its own `###` heading, grouped by collection.
+ * Where `llms.txt` is a map, this is the territory — one document an answer engine can retrieve without
+ * crawling. Pure + deterministic; the route feeds it published, indexable pages only.
+ */
+export function buildLlmsFullTxt(opts: { siteName: string; siteDescription?: string; sections: LlmsFullSection[] }): string {
+  const blocks: string[] = [`# ${oneLine(opts.siteName)}`]
+  // A description is a whole block of its own, so flattening its newlines is not enough — a leading `##`
+  // would still open a section beside the ones this generator writes.
+  if (opts.siteDescription) blocks.push(`> ${escapeMarkdownBlock(oneLine(opts.siteDescription))}`)
+  for (const section of opts.sections) {
+    if (!section.pages.length) continue
+    blocks.push(`## ${oneLine(section.heading)}`)
+    for (const page of section.pages) {
+      blocks.push(`### ${oneLine(page.title)}`)
+      blocks.push(`Source: ${page.url}`)
+      if (page.description) blocks.push(escapeMarkdownBlock(oneLine(page.description)))
+      if (page.body) blocks.push(page.body)
+    }
+  }
+  return `${blocks.join('\n\n')}\n`
+}
+
+export interface RecordMarkdownOptions {
+  /** Push every body heading down by this many levels — see `LLMS_FULL_HEADING_OFFSET`. */
+  headingOffset?: number
+  /** Top-level field keys the caller already rendered (the title it used as the heading). */
+  skipFields?: string[]
+  /** `kestrel:<collection>:<id>` → absolute URL, or null for a target that must not be linked (a draft,
+   *  a noindexed page, a non-routable record). Unresolved links keep their text and lose the anchor. */
+  resolveLink?: (collection: string, id: number) => string | null
+}
+
+/** The prose in one flat value bag (record columns | block props | a repeater entry), in field order.
+ *  Only `text` and `richtext` carry prose; `repeater` recurses. Everything else is data, not content —
+ *  a consumer's own field type is skipped rather than guessed at. */
+function bagMarkdown(fields: Record<string, FieldDef>, bag: Record<string, unknown>, opts: RecordMarkdownOptions, skip?: Set<string>): string[] {
+  const out: string[] = []
+  for (const [key, field] of Object.entries(fields)) {
+    if (skip?.has(key)) continue
+    const value = bag[key]
+    if (field.type === 'text') {
+      // `fieldIs` rather than a switch: the open consumer-type arm makes `type` a non-discriminant, so a
+      // switch would not narrow (the same reason `extract-refs` walks this way).
+      // A text field is raw editor input with no markup to constrain it, so it is the one value that
+      // reaches the document verbatim — it needs the same block-marker escaping converted prose gets.
+      const text = typeof value === 'string' ? value.trim() : ''
+      if (text) out.push(escapeMarkdownBlock(text))
+    } else if (field.type === 'richtext') {
+      // Always run the marker rewrite, resolver or not: an unrewritten `kestrel:<coll>:<id>` href would
+      // ship a private storage token as a link target. With no resolver every marker declines to `#`,
+      // which the converter renders as plain text.
+      const html = typeof value === 'string' ? resolveRichtextLinks(value, opts.resolveLink ?? (() => null)) : ''
+      const md = richtextToMarkdown(html, { headingOffset: opts.headingOffset })
+      if (md) out.push(md)
+    } else if (fieldIs(field, 'repeater')) {
+      if (Array.isArray(value)) {
+        for (const entry of value) {
+          if (entry && typeof entry === 'object') out.push(...bagMarkdown(field.options.fields, entry as Record<string, unknown>, opts))
+        }
+      }
+    }
+  }
+  return out
+}
+
+/** The prose in a block `content` array, recursing slots — the same walk `extract-refs` does for refs. */
+function blockMarkdown(content: unknown, opts: RecordMarkdownOptions): string[] {
+  const out: string[] = []
+  const walk = (nodes: unknown): void => {
+    if (!Array.isArray(nodes)) return
+    for (const node of nodes) {
+      if (!node || typeof node !== 'object') continue
+      const n = node as { type?: string; props?: Record<string, unknown>; slots?: Record<string, unknown> }
+      // An unregistered block type has no field defs, so there is no way to tell its prose from its
+      // configuration — emitting every string prop would put layout tokens into the document.
+      const def = n.type ? getBlock(n.type) : undefined
+      if (def && n.props && typeof n.props === 'object') out.push(...bagMarkdown(def.fields, n.props, opts))
+      if (n.slots && typeof n.slots === 'object') for (const slotNodes of Object.values(n.slots)) walk(slotNodes)
+    }
+  }
+  walk(content)
+  return out
+}
+
+/**
+ * A record's readable content as Markdown: its own text/richtext fields (in declaration order), then its
+ * block tree if the collection enables blocks. Pure apart from the block registry — the same dependency
+ * `extractRecordRefs` has, and for the same reason: a block's prose is only identifiable through its
+ * registered field defs.
+ */
+export function recordMarkdown(def: CollectionDef, row: Record<string, unknown>, opts: RecordMarkdownOptions = {}): string {
+  const blocks = bagMarkdown(def.fields, row, opts, opts.skipFields?.length ? new Set(opts.skipFields) : undefined)
+  if (def.blocks?.enabled) blocks.push(...blockMarkdown(row.content, opts))
+  return blocks.join('\n\n')
+}

package/layers/public/server/utils/llms.ts

@@ -24,6 +24,19 @@ const oneLine = (s: string): string => s.replace(/\s+/g, ' ').trim()
 // Additionally escape the brackets that would otherwise break the `[title](url)` markdown link.
 const linkText = (s: string): string => oneLine(s).replace(/[[\]]/g, '\\$&')
 
+/** The `## heading` for a collection's section: its plural label in the primary locale, else any locale's,
+ *  else its capitalised name. Shared by `llms.txt` and `llms-full.txt` so the two never disagree. */
+export function collectionHeading(def: { name: string; label?: { plural?: unknown } }, primaryLocale: string): string {
+  const cap = (s: string) => (s ? s[0]!.toUpperCase() + s.slice(1) : s)
+  const plural = def.label?.plural
+  if (typeof plural === 'string') return plural
+  if (plural && typeof plural === 'object') {
+    const byLocale = plural as Record<string, string>
+    return byLocale[primaryLocale] ?? Object.values(byLocale)[0] ?? cap(def.name)
+  }
+  return cap(def.name)
+}
+
 export function buildLlmsTxt(opts: { siteName: string; siteDescription?: string; sections: LlmsSection[] }): string {
   const lines: string[] = [`# ${oneLine(opts.siteName)}`]
   if (opts.siteDescription) lines.push('', `> ${oneLine(opts.siteDescription)}`)

package/layers/public/server/utils/page-resolve.ts

@@ -1,12 +1,26 @@
-import { asc, eq, getTableColumns } from 'drizzle-orm'
+import { and, asc, eq, getTableColumns } from 'drizzle-orm'
 import { list } from '../../../core/server/utils/crud'
 import { captureRead } from '../../../core/server/utils/read-capture'
-import { translationGroupTag } from './publish/invalidation'
+import { pagePathTag, translationGroupTag } from './publish/invalidation'
 import type { BuiltCollection } from '../../../core/server/utils/collection-types'
 import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
 
 export interface PageAlternate { locale: string; path: string }
-export interface ResolvedPage { collection: string; page: Record<string, unknown>; alternates: PageAlternate[] }
+/** One published page above this one in the path hierarchy — a real, linkable breadcrumb step. */
+export interface PageAncestor {
+  path: string
+  title?: string
+  /** The ancestor's OWN locale, so the crumb builds the URL that was actually published. Absent for a
+   *  non-translatable collection, whose rows have a single unprefixed (primary-locale) URL — prefixing
+   *  one of those with the reader's locale would link a page `nuxt generate` never wrote. */
+  locale?: string
+}
+export interface ResolvedPage {
+  collection: string
+  page: Record<string, unknown>
+  alternates: PageAlternate[]
+  ancestors: PageAncestor[]
+}
 
 /** The matched page (or null) plus the collections whose lookup threw. `failed` is non-empty ⇒ the scan
  *  was INCOMPLETE, so `page: null` must never be treated as an authoritative "no such page". */
@@ -63,6 +77,92 @@ function publishedAlternates(db: BetterSQLite3Database, c: BuiltCollection, page
   return alternates.length >= 2 ? alternates : []
 }
 
+/** Every strict path prefix of a page's path, outermost first: `/blog/hello` → `['/', '/blog']`. The
+ *  site root is an ancestor of everything except itself. */
+function ancestorPaths(path: string): string[] {
+  if (path === '/' || !path.startsWith('/')) return []
+  const segments = path.split('/').filter(Boolean)
+  const paths = ['/']
+  for (let i = 1; i < segments.length; i += 1) paths.push(`/${segments.slice(0, i).join('/')}`)
+  return paths
+}
+
+/**
+ * The page's breadcrumb trail: the published, INDEXABLE page at each ancestor path, in the page's own
+ * locale. A path segment with no page behind it is SKIPPED rather than synthesised — schema.org
+ * breadcrumb items are links, and a trail that points at a 404 is a worse signal than a shorter trail.
+ * The filters mirror the sitemap's, so a breadcrumb never advertises what the sitemap withholds.
+ *
+ * TWO dependency edges are captured per ancestor, because neither covers the other:
+ *  - the PATH (`pagePathTag`), for every path looked in — including those with no page at all and those
+ *    whose lookup threw. Kestrel has no parent/child relation between pages, so an ancestor is a
+ *    path-prefix match, and a page CREATED at `/blog` after `/blog/hello` was published has no id anything
+ *    could have captured beforehand. A path is knowable before its page exists.
+ *  - the RECORD (`<coll>:<id>`) of whatever row sits there, captured before the filters below so a
+ *    currently-invisible one counts too — the edge that carries a rename, a `noindex` or an unpublish,
+ *    none of which `crumbTags` can see (see the comment at that capture).
+ * `publishedAlternates` pairs a group tag with a record tag for exactly the same reason.
+ */
+function publishedAncestors(
+  db: BetterSQLite3Database,
+  collections: BuiltCollection[],
+  path: string,
+  locale: string | undefined,
+  publishedOnly: boolean,
+): PageAncestor[] {
+  const out: PageAncestor[] = []
+  for (const ancestorPath of ancestorPaths(path)) {
+    // Before the scan, so the edge exists whatever the scan finds — no page, a draft, a noindexed one, or
+    // a collection whose table could not be read. A write at this path emits the same tag (`crumbTags` in
+    // classifyWrite), which is what repairs this page's trail.
+    captureRead(pagePathTag(ancestorPath))
+    for (const c of collections) {
+      if (!c.def.pageLike) continue
+      // Project only what a crumb needs — never the row: this runs once per path segment per render, and
+      // pulling every page's block JSON to read a title would multiply the cost of a full publish.
+      const cols = getTableColumns(c.table) as Record<string, never>
+      const hasStatus = Object.hasOwn(cols, 'status')
+      const proj: Record<string, unknown> = { id: cols.id, path: cols.path }
+      if (hasStatus) proj.status = cols.status
+      if (c.def.seo) proj.seo = cols.seo
+      if (c.def.translatable) proj.locale = cols.locale
+      if (Object.hasOwn(cols, 'title')) proj.title = cols.title
+      const scoped = c.def.translatable && locale ? and(eq(cols.path, ancestorPath), eq(cols.locale, locale)) : eq(cols.path, ancestorPath)
+      let row: { id: number; status?: string; seo?: { title?: string; noindex?: boolean } | null; title?: unknown; locale?: string } | undefined
+      try {
+        // Order by locale so an unscoped lookup (no locale requested) still answers deterministically
+        // rather than with whatever row the table happens to yield first.
+        const q = db.select(proj as never).from(c.table).where(scoped)
+        row = (c.def.translatable ? q.orderBy(asc(cols.locale)) : q).limit(1).get() as typeof row
+      } catch (error) {
+        // Same isolation rule as the main scan: a drifted collection loses its crumbs, loudly, instead of
+        // failing the whole render.
+        console.error(`[kestrel] resolvePage: skipped ancestor lookup in ${c.def.name}:`, (error as Error)?.message ?? error)
+        continue
+      }
+      if (!row) continue
+      // BOTH edges are needed, and neither subsumes the other — the same pairing `publishedAlternates`
+      // uses. The record tag covers every change to the row sitting here, INCLUDING the ones that make it
+      // stop being a crumb: the explicit publish action classifies its write as `before === after` (the
+      // record's current state), so a rename, a `noindex` or an unpublish is invisible in `crumbTags`,
+      // which only ever names where the record is NOW. `<coll>:<id>` is in that write's tag list whatever
+      // the row looks like, so it is what repairs the trail. Captured BEFORE the filters below, so a
+      // draft/noindexed/shadowing row — one that is currently NOT the crumb — still carries the edge that
+      // fires when it goes away.
+      captureRead(c.def.name, row.id)
+      if (publishedOnly && hasStatus && row.status !== 'published') break
+      if (row.seo?.noindex) break
+      const ancestor: PageAncestor = { path: ancestorPath }
+      const title = row.seo?.title || (typeof row.title === 'string' ? row.title : undefined)
+      if (title) ancestor.title = title
+      if (c.def.translatable && row.locale) ancestor.locale = row.locale
+      out.push(ancestor)
+      break
+    }
+  }
+  return out
+}
+
 /**
  * The first page-like record (across all collections, in registration order) whose `path` matches,
  * populated at depth 1 — or null, alongside the collections that could not be read at all. Reuses the
@@ -93,7 +193,15 @@ export function resolvePage(db: BetterSQLite3Database, collections: BuiltCollect
     const { data } = result
     if (data.length) {
       captureRead(c.def.name, (data[0] as { id?: number }).id ?? null)
-      return { page: { collection: c.def.name, page: data[0]!, alternates: publishedAlternates(db, c, data[0]!) }, failed }
+      return {
+        page: {
+          collection: c.def.name,
+          page: data[0]!,
+          alternates: publishedAlternates(db, c, data[0]!),
+          ancestors: publishedAncestors(db, collections, path, locale, publishedOnly),
+        },
+        failed,
+      }
     }
   }
   return { page: null, failed }

package/layers/public/server/utils/publish/invalidation.ts

@@ -28,6 +28,9 @@ export interface WriteClassification {
    *  static file must be pruned on a slug change / unpublish / delete (symmetric to `selfRoute`). */
   oldRoute: string | null
   groupTag: string | null
+  /** Page-path tags for the breadcrumb edge — this record's own path before and/or after the write (both,
+   *  on a rename); empty when it is nobody's crumb step on either side. See `pagePathTag`. */
+  crumbTags: string[]
 }
 
 /** The data tag naming a translation group. `#` keeps it clear of the `<coll>:<id>` record namespace. */
@@ -35,6 +38,27 @@ export function translationGroupTag(coll: string, group: string): string {
   return `${coll}#group:${group}`
 }
 
+/**
+ * The data tag naming a page-like PATH rather than a record — the edge a DESCENDANT's breadcrumb hangs on.
+ *
+ * It has to be the path, because Kestrel has no parent/child relation between pages: `path` is a plain
+ * column, a slug is flat unless an editor types slashes into it, and "descendant" is nothing but a
+ * path-prefix match. So the case that matters most — a page CREATED at `/blog` after `/blog/hello` was
+ * already published — has no record id that anything could have captured beforehand. A path, by contrast,
+ * is knowable before its page exists, so a descendant subscribes to the path it looked in.
+ *
+ * Deliberately locale-LESS: a non-translatable record has no locale to name, and a descendant looking up
+ * `/blog` in its own locale must still be reached when the page that appears there is a locale-less one.
+ * It therefore over-approximates across locales (an `en` `/blog` write also re-renders a `de` descendant
+ * of the same spelling) — extra renders, never a stale page.
+ *
+ * The leading `#` keeps it clear of the `<coll>` and `<coll>:<id>` namespaces (a collection name never
+ * starts with one).
+ */
+export function pagePathTag(path: string): string {
+  return `#path:${path}`
+}
+
 /** What to republish for a write. Routes are resolved from `tags` against the captured deps index. */
 export type Invalidation =
   | { type: 'full' }
@@ -59,6 +83,18 @@ function isPublic(def: WriteCollection, row: Row): boolean {
   return !!row && row.status === 'published'
 }
 
+/**
+ * The path this record contributes as a breadcrumb step, or null when it contributes none. Mirrors
+ * `publishedAncestors` exactly — that lookup skips anything unpublished, `noindex`ed or path-less, so a
+ * record in one of those states is in nobody's trail and its writes owe nobody a re-render.
+ */
+function crumbPath(def: WriteCollection, row: Row): string | null {
+  if (!def.pageLike || !row) return null
+  if (!isPublic(def, row)) return null
+  if ((row.seo as { noindex?: boolean } | null | undefined)?.noindex) return null
+  return typeof row.path === 'string' && row.path ? row.path : null
+}
+
 /** Reduce a before/after row pair (either may be null) to a `WriteClassification`. Pure (routes via the shared `pageRowHref`). */
 export function classifyWrite(def: WriteCollection, before: Row, after: Row, primaryLocale: string, prefixPrimary = false): WriteClassification {
   const status: WriteClassification['status'] = before === null ? 'created' : after === null ? 'deleted' : 'updated'
@@ -81,7 +117,14 @@ export function classifyWrite(def: WriteCollection, before: Row, after: Row, pri
   const group = row?.translationGroup
   const groupTag = typeof group === 'string' && group ? translationGroupTag(def.name, group) : null
 
-  return { collection: def.name, pageLike, status, id, pathChanged, statusChanged, isPublished, wasPublished, selfRoute, oldRoute, groupTag }
+  // Both sides, so a rename repairs the descendants of the OLD path as well as the new one. Deliberately
+  // NOT narrowed to "did the crumb's label actually change": the explicit publish action classifies its
+  // write as before === after (`publish.post.ts` — a re-render of the record's current state), so a diff
+  // would see nothing on the very publish that makes the crumb appear.
+  const crumbTags = [...new Set([crumbPath(def, before), crumbPath(def, after)].filter((p): p is string => p !== null))]
+    .map(pagePathTag)
+
+  return { collection: def.name, pageLike, status, id, pathChanged, statusChanged, isPublished, wasPublished, selfRoute, oldRoute, groupTag, crumbTags }
 }
 
 /**
@@ -133,7 +176,9 @@ export function planInvalidation(ev: WriteClassification): Invalidation {
   // Unlike recordTag (dropped on create — no referrer can target a brand-new id), groupTag is included even
   // there: a new sibling still changes every existing member's hreflang set.
   const groupTags = ev.groupTag ? [ev.groupTag] : []
-  const tags = recordTag ? [coll, recordTag, ...groupTags] : [coll, ...groupTags]
+  // Like groupTag, the crumb tags ride EVERY branch including create — a page appearing at an ancestor
+  // path is exactly what a descendant's breadcrumb was waiting for.
+  const tags = recordTag ? [coll, recordTag, ...groupTags, ...ev.crumbTags] : [coll, ...groupTags, ...ev.crumbTags]
   const selfRender = ev.pageLike && ev.selfRoute ? [ev.selfRoute] : []
 
   // DELETE — leaves the collection. Listings re-render, referrers too (their baked link/hreflang now points
@@ -147,7 +192,7 @@ export function planInvalidation(ev: WriteClassification): Invalidation {
   // record re-renders listings + its own route. No referrer can point at a brand-new id, so no `coll:id`.
   if (ev.status === 'created') {
     if (!ev.isPublished) return { type: 'noop' }
-    return { type: 'tags', tags: [coll, ...groupTags], render: selfRender, prune: [] }
+    return { type: 'tags', tags: [coll, ...groupTags, ...ev.crumbTags], render: selfRender, prune: [] }
   }
 
   // UNPUBLISH — leaves the published set. Listings re-render; referrers re-render so their link falls back to

package/layers/public/server/utils/publish/publisher.ts

@@ -4,7 +4,7 @@ import { getTableColumns } from 'drizzle-orm'
 import type { StorageDriver } from '../../../../core/server/utils/storage'
 import { createLocalDriver } from '../../../../core/server/utils/storage.local'
 import { createS3Driver } from '../../../../core/server/utils/storage.s3'
-import { contentTypeFor, cacheControlFor, precompressedEncoding } from '../../../modules/deploy-output/deploy-output'
+import { contentTypeFor, cacheControlFor, precompressedEncoding, META_KEYS, isMetaKey } from '../../../modules/deploy-output/deploy-output'
 import { localePath } from '../../../../core/app/utils/locale-path'
 import { pageRowHref } from '../../../../core/server/utils/page-route'
 import { withReadCapture } from '../../../../core/server/utils/read-capture'
@@ -185,11 +185,17 @@ export async function prunePages(routes: string[], driver: StorageDriver): Promi
   }
 }
 
-/** Render + write sitemap.xml, robots.txt and llms.txt (served at literal keys, not `<path>/index.html`). */
+/** Render + write the crawler/agent artifacts — sitemap/robots/llms/redirects, served at literal keys
+ *  rather than `<path>/index.html`.
+ *  A 404 means the route is switched off (`llms-full.txt` without `kestrel.seo.llmsFull`) — the file it
+ *  wrote while it WAS on must go, or the flag would stop publishing new content while the last full dump
+ *  stayed live. That is a deterministic route-level answer, not the incomplete-read case a delete must
+ *  never act on; any other non-200 leaves the existing file alone. */
 async function publishMeta(driver: StorageDriver): Promise<void> {
-  for (const key of ['sitemap.xml', 'robots.txt', 'llms.txt']) {
-    const { body } = await renderRoute(`/${key}`)
+  for (const key of META_KEYS) {
+    const { body, status } = await renderRoute(`/${key}`)
     if (body) await driver.put(key, body, contentTypeFor(key), { cacheControl: cacheControlFor(key) })
+    else if (status === 404) await driver.delete(key)
   }
 }
 
@@ -218,7 +224,7 @@ async function syncStaticAssets(driver: StorageDriver, publicDir: string): Promi
       // exactly like its uncompressed sibling, or it ships as a live sidecar for the fresh HTML rendered
       // below — served to any Accept-Encoding-negotiating client instead of the page just published.
       const base = rel.replace(/\.(?:br|gz)$/i, '')
-      if (!e.isFile() || base.endsWith('.html') || base === 'sitemap.xml' || base === 'robots.txt' || base === 'llms.txt') continue
+      if (!e.isFile() || base.endsWith('.html') || isMetaKey(base)) continue
       const bytes = await readFile(resolve(dir, e.name))
       // Tag a precompressed sibling (`.br`/`.gz` beside its base) with Content-Encoding so a proxy over S3
       // serves it directly; a standalone archive stays unencoded so browsers don't decode + corrupt it.

package/layers/public/server/utils/publish/redirect-rules.ts

@@ -0,0 +1,221 @@
+/**
+ * Compile the editor-authored redirect rows into the flat `redirects.json` artifact the edge consumes.
+ *
+ * Editors never write a regex: `from` is a path with `*` (one segment) or `**` (one or more) wildcards,
+ * and `to` may reference them positionally as `$1`, `$2`, … in authored order. The translation happens
+ * here — versioned, tested code — so the edge script only has to match and substitute.
+ *
+ * Pure by design (no Nuxt/Nitro imports): it is the executable spec for the edge as much as it is the
+ * artifact writer's input, which is why `matchRedirect` lives here even though nothing in Kestrel
+ * serves redirects at runtime.
+ */
+
+/** One entry of the published artifact. `pattern` is a regex SOURCE string, anchored, path-only. */
+export interface RedirectRule {
+  pattern: string
+  target: string
+  status: number
+}
+
+/** The statuses the editor offers. 301/302 cover SEO; 307/308 preserve the method on non-GET requests. */
+export const REDIRECT_STATUSES = ['301', '302', '307', '308'] as const
+
+/** A rule the editor has to fix. The message names the 1-based row so it is actionable in the UI. */
+export class RedirectRuleError extends Error {}
+
+const ESCAPE = /[.*+?^${}()|[\]\\-]/g
+// eslint-disable-next-line no-control-regex -- deliberately rejects control characters headed for a Location header
+const CONTROL = /[\u0000-\u001f\u007f]/
+const SCHEME = /^[a-z][a-z0-9+.-]*:/i
+
+function escapeLiteral(s: string): string {
+  return s.replace(ESCAPE, '\\$&')
+}
+
+/**
+ * What a wildcard may capture. This is a SECURITY boundary, not a convenience: a capture comes from the
+ * request, not from the editor, so `normalizeTarget`'s checks — which only ever saw the authored literal
+ * — say nothing about it. The pattern is the guard instead, and a request that would splice something
+ * dangerous into `Location` simply does not match and falls through to the origin.
+ *
+ * Excluded everywhere: a backslash (every browser resolves `Location: /\host` as `//host` — an open
+ * redirect) and the control characters that split a header (CR/LF) or terminate it (NUL, DEL).
+ * Additionally, a multi-segment capture may not START with `/`, or a target of `/$1` would become the
+ * protocol-relative `//host`. Anything a legitimate path contains still matches.
+ */
+const SEGMENT_CHAR = '[^/\\\\\\x00-\\x1f\\x7f]'
+const PATH_CHAR = '[^\\\\\\x00-\\x1f\\x7f]'
+const ONE_SEGMENT = `(${SEGMENT_CHAR}+)`
+const MANY_SEGMENTS = `(${SEGMENT_CHAR}${PATH_CHAR}*?)`
+
+/**
+ * Translate an authored `from` into an anchored regex source. Matching is path-only and case-sensitive;
+ * an authored trailing slash is dropped and one is tolerated at match time, so `/blog` and `/blog/` are
+ * the same rule.
+ */
+export function patternToRegexSource(from: string): string {
+  const raw = from.trim()
+  if (!raw) throw new RedirectRuleError('"From" must not be blank')
+  if (SCHEME.test(raw) || raw.startsWith('//')) {
+    throw new RedirectRuleError('"From" matches the request path only — drop the scheme and host')
+  }
+  if (/[?#]/.test(raw)) throw new RedirectRuleError('"From" must not contain a query string or fragment')
+  if (CONTROL.test(raw)) throw new RedirectRuleError('"From" must not contain control characters')
+  if (raw.includes('\\')) throw new RedirectRuleError('"From" must not contain a backslash')
+  if (raw.split('/').some((seg) => seg === '..')) throw new RedirectRuleError('"From" must not contain ".."')
+  // Two `**` with only a separator between them match the same thing through every split point, which is
+  // quadratic on a long path — seconds of CPU per request on a path an attacker chooses. It is also never
+  // what the author meant, so it is an authoring error rather than a limit to tune.
+  if (/\*\*\/?\*\*/.test(raw)) throw new RedirectRuleError('"From" has two `**` in a row — one already matches any number of segments')
+
+  const path = `/${raw.replace(/^\/+/, '').replace(/\/+$/, '')}`
+  if (path === '/') return '^/$'
+
+  let body = ''
+  let last = 0
+  for (const m of path.matchAll(/\*\*|\*/g)) {
+    body += escapeLiteral(path.slice(last, m.index)) + (m[0] === '**' ? MANY_SEGMENTS : ONE_SEGMENT)
+    last = m.index + m[0].length
+  }
+  return `^${body + escapeLiteral(path.slice(last))}/?$`
+}
+
+/** Number of capture groups `patternToRegexSource` emits for an authored `from`. */
+function wildcardCount(from: string): number {
+  return (from.trim().match(/\*\*|\*/g) ?? []).length
+}
+
+/**
+ * Normalize an authored `to` into a `Location` value. A path gets its leading slash; an absolute
+ * http(s) URL is kept verbatim (a moved domain is a legitimate target). Everything else is rejected —
+ * a `javascript:`/`data:` scheme or a protocol-relative `//host` would turn a redirect into a hazard.
+ */
+export function normalizeTarget(to: string): string {
+  const raw = to.trim()
+  if (!raw) throw new RedirectRuleError('"To" must not be blank')
+  if (CONTROL.test(raw)) throw new RedirectRuleError('"To" must not contain control characters')
+  if (raw.includes('\\')) throw new RedirectRuleError('"To" must not contain a backslash')
+  if (raw.startsWith('//')) {
+    throw new RedirectRuleError('"To" must not be protocol-relative — write the full https:// URL')
+  }
+  if (!SCHEME.test(raw)) return `/${raw.replace(/^\/+/, '')}`
+
+  if (!/^https?:\/\//i.test(raw)) throw new RedirectRuleError('"To" may only use http:// or https://')
+  let url: URL
+  try {
+    url = new URL(raw)
+  } catch {
+    throw new RedirectRuleError(`"To" is not a valid URL: ${raw}`)
+  }
+  if (!url.host) throw new RedirectRuleError('"To" is missing a host')
+  if (url.username || url.password) throw new RedirectRuleError('"To" must not embed credentials')
+  return raw
+}
+
+/**
+ * A placeholder inside an absolute target's HOST would let a visitor choose the destination
+ * (`https://neu.example.com$1` + a request of `/blog/.evil.com` → `https://neu.example.com.evil.com`).
+ * The capture classes cannot prevent that one — the hazard is where `$n` sits, not what it holds — so it
+ * is rejected at authoring time.
+ */
+function assertPlaceholdersAfterHost(target: string): void {
+  if (!SCHEME.test(target)) return
+  const firstPlaceholder = target.indexOf('$')
+  if (firstPlaceholder === -1) return
+  const pathStart = target.indexOf('/', target.indexOf('://') + 3)
+  if (pathStart === -1 || firstPlaceholder < pathStart) {
+    throw new RedirectRuleError('"To" may only use $1, $2, … after the host — a placeholder in the host lets a visitor pick the destination')
+  }
+}
+
+function readStatus(value: unknown): number {
+  const s = value === undefined || value === null || value === '' ? '301' : String(value)
+  if (!(REDIRECT_STATUSES as readonly string[]).includes(s)) {
+    throw new RedirectRuleError(`Status must be one of ${REDIRECT_STATUSES.join(', ')} (got ${s})`)
+  }
+  return Number(s)
+}
+
+function readText(value: unknown, what: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new RedirectRuleError(`${what} must not be blank`)
+  return value.trim()
+}
+
+/**
+ * Rows → artifact entries, in authored order (order IS priority: the edge takes the first match).
+ * An empty/absent field is zero redirects, which is a fully supported state — not an error.
+ * A row the edge could not honour throws instead of being dropped, so a typo fails the save loudly.
+ */
+export function compileRedirects(rows: unknown): RedirectRule[] {
+  if (rows === null || rows === undefined) return []
+  if (!Array.isArray(rows)) throw new RedirectRuleError('Redirect rules must be a list')
+
+  return rows.map((raw, i) => {
+    try {
+      const entry = (raw ?? {}) as Record<string, unknown>
+      const from = readText(entry.from, '"From"')
+      const target = normalizeTarget(readText(entry.to, '"To"'))
+      const groups = wildcardCount(from)
+      for (const [, n] of target.matchAll(/\$(\d+)/g)) {
+        if (Number(n) < 1 || Number(n) > groups) {
+          throw new RedirectRuleError(`"To" references $${n} but "From" has ${groups} wildcard(s)`)
+        }
+      }
+      // `${1}` is the plausible typo — it compiles clean and then ships verbatim in every Location, a
+      // rule that silently 404s. A bare `$` is left alone: it is a legal path character (RFC 3986
+      // sub-delim), and only `$` followed by digits is reserved.
+      if (/\$\{/.test(target)) {
+        throw new RedirectRuleError('"To" writes a placeholder as $1, $2, … — not ${1}')
+      }
+      assertPlaceholdersAfterHost(target)
+      return { pattern: patternToRegexSource(from), target, status: readStatus(entry.status) }
+    } catch (err) {
+      throw new RedirectRuleError(`Row ${i + 1}: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  })
+}
+
+/**
+ * The PUBLISHING counterpart of `compileRedirects`. Identical on data the save path accepted — which is
+ * all of it, since the collection's `validate` compiles every row before the write. The difference only
+ * shows after an upgrade that tightened a rule: a row stored by an older version would otherwise make
+ * this artifact unrenderable forever, taking every OTHER redirect down with it (and, at build time,
+ * suppressing the deploy's reconcile). Publishing the rest and naming what was dropped is the lesser
+ * failure; the editor learns about it the moment they next save, which is the strict path.
+ *
+ * A malformed `rows` still throws: that is a read bug, not a bad row, and `[]` would be a lie.
+ */
+export function compilePublishableRedirects(rows: unknown): { rules: RedirectRule[]; skipped: string[] } {
+  if (rows === null || rows === undefined) return { rules: [], skipped: [] }
+  if (!Array.isArray(rows)) throw new RedirectRuleError('Redirect rules must be a list')
+
+  const rules: RedirectRule[] = []
+  const skipped: string[] = []
+  rows.forEach((row, i) => {
+    try {
+      rules.push(...compileRedirects([row]))
+    } catch (error) {
+      skipped.push(`Row ${i + 1}: ${(error as Error).message.replace(/^Row 1: /, '')}`)
+    }
+  })
+  return { rules, skipped }
+}
+
+/** The artifact body. An empty list is a valid document (`[]`), never an absent file. */
+export function serializeRedirects(rules: RedirectRule[]): string {
+  return JSON.stringify(rules)
+}
+
+/**
+ * Reference implementation of the edge's match step — first rule that matches wins, `$n` substituted
+ * from the capture groups. Kestrel does not serve redirects; this pins the semantics the njs handler
+ * has to reproduce, and is what the tests assert against.
+ */
+export function matchRedirect(rules: RedirectRule[], path: string): { target: string; status: number } | null {
+  for (const rule of rules) {
+    const m = new RegExp(rule.pattern).exec(path)
+    if (!m) continue
+    return { target: rule.target.replace(/\$(\d+)/g, (_, n: string) => m[Number(n)] ?? ''), status: rule.status }
+  }
+  return null
+}