claude-git-hooks 2.1.0 → 2.3.1

package/README.md

@@ -5,6 +5,7 @@
 ## ✨ Novedad v2.0.0 - Ahora Cross-Platform
 
 **¡Nueva arquitectura!** Migración completa a Node.js con ES6 modules para soporte más universal:
+
 - ✅ **Windows** - Git en Bash y Powershell
 - ✅ **WSL** - Subsistema de Linux
 - ✅ **Linux** - Funcionamiento nativo
@@ -16,8 +17,9 @@
 - 🔍 **Análisis de código pre-commit**: Detecta issues críticos antes de que lleguen al repo
 - 💬 **Mensajes de commit automáticos**: Escribe "auto" y Claude genera el mensaje
 - 📋 **Generación de PRs**: Título, descripción y tests sugeridos con un solo comando
+- 🎯 **Presets por tech-stack**: 6 configuraciones optimizadas (backend, frontend, fullstack, database, ai, default) - v2.3.0+
 - ⚠️ **Skip inteligente** (EXPERIMENTAL/BROKEN): Exclusión de código con comentarios SKIP_ANALYSIS - no funciona correctamente con git diff
-- 🕵️‍♂️ **Paralelización**: Análisis asincrónico de archivos con sub agentes
+- 🚀 **Parallel Analysis**: Multiple Claude CLI processes analyzing file batches simultaneously (v2.2.0+)
 - 🔄 **Auto-actualización**: Se mantiene actualizado automáticamente
 - 🌍 **Cross-platform**: Windows, WSL, macOS, Linux sin configuración especial
 
@@ -37,6 +39,15 @@ claude-hooks analyze-diff develop
 
 # Reinstalar durante desarrollo (después de npm link)
 claude-hooks install --force --skip-auth
+
+# Listar presets
+claude-hooks presets
+
+# Seleccionar preset
+claude-hooks --set-preset <name>
+
+# Mostrar preset actual
+claude-hooks preset current
 ```
 
 ### 📦 Instalación y Gestión
@@ -102,25 +113,126 @@ public void methodToIgnore() {
 // SKIP_ANALYSIS_BLOCK
 ```
 
