bug_bunny 4.18.0 → 4.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 030517babaaafccb4ac6b067e1c11ac1cf6d4a6a711919c8455c3dcfe6a79637
-  data.tar.gz: fb9a551e05882e05efc3cd23215773507ae6d5d2baab70681360c04100724d29
+  metadata.gz: 8c751d42f963af2dc145005dba7b6245b0dc9fa549cacecb824e6a5cc2c3232d
+  data.tar.gz: c7c602f3f96a47a85080b287fd87435bb161abcab6b5358f51b45ed05fd1428a
 SHA512:
-  metadata.gz: a5c4fbaade4883c361a20e705155d2b60dc6b3e6e64905afe34b02a7a7016cd7913bfd9f1f2de09979d357f72b026dbdc3129ad871d128a1b9ee901628a096b6
-  data.tar.gz: fb7b8dd6f7b74dee3c6d13b789dd07ff3abaeda535680a1ab7ea4276269e40a238588403e5fd7c8d2cdb3188acd3b7889d867d4dffed6a19af45d91eefa68591
+  metadata.gz: e8e1e583486fec890b5ccdedb77f99f1954f37e9a4217afe1aee0085ca8483f242a966643bcce5da5a7a180d0223850039a883ae9ce92b8be91a02c7beaac7b7
+  data.tar.gz: 71305eaf4dec9b4bf3fae7bf19bbb3fd997d75c409c6d5239d52030c1c7b5833f48f675f5bbcf187ef16334c0286f7a780675add36980c5b927ca592c68ab9d7

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [4.19.0] - 2026-06-25
+
+> Capa de errores transport-agnostic (#52). Cambio **aditivo y retrocompatible**: `.message` no se degrada y se suman dos accesores. Bump minor.
+
+### Nuevas funcionalidades
+- **`status` + `raw_response` uniformes en toda la jerarquía (#52):** subidos a la base `BugBunny::Error` (`attr_accessor`) y poblados por `RaiseError.on_complete` en **todas** las clases de error, no solo `UnprocessableEntity`. El consumidor accede a `e.status` / `e.raw_response` de forma uniforme; la gema queda agnóstica al payload y el boundary del servicio interpreta el envelope de dominio. — @Gabriel
+
+### Correcciones
+- **`.message` ya no vuelca un `Hash#inspect` con el envelope anidado (#52):** ante `{ error: { code, message, details } }`, `format_error_message` extrae `error.message` best-effort en vez de interpolar el Hash; mantiene el shape plano histórico (incluido `error: ""`) y cae a JSON. Es solo el string humano para logs/Sentry, no contrato. — @Gabriel
+
+### Documentación
+- `skill/references/errores.md` y `skill/SKILL.md`: nueva sección "Materia prima del error" (`status`/`raw_response`), formato de `.message` endurecido y advertencia de sanitización (no loguear `raw_response` crudo). — @Gabriel
+- Piloto RFC-014: `docs/release/release.md` (suplemento de release de la gema) (#51) — @Gabriel
+
 ## [4.18.0] - 2026-05-26
 
 > Behavior change menor: cualquier `Bunny::Exception` que escape en la frontera del gem (TCP fail, conn rota, canal cerrado, auth fail) ahora se envuelve como `BugBunny::CommunicationError`. La excepción original queda accesible vía `.cause`. Callers que rescatan `Bunny::TCPConnectionFailed` directo deben migrar a `BugBunny::CommunicationError`. Callers que ya rescatan `BugBunny::Error` / `CommunicationError`: sin cambios.

data/docs/release/release.md

@@ -0,0 +1,108 @@
+# Release — bug_bunny
+
+> meta: artefacto release · RFC-014 (shape v2.0, `proposed`) · generado
+> manualmente (**piloto RFC-014** — suplemento gema, valida patrón 1 +
+> per-repo-visible) · anclado a `.github/workflows/release.yml`, `*.gemspec`,
+> `lib/bug_bunny/version.rb`, `CHANGELOG.md`, git · fecha 2026-06-01 · cobertura:
+> completa (régimen gema: build→publish, §e/f/g n/a).
+
+## 1. Resumen
+
+Cómo se libera esta gema. **Patrón 1 (gema-tag):** push de tag `vX.X.X` → un
+**GitHub Actions workflow que vive en el repo** (`.github/workflows/release.yml`)
+→ `gem build` + `gem push` a **RubyGems público**. A diferencia de un servicio,
+el pipeline **no es opaco**: vive en `.github/`, es auditable y versionado con el
+código (`dueño: per-repo-visible`). Una gema **no despliega — publica**: §e
+(deploy), §f (ambientes), §g (rollback) son **n/a** (rollback = `gem yank`,
+out-of-repo).
+
+## 2. Cuerpo
+
+### a. Hecho verificable
+
+- **Convención de versión:** SemVer `vX.X.X`. Actual: **4.18.0**.
+- **Source of truth:** tag remoto (`v4.18.0`) + **triple mirror**
+  `lib/bug_bunny/version.rb` (`VERSION = '4.18.0'`) ← `bug_bunny.gemspec:7`
+  (`spec.version = BugBunny::VERSION`).
+- **Changelog canónico:** `CHANGELOG.md` único.
+- **Patrón de trigger:** `gema-tag` (patrón 1).
+- **Salida:** gema publicada en **RubyGems público**.
+- **Deploy / ambientes / rollback:** **n/a** (gema publica, no despliega).
+
+### b. Versionado
+
+- **Convención:** SemVer `vX.X.X` (**con `v`** — distinto al servicio).
+- **Source of truth:** tag remoto canónico (`git tag --sort=-v:refname` →
+  `v4.18.0`).
+- **Mirror:** `lib/bug_bunny/version.rb` (`VERSION`), leído por
+  `bug_bunny.gemspec:7` (`spec.version = BugBunny::VERSION`).
+  `required_ruby_version >= 2.6.0` (`bug_bunny.gemspec:17`).
+- **Política de divergencia:** `gem-release` lee el tag remoto; si `version.rb`
+  difiere → warn (posible release sin taguear). El bump se calcula sobre el tag.
+
+### c. Changelog
+
+- **Canónico único:** `CHANGELOG.md` ✓.
+- **Formato:** `## [X.X.X] - YYYY-MM-DD` + nota de behavior-change si aplica +
+  categorías (`### Correcciones`), atribución `— @autor`, **link al issue**
+  (ej. `(#49)`). Cruza RFC-013 §h: el changelog ya referencia el incidente que
+  motivó el fix.
+
+### d. Trigger → pipeline → salida
+
+| Patrón | Trigger (señal per-repo) | Pipeline | Salida | Dueño |
+|---|---|---|---|---|
+| `gema-tag` | push tag `vX.X.X` | GH Actions `.github/workflows/release.yml` | gema en **RubyGems público** | **`per-repo-visible`** |
+
+- **Pipeline NO opaco:** `.github/workflows/release.yml` —
+  `on: push: tags: ['v*']` → `ruby/setup-ruby@v1` → `gem build *.gemspec` +
+  `gem push *.gem` (auth `secrets.RUBYGEMS_API_KEY`). Auditable y versionado con
+  el código; se ancla a `file:line`, no se referencia como caja negra.
+- **Consumo:** los servicios la pinnean por versión (`gem "bug_bunny", "~> 4.18.0"`)
+  desde RubyGems — **no** git-source.
+
+### e. Deploy / publish
+
+**n/a (deploy)** — una gema no despliega. El "release" es **publish** a RubyGems,
+cubierto en §d. No hay ambiente de runtime propio.
+
+### f. Ambientes
+
+**n/a** — no hay `dev`/`staging`/`prod`. La única salida es la gema publicada.
+
+### g. Rollback
+
+**n/a en el repo** — el rollback de una gema es **`gem yank <version>`** en
+RubyGems (admin out-of-repo), no un cambio de código. No se documenta como
+procedimiento per-repo porque no vive acá. Una versión yankeada se anotaría en
+`CHANGELOG.md` (con su razón) si pasara.
+
+### h. Dependencias de deploy inter-servicio
+
+- **Consumidores** (cruza RFC-018): servicios del fleet la pinnean
+  `~> 4.18.0` (semántica minor-compatible). Un cambio de contrato del gem
+  (ej. el behavior-change de `4.18.0` — `Bunny::Exception` → `CommunicationError`)
+  obliga a los consumidores a migrar; el `CHANGELOG.md` lo documenta como
+  breaking note. **Orden de deploy:** los consumidores adoptan al hacer `bundle
+  update bug_bunny` — no hay deploy coordinado (cada servicio elige cuándo).
+
+### i. Contrato con la skill productora
+
+- **Skill:** `gem-release` (tag-based, **aplica** — patrón 1 emite tag).
+- **Qué espera del repo:** `lib/bug_bunny/version.rb` como source, `*.gemspec`
+  que lo lee, `CHANGELOG.md` canónico, tag `vX.X.X`, gate `quality-code` verde,
+  y el `.github/workflows/release.yml` que publica en el tag.
+- **Estado:** conforma — layout estándar de gema, workflow per-repo presente.
+
+## 3. Inferencias
+
+- Ninguna relevante: el pipeline de gema es **visible** (`.github/`), así que el
+  artefacto se ancla a archivos reales, no a inferencia sobre cajas negras.
+
+## 4. Cobertura y fronteras
+
+- Cobertura **completa** del régimen gema (build→publish). §e/f/g `n/a` honesto.
+- Contraste validado con el piloto servicio (`box_radius_manager`): allá el
+  pipeline es **opaco** (`fleet-link` Codefresh); acá es **per-repo-visible**
+  (GH Actions en el repo). Misma RFC, dos loci de dueño — el valor de la columna
+  `dueño` de §d.

data/lib/bug_bunny/exception.rb

@@ -5,7 +5,36 @@ require 'json'
 module BugBunny
   # Clase base para todas las excepciones lanzadas por la gema BugBunny.
   # Permite capturar cualquier error de la librería con un `rescue BugBunny::Error`.
-  class Error < ::StandardError; end
+  #
+  # Para los errores derivados de una respuesta RPC (los que levanta
+  # {BugBunny::Middleware::RaiseError}), expone de forma uniforme la **materia
+  # prima** del error: el `status` y el `raw_response` (cuerpo crudo). La gema es
+  # **agnóstica al payload**: no interpreta la estructura del cuerpo de error: es
+  # el boundary de cada servicio quien lee `raw_response` y decide la semántica
+  # de dominio (códigos, detalles de validación, etc.).
+  #
+  # @example Leer la materia prima en el boundary del servicio
+  #   rescue BugBunny::Error => e
+  #     e.status       # => 409
+  #     e.raw_response # => { "error" => { "code" => "...", "message" => "...", "details" => {} } }
+  class Error < ::StandardError
+    # @return [Hash, String, nil] El cuerpo crudo de la respuesta de error, tal
+    #   como llegó por el wire. `nil` para errores que no provienen de una
+    #   respuesta RPC (ej: {CommunicationError}, {ConfigurationError}).
+    #
+    # @note **No loguear ni enviar a sinks (Sentry/logs) sin sanitizar.** El
+    #   cuerpo crudo puede contener datos sensibles (p. ej. en `details`). Antes
+    #   de cualquier sink, filtrar las claves sensibles del fleet
+    #   (`password|pass|passwd|secret|token|api_key|auth`) → `[FILTERED]`. La
+    #   gema entrega el cuerpo crudo a propósito; sanitizarlo es responsabilidad
+    #   del consumidor.
+    attr_accessor :raw_response
+
+    # @return [Integer, nil] El código de estado de la respuesta que originó el
+    #   error (ej: 400, 404, 409, 422, 500). `nil` para errores que no provienen
+    #   de una respuesta RPC.
+    attr_accessor :status
+  end
 
   # Error lanzado cuando ocurren problemas de red, conexión o protocolo AMQP con RabbitMQ.
   #
@@ -191,8 +220,9 @@ module BugBunny
     # @return [Hash, Array, String] Los mensajes de error listos para ser iterados.
     attr_reader :error_messages
 
-    # @return [String, Hash] El cuerpo crudo de la respuesta original.
-    attr_reader :raw_response
+    # `raw_response` y `status` se heredan de {BugBunny::Error} (poblados por
+    # {BugBunny::Middleware::RaiseError}); `raw_response` además se setea acá en
+    # el constructor para mantener el comportamiento histórico.
 
     # Inicializa la excepción procesando el cuerpo de la respuesta.
     #

data/lib/bug_bunny/middleware/raise_error.rb

@@ -34,71 +34,125 @@ module BugBunny
         body = response['body']
 
         case status
-        when 200..299
-          nil # Flujo normal (Success)
-        when 400
-          raise BugBunny::BadRequest, format_error_message(body)
-        when 404
-          raise_not_found(body)
-        when 406
-          raise BugBunny::NotAcceptable
-        when 408
-          raise BugBunny::RequestTimeout
-        when 409
-          raise BugBunny::Conflict, format_error_message(body)
-        when 422
-          # Pasamos el body crudo; UnprocessableEntity lo procesará en exception.rb
-          raise BugBunny::UnprocessableEntity, body
-        when 500..599
-          if body.is_a?(Hash) && body['bug_bunny_exception']
-            exception_data = body['bug_bunny_exception']
-            raise BugBunny::RemoteError.new(
-              exception_data['class'],
-              exception_data['message'],
-              exception_data['backtrace'] || []
-            )
-          end
-          raise BugBunny::InternalServerError, format_error_message(body)
-        else
-          handle_unknown_error(status, body)
+        when 200..299 then nil # Flujo normal (Success)
+        when 400 then raise_typed(BugBunny::BadRequest.new(format_error_message(body)), status, body)
+        when 404 then raise_not_found(status, body)
+        when 406 then raise_typed(BugBunny::NotAcceptable.new, status, body)
+        when 408 then raise_typed(BugBunny::RequestTimeout.new, status, body)
+        when 409 then raise_typed(BugBunny::Conflict.new(format_error_message(body)), status, body)
+        # Pasamos el body crudo; UnprocessableEntity lo procesará en exception.rb
+        when 422 then raise_typed(BugBunny::UnprocessableEntity.new(body), status, body)
+        when 500..599 then raise_server_error(status, body)
+        else handle_unknown_error(status, body)
         end
       end
 
       private
 
-      # Formatea el cuerpo de la respuesta de error para que sea legible en las excepciones.
+      # Levanta el error de servidor (5xx). Si el worker remoto serializó su
+      # excepción en `bug_bunny_exception`, propaga un {BugBunny::RemoteError} con
+      # la traza original; si no, un {BugBunny::InternalServerError} genérico.
       #
-      # Prioriza la convención `{ "error": "...", "detail": "..." }`. Si la respuesta no
-      # sigue esta convención, convierte el Hash completo a un JSON string para mantenerlo legible.
+      # @param status [Integer] El código de estado (rango 500..599).
+      # @param body [Hash, String, nil] El cuerpo crudo de la respuesta.
+      # @raise [BugBunny::RemoteError] Si el cuerpo trae `bug_bunny_exception`.
+      # @raise [BugBunny::InternalServerError] Para 5xx genéricos.
+      def raise_server_error(status, body)
+        if body.is_a?(Hash) && body['bug_bunny_exception']
+          data = body['bug_bunny_exception']
+          remote = BugBunny::RemoteError.new(data['class'], data['message'], data['backtrace'] || [])
+          raise_typed(remote, status, body)
+        end
+
+        raise_typed(BugBunny::InternalServerError.new(format_error_message(body)), status, body)
+      end
+
+      # Puebla la materia prima del error (`status` + `raw_response`) en la
+      # excepción y la levanta. Aplica de forma uniforme a **todas** las clases de
+      # error derivadas de una respuesta RPC, no solo a {BugBunny::UnprocessableEntity}.
+      #
+      # La gema es agnóstica al payload: entrega el cuerpo crudo tal cual para que
+      # el boundary del servicio lo interprete; no parsea su estructura.
+      #
+      # @param error [BugBunny::Error] La excepción ya construida.
+      # @param status [Integer] El código de estado de la respuesta.
+      # @param body [Hash, String, nil] El cuerpo crudo de la respuesta.
+      # @raise [BugBunny::Error] Siempre levanta la excepción recibida.
+      # @return [void]
+      def raise_typed(error, status, body)
+        error.status = status
+        error.raw_response = body
+        raise error
+      end
+
+      # Formatea el cuerpo de la respuesta de error en un **string humano**
+      # best-effort para logs/Sentry. Es de mejor esfuerzo, **no un contrato**: la
+      # gema no expone `code`/`details` como API; quien los necesite los lee desde
+      # `raw_response` en el boundary del servicio.
+      #
+      # Soporta dos shapes del cuerpo, en orden de prioridad:
+      #
+      # 1. **Envelope anidado** `{ "error": { "message": "...", ... } }`: extrae
+      #    `error.message`.
+      # 2. **Shape plano** `{ "error": "texto", "detail": "..." }`: concatena
+      #    `error` + `detail`.
+      #
+      # Si ninguno aplica, cae a `body.to_json` para no volcar un `Hash#inspect`
+      # ilegible en los logs.
+      #
+      # @note Esta función **solo** arma el mensaje humano y no interpreta el
+      #   detalle estructurado del cuerpo (claves como `code`/`details`/`detail`).
+      #   Ese contenido vive en `raw_response` y lo interpreta el boundary del
+      #   servicio; la gema se mantiene agnóstica al payload.
       #
       # @param body [Hash, String, nil] El cuerpo de la respuesta.
-      # @return [String] Un mensaje de error limpio y estructurado.
+      # @return [String] Un mensaje de error limpio y legible.
       def format_error_message(body)
         return 'Unknown Error' if body.nil? || (body.respond_to?(:empty?) && body.empty?)
         return body if body.is_a?(String)
+        return body.to_json unless body.is_a?(Hash)
+
+        human_message_from(body) || body.to_json
+      end
 
-        # Si el worker devolvió un JSON con una key 'error' (nuestra convención en Controller)
-        if body.is_a?(Hash) && body['error']
-          detail = body['detail'] ? " - #{body['detail']}" : ''
-          "#{body['error']}#{detail}"
-        else
-          # Fallback: Convertir todo el Hash a JSON string para que se vea claro en Sentry/Logs
-          body.to_json
+      # Extrae el string humano del cuerpo según el shape, sin volcar Hashes.
+      #
+      # @param body [Hash] El cuerpo de la respuesta.
+      # @return [String, nil] El mensaje humano, o `nil` si el shape no lo provee.
+      # @api private
+      def human_message_from(body)
+        err = body['error']
+
+        # Envelope canónico anidado: { error: { message: "..." } }
+        if err.is_a?(Hash)
+          nested = err['message']
+          return nested if nested.is_a?(String) && !nested.empty?
+
+          return nil
         end
+
+        # Shape plano histórico: { error: "texto", detail: "..." }.
+        # Cualquier String (incluido "") entra por acá para preservar el
+        # comportamiento histórico (la key 'error' siempre fue truthy).
+        return nil unless err.is_a?(String)
+
+        detail = body['detail'] ? " - #{body['detail']}" : ''
+        "#{err}#{detail}"
       end
 
       # Distingue un error de routing (ruta/controller no existe en el servicio remoto)
       # de un 404 genérico de recurso no encontrado.
       #
+      # @param status [Integer] El código de estado (404).
       # @param body [Hash, String, nil] El cuerpo de la respuesta 404.
       # @raise [BugBunny::RoutingError] Si el consumer marcó `error_type: 'routing_error'`.
       # @raise [BugBunny::NotFound] Para 404 genéricos.
-      def raise_not_found(body)
+      def raise_not_found(status, body)
         if body.is_a?(Hash) && body['error_type'] == 'routing_error'
-          raise BugBunny::RoutingError, format_error_message(body)
+          raise_typed(BugBunny::RoutingError.new(format_error_message(body)), status, body)
         end
 
-        raise BugBunny::NotFound, format_error_message(body)
+        raise_typed(BugBunny::NotFound.new(format_error_message(body)), status, body)
       end
 
       # Maneja códigos de error genéricos no mapeados explícitamente en el `case`.
@@ -111,9 +165,9 @@ module BugBunny
         msg = format_error_message(body)
 
         if status >= 500
-          raise BugBunny::ServerError, "Server Error (#{status}): #{msg}"
+          raise_typed(BugBunny::ServerError.new("Server Error (#{status}): #{msg}"), status, body)
         elsif status >= 400
-          raise BugBunny::ClientError, "Client Error (#{status}): #{msg}"
+          raise_typed(BugBunny::ClientError.new("Client Error (#{status}): #{msg}"), status, body)
         end
       end
     end

data/lib/bug_bunny/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BugBunny
-  VERSION = '4.18.0'
+  VERSION = '4.19.0'
 end

data/skill/SKILL.md

@@ -435,6 +435,11 @@ Limitación de RSpec: `instance_double` valida que el método exista pero **no**
 **Causa:** Fallo de transporte AMQP — envuelve cualquier `Bunny::Exception` que escape en la frontera del gem (`Client#publish`/`#request`/`#send`, `Producer#confirmed`, `BugBunny.create_connection`). Cubre TCP fail (`Bunny::TCPConnectionFailed`), conn rota in-flight (`ConnectionClosedError`), canal cerrado (`ChannelAlreadyClosed`), auth fail, etc. La excepción original queda en `.cause`.
 **Resolución:** Verificar conectividad a RabbitMQ (host/port/auth/vhost). Inspeccionar `e.cause` para clasificar el fallo concreto. Revisar `max_reconnect_attempts` y logs de reconexión.
 
+**Materia prima (desde 4.19):** todo `BugBunny::Error` de respuesta RPC expone
+`e.status` y `e.raw_response` (cuerpo crudo) de forma uniforme — no solo 422. La
+gema es agnóstica al payload: el envelope de dominio se parsea en el boundary del
+servicio. No loguear `raw_response` sin sanitizar.
+
 Ver catálogo completo en [Errores](references/errores.md).
 
 ---

data/skill/references/errores.md

@@ -22,6 +22,30 @@ StandardError
         └── BugBunny::RemoteError (500)
 ```
 
+## Materia prima del error (`status` + `raw_response`) — desde 4.19
+
+Todos los errores derivados de una respuesta RPC exponen de forma **uniforme**
+el `status` y el `raw_response` (cuerpo crudo), no solo `UnprocessableEntity`.
+La gema es **agnóstica al payload**: entrega el cuerpo crudo tal cual y el
+boundary del servicio decide la semántica de dominio (códigos, detalles, etc.).
+
+```ruby
+begin
+  client.request('clusters/42', method: :get)
+rescue BugBunny::Error => e
+  e.status       # => 409 (Integer, nil si el error no viene de una respuesta RPC)
+  e.raw_response # => cuerpo crudo tal como llegó por el wire (Hash/String/nil)
+end
+```
+
+> ⚠️ **No loguear `raw_response` crudo.** Puede contener datos sensibles. Filtrar
+> claves (`password|pass|passwd|secret|token|api_key|auth`) → `[FILTERED]` antes
+> de Sentry/logs. La gema lo entrega a propósito; sanitizar es del consumidor.
+
+Para consumir un envelope estructurado de dominio (ej. `{ error: { code,
+message, details } }`), parsealo en el boundary del servicio desde
+`e.raw_response` — la gema **no** expone `code`/`details` como contrato.
+
 ## Errores de Infraestructura
 
 ### BugBunny::CommunicationError
@@ -133,10 +157,15 @@ end
 
 ## 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"`.
+El middleware `RaiseError` construye el `.message` humano (best-effort, para
+logs/Sentry — **no es contrato**) así:
+1. Envelope anidado `{ "error": { "message": "..." } }` → extrae `error.message`.
+2. Shape plano `{ "error": "...", "detail": "..." }` → concatena `error` + `detail`.
+3. Si ninguno aplica, usa el cuerpo completo como JSON (nunca un `Hash#inspect`).
+4. Si el body está vacío, usa `"Unknown Error"`.
+
+Para detalle estructurado (`code`/`details`), leé `e.raw_response` en el
+boundary del servicio (ver "Materia prima del error").
 
 ## Connection Pool Missing
 

data/skills.yml

@@ -2,34 +2,18 @@ mcps:
   - github
   - clickup
 skills:
+  multi-vendor-feedback:
   yard:
-    repo: sequre/ai_knowledge
   quality-code:
-    repo: sequre/ai_knowledge
   gem-release:
-    repo: sequre/ai_knowledge
   dev-structure:
-    repo: sequre/ai_knowledge
   dev-compose:
-    repo: sequre/ai_knowledge
   dev-enrich:
-    repo: sequre/ai_knowledge
   skill-feedback:
-    repo: sequre/ai_knowledge
   agent-issue:
-    repo: sequre/ai_knowledge
+  bug-report:
   dev-flow:
-    repo: sequre/ai_knowledge
   matrix-element:
-    repo: sequre/ai_knowledge
-    environment:
-      homeserver: "https://matrix.cloud.wispro.co"
-      auth_token: "${MATRIX_AUTH_TOKEN}"
-      rooms:
-        agents: "!VCHwQXgmXdyhhhPhoz:matrix.cloud.wispro.co"
-  documentation-writer:
-    repo: github/awesome-copilot
-    path: skills/documentation-writer
-  rabbitmq-expert:
-    repo: martinholovsky/claude-skills-generator
-    path: skills/rabbitmq-expert
+  # rabbitmq-expert:
+  #   repo: martinholovsky/claude-skills-generator
+  #   path: skills/rabbitmq-expert

data/spec/unit/raise_error_spec.rb

@@ -55,5 +55,181 @@ RSpec.describe BugBunny::Middleware::RaiseError do
         expect { middleware.on_complete(response) }.to raise_error(BugBunny::NotFound)
       end
     end
+
+    # Alcance issue #52: status + raw_response como materia prima en TODAS las
+    # clases de error, no solo en 422.
+    describe 'raw_response and status on every error class' do
+      def captured_error(response)
+        middleware.on_complete(response)
+        nil
+      rescue BugBunny::Error => e
+        e
+      end
+
+      {
+        400 => BugBunny::BadRequest,
+        409 => BugBunny::Conflict,
+        500 => BugBunny::InternalServerError
+      }.each do |status, klass|
+        context "when status is #{status}" do
+          let(:body) { { 'error' => 'boom' } }
+          let(:error) { captured_error('status' => status, 'body' => body) }
+
+          it "raises #{klass} with status and raw_response populated" do
+            expect(error).to be_a(klass)
+            expect(error.status).to eq(status)
+            expect(error.raw_response).to eq(body)
+          end
+        end
+      end
+
+      context 'when status is 404 (NotFound)' do
+        let(:body) { { 'error' => 'missing' } }
+        let(:error) { captured_error('status' => 404, 'body' => body) }
+
+        it 'populates status and raw_response' do
+          expect(error.status).to eq(404)
+          expect(error.raw_response).to eq(body)
+        end
+      end
+
+      context 'when status is 422 (UnprocessableEntity)' do
+        let(:body) { { 'errors' => { 'name' => ['blank'] } } }
+        let(:error) { captured_error('status' => 422, 'body' => body) }
+
+        it 'keeps raw_response/error_messages and adds status from base' do
+          expect(error).to be_a(BugBunny::UnprocessableEntity)
+          expect(error.status).to eq(422)
+          expect(error.raw_response).to eq(body)
+          expect(error.error_messages).to eq('name' => ['blank'])
+        end
+      end
+
+      context 'when status is unmapped (418)' do
+        let(:body) { { 'error' => 'teapot' } }
+        let(:error) { captured_error('status' => 418, 'body' => body) }
+
+        it 'populates status and raw_response on the generic ClientError' do
+          expect(error).to be_a(BugBunny::ClientError)
+          expect(error.status).to eq(418)
+          expect(error.raw_response).to eq(body)
+        end
+      end
+    end
+
+    # Alcance issue #52: hardening de format_error_message contra el envelope
+    # anidado para no volcar un Hash#inspect en .message.
+    describe 'message hardening against the nested canonical envelope' do
+      def captured_error(response)
+        middleware.on_complete(response)
+        nil
+      rescue BugBunny::Error => e
+        e
+      end
+
+      context 'when error is the nested canonical envelope { error: { message } }' do
+        let(:body) { { 'error' => { 'code' => 'shortname_taken', 'message' => 'shortname already taken', 'details' => {} } } }
+        let(:error) { captured_error('status' => 409, 'body' => body) }
+
+        it 'extracts the human message and does not dump the Hash' do
+          expect(error.message).to eq('shortname already taken')
+          expect(error.message).not_to include('=>')
+        end
+      end
+
+      context 'when the nested envelope lacks a usable message' do
+        let(:body) { { 'error' => { 'code' => 'x', 'details' => {} } } }
+        let(:error) { captured_error('status' => 409, 'body' => body) }
+
+        it 'falls back to JSON instead of Hash#inspect' do
+          expect(error.message).to eq(body.to_json)
+          expect(error.message).not_to include('=>')
+        end
+      end
+
+      context 'when error is the flat historical shape { error: string, detail: string }' do
+        let(:body) { { 'error' => 'boom', 'detail' => 'because reasons' } }
+        let(:error) { captured_error('status' => 400, 'body' => body) }
+
+        it 'keeps concatenating error and detail (backward compatible)' do
+          expect(error.message).to eq('boom - because reasons')
+        end
+      end
+
+      context 'when error is an empty string (backward-compat edge case)' do
+        let(:body) { { 'error' => '', 'detail' => 'x' } }
+        let(:error) { captured_error('status' => 400, 'body' => body) }
+
+        it 'preserves the historical concatenation instead of dumping JSON' do
+          expect(error.message).to eq(' - x')
+        end
+      end
+    end
+
+    # Alcance issue #52: casos borde y paths no cubiertos arriba.
+    describe 'edge cases and uncovered paths' do
+      def captured_error(response)
+        middleware.on_complete(response)
+        nil
+      rescue BugBunny::Error => e
+        e
+      end
+
+      context 'when 5xx carries a serialized remote exception (bug_bunny_exception)' do
+        let(:body) do
+          { 'bug_bunny_exception' => { 'class' => 'ActiveRecord::RecordNotFound',
+                                       'message' => 'User not found',
+                                       'backtrace' => ['app.rb:1'] } }
+        end
+        let(:error) { captured_error('status' => 500, 'body' => body) }
+
+        it 'raises RemoteError with status and raw_response populated' do
+          expect(error).to be_a(BugBunny::RemoteError)
+          expect(error.status).to eq(500)
+          expect(error.raw_response).to eq(body)
+          expect(error.original_class).to eq('ActiveRecord::RecordNotFound')
+        end
+      end
+
+      context 'when 422 carries the nested envelope (consumer parses from raw_response)' do
+        let(:body) { { 'error' => { 'code' => 'taken', 'message' => 'shortname already taken', 'details' => {} } } }
+        let(:error) { captured_error('status' => 422, 'body' => body) }
+
+        it 'keeps raw_response intact for the service boundary' do
+          expect(error).to be_a(BugBunny::UnprocessableEntity)
+          expect(error.status).to eq(422)
+          expect(error.raw_response).to eq(body)
+        end
+      end
+
+      context 'when status is 406 (no-arg constructor)' do
+        let(:body) { { 'error' => 'nope' } }
+        let(:error) { captured_error('status' => 406, 'body' => body) }
+
+        it 'still populates status and raw_response' do
+          expect(error).to be_a(BugBunny::NotAcceptable)
+          expect(error.status).to eq(406)
+          expect(error.raw_response).to eq(body)
+        end
+      end
+
+      context 'when status is 408 (no-arg constructor)' do
+        let(:error) { captured_error('status' => 408, 'body' => nil) }
+
+        it 'still populates status' do
+          expect(error).to be_a(BugBunny::RequestTimeout)
+          expect(error.status).to eq(408)
+        end
+      end
+
+      context 'when body is not a Hash nor a String (e.g. Array)' do
+        let(:body) { [1, 2, 3] }
+        let(:error) { captured_error('status' => 400, 'body' => body) }
+
+        it 'falls back to JSON without raising in the formatter' do
+          expect(error.message).to eq(body.to_json)
+        end
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 4.18.0
+  version: 4.19.0
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-26 00:00:00.000000000 Z
+date: 2026-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -235,6 +235,7 @@ files:
 - Rakefile
 - docs/behavior/behavior.md
 - docs/glossary/glossary.md
+- docs/release/release.md
 - initializer_example.rb
 - lib/bug_bunny.rb
 - lib/bug_bunny/client.rb
@@ -307,7 +308,7 @@ metadata:
   homepage_uri: https://github.com/gedera/bug_bunny
   source_code_uri: https://github.com/gedera/bug_bunny
   changelog_uri: https://github.com/gedera/bug_bunny/blob/main/CHANGELOG.md
-  documentation_uri: https://github.com/gedera/bug_bunny/blob/v4.18.0/skill
+  documentation_uri: https://github.com/gedera/bug_bunny/blob/v4.19.0/skill
 post_install_message:
 rdoc_options: []
 require_paths: