quoxcli 0.3.1 → 0.5.0

package/lib/commands/kumaSla.js

@@ -0,0 +1,174 @@
+/**
+ * quox kuma sla ... : signed, verifiable uptime reports (NQ-KUMA-7).
+ *
+ * quox kuma sla [--month YYYY-MM | --from <iso> --to <iso>] [--out <file>] [--json]   generate + sign + store
+ * quox kuma sla list                                                                   this org's stored reports
+ * quox kuma sla verify <id|file> [--public-key <base64>]                               recompute the hash, check the signature
+ *
+ * `verify <id>` asks the collector, which checks against its pinned WARD key (trust anchored).
+ * `verify <file>` is fully OFFLINE: it recomputes sha256 over the canonical report and checks the Ed25519
+ * signature with node:crypto. Against the key embedded in the file this proves integrity only (anyone can
+ * mint a keypair); pass --public-key <raw 32 byte base64 WARD key> to pin the signer yourself.
+ *
+ * Exit codes: 0 ok / verified, 1 error, 2 verification FAILED.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { createHash, createPublicKey, verify as cryptoVerify } from 'node:crypto';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { line as glyphLine } from '../core/quoxglyph.js';
+
+// Same canonical form as services/collector/lib/bundleSigner.js canonicalize (sorted keys, no whitespace).
+export function canonicalize(val) {
+  if (val === null || val === undefined) return JSON.stringify(val);
+  if (typeof val !== 'object') return JSON.stringify(val);
+  if (Array.isArray(val)) return `[${val.map((v) => canonicalize(v)).join(',')}]`;
+  const keys = Object.keys(val).filter((k) => val[k] !== undefined).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(val[k])}`).join(',')}}`;
+}
+
+const SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+const keyFromRaw = (b64) => {
+  try {
+    const raw = Buffer.from(String(b64 || ''), 'base64');
+    if (raw.length !== 32) return null;
+    return createPublicKey({ key: Buffer.concat([SPKI_PREFIX, raw]), format: 'der', type: 'spki' });
+  } catch { return null; }
+};
+
+/** Offline verification of an export bundle. Mirrors kumaSlaReports.verifyBundle. */
+export function verifyBundleOffline(bundle, { publicKey } = {}) {
+  const out = { valid: false, hash_ok: false, binding_ok: false, signature_ok: false, key_source: 'none', trust_anchored: false };
+  if (!bundle || typeof bundle !== 'object' || !bundle.report || typeof bundle.report !== 'object') return { ...out, reason: 'malformed_bundle' };
+  const sig = bundle.signature;
+  if (!sig || !sig.signature || !sig.message) return { ...out, reason: 'missing_signature' };
+  const recomputed = createHash('sha256').update(canonicalize(bundle.report), 'utf-8').digest('hex');
+  out.recomputed_sha256 = recomputed;
+  out.hash_ok = recomputed === bundle.report_sha256;
+  if (!out.hash_ok) return { ...out, reason: 'report_hash_mismatch' };
+  const r = bundle.report;
+  const expected = r.period ? {
+    kind: 'quox.kuma.sla.report', report_id: bundle.report_id, org_id: r.org_id,
+    period_from: r.period.from, period_to: r.period.to, generated_at: r.generated_at, report_sha256: recomputed,
+  } : null;
+  out.binding_ok = !!expected && canonicalize(expected) === canonicalize(sig.message);
+  if (!out.binding_ok) return { ...out, reason: 'signature_not_bound_to_report' };
+  if (sig.sig_type !== 'ed25519') return { ...out, reason: `unverifiable_sig_type:${sig.sig_type}` };
+  let key = null; let source = 'none';
+  if (publicKey) { key = keyFromRaw(publicKey); source = 'pinned'; if (!key) return { ...out, reason: 'bad_public_key' }; }
+  else { key = keyFromRaw(sig.public_key); source = 'embedded'; }
+  if (!key) return { ...out, reason: 'no_verification_key' };
+  out.key_source = source;
+  try {
+    out.signature_ok = cryptoVerify(null, Buffer.from(canonicalize(sig.message), 'utf-8'), key, Buffer.from(String(sig.signature), 'base64'));
+  } catch (err) { return { ...out, reason: `verify_error:${err.message}` }; }
+  if (!out.signature_ok) return { ...out, reason: 'signature_mismatch' };
+  out.valid = true;
+  out.trust_anchored = source === 'pinned' && !sig.warning;
+  if (sig.warning) out.warning = sig.warning;
+  return out;
+}
+
+const dur = (s) => {
+  if (s === null || s === undefined) return '-';
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ${s % 60}s`;
+  return `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`;
+};
+
+export function registerKumaSla(kuma, { client, auth, jsonOut, guard, KumaFail, pad }) {
+  const slaFail = (verb, ep, err) => {
+    const status = err && (err.status ?? err.statusCode);
+    const msg = (err && err.message) || String(err);
+    const head = `quox kuma ${verb}: ${ep.method} ${ep.path} failed${status ? ` with HTTP ${status}` : ''}`;
+    if (status === 422) return new KumaFail(`${head}: Uptime Kuma is not configured for this org (add the uptime_kuma credential in the vault).`);
+    if (status === 404) return new KumaFail(`${head}: not found in this org.`);
+    return new KumaFail(`${head}: ${msg}`);
+  };
+
+  const sla = kuma
+    .command('sla')
+    .description('Signed, verifiable uptime (SLA) report from Kuma heartbeats; `sla verify <id|file>` checks one')
+    .option('--month <YYYY-MM>', 'calendar month (UTC), e.g. 2026-09')
+    .option('--from <iso>', 'range start (with --to)')
+    .option('--to <iso>', 'range end, exclusive')
+    .option('--out <file>', 'also write the signed bundle here for offline verification')
+    .addHelpText('after', '\nExit codes: 0 ok, 1 error, 2 `sla verify` found the report does NOT verify.')
+    .action(guard('sla', async (options) => {
+      auth.requireAuth();
+      if (!options.month && !(options.from && options.to)) throw new KumaFail('quox kuma sla: give --month YYYY-MM, or both --from and --to.');
+      const ep = resolveEndpoint('mon.kuma.sla.create');
+      const body = options.month ? { month: options.month } : { from: options.from, to: options.to };
+      let data;
+      try { data = await client.post(ep.path, { service: ep.service, body }); } catch (err) { throw slaFail('sla', ep, err); }
+      if (!data || data.success === false || data.error || !data.report || !data.signature) {
+        throw new KumaFail(`quox kuma sla: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no report'}`);
+      }
+      if (options.out) {
+        writeFileSync(options.out, `${JSON.stringify({ report_id: data.report_id, report: data.report, report_sha256: data.report_sha256, signature: data.signature }, null, 2)}\n`);
+      }
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      const r = data.report; const ro = r.rollup;
+      console.log(glyphLine('kuma', 'sla', { result: `${r.period.label} · ${ro.uptime_pct === null ? 'no data' : `${ro.uptime_pct}%`}`, status: ro.uptime_pct === null ? 'warn' : 'ok' }));
+      console.log(`Report ${data.report_id}   sha256 ${data.report_sha256}`);
+      console.log(`Period ${r.period.from} to ${r.period.effective_to}${r.period.partial ? '  (partial: the period has not ended)' : ''}`);
+      const rows = [['MONITOR', 'UPTIME', 'OUTAGES', 'DOWNTIME', 'LONGEST', 'MTTR', 'MAINT', 'GAPS']];
+      for (const m of r.monitors) {
+        rows.push([m.name || m.monitor_id, m.status === 'no_data' ? 'no data' : `${m.uptime_pct}%`, m.outages.count, dur(m.outages.total_downtime_seconds), dur(m.outages.longest_seconds), dur(m.outages.mttr_seconds), m.beats.maintenance, m.coverage.gaps.length]);
+      }
+      console.log(`\n${pad(rows).join('\n')}`);
+      console.log(`\nOrg: ${ro.uptime_pct === null ? 'no data' : `${ro.uptime_pct}%`} over ${ro.monitors_with_data}/${ro.monitors_total} monitors with data; ${ro.outages.count} ${ro.outages.count === 1 ? 'outage' : 'outages'}, ${dur(ro.outages.total_downtime_seconds)} down, MTTR ${dur(ro.outages.mttr_seconds)}.`);
+      if (ro.monitors_no_data) console.log(`${ro.monitors_no_data} ${ro.monitors_no_data === 1 ? 'monitor has' : 'monitors have'} no heartbeats in the period: reported as no data, not as 100%.`);
+      console.log(data.trust_anchored ? 'Signed with the WARD key and witnessed.' : 'WARNING: signed with an ephemeral key (no persistent WARD key on this collector): integrity only, not trust anchored.');
+      console.log(`Verify:  quox kuma sla verify ${options.out || data.report_id}`);
+    }));
+
+  sla
+    .command('list')
+    .description('This org\'s stored SLA reports')
+    .action(guard('sla list', async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('mon.kuma.sla.list');
+      let data;
+      try { data = await client.get(ep.path, { service: ep.service }); } catch (err) { throw slaFail('sla list', ep, err); }
+      if (!data || data.success === false || data.error || !Array.isArray(data.reports)) {
+        throw new KumaFail(`quox kuma sla list: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no reports array'}`);
+      }
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      console.log(glyphLine('kuma', 'sla list', { result: `${data.reports.length} ${data.reports.length === 1 ? 'report' : 'reports'}`, status: 'ok' }));
+      if (!data.reports.length) { console.log('No reports yet. Generate one: quox kuma sla --month YYYY-MM'); return; }
+      const rows = [['REPORT', 'PERIOD', 'CREATED', 'SHA256']];
+      for (const r of data.reports) rows.push([r.report_id, r.period, r.created_at, String(r.report_sha256).slice(0, 16)]);
+      console.log(pad(rows).join('\n'));
+    }));
+
+  sla
+    .command('verify')
+    .description('Recompute the report hash and check the signature (id: via the collector, pinned WARD key; file: fully offline)')
+    .argument('<id|file>', 'a report id from `quox kuma sla list`, or a bundle file written by `sla --out`')
+    .option('--public-key <base64>', 'offline: pin this raw 32 byte Ed25519 WARD public key instead of trusting the key in the file')
+    .action(guard('sla verify', async (target, options) => {
+      let result;
+      if (existsSync(target)) {
+        let bundle;
+        try { bundle = JSON.parse(readFileSync(target, 'utf-8')); } catch (err) { throw new KumaFail(`quox kuma sla verify: ${target} is not valid JSON: ${err.message}`); }
+        result = { report_id: bundle && bundle.report_id, mode: 'offline', ...verifyBundleOffline(bundle, { publicKey: options.publicKey }) };
+      } else {
+        auth.requireAuth();
+        const ep = resolveEndpoint('mon.kuma.sla.verify', { id: target });
+        let data;
+        try { data = await client.get(ep.path, { service: ep.service }); } catch (err) { throw slaFail('sla verify', ep, err); }
+        if (!data || data.success === false || data.error || typeof data.valid !== 'boolean') {
+          throw new KumaFail(`quox kuma sla verify: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no verdict'}`);
+        }
+        result = { mode: 'collector', ...data };
+      }
+      if (jsonOut()) { console.log(JSON.stringify(result, null, 2)); } else {
+        console.log(glyphLine('kuma', 'sla verify', { result: result.valid ? `verified (${result.mode})` : `NOT verified: ${result.reason}`, status: result.valid ? 'ok' : 'error' }));
+        console.log(`hash ${result.hash_ok ? 'matches' : 'DOES NOT match'}   binding ${result.binding_ok ? 'ok' : 'FAILED'}   signature ${result.signature_ok ? 'valid' : 'INVALID'}   key ${result.key_source}${result.trust_anchored ? ' (trust anchored)' : ' (not trust anchored)'}`);
+        if (result.valid && !result.trust_anchored) console.log('Integrity holds, but the signer was not checked against the WARD key. Pin it with --public-key, or verify by id through the collector.');
+        if (result.warning) console.log(`Warning: ${result.warning}`);
+      }
+      if (!result.valid) process.exitCode = 2;
+    }));
+}

