bug_bunny 4.8.0 → 4.9.0

data/.claude/commands/gem-ai-setup.md

@@ -1,174 +0,0 @@
-Generate or update the complete AI documentation suite for this gem.
-
-This skill is invoked automatically by `/release`. It can also be run standalone to update docs without a full release.
-
-BugBunny's `docs/ai/` is the **golden example** of the expected output quality. When in doubt, read it.
-
----
-
-## Step 1 — Discover the current state
-
-Read in order:
-1. `lib/bug_bunny/version.rb` (or equivalent) — current version
-2. `docs/_index.md` — if it exists, it lists all files to update and their purpose
-3. `docs/ai/_index.md` — if it exists, it has the current profile (minimal/full) and file list
-4. `gemspec` — gem name, summary, description, dependencies
-5. `CLAUDE.md` — architecture, components, patterns, extension hooks
-
-If `docs/ai/` does not exist yet, this is a **first-time generation**. Create from scratch.
-If it exists, **update only the sections affected by the changes in this release**.
-
----
-
-## Step 2 — Determine the profile
-
-**Full profile** when any of these apply:
-- Gem is public (has a homepage or published to RubyGems)
-- Gem has multiple audiences (internal maintainers + external integrators)
-- Gem has a non-trivial public API (multiple classes, errors, configuration)
-
-**Minimal profile** when all of these apply:
-- Gem is internal-only
-- Single audience
-- Simple API (one entry point, few methods)
-
-Full profile files: `_index.md`, `glossary.md`, `architecture.md`, `api.md`, `faq_internal.md`, `faq_external.md`, `antipatterns.md`, `errors.md`
-Minimal profile files: `_index.md`, `api.md`, `errors.md`
-
----
-
-## Step 3 — Analyze the codebase
-
-Read the following to generate accurate content:
-- All files under `lib/` — public API, class responsibilities, method signatures
-- `spec/` or `test/` — usage patterns, edge cases, what errors are expected
-- `CHANGELOG.md` — what changed in this version (for updating existing docs)
-- `docs/howto/` — existing human docs to stay consistent with
-
----
-
-## Step 4 — Generate or update each file
-
-Apply these rules to every file:
-
-**RAG optimization rules (mandatory):**
-1. Each section ≤ 400 tokens — chunks must be self-contained
-2. Each section self-contained — do not assume context from previous sections
-3. `faq_*.md` always in strict Q&A format — H3 with the question, answer ≤ 150 words
-4. `glossary.md` one entry per term — term in bold, definition in 1-3 lines
-5. `errors.md` one entry per error — name, cause, how to reproduce, how to resolve
-6. No introductory prose — go straight to content
-
-### `_index.md`
-
-Frontmatter manifest. Update `version:` to the new version. Keep `profile:`, `kind:`, `audiences:` stable unless the gem changed fundamentally. List every file under `files:` with its audience.
-
-Reference: `docs/ai/_index.md` in BugBunny.
-
-### `glossary.md`
-
-Domain terms specific to this gem. Include:
-- Core abstractions introduced by the gem
-- Terms a developer needs to understand to use the gem correctly
-- Terms that have a non-obvious meaning in this context
-
-Do NOT include generic Ruby or framework terms unless the gem redefines them.
-
-Reference: `docs/ai/glossary.md` in BugBunny.
-
-### `architecture.md`
-
-Internal-facing. Include:
-- Component map (ASCII diagram if useful)
-- How the components interact at runtime
-- Key design decisions and why (not just what)
-- Thread safety considerations if relevant
-- Caching or lifecycle patterns
-
-Reference: `docs/ai/architecture.md` in BugBunny.
-
-### `api.md`
-
-External-facing. Include:
-- Configuration block with all options, types, defaults, and constraints
-- Every public class with its public methods: signature, parameters, return type, description
-- Code examples for each major operation
-- Class-level configuration options (`.with`, class attributes, etc.)
-
-Reference: `docs/ai/api.md` in BugBunny.
-
-### `faq_internal.md`
-
-Q&A for the gem maintainer. Cover:
-- Non-obvious implementation decisions ("why X instead of Y?")
-- Thread safety and concurrency considerations
-- How to extend or hook into the gem
-- Common mistakes when modifying the gem internals
-
-Each Q&A: H3 for the question, answer ≤ 150 words, no preamble.
-
-Reference: `docs/ai/faq_internal.md` in BugBunny.
-
-### `faq_external.md`
-
-Q&A for the developer integrating the gem. Cover:
-- Setup and configuration questions
-- How to perform the most common operations
-- Error handling patterns
-- Testing patterns
-- Performance and tuning questions
-
-Each Q&A: H3 for the question, answer ≤ 150 words, no preamble.
-
-Reference: `docs/ai/faq_external.md` in BugBunny.
-
-### `antipatterns.md`
-
-What NOT to do. For each antipattern:
-1. Name it clearly
-2. Show the wrong code
-3. Explain why it's wrong (not just "it's bad")
-4. Show the correct alternative
-
-Reference: `docs/ai/antipatterns.md` in BugBunny.
-
-### `errors.md`
-
-All exceptions the gem raises. For each:
-- Class name and inheritance
-- Cause (what triggers it)
-- How to reproduce it (minimal example)
-- How to resolve it
-
-Reference: `docs/ai/errors.md` in BugBunny.
-
----
-
-## Step 5 — Update docs/howto/ and docs/concepts.md
-
-Read `docs/_index.md` (human documentation section) to know which files exist.
-Update only the sections affected by the changes in this release.
-Do not rewrite files that were not affected by the changes.
-
----
-
-## Step 6 — Update README.md
-
-Generate or update README.md after `docs/howto/` is already updated.
-README structure:
-1. One-line description
-2. Installation (`gem 'gem_name'` in Gemfile)
-3. Quick start — two minimal code examples (publisher side + consumer/server side if applicable)
-4. Features list for the current version
-5. Links to `docs/` for deeper guides
-
-Keep it under 150 lines. README is the entry point — `docs/` is the depth.
-
----
-
-## Step 7 — Show diff and wait for approval
-
-Show the complete diff of all generated/updated files.
-Wait for developer approval before proceeding.
-The developer may adjust content before confirming.
-Do NOT proceed to version bump or CHANGELOG until approved.

