@michaelthielemann/kestrel 1.2.1 → 1.4.0

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/layers/fields/server/utils/buildTable.ts

@@ -17,7 +17,7 @@ function reservedColumns(def: CollectionDef): { js: Set<string>; db: Set<string>
   if (def.translatable) add('locale', 'locale')
   if (def.mode === 'single') add('singletonKey', 'singleton_key')
   else if (def.translatable) add('translationGroup', 'translation_group')
-  if (def.pageLike) add('path', 'path')
+  if (def.pageLike) { add('path', 'path'); add('layout', 'layout') }
   if (def.status) add('status', 'status')
   if (def.seo) add('seo', 'seo')
   if (def.blocks?.enabled) add('content', 'content')
@@ -67,7 +67,13 @@ export function buildTable(def: CollectionDef): SQLiteTable {
   if (def.translatable) cols.locale = text('locale').notNull()
   if (def.mode === 'single') cols.singletonKey = text('singleton_key').notNull()
   else if (def.translatable) cols.translationGroup = text('translation_group').notNull()
-  if (def.pageLike) cols.path = text('path')
+  if (def.pageLike) {
+    cols.path = text('path')
+    // Nullable with no default: an editor's "inherit" must be distinguishable from an explicit `default`,
+    // and the render decides the fallback (see resolvePageLayout) so a deleted layout file degrades in one
+    // place instead of being frozen into every row.
+    cols.layout = text('layout')
+  }
   if (def.status) cols.status = text('status').notNull().default('draft')
   if (def.seo) cols.seo = text('seo', { mode: 'json' }).$type<SeoMeta>().notNull().default(sql`'{}'`)
   if (def.blocks?.enabled) cols.content = text('content', { mode: 'json' }).$type<Block[]>().notNull().default(sql`'[]'`)

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

@@ -1,6 +1,14 @@
 <script setup lang="ts">
+import type { LayoutKey } from 'nuxt/app'
+
+// The record decides its own layout, so route-meta resolution is opted out of and this page renders the
+// `<NuxtLayout>` itself. Side effect worth knowing: the layout becomes a CHILD of the page, so it can read
+// `usePublicPageState()` during SSR — as its parent it rendered before the page had written it.
+definePageMeta({ layout: false })
+
 interface RenderedPage {
   title?: string
+  layout?: string | null
   seo?: {
     title?: string
     description?: string
@@ -36,6 +44,12 @@ const { data: resolved } = await useAsyncData(`page:${locale}:${path}`, () =>
   }),
 )
 const page = computed(() => resolved.value?.page ?? null)
+// `fallback` below only rescues a truthy name that is missing from the layout map, so the empty cases have
+// to be coalesced here — see resolvePageLayout. The cast is the one honest bridge in this file: the stored
+// name is arbitrary editor data, while `NuxtLayout` types `name` as the union of layouts that existed at
+// build time. Narrowing to that union is impossible for a value read from the DB, and `fallback` is exactly
+// the runtime guard for a name outside it.
+const pageLayout = computed(() => resolvePageLayout(page.value?.layout) as LayoutKey)
 
 // The layout (language menu & co.) needs the resolved record and its collection; pages and layouts share
 // no other channel, so mirror the fetch result into the shared state — reactively, so client-side
@@ -113,21 +127,23 @@ useSeoMeta({
 </script>
 
 <template>
-  <article>
-    <!-- Only ever shown to an authenticated admin previewing an unpublished page (drafts never resolve
-         for anonymous visitors or the static render), so it never ships to the public/static site.
-         Suppressed inside the editor preview iframe — the editor's own status ampel covers it. -->
-    <div v-if="isDraftPreview && !previewActive" class="kestrel-draft-badge" role="status">
-      <span class="kestrel-draft-badge__dot" aria-hidden="true" />
-      Draft preview — not published
-    </div>
-    <!-- Editor preview: the bridge swaps in the editor's live (unsaved) tree over postMessage and makes
-         blocks selectable; the saved content renders until the first message. Normal path unchanged. -->
-    <LazyKestrelPreviewBridge v-if="previewActive" :blocks="(page?.content as any[]) ?? []" v-slot="{ blocks }">
-      <BlockRenderer :blocks="(blocks as any[])" />
-    </LazyKestrelPreviewBridge>
-    <BlockRenderer v-else :blocks="(page?.content as any[]) ?? []" />
-  </article>
+  <NuxtLayout :name="pageLayout" fallback="default">
+    <article>
+      <!-- Only ever shown to an authenticated admin previewing an unpublished page (drafts never resolve
+           for anonymous visitors or the static render), so it never ships to the public/static site.
+           Suppressed inside the editor preview iframe — the editor's own status ampel covers it. -->
+      <div v-if="isDraftPreview && !previewActive" class="kestrel-draft-badge" role="status">
+        <span class="kestrel-draft-badge__dot" aria-hidden="true" />
+        Draft preview — not published
+      </div>
+      <!-- Editor preview: the bridge swaps in the editor's live (unsaved) tree over postMessage and makes
+           blocks selectable; the saved content renders until the first message. Normal path unchanged. -->
+      <LazyKestrelPreviewBridge v-if="previewActive" :blocks="(page?.content as any[]) ?? []" v-slot="{ blocks }">
+        <BlockRenderer :blocks="(blocks as any[])" />
+      </LazyKestrelPreviewBridge>
+      <BlockRenderer v-else :blocks="(page?.content as any[]) ?? []" />
+    </article>
+  </NuxtLayout>
 </template>
 
 <style scoped>

package/layers/public/app/utils/page-layout.ts

@@ -0,0 +1,18 @@
+/** The layout every page falls back to. Nuxt's own name for the unnamed layout, and the one the public
+ *  layer ships (`layers/public/app/layouts/default.vue`), so it is always present. */
+export const DEFAULT_LAYOUT = 'default'
+
+/**
+ * The layout name to render a page in, from its stored `layout` column.
+ *
+ * Must never return an empty value. The catch-all declares `definePageMeta({ layout: false })` so the page
+ * owns its own `<NuxtLayout>`; that makes `route.meta.layout` the literal `false`, and NuxtLayout resolves
+ * `unref(props.name) ?? route.meta.layout ?? …` — `??` keeps `false`, which fails its `hasLayout` check and
+ * renders the page with NO layout wrapper. The `fallback` prop does not cover this: it only applies to a
+ * truthy name absent from the layout map. Coalescing here is what keeps an unset column rendering the
+ * normal site frame.
+ */
+export function resolvePageLayout(stored: string | null | undefined): string {
+  const name = typeof stored === 'string' ? stored.trim() : ''
+  return name || DEFAULT_LAYOUT
+}

package/layers/ui/app/i18n/de.ts

@@ -133,6 +133,9 @@ export const de: Catalog = {
 
   'pageSettings.slugLabel': 'Slug',
   'pageSettings.slugHint': 'URL-Pfad, z. B. /about (leer = automatisch aus dem Titel)',
+  'pageSettings.layoutLabel': 'Layout',
+  'pageSettings.layoutHint': 'Mit welchem Layout diese Seite gerendert wird.',
+  'pageSettings.layoutDefault': 'Standard (default)',
   'pageSettings.statusLabel': 'Status',
   'pageSettings.statusHint': 'Entwurf bleibt offline; Veröffentlicht rendert die Seite.',
   'pageSettings.statusDraft': 'Entwurf',

package/layers/ui/app/i18n/en.ts

@@ -144,6 +144,9 @@ export const en: Catalog = {
   // page settings (system fields on pageLike collections)
   'pageSettings.slugLabel': 'Slug',
   'pageSettings.slugHint': 'URL path, e.g. /about (blank = auto-generated from the title)',
+  'pageSettings.layoutLabel': 'Layout',
+  'pageSettings.layoutHint': 'Which layout renders this page.',
+  'pageSettings.layoutDefault': 'Standard (default)',
   'pageSettings.statusLabel': 'Status',
   'pageSettings.statusHint': 'Draft stays off the live site; Published renders it.',
   'pageSettings.statusDraft': 'Draft',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michaelthielemann/kestrel",
-  "version": "1.2.1",
+  "version": "1.4.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"

package/scripts/copy-create-payload.mjs

@@ -0,0 +1,49 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// create-kestrel ships copies of the engine's templates + scaffold lib. Generating them at pack time
+// keeps one source of truth; committing them would let the two drift. See ADR-0005.
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const PKG = join(ROOT, 'packages/create-kestrel')
+const LIB_FILES = ['scaffold.mjs', 'password.mjs', 'cli.mjs']
+const GENERATED = ['templates', 'lib', 'LICENSE', 'NOTICE']
+
+const manifestPath = join(PKG, 'package.json')
+
+const clean = () => {
+  for (const entry of GENERATED) rmSync(join(PKG, entry), { recursive: true, force: true })
+}
+
+if (process.argv.includes('--clean')) {
+  clean()
+} else {
+  clean()
+  const engine = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'))
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+
+  // The version cannot be corrected here: npm derives the tarball name from the manifest as it stood
+  // BEFORE prepack, so a rewrite yields a tarball whose name and contents disagree. Refuse instead —
+  // test/create-kestrel.test.ts keeps the two manifests in lockstep so this never fires in practice.
+  if (manifest.version !== engine.version) {
+    console.error(`create-kestrel is at ${manifest.version} but the engine is at ${engine.version} — bump both.`)
+    process.exit(1)
+  }
+
+  cpSync(join(ROOT, 'templates'), join(PKG, 'templates'), { recursive: true })
+  mkdirSync(join(PKG, 'lib'), { recursive: true })
+  for (const file of LIB_FILES) cpSync(join(ROOT, 'scripts/lib', file), join(PKG, 'lib', file))
+  for (const file of ['LICENSE', 'NOTICE']) {
+    if (existsSync(join(ROOT, file))) cpSync(join(ROOT, file), join(PKG, file))
+  }
+
+  // A generated file, not a key in the committed manifest: `postpack` is not guaranteed to run (a failed
+  // publish skips it), and a stamp left behind in package.json would be committed and then silently pin
+  // stale ranges. Deleting `lib/` removes this with everything else.
+  const stamp = {
+    nuxt: engine.dependencies?.nuxt,
+    typescript: engine.dependencies?.typescript,
+    'vue-tsc': engine.devDependencies?.['vue-tsc'],
+  }
+  writeFileSync(join(PKG, 'lib', 'engine-meta.mjs'), `export default ${JSON.stringify(stamp, null, 2)}\n`)
+}

package/scripts/hash-password.mjs

@@ -1,26 +1,17 @@
-import { scryptSync, randomBytes } from 'node:crypto'
 import { createInterface } from 'node:readline'
+import { hashPassword } from './lib/password.mjs'
 
-const N = 2 ** 17
-const r = 8
-const p = 1
-const KEYLEN = 64
-const MAXMEM = 256 * 1024 * 1024
-
-function make(password) {
-  const salt = randomBytes(16)
-  const hash = scryptSync(password, salt, KEYLEN, { N, r, p, maxmem: MAXMEM })
-  return `scrypt$${N}$${r}$${p}$${salt.toString('base64url')}$${hash.toString('base64url')}`
-}
-
+// Not used at runtime: this prints a value an operator pastes into KESTREL_ADMIN_PASSWORD_HASH. Kept as a
+// standalone entry point because docs/consuming-kestrel.md tells consumers to run it straight out of
+// node_modules, which must keep working whether or not the `kestrel` bin is on PATH.
 const arg = process.argv[2]
 if (arg) {
-  process.stdout.write(make(arg) + '\n')
+  process.stdout.write(hashPassword(arg) + '\n')
 } else {
   const rl = createInterface({ input: process.stdin, terminal: false })
   process.stderr.write('Enter password, then press Enter:\n')
   rl.on('line', (line) => {
-    process.stdout.write(make(line) + '\n')
+    process.stdout.write(hashPassword(line) + '\n')
     rl.close()
   })
 }

package/scripts/kestrel.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { join, resolve, basename, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createInterface } from 'node:readline/promises'
+import { hashPassword, sessionSecret } from './lib/password.mjs'
+import { PACKAGE_NAME, diagnoseProject, 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`.
+const PKG_ROOT = resolve(fileURLToPath(import.meta.url), '../..')
+const TEMPLATES = join(PKG_ROOT, 'templates')
+const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'))
+
+const { dim, bold, red, yellow, green } = makePaint()
+const fail = (s) => {
+  process.stderr.write(`${red('error')} ${s}\n`)
+  process.exit(1)
+}
+
+const templateVars = (name) => ({
+  name,
+  version: `^${pkg.version}`,
+  nuxtVersion: pkg.dependencies?.nuxt ?? '^4.4.8',
+  typescriptVersion: pkg.dependencies?.typescript ?? '^6.0.3',
+  vueTscVersion: pkg.devDependencies?.['vue-tsc'] ?? '^3.3.7',
+})
+
+function inspect(target) {
+  return diagnoseProject({
+    packageJson: readIf(join(target, 'package.json')),
+    nuxtConfig: readIf(join(target, 'nuxt.config.ts')) ?? readIf(join(target, 'nuxt.config.js')),
+    appVue: readIf(join(target, 'app', 'app.vue')) ?? readIf(join(target, 'app.vue')),
+    env: readIf(join(target, '.env')),
+  })
+}
+
+function printFindings(found) {
+  for (const d of found) {
+    out(`${d.level === 'error' ? red('✖ error') : yellow('▲ warn ')} ${d.message}`)
+    out()
+  }
+}
+
+async function init(positional, flags) {
+  const target = resolve(positional[0] ?? '.')
+  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.
+  const manifestPath = join(target, 'package.json')
+  const existingManifest = readIf(manifestPath)
+  if (existingManifest !== null) {
+    try {
+      JSON.parse(existingManifest)
+    } catch {
+      fail(`${manifestPath} is not valid JSON — fix it first; refusing to scaffold over a broken manifest.`)
+    }
+  }
+
+  let password = typeof flags.password === 'string' ? 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).`)
+  }
+
+  mkdirSync(target, { recursive: true })
+  const projectName = toPackageName(typeof flags.name === 'string' ? flags.name : basename(target))
+
+  out()
+  out(`${bold('Kestrel')} ${dim(`v${pkg.version}`)} — setting up ${bold(relative(process.cwd(), target) || '.')}`)
+  out()
+
+  if (password === undefined && !flags.yes && process.stdin.isTTY) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    try {
+      password = await promptPassword(rl, { warn: (m) => out(yellow(m)) })
+    } catch (err) {
+      rl.close()
+      if (err instanceof Cancelled) fail('cancelled')
+      throw err
+    }
+    rl.close()
+    out()
+  }
+
+  const vars = templateVars(projectName)
+  const created = []
+  const kept = []
+  const merged = []
+
+  for (const rel of walk(templateDir).sort()) {
+    const name = targetName(rel)
+    const dest = join(target, name)
+    const body = renderTemplate(readFileSync(join(templateDir, rel), 'utf8'), vars)
+    const existing = readIf(dest)
+
+    // A manifest is never overwritten, not even with --force: the caller most likely already ran
+    // `pnpm add`, and replacing their dependencies and version is not a scaffold, it is data loss.
+    if (name === 'package.json' && existing !== null) {
+      const { merged: result, added } = mergePackageJson(JSON.parse(existing), JSON.parse(body))
+      if (added.length) {
+        write(dest, `${JSON.stringify(result, null, 2)}\n`)
+        merged.push(`package.json ${dim(`(+ ${added.join(', ')})`)}`)
+      } else kept.push('package.json')
+      continue
+    }
+    if (existing !== null && !flags.force) {
+      kept.push(name)
+      continue
+    }
+    write(dest, body)
+    created.push(name)
+  }
+
+  // Seed from `.env.example` so the generated file keeps its per-key comments.
+  const envPath = join(target, '.env')
+  const hadEnv = existsSync(envPath)
+  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)
+  if (written.length) {
+    write(envPath, text, 0o600)
+    ;(hadEnv ? merged : created).push(`.env ${dim(`(${written.join(', ')})`)}`)
+  } else kept.push('.env')
+
+  const report = (label, items, paint) => {
+    for (const f of items) out(`  ${paint(label)} ${f}`)
+  }
+  report('created', created, green)
+  report('updated', merged, green)
+  report('kept   ', kept, dim)
+
+  // Existing files are kept, so init must never report success over a project that still can't serve /admin.
+  const remaining = inspect(target)
+  if (remaining.length) {
+    out()
+    out(bold('Still to fix:'))
+    out()
+    printFindings(remaining)
+  }
+
+  out()
+  out(bold('Next:'))
+  const rel = relative(process.cwd(), target)
+  if (rel) out(`  cd ${rel}`)
+  out('  pnpm install')
+  out('  pnpm dev')
+  out()
+  out(`  Admin: ${bold('http://localhost:3000/admin')}`)
+  out()
+  return remaining.some((d) => d.level === 'error') ? 1 : 0
+}
+
+function doctor(positional) {
+  const target = resolve(positional[0] ?? '.')
+  const found = inspect(target)
+
+  out()
+  if (!found.length) {
+    out(`${green('✔')} ${relative(process.cwd(), target) || '.'} looks like a working Kestrel project.`)
+    out()
+    return 0
+  }
+  printFindings(found)
+  return found.some((d) => d.level === 'error') ? 1 : 0
+}
+
+async function hashPasswordCommand(positional) {
+  let password = positional[0]
+  if (password === undefined) {
+    if (process.stdin.isTTY) {
+      const rl = createInterface({ input: process.stdin, output: process.stdout })
+      try {
+        password = await promptPassword(rl, { warn: (m) => out(yellow(m)) })
+      } catch (err) {
+        rl.close()
+        if (err instanceof Cancelled) fail('cancelled')
+        throw err
+      }
+      rl.close()
+    } else password = await readStdin()
+  }
+  if (!password) fail('no password given')
+  out(hashPassword(password))
+}
+
+function help() {
+  out(`
+${bold('kestrel')} ${dim(`v${pkg.version}`)}
+
+  ${bold('kestrel init')} [dir]        scaffold a runnable Kestrel project (default: the current directory)
+  ${bold('kestrel doctor')} [dir]      check a project for the things that silently break /admin
+  ${bold('kestrel hash-password')} [p] print a KESTREL_ADMIN_PASSWORD_HASH value
+  ${bold('kestrel secret')}            print a KESTREL_SESSION_SECRET value
+
+${bold('init flags')}
+  --name <name>       package name (default: the directory name, slugified)
+  --password <pw>     set 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)
+
+${dim('Existing files are kept and re-running init is safe. To create a NEW project: pnpm create kestrel')}
+`)
+}
+
+const { flags, positional } = parseArgs(process.argv.slice(2), ['yes', 'force', 'help', 'version'])
+const command = positional.shift()
+
+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)
+else if (command === 'doctor') process.exitCode = doctor(positional)
+else if (command === 'hash-password') await hashPasswordCommand(positional)
+else if (command === 'secret') out(sessionSecret())
+else fail(`unknown command "${command}" — run \`kestrel help\`.`)