@skillrecordings/cli 0.1.0

package/src/commands/faq-extract.ts

@@ -0,0 +1,249 @@
+/**
+ * FAQ Extraction CLI Command
+ *
+ * Extracts FAQ candidates from clustered conversations.
+ * Part of Phase 1.3 of the FAQ Mining pipeline.
+ *
+ * Usage:
+ *   bun src/index.ts faq-extract
+ *   bun src/index.ts faq-extract --app total-typescript --push-redis
+ *   bun src/index.ts faq-extract --dry-run
+ *   bun src/index.ts faq-extract --version v2
+ */
+
+import { existsSync } from 'fs'
+import { join, resolve } from 'path'
+import { createDuckDBSource } from '@skillrecordings/core/faq/duckdb-source'
+import {
+  type ExtractionOptions,
+  extractFaqCandidates,
+} from '@skillrecordings/core/faq/extractor'
+import { closeDb } from '@skillrecordings/database'
+import type { Command } from 'commander'
+
+/** Project root */
+const PROJECT_ROOT = resolve(__dirname, '../../../..')
+
+/** Default paths */
+const DEFAULT_CLUSTERING_PATH = join(
+  PROJECT_ROOT,
+  'artifacts/phase-1/clustering/v1/clustering-result.json'
+)
+const DEFAULT_GOLDEN_PATH = join(
+  PROJECT_ROOT,
+  'artifacts/phase-0/golden/latest/responses.json'
+)
+const DEFAULT_OUTPUT_PATH = join(PROJECT_ROOT, 'artifacts/phase-1/extraction')
+const DEFAULT_CACHE_PATH = `${process.env.HOME}/skill/data/front-cache.db`
+
+/**
+ * Validate required files exist
+ */
+function validatePaths(clusteringPath: string, goldenPath?: string): void {
+  if (!existsSync(clusteringPath)) {
+    throw new Error(
+      `Clustering result not found at ${clusteringPath}\n` +
+        'Run `bun src/index.ts faq-cluster` first to generate clustering.'
+    )
+  }
+
+  if (goldenPath && !existsSync(goldenPath)) {
+    console.warn(`⚠️  Golden responses not found at ${goldenPath}`)
+    console.warn('   Golden matching will be disabled.')
+  }
+}
+
+/**
+ * Main command handler
+ */
+async function faqExtract(options: {
+  clusteringPath?: string
+  goldenPath?: string
+  outputPath?: string
+  cachePath?: string
+  outputVersion?: string
+  minClusterSize?: number
+  topN?: number
+  dedupThreshold?: number
+  pushRedis?: boolean
+  app?: string
+  dryRun?: boolean
+  json?: boolean
+  filters?: boolean
+}): Promise<void> {
+  const clusteringPath = options.clusteringPath ?? DEFAULT_CLUSTERING_PATH
+  const goldenPath = options.goldenPath ?? DEFAULT_GOLDEN_PATH
+  const outputPath = options.outputPath ?? DEFAULT_OUTPUT_PATH
+  const cachePath = options.cachePath ?? DEFAULT_CACHE_PATH
+  const version = options.outputVersion ?? 'v1'
+
+  const applyFilters = options.filters ?? true
+
+  console.log('🔬 FAQ Extraction Pipeline')
+  console.log('='.repeat(60))
+  console.log(`   Clustering:    ${clusteringPath}`)
+  console.log(`   Golden:        ${goldenPath}`)
+  console.log(`   Output:        ${outputPath}`)
+  console.log(`   DuckDB cache:  ${cachePath}`)
+  console.log(`   Version:       ${version}`)
+  console.log(`   Apply filters: ${applyFilters}`)
+  console.log(`   Push to Redis: ${options.pushRedis ?? false}`)
+  console.log(`   Dry run:       ${options.dryRun ?? false}`)
+  console.log('')
+
+  // Validate paths
+  validatePaths(clusteringPath, goldenPath)
+
+  // Check DuckDB cache
+  if (!existsSync(cachePath)) {
+    throw new Error(
+      `DuckDB cache not found at ${cachePath}\n` +
+        'Run `bun src/index.ts front-cache sync` first to populate cache.'
+    )
+  }
+
+  let source
+
+  try {
+    // Create DuckDB source
+    console.log('📦 Connecting to DuckDB cache...')
+    source = await createDuckDBSource({ dbPath: cachePath })
+
+    // Get source stats
+    const stats = await source.getStats?.()
+    if (stats) {
+      console.log(
+        `   ${stats.totalConversations.toLocaleString()} conversations in cache`
+      )
+    }
+
+    // Run extraction
+    const extractionOptions: ExtractionOptions = {
+      clusteringPath,
+      goldenPath: existsSync(goldenPath) ? goldenPath : undefined,
+      source,
+      outputPath,
+      version,
+      minClusterSize: options.minClusterSize ?? 3,
+      topN: options.topN ?? 5,
+      dedupThreshold: options.dedupThreshold ?? 0.85,
+      pushToRedis: options.pushRedis ?? false,
+      appId: options.app,
+      dryRun: options.dryRun ?? false,
+      applyFilters,
+    }
+
+    const result = await extractFaqCandidates(extractionOptions)
+
+    // JSON output
+    if (options.json) {
+      console.log('\n📋 JSON Output:')
+      console.log(JSON.stringify(result.stats, null, 2))
+    }
+
+    // Check acceptance criteria
+    console.log('\n✅ Acceptance Criteria Check:')
+    const highConfidence = result.stats.highConfidenceCount
+    const target = 50
+
+    if (highConfidence >= target) {
+      console.log(
+        `   ✅ ${highConfidence} candidates with confidence ≥ 0.7 (target: ${target})`
+      )
+    } else {
+      console.log(
+        `   ⚠️  Only ${highConfidence} candidates with confidence ≥ 0.7 (target: ${target})`
+      )
+      console.log(
+        '   Consider lowering --min-cluster-size or --dedup-threshold'
+      )
+    }
+
+    console.log(
+      `   ✅ Golden match rate: ${(result.stats.goldenMatchRate * 100).toFixed(1)}%`
+    )
+    console.log(
+      `   ✅ Deduplication working: ${result.stats.deduplicatedCount} removed`
+    )
+
+    if (!options.dryRun) {
+      console.log(`\n✅ Extraction complete!`)
+      console.log(`   Artifacts written to: ${join(outputPath, version)}`)
+
+      if (options.pushRedis && options.app) {
+        console.log(
+          `   Candidates pushed to Redis queue: faq:pending:${options.app}`
+        )
+      }
+    }
+  } catch (error) {
+    console.error(
+      '\n❌ Error:',
+      error instanceof Error ? error.message : String(error)
+    )
+    process.exit(1)
+  } finally {
+    if (source?.close) {
+      await source.close()
+    }
+    await closeDb()
+  }
+}
+
+/**
+ * Register FAQ extraction commands with Commander
+ */
+export function registerFaqExtractCommands(program: Command): void {
+  program
+    .command('faq-extract')
+    .description('Extract FAQ candidates from clustered conversations')
+    .option(
+      '--clustering-path <path>',
+      'Path to clustering result file',
+      DEFAULT_CLUSTERING_PATH
+    )
+    .option(
+      '--golden-path <path>',
+      'Path to golden responses file',
+      DEFAULT_GOLDEN_PATH
+    )
+    .option(
+      '--output-path <path>',
+      'Path to write extraction artifacts',
+      DEFAULT_OUTPUT_PATH
+    )
+    .option(
+      '--cache-path <path>',
+      'Path to DuckDB cache file',
+      DEFAULT_CACHE_PATH
+    )
+    .option(
+      '--output-version <version>',
+      'Version tag for output (e.g., v1, v2)',
+      'v1'
+    )
+    .option(
+      '--min-cluster-size <n>',
+      'Minimum cluster size to process (default: 3)',
+      (val: string) => parseInt(val, 10)
+    )
+    .option(
+      '--top-n <n>',
+      'Number of representative conversations per cluster (default: 5)',
+      (val: string) => parseInt(val, 10)
+    )
+    .option(
+      '--dedup-threshold <n>',
+      'Similarity threshold for deduplication (default: 0.85)',
+      (val: string) => parseFloat(val)
+    )
+    .option('--push-redis', 'Push candidates to Redis review queue')
+    .option(
+      '-a, --app <slug>',
+      'App ID for Redis queue (required with --push-redis)'
+    )
+    .option('-d, --dry-run', 'Show summary without writing artifacts')
+    .option('--json', 'Output stats as JSON')
+    .option('--no-filters', 'Disable preprocessing filters (for comparison)')
+    .action(faqExtract)
+}

