claude-git-hooks 2.8.0 → 2.10.0

package/CHANGELOG.md

@@ -5,6 +5,163 @@ 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.10.0] - 2026-02-02
+
+### 🏗️ Architecture - Modular CLI Refactoring
+
+**Major refactoring: All CLI commands extracted to `lib/commands/` modules.**
+
+This release implements a **modular, decoupled, reusable** architecture for better maintainability, testability, and extensibility.
+
+### ✨ Added
+
+- **New `lib/commands/` directory** - One file per CLI command
+    - `helpers.js` - Shared CLI utilities (colors, output, platform detection, Entertainment)
+    - `install.js` - Installation logic (dependencies, hooks, templates, config migration)
+    - `hooks.js` - Hook management (enable, disable, status, uninstall)
+    - `analyze-diff.js` - Diff analysis (generate PR metadata from git diff)
+    - `create-pr.js` - PR creation (full Octokit workflow)
+    - `setup-github.js` - Token setup (interactive GitHub configuration)
+    - `presets.js` - Preset management (list, set, show current)
+    - `update.js` - Self-update (check and install latest version)
+    - `migrate-config.js` - Config migration (legacy to v2.8.0 format)
+    - `debug.js` - Debug toggle (enable/disable verbose logging)
+    - `telemetry-cmd.js` - Telemetry commands (show/clear statistics)
+    - `help.js` - Help display (usage information)
+
+### 🔄 Changed
+
+- **`bin/claude-hooks` reduced from 2,300 to 111 lines** - Now a thin CLI router
+    - Only handles argument parsing and command dispatch
+    - All business logic moved to `lib/commands/` modules
+    - Imports and calls appropriate command module based on CLI argument
+
+- **Design philosophy documented** - CLAUDE.md and README.md updated with:
+    - Purpose annotations for each component/layer
+    - Module responsibility descriptions
+    - Architectural decision rationale
+
+### 🎯 Benefits
+
+| Aspect | Before | After |
+|--------|--------|-------|
+| `bin/claude-hooks` size | 2,277 lines | 111 lines |
+| Command modules | 1 (`setup-github.js`) | 13 files |
+| Testability | Hard (monolithic) | Easy (modular) |
+| Finding code | Search entire file | Match filename to command |
+| Adding commands | Edit large file | Create new module |
+
+### 📚 Documentation
+
+- **README.md** - Added Command Modules table with purpose annotations
+- **CLAUDE.md** - Updated directory structure with purpose for each file
+- **README-NPM.md** - Added architecture section
+- **CHANGELOG.md** - This entry
+
+### 🔧 Technical Details
+
+**New module structure:**
+```
+lib/commands/
+├── helpers.js        (389 lines) - Shared utilities
+├── install.js        (691 lines) - Installation
+├── hooks.js          (148 lines) - Hook management
+├── analyze-diff.js   (267 lines) - Diff analysis
+├── create-pr.js      (374 lines) - PR creation
+├── presets.js        (101 lines) - Preset commands
+├── update.js         (67 lines)  - Self-update
+├── migrate-config.js (103 lines) - Config migration
+├── debug.js          (52 lines)  - Debug mode
+├── telemetry-cmd.js  (47 lines)  - Telemetry
+├── help.js           (147 lines) - Help display
+└── setup-github.js   (98 lines)  - GitHub setup
+```
+
+**Key patterns implemented:**
+- **Command Pattern**: Each CLI command is a self-contained module
+- **Thin Controller**: `bin/claude-hooks` only routes, doesn't implement
+- **Separation of Concerns**: UI helpers in `helpers.js`, business logic in specific modules
+
+### 🗑️ Removed
+
+- **Inline command implementations** from `bin/claude-hooks`:
+    - `install()` - moved to `lib/commands/install.js`
+    - `uninstall()` - moved to `lib/commands/hooks.js`
+    - `enable()` / `disable()` - moved to `lib/commands/hooks.js`
+    - `status()` - moved to `lib/commands/hooks.js`
+    - `analyzeDiff()` - moved to `lib/commands/analyze-diff.js`
+    - `createPr()` - moved to `lib/commands/create-pr.js`
+    - `showPresets()` / `setPreset()` / `currentPreset()` - moved to `lib/commands/presets.js`
+    - `update()` - moved to `lib/commands/update.js`
+    - `migrateConfig()` - moved to `lib/commands/migrate-config.js`
+    - `setDebug()` - moved to `lib/commands/debug.js`
+    - `showTelemetry()` / `clearTelemetry()` - moved to `lib/commands/telemetry-cmd.js`
+    - `showHelp()` / `showVersion()` - moved to `lib/commands/help.js`
+    - Helper functions (colors, log, error, success, etc.) - moved to `lib/commands/helpers.js`
+    - `Entertainment` class - moved to `lib/commands/helpers.js`
+
+### 📋 Migration
+
+**No breaking changes.** All CLI commands work identically. This is an internal refactoring.
+
+```bash
+# All commands work the same
+claude-hooks install
+claude-hooks create-pr develop
+claude-hooks --set-preset backend
+claude-hooks status
+```
+
+## [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