pgbus 0.0.1 → 0.1.1

data/.claude/commands/lfg.md

@@ -1,271 +0,0 @@
----
-description: "Executes full autonomous engineering workflow with verification. Use when implementing complete features, tackling GitHub issues, or running end-to-end development cycles."
-model: claude-opus-4-6
-argument-hint: "GitHub issue number/URL or feature description"
-allowed-tools: Bash(gh issue view:*), Bash(gh search:*), Bash(gh issue list:*), Bash(gh pr create:*), Bash(gh pr view:*), Bash(bundle exec:*), Bash(git:*), Read, Write, Edit, Glob, Grep, Agent
----
-
-# LFG - Full Autonomous Workflow
-
-Execute a complete engineering workflow with verification at each phase.
-
-## Phase 0: Branch Setup
-
-**BEFORE any other work, prepare the git branch:**
-
-1. Check the current branch: `git branch --show-current`
-2. If NOT on `main`, switch: `git checkout main`
-3. Pull latest: `git pull origin main`
-4. Create feature branch: `git checkout -b issue-{number}-{brief-description}` (or `feature/{description}` if no issue number)
-
----
-
-## Phase 1: Understand
-
-### Step 1: Gather Requirements
-
-If `$ARGUMENTS` is a GitHub issue number or URL:
-
-```bash
-gh issue view <number> --json title,body,labels,assignees,comments
-```
-
-If `$ARGUMENTS` is a description, use it directly.
-
-### Step 2: Define Acceptance Criteria
-
-**MANDATORY:** Write explicit acceptance criteria:
-
-- **GIVEN** [context/setup]
-- **WHEN** [action taken]
-- **THEN** [expected outcome]
-
-You MUST NOT proceed until you can articulate these clearly.
-
-### Step 3: Comprehension Gate
-
-Before proceeding, you must:
-
-1. State the problem/feature in one sentence
-2. Explain WHY this is needed (business context)
-3. List what will change from the user's perspective
-4. Identify edge cases not explicitly mentioned
-5. Explain the data flow or code path involved
-
-If you cannot complete ALL five items, investigate further.
-
-### Step 4: Create Task List
-
-Create a TaskCreate todo list with specific implementation steps.
-
----
-
-## Phase 2: Explore
-
-1. Find related files (Glob/Grep or Explore agent)
-2. Read existing patterns in similar features
-3. Understand dependencies and integration points
-4. Check existing test coverage
-5. Review PGMQ client interactions in `lib/pgbus/client.rb`
-6. Check ActiveJob adapter in `lib/pgbus/active_job/`
-7. Review event bus patterns in `lib/pgbus/event_bus/`
-8. Check process model in `lib/pgbus/process/`
-
----
-
-## Phase 3: Plan
-
-1. List files to modify with specific changes
-2. List new files to create with purpose
-3. Identify migration changes needed (PGMQ queues, metadata tables)
-4. Plan test coverage (TDD: tests FIRST)
-5. Update task list with implementation steps
-6. Consider backwards compatibility with existing queue configurations
-
----
-
-## Phase 4: Implement (TDD)
-
-For each logical unit:
-
-### 4.1: Write Failing Test First
-
-Create a test that demonstrates the expected behavior. Run it to confirm it FAILS:
-
-```bash
-bundle exec rspec <spec_file>
-```
-
-### 4.2: Implement Minimum Code
-
-Write the MINIMUM code to make the test pass. Follow project patterns:
-
-| Never Do | Always Do |
-|----------|-----------|
-| Direct PGMQ SQL calls | Use `Pgbus::Client` wrapper |
-| Skip queue prefixing | Always use `config.queue_name()` |
-| Hardcode queue names | Use configuration |
-| Skip visibility timeout | Use PGMQ's native VT mechanism |
-| Ignore dead letter routing | Check `read_ct` against `max_retries` |
-| Raw SQL in controllers | Use `Web::DataSource` for dashboard |
-
-### 4.3: Refactor
-
-Once green, refactor while keeping tests passing.
-
-### 4.4: Validate
-
-```bash
-bundle exec rubocop <changed_files>
-```
-
-### 4.5: Repeat
-
-Move to next logical unit. Mark task items complete.
-
----
-
-## Phase 5: Deep Root Cause Analysis (Bug Fixes Only)
-
-**If this is a bug fix, apply deep investigation before implementing:**
-
-### Trace the Data Lifecycle
-
-For the message/job/event causing the issue:
-- Where and when was the message enqueued? By what adapter call?
-- What visibility timeout was set? Has it expired?
-- What ASSUMPTIONS does the code make at the failure point?
-- Which assumption was violated, and WHY?
-
-### Use Git History
-
-```bash
-git log --oneline -20 <file>
-git blame <file>
-```
-
-- When was the code written? What was the original intent?
-- Has something ELSE changed that invalidated the original assumptions?
-
-### Map All Callers
-
-Don't just look at the method that failed:
-- Use Grep to find all call sites
-- Different contexts (ActiveJob adapter vs event bus vs dashboard)?
-- Does the error only happen in ONE context? Why?
-
-### Five Whys
-
-Keep asking WHY until you reach a meaningful fix point:
-
-1. Error: X happened -> Why?
-2. Because Y -> Why was Y in that state?
-3. Because Z -> Why wasn't Z prevented?
-4. Because no check existed -> Why not?
-5. **THIS** is where the fix belongs
-
-### Fix Location Principle
-
-The best fix is usually NOT where the error is raised:
-- Nil message in executor -> fix in worker that should provide non-nil
-- Queue not found -> fix in code that should ensure_queue first
-- Race condition -> PGMQ-level visibility timeout
-- Dead letter overflow -> fix the retry/DLQ routing logic
-
-**Ask: "Where is the EARLIEST point I could prevent this error?" Fix there.**
-
-### Unacceptable Superficial Fixes -- DO NOT DO THESE
-
-- `rescue nil` without understanding why the exception occurs
-- `&.` to silence nil errors without investigating why nil occurs
-- `if object.present?` guards without understanding why missing
-- `return if message.nil?` to silently skip processing
-- Wrapping everything in `begin/rescue` to swallow errors
-
-**These HIDE bugs. The root cause continues causing issues elsewhere.**
-
----
-
-## Phase 6: Verify
-
-**ALL of these must pass before committing:**
-
-```bash
-bundle exec rubocop              # Style
-bundle exec rspec <relevant_specs>  # Tests
-```
-
-### Solution Verification
-
-Re-read the original requirements and verify:
-- "If I were the requester, would I consider this fully resolved?"
-- "Have I addressed the ROOT CAUSE, not just the symptom?"
-- "Do my tests prove the issue is ACTUALLY fixed, not just suppressed?"
-- "Does this maintain backwards compatibility?"
-
----
-
-## Phase 7: Commit & PR
-
-### Commit
-
-```bash
-git add <specific_files>
-git commit -m "$(cat <<'EOF'
-feat(scope): brief description
-
-## Summary
-[What changed and why]
-
-## Test Coverage
-- spec 1: validates requirement X
-- spec 2: validates edge case Y
-
-## Verification
-- [x] bundle exec rubocop passes
-- [x] bundle exec rspec passes
-EOF
-)"
-```
-
-### Push & PR
-
-```bash
-git push -u origin $(git branch --show-current)
-
-gh pr create --title "feat(scope): brief description" --body "$(cat <<'EOF'
-## Summary
-- Key change 1
-- Key change 2
-
-Closes #<issue_number>
-
-## Test plan
-- [ ] Scenario 1
-- [ ] Scenario 2
-EOF
-)"
-```
-
----
-
-## Verification Checklist
-
-- [ ] All acceptance criteria met
-- [ ] Tests written BEFORE implementation
-- [ ] `bundle exec rubocop` passes
-- [ ] `bundle exec rspec` passes
-- [ ] Backwards compatibility maintained
-- [ ] PGMQ operations go through Client wrapper
-- [ ] PR created with description
-
----
-
-## Handoff
-
-When complete:
-- All phases executed
-- Verification passed
-- PR created and linked
-
-Now, execute this workflow for the provided issue or feature.

