quoxcli 0.2.0 → 0.4.0

package/lib/core/hyperion.js

@@ -0,0 +1,102 @@
+/**
+ * HYPERION activity: the shared reader and plain-text renderers behind `quox hyperion`,
+ * `quox hyperion deck` and the QUOXON /hyperion command. Pure functions over the
+ * GET /api/v1/proxmox/activity payload; no colour (callers paint), no grey, labels not bare values.
+ */
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function fetchActivity(client) {
+  const ep = resolveEndpoint('v1.proxmox.activity');
+  return client.get(ep.path, { service: ep.service });
+}
+
+const ms = (v) => {
+  if (v == null || v === '') return null;
+  const n = typeof v === 'number' ? v : Date.parse(v);
+  return Number.isFinite(n) ? n : null;
+};
+
+function span(delta) {
+  const s = Math.max(0, Math.floor(delta / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+/** Expiry wins ("expires in 3h" / "expired 1h ago"), else how long it has been held, else "-". */
+export function whenText(held, now = Date.now()) {
+  const exp = ms(held && held.expires);
+  if (exp != null) return exp >= now ? `expires in ${span(exp - now)}` : `expired ${span(now - exp)} ago`;
+  const since = ms(held && held.since);
+  if (since != null) return `held ${span(now - since)}`;
+  return '-';
+}
+
+export function holderText(held) {
+  const h = held || {};
+  if (h.source === 'pool') return h.lessee ? `${h.lessee} (pool)` : 'free (pool)';
+  if (h.source === 'lane') return `${h.lessee || 'unknown'} (lane)`;
+  return 'nobody recorded';
+}
+
+const isHeld = (v) => Boolean(v.held_by && v.held_by.lessee);
+const pct = (x) => (typeof x === 'number' ? `${Math.round(x * 100)}%` : '?');
+const gb = (b) => (typeof b === 'number' ? (b / 1e9).toFixed(1) : '?');
+const clipTo = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+
+/** Full one-shot view: VM table, node load, pool counts, last 5 ops. */
+export function statusLines(data, { now = Date.now() } = {}) {
+  const d = data || {};
+  const out = [];
+  const vms = d.vms || [];
+  if (!vms.length) out.push('No VMs are held or pooled right now.');
+  else {
+    const rows = vms.map((v) => [String(v.vmid), v.name || '', v.node || '', v.status || '', holderText(v.held_by), (v.held_by && v.held_by.purpose) || '-', whenText(v.held_by, now)]);
+    const head = ['VMID', 'NAME', 'NODE', 'STATUS', 'HELD BY', 'PURPOSE', 'AGE / EXPIRY'];
+    const w = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+    const fmt = (r) => r.map((c, i) => c.padEnd(w[i])).join('  ').trimEnd();
+    out.push(fmt(head), ...rows.map(fmt));
+  }
+  if (d.vms_truncated) out.push(`⚠ ${d.vms_truncated} more tagged VMs not shown`);
+  if (d.vm_config_errors) out.push(`⚠ ${d.vm_config_errors} VM description(s) could not be read, holder taken from tags`);
+  out.push('');
+  out.push('Node load');
+  if (d.nodes_error) out.push(`  Node load unavailable: ${d.nodes_error}`);
+  else if (!(d.nodes || []).length) out.push('  no nodes reported');
+  else for (const n of d.nodes) out.push(`  ${String(n.node).padEnd(10)} ${String(n.status).padEnd(8)} cpu ${pct(n.cpu)}   mem ${gb(n.mem_used)}/${gb(n.mem_total)} GB`);
+  out.push('');
+  if (d.pool) {
+    const counts = Object.entries(d.pool.counts || {}).map(([k, v]) => `${k} ${v}`).join(', ') || 'no VMs';
+    out.push(`Pool: ${d.pool.enabled ? 'enabled' : 'disabled'}, ${counts}${d.pool.paused ? ' (paused, waiting for approval)' : ''}`);
+  } else out.push(`Pool unavailable: ${d.pool_error || 'unknown'}`);
+  out.push('');
+  if (d.ops_error) out.push(`Recent ops unavailable: ${d.ops_error}`);
+  else {
+    const ops = (d.recent_ops || []).slice(0, 5);
+    out.push(`Recent ops (${ops.length})`);
+    if (!ops.length) out.push('  none recorded');
+    for (const o of ops) out.push(`  ${o.ts}  ${o.intent}  vmid ${o.vmid ?? '-'}  by ${o.actor || '?'}  outcome ${o.outcome ?? '-'}`);
+  }
+  return out;
+}
+
+/** Compact list for the TUI: a header, then one line per held VM. */
+export function heldLines(data, { now = Date.now(), width = 100 } = {}) {
+  const held = ((data && data.vms) || []).filter(isHeld);
+  if (!held.length) return ['No VMs are held right now.'];
+  const lines = [`${held.length} held`];
+  for (const v of held) {
+    const purpose = v.held_by.purpose ? `, ${v.held_by.purpose}` : '';
+    lines.push(clipTo(`${v.vmid} ${v.name || ''} on ${v.node || '?'} ${v.status || ''}: held by ${holderText(v.held_by)}${purpose}, ${whenText(v.held_by, now)}`, width));
+  }
+  return lines;
+}
+
+/** Result text for the QuoxGlyph header line. */
+export function summaryText(data) {
+  const vms = (data && data.vms) || [];
+  return `${vms.length} VMs · ${vms.filter(isHeld).length} held`;
+}

package/lib/core/inboxResolution.js

@@ -0,0 +1,65 @@
+/**
+ * CLI-ERRORS (owner 2026-10-17): "Already approved by <who> at <time>; nothing to do".
+ * Mirrors services/auth/lib/alreadyResolved.js so an older server (no `resolution` in its
+ * 400 body) still gets the same one-line answer from the card itself.
+ */
+import { QuoxUserError } from './errors.js';
+
+const APPROVE = new Set(['approve', 'approved', 'accept', 'accepted', 'grant', 'granted']);
+const DENY = new Set(['deny', 'denied', 'dismissed', 'reject', 'rejected']);
+
+function normalise(action) {
+  const a = String(action || '').trim().toLowerCase();
+  if (APPROVE.has(a)) return 'approved';
+  if (DENY.has(a)) return 'rejected';
+  if (a === 'answer') return 'answered';
+  if (a === 'defer') return 'deferred';
+  if (a === 'request_changes') return 'changes requested';
+  return a ? 'resolved' : null;
+}
+
+/** A y/n decision answered "y" reads as approved, "n" as rejected; another option as answered "<key>". */
+function outcomeOf(prior) {
+  const opt = prior && typeof prior.option === 'string' ? prior.option : null;
+  if (opt === 'y') return 'approved';
+  if (opt === 'n') return 'rejected';
+  const n = normalise(prior?.action);
+  return n === 'answered' && opt ? `answered "${opt}"` : n;
+}
+
+function toIso(ts) {
+  if (!ts) return null;
+  const s = String(ts);
+  const d = new Date(/[zZ]|[+-]\d\d:?\d\d$/.test(s) ? s : `${s.replace(' ', 'T')}Z`);
+  return Number.isNaN(d.getTime()) ? null : d.toISOString();
+}
+
+export function humanUtc(iso) {
+  return iso ? `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC` : 'an unknown time';
+}
+
+export function resolutionFromItem(item, requestedAction) {
+  if (!item || !item.id) return null;
+  const response = item.response || null;
+  const outcome = item.status === 'expired' ? 'expired' : item.status === 'cancelled' ? 'cancelled' : (outcomeOf(response) || 'resolved');
+  const name = item.resolved_by_name || response?.responded_by_name || null;
+  const at = toIso(item.resolved_at) || toIso(response?.responded_at) || null;
+  const requested = String(requestedAction || '').trim().toLowerCase() || null;
+  const matches = Boolean(requested) && outcome !== 'expired' && outcome !== 'cancelled' && normalise(requested) === outcome;
+  let message;
+  if (outcome === 'expired') message = `This approval expired at ${humanUtc(at)}; nothing was approved. Ask for it again.`;
+  else if (outcome === 'cancelled') message = `This item was cancelled at ${humanUtc(at)}${name ? ` by ${name}` : ''}; there is nothing to respond to.`;
+  else {
+    const head = `Already ${outcome}${name ? ` by ${name}` : ''} at ${humanUtc(at)}`;
+    message = matches || !requested ? `${head}; nothing to do.` : `${head}; your ${requested} was not applied.`;
+  }
+  return { item_id: item.id, status: item.status, outcome, resolved_by: item.resolved_by || null, resolved_by_name: name, resolved_at: at, requested, matches, message };
+}
+
+/** A respond whose outcome does NOT match what is already recorded: exit 6 (conflict). */
+export function alreadyResolvedError(resolution, cause) {
+  return new QuoxUserError(resolution.message, {
+    next: `\`quox inbox show ${resolution.item_id}\` shows the decision.`,
+    exitCode: 6, code: 'already_resolved', status: cause?.status, body: cause?.body,
+  });
+}

package/lib/core/lazyCommands.js

@@ -95,7 +95,10 @@ async function fullLoad(program, ctx, registrars, baseUrl, key) {
  * @param {string} baseUrl import.meta.url of the caller
  */
 export async function registerCommandGroups(program, ctx, registrars, argv, baseUrl) {
-  const commandsDir = join(dirname(fileURLToPath(baseUrl)), '..', 'lib', 'commands');
+  // The directory the registrar modules live in, resolved from the registrar paths
+  // themselves (the list moved to lib/core/commandRegistrars.js, so baseUrl is no
+  // longer bin/quox.js and a fixed '../lib/commands' would miss).
+  const commandsDir = registrars.length ? dirname(fileURLToPath(new URL(registrars[0][0], baseUrl))) : join(dirname(fileURLToPath(baseUrl)), '..', 'lib', 'commands');
   const key = process.env.QUOX_CLI_EAGER === '1' ? null : mapKey(registrars, commandsDir);
   const token = commandToken(argv);
   if (key && token && !FULL_LOAD_TOKENS.has(token)) {

package/lib/core/liveSessionsReport.js

@@ -10,7 +10,7 @@ import { spawnSync } from 'node:child_process';
 
 export const TMUX_FORMAT = '#{session_name}\t#{session_created}\t#{session_attached}\t#{pane_current_command}\t#{pane_pid}\t#{session_activity}';
 
-const AGENT_PROGRAMS = new Set(['claude', 'codex', 'gemini']);
+const AGENT_PROGRAMS = new Set(['claude', 'codex']);
 
 /** Parse `tmux list-panes -a -F TMUX_FORMAT` output; one entry per session (first pane wins). */
 export function parseTmuxPanes(out) {

package/lib/core/loopGlyph.js

@@ -0,0 +1,97 @@
+/**
+ * QLOOP-LIVE: render loop events as QuoxGlyph lines (`quox loop watch`).
+ *   ∞ QLOOP │ turn 3/10 │ wrote report.md · 41s ✔
+ *
+ * Pure: event in, string out, so the watch loop, the tests and anything else that wants the same
+ * voice (the TUI card's observe lines) share one renderer. The ∞ icon is claimed here by extending
+ * the exported registry at import time (the vendored quoxglyph.js is source-locked to the package).
+ */
+
+import { ICONS, STATUS, brandName } from './quoxglyph.js';
+
+ICONS.qloop = '∞ QLOOP';
+
+const R = '\x1b[0m', DIM = '\x1b[2m';
+const colourOn = () => brandName('x y') !== 'x y';
+
+function oneLine(s, n) {
+  const t = String(s == null ? '' : s).replace(/\s+/g, ' ').trim();
+  return [...t].length > n ? `${[...t].slice(0, n - 1).join('')}…` : t;
+}
+
+/** "41s", "1m12s", "2h03m" */
+export function elapsedLabel(ms) {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m${String(s % 60).padStart(2, '0')}s`;
+  return `${Math.floor(s / 3600)}h${String(Math.floor((s % 3600) / 60)).padStart(2, '0')}m`;
+}
+
+/** One QLOOP line: icon+name, verb, optional result, optional status glyph. Result is NOT budget-truncated here (callers cap it). */
+export function loopLine(verb, result, status) {
+  const col = colourOn();
+  const sep = col ? `${DIM}│${R}` : '│';
+  let out = `${brandName(ICONS.qloop)} ${sep} ${verb}`;
+  if (result) out += ` ${sep} ${result}`;
+  const s = status && STATUS[status];
+  if (s) out += ' ' + (col && s.rgb ? `\x1b[38;2;${s.rgb[0]};${s.rgb[1]};${s.rgb[2]}m${s.glyph}${R}` : s.glyph);
+  return out;
+}
+
+const OBSERVE_STATUS = { interval: 'busy', milestone: 'ok', error: 'fail', approval: 'warn', stall: 'warn' };
+
+/**
+ * @param {object} e   a loop event (design section 1)
+ * @param {object} ctx { title, maxTurns, startedMs, spool }
+ * @returns {string[]} lines to print (may be empty)
+ */
+export function renderEvent(e, ctx = {}) {
+  const max = ctx.maxTurns ? `/${ctx.maxTurns}` : '';
+  const since = ctx.startedMs ? ` · ${elapsedLabel(Date.parse(e.at) - ctx.startedMs)}` : '';
+  switch (e.type) {
+    case 'loop.started': {
+      const scope = Array.isArray(e.scope) && e.scope.length ? e.scope.join(',') : 'none';
+      return [loopLine('started', `host ${e.host} · ${e.backend} · scope ${oneLine(scope, 60)}${e.max_turns ? ` · ${e.max_turns} turns max` : ''}`, 'busy')];
+    }
+    case 'loop.turn.started':
+      return ctx.spool ? [loopLine(`turn ${e.turn}${max}`, 'working', 'busy')] : [];
+    case 'loop.turn.output':
+      return ctx.spool ? String(e.chunk).replace(/\n+$/, '').split('\n').map((l) => `  │ ${l}`) : [];
+    case 'loop.turn.tool': {
+      if (e.note) return [loopLine(`turn ${e.turn}`, `${e.tool} no result (${oneLine(e.note, 60)})${since}`, 'warn')];
+      if (e.denied) return [loopLine(`turn ${e.turn}`, `${e.tool} denied: ${oneLine(e.denied, 60)}${since}`, 'warn')];
+      return [loopLine(`turn ${e.turn}`, `${e.tool} ${e.ok ? 'ok' : 'failed'}${e.ms ? ` ${e.ms}ms` : ''}${since}`, e.ok ? 'ok' : 'fail')];
+    }
+    case 'loop.turn.completed':
+      return [loopLine(`turn ${e.turn}${max}`, `${oneLine(e.summary, 70)}${since}`, 'ok')];
+    case 'loop.observe':
+      if (e.kind === 'milestone') return [loopLine('milestone', oneLine(e.text, 100), 'ok')];
+      return [loopLine(e.kind === 'interval' ? 'status' : e.kind, oneLine(e.text, 110), OBSERVE_STATUS[e.kind] || 'busy')];
+    case 'loop.ward':
+      if (e.status === 'pending') return []; // announced, not yet witnessed: nothing to say yet
+      return [loopLine('receipt', `${String(e.envelope_id).slice(0, 12)} ${e.status}`, e.status === 'WITNESSED' ? 'ok' : 'warn')];
+    case 'loop.approval':
+      return [loopLine('approval', `${oneLine(e.what, 90)} (${e.checkpoint_id})`, 'warn')];
+    case 'loop.finished': {
+      // Only a clean completion is a tick. completed_with_errors and a halt / interruption warn; a failure fails. The reason is
+      // whole (a wrapped line beats a cut sentence) and loses the raw component prefix the spawner puts first.
+      const status = e.state === 'completed' ? 'ok' : e.state === 'failed' ? 'fail' : 'warn';
+      const wit = e.receipts != null ? `, ${e.witnessed}/${e.receipts} witnessed` : '';
+      const reason = String(e.reason || '').replace(/\s+/g, ' ').trim().replace(/^[a-z][A-Za-z0-9]*[A-Z][A-Za-z0-9]*:\s+/, '');
+      const why = e.state !== 'completed' && reason ? `: ${reason}` : '';
+      return [loopLine(oneLine(ctx.title || 'loop', 48), `${e.state}, ${e.turns} turn${e.turns === 1 ? '' : 's'}${wit}${why}`, status)];
+    }
+    default:
+      return [];
+  }
+}
+
+/** Exit code for a finished loop: 0 completed (also with errors), 1 failed, 2 halted by a human, 3 interrupted. */
+export function exitCodeFor(state) {
+  switch (state) {
+    case 'completed': case 'completed_with_errors': return 0;
+    case 'halted': return 2;
+    case 'interrupted': return 3;
+    default: return 1;
+  }
+}