quoxcli 0.0.0-stage → 0.3.1

package/lib/commands/policy.js

@@ -0,0 +1,78 @@
+/**
+ * `quox policy` — the governance compiler from the terminal (OPGOV quox#582).
+ *
+ * compile: plain-language rule -> deterministic quox-policy.v1 DRAFT, with
+ * the compiled policy printed in full for review (a policy nobody read is
+ * not governance). arm: moves a reviewed draft to armed; the collector
+ * refuses arming without a logged-in human. Honesty: enforcement is phase 3
+ * (IMPACT #491) and is NOT wired; an armed policy is a reviewed intent, not
+ * yet a running gate, and this command says so.
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+
+function isJsonOutput(program) {
+  const o = program.opts();
+  return o.json === true || o.output === 'json';
+}
+
+const NOT_ENFORCED_NOTE = 'note: enforcement is phase 3 (IMPACT #491) and is not wired yet; armed = reviewed intent, not a running gate.';
+
+export function registerPolicyCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const p = program
+    .command('policy')
+    .description('Governance compiler: plain-language rule -> reviewed, armable policy (OPGOV)');
+
+  p.command('compile <rule>')
+    .description('Compile a plain-language rule to a quox-policy.v1 draft (deterministic grammar; out-of-grammar rules are refused, never approximated)')
+    .action(async (rule) => {
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('governance.policy.compile', { orgId });
+      try {
+        const data = await client.post(ep.path, { service: ep.service, body: { rule } });
+        if (isJsonOutput(program)) { console.log(JSON.stringify(data, null, 2)); return; }
+        const rec = data.record;
+        console.log(`compiled DRAFT ${rec.id} (${rec.policy.effect})`);
+        console.log(JSON.stringify(rec.policy, null, 2));
+        console.log(`review it, then: quox policy arm ${rec.id}`);
+        console.log(NOT_ENFORCED_NOTE);
+      } catch (err) {
+        const msg = err?.message || String(err);
+        if (/422|unknown/i.test(msg)) {
+          console.log('NOT COMPILED: the rule is outside the deterministic grammar and was refused rather than approximated.');
+        }
+        throw err;
+      }
+    });
+
+  p.command('list')
+    .description('List compiled policies for this org')
+    .option('--state <s>', 'draft | armed | retired')
+    .action(async (opts) => {
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('governance.policy.list', { orgId, state: opts.state });
+      const data = await client.get(ep.path, { service: ep.service });
+      if (isJsonOutput(program)) { console.log(JSON.stringify(data, null, 2)); return; }
+      const items = data.policies || [];
+      if (!items.length) { console.log('No policies. Compile one: quox policy compile "<rule>"'); return; }
+      for (const r of items) {
+        console.log(`${r.id}  [${r.state}]  ${r.policy?.effect ?? '?'}  ${r.rule_text}${r.approved_by ? `  (armed by ${r.approved_by})` : ''}`);
+      }
+      console.log(NOT_ENFORCED_NOTE);
+    });
+
+  p.command('arm <id>')
+    .description('Arm a reviewed draft (requires a logged-in human; service keys are refused by design)')
+    .action(async (id) => {
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('governance.policy.arm', { orgId, id });
+      const data = await client.post(ep.path, { service: ep.service, body: {} });
+      if (isJsonOutput(program)) { console.log(JSON.stringify(data, null, 2)); return; }
+      const rec = data.record;
+      console.log(`ARMED ${rec.id} (${rec.policy.effect}) approved by ${rec.approved_by}`);
+      console.log(NOT_ENFORCED_NOTE);
+    });
+}

package/lib/commands/powers.js

@@ -0,0 +1,296 @@
+/**
+ * Powers commands: MCP endpoint + hosted-repo tool deploys (LIFECYCLE-P1..P3)
+ *
+ * quox powers detect|deploy|deploy-repo|status|finalize|update|archive|restore|config|delete
+ *
+ * Backend: services/auth/routes/powers.js, mounted org-scoped at
+ * `/api/orgs/:orgId/powers/...`. Two deploy flows:
+ *   - `deploy` (mcp_endpoint): probes a live MCP URL and registers it as a
+ *     governed agent in one call. Requires `persona` (agent_id + name) upfront.
+ *   - `deploy-repo` (mcp_hosted): kicks off an async container build from a
+ *     GitHub repo (202 Accepted). Poll `status` until the build reaches a
+ *     terminal state (`built`/`failed`), then call `finalize` (persona
+ *     required there, NOT at deploy-repo time) to activate the agent.
+ */
+
+import { formatDetail, printSuccess, printWarning, printInfo } from '../core/output.js';
+import { resolveOrgId } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const TERMINAL_BUILD_STATES = new Set(['built', 'failed']);
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/** Commander collector for repeatable --env key=value flags -> [{ key, value }]. */
+function collectEnvVar(input, previous) {
+  const idx = input.indexOf('=');
+  if (idx === -1) {
+    throw new Error(`Invalid --env value "${input}". Expected key=value.`);
+  }
+  const key = input.slice(0, idx).trim();
+  const value = input.slice(idx + 1);
+  if (!key) {
+    throw new Error(`Invalid --env value "${input}". Key cannot be empty.`);
+  }
+  return [...previous, { key, value }];
+}
+
+function buildPersona(options, { requireCore = false } = {}) {
+  const persona = {};
+  if (options.agentId) persona.agent_id = options.agentId;
+  if (options.name) persona.name = options.name;
+  if (options.description !== undefined) persona.description = options.description;
+  if (options.icon) persona.icon = options.icon;
+  if (options.systemPromptAdditions) persona.system_prompt_additions = options.systemPromptAdditions;
+  if (requireCore && (!persona.agent_id || !persona.name)) {
+    throw new Error('--agent-id and --name are required.');
+  }
+  return persona;
+}
+
+async function confirmOrSkip(message) {
+  const { default: inquirer } = await import('inquirer');
+  const ans = await inquirer.prompt([{ type: 'confirm', name: 'confirm', message, default: false }]);
+  return ans.confirm;
+}
+
+export function registerPowersCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const powers = program
+    .command('powers')
+    .description('Deploy and manage POWERS (MCP endpoint / hosted-repo tools)');
+
+  // ── powers detect ───────────────────────────────────────────────────────────
+
+  powers
+    .command('detect')
+    .description('Probe an MCP URL to see what kind of server it is and what tools it exposes')
+    .requiredOption('--url <url>', 'MCP server URL')
+    .option('--auth-kind <kind>', 'none|bearer|header', 'none')
+    .option('--auth-value <value>', 'auth token/header value (required if --auth-kind is bearer or header)')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = { url: options.url, authKind: options.authKind };
+      if (options.authValue) body.authValue = options.authValue;
+      const ep = resolveEndpoint('powers.detect', { orgId });
+      const data = await client.post(ep.path, { service: ep.service, body });
+      formatDetail(data, { format: program.opts().output, title: 'Detection Result' });
+    });
+
+  // ── powers deploy (mcp_endpoint) ────────────────────────────────────────────
+
+  powers
+    .command('deploy')
+    .description('Deploy a live MCP endpoint as a governed agent (one-shot, no build)')
+    .requiredOption('--url <url>', 'MCP server URL')
+    .option('--auth-kind <kind>', 'none|bearer|header', 'none')
+    .option('--auth-value <value>', 'auth token/header value')
+    .requiredOption('--agent-id <id>', 'new agent id (lowercase letters/numbers/underscores, starts with a letter)')
+    .requiredOption('--name <name>', 'agent display name')
+    .option('--description <text>', 'agent description')
+    .option('--icon <icon>', 'agent icon')
+    .option('--system-prompt-additions <text>', 'extra system prompt text for the agent')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = {
+        url: options.url,
+        authKind: options.authKind,
+        persona: buildPersona(options, { requireCore: true }),
+      };
+      if (options.authValue) body.authValue = options.authValue;
+      const ep = resolveEndpoint('powers.deploy', { orgId });
+      const data = await client.post(ep.path, { service: ep.service, body });
+      printSuccess(`Power deployed: agent "${data.agent_id}" (tool ${data.tool_id}).`);
+      formatDetail(data, { format: program.opts().output });
+    });
+
+  // ── powers deploy-repo (mcp_hosted) ─────────────────────────────────────────
+
+  powers
+    .command('deploy-repo')
+    .description('Deploy a public GitHub repo as a hosted MCP power (builds a container; async)')
+    .requiredOption('--repo-url <url>', 'public GitHub repo URL, e.g. https://github.com/owner/repo')
+    .option('--env <key=value>', 'env var to inject into the build (repeatable)', collectEnvVar, [])
+    .option('--agent-id <id>', 'reserve an agent id upfront (optional — can also be set at finalize)')
+    .option('--force-suffix <suffix>', 'suffix to allow deploying the same repo again as a duplicate')
+    .option('--no-poll', 'return immediately after kicking off the build instead of polling status')
+    .option('--poll-interval <ms>', 'polling interval in ms', '3000')
+    .option('--poll-timeout <ms>', 'max time to poll before giving up, in ms', '300000')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+
+      const body = { repo_url: options.repoUrl, env_vars: options.env };
+      if (options.agentId) body.persona = { agent_id: options.agentId };
+      if (options.forceSuffix) body.force_suffix = options.forceSuffix;
+
+      const deployEp = resolveEndpoint('powers.deploy-repo', { orgId });
+      const data = await client.post(deployEp.path, { service: deployEp.service, body });
+      printSuccess(`Build started: tool_def_id=${data.tool_def_id} (${data.tool_id}), build_state=${data.build_state}.`);
+
+      if (options.poll === false) {
+        formatDetail(data, { format: program.opts().output });
+        printInfo(`Poll with: quox powers status ${data.tool_def_id}`);
+        return;
+      }
+
+      const toolDefId = data.tool_def_id;
+      const pollInterval = Number(options.pollInterval);
+      const pollTimeout = Number(options.pollTimeout);
+      const statusEp = resolveEndpoint('powers.deploy-repo.status', { orgId, toolDefId });
+      const start = Date.now();
+      let status = { build_state: data.build_state };
+
+      while (!TERMINAL_BUILD_STATES.has(status.build_state) && (Date.now() - start) < pollTimeout) {
+        await sleep(pollInterval);
+        status = await client.get(statusEp.path, { service: statusEp.service });
+        printInfo(`build_state=${status.build_state}`);
+      }
+
+      formatDetail(status, { format: program.opts().output, title: 'Build Status' });
+
+      if (status.build_state === 'built') {
+        printSuccess(`Build complete. Run: quox powers finalize ${toolDefId} --agent-id <id> --name <name>`);
+      } else if (status.build_state === 'failed') {
+        printWarning(`Build failed: ${status.build_failed_reason || 'unknown reason'}`);
+      } else {
+        printWarning(`Polling timed out before the build reached a terminal state. Check later: quox powers status ${toolDefId}`);
+      }
+    });
+
+  // ── powers status ───────────────────────────────────────────────────────────
+
+  powers
+    .command('status')
+    .description('Check a hosted-repo power\'s build status')
+    .argument('<toolDefId>', 'tool definition ID')
+    .action(async (toolDefId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('powers.deploy-repo.status', { orgId, toolDefId });
+      const data = await client.get(ep.path, { service: ep.service });
+      formatDetail(data, { format: program.opts().output, title: 'Build Status' });
+    });
+
+  // ── powers finalize ─────────────────────────────────────────────────────────
+
+  powers
+    .command('finalize')
+    .description('Activate the agent for a completed hosted-repo build')
+    .argument('<toolDefId>', 'tool definition ID')
+    .requiredOption('--agent-id <id>', 'new agent id (lowercase letters/numbers/underscores, starts with a letter)')
+    .requiredOption('--name <name>', 'agent display name')
+    .option('--description <text>', 'agent description')
+    .option('--icon <icon>', 'agent icon')
+    .option('--system-prompt-additions <text>', 'extra system prompt text for the agent')
+    .action(async (toolDefId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = { persona: buildPersona(options, { requireCore: true }) };
+      const ep = resolveEndpoint('powers.deploy-repo.finalize', { orgId, toolDefId });
+      const data = await client.post(ep.path, { service: ep.service, body });
+      printSuccess(`Power finalized: agent "${data.agent_id}" (tool ${data.tool_id}).`);
+      formatDetail(data, { format: program.opts().output });
+    });
+
+  // ── powers update (redeploy at a new ref) ──────────────────────────────────
+
+  powers
+    .command('update')
+    .description('Redeploy a hosted-repo power at a new git ref (branch/tag/commit)')
+    .argument('<toolDefId>', 'tool definition ID')
+    .requiredOption('--repo-ref <ref>', 'git ref to build, e.g. HEAD or a commit SHA')
+    .action(async (toolDefId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('powers.deploy-repo.update', { orgId, toolDefId });
+      const data = await client.post(ep.path, { service: ep.service, body: { repo_ref: options.repoRef } });
+      printSuccess(`Update build started for ${toolDefId} at ref "${data.repo_ref}" (build_state=${data.build_state}).`);
+      formatDetail(data, { format: program.opts().output });
+    });
+
+  // ── powers archive / restore ────────────────────────────────────────────────
+
+  powers
+    .command('archive')
+    .description('Archive a hosted-repo power (disables it without deleting any rows)')
+    .argument('<toolDefId>', 'tool definition ID')
+    .action(async (toolDefId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('powers.deploy-repo.archive', { orgId, toolDefId });
+      const data = await client.post(ep.path, { service: ep.service });
+      printSuccess('Power archived.');
+      formatDetail(data, { format: program.opts().output });
+    });
+
+  powers
+    .command('restore')
+    .description('Restore a previously archived hosted-repo power')
+    .argument('<toolDefId>', 'tool definition ID')
+    .action(async (toolDefId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('powers.deploy-repo.restore', { orgId, toolDefId });
+      const data = await client.post(ep.path, { service: ep.service });
+      printSuccess('Power restored.');
+      formatDetail(data, { format: program.opts().output });
+    });
+
+  // ── powers config ───────────────────────────────────────────────────────────
+
+  powers
+    .command('config')
+    .description('Update env vars and/or agent persona for a hosted-repo power without rebuilding')
+    .argument('<toolDefId>', 'tool definition ID')
+    .option('--env <key=value>', 'env var to set/rotate (repeatable)', collectEnvVar, [])
+    .option('--name <name>', 'new agent display name')
+    .option('--description <text>', 'new agent description')
+    .option('--icon <icon>', 'new agent icon')
+    .option('--system-prompt-additions <text>', 'new system prompt additions')
+    .action(async (toolDefId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+
+      const body = {};
+      if (options.env && options.env.length > 0) body.env_vars = options.env;
+      const persona = buildPersona(options);
+      if (Object.keys(persona).length > 0) body.persona = persona;
+
+      if (!body.env_vars && !body.persona) {
+        throw new Error('Specify at least one of --env or a persona field (--name/--description/--icon/--system-prompt-additions).');
+      }
+
+      const ep = resolveEndpoint('powers.deploy-repo.config', { orgId, toolDefId });
+      const data = await client.patch(ep.path, { service: ep.service, body });
+      printSuccess('Power config updated.');
+      formatDetail(data, { format: program.opts().output });
+    });
+
+  // ── powers delete ───────────────────────────────────────────────────────────
+
+  powers
+    .command('delete')
+    .description('Permanently destroy a hosted-repo power (revokes agent, deletes credentials)')
+    .argument('<toolDefId>', 'tool definition ID')
+    .option('--force', 'skip confirmation')
+    .action(async (toolDefId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+
+      if (!options.force && !program.opts().yes) {
+        const ok = await confirmOrSkip(`Permanently destroy power ${toolDefId}? This retires its agent and deletes its credentials. This cannot be undone.`);
+        if (!ok) { printInfo('Cancelled.'); return; }
+      }
+
+      const ep = resolveEndpoint('powers.deploy-repo.delete', { orgId, toolDefId });
+      const data = await client.delete(ep.path, { service: ep.service, query: { confirm: 'true' } });
+      printSuccess('Power deleted.');
+      formatDetail(data, { format: program.opts().output });
+    });
+}