-### 🔧 Configuración Avanzada
+### 🔧 Configuración Avanzada (v2.2.0+)
 
 ```bash
-# Archivos de configuración
+# Configuración vía .claude/config.json
 .claude/
-├── CLAUDE_PRE_COMMIT_SONAR.md      # Personalizar criterios
-├── CLAUDE_ANALYSIS_PROMPT_SONAR.md # Modificar prompt
-└── settings.local.json              # Configuración local
-
-# Variables de entorno
-export CLAUDE_ANALYSIS_MODE=sonarqube  # Modo de análisis
-export CLAUDE_DEBUG=true               # Debug detallado
-
-# Subagent configuration (parallel analysis for multiple files)
-export CLAUDE_USE_SUBAGENTS=true           # Enable subagent parallel analysis
-export CLAUDE_SUBAGENT_MODEL=haiku         # Model: haiku (fast), sonnet (balanced), opus (thorough)
-export CLAUDE_SUBAGENT_BATCH_SIZE=3        # Parallel subagents per batch (default: 3)
+├── config.json                      # Configuración principal (v2.2.0+)
+├── CLAUDE_PRE_COMMIT_SONAR.md      # Personalizar criterios (override)
+└── CLAUDE_ANALYSIS_PROMPT_SONAR.md # Modificar prompt (override)
+
+# Ejemplo de config.json (todas las opciones son opcionales)
+cat > .claude/config.json << 'EOF'
+{
+  "preset": "backend",
+  "analysis": {
+    "maxFileSize": 150000,
+    "maxFiles": 12,
+    "timeout": 150000
+  },
+  "commitMessage": {
+    "autoKeyword": "auto",
+    "timeout": 180000
+  },
+  "subagents": {
+    "enabled": true,
+    "model": "haiku",
+    "batchSize": 3
+  },
+  "system": {
+    "debug": true
+  }
+}
+EOF
+```
+
+#### 🎯 Presets Disponibles
+
+| Preset        | Extensiones de Archivo                                                     | Caso de Uso      | Tech Stack                   |
+| ------------- | -------------------------------------------------------------------------- | ---------------- | ---------------------------- |
+| **backend**   | `.java`, `.xml`, `.yml`, `.yaml`                                           | APIs Spring Boot | Spring Boot, JPA, SQL Server |
+| **frontend**  | `.js`, `.jsx`, `.ts`, `.tsx`, `.css`, `.scss`, `.html`                     | Apps React       | React, Redux, Material-UI    |
+| **fullstack** | Todos backend + frontend                                                   | Apps full-stack  | Spring Boot + React          |
+| **database**  | `.sql`                                                                     | Scripts de BD    | SQL Server, T-SQL            |
+| **ai**        | `.js`, `.json`, `.md`, `.sh`                                               | Herramientas CLI | Node.js, Claude API          |
+| **default**   | `.js`, `.sh`, `.py`, `.rb`, `.pl`, `.sql`, `.yaml`, `.json`, `.xml`, `.md` | Propósito general| Lenguajes mixtos             |
+
+---
+
+#### 🔍 Qué Verifica Cada Preset
+
+**Backend (Spring Boot + SQL Server)**
+
+- ✅ Diseño de API REST y métodos HTTP
+- ✅ Entidades JPA y repositorios
+- ✅ Seguridad (OWASP Top 10)
+- ✅ Prevención de inyección SQL
+- ✅ Gestión de transacciones
+- ✅ Mapeos DTO
+- ✅ Mejores prácticas Spring Security
+
+**Frontend (React + Material-UI)**
+
+- ✅ Mejores prácticas de hooks React
+- ✅ Diseño de componentes y reusabilidad
+- ✅ Patrones de gestión de estado
+- ✅ Prevención XSS
+- ✅ Optimización de rendimiento
+- ✅ Accesibilidad (a11y)
+- ✅ Error boundaries
+
+**Fullstack (Spring Boot + React)**
+
+- ✅ **Consistencia de contrato API** (prioridad)
+- ✅ Flujo de datos (BD → API → UI)
+- ✅ Autenticación entre capas
+- ✅ Consistencia en manejo de errores
+- ✅ Todas las verificaciones backend
+- ✅ Todas las verificaciones frontend
+
+**Database (SQL Server)**
+
+- ✅ Riesgos de inyección SQL
+- ✅ UPDATE/DELETE sin WHERE
+- ✅ Índices faltantes
+- ✅ Rendimiento de consultas
+- ✅ Manejo de transacciones
+- ✅ Restricciones de integridad de datos
+
+**AI (Node.js + Claude)**
+
+- ✅ Mejores prácticas Claude API
+- ✅ Calidad de ingeniería de prompts
+- ✅ Experiencia de usuario CLI
+- ✅ Seguridad de operaciones Git
+- ✅ Compatibilidad multiplataforma
+- ✅ Protección de API key
+
+**Default (Propósito general)**
+
+- ✅ Fundamentos de calidad de código
+- ✅ Fundamentos de seguridad
+- ✅ Manejo de errores
+- ✅ Mejores prácticas por lenguaje
+- ✅ Mantenibilidad
+
+---
+
+##### ⚙️ Prioridad de Configuración
+
+```
+defaults (lib/config.js)
+  ↓
+user config (.claude/config.json)  ← General preferences
+  ↓
+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
 
 ```bash
@@ -148,60 +260,84 @@ git commit -m "fix: resolver issues"
 1. **Mensaje automático**: Usa `"auto"` como mensaje para que Claude lo genere
 2. **Skip auth**: Usa `--skip-auth` en CI/CD o desarrollo local
 3. **Force install**: Usa `--force` para reinstalar sin confirmación
-4. **Debug**: Activa `CLAUDE_DEBUG=true` para ver detalles completos
+4. **Debug**: Activa en `.claude/config.json`: `{"system": {"debug": true}}`
 5. **Archivos grandes**: Se omiten automáticamente archivos > 100KB
-6. **Límite de archivos**: Máximo 10 archivos por commit
+6. **Límite de archivos**: Máximo 10 archivos por commit (configurable)
 
-### 🚀 Parallel Analysis with Subagents (NEW in v1.5.5)
+### 🚀 Parallel Analysis (v2.2.0+)
 
-**When analyzing 3+ files**, enable subagents for faster parallel processing:
+**When analyzing 3+ files**, parallel execution runs multiple Claude CLI processes simultaneously for faster analysis:
 
 ```bash
-# Enable subagent parallel analysis
-export CLAUDE_USE_SUBAGENTS=true
-
-# Optional: Choose model (default: haiku for speed)
-export CLAUDE_SUBAGENT_MODEL=haiku    # Fast & cheap
-export CLAUDE_SUBAGENT_MODEL=sonnet   # Balanced quality/speed
-export CLAUDE_SUBAGENT_MODEL=opus     # Maximum quality
+# Configure in .claude/config.json
+{
+  "subagents": {
+    "enabled": true,
+    "model": "haiku",
+    "batchSize": 2
+  }
+}
+```
 
