claude-git-hooks 2.1.0 → 2.3.1

package/CHANGELOG.md

@@ -5,6 +5,246 @@ 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
+
+- **Preset System (Phase 3)**
+  - 🎯 6 built-in presets: `backend`, `frontend`, `fullstack`, `database`, `ai`, `default`
+  - 📦 Self-contained preset packages with custom prompts and configurations
+  - 🔍 Smart file filtering per preset (`.java` for backend, `.tsx` for frontend, etc.)
+  - 🎨 Rich metadata: tech stack, focus areas, file extensions, display names
+  - 🔌 Template inheritance with placeholder replacement ({{TECH_STACK}}, {{FOCUS_AREAS}})
+  - 🛠️ Manual preset selection via CLI: `claude-hooks --set-preset <name>`
+  - 📋 Preset management commands: `presets`, `preset current`, `--set-preset`
+  - 📖 See `next-steps/V2.3.0_PHASE3_PRESETS_FINAL.md` for full specification
+
+- **CLI Enhancements**
+  - 🏷️ Added `--version`, `-v`, and `version` commands to display current version
+  - 📊 Version check on install with interactive update prompt (skippable with `--skip-auth` or `--force`)
+
+### 🐛 Fixed
+
+- **Critical Bug**: `prepare-commit-msg` now properly loads merged config (preset + user overrides)
+  - Was using sync default import instead of async `getConfig()`
+  - Preset settings were being ignored in commit message generation
+- **Template Name Mismatch**: Fixed config.js template paths
+  - `COMMIT_MESSAGE.md` (was `CLAUDE_COMMIT_MESSAGE.md`)
+  - `ANALYZE_DIFF.md` (was `CLAUDE_ANALYZE_DIFF.md`)
+- **Missing Auto-Update**: `checkVersionAndPromptUpdate()` now called during install
+
+### 🗑️ Removed
+
+- ❌ Deleted `readPassword()` function (24 lines) - unused since v2.0.0 sudo removal
+- ❌ Deleted `setMode()` function (5 lines) - empty implementation, never used
+- ❌ Deleted `readMultipleFiles()` function (62 lines) - exported but never imported
+- ❌ Removed `"main": "lib/index.js"` from package.json - CLI-only package
+- ❌ Deleted obsolete root template `CLAUDE_PRE_COMMIT_SONAR.md`
+
+### 🔄 Changed
+
+- **Commit Message Timeout**: Increased from 120s to 180s for complex analysis
+- **Config Loading**: All hooks now use async `getConfig()` for proper preset merging
+
+### 📚 Documentation
+
+- 📖 Updated CHANGELOG with v2.3.0 release notes
+- 📝 Marked Phase 3 preset system as IMPLEMENTED in spec
+
+### 🎯 Preset Examples
+
+```bash
+# List available presets
+claude-hooks presets
+
+# Set backend preset (filters to .java, .xml, .yml files)
+claude-hooks --set-preset backend
+
+# Check active preset
+claude-hooks preset current
+
+# All presets installed during: claude-hooks install
+```
+
+### 📦 Available Presets
+
+1. **backend** - Spring Boot + SQL Server (Java, XML, YAML)
+2. **frontend** - React + Material-UI (JS, JSX, TS, TSX, CSS)
+3. **fullstack** - Backend + Frontend + DB with consistency checks
+4. **database** - SQL Server migrations and procedures
+5. **ai** - Node.js + Claude CLI integration
+6. **default** - General-purpose scripting
+
+### 📋 Migration from v2.2.0
+
+No breaking changes. Presets are opt-in:
+
+```bash
+# Continue using defaults (no preset)
+git commit -m "message"
+
+# Or activate a preset
+claude-hooks --set-preset backend
+git commit -m "message"  # Now filters to .java, .xml, .yml only
+```
+
+## [2.2.0] - 2025-11-04
+
+### ✨ Added
+
+- **Configuration Centralization (Phase 1)**
+  - 📁 Created `lib/config.js` - single source of truth for all configurable values
+  - 🔧 User override support via `.claude/config.json` with deep merge
+  - 📊 Structured config: analysis, commitMessage, subagents, templates, output, system, git
+  - 🚫 Eliminated environment variables (except OS for platform detection)
+  - 📖 See `next-steps/V2.2.0_CONFIG_CENTRALIZATION.md` for details
+
+- **Prompt Externalization (Phase 2)**
+  - 📝 Extracted ALL embedded prompts to external .md template files
+  - 🔌 Created `loadPrompt()` utility - combines load + variable replacement
+  - 📄 New templates: `COMMIT_MESSAGE.md`, `ANALYZE_DIFF.md`
+  - 🎯 JavaScript is now completely "prompt-agnostic"
+  - 📖 See `next-steps/V2.2.0_PHASE2_PROMPTS.md` for details
+
+- **Parallel Analysis**
+  - 🚀 True OS-level parallel execution using multiple Claude CLI processes simultaneously
+  - ⚡ `analyzeCodeParallel()` function runs batches via Node.js `Promise.all()`
+  - 📊 Configurable `batchSize` for optimal speed/cost balance (default: 2)
+  - 🔀 Automatic result consolidation with worst-case quality gate logic
+  - 📈 Real-time console output showing parallel batch launches and completion
+  - 🎯 Enabled by default for commits with 3+ files
+  - ⏱️ Speed improvement: up to 4x faster with `batchSize: 1`
+
+### 🔄 Changed
+
+- **Configuration Migration**
+  - ♻️ Migrated `lib/hooks/pre-commit.js` to use centralized config
+  - ♻️ Migrated `lib/hooks/prepare-commit-msg.js` to use centralized config
+  - ♻️ Migrated `lib/utils/claude-client.js` to use centralized config
+  - 🔧 `process.env.DEBUG` → `config.system.debug`
+  - 🔧 All hardcoded timeouts now configurable
+
+- **Prompt Migration**
+  - ♻️ `prepare-commit-msg.js`: 40 lines → 15 lines (62% reduction)
+  - ♻️ `bin/claude-hooks`: 30 lines → 10 lines (67% reduction)
+  - 🎨 Prompts now editable without touching JavaScript code
+
+- **Template Loading**
+  - 📂 Enhanced `loadTemplate()` with fallback: `.claude/` → `templates/`
+  - 🔀 Enables per-project customization of prompts
+
+### 🗑️ Removed
+
+- ❌ Deleted `buildCommitMessagePrompt()` - unused legacy code
+- ❌ Removed all `process.env` references except OS check
+
+### 📚 Documentation
+
+- 📖 Added `next-steps/V2.2.0_CONFIG_CENTRALIZATION.md`
+- 📖 Added `next-steps/V2.2.0_PHASE2_PROMPTS.md`
+- 📝 Updated configuration examples and customization guides
+
+### 🎯 Benefits
+
+- **Maintainability:** Prompts editable by non-developers
+- **Flexibility:** Easy A/B testing of prompt styles
+- **Customization:** Per-project overrides via `.claude/config.json`
+- **Simplicity:** Clear separation of concerns (JS = logic, .md = content)
+
+### 📋 Migration Guide
+
+No breaking changes. All defaults match previous behavior.
+
+**Optional: Customize configuration**
+```bash
+# Create project config
+mkdir -p .claude
+cat > .claude/config.json << 'EOF'
+{
+  "analysis": {
+    "maxFileSize": 200000,
+    "maxFiles": 15
+  },
+  "subagents": {
+    "enabled": true,
+    "model": "sonnet"
+  },
+  "system": {
+    "debug": true
+  }
+}
+EOF
+```
+
+**Optional: Customize prompts**
+```bash
+# Override commit message prompt
+cp templates/COMMIT_MESSAGE.md .claude/
+# Edit .claude/COMMIT_MESSAGE.md as needed
+```
+
 ## [2.1.0] - 2025-11-04
 
 ### Changed