quoxcli 0.0.0-stage → 0.3.1

package/lib/commands/invites.js

@@ -0,0 +1,45 @@
+/**
+ * Invitation commands (GRIPE-712): list and accept the caller's own pending
+ * invitations without needing the emailed token.
+ */
+import { formatOutput, printSuccess } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function registerInvitesCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const invites = program.command('invites').description('Your pending organization invitations');
+
+  invites
+    .command('list')
+    .description('List pending invitations addressed to your verified email')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('invites.mine.list');
+      const data = await client.get(ep.path, { service: ep.service });
+      const rows = (data.invites || []).map(i => ({
+        id: i.id,
+        organization: i.organization?.name || i.organization?.slug || '',
+        role: i.role,
+        invited_by: i.invited_by || '',
+        expires_at: i.expires_at || '',
+      }));
+      formatOutput({
+        columns: ['id', 'organization', 'role', 'invited_by', 'expires_at'],
+        headers: ['ID', 'Organization', 'Role', 'Invited by', 'Expires'],
+        rows,
+      }, { format: program.opts().output });
+    });
+
+  invites
+    .command('accept')
+    .description('Accept a pending invitation by id (no emailed token needed)')
+    .argument('<id>', 'invitation id from `quox invites list`')
+    .action(async (id) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('invites.mine.accept', { inviteId: id });
+      const data = await client.post(ep.path, { service: ep.service, body: {} });
+      const org = data.organization;
+      printSuccess(`${data.message || 'Invite accepted'}${org?.name ? `: ${org.name}` : ''}. Run \`quox org switch ${org?.id || '<orgId>'}\` to use it.`);
+    });
+}

package/lib/commands/licence.js

