@tracehound/cli 1.2.0

package/src/commands/inspect.ts

@@ -0,0 +1,142 @@
+/**
+ * Inspect command - Inspect quarantine contents
+ */
+
+import Table from 'cli-table3'
+import { Command } from 'commander'
+
+export const inspectCommand = new Command('inspect')
+  .description('Inspect quarantine contents')
+  .option('-s, --signature <sig>', 'Inspect specific signature')
+  .option('-l, --limit <n>', 'Limit results', '10')
+  .option('-j, --json', 'Output as JSON')
+  .action((options) => {
+    if (options.signature) {
+      inspectSingle(options.signature, options.json)
+    } else {
+      inspectList(parseInt(options.limit), options.json)
+    }
+  })
+
+interface QuarantineEntry {
+  signature: string
+  severity: 'critical' | 'high' | 'medium' | 'low'
+  category: string
+  size: number
+  captured: number
+  source: string
+}
+
+function getQuarantineEntries(limit: number): QuarantineEntry[] {
+  // TODO: Connect to real core when available
+  void limit
+  return []
+}
+
+function getEntry(signature: string): QuarantineEntry | null {
+  // TODO: Connect to real core when available
+  void signature
+  return null
+}
+
+function inspectSingle(signature: string, json: boolean): void {
+  const entry = getEntry(signature)
+
+  if (!entry) {
+    console.log(`\n  ❌ Evidence not found: ${signature}\n`)
+    return
+  }
+
+  if (json) {
+    console.log(JSON.stringify(entry, null, 2))
+  } else {
+    printEntry(entry)
+  }
+}
+
+function inspectList(limit: number, json: boolean): void {
+  const entries = getQuarantineEntries(limit)
+
+  if (json) {
+    console.log(JSON.stringify(entries, null, 2))
+    return
+  }
+
+  if (entries.length === 0) {
+    console.log('\n  📭 Quarantine is empty\n')
+    return
+  }
+
+  // Header
+  console.log('\n  ╔══════════════════════════════════════════════════════════════╗')
+  console.log('  ║                    QUARANTINE CONTENTS                       ║')
+  console.log('  ╚══════════════════════════════════════════════════════════════╝\n')
+
+  const table = new Table({
+    head: ['Signature', 'Severity', 'Category', 'Size', 'Source'],
+    style: { head: ['cyan'], border: ['gray'] },
+    colWidths: [16, 12, 12, 12, 18],
+  })
+
+  for (const entry of entries) {
+    const severityIcon = getSeverityIcon(entry.severity)
+    table.push([
+      entry.signature.slice(0, 12) + '...',
+      `${severityIcon} ${entry.severity}`,
+      entry.category,
+      formatBytes(entry.size),
+      entry.source.slice(0, 15),
+    ])
+  }
+
+  console.log(table.toString())
+  console.log()
+}
+
+function printEntry(entry: QuarantineEntry): void {
+  const severityIcon = getSeverityIcon(entry.severity)
+
+  // Header
+  console.log('\n  ╔══════════════════════════════════════════════════════════════╗')
+  console.log('  ║                     EVIDENCE DETAILS                         ║')
+  console.log('  ╚══════════════════════════════════════════════════════════════╝\n')
+
+  const table = new Table({
+    style: { border: ['gray'] },
+  })
+
+  table.push(
+    { Signature: entry.signature },
+    { Severity: `${severityIcon} ${entry.severity}` },
+    { Category: entry.category },
+    { Size: formatBytes(entry.size) },
+    { Source: entry.source },
+    { Captured: new Date(entry.captured).toISOString() }
+  )
+
+  console.log(table.toString())
+  console.log()
+}
+
+function getSeverityIcon(severity: string): string {
+  switch (severity) {
+    case 'critical':
+      return '🔴'
+    case 'high':
+      return '🟠'
+    case 'medium':
+      return '🟡'
+    case 'low':
+      return '🟢'
+    default:
+      return '⚪'
+  }
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B'
+  const k = 1024
+  const sizes = ['B', 'KB', 'MB', 'GB']
+  const i = Math.floor(Math.log(bytes) / Math.log(k))
+  return `${(bytes / Math.pow(k, i)).toFixed(1)} ${sizes[i]}`
+}

