quoxcli 0.2.0 → 0.3.1

package/lib/commands/done.js

@@ -55,6 +55,7 @@ import path from 'node:path';
 import {
   resolveFetchDestination,
   fetchEngine,
+  inspectInstall,
   OPT_GAUGE_DIR,
   userLocalGaugeDir,
   legacyGaugeDir,
@@ -88,19 +89,21 @@ export function resolveEnginePath({ env = process.env, existsSync = fs.existsSyn
 
 const ENGINE = resolveEnginePath();
 
-function runEngine(args) {
-  if (!fs.existsSync(ENGINE)) {
-    process.stderr.write(
-      `DoneEngine not found at ${ENGINE}\n` +
-      'Self-heal: `quox done fetch` pulls the engine bundle straight from ' +
-      'the collector, no human in the loop. Otherwise `quox dev enable` ' +
-      'delivers it to /opt/quoxgauge as part of full dev-server ' +
-      'provisioning. Or set QUOX_DONEENGINE_PATH to a checkout.\n',
-    );
+function engineMissingMessage(engine) {
+  return `DoneEngine not found at ${engine}\n`
+    + 'Self-heal: `quox done fetch` pulls the engine bundle straight from '
+    + 'the collector, no human in the loop. Otherwise `quox dev enable` '
+    + 'delivers it to /opt/quoxgauge as part of full dev-server '
+    + 'provisioning. Or set QUOX_DONEENGINE_PATH to a checkout.\n';
+}
+
+function runEngine(args, engine = ENGINE) {
+  if (!fs.existsSync(engine)) {
+    process.stderr.write(engineMissingMessage(engine));
     // 2, not 1: a missing engine is "cannot tell", not "refused".
     return 2;
   }
-  const r = spawnSync(process.execPath, [ENGINE, ...args], { stdio: 'inherit' });
+  const r = spawnSync(process.execPath, [engine, ...args], { stdio: 'inherit' });
   if (r.error) {
     process.stderr.write(`DoneEngine failed to run: ${r.error.message}\n`);
     return 2;
@@ -108,6 +111,23 @@ function runEngine(args) {
   return r.status ?? 2;
 }
 
+/**
+ * VISIBILITY GATE (#988 follow-on). Public installs do not ship DoneEngine
+ * (its bundle is built from the private quox-gauge repo and delivered to dev
+ * servers by `quox dev enable`), so listing `quox done` in their help
+ * advertises a command that can only fail. It is listed only when an engine
+ * is installed locally, decided from the filesystem alone with the same
+ * resolution the runner uses: building help never makes a network call.
+ * QUOX_HELP_INCLUDE_GATED=1 lists it regardless; the generators that scrape
+ * `--help` into the command trees set it so those trees do not depend on
+ * which host ran them.
+ */
+export function isDoneEngineInstalled({ env = process.env, home = os.homedir(), fsOps } = {}) {
+  const ops = fsOps || { existsSync: fs.existsSync, readdirSync: fs.readdirSync };
+  const engine = resolveEnginePath({ env, existsSync: ops.existsSync, home });
+  return inspectInstall(path.dirname(engine), ops).healthy;
+}
+
 function defaultExecFn(cmd, args) {
   return spawnSync(cmd, args, { encoding: 'utf8' });
 }
@@ -140,8 +160,56 @@ function defaultFsOps() {
 }
 
 export function registerDoneCommands(program, ctx = {}) {
+  const env = ctx.env || process.env;
+  const home = ctx.home || os.homedir();
+  // Tests inject fsOps/env/home; the real CLI keeps the import-time ENGINE.
+  const injected = !!(ctx.fsOps || ctx.env || ctx.home);
+  const currentEngine = () => (injected
+    ? resolveEnginePath({ env, existsSync: (ctx.fsOps || fs).existsSync, home })
+    : ENGINE);
+  const visible = env.QUOX_HELP_INCLUDE_GATED === '1'
+    || isDoneEngineInstalled({ env, home, fsOps: ctx.fsOps });
+
+  const fetchDeps = () => ({
+    execFn: ctx.execFn || defaultExecFn,
+    isWritable: ctx.isWritable || defaultIsWritable,
+    fsOps: ctx.fsOps || defaultFsOps(),
+  });
+
+  /**
+   * Resolve a runnable engine for a subcommand. Present: use it, no network.
+   * Absent: try the existing fetch path once. A collector 404
+   * (DONEENGINE_NOT_SHIPPED) means this is a public install: refuse with that
+   * message and exit 2, having changed nothing. A bundle that IS available
+   * (a dev collector) installs and the freshly fetched engine runs.
+   */
+  async function ensureEngine() {
+    const engine = currentEngine();
+    const exists = (ctx.fsOps || fs).existsSync(engine);
+    if (exists || !ctx.client || env.QUOX_DONEENGINE_PATH) return { engine };
+    const { execFn, isWritable, fsOps } = fetchDeps();
+    const { dest, needsSudo } = resolveFetchDestination({ env, isWritable, execFn });
+    try {
+      await fetchEngine({ dest, needsSudo, force: false, client: ctx.client, execFn, fsOps });
+      return { engine: path.join(dest, 'gauge.mjs') };
+    } catch (err) {
+      if (err.code === 'DONEENGINE_NOT_SHIPPED') {
+        process.stderr.write(`quox done: ${err.message}\n`);
+        return { code: 2 };
+      }
+      process.stderr.write(`quox done: engine fetch failed: ${err.message}\n`);
+      return { engine };
+    }
+  }
+
+  async function runGuarded(args) {
+    const r = await ensureEngine();
+    if (r.code !== undefined) return r.code;
+    return runEngine(args, r.engine);
+  }
+
   const done = program
-    .command('done')
+    .command('done', { hidden: !visible })
     .description('Quox DoneEngine: is this actually done, and what is the evidence?');
 
   done
@@ -150,7 +218,7 @@ export function registerDoneCommands(program, ctx = {}) {
     .option('--pack <id>', 'rule pack to judge against', 'launch-spine')
     .option('--json', 'structured verdict for agents')
     .option('--root <path>', 'judge <subject> in this repo, reading its own STATUS map with the selected pack (e.g. a plugin with --pack plugin)')
-    .action((subject, options) => {
+    .action(async (subject, options) => {
       const args = ['--can-ship', subject || 'all', '--pack', options.pack];
       if (options.root) {
         if (!subject) {
@@ -161,17 +229,17 @@ export function registerDoneCommands(program, ctx = {}) {
         args.push('--subject', subject, '--root', path.resolve(options.root));
       }
       if (options.json) args.push('--json');
-      process.exitCode = runEngine(args);
+      process.exitCode = await runGuarded(args);
     });
 
   done
     .command('checklist [pack]')
     .description('The builder checklist GENERATED from a pack (every gate the engine judges); --check verifies a doc that embeds it')
     .option('--check <file>', 'exit 1 if the checklist block in this file has drifted from the pack')
-    .action((pack, options) => {
+    .action(async (pack, options) => {
       const args = ['--checklist', pack || 'plugin'];
       if (options.check) args.push('--check', path.resolve(options.check));
-      process.exitCode = runEngine(args);
+      process.exitCode = await runGuarded(args);
     });
 
   done
@@ -180,12 +248,12 @@ export function registerDoneCommands(program, ctx = {}) {
     .option('--json', 'machine-readable, includes raw deploy state')
     .option('--dod', 'per-surface gates, split by evidence class')
     .option('--no-deploy', 'skip docker/git; Deployed Ready becomes unknown, which is not a pass')
-    .action((options) => {
+    .action(async (options) => {
       const args = [];
       if (options.json) args.push('--json');
       if (options.dod) args.push('--dod');
       if (options.deploy === false) args.push('--no-deploy');
-      process.exitCode = runEngine(args);
+      process.exitCode = await runGuarded(args);
     });
 
   done
@@ -193,25 +261,27 @@ export function registerDoneCommands(program, ctx = {}) {
     .description('One rule pack against its subjects: BOTH finish lines, build and deployed')
     .option('--snapshot', 'append this reading to the snapshot history')
     .option('--org <id>', 'measure FOR this org: plan evidence reads as it, the snapshot is stamped with it (default: the pack\'s own org field)')
-    .action((pack, options) => {
+    .action(async (pack, options) => {
       const args = pack ? ['--pack', pack] : ['--launch'];
       if (options.snapshot) args.push('--snapshot');
       if (options.org) args.push('--org', options.org);
-      process.exitCode = runEngine(args);
+      process.exitCode = await runGuarded(args);
     });
 
   done
     .command('history [pack]')
     .description('Movement between snapshots, regressions listed first')
-    .action((pack) => {
-      process.exitCode = runEngine(pack ? ['--history', '--pack', pack] : ['--history']);
+    .action(async (pack) => {
+      process.exitCode = await runGuarded(pack ? ['--history', '--pack', pack] : ['--history']);
     });
 
   done
     .command('packs')
     .description('List available rule packs')
-    .action(() => {
-      const dir = path.join(path.dirname(ENGINE), 'packs');
+    .action(async () => {
+      const r = await ensureEngine();
+      if (r.code !== undefined) { process.exitCode = r.code; return; }
+      const dir = path.join(path.dirname(r.engine), 'packs');
       if (!fs.existsSync(dir)) {
         process.stderr.write(
           `No packs directory at ${dir}\n` +
@@ -246,13 +316,11 @@ export function registerDoneCommands(program, ctx = {}) {
         process.exitCode = 2;
         return;
       }
-      const execFn = ctx.execFn || defaultExecFn;
-      const isWritable = ctx.isWritable || defaultIsWritable;
-      const fsOps = ctx.fsOps || defaultFsOps();
+      const { execFn, isWritable, fsOps } = fetchDeps();
 
       const { dest, reason, needsSudo } = resolveFetchDestination({
         destOption: options.dest,
-        env: process.env,
+        env,
         isWritable,
         execFn,
       });
@@ -267,7 +335,9 @@ export function registerDoneCommands(program, ctx = {}) {
         }
       } catch (err) {
         process.stderr.write(`quox done fetch failed: ${err.message}\n`);
-        process.exitCode = 1;
+        // A public install's 404 is "this install has no DoneEngine", not a
+        // transient failure: exit 2 like every other "cannot tell" here.
+        process.exitCode = err.code === 'DONEENGINE_NOT_SHIPPED' ? 2 : 1;
       }
     });
 

package/lib/commands/engagement.js

@@ -121,10 +121,13 @@ export function registerEngagementCommands(program, ctx) {
       const data = await client.post(ep.path, { service: ep.service, body });
       printSuccess(`Target "${value}" added to engagement ${id}.`);
       if (data.target.verification_token) {
+        // #1007: a url target is challenged on its hostname (dns_txt) or at its own origin (well_known_file)
+        const stored = data.target.value || value;
+        const url = data.target.type === 'url' ? (() => { try { return new URL(stored); } catch { return null; } })() : null;
         if (data.target.verification_method === 'dns_txt') {
-          console.log(`  Add a DNS TXT record on ${value}: quox-verify=${data.target.verification_token}`);
+          console.log(`  Add a DNS TXT record on ${url ? url.hostname : stored}: quox-verify=${data.target.verification_token}`);
         } else if (data.target.verification_method === 'well_known_file') {
-          console.log(`  Serve this content at https://${value}/.well-known/quox-verification: ${data.target.verification_token}`);
+          console.log(`  Serve this content at ${url ? url.origin : `https://${stored}`}/.well-known/quox-verification: ${data.target.verification_token}`);
         }
         console.log(`  Then run: quox engagement verify-target ${id} ${data.target.id}`);
       }
@@ -172,6 +175,7 @@ export function registerEngagementCommands(program, ctx) {
         console.log(JSON.stringify(data.output, null, 2));
       } else {
         console.log(`  Failed (allowed: ${data.allowed}): ${data.error}`);
+        process.exitCode = 1; // #1007: a refusal is not success, for scripts as much as people
       }
     });
 
@@ -185,6 +189,7 @@ export function registerEngagementCommands(program, ctx) {
       const data = await client.post(ep.path, { service: ep.service, body: { target: hostTarget, add: options.add === true } });
       if (!data.success) {
         console.log(`  Failed (allowed: ${data.allowed}): ${data.error}`);
+        process.exitCode = 1; // #1007: a refusal is not success, for scripts as much as people
         return;
       }
       const discovered = data.discovered || [];
@@ -234,6 +239,7 @@ export function registerEngagementCommands(program, ctx) {
         console.log(`  Poll: quox engagement job ${data.job_id}`);
       } else {
         console.log(`  Failed (allowed: ${data.allowed}): ${data.error}`);
+        process.exitCode = 1; // #1007: a refusal is not success, for scripts as much as people
       }
     });
 
@@ -372,11 +378,16 @@ export function registerEngagementCommands(program, ctx) {
       }
       const buf = Buffer.from(await res.arrayBuffer());
       const rootOutput = program.opts().output;
-      const outFile = options.output
-        || (rootOutput && !KNOWN_OUTPUT_FORMATS.has(rootOutput) ? rootOutput : null)
-        || `quox-security-${id}.pdf`;
+      // quox#919: the global --json reaches options.output as 'json' via
+      // mergeShadowedGlobals; an output-format name is never a file path.
+      const asPath = (v) => (v && !KNOWN_OUTPUT_FORMATS.has(v) ? v : null);
+      const outFile = asPath(options.output) || asPath(rootOutput) || `quox-security-${id}.pdf`;
       writeFileSync(outFile, buf);
-      printSuccess(`Report saved to ${outFile} (${buf.length} bytes).`);
+      if (rootOutput === 'json') {
+        console.log(JSON.stringify({ success: true, file: outFile, bytes: buf.length }));
+      } else {
+        printSuccess(`Report saved to ${outFile} (${buf.length} bytes).`);
+      }
     });
 
   async function raiseIssue(findingId) {

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