@@ -0,0 +1,139 @@
+/**
+ * `quox licence` (alias `license`), GRIPE-715: governed, audited licence
+ * operations from the terminal.
+ *
+ * Phase 1 (instance-local): status reads the lease (never the key), refresh
+ * runs the renewal, seats lists/cleans band holders (dry run default).
+ *
+ * Phase 2 (owner-only vendor tooling for the quox.ai website) lives in
+ * lib/vendor/licenceOwner.js and is registered only when that file is present.
+ * lib/vendor/ is excluded from the npm package (quox#1134): the public build
+ * never carries it.
+ */
+
+import { formatOutput, formatDetail, printSuccess, printInfo, printWarning } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { QuoxValidationError } from '../core/errors.js';
+
+// quox#1134: the owner-only website verbs are vendor tooling, kept out of the published package (package.json
+// "files" excludes lib/vendor/). Present in the dev tree, absent for every npm user.
+let VENDOR_OWNER = null;
+try {
+  VENDOR_OWNER = await import('../vendor/licenceOwner.js');
+} catch (e) {
+  if (!(e?.code === 'ERR_MODULE_NOT_FOUND' && String(e?.message || '').includes('licenceOwner'))) throw e;
+}
+
+export function registerLicenceCommands(program, ctx, { owner = VENDOR_OWNER } = {}) {
+  const { client, auth } = ctx;
+  const fetchImpl = ctx.websiteFetch || globalThis.fetch;
+  const json = () => program.opts().output === 'json';
+
+  const licence = program
+    .command('licence')
+    .alias('license')
+    .description('Instance licence status, lease refresh and seat bands')
+    .action(() => { licence.help(); });
+  if (owner) licence.addHelpText('after', owner.OWNER_HELP);
+
+  licence
+    .command('status')
+    .description('Licence id, plan, lease timestamps, governed count, entitled list with seat usage')
+    .option('--plugin <id>', 'limit to one plugin')
+    .action(async (opts) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('setup.licensing.status');
+      const d = await client.get(ep.path, { service: ep.service });
+      const bands = d.org_bands || {};
+      const pick = (id) => !opts.plugin || id === opts.plugin;
+      const entitled = (d.entitlements || []).filter(pick).map((id) => {
+        const b = bands[id];
+        return { plugin: id, seats: b ? `${b.assigned_count}/${b.allowance}` : 'whole install' };
+      });
+      const out = {
+        licenses: (d.licenses || []).map((l) => ({
+          license_id: l.license_id,
+          plans: l.plans || [],
+          lease_issued_at: l.issued_at,
+          lease_expires_at: l.lease_expires_at,
+          licence_expires_at: l.expires_at,
+        })),
+        governed_count: Array.isArray(d.governed) ? d.governed.length : 0,
+        org_id: d.org_id || null,
+        entitled,
+        entitlement_errors: d.entitlement_errors || [],
+        renewal_health: d.renewal_health || null,
+      };
+      if (opts.plugin) out.governed = (d.governed || []).includes(opts.plugin);
+      if (json()) { console.log(JSON.stringify(out, null, 2)); return; }
+      formatDetail({
+        licence_id: out.licenses.map((l) => l.license_id).join(', ') || '(none)',
+        plan: out.licenses.flatMap((l) => l.plans).join(', ') || '(none)',
+        lease_issued: out.licenses.map((l) => l.lease_issued_at || '?').join(', ') || '(none)',
+        lease_expires: out.licenses.map((l) => l.lease_expires_at).join(', ') || '(none)',
+        governed: String(out.governed_count),
+        org_id: out.org_id || '(instance scoped)',
+        entitlement_errors: out.entitlement_errors.length
+          ? out.entitlement_errors.map((e) => (e.entitlement ? `${e.entitlement}: ${e.error}` : JSON.stringify(e))).join('; ')
+          : '(none)',
+      }, { title: 'Licence status' });
+      formatOutput({
+        columns: ['plugin', 'seats'],
+        headers: ['Entitled plugin', 'Seats (used/cap)'],
+        rows: entitled,
+      }, { format: program.opts().output, emptyMessage: 'No entitlements.' });
+    });
+
+  licence
+    .command('refresh')
+    .description('Renew the licence lease now; prints old to new lease timestamps and entitlement diff')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('setup.licensing.refresh');
+      const d = await client.post(ep.path, { service: ep.service, body: {} });
+      if (json()) { console.log(JSON.stringify(d, null, 2)); return; }
+      const byId = new Map((d.before || []).map((l) => [l.license_id, l]));
+      for (const l of d.after || []) {
+        const old = byId.get(l.license_id);
+        printInfo(`${l.license_id}: lease expires ${old ? old.lease_expires_at : '(new)'} -> ${l.lease_expires_at}`);
+      }
+      for (const r of d.results || []) printInfo(`${r.license_id}: ${r.action}${r.reason ? ` (${r.reason})` : ''}`);
+      const diff = d.entitlement_diff || { added: [], removed: [] };
+      printInfo(`entitlements added: ${diff.added.join(', ') || '(none)'}`);
+      printInfo(`entitlements removed: ${diff.removed.join(', ') || '(none)'}`);
+      printSuccess('Lease refresh complete.');
+    });
+
+  licence
+    .command('seats')
+    .description('List a plugin band holders; --release-dead frees non-live holders (dry run unless --yes)')
+    .argument('<pluginId>', 'plugin id, e.g. notesq')
+    .option('--release-dead', 'release holders that are not live orgs (deleted orgs, user: ids)')
+    .option('--yes', 'actually release (otherwise dry run)')
+    .action(async (pluginId, opts) => {
+      auth.requireAuth();
+      const lep = resolveEndpoint('setup.licensing.seats.list', { pluginId });
+      const list = await client.get(lep.path, { service: lep.service });
+      let rel = null;
+      if (opts.releaseDead) {
+        const rep = resolveEndpoint('setup.licensing.seats.releaseDead', { pluginId });
+        rel = await client.post(rep.path, { service: rep.service, body: { dry_run: !opts.yes } });
+      }
+      if (json()) { console.log(JSON.stringify({ ...list, release: rel }, null, 2)); return; }
+      printInfo(`${pluginId}: ${list.holders.length} holder(s), cap ${list.allowance ?? '(no band)'}`);
+      formatOutput({
+        columns: ['id', 'name', 'status'],
+        headers: ['Holder', 'Org name', 'Status'],
+        rows: list.holders.map((h) => ({ id: h.id, name: h.name || '-', status: h.status })),
+      }, { format: program.opts().output, emptyMessage: 'No holders.' });
+      if (rel) {
+        if (rel.dry_run) {
+          printInfo(`DRY RUN: would release ${rel.dead.length} non-live holder(s): ${rel.dead.map((d) => d.id).join(', ') || '(none)'}. Re-run with --yes to release.`);
+        } else {
+          printSuccess(`Released ${rel.released.length} non-live holder(s): ${rel.released.join(', ') || '(none)'}`);
+        }
+      }
+    });
+
+  if (owner) owner.registerLicenceOwnerCommands(licence, { json, fetchImpl });
+}

package/lib/commands/linkedin.js

