claude-git-hooks/README.md

Git hooks with Claude CLI for code analysis and automatic commit messages

# Pre-commit Hook con Claude CLI

🚀 **Transforma tu flujo de desarrollo con IA**: análisis de código instantáneo, mensajes de commit automáticos y generación de PRs perfectas. Claude revisa tu código antes de cada commit, detecta issues críticos con análisis estructurado, y genera toda la documentación que necesitas. ¿Lo mejor? Se ejecuta localmente sin contaminar tu CI/CD.

## ✨ Novedad v2.7.1 - Improved Reliability

**Nuevo v2.7.1**: Sistema de reintentos automáticos para errores transitorios de Claude API. Cuando Claude devuelve "Execution error" (típicamente por rate limiting), el sistema ahora reintenta automáticamente después de 2 segundos.

## ✨ 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
- ✅ **Worktrees** - Compatible con git worktrees en cualquier entorno
- ✅ **IDEs** - Compatible con git manager de IntelliJ and VSCode -> mensaje de commit "auto" committea (y pushea si se quiere) con mensaje automático. Si el commit tiene problemas, se bloquea.

## 🎯 Características principales

- 🔍 **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 con task-id (Jira, GitHub, Linear)
- 📋 **Generación de PRs**: Análisis de diff y metadata automática con un comando
- 🔗 **Creación de PRs en GitHub**: Claude genera metadata, Octokit crea el PR (determinista) - v2.5.0+
- 🎯 **Presets por tech-stack**: 6 configuraciones optimizadas (backend, frontend, fullstack, database, ai, default) - v2.3.0+
- 🚀 **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
- ♻️ **Reintentos automáticos**: Recuperación automática de errores transitorios de API (v2.7.1+)

## 📋 CHEATSHEET

### 🚀 Comandos Frecuentes

```bash
# Commit rápido sin análisis + mensaje automático
git commit --no-verify -m "auto"

# Analizar diferencias con origin de la rama actual
claude-hooks analyze-diff

# Analizar diferencias para PR (comparar con origin/develop)
claude-hooks analyze-diff develop

# Crear PR en GitHub con metadata automática (v2.5.0+)
claude-hooks create-pr develop

# Configurar token de GitHub para PRs (v2.5.0+)
claude-hooks setup-github

# 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

# Activar modo debug
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

✨ **v2.0.0+**: Funciona terminales WSL y Bash.

Se debe instalar el paquete globalmente, para luego gestionarlo localmente en cada repositorio.

```bash
# Instalar globalmente (desde cualquier terminal)
npm install -g claude-git-hooks

# Luego en cada proyecto
cd /tu/proyecto
claude-hooks install

# Actualizar a última versión
claude-hooks update

# Desinstalar hooks
claude-hooks uninstall

# Ver estado actual
claude-hooks status

# Desactivar temporalmente
claude-hooks disable

# Reactivar hooks
claude-hooks enable
```

### 💻 Flujos de Commit

```bash
# Commit con análisis de código
git commit -m "feat: nueva funcionalidad"

# Generar mensaje automático con task-id (v2.5.0+)
# Branch: feature/IX-123-add-auth → detecta IX-123
git commit -m "auto"
# Resultado: [IX-123] feat: add user authentication

# Branch: feature/471459f-test → NO detecta (hash, no task-id)
git commit -m "auto"
# Resultado: feat: add test feature (sin task-id)

# Saltar análisis (emergencias)
git commit --no-verify -m "hotfix: corrección urgente"

# Modificar último commit
git commit --amend
```

## 🚀 Quick Setup: GitHub PR Creation

Para usar `create-pr` necesitas configurar autenticación con GitHub:

### 1. Ejecuta el setup wizard

```bash
claude-hooks setup-github
```

El comando verificará tu token o te guiará a configurarlo.

### 2. Opciones de configuración del token

**Opción A - Settings local (recomendado):**

```bash
# Crear .claude/settings.local.json
cat > .claude/settings.local.json << 'EOF'
{
  "githubToken": "ghp_tu_token_aqui"
}
EOF
```

**Opción B - Variable de entorno:**

```bash
export GITHUB_TOKEN="ghp_tu_token_aqui"
# o
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_tu_token_aqui"
```

**Opción C - Claude Desktop config** (auto-detectado si existe)

### 3. Crear GitHub token

1. Ir a https://github.com/settings/tokens
2. "Generate new token (classic)"
3. Scopes requeridos: **repo** (all) + **read:org**
4. Copiar token (empieza con `ghp_`)

### 4. Configurar reviewers y labels (opcional)

```bash
# Ver .claude/config_example/ para más ejemplos
cat > .claude/config.json << 'EOF'
{
  "version": "2.8.0",
  "preset": "backend",
  "overrides": {
    "github": {
      "pr": {
        "defaultBase": "develop",
        "reviewers": ["tu-usuario-github", "teammate"],
        "labelRules": {
          "backend": ["backend", "java"],
          "frontend": ["frontend", "react"]
        }
      }
    }
  }
}
EOF
```

**Nota:** Los reviewers también se detectan automáticamente desde CODEOWNERS si existe.

### 5. Crear tu primer PR

```bash
git checkout -b feature/mi-feature
# ... hacer cambios ...
git add .
git commit -m "feat: nueva funcionalidad"
git push -u origin feature/mi-feature

