@michaelthielemann/kestrel 1.4.0 → 1.5.0

package/README.md

@@ -36,7 +36,7 @@ static host. It is deliberately **not**:
 ## Features
 
 - **Runnable in one command** — `pnpm create kestrel` scaffolds a project that boots with a working
-  `/admin`, prompting for the admin password and writing its hash; `kestrel init` does the same to an
+  `/admin`, asking you to choose the admin password and writing its hash; `kestrel init` does the same to an
   existing project without clobbering it, and `kestrel doctor` names whatever is still missing.
 - **Collection-driven** — declare collections + fields in TypeScript; Kestrel derives the SQLite tables, a
   typed CRUD REST API, and the full admin UI. The schema **migrates itself** (additive in dev; explicit
@@ -66,7 +66,7 @@ pnpm create kestrel my-site
 cd my-site && pnpm install && pnpm dev
 ```
 
-It asks for an admin password and writes a project that runs as-is: `nuxt.config.ts` extending the
+It asks you to choose an admin password and writes a project that runs as-is: `nuxt.config.ts` extending the
 meta-layer, an `app.vue` that renders, a `.env` holding a fresh session secret and the scrypt hash of
 your password, and one example block. Sign in at <http://localhost:3000/admin>.
 

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

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import type { LayoutKey } from 'nuxt/app'
+import type { SiteHead } from '../utils/site-head'
 
 // The record decides its own layout, so route-meta resolution is opted out of and this page renders the
 // `<NuxtLayout>` itself. Side effect worth knowing: the layout becomes a CHILD of the page, so it can read
@@ -41,6 +42,7 @@ const { data: resolved } = await useAsyncData(`page:${locale}:${path}`, () =>
     collection: string | null
     page: (RenderedPage & Record<string, unknown>) | null
     alternates?: Array<{ locale: string; path: string }>
+    site?: SiteHead | null
   }),
 )
 const page = computed(() => resolved.value?.page ?? null)
@@ -86,6 +88,11 @@ if (!page.value && path !== '/') throw createError({ statusCode: 404, statusMess
 // og:image) require a configured siteUrl and degrade away without one.
 const publicRc = useRuntimeConfig().public as { siteUrl?: string; siteName?: string }
 const seo = page.value?.seo ?? {}
+const siteHead = resolved.value?.site ?? null
+const fallbacks = siteHeadFallbacks(seo, siteHead)
+// og:title stays the bare page title (og:site_name already carries the site); only <title> is composed.
+const pageTitle = seo.title || page.value?.title
+const documentTitle = composeTitle(pageTitle, siteHead)
 const head = buildPageHead({
   siteUrl: typeof publicRc.siteUrl === 'string' ? publicRc.siteUrl : '',
   siteName: typeof publicRc.siteName === 'string' ? publicRc.siteName : '',
@@ -93,9 +100,9 @@ const head = buildPageHead({
   locale,
   primary,
   prefixPrimary,
-  title: seo.title || page.value?.title,
-  description: seo.description || undefined,
-  image: seo.$media?.image ?? null,
+  title: pageTitle,
+  description: fallbacks.description,
+  image: fallbacks.image,
   alternates: resolved.value?.alternates ?? [],
 })
 
@@ -111,8 +118,8 @@ useHead({
   ],
 })
 useSeoMeta({
-  title: seo.title || page.value?.title,
-  description: seo.description || undefined,
+  title: documentTitle,
+  description: fallbacks.description,
   robots: seo.noindex ? 'noindex, nofollow' : undefined,
   ogTitle: head.meta.ogTitle,
   ogDescription: head.meta.ogDescription,

package/layers/public/app/utils/site-head.ts

@@ -0,0 +1,43 @@
+export interface SiteHead {
+  baseTitle?: string | null
+  titleSeparator?: string | null
+  titlePosition?: 'before' | 'after' | null
+  description?: string | null
+  $media?: { image?: { src: string, width: number | null, height: number | null } | null } | null
+}
+
+const DEFAULT_SEPARATOR = '|'
+
+const trimmed = (v: unknown): string | undefined => {
+  const s = typeof v === 'string' ? v.trim() : ''
+  return s || undefined
+}
+
+/**
+ * The `<title>` for a page. Only the document title is composed — `og:title` keeps the bare page title,
+ * because `og:site_name` already carries the site.
+ */
+export function composeTitle(pageTitle: string | undefined | null, site: SiteHead | null | undefined): string | undefined {
+  const page = trimmed(pageTitle)
+  const base = trimmed(site?.baseTitle)
+  if (!base) return page
+  if (!page) return base
+  // Migrated content often carries the site name in the page title already; appending it again reads as a
+  // bug to every visitor who looks at the tab.
+  if (page === base || page.endsWith(base)) return page
+  // The separator is stored as a bare token and padded here: a `text` field trims on write, so a stored
+  // " | " would come back as "|" and glue the two titles together.
+  const separator = trimmed(site?.titleSeparator) ?? DEFAULT_SEPARATOR
+  return site?.titlePosition === 'before' ? `${base} ${separator} ${page}` : `${page} ${separator} ${base}`
+}
+
+/** The page wins, the site stands in, and both degrade to absent so the tags disappear entirely. */
+export function siteHeadFallbacks(
+  seo: { description?: string | null, $media?: { image?: { src: string, width: number | null, height: number | null } | null } | null } | null | undefined,
+  site: SiteHead | null | undefined,
+): { description?: string, image: { src: string, width: number | null, height: number | null } | null } {
+  return {
+    description: trimmed(seo?.description) ?? trimmed(site?.description),
+    image: seo?.$media?.image ?? site?.$media?.image ?? null,
+  }
+}

package/layers/public/server/api/route.get.ts

@@ -13,6 +13,14 @@ export default defineEventHandler((event) => {
   const locale = typeof q.locale === 'string' ? q.locale : undefined
   const isStaticRender = import.meta.prerender === true || isRendererContext()
   const publishedOnly = isStaticRender || event.context.readScope !== 'all'
-  const resolved = resolvePage(useDb(), allCollections(), path, locale, publishedOnly)
-  return { collection: resolved?.collection ?? null, page: resolved?.page ?? null, alternates: resolved?.alternates ?? [] }
+  const db = useDb()
+  const resolved = resolvePage(db, allCollections(), path, locale, publishedOnly)
+  // The site-wide head tier rides along on the fetch the page already awaits, so it reaches SSR and the
+  // prerender on a path that is known to work. Looked up through the registry, not imported, so a consumer
+  // that disables the collection gets `null` instead of a query against a table the schema never created.
+  // `depth: 1` resolves the sharing image into `$media`; `getSingleton` captures the read, so an edit
+  // re-publishes every route that embedded it.
+  const siteCollection = getCollection('site')
+  const site = siteCollection ? getSingleton(db, siteCollection, locale, false, 1) : null
+  return { collection: resolved?.collection ?? null, page: resolved?.page ?? null, alternates: resolved?.alternates ?? [], site }
 })

package/layers/public/server/collections/site.ts

@@ -0,0 +1,44 @@
+import { buildCollection } from '../../../fields/server/utils/buildCollection'
+import { defineCollection } from '../../../core/server/utils/defineCollection'
+
+// `siteUrl`/`siteName` stay in `kestrel.config` on purpose: the build needs them for canonical URLs, the
+// sitemap and robots.txt, so they cannot live in the DB. What is here is editorial instead — and a write
+// re-publishes the routes that embed it, which a config value frozen at module setup can never do.
+const built = buildCollection(defineCollection({
+  name: 'site',
+  mode: 'single',
+  translatable: true,
+  builtin: true,
+  label: { singular: { en: 'Site', de: 'Website' }, plural: { en: 'Site', de: 'Website' } },
+  icon: 'globe',
+  fields: {
+    baseTitle: { type: 'text', label: { en: 'Base title', de: 'Basis-Titel' } },
+    titleSeparator: { type: 'text', label: { en: 'Title separator', de: 'Titel-Trenner' }, default: '|' },
+    titlePosition: {
+      type: 'choice',
+      label: { en: 'Base title position', de: 'Position des Basis-Titels' },
+      options: {
+        choices: [
+          { label: { en: 'After the page title', de: 'Nach dem Seitentitel' }, value: 'after' },
+          { label: { en: 'Before the page title', de: 'Vor dem Seitentitel' }, value: 'before' },
+        ],
+        display: 'buttons',
+      },
+      default: 'after',
+    },
+    description: {
+      type: 'text',
+      label: { en: 'Default meta description', de: 'Standard-Meta-Beschreibung' },
+      options: { multiline: true },
+    },
+    image: {
+      type: 'media',
+      label: { en: 'Default sharing image', de: 'Standard-Sharing-Bild' },
+      options: { accept: 'image' },
+    },
+  },
+  fieldLayout: [['baseTitle|2', 'titleSeparator|1'], 'titlePosition', 'description', 'image'],
+}))
+
+export const site = built.table
+export default built

package/nuxt.config.ts

@@ -83,22 +83,25 @@ export default defineNuxtConfig({
   vite: {
     build: { rollupOptions: { onwarn } },
     optimizeDeps: {
-      // Nested "kestrel > dep" form: Vite resolves each dep from the `kestrel` PACKAGE's directory
-      // rather than the (consumer) project root. Under pnpm these are kestrel's transitive deps and
-      // are NOT hoisted into a consumer's top-level node_modules, so a bare specifier is
-      // "Unresolvable" from the consumer root. In-repo `kestrel` is not a resolvable package name, so
-      // Vite's nestedResolveBasedir falls back to the repo root where these deps ARE hoisted — same
-      // result. The runtime `import('@tiptap/...')` still reuses the pre-bundle (tryOptimizedResolve
-      // matches the "> dep" id + src dir).
+      // Nested "<pkg> > dep" form: Vite resolves each dep from THIS package's directory rather than from
+      // the consumer's project root. It has to be the published name — under pnpm these are kestrel's
+      // transitive deps and are not hoisted into a consumer's top-level node_modules, so resolving from
+      // the root finds nothing. An unresolvable prefix is swallowed (`resolvePackageData(…)?.dir ||
+      // basedir`), and the entry then degrades to a bare lookup from the root: fine in-repo and for a
+      // hoisted npm/yarn consumer, silently unbundled for a pnpm one — which is why a stale prefix shows
+      // up only in a consumer's terminal. In-repo the name is likewise unresolvable and that same
+      // fallback lands on the repo root, where the deps ARE hoisted. The runtime `import('@tiptap/...')`
+      // still reuses the pre-bundle (tryOptimizedResolve matches the "> dep" id + src dir).
+      // `test/package.test.ts` pins the prefix to package.json's `name`.
       include: [
-        'kestrel > @internationalized/date',
-        'kestrel > @tiptap/extension-highlight',
-        'kestrel > @tiptap/extension-subscript',
-        'kestrel > @tiptap/extension-superscript',
-        'kestrel > @tiptap/extension-text-align',
-        'kestrel > @tiptap/starter-kit',
-        'kestrel > @tiptap/vue-3',
-        'kestrel > reka-ui',
+        '@michaelthielemann/kestrel > @internationalized/date',
+        '@michaelthielemann/kestrel > @tiptap/extension-highlight',
+        '@michaelthielemann/kestrel > @tiptap/extension-subscript',
+        '@michaelthielemann/kestrel > @tiptap/extension-superscript',
+        '@michaelthielemann/kestrel > @tiptap/extension-text-align',
+        '@michaelthielemann/kestrel > @tiptap/starter-kit',
+        '@michaelthielemann/kestrel > @tiptap/vue-3',
+        '@michaelthielemann/kestrel > reka-ui',
       ],
     },
   },