-# Optional: Adjust batch size (default: 3 files at a time)
-export CLAUDE_SUBAGENT_BATCH_SIZE=3
+**Model options:**
 
-# Now commits will use parallel analysis automatically
-git commit -m "feat: implement multiple features"
-```
+- `haiku` - Fast & cheap (default, recommended)
+- `sonnet` - Balanced quality/speed
+- `opus` - Maximum quality (slower)
 
 **How batching works:**
-- `BATCH_SIZE=1` with 4 files → 4 sequential batches (1 subagent each)
-- `BATCH_SIZE=3` with 4 files → 2 batches (3 parallel, then 1)
-- `BATCH_SIZE=4` with 4 files → 1 batch (all 4 in parallel)
-- Batch size is validated automatically (minimum: 1)
 
-**How it works:**
-- Each file is analyzed by a dedicated Claude subagent
-- Files are processed in batches for optimal performance
-- Results are consolidated automatically into single response
-- Shows execution time for all operations
-- Uses one-line prompt injection - no complex architecture changes
+- Files are split into batches of size `batchSize`
+- Each batch runs in a separate Claude CLI process
+- All batches execute in parallel (true OS-level parallelism)
+- Results are consolidated automatically
 
-**Best for:** Large commits (3+ files), refactoring tasks, feature branches
+**Examples with 4 files:**
+
+- `batchSize: 1` → 4 parallel Claude processes (1 file each) - **fastest**
+- `batchSize: 2` → 2 parallel Claude processes (2 files each) - **balanced**
+- `batchSize: 4` → 1 process (all files) - no parallelization
+
+**Speed improvement:**
+
+- Sequential: 60s per file × 4 = 240s total
+- Parallel (batch=1): max(60s) = 60s total ✅ **4x faster**
+
+**Console output:**
+
+```
+🚀 PARALLEL EXECUTION: 4 Claude processes
+  ⚡ Launching batch 1/4...
+  ⚡ Launching batch 2/4...
+  ⚡ Launching batch 3/4...
+  ⚡ Launching batch 4/4...
+  ⏳ Waiting for all batches to complete...
+
+✅ PARALLEL EXECUTION COMPLETE: 4 results in 62.5s
+```
+
+**Best for:** Large commits (3+ files), refactoring, multi-file features
 
 ### 🎨 Personalización y Customización
 
 **Archivos clave para modificar:**
+
+- `.claude/config.json` - Configuración principal (v2.2.0+)
 - `.claude/CLAUDE_PRE_COMMIT_SONAR.md` - Criterios (backend/frontend/data/db)
 - `.claude/CLAUDE_ANALYSIS_PROMPT_SONAR.md` - Template del prompt
-- `lib/hooks/pre-commit.js` - CONFIG object (extensiones, límites, umbrales)
 
-**Subagents (v1.5.5+)** - Para commits multi-archivo (3+), reduce análisis 60-70%:
+**Crear o modificar presets personalizados:**
+
 ```bash
