quoxcli 0.2.0 → 0.4.0

package/lib/commands/evidence.js

@@ -0,0 +1,154 @@
+/**
+ * Evidence commands (DEVFLEET EV-1): `quox evidence status` shows size, rows, time span, growth, archive and
+ * backup for the AEE, WARD and VOLT stores. Read-only; the collector route is instance admin only.
+ */
+
+import chalk from 'chalk';
+import { formatOutput } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import fs from 'node:fs';
+import { exportConversationBundle, newestConversationId } from '../evidence/bundleExport.js';
+import { verifyEvidenceBundle } from '../evidence/bundleVerify.js';
+
+const NA = 'n/a';
+
+// verify_state from auth, said once: 'verified', 'never verified', 'verify failed', 'verify n/a'.
+function verifyLabel(v) {
+  if (v === null || v === undefined || v === '') return 'verify n/a';
+  if (v === 'verified') return 'verified';
+  if (v === 'failed') return 'verify failed';
+  if (v === 'never_verified') return 'never verified';
+  return `verify ${String(v).replace(/_/g, ' ')}`;
+}
+
+function bytes(n) {
+  if (n === null || n === undefined) return NA;
+  if (n < 1024) return `${n} B`;
+  const units = ['KB', 'MB', 'GB', 'TB'];
+  let v = n; let i = -1;
+  do { v /= 1024; i++; } while (v >= 1024 && i < units.length - 1);
+  return `${v.toFixed(1)} ${units[i]}`;
+}
+
+const val = (v) => (v === null || v === undefined ? NA : String(v));
+const day = (iso) => (iso ? String(iso).slice(0, 10) : NA);
+
+function archiveCell(a) {
+  if (a === null || a === undefined) return NA;
+  if (typeof a === 'string') return a;
+  return `${a.anchors} anchors${a.newest_archived_at ? `, newest ${day(a.newest_archived_at)}` : ''}`;
+}
+
+function diskCell(d) {
+  if (!d) return NA;
+  return `${bytes(d.free_bytes)} free of ${bytes(d.total_bytes)} (${d.mount})`;
+}
+
+export function registerEvidenceCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const evidence = program
+    .command('evidence')
+    .description('Evidence stores: AEE, WARD, VOLT');
+
+  evidence
+    .command('status')
+    .description('Evidence stores (AEE, WARD, VOLT): size, rows, time span, growth, archive and backup, read-only')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('evidence.status');
+      const data = await client.get(ep.path, { service: ep.service });
+      if (!data || !Array.isArray(data.stores)) {
+        throw new Error(`Unexpected evidence status response${data && data.error ? `: ${data.error}` : ''}`);
+      }
+      const format = program.opts().output;
+      if (format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+
+      const rows = data.stores.map((s) => ({
+        store: s.name,
+        size: bytes(s.bytes),
+        wal: bytes(s.wal_bytes),
+        rows: val(s.rows),
+        oldest: day(s.oldest),
+        newest: day(s.newest),
+        last7d: s.per_day && s.per_day.last_7d ? `${s.per_day.last_7d.per_day}/day` : NA,
+        archive: archiveCell(s.archive),
+        disk: diskCell(s.disk),
+      }));
+      formatOutput({
+        columns: ['store', 'size', 'wal', 'rows', 'oldest', 'newest', 'last7d', 'archive', 'disk'],
+        headers: ['Store', 'Size', 'WAL', 'Rows', 'Oldest', 'Newest', 'Last 7d', 'Archive', 'Disk'],
+        rows,
+      }, { format, full: true });
+
+      const b = data.backup || {};
+      if (b.last) {
+        const l = b.last;
+        const when = l.ts ? `${String(l.ts).slice(0, 10)} ${String(l.ts).slice(11, 16)} UTC` : NA;
+        const parts = [
+          b.age_hours === null || b.age_hours === undefined ? 'age n/a' : `${b.age_hours} h ago`,
+          l.count === null || l.count === undefined ? 'count n/a' : `${l.count} backups`,
+          (b.scope && b.scope.ts) || 'all orgs',
+        ];
+        const line = `Last backup ${when} (${parts.join(', ')})${b.stale ? ' STALE' : ''}`;
+        console.log(b.stale ? chalk.yellow(line) : line);
+        // The newest backup can belong to any org; health and verify state are the caller's org only.
+        console.log(`Backup health (${(b.scope && b.scope.health) || 'your org'}): ${val(l.status)}, ${verifyLabel(l.verified)}`);
+        if (l.last_failed) console.log(`  last failure: ${val(l.last_failed.error)} (${l.last_failed.at ? String(l.last_failed.at).slice(0, 16).replace('T', ' ') + ' UTC' : NA})`);
+        if (b.verify_error) console.log(`  ${b.verify_error}`);
+      } else {
+        console.log(`Backup: ${NA}`);
+      }
+
+      const errors = [];
+      for (const s of data.stores) for (const e of s.errors || []) errors.push(`${s.name}: ${e}`);
+      if (b.error) errors.push(`backup: ${b.error}`);
+      if (errors.length) {
+        console.log(chalk.yellow('Errors'));
+        for (const e of errors) console.log(`  ${e}`);
+      }
+    });
+  evidence
+    .command('bundle')
+    .description('Export a signed, offline-verifiable evidence bundle (zip) of every AEE envelope, WARD receipt and VOLT run for one conversation')
+    .argument('[conversation]', 'conversation id (the corr); default: your newest chat conversation')
+    .option('--out <file.zip>', 'where to write it (default ~/quox-evidence/<conversation>-<timestamp>.zip)')
+    .option('--json', 'print the result as JSON')
+    .action(async (conversation, options) => {
+      auth.requireAuth();
+      const corr = conversation || await newestConversationId(client);
+      if (!corr) throw new Error('No conversation to export: pass a conversation id (`quox conversation list`).');
+      const r = await exportConversationBundle({ client, corr, out: options.out });
+      const failed = r.verify.checks.filter((c) => !c.ok);
+      if (options.json || program.opts().output === 'json') {
+        console.log(JSON.stringify({ path: r.path, conversation: r.corr, bytes: r.bytes, envelopes: r.envelopes, receipts: r.receipts, verified: r.verify.ok, failed_checks: failed }, null, 2));
+      } else {
+        console.log(`${r.verify.ok ? chalk.green('Evidence bundle written') : chalk.red('Evidence bundle written but FAILED verification')}: ${r.path}`);
+        console.log(`  conversation ${r.corr} | ${r.envelopes} envelopes | ${r.receipts} WARD receipts | ${r.bytes} bytes`);
+        console.log(`  verify offline: quox evidence verify ${r.path}`);
+        for (const c of failed) console.log(chalk.red(`  FAILED ${c.name}: ${c.detail || ''}`));
+      }
+      if (!r.verify.ok) process.exitCode = 1;
+    });
+
+  evidence
+    .command('verify')
+    .description('Verify an evidence bundle zip offline: file hashes, envelope list hash, counts and the Ed25519 signature (no network)')
+    .argument('<file.zip>', 'a bundle from `quox evidence bundle`')
+    .option('--json', 'print the result as JSON')
+    .action(async (file, options) => {
+      let bytes;
+      try { bytes = fs.readFileSync(file); } catch (e) { throw new Error(`Cannot read ${file}: ${e.message}`); }
+      const v = await verifyEvidenceBundle(bytes);
+      if (options.json || program.opts().output === 'json') {
+        console.log(JSON.stringify({ file, verified: v.ok, checks: v.checks, counts: v.manifest?.counts || null, conversation: v.manifest?.corr || null, key_id: v.signature?.key_id || null }, null, 2));
+      } else {
+        for (const c of v.checks) console.log(`  ${c.ok ? chalk.green('PASS') : chalk.red('FAIL')} ${c.name}${c.detail ? ` (${c.detail})` : ''}`);
+        const m = v.manifest;
+        console.log(v.ok
+          ? chalk.green(`VERIFIED: ${m.counts.envelopes} envelopes, ${m.counts.ward_receipts} WARD receipts, conversation ${m.corr}, signed by ${v.signature.key_id}`)
+          : chalk.red('NOT VERIFIED: this bundle was altered or is not a Quox evidence bundle.'));
+      }
+      if (!v.ok) process.exitCode = 1;
+    });
+}