data/.claude/commands/review-pr.md

@@ -1,69 +0,0 @@
----
-description: Review a GitHub pull request for code quality, patterns, and best practices
-model: claude-opus-4-6
-argument-hint: "PR URL or number (e.g., 5 or https://github.com/mhenrixon/pgbus/pull/5)"
----
-
-# PR Review
-
-Review PR for pattern compliance and issues. Be concise.
-
-## Workflow
-
-1. Fetch PR details and diff via `mcp__github__pull_request_read`
-2. Categorize files by type
-3. Check for pattern violations
-4. Output structured review
-
-## Pattern Violations to Check
-
-```ruby
-# WRONG -> RIGHT
-Direct PGMQ calls outside Client   -> Use Pgbus::Client wrapper
-Raw SQL in controllers/views        -> Use Web::DataSource
-Hardcoded queue names               -> Use config.queue_name()
-Missing visibility timeout          -> Always pass vt: parameter
-Skip dead letter routing            -> Check read_ct > max_retries
-No error handling in workers        -> Rescue and log via Pgbus.logger
-Polling without LISTEN/NOTIFY       -> Use enable_notify_insert
-Missing queue prefix                -> All queues go through config.queue_name
-Thread.new for concurrency          -> Use Concurrent::* primitives
-rescue StandardError => nil         -> Specific error handling
-```
-
-## Output Format
-
-```
-## Files Requiring Manual Review
-
-| File | Reason |
-|------|--------|
-| lib/pgbus/process/worker.rb | Worker recycling logic, verify thresholds |
-| lib/pgbus/client.rb | PGMQ interaction, check thread safety |
-
-## Critical Issues
-
-- `lib/pgbus/client.rb:45` - Missing mutex synchronization
-- `lib/pgbus/process/worker.rb:12` - Memory check not platform-aware
-
-## Suggestions (non-blocking)
-
-- Consider extracting X to shared module
-
-## Verdict
-
-**Request Changes** - Fix thread safety before merge
-```
-
-## Tools
-
-```
-mcp__github__pull_request_read
-  method: "get"        -> PR details
-  method: "get_diff"   -> Changes
-  method: "get_files"  -> File list
-  method: "get_status" -> CI status
-
-bundle exec rubocop    -> Style checks
-bundle exec rspec      -> Tests
-```

