@velaro/cli 0.7.0 → 1.4.8

package/lib/commands/entitlement.js

@@ -0,0 +1,176 @@
+// velaro entitlement — query and manage site feature entitlements (superadmin only)
+import { request } from '../api.js';
+
+async function getSite(args) {
+  if (!args.site) { console.error('Usage: velaro entitlement get --site 1032'); process.exit(1); }
+  const result = await request('GET', `Entitlements/${args.site}`);
+
+  console.log(`\nSite ${result.siteId} — plan: ${result.planKey || 'none'} | status: ${result.status}`);
+  if (result.cancelAtPeriodEnd) console.log(`⚠️  Cancels at period end: ${result.currentPeriodEnd}`);
+  if (result.trialEndAt) console.log(`   Trial ends: ${result.trialEndAt}`);
+
+  const features = Object.entries(result.features || {});
+  const enabled  = features.filter(([,v]) => v).map(([k]) => k).sort();
+  const disabled = features.filter(([,v]) => !v).map(([k]) => k).sort();
+
+  console.log(`\nEnabled (${enabled.length}):`);
+  for (const k of enabled) console.log(`  ✅ ${k}`);
+
+  if (args.all) {
+    console.log(`\nDisabled (${disabled.length}):`);
+    for (const k of disabled) console.log(`  ❌ ${k}`);
+  } else {
+    console.log(`\n(${disabled.length} features disabled — use --all to show them)`);
+  }
+}
+
+async function listFeatures() {
+  const features = await request('GET', 'Entitlements/features');
+
+  const byCategory = {};
+  for (const f of features) {
+    if (!byCategory[f.category]) byCategory[f.category] = [];
+    byCategory[f.category].push(f);
+  }
+
+  console.log(`\nEntitlementFeature registry (${features.length} features)\n`);
+  for (const [cat, rows] of Object.entries(byCategory).sort()) {
+    console.log(`── ${cat.toUpperCase()} (${rows.length}) ──`);
+    for (const f of rows) console.log(`  ${f.featureKey.padEnd(40)} ${f.displayName}`);
+    console.log('');
+  }
+}
+
+async function setOverride(args) {
+  if (!args.site || !args.key) {
+    console.error('Usage: velaro entitlement set-override --site 1032 --key EnableIvr --value true [--reason "Custom deal"]');
+    process.exit(1);
+  }
+  const value = args.value === 'true' || args.value === true;
+  await request('POST', `Entitlements/${args.site}/override`, {
+    featureKey: args.key,
+    value,
+    reason: args.reason,
+  });
+  console.log(`✅ Site ${args.site}: ${args.key} = ${value}${args.reason ? ` (${args.reason})` : ''}`);
+}
+
+async function seed() {
+  const result = await request('POST', 'Entitlements/admin/seed');
+  console.log(`✅ ${result.message}`);
+}
+
+async function compSite(args) {
+  if (!args.site || !args.plan) {
+    console.error('Usage: velaro entitlement comp --site 1032 --plan plan.professional [--until 2027-01-01] [--notes "Custom deal"]');
+    process.exit(1);
+  }
+  const result = await request('POST', `Entitlements/admin/comp/${args.site}`, {
+    planKey: args.plan,
+    compEndAt: args.until ?? null,
+    notes: args.notes,
+  });
+  const expiry = result.compEndAt ? ` — expires ${result.compEndAt}` : ' — indefinite';
+  console.log(`✅ Site ${args.site} comped on plan ${result.planKey}${expiry}`);
+  console.log(`   Use 'velaro entitlement set-override --site ${args.site} ...' to customize features.`);
+}
+
+async function removeOverride(args) {
+  if (!args.site || !args.key) {
+    console.error('Usage: velaro entitlement remove-override --site 1032 --key EnableIvr');
+    process.exit(1);
+  }
+  await request('DELETE', `Entitlements/${args.site}/override/${args.key}`);
+  console.log(`✅ Removed override for ${args.key} on site ${args.site}.`);
+}
+
+async function seedPlans() {
+  const result = await request('POST', 'Entitlements/admin/seed-plans');
+  if (result.error) { console.error(`❌ ${result.error}`); process.exit(1); }
+  console.log(`✅ Plan entitlements seeded: ${result.plansSeeded} plans, ${result.inserted} inserted, ${result.updated} versioned, ${result.unchanged} unchanged.`);
+  if (result.plans?.length) console.log(`   Plans: ${result.plans.join(', ')}`);
+}
+
+async function backfill() {
+  const result = await request('POST', 'Entitlements/admin/backfill-subscriptions');
+  console.log(`✅ Backfill: ${result.inserted} inserted, ${result.skipped} already existed, ${result.unknownPlan} skipped (unknown plan).`);
+}
+
+async function reconcile(args) {
+  if (!args.site) {
+    console.error('Usage: velaro entitlement reconcile --site 1032');
+    process.exit(1);
+  }
+  const result = await request('GET', `Entitlements/admin/reconcile/${args.site}`);
+  const status = result.deltaCount === 0
+    ? `✅ ZERO deltas — site ${args.site} is ready for entitlements cutover`
+    : `⚠️  ${result.deltaCount} delta(s) — NOT ready for cutover`;
+  console.log(`\n${status}`);
+  console.log(`Plan: ${result.planKey || 'none'} | Flags checked: ${result.totalFlags} | Matching: ${result.matching}`);
+  if (result.deltas?.length) {
+    console.log('\nDeltas:');
+    for (const d of result.deltas)
+      console.log(`  ${d.featureKey}: Subscription=${d.subscriptionValue} → Entitlements=${d.entitlementValue}`);
+  }
+}
+
+async function listCutover() {
+  const result = await request('GET', 'Entitlements/admin/cutover');
+  console.log(`\nCutover flags: ${result.liveCount} live / ${result.total} total`);
+  const live = (result.flags || []).filter(f => f.isLive);
+  const pending = (result.flags || []).filter(f => !f.isLive);
+  if (live.length) {
+    console.log('\n✅ Live (messaging reads admin instead of Subscription.cs):');
+    for (const f of live) console.log(`  ${f.featureKey}  (since ${f.wentLiveAt?.slice(0,10) || 'n/a'})`);
+  }
+  if (pending.length) {
+    console.log(`\n⏸  Not live (${pending.length} flags) — use 'set-cutover' to flip`);
+  }
+}
+
+async function setCutover(args) {
+  if (!args.key) {
+    console.error('Usage: velaro entitlement set-cutover --key EnableIvr --live [--rollback]');
+    process.exit(1);
+  }
+  const isLive = !args.rollback;
+  const result = await request('PUT', `Entitlements/admin/cutover/${args.key}`, { isLive });
+  console.log(result.message);
+}
+
+export function entitlementCommand(yargs) {
+  return yargs
+    .command('get', 'Get resolved feature set for a site', y => y
+      .option('site',  { type: 'number', demandOption: true, desc: 'Site ID' })
+      .option('all',   { type: 'boolean', desc: 'Show disabled features too (default: enabled only)' })
+    , a => getSite(a))
+    .command('list-features', 'List all registered entitlement feature keys', () => {}, () => listFeatures())
+    .command('set-override', 'Enable or disable a feature for a specific site (overrides plan)', y => y
+      .option('site',   { type: 'number',  demandOption: true, desc: 'Site ID' })
+      .option('key',    { type: 'string',  demandOption: true, desc: 'Feature key, e.g. EnableIvr' })
+      .option('value',  { type: 'string',  demandOption: true, desc: 'true or false' })
+      .option('reason', { type: 'string',  desc: 'Reason / notes for the override' })
+    , a => setOverride(a))
+    .command('remove-override', 'Remove a per-site override, reverting to plan default', y => y
+      .option('site', { type: 'number', demandOption: true, desc: 'Site ID' })
+      .option('key',  { type: 'string', demandOption: true, desc: 'Feature key to un-override' })
+    , a => removeOverride(a))
+    .command('seed', 'Seed the EntitlementFeature registry (idempotent, superadmin only)', () => {}, () => seed())
+    .command('seed-plans', 'Seed PlanEntitlement rows from live PackageVersions in messaging DB (idempotent, superadmin only)', () => {}, () => seedPlans())
+    .command('backfill', 'Backfill SiteSubscription rows from active Subscription rows in messaging DB (idempotent, superadmin only)', () => {}, () => backfill())
+    .command('reconcile', 'Diff Subscription.cs vs Entitlements API for a site — zero deltas = ready for cutover', y => y
+      .option('site', { type: 'number', demandOption: true, desc: 'Site ID' })
+    , a => reconcile(a))
+    .command('comp', 'Comp a site on a plan (creates a SiteSubscription so overrides can be set)', y => y
+      .option('site',  { type: 'number', demandOption: true, desc: 'Site ID' })
+      .option('plan',  { type: 'string', demandOption: true, desc: 'Plan key, e.g. plan.professional' })
+      .option('until', { type: 'string', desc: 'ISO 8601 comp expiry date (omit for indefinite)' })
+      .option('notes', { type: 'string', desc: 'Internal notes' })
+    , a => compSite(a))
+    .command('list-cutover', 'List all feature keys and whether they are live (messaging reads admin) or not (Subscription.cs)', () => {}, () => listCutover())
+    .command('set-cutover', 'Flip a feature key live (or roll it back). Live = messaging reads admin value within 45s. --rollback reverts to Subscription.cs.', y => y
+      .option('key',      { type: 'string',  demandOption: true, desc: 'Feature key, e.g. EnableIvr' })
+      .option('rollback', { type: 'boolean', desc: 'Pass to roll back this flag to Subscription.cs (default: go live)' })
+    , a => setCutover(a))
+    .demandCommand(1, 'Specify a subcommand: get | list-features | set-override | remove-override | seed | seed-plans | backfill | reconcile | comp | list-cutover | set-cutover');
+}

