vibecheck-ai 2.0.2 → 5.0.0

package/bin/runners/runDoctor.js

@@ -0,0 +1,877 @@
+/**
+ * vibecheck doctor - Enterprise Environment Diagnostics
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * ENTERPRISE EDITION - World-Class Terminal Experience
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Comprehensive environment checks with auto-fix capability.
+ * 
+ * Features:
+ * - Full environment diagnostics (Node, npm, OS, build tools, etc.)
+ * - OS-specific quirk detection (Windows/macOS/Linux)
+ * - Known failure signature matching with exact remediation
+ * - "Fix Script" generation (copy-paste commands)
+ * - "Diagnosis Receipt" JSON export
+ * - Safe `--repair` mode for non-destructive fixes
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { 
+  generateRunId, 
+  createJsonOutput, 
+  writeJsonOutput, 
+  exitCodeToVerdict,
+  verdictToExitCode,
+  saveArtifact 
+} = require("./lib/cli-output");
+const { parseGlobalFlags, shouldShowBanner, shouldSuppressOutput, isJsonMode } = require("./lib/global-flags");
+const { EXIT } = require("./lib/exit-codes");
+const { formatWorkflowUpsell } = require("./lib/upsell");
+const { getApiKey } = require("./lib/auth");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ADVANCED TERMINAL - ANSI CODES & UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  italic: '\x1b[3m',
+  underline: '\x1b[4m',
+  // Colors
+  black: '\x1b[30m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  // Bright colors
+  gray: '\x1b[90m',
+  brightRed: '\x1b[91m',
+  brightGreen: '\x1b[92m',
+  brightYellow: '\x1b[93m',
+  brightBlue: '\x1b[94m',
+  brightMagenta: '\x1b[95m',
+  brightCyan: '\x1b[96m',
+  brightWhite: '\x1b[97m',
+  // Cursor control
+  clearLine: '\x1b[2K',
+  hideCursor: '\x1b[?25l',
+  showCursor: '\x1b[?25h',
+};
+
+// 256-color / True color support
+const rgb = (r, g, b) => `\x1b[38;2;${r};${g};${b}m`;
+const bgRgb = (r, g, b) => `\x1b[48;2;${r};${g};${b}m`;
+
+// Premium color palette
+const colors = {
+  // Gradients for banner
+  gradient1: rgb(100, 200, 255),   // Light blue
+  gradient2: rgb(80, 180, 255),    // Blue
+  gradient3: rgb(60, 160, 255),    // Deeper blue
+  gradient4: rgb(40, 140, 255),    // Even deeper
+  gradient5: rgb(20, 120, 255),    // Deep blue
+  gradient6: rgb(0, 100, 255),     // Navy
+  
+  // Status colors
+  healthy: rgb(0, 255, 150),
+  warning: rgb(255, 200, 0),
+  error: rgb(255, 80, 80),
+  critical: rgb(255, 40, 40),
+  
+  // UI colors
+  accent: rgb(100, 200, 255),
+  muted: rgb(120, 120, 140),
+  subtle: rgb(80, 80, 100),
+  highlight: rgb(255, 255, 255),
+  
+  // Category colors
+  system: rgb(150, 200, 255),
+  runtime: rgb(200, 150, 255),
+  project: rgb(255, 200, 150),
+  security: rgb(255, 150, 150),
+  network: rgb(150, 255, 200),
+  vibecheck: rgb(255, 150, 255),
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// PREMIUM BANNER
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const DOCTOR_BANNER = `
+${rgb(100, 200, 255)}  ██████╗  ██████╗  ██████╗████████╗ ██████╗ ██████╗ ${c.reset}
+${rgb(80, 180, 255)}  ██╔══██╗██╔═══██╗██╔════╝╚══██╔══╝██╔═══██╗██╔══██╗${c.reset}
+${rgb(60, 160, 255)}  ██║  ██║██║   ██║██║        ██║   ██║   ██║██████╔╝${c.reset}
+${rgb(40, 140, 255)}  ██║  ██║██║   ██║██║        ██║   ██║   ██║██╔══██╗${c.reset}
+${rgb(20, 120, 255)}  ██████╔╝╚██████╔╝╚██████╗   ██║   ╚██████╔╝██║  ██║${c.reset}
+${rgb(0, 100, 255)}  ╚═════╝  ╚═════╝  ╚═════╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝${c.reset}
+`;
+
+const BANNER_FULL = `
+${rgb(100, 200, 255)}  ██╗   ██╗██╗██████╗ ███████╗ ██████╗██╗  ██╗███████╗ ██████╗██╗  ██╗${c.reset}
+${rgb(90, 190, 255)}  ██║   ██║██║██╔══██╗██╔════╝██╔════╝██║  ██║██╔════╝██╔════╝██║ ██╔╝${c.reset}
+${rgb(80, 180, 255)}  ██║   ██║██║██████╔╝█████╗  ██║     ███████║█████╗  ██║     █████╔╝ ${c.reset}
+${rgb(60, 160, 255)}  ╚██╗ ██╔╝██║██╔══██╗██╔══╝  ██║     ██╔══██║██╔══╝  ██║     ██╔═██╗ ${c.reset}
+${rgb(40, 140, 255)}   ╚████╔╝ ██║██████╔╝███████╗╚██████╗██║  ██║███████╗╚██████╗██║  ██╗${c.reset}
+${rgb(20, 120, 255)}    ╚═══╝  ╚═╝╚═════╝ ╚══════╝ ╚═════╝╚═╝  ╚═╝╚══════╝ ╚═════╝╚═╝  ╚═╝${c.reset}
+
+${c.dim}  ┌─────────────────────────────────────────────────────────────────────┐${c.reset}
+${c.dim}  │${c.reset}  ${rgb(100, 200, 255)}🩺${c.reset} ${c.bold}DOCTOR${c.reset} ${c.dim}•${c.reset} ${rgb(200, 200, 200)}Environment Diagnostics${c.reset} ${c.dim}•${c.reset} ${rgb(150, 150, 150)}Auto-Fix${c.reset} ${c.dim}•${c.reset} ${rgb(100, 100, 100)}Health Check${c.reset}  ${c.dim}│${c.reset}
+${c.dim}  └─────────────────────────────────────────────────────────────────────┘${c.reset}
+`;
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TERMINAL UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const BOX = {
+  topLeft: '╭', topRight: '╮', bottomLeft: '╰', bottomRight: '╯',
+  horizontal: '─', vertical: '│',
+  teeRight: '├', teeLeft: '┤', teeDown: '┬', teeUp: '┴',
+  cross: '┼',
+  dTopLeft: '╔', dTopRight: '╗', dBottomLeft: '╚', dBottomRight: '╝',
+  dHorizontal: '═', dVertical: '║',
+};
+
+const ICONS = {
+  doctor: '🩺',
+  check: '✓',
+  cross: '✗',
+  warning: '⚠',
+  info: 'ℹ',
+  arrow: '→',
+  bullet: '•',
+  sparkle: '✨',
+  wrench: '🔧',
+  shield: '🛡️',
+  lightning: '⚡',
+  package: '📦',
+  folder: '📁',
+  file: '📄',
+  gear: '⚙️',
+  clock: '⏱',
+  network: '🌐',
+  lock: '🔒',
+  node: '📗',
+  npm: '📦',
+  ts: '🔷',
+  disk: '💾',
+  memory: '🧠',
+  cpu: '🖥️',
+  healthy: '💚',
+  sick: '🤒',
+};
+
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const SPINNER_DOTS = ['⣾', '⣽', '⣻', '⢿', '⡿', '⣟', '⣯', '⣷'];
+
+let spinnerIndex = 0;
+let spinnerInterval = null;
+let spinnerStartTime = null;
+
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.floor(ms / 60000)}m ${Math.floor((ms % 60000) / 1000)}s`;
+}
+
+function truncate(str, len) {
+  if (!str) return '';
+  if (str.length <= len) return str;
+  return str.slice(0, len - 3) + '...';
+}
+
+function padCenter(str, width) {
+  const padding = Math.max(0, width - str.length);
+  const left = Math.floor(padding / 2);
+  const right = padding - left;
+  return ' '.repeat(left) + str + ' '.repeat(right);
+}
+
+function progressBar(percent, width = 30, opts = {}) {
+  const filled = Math.round((percent / 100) * width);
+  const empty = width - filled;
+  
+  let filledColor;
+  if (opts.color) {
+    filledColor = opts.color;
+  } else if (percent >= 80) {
+    filledColor = colors.healthy;
+  } else if (percent >= 50) {
+    filledColor = colors.warning;
+  } else {
+    filledColor = colors.error;
+  }
+  
+  const filledChar = opts.filled || '█';
+  const emptyChar = opts.empty || '░';
+  
+  return `${filledColor}${filledChar.repeat(filled)}${c.dim}${emptyChar.repeat(empty)}${c.reset}`;
+}
+
+function startSpinner(message, style = 'dots') {
+  const frames = style === 'dots' ? SPINNER_DOTS : SPINNER_FRAMES;
+  spinnerStartTime = Date.now();
+  process.stdout.write(c.hideCursor);
+  
+  spinnerInterval = setInterval(() => {
+    const elapsed = formatDuration(Date.now() - spinnerStartTime);
+    process.stdout.write(`\r${c.clearLine}  ${colors.accent}${frames[spinnerIndex]}${c.reset} ${message} ${c.dim}${elapsed}${c.reset}`);
+    spinnerIndex = (spinnerIndex + 1) % frames.length;
+  }, 80);
+}
+
+function stopSpinner(message, success = true) {
+  if (spinnerInterval) {
+    clearInterval(spinnerInterval);
+    spinnerInterval = null;
+  }
+  const elapsed = spinnerStartTime ? formatDuration(Date.now() - spinnerStartTime) : '';
+  const icon = success ? `${colors.healthy}${ICONS.check}${c.reset}` : `${colors.error}${ICONS.cross}${c.reset}`;
+  process.stdout.write(`\r${c.clearLine}  ${icon} ${message} ${c.dim}${elapsed}${c.reset}\n`);
+  process.stdout.write(c.showCursor);
+  spinnerStartTime = null;
+}
+
+function printBanner(compact = false) {
+  console.log(compact ? DOCTOR_BANNER : BANNER_FULL);
+}
+
+function printDivider(char = '─', width = 69, color = c.dim) {
+  console.log(`${color}  ${char.repeat(width)}${c.reset}`);
+}
+
+function printSection(title, icon = '◆') {
+  console.log();
+  console.log(`  ${colors.accent}${icon}${c.reset} ${c.bold}${title}${c.reset}`);
+  printDivider();
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CATEGORY ICONS & COLORS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function getCategoryIcon(category) {
+  const icons = {
+    system: ICONS.cpu,
+    runtime: ICONS.node,
+    project: ICONS.package,
+    dependencies: ICONS.npm,
+    security: ICONS.shield,
+    network: ICONS.network,
+    vibecheck: ICONS.sparkle,
+  };
+  return icons[category] || ICONS.gear;
+}
+
+function getCategoryColor(category) {
+  const colorMap = {
+    system: colors.system,
+    runtime: colors.runtime,
+    project: colors.project,
+    dependencies: colors.accent,
+    security: colors.security,
+    network: colors.network,
+    vibecheck: colors.vibecheck,
+  };
+  return colorMap[category] || colors.accent;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// DOCTOR SERVICE LOADING
+// ═══════════════════════════════════════════════════════════════════════════════
+
+let DoctorService;
+try {
+  DoctorService = require("./lib/doctor").DoctorService;
+} catch {
+  // Fallback to legacy implementations
+  try {
+    DoctorService = require("./lib/doctor-v2").DoctorV2;
+  } catch {
+    DoctorService = require("./lib/doctor-enhanced").DoctorEnhanced;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MAIN DOCTOR FUNCTION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+async function runDoctor(args, context = {}) {
+  // Extract runId from context or generate new one
+  const runId = context.runId || generateRunId();
+  const startTime = context.startTime || new Date().toISOString();
+  
+  const opts = parseArgs(args);
+  const quiet = shouldSuppressOutput(opts);
+  const json = isJsonMode(opts);
+  const executionStart = Date.now();
+  
+  if (opts.help) {
+    printHelp(shouldShowBanner(opts));
+    return EXIT.SUCCESS;
+  }
+  
+  // Handle --list-actions (list available repair actions)
+  if (opts.listActions) {
+    return handleListActions(opts);
+  }
+  
+  // Handle --analyze (match error text against known signatures)
+  if (opts.analyze) {
+    return handleAnalyzeError(opts.analyze, opts);
+  }
+
+  const projectPath = path.resolve(opts.path || process.cwd());
+  
+  // Validate project path exists
+  if (!fs.existsSync(projectPath)) {
+    if (json) {
+      console.log(JSON.stringify({ success: false, error: `Project path does not exist: ${projectPath}` }));
+    } else {
+      console.error(`  ❌ Project path does not exist: ${projectPath}`);
+    }
+    return EXIT.NOT_FOUND;
+  }
+  const projectName = path.basename(projectPath);
+  
+  try {
+    // Print banner conditionally
+    if (shouldShowBanner(opts) && !quiet) {
+      printBanner();
+      console.log(`  ${c.dim}Project:${c.reset}  ${c.bold}${projectName}${c.reset}`);
+      console.log(`  ${c.dim}Path:${c.reset}     ${projectPath}`);
+      console.log();
+    }
+    
+    // Use new DoctorService if available
+    if (DoctorService.name === 'DoctorService') {
+      const doctor = new DoctorService(projectPath, {
+        json: opts.json,
+        fix: opts.fix && !opts.repair, // Don't use old fix if repair mode
+        fixDryRun: opts.dryRun,
+        quiet: opts.quiet || quiet,
+        verbose: opts.verbose,
+        categories: opts.categories,
+        skipNetwork: opts.skipNetwork,
+        saveReport: opts.saveReport,
+        failOnWarn: opts.failOnWarn,
+        runId,
+      });
+      
+      const results = await doctor.run();
+      const endTime = new Date().toISOString();
+      
+      // Get diagnostic results for enhanced features
+      const diagnostics = doctor.results || results.checks || [];
+      
+      // Handle --repair mode (safe repairs only)
+      if (opts.repair) {
+        const repairResults = await handleRepairMode(diagnostics, projectPath, opts);
+        if (repairResults.needsRecheck) {
+          if (!quiet && !json) {
+            console.log(`\n  ${colors.accent}↻${c.reset} Re-running diagnostics after repairs...\n`);
+          }
+          return runDoctor(args.filter(a => a !== '--repair'), context);
+        }
+      }
+      
+      // Handle --fix-script (generate copy-paste fix commands)
+      if (opts.fixScript) {
+        handleFixScript(diagnostics, projectPath, opts);
+      }
+      
+      // Handle --receipt (generate diagnosis receipt JSON)
+      if (opts.receipt) {
+        handleReceipt(diagnostics, projectPath, { startTime, endTime, runId }, opts);
+      }
+      
+      // Apply CLI output conventions
+      if (opts.json || json) {
+        // Enhanced JSON output with receipt format
+        const output = createJsonOutput({
+          runId,
+          command: "doctor",
+          startTime,
+          exitCode: results.exitCode || EXIT.SUCCESS,
+          verdict: exitCodeToVerdict(results.exitCode || EXIT.SUCCESS),
+          result: {
+            health: results.health || "unknown",
+            checks: diagnostics.map(d => ({
+              id: d.id,
+              name: d.name,
+              category: d.category,
+              severity: d.severity,
+              message: d.message,
+              detail: d.detail,
+              fixes: d.fixes,
+            })),
+            fixes: results.fixes || [],
+            summary: {
+              total: results.totalChecks || diagnostics.length,
+              passed: results.passedChecks || diagnostics.filter(d => d.severity === 'pass').length,
+              warnings: results.warnings || diagnostics.filter(d => d.severity === 'warning').length,
+              errors: results.errors || diagnostics.filter(d => d.severity === 'error' || d.severity === 'critical').length,
+            }
+          },
+          tier: "free",
+          version: require("../../package.json").version,
+          artifacts: results.reportPath ? [{
+            type: "report",
+            path: results.reportPath,
+            description: "Doctor report"
+          }] : []
+        });
+        
+        writeJsonOutput(output, opts.output);
+      }
+      
+      // Save artifacts
+      if (diagnostics.length > 0) {
+        saveArtifact(runId, "checks", diagnostics);
+      }
+      if (results.fixes) {
+        saveArtifact(runId, "fixes", results.fixes);
+      }
+      
+      // Map results to proper exit codes
+      if (results.errors > 0) return EXIT.BLOCKING;
+      if (results.warnings > 0) return EXIT.WARNINGS;
+      return EXIT.SUCCESS;
+    }
+    
+    // Legacy fallback
+    const doctor = new DoctorService(projectPath, opts);
+    return await doctor.diagnose();
+  } catch (error) {
+    if (json) {
+      console.log(JSON.stringify({ success: false, error: error.message }));
+    } else {
+      console.error(`  ❌ Doctor check failed: ${error.message}`);
+    }
+    return EXIT.INTERNAL_ERROR;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ENHANCED FEATURE HANDLERS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function handleListActions(opts) {
+  const safeRepair = require('./lib/doctor/safe-repair');
+  const actions = safeRepair.listSafeRepairActions();
+  
+  if (opts.json) {
+    console.log(JSON.stringify({ actions }, null, 2));
+  } else {
+    console.log(`\n  ${colors.accent}🔧${c.reset} ${c.bold}Available Safe Repair Actions${c.reset}\n`);
+    printDivider();
+    
+    for (const action of actions) {
+      console.log(`  ${colors.healthy}${action.id}${c.reset}`);
+      console.log(`    ${action.name}`);
+      console.log(`    ${c.dim}${action.description}${c.reset}`);
+      console.log();
+    }
+  }
+  
+  return EXIT.SUCCESS;
+}
+
+function handleAnalyzeError(errorText, opts) {
+  const failureSignatures = require('./lib/doctor/failure-signatures');
+  const matches = failureSignatures.matchFailureSignatures(errorText);
+  
+  if (opts.json) {
+    console.log(JSON.stringify({ 
+      analyzed: errorText.slice(0, 200),
+      matches: matches.map(m => ({
+        id: m.id,
+        name: m.name,
+        diagnosis: m.diagnosis,
+        remediation: m.remediation,
+        commands: m.commands,
+      })),
+      safeCommands: failureSignatures.getSafeCommands(matches),
+    }, null, 2));
+  } else {
+    if (matches.length === 0) {
+      console.log(`\n  ${colors.warning}⚠${c.reset} No known failure signatures matched.\n`);
+      console.log(`  ${c.dim}Try running: vibecheck doctor --verbose${c.reset}\n`);
+    } else {
+      console.log(`\n  ${colors.healthy}✓${c.reset} ${c.bold}Matched ${matches.length} known failure signature(s)${c.reset}\n`);
+      printDivider();
+      
+      for (const match of matches) {
+        console.log(failureSignatures.formatDiagnosis(match));
+        console.log();
+      }
+    }
+  }
+  
+  return EXIT.SUCCESS;
+}
+
+async function handleRepairMode(diagnostics, projectPath, opts) {
+  const safeRepair = require('./lib/doctor/safe-repair');
+  
+  const quiet = shouldSuppressOutput(opts);
+  const json = isJsonMode(opts);
+  
+  if (!quiet && !json) {
+    console.log(`\n  ${colors.accent}🔧${c.reset} ${c.bold}Safe Repair Mode${c.reset}`);
+    printDivider();
+  }
+  
+  const repairResults = await safeRepair.runSafeRepair(diagnostics, projectPath, {
+    dryRun: opts.dryRun,
+    verbose: opts.verbose,
+  });
+  
+  if (json) {
+    console.log(JSON.stringify({ repair: repairResults }, null, 2));
+  } else if (!quiet) {
+    const { summary, results } = repairResults;
+    
+    for (const result of results) {
+      const icon = result.status === 'success' ? `${colors.healthy}✓` : 
+                   result.status === 'failed' ? `${colors.error}✗` :
+                   `${colors.warning}○`;
+      console.log(`  ${icon}${c.reset} ${result.actionName}`);
+      console.log(`    ${c.dim}${result.message}${c.reset}`);
+    }
+    
+    console.log();
+    console.log(`  ${c.bold}Summary:${c.reset} ${summary.succeeded} succeeded, ${summary.failed} failed, ${summary.skipped} skipped`);
+  }
+  
+  return repairResults;
+}
+
+function handleFixScript(diagnostics, projectPath, opts) {
+  const fixScript = require('./lib/doctor/fix-script');
+  
+  const quiet = shouldSuppressOutput(opts);
+  const json = isJsonMode(opts);
+  
+  const format = opts.json ? 'json' : (opts.output?.endsWith('.md') ? 'markdown' : 'shell');
+  const result = fixScript.generateFixScript(diagnostics, {
+    projectPath,
+    format,
+    includeDangerous: false,
+    safeOnly: true,
+  });
+  
+  if (json || format === 'json') {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!quiet) {
+    // Save to file if output specified
+    if (opts.output) {
+      fs.writeFileSync(opts.output, result.script);
+      console.log(`\n  ${colors.healthy}✓${c.reset} Fix script saved to: ${opts.output}`);
+    } else {
+      console.log(`\n  ${colors.accent}📋${c.reset} ${c.bold}Fix Script${c.reset}`);
+      printDivider();
+      console.log(result.script);
+    }
+    
+    console.log(`\n  ${c.dim}Safe fixes: ${result.safeFixes}, Dangerous: ${result.dangerousFixes}, Manual: ${result.manualFixes}${c.reset}`);
+  }
+}
+
+function handleReceipt(diagnostics, projectPath, timing, opts) {
+  // Lazy load the module
+  const diagnosisReceipt = require('./lib/doctor/diagnosis-receipt');
+  
+  const quiet = shouldSuppressOutput(opts);
+  const json = isJsonMode(opts);
+  
+  const receipt = diagnosisReceipt.generateDiagnosisReceipt(diagnostics, {
+    projectPath,
+    startTime: timing.startTime,
+    endTime: timing.endTime,
+    runId: timing.runId,
+  });
+  
+  if (json) {
+    console.log(JSON.stringify(receipt, null, 2));
+  } else {
+    // Save to file
+    const outputPath = opts.output || path.join(projectPath, '.vibecheck', 'diagnosis-receipt.json');
+    diagnosisReceipt.saveReceipt(receipt, outputPath);
+    
+    if (!quiet) {
+      console.log(`\n  ${colors.healthy}✓${c.reset} Diagnosis receipt saved to: ${outputPath}`);
+      console.log(`  ${c.dim}Receipt ID: ${receipt.receiptId}${c.reset}`);
+      console.log(`  ${c.dim}Health: ${receipt.health.grade} (${receipt.health.score}/100) - ${receipt.health.verdict}${c.reset}`);
+    }
+  }
+}
+
+function parseArgs(args) {
+  // Parse global flags first
+  const { flags: globalFlags, cleanArgs } = parseGlobalFlags(args);
+  
+  const opts = {
+    ...globalFlags, // Merge global flags (json, verbose, noBanner, quiet, ci, help, etc.)
+    path: globalFlags.path || process.cwd(),
+    fix: false,
+    dryRun: false,
+    output: null,
+    categories: null,
+    skipNetwork: false,
+    saveReport: true,
+    failOnWarn: false,
+    // New options for enhanced doctor
+    repair: false,         // Safe repair mode (--repair)
+    fixScript: false,      // Generate fix script (--fix-script)
+    receipt: false,        // Generate diagnosis receipt (--receipt)
+    analyze: null,         // Analyze error output (--analyze <text>)
+    listActions: false,    // List available repair actions (--list-actions)
+  };
+
+  // Parse command-specific args from cleanArgs
+  for (let i = 0; i < cleanArgs.length; i++) {
+    const arg = cleanArgs[i];
+    switch (arg) {
+      case '--help':
+      case '-h':
+        opts.help = true;
+        break;
+      case '--path':
+      case '-p':
+        opts.path = cleanArgs[++i];
+        break;
+      case '--fix':
+        opts.fix = true;
+        break;
+      case '--repair':
+        opts.repair = true;
+        break;
+      case '--dry-run':
+        opts.dryRun = true;
+        break;
+      case '--fix-script':
+        opts.fixScript = true;
+        break;
+      case '--receipt':
+        opts.receipt = true;
+        break;
+      case '--analyze':
+        opts.analyze = cleanArgs[++i];
+        break;
+      case '--list-actions':
+        opts.listActions = true;
+        break;
+      case '--category':
+      case '-c':
+        if (!opts.categories) opts.categories = [];
+        opts.categories.push(cleanArgs[++i]);
+        break;
+      case '--skip-network':
+        opts.skipNetwork = true;
+        break;
+      case '--no-report':
+        opts.saveReport = false;
+        break;
+      case '--fail-on-warn':
+        opts.failOnWarn = true;
+        break;
+      case '--strict':
+        opts.strict = true;
+        break;
+      case '--output':
+      case '-o':
+        opts.output = cleanArgs[++i];
+        break;
+      default:
+        if (!arg.startsWith('-')) {
+          opts.path = path.resolve(arg);
+        }
+    }
+  }
+
+  return opts;
+}
+
+function printHelp(showBanner = true) {
+  if (showBanner && shouldShowBanner({})) {
+    console.log(BANNER_FULL);
+  }
+  console.log(`
+  ${c.bold}Usage:${c.reset} vibecheck doctor (health, diag) [options] [path]
+
+  ${c.bold}Environment Diagnostics${c.reset} — Comprehensive checks with auto-fix capability.
+  World-class diagnostic that gets you unblocked in minutes.
+
+  ${c.bold}Core Options:${c.reset}
+    ${colors.accent}--path, -p <path>${c.reset}     Project path ${c.dim}(default: current directory)${c.reset}
+    ${colors.accent}--json${c.reset}                Output JSON report only
+    ${colors.accent}--fix${c.reset}                 Auto-fix issues when possible
+    ${colors.accent}--dry-run${c.reset}             Show what fixes would be applied
+    ${colors.accent}--quiet, -q${c.reset}           Minimal output
+    ${colors.accent}--verbose, -v${c.reset}         Show detailed output and fix commands
+    ${colors.accent}--category, -c <cat>${c.reset}  Run specific category ${c.dim}(can repeat)${c.reset}
+    ${colors.accent}--skip-network${c.reset}        Skip network connectivity checks
+    ${colors.accent}--no-report${c.reset}           Don't save report files
+    ${colors.accent}--fail-on-warn${c.reset}        Exit code 2 for warnings ${c.dim}(CI mode)${c.reset}
+    ${colors.accent}--help, -h${c.reset}            Show this help
+
+  ${c.bold}Legendary Features:${c.reset}
+    ${colors.healthy}--repair${c.reset}              Safe repair mode ${c.dim}(clear cache, regen lock, etc.)${c.reset}
+    ${colors.healthy}--fix-script${c.reset}          Generate copy-paste fix commands
+    ${colors.healthy}--receipt${c.reset}             Generate diagnosis receipt JSON
+    ${colors.healthy}--analyze <error>${c.reset}     Match error against known failure signatures
+    ${colors.healthy}--list-actions${c.reset}        List all available safe repair actions
+
+  ${c.bold}Categories:${c.reset}
+    ${colors.system}${ICONS.cpu}${c.reset} ${c.bold}system${c.reset}         ${c.dim}OS, memory, disk, CPU, shell${c.reset}
+    ${colors.runtime}${ICONS.node}${c.reset} ${c.bold}runtime${c.reset}        ${c.dim}Node.js, npm, pnpm, yarn${c.reset}
+    ${colors.project}${ICONS.package}${c.reset} ${c.bold}project${c.reset}        ${c.dim}package.json, tsconfig, git state${c.reset}
+    ${colors.accent}${ICONS.npm}${c.reset} ${c.bold}dependencies${c.reset}   ${c.dim}Outdated packages, vulnerabilities${c.reset}
+    ${colors.security}${ICONS.shield}${c.reset} ${c.bold}security${c.reset}       ${c.dim}Secrets, gitignore, env files${c.reset}
+    ${colors.network}${ICONS.network}${c.reset} ${c.bold}network${c.reset}        ${c.dim}Internet, npm registry, API${c.reset}
+    ${colors.vibecheck}${ICONS.sparkle}${c.reset} ${c.bold}vibecheck${c.reset}      ${c.dim}Config, truth pack, scan status${c.reset}
+
+  ${c.bold}OS-Specific Checks:${c.reset}
+    ${c.dim}Windows:${c.reset} Long paths, PowerShell policy, antivirus, symlinks
+    ${c.dim}macOS:${c.reset}   Xcode CLI tools, Homebrew, Rosetta 2, file limits
+    ${c.dim}Linux:${c.reset}   build-essential, inotify watches, distro detection
+
+  ${c.bold}Exit Codes:${c.reset}
+    ${colors.healthy}0${c.reset}  Healthy ${c.dim}(or warnings without --fail-on-warn)${c.reset}
+    ${colors.warning}1${c.reset}  Warnings found
+    ${colors.error}2${c.reset}  Errors found
+    ${colors.critical}3${c.reset}  Critical issues found
+
+  ${c.bold}Examples:${c.reset}
+    ${c.dim}# Full diagnostic${c.reset}
+    vibecheck doctor
+
+    ${c.dim}# Safe repair mode (recommended first step)${c.reset}
+    vibecheck doctor --repair
+
+    ${c.dim}# Generate fix script for manual review${c.reset}
+    vibecheck doctor --fix-script -o fix.sh
+
+    ${c.dim}# Analyze a specific error message${c.reset}
+    vibecheck doctor --analyze "EACCES permission denied"
+
+    ${c.dim}# Generate diagnosis receipt for support${c.reset}
+    vibecheck doctor --receipt --json > diagnosis.json
+
+    ${c.dim}# JSON output for CI${c.reset}
+    vibecheck doctor --json --fail-on-warn
+
+    ${c.dim}# Security checks only${c.reset}
+    vibecheck doctor -c security
+
+    ${c.dim}# Skip slow network checks${c.reset}
+    vibecheck doctor --skip-network
+  `);
+}
+
+// Legacy function for backwards compatibility
+function runDoctorLegacy() {
+  console.log("\n  🩺 vibecheck DOCTOR\n");
+
+  const checks = [];
+
+  // Node version
+  const nodeVersion = process.version;
+  const nodeMajor = parseInt(nodeVersion.slice(1).split(".")[0], 10);
+  checks.push({
+    name: "Node.js",
+    status: nodeMajor >= 18 ? "pass" : "fail",
+    message: `${nodeVersion}`,
+    fix: nodeMajor < 18 ? "Upgrade to Node.js 18+" : null,
+  });
+
+  // Config file
+  const configPath = path.join(process.cwd(), ".vibecheckrc");
+  const hasConfig =
+    fs.existsSync(configPath) ||
+    fs.existsSync(path.join(process.cwd(), ".vibecheckrc"));
+  checks.push({
+    name: "Config",
+    status: hasConfig ? "pass" : "warn",
+    message: hasConfig ? "Found" : "Not found",
+    fix: !hasConfig ? "Run: vibecheck init" : null,
+  });
+
+  // Output directory
+  const outputDir = path.join(process.cwd(), ".vibecheck");
+  const hasOutput = fs.existsSync(outputDir);
+  checks.push({
+    name: "Output Dir",
+    status: hasOutput ? "pass" : "info",
+    message: hasOutput ? ".vibecheck/" : "Will be created on first scan",
+  });
+
+  // Package.json
+  const pkgPath = path.join(process.cwd(), "package.json");
+  const hasPkg = fs.existsSync(pkgPath);
+  checks.push({
+    name: "package.json",
+    status: hasPkg ? "pass" : "warn",
+    message: hasPkg ? "Found" : "Not found",
+  });
+
+  // TypeScript
+  const hasTsConfig = fs.existsSync(path.join(process.cwd(), "tsconfig.json"));
+  checks.push({
+    name: "TypeScript",
+    status: hasTsConfig ? "pass" : "info",
+    message: hasTsConfig ? "Enabled" : "JavaScript project",
+  });
+
+  // Collect results
+  let hasIssues = false;
+  const errors = [];
+  const warnings = [];
+  
+  for (const check of checks) {
+    if (check.status === "fail") {
+      hasIssues = true;
+      errors.push({ message: check.message || check.name });
+    } else if (check.status === "warn") {
+      warnings.push({ message: check.message || check.name });
+    }
+  }
+
+  // Get tier for upsell
+  const { key } = getApiKey();
+  const currentTier = key ? "starter" : "free";
+  
+  // Use Mission Control format
+  if (!opts.json && !opts.quiet) {
+    const { formatDoctorOutput } = require('./lib/doctor-output');
+    const summary = {
+      total: checks.length,
+      passed: checks.filter(c => c.status === "pass").length,
+      failed: checks.filter(c => c.status === "fail").length,
+      warnings: checks.filter(c => c.status === "warn").length,
+    };
+    
+    console.log(formatDoctorOutput({
+      checks,
+      summary,
+      healthy: !hasIssues,
+      errors,
+      warnings,
+    }, { projectPath: root, version: 'v3.5.5' }));
+  }
+  
+  return hasIssues ? EXIT.BLOCKING : EXIT.SUCCESS;
+}
+
+module.exports = { 
+  runDoctor: runDoctor,
+  runDoctorLegacy: runDoctorLegacy,
+};