data/.claude/commands/security.md

@@ -1,122 +0,0 @@
----
-description: "Reviews code for security vulnerabilities. Use when auditing PGMQ operations, connection handling, SQL injection risks, or dashboard authentication."
-model: claude-opus-4-6
-argument-hint: "code, feature, or area to review for security"
----
-
-# Security Specialist
-
-You are the **Security review and vulnerability audit specialist** for pgbus.
-
-## Trigger Contexts
-
-Use this skill when:
-- Auditing PGMQ SQL operations for injection risks
-- Reviewing connection pool handling
-- Checking for race conditions in message processing
-- Reviewing deserialization of job arguments / event payloads
-- Auditing the dashboard web UI
-- Reviewing worker process management
-
-## Key Security Concerns for This Gem
-
-### SQL Injection via Queue Names
-
-```ruby
-# BAD: Unsanitized queue name in SQL
-connection.execute("SELECT * FROM pgmq.q_#{queue_name}")
-
-# GOOD: Sanitize queue names
-def sanitize_name(name)
-  name.gsub(/[^a-zA-Z0-9_]/, "")
-end
-```
-
-PGMQ queue names are interpolated into SQL identifiers. The `Client` validates names, but any new code touching queue names must sanitize.
-
-### Connection Pool Safety
-
-- pgmq-ruby uses `connection_pool` gem for thread-safe pooling
-- Never hold a connection across async boundaries
-- `TransactionalClient` pins a single connection -- ensure it's not leaked
-- When using `-> { ActiveRecord::Base.connection.raw_connection }`, connection lifecycle is Rails-managed
-
-### Message Deserialization
-
-```ruby
-# BAD: Unsafe deserialization
-Marshal.load(message.message)
-
-# GOOD: JSON only
-JSON.parse(message.message)
-```
-
-- All payloads are JSONB -- stick to JSON.parse
-- ActiveJob's `deserialize` handles GlobalID resolution -- trust it but validate
-- Event payloads with `_global_id` call `GlobalID::Locator.locate` -- ensure objects exist
-
-### Dashboard Authentication
-
-- `web_auth` block receives the raw request -- must be configured by the host app
-- Default is `nil` (allow all) -- document this clearly
-- Dashboard inherits from `ActionController::Base` (isolated from host app)
-- Never expose raw PGMQ internals without sanitization
-- Filter sensitive job arguments in the UI
-
-### Worker Process Security
-
-- Supervisor forks child processes -- signal handling must be correct
-- Worker recycling kills processes -- ensure graceful cleanup
-- Heartbeat writes to DB -- validate process ownership
-- Memory measurement uses `ps` / `/proc` -- no shell injection risk (pid is numeric)
-
-### Visibility Timeout / Message Safety
-
-- Messages become visible again after VT expires -- idempotency is critical
-- `read_ct` tracks redeliveries -- DLQ routing must be reliable
-- `FOR UPDATE SKIP LOCKED` prevents double-processing -- verify all read paths use it
-- Archive vs delete: archived messages are queryable, deleted are gone
-
-## Verification Checklist
-
-- [ ] No SQL injection via queue names
-- [ ] All PGMQ operations go through Client (sanitized)
-- [ ] Connection pool properly managed
-- [ ] No unsafe deserialization (JSON only)
-- [ ] Dashboard auth is configurable and documented
-- [ ] Worker signals handled correctly
-- [ ] No secrets in logs or error messages
-- [ ] Idempotency enforced for event handlers
-
-## Security Tools
-
-```bash
-# Static analysis
-bundle exec rubocop
-
-# Check for known vulnerabilities in dependencies
-bundle audit check --update
-
-# Review queue name handling
-grep -r "pgmq\.q_\|pgmq\.a_" lib/
-```
-
-## Common Mistakes to Avoid
-
-| Wrong | Right |
-|-------|-------|
-| String interpolation in SQL | Parameterized queries or sanitized identifiers |
-| Marshal.load on payloads | JSON.parse only |
-| Global PGMQ client without pool | Connection pool with thread safety |
-| Default-open dashboard | Require explicit auth configuration |
-| Swallowing worker errors | Log and track via failed_events table |
-| Infinite visibility timeout | Always set reasonable VT with DLQ fallback |
-
-## Handoff
-
-When complete, summarize:
-- Vulnerabilities found (with severity)
-- Remediation steps
-- Tests to add
-
-Now, focus on security review for the current task.

