@michaelthielemann/kestrel 3.0.1 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michaelthielemann/kestrel",
-  "version": "3.0.1",
+  "version": "4.0.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>",
@@ -24,7 +24,6 @@
   "bin": {
     "kestrel": "./scripts/kestrel.mjs"
   },
-  "packageManager": "pnpm@11.9.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -45,21 +44,6 @@
     "node": ">=22.12.0"
   },
   "//lint": "The root eslint.config.mjs imports the generated playground/.nuxt/eslint.config.mjs (Nuxt-aware: auto-import globals for every layer + extension) — `nuxt prepare` must run first or that import 404s on a fresh checkout. Cheap on a warm .nuxt cache, so it's chained rather than a separate step.",
-  "scripts": {
-    "dev": "nuxt dev",
-    "build": "nuxt build",
-    "preview": "nuxt preview",
-    "generate": "nuxt generate",
-    "db:generate": "drizzle-kit generate",
-    "db:migrate": "drizzle-kit migrate",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:e2e": "vitest run --config vitest.e2e.config.ts",
-    "test:nuxt": "vitest run --config vitest.nuxt.config.ts",
-    "typecheck": "node scripts/typecheck.mjs",
-    "lint": "nuxt prepare playground && eslint .",
-    "hash-password": "node scripts/hash-password.mjs"
-  },
   "dependencies": {
     "@babel/parser": "^7.29.8",
     "@internationalized/date": "^3.12.3",
@@ -78,10 +62,12 @@
     "dompurify": "^3.4.13",
     "drizzle-orm": "^0.45.2",
     "drizzle-zod": "^0.8.3",
+    "effect": "~3.22.1",
     "exifr": "^7.1.3",
     "file-type": "^22.0.1",
     "jsdom": "^29.1.1",
     "nanoid": "^5.1.16",
+    "nitropack": "^2.13.4",
     "nuxt": "^4.5.2",
     "reka-ui": "^2.10.1",
     "sanitize-html": "^2.17.6",
@@ -89,7 +75,17 @@
     "sharp": "^0.35.3",
     "thumbhash": "^0.1.1",
     "typescript": "^6.0.3",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "@michaelthielemann/kestrel-access": "0.1.0",
+    "@michaelthielemann/kestrel-auth": "0.1.0",
+    "@michaelthielemann/kestrel-core": "0.1.0",
+    "@michaelthielemann/kestrel-contracts": "0.1.0",
+    "@michaelthielemann/kestrel-collections": "0.1.0",
+    "@michaelthielemann/kestrel-delivery-live": "0.1.0",
+    "@michaelthielemann/kestrel-delivery-static": "0.1.0",
+    "@michaelthielemann/kestrel-fields": "0.1.0",
+    "@michaelthielemann/kestrel-media": "0.1.0",
+    "@michaelthielemann/kestrel-publishing": "0.1.0"
   },
   "//peers": "Framework singletons the layer sources import by bare specifier. Peers, not dependencies: a second copy breaks identity (two Vue instances; an h3 v1 `createError` handed to an h3 v2 error handler, which surfaces our 400/404/409 as bare 500s). All optional, because kestrel's own `nuxt` dependency already supplies them transitively — the entry pins identity where a copy exists rather than demanding one, and a required peer would ERESOLVE-fail npm installs on any Nuxt whose bundled range we did not anticipate. Each is also a devDependency so this repo resolves it without auto-install-peers writing a phantom root dependency into the lockfile.",
   "peerDependencies": {
@@ -113,20 +109,58 @@
     }
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@fast-check/vitest": "^0.4.1",
+    "@microsoft/api-extractor": "^7.58.13",
     "@nuxt/eslint": "^1.9.0",
     "@nuxt/kit": "^4.5.2",
     "@nuxt/test-utils": "^4.1.0",
+    "@stryker-mutator/core": "^10.0.0",
+    "@stryker-mutator/vitest-runner": "^10.0.0",
     "@vitejs/plugin-vue": "^6.0.8",
+    "@vitest/coverage-v8": "4.1.10",
     "@vue/test-utils": "^2.4.11",
     "drizzle-kit": "^0.31.10",
     "eslint": "^9.39.1",
