@michaelthielemann/kestrel 1.2.1 → 1.4.0

package/README.md

@@ -35,6 +35,9 @@ static host. It is deliberately **not**:
 
 ## Features
 
+- **Runnable in one command** — `pnpm create kestrel` scaffolds a project that boots with a working
+  `/admin`, prompting for the admin password and writing its hash; `kestrel init` does the same to an
+  existing project without clobbering it, and `kestrel doctor` names whatever is still missing.
 - **Collection-driven** — declare collections + fields in TypeScript; Kestrel derives the SQLite tables, a
   typed CRUD REST API, and the full admin UI. The schema **migrates itself** (additive in dev; explicit
   `db:migrate` in prod).
@@ -58,10 +61,26 @@ static host. It is deliberately **not**:
 
 ## Quickstart (consumer)
 
+```bash
+pnpm create kestrel my-site
+cd my-site && pnpm install && pnpm dev
+```
+
+It asks for an admin password and writes a project that runs as-is: `nuxt.config.ts` extending the
+meta-layer, an `app.vue` that renders, a `.env` holding a fresh session secret and the scrypt hash of
+your password, and one example block. Sign in at <http://localhost:3000/admin>.
+
+Already have a project? Run it in place — existing files are kept, `package.json` and `.env` are merged:
+
 ```bash
 pnpm add @michaelthielemann/kestrel
+pnpm kestrel init      # completes the project
+pnpm kestrel doctor    # or just diagnose one that misbehaves
 ```
 
