@michaelthielemann/kestrel 1.2.1

package/layers/public/modules/deploy-output/deploy-output.ts

@@ -0,0 +1,370 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { join, relative, sep, extname } from 'node:path'
+import { setTimeout as sleepFor } from 'node:timers/promises'
+import { resolveS3Settings } from '../../../core/server/utils/kestrel-config'
+import type { StorageDriver } from '../../../core/server/utils/storage'
+
+const MIME: Record<string, string> = {
+  // markup / scripts / data
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.xml': 'application/xml; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8',
+  '.csv': 'text/csv; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+  '.wasm': 'application/wasm',
+  '.pdf': 'application/pdf',
+  '.webmanifest': 'application/manifest+json',
+  // images
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.apng': 'image/apng',
+  '.bmp': 'image/bmp',
+  // fonts
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.eot': 'application/vnd.ms-fontobject',
+  // audio / video
+  '.mp3': 'audio/mpeg',
+  '.ogg': 'audio/ogg',
+  '.wav': 'audio/wav',
+  '.m4a': 'audio/mp4',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mov': 'video/quicktime',
+}
+
+/** MIME type for a static output file, inferred from its extension; octet-stream when unknown. A
+ *  pre-compressed sibling (`app.js.br`) carries the encoding in `Content-Encoding`, so its type is the
+ *  underlying asset's — strip a trailing `.br`/`.gz` before the lookup. Only strip it when a
+ *  `Content-Encoding` will actually be sent (`hasEncoding`, default true for existing callers): a
+ *  standalone archive with no such header must keep its own extension, or it ships mislabelled as the
+ *  underlying (uncompressed) type — e.g. a browser trying to parse raw gzip bytes as JSON. */
+export function contentTypeFor(filename: string, hasEncoding = true): string {
+  const base = hasEncoding ? filename.replace(/\.(?:br|gz)$/i, '') : filename
+  return MIME[extname(base).toLowerCase()] ?? 'application/octet-stream'
+}
+
+/** The `Content-Encoding` for a precompressed sidecar (`app.js.br` beside `app.js`), or undefined for a
+ *  standalone archive with no uncompressed base — tagging that would make a browser transparently decode
+ *  genuine content and corrupt it. `siblingNames` are the file names in the same directory. */
+export function precompressedEncoding(filename: string, siblingNames: string[]): 'br' | 'gzip' | undefined {
+  const m = /\.(br|gz)$/.exec(filename)
+  if (!m || !siblingNames.includes(filename.slice(0, m.index))) return undefined
+  return m[1] === 'br' ? 'br' : 'gzip'
+}
+
+const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable'
+const REVALIDATE_CACHE = 'public, max-age=0, must-revalidate'
+
+/**
+ * `Cache-Control` for a static-output key, or `undefined` for no explicit policy. Content-hashed
+ * `_nuxt/` assets get a year + `immutable` (the hash is the cache key — new content ⇒ new URL). HTML,
+ * the sitemap and `robots.txt` live at *stable* URLs whose content changes on any deploy, so they get
+ * `max-age=0, must-revalidate` (cacheable but always revalidated). Everything else (favicons, fonts,
+ * un-hashed media) is left to the host default.
+ */
+export function cacheControlFor(key: string): string | undefined {
+  // Nuxt's app manifest lives at a STABLE _nuxt URL but its content (the buildId) changes every build, so it
+  // must revalidate — else the immutable rule below pins it and clients never detect a new deploy.
+  if (key === '_nuxt/builds/latest.json') return REVALIDATE_CACHE
+  if (key === '_nuxt' || key.startsWith('_nuxt/')) return IMMUTABLE_CACHE
+  const base = key.split('/').pop() ?? key
+  if (base.endsWith('.html') || base === 'sitemap.xml' || base === 'robots.txt' || base === 'llms.txt') return REVALIDATE_CACHE
+  return undefined
+}
+
+/** A boolean env flag is on for any of the common truthy spellings (case-insensitive, trimmed). */
+export function isEnvTrue(value: string | undefined): boolean {
+  const t = value?.trim().toLowerCase()
+  return t === 'true' || t === '1' || t === 'yes' || t === 'on'
+}
+
+/**
+ * Decide what the deploy hook should do, kept pure so the trigger guard is unit-testable. Returns
+ * `'skip'` when this isn't a static `nuxt generate` — a plain `nuxt build` (or dev) must never deploy,
+ * even with `driver: s3` configured — and when `output.auto` hands publishing to the running server
+ * (see `autoPublish`). For a real (non-dry-run) static generate it throws when the
+ * bucket or `KESTREL_S3_*` credentials are missing, so a misconfigured deploy fails the generate
+ * loudly instead of warning and exiting 0 with a stale live bucket. A dry-run needs neither.
+ */
+/** Strip leading/trailing slashes so prefixes compare on bare path segments. */
+const normPrefix = (p: string): string => p.replace(/^\/+|\/+$/g, '')
+
+/**
+ * Do two S3 key prefixes share keyspace on a path-segment boundary — i.e. is one equal to, or nested
+ * under, the other? Catches both nesting directions: a prune of `a` reaches everything under `a/b`, and
+ * a prune of `a/b` reaches the `a/b/…` slice of media stored under `a`. A pure-string collision like
+ * `site` vs `siteother` is *not* an overlap. Empty prefixes never overlap (handled by their own guards).
+ */
+function prefixesOverlap(a: string, b: string): boolean {
+  const x = normPrefix(a)
+  const y = normPrefix(b)
+  if (!x || !y) return false
+  return x === y || x.startsWith(`${y}/`) || y.startsWith(`${x}/`)
+}
+
+export function planS3Deploy(opts: {
+  isStaticGenerate: boolean
+  dryRun: boolean
+  bucket: string
+  accessKeyId: string
+  secretAccessKey: string
+  prefix?: string
+  /**
+   * `output.auto` — the running server publishes to this bucket/prefix itself. Build-time route seeding is
+   * then disabled (a prerendered file would shadow the live route), so `.output/public` holds only what
+   * Nitro's crawler reached: shipping it would reconcile the server's live pages, sitemap and robots away.
+   */
+  autoPublish?: boolean
+  /** Bucket the S3 media driver writes live uploads to (empty when media isn't on S3 — then irrelevant). */
+  mediaBucket?: string
+  /** Key prefix of those live media objects, to keep the reconcile from deleting them. */
+  mediaPrefix?: string
+}): 'skip' | 'deploy' {
+  if (!opts.isStaticGenerate) return 'skip'
+  if (opts.autoPublish) return 'skip'
+  if (!opts.dryRun) {
+    const missing: string[] = []
+    if (!opts.bucket) missing.push('bucket (KESTREL_OUTPUT_S3_BUCKET)')
+    if (!opts.accessKeyId) missing.push('KESTREL_OUTPUT_S3_ACCESS_KEY_ID / KESTREL_S3_ACCESS_KEY_ID')
+    if (!opts.secretAccessKey) missing.push('KESTREL_OUTPUT_S3_SECRET_ACCESS_KEY / KESTREL_S3_SECRET_ACCESS_KEY')
+    if (missing.length) {
+      throw new Error(
+        `[kestrel] output.driver=s3 but ${missing.join(', ')} ${missing.length > 1 ? 'are' : 'is'} missing`
+        + ' — refusing to finish `nuxt generate` with a broken S3 deploy.',
+      )
+    }
+    // The deploy always reconciles (deletes every remote object under the prefix not in this generate —
+    // output ≡ DB). With an empty prefix that's the whole bucket root, which may hold the media bucket's
+    // objects too. Refuse rather than risk wiping it: an S3 deploy must target a dedicated prefix.
+    if (!opts.prefix) {
+      throw new Error(
+        '[kestrel] output.s3.prefix is empty — refusing to deploy (the always-on reconcile would delete the'
+        + ' whole bucket root, and a shared/media bucket could be wiped). Set KESTREL_OUTPUT_S3_PREFIX to a'
+        + ' prefix dedicated to the generated site.',
+      )
+    }
+    // Same bucket as the S3 media driver AND overlapping prefixes → the reconcile would delete live uploads.
+    if (opts.mediaBucket && opts.mediaBucket === opts.bucket
+      && opts.mediaPrefix && prefixesOverlap(opts.prefix, opts.mediaPrefix)) {
+      throw new Error(
+        `[kestrel] the output reconcile would delete live media: output prefix "${opts.prefix}" overlaps the`
+        + ` S3 media prefix "${opts.mediaPrefix}" in the same bucket "${opts.bucket}". Give the generated`
+        + ' site its own bucket or a non-overlapping KESTREL_OUTPUT_S3_PREFIX.',
+      )
+    }
+  }
+  return 'deploy'
+}
+
+export interface OutputTarget {
+  driver: 'local' | 's3'
+  /** Non-secret S3 settings; credentials are resolved separately by `resolveOutputCreds`. */
+  s3: { bucket: string; region: string; endpoint: string; prefix: string }
+}
+
+type OutputConfig = { driver?: string; s3?: { bucket?: string; region?: string; endpoint?: string; prefix?: string } }
+const clean = (v: unknown): string | undefined => (typeof v === 'string' && v.trim() ? v.trim() : undefined)
+
+/**
+ * Resolve where `nuxt generate`'s static output is shipped: a local directory (default) or an S3
+ * bucket. Precedence per setting: `KESTREL_OUTPUT_*` env → config → default (the documented Kestrel
+ * order, same as the runtime publisher). Pure, so the precedence is unit-testable; secrets are resolved
+ * by `resolveOutputCreds`, never here.
+ */
+export function resolveOutputTarget(out: OutputConfig = {}, env: Record<string, string | undefined> = {}): OutputTarget {
+  const driver = (clean(env.KESTREL_OUTPUT_DRIVER) ?? clean(out.driver))?.toLowerCase() === 's3' ? 's3' : 'local'
+  // Same non-secret resolver media uses, under the KESTREL_OUTPUT_S3_* prefix (own bucket, own creds).
+  return { driver, s3: resolveS3Settings(out.s3, env, 'KESTREL_OUTPUT_S3') }
+}
+
+/**
+ * S3 credentials for the output deploy: the output-specific `KESTREL_OUTPUT_S3_*`, falling back to the
+ * shared media `KESTREL_S3_*` so a single S3 account "just works" — identical to the runtime publisher's
+ * resolution. Required keys default to '' (not undefined) so `planS3Deploy` detects a missing credential.
+ */
+export function resolveOutputCreds(env: Record<string, string | undefined> = {}): { accessKeyId: string; secretAccessKey: string; sessionToken?: string } {
+  return {
+    accessKeyId: clean(env.KESTREL_OUTPUT_S3_ACCESS_KEY_ID) ?? clean(env.KESTREL_S3_ACCESS_KEY_ID) ?? '',
+    secretAccessKey: clean(env.KESTREL_OUTPUT_S3_SECRET_ACCESS_KEY) ?? clean(env.KESTREL_S3_SECRET_ACCESS_KEY) ?? '',
+    sessionToken: clean(env.KESTREL_OUTPUT_S3_SESSION_TOKEN) ?? clean(env.KESTREL_S3_SESSION_TOKEN),
+  }
+}
+
+/** Every file under `dir` as `{ abs, key }`, the key being its POSIX-relative path (stable order). */
+function listFiles(dir: string): Array<{ abs: string; key: string }> {
+  return readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((e) => e.isFile())
+    .map((e) => {
+      const abs = join(e.parentPath, e.name)
+      return { abs, key: relative(dir, abs).split(sep).join('/') }
+    })
+}
+
+/**
+ * A `*.gz`/`*.br` file is a pre-compressed sidecar (from `nitro.compressPublicAssets`) when its
+ * uncompressed base is also in the output. On a plain static S3 host these are dead weight — the host
+ * does no `Accept-Encoding` negotiation, so nobody fetches `index.html.gz`, and storing it *as*
+ * `index.html` with `Content-Encoding` would collide with the real file — so the deploy skips them.
+ * A standalone `*.gz` archive (no base file) is genuine content and is kept.
+ */
+export function isCompressedSidecar(key: string, all: Set<string>): boolean {
+  const m = /\.(?:gz|br)$/.exec(key)
+  return m ? all.has(key.slice(0, m.index)) : false
+}
+
+export interface DeployResult { pruned: number; keys: string[] }
+
+/**
+ * What build-time route discovery enumerated for this generate, plus WHY that enumeration is known to be
+ * short of the site's pages (`incomplete` unset ⇒ it is complete). The runtime publisher's
+ * `{ routes, failed }` is the same contract: an enumeration that came up short must never be the
+ * authority for what gets deleted.
+ */
+export interface RouteDiscovery { routes: string[]; incomplete?: string }
+
+interface DiscoveryHost { _kestrelRouteDiscovery?: RouteDiscovery }
+
+/** The prerender and deploy modules are loaded separately and share no module scope — but they are handed
+ *  the same Nuxt instance, so that object is what carries the signal from the one to the other. */
+export function recordRouteDiscovery(nuxt: object, discovery: RouteDiscovery): void {
+  (nuxt as DiscoveryHost)._kestrelRouteDiscovery = discovery
+}
+
+/** `undefined` ⇒ discovery never reported anything, which is not itself evidence of a degraded build. */
+export function readRouteDiscovery(nuxt: object): RouteDiscovery | undefined {
+  return (nuxt as DiscoveryHost)._kestrelRouteDiscovery
+}
+
+/** The deploy needs `put` always, and `list`+`delete` for the reconcile; both are optional on the driver. */
+type DeployDriver = Pick<StorageDriver, 'put'> & Partial<Pick<StorageDriver, 'list' | 'delete'>>
+
+export interface DeployOptions {
+  dryRun?: boolean
+  log?: (msg: string) => void
+  /** Max operations in flight at once (default 8). Bounded so a large tree never opens thousands of sockets. */
+  concurrency?: number
+  /** Total attempts per operation before giving up (default 3); retries ride out transient S3 errors. */
+  retries?: number
+  /** Sleep between retries (exponential backoff); injectable so tests run without real delay. */
+  sleep?: (ms: number) => Promise<void>
+  /**
+   * Why a build step REPORTED that this output tree is short of pages (routes that failed to prerender,
+   * route discovery that could not read the DB). Set ⇒ upload but never reconcile: pages missing from the
+   * input are indistinguishable from pages removed from the CMS, so the prune would delete live ones.
+   * Only a step's own failure report belongs here: the SHAPE of the output cannot tell a degraded build
+   * from a small site, so inferring it would strand the pages an editor deleted.
+   */
+  incomplete?: string
+}
+
+/** Run `task` over `items` with at most `concurrency` in flight at once. */
+async function runPool<T>(items: T[], concurrency: number, task: (item: T) => Promise<void>): Promise<void> {
+  let next = 0
+  const worker = async (): Promise<void> => {
+    while (next < items.length) {
+      const i = next++
+      await task(items[i])
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker))
+}
+
+/** HTTP statuses the S3 driver surfaces in its error message (e.g. `S3 put failed (403) for x`). */
+function statusFromError(err: unknown): number | undefined {
+  const m = /\((\d{3})\)/.exec((err as Error)?.message ?? '')
+  return m ? Number(m[1]) : undefined
+}
+
+/**
+ * A permanent client error — bad/forbidden credentials, missing bucket, denied access (400/401/403/404).
+ * These never become successful on a later attempt, so retrying only delays the inevitable loud failure.
+ */
+export function isPermanentError(err: unknown): boolean {
+  const s = statusFromError(err)
+  return s === 400 || s === 401 || s === 403 || s === 404
+}
+
+/** Retry `fn` with exponential backoff up to `retries` total attempts, surfacing the last error. */
+async function withRetry(fn: () => Promise<void>, label: string, retries: number, sleep: (ms: number) => Promise<void>, log?: (msg: string) => void): Promise<void> {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      await fn()
+      return
+    } catch (err) {
+      // A permanent 4xx can't be ridden out — re-throw at once so the deploy fails loudly, not slowly.
+      if (isPermanentError(err) || attempt >= retries) throw err
+      log?.(`retry ${attempt}/${retries - 1} for ${label}: ${(err as Error).message}`)
+      await sleep(100 * 2 ** (attempt - 1))
+    }
+  }
+}
+
+/**
+ * Upload every file under `dir` to `driver`, keyed by its POSIX-relative path, with a content type
+ * inferred from the extension — the S3 equivalent of `aws s3 sync` (overwrites). Then reconciles: deletes
+ * remote objects under the prefix that this generate didn't produce (`--delete`), so pages removed from
+ * the CMS stop being served (output ≡ DB, no toggle). The reconcile is skipped when the driver can't
+ * list+delete and when the caller flagged the tree `incomplete` — a build step reported it is short of
+ * pages, so their absence says nothing about the CMS. Uploads still run then: shipping the pages that did
+ * render is safe, deleting on their absence is not.
+ * Uploads and deletes run with bounded concurrency and each is retried with
+ * backoff, so a transient 5xx/throttle/dropped-connection no longer aborts the deploy mid-way and
+ * half-updates the bucket; only an operation that fails every attempt rejects (true rollback isn't
+ * possible on S3). With `dryRun`, walks/lists and reports without writing.
+ */
+export async function deployStaticOutput(
+  dir: string,
+  driver: DeployDriver,
+  opts: DeployOptions = {},
+): Promise<DeployResult> {
+  const concurrency = Math.max(1, opts.concurrency ?? 8)
+  const retries = Math.max(1, opts.retries ?? 3)
+  const sleep = opts.sleep ?? ((ms: number) => sleepFor(ms))
+  const all = listFiles(dir)
+  const allKeys = new Set(all.map((f) => f.key))
+  const files = all.filter((f) => !isCompressedSidecar(f.key, allKeys))
+  const skipped = all.length - files.length
+  if (skipped) opts.log?.(`skipping ${skipped} pre-compressed sidecar(s) (.gz/.br)`)
+  const keys = files.map((f) => f.key)
+
+  if (!opts.dryRun) {
+    // `files` already excludes pre-compressed sidecars (above), so anything ending `.gz`/`.br` here is a
+    // standalone archive shipped with no `Content-Encoding` — keep its own extension in the type lookup.
+    await runPool(files, concurrency, (f) =>
+      withRetry(() => driver.put(f.key, readFileSync(f.abs), contentTypeFor(f.key, false), { cacheControl: cacheControlFor(f.key) }), f.key, retries, sleep, opts.log))
+  }
+  opts.log?.(`${opts.dryRun ? 'Would deploy' : 'Deployed'} ${keys.length} file(s)`)
+
+  // Reconcile (output ≡ DB) — skipped when the driver lacks list/delete (e.g. a put-only target) and when
+  // a build step reported that this generate is short of pages.
+  let pruned = 0
+  if (!driver.list || !driver.delete) {
+    opts.log?.('driver cannot list/delete — skipping reconcile')
+  } else if (opts.incomplete) {
+    opts.log?.(`skipping reconcile — ${opts.incomplete}; the missing pages would read as stale and be deleted`)
+  } else {
+    const keep = new Set(keys)
+    const stale = (await driver.list()).filter((k) => !keep.has(k))
+    if (!opts.dryRun) {
+      const del = driver.delete
+      await runPool(stale, concurrency, (k) => withRetry(() => del(k), `delete ${k}`, retries, sleep, opts.log))
+      pruned = stale.length
+    }
+    opts.log?.(`${opts.dryRun ? 'Would prune' : 'Pruned'} ${stale.length} stale object(s)`)
+  }
+  return { pruned, keys }
+}