data/.claude/commands/pr.md

@@ -1,53 +0,0 @@
-Create a Pull Request for BugBunny via GitHub CLI. Usage: /pr
-
-Creá un PR desde la rama actual hacia `main` usando `gh`.
-
-## Pasos
-
-1. **Correr tests** — si fallan, detener todo:
-   ```bash
-   source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8
-   bundle exec rspec
-   ```
-2. **autocorregir rubocop** - si fallan, detener todo
-   ```bash
-   bundle exec rubocop -a
-   ```
-3. **Ejecutar `/gem-ai-setup`** — genera/actualiza `docs/howto/`, `docs/ai/` y `README.md`.
-   Esperar aprobación del developer antes de continuar.
-4. Verificá que hay commits en la rama que no están en main: `git log main..HEAD --oneline`
-5. Revisá todos los cambios del PR: `git diff main...HEAD`
-6. Determiná el tipo de cambio (feature, bugfix, refactor, docs, chore)
-7. Creá el PR con `gh pr create`:
-
-```bash
-gh pr create --title "tipo: descripción breve" --body "$(cat <<'EOF'
-## Summary
-- Bullet points de los cambios principales
-
-## Test plan
-- [ ] Tests existentes pasan (`/test`)
-- [ ] RuboCop sin offenses (`/rubocop`)
-- [ ] YARD documentado en métodos nuevos/modificados
-
-## Notes
-Contexto adicional si es necesario.
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-EOF
-)"
-```
-
-## Convenciones de título
-
-- `feat: descripción` — feature nueva
-- `fix: descripción` — bugfix
-- `chore: descripción` — mantenimiento, deps, config
-- `docs: descripción` — solo documentación
-- `refactor: descripción` — refactor sin cambio de comportamiento
-
-## Importante
-
-- El remote SSH está roto — si el PR requiere push previo, usar HTTPS temporalmente
-- Mostrar la URL del PR creado al usuario
-- No crear el PR sin confirmación del usuario

