quoxcli 0.2.0 → 0.4.0

package/lib/commands/ask.js

@@ -0,0 +1,146 @@
+/**
+ * `quox ask`: a session puts a fork in front of a human through the Approvals inbox (one inbox item, kind decision).
+ * Who is asking, what, why, the options, the recommendation and the expiry travel with it, so ONE HITL session
+ * can answer for twenty terminals. Not an approval of an action: no step-up PIN unless --high-risk.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+import { readPresence, approvalPresenceFields } from './presence.js';
+import { toRepoRelative, LOOSENING_HINT } from '../core/repoPath.js';
+import { parseOptions, parseDuration, YN_OPTIONS, waitForDecision, EXIT_NO_ANSWER } from '../core/askDecision.js';
+
+function heldSlotFor(session) {
+  try {
+    const all = JSON.parse(readFileSync(join(homedir(), '.quox', 'held-slots.json'), 'utf8'));
+    const want = String(session || '').toLowerCase();
+    return Object.keys(all).find((k) => String(all[k]?.session || '').toLowerCase() === want) || null;
+  } catch { return null; }
+}
+
+export function registerAskCommands(program, { client, auth }) {
+  const err = (s) => process.stderr.write(`${s}\n`);
+
+  async function waitAndPrint(orgId, id, { timeoutSec = null } = {}) {
+    const r = await waitForDecision({
+      poll: (w) => { const ep = resolveEndpoint('inbox.decision.get', { orgId, id }); return client.get(ep.path, { service: ep.service, query: { wait: w }, timeout: (w + 15) * 1000, retries: 0 }); },
+      log: err,
+      maxWaitMs: timeoutSec != null ? timeoutSec * 1000 : null,
+    });
+    if (r.stdout) console.log(r.stdout);
+    process.exitCode = r.code;
+    return r;
+  }
+
+  const ask = program
+    .command('ask')
+    .description('Ask a human a question through the Approvals inbox: who asks, what, why, the options. Use this instead of asking in your own terminal')
+    .option('--session <name>', 'which session is asking (default: $QUOX_SESSION)')
+    .option('--title <text>', 'what you are asking, one line')
+    .option('--why <text>', 'a simple why: what the human needs to know to decide')
+    .option('--justify <text>', 'for a loosening (a check made easier to pass): why it is safe, in plain words; the card shows it on its JUSTIFY line and defaults to No without one')
+    .option('--options <list>', 'the choices: "a: Ship now|b: Wait for review|c: Drop it"')
+    .option('--yn', 'shorthand for a yes/no question (options y and n)')
+    .option('--default <key>', 'the option you would take if nobody answers (shown, never applied for you)')
+    .option('--recommend <key>', 'the option you recommend')
+    .option('--expires <dur>', 'how long it stays open: 30m, 2h, 1d (default 24h, max 30d)')
+    .option('--slot <name>', 'your slot, so the answer is also posted there (default: found from held slots)')
+    .option('--agent <name>', 'the agent asking, when it is an agent rather than a session')
+    .option('--high-risk', 'the answer needs the human step-up PIN')
+    .option('--wait', 'block until answered; prints the chosen option key (and any note) on stdout, exits 2 on expiry or deny')
+    .option('--timeout <dur>', 'with --wait: stop waiting after this long (the question stays open)')
+    .action((options) => fileAsk(options));
+
+  async function fileAsk(options) {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const session = options.session || process.env.QUOX_SESSION;
+      if (!session) throw new Error('say which session is asking: --session <NAME>');
+      if (!options.title) throw new Error('say what you are asking: --title "<what>"');
+      if (options.yn && options.options) throw new Error('use --yn or --options, not both');
+      if (!options.yn && !options.options) throw new Error('give the choices: --options "a: Ship now|b: Wait" (or --yn)');
+      // QUOXON 2026-10-17: a high-risk ask (a loosening, anything the owner must PIN) carries a plain justification
+      // 2026-10-19: three PIN approvals were wasted on loosening asks filed without --high-risk or with unusable paths
+      if (!options.highRisk && /^\s*approve\s+(?:loosening|test)/i.test(options.title)) { err(`A test-edit approval must go through the loosening verb, which sets --high-risk and repo-relative paths for you:\n  ${LOOSENING_HINT}`); process.exitCode = 2; return; }
+      if (options.highRisk && !String(options.justify || '').trim()) { err('High-risk asks need --justify "<2-3 plain lines the owner can judge>"'); process.exitCode = 2; return; }
+      const opts = options.yn ? YN_OPTIONS : parseOptions(options.options);
+      const body = {
+        session, title: options.title, why: options.why, options: opts,
+        ...(options.justify ? { justification: options.justify } : {}),
+        default: options.default, recommend: options.recommend,
+        ...(options.expires ? { expires_in_seconds: parseDuration(options.expires) } : {}),
+        high_risk: Boolean(options.highRisk),
+        slot: options.slot || heldSlotFor(session) || undefined,
+        profile: program.opts().profile || process.env.QUOX_PROFILE || undefined,
+        agent: options.agent,
+      };
+      const ep = resolveEndpoint('inbox.decision.create', { orgId });
+      const data = await client.post(ep.path, { service: ep.service, body });
+      // PRESENCE (owner 2026-10-16): say now whether the human is away, so this session can work on
+      // something else instead of waiting. The question is filed and queued exactly as before.
+      const presence = approvalPresenceFields(await readPresence(client, orgId));
+      const d = { ...data.decision, ...presence };
+      if (program.opts().output === 'json' && !options.wait) { console.log(JSON.stringify(d, null, 2)); return; }
+      err(`asked: ${d.id} (${session}: ${d.title}); it shows in /approvals${d.expires_at ? `, open until ${d.expires_at}` : ''}`);
+      if (presence.owner_away) err(`${presence.owner_away_notice}. Expect a wait: work on something else meanwhile.`);
+      if (!options.wait) { console.log(d.id); return; }
+      await waitAndPrint(orgId, d.id, { timeoutSec: options.timeout ? parseDuration(options.timeout) : null });
+  }
+
+  ask
+    .command('loosening')
+    .description('Ask a human to approve edits to test files (a check made easier to pass). Files a yes/no, high-risk (PIN) ask with repo-relative paths')
+    .option('--paths <files...>', 'every test file the commit edits (absolute, worktree or repo-relative: all are normalised)')
+    .option('--justify <text>', 'why it is safe, in plain words (required)')
+    .option('--why <text>', 'detail: the findings, before and after lines')
+    .option('--recommend <y|n>', 'your advice for the card: y or n (shown as the recommendation)')
+    .option('--session <name>', 'which session is asking (default: $QUOX_SESSION)')
+    .option('--slot <name>', 'your slot')
+    .option('--expires <dur>', 'how long it stays open')
+    .option('--wait', 'block until answered')
+    .option('--timeout <dur>', 'with --wait: stop waiting after this long')
+    .action(async (subOptions) => {
+      // commander lets the parent `ask` swallow flags it shares with this verb (--justify, --why, --session...), so merge both
+      const options = { ...ask.opts(), ...Object.fromEntries(Object.entries(subOptions).filter(([, v]) => v !== undefined)) };
+      if (!String(options.justify || '').trim()) { err('say why it is safe: --justify "<plain words>"'); process.exitCode = 2; return; }
+      if (!options.recommend) err('tip: add --recommend y|n so the card shows your advice');
+      const raw = [].concat(options.paths || []).flatMap((x) => String(x).split(',')).map((x) => x.trim()).filter(Boolean);
+      let root;
+      try { root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim(); } catch { root = process.cwd(); }
+      const paths = [...new Set(raw.map(toRepoRelative))];
+      const missing = paths.filter((p) => !p || !existsSync(join(root, p)));
+      if (!paths.length || missing.length) { err(`not found in this repo (${root}): ${missing.join(', ') || '(no paths)'}. Run from the worktree and name files that exist.`); process.exitCode = 2; return; }
+      // 2026-10-19: the server truncates long titles, and the attestation names only paths found in title+body,
+      // so a 7-file ask covered 3. Every path also goes in the body.
+      const files = `Files (${paths.length}):\n${paths.map((p) => `- ${p}`).join('\n')}`;
+      await fileAsk({ ...options, title: `Approve test edits: ${paths.join(' ')}`, why: options.why ? `${files}\n\n${options.why}` : files, yn: true, highRisk: true, justify: options.justify, recommend: options.recommend });
+    });
+
+  ask
+    .command('status')
+    .description('Show where a question stands: pending, answered, denied or expired, with the answer')
+    .argument('<id>', 'the id `quox ask` printed')
+    .action(async (id) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('inbox.decision.get', { orgId, id });
+      const d = (await client.get(ep.path, { service: ep.service })).decision;
+      if (program.opts().output === 'json') { console.log(JSON.stringify(d, null, 2)); return; }
+      console.log(`${d.state}${d.answer?.option ? ` ${d.answer.option}` : ''}${d.answer?.note ? ` (${d.answer.note})` : ''}`);
+      if (d.state === 'expired' || d.state === 'denied') process.exitCode = EXIT_NO_ANSWER;
+    });
+
+  ask
+    .command('wait')
+    .description('Block until a question is answered; prints the chosen option key (and note), exits 2 on expiry or deny')
+    .argument('<id>', 'the id `quox ask` printed')
+    .option('--timeout <dur>', 'stop waiting after this long (the question stays open)')
+    .action(async (id, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      await waitAndPrint(orgId, id, { timeoutSec: options.timeout ? parseDuration(options.timeout) : null });
+    });
+}

package/lib/commands/assistant.js

@@ -5,6 +5,10 @@
 import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
 import { resolveOrgId } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { QuoxError } from '../core/errors.js';
+
+// #1049: auth routes/assistants.js DEPLOYMENT_MODES (the server is the authority).
+const DEPLOY_MODES = ['private', 'shared', 'public'];
 
 export function registerAssistantCommands(program, ctx) {
   const { client, auth } = ctx;
@@ -84,20 +88,71 @@ export function registerAssistantCommands(program, ctx) {
       printSuccess('Assistant deleted.');
     });
 
+  assistant
+    .command('publish')
+    .description('Publish a draft assistant (draft to active), so it can be deployed')
+    .argument('<assistantId>', 'assistant ID')
+    .action(async (assistantId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      // #1028: create makes a draft and deploy refuses anything not active; this is the step between.
+      const ep = resolveEndpoint('assistants.publish', { orgId, assistantId });
+      await client.post(ep.path, { service: ep.service });
+      printSuccess('Assistant published.');
+    });
+
   assistant
     .command('deploy')
-    .description('Deploy an assistant')
+    .description('Deploy an active assistant to a scope (scope ids: quox org divisions list, quox department list, quox team list)')
     .argument('<assistantId>', 'assistant ID')
-    .option('--target <target>', 'deployment target')
+    .option('--scope <scopeId>', 'scope ID to deploy to (required)')
+    .option('--target <scopeId>', 'alias for --scope')
+    .option('--mode <mode>', `${DEPLOY_MODES.join(', ')} (default shared)`)
     .action(async (assistantId, options) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
-      const body = {};
-      if (options.target) body.target = options.target;
+      // #998: the auth route requires scope_id; the CLI used to send { target }.
+      const scopeId = options.scope || options.target;
+      if (!scopeId) throw new QuoxError('assistant deploy needs --scope <scopeId>.', 1);
+      // #1049: the server's modes (auth routes/assistants.js DEPLOYMENT_MODES); refuse anything else here.
+      if (options.mode && !DEPLOY_MODES.includes(options.mode)) {
+        throw new QuoxError(`--mode must be one of: ${DEPLOY_MODES.join(', ')} (got "${options.mode}").`, 1);
+      }
+      const body = { scope_id: scopeId };
+      if (options.mode) body.mode = options.mode;
       await client.post(resolveEndpoint('assistants.deploy', { orgId, assistantId }).path, { service: resolveEndpoint('assistants.deploy', { orgId, assistantId }).service, body });
       printSuccess('Assistant deployed.');
     });
 
+  assistant
+    .command('undeploy')
+    .description('Remove a deployment of an assistant (by --deployment id, or the active one at --scope)')
+    .argument('<assistantId>', 'assistant ID')
+    .option('--deployment <deploymentId>', 'deployment ID to remove (see quox assistant get)')
+    .option('--scope <scopeId>', 'remove the active deployment at this scope')
+    .action(async (assistantId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      // #1049: a deployed assistant could not be removed from the CLI.
+      let deploymentId = options.deployment;
+      if (!deploymentId) {
+        if (!options.scope) throw new QuoxError('assistant undeploy needs --deployment <id> or --scope <scopeId>.', 1);
+        const g = resolveEndpoint('assistants.get', { orgId, assistantId });
+        const data = await client.get(g.path, { service: g.service });
+        const deps = (data && data.assistant && data.assistant.deployments) || (data && data.deployments) || [];
+        const live = deps.filter((d) => d.status === 'active');
+        const hit = live.find((d) => d.scope_id === options.scope);
+        if (!hit) {
+          const where = live.length ? live.map((d) => `${d.scope_id} (${d.id})`).join(', ') : 'nowhere';
+          throw new QuoxError(`No active deployment of ${assistantId} at scope ${options.scope}. It is deployed at: ${where}.`, 1);
+        }
+        deploymentId = hit.id;
+      }
+      const ep = resolveEndpoint('assistants.undeploy', { orgId, assistantId, deploymentId });
+      await client.delete(ep.path, { service: ep.service });
+      printSuccess(`Deployment ${deploymentId} removed.`);
+    });
+
   assistant
     .command('fork')
     .description('Fork an assistant')

package/lib/commands/auth.js

@@ -199,7 +199,9 @@ export function registerAuthCommands(program, ctx) {
     .action(async () => {
       auth.requireAuth();
       const data = await client.get(resolveEndpoint('auth.me.list').path, { service: resolveEndpoint('auth.me.list').service });
-      const authData = config.getAuth();
+      // A QUOX_TOKEN_FILE principal (the W4 builder uid) has no stored profile:
+      // render from the server's /me answer rather than crash on null.
+      const authData = config.getAuth() || {};
 
       // quox#463: resident logins carry org_id but no org_name (the
       // bootstrap has only the id), and this rendered a real membership as
@@ -245,8 +247,12 @@ export function registerAuthCommands(program, ctx) {
         org: orgDisplay,
         role: authData.org_role || 'n/a',
         mfa: data.user?.mfa_enabled ? 'enabled' : 'disabled',
+        // Z2H-3c: expires_at is the ACCESS token. With a refresh token the sign-in outlives it, so do not
+        // present it as the session ending (a fresh owner read "expires in 60m" right after logging in).
         session: authData.expires_at
-          ? `expires in ${Math.max(0, Math.round((authData.expires_at - Date.now()) / 60000))}m`
+          ? (authData.refresh_token
+            ? `active, auto-renews (token refresh in ${Math.max(0, Math.round((authData.expires_at - Date.now()) / 60000))}m)`
+            : `expires in ${Math.max(0, Math.round((authData.expires_at - Date.now()) / 60000))}m`)
           : 'unknown',
         profile: config.getActiveProfileName(),
       };

package/lib/commands/backup.js

@@ -59,14 +59,18 @@ export function registerBackupCommands(program, ctx) {
   backup
     .command('create')
     .description('Create a backup')
-    .option('--label <label>', 'backup label')
-    .option('--type <type>', 'backup type: full, incremental', 'full')
+    .option('--label <label>', 'backup label (stored as the backup name)')
+    .option('--type <type>', 'backup type: full, quick, selective', 'full')
     .option('--components <list>', 'comma-separated components to include')
     .action(async (options) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
-      const body = { type: options.type };
-      if (options.label) body.label = options.label;
+      // #1017: the server reads backup_type and name (services/auth/routes/backups.js); type/label were dropped,
+      // and a type outside the backups.backup_type CHECK would only fail later inside the server.
+      const TYPES = ['full', 'quick', 'selective'];
+      if (!TYPES.includes(options.type)) throw new Error(`--type must be one of: ${TYPES.join(', ')}`);
+      const body = { backup_type: options.type };
+      if (options.label) body.name = options.label;
       if (options.components) body.components = options.components.split(',').map(c => c.trim());
 
       const ora = (await import('ora')).default;

package/lib/commands/blog.js

@@ -0,0 +1,110 @@
+/**
+ * `quox blog draft submit|list|show|mark-published` (BLOG-DRAFT).
+ *
+ * Submit saves the draft as a NotesQ note in the blog-drafts collection and files a hand-off to
+ * the blog publisher (a line in the publisher's slot plus an inbox item). It NEVER publishes:
+ * publishing is the publisher's governed pipeline after the owner's yes. `mark-published` is the
+ * publisher-side verb that records the URL and tells the originating conversation/objective.
+ */
+
+import { readFileSync } from 'fs';
+import { formatOutput, formatDetail, printSuccess, printInfo } from '../core/output.js';
+import { line as glyphLine, printEvent } from '../core/quoxglyph.js';
+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 readBody(options, ctx) {
+  if (options.file) return readFileSync(options.file, 'utf-8');
+  if (options.stdin) {
+    const input = ctx.stdin || process.stdin;
+    let buf = '';
+    for await (const chunk of input) buf += chunk;
+    return buf;
+  }
+  return null;
+}
+
+export function registerBlogCommands(program, ctx) {
+  const { client, auth } = ctx;
+  const blog = program.command('blog').description('Blog: hand drafts to the blog publisher (never publishes)');
+  const draft = blog.command('draft').description('Blog drafts: saved as revisioned NotesQ notes in the blog-drafts collection');
+
+  draft
+    .command('submit')
+    .description('Save a draft and hand it to the blog publisher (slot + inbox). Does NOT publish.')
+    .requiredOption('--title <title>', 'post title')
+    .option('--file <path>', 'read the post markdown from a file')
+    .option('--stdin', 'read the post markdown from stdin')
+    .option('--hero <image>', 'hero image path or URL')
+    .option('--tag <tag...>', 'tag (repeatable)')
+    .option('--conversation <id>', 'originating conversation id (so its publication is reported back)')
+    .option('--objective <id>', 'originating objective id')
+    .action(async (options) => {
+      auth.requireAuth();
+      const markdown = await readBody(options, ctx);
+      if (markdown === null) throw new Error('give the post body with --file <path> or --stdin');
+      if (!markdown.trim()) throw new Error('the draft body is empty; nothing to submit');
+      const body = { title: options.title, markdown };
+      if (options.hero) body.hero = options.hero;
+      if (options.tag && options.tag.length) body.tags = options.tag;
+      if (options.conversation) body.conversation_id = options.conversation;
+      if (options.objective) body.objective_id = options.objective;
+      const ep = resolveEndpoint('blog.drafts.submit');
+      const data = await client.post(ep.path, { service: ep.service, body });
+      if (isJson(program)) return printJson(data);
+      printEvent(glyphLine('quox', `blog draft submit "${options.title}"`, `note ${data.note_id}`));
+      printSuccess(`Draft saved as note ${data.note_id} and handed to the publisher slot ${data.slot} (hand-off ${data.handoff_id}).`);
+      if (data.link) console.log(`link: ${data.link}`);
+      printInfo('Not published: nothing goes live until the publisher publishes after the owner approves.');
+    });
+
+  draft
+    .command('list')
+    .description('List blog drafts')
+    .option('--status <status>', 'draft | published')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('blog.drafts.list');
+      const data = await client.get(ep.path, { service: ep.service, query: options.status ? { status: options.status } : {} });
+      if (isJson(program)) return printJson(data);
+      const rows = (data.drafts || []).map((d) => ({ id: d.id, title: d.title, status: d.status, url: d.url || '', updated: d.updated || '' }));
+      if (!rows.length) return printInfo('No blog drafts.');
+      formatOutput({ columns: ['id', 'title', 'status', 'url', 'updated'], rows });
+    });
+
+  draft
+    .command('show')
+    .description('Show one blog draft (body and hand-off facts)')
+    .argument('<id>', 'draft (note) id')
+    .action(async (id) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('blog.drafts.get', { id });
+      const data = await client.get(ep.path, { service: ep.service });
+      if (isJson(program)) return printJson(data);
+      const d = data.draft || {};
+      const { markdown, ...facts } = d;
+      formatDetail(facts);
+      console.log('');
+      console.log(markdown || '');
+    });
+
+  draft
+    .command('mark-published')
+    .description('Publisher side: record the published URL and tell the originating conversation/objective')
+    .argument('<id>', 'draft (note) id')
+    .requiredOption('--url <url>', 'the published https URL')
+    .action(async (id, options) => {
+      auth.requireAuth();
+      if (!/^https:\/\//i.test(options.url)) throw new Error('--url must be an https URL');
+      const ep = resolveEndpoint('blog.drafts.published', { id });
+      const data = await client.post(ep.path, { service: ep.service, body: { url: options.url } });
+      if (isJson(program)) return printJson(data);
+      printSuccess(data.already ? `Draft ${id} was already marked published at ${data.url}.` : `Draft ${id} marked published at ${data.url}.`);
+      if (data.notified) {
+        const n = data.notified;
+        printInfo(`Told: ${[n.conversation_id && `conversation ${n.conversation_id}`, n.objective_id && `objective ${n.objective_id}`, n.inbox_item_id && `inbox ${n.inbox_item_id}`].filter(Boolean).join(', ') || 'inbox only'}.`);
+      }
+    });
+}