@michaelthielemann/kestrel 1.2.1

package/layers/core/server/utils/serialize-collection.ts

@@ -0,0 +1,149 @@
+import { fieldIs, isSingleRefColumn, type CollectionDef, type Condition, type FieldDef, type FieldType, type Localized } from './defineCollection'
+import { resolveFieldLayout, type LayoutNode } from './field-layout'
+
+export interface SerializedField {
+  type: FieldType
+  required: boolean
+  translatable: boolean
+  unique: boolean
+  /** Optional (localized) editor label; the admin falls back to the humanized field key when absent. */
+  label?: Localized
+  /** True when stored as a single `<name>Id` FK column (single relation/media). The editor reads this
+   *  to derive the wire/column key instead of re-deriving the rule. Omitted (falsy) for normal fields. */
+  single?: boolean
+  options?: Record<string, unknown>
+  relation?: { collection: string; many: boolean; labelField?: string }
+  default?: unknown
+  /** Visibility logic (see `Condition`). Crosses to the admin so the editor can hide the field; it is
+   *  JSON-safe by construction, so it passes the wire (and the `asFieldDef` cast) unchanged. */
+  condition?: Condition
+}
+
+export interface SerializedCollection {
+  name: string
+  mode: 'multi' | 'single'
+  translatable: boolean
+  pageLike: boolean
+  seo: boolean
+  status: boolean
+  blocks: { enabled: boolean; allowed?: string[] }
+  /** The admin editor body to render — resolved once here so the client just reads it. Defaults from the
+   *  `blocks` flag (`'blocks'` / `'fields'`); an explicit `def.editor` (incl. extension types) wins. */
+  editor: string
+  /** Whether the collection appears in the admin rail (default true; `false` = system/config store). */
+  nav: boolean
+  label?: { singular?: Localized; plural?: Localized; new?: Localized }
+  icon?: string
+  fields: Record<string, SerializedField>
+  /** Normalized admin editor layout (rows / named groups). Resolved once here; absent when the author
+   *  gave none (the admin then renders one field per row). Plain JSON — crosses the wire untouched. */
+  fieldLayout?: LayoutNode[]
+}
+
+// A field `default` is typed `unknown`; it crosses the HTTP/JSON boundary verbatim, so anything
+// that is not plain JSON (Date, Map, Set, function, NaN, class instance, …) would silently mismatch
+// or throw on serialize. Keep only values that survive JSON unchanged.
+function isJsonSafe(value: unknown): boolean {
+  if (value === null) return true
+  switch (typeof value) {
+    case 'string':
+    case 'boolean':
+      return true
+    case 'number':
+      return Number.isFinite(value)
+    case 'object': {
+      if (Array.isArray(value)) return value.every(isJsonSafe)
+      const proto = Object.getPrototypeOf(value)
+      if (proto !== Object.prototype && proto !== null) return false
+      return Object.values(value as Record<string, unknown>).every(isJsonSafe)
+    }
+    default:
+      return false
+  }
+}
+
+export function serializeField(field: FieldDef): SerializedField {
+  const out: SerializedField = {
+    type: field.type,
+    required: field.required ?? false,
+    translatable: field.translatable ?? false,
+    unique: field.unique ?? false,
+  }
+  if (isSingleRefColumn(field)) out.single = true
+  if (field.label) out.label = field.label
+  if ('default' in field && isJsonSafe(field.default)) {
+    out.default = field.default
+  }
+  // Top-level (never inside `options`, which relations don't set and repeaters overwrite). One copy
+  // here flows to collection fields, repeater sub-fields (the recursion below), and serializeBlock.
+  if (field.condition) out.condition = field.condition
+  if (fieldIs(field, 'relation')) {
+    out.relation = {
+      collection: field.relation.collection,
+      many: field.relation.many ?? false,
+      ...(field.relation.labelField ? { labelField: field.relation.labelField } : {}),
+    }
+  } else if (fieldIs(field, 'repeater')) {
+    out.options = {
+      fields: serializeFields(field.options.fields),
+      ...(field.options.fieldLayout
+        ? { fieldLayout: resolveFieldLayout(field.options.fieldLayout, Object.keys(field.options.fields), 'repeater') }
+        : {}),
+    }
+  } else if ('options' in field && field.options && isJsonSafe(field.options)) {
+    // Gate options through the same JSON-safety guard as `default`: a custom defineFieldType config carrying a
+    // Date/function/Map/NaN would otherwise throw (or silently corrupt) the whole /api/collections response.
+    out.options = field.options as Record<string, unknown>
+  }
+  return out
+}
+
+export function serializeFields(fields: Record<string, FieldDef>): Record<string, SerializedField> {
+  const out: Record<string, SerializedField> = {}
+  for (const [key, def] of Object.entries(fields)) out[key] = serializeField(def)
+  return out
+}
+
+export function serializeCollection(def: CollectionDef): SerializedCollection {
+  return {
+    name: def.name,
+    mode: def.mode,
+    translatable: def.translatable ?? false,
+    pageLike: def.pageLike ?? false,
+    seo: def.seo ?? false,
+    status: def.status ?? false,
+    blocks: { enabled: def.blocks?.enabled ?? false, ...(def.blocks?.allowed ? { allowed: def.blocks.allowed } : {}) },
+    editor: def.editor ?? (def.blocks?.enabled ? 'blocks' : 'fields'),
+    nav: def.nav !== false,
+    ...(def.label ? { label: def.label } : {}),
+    ...(def.icon ? { icon: def.icon } : {}),
+    fields: serializeFields(def.fields),
+    ...(def.fieldLayout
+      ? { fieldLayout: resolveFieldLayout(def.fieldLayout, Object.keys(def.fields), `collection "${def.name}"`) }
+      : {}),
+  }
+}
+
+export interface SerializedBlock {
+  name: string
+  label?: Localized
+  slots?: string[]
+  /** Icon name for the admin block picker (from the SFC's `defineBlock({ icon })`). */
+  icon?: string
+  /** Preview image (URL/path) shown above the name in the admin block picker (from `defineBlock({ image })`). */
+  image?: string
+  fields: Record<string, SerializedField>
+}
+
+// Structurally typed (not importing BlockDef) so `core` stays independent of the `fields` layer.
+// Block fields serialize identically to collection fields, so the admin FieldRenderer reuses them as-is.
+export function serializeBlock(def: { name: string; label?: Localized; slots?: string[]; icon?: string; image?: string; fields: Record<string, FieldDef> }): SerializedBlock {
+  return {
+    name: def.name,
+    ...(def.label ? { label: def.label } : {}),
+    ...(def.slots?.length ? { slots: def.slots } : {}),
+    ...(def.icon ? { icon: def.icon } : {}),
+    ...(def.image ? { image: def.image } : {}),
+    fields: serializeFields(def.fields),
+  }
+}