data/.claude/commands/release.md

@@ -1,52 +0,0 @@
-Release BugBunny gem. Usage: /release [patch|minor|major]
-
-Ejecutá el flujo completo de release para BugBunny. El argumento determina el tipo de bump:
-- `patch` → bugfix (4.6.1 → 4.6.2)
-- `minor` → feature nueva (4.6.1 → 4.7.0)
-- `major` → breaking change (4.6.1 → 5.0.0)
-
-## Pasos
-
-1. **Leer versión actual** de `lib/bug_bunny/version.rb`
-2. **Calcular nueva versión** según el tipo de bump
-3. **Correr tests** — si fallan, detener todo:
-   ```bash
-   source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8
-   bundle exec rspec
-   ```
-4. **autocorregir rubocop** - si fallan, detener todo
-   ```bash
-   bundle exec rubocop -a
-   ```
-5. **Ejecutar `/gem-ai-setup`** — genera/actualiza `docs/howto/`, `docs/ai/` y `README.md`.
-   Esperar aprobación del developer antes de continuar.
-6. **Actualizar `lib/bug_bunny/version.rb`** con la nueva versión
-7. **Agregar entrada al tope de `CHANGELOG.md`** con formato:
-   ```
-   ## [X.Y.Z] - YYYY-MM-DD
-   ### ✨ New Features / 🐛 Bug Fixes / 💥 Breaking Changes
-   * Descripción de los cambios
-   ```
-8. **Mostrar el diff completo** al usuario y pedir confirmación antes de continuar
-9. **Commit** con mensaje: `feat|fix|chore: descripción breve vX.Y.Z`
-10. **Merge a main** desde `/Users/gabriel/src/gems/bug_bunny`: `git merge --ff-only <branch>`
-11. **Push via HTTPS**:
-    ```bash
-    git remote set-url origin https://github.com/gedera/bug_bunny.git
-    git push origin main
-    git remote set-url origin git@github.com:gedera/bug_bunny.git
-    ```
-12. **Tag y push**:
-    ```bash
-    git tag vX.Y.Z
-    git remote set-url origin https://github.com/gedera/bug_bunny.git
-    git push origin vX.Y.Z
-    git remote set-url origin git@github.com:gedera/bug_bunny.git
-    ```
-
-## Importante
-
-- Nunca commitear ni pushear sin confirmación explícita del usuario
-- El worktree de main está en `/Users/gabriel/src/gems/bug_bunny`
-- SSH está roto — siempre usar HTTPS para push y restaurar SSH después
-- Sourcear chruby antes de cualquier comando Ruby: `source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8`

data/.claude/commands/rubocop.md

@@ -1,22 +0,0 @@
-Run RuboCop for BugBunny. Usage: /rubocop [--fix]
-
-Ejecutá RuboCop con rubocop-rails-omakase sobre el código modificado.
-
-## Comandos
-
-Sin argumentos — solo reporte:
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec rubocop
-```
-
-Con `--fix` — autocorrect seguro:
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec rubocop -a
-```
-
-## Reglas importantes
-
-- **Solo corregir código nuevo o modificado en el PR actual** — nunca tocar código existente no relacionado
-- Si hay offenses que requieren intervención manual (no autocorregibles), reportalos con línea y descripción
-- rubocop-rails-omakase tiene opiniones fuertes sobre estilo — seguirlas sin discutir
-- Si hay un offense legítimo que debe ignorarse, usar `# rubocop:disable Cop/Name` en la línea específica con un comentario explicativo

data/.claude/commands/service-ai-setup.md

