@michaelthielemann/kestrel 1.2.1 → 1.3.0

package/scripts/copy-create-payload.mjs

@@ -0,0 +1,52 @@
+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 })
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  if (manifest['//engine']) {
+    delete manifest['//engine']
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+  }
+}
+
+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))
+  }
+
+  // Stamped so the scaffolded manifest pins the ranges the engine actually resolves.
+  manifest['//engine'] = {
+    nuxt: engine.dependencies?.nuxt,
+    typescript: engine.dependencies?.typescript,
+    'vue-tsc': engine.devDependencies?.['vue-tsc'],
+  }
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, 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\`.`)

package/scripts/lib/cli.mjs

@@ -0,0 +1,114 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, chmodSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+
+export const MIN_PASSWORD_LENGTH = 8
+
+/**
+ * `booleans` never consume the following token, so `init --force my-site` keeps `my-site` as the target
+ * rather than scaffolding over the current directory. `--` ends flag parsing.
+ */
+export function parseArgs(argv, booleans = []) {
+  const isBoolean = new Set(booleans)
+  const flags = {}
+  const positional = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--') {
+      positional.push(...argv.slice(i + 1))
+      break
+    }
+    if (a === '-h') {
+      flags.help = true
+      continue
+    }
+    if (a === '-v') {
+      flags.version = true
+      continue
+    }
+    if (!a.startsWith('--')) {
+      positional.push(a)
+      continue
+    }
+    const [key, inline] = a.slice(2).split(/=(.*)/s)
+    if (inline !== undefined) flags[key] = inline
+    else if (!isBoolean.has(key) && i + 1 < argv.length && !argv[i + 1].startsWith('-')) flags[key] = argv[++i]
+    else flags[key] = true
+  }
+  return { flags, positional }
+}
+
+export function makePaint(stream = process.stdout) {
+  const on = stream.isTTY && !process.env.NO_COLOR
+  const wrap = (code) => (s) => (on ? `\u001b[${code}m${s}\u001b[0m` : s)
+  return { dim: wrap(2), bold: wrap(1), red: wrap(31), yellow: wrap(33), green: wrap(32) }
+}
+
+export const out = (s = '') => process.stdout.write(`${s}\n`)
+
+export const readIf = (file) => (existsSync(file) ? readFileSync(file, 'utf8') : null)
+
+/** `mode` is applied even when the file already exists, which `writeFileSync` alone does not do. */
+export function write(file, content, mode) {
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, content, mode === undefined ? undefined : { mode })
+  if (mode !== undefined) chmodSync(file, mode)
+}
+
+/** Every file under `dir`, as `/`-separated paths relative to it. */
+export function walk(dir, base = dir) {
+  const found = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) found.push(...walk(full, base))
+    else found.push(relative(base, full).split('\\').join('/'))
+  }
+  return found
+}
+
+/**
+ * Reads a line with the echo suppressed. readline echoes before we see the data event, so the fix is to
+ * repaint the prompt over whatever was written — unconditionally, because a pasted secret arrives as one
+ * chunk that ends in a newline and would otherwise be left on screen and in the scrollback.
+ */
+async function askHidden(rl, question) {
+  const repaint = () => process.stdout.write(`\u001b[2K\u001b[200D${question}`)
+  process.stdin.on('data', repaint)
+  try {
+    return (await rl.question(question)).trim()
+  } finally {
+    process.stdin.off('data', repaint)
+    repaint()
+    process.stdout.write('\n')
+  }
+}
+
+export class Cancelled extends Error {}
+
+/** Throws `Cancelled` on Ctrl-C / Ctrl-D so a caller can exit cleanly instead of on an AbortError stack. */
+export async function promptPassword(rl, { warn = out } = {}) {
+  for (;;) {
+    let first
+    try {
+      first = await askHidden(rl, 'Admin password: ')
+      if (first.length < MIN_PASSWORD_LENGTH) {
+        warn(`  at least ${MIN_PASSWORD_LENGTH} characters, please`)
+        continue
+      }
+      if (first !== (await askHidden(rl, 'Repeat password: '))) {
+        warn('  the two entries differ — try again')
+        continue
+      }
+    } catch (err) {
+      throw err?.code === 'ABORT_ERR' ? new Cancelled() : err
+    }
+    if (first === undefined) throw new Cancelled()
+    return first
+  }
+}
+
+/** All of stdin as a string; `''` at EOF, which the callers turn into a clean error. */
+export async function readStdin() {
+  let text = ''
+  for await (const chunk of process.stdin) text += chunk
+  return text.split('\n')[0].trim()
+}

package/scripts/lib/password.mjs

