@michaelthielemann/kestrel 3.0.1 → 4.0.0

package/layers/core/server/plugins/02.schema-sync.ts

@@ -1,14 +1,9 @@
 import collections from '#kestrel/collections'
 import schemaTables from '#kestrel/schema-tables'
 import type { AnySQLiteTable } from 'drizzle-orm/sqlite-core'
-import type { BuiltCollection } from '../utils/collection-types'
-import type { CollectionDef } from '../utils/defineCollection'
+import { describeOp, desiredFromCollections, isDestructive, planOps, runDevSchemaSync, sqlite, useDb } from '@michaelthielemann/kestrel-core'
+import type { BuiltCollection, CollectionDef, SyncDb } from '@michaelthielemann/kestrel-core'
 import { resolveServerKestrel, serverRuntimeConfig } from '../utils/server-config'
-import { desiredFromCollections } from '../schema/bootstrap'
-import { planOps, describeOp, isDestructive, type SyncDb } from '../schema/sync'
-import { sqlite } from '../schema/dialect'
-import { runDevSchemaSync } from '../schema/dev-sync'
-
 // Dev-only schema auto-sync (ADR-0002). Runs after 00.migrate, so built-in collections are already
 // migrated and this is a no-op on them; it additively reconciles the live DB to whatever the registered
 // collections (+ the discovered standalone tables) now compile to — so adding a collection or a field

package/layers/core/server/plugins/04.outbox-worker.ts

@@ -0,0 +1,31 @@
+import { buildOutboxPipelines, makeTicker, registerPipeline, useDb } from '@michaelthielemann/kestrel-core'
+/** Hard-coded to `content` — the only module with an outbox table today; extend alongside
+ *  `pipelines/outbox.ts` if a second module gets one. */
+const OUTBOX_MODULE = 'content'
+const POLL_INTERVAL_MS = 1000
+
+/**
+ * The outbox worker: NOT a Nitro `scheduledTask` (those run per-request-worker in a way that doesn't suit
+ * an always-on background loop here) — a plain `setInterval` loop started at plugin init, `unref`'d so it
+ * never keeps the process alive on its own (a test/dev server can still exit while it's running).
+ *
+ * Polls every tick, unconditionally — no `PRAGMA data_version` short-circuit: `useDb()` is the process-
+ * wide singleton connection every write also goes through, and a connection never observes its OWN writes
+ * bumping `data_version` (only a write from a DIFFERENT connection does), so gating on it here would go
+ * permanently blind after the first write this same connection ever made. The poll query itself is a
+ * covered index search (see `outbox.ts`'s `readPendingOutbox`), cheap enough at a 1s interval to not need
+ * a short-circuit at all.
+ */
+export default defineNitroPlugin(() => {
+  // `makeTicker` takes `useDb` itself (a thunk), not its result — nothing here calls it, so the db is
+  // still untouched at plugin-init time; the interval callback is the first thing that ever does.
+  const tick = makeTicker(useDb, OUTBOX_MODULE)
+
+  // Registration only — nothing here resolves a pipeline or reads the collection registry at init.
+  for (const def of buildOutboxPipelines()) registerPipeline(def)
+
+  const timer = setInterval(() => {
+    tick().catch((error: unknown) => console.error('[kestrel] outbox worker tick failed', error))
+  }, POLL_INTERVAL_MS)
+  timer.unref?.()
+})

package/layers/core/server/plugins/05.reindex-refs.ts

@@ -0,0 +1,5 @@
+import { registerReindexRefs } from '@michaelthielemann/kestrel-core'
+
+export default defineNitroPlugin(() => {
+  registerReindexRefs()
+})

package/layers/core/server/routes/__kestrel/dashboard.get.ts

@@ -0,0 +1,29 @@
+import { allCollections, buildPipelineIndex, renderDashboard } from '@michaelthielemann/kestrel-core'
+import { PLUGIN_ORDER } from '../../../modules/plugin-order/plugin-order'
+
+/**
+ * Dev-only introspection dashboard: gathers live registry state, so it reflects the CONSUMER's own
+ * collections/pipelines/overrides — not a static analysis of Kestrel's own source. File-based
+ * `server/routes/**` modules are compiled into production builds unconditionally, so the
+ * `import.meta.dev` check below is the real guard: Nitro inlines it to `false` in production and
+ * dead-code-eliminates everything past it, leaving only the 404.
+ */
+export default defineEventHandler((event) => {
+  if (!import.meta.dev) {
+    throw createError({ statusCode: 404, statusMessage: 'Not found' })
+  }
+  const collections = allCollections().map((c) => ({
+    name: c.name,
+    mode: c.def.mode,
+    translatable: Boolean(c.def.translatable),
+    fieldCount: Object.keys(c.def.fields).length,
+  }))
+  const html = renderDashboard({
+    pipelines: buildPipelineIndex(),
+    pluginOrder: PLUGIN_ORDER.map((p) => ({ layer: p.layer, file: p.file, after: p.after })),
+    collections,
+    generatedAt: new Date().toISOString(),
+  })
+  setHeader(event, 'content-type', 'text/html; charset=utf-8')
+  return html
+})