@@ -0,0 +1,178 @@
+/**
+ * `quox linkedin` — LinkedIn plugin verbs, LI-OVERHAUL P9 (X CLI parity).
+ *
+ * quox linkedin post "<text>" --as <author_urn> [--visibility PUBLIC|CONNECTIONS] [--link <url>] [--image-url <https url>]
+ * quox linkedin comment <post_urn> "<text>" --as <actor_urn>
+ * quox linkedin posts <author_urn> [--count <n>]
+ * quox linkedin org <org_id>
+ *
+ * Both write verbs execute the linkedin connector tools through the governed
+ * collector endpoint (POST /api/v1/tools/execute -> connector bridge). The
+ * bridge gates them on their requiresApproval flag: each files an owner
+ * approval card and returns immediately with
+ * { pending:true, status:'awaiting_approval', approvalId, inbox_item_id }.
+ * The actual LinkedIn API write only happens once the owner approves via the
+ * dashboard inbox or `quox inbox respond <id> --action approve`. Reads
+ * (posts, org) execute directly; LinkedIn reads carry no per-call dollar
+ * cost (unlike X), only LinkedIn's own daily program quotas.
+ *
+ * URNs are explicit by design: LinkedIn addresses everything by URN
+ * (urn:li:person:xxx member, urn:li:organization:12345 org page) and the
+ * CLI has no org-scoped plugin-config lookup yet, so --as is required on
+ * writes rather than silently guessed.
+ */
+
+import { formatDetail, printSuccess, printInfo } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+
+const MAX_POST_CHARS = 3000;
+
+/**
+ * Execute one linkedin connector tool via the governed collector endpoint.
+ * A pending-approval response is a SUCCESS shape here (the card was filed);
+ * only a non-pending success:false is an error.
+ */
+async function executeLinkedInTool({ client, auth, program }, toolName, input) {
+  auth.requireAuth();
+  const orgId = resolveOrgId(auth, program);
+  const ep = resolveEndpoint('v1.tools.execute');
+  const body = { tool_name: toolName, input, org_id: orgId };
+  const data = await client.post(ep.path, { service: ep.service, body });
+  if (data && data.success === false && !data.pending) {
+    throw new Error(`${toolName} via POST ${ep.path} returned success:false: ${data.error || 'unknown error'}`);
+  }
+  return data;
+}
+
+function printAwaitingApproval(action, data) {
+  const itemRef = data.inbox_item_id || data.approvalId || 'unknown';
+  printSuccess(`${action} filed for owner approval — inbox item ${itemRef} (awaiting approval). Nothing publishes until an approver says yes.`);
+  if (data.inbox_item_id) {
+    printInfo(`Review and approve: quox inbox get ${data.inbox_item_id}  (or: quox inbox respond ${data.inbox_item_id} --action approve)`);
+  }
+}
+
+export function registerLinkedInCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const linkedin = program
+    .command('linkedin')
+    .description('LinkedIn publishing: governed, HITL-approved via HITL Inbox');
+
+  // ── linkedin post ────────────────────────────────────────────────────────
+
+  linkedin
+    .command('post')
+    .description('Draft a LinkedIn post. Files an owner approval card and returns immediately; never posts directly.')
+    .argument('<text>', `post text, max ${MAX_POST_CHARS} characters`)
+    .requiredOption('--as <author_urn>', 'author URN (urn:li:person:xxx or urn:li:organization:12345)')
+    .option('--visibility <visibility>', 'PUBLIC or CONNECTIONS', 'PUBLIC')
+    .option('--link <url>', 'attach a link/article URL')
+    .option('--image-url <url>', 'attach an image from an https URL (max 10MB); uploaded to LinkedIn server-side before the card is filed, so the approver sees the finished attachment')
+    .action(async (text, options) => {
+      if (text.length > MAX_POST_CHARS) {
+        throw new Error(`Text is ${text.length} characters, over the ${MAX_POST_CHARS} character limit.`);
+      }
+      if (!['PUBLIC', 'CONNECTIONS'].includes(options.visibility)) {
+        throw new Error(`--visibility must be PUBLIC or CONNECTIONS, got ${options.visibility}`);
+      }
+
+      const input = { author: options.as, text, visibility: options.visibility };
+      if (options.link) input.link_url = options.link;
+
+      if (options.imageUrl) {
+        const media = await executeLinkedInTool({ client, auth, program }, 'linkedin_upload_media', {
+          owner: options.as,
+          image_url: options.imageUrl,
+        });
+        const urn = media?.result?.image_urn;
+        if (!urn) {
+          throw new Error(`Image upload did not return an image URN: ${JSON.stringify(media).slice(0, 200)}`);
+        }
+        printInfo(`Image uploaded (${media.result.bytes} bytes) — ${urn}`);
+        input.media_id = urn;
+      }
+
+      const data = await executeLinkedInTool({ client, auth, program }, 'linkedin_publish_post', input);
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      printAwaitingApproval('Post', data);
+    });
+
+  // ── linkedin comment ─────────────────────────────────────────────────────
+
+  linkedin
+    .command('comment')
+    .description('Draft a comment on a LinkedIn post. Files an owner approval card and returns immediately; never comments directly.')
+    .argument('<post_urn>', 'URN of the post to comment on (e.g. urn:li:share:12345)')
+    .argument('<text>', 'comment text')
+    .requiredOption('--as <actor_urn>', 'actor URN posting the comment (person or organisation)')
+    .action(async (postUrn, text, options) => {
+      const data = await executeLinkedInTool({ client, auth, program }, 'linkedin_create_comment', {
+        post_urn: postUrn,
+        actor: options.as,
+        text,
+      });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      printAwaitingApproval('Comment', data);
+    });
+
+  // ── linkedin posts (read) ────────────────────────────────────────────────
+
+  linkedin
+    .command('posts')
+    .description('List recent posts for a member or organisation (read-only, no approval needed).')
+    .argument('<author_urn>', 'author URN (person or organisation)')
+    .option('--count <n>', 'number of posts (max 50)', '20')
+    .action(async (authorUrn, options) => {
+      const count = Math.min(parseInt(options.count, 10) || 20, 50);
+      const data = await executeLinkedInTool({ client, auth, program }, 'linkedin_get_posts', {
+        author: authorUrn,
+        count,
+      });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const posts = data.result || [];
+      if (posts.length === 0) {
+        printInfo('No posts returned.');
+        return;
+      }
+      for (const p of posts) {
+        console.log(`${p.id}  ${p.created_at || ''}  ${p.lifecycle_state || ''}`);
+        console.log(`  ${String(p.text || '').replace(/\n/g, '\n  ')}`);
+      }
+    });
+
+  // ── linkedin org (read) ──────────────────────────────────────────────────
+
+  linkedin
+    .command('org')
+    .description('Show a LinkedIn organisation page: name, follower count, website (read-only). Also the cheapest live credential check.')
+    .argument('<org_id>', 'numeric organisation id (e.g. 12345)')
+    .action(async (orgId) => {
+      const data = await executeLinkedInTool({ client, auth, program }, 'linkedin_get_org_info', { org_id: orgId });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const org = data.result || {};
+      printSuccess(`${org.name || 'Unknown'} (urn:li:organization:${org.id})`);
+      if (org.vanity_name) printInfo(`linkedin.com/company/${org.vanity_name}`);
+      // followers can be null when networkSizes is unavailable — say unknown,
+      // never a fake 0.
+      printInfo(`Followers: ${org.followers == null ? 'unknown' : org.followers.toLocaleString()}`);
+      if (org.website) printInfo(`Website: ${org.website}`);
+    });
+}

