quoxcli 0.0.0-stage → 0.3.1

package/lib/commands/contactsSelftest.js

@@ -0,0 +1,132 @@
+/**
+ * `quox contacts selftest [--agent]`: drives the ContactsQ READ path against a dedicated demo
+ * contact and prints a pass/fail table. Never dials, sends or leases context (those file
+ * approvals). With --agent the same checks run through the attached agent's tool scope
+ * (POST /api/v1/tools/execute with the attach token, exactly like `quox agent exec`).
+ */
+
+import { QuoxApiError, QuoxError } from '../core/errors.js';
+import { line as glyphLine, printEvent } from '../core/quoxglyph.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { ensureFreshAttachToken, execResultFailed } from './agentAttach.js';
+
+export const DEMO_NAME = 'ContactsQ Selftest (demo)';
+export const DEMO_PHONE = '+44 7911 123000';
+export const DEMO_EMAIL = 'selftest@example.com';
+export const DEMO_TAG = 'selftest';
+const AGENT_ID = 'contactsq';
+
+const errText = (e) => (e instanceof QuoxApiError ? `${e.status} ${(e.body && e.body.error) || e.message}` : (e && e.message) || String(e));
+
+/** Find the demo contact or create it (human path). Idempotent. */
+export async function ensureDemoContact(client) {
+  const list = resolveEndpoint('contactsq.contacts.list');
+  const found = await client.get(list.path, { service: list.service, query: { q: 'Selftest', limit: 50 } });
+  const hit = (found.contacts || []).find((c) => c.display_name === DEMO_NAME);
+  if (hit) return { id: hit.id, created: false };
+  const create = resolveEndpoint('contactsq.contacts.create');
+  const made = await client.post(create.path, {
+    service: create.service,
+    body: { display_name: DEMO_NAME, identifiers: [{ channel: 'phone', value: DEMO_PHONE, is_primary: true }, { channel: 'email', value: DEMO_EMAIL, is_primary: true }] },
+  });
+  const id = made.contact && made.contact.id;
+  if (!id) throw new QuoxError('Could not create the selftest demo contact.', 1);
+  const upd = resolveEndpoint('contactsq.contacts.update', { id });
+  // Tagging is a human edit: an attached agent creates the demo contact but may not tag it (403 human_required).
+  // The tag is a convenience for people browsing the book, so a refusal here never fails the selftest.
+  try {
+    await client.put(upd.path, { service: upd.service, body: { tags: [DEMO_TAG] } });
+  } catch (e) {
+    if (!(e && (e.status === 403 || e.statusCode === 403))) throw e;
+  }
+  return { id, created: true };
+}
+
+/** Direct (human) transport: the governed HTTP routes. */
+function directOps(client, id) {
+  const get = (key, params, query) => { const ep = resolveEndpoint(key, params); return client.get(ep.path, { service: ep.service, query }); };
+  const post = (key, params, body) => { const ep = resolveEndpoint(key, params); return client.post(ep.path, { service: ep.service, body }); };
+  return {
+    search: (q) => get('contactsq.search', {}, { q }),
+    find: (q) => get('contactsq.contacts.list', {}, { q }),
+    resolve: (channel, value) => post('contactsq.resolve', {}, { channel, value }),
+    // No HTTP route for best_channel: the policy check is the same engine, per channel.
+    best_channel: async () => {
+      const out = [];
+      for (const channel of ['voice', 'email']) {
+        const r = await post('contactsq.policy', { id }, { purpose: 'service', channel });
+        out.push({ channel, decision: r.decision || (r.policy && r.policy.decision) || null });
+      }
+      return { alternatives: out };
+    },
+    timeline: () => get('contactsq.timeline', { id }, {}),
+    log: () => post('contactsq.touchpoints.add', { id }, { surface: 'manual', direction: 'internal', outcome: 'selftest' }),
+    brief: () => get('contactsq.brief', {}, {}),
+  };
+}
+
+/** Agent transport: the attached agent's own tool scope through /api/v1/tools/execute. */
+async function agentOps(client, id, orgId) {
+  const token = await ensureFreshAttachToken(client, AGENT_ID);
+  const ep = resolveEndpoint('v1.tools.execute');
+  const exec = async (tool, input) => {
+    let data;
+    try {
+      data = await client.post(ep.path, { service: ep.service, noAuth: true, headers: { Authorization: `Bearer ${token}` }, body: { tool_name: tool, input, org_id: orgId } });
+    } catch (e) {
+      if (e instanceof QuoxApiError && (e.status === 401 || e.status === 403)) {
+        throw new Error(`${tool}: attach token for "${AGENT_ID}" refused (${e.status}). Re-attach with \`quox agent attach ${AGENT_ID}\`.`);
+      }
+      throw e;
+    }
+    // Tool envelopes vary: unwrap { result } if present, then require success.
+    const res = data && typeof data.result === 'object' && data.result ? data.result : data;
+    if (execResultFailed(res) || execResultFailed(data)) throw new Error(`${tool}: ${res.error || data.error || 'tool reported failure'}`);
+    return res;
+  };
+  return {
+    search: (q) => exec('contacts_search', { q }),
+    find: (q) => exec('contacts_find', { q }),
+    resolve: (channel, value) => exec('contacts_resolve', { channel, value }),
+    best_channel: () => exec('contacts_best_channel', { contact_id: id }),
+    timeline: () => exec('contacts_timeline', { contact_id: id }),
+    log: () => exec('contacts_log_touchpoint', { contact_id: id, surface: 'manual', direction: 'internal', outcome: 'selftest' }),
+    brief: () => exec('contacts_brief', {}),
+  };
+}
+
+const idsOf = (r) => [...(r.candidates || []), ...(r.contacts || [])].map((c) => c.id);
+
+/** The checks, transport-agnostic. Each returns a short result string or throws. */
+export function buildChecks(ops, id) {
+  return [
+    ['search', async () => { const r = await ops.search('ContactsQ Selftest'); if (!idsOf(r).includes(id)) throw new Error('demo contact not in results'); return `${idsOf(r).length} hit(s)`; }],
+    ['search (sound-alike)', async () => { const r = await ops.search('Selftast'); if (!idsOf(r).includes(id)) throw new Error('sound-alike did not reach the demo contact'); return 'Selftast -> Selftest'; }],
+    ['find', async () => { const r = await ops.find('Selftest'); if (!idsOf(r).includes(id)) throw new Error('demo contact not found'); return `${idsOf(r).length} hit(s)`; }],
+    ['resolve by email', async () => { const r = await ops.resolve('email', DEMO_EMAIL); if (!r.match || r.match.id !== id) throw new Error('email did not resolve to the demo contact'); return 'matched'; }],
+    ['best_channel', async () => { const r = await ops.best_channel(); const n = (r.alternatives || []).length; if (!n) throw new Error('no channel evaluation returned'); return r.channel ? `chose ${r.channel}` : `${n} evaluated`; }],
+    ['timeline', async () => { const r = await ops.timeline(); if (!Array.isArray(r.timeline)) throw new Error('no timeline array'); return `${r.timeline.length} entr(ies)`; }],
+    ['log touchpoint', async () => { const r = await ops.log(); const t = r.touchpoint || r; if (!t.id) throw new Error('no touchpoint id returned'); return t.id; }],
+    ['brief', async () => { const r = await ops.brief(); if (typeof r.candidates_to_review !== 'number' || !Array.isArray(r.sync)) throw new Error('brief shape wrong'); return `${r.candidates_to_review} candidates, ${r.duplicates} dupes`; }],
+  ];
+}
+
+export async function runSelftest({ client, auth, program, options, orgId, print = console.log }) {
+  auth.requireAuth();
+  const demo = await ensureDemoContact(client);
+  const mode = options.agent ? 'agent' : 'direct';
+  const ops = options.agent ? await agentOps(client, demo.id, orgId) : directOps(client, demo.id);
+  const rows = [];
+  for (const [name, fn] of buildChecks(ops, demo.id)) {
+    try { rows.push({ check: name, ok: true, detail: await fn() }); } catch (e) { rows.push({ check: name, ok: false, detail: errText(e) }); }
+  }
+  const failed = rows.filter((r) => !r.ok).length;
+  if (program.opts().output === 'json') {
+    print(JSON.stringify({ mode, demo_contact: demo.id, created: demo.created, passed: rows.length - failed, failed, checks: rows }, null, 2));
+  } else {
+    for (const r of rows) print(`${r.ok ? '✔' : '✖'} ${r.check.padEnd(22)} ${r.detail}`);
+    printEvent(glyphLine('contactsq', `selftest (${mode})`, { result: `${rows.length - failed}/${rows.length} passed`, status: failed ? 'fail' : 'ok' }));
+  }
+  if (failed) process.exitCode = 1;
+  return { rows, failed };
+}