data/.claude/commands/tdd.md

@@ -1,148 +0,0 @@
----
-description: "Use when implementing any feature or fixing any bug -- enforces RED-GREEN-REFACTOR: write failing test first, implement minimum code to pass, then refactor."
----
-
-# TDD Command
-
-Enforce test-driven development methodology with RED -> GREEN -> REFACTOR cycle.
-
-## The TDD Cycle
-
-```text
-RED -> GREEN -> REFACTOR -> REPEAT
-
-RED:      Write a failing test (test MUST fail first)
-GREEN:    Write MINIMAL code to pass (nothing more)
-REFACTOR: Improve code while keeping tests green
-REPEAT:   Next feature/scenario
-```
-
-## When to Use
-
-- Implementing new features
-- Adding new queue types or event handlers
-- Fixing bugs (write test that reproduces bug FIRST)
-- Refactoring existing code
-- Modifying the ActiveJob adapter
-- Changing worker/process behavior
-- Adding dashboard endpoints
-
-## Workflow
-
-### Step 1: Write Failing Tests (RED)
-
-```ruby
-# spec/pgbus/example_spec.rb
-RSpec.describe Pgbus::NewFeature do
-  describe "#process" do
-    context "when message is valid" do
-      it "processes successfully" do
-        expect(subject.process(message)).to eq(:success)
-      end
-    end
-
-    context "when max retries exceeded" do
-      it "routes to dead letter queue" do
-        expect(subject.process(stale_message)).to eq(:dead_lettered)
-      end
-    end
-  end
-end
-```
-
-### Step 2: Run Tests - Verify FAIL
-
-```bash
-bundle exec rspec spec/pgbus/example_spec.rb
-
-FAIL - NotImplementedError / Expected behavior not met
-```
-
-**Tests MUST fail before implementing.** This confirms:
-- Tests are actually running
-- Tests are testing the right thing
-- Implementation doesn't already exist
-
-### Step 3: Implement Minimal Code (GREEN)
-
-Write the minimum code to make the test pass.
-
-### Step 4: Run Tests - Verify PASS
-
-```bash
-bundle exec rspec spec/pgbus/example_spec.rb
-
-N examples, 0 failures
-```
-
-### Step 5: Refactor (IMPROVE)
-
-Improve code while keeping tests green:
-- Extract methods to reduce complexity
-- Improve naming
-- Reduce duplication
-- Ensure thread safety
-
-### Step 6: Run Full Suite
-
-```bash
-bundle exec rspec
-```
-
-## Coverage Requirements
-
-| Code Type | Minimum Coverage |
-|-----------|------------------|
-| All code | 80% |
-| ActiveJob adapter | 100% |
-| Event bus (handler, registry) | 100% |
-| Process model (worker, supervisor) | 100% |
-| Client (PGMQ wrapper) | 100% |
-| Web::DataSource | 100% |
-| Configuration | 100% |
-
-## Test Types to Include
-
-### Unit Tests (Configuration, Event, Serializer)
-- Happy path scenarios
-- Edge cases (nil values, empty queues, expired VT)
-- Error conditions
-
-### Integration Tests (Client, Adapter, Worker)
-- ActiveJob enqueue/execute lifecycle
-- Worker claim-process-archive flow
-- Dead letter queue routing
-- Event publish/subscribe round-trip
-
-### Web Tests (DataSource, Authentication)
-- DataSource with mocked PGMQ client
-- Authentication block allow/deny
-- Helper formatting
-
-## Best Practices
-
-**DO:**
-- Write the test FIRST, before any implementation
-- Run tests and verify they FAIL before implementing
-- Write MINIMAL code to make tests pass
-- Refactor only after tests are green
-- Mock PGMQ client in unit tests (avoid DB dependency)
-- Test worker recycling thresholds explicitly
-
-**DON'T:**
-- Write implementation before tests
-- Skip running tests after each change
-- Write too much code at once
-- Ignore failing tests
-- Test implementation details (test behavior)
-- Skip testing error paths
-
-## Checklist
-
-- [ ] Tests written BEFORE implementation
-- [ ] Tests fail initially (RED phase verified)
-- [ ] Minimal code written to pass (GREEN)
-- [ ] Code refactored with tests still passing
-- [ ] Coverage meets requirements (80%+)
-- [ ] All edge cases covered
-- [ ] Backwards compatibility maintained

