@michaelthielemann/kestrel 1.3.0 → 1.4.1

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/admin/app/components/PageFields.vue

@@ -25,6 +25,11 @@ const props = defineProps<{
 const emit = defineEmits<{ update: [name: string, value: unknown] }>()
 const { t } = useT()
 
+// A project with a single layout has nothing to choose, so the control stays out of the pane entirely
+// rather than offering one dead option.
+const layoutOptions = computed(() => layoutSelectOptions(useOfferableLayouts(), t('pageSettings.layoutDefault')))
+const showLayout = computed(() => !!props.pageLike && layoutOptions.value.length > 1)
+
 // Live preview of the slug the server will auto-generate from the title while the field is left blank
 // (the server slugifies the title on save). Falls back to '/' when there is no title yet.
 const slugPlaceholder = computed(() => {
@@ -88,6 +93,26 @@ const slugPlaceholder = computed(() => {
     </template>
   </UiField>
 
+  <!-- Which layout renders this page (the `layout` system column). Empty = the `default` layout, so an
+       unset value keeps rendering exactly as a project without the column. -->
+  <UiField
+    v-if="showLayout"
+    class="page-settings__layout"
+    :label="t('pageSettings.layoutLabel')"
+    :hint="t('pageSettings.layoutHint')"
+    :error="errors.layout || null"
+  >
+    <template #default="f">
+      <UiSelect
+        :model-value="(values.layout as string) ?? ''"
+        :options="layoutOptions"
+        :disabled="disabled"
+        v-bind="f"
+        @update:model-value="(v) => emit('update', 'layout', v)"
+      />
+    </template>
+  </UiField>
+
   <!-- Page SEO (meta title/description/noindex + Google preview). The `seo` JSON system column. -->
   <SeoFields
     v-if="seo"

package/layers/admin/app/composables/useEditForm.ts

@@ -135,6 +135,8 @@ export function useEditForm(opts: UseEditFormOptions) {
     if (blocksEnabled.value) next.content = (source?.content as unknown[]) ?? []
     // `path` (the page slug) is a pageLike system column, likewise round-tripped explicitly.
     if (pageLike.value) next.path = (source?.path as string | null | undefined) ?? ''
+    // '' is the "no override" form the select binds to.
+    if (pageLike.value) next.layout = (source?.layout as string | null | undefined) ?? ''
     // `seo` is a JSON system column; default to an empty object so the editor can fill it in.
     if (hasSeo.value) next.seo = (source?.seo as Record<string, unknown> | undefined) ?? {}
     // `status` is a system column; a new record defaults to 'draft' (unpublished) — matches the DB default.
@@ -261,6 +263,9 @@ export function useEditForm(opts: UseEditFormOptions) {
     if (blocksEnabled.value) body.content = values.content
     // Send the slug as the routable path; a blank slug clears the route (stored as null, not "").
     if (pageLike.value) body.path = (values.path as string) ? values.path : null
+    // An unset layout is stored as NULL, never '': the render coalesces NULL to `default`, and a stored ''
+    // would be indistinguishable from a name that failed to save.
+    if (pageLike.value) body.layout = (values.layout as string) || null
     if (hasSeo.value) body.seo = values.seo ?? {}
     if (hasStatus.value) body.status = (values.status as string) ?? 'draft'
     // A new translatable multi record carries its locale, and links to a translation group when it is

package/layers/core/app/composables/layouts.ts

@@ -0,0 +1,5 @@
+import { kestrelLayouts } from '#build/kestrel-layouts.mjs'
+
+export function useOfferableLayouts(): string[] {
+  return kestrelLayouts
+}

package/layers/core/app/utils/layouts.ts

@@ -0,0 +1,38 @@
+/** The admin shell. Never offerable for a public record — a page rendered inside it would carry the
+ *  admin chrome and its own `useHead`. */
+export const ADMIN_LAYOUT = 'admin'
+
+/** Nuxt's resolved `app.layouts` entry (`nuxt.options.app.layouts`, filled before the `app:resolve` hook). */
+export interface ResolvedLayout { name: string, file: string }
+
+/**
+ * The layout names a page may be assigned, from Nuxt's own resolved layout map. Nuxt has already done the
+ * layer-ordered, name-first dedup (a consumer's `default.vue` shadows the engine's), so this only filters
+ * and sorts — no directory scan of our own.
+ */
+export function offerableLayouts(layouts: Record<string, ResolvedLayout | undefined>): string[] {
+  return Object.values(layouts)
+    .filter((l): l is ResolvedLayout => !!l && typeof l.file === 'string' && l.file.endsWith('.vue'))
+    .map((l) => l.name)
+    .filter((name) => name !== ADMIN_LAYOUT)
+    .sort()
+}
+
+export function renderLayoutRegistry(names: string[]): string {
+  return `export const kestrelLayouts = ${JSON.stringify(names)}\n`
+}
+
+/**
+ * Options for the page-layout select. The fallback is one entry with an EMPTY value — an unset column
+ * already renders `default`, so offering `default` as its own value would give the editor two controls for
+ * one outcome and pin the row to a name the consumer may later rename.
+ */
+export function layoutSelectOptions(names: string[], fallbackLabel: string): { label: string, value: string }[] {
+  return [
+    { label: fallbackLabel, value: '' },
+    ...names.filter((n) => n !== DEFAULT_LAYOUT_NAME).map((n) => ({ label: n, value: n })),
+  ]
+}
+
+/** Mirrors `DEFAULT_LAYOUT` in the public layer; kept local so this util stays dependency-free. */
+const DEFAULT_LAYOUT_NAME = 'default'

package/layers/core/modules/auto-discovery/index.ts

@@ -1,8 +1,9 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { addComponentsDir, addTypeTemplate, createResolver, defineNuxtModule } from '@nuxt/kit'
+import { addComponentsDir, addTemplate, addTypeTemplate, createResolver, defineNuxtModule } from '@nuxt/kit'
 import { collectBlockSfcs, collectDefinitions, renderRegistry } from './scan'
 import { renderBlockRegistry } from './extract-block'
+import { offerableLayouts, renderLayoutRegistry } from '../../app/utils/layouts'
 
 export default defineNuxtModule({
   meta: { name: 'kestrel-auto-discovery' },
@@ -22,6 +23,15 @@ export default defineNuxtModule({
       if (existsSync(dir)) addComponentsDir({ path: dir, prefix: 'Blocks', global: true, pathPrefix: false })
     }
 
+    // Layouts need no scan of our own: Nuxt already resolves `app/layouts/*.vue` across the layers with the
+    // same name-first, consumer-wins dedup, and fills `app.layouts` just before `app:resolve` — which runs
+    // inside `generateApp`, ahead of the templates being written, so the closure below is filled in time.
+    let layoutNames: string[] = []
+    nuxt.hook('app:resolve', (app) => { layoutNames = offerableLayouts(app.layouts ?? {}) })
+    // `write` so the resolved list is inspectable in `.nuxt/` — a virtual-only template makes "which layouts
+    // did the build actually find" unanswerable without a debugger.
+    addTemplate({ filename: 'kestrel-layouts.mjs', write: true, getContents: () => renderLayoutRegistry(layoutNames) })
+
     nuxt.hook('nitro:config', (nitro) => {
       nitro.virtual ||= {}
       // Consumer field types register as a side effect on import, and the schema engine builds a table the

package/layers/core/modules/auto-discovery/virtual.d.ts

@@ -10,3 +10,6 @@ declare module '#kestrel/schema-tables' {
   const tables: unknown[]
   export default tables
 }
+declare module '#build/kestrel-layouts.mjs' {
+  export const kestrelLayouts: string[]
+}

package/layers/fields/server/utils/buildTable.ts

@@ -17,7 +17,7 @@ function reservedColumns(def: CollectionDef): { js: Set<string>; db: Set<string>
   if (def.translatable) add('locale', 'locale')
   if (def.mode === 'single') add('singletonKey', 'singleton_key')
   else if (def.translatable) add('translationGroup', 'translation_group')
-  if (def.pageLike) add('path', 'path')
+  if (def.pageLike) { add('path', 'path'); add('layout', 'layout') }
   if (def.status) add('status', 'status')
   if (def.seo) add('seo', 'seo')
   if (def.blocks?.enabled) add('content', 'content')
@@ -67,7 +67,13 @@ export function buildTable(def: CollectionDef): SQLiteTable {
   if (def.translatable) cols.locale = text('locale').notNull()
   if (def.mode === 'single') cols.singletonKey = text('singleton_key').notNull()
   else if (def.translatable) cols.translationGroup = text('translation_group').notNull()
-  if (def.pageLike) cols.path = text('path')
+  if (def.pageLike) {
+    cols.path = text('path')
+    // Nullable with no default: an editor's "inherit" must be distinguishable from an explicit `default`,
+    // and the render decides the fallback (see resolvePageLayout) so a deleted layout file degrades in one
+    // place instead of being frozen into every row.
+    cols.layout = text('layout')
+  }
   if (def.status) cols.status = text('status').notNull().default('draft')
   if (def.seo) cols.seo = text('seo', { mode: 'json' }).$type<SeoMeta>().notNull().default(sql`'{}'`)
   if (def.blocks?.enabled) cols.content = text('content', { mode: 'json' }).$type<Block[]>().notNull().default(sql`'[]'`)

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

@@ -1,6 +1,14 @@
 <script setup lang="ts">
+import type { LayoutKey } from 'nuxt/app'
+
+// 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
+// `usePublicPageState()` during SSR — as its parent it rendered before the page had written it.
+definePageMeta({ layout: false })
+
 interface RenderedPage {
   title?: string
+  layout?: string | null
   seo?: {
     title?: string
     description?: string
@@ -36,6 +44,12 @@ const { data: resolved } = await useAsyncData(`page:${locale}:${path}`, () =>
   }),
 )
 const page = computed(() => resolved.value?.page ?? null)
+// `fallback` below only rescues a truthy name that is missing from the layout map, so the empty cases have
+// to be coalesced here — see resolvePageLayout. The cast is the one honest bridge in this file: the stored
+// name is arbitrary editor data, while `NuxtLayout` types `name` as the union of layouts that existed at
+// build time. Narrowing to that union is impossible for a value read from the DB, and `fallback` is exactly
+// the runtime guard for a name outside it.
+const pageLayout = computed(() => resolvePageLayout(page.value?.layout) as LayoutKey)
 
 // The layout (language menu & co.) needs the resolved record and its collection; pages and layouts share
 // no other channel, so mirror the fetch result into the shared state — reactively, so client-side
@@ -113,21 +127,23 @@ useSeoMeta({
 </script>
 
 <template>
-  <article>
-    <!-- Only ever shown to an authenticated admin previewing an unpublished page (drafts never resolve
-         for anonymous visitors or the static render), so it never ships to the public/static site.
-         Suppressed inside the editor preview iframe — the editor's own status ampel covers it. -->
-    <div v-if="isDraftPreview && !previewActive" class="kestrel-draft-badge" role="status">
-      <span class="kestrel-draft-badge__dot" aria-hidden="true" />
-      Draft preview — not published
-    </div>
-    <!-- Editor preview: the bridge swaps in the editor's live (unsaved) tree over postMessage and makes
-         blocks selectable; the saved content renders until the first message. Normal path unchanged. -->
-    <LazyKestrelPreviewBridge v-if="previewActive" :blocks="(page?.content as any[]) ?? []" v-slot="{ blocks }">
-      <BlockRenderer :blocks="(blocks as any[])" />
-    </LazyKestrelPreviewBridge>
-    <BlockRenderer v-else :blocks="(page?.content as any[]) ?? []" />
-  </article>
+  <NuxtLayout :name="pageLayout" fallback="default">
+    <article>
+      <!-- Only ever shown to an authenticated admin previewing an unpublished page (drafts never resolve
+           for anonymous visitors or the static render), so it never ships to the public/static site.
+           Suppressed inside the editor preview iframe — the editor's own status ampel covers it. -->
+      <div v-if="isDraftPreview && !previewActive" class="kestrel-draft-badge" role="status">
+        <span class="kestrel-draft-badge__dot" aria-hidden="true" />
+        Draft preview — not published
+      </div>
+      <!-- Editor preview: the bridge swaps in the editor's live (unsaved) tree over postMessage and makes
+           blocks selectable; the saved content renders until the first message. Normal path unchanged. -->
+      <LazyKestrelPreviewBridge v-if="previewActive" :blocks="(page?.content as any[]) ?? []" v-slot="{ blocks }">
+        <BlockRenderer :blocks="(blocks as any[])" />
+      </LazyKestrelPreviewBridge>
+      <BlockRenderer v-else :blocks="(page?.content as any[]) ?? []" />
+    </article>
+  </NuxtLayout>
 </template>
 
 <style scoped>

package/layers/public/app/utils/page-layout.ts

@@ -0,0 +1,18 @@
+/** The layout every page falls back to. Nuxt's own name for the unnamed layout, and the one the public
+ *  layer ships (`layers/public/app/layouts/default.vue`), so it is always present. */
+export const DEFAULT_LAYOUT = 'default'
+
+/**
+ * The layout name to render a page in, from its stored `layout` column.
+ *
+ * Must never return an empty value. The catch-all declares `definePageMeta({ layout: false })` so the page
+ * owns its own `<NuxtLayout>`; that makes `route.meta.layout` the literal `false`, and NuxtLayout resolves
+ * `unref(props.name) ?? route.meta.layout ?? …` — `??` keeps `false`, which fails its `hasLayout` check and
+ * renders the page with NO layout wrapper. The `fallback` prop does not cover this: it only applies to a
+ * truthy name absent from the layout map. Coalescing here is what keeps an unset column rendering the
+ * normal site frame.
+ */
+export function resolvePageLayout(stored: string | null | undefined): string {
+  const name = typeof stored === 'string' ? stored.trim() : ''
+  return name || DEFAULT_LAYOUT
+}

package/layers/ui/app/i18n/de.ts

@@ -133,6 +133,9 @@ export const de: Catalog = {
 
   'pageSettings.slugLabel': 'Slug',
   'pageSettings.slugHint': 'URL-Pfad, z. B. /about (leer = automatisch aus dem Titel)',
+  'pageSettings.layoutLabel': 'Layout',
+  'pageSettings.layoutHint': 'Mit welchem Layout diese Seite gerendert wird.',
+  'pageSettings.layoutDefault': 'Standard (default)',
   'pageSettings.statusLabel': 'Status',
   'pageSettings.statusHint': 'Entwurf bleibt offline; Veröffentlicht rendert die Seite.',
   'pageSettings.statusDraft': 'Entwurf',

package/layers/ui/app/i18n/en.ts

@@ -144,6 +144,9 @@ export const en: Catalog = {
   // page settings (system fields on pageLike collections)
   'pageSettings.slugLabel': 'Slug',
   'pageSettings.slugHint': 'URL path, e.g. /about (blank = auto-generated from the title)',
+  'pageSettings.layoutLabel': 'Layout',
+  'pageSettings.layoutHint': 'Which layout renders this page.',
+  'pageSettings.layoutDefault': 'Standard (default)',
   'pageSettings.statusLabel': 'Status',
   'pageSettings.statusHint': 'Draft stays off the live site; Published renders it.',
   'pageSettings.statusDraft': 'Draft',

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.3.0",
+  "version": "1.4.1",
   "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/copy-create-payload.mjs

@@ -13,11 +13,6 @@ 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')) {
@@ -42,11 +37,13 @@ if (process.argv.includes('--clean')) {
     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'] = {
+  // A generated file, not a key in the committed manifest: `postpack` is not guaranteed to run (a failed
+  // publish skips it), and a stamp left behind in package.json would be committed and then silently pin
+  // stale ranges. Deleting `lib/` removes this with everything else.
+  const stamp = {
     nuxt: engine.dependencies?.nuxt,
     typescript: engine.dependencies?.typescript,
     'vue-tsc': engine.devDependencies?.['vue-tsc'],
   }
-  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+  writeFileSync(join(PKG, 'lib', 'engine-meta.mjs'), `export default ${JSON.stringify(stamp, null, 2)}\n`)
 }

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