claude-git-hooks 2.6.1 → 2.6.3

package/CHANGELOG.md

@@ -5,6 +5,50 @@ 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
+
+- **Parallel analysis stdin error handling** - Added graceful error handling for EOF errors during parallel execution (#43)
+    - **What was broken**: Unhandled 'error' events on stdin stream when Claude CLI process terminates unexpectedly during parallel analysis
+    - **Root cause**: `stdin.write()` failures emit asynchronous 'error' events that weren't being caught, causing uncaught exceptions with large prompts (18+ files) in parallel mode
+    - **Fix**: Added explicit error handler on `stdin` stream before writing prompt
+    - **Files changed**:
+        - `lib/utils/claude-client.js:287-308` - Added stdin error handler with detailed diagnostics
+    - **Impact**:
+        - Provides clear error message: "Failed to write to Claude stdin - process terminated unexpectedly"
+        - Logs diagnostic info: prompt length, error code, duration
+        - Suggests actionable fix: "Try reducing batch size or number of files per commit"
+    - **Compatibility**: No breaking changes, improves error reporting for all platforms
+
+### 🎯 User Experience
+
+- **Before**: Cryptic unhandled 'write EOF' exceptions crashed commit process with no actionable information
+- **After**: Clear error message with diagnostic context and suggested remediation
+- **Debug**: Added structured logging with prompt length and timing when EOF errors occur
+
 ## [2.6.1] - 2025-12-04
 
 ### 🐛 Fixed
@@ -96,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
@@ -109,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)
@@ -127,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'
                     }
                 });
             }
@@ -280,13 +309,40 @@ const executeClaude = (prompt, { timeout = 120000, allowedTools = [] } = {}) =>
 
     // Write prompt to stdin
     // Why: Claude CLI reads prompt from stdin, not command arguments
+
+    // Handle stdin errors (e.g., EOF when process terminates unexpectedly)
+    // Why: write() failures can emit 'error' events asynchronously
+    // Common in parallel execution with large prompts
+    claude.stdin.on('error', (error) => {
+        logger.error(
+            'claude-client - executeClaude',
+            'stdin stream error (process may have terminated early)',
+            {
+                error: error.message,
+                code: error.code,
+                promptLength: prompt.length,
+                duration: Date.now() - startTime
+            }
+        );
+
+        reject(new ClaudeClientError('Failed to write to Claude stdin - process terminated unexpectedly', {
+            cause: error,
+            context: {
+                promptLength: prompt.length,
+                errorCode: error.code,
+                errorMessage: error.message,
+                suggestion: 'Try reducing batch size or number of files per commit'
+            }
+        }));
+    });
+
     try {
         claude.stdin.write(prompt);
         claude.stdin.end();
     } catch (error) {
         logger.error(
             'claude-client - executeClaude',
-            'Failed to write prompt to Claude CLI stdin',
+            'Failed to write prompt to Claude CLI stdin (synchronous error)',
             error
         );
 

package/package.json

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