package/lib/commands/env.js

@@ -1,45 +1,45 @@
-import { readConfig, setActiveEnv, getActiveEnv, ENVS } from '../config.js';
-import { runCommand } from '../run.js';
-
-export const envCommand = {
-  command:  'env [name]',
-  describe: 'Show or switch the active environment (prod/staging)',
-  builder:  (y) =>
-    y.positional('name', {
-      describe: 'Environment to switch to: prod or staging',
-      type:     'string',
-      choices:  ['prod', 'staging'],
-    }),
-
-  handler: runCommand(async (argv) => {
-    if (argv.name) {
-      setActiveEnv(argv.name);
-      console.log(`Switched to ${argv.name}.`);
-      console.log(`All velaro commands now target: ${ENVS[argv.name].adminApiBase}`);
-      return;
-    }
-
-    // Show status of all environments
-    const cfg    = readConfig();
-    const active = cfg.activeEnv || 'prod';
-    const envs   = cfg.envs || {};
-
-    console.log('Velaro environments:\n');
-    for (const [name, urls] of Object.entries(ENVS)) {
-      const creds   = envs[name];
-      const marker  = name === active ? '▶ ' : '  ';
-      const status  = creds?.velaroToken
-        ? `logged in as ${creds.userName ?? 'unknown'} (site ${creds.siteId})`
-        : 'not logged in';
-      const expiry  = creds?.velaroExpires
-        ? new Date(creds.velaroExpires) > new Date() ? '' : '  ⚠ token expired'
-        : '';
-      console.log(`${marker}${name.padEnd(10)} ${status}${expiry}`);
-      console.log(`          ${urls.adminApiBase}`);
-    }
-
-    console.log(`\nActive: ${active}`);
-    console.log('\nTo switch:  velaro env staging  |  velaro env prod');
-    console.log('To log in:  velaro login         |  velaro login --staging');
-  }),
-};
+import { readConfig, setActiveEnv, getActiveEnv, ENVS } from '../config.js';
+import { runCommand } from '../run.js';
+
+export const envCommand = {
+  command:  'env [name]',
+  describe: 'Show or switch the active environment (prod/staging)',
+  builder:  (y) =>
+    y.positional('name', {
+      describe: 'Environment to switch to: prod or staging',
+      type:     'string',
+      choices:  ['prod', 'staging'],
+    }),
+
+  handler: runCommand(async (argv) => {
+    if (argv.name) {
+      setActiveEnv(argv.name);
+      console.log(`Switched to ${argv.name}.`);
+      console.log(`All velaro commands now target: ${ENVS[argv.name].adminApiBase}`);
+      return;
+    }
+
+    // Show status of all environments
+    const cfg    = readConfig();
+    const active = cfg.activeEnv || 'prod';
+    const envs   = cfg.envs || {};
+
+    console.log('Velaro environments:\n');
+    for (const [name, urls] of Object.entries(ENVS)) {
+      const creds   = envs[name];
+      const marker  = name === active ? '▶ ' : '  ';
+      const status  = creds?.velaroToken
+        ? `logged in as ${creds.userName ?? 'unknown'} (site ${creds.siteId})`
+        : 'not logged in';
+      const expiry  = creds?.velaroExpires
+        ? new Date(creds.velaroExpires) > new Date() ? '' : '  ⚠ token expired'
+        : '';
+      console.log(`${marker}${name.padEnd(10)} ${status}${expiry}`);
+      console.log(`          ${urls.adminApiBase}`);
+    }
+
+    console.log(`\nActive: ${active}`);
+    console.log('\nTo switch:  velaro env staging  |  velaro env prod');
+    console.log('To log in:  velaro login         |  velaro login --staging');
+  }),
+};

