@michaelthielemann/kestrel 1.7.0 → 2.1.0

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'
@@ -12,8 +12,9 @@ import { withResolveScope } from '../../../../core/server/utils/resolve-scope'
 import { runAsRenderer } from '../../../../access/server/utils/render-context'
 import { htmlKeyForRoute } from './route-keys'
 import { staleRoutes, type DepsStore } from './deps'
-import { recordPublishStatus, clearPublishStatus, renderOutcome } from './publish-status'
+import { recordPublishStatus, clearPublishStatus, renderOutcome, lastPublishedAt } from './publish-status'
 import { routesToPrune, type Invalidation } from './invalidation'
+import { pendingRoutes, heldRoutes } from './pending'
 
 /**
  * The runtime static publisher: renders public routes from the LIVE server (`localFetch`, the same
@@ -28,6 +29,7 @@ interface OutputRc {
   dir: string
   publicDir: string
   auto: boolean
+  publishOnSave: boolean
   reconcileMinutes: number
   verbose: boolean
   s3: { bucket: string; region: string; endpoint: string; prefix: string; accessKeyId: string; secretAccessKey: string; sessionToken: string }
@@ -69,6 +71,11 @@ export async function renderRoute(route: string): Promise<{ body: Buffer | null;
  *  route set is INCOMPLETE, so it must never be used as the authority for what to delete. */
 export interface PublishedRoutes {
   routes: string[]
+  /** Each route's record `updatedAt` in ms — the "last saved" half of the saved-vs-published comparison. */
+  savedAt: Map<string, number>
+  /** Each route's owning record as its deps tag (`<coll>:<id>`) — route strings move on a rename, records
+   *  do not, so withholding a renamed page needs the identity behind the route. */
+  recordTag: Map<string, string>
   /** Names of collections whose route query threw (drifted schema, locked DB) — routes are missing. */
   failed: string[]
 }
@@ -82,6 +89,8 @@ export function allPublishedRoutes(): PublishedRoutes {
   const prefixPrimary = prefixPrimaryLocale()
   const pub = publicReadableResources()
   const routes = new Set<string>([localePath('/', primary, primary, prefixPrimary)]) // `/` or `/<primary>`
+  const savedAt = new Map<string, number>()
+  const recordTag = new Map<string, string>()
   const failed: string[] = []
   for (const c of allCollections()) {
     if (!c.def.pageLike || !isPubliclyReadable(c.def.name, pub)) continue
@@ -94,6 +103,10 @@ export function allPublishedRoutes(): PublishedRoutes {
     const proj: Record<string, unknown> = { path: cols.path }
     if (c.def.translatable) proj.locale = cols.locale
     if (c.def.status) proj.status = cols.status
+    // `updatedAt` is a system column on every built collection, but this projection also runs against
+    // hand-rolled tables in tests — guard it exactly like `locale`, or its absence throws the select.
+    if (Object.hasOwn(cols, 'updatedAt')) proj.updatedAt = cols.updatedAt
+    if (Object.hasOwn(cols, 'id')) proj.id = cols.id
     let rows: Record<string, unknown>[]
     try { rows = db.select(proj as never).from(c.table).all() as Record<string, unknown>[] }
     catch (error) {
@@ -106,10 +119,17 @@ export function allPublishedRoutes(): PublishedRoutes {
     for (const row of rows) {
       if (c.def.status && row.status !== 'published') continue
       const route = pageRowHref(row, primary, prefixPrimary) // the shared (path, locale) → route rule
-      if (route) routes.add(route)
+      if (!route) continue
+      routes.add(route)
+      const saved = row.updatedAt
+      if (saved instanceof Date) savedAt.set(route, saved.getTime())
+      else if (typeof saved === 'number') savedAt.set(route, saved)
+      // The same tag the publisher records against a rendered route, so a route can be traced back to its
+      // record even after a rename moved the route string.
+      if (typeof row.id === 'number') recordTag.set(route, `${c.def.name}:${row.id}`)
     }
   }
-  return { routes: [...routes], failed }
+  return { routes: [...routes], savedAt, recordTag, failed }
 }
 
 /** Render + write the given routes (skips non-200). When `deps` is given, each render is wrapped in a
@@ -165,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)
   }
 }
 
@@ -198,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.
@@ -226,7 +252,7 @@ export async function publishFull(driver: StorageDriver = outputDriver(), deps?:
   // runs late (layer-then-filename order) — finish populating the registry first. Moving the read before
   // an await would silently render an empty registry. See docs/architecture.md → "Server plugins".
   await syncStaticAssets(driver, cfg.publicDir)
-  const { routes, failed } = allPublishedRoutes()
+  const { routes, savedAt, recordTag, failed } = allPublishedRoutes()
   if (failed.length) {
     // Keep on doubt: with a collection missing from the enumeration, every one of its live pages looks
     // stale, so a prune would wipe it from the output. Rendering still proceeds — a stale extra file is
@@ -234,12 +260,27 @@ export async function publishFull(driver: StorageDriver = outputDriver(), deps?:
     console.error(`[kestrel] publish: prune skipped — routes of ${failed.join(', ')} could not be enumerated; existing files kept`)
   }
 
+  // A full run resynchronizes the output with the DB, so without this it would push every saved-but-
+  // unpublished edit live — exactly what deferring the publish exists to prevent. Those routes keep the
+  // file their last publish wrote.
+  // …unless the consumer opted out of the split (`output.publishOnSave`): there, a save IS a publish, so
+  // "saved after the last publish" means a republish is merely in flight, not deliberately withheld.
+  // Computed BEFORE the prune, because a held record's live file may sit at a route the DB no longer names
+  // (an unpublished rename), and that file is what the site is still serving. Without `deps` there is no
+  // way to find those prior routes, so only same-route withholding applies — the pre-rename behaviour.
+  const { hold, keep } = cfg.publishOnSave
+    ? { hold: new Set<string>(), keep: new Set<string>() }
+    : heldRoutes(savedAt, lastPublishedAt(useDb()), recordTag, (tag) => deps?.routesForTags([tag]) ?? [])
+  if (hold.size) {
+    console.info(`[kestrel] publish: ${hold.size} route(s) held at their published version (unpublished changes): ${[...hold].join(', ')}`)
+  }
+
   // Targeted prune: a route we previously published that is no longer in the published set — a page
   // unpublished, deleted, or whose slug changed — must lose its static file. Safe because it only deletes
   // files this publisher wrote (tracked in deps, durable across restarts). Output ≡ DB; no opt-in toggle.
   let pruned = 0
   if (deps && !failed.length) {
-    const stale = staleRoutes(deps.routes(), routes)
+    const stale = staleRoutes(deps.routes(), routes).filter((route) => !keep.has(route))
     if (stale.length) {
       await prunePages(stale, driver)
       for (const route of stale) deps.forget(route)
@@ -247,11 +288,13 @@ export async function publishFull(driver: StorageDriver = outputDriver(), deps?:
     }
   }
 
+  const renderRoutes = routes.filter((route) => !hold.has(route))
+
   // Reset the discovery accumulator so this full run reconciles ONLY what it actually renders — an earlier
   // incremental (tag) publish also feeds the accumulator, and a variant it recorded whose usage was later
   // removed would otherwise survive and be re-registered here (defeating usage-driven narrowing).
   clearVariants()
-  const written = await publishRoutes(routes, driver, deps)
+  const written = await publishRoutes(renderRoutes, driver, deps)
   const rendered = written.length
   await publishMeta(driver)
   // Auto-discovery: a FULL render just visited every published route, so the capture accumulator now holds
@@ -260,8 +303,10 @@ export async function publishFull(driver: StorageDriver = outputDriver(), deps?:
   // by the un-rendered routes. ONLY narrow when EVERY route rendered: a partial failure leaves the accumulator
   // incomplete, so reconciling would deregister variants still referenced by the stale (kept) published HTML,
   // which a later backfill would then delete out from under the live page. An un-enumerated collection is
-  // the same partial-coverage case: its pages were never visited, so their variants are missing too.
-  if (!failed.length && rendered === routes.length) saveDiscoveredVariants(useDb())
+  // the same partial-coverage case: its pages were never visited, so their variants are missing too — and
+  // so is a route held back at its published version: its live file still references the variants this run
+  // never saw.
+  if (!failed.length && !hold.size && rendered === renderRoutes.length) saveDiscoveredVariants(useDb())
   return { rendered, pruned }
 }
 
@@ -270,13 +315,39 @@ export async function publishFull(driver: StorageDriver = outputDriver(), deps?:
  *  (their `<lastmod>` may have changed). */
 export interface PublishResult { rendered: string[]; pruned: string[]; counts: { rendered: number; pruned: number } }
 
+/**
+ * Drop the routes a tag match dragged in that are holding their published version back. Withholding is a
+ * property of the ROUTE, not of the full publish: a route whose record was saved after its last publish
+ * serves that published file until someone publishes it. Without this, publishing one record re-renders
+ * every route tagged with the collection — and every route reads the `site` singleton — from the live DB,
+ * so a routine Publish writes an unrelated record's withheld body to the live site.
+ *
+ * A route named in `render` is exempt: it IS what the publish was for, and pressing Publish is what clears
+ * the withholding. The prune set is untouched — removal has no publish intent left to protect, so an
+ * unpublished or deleted record's page still goes at once (ADR-0008).
+ *
+ * The cost, deliberately accepted: a withheld route keeps the baked links and hreflang of its last
+ * publish, so a link to a record that has since been unpublished stays stale until the referrer itself is
+ * published. That is the same staleness its body already carries — a frozen route is one publish
+ * generation throughout, rather than a mix of two. Rendering a referrer from its published state while
+ * resolving fresh links needs a published snapshot per record, which is ADR-0008's "Future".
+ */
+function withheldRemoved(inv: Extract<Invalidation, { type: 'tags' }>, routes: string[]): string[] {
+  if (outputConfig().publishOnSave) return routes // that mode never defers a publish in the first place
+  // An un-enumerable collection contributes no `savedAt` entry, so its routes are simply not withheld —
+  // the same direction publishFull takes, and the non-destructive one (a stale re-render, never a delete).
+  const held = new Set(pendingRoutes(allPublishedRoutes().savedAt, lastPublishedAt(useDb())))
+  const explicit = new Set(inv.render)
+  return routes.filter((route) => explicit.has(route) || !held.has(route))
+}
+
 export async function publishInvalidation(inv: Invalidation, driver: StorageDriver = outputDriver(), deps?: DepsStore): Promise<PublishResult> {
   if (inv.type === 'noop') return { rendered: [], pruned: [], counts: { rendered: 0, pruned: 0 } }
   if (inv.type === 'full') {
     const r = await publishFull(driver, deps) // full: counts only (don't list every route)
     return { rendered: [], pruned: [], counts: { rendered: r.rendered, pruned: r.pruned } }
   }
-  const routes = [...new Set([...(deps?.routesForTags(inv.tags) ?? []), ...inv.render])]
+  const routes = withheldRemoved(inv, [...new Set([...(deps?.routesForTags(inv.tags) ?? []), ...inv.render])])
   const rendered = await publishRoutes(routes, driver, deps)
   let pruned: string[] = []
   // Never prune a route we just wrote live — render wins a coalesced render+prune collision (see routesToPrune).

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
+}

package/layers/public/server/utils/publish/redirects-artifact.ts

@@ -0,0 +1,20 @@
+import type { StorageDriver } from '../../../../core/server/utils/storage'
+import { contentTypeFor, cacheControlFor } from '../../../modules/deploy-output/deploy-output'
+import { compileRedirects, serializeRedirects } from './redirect-rules'
+
+/** The collection and the repeater field the artifact is compiled from, named once. */
+export const REDIRECTS_COLLECTION = 'redirects'
+export const REDIRECTS_FIELD = 'rules'
+
+/** Literal key at the output root — a sibling of `index.html`, not a child of it. The driver's root IS
+ *  the output root (local `output.dir`, or the S3 prefix), so a key can never sit *beside* that tree. */
+export const REDIRECTS_KEY = 'redirects.json'
+
+/**
+ * Compile the editor's rows and publish them. Compilation runs first so an unpublishable rule fails
+ * before the driver is touched, and the writer never swallows: a rejection is the caller's to surface.
+ */
+export async function writeRedirectsArtifact(rows: unknown, driver: StorageDriver): Promise<void> {
+  const body = Buffer.from(serializeRedirects(compileRedirects(rows)))
+  await driver.put(REDIRECTS_KEY, body, contentTypeFor(REDIRECTS_KEY), { cacheControl: cacheControlFor(REDIRECTS_KEY) })
+}