@curia-sh/cli 0.4.1

package/src/config.mjs

@@ -0,0 +1,289 @@
+import { lstatSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { writeAtomically } from './atomic.mjs'
+
+// The operator configuration contract: `config/config.yaml` inside the
+// installation root. This module is the one reader, validator, and writer of
+// that file. The lifecycle interface, the Curia service, and the Curia app all
+// go through it, so one file means one thing in three processes and a refusal
+// reads the same in each.
+//
+// The file holds operator intent and nothing else. Generated state, release
+// metadata, and secrets have their own homes (`state/`, the release manifest,
+// `secrets/`) and never appear here. Every key is optional: a key the operator
+// does not set takes the service's shipped default, and the first installation
+// writes `max_concurrent: 4` and no other value.
+//
+// The file is read as a plain subset of YAML: `key: value` lines, comments, and
+// the `watch` list as `- repo: owner/name` entries. Anchors, flow collections,
+// block scalars, and other YAML are refused by line rather than guessed at.
+// That keeps the reader dependency-free, which the lifecycle interface has to
+// be, and it keeps a hand edit either exactly what the operator wrote or an
+// exact error. Curia never rewrites an edit into a different meaning.
+
+export const WATCH_MODES = Object.freeze(['auto', 'map', 'ready-for-agent'])
+
+const REPO_RE = /^[\w.-]+\/[\w.-]+$/
+
+const wholeNumber = (text) => (/^\d+$/.test(text) ? Number(text) : undefined)
+const number = (text) => (/^\d+(\.\d+)?$/.test(text) ? Number(text) : undefined)
+const positiveInteger = (v) => Number.isInteger(v) && v > 0
+
+// One rule per scalar key: how a written value reads, what a value must
+// satisfy, and the words a refusal uses. The same `check` judges a value the
+// app hands over as an object, so the two paths cannot disagree.
+const SCALAR_RULES = {
+  max_concurrent: { parse: wholeNumber, check: positiveInteger, rule: 'a positive whole number' },
+  auto_dispatch: {
+    parse: (text) => ({ true: true, false: false })[text],
+    check: (v) => typeof v === 'boolean',
+    rule: 'true or false',
+  },
+  poll_interval_s: { parse: number, check: (v) => typeof v === 'number' && Number.isFinite(v) && v > 0, rule: 'a positive number' },
+  prototype_variations: { parse: wholeNumber, check: positiveInteger, rule: 'a positive whole number' },
+  messages_per_send: {
+    parse: wholeNumber,
+    check: (v) => Number.isInteger(v) && v >= 1 && v <= 4,
+    rule: 'a whole number from 1 through 4',
+  },
+  live_pane_cap: { parse: wholeNumber, check: positiveInteger, rule: 'a positive whole number' },
+}
+
+// The keys, in the order the operator documentation lists them and the order
+// a written file carries them.
+export const OPERATOR_CONFIG_KEYS = Object.freeze([...Object.keys(SCALAR_RULES), 'watch'])
+
+const WATCH_RULE = '`watch` must be a list written as `- repo: owner/name` lines'
+const WATCH_EMPTY = '`watch` must list at least one `- repo: owner/name` entry'
+
+export class ConfigError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'ConfigError'
+  }
+}
+
+export function operatorConfigPath(root) {
+  return join(root, 'config', 'config.yaml')
+}
+
+// What `curia install` writes into a fresh root: the one value the first
+// release fixes, and no operator-specific default.
+export function initialOperatorConfig() {
+  return { max_concurrent: 4 }
+}
+
+// ---------------------------------------------------------------------------
+// reading
+// ---------------------------------------------------------------------------
+
+// Parses the text of a configuration file and returns the validated
+// configuration: an object holding only the keys the file sets, each in its
+// checked form. `file` names the file in every message.
+export function parseOperatorConfig(text, { file }) {
+  const at = (line, message) => new ConfigError(`${file} line ${line}: ${message}`)
+  const got = (value) => `(got ${value === '' ? 'nothing' : value})`
+  const config = {}
+  const lines = text.split('\n')
+
+  // The `watch` list under construction, or null outside it.
+  let list = null
+  const closeEntry = () => {
+    const entry = list.entries.at(-1)
+    if (!entry) return
+    if (entry.repo === undefined) throw at(entry.line, `\`watch\` entry ${list.entries.length} needs a \`repo\``)
+  }
+  const closeList = () => {
+    if (!list) return
+    if (list.entries.length === 0) throw at(list.line, WATCH_EMPTY)
+    closeEntry()
+    config.watch = list.entries.map((e) => ({ repo: e.repo, mode: e.mode ?? 'auto' }))
+    list = null
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const n = i + 1
+    const raw = lines[i]
+    if (raw.includes('\t')) throw at(n, 'tabs are not allowed; indent with spaces')
+    const line = stripComment(raw)
+    if (line.trim() === '') continue
+    const indent = line.length - line.trimStart().length
+    const body = line.trim()
+
+    if (indent === 0) {
+      closeList()
+      const m = /^([A-Za-z_][A-Za-z0-9_]*):(?:\s+(.*))?$/.exec(body)
+      if (!m) throw at(n, 'expected `key: value`')
+      const [, key, value = ''] = m
+      if (!OPERATOR_CONFIG_KEYS.includes(key)) {
+        throw at(n, `\`${key}\` is not an operator configuration key. The keys are ${OPERATOR_CONFIG_KEYS.join(', ')}`)
+      }
+      if (key in config || (list && key === 'watch')) throw at(n, `\`${key}\` appears twice`)
+      if (key === 'watch') {
+        if (value !== '') throw at(n, WATCH_RULE)
+        list = { line: n, entries: [] }
+        continue
+      }
+      const rule = SCALAR_RULES[key]
+      const parsed = rule.parse(unquote(value))
+      if (parsed === undefined || !rule.check(parsed)) throw at(n, `\`${key}\` must be ${rule.rule} ${got(value)}`)
+      config[key] = parsed
+      continue
+    }
+
+    if (!list) throw at(n, 'expected `key: value` at the start of the line')
+    let entryBody = body
+    if (body.startsWith('- ')) {
+      if (indent !== 2) throw at(n, WATCH_RULE)
+      closeEntry()
+      list.entries.push({ line: n })
+      entryBody = body.slice(2).trim()
+    } else if (indent !== 4 || list.entries.length === 0) {
+      throw at(n, WATCH_RULE)
+    }
+    const entry = list.entries.at(-1)
+    const index = list.entries.length
+    const m = /^([A-Za-z_][A-Za-z0-9_]*):(?:\s+(.*))?$/.exec(entryBody)
+    if (!m) throw at(n, WATCH_RULE)
+    const [, key, value = ''] = m
+    if (key !== 'repo' && key !== 'mode') throw at(n, `\`watch\` entry ${index}: \`${key}\` is not a watch entry key`)
+    if (key in entry) throw at(n, `\`watch\` entry ${index}: \`${key}\` appears twice`)
+    const text = unquote(value)
+    if (key === 'repo') {
+      if (!REPO_RE.test(text)) throw at(n, `\`watch\` entry ${index}: \`repo\` must be \`owner/name\` ${got(value)}`)
+      if (list.entries.some((e) => e !== entry && e.repo === text)) throw at(n, `\`watch\` lists ${text} twice`)
+    } else if (!WATCH_MODES.includes(text)) {
+      throw at(n, `\`watch\` entry ${index}: \`mode\` must be one of ${WATCH_MODES.join(', ')} ${got(value)}`)
+    }
+    entry[key] = text
+  }
+  closeList()
+  return config
+}
+
+// A `#` starts a comment at the start of a line or after whitespace, outside
+// quotes. Values here never legitimately hold one.
+function stripComment(line) {
+  let quote = null
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i]
+    if (quote) {
+      if (c === quote) quote = null
+    } else if (c === '"' || c === "'") {
+      quote = c
+    } else if (c === '#' && (i === 0 || /\s/.test(line[i - 1]))) {
+      return line.slice(0, i)
+    }
+  }
+  return line
+}
+
+function unquote(value) {
+  const m = /^(["'])(.*)\1$/.exec(value)
+  return m ? m[2] : value
+}
+
+// Returns the validated configuration, or null when the file does not exist.
+// A symbolic link at the path is refused: the file is owner-only and lives in
+// `config/`, and a link would let it read from anywhere.
+export function readOperatorConfig(path) {
+  let text
+  try {
+    if (lstatSync(path).isSymbolicLink()) {
+      throw new ConfigError(`${path} is a symbolic link. Replace the link with the real file.`)
+    }
+    text = readFileSync(path, 'utf8')
+  } catch (e) {
+    if (e.code === 'ENOENT') return null
+    throw e
+  }
+  return parseOperatorConfig(text, { file: path })
+}
+
+// ---------------------------------------------------------------------------
+// validating an object, and writing
+// ---------------------------------------------------------------------------
+
+// Judges a configuration handed over as an object (the app's save, the
+// installer's initial file) by the same rules the reader applies, and returns
+// it with the keys in contract order.
+export function validateOperatorConfig(data) {
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    throw new ConfigError('the operator configuration must be a mapping of keys to values')
+  }
+  for (const key of Object.keys(data)) {
+    if (!OPERATOR_CONFIG_KEYS.includes(key)) {
+      throw new ConfigError(`\`${key}\` is not an operator configuration key. The keys are ${OPERATOR_CONFIG_KEYS.join(', ')}`)
+    }
+  }
+  const out = {}
+  for (const [key, rule] of Object.entries(SCALAR_RULES)) {
+    if (data[key] === undefined) continue
+    if (!rule.check(data[key])) throw new ConfigError(`\`${key}\` must be ${rule.rule} (got ${JSON.stringify(data[key])})`)
+    out[key] = data[key]
+  }
+  if (data.watch !== undefined) {
+    if (!Array.isArray(data.watch)) throw new ConfigError(WATCH_RULE)
+    if (data.watch.length === 0) throw new ConfigError(WATCH_EMPTY)
+    const seen = new Set()
+    out.watch = data.watch.map((entry, i) => {
+      const index = i + 1
+      if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) throw new ConfigError(WATCH_RULE)
+      for (const key of Object.keys(entry)) {
+        if (key !== 'repo' && key !== 'mode') throw new ConfigError(`\`watch\` entry ${index}: \`${key}\` is not a watch entry key`)
+      }
+      if (typeof entry.repo !== 'string' || !REPO_RE.test(entry.repo)) {
+        throw new ConfigError(`\`watch\` entry ${index}: \`repo\` must be \`owner/name\` (got ${JSON.stringify(entry.repo ?? '')})`)
+      }
+      if (seen.has(entry.repo)) throw new ConfigError(`\`watch\` lists ${entry.repo} twice`)
+      seen.add(entry.repo)
+      const mode = entry.mode ?? 'auto'
+      if (!WATCH_MODES.includes(mode)) {
+        throw new ConfigError(`\`watch\` entry ${index}: \`mode\` must be one of ${WATCH_MODES.join(', ')} (got ${JSON.stringify(entry.mode)})`)
+      }
+      return { repo: entry.repo, mode }
+    })
+  }
+  return out
+}
+
+const HEADER = [
+  '# Curia operator configuration.',
+  '#',
+  '# Curia reads this file when the service starts and when the Curia app saves',
+  '# a setting. A key you leave out takes the shipped default. Curia checks the',
+  '# file before every write and refuses an invalid edit by line, so what is',
+  '# here is either exactly what you wrote or an exact error.',
+  '#',
+  '# The keys, and what each accepts, are documented in the operator guide under',
+  '# "Operator configuration". The Curia app rewrites this file when you save, and',
+  '# it keeps only the keys, not the comments.',
+  '',
+]
+
+// The text of a configuration file for `config`, validated first. Keys print
+// in contract order, and a watch entry prints its mode only when it is not
+// the default, so a file round-trips through the reader unchanged in meaning.
+export function renderOperatorConfig(data) {
+  const config = validateOperatorConfig(data)
+  const lines = [...HEADER]
+  for (const key of Object.keys(SCALAR_RULES)) {
+    if (config[key] !== undefined) lines.push(`${key}: ${config[key]}`)
+  }
+  if (config.watch) {
+    lines.push('watch:')
+    for (const entry of config.watch) {
+      lines.push(`  - repo: ${entry.repo}`)
+      if (entry.mode !== 'auto') lines.push(`    mode: ${entry.mode}`)
+    }
+  }
+  return `${lines.join('\n')}\n`
+}
+
+// Validates, renders, and writes the file atomically with owner-only mode. An
+// invalid configuration throws before anything touches the disk.
+export function writeOperatorConfig(path, data) {
+  const text = renderOperatorConfig(data)
+  writeAtomically(path, text, { mode: 0o600 })
+}