package/lib/commands/ext.js

@@ -0,0 +1,23 @@
+/**
+ * quox ext add|remove|list <pkg>
+ *
+ * The listing behind quoxon's extension host (cli/lib/quoxon/extensions.js, contract EXTENSIONS.md). It edits
+ * ~/.quox/extensions.json only; it does not install npm packages (npm i -g <pkg> does that). Nothing loads unless
+ * it is both installed and listed.
+ */
+import { readExtList, extAdd, extRemove, extListPath } from '../quoxon/extensions.js';
+
+export function registerExtCommands(program) {
+  const ext = program.command('ext').description('Optional quoxon extensions: list, add or remove one (npm i -g <pkg> installs it)');
+  const out = (r) => { console.log(r.text); if (!r.ok) process.exitCode = 1; };
+  ext.command('list').description('Extensions listed in ~/.quox/extensions.json')
+    .option('--json', 'print as JSON')
+    .action((opts) => {
+      const list = readExtList();
+      if (opts.json || program.opts().output === 'json') { console.log(JSON.stringify({ file: extListPath(), extensions: list }, null, 2)); return; }
+      if (!list.length) { console.log('No extensions listed. quox ext add <pkg>'); return; }
+      for (const x of list) console.log(`${x.name}  ${x.enabled ? 'on' : 'off'}`);
+    });
+  ext.command('add').description('List an extension so quoxon loads it once installed').argument('<pkg>').action((pkg) => out(extAdd(pkg)));
+  ext.command('remove').description('Stop listing an extension').argument('<pkg>').action((pkg) => out(extRemove(pkg)));
+}

