@operor/cli 0.1.0

package/src/commands/analytics.ts

@@ -0,0 +1,408 @@
+import { Command } from 'commander';
+import * as clack from '@clack/prompts';
+import { readConfig, configExists } from '../config.js';
+
+function getAnalyticsConfig() {
+  if (!configExists()) {
+    clack.log.error('.env file not found. Run "operor setup" first.');
+    process.exit(1);
+  }
+  const config = readConfig();
+  if (config.ANALYTICS_ENABLED === 'false') {
+    clack.log.error('Analytics is disabled. Set ANALYTICS_ENABLED=true in .env.');
+    process.exit(1);
+  }
+  return config;
+}
+
+async function loadStore(config: ReturnType<typeof readConfig>) {
+  try {
+    const { SQLiteAnalyticsStore } = await import('@operor/analytics');
+    const store = new SQLiteAnalyticsStore(config.ANALYTICS_DB_PATH || './analytics.db');
+    await store.initialize();
+    return store;
+  } catch {
+    clack.log.error(
+      '@operor/analytics package not found. Install it first:\n  pnpm add @operor/analytics',
+    );
+    process.exit(1);
+  }
+}
+
+function makeRange(days: number): { from: number; to: number } {
+  const to = Date.now();
+  const from = to - days * 24 * 60 * 60 * 1000;
+  return { from, to };
+}
+
+/** Simple sparkline from an array of numbers */
+function sparkline(values: number[]): string {
+  if (values.length === 0) return '';
+  const chars = '▁▂▃▄▅▆▇█';
+  const max = Math.max(...values);
+  if (max === 0) return chars[0].repeat(values.length);
+  return values.map(v => chars[Math.min(Math.floor((v / max) * (chars.length - 1)), chars.length - 1)]).join('');
+}
+
+/** Simple horizontal bar */
+function bar(value: number, max: number, width = 30): string {
+  if (max === 0) return '';
+  const filled = Math.round((value / max) * width);
+  return '█'.repeat(filled) + '░'.repeat(width - filled);
+}
+
+function maskPhone(phone: string): string {
+  if (phone.length <= 6) return '***' + phone.slice(-3);
+  return phone.slice(0, 3) + '***' + phone.slice(-3);
+}
+
+function fmtMs(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+function fmtPct(pct: number): string {
+  return `${pct.toFixed(1)}%`;
+}
+
+export function registerAnalyticsCommand(program: Command): void {
+  const analytics = program.command('analytics').description('Usage analytics and insights');
+
+  // Default: summary dashboard
+  analytics
+    .option('--days <n>', 'Number of days to include', '7')
+    .action(async (opts: { days: string }) => {
+      clack.intro('Analytics — Dashboard');
+      const config = getAnalyticsConfig();
+      const store = await loadStore(config);
+      const range = makeRange(parseInt(opts.days));
+
+      try {
+        const [summary, volume, agents] = await Promise.all([
+          store.getSummary(range),
+          store.getMessageVolume(range, 'day'),
+          store.getAgentStats(range),
+        ]);
+
+        if (summary.totalMessages === 0) {
+          clack.log.info('No messages recorded in this period.');
+          return;
+        }
+
+        // Messages
+        const trend = sparkline(volume.map(v => v.count));
+        clack.log.info(`  Messages`);
+        clack.log.info(`    Total:       ${summary.totalMessages}`);
+        clack.log.info(`    Avg/day:     ${summary.avgPerDay.toFixed(1)}`);
+        clack.log.info(`    Peak day:    ${summary.peakDay || '—'}`);
+        clack.log.info(`    Trend:       ${trend}`);
+
+        // Response quality
+        clack.log.info('');
+        clack.log.info(`  Response Quality`);
+        clack.log.info(`    KB answered:   ${fmtPct(summary.kbAnsweredPct)}`);
+        clack.log.info(`    LLM fallback:  ${fmtPct(summary.llmFallbackPct)}`);
+        clack.log.info(`    No answer:     ${fmtPct(summary.noAnswerPct)}`);
+        clack.log.info(`    Avg response:  ${fmtMs(summary.avgResponseTime)}`);
+        clack.log.info(`    FAQ hit rate:  ${fmtPct(summary.faqHitRate)}`);
+
+        // Customers
+        clack.log.info('');
+        clack.log.info(`  Customers`);
+        clack.log.info(`    Unique:      ${summary.uniqueCustomers}`);
+        clack.log.info(`    New:         ${summary.newCustomers}`);
+        clack.log.info(`    Returning:   ${summary.returningCustomers}`);
+        if (summary.uniqueCustomers > 0) {
+          clack.log.info(`    Avg msgs:    ${(summary.totalMessages / summary.uniqueCustomers).toFixed(1)}/customer`);
+        }
+
+        // Agents
+        if (agents.length > 0) {
+          clack.log.info('');
+          clack.log.info(`  Agents`);
+          for (const a of agents) {
+            const pct = summary.totalMessages > 0
+              ? ((a.messageCount / summary.totalMessages) * 100).toFixed(1)
+              : '0.0';
+            clack.log.info(`    ${a.agentName.padEnd(20)} ${String(a.messageCount).padStart(5)} msgs (${pct}%)  avg ${fmtMs(a.avgResponseTimeMs)}`);
+          }
+        }
+
+        // Copilot
+        if (summary.pendingReviews > 0) {
+          clack.log.info('');
+          clack.log.info(`  Copilot`);
+          clack.log.info(`    Pending reviews: ${summary.pendingReviews}`);
+        }
+      } catch (error: any) {
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        await store.close();
+      }
+      clack.outro('');
+    });
+
+  // Messages subcommand
+  analytics
+    .command('messages')
+    .description('Message volume breakdown')
+    .option('--days <n>', 'Number of days to include', '7')
+    .action(async (opts: { days: string }) => {
+      clack.intro('Analytics — Messages');
+      const config = getAnalyticsConfig();
+      const store = await loadStore(config);
+      const days = parseInt(opts.days);
+      const range = makeRange(days);
+
+      try {
+        const [daily, hourly] = await Promise.all([
+          store.getMessageVolume(range, 'day'),
+          store.getMessageVolume(makeRange(1), 'hour'),
+        ]);
+
+        if (daily.length === 0) {
+          clack.log.info('No messages recorded in this period.');
+          return;
+        }
+
+        // Daily breakdown
+        const maxDaily = Math.max(...daily.map(d => d.count));
+        clack.log.info('  Daily Volume');
+        for (const d of daily) {
+          clack.log.info(`    ${d.date}  ${bar(d.count, maxDaily, 25)} ${d.count}`);
+        }
+
+        // Hourly distribution (today)
+        if (hourly.length > 0) {
+          const maxHourly = Math.max(...hourly.map(h => h.count));
+          clack.log.info('');
+          clack.log.info('  Today — Hourly');
+          for (const h of hourly) {
+            const hour = h.date.split(' ')[1] || h.date;
+            clack.log.info(`    ${hour}  ${bar(h.count, maxHourly, 20)} ${h.count}`);
+          }
+        }
+      } catch (error: any) {
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        await store.close();
+      }
+      clack.outro('');
+    });
+
+  // Agents subcommand
+  analytics
+    .command('agents')
+    .description('Per-agent performance breakdown')
+    .option('--days <n>', 'Number of days to include', '7')
+    .action(async (opts: { days: string }) => {
+      clack.intro('Analytics — Agents');
+      const config = getAnalyticsConfig();
+      const store = await loadStore(config);
+      const range = makeRange(parseInt(opts.days));
+
+      try {
+        const [agents, summary] = await Promise.all([
+          store.getAgentStats(range),
+          store.getSummary(range),
+        ]);
+
+        if (agents.length === 0) {
+          clack.log.info('No agent activity in this period.');
+          return;
+        }
+
+        const header = `${'Agent'.padEnd(22)} ${'Msgs'.padStart(6)} ${'%'.padStart(6)} ${'Avg Time'.padStart(10)} ${'Confidence'.padStart(11)} ${'Escalations'.padStart(12)} ${'Tools'.padStart(6)}`;
+        clack.log.info(header);
+        clack.log.info('─'.repeat(header.length));
+
+        for (const a of agents) {
+          const pct = summary.totalMessages > 0
+            ? ((a.messageCount / summary.totalMessages) * 100).toFixed(1)
+            : '0.0';
+          const line = `${a.agentName.padEnd(22)} ${String(a.messageCount).padStart(6)} ${(pct + '%').padStart(6)} ${fmtMs(a.avgResponseTimeMs).padStart(10)} ${fmtPct(a.avgConfidence * 100).padStart(11)} ${String(a.escalationCount).padStart(12)} ${String(a.toolCallCount).padStart(6)}`;
+          clack.log.info(line);
+        }
+      } catch (error: any) {
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        await store.close();
+      }
+      clack.outro('');
+    });
+
+  // Customers subcommand
+  analytics
+    .command('customers')
+    .description('Customer engagement metrics')
+    .option('--days <n>', 'Number of days to include', '7')
+    .option('-n, --limit <n>', 'Top customers to show', '10')
+    .action(async (opts: { days: string; limit: string }) => {
+      clack.intro('Analytics — Customers');
+      const config = getAnalyticsConfig();
+      const store = await loadStore(config);
+      const range = makeRange(parseInt(opts.days));
+
+      try {
+        const [customers, summary] = await Promise.all([
+          store.getCustomerStats(range, parseInt(opts.limit)),
+          store.getSummary(range),
+        ]);
+
+        if (customers.length === 0) {
+          clack.log.info('No customer activity in this period.');
+          return;
+        }
+
+        clack.log.info(`  Unique:      ${summary.uniqueCustomers}`);
+        clack.log.info(`  New:         ${summary.newCustomers}`);
+        clack.log.info(`  Returning:   ${summary.returningCustomers}`);
+
+        // Engagement distribution
+        const buckets = { '1 msg': 0, '2-5': 0, '6-10': 0, '10+': 0 };
+        for (const c of customers) {
+          if (c.messageCount === 1) buckets['1 msg']++;
+          else if (c.messageCount <= 5) buckets['2-5']++;
+          else if (c.messageCount <= 10) buckets['6-10']++;
+          else buckets['10+']++;
+        }
+        clack.log.info('');
+        clack.log.info('  Engagement Distribution');
+        const maxBucket = Math.max(...Object.values(buckets));
+        for (const [label, count] of Object.entries(buckets)) {
+          clack.log.info(`    ${label.padEnd(8)} ${bar(count, maxBucket, 20)} ${count}`);
+        }
+
+        // Top customers
+        clack.log.info('');
+        clack.log.info('  Top Customers');
+        const header = `${'Phone'.padEnd(16)} ${'Msgs'.padStart(6)} ${'Status'.padStart(8)} ${'Last Seen'.padStart(12)}`;
+        clack.log.info(`    ${header}`);
+        clack.log.info(`    ${'─'.repeat(header.length)}`);
+        for (const c of customers) {
+          const lastSeen = new Date(c.lastSeen).toLocaleDateString();
+          const status = c.isNew ? 'new' : 'return';
+          clack.log.info(`    ${maskPhone(c.customerPhone).padEnd(16)} ${String(c.messageCount).padStart(6)} ${status.padStart(8)} ${lastSeen.padStart(12)}`);
+        }
+      } catch (error: any) {
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        await store.close();
+      }
+      clack.outro('');
+    });
+
+  // KB subcommand
+  analytics
+    .command('kb')
+    .description('Knowledge Base performance metrics')
+    .option('--days <n>', 'Number of days to include', '7')
+    .action(async (opts: { days: string }) => {
+      clack.intro('Analytics — Knowledge Base');
+      const config = getAnalyticsConfig();
+      const store = await loadStore(config);
+      const range = makeRange(parseInt(opts.days));
+
+      try {
+        const kbStats = await store.getKbStats(range);
+
+        if (kbStats.totalQueries === 0) {
+          clack.log.info('No KB queries in this period.');
+          return;
+        }
+
+        clack.log.info(`  Total queries:   ${kbStats.totalQueries}`);
+        clack.log.info(`  FAQ hits:        ${kbStats.faqHits} (${fmtPct(kbStats.faqHitRate)})`);
+        clack.log.info(`  Avg top score:   ${kbStats.avgTopScore.toFixed(4)}`);
+
+        // Pipeline breakdown
+        const hybridCount = kbStats.totalQueries - kbStats.faqHits;
+        clack.log.info('');
+        clack.log.info('  Pipeline Breakdown');
+        clack.log.info(`    FAQ fast-path:  ${kbStats.faqHits}`);
+        clack.log.info(`    Hybrid/LLM:     ${hybridCount}`);
+
+        // Top FAQ hits
+        if (kbStats.topFaqHits.length > 0) {
+          clack.log.info('');
+          clack.log.info('  Top FAQ Hits');
+          for (const h of kbStats.topFaqHits.slice(0, 10)) {
+            clack.log.info(`    ${String(h.count).padStart(4)}x  ${h.intent}`);
+          }
+        }
+
+        // Top misses
+        if (kbStats.topMisses.length > 0) {
+          clack.log.info('');
+          clack.log.info('  Top Misses (consider teaching these)');
+          for (const m of kbStats.topMisses.slice(0, 10)) {
+            clack.log.info(`    ${String(m.count).padStart(4)}x  ${m.intent}  (avg score: ${m.avgScore.toFixed(3)})`);
+          }
+          clack.log.info('');
+          clack.log.info('  Tip: Use "operor kb add-faq <question> <answer>" to teach missed queries.');
+        }
+      } catch (error: any) {
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        await store.close();
+      }
+      clack.outro('');
+    });
+
+  // Export subcommand
+  analytics
+    .command('export')
+    .description('Export analytics data as CSV or JSON')
+    .option('--days <n>', 'Number of days to include', '7')
+    .option('--json', 'Export as JSON instead of CSV')
+    .option('-o, --output <file>', 'Output file path')
+    .action(async (opts: { days: string; json?: boolean; output?: string }) => {
+      clack.intro('Analytics — Export');
+      const config = getAnalyticsConfig();
+      const store = await loadStore(config);
+      const range = makeRange(parseInt(opts.days));
+
+      try {
+        const [summary, volume, agents, customers, kbStats] = await Promise.all([
+          store.getSummary(range),
+          store.getMessageVolume(range, 'day'),
+          store.getAgentStats(range),
+          store.getCustomerStats(range, 100),
+          store.getKbStats(range),
+        ]);
+
+        const data = { summary, volume, agents, customers, kbStats };
+
+        let output: string;
+        if (opts.json) {
+          output = JSON.stringify(data, null, 2);
+        } else {
+          // CSV: export daily volume as the primary table
+          const lines = ['date,messages'];
+          for (const v of volume) {
+            lines.push(`${v.date},${v.count}`);
+          }
+          output = lines.join('\n');
+        }
+
+        if (opts.output) {
+          const { writeFileSync } = await import('node:fs');
+          writeFileSync(opts.output, output);
+          clack.log.success(`Exported to ${opts.output}`);
+        } else {
+          console.log(output);
+        }
+      } catch (error: any) {
+        clack.log.error(error.message);
+        process.exit(1);
+      } finally {
+        await store.close();
+      }
+      clack.outro('');
+    });
+}