@@ -1,168 +0,0 @@
-Generate or update the complete AI documentation suite for this microservice.
-
-This skill is invoked automatically by `/pr`. It can also be run standalone.
-
-The same quality standard as BugBunny's `docs/ai/` applies here — self-contained chunks, RAG-optimized, no introductory prose.
-
----
-
-## Step 1 — Discover the current state
-
-Read in order:
-1. `docs/_index.md` — if it exists, lists all files and their purpose
-2. `docs/ai/_index.md` — if it exists, current profile and file list
-3. `CLAUDE.md` — service purpose, architecture, dependencies
-4. `config/services.yml` — declared dependencies (other services this one talks to)
-5. `config/routes.rb` or `config/initializers/bug_bunny_routes.rb` — what this service exposes
-
-If `docs/ai/` does not exist yet, this is a **first-time generation**. Create from scratch.
-If it exists, **update only the sections affected by the changes in this PR**.
-
----
-
-## Step 2 — Profile
-
-Microservices always use the **full profile** with `contracts.md` instead of `api.md`:
-
-```
-docs/ai/
-  _index.md
-  glossary.md
-  architecture.md
-  contracts.md      ← what this service exposes (queues, endpoints, events)
-  faq_internal.md
-  faq_external.md
-  antipatterns.md
-  errors.md
-```
-
----
-
-## Step 3 — Analyze the codebase
-
-Read:
-- `app/` — controllers, models, workers, services
-- `config/` — routes, initializers, services.yml
-- `lib/` — custom libraries
-- `spec/` — usage patterns and edge cases
-- `CHANGELOG.md` or git log — what changed in this PR
-
----
-
-## Step 4 — Generate or update each file
-
-Apply the same RAG optimization rules as `gem-ai-setup`:
-1. Each section ≤ 400 tokens, self-contained
-2. `faq_*.md` strict Q&A format, H3 question, answer ≤ 150 words
-3. `glossary.md` one entry per term, 1-3 lines
-4. `errors.md` one entry per error, cause + reproduction + resolution
-5. No introductory prose
-
-### `_index.md`
-
-Frontmatter manifest. Use `kind: microservice` and `transports:` listing all transports used (bug_bunny, http, etc.). List every file with its audience.
-
-```yaml
----
-type: knowledge_base
-kind: microservice
-name: service_name
-version: main        # microservices don't have semver — use branch or date
-profile: full
-language: ruby
-audiences:
-  - internal
-  - external
-transports:
-  - bug_bunny        # list actual transports used
-  - http
-files:
-  - path: glossary.md
-    audience: [internal, external]
-  - path: architecture.md
-    audience: [internal]
-  - path: contracts.md
-    audience: [external]
-  ...
----
-```
-
-### `glossary.md`
-
-Domain terms specific to this service's business domain and technical patterns.
-
-### `architecture.md`
-
-Internal-facing. Include:
-- Service responsibility (one paragraph)
-- Component map
-- Data flows for the main operations
-- External dependencies and how they're used
-- Background jobs and their triggers
-
-### `contracts.md`
-
-External-facing. The complete contract this service exposes. Include:
-
-**BugBunny queues (if applicable):**
-- Queue name, exchange, routing key, exchange type
-- For each route: method, path, request format, response format, possible errors
-- Example request and response payloads
-
-**HTTP endpoints (if applicable):**
-- Method, path, parameters, response format
-- Authentication requirements
-
-**Events published (if applicable):**
-- Exchange, routing key, payload format
-
-### `faq_internal.md`
-
-Q&A for the service developer. Cover:
-- How to add a new route or endpoint
-- How background jobs work and how to add one
-- How to add a new service dependency
-- Non-obvious architectural decisions
-
-### `faq_external.md`
-
-Q&A for developers of other services that consume this one. Cover:
-- How to make a request to this service
-- What errors to expect and how to handle them
-- How to handle retries and timeouts
-- How to test integrations against this service
-
-### `antipatterns.md`
-
-Common mistakes when interacting with or modifying this service.
-
-### `errors.md`
-
-All error responses this service can return. For each:
-- HTTP status / error code
-- When it occurs
-- What the response body looks like
-- How the caller should handle it
-
----
-
-## Step 5 — Update docs/howto/ and README.md
-
-Read `docs/_index.md` to discover which human docs exist.
-Update sections affected by this PR's changes.
-Update `README.md` last — after `docs/howto/` is updated.
-
-README structure for a microservice:
-1. Service purpose (one paragraph)
-2. Transports (BugBunny queue name, HTTP base URL)
-3. Quick start — how another service calls this one
-4. Links to `docs/ai/contracts.md` for full contract reference
-
----
-
-## Step 6 — Show diff and wait for approval
-
-Show the complete diff of all generated/updated files.
-Wait for developer approval before proceeding to PR creation.
-The developer may adjust content before confirming.
-Do NOT create the PR until the docs are approved.

