@michaelthielemann/kestrel 1.6.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michaelthielemann/kestrel",
-  "version": "1.6.0",
+  "version": "2.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>",
@@ -44,6 +44,7 @@
   "engines": {
     "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",
@@ -56,6 +57,7 @@
     "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": {
@@ -68,6 +70,9 @@
     "@tiptap/pm": "^3.29.2",
     "@tiptap/starter-kit": "^3.29.2",
     "@tiptap/vue-3": "^3.29.2",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/jsdom": "^28.0.3",
+    "@types/sanitize-html": "^2.16.1",
     "aws4fetch": "^1.0.20",
     "better-sqlite3": "^12.11.1",
     "dompurify": "^3.4.13",
@@ -107,14 +112,14 @@
     }
   },
   "devDependencies": {
+    "@nuxt/eslint": "^1.9.0",
     "@nuxt/kit": "^4.5.2",
     "@nuxt/test-utils": "^4.1.0",
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/jsdom": "^28.0.3",
-    "@types/sanitize-html": "^2.16.1",
     "@vitejs/plugin-vue": "^6.0.8",
     "@vue/test-utils": "^2.4.11",
     "drizzle-kit": "^0.31.10",
+    "eslint": "^9.39.1",
+    "eslint-plugin-vuejs-accessibility": "^2.4.1",
     "h3": "^1.15.11",
     "happy-dom": "^20.11.2",
     "playwright-core": "^1.62.1",

package/scripts/kestrel.mjs

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readFileSync } from 'node:fs'
 import { join, resolve, basename, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { hashPassword, sessionSecret } from './lib/password.mjs'
-import { PACKAGE_NAME, diagnoseProject, mergeEnv, mergePackageJson, renderTemplate, targetName, toPackageName } from './lib/scaffold.mjs'
+import { PACKAGE_NAME, diagnoseProject, envValue, isPlainObject, 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`.
@@ -30,13 +30,16 @@ function inspect(target) {
     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')),
+    kestrelConfig: readIf(join(target, 'kestrel.config.ts')) ?? readIf(join(target, 'kestrel.config.js')),
     env: readIf(join(target, '.env')),
   })
 }
 
+const LEVEL_LABEL = { error: () => red('✖ error'), info: () => dim('· note '), warn: () => yellow('▲ warn ') }
+
 function printFindings(found) {
   for (const d of found) {
-    out(`${d.level === 'error' ? red('✖ error') : yellow('▲ warn ')} ${d.message}`)
+    out(`${(LEVEL_LABEL[d.level] ?? LEVEL_LABEL.warn)()} ${d.message}`)
     out()
   }
 }
@@ -46,18 +49,25 @@ async function init(positional, flags) {
   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.
+  // Read the target 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) {
+    let parsed
     try {
-      JSON.parse(existingManifest)
+      parsed = JSON.parse(existingManifest)
     } catch {
       fail(`${manifestPath} is not valid JSON — fix it first; refusing to scaffold over a broken manifest.`)
     }
+    if (!isPlainObject(parsed)) fail(`${manifestPath} is not a JSON object — fix it first; refusing to scaffold over a broken manifest.`)
   }
+  const envPath = join(target, '.env')
+  const existingEnv = readIf(envPath)
 
-  let password = typeof flags.password === 'string' ? flags.password : undefined
+  // No flag swallows a `-`-prefixed token, so a dash-leading password reaches init as no value at all.
+  if (flags.password === true) fail('--password needs a value — write --password=<pw> if it starts with a dash.')
+  const supplied = typeof flags.password === 'string'
+  let password = supplied ? 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).`)
   }