data/.claude/rules/agents.md

@@ -1,49 +0,0 @@
-# Agent Orchestration Rules
-
-## Available Agents
-
-| Agent | Purpose | When to Use |
-|-------|---------|-------------|
-| Explore | Codebase exploration | Finding files, understanding patterns |
-| Plan | Implementation planning | Complex features, architectural decisions |
-| general-purpose | Multi-step tasks | Research, complex searches |
-
-## Immediate Agent Usage
-
-Use agents PROACTIVELY without waiting for user prompt:
-
-1. **Complex feature requests** -> Use Plan agent first
-2. **Codebase exploration** -> Use Explore agent
-3. **Multi-file searches** -> Use Explore agent (not direct Glob/Grep)
-4. **Architectural decisions** -> Use Plan agent
-
-## Parallel Execution
-
-**ALWAYS** use parallel Task execution for independent operations:
-
-```markdown
-# GOOD: Parallel execution
-Launch multiple agents simultaneously:
-1. Agent 1: Explore client/adapter patterns
-2. Agent 2: Check event bus patterns
-3. Agent 3: Review test coverage
-
-# BAD: Sequential when unnecessary
-First explore, wait, then check patterns, wait, then review...
-```
-
-## When to Use Explore Agent
-
-Use the Explore agent (subagent_type=Explore) instead of direct Glob/Grep when:
-- Open-ended codebase exploration
-- Searching for patterns across client, adapter, event bus, and process layers
-- Answering questions about codebase structure
-- Finding related implementations across modules
-
-## When NOT to Use Agents
-
-Use direct tools when:
-- Reading a specific known file path
-- Simple pattern match in known location
-- Single-file edits
-- Running specific commands