nervur 0.0.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,48 @@
 # nervur
 
-This name is reserved. nervur is not yet released.
+The nervur CLI — the operator's command-line face over a running carcass.
+It is a client, never the runtime: every verb speaks to the carcass's HTTP
+API, and the same verbs exist at parity on the nervur console, the
+machine-level face the carcass serves on loopback.
+
+nervur is neutral ground for inter-company work: two companies are two
+cryptographic identities meeting in one shared datastore that neither hosts
+and both can read. Humans and AI agents are first-class colleagues on it.
+
+## Install
+
+```sh
+npm create nervur
+```
+
+One command stands the whole thing: verifies Docker (binary · daemon ·
+permission, each failure a one-line fix), pulls the carcass image, lays down
+compose + volume under `~/.nervur`, and mints your first identity.
+
+## Verbs
+
+```text
+carcass family: install, up, down, reset, preflight, whoami, status,
+                identity, use, add, list, remove
+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 list           identities on this machine · name + public id
+  identity remove <name>  destroy an identity — refused while beings remain
+  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
+  scaffold <name>         mint a species repo (the DNA)
+  deploy <name> <repo> <hash>   grant + pin + run a species
+  species                 list deployed species and their pins
+```
+
+No verb ever prompts — every fork is a flag or env var with a sane default,
+and destructive turns are their own explicitly named verbs.
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).

package/nervur.js

