claude-agent-framework 1.0.0

package/framework/commands/debug.md

@@ -0,0 +1,334 @@
+# Comando: /debug
+
+Analiza errores y ayuda a depurar problemas en la aplicación.
+
+## Uso
+
+```
+/debug [descripción del error | "logs" | "performance"]
+```
+
+## Parámetros
+
+- Sin argumentos: pregunta qué tipo de problema hay
+- `descripción`: analiza el stack trace o error específico
+- `logs`: revisa logs recientes e identifica patrones de error
+- `performance`: ejecuta profiling e identifica problemas de rendimiento
+
+## Flujo de trabajo
+
+### Paso 1: Identificar el tipo de problema
+
+Sin argumentos, preguntar:
+
+"¿Qué tipo de problema estás experimentando?"
+
+Opciones:
+- Un error específico (pega el mensaje o stack trace)
+- La app va lenta
+- Algo no funciona como esperaba
+- Quiero revisar los logs
+
+### Paso 2: Según el tipo de problema
+
+#### Para errores específicos
+
+1. **Analizar el stack trace**
+   ```bash
+   # Extraer información clave
+   # - Archivo y línea donde ocurre
+   # - Tipo de excepción
+   # - Mensaje de error
+   # - Contexto (controlador, modelo, vista)
+   ```
+
+2. **Identificar la causa probable**
+   - Error de sintaxis
+   - Nil reference (NoMethodError on nil)
+   - Base de datos (ActiveRecord errors)
+   - Routing
+   - Validación
+   - Autorización
+
+3. **Buscar el código relacionado**
+   ```bash
+   # Leer el archivo mencionado en el stack trace
+   # Verificar el contexto alrededor de la línea
+   ```
+
+4. **Proponer solución**
+   - Explicar qué está pasando en lenguaje simple
+   - Mostrar el código problemático
+   - Proponer corrección con ejemplo
+
+#### Para `/debug logs`
+
+1. **Revisar logs recientes**
+   ```bash
+   # Ver últimas líneas del log de desarrollo
+   tail -100 log/development.log
+
+   # Buscar errores
+   grep -i "error\|exception\|fail" log/development.log | tail -50
+
+   # Ver requests fallidos
+   grep "500\|422\|404" log/development.log | tail -20
+   ```
+
+2. **Identificar patrones**
+   - Errores repetidos
+   - Queries lentas
+   - Excepciones no manejadas
+   - Problemas de memoria
+
+3. **Generar reporte**
+   ```markdown
+   ## Análisis de Logs
+
+   ### Errores encontrados
+   | Error | Frecuencia | Última vez |
+   |-------|------------|------------|
+   | [Error 1] | X veces | [timestamp] |
+
+   ### Warnings
+   - [Warning 1]
+
+   ### Recomendaciones
+   1. [Acción 1]
+   2. [Acción 2]
+   ```
+
+#### Para `/debug performance`
+
+1. **Ejecutar análisis**
+   ```bash
+   # Identificar N+1 queries en desarrollo
+   # El bullet gem detecta esto automáticamente
+
+   # Ver queries lentas
+   grep "ms)" log/development.log | sort -t'(' -k2 -rn | head -20
+   ```
+
+2. **Analizar código**
+   - Buscar `each` sin `includes`
+   - Identificar queries en loops
+   - Verificar índices en la base de datos
+   - Revisar uso de memoria
+
+3. **Generar reporte de rendimiento**
+   ```markdown
+   ## Análisis de Rendimiento
+
+   ### N+1 Queries Detectadas
+   1. **[Ubicación]**
+      - Problema: [Descripción]
+      - Solución: `includes(:asociacion)`
+
+   ### Queries Lentas
+   | Query | Tiempo | Ubicación |
+   |-------|--------|-----------|
+   | [Query] | Xms | [archivo:línea] |
+
+   ### Índices Faltantes
+   - Tabla `X`, columna `Y`
+
+   ### Recomendaciones
+   1. [Mejora 1]
+   2. [Mejora 2]
+   ```
+
+### Paso 3: Proporcionar solución
+
+Para cada problema identificado:
+
+1. **Explicar el problema**
+   - Qué está pasando
+   - Por qué está pasando
+   - Impacto (crítico/medio/bajo)
+
+2. **Mostrar la solución**
+   ```ruby
+   # ❌ Antes (código problemático)
+   [código actual]
+
+   # ✅ Después (código corregido)
+   [código sugerido]
+   ```
+
+3. **Ofrecer implementar**
+   "¿Quieres que aplique esta corrección?"
+
+## Errores comunes y soluciones
+
+### NoMethodError: undefined method for nil:NilClass
+
+```ruby
+# ❌ Problema
+user.profile.name  # user.profile es nil
+
+# ✅ Solución 1: Safe navigation
+user.profile&.name
+
+# ✅ Solución 2: Verificación
+user.profile.name if user.profile.present?
+
+# ✅ Solución 3: Default
+user.profile&.name || "Sin nombre"
+```
+
+### ActiveRecord::RecordNotFound
+
+```ruby
+# ❌ Problema
+@article = Article.find(params[:id])  # Lanza excepción si no existe
+
+# ✅ Solución 1: find_by (retorna nil)
+@article = Article.find_by(id: params[:id])
+return head :not_found unless @article
+
+# ✅ Solución 2: Manejo de excepción
+rescue ActiveRecord::RecordNotFound
+  redirect_to articles_path, alert: "Artículo no encontrado"
+```
+
+### ActionController::ParameterMissing
+
+```ruby
+# ❌ Problema
+params.require(:article)  # :article no está en params
+
+# ✅ Solución
+# Verificar que el formulario envía correctamente
+# o hacer el parámetro opcional
+params.fetch(:article, {})
+```
+
+### N+1 Query
+
+```ruby
+# ❌ Problema
+Article.all.each do |article|
+  puts article.user.name  # Una query por cada artículo
+end
+
+# ✅ Solución
+Article.includes(:user).each do |article|
+  puts article.user.name  # Una sola query
+end
+```
+
+### Rollback en validaciones
+
+```ruby
+# ❌ Problema
+# Transaction rolled back - pero no sabes por qué
+
+# ✅ Solución: Ver errores
+article = Article.new(params)
+unless article.save
+  puts article.errors.full_messages
+end
+
+# O usar save! para ver la excepción
+article.save!  # Lanza ActiveRecord::RecordInvalid con detalles
+```
+
+## Herramientas de debugging
+
+### Rails Console
+
+```ruby
+# Iniciar consola
+bin/rails console
+
+# Recargar código
+reload!
+
+# Ver SQL generado
+Article.where(published: true).to_sql
+
+# Debugear objeto
+article.inspect
+article.attributes
+
+# Ver errores de validación
+article.valid?
+article.errors.full_messages
+```
+
+### Byebug/Debug
+
+```ruby
+# Añadir breakpoint en el código
+debugger  # Rails 7+
+byebug    # Gem byebug
+
+# Comandos en el debugger
+n         # next (siguiente línea)
+s         # step (entrar en método)
+c         # continue
+p variable # print variable
+```
+
+### Logs mejorados
+
+```ruby
+# En cualquier parte del código
+Rails.logger.debug "Variable: #{variable.inspect}"
+Rails.logger.info "Llegamos aquí"
+Rails.logger.error "Algo salió mal: #{error.message}"
+```
+
+## Checklist de debugging
+
+- [ ] ¿Leí el mensaje de error completo?
+- [ ] ¿Identifiqué el archivo y línea del error?
+- [ ] ¿Revisé el contexto alrededor del error?
+- [ ] ¿Busqué el error en Google/Stack Overflow?
+- [ ] ¿Reproduje el error localmente?
+- [ ] ¿Aislé el problema (comentando código)?
+- [ ] ¿Usé breakpoints para inspeccionar el estado?
+- [ ] ¿Verifiqué los datos de entrada?
+- [ ] ¿Revisé los logs?
+- [ ] ¿Probé la solución con tests?
+
+## Ejemplo de salida
+
+```
+🔍 Analizando el error...
+
+📍 Ubicación: app/controllers/articles_controller.rb:25
+
+🐛 Error: NoMethodError: undefined method 'name' for nil:NilClass
+
+📋 Contexto:
+   El error ocurre cuando intentas acceder a `@article.user.name`
+   pero el artículo no tiene un usuario asociado (user_id es nil).
+
+💡 Causa probable:
+   - El artículo se creó sin asociar un usuario
+   - El usuario fue eliminado pero el artículo permanece
+
+🔧 Solución sugerida:
+
+   # En app/controllers/articles_controller.rb línea 25
+   # Cambiar:
+   @article.user.name
+
+   # Por:
+   @article.user&.name || "Usuario desconocido"
+
+   # O mejor, arreglar el modelo:
+   # app/models/article.rb
+   validates :user, presence: true
+
+¿Quieres que aplique esta corrección?
+```
+
+## Notas importantes
+
+- No modificar código de producción sin entender el problema
+- Siempre reproducir el error antes de corregir
+- Los tests deben pasar después de la corrección
+- Documentar bugs significativos para evitar repetirlos
+- Explicar en lenguaje simple qué pasó y cómo se resolvió

