@michaelthielemann/kestrel 1.6.0 → 1.7.0

package/layers/access/server/utils/ip-allowlist.ts

@@ -42,7 +42,10 @@ function parseCidr(token: string): Cidr | null {
   const slash = token.indexOf('/')
   const base = ipv4ToInt(slash === -1 ? token : token.slice(0, slash))
   if (base === null) return null
-  const bits = slash === -1 ? 32 : Number(token.slice(slash + 1))
+  // `Number()` alone would widen a malformed prefix into a mask: '' → 0 → 0.0.0.0/0, and '0x10'/'1e1' → 16/10.
+  const bitsRaw = slash === -1 ? '32' : token.slice(slash + 1).trim()
+  if (!/^\d+$/.test(bitsRaw)) return null
+  const bits = Number(bitsRaw)
   if (!Number.isInteger(bits) || bits < 0 || bits > 32) return null
   const mask = bits === 0 ? 0 : (0xffffffff << (32 - bits)) >>> 0
   return { base: (base & mask) >>> 0, mask }

package/layers/collections/server/plugins/02.register-relation-populate.ts

@@ -8,10 +8,13 @@ import { getOne } from '../../../core/server/utils/crud'
 // stale/deleted id (getOne 404 → null via `skipMissing`, other errors propagate — fail-loud), and runs at
 // `depth - 1`, so `populateRow` bails at 0 and cycles terminate. Registered per-type; the shared field-tree
 // walker (fields layer) dispatches it.
+// The reachability predicate is the registry-driven public set, NOT the guard's full decision — the guard
+// also folds in `registeredGrants()`, which this omits. So a collection opened to anonymous by a registered
+// grant is served on its own route but stays unexpanded here: fail-closed drift, never a widening.
 export default defineNitroPlugin(() => {
-  registerFieldPopulator('relation', buildRelationFieldPopulator((collection, id, depth, locale) => {
+  registerFieldPopulator('relation', buildRelationFieldPopulator((collection, id, depth, locale, publicOnly) => {
     const built = getCollection(collection)
     if (!built) return null
-    return skipMissing(() => getOne(useDb(), built, id, depth, locale, true) as Record<string, unknown>)
-  }))
+    return skipMissing(() => getOne(useDb(), built, id, depth, locale, true, publicOnly) as Record<string, unknown>)
+  }, (collection) => isPubliclyReadable(collection, publicReadableResources())))
 })

package/layers/collections/server/utils/populate-relations.ts

@@ -11,6 +11,7 @@ export type ResolveRecord = (
   id: number,
   depth: number,
   locale: string,
+  publicOnly: boolean,
 ) => Record<string, unknown> | null
 
 /**
@@ -36,31 +37,43 @@ export function skipMissing(fetch: () => Record<string, unknown>): Record<string
  * fails the whole read. The related read passes `ctx.depth - 1`; `populateRow` bails at depth 0, so a
  * relation cycle terminates. Registered per-type via `registerFieldPopulator('relation', …)`; the shared
  * field-tree walker drives it over top-level fields, block props, slots, and repeater entries.
+ *
+ * Under `ctx.publicOnly` a relation into a collection `isPublicCollection` rejects is left unexpanded
+ * (raw id only, NO `$<name>` sibling at all — a relation field targets exactly one collection, so a
+ * `many` relation is all-or-nothing): expansion must not reach a record the caller could not have
+ * requested directly. The check runs BEFORE `resolve`, so a withheld target never enters the memo.
  */
-export function buildRelationFieldPopulator(resolveRecord: ResolveRecord): FieldPopulator {
-  // The same target (collection+id+depth+locale) is resolved once — build-wide during a generate run
+export function buildRelationFieldPopulator(
+  resolveRecord: ResolveRecord,
+  isPublicCollection: (collection: string) => boolean,
+): FieldPopulator {
+  // The same target (collection+id+depth+locale+scope) is resolved once — build-wide during a generate run
   // (memoDuringPrerender), request-/publish-run-wide via the resolve scope (which also budgets the
   // distinct fan-out of one live request and replays read-tags on hits, so publish deps stay complete).
   // memoResolver OUTERMOST: the per-scope budget verdict must stay scope-local. If memoDuringPrerender
   // wrapped memoResolver, a build-wide memoize would cache a budget-skip `null` and poison every later
   // page of a `nuxt generate`. With this order the build-wide memo only ever caches REAL resolver results.
-  const key = (collection: string, id: number, depth: number, locale: string) => `rel:${collection}:${id}:${depth}:${locale}`
+  // `publicOnly` is part of the key because the same record populates DIFFERENTLY under it (its own
+  // non-public relations are withheld) — sharing one entry would serve one scope's record to the other.
+  const key = (collection: string, id: number, depth: number, locale: string, publicOnly: boolean) => `rel:${collection}:${id}:${depth}:${locale}:${publicOnly}`
   const resolve = memoResolver(memoDuringPrerender(resolveRecord, key), key)
   return (bag, key, field, ctx, keyMode) => {
     if (!fieldIs(field, 'relation')) return
     const collection = field.relation.collection
+    const publicOnly = ctx.publicOnly === true
+    if (publicOnly && !isPublicCollection(collection)) return
     const depth = ctx.depth - 1
     if (field.relation.many) {
       const ids = bag[key]
       if (Array.isArray(ids)) {
         bag['$' + key] = ids
           .filter((n): n is number => typeof n === 'number')
-          .map((id) => resolve(collection, id, depth, ctx.locale))
+          .map((id) => resolve(collection, id, depth, ctx.locale, publicOnly))
           .filter((r): r is Record<string, unknown> => r != null)
       }
     } else {
       const id = bag[keyMode === 'columns' ? `${key}Id` : key]
-      if (typeof id === 'number') bag['$' + key] = resolve(collection, id, depth, ctx.locale)
+      if (typeof id === 'number') bag['$' + key] = resolve(collection, id, depth, ctx.locale, publicOnly)
     }
   }
 }

package/layers/core/server/api/[collection]/[id].get.ts

@@ -4,5 +4,8 @@ export default defineEventHandler((event) => {
   const depth = Number(query.depth ?? 0)
   const locale = query.locale as string | undefined
   const publishedOnly = publishedOnlyForScope(event.context.readScope)
-  return getOne(useDb(), collection, requireId(event), depth, locale, publishedOnly)
+  // See index.get.ts: the public-set restriction follows the ROLE, so the renderer keeps full population;
+  // a missing principal fails closed onto it.
+  const publicOnly = (event.context.principal?.role ?? 'anonymous') === 'anonymous'
+  return getOne(useDb(), collection, requireId(event), depth, locale, publishedOnly, publicOnly)
 })

package/layers/core/server/api/[collection]/index.get.ts

@@ -3,9 +3,14 @@ export default defineEventHandler((event) => {
   const query = getQuery(event)
   const db = useDb()
   const publishedOnly = publishedOnlyForScope(event.context.readScope)
+  // Keyed on the ROLE, not the read scope: the renderer reads published-only too, but it produces the
+  // static site and must still see every relation the output embeds. Only a visitor the guard scopes to
+  // the public collection set is barred from reaching further through a populated relation. Fail-CLOSED
+  // on a missing principal, like `publishedOnlyForScope` above — an absent one is a guard regression.
+  const publicOnly = (event.context.principal?.role ?? 'anonymous') === 'anonymous'
 
   if (collection.def.mode === 'single') {
-    return getSingleton(db, collection, query.locale as string | undefined, publishedOnly, query.depth ? Number(query.depth) : 0)
+    return getSingleton(db, collection, query.locale as string | undefined, publishedOnly, query.depth ? Number(query.depth) : 0, publicOnly)
   }
 
   return list(db, collection, {
@@ -15,5 +20,5 @@ export default defineEventHandler((event) => {
     perPage: query.perPage ? Number(query.perPage) : undefined,
     filter: parseFilter(query as Record<string, unknown>),
     depth: query.depth ? Number(query.depth) : 0,
-  }, publishedOnly)
+  }, publishedOnly, publicOnly)
 })

package/layers/core/server/api/[collection]/populate-scope.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { createError } from 'h3'
+import Database from 'better-sqlite3'
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import { buildCollection } from '../../../../fields/server/utils/buildCollection'
+import { defineCollection } from '../../utils/defineCollection'
+import { create, getOne, getSingleton, list, parseFilter, putSingleton } from '../../utils/crud'
+import { requireCollection, requireId } from '../../utils/http'
+import { clearRegistry, registerCollection } from '../../utils/registry'
+import { clearPopulator, registerPopulator, type PopulateCtx } from '../../utils/populate'
+import { desiredSchema } from '../../schema/desired'
+import { diffSchema } from '../../schema/diff'
+import { renderSqlite } from '../../schema/render-sqlite'
+
+const posts = buildCollection(defineCollection({
+  name: 'posts', mode: 'multi', translatable: false,
+  fields: { title: { type: 'text', required: true } },
+}))
+const settings = buildCollection(defineCollection({
+  name: 'settings', mode: 'single', translatable: false,
+  fields: { siteName: { type: 'text' } },
+}))
+
+interface FakeEvent {
+  query: Record<string, unknown>
+  context: { params: Record<string, string>; readScope?: string; principal?: { userId: string | null; role: string } }
+}
+
+let db: ReturnType<typeof drizzle>
+const seen: PopulateCtx[] = []
+
+// The handlers are Nitro routes: their auto-imported helpers are plain globals in a node test. Every read
+// entry point is the REAL one, so this exercises the actual crud → populate threading.
+Object.assign(globalThis, {
+  defineEventHandler: (handler: unknown) => handler,
+  createError,
+  getQuery: (event: FakeEvent) => event.query,
+  useDb: () => db,
+  requireCollection,
+  requireId,
+  list,
+  getOne,
+  getSingleton,
+  parseFilter,
+  // Published-only for EVERY role, so a flag that tracked the read scope instead of the role would be
+  // indistinguishable here — the renderer/admin cases below would then fail.
+  publishedOnlyForScope: () => true,
+})
+
+const listHandler = (await import('./index.get')).default as unknown as (event: FakeEvent) => unknown
+const detailHandler = (await import('./[id].get')).default as unknown as (event: FakeEvent) => unknown
+
+let postId: number
+
+beforeEach(() => {
+  clearRegistry()
+  clearPopulator()
+  seen.length = 0
+  const sqlite = new Database(':memory:')
+  for (const stmt of renderSqlite(diffSchema(desiredSchema([posts.table, settings.table]), {}))) sqlite.exec(stmt)
+  db = drizzle(sqlite)
+  registerCollection(posts)
+  registerCollection(settings)
+  postId = (create(db, posts, { title: 'A' }) as Record<string, unknown>).id as number
+  putSingleton(db, settings, undefined, { siteName: 'Kestrel' })
+  registerPopulator((row, ctx) => { seen.push(ctx); return row })
+})
+afterEach(() => {
+  clearRegistry()
+  clearPopulator()
+})
+
+const eventFor = (collection: string, role: string | undefined, params: Record<string, string> = {}): FakeEvent => ({
+  query: { depth: 1 },
+  context: {
+    params: { collection, ...params },
+    readScope: 'published',
+    principal: role ? { userId: null, role } : undefined,
+  },
+})
+
+describe('read routes — public-only populate scope', () => {
+  it('marks an anonymous list read public-only', () => {
+    listHandler(eventFor('posts', 'anonymous'))
+    expect(seen[0]?.publicOnly).toBe(true)
+  })
+
+  it('marks an anonymous detail read public-only', () => {
+    detailHandler(eventFor('posts', 'anonymous', { id: String(postId) }))
+    expect(seen[0]?.publicOnly).toBe(true)
+  })
+
+  it('marks an anonymous singleton read public-only', () => {
+    listHandler(eventFor('settings', 'anonymous'))
+    expect(seen[0]?.publicOnly).toBe(true)
+  })
+
+  // The renderer produces the static site: stripping its relation sidecars would silently empty the
+  // generated HTML, so its read stays unrestricted even though it too is published-only.
+  it('leaves a renderer read unrestricted', () => {
+    listHandler(eventFor('posts', 'renderer'))
+    detailHandler(eventFor('posts', 'renderer', { id: String(postId) }))
+    expect(seen.map((c) => c.publicOnly)).toEqual([false, false])
+  })
+
+  it('leaves an admin read unrestricted', () => {
+    listHandler(eventFor('posts', 'admin'))
+    detailHandler(eventFor('posts', 'admin', { id: String(postId) }))
+    expect(seen.map((c) => c.publicOnly)).toEqual([false, false])
+  })
+
+  // A principal-less request is a guard regression, never a trusted caller — it must fail the same
+  // direction as the `publishedOnly` flag the handler derives beside it.
+  it('treats a missing principal as public-only', () => {
+    listHandler(eventFor('posts', undefined))
+    detailHandler(eventFor('posts', undefined, { id: String(postId) }))
+    expect(seen.map((c) => c.publicOnly)).toEqual([true, true])
+  })
+})

package/layers/core/server/api/references/broken.get.ts

@@ -1,3 +1,9 @@
 // Every reference in the index whose target is currently deleted or unpublished — the global broken-
 // references report. Admin-only (the `references` resource is not in the public set). Derived on read.
-export default defineEventHandler(() => findBrokenRefs(useDb()) ?? [])
+// A `null` scan means the index itself could not be read (e.g. record_refs not migrated yet); answering
+// `[]` there would report a verified-clean site when nothing was actually checked.
+export default defineEventHandler(() => {
+  const rows = findBrokenRefs(useDb())
+  if (rows === null) throw createError({ statusCode: 503, statusMessage: 'Reference index unavailable' })
+  return rows
+})

package/layers/core/server/schema/dialect.ts

@@ -7,9 +7,11 @@ import { renderSqlite } from './render-sqlite'
 // `SchemaOp[]` over the normalized model, independent of any database. A `Dialect` is what binds that
 // core to a concrete backend — it knows how to read the backend's live schema back into the model
 // (`introspect`), how to turn ops into the backend's DDL (`render`), and how to quote an identifier.
-// `sync.ts` is threaded with a Dialect (defaulting to `sqlite`), so adding a second backend means writing
-// one new Dialect — not touching diff/sync. SQLite is the only implementation today; `postgres` is a
-// reserved, fail-loud slot.
+// `sync.ts` is threaded with a Dialect (defaulting to `sqlite`), so DDL rendering, introspection and
+// identifier quoting are swappable without touching the diff. The seam stops there: `diff.ts` emits
+// `rebuild_table` because SQLite has no ALTER/DROP COLUMN, and sync's pre-flight feasibility probes are
+// SQLite SQL (`PRAGMA table_info`, `json_extract`) — a second backend needs both adjusted alongside its
+// new Dialect. SQLite is the only implementation today; `postgres` is a reserved, fail-loud slot.
 export interface Dialect {
   /** Stable identifier, e.g. `sqlite` | `postgres`. */
   readonly name: string

package/layers/core/server/schema/introspect.ts

@@ -1,8 +1,9 @@
 import type { ColumnShape, IndexShape, TableShape, SchemaSnapshot } from './model'
 
 // Read the *actual* schema of a live SQLite database into the normalized model, so `diffSchema` can
-// compare it against the desired schema (ADR-0002). Typed structurally (prepare + pragma) so it accepts
-// any better-sqlite3 connection without importing the native module here.
+// compare it against the desired schema (ADR-0002). Typed structurally (prepare + pragma) to keep the
+// native module out of this file — but the shape is narrower than better-sqlite3's own (which types
+// `pragma` as returning `unknown`), so a real connection only reaches these entry points through a cast.
 
 interface Row { [key: string]: unknown }
 export interface IntrospectDb {

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

@@ -123,7 +123,7 @@ function filterKindMap(c: BuiltCollection): Record<string, FilterKind> {
   return map
 }
 
-export function list(db: DB, c: BuiltCollection, q: ListQuery, publishedOnly = false) {
+export function list(db: DB, c: BuiltCollection, q: ListQuery, publishedOnly = false, publicOnly = false) {
   const cols = columns(c)
   // A listing depends on the whole collection (any add/remove/edit changes it) — tag it collection-level.
   if (q.capture !== false) captureRead(c.def.name)
@@ -187,7 +187,7 @@ export function list(db: DB, c: BuiltCollection, q: ListQuery, publishedOnly = f
   // fan-out is budgeted — an anonymous `?depth=10&perPage=500` read can no longer multiply into an
   // unbounded number of synchronous DB reads (each blocks the single event-loop thread).
   const data = withResolveScope(
-    () => rawData.map((r) => populateRow(r as Record<string, unknown>, { depth, locale: populateLocale, def: c.def })),
+    () => rawData.map((r) => populateRow(r as Record<string, unknown>, { depth, locale: populateLocale, def: c.def, publicOnly })),
     resolveBudgetFor(perPage), // scale the ceiling with the page size so a full legitimate page always populates
     `list ${c.def.name}`,
   ) as Row[]
@@ -258,7 +258,7 @@ function attachTranslationStatus(db: DB, c: BuiltCollection, rows: Row[], publis
   }
 }
 
-export function getOne(db: DB, c: BuiltCollection, id: number, depth = 0, locale?: string, publishedOnly = false): Row {
+export function getOne(db: DB, c: BuiltCollection, id: number, depth = 0, locale?: string, publishedOnly = false, publicOnly = false): Row {
   captureRead(c.def.name, id) // a detail read depends on exactly this record
   const cols = columns(c)
   const row = db.select().from(table(c)).where(eq(cols.id, id)).get() as Row | undefined
@@ -270,7 +270,7 @@ export function getOne(db: DB, c: BuiltCollection, id: number, depth = 0, locale
   const loc = c.def.translatable ? resolveLocale(locale) : primaryLocale()
   // Nested reads (the relation populator's recursive getOne) reuse the enclosing request's scope.
   return withResolveScope(
-    () => populateRow(row as Record<string, unknown>, { depth: safeDepth, locale: loc, def: c.def }),
+    () => populateRow(row as Record<string, unknown>, { depth: safeDepth, locale: loc, def: c.def, publicOnly }),
     resolveBudgetFor(1),
     `get ${c.def.name}:${id}`,
   ) as Row
@@ -516,7 +516,7 @@ export function resolveTranslations(db: DB, c: BuiltCollection, id: number): Rec
   return result
 }
 
-export function getSingleton(db: DB, c: BuiltCollection, locale?: string, publishedOnly = false, depth = 0): Row | null {
+export function getSingleton(db: DB, c: BuiltCollection, locale?: string, publishedOnly = false, depth = 0, publicOnly = false): Row | null {
   captureRead(c.def.name) // a singleton (nav/settings/footer) is global — any page that reads it depends on it
   const cols = columns(c)
   const loc = c.def.translatable ? resolveLocale(locale) : primaryLocale()
@@ -527,7 +527,7 @@ export function getSingleton(db: DB, c: BuiltCollection, locale?: string, publis
   // Populate like list()/getOne() so a singleton's media/relation/link fields resolve at depth > 0 — the
   // canonical settings-singleton (site logo, nav link repeater) relies on this exactly as any collection does.
   return withResolveScope(
-    () => populateRow(row as Record<string, unknown>, { depth: clampDepth(depth), locale: loc, def: c.def }),
+    () => populateRow(row as Record<string, unknown>, { depth: clampDepth(depth), locale: loc, def: c.def, publicOnly }),
     resolveBudgetFor(1),
     `singleton ${c.def.name}`,
   ) as Row

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

@@ -6,7 +6,8 @@ import { resolve } from 'node:path'
 /**
  * Non-secret S3 settings (used when `media.driver === 's3'`). The access-key id and secret are
  * deliberately **absent** here — they are env-only (`KESTREL_S3_ACCESS_KEY_ID` /
- * `KESTREL_S3_SECRET_ACCESS_KEY`), read at driver construction, never in committed config.
+ * `KESTREL_S3_SECRET_ACCESS_KEY`), read at module setup — unconditionally, whatever the driver — and
+ * frozen into `runtimeConfig`, never in committed config.
  */
 export interface KestrelS3Config {
   /** Target bucket name. */
@@ -122,8 +123,7 @@ export interface KestrelConfig {
     publicDir?: string
     /** Auto-publish affected pages on every content write (default true). */
     auto?: boolean
-    /** Run a FULL reconcile every N minutes (default 0 = off) — self-heals missed invalidations and
-     *  picks up time-based `publishDate` publishing that no write event would trigger. */
+    /** Run a FULL reconcile every N minutes (default 0 = off) — self-heals a missed invalidation. */
     reconcileMinutes?: number
     /** Verbose publish logging: emit a timestamped per-route line (rendered / pruned) on each incremental
      *  republish, on top of the summary line. Default false (`KESTREL_OUTPUT_VERBOSE`). */

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

@@ -1,6 +1,8 @@
 import type { CollectionDef, FieldDef } from './defineCollection'
 
-export interface PopulateCtx { depth: number; locale: string; def: CollectionDef }
+/** `publicOnly`: the read is served to a principal that may only reach the public collection set, so a
+ *  populator must not expand a reference into a collection the guard would have refused it directly. */
+export interface PopulateCtx { depth: number; locale: string; def: CollectionDef; publicOnly?: boolean }
 export type Populator = (row: Record<string, unknown>, ctx: PopulateCtx) => Record<string, unknown>
 
 // A composed list: each registered populator runs in turn over the row (e.g. media attaches `$media`,

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

@@ -5,7 +5,7 @@ import type { StorageDriver } from '../../../core/server/utils/storage'
 import { media } from '../collections/media'
 import { deriveImage, RASTER } from './derive'
 import { derivativeKey, type DerivativeManifest } from './record'
-import { activeVariants } from './variants'
+import { readVariantRegistry, resolveActiveVariants } from './variants'
 import { withLock, mediaLockKey } from '../../../core/server/utils/key-lock'
 import { emitMediaWrite } from './media-write'
 
@@ -16,7 +16,8 @@ const MEDIA_CACHE_CONTROL = 'public, max-age=31536000'
 export interface BackfillPlan {
   /** Specs, each carrying ONLY its missing formats, to derive + add. */
   missing: ResolvedVariant[]
-  /** Object keys of manifest entries no longer in the active set (deregistered) — to prune. */
+  /** Object keys of manifest entries no longer in the active set (deregistered) — to prune. Always empty
+   *  when the caller passes `prune: false`, i.e. the active set is a fallback rather than the registry. */
   orphanKeys: string[]
 }
 
@@ -26,7 +27,9 @@ export interface BackfillPlan {
  * never be satisfied). Orphans are keyed per `<name>.<format>`, so a deregistered FORMAT of a still-active
  * name is pruned too.
  */
-export function planBackfill(row: { width: number | null; derivatives: DerivativeManifest | null }, specs: ResolvedVariant[]): BackfillPlan {
+export function planBackfill(
+  row: { width: number | null; derivatives: DerivativeManifest | null }, specs: ResolvedVariant[], prune = true,
+): BackfillPlan {
   const manifest = row.derivatives ?? {}
   const activeKeys = new Set<string>()
   const missing: ResolvedVariant[] = []
@@ -40,7 +43,7 @@ export function planBackfill(row: { width: number | null; derivatives: Derivativ
     if (missingFormats.length) missing.push({ ...spec, formats: missingFormats })
   }
   const orphanKeys: string[] = []
-  for (const [k, entry] of Object.entries(manifest)) if (!activeKeys.has(k) && entry.key) orphanKeys.push(entry.key)
+  if (prune) for (const [k, entry] of Object.entries(manifest)) if (!activeKeys.has(k) && entry.key) orphanKeys.push(entry.key)
   return { missing, orphanKeys }
 }
 
@@ -53,9 +56,9 @@ interface BackfillRow { id: number; storageKey: string; mime: string; width: num
  * (that is Slice 9's published-media GC, a different concern).
  */
 export async function backfillRow(
-  db: BetterSQLite3Database, driver: StorageDriver, row: BackfillRow, specs: ResolvedVariant[], policy: ResolvedImagePolicy,
+  db: BetterSQLite3Database, driver: StorageDriver, row: BackfillRow, specs: ResolvedVariant[], policy: ResolvedImagePolicy, prune = true,
 ): Promise<{ generated: number; pruned: number }> {
-  const plan = planBackfill(row, specs)
+  const plan = planBackfill(row, specs, prune)
   if (!plan.missing.length && !plan.orphanKeys.length) return { generated: 0, pruned: 0 }
 
   const orphaned = new Set(plan.orphanKeys)
@@ -84,7 +87,12 @@ export async function backfillRow(
   return { generated, pruned: plan.orphanKeys.length }
 }
 
-export interface BackfillReport { rows: number; rowsChanged: number; generated: number; pruned: number; check: boolean }
+export interface BackfillReport {
+  rows: number; rowsChanged: number; generated: number; pruned: number; check: boolean
+  /** The run declined to prune because the active set is the config fallback, not the registry — so a
+   *  `pruned: 0` here means "could not tell what is registered", not "nothing was deregistered". */
+  pruneWithheld: boolean
+}
 
 /**
  * Iterate every raster media row, reconciling each to the active variant set. Sequential (sharp CPU + a
@@ -94,14 +102,18 @@ export interface BackfillReport { rows: number; rowsChanged: number; generated:
 export async function runBackfill(
   db: BetterSQLite3Database, driver: StorageDriver, policy: ResolvedImagePolicy, opts: { check?: boolean } = {},
 ): Promise<BackfillReport> {
-  const specs = activeVariants(db, policy.variants, policy.presets)
+  // Deriving a superset is harmless, deleting against one is not, so the prune follows the resolver's own
+  // verdict: an unmigrated, unreadable, empty or wholly-rejected registry resolves to the CONFIG fallback,
+  // under which every registered variant of every row looks deregistered.
+  const { specs, fromRegistry: prune } = resolveActiveVariants(readVariantRegistry(db), policy.variants, policy.presets)
+  if (!prune) console.warn('[kestrel] backfill: no usable variant registry — generating against the config fallback and withholding the prune. Run a full publish so the prerender scan populates media_settings.')
   const rows = db.select().from(media).all() as BackfillRow[]
-  const report: BackfillReport = { rows: rows.length, rowsChanged: 0, generated: 0, pruned: 0, check: !!opts.check }
+  const report: BackfillReport = { rows: rows.length, rowsChanged: 0, generated: 0, pruned: 0, check: !!opts.check, pruneWithheld: !prune }
   for (const snapshot of rows) {
     if (!RASTER.has(snapshot.mime)) continue
     if (opts.check) {
       // Dry-run reads only (against the snapshot) — no mutation, so no lock.
-      const plan = planBackfill(snapshot, specs)
+      const plan = planBackfill(snapshot, specs, prune)
       const toGenerate = plan.missing.reduce((n, s) => n + s.formats.length, 0)
       if (!toGenerate && !plan.orphanKeys.length) continue
       report.rowsChanged++
@@ -116,11 +128,11 @@ export async function runBackfill(
       const cols = getTableColumns(media) as Record<string, never>
       const row = db.select().from(media).where(eq(cols.id, snapshot.id)).get() as BackfillRow | undefined
       if (!row || !RASTER.has(row.mime)) return
-      const plan = planBackfill(row, specs)
+      const plan = planBackfill(row, specs, prune)
       if (!plan.missing.length && !plan.orphanKeys.length) return
       report.rowsChanged++
       try {
-        const r = await backfillRow(db, driver, row, specs, policy)
+        const r = await backfillRow(db, driver, row, specs, policy, prune)
         report.generated += r.generated
         report.pruned += r.pruned
       } catch (error) {

package/layers/media/server/utils/variants.ts

@@ -28,11 +28,16 @@ const rank = (v: StoredVariant): number => (v.pinned || v.source === 'manual' ?
  * config policy variants) when the registry is empty/absent. `presets` are config-authored named variants
  * (`image.variants`): explicit, name-referenced declarations that are never scan-discovered, so they stay
  * active through usage-driven narrowing (unioned into a non-empty registry, winning any name collision).
+ *
+ * `fromRegistry` is the verdict a DELETING caller (the backfill prune) must gate on: true only when at least
+ * one stored entry SURVIVED validation, so the set really is the registered one. Absent, unread, empty and
+ * wholly-rejected registries all resolve to the same superset fallback, under which every registered
+ * derivative looks deregistered — the row count alone cannot tell those apart from a narrowed set.
  * Pure — the load-bearing logic, unit-tested without a DB.
  */
 export function resolveActiveVariants(
   stored: StoredVariant[] | null | undefined, fallback: ResolvedVariant[], presets: ResolvedVariant[] = [],
-): ResolvedVariant[] {
+): { specs: ResolvedVariant[]; fromRegistry: boolean } {
   // A registry row is hand-authorable via the media_settings JSON PATCH; reject a name outside the
   // derivative-key charset ([A-Za-z0-9_-]) — an out-of-charset char breaks the URL / the prune-media
   // referencedKeys regex (its derivative is pruned though pages reference it) and a `/` nests a pseudo-folder.
@@ -41,7 +46,7 @@ export function resolveActiveVariants(
     (v): v is StoredVariant => !!v && safeName(v.name) && Number.isFinite(v.width) && v.width >= 1,
   )
   // Empty registry ⇒ the fallback already contains the presets (resolveVariants unions them), so return it as-is.
-  if (!list.length) return fallback
+  if (!list.length) return { specs: fallback, fromRegistry: false }
   const byName = new Map<string, StoredVariant>()
   for (const v of list) {
     const prev = byName.get(v.name)
@@ -50,7 +55,7 @@ export function resolveActiveVariants(
   for (const p of presets) {
     if (p && typeof p.name === 'string' && p.name !== '' && Number.isFinite(p.width) && p.width >= 1) byName.set(p.name, { ...p, source: 'manual' })
   }
-  return [...byName.values()].map((v): ResolvedVariant => ({
+  const specs = [...byName.values()].map((v): ResolvedVariant => ({
     name: v.name,
     width: Math.floor(v.width),
     // coerce a garbage/stale height to null so it never reaches sharp's crop resize and 500s the upload
@@ -62,6 +67,7 @@ export function resolveActiveVariants(
     position: typeof v.position === 'string' && SHARP_POSITIONS.has(v.position) ? v.position : 'centre',
     formats: v.formats?.length ? v.formats : ['webp'],
   }))
+  return { specs, fromRegistry: true }
 }
 
 /**
@@ -87,12 +93,12 @@ export function reconcileVariants(existing: StoredVariant[], discovered: Resolve
 }
 
 /**
- * Read the persisted variant registry (the `media_settings` singleton) and resolve the active set,
- * falling back to `fallback` (the resolved config policy variants) when nothing is stored yet. `presets`
- * (config-authored named variants) stay active regardless of the stored set. The upload path calls this
- * so it derives exactly the currently-registered set + presets (narrow generation).
+ * The raw stored registry rows (the `media_settings` singleton), or `null` when there are none to resolve
+ * from — the read threw (media_settings not migrated) or nothing is stored. Whether the resolved set may be
+ * DELETED against is not decidable here: that is `resolveActiveVariants`' `fromRegistry` verdict, which only
+ * a validation pass over these rows can give.
  */
-export function activeVariants(db: BetterSQLite3Database, fallback: ResolvedVariant[], presets: ResolvedVariant[] = []): ResolvedVariant[] {
+export function readVariantRegistry(db: BetterSQLite3Database): StoredVariant[] | null {
   const cols = getTableColumns(mediaSettings) as Record<string, never>
   let row: { variants?: StoredVariant[] | null } | undefined
   try {
@@ -100,9 +106,18 @@ export function activeVariants(db: BetterSQLite3Database, fallback: ResolvedVari
       | { variants?: StoredVariant[] | null }
       | undefined
   } catch {
-    // media_settings not migrated yet (a DB provisioned by committed migrations alone) — degrade to the
-    // config fallback rather than 500 the upload. Mirrors attachDeadRefs tolerating a missing record_refs.
-    row = undefined
+    return null
   }
-  return resolveActiveVariants(row?.variants ?? null, fallback, presets)
+  const stored = row?.variants
+  return Array.isArray(stored) ? stored : null
+}
+
+/**
+ * Resolves the active variant set for the upload path (narrow generation: registered set + presets).
+ * Deliberately forgiving: an unreadable registry degrades to the config fallback rather than 500 the
+ * upload (mirrors attachDeadRefs tolerating a missing record_refs). Discards `fromRegistry` — never use
+ * this to decide what may be pruned; a deleting caller needs `resolveActiveVariants` directly.
+ */
+export function activeVariants(db: BetterSQLite3Database, fallback: ResolvedVariant[], presets: ResolvedVariant[] = []): ResolvedVariant[] {
+  return resolveActiveVariants(readVariantRegistry(db), fallback, presets).specs
 }

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

@@ -35,7 +35,7 @@ const { locale, path } = resolvePublicRoute(route.path.split('/').filter(Boolean
 // `/api/route` and a draft renders at its real URL (the live preview); anonymous + the static render
 // stay published-only (the handler enforces it).
 const requestFetch = useRequestFetch()
-const { data: resolved } = await useAsyncData(`page:${locale}:${path}`, () =>
+const { data: resolved, error: resolveError } = await useAsyncData(`page:${locale}:${path}`, () =>
   requestFetch('/api/route', {
     query: { path, locale },
   }).then((r) => r as {
@@ -79,6 +79,13 @@ const { data: previewSession } = previewRequested
   : { data: ref<{ authenticated: boolean } | null>(null) }
 const previewActive = computed(() => previewRequested && previewSession.value?.authenticated === true)
 
+// `useAsyncData` resolves even when the fetch threw, so the resolver's own failure has to be re-raised here
+// or the root's empty document (a 200 WITH a body) reads as a successful render and the publisher bakes it
+// over the live page. Unconditional on purpose, not just for `/`: on any other path the failure would fall
+// through to the 404 below, which asserts "no such page" from a lookup that never completed — a claim
+// crawlers and caches act on, and one the publisher files as a skip instead of the error the editor shows.
+if (resolveError.value) throw resolveError.value
+
 // The site root stays reachable (empty document) before a home page is published;
 // any other unmatched path is a genuine 404.
 if (!page.value && path !== '/') throw createError({ statusCode: 404, statusMessage: 'Page not found' })

package/layers/public/server/api/route.get.ts

@@ -14,13 +14,33 @@ export default defineEventHandler((event) => {
   const isStaticRender = import.meta.prerender === true || isRendererContext()
   const publishedOnly = isStaticRender || event.context.readScope !== 'all'
   const db = useDb()
-  const resolved = resolvePage(db, allCollections(), path, locale, publishedOnly)
+  const { page: resolved, failed } = resolvePage(db, allCollections(), path, locale, publishedOnly)
   // The site-wide head tier rides along on the fetch the page already awaits, so it reaches SSR and the
-  // prerender on a path that is known to work. Looked up through the registry, not imported, so a consumer
-  // that disables the collection gets `null` instead of a query against a table the schema never created.
-  // `depth: 1` resolves the sharing image into `$media`; `getSingleton` captures the read, so an edit
-  // re-publishes every route that embedded it.
+  // prerender on a path that is known to work. Looked up through the registry, not imported, so an
+  // installation whose registry never received the built-in simply has the tier off (`null`) instead of
+  // querying a table the schema never created. `depth: 1` resolves the sharing image into `$media`;
+  // `getSingleton` captures the read, so an edit re-publishes every route that embedded it.
   const siteCollection = getCollection('site')
-  const site = siteCollection ? getSingleton(db, siteCollection, locale, false, 1) : null
+  let site: ReturnType<typeof getSingleton> = null
+  let siteUnreadable = false
+  if (siteCollection) {
+    try { site = getSingleton(db, siteCollection, locale, false, 1) }
+    catch (error) {
+      // Registered but unreadable (its migration hasn't been run) — indistinguishable in the response from
+      // the off state above, so it joins the incomplete-read channel rather than degrading silently.
+      siteUnreadable = true
+      console.error('[kestrel] route: the site singleton could not be read:', (error as Error)?.message ?? error)
+    }
+  }
+  // One rule for every incomplete read: never answer 200. The publisher classifies a 200-with-body as a
+  // successful render, writes it over the live file and records success — so an unreadable page collection
+  // would bake the catch-all's empty document over a real page (the record may well live in the collection
+  // that failed, which is why this is not a 404), and an unreadable head tier would strip the composed
+  // title, default description and sharing image from every route it touches. Both are unrecoverable
+  // without a full re-publish and neither leaves a mark. A 5xx keeps the existing artifact and turns the
+  // editor's status red. The head tier is site-wide, so it fails the request even when a page did resolve.
+  if (siteUnreadable || (failed.length && !resolved)) {
+    throw createError({ statusCode: 503, statusMessage: 'Route lookup incomplete' })
+  }
   return { collection: resolved?.collection ?? null, page: resolved?.page ?? null, alternates: resolved?.alternates ?? [], site }
 })

package/layers/public/server/plugins/02.register-links.ts

@@ -3,10 +3,10 @@ import { buildLinkFieldPopulators } from '../utils/populate-links'
 import { resolveInternalHref } from '../utils/link-resolve'
 
 // Resolve internal links to the target record's localized public path at read time (page-like targets;
-// external/email/tel pass through). NOTE: the resolver does NOT status-gate the target — a link to a DRAFT
-// emits the draft's real (not-yet-generated) path, disclosing its slug and shipping a 404 until publish. This
-// is deliberate: it keeps links stable without re-rendering every referrer when a target's status flips, and
-// the editor warns about draft/dead links instead. (See link-resolve.ts for the rationale.)
+// external/email/tel pass through). The resolver IS status-gated: a link to a DRAFT resolves to nothing and
+// bakes `'#'`, so an unpublished slug never reaches published HTML. The href therefore encodes availability,
+// which is why flipping a target's status re-renders its referrers; the editor warns about the resulting
+// draft/dead links separately. (See link-resolve.ts.)
 //
 // Registered as `link` + `richtext` per-type populators; the shared field-tree walker dispatches them over
 // top-level fields, block props, slots, and repeater entries.

package/layers/public/server/plugins/zz.publish.ts

@@ -15,7 +15,7 @@ import { registerWriteListener } from '../../../core/server/utils/write-events'
  *     DETACHED (`runNitroPlugins` is synchronous + unawaited; `localFetch` is already wired before plugins
  *     run + before the server listens), so it never blocks boot.
  *  3. RECONCILER — an optional periodic full publish (`output.reconcileMinutes`) self-heals any missed
- *     invalidation and picks up time-based `publishDate` publishing that no write event would trigger.
+ *     invalidation.
  */
 export default defineNitroPlugin(() => {
   if (import.meta.dev) return

package/layers/public/server/routes/llms.txt.get.ts

@@ -44,8 +44,11 @@ export default defineEventHandler((event) => {
     let rows: Record<string, unknown>[]
     try {
       rows = db.select(proj as never).from(c.table).all() as Record<string, unknown>[]
-    } catch {
-      continue // table not migrated yet (e.g. a bare prerender DB)
+    } catch (error) {
+      // Skipping keeps a bare prerender DB publishable, but a drifted table drops the whole section — a
+      // silent gap the publisher would write straight over the live artifact.
+      console.error(`[kestrel] llms.txt: skipped collection ${c.def.name}:`, (error as Error)?.message ?? error)
+      continue
     }
     const entries: LlmsEntry[] = []
     for (const row of rows) {

package/layers/public/server/routes/sitemap.xml.get.ts

@@ -39,8 +39,11 @@ export default defineEventHandler((event) => {
     let rows: Record<string, unknown>[]
     try {
       rows = db.select(proj as never).from(c.table).all() as Record<string, unknown>[]
-    } catch {
-      continue // table not migrated yet (e.g. a bare prerender DB)
+    } catch (error) {
+      // Skipping keeps a bare prerender DB publishable, but a drifted table de-indexes every page of the
+      // collection — a silent gap the publisher would write straight over the live sitemap.
+      console.error(`[kestrel] sitemap.xml: skipped collection ${c.def.name}:`, (error as Error)?.message ?? error)
+      continue
     }
     for (const row of rows) {
       if (c.def.status && row.status !== 'published') continue

package/layers/public/server/utils/link-resolve.ts

@@ -27,8 +27,11 @@ export function resolveInternalHref(collection: string, id: number, db = useDb()
   let row: Record<string, unknown> | undefined
   try {
     row = db.select().from(c.table).where(eq(cols.id, id)).get() as Record<string, unknown> | undefined
-  } catch {
-    return null // table not migrated yet (e.g. a bare prerender DB)
+  } catch (error) {
+    // Still null (a throw would 500 every page holding an internal link on a bare prerender DB), but the
+    // memo caches that null run-wide as "not linkable", so the dead link needs a trace to be diagnosable.
+    console.error(`[kestrel] resolveInternalHref: ${collection}:${id} unreadable:`, (error as Error)?.message ?? error)
+    return null
   }
   if (!isPubliclyLinkable(row, Object.hasOwn(cols, 'status'))) return null
   return pageRowHref(row, primaryLocale(), prefixPrimaryLocale())

package/layers/public/server/utils/page-resolve.ts

@@ -1,12 +1,20 @@
 import { asc, eq, getTableColumns } from 'drizzle-orm'
 import { list } from '../../../core/server/utils/crud'
 import { captureRead } from '../../../core/server/utils/read-capture'
+import { translationGroupTag } from './publish/invalidation'
 import type { BuiltCollection } from '../../../core/server/utils/collection-types'
 import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
 
 export interface PageAlternate { locale: string; path: string }
 export interface ResolvedPage { collection: string; page: Record<string, unknown>; alternates: PageAlternate[] }
 
+/** The matched page (or null) plus the collections whose lookup threw. `failed` is non-empty ⇒ the scan
+ *  was INCOMPLETE, so `page: null` must never be treated as an authoritative "no such page". */
+export interface PageResolution {
+  page: ResolvedPage | null
+  failed: string[]
+}
+
 /**
  * The page's published, INDEXABLE translation siblings (self included) as locale→path pairs — the hreflang
  * set the public head emits. Mirrors the sitemap's rules exactly so the two never disagree: published-only
@@ -14,12 +22,15 @@ export interface ResolvedPage { collection: string; page: Record<string, unknown
  * hreflang to a noindexed page is a conflicting signal), null-path rows skipped, and a single-member group
  * returns [] (hreflang is meaningless for a lone page). EVERY sibling in the group is `captureRead`-tagged,
  * filtered-out ones included, so an incremental publish re-renders every group member when a sibling is
- * renamed/published/unpublished — otherwise a baked page would keep a stale/dead hreflang href.
+ * renamed/published/unpublished — otherwise a baked page would keep a stale/dead hreflang href. The GROUP
+ * itself is tagged too: a sibling that does not exist yet has no id to have been captured, so the group tag
+ * is the only edge a later CREATE can match.
  */
 function publishedAlternates(db: BetterSQLite3Database, c: BuiltCollection, page: Record<string, unknown>): PageAlternate[] {
   if (c.def.mode !== 'multi' || !c.def.translatable) return []
   const group = page.translationGroup
   if (typeof group !== 'string' || !group) return []
+  captureRead(translationGroupTag(c.def.name, group))
   const cols = getTableColumns(c.table) as Record<string, never>
   // A status-less pageLike collection has no draft state — every sibling is "published".
   const hasStatus = Object.hasOwn(cols, 'status')
@@ -54,13 +65,15 @@ function publishedAlternates(db: BetterSQLite3Database, c: BuiltCollection, page
 
 /**
  * The first page-like record (across all collections, in registration order) whose `path` matches,
- * populated at depth 1 — or null. Reuses the access-scoped `list()` so media/links populate exactly as
- * a direct collection read would. `publishedOnly` defaults true: a static render (prerender / runtime
- * publisher) and an anonymous live request must never see drafts. The authenticated-admin live preview
- * passes false to surface a draft at its real URL. Registration order is the precedence rule when two
- * page-like collections happen to share a path.
+ * populated at depth 1 — or null, alongside the collections that could not be read at all. Reuses the
+ * access-scoped `list()` so media/links populate exactly as a direct collection read would.
+ * `publishedOnly` defaults true: a static render (prerender / runtime publisher) and an anonymous live
+ * request must never see drafts. The authenticated-admin live preview passes false to surface a draft at
+ * its real URL. Registration order is the precedence rule when two page-like collections happen to share
+ * a path.
  */
-export function resolvePage(db: BetterSQLite3Database, collections: BuiltCollection[], path: string, locale?: string, publishedOnly = true): ResolvedPage | null {
+export function resolvePage(db: BetterSQLite3Database, collections: BuiltCollection[], path: string, locale?: string, publishedOnly = true): PageResolution {
+  const failed: string[] = []
   for (const c of collections) {
     if (!c.def.pageLike) continue
     // withTotal:false — read only the first row, skip count(). capture:false — don't tag the whole
@@ -73,14 +86,15 @@ export function resolvePage(db: BetterSQLite3Database, collections: BuiltCollect
       // Table not migrated yet (e.g. a bare prerender DB) — isolate this collection's drift from the rest,
       // but never silently: an unread collection is indistinguishable from one with no matching page, and
       // the publisher would write a 404 over every one of its routes.
+      failed.push(c.def.name)
       console.error(`[kestrel] resolvePage: skipped collection ${c.def.name}:`, (error as Error)?.message ?? error)
       continue
     }
     const { data } = result
     if (data.length) {
       captureRead(c.def.name, (data[0] as { id?: number }).id ?? null)
-      return { collection: c.def.name, page: data[0]!, alternates: publishedAlternates(db, c, data[0]!) }
+      return { page: { collection: c.def.name, page: data[0]!, alternates: publishedAlternates(db, c, data[0]!) }, failed }
     }
   }
-  return null
+  return { page: null, failed }
 }

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

@@ -27,6 +27,12 @@ export interface WriteClassification {
   /** The page's own public route from the OLD row (pageLike + had a path), else null — the route whose
    *  static file must be pruned on a slug change / unpublish / delete (symmetric to `selfRoute`). */
   oldRoute: string | null
+  groupTag: string | null
+}
+
+/** The data tag naming a translation group. `#` keeps it clear of the `<coll>:<id>` record namespace. */
+export function translationGroupTag(coll: string, group: string): string {
+  return `${coll}#group:${group}`
 }
 
 /** What to republish for a write. Routes are resolved from `tags` against the captured deps index. */
@@ -71,13 +77,19 @@ export function classifyWrite(def: WriteCollection, before: Row, after: Row, pri
   // change (path unchanged) still moves the route — the old-locale file must be pruned.
   const pathChanged = pageLike && status === 'updated' && oldRoute !== selfRoute
 
-  return { collection: def.name, pageLike, status, id, pathChanged, statusChanged, isPublished, wasPublished, selfRoute, oldRoute }
+  // `update` refuses to move a row between groups, so the surviving row's group is the group either way.
+  const group = row?.translationGroup
+  const groupTag = typeof group === 'string' && group ? translationGroupTag(def.name, group) : null
+
+  return { collection: def.name, pageLike, status, id, pathChanged, statusChanged, isPublished, wasPublished, selfRoute, oldRoute, groupTag }
 }
 
 /**
- * Decide what a write invalidates, per the maintainer-agreed model. Two notions of "dependent":
+ * Decide what a write invalidates, per the maintainer-agreed model. Three notions of "dependent":
  *  - LISTINGS — pages that QUERY the collection (overviews) → captured as the `<coll>` tag.
  *  - EXPLICIT REFERRERS — pages that LINK/EMBED/relate-to a specific record → captured as `<coll>:<id>`.
+ *  - TRANSLATION SIBLINGS — every member of a group bakes the group's hreflang set → captured as the
+ *    group tag, the only edge that reaches members which rendered before this row existed.
  *
  * Two principles drive the split:
  *  1. FRESHENING (content or path changed) re-renders BOTH listings and explicit referrers (`[coll, coll:id]`)
@@ -94,7 +106,10 @@ export function classifyWrite(def: WriteCollection, before: Row, after: Row, pri
 export function planInvalidation(ev: WriteClassification): Invalidation {
   const coll = ev.collection
   const recordTag = ev.id != null ? `${coll}:${ev.id}` : null
-  const tags = recordTag ? [coll, recordTag] : [coll]
+  // Unlike recordTag (dropped on create — no referrer can target a brand-new id), groupTag is included even
+  // there: a new sibling still changes every existing member's hreflang set.
+  const groupTags = ev.groupTag ? [ev.groupTag] : []
+  const tags = recordTag ? [coll, recordTag, ...groupTags] : [coll, ...groupTags]
   const selfRender = ev.pageLike && ev.selfRoute ? [ev.selfRoute] : []
 
   // DELETE — leaves the collection. Listings re-render, referrers too (their baked link/hreflang now points
@@ -108,7 +123,7 @@ export function planInvalidation(ev: WriteClassification): Invalidation {
   // record re-renders listings + its own route. No referrer can point at a brand-new id, so no `coll:id`.
   if (ev.status === 'created') {
     if (!ev.isPublished) return { type: 'noop' }
-    return { type: 'tags', tags: [coll], render: selfRender, prune: [] }
+    return { type: 'tags', tags: [coll, ...groupTags], render: selfRender, prune: [] }
   }
 
   // UNPUBLISH — leaves the published set. Listings re-render; referrers re-render so their link falls back to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michaelthielemann/kestrel",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "A slim, collection-driven Nuxt 4 CMS meta-layer with a runtime schema engine. Add `extends: ['@michaelthielemann/kestrel']`, define collections, and the database migrates itself.",
   "license": "Apache-2.0",
   "author": "Michael Thielemann <283621694+MichaelThielemann@users.noreply.github.com>",
@@ -68,6 +68,9 @@
     "@tiptap/pm": "^3.29.2",
     "@tiptap/starter-kit": "^3.29.2",
     "@tiptap/vue-3": "^3.29.2",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/jsdom": "^28.0.3",
+    "@types/sanitize-html": "^2.16.1",
     "aws4fetch": "^1.0.20",
     "better-sqlite3": "^12.11.1",
     "dompurify": "^3.4.13",
@@ -109,9 +112,6 @@
   "devDependencies": {
     "@nuxt/kit": "^4.5.2",
     "@nuxt/test-utils": "^4.1.0",
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/jsdom": "^28.0.3",
-    "@types/sanitize-html": "^2.16.1",
     "@vitejs/plugin-vue": "^6.0.8",
     "@vue/test-utils": "^2.4.11",
     "drizzle-kit": "^0.31.10",

package/scripts/kestrel.mjs

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readFileSync } from 'node:fs'
 import { join, resolve, basename, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { hashPassword, sessionSecret } from './lib/password.mjs'
-import { PACKAGE_NAME, diagnoseProject, mergeEnv, mergePackageJson, renderTemplate, targetName, toPackageName } from './lib/scaffold.mjs'
+import { PACKAGE_NAME, diagnoseProject, envValue, isPlainObject, mergeEnv, mergePackageJson, renderTemplate, targetName, toPackageName } from './lib/scaffold.mjs'
 import { Cancelled, MIN_PASSWORD_LENGTH, makePaint, out, parseArgs, promptPassword, readIf, readStdin, walk, write } from './lib/cli.mjs'
 
 // Node builtins only, no build step: runs the same from a checkout, from node_modules and via `pnpm dlx`.
@@ -46,18 +46,25 @@ async function init(positional, flags) {
   const templateDir = join(TEMPLATES, 'starter')
   if (!existsSync(templateDir)) fail(`template payload missing at ${templateDir} — reinstall ${PACKAGE_NAME}.`)
 
-  // Validate before touching disk: a half-scaffolded project is worse than a refused one.
+  // Read the target before touching disk: a half-scaffolded project is worse than a refused one.
   const manifestPath = join(target, 'package.json')
   const existingManifest = readIf(manifestPath)
   if (existingManifest !== null) {
+    let parsed
     try {
-      JSON.parse(existingManifest)
+      parsed = JSON.parse(existingManifest)
     } catch {
       fail(`${manifestPath} is not valid JSON — fix it first; refusing to scaffold over a broken manifest.`)
     }
+    if (!isPlainObject(parsed)) fail(`${manifestPath} is not a JSON object — fix it first; refusing to scaffold over a broken manifest.`)
   }
+  const envPath = join(target, '.env')
+  const existingEnv = readIf(envPath)
 
-  let password = typeof flags.password === 'string' ? flags.password : undefined
+  // No flag swallows a `-`-prefixed token, so a dash-leading password reaches init as no value at all.
+  if (flags.password === true) fail('--password needs a value — write --password=<pw> if it starts with a dash.')
+  const supplied = typeof flags.password === 'string'
+  let password = supplied ? flags.password : undefined
   if (password !== undefined && password.length < MIN_PASSWORD_LENGTH) {
     fail(`--password must be at least ${MIN_PASSWORD_LENGTH} characters (an empty one would leave /admin open).`)
   }
@@ -70,13 +77,21 @@ async function init(positional, flags) {
   out()
 
   if (password === undefined && !flags.yes && process.stdin.isTTY) {
-    try {
-      password = await promptPassword({ warn: (m) => out(yellow(m)), note: (m) => out(dim(m)) })
-    } catch (err) {
-      if (err instanceof Cancelled) fail('cancelled')
-      throw err
+    // The prompt loops until a valid password is typed twice, so it cannot be declined, and the hash is
+    // folded into the session signing key — asking on a project that already has one would rotate the
+    // password, and sign everyone out, without ever offering the operator a way to say no.
+    if (envValue(existingEnv ?? '', 'KESTREL_ADMIN_PASSWORD_HASH')) {
+      out(dim('KESTREL_ADMIN_PASSWORD_HASH is already set — pass --password to change it.'))
+      out()
+    } else {
+      try {
+        password = await promptPassword({ warn: (m) => out(yellow(m)), note: (m) => out(dim(m)) })
+      } catch (err) {
+        if (err instanceof Cancelled) fail('cancelled')
+        throw err
+      }
+      out()
     }
-    out()
   }
 
   const vars = templateVars(projectName)
@@ -109,12 +124,14 @@ async function init(positional, flags) {
   }
 
   // Seed from `.env.example` so the generated file keeps its per-key comments.
-  const envPath = join(target, '.env')
-  const hadEnv = existsSync(envPath)
+  const hadEnv = existingEnv !== null
   const envEntries = { KESTREL_SESSION_SECRET: sessionSecret(), KESTREL_SECURE_COOKIES: 'false' }
   if (password !== undefined) envEntries.KESTREL_ADMIN_PASSWORD_HASH = hashPassword(password)
-  const seed = hadEnv ? readFileSync(envPath, 'utf8') : (readIf(join(target, '.env.example')) ?? '')
-  const { text, written } = mergeEnv(seed, envEntries)
+  const seed = existingEnv ?? readIf(join(target, '.env.example')) ?? ''
+  // Only an explicitly supplied password replaces a hash that is already set. That is not session-safety:
+  // the hash is folded into the cookie signing key, so any rotation signs every user out. What keeps a
+  // plain re-run harmless is that it changes neither the hash nor the secret.
+  const { text, written } = mergeEnv(seed, envEntries, supplied ? ['KESTREL_ADMIN_PASSWORD_HASH'] : [])
   if (written.length) {
     write(envPath, text, 0o600)
     ;(hadEnv ? merged : created).push(`.env ${dim(`(${written.join(', ')})`)}`)
@@ -191,7 +208,7 @@ ${bold('kestrel')} ${dim(`v${pkg.version}`)}
 
 ${bold('init flags')}
   --name <name>       package name (default: the directory name, slugified)
-  --password <pw>     set the admin password without prompting
+  --password <pw>     set or change the admin password without prompting
   --yes               never prompt; leaves KESTREL_ADMIN_PASSWORD_HASH for you to fill in
   --force             overwrite existing files (package.json and .env are always merged, never replaced)
 
@@ -199,9 +216,17 @@ ${dim('Existing files are kept and re-running init is safe. To create a NEW proj
 `)
 }
 
-const { flags, positional } = parseArgs(process.argv.slice(2), ['yes', 'force', 'help', 'version'])
+const argv = process.argv.slice(2)
+const { flags, positional } = parseArgs(argv, ['yes', 'force', 'help', 'version'])
 const command = positional.shift()
 
+// Only these two read a positional as a directory, and an option that took no value lands there: a
+// `--password -pw` would otherwise put the cleartext on disk as a directory name. `--` is how the caller
+// says a dash-leading positional is what they meant.
+if (!argv.includes('--') && (command === 'init' || command === 'doctor') && positional[0]?.startsWith('-')) {
+  fail(`unknown option "${positional[0]}" — run \`kestrel help\`.`)
+}
+
 if (flags.version || command === 'version') out(pkg.version)
 else if (flags.help || !command || command === 'help') help()
 else if (command === 'init') process.exitCode = await init(positional, flags)

package/scripts/lib/scaffold.mjs

@@ -31,9 +31,12 @@ const KEY_RE = /^\s*([A-Z][A-Z0-9_]*)\s*=/
 
 /**
  * Fills only keys that are absent or empty, so re-running `init` never rotates a live session secret.
+ * A key in `force` replaces a value that is already there — for a secret the caller supplied by hand,
+ * where being handed one at all is the instruction to change it.
  * Returns the new text plus the keys that changed.
  */
-export function mergeEnv(existing, entries) {
+export function mergeEnv(existing, entries, force = []) {
+  const forced = new Set(force)
   const pending = new Map(Object.entries(entries))
   const lines = existing === '' ? [] : existing.split('\n')
   const written = []
@@ -51,7 +54,7 @@ export function mergeEnv(existing, entries) {
     if (!key || !pending.has(key) || lastIndex.get(key) !== i) return line
     const value = pending.get(key)
     pending.delete(key)
-    if (line.slice(line.indexOf('=') + 1).trim() !== '') return line
+    if (line.slice(line.indexOf('=') + 1).trim() !== '' && !forced.has(key)) return line
     written.push(key)
     return `${key}=${value}`
   })
@@ -68,7 +71,8 @@ export function mergeEnv(existing, entries) {
   return { text: out.join('\n'), written }
 }
 
-const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v)
+/** `typeof null === 'object'`, and arrays are objects too — both need explicit exclusion for a plain object check. */
+export const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v)
 
 const NESTED = ['scripts', 'dependencies', 'devDependencies']
 // `type` decides whether every .js in the project is ESM or CJS, so injecting it silently could break a
@@ -87,14 +91,20 @@ export function mergePackageJson(existing, template) {
   }
   for (const key of NESTED) {
     if (!template[key]) continue
-    merged[key] = isObject(existing[key]) ? { ...template[key], ...existing[key] } : template[key]
+    merged[key] = isPlainObject(existing[key]) ? { ...template[key], ...existing[key] } : template[key]
     for (const name of Object.keys(template[key])) {
-      if (!isObject(existing[key]) || !(name in existing[key])) added.push(`${key}.${name}`)
+      if (!isPlainObject(existing[key]) || !(name in existing[key])) added.push(`${key}.${name}`)
     }
   }
   return { merged, added }
 }
 
+/**
+ * The value a dotenv key carries, or `undefined`/`''` when it carries none.
+ * Horizontal whitespace only: `\s*` would let an empty assignment match the NEXT line's value.
+ */
+export const envValue = (env, key) => new RegExp(`^[^\\S\\n]*${key}[^\\S\\n]*=[^\\S\\n]*(.+)$`, 'm').exec(env)?.[1].trim()
+
 const withoutComments = (src) => src.replace(/<!--[\s\S]*?-->/g, '')
 // `<nuxt-page />` is as valid as `<NuxtPage />`; matching only the Pascal spelling would flag a working app.
 const kebab = (tag) => tag.replace(/(?!^)([A-Z])/g, '-$1').toLowerCase()
@@ -160,8 +170,7 @@ export function diagnoseProject({ packageJson, nuxtConfig, appVue, env }) {
   if (env === null) {
     add('error', 'no .env — sign-in at /admin answers 503 until KESTREL_ADMIN_PASSWORD_HASH is set. Run `kestrel init`.')
   } else {
-    // Horizontal whitespace only: `\s*` would let an empty assignment match the NEXT line's value.
-    const value = (key) => new RegExp(`^[^\\S\\n]*${key}[^\\S\\n]*=[^\\S\\n]*(.+)$`, 'm').exec(env)?.[1].trim()
+    const value = (key) => envValue(env, key)
     if (!value('KESTREL_ADMIN_PASSWORD_HASH')) {
       add('error', 'KESTREL_ADMIN_PASSWORD_HASH is unset — /admin renders but sign-in answers 503. Run `kestrel hash-password`.')
     }