@vibecheckai/cli 3.6.1 → 3.8.0

package/bin/runners/runSafelist.js

@@ -0,0 +1,1190 @@
+/**
+ * vibecheck safelist - Responsible Finding Suppression
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * A SCALPEL, NOT A TRASH CAN
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Let teams suppress known findings responsibly with:
+ * - Required justification with category
+ * - Owner accountability
+ * - Optional expiration (enforced for some categories)
+ * - Audit trail
+ * - Repo-wide vs local-only scopes
+ * - Suppressed findings reported separately
+ * 
+ * Usage:
+ *   vibecheck safelist                    # List all entries
+ *   vibecheck safelist add                # Add entry (interactive)
+ *   vibecheck safelist add --id <id> ...  # Add entry (CLI)
+ *   vibecheck safelist remove --id <id>   # Remove entry
+ *   vibecheck safelist check --id <id>    # Check if suppressed
+ *   vibecheck safelist report             # Suppression report
+ *   vibecheck safelist migrate            # Migrate legacy allowlist
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const safelist = require("./lib/safelist");
+const { EXIT } = require("./lib/exit-codes");
+const { parseGlobalFlags, shouldSuppressOutput, isJsonMode } = require("./lib/global-flags");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// UNIFIED CLI OUTPUT
+// ═══════════════════════════════════════════════════════════════════════════════
+
+let _cliOutput = null;
+function getCliOutput() {
+  if (!_cliOutput) _cliOutput = require("./lib/unified-cli-output");
+  return _cliOutput;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TERMINAL STYLING
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const SUPPORTS_COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+
+// Use unified CLI output when available, fallback to local
+let c, icons;
+try {
+  const cli = getCliOutput();
+  c = cli.ansi;
+  icons = cli.sym;
+} catch {
+  c = SUPPORTS_COLOR ? {
+    reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m", italic: "\x1b[3m",
+    red: "\x1b[31m", green: "\x1b[32m", yellow: "\x1b[33m", blue: "\x1b[34m",
+    magenta: "\x1b[35m", cyan: "\x1b[36m",
+    bgRed: "\x1b[41m", bgGreen: "\x1b[42m", bgYellow: "\x1b[43m",
+  } : {
+    reset: "", bold: "", dim: "", italic: "",
+    red: "", green: "", yellow: "", blue: "", magenta: "", cyan: "",
+    bgRed: "", bgGreen: "", bgYellow: "",
+  };
+  icons = {
+    check: "✓", cross: "✗", warning: "⚠", info: "ℹ",
+    add: "+", remove: "-", list: "📋", shield: "🛡️",
+    clock: "⏱️", person: "👤", lock: "🔒", unlock: "🔓",
+    expired: "⌛", review: "👁️",
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELP
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function printHelp(projectRoot = process.cwd()) {
+  const categories = Object.entries(safelist.JUSTIFICATION_CATEGORIES)
+    .map(([key, val]) => `    ${c.cyan}${key.padEnd(16)}${c.reset} ${val.description}`)
+    .join("\n");
+
+  // Print unified header
+  try {
+    const cli = getCliOutput();
+    cli.renderMinimalHeader("safelist", "free");
+  } catch {
+    console.log(`\n${c.bold}${icons.shield || "🛡️"} vibecheck safelist${c.reset}\n`);
+  }
+  
+  console.log(`${c.bold}SAFELIST${c.reset} - Responsible Finding Suppression
+
+${c.dim}A scalpel, not a trash can. Suppress findings responsibly with
+required justification, owner accountability, and optional expiration.${c.reset}
+
+${c.bold}USAGE${c.reset}
+  vibecheck safelist <action> [options]
+
+${c.bold}ACTIONS${c.reset}
+  ${c.cyan}list${c.reset}              List all safelist entries ${c.dim}(default)${c.reset}
+  ${c.cyan}add${c.reset}               Add a new entry (requires justification)
+  ${c.cyan}remove${c.reset}            Remove an entry
+  ${c.cyan}check${c.reset}             Check if a finding is suppressed
+  ${c.cyan}search${c.reset}            Search entries by pattern, owner, file, etc.
+  ${c.cyan}report${c.reset}            Show suppression health report
+  ${c.cyan}stats${c.reset}             Show detailed statistics
+  ${c.cyan}migrate${c.reset}           Migrate legacy allowlist.json
+  ${c.cyan}validate${c.reset}          Validate safelist files
+  ${c.cyan}clean${c.reset}             Remove expired entries
+
+${c.bold}ADD OPTIONS${c.reset}
+  ${c.cyan}--id <finding-id>${c.reset}      Specific finding ID to suppress
+  ${c.cyan}--pattern <regex>${c.reset}      Pattern to match (message, file, etc.)
+  ${c.cyan}--rule <rule-id>${c.reset}       Rule ID to suppress everywhere
+  ${c.cyan}--file <path>${c.reset}          File path (supports globs)
+  ${c.cyan}--lines <start-end>${c.reset}    Line range (e.g., "10-20")
+
+  ${c.cyan}--reason <text>${c.reset}        ${c.yellow}REQUIRED${c.reset} - Why this is suppressed
+  ${c.cyan}--category <cat>${c.reset}       ${c.yellow}REQUIRED${c.reset} - Justification category (see below)
+  ${c.cyan}--ticket <url>${c.reset}         Link to issue/ticket (required for some categories)
+
+  ${c.cyan}--owner <name>${c.reset}         ${c.yellow}REQUIRED${c.reset} - Person/team responsible
+  ${c.cyan}--email <email>${c.reset}        Owner contact email
+  ${c.cyan}--team <team>${c.reset}          Team name
+
+  ${c.cyan}--scope <type>${c.reset}         Scope: repo, local ${c.dim}(default: repo)${c.reset}
+  ${c.cyan}--expires <days>${c.reset}       Auto-expire after N days
+  ${c.cyan}--review <days>${c.reset}        Schedule review after N days
+
+${c.bold}GLOBAL OPTIONS${c.reset}
+  ${c.cyan}--json${c.reset}                Output as JSON (for CI/automation)
+  ${c.cyan}--verbose, -v${c.reset}         Show detailed information
+  ${c.cyan}--dry-run${c.reset}             Preview changes without applying
+  ${c.cyan}--no-strict${c.reset}           Disable strict validation warnings
+  ${c.cyan}--path <dir>${c.reset}          Project root ${c.dim}(default: cwd)${c.reset}
+
+${c.bold}JUSTIFICATION CATEGORIES${c.reset}
+${categories}
+
+${c.bold}EXAMPLES${c.reset}
+
+  ${c.dim}# Suppress a specific finding (false positive)${c.reset}
+  vibecheck safelist add \\
+    --id MOCK_DATA_abc123 \\
+    --reason "Test fixture data, not production code" \\
+    --category false-positive \\
+    --owner "Jane Developer"
+
+  ${c.dim}# Suppress a pattern in test files${c.reset}
+  vibecheck safelist add \\
+    --pattern "lorem ipsum" \\
+    --file "**/*.test.ts" \\
+    --reason "Placeholder text in tests" \\
+    --category test-fixture \\
+    --owner "QA Team"
+
+  ${c.dim}# Accept risk for legacy code with expiration${c.reset}
+  vibecheck safelist add \\
+    --pattern "vulnerable-function" \\
+    --reason "Legacy code pending refactor - tracked in JIRA-123" \\
+    --category accepted-risk \\
+    --ticket "https://jira.example.com/JIRA-123" \\
+    --owner "Security Team" \\
+    --expires 90
+
+  ${c.dim}# Local-only suppression (not committed)${c.reset}
+  vibecheck safelist add \\
+    --id DEV_xyz \\
+    --reason "Local dev environment artifact" \\
+    --category temporary \\
+    --owner "Me" \\
+    --scope local \\
+    --expires 7
+
+  ${c.dim}# Show suppression health report${c.reset}
+  vibecheck safelist report
+
+  ${c.dim}# Clean up expired entries${c.reset}
+  vibecheck safelist clean
+
+${c.bold}SCOPE TYPES${c.reset}
+  ${c.cyan}repo${c.reset}      Committed to version control, applies to everyone
+  ${c.cyan}local${c.reset}     Machine-specific, .gitignored
+
+${c.bold}ENFORCEMENT${c.reset}
+  Safelist is checked by: ${safelist.SAFELIST_COMMANDS.map(cmd => c.cyan + cmd + c.reset).join(", ")}
+  Suppressed findings are reported separately (not hidden).
+`);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ARGUMENT PARSING
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check for conflicts with existing entries
+ */
+function checkForConflicts(newEntry, existingSafelist) {
+  const conflicts = [];
+  
+  if (!existingSafelist?.entries) return conflicts;
+  
+  for (const existing of existingSafelist.entries) {
+    // Same finding ID
+    if (newEntry.target?.findingId && existing.target?.findingId === newEntry.target.findingId) {
+      conflicts.push({
+        id: existing.id,
+        type: "duplicate",
+        reason: `Same finding ID: ${newEntry.target.findingId}`,
+      });
+      continue;
+    }
+    
+    // Same rule ID
+    if (newEntry.target?.ruleId && existing.target?.ruleId === newEntry.target.ruleId) {
+      conflicts.push({
+        id: existing.id,
+        type: "duplicate",
+        reason: `Same rule ID: ${newEntry.target.ruleId}`,
+      });
+      continue;
+    }
+    
+    // Overlapping patterns
+    if (newEntry.target?.pattern && existing.target?.pattern) {
+      if (safelist.patternsOverlap(newEntry.target.pattern, existing.target.pattern)) {
+        conflicts.push({
+          id: existing.id,
+          type: "overlap",
+          reason: `Overlapping pattern with: ${existing.target.pattern}`,
+        });
+        continue;
+      }
+    }
+    
+    // Same file (without different line ranges)
+    if (newEntry.target?.file && existing.target?.file) {
+      if (safelist.filesOverlap(newEntry.target.file, existing.target.file)) {
+        // Only conflict if line ranges overlap or are not specified
+        if (!newEntry.target.lines || !existing.target.lines ||
+            rangesOverlap(newEntry.target.lines, existing.target.lines)) {
+          conflicts.push({
+            id: existing.id,
+            type: "overlap",
+            reason: `Overlapping file scope: ${existing.target.file}`,
+          });
+        }
+      }
+    }
+  }
+  
+  return conflicts;
+}
+
+/**
+ * Check if two line ranges overlap
+ */
+function rangesOverlap(range1, range2) {
+  if (!range1 || !range2) return true; // No range = all lines = overlap
+  return range1[0] <= range2[1] && range2[0] <= range1[1];
+}
+
+function parseArgs(args) {
+  const opts = {
+    action: "list",
+    // Target
+    id: null,
+    pattern: null,
+    rule: null,
+    file: null,
+    lines: null,
+    // Justification
+    reason: null,
+    category: null,
+    ticket: null,
+    // Owner
+    owner: null,
+    email: null,
+    team: null,
+    // Scope & lifecycle
+    scope: "repo",
+    expires: null,
+    review: null,
+    commands: null,
+    // General
+    help: false,
+    json: false,
+    verbose: false,
+    dryRun: false,
+    strict: true,
+    path: process.cwd(),
+  };
+  
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const next = args[i + 1];
+    
+    // Flags
+    if (arg === "--help" || arg === "-h") opts.help = true;
+    else if (arg === "--json") opts.json = true;
+    else if (arg === "--verbose" || arg === "-v") opts.verbose = true;
+    else if (arg === "--dry-run" || arg === "--preview") opts.dryRun = true;
+    else if (arg === "--no-strict") opts.strict = false;
+    // Target
+    else if (arg === "--id") opts.id = args[++i];
+    else if (arg === "--pattern") opts.pattern = args[++i];
+    else if (arg === "--rule") opts.rule = args[++i];
+    else if (arg === "--file" || arg === "-f") opts.file = args[++i];
+    else if (arg === "--lines") opts.lines = args[++i];
+    // Justification
+    else if (arg === "--reason" || arg === "-r") opts.reason = args[++i];
+    else if (arg === "--category" || arg === "-c") opts.category = args[++i];
+    else if (arg === "--ticket" || arg === "-t") opts.ticket = args[++i];
+    // Owner
+    else if (arg === "--owner" || arg === "-o") opts.owner = args[++i];
+    else if (arg === "--email") opts.email = args[++i];
+    else if (arg === "--team") opts.team = args[++i];
+    // Scope & lifecycle
+    else if (arg === "--scope" || arg === "-s") opts.scope = args[++i];
+    else if (arg === "--expires" || arg === "-e") opts.expires = parseInt(args[++i], 10);
+    else if (arg === "--review") opts.review = parseInt(args[++i], 10);
+    else if (arg === "--commands") opts.commands = args[++i].split(",");
+    else if (arg === "--path" || arg === "-p") opts.path = args[++i];
+    // Action (positional)
+    else if (!arg.startsWith("-") && !opts.action || opts.action === "list") {
+      if (["list", "add", "remove", "check", "report", "migrate", "validate", "clean", "preview", "search", "stats"].includes(arg)) {
+        opts.action = arg;
+      }
+    }
+  }
+  
+  return opts;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ACTIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+async function actionList(projectRoot, opts) {
+  const { safelist: sl, warnings, errors } = safelist.loadSafelist(projectRoot);
+  
+  if (opts.json) {
+    console.log(JSON.stringify({
+      entries: sl.entries,
+      warnings,
+      errors,
+      stats: {
+        total: sl.entries.length,
+        repo: sl.entries.filter(e => e._source === "repo").length,
+        local: sl.entries.filter(e => e._source === "local").length,
+        expired: safelist.getExpired(sl).length,
+        expiringSoon: safelist.getExpiringSoon(sl).length,
+      },
+    }, null, 2));
+    return EXIT.SUCCESS;
+  }
+  
+  console.log(`\n${c.bold}${icons.list} Safelist Entries${c.reset}\n`);
+  
+  if (errors.length > 0) {
+    for (const err of errors) {
+      console.log(`  ${c.red}${icons.cross}${c.reset} ${err}`);
+    }
+    console.log();
+  }
+  
+  if (warnings.length > 0) {
+    for (const warn of warnings) {
+      console.log(`  ${c.yellow}${icons.warning}${c.reset} ${warn}`);
+    }
+    console.log();
+  }
+  
+  // Filter out expired
+  const now = Date.now();
+  const active = sl.entries.filter(e => {
+    if (!e.lifecycle?.expiresAt) return true;
+    return new Date(e.lifecycle.expiresAt).getTime() > now;
+  });
+  
+  if (active.length === 0) {
+    console.log(`  ${c.dim}No active entries in safelist.${c.reset}`);
+    console.log(`  ${c.dim}Add entries with: vibecheck safelist add --id <id> --reason "..." --category <cat> --owner <name>${c.reset}\n`);
+    return EXIT.SUCCESS;
+  }
+  
+  // Group by source
+  const bySource = { repo: [], local: [] };
+  for (const entry of active) {
+    (bySource[entry._source] || bySource.repo).push(entry);
+  }
+  
+  for (const [source, entries] of Object.entries(bySource)) {
+    if (entries.length === 0) continue;
+    
+    const scopeIcon = source === "local" ? icons.unlock : icons.lock;
+    console.log(`${c.bold}${scopeIcon} ${source.toUpperCase()} SCOPE${c.reset} ${c.dim}(${entries.length})${c.reset}\n`);
+    
+    for (const entry of entries) {
+      printEntry(entry, opts.verbose);
+    }
+  }
+  
+  // Summary
+  const expired = safelist.getExpired(sl);
+  const expiringSoon = safelist.getExpiringSoon(sl);
+  const dueForReview = safelist.getDueForReview(sl);
+  
+  console.log(`${c.dim}${"─".repeat(60)}${c.reset}`);
+  console.log(`  Total: ${active.length} active, ${expired.length} expired`);
+  if (expiringSoon.length > 0) {
+    console.log(`  ${c.yellow}${icons.clock}${c.reset} ${expiringSoon.length} expiring soon (7 days)`);
+  }
+  if (dueForReview.length > 0) {
+    console.log(`  ${c.yellow}${icons.review}${c.reset} ${dueForReview.length} due for review`);
+  }
+  console.log();
+  
+  return EXIT.SUCCESS;
+}
+
+function printEntry(entry, verbose = false) {
+  const cat = safelist.JUSTIFICATION_CATEGORIES[entry.justification?.category];
+  const catBadge = cat ? `${c.cyan}[${entry.justification.category}]${c.reset}` : "";
+  
+  // Expiry indicator
+  let expiryStr = "";
+  if (entry.lifecycle?.expiresAt) {
+    const expiresAt = new Date(entry.lifecycle.expiresAt);
+    const daysLeft = Math.ceil((expiresAt - Date.now()) / (1000 * 60 * 60 * 24));
+    if (daysLeft <= 7) {
+      expiryStr = `${c.yellow}${icons.clock} ${daysLeft}d${c.reset}`;
+    } else {
+      expiryStr = `${c.dim}expires ${expiresAt.toLocaleDateString()}${c.reset}`;
+    }
+  }
+  
+  console.log(`  ${c.green}${icons.check}${c.reset} ${c.bold}${entry.id}${c.reset} ${catBadge} ${expiryStr}`);
+  
+  // Target
+  if (entry.target?.findingId) {
+    console.log(`    ${c.dim}Finding:${c.reset} ${entry.target.findingId}`);
+  }
+  if (entry.target?.pattern) {
+    console.log(`    ${c.dim}Pattern:${c.reset} ${entry.target.pattern}`);
+  }
+  if (entry.target?.ruleId) {
+    console.log(`    ${c.dim}Rule:${c.reset} ${entry.target.ruleId}`);
+  }
+  if (entry.target?.file) {
+    console.log(`    ${c.dim}File:${c.reset} ${entry.target.file}${entry.target.lines ? `:${entry.target.lines.join("-")}` : ""}`);
+  }
+  
+  // Justification
+  console.log(`    ${c.dim}Reason:${c.reset} ${entry.justification?.reason || "No reason"}`);
+  if (entry.justification?.ticket) {
+    console.log(`    ${c.dim}Ticket:${c.reset} ${entry.justification.ticket}`);
+  }
+  
+  // Owner
+  console.log(`    ${c.dim}Owner:${c.reset} ${entry.owner?.name || "Unknown"}${entry.owner?.team ? ` (${entry.owner.team})` : ""}`);
+  
+  if (verbose) {
+    console.log(`    ${c.dim}Created:${c.reset} ${entry.lifecycle?.createdAt} by ${entry.lifecycle?.createdBy || "unknown"}`);
+    console.log(`    ${c.dim}Matches:${c.reset} ${entry.lifecycle?.matchCount || 0}`);
+    if (entry.lifecycle?.lastMatchedAt) {
+      console.log(`    ${c.dim}Last match:${c.reset} ${entry.lifecycle.lastMatchedAt}`);
+    }
+  }
+  
+  console.log();
+}
+
+async function actionAdd(projectRoot, opts) {
+  // Validate required fields
+  const missingFields = [];
+  
+  if (!opts.id && !opts.pattern && !opts.rule && !opts.file) {
+    missingFields.push("target (--id, --pattern, --rule, or --file)");
+  }
+  if (!opts.reason || opts.reason.length < 10) {
+    missingFields.push("--reason (min 10 characters)");
+  }
+  if (!opts.category) {
+    missingFields.push("--category");
+  } else if (!safelist.JUSTIFICATION_CATEGORIES[opts.category]) {
+    console.error(`\n  ${c.red}${icons.cross}${c.reset} Invalid category: ${opts.category}`);
+    console.error(`  ${c.dim}Valid categories: ${Object.keys(safelist.JUSTIFICATION_CATEGORIES).join(", ")}${c.reset}\n`);
+    return EXIT.USER_ERROR;
+  }
+  if (!opts.owner) {
+    missingFields.push("--owner");
+  }
+  
+  if (missingFields.length > 0) {
+    console.error(`\n  ${c.red}${icons.cross}${c.reset} Missing required fields:`);
+    for (const field of missingFields) {
+      console.error(`    ${c.yellow}•${c.reset} ${field}`);
+    }
+    console.error(`\n  ${c.dim}Run 'vibecheck safelist --help' for usage${c.reset}\n`);
+    return EXIT.USER_ERROR;
+  }
+  
+  // Check if category requires ticket
+  const category = safelist.JUSTIFICATION_CATEGORIES[opts.category];
+  if (category.requiresTicket && !opts.ticket) {
+    console.error(`\n  ${c.red}${icons.cross}${c.reset} Category '${opts.category}' requires --ticket`);
+    console.error(`  ${c.dim}${category.description}${c.reset}\n`);
+    return EXIT.USER_ERROR;
+  }
+  
+  // Check expiry constraints
+  if (category.maxExpiry) {
+    if (!opts.expires) {
+      console.error(`\n  ${c.red}${icons.cross}${c.reset} Category '${opts.category}' requires --expires (max ${category.maxExpiry} days)`);
+      return EXIT.USER_ERROR;
+    }
+    if (opts.expires > category.maxExpiry) {
+      console.error(`\n  ${c.red}${icons.cross}${c.reset} Category '${opts.category}' max expiry is ${category.maxExpiry} days`);
+      return EXIT.USER_ERROR;
+    }
+  }
+  
+  // Determine entry type
+  let type = "finding";
+  if (opts.pattern) type = "pattern";
+  else if (opts.rule) type = "rule";
+  else if (opts.file && !opts.id) type = "file";
+  
+  // Parse lines
+  let lines = null;
+  if (opts.lines) {
+    const parts = opts.lines.split("-").map(n => parseInt(n, 10));
+    lines = [parts[0], parts[1] || parts[0]];
+  }
+  
+  // Create entry
+  const entry = safelist.createEntry({
+    type,
+    findingId: opts.id,
+    pattern: opts.pattern,
+    ruleId: opts.rule,
+    file: opts.file,
+    lines,
+    reason: opts.reason,
+    category: opts.category,
+    ticket: opts.ticket,
+    ownerName: opts.owner,
+    ownerEmail: opts.email,
+    ownerTeam: opts.team,
+    scopeType: opts.scope,
+    commands: opts.commands,
+    expiresIn: opts.expires,
+    reviewIn: opts.review,
+  });
+  
+  // Validate
+  const validation = safelist.validateEntry(entry);
+  if (!validation.valid) {
+    console.error(`\n  ${c.red}${icons.cross}${c.reset} Validation failed:`);
+    for (const err of validation.errors) {
+      console.error(`    ${c.yellow}•${c.reset} ${err}`);
+    }
+    return EXIT.USER_ERROR;
+  }
+  
+  // Show warnings
+  if (validation.warnings && validation.warnings.length > 0 && !opts.json) {
+    console.log(`\n  ${c.yellow}${icons.warning}${c.reset} Warnings:`);
+    for (const warn of validation.warnings) {
+      console.log(`    ${c.dim}•${c.reset} ${warn}`);
+    }
+  }
+  
+  // Check for duplicate/overlapping entries
+  const { safelist: existingSafelist } = safelist.loadSafelist(projectRoot);
+  const conflicts = checkForConflicts(entry, existingSafelist);
+  
+  if (conflicts.length > 0 && !opts.json) {
+    console.log(`\n  ${c.yellow}${icons.warning}${c.reset} Potential conflicts with existing entries:`);
+    for (const conflict of conflicts) {
+      console.log(`    ${c.dim}•${c.reset} ${conflict.id}: ${conflict.reason}`);
+    }
+    console.log(`  ${c.dim}Consider removing duplicates or using more specific patterns.${c.reset}`);
+  }
+  
+  // Dry-run mode
+  if (opts.dryRun) {
+    if (opts.json) {
+      console.log(JSON.stringify({ 
+        dryRun: true, 
+        entry, 
+        validation,
+        conflicts,
+      }, null, 2));
+    } else {
+      console.log(`\n  ${c.cyan}${icons.info}${c.reset} Dry-run: Would add entry:`);
+      printEntry(entry, true);
+    }
+    return EXIT.SUCCESS;
+  }
+  
+  // Save
+  const result = safelist.saveEntry(projectRoot, entry, opts.scope);
+  
+  if (!result.success) {
+    console.error(`\n  ${c.red}${icons.cross}${c.reset} Failed to save: ${result.error}\n`);
+    return EXIT.INTERNAL_ERROR;
+  }
+  
+  // Ensure local safelist is gitignored
+  if (opts.scope === "local") {
+    safelist.ensureGitIgnore(projectRoot);
+  }
+  
+  if (opts.json) {
+    console.log(JSON.stringify({ success: true, entry }, null, 2));
+  } else {
+    console.log(`\n  ${c.green}${icons.add}${c.reset} Added safelist entry: ${c.bold}${entry.id}${c.reset}`);
+    console.log(`  ${c.dim}Scope: ${opts.scope} | Category: ${opts.category}${c.reset}`);
+    if (entry.lifecycle.expiresAt) {
+      console.log(`  ${c.dim}Expires: ${new Date(entry.lifecycle.expiresAt).toLocaleDateString()}${c.reset}`);
+    }
+    console.log();
+  }
+  
+  return EXIT.SUCCESS;
+}
+
+async function actionRemove(projectRoot, opts) {
+  if (!opts.id) {
+    console.error(`\n  ${c.red}${icons.cross}${c.reset} --id is required for remove\n`);
+    return EXIT.USER_ERROR;
+  }
+  
+  const result = safelist.removeEntry(projectRoot, opts.id);
+  
+  if (!result.success) {
+    console.error(`\n  ${c.red}${icons.cross}${c.reset} ${result.error}\n`);
+    return EXIT.INTERNAL_ERROR;
+  }
+  
+  if (opts.json) {
+    console.log(JSON.stringify({ success: true, removed: result.removed, source: result.source }, null, 2));
+  } else if (result.removed) {
+    console.log(`\n  ${c.green}${icons.remove}${c.reset} Removed entry: ${c.bold}${opts.id}${c.reset}`);
+    console.log(`  ${c.dim}From: ${result.source} safelist${c.reset}\n`);
+  } else {
+    console.log(`\n  ${c.yellow}${icons.warning}${c.reset} Entry not found: ${opts.id}\n`);
+  }
+  
+  return result.removed ? EXIT.SUCCESS : EXIT.NOT_FOUND;
+}
+
+async function actionCheck(projectRoot, opts) {
+  if (!opts.id) {
+    console.error(`\n  ${c.red}${icons.cross}${c.reset} --id is required for check\n`);
+    return EXIT.USER_ERROR;
+  }
+  
+  const { safelist: sl } = safelist.loadSafelist(projectRoot);
+  const result = safelist.isSuppressed({ id: opts.id }, sl);
+  
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.suppressed) {
+    console.log(`\n  ${c.green}${icons.check}${c.reset} ${c.bold}Suppressed${c.reset}`);
+    console.log(`  ${c.dim}Entry:${c.reset} ${result.entry?.id}`);
+    console.log(`  ${c.dim}Reason:${c.reset} ${result.reason}`);
+    console.log(`  ${c.dim}Owner:${c.reset} ${result.entry?.owner?.name || "Unknown"}\n`);
+  } else {
+    console.log(`\n  ${c.yellow}${icons.cross}${c.reset} ${c.bold}Not suppressed${c.reset}\n`);
+  }
+  
+  return result.suppressed ? EXIT.SUCCESS : EXIT.BLOCKING;
+}
+
+async function actionReport(projectRoot, opts) {
+  const { safelist: sl, warnings, errors } = safelist.loadSafelist(projectRoot);
+  
+  const expired = safelist.getExpired(sl);
+  const expiringSoon = safelist.getExpiringSoon(sl);
+  const dueForReview = safelist.getDueForReview(sl);
+  const unused = safelist.getUnused(sl);
+  
+  // Group by category
+  const byCategory = {};
+  for (const entry of sl.entries) {
+    const cat = entry.justification?.category || "unknown";
+    if (!byCategory[cat]) byCategory[cat] = [];
+    byCategory[cat].push(entry);
+  }
+  
+  // Group by owner
+  const byOwner = {};
+  for (const entry of sl.entries) {
+    const owner = entry.owner?.name || "Unknown";
+    if (!byOwner[owner]) byOwner[owner] = [];
+    byOwner[owner].push(entry);
+  }
+  
+  if (opts.json) {
+    console.log(JSON.stringify({
+      summary: {
+        total: sl.entries.length,
+        repo: sl.entries.filter(e => e._source === "repo").length,
+        local: sl.entries.filter(e => e._source === "local").length,
+      },
+      health: {
+        expired: expired.length,
+        expiringSoon: expiringSoon.length,
+        dueForReview: dueForReview.length,
+        unused: unused.length,
+      },
+      byCategory,
+      byOwner,
+      warnings,
+      errors,
+    }, null, 2));
+    return EXIT.SUCCESS;
+  }
+  
+  console.log(`
+${c.bold}╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║  ${icons.shield} ${c.cyan}SAFELIST HEALTH REPORT${c.reset}${c.bold}                                              ║
+║                                                                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝${c.reset}
+`);
+  
+  // Summary
+  console.log(`${c.bold}${icons.list} SUMMARY${c.reset}`);
+  console.log(`${"─".repeat(60)}`);
+  console.log(`  Total entries:     ${c.bold}${sl.entries.length}${c.reset}`);
+  console.log(`  Repo-wide:         ${sl.entries.filter(e => e._source === "repo").length}`);
+  console.log(`  Local-only:        ${sl.entries.filter(e => e._source === "local").length}`);
+  console.log();
+  
+  // Health
+  console.log(`${c.bold}${icons.warning} HEALTH${c.reset}`);
+  console.log(`${"─".repeat(60)}`);
+  
+  const healthyColor = (count, threshold) => count > threshold ? c.red : count > 0 ? c.yellow : c.green;
+  
+  console.log(`  ${healthyColor(expired.length, 0)}${icons.expired} Expired:${c.reset}          ${expired.length}`);
+  console.log(`  ${healthyColor(expiringSoon.length, 5)}${icons.clock} Expiring soon:${c.reset}    ${expiringSoon.length}`);
+  console.log(`  ${healthyColor(dueForReview.length, 3)}${icons.review} Due for review:${c.reset}   ${dueForReview.length}`);
+  console.log(`  ${healthyColor(unused.length, 10)}${icons.info} Unused (30d):${c.reset}     ${unused.length}`);
+  console.log();
+  
+  // By category
+  console.log(`${c.bold}${icons.info} BY CATEGORY${c.reset}`);
+  console.log(`${"─".repeat(60)}`);
+  for (const [cat, entries] of Object.entries(byCategory)) {
+    const catInfo = safelist.JUSTIFICATION_CATEGORIES[cat];
+    console.log(`  ${cat.padEnd(20)} ${entries.length} ${c.dim}(${catInfo?.name || "Unknown"})${c.reset}`);
+  }
+  console.log();
+  
+  // By owner
+  console.log(`${c.bold}${icons.person} BY OWNER${c.reset}`);
+  console.log(`${"─".repeat(60)}`);
+  for (const [owner, entries] of Object.entries(byOwner)) {
+    console.log(`  ${owner.padEnd(20)} ${entries.length}`);
+  }
+  console.log();
+  
+  // Action items
+  if (expired.length > 0 || dueForReview.length > 0 || unused.length > 5) {
+    console.log(`${c.bold}${icons.warning} ACTION ITEMS${c.reset}`);
+    console.log(`${"─".repeat(60)}`);
+    
+    if (expired.length > 0) {
+      console.log(`  ${c.red}•${c.reset} Clean up ${expired.length} expired entries: ${c.cyan}vibecheck safelist clean${c.reset}`);
+    }
+    if (dueForReview.length > 0) {
+      console.log(`  ${c.yellow}•${c.reset} Review ${dueForReview.length} entries due for review`);
+    }
+    if (unused.length > 5) {
+      console.log(`  ${c.yellow}•${c.reset} Consider removing ${unused.length} unused entries`);
+    }
+    console.log();
+  }
+  
+  return EXIT.SUCCESS;
+}
+
+async function actionMigrate(projectRoot, opts) {
+  const result = safelist.migrateLegacyAllowlist(projectRoot);
+  
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.success) {
+    if (result.migrated > 0) {
+      console.log(`\n  ${c.green}${icons.check}${c.reset} Migrated ${result.migrated} entries from legacy allowlist`);
+      console.log(`  ${c.dim}Original file renamed to allowlist.json.migrated${c.reset}\n`);
+    } else {
+      console.log(`\n  ${c.dim}No legacy allowlist.json found${c.reset}\n`);
+    }
+  } else {
+    console.error(`\n  ${c.red}${icons.cross}${c.reset} Migration failed: ${result.error}\n`);
+  }
+  
+  return result.success ? EXIT.SUCCESS : EXIT.INTERNAL_ERROR;
+}
+
+async function actionValidate(projectRoot, opts) {
+  const { safelist: sl, warnings, errors } = safelist.loadSafelist(projectRoot);
+  
+  const validation = safelist.validateSafelist(sl);
+  const allErrors = [...errors, ...validation.errors];
+  const allWarnings = [...warnings, ...validation.warnings];
+  
+  if (opts.json) {
+    console.log(JSON.stringify({
+      valid: allErrors.length === 0,
+      errors: allErrors,
+      warnings: allWarnings,
+    }, null, 2));
+  } else {
+    if (allErrors.length === 0 && allWarnings.length === 0) {
+      console.log(`\n  ${c.green}${icons.check}${c.reset} Safelist is valid\n`);
+    } else {
+      if (allErrors.length > 0) {
+        console.log(`\n  ${c.red}${icons.cross} ERRORS${c.reset}`);
+        for (const err of allErrors) {
+          console.log(`    ${c.red}•${c.reset} ${err}`);
+        }
+      }
+      if (allWarnings.length > 0) {
+        console.log(`\n  ${c.yellow}${icons.warning} WARNINGS${c.reset}`);
+        for (const warn of allWarnings) {
+          console.log(`    ${c.yellow}•${c.reset} ${warn}`);
+        }
+      }
+      console.log();
+    }
+  }
+  
+  return allErrors.length === 0 ? EXIT.SUCCESS : EXIT.BLOCKING;
+}
+
+async function actionClean(projectRoot, opts) {
+  const { safelist: sl, paths } = safelist.loadSafelist(projectRoot);
+  const expired = safelist.getExpired(sl);
+  
+  if (expired.length === 0) {
+    if (!opts.json) {
+      console.log(`\n  ${c.dim}No expired entries to clean${c.reset}\n`);
+    } else {
+      console.log(JSON.stringify({ cleaned: 0 }));
+    }
+    return EXIT.SUCCESS;
+  }
+  
+  // Dry-run mode
+  if (opts.dryRun) {
+    if (opts.json) {
+      console.log(JSON.stringify({ 
+        dryRun: true, 
+        wouldClean: expired.map(e => ({ id: e.id, expiresAt: e.lifecycle?.expiresAt })),
+      }, null, 2));
+    } else {
+      console.log(`\n  ${c.cyan}${icons.info}${c.reset} Dry-run: Would clean ${expired.length} entries:`);
+      for (const entry of expired) {
+        console.log(`    ${c.dim}•${c.reset} ${entry.id} (expired ${new Date(entry.lifecycle?.expiresAt).toLocaleDateString()})`);
+      }
+      console.log();
+    }
+    return EXIT.SUCCESS;
+  }
+  
+  // Remove expired entries
+  let cleaned = 0;
+  for (const entry of expired) {
+    const result = safelist.removeEntry(projectRoot, entry.id);
+    if (result.removed) cleaned++;
+  }
+  
+  if (opts.json) {
+    console.log(JSON.stringify({ cleaned }));
+  } else {
+    console.log(`\n  ${c.green}${icons.remove}${c.reset} Cleaned ${cleaned} expired entries\n`);
+  }
+  
+  return EXIT.SUCCESS;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MAIN
+// ═══════════════════════════════════════════════════════════════════════════════
+
+async function runSafelist(args = [], context = {}) {
+  const { flags: globalFlags } = parseGlobalFlags(args);
+  const opts = parseArgs(args);
+  
+  if (opts.help || globalFlags.help) {
+    printHelp();
+    return EXIT.SUCCESS;
+  }
+  
+  opts.json = opts.json || isJsonMode(globalFlags);
+  const projectRoot = path.resolve(opts.path || context.repoRoot || process.cwd());
+  
+  // Validate project exists
+  if (!fs.existsSync(projectRoot)) {
+    if (opts.json) {
+      console.log(JSON.stringify({ error: `Path not found: ${projectRoot}` }));
+    } else {
+      console.error(`\n  ${c.red}${icons.cross}${c.reset} Path not found: ${projectRoot}\n`);
+    }
+    return EXIT.NOT_FOUND;
+  }
+  
+  switch (opts.action) {
+    case "list":
+      return actionList(projectRoot, opts);
+    case "add":
+      return actionAdd(projectRoot, opts);
+    case "remove":
+      return actionRemove(projectRoot, opts);
+    case "check":
+      return actionCheck(projectRoot, opts);
+    case "report":
+      return actionReport(projectRoot, opts);
+    case "migrate":
+      return actionMigrate(projectRoot, opts);
+    case "validate":
+      return actionValidate(projectRoot, opts);
+    case "clean":
+      return actionClean(projectRoot, opts);
+    case "search":
+      return actionSearch(projectRoot, opts);
+    case "stats":
+      return actionStats(projectRoot, opts);
+    default:
+      console.error(`\n  ${c.red}${icons.cross}${c.reset} Unknown action: ${opts.action}\n`);
+      return EXIT.USER_ERROR;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ADDITIONAL ACTIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+async function actionSearch(projectRoot, opts) {
+  const { safelist: sl } = safelist.loadSafelist(projectRoot);
+  
+  // Search criteria
+  const query = opts.pattern || opts.id || opts.file || opts.owner;
+  if (!query) {
+    console.error(`\n  ${c.red}${icons.cross}${c.reset} Search requires --pattern, --id, --file, or --owner\n`);
+    return EXIT.USER_ERROR;
+  }
+  
+  const results = sl.entries.filter(entry => {
+    // Search by ID
+    if (opts.id && entry.id.toLowerCase().includes(opts.id.toLowerCase())) {
+      return true;
+    }
+    
+    // Search by pattern
+    if (opts.pattern) {
+      const targets = [
+        entry.target?.findingId,
+        entry.target?.pattern,
+        entry.target?.ruleId,
+        entry.target?.file,
+        entry.justification?.reason,
+      ].filter(Boolean);
+      
+      const regex = safelist.getCachedRegex(opts.pattern, "i");
+      if (regex && targets.some(t => regex.test(t))) {
+        return true;
+      }
+    }
+    
+    // Search by file
+    if (opts.file && entry.target?.file) {
+      if (entry.target.file.toLowerCase().includes(opts.file.toLowerCase())) {
+        return true;
+      }
+    }
+    
+    // Search by owner
+    if (opts.owner) {
+      const ownerStr = `${entry.owner?.name || ""} ${entry.owner?.team || ""} ${entry.owner?.email || ""}`.toLowerCase();
+      if (ownerStr.includes(opts.owner.toLowerCase())) {
+        return true;
+      }
+    }
+    
+    // Search by category
+    if (opts.category && entry.justification?.category === opts.category) {
+      return true;
+    }
+    
+    return false;
+  });
+  
+  if (opts.json) {
+    console.log(JSON.stringify({ results, count: results.length }, null, 2));
+    return EXIT.SUCCESS;
+  }
+  
+  console.log(`\n${c.bold}${icons.list} Search Results${c.reset} ${c.dim}(${results.length} found)${c.reset}\n`);
+  
+  if (results.length === 0) {
+    console.log(`  ${c.dim}No entries match your search.${c.reset}\n`);
+    return EXIT.SUCCESS;
+  }
+  
+  for (const entry of results) {
+    printEntry(entry, opts.verbose);
+  }
+  
+  return EXIT.SUCCESS;
+}
+
+async function actionStats(projectRoot, opts) {
+  const { safelist: sl, warnings, errors } = safelist.loadSafelist(projectRoot);
+  
+  // Compute detailed statistics
+  const now = Date.now();
+  const stats = {
+    total: sl.entries.length,
+    byScope: {
+      repo: sl.entries.filter(e => e._source === "repo").length,
+      local: sl.entries.filter(e => e._source === "local").length,
+    },
+    byType: {},
+    byCategory: {},
+    byOwner: {},
+    lifecycle: {
+      expired: 0,
+      expiringSoon: 0,
+      permanent: 0,
+      withExpiry: 0,
+      dueForReview: 0,
+    },
+    activity: {
+      totalMatches: 0,
+      neverMatched: 0,
+      lastWeek: 0,
+      lastMonth: 0,
+    },
+    age: {
+      today: 0,
+      thisWeek: 0,
+      thisMonth: 0,
+      older: 0,
+    },
+  };
+  
+  const oneDay = 24 * 60 * 60 * 1000;
+  const oneWeek = 7 * oneDay;
+  const oneMonth = 30 * oneDay;
+  
+  for (const entry of sl.entries) {
+    // By type
+    stats.byType[entry.type] = (stats.byType[entry.type] || 0) + 1;
+    
+    // By category
+    const cat = entry.justification?.category || "unknown";
+    stats.byCategory[cat] = (stats.byCategory[cat] || 0) + 1;
+    
+    // By owner
+    const owner = entry.owner?.name || "Unknown";
+    stats.byOwner[owner] = (stats.byOwner[owner] || 0) + 1;
+    
+    // Lifecycle
+    if (entry.lifecycle?.expiresAt) {
+      const expiresAt = new Date(entry.lifecycle.expiresAt).getTime();
+      if (expiresAt < now) {
+        stats.lifecycle.expired++;
+      } else if (expiresAt < now + oneWeek) {
+        stats.lifecycle.expiringSoon++;
+      }
+      stats.lifecycle.withExpiry++;
+    } else {
+      stats.lifecycle.permanent++;
+    }
+    
+    if (entry.lifecycle?.reviewAt) {
+      const reviewAt = new Date(entry.lifecycle.reviewAt).getTime();
+      if (reviewAt < now) {
+        stats.lifecycle.dueForReview++;
+      }
+    }
+    
+    // Activity
+    const matchCount = entry.lifecycle?.matchCount || 0;
+    stats.activity.totalMatches += matchCount;
+    if (matchCount === 0) {
+      stats.activity.neverMatched++;
+    }
+    
+    if (entry.lifecycle?.lastMatchedAt) {
+      const lastMatched = new Date(entry.lifecycle.lastMatchedAt).getTime();
+      if (lastMatched > now - oneWeek) {
+        stats.activity.lastWeek++;
+      } else if (lastMatched > now - oneMonth) {
+        stats.activity.lastMonth++;
+      }
+    }
+    
+    // Age
+    if (entry.lifecycle?.createdAt) {
+      const created = new Date(entry.lifecycle.createdAt).getTime();
+      if (created > now - oneDay) {
+        stats.age.today++;
+      } else if (created > now - oneWeek) {
+        stats.age.thisWeek++;
+      } else if (created > now - oneMonth) {
+        stats.age.thisMonth++;
+      } else {
+        stats.age.older++;
+      }
+    }
+  }
+  
+  if (opts.json) {
+    console.log(JSON.stringify(stats, null, 2));
+    return EXIT.SUCCESS;
+  }
+  
+  console.log(`
+${c.bold}╔══════════════════════════════════════════════════════════════════════════════╗
+║  ${icons.shield} ${c.cyan}SAFELIST STATISTICS${c.reset}${c.bold}                                                  ║
+╚══════════════════════════════════════════════════════════════════════════════╝${c.reset}
+`);
+  
+  // Overview
+  console.log(`${c.bold}OVERVIEW${c.reset}`);
+  console.log(`${"─".repeat(60)}`);
+  console.log(`  Total entries:     ${c.bold}${stats.total}${c.reset}`);
+  console.log(`  Repo-wide:         ${stats.byScope.repo}`);
+  console.log(`  Local-only:        ${stats.byScope.local}`);
+  console.log();
+  
+  // By type
+  console.log(`${c.bold}BY TYPE${c.reset}`);
+  console.log(`${"─".repeat(60)}`);
+  for (const [type, count] of Object.entries(stats.byType)) {
+    const bar = "█".repeat(Math.min(20, Math.round(count / stats.total * 20)));
+    console.log(`  ${type.padEnd(12)} ${bar.padEnd(20)} ${count}`);
+  }
+  console.log();
+  
+  // Lifecycle
+  console.log(`${c.bold}LIFECYCLE${c.reset}`);
+  console.log(`${"─".repeat(60)}`);
+  console.log(`  ${stats.lifecycle.expired > 0 ? c.red : c.green}Expired:${c.reset}          ${stats.lifecycle.expired}`);
+  console.log(`  ${stats.lifecycle.expiringSoon > 0 ? c.yellow : c.green}Expiring soon:${c.reset}    ${stats.lifecycle.expiringSoon}`);
+  console.log(`  With expiry:       ${stats.lifecycle.withExpiry}`);
+  console.log(`  Permanent:         ${stats.lifecycle.permanent}`);
+  console.log(`  ${stats.lifecycle.dueForReview > 0 ? c.yellow : c.green}Due for review:${c.reset}   ${stats.lifecycle.dueForReview}`);
+  console.log();
+  
+  // Activity
+  console.log(`${c.bold}ACTIVITY${c.reset}`);
+  console.log(`${"─".repeat(60)}`);
+  console.log(`  Total matches:     ${stats.activity.totalMatches}`);
+  console.log(`  ${stats.activity.neverMatched > 5 ? c.yellow : c.green}Never matched:${c.reset}    ${stats.activity.neverMatched}`);
+  console.log(`  Active last week:  ${stats.activity.lastWeek}`);
+  console.log(`  Active last month: ${stats.activity.lastMonth}`);
+  console.log();
+  
+  // Age
+  console.log(`${c.bold}AGE DISTRIBUTION${c.reset}`);
+  console.log(`${"─".repeat(60)}`);
+  console.log(`  Today:             ${stats.age.today}`);
+  console.log(`  This week:         ${stats.age.thisWeek}`);
+  console.log(`  This month:        ${stats.age.thisMonth}`);
+  console.log(`  Older:             ${stats.age.older}`);
+  console.log();
+  
+  return EXIT.SUCCESS;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = { 
+  runSafelist,
+  // Re-export safelist module for integration
+  ...safelist,
+};