@michaelthielemann/kestrel 4.1.2 → 5.0.0

package/scripts/coverage-all.mjs

@@ -1,163 +0,0 @@
-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

@@ -1,89 +0,0 @@
-// 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

@@ -1,29 +0,0 @@
-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/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) {
-  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) => {
-    process.stdout.write(hashPassword(line) + '\n')
-    rl.close()
-  })
-}

package/scripts/kestrel.mjs

@@ -1,240 +0,0 @@
-#!/usr/bin/env node
-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, 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`.
-const PKG_ROOT = resolve(fileURLToPath(import.meta.url), '../..')
-const TEMPLATES = join(PKG_ROOT, 'templates')
-const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'))
-
-const { dim, bold, red, yellow, green } = makePaint()
-const fail = (s) => {
-  process.stderr.write(`${red('error')} ${s}\n`)
-  process.exit(1)
-}
-
-const templateVars = (name) => ({
-  name,
-  version: `^${pkg.version}`,
-  nuxtVersion: pkg.dependencies?.nuxt ?? '^4.4.8',
-  typescriptVersion: pkg.dependencies?.typescript ?? '^6.0.3',
-  vueTscVersion: pkg.devDependencies?.['vue-tsc'] ?? '^3.3.7',
-})
-
-function inspect(target) {
-  return diagnoseProject({
-    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(`${(LEVEL_LABEL[d.level] ?? LEVEL_LABEL.warn)()} ${d.message}`)
-    out()
-  }
-}
-
-async function init(positional, flags) {
-  const target = resolve(positional[0] ?? '.')
-  const templateDir = join(TEMPLATES, 'starter')
-  if (!existsSync(templateDir)) fail(`template payload missing at ${templateDir} — reinstall ${PACKAGE_NAME}.`)
-
-  // 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 {
-      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)
-
-  // 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).`)
-  }
-
-  mkdirSync(target, { recursive: true })
-  const projectName = toPackageName(typeof flags.name === 'string' ? flags.name : basename(target))
-
-  out()
-  out(`${bold('Kestrel')} ${dim(`v${pkg.version}`)} — setting up ${bold(relative(process.cwd(), target) || '.')}`)
-  out()
-
-  if (password === undefined && !flags.yes && process.stdin.isTTY) {
-    // 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()
-    }
-  }
-
-  const vars = templateVars(projectName)
-  const created = []
-  const kept = []
-  const merged = []
-
-  for (const rel of walk(templateDir).sort()) {
-    const name = targetName(rel)
-    const dest = join(target, name)
-    const body = renderTemplate(readFileSync(join(templateDir, rel), 'utf8'), vars)
-    const existing = readIf(dest)
-
-    // A manifest is never overwritten, not even with --force: the caller most likely already ran
-    // `pnpm add`, and replacing their dependencies and version is not a scaffold, it is data loss.
-    if (name === 'package.json' && existing !== null) {
-      const { merged: result, added } = mergePackageJson(JSON.parse(existing), JSON.parse(body))
-      if (added.length) {
-        write(dest, `${JSON.stringify(result, null, 2)}\n`)
-        merged.push(`package.json ${dim(`(+ ${added.join(', ')})`)}`)
-      } else kept.push('package.json')
-      continue
-    }
-    if (existing !== null && !flags.force) {
-      kept.push(name)
-      continue
-    }
-    write(dest, body)
-    created.push(name)
-  }
-
-  // Seed from `.env.example` so the generated file keeps its per-key comments.
-  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 = 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(', ')})`)}`)
-  } else kept.push('.env')
-
-  const report = (label, items, paint) => {
-    for (const f of items) out(`  ${paint(label)} ${f}`)
-  }
-  report('created', created, green)
-  report('updated', merged, green)
-  report('kept   ', kept, dim)
-
-  // Existing files are kept, so init must never report success over a project that still can't serve /admin.
-  const remaining = inspect(target)
-  if (remaining.length) {
-    out()
-    out(bold('Still to fix:'))
-    out()
-    printFindings(remaining)
-  }
-
-  out()
-  out(bold('Next:'))
-  const rel = relative(process.cwd(), target)
-  if (rel) out(`  cd ${rel}`)
-  out('  pnpm install')
-  out('  pnpm dev')
-  out()
-  out(`  Admin: ${bold('http://localhost:3000/admin')}`)
-  out()
-  return remaining.some((d) => d.level === 'error') ? 1 : 0
-}
-
-function doctor(positional) {
-  const target = resolve(positional[0] ?? '.')
-  const found = inspect(target)
-
-  out()
-  // 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()
-  }
-  printFindings(found)
-  return found.some((d) => d.level === 'error') ? 1 : 0
-}
-
-async function hashPasswordCommand(positional) {
-  let password = positional[0]
-  if (password === undefined) {
-    if (process.stdin.isTTY) {
-      // 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({ output: process.stderr, warn: (m) => ask(yellow(m)), note: (m) => ask(dim(m)) })
-      } catch (err) {
-        if (err instanceof Cancelled) fail('cancelled')
-        throw err
-      }
-    } else password = await readStdin()
-  }
-  if (!password) fail('no password given')
-  out(hashPassword(password))
-}
-
-function help() {
-  out(`
-${bold('kestrel')} ${dim(`v${pkg.version}`)}
-
-  ${bold('kestrel init')} [dir]        scaffold a runnable Kestrel project (default: the current directory)
-  ${bold('kestrel doctor')} [dir]      check a project for the things that silently break /admin
-  ${bold('kestrel hash-password')} [p] print a KESTREL_ADMIN_PASSWORD_HASH value
-  ${bold('kestrel secret')}            print a KESTREL_SESSION_SECRET value
-
-${bold('init flags')}
-  --name <name>       package name (default: the directory name, slugified)
-  --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)
-
-${dim('Existing files are kept and re-running init is safe. To create a NEW project: pnpm create kestrel')}
-`)
-}
-
-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)
-else if (command === 'doctor') process.exitCode = doctor(positional)
-else if (command === 'hash-password') await hashPasswordCommand(positional)
-else if (command === 'secret') out(sessionSecret())
-else fail(`unknown command "${command}" — run \`kestrel help\`.`)