package/layers/public/modules/deploy-output/index.ts

@@ -0,0 +1,82 @@
+import { defineNuxtModule } from '@nuxt/kit'
+import { createS3Driver } from '../../../core/server/utils/storage.s3'
+import { resolveOutputCreds, deployStaticOutput, isEnvTrue, planS3Deploy, readRouteDiscovery } from './deploy-output'
+import { resolveKestrel } from '../../../core/server/utils/kestrel-config'
+import type { KestrelConfig } from '../../../core/server/utils/kestrel-config'
+
+
+/**
+ * Ships `nuxt generate`'s static output (`.output/public`) to an S3 bucket when `kestrel.output.driver`
+ * is `s3` — the deploy half of FEATURES "Output target: local directory or S3 bucket". Runs on Nitro's
+ * `compiled` hook (which fires once the full output is on disk — prerendered HTML, the `_nuxt` client
+ * bundle + static `public/` assets copied by `copyPublicAssets`, and any compressed variants — i.e. after
+ * prerendering, which does NOT abort on a route error unless `prerender.failOnError` is set: hence the
+ * `incomplete` signal below), and only when `nitro.options.static` is set, i.e. a real `nuxt generate`.
+ * A plain `nuxt build`/`dev` never deploys.
+ * Nor does it with `output.auto` on — then the running server owns publishing (see the `auto` note below).
+ * With `driver: local` (the default) it does nothing — the local `.output/public` tree is the artifact.
+ * S3 credentials are env-only (`KESTREL_OUTPUT_S3_*`, falling back to the shared media `KESTREL_S3_*`).
+ */
+export default defineNuxtModule({
+  meta: { name: 'kestrel-deploy-output' },
+  setup(_options, nuxt) {
+    // Build-time: resolve from the consumer's config through the one shared resolver, so driver, prefixes
+    // and `auto` here are byte-identical to what the runtime publisher and the media driver see — an
+    // ad-hoc env probe that disagrees (env-first vs config-first) would silently disarm the guards below.
+    const c = resolveKestrel(nuxt.options.kestrel as KestrelConfig, process.env, nuxt.options.rootDir)
+    if (c.output.driver !== 's3') return
+    const target = c.output.s3
+
+    // Where the S3 media driver keeps live uploads — used to stop the reconcile from wiping them when the
+    // generated site shares its bucket. Undefined (media on the local driver) makes the guard a no-op.
+    const mediaS3 = c.media.driver === 's3' ? c.media.s3 : undefined
+
+    nuxt.hook('nitro:init', (nitro) => {
+      // Nitro prerenders BEFORE the build that fires `compiled`, and `prerender.failOnError` is off by
+      // default — a route that 5xx'd leaves no file and does not abort the generate. Remember that here:
+      // its live page is still there and must not be mistaken for content removed from the CMS.
+      let failedRoutes = 0
+      nitro.hooks.hook('prerender:done', ({ failedRoutes: failed }) => { failedRoutes = failed?.length ?? 0 })
+
+      nitro.hooks.hook('compiled', async () => {
+        const env = process.env
+        const creds = resolveOutputCreds(env)
+        const dryRun = isEnvTrue(env.KESTREL_OUTPUT_DRY_RUN)
+        // Skip on a plain build (no static generate) or when the runtime publisher owns the bucket;
+        // throw on a misconfigured real deploy or unsafe reconcile.
+        if (planS3Deploy({
+          isStaticGenerate: nitro.options.static === true,
+          autoPublish: c.output.auto,
+          dryRun,
+          bucket: target.bucket,
+          accessKeyId: creds.accessKeyId,
+          secretAccessKey: creds.secretAccessKey,
+          prefix: target.prefix,
+          mediaBucket: mediaS3?.bucket,
+          mediaPrefix: mediaS3?.prefix,
+        }) === 'skip') {
+          // A plain build skips silently; someone who actually ran `nuxt generate` deserves to hear why
+          // nothing shipped.
+          if (nitro.options.static === true && c.output.auto) {
+            console.log('[kestrel] output.auto is on — the running server publishes to this bucket; not shipping'
+              + ' .output/public. Set output.auto=false (or KESTREL_OUTPUT_AUTO=false) for the build-time model.')
+          }
+          return
+        }
+
+        const driver = createS3Driver({ ...target, publicBaseUrl: '', ...creds })
+        console.log(`[kestrel] ${dryRun ? 'dry-run: ' : ''}shipping static output → s3://${target.bucket || '<bucket>'}/${target.prefix}`)
+        // Both signals are REPORTED failures of a step that knows: route discovery could not enumerate the
+        // pages, or Nitro could not render some of them. Neither is inferred from how the tree looks —
+        // no shape of output distinguishes a degraded build from a small site.
+        const discovery = readRouteDiscovery(nuxt)
+        const res = await deployStaticOutput(nitro.options.output.publicDir, driver, {
+          dryRun,
+          incomplete: discovery?.incomplete ?? (failedRoutes ? `${failedRoutes} route(s) failed to prerender` : undefined),
+          log: (m) => console.log(`[kestrel] ${m}`),
+        })
+        console.log(`[kestrel] static output ${dryRun ? 'walk' : 'deploy'} complete — ${res.keys.length} file(s), ${res.pruned} pruned.`)
+      })
+    })
+  },
+})