package/layers/core/server/utils/server-config.ts

@@ -0,0 +1,18 @@
+import kestrelConfig from '../../../../kestrel.config'
+import { resolveKestrel } from './kestrel-config'
+
+/**
+ * The Nitro runtimeConfig, or `undefined` for non-Nitro callers (node scripts, build) so they don't
+ * throw on `useRuntimeConfig()`. Server utils prefer the values the kestrel module put here (from the
+ * consumer's `kestrel: {}`), falling back to `resolveServerKestrel()` when it isn't populated.
+ */
+export function serverRuntimeConfig(): { kestrel?: Record<string, unknown>; public?: Record<string, unknown> } | undefined {
+  return typeof useRuntimeConfig === 'function'
+    ? (useRuntimeConfig() as { kestrel?: Record<string, unknown>; public?: Record<string, unknown> })
+    : undefined
+}
+
+/** Resolve Kestrel's own config file + env — the fallback when runtimeConfig isn't populated. */
+export function resolveServerKestrel(): ReturnType<typeof resolveKestrel> {
+  return resolveKestrel(kestrelConfig, process.env, process.cwd())
+}

package/layers/core/server/utils/sql.ts

@@ -0,0 +1,2 @@
+/** Escape LIKE metacharacters so a search for "a_b" / "%" matches them literally (paired with ESCAPE '\'). */
+export const escapeLike = (s: string): string => s.replace(/[\\%_]/g, (ch) => `\\${ch}`)

package/layers/core/server/utils/storage.local.ts