package/layers/core/server/tasks/db/migrate-module.ts

@@ -0,0 +1,83 @@
+import collections from '#kestrel/collections'
+import schemaTables from '#kestrel/schema-tables'
+import moduleManifests from '#kestrel/module-manifests'
+import type { AnySQLiteTable } from 'drizzle-orm/sqlite-core'
+import type { OwnershipManifest } from '@michaelthielemann/kestrel-contracts'
+import { buildContentManifest, describeOp, desiredFromCollections, isDestructive, opTable, orderManifests, planOps, sqlite, syncSchema, useDb } from '@michaelthielemann/kestrel-core'
+import type { BuiltCollection, CollectionDef, Dialect, SchemaSnapshot, SyncDb } from '@michaelthielemann/kestrel-core'
+import { resolveServerKestrel, serverRuntimeConfig } from '../../utils/server-config'
+// The per-module counterpart to `db:migrate` (ADR-0012): runs the SAME diff/apply engine, but scoped to
+// one ownership manifest's tables at a time, in a fixed order — `content` (the collection/base schema
+// other modules are conceptually layered on) first, then every discovered module manifest
+// (`module-order.ts`'s `MODULE_MIGRATION_ORDER`), then an `unmanaged` catch-all for any table no
+// manifest yet claims (never silently skipped). Payload/trigger mirror `db:migrate` exactly — {module:
+// "media"}=one module only, otherwise every module in order; {check:true}=dry-run, {force:true}=rebuilds,
+// {drop:[names]}=drop tables. Same dev/prod trigger shape as `db:migrate` (see that file's header).
+type ModulePayload = { module?: string; check?: boolean; force?: boolean; drop?: string[] }
+type ModuleResult =
+  | { module: string; check: true; pending: string[]; destructive: string[] }
+  | { module: string; applied: string[]; skipped: string[] }
+
+function runOne(
+  module: string,
+  tables: readonly string[],
+  client: SyncDb,
+  desired: SchemaSnapshot,
+  dialect: Dialect,
+  p: ModulePayload,
+): ModuleResult {
+  if (p.check === true) {
+    const ops = planOps(client, desired, dialect).filter((op) => tables.includes(opTable(op)))
+    const destructive = ops.filter(isDestructive).map(describeOp)
+    return { module, check: true, pending: dialect.render(ops), destructive }
+  }
+
+  const { applied, skipped } = syncSchema(client, desired, {
+    allowDestructive: p.force === true,
+    dropTables: Array.isArray(p.drop) ? p.drop : undefined,
+    tables,
+  }, dialect)
+  if (skipped.length) {
+    console.warn(`[kestrel] db:migrate-module(${module}) withheld ${skipped.length} destructive change(s) — opt in with {"force":true} (rebuilds) / {"drop":[…]} (drops):\n  - ${skipped.map(describeOp).join('\n  - ')}`)
+  }
+  console.info(`[kestrel] db:migrate-module(${module}) applied ${applied.length} statement(s)`)
+  return { module, applied, skipped: skipped.map(describeOp) }
+}
+
+export default defineTask<ModuleResult[]>({
+  meta: {
+    name: 'db:migrate-module',
+    description: 'Per-module schema migration, ordered (content → media → publishing → unmanaged). {module:"name"}=one module only, otherwise every module in order. {check}/{force}/{drop} match db:migrate.',
+  },
+  run({ payload }) {
+    const p = (payload ?? {}) as ModulePayload
+    const desired = desiredFromCollections(collections as (CollectionDef | BuiltCollection)[], {
+      toggles: (serverRuntimeConfig()?.kestrel?.collections ?? resolveServerKestrel().collections) as Record<string, boolean>,
+      extraTables: schemaTables as AnySQLiteTable[],
+    })
+    const client = (useDb() as unknown as { $client: SyncDb }).$client
+    const dialect = sqlite
+
+    const manifests = orderManifests([buildContentManifest(), ...(moduleManifests as OwnershipManifest[])])
+    const claimed = new Set(manifests.flatMap((m) => m.tables))
+    // The `unmanaged` bucket's table list: every table any pending op touches that no manifest claims —
+    // computed up front so both `check` and apply modes scope to the SAME set (rather than an unfiltered
+    // rescan, which in apply mode would re-touch already-migrated tables and in check mode would re-list
+    // every module's pending ops a second time under `unmanaged`).
+    const unmanagedTables = [...new Set(planOps(client, desired, dialect).map(opTable))].filter((t) => !claimed.has(t))
+
+    if (p.module) {
+      const manifest = manifests.find((m) => m.module === p.module)
+      const tables = manifest ? manifest.tables : p.module === 'unmanaged' ? unmanagedTables : undefined
+      if (!tables) {
+        const known = [...manifests.map((m) => m.module), 'unmanaged'].join(', ')
+        throw new Error(`kestrel: db:migrate-module: unknown module "${p.module}" — known: ${known}`)
+      }
+      return { result: [runOne(p.module, tables, client, desired, dialect, p)] }
+    }
+
+    const results = manifests.map((m) => runOne(m.module, m.tables, client, desired, dialect, p))
+    results.push(runOne('unmanaged', unmanagedTables, client, desired, dialect, p))
+    return { result: results }
+  },
+})

