@vibe-validate/cli 0.10.3 → 0.12.0

package/dist/commands/doctor.js

@@ -12,9 +12,14 @@
  */
 import { existsSync, readFileSync } from 'fs';
 import { execSync } from 'child_process';
-import { loadConfig } from '../utils/config-loader.js';
+import { stringify as stringifyYaml } from 'yaml';
+import { loadConfig, findConfigPath, loadConfigWithErrors } from '../utils/config-loader.js';
 import { checkSync, ciConfigToWorkflowOptions } from './generate-workflow.js';
 import { getMainBranch, getRemoteOrigin } from '@vibe-validate/config';
+import { formatTemplateList } from '../utils/template-discovery.js';
+import { checkHistoryHealth as checkValidationHistoryHealth } from '@vibe-validate/history';
+/** @deprecated State file deprecated in v0.12.0 - validation now uses git notes */
+const DEPRECATED_STATE_FILE = '.vibe-validate-state.yaml';
 /**
  * Check Node.js version meets requirements
  */
@@ -93,16 +98,12 @@ function checkGitRepository() {
  * Check if configuration file exists
  */
 function checkConfigFile() {
-    const configPatterns = [
-        'vibe-validate.config.yaml',
-        'vibe-validate.config.mjs', // Legacy (deprecated)
-    ];
-    const found = configPatterns.find(pattern => existsSync(pattern));
-    if (found) {
+    const yamlConfig = 'vibe-validate.config.yaml';
+    if (existsSync(yamlConfig)) {
         return {
             name: 'Configuration file',
             passed: true,
-            message: `Found: ${found}`,
+            message: `Found: ${yamlConfig}`,
         };
     }
     else {
@@ -114,48 +115,71 @@ function checkConfigFile() {
         };
     }
 }
-/**
- * Check if config format needs migration from .mjs to .yaml
- */
-function checkConfigFormatMigration() {
-    const mjsConfig = 'vibe-validate.config.mjs';
-    const yamlConfig = 'vibe-validate.config.yaml';
-    // If using YAML, all good!
-    if (existsSync(yamlConfig)) {
-        return {
-            name: 'Config format',
-            passed: true,
-            message: 'Using modern YAML format',
-        };
-    }
-    // If using legacy .mjs format, suggest migration
-    if (existsSync(mjsConfig)) {
-        return {
-            name: 'Config format',
-            passed: false,
-            message: 'Using deprecated .mjs format (will be removed in v1.0)',
-            suggestion: '⚠️  Migrate to YAML:\n   1. Run: vibe-validate init --migrate\n   2. Test the new YAML config\n   3. Delete vibe-validate.config.mjs after migration',
-        };
-    }
-    // No config found (will be caught by checkConfigFile)
-    return {
-        name: 'Config format',
-        passed: true,
-        message: 'Skipped (no config file)',
-    };
-}
 /**
  * Check if configuration is valid
+ *
+ * @param config - Config from loadConfig() (may be null)
+ * @param configWithErrors - Result from loadConfigWithErrors() with detailed error info
  */
-async function checkConfigValid(config) {
+async function checkConfigValid(config, configWithErrors) {
     try {
         if (!config) {
-            return {
-                name: 'Configuration valid',
-                passed: false,
-                message: 'Failed to load configuration',
-                suggestion: 'Check syntax in vibe-validate.config.*',
-            };
+            // Check if we have detailed error information
+            if (configWithErrors?.errors && configWithErrors.filePath) {
+                const fileName = configWithErrors.filePath.split('/').pop() || 'vibe-validate.config.yaml';
+                const errorList = configWithErrors.errors.slice(0, 5); // Show first 5 errors
+                const errorMessages = errorList.map(err => `     • ${err}`).join('\n');
+                return {
+                    name: 'Configuration valid',
+                    passed: false,
+                    message: `Found ${fileName} but it contains validation errors:\n${errorMessages}`,
+                    suggestion: [
+                        'Fix validation errors shown above',
+                        'See configuration docs: https://github.com/jdutton/vibe-validate/blob/main/docs/configuration-reference.md',
+                        'JSON Schema for IDE validation: https://raw.githubusercontent.com/jdutton/vibe-validate/main/packages/config/vibe-validate.schema.json',
+                        'Example YAML configs: https://github.com/jdutton/vibe-validate/tree/main/config-templates'
+                    ].join('\n   '),
+                };
+            }
+            // Fallback: try to find config file path
+            const configPath = findConfigPath();
+            if (configPath) {
+                const fileName = configPath.split('/').pop() || 'vibe-validate.config.yaml';
+                return {
+                    name: 'Configuration valid',
+                    passed: false,
+                    message: `Found ${fileName} but it contains validation errors`,
+                    suggestion: [
+                        `Fix syntax/validation errors in ${fileName}`,
+                        'See configuration docs: https://github.com/jdutton/vibe-validate/blob/main/docs/configuration-reference.md',
+                        'JSON Schema for IDE validation: https://raw.githubusercontent.com/jdutton/vibe-validate/main/packages/config/vibe-validate.schema.json',
+                        'Example YAML configs: https://github.com/jdutton/vibe-validate/tree/main/config-templates'
+                    ].join('\n   '),
+                };
+            }
+            else {
+                // No config file found
+                const templateList = formatTemplateList();
+                return {
+                    name: 'Configuration valid',
+                    passed: false,
+                    message: 'No configuration file found',
+                    suggestion: [
+                        'Copy a config template from GitHub:',
+                        'https://github.com/jdutton/vibe-validate/tree/main/config-templates',
+                        '',
+                        'Available templates:',
+                        ...templateList.map(line => line),
+                        '',
+                        'Quick start:',
+                        'curl -o vibe-validate.config.yaml \\',
+                        '  https://raw.githubusercontent.com/jdutton/vibe-validate/main/config-templates/typescript-nodejs.yaml',
+                        '',
+                        'JSON Schema for IDE validation:',
+                        'https://raw.githubusercontent.com/jdutton/vibe-validate/main/packages/config/vibe-validate.schema.json',
+                    ].join('\n   '),
+                };
+            }
         }
         return {
             name: 'Configuration valid',
@@ -168,7 +192,7 @@ async function checkConfigValid(config) {
             name: 'Configuration valid',
             passed: false,
             message: `Invalid configuration: ${_error instanceof Error ? _error.message : String(_error)}`,
-            suggestion: 'Fix syntax errors in vibe-validate.config.*',
+            suggestion: 'Check syntax in vibe-validate.config.yaml',
         };
     }
 }
@@ -235,7 +259,7 @@ async function checkWorkflowSync(config) {
                 message: 'Skipped (no config)',
             };
         }
-        // Use CI config from vibe-validate.config.mjs if available
+        // Use CI config from vibe-validate config
         const generateOptions = ciConfigToWorkflowOptions(config);
         const { inSync, diff } = checkSync(config, generateOptions);
         if (inSync) {
@@ -336,6 +360,19 @@ async function checkVersion() {
                 encoding: 'utf8',
                 stdio: 'pipe',
             }).trim();
+            // Compare versions (simple semver comparison)
+            const current = currentVersion.split('.').map(Number);
+            const latest = latestVersion.split('.').map(Number);
+            let isOutdated = false;
+            for (let i = 0; i < 3; i++) {
+                if (current[i] < latest[i]) {
+                    isOutdated = true;
+                    break;
+                }
+                else if (current[i] > latest[i]) {
+                    break; // Current is newer
+                }
+            }
             if (currentVersion === latestVersion) {
                 return {
                     name: 'vibe-validate version',
@@ -343,7 +380,8 @@ async function checkVersion() {
                     message: `Current version ${currentVersion} is up to date`,
                 };
             }
-            else {
+            else if (isOutdated) {
+                // Only show suggestion if current version is behind npm
                 return {
                     name: 'vibe-validate version',
                     passed: true, // Warning only, not a failure
@@ -351,6 +389,14 @@ async function checkVersion() {
                     suggestion: `Upgrade: npm install -D vibe-validate@latest (or pnpm add -D vibe-validate@latest)\n   💡 After upgrade: Run 'vibe-validate doctor' to verify setup`,
                 };
             }
+            else {
+                // Current version is ahead of npm (pre-release or unpublished)
+                return {
+                    name: 'vibe-validate version',
+                    passed: true,
+                    message: `Current: ${currentVersion} (ahead of npm: ${latestVersion})`,
+                };
+            }
         }
         catch (_npmError) {
             // npm registry unavailable - not a critical error
@@ -370,36 +416,35 @@ async function checkVersion() {
     }
 }
 /**
- * Check if .vibe-validate-state.yaml is in .gitignore
+ * Check if deprecated state file is in .gitignore
  */
 function checkGitignoreStateFile() {
     const gitignorePath = '.gitignore';
-    const stateFileName = '.vibe-validate-state.yaml';
+    const stateFileName = DEPRECATED_STATE_FILE;
     // Check if .gitignore exists
     if (!existsSync(gitignorePath)) {
         return {
             name: 'Gitignore state file',
-            passed: false,
-            message: '.gitignore file not found',
-            suggestion: 'Manual: echo ".vibe-validate-state.yaml" >> .gitignore\n   💡 Or run: vibe-validate init --fix-gitignore',
+            passed: true,
+            message: '.gitignore file not found (state file deprecated - using git notes)',
         };
     }
     try {
         const gitignoreContent = readFileSync(gitignorePath, 'utf8');
-        // Check if state file is already in .gitignore
+        // Check if deprecated state file is in .gitignore
         if (gitignoreContent.includes(stateFileName)) {
             return {
-                name: 'Gitignore state file',
-                passed: true,
-                message: '.vibe-validate-state.yaml is in .gitignore',
+                name: 'Gitignore state file (deprecated)',
+                passed: false,
+                message: `${DEPRECATED_STATE_FILE} in .gitignore (deprecated - can be removed)`,
+                suggestion: `Remove from .gitignore: sed -i.bak '/${DEPRECATED_STATE_FILE}/d' .gitignore && rm .gitignore.bak\n   ℹ️  Validation now uses git notes instead of state file`,
             };
         }
         else {
             return {
                 name: 'Gitignore state file',
-                passed: false,
-                message: '.vibe-validate-state.yaml not in .gitignore (state file should not be committed)',
-                suggestion: 'Manual: echo ".vibe-validate-state.yaml" >> .gitignore\n   💡 Or run: vibe-validate init --fix-gitignore',
+                passed: true,
+                message: 'No deprecated state file entries in .gitignore',
             };
         }
     }
@@ -413,24 +458,54 @@ function checkGitignoreStateFile() {
     }
 }
 /**
- * Check if validation state file exists
+ * Check if deprecated validation state file exists
  */
 function checkValidationState() {
-    const statePath = '.vibe-validate-state.yaml';
-    // This check is informational only - missing state file is not an error
-    // (fresh checkouts, CI environments, etc. won't have it until first validation run)
+    const statePath = DEPRECATED_STATE_FILE;
+    // Check if deprecated state file exists
     if (existsSync(statePath)) {
         return {
-            name: 'Validation state',
-            passed: true,
-            message: 'Validation state file exists',
+            name: 'Validation state (deprecated)',
+            passed: false,
+            message: `${DEPRECATED_STATE_FILE} found (deprecated file - safe to remove)`,
+            suggestion: `Remove deprecated state file: rm ${DEPRECATED_STATE_FILE}\n   ℹ️  Validation now uses git notes for improved caching`,
         };
     }
     else {
         return {
             name: 'Validation state',
-            passed: true, // Always pass - this is informational only
-            message: 'Validation state file not found (will be created on first validation run)',
+            passed: true,
+            message: 'No deprecated state file found (using git notes)',
+        };
+    }
+}
+/**
+ * Check validation history health
+ */
+async function checkHistoryHealth() {
+    try {
+        const health = await checkValidationHistoryHealth();
+        if (!health.shouldWarn) {
+            return {
+                name: 'Validation history',
+                passed: true,
+                message: `${health.totalNotes} tree hashes tracked, history is healthy`,
+            };
+        }
+        // Has warnings
+        return {
+            name: 'Validation history',
+            passed: false,
+            message: `${health.totalNotes} tree hashes tracked (${health.oldNotesCount} older than 90 days)`,
+            suggestion: 'Prune old history: vibe-validate history prune --older-than "90 days"',
+        };
+    }
+    catch (_error) {
+        // Git notes not available or other error - not critical
+        return {
+            name: 'Validation history',
+            passed: true,
+            message: 'History unavailable (not in git repo or no validation runs yet)',
         };
     }
 }
@@ -589,6 +664,91 @@ async function checkRemoteMainBranch(config) {
         };
     }
 }
+/**
+ * Check if secret scanning is configured and tool is available
+ */
+async function checkSecretScanning(config) {
+    try {
+        if (!config) {
+            return {
+                name: 'Pre-commit secret scanning',
+                passed: true,
+                message: 'Skipped (no config)',
+            };
+        }
+        const secretScanning = config.hooks?.preCommit?.secretScanning;
+        // If not configured at all, recommend enabling it
+        if (!secretScanning) {
+            return {
+                name: 'Pre-commit secret scanning',
+                passed: true,
+                message: 'Secret scanning not configured',
+                suggestion: 'Recommended: Enable secret scanning to prevent credential leaks\n   • Add to config: hooks.preCommit.secretScanning.enabled=true\n   • scanCommand: "gitleaks protect --staged --verbose"\n   • Install gitleaks: brew install gitleaks',
+            };
+        }
+        // If explicitly disabled, acknowledge user choice
+        if (secretScanning.enabled === false) {
+            return {
+                name: 'Pre-commit secret scanning',
+                passed: true,
+                message: 'Secret scanning disabled in config (user preference)',
+            };
+        }
+        // If enabled, check if tool is available
+        if (secretScanning.scanCommand) {
+            // Extract tool name (first word of command)
+            const toolName = secretScanning.scanCommand.split(' ')[0];
+            try {
+                // Try to get tool version
+                let version;
+                try {
+                    version = execSync(`${toolName} version`, { encoding: 'utf8', stdio: 'pipe' }).trim();
+                }
+                catch (_versionError) {
+                    // Try --version flag
+                    version = execSync(`${toolName} --version`, { encoding: 'utf8', stdio: 'pipe' }).trim();
+                }
+                return {
+                    name: 'Pre-commit secret scanning',
+                    passed: true,
+                    message: `Secret scanning enabled with ${toolName} ${version}`,
+                };
+            }
+            catch (_error) {
+                // Tool not found
+                // In CI, this is expected (secret scanning is pre-commit only, not needed in CI)
+                const isCI = process.env.CI === 'true' || process.env.CI === '1';
+                if (isCI) {
+                    return {
+                        name: 'Pre-commit secret scanning',
+                        passed: true,
+                        message: `Secret scanning enabled (pre-commit only, not needed in CI)`,
+                    };
+                }
+                return {
+                    name: 'Pre-commit secret scanning',
+                    passed: true, // Advisory only, never fails
+                    message: `Secret scanning enabled but '${toolName}' not found`,
+                    suggestion: `Install ${toolName}:\n   • gitleaks: brew install gitleaks\n   • Or disable: set hooks.preCommit.secretScanning.enabled=false in config`,
+                };
+            }
+        }
+        // Enabled but no scanCommand (should be caught by schema validation)
+        return {
+            name: 'Pre-commit secret scanning',
+            passed: true,
+            message: 'Secret scanning enabled but no scanCommand configured',
+            suggestion: 'Add hooks.preCommit.secretScanning.scanCommand to config',
+        };
+    }
+    catch (_error) {
+        return {
+            name: 'Pre-commit secret scanning',
+            passed: true,
+            message: 'Skipped (config or execution error)',
+        };
+    }
+}
 /**
  * Run all doctor checks
  */
@@ -597,12 +757,15 @@ export async function runDoctor(options = {}) {
     const allChecks = [];
     // Load config once to avoid duplicate warnings
     let config;
+    let configWithErrors;
     try {
         config = await loadConfig();
+        configWithErrors = await loadConfigWithErrors();
     }
     catch (_error) {
         // Config load error will be caught by checkConfigValid
         config = null;
+        configWithErrors = { config: null, errors: null, filePath: null };
     }
     // Run all checks
     allChecks.push(await checkVersion());
@@ -610,16 +773,17 @@ export async function runDoctor(options = {}) {
     allChecks.push(checkGitInstalled());
     allChecks.push(checkGitRepository());
     allChecks.push(checkConfigFile());
-    allChecks.push(checkConfigFormatMigration());
-    allChecks.push(await checkConfigValid(config));
+    allChecks.push(await checkConfigValid(config, configWithErrors));
     allChecks.push(await checkPackageManager(config));
     allChecks.push(await checkMainBranch(config));
     allChecks.push(await checkRemoteOrigin(config));
     allChecks.push(await checkRemoteMainBranch(config));
     allChecks.push(await checkWorkflowSync(config));
     allChecks.push(await checkPreCommitHook(config));
+    allChecks.push(await checkSecretScanning(config));
     allChecks.push(checkGitignoreStateFile());
     allChecks.push(checkValidationState());
+    allChecks.push(await checkHistoryHealth());
     // Collect suggestions from failed checks
     const suggestions = allChecks
         .filter(c => !c.passed && c.suggestion)
@@ -627,8 +791,9 @@ export async function runDoctor(options = {}) {
     const allPassed = allChecks.every(c => c.passed);
     const totalChecks = allChecks.length;
     const passedChecks = allChecks.filter(c => c.passed).length;
-    // In non-verbose mode, only show failing checks (or all if all pass for summary)
-    const checks = verbose ? allChecks : (allPassed ? allChecks : allChecks.filter(c => !c.passed));
+    // In non-verbose mode, show failing checks OR checks with recommendations
+    // In verbose mode, always show all checks
+    const checks = verbose ? allChecks : allChecks.filter(c => !c.passed || c.suggestion);
     return {
         allPassed,
         checks,
@@ -644,15 +809,30 @@ export async function runDoctor(options = {}) {
 export function doctorCommand(program) {
     program
         .command('doctor')
-        .description('Diagnose vibe-validate setup and environment')
-        .option('--json', 'Output results as JSON')
-        .option('--verbose', 'Show all checks including passing ones')
-        .action(async (options) => {
+        .description('Diagnose vibe-validate setup and environment (run after upgrading)')
+        .option('--yaml', 'Output YAML only (no human-friendly display)')
+        .action(async (options, command) => {
+        // Get verbose from global options (inherited from program)
+        const verbose = command.optsWithGlobals().verbose;
         try {
-            const result = await runDoctor({ verbose: options.verbose });
-            if (options.json) {
-                // JSON output for programmatic use
-                console.log(JSON.stringify(result, null, 2));
+            const result = await runDoctor({ verbose });
+            if (options.yaml) {
+                // YAML mode: Output structured result to stdout
+                // Small delay to ensure stderr is flushed
+                await new Promise(resolve => setTimeout(resolve, 10));
+                // RFC 4627 separator
+                process.stdout.write('---\n');
+                // Write pure YAML
+                process.stdout.write(stringifyYaml(result));
+                // CRITICAL: Wait for stdout to flush before exiting
+                await new Promise(resolve => {
+                    if (process.stdout.write('')) {
+                        resolve();
+                    }
+                    else {
+                        process.stdout.once('drain', resolve);
+                    }
+                });
             }
             else {
                 // Human-friendly output
@@ -668,7 +848,7 @@ export function doctorCommand(program) {
                     const icon = check.passed ? '✅' : '❌';
                     console.log(`${icon} ${check.name}`);
                     console.log(`   ${check.message}`);
-                    if (check.suggestion && !check.passed) {
+                    if (check.suggestion) {
                         console.log(`   💡 ${check.suggestion}`);
                     }
                     console.log('');
@@ -697,4 +877,127 @@ export function doctorCommand(program) {
         }
     });
 }
+/**
+ * Show verbose help with detailed documentation
+ */
+export function showDoctorVerboseHelp() {
+    console.log(`# doctor Command Reference
+
+> Diagnose vibe-validate setup and environment (run after upgrading)
+
+## Overview
+
+The \`doctor\` command performs comprehensive diagnostics of your vibe-validate setup and environment. It checks Node.js version, git repository health, configuration validity, package manager availability, and CI/CD integration status.
+
+## How It Works
+
+1. Checks Node.js version (20+)
+2. Verifies git repository exists
+3. Checks package manager availability
+4. Validates configuration file
+5. Checks pre-commit hook setup
+6. Verifies GitHub Actions workflow sync
+
+## Options
+
+- \`--yaml\` - Output YAML only (no human-friendly display)
+
+## Exit Codes
+
+- \`0\` - All critical checks passed
+- \`1\` - One or more critical checks failed
+
+## Examples
+
+\`\`\`bash
+# Run diagnostics
+vibe-validate doctor
+
+# YAML output only
+vibe-validate doctor --yaml
+\`\`\`
+
+## Common Workflows
+
+### After installing vibe-validate
+
+\`\`\`bash
+# Initialize configuration
+vibe-validate init
+
+# Verify setup
+vibe-validate doctor
+\`\`\`
+
+### After upgrading vibe-validate
+
+\`\`\`bash
+# Upgrade package
+npm install -D vibe-validate@latest
+
+# CRITICAL: Always run doctor after upgrade
+vibe-validate doctor
+
+# Fix any issues reported
+\`\`\`
+
+### Troubleshooting validation issues
+
+\`\`\`bash
+# Diagnose environment
+vibe-validate doctor
+
+# Fix reported issues
+
+# Retry validation
+vibe-validate validate
+\`\`\`
+
+## Checks Performed
+
+### Critical Checks (must pass)
+
+- **Node.js version**: >=20.0.0 required
+- **Git installed**: git command available
+- **Git repository**: Current directory is a git repo
+- **Configuration file**: vibe-validate.config.yaml exists
+- **Configuration valid**: No syntax or schema errors
+
+### Advisory Checks (warnings only)
+
+- **Package manager**: npm or pnpm available
+- **Pre-commit hook**: Husky pre-commit hook configured
+- **GitHub Actions workflow**: Workflow in sync with config
+- **Validation history**: Git notes health status
+
+## Error Recovery
+
+**If Node.js version check fails:**
+\`\`\`bash
+# Upgrade Node.js to 20+
+# Via nvm:
+nvm install 20
+nvm use 20
+
+# Or download from: https://nodejs.org/
+\`\`\`
+
+**If configuration check fails:**
+\`\`\`bash
+# Reinitialize with template
+vibe-validate init --force
+
+# Or manually fix YAML syntax errors
+\`\`\`
+
+**If workflow is out of sync:**
+\`\`\`bash
+# Regenerate workflow
+vibe-validate generate-workflow
+
+# Or reinitialize
+vibe-validate init --setup-workflow
+\`\`\`
+`);
+}
 //# sourceMappingURL=doctor.js.map