quoxcli 0.0.0-stage → 0.2.0

package/lib/core/doneEngineFetch.js

@@ -0,0 +1,219 @@
+/**
+ * `quox done fetch` engine (quox#456 follow-on).
+ *
+ * quox#456 pointed `quox done` at /opt/quoxgauge, which is delivered ONLY by
+ * `quox dev enable` (see cli/lib/commands/dev.js and
+ * services/collector/lib/devServerRefresh.js buildGaugeRefreshCommand).
+ * Enable is correctly human-gated (requireHumanAdmin), so a RESIDENT agent
+ * with a missing or stale engine had no self-service path and was stuck
+ * waiting on a human forever. The bundle download endpoint is already
+ * public (see services/collector/utils/collectorAuthGate.js PUBLIC_EXACT:
+ * /download/quoxgauge-bundle.tar.gz), so a resident-driven fetch needs no
+ * new permission grant, only this verb.
+ *
+ * Everything here is pure or takes its side effects (HTTP client, exec,
+ * filesystem reads/writes) as injected dependencies, so
+ * cli/lib/commands/done.js is a thin wrapper and every path below is driven
+ * from tests with no real network call, no real `tar`/`sudo`, and no writes
+ * outside a scratch fsOps fake.
+ *
+ * Extraction shape mirrors the collector's own refresh command exactly:
+ * flat `tar -xzf <bundle> -C <dest>`, never into a parent directory.
+ */
+
+import path from 'node:path';
+import os from 'node:os';
+
+export const OPT_GAUGE_DIR = '/opt/quoxgauge';
+
+export function userLocalGaugeDir(home = os.homedir()) {
+  return path.join(home, '.local', 'share', 'quox', 'gauge');
+}
+
+export function legacyGaugeDir(home = os.homedir()) {
+  return path.join(home, 'quox-gauge');
+}
+
+/**
+ * Decide where a fetched engine should land, and whether getting there
+ * needs privilege escalation.
+ *
+ * Order:
+ *   1. --dest (explicit, always wins, never needs sudo)
+ *   2. $QUOX_DONEENGINE_HOME (an override for an already server-controlled
+ *      path, same precedent as QUOX_DONEENGINE_PATH — not a new feature flag)
+ *   3. /opt/quoxgauge, if directly writable, or reachable via passwordless
+ *      sudo (`sudo -n true`) — matching where `quox dev enable` puts it, so
+ *      a resident does not silently diverge from the host-wide install
+ *   4. ~/.local/share/quox/gauge — always-writable fallback
+ *
+ * `isWritable` and `execFn` are injected so this stays testable without a
+ * real filesystem probe or a real `sudo` spawn.
+ */
+export function resolveFetchDestination({ destOption, env = process.env, isWritable, execFn } = {}) {
+  if (destOption) {
+    return { dest: destOption, reason: '--dest', needsSudo: false };
+  }
+  if (env.QUOX_DONEENGINE_HOME) {
+    return { dest: env.QUOX_DONEENGINE_HOME, reason: 'QUOX_DONEENGINE_HOME override', needsSudo: false };
+  }
+
+  const directlyWritable = typeof isWritable === 'function' ? isWritable(OPT_GAUGE_DIR) : false;
+  if (directlyWritable) {
+    return { dest: OPT_GAUGE_DIR, reason: `${OPT_GAUGE_DIR} is writable`, needsSudo: false };
+  }
+
+  let sudoAvailable = false;
+  if (typeof execFn === 'function') {
+    try {
+      const r = execFn('sudo', ['-n', 'true']);
+      sudoAvailable = !!r && r.status === 0;
+    } catch {
+      sudoAvailable = false;
+    }
+  }
+  if (sudoAvailable) {
+    return {
+      dest: OPT_GAUGE_DIR,
+      reason: `${OPT_GAUGE_DIR} is not directly writable, using passwordless sudo (matches quox dev enable's install)`,
+      needsSudo: true,
+    };
+  }
+
+  return {
+    dest: userLocalGaugeDir(),
+    reason: `${OPT_GAUGE_DIR} is not writable and no passwordless sudo is available; falling back to a user-writable path`,
+    needsSudo: false,
+  };
+}
+
+/**
+ * Inspect an install directory. Never throws: an unreadable or missing
+ * directory just reports unhealthy, it is not itself an error.
+ */
+export function inspectInstall(dest, fsOps) {
+  const gaugePath = path.join(dest, 'gauge.mjs');
+  const packsPath = path.join(dest, 'packs');
+  const gaugeExists = fsOps.existsSync(gaugePath);
+  const packsDirExists = fsOps.existsSync(packsPath);
+  let packsCount = 0;
+  if (packsDirExists) {
+    try {
+      packsCount = fsOps.readdirSync(packsPath).filter((f) => f.endsWith('.json')).length;
+    } catch {
+      packsCount = 0;
+    }
+  }
+  return {
+    healthy: gaugeExists && packsDirExists && packsCount > 0,
+    gaugeExists,
+    packsDirExists,
+    packsCount,
+    gaugePath,
+    packsPath,
+  };
+}
+
+/**
+ * Fetch the bundle from the collector and extract it flat into `dest`.
+ *
+ * A healthy existing install is a no-op unless `force` is set. On failure
+ * after a previous install existed, the previous install is restored so a
+ * resident is never left worse off than it started (leave the previous
+ * install intact where possible).
+ *
+ * `client` is the CLI's existing HTTP client (already injectable in every
+ * command via ctx) — reused here rather than a bare fetch so auth headers,
+ * retries and service-url resolution stay identical to every other command.
+ * `execFn(cmd, args)` is the child-process seam (mirrors ctx.spawnFn in
+ * lib/commands/devSupervisor.js): all destination mutation (mkdir/mv/rm/tar)
+ * goes through it, prefixed with `sudo -n` when `needsSudo` is set, so the
+ * privileged and unprivileged paths share one code path.
+ */
+export async function fetchEngine({ dest, needsSudo, force, client, execFn, fsOps } = {}) {
+  if (!force) {
+    const existing = inspectInstall(dest, fsOps);
+    if (existing.healthy) {
+      return {
+        status: 'noop',
+        dest,
+        packsCount: existing.packsCount,
+        message: `DoneEngine already installed and healthy at ${dest} (${existing.packsCount} packs). `
+          + 'Nothing to do; pass --force to re-fetch anyway.',
+      };
+    }
+  }
+
+  const res = await client.get('/download/quoxgauge-bundle.tar.gz', { service: 'collector', raw: true });
+  if (!res || !res.ok) {
+    throw new Error(`Bundle download failed (status ${res ? res.status : 'no response'}) from /download/quoxgauge-bundle.tar.gz`);
+  }
+  const buffer = Buffer.from(await res.arrayBuffer());
+  const tmpFile = fsOps.tmpFile();
+  fsOps.writeFileSync(tmpFile, buffer);
+
+  const run = (cmd, args) => (needsSudo ? execFn('sudo', ['-n', cmd, ...args]) : execFn(cmd, args));
+  const requireOk = (r, label) => {
+    if (!r || r.status !== 0) {
+      throw new Error(`${label} failed: ${(r && (r.stderr || r.stdout)) || 'unknown error'}`);
+    }
+  };
+
+  const hadPrevious = fsOps.existsSync(dest);
+  const backupDest = `${dest}.pre-fetch`;
+  // A writable dest inside a non-writable parent (e.g. control-owned
+  // /opt/quoxgauge under root:root /opt) cannot be renamed to a sibling.
+  // Back up its contents into a temp dir instead and mutate dest in place.
+  const inPlace = hadPrevious && !needsSudo
+    && typeof fsOps.isWritable === 'function'
+    && !fsOps.isWritable(path.dirname(dest));
+  let inPlaceBackup = null;
+  const emptyDest = () => run('find', [dest, '-mindepth', '1', '-delete']);
+
+  try {
+    if (inPlace) {
+      inPlaceBackup = fsOps.mkdtemp();
+      requireOk(run('cp', ['-a', `${dest}/.`, `${inPlaceBackup}/`]), 'backing up previous install in place');
+      requireOk(emptyDest(), 'emptying previous install');
+    } else if (hadPrevious) {
+      if (fsOps.existsSync(backupDest)) requireOk(run('rm', ['-rf', backupDest]), 'clearing stale backup');
+      requireOk(run('mv', [dest, backupDest]), 'backing up previous install');
+    }
+
+    requireOk(run('mkdir', ['-p', dest]), 'creating destination');
+    requireOk(run('tar', ['-xzf', tmpFile, '-C', dest]), 'extracting bundle');
+
+    const verified = inspectInstall(dest, fsOps);
+    if (!verified.healthy) {
+      throw new Error(
+        `Extracted bundle at ${dest} failed verification `
+        + `(gauge.mjs present: ${verified.gaugeExists}, packs: ${verified.packsCount}). `
+        + 'Left the previous install in place where one existed.',
+      );
+    }
+
+    if (inPlace) requireOk(run('rm', ['-rf', inPlaceBackup]), 'cleaning up backup');
+    else if (hadPrevious) requireOk(run('rm', ['-rf', backupDest]), 'cleaning up backup');
+
+    return {
+      status: 'updated',
+      dest,
+      packsCount: verified.packsCount,
+      message: `DoneEngine installed at ${dest} (${verified.packsCount} packs).`,
+    };
+  } catch (err) {
+    if (inPlaceBackup) {
+      emptyDest();
+      run('cp', ['-a', `${inPlaceBackup}/.`, `${dest}/`]);
+    } else if (hadPrevious && fsOps.existsSync(backupDest)) {
+      run('rm', ['-rf', dest]);
+      run('mv', [backupDest, dest]);
+    }
+    throw err;
+  } finally {
+    if (inPlaceBackup) {
+      try { run('rm', ['-rf', inPlaceBackup]); } catch { /* best effort cleanup */ }
+    }
+    try { fsOps.rmSync(tmpFile, { force: true }); } catch { /* best effort cleanup */ }
+  }
+}