@@ -0,0 +1,19 @@
+import { scryptSync, randomBytes } from 'node:crypto'
+
+// Must match what layers/auth parses back out. ADR-0001 covers the parameter choice.
+const N = 2 ** 17
+const r = 8
+const p = 1
+const KEYLEN = 64
+const MAXMEM = 256 * 1024 * 1024
+
+/** `scrypt$N$r$p$salt$hash`, the `KESTREL_ADMIN_PASSWORD_HASH` format. */
+export function hashPassword(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')}`
+}
+
+export function sessionSecret() {
+  return randomBytes(32).toString('base64url')
+}

package/scripts/lib/scaffold.mjs

@@ -0,0 +1,174 @@
+export const PACKAGE_NAME = '@michaelthielemann/kestrel'
+
+// Template dotfiles are `_`-prefixed because npm strips a literal `.gitignore` from a tarball. ADR-0005.
+const RENAMES = {
+  _gitignore: '.gitignore',
+  '_env.example': '.env.example',
+  '_package.json': 'package.json',
+}
+
+export function targetName(rel) {
+  const parts = rel.split('/')
+  const base = parts[parts.length - 1]
+  parts[parts.length - 1] = RENAMES[base] ?? base
+  return parts.join('/')
+}
+
+/** An unknown placeholder is left as-is so a typo is visible rather than silently blank. */
+export function renderTemplate(src, vars) {
+  return src.replace(/\{\{(\w+)\}\}/g, (whole, key) => (key in vars ? String(vars[key]) : whole))
+}
+
+export function toPackageName(dirName) {
+  const slug = dirName
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^[-._]+|[-._]+$/g, '')
+  return slug || 'kestrel-site'
+}
+
+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.
+ * Returns the new text plus the keys that changed.
+ */
+export function mergeEnv(existing, entries) {
+  const pending = new Map(Object.entries(entries))
+  const lines = existing === '' ? [] : existing.split('\n')
+  const written = []
+
+  // A dotenv loader takes the LAST assignment of a key, so filling the first would leave the file
+  // reporting a value the app never sees.
+  const lastIndex = new Map()
+  lines.forEach((line, i) => {
+    const key = KEY_RE.exec(line)?.[1]
+    if (key) lastIndex.set(key, i)
+  })
+
+  const out = lines.map((line, i) => {
+    const key = KEY_RE.exec(line)?.[1]
+    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
+    written.push(key)
+    return `${key}=${value}`
+  })
+
+  if (pending.size) {
+    if (out.length && out[out.length - 1].trim() !== '') out.push('')
+    for (const [key, value] of pending) {
+      out.push(`${key}=${value}`)
+      written.push(key)
+    }
+    out.push('')
+  }
+
+  return { text: out.join('\n'), written }
+}
+
+const isObject = (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
+// CommonJS project outright. Only these top-level keys may be introduced, and each is reported.
+const TOP_LEVEL = ['name', 'private', 'type']
+
+/** Additive: the project's own values always win. Returns the manifest plus every key it introduced. */
+export function mergePackageJson(existing, template) {
+  const merged = { ...existing }
+  const added = []
+
+  for (const key of TOP_LEVEL) {
+    if (!(key in template) || key in existing) continue
+    merged[key] = template[key]
+    added.push(key)
+  }
+  for (const key of NESTED) {
+    if (!template[key]) continue
+    merged[key] = isObject(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}`)
+    }
+  }
+  return { merged, added }
+}
+
+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()
+export const usesComponent = (src, tag) => new RegExp(`<\\s*(${tag}|${kebab(tag)})[\\s/>]`, 'i').test(src)
+
+/**
+ * `kestrel doctor`, as a pure function of what was read; `null` means the file is absent.
+ * The `app.vue` rules mirror `layers/core/modules/kestrel/app-shell.ts`; a test pins the two together.
+ */
+export function diagnoseProject({ packageJson, nuxtConfig, appVue, env }) {
+  const found = []
+  const add = (level, message) => found.push({ level, message })
+
+  let manifest
+  if (packageJson !== null) {
+    try {
+      manifest = JSON.parse(packageJson)
+    } catch {
+      add('error', 'package.json is not valid JSON — nothing can read it, including pnpm.')
+    }
+  }
+
+  if (packageJson === null) {
+    add('error', 'no package.json — run this inside a project directory, or `kestrel init <dir>` to make one.')
+  } else if (manifest !== undefined) {
+    const deps = { ...manifest.dependencies, ...manifest.devDependencies }
+    if (!(PACKAGE_NAME in deps)) add('error', `${PACKAGE_NAME} is not a dependency — run \`pnpm add ${PACKAGE_NAME}\`.`)
+    if (!('nuxt' in deps)) {
+      add(
+        'error',
+        'nuxt is not a direct dependency. Kestrel depends on it, but a strict node_modules layout (pnpm) does not link a transitive package\'s `nuxt` binary, so `nuxt dev` will not resolve — run `pnpm add -D nuxt`.',
+      )
+    }
+    if (!manifest.scripts?.dev) add('warn', 'no `dev` script — add `"dev": "nuxt dev"` so `pnpm dev` works.')
+  }
+
+  if (nuxtConfig === null) {
+    add(
+      'error',
+      'no nuxt.config.ts. Installing the package does nothing on its own: Nuxt only loads Kestrel when the config extends it. Without this file every route, /admin included, serves the default Nuxt welcome page.',
+    )
+  } else if (!nuxtConfig.includes(PACKAGE_NAME)) {
+    add('error', `nuxt.config.ts does not extend ${PACKAGE_NAME} — add \`extends: ['${PACKAGE_NAME}']\`.`)
+  } else if (/extends\s*:\s*\[[^\]]*['"]\.\.[/\\]\.\./.test(nuxtConfig)) {
+    add(
+      'warn',
+      "a relative `extends` path of '../..' or deeper silently drops every Kestrel sub-layer (c12 treats it as a file, not a directory, because pathe reports its extension as '.'). Use the package name.",
+    )
+  }
+
+  if (appVue !== null) {
+    const src = withoutComments(appVue)
+    if (!usesComponent(src, 'NuxtPage')) {
+      add(
+        'error',
+        'app/app.vue renders no <NuxtPage />, so no route renders — including /admin. It shadows the one Kestrel ships. Delete it, or wrap <NuxtPage /> in <NuxtLayout>.',
+      )
+    } else if (!usesComponent(src, 'NuxtLayout')) {
+      add('warn', 'app/app.vue renders no <NuxtLayout />, so the admin loses its navigation shell.')
+    }
+  }
+
+  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()
+    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`.')
+    }
+    if (!value('KESTREL_SESSION_SECRET')) {
+      add('warn', 'KESTREL_SESSION_SECRET is unset — dev falls back to a random per-process secret (sessions drop on restart) and production refuses to boot.')
+    }
+  }
+
+  return found
+}

package/templates/starter/README.md

@@ -0,0 +1,65 @@
+# {{name}}
+
+A [Kestrel](https://github.com/MichaelThielemann/kestrel) site — a collection-driven CMS that renders
+published content to static HTML.
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Admin: <http://localhost:3000/admin> — sign in with the password you chose during `kestrel init`.
+Forgot it? `pnpm hash-password` prints a fresh hash for `KESTREL_ADMIN_PASSWORD_HASH` in `.env`.
+
+## What is here
+
+| Path | What it does |
+| --- | --- |
+| `nuxt.config.ts` | Composes Kestrel (`extends`) and holds every non-secret setting under `kestrel: {}` |
+| `.env` | Session secret + admin password hash. **Never commit it** — `.env.example` is the committed copy |
+| `app/app.vue` | The app root. Keep `<NuxtLayout>` and `<NuxtPage />` or the admin stops rendering |
+| `app/layouts/default.vue` | Your public site frame — header, nav, footer |
+| `app/blocks/Prose.vue` | One block type for the page builder: schema and display in a single file |
+| `.data/` | The SQLite database, uploads and published output. Gitignored |
+
+## Add a collection
+
+Drop a file in `server/collections/`; the table is created on the next dev start and the collection
+shows up in the admin. Nothing to register.
+
+```ts
+// server/collections/posts.ts
+export default defineCollection({
+  name: 'posts',
+  mode: 'multi',
+  pageLike: true,          // gives records a `path` so they render to static HTML
+  status: true,            // draft / published
+  seo: true,
+  blocks: { enabled: true },
+  fields: { title: { type: 'text', required: true } },
+})
+```
+
+## Publish
+
+Run `pnpm dev` at least once first: the database schema is derived from your collections and created on
+a dev boot, and a production build never touches it. Generating against a database that does not exist
+yet succeeds but emits an empty site plus `no such table` errors.
+
+There are two ways to get static files out, and this project has **both** enabled:
+
+- **One-shot:** `pnpm generate` renders everything published into `.output/public/`.
+- **Incremental (the default at runtime):** a production run (`pnpm build && pnpm preview`) publishes on
+  boot and re-renders only the pages each content write affects, into `.data/published/`. Turn it off with
+  `kestrel: { output: { auto: false } }` in `nuxt.config.ts` if you only want the one-shot flow.
+
+Either way, serve the resulting directory from any static host. The editing origin is not meant to be
+public. Set `siteUrl` in `nuxt.config.ts` to the real public origin first — it is baked into canonical
+URLs, `sitemap.xml` and `llms.txt` at build time.
+
+## Health check
+
+`pnpm doctor` checks this project for the things that silently break a Kestrel site: a missing
+`extends`, an `app.vue` that renders no pages, unset auth env.
+
+Full documentation: <https://github.com/MichaelThielemann/kestrel#documentation>