# Crear PR
claude-hooks create-pr develop
```

**Arquitectura:** Claude analiza el diff y genera metadata (título, descripción, reviewers, labels) → Octokit crea el PR de forma determinista.

Ver `templates/config.github.example.json` para configuración avanzada (reviewer rules por path, custom labels, etc.).

---

## 📆 Próximos Desarrollos

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.8.0+)

```bash
# Configuración vía .claude/config.json (v2.8.0+)
.claude/
├── 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",
  "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
# No detecta: 471459f (hash), ABCD-123 (4 letras), IX-12 (2 dígitos)
```

#### 🎯 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
# Desarrollo local de claude-hooks
cd /path/to/claude-git-hooks
npm link
cd /path/to/your-project
claude-hooks install --force --skip-auth

# Preparar PR hacia develop
git checkout -b feature/nueva-funcionalidad
# ... hacer cambios ...
git add .
git commit -m "feat: implementar nueva funcionalidad"
claude-hooks analyze-diff develop  # Genera título, descripción y tests

# Resolver issues bloqueantes
git commit -m "fix: resolver issues"
# Si falla, ver claude_resolution_prompt.md generado
# Copiar contenido y pegar en Claude para obtener solución
```

### ⚡ 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_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`
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.

**Configuración automática (hardcoded):**
- ✅ **Enabled**: `true` (siempre activo)
- ⚡ **Model**: `haiku` (rápido y económico)
- 📦 **BatchSize**: `3` files per batch (puede overridearse)

**Customizar batch size (opcional):**

```bash
# En .claude/config.json v2.8.0
{
  "version": "2.8.0",
  "preset": "backend",
  "overrides": {
    "subagents": {
      "batchSize": 2
    }
  }
}
```

**Model options (solo en config avanzado):**

- `haiku` - Fast & cheap (default)
- `sonnet` - Balanced quality/speed
- `opus` - Maximum quality (slower)

**How batching works:**

- 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

**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.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:**

```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
vim .claude/prompts/CLAUDE_PRE_COMMIT.md  # Agregar reglas API REST/Spring Boot
```

## 🔧 Configuración Previa Importante

### Requisitos del Sistema

✨ **v2.0.0+**: Los hooks funcionan en cualquier terminal donde tengas:

- **Node.js** >= 16.9.0
- **Git** configurado
- **Claude CLI** instalado y autenticado

🆕 **v2.6.0+**: Totalmente compatible con Node.js 24

### Credenciales Git

Si es tu primera vez configurando git en esta terminal, configura tus credenciales:

```bash
git config --global user.name "Tu Nombre"
git config --global user.email "tu.email@ejemplo.com"

# Si usas credential helper (opcional)
git config --global credential.helper store
```

## 🚀 Instalación

✨ **v2.0.0+**: Instalación cross-platform. Funciona en PowerShell, CMD, WSL, macOS Terminal, Linux shell.

```bash
# Instalar el paquete globalmente
npm install -g claude-git-hooks

# En cualquier repositorio, instalar los hooks
cd tu-proyecto
claude-hooks install
```

El comando `claude-hooks install` incluye:

- ✅ Verificación completa de dependencias del sistema (Node.js, Git, Claude CLI)
- ✅ Verificación de autenticación Claude con entretenimiento (omitible con `--skip-auth`)
- ✅ Instalación de hooks con arquitectura bash wrapper + Node.js
- ✅ Instalación de archivos de pautas y templates
- ✅ Actualización automática de .gitignore con archivos de Claude

**Nuevo en v2.0.0 - Soporte Cross-Platform:**

