nervur 0.1.1 → 0.2.0

package/README.md

@@ -29,9 +29,14 @@ being family:   scaffold, deploy, species
   install                 Docker preflight, then stand a carcass at
                           NERVUR_HOME (default ~/.nervur)
   whoami · status         the carcass answers with its identity and state
-  identity add <name>     mint an identity on this machine (silent, idempotent)
+  identity add <name>     mint an identity on this machine (silent, idempotent);
+                          --key <file> adopts a brought ed25519 key instead —
+                          it never replaces an existing different owner
+  identity key <name>     print the identity's private key (base64url PKCS8),
+                          the exact shape --key accepts back
   identity list           identities on this machine · name + public id
-  identity remove <name>  destroy an identity — refused while beings remain
+  identity remove <name>  destroy an identity — refused while beings or
+                          sealed lineages remain (only an empty one goes)
   use [name]              select which identity add/list act as
   add <kind> [--as name]  add a being under the selected identity
   list · remove <name>    the fleet registry · retire a being

package/completion.js

@@ -0,0 +1,122 @@
+// nervur — shell completion (`nervur completion [bash|zsh]`). Client-local like
+// scaffold: touches no carcass. One verb table is the single truth; both scripts
+// are generated from it so a new verb lands in completion by editing one list.
+// No prompt anywhere: the shell is a positional with a sane default ($SHELL).
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+// verb → one-line description; subs/kinds drive second-position completion.
+export const VERBS = [
+  ['install', 'stand a published carcass at NERVUR_HOME'],
+  ['up', '(dev bench) preflight, then stand the ground'],
+  ['down', 'stop the ground'],
+  ['reset', 'stop the ground and wipe its data'],
+  ['preflight', 'run the bench preflight and report'],
+  ['whoami', 'ask the carcass who it is'],
+  ['status', 'ask the carcass for its status'],
+  ['identity', 'manage identities (add · key · list · remove)'],
+  ['use', 'select the identity the verbs act as'],
+  ['add', 'add a being under the selected identity'],
+  ['list', 'list the beings on the ground'],
+  ['remove', 'remove a being'],
+  ['scaffold', 'mint a species repo from a template'],
+  ['deploy', 'grant + pin + run a species'],
+  ['species', 'list deployed species and their pins'],
+  ['completion', 'print the shell completion script (bash · zsh)'],
+  ['help', 'show help']
+]
+
+const names = VERBS.map(([v]) => v).join(' ')
+
+const bash = () => `# nervur completion (bash)
+# load now:   eval "$(nervur completion bash)"
+# persist:    nervur completion bash >> ~/.bashrc   (or into bash_completion.d)
+_nervur() {
+  local cur prev
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  case "$prev" in
+    identity)   COMPREPLY=($(compgen -W "add key list remove" -- "$cur")); return ;;
+    completion) COMPREPLY=($(compgen -W "bash zsh" -- "$cur")); return ;;
+    add|--kind) COMPREPLY=($(compgen -W "empty" -- "$cur")); return ;;
+    --dir)      COMPREPLY=($(compgen -d -- "$cur")); return ;;
+  esac
+  case "$cur" in
+    --*) COMPREPLY=($(compgen -W "--as --no-door --kind --dir --key" -- "$cur")); return ;;
+  esac
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=($(compgen -W "${names}" -- "$cur"))
+  fi
+}
+complete -F _nervur nervur
+`
+
+const zsh = () => `#compdef nervur
+# nervur completion (zsh)
+# load now:   eval "$(nervur completion zsh)"
+# persist:    nervur completion zsh > "\${fpath[1]}/_nervur" && rm -f ~/.zcompdump; compinit
+_nervur() {
+  local -a verbs
+  verbs=(
+${VERBS.map(([v, d]) => `    '${v}:${d.replace(/'/g, "'\\''")}'`).join('\n')}
+  )
+  if (( CURRENT == 2 )); then
+    _describe 'verb' verbs
+    return
+  fi
+  case "\${words[2]}" in
+    identity)     (( CURRENT == 3 )) && _values 'sub' add key list remove ;;
+    completion)   (( CURRENT == 3 )) && _values 'shell' bash zsh ;;
+    add)          (( CURRENT == 3 )) && _values 'kind' empty ;;
+    scaffold)     _arguments '--kind[template kind]:kind:(empty)' '--dir[target directory]:dir:_directories' ;;
+    up|preflight) _arguments '--no-door[stand on localhost only (headless/CI)]' ;;
+  esac
+}
+if (( ! $+functions[compdef] )); then
+  autoload -Uz compinit
+  compinit
+fi
+compdef _nervur nervur
+`
+
+export function completionScript(shell) {
+  const which = shell ?? (process.env.SHELL?.endsWith('zsh') ? 'zsh' : 'bash')
+  if (which === 'zsh') return zsh()
+  if (which === 'bash') return bash()
+  throw new Error(`usage: nervur completion [bash|zsh] — '${which}' is not a shell I know`)
+}
+
+const MARK_OPEN = '# >>> nervur completion >>>'
+const MARK_CLOSE = '# <<< nervur completion <<<'
+
+// Wire completion for the operator's shell: the script lands as a file in the
+// nervur home and the rc file gains one marked source-block — sourcing a file
+// costs nothing per shell start, where `eval "$(nervur completion)"` would
+// spawn node every time. Idempotent by the marker block (the dev/hosts.sh
+// idiom): re-wiring rewrites the block in place, never stacks a second one.
+export function wireCompletion(home) {
+  const shell = process.env.SHELL?.endsWith('zsh')
+    ? 'zsh'
+    : process.env.SHELL?.endsWith('bash')
+      ? 'bash'
+      : null
+  if (!shell) return { wired: false }
+  mkdirSync(home, { recursive: true })
+  const scriptPath = join(home, `completion.${shell}`)
+  writeFileSync(scriptPath, completionScript(shell))
+  const rc = join(homedir(), shell === 'zsh' ? '.zshrc' : '.bashrc')
+  const block = `${MARK_OPEN}\n[ -f "${scriptPath}" ] && source "${scriptPath}"\n${MARK_CLOSE}\n`
+  const current = existsSync(rc) ? readFileSync(rc, 'utf8') : ''
+  if (current.includes(MARK_OPEN)) {
+    const next = current.replace(
+      current.slice(current.indexOf(MARK_OPEN), current.indexOf(MARK_CLOSE) + MARK_CLOSE.length + 1),
+      block
+    )
+    if (next !== current) writeFileSync(rc, next)
+  } else {
+    appendFileSync(rc, `${current && !current.endsWith('\n') ? '\n' : ''}\n${block}`)
+  }
+  return { wired: true, shell, rc, scriptPath }
+}

package/nervur.js

@@ -15,6 +15,8 @@ import { pathToFileURL } from 'node:url'
 import { resolveTemplate } from '@nervur-org/kit/templates.js'
 import { runPreflight, renderChain, blockingFailure } from './preflight.js'
 import { scaffoldSpecies } from './scaffold.js'
+import { completionScript, wireCompletion, VERBS } from './completion.js'
+import { banner, bold, columns, cyan, dim, heading, identityTree, red } from './style.js'
 
 // The one published tag — what `nervur install` pulls, and what a local
 // `docker build` must name for install to find it (papers/dev.md — "the
@@ -229,6 +231,7 @@ async function main() {
 
   const faceDomain = config.domains?.face
 
+  const bare = rawArgs.length === 0
   const [verb = 'whoami', ...args] = rawArgs
   const print = (v) => console.log(JSON.stringify(v, null, 2))
 
@@ -270,7 +273,7 @@ async function main() {
       console.log(renderChain(results))
       const blocked = blockingFailure(results)
       if (blocked) {
-        console.error(`\n  refusing: ${blocked.name} — ${blocked.note}\n  fix: ${blocked.fix}`)
+        console.error(`\n  ${red('refusing:')} ${blocked.name} — ${blocked.note}\n  ${dim('fix:')} ${blocked.fix}`)
         process.exit(1)
       }
 
@@ -314,8 +317,26 @@ async function main() {
 
       const localUrl = `http://localhost:${port}`
       await knock({ localUrl: `${localUrl}/health` })