package/src/doctor.mjs

@@ -0,0 +1,392 @@
+import { existsSync } from 'node:fs'
+
+import { BOOTSTRAP_COMMAND } from './acquire.mjs'
+import { EXIT } from './exit.mjs'
+import { ConfigError, operatorConfigPath, readOperatorConfig } from './config.mjs'
+import { composeProject, dockerRunner, serviceStates } from './compose.mjs'
+import { APP_SERVE_PORT } from './install.mjs'
+import { launcherPath } from './launcher.mjs'
+import { SERVICES } from './layout.mjs'
+import { releaseProbes, verifyInstalledRelease } from './manifest.mjs'
+import { hostProbes, preflight } from './preflight.mjs'
+import { openRoot, versionPaths } from './root.mjs'
+import { SECRET_NAMES, credentialsInEnvironment, secretsStatus } from './secrets.mjs'
+
+// `curia doctor` (#881, implementing #857): one read-only pass over every
+// direct check an installed Curia has, in the order an operator would look.
+//
+//   host           the supported-host preflight, the same checks `curia
+//                  install` and `curia update` run
+//   installation   the root boundary, the record, the active version's
+//                  files, and the launcher
+//   configuration  `config/config.yaml` through the operator configuration
+//                  contract
+//   release        the retained artifacts of the active version, the
+//                  installed files, and the publication provenance
+//   secrets        the four secret files by presence, and the shell
+//                  environment by key
+//   containers     the state and health of the five services from Compose
+//   service        the service answers on loopback
+//   integrations   the four cards and the Full-loop gate, as the running
+//                  service verifies them on this read, and the operator it
+//                  admits
+//   app            the Curia app answers on loopback, and its tailnet address
+//
+// Every check is `{ name, status, observed, action }`, the shape the preflight
+// and the release verification already use, with `status` one of `passed`,
+// `warning`, `failed`, or `refused`. A failed or refused check carries one
+// corrective action. The command reruns every applicable check on every
+// invocation, keeps no history, and repairs nothing: it opens the root, reads
+// files, asks Docker for `ps`, and sends two reads to the service and one to
+// the app. It never escalates, retries in the background, or schedules
+// anything. The exit code is `ok` when nothing failed, `failed` when a check
+// failed or a host condition is refused, and `refused` only when the root
+// boundary refuses before anything runs.
+//
+// Everything printed passes through `redactDiagnostic`, so a secret that
+// reaches the doctor through an error message, a service answer, or a Docker
+// message never reaches the terminal. The doctor reads no secret value
+// itself: `secretsStatus` reports presence only.
+
+export const DOCTOR_SECTIONS = Object.freeze(['host', 'installation', 'configuration', 'release', 'secrets', 'containers', 'service', 'integrations', 'app'])
+
+// The service's own loopback listener (the `/ping` route the bundle's health
+// check asks) and the Curia app's loopback port, `dashboard.port` in
+// config/curia.yaml. daemon/test/preflightports.test.mjs keeps the app port
+// equal to the shipped configuration.
+export const SERVICE_PORT = 4271
+export const APP_PORT = 4273
+
+const READ_TIMEOUT_MS = 10_000
+const BOOTSTRAP = BOOTSTRAP_COMMAND
+const AGAIN = 'run curia doctor again'
+
+const CARD_NAMES = Object.freeze({ github: 'GitHub', discord: 'Discord', tailscale: 'Tailscale', model: 'model provider' })
+
+export async function runDoctor(
+  { env, stdout, uid, root },
+  { hostProbes: host = hostProbes, releaseProbes: release = releaseProbes, docker = dockerRunner, fetch: fetchImpl = globalThis.fetch } = {},
+) {
+  // The root boundary first, like every lifecycle command. A refusal here is
+  // the one refusal the doctor raises: it says nothing about the host until
+  // it knows the root is the operator's own.
+  const opened = openRoot(root, { uid })
+  const report = reporter(stdout)
+
+  report.section('host')
+  const hostReport = await preflight({ uid, root }, host)
+  report.checks(hostReport.checks)
+
+  report.section('installation')
+  report.checks([installationCheck({ opened, root, env })])
+  if (opened.status !== 'installed') {
+    report.note('the remaining checks need an installation.')
+    return report.finish()
+  }
+  const version = opened.record.activeVersion
+
+  report.section('configuration')
+  report.checks([configurationCheck(root)])
+
+  report.section('release')
+  const releaseReport = await verifyInstalledRelease({ root, version, stdout: { write: () => true } }, release)
+  report.checks(releaseReport.checks)
+
+  report.section('secrets')
+  report.checks([secretsCheck(root, uid), environmentCheck(env)])
+
+  report.section('containers')
+  const project = composeProject({ root, version })
+  report.checks([await containersCheck(project, docker)])
+
+  report.section('service')
+  const read = reader(fetchImpl)
+  const service = await serviceCheck(read, project)
+  report.checks([service])
+
+  report.section('integrations')
+  let address = null
+  if (service.status === 'passed') {
+    const setup = await read.json(`http://127.0.0.1:${SERVICE_PORT}/setup`)
+    const identity = await read.json(`http://127.0.0.1:${SERVICE_PORT}/identity`)
+    const checks = integrationChecks(setup)
+    report.checks([...checks.checks, operatorCheck(identity)])
+    address = checks.address
+  } else {
+    report.note('integrations not checked: the service did not answer.')
+  }
+
+  report.section('app')
+  report.checks([await appCheck(read, { project, address: address ?? hostReport.facts.tailscale?.certDomains?.[0] ?? null })])
+
+  return report.finish()
+}
+
+// ---------------------------------------------------------------------------
+// The checks. Each returns one result in the shared shape.
+
+function passed(name, observed) { return { name, status: 'passed', observed, action: null } }
+function warning(name, observed, action) { return { name, status: 'warning', observed, action } }
+function failed(name, observed, action) { return { name, status: 'failed', observed, action } }
+
+function installationCheck({ opened, root, env }) {
+  if (opened.status !== 'installed') {
+    return failed('installation', `${root} holds no installation.`, `Run the bootstrap: ${BOOTSTRAP}`)
+  }
+  const { activeVersion, installationId } = opened.record
+  const paths = versionPaths(root, activeVersion)
+  const missing = ['node', 'cli', 'manifest', 'package', 'bundleArchive', 'bundleChecksum', 'bundle'].filter((k) => !existsSync(paths[k]))
+  if (missing.length > 0) {
+    return failed('installation', `version ${activeVersion} is active, but ${paths.dir} lacks ${missing.map((k) => paths[k].slice(paths.dir.length + 1)).join(', ')}.`, `Run 'curia reinstall' to restore the version from the release, or the bootstrap: ${BOOTSTRAP}`)
+  }
+  const launcher = launcherPath(env)
+  const seen = `version ${activeVersion} (installation ${installationId}) at ${root}`
+  if (!existsSync(launcher)) {
+    return warning('installation', `${seen}; the launcher ${launcher} is missing.`, `Run 'curia reinstall' from the installed version to write the launcher again.`)
+  }
+  return passed('installation', `${seen}; launcher ${launcher}`)
+}
+
+function configurationCheck(root) {
+  const path = operatorConfigPath(root)
+  let config
+  try {
+    config = readOperatorConfig(path)
+  } catch (e) {
+    if (!(e instanceof ConfigError)) throw e
+    return failed('operator configuration', e.message, 'Fix that line or revert the file, then save any setting from the Curia app or restart the service.')
+  }
+  if (config === null) {
+    return warning('operator configuration', `${path} is absent, so the shipped defaults apply.`, `Run 'curia reinstall' to write the initial configuration, or create the file.`)
+  }
+  const keys = Object.entries(config).map(([k, v]) => (k === 'watch' ? `watch: ${v.length} ${v.length === 1 ? 'repository' : 'repositories'}` : `${k}: ${v}`))
+  return passed('operator configuration', `${path} is valid${keys.length ? ` (${keys.join(', ')})` : ''}`)
+}
+
+function secretsCheck(root, uid) {
+  const status = secretsStatus(root, { uid })
+  const of = (state) => SECRET_NAMES.filter((n) => status[n].state === state)
+  const presence = [
+    of('present').length ? `present: ${of('present').join(', ')}` : 'none present',
+    of('absent').length ? `absent: ${of('absent').join(', ')}` : null,
+  ].filter(Boolean).join('; ')
+  const refused = of('refused')
+  if (refused.length > 0) {
+    return failed('secret files', `${refused.map((n) => status[n].why).join(' ')} ${presence}.`, `After the fix, ${AGAIN}.`)
+  }
+  return passed('secret files', presence)
+}
+
+function environmentCheck(env) {
+  const keys = credentialsInEnvironment(env ?? {})
+  if (keys.length === 0) return passed('environment', 'no credential key is set in this shell')
+  return warning('environment', `${keys.join(', ')} ${keys.length === 1 ? 'is' : 'are'} set in this shell. Curia reads a credential from its secret file only, and the service refuses to boot with one of these keys set.`, `Unset ${keys.length === 1 ? 'it' : 'them'}. The secret files are ${SECRET_NAMES.map((n) => `secrets/${n}`).join(', ')}.`)
+}
+
+function logsCommand(project, service) {
+  return `docker compose --env-file ${project.envFile} -f ${project.file} logs ${service}`
+}
+
+async function containersCheck(project, docker) {
+  if (!existsSync(project.envFile)) {
+    return failed('containers', `${project.envFile} is missing, so the Compose project cannot be addressed.`, `Run 'curia reinstall' to write it and start the project again.`)
+  }
+  let states
+  try {
+    states = await serviceStates(project, { docker })
+  } catch (e) {
+    return failed('containers', oneLine(e.message), `Fix Docker access for this user, then ${AGAIN}.`)
+  }
+  const problems = []
+  const starting = []
+  for (const service of SERVICES) {
+    const s = states.find((x) => x.service === service)
+    if (!s) problems.push({ service, what: `${service} is not in the project` })
+    else if (s.state === 'exited' || s.state === 'dead') problems.push({ service, what: `${service} exited with code ${s.exitCode ?? '?'}` })
+    else if (s.health === 'unhealthy') problems.push({ service, what: `${service} is unhealthy` })
+    else if (s.health !== 'healthy') starting.push(service)
+  }
+  if (problems.length > 0) {
+    const all = [...problems.map((p) => p.what), ...starting.map((s) => `${s} is starting`)]
+    return failed('containers', `${all.join('; ')}.`, `Read its log with '${logsCommand(project, problems[0].service)}', fix the cause, and ${problems[0].what.endsWith('in the project') ? "run 'curia reinstall'" : 'start the service again'}.`)
+  }
+  if (starting.length > 0) {
+    return warning('containers', `${starting.map((s) => `${s} is starting`).join('; ')}; the rest are healthy.`, `Wait a minute and ${AGAIN}. A service still starting after four minutes is one to read the log of: '${logsCommand(project, starting[0])}'.`)
+  }
+  return passed('containers', `${SERVICES.join(', ')} healthy`)
+}
+
+async function serviceCheck(read, project) {
+  const at = `127.0.0.1:${SERVICE_PORT}`
+  const answer = await read.json(`http://${at}/ping`)
+  if (answer.ok) return passed('service', `the service answers on ${at}`)
+  return failed('service', `the service did not answer on ${at} (${answer.error}).`, `Read its log with '${logsCommand(project, 'daemon')}', fix the cause, and ${AGAIN}.`)
+}
+
+// The four cards and the gate, as the service verified them on this read.
+// Nothing here comes from a file: a card is connected only because its
+// verifier said so now.
+function integrationChecks(setup) {
+  if (!setup.ok) {
+    return { checks: [failed('integrations', `the service did not answer GET /setup (${setup.error}).`, `Read its log and ${AGAIN}.`)], address: null }
+  }
+  const body = setup.body ?? {}
+  const cards = Array.isArray(body.cards) ? body.cards : []
+  const checks = []
+  let address = null
+  for (const key of Object.keys(CARD_NAMES)) {
+    const name = CARD_NAMES[key]
+    const card = cards.find((c) => c?.key === key)
+    if (!card) { checks.push(failed(name, 'the service reported no such card.', `Update Curia, then ${AGAIN}.`)); continue }
+    if (card.state === 'connected') {
+      const footer = card.footer ?? {}
+      checks.push(passed(name, [footer.primary, footer.secondary].filter(Boolean).join(' · ') || 'connected and verified'))
+      if (key === 'tailscale') address = card.detail?.app_url ?? (card.detail?.address ? `https://${card.detail.address}:${APP_SERVE_PORT}/` : null)
+    } else if (card.state === 'failed') {
+      checks.push(failed(name, String(card.error?.failed ?? 'the verification did not pass.'), String(card.error?.action ?? 'Open the Curia app, select Setup, and select Try again.')))
+    } else if (card.state === 'unavailable') {
+      checks.push(warning(name, 'not available in this release.', 'Update Curia when a release adds it.'))
+    } else {
+      checks.push(warning(name, 'not connected yet.', `Open the Curia app, select Setup, and connect ${key === 'model' ? 'a model provider' : name}.`))
+    }
+  }
+  const loop = body.full_loop ?? {}
+  if (loop.ready) checks.push(passed('Full loop', 'ready on this read: every card verified and handed its fact'))
+  else checks.push(warning('Full loop', String(loop.reason ?? 'not ready.'), 'Finish setup in the Curia app; Run Full loop enables when every card is connected on one read.'))
+  return { checks, address }
+}
+
+function operatorCheck(identity) {
+  if (!identity.ok) return failed('admitted operator', `the service did not answer GET /identity (${identity.error}).`, `Read its log and ${AGAIN}.`)
+  const allow = Array.isArray(identity.body?.allow) ? identity.body.allow.map(String) : []
+  if (allow.length > 0) return passed('admitted operator', allow.join(', '))
+  if (identity.body?.first_operator) {
+    return warning('admitted operator', 'no operator confirmed; the app admits the first tailnet identity to Setup only.', 'Open the Curia app from your tailnet and select Confirm operator and verify on the Tailscale card.')
+  }
+  return warning('admitted operator', 'the service admits no login.', 'Confirm the operator on the Tailscale card of Setup.')
+}
+
+async function appCheck(read, { project, address }) {
+  const at = `127.0.0.1:${APP_PORT}`
+  const answer = await read.status(`http://${at}/`)
+  const url = address ? (address.startsWith('https://') ? address : `https://${address}:${APP_SERVE_PORT}/`) : null
+  if (answer.ok) return passed('Curia app', `the app answers on ${at}${url ? `; open it at ${url}` : ''}`)
+  return failed('Curia app', `the app did not answer on ${at} (${answer.error}).`, `Read its log with '${logsCommand(project, 'dashboard')}', fix the cause, and ${AGAIN}.`)
+}
+
+// ---------------------------------------------------------------------------
+// The two reads: a JSON route and a bare status. Both answer instead of
+// throwing, and both scrub what comes back before it is used.
+
+function reader(fetchImpl) {
+  const get = (url) => fetchImpl(url, { redirect: 'manual', signal: AbortSignal.timeout(READ_TIMEOUT_MS) })
+  return {
+    async json(url) {
+      try {
+        const response = await get(url)
+        if (!response.ok) return { ok: false, error: `HTTP ${response.status}` }
+        return { ok: true, body: scrubFacts(await response.json()) }
+      } catch (e) {
+        return { ok: false, error: oneLine(e.cause?.message ?? e.message) }
+      }
+    },
+    async status(url) {
+      try {
+        const response = await get(url)
+        if (response.status >= 500) return { ok: false, error: `HTTP ${response.status}` }
+        return { ok: true, status: response.status }
+      } catch (e) {
+        return { ok: false, error: oneLine(e.cause?.message ?? e.message) }
+      }
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Redaction. Two layers: values under a key that names a credential are
+// dropped from every service answer before the doctor reads it, and every
+// printed line loses any string shaped like a long-lived secret (a Discord
+// bot token, a provider key, a GitHub token, a private key), a renewable or
+// session token (a JWT, a bearer, a 64-hex agent or conversation token), or
+// a one-turn value carried as `code=` or `token=`. A `sha256:` digest and the
+// 32-hex installation ID are not secrets and stay.
+
+const SECRET_KEY = /^(token|secret|password|pem|private_key|api_key|access_token|refresh_token|id_token|device_code|user_code|code|capability|authorization|bearer)$|(?:_|-)(token|secret|key|code|capability)$/i
+
+export function scrubFacts(value) {
+  if (Array.isArray(value)) return value.map(scrubFacts)
+  if (value && typeof value === 'object') {
+    const out = {}
+    for (const [k, v] of Object.entries(value)) out[k] = SECRET_KEY.test(k) && typeof v === 'string' ? '[redacted]' : scrubFacts(v)
+    return out
+  }
+  return value
+}
+
+const REDACTIONS = [
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, '[redacted]'],
+  [/\b(Bearer|Bot|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/g, '$1 [redacted]'],
+  [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, '[redacted]'],
+  [/\b[A-Za-z0-9_-]{23,28}\.[A-Za-z0-9_-]{6,7}\.[A-Za-z0-9_-]{25,}/g, '[redacted]'],
+  [/\bsk-[A-Za-z0-9_-]{16,}/g, '[redacted]'],
+  [/\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{16,}/g, '[redacted]'],
+  [/\bgithub_pat_[A-Za-z0-9_]{16,}/g, '[redacted]'],
+  [/\b(?<!sha256:)[0-9a-f]{48,}\b/gi, '[redacted]'],
+  [/\b(token|secret|password|code|key|capability|session_id|api_key)=([^\s&"']+)/gi, '$1=[redacted]'],
+]
+
+export function redactDiagnostic(text) {
+  let out = String(text)
+  for (const [pattern, replacement] of REDACTIONS) out = out.replace(pattern, replacement)
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// The report: sections, one line per check in the preflight's format, and a
+// summary that decides the exit code.
+
+const STATUS_WORD = { passed: 'ok', warning: 'warning', failed: 'failed', refused: 'refused' }
+
+function reporter(stdout) {
+  const all = []
+  let current = null
+  let pending = []
+  let notes = []
+  let printed = 0
+  const write = (text) => stdout.write(redactDiagnostic(text))
+  const flush = () => {
+    if (current === null) return
+    write(`${printed > 0 ? '\n' : ''}${current}\n`)
+    printed += 1
+    if (pending.length > 0) {
+      const width = Math.max(...pending.map((c) => c.name.length))
+      for (const c of pending) {
+        write(`${STATUS_WORD[c.status].padEnd(8)} ${c.name.padEnd(width)}  ${oneLine(c.observed)}\n`)
+        if (c.action) write(`${''.padEnd(9 + width + 2)}${oneLine(c.action)}\n`)
+      }
+    }
+    for (const note of notes) write(`${note}\n`)
+    notes = []
+    pending = []
+  }
+  return {
+    section(name) { flush(); current = name },
+    checks(results) { for (const c of results) { all.push(c); pending.push(c) } },
+    note(text) { notes.push(text) },
+    finish() {
+      flush()
+      const count = (status) => all.filter((c) => c.status === status).length
+      const broken = count('failed') + count('refused')
+      const warnings = count('warning')
+      const summary = [`${count('passed')} checks passed`]
+      if (warnings > 0) summary.push(`${warnings} warning${warnings === 1 ? '' : 's'}`)
+      if (broken > 0) summary.push(`failed: ${broken} condition${broken === 1 ? '' : 's'}`)
+      write(`\n${summary.join(', ')}.\n`)
+      return broken > 0 ? EXIT.failed : EXIT.ok
+    },
+  }
+}
+
+function oneLine(text) {
+  return String(text ?? '').split('\n').map((l) => l.trim()).filter(Boolean).join(' ')
+}