nervur 0.3.0 → 0.6.0

package/nervur.js

@@ -1,672 +0,0 @@
-#!/usr/bin/env node
-// nervur — the CLI: a CLIENT of a running carcass, never the runtime
-// (papers/host.md — "the CLI talks to a carcass over its API; it is never the
-// runtime"). `up`/`down`/`reset` drive the compose that holds the carcass; every
-// other verb reaches the carcass's face over HTTP, so what the CLI reports is the
-// LIVE ground, not a fresh in-process being.
-
-import { spawnSync } from 'node:child_process'
-import { createHash } from 'node:crypto'
-import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { dirname, join, relative } from 'node:path'
-import { request as httpsRequest } from 'node:https'
-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
-// published install idiom").
-const DEFAULT_IMAGE = 'nervur/carcass:latest'
-
-// A `--flag value` reader for the being-family verbs — a fork is always a flag with
-// a sane default, never a prompt (papers/dev.md).
-const flagValue = (args, flag) => {
-  const i = args.indexOf(flag)
-  return i >= 0 ? args[i + 1] : undefined
-}
-const positional = (args) => args.filter((a) => !a.startsWith('--'))
-
-const sh = (cmd, args, opts = {}) => {
-  const r = spawnSync(cmd, args, { stdio: 'inherit', ...opts })
-  if (r.status !== 0) throw new Error(`${cmd} ${args.join(' ')} exited ${r.status}`)
-}
-
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
-
-// Knock a being domain through the Caddy door over the dev CA — the same TLS path
-// a browser and a remote caller ride (papers/dev.md). `address`/`servername` let a
-// caller resolve like `curl --resolve` (connect to an IP, present the domain in
-// SNI + Host) so the path is provable without /etc/hosts. Any error — DNS not
-// resolving because dev/hosts.sh has not run, a TLS or connection failure —
-// resolves false, and `up` falls back to the always-published localhost face; a
-// missing hosts entry must never break `up` (the refusing preflight is later).
-export function knockDomain(
-  domain,
-  ca,
-  path = '/health',
-  { address, servername, timeout = 2500 } = {}
-) {
-  return new Promise((resolve) => {
-    const req = httpsRequest(
-      {
-        host: address ?? domain,
-        servername: servername ?? domain,
-        port: 443,
-        path,
-        ca,
-        timeout,
-        headers: { host: domain }
-      },
-      (res) => {
-        let body = ''
-        res.on('data', (c) => (body += c))
-        res.on('end', () => resolve({ ok: res.statusCode >= 200 && res.statusCode < 300, body }))
-      }
-    )
-    req.on('error', () => resolve({ ok: false }))
-    req.on('timeout', () => {
-      req.destroy()
-      resolve({ ok: false })
-    })
-    req.end()
-  })
-}
-
-// The dev CA the door serves under — beside the certs script (dev/certs/gen.sh →
-// dev/certs/out/ca.crt). Absent before the first `up`, so read lazily and tolerate
-// its absence (the domain knock simply can't run yet).
-function readCA(config) {
-  if (!config.certs) return undefined
-  try {
-    return readFileSync(join(dirname(config.certs), 'out', 'ca.crt'))
-  } catch {
-    return undefined
-  }
-}
-
-const localOk = async (url) => {
-  try {
-    return (await fetch(url)).ok
-  } catch {
-    return false
-  }
-}
-
-// Knock the carcass until it answers, preferring the domain door when it can. Each
-// tick tries the domain (over the dev CA) first, then the always-published
-// localhost face — so a ground with dev/hosts.sh run reports through the real URL
-// scheme, and one without it still comes up on localhost. Bounded but generous:
-// the first boot installs node_modules (a native module) inside the container,
-// which takes a few minutes, so the wait prints progress rather than looking hung.
-async function knock({ localUrl, domain, ca, ms = 600_000 }) {
-  const until = Date.now() + ms
-  let noted = 0
-  for (;;) {
-    if (domain && ca && (await knockDomain(domain, ca)).ok) return { via: 'domain' }
-    if (await localOk(localUrl)) return { via: 'localhost' }
-    if (Date.now() > until)
-      throw new Error(`the carcass did not answer at ${localUrl} within ${Math.round(ms / 1000)}s`)
-    if (Date.now() - noted > 5000) {
-      process.stdout.write(
-        '  · standing the carcass (first boot installs node_modules inside the container)…\n'
-      )
-      noted = Date.now()
-    }
-    await sleep(1000)
-  }
-}
-
-const getJson = async (url) => (await fetch(url)).json()
-const postJson = async (url, body) =>
-  (
-    await fetch(url, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify(body ?? {})
-    })
-  ).json()
-// Same as postJson but keeps the status code — the identity verbs need to tell a
-// 409 (refused, still occupied) apart from success without throwing on either.
-const postJsonStatus = async (url, body) => {
-  const res = await fetch(url, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify(body ?? {})
-  })
-  return { status: res.status, body: await res.json() }
-}
-
-// The install compose — the same shape carcass/compose.yml stands (carcass,
-// durable named volume, image disposable/volume durable): one carcass container,
-// its ground config bind-mounted read-only, its state on a volume, published to
-// loopback via the NERVUR_PORT/NERVUR_FACES_PORT seams. Caddy fronting is parked
-// (papers/prod.md — "arrives with the per-box configuration"); this is the honest
-// floor today. Rewritten on every `install` — mechanical, never hand-edited.
-// Docker derives volume/network names from the project name — a fixed name would
-// share one state volume across every NERVUR_HOME on the machine.
-function installCompose(home) {
-  const scope = createHash('sha256').update(realpathSync(home)).digest('hex').slice(0, 8)
-  return `name: nervur-${scope}
-
-# Generated by \`nervur install\` — the published carcass stand (papers/host.md,
-# papers/dev.md § the published install idiom). Image disposable, volume durable:
-# re-running install is image + boot, nothing wiped.
-services:
-  carcass:
-    image: \${NERVUR_IMAGE:-${DEFAULT_IMAGE}}
-    environment:
-      NERVUR_GROUND: /app/ground.config.js
-    volumes:
-      - ./ground.config.js:/app/ground.config.js:ro
-      - nervur-state:/app/state
-    ports:
-      - '127.0.0.1:\${NERVUR_PORT:-4000}:4000'
-      - '127.0.0.1:\${NERVUR_FACES_PORT:-4400}:4400'
-      - '127.0.0.1:\${NERVUR_CONSOLE_PORT:-4200}:4200'
-    restart: unless-stopped
-
-volumes:
-  nervur-state:
-`
-}
-
-// The ground config the carcass reads INSIDE the container — internal ports are
-// fixed (4000/4400); the compose above remaps them to the host's NERVUR_PORT/
-// NERVUR_FACES_PORT, so changing the host port never touches this file. Written
-// once and kept (host.md — install delivers code, boot converges state); edit it
-// freely, a re-install never overwrites it.
-function installGroundConfig() {
-  return `// nervur ground — generated once by \`nervur install\`; edit freely, it is kept.
-// The state root a mounted volume converges on every boot (papers/host.md); no
-// stations stand bare — \`nervur add\` makes beings on top of this.
-export default {
-  version: '0.1.0',
-  ground: '/app/state',
-  face: { port: 4000 },
-  faces: { port: 4400 },
-  console: { port: 4200 },
-  stations: {}
-}
-`
-}
-
-async function main() {
-  const configPath = process.env.NERVUR_GROUND ?? 'dev/ground.config.js'
-  // The ground config is tolerant of absence: the being-family author verb
-  // `scaffold` is client-local and needs no ground at all, so a missing config
-  // must not block it. A verb that needs the face resolves it through face()
-  // below, which throws a clear error when the port is absent.
-  let config = {}
-  try {
-    config = (await import(pathToFileURL(configPath))).default
-  } catch {
-    // no ground config here — the NERVUR_PORT fallback below still reaches an
-    // installed carcass (nervur install has no dev/ground.config.js to hand it)
-  }
-  // NERVUR_PORT, when set, always wins — it is the explicit seam `nervur install`
-  // published the carcass on, and must override even a resolved dev/ground.config.js
-  // (running from inside the monorepo with NERVUR_PORT set is exactly how this probe,
-  // and any contributor testing `install`, points the client at their OWN carcass
-  // rather than the dev bench's). Absent NERVUR_PORT, the dev bench's config.face.port
-  // is the convenience default; absent both, a published install's own default (4000).
-  // Reached at 127.0.0.1, never `localhost`: the compose binds IPv4 loopback
-  // only, and macOS launchd holds ::1 listeners (AirPlay on 5000) that accept
-  // and hang a localhost knock. Host ports must also dodge the WHATWG fetch
-  // bad-ports list (6000/X11 and kin) — node's fetch refuses those outright.
-  const faceUrl = process.env.NERVUR_PORT
-    ? `http://127.0.0.1:${process.env.NERVUR_PORT}`
-    : (config.hostPorts?.face ?? config.face?.port)
-      ? `http://127.0.0.1:${config.hostPorts?.face ?? config.face.port}`
-      : 'http://127.0.0.1:4000'
-  const face = () => faceUrl
-
-  // A config without project/hostPorts/domains (the published install path)
-  // gets none of these vars — the compose defaults hold.
-  const composeEnv = () => {
-    const env = { ...process.env }
-    if (config.project) env.COMPOSE_PROJECT_NAME = config.project
-    if (config.domains) env.COMPOSE_PROFILES = 'door'
-    const seam = {
-      face: 'FACE',
-      console: 'CONSOLE',
-      faces: 'FACES',
-      ctlKeeper: 'CTL_KEEPER',
-      ctlUpsy: 'CTL_UPSY',
-      ctlFedexy: 'CTL_FEDEXY',
-      dpUpsy: 'DP_UPSY',
-      dpFedexy1: 'DP_FEDEXY1',
-      dpFedexy2: 'DP_FEDEXY2'
-    }
-    for (const [key, name] of Object.entries(seam))
-      if (config.hostPorts?.[key] != null) env[`NERVUR_HOST_${name}`] = String(config.hostPorts[key])
-    if (config.compose) {
-      const rel = configPath.startsWith('/') ? relative(process.cwd(), configPath) : configPath
-      env.NERVUR_GROUND_IN = `/app/${rel.replace(/^\.\//, '')}`
-    }
-    return env
-  }
-
-  // `--as <name>` is a global flag — it rides before OR after the verb (`nervur
-  // --as acme add empty` and `nervur add empty --as acme` both work), so pull it
-  // out of the raw argv before the verb is read off position 0.
-  const rawArgs = process.argv.slice(2)
-  const asIdx = rawArgs.indexOf('--as')
-  const asFlag = asIdx >= 0 ? rawArgs[asIdx + 1] : undefined
-  if (asIdx >= 0) rawArgs.splice(asIdx, 2)
-
-  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))
-
-  // Which identity the being-family verbs act as (papers/host.md — "switching
-  // identity is a client act"). Precedence: --as <name> flag > NERVUR_IDENTITY env
-  // > sticky file beside the resolved ground config > 'main'. Never a prompt.
-  // The sticky file rides beside whatever ground config actually resolved; a
-  // published install has none, so it rides beside NERVUR_HOME instead — never a
-  // relative 'dev/' path that doesn't exist outside the monorepo.
-  const stickyHome = process.env.NERVUR_HOME ?? join(homedir(), '.nervur')
-  const stickyPath = existsSync(configPath)
-    ? join(dirname(configPath), '.nervur-identity')
-    : join(stickyHome, '.nervur-identity')
-  const readSticky = () => {
-    try {
-      return readFileSync(stickyPath, 'utf8').trim() || null
-    } catch {
-      return null
-    }
-  }
-  const selectedIdentity = asFlag ?? process.env.NERVUR_IDENTITY ?? readSticky() ?? 'main'
-
-  // The door is open by default; `--no-door` (or NERVUR_DOOR=0) closes it for
-  // headless/CI — a command with a sane default, never a prompt. Closed, the hosts
-  // check degrades to advisory and 443 is skipped: the ground stands on localhost.
-  const doorOpen = !(args.includes('--no-door') || process.env.NERVUR_DOOR === '0')
-
-  switch (verb) {
-    // The published install (papers/host.md — "the CLI, client, never runtime";
-    // papers/dev.md — "the published install idiom"): Docker preflight, then the
-    // carcass image, a compose + volume in NERVUR_HOME, up, knock /health, whoami.
-    // Installer dumb, boot smart — existing state (the volume) is never touched;
-    // re-running this is image + boot, nothing asked, nothing lost.
-    case 'install': {
-      // Only the docker check applies here — an empty config skips certs/hosts/
-      // ca-trust/port-443 (those are the DEV BENCH's own preconditions, preflight.js
-      // runs them only when the config declares certs/domains).
-      const results = await runPreflight({}, { door: false })
-      console.log(renderChain(results))
-      const blocked = blockingFailure(results)
-      if (blocked) {
-        console.error(`\n  ${red('refusing:')} ${blocked.name} — ${blocked.note}\n  ${dim('fix:')} ${blocked.fix}`)
-        process.exit(1)
-      }
-
-      const home = process.env.NERVUR_HOME ?? join(homedir(), '.nervur')
-      const image = process.env.NERVUR_IMAGE ?? DEFAULT_IMAGE
-      const port = process.env.NERVUR_PORT ?? '4000'
-      const facesPort = process.env.NERVUR_FACES_PORT ?? '4400'
-
-      // Refused here, before the compose — `compose up` against a missing image
-      // fails too, but far less legibly than this message.
-      const inspect = spawnSync('docker', ['image', 'inspect', image], { stdio: 'ignore' })
-      if (inspect.status !== 0) {
-        console.log(`  · image ${image} not found locally — trying \`docker pull\`…`)
-        const pull = spawnSync('docker', ['pull', image], { stdio: 'inherit' })
-        if (pull.status !== 0) {
-          console.error(
-            `\n  refusing: no carcass image '${image}' locally, and the pull failed.\n` +
-              `  fix: check the network and the image name — \`docker pull ${image}\` by hand shows the registry's answer; \`docker build -f carcass/Dockerfile -t ${image} .\` builds it locally`
-          )
-          process.exit(1)
-        }
-      }
-
-      // Lay down the ground. The compose is rewritten every run (mechanical, not
-      // state); the ground config is written once and kept (edit it freely — the
-      // boot converges whatever it finds, papers/host.md).
-      mkdirSync(home, { recursive: true })
-      const composePath = join(home, 'compose.yml')
-      writeFileSync(composePath, installCompose(home))
-      const groundPath = join(home, 'ground.config.js')
-      if (!existsSync(groundPath)) writeFileSync(groundPath, installGroundConfig())
-
-      sh('docker', ['compose', '-f', composePath, 'up', '-d'], {
-        env: {
-          ...process.env,
-          NERVUR_IMAGE: image,
-          NERVUR_PORT: String(port),
-          NERVUR_FACES_PORT: String(facesPort)
-        }
-      })
-
-      const localUrl = `http://127.0.0.1:${port}`
-      await knock({ localUrl: `${localUrl}/health` })
-      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': {
-      // The chain on its own: report the bench's readiness without standing it.
-      // Exit code reflects the verdict so a script can gate on it.
-      const results = await runPreflight(config, { door: doorOpen })
-      console.log(renderChain(results))
-      process.exit(blockingFailure(results) ? 1 : 0)
-      break
-    }
-    case 'up': {
-      // The preflight runs FIRST (papers/dev.md): refuse at the door on the first
-      // blocking failure, pointing at the fix, rather than raising a compose that
-      // will fail as a runtime surprise.
-      const results = await runPreflight(config, { door: doorOpen })
-      console.log(renderChain(results))
-      const blocked = blockingFailure(results)
-      if (blocked) {
-        console.error(`\n  ${red('refusing:')} ${blocked.name} — ${blocked.note}\n  ${dim('fix:')} ${blocked.fix}`)
-        process.exit(1)
-      }
-      if (config.certs) sh('bash', [config.certs])
-      if (config.compose) sh('docker', ['compose', '-f', config.compose, 'up', '-d'], { env: composeEnv() })
-      const ca = readCA(config)
-      // Door open: knock the domain first, so a bench with hosts run reports through
-      // the real URL scheme (slice-2 behavior). Door closed: localhost only.
-      const { via } = await knock({
-        localUrl: `${face()}/health`,
-        domain: doorOpen ? faceDomain : null,
-        ca
-      })
-      if (via === 'domain') {
-        console.log(`  · carcass answered through the door: https://${faceDomain}`)
-        print(JSON.parse((await knockDomain(faceDomain, ca, '/whoami')).body))
-      } else {
-        if (!doorOpen) console.log('  · door closed — ground stands degraded (localhost only)')
-        else if (faceDomain)
-          console.log(
-            `  · carcass on ${face()} — run \`sudo dev/hosts.sh\` to reach it at https://${faceDomain}`
-          )
-        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.hostPorts?.console ?? config.console?.port ?? 4200}`), 'open in your browser']
-        ]) + `\n    ${dim(`api ${via === 'domain' ? `https://${faceDomain}` : face()}`)}\n`
-      )
-      break
-    }
-    case 'down':
-      if (config.compose) sh('docker', ['compose', '-f', config.compose, 'down'], { env: composeEnv() })
-      console.log('down')
-      break
-    case 'reset':
-      if (config.compose) sh('docker', ['compose', '-f', config.compose, 'down', '-v'], { env: composeEnv() })
-      for (const dir of config.dataDirs ?? []) rmSync(dir, { recursive: true, force: true })
-      console.log('reset')
-      break
-    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
-    case 'add':
-      print(
-        await postJson(`${face()}/fleet/add`, {
-          kind: args[0] ?? 'empty',
-          identity: selectedIdentity
-        })
-      )
-      break
-    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 — 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> [--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)
-          console.log(`${i.name === selectedIdentity ? '*' : ' '} ${i.name}  ${i.id}`)
-      } else if (sub === 'remove') {
-        if (!name) throw new Error('usage: nervur identity remove <name>')
-        const { status, body } = await postJsonStatus(`${face()}/identities/remove`, { name })
-        if (status === 409) {
-          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) {
-          console.error(`nervur: ${body.error}`)
-          process.exit(1)
-        }
-        print(body)
-      } else {
-        throw new Error('usage: nervur identity <add|key|list|remove> <name>')
-      }
-      break
-    }
-    // Client-side sticky selection (papers/host.md — switching is a client act; it
-    // selects which vault the verbs act on, stands no container, crosses no wall).
-    case 'use': {
-      const name = positional(args)[0]
-      if (!name) {
-        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}'`)
-      break
-    }
-    // ── the being family: scaffold (client-local) authors a species; deploy/species
-    //    reach the carcass over its face, like every other verb (papers/host.md).
-    case 'scaffold': {
-      // Mint a species repo from a template kind into a target dir — the DNA a git
-      // repo from birth. Local, like up/down: it touches no carcass.
-      const name = positional(args)[0]
-      if (!name) throw new Error('usage: nervur scaffold <name> [--kind empty] [--dir <path>]')
-      const kind = flagValue(args, '--kind') ?? 'empty'
-      print(
-        scaffoldSpecies({
-          name,
-          template: resolveTemplate(kind, { from: join(process.cwd(), 'noop.js') }),
-          dir: flagValue(args, '--dir')
-        })
-      )
-      break
-    }
-    case 'deploy': {
-      // Grant this carcass a species repo at a pinned full-hash release, materialize
-      // and run it. Re-deploy with a new hash = upgrade or rollback, same verb.
-      const [name, repo, ref] = positional(args)
-      if (!name || !repo || !ref)
-        throw new Error('usage: nervur deploy <name> <repo> <full-commit-hash>')
-      print(await postJson(`${face()}/deploy`, { name, repo, ref }))
-      break
-    }
-    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': {
-      // 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(
-        `${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: {
-      const known = VERBS.map(([v]) => v)
-      const near = known.filter((v) => v.startsWith(verb) || verb.startsWith(v.slice(0, 3)))
-      console.error(
-        `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)
-}
-
-// Run only as the CLI; importing this module (e.g. to exercise knockDomain against
-// the door) must not fire main(). Resolve the invoked path through symlinks — `npx
-// nervur` / `node_modules/.bin/nervur` reach here via a symlink, and import.meta.url
-// is already the realpath, so compare realpath to realpath or the door never opens.
-function invokedAsCli() {
-  if (!process.argv[1]) return false
-  try {
-    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href
-  } catch {
-    return false
-  }
-}
-if (invokedAsCli()) {
-  main().catch((e) => {
-    console.error(`nervur: ${red(e.message)}`)
-    process.exit(1)
-  })
-}