package/framework/commands/deploy.md

@@ -0,0 +1,383 @@
+# Comando: /deploy
+
+## Descripción
+
+Despliega la aplicación a producción de forma guiada y segura.
+
+## Uso
+
+```
+/deploy [entorno]
+```
+
+## Parámetros
+
+- `entorno` (opcional): "staging" o "production" (default: production)
+
+## Proceso de deploy
+
+### 1. Pre-checks
+
+Antes de desplegar, verificar:
+
+```bash
+# Estado del repositorio
+git status
+git log --oneline -5
+
+# Tests pasando
+bin/rails test
+# o
+bundle exec rspec
+
+# Assets compilan
+bin/rails assets:precompile
+
+# Migraciones pendientes
+bin/rails db:migrate:status
+```
+
+### 2. Checklist pre-deploy
+
+- [ ] Todos los tests pasan
+- [ ] No hay cambios sin commitear
+- [ ] La rama está actualizada con main/master
+- [ ] Las migraciones son reversibles
+- [ ] Variables de entorno configuradas
+- [ ] Backup de base de datos realizado
+
+### 3. Opciones de hosting gratuito
+
+#### Fly.io (Recomendado)
+
+```bash
+# Instalación
+curl -L https://fly.io/install.sh | sh
+
+# Login
+fly auth login
+
+# Primera vez: crear app
+fly launch
+
+# Deploy
+fly deploy
+
+# Ver logs
+fly logs
+
+# Consola Rails
+fly ssh console -C "bin/rails console"
+
+# Migraciones
+fly ssh console -C "bin/rails db:migrate"
+```
+
+**fly.toml básico:**
+```toml
+app = "mi-app"
+primary_region = "mad"
+
+[build]
+  [build.args]
+    RUBY_VERSION = "3.3.0"
+
+[env]
+  RAILS_ENV = "production"
+  RAILS_LOG_TO_STDOUT = "true"
+
+[http_service]
+  internal_port = 3000
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+  min_machines_running = 0
+
+[[services]]
+  protocol = "tcp"
+  internal_port = 3000
+
+  [[services.ports]]
+    port = 80
+    handlers = ["http"]
+
+  [[services.ports]]
+    port = 443
+    handlers = ["tls", "http"]
+
+[[statics]]
+  guest_path = "/rails/public"
+  url_prefix = "/"
+```
+
+#### Render.com
+
+```yaml
+# render.yaml
+services:
+  - type: web
+    name: mi-app
+    env: ruby
+    buildCommand: bundle install && bin/rails assets:precompile
+    startCommand: bin/rails server
+    envVars:
+      - key: RAILS_MASTER_KEY
+        sync: false
+      - key: DATABASE_URL
+        fromDatabase:
+          name: mi-app-db
+          property: connectionString
+
+databases:
+  - name: mi-app-db
+    plan: free
+```
+
+#### Railway.app
+
+```bash
+# Instalación CLI
+npm i -g @railway/cli
+
+# Login
+railway login
+
+# Crear proyecto
+railway init
+
+# Deploy
+railway up
+
+# Variables de entorno
+railway variables set RAILS_ENV=production
+```
+
+### 4. Deploy con Kamal (Docker)
+
+```bash
+# Instalación
+gem install kamal
+
+# Configurar
+kamal init
+
+# Deploy
+kamal deploy
+```
+
+**config/deploy.yml:**
+```yaml
+service: mi-app
+image: usuario/mi-app
+
+servers:
+  web:
+    - 192.168.0.1
+  job:
+    hosts:
+      - 192.168.0.1
+    cmd: bin/jobs
+
+registry:
+  username: usuario
+  password:
+    - KAMAL_REGISTRY_PASSWORD
+
+env:
+  clear:
+    RAILS_ENV: production
+  secret:
+    - RAILS_MASTER_KEY
+    - DATABASE_URL
+
+accessories:
+  db:
+    image: sqlite3
+    host: 192.168.0.1
+    directories:
+      - data:/rails/storage
+
+traefik:
+  options:
+    publish:
+      - "443:443"
+    volume:
+      - "/letsencrypt:/letsencrypt"
+```
+
+### 5. Scripts de deploy
+
+```bash
+#!/bin/bash
+# bin/deploy
+
+set -e
+
+echo "🚀 Iniciando deploy..."
+
+# Pre-checks
+echo "📋 Verificando pre-requisitos..."
+
+if ! git diff-index --quiet HEAD --; then
+  echo "❌ Hay cambios sin commitear"
+  exit 1
+fi
+
+echo "🧪 Ejecutando tests..."
+bin/rails test || bundle exec rspec
+
+echo "📦 Compilando assets..."
+bin/rails assets:precompile
+
+echo "🔄 Desplegando..."
+# Descomentar según plataforma:
+# fly deploy
+# railway up
+# kamal deploy
+# git push heroku main
+
+echo "🗃️ Ejecutando migraciones..."
+# fly ssh console -C "bin/rails db:migrate"
+# railway run bin/rails db:migrate
+# kamal app exec 'bin/rails db:migrate'
+
+echo "✅ Deploy completado!"
+```
+
+### 6. Post-deploy checks
+
+```ruby
+# lib/tasks/health.rake
+namespace :health do
+  desc "Verificar estado de la aplicación"
+  task check: :environment do
+    checks = []
+
+    # Base de datos
+    begin
+      ActiveRecord::Base.connection.execute("SELECT 1")
+      checks << "✅ Base de datos: OK"
+    rescue => e
+      checks << "❌ Base de datos: #{e.message}"
+    end
+
+    # Cache
+    begin
+      Rails.cache.write("health_check", "ok", expires_in: 1.minute)
+      Rails.cache.read("health_check") == "ok" or raise "Cache read failed"
+      checks << "✅ Cache: OK"
+    rescue => e
+      checks << "❌ Cache: #{e.message}"
+    end
+
+    # Storage
+    begin
+      ActiveStorage::Blob.service.exist?("health_check_#{Time.now.to_i}")
+      checks << "✅ Storage: OK"
+    rescue => e
+      checks << "⚠️ Storage: #{e.message}"
+    end
+
+    # Jobs
+    begin
+      SolidQueue::Job.count
+      checks << "✅ Jobs: OK"
+    rescue => e
+      checks << "⚠️ Jobs: #{e.message}"
+    end
+
+    puts checks.join("\n")
+  end
+end
+```
+
+### 7. Rollback
+
+```bash
+# Fly.io
+fly releases
+fly deploy --image registry.fly.io/mi-app:v123
+
+# Kamal
+kamal rollback
+
+# Railway
+railway rollback
+
+# Git-based (Heroku, Render)
+git revert HEAD
+git push
+```
+
+## Variables de entorno necesarias
+
+```bash
+# Producción mínimo
+RAILS_ENV=production
+RAILS_MASTER_KEY=xxx
+SECRET_KEY_BASE=xxx
+DATABASE_URL=sqlite3:///rails/storage/production.sqlite3
+
+# Opcionales
+RAILS_LOG_TO_STDOUT=true
+RAILS_SERVE_STATIC_FILES=true
+WEB_CONCURRENCY=2
+RAILS_MAX_THREADS=5
+```
+
+## Ejemplo de salida
+
+```
+🚀 Iniciando proceso de deploy...
+
+📋 Pre-checks:
+   ✅ Git: rama main, sin cambios pendientes
+   ✅ Tests: 142 tests, 0 failures
+   ✅ Assets: compilados correctamente
+   ✅ Migraciones: 0 pendientes
+
+🔐 Verificación de seguridad:
+   ✅ RAILS_MASTER_KEY configurado
+   ✅ Credenciales encriptadas
+   ✅ No hay secretos expuestos
+
+📦 Desplegando a Fly.io...
+   → Building image...
+   → Pushing to registry...
+   → Deploying v24...
+   → Health check passed
+
+🗃️ Post-deploy:
+   → Ejecutando migraciones... OK
+   → Verificando salud... OK
+
+✅ Deploy completado exitosamente!
+
+🌐 Tu app está disponible en: https://mi-app.fly.dev
+```
+
+## Respuesta del agente
+
+Al ejecutar `/deploy`, el agente:
+
+1. **Verifica pre-requisitos**
+   - Estado de git
+   - Tests pasando
+   - Assets compilando
+
+2. **Detecta plataforma**
+   - Busca fly.toml, render.yaml, etc.
+   - Sugiere opciones si no hay configuración
+
+3. **Ejecuta deploy**
+   - Usa comandos de la plataforma detectada
+   - Muestra progreso en tiempo real
+
+4. **Verifica post-deploy**
+   - Health checks
+   - Migraciones
+   - Logs de errores
+
+5. **Reporta resultado**
+   - URL de la aplicación
+   - Cualquier warning o error