claude-git-hooks 2.4.1 → 2.5.0

package/README.md

@@ -15,10 +15,10 @@
 ## 🎯 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
-- 📋 **Generación de PRs**: Título, descripción y tests sugeridos con un solo comando
+- 💬 **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+
-- ⚠️ **Skip inteligente** (EXPERIMENTAL/BROKEN): Exclusión de código con comentarios SKIP_ANALYSIS - no funciona correctamente con git diff
 - 🚀 **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 +37,12 @@ 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
 
@@ -92,8 +98,14 @@ claude-hooks enable
 # Commit con análisis de código
 git commit -m "feat: nueva funcionalidad"
 
-# Generar mensaje de commit automático
+# 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"
@@ -102,27 +114,93 @@ git commit --no-verify -m "hotfix: corrección urgente"
 git commit --amend
 ```
 
-## 📆 Próximos Desarrollos
+## 🚀 Quick Setup: GitHub PR Creation
 
-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.
+Para usar `create-pr` necesitas configurar autenticación con GitHub:
 
-### ⚠️ Exclusión de Código del Análisis (EXPERIMENTAL/BROKEN)
+### 1. Ejecuta el setup wizard
 
-```java
-// NOTA: Este feature NO funciona correctamente
-// Los marcadores no son detectados si fueron agregados en commits anteriores
+```bash
+claude-hooks setup-github
+```
+
+El comando verificará tu token o te guiará a configurarlo.
+
+### 2. Opciones de configuración del token
 
-// SKIP_ANALYSIS_LINE
-private String legacyCode = "no analizar siguiente línea";
+**Opción A - Settings local (recomendado):**
 
-// SKIP_ANALYSIS_BLOCK
-public void methodToIgnore() {
-    // Todo este bloque será ignorado
-    String oldCode = "legacy";
+```bash
+# Crear .claude/settings.local.json
+cat > .claude/settings.local.json << 'EOF'
+{
+  "githubToken": "ghp_tu_token_aqui"
 }
-// SKIP_ANALYSIS_BLOCK
+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 templates/config.github.example.json para formato completo
+cat > .claude/config.json << 'EOF'
+{
+  "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.2.0+)
 
 ```bash
@@ -143,7 +221,8 @@ cat > .claude/config.json << 'EOF'
   },
   "commitMessage": {
     "autoKeyword": "auto",
-    "timeout": 180000
+    "timeout": 180000,
+    "taskIdPattern": "([A-Z]{1,3}[-\\s]\\d{3,5})"
   },
   "subagents": {
     "enabled": true,
@@ -155,6 +234,11 @@ cat > .claude/config.json << 'EOF'
   }
 }
 EOF
+
+# 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
@@ -267,12 +351,13 @@ git commit -m "fix: resolver issues"
 
 ### ⚡ Tips y Trucos
 
-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 con `claude-hooks --debug true` o en `.claude/config.json`: `{"system": {"debug": true}}`
-5. **Archivos grandes**: Se omiten automáticamente archivos > 1MB
-6. **Límite de archivos**: Máximo 30 archivos por commit (configurable)
+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`
+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)
 
 ### 🚀 Parallel Analysis (v2.2.0+)
 
@@ -488,25 +573,12 @@ Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas s
     - ⚠️ 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
-- **⚠️ Exclusión de código del análisis (EXPERIMENTAL/BROKEN)**: Los marcadores `// SKIP_ANALYSIS_LINE` y `// SKIP_ANALYSIS_BLOCK` no funcionan correctamente. El hook analiza git diff en lugar del archivo completo, por lo que marcadores agregados en commits anteriores no son detectados en cambios subsecuentes.
-
-```java
-// NOTA: Este feature actualmente NO funciona de forma confiable
-// SKIP_ANALYSIS_LINE
-@Autowired private LegacyService legacyService;
-
-// SKIP_ANALYSIS_BLOCK
-@Deprecated
-public void methodWithKnownIssues() {
-    System.out.println("Legacy code");
-}
-// SKIP_ANALYSIS_BLOCK
-```
 
 ### Desactivar/Activar hooks
 
@@ -588,14 +660,23 @@ claude-git-hooks/
 │       ├── 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
+│       ├── 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_SONAR.md            # Pautas SonarQube
 │   ├── CLAUDE_ANALYSIS_PROMPT_SONAR.md       # Template de prompt para análisis
-│   └── CLAUDE_RESOLUTION_PROMPT.md           # Template para resolución de issues
+│   ├── 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
@@ -629,6 +710,11 @@ claude-git-hooks/
 | **`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