quoxcli 0.0.0-stage → 0.2.0

package/lib/commands/discord.js

@@ -0,0 +1,96 @@
+/**
+ * `quox discord` — Quox Discord Pro from the canonical CLI (quoxcli-parity-gate:
+ * nothing ships without quox CLI support).
+ *
+ * Same principle as `quox done`: this is a thin wrapper over the daemon's own
+ * control CLI (`qdp`, quox-discord-pro/bin/qdp.mjs), not a reimplementation.
+ * The daemon already exposes status | instances | bindings | bind | unbind |
+ * gaps | health over its token-gated loopback control API, and qdp is the one
+ * client for it. Two clients for one control surface is how a control surface
+ * drifts, so `quox discord <verb>` shells straight through to qdp with the
+ * arguments unchanged, and qdp's exit code is passed through.
+ *
+ * Host-local, like `quox done` shelling to the DoneEngine: the operator CLI
+ * runs where the daemon runs (one daemon per QuoxCORE instance). Set
+ * QDP_CLI_PATH if qdp lives elsewhere.
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const QDP = process.env.QDP_CLI_PATH
+  || path.join(os.homedir(), 'quox-discord-pro', 'bin', 'qdp.mjs');
+
+/**
+ * Per-verb usage, mirrored from qdp.mjs's own header doc block (bin/qdp.mjs
+ * in the quox-discord-pro repo). qdp itself has no --help handling of its
+ * own, and this command hand-rolls arg dispatch (allowUnknownOption +
+ * helpOption(false), see below) rather than commander subcommands, so
+ * `--help`/`-h` was previously just another unrecognised arg forwarded
+ * straight through to qdp — which silently ran the verb instead of showing
+ * help. Worst case for a mutating verb (bind/unbind/provision): "--help"
+ * would have actually bound/unbound/provisioned a channel. This map is
+ * checked BEFORE qdp is ever spawned so that can't happen (quox#603).
+ */
+const VERB_USAGE = {
+  status: 'qdp status                 daemon liveness, instances, binding count',
+  instances: 'qdp instances              configured instances and their targets',
+  bindings: 'qdp bindings               every channel binding',
+  gaps: 'qdp gaps                   open support-gap items awaiting an official answer',
+  health: 'qdp health                 one-line OK/actionable summary',
+  doctor: 'qdp doctor                 per-binding view/webhook/liveness check; exits\n'
+    + '                            non-zero if any binding is non-functional',
+  bind: 'qdp bind <channelId> <mode> [key=value ...]   bind an EXISTING channel',
+  unbind: 'qdp unbind <channelId>',
+  provision: 'qdp provision <agent-id> [options]   create/reuse a channel AND bind it\n'
+    + '    --mode <feed|bridge|team|roundtable>   default: feed\n'
+    + '    --channel <name>            default: feed-<agent-id> for feed, <agent-id> otherwise\n'
+    + '    --host <hostname-or-ip>     dev server the agent runs on (sets bridge_remote_host)\n'
+    + '    --inbox <name>              remote session-mail inbox (default <agent-id>-inbox)\n'
+    + '    --outbox <name>             remote outbox (default discord-outbox)\n'
+    + '    --two-way                   allow authorised humans to talk back (bridge only)\n'
+    + '    --persona <name>            webhook display name (default: titlecased agent id)\n'
+    + '    --roster <ids>              roundtable only: comma-separated "id" or "id:role" list\n'
+    + '    --dry-run                   print exactly what it WOULD do, change nothing',
+};
+
+const GENERAL_USAGE = 'Usage: quox discord <verb> [args...]\n\n'
+  + Object.values(VERB_USAGE).map((u) => `  ${u}`).join('\n')
+  + '\n\nRun `quox discord <verb> --help` for a single verb\'s usage.';
+
+function printVerbHelp(verb) {
+  if (verb && VERB_USAGE[verb]) {
+    process.stdout.write(`Usage:\n  ${VERB_USAGE[verb]}\n`);
+  } else {
+    process.stdout.write(`${GENERAL_USAGE}\n`);
+  }
+}
+
+export function registerDiscordCommands(program) {
+  program
+    .command('discord [args...]')
+    .description('Quox Discord Pro daemon: status | instances | bindings | bind | unbind | gaps | health')
+    .allowUnknownOption(true)
+    .helpOption(false)
+    .action((args = []) => {
+      if (args.includes('--help') || args.includes('-h')) {
+        printVerbHelp(args[0]);
+        process.exit(0);
+      }
+      if (!fs.existsSync(QDP)) {
+        process.stderr.write(
+          `Discord Pro control CLI (qdp) not found at ${QDP}\n` +
+          'Set QDP_CLI_PATH if it lives elsewhere, or install the quox-discord-pro daemon on this host.\n',
+        );
+        process.exit(2);
+      }
+      const r = spawnSync(process.execPath, [QDP, ...args], { stdio: 'inherit' });
+      if (r.error) {
+        process.stderr.write(`qdp failed to run: ${r.error.message}\n`);
+        process.exit(2);
+      }
+      process.exit(r.status ?? 2);
+    });
+}