+    "eslint-plugin-boundaries": "^7.2.0",
+    "eslint-plugin-jsdoc": "^64.2.1",
+    "eslint-plugin-tsdoc": "^0.5.2",
     "eslint-plugin-vuejs-accessibility": "^2.4.1",
+    "fast-check": "^4.9.0",
     "h3": "^1.15.11",
     "happy-dom": "^20.11.2",
     "playwright-core": "^1.62.1",
+    "publint": "^0.3.24",
+    "typedoc": "^0.28.20",
     "vitest": "^4.1.10",
+    "vitest-openapi": "^1.0.3",
     "vue": "3.5.35",
     "vue-router": "^5.2.0",
     "vue-tsc": "^3.3.9"
+  },
+  "scripts": {
+    "dev": "nuxt dev",
+    "build": "nuxt build",
+    "build:packages": "pnpm -F @michaelthielemann/kestrel-contracts build && pnpm -F @michaelthielemann/kestrel-core build && pnpm -F @michaelthielemann/kestrel-fields build && pnpm -F @michaelthielemann/kestrel-auth build && pnpm -F @michaelthielemann/kestrel-access build && pnpm -F @michaelthielemann/kestrel-media build && pnpm -F @michaelthielemann/kestrel-collections build && pnpm -F @michaelthielemann/kestrel-publishing build && pnpm -F @michaelthielemann/kestrel-delivery-live build && pnpm -F @michaelthielemann/kestrel-delivery-static build",
+    "preview": "nuxt preview",
+    "generate": "nuxt generate",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "test": "vitest run",
+    "test:coverage": "node scripts/coverage-all.mjs",
+    "test:watch": "vitest",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:nuxt": "vitest run --config vitest.nuxt.config.ts",
+    "test:packages": "pnpm --filter \"@michaelthielemann/kestrel-*\" -r test",
+    "typecheck": "node scripts/typecheck.mjs",
+    "typecheck:packages": "pnpm --filter \"@michaelthielemann/kestrel-*\" -r typecheck",
+    "lint": "nuxt prepare playground && eslint .",
+    "docs:api": "nuxt prepare playground && typedoc",
+    "api:check": "pnpm -F @michaelthielemann/kestrel-contracts build && api-extractor run -c packages/kestrel-contracts/api-extractor.json && pnpm -F @michaelthielemann/kestrel-core build && api-extractor run -c packages/kestrel-core/api-extractor.json && api-extractor run -c packages/kestrel-core/api-extractor.client.json && pnpm -F @michaelthielemann/kestrel-fields build && api-extractor run -c packages/kestrel-fields/api-extractor.json && api-extractor run -c packages/kestrel-fields/api-extractor.client.json && pnpm -F @michaelthielemann/kestrel-auth build && api-extractor run -c packages/kestrel-auth/api-extractor.json && pnpm -F @michaelthielemann/kestrel-access build && api-extractor run -c packages/kestrel-access/api-extractor.json && pnpm -F @michaelthielemann/kestrel-media build && api-extractor run -c packages/kestrel-media/api-extractor.json && pnpm -F @michaelthielemann/kestrel-collections build && api-extractor run -c packages/kestrel-collections/api-extractor.json && pnpm -F @michaelthielemann/kestrel-publishing build && api-extractor run -c packages/kestrel-publishing/api-extractor.json && pnpm -F @michaelthielemann/kestrel-delivery-live build && api-extractor run -c packages/kestrel-delivery-live/api-extractor.json && pnpm -F @michaelthielemann/kestrel-delivery-static build && api-extractor run -c packages/kestrel-delivery-static/api-extractor.json",
+    "api:update": "pnpm -F @michaelthielemann/kestrel-contracts build && api-extractor run --local -c packages/kestrel-contracts/api-extractor.json && pnpm -F @michaelthielemann/kestrel-core build && api-extractor run --local -c packages/kestrel-core/api-extractor.json && api-extractor run --local -c packages/kestrel-core/api-extractor.client.json && pnpm -F @michaelthielemann/kestrel-fields build && api-extractor run --local -c packages/kestrel-fields/api-extractor.json && api-extractor run --local -c packages/kestrel-fields/api-extractor.client.json && pnpm -F @michaelthielemann/kestrel-auth build && api-extractor run --local -c packages/kestrel-auth/api-extractor.json && pnpm -F @michaelthielemann/kestrel-access build && api-extractor run --local -c packages/kestrel-access/api-extractor.json && pnpm -F @michaelthielemann/kestrel-media build && api-extractor run --local -c packages/kestrel-media/api-extractor.json && pnpm -F @michaelthielemann/kestrel-collections build && api-extractor run --local -c packages/kestrel-collections/api-extractor.json && pnpm -F @michaelthielemann/kestrel-publishing build && api-extractor run --local -c packages/kestrel-publishing/api-extractor.json && pnpm -F @michaelthielemann/kestrel-delivery-live build && api-extractor run --local -c packages/kestrel-delivery-live/api-extractor.json && pnpm -F @michaelthielemann/kestrel-delivery-static build && api-extractor run --local -c packages/kestrel-delivery-static/api-extractor.json",
+    "pkg:lint": "publint . && pnpm -F @michaelthielemann/kestrel-contracts build && publint packages/kestrel-contracts && attw --pack packages/kestrel-contracts --profile esm-only && pnpm -F @michaelthielemann/kestrel-core build && publint packages/kestrel-core && attw --pack packages/kestrel-core --profile esm-only && pnpm -F @michaelthielemann/kestrel-fields build && publint packages/kestrel-fields && attw --pack packages/kestrel-fields --profile esm-only && pnpm -F @michaelthielemann/kestrel-auth build && publint packages/kestrel-auth && attw --pack packages/kestrel-auth --profile esm-only && pnpm -F @michaelthielemann/kestrel-access build && publint packages/kestrel-access && attw --pack packages/kestrel-access --profile esm-only && pnpm -F @michaelthielemann/kestrel-media build && publint packages/kestrel-media && attw --pack packages/kestrel-media --profile esm-only && pnpm -F @michaelthielemann/kestrel-collections build && publint packages/kestrel-collections && attw --pack packages/kestrel-collections --profile esm-only && pnpm -F @michaelthielemann/kestrel-publishing build && publint packages/kestrel-publishing && attw --pack packages/kestrel-publishing --profile esm-only && pnpm -F @michaelthielemann/kestrel-delivery-live build && publint packages/kestrel-delivery-live && attw --pack packages/kestrel-delivery-live --profile esm-only && pnpm -F @michaelthielemann/kestrel-delivery-static build && publint packages/kestrel-delivery-static && attw --pack packages/kestrel-delivery-static --profile esm-only",
+    "ci:consumer-template": "node scripts/consumer-template-ci.mjs",
+    "dashboard": "npx tsx scripts/dashboard.mjs",
+    "hash-password": "node scripts/hash-password.mjs"
   }