data/.claude/commands/test.md

@@ -1,28 +0,0 @@
-Run RSpec tests for BugBunny. Usage: /test [path]
-
-Ejecutá la suite de tests de BugBunny con Ruby 3.3.8.
-
-## Comando base
-
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec rspec
-```
-
-Si se pasa un path como argumento, corré solo ese archivo o directorio:
-
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec rspec $ARGUMENTS
-```
-
-## Después de correr los tests
-
-- Si hay failures: analizá el error, identificá la causa raíz, proponé el fix al usuario antes de tocar código
-- Si hay warnings de deprecación: reportalos al usuario
-- Si todos pasan: confirmá con el conteo de ejemplos y tiempo de ejecución
-
-## Convenciones de RSpec en este proyecto
-
-- Tests en `spec/`
-- Sin mocks de RabbitMQ real — usar doubles de Bunny
-- Describir comportamiento, no implementación
-- Un `context` por escenario, `it` con descripción en español o inglés consistente con el archivo

data/.claude/commands/yard.md

@@ -1,46 +0,0 @@
-Validate and generate YARD documentation for BugBunny. Usage: /yard
-
-Verificá y generá la documentación YARD de la gema.
-
-## Comandos
-
-Generar docs:
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec yard doc
-```
-
-Ver métodos sin documentar:
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec yard stats --list-undoc
-```
-
-## Estándar YARD de este proyecto
-
-Todo método público nuevo o modificado debe tener:
-
-```ruby
-# Descripción breve en una línea.
-#
-# Descripción extendida opcional si la firma no es autoexplicativa.
-#
-# @param nombre [Tipo] Descripción del parámetro
-# @return [Tipo] Descripción del valor de retorno
-# @raise [ClaseError] Condición bajo la cual se lanza
-# @example
-#   resultado = mi_metodo(arg)
-def mi_metodo(nombre)
-```
-
-## Tipos comunes en este proyecto
-
-- `[String]`, `[Integer]`, `[Boolean]`, `[Hash]`, `[Array]`, `[Symbol]`
-- `[Bunny::Session]`, `[Bunny::Channel]`, `[Bunny::MessageProperties]`
-- `[BugBunny::Session]`, `[BugBunny::Request]`, `[BugBunny::Configuration]`
-- `[Proc, nil]` para callbacks opcionales
-- `[void]` para métodos sin return value relevante
-
-## Después de correr
-
-- Reportá los métodos públicos sin documentar
-- No documentar métodos privados (YARD los ignora por defecto con `private`)
-- No documentar métodos triviales (`attr_reader`, `attr_accessor`) salvo que necesiten contexto

data/docs/_index.md

