quoxcli 0.0.0-stage → 0.3.1

package/lib/core/confirm.js

@@ -0,0 +1,37 @@
+/**
+ * Shared non-TTY-safe destructive-action confirmation.
+ *
+ * fleet #398/#399: several commands (`prompt delete`, `tag delete`, etc.)
+ * either lacked a --force/-y escape hatch entirely, or called inquirer
+ * unconditionally when neither was set. On a non-interactive shell (no
+ * stdin TTY — cron, CI, a piped script) inquirer throws
+ * `Error: User force closed the prompt with 13 null` AND leaks
+ * `Warning: Detected unsettled top-level await at cli/bin/quox.js:221`,
+ * verified live on .131. Checking `process.stdin.isTTY` BEFORE importing
+ * inquirer avoids both — fail fast with a clear message instead.
+ */
+
+/**
+ * @param {import('commander').Command} program - root commander program (for global --yes)
+ * @param {{ force?: boolean }} options - local command options (for --force)
+ * @param {string} message - confirmation prompt text
+ * @returns {Promise<boolean>}
+ */
+export async function confirmDestructive(program, options, message) {
+  if (options.force === true || program.opts().yes === true) {
+    return true;
+  }
+
+  if (!process.stdin.isTTY) {
+    throw new Error(`${message} — this needs confirmation; re-run with --force (or -y) in a non-interactive shell`);
+  }
+
+  const { default: inquirer } = await import('inquirer');
+  const ans = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'confirm',
+    message,
+    default: false,
+  }]);
+  return ans.confirm;
+}

package/lib/core/customHats.js