-export CLAUDE_USE_SUBAGENTS=true      # Activar paralelo
-export CLAUDE_SUBAGENT_MODEL=haiku    # haiku/sonnet/opus
-export CLAUDE_SUBAGENT_BATCH_SIZE=3   # Archivos simultáneos
+# 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
 vim .claude/CLAUDE_PRE_COMMIT_SONAR.md  # Agregar reglas API REST/Spring Boot
 ```
@@ -268,9 +404,9 @@ El comando `claude-hooks install` crea los siguientes archivos y directorios:
 2. **`.git/hooks/prepare-commit-msg`** - Hook de generación de mensajes
 3. **`.git/hooks/check-version.sh`** - Script de verificación de versión
 4. **`.claude/`** - Directorio para archivos de configuración
-   - `CLAUDE_PRE_COMMIT_SONAR.md` - Pautas de evaluación SonarQube
-   - `CLAUDE_ANALYSIS_PROMPT_SONAR.md` - Template de prompt para análisis SonarQube
-   - `CLAUDE_RESOLUTION_PROMPT.md` - Template para prompt de resolución AI
+    - `CLAUDE_PRE_COMMIT_SONAR.md` - Pautas de evaluación SonarQube
+    - `CLAUDE_ANALYSIS_PROMPT_SONAR.md` - Template de prompt para análisis SonarQube
+    - `CLAUDE_RESOLUTION_PROMPT.md` - Template para prompt de resolución AI
 
 ### Actualización automática de .gitignore
 
@@ -298,21 +434,21 @@ Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas s
 
 1. **Intercepta cada intento de commit**
 2. **Extrae y filtra archivos modificados**:
-   - Solo analiza: Java, XML, properties, yml, yaml
-   - Omite archivos mayores a 100KB
-   - Límite de 10 archivos por commit
+    - Solo analiza: Java, XML, properties, yml, yaml
+    - Omite archivos mayores a 100KB
+    - Límite de 10 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`
-   - Incluye el diff completo para archivos nuevos
-   - Muestra solo cambios para archivos existentes
+    - Usa template de prompt desde `.claude/CLAUDE_ANALYSIS_PROMPT*.md`
+    - Lee las pautas desde `.claude/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**
 5. **Procesa respuesta JSON estructurada**:
-   - blockingIssues siempre como objetos con localización precisa
-   - verifica `QUALITY_GATE`, muestra métricas y issues por severidad
+    - blockingIssues siempre como objetos con localización precisa
+    - verifica `QUALITY_GATE`, muestra métricas y issues por severidad
 6. **Decisión final**:
-   - Si hay problemas críticos → genera prompt AI de resolución y bloquea commit
-   - Si todo está bien → commit procede
+    - Si hay problemas críticos → genera prompt AI de resolución y bloquea commit
+    - Si todo está bien → commit procede
 7. **Generación de Prompt de Resolución AI** (opcional): Cuando se detectan problemas críticos:
 
 - Se genera automáticamente un archivo `claude_resolution_prompt.md`
@@ -323,28 +459,28 @@ Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas s
 ### Hook prepare-commit-msg (Generación automática de mensajes)
 
 1. **Se activa cuando el mensaje es**:
-   - `"auto"`
+    - `"auto"`
 2. **Analiza los cambios del staging area**:
-   - Lista archivos modificados con estadísticas
-   - Incluye diffs completos para archivos < 100KB
+    - Lista archivos modificados con estadísticas
+    - Incluye diffs completos para archivos < 100KB
 3. **Genera mensaje en formato Conventional Commits**:
-   - Determina tipo: feat, fix, docs, style, refactor, test, chore
-   - Crea título conciso y descriptivo
-   - Añade body con detalles si es necesario
+    - Determina tipo: feat, fix, docs, style, refactor, test, chore
+    - Crea título conciso y descriptivo
+    - Añade body con detalles si es necesario
 4. **Manejo de errores**:
-   - Si falla la generación → cancela el commit completamente
-   - No usa mensajes genéricos de fallback
+    - Si falla la generación → cancela el commit completamente
+    - No usa mensajes genéricos de fallback
 
 ### Características adicionales
 
 - **Generación de información para Pull Requests**: `claude-hooks analyze-diff [branch]` para comparar rama local con rama origin, propone nombre para rama actual, título y detalles para pull request, da tips para verificar trabajo. Si se especifica branch, compara con origin/branch. Si no, compara con origin de la rama actual. Este comando genera automáticamente:
-  - 📝 Título de PR conciso (máx. 72 caracteres)
-  - 📄 Descripción detallada con markdown
-  - 🌿 Nombre de rama sugerido (formato: tipo/descripcion)
-  - 📋 Tipo de cambio (feature/fix/refactor/docs/test/chore)
-  - ⚠️ Indicador de breaking changes
-  - 🧪 Notas de testing recomendado
-  - 📝 Archivo `.claude-pr-analysis.json`
+    - 📝 Título de PR conciso (máx. 72 caracteres)
+    - 📄 Descripción detallada con markdown
+    - 🌿 Nombre de rama sugerido (formato: tipo/descripcion)
+    - 📋 Tipo de cambio (feature/fix/refactor/docs/test/chore)
+    - ⚠️ Indicador de breaking changes
+    - 🧪 Notas de testing recomendado
+    - 📝 Archivo `.claude-pr-analysis.json`
 - **Auto-actualización**: Verificación automática de versiones antes de cada commit con prompt interactivo para actualizar
 - **Comando update**: `claude-hooks update` para actualizar manualmente a la última versión
 - **Modo debug**: `DEBUG=1 git commit` guarda respuestas en `debug-claude-response.json`
@@ -432,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)
@@ -464,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