@@ -1,50 +0,0 @@
-# docs/_index.md — Documentation Manifest
-
-This file is the source of truth for the `docs/` directory structure.
-It is read by the `/release` command to know which files to generate or update.
-
----
-
-## Human documentation (developers integrating BugBunny)
-
-| File | Purpose |
-|---|---|
-| `concepts.md` | AMQP in 5 min, architecture diagram, RPC vs fire-and-forget, connection pool |
-| `howto/routing.md` | Routes DSL: `resources`, `namespace`, `member`, `collection`, `recognize` |
-| `howto/controller.md` | `params`, `before_action`, `after_action`, `around_action`, `rescue_from`, `render` |
-| `howto/resource.md` | CRUD methods, typed vs dynamic attributes, dirty tracking, validations, `.with` |
-| `howto/middleware_client.md` | Client-side middlewares: built-ins, custom, usage in Client and Resource |
-| `howto/middleware_consumer.md` | Consumer-side middlewares: execution order, writing, registering |
-| `howto/tracing.md` | Trace context propagation: `rpc_reply_headers`, `on_rpc_reply`, consumer middleware |
-| `howto/rails.md` | Full Rails setup: initializer, connection pool, Zeitwerk, Puma, Sidekiq, K8s health checks |
-| `howto/testing.md` | Bunny doubles, unit tests for controllers/middleware, integration helper |
-
-These files are referenced by `README.md`. Update them before updating the README.
-
----
-
-## AI documentation (agents consuming or maintaining BugBunny)
-
-Managed by `docs/ai/_index.md`. See that file for the full manifest and audience breakdown.
-
-| File | Audience | Purpose |
-|---|---|---|
-| `ai/_index.md` | internal + external | Manifest: version, profile, file index |
-| `ai/glossary.md` | internal + external | Domain terms with precise definitions |
-| `ai/architecture.md` | internal | Internal patterns, component map, data flows |
-| `ai/api.md` | external | Public API contracts |
-| `ai/faq_internal.md` | internal | Q&A for gem maintainers |
-| `ai/faq_external.md` | external | Q&A for gem integrators |
-| `ai/antipatterns.md` | internal + external | What NOT to do and why |
-| `ai/errors.md` | external | All exceptions with cause and resolution |
-
----
-
-## Update rules for `/release`
-
-1. Run tests first. If they fail, stop.
-2. Read this file to discover all files to update.
-3. For each file in **Human documentation**: update only sections affected by the changes in this release.
-4. For each file in **AI documentation**: update only sections affected by the changes. Update `version` in `ai/_index.md`.
-5. Update `README.md` last — it depends on `docs/howto/` being up to date.
-6. Show the full diff to the developer and wait for approval before touching version or CHANGELOG.

data/docs/ai/_index.md

@@ -1,56 +0,0 @@
----
-type: knowledge_base
-kind: gem
-name: bug_bunny
-version: 4.8.0
-profile: full
-language: ruby
-generated_by: gem-ai-setup@1.0.0
-audiences:
-  - internal
-  - external
-files:
-  - path: glossary.md
-    audience: [internal, external]
-  - path: architecture.md
-    audience: [internal]
-  - path: api.md
-    audience: [external]
-  - path: faq_internal.md
-    audience: [internal]
-  - path: faq_external.md
-    audience: [external]
-  - path: antipatterns.md
-    audience: [internal, external]
-  - path: errors.md
-    audience: [external]
----
-
-## What is BugBunny?
-
-BugBunny is a Ruby gem that implements a RESTful routing layer over AMQP (RabbitMQ). It lets microservices communicate via RabbitMQ using familiar HTTP patterns: verbs (GET, POST, PUT, DELETE), controllers, declarative routes, synchronous RPC, and fire-and-forget.
-
-**Problem solved:** Eliminates direct HTTP coupling between microservices. RabbitMQ acts as the message bus with the same ergonomics as a web framework.
-
-## Version
-
-4.8.0 — April 2026
-
-## Key features in this version
-
-- Namespace routing (`namespace :admin { resources :users }`)
-- `after_action` filter (runs after action, not after `before_action` halts)
-- `render(headers:)` — inject custom headers into RPC replies
-- `Consumer#shutdown` — explicit graceful shutdown with health check cleanup
-- `Configuration#validate!` — invoked automatically at end of `BugBunny.configure`
-- Producer/Session caching per connection slot (prevents double-consumer AMQP error)
-- Expanded `SENSITIVE_KEYS` filter in `safe_log`
-- `ConsumerMiddleware::Stack` mutex for thread-safe registration
-
-## How to use this knowledge base
-
-- **Building an integration** → start with `api.md`, then `faq_external.md`
-- **Debugging errors** → `errors.md`
-- **Avoiding mistakes** → `antipatterns.md`
-- **Understanding internals** → `architecture.md`, then `faq_internal.md`
-- **Domain vocabulary** → `glossary.md`