-      console.log(`  · carcass standing at ${home} — face on ${localUrl}`)
       print(await getJson(`${localUrl}/whoami`))
+
+      // TTY-gated: CI, probes, and scripts must never gain an rc edit as a
+      // side effect of install; NERVUR_COMPLETION=0 opts a human out too.
+      let completionRow = ['shell', 'nervur completion', 'prints the autocomplete script']
+      if (process.stdout.isTTY && process.env.NERVUR_COMPLETION !== '0') {
+        const wired = wireCompletion(home)
+        if (wired.wired)
+          completionRow = ['shell', `${wired.shell} autocomplete wired`, `${wired.rc} — new shells complete`]
+      }
+
+      const consolePort = process.env.NERVUR_CONSOLE_PORT ?? '4200'
+      console.log(
+        banner('nervur is standing', [
+          ['console', cyan(`http://localhost:${consolePort}`), 'open in your browser'],
+          ['home', home, 'compose + ground config, kept across installs'],
+          completionRow,
+          ['next', 'nervur add empty', 'stand your first being']
+        ]) + `\n    ${dim(`api ${localUrl}`)}\n`
+      )
       break
     }
     case 'preflight': {
@@ -334,7 +355,7 @@ async function main() {
       console.log(renderChain(results))
       const blocked = blockingFailure(results)
       if (blocked) {
-        console.error(`\n  refusing: ${blocked.name} — ${blocked.note}\n  fix: ${blocked.fix}`)
+        console.error(`\n  ${red('refusing:')} ${blocked.name} — ${blocked.note}\n  ${dim('fix:')} ${blocked.fix}`)
         process.exit(1)
       }
       if (config.certs) sh('bash', [config.certs])
@@ -358,6 +379,14 @@ async function main() {
           )
         print(await getJson(`${face()}/whoami`))
       }
+      // The console is loopback-only by design (host.md — "One operator, one
+      // console"), so its URL is localhost even when the face answers through
+      // the domain door.
+      console.log(
+        banner('ground is standing', [
+          ['console', cyan(`http://localhost:${config.console?.port ?? 4200}`), 'open in your browser']
+        ]) + `\n    ${dim(`api ${via === 'domain' ? `https://${faceDomain}` : face()}`)}\n`
+      )
       break
     }
     case 'down':