package/lib/commands/conversation.js

@@ -0,0 +1,105 @@
+/**
+ * Conversation commands
+ *
+ * quox conversation list|get|search|stats
+ */
+
+import { formatOutput, formatDetail } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function registerConversationCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const conv = program
+    .command('conversation')
+    .description('Manage conversations');
+
+  conv
+    .command('list')
+    .description('List your chat conversations (newest first); --archive lists the imported conversation archive')
+    .option('--limit <n>', 'Max results', '20')
+    .option('--offset <n>', 'Skip results (archive only)', '0')
+    .option('--archive', 'list the imported conversation archive instead of chat conversations')
+    .action(async (opts) => {
+      auth.requireAuth();
+      if (!opts.archive) {
+        const ep = resolveEndpoint('conversations.chat.list');
+        const data = await client.get(ep.path, { service: ep.service, query: { limit: opts.limit } });
+        const rows = data.conversations || [];
+        formatOutput({
+          columns: ['id', 'title', 'turns', 'agent', 'updated_at'],
+          headers: ['ID', 'Title', 'Turns', 'Agent', 'Updated'],
+          rows: rows.map((c) => ({
+            id: c.id,
+            title: (c.title || 'Untitled').slice(0, 50),
+            turns: c.turn_count ?? 0,
+            agent: c.agent || '-',
+            updated_at: c.updated_at ? new Date(c.updated_at).toLocaleString() : '-',
+          })),
+        }, { format: program.opts().output });
+        return;
+      }
+      const query = { limit: opts.limit, offset: opts.offset };
+      const data = await client.get(resolveEndpoint('conversations.list').path, { service: resolveEndpoint('conversations.list').service, query });
+      const conversations = data.conversations || data || [];
+      formatOutput({
+        columns: ['id', 'title', 'messages', 'created_at'],
+        headers: ['ID', 'Title', 'Messages', 'Created'],
+        rows: conversations.map(c => ({
+          id: c.id,
+          title: (c.title || 'Untitled').slice(0, 50),
+          messages: c.message_count || c.messages?.length || 0,
+          created_at: c.created_at ? new Date(c.created_at).toLocaleDateString() : '-',
+        })),
+      }, { format: program.opts().output });
+    });
+
+  conv
+    .command('get')
+    .argument('<id>', 'conversation ID')
+    .description('Show a chat conversation\'s turns; --archive reads the imported conversation archive')
+    .option('--limit <n>', 'Max turns (chat only)', '50')
+    .option('--archive', 'read the imported conversation archive instead of chat conversations')
+    .action(async (id, opts) => {
+      auth.requireAuth();
+      if (!opts.archive) {
+        const ep = resolveEndpoint('conversations.chat.turns', { id });
+        const data = await client.get(ep.path, { service: ep.service, query: { limit: opts.limit } });
+        const turns = data.turns || [];
+        formatOutput({
+          columns: ['ts', 'role', 'content'],
+          headers: ['Time', 'Role', 'Content'],
+          rows: turns.map((t) => ({ ts: t.ts ? new Date(t.ts).toLocaleString() : '-', role: t.role, content: t.content })),
+        }, { format: program.opts().output });
+        return;
+      }
+      const data = await client.get(resolveEndpoint('conversations.get', { id }).path, { service: resolveEndpoint('conversations.get', { id }).service });
+      formatDetail(data.conversation || data, { format: program.opts().output, title: 'Conversation' });
+    });
+
+  conv
+    .command('search')
+    .description('Search conversations')
+    .requiredOption('--query <q>', 'Search query')
+    .option('--limit <n>', 'Max results', '10')
+    .action(async (opts) => {
+      auth.requireAuth();
+      const query = { query: opts.query, limit: opts.limit };
+      const data = await client.get(resolveEndpoint('conversations.search.list').path, { service: resolveEndpoint('conversations.search.list').service, query });
+      const results = data.results || data || [];
+      formatOutput({
+        columns: ['id', 'title', 'score'],
+        headers: ['ID', 'Title', 'Score'],
+        rows: results.map(r => ({ id: r.id, title: (r.title || 'Untitled').slice(0, 50), score: r.score != null ? r.score.toFixed(2) : '-' })),
+      }, { format: program.opts().output });
+    });
+
+  conv
+    .command('stats')
+    .description('Conversation statistics')
+    .action(async () => {
+      auth.requireAuth();
+      const data = await client.get(resolveEndpoint('conversations.stats.list').path, { service: resolveEndpoint('conversations.stats.list').service });
+      formatDetail(data.stats || data, { format: program.opts().output, title: 'Conversation Stats' });
+    });
+}