@@ -0,0 +1,517 @@
+#!/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 } 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'
+
+// 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 = 300_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).
+  const faceUrl = process.env.NERVUR_PORT
+    ? `http://localhost:${process.env.NERVUR_PORT}`
+    : config.face?.port
+      ? `http://localhost:${config.face.port}`
+      : 'http://localhost:4000'
+  const face = () => faceUrl
+
+  // `--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 [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  refusing: ${blocked.name} — ${blocked.note}\n  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://localhost:${port}`
+      await knock({ localUrl: `${localUrl}/health` })
+      console.log(`  · carcass standing at ${home} — face on ${localUrl}`)
+      print(await getJson(`${localUrl}/whoami`))
+      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  refusing: ${blocked.name} — ${blocked.note}\n  fix: ${blocked.fix}`)
+        process.exit(1)
+      }
+      if (config.certs) sh('bash', [config.certs])
+      if (config.compose) sh('docker', ['compose', '-f', config.compose, 'up', '-d'])
+      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`))
+      }
+      break
+    }
+    case 'down':
+      if (config.compose) sh('docker', ['compose', '-f', config.compose, 'down'])
+      console.log('down')
+      break
+    case 'reset':
+      if (config.compose) sh('docker', ['compose', '-f', config.compose, 'down', '-v'])
+      for (const dir of config.dataDirs ?? []) rmSync(dir, { recursive: true, force: true })
+      console.log('reset')
+      break
+    case 'whoami':
+      print(await getJson(`${face()}/whoami`))
+      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':
+      print(await getJson(`${face()}/fleet/list`))
+      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.
+    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 }))
+      } 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) {
+          console.error(
+            `refused: identity '${name}' still has beings attached: ${body.beings.join(', ')}`
+          )
+          for (const b of body.beings) console.error(`  fix: nervur remove ${b}`)
+          process.exit(1)
+        }
+        if (status >= 400) {
+          console.error(`nervur: ${body.error}`)
+          process.exit(1)
+        }
+        print(body)
+      } else {
+        throw new Error('usage: nervur identity <add|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
+      }
+      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 'help':
+    case '--help':
+    case '-h':
+      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'
+      )
+      break
+    default:
+      console.error(
+        `nervur: unknown verb: ${verb} (have: install, up, down, reset, preflight, whoami, status, identity, use, add, list, remove, scaffold, deploy, species)`
+      )
+      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: ${e.message}`)
+    process.exit(1)
+  })
+}

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "nervur",
-  "version": "0.0.0",
-  "description": "nervur — reserved. Not yet released.",
-  "license": "Apache-2.0",
-  "type": "module"
+  "version": "0.1.1",
+  "description": "The nervur CLI — a client of a running carcass, never the runtime (papers/host.md).",
+  "type": "module",
+  "bin": {
+    "nervur": "./nervur.js"
+  },
+  "files": [
+    "nervur.js",
+    "preflight.js",
+    "scaffold.js"
+  ],
+  "dependencies": {
+    "@nervur-org/kit": "^0.1.0"
+  },
+  "license": "Apache-2.0"
 }

package/preflight.js

@@ -0,0 +1,161 @@
+// nervur — the bench preflight (papers/dev.md — "the bench preflight"; host.md —
+// "the CLI ... refuses at the door, not as a runtime bug"). A chain of checks
+// `nervur up` runs FIRST, derived entirely from the ground config: a check only
+// runs for what the config declares — a config with no `domains` gets no domain
+// checks, a config with no `certs` gets no cert checks. Each check returns a plain
+// result {name, status, note, fix}; the CLI prints the chain and refuses on the
+// first blocking failure, pointing at the fix without running it.
+//
+// Pure node built-ins, no runtime state: docker / lsof / security are shelled out,
+// dns.lookup honors /etc/hosts. The module is importable so a probe can drive the
+// chain against a crafted config without standing a ground.
+
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { lookup } from 'node:dns/promises'
+
+// Status vocabulary: 'ok' passes; 'fail' blocks (refuse at the door); 'warn' is
+// advisory — a real finding that never blocks (browser trust, the door-closed
+// degrade); 'skip' is a check the config didn't ask for. Only 'fail' blocks.
+const ok = (name, note) => ({ name, status: 'ok', note, fix: null })
+const fail = (name, note, fix) => ({ name, status: 'fail', note, fix })
+const warn = (name, note, fix) => ({ name, status: 'warn', note, fix })
+const skip = (name, note) => ({ name, status: 'skip', note, fix: null })
+
+const domainNames = (config) => Object.keys(config.domains?.routes ?? {})
+const isLoopback = (addr) => addr === '::1' || /^127\./.test(addr)
+const plural = (n, one, many = `${one}s`) => (n === 1 ? one : many)
+
+// docker — binary present → daemon answering → permission ok. Each failure its own
+// precise one-line diagnosis + fix. Always runs; always blocking.
+function checkDocker() {
+  const v = spawnSync('docker', ['--version'], { encoding: 'utf8' })
+  if (v.error || v.status !== 0)
+    return fail(
+      'docker',
+      'the docker binary is not on PATH',
+      'install Docker — https://docs.docker.com/get-docker/'
+    )
+  const info = spawnSync('docker', ['info'], { encoding: 'utf8' })
+  if (info.status === 0) return ok('docker', `daemon answering (${(v.stdout || '').trim()})`)
+  const err = `${info.stderr || ''}${info.stdout || ''}`.toLowerCase()
+  if (err.includes('permission denied'))
+    return fail(
+      'docker',
+      'the Docker socket denies this user',
+      'add your user to the docker group (or run Docker Desktop as this user), then re-login'
+    )
+  return fail(
+    'docker',
+    'the Docker daemon is not responding',
+    'start Docker (`open -a Docker` on macOS), then retry'
+  )
+}
+
+// certs — the dev CA and a cert per declared domain exist, and the cert set covers
+// every declared domain (a config edit that outran gen.sh is caught here, not as a
+// TLS surprise). Only runs when config.certs is declared; blocking.
+function checkCerts(config) {
+  if (!config.certs) return skip('certs', 'no certs declared')
+  const outDir = join(dirname(config.certs), 'out')
+  const fix = `bash ${config.certs}`
+  if (!existsSync(join(outDir, 'ca.crt'))) return fail('certs', 'the dev CA is not minted', fix)
+  const names = domainNames(config)
+  const missing = names.filter((n) => !existsSync(join(outDir, `${n}.crt`)))
+  if (missing.length)
+    return fail('certs', `no cert for ${missing.join(', ')} — the config outran the cert set`, fix)
+  return ok('certs', `dev CA + ${names.length} domain ${plural(names.length, 'cert')}`)
+}
+
+// hosts — every declared domain resolves to loopback (dns.lookup honors /etc/hosts).
+// Only runs when config.domains is declared. Blocking WITH the door; door closed
+// (--no-door / NERVUR_DOOR=0) demotes it to an advisory degrade — the ground stands
+// on localhost only.
+async function checkHosts(config, door) {
+  const names = domainNames(config)
+  if (!names.length) return skip('hosts', 'no domains declared')
+  const unresolved = []
+  for (const n of names) {
+    try {
+      const { address } = await lookup(n)
+      if (!isLoopback(address)) unresolved.push(`${n}→${address}`)
+    } catch {
+      unresolved.push(n)
+    }
+  }
+  const fix = 'sudo dev/hosts.sh'
+  if (!unresolved.length)
+    return ok('hosts', `${names.length} ${plural(names.length, 'domain')} resolve to loopback`)
+  const summary = `${unresolved.length}/${names.length} ${plural(unresolved.length, 'domain')} do not resolve to loopback`
+  if (door) return fail('hosts', summary, fix)
+  return warn('hosts', `door closed — ground stands degraded (localhost only); ${summary}`, fix)
+}
+
+// CA browser trust — macOS keychain only, ADVISORY: print the one-line fix, never
+// block, never run it. Only meaningful when a dev CA is declared.
+function checkCaTrust(config) {
+  if (!config.certs) return skip('ca-trust', 'no certs declared')
+  if (process.platform !== 'darwin') return skip('ca-trust', 'not macOS')
+  const caPath = join(dirname(config.certs), 'out', 'ca.crt')
+  if (!existsSync(caPath)) return skip('ca-trust', 'no dev CA yet')
+  const r = spawnSync('security', ['verify-cert', '-c', caPath], { encoding: 'utf8' })
+  if (r.status === 0) return ok('ca-trust', 'dev CA trusted by the keychain')
+  return warn(
+    'ca-trust',
+    'dev CA not trusted by the keychain — the lens will warn until you trust it',
+    `security add-trusted-cert -r trustRoot -k ~/Library/Keychains/login.keychain-db ${caPath}`
+  )
+}
+
+// port 443 — free, or already held by OUR Docker/Caddy (then fine). A stranger is a
+// blocking diagnosis naming the holder (lsof). Skipped with the door closed, and
+// skipped when the config declares no domains — no door exists to hold 443 for.
+function checkPort443(config, door) {
+  if (!config.domains) return skip('port-443', 'no domains declared')
+  if (!door) return skip('port-443', 'door closed')
+  // `+c0` disables lsof's 9-char COMMAND truncation, so `com.docker.backend` reads
+  // whole and our own Docker is never mistaken for a stranger.
+  const r = spawnSync('lsof', ['+c0', '-nP', '-iTCP:443', '-sTCP:LISTEN'], { encoding: 'utf8' })
+  if (r.error) return warn('port-443', 'cannot probe 443 (lsof unavailable)', null)
+  const rows = (r.stdout || '')
+    .trim()
+    .split('\n')
+    .slice(1)
+    .filter((l) => l.trim())
+  if (!rows.length) return ok('port-443', '443 free')
+  if (rows.every((l) => /docker|com\.docker|vpnkit|caddy/i.test(l)))
+    return ok('port-443', '443 held by our Docker/Caddy')
+  const [cmd, pid] = rows[0].split(/\s+/)
+  return fail(
+    'port-443',
+    `443 held by a stranger: ${cmd} (pid ${pid})`,
+    'stop the process holding 443, or free the port'
+  )
+}
+
+// The chain, in door order: docker → certs → hosts → ca-trust → port-443. Every
+// check runs so the report is complete; the caller refuses on the first blocker.
+export async function runPreflight(config, { door = true } = {}) {
+  return [
+    checkDocker(),
+    checkCerts(config),
+    await checkHosts(config, door),
+    checkCaTrust(config),
+    checkPort443(config, door)
+  ]
+}
+
+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}`)
+  }
+  return lines.join('\n')
+}
+
+// The first blocking failure, or undefined — the CLI refuses on this and exits 1.
+export const blockingFailure = (results) => results.find((r) => r.status === 'fail')