package/lib/commands/fetchAllowlist.js

@@ -0,0 +1,71 @@
+/**
+ * `quox fetch allow` — the URL prefixes this org's agents may GET through the
+ * governed web_fetch_allowlisted tool (quox#1171). Default-deny: nothing is
+ * fetchable until an org admin adds a prefix. Every call goes through the
+ * collector; adding and removing need a human org admin (the server refuses
+ * agent tokens).
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+
+async function call(client, id, params = {}, body) {
+  const ep = resolveEndpoint(id, params);
+  const opts = { service: ep.service };
+  if (body) opts.body = body;
+  switch (ep.method) {
+    case 'POST': return client.post(ep.path, opts);
+    case 'DELETE': return client.delete(ep.path, opts);
+    default: return client.get(ep.path, opts);
+  }
+}
+
+export function registerFetchAllowlistCommands(program, ctx) {
+  const { client } = ctx;
+
+  const f = program
+    .command('fetch')
+    .description('Governed agent fetch: which URLs your agents may GET');
+
+  const al = f.command('allow')
+    .description('The URL prefixes this org allows agents to fetch (default-deny)');
+
+  al.command('list', { isDefault: true })
+    .description('Show the allowed URL prefixes for this org')
+    .action(async () => {
+      const d = await call(client, 'fetchAllowlist.list');
+      if (d.prefixes?.length) {
+        process.stdout.write('allowed prefixes:\n');
+        for (const e of d.prefixes) process.stdout.write(`  ${e.url_prefix}${e.note ? `  (${e.note})` : ''}\n`);
+      } else {
+        process.stdout.write('none allowed yet: agents cannot fetch anything. Add one with `quox fetch allow add <url-prefix>`\n');
+      }
+    });
+
+  al.command('add <url-prefix>')
+    .description('Allow agents to GET URLs under a prefix, e.g. https://status.example.com/api/')
+    .option('--note <text>', 'why it is allowed, shown alongside it later')
+    .action(async (urlPrefix, opts) => {
+      try {
+        const d = await call(client, 'fetchAllowlist.add', {}, { url_prefix: urlPrefix, note: opts.note });
+        process.stdout.write(`allowed ${d.entry.url_prefix}\n`);
+        process.stdout.write(`  ${d.prefixes.length} prefix(es) now allowed for this org\n`);
+      } catch (err) {
+        if (err?.status === 400 && err?.message) {
+          process.stderr.write(`Not added: ${err.message}\n`);
+          process.exitCode = 1;
+          return;
+        }
+        throw err;
+      }
+    });
+
+  al.command('remove <url-prefix>')
+    .description('Stop allowing a URL prefix')
+    .action(async (urlPrefix) => {
+      const d = await call(client, 'fetchAllowlist.remove', { prefix: urlPrefix });
+      if (d.removed) process.stdout.write(`removed ${urlPrefix}\n`);
+      else process.stdout.write(`nothing to remove: ${urlPrefix} was not allowed for this org\n`);
+    });
+}
+
+export default registerFetchAllowlistCommands;

package/lib/commands/file.js

@@ -2,7 +2,7 @@
  * File commands: upload, download, list, delete
  */
 