-}
+}

package/scripts/consumer-template-ci.mjs

@@ -0,0 +1,157 @@
+// The ONLY real package-consumption test. Every earlier gate (api:check, pkg:lint) inspects one
+// package's own tarball in isolation; this script is the one that scaffolds an actual consumer from
+// templates/starter (via create-kestrel's real CLI), packs the engine + every @michaelthielemann/kestrel-* package the way
+// `npm publish` would, installs them into that consumer with a real `npm install` (no workspace protocol,
+// no symlinks back into this repo), builds it, boots the production server, and hits it over real HTTP.
+//
+// Local: `pnpm ci:consumer-template`. CI: the `consumer-template` job in .github/workflows/ci.yml.
+import { execFileSync, spawn } from 'node:child_process'
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { setTimeout as sleep } from 'node:timers/promises'
+
+const root = process.cwd()
+const log = (msg) => console.log(`[consumer-template-ci] ${msg}`)
+const run = (cmd, args, opts = {}) => execFileSync(cmd, args, { stdio: 'inherit', ...opts })
+
+// @michaelthielemann/kestrel-* in the order `pnpm --filter "@michaelthielemann/kestrel-*" -r exec` resolves them (a real topological walk of
+// the workspace graph, not a hand guess) — mirrors the publish order in .github/workflows/release.yml.
+const PACKAGES = ['contracts', 'core', 'auth', 'access', 'fields', 'collections', 'media', 'publishing', 'delivery-live', 'delivery-static']
+
+const work = mkdtempSync(join(tmpdir(), 'kestrel-consumer-ci-'))
+const tarballDir = join(work, 'tarballs')
+const consumerDir = join(work, 'site')
+mkdirSync(tarballDir, { recursive: true })
+log(`work dir: ${work}`)
+
+let server
+try {
+  log('building @michaelthielemann/kestrel-* packages (dist/ must exist before pnpm pack)')
+  run('pnpm', ['--filter', '@michaelthielemann/kestrel-*', '-r', 'build'], { cwd: root })
+
+  log('packing the engine + every @michaelthielemann/kestrel-* package as npm publish would')
+  const tarball = {}
+  for (const dir of ['.', ...PACKAGES.map((n) => `packages/kestrel-${n}`)]) {
+    const out = execFileSync('pnpm', ['pack', '--pack-destination', tarballDir], { cwd: join(root, dir) }).toString().trim()
+    const file = out.split('\n').pop().trim()
+    const name = JSON.parse(readFileSync(join(root, dir, 'package.json'), 'utf8')).name
+    tarball[name] = file
+    log(`  ${name} -> ${file}`)
+  }
+
+  log('scaffolding a consumer from templates/starter via the real create-kestrel CLI')
+  const password = 'consumer-ci-password'
+  run('node', [join(root, 'packages/create-kestrel/index.mjs'), consumerDir, '--yes', '--password', password], { cwd: work })
+
+  log('pointing the scaffolded package.json at the packed tarballs (no registry, no workspace protocol)')
+  const pkgPath = join(consumerDir, 'package.json')
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+  pkg.dependencies['@michaelthielemann/kestrel'] = `file:${tarball['@michaelthielemann/kestrel']}`
+  // npm's `overrides` redirects a dependency AT ANY DEPTH — the engine tarball's own manifest declares
+  // "@michaelthielemann/kestrel-core": "0.1.0" etc. (pnpm pack already rewrote the workspace:* protocol to that real
+  // version), which would otherwise 404 against the real registry since these packages are not published
+  // yet in this checkout's tag. This is what actually forces npm's resolver to read each package's real
+  // `exports` map / `main` / `types` from a standalone tarball, the same way a real end user's install
+  // would — not a symlink into this repo's own packages/*/src.
+  pkg.overrides = Object.fromEntries(PACKAGES.map((n) => [`@michaelthielemann/kestrel-${n}`, `file:${tarball[`@michaelthielemann/kestrel-${n}`]}`]))
+  writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
+
+  // The runner's ambient npm (10.9.8 as of this writing) hits a real npm/arborist bug resolving nuxt's
+  // large optional-peer set (`TypeError: Cannot read properties of null (reading 'edgesOut')`, inside
+  // `#loadPeerSet`) — reproduced directly, unrelated to anything this script does. npm >= 11 does not
+  // have it. `npx --yes npm@11` sidesteps needing a global npm upgrade (which needs root the runner may
+  // not have) while still using real npm, not pnpm.
+  log('npm install (real npm 11 via npx — the most representative simulation of an actual end user)')
+  run('npx', ['--yes', 'npm@11', 'install'], { cwd: consumerDir })
+
+  log('verifying no @michaelthielemann/kestrel-* dependency resolved back into this repo (would prove nothing)')
+  for (const n of PACKAGES) {
+    let resolved = ''
+    try {
+      resolved = execFileSync('npm', ['ls', `@michaelthielemann/kestrel-${n}`, '--json'], { cwd: consumerDir }).toString()
+    } catch (err) {
+      // `npm ls` exits non-zero on a peer-dep mismatch warning even when the tree itself resolved fine;
+      // its stdout (on the error object) still carries the real tree, which is what matters here.
+      resolved = err.stdout?.toString() ?? ''
+    }
+    if (resolved.includes(root)) throw new Error(`@michaelthielemann/kestrel-${n} resolved into ${root} — the override did not take effect`)
+  }
+
+  log('reading the .env create-kestrel wrote (session secret + admin password hash)')
+  const env = Object.fromEntries(
+    readFileSync(join(consumerDir, '.env'), 'utf8')
+      .split('\n')
+      .map((l) => /^([A-Z][A-Z0-9_]*)=(.*)$/.exec(l))
+      .filter(Boolean)
+      .map((m) => [m[1], m[2]]),
+  )
+  // KESTREL_SECURE_COOKIES=false is what create-kestrel writes for a brand-new site (local http dev) —
+  // the app itself refuses it under a production boot ("KESTREL_SECURE_COOKIES=false is not allowed in
+  // production"), which is the correct, secure-by-default behavior, not a bug this script should route
+  // around by keeping the flag. Unset it; the production default is secure.
+  delete env.KESTREL_SECURE_COOKIES
+
+  const devPort = 41822
+  log('nuxt dev (brief boot, then kill) — schema auto-syncs additively at dev boot; a production boot never touches it (by design), so this is what a real `pnpm dev` first run also does')
+  const dev = spawn('npx', ['nuxt', 'dev', '--port', String(devPort)], {
+    cwd: consumerDir,
+    env: { ...process.env, ...env },
+    stdio: 'inherit',
+  })
+  try {
+    await waitForServer(`http://localhost:${devPort}/robots.txt`, 60000)
+  } finally {
+    dev.kill()
+    await sleep(1000) // let the dev Nitro process release the sqlite file before the production build reopens it
+  }
+
+  log('nuxt build (production) — the real exports-map/deps resolution surface, not a dev-mode shortcut')
+  run('npx', ['nuxt', 'build'], { cwd: consumerDir, env: { ...process.env, ...env } })
+
+  log('booting the built server and hitting it over real HTTP')
+  const port = 41823
+  server = spawn('node', [join(consumerDir, '.output/server/index.mjs')], {
+    cwd: consumerDir,
+    env: { ...process.env, ...env, PORT: String(port), NITRO_PORT: String(port) },
+    stdio: 'inherit',
+  })
+  await waitForServer(`http://localhost:${port}/robots.txt`, 30000)
+
+  const checks = [
+    ['GET /robots.txt', `http://localhost:${port}/robots.txt`, 200],
+    ['GET /sitemap.xml', `http://localhost:${port}/sitemap.xml`, 200],
+    ['GET /admin (login page, SPA shell)', `http://localhost:${port}/admin`, 200],
+  ]
+  for (const [label, url, wantStatus] of checks) {
+    const res = await fetch(url)
+    if (res.status !== wantStatus) throw new Error(`${label} -> ${res.status}, expected ${wantStatus}`)
+    log(`  ${label} -> ${res.status} OK`)
+  }
+
+  const loginRes = await fetch(`http://localhost:${port}/api/login`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ password }),
+  })
+  if (loginRes.status !== 200) throw new Error(`POST /api/login -> ${loginRes.status}, expected 200 (the packed admin auth stack did not resolve)`)
+  log('  POST /api/login -> 200 OK (the packed @michaelthielemann/kestrel-auth + @michaelthielemann/kestrel-access stack authenticates for real)')
+
+  log('PASS — a real npm install of the packed engine + packages boots and serves under production, and login round-trips through the packed auth stack.')
+} finally {
+  server?.kill()
+  if (!process.env.KEEP_CONSUMER_TEMPLATE_CI_WORKDIR) rmSync(work, { recursive: true, force: true })
+  else log(`KEEP_CONSUMER_TEMPLATE_CI_WORKDIR set — leaving ${work} in place`)
+}
+
+async function waitForServer(url, timeoutMs) {
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    try {
+      const res = await fetch(url)
+      if (res.status) return
+    } catch { /* not up yet */ }
+    if (Date.now() > deadline) throw new Error(`server did not come up at ${url} within ${timeoutMs}ms`)
+    await sleep(250)
+  }
+}