package/scaffold.js

@@ -0,0 +1,50 @@
+// Scaffold a species repo (papers/host.md — "a species is a template … and
+// physically a git repo: the DNA. It is scaffolded by the CLI as a repo of its
+// own"). A being-family author verb, CLIENT-LOCAL like `up`/`down`: it mints a
+// species from a template kind into a target dir — the template files, a named
+// package.json, `git init`, and an initial commit — so the DNA is a git repo from
+// birth. No prompt: the target defaults to ./<name>, flag-overridable; the kind
+// defaults to the kit's bundled `empty`, any other resolved on the npm rail by the
+// caller. Nothing here reaches a carcass — a species is authored, not deployed.
+
+import { cpSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+// git is ambient on the bench and in the image (papers/host.md — code travels as
+// DNA over bare repos); no npm dependency stands in for it. Every call runs in
+// `cwd` and throws git's own stderr on nonzero, so a failure is never silent.
+function defaultGit(args, cwd) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' })
+  if (r.status !== 0)
+    throw new Error(`git ${args[0]} failed: ${(r.stderr || r.stdout || '').trim()}`)
+  return (r.stdout || '').trim()
+}
+
+// scaffoldSpecies({ name, template, dir?, git? }) → { name, dir, head }. `template`
+// is a resolved directory (the caller resolves the kind — bundled or npm). Returns
+// the initial commit hash: the first pin a deploy can grant against.
+export function scaffoldSpecies({ name, template, dir, git = defaultGit } = {}) {
+  if (!name) throw new Error('scaffold: a species name is required')
+  if (!template || !existsSync(template))
+    throw new Error(`scaffold: no template at ${template} — bundle it, or \`npm i\` it first`)
+  const target = dir ?? join(process.cwd(), name)
+  if (existsSync(target)) throw new Error(`scaffold: ${target} already exists — pick another --dir`)
+
+  cpSync(template, target, { recursive: true })
+
+  // Name the species in its package.json (the template ships a generic name); the
+  // DNA carries its own identity from birth.
+  const pkgPath = join(target, 'package.json')
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    pkg.name = name
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+  }
+
+  git(['init', '-q'], target)
+  git(['add', '-A'], target)
+  git(['commit', '-q', '-m', `scaffold ${name}`], target)
+  const head = git(['rev-parse', 'HEAD'], target)
+  return { name, dir: target, head }
+}