package/lib/commands/feature-discovery.js

@@ -0,0 +1,40 @@
+// velaro feature-discovery — non-nag "features on other plans this account doesn't have yet" nudge.
+// Site scoping is server-side (FeatureDiscoveryController derives siteId from the logged-in
+// identity) — this CLI never passes a siteId, same as the messaging/entitlement site-scoped calls.
+import { request } from '../api.js';
+
+async function list() {
+  const result = await request('GET', 'FeatureDiscovery/suggestions');
+  const suggestions = result?.suggestions ?? [];
+
+  if (!suggestions.length) {
+    console.log(`\nNo feature-discovery suggestions right now (newCount: ${result?.newCount ?? 0}).`);
+    return;
+  }
+
+  console.log(`\nFeature discovery suggestions (newCount: ${result.newCount}):\n`);
+  for (const s of suggestions) {
+    const badge = s.isNew ? '🆕' : '  ';
+    const pkg = s.contactSales ? ' [Contact Sales]' : s.pricingPackageKey ? ` [package: ${s.pricingPackageKey}]` : '';
+    console.log(`${badge} ${s.featureKey.padEnd(30)} ${s.pitchCopy}${pkg}`);
+  }
+}
+
+async function requestFeature(args) {
+  const featureKey = args.featureKey || args._?.[1];
+  if (!featureKey) {
+    console.error('Usage: velaro feature-discovery request <featureKey>');
+    process.exit(1);
+  }
+  const result = await request('POST', `FeatureDiscovery/${featureKey}/request`, {});
+  console.log(`✅ Request submitted for "${featureKey}" (requestId: ${result.requestId}, status: ${result.status})`);
+}
+
+export function featureDiscoveryCommand(yargs) {
+  return yargs
+    .command('list', 'List this site\'s current feature-discovery suggestions', () => {}, () => list())
+    .command('request <featureKey>', 'Submit "I\'m interested" for a suggested feature', y => y
+      .positional('featureKey', { type: 'string', desc: 'Feature key from "list", e.g. EnableIvr' })
+    , a => requestFeature(a))
+    .demandCommand(1, 'Specify a subcommand: list | request');
+}

