quoxcli 0.5.0 → 0.6.1

package/lib/commands/lens.js

@@ -0,0 +1,268 @@
+/**
+ * `quox lens`: QuoxLens, apply a declared-stance Lens to a target text.
+ * Collector routes under /api/v1/lens (services/collector/routes/quoxlens.js), behind
+ * requireServiceOrUserAuth + requirePluginEntitlement('quoxlens').
+ *
+ *   quox lens list                                   every Lens, its stance, measured lift, unproven flag
+ *   quox lens show <id>                              one Lens in full (blind spots, finding classes, body)
+ *   quox lens apply <lensId> --file <path|->         apply one Lens to text from a file or stdin (-)
+ *                       [--target-label <s>]         a human label for the target (artifact title)
+ *   quox lens panel --file <path|->                  the Critic panel: several Lenses, repeated runs, run consensus
+ *                       [--lenses a,b] [--runs N] [--min-agreement K] [--depth quick|standard|thorough]
+ *                       [--target-label <s>] [--allow-unproven]
+ *
+ * All honour --json / -o json. An error body is not data: a non-2xx (400 unknown lens,
+ * 402 LICENSE_REQUIRED, 404, 409, 422) is reported with its status and exits 1.
+ */
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const isJson = (program) => program.opts().output === 'json';
+const printJson = (d) => console.log(JSON.stringify(d, null, 2));
+
+async function readTarget(file, ctx) {
+  if (file === '-') {
+    const input = ctx.stdin || process.stdin;
+    let buf = '';
+    for await (const chunk of input) buf += chunk;
+    return buf;
+  }
+  return readFileSync(file, 'utf-8');
+}
+
+// Stable per text, so finding fingerprints (lens + artifact.id + class + location) stay
+// stable when the same target is re-checked.
+function artifactIdFor(text) {
+  return `cli-${createHash('sha256').update(text).digest('hex').slice(0, 16)}`;
+}
+
+function describeError(err) {
+  const body = err.body || {};
+  const parts = [`HTTP ${err.status || err.statusCode}`];
+  if (body.error && !String(err.message || '').includes(body.error)) parts.push(body.error);
+  if (err.message) parts.push(err.message);
+  const detail = body.detail || err.details;
+  if (detail && typeof detail === 'string' && !String(err.message || '').includes(detail)) parts.push(`(${detail})`);
+  if (body.plugin) parts.push(`[plugin: ${body.plugin}]`);
+  return parts.join(' ');
+}
+
+const PANEL_DEPTHS = ['quick', 'standard', 'thorough'];
+// One lens call can take up to 5 minutes server-side and a panel runs lenses x runs calls in sequence.
+const PANEL_CALL_WAIT_MS = 5.5 * 60 * 1000;
+const PANEL_WAIT_CAP_MS = 30 * 60 * 1000;
+
+function parseWholeNumber(value, flag, min, max) {
+  if (value === undefined) return { value: undefined };
+  const n = Number(value);
+  if (!/^\d+$/.test(String(value).trim()) || !Number.isInteger(n) || n < min || n > max) {
+    return { error: `${flag} must be a whole number from ${min} to ${max}, got "${value}"` };
+  }
+  return { value: n };
+}
+
+function formatUsage(verdict) {
+  const u = verdict && verdict.usage;
+  if (!u) return `not available (${(verdict && verdict.usage_reason) || 'no reason given'})`;
+  const parts = [`input ${u.input_tokens}`, `output ${u.output_tokens}`];
+  if (u.cache_creation_input_tokens) parts.push(`cache write ${u.cache_creation_input_tokens}`);
+  if (u.cache_read_input_tokens) parts.push(`cache read ${u.cache_read_input_tokens}`);
+  const calls = `${u.calls} model call${u.calls === 1 ? '' : 's'}`;
+  const price = typeof u.list_price_usd === 'number' ? `, list price $${u.list_price_usd.toFixed(4)}` : '';
+  return `${parts.join(', ')} tokens over ${calls}${price}`;
+}
+
+export function registerLensCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  // An error body is not data: a non-2xx is reported with its status and exits 1 (returns null).
+  async function guarded(request) {
+    if (auth && typeof auth.requireAuth === 'function') auth.requireAuth();
+    try {
+      return await request();
+    } catch (err) {
+      if (err && (err.status || err.statusCode)) {
+        console.error(`QuoxLens request failed: ${describeError(err)}`);
+        process.exitCode = 1;
+        return null;
+      }
+      throw err;
+    }
+  }
+
+  const lens = program
+    .command('lens')
+    .description('QuoxLens: apply a declared-stance Lens to a target and get evidence-quoted findings');
+
+  lens
+    .command('list')
+    .description('List every Lens with its stance, measured lift and unproven flag')
+    .action(async () => {
+      const ep = resolveEndpoint('lens.list');
+      const data = await guarded(() => client.get(ep.path, { service: ep.service }));
+      if (data === null) return;
+      const lenses = Array.isArray(data.lenses) ? data.lenses : [];
+      if (isJson(program)) { printJson(lenses); return; }
+      if (!lenses.length) { console.log('No lenses installed.'); return; }
+      for (const l of lenses) {
+        if (l.error) { console.log(`${l.id}  [${l.category || '-'}]  ERROR: ${l.error}`); continue; }
+        const proof = l.unproven ? 'unproven' : 'measured';
+        const ver = l.version ? ` v${l.version}` : '';
+        console.log(`${l.id}${ver}  [${l.category || '-'}]  ${proof}  ${l.name || ''}`);
+        if (l.description) console.log(`    ${l.description}`);
+      }
+      console.log(`\n${lenses.length} lens${lenses.length === 1 ? '' : 'es'}`);
+    });
+
+  lens
+    .command('show <id>')
+    .description('Show one Lens in full: blind spots, finding classes, prohibited, eval results, body')
+    .action(async (id) => {
+      const ep = resolveEndpoint('lens.get', { id });
+      const data = await guarded(() => client.get(ep.path, { service: ep.service }));
+      if (data === null) return;
+      if (isJson(program)) { printJson(data); return; }
+      const list = (a) => (Array.isArray(a) && a.length ? a.join(', ') : '-');
+      console.log(`${data.name || data.id} (${data.id})`);
+      if (data.description) console.log(data.description);
+      console.log(`version:         ${data.version || '-'}`);
+      console.log(`kind:            ${data.kind || '-'}`);
+      if (data.edition) console.log(`edition:         ${data.edition}`);
+      if (data.author) console.log(`author:          ${data.author}`);
+      console.log(`unproven:        ${data.unproven ? 'yes (no measured lift)' : 'no'}`);
+      console.log(`tags:            ${list(data.tags)}`);
+      console.log(`finding classes: ${list(data.finding_classes)}`);
+      console.log(`blind spots:     ${list(data.blind_spots)}`);
+      console.log(`prohibited:      ${list(data.prohibited)}`);
+      console.log(`eval results:    ${Array.isArray(data.results) ? data.results.length : 0}`);
+      if (data.body) console.log(`\n${data.body}`);
+    });
+
+  lens
+    .command('apply <lensId>')
+    .description('Apply one Lens to target text from a file, or stdin with --file -')
+    .requiredOption('--file <path>', 'read the target text from this file, or - for stdin')
+    .option('--target-label <label>', 'a human label for the target (sent as the artifact title)')
+    .action(async (lensId, options) => {
+      let text;
+      try {
+        text = await readTarget(options.file, ctx);
+      } catch (err) {
+        console.error(`Could not read target ${options.file === '-' ? 'from stdin' : `file ${options.file}`}: ${err.message}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (!text || !text.trim()) {
+        console.error('Not applied: the target text is empty. Nothing was sent.');
+        process.exitCode = 1;
+        return;
+      }
+      const artifact = { kind: 'text', id: artifactIdFor(text), content: text };
+      if (options.targetLabel) artifact.title = options.targetLabel;
+      const ep = resolveEndpoint('lens.apply');
+      const body = { lens_id: lensId, mode: 'single', artifact };
+      // A lens apply is one model call (up to 5 min on the server); the client default (30s) gave up on real runs.
+      const data = await guarded(() => client.post(ep.path, { service: ep.service, body, timeout: PANEL_CALL_WAIT_MS, retries: 0 }));
+      if (data === null) return;
+      if (isJson(program)) { printJson(data); return; }
+
+      const v = data.verdict || {};
+      const a = data.applied || {};
+      console.log(`lens:        ${a.lens_id || lensId}${a.version ? ` v${a.version}` : ''}${a.unproven ? '  (unproven: no measured lift)' : ''}`);
+      if (artifact.title) console.log(`target:      ${artifact.title}`);
+      console.log(`disposition: ${v.disposition || '-'}`);
+      console.log(`confidence:  ${v.confidence ?? '-'}`);
+      if (a.model) console.log(`model:       ${a.model}`);
+      if (v.summary) console.log(`\n${v.summary}`);
+      const findings = Array.isArray(data.findings) ? data.findings : [];
+      console.log(`\nfindings: ${findings.length}`);
+      for (const f of findings) {
+        console.log(`  [${f.severity || '-'}] ${f.class || '-'}: ${f.claim || ''}`);
+        for (const e of Array.isArray(f.evidence) ? f.evidence : []) {
+          if (e && e.quote) console.log(`      "${e.quote}"${e.at ? ` (${e.at})` : ''}`);
+        }
+      }
+      if (Array.isArray(a.blind_spots) && a.blind_spots.length) console.log(`\nblind spots: ${a.blind_spots.join(', ')}`);
+      if (data.evidence && data.evidence.corr) console.log(`evidence:    ${data.evidence.corr}`);
+    });
+
+  lens
+    .command('panel')
+    .description('The Critic panel: several Lenses over one target, repeated runs; keeps findings that recur across runs')
+    .requiredOption('--file <path>', 'read the target text from this file, or - for stdin')
+    .option('--lenses <ids>', 'comma-separated lens ids, 2 to 5 (server default: honesty-and-claims,enterprise-compliance-auditor)')
+    .option('--runs <n>', 'how many times to run the panel, 1 to 5 (server default 1)')
+    .option('--min-agreement <k>', 'runs a finding must appear in to be kept (server default: a majority of runs)')
+    .option('--depth <depth>', `depth profile: ${PANEL_DEPTHS.join(', ')} (server default standard)`)
+    .option('--target-label <label>', 'a human label for the target (sent as the artifact title)')
+    .option('--allow-unproven', 'run lenses with no measured lift anyway (the result says so)')
+    .action(async (options) => {
+      const runs = parseWholeNumber(options.runs, '--runs', 1, 5);
+      const minAgreement = parseWholeNumber(options.minAgreement, '--min-agreement', 1, 5);
+      const bad = runs.error || minAgreement.error
+        || (options.depth !== undefined && !PANEL_DEPTHS.includes(options.depth) ? `--depth must be one of ${PANEL_DEPTHS.join(', ')}, got "${options.depth}"` : null);
+      if (bad) {
+        console.error(`Not run: ${bad}. Nothing was sent.`);
+        process.exitCode = 1;
+        return;
+      }
+      let text;
+      try {
+        text = await readTarget(options.file, ctx);
+      } catch (err) {
+        console.error(`Could not read target ${options.file === '-' ? 'from stdin' : `file ${options.file}`}: ${err.message}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (!text || !text.trim()) {
+        console.error('Not run: the target text is empty. Nothing was sent.');
+        process.exitCode = 1;
+        return;
+      }
+      const artifact = { kind: 'text', id: artifactIdFor(text), content: text };
+      if (options.targetLabel) artifact.title = options.targetLabel;
+      const body = { artifact };
+      const lensIds = options.lenses ? options.lenses.split(',').map((s) => s.trim()).filter(Boolean) : null;
+      if (lensIds) body.lens_ids = lensIds;
+      if (runs.value !== undefined) body.runs = runs.value;
+      if (minAgreement.value !== undefined) body.min_agreement = minAgreement.value;
+      if (options.depth) body.depth = options.depth;
+      if (options.allowUnproven) body.allow_unproven = true;
+
+      const calls = (lensIds ? lensIds.length : 2) * (runs.value || 1);
+      const timeout = Math.min(calls * PANEL_CALL_WAIT_MS, PANEL_WAIT_CAP_MS);
+      const ep = resolveEndpoint('lens.panel');
+      // retries: 0, a panel is a paid model run; a retried POST would run it twice.
+      const data = await guarded(() => client.post(ep.path, { service: ep.service, body, timeout, retries: 0 }));
+      if (data === null) return;
+      if (isJson(program)) { printJson(data); return; }
+
+      const v = data.verdict || {};
+      const lensList = (Array.isArray(data.lenses) ? data.lenses : []).map((l) => `${l.id}${l.version ? ` v${l.version}` : ''}${l.unproven ? ' (unproven)' : ''}`);
+      console.log(`lenses:      ${lensList.join(', ') || '-'}`);
+      if (artifact.title) console.log(`target:      ${artifact.title}`);
+      console.log(`disposition: ${v.disposition || '-'}`);
+      console.log(`runs:        ${data.runs_completed ?? '-'} of ${data.runs_requested ?? '-'} completed, a finding needs ${data.min_agreement ?? '-'} to be kept${data.depth ? `, depth ${data.depth}` : ''}`);
+      if (data.partial) console.log(`PARTIAL:     stopped early (${data.stop_reason || 'unknown'}${data.stop_detail ? `: ${data.stop_detail}` : ''})`);
+      if (Array.isArray(data.unproven_lenses) && data.unproven_lenses.length) console.log(`unproven:    ${data.unproven_lenses.join(', ')} (no measured lift; run because --allow-unproven was given)`);
+      if (v.summary) console.log(`\n${v.summary}`);
+      const findings = Array.isArray(data.findings) ? data.findings : [];
+      console.log(`\nfindings: ${findings.length}`);
+      for (const f of findings) {
+        const agreement = f.agreement ? `${f.agreement.label || `${f.agreement.runs}/${f.agreement.of}`} runs` : '-';
+        const by = Array.isArray(f.lens_ids) && f.lens_ids.length ? `  [${f.lens_ids.join(', ')}]` : '';
+        console.log(`  [${f.severity || '-'}] ${f.class || '-'}: ${f.claim || ''}  (${agreement})${by}`);
+        for (const e of Array.isArray(f.evidence) ? f.evidence : []) {
+          if (e && e.quote) console.log(`      "${e.quote}"${e.at ? ` (${e.at})` : ''}`);
+        }
+      }
+      const below = Array.isArray(data.below_agreement) ? data.below_agreement : [];
+      if (below.length) {
+        console.log(`\nbelow agreement (not kept): ${below.length}`);
+        for (const f of below) console.log(`  ${f.class || '-'}: ${f.claim || ''}  (${f.agreement ? f.agreement.label : '-'} runs)`);
+      }
+      console.log(`\nusage:       ${formatUsage(v)}`);
+      if (data.evidence && data.evidence.corr) console.log(`evidence:    ${data.evidence.corr}`);
+    });
+}

package/lib/commands/lucid.js

@@ -9,12 +9,14 @@
  *   quox lucid teach <target> <field>=<value> | lessons | forget <id>
  *   quox lucid herald [set key=value... | test]   when LUCID speaks first, and what it has said
  *   quox lucid blind          sources live/silent/failing/never heard, and what doesn't add up
+ *   quox lucid goals ...      your goals and decisions, so LUCID ranks against them (see lucidGoals.js)
  */
 import { formatOutput, printSuccess } from '../core/output.js';
 import { line as glyphLine, printEvent } from '../core/quoxglyph.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { confirmDestructive } from '../core/confirm.js';
 import { resolveOrgId } from './helpers.js';
+import { registerLucidGoalsCommands, registerLucidInsightsCommands, registerLucidBriefCommand } from './lucidGoals.js';
 
 const SURFACE = 'cli';
 
@@ -505,6 +507,10 @@ export function registerLucidCommands(program, ctx) {
       if (st.length) console.log(`Stats: ${st.map(([k, v]) => `${k}=${Array.isArray(v) ? v.join(',') : v}`).join(' · ')}`);
     });
 
+  registerLucidGoalsCommands(lu, program, ctx);
+  registerLucidInsightsCommands(lu, program, ctx);
+  registerLucidBriefCommand(lu, program, ctx);
+
   // ---- herald: when LUCID reaches out on its own ----
   const LEVELS = { l1_inbox: 'filed in your Approvals inbox', l2_slot: 'nudged you in your slot', l3_call: 'called you', resolved: 'resolved' };
   const levelWords = (l) => LEVELS[l] || l || 'not yet reached out';