package/lib/commands/doctor.js

@@ -0,0 +1,181 @@
+/**
+ * quox doctor — Platform Diagnostics
+ *
+ * Deep-checks every service, database, agent daemon, and credential.
+ * Reports pass/warning/critical with actionable details.
+ *
+ * CLI-3b (Stream CLI Phase 3)
+ */
+
+import chalk from 'chalk';
+import { SERVICE_PORTS } from '../core/config.js';
+import { emitCliEvent } from '../core/aee.js';
+import { resolveCliVersion, checkCliDrift } from '../core/version.js';
+
+const CHECKS = [
+  // Core services
+  { name: 'Auth service', service: 'auth', port: 3101, path: '/health', critical: true },
+  { name: 'Memory service', service: 'memory', port: 3103, path: '/health' },
+  { name: 'Collector', service: 'collector', port: 9848, path: '/health', critical: true },
+  { name: 'QuoxFlow', service: 'quoxflow', port: 3200, path: '/health' },
+  { name: 'Files service', service: 'files', port: 3102, path: '/health' },
+  // External services
+  { name: 'QuoxAgent daemon', port: 9847, path: '/health', url: 'http://localhost:9847' },
+  { name: 'Qdrant vectors', port: 6333, path: '/', url: 'http://localhost:6333' },
+];
+
+async function checkEndpoint(url, path, timeoutMs = 3000) {
+  const start = Date.now();
+  try {
+    const resp = await fetch(`${url}${path}`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const latency = Date.now() - start;
+    if (resp.ok) {
+      return { status: 'pass', latency_ms: latency };
+    }
+    return { status: 'warn', latency_ms: latency, detail: `HTTP ${resp.status}` };
+  } catch (err) {
+    return { status: 'fail', latency_ms: null, detail: err.message };
+  }
+}
+
+/**
+ * Every doctor check, in this process: services, auth token, CLI version. Shared by `quox doctor` and the
+ * conversation's /doctor so the two can never disagree. -> [{ name, status, detail?, latency_ms?, ... }].
+ */
+export async function runDoctorChecks({ config }) {
+  // Check all services in parallel — per-item try/catch so one failure doesn't lose all results
+  const checks = await Promise.all(
+    CHECKS.map(async (check) => {
+      try {
+        const url = check.url || config.getServiceUrl(check.service);
+        let result = await checkEndpoint(url, check.path);
+        // #623: doctor was crying CRITICAL when the configured URL was just
+        // WRONG (stale profile override / wrong scheme+host) while the
+        // service was up on its loopback bind. On a connection failure,
+        // probe http://127.0.0.1:<port> — if THAT answers, the service is
+        // UP and the verdict is "misconfigured URL", not "service down".
+        // Downgrade to a warning that names the reachable bind + the bad
+        // URL, so an operator fixes the config instead of chasing an outage.
+        if (result.status === 'fail' && check.port) {
+          const loopbackUrl = `http://127.0.0.1:${check.port}`;
+          if (url !== loopbackUrl) {
+            const alt = await checkEndpoint(loopbackUrl, check.path);
+            if (alt.status === 'pass') {
+              result = {
+                status: 'warn',
+                latency_ms: alt.latency_ms,
+                detail: `reachable at ${loopbackUrl} but configured URL ${url} failed — profile URL likely stale/wrong (misconfig, not an outage)`,
+              };
+            }
+          }
+        }
+        return {
+          name: check.name,
+          port: check.port,
+          ...result,
+          critical: check.critical || false,
+        };
+      } catch {
+        return {
+          name: check.name,
+          port: check.port,
+          ok: false,
+          status: 'error',
+          ms: 0,
+          critical: check.critical || false,
+        };
+      }
+    })
+  );
+
+  // Check auth token. fleet #479: the CURRENT profile (persisted
+  // default, or a -p/QUOX_PROFILE override) is config._effectiveProfile,
+  // never config._data.activeProfile (that's always the persisted
+  // default now, and would report the wrong profile under an override).
+  const auth = config.getAuth?.() || config._data?.profiles?.[config._effectiveProfile]?.auth;
+  if (auth?.access_token) {
+    const expired = auth.expires_at && Date.now() > auth.expires_at;
+    if (expired) {
+      checks.push({ name: 'Auth token', status: 'warn', detail: 'expired' });
+    } else {
+      const remaining = auth.expires_at ? Math.round((auth.expires_at - Date.now()) / 3600000) : '?';
+      checks.push({ name: 'Auth token', status: 'pass', detail: `valid (expires in ${remaining}h)` });
+    }
+  } else {
+    checks.push({ name: 'Auth token', status: 'warn', detail: 'not logged in' });
+  }
+
+  // #610 Part 3: which build is this, and is it drifted from origin/main?
+  // A silently-stale CLI (the worktree was 32 commits behind and nothing
+  // said so) is a real warning, so a stale drift maps to 'warn' and bumps
+  // the exit code like any other. unknown/skip are informational (pass) —
+  // never fail a health check because we could not compute drift. The
+  // drift count reflects the last fetch (no network fetch here).
+  const cliVersion = resolveCliVersion();
+  const drift = checkCliDrift();
+  checks.push({
+    name: 'CLI version',
+    status: drift.status === 'stale' ? 'warn' : 'pass',
+    detail: `${cliVersion} · ${drift.detail}`,
+  });
+
+  return checks;
+}
+
+export function registerDoctorCommand(program, ctx) {
+  const { config, client } = ctx;
+
+  program
+    .command('doctor')
+    .description('Run platform health diagnostics')
+    .action(async (opts, cmd) => {
+      const outputFormat = cmd.parent?.opts()?.output || 'table';
+      const isJson = outputFormat === 'json' || cmd.parent?.opts()?.json;
+
+      const checks = await runDoctorChecks({ config });
+
+      // Summary
+      const passed = checks.filter(c => c.status === 'pass').length;
+      const warnings = checks.filter(c => c.status === 'warn').length;
+      const failed = checks.filter(c => c.status === 'fail').length;
+
+      if (isJson) {
+        console.log(JSON.stringify({ checks, summary: { passed, warnings, failed } }, null, 2));
+        return;
+      }
+
+      // Render
+      console.log('');
+      for (const c of checks) {
+        const icon = c.status === 'pass' ? chalk.green(' ✓')
+          : c.status === 'warn' ? chalk.yellow(' ⚠')
+          : chalk.red(' ✗');
+
+        const latency = c.latency_ms != null ? chalk.dim(` (${c.latency_ms}ms)`) : '';
+        const detail = c.detail ? chalk.dim(` ${c.detail}`) : '';
+        const port = c.port ? chalk.dim(` ${c.port}`) : '';
+
+        console.log(`${icon} ${c.name.padEnd(20)}${port}${latency}${detail}`);
+      }
+
+      console.log('');
+      const parts = [];
+      if (passed) parts.push(chalk.green(`${passed} passed`));
+      if (warnings) parts.push(chalk.yellow(`${warnings} warning${warnings > 1 ? 's' : ''}`));
+      if (failed) parts.push(chalk.red(`${failed} critical`));
+      console.log(` ${parts.join('  ')}`);
+      console.log('');
+
+      emitCliEvent(client, {
+        command: 'doctor',
+        intent: 'quox.cli.doctor',
+        payload: { passed, warnings, failed, total: checks.length },
+        status: failed > 0 ? 'error' : 'success',
+      });
+
+      if (failed > 0) process.exitCode = 2;
+      else if (warnings > 0) process.exitCode = 1;
+    });
+}

package/lib/commands/domain.js

@@ -0,0 +1,114 @@
+/**
+ * Domain commands: org domain verification (DNS TXT record ownership proof)
+ *
+ * quox domain list|add|verify|remove
+ *
+ * Backend: services/auth/routes/domains.js, mounted at plain `/api`
+ * (org-scoped IN the URL: /api/orgs/:orgId/domains...). Team-tier+ +
+ * ORG_MANAGE_SETTINGS gated — expect 402/403 on non-team orgs.
+ *
+ * `add` returns a verification token and human-readable DNS instructions;
+ * `verify` re-checks DNS and returns 202 (retryable) rather than an error
+ * when the TXT record isn't there yet or hasn't propagated.
+ */
+
+import { formatOutput, formatDetail, printSuccess, printWarning, printInfo } from '../core/output.js';
+import { resolveOrgId } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function registerDomainCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const domain = program
+    .command('domain')
+    .description('Manage org domain verification (team+ — DNS ownership proof)');
+
+  // ── domain list ──────────────────────────────────────────────────────────────
+
+  domain
+    .command('list')
+    .description('List domains claimed by the active org')
+    .action(async () => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('domains.list', { orgId });
+      const data = await client.get(ep.path, { service: ep.service });
+      const rows = data.domains || data || [];
+
+      formatOutput({
+        // fleet #392: column is verified_at (a timestamp), not a `verified` flag.
+        columns: ['id', 'domain', 'verified_at', 'created_at'],
+        headers: ['ID', 'Domain', 'Verified', 'Created'],
+        rows,
+      }, { format: program.opts().output, emptyMessage: 'No domains claimed for this org.' });
+    });
+
+  // ── domain add ───────────────────────────────────────────────────────────────
+
+  domain
+    .command('add')
+    .description('Claim a domain and get its DNS verification instructions')
+    .argument('<domain>', 'domain name (e.g. "example.com")')
+    .action(async (domainName) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = { domain: domainName };
+
+      const ep = resolveEndpoint('domains.create', { orgId });
+      const data = await client.post(ep.path, { service: ep.service, body });
+      printSuccess(`Domain "${domainName}" claim started.`);
+      formatDetail(data.domain || {}, { format: program.opts().output });
+      if (data.instructions && program.opts().output !== 'json') {
+        printInfo(data.instructions);
+      }
+    });
+
+  // ── domain verify ────────────────────────────────────────────────────────────
+
+  domain
+    .command('verify')
+    .description('Re-check DNS for a claimed domain')
+    .argument('<domainId>', 'domain ID')
+    .action(async (domainId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('domains.verify', { orgId, domainId });
+      const data = await client.post(ep.path, { service: ep.service });
+
+      if (data.verified) {
+        printSuccess('Domain verified.');
+      } else {
+        printWarning(`Not verified yet (reason: ${data.reason || 'unknown'}).${data.retryable ? ' Retryable — DNS changes can take up to 48 hours.' : ''}`);
+      }
+    });
+
+  // ── domain remove ────────────────────────────────────────────────────────────
+
+  domain
+    .command('remove')
+    .description('Remove a claimed domain')
+    .argument('<domainId>', 'domain ID')
+    .option('--force', 'skip confirmation')
+    .action(async (domainId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+
+      if (!options.force && !program.opts().yes) {
+        const { default: inquirer } = await import('inquirer');
+        const ans = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'confirm',
+          message: `Remove domain ${domainId}? SSO/user-domain routing tied to it will stop working.`,
+          default: false,
+        }]);
+        if (!ans.confirm) {
+          printInfo('Cancelled.');
+          return;
+        }
+      }
+
+      const ep = resolveEndpoint('domains.delete', { orgId, domainId });
+      await client.delete(ep.path, { service: ep.service });
+      printSuccess('Domain removed.');
+    });
+}