package/lib/commands/focus.js

@@ -0,0 +1,278 @@
+import { messagingGet, messagingPost, messagingPut } from '../api.js';
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+const RESET = '\x1b[0m';
+const BOLD  = '\x1b[1m';
+const DIM   = '\x1b[2m';
+const CYN   = '\x1b[36m';
+const YEL   = '\x1b[33m';
+const GRN   = '\x1b[32m';
+
+function fmtDate(iso) {
+  if (!iso) return '—';
+  return new Date(iso).toLocaleString('en-US', { timeZone: 'America/Los_Angeles', dateStyle: 'short', timeStyle: 'short' });
+}
+
+const STAGE_COLORS = {
+  new:            '\x1b[37m',
+  submitted:      CYN,
+  offer_received: YEL,
+  negotiating:    '\x1b[35m',
+  confirmed:      GRN,
+  declined:       '\x1b[31m',
+};
+
+function stageLabel(stage) {
+  const color = STAGE_COLORS[stage] ?? RESET;
+  return `${color}${(stage ?? '—').padEnd(16)}${RESET}`;
+}
+
+// ── snoozed ───────────────────────────────────────────────────────────────────
+
+const snoozedCommand = {
+  command:  'snoozed',
+  describe: 'List all currently snoozed conversations',
+  builder:  (y) => y,
+  handler:  async () => {
+    const data = await messagingGet('/Focus/conversations/snoozed');
+    const items = Array.isArray(data) ? data : [];
+
+    console.log(`\n${BOLD}── Snoozed Conversations ──────────────────────────────────────────────${RESET}`);
+    if (!items.length) {
+      console.log(`  ${DIM}No snoozed conversations.${RESET}\n`);
+      return;
+    }
+
+    const idW      = String(items.reduce((m, i) => Math.max(m, String(i.id).length), 2)).length + 2;
+    const nameW    = 24;
+    const chanW    = 14;
+
+    console.log(
+      `  ${DIM}${'ID'.padEnd(idW)}  ${'Contact'.padEnd(nameW)}  ${'Channel'.padEnd(chanW)}  Snoozed Until${RESET}`
+    );
+    for (const item of items) {
+      const name = (item.contactName ?? '—').slice(0, nameW).padEnd(nameW);
+      const chan  = (item.channel    ?? '—').slice(0, chanW).padEnd(chanW);
+      console.log(
+        `  ${CYN}${String(item.id).padEnd(idW)}${RESET}  ${name}  ${DIM}${chan}${RESET}  ${YEL}${fmtDate(item.snoozedUntil)}${RESET}`
+      );
+    }
+    console.log();
+  },
+};
+
+// ── follow-ups ────────────────────────────────────────────────────────────────
+
+const followUpsCommand = {
+  command:  'follow-ups',
+  describe: 'List follow-ups due in the next 24 hours',
+  builder:  (y) => y,
+  handler:  async () => {
+    const data  = await messagingGet('/Focus/conversations/follow-ups');
+    const items = Array.isArray(data) ? data : [];
+
+    console.log(`\n${BOLD}── Follow-Ups Due (next 24h) ───────────────────────────────────────────${RESET}`);
+    if (!items.length) {
+      console.log(`  ${DIM}No follow-ups due in the next 24 hours.${RESET}\n`);
+      return;
+    }
+
+    for (const item of items) {
+      const name = item.contactName ?? '—';
+      console.log(
+        `  ${CYN}#${item.id}${RESET}  ${name.padEnd(24)}  ${DIM}${(item.channel ?? '—').padEnd(14)}${RESET}  ${YEL}${fmtDate(item.followUpAt)}${RESET}`
+      );
+    }
+    console.log();
+  },
+};
+
+// ── clusters ──────────────────────────────────────────────────────────────────
+
+const clustersCommand = {
+  command:  'clusters',
+  describe: 'List all saved conversation clusters',
+  builder:  (y) => y,
+  handler:  async () => {
+    const data  = await messagingGet('/Focus/clusters');
+    const items = Array.isArray(data) ? data : [];
+
+    console.log(`\n${BOLD}── Focus Clusters ─────────────────────────────────────────────────────${RESET}`);
+    if (!items.length) {
+      console.log(`  ${DIM}No clusters saved yet.${RESET}\n`);
+      return;
+    }
+
+    for (const c of items) {
+      const ids   = Array.isArray(c.conversationIds) ? c.conversationIds : JSON.parse(c.conversationIds || '[]');
+      const val   = c.estimatedValue != null ? `  ${GRN}$${c.estimatedValue.toLocaleString()}${RESET}` : '';
+      const updated = fmtDate(c.updatedAt);
+      console.log(
+        `  ${CYN}#${c.id}${RESET}  ${BOLD}${c.title}${RESET}\n` +
+        `       Stage: ${stageLabel(c.stage)}  Conversations: ${ids.length}${val}  Updated: ${DIM}${updated}${RESET}`
+      );
+    }
+    console.log();
+  },
+};
+
+// ── cluster-stage ─────────────────────────────────────────────────────────────
+
+const VALID_STAGES = ['new', 'submitted', 'offer_received', 'negotiating', 'confirmed', 'declined'];
+
+const clusterStageCommand = {
+  command:  'cluster-stage <id> <stage>',
+  describe: 'Move a cluster to a different pipeline stage',
+  builder:  (y) => y
+    .positional('id',    { type: 'number', describe: 'Cluster ID' })
+    .positional('stage', { type: 'string', describe: `Pipeline stage: ${VALID_STAGES.join(', ')}` }),
+  handler:  async (argv) => {
+    const { id, stage } = argv;
+    if (!VALID_STAGES.includes(stage)) {
+      console.error(`Invalid stage "${stage}". Valid values: ${VALID_STAGES.join(', ')}`);
+      process.exit(1);
+    }
+    const result = await messagingPut(`/Focus/clusters/${id}/stage`, { stage });
+    const color  = STAGE_COLORS[result?.stage ?? stage] ?? RESET;
+    console.log(`\n  ${GRN}✓${RESET} Cluster #${result?.id ?? id} moved to ${color}${result?.stage ?? stage}${RESET}\n`);
+  },
+};
+
+// ── auto-reply report ────────────────────────────────────────────────────────
+
+function pct(used, max) {
+  if (!max) return '0%';
+  return `${Math.round((used / max) * 100)}%`;
+}
+
+function bar(count, maxCount, width = 24) {
+  if (maxCount <= 0) return DIM + '·'.repeat(width) + RESET;
+  const filled = Math.round((count / maxCount) * width);
+  return CYN + '█'.repeat(filled) + DIM + '·'.repeat(width - filled) + RESET;
+}
+
+const reportCommand = {
+  command:  'report',
+  describe: 'AI auto-reply funnel report: auto-resolved vs escalated, confidence distribution, usage vs cap',
+  builder:  (y) => y
+    .option('from',    { type: 'string', describe: 'ISO 8601 start of range (default: 30 days before --to)' })
+    .option('to',      { type: 'string', describe: 'ISO 8601 end of range (default: now)' })
+    .option('channel', { type: 'string', choices: ['All', 'Email', 'TicketGeneral'], default: 'All', describe: 'Filter by channel' }),
+  handler:  async (argv) => {
+    const qs = new URLSearchParams();
+    if (argv.from) qs.set('from', argv.from);
+    if (argv.to) qs.set('to', argv.to);
+    if (argv.channel) qs.set('channel', argv.channel);
+    const r = await messagingGet(`/Focus/AutoReply/Report?${qs.toString()}`);
+
+    console.log(`\n${BOLD}── AI Auto-Reply Report ────────────────────────────────────────────────${RESET}`);
+    console.log(`  ${DIM}${fmtDate(r.from)} to ${fmtDate(r.to)}  |  Channel: ${r.channel}${RESET}\n`);
+
+    console.log(`  ${BOLD}Total eligible:${RESET} ${r.totalEligible}`);
+    console.log(`  ${GRN}Auto-resolved:${RESET}  ${r.autoResolved.total}  ${DIM}(Email: ${r.autoResolved.email}, Ticket: ${r.autoResolved.ticketGeneral})${RESET}`);
+    console.log(`  ${YEL}Escalated:${RESET}      ${r.escalated.total}  ${DIM}(all below-confidence; ${r.escalated.explicitEscalationTrigger} of these explicitly told the customer)${RESET}`);
+    console.log(`  Negative follow-ups after auto-reply: ${r.negativeFollowUpCount}\n`);
+
+    console.log(`  ${BOLD}Confidence distribution${RESET}`);
+    const maxCount = Math.max(1, ...r.confidenceDistribution.map((b) => b.count));
+    for (const b of r.confidenceDistribution) {
+      const label = `${String(b.bucketMin).padStart(3)}-${String(b.bucketMax).padStart(3)}`;
+      console.log(`    ${DIM}${label}${RESET}  ${bar(b.count, maxCount)}  ${b.count}`);
+    }
+
+    console.log(`\n  ${BOLD}Usage${RESET}  ${r.usage.used} / ${r.usage.max} ${r.usage.metric} this period (${pct(r.usage.used, r.usage.max)})`);
+    if (r.usage.percent > 90) {
+      console.log(`  ${YEL}Warning: approaching the auto-reply cap. Consider raising the plan limit or the confidence threshold.${RESET}`);
+    }
+    console.log();
+  },
+};
+
+// ── triage-rules (#582 Phase B) ──────────────────────────────────────────────
+//
+// SECURITY: the label set is fixed (urgent/needs_reply/offer/fyi/waiting). This command only
+// ever sends a boolean enable/disable per fixed label, never free text. See CLAUDE.md's Moshky
+// AI safety rule and ConversationTriageService's prompt assembly (velaro-messaging).
+
+const VALID_LABELS = ['urgent', 'needs_reply', 'offer', 'fyi', 'waiting'];
+
+const triageRulesCommand = {
+  command:  'triage-rules',
+  describe: 'Show which AI triage labels are enabled and current per-channel priority weights',
+  builder:  (y) => y,
+  handler:  async () => {
+    const data = await messagingGet('/Focus/triage-rules');
+
+    console.log(`\n${BOLD}── AI Triage Rules ─────────────────────────────────────────────────────${RESET}`);
+    console.log(`  ${BOLD}Labels${RESET}`);
+    for (const l of data.labels ?? []) {
+      const mark = l.enabled ? `${GRN}on${RESET} ` : `${DIM}off${RESET}`;
+      console.log(`    ${mark}  ${l.enabled ? '' : DIM}${l.label}${RESET}`);
+    }
+    console.log(`\n  ${BOLD}Channels${RESET}  ${DIM}(edit via focus channel-config)${RESET}`);
+    for (const c of data.channels ?? []) {
+      const triage = c.triageEnabled ? `${GRN}on${RESET}` : `${DIM}off${RESET}`;
+      console.log(`    ${(c.channel ?? '—').padEnd(12)}  triage: ${triage}  weight: ${c.priorityWeight}x`);
+    }
+    console.log();
+  },
+};
+
+const setTriageRuleCommand = {
+  command:  'set-triage-rule <label> <enabled>',
+  describe: `Enable or disable one fixed AI triage label (${VALID_LABELS.join(', ')})`,
+  builder:  (y) => y
+    .positional('label',   { type: 'string', describe: `Label: ${VALID_LABELS.join(', ')}` })
+    .positional('enabled', { type: 'string', describe: 'true or false', choices: ['true', 'false'] }),
+  handler:  async (argv) => {
+    const { label, enabled } = argv;
+    if (!VALID_LABELS.includes(label)) {
+      console.error(`Invalid label "${label}". Valid values: ${VALID_LABELS.join(', ')}`);
+      process.exit(1);
+    }
+    const result = await messagingPut('/Focus/triage-rules', [{ Label: label, Enabled: enabled === 'true' }]);
+    console.log(`\n  ${GRN}✓${RESET} Label "${label}" ${enabled === 'true' ? 'enabled' : 'disabled'}. Effective labels: ${(result?.effectiveLabels ?? []).join(', ')}\n`);
+  },
+};
+
+// ── draft-pregeneration report ("Always Learning" addon, issue #582 Phase D) ───
+// Entitlements-gated (EnableFocusDraftPregeneration), not a Subscription.cs flag --
+// `entitled` on the response is the source of truth for whether the site has it.
+
+const draftPregenerationReportCommand = {
+  command:  'draft-pregeneration-report',
+  describe: 'Draft pregeneration usage/cap report ("Always Learning" addon) -- entitled status plus used/max/percent',
+  builder:  (y) => y,
+  handler:  async () => {
+    const r = await messagingGet('/Focus/DraftPregeneration/Report');
+
+    console.log(`\n${BOLD}── Draft Pregeneration Report ──────────────────────────────────────────${RESET}`);
+    console.log(`  ${BOLD}Status:${RESET} ${r.entitled ? `${GRN}Active${RESET}` : `${DIM}Not included in your plan${RESET}`}\n`);
+
+    console.log(`  ${BOLD}Usage${RESET}  ${r.usage.used} / ${r.usage.max} ${r.usage.metric} this period (${pct(r.usage.used, r.usage.max)})`);
+    if (r.usage.percent > 90) {
+      console.log(`  ${YEL}Warning: approaching the draft pregeneration cap. Contact support to raise the plan limit.${RESET}`);
+    }
+    console.log();
+  },
+};
+
+// ── top-level focus command ───────────────────────────────────────────────────
+
+export const focusCommand = {
+  command:  'focus <subcommand>',
+  describe: 'Focus Inbox: snooze, follow-ups, conversation clusters, AI triage rules, and the AI auto-reply / draft pregeneration reports',
+  builder:  (y) => y
+    .command(snoozedCommand)
+    .command(followUpsCommand)
+    .command(clustersCommand)
+    .command(clusterStageCommand)
+    .command(reportCommand)
+    .command(triageRulesCommand)
+    .command(setTriageRuleCommand)
+    .command(draftPregenerationReportCommand)
+    .demandCommand(1, 'Specify a focus subcommand.')
+    .strict(),
+  handler:  () => {},
+};

