claude-git-hooks 2.3.0 → 2.3.1

package/CHANGELOG.md

@@ -5,6 +5,68 @@ 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.3.1] - 2025-11-13
+
+### 🔄 Changed
+
+- **Configuration Priority** - Updated merge order: `defaults < user config < preset config`
+  - **Rationale**: User sets general preferences in `.claude/config.json`, preset provides tech-stack-specific overrides (highest priority)
+  - **Effect**: Presets now correctly override user settings (e.g., preset's `model: sonnet` wins over user's `model: haiku`)
+  - **Files updated**: `lib/config.js:116` (merge logic), README.md:222 (documentation)
+
+### ✨ Added
+
+- **Installation Diagnostics Utility** - New `lib/utils/installation-diagnostics.js`
+  - **Purpose**: Reusable error diagnostics with actionable remediation steps
+  - **Exports**: `formatError()`, `getInstallationDiagnostics()`, `isInstallationHealthy()`
+  - **Use case**: Detects installation in wrong directory (common cause of "presets not found" errors)
+  - **Extensible**: Documented future enhancements (file permissions, Claude CLI check, etc.)
+
+- **Enhanced Error Messages** - Better guidance when installation fails
+  - **Presets not found** (`lib/utils/preset-loader.js:194`): Shows current vs repo root directory
+  - **Hook scripts missing** (`templates/pre-commit:76`, `templates/prepare-commit-msg:76`): Early `.claude/` check with remediation steps
+  - **npm package issues**: Suggests verifying `npm list -g claude-git-hooks`
+
+- **Bash Wrapper Early Validation** - Hooks now check `.claude/` exists before attempting execution
+  - **Why**: Fails fast with helpful message if installation incomplete or performed from wrong directory
+  - **Effect**: Users immediately know to `cd` to repo root and reinstall
+
+- **Claude Error Diagnostics** - New `lib/utils/claude-diagnostics.js`
+  - **Purpose**: Detects and formats Claude CLI errors with actionable solutions
+  - **Error types**: Rate limit, authentication, network, invalid response, generic
+  - **Exports**: `detectClaudeError()`, `formatClaudeError()`, `ClaudeErrorType`, `isRecoverableError()`
+  - **Integration**: `lib/utils/claude-client.js:147` automatically detects and formats errors
+  - **Effect**: Users see clear guidance (e.g., "Rate limit resets in 2 hours, switch to haiku model")
+
+### 📚 Documentation
+
+- **CUSTOMIZATION_GUIDE.md** - Comprehensive preset creation guide in `/templates`
+  - Visual flowchart showing prompt assembly (8-step diagram)
+  - Step-by-step preset creation tutorial
+  - Placeholder system reference with examples
+  - Preset kickstart prompt for Claude-assisted generation
+  - **Burst limit warning**: Explains why git hooks hit rate limits when manual CLI doesn't
+  - Referenced in README.md:333 for discoverability
+
+- **Utility Modules Reference** - New section in README.md:596
+  - Table of all `lib/utils/` modules with purpose and key exports
+  - Usage examples for other Claude instances
+  - Promotes code reuse across projects
+
+- **README-NPM.md** - Complete rewrite for npm package page
+  - **Length**: 266 lines (up from 145 lines, but more focused)
+  - **Updated**: v2.3.0 presets, v2.2.0 config centralization, v2.0.0 cross-platform
+  - **Added**: Configuration priority explanation, troubleshooting, "What's New" section
+  - **Removed**: Outdated v1.x references, environment variable examples
+
+### 🎯 User Experience
+
+- **Clearer error context**: Errors now show current directory vs repository root
+- **Actionable solutions**: Every error includes specific commands to fix the issue
+- **Installation verification**: Early checks prevent confusing downstream errors
+- **Better documentation**: Users can find utility functions and customization guides easily
+- **Claude error clarity**: Rate limits, auth failures, and network errors now show specific remediation steps
+
 ## [2.3.0] - 2025-11-11
 
 ### ✨ Added