package/src/commands/faq-mine.ts

@@ -0,0 +1,432 @@
+/**
+ * FAQ Mining CLI Command
+ *
+ * Mines resolved support conversations for FAQ candidates.
+ * Uses semantic clustering to identify recurring questions.
+ *
+ * Usage:
+ *   skill faq-mine --app total-typescript --since 30d
+ *   skill faq-mine --app epic-react --since 7d --unchanged-only
+ *   skill faq-mine --app total-typescript --since 90d --json
+ *   skill faq-mine --app epic-web --since 30d --export faq-candidates.json
+ */
+
+import { writeFileSync } from 'fs'
+import {
+  type FaqCandidate,
+  type MineResult,
+  filterAutoSurfaceCandidates,
+  mineConversations,
+  mineFaqCandidates,
+} from '@skillrecordings/core/faq'
+import { createDuckDBSource } from '@skillrecordings/core/faq/duckdb-source'
+import type { DataSource } from '@skillrecordings/core/faq/types'
+import { closeDb } from '@skillrecordings/database'
+import type { Command } from 'commander'
+
+/**
+ * Format timestamp for display
+ */
+function formatDate(date: Date): string {
+  return date.toLocaleString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  })
+}
+
+/**
+ * Truncate string with ellipsis
+ */
+function truncate(str: string, len: number): string {
+  if (!str) return ''
+  if (str.length <= len) return str
+  return str.slice(0, len - 3) + '...'
+}
+
+/**
+ * Color codes for terminal output
+ */
+const COLORS = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+} as const
+
+/**
+ * Display human-readable mining results
+ */
+function displayResults(result: MineResult): void {
+  console.log(`\n${COLORS.bold}📚 FAQ Mining Results${COLORS.reset}`)
+  console.log('='.repeat(60))
+
+  // Stats
+  console.log(`\n${COLORS.cyan}Statistics:${COLORS.reset}`)
+  console.log(`  Total conversations:   ${result.stats.totalConversations}`)
+  console.log(`  Clustered:             ${result.stats.clusteredConversations}`)
+  console.log(`  Clusters formed:       ${result.stats.clusterCount}`)
+  console.log(`  FAQ candidates:        ${result.stats.candidateCount}`)
+  console.log(
+    `  Avg cluster size:      ${result.stats.averageClusterSize.toFixed(1)}`
+  )
+  console.log(
+    `  ${COLORS.green}Avg unchanged rate:  ${(result.stats.averageUnchangedRate * 100).toFixed(1)}%${COLORS.reset}`
+  )
+
+  // Clusters
+  if (result.clusters.length > 0) {
+    console.log(`\n${COLORS.bold}📊 Clusters:${COLORS.reset}`)
+    console.log('-'.repeat(60))
+
+    for (const cluster of result.clusters.slice(0, 10)) {
+      const unchangedPct = (cluster.unchangedRate * 100).toFixed(0)
+      console.log(
+        `\n${COLORS.cyan}Cluster ${cluster.id.slice(0, 8)}${COLORS.reset} (${cluster.conversations.length} convos, ${unchangedPct}% unchanged)`
+      )
+      console.log(
+        `  ${COLORS.dim}Centroid: ${truncate(cluster.centroid, 150)}${COLORS.reset}`
+      )
+      console.log(
+        `  ${COLORS.dim}Period: ${formatDate(cluster.oldest)} - ${formatDate(cluster.mostRecent)}${COLORS.reset}`
+      )
+    }
+
+    if (result.clusters.length > 10) {
+      console.log(
+        `\n  ${COLORS.dim}... and ${result.clusters.length - 10} more clusters${COLORS.reset}`
+      )
+    }
+  }
+
+  // Top candidates
+  if (result.candidates.length > 0) {
+    console.log(`\n${COLORS.bold}🏆 Top FAQ Candidates:${COLORS.reset}`)
+    console.log('-'.repeat(60))
+
+    // Filter to auto-surface candidates
+    const autoSurface = filterAutoSurfaceCandidates(result.candidates)
+
+    const displayCandidates =
+      autoSurface.length > 0
+        ? autoSurface.slice(0, 10)
+        : result.candidates.slice(0, 10)
+
+    const label =
+      autoSurface.length > 0
+        ? `(${autoSurface.length} auto-surface ready)`
+        : '(no auto-surface candidates)'
+
+    console.log(`${COLORS.dim}${label}${COLORS.reset}\n`)
+
+    for (const [i, candidate] of displayCandidates.entries()) {
+      if (!candidate) continue
+
+      const confPct = (candidate.confidence * 100).toFixed(0)
+      const unchangedPct = (candidate.unchangedRate * 100).toFixed(0)
+
+      console.log(
+        `${COLORS.bold}#${i + 1}${COLORS.reset} ${COLORS.dim}Confidence: ${confPct}% | ${candidate.clusterSize} occurrences | ${unchangedPct}% unchanged${COLORS.reset}`
+      )
+      console.log(
+        `  ${COLORS.bold}Q:${COLORS.reset} ${truncate(candidate.question, 200)}`
+      )
+      console.log(
+        `  ${COLORS.green}A:${COLORS.reset} ${truncate(candidate.answer, 300)}`
+      )
+      if (candidate.suggestedCategory) {
+        console.log(
+          `  ${COLORS.cyan}Category: ${candidate.suggestedCategory}${COLORS.reset}`
+        )
+      }
+      if (candidate.tags.length > 0) {
+        console.log(
+          `  ${COLORS.dim}Tags: ${candidate.tags.slice(0, 5).join(', ')}${COLORS.reset}`
+        )
+      }
+      console.log('')
+    }
+  }
+
+  console.log('')
+}
+
+/** Default DuckDB cache path */
+const DEFAULT_CACHE_PATH = `${process.env.HOME}/skill/data/front-cache.db`
+
+/**
+ * Create data source based on --source flag.
+ */
+async function createSource(
+  sourceType: 'cache' | 'front' | undefined,
+  cachePath?: string
+): Promise<DataSource | undefined> {
+  if (sourceType === 'cache') {
+    const dbPath = cachePath ?? DEFAULT_CACHE_PATH
+    console.log(`📦 Using DuckDB cache: ${dbPath}`)
+    return createDuckDBSource({ dbPath })
+  }
+
+  // Default to Front API (undefined means use existing behavior)
+  return undefined
+}
+
+/**
+ * Main command handler
+ */
+async function faqMine(options: {
+  app: string
+  since: string
+  limit?: number
+  unchangedOnly?: boolean
+  clusterThreshold?: number
+  json?: boolean
+  export?: string
+  raw?: boolean
+  source?: 'cache' | 'front'
+  cachePath?: string
+  dryRun?: boolean
+}): Promise<void> {
+  if (!options.app) {
+    console.error('Error: --app is required')
+    process.exit(1)
+  }
+
+  if (!options.since) {
+    console.error('Error: --since is required (e.g., 30d, 7d, 90d)')
+    process.exit(1)
+  }
+
+  let source: DataSource | undefined
+
+  try {
+    // Create data source
+    source = await createSource(options.source ?? 'cache', options.cachePath)
+    // Dry run mode: show stats and sample data
+    if (options.dryRun) {
+      console.log(`\n🧪 DRY RUN MODE - ${options.app}`)
+      console.log(`   Source: ${source?.name ?? 'front'}`)
+      console.log(`   Since: ${options.since}`)
+      console.log(`   Limit: ${options.limit ?? 500}`)
+
+      if (source?.getStats) {
+        const stats = await source.getStats()
+        console.log(`\n📊 Cache Statistics:`)
+        console.log(
+          `   Total conversations: ${stats.totalConversations.toLocaleString()}`
+        )
+        console.log(
+          `   Filtered (matching criteria): ${stats.filteredConversations.toLocaleString()}`
+        )
+        console.log(
+          `   Total messages: ${stats.totalMessages.toLocaleString()}`
+        )
+        console.log(`   Inboxes: ${stats.inboxCount}`)
+        if (stats.dateRange.oldest && stats.dateRange.newest) {
+          console.log(
+            `   Date range: ${stats.dateRange.oldest.toLocaleDateString()} - ${stats.dateRange.newest.toLocaleDateString()}`
+          )
+        }
+      }
+
+      // Fetch a small sample
+      console.log(`\n📝 Sample conversations (limit 5):`)
+      const sample = await mineConversations({
+        appId: options.app,
+        since: options.since,
+        limit: 5,
+        unchangedOnly: options.unchangedOnly ?? false,
+        source,
+      })
+
+      for (const conv of sample) {
+        console.log(`\n   [${conv.conversationId}]`)
+        console.log(`   Q: ${truncate(conv.question, 100)}`)
+        console.log(`   A: ${truncate(conv.answer, 100)}`)
+        console.log(`   Tags: ${conv.tags.slice(0, 5).join(', ')}`)
+      }
+
+      console.log(
+        `\n✅ Dry run complete. ${sample.length} sample conversations loaded.`
+      )
+      return
+    }
+
+    // Raw mode: just export Q&A pairs without clustering
+    if (options.raw) {
+      console.log(`📚 Mining raw Q&A pairs for ${options.app}...`)
+      console.log(`   Source: ${source?.name ?? 'front'}`)
+      console.log(`   Since: ${options.since}`)
+      console.log(`   Unchanged only: ${options.unchangedOnly ?? false}`)
+
+      const conversations = await mineConversations({
+        appId: options.app,
+        since: options.since,
+        limit: options.limit ?? 500,
+        unchangedOnly: options.unchangedOnly ?? false,
+        source,
+      })
+
+      const rawData = {
+        generatedAt: new Date().toISOString(),
+        options: {
+          appId: options.app,
+          since: options.since,
+          unchangedOnly: options.unchangedOnly ?? false,
+        },
+        stats: {
+          total: conversations.length,
+        },
+        conversations: conversations.map((c) => ({
+          conversationId: c.conversationId,
+          question: c.question,
+          answer: c.answer,
+          subject: c.subject,
+          tags: c.tags,
+          wasUnchanged: c.wasUnchanged,
+          resolvedAt: c.resolvedAt.toISOString(),
+        })),
+      }
+
+      if (options.export) {
+        writeFileSync(options.export, JSON.stringify(rawData, null, 2), 'utf-8')
+        console.log(
+          `\n✅ Exported ${conversations.length} raw Q&A pairs to ${options.export}`
+        )
+      } else {
+        console.log(JSON.stringify(rawData, null, 2))
+      }
+
+      return
+    }
+
+    const result = await mineFaqCandidates({
+      appId: options.app,
+      since: options.since,
+      limit: options.limit ?? 500,
+      unchangedOnly: options.unchangedOnly ?? false,
+      clusterThreshold: options.clusterThreshold,
+      source,
+    })
+
+    // JSON output
+    if (options.json) {
+      // Convert dates to ISO strings for JSON
+      const jsonResult = {
+        ...result,
+        conversations: result.conversations.map((c) => ({
+          ...c,
+          resolvedAt: c.resolvedAt.toISOString(),
+          _raw: undefined, // Don't include raw data in JSON
+        })),
+        clusters: result.clusters.map((c) => ({
+          ...c,
+          mostRecent: c.mostRecent.toISOString(),
+          oldest: c.oldest.toISOString(),
+          conversations: c.conversations.map((conv) => ({
+            conversationId: conv.conversationId,
+            question: conv.question.slice(0, 200),
+            wasUnchanged: conv.wasUnchanged,
+          })),
+        })),
+        candidates: result.candidates.map((c) => ({
+          ...c,
+          generatedAt: c.generatedAt.toISOString(),
+        })),
+      }
+      console.log(JSON.stringify(jsonResult, null, 2))
+      return
+    }
+
+    // Export to file
+    if (options.export) {
+      const exportData = {
+        generatedAt: new Date().toISOString(),
+        options: {
+          appId: options.app,
+          since: options.since,
+          unchangedOnly: options.unchangedOnly,
+        },
+        stats: result.stats,
+        candidates: result.candidates.map((c) => ({
+          id: c.id,
+          question: c.question,
+          answer: c.answer,
+          clusterSize: c.clusterSize,
+          unchangedRate: c.unchangedRate,
+          confidence: c.confidence,
+          suggestedCategory: c.suggestedCategory,
+          tags: c.tags,
+          generatedAt: c.generatedAt.toISOString(),
+        })),
+      }
+      writeFileSync(
+        options.export,
+        JSON.stringify(exportData, null, 2),
+        'utf-8'
+      )
+      console.log(
+        `\n✅ Exported ${result.candidates.length} FAQ candidates to ${options.export}`
+      )
+      return
+    }
+
+    // Human-readable output
+    displayResults(result)
+  } catch (error) {
+    console.error(
+      'Error:',
+      error instanceof Error ? error.message : String(error)
+    )
+    process.exit(1)
+  } finally {
+    // Close data source if needed
+    if (source?.close) {
+      await source.close()
+    }
+    await closeDb()
+  }
+}
+
+/**
+ * Register FAQ mining commands with Commander
+ */
+export function registerFaqMineCommands(program: Command): void {
+  program
+    .command('faq-mine')
+    .description('Mine FAQ candidates from resolved support conversations')
+    .requiredOption('-a, --app <slug>', 'App slug to mine from (required)')
+    .requiredOption(
+      '-s, --since <duration>',
+      'Time window to mine (e.g., 30d, 7d, 90d)'
+    )
+    .option(
+      '-l, --limit <n>',
+      'Maximum conversations to process (default: 500)',
+      parseInt
+    )
+    .option(
+      '-u, --unchanged-only',
+      'Only include conversations where draft was sent unchanged'
+    )
+    .option(
+      '--cluster-threshold <n>',
+      'Similarity threshold for clustering (default: 0.75)',
+      parseFloat
+    )
+    .option('--json', 'Output as JSON')
+    .option('-e, --export <file>', 'Export candidates to file')
+    .option('-r, --raw', 'Export raw Q&A pairs without clustering (faster)')
+    .option(
+      '--source <type>',
+      'Data source: cache (DuckDB, default) or front (live API)',
+      'cache'
+    )
+    .option('--cache-path <path>', 'Path to DuckDB cache file')
+    .option('-d, --dry-run', 'Show stats and sample data without full mining')
+    .action(faqMine)
+}