@vibe-validate/cli 0.11.0 → 0.12.1

package/dist/commands/pre-commit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pre-commit.d.ts","sourceRoot":"","sources":["../../src/commands/pre-commit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASzC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoFvD"}
+{"version":3,"file":"pre-commit.d.ts","sourceRoot":"","sources":["../../src/commands/pre-commit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASzC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8IvD;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CA4F/C"}

package/dist/commands/pre-commit.js

@@ -4,12 +4,12 @@
  * Runs branch sync check + validation before allowing commit.
  * This is the recommended workflow before committing code.
  */
-import { runValidation } from '@vibe-validate/core';
 import { checkBranchSync } from '@vibe-validate/git';
 import { getRemoteBranch } from '@vibe-validate/config';
 import { loadConfig } from '../utils/config-loader.js';
-import { createRunnerConfig } from '../utils/runner-adapter.js';
 import { detectContext } from '../utils/context-detector.js';
+import { runValidateWorkflow } from '../utils/validate-workflow.js';
+import { execSync } from 'child_process';
 import chalk from 'chalk';
 export function preCommitCommand(program) {
     program
@@ -52,15 +52,70 @@ export function preCommitCommand(program) {
             const context = detectContext();
             // Step 4: Verbose mode is ONLY enabled via explicit --verbose flag
             const verbose = options.verbose ?? false;
-            // Step 5: Run validation
+            // Step 5: Run secret scanning if enabled
+            const secretScanning = config.hooks?.preCommit?.secretScanning;
+            if (secretScanning?.enabled && secretScanning?.scanCommand) {
+                console.log(chalk.blue('\n🔒 Running secret scanning...'));
+                try {
+                    const result = execSync(secretScanning.scanCommand, {
+                        encoding: 'utf8',
+                        stdio: 'pipe',
+                    });
+                    // Show scan output if verbose
+                    if (verbose && result) {
+                        console.log(chalk.gray(result));
+                    }
+                    console.log(chalk.green('✅ No secrets detected'));
+                }
+                catch (error) {
+                    // Secret scanning failed (either tool missing or secrets found)
+                    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+                        // Tool not found
+                        const toolName = secretScanning.scanCommand.split(' ')[0];
+                        console.error(chalk.red('\n❌ Secret scanning tool not found'));
+                        console.error(chalk.yellow(`   Command: ${chalk.white(secretScanning.scanCommand)}`));
+                        console.error(chalk.yellow(`   Tool '${toolName}' is not installed or not in PATH`));
+                        console.error(chalk.blue('\n💡 Fix options:'));
+                        console.error(chalk.gray('   1. Install the tool (e.g., brew install gitleaks)'));
+                        console.error(chalk.gray('   2. Disable scanning: set hooks.preCommit.secretScanning.enabled=false'));
+                        process.exit(1);
+                    }
+                    else if (error && typeof error === 'object' && 'stderr' in error && 'stdout' in error) {
+                        // Tool ran but found secrets
+                        const stderr = 'stderr' in error && error.stderr ? String(error.stderr) : '';
+                        const stdout = 'stdout' in error && error.stdout ? String(error.stdout) : '';
+                        console.error(chalk.red('\n❌ Secret scanning detected potential secrets in staged files\n'));
+                        // Show scan output
+                        if (stdout) {
+                            console.error(stdout);
+                        }
+                        if (stderr) {
+                            console.error(stderr);
+                        }
+                        console.error(chalk.blue('\n💡 Fix options:'));
+                        console.error(chalk.gray('   1. Remove secrets from staged files'));
+                        console.error(chalk.gray('   2. Use .gitleaksignore to mark false positives (if using gitleaks)'));
+                        console.error(chalk.gray('   3. Disable scanning: set hooks.preCommit.secretScanning.enabled=false'));
+                        process.exit(1);
+                    }
+                    else {
+                        // Unknown error
+                        console.error(chalk.red('\n❌ Secret scanning failed with unknown error'));
+                        console.error(chalk.gray(String(error)));
+                        process.exit(1);
+                    }
+                }
+            }
+            // Step 6: Run validation with caching
             console.log(chalk.blue('\n🔄 Running validation...'));
-            const runnerConfig = createRunnerConfig(config, {
+            const result = await runValidateWorkflow(config, {
                 force: false, // Respect cache by default
                 verbose,
+                yaml: false, // Pre-commit uses human-readable output
+                check: false,
                 context,
             });
-            const result = await runValidation(runnerConfig);
-            // Step 6: Report results
+            // Step 7: Report results
             if (result.passed) {
                 console.log(chalk.green('\n✅ Pre-commit checks passed!'));
                 console.log(chalk.gray('   Safe to commit.'));
@@ -70,7 +125,7 @@ export function preCommitCommand(program) {
                 console.error(chalk.red('\n❌ Pre-commit checks failed'));
                 console.error(chalk.yellow('   Fix errors before committing.'));
                 // Show agent-friendly error details
-                console.error(chalk.blue('\n📋 Error details:'), chalk.white(runnerConfig.stateFilePath || '.vibe-validate-state.yaml'));
+                console.error(chalk.blue('\n📋 Error details:'), chalk.white('vibe-validate state'));
                 if (result.rerunCommand) {
                     console.error(chalk.blue('🔄 To retry:'), chalk.white(result.rerunCommand));
                 }
@@ -86,4 +141,100 @@ export function preCommitCommand(program) {
         }
     });
 }
+/**
+ * Show verbose help with detailed documentation
+ */
+export function showPreCommitVerboseHelp() {
+    console.log(`# pre-commit Command Reference
+
+> Run branch sync check + validation (recommended before commit)
+
+## Overview
+
+The \`pre-commit\` command runs a comprehensive pre-commit workflow to ensure your code is synced with the remote main branch and passes all validation checks before allowing a commit. This prevents pushing broken code or creating merge conflicts.
+
+## How It Works
+
+1. Runs sync-check (fails if branch behind origin/main)
+2. Runs validate (with caching)
+3. Reports git status (warns about unstaged files)
+
+## Options
+
+- \`--skip-sync\` - Skip branch sync check (not recommended)
+- \`-v, --verbose\` - Show detailed progress and output
+
+## Exit Codes
+
+- \`0\` - Sync OK and validation passed
+- \`1\` - Sync failed OR validation failed
+
+## Examples
+
+\`\`\`bash
+# Standard pre-commit workflow
+vibe-validate pre-commit
+
+# Skip sync check (not recommended)
+vibe-validate pre-commit --skip-sync
+\`\`\`
+
+## Common Workflows
+
+### Typical usage before committing
+
+\`\`\`bash
+# Make changes
+git add .
+
+# Run pre-commit checks
+vibe-validate pre-commit
+
+# If passed, commit
+git commit -m "Your message"
+\`\`\`
+
+### Integrate with Husky
+
+\`\`\`bash
+# Setup pre-commit hook
+npx husky init
+echo "npx vibe-validate pre-commit" > .husky/pre-commit
+
+# Now runs automatically before every commit
+git commit -m "Your message"
+\`\`\`
+
+## Error Recovery
+
+### If sync check fails
+
+**Branch is behind origin/main:**
+\`\`\`bash
+# Fetch latest changes
+git fetch origin
+
+# Merge origin/main
+git merge origin/main
+
+# Resolve conflicts if any
+
+# Retry pre-commit
+vibe-validate pre-commit
+\`\`\`
+
+### If validation fails
+
+**Fix errors shown in output:**
+\`\`\`bash
+# View detailed error info
+vibe-validate state
+
+# Fix the errors
+
+# Retry pre-commit
+vibe-validate pre-commit
+\`\`\`
+`);
+}
 //# sourceMappingURL=pre-commit.js.map

package/dist/commands/pre-commit.js.map

@@ -1 +1 @@
-{"version":3,"file":"pre-commit.js","sourceRoot":"","sources":["../../src/commands/pre-commit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pre-commit.js","sourceRoot":"","sources":["../../src/commands/pre-commit.ts"],"names":[],"mappings":"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"}

package/dist/commands/state.d.ts

@@ -1,8 +1,12 @@
 /**
  * State Command
  *
- * Display current validation state from cache file.
+ * Display current validation state from git notes cache.
  */
 import type { Command } from 'commander';
 export declare function stateCommand(program: Command): void;
+/**
+ * Show verbose help with detailed documentation
+ */
+export declare function showStateVerboseHelp(): void;
 //# sourceMappingURL=state.d.ts.map

package/dist/commands/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/commands/state.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAczC,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwCnD"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/commands/state.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOzC,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4FnD;AAgED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAyH3C"}

package/dist/commands/state.js

@@ -1,46 +1,89 @@
 /**
  * State Command
  *
- * Display current validation state from cache file.
+ * Display current validation state from git notes cache.
  */
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
 import chalk from 'chalk';
-import { parse as parseYaml } from 'yaml';
+import { stringify as stringifyYaml } from 'yaml';
+import { getGitTreeHash } from '@vibe-validate/git';
+import { readHistoryNote, hasHistoryForTree } from '@vibe-validate/history';
 export function stateCommand(program) {
     program
         .command('state')
-        .description('Show current validation state')
+        .description('Show current validation state from git notes')
         .option('-v, --verbose', 'Show full error output without truncation')
-        .option('--file <path>', 'State file path', '.vibe-validate-state.yaml')
         .action(async (options) => {
         try {
-            const cwd = process.cwd();
-            const statePath = join(cwd, options.file);
-            // Check if state file exists
-            if (!existsSync(statePath)) {
-                console.log('exists: false');
+            // Get current tree hash
+            const treeHash = await getGitTreeHash();
+            // Check if history exists for current tree
+            const hasHistory = await hasHistoryForTree(treeHash);
+            if (!hasHistory) {
+                // Always show tree hash, even when no history exists (helpful for debugging)
+                const noStateOutput = {
+                    exists: false,
+                    treeHash: treeHash,
+                };
+                console.log(stringifyYaml(noStateOutput));
                 if (options.verbose) {
-                    console.log(chalk.gray('\nℹ️  No validation state found'));
+                    console.log(chalk.gray('ℹ️  No validation state found for current worktree'));
                     console.log(chalk.gray('   Run: vibe-validate validate'));
                 }
                 process.exit(0);
             }
-            // Read and parse state file
-            const stateContent = readFileSync(statePath, 'utf-8');
-            const state = parseYaml(stateContent);
+            // Read history note
+            const historyNote = await readHistoryNote(treeHash);
+            if (!historyNote || historyNote.runs.length === 0) {
+                // Always show tree hash, even when no runs exist
+                const noStateOutput = {
+                    exists: false,
+                    treeHash: treeHash,
+                };
+                console.log(stringifyYaml(noStateOutput));
+                if (options.verbose) {
+                    console.log(chalk.gray('ℹ️  No validation runs found for current worktree'));
+                }
+                process.exit(0);
+            }
+            // Get most recent run
+            const mostRecentRun = historyNote.runs[historyNote.runs.length - 1];
+            const result = mostRecentRun.result;
+            // Convert to state format (compatible with old format)
+            const state = {
+                passed: result.passed,
+                timestamp: result.timestamp,
+                treeHash: result.treeHash,
+                failedStep: result.failedStep,
+                failedStepOutput: result.failedStepOutput,
+                phases: result.phases,
+                rerunCommand: result.rerunCommand,
+            };
             // Output YAML format (always)
+            const yamlContent = stringifyYaml(state);
             if (options.verbose) {
                 // Verbose mode: show full output with colors and explanations
-                displayVerboseState(state, stateContent);
+                displayVerboseState(state, yamlContent, mostRecentRun.branch);
             }
             else {
                 // Minimal mode: just the YAML content
-                console.log(stateContent);
+                console.log(yamlContent);
             }
             process.exit(0);
         }
         catch (error) {
+            if (error instanceof Error && error.message.includes('not a git repository')) {
+                // Not in git repo - show structured output
+                const noGitOutput = {
+                    exists: false,
+                    error: 'Not in git repository',
+                };
+                console.log(stringifyYaml(noGitOutput));
+                if (options.verbose) {
+                    console.log(chalk.gray('ℹ️  Not in a git repository'));
+                    console.log(chalk.gray('   Validation history requires git'));
+                }
+                process.exit(0);
+            }
             console.error(chalk.red('❌ Failed to read validation state:'), error);
             process.exit(1);
         }
@@ -49,7 +92,7 @@ export function stateCommand(program) {
 /**
  * Display validation state in verbose format with colors and explanations
  */
-function displayVerboseState(state, yamlContent) {
+function displayVerboseState(state, yamlContent, branch) {
     // First show the raw YAML
     console.log(yamlContent);
     // Then add colored summary and explanations
@@ -68,6 +111,8 @@ function displayVerboseState(state, yamlContent) {
     console.log(chalk.gray(`⏰ Last Run: ${timestamp.toLocaleString()}`));
     // Tree hash
     console.log(chalk.gray(`🌳 Git Tree Hash: ${state.treeHash.substring(0, 12)}...`));
+    // Branch
+    console.log(chalk.gray(`🌿 Branch: ${branch}`));
     // Failed step details (if any)
     if (!state.passed && state.failedStep) {
         console.log(chalk.red(`\n❌ Failed Step: ${state.failedStep}`));
@@ -83,9 +128,138 @@ function displayVerboseState(state, yamlContent) {
         console.log(chalk.gray('  1. Fix the failed step'));
         console.log(chalk.gray('  2. Re-run: vibe-validate validate'));
         console.log(chalk.gray('  3. Or force re-validation: vibe-validate validate --force'));
+        // Suggest reporting extractor issues
+        console.log(chalk.gray('\n💡 Error output unclear or missing details?'));
+        console.log(chalk.gray('   Help improve extraction: https://github.com/jdutton/vibe-validate/issues/new?template=extractor-improvement.yml'));
     }
     else {
         console.log(chalk.green('\n✅ Validation passed! Safe to commit.'));
     }
+    console.log(chalk.gray('\n💡 Tip: View full history with: vibe-validate history list'));
+}
+/**
+ * Show verbose help with detailed documentation
+ */
+export function showStateVerboseHelp() {
+    console.log(`# state Command Reference
+
+> View current validation state
+
+## Overview
+
+The \`state\` command shows the current validation status without re-running validation. It reads the cached validation result from git notes.
+
+## How It Works
+
+1. **Reads validation state** from git notes (if exists)
+2. **Shows pass/fail status**
+3. **Shows git tree hash** (cache key)
+4. **Shows timestamp** of last validation
+5. **Shows error summary** (if failed)
+
+## Options
+
+- \`-v, --verbose\` - Show full error output and details
+- \`-y, --yaml\` - Output as YAML (machine-readable)
+
+## Exit Codes
+
+- \`0\` - State file found and read successfully
+- \`1\` - State file not found or invalid
+
+## Examples
+
+\`\`\`bash
+# Check current state
+vibe-validate state
+
+# See full error details
+vibe-validate state --verbose
+
+# Machine-readable output
+vibe-validate state --yaml
+\`\`\`
+
+## Output Formats
+
+### Standard Output
+\`\`\`
+✅ Validation Status: PASSED
+📅 Last validated: 2025-10-23T14:30:00Z
+🔑 Tree hash: 2b62c71a3f
+⏱️  Duration: 62.4s
+\`\`\`
+
+### Verbose Output
+Includes:
+- Full error messages
+- Stack traces (if available)
+- Failed step details
+- Recommendations for fixing
+
+### YAML Output
+\`\`\`yaml
+exists: true
+passed: true
+timestamp: 2025-10-23T14:30:00Z
+treeHash: 2b62c71a3f...
+duration: 62.4
+\`\`\`
+
+## When to Use
+
+**Use \`state\` when you want to:**
+- Check validation status without re-running
+- Debug why validation failed
+- See what tree hash is cached
+- Verify validation result before committing
+- Get machine-readable validation status
+
+**Don't use \`state\` when:**
+- You want to force fresh validation (use \`validate --force\`)
+- You want to run validation if cache is stale (use \`validate\`)
+
+## Integration with Other Commands
+
+- \`vibe-validate validate\` - Run validation (creates state)
+- \`vibe-validate validate --check\` - Same as \`state\` but with different exit codes
+- \`vibe-validate history list\` - View validation history timeline
+- \`vibe-validate history show <hash>\` - View state for specific tree hash
+
+## Common Workflows
+
+### Debug validation failure
+\`\`\`bash
+# 1. Run validation
+vibe-validate validate
+
+# 2. If fails, see details
+vibe-validate state --verbose
+
+# 3. Fix errors
+
+# 4. Re-run
+vibe-validate validate
+\`\`\`
+
+### AI agent workflow
+\`\`\`bash
+# Run validation
+vibe-validate validate --yaml > /dev/null 2>&1
+
+# Get structured result
+vibe-validate state --yaml
+\`\`\`
+
+### Pre-commit check
+\`\`\`bash
+# Check if validation already passed
+if vibe-validate state --yaml | grep -q "passed: true"; then
+  echo "Validation already passed, skipping"
+else
+  vibe-validate validate
+fi
+\`\`\`
+`);
 }
 //# sourceMappingURL=state.js.map

package/dist/commands/state.js.map

@@ -1 +1 @@
-{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/commands/state.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/commands/state.ts"],"names":[],"mappings":"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"}

package/dist/commands/sync-check.d.ts

@@ -5,4 +5,8 @@
  */
 import type { Command } from 'commander';
 export declare function syncCheckCommand(program: Command): void;
+/**
+ * Show verbose help with detailed documentation
+ */
+export declare function showSyncCheckVerboseHelp(): void;
 //# sourceMappingURL=sync-check.d.ts.map

package/dist/commands/sync-check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-check.d.ts","sourceRoot":"","sources":["../../src/commands/sync-check.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOzC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8CvD"}
+{"version":3,"file":"sync-check.d.ts","sourceRoot":"","sources":["../../src/commands/sync-check.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOzC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA+DvD;AAmCD;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CA6E/C"}

package/dist/commands/sync-check.js

@@ -32,9 +32,24 @@ export function syncCheckCommand(program) {
             const result = await checkBranchSync({
                 remoteBranch,
             });
-            // Output based on quiet flag
+            // Output based on yaml flag
             if (options.yaml) {
-                console.log(stringifyYaml(result));
+                // 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 format
@@ -80,4 +95,85 @@ function displayHumanSyncCheck(result, mainBranch) {
     }
     console.log(chalk.gray('─'.repeat(50)));
 }
+/**
+ * Show verbose help with detailed documentation
+ */
+export function showSyncCheckVerboseHelp() {
+    console.log(`# sync-check Command Reference
+
+> Check if branch is behind remote main branch
+
+## Overview
+
+The \`sync-check\` command verifies that your current branch is up to date with the remote main branch (usually origin/main). It compares local and remote commit histories without making any changes to your repository.
+
+## How It Works
+
+1. Checks if current branch has a remote tracking branch
+2. Compares local and remote commit histories
+3. Reports sync status (up to date, behind, or no remote)
+
+## Options
+
+- \`--main-branch <branch>\` - Main branch name (overrides config, default: main)
+- \`--remote-origin <remote>\` - Remote origin name (overrides config, default: origin)
+- \`--yaml\` - Output YAML only (no human-friendly display)
+
+## Exit Codes
+
+- \`0\` - Up to date or no remote tracking
+- \`1\` - Branch is behind (needs merge)
+- \`2\` - Git command failed
+
+## Examples
+
+\`\`\`bash
+# Check sync with default main branch
+vibe-validate sync-check
+
+# Check sync with custom main branch
+vibe-validate sync-check --main-branch develop
+
+# YAML output only
+vibe-validate sync-check --yaml
+\`\`\`
+
+## Common Workflows
+
+### Before starting work
+
+\`\`\`bash
+# Check if your branch is behind
+vibe-validate sync-check
+
+# If behind, merge latest
+git merge origin/main
+\`\`\`
+
+### In CI/CD pipeline
+
+\`\`\`bash
+# Check sync as YAML for parsing
+vibe-validate sync-check --yaml
+\`\`\`
+
+## Error Recovery
+
+### If branch is behind (exit 1)
+
+**Merge the remote branch:**
+\`\`\`bash
+# Fetch latest changes
+git fetch origin
+
+# Merge origin/main (or git rebase origin/main)
+git merge origin/main
+
+# Resolve conflicts if any
+
+# Retry sync check
+vibe-validate sync-check
+\`\`\`
+`);
+}
 //# sourceMappingURL=sync-check.js.map