@@ -0,0 +1,168 @@
+/**
+ * CUSTOM-HATS (owner 2026-10-17): pure helpers that build and edit a custom hat definition.
+ * Shared by `quox hat create|edit` (cli/lib/commands/hat.js) and the quox window's /hat new|edit
+ * (cli/lib/quoxon). No I/O, no chalk: safe to import anywhere.
+ */
+
+/** The two tools an orchestrator needs to reach the agents a hat lists. */
+export const DELEGATION_TOOLS = ['delegate_to_agent', 'agent_directory'];
+export const HAT_MODES = ['permissive', 'restrictive'];
+export const HAT_OFFERS = ['members', 'authorized'];
+const HARD_CAP = 128;
+
+/** "a, b,,c" -> ['a','b','c'] (trimmed, lowercased, deduped, order kept). */
+export function parseList(v) {
+  if (v === undefined || v === null || v === true) return [];
+  const out = [];
+  for (const raw of String(v).split(',')) {
+    const x = raw.trim().toLowerCase();
+    if (x && !out.includes(x)) out.push(x);
+  }
+  return out;
+}
+
+/** Every tool name a hat names: explicit, bundles, on-demand reads. */
+export function memberTools(def) {
+  const t = def?.tools || {};
+  const names = [
+    ...(Array.isArray(t.explicit) ? t.explicit : []),
+    ...(Array.isArray(t.bundles) ? t.bundles.flatMap(b => (Array.isArray(b?.tools) ? b.tools : [])) : []),
+    ...(Array.isArray(t.on_demand_reads) ? t.on_demand_reads : []),
+  ];
+  return [...new Set(names)];
+}
+
+function emptyDefinition() {
+  return {
+    schema_version: 1,
+    purpose: '',
+    agents: { orchestrator: 'quox', specialists: [] },
+    tools: { explicit: [], bundles: [], connector_families: [] },
+    budgets: { initial_tool_target: 12, max_manifest: 32 },
+    transitions: { allowed: 'any', confirm: 'none', privileged: false },
+  };
+}
+
+function ensureDelegationTools(def) {
+  const specialists = def.agents?.specialists || [];
+  if (!specialists.length) return [];
+  const explicit = def.tools.explicit;
+  const added = DELEGATION_TOOLS.filter(t => !explicit.includes(t));
+  explicit.unshift(...added);
+  return added;
+}
+
+function fitBudgets(def) {
+  const b = def.budgets || (def.budgets = {});
+  const need = (def.tools.explicit || []).length;
+  if (!Number.isInteger(b.max_manifest) || b.max_manifest < need) b.max_manifest = Math.min(HARD_CAP, Math.max(32, need));
+  if (!Number.isInteger(b.initial_tool_target) || b.initial_tool_target < 1) b.initial_tool_target = Math.min(12, b.max_manifest);
+  if (b.initial_tool_target > b.max_manifest) b.initial_tool_target = b.max_manifest;
+}
+
+/**
+ * Restrictive = the hat AUTHORIZES only its members (+ the delegation pair); this binds every agent
+ * working under the hat, the hat's own agents included when delegated to. Permissive = the agent's
+ * own grant is the ceiling (the default). A deny list carried from --from is kept either way.
+ */
+export function applyMode(def, mode) {
+  if (mode === undefined || mode === null) return;
+  if (!HAT_MODES.includes(mode)) throw new Error(`--mode must be ${HAT_MODES.join(' or ')} (got '${mode}')`);
+  const deny = Array.isArray(def.authz?.deny) ? def.authz.deny : null;
+  if (mode === 'permissive') {
+    if (deny) def.authz = { mode: 'permissive', deny };
+    else delete def.authz;
+    return;
+  }
+  def.authz = { mode: 'restrictive', allow: [...new Set([...memberTools(def), ...DELEGATION_TOOLS])], ...(deny ? { deny } : {}) };
+}
+
+/**
+ * The definition a new custom hat starts from: a copy of --from (or an empty hat), with
+ * --agents / --tools REPLACING the lists, the delegation tools added when the hat lists agents,
+ * the offer set (default 'members': a custom hat offers its orchestrator only what it lists),
+ * and budgets widened to fit. Pure: never mutates base.
+ */
+export function buildCustomDefinition({ base = null, name = '', purpose, agents, tools, mode, offer } = {}) {
+  const def = base ? JSON.parse(JSON.stringify(base)) : emptyDefinition();
+  def.schema_version = 1;
+  def.agents = { orchestrator: 'quox', ...(def.agents || {}) };
+  if (!Array.isArray(def.agents.specialists)) def.agents.specialists = [];
+  def.tools = { ...(def.tools || {}) };
+  def.tools.explicit = Array.isArray(def.tools.explicit) ? [...def.tools.explicit] : [];
+  if (agents !== undefined) def.agents.specialists = [...agents];
+  if (tools !== undefined) def.tools.explicit = [...tools];
+  const autoAdded = ensureDelegationTools(def);
+  const o = offer === undefined ? 'members' : offer;
+  if (!HAT_OFFERS.includes(o)) throw new Error(`--offer must be ${HAT_OFFERS.join(' or ')} (got '${o}')`);
+  def.tools.offer = o;
+  if (purpose !== undefined && String(purpose).trim()) def.purpose = String(purpose).trim();
+  if (!def.purpose || base) {
+    if (purpose === undefined || !String(purpose).trim()) def.purpose = `${name || 'Custom'} work${def.agents.specialists.length ? ` with ${def.agents.specialists.join(', ')}` : ''}`;
+  }
+  fitBudgets(def);
+  applyMode(def, mode);
+  return { definition: def, autoAdded };
+}
+
+/**
+ * Apply `quox hat edit` options to a copy of a definition. Returns the new definition and a
+ * human list of changes (empty = nothing to do). --agents/--tools replace; --add-* / --remove-*
+ * adjust. A restrictive allow list follows tool adds/removes so the hat keeps authorizing exactly
+ * its members.
+ */
+export function applyHatEdits(current, opts = {}) {
+  const def = JSON.parse(JSON.stringify(current || {}));
+  def.agents = { orchestrator: 'quox', ...(def.agents || {}) };
+  def.tools = { ...(def.tools || {}) };
+  let specialists = Array.isArray(def.agents.specialists) ? [...def.agents.specialists] : [];
+  let explicit = Array.isArray(def.tools.explicit) ? [...def.tools.explicit] : [];
+  const changes = [];
+  const beforeAgents = [...specialists];
+  const beforeTools = new Set(memberTools(def));
+
+  if (opts.agents !== undefined) specialists = [...opts.agents];
+  for (const a of opts.addAgents || []) if (!specialists.includes(a)) specialists.push(a);
+  if ((opts.removeAgents || []).length) specialists = specialists.filter(a => !opts.removeAgents.includes(a));
+  if (opts.tools !== undefined) explicit = [...opts.tools];
+  for (const t of opts.addTools || []) if (!explicit.includes(t)) explicit.push(t);
+  if ((opts.removeTools || []).length) {
+    explicit = explicit.filter(t => !opts.removeTools.includes(t));
+    if (Array.isArray(def.tools.bundles)) def.tools.bundles = def.tools.bundles.map(b => ({ ...b, tools: (b.tools || []).filter(t => !opts.removeTools.includes(t)) }));
+  }
+  def.agents.specialists = specialists;
+  def.tools.explicit = explicit;
+  const autoAdded = (opts.removeTools || []).some(t => DELEGATION_TOOLS.includes(t)) ? [] : ensureDelegationTools(def);
+
+  const agentsAdded = specialists.filter(a => !beforeAgents.includes(a));
+  const agentsRemoved = beforeAgents.filter(a => !specialists.includes(a));
+  if (agentsAdded.length) changes.push(`agents +${agentsAdded.join(', +')}`);
+  if (agentsRemoved.length) changes.push(`agents -${agentsRemoved.join(', -')}`);
+  const afterTools = new Set(memberTools(def));
+  const toolsAdded = [...afterTools].filter(t => !beforeTools.has(t));
+  const toolsRemoved = [...beforeTools].filter(t => !afterTools.has(t));
+  if (toolsAdded.length) changes.push(`tools +${toolsAdded.join(', +')}`);
+  if (toolsRemoved.length) changes.push(`tools -${toolsRemoved.join(', -')}`);
+
+  if (opts.purpose !== undefined && String(opts.purpose).trim() && String(opts.purpose).trim() !== def.purpose) {
+    def.purpose = String(opts.purpose).trim();
+    changes.push('purpose');
+  }
+  if (opts.offer !== undefined) {
+    if (!HAT_OFFERS.includes(opts.offer)) throw new Error(`--offer must be ${HAT_OFFERS.join(' or ')} (got '${opts.offer}')`);
+    if ((def.tools.offer || 'authorized') !== opts.offer) { def.tools.offer = opts.offer; changes.push(`offer ${opts.offer}`); }
+  }
+  const prevMode = def.authz?.mode === 'restrictive' ? 'restrictive' : 'permissive';
+  if (opts.mode !== undefined) {
+    applyMode(def, opts.mode);
+    if (opts.mode !== prevMode) changes.push(`mode ${opts.mode}`);
+  } else if (prevMode === 'restrictive' && Array.isArray(def.authz?.allow) && (toolsAdded.length || toolsRemoved.length)) {
+    const allow = new Set(def.authz.allow);
+    for (const t of toolsAdded) allow.add(t);
+    for (const t of toolsRemoved) allow.delete(t);
+    def.authz = { ...def.authz, allow: [...allow] };
+  }
+  fitBudgets(def);
+  return { definition: def, changes, autoAdded };
+}
+

