claude-git-hooks 2.6.2 → 2.6.3

package/CHANGELOG.md

@@ -5,6 +5,28 @@ Todos los cambios notables en este proyecto se documentarán en este archivo.
 El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.6.3]
+
+### 🐛 Fixed
+
+- **WSL timeout error misreporting** - Fixed misleading error message when WSL times out under system load (#49)
+    - **What was broken**: ETIMEDOUT errors during WSL Claude verification were misreported as "Claude CLI not found in WSL"
+    - **Root cause**: Catch block in WSL verification treated all errors identically, including transient ETIMEDOUT timeouts from system load
+    - **Fix**: Added error type differentiation to distinguish between ETIMEDOUT (transient timeout), ENOENT (missing CLI), and generic WSL errors
+    - **Files changed**:
+        - `lib/utils/claude-client.js:109-146` - Enhanced error detection with three distinct error paths
+    - **Impact**:
+        - ETIMEDOUT: Clear message "Timeout connecting to WSL - system under heavy load" with suggestion to retry or skip
+        - ENOENT: Preserved original "Claude CLI not found in WSL" with installation instructions
+        - Generic: New fallback "Failed to verify Claude CLI in WSL" with WSL diagnostic suggestions
+    - **Compatibility**: No breaking changes, improves error accuracy for Windows WSL users
+
+### 🎯 User Experience
+
+- **Before**: Users experiencing system load timeouts saw misleading "Claude CLI not found" error and tried reinstalling unnecessarily
+- **After**: Clear distinction between transient timeouts (retry/skip) and missing CLI (install) with actionable suggestions for each
+- **Debug**: All error cases now include context with platform, wslPath, error type, and specific remediation steps
+
 ## [2.6.2] - 2025-12-12
 
 ### 🐛 Fixed
@@ -118,11 +140,13 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 ### 🔧 Technical Details
 
 **DEP0190 Explanation**:
+
 - **What**: Node.js 24 deprecates `spawn(cmd, args, { shell: true })`
 - **Why**: Args are not escaped, just concatenated → shell injection risk
 - **Fix**: Use absolute executable paths, remove `shell: true`
 
 **Files Changed**:
+
 - `lib/utils/claude-client.js` - Command resolution and spawn call
 - `lib/utils/which-command.js` - NEW utility for path resolution
 - `package.json` - Platform documentation
@@ -131,6 +155,7 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - `MIGRATION_NODE24.md` - NEW migration guide
 
 **Backward Compatibility**:
+
 - ✅ Works on Node 16.9.0+ (unchanged)
 - ✅ Works on Node 18 (unchanged)
 - ✅ Works on Node 20 (unchanged)
@@ -149,6 +174,7 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 ### 📋 Migration Checklist
 
 For users on Node 24:
+
 - [x] Update to claude-git-hooks 2.6.0
 - [x] Verify no DEP0190 warnings: `claude-hooks install`
 - [x] Test pre-commit hook: `git commit`

package/lib/utils/claude-client.js

@@ -107,11 +107,40 @@ const getClaudeCommand = () => {
                 logger.debug('claude-client - getClaudeCommand', 'Using WSL Claude CLI', { wslPath });
                 return { command: wslPath, args: ['claude'] };
             } catch (wslError) {
-                throw new ClaudeClientError('Claude CLI not found in WSL', {
+                // Differentiate error types for accurate user feedback
+                const errorMsg = wslError.message || '';
+
+                // Timeout: Transient system load issue
+                if (errorMsg.includes('ETIMEDOUT')) {
+                    throw new ClaudeClientError('Timeout connecting to WSL - system under heavy load', {
+                        context: {
+                            platform: 'Windows',
+                            wslPath,
+                            error: 'ETIMEDOUT',
+                            suggestion: 'System is busy. Wait a moment and try again, or skip analysis: git commit --no-verify'
+                        }
+                    });
+                }
+
+                // Not found: Claude CLI missing in WSL
+                if (errorMsg.includes('ENOENT') || errorMsg.includes('command not found')) {
+                    throw new ClaudeClientError('Claude CLI not found in WSL', {
+                        context: {
+                            platform: 'Windows',
+                            wslPath,
+                            error: 'ENOENT',
+                            suggestion: 'Install Claude in WSL: wsl -e bash -c "npm install -g @anthropic-ai/claude-cli"'
+                        }
+                    });
+                }
+
+                // Generic error: Other WSL issues
+                throw new ClaudeClientError('Failed to verify Claude CLI in WSL', {
                     context: {
                         platform: 'Windows',
                         wslPath,
-                        wslError: wslError.message
+                        error: errorMsg,
+                        suggestion: 'Check WSL is functioning: wsl --version, or skip analysis: git commit --no-verify'
                     }
                 });
             }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-git-hooks",
-    "version": "2.6.2",
+    "version": "2.6.3",
     "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
     "type": "module",
     "bin": {