bug_bunny 4.8.0 → 4.9.0

data/skill/references/errores.md

@@ -0,0 +1,97 @@
+# Catálogo de Errores
+
+## Jerarquía
+
+```
+StandardError
+└── BugBunny::Error
+    ├── BugBunny::CommunicationError
+    ├── BugBunny::ConfigurationError
+    ├── BugBunny::SecurityError
+    ├── BugBunny::ClientError (4xx)
+    │   ├── BugBunny::BadRequest (400)
+    │   ├── BugBunny::NotFound (404)
+    │   ├── BugBunny::NotAcceptable (406)
+    │   ├── BugBunny::RequestTimeout (408)
+    │   ├── BugBunny::Conflict (409)
+    │   └── BugBunny::UnprocessableEntity (422)
+    └── BugBunny::ServerError (5xx)
+        └── BugBunny::InternalServerError (500+)
+```
+
+## Errores de Infraestructura
+
+### BugBunny::CommunicationError
+**Causa:** Fallo de conexión TCP/AMQP o reconexión agotada (`max_reconnect_attempts`).
+**Cuándo:** Al intentar publicar o consumir sin conexión activa, o tras agotar intentos de reconexión.
+**Resolución:** Verificar conectividad a RabbitMQ (host, port, firewall). Revisar logs `event=session.reconnect_failed`. Ajustar `max_reconnect_attempts` y `max_reconnect_interval`.
+
+### BugBunny::ConfigurationError
+**Causa:** Campo requerido faltante o valor fuera de rango en `BugBunny.configure`.
+**Validaciones:** host (String no vacío), port (1-65535), username/password (no nil), heartbeat (0-3600), rpc_timeout (>0), channel_prefetch (1-10000).
+**Resolución:** Revisar el bloque `BugBunny.configure` y corregir valores.
+
+### BugBunny::SecurityError
+**Causa:** Un mensaje intenta ejecutar un controlador que no hereda de `BugBunny::Controller`.
+**Cuándo:** El consumer resuelve la clase pero falla la validación `is_a?(BugBunny::Controller)`.
+**Resolución:** Verificar que el controlador herede de `BugBunny::Controller` y que `config.controller_namespace` sea correcto.
+
+## Errores de Cliente (4xx)
+
+### BugBunny::BadRequest (400)
+**Causa:** Request malformado o sintaxis inválida.
+**Resolución:** Verificar formato del body y headers.
+
+### BugBunny::NotFound (404)
+**Causa:** El recurso solicitado no existe en el servicio remoto.
+**Resolución:** Verificar ID del recurso y que el endpoint exista.
+
+### BugBunny::NotAcceptable (406)
+**Causa:** Negociación de contenido falló.
+**Resolución:** Verificar `content_type` del request.
+
+### BugBunny::RequestTimeout (408)
+**Causa:** No hubo respuesta en `config.rpc_timeout` segundos.
+**Cuándo:** El `Concurrent::IVar` expira sin recibir reply.
+**Resolución:** Verificar que el worker esté activo. Revisar saturación de prefetch. Aumentar `rpc_timeout` si el procesamiento es legítimamente lento.
+
+### BugBunny::Conflict (409)
+**Causa:** Conflicto de regla de negocio (ej: recurso ya existe, versión desactualizada).
+**Resolución:** Reintentar tras refrescar el estado del recurso.
+
+### BugBunny::UnprocessableEntity (422)
+**Causa:** Fallo de validación en el servicio remoto.
+**Acceso a errores:**
+```ruby
+begin
+  order.save
+rescue BugBunny::UnprocessableEntity => e
+  e.error_messages   # Hash, Array o String con detalles
+  e.raw_response     # Response original completo
+end
+```
+**Smart extraction:** Busca `errors`, `error`, `detail`, `message` en el body. Formatea como Hash descriptivo si no encuentra convención.
+**En Resource:** `save` captura 422 automáticamente, carga `resource.errors` y retorna `false`.
+
+## Errores de Servidor (5xx)
+
+### BugBunny::InternalServerError (500+)
+**Causa:** Error no controlado en el servicio remoto.
+**Resolución:** Revisar logs del servicio remoto. Verificar backtrace en `event=controller.unhandled_exception`.
+
+### BugBunny::ServerError (base 5xx)
+**Causa:** Cualquier error de servidor no mapeado a InternalServerError.
+**Resolución:** Similar a InternalServerError.
+
+## Formato de Mensajes de Error
+
+El middleware `RaiseError` construye el mensaje así:
+1. Busca `{ "error": "...", "detail": "..." }` en el body.
+2. Si no encuentra, usa el Hash completo como JSON.
+3. Si el body está vacío, usa `"Unknown Error"`.
+
+## Connection Pool Missing
+
+**No es una excepción BugBunny**, pero es un error común:
+**Causa:** Se intentó usar un Resource sin asignar el pool global.
+**Resolución:** Asegurar que `BugBunny::Resource.connection_pool = MY_POOL` se ejecute en el arranque.