package/lib/commands/dashboard.js

@@ -0,0 +1,43 @@
+/**
+ * `quox dashboard [page]`: open the web dashboard already signed in, via a one-time link
+ * (10 minutes, single use). Same engine as /dashboard in the Quox client (lib/quoxon/slash/dashboard.js).
+ * Over SSH it prints the link and does not open a browser. The link is a credential: it is printed
+ * to the terminal only, never logged.
+ */
+import { resolveEndpoint } from '../api/endpoints.js';
+import { runDashboard, dashboardLines, PAGES } from '../quoxon/slash/dashboard.js';
+import { supportsHyperlinks } from '../quoxon/markdown.js';
+import { resolveDashboardBase, detectLanIp } from '../quoxon/hostUrls.js';
+import { loadJourney } from '../quoxon/onboarding/journey.js';
+
+/**
+ * Z2H-R4: the address to print, resolved exactly like /dashboard in the Quox client (api.js
+ * dashboardBase): server app URL, else a non-loopback profile URL, else the install finale's URL,
+ * else this machine's LAN IP. Over SSH a localhost link only works on the Quox box itself.
+ */
+export async function commandDashboardBase({ client, config, journey = loadJourney, lanIp = detectLanIp() } = {}) {
+  const profileUrl = config.getActiveProfile?.()?.url || config.getBaseUrl();
+  let serverApp = null;
+  try { const ep = resolveEndpoint('admin.instance.basics.get'); const r = await client.get(ep.path, { service: ep.service, retries: 0 }); serverApp = r?.effective?.appBaseUrl || null; } catch { serverApp = null; }
+  let journeyUrl = null; try { journeyUrl = journey()?.dashboardUrl || null; } catch { journeyUrl = null; }
+  return resolveDashboardBase({ serverApp, profileUrl, journeyUrl, lanIp }).url;
+}
+
+export function registerDashboardCommands(program, ctx) {
+  const { client, auth, config, lanIp = detectLanIp, journey = loadJourney } = ctx;
+  program
+    .command('dashboard')
+    .description(`Open the web dashboard signed in (one-time link, 10 minutes). Pages: ${Object.keys(PAGES).join(', ')}`)
+    .argument('[page]', 'dashboard page to land on')
+    .action(async (page) => {
+      auth.requireAuth();
+      const baseUrl = await commandDashboardBase({ client, config, journey, lanIp: lanIp() });
+      const r = await runDashboard({ page, baseUrl, mint: () => { const ep = resolveEndpoint('auth.login-link'); return client.post(ep.path, { service: ep.service, body: {}, retries: 0 }); } });
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify({ kind: r.kind, url: r.url ?? null, opened: Boolean(r.opened), remote: Boolean(r.remote), error: r.error ?? null }, null, 2));
+      } else {
+        for (const l of dashboardLines(r, { hyperlinks: supportsHyperlinks() })) console.log(l.text);
+      }
+      if (r.kind === 'error') process.exitCode = 1;
+    });
+}

