quoxcli 0.0.0-stage → 0.3.1

package/lib/commands/watch.js

@@ -0,0 +1,167 @@
+/**
+ * Watch commands — real-time monitoring dashboards
+ *
+ * quox watch fleet        Live fleet status (polling)
+ * quox watch services     Live service health
+ */
+
+import chalk from 'chalk';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { joinServiceUrl } from '../core/config.js';
+
+/** Seconds to a short "1d 1h" / "3h 12m" / "45s" label. */
+function shortUptime(sec) {
+  if (typeof sec !== 'number' || !Number.isFinite(sec)) return '-';
+  const d = Math.floor(sec / 86400); const h = Math.floor((sec % 86400) / 3600); const m = Math.floor((sec % 3600) / 60);
+  if (d) return `${d}d ${h}h`;
+  if (h) return `${h}h ${m}m`;
+  return m ? `${m}m` : `${Math.floor(sec)}s`;
+}
+
+/**
+ * quox#946: one row per agent from GET /api/v1/agents (the same source as
+ * `quox fleet agents`). /api/v1/fleet/status carries totals only, which is why
+ * the old dashboard always said "No agents reporting".
+ */
+export function fleetRows(data) {
+  const list = Array.isArray(data) ? data : (Array.isArray(data?.agents) ? data.agents : []);
+  return list.map((a) => ({
+    host_id: a.host_id || a.system?.hostname || '-',
+    status: typeof a.status === 'object' ? (a.status?.health ?? a.status?.connection ?? 'unknown') : (a.status || 'unknown'),
+    cpu_percent: Math.round(a.resources?.cpu?.usage_percent ?? a.cpu_percent ?? 0),
+    memory_percent: Math.round(a.resources?.memory?.usage_percent ?? a.memory_percent ?? 0),
+    uptime: shortUptime(a.system?.uptime_seconds ?? a.uptime_seconds),
+    version: a.agent?.version || a.version || '-',
+    last_seen_seconds: typeof a.status?.last_seen_seconds === 'number' ? a.status.last_seen_seconds : null,
+  }));
+}
+
+/**
+ * quox#946: a slow service is a TIMEOUT, a refused connection is DOWN, a non-2xx
+ * answer is DEGRADED. The old dashboard called every failure "down".
+ */
+export async function probeService(url, fetchImpl = fetch, timeoutMs = 8000) {
+  const start = Date.now();
+  try {
+    const res = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs) });
+    const latency_ms = Date.now() - start;
+    return res.ok ? { status: 'healthy', latency_ms, code: res.status } : { status: 'degraded', latency_ms, code: res.status };
+  } catch (err) {
+    if (err?.name === 'TimeoutError' || err?.name === 'AbortError') return { status: 'timeout', latency_ms: Date.now() - start };
+    return { status: 'down', reason: err?.cause?.code || err?.message || 'error' };
+  }
+}
+
+export function registerWatchCommands(program, { client, auth, config }) {
+  const watch = program
+    .command('watch')
+    .description('Real-time monitoring dashboards');
+
+  watch
+    .command('fleet')
+    .description('Live fleet status dashboard')
+    .option('--interval <seconds>', 'Refresh interval', '5')
+    .action(async (opts) => {
+      auth.requireAuth();
+      const interval = Math.max(2, parseInt(opts.interval, 10) || 5) * 1000;
+      const fetchAgents = async () => {
+        const ep = resolveEndpoint('v1.agents.list');
+        return fleetRows(await client.get(ep.path, { service: ep.service }));
+      };
+
+      // --json: one snapshot, then exit (a dashboard loop is not machine output).
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify({ agents: await fetchAgents(), timestamp: new Date().toISOString() }, null, 2));
+        return;
+      }
+
+      console.log(chalk.cyan('Fleet Watch') + chalk.dim(' (Ctrl+C to stop)\n'));
+
+      const tick = async () => {
+        try {
+          const agents = await fetchAgents();
+
+          // Clear screen and redraw
+          process.stdout.write('\x1B[2J\x1B[H');
+          console.log(chalk.cyan.bold('QuoxCLI Fleet Watch') + chalk.dim(`  ${new Date().toLocaleTimeString()}  (Ctrl+C to stop)`));
+          console.log(chalk.dim('─'.repeat(72)));
+
+          if (agents.length === 0) {
+            console.log(chalk.yellow('  No agents reporting'));
+          } else {
+            const header = `  ${'HOST'.padEnd(16)} ${'STATUS'.padEnd(10)} ${'CPU'.padEnd(7)} ${'MEM'.padEnd(7)} ${'UPTIME'.padEnd(10)} ${'VERSION'}`;
+            console.log(chalk.dim(header));
+            console.log(chalk.dim('  ' + '─'.repeat(68)));
+
+            for (const a of agents) {
+              const statusColor = a.status === 'healthy' ? chalk.green : a.status === 'degraded' ? chalk.yellow : chalk.red;
+              const cpuColor = (a.cpu_percent || 0) > 80 ? chalk.red : (a.cpu_percent || 0) > 60 ? chalk.yellow : chalk.white;
+              const memColor = (a.memory_percent || 0) > 80 ? chalk.red : (a.memory_percent || 0) > 60 ? chalk.yellow : chalk.white;
+
+              console.log(
+                `  ${chalk.white(String(a.host_id || '').padEnd(16))} ` +
+                `${statusColor(String(a.status || 'unknown').padEnd(10))} ` +
+                `${cpuColor(String((a.cpu_percent || 0) + '%').padEnd(7))} ` +
+                `${memColor(String((a.memory_percent || 0) + '%').padEnd(7))} ` +
+                `${String(a.uptime).padEnd(10)} ` +
+                `${chalk.dim(a.version || '-')}`
+              );
+            }
+          }
+
+          console.log(chalk.dim('\n  ' + '─'.repeat(68)));
+          console.log(chalk.dim(`  ${agents.length} agents  |  refreshing every ${interval / 1000}s`));
+        } catch (err) {
+          console.error(chalk.red(`  Error: ${err.message}`));
+        }
+      };
+
+      await tick();
+      const timer = setInterval(tick, interval);
+      process.on('SIGINT', () => { clearInterval(timer); process.exit(0); });
+    });
+
+  watch
+    .command('services')
+    .description('Live service health dashboard')
+    .option('--interval <seconds>', 'Refresh interval', '10')
+    .action(async (opts) => {
+      const interval = Math.max(5, parseInt(opts.interval, 10) || 10) * 1000;
+      const services = [
+        { name: 'auth', port: 3101, path: '/health' },
+        { name: 'collector', port: 9848, path: '/health' },
+        { name: 'memory', port: 3103, path: '/health' },
+        { name: 'files', port: 3102, path: '/health' },
+        { name: 'orchestrator', port: 3100, path: '/health' },
+      ];
+
+      const probeAll = async () => Promise.all(services.map(async (svc) => ({
+        name: svc.name,
+        ...(await probeService(joinServiceUrl(config.getServiceUrl(svc.name), svc.path).href)),
+      })));
+
+      // --json: one snapshot, then exit.
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify({ services: await probeAll(), timestamp: new Date().toISOString() }, null, 2));
+        return;
+      }
+
+      const tick = async () => {
+        const results = await probeAll();
+        process.stdout.write('\x1B[2J\x1B[H');
+        console.log(chalk.cyan.bold('QuoxCLI Service Watch') + chalk.dim(`  ${new Date().toLocaleTimeString()}  (Ctrl+C to stop)`));
+        console.log(chalk.dim('─'.repeat(50)));
+        for (const r of results) {
+          if (r.status === 'healthy') console.log(`  ${chalk.green('●')} ${r.name.padEnd(14)} ${chalk.green('healthy')}  ${chalk.dim(r.latency_ms + 'ms')}`);
+          else if (r.status === 'degraded') console.log(`  ${chalk.yellow('●')} ${r.name.padEnd(14)} ${chalk.yellow(r.code)}     ${chalk.dim(r.latency_ms + 'ms')}`);
+          else if (r.status === 'timeout') console.log(`  ${chalk.yellow('●')} ${r.name.padEnd(14)} ${chalk.yellow('slow (no answer in ' + Math.round(r.latency_ms / 1000) + 's)')}`);
+          else console.log(`  ${chalk.red('●')} ${r.name.padEnd(14)} ${chalk.red('down')}  ${chalk.dim(r.reason || '')}`);
+        }
+        console.log(chalk.dim('\n  refreshing every ' + (interval / 1000) + 's'));
+      };
+
+      await tick();
+      const timer = setInterval(tick, interval);
+      process.on('SIGINT', () => { clearInterval(timer); process.exit(0); });
+    });
+}