package/README.md

@@ -224,11 +224,13 @@ EOF
 ```
 defaults (lib/config.js)
   ↓
-preset config (templates/presets/backend/config.json)
+user config (.claude/config.json)  ← General preferences
   ↓
-user config (.claude/config.json)  ← MÁXIMA PRIORIDAD
+preset config (.claude/presets/{name}/config.json)  ← MÁXIMA PRIORIDAD (tech-stack specific)
 ```
 
+**Rationale**: User sets general preferences, preset provides tech-stack-specific overrides.
+
 **Nota v2.2.0+:** Variables de entorno ya NO son soportadas. Usar `.claude/config.json` en su lugar.
 
 ### 🎯 Casos de Uso Específicos
@@ -324,6 +326,16 @@ git commit -m "fix: resolver issues"
 - `.claude/CLAUDE_PRE_COMMIT_SONAR.md` - Criterios (backend/frontend/data/db)
 - `.claude/CLAUDE_ANALYSIS_PROMPT_SONAR.md` - Template del prompt
 
+**Crear o modificar presets personalizados:**
+
+```bash
+# Ver guía completa de customización
+cat templates/CUSTOMIZATION_GUIDE.md
+
+# O en GitHub
+# https://github.com/pablorovito/claude-git-hooks/blob/main/templates/CUSTOMIZATION_GUIDE.md
+```
+
 **Ejemplo:**
 
 ```bash
@@ -556,16 +568,20 @@ claude-git-hooks/
 ├── bin/
 │   └── claude-hooks                          # CLI principal (ES6 modules)
 ├── lib/                                      # 🆕 Código Node.js modular
+│   ├── config.js                             # Configuración centralizada con merge
 │   ├── hooks/
 │   │   ├── pre-commit.js                     # Hook de análisis (Node.js)
 │   │   └── prepare-commit-msg.js             # Hook de mensajes (Node.js)
 │   └── utils/
 │       ├── logger.js                         # Sistema de logging centralizado
 │       ├── git-operations.js                 # Operaciones git abstractas
-│       ├── file-operations.js                # I/O con filtro SKIP_ANALYSIS_LINE
+│       ├── file-utils.js                     # Utilidades de sistema de archivos
 │       ├── claude-client.js                  # Cliente Claude CLI
 │       ├── prompt-builder.js                 # Constructor de prompts
-│       └── resolution-prompt.js              # Generador de resolution prompts
+│       ├── resolution-prompt.js              # Generador de resolution prompts
+│       ├── preset-loader.js                  # Cargador de presets
+│       ├── installation-diagnostics.js       # Diagnósticos de instalación
+│       └── claude-diagnostics.js             # Diagnósticos de errores Claude CLI
 ├── templates/
 │   ├── pre-commit                            # Bash wrapper (llama a lib/hooks/pre-commit.js)
 │   ├── prepare-commit-msg                    # Bash wrapper (llama a lib/hooks/prepare-commit-msg.js)
@@ -588,6 +604,68 @@ claude-git-hooks/
 └── .gitignore                                # Archivos ignorados por git
 ```
 