package/lib/core/errors.js

@@ -0,0 +1,132 @@
+/**
+ * Error types and handler for QuoxCLI
+ */
+
+import chalk from 'chalk';
+
+export class QuoxError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = 'QuoxError';
+    this.exitCode = exitCode;
+  }
+}
+
+export class QuoxApiError extends QuoxError {
+  /**
+   * @param {number} status  HTTP status
+   * @param {string} code    machine-readable error code from the body
+   * @param {string} message human-readable message
+   * @param {*} [detail]     the body's `detail`/`details` field, if any
+   * @param {object} [body]  LL-3d: the WHOLE parsed JSON error body. Lifting
+   *   only message/detail threw away everything else the server said, and the
+   *   licensing endpoints say a lot: which instance holds the seat, how many
+   *   of the licensed servers are in use, which plugin is unlicensed. Command
+   *   handlers read this to render something actionable; --json emits it raw.
+   */
+  constructor(status, code, message, detail, body) {
+    super(message, statusToExitCode(status));
+    this.name = 'QuoxApiError';
+    this.status = status;
+    this.code = code;
+    this.detail = detail;
+    if (body && typeof body === 'object') this.body = body;
+  }
+}
+
+export class QuoxAuthError extends QuoxError {
+  constructor(message = 'Not authenticated. Run `quox login` first.') {
+    super(message, 3);
+    this.name = 'QuoxAuthError';
+  }
+}
+
+/**
+ * A re-authentication that failed for a reason expected to clear by itself
+ * (auth service restarting, 429 rate_limited on the resident token exchange,
+ * 502/503/504, network fault). It IS a QuoxAuthError, so every verb that does
+ * not know about it behaves exactly as before; only long-lived listeners
+ * (`quox slot wait`) choose to back off and keep going. `retryAfterMs` carries
+ * the server's Retry-After when it sent one.
+ */
+export class QuoxTransientAuthError extends QuoxAuthError {
+  constructor(message, retryAfterMs = null) {
+    super(message);
+    this.name = 'QuoxTransientAuthError';
+    this.transient = true;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+export class QuoxNetworkError extends QuoxError {
+  constructor(message = 'Could not connect to QuoxCORE services.', cause) {
+    super(message, 7);
+    this.name = 'QuoxNetworkError';
+    this.cause = cause;
+  }
+}
+
+export class QuoxValidationError extends QuoxError {
+  constructor(message) {
+    super(message, 2);
+    this.name = 'QuoxValidationError';
+  }
+}
+
+function statusToExitCode(status) {
+  if (status === 401) return 3;
+  if (status === 403) return 4;
+  if (status === 404) return 5;
+  if (status === 409) return 6;
+  if (status >= 500) return 8;
+  return 1;
+}
+
+const STATUS_HINTS = {
+  401: 'Run `quox login` to authenticate.',
+  403: 'You may not have permission. Try `quox org switch` to change context.',
+  404: 'Resource not found. Use the `list` subcommand to see what exists.',
+  409: 'Resource conflict. The item may already exist.',
+  429: 'Rate limited. Wait a moment and try again.',
+  500: 'Server error. Use --debug for details.',
+  502: 'Service temporarily unavailable. Check `quox service health`.',
+  503: 'Service temporarily unavailable. Check `quox service health`.',
+};
+
+export function handleError(err, outputFormat = 'table') {
+  if (outputFormat === 'json') {
+    const obj = {
+      error: true,
+      code: err.code || err.name,
+      message: err.message,
+    };
+    if (err.status) obj.status = err.status;
+    if (err.detail) obj.detail = err.detail;
+    // LL-3d: scripts parsing --json get the server's own body verbatim, not
+    // our prose rendering of it.
+    if (err.body && typeof err.body === 'object') obj.body = err.body;
+    process.stderr.write(JSON.stringify(obj) + '\n');
+    return;
+  }
+
+  if (err instanceof QuoxApiError) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    if (err.detail) console.error(chalk.dim(`  Detail: ${err.detail}`));
+    console.error(chalk.dim(`  Status: ${err.status} ${err.code || ''}`));
+    const hint = STATUS_HINTS[err.status];
+    if (hint) console.error(chalk.yellow(`  Hint: ${hint}`));
+  } else if (err instanceof QuoxAuthError) {
+    console.error(chalk.red(`Auth: ${err.message}`));
+  } else if (err instanceof QuoxNetworkError) {
+    console.error(chalk.red(`Network: ${err.message}`));
+    console.error(chalk.yellow('  Hint: Check that services are running with `quox service health`.'));
+  } else if (err instanceof QuoxValidationError) {
+    console.error(chalk.red(`Validation: ${err.message}`));
+  } else {
+    console.error(chalk.red(`Error: ${err.message}`));
+    if (process.env.DEBUG || process.argv.includes('--debug')) {
+      const sanitized = (err.stack || '').replace(/eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, '[JWT_REDACTED]');
+      console.error(chalk.dim(sanitized));
+    }
+  }
+}

package/lib/core/global-flags.js

@@ -0,0 +1,90 @@
+/**
+ * global-flags.js — repair for commander's silent global-flag shadowing.
+ *
+ * Commander 13 resolves a long flag against the ROOT program first. When a
+ * subcommand redeclares a flag the root already declares, the root definition
+ * wins: the typed value lands on `program.opts()` and the subcommand's own
+ * options object holds `undefined` forever. Nothing warns. Nothing throws.
+ *
+ * That is a silent-wrong-answer bug, and it had already shipped in 13 places:
+ *
+ *   - `quox gripe --yes` read `options.yes === undefined`, so it never told
+ *     GRIPE to file directly and then advised re-running with the flag the
+ *     user had just passed (fleet #441). Headless sessions could not file
+ *     a gripe at all.
+ *   - `--dry-run` on `vault migrate`, `admin` and `backup restore` read
+ *     `undefined`, meaning a requested dry run EXECUTED FOR REAL. That one
+ *     can cost data, which is why this is a scaffold fix and not a patch to
+ *     gripe.js alone.
+ *   - `--org` on fleet/skills/governance/done and `--json` on done/qlarity
+ *     silently fell back to the active org / table output.
+ *
+ * The fix is a merge-down, not a de-duplication. Removing the subcommand's
+ * declaration would also work, but commander does not list parent options in
+ * subcommand help (verified on 13.1.0), so `quox vault migrate --help` would
+ * stop mentioning `--dry-run` while still honouring it. Keeping the local
+ * declaration keeps it discoverable; this hook makes it actually arrive.
+ *
+ * Only options the subcommand ITSELF declares are merged, so a command that
+ * never declared `--yes` does not silently gain it.
+ */
+
+/**
+ * Copy shadowed global values down onto the subcommand that declared them.
+ *
+ * @param {import('commander').Command} rootCommand - the root program
+ * @param {import('commander').Command} actionCommand - the subcommand running
+ * @returns {string[]} attribute names that were merged (for tests/diagnostics)
+ */
+export function mergeShadowedGlobals(rootCommand, actionCommand) {
+  if (!rootCommand || !actionCommand || actionCommand === rootCommand) return [];
+
+  const rootOpts = rootCommand.opts();
+  const merged = [];
+
+  for (const option of actionCommand.options) {
+    const name = option.attributeName();
+    // A shadowed option can never carry a user value (commander gave it to
+    // the root), so an undefined here is unambiguous: nothing local to lose.
+    // A subcommand default is a real value and is left alone.
+    if (actionCommand.getOptionValue(name) === undefined && rootOpts[name] !== undefined) {
+      actionCommand.setOptionValue(name, rootOpts[name]);
+      merged.push(name);
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Walk a command tree and report every subcommand option that collides with a
+ * root option. Used by the regression test to keep the blast radius visible:
+ * new collisions are fine (the hook handles them) but they should be a
+ * deliberate, seen decision rather than a surprise.
+ *
+ * @param {import('commander').Command} rootCommand
+ * @returns {Array<{command: string, flag: string, attribute: string}>}
+ */
+export function findShadowedOptions(rootCommand) {
+  const rootAttrs = new Map();
+  for (const option of rootCommand.options) {
+    rootAttrs.set(option.attributeName(), option.flags);
+  }
+
+  const found = [];
+  const walk = (cmd, path) => {
+    for (const sub of cmd.commands) {
+      const subPath = [...path, sub.name()];
+      for (const option of sub.options) {
+        const attr = option.attributeName();
+        if (rootAttrs.has(attr)) {
+          found.push({ command: subPath.join(' '), flag: option.flags, attribute: attr });
+        }
+      }
+      walk(sub, subPath);
+    }
+  };
+  walk(rootCommand, []);
+
+  return found;
+}