@vibe-validate/cli 0.10.3 → 0.12.0

package/dist/commands/sync-check.js

@@ -6,6 +6,7 @@
 import { checkBranchSync } from '@vibe-validate/git';
 import { getRemoteBranch, getMainBranch } from '@vibe-validate/config';
 import { loadConfig } from '../utils/config-loader.js';
+import { stringify as stringifyYaml } from 'yaml';
 import chalk from 'chalk';
 export function syncCheckCommand(program) {
     program
@@ -13,7 +14,7 @@ export function syncCheckCommand(program) {
         .description('Check if branch is behind remote main branch')
         .option('--main-branch <branch>', 'Main branch name (overrides config)')
         .option('--remote-origin <remote>', 'Remote origin name (overrides config)')
-        .option('--format <format>', 'Output format (human|yaml|json)', 'human')
+        .option('--yaml', 'Output YAML only (no human-friendly display)')
         .action(async (options) => {
         try {
             // Load config to get defaults
@@ -31,19 +32,24 @@ export function syncCheckCommand(program) {
             const result = await checkBranchSync({
                 remoteBranch,
             });
-            // Output based on format
-            if (options.format === 'json') {
-                console.log(JSON.stringify(result, null, 2));
-            }
-            else if (options.format === 'yaml') {
-                console.log(`hasRemote: ${result.hasRemote}`);
-                console.log(`isUpToDate: ${result.isUpToDate}`);
-                if (result.currentBranch) {
-                    console.log(`currentBranch: ${result.currentBranch}`);
-                }
-                if (result.behindBy !== undefined) {
-                    console.log(`behindBy: ${result.behindBy}`);
-                }
+            // Output based on yaml flag
+            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 format
@@ -89,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

package/dist/commands/sync-check.js.map

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

package/dist/commands/validate.d.ts

@@ -1,8 +1,12 @@
 /**
  * Validate Command
  *
- * Runs validation phases with git tree hash caching.
+ * Runs validation phases with git tree hash caching and history recording.
  */
 import type { Command } from 'commander';
 export declare function validateCommand(program: Command): void;
+/**
+ * Show verbose help with detailed documentation
+ */
+export declare function showValidateVerboseHelp(): void;
 //# sourceMappingURL=validate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOzC,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyDtD"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOzC,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA6CtD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAiK9C"}

package/dist/commands/validate.js

@@ -1,12 +1,11 @@
 /**
  * Validate Command
  *
- * Runs validation phases with git tree hash caching.
+ * Runs validation phases with git tree hash caching and history recording.
  */
-import { runValidation } from '@vibe-validate/core';
 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 chalk from 'chalk';
 export function validateCommand(program) {
     program
@@ -14,6 +13,7 @@ export function validateCommand(program) {
         .description('Run validation with git tree hash caching')
         .option('-f, --force', 'Force validation even if already passed')
         .option('-v, --verbose', 'Show detailed progress and output')
+        .option('-y, --yaml', 'Output validation result as YAML to stdout')
         .option('-c, --check', 'Check if validation has already passed (do not run)')
         .action(async (options) => {
         try {
@@ -23,41 +23,197 @@ export function validateCommand(program) {
                 console.error(chalk.red('❌ No configuration found'));
                 process.exit(1);
             }
-            // If --check flag is used, only check validation state without running
-            if (options.check) {
-                const { checkValidationStatus } = await import('../utils/check-validation.js');
-                await checkValidationStatus(config);
-                return; // Exit handled by checkValidationStatus
-            }
             // Detect context (Claude Code, CI, etc.)
             const context = detectContext();
-            // Verbose mode is ONLY enabled via explicit --verbose flag
-            const verbose = options.verbose ?? false;
-            // Create runner config
-            const runnerConfig = createRunnerConfig(config, {
+            // Run shared validation workflow
+            const result = await runValidateWorkflow(config, {
                 force: options.force,
-                verbose,
+                verbose: options.verbose,
+                yaml: options.yaml,
+                check: options.check,
                 context,
             });
-            // Run validation
-            const result = await runValidation(runnerConfig);
-            // If validation failed, show agent-friendly error details
-            if (!result.passed) {
-                console.error(chalk.blue('\n📋 Error details:'), chalk.white(runnerConfig.stateFilePath || '.vibe-validate-state.yaml'));
-                if (result.rerunCommand) {
-                    console.error(chalk.blue('🔄 To retry:'), chalk.white(result.rerunCommand));
-                }
-                if (result.fullLogFile) {
-                    console.error(chalk.blue('📄 Full log:'), chalk.gray(result.fullLogFile));
-                }
+            // Only call process.exit for non-cached results
+            // Cache hits return early without calling process.exit (to support testing)
+            const resultWithCache = result;
+            if (!resultWithCache._fromCache) {
+                process.exit(result.passed ? 0 : 1);
             }
-            // Exit with appropriate code
-            process.exit(result.passed ? 0 : 1);
+            // For cache hits, return normally and let Commander exit with code 0
         }
         catch (error) {
-            console.error(chalk.red('❌ Validation failed with error:'), error);
+            // Re-throw process.exit errors (for testing)
+            if (error instanceof Error && error.message.startsWith('process.exit')) {
+                throw error;
+            }
+            // Error already logged by runValidateWorkflow
             process.exit(1);
         }
     });
 }
+/**
+ * Show verbose help with detailed documentation
+ */
+export function showValidateVerboseHelp() {
+    console.log(`# validate Command Reference
+
+> Run validation with git tree hash caching
+
+## Overview
+
+The \`validate\` command is the core of vibe-validate. It executes your validation pipeline (linting, testing, type-checking, etc.) and uses git tree hashes for intelligent caching.
+
+## How It Works
+
+1. **Calculates git tree hash** of working directory (includes all tracked and untracked files)
+2. **Checks if hash matches cached state** (from previous run)
+3. **If match:** Exits immediately with cached result (~288ms)
+4. **If no match:** Runs validation pipeline (~60-90s depending on your project)
+5. **Caches result** in git notes for next run
+6. **Records history** for analysis via \`vibe-validate history\`
+
+## Options
+
+- \`-f, --force\` - Force validation even if already passed (bypasses cache)
+- \`-v, --verbose\` - Show detailed progress and output
+- \`-y, --yaml\` - Output validation result as YAML to stdout (LLM-friendly)
+- \`-c, --check\` - Check if validation has already passed without running
+
+## Exit Codes
+
+- \`0\` - Validation passed (or cached pass)
+- \`1\` - Validation failed
+- \`2\` - Configuration error
+
+## Examples
+
+\`\`\`bash
+# Standard usage (uses cache if available)
+vibe-validate validate
+
+# Force re-validation (bypass cache)
+vibe-validate validate --force
+
+# Check status without running
+vibe-validate validate --check
+
+# YAML output for AI agents
+vibe-validate validate --yaml
+
+# Verbose output with YAML result
+vibe-validate validate --verbose --yaml
+\`\`\`
+
+## Caching Behavior
+
+### Cache Key
+- Based on **git tree hash** (not commit SHA)
+- Includes **all files** (tracked + untracked)
+- Deterministic: same content = same hash
+
+### Cache Hit
+- Validation result found for current tree hash
+- Exits in ~288ms
+- Shows: "✓ Validation already passed for tree <hash>"
+
+### Cache Miss
+- No result found for current tree hash
+- Runs full validation pipeline
+- Typical duration: 60-90s
+
+### Cache Invalidation
+- ANY file change (content or path)
+- Adding/removing files
+- Modifying .gitignore
+
+## YAML Output Mode
+
+When using \`--yaml\`, output is split:
+
+**stderr** (human-readable progress):
+\`\`\`
+phase_start: Pre-Qualification
+🔍 Running Pre-Qualification...
+✅ TypeScript - PASSED
+phase_complete: Pre-Qualification (passed)
+\`\`\`
+
+**stdout** (machine-parseable YAML):
+\`\`\`yaml
+---
+passed: true
+timestamp: 2025-10-23T14:30:00Z
+treeHash: 2b62c71a3f...
+duration: 62.4
+\`\`\`
+
+This design:
+- ✅ Humans see progress in real-time (stderr)
+- ✅ LLMs parse structured result (stdout)
+- ✅ 90% smaller than verbose logs
+
+## Integration with Other Commands
+
+- \`vibe-validate state\` - View cached result
+- \`vibe-validate state --verbose\` - See full error details
+- \`vibe-validate history list\` - View validation timeline
+- \`vibe-validate pre-commit\` - Runs sync-check + validate
+
+## Common Workflows
+
+### Development workflow
+\`\`\`bash
+# Make changes
+# ...
+
+# Run validation (uses cache if no changes)
+vibe-validate validate
+
+# If fails, fix errors and retry
+vibe-validate validate
+\`\`\`
+
+### Debugging workflow
+\`\`\`bash
+# Why did validation fail?
+vibe-validate state --verbose
+
+# View history
+vibe-validate history list
+
+# Force fresh validation
+vibe-validate validate --force
+\`\`\`
+
+### AI agent workflow
+\`\`\`bash
+# Run validation
+vibe-validate validate --yaml 2>&1 | sed -n '/^---$/,$p' | tail -n +2
+
+# Or use state command
+vibe-validate validate
+vibe-validate state --yaml
+\`\`\`
+
+## Performance
+
+| Scenario | Duration | Notes |
+|----------|----------|-------|
+| Cache hit | ~288ms | Cached result found |
+| Cache miss | ~60-90s | Full validation run |
+| Force flag | ~60-90s | Cache bypassed |
+
+## Files Created/Modified
+
+- \`refs/notes/vibe-validate/runs\` - Validation history (git notes, auto-created)
+
+## Error Recovery
+
+If validation fails:
+1. Check error details: \`vibe-validate state --verbose\`
+2. Fix errors shown in output
+3. Re-run: \`vibe-validate validate\`
+4. Verify: \`vibe-validate state\`
+`);
+}
 //# sourceMappingURL=validate.js.map

package/dist/commands/validate.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO;SACJ,OAAO,CAAC,UAAU,CAAC;SACnB,WAAW,CAAC,2CAA2C,CAAC;SACxD,MAAM,CAAC,aAAa,EAAE,yCAAyC,CAAC;SAChE,MAAM,CAAC,eAAe,EAAE,mCAAmC,CAAC;SAC5D,MAAM,CAAC,aAAa,EAAE,qDAAqD,CAAC;SAC5E,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACxB,IAAI,CAAC;YACH,qBAAqB;YACrB,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;YAClC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC,CAAC;gBACrD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YAED,uEAAuE;YACvE,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;gBAClB,MAAM,EAAE,qBAAqB,EAAE,GAAG,MAAM,MAAM,CAAC,8BAA8B,CAAC,CAAC;gBAC/E,MAAM,qBAAqB,CAAC,MAAM,CAAC,CAAC;gBACpC,OAAO,CAAC,wCAAwC;YAClD,CAAC;YAED,yCAAyC;YACzC,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;YAEhC,2DAA2D;YAC3D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,KAAK,CAAC;YAEzC,uBAAuB;YACvB,MAAM,YAAY,GAAG,kBAAkB,CAAC,MAAM,EAAE;gBAC9C,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,OAAO;gBACP,OAAO;aACR,CAAC,CAAC;YAEH,iBAAiB;YACjB,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,YAAY,CAAC,CAAC;YAEjD,0DAA0D;YAC1D,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;gBACnB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,aAAa,IAAI,2BAA2B,CAAC,CAAC,CAAC;gBACzH,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;oBACxB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;gBAC9E,CAAC;gBACD,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;oBACvB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC;gBAC5E,CAAC;YACH,CAAC;YAED,6BAA6B;YAC7B,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,iCAAiC,CAAC,EAAE,KAAK,CAAC,CAAC;YACnE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO;SACJ,OAAO,CAAC,UAAU,CAAC;SACnB,WAAW,CAAC,2CAA2C,CAAC;SACxD,MAAM,CAAC,aAAa,EAAE,yCAAyC,CAAC;SAChE,MAAM,CAAC,eAAe,EAAE,mCAAmC,CAAC;SAC5D,MAAM,CAAC,YAAY,EAAE,4CAA4C,CAAC;SAClE,MAAM,CAAC,aAAa,EAAE,qDAAqD,CAAC;SAC5E,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACxB,IAAI,CAAC;YACH,qBAAqB;YACrB,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;YAClC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC,CAAC;gBACrD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YAED,yCAAyC;YACzC,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;YAEhC,iCAAiC;YACjC,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,MAAM,EAAE;gBAC/C,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,OAAO;aACR,CAAC,CAAC;YAEH,gDAAgD;YAChD,4EAA4E;YAC5E,MAAM,eAAe,GAAG,MAAqD,CAAC;YAC9E,IAAI,CAAC,eAAe,CAAC,UAAU,EAAE,CAAC;gBAChC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACtC,CAAC;YACD,qEAAqE;QACvE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,6CAA6C;YAC7C,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;gBACvE,MAAM,KAAK,CAAC;YACd,CAAC;YACD,8CAA8C;YAC9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+Jb,CAAC,CAAC;AACH,CAAC"}

package/dist/commands/watch-pr.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from 'commander';
+/**
+ * Register the watch-pr command
+ */
+export declare function registerWatchPRCommand(program: Command): void;
+/**
+ * Show verbose help with detailed documentation
+ */
+export declare function showWatchPRVerboseHelp(): void;
+//# sourceMappingURL=watch-pr.d.ts.map

package/dist/commands/watch-pr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-pr.d.ts","sourceRoot":"","sources":["../../src/commands/watch-pr.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8CzC;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgC7D;AAgUD;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CA4I7C"}