package/src/commands/stats.ts

@@ -0,0 +1,124 @@
+/**
+ * Stats command - Show threat statistics
+ */
+
+import Table from 'cli-table3'
+import { Command } from 'commander'
+
+export const statsCommand = new Command('stats')
+  .description('Show threat statistics')
+  .option('-j, --json', 'Output as JSON')
+  .option('--since <duration>', 'Time window (e.g., 1h, 24h, 7d)', '24h')
+  .action((options) => {
+    const stats = getStats(options.since)
+
+    if (options.json) {
+      console.log(JSON.stringify(stats, null, 2))
+    } else {
+      printStats(stats)
+    }
+  })
+
+interface ThreatStats {
+  window: string
+  total: number
+  bySeverity: {
+    critical: number
+    high: number
+    medium: number
+    low: number
+  }
+  byCategory: {
+    injection: number
+    ddos: number
+    other: number
+  }
+  outcomes: {
+    quarantined: number
+    rateLimited: number
+    clean: number
+    ignored: number
+  }
+}
+
+function getStats(_since: string): ThreatStats {
+  // TODO: Connect to real core when available
+  return {
+    window: _since,
+    total: 0,
+    bySeverity: {
+      critical: 0,
+      high: 0,
+      medium: 0,
+      low: 0,
+    },
+    byCategory: {
+      injection: 0,
+      ddos: 0,
+      other: 0,
+    },
+    outcomes: {
+      quarantined: 0,
+      rateLimited: 0,
+      clean: 0,
+      ignored: 0,
+    },
+  }
+}
+
+function printStats(stats: ThreatStats): void {
+  // Header
+  console.log('\n  ╔══════════════════════════════════════════════════════════════╗')
+  console.log(`  ║              THREAT STATISTICS (${stats.window.padEnd(24)})  ║`)
+  console.log('  ╚══════════════════════════════════════════════════════════════╝\n')
+
+  // Summary
+  const summaryTable = new Table({
+    head: ['Metric', 'Value'],
+    style: { head: ['cyan'], border: ['gray'] },
+  })
+  summaryTable.push(['Total Threats', String(stats.total)], ['Time Window', stats.window])
+  console.log(summaryTable.toString())
+  console.log()
+
+  // By Severity
+  const severityTable = new Table({
+    head: ['Severity', 'Count'],
+    style: { head: ['red'], border: ['gray'] },
+  })
+  severityTable.push(
+    ['🔴 Critical', String(stats.bySeverity.critical)],
+    ['🟠 High', String(stats.bySeverity.high)],
+    ['🟡 Medium', String(stats.bySeverity.medium)],
+    ['🟢 Low', String(stats.bySeverity.low)]
+  )
+  console.log(severityTable.toString())
+  console.log()
+
+  // By Category
+  const categoryTable = new Table({
+    head: ['Category', 'Count'],
+    style: { head: ['yellow'], border: ['gray'] },
+  })
+  categoryTable.push(
+    ['💉 Injection', String(stats.byCategory.injection)],
+    ['🌊 DDoS', String(stats.byCategory.ddos)],
+    ['❓ Other', String(stats.byCategory.other)]
+  )
+  console.log(categoryTable.toString())
+  console.log()
+
+  // Outcomes
+  const outcomesTable = new Table({
+    head: ['Outcome', 'Count'],
+    style: { head: ['green'], border: ['gray'] },
+  })
+  outcomesTable.push(
+    ['🔒 Quarantined', String(stats.outcomes.quarantined)],
+    ['⏱️  Rate Limited', String(stats.outcomes.rateLimited)],
+    ['✅ Clean', String(stats.outcomes.clean)],
+    ['⏭️  Ignored', String(stats.outcomes.ignored)]
+  )
+  console.log(outcomesTable.toString())
+  console.log()
+}

package/src/commands/status.ts