@@ -0,0 +1,117 @@
+import { mkdir, writeFile, readFile, unlink, access, copyFile, rm, rmdir, readdir, stat, rename } from 'node:fs/promises'
+import { dirname, resolve, sep } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import type { StorageDriver } from './storage'
+
+function joinURL(base: string, path: string): string {
+  return base.replace(/\/+$/, '') + '/' + path.replace(/^\/+/, '')
+}
+
+/** Whether an fs error proves the key is not there (missing, or a path component that is not a directory).
+ *  Anything else — EACCES, EIO/ESTALE on a network volume — means the driver could not TELL, and callers key
+ *  destructive decisions off that difference (the gallery index guard treats "absent" as licence to skip its
+ *  concurrency check and prune unreferenced ciphertext), so it must surface instead of reading as absence. */
+function provesMissing(error: unknown): boolean {
+  const code = (error as NodeJS.ErrnoException | null)?.code
+  return code === 'ENOENT' || code === 'ENOTDIR'
+}
+
+export function createLocalDriver(opts: { dir: string; baseUrl: string }): StorageDriver {
+  const root = resolve(opts.dir)
+  const abs = (key: string) => {
+    const path = resolve(root, key)
+    if (path !== root && !path.startsWith(root + sep)) {
+      throw new Error(`storage key escapes the uploads root: ${key}`)
+    }
+    return path
+  }
+  return {
+    async put(key, bytes) {
+      const path = abs(key)
+      await mkdir(dirname(path), { recursive: true })
+      // Write to a temp sibling then atomically rename into place: an overwrite (replace-upload, backfill
+      // re-put, republished HTML) never exposes a truncated/partial file to a concurrent reader (nginx / the
+      // static host), and a crash mid-write leaves the stale temp file, not a corrupt object at the real key.
+      const tmp = `${path}.${randomUUID()}.tmp`
+      try {
+        await writeFile(tmp, bytes)
+        await rename(tmp, path)
+      } catch (error) {
+        await unlink(tmp).catch(() => {})
+        throw error
+      }
+    },
+    async copy(srcKey, dstKey) {
+      const dst = abs(dstKey)
+      await mkdir(dirname(dst), { recursive: true })
+      await copyFile(abs(srcKey), dst)
+    },
+    async delete(key, opts) {
+      const path = abs(key)
+      try { await unlink(path) } catch (error) { if (!provesMissing(error)) throw error }
+      // Opt-in (publisher) only: remove parent dirs left empty (up to — never including — the root), so
+      // unpublishing `/a/b` leaves no orphan empty `a/b/`. OFF by default so the media library keeps a
+      // user-created folder after its last file is deleted. Stops climbing at the first non-empty dir.
+      if (!opts?.pruneEmptyDirs) return
+      let dir = dirname(path)
+      while (dir !== root && dir.startsWith(root + sep)) {
+        try { await rmdir(dir) } catch { break } // ENOTEMPTY (still holds files) or already gone → stop
+        dir = dirname(dir)
+      }
+    },
+    publicUrl(key) { return joinURL(opts.baseUrl, key) },
+    async get(key) {
+      // abs() reapplies the escape-guard: an attacker-influenced key must never read outside the root.
+      return readFile(abs(key))
+    },
+    async exists(key) {
+      try { await access(abs(key)); return true } catch (error) { if (provesMissing(error)) return false; throw error }
+    },
+    async stat(key) {
+      try { return { mtimeMs: (await stat(abs(key))).mtimeMs } } catch (error) { if (provesMissing(error)) return null; throw error }
+    },
+    async ensureDir(folder) {
+      await mkdir(abs(folder), { recursive: true })
+    },
+    async removeDir(folder) {
+      if (!folder) return
+      const path = abs(folder)
+      if (path === root) return // never remove the uploads root ('.', 'a/..', etc. resolve to it)
+      await rm(path, { recursive: true, force: true })
+    },
+    async list() {
+      // Every file under the root as a sorted POSIX-relative key (the put/delete key space), so the
+      // publish reconciler can set-difference against the keys it just wrote and prune the rest.
+      const out: string[] = []
+      async function walk(dir: string, prefix: string): Promise<void> {
+        let entries
+        try {
+          entries = await readdir(dir, { withFileTypes: true })
+        } catch (error) {
+          // A proven-absent dir (an uploads root not built yet, a subtree deleted concurrently) holds no
+          // keys. Anything else means the enumeration could not be performed, and callers that delete on
+          // the strength of an empty listing (the media removeDir guards) would read that as "nothing is
+          // stored here" and recursively wipe a subtree whose contents merely could not be read.
+          if (provesMissing(error)) return
+          throw error
+        }
+        for (const e of entries) {
+          const rel = prefix ? `${prefix}/${e.name}` : e.name
+          if (e.isDirectory()) await walk(resolve(dir, e.name), rel)
+          else if (e.isFile()) out.push(rel)
+        }
+      }
+      await walk(root, '')
+      return out.sort()
+    },
+    async listPrefix(prefix) {
+      // A namespace listing: every key under `<prefix>/` (normalised). Filters the full walk — fine for the
+      // small per-record namespaces this serves. Empty/`.` prefix → all keys (same as list()).
+      const all = await this.list!()
+      const p = prefix.replace(/^\/+|\/+$/g, '')
+      if (!p) return all
+      const under = `${p}/`
+      return all.filter((k) => k === p || k.startsWith(under))
+    },
+  }
+}