data/skill/references/resource.md

@@ -0,0 +1,116 @@
+# Resources
+
+## Definición
+
+```ruby
+class Order < BugBunny::Resource
+  # Infraestructura AMQP
+  @connection_pool = MY_POOL
+  @exchange = 'orders_ex'
+  @exchange_type = 'topic'
+  @resource_name = 'orders'        # path en la URL
+  @routing_key = 'orders.#'
+  @param_key = 'order'             # wrapper key en payloads
+  @exchange_options = { durable: true }
+  @queue_options = { auto_delete: false }
+
+  # Atributos tipados (ActiveModel::Attributes)
+  attribute :id, :integer
+  attribute :status, :string
+  attribute :total, :decimal
+  attribute :active, :boolean
+
+  # Validaciones (ActiveModel::Validations)
+  validates :status, presence: true
+
+  # Callbacks
+  before_save :normalize_status
+  after_create :notify_warehouse
+  around_destroy :audit_deletion
+
+  # Middleware client-side
+  client_middleware do |stack|
+    stack.use BugBunny::Middleware::RaiseError
+    stack.use BugBunny::Middleware::JsonResponse
+  end
+end
+```
+
+## Operaciones CRUD
+
+### Class Methods
+
+```ruby
+Order.find(42)                           # GET orders/42 → Order
+Order.where(status: 'active')            # GET orders?status=active → [Order, ...]
+Order.all                                # GET orders → [Order, ...]
+Order.create(status: 'pending', total: 100) # POST orders → Order
+```
+
+### Instance Methods
+
+```ruby
+order = Order.new(status: 'pending')
+order.save                               # POST orders (nuevo) o PUT orders/42 (existente)
+order.update(status: 'shipped')          # assign + save
+order.destroy                            # DELETE orders/42
+order.persisted?                         # true si fue guardado
+order.changed?                           # true si tiene cambios sin guardar
+order.errors                             # ActiveModel::Errors
+```
+
+### Save: Create vs Update
+
+- **Nuevo** (`persisted? == false`): Envía POST con todos los atributos.
+- **Existente** (`persisted? == true`): Envía PUT solo con atributos cambiados (`changes_to_send`).
+- Captura `BugBunny::UnprocessableEntity` (422) y carga `resource.errors`. Retorna `false`.
+
+## Contexto Dinámico (.with)
+
+### Forma de bloque (recomendada)
+
+```ruby
+Order.with(exchange: 'priority_ex', routing_key: 'priority.orders') do
+  Order.all                    # Usa config temporal
+  Order.find(1)                # También usa config temporal
+end
+# Config restaurada automáticamente
+```
+
+### Forma de cadena (single use)
+
+```ruby
+order = Order.with(pool: special_pool).find(42)
+# Siguiente llamada requiere nuevo .with()
+```
+
+**Antipatrón:** No guardar el proxy en variable para múltiples llamadas → lanza error.
+
+## Change Tracking
+
+Combina `ActiveModel::Dirty` con atributos dinámicos:
+
+```ruby
+order = Order.find(42)
+order.name = 'New Name'              # Atributo definido
+order.custom_field = 'value'         # Atributo dinámico
+order.changed                        # → ['name', 'custom_field']
+order.changes_to_send                # → { 'name' => 'New Name', 'custom_field' => 'value' }
+```
+
+## Callbacks Disponibles
+
+Definidos con `define_model_callbacks`:
+- `:save` — before/after/around save (create o update)
+- `:create` — before/after/around create (recurso nuevo)
+- `:update` — before/after/around update (recurso existente)
+- `:destroy` — before/after/around destroy
+
+## Coerción de Tipos
+
+Los atributos tipados usan `ActiveModel::Attributes`:
+- `'25.50'` → `BigDecimal` (con `:decimal`)
+- `'1'` / `'true'` → `true` (con `:boolean`)
+- `'2026-04-01T...'` → `Time` (con `:time`)
+
+Los atributos dinámicos (no declarados) se almacenan sin coerción.