package/layers/core/server/tasks/db/migrate-revisions.ts

@@ -0,0 +1,20 @@
+import { migrateRevisions, useDb, type MigrateRevisionsResult } from '@michaelthielemann/kestrel-core'
+
+// Thin Nitro wrapper (defineTask is a runtime global) around the core, independently-unit-tested
+// `migrateRevisions` (db/revision-migration.ts) — same sync/task split as db:migrate (schema/sync.ts +
+// tasks/db/migrate.ts). Dev: GET/POST http://localhost:3000/_nitro/tasks/db:migrate-revisions ; prod: call
+// runTask('db:migrate-revisions', { payload }) from inside the process — the built node-server has no task
+// CLI/endpoint. Payload: {force:true} required, or the run refuses.
+export default defineTask<MigrateRevisionsResult[]>({
+  meta: {
+    name: 'db:migrate-revisions',
+    description: 'Seed revision 1 for every existing row with no revision history yet. Requires {"force":true}.',
+  },
+  run({ payload }) {
+    const p = (payload ?? {}) as { force?: boolean }
+    const result = migrateRevisions(useDb(), { force: p.force === true })
+    const totalSeeded = result.reduce((n, r) => n + r.seeded, 0)
+    console.info(`[kestrel] db:migrate-revisions seeded ${totalSeeded} revision(s) across ${result.length} collection(s)`)
+    return { result }
+  },
+})

package/layers/core/server/tasks/db/migrate.ts

@@ -1,13 +1,9 @@
 import collections from '#kestrel/collections'
 import schemaTables from '#kestrel/schema-tables'
 import type { AnySQLiteTable } from 'drizzle-orm/sqlite-core'
-import type { BuiltCollection } from '../../utils/collection-types'
-import type { CollectionDef } from '../../utils/defineCollection'
+import { describeOp, desiredFromCollections, isDestructive, planOps, sqlite, syncSchema, useDb } from '@michaelthielemann/kestrel-core'
+import type { BuiltCollection, CollectionDef, SyncDb } from '@michaelthielemann/kestrel-core'
 import { resolveServerKestrel, serverRuntimeConfig } from '../../utils/server-config'
-import { desiredFromCollections } from '../../schema/bootstrap'
-import { planOps, syncSchema, isDestructive, describeOp, type SyncDb } from '../../schema/sync'
-import { sqlite } from '../../schema/dialect'
-
 // Explicit schema-migrate step for production (ADR-0002). Dev auto-syncs additively at boot
 // (02.schema-sync); prod boot never auto-DDLs, so an operator runs this task. Triggering (Nuxt 4.4 /
 // Nitro 2.13 — there is NO `nuxi task run`):

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

@@ -1,14 +1,14 @@
 import kestrelConfig from '../../../../kestrel.config'
