quoxcli 0.0.0-stage → 0.3.1

package/lib/commands/discord.js

@@ -0,0 +1,132 @@
+/**
+ * `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), shown in each subcommand's --help. qdp has no
+ * --help handling of its own; before quox#1077 this command hand-rolled arg
+ * dispatch and had to intercept --help itself (quox#603). Commander
+ * subcommands now answer --help before any action runs.
+ */
+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',
+};
+
+/**
+ * qdp verbs that only READ (quox#1077). Each was checked against bin/qdp.mjs:
+ * status/instances/bindings print config.json, the pid file and the systemd
+ * state; gaps GETs the open support-gap inbox items; health reads the pid and
+ * systemd state; doctor GETs the control API /health and Discord's channel,
+ * webhook and @me endpoints. None issues PUT/POST/PATCH/DELETE or writes a
+ * file. bind, unbind and provision PUT/DELETE bindings and create channels.
+ */
+export const DISCORD_READ_VERBS = ['status', 'instances', 'bindings', 'gaps', 'health', 'doctor'];
+export const DISCORD_WRITE_VERBS = ['bind', 'unbind', 'provision'];
+
+// No "Usage:" line here: the matrix's --help walker (scripts/matrix/cli-tree.mjs) reads one as the command's usage.
+const GENERAL_USAGE = Object.values(VERB_USAGE).map((u) => `  ${u}`).join('\n')
+  + '\n\nRun `quox discord <verb> --help` for a single verb\'s usage.';
+
+function runQdp(verb, args = []) {
+  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, verb, ...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);
+}
+
+const VERB_DESC = { unbind: 'remove a channel binding', doctor: 'per-binding view/webhook/liveness check (exits non-zero if any binding is broken)' };
+const firstLine = (verb) => VERB_DESC[verb] || VERB_USAGE[verb].split('\n')[0].replace(/^qdp \S+(?: [<[][^\]>]*[>\]])*\s+/, '').trim();
+
+/**
+ * One commander subcommand per qdp verb (quox#1077). It used to be a single
+ * `discord [args...]` leaf, so the CLI leaf policy could only class the whole
+ * group, and it classed it write: a read like `quox discord bindings` was held
+ * for approval. Per-verb leaves let reads be read and keep bind/unbind/provision
+ * write. Commander's own --help runs before any action, so `--help` can never
+ * reach qdp and run a mutating verb (quox#603).
+ */
+export function registerDiscordCommands(program) {
+  const discord = program
+    .command('discord')
+    .description('Quox Discord Pro daemon: status | instances | bindings | gaps | health | doctor | bind | unbind | provision')
+    .addHelpText('after', `\nPer-verb usage (each verb shells straight through to qdp):\n${GENERAL_USAGE}`);
+
+  for (const verb of DISCORD_READ_VERBS) {
+    discord
+      .command(verb)
+      .description(firstLine(verb) || verb)
+      .addHelpText('after', `\nqdp usage:\n  ${VERB_USAGE[verb]}`)
+      .action(() => runQdp(verb));
+  }
+
+  const writeArgs = { bind: '<channelId> <mode> [pairs...]', unbind: '<channelId>', provision: '<agentId> [args...]' };
+  for (const verb of DISCORD_WRITE_VERBS) {
+    const leaf = discord
+      .command(`${verb} ${writeArgs[verb]}`);
+    // Only provision has a dry run in qdp. Declaring it here keeps it in --help and lets the
+    // root guard refuse `discord bind|unbind --dry-run` instead of binding for real.
+    if (verb === 'provision') leaf.option('--dry-run', 'print exactly what it WOULD do, change nothing');
+    leaf
+      .description(firstLine(verb) || verb)
+      .addHelpText('after', `\nqdp usage:\n  ${VERB_USAGE[verb]}`)
+      // qdp parses its own options (provision --mode/--host/...), so they pass through unchanged.
+      .allowUnknownOption(true)
+      .action((...a) => {
+        const cmd = a[a.length - 1];
+        const args = [...cmd.args];
+        // --dry-run is also a root quox flag, so commander hands it to the root and it never reaches
+        // cmd.args: a requested dry run of provision used to provision for real. Forward it explicitly.
+        if (cmd.optsWithGlobals().dryRun && !args.includes('--dry-run')) args.push('--dry-run');
+        runQdp(verb, args);
+      });
+  }
+}

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.');
+    });
+}