@michaelthielemann/kestrel 1.2.1 → 1.4.0

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>

package/templates/starter/_env.example

@@ -0,0 +1,17 @@
+# Auth/session is env-only — secrets never belong in a committed config file. `.env.example` is the
+# committed copy of this template; `.env` holds the real values and is gitignored.
+#
+# The two below are read per request. Every other KESTREL_* var is read once when the app is BUILT
+# (dev start / build / generate) and frozen into runtimeConfig — see docs/configuration.md.
+
+# Session signing secret, >= 32 bytes. Required in production. Generate: kestrel secret
+KESTREL_SESSION_SECRET=
+
+# Admin password hash. Without it /admin renders but sign-in answers 503. Generate: kestrel hash-password
+KESTREL_ADMIN_PASSWORD_HASH=
+
+# Drops the __Host- cookie prefix and the Secure flag. Plain-HTTP localhost ONLY; rejected in production.
+KESTREL_SECURE_COOKIES=false
+
+# Optional: session lifetime in seconds (default 604800 = 7 days)
+# KESTREL_SESSION_MAX_AGE=604800

package/templates/starter/_gitignore

@@ -0,0 +1,26 @@
+# Dependencies
+node_modules
+
+# Nuxt / Nitro build output
+.nuxt
+.nitro
+.cache
+.output
+dist
+
+# Secrets
+.env
+.env.*
+!.env.example
+
+# Runtime database, uploads and published output
+.data
+*.sqlite
+*.sqlite-shm
+*.sqlite-wal
+
+# Logs
+*.log
+
+# OS / editor
+.DS_Store

package/templates/starter/_package.json

@@ -0,0 +1,22 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "nuxt dev",
+    "build": "nuxt build",
+    "preview": "nuxt preview",
+    "generate": "nuxt generate",
+    "typecheck": "nuxt prepare && nuxt typecheck && tsc -p .nuxt/tsconfig.server.json --noEmit",
+    "hash-password": "kestrel hash-password",
+    "doctor": "kestrel doctor"
+  },
+  "dependencies": {
+    "@michaelthielemann/kestrel": "{{version}}"
+  },
+  "devDependencies": {
+    "nuxt": "{{nuxtVersion}}",
+    "typescript": "{{typescriptVersion}}",
+    "vue-tsc": "{{vueTscVersion}}"
+  }
+}

package/templates/starter/app/app.vue

@@ -0,0 +1,7 @@
+<template>
+  <!-- Both wrappers are load-bearing: without <NuxtPage /> no route renders, without <NuxtLayout /> the
+       admin loses its shell. Delete this file to fall back to the one Kestrel ships. -->
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>

package/templates/starter/app/blocks/Prose.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+// One SFC is one block type: the filename names it, defineProps is its schema. Add a sibling to add one.
+defineProps({
+  body: richtextField({ required: true }),
+})
+defineBlock({ label: { en: 'Prose' }, icon: 'file-text' })
+</script>
+
+<template>
+  <!-- richtext is sanitized server-side on write -->
+  <div class="block-prose" v-html="body" />
+</template>

package/templates/starter/app/layouts/default.vue

@@ -0,0 +1,6 @@
+<template>
+  <!-- The public site's frame. The admin uses its own layout and is unaffected by anything here. -->
+  <main>
+    <slot />
+  </main>
+</template>

package/templates/starter/nuxt.config.ts

@@ -0,0 +1,20 @@
+export default defineNuxtConfig({
+  compatibilityDate: '2026-06-02',
+  future: { compatibilityVersion: 4 },
+  // This one line composes the whole CMS. Opt-in extension layers go after it.
+  extends: ['@michaelthielemann/kestrel'],
+  // Not inherited from an extended layer, so it has to be repeated here.
+  typescript: { tsConfig: { compilerOptions: { noUncheckedIndexedAccess: false } } },
+  nitro: { typescript: { tsConfig: { compilerOptions: { noUncheckedIndexedAccess: false } } } },
+  // Auth/session is env-only, see `.env`. Every key here is optional.
+  kestrel: {
+    db: '.data/db.sqlite',
+    // Baked into canonical URLs, hreflang, sitemap.xml and llms.txt at build time. Set it to the public
+    // origin before the first real deploy — or leave it to KESTREL_SITE_URL per environment.
+    siteUrl: 'http://localhost:3000',
+    siteName: '{{name}}',
+    media: { uploadDir: '.data/uploads' },
+    // locales: ['en', 'de'],
+    // collections: { pages: false },
+  },
+})

package/templates/starter/pnpm-workspace.yaml

@@ -0,0 +1,8 @@
+# pnpm blocks dependency build scripts unless they are listed here, and Kestrel's SQLite driver and image
+# pipeline are native — without this `pnpm install` completes but the app cannot start. Delete this file
+# if you use npm or yarn. (`pnpm.onlyBuiltDependencies` in package.json is silently ignored on pnpm 11.)
+allowBuilds:
+  '@parcel/watcher': true
+  better-sqlite3: true
+  esbuild: true
+  sharp: true

package/templates/starter/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "./.nuxt/tsconfig.json"
+}