-import { resolveKestrel } from './kestrel-config'
+import { resolveKestrel, type ResolvedKestrel } from '@michaelthielemann/kestrel-core'
 
 /**
  * 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 {
+export function serverRuntimeConfig(): { kestrel?: Record<string, unknown>; media?: Record<string, unknown>; public?: Record<string, unknown> } | undefined {
   return typeof useRuntimeConfig === 'function'
-    ? (useRuntimeConfig() as { kestrel?: Record<string, unknown>; public?: Record<string, unknown> })
+    ? (useRuntimeConfig() as { kestrel?: Record<string, unknown>; media?: Record<string, unknown>; public?: Record<string, unknown> })
     : undefined
 }
 
@@ -16,3 +16,66 @@ export function serverRuntimeConfig(): { kestrel?: Record<string, unknown>; publ
 export function resolveServerKestrel(): ReturnType<typeof resolveKestrel> {
   return resolveKestrel(kestrelConfig, process.env, process.cwd())
 }
+
+/**
+ * The full `ResolvedKestrel` shape, merging every server util's own `runtimeConfig ?? resolveServerKestrel()`
+ * precedence into ONE call — the boot-time config-wiring plugin (`00.config.ts`) calls this once and
+ * pushes the result into the (eventually package-side) config provider, so package code never calls
+ * `useRuntimeConfig()` itself. Per-field precedence matches each field's existing reader exactly (the
+ * kestrel module writes a CLOSED set of fields into `runtimeConfig.kestrel`/`.public` — see
+ * `layers/core/modules/kestrel/index.ts`; anything it doesn't write there falls through to the
+ * `resolveServerKestrel()` base for every reader, unchanged from before this function existed).
+ */
+export function resolveServerKestrelConfig(): ResolvedKestrel {
+  const rc = serverRuntimeConfig()
+  const fallback = resolveServerKestrel()
+  const srv = (rc?.kestrel ?? {}) as Partial<Record<string, unknown>>
+  const pub = rc?.public as { locales?: string[]; primaryLocale?: string; prefixPrimary?: boolean } | undefined
+  // `runtimeConfig.media` is a TOP-LEVEL key (sibling to `.kestrel`/`.public`, not nested under `.kestrel`
+  // — see `layers/core/modules/kestrel/index.ts`'s `rc.media = {...}`), and it is the ONLY place the S3
+  // credentials + every Nitro `NUXT_MEDIA_*`/`NUXT_MEDIA_S3_*` env override (docs/guide/configuration.md) ever
+  // land — `resolveKestrel`'s own pure computation never sees them. Merged in wholesale (undefined ⇒ the
+  // module never ran ⇒ fall through to the pure fallback), mirroring `output`'s existing merge below.
+  const rcMedia = rc?.media as {
+    driver?: string
+    maxUploadBytes?: number
+    allowedMimes?: string
+    imagePolicy?: ResolvedKestrel['media']['imagePolicy']
+    local?: { dir?: string; baseUrl?: string }
+    s3?: { bucket?: string; region?: string; endpoint?: string; prefix?: string; publicBaseUrl?: string; accessKeyId?: string; secretAccessKey?: string; sessionToken?: string }
+  } | undefined
+  // The locale trio is populated together or not at all (see `locale.ts`'s original `resolved()`) — a
+  // partial `runtimeConfig.public` (e.g. `locales` present but `primaryLocale` absent) falls through to
+  // the fallback for all three rather than mixing sources mid-trio.
+  const locale = pub?.locales?.length && pub.primaryLocale
+    ? { supportedLocales: pub.locales, primaryLocale: pub.primaryLocale, prefixPrimary: pub.prefixPrimary === true }
+    : { supportedLocales: fallback.supportedLocales, primaryLocale: fallback.primaryLocale, prefixPrimary: fallback.prefixPrimary }
+  return {
+    ...fallback,
+    ...locale,
+    dbPath: (srv.dbPath as string | undefined) ?? fallback.dbPath,
+    siteUrl: (srv.siteUrl as string | undefined) ?? fallback.siteUrl,
+    siteName: (srv.siteName as string | undefined) ?? fallback.siteName,
+    siteDescription: (srv.siteDescription as string | undefined) ?? fallback.siteDescription,
+    media: rcMedia ? {
+      dir: rcMedia.local?.dir ?? fallback.media.dir,
+      baseUrl: rcMedia.local?.baseUrl ?? fallback.media.baseUrl,
+      driver: (rcMedia.driver as 'local' | 's3' | undefined) ?? fallback.media.driver,
+      maxUploadBytes: rcMedia.maxUploadBytes ?? fallback.media.maxUploadBytes,
+      allowedMimes: rcMedia.allowedMimes ?? fallback.media.allowedMimes,
+      imagePolicy: rcMedia.imagePolicy ?? fallback.media.imagePolicy,
+      s3: { ...fallback.media.s3, ...rcMedia.s3 },
+    } : fallback.media,
+    collections: (srv.collections as ResolvedKestrel['collections'] | undefined) ?? fallback.collections,
+    aiDisclosure: (srv.aiDisclosure as ResolvedKestrel['aiDisclosure'] | undefined) ?? fallback.aiDisclosure,
+    seo: (srv.seo as ResolvedKestrel['seo'] | undefined) ?? fallback.seo,
+    delivery: (srv.delivery as ResolvedKestrel['delivery'] | undefined) ?? fallback.delivery,
+    deliveryExempt: (srv.deliveryExempt as string[] | undefined) ?? fallback.deliveryExempt,
+    output: (srv.output as ResolvedKestrel['output'] | undefined) ?? fallback.output,
+    // `revisions` is NOT written into `runtimeConfig.kestrel` by the module today (pre-existing —
+    // unrelated to this seam), so this reads as `fallback.revisions` in every real boot right now; kept
+    // symmetric with every other field rather than special-cased, so a future module fix (writing
+    // `srv.revisions`) is picked up here for free.
+    revisions: (srv.revisions as ResolvedKestrel['revisions'] | undefined) ?? fallback.revisions,
+  }
+}

