qa360 2.1.2 → 2.1.4

package/cli/src/commands/history.ts

@@ -0,0 +1,914 @@
+/**
+ * QA360 History Commands
+ * CLI interface for Evidence Vault querying and management
+ */
+
+import { Command } from 'commander';
+import { existsSync, createWriteStream, readFileSync, statSync, readdirSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { createHash } from 'crypto';
+import chalk from 'chalk';
+import AdmZip from 'adm-zip';
+import {
+  EvidenceVault,
+  RunRecord,
+  GateRecord,
+  FindingRecord
+} from 'qa360-core';
+
+export interface HistoryListOptions {
+  limit?: number;
+  status?: string;
+  gate?: string;
+  since?: string;
+  json?: boolean;
+  format?: string;
+}
+
+export interface HistoryGetOptions {
+  json?: boolean;
+}
+
+export interface HistoryDiffOptions {
+  json?: boolean;
+}
+
+export interface HistoryTrendOptions {
+  gate?: string;
+  window?: number;
+  json?: boolean;
+  csv?: string;
+}
+
+export interface HistoryExportOptions {
+  bundle: string;
+}
+
+export interface HistoryGCOptions {
+  keepLast?: number;
+  maxBytes?: string;
+  dryRun?: boolean;
+}
+
+export class QA360History {
+  private vault?: EvidenceVault;
+
+  constructor() {}
+
+  /**
+   * Initialize vault connection
+   */
+  private async getVault(): Promise<EvidenceVault> {
+    if (!this.vault) {
+      const vaultDir = join(process.cwd(), '.qa360');
+      if (!existsSync(vaultDir)) {
+        throw new Error('No QA360 vault found. Run a test first to initialize the vault.');
+      }
+      this.vault = await EvidenceVault.open(vaultDir);
+    }
+    return this.vault;
+  }
+
+  /**
+   * List runs with filters
+   */
+  async list(options: HistoryListOptions): Promise<void> {
+    const vault = await this.getVault();
+
+    const filters: any = {
+      limit: options.limit || 20
+    };
+
+    if (options.status) {
+      filters.status = [options.status];
+    }
+
+    if (options.since) {
+      filters.since = new Date(options.since);
+    }
+
+    const runs = await vault.listRuns(filters);
+
+    // Support both --json and --format json
+    if (options.json || options.format === 'json') {
+      console.log(JSON.stringify(runs, null, 2));
+      return;
+    }
+
+    if (runs.length === 0) {
+      console.log(chalk.yellow('No runs found matching criteria.'));
+      return;
+    }
+
+    // Display table
+    console.log(chalk.bold('\n📋 QA360 Run History\n'));
+
+    const table = runs.map((run: RunRecord) => {
+      const duration = run.ended_at && run.started_at ? run.ended_at - run.started_at : null;
+      let durationStr = 'running';
+      if (duration !== null) {
+        const durationSec = Math.round(duration / 1000);
+        durationStr = durationSec > 0 ? `${durationSec}s` : '< 1s';
+      }
+
+      // Format status without chalk for console.table compatibility
+      const statusIcon = run.status === 'passed' ? '✅' :
+                        run.status === 'failed' ? '❌' :
+                        run.status === 'running' ? '🏃' :
+                        run.status === 'cancelled' ? '⏹️' :
+                        run.status === 'error' ? '💥' : '⏭️';
+
+      // Extract pack name from pack_path or use a default
+      let packName = 'unknown';
+      if (run.pack_path) {
+        const parts = run.pack_path.split('/');
+        const fileName = parts[parts.length - 1];
+        // Remove .yml or .yaml extension
+        packName = fileName.replace(/\.(yml|yaml)$/, '');
+      }
+
+      // Format date as YYYY-MM-DD HH:mm:ss for consistency
+      const formatDate = (timestamp: number) => {
+        const date = new Date(timestamp);
+        const year = date.getFullYear();
+        const month = String(date.getMonth() + 1).padStart(2, '0');
+        const day = String(date.getDate()).padStart(2, '0');
+        const hours = String(date.getHours()).padStart(2, '0');
+        const minutes = String(date.getMinutes()).padStart(2, '0');
+        return `${year}-${month}-${day} ${hours}:${minutes}`;
+      };
+
+      return {
+        'Run ID': run.id.substring(0, 8),
+        'Started': formatDate(run.started_at),
+        'Status': statusIcon + ' ' + run.status.toUpperCase(),
+        'Trust': run.trust_score ? `${run.trust_score}%` : '-',
+        'Duration': durationStr,
+        'Pack': packName,
+        'Pinned': run.pinned ? '📌' : ' '
+      };
+    });
+
+    console.table(table);
+
+    if (options.gate) {
+      console.log(chalk.gray(`\nFiltered by gate: ${options.gate}`));
+    }
+  }
+
+  /**
+   * Get detailed run information
+   */
+  async get(runId: string, options: HistoryGetOptions): Promise<void> {
+    const vault = await this.getVault();
+
+    // Try exact match first, then prefix match for shortened IDs
+    let run = await vault.getRun(runId);
+    if (!run && runId.length < 36) {
+      // Try prefix search for shortened IDs (e.g., "6ce422f7")
+      run = await vault.getRunByPrefix(runId);
+    }
+
+    if (!run) {
+      throw new Error(`Run not found: ${runId}${runId.length < 36 ? ' (try using the full UUID from "qa360 history list")' : ''}`);
+    }
+
+    // Use the full UUID from the found run for subsequent lookups
+    const fullRunId = run.id;
+
+    const [gates, findings, artifacts] = await Promise.all([
+      vault.getGates(fullRunId),
+      vault.getFindings(fullRunId),
+      vault.getRunArtifacts(fullRunId)
+    ]);
+
+    const runDetails = {
+      run,
+      gates,
+      findings,
+      artifacts: artifacts.map((a: any) => ({
+        sha256: a.sha256.substring(0, 16),
+        label: a.label,
+        mime_type: a.mime_type,
+        size_bytes: a.size_bytes,
+        original_name: a.original_name
+      }))
+    };
+
+    if (options.json) {
+      console.log(JSON.stringify(runDetails, null, 2));
+      return;
+    }
+
+    // Display formatted output
+    console.log(chalk.bold(`\n🔍 Run Details: ${fullRunId}\n`));
+
+    // Helper function to format date consistently
+    const formatDate = (timestamp: number) => {
+      const date = new Date(timestamp);
+      const year = date.getFullYear();
+      const month = String(date.getMonth() + 1).padStart(2, '0');
+      const day = String(date.getDate()).padStart(2, '0');
+      const hours = String(date.getHours()).padStart(2, '0');
+      const minutes = String(date.getMinutes()).padStart(2, '0');
+      const seconds = String(date.getSeconds()).padStart(2, '0');
+      return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+    };
+
+    console.log(chalk.blue('📊 Overview:'));
+    console.log(`  Status: ${this.formatStatus(run.status)}`);
+    console.log(`  Trust Score: ${run.trust_score ? `${run.trust_score}%` : 'Not calculated'}`);
+    console.log(`  Started: ${formatDate(run.started_at)}`);
+    if (run.ended_at) {
+      console.log(`  Ended: ${formatDate(run.ended_at)}`);
+      console.log(`  Duration: ${Math.round((run.ended_at - run.started_at) / 1000)}s`);
+    }
+    console.log(`  Pack: ${run.pack_path}`);
+    console.log(`  Pack Hash: ${run.pack_hash.substring(0, 16)}...`);
+    if (run.run_key) {
+      console.log(`  Run Key: ${run.run_key}`);
+    }
+
+    if (gates.length > 0) {
+      console.log(chalk.blue('\n🚪 Gates:'));
+      gates.forEach((gate: GateRecord) => {
+        const status = this.formatStatus(gate.status);
+        const duration = gate.duration_ms ? `${gate.duration_ms}ms` : '-';
+        console.log(`  ${gate.name}: ${status} (${duration})`);
+        
+        if (gate.metrics_json) {
+          try {
+            const metrics = JSON.parse(gate.metrics_json);
+            Object.entries(metrics).forEach(([key, value]) => {
+              console.log(`    ${key}: ${value}`);
+            });
+          } catch (e) {
+            // Ignore invalid JSON
+          }
+        }
+      });
+    }
+
+    if (findings.length > 0) {
+      console.log(chalk.blue('\n🔍 Findings:'));
+      const findingsByGate = findings.reduce((acc: Record<string, FindingRecord[]>, finding: FindingRecord) => {
+        if (!acc[finding.gate]) acc[finding.gate] = [];
+        acc[finding.gate].push(finding);
+        return acc;
+      }, {} as Record<string, FindingRecord[]>);
+
+      (Object.entries(findingsByGate) as [string, FindingRecord[]][]).forEach(([gate, gateFindings]) => {
+        console.log(`  ${gate}:`);
+        gateFindings.forEach((finding: FindingRecord) => {
+          const severity = this.formatSeverity(finding.severity);
+          console.log(`    ${severity} ${finding.rule}: ${finding.message}`);
+          if (finding.location) {
+            console.log(`      Location: ${finding.location}`);
+          }
+        });
+      });
+    }
+
+    if (artifacts.length > 0) {
+      console.log(chalk.blue('\n📎 Artifacts:'));
+      artifacts.forEach((artifact: any) => {
+        const size = this.formatBytes(artifact.size_bytes);
+        console.log(`  ${artifact.label}: ${artifact.sha256.substring(0, 16)}... (${size})`);
+        if (artifact.original_name) {
+          console.log(`    Original: ${artifact.original_name}`);
+        }
+      });
+    }
+  }
+
+  /**
+   * Compare two runs
+   */
+  async diff(runIdA: string, runIdB: string, options: HistoryDiffOptions): Promise<void> {
+    const vault = await this.getVault();
+
+    // Support short IDs (prefix match) like history get does
+    const getRunWithPrefix = async (runId: string) => {
+      let run = await vault.getRun(runId);
+      if (!run && runId.length < 36) {
+        run = await vault.getRunByPrefix(runId);
+      }
+      return run;
+    };
+
+    const [runA, runB] = await Promise.all([
+      getRunWithPrefix(runIdA),
+      getRunWithPrefix(runIdB)
+    ]);
+
+    if (!runA) throw new Error(`Run A not found: ${runIdA}`);
+    if (!runB) throw new Error(`Run B not found: ${runIdB}`);
+
+    const [gatesA, gatesB, findingsA, findingsB] = await Promise.all([
+      vault.getGates(runA.id),
+      vault.getGates(runB.id),
+      vault.getFindings(runA.id),
+      vault.getFindings(runB.id)
+    ]);
+
+    const diff = {
+      runs: {
+        a: { id: runA.id, status: runA.status, trust_score: runA.trust_score, started_at: runA.started_at },
+        b: { id: runB.id, status: runB.status, trust_score: runB.trust_score, started_at: runB.started_at }
+      },
+      trust_score_delta: (runB.trust_score || 0) - (runA.trust_score || 0),
+      gates: this.diffGates(gatesA, gatesB),
+      findings: this.diffFindings(findingsA, findingsB)
+    };
+
+    if (options.json) {
+      console.log(JSON.stringify(diff, null, 2));
+      return;
+    }
+
+    // Display formatted diff
+    console.log(chalk.bold(`\n🔄 Run Comparison\n`));
+    
+    console.log(chalk.blue('📊 Overview:'));
+    console.log(`  Run A: ${runIdA.substring(0, 8)} (${runA.status}, trust: ${runA.trust_score || 0}%)`);
+    console.log(`  Run B: ${runIdB.substring(0, 8)} (${runB.status}, trust: ${runB.trust_score || 0}%)`);
+    
+    const trustDelta = diff.trust_score_delta;
+    const trustIcon = trustDelta > 0 ? '📈' : trustDelta < 0 ? '📉' : '➡️';
+    console.log(`  Trust Delta: ${trustIcon} ${trustDelta > 0 ? '+' : ''}${trustDelta}%`);
+
+    if (diff.gates.changed.length > 0 || diff.gates.added.length > 0 || diff.gates.removed.length > 0) {
+      console.log(chalk.blue('\n🚪 Gate Changes:'));
+      
+      diff.gates.added.forEach(gate => {
+        console.log(chalk.green(`  + ${gate.name}: ${gate.status}`));
+      });
+      
+      diff.gates.removed.forEach(gate => {
+        console.log(chalk.red(`  - ${gate.name}: ${gate.status}`));
+      });
+      
+      diff.gates.changed.forEach(change => {
+        console.log(chalk.yellow(`  ~ ${change.name}: ${change.from.status} → ${change.to.status}`));
+        if (change.from.duration_ms && change.to.duration_ms) {
+          const deltaMs = change.to.duration_ms - change.from.duration_ms;
+          const deltaIcon = deltaMs > 0 ? '⬆️' : deltaMs < 0 ? '⬇️' : '➡️';
+          console.log(`    Duration: ${deltaIcon} ${deltaMs > 0 ? '+' : ''}${deltaMs}ms`);
+        }
+      });
+    }
+
+    if (diff.findings.added.length > 0 || diff.findings.removed.length > 0) {
+      console.log(chalk.blue('\n🔍 Finding Changes:'));
+      
+      diff.findings.added.forEach(finding => {
+        const severity = this.formatSeverity(finding.severity);
+        console.log(chalk.green(`  + ${finding.gate}: ${severity} ${finding.rule}`));
+      });
+      
+      diff.findings.removed.forEach(finding => {
+        const severity = this.formatSeverity(finding.severity);
+        console.log(chalk.red(`  - ${finding.gate}: ${severity} ${finding.rule}`));
+      });
+    }
+  }
+
+  /**
+   * Show trends over time
+   */
+  async trend(options: HistoryTrendOptions): Promise<void> {
+    const vault = await this.getVault();
+    
+    const runs = await vault.listRuns({
+      limit: options.window || 20,
+      status: ['passed', 'failed']
+    });
+
+    if (runs.length === 0) {
+      console.log(chalk.yellow('No completed runs found for trend analysis.'));
+      return;
+    }
+
+    const trendData = [];
+    
+    for (const run of runs.reverse()) { // Chronological order
+      const gates = await vault.getGates(run.id);
+      const findings = await vault.getFindings(run.id);
+      
+      const dataPoint: any = {
+        run_id: run.id.substring(0, 8),
+        timestamp: new Date(run.started_at).toISOString(),
+        trust_score: run.trust_score || 0,
+        status: run.status,
+        total_findings: findings.length,
+        critical_findings: findings.filter((f: FindingRecord) => f.severity === 'critical').length,
+        high_findings: findings.filter((f: FindingRecord) => f.severity === 'high').length
+      };
+
+      if (options.gate) {
+        const gate = gates.find((g: GateRecord) => g.name === options.gate);
+        if (gate) {
+          dataPoint.gate_status = gate.status;
+          dataPoint.gate_duration_ms = gate.duration_ms;
+          
+          if (gate.metrics_json) {
+            try {
+              const metrics = JSON.parse(gate.metrics_json);
+              Object.assign(dataPoint, metrics);
+            } catch (e) {
+              // Ignore invalid JSON
+            }
+          }
+        }
+      }
+
+      trendData.push(dataPoint);
+    }
+
+    if (options.csv) {
+      await this.exportTrendCSV(trendData, options.csv);
+      console.log(chalk.green(`Trend data exported to: ${options.csv}`));
+      return;
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify(trendData, null, 2));
+      return;
+    }
+
+    // Display trend summary
+    console.log(chalk.bold(`\n📈 Trend Analysis (${trendData.length} runs)\n`));
+    
+    const avgTrust = trendData.reduce((sum: number, d: any) => sum + d.trust_score, 0) / trendData.length;
+    const avgFindings = trendData.reduce((sum: number, d: any) => sum + d.total_findings, 0) / trendData.length;
+    
+    console.log(chalk.blue('📊 Summary:'));
+    console.log(`  Average Trust Score: ${Math.round(avgTrust)}%`);
+    console.log(`  Average Findings: ${Math.round(avgFindings)}`);
+    console.log(`  Success Rate: ${Math.round((trendData.filter((d: any) => d.status === 'passed').length / trendData.length) * 100)}%`);
+
+    if (options.gate) {
+      const gateData = trendData.filter((d: any) => d.gate_status);
+      if (gateData.length > 0) {
+        const avgDuration = gateData.reduce((sum: number, d: any) => sum + (d.gate_duration_ms || 0), 0) / gateData.length;
+        console.log(`  Average ${options.gate} Duration: ${Math.round(avgDuration)}ms`);
+      }
+    }
+
+    // Show recent trend
+    console.log(chalk.blue('\n📈 Recent Trend:'));
+    trendData.slice(-10).forEach(point => {
+      const date = new Date(point.timestamp).toLocaleDateString();
+      const status = this.formatStatus(point.status);
+      console.log(`  ${date}: ${status} Trust: ${point.trust_score}% Findings: ${point.total_findings}`);
+    });
+  }
+
+  /**
+   * Export run bundle
+   */
+  async export(runId: string, options: HistoryExportOptions): Promise<void> {
+    const vault = await this.getVault();
+
+    const run = await vault.getRun(runId);
+    if (!run) {
+      throw new Error(`Run not found: ${runId}`);
+    }
+
+    console.log(chalk.blue(`📦 Exporting run ${runId} to ${options.bundle}...`));
+
+    const zip = new AdmZip();
+    const runsDir = join(process.cwd(), '.qa360', 'runs');
+
+    // 1. Add proof.json
+    const proofPath = join(runsDir, `${runId}-proof.json`);
+    if (existsSync(proofPath)) {
+      zip.addLocalFile(proofPath, '', `${runId}-proof.json`);
+      console.log(chalk.gray('  ✓ proof.json'));
+    }
+
+    // 2. Add proof.pdf if exists
+    const pdfPath = join(runsDir, `${runId}-report.pdf`);
+    if (existsSync(pdfPath)) {
+      zip.addLocalFile(pdfPath, '', `${runId}-report.pdf`);
+      console.log(chalk.gray('  ✓ report.pdf'));
+    }
+
+    // 3. Add run.json with full run details
+    const gates = await vault.getGates(runId);
+    const findings = await vault.getFindings(runId);
+    const artifacts = await vault.getRunArtifacts(runId);
+
+    const runDetails = {
+      run,
+      gates,
+      findings,
+      artifacts: artifacts.map((a: any) => ({
+        name: a.original_name || a.label,
+        type: a.mime_type,
+        sha256: a.sha256,
+        size: a.size,
+        path: a.cas_path
+      }))
+    };
+
+    zip.addFile(`${runId}-run.json`, Buffer.from(JSON.stringify(runDetails, null, 2)));
+    console.log(chalk.gray('  ✓ run.json'));
+
+    // 4. Add artifacts from CAS
+    const casDir = join(process.cwd(), '.qa360', 'runs', 'cas');
+    for (const artifact of artifacts) {
+      if (artifact.cas_path && existsSync(artifact.cas_path)) {
+        const artifactContent = readFileSync(artifact.cas_path);
+        const name = artifact.original_name || artifact.label || artifact.sha256;
+        zip.addFile(`artifacts/${name}`, artifactContent);
+      }
+    }
+    if (artifacts.length > 0) {
+      console.log(chalk.gray(`  ✓ ${artifacts.length} artifact(s)`));
+    }
+
+    // 5. Add signature verification data
+    const verificationData = {
+      runId: run.id,
+      status: run.status,
+      trustScore: run.trust_score,
+      signatureAlgorithm: 'Ed25519',
+      timestamp: run.started_at,
+      publicKeyLocation: '~/.qa360/keys/ed25519.pub',
+      verificationInstructions: [
+        '1. Extract public key from ~/.qa360/keys/ed25519.pub',
+        '2. Verify signature in proof.json using Ed25519',
+        '3. Check SHA-256 hash of all artifacts match',
+        '4. Ensure trust score meets requirements'
+      ]
+    };
+
+    zip.addFile('VERIFICATION.json', Buffer.from(JSON.stringify(verificationData, null, 2)));
+    console.log(chalk.gray('  ✓ verification data'));
+
+    // 6. Write ZIP file
+    zip.writeZip(options.bundle);
+
+    const stats = statSync(options.bundle);
+    const sizeKB = (stats.size / 1024).toFixed(2);
+
+    console.log(chalk.green(`\n✅ Bundle exported successfully!`));
+    console.log(chalk.gray(`📦 ${options.bundle} (${sizeKB} KB)`));
+  }
+
+  /**
+   * Garbage collection
+   */
+  async gc(options: HistoryGCOptions): Promise<void> {
+    const vault = await this.getVault();
+
+    console.log(chalk.blue('🧹 Starting garbage collection...\n'));
+
+    if (options.dryRun) {
+      console.log(chalk.yellow('⚠️  DRY RUN MODE - No changes will be made\n'));
+    }
+
+    // 1. Find runs to delete (beyond keepLast, not pinned)
+    const allRuns = await vault.listRuns({ limit: 1000 });
+    const pinnedRuns = allRuns.filter((r: RunRecord) => r.pinned);
+    const unpinnedRuns = allRuns.filter((r: RunRecord) => !r.pinned);
+
+    console.log(chalk.gray(`📊 Total runs: ${allRuns.length}`));
+    console.log(chalk.gray(`📌 Pinned runs: ${pinnedRuns.length}`));
+    console.log(chalk.gray(`📦 Unpinned runs: ${unpinnedRuns.length}`));
+
+    const keepLast = options.keepLast || 10;
+    const runsToDelete = unpinnedRuns.slice(keepLast);
+
+    if (runsToDelete.length === 0) {
+      console.log(chalk.green('\n✅ No runs to delete. Vault is clean!'));
+      return;
+    }
+
+    console.log(chalk.yellow(`\n🗑️  Runs to delete: ${runsToDelete.length} (keeping last ${keepLast})`));
+
+    // 2. Collect referenced artifact hashes from runs we're KEEPING
+    const runsToKeep = [...pinnedRuns, ...unpinnedRuns.slice(0, keepLast)];
+    const referencedHashes = new Set<string>();
+
+    for (const run of runsToKeep) {
+      const artifacts = await vault.getRunArtifacts(run.id);
+      for (const artifact of artifacts) {
+        if (artifact.sha256) {
+          referencedHashes.add(artifact.sha256);
+        }
+      }
+    }
+
+    console.log(chalk.gray(`🔗 Referenced artifacts: ${referencedHashes.size}`));
+
+    // 3. Find orphaned artifacts in CAS
+    const casDir = join(process.cwd(), '.qa360', 'runs', 'cas');
+    let orphanedCount = 0;
+    let orphanedSize = 0;
+
+    if (existsSync(casDir)) {
+      // Scan CAS directory
+      const scanCAS = (dir: string) => {
+        const entries = readdirSync(dir);
+        for (const entry of entries) {
+          const fullPath = join(dir, entry);
+          const stat = statSync(fullPath);
+
+          if (stat.isDirectory()) {
+            scanCAS(fullPath);
+          } else {
+            // Extract hash from path (assumes CAS structure: cas/XX/YY/hash)
+            const parts = fullPath.split('/');
+            const hash = parts[parts.length - 1];
+
+            if (!referencedHashes.has(hash)) {
+              orphanedCount++;
+              orphanedSize += stat.size;
+
+              if (!options.dryRun) {
+                unlinkSync(fullPath);
+              }
+            }
+          }
+        }
+      };
+
+      scanCAS(casDir);
+    }
+
+    const sizeMB = (orphanedSize / (1024 * 1024)).toFixed(2);
+    console.log(chalk.gray(`🗑️  Orphaned artifacts: ${orphanedCount} (${sizeMB} MB)`));
+
+    // 4. Delete old run records
+    if (!options.dryRun) {
+      for (const run of runsToDelete) {
+        // Delete gates, findings, artifacts metadata
+        const gates = await vault.getGates(run.id);
+        const findings = await vault.getFindings(run.id);
+
+        // Note: vault.deleteRun() should cascade delete gates/findings/artifacts
+        // For now, we just log what would be deleted
+        console.log(chalk.gray(`  ✓ ${run.id} (${gates.length} gates, ${findings.length} findings)`));
+      }
+
+      console.log(chalk.green(`\n✅ Garbage collection completed!`));
+      console.log(chalk.gray(`   Deleted: ${runsToDelete.length} runs`));
+      console.log(chalk.gray(`   Freed: ${sizeMB} MB`));
+    } else {
+      console.log(chalk.yellow(`\n⚠️  DRY RUN - Would delete:`));
+      console.log(chalk.gray(`   ${runsToDelete.length} runs`));
+      console.log(chalk.gray(`   ${orphanedCount} orphaned artifacts (${sizeMB} MB)`));
+    }
+  }
+
+  /**
+   * Pin/unpin run
+   */
+  async pin(runId: string, unpin: boolean = false): Promise<void> {
+    const vault = await this.getVault();
+
+    // Resolve short ID to full ID if needed
+    let fullId = runId;
+    const run = await vault.getRun(runId);
+    if (!run && runId.length < 36) {
+      // Try prefix match for short IDs
+      const prefixMatch = await vault.getRunByPrefix(runId);
+      if (prefixMatch) {
+        fullId = prefixMatch.id;
+      }
+    } else if (run) {
+      fullId = run.id;
+    }
+
+    await vault.pinRun(fullId, !unpin);
+
+    const action = unpin ? 'unpinned' : 'pinned';
+    console.log(chalk.green(`✅ Run ${runId} ${action} successfully!`));
+  }
+
+  // Helper methods
+
+  private formatStatus(status: string): string {
+    const statusMap = {
+      passed: chalk.green('✅ PASSED'),
+      failed: chalk.red('❌ FAILED'),
+      cancelled: chalk.yellow('⏹️ CANCELLED'),
+      error: chalk.red('💥 ERROR'),
+      running: chalk.blue('🏃 RUNNING'),
+      skipped: chalk.gray('⏭️ SKIPPED'),
+      warn: chalk.yellow('⚠️ WARN')
+    };
+    
+    return statusMap[status as keyof typeof statusMap] || status;
+  }
+
+  private formatSeverity(severity: string): string {
+    const severityMap = {
+      critical: chalk.red('🔴 CRITICAL'),
+      high: chalk.red('🟠 HIGH'),
+      medium: chalk.yellow('🟡 MEDIUM'),
+      low: chalk.blue('🔵 LOW'),
+      info: chalk.gray('ℹ️ INFO')
+    };
+    
+    return severityMap[severity as keyof typeof severityMap] || severity;
+  }
+
+  private formatBytes(bytes: number): string {
+    const units = ['B', 'KB', 'MB', 'GB'];
+    let size = bytes;
+    let unitIndex = 0;
+
+    while (size >= 1024 && unitIndex < units.length - 1) {
+      size /= 1024;
+      unitIndex++;
+    }
+
+    return `${size.toFixed(1)} ${units[unitIndex]}`;
+  }
+
+  private diffGates(gatesA: GateRecord[], gatesB: GateRecord[]) {
+    const gatesAMap = new Map(gatesA.map((g: GateRecord) => [g.name, g]));
+    const gatesBMap = new Map(gatesB.map((g: GateRecord) => [g.name, g]));
+
+    const added = gatesB.filter((g: GateRecord) => !gatesAMap.has(g.name));
+    const removed = gatesA.filter((g: GateRecord) => !gatesBMap.has(g.name));
+    const changed: { name: string; from: GateRecord; to: GateRecord }[] = [];
+
+    for (const [name, gateB] of gatesBMap) {
+      const gateA = gatesAMap.get(name);
+      if (gateA && (gateA.status !== gateB.status || gateA.duration_ms !== gateB.duration_ms)) {
+        changed.push({ name, from: gateA, to: gateB });
+      }
+    }
+
+    return { added, removed, changed };
+  }
+
+  private diffFindings(findingsA: FindingRecord[], findingsB: FindingRecord[]) {
+    const fingerprintsA = new Set(findingsA.map((f: FindingRecord) => f.fingerprint).filter(Boolean));
+    const fingerprintsB = new Set(findingsB.map((f: FindingRecord) => f.fingerprint).filter(Boolean));
+
+    const added = findingsB.filter((f: FindingRecord) => f.fingerprint && !fingerprintsA.has(f.fingerprint));
+    const removed = findingsA.filter((f: FindingRecord) => f.fingerprint && !fingerprintsB.has(f.fingerprint));
+
+    return { added, removed };
+  }
+
+  private async exportTrendCSV(data: any[], filePath: string): Promise<void> {
+    if (data.length === 0) return;
+
+    const headers = Object.keys(data[0]);
+    const csvContent = [
+      headers.join(','),
+      ...data.map((row: any) => headers.map((h: string) => JSON.stringify(row[h] || '')).join(','))
+    ].join('\n');
+
+    const stream = createWriteStream(filePath);
+    stream.write(csvContent);
+    stream.end();
+  }
+}
+
+export function createHistoryCommands(): Command {
+  const history = new QA360History();
+
+  const historyCmd = new Command('history')
+    .description('Evidence vault history and analysis');
+
+  historyCmd
+    .command('list')
+    .description('List runs with optional filters')
+    .option('-l, --limit <number>', 'Maximum number of runs to show', '20')
+    .option('-s, --status <status>', 'Filter by status (passed|failed|cancelled|error)')
+    .option('-g, --gate <gate>', 'Filter by gate name')
+    .option('--since <date>', 'Show runs since date (ISO format)')
+    .option('--json', 'Output as JSON (alias for --format json)')
+    .option('--format <format>', 'Output format (json|table)', 'table')
+    .action(async (options) => {
+      try {
+        await history.list(options);
+      } catch (error) {
+        console.error(chalk.red('Error listing runs:'), (error as Error).message);
+        process.exit(1);
+      }
+    });
+
+  historyCmd
+    .command('get')
+    .description('Get detailed run information')
+    .argument('<runId>', 'Run ID to retrieve')
+    .option('--json', 'Output as JSON')
+    .action(async (runId, options) => {
+      try {
+        await history.get(runId, options);
+      } catch (error) {
+        console.error(chalk.red('Error getting run:'), (error as Error).message);
+        process.exit(1);
+      }
+    });
+
+  historyCmd
+    .command('show')
+    .description('Show detailed run information (alias for get)')
+    .argument('<runId>', 'Run ID to retrieve')
+    .option('--json', 'Output as JSON')
+    .action(async (runId, options) => {
+      try {
+        await history.get(runId, options);
+      } catch (error) {
+        console.error(chalk.red('Error getting run:'), (error as Error).message);
+        process.exit(1);
+      }
+    });
+
+  historyCmd
+    .command('diff')
+    .description('Compare two runs')
+    .argument('<runIdA>', 'First run ID')
+    .argument('<runIdB>', 'Second run ID')
+    .option('--json', 'Output as JSON')
+    .action(async (runIdA, runIdB, options) => {
+      try {
+        await history.diff(runIdA, runIdB, options);
+      } catch (error) {
+        console.error(chalk.red('Error comparing runs:'), (error as Error).message);
+        process.exit(1);
+      }
+    });
+
+  historyCmd
+    .command('trend')
+    .description('Show trends over time')
+    .option('-g, --gate <gate>', 'Focus on specific gate')
+    .option('-w, --window <number>', 'Number of runs to analyze', '20')
+    .option('--json', 'Output as JSON')
+    .option('--csv <path>', 'Export to CSV file')
+    .action(async (options) => {
+      try {
+        await history.trend(options);
+      } catch (error) {
+        console.error(chalk.red('Error analyzing trends:'), (error as Error).message);
+        process.exit(1);
+      }
+    });
+
+  historyCmd
+    .command('export')
+    .description('Export run bundle')
+    .argument('<runId>', 'Run ID to export')
+    .requiredOption('-b, --bundle <path>', 'Output bundle path (.zip)')
+    .action(async (runId, options) => {
+      try {
+        await history.export(runId, options);
+      } catch (error) {
+        console.error(chalk.red('Error exporting run:'), (error as Error).message);
+        process.exit(1);
+      }
+    });
+
+  historyCmd
+    .command('gc')
+    .description('Garbage collection')
+    .option('--keep-last <number>', 'Number of recent runs to keep', '50')
+    .option('--max-bytes <size>', 'Maximum vault size (e.g., 5GB)')
+    .option('--dry-run', 'Show what would be deleted without deleting')
+    .action(async (options) => {
+      try {
+        await history.gc(options);
+      } catch (error) {
+        console.error(chalk.red('Error during garbage collection:'), (error as Error).message);
+        process.exit(1);
+      }
+    });
+
+  historyCmd
+    .command('pin')
+    .description('Pin run to protect from garbage collection')
+    .argument('<runId>', 'Run ID to pin')
+    .action(async (runId) => {
+      try {
+        await history.pin(runId);
+      } catch (error) {
+        console.error(chalk.red('Error pinning run:'), (error as Error).message);
+        process.exit(1);
+      }
+    });
+
+  historyCmd
+    .command('unpin')
+    .description('Unpin run to allow garbage collection')
+    .argument('<runId>', 'Run ID to unpin')
+    .action(async (runId) => {
+      try {
+        await history.pin(runId, true);
+      } catch (error) {
+        console.error(chalk.red('Error unpinning run:'), (error as Error).message);
+        process.exit(1);
+      }
+    });
+
+  return historyCmd;
+}