@@ -369,9 +398,25 @@ async function main() {
       for (const dir of config.dataDirs ?? []) rmSync(dir, { recursive: true, force: true })
       console.log('reset')
       break
-    case 'whoami':
-      print(await getJson(`${face()}/whoami`))
+    case 'whoami': {
+      const who = await getJson(`${face()}/whoami`)
+      if (!bare || !process.stdout.isTTY) {
+        print(who)
+        break
+      }
+      const consoleUrl = `http://localhost:${process.env.NERVUR_CONSOLE_PORT ?? config.console?.port ?? 4200}`
+      const beings = who.beings ?? []
+      const tree = identityTree(who.identities ?? [], beings, selectedIdentity)
+      const hint = beings.length
+        ? ''
+        : `\n\n    ${dim('nervur add empty stands your first being')}`
+      console.log(
+        `\n${heading(`nervur — carcass ${who.health} ${dim(`· v${who.version}`)}`)}\n\n${tree}${hint}\n\n` +
+          `${columns([['console', cyan(consoleUrl), 'open in your browser']])}\n\n` +
+          `    ${dim(`api ${face()} · faces ${who.faces ?? '—'}`)}\n`
+      )
       break
+    }
     case 'status':
       print(await getJson(`${face()}/status`))
       break
@@ -383,22 +428,48 @@ async function main() {
         })
       )
       break