data/skill/references/routing.md

@@ -0,0 +1,82 @@
+# Routing
+
+## DSL Completo
+
+```ruby
+BugBunny.routes.draw do
+  # Verbos HTTP individuales
+  get    'health',       to: 'health#check'
+  post   'events',       to: 'events#create'
+  put    'settings',     to: 'settings#update'
+  patch  'settings',     to: 'settings#patch'
+  delete 'cache',        to: 'cache#clear'
+
+  # Resources genera 5 rutas REST
+  resources :users
+  # GET    users      → UsersController#index
+  # GET    users/:id  → UsersController#show
+  # POST   users      → UsersController#create
+  # PUT    users/:id  → UsersController#update
+  # DELETE users/:id  → UsersController#destroy
+
+  # Filtros
+  resources :orders, only: [:index, :show]
+  resources :products, except: [:destroy]
+
+  # Namespaces (anidables)
+  namespace :admin do
+    namespace :v2 do
+      resources :reports   # → Admin::V2::ReportsController
+    end
+  end
+
+  # Member y Collection
+  resources :nodes do
+    member do
+      put :drain           # PUT nodes/:id/drain → NodesController#drain
+      post :restart        # POST nodes/:id/restart → NodesController#restart
+    end
+    collection do
+      get :stats           # GET nodes/stats → NodesController#stats
+      get :health          # GET nodes/health → NodesController#health
+    end
+  end
+end
+```
+
+## Route Matching
+
+El `RouteSet#recognize(method, path)` busca la primera ruta que matchee:
+
+- **Normalización:** Strips leading/trailing slashes del path.
+- **Parámetros:** `:id` se compila a regex `(?<id>[^/]+)`. Los valores se extraen como Hash.
+- **No match:** Retorna `nil` → el consumer responde 404.
+
+```ruby
+route = BugBunny.routes.recognize('GET', 'users/42')
+route.controller  # => "users"
+route.action      # => "show"
+route.namespace   # => nil
+route.params      # => { 'id' => '42' }
+```
+
+## Resolución de Controller
+
+El consumer resuelve el controlador concatenando:
+1. `config.controller_namespace` (default: `BugBunny::Controllers`)
+2. `route.namespace` (si existe)
+3. `route.controller.classify + "Controller"`
+
+Ejemplo: namespace `:admin`, controller `:reports` → `BugBunny::Controllers::Admin::ReportsController`
+
+Valida que el controlador sea subclase de `BugBunny::Controller`. Si no, lanza `SecurityError`.
+
+## Route Object
+
+```ruby
+route.http_method       # String: "GET", "POST", etc.
+route.path_pattern      # String: "users/:id"
+route.controller        # String: "users"
+route.action            # String: "show"
+route.namespace         # String o nil: "Admin::V2"
+```

data/skill/references/testing.md