@@ -70,13 +80,21 @@ async function init(positional, flags) {
   out()
 
   if (password === undefined && !flags.yes && process.stdin.isTTY) {
-    try {
-      password = await promptPassword({ warn: (m) => out(yellow(m)), note: (m) => out(dim(m)) })
-    } catch (err) {
-      if (err instanceof Cancelled) fail('cancelled')
-      throw err
+    // The prompt loops until a valid password is typed twice, so it cannot be declined, and the hash is
+    // folded into the session signing key — asking on a project that already has one would rotate the
+    // password, and sign everyone out, without ever offering the operator a way to say no.
+    if (envValue(existingEnv ?? '', 'KESTREL_ADMIN_PASSWORD_HASH')) {
+      out(dim('KESTREL_ADMIN_PASSWORD_HASH is already set — pass --password to change it.'))
+      out()
+    } else {
+      try {
+        password = await promptPassword({ warn: (m) => out(yellow(m)), note: (m) => out(dim(m)) })
+      } catch (err) {
+        if (err instanceof Cancelled) fail('cancelled')
+        throw err
+      }
+      out()
     }
-    out()
   }
 
   const vars = templateVars(projectName)
@@ -109,12 +127,14 @@ async function init(positional, flags) {
   }
 
   // Seed from `.env.example` so the generated file keeps its per-key comments.
-  const envPath = join(target, '.env')
-  const hadEnv = existsSync(envPath)
+  const hadEnv = existingEnv !== null
   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)
+  const seed = existingEnv ?? readIf(join(target, '.env.example')) ?? ''
+  // Only an explicitly supplied password replaces a hash that is already set. That is not session-safety:
+  // the hash is folded into the cookie signing key, so any rotation signs every user out. What keeps a
+  // plain re-run harmless is that it changes neither the hash nor the secret.
+  const { text, written } = mergeEnv(seed, envEntries, supplied ? ['KESTREL_ADMIN_PASSWORD_HASH'] : [])
   if (written.length) {
     write(envPath, text, 0o600)
     ;(hadEnv ? merged : created).push(`.env ${dim(`(${written.join(', ')})`)}`)
@@ -153,10 +173,11 @@ function doctor(positional) {
   const found = inspect(target)
 
   out()
-  if (!found.length) {
+  // An `info` finding is a note about how this project is configured, not a problem with it — so it prints,
+  // but it must not withhold the all-clear the way a warning does.
+  if (!found.some((d) => d.level !== 'info')) {
     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
@@ -191,7 +212,7 @@ ${bold('kestrel')} ${dim(`v${pkg.version}`)}
 
 ${bold('init flags')}
   --name <name>       package name (default: the directory name, slugified)
-  --password <pw>     set the admin password without prompting
+  --password <pw>     set or change 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)
 
@@ -199,9 +220,17 @@ ${dim('Existing files are kept and re-running init is safe. To create a NEW proj
 `)
 }
 
-const { flags, positional } = parseArgs(process.argv.slice(2), ['yes', 'force', 'help', 'version'])
+const argv = process.argv.slice(2)
+const { flags, positional } = parseArgs(argv, ['yes', 'force', 'help', 'version'])
 const command = positional.shift()
 
+// Only these two read a positional as a directory, and an option that took no value lands there: a
+// `--password -pw` would otherwise put the cleartext on disk as a directory name. `--` is how the caller
+// says a dash-leading positional is what they meant.
+if (!argv.includes('--') && (command === 'init' || command === 'doctor') && positional[0]?.startsWith('-')) {
+  fail(`unknown option "${positional[0]}" — run \`kestrel help\`.`)
+}
+
 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)

package/scripts/lib/scaffold.mjs

@@ -31,9 +31,12 @@ 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.
+ * A key in `force` replaces a value that is already there — for a secret the caller supplied by hand,
+ * where being handed one at all is the instruction to change it.
  * Returns the new text plus the keys that changed.
  */
-export function mergeEnv(existing, entries) {
+export function mergeEnv(existing, entries, force = []) {
+  const forced = new Set(force)
   const pending = new Map(Object.entries(entries))
   const lines = existing === '' ? [] : existing.split('\n')
   const written = []
@@ -51,7 +54,7 @@ export function mergeEnv(existing, entries) {
     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
+    if (line.slice(line.indexOf('=') + 1).trim() !== '' && !forced.has(key)) return line
     written.push(key)
     return `${key}=${value}`
   })
@@ -68,7 +71,8 @@ export function mergeEnv(existing, entries) {
   return { text: out.join('\n'), written }
 }
 
-const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v)
+/** `typeof null === 'object'`, and arrays are objects too — both need explicit exclusion for a plain object check. */
+export const isPlainObject = (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
@@ -87,24 +91,41 @@ export function mergePackageJson(existing, template) {
   }
   for (const key of NESTED) {
     if (!template[key]) continue
-    merged[key] = isObject(existing[key]) ? { ...template[key], ...existing[key] } : template[key]
+    merged[key] = isPlainObject(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}`)
+      if (!isPlainObject(existing[key]) || !(name in existing[key])) added.push(`${key}.${name}`)
     }
   }
   return { merged, added }
 }
 
+/**
+ * The value a dotenv key carries, or `undefined`/`''` when it carries none.
+ * Horizontal whitespace only: `\s*` would let an empty assignment match the NEXT line's value.
+ */
+export const envValue = (env, key) => new RegExp(`^[^\\S\\n]*${key}[^\\S\\n]*=[^\\S\\n]*(.+)$`, 'm').exec(env)?.[1].trim()
+
 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)
 
+/** Whether `output.publishOnSave` resolves to `true` — config or its env override, same precedence as
+ *  `resolveKestrel` (env wins when it names a valid boolean; otherwise the config file's own value). */
+function publishOnSaveEnabled(kestrelConfig, env) {
+  const fromEnv = env !== null ? envValue(env, 'KESTREL_OUTPUT_PUBLISH_ON_SAVE')?.toLowerCase() : undefined
+  if (fromEnv !== undefined) {
+    if (['true', '1', 'yes', 'on'].includes(fromEnv)) return true
+    if (['false', '0', 'no', 'off'].includes(fromEnv)) return false
+  }
+  return typeof kestrelConfig === 'string' && /\bpublishOnSave\s*:\s*true\b/.test(kestrelConfig)
+}
+
 /**
  * `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 }) {
+export function diagnoseProject({ packageJson, nuxtConfig, appVue, env, kestrelConfig }) {
   const found = []
   const add = (level, message) => found.push({ level, message })
 
@@ -160,8 +181,7 @@ export function diagnoseProject({ packageJson, nuxtConfig, appVue, env }) {
   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()
+    const value = (key) => envValue(env, key)
     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`.')
     }
@@ -170,5 +190,16 @@ export function diagnoseProject({ packageJson, nuxtConfig, appVue, env }) {
     }
   }
 
+  // Informational, not a misconfiguration: `publishOnSave: false` is the correct 2.0 default. Named
+  // because it is a silent behaviour change from 1.x — a headless consumer that only PATCHes content and
+  // never opens /admin gets no other signal that saves stopped reaching the static output.
+  if (!publishOnSaveEnabled(kestrelConfig, env)) {
+    add(
+      'info',
+      'saving a record no longer publishes it by default — only an explicit Publish action does (ADR-0008). ' +
+        'Set `output.publishOnSave: true` in kestrel.config.ts, or KESTREL_OUTPUT_PUBLISH_ON_SAVE=1, to restore the pre-2.0 behaviour.',
+    )
+  }
+
   return found
 }

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

@@ -8,5 +8,6 @@ defineBlock({ label: { en: 'Prose' }, icon: 'file-text' })
 
 <template>
   <!-- richtext is sanitized server-side on write -->
+  <!-- eslint-disable-next-line vue/no-v-html -- sanitized via sanitizeRichtext (sanitize-html allowlist) in layers/fields/server/field-registry/index.ts -->
   <div class="block-prose" v-html="body" />
 </template>