+### 🔌 Utility Modules Reference
+
+**Purpose**: Reusable modules for extending claude-hooks or building similar tools
+
+#### Core Utilities
+
+| Module | Purpose | Key Exports | Usage Context |
+|--------|---------|-------------|---------------|
+| **`config.js`** | Centralized configuration management | `getConfig()`, `defaults` | Priority merging: defaults < user < preset |
+| **`logger.js`** | Structured logging with debug support | `info()`, `warning()`, `error()`, `debug()` | Console output with context tracking |
+| **`git-operations.js`** | Git command abstractions | `getRepoRoot()`, `getStagedFiles()`, `getDiff()` | Safe git operations with error handling |
+| **`file-utils.js`** | File system operations | `ensureDir()`, `writeFile()` | Repo-root-relative path handling |
+| **`claude-client.js`** | Claude CLI integration | `analyzeCode()`, `analyzeCodeParallel()` | Prompt execution with timeout/retry |
+| **`prompt-builder.js`** | Template-based prompts | `buildAnalysisPrompt()`, `loadTemplate()` | Dynamic prompt construction from .md files |
+| **`preset-loader.js`** | Preset system | `loadPreset()`, `listPresets()`, `loadTemplate()` | Metadata, config, template loading |
+| **`resolution-prompt.js`** | Issue resolution prompts | `generateResolutionPrompt()` | AI-friendly error remediation prompts |
+| **`installation-diagnostics.js`** | Installation error diagnostics | `formatError()`, `getInstallationDiagnostics()` | Installation error formatting with remediation |
+| **`claude-diagnostics.js`** | Claude CLI error diagnostics | `detectClaudeError()`, `formatClaudeError()` | Rate limit, auth, network error detection |
+
+#### Using Utilities in Other Claude Instances
+
+**Example: Check installation health**
+```javascript
+import { formatError } from './lib/utils/installation-diagnostics.js';
+
+try {
+  // ... operation that may fail
+} catch (error) {
+  console.error(formatError('Operation failed', ['Additional context line']));
+  process.exit(1);
+}
+```
+
+**Example: Load configuration**
+```javascript
+import { getConfig } from './lib/config.js';
+
+const config = await getConfig();
+const maxFiles = config.analysis.maxFiles;
+```
+
+**Example: Execute git operations**
+```javascript
+import { getRepoRoot, getStagedFiles } from './lib/utils/git-operations.js';
+
+const repoRoot = getRepoRoot();
+const files = getStagedFiles({ extensions: ['.js', '.ts'] });
+```
+
+**Example: Build custom prompts**
+```javascript
+import { buildAnalysisPrompt } from './lib/utils/prompt-builder.js';
+
+const prompt = await buildAnalysisPrompt({
+  templateName: 'CUSTOM_PROMPT.md',
+  files: filesData,
+  metadata: { REPO_NAME: 'my-repo' }
+});
+```
+
+**Note**: All utilities follow single-responsibility principle and include JSDoc documentation inline.
+
 ### Configuración del Entorno de Desarrollo
 
 ```bash

package/lib/config.js

@@ -2,13 +2,14 @@
  * File: config.js
  * Purpose: Centralized configuration management
  *
- * Priority: .claude/config.json > defaults
+ * Priority: preset config > .claude/config.json > defaults
  *
  * Key features:
  * - Single source of truth for all configurable values
  * - No environment variables (except OS for platform detection)
  * - Preset-aware (allowedExtensions come from preset templates)
- * - Override via .claude/config.json per project
+ * - User config (.claude/config.json) provides general preferences per project
+ * - Preset config provides tech-stack-specific overrides (highest priority)
  */
 
 import fs from 'fs';
@@ -79,9 +80,9 @@ const defaults = {
 
 /**
  * Loads user configuration from .claude/config.json
- * Merges with defaults and preset config (preset -> user config takes priority)
+ * Merges with defaults and preset config (preset takes highest priority)
  *
- * Priority: defaults < preset config < user config
+ * Priority: defaults < user config < preset config
  *
  * @param {string} baseDir - Base directory to search for config (default: cwd)
  * @returns {Promise<Object>} Merged configuration
@@ -112,8 +113,8 @@ const loadUserConfig = async (baseDir = process.cwd()) => {
         }
     }
 
-    // Merge: defaults < preset < user
-    return deepMerge(deepMerge(defaults, presetConfig), userConfig);
+    // Merge: defaults < user < preset
+    return deepMerge(deepMerge(defaults, userConfig), presetConfig);
 };
 
 /**

package/lib/hooks/pre-commit.js

@@ -312,7 +312,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/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;
+};