package/lib/core/deeplinks.js

@@ -0,0 +1,76 @@
+/**
+ * Deep Links — quox:// URI scheme
+ *
+ * Every Quox entity has a canonical URI:
+ *   quox://fleet/docker01
+ *   quox://workflow/WF_abc123/run/RUN_xyz
+ *   quox://agent/sentinel
+ *   quox://aee/ENV_789
+ *   quox://memory/MEM_123
+ *
+ * URIs resolve to both a dashboard URL (browser) and a CLI command.
+ *
+ * CLI-3f (Stream CLI Phase 3)
+ */
+
+const ROUTE_MAP = {
+  fleet:        { dashboard: '/noc?host=',        cli: 'bastion host show' },
+  agent:        { dashboard: '/agents?id=',       cli: 'quox agent get' },
+  workflow:     { dashboard: '/workflows?id=',    cli: 'quox workflow get' },
+  aee:          { dashboard: '/activity?id=',     cli: 'quox aee get' },
+  memory:       { dashboard: '/memory?id=',       cli: 'quox memory get' },
+  tool:         { dashboard: '/tools?id=',        cli: 'quox tool get' },
+  vault:        { dashboard: '/settings/vault?id=', cli: 'quox vault get' },
+  session:      { dashboard: '/fleet?session=',   cli: 'quoxagent agent info' },
+  conversation: { dashboard: '/assistants?conv=', cli: 'quox conversation get' },
+};
+
+/**
+ * Build a quox:// URI for an entity.
+ * @param {string} type - Entity type (fleet, workflow, agent, aee, etc.)
+ * @param {string} id - Entity ID
+ * @param {string} [subpath] - Optional sub-path (e.g., "run/RUN_xyz")
+ * @returns {string}
+ */
+export function buildQuoxUri(type, id, subpath) {
+  let uri = `quox://${type}/${id}`;
+  if (subpath) uri += `/${subpath}`;
+  return uri;
+}
+
+/**
+ * Resolve a quox:// URI to a dashboard URL and CLI command.
+ * @param {string} uri - The quox:// URI
+ * @param {string} baseUrl - Dashboard base URL (e.g., http://localhost:3000)
+ * @returns {{_ref: string, type: string, id: string, dashboardUrl: string, cliCommand: string}|null}
+ */
+export function resolveQuoxUri(uri, baseUrl) {
+  if (!uri || !uri.startsWith('quox://')) return null;
+
+  const path = uri.slice('quox://'.length);
+  const parts = path.split('/');
+  const type = parts[0];
+  const id = parts[1];
+
+  if (!type || !id) return null;
+
+  const route = ROUTE_MAP[type];
+  if (!route) {
+    // Unknown type — best effort
+    return {
+      _ref: uri,
+      type,
+      id,
+      dashboardUrl: `${baseUrl}/${type}?id=${id}`,
+      cliCommand: `quox ${type} get ${id}`,
+    };
+  }
+
+  return {
+    _ref: uri,
+    type,
+    id,
+    dashboardUrl: `${baseUrl}${route.dashboard}${id}`,
+    cliCommand: `${route.cli} ${id}`,
+  };
+}

package/lib/core/doneEngineFetch.js

@@ -0,0 +1,227 @@
+/**
+ * `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 });
+  // #988: a public install's collector has no DoneEngine bundle (dev servers build it from the private quox-gauge
+  // repo), so a 404 is a fact about this install, not a transient failure worth retrying.
+  if (res && res.status === 404) {
+    const err = new Error('DoneEngine is not part of this Quox install: this collector does not carry the DoneEngine bundle '
+      + '(it is delivered to Quox dev servers by `quox dev enable`). Nothing was changed.');
+    err.code = 'DONEENGINE_NOT_SHIPPED';
+    throw err;
+  }
+  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 */ }
+  }
+}