package/scripts/coverage-all.mjs

@@ -0,0 +1,163 @@
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const VITEST_BIN = path.join(ROOT, 'node_modules/.bin/vitest')
+const PARTS_DIR = path.join(ROOT, 'reports/coverage/.parts')
+const OUT_DIR = path.join(ROOT, 'reports/coverage')
+
+function sameKeys(a, b) {
+  const ka = Object.keys(a)
+  const kb = Object.keys(b)
+  if (ka.length !== kb.length) return false
+  const setB = new Set(kb)
+  return ka.every((k) => setB.has(k))
+}
+
+function mapsAgree(a, b) {
+  return sameKeys(a.statementMap, b.statementMap) && sameKeys(a.fnMap, b.fnMap) && sameKeys(a.branchMap, b.branchMap)
+}
+
+function countExecutedFunctions(entry) {
+  return Object.values(entry.f).filter((n) => n > 0).length
+}
+
+function cloneEntry(entry) {
+  return structuredClone(entry)
+}
+
+function sumCounters(a, b) {
+  const out = {}
+  for (const k of Object.keys(a)) out[k] = a[k] + (b[k] ?? 0)
+  return out
+}
+
+function sumBranches(a, b) {
+  const out = {}
+  for (const k of Object.keys(a)) {
+    const branchA = a[k]
+    const branchB = b[k] ?? []
+    out[k] = branchA.map((count, i) => count + (branchB[i] ?? 0))
+  }
+  return out
+}
+
+// Istanbul JSON is keyed by absolute file path; the same path can show up in several parts
+// (a package run and the root run both touching a shared file). When their instrumentation
+// maps agree, counters are additive. When they disagree, the maps describe different
+// transforms of the file — summing them would misattribute counts to the wrong statements/
+// functions, so the richer entry wins outright and the conflict is reported instead of hidden.
+export function mergeCoverage(parts, conflicts = []) {
+  const merged = {}
+  for (const part of parts) {
+    for (const [filePath, entry] of Object.entries(part)) {
+      const existing = merged[filePath]
+      if (!existing) {
+        merged[filePath] = cloneEntry(entry)
+        continue
+      }
+      if (mapsAgree(existing, entry)) {
+        merged[filePath] = {
+          ...existing,
+          s: sumCounters(existing.s, entry.s),
+          f: sumCounters(existing.f, entry.f),
+          b: sumBranches(existing.b, entry.b),
+        }
+      } else {
+        if (countExecutedFunctions(entry) > countExecutedFunctions(existing)) {
+          merged[filePath] = cloneEntry(entry)
+        }
+        conflicts.push(filePath)
+      }
+    }
+  }
+  return merged
+}
+
+function readCoverage(dir) {
+  const file = path.join(dir, 'coverage-final.json')
+  if (!fs.existsSync(file)) return null
+  return JSON.parse(fs.readFileSync(file, 'utf8'))
+}
+
+function countFiles(coverage) {
+  return coverage ? Object.keys(coverage).length : 0
+}
+
+function countFunctionsTotal(coverage) {
+  if (!coverage) return 0
+  let total = 0
+  for (const entry of Object.values(coverage)) total += countExecutedFunctions(entry)
+  return total
+}
+
+function discoverPackageSuites() {
+  const packagesDir = path.join(ROOT, 'packages')
+  if (!fs.existsSync(packagesDir)) return []
+  return fs
+    .readdirSync(packagesDir)
+    .filter((name) => fs.existsSync(path.join(packagesDir, name, 'vitest.config.ts')))
+    .sort()
+    .map((name) => ({ name, cwd: path.join(packagesDir, name) }))
+}
+
+function runSuite(name, cwd) {
+  const reportsDirectory = path.join(PARTS_DIR, name)
+  fs.mkdirSync(reportsDirectory, { recursive: true })
+  const args = [
+    'run',
+    '--coverage.enabled',
+    '--coverage.provider=v8',
+    '--coverage.reporter=json',
+    `--coverage.reportsDirectory=${reportsDirectory}`,
+    '--coverage.reportOnFailure=true',
+  ]
+  console.log(`\n=== ${name} (${path.relative(ROOT, cwd) || '.'}) ===`)
+  const result = spawnSync(VITEST_BIN, args, { cwd, stdio: 'inherit' })
+  const passed = result.status === 0
+  const coverage = readCoverage(reportsDirectory)
+  return { name, passed, coverage }
+}
+
+export function main() {
+  fs.rmSync(PARTS_DIR, { recursive: true, force: true })
+  fs.mkdirSync(PARTS_DIR, { recursive: true })
+
+  const suites = [{ name: 'root', cwd: ROOT }, ...discoverPackageSuites()]
+  const results = suites.map(({ name, cwd }) => runSuite(name, cwd))
+
+  const conflicts = []
+  const merged = mergeCoverage(
+    results.map((r) => r.coverage).filter(Boolean),
+    conflicts,
+  )
+
+  fs.mkdirSync(OUT_DIR, { recursive: true })
+  fs.writeFileSync(path.join(OUT_DIR, 'coverage-final.json'), JSON.stringify(merged))
+
+  console.log('\n=== coverage-all summary ===')
+  for (const r of results) {
+    const status = r.passed ? 'PASS' : 'FAIL'
+    console.log(
+      `${r.name.padEnd(24)} ${status}  files=${countFiles(r.coverage)}  functionsExecuted=${countFunctionsTotal(r.coverage)}`,
+    )
+  }
+
+  if (conflicts.length > 0) {
+    console.log(`\n${conflicts.length} merge conflict(s) (kept the entry with more executed functions):`)
+    for (const filePath of conflicts) console.log(`  ${filePath}`)
+  } else {
+    console.log('\nno merge conflicts')
+  }
+
+  console.log(
+    `\nmerged: files=${Object.keys(merged).length} functionsExecuted=${countFunctionsTotal(merged)} -> ${path.join(OUT_DIR, 'coverage-final.json')}`,
+  )
+
+  const anyFailed = results.some((r) => !r.passed)
+  process.exitCode = anyFailed ? 1 : 0
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main()

package/scripts/dashboard.mjs

@@ -0,0 +1,89 @@
+// Deterministic static dashboard generator — no network. Boots the pipeline/collection registries
+// the same way test/architecture/pipeline-invariants.test.ts does (no Nuxt boot needed for that), then
+// renders through the SAME renderDashboard() the dev route uses, so the two surfaces never drift.
+//
+// Run with: npx tsx scripts/dashboard.mjs   (or `pnpm dashboard`)
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import Database from 'better-sqlite3'
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import { fieldTypes } from '@michaelthielemann/kestrel-fields'
+import {
+  buildIntrospectionPipelines, buildPipelineIndex, clearPipelines, clearRegistry,
+  registerCollection, registerPipeline, renderDashboard, setResolvedKestrelConfig, allCollections,
+} from '@michaelthielemann/kestrel-core'
+import { buildAuthPipelines } from '@michaelthielemann/kestrel-auth'
+import { pagesCollection } from '@michaelthielemann/kestrel-collections'
+import { mediaCollection, mediaSettingsCollection } from '@michaelthielemann/kestrel-media'
+import { redirectsCollection, siteCollection } from '@michaelthielemann/kestrel-publishing'
+import { resolveServerKestrelConfig } from '../layers/core/server/utils/server-config.ts'
+import { PLUGIN_ORDER } from '../layers/core/modules/plugin-order/plugin-order.ts'
+import posts from '../server/collections/posts.ts'
+import settings from '../server/collections/settings.ts'
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+void fieldTypes
+setResolvedKestrelConfig(resolveServerKestrelConfig())
+Object.assign(globalThis, {
+  useRuntimeConfig: () => ({
+    kestrel: { output: { driver: 'local', dir: '', publicDir: '/kestrel-no-such-public-dir', auto: true, publishOnSave: false, reconcileMinutes: 0, verbose: false, s3: {} } },
+  }),
+  useDb: () => drizzle(new Database(':memory:')),
+  primaryLocale: () => 'en',
+  prefixPrimaryLocale: () => false,
+})
+
+clearRegistry()
+for (const c of [pagesCollection, posts, settings, mediaCollection, mediaSettingsCollection, redirectsCollection, siteCollection]) registerCollection(c)
+
+clearPipelines()
+for (const def of buildAuthPipelines()) registerPipeline(def)
+for (const def of buildIntrospectionPipelines()) registerPipeline(def)
+
+const collections = allCollections().map((c) => ({
+  name: c.name,
+  mode: c.def.mode,
+  translatable: Boolean(c.def.translatable),
+  fieldCount: Object.keys(c.def.fields).length,
+}))
+
+/** Reads a repo-only enrichment file, or returns undefined — a consumer project (or a fresh checkout
+ *  before `graphify update`/`pnpm api:check` have run) ships none of these, so every read is optional. */
+function readJsonIfExists(relPath) {
+  const abs = join(repoRoot, relPath)
+  if (!existsSync(abs)) return undefined
+  return JSON.parse(readFileSync(abs, 'utf8'))
+}
+
+function apiSurfaceSection() {
+  const ceilings = readJsonIfExists('test/architecture/public-api-ceilings.json')
+  if (!ceilings) return undefined
+  const out = []
+  for (const [report, ceiling] of Object.entries(ceilings)) {
+    const abs = join(repoRoot, report)
+    if (!existsSync(abs)) continue
+    const count = readFileSync(abs, 'utf8').split('\n').filter((l) => /^\/\/ @(public|alpha|beta|internal)\b/.test(l)).length
+    out.push({ report, count, ceiling })
+  }
+  return out
+}
+
+const edgeAllowlist = readJsonIfExists('test/architecture/edge-allowlist.json')
+const apiSurface = apiSurfaceSection()
+
+const html = renderDashboard({
+  pipelines: buildPipelineIndex(),
+  pluginOrder: PLUGIN_ORDER.map((p) => ({ layer: p.layer, file: p.file, after: p.after })),
+  collections,
+  graph: (edgeAllowlist || apiSurface) ? { packageEdges: edgeAllowlist?.edges, apiSurface } : undefined,
+  generatedAt: new Date().toISOString(),
+})
+
+const outDir = join(repoRoot, 'docs')
+mkdirSync(outDir, { recursive: true })
+const outFile = join(outDir, 'dashboard.html')
+writeFileSync(outFile, html)
+console.log(`[dashboard] wrote ${outFile} (${buildPipelineIndex().length} pipelines, ${collections.length} collections)`)

package/scripts/hash-password.mjs

@@ -3,7 +3,7 @@ import { hashPassword } from './lib/password.mjs'
 import { Cancelled, promptPassword } from './lib/cli.mjs'
 
 // 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
+// standalone entry point because docs/guide/getting-started.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) {

package/scripts/lib/coverage-model.mjs

@@ -0,0 +1,51 @@
+// Indexed view over an Istanbul-shaped coverage report, for the audit detectors.
+//
+// Two questions only: which branch arms were never taken, and which functions never ran. Both are
+// keyed by line so they can be joined to the graph, whose nodes carry a start line and no span.
+import { readFileSync, statSync } from 'node:fs'
+import { join, relative, isAbsolute } from 'node:path'
+
+export function loadCoverage(root, file = 'reports/coverage/coverage-final.json') {
+  const path = isAbsolute(file) ? file : join(root, file)
+  let raw
+  let generatedAt
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8'))
+    generatedAt = statSync(path).mtimeMs
+  } catch {
+    return null
+  }
+
+  const byFile = new Map()
+  for (const entry of Object.values(raw)) {
+    const rel = relative(root, entry.path)
+    const missedBranchLines = new Set()
+    let branchMissCount = 0
+    for (const [key, arm] of Object.entries(entry.branchMap ?? {})) {
+      const counts = entry.b?.[key] ?? []
+      arm.locations?.forEach((location, index) => {
+        if (counts[index] !== 0) return
+        branchMissCount += 1
+        const line = location.start?.line ?? arm.line
+        if (line) missedBranchLines.add(line)
+      })
+    }
+    const ranFunctionLines = new Set()
+    for (const [key, fn] of Object.entries(entry.fnMap ?? {})) {
+      if (!entry.f?.[key]) continue
+      const line = fn.decl?.start?.line ?? fn.loc?.start?.line
+      if (line) ranFunctionLines.add(line)
+    }
+    byFile.set(rel, { missedBranchLines, branchMissCount, ranFunctionLines })
+  }
+
+  const empty = { missedBranchLines: new Set(), branchMissCount: 0, ranFunctionLines: new Set() }
+  return {
+    generatedAt,
+    files: [...byFile.keys()],
+    has: (file) => byFile.has(file),
+    missedBranchLines: (file) => (byFile.get(file) ?? empty).missedBranchLines,
+    branchMissCount: (file) => (byFile.get(file) ?? empty).branchMissCount,
+    ranFunctionLines: (file) => (byFile.get(file) ?? empty).ranFunctionLines,
+  }
+}