package/lib/commands/llm-policy.js

@@ -0,0 +1,117 @@
+/**
+ * LLM routing policy commands: view/set/dry-run-test the org's execution
+ * policy (which providers/models agents are allowed to route to).
+ *
+ * quox llm-policy get|set|test
+ *
+ * Backend: services/auth/routes/llm-routing-policies.js, mounted at plain
+ * `/api` (org-scoped in the URL): GET/PUT `/api/orgs/:orgId/llm-routing-policy`,
+ * POST `/api/orgs/:orgId/llm-routing-policy/test`. See
+ * cli/lib/api/endpoints/llm-policy.js for the full verified response shapes.
+ */
+
+import { readFileSync } from 'node:fs';
+import { formatDetail, printSuccess, printWarning } from '../core/output.js';
+import { resolveOrgId, parseJSON } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+/**
+ * Resolve a policy object from --file or --policy. Throws if neither given
+ * or the input isn't a JSON object.
+ */
+function resolvePolicy(options) {
+  let raw;
+  if (options.file) {
+    try {
+      raw = readFileSync(options.file, 'utf-8');
+    } catch (err) {
+      throw new Error(`Could not read ${options.file}: ${err.message}`);
+    }
+  } else if (options.policy !== undefined) {
+    raw = options.policy;
+  } else {
+    throw new Error('Policy input is required. Use --file <path> or --policy <json>.');
+  }
+
+  const policy = parseJSON(raw, options.file ? '--file contents' : '--policy');
+  if (!policy || typeof policy !== 'object' || Array.isArray(policy)) {
+    throw new Error('Policy must be a JSON object.');
+  }
+  return policy;
+}
+
+export function registerLlmPolicyCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const llmPolicy = program
+    .command('llm-policy')
+    .description('View, set, and dry-run-validate the org LLM routing policy');
+
+  // ── llm-policy get ──────────────────────────────────────────────────────────
+
+  llmPolicy
+    .command('get')
+    .description('Show the effective LLM routing policy for the active org')
+    .action(async () => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const data = await client.get(resolveEndpoint('llm-policy.get', { orgId }).path, {
+        service: resolveEndpoint('llm-policy.get', { orgId }).service,
+      });
+
+      if (data.source === 'seed') {
+        printWarning('No org-specific policy saved — showing the built-in seed policy.');
+      }
+
+      formatDetail(data.policy, {
+        format: program.opts().output,
+        title: `LLM Routing Policy (source: ${data.source})`,
+      });
+    });
+
+  // ── llm-policy set ──────────────────────────────────────────────────────────
+
+  llmPolicy
+    .command('set')
+    .description('Save a new LLM routing policy for the active org (requires ORG_MANAGE_SETTINGS)')
+    .option('--file <path>', 'path to a JSON file containing the policy object')
+    .option('--policy <json>', 'inline JSON policy object')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const policy = resolvePolicy(options);
+
+      const data = await client.put(resolveEndpoint('llm-policy.set', { orgId }).path, {
+        service: resolveEndpoint('llm-policy.set', { orgId }).service,
+        body: { policy },
+      });
+
+      printSuccess('LLM routing policy saved.');
+      formatDetail(data.policy, { format: program.opts().output });
+    });
+
+  // ── llm-policy test ─────────────────────────────────────────────────────────
+
+  llmPolicy
+    .command('test')
+    .description('Dry-run validate a policy without saving it')
+    .option('--file <path>', 'path to a JSON file containing the policy object')
+    .option('--policy <json>', 'inline JSON policy object')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const policy = resolvePolicy(options);
+
+      const data = await client.post(resolveEndpoint('llm-policy.test', { orgId }).path, {
+        service: resolveEndpoint('llm-policy.test', { orgId }).service,
+        body: { policy },
+      });
+
+      if (data.valid) {
+        printSuccess('Policy is valid.');
+      } else {
+        printWarning(`Policy is invalid (${(data.errors || []).length} error(s)).`);
+      }
+      formatDetail(data, { format: program.opts().output });
+    });
+}

package/lib/commands/llm.js

@@ -0,0 +1,45 @@
+/**
+ * LLM commands: provider status incl. degraded state and the failover target.
+ *
+ * quox llm status
+ *
+ * Backend: collector `GET /chat/status` (same endpoint as `quox chat-status`,
+ * key 'chat.status.list'). This is the curated LLM view of it: it surfaces the
+ * failover fields shipped with the LLM failover chain work (`degraded`,
+ * `degraded_reason`, `degraded_until`, `fallback_hint`) and warns loudly when
+ * the primary provider is in a failover cooldown. Routing policy itself lives
+ * under `quox llm-policy`.
+ */
+
+import { formatDetail, printWarning } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function registerLlmCommands(program, ctx) {
+  const { client } = ctx;
+
+  const llm = program
+    .command('llm')
+    .description('LLM provider status and failover');
+
+  llm
+    .command('status')
+    .description('Show LLM provider status, degraded state, and the failover target')
+    .action(async () => {
+      // No requireAuth: the route is public on collectors that allowlist it,
+      // but the token is attached when logged in (the dev gate requires a JWT).
+      const data = await client.get(resolveEndpoint('chat.status.list').path, { service: resolveEndpoint('chat.status.list').service });
+
+      if (data.degraded) {
+        const reason = data.degraded_reason ? ` (${data.degraded_reason})` : '';
+        const fallback = data.fallback_hint
+          ? ` Failing over to ${data.fallback_hint.provider}:${data.fallback_hint.model}.`
+          : '';
+        printWarning(`Primary provider degraded${reason}.${fallback}`);
+      }
+
+      formatDetail(data, {
+        format: program.opts().output,
+        title: 'LLM Status',
+      });
+    });
+}