package/layers/fields/server/plugins/01.register-blocks-pipeline.ts

@@ -0,0 +1,7 @@
+import { registerPipeline } from '@michaelthielemann/kestrel-core'
+import { buildBlocksPipelines } from '@michaelthielemann/kestrel-fields'
+
+// Registration only — nothing resolves a pipeline here; the registry is read on the first request.
+export default defineNitroPlugin(() => {
+  for (const def of buildBlocksPipelines()) registerPipeline(def)
+})

package/layers/fields/server/plugins/01.register-field-populate.ts

@@ -1,5 +1,5 @@
-import { registerPopulator } from '../../../core/server/utils/populate'
-import { buildFieldTreePopulator } from '../utils/field-populate'
+import { registerPopulator } from '@michaelthielemann/kestrel-core'
+import { buildFieldTreePopulator } from '@michaelthielemann/kestrel-fields'
 
 // The single global row populator: walks a record's fields + block tree and dispatches each field to its
 // per-type populator (media / link / richtext / relation), each registered by its owning layer. It recurses

package/layers/media/app/components/KestrelImg.vue

@@ -2,8 +2,8 @@
 import { useBlurUp } from '../composables/useBlurUp'
 import { useMediaVariant } from '../composables/useMediaVariant'
 import { aiSourceTypeLabel } from '../utils/ai-disclosure'
-import type { ResolvedMedia } from '../../server/utils/resolve'
-import type { VariantFit, VariantFormat } from '../../../core/server/utils/kestrel-config'
+import type { ResolvedMedia } from '@michaelthielemann/kestrel-media'
+import type { VariantFit, VariantFormat } from '@michaelthielemann/kestrel-core'
 
 // The engine's responsive-image component: it renders a <picture> from the media's generated derivatives
 // AND its usage declares (to the generate-time scan) which sizes/formats are actually needed — "not in the
@@ -21,7 +21,7 @@ const props = defineProps<{
   /** Opt into a structurally-present but UNSTYLED EU AI Act disclosure badge (`.kestrel-img__ai-badge`),
    *  rendered only when `media.aiDisclosure` is set. Off by default: Kestrel must never publish a claim
    *  the consumer did not ask for, in a place/language/style it cannot know. The alternative escape hatch
-   *  is to read `media.aiDisclosure` and render your own element — see docs/media-uploads.md. */
+   *  is to read `media.aiDisclosure` and render your own element — see docs/guide/ai-disclosure.md. */
   aiBadge?: boolean
 }>()
 

package/layers/media/app/components/MediaLibrary.vue