package/lib/commands/department.js

@@ -0,0 +1,96 @@
+/**
+ * Department commands: CRUD
+ */
+
+import { formatOutput, printSuccess } from '../core/output.js';
+import { resolveOrgId } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function registerDepartmentCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const dept = program
+    .command('department')
+    .description('Manage departments within divisions');
+
+  dept
+    .command('list')
+    .description('List departments (all divisions unless --division; division ids: quox org divisions list)')
+    .option('--division <divId>', 'only this division')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const listFor = async (division) => {
+        const ep = resolveEndpoint('divisions.departments.list', { orgId, division });
+        const data = await client.get(ep.path, { service: ep.service });
+        return data.departments || data || [];
+      };
+      if (options.division) {
+        formatOutput({
+          columns: ['id', 'name', 'description', 'created_at'],
+          headers: ['ID', 'Name', 'Description', 'Created'],
+          rows: await listFor(options.division),
+        }, { format: program.opts().output });
+        return;
+      }
+      // quox#922: no --division lists every division's departments, so the read
+      // needs no id the department group cannot show.
+      const divEp = resolveEndpoint('divisions.list', { orgId });
+      const divData = await client.get(divEp.path, { service: divEp.service });
+      const divisions = divData.divisions || divData || [];
+      const rows = [];
+      for (const d of divisions) {
+        for (const dept of await listFor(d.id)) rows.push({ ...dept, division: d.name || d.id });
+      }
+      formatOutput({
+        columns: ['id', 'name', 'division', 'description', 'created_at'],
+        headers: ['ID', 'Name', 'Division', 'Description', 'Created'],
+        rows,
+      }, { format: program.opts().output, emptyMessage: 'No departments.' });
+    });
+
+  dept
+    .command('create')
+    .description('Create a department')
+    .requiredOption('--division <divId>', 'division ID')
+    .requiredOption('--name <name>', 'department name')
+    .option('--description <desc>', 'description')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      await client.post(resolveEndpoint('divisions.departments.create', { orgId, division: options.division }).path, {
+        service: resolveEndpoint('divisions.departments.create', { orgId, division: options.division }).service,
+        body: { name: options.name, description: options.description },
+      });
+      printSuccess(`Department "${options.name}" created.`);
+    });
+
+  dept
+    .command('update')
+    .description('Update a department')
+    .argument('<deptId>', 'department ID')
+    .requiredOption('--division <divId>', 'division ID')
+    .option('--name <name>', 'new name')
+    .option('--description <desc>', 'new description')
+    .action(async (deptId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = {};
+      if (options.name) body.name = options.name;
+      if (options.description) body.description = options.description;
+      await client.patch(resolveEndpoint('divisions.departments.update', { orgId, division: options.division, deptId }).path, { service: resolveEndpoint('divisions.departments.update', { orgId, division: options.division, deptId }).service, body });
+      printSuccess('Department updated.');
+    });
+
+  dept
+    .command('delete')
+    .description('Delete a department')
+    .argument('<deptId>', 'department ID')
+    .requiredOption('--division <divId>', 'division ID')
+    .action(async (deptId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      await client.delete(resolveEndpoint('divisions.departments.delete', { orgId, division: options.division, deptId }).path, { service: resolveEndpoint('divisions.departments.delete', { orgId, division: options.division, deptId }).service });
+      printSuccess('Department deleted.');
+    });
+}