package/lib/commands/index.js

@@ -1,4 +1,4 @@
-import { get, post, getCredentials } from '../api.js';
+import { get, post, getCredentials, messagingGet, messagingPost } from '../api.js';
 
 // ── helpers ──────────────────────────────────────────────────────────────────
 
@@ -69,7 +69,7 @@ const listCommand = {
       // ── Customer: show their virtual indexes + quota ────────────────────────
       const siteId = argv.site ?? creds.siteId;
       const [indexes, breakdown] = await Promise.all([
-        get('/AzureIndexes/List'),
+        messagingGet('/AzureIndexes/List'),
         get(`/DatabaseTool/SearchIndexSite?siteId=${siteId}`).catch(() => null),
       ]);
 
@@ -171,7 +171,7 @@ const reingestCommand = {
     // Check quota before allowing reingest
     const sub = await get('/Subscription/Get').catch(() => null);
     if (!isVelaroAdmin(creds) && sub?.maxIndexedChunkTotal > 0) {
-      const indexes = await get('/AzureIndexes/List').catch(() => []);
+      const indexes = await messagingGet('/AzureIndexes/List').catch(() => []);
       const usedChunks = indexes.reduce((s, i) => s + (i.documentCount ?? 0), 0);
       if (usedChunks >= sub.maxIndexedChunkTotal) {
         console.error(`\x1b[31m✗ Index quota full (${usedChunks.toLocaleString()} / ${sub.maxIndexedChunkTotal.toLocaleString()} chunks).\x1b[0m`);
@@ -186,7 +186,7 @@ const reingestCommand = {
     for (const source of sources) {
       try {
         console.log(`  Syncing ${source}...`);
-        await post(`/AzureIndexes/SyncIntegration${siteParam}`, { source, forceAll: true });
+        await messagingPost(`/AzureIndexes/SyncIntegration${siteParam}`, { source, forceAll: true });
         console.log(`  \x1b[32m✓ ${source} queued\x1b[0m`);
       } catch (e) {
         console.log(`  \x1b[33m⚠ ${source} skipped: ${e.message}\x1b[0m`);
@@ -196,6 +196,38 @@ const reingestCommand = {
   },
 };
 
+// ── test ─────────────────────────────────────────────────────────────────────
+
+const testCommand = {
+  command:  'test <query>',
+  describe: 'Run a content-search query against your site\'s index and show results',
+  builder:  (y) =>
+    y
+      .positional('query', { type: 'string', describe: 'Search query' })
+      .option('top', { type: 'number', default: 5, describe: 'Number of results to return' })
+      .option('site', { type: 'number', describe: 'Site ID override (Velaro staff only)' }),
+  handler: async (argv) => {
+    const creds = await getCredentials();
+    const siteParam = isVelaroAdmin(creds) && argv.site ? `&siteId=${argv.site}` : '';
+    const qs = `q=${encodeURIComponent(argv.query)}&top=${argv.top}${siteParam}`;
+
+    console.log(`\nSearching index for: "${argv.query}"\n`);
+    const results = await messagingGet(`/AzureIndexes/content-search?${qs}`);
+
+    if (!results?.length) {
+      console.log('  No results found. Index may be empty — run `velaro ingest --job-id <id>` first.');
+      return;
+    }
+
+    for (let i = 0; i < results.length; i++) {
+      const r = results[i];
+      console.log(`\x1b[1m[${i + 1}] ${r.label ?? r.sourceId ?? 'unknown'}\x1b[0m`);
+      console.log(`  type: ${r.contentType ?? 'unknown'}  index: ${r.indexName ?? ''}  id: ${r.sourceId ?? ''}`);
+      console.log('');
+    }
+  },
+};
+
 // ── export ────────────────────────────────────────────────────────────────────
 
 export const indexCommand = {
@@ -207,6 +239,7 @@ export const indexCommand = {
       .command(siteCommand)
       .command(provisionCommand)
       .command(reingestCommand)
-      .demandCommand(1, 'Specify a subcommand: list, site, provision, reingest'),
+      .command(testCommand)
+      .demandCommand(1, 'Specify a subcommand: list, site, provision, reingest, test'),
   handler: () => {},
 };