@@ -0,0 +1,144 @@
+/**
+ * Status command - Show current system status
+ */
+
+import Table from 'cli-table3'
+import { Command } from 'commander'
+import { createRequire } from 'module'
+const require = createRequire(import.meta.url)
+const { version } = require('../../package.json')
+
+export const statusCommand = new Command('status')
+  .description('Show current Tracehound system status')
+  .option('-j, --json', 'Output as JSON')
+  .action((options) => {
+    const status = getSystemStatus()
+
+    if (options.json) {
+      console.log(JSON.stringify(status, null, 2))
+    } else {
+      printStatus(status)
+    }
+  })
+
+interface SystemStatus {
+  version: string
+  uptime: number
+  health: 'healthy' | 'degraded' | 'critical'
+  quarantine: {
+    count: number
+    bytes: number
+    capacity: number
+  }
+  rateLimit: {
+    blocked: number
+    active: number
+  }
+  houndPool: {
+    active: number
+    dormant: number
+    total: number
+  }
+}
+
+function getSystemStatus(): SystemStatus {
+  // TODO: Connect to real core when available
+  return {
+    version: version,
+    uptime: Math.floor(process.uptime()),
+    health: 'healthy',
+    quarantine: {
+      count: 0,
+      bytes: 0,
+      capacity: 1000,
+    },
+    rateLimit: {
+      blocked: 0,
+      active: 0,
+    },
+    houndPool: {
+      active: 0,
+      dormant: 0,
+      total: 0,
+    },
+  }
+}
+
+function printStatus(status: SystemStatus): void {
+  const healthIcon = status.health === 'healthy' ? '✅' : status.health === 'degraded' ? '⚠️' : '🔴'
+
+  // Header
+  console.log('\n  ╔══════════════════════════════════════════════════════════════╗')
+  console.log('  ║                    TRACEHOUND STATUS                         ║')
+  console.log('  ╚══════════════════════════════════════════════════════════════╝\n')
+
+  // System Info Table
+  const systemTable = new Table({
+    head: ['Property', 'Value'],
+    style: { head: ['cyan'], border: ['gray'] },
+  })
+  systemTable.push(
+    ['Version', status.version],
+    ['Uptime', formatUptime(status.uptime)],
+    ['Health', `${healthIcon} ${status.health}`],
+  )
+  console.log(systemTable.toString())
+  console.log()
+
+  // Quarantine Table
+  const quarantineTable = new Table({
+    head: ['QUARANTINE', 'Value'],
+    style: { head: ['yellow'], border: ['gray'] },
+  })
+  const usage =
+    status.quarantine.capacity > 0
+      ? ((status.quarantine.count / status.quarantine.capacity) * 100).toFixed(1)
+      : '0.0'
+  quarantineTable.push(
+    ['Count', `${status.quarantine.count} / ${status.quarantine.capacity}`],
+    ['Usage', `${usage}%`],
+    ['Bytes', formatBytes(status.quarantine.bytes)],
+  )
+  console.log(quarantineTable.toString())
+  console.log()
+
+  // Rate Limit Table
+  const rateLimitTable = new Table({
+    head: ['RATE LIMIT', 'Value'],
+    style: { head: ['magenta'], border: ['gray'] },
+  })
+  rateLimitTable.push(
+    ['Blocked', String(status.rateLimit.blocked)],
+    ['Active', String(status.rateLimit.active)],
+  )
+  console.log(rateLimitTable.toString())
+  console.log()
+
+  // Hound Pool Table
+  const poolTable = new Table({
+    head: ['HOUND POOL', 'Value'],
+    style: { head: ['green'], border: ['gray'] },
+  })
+  poolTable.push(
+    ['Active', String(status.houndPool.active)],
+    ['Dormant', String(status.houndPool.dormant)],
+    ['Total', String(status.houndPool.total)],
+  )
+  console.log(poolTable.toString())
+  console.log()
+}
+
+function formatUptime(seconds: number): string {
+  const h = Math.floor(seconds / 3600)
+  const m = Math.floor((seconds % 3600) / 60)
+  const s = seconds % 60
+  return `${h}h ${m}m ${s}s`
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B'
+  const k = 1024
+  const sizes = ['B', 'KB', 'MB', 'GB']
+  const i = Math.floor(Math.log(bytes) / Math.log(k))
+  return `${(bytes / Math.pow(k, i)).toFixed(1)} ${sizes[i]}`
+}

package/src/commands/watch.ts

