claude-git-hooks 2.3.0 → 2.4.0

package/lib/hooks/pre-commit.js

@@ -181,12 +181,38 @@ const main = async () => {
         // Load configuration
         const config = await getConfig();
 
+        // Enable debug mode from config
+        if (config.system.debug) {
+            logger.setDebugMode(true);
+        }
+
         // Display configuration info
         const version = await getVersion();
         console.log(`\n🤖 claude-git-hooks v${version}`);
 
         logger.info('Starting code quality analysis...');
 
+        // DEBUG: Log working directories
+        const repoRoot = await import('../utils/git-operations.js').then(m => m.getRepoRoot());
+        const { getRepoRoot } = await import('../utils/git-operations.js');
+
+        // Normalize paths for comparison (handle Windows backslash vs forward slash)
+        const normalizePath = (p) => p.replace(/\\/g, '/').toLowerCase();
+        const cwdNormalized = normalizePath(process.cwd());
+        const repoRootNormalized = normalizePath(repoRoot);
+
+        logger.debug(
+            'pre-commit - main',
+            'Working directory info',
+            {
+                'process.cwd()': process.cwd(),
+                'repo root': repoRoot,
+                'cwd (normalized)': cwdNormalized,
+                'repo root (normalized)': repoRootNormalized,
+                'match': cwdNormalized === repoRootNormalized
+            }
+        );
+
         logger.debug(
             'pre-commit - main',
             'Configuration',
@@ -237,6 +263,14 @@ const main = async () => {
         });
 
         const validFiles = filteredFiles.filter(f => f.valid);
+        const invalidFiles = filteredFiles.filter(f => !f.valid);
+
+        // Show user-facing warnings for rejected files
+        if (invalidFiles.length > 0) {
+            invalidFiles.forEach(file => {
+                logger.warning(`Skipping ${file.path}: ${file.reason}`);
+            });
+        }
 
         if (validFiles.length === 0) {
             logger.warning('No valid files found to review');
@@ -312,7 +346,8 @@ const main = async () => {
 
         // Step 5: Analyze with Claude (parallel or single)
         let result;
-
+            // TODO: This can be refactored so no conditional is needed. 
+            // Lists can have 0...N items, e.g. iterating a list of 1 element is akin to single execution.
         if (subagentsEnabled && filesData.length >= 3) {
             // Parallel execution: split files into batches
             logger.info(`Using parallel execution with batch size ${batchSize}`);

package/lib/hooks/prepare-commit-msg.js

@@ -120,6 +120,11 @@ const main = async () => {
     // Load configuration (includes preset + user overrides)
     const config = await getConfig();
 
+    // Enable debug mode from config
+    if (config.system.debug) {
+        logger.setDebugMode(true);
+    }
+
     try {
         // Get hook arguments
         const args = process.argv.slice(2);

package/lib/utils/claude-client.js

@@ -12,6 +12,7 @@
  * - child_process: For executing Claude CLI
  * - fs/promises: For debug file writing
  * - logger: Debug and error logging
+ * - claude-diagnostics: Error detection and formatting
  */
 
 import { spawn, execSync } from 'child_process';
@@ -20,6 +21,7 @@ import path from 'path';
 import os from 'os';
 import logger from './logger.js';
 import config from '../config.js';
+import { detectClaudeError, formatClaudeError, ClaudeErrorType } from './claude-diagnostics.js';
 
 /**
  * Custom error for Claude client failures
@@ -141,18 +143,25 @@ const executeClaude = (prompt, { timeout = 120000 } = {}) => {
                 );
                 resolve(stdout);
             } else {
+                // Detect specific error type
+                const errorInfo = detectClaudeError(stdout, stderr, code);
+
                 logger.error(
                     'claude-client - executeClaude',
-                    `Claude CLI failed with exit code ${code}`,
-                    new ClaudeClientError('Claude CLI execution failed', {
+                    `Claude CLI failed: ${errorInfo.type}`,
+                    new ClaudeClientError(`Claude CLI error: ${errorInfo.type}`, {
                         output: { stdout, stderr },
-                        context: { exitCode: code, duration }
+                        context: { exitCode: code, duration, errorType: errorInfo.type }
                     })
                 );
 
-                reject(new ClaudeClientError('Claude CLI execution failed', {
+                // Show formatted error to user
+                const formattedError = formatClaudeError(errorInfo);
+                console.error('\n' + formattedError + '\n');
+
+                reject(new ClaudeClientError(`Claude CLI error: ${errorInfo.type}`, {
                     output: { stdout, stderr },
-                    context: { exitCode: code, duration }
+                    context: { exitCode: code, duration, errorInfo }
                 }));
             }
         });

package/lib/utils/claude-diagnostics.js

@@ -0,0 +1,266 @@
+/**
+ * File: claude-diagnostics.js
+ * Purpose: Reusable Claude CLI error diagnostics and formatting
+ *
+ * Key features:
+ * - Detects common Claude CLI error patterns
+ * - Provides actionable remediation steps
+ * - Extensible for future error types
+ *
+ * Usage:
+ *   import { detectClaudeError, formatClaudeError } from './claude-diagnostics.js';
+ *
+ *   const errorInfo = detectClaudeError(stdout, stderr, exitCode);
+ *   if (errorInfo) {
+ *     console.error(formatClaudeError(errorInfo));
+ *   }
+ */
+
+/**
+ * Error types that can be detected
+ */
+export const ClaudeErrorType = {
+    RATE_LIMIT: 'RATE_LIMIT',
+    AUTH_FAILED: 'AUTH_FAILED',
+    TIMEOUT: 'TIMEOUT',
+    NETWORK: 'NETWORK',
+    INVALID_RESPONSE: 'INVALID_RESPONSE',
+    GENERIC: 'GENERIC'
+};
+
+/**
+ * Detects Claude CLI error type and extracts relevant information
+ * Why: Centralized error detection for consistent handling
+ *
+ * Future enhancements:
+ * - Network connectivity errors
+ * - Authentication expiration
+ * - Model availability errors
+ * - Token limit exceeded errors
+ *
+ * @param {string} stdout - Claude CLI stdout
+ * @param {string} stderr - Claude CLI stderr
+ * @param {number} exitCode - Process exit code
+ * @returns {Object|null} Error information or null if no specific error detected
+ */
+export const detectClaudeError = (stdout = '', stderr = '', exitCode = 1) => {
+    // 1. Rate limit detection
+    const rateLimitMatch = stdout.match(/Claude AI usage limit reached\|(\d+)/);
+    if (rateLimitMatch) {
+        const resetTimestamp = parseInt(rateLimitMatch[1], 10);
+        const resetDate = new Date(resetTimestamp * 1000);
+        const now = new Date();
+        const minutesUntilReset = Math.ceil((resetDate - now) / 60000);
+
+        return {
+            type: ClaudeErrorType.RATE_LIMIT,
+            exitCode,
+            resetTimestamp,
+            resetDate,
+            minutesUntilReset
+        };
+    }
+
+    // 2. Authentication failure detection
+    if (stdout.includes('not authenticated') || stderr.includes('not authenticated') ||
+        stdout.includes('authentication failed') || stderr.includes('authentication failed')) {
+        return {
+            type: ClaudeErrorType.AUTH_FAILED,
+            exitCode
+        };
+    }
+
+    // 3. Network errors
+    if (stderr.includes('ENOTFOUND') || stderr.includes('ECONNREFUSED') ||
+        stderr.includes('network error') || stderr.includes('connection refused')) {
+        return {
+            type: ClaudeErrorType.NETWORK,
+            exitCode
+        };
+    }
+
+    // 4. Invalid response (JSON parsing errors)
+    if (stdout.includes('SyntaxError') || stdout.includes('Unexpected token')) {
+        return {
+            type: ClaudeErrorType.INVALID_RESPONSE,
+            exitCode
+        };
+    }
+
+    // 5. Generic error
+    return {
+        type: ClaudeErrorType.GENERIC,
+        exitCode,
+        stdout: stdout.substring(0, 200), // First 200 chars
+        stderr: stderr.substring(0, 200)
+    };
+};
+
+/**
+ * Formats Claude error message with diagnostics and remediation steps
+ * Why: Provides consistent, actionable error messages
+ *
+ * @param {Object} errorInfo - Output from detectClaudeError()
+ * @returns {string} Formatted error message
+ */
+export const formatClaudeError = (errorInfo) => {
+    const lines = [];
+
+    switch (errorInfo.type) {
+        case ClaudeErrorType.RATE_LIMIT:
+            return formatRateLimitError(errorInfo);
+
+        case ClaudeErrorType.AUTH_FAILED:
+            return formatAuthError(errorInfo);
+
+        case ClaudeErrorType.NETWORK:
+            return formatNetworkError(errorInfo);
+
+        case ClaudeErrorType.INVALID_RESPONSE:
+            return formatInvalidResponseError(errorInfo);
+
+        case ClaudeErrorType.GENERIC:
+        default:
+            return formatGenericError(errorInfo);
+    }
+};
+
+/**
+ * Format rate limit error
+ */
+const formatRateLimitError = ({ resetDate, minutesUntilReset }) => {
+    const lines = [];
+
+    lines.push('❌ Claude API usage limit reached');
+    lines.push('');
+    lines.push('Rate limit details:');
+    lines.push(`  Reset time: ${resetDate.toLocaleString()}`);
+
+    if (minutesUntilReset > 60) {
+        const hours = Math.ceil(minutesUntilReset / 60);
+        lines.push(`  Time until reset: ~${hours} hour${hours > 1 ? 's' : ''}`);
+    } else if (minutesUntilReset > 0) {
+        lines.push(`  Time until reset: ~${minutesUntilReset} minute${minutesUntilReset !== 1 ? 's' : ''}`);
+    } else {
+        lines.push('  Limit should be reset now');
+    }
+
+    lines.push('');
+    lines.push('Options:');
+    lines.push('  1. Wait for rate limit to reset');
+    lines.push('  2. Skip analysis for now:');
+    lines.push('     git commit --no-verify -m "your message"');
+    lines.push('  3. Reduce API usage by switching to haiku model:');
+    lines.push('     Edit .claude/config.json:');
+    lines.push('     { "subagents": { "model": "haiku" } }');
+
+    return lines.join('\n');
+};
+
+/**
+ * Format authentication error
+ */
+const formatAuthError = ({ exitCode }) => {
+    const lines = [];
+
+    lines.push('❌ Claude CLI authentication failed');
+    lines.push('');
+    lines.push('Possible causes:');
+    lines.push('  1. Not logged in to Claude CLI');
+    lines.push('  2. Authentication token expired');
+    lines.push('  3. Invalid API credentials');
+    lines.push('');
+    lines.push('Solution:');
+    lines.push('  claude auth login');
+    lines.push('');
+    lines.push('Then try your commit again.');
+
+    return lines.join('\n');
+};
+
+/**
+ * Format network error
+ */
+const formatNetworkError = ({ exitCode }) => {
+    const lines = [];
+
+    lines.push('❌ Network error connecting to Claude API');
+    lines.push('');
+    lines.push('Possible causes:');
+    lines.push('  1. No internet connection');
+    lines.push('  2. Firewall blocking Claude API');
+    lines.push('  3. Claude API temporarily unavailable');
+    lines.push('');
+    lines.push('Solutions:');
+    lines.push('  1. Check your internet connection');
+    lines.push('  2. Verify firewall settings');
+    lines.push('  3. Try again in a few moments');
+    lines.push('  4. Skip analysis: git commit --no-verify -m "message"');
+
+    return lines.join('\n');
+};
+
+/**
+ * Format invalid response error
+ */
+const formatInvalidResponseError = ({ exitCode }) => {
+    const lines = [];
+
+    lines.push('❌ Claude returned invalid response');
+    lines.push('');
+    lines.push('This usually means:');
+    lines.push('  - Claude did not return valid JSON');
+    lines.push('  - Response format does not match expected schema');
+    lines.push('');
+    lines.push('Solutions:');
+    lines.push('  1. Check debug output: .claude/out/debug-claude-response.json');
+    lines.push('  2. Try again (may be temporary issue)');
+    lines.push('  3. Skip analysis: git commit --no-verify -m "message"');
+
+    return lines.join('\n');
+};
+
+/**
+ * Format generic error
+ */
+const formatGenericError = ({ exitCode, stdout, stderr }) => {
+    const lines = [];
+
+    lines.push('❌ Claude CLI execution failed');
+    lines.push('');
+    lines.push(`Exit code: ${exitCode}`);
+
+    if (stdout && stdout.trim()) {
+        lines.push('');
+        lines.push('Output:');
+        lines.push(`  ${stdout.trim()}`);
+    }
+
+    if (stderr && stderr.trim()) {
+        lines.push('');
+        lines.push('Error:');
+        lines.push(`  ${stderr.trim()}`);
+    }
+
+    lines.push('');
+    lines.push('Solutions:');
+    lines.push('  1. Verify Claude CLI is installed: claude --version');
+    lines.push('  2. Check authentication: claude auth login');
+    lines.push('  3. Enable debug mode in .claude/config.json:');
+    lines.push('     { "system": { "debug": true } }');
+    lines.push('  4. Skip analysis: git commit --no-verify -m "message"');
+
+    return lines.join('\n');
+};
+
+/**
+ * Checks if Claude CLI error is recoverable
+ * Why: Some errors (rate limit) should wait, others (auth) should fail immediately
+ *
+ * @param {Object} errorInfo - Output from detectClaudeError()
+ * @returns {boolean} True if error might resolve with retry
+ */
+export const isRecoverableError = (errorInfo) => {
+    return errorInfo.type === ClaudeErrorType.RATE_LIMIT ||
+           errorInfo.type === ClaudeErrorType.NETWORK;
+};

package/lib/utils/file-operations.js

@@ -250,13 +250,24 @@ const filterFiles = async (files, { maxSize = 100000, extensions = [] } = {}) =>
     logger.debug(
         'file-operations - filterFiles',
         'Filtering files',
-        { fileCount: files.length, maxSize, extensions }
+        {
+            fileCount: files.length,
+            maxSize,
+            extensions,
+            'process.cwd()': process.cwd(),
+            files: files
+        }
     );
 
     const results = await Promise.allSettled(
         files.map(async (filePath) => {
             // Check extension first (fast)
             if (!hasAllowedExtension(filePath, extensions)) {
+                logger.debug(
+                    'file-operations - filterFiles',
+                    'Extension rejected',
+                    { filePath }
+                );
                 return {
                     path: filePath,
                     size: 0,
@@ -267,6 +278,11 @@ const filterFiles = async (files, { maxSize = 100000, extensions = [] } = {}) =>
 
             // Check if file exists
             const exists = await fileExists(filePath);
+            logger.debug(
+                'file-operations - filterFiles',
+                'File exists check',
+                { filePath, exists }
+            );
             if (!exists) {
                 return {
                     path: filePath,
@@ -281,6 +297,11 @@ const filterFiles = async (files, { maxSize = 100000, extensions = [] } = {}) =>
                 const size = await getFileSize(filePath);
 
                 if (size > maxSize) {
+                    logger.debug(
+                        'file-operations - filterFiles',
+                        'File too large',
+                        { filePath, size, maxSize, 'size (KB)': Math.round(size / 1024), 'maxSize (KB)': Math.round(maxSize / 1024) }
+                    );
                     return {
                         path: filePath,
                         size,
@@ -289,6 +310,12 @@ const filterFiles = async (files, { maxSize = 100000, extensions = [] } = {}) =>
                     };
                 }
 
+                logger.debug(
+                    'file-operations - filterFiles',
+                    'File passed size check',
+                    { filePath, size, maxSize, 'size (KB)': Math.round(size / 1024) }
+                );
+
                 return {
                     path: filePath,
                     size,
@@ -297,6 +324,11 @@ const filterFiles = async (files, { maxSize = 100000, extensions = [] } = {}) =>
                 };
 
             } catch (error) {
+                logger.debug(
+                    'file-operations - filterFiles',
+                    'Error reading file',
+                    { filePath, error: error.message }
+                );
                 return {
                     path: filePath,
                     size: 0,
@@ -312,15 +344,17 @@ const filterFiles = async (files, { maxSize = 100000, extensions = [] } = {}) =>
         .filter(r => r.status === 'fulfilled')
         .map(r => r.value);
 
-    const validCount = fileMetadata.filter(f => f.valid).length;
+    const validFiles = fileMetadata.filter(f => f.valid);
+    const invalidFiles = fileMetadata.filter(f => !f.valid);
 
     logger.debug(
         'file-operations - filterFiles',
         'Filtering complete',
         {
             totalFiles: files.length,
-            validFiles: validCount,
-            invalidFiles: fileMetadata.length - validCount
+            validFiles: validFiles.length,
+            invalidFiles: invalidFiles.length,
+            rejectedFiles: invalidFiles.map(f => ({ path: f.path, reason: f.reason }))
         }
     );
 

package/lib/utils/installation-diagnostics.js

@@ -0,0 +1,145 @@
+/**
+ * File: installation-diagnostics.js
+ * Purpose: Reusable error diagnostics and formatting utilities
+ *
+ * Key features:
+ * - Generic error formatting with installation diagnostics
+ * - Detects common installation issues
+ * - Provides actionable remediation steps
+ * - Extensible for future diagnostic checks
+ *
+ * Usage:
+ *   import { formatError } from './installation-diagnostics.js';
+ *
+ *   try {
+ *     // ... operation that might fail
+ *   } catch (error) {
+ *     console.error(formatError('Presets not found'));
+ *     process.exit(1);
+ *   }
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { getRepoRoot } from './git-operations.js';
+
+/**
+ * Gets installation diagnostics
+ * Why: Centralized logic to detect common installation issues
+ *
+ * Future enhancements:
+ * - Check file permissions
+ * - Verify Claude CLI installation
+ * - Check Node.js version compatibility
+ * - Validate .gitignore entries
+ * - Check hook file integrity
+ * - Verify template files exist
+ * - Check config.json validity
+ *
+ * @returns {Object} Diagnostic information
+ */
+export const getInstallationDiagnostics = () => {
+    const diagnostics = {
+        currentDir: process.cwd(),
+        repoRoot: null,
+        isInRepoRoot: false,
+        claudeDirExists: false,
+        claudeDirPath: null,
+        presetsDirExists: false,
+        presetsDirPath: null,
+        gitHooksExists: false,
+    };
+
+    try {
+        diagnostics.repoRoot = getRepoRoot();
+        diagnostics.isInRepoRoot = diagnostics.currentDir === diagnostics.repoRoot;
+
+        diagnostics.claudeDirPath = path.join(diagnostics.repoRoot, '.claude');
+        diagnostics.claudeDirExists = fs.existsSync(diagnostics.claudeDirPath);
+
+        diagnostics.presetsDirPath = path.join(diagnostics.claudeDirPath, 'presets');
+        diagnostics.presetsDirExists = fs.existsSync(diagnostics.presetsDirPath);
+
+        const gitHooksPath = path.join(diagnostics.repoRoot, '.git', 'hooks');
+        diagnostics.gitHooksExists = fs.existsSync(gitHooksPath);
+    } catch (error) {
+        // Not in a git repository - diagnostics.repoRoot will be null
+    }
+
+    return diagnostics;
+};
+
+/**
+ * Formats error message with diagnostics and remediation steps
+ * Why: Provides consistent, actionable error messages across all errors
+ *
+ * @param {string} errorMessage - Description of what failed (e.g., "Presets not found", "Template file missing")
+ * @param {string[]} additionalContext - Optional additional context lines
+ * @returns {string} Formatted error message with diagnostics and remediation steps
+ */
+export const formatError = (errorMessage, additionalContext = []) => {
+    const diagnostics = getInstallationDiagnostics();
+    const lines = [];
+
+    lines.push(`⚠️  ${errorMessage}`);
+    lines.push('');
+
+    // Add any additional context first
+    if (additionalContext.length > 0) {
+        lines.push(...additionalContext);
+        lines.push('');
+    }
+
+    // Diagnostic information
+    lines.push('Installation diagnostics:');
+    lines.push(`  Current directory: ${diagnostics.currentDir}`);
+    if (diagnostics.repoRoot) {
+        lines.push(`  Repository root:   ${diagnostics.repoRoot}`);
+        lines.push(`  .claude/ exists:   ${diagnostics.claudeDirExists ? '✓' : '✗'}`);
+        lines.push(`  presets/ exists:   ${diagnostics.presetsDirExists ? '✓' : '✗'}`);
+    } else {
+        lines.push(`  Repository root:   [Not in a git repository]`);
+    }
+    lines.push('');
+
+    // Remediation steps based on detected issues
+    lines.push('Recommended solution:');
+    if (!diagnostics.repoRoot) {
+        lines.push('  Not in a git repository');
+        lines.push('  → Navigate to your repository and try again');
+    } else if (!diagnostics.claudeDirExists) {
+        lines.push('  claude-hooks not installed');
+        if (!diagnostics.isInRepoRoot) {
+            lines.push(`  → cd ${diagnostics.repoRoot}`);
+            lines.push('  → claude-hooks install');
+        } else {
+            lines.push('  → claude-hooks install');
+        }
+    } else if (!diagnostics.isInRepoRoot) {
+        lines.push('  Running from subdirectory (may cause path issues)');
+        lines.push(`  → cd ${diagnostics.repoRoot}`);
+        lines.push('  → claude-hooks uninstall');
+        lines.push('  → claude-hooks install');
+    } else if (!diagnostics.presetsDirExists) {
+        lines.push('  Incomplete installation (presets missing)');
+        lines.push('  → claude-hooks install --force');
+    } else {
+        lines.push('  Unknown issue detected');
+        lines.push('  → claude-hooks install --force');
+    }
+
+    return lines.join('\n');
+};
+
+/**
+ * Checks if installation appears healthy
+ * Why: Quick validation before operations that require full installation
+ *
+ * @returns {boolean} True if installation looks healthy
+ */
+export const isInstallationHealthy = () => {
+    const diagnostics = getInstallationDiagnostics();
+    return diagnostics.claudeDirExists &&
+           diagnostics.presetsDirExists &&
+           diagnostics.gitHooksExists;
+};

package/lib/utils/logger.js

@@ -16,7 +16,7 @@
 
 class Logger {
     constructor({ debugMode = false } = {}) {
-        this.debugMode = debugMode || process.env.DEBUG === 'true';
+        this.debugMode = debugMode;
         this.colors = {
             reset: '\x1b[0m',
             red: '\x1b[31m',
@@ -138,4 +138,4 @@ class Logger {
 
 // Export singleton instance
 // Why: Single logger instance ensures consistent debug mode across entire application
-export default new Logger({ debugMode: process.env.DEBUG === 'true' });
+export default new Logger();

package/lib/utils/preset-loader.js

@@ -13,12 +13,14 @@
  * - path: Cross-platform path handling
  * - git-operations: For getRepoRoot()
  * - logger: Debug and error logging
+ * - installation-diagnostics: Error formatting with remediation steps
  */
 
 import fs from 'fs/promises';
 import path from 'path';
 import { getRepoRoot } from './git-operations.js';
 import logger from './logger.js';
+import { formatError } from './installation-diagnostics.js';
 
 /**
  * Custom error for preset loading failures
@@ -189,7 +191,10 @@ export async function listPresets() {
             }
         }
     } catch (error) {
-        logger.warning('No presets directory found. Run "claude-hooks install" first.');
+        const errorMsg = formatError('No presets directory found', [
+            `Expected location: ${presetsDir}`
+        ]);
+        logger.warning(errorMsg);
         logger.debug(
             'preset-loader - listPresets',
             'Failed to read presets directory',

package/package.json

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