package/lib/commands/done.js

@@ -0,0 +1,277 @@
+/**
+ * `quox done` — Quox DoneEngine from the terminal.
+ *
+ * The house gate is that nothing ships without CLI support, and the north star
+ * is Claude running Quox headless. That matters more here than for most
+ * surfaces: DoneEngine's primary users are AGENTS, not people. "Is this
+ * actually done?" is a question something asks before it acts, so a completion
+ * engine reachable only from a dashboard fails its own premise.
+ *
+ * This is a thin wrapper over the quox-gauge engine rather than a
+ * reimplementation. Two implementations of a rule set is how a rule set
+ * drifts, which is the thing DoneEngine exists to catch, so there is exactly
+ * one engine and the CLI shells out to it.
+ *
+ * ENGINE RESOLUTION (#456, extended by the fetch follow-on below): defaults
+ * to ~/quox-gauge/gauge.mjs, which only ever existed on the box quox-gauge
+ * was developed on, so every other dev-enabled host got a bare "not found"
+ * error. `quox dev enable` delivers the engine to /opt/quoxgauge and points
+ * QUOX_DONEENGINE_PATH at it via the generated CLI wrapper (see
+ * devServerRefresh.js), so a fresh dev-enabled host resolves it there
+ * without any local checkout.
+ *
+ * FETCH FOLLOW-ON: enable is correctly human-gated (requireHumanAdmin), so a
+ * RESIDENT agent with a missing or stale engine on a host nobody has run
+ * `quox dev enable` on had no self-service path — permanently stuck waiting
+ * on a human. `quox done fetch` closes that: it pulls the same public bundle
+ * (/download/quoxgauge-bundle.tar.gz) directly and installs it, no human in
+ * the loop, no new permission (see cli/lib/core/doneEngineFetch.js for the
+ * fetch/extract/verify logic). Resolution now also checks a user-local
+ * fallback (~/.local/share/quox/gauge/gauge.mjs), which is where fetch lands
+ * when /opt/quoxgauge is not writable and there is no passwordless sudo. A
+ * missing engine or packs directory names `quox done fetch` first (the
+ * self-service fix) and `quox dev enable` second.
+ *
+ * EXIT CODES are the contract, and `check` passes the engine's through
+ * unchanged:
+ *   0  CLEAR    every gate in the pack passes and the running code agrees
+ *   1  REFUSED  a named gate fails; reasons are printed
+ *   2  UNKNOWN  insufficient evidence to say either way
+ *
+ * UNKNOWN is deliberately not folded into either neighbour. Treating "no
+ * evidence" as approval is the exact failure this engine was built after, and
+ * treating it as refusal trains people to ignore refusals.
+ *
+ * ADVISORY. `quox done check` never blocks anything. Whether DoneEngine may
+ * refuse a deploy is an open owner decision on the DONEENGINE stream, and a
+ * tool that started refusing other people's deploys before that was settled
+ * would be taking a governance power nobody granted it.
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  resolveFetchDestination,
+  fetchEngine,
+  OPT_GAUGE_DIR,
+  userLocalGaugeDir,
+  legacyGaugeDir,
+} from '../core/doneEngineFetch.js';
+import { printSuccess, printInfo } from '../core/output.js';
+
+/**
+ * Engine resolution order (see the FETCH FOLLOW-ON note above):
+ *   1. QUOX_DONEENGINE_PATH (explicit override, wins even if the file is
+ *      missing — the honest "not found" error below still needs a concrete
+ *      path to name)
+ *   2. /opt/quoxgauge/gauge.mjs — where `quox dev enable` and a sudo-capable
+ *      `quox done fetch` both put it
+ *   3. ~/.local/share/quox/gauge/gauge.mjs — where `quox done fetch` puts it
+ *      when /opt/quoxgauge is not writable and there is no passwordless sudo
+ *   4. ~/quox-gauge/gauge.mjs — legacy default, kept as the final fallback so
+ *      the error message always names a concrete path
+ *
+ * Exported (rather than inlined into the ENGINE constant) so this order is
+ * unit-testable with an injected existsSync/env/home instead of the real
+ * filesystem.
+ */
+export function resolveEnginePath({ env = process.env, existsSync = fs.existsSync, home = os.homedir() } = {}) {
+  if (env.QUOX_DONEENGINE_PATH) return env.QUOX_DONEENGINE_PATH;
+  const optPath = path.join(OPT_GAUGE_DIR, 'gauge.mjs');
+  if (existsSync(optPath)) return optPath;
+  const userLocalPath = path.join(userLocalGaugeDir(home), 'gauge.mjs');
+  if (existsSync(userLocalPath)) return userLocalPath;
+  return path.join(legacyGaugeDir(home), 'gauge.mjs');
+}
+
+const ENGINE = resolveEnginePath();
+
+function runEngine(args) {
+  if (!fs.existsSync(ENGINE)) {
+    process.stderr.write(
+      `DoneEngine not found at ${ENGINE}\n` +
+      'Self-heal: `quox done fetch` pulls the engine bundle straight from ' +
+      'the collector, no human in the loop. Otherwise `quox dev enable` ' +
+      'delivers it to /opt/quoxgauge as part of full dev-server ' +
+      'provisioning. Or set QUOX_DONEENGINE_PATH to a checkout.\n',
+    );
+    // 2, not 1: a missing engine is "cannot tell", not "refused".
+    return 2;
+  }
+  const r = spawnSync(process.execPath, [ENGINE, ...args], { stdio: 'inherit' });
+  if (r.error) {
+    process.stderr.write(`DoneEngine failed to run: ${r.error.message}\n`);
+    return 2;
+  }
+  return r.status ?? 2;
+}
+
+function defaultExecFn(cmd, args) {
+  return spawnSync(cmd, args, { encoding: 'utf8' });
+}
+
+function defaultIsWritable(dir) {
+  let probe = dir;
+  while (!fs.existsSync(probe)) {
+    const parent = path.dirname(probe);
+    if (parent === probe) break;
+    probe = parent;
+  }
+  try {
+    fs.accessSync(probe, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function defaultFsOps() {
+  return {
+    existsSync: fs.existsSync,
+    readdirSync: fs.readdirSync,
+    writeFileSync: fs.writeFileSync,
+    rmSync: fs.rmSync,
+    isWritable: defaultIsWritable,
+    mkdtemp: () => fs.mkdtempSync(path.join(os.tmpdir(), 'quoxgauge-backup-')),
+    tmpFile: () => path.join(os.tmpdir(), `quoxgauge-bundle-${process.pid}-${Date.now()}.tar.gz`),
+  };
+}
+
+export function registerDoneCommands(program, ctx = {}) {
+  const done = program
+    .command('done')
+    .description('Quox DoneEngine: is this actually done, and what is the evidence?');
+
+  done
+    .command('check [subject]')
+    .description('Can this ship? exit 0 clear, 1 refused with reasons, 2 unknown. Advisory: never blocks.')
+    .option('--pack <id>', 'rule pack to judge against', 'launch-spine')
+    .option('--json', 'structured verdict for agents')
+    .option('--root <path>', 'judge <subject> in this repo, reading its own STATUS map with the selected pack (e.g. a plugin with --pack plugin)')
+    .action((subject, options) => {
+      const args = ['--can-ship', subject || 'all', '--pack', options.pack];
+      if (options.root) {
+        if (!subject) {
+          process.stderr.write('quox done check: --root needs a subject (the surface to judge in that repo).\n');
+          process.exitCode = 2;
+          return;
+        }
+        args.push('--subject', subject, '--root', path.resolve(options.root));
+      }
+      if (options.json) args.push('--json');
+      process.exitCode = runEngine(args);
+    });
+
+  done
+    .command('checklist [pack]')
+    .description('The builder checklist GENERATED from a pack (every gate the engine judges); --check verifies a doc that embeds it')
+    .option('--check <file>', 'exit 1 if the checklist block in this file has drifted from the pack')
+    .action((pack, options) => {
+      const args = ['--checklist', pack || 'plugin'];
+      if (options.check) args.push('--check', path.resolve(options.check));
+      process.exitCode = runEngine(args);
+    });
+
+  done
+    .command('board')
+    .description('Estate scoreboard: every surface, score, attested gates, deploy state')
+    .option('--json', 'machine-readable, includes raw deploy state')
+    .option('--dod', 'per-surface gates, split by evidence class')
+    .option('--no-deploy', 'skip docker/git; Deployed Ready becomes unknown, which is not a pass')
+    .action((options) => {
+      const args = [];
+      if (options.json) args.push('--json');
+      if (options.dod) args.push('--dod');
+      if (options.deploy === false) args.push('--no-deploy');
+      process.exitCode = runEngine(args);
+    });
+
+  done
+    .command('bar [pack]')
+    .description('One rule pack against its subjects: BOTH finish lines, build and deployed')
+    .option('--snapshot', 'append this reading to the snapshot history')
+    .option('--org <id>', 'measure FOR this org: plan evidence reads as it, the snapshot is stamped with it (default: the pack\'s own org field)')
+    .action((pack, options) => {
+      const args = pack ? ['--pack', pack] : ['--launch'];
+      if (options.snapshot) args.push('--snapshot');
+      if (options.org) args.push('--org', options.org);
+      process.exitCode = runEngine(args);
+    });
+
+  done
+    .command('history [pack]')
+    .description('Movement between snapshots, regressions listed first')
+    .action((pack) => {
+      process.exitCode = runEngine(pack ? ['--history', '--pack', pack] : ['--history']);
+    });
+
+  done
+    .command('packs')
+    .description('List available rule packs')
+    .action(() => {
+      const dir = path.join(path.dirname(ENGINE), 'packs');
+      if (!fs.existsSync(dir)) {
+        process.stderr.write(
+          `No packs directory at ${dir}\n` +
+          'This usually means the engine delivery is missing or stale. ' +
+          'Run `quox done fetch` to self-heal it (no human needed), or ' +
+          're-run `quox dev enable`, or set QUOX_DONEENGINE_PATH to a ' +
+          'checkout that has one.\n',
+        );
+        process.exitCode = 2;
+        return;
+      }
+      for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.json')).sort()) {
+        try {
+          const p = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+          const scoped = p.subjects ? `${p.subjects.length} subjects` : 'base pack';
+          process.stdout.write(`${(p.id || f).padEnd(16)} v${p.version || '?'}  ${scoped}  ${p.name || ''}\n`);
+        } catch {
+          process.stdout.write(`${f} (unreadable)\n`);
+        }
+      }
+    });
+
+  done
+    .command('fetch')
+    .description('Self-fetch the DoneEngine bundle, no human in the loop (quox#456 follow-on)')
+    .option('--dest <path>', 'install destination (default: $QUOX_DONEENGINE_HOME, else /opt/quoxgauge if writable/sudo-reachable, else ~/.local/share/quox/gauge)')
+    .option('--force', 'refetch and reinstall even if the current install already looks healthy')
+    .action(async (options) => {
+      const client = ctx.client;
+      if (!client) {
+        process.stderr.write('quox done fetch: no HTTP client available in this context.\n');
+        process.exitCode = 2;
+        return;
+      }
+      const execFn = ctx.execFn || defaultExecFn;
+      const isWritable = ctx.isWritable || defaultIsWritable;
+      const fsOps = ctx.fsOps || defaultFsOps();
+
+      const { dest, reason, needsSudo } = resolveFetchDestination({
+        destOption: options.dest,
+        env: process.env,
+        isWritable,
+        execFn,
+      });
+      process.stdout.write(`Destination: ${dest} (${reason})\n`);
+
+      try {
+        const result = await fetchEngine({ dest, needsSudo, force: !!options.force, client, execFn, fsOps });
+        if (result.status === 'noop') {
+          printInfo(result.message);
+        } else {
+          printSuccess(result.message);
+        }
+      } catch (err) {
+        process.stderr.write(`quox done fetch failed: ${err.message}\n`);
+        process.exitCode = 1;
+      }
+    });
+
+  return done;
+}
+
+export default registerDoneCommands;