@@ -0,0 +1,273 @@
+/**
+ * Watch command - Live dashboard (Pure ANSI, no React)
+ */
+
+import Table from 'cli-table3'
+import { Command } from 'commander'
+import { createRequire } from 'module'
+import {
+  bold,
+  clearScreen,
+  hideCursor,
+  muted,
+  primary,
+  progressBar,
+  secondary,
+  severity,
+  showCursor,
+  theme,
+} from '../lib/theme.js'
+
+const require = createRequire(import.meta.url)
+const { version } = require('../../package.json')
+
+export const watchCommand = new Command('watch')
+  .description('Launch live dashboard')
+  .option('-r, --refresh <ms>', 'Refresh interval in ms', '1000')
+  .action((options) => {
+    const refreshMs = parseInt(options.refresh)
+    startDashboard(refreshMs)
+  })
+
+interface Snapshot {
+  timestamp: string
+  system: {
+    version: string
+    uptime: string
+    health: 'healthy' | 'degraded' | 'critical'
+    memory: { used: number; total: number }
+  }
+  quarantine: {
+    count: number
+    capacity: number
+    bytes: number
+    bySeverity: { critical: number; high: number; medium: number; low: number }
+  }
+  houndPool: {
+    active: number
+    dormant: number
+    total: number
+    status: 'ok' | 'exhausted'
+  }
+  recentThreats: Array<{
+    signature: string
+    severity: string
+    category: string
+    size: string
+    time: string
+  }>
+}
+
+export function getSnapshot(): Snapshot {
+  // TODO: Connect to real core
+  return {
+    timestamp: new Date().toISOString(),
+    system: {
+      version: version,
+      uptime: formatUptime(Math.floor(process.uptime())),
+      health: 'healthy',
+      memory: { used: 45, total: 256 },
+    },
+    quarantine: {
+      count: 0,
+      capacity: 1000,
+      bytes: 0,
+      bySeverity: { critical: 0, high: 0, medium: 0, low: 0 },
+    },
+    houndPool: {
+      active: 0,
+      dormant: 0,
+      total: 0,
+      status: 'ok',
+    },
+    recentThreats: [],
+  }
+}
+
+function startDashboard(refreshMs: number): void {
+  hideCursor()
+
+  // Handle Ctrl+C gracefully
+  process.on('SIGINT', () => {
+    showCursor()
+    clearScreen()
+    console.log(muted('\n  Dashboard closed.\n'))
+    process.exit(0)
+  })
+
+  const render = () => {
+    clearScreen()
+    const snapshot = getSnapshot()
+    renderDashboard(snapshot, refreshMs)
+  }
+
+  render()
+  setInterval(render, refreshMs)
+}
+
+export function renderDashboard(s: Snapshot, refreshMs: number): void {
+  const width = 76
+
+  // Header
+  console.log()
+  console.log(primary(`  ╔${'═'.repeat(width)}╗`))
+  console.log(
+    primary(`  ║${' '.repeat(20)}`) +
+      bold('🐕 TRACEHOUND LIVE DASHBOARD') +
+      primary(`${' '.repeat(28)}║`),
+  )
+  console.log(primary(`  ║${' '.repeat(24)}`) + muted(s.timestamp) + primary(`${' '.repeat(28)}║`))
+  console.log(primary(`  ╚${'═'.repeat(width)}╝`))
+  console.log()
+
+  // System Status
+  const systemTable = new Table({
+    chars: getTableChars(),
+    style: { head: [], border: [] },
+    head: [secondary('Version'), secondary('Uptime'), secondary('Health'), secondary('Memory')],
+  })
+
+  const healthIcon =
+    s.system.health === 'healthy' ? '✅' : s.system.health === 'degraded' ? '⚠️' : '🔴'
+  const memBar = progressBar(s.system.memory.used, s.system.memory.total, 10)
+
+  systemTable.push([
+    s.system.version,
+    s.system.uptime,
+    `${healthIcon} ${s.system.health}`,
+    `${memBar} ${s.system.memory.used}/${s.system.memory.total} MB`,
+  ])
+
+  console.log(muted('  SYSTEM'))
+  console.log(indent(systemTable.toString()))
+  console.log()
+
+  // Quarantine & Hound Pool side by side
+  const quarantineTable = new Table({
+    chars: getTableChars(),
+    style: { head: [], border: [] },
+    head: [secondary('QUARANTINE'), secondary('Value')],
+  })
+
+  const qUsage = s.quarantine.capacity > 0 ? (s.quarantine.count / s.quarantine.capacity) * 100 : 0
+  const qBar = progressBar(s.quarantine.count, s.quarantine.capacity, 8)
+
+  quarantineTable.push(
+    ['Count', `${s.quarantine.count} / ${s.quarantine.capacity}`],
+    ['Usage', `${qBar} ${qUsage.toFixed(1)}%`],
+    ['Bytes', formatBytes(s.quarantine.bytes)],
+    [
+      'Split',
+      `${severity('critical').slice(0, 15)} ${s.quarantine.bySeverity.critical}  ${severity(
+        'high',
+      ).slice(0, 12)} ${s.quarantine.bySeverity.high}  ${severity('medium').slice(0, 12)} ${
+        s.quarantine.bySeverity.medium
+      }  ${severity('low').slice(0, 10)} ${s.quarantine.bySeverity.low}`,
+    ],
+  )
+
+  const poolTable = new Table({
+    chars: getTableChars(),
+    style: { head: [], border: [] },
+    head: [secondary('HOUND POOL'), secondary('Value')],
+  })
+
+  const poolBar = progressBar(s.houndPool.active, s.houndPool.total || 1, 8)
+  const poolStatus = s.houndPool.status === 'ok' ? '✅ OK' : '🔴 EXHAUSTED'
+
+  poolTable.push(
+    ['Active', `${poolBar} ${s.houndPool.active}/${s.houndPool.total}`],
+    ['Dormant', String(s.houndPool.dormant)],
+    ['Status', poolStatus],
+  )
+
+  console.log(indent(quarantineTable.toString()))
+  console.log()
+  console.log(indent(poolTable.toString()))
+  console.log()
+
+  // Recent Threats
+  if (s.recentThreats.length > 0) {
+    const threatTable = new Table({
+      chars: getTableChars(),
+      style: { head: [], border: [] },
+      head: [
+        secondary('Signature'),
+        secondary('Severity'),
+        secondary('Category'),
+        secondary('Size'),
+        secondary('Time'),
+      ],
+    })
+
+    for (const t of s.recentThreats.slice(0, 5)) {
+      threatTable.push([
+        t.signature.slice(0, 12) + '...',
+        severity(t.severity),
+        t.category,
+        t.size,
+        t.time,
+      ])
+    }
+
+    console.log(muted('  RECENT THREATS'))
+    console.log(indent(threatTable.toString()))
+    console.log()
+  } else {
+    console.log(muted('  RECENT THREATS'))
+    console.log(muted('  📭 No recent threats'))
+    console.log()
+  }
+
+  // Footer
+  console.log(muted(`  ${'─'.repeat(width)}`))
+  console.log(
+    muted(
+      `  Press Ctrl+C to exit │ Refresh: ${refreshMs}ms │ ${theme.reset}${secondary(
+        new Date().toLocaleTimeString(),
+      )}`,
+    ),
+  )
+}
+
+function getTableChars() {
+  return {
+    top: '─',
+    'top-mid': '┬',
+    'top-left': '┌',
+    'top-right': '┐',
+    bottom: '─',
+    'bottom-mid': '┴',
+    'bottom-left': '└',
+    'bottom-right': '┘',
+    left: '│',
+    'left-mid': '├',
+    mid: '─',
+    'mid-mid': '┼',
+    right: '│',
+    'right-mid': '┤',
+    middle: '│',
+  }
+}
+
+function indent(text: string, spaces = 2): string {
+  return text
+    .split('\n')
+    .map((line) => ' '.repeat(spaces) + line)
+    .join('\n')
+}
+
+function formatUptime(seconds: number): string {
+  const h = Math.floor(seconds / 3600)
+  const m = Math.floor((seconds % 3600) / 60)
+  const s = seconds % 60
+  return `${h}h ${m}m ${s}s`
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B'
+  const k = 1024
+  const sizes = ['B', 'KB', 'MB', 'GB']
+  const i = Math.floor(Math.log(bytes) / Math.log(k))
+  return `${(bytes / Math.pow(k, i)).toFixed(1)} ${sizes[i]}`
+}