package/layers/core/server/utils/storage.s3.ts

@@ -0,0 +1,197 @@
+import { createHash } from 'node:crypto'
+import { AwsClient } from 'aws4fetch'
+import type { StorageDriver } from './storage'
+
+/**
+ * Non-secret S3 settings plus the env-only credentials. Built by `useStorageDriver` from
+ * `runtimeConfig.media.s3`; the factory is otherwise free of Nitro/Nuxt globals so it stays
+ * unit-testable with an injected `fetch`.
+ */
+export interface S3DriverOptions {
+  bucket: string
+  /** Signing region (default `us-east-1`). */
+  region?: string
+  /** Custom endpoint origin for S3-compatible services (R2/MinIO); omit for AWS S3. */
+  endpoint?: string
+  /** Key prefix prepended to every object key (slashes normalised away). */
+  prefix?: string
+  /** Public base URL objects are served from; `publicUrl` joins this + the full key. */
+  publicBaseUrl: string
+  accessKeyId: string
+  secretAccessKey: string
+  sessionToken?: string
+}
+
+const trimSlashes = (s: string) => s.replace(/^\/+|\/+$/g, '')
+const stripTrailing = (s: string) => s.replace(/\/+$/, '')
+const xmlEscape = (s: string) =>
+  s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;')
+const xmlUnescape = (s: string) =>
+  s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&')
+
+/**
+ * S3-compatible storage driver over SigV4-signed `fetch` (AWS S3, Cloudflare R2, MinIO). Path-style
+ * addressing throughout for maximum compatibility. Credentials are SigV4-signed by `aws4fetch`; the
+ * injected `fetchImpl` keeps it fully testable.
+ */
+export function createS3Driver(opts: S3DriverOptions, fetchImpl: typeof fetch = globalThis.fetch): StorageDriver {
+  const { bucket, publicBaseUrl } = opts
+  const region = opts.region || 'us-east-1'
+  const prefix = trimSlashes(opts.prefix || '')
+  const origin = opts.endpoint ? stripTrailing(opts.endpoint) : `https://s3.${region}.amazonaws.com`
+  const bucketUrl = `${origin}/${bucket}`
+  const client = new AwsClient({
+    accessKeyId: opts.accessKeyId,
+    secretAccessKey: opts.secretAccessKey,
+    sessionToken: opts.sessionToken,
+    service: 's3',
+    region,
+  })
+
+  const fullKey = (key: string) => (prefix ? `${prefix}/${key}` : key)
+  const encodePath = (k: string) => k.split('/').map(encodeURIComponent).join('/')
+  const objectUrl = (key: string) => `${bucketUrl}/${encodePath(fullKey(key))}`
+
+  async function send(method: string, url: string, init: { body?: Buffer | Uint8Array | string; headers?: Record<string, string> } = {}): Promise<Response> {
+    // Buffer/Uint8Array/string are all valid request bodies at runtime; the cast bridges the DOM `BodyInit`
+    // type (which omits Node's Buffer) at the single aws4fetch boundary.
+    const signed = await client.sign(url, { method, body: init.body as BodyInit | undefined, headers: init.headers })
+    return fetchImpl(signed)
+  }
+
+  /** One ListObjectsV2 page: the keys it lists plus the continuation token when more remain. */
+  async function listPage(listPrefix: string, token?: string): Promise<{ keys: string[]; next?: string }> {
+    const u = new URL(bucketUrl)
+    u.searchParams.set('list-type', '2')
+    u.searchParams.set('prefix', listPrefix)
+    if (token) u.searchParams.set('continuation-token', token)
+    const res = await send('GET', u.toString())
+    if (!res.ok) throw new Error(`S3 list failed (${res.status}) for prefix ${listPrefix}`)
+    const xml = await res.text()
+    const keys = [...xml.matchAll(/<Key>([^<]*)<\/Key>/g)].map((m) => xmlUnescape(m[1]))
+    const truncated = /<IsTruncated>\s*true\s*<\/IsTruncated>/i.test(xml)
+    const next = xml.match(/<NextContinuationToken>([^<]*)<\/NextContinuationToken>/)
+    return { keys, next: truncated && next ? xmlUnescape(next[1]) : undefined }
+  }
+
+  /** Multi-object delete (≤1000 keys, one page). Content-MD5 is required by AWS for this request. */
+  async function batchDelete(keys: string[]): Promise<void> {
+    if (!keys.length) return
+    const body = `<?xml version="1.0" encoding="UTF-8"?><Delete>`
+      + keys.map((k) => `<Object><Key>${xmlEscape(k)}</Key></Object>`).join('')
+      + `<Quiet>true</Quiet></Delete>`
+    const md5 = createHash('md5').update(body).digest('base64')
+    const res = await send('POST', `${bucketUrl}?delete`, {
+      body,
+      headers: { 'content-type': 'application/xml', 'content-md5': md5 },
+    })
+    if (!res.ok) throw new Error(`S3 batch delete failed (${res.status})`)
+    // Quiet mode still returns per-key failures as <Error> elements in the 200 body (retention lock,
+    // AccessDenied on some keys). Without parsing them a partial delete passes silently while objects
+    // remain — fail loud like every other method here, so removeDir/GC callers never claim a false success.
+    const text = await res.text()
+    if (text.includes('<Error>')) {
+      const failed = [...text.matchAll(/<Key>([^<]*)<\/Key>/g)].map((m) => m[1])
+      throw new Error(`S3 batch delete reported errors for ${failed.length || 'some'} key(s): ${failed.slice(0, 5).join(', ')}`)
+    }
+  }
+
+  return {
+    async list() {
+      // Page through every object under the driver prefix, returning keys relative to it so they line
+      // up with the keys `put`/`delete` take (the deploy compares them against freshly-uploaded keys).
+      const listPrefix = prefix ? `${prefix}/` : ''
+      const out: string[] = []
+      let token: string | undefined
+      do {
+        const { keys, next } = await listPage(listPrefix, token)
+        for (const k of keys) out.push(listPrefix && k.startsWith(listPrefix) ? k.slice(listPrefix.length) : k)
+        token = next
+      } while (token)
+      return out
+    },
+    async listPrefix(rel) {
+      // Keys under `<driverPrefix>/<rel>/`, returned relative to the driver root (same space as list()).
+      const r = trimSlashes(rel)
+      if (!r) return this.list!()
+      const base = prefix ? `${prefix}/` : ''
+      const listPrefix = `${fullKey(r)}/`
+      const out: string[] = []
+      let token: string | undefined
+      do {
+        const { keys, next } = await listPage(listPrefix, token)
+        for (const k of keys) out.push(base && k.startsWith(base) ? k.slice(base.length) : k)
+        token = next
+      } while (token)
+      return out
+    },
+    async put(key, bytes, contentType, opts) {
+      const headers: Record<string, string> = { 'content-type': contentType }
+      if (opts?.cacheControl) headers['cache-control'] = opts.cacheControl
+      if (opts?.contentEncoding) headers['content-encoding'] = opts.contentEncoding
+      const res = await send('PUT', objectUrl(key), { body: bytes, headers })
+      if (!res.ok) throw new Error(`S3 put failed (${res.status}) for ${key}`)
+    },
+    async copy(srcKey, dstKey) {
+      const res = await send('PUT', objectUrl(dstKey), {
+        headers: { 'x-amz-copy-source': `/${bucket}/${encodePath(fullKey(srcKey))}` },
+      })
+      if (!res.ok) throw new Error(`S3 copy failed (${res.status}) ${srcKey} → ${dstKey}`)
+      // CopyObject can fail *after* the request was accepted and still answer 200, reporting it as an
+      // <Error> body instead of a status. Callers (relocate/duplicate) delete the source once copy
+      // resolves, so a silent success here destroys the only bytes — parse the body and fail loud.
+      // A real success is `<CopyObjectResult>…`; some S3-compatibles send an empty body.
+      const text = await res.text()
+      if (text.includes('<Error>')) {
+        const code = text.match(/<Code>([^<]*)<\/Code>/)?.[1] ?? 'unknown'
+        throw new Error(`S3 copy failed (200 with error body: ${code}) ${srcKey} → ${dstKey}`)
+      }
+    },
+    async delete(key) {
+      const res = await send('DELETE', objectUrl(key))
+      // DELETE is idempotent on S3; a 404 just means it was already gone (matches the local driver).
+      if (!res.ok && res.status !== 404) throw new Error(`S3 delete failed (${res.status}) for ${key}`)
+    },
+    publicUrl(key) {
+      return `${stripTrailing(publicBaseUrl)}/${fullKey(key)}`
+    },
+    async get(key) {
+      const res = await send('GET', objectUrl(key))
+      // A read has no idempotent empty result: a 404 (or any non-200) is a genuine error the caller
+      // handles (backfill skips, GC keeps-on-doubt) rather than a silently-empty buffer.
+      if (!res.ok) throw new Error(`S3 get failed (${res.status}) for ${key}`)
+      return Buffer.from(await res.arrayBuffer())
+    },
+    async exists(key) {
+      const res = await send('HEAD', objectUrl(key))
+      if (res.status === 200) return true
+      if (res.status === 404) return false
+      throw new Error(`S3 head failed (${res.status}) for ${key}`)
+    },
+    async stat(key) {
+      const res = await send('HEAD', objectUrl(key))
+      if (res.status === 404) return null
+      if (res.status !== 200) throw new Error(`S3 head failed (${res.status}) for ${key}`)
+      const lastModified = res.headers.get('last-modified')
+      const mtimeMs = lastModified ? Date.parse(lastModified) : NaN
+      // A gateway/CDN that strips (or garbles) Last-Modified leaves the age unknown; reporting 0 would
+      // date the object to 1970 and let every age/grace-window comparison treat it as ancient.
+      return { mtimeMs: Number.isFinite(mtimeMs) ? mtimeMs : null }
+    },
+    async ensureDir() {
+      // No-op: S3 has a flat keyspace with no real directories. Empty folders live only as DB rows.
+    },
+    async removeDir(folder) {
+      const f = stripTrailing(String(folder ?? '')).trim()
+      if (!f) return // root guard: never list/delete the whole bucket
+      const listPrefix = `${fullKey(f)}/`
+      if (listPrefix === '/') return // defense in depth: an empty prefix would match every object
+      let token: string | undefined
+      do {
+        const { keys, next } = await listPage(listPrefix, token)
+        await batchDelete(keys)
+        token = next
+      } while (token)
+    },
+  }
+}