Auto-detecta plataforma, convierte CRLF→LF en install, busca Claude en WSL (Windows), instala bash wrappers que convierten rutas C:\ a /c/

**Opciones de instalación:**

- `--force`: Reinstala aunque los hooks ya existan
- `--skip-auth`: Omite la verificación de autenticación de Claude (útil para CI/CD)

## 📁 Gestión de Archivos

### Archivos creados durante la instalación

El comando `claude-hooks install` crea los siguientes archivos y directorios:

1. **`.git/hooks/pre-commit`** - Hook de análisis de código
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.md` - Criterios de evaluación de calidad
    - `CLAUDE_ANALYSIS_PROMPT.md` - Template de prompt para análisis
    - `CLAUDE_RESOLUTION_PROMPT.md` - Template para prompt de resolución AI

### Actualización automática de .gitignore

Durante la instalación, Claude Hooks actualiza automáticamente tu `.gitignore` para incluir:

```gitignore
# Claude Git Hooks
.claude/
```

Esto asegura que:

- Los archivos de configuración de Claude específicos del proyecto no se suban al repositorio
- Los archivos de debug temporales se ignoren
- Cada desarrollador pueda tener sus propias preferencias de análisis

Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas se agregarán al final solo si no están presentes.

## 🎯 Funcionamiento

### Hook pre-commit (Análisis de código)

1. **Intercepta cada intento de commit**
2. **Extrae y filtra archivos modificados**:
    - Solo analiza: Java, XML, properties, yml, yaml
    - Omite archivos mayores a 1MB
    - Límite de 30 archivos por commit
3. **Construye prompt inteligente**:
    - 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**
5. **Procesa respuesta JSON estructurada**:
    - 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
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`
- Contiene información estructurada y AI-friendly de todos los issues
- Incluye localización precisa (archivo, línea, método)
- Puede copiarse a otra instancia de Claude para resolución automática

### Hook prepare-commit-msg (Generación automática de mensajes)

1. **Se activa cuando el mensaje es**:
    - `"auto"`
2. **Analiza los cambios del staging area**:
    - Lista archivos modificados con estadísticas
    - Incluye diffs completos para archivos < 1MB
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
4. **Manejo de errores**:
    - 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`
- **Creación de PRs en GitHub (v2.5.0+)**: `claude-hooks create-pr [branch]` crea pull requests directamente en GitHub vía MCP. Extrae task-id de branch, genera metadata con Claude, detecta reviewers desde CODEOWNERS o config, aplica labels por preset, y muestra preview interactivo antes de crear
- **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**: `claude-hooks --debug true` activa logging detallado para troubleshooting
- **Análisis de PR**: Nuevo comando `analyze-diff` para generar información de Pull Requests
- **Validación de dependencias**: Verifica que Claude CLI esté autenticado antes de ejecutar

### Desactivar/Activar hooks

```bash
# Desactivar todos los hooks
claude-hooks disable

# Desactivar un hook específico
claude-hooks disable pre-commit
claude-hooks disable prepare-commit-msg

# Habilitar todos los hooks
claude-hooks enable

# Habilitar un hook específico
claude-hooks enable pre-commit
claude-hooks enable prepare-commit-msg