@@ -62,8 +62,8 @@ async function onSaveMeta(alt: string, ai?: { aiSourceType: string | null; aiNot
     // so it rides alongside as top-level keys — and only when the viewer actually offered it, so a save
     // from a consumer with the feature off never clears a recorded disclosure. The precondition header
     // lets the server 409 instead of silently losing a concurrent edit from another open viewer tab.
-    await $fetch(`/api/media/${f.id}`, {
-      method: 'PATCH',
+    await $fetch(`/api/media/updateAsset/${f.id}`, {
+      method: 'POST',
       body: { translations: { [primary]: { alt } }, ...(ai ?? {}) },
       ...(f.updatedAt ? { headers: { 'x-kestrel-if-unmodified-since': String(new Date(f.updatedAt).getTime()) } } : {}),
     })

package/layers/media/app/components/field/Media.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { ref, computed, watch, nextTick } from 'vue'
 import type { FieldComponentProps } from '../../../../ui/app/utils/field-component'
-import type { FieldOf } from '../../../../core/server/utils/defineCollection'
+import type { FieldOf } from '@michaelthielemann/kestrel-core'
 import { reorder } from '../../../../ui/app/utils/reorder'
 import { commonFolder } from '../../utils/library'
 

package/layers/media/app/composables/useMediaResolver.ts

@@ -1,6 +1,6 @@
 import { reactive, toValue } from 'vue'
 import type { MaybeRefOrGetter } from 'vue'
-import type { ResolvedMedia } from '../../server/utils/resolve'
+import type { ResolvedMedia } from '@michaelthielemann/kestrel-media'
 
 // The client-facing resolved-media shape (`GET /api/media/resolve`) is the server resolver's own
 // return type — re-exported so consumers keep importing it from here, single-sourced so it can't drift.

package/layers/media/app/composables/useMediaUpload.ts

@@ -35,7 +35,7 @@ export function useMediaUpload(cb: UploadCallbacks = {}) {
     fd.append('filename', opts.filename ?? item.filename)
     if (opts.overwrite) fd.append('overwrite', 'true')
     try {
-      await $fetch('/api/media', { method: 'POST', body: fd })
+      await $fetch('/api/media/upload', { method: 'POST', body: fd })
       item.status = 'done'
     } catch (e) {
       type ConflictData = { suggestion?: string; existingId?: number }

package/layers/media/app/composables/useMediaVariant.ts

@@ -1,6 +1,6 @@
 import { computed, toValue, type MaybeRefOrGetter } from 'vue'
-import type { ResolvedMedia } from '../../server/utils/resolve'
-import type { ResolvedVariant } from '../../../core/server/utils/kestrel-config'
+import type { ResolvedMedia } from '@michaelthielemann/kestrel-media'
+import type { ResolvedVariant } from '@michaelthielemann/kestrel-core'
 import { buildPictureModel, requestVariantSpecs, type VariantRequest, type PictureModel } from '../utils/picture-model'
 
 /**

package/layers/media/app/utils/ai-disclosure.ts

@@ -1,4 +1,4 @@
-import type { AiSourceType } from '../../server/utils/resolve'
+import type { AiSourceType } from '@michaelthielemann/kestrel-media'
 
 /**
  * Default human-readable label for an EU AI Act source type — the badge text when no editor note was

package/layers/media/app/utils/library.ts

@@ -1,4 +1,4 @@
-import type { LibraryFolder } from '../../server/utils/library'
+import type { LibraryFolder } from '@michaelthielemann/kestrel-media'
 
 // Re-exported from the server util that produces it (`GET /api/media/library`) so the wire shape is
 // single-sourced.

package/layers/media/app/utils/ops.ts

@@ -1,7 +1,5 @@
 import type { LibraryItem } from './library'
-import type { OpItem, DeleteReport } from '../../server/utils/media-ops'
-import type { Conflict, RelocationReport } from '../../server/utils/relocate-ops'
-import type { MediaUsage } from '../../server/utils/usages'
+import type { OpItem, DeleteReport, Conflict, RelocationReport, MediaUsage } from '@michaelthielemann/kestrel-media'
 
 // Single-source the HTTP wire shapes from the server utils that own them — one definition, no drift.
 export type { OpItem, DeleteReport, Conflict, RelocationReport, MediaUsage }

package/layers/media/app/utils/picture-model.ts

@@ -1,5 +1,5 @@
-import type { ResolvedMedia } from '../../server/utils/resolve'
-import type { VariantFit, VariantFormat, ResolvedVariant } from '../../../core/server/utils/kestrel-config'
+import type { ResolvedMedia } from '@michaelthielemann/kestrel-media'
+import type { VariantFit, VariantFormat, ResolvedVariant } from '@michaelthielemann/kestrel-core'
 import { variantName } from './variant-name'
 
 /** What a `KestrelImg` / `useMediaVariant` call declares it needs. One call may declare MULTIPLE sizes and

package/layers/media/app/utils/variant-name.ts

@@ -1,4 +1,4 @@
-import type { VariantFit } from '../../../core/server/utils/kestrel-config'
+import type { VariantFit } from '@michaelthielemann/kestrel-core'
 
 export interface VariantShape {
   width: number

package/layers/media/server/middleware/ondemand-variants.ts

@@ -1,7 +1,8 @@
 import type { H3Event } from 'h3'
-import { deriveOnDemand, variantKeyFromPath } from '../utils/ondemand'
-import { useStorageDriver, mediaRuntimeConfig } from '../../../core/server/utils/storage'
-import { DEFAULT_IMAGE_POLICY } from '../../../core/server/utils/kestrel-config'
+import { clientIp } from '@michaelthielemann/kestrel-auth'
+import { allowlistMode, ipAllowed, parseAllowlist } from '@michaelthielemann/kestrel-access'
+import { deriveOnDemand, variantKeyFromPath, useStorageDriver, mediaRuntimeConfig, useMediaDb } from '@michaelthielemann/kestrel-media'
+import { DEFAULT_IMAGE_POLICY } from '@michaelthielemann/kestrel-core'
 
 /**
  * Whether the IP allow-list would deny this request, checked directly rather than relied on by ordering:
@@ -21,13 +22,13 @@ export default defineEventHandler(async (event) => {
   if (!import.meta.dev || event.method !== 'GET') return
   if (deniedByAllowlist(event)) return
   const cfg = mediaRuntimeConfig()
-  const key = variantKeyFromPath(event.path, cfg.local.baseUrl)
+  const key = variantKeyFromPath(event.path, cfg.baseUrl)
   if (key == null) return
   const driver = useStorageDriver()
   if (await driver.exists?.(key)) return
   // Dev is the diagnosis environment, so surface a real derive failure (missing original, sharp reject)
   // instead of silently 404ing — a broken preview <img> with no log violates the fail-loud convention.
-  const result = await deriveOnDemand(useDb(), driver, cfg.imagePolicy ?? DEFAULT_IMAGE_POLICY, key).catch((error) => {
+  const result = await deriveOnDemand(useMediaDb().db, driver, cfg.imagePolicy ?? DEFAULT_IMAGE_POLICY, key).catch((error) => {
     console.warn(`[kestrel] on-demand variant derive failed for ${key}:`, (error as Error)?.message ?? error)
     return null
   })

package/layers/media/server/plugins/01.register-media-pipelines.ts

@@ -0,0 +1,7 @@
+import { registerPipeline } from '@michaelthielemann/kestrel-core'
+import { buildMediaPipelines } from '@michaelthielemann/kestrel-media'
+
+// Registration only — nothing resolves a pipeline here; the registry is read on the first request.
+export default defineNitroPlugin(() => {
+  for (const def of buildMediaPipelines()) registerPipeline(def)
+})

package/layers/media/server/plugins/02.register-media.ts

@@ -1,10 +1,13 @@
 import { eq, getTableColumns } from 'drizzle-orm'
-import { media as mediaTable } from '../collections/media'
-import { registerFieldPopulator } from '../../../core/server/utils/populate'
-import { buildMediaFieldPopulator } from '../utils/populate'
-import { resolveMedia } from '../utils/resolve'
-import { useStorageDriver } from '../../../core/server/utils/storage'
-import { mediaCollectionEnabled } from '../utils/media-enabled'
+import { registerFieldPopulator } from '@michaelthielemann/kestrel-core'
+import {
+  media as mediaTable,
+  buildMediaFieldPopulator,
+  resolveMedia,
+  useStorageDriver,
+  mediaCollectionEnabled,
+  useMediaDb,
+} from '@michaelthielemann/kestrel-media'
 
 export default defineNitroPlugin(() => {
   // A consumer who turned the built-in off has no `media` table, so a row that still carries a media id
@@ -13,7 +16,7 @@ export default defineNitroPlugin(() => {
   const cols = getTableColumns(mediaTable) as Record<string, never>
   registerFieldPopulator('media', buildMediaFieldPopulator((id, locale) => {
     const driver = useStorageDriver()
-    const row = useDb().select().from(mediaTable).where(eq(cols.id, id)).get()
+    const row = useMediaDb().db.select().from(mediaTable).where(eq(cols.id, id)).get()
     return row ? resolveMedia(row as never, locale, (k) => driver.publicUrl(k)) : null
   }))
 })

package/layers/media/server/plugins/04.variant-capture.ts

@@ -1,13 +1,17 @@
-import { recordVariants, saveDiscoveredVariants } from '../utils/variant-capture'
+import { isRendererContext } from '@michaelthielemann/kestrel-access'
+import { recordVariants, saveDiscoveredVariants, useMediaDb } from '@michaelthielemann/kestrel-media'
 
 /**
  * Auto-discovery capture. `KestrelImg`/`useMediaVariant` stash their concrete specs on the render's
  * `event.context.kestrelVariants` during SSR. Renders count when they are either a PUBLISH render (the
- * incremental publisher marks them with the `x-kestrel-publish` header, see publisher.ts `renderRoute`) OR
- * a build-time PRERENDER render (the classic `nuxt generate` topology) — so live preview / stray runtime
- * renders never pollute the scan. For a publish, `publishFull` reconciles the drained accumulator once at
- * the end; the generate topology has no such orchestrator, so each prerendered route reconciles inline
- * WITHOUT draining and the growing accumulator converges to the full used set by the last route.
+ * incremental publisher runs it under `runAsRenderer`, see `render-live.ts`) OR a build-time PRERENDER
+ * render (the classic `nuxt generate` topology) — so live preview / stray runtime renders never pollute the
+ * scan. For a publish, `publishFull` reconciles the drained accumulator once at the end; the generate
+ * topology has no such orchestrator, so each prerendered route reconciles inline WITHOUT draining and the
+ * growing accumulator converges to the full used set by the last route.
+ *
+ * Gating uses the unforgeable AsyncLocalStorage signal `isRendererContext()` (the same one
+ * `delivery-live`'s catch-all uses), not the spoofable `x-kestrel-publish` header.
  *
  * NOTE: relies on `beforeResponse` firing for the publisher's `localFetch` renders / the prerenderer, and on
  * the app→server `event.context` bridge — verified by a real publish/generate, not the headless unit suite.
@@ -15,9 +19,9 @@ import { recordVariants, saveDiscoveredVariants } from '../utils/variant-capture
 export default defineNitroPlugin((nitroApp) => {
   nitroApp.hooks.hook('beforeResponse', (event) => {
     const isPrerender = import.meta.prerender === true
-    if (getRequestHeader(event, 'x-kestrel-publish') !== '1' && !isPrerender) return
+    if (!isRendererContext() && !isPrerender) return
     const specs = (event.context as { kestrelVariants?: unknown[] }).kestrelVariants
     if (Array.isArray(specs) && specs.length) recordVariants(specs as never)
-    if (isPrerender) saveDiscoveredVariants(useDb(), { clear: false })
+    if (isPrerender) saveDiscoveredVariants(useMediaDb().db, { clear: false })
   })
 })

package/layers/media/server/plugins/05.media-cleanup.ts

@@ -0,0 +1,5 @@
+import { registerMediaCleanup } from '@michaelthielemann/kestrel-media'
+
+export default defineNitroPlugin(() => {
+  registerMediaCleanup()
+})

package/layers/media/server/tasks/media/backfill.ts

@@ -1,6 +1,5 @@
-import { runBackfill } from '../../utils/backfill'
-import { useStorageDriver, mediaRuntimeConfig } from '../../../../core/server/utils/storage'
-import { DEFAULT_IMAGE_POLICY } from '../../../../core/server/utils/kestrel-config'
+import { runBackfill, useStorageDriver, mediaRuntimeConfig, useMediaDb } from '@michaelthielemann/kestrel-media'
+import { DEFAULT_IMAGE_POLICY } from '@michaelthielemann/kestrel-core'
 
 /**
  * Reconcile every media row's derivatives to the active variant registry: generate the missing sizes/formats
@@ -12,7 +11,7 @@ export default defineTask({
   meta: { name: 'media:backfill', description: 'Generate missing image variants + prune deregistered ones; {check:true}=dry-run' },
   async run({ payload }) {
     const policy = mediaRuntimeConfig().imagePolicy ?? DEFAULT_IMAGE_POLICY
-    const result = await runBackfill(useDb(), useStorageDriver(), policy, { check: !!(payload as { check?: boolean })?.check })
+    const result = await runBackfill(useMediaDb().db, useStorageDriver(), policy, { check: !!(payload as { check?: boolean })?.check })
     return { result }
   },
 })

package/layers/public/app/components/KestrelLink.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { computed, useSlots } from 'vue'
-import type { LinkValue } from '../../../core/server/utils/defineCollection'
+import type { LinkValue } from '@michaelthielemann/kestrel-core'
 import { linkToHref, linkLabel } from '../utils/link-href'
 
 // Generic renderer for the `link` field type, for consumer projects + blocks. Renders an <a> for any

package/layers/public/app/pages/[...slug].vue

@@ -99,7 +99,7 @@ const previewNotice = computed(() => {
 const previewRequested = route.query[PREVIEW_QUERY] === '1'
 const { data: previewSession } = previewRequested
   ? await useAsyncData('kestrel-preview-session', () =>
-      requestFetch('/api/auth/session').catch(() => ({ authenticated: false })))
+      requestFetch<{ authenticated: boolean }>('/api/session').catch(() => ({ authenticated: false })))
   : { data: ref<{ authenticated: boolean } | null>(null) }
 const previewActive = computed(() => previewRequested && previewSession.value?.authenticated === true)
 

package/layers/public/app/pages/__kestrel/preview.vue

@@ -8,14 +8,14 @@
  * Saved pageLike records preview at their REAL URL instead (higher fidelity); this page is the graceful
  * fallback so previews never regress to "save first".
  *
- * Admin-gated server-side: `useRequestFetch` forwards the incoming cookies to `/api/auth/session`
+ * Admin-gated server-side: `useRequestFetch` forwards the incoming cookies to `/api/session`
  * (the same seam the catch-all uses for draft rendering), and anonymous requests get a 404 — the
  * page's existence is not advertised. It is never linked, prerendered, or published (the publisher
  * enumerates DB page rows only), and carries noindex as belt-and-braces.
  */
 const requestFetch = useRequestFetch()
 const { data: session } = await useAsyncData('kestrel-preview-session', () =>
-  requestFetch('/api/auth/session').catch(() => ({ authenticated: false })),
+  requestFetch<{ authenticated: boolean }>('/api/session').catch(() => ({ authenticated: false })),
 )
 if (!session.value?.authenticated) throw createError({ statusCode: 404, statusMessage: 'Page not found' })
 

package/layers/public/app/utils/json-ld.ts

@@ -1,4 +1,4 @@
-import { localePath } from '../../../core/app/utils/locale-path'
+import { localePath } from '@michaelthielemann/kestrel-core/client'
 
 /** One published ancestor of the rendered page, outermost first — the breadcrumb trail. */
 export interface JsonLdAncestor {

package/layers/public/app/utils/link-href.ts

@@ -1,4 +1,4 @@
-import type { LinkValue } from '../../../core/server/utils/defineCollection'
+import type { LinkValue } from '@michaelthielemann/kestrel-core'
 
 // The server link populator (depth > 0) resolves an internal link's localized target path and attaches
 // it as `href`. Until that populator runs (or for a not-yet-resolved value), internal links fall back