package/package.json

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

package/scripts/hash-password.mjs

@@ -1,5 +1,6 @@
 import { createInterface } from 'node:readline'
 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
@@ -7,7 +8,18 @@ import { hashPassword } from './lib/password.mjs'
 const arg = process.argv[2]
 if (arg) {
   process.stdout.write(hashPassword(arg) + '\n')
+} else if (process.stdin.isTTY) {
+  // Only the hash may reach stdout — an operator pipes it straight into a secret store.
+  try {
+    process.stdout.write(hashPassword(await promptPassword({ output: process.stderr })) + '\n')
+  } catch (err) {
+    if (!(err instanceof Cancelled)) throw err
+    process.stderr.write('cancelled\n')
+    process.exitCode = 1
+  }
 } else {
+  // `terminal: false` keeps the piped form (`echo pw | node hash-password.mjs`) working; it is only safe
+  // because stdin is not a tty here, so there is no line discipline echoing the password onto a screen.
   const rl = createInterface({ input: process.stdin, terminal: false })
   process.stderr.write('Enter password, then press Enter:\n')
   rl.on('line', (line) => {

package/scripts/kestrel.mjs

@@ -2,7 +2,6 @@
 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'
@@ -71,15 +70,12 @@ async function init(positional, flags) {
   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)) })