-import { createWriteStream } from 'node:fs';
+import { createWriteStream, readFileSync } from 'node:fs';
 import { basename } from 'node:path';
 import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
 import { resolveEndpoint } from '../api/endpoints.js';
@@ -125,4 +125,41 @@ export function registerFileCommands(program, ctx) {
       const data = await client.get(resolveEndpoint('files.stats').path, { service: resolveEndpoint('files.stats').service });
       formatDetail(data.stats || data, { format: program.opts().output, title: 'File Storage Stats' });
     });
+
+  // F01 A': legacy files with no proven owner are hidden from every org until a human instance admin assigns them.
+  file
+    .command('quarantine')
+    .description('List files with no proven owner org (instance admin only)')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('files.quarantine.list');
+      const data = await client.get(ep.path, { service: ep.service });
+      formatOutput({ columns: ['id', 'name', 'size'], headers: ['ID', 'Name', 'Size'], rows: data.files || [] }, { format: program.opts().output });
+    });
+
+  file
+    .command('assign')
+    .description('Assign a quarantined file to an org (instance admin only; witnessed): <fileId> --org <orgId>, or --from-report <dry-run.json>')
+    .argument('[fileId]', 'quarantined file id')
+    .option('--org <orgId>', 'org that owns the file')
+    .option('--from-report <path>', 'an owner-approved backfill dry-run report: assigns only rows with a derived owner')
+    .action(async (fileId, options) => {
+      auth.requireAuth();
+      let assignments;
+      if (options.fromReport) {
+        const report = JSON.parse(readFileSync(options.fromReport, 'utf8'));
+        assignments = (report.rows || []).filter((r) => r && r.id && r.orgId).map((r) => ({ file_id: r.id, org_id: r.orgId }));
+        if (!assignments.length) throw new Error('The report has no rows with a derived owner; nothing to assign.');
+      } else if (fileId) {
+        if (!options.org) throw new Error('Give the owning org: quox file assign <fileId> --org <orgId>');
+        assignments = [{ file_id: fileId, org_id: options.org }];
+      } else {
+        throw new Error('Give <fileId> --org <orgId>, or --from-report <dry-run.json>');
+      }
+      const ep = resolveEndpoint('files.quarantine.assign');
+      const data = await client.post(ep.path, { service: ep.service, body: { assignments } });
+      formatOutput({ columns: ['file_id', 'org_id', 'ok', 'error'], headers: ['File', 'Org', 'Assigned', 'Error'], rows: data.results || [] }, { format: program.opts().output });
+      const failed = (data.results || []).filter((r) => !r.ok).length;
+      if (failed) { process.exitCode = 1; } else { printSuccess(`Assigned ${assignments.length} file(s).`); }
+    });
 }