package/layers/public/modules/prerender-routes/discover.ts

@@ -0,0 +1,37 @@
+import type Database from 'better-sqlite3'
+import { pagesToRoutes, type PageRouteRow } from './routes'
+
+/** Tables the schema engine marked routable, by their partial `path` index (see `collectPageRoutes`).
+ *  Empty means this file holds no page-like collection at all — a structural fact about the schema, not a
+ *  statement about how many pages exist: a CMS with one page still has its table and that index. */
+export function pageLikeTables(db: Database.Database): string[] {
+  return (db
+    .prepare("SELECT DISTINCT tbl_name AS name FROM sqlite_master WHERE type = 'index' AND sql LIKE '%path is not null%'")
+    .all() as { name: string }[]).map((t) => t.name)
+}
+
+/**
+ * Page routes to seed for `nuxt generate`, discovered straight from the build-time DB (no registry is
+ * available at build). Every page-like collection carries a **partial unique index on `path`**
+ * (`… WHERE path is not null`) — the schema engine's marker for a routable table — so we enumerate those.
+ * That is reliable where "has a `path` column" is NOT: the media `folders` registry has a `path` column +
+ * a plain unique index, but no such partial clause, so it is correctly excluded. Per pageLike table:
+ * published rows (only where a `status` column exists) with a non-null path, keyed by their own `locale`
+ * (or the primary locale for a non-translatable collection). Returns the deduped, sorted route list
+ * (always including the root).
+ */
+export function collectPageRoutes(db: Database.Database, primaryLocale: string, prefixPrimary = false): string[] {
+  const rows: PageRouteRow[] = []
+  for (const name of pageLikeTables(db)) {
+    const q = `"${name.replace(/"/g, '""')}"`
+    const cols = (db.prepare(`PRAGMA table_info(${q})`).all() as { name: string }[]).map((c) => c.name)
+    const statusClause = cols.includes('status') ? "status = 'published' AND " : ''
+    if (cols.includes('locale')) {
+      rows.push(...(db.prepare(`SELECT path, locale FROM ${q} WHERE ${statusClause}path IS NOT NULL`).all() as PageRouteRow[]))
+    } else {
+      const bare = db.prepare(`SELECT path FROM ${q} WHERE ${statusClause}path IS NOT NULL`).all() as { path: string | null }[]
+      for (const r of bare) rows.push({ path: r.path, locale: primaryLocale })
+    }
+  }
+  return pagesToRoutes(rows, primaryLocale, prefixPrimary)
+}

