@vibe-validate/cli 0.17.0-rc4 → 0.17.1-rc.1

package/README.md

@@ -9,6 +9,7 @@ The `@vibe-validate/cli` package provides a command-line interface for running v
 
 ## Features
 
+- **🛡️ Automatic work protection** - Invisible safety net for all uncommitted changes
 - **🚀 Git tree hash-based caching** - 312x faster validation on unchanged code
 - **🤖 Agent-friendly output** - Minimal token waste, structured error reporting
 - **⚡ Parallel phase execution** - Run validation steps concurrently
@@ -487,6 +488,56 @@ phases:
           totalErrors: 1
 ```
 
+## Work Protection & Recovery
+
+vibe-validate automatically protects your uncommitted work every time it calculates a git tree hash for caching.
+
+### How It Works
+
+When you run validation commands, vibe-validate:
+1. Creates a temporary git index
+2. Stages all your files (tracked + untracked) in that temp index
+3. Runs `git write-tree` to create git objects for everything
+4. Cleans up the temp index (your real index is untouched)
+
+**Result**: All your files are now in `.git/objects/` as git blobs, even if they're unstaged or untracked.
+
+### Recovery Commands
+
+```bash
+# List validation history (shows tree hashes with timestamps)
+vv history list
+
+# Show files in a specific tree hash
+git ls-tree <tree-hash>
+
+# View a specific file from any validation point
+git cat-file -p <tree-hash>:path/to/file.ts
+
+# Recover a file
+git cat-file -p <tree-hash>:src/deleted-work.ts > src/deleted-work.ts
+
+# Recover entire directory
+git checkout <tree-hash> -- src/
+```
+
+### Use Cases
+
+- **Accidental git restore**: Recover unstaged changes after accidental revert
+- **Bad refactoring**: Revert to code state before risky changes
+- **Editor crashes**: Restore in-progress work from last validation
+- **Experimental changes**: Compare current code vs previous validation snapshots
+- **Team debugging**: Share exact code state via tree hash
+
+### When Protection Happens
+
+Your work is automatically captured during:
+- `vv validate` - Full validation
+- `vv pre-commit` - Pre-commit workflow
+- `vv run <command>` - Individual command execution (cached)
+
+See [Work Protection Guide](../../docs/work-protection.md) for detailed examples.
+
 ## Integration with Pre-Commit Hooks
 
 **Recommended setup using [husky](https://typicode.github.io/husky/):**

package/config-templates/README.md

@@ -322,8 +322,8 @@ All templates in this directory are:
 ## Related Documentation
 
 - [Getting Started Guide](../docs/getting-started.md)
-- [Configuration Reference](../docs/configuration-reference.md)
-- [CLI Reference](../docs/cli-reference.md)
+- [Configuration Reference](../docs/skill/resources/configuration-reference.md)
+- [CLI Reference](../docs/skill/resources/cli-reference.md)
 
 ---
 

package/config-templates/minimal.yaml

@@ -25,17 +25,28 @@ hooks:
   preCommit:
     enabled: true
     # Secret scanning prevents accidental credential commits
-    # Runs before validation to catch secrets in staged files
     secretScanning:
       enabled: true
-      # Gitleaks is recommended for speed and comprehensive detection (160+ secret types)
-      # Install: brew install gitleaks (macOS) | https://github.com/gitleaks/gitleaks#installation
-      scanCommand: "gitleaks protect --staged --verbose"
-      # Alternative tools:
-      # - detect-secrets: scanCommand: "detect-secrets scan --staged"
-      # - semgrep: scanCommand: "semgrep scan --config auto"
+      # Autodetect mode (recommended): Omit scanCommand to auto-detect tools
+      # Automatically runs tools based on config files present:
+      #   - .gitleaks.toml or .gitleaksignore → runs gitleaks
+      #   - .secretlintrc.json → runs secretlint (via npx)
+      #   - Both files present → runs both tools (defense-in-depth)
       #
-      # False positives: Create .gitleaksignore file with fingerprints
+      # Setup options:
+      # 1. gitleaks (recommended - fast, 160+ secret types):
+      #    macOS: brew install gitleaks
+      #    Linux/Windows: https://github.com/gitleaks/gitleaks#installation
+      #    Create .gitleaksignore for false positives
+      #
+      # 2. secretlint (npm-based, always available):
+      #    npm install --save-dev @secretlint/secretlint-rule-preset-recommend secretlint
+      #    Create .secretlintrc.json with: {"rules": [{"id": "@secretlint/secretlint-rule-preset-recommend"}]}
+      #    Create .secretlintignore for false positives
+      #
+      # 3. Both (defense-in-depth): Create both config files
+      #
+      # To use explicit command instead: scanCommand: "gitleaks protect --staged --verbose"
       # To disable: set enabled: false
 
 # Validation configuration

package/config-templates/typescript-library.yaml

@@ -25,17 +25,28 @@ hooks:
   preCommit:
     enabled: true
     # Secret scanning prevents accidental credential commits
-    # Runs before validation to catch secrets in staged files
     secretScanning:
       enabled: true
-      # Gitleaks is recommended for speed and comprehensive detection (160+ secret types)
-      # Install: brew install gitleaks (macOS) | https://github.com/gitleaks/gitleaks#installation
-      scanCommand: "gitleaks protect --staged --verbose"
-      # Alternative tools:
-      # - detect-secrets: scanCommand: "detect-secrets scan --staged"
-      # - semgrep: scanCommand: "semgrep scan --config auto"
+      # Autodetect mode (recommended): Omit scanCommand to auto-detect tools
+      # Automatically runs tools based on config files present:
+      #   - .gitleaks.toml or .gitleaksignore → runs gitleaks
+      #   - .secretlintrc.json → runs secretlint (via npx)
+      #   - Both files present → runs both tools (defense-in-depth)
       #
-      # False positives: Create .gitleaksignore file with fingerprints
+      # Setup options:
+      # 1. gitleaks (recommended - fast, 160+ secret types):
+      #    macOS: brew install gitleaks
+      #    Linux/Windows: https://github.com/gitleaks/gitleaks#installation
+      #    Create .gitleaksignore for false positives
+      #
+      # 2. secretlint (npm-based, always available):
+      #    npm install --save-dev @secretlint/secretlint-rule-preset-recommend secretlint
+      #    Create .secretlintrc.json with: {"rules": [{"id": "@secretlint/secretlint-rule-preset-recommend"}]}
+      #    Create .secretlintignore for false positives
+      #
+      # 3. Both (defense-in-depth): Create both config files
+      #
+      # To use explicit command instead: scanCommand: "gitleaks protect --staged --verbose"
       # To disable: set enabled: false
 
 # Validation configuration

package/config-templates/typescript-nodejs.yaml

@@ -26,17 +26,28 @@ hooks:
   preCommit:
     enabled: true
     # Secret scanning prevents accidental credential commits
-    # Runs before validation to catch secrets in staged files
     secretScanning:
       enabled: true
-      # Gitleaks is recommended for speed and comprehensive detection (160+ secret types)
-      # Install: brew install gitleaks (macOS) | https://github.com/gitleaks/gitleaks#installation
-      scanCommand: "gitleaks protect --staged --verbose"
-      # Alternative tools:
-      # - detect-secrets: scanCommand: "detect-secrets scan --staged"
-      # - semgrep: scanCommand: "semgrep scan --config auto"
+      # Autodetect mode (recommended): Omit scanCommand to auto-detect tools
+      # Automatically runs tools based on config files present:
+      #   - .gitleaks.toml or .gitleaksignore → runs gitleaks
+      #   - .secretlintrc.json → runs secretlint (via npx)
+      #   - Both files present → runs both tools (defense-in-depth)
       #
-      # False positives: Create .gitleaksignore file with fingerprints
+      # Setup options:
+      # 1. gitleaks (recommended - fast, 160+ secret types):
+      #    macOS: brew install gitleaks
+      #    Linux/Windows: https://github.com/gitleaks/gitleaks#installation
+      #    Create .gitleaksignore for false positives
+      #
+      # 2. secretlint (npm-based, always available):
+      #    npm install --save-dev @secretlint/secretlint-rule-preset-recommend secretlint
+      #    Create .secretlintrc.json with: {"rules": [{"id": "@secretlint/secretlint-rule-preset-recommend"}]}
+      #    Create .secretlintignore for false positives
+      #
+      # 3. Both (defense-in-depth): Create both config files
+      #
+      # To use explicit command instead: scanCommand: "gitleaks protect --staged --verbose"
       # To disable: set enabled: false
 
 # Validation configuration

package/config-templates/typescript-react.yaml

@@ -26,17 +26,28 @@ hooks:
   preCommit:
     enabled: true
     # Secret scanning prevents accidental credential commits
-    # Runs before validation to catch secrets in staged files
     secretScanning:
       enabled: true
-      # Gitleaks is recommended for speed and comprehensive detection (160+ secret types)
-      # Install: brew install gitleaks (macOS) | https://github.com/gitleaks/gitleaks#installation
-      scanCommand: "gitleaks protect --staged --verbose"
-      # Alternative tools:
-      # - detect-secrets: scanCommand: "detect-secrets scan --staged"
-      # - semgrep: scanCommand: "semgrep scan --config auto"
+      # Autodetect mode (recommended): Omit scanCommand to auto-detect tools
+      # Automatically runs tools based on config files present:
+      #   - .gitleaks.toml or .gitleaksignore → runs gitleaks
+      #   - .secretlintrc.json → runs secretlint (via npx)
+      #   - Both files present → runs both tools (defense-in-depth)
       #
-      # False positives: Create .gitleaksignore file with fingerprints
+      # Setup options:
+      # 1. gitleaks (recommended - fast, 160+ secret types):
+      #    macOS: brew install gitleaks
+      #    Linux/Windows: https://github.com/gitleaks/gitleaks#installation
+      #    Create .gitleaksignore for false positives
+      #
+      # 2. secretlint (npm-based, always available):
+      #    npm install --save-dev @secretlint/secretlint-rule-preset-recommend secretlint
+      #    Create .secretlintrc.json with: {"rules": [{"id": "@secretlint/secretlint-rule-preset-recommend"}]}
+      #    Create .secretlintignore for false positives
+      #
+      # 3. Both (defense-in-depth): Create both config files
+      #
+      # To use explicit command instead: scanCommand: "gitleaks protect --staged --verbose"
       # To disable: set enabled: false
 
 # Validation configuration

package/dist/bin/vibe-validate

@@ -7,10 +7,15 @@
  * - Local install: Project has vibe-validate → node_modules version (packaged)
  * - Global install: Fallback → globally installed version (packaged)
  *
+ * Features:
+ * - Version detection and comparison
+ * - Gentle warnings when global is outdated
+ * - Debug mode (VV_DEBUG=1) shows resolution details
+ *
  * Works in both git and non-git directories. Non-git directories don't get
  * caching but still get error extraction.
  */
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -46,8 +51,12 @@ function findProjectRoot(startDir) {
  * @returns Path to bin.js if detected, null otherwise
  */
 function getDevModeBinary(projectRoot) {
-    const wrapperPath = join(projectRoot, 'packages/cli/dist/vibe-validate');
+    const wrapperPath = join(projectRoot, 'packages/cli/dist/bin/vibe-validate');
     const binPath = join(projectRoot, 'packages/cli/dist/bin.js');
+    if (process.env.VV_DEBUG === '1') {
+        console.error(`[vv debug] Dev check - wrapper: ${wrapperPath} (${existsSync(wrapperPath)})`);
+        console.error(`[vv debug] Dev check - bin: ${binPath} (${existsSync(binPath)})`);
+    }
     // Both files must exist to confirm we're in vibe-validate repo
     if (existsSync(wrapperPath) && existsSync(binPath)) {
         return binPath;
@@ -77,21 +86,42 @@ function findLocalInstall(projectRoot) {
     }
     return null;
 }
+/**
+ * Read version from package.json
+ * @param packageJsonPath - Path to package.json file
+ * @returns Version string or null if not found
+ */
+function readVersion(packageJsonPath) {
+    try {
+        if (!existsSync(packageJsonPath)) {
+            return null;
+        }
+        const content = readFileSync(packageJsonPath, 'utf-8');
+        const pkg = JSON.parse(content);
+        return pkg.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Main entry point - detects context and executes appropriate binary
  */
 function main() {
     const cwd = process.cwd();
     const args = process.argv.slice(2);
+    const debug = process.env.VV_DEBUG === '1';
     // Find project root (where .git is, or cwd if no git)
     const projectRoot = findProjectRoot(cwd);
     let binPath;
     let context;
+    let binDir;
     // Priority 1: Check for developer mode (inside vibe-validate repo)
     const devBin = getDevModeBinary(projectRoot);
     if (devBin) {
         binPath = devBin;
         context = 'dev';
+        binDir = dirname(dirname(devBin)); // packages/cli/dist -> packages/cli
     }
     // Priority 2: Check for local install (node_modules)
     else {
@@ -99,19 +129,40 @@ function main() {
         if (localBin) {
             binPath = localBin;
             context = 'local';
+            binDir = dirname(dirname(localBin)); // node_modules/@vibe-validate/cli/dist -> node_modules/@vibe-validate/cli
         }
         // Priority 3: Use global install (this script's location)
         else {
             binPath = join(__dirname, '../bin.js');
             context = 'global';
+            binDir = dirname(__dirname); // dist -> cli root
         }
     }
+    // Read versions for comparison
+    // __dirname = dist/bin, so go up twice to reach package.json at cli root
+    const globalPkgPath = join(dirname(dirname(__dirname)), 'package.json');
+    const globalVersion = readVersion(globalPkgPath);
+    let localVersion = null;
+    if (context === 'local') {
+        const localPkgPath = join(binDir, 'package.json');
+        localVersion = readVersion(localPkgPath);
+    }
+    // Debug output
+    if (debug) {
+        console.error(`[vv debug] CWD: ${cwd}`);
+        console.error(`[vv debug] Project root: ${projectRoot}`);
+        console.error(`[vv debug] Context: ${context}`);
+        console.error(`[vv debug] Binary: ${binPath}`);
+        console.error(`[vv debug] Global version: ${globalVersion ?? 'unknown'}`);
+        console.error(`[vv debug] Local version: ${localVersion ?? 'N/A'}`);
+        console.error(`[vv debug] Args: ${args.join(' ')}`);
+    }
     // Execute the binary with all arguments
     const result = spawnSync(process.execPath, [binPath, ...args], {
         stdio: 'inherit',
         env: {
             ...process.env,
-            VV_CONTEXT: context, // Pass context for debugging (optional)
+            VV_CONTEXT: context, // Pass context for debugging
         },
     });
     // Exit with same code as child process

package/dist/bin/vibe-validate.d.ts

@@ -7,6 +7,11 @@
  * - Local install: Project has vibe-validate → node_modules version (packaged)
  * - Global install: Fallback → globally installed version (packaged)
  *
+ * Features:
+ * - Version detection and comparison
+ * - Gentle warnings when global is outdated
+ * - Debug mode (VV_DEBUG=1) shows resolution details
+ *
  * Works in both git and non-git directories. Non-git directories don't get
  * caching but still get error extraction.
  */

package/dist/bin/vibe-validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vibe-validate.d.ts","sourceRoot":"","sources":["../../src/bin/vibe-validate.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG"}
+{"version":3,"file":"vibe-validate.d.ts","sourceRoot":"","sources":["../../src/bin/vibe-validate.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG"}

package/dist/bin/vibe-validate.js

@@ -7,10 +7,15 @@
  * - Local install: Project has vibe-validate → node_modules version (packaged)
  * - Global install: Fallback → globally installed version (packaged)
  *
+ * Features:
+ * - Version detection and comparison
+ * - Gentle warnings when global is outdated
+ * - Debug mode (VV_DEBUG=1) shows resolution details
+ *
  * Works in both git and non-git directories. Non-git directories don't get
  * caching but still get error extraction.
  */
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -46,8 +51,12 @@ function findProjectRoot(startDir) {
  * @returns Path to bin.js if detected, null otherwise
  */
 function getDevModeBinary(projectRoot) {
-    const wrapperPath = join(projectRoot, 'packages/cli/dist/vibe-validate');
+    const wrapperPath = join(projectRoot, 'packages/cli/dist/bin/vibe-validate');
     const binPath = join(projectRoot, 'packages/cli/dist/bin.js');
+    if (process.env.VV_DEBUG === '1') {
+        console.error(`[vv debug] Dev check - wrapper: ${wrapperPath} (${existsSync(wrapperPath)})`);
+        console.error(`[vv debug] Dev check - bin: ${binPath} (${existsSync(binPath)})`);
+    }
     // Both files must exist to confirm we're in vibe-validate repo
     if (existsSync(wrapperPath) && existsSync(binPath)) {
         return binPath;
@@ -77,21 +86,42 @@ function findLocalInstall(projectRoot) {
     }
     return null;
 }
+/**
+ * Read version from package.json
+ * @param packageJsonPath - Path to package.json file
+ * @returns Version string or null if not found
+ */
+function readVersion(packageJsonPath) {
+    try {
+        if (!existsSync(packageJsonPath)) {
+            return null;
+        }
+        const content = readFileSync(packageJsonPath, 'utf-8');
+        const pkg = JSON.parse(content);
+        return pkg.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Main entry point - detects context and executes appropriate binary
  */
 function main() {
     const cwd = process.cwd();
     const args = process.argv.slice(2);
+    const debug = process.env.VV_DEBUG === '1';
     // Find project root (where .git is, or cwd if no git)
     const projectRoot = findProjectRoot(cwd);
     let binPath;
     let context;
+    let binDir;
     // Priority 1: Check for developer mode (inside vibe-validate repo)
     const devBin = getDevModeBinary(projectRoot);
     if (devBin) {
         binPath = devBin;
         context = 'dev';
+        binDir = dirname(dirname(devBin)); // packages/cli/dist -> packages/cli
     }
     // Priority 2: Check for local install (node_modules)
     else {
@@ -99,19 +129,40 @@ function main() {
         if (localBin) {
             binPath = localBin;
             context = 'local';
+            binDir = dirname(dirname(localBin)); // node_modules/@vibe-validate/cli/dist -> node_modules/@vibe-validate/cli
         }
         // Priority 3: Use global install (this script's location)
         else {
             binPath = join(__dirname, '../bin.js');
             context = 'global';
+            binDir = dirname(__dirname); // dist -> cli root
         }
     }
+    // Read versions for comparison
+    // __dirname = dist/bin, so go up twice to reach package.json at cli root
+    const globalPkgPath = join(dirname(dirname(__dirname)), 'package.json');
+    const globalVersion = readVersion(globalPkgPath);
+    let localVersion = null;
+    if (context === 'local') {
+        const localPkgPath = join(binDir, 'package.json');
+        localVersion = readVersion(localPkgPath);
+    }
+    // Debug output
+    if (debug) {
+        console.error(`[vv debug] CWD: ${cwd}`);
+        console.error(`[vv debug] Project root: ${projectRoot}`);
+        console.error(`[vv debug] Context: ${context}`);
+        console.error(`[vv debug] Binary: ${binPath}`);
+        console.error(`[vv debug] Global version: ${globalVersion ?? 'unknown'}`);
+        console.error(`[vv debug] Local version: ${localVersion ?? 'N/A'}`);
+        console.error(`[vv debug] Args: ${args.join(' ')}`);
+    }
     // Execute the binary with all arguments
     const result = spawnSync(process.execPath, [binPath, ...args], {
         stdio: 'inherit',
         env: {
             ...process.env,
-            VV_CONTEXT: context, // Pass context for debugging (optional)
+            VV_CONTEXT: context, // Pass context for debugging
         },
     });
     // Exit with same code as child process

package/dist/bin/vibe-validate.js.map

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

package/dist/bin/vv

@@ -7,10 +7,15 @@
  * - Local install: Project has vibe-validate → node_modules version (packaged)
  * - Global install: Fallback → globally installed version (packaged)
  *
+ * Features:
+ * - Version detection and comparison
+ * - Gentle warnings when global is outdated
+ * - Debug mode (VV_DEBUG=1) shows resolution details
+ *
  * Works in both git and non-git directories. Non-git directories don't get
  * caching but still get error extraction.
  */
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -46,8 +51,12 @@ function findProjectRoot(startDir) {
  * @returns Path to bin.js if detected, null otherwise
  */
 function getDevModeBinary(projectRoot) {
-    const wrapperPath = join(projectRoot, 'packages/cli/dist/vibe-validate');
+    const wrapperPath = join(projectRoot, 'packages/cli/dist/bin/vibe-validate');
     const binPath = join(projectRoot, 'packages/cli/dist/bin.js');
+    if (process.env.VV_DEBUG === '1') {
+        console.error(`[vv debug] Dev check - wrapper: ${wrapperPath} (${existsSync(wrapperPath)})`);
+        console.error(`[vv debug] Dev check - bin: ${binPath} (${existsSync(binPath)})`);
+    }
     // Both files must exist to confirm we're in vibe-validate repo
     if (existsSync(wrapperPath) && existsSync(binPath)) {
         return binPath;
@@ -77,21 +86,42 @@ function findLocalInstall(projectRoot) {
     }
     return null;
 }
+/**
+ * Read version from package.json
+ * @param packageJsonPath - Path to package.json file
+ * @returns Version string or null if not found
+ */
+function readVersion(packageJsonPath) {
+    try {
+        if (!existsSync(packageJsonPath)) {
+            return null;
+        }
+        const content = readFileSync(packageJsonPath, 'utf-8');
+        const pkg = JSON.parse(content);
+        return pkg.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Main entry point - detects context and executes appropriate binary
  */
 function main() {
     const cwd = process.cwd();
     const args = process.argv.slice(2);
+    const debug = process.env.VV_DEBUG === '1';
     // Find project root (where .git is, or cwd if no git)
     const projectRoot = findProjectRoot(cwd);
     let binPath;
     let context;
+    let binDir;
     // Priority 1: Check for developer mode (inside vibe-validate repo)
     const devBin = getDevModeBinary(projectRoot);
     if (devBin) {
         binPath = devBin;
         context = 'dev';
+        binDir = dirname(dirname(devBin)); // packages/cli/dist -> packages/cli
     }
     // Priority 2: Check for local install (node_modules)
     else {
@@ -99,19 +129,40 @@ function main() {
         if (localBin) {
             binPath = localBin;
             context = 'local';
+            binDir = dirname(dirname(localBin)); // node_modules/@vibe-validate/cli/dist -> node_modules/@vibe-validate/cli
         }
         // Priority 3: Use global install (this script's location)
         else {
             binPath = join(__dirname, '../bin.js');
             context = 'global';
+            binDir = dirname(__dirname); // dist -> cli root
         }
     }
+    // Read versions for comparison
+    // __dirname = dist/bin, so go up twice to reach package.json at cli root
+    const globalPkgPath = join(dirname(dirname(__dirname)), 'package.json');
+    const globalVersion = readVersion(globalPkgPath);
+    let localVersion = null;
+    if (context === 'local') {
+        const localPkgPath = join(binDir, 'package.json');
+        localVersion = readVersion(localPkgPath);
+    }
+    // Debug output
+    if (debug) {
+        console.error(`[vv debug] CWD: ${cwd}`);
+        console.error(`[vv debug] Project root: ${projectRoot}`);
+        console.error(`[vv debug] Context: ${context}`);
+        console.error(`[vv debug] Binary: ${binPath}`);
+        console.error(`[vv debug] Global version: ${globalVersion ?? 'unknown'}`);
+        console.error(`[vv debug] Local version: ${localVersion ?? 'N/A'}`);
+        console.error(`[vv debug] Args: ${args.join(' ')}`);
+    }
     // Execute the binary with all arguments
     const result = spawnSync(process.execPath, [binPath, ...args], {
         stdio: 'inherit',
         env: {
             ...process.env,
-            VV_CONTEXT: context, // Pass context for debugging (optional)
+            VV_CONTEXT: context, // Pass context for debugging
         },
     });
     // Exit with same code as child process

package/dist/bin.js

@@ -30,6 +30,10 @@ let version = '0.9.2'; // Fallback version
 try {
     const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
     version = packageJson.version;
+    // Append "-dev" suffix if running in dev context
+    if (process.env.VV_CONTEXT === 'dev') {
+        version = `${version}-dev`;
+    }
 }
 catch (error) {
     // If package.json can't be read (shouldn't happen in production), use fallback