+Installing the package **alone does nothing**: Nuxt only loads Kestrel once a config extends it. If you
+would rather wire it up by hand, that is two files:
+
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
@@ -88,8 +107,13 @@ export default defineCollection({
 
 Set the auth env (`KESTREL_SESSION_SECRET`, `KESTREL_ADMIN_PASSWORD_HASH`), start the app, and manage
 content at `/admin`. You bring your own **public layout** and **block SFCs**
-(`app/blocks/Hero.vue` — one file for schema + display — is the `hero` block). Full guide:
-**[consuming-kestrel.md](docs/consuming-kestrel.md)**.
+(`app/blocks/Hero.vue` — one file for schema + display — is the `hero` block).
+
+> **Do not add an `app/app.vue` that omits `<NuxtPage />`.** A project-owned one shadows the layer's, and
+> the file `nuxi init` writes renders `<NuxtWelcome />` instead of your routes — the admin then appears to
+> be missing rather than blank. Kestrel reports this at build time; `kestrel doctor` catches it earlier.
+
+Full guide: **[consuming-kestrel.md](docs/consuming-kestrel.md)**.
 
 ## Documentation
 
@@ -125,7 +149,10 @@ The CMS is split into Nuxt layers under `layers/`:
 - **`admin`** — the editor SPA: collection list, record editor, the 3-pane block editor.
 - **`public`** — the SSG render path: the catch-all page, `BlockRenderer`, sitemap / robots / llms.txt, deploy.
 
-`playground/` is a small consuming example.
+`playground/` is a small consuming example. `templates/starter/` is what the scaffolder writes out;
+`scripts/kestrel.mjs` is the engine's CLI and `packages/create-kestrel/` the standalone
+`pnpm create kestrel` front end, which copies the same templates in at pack time rather than keeping
+its own.
 
 ## Development
 
@@ -144,6 +171,9 @@ pnpm test:e2e       # end-to-end tests (real dev server)
 pnpm db:generate    # drizzle-kit: generate a migration
 pnpm db:migrate     # drizzle-kit: apply migrations
 pnpm hash-password  # produce a KESTREL_ADMIN_PASSWORD_HASH
+
+node scripts/kestrel.mjs init <dir>   # the consumer scaffolder, from a checkout
+node scripts/kestrel.mjs doctor <dir> # diagnose a consumer project
 ```
 
 In dev, the schema auto-syncs from the collection definitions (additive changes only); production applies

package/layers/admin/app/components/PageFields.vue

@@ -25,6 +25,11 @@ const props = defineProps<{
 const emit = defineEmits<{ update: [name: string, value: unknown] }>()
 const { t } = useT()
 
+// A project with a single layout has nothing to choose, so the control stays out of the pane entirely
+// rather than offering one dead option.
+const layoutOptions = computed(() => layoutSelectOptions(useOfferableLayouts(), t('pageSettings.layoutDefault')))
+const showLayout = computed(() => !!props.pageLike && layoutOptions.value.length > 1)
+
 // Live preview of the slug the server will auto-generate from the title while the field is left blank
 // (the server slugifies the title on save). Falls back to '/' when there is no title yet.
 const slugPlaceholder = computed(() => {
@@ -88,6 +93,26 @@ const slugPlaceholder = computed(() => {
     </template>
   </UiField>
 
+  <!-- Which layout renders this page (the `layout` system column). Empty = the `default` layout, so an
+       unset value keeps rendering exactly as a project without the column. -->
+  <UiField
+    v-if="showLayout"
+    class="page-settings__layout"
+    :label="t('pageSettings.layoutLabel')"
+    :hint="t('pageSettings.layoutHint')"
+    :error="errors.layout || null"
+  >
+    <template #default="f">
+      <UiSelect
+        :model-value="(values.layout as string) ?? ''"
+        :options="layoutOptions"
+        :disabled="disabled"
+        v-bind="f"
+        @update:model-value="(v) => emit('update', 'layout', v)"
+      />
+    </template>
+  </UiField>
+
   <!-- Page SEO (meta title/description/noindex + Google preview). The `seo` JSON system column. -->
   <SeoFields
     v-if="seo"

package/layers/admin/app/composables/useEditForm.ts

@@ -135,6 +135,8 @@ export function useEditForm(opts: UseEditFormOptions) {
     if (blocksEnabled.value) next.content = (source?.content as unknown[]) ?? []
     // `path` (the page slug) is a pageLike system column, likewise round-tripped explicitly.
     if (pageLike.value) next.path = (source?.path as string | null | undefined) ?? ''
+    // '' is the "no override" form the select binds to.
+    if (pageLike.value) next.layout = (source?.layout as string | null | undefined) ?? ''
     // `seo` is a JSON system column; default to an empty object so the editor can fill it in.
     if (hasSeo.value) next.seo = (source?.seo as Record<string, unknown> | undefined) ?? {}
     // `status` is a system column; a new record defaults to 'draft' (unpublished) — matches the DB default.
@@ -261,6 +263,9 @@ export function useEditForm(opts: UseEditFormOptions) {
     if (blocksEnabled.value) body.content = values.content
     // Send the slug as the routable path; a blank slug clears the route (stored as null, not "").
     if (pageLike.value) body.path = (values.path as string) ? values.path : null
+    // An unset layout is stored as NULL, never '': the render coalesces NULL to `default`, and a stored ''
+    // would be indistinguishable from a name that failed to save.
+    if (pageLike.value) body.layout = (values.layout as string) || null
     if (hasSeo.value) body.seo = values.seo ?? {}
     if (hasStatus.value) body.status = (values.status as string) ?? 'draft'
     // A new translatable multi record carries its locale, and links to a translation group when it is

package/layers/admin/app/pages/admin/[collection]/[id].nuxt.test.ts

@@ -0,0 +1,200 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { useState } from '#imports'
+import { flushPromises } from '@vue/test-utils'
+import { readBody } from 'h3'
+import { mountSuspended, registerEndpoint, mockNuxtImport } from '@nuxt/test-utils/runtime'
+import RecordPage from './[id].vue'
+
+const thingsSchema = {
+  name: 'things', mode: 'multi', translatable: false, pageLike: false, seo: false, status: false,
+  blocks: { enabled: false }, label: { singular: 'Thing', plural: 'Things' },
+  fields: { title: { type: 'text', required: true, translatable: false, unique: false } },
+}
+// Carries an explicit `label.new` — the create heading must use it verbatim, not the generic template.
+const articlesSchema = {
+  name: 'articles', mode: 'multi', translatable: false, pageLike: false, seo: false, status: false,
+  blocks: { enabled: false }, label: { singular: 'Article', plural: 'Articles', new: 'Compose article' },
+  fields: { title: { type: 'text', required: true, translatable: false, unique: false } },
+}
+registerEndpoint('/api/collections', () => ({ data: [thingsSchema, articlesSchema] }))
+registerEndpoint('/api/articles', () => ({ data: [], total: 0, page: 1, perPage: 25 }))
+
+let patched: Record<string, unknown> | null = null
+let posted: Record<string, unknown> | null = null
+registerEndpoint('/api/things/1', async (event) => {
+  if (event.method === 'PATCH') { patched = await readBody(event); return { id: 1, ...patched } }
+  return { id: 1, title: 'Existing' }
+})
+// A record whose title field is blank — the heading must fall back to the generic "#id" phrase.
+registerEndpoint('/api/things/2', () => ({ id: 2, title: '   ' }))
+registerEndpoint('/api/things', async (event) => {
+  if (event.method === 'POST') { posted = await readBody(event); return { id: 7, ...posted } }
+  return { data: [], total: 0, page: 1, perPage: 25 }
+})
+
+// The editor's Delete flows through the shared batch endpoint + the referrer-aggregate preview.
+let bulkBody: Record<string, unknown> | null = null
+registerEndpoint('/api/things/bulk', async (event) => {
+  bulkBody = await readBody(event)
+  return { action: bulkBody!.action, count: 1, ids: bulkBody!.ids }
+})
+registerEndpoint('/api/references/referrers', () => ({ counts: {} }))
+
+// Route + navigation are mocked so the page reads collection/id from `h.params` and navigations are captured.
+const h = vi.hoisted(() => ({ params: { collection: 'things', id: '1' }, nav: [] as unknown[] }))
+mockNuxtImport('useRoute', () => () => ({ params: h.params, query: {}, fullPath: `/admin/${h.params.collection}/${h.params.id}` }))
+mockNuxtImport('navigateTo', () => (to: unknown) => { h.nav.push(to); return Promise.resolve() })
+
+beforeEach(() => {
+  h.params = { collection: 'things', id: '1' }
+  h.nav.length = 0
+  patched = null
+  posted = null
+  bulkBody = null
+  useState('kestrel-collections').value = null
+  useState('kestrel-blocks').value = null
+})
+
+const settle = async () => {
+  await new Promise((r) => setTimeout(r, 20))
+  await flushPromises()
+}
+
+describe('record editor page header', () => {
+  it('merges Save, Cancel and Delete into the record head, each with an icon', async () => {
+    const w = await mountSuspended(RecordPage)
+    await flushPromises()
+
+    const head = w.find('.record__head')
+    expect(head.exists()).toBe(true)
+    const buttons = head.findAll('.ui-button')
+    expect(buttons.map((b) => b.text())).toEqual(expect.arrayContaining(['Save', 'Cancel', 'Delete']))
+    for (const b of buttons) expect(b.find('.ui-icon').exists()).toBe(true)
+    expect(w.find('.editor__actions').exists()).toBe(false)
+
+    // Cancel carries real button chrome — it sits beside the solid Delete/Save, not as bare text…
+    expect(buttons.find((b) => b.text() === 'Cancel')!.classes()).toContain('ui-button--secondary')
+    // …while the icon-only tools (undo/redo/open) stay quiet ghosts.
+    const iconOnly = buttons.filter((b) => b.text() === '')
+    expect(iconOnly.length).toBeGreaterThan(0)
+    for (const b of iconOnly) expect(b.classes()).toContain('ui-button--ghost')
+  })
+
+  it('titles the header with the singular label, not the raw (plural) route param', async () => {
+    h.params = { collection: 'things', id: 'new' }
+    const wNew = await mountSuspended(RecordPage)
+    await flushPromises()
+    expect(wNew.find('.record__title').text()).toBe('New Thing')
+    expect(wNew.find('.record__back').text()).toContain('Things')
+    // The generic phrase is title-cased; a real record title would not be.
+    expect(wNew.find('.record__title').classes()).toContain('record__title--generic')
+  })
+
+  it('keeps the back link on the heading row (one line, so the panes keep the vertical space)', async () => {
+    const w = await mountSuspended(RecordPage)
+    await flushPromises()
+    expect(w.find('.record__head .record__back').exists()).toBe(true)
+  })
+
+  it('titles a saved record with its own title — an id means nothing to an editor', async () => {
+    h.params = { collection: 'things', id: '1' }
+    const wEdit = await mountSuspended(RecordPage)
+    await settle()
+    expect(wEdit.find('.record__title').text()).toBe('Existing')
+    expect(wEdit.find('.record__title').classes()).not.toContain('record__title--generic')
+  })
+
+  it('falls back to "Edit {collection} #{id}" when the record has no usable title', async () => {
+    h.params = { collection: 'things', id: '2' }
+    const wEdit = await mountSuspended(RecordPage)
+    await settle()
+    expect(wEdit.find('.record__title').text()).toBe('Edit Thing #2')
+    expect(wEdit.find('.record__title').classes()).toContain('record__title--generic')
+  })
+
+  it('uses the collection\'s explicit label.new for the create heading (no generic "New X")', async () => {
+    h.params = { collection: 'articles', id: 'new' }
+    const w = await mountSuspended(RecordPage)
+    await flushPromises()
+    expect(w.find('.record__title').text()).toBe('Compose article')
+  })
+
+  it('wires the header Save button to submit the editor form', async () => {
+    const w = await mountSuspended(RecordPage)
+    await flushPromises()
+    const save = w.findAll('.record__head .ui-button').find((b) => b.text() === 'Save')!
+    expect(save.attributes('type')).toBe('submit')
+    expect(save.attributes('form')).toBe('record-editor')
+    expect(w.find('form.editor').attributes('id')).toBe('record-editor')
+  })
+
+  it('shows the back link with a centered SVG arrow (no text arrow glyph)', async () => {
+    const w = await mountSuspended(RecordPage)
+    await flushPromises()
+    const back = w.find('.record__back')
+    expect(back.exists()).toBe(true)
+    expect(back.find('.ui-icon').exists()).toBe(true)
+    expect(back.text()).not.toContain('←')
+  })
+
+  it('saving an existing record stays on the page — Save only saves', async () => {
+    const w = await mountSuspended(RecordPage)
+    await flushPromises()
+    await w.find('form.editor').trigger('submit')
+    await settle()
+    expect(patched).toMatchObject({ title: 'Existing' })
+    expect(h.nav).toEqual([])
+  })
+
+  it('saving a NEW record moves to its own editor, not back to the list', async () => {
+    h.params = { collection: 'things', id: 'new' }
+    const w = await mountSuspended(RecordPage)
+    await flushPromises()
+    await w.findAll('input')[0]!.setValue('Fresh')
+    await w.find('form.editor').trigger('submit')
+    await settle()
+    expect(posted).toMatchObject({ title: 'Fresh' })
+    // navigates to the created record's editor (id 7), never to the list path
+    expect(h.nav).toContain('/admin/things/7')
+    expect(h.nav).not.toContain('/admin/things')
+  })
+
+  it('deletes through the confirm dialog (shared batch op) and navigates back to the list', async () => {
+    const w = await mountSuspended(RecordPage)
+    await settle()
+    // the header Delete opens the dialog rather than window.confirm
+    const del = w.findAll('.record__head .ui-button').find((b) => b.text() === 'Delete')!
+    await del.trigger('click')
+    await settle()
+    expect(w.find('.ui-dialog__content').exists()).toBe(true)
+    // confirming posts the bulk delete for this one id and then navigates to the list
+    const confirm = w.findAll('.ui-dialog__content .ui-button').find((b) => /^delete$/i.test(b.text().trim()))!
+    await confirm.trigger('click')
+    await settle()
+    expect(bulkBody).toEqual({ action: 'delete', ids: [1] })
+    expect(h.nav).toContain('/admin/things')
+  })
+
+  it('a native beforeunload (tab close / reload) is blocked only while there are unsaved changes', async () => {
+    const w = await mountSuspended(RecordPage)
+    await flushPromises()
+
+    // pristine → unload is NOT blocked
+    const clean = new Event('beforeunload', { cancelable: true })
+    window.dispatchEvent(clean)
+    expect(clean.defaultPrevented).toBe(false)
+
+    // edit a field → dirty → unload IS blocked (browser shows its native prompt)
+    await w.findAll('input')[0]!.setValue('Changed')
+    await settle()
+    const dirty = new Event('beforeunload', { cancelable: true })
+    window.dispatchEvent(dirty)
+    expect(dirty.defaultPrevented).toBe(true)
+
+    // unmounting removes the listener (no leak across pages)
+    w.unmount()
+    const afterUnmount = new Event('beforeunload', { cancelable: true })
+    window.dispatchEvent(afterUnmount)
+    expect(afterUnmount.defaultPrevented).toBe(false)
+  })
+})

package/layers/auth/server/utils/session.ts

@@ -52,7 +52,7 @@ export interface SessionSettings {
   cookieName: string
 }
 
-export function sessionSettings(): SessionSettings {
+export function sessionSettings({ prerender = import.meta.prerender === true } = {}): SessionSettings {
   // Treat anything that isn't an EXPLICIT dev signal as production for these safeguards, so a deployment
   // that simply omits NODE_ENV (a common slip when launching `.output/server/index.mjs`) is hardened —
   // not silently downgraded to dev, which would tolerate a missing secret + non-Secure cookies. Vitest
@@ -60,7 +60,10 @@ export function sessionSettings(): SessionSettings {
   const explicitDev = process.env.NODE_ENV === 'development' || process.env.NODE_ENV === 'test' || process.env.KESTREL_DEV === '1'
   const isProd = !explicitDev
   const secureCookies = process.env.KESTREL_SECURE_COOKIES !== 'false'
-  if (isProd && !secureCookies) {
+  // `nuxt generate` prerenders every page through `/api/route`, which passes the access guard and lands
+  // here with NODE_ENV=production. A prerender request never issues a cookie, so enforcing the flag there
+  // only means a dev `.env` silently drops pages from the static output.
+  if (isProd && !secureCookies && !prerender) {
     throw new Error('KESTREL_SECURE_COOKIES=false is not allowed in production')
   }
   const rawMaxAge = Number(process.env.KESTREL_SESSION_MAX_AGE)

package/layers/core/app/composables/layouts.ts

@@ -0,0 +1,5 @@
+import { kestrelLayouts } from '#build/kestrel-layouts.mjs'
+
+export function useOfferableLayouts(): string[] {
+  return kestrelLayouts
+}

package/layers/core/app/utils/layouts.ts

@@ -0,0 +1,38 @@
+/** The admin shell. Never offerable for a public record — a page rendered inside it would carry the
+ *  admin chrome and its own `useHead`. */
+export const ADMIN_LAYOUT = 'admin'
+
+/** Nuxt's resolved `app.layouts` entry (`nuxt.options.app.layouts`, filled before the `app:resolve` hook). */
+export interface ResolvedLayout { name: string, file: string }
+
+/**
+ * The layout names a page may be assigned, from Nuxt's own resolved layout map. Nuxt has already done the
+ * layer-ordered, name-first dedup (a consumer's `default.vue` shadows the engine's), so this only filters
+ * and sorts — no directory scan of our own.
+ */
+export function offerableLayouts(layouts: Record<string, ResolvedLayout | undefined>): string[] {
+  return Object.values(layouts)
+    .filter((l): l is ResolvedLayout => !!l && typeof l.file === 'string' && l.file.endsWith('.vue'))
+    .map((l) => l.name)
+    .filter((name) => name !== ADMIN_LAYOUT)
+    .sort()
+}
+
+export function renderLayoutRegistry(names: string[]): string {
+  return `export const kestrelLayouts = ${JSON.stringify(names)}\n`
+}
+
+/**
+ * Options for the page-layout select. The fallback is one entry with an EMPTY value — an unset column
+ * already renders `default`, so offering `default` as its own value would give the editor two controls for
+ * one outcome and pin the row to a name the consumer may later rename.
+ */
+export function layoutSelectOptions(names: string[], fallbackLabel: string): { label: string, value: string }[] {
+  return [
+    { label: fallbackLabel, value: '' },
+    ...names.filter((n) => n !== DEFAULT_LAYOUT_NAME).map((n) => ({ label: n, value: n })),
+  ]
+}
+
+/** Mirrors `DEFAULT_LAYOUT` in the public layer; kept local so this util stays dependency-free. */
+const DEFAULT_LAYOUT_NAME = 'default'

package/layers/core/modules/auto-discovery/index.ts

@@ -1,8 +1,9 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { addComponentsDir, addTypeTemplate, createResolver, defineNuxtModule } from '@nuxt/kit'
+import { addComponentsDir, addTemplate, addTypeTemplate, createResolver, defineNuxtModule } from '@nuxt/kit'
 import { collectBlockSfcs, collectDefinitions, renderRegistry } from './scan'
 import { renderBlockRegistry } from './extract-block'
+import { offerableLayouts, renderLayoutRegistry } from '../../app/utils/layouts'
 
 export default defineNuxtModule({
   meta: { name: 'kestrel-auto-discovery' },
@@ -22,6 +23,15 @@ export default defineNuxtModule({
       if (existsSync(dir)) addComponentsDir({ path: dir, prefix: 'Blocks', global: true, pathPrefix: false })
     }
 
+    // Layouts need no scan of our own: Nuxt already resolves `app/layouts/*.vue` across the layers with the
+    // same name-first, consumer-wins dedup, and fills `app.layouts` just before `app:resolve` — which runs
+    // inside `generateApp`, ahead of the templates being written, so the closure below is filled in time.
+    let layoutNames: string[] = []
+    nuxt.hook('app:resolve', (app) => { layoutNames = offerableLayouts(app.layouts ?? {}) })
+    // `write` so the resolved list is inspectable in `.nuxt/` — a virtual-only template makes "which layouts
+    // did the build actually find" unanswerable without a debugger.
+    addTemplate({ filename: 'kestrel-layouts.mjs', write: true, getContents: () => renderLayoutRegistry(layoutNames) })
+
     nuxt.hook('nitro:config', (nitro) => {
       nitro.virtual ||= {}
       // Consumer field types register as a side effect on import, and the schema engine builds a table the

package/layers/core/modules/auto-discovery/virtual.d.ts

@@ -10,3 +10,6 @@ declare module '#kestrel/schema-tables' {
   const tables: unknown[]
   export default tables
 }
+declare module '#build/kestrel-layouts.mjs' {
+  export const kestrelLayouts: string[]
+}

package/layers/core/modules/kestrel/app-shell.ts

@@ -0,0 +1,55 @@
+export type AppShellDiagnostic = { level: 'error' | 'warn'; message: string }
+
+export type AppShellInput = {
+  mainComponent: string | null | undefined
+  pagesEnabled: boolean
+  read: (file: string) => string
+}
+
+const withoutComments = (src: string) => 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: string) => tag.replace(/(?!^)([A-Z])/g, '-$1').toLowerCase()
+const uses = (src: string, tag: string) => new RegExp(`<\\s*(${tag}|${kebab(tag)})[\\s/>]`, 'i').test(src)
+
+const FIX = `
+  <template>
+    <NuxtLayout>
+      <NuxtPage />
+    </NuxtLayout>
+  </template>`
+
+/** Reports only — assigning `mainComponent` would defeat a legitimate override. See ADR-0005. */
+export function diagnoseAppShell({ mainComponent, pagesEnabled, read }: AppShellInput): AppShellDiagnostic[] {
+  const found: AppShellDiagnostic[] = []
+
+  if (!pagesEnabled) {
+    found.push({
+      level: 'error',
+      message:
+        'the pages feature is disabled (`pages: false`), so no route is registered at all — the admin is a set of pages under `app/pages/admin/`. Remove the override to reach /admin.',
+    })
+  }
+
+  if (mainComponent) {
+    let src: string | undefined
+    try {
+      src = withoutComments(read(mainComponent))
+    } catch {
+      // An unreadable app root is Nuxt's to report; guessing here would produce a phantom error.
+    }
+    if (src !== undefined && !uses(src, 'NuxtPage')) {
+      found.push({
+        level: 'error',
+        message: `${mainComponent} renders no <NuxtPage />, so NO route renders — including /admin. It shadows Kestrel's own app.vue because the consumer layer wins. Either delete it (Kestrel ships a working one) or make it:${FIX}`,
+      })
+    } else if (src !== undefined && !uses(src, 'NuxtLayout')) {
+      found.push({
+        level: 'warn',
+        message: `${mainComponent} renders no <NuxtLayout />, so page-level \`layout\` is ignored and the admin loses its navigation shell. Wrap <NuxtPage /> in <NuxtLayout>.`,
+      })
+    }
+  }
+
+  return found
+}

package/layers/core/modules/kestrel/index.ts

@@ -1,5 +1,7 @@
+import { readFileSync } from 'node:fs'
 import { defineNuxtModule } from '@nuxt/kit'
 import { resolveKestrel, type KestrelConfig } from '../../server/utils/kestrel-config'
+import { diagnoseAppShell } from './app-shell'
 
 /**
  * The `kestrel` config namespace (`kestrel: { … }` in nuxt.config, sourced from `kestrel.config.ts`).
@@ -13,6 +15,21 @@ export default defineNuxtModule<KestrelConfig>({
   setup(options, nuxt) {
     const c = resolveKestrel(options, process.env, nuxt.options.rootDir)
 
+    // `app:resolve` is the first hook where `mainComponent` is settled across all layers. In dev it fires
+    // on every watched change, so an unfixed problem would repaint the whole message on each keystroke.
+    const reported = new Set<string>()
+    nuxt.hook('app:resolve', (app) => {
+      for (const d of diagnoseAppShell({
+        mainComponent: app.mainComponent,
+        pagesEnabled: nuxt.options.pages !== false,
+        read: (file) => readFileSync(file, 'utf8'),
+      })) {
+        if (reported.has(d.message)) continue
+        reported.add(d.message)
+        console[d.level === 'error' ? 'error' : 'warn'](`[kestrel] ${d.message}`)
+      }
+    })
+
     const rc = nuxt.options.runtimeConfig
     rc.media = {
       driver: c.media.driver,

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

@@ -0,0 +1,60 @@
+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 } from '../../utils/crud'
+import { requireCollection, parseIdList } from '../../utils/http'
+import { clearRegistry, registerCollection } from '../../utils/registry'
+import { pickerOptions } from '../../utils/picker'
+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 } },
+}))
+
+interface FakeEvent { query: Record<string, unknown>; context: { params: Record<string, string>; readScope?: string } }
+
+let db: ReturnType<typeof drizzle>
+
+// Same rationale as translations.get.test.ts: bind the handler's auto-imported helpers to the REAL
+// implementations so this proves the actual wiring, not a stub the server does not have.
+Object.assign(globalThis, {
+  defineEventHandler: (handler: unknown) => handler,
+  createError,
+  getQuery: (event: FakeEvent) => event.query,
+  useDb: () => db,
+  requireCollection,
+  parseIdList,
+  pickerOptions,
+  publishedOnlyForScope: () => false,
+})
+
+const handler = (await import('./options.get')).default as unknown as (event: FakeEvent) => ReturnType<typeof pickerOptions>
+const get = (collection: string, query: Record<string, unknown>) => handler({ query, context: { params: { collection } } })
+
+beforeEach(() => {
+  const sqlite = new Database(':memory:')
+  for (const stmt of renderSqlite(diffSchema(desiredSchema([posts.table]), {}))) sqlite.exec(stmt)
+  db = drizzle(sqlite)
+  clearRegistry()
+  registerCollection(posts)
+})
+afterEach(() => clearRegistry())
+
+describe('GET /api/{collection}/options?ids=', () => {
+  it('resolves more than 100 ids in one request instead of truncating', () => {
+    const ids = Array.from({ length: 150 }, (_, i) => (create(db, posts, { title: `T${i}` }) as { id: number }).id)
+    const r = get('posts', { ids: ids.join(',') })
+    expect(r.data.length).toBe(150)
+  })
+
+  it('400s (never silently truncates) an ids list over the shared bulk cap', () => {
+    const ids = Array.from({ length: 501 }, (_, i) => i + 1)
+    expect(() => get('posts', { ids: ids.join(',') })).toThrowError(expect.objectContaining({ statusCode: 400 }))
+  })
+})