@michaelthielemann/kestrel 3.0.1 → 4.0.0

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

@@ -1,362 +0,0 @@
-import { readdir, readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
-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, 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'
-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, 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
- * handler `nuxt generate` uses) and writes them — plus the built `_nuxt` bundle + assets — through the
- * configured output StorageDriver (local dir or S3). This is the engine the manual `publish:run` task
- * and (later) the auto-trigger queue both drive. NOT unit-tested (needs a running build); the pure
- * pieces it composes (route-keys, invalidation, deps, queue) are.
- */
-
-interface OutputRc {
-  driver: 'local' | 's3'
-  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 }
-}
-
-export function outputConfig(): OutputRc {
-  return (useRuntimeConfig().kestrel as { output: OutputRc }).output
-}
-
-/** Build the output driver from runtimeConfig (local dir or S3 bucket) — separate from the media driver. */
-export function outputDriver(cfg: OutputRc = outputConfig()): StorageDriver {
-  if (cfg.driver === 's3') {
-    return createS3Driver({
-      bucket: cfg.s3.bucket, region: cfg.s3.region, endpoint: cfg.s3.endpoint || undefined, prefix: cfg.s3.prefix,
-      publicBaseUrl: '', accessKeyId: cfg.s3.accessKeyId, secretAccessKey: cfg.s3.secretAccessKey, sessionToken: cfg.s3.sessionToken || undefined,
-    })
-  }
-  return createLocalDriver({ dir: cfg.dir, baseUrl: '/' })
-}
-
-/** Render a public route via the in-process server, returning its HTML buffer (200) or a null body with the
- *  HTTP status, so the caller can tell a broken page (5xx — a server-error RESPONSE, not a throw) from an
- *  expected non-200 (a draft / unpublish race → 404 / redirect). */
-export async function renderRoute(route: string): Promise<{ body: Buffer | null; status: number }> {
-  // Run as the renderer principal so the nested $fetch('/api/route') passes the access guard (it is not a
-  // public endpoint). The ALS context propagates through localFetch → the page render → the nested fetch.
-  // useNitroApp is imported LAZILY (not via the Nitro auto-import) on purpose: a static import gives this
-  // module an edge to nitropack's app.mjs, which both defines useNitroApp AND loads the plugin registry
-  // that reaches this file (via zz.publish) — a build-time circular dependency. A dynamic import is a chunk
-  // boundary, so that cycle disappears from the build graph; it's the same nitroApp singleton either way
-  // (Rollup bundles the literal specifier; useNitroApp is only CALLED here at publish time, long after boot).
-  const { useNitroApp } = await import('nitropack/runtime')
-  const res = await runAsRenderer(() => useNitroApp().localFetch(route, { method: 'GET', headers: { 'x-kestrel-publish': '1' } }))
-  if (res.status !== 200) return { body: null, status: res.status }
-  return { body: Buffer.from(await res.arrayBuffer()), status: res.status }
-}
-
-/** The enumerated published routes plus the collections whose query failed. `failed` is non-empty ⇒ the
- *  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[]
-}
-
-/** Every published, publicly-readable page-like route (across collections) + the site root — the
- *  runtime analogue of the prerender/sitemap route enumeration. noindex pages ARE published (real
- *  reachable pages); only the sitemap omits them. */
-export function allPublishedRoutes(): PublishedRoutes {
-  const db = useDb()
-  const primary = primaryLocale()
-  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
-    // Project ONLY the columns the route rule + status gate need — never SELECT *, which would pull every
-    // row's block-content JSON (and every other field) into memory on each full publish just to read `path`.
-    // `locale` exists ONLY on a translatable collection (buildTable adds no locale column otherwise); a bare
-    // `cols.locale` would be undefined and make the select throw, dropping every one of this NON-translatable
-    // collection's live pages (then pruning them). Guard it exactly like findRouteConflict does.
-    const cols = getTableColumns(c.table) as Record<string, never>
-    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) {
-      // Report the gap instead of contributing zero routes: an unreadable collection is NOT an empty one,
-      // and a caller that can't tell them apart would treat every live page of it as stale.
-      failed.push(c.def.name)
-      console.error(`[kestrel] allPublishedRoutes: skipped collection ${c.def.name}:`, (error as Error)?.message ?? error)
-      continue
-    }
-    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) 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], savedAt, recordTag, failed }
-}
-
-/** Render + write the given routes (skips non-200). When `deps` is given, each render is wrapped in a
- *  read-capture and its data tags recorded, so a later write maps back to the routes it affects. */
-export async function publishRoutes(routes: string[], driver: StorageDriver, deps?: DepsStore): Promise<string[]> {
-  // One UNBUDGETED resolve scope for the whole run: a media/link/relation shared across pages resolves
-  // once per publish instead of once per embedding page (the runtime analogue of the generate build's
-  // memoDuringPrerender). Memo hits replay their read-tags, so each page's dep capture stays complete.
-  return withResolveScope(() => publishRoutesInScope(routes, driver, deps))
-}
-
-async function publishRoutesInScope(routes: string[], driver: StorageDriver, deps?: DepsStore): Promise<string[]> {
-  const written: string[] = []
-  const db = useDb()
-  const target = outputConfig().driver
-  for (const route of routes) {
-    try {
-      const { result, tags } = await withReadCapture(() => renderRoute(route))
-      const outcome = renderOutcome(result.status, !!result.body)
-      if (outcome === 'success') {
-        deps?.record(route, tags)
-        const key = htmlKeyForRoute(route)
-        await driver.put(key, result.body!, contentTypeFor(key), { cacheControl: cacheControlFor(key) })
-        written.push(route)
-        recordPublishStatus(db, route, { status: 'success', target })
-      } else if (outcome === 'error') {
-        // The page itself rendered to a server error (5xx) — a non-200 RESPONSE, not a thrown exception, so
-        // it never reaches the catch below. Record it so the editor ampel shows the failure; the
-        // previously-written file (if any) stays in place.
-        const message = `Render failed with HTTP ${result.status}`
-        recordPublishStatus(db, route, { status: 'error', error: message, target })
-        console.error(`[kestrel] publish failed for ${route}: ${message}`)
-      }
-      // outcome === 'skip': an expected non-200 (a draft / unpublish race) — leave the status untouched.
-    } catch (error) {
-      // Render or write (incl. S3 put) THREW for THIS route: record the outcome and carry on so one bad
-      // route doesn't abort the whole publish. The failure stays visible in the logs and the editor ampel.
-      const message = (error as Error)?.message ?? String(error)
-      recordPublishStatus(db, route, { status: 'error', error: message, target })
-      console.error(`[kestrel] publish failed for ${route}:`, message)
-    }
-  }
-  return written
-}
-
-/** Delete the given routes' static files (idempotent) — unpublish / delete / old-path prune. */
-export async function prunePages(routes: string[], driver: StorageDriver): Promise<void> {
-  // pruneEmptyDirs: a page is `<path>/index.html`, so removing it must also clear the now-empty `<path>/`.
-  const db = useDb()
-  for (const route of routes) {
-    await driver.delete(htmlKeyForRoute(route), { pruneEmptyDirs: true })
-    clearPublishStatus(db, route) // the file is gone → no live status (after the delete, so a failed delete keeps the row)
-  }
-}
-
-/** 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 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)
-  }
-}
-
-/** Mirror the built client bundle + static assets (`_nuxt/**`, favicon, fonts) into the output, but
- *  NOT the build's stale `*.html`/sitemap/robots — those are rendered fresh from the live DB. */
-async function syncStaticAssets(driver: StorageDriver, publicDir: string): Promise<void> {
-  const walk = async (dir: string, prefix: string): Promise<void> => {
-    let entries
-    try { entries = await readdir(dir, { withFileTypes: true }) }
-    catch (error) {
-      // The root directory failing is a misconfig (missing/unreadable output.publicDir), not an empty
-      // tree — silently returning here means zero assets get synced while the render below still
-      // uploads fresh HTML referencing hashed `_nuxt/*` chunks that were never uploaded. A nested
-      // directory disappearing mid-walk is comparatively benign and stays silent.
-      if (!prefix) {
-        console.error(`[kestrel] output.publicDir "${dir}" is unreadable — publishing HTML without syncing _nuxt/assets: ${(error as Error)?.message ?? error}`)
-      }
-      return
-    }
-    const names = entries.map((s) => s.name)
-    for (const e of entries) {
-      const rel = prefix ? `${prefix}/${e.name}` : e.name
-      if (e.isDirectory()) { await walk(resolve(dir, e.name), rel); continue }
-      // Strip a precompressed `.br`/`.gz` suffix before the skip test: `index.html.br` is still the
-      // build's stale HTML (only content-negotiable, not literally named `*.html`) and must be excluded
-      // 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') || 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.
-      const contentEncoding = precompressedEncoding(e.name, names)
-      await driver.put(rel, bytes, contentTypeFor(rel, !!contentEncoding), { cacheControl: cacheControlFor(rel), contentEncoding })
-    }
-  }
-  await walk(publicDir, '')
-}
-
-/** Full publish: sync `_nuxt`/assets first (so HTML never references not-yet-uploaded chunks), render
- *  every published route + sitemap/robots, and prune routes that left the published set (unpublish /
- *  delete / slug change) — tracked via the now-durable deps index, so a page unpublished/deleted while the
- *  server was down is pruned on the next boot too. Targeted (only ever deletes routes this publisher wrote),
- *  and skipped entirely when the published set could not be enumerated in full.
- *
- *  Deliberately NOT single-flighted: each caller brings its own driver and DepsStore, and folding a later
- *  caller into a run already in progress would hand it that run's older route snapshot — an edit made
- *  after the snapshot would never render and its deps would never be recorded. Serializing overlapping
- *  triggers is the publish queue's job. */
-export async function publishFull(driver: StorageDriver = outputDriver(), deps?: DepsStore): Promise<{ rendered: number; pruned: number }> {
-  const cfg = outputConfig()
-  // Keep the registry read (`allPublishedRoutes` → `allCollections()`) AFTER this first `await`: on a
-  // boot publish it lets the synchronous Nitro plugin loop — including collections/01.register, which
-  // 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, 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
-    // recoverable, a deleted site is not.
-    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).filter((route) => !keep.has(route))
-    if (stale.length) {
-      await prunePages(stale, driver)
-      for (const route of stale) deps.forget(route)
-      pruned = stale.length
-    }
-  }
-
-  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(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
-  // the complete set of variants actually used — reconcile it into the media_settings registry (scan entries
-  // replaced, manual/pinned kept). A partial (tag) publish must NOT do this: it would drop variants used only
-  // 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 — 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 }
-}
-
-/** Dispatch a coalesced invalidation from the queue: `full` → full publish; `tags` → re-render exactly
- *  the affected routes (deps-matched ∪ explicit `render`) + prune the `prune` routes + regen sitemap/robots
- *  (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 = 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).
-  const toPrune = routesToPrune(inv.prune, rendered)
-  if (toPrune.length) {
-    await prunePages(toPrune, driver)
-    for (const route of toPrune) deps?.forget(route)
-    pruned = toPrune
-  }
-  await publishMeta(driver)
-  return { rendered, pruned, counts: { rendered: rendered.length, pruned: pruned.length } }
-}

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

@@ -1,67 +0,0 @@
-import type { Invalidation } from './invalidation'
-import { coalesce } from './coalesce'
-
-export interface PublishQueueOptions {
-  /** Dispatch a coalesced invalidation (full or tags). Rejections are caught + re-queued. */
-  run: (inv: Invalidation) => Promise<void>
-  /** Quiet window before a pending batch fires (default 3000ms). */
-  debounceMs?: number
-  /** Cap on how long a steady stream of writes can defer the flush (default 60000ms). */
-  maxWaitMs?: number
-  onError?: (error: unknown) => void
-}
-
-export interface PublishQueue {
-  /** Record an invalidation; a coalesced run fires after the quiet window. noop is ignored. */
-  enqueue: (inv: Invalidation) => void
-}
-
-/**
- * Debounce + coalesce + single-flight queue for publish invalidations. A burst of content writes
- * collapses to ONE run after a quiet window (capped by maxWait); only one run is in flight at a time,
- * and anything enqueued mid-run defers to the next pass — so a publish always reflects the CURRENT DB
- * state and converges (idempotent). A failed run re-queues its batch (never silently drops writes).
- */
-export function createPublishQueue(opts: PublishQueueOptions): PublishQueue {
-  const debounceMs = opts.debounceMs ?? 3000
-  const maxWaitMs = opts.maxWaitMs ?? 60000
-  let pending: Invalidation[] = []
-  let timer: ReturnType<typeof setTimeout> | null = null
-  let firstAt = 0
-  let running = false
-
-  function arm() {
-    if (timer) clearTimeout(timer)
-    const now = Date.now()
-    if (!firstAt) firstAt = now
-    const wait = Math.max(0, Math.min(debounceMs, firstAt + maxWaitMs - now))
-    timer = setTimeout(flush, wait)
-  }
-
-  function flush() {
-    timer = null
-    firstAt = 0
-    if (running || pending.length === 0) return // a run is in flight; its finally() re-arms
-    const inv = coalesce(pending)
-    pending = []
-    if (inv.type === 'noop') return
-    running = true
-    void opts.run(inv)
-      .catch((error) => {
-        opts.onError?.(error)
-        pending.unshift(inv) // never drop a batch on failure — retry on the next pass
-      })
-      .finally(() => {
-        running = false
-        if (pending.length) arm()
-      })
-  }
-
-  function enqueue(inv: Invalidation) {
-    if (inv.type === 'noop') return
-    pending.push(inv)
-    if (!running) arm() // mid-run enqueues are collected; finally() re-arms once the run settles
-  }
-
-  return { enqueue }
-}

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

@@ -1,221 +0,0 @@
-/**
- * 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
-}