# Ver estado actual
claude-hooks status
```

## ⚙️ Configuración

### Scripts

✨ **v2.0.0+**: Configuración en archivos Node.js dentro de `lib/hooks/`.

En `lib/hooks/pre-commit.js`:

- **`MAX_FILE_SIZE`**: Tamaño máximo de archivo a analizar (default: 1MB)
- **`MAX_FILES`**: Número máximo de archivos por commit (default: 30)
- **`ALLOWED_EXTENSIONS`**: Extensiones permitidas (default: .java, .xml, .properties, .yml, .yaml)

En `lib/hooks/prepare-commit-msg.js`:

- **`MAX_FILE_SIZE`**: Tamaño máximo para incluir diff completo (default: 1MB)

### Pautas de Evaluación

- **`CLAUDE_PRE_COMMIT.md`** - Criterios de evaluación de calidad

### Templates de Prompts

- **`CLAUDE_ANALYSIS_PROMPT.md`** - Estructura del prompt de análisis
- **`CLAUDE_RESOLUTION_PROMPT.md`** - Template para generar prompts de resolución

Todos estos archivos son personalizables y específicos de tu proyecto. Puedes:

- Modificar los criterios de evaluación según estándares del equipo
- Ajustar la estructura de los prompts para obtener respuestas más precisas
- Personalizar el formato de salida del prompt de resolución

## 🐛 Troubleshooting

No hay... esto es la perfección hecha código.

## 🔧 Desarrollo y Contribución

### Estructura del Proyecto

✨ **v2.0.0+**: Nueva arquitectura modular con ES6 modules.

```
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-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
│       ├── preset-loader.js                  # Cargador de presets
│       ├── installation-diagnostics.js       # Diagnósticos de instalación
│       ├── claude-diagnostics.js             # Diagnósticos de errores Claude CLI
│       ├── github-api.js                     # 🆕 Integración Octokit (determinista)
│       ├── github-client.js                  # Cliente GitHub (CODEOWNERS, reviewers)
│       ├── task-id.js                        # Extracción task-id (Jira, GitHub, Linear)
│       ├── interactive-ui.js                 # UI interactiva CLI (preview, prompts)
│       └── mcp-setup.js                      # Setup y detección MCP
├── 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)
│   ├── check-version.sh                      # Script de verificación de versión
│   ├── CLAUDE_PRE_COMMIT.md            # Criterios de evaluación
│   ├── CLAUDE_ANALYSIS_PROMPT.md       # Template de prompt para análisis
│   ├── CLAUDE_RESOLUTION_PROMPT.md           # Template para resolución de issues
│   ├── ANALYZE_DIFF.md                       # Template para análisis de diff (PR metadata)
│   ├── CREATE_GITHUB_PR.md                   # Template para creación de PR
│   ├── config.github.example.json            # 🆕 Ejemplo configuración GitHub
│   └── settings.local.example.json           # 🆕 Ejemplo token local (gitignored)
├── test/                                     # 🆕 Tests unitarios con Jest
│   └── unit/
│       └── logger.test.js                    # Tests del logger
├── .claude/                                  # Directorio de configuración local (gitignore)
│   └── settings.local.json                   # Configuración local del usuario
├── jest.config.js                            # 🆕 Configuración Jest para ES6
├── .eslintrc.json                            # 🆕 Configuración ESLint
├── .prettierrc.json                          # 🆕 Configuración Prettier
├── package.json                              # Configuración NPM (type: "module")
├── package-lock.json                         # Lock file de NPM
├── README.md                                 # Este archivo
├── CHANGELOG.md                              # Historial de versiones
└── .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      |
| **`github-api.js`**               | Octokit GitHub integration            | `createPullRequest()`, `readCodeowners()`         | Deterministic PR creation, token resolution    |
| **`github-client.js`**            | GitHub operations                     | `getReviewersForFiles()`, `parseGitHubRepo()`     | CODEOWNERS parsing, reviewer detection         |
| **`task-id.js`**                  | Task ID extraction                    | `getOrPromptTaskId()`, `formatWithTaskId()`       | Jira, GitHub, Linear task-id extraction        |
| **`interactive-ui.js`**           | Interactive CLI components            | `showPRPreview()`, `promptConfirmation()`         | Terminal UI helpers (spinners, menus)          |
| **`mcp-setup.js`**                | MCP detection and setup               | `findGitHubTokenInDesktopConfig()`                | Claude Desktop config token resolution         |

#### 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
# 1. Clonar el repositorio
git clone https://github.com/pablorovito/claude-git-hooks.git
cd claude-git-hooks

# 2. Instalar dependencias (si las hubiera)
npm install

# 3. Enlazar para desarrollo local
npm link

# 4. Probar en un repositorio de prueba
cd /path/to/test-repo
claude-hooks install
```

### Workflow de Desarrollo

#### 1. Modificar Hooks

✨ **v2.0.0+**: La lógica de los hooks está en `lib/hooks/`:

- `lib/hooks/pre-commit.js` - Lógica de análisis de código (Node.js ES6)
- `lib/hooks/prepare-commit-msg.js` - Lógica de generación de mensajes (Node.js ES6)
- `templates/pre-commit` - Bash wrapper que llama al script Node.js
- `templates/prepare-commit-msg` - Bash wrapper que llama al script Node.js

#### 2. Probar Localmente

```bash
# Después de modificar archivos, repo de claude-hooks
npm link

# En un repo de prueba
claude-hooks install --force  # Fuerza reinstalación, luego probar lo que se desee
```

#### 3. Actualizar Documentación

- `README.md` - Documentación principal
- `CHANGELOG.md` - Documentación principal
- `README-NPM.md` - Para usuarios de NPM

#### 4. Versioning y Publicación

```bash
# Actualizar versión
npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0

# Publicar nueva versión
npm publish
```