+      password = await promptPassword({ warn: (m) => out(yellow(m)), note: (m) => out(dim(m)) })
     } catch (err) {
-      rl.close()
       if (err instanceof Cancelled) fail('cancelled')
       throw err
     }
-    rl.close()
     out()
   }
 
@@ -170,15 +166,14 @@ async function hashPasswordCommand(positional) {
   let password = positional[0]
   if (password === undefined) {
     if (process.stdin.isTTY) {
-      const rl = createInterface({ input: process.stdin, output: process.stdout })
+      // Only the hash may reach stdout — an operator redirects it straight into a secret store.
+      const ask = (m) => process.stderr.write(`${m}\n`)
       try {
-        password = await promptPassword(rl, { warn: (m) => out(yellow(m)) })
+        password = await promptPassword({ output: process.stderr, warn: (m) => ask(yellow(m)), note: (m) => ask(dim(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')

package/scripts/lib/cli.mjs

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, chmodSync } from 'node:fs'
 import { dirname, join, relative } from 'node:path'
+import { createInterface } from 'node:readline/promises'
 
 export const MIN_PASSWORD_LENGTH = 8
 
@@ -65,44 +66,58 @@ export function walk(dir, base = dir) {
   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)
+/** Reads a line the interface is configured never to echo, so the prompt is ours to draw and to close. */
+async function askHidden(rl, question, write) {
+  write(question)
   try {
-    return (await rl.question(question)).trim()
+    return (await rl.question('')).trim()
   } finally {
-    process.stdin.off('data', repaint)
-    repaint()
-    process.stdout.write('\n')
+    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
+/**
+ * Owns its readline interface, because the two options that keep the secret off the screen can only be
+ * set at construction: `output: null` makes readline write nothing at all, and `terminal: true` still
+ * gives it the keypress handling (backspace, Ctrl-C, Ctrl-D) that would otherwise fall to the tty's own
+ * echoing line discipline. Erasing readline's echo afterwards cannot match that — a pasted secret arrives
+ * as one chunk that is echoed AND newlined in a single write, stranding the cleartext on a line no
+ * repaint can still reach, and a redirected stdout leaves `terminal` false with nothing to suppress.
+ *
+ * Throws `Cancelled` on Ctrl-C / Ctrl-D so a caller can exit cleanly instead of on an AbortError stack.
+ */
+export async function promptPassword({
+  input = process.stdin,
+  output = process.stdout,
+  warn = (m) => output.write(`${m}\n`),
+  note = (m) => output.write(`${m}\n`),
+} = {}) {
+  const draw = (s) => output.write(s)
+  const rl = createInterface({ input, output: null, terminal: true })
+  note(`Choose a password for /admin — at least ${MIN_PASSWORD_LENGTH} characters, kept only as a scrypt hash.`)
+  try {
+    for (;;) {
+      let first
+      try {
+        first = await askHidden(rl, 'New admin password: ', draw)
+        if (first.length < MIN_PASSWORD_LENGTH) {
+          warn(`  too short — at least ${MIN_PASSWORD_LENGTH} characters`)
+          continue
+        }
+        if (first !== (await askHidden(rl, 'Repeat password: ', draw))) {
+          warn('  the two entries differ — try again')
+          continue
+        }
+      } catch (err) {
+        throw err?.code === 'ABORT_ERR' ? new Cancelled() : err
       }
-    } catch (err) {
-      throw err?.code === 'ABORT_ERR' ? new Cancelled() : err
+      if (first === undefined) throw new Cancelled()
+      return first
     }
-    if (first === undefined) throw new Cancelled()
-    return first
+  } finally {
+    rl.close()
   }
 }
 

package/templates/starter/README.md

@@ -8,7 +8,7 @@ pnpm install
 pnpm dev
 ```
 
-Admin: <http://localhost:3000/admin> — sign in with the password you chose during `kestrel init`.
+Admin: <http://localhost:3000/admin> — sign in with the password you chose while scaffolding.
 Forgot it? `pnpm hash-password` prints a fresh hash for `KESTREL_ADMIN_PASSWORD_HASH` in `.env`.
 
 ## What is here