package/layers/core/server/utils/storage.ts

@@ -0,0 +1,90 @@
+import { createLocalDriver } from './storage.local'
+import { createS3Driver } from './storage.s3'
+import type { ResolvedImagePolicy } from './kestrel-config'
+
+/** Optional per-object write metadata. Omitted by media uploads; the static-output deploy sets `cacheControl`. */
+export interface PutOptions {
+  /** `Cache-Control` value (S3 stores it as object metadata served on GET; the local driver ignores it). */
+  cacheControl?: string
+  /** `Content-Encoding` (e.g. `br`/`gzip`) for a pre-compressed object, so a reverse proxy can serve it
+   *  as-is. S3 stores + serves it as object metadata; the local driver ignores it. */
+  contentEncoding?: string
+}
+
+export interface DeleteOptions {
+  /** Local driver only: after removing the file, also remove parent dirs left empty (up to, never
+   *  including, the root). The publisher opts in so an unpublished page leaves no orphan folder; media
+   *  uploads leave it OFF so a user-created library folder survives deleting its last file. S3 has no
+   *  real directories, so the S3 driver ignores it. */
+  pruneEmptyDirs?: boolean
+}
+
+export interface StorageDriver {
+  put(key: string, bytes: Buffer | Uint8Array, contentType: string, opts?: PutOptions): Promise<void>
+  copy(srcKey: string, dstKey: string): Promise<void>
+  delete(key: string, opts?: DeleteOptions): Promise<void>
+  publicUrl(key: string): string
+  /** Read an object's bytes back. Rejects when the key is missing (a read, unlike idempotent delete, has
+   *  no empty fallback). Backfill / GC re-derivation and the dev on-demand deriver need the original. */
+  get?(key: string): Promise<Buffer>
+  exists?(key: string): Promise<boolean>
+  /** An object's last-modified time (epoch ms), or null when the key is missing. Used by the gallery blob
+   *  GC to spare recently-uploaded (not-yet-indexed) blobs from a racing reconcile. `mtimeMs: null` means
+   *  the store does not expose an age — callers must treat that as unknown, not as old. */
+  stat?(key: string): Promise<{ mtimeMs: number | null } | null>
+  ensureDir?(folder: string): Promise<void>
+  removeDir?(folder: string): Promise<void>
+  /** Every object key under the driver's configured prefix, relative to it (i.e. the put/delete space).
+   *  Rejects when the enumeration itself fails: callers delete on the strength of an empty listing, so
+   *  "could not enumerate" must never arrive as "there is nothing here". */
+  list?(): Promise<string[]>
+  /** Like `list()` but restricted to keys under `prefix` (a sub-path of the put/delete space), returned
+   *  relative to the driver root. Used to reconcile a per-record namespace against its index (drop strays),
+   *  and as the media guard against recursively removing a path that still holds unmanaged objects — so it
+   *  rejects on a failed enumeration just like `list()`. */
+  listPrefix?(prefix: string): Promise<string[]>
+}
+
+/** The `runtimeConfig.media` namespace as the `kestrel` module writes it. */
+export interface MediaRuntimeConfig {
+  driver: string
+  maxUploadBytes: number
+  allowedMimes?: string
+  imagePolicy?: ResolvedImagePolicy
+  local: { dir: string; baseUrl: string }
+  s3: {
+    bucket: string; region: string; endpoint: string; prefix: string; publicBaseUrl: string
+    accessKeyId: string; secretAccessKey: string; sessionToken: string
+  }
+}
+
+/** Reads that namespace with its real shape. Nuxt derives runtimeConfig types from the values present at
+ *  type generation, so the nested variant specs arrive widened to `{}[]` and every consumer would otherwise
+ *  assert its own ad-hoc shape. One assertion here also makes a read of a key the module never writes
+ *  (e.g. a top-level `baseUrl`) a compile error instead of a silent `undefined`. */
+export function mediaRuntimeConfig(): MediaRuntimeConfig {
+  return useRuntimeConfig().media as MediaRuntimeConfig
+}
+
+export function useStorageDriver(): StorageDriver {
+  const media = mediaRuntimeConfig()
+  if (media.driver === 's3') {
+    const s = media.s3
+    // publicBaseUrl is required too: without it publicUrl() would emit relative `/key` URLs that resolve
+    // against the app origin (which serves no uploads on S3) instead of the bucket/CDN — breaking media.
+    if (!s?.bucket || !s.publicBaseUrl || !s.accessKeyId || !s.secretAccessKey) {
+      throw createError({ statusCode: 500, statusMessage: 'S3 media driver is not configured: bucket, publicBaseUrl, and credentials (KESTREL_S3_ACCESS_KEY_ID / _SECRET_ACCESS_KEY) are required' })
+    }
+    return createS3Driver({
+      bucket: s.bucket,
+      region: s.region,
+      endpoint: s.endpoint || undefined,
+      prefix: s.prefix,
+      publicBaseUrl: s.publicBaseUrl,
+      accessKeyId: s.accessKeyId,
+      secretAccessKey: s.secretAccessKey,
+      sessionToken: s.sessionToken || undefined,
+    })
+  }
+  return createLocalDriver(media.local)
+}

package/layers/core/server/utils/write-events.ts

@@ -0,0 +1,31 @@
+import type { CollectionDef } from './defineCollection'
+
+/**
+ * A tiny write-event bus (mirrors the populate registry): the CRUD writes emit, and a higher layer
+ * subscribes — so `core` stays independent of `public`'s publish concern. The publish plugin registers
+ * a listener that classifies the write and enqueues an incremental republish. A listener that throws is
+ * swallowed: a publishing failure must never break the actual content write.
+ */
+export interface WriteEvent {
+  def: CollectionDef
+  before: Record<string, unknown> | null
+  after: Record<string, unknown> | null
+}
+
+type WriteListener = (event: WriteEvent) => void
+
+const listeners: WriteListener[] = []
+
+export function registerWriteListener(fn: WriteListener): void {
+  listeners.push(fn)
+}
+
+export function clearWriteListeners(): void {
+  listeners.length = 0
+}
+
+export function emitWrite(def: CollectionDef, before: WriteEvent['before'], after: WriteEvent['after']): void {
+  for (const fn of listeners) {
+    try { fn({ def, before, after }) } catch (error) { console.error('[kestrel] write listener failed:', error) }
+  }
+}