@@ -0,0 +1,138 @@
+# Testing
+
+## Estructura
+
+```
+spec/
+├── spec_helper.rb
+├── support/
+│   ├── bunny_mocks.rb          # Stubs para unit tests
+│   └── integration_helper.rb   # Helpers para integration tests
+├── unit/                       # Sin RabbitMQ real
+│   ├── configuration_spec.rb
+│   ├── client_session_pool_spec.rb
+│   ├── consumer_spec.rb
+│   ├── session_spec.rb
+│   ├── consumer_middleware_spec.rb
+│   ├── controller_after_action_spec.rb
+│   ├── observability_spec.rb
+│   └── resource_attributes_spec.rb
+└── integration/                # Requiere RabbitMQ
+    ├── client_spec.rb
+    ├── consumer_middleware_spec.rb
+    ├── controller_spec.rb
+    ├── error_handling_spec.rb
+    ├── infrastructure_spec.rb
+    └── resource_spec.rb
+```
+
+## Unit Tests — Mocking de Bunny
+
+Los unit tests usan `BunnyMocks` para evitar dependencia de RabbitMQ:
+
+```ruby
+# spec/support/bunny_mocks.rb
+BunnyMocks::FakeChannel     # Simula canal Bunny
+BunnyMocks::FakeConnection  # Simula conexión Bunny
+```
+
+Patrón de uso:
+
+```ruby
+let(:connection) { BunnyMocks::FakeConnection.new }
+let(:session) { BugBunny::Session.new(connection) }
+```
+
+Para Producer: `allow_any_instance_of(BugBunny::Producer).to receive(:rpc).and_return(response)`
+
+## Integration Tests — Helpers
+
+### with_running_worker
+
+Levanta un consumer real en un thread:
+
+```ruby
+with_running_worker(
+  queue: unique('test_q'),
+  exchange: unique('test_ex'),
+  exchange_type: 'topic',
+  routing_key: 'users.#'
+) do
+  response = client.request('users/1', method: :get)
+  expect(response['status']).to eq(200)
+end
+# Worker se detiene automáticamente al salir del bloque
+```
+
+### with_spy_worker
+
+Captura mensajes sin procesarlos:
+
+```ruby
+with_spy_worker(queue:, exchange:) do |messages|
+  client.publish('events', body: { type: 'test' })
+  msg = wait_for_message(messages, 5)
+  expect(msg[:body]).to include('type' => 'test')
+end
+```
+
+### unique(name)
+
+Genera nombres únicos para evitar colisiones entre tests:
+
+```ruby
+unique('my_queue')  # → "my_queue_a3f1b2c4"
+# Usa SecureRandom.hex(4)
+```
+
+## Thread Safety Testing
+
+Patrón con `Concurrent::CyclicBarrier`:
+
+```ruby
+barrier = Concurrent::CyclicBarrier.new(10)
+counter = Concurrent::AtomicFixnum.new(0)
+
+threads = 10.times.map do
+  Thread.new do
+    barrier.wait   # Sincroniza inicio
+    session.channel
+    counter.increment
+  end
+end
+
+threads.each(&:join)
+expect(counter.value).to eq(10)
+```
+
+## Skip de Integration Tests
+
+Los tests `:integration` se skipean automáticamente si RabbitMQ no está disponible:
+
+```ruby
+# spec_helper.rb
+config.before(:each, :integration) do
+  skip 'RabbitMQ not available' unless rabbitmq_available?
+end
+```
+
+## Configuración de Test
+
+```ruby
+BugBunny.configure do |config|
+  config.host     = ENV.fetch('RABBITMQ_HOST', 'localhost')
+  config.username = ENV.fetch('RABBITMQ_USER', 'guest')
+  config.password = ENV.fetch('RABBITMQ_PASS', 'guest')
+end
+
+TEST_POOL = ConnectionPool.new(size: 5) { BugBunny.create_connection }
+```
+
+## Ejecutar Tests
+
+```bash
+bundle exec rspec                           # Todos
+bundle exec rspec spec/unit/                # Solo unit
+bundle exec rspec spec/integration/         # Solo integration (requiere RabbitMQ)
+bundle exec rspec spec/unit/session_spec.rb # Archivo específico
+```

data/skills.lock