package/lib/commands/presence.js

@@ -0,0 +1,89 @@
+/**
+ * `quox presence [who]` / `quox presence set present|away|sleeping`: PRESENCE (owner 2026-10-16).
+ * A human says they are not at their terminal (/afk, /sleep in quox do the same). Sessions and agents
+ * read it so they stop waiting on approvals, which still queue normally: nothing is ever auto-approved.
+ * Collector routes GET/PUT /api/v1/presence; the org is the caller's, only a human login sets its own.
+ */
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+
+const STATES = ['present', 'away', 'sleeping'];
+
+function stamp(iso) {
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? String(iso || '') : `${d.toISOString().slice(0, 10)} ${d.toISOString().slice(11, 16)} UTC`;
+}
+
+/** One plain line for a presence record. */
+export function presenceText(p) {
+  if (!p || !p.away) return `${p?.who || 'they'}: present`;
+  const note = p.note ? `, "${p.note}"` : '';
+  return `${p.who}: ${p.auto ? 'away (idle)' : p.state} since ${stamp(p.since)}${note} (approvals will queue)`;
+}
+
+/** The fields an approval request reports, from GET /api/v1/presence. */
+export function approvalPresenceFields(list) {
+  const away = (list && Array.isArray(list.presence) ? list.presence : []).filter((p) => p && p.away);
+  if (!away.length) return { owner_away: false };
+  const p = away.find((x) => x.who === 'owner') || away[0];
+  return { owner_away: true, owner_away_since: p.since, owner_presence: p.state, owner_away_notice: list.notice || presenceText(p) };
+}
+
+/** Read the org's presence; null on any failure (a presence read never fails the caller). */
+export async function readPresence(client, orgId) {
+  try {
+    const ep = resolveEndpoint('presence.list');
+    return await client.get(ep.path, { service: ep.service, query: orgId ? { org_id: orgId } : undefined, retries: 0, timeout: 5000 });
+  } catch { return null; }
+}
+
+export function registerPresenceCommands(program, { client, auth }) {
+  const pr = program
+    .command('presence')
+    .description('Is a person at their terminal? With no name: everyone with presence on record. When someone is away, approvals queue; work on something else')
+    .argument('[who]', 'user id, email, email name, "owner" or "me"')
+    .action(async (who) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const json = program.opts().output === 'json';
+      if (who) {
+        const ep = resolveEndpoint('presence.get', { who });
+        const d = await client.get(ep.path, { service: ep.service, query: { org_id: orgId } });
+        if (json) { console.log(JSON.stringify(d, null, 2)); return; }
+        console.log(presenceText(d.presence));
+        return;
+      }
+      const ep = resolveEndpoint('presence.list');
+      const d = await client.get(ep.path, { service: ep.service, query: { org_id: orgId } });
+      if (json) { console.log(JSON.stringify(d, null, 2)); return; }
+      const list = Array.isArray(d.presence) ? d.presence : [];
+      if (!list.some((p) => p.away)) console.log('Everyone is present: nobody has marked themselves away.');
+      for (const p of list) console.log(presenceText(p));
+    });
+
+  pr
+    .command('set')
+    .description('Say where you are: present, away or sleeping (a human login only). Same as /afk, /sleep, /back in quox')
+    .argument('<state>', 'present | away | sleeping')
+    .option('--note <text>', 'a short note sessions will see ("school run")')
+    .option('--slots <list>', 'your own window slots, comma separated (hitl and triage-q always count)')
+    .option('--auto-away <minutes>', 'read as away after this many idle minutes; "off" to disable (default off)')
+    .action(async (state, options) => {
+      if (!STATES.includes(state)) throw new Error('state must be present, away or sleeping');
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = { state };
+      if (options.note !== undefined) body.note = options.note;
+      if (options.slots) body.slots = String(options.slots).split(',').map((s) => s.trim()).filter(Boolean);
+      if (options.autoAway !== undefined) {
+        const off = /^(off|0|no)$/i.test(String(options.autoAway));
+        const n = Number(options.autoAway);
+        if (!off && (!Number.isInteger(n) || n < 1 || n > 1440)) throw new Error('--auto-away is minutes (1 to 1440) or off');
+        body.auto_away_minutes = off ? 0 : n;
+      }
+      const ep = resolveEndpoint('presence.set');
+      const d = await client.put(ep.path, { service: ep.service, body, query: { org_id: orgId } });
+      if (program.opts().output === 'json') { console.log(JSON.stringify(d, null, 2)); return; }
+      console.log(presenceText(d.presence));
+    });
+}