claude-git-hooks 2.4.0 → 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,23 +114,93 @@ git commit --no-verify -m "hotfix: corrección urgente"
 git commit --amend
 ```
 
-### ⚠️ Exclusión de Código del Análisis (EXPERIMENTAL/BROKEN)
+## 🚀 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.
 
-```java
-// NOTA: Este feature NO funciona correctamente
-// Los marcadores no son detectados si fueron agregados en commits anteriores
+### 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
@@ -139,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,
@@ -151,18 +234,23 @@ 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
 
-| 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             |
+| 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             |
 
 ---
 
@@ -263,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+)
 
@@ -421,9 +510,6 @@ Durante la instalación, Claude Hooks actualiza automáticamente tu `.gitignore`
 ```gitignore
 # Claude Git Hooks
 .claude/
-debug-claude-response.json
-claude_resolution_prompt.md
-.claude-pr-analysis.json
 ```
 
 Esto asegura que:
@@ -487,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
 
@@ -587,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
@@ -616,34 +698,41 @@ claude-git-hooks/
 
 #### 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 |
+| 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
+    // ... operation that may fail
 } catch (error) {
-  console.error(formatError('Operation failed', ['Additional context line']));
-  process.exit(1);
+    console.error(formatError('Operation failed', ['Additional context line']));
+    process.exit(1);
 }
 ```
 
 **Example: Load configuration**
+
 ```javascript
 import { getConfig } from './lib/config.js';
 
@@ -652,6 +741,7 @@ const maxFiles = config.analysis.maxFiles;
 ```
 
 **Example: Execute git operations**
+
 ```javascript
 import { getRepoRoot, getStagedFiles } from './lib/utils/git-operations.js';
 
@@ -660,13 +750,14 @@ 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' }
+    templateName: 'CUSTOM_PROMPT.md',
+    files: filesData,
+    metadata: { REPO_NAME: 'my-repo' }
 });
 ```