package/scripts/lib/cli.mjs

@@ -1,129 +0,0 @@
-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
-
-/**
- * `booleans` never consume the following token, so `init --force my-site` keeps `my-site` as the target
- * rather than scaffolding over the current directory. `--` ends flag parsing.
- */
-export function parseArgs(argv, booleans = []) {
-  const isBoolean = new Set(booleans)
-  const flags = {}
-  const positional = []
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i]
-    if (a === '--') {
-      positional.push(...argv.slice(i + 1))
-      break
-    }
-    if (a === '-h') {
-      flags.help = true
-      continue
-    }
-    if (a === '-v') {
-      flags.version = true
-      continue
-    }
-    if (!a.startsWith('--')) {
-      positional.push(a)
-      continue
-    }
-    const [key, inline] = a.slice(2).split(/=(.*)/s)
-    if (inline !== undefined) flags[key] = inline
-    else if (!isBoolean.has(key) && i + 1 < argv.length && !argv[i + 1].startsWith('-')) flags[key] = argv[++i]
-    else flags[key] = true
-  }
-  return { flags, positional }
-}
-
-export function makePaint(stream = process.stdout) {
-  const on = stream.isTTY && !process.env.NO_COLOR
-  const wrap = (code) => (s) => (on ? `\u001b[${code}m${s}\u001b[0m` : s)
-  return { dim: wrap(2), bold: wrap(1), red: wrap(31), yellow: wrap(33), green: wrap(32) }
-}
-
-export const out = (s = '') => process.stdout.write(`${s}\n`)
-
-export const readIf = (file) => (existsSync(file) ? readFileSync(file, 'utf8') : null)
-
-/** `mode` is applied even when the file already exists, which `writeFileSync` alone does not do. */
-export function write(file, content, mode) {
-  mkdirSync(dirname(file), { recursive: true })
-  writeFileSync(file, content, mode === undefined ? undefined : { mode })
-  if (mode !== undefined) chmodSync(file, mode)
-}
-
-/** Every file under `dir`, as `/`-separated paths relative to it. */
-export function walk(dir, base = dir) {
-  const found = []
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const full = join(dir, entry.name)
-    if (entry.isDirectory()) found.push(...walk(full, base))
-    else found.push(relative(base, full).split('\\').join('/'))
-  }
-  return found
-}
-
-/** Reads a line 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('')).trim()
-  } finally {
-    write('\n')
-  }
-}
-
-export class Cancelled extends Error {}
-
-/**
- * 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
-      }
-      if (first === undefined) throw new Cancelled()
-      return first
-    }
-  } finally {
-    rl.close()
-  }
-}
-
-/** All of stdin as a string; `''` at EOF, which the callers turn into a clean error. */
-export async function readStdin() {
-  let text = ''
-  for await (const chunk of process.stdin) text += chunk
-  return text.split('\n')[0].trim()
-}