claude-git-hooks 2.7.1 → 2.9.1

package/CHANGELOG.md

@@ -5,6 +5,169 @@ 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.9.1] - 2025-12-30
+
+### 🐛 Fixed
+
+- **Template path mismatch after v2.8.0 migration** - Fixed critical bug where templates were not found after config migration (#51)
+    - **What was broken**: After v2.8.0 moved templates from `.claude/` to `.claude/prompts/`, the code still looked in the old location
+    - **Root cause**: `prompt-builder.js` and `resolution-prompt.js` had hardcoded `.claude/` paths instead of `.claude/prompts/`
+    - **Symptom**: `ENOENT: no such file or directory` errors for `CLAUDE_ANALYSIS_PROMPT.md` and `CLAUDE_RESOLUTION_PROMPT.md`
+    - **Fix**: Updated default paths in template loading functions to `.claude/prompts/`
+    - **Files changed**:
+        - `lib/utils/prompt-builder.js:45,133,223,234-235,244` - Updated `loadTemplate`, `loadPrompt`, `buildAnalysisPrompt` defaults
+        - `lib/utils/resolution-prompt.js:183` - Updated `generateResolutionPrompt` template path
+    - **Impact**: Pre-commit analysis and resolution prompt generation now work correctly after v2.8.0+ installation
+
+### 🎯 User Experience
+
+- **Before**: Users upgrading from v2.6.x to v2.8.0+ experienced "Template not found" errors even after successful installation
+- **After**: Templates are found in correct `.claude/prompts/` directory as intended by v2.8.0 changes
+
+## [2.9.0] - 2025-12-26
+
+### ✨ Added
+
+- **Local telemetry system with per-retry tracking** - Enabled by default for debugging JSON parsing failures (#50)
+    - **What it does**: Tracks JSON parsing failures and successes with full context, recording EVERY retry attempt individually
+    - **Key features**:
+        - **Granular tracking**: Records each retry attempt separately (not just final result)
+        - **Unique IDs**: Each event has unique ID (timestamp-counter-random) for deduplication
+        - **Success flag**: Boolean indicating whether attempt succeeded (true) or failed (false)
+        - **Retry metadata**: `retryAttempt` (0-3) and `totalRetries` (max configured)
+        - **Error types**: Tracks EXECUTION_ERROR, JSON_PARSE_ERROR, etc.
+        - **Hook coverage**: pre-commit, prepare-commit-msg, analyze-diff, create-pr
+    - **Privacy-first**: Local-only (`.claude/telemetry/`), no data leaves user's machine, no external transmission
+    - **Storage**: JSON lines format with automatic rotation (keeps last 30 days)
+    - **CLI commands**:
+        - `claude-hooks telemetry show` - Display statistics (failure rate, failures by batch size/model/hook, retry patterns)
+        - `claude-hooks telemetry clear` - Reset telemetry data
+    - **Enabled by default**: To disable, add `"system": { "telemetry": false }` to `.claude/config.json`
+    - **Files added**:
+        - `lib/utils/telemetry.js` - Telemetry collection with ID generation, retry tracking, and statistics
+    - **Files changed**:
+        - `lib/utils/claude-client.js:678-780,788-798` - Modified withRetry() to record telemetry on each attempt
+        - `lib/utils/claude-client.js:609-618,845-856` - Removed duplicate telemetry recordings
+        - `lib/hooks/pre-commit.js` - Pass telemetry context for analysis
+        - `lib/hooks/prepare-commit-msg.js` - Pass telemetry context for commit messages
+        - `lib/config.js` - Add telemetry config option (default: true)
+        - `bin/claude-hooks:1076-1091,1354-1366` - Add telemetry context to analyze-diff and create-pr
+        - `bin/claude-hooks` - Add telemetry CLI commands
+    - **Impact**: Enables diagnosis of retry patterns, identifies which retry attempts succeed, tracks transient vs persistent errors, helps optimize batch sizes and models
+
+## [2.8.0] - 2025-12-24
+
+### 🎨 Changed
+
+- **Simplified configuration format** - New v2.8.0 config structure reduces redundancy and improves maintainability
+    - **What changed**: Config now uses `version` field and `overrides` structure, 21 parameters moved to hardcoded defaults
+    - **New format**: `{ "version": "2.8.0", "preset": "backend", "overrides": {...} }`
+    - **Old format**: `{ "preset": "backend", "analysis": {...}, "subagents": {...}, ... }` (20+ top-level keys)
+    - **User-configurable** (5 params): `preset`, `github.pr.*`, `subagents.batchSize`
+    - **Hardcoded** (21 params): `analysis.*` (maxFileSize, maxFiles, timeout), `commitMessage.*`, `templates.*`, etc.
+    - **Advanced** (3 params): `analysis.ignoreExtensions`, `commitMessage.taskIdPattern`, `subagents.model`
+    - **Files changed**:
+        - `lib/config.js:1-280` - Split into HARDCODED and defaults, added legacy format detection
+        - `templates/config.example.json` - New simplified format with examples
+        - `templates/config.advanced.example.json` - Advanced parameters with documentation
+        - `bin/claude-hooks:483-570` - Auto-migration during install
+    - **Impact**: Cleaner config files, sensible defaults work for 99% of users
+
+- **Automatic config migration** - Legacy configs auto-migrate during installation with backup
+    - **What changed**: `claude-hooks install` detects legacy format and migrates automatically
+    - **Migration process**: Backup to `.claude/config_old/`, extract allowed params, create v2.8.0 config
+    - **Preserved settings**: `github.pr.*`, `subagents.batchSize`, and advanced params (with warnings)
+    - **Files changed**:
+        - `bin/claude-hooks:510-530,1942-2115` - Auto-migration in install, new `migrate-config` command
+    - **Impact**: Seamless upgrade path, settings preserved, zero manual work
+
+- **Organized prompt templates** - All .md files moved to `.claude/prompts/` subdirectory
+    - **What changed**: Installation creates `.claude/prompts/` and places markdown templates there
+    - **Old location**: `.claude/CLAUDE_ANALYSIS_PROMPT.md`, `.claude/CLAUDE_PRE_COMMIT.md`, etc.
+    - **New location**: `.claude/prompts/CLAUDE_ANALYSIS_PROMPT.md`, `.claude/prompts/CLAUDE_PRE_COMMIT.md`, etc.
+    - **Auto-cleanup**: Old .md files in `.claude/` root are automatically removed during installation
+    - **Files changed**:
+        - `bin/claude-hooks:401-457` - Creates prompts directory, moves .md files, cleans up old files
+        - `lib/config.js:57` - Updated `templates.baseDir` to `.claude/prompts`
+    - **Impact**: Cleaner `.claude/` directory structure, prompts separated from config files
+
+- **Parallel analysis enabled by default** - Subagents now hardcoded to enabled (was opt-in)
+    - **What changed**: `subagents.enabled` moved from user config to hardcoded `true`
+    - **Why**: Faster analysis is universally beneficial, no reason to disable
+    - **Files changed**: `lib/config.js:52-54` - Hardcoded `enabled: true`, `model: 'haiku'`, `batchSize: 3`
+    - **Impact**: All users get faster analysis out-of-box (4x speedup on 3+ files)
+
+### ✨ Added
+
+- **Config example files** - Split documentation into simple and advanced examples
+    - `templates/config.example.json` - Minimal config (99% of users) with inline examples
+    - `templates/config.advanced.example.json` - Advanced parameters with full documentation
+    - Installation copies both to `.claude/config_example/` for reference
+    - **Impact**: Clear guidance for common use cases, power users can tinker safely
+
+- **Manual config migration command** - New `claude-hooks migrate-config` for manual upgrades
+    - Checks config version, creates backup in `.claude/config_old/`
+    - Extracts allowed parameters, warns about advanced params
+    - Shows diff preview before writing
+    - **Impact**: Users can migrate at their pace, review changes before applying
+
+### 🔧 Fixed
+
+- **Preset name now correctly displayed in hooks** - Fixed config loader not including preset name in final config
+    - **What was broken**: Hooks always showed "Default (General-purpose)" preset regardless of actual preset configured
+    - **Root cause**: Config loader extracted `presetName` but never added it to the final merged config object
+    - **Fix**: Add `preset` field to final config object after merge operations
+    - **Files changed**: `lib/config.js:181-184`
+    - **Impact**: Hooks now correctly display configured preset (e.g., "AI", "Backend", "Frontend")
+
+- **Example configs no longer clutter .claude/** - Example files only exist in `.claude/config_example/`
+    - **What was broken**: Installation copied `*example.json` to both `.claude/` and `.claude/config_example/`
+    - **Fix**: Filter `*example.json` during template copy, only place in `config_example/`
+    - **Files changed**: `bin/claude-hooks:410-415,498-507`
+    - **Impact**: Cleaner `.claude/` directory without redundant example files
+
+### ⚠️ Breaking Changes
+
+- **Config format change** - Legacy config format (pre-v2.8.0) requires migration
+    - **Migration**: Automatic during `install`, or manual via `claude-hooks migrate-config`
+    - **Compatibility**: Legacy format still works with deprecation warning until v3.0.0
+    - **Action required**: None (auto-migrates), but consider running `migrate-config` to see diff
+
+- **Template location change** - .md files moved from `.claude/` to `.claude/prompts/`
+    - **Migration**: Automatic during `install --force`
+    - **Custom templates**: If you customized templates, move them to `.claude/prompts/` manually
+    - **Impact**: Low - most users don't customize, system checks both locations
+
+- **Hardcoded parameters** - 21 parameters no longer user-configurable in .claude/config.json
+    - **Removed from user config**: `analysis.*` (except ignoreExtensions), `commitMessage.*` (except taskIdPattern), `templates.*`, `output.*`, `system.*`, `git.*`, `subagents.enabled`, `subagents.model` (except in advanced config)
+    - **Rationale**: Sensible defaults work for everyone, reduces configuration complexity
+    - **Override**: Advanced params available in `config.advanced.example.json` (use with caution)
+
+## [2.7.2] - 2025-12-23
+
+### ✨ Added
+
+- **Retry logic for PR commands** - Added automatic retry for `create-pr` and `analyze-diff` commands (#49)
+    - **What changed**: Both commands now use `executeClaudeWithRetry()` with exponential backoff (2s, 4s, 8s delays)
+    - **Impact**: PR creation and diff analysis now automatically recover from transient Claude API errors
+    - **Files changed**:
+        - `lib/utils/claude-client.js:676-745,846` - Created reusable `withRetry()` wrapper and `executeClaudeWithRetry()` export
+        - `bin/claude-hooks:11,972,1234` - Updated create-pr and analyze-diff to use retry logic
+
+### 🐛 Fixed
+
+- **Windows WSL timeout** - Increased WSL availability check from 3s to 15s to handle system load (#49)
+    - `lib/config.js:78` - Made configurable via `config.system.wslCheckTimeout`
+    - `lib/utils/claude-client.js:107` - Uses config value for WSL check
+- **Duplicate task ID logging** - Removed redundant log in prepare-commit-msg (#49)
+    - `lib/hooks/prepare-commit-msg.js:191-193` - Removed duplicate logger.info call
+
+### 🎯 Improved
+
+- **Error diagnostics** - Added timing information to all error contexts (#49)
+    - `lib/utils/claude-client.js:248-340` - Added `elapsedTime`, `timeoutValue`, `retryAttempt` to errors
+    - `lib/utils/claude-diagnostics.js:118-143,187-344` - Created `formatTimingInfo()` helper, updated all error formatters
+
 ## [2.7.1] - 2025-12-22
 
 ### 🐛 Fixed

package/README.md

@@ -65,6 +65,12 @@ claude-hooks --debug true
 
 # Ver estado de debug
 claude-hooks --debug status
+
+# Ver estadísticas de telemetría (v2.9.0+, habilitada por defecto)
+claude-hooks telemetry show
+
+# Limpiar datos de telemetría (v2.9.0+)
+claude-hooks telemetry clear
 ```
 
 ### 📦 Instalación y Gestión
@@ -164,16 +170,20 @@ export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_tu_token_aqui"
 ### 4. Configurar reviewers y labels (opcional)
 
 ```bash
-# Ver templates/config.github.example.json para formato completo
+# Ver .claude/config_example/ para más ejemplos
 cat > .claude/config.json << 'EOF'
 {
-  "github": {
-    "pr": {
-      "defaultBase": "develop",
-      "reviewers": ["tu-usuario-github", "teammate"],
-      "labelRules": {
-        "backend": ["backend", "java"],
-        "frontend": ["frontend", "react"]
+  "version": "2.8.0",
+  "preset": "backend",
+  "overrides": {
+    "github": {
+      "pr": {
+        "defaultBase": "develop",
+        "reviewers": ["tu-usuario-github", "teammate"],
+        "labelRules": {
+          "backend": ["backend", "java"],
+          "frontend": ["frontend", "react"]
+        }
       }
     }
   }
@@ -206,40 +216,41 @@ Ver `templates/config.github.example.json` para configuración avanzada (reviewe
 
 Toda idea es bienvenida, aunque parezca espantosa. Si hay bugs, incluirlos también. Dónde? en https://github.com/mscope-S-L/git-hooks/issues/new.
 
-### 🔧 Configuración Avanzada (v2.2.0+)
+### 🔧 Configuración Avanzada (v2.8.0+)
 
 ```bash
-# Configuración vía .claude/config.json
+# Configuración vía .claude/config.json (v2.8.0+)
 .claude/
-├── config.json                      # Configuración principal (v2.2.0+)
-├── CLAUDE_PRE_COMMIT.md      # Personalizar criterios (override)
-└── CLAUDE_ANALYSIS_PROMPT.md # Modificar prompt (override)
-
-# Ejemplo de config.json (todas las opciones son opcionales)
+├── config.json                      # Configuración principal (formato simplificado)
+├── config_example/                  # Ejemplos de configuración
+│   ├── config.example.json          # Configuración básica
+│   └── config.advanced.example.json # Parámetros avanzados
+└── prompts/                         # Templates de prompts (v2.8.0+)
+    ├── CLAUDE_PRE_COMMIT.md         # Criterios de análisis
+    └── CLAUDE_ANALYSIS_PROMPT.md    # Template del prompt
+
+# Ejemplo de config.json v2.8.0 (formato simplificado)
 cat > .claude/config.json << 'EOF'
 {
+  "version": "2.8.0",
   "preset": "backend",
-  "analysis": {
-    "maxFileSize": 1000000,
-    "maxFiles": 12,
-    "timeout": 150000
-  },
-  "commitMessage": {
-    "autoKeyword": "auto",
-    "timeout": 180000,
-    "taskIdPattern": "([A-Z]{1,3}[-\\s]\\d{3,5})"
-  },
-  "subagents": {
-    "enabled": true,
-    "model": "haiku",
-    "batchSize": 3
-  },
-  "system": {
-    "debug": true
+  "overrides": {
+    "github": {
+      "pr": {
+        "defaultBase": "main",
+        "reviewers": ["tech-lead"]
+      }
+    },
+    "subagents": {
+      "batchSize": 2
+    }
   }
 }
 EOF
 
+# Para configuración avanzada, consultar:
+# .claude/config_example/config.advanced.example.json
+
 # Personalizar patrón de task-id
 # Default: 1-3 letras + separador + 3-5 dígitos
 # Ejemplos válidos: ABC-12345, IX-123, DE 4567
@@ -357,31 +368,40 @@ git commit -m "fix: resolver issues"
 ### ⚡ Tips y Trucos
 
 1. **Mensaje automático**: Usa `"auto"` como mensaje para que Claude lo genere con task-id automático
-2. **Task-ID pattern**: Default 1-3 letras + separador + 3-5 dígitos (ABC-12345, IX-123). Configurable en `.claude/config.json` → `commitMessage.taskIdPattern`
+2. **Task-ID pattern**: Default 1-3 letras + separador + 3-5 dígitos (ABC-12345, IX-123). Configurable en `.claude/config_example/config.advanced.example.json`
 3. **Skip auth**: Usa `--skip-auth` en CI/CD o desarrollo local
 4. **Force install**: Usa `--force` para reinstalar sin confirmación
-5. **Debug**: Activa con `claude-hooks --debug true` o en `.claude/config.json`: `{"system": {"debug": true}}`
-6. **Archivos grandes**: Se omiten automáticamente archivos > 1MB
-7. **Límite de archivos**: Máximo 30 archivos por commit (configurable)
+5. **Debug**: Activa con `claude-hooks --debug true`
+6. **Archivos grandes**: Se omiten automáticamente archivos > 1MB (hardcoded desde v2.8.0)
+7. **Límite de archivos**: Máximo 20 archivos por commit (hardcoded desde v2.8.0)
+
+### 🚀 Parallel Analysis (Enabled by default desde v2.8.0)
+
+**When analyzing 3+ files**, parallel execution runs multiple Claude CLI processes simultaneously for faster analysis.
 
-### 🚀 Parallel Analysis (v2.2.0+)
+**Configuración automática (hardcoded):**
+- ✅ **Enabled**: `true` (siempre activo)
+- ⚡ **Model**: `haiku` (rápido y económico)
+- 📦 **BatchSize**: `3` files per batch (puede overridearse)
 
-**When analyzing 3+ files**, parallel execution runs multiple Claude CLI processes simultaneously for faster analysis:
+**Customizar batch size (opcional):**
 
 ```bash
-# Configure in .claude/config.json
+# En .claude/config.json v2.8.0
 {
-  "subagents": {
-    "enabled": true,
-    "model": "haiku",
-    "batchSize": 2
+  "version": "2.8.0",
+  "preset": "backend",
+  "overrides": {
+    "subagents": {
+      "batchSize": 2
+    }
   }
 }
 ```
 
-**Model options:**
+**Model options (solo en config avanzado):**
 
-- `haiku` - Fast & cheap (default, recommended)
+- `haiku` - Fast & cheap (default)
 - `sonnet` - Balanced quality/speed
 - `opus` - Maximum quality (slower)
 
@@ -422,9 +442,9 @@ git commit -m "fix: resolver issues"
 
 **Archivos clave para modificar:**
 
-- `.claude/config.json` - Configuración principal (v2.2.0+)
-- `.claude/CLAUDE_PRE_COMMIT.md` - Criterios (backend/frontend/data/db)
-- `.claude/CLAUDE_ANALYSIS_PROMPT.md` - Template del prompt
+- `.claude/config.json` - Configuración principal (v2.8.0+)
+- `.claude/prompts/CLAUDE_PRE_COMMIT.md` - Criterios (backend/frontend/data/db)
+- `.claude/prompts/CLAUDE_ANALYSIS_PROMPT.md` - Template del prompt
 
 **Crear o modificar presets personalizados:**
 
@@ -439,7 +459,7 @@ cat templates/CUSTOMIZATION_GUIDE.md
 **Ejemplo:**
 
 ```bash
-vim .claude/CLAUDE_PRE_COMMIT.md  # Agregar reglas API REST/Spring Boot
+vim .claude/prompts/CLAUDE_PRE_COMMIT.md  # Agregar reglas API REST/Spring Boot
 ```
 
 ## 🔧 Configuración Previa Importante
@@ -537,8 +557,8 @@ Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas s
     - Omite archivos mayores a 1MB
     - Límite de 30 archivos por commit
 3. **Construye prompt inteligente**:
-    - Usa template de prompt desde `.claude/CLAUDE_ANALYSIS_PROMPT*.md`
-    - Lee las pautas desde `.claude/CLAUDE_PRE_COMMIT*.md`
+    - Usa template de prompt desde `.claude/prompts/CLAUDE_ANALYSIS_PROMPT*.md`
+    - Lee las pautas desde `.claude/prompts/CLAUDE_PRE_COMMIT*.md`
     - Incluye el diff completo para archivos nuevos
     - Muestra solo cambios para archivos existentes
 4. **Envía a Claude CLI para revisión**