-    case 'list':
-      print(await getJson(`${face()}/fleet/list`))
+    case 'list': {
+      const fleet = await getJson(`${face()}/fleet/list`)
+      if (!process.stdout.isTTY) {
+        print(fleet)
+        break
+      }
+      const identities = (await getJson(`${face()}/identities`)).map((i) => i.name)
+      console.log(`\n${identityTree(identities, fleet, selectedIdentity)}\n`)
       break
+    }
     case 'remove':
       if (!args[0]) throw new Error('usage: nervur remove <name>')
       print(await postJson(`${face()}/fleet/remove`, { name: args[0] }))
       break
     // ── identities (papers/host.md — "The identities"): locally one carcass
-    //    custodies many, one vault each. `add` mints silently, `list` shows the
-    //    public ids only, `remove` refuses (409) while any being is attached —
-    //    never force, never prompt.
+    //    custodies many, one vault each. `add` mints silently — or adopts a brought
+    //    key (`--key`, the bring-your-own-key seed; a different key never replaces
+    //    an owner, 409). `list` shows the public ids only; `key` prints the owner's
+    //    private key (the export half, hand-to-self); `remove` refuses (409) while
+    //    any being is attached — never force, never prompt.
     case 'identity': {
       const [sub, name] = positional(args)
       if (sub === 'add') {
-        if (!name) throw new Error('usage: nervur identity add <name>')
-        print(await postJson(`${face()}/identities/add`, { name }))
+        if (!name) throw new Error('usage: nervur identity add <name> [--key <file>]')
+        const keyFile = flagValue(args, '--key')
+        const key = keyFile ? readFileSync(keyFile, 'utf8').trim() : undefined
+        const { status, body } = await postJsonStatus(`${face()}/identities/add`, { name, key })
+        if (status >= 400) {
+          console.error(`nervur: ${body.error}`)
+          process.exit(1)
+        }
+        print(body)
+      } else if (sub === 'key') {
+        if (!name) throw new Error('usage: nervur identity key <name>')
+        const { status, body } = await postJsonStatus(`${face()}/identities/key`, { name })
+        if (status >= 400) {
+          console.error(`nervur: ${body.error}`)
+          process.exit(1)
+        }
+        // The secret alone, pipe-friendly (`nervur identity key acme > key.txt`) —
+        // base64url PKCS8 DER, the exact shape `identity add --key` accepts back.
+        console.log(body.secret)
       } else if (sub === 'list') {
         const list = await getJson(`${face()}/identities`)
         for (const i of list)
@@ -407,10 +478,17 @@ async function main() {
         if (!name) throw new Error('usage: nervur identity remove <name>')
         const { status, body } = await postJsonStatus(`${face()}/identities/remove`, { name })
         if (status === 409) {
-          console.error(
-            `refused: identity '${name}' still has beings attached: ${body.beings.join(', ')}`
-          )
-          for (const b of body.beings) console.error(`  fix: nervur remove ${b}`)
+          if (body.beings) {
+            console.error(
+              `refused: identity '${name}' still has beings attached: ${body.beings.join(', ')}`
+            )
+            for (const b of body.beings) console.error(`  fix: nervur remove ${b}`)
+          } else {
+            console.error(
+              `refused: identity '${name}' still holds sealed lineages: ${body.lineages.join(', ')}`
+            )
+            console.error('  lineage destruction has no verb yet — the sealed custody stays')
+          }
           process.exit(1)
         }
         if (status >= 400) {
@@ -419,7 +497,7 @@ async function main() {
         }
         print(body)
       } else {
-        throw new Error('usage: nervur identity <add|list|remove> <name>')
+        throw new Error('usage: nervur identity <add|key|list|remove> <name>')
       }
       break
     }
@@ -431,6 +509,26 @@ async function main() {
         console.log(selectedIdentity)
         break
       }
+      // Sticky selection is a client act, but it selects a real vault — an
+      // unknown name is refused against the live list here, never stored to
+      // fail later as a runtime surprise on some other verb.
+      let known
+      try {
+        known = (await getJson(`${face()}/identities`)).map((i) => i.name)
+      } catch {
+        console.error(
+          `nervur: ${red(`cannot verify identity '${name}'`)} — no carcass answering at ${face()}\n` +
+            `  ${dim('fix:')} stand it first — nervur up (bench) or nervur install (published)`
+        )
+        process.exit(1)
+      }
+      if (!known.includes(name)) {
+        console.error(
+          `nervur: ${red(`no identity '${name}'`)} on this carcass — have: ${known.join(' · ') || '(none)'}\n` +
+            `  ${dim('fix:')} nervur identity add ${name}`
+        )
+        process.exit(1)
+      }
       mkdirSync(dirname(stickyPath), { recursive: true })
       writeFileSync(stickyPath, name)
       console.log(`using identity '${name}'`)
@@ -465,34 +563,61 @@ async function main() {
     case 'species':
       print(await getJson(`${face()}/deploy/list`))
       break
+    case 'completion':
+      process.stdout.write(completionScript(positional(args)[0]))
+      break
     case 'help':
     case '--help':
-    case '-h':
+    case '-h': {
+      // Help renders from the same VERBS table completion generates from — a
+      // verb missing here was never added to cli/completion.js.
+      const sig = {
+        up: '[--no-door]',
+        preflight: '[--no-door]',
+        identity: '<add|key|list|remove> [name] [--key <file>]',
+        use: '[name]',
+        add: '<kind> [--as <identity>]',
+        remove: '<name>',
+        scaffold: '<name> [--kind empty] [--dir <path>]',
+        deploy: '<name> <repo> <full-commit-hash>',
+        completion: '[bash|zsh]'
+      }
+      const carcass = new Set([
+        'install', 'up', 'down', 'reset', 'preflight', 'whoami', 'status',
+        'identity', 'use', 'add', 'list', 'remove'
+      ])
+      // Pad on the UNSTYLED signature so ANSI codes never skew the column.
+      const width = Math.max(...VERBS.map(([v]) => `${v} ${sig[v] ?? ''}`.trim().length))
+      const row = ([v, d]) => {
+        const plain = `${v}${sig[v] ? ` ${sig[v]}` : ''}`
+        const left = `${bold(v)}${sig[v] ? ` ${dim(sig[v])}` : ''}`
+        return `  ${left}${' '.repeat(width - plain.length + 2)}${d}`
+      }
       console.log(
-        'nervur — client of a running carcass\n\n' +
-          'carcass family: install, up, down, reset, preflight, whoami, status, identity, use, add, list, remove\n' +
-          'being family:   scaffold, deploy, species\n\n' +
-          '  install                Docker preflight, then stand a carcass at NERVUR_HOME (default ~/.nervur)\n' +
-          '                        [NERVUR_HOME, NERVUR_IMAGE, NERVUR_PORT, NERVUR_FACES_PORT]\n' +
-          '  up [--no-door]        (dev bench) run the bench preflight, then stand the ground\n' +
-          '  preflight [--no-door] run the bench preflight and report (exit code = verdict)\n' +
-          '  identity add <name>   mint an identity on this machine (silent, idempotent)\n' +
-          '  identity list         list identities on this machine · name + public id\n' +
-          '  identity remove <name> destroy an identity — refused (409) while beings remain\n' +
-          '  use [name]            select which identity add/list act as (client-only); no args prints it\n' +
-          '  add <kind> [--as name] add a being under the selected (or --as) identity\n' +
-          '  scaffold <name>       mint a species repo (the DNA) [--kind empty] [--dir <path>]\n' +
-          '  deploy <name> <repo> <full-commit-hash>   grant + pin + run a species\n' +
-          '  species               list the deployed species and their pins\n\n' +
-          'the door is open by default; --no-door (or NERVUR_DOOR=0) stands the ground\n' +
-          'on localhost only for headless/CI — the hosts check degrades, 443 is skipped'
+        `${bold('nervur')} — client of a running carcass\n\n` +
+          `${dim('usage')}  nervur <verb> [args] ${dim('[--as <identity>]')}\n\n` +
+          `${cyan('carcass family')}\n` +
+          VERBS.filter(([v]) => carcass.has(v)).map(row).join('\n') +
+          `\n\n${cyan('being family')}\n` +
+          VERBS.filter(([v]) => !carcass.has(v) && v !== 'help').map(row).join('\n') +
+          `\n\n${dim(
+            'install honors NERVUR_HOME · NERVUR_IMAGE · NERVUR_PORT · NERVUR_FACES_PORT · NERVUR_CONSOLE_PORT\n' +
+              'the door is open by default; --no-door (or NERVUR_DOOR=0) stands the ground\n' +
+              'on localhost only for headless/CI — the hosts check degrades, 443 is skipped'
+          )}`
       )
       break
-    default:
+    }
+    default: {
+      const known = VERBS.map(([v]) => v)
+      const near = known.filter((v) => v.startsWith(verb) || verb.startsWith(v.slice(0, 3)))
       console.error(
-        `nervur: unknown verb: ${verb} (have: install, up, down, reset, preflight, whoami, status, identity, use, add, list, remove, scaffold, deploy, species)`
+        `nervur: ${red(`unknown verb: ${verb}`)}` +
+          (near.length ? ` — did you mean ${near.map(bold).join(' · ')}?` : '') +
+          `\n${dim(`have: ${known.join(', ')}`)}`
       )
       process.exit(1)
+    }
   }
   process.exit(0)
 }
@@ -511,7 +636,7 @@ function invokedAsCli() {
 }
 if (invokedAsCli()) {
   main().catch((e) => {
-    console.error(`nervur: ${e.message}`)
+    console.error(`nervur: ${red(e.message)}`)
     process.exit(1)
   })
 }

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "nervur",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "The nervur CLI — a client of a running carcass, never the runtime (papers/host.md).",
   "type": "module",
   "bin": {
-    "nervur": "./nervur.js"
+    "nervur": "nervur.js"
   },
   "files": [
     "nervur.js",
     "preflight.js",
-    "scaffold.js"
+    "scaffold.js",
+    "completion.js",
+    "style.js"
   ],
   "dependencies": {
     "@nervur-org/kit": "^0.1.0"

package/preflight.js

@@ -14,6 +14,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { lookup } from 'node:dns/promises'
+import { dim, glyph } from './style.js'
 
 // Status vocabulary: 'ok' passes; 'fail' blocks (refuse at the door); 'warn' is
 // advisory — a real finding that never blocks (browser trust, the door-closed
@@ -146,13 +147,13 @@ export async function runPreflight(config, { door = true } = {}) {
   ]
 }
 
-const GLYPH = { ok: '✓', fail: '✗', warn: '!', skip: '·' }
-
 export function renderChain(results) {
   const lines = []
   for (const r of results) {
-    lines.push(`  ${GLYPH[r.status] ?? '·'} ${r.name.padEnd(9)} ${r.note}`)
-    if ((r.status === 'fail' || r.status === 'warn') && r.fix) lines.push(`      ↳ fix: ${r.fix}`)
+    const note = r.status === 'skip' ? dim(r.note) : r.note
+    lines.push(`  ${glyph[r.status] ?? glyph.skip} ${r.name.padEnd(9)} ${note}`)
+    if ((r.status === 'fail' || r.status === 'warn') && r.fix)
+      lines.push(`      ${dim('↳ fix:')} ${r.fix}`)
   }
   return lines.join('\n')
 }

package/style.js

@@ -0,0 +1,82 @@
+// nervur — CLI presentation: color and the standing banner. Pure node:util
+// styleText, zero dependencies; color only when stdout is a TTY and NO_COLOR is
+// unset, so piped output (probes, scripts) stays plain and machine-stable.
+
+import * as util from 'node:util'
+
+// util.styleText arrives in node 20.12/21.7 — a named import would crash the
+// whole CLI on anything older (an operator's nvm default may lag), so ink is
+// feature-detected: absent, everything renders plain instead of dying.
+const styleText = util.styleText ?? ((_format, text) => text)
+const stripVTControlCharacters = util.stripVTControlCharacters ?? ((s) => s)
+
+const on = () => process.stdout.isTTY && !process.env.NO_COLOR
+
+// paint(format, text) — styleText that degrades to plain text off-TTY. `format`
+// is a styleText format or array of formats ('green', ['bold','cyan'], …).
+export const paint = (format, text) => (on() ? styleText(format, text) : text)
+
+export const dim = (t) => paint('dim', t)
+export const bold = (t) => paint('bold', t)
+export const red = (t) => paint('red', t)
+export const green = (t) => paint('green', t)
+export const yellow = (t) => paint('yellow', t)
+export const cyan = (t) => paint('cyan', t)
+
+// The status glyphs the preflight chain and the probes share, colored: the
+// vocabulary stays ✓ ✗ ! · (preflight.js), only the ink changes.
+export const glyph = {
+  ok: green('✓'),
+  fail: red('✗'),
+  warn: yellow('!'),
+  skip: dim('·')
+}
+
+// The standing banner — printed once the carcass answers, on `install` and `up`.
+// The console line leads: it is the operator's browser door (host.md — "One
+// operator, one console"), and the one URL a fresh operator should open first.
+// rows: [label, value, note?]; labels and notes align in columns, notes ride
+// dim. Values may carry ANSI ink, so columns measure the stripped length.
+const plainLength = (s) => stripVTControlCharacters(s).length
+
+export function columns(rows) {
+  const labelW = Math.max(...rows.map(([label]) => label.length))
+  const valueW = Math.max(...rows.map(([, value]) => plainLength(value)))
+  return rows
+    .map(([label, value, note]) => {
+      const pad = ' '.repeat(valueW - plainLength(value))
+      const noteStr = note ? `${pad}   ${dim(note)}` : ''
+      return `    ${dim(label.padEnd(labelW))}  ${value}${noteStr}`
+    })
+    .join('\n')
+}
+
+export const heading = (title) => `  ${paint(['bold', 'cyan'], '◆')} ${bold(title)}`
+
+export function banner(title, rows) {
+  return `\n${heading(title)}\n\n${columns(rows)}\n`
+}
+
+// The identity → beings tree — the ground's real shape (beings live under
+// identities, never flat). `identities` may lag `beings` (a being can outlive
+// its vault's listing), so the tree is keyed by the union of both.
+export function identityTree(identities, beings, selected) {
+  const byId = new Map(identities.map((i) => [i, []]))
+  for (const b of beings) {
+    if (!byId.has(b.identity)) byId.set(b.identity, [])
+    byId.get(b.identity).push(b)
+  }
+  const nameW = Math.max(0, ...beings.map((b) => b.name.length))
+  const lines = []
+  for (const [id, bs] of byId) {
+    const marks = [
+      id === selected ? cyan(' ← selected') : '',
+      identities.includes(id) ? '' : dim(' (no vault)')
+    ].join('')
+    lines.push(`    ${bold(id)}${marks}`)
+    if (!bs.length) lines.push(dim('      · no beings'))
+    for (const b of bs)
+      lines.push(`      ${b.name.padEnd(nameW)}  ${dim(`${b.kind} · ${b.state}`)}`)
+  }
+  return lines.join('\n')
+}