openvoidnet 1.0.0

package/README.md

@@ -0,0 +1,41 @@
+# openvoidnet
+
+Voidnet publisher CLI. Manage your Voidnet apps from the terminal.
+
+```bash
+npm i -g openvoidnet
+voidnet login
+voidnet apps list
+```
+
+## Login
+
+Browser approval via Void Accounts (recommended):
+
+```bash
+voidnet login
+```
+
+Headless and CI — paste a console-issued token:
+
+```bash
+voidnet login --token vnp-pub-...
+```
+
+## Commands
+
+```bash
+voidnet apps list [--format=json]
+voidnet logs tail --app <appId> [--request-id <uuid>]
+voidnet keys list <appId>
+voidnet keys rotate <appId>
+voidnet logout
+```
+
+`logs tail --request-id` filters by the join ID the gateway forwards as
+`X-Voidnet-Request-Id` on every routed call — match one call against Usage Logs.
+
+Browser login grants read + verify scopes only. Publishing and key rotation
+require a deliberately console-issued token.
+
+Proprietary — Voidnet ecosystem. Not open source.

package/bin/voidnet.js

@@ -0,0 +1,407 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { resolveEnv } from '../src/env.js';
+import { makeOut, resolveMode } from '../src/out.js';
+import { gateMinimum, noteUpdate, readPkgVersion } from '../src/update.js';
+import { serviceName, adapterName } from '../src/words.js';
+
+const ENV = resolveEnv({ silent: true });
+const MODE = resolveMode();
+const out = makeOut(MODE);
+
+const DOCS_SIGNIN = 'https://docs.openvoidnet.com/docs/concepts/voidnet-cli#sign-in';
+const NOT_LOGGED_IN = `Not logged in. Run: voidnet login — ${DOCS_SIGNIN}`;
+
+function announceEnv() {
+  out.diag(`env=${ENV.name} mgmt=${ENV.mgmtBase} auth=${ENV.authBase} live=${ENV.liveBase}`, { verboseOnly: true });
+}
+
+function loadConfig() {
+  try {
+    if (!existsSync(ENV.configPath)) return { env: ENV.name, token: null };
+    const cfg = JSON.parse(readFileSync(ENV.configPath, 'utf8'));
+    // Unmarked, foreign-env, or tokenless files all mean one thing: logged out.
+    // Re-login mints fresh. No cryptic states leak to humans.
+    if (cfg.env !== ENV.name || !cfg.token) return { env: ENV.name, token: null };
+    return cfg;
+  } catch (err) {
+    out.diag(`config unreadable, treating as logged out: ${String(err && err.message || err)}`, { verboseOnly: true });
+    return { env: ENV.name, token: null };
+  }
+}
+
+function saveConfig(cfg) {
+  mkdirSync(dirname(ENV.configPath), { recursive: true });
+  writeFileSync(ENV.configPath, JSON.stringify({ ...cfg, env: ENV.name }, null, 2), { mode: 0o600 });
+  out.diag(`config saved path=${ENV.configPath}`, { verboseOnly: true });
+}
+
+async function authed(path, opts = {}) {
+  const cfg = loadConfig();
+  if (!cfg.token) {
+    out.error(NOT_LOGGED_IN);
+  }
+  const url = `${ENV.mgmtBase}${path}`;
+  out.diag(`request ${opts.method || 'GET'} ${url}`, { verboseOnly: true });
+  const res = await fetch(url, {
+    ...opts,
+    headers: { Authorization: `Bearer ${cfg.token}`, 'Content-Type': 'application/json', ...(opts.headers || {}) },
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    // Dead or revoked token: same fix as never logged in.
+    if (res.status === 401) out.error(NOT_LOGGED_IN);
+    out.error(`Request failed (status=${res.status} code=${data.code || data.error || 'unknown'}). — ${DOCS_SIGNIN}`);
+  }
+  return data;
+}
+
+const [cmd, sub, ...rest] = process.argv.slice(2);
+const tokenIdx = process.argv.indexOf('--token');
+
+const KNOWN = new Set(['login', 'logout', 'apps', 'logs', 'keys', 'help', 'whoami', 'status', 'doctor']);
+if (!cmd || cmd === 'help' || process.argv.includes('--help') || process.argv.includes('-h')) {
+  printHelp(sub || null);
+} else if (process.argv.includes('--version') || cmd === 'version') {
+  printVersion();
+} else if (!KNOWN.has(cmd)) {
+  out.error(`unknown command "${cmd}". Run voidnet --help.`);
+} else {
+  announceEnv();
+  const pkgVersion = readPkgVersion(import.meta.url);
+  const vv = (m) => out.diag(m, { verboseOnly: true });
+  const meta = await gateMinimum({ pkgVersion, mgmtBase: ENV.mgmtBase, homeDir: homedir(), onVerbose: vv });
+  await dispatch(cmd, sub, rest, tokenIdx);
+  noteUpdate({ pkgVersion, meta });
+}
+
+function printHelp(topic) {
+  if (topic === 'advanced') {
+    out.data(`Advanced environment control:
+  --env production|development, --base/--auth-base/--live-base URLs
+  VOIDNET_ENV, VOIDNET_MGMT_BASE, VOIDNET_AUTH_BASE, VOIDNET_LIVE_BASE
+Resolution: flags > VOIDNET_* env > baked default (production).
+Config: ~/.config/voidnet/cli.json vs cli.development.json (per env, never shared).`);
+    return;
+  }
+  if (topic === 'login') {
+    out.data(`voidnet login [--app <id>...]
+  Browser approval via Void Accounts. See: voidnet help advanced for environments.`);
+    return;
+  }
+  out.data(`Usage:
+  voidnet [command] [flags]
+
+Auth commands:
+  login     Sign in (browser approval, or --token for CI)
+  logout    Revoke and remove local credentials
+
+App commands:
+  apps      List apps and status
+
+Observability:
+  logs      Tail usage logs, filterable by request ID
+  status    Probe auth, management, gateway reachability
+  doctor    Diagnose local setup with fix for every failure
+
+Key commands:
+  keys      List fingerprints, rotate per-app keys
+
+Other commands:
+  whoami    Show env, targets, and login state
+  version   Print CLI version
+
+Global flags:
+  --json, --quiet, --verbose
+
+Run voidnet help advanced for environments.`);
+}
+
+function printVersion() {
+  out.data(`voidnet ${readPkgVersion(import.meta.url)}`);
+}
+
+async function dispatch(cmd, sub, rest, tokenIdx) {
+if (cmd === 'login' && tokenIdx >= 0) {
+  const token = process.argv[tokenIdx + 1];
+  if (!token || !token.startsWith('vnp-pub-')) {
+    out.error('usage: voidnet login --token vnp-pub-... [--env production|development]');
+  }
+  saveConfig({ token });
+  out.ok(`Signed in. Token stored (last4=${token.slice(-4)}).`);
+} else if (cmd === 'login') {
+  await browserLogin();
+} else if (cmd === 'logout') {
+  const cfg = loadConfig();
+  if (cfg.token) {
+    try {
+      await fetch(`${ENV.mgmtBase}/api/publisher/v1/auth/revoke-self`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${cfg.token}` },
+      });
+      out.diag('server-side token revoked');
+    } catch (err) {
+      out.diag(`revoke call failed (local config still removed): ${String(err && err.message || err)}`);
+    }
+  }
+  saveConfig({ token: null });
+  out.ok('Signed out.');
+} else if (cmd === 'whoami') {
+  const cfg = loadConfig();
+  if (!cfg.token) {
+    if (MODE === 'json') out.json({ login: false });
+    else out.data('login=no');
+    out.error(NOT_LOGGED_IN);
+  }
+  if (MODE === 'json') {
+    const payload = { login: true, last4: String(cfg.token).slice(-4), mgmt: ENV.mgmtBase };
+    if (process.argv.includes('--verify')) {
+      const data = await authed('/api/publisher/v1/apps');
+      out.json({ ...payload, verified: true, apps: (data.apps || []).length });
+    } else {
+      out.json(payload);
+    }
+    return;
+  }
+  out.data(`Signed in. Token •••• ${String(cfg.token).slice(-4)}.\nTarget: ${ENV.mgmtBase}`);
+  if (process.argv.includes('--verify')) {
+    const data = await authed('/api/publisher/v1/apps');
+    out.data(`verified=yes apps=${(data.apps || []).length}`);
+  }
+} else if (cmd === 'status') {
+  const { probe } = await import('../src/probes.js');
+  const vv = (m) => out.diag(m, { verboseOnly: true });
+  const rows = [
+    await probe(serviceName('auth'), `${ENV.authBase}/api/auth/session/status`, { onVerbose: vv }),
+    await probe(serviceName('management'), `${ENV.mgmtBase}/api/publisher/v1/apps`, { onVerbose: vv }),
+    await probe(serviceName('gateway'), `${ENV.liveBase}/health`, { expectJson: true, onVerbose: vv }),
+  ];
+  if (MODE === 'json') {
+    out.json({ rows });
+    if (rows.some((r) => !r.ok)) process.exit(1);
+    return;
+  }
+  for (const r of rows) {
+    out.data(`${r.ok ? 'ok' : 'FAIL'} ${r.name} ${r.detail} ${r.latencyMs}ms`);
+  }
+  if (rows.some((r) => !r.ok)) {
+    out.error('status: one or more probes failed (rows above name the cause)');
+  }
+  out.ok('status: all probes green');
+} else if (cmd === 'doctor') {
+  const { probe, checkNode } = await import('../src/probes.js');
+  const { execSync } = await import('node:child_process');
+  const { statSync } = await import('node:fs');
+  const rows = [];
+  const vv2 = (m) => out.diag(m, { verboseOnly: true });
+  rows.push(checkNode(20, 9, { onVerbose: vv2 }));
+  try {
+    const hits = execSync('which -a voidnet 2>/dev/null || true', { encoding: 'utf8' })
+      .split('\n').map((s) => s.trim()).filter(Boolean);
+    const shadowed = hits.some((h) => h.includes('.local/bin') && !h.includes('fnm') && !h.includes('node-versions'));
+    const base = (process.argv[1] || 'voidnet').split('/').pop() || 'voidnet';
+    rows.push({
+      name: 'binary',
+      ok: !shadowed,
+      detail: shadowed ? `shadowed entries found — run hash -r, check PATH order: ${hits.join(',')}` : `binary=${base}`,
+      latencyMs: 0,
+    });
+    out.diag(`binary check entries=${hits.length} shadowed=${shadowed}`, { verboseOnly: true });
+  } catch (err) {
+    rows.push({ name: 'binary', ok: true, detail: 'which unavailable, skipped', latencyMs: 0 });
+  }
+  try {
+    const st = statSync(ENV.configPath);
+    const mode = (st.mode & 0o777).toString(8);
+    rows.push({
+      name: 'config-perms',
+      ok: mode === '600',
+      detail: mode === '600' ? `mode=600 path=${ENV.configPath}` : `mode=${mode} — run chmod 600 ${ENV.configPath}`,
+      latencyMs: 0,
+    });
+  } catch {
+    rows.push({ name: 'config-perms', ok: true, detail: 'no config file yet — run voidnet login', latencyMs: 0 });
+  }
+  const cfg = loadConfig();
+  rows.push({
+    name: 'login',
+    ok: Boolean(cfg.token),
+    detail: cfg.token ? `logged in last4=${String(cfg.token).slice(-4)}` : 'not logged in — run voidnet login',
+    latencyMs: 0,
+  });
+  rows.push(await probe(serviceName('auth'), `${ENV.authBase}/api/auth/session/status`, { onVerbose: vv2 }));
+  rows.push(await probe(serviceName('management'), `${ENV.mgmtBase}/api/publisher/v1/apps`, { onVerbose: vv2 }));
+  rows.push(await probe(serviceName('gateway'), `${ENV.liveBase}/health`, { expectJson: true, onVerbose: vv2 }));
+  const failed = rows.filter((r) => !r.ok).length;
+  if (MODE === 'json') {
+    out.json({ rows, failed });
+    if (failed > 0) process.exit(1);
+    return;
+  }
+  for (const r of rows) {
+    out.data(`${r.ok ? 'ok' : 'FAIL'} ${r.name} ${r.detail}${r.latencyMs ? ` ${r.latencyMs}ms` : ''}`);
+  }
+  if (failed > 0) {
+    out.error(`doctor: ${failed} check(s) failed (fix commands above)`);
+  }
+  out.ok('doctor: all checks green');
+} else if (cmd === 'apps' && (sub === 'list' || !sub)) {
+  const data = await authed('/api/publisher/v1/apps');
+  if (MODE === 'json' || process.argv.includes('--format=json')) {
+    out.json(data);
+  } else {
+    out.data('ID  NAME  STATUS  KIND  SERVER_URL');
+    for (const a of data.apps || []) {
+      out.data(`${a.id}  ${a.app_name}  ${a.status}  ${adapterName(a.adapter_type)}  ${a.server_url}`);
+    }
+  }
+  out.diag(`apps rows=${(data.apps || []).length}`, { verboseOnly: true });
+} else if (cmd === 'logs' && sub === 'tail') {
+  const appIdx = process.argv.indexOf('--app');
+  const reqIdx = process.argv.indexOf('--request-id');
+  const app = appIdx >= 0 ? process.argv[appIdx + 1] : null;
+  if (!app) {
+    out.error('usage: voidnet logs tail --app <appId> [--request-id <uuid>]');
+  }
+  const q = reqIdx >= 0 ? `?request_id=${encodeURIComponent(process.argv[reqIdx + 1])}` : '';
+  const data = await authed(`/api/publisher/v1/apps/${app}/metering${q}`);
+  if (MODE === 'json') {
+    out.json(data);
+    return;
+  }
+  for (const r of data.records || []) {
+    out.data(`${r.timestamp} ${r.requestId} ${r.operationType} ${r.toolName || '-'} ${r.error ? 'ERROR' : 'ok'} ${r.durationMs}ms`);
+  }
+  out.diag(`logs rows=${(data.records || []).length} total=${data.pagination?.total ?? '?'}`, { verboseOnly: true });
+} else if (cmd === 'keys' && sub === 'list') {
+  const app = rest[0];
+  if (!app) {
+    out.error('usage: voidnet keys list <appId>');
+  }
+  const data = await authed(`/api/publisher/v1/apps/${app}/keys`);
+  if (MODE === 'json') {
+    out.json(data);
+    return;
+  }
+  for (const k of data.keys || []) {
+    out.data(`id=${k.id} last4=${k.last4} active=${k.is_active} created=${k.created_at}`);
+  }
+} else if (cmd === 'keys' && sub === 'rotate') {
+  const app = rest[0];
+  if (!app) {
+    out.error('usage: voidnet keys rotate <appId>');
+  }
+  const data = await authed(`/api/publisher/v1/apps/${app}/keys`, { method: 'POST' });
+  out.data(`rotated last4=${data.last4}. Full value below — copy now, never shown again.`);
+  out.data(data.api_key);
+} else {
+  out.error(`unknown command "${cmd}${sub ? ` ${sub}` : ''}". Run voidnet --help.`);
+}
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  const opener = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start' : 'xdg-open';
+  out.diag(`opening browser: ${url}`);
+  import('node:child_process').then(({ execFile }) => {
+    execFile(opener, [url], (err) => {
+      if (err) {
+        out.diag(`auto-open failed (${opener}). Open this URL manually:`);
+        out.data(url);
+      }
+    });
+  });
+}
+
+async function browserLogin() {
+  const [{ randomBytes, createHash }, { createServer }] = await Promise.all([
+    import('node:crypto'),
+    import('node:http'),
+  ]);
+  const mgmtBase = ENV.mgmtBase;
+  const authBase = ENV.authBase;
+
+  const verifier = randomBytes(32).toString('base64url');
+  const challenge = createHash('sha256').update(verifier).digest('base64url');
+  const state = randomBytes(16).toString('hex');
+  const appFlags = [];
+  for (let i = 0; i < process.argv.length; i++) {
+    if (process.argv[i] === '--app' && process.argv[i + 1]) appFlags.push(process.argv[i + 1]);
+  }
+  if (appFlags.length > 0) {
+    out.diag(`login scoped to ${appFlags.length} app(s); consent preselects them, server enforces the subset`);
+  }
+  out.diag(`starting loopback listener mgmt=${mgmtBase} auth=${authBase}`, { verboseOnly: true });
+
+  const { code, redirectUri, gotState } = await new Promise((resolve, reject) => {
+    let boundPort = 0;
+    const server = createServer((req, res) => {
+      const u = new URL(req.url, 'http://127.0.0.1');
+      if (u.pathname !== '/callback') {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end('<h1>Signed in. Return to the terminal.</h1>');
+      const done = { code: u.searchParams.get('code'), redirectUri: `http://127.0.0.1:${boundPort}/callback`, gotState: u.searchParams.get('state') };
+      server.close();
+      resolve(done);
+    });
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      boundPort = server.address().port;
+      const redirect = `http://127.0.0.1:${boundPort}/callback`;
+      const appHint = appFlags.map((a) => `&app_ids=${encodeURIComponent(a)}`).join('');
+      const authUrl = `${authBase}/api/auth/oauth/authorize?response_type=code&client_id=voidnet-cli&redirect_uri=${encodeURIComponent(redirect)}&scope=publisher_login&state=${state}&code_challenge=${challenge}&code_challenge_method=S256${appHint}`;
+      openBrowser(authUrl);
+      out.diag('waiting for browser approval (5 minutes)...');
+      setTimeout(() => {
+        server.close();
+        reject(new Error('Timed out waiting for browser approval'));
+      }, 5 * 60 * 1000).unref?.();
+    });
+  }).catch((err) => {
+    out.error(`login failed: ${err.message}`);
+    process.exit(1);
+  });
+
+  if (!code || gotState !== state) {
+    out.error('login failed: missing code or state mismatch (possible CSRF — aborted)');
+    process.exit(1);
+  }
+  out.diag('approval received, exchanging code...');
+
+  const tokenRes = await fetch(`${authBase}/api/auth/oauth/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      grant_type: 'authorization_code',
+      client_id: 'voidnet-cli',
+      code,
+      redirect_uri: redirectUri,
+      code_verifier: verifier,
+    }),
+  });
+  const tokenData = await tokenRes.json().catch(() => ({}));
+  if (!tokenRes.ok || !tokenData.access_token) {
+    out.error(`code exchange failed: ${tokenData.error || tokenData.code || tokenRes.status}`);
+    process.exit(1);
+  }
+  out.diag('accounts token issued, exchanging for publisher token...');
+
+  const exRes = await fetch(`${mgmtBase}/api/publisher/v1/auth/exchange`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ accounts_token: tokenData.access_token, app_ids: appFlags.length > 0 ? appFlags : undefined }),
+  });
+  const exData = await exRes.json().catch(() => ({}));
+  if (!exRes.ok || !exData.token) {
+    out.error(`publisher exchange failed: ${exData.code || exData.error || exRes.status}`);
+    process.exit(1);
+  }
+  saveConfig({ token: exData.token });
+  out.ok(`logged in. token last4=${exData.last4} scopes=${(exData.scopes || []).join(',')}`);
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "openvoidnet",
+  "version": "1.0.0",
+  "private": false,
+  "description": "Voidnet publisher CLI — manage your Voidnet apps from the terminal with browser-based login.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/roshaan-akther/void.git",
+    "directory": "packages/voidnet-cli"
+  },
+  "type": "module",
+  "bin": {
+    "voidnet": "bin/voidnet.js"
+  },
+  "scripts": {
+    "dev": "VOIDNET_ENV=development node bin/voidnet.js",
+    "test": "node test/env.test.mjs && node test/output.test.mjs && node test/update.test.mjs && node test/words.test.mjs"
+  },
+  "files": [
+    "bin/voidnet.js",
+    "src/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  }
+}

package/src/env.js

@@ -0,0 +1,55 @@
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+// Environment table: the only place hosts are defined. No includes()
+// heuristics anywhere — unknown hosts fail loud instead of guessing.
+export const ENVS = {
+  production: {
+    mgmtBase: 'https://openvoidnet.com',
+    authBase: 'https://accounts.openvoidnet.com',
+    liveBase: 'https://api.openvoidnet.com',
+    configFile: 'cli.json',
+  },
+  development: {
+    mgmtBase: 'http://localhost:3000',
+    authBase: 'http://localhost:3020',
+    liveBase: 'http://localhost:8090',
+    configFile: 'cli.development.json',
+  },
+};
+
+export function flagValue(argv, name) {
+  const i = argv.indexOf(name);
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : null;
+}
+
+// Resolve order: explicit flags > VOIDNET_* env > baked default (production).
+// Files without an env marker are ignored loudly — a token minted for one env
+// never addresses another, even by stale config.
+// noteworthy is true when anything deviates from a plain production run:
+// callers announce only then, so default runs stay silent.
+export function resolveEnv({ argv = process.argv, env = process.env, silent = false } = {}) {
+  const explicit = flagValue(argv, '--env');
+  let name = explicit || env.VOIDNET_ENV || 'production';
+  if (name !== 'production' && name !== 'development') {
+    console.error(`[voidnet] invalid env "${name}". Use production or development.`);
+    process.exit(1);
+  }
+  const table = ENVS[name];
+  const mgmtBase = flagValue(argv, '--base') || env.VOIDNET_MGMT_BASE || table.mgmtBase;
+  const authBase = flagValue(argv, '--auth-base') || env.VOIDNET_AUTH_BASE || table.authBase;
+  const liveBase = flagValue(argv, '--live-base') || env.VOIDNET_LIVE_BASE || table.liveBase;
+  const configPath = join(homedir(), '.config', 'voidnet', table.configFile);
+  const noteworthy =
+    name !== 'production' ||
+    explicit !== null ||
+    flagValue(argv, '--base') !== null ||
+    flagValue(argv, '--auth-base') !== null ||
+    flagValue(argv, '--live-base') !== null ||
+    env.VOIDNET_ENV !== undefined ||
+    env.VOIDNET_MGMT_BASE !== undefined ||
+    env.VOIDNET_AUTH_BASE !== undefined ||
+    env.VOIDNET_LIVE_BASE !== undefined;
+  if (!silent) console.log(`[voidnet] env=${name} mgmt=${mgmtBase} auth=${authBase} live=${liveBase}`);
+  return { name, mgmtBase, authBase, liveBase, configPath, noteworthy };
+}

package/src/out.js

@@ -0,0 +1,42 @@
+// Unified output system: every command speaks through this module.
+// stdout = data only, always pipe-safe. stderr = diagnostics, errors, identity.
+// Modes: --json > --quiet > --verbose > default. No command invents output.
+export function resolveMode(argv = process.argv) {
+  if (argv.includes('--json')) return 'json';
+  if (argv.includes('--quiet')) return 'quiet';
+  if (argv.includes('--verbose')) return 'verbose';
+  return 'default';
+}
+
+export function makeOut(mode) {
+  const loud = mode === 'verbose';
+  return {
+    mode,
+    // Data: stdout, never prefixed, pipe-safe.
+    data(text) {
+      console.log(text);
+    },
+    json(payload) {
+      console.log(JSON.stringify({ data: payload }, null, 2));
+    },
+    // Diagnostics: stderr, prefixed, verbose-gated where marked.
+    diag(message, { verboseOnly = false } = {}) {
+      if (verboseOnly && !loud) return;
+      if (mode === 'quiet' && !verboseOnly) {
+        // quiet keeps errors only; diag lines drop. Errors use error() below.
+        return;
+      }
+      console.error(`[voidnet] ${message}`);
+    },
+    // Errors: stderr always, named shape, mapped exit code.
+    error(message, code = 1) {
+      console.error(`[voidnet] ${message}`);
+      process.exit(code);
+    },
+    // One-line success note on stderr (never pollutes data streams).
+    ok(message) {
+      if (mode === 'quiet') return;
+      console.error(`[voidnet] ${message}`);
+    },
+  };
+}

package/src/probes.js

@@ -0,0 +1,46 @@
+// Shared probe harness for status + doctor. Every probe is bounded,
+// named, and returns a row — never throws, never hangs past its budget.
+// Chatter goes through onVerbose so quiet runs show rows only.
+export async function probe(name, url, { timeoutMs = 3000, expectJson = false, onVerbose = null } = {}) {
+  const started = Date.now();
+  const say = (m) => { if (onVerbose) onVerbose(m); };
+  say(`probe start name=${name}`);
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+      res = await fetch(url, { signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+    const latencyMs = Date.now() - started;
+    let detail = `http=${res.status}`;
+    if (expectJson) {
+      const body = await res.json().catch(() => null);
+      if (body && typeof body.status === 'string') detail += ` status=${body.status}`;
+    }
+    const ok = res.status < 500;
+    say(`probe done name=${name} ok=${ok} latency=${latencyMs}ms`);
+    return { name, ok, detail, latencyMs };
+  } catch (err) {
+    const latencyMs = Date.now() - started;
+    const reason = err && err.name === 'AbortError' ? 'timeout' : String((err && err.message) || err);
+    say(`probe failed name=${name} reason=${reason}`);
+    return { name, ok: false, detail: reason, latencyMs };
+  }
+}
+
+export function checkNode(minMajor = 20, minMinor = 9, { onVerbose = null } = {}) {
+  const match = /^v(\d+)\.(\d+)/.exec(process.version || '');
+  const major = match ? Number(match[1]) : 0;
+  const minor = match ? Number(match[2]) : 0;
+  const ok = major > minMajor || (major === minMajor && minor >= minMinor);
+  if (onVerbose) onVerbose(`runtime check node=${process.version} ok=${ok}`);
+  return {
+    name: 'runtime',
+    ok,
+    detail: ok ? `node=${process.version}` : `node=${process.version}, need >=${minMajor}.${minMinor} — upgrade Node`,
+    latencyMs: 0,
+  };
+}

package/src/update.js

@@ -0,0 +1,106 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 3000;
+
+function cachePath(homeDir) {
+  return `${homeDir}/.config/voidnet/update-cache.json`;
+}
+
+function readCache(path) {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    console.error(`[voidnet] update cache unreadable: ${String(err && err.message || err)}`);
+    return null;
+  }
+}
+
+function writeCache(path, payload) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify({ ...payload, checkedAt: Date.now() }), { mode: 0o600 });
+  } catch (err) {
+    console.error(`[voidnet] update cache write failed: ${String(err && err.message || err)}`);
+  }
+}
+
+function newer(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) > (pb[i] || 0);
+  }
+  return false;
+}
+
+async function fetchMeta(mgmtBase) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(`${mgmtBase}/.well-known/voidnet.json`, { signal: controller.signal });
+    if (!res.ok) return null;
+    return await res.json().catch(() => null);
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Minimum-version gate: runs before the command. Fails loud (exit 3) when the
+// installed CLI is below minimum. Silence only on check failure, never on verdict.
+export async function gateMinimum({ pkgVersion, mgmtBase, homeDir, cache, onVerbose = null }) {
+  const say = (m) => { if (onVerbose) onVerbose(m); };
+  if (process.argv.includes('--no-update-check') || process.env.VOIDNET_NO_UPDATE_CHECK === '1') {
+    say('update check disabled by flag/env');
+    return null;
+  }
+  const path = cache?.path || cachePath(homeDir);
+  let meta = cache?.meta || null;
+  if (!meta) {
+    const cached = readCache(path);
+    if (cached && Date.now() - (cached.checkedAt || 0) < CACHE_TTL_MS && cached.cli) {
+      meta = cached;
+      say('update metadata from cache');
+    } else {
+      const fresh = await fetchMeta(mgmtBase);
+      if (fresh && fresh.cli) {
+        meta = fresh;
+        writeCache(path, fresh);
+        say('update metadata refreshed');
+      } else {
+        say('update metadata unreachable — proceeding without version gate');
+        return null;
+      }
+    }
+  }
+  const minimum = meta.cli.minimum;
+  if (minimum && newer(minimum, pkgVersion)) {
+    console.error(`[voidnet] CLI ${pkgVersion} is below minimum ${minimum}. Update: npm i -g openvoidnet`);
+    process.exit(3);
+  }
+  return meta;
+}
+
+// Newer-version notice: runs after successful commands, stderr only.
+export function noteUpdate({ pkgVersion, meta }) {
+  if (!meta || !meta.cli || !meta.cli.latest) return;
+  if (newer(meta.cli.latest, pkgVersion)) {
+    const extra = meta.cli.message ? ` ${meta.cli.message}` : '';
+    console.error(`[voidnet] update available: voidnet ${meta.cli.latest} (you have ${pkgVersion}). npm i -g openvoidnet.${extra}`);
+  }
+}
+
+export const __test = { newer };
+
+export function readPkgVersion(metaUrl) {
+  try {
+    return JSON.parse(readFileSync(new URL('../package.json', metaUrl), 'utf8')).version || '0.0.0';
+  } catch (err) {
+    console.error(`[voidnet] version unreadable: ${String(err && err.message || err)}`);
+    process.exit(1);
+  }
+}

package/src/words.js

@@ -0,0 +1,29 @@
+// User vocabulary: the only words that may reach human eyes.
+// Internal names (auth, management, gateway, env, mcp, table columns) never
+// appear in output directly — every display string passes through here.
+// Tests assert these exact values appear in status/doctor rows.
+export const SERVICE_NAMES = {
+  auth: 'Sign-in service',
+  management: 'Publisher API',
+  gateway: 'Gateway',
+};
+
+export function serviceName(key) {
+  const name = SERVICE_NAMES[key];
+  if (!name) {
+    console.error(`[voidnet] unknown service key "${key}" — refusing to guess a label`);
+    process.exit(1);
+  }
+  return name;
+}
+
+// Marketplace vocabulary for app kinds. Raw adapter codes never reach humans;
+// unknown future kinds pass through verbatim rather than failing the command.
+export const ADAPTER_NAMES = {
+  mcp: 'tool',
+  llm: 'model',
+};
+
+export function adapterName(code) {
+  return ADAPTER_NAMES[code] || String(code);
+}