@@ -0,0 +1,30 @@
+---
+synced_at: '2026-04-05 13:40:39'
+skills:
+- name: agent-review
+  scope: local
+  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/agent-review"
+- name: ai-reports
+  scope: local
+  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/ai-reports"
+- name: documentation-writer
+  scope: local
+  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/documentation-writer"
+- name: find-skills
+  scope: local
+  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/find-skills"
+- name: gem-release
+  scope: local
+  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/gem-release"
+- name: quality-code
+  scope: local
+  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/quality-code"
+- name: skill-builder
+  scope: local
+  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/skill-builder"
+- name: skill-manager
+  scope: local
+  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/skill-manager"
+- name: yard
+  scope: local
+  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/yard"

data/skills.yml

@@ -0,0 +1,40 @@
+mcps:
+  - github
+  - clickup
+skills:
+  skill-manager:
+    repo: sequre/ai_knowledge
+    scope: local
+  yard:
+    repo: sequre/ai_knowledge
+    scope: local
+  quality-code:
+    repo: sequre/ai_knowledge
+    scope: local
+  gem-release:
+    repo: sequre/ai_knowledge
+    scope: local
+  skill-builder:
+    repo: sequre/ai_knowledge
+    scope: local
+  ai-reports:
+    repo: sequre/ai_knowledge
+    scope: local
+    environment:
+      space_id: "${AI_REPORTS_SPACE_ID}"
+      bug_reports_list_id: "${AI_REPORTS_BUG_REPORTS_LIST_ID}"
+      improvements_list_id: "${AI_REPORTS_IMPROVEMENTS_LIST_ID}"
+  agent-review:
+    repo: sequre/ai_knowledge
+    scope: local
+    environment:
+      space_id: "${AGENT_REVIEW_SAPCE_ID}"
+      list_id: "${AGENT_LIST_ID}"
+  documentation-writer:
+    repo: github/awesome-copilot
+    path: skills/documentation-writer
+    scope: local
+  find-skills:
+    repo: vercel-labs/skills
+    path: skills/find-skills
+    scope: local

data/spec/integration/consumer_middleware_spec.rb

@@ -24,7 +24,7 @@ class TrackingMiddleware < BugBunny::ConsumerMiddleware::Base
   def call(delivery_info, properties, body)
     self.class.calls << {
       routing_key: delivery_info.routing_key,
-      headers:     properties.headers
+      headers: properties.headers
     }
     @app.call(delivery_info, properties, body)
   end
@@ -45,7 +45,7 @@ RSpec.describe 'Consumer Middleware Stack', :integration do
     BugBunny.configure { |c| c.controller_namespace = 'BugBunny::Controllers' }
     # Limpiamos el middleware para no afectar otros specs
     BugBunny.configuration.instance_variable_set(:@consumer_middlewares,
-      BugBunny::ConsumerMiddleware::Stack.new)
+                                                 BugBunny::ConsumerMiddleware::Stack.new)
   end
 
   it 'ejecuta el middleware antes de process_message' do
@@ -82,5 +82,26 @@ RSpec.describe 'Consumer Middleware Stack', :integration do
       BugBunny.configuration.rpc_reply_headers = nil
       BugBunny.configuration.on_rpc_reply      = nil
     end
+
+    it 'incluye los campos OTel semantic conventions en el reply' do
+      received_headers = nil
+
+      BugBunny.configuration.rpc_reply_headers = -> { { 'X-Test-Header' => 'from-consumer' } }
+      BugBunny.configuration.on_rpc_reply = ->(headers) { received_headers = headers }
+
+      with_running_worker(queue: queue, exchange: exchange, routing_key: 'ping') do
+        client.request('ping', method: :get, exchange: exchange, exchange_type: 'topic', routing_key: 'ping')
+      end
+
+      expect(received_headers).to include(
+        'messaging_system' => 'rabbitmq',
+        'messaging_operation' => 'publish',
+        'X-Test-Header' => 'from-consumer'
+      )
+      expect(received_headers['messaging_message_id']).not_to be_nil
+    ensure
+      BugBunny.configuration.rpc_reply_headers = nil
+      BugBunny.configuration.on_rpc_reply      = nil
+    end
   end
 end