package/layers/public/modules/prerender-routes/index.ts

@@ -0,0 +1,85 @@
+import { cpus } from 'node:os'
+import { existsSync } from 'node:fs'
+import { defineNuxtModule } from '@nuxt/kit'
+import Database from 'better-sqlite3'
+import { collectPageRoutes, pageLikeTables } from './discover'
+import { localePath } from '../../../core/app/utils/locale-path'
+import { recordRouteDiscovery, type RouteDiscovery } from '../deploy-output/deploy-output'
+import { resolveKestrel, type KestrelConfig } from '../../../core/server/utils/kestrel-config'
+
+// Read published paths from EVERY page-like collection straight from the DB at build time so
+// `nuxt generate` prerenders one HTML file per page (see `collectPageRoutes` for how pageLike tables
+// are identified). The server's migrate-on-boot hasn't run yet at this point, so a DB that isn't there
+// yet degrades to the root alone — reported as `incomplete`, because a deploy that reconciles must be
+// able to tell that degrade apart from a CMS that genuinely holds one page.
+// `reconciles` (an S3 deploy follows this build) makes an unreadable-but-present DB fail the build
+// instead: there the degraded tree would also be uploaded over a real live site. Without that step there
+// is nothing destructive downstream, so a degrade stays a warning.
+export function discoverRoutes(path: string, primary: string, prefixPrimary: boolean, reconciles = false): RouteDiscovery {
+  const root = localePath('/', primary, primary, prefixPrimary) // `/` or `/<primary>` when the primary is prefixed
+  if (path === ':memory:') return { routes: [root], incomplete: 'the build ran against an in-memory database — only the site root was prerendered' }
+  if (!existsSync(path)) {
+    console.warn(`[kestrel] prerender: no database at ${path} — prerendering the site root only`)
+    return { routes: [root], incomplete: `no database at ${path} — only the site root was prerendered` }
+  }
+  let db: Database.Database | undefined
+  try {
+    db = new Database(path, { readonly: true, fileMustExist: true })
+    // Opening the file is not enumerating it: an unmigrated, zero-byte or simply wrong `KESTREL_DB` file
+    // opens as a valid EMPTY database, and the root-only route list it yields is byte-identical to a
+    // complete enumeration. Report the missing schema so a reconcile downstream can tell the two apart.
+    if (!pageLikeTables(db).length) {
+      const why = `the database at ${path} holds no page-like table — only the site root was prerendered`
+      console.warn(`[kestrel] prerender: ${why}`)
+      return { routes: [root], incomplete: why }
+    }
+    return { routes: collectPageRoutes(db, primary, prefixPrimary) }
+  } catch (error) {
+    const why = `cannot read the database at ${path}: ${(error as Error)?.message ?? error}`
+    if (reconciles) throw new Error(`[kestrel] prerender: ${why} — refusing to ship a site with no pages to an S3 target`)
+    console.warn(`[kestrel] prerender: ${why} — prerendering the site root only`)
+    return { routes: [root], incomplete: why }
+  } finally {
+    db?.close()
+  }
+}
+
+export default defineNuxtModule({
+  meta: { name: 'kestrel-prerender-routes' },
+  setup(_options, nuxt) {
+    // Build-time: resolve directly from the consumer's config (runtimeConfig/useRuntimeConfig aren't
+    // available here), rather than the request-time locale.ts globals.
+    const c = resolveKestrel(nuxt.options.kestrel as KestrelConfig, process.env, nuxt.options.rootDir)
+    // The editor-preview fallback page must NEVER be prerendered: the classic `nuxt generate` (static
+    // preset) auto-seeds every static page path, and this page 404s without an admin session — a
+    // guaranteed prerender error on every SSG build. Registered unconditionally (before the output.auto
+    // early-return) so both publishing models exclude it.
+    nuxt.hook('nitro:config', (nitro) => {
+      nitro.prerender ||= {}
+      nitro.prerender.ignore = [...(nitro.prerender.ignore ?? []), '/__kestrel/preview']
+    })
+    // The runtime publisher (output.auto) and build-time prerendering are mutually exclusive: a prerendered
+    // `.output/public/<route>/index.html` SHADOWS the live SSR route, so the publisher's localFetch would
+    // read STALE build-time HTML instead of rendering fresh. With auto on, the publisher (boot + on-write)
+    // owns publishing — so skip prerender seeding entirely. (auto off = the classic `nuxt generate` SSG model.)
+    if (c.output.auto) return
+    nuxt.hook('nitro:config', (nitro) => {
+      // Only an S3 target reconciles (deletes what this build didn't produce); a local build leaves the
+      // tree on disk, so an incomplete enumeration destroys nothing there. `nitro.static` is the same flag
+      // the deploy itself gates on: this hook also runs for `nuxt dev` and a plain `nuxt build`, and
+      // neither ships anything, so there a degrade must stay a warning instead of failing the command.
+      const reconciles = c.output.driver === 's3' && nitro.static === true
+      const discovery = discoverRoutes(c.dbPath, c.primaryLocale, c.prefixPrimary, reconciles)
+      // Hand the deploy module the completeness of THIS enumeration — the only step that knows it.
+      recordRouteDiscovery(nuxt, discovery)
+      nitro.prerender ||= {}
+      nitro.prerender.routes = [...new Set([...(nitro.prerender.routes ?? []), ...discovery.routes, '/sitemap.xml', '/robots.txt', '/llms.txt'])]
+      // Render pages in parallel — the dominant lever on `nuxt generate` wall-clock as page count grows.
+      // Safe: page reads are synchronous better-sqlite3 (WAL + busy_timeout, can't interleave mid-statement);
+      // the one WRITE on this path — the variant-registry capture — is an IMMEDIATE transaction, so
+      // concurrent prerender writers (and a co-running server publisher) serialize instead of losing updates.
+      // Capped to avoid memory over-subscription; overridable.
+      nitro.prerender.concurrency ??= Math.min(Math.max(cpus().length, 2), 8)
+    })
+  },
+})

package/layers/public/modules/prerender-routes/routes.ts

@@ -0,0 +1,16 @@
+import { localePath } from '../../../core/app/utils/locale-path'
+
+export interface PageRouteRow {
+  path: string | null
+  locale: string
+}
+
+export function pagesToRoutes(rows: PageRouteRow[], primaryLocale: string, prefixPrimary = false): string[] {
+  // The site root is the primary-locale home — `/` normally, `/<primary>` when the primary is prefixed.
+  const routes = new Set<string>([localePath('/', primaryLocale, primaryLocale, prefixPrimary)])
+  for (const { path, locale } of rows) {
+    if (!path) continue
+    routes.add(localePath(path, locale, primaryLocale, prefixPrimary))
+  }
+  return [...routes].sort()
+}

package/layers/public/modules/prune-media/index.ts

@@ -0,0 +1,48 @@
+import { defineNuxtModule } from '@nuxt/kit'
+import Database from 'better-sqlite3'
+import { resolveKestrel, type KestrelConfig } from '../../../core/server/utils/kestrel-config'
+import { isEnvTrue } from '../deploy-output/deploy-output'
+import { pruneUnreferencedMedia, mediaOwnedKeys } from './prune-media'
+
+// The set of storage keys the media library owns (originals + derivatives), read straight from the DB at
+// build time. Returns null when the registry can't be read (no DB, no media table) — the caller then SKIPS
+// the prune entirely rather than risk deleting extension/consumer blobs (e.g. gallery ciphertext).
+function readOwnedKeys(dbPath: string): Set<string> | null {
+  if (dbPath === ':memory:') return null
+  try {
+    const db = new Database(dbPath, { readonly: true, fileMustExist: true })
+    try {
+      const rows = db.prepare('SELECT storage_key AS storageKey, derivatives FROM media').all() as { storageKey: string; derivatives: string | null }[]
+      return mediaOwnedKeys(rows.map((r) => ({ storageKey: r.storageKey, derivatives: r.derivatives ? JSON.parse(r.derivatives) : null })))
+    } finally {
+      db.close()
+    }
+  } catch {
+    return null
+  }
+}
+
+// `nuxt generate` bakes the WHOLE upload dir into .output/public/<baseUrl>; without this, images of
+// deleted/unpublished pages ship to prod. At `compiled` (full output on disk, post prerender-abort) delete
+// every baked media file no generated page references — prunes the BAKE only, so a wrong prune costs a
+// re-generate, not data. Local-driver only (only it registers the /uploads publicAssets that gets baked).
+// If deploy-output is ever added to modules[], it must come AFTER this so the prune runs before the ship.
+export default defineNuxtModule({
+  meta: { name: 'kestrel-prune-media' },
+  setup(_options, nuxt) {
+    const c = resolveKestrel(nuxt.options.kestrel as KestrelConfig, process.env, nuxt.options.rootDir)
+    if (c.media.driver !== 'local') return
+    const dryRun = isEnvTrue(process.env.KESTREL_OUTPUT_DRY_RUN)
+    nuxt.hook('nitro:init', (nitro) => {
+      nitro.hooks.hook('compiled', () => {
+        if (nitro.options.static !== true) return
+        const ownedKeys = readOwnedKeys(c.dbPath)
+        if (!ownedKeys) {
+          console.log('[kestrel] media prune skipped: media registry unavailable (would risk deleting extension/consumer blobs)')
+          return
+        }
+        pruneUnreferencedMedia(nitro.options.output.publicDir, c.media.baseUrl, { dryRun, ownedKeys, log: (m) => console.log(`[kestrel] ${m}`) })
+      })
+    })
+  },
+})