nervur 0.2.0 → 0.5.0

package/preflight.js

@@ -1,162 +0,0 @@
-// 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'
-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
-// 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)
-  ]
-}
-
-export function renderChain(results) {
-  const lines = []
-  for (const r of results) {
-    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')
-}
-
-// 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

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

package/style.js

@@ -1,82 +0,0 @@
-// 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')
-}