package/lib/commands/webhook.js

@@ -0,0 +1,137 @@
+/**
+ * Webhook commands: org webhook subscribers (team_event fan-out targets).
+ *
+ * quox webhook list|create|rotate|delete
+ *
+ * Backend: services/auth/routes/webhooks.js, mounted at plain `/api`
+ * (org-scoped IN the URL: /api/orgs/:orgId/webhooks...). Enterprise-tier +
+ * ORG_MANAGE_SETTINGS gated — expect 402/403 on non-enterprise orgs.
+ *
+ * The secret is returned ONLY on create and rotate (plaintext, once) — it
+ * is never retrievable again after that response, by design (HMAC signing
+ * secret for payload verification). We print it prominently and warn the
+ * user to record it now.
+ *
+ * Valid `events` values are the frozen TEAM_EVENT_TYPES set
+ * (services/auth/utils/teamEvents.js): team.created, team.archived,
+ * team.member.invited, team.member.joined, team.member.left,
+ * team.member.role_changed. Not enumerated client-side — the server
+ * validates and returns `invalid_webhook` on an unknown type.
+ *
+ * Distinct from `quox trigger webhooks` (endpoints/triggers.js), which
+ * lists INBOUND workflow-trigger webhook paths on quoxflow, not these
+ * outbound org subscriptions.
+ */
+
+import { formatOutput, formatDetail, printSuccess, printWarning, printInfo } from '../core/output.js';
+import { resolveOrgId } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+function printSecret(secret) {
+  printWarning('Record this secret now — it will not be shown again:');
+  console.log(`  ${secret}`);
+}
+
+export function registerWebhookCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const webhook = program
+    .command('webhook')
+    .description('Manage org webhook subscribers (enterprise — team_event fan-out)');
+
+  // ── webhook list ─────────────────────────────────────────────────────────────
+
+  webhook
+    .command('list')
+    .description('List org webhook subscriptions')
+    .action(async () => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const data = await client.get(resolveEndpoint('webhooks.list', { orgId }).path, {
+        service: resolveEndpoint('webhooks.list', { orgId }).service,
+      });
+      const webhooks = data.webhooks || data || [];
+
+      formatOutput({
+        columns: ['id', 'url', 'events', 'enabled', 'created_at'],
+        headers: ['ID', 'URL', 'Events', 'Enabled', 'Created'],
+        rows: webhooks.map(w => ({
+          ...w,
+          events: Array.isArray(w.events) ? w.events.join(', ') : w.events,
+        })),
+      }, { format: program.opts().output, emptyMessage: 'No webhooks configured.' });
+    });
+
+  // ── webhook create ──────────────────────────────────────────────────────────
+
+  webhook
+    .command('create')
+    .description('Create an org webhook subscription')
+    .requiredOption('--url <url>', 'https:// endpoint to receive events')
+    .requiredOption('--events <events>', 'comma-separated team_event types (e.g. team.created,team.member.joined)')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const events = options.events.split(',').map(e => e.trim()).filter(Boolean);
+
+      const data = await client.post(resolveEndpoint('webhooks.create', { orgId }).path, {
+        service: resolveEndpoint('webhooks.create', { orgId }).service,
+        body: { url: options.url, events },
+      });
+      const created = data.webhook || data;
+      printSuccess(`Webhook created for ${options.url}.`);
+      formatDetail(created, {
+        format: program.opts().output,
+        fields: ['id', 'url', 'events', 'enabled', 'created_at'],
+        labels: { id: 'ID', url: 'URL', events: 'Events', enabled: 'Enabled', created_at: 'Created' },
+      });
+      if (created.secret) printSecret(created.secret);
+    });
+
+  // ── webhook rotate ──────────────────────────────────────────────────────────
+
+  webhook
+    .command('rotate')
+    .description('Rotate a webhook\'s signing secret')
+    .argument('<id>', 'webhook ID')
+    .action(async (id) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const data = await client.post(resolveEndpoint('webhooks.rotate', { orgId, id }).path, {
+        service: resolveEndpoint('webhooks.rotate', { orgId, id }).service,
+      });
+      printSuccess(`Webhook ${id} secret rotated.`);
+      if (data.secret) printSecret(data.secret);
+    });
+
+  // ── webhook delete ──────────────────────────────────────────────────────────
+
+  webhook
+    .command('delete')
+    .description('Delete an org webhook subscription')
+    .argument('<id>', 'webhook ID')
+    .option('--force', 'skip confirmation')
+    .action(async (id, 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: `Delete webhook ${id}? This cannot be undone.`,
+          default: false,
+        }]);
+        if (!ans.confirm) {
+          printInfo('Cancelled.');
+          return;
+        }
+      }
+
+      await client.delete(resolveEndpoint('webhooks.delete', { orgId, id }).path, {
+        service: resolveEndpoint('webhooks.delete', { orgId, id }).service,
+      });
+      printSuccess('Webhook deleted.');
+    });
+}

package/lib/commands/welcome.js

@@ -0,0 +1,14 @@
+/**
+ * quox welcome: print the greeting from the first screen again. Read only: no server, no login, and it never
+ * touches the first-run marker or any config.
+ */
+export function registerWelcomeCommand(program) {
+  program
+    .command('welcome')
+    .description('Show the welcome screen again (read only; changes no setup or config)')
+    .action(async () => {
+      const { INTRO_HEAD, INTRO_LINES } = await import('../quoxon/render.js');
+      const { packageVersion } = await import('../quoxon/welcome.js');
+      console.log([INTRO_HEAD, ...INTRO_LINES, `${packageVersion()} · ${process.cwd()}`].join('\n'));
+    });
+}