@skillrecordings/cli 0.1.0 → 0.2.1

package/src/commands/faq-extract.ts

@@ -1,249 +0,0 @@
-/**
- * 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

@@ -1,432 +0,0 @@
-/**
- * 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)
-}