@michaelthielemann/kestrel 1.2.1 → 1.3.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/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/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 }))
+  })
+})

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

@@ -0,0 +1,90 @@
+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, resolveTranslations } from '../../utils/crud'
+import { requireCollection } from '../../utils/http'
+import { clearRegistry, registerCollection } from '../../utils/registry'
+import { desiredSchema } from '../../schema/desired'
+import { diffSchema } from '../../schema/diff'
+import { renderSqlite } from '../../schema/render-sqlite'
+
+const pages = buildCollection(defineCollection({
+  name: 'pages', mode: 'multi', translatable: true, pageLike: true,
+  fields: { title: { type: 'text', required: true } },
+}))
+const notes = buildCollection(defineCollection({
+  name: 'notes', mode: 'multi', translatable: false,
+  fields: { title: { type: 'text', required: true } },
+}))
+
+// `context.params` is where Nitro puts the route params the real `requireCollection` reads via h3.
+interface FakeEvent { query: Record<string, unknown>; context: { params: Record<string, string> } }
+
+let db: ReturnType<typeof drizzle>
+
+// The handler is a Nitro route: its auto-imported helpers are plain globals in a node test — bound to the
+// REAL implementations so nothing here can pass against a stub the server does not have.
+Object.assign(globalThis, {
+  defineEventHandler: (handler: unknown) => handler,
+  createError,
+  getQuery: (event: FakeEvent) => event.query,
+  useDb: () => db,
+  requireCollection,
+  resolveTranslations,
+})
+
+// Calling the handler directly says nothing about the path ever reaching it: that the literal `translations`
+// segment wins over the sibling `[id]` route is only provable on a real server → `test/e2e/api.test.ts`.
+const handler = (await import('./translations.get')).default as unknown as (event: FakeEvent) => Record<string, number | null>
+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([pages.table, notes.table]), {}))) sqlite.exec(stmt)
+  db = drizzle(sqlite)
+  clearRegistry()
+  registerCollection(pages)
+  registerCollection(notes)
+})
+afterEach(() => clearRegistry())
+
+describe('GET /api/{collection}/translations?group=', () => {
+  it('resolves the group\'s locale → sibling id map without a record id', () => {
+    const en = create(db, pages, { title: 'Home' }) as Record<string, unknown>
+    const de = create(db, pages, { title: 'Start', locale: 'de', translationGroup: en.translationGroup as string }) as Record<string, unknown>
+    expect(get('pages', { group: en.translationGroup })).toEqual({ en: en.id, de: de.id })
+  })
+
+  it('reports a locale with no sibling as null (what the "+ create" affordance keys off)', () => {
+    const en = create(db, pages, { title: 'Only EN' }) as Record<string, unknown>
+    expect(get('pages', { group: en.translationGroup })).toEqual({ en: en.id, de: null })
+  })
+
+  it('returns exactly the per-record map for the same group (one map builder, two entry points)', () => {
+    const en = create(db, pages, { title: 'Home' }) as Record<string, unknown>
+    create(db, pages, { title: 'Start', locale: 'de', translationGroup: en.translationGroup as string })
+    expect(get('pages', { group: en.translationGroup })).toEqual(resolveTranslations(db, pages, en.id as number))
+  })
+
+  it('400s without a group rather than answering for an arbitrary one', () => {
+    expect(() => get('pages', {})).toThrowError(expect.objectContaining({ statusCode: 400 }))
+    expect(() => get('pages', { group: '  ' })).toThrowError(expect.objectContaining({ statusCode: 400 }))
+  })
+
+  it('404s for a group that has no rows', () => {
+    create(db, pages, { title: 'Home' })
+    expect(() => get('pages', { group: 'nope' })).toThrowError(expect.objectContaining({ statusCode: 404 }))
+  })
+
+  it('400s (never 500s) for a collection without translations — it has no group column at all', () => {
+    create(db, notes, { title: 'Note' })
+    expect(() => get('notes', { group: 'g1' })).toThrowError(/Translations are not enabled/)
+  })
+
+  it('404s for an unknown collection', () => {
+    expect(() => get('nope', { group: 'g1' })).toThrowError(expect.objectContaining({ statusCode: 404 }))
+  })
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michaelthielemann/kestrel",
-  "version": "1.2.1",
+  "version": "1.3.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>",
@@ -21,18 +21,22 @@
   ],
   "type": "module",
   "main": "./nuxt.config.ts",
+  "bin": {
+    "kestrel": "./scripts/kestrel.mjs"
+  },
   "packageManager": "pnpm@11.9.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
-  "//publish": "Consumed as a meta-layer: `extends: ['@michaelthielemann/kestrel']`. `main` points at the layer's nuxt.config so the BARE specifier resolves — without it c12 can't resolve the package, silently drops the whole layer (\"Cannot extend config from …\"), and every auto-import/component vanishes. Use `main`, NOT `exports` (exports would gate subpaths like `@michaelthielemann/kestrel/scripts/hash-password.mjs` + the deep config-type import). `files` ships the entry + sub-layers + operator scripts; the `!**/*.test.ts` globs strip tests. Releases run from the tag workflow via npm trusted publishing (OIDC), so no npm token exists anywhere.",
+  "//publish": "Consumed as a meta-layer: `extends: ['@michaelthielemann/kestrel']`. `main` points at the layer's nuxt.config so the BARE specifier resolves — without it c12 can't resolve the package, silently drops the whole layer (\"Cannot extend config from …\"), and every auto-import/component vanishes. Use `main`, NOT `exports` (exports would gate subpaths like `@michaelthielemann/kestrel/scripts/hash-password.mjs` + the deep config-type import); `bin` resolves by path from the package root, so it coexists with `main` untouched. `files` ships the entry + sub-layers + operator scripts + the `kestrel init` templates; the `!**/*.test.ts` globs strip tests — they are GLOBAL, so nothing under `templates/` may be named `*.test.ts` or it vanishes from the tarball. Template dotfiles are `_`-prefixed for the same class of reason: npm strips a literal `.gitignore` from a tarball and then applies it, taking its listed siblings with it. Releases run from the tag workflow via npm trusted publishing (OIDC), so no npm token exists anywhere.",
   "files": [
     "NOTICE",
     "nuxt.config.ts",
     "kestrel.config.ts",
     "layers",
     "scripts",
+    "templates",
     "!**/*.test.ts",
     "!**/*.dom.test.ts",
     "!**/*.nuxt.test.ts"