package/lib/commands/licence.js

@@ -109,9 +109,21 @@ export function registerLicenceCommands(program, ctx, { owner = VENDOR_OWNER } =
     .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('--release <orgId>', 'release a LIVE org seat (its install of the plugin is disabled); dry run unless --yes')
+    .option('--to <orgId>', 'with --release: hand the freed seat to this org in the same call')
     .option('--yes', 'actually release (otherwise dry run)')
     .action(async (pluginId, opts) => {
       auth.requireAuth();
+      if (opts.to && !opts.release) {
+        const e = new Error('--to only works together with --release <orgId>');
+        e.exitCode = 2;
+        throw e;
+      }
+      if (opts.release && opts.releaseDead) {
+        const e = new Error('use either --release or --release-dead, not both');
+        e.exitCode = 2;
+        throw e;
+      }
       const lep = resolveEndpoint('setup.licensing.seats.list', { pluginId });
       const list = await client.get(lep.path, { service: lep.service });
       let rel = null;
@@ -119,7 +131,15 @@ export function registerLicenceCommands(program, ctx, { owner = VENDOR_OWNER } =
         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; }
+      let live = null;
+      if (opts.release) {
+        const rp = resolveEndpoint('setup.licensing.seats.release', { pluginId });
+        live = await client.post(rp.path, {
+          service: rp.service,
+          body: { org_id: opts.release, ...(opts.to ? { to_org_id: opts.to } : {}), dry_run: !opts.yes },
+        });
+      }
+      if (json()) { console.log(JSON.stringify({ ...list, release: rel, live_release: live }, null, 2)); return; }
       printInfo(`${pluginId}: ${list.holders.length} holder(s), cap ${list.allowance ?? '(no band)'}`);
       formatOutput({
         columns: ['id', 'name', 'status'],
@@ -133,6 +153,24 @@ export function registerLicenceCommands(program, ctx, { owner = VENDOR_OWNER } =
           printSuccess(`Released ${rel.released.length} non-live holder(s): ${rel.released.join(', ') || '(none)'}`);
         }
       }
+      if (live) {
+        const who = `${live.org_name || live.org_id} (${live.org_id})`;
+        const loses = live.will_disable_install
+          ? `its install of ${pluginId} goes disabled and the plugin stops working there`
+          : `it loses access to ${pluginId} (no enabled install to disable)`;
+        if (live.dry_run) {
+          printInfo(`DRY RUN: would release the ${pluginId} seat held by ${who}: ${loses}.`);
+          if (live.would_assign_to) printInfo(`DRY RUN: the freed seat would go to ${live.would_assign_to}.`);
+          else printInfo(`Seats are first-come: add --to <orgId> to hand the freed seat to a specific org, otherwise the first org to use ${pluginId} takes it.`);
+          printInfo(`Re-run with --yes to release.`);
+        } else if (live.released) {
+          printSuccess(`Released the ${pluginId} seat held by ${who}: ${loses}.`);
+          if (live.assigned_to) printSuccess(`Seat now held by ${live.assigned_to}.`);
+          else if (opts.to) printWarning(`The seat was freed but ${opts.to} could not take it (see the band with: quox licence seats ${pluginId}).`);
+        } else {
+          printWarning(`Nothing released: ${who} no longer holds a ${pluginId} seat.`);
+        }
+      }
     });
 
   if (owner) owner.registerLicenceOwnerCommands(licence, { json, fetchImpl });

package/lib/commands/licenceLinkView.js

@@ -0,0 +1,311 @@
+/**
+ * QUOXON (owner 2026-11-05): the render layer for `quox setup license link`.
+ *
+ * The owner linked the wrong licence twice in one day (one granting 0
+ * plugins) because neither the web page nor the CLI said what was being
+ * picked. This view frames the code and link, counts the code down live,
+ * and on approval names WHAT was linked: licence id, plan, plugins, seats.
+ *
+ * Everything here is pure (strings in, strings out) so it is testable without
+ * a terminal. Colour comes from the house QuoxGlyph module (lib/core/
+ * quoxglyph.js: line grammar, brand gradient, status colours) and the spinner
+ * frames from the TUI's house spinner; nothing here invents a parallel style.
+ * With colour off every function returns plain lines with no escape codes.
+ */
+
+import { line, setColor, GRAD, STATUS, celebrate } from '../core/quoxglyph.js';
+import { SPIN_FRAMES } from '../quoxon/slashSpinner.js';
+import { motionAllowed } from '../quoxon/motion/clock.js';
+
+const R = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const UNDERLINE = '\x1b[4m';
+const fg = ([r, g, b]) => `\x1b[38;2;${r};${g};${b}m`;
+const AMBER = STATUS.warn.rgb;
+const GREEN = STATUS.ok.rgb;
+
+// eslint-disable-next-line no-control-regex
+const ESC = /\x1b\]8;;[^\x07]*\x07|\x1b\[[0-9;]*[A-Za-z]/g;
+/** Visible width: escape codes stripped, one column per code point. */
+const vis = (s) => [...String(s).replace(ESC, '')].length;
+const padTo = (s, w) => s + ' '.repeat(Math.max(0, w - vis(s)));
+
+/** Run a QuoxGlyph render with colour forced on or off, then hand control back to auto. */
+function withColor(color, fn) {
+  setColor(color);
+  try { return fn(); } finally { setColor(null); }
+}
+
+/** Should this terminal get colour? Same rule as quoxglyph, decided for an injected stream. */
+export function colorFor(term, env = process.env) {
+  if (env.QUOX_COLOR === '0') return false;
+  if (env.QUOX_COLOR === '1' || env.QUOX_COLOR === '2') return true;
+  return Boolean(term && term.isTTY) && !env.NO_COLOR;
+}
+
+/** Should the waiting line animate? TTY only, and never under reduced motion. */
+export const animateFor = (term, env = process.env) => motionAllowed(Boolean(term && term.isTTY), env);
+
+/** m:ss, floored at 0:00. */
+export function fmtCountdown(ms) {
+  const total = Math.max(0, Math.floor(Number(ms) / 1000) || 0);
+  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`;
+}
+
+/** WQXP-7T4K -> "W Q X P - 7 T 4 K". */
+export const spacedCode = (code) => [...String(code || '')].join(' ');
+
+/** Paint text in the brand gradient (per visible character), bold. */
+function gradient(text) {
+  const chars = [...text];
+  const last = Math.max(1, chars.length - 1);
+  return BOLD + chars.map((ch, i) => (ch === ' ' ? ch
+    : fg(GRAD[0].map((v, k) => Math.round(v + (GRAD[1][k] - v) * (i / last)))) + ch)).join('') + R;
+}
+
+/** ▰▰▰▱▱ in the brand gradient, for a 0..1 ratio. */
+function bar(ratio, width = 10) {
+  const filled = Math.max(0, Math.min(width, Math.round(ratio * width)));
+  const last = Math.max(1, width - 1);
+  let out = '';
+  for (let i = 0; i < filled; i++) out += fg(GRAD[0].map((v, k) => Math.round(v + (GRAD[1][k] - v) * (i / last)))) + '▰';
+  return out + (filled ? R : '') + DIM + '▱'.repeat(width - filled) + R;
+}
+
+/** OSC 8 hyperlink whose visible text is the full URL, so it is clickable either way. */
+const hyperlink = (url) => `\x1b]8;;${url}\x07${UNDERLINE}${fg(GRAD[0])}${url}${R}\x1b]8;;\x07`;
+
+/**
+ * A rounded frame around rows (already styled). The title sits in the top
+ * border. The frame grows to fit its widest row (a URL is never clipped).
+ */
+function frame(rows, { title = '', cols = 80, tint = null } = {}) {
+  const b = (s) => (tint ? fg(tint) + s + R : DIM + s + R);
+  const titleText = title ? ` ${title} ` : '';
+  const inner = Math.max(44, Math.min(Math.max(44, cols - 6), 76), ...rows.map((r) => vis(r) + 4), vis(titleText) + 4);
+  const top = b('╭─') + titleText + b('─'.repeat(Math.max(0, inner - 1 - vis(titleText))) + '╮');
+  const body = rows.map((r) => b('│') + padTo(`  ${r}`, inner) + b('│'));
+  const bottom = b('╰' + '─'.repeat(inner) + '╯');
+  return [top, ...body, bottom].map((l) => `  ${l}`).join('\n');
+}
+
+/** Greedy wrap of items into lines no wider than `width`, joined by `sep`. */
+function wrapList(items, width, sep = ' · ') {
+  const lines = [];
+  let cur = '';
+  for (const item of items) {
+    const next = cur ? cur + sep + item : item;
+    if (cur && vis(next) > width) { lines.push(cur); cur = item; } else cur = next;
+  }
+  if (cur) lines.push(cur);
+  return lines;
+}
+
+const minutes = (ms) => Math.max(1, Math.round(ms / 60000));
+
+/**
+ * The card shown while the code waits for approval.
+ * @param {{userCode:string,url:string,remainingMs:number,color:boolean,cols?:number}} o
+ */
+export function renderLinkCard({ userCode, url, remainingMs, color, cols = 80 }) {
+  const header = withColor(color, () => line('quox', 'licence link', { result: 'approve on quox.ai', status: 'busy' }));
+  if (!color) {
+    return [
+      header,
+      `Open ${url} and enter this code:`,
+      '',
+      `    ${userCode}`,
+      '',
+      `The code is good for ${minutes(remainingMs)} minutes.`,
+      'Pick the licence you want on quox.ai: this instance gets exactly what you approve.',
+      'Waiting for approval...',
+    ].join('\n');
+  }
+  const label = (s) => `${DIM}${s.padEnd(11)}${R}`;
+  const rows = [
+    '',
+    `${label('Your code')}${gradient(spacedCode(userCode))}`,
+    '',
+    `${label('Open')}${hyperlink(url)}`,
+    `${label('Expires in')}${bar(1)} ${BOLD}${fmtCountdown(remainingMs)}${R}`,
+    '',
+    `${fg(AMBER)}Pick the licence you want on quox.ai.${R}`,
+    `${DIM}This instance gets exactly what you approve.${R}`,
+  ];
+  return [header, frame(rows, { title: `${BOLD}Link this instance${R}`, cols })].join('\n');
+}
+
+/**
+ * One frame of the live waiting line (TTY only): spinner, label, countdown.
+ * @param {{frame:number,remainingMs:number,totalMs?:number,color:boolean,note?:string}} o
+ */
+export function renderWaitingLine({ frame: i, remainingMs, totalMs = 600000, color, note = '' }) {
+  const spin = SPIN_FRAMES[i % SPIN_FRAMES.length];
+  const left = `${fmtCountdown(remainingMs)} left`;
+  const extra = note ? ` · ${note}` : '';
+  if (!color) return `${spin} Waiting for approval on quox.ai · ${left}${extra}`;
+  const ratio = totalMs > 0 ? remainingMs / totalMs : 0;
+  const tone = ratio < 0.2 ? fg(AMBER) : '';
+  return `  ${fg(GRAD[0])}${spin}${R} Waiting for approval on quox.ai ${DIM}│${R} ${bar(ratio)} ${tone}${BOLD}${left}${R}${note ? `${DIM}${extra}${R}` : ''}`;
+}
+
+const bareId = (raw) => String(raw).split('@')[0];
+const orgAllowance = (raw) => {
+  const m = /@orgs=(\d+)/.exec(String(raw));
+  return m ? Number(m[1]) : null;
+};
+
+/**
+ * What was linked, from the approved lease plus the read-back of
+ * GET /api/setup/licensing/entitlements (the route `quox licence status`
+ * reads). The read-back wins where it has the licence; the lease is the
+ * fallback, so a failed read never hides what was activated.
+ *
+ * @returns {{license_id, plans:string[], entitlements:string[], seats:Array<{plugin,used,total}>, warnings:string[], servers?:{used,total}}}
+ */
+export function linkedDetails(lease = {}, status = null, poll = {}) {
+  const id = lease.license_id || null;
+  const row = (status && Array.isArray(status.licenses))
+    ? status.licenses.find((l) => l && l.license_id === id) : null;
+
+  let rawEntitlements;
+  let plans;
+  if (row) {
+    rawEntitlements = row.entitlements || [];
+    plans = row.plans || [];
+  } else {
+    const raw = lease.entitlements || [];
+    plans = raw.filter((e) => String(e).toLowerCase().startsWith('plan.')).map((e) => bareId(e).slice(5).toLowerCase()).filter(Boolean);
+    rawEntitlements = raw.filter((e) => !String(e).toLowerCase().startsWith('plan.'));
+  }
+
+  const bands = (status && status.org_bands && typeof status.org_bands === 'object') ? status.org_bands : {};
+  const entitlements = [...new Set(rawEntitlements.map(bareId))];
+  const seats = [];
+  for (const raw of rawEntitlements) {
+    const plugin = bareId(raw);
+    const band = bands[plugin];
+    if (band) seats.push({ plugin, used: Number(band.assigned_count ?? 0), total: Number(band.allowance ?? 0) });
+    else if (orgAllowance(raw) != null) seats.push({ plugin, used: null, total: orgAllowance(raw) });
+  }
+
+  const out = { license_id: id, plans, entitlements, seats, warnings: entitlements.length === 0 ? ['zero_entitlements'] : [] };
+  // Server seats travel only when the poll response carries them (the
+  // control plane sends max_servers and bound; additive, never guessed).
+  if (poll && poll.max_servers != null) {
+    out.servers = { used: Array.isArray(poll.bound) ? poll.bound.length : null, total: Number(poll.max_servers) };
+  }
+  return out;
+}
+
+const seatText = (s) => (s.used == null ? `${s.plugin} up to ${s.total} orgs` : `${s.plugin} ${s.used} of ${s.total} orgs`);
+const leaseText = (iso) => {
+  const t = Date.parse(iso);
+  return Number.isFinite(t) ? new Date(t).toISOString().slice(0, 16).replace('T', ' ') + ' UTC' : null;
+};
+
+/** The exact command that unlinks this licence and starts a fresh link. */
+export function relinkCommand(licenseId, profile) {
+  const q = profile ? `quox -p ${profile}` : 'quox';
+  return `${q} setup license deactivate --license-id ${licenseId} --yes && ${q} setup license link`;
+}
+
+/**
+ * The result after approval: compact, celebratory when the licence grants
+ * something, amber with the one fix command when it grants nothing.
+ * @param {ReturnType<typeof linkedDetails>} d
+ * @param {{color:boolean, cols?:number, leaseExpiresAt?:string, profile?:string, readBackError?:string}} o
+ */
+export function renderLinkedCard(d, { color, cols = 80, leaseExpiresAt = null, profile = null, readBackError = null } = {}) {
+  const zero = d.warnings.includes('zero_entitlements');
+  const header = withColor(color, () => (zero
+    ? line('quox', 'licence linked', { result: 'grants 0 plugins', status: 'warn' })
+    : line('quox', 'licence linked', { result: color ? celebrate('instance activated') : 'instance activated', status: 'ok', max: 400 })));
+  const plan = d.plans.length ? d.plans.join(', ') : '(none on this licence)';
+  const renews = leaseText(leaseExpiresAt);
+  const fix = relinkCommand(d.license_id, profile);
+  const warnText = 'This licence grants 0 plugins, so nothing unlocks. You may have picked the wrong licence on quox.ai.';
+  const readBack = readBackError
+    ? `Could not read the licence details back (${readBackError}). Showing what the lease carried; run \`quox licence status\` to check.`
+    : null;
+
+  if (!color) {
+    const out = [header];
+    if (readBack) out.push(readBack);
+    out.push(`Licence: ${d.license_id}`);
+    out.push(`Plan: ${plan}`);
+    out.push(`Plugins (${d.entitlements.length}): ${d.entitlements.join(', ') || 'none'}`);
+    if (d.seats.length) out.push(`Seats: ${d.seats.map(seatText).join(', ')}`);
+    if (d.servers) out.push(`Servers: ${d.servers.used ?? '?'} of ${d.servers.total} in use`);
+    if (renews) out.push(`Lease renews by: ${renews}`);
+    if (zero) {
+      out.push(`⚠ ${warnText}`);
+      out.push('Unlink it and link the right one:');
+      out.push(`    ${fix}`);
+    } else {
+      out.push('This instance is activated. No key was ever pasted into it.');
+    }
+    return out.join('\n');
+  }
+
+  const label = (s) => `${DIM}${s.padEnd(10)}${R}`;
+  const width = Math.min(Math.max(44, cols - 6), 76) - 14;
+  const rows = [
+    `${label('Licence')}${BOLD}${d.license_id}${R}`,
+    `${label('Plan')}${d.plans.length ? gradient(plan) : `${DIM}${plan}${R}`}`,
+  ];
+  if (zero) {
+    rows.push(`${label('Plugins')}${fg(AMBER)}${BOLD}0${R}${fg(AMBER)} entitled${R}`);
+  } else {
+    const list = wrapList(d.entitlements, width);
+    rows.push(`${label('Plugins')}${BOLD}${d.entitlements.length}${R} ${DIM}entitled${R}`);
+    for (const l of list) rows.push(`${' '.repeat(10)}${fg(GREEN)}${l}${R}`);
+  }
+  for (const [n, s] of d.seats.entries()) {
+    const ratio = s.used == null || !s.total ? 0 : s.used / s.total;
+    const text = s.used == null ? `up to ${s.total} orgs` : `${s.used} of ${s.total} orgs`;
+    rows.push(`${label(n === 0 ? 'Seats' : '')}${s.plugin} ${bar(ratio, 6)} ${text}`);
+  }
+  if (d.servers) rows.push(`${label('Servers')}${d.servers.used ?? '?'} of ${d.servers.total} in use`);
+  if (renews) rows.push(`${label('Lease')}${DIM}renews by ${renews}${R}`);
+
+  const title = zero
+    ? `${fg(AMBER)}${BOLD}${STATUS.warn.glyph} Linked, but it grants 0 plugins${R}`
+    : `${fg(GREEN)}${BOLD}${STATUS.ok.glyph} Licence linked${R}`;
+  const out = [header];
+  if (readBack) out.push(`  ${fg(AMBER)}${readBack}${R}`);
+  out.push(frame(rows, { title, cols, tint: zero ? AMBER : GREEN }));
+  if (zero) {
+    out.push(`  ${fg(AMBER)}${BOLD}${STATUS.warn.glyph}${R} ${fg(AMBER)}${warnText}${R}`);
+    out.push(`    ${DIM}Unlink it and link the right one:${R}`);
+    out.push(`    ${BOLD}${fix}${R}`);
+  } else {
+    out.push(`  ${DIM}No key was ever pasted into this instance.${R}`);
+  }
+  return out.join('\n');
+}
+
+/**
+ * The live waiting indicator. On an animating TTY it redraws one line in
+ * place every 80 ms (house spinner pace) with the countdown; with motion off
+ * it draws once. `note()` prints a line above it without tearing the spinner.
+ * `stop()` clears the line. Never used when the stream is not a TTY.
+ */
+export function startWaiting({ term, deadline, totalMs, color, animate, now = () => Date.now(), frameMs = 80 }) {
+  let i = 0;
+  let note = '';
+  const draw = () => {
+    term.write('\r\x1b[2K' + renderWaitingLine({ frame: i++, remainingMs: deadline - now(), totalMs, color, note }));
+  };
+  draw();
+  const timer = animate ? setInterval(draw, frameMs) : null;
+  if (timer && typeof timer.unref === 'function') timer.unref();
+  return {
+    note(text) { note = text; draw(); },
+    stop() {
+      if (timer) clearInterval(timer);
+      term.write('\r\x1b[2K');
+    },
+  };
+}

package/lib/commands/linkedin.js

@@ -4,6 +4,7 @@
  * 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 whoami
  * quox linkedin org <org_id>
  *
  * Both write verbs execute the linkedin connector tools through the governed
@@ -154,6 +155,24 @@ export function registerLinkedInCommands(program, ctx) {
       }
     });
 
+  // ── linkedin me (read) ───────────────────────────────────────────────────
+
+  linkedin
+    .command('whoami')
+    .description('Show the connected member identity and the member URN to use with --as on posts (read-only). Needs the openid and profile scopes on the token.')
+    .action(async () => {
+      const data = await executeLinkedInTool({ client, auth, program }, 'linkedin_get_me', {});
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const me = data.result || {};
+      printSuccess(`${me.name || 'Unknown'} (${me.member_urn || 'no member URN returned'})`);
+      if (me.email) printInfo(`Email: ${me.email}`);
+      if (me.member_urn) printInfo(`Use as author: --as ${me.member_urn}`);
+    });
+
   // ── linkedin org (read) ──────────────────────────────────────────────────
 
   linkedin