pgbus 0.0.1 → 0.1.2

data/.claude/commands/github-review-comments.md

@@ -1,237 +0,0 @@
----
-description: "Use when a PR has unresolved review comments that need responses -- evaluates each comment, implements valid fixes, pushes back on incorrect suggestions, and resolves all threads."
-model: claude-opus-4-6
-argument-hint: "PR number (e.g., 123 or #123)"
-allowed-tools: Bash(gh pr view:*), Bash(gh pr diff:*), Bash(gh pr comment:*), Bash(gh api:*), Bash(git log:*), Bash(git blame:*), Bash(git push:*), Bash(git commit:*), Bash(git add:*), Bash(bundle exec:*), Read, Write, Edit, Glob, Grep, Agent
----
-
-# Review GitHub PR Comments: $ARGUMENTS
-
-You are reviewing and responding to all unresolved review comments on a GitHub pull request. Apply technical rigour -- evaluate each comment against the actual codebase before accepting or rejecting it.
-
-## Phase 0: Determine the PR Number
-
-The user may provide a PR number as `$ARGUMENTS`. Parse it flexibly:
-
-- `PR123`, `PR 123`, `pr123` -> PR 123
-- `123` -> PR 123
-- `#123` -> PR 123
-- Empty/blank -> auto-detect from current branch
-
-**If no PR number is provided**, detect it automatically:
-
-```bash
-gh pr list --author=@me --head="$(git branch --show-current)" --state=open --json number,title
-```
-
-If exactly one open PR exists for the current branch, use it. If none or multiple, ask the user.
-
-Once you have the PR number, confirm it:
-
-```bash
-gh pr view <PR_NUMBER> --json title,state,url
-```
-
----
-
-## Phase 1: Fetch All Unresolved Review Comments
-
-Retrieve all review comments and identify unresolved ones:
-
-```bash
-# Get all review comments (not resolved)
-gh api "repos/mhenrixon/pgbus/pulls/<PR_NUMBER>/comments" --paginate
-
-# Get all review threads to check resolution status
-gh api graphql -f query='
-  query($owner: String!, $repo: String!, $pr: Int!) {
-    repository(owner: $owner, name: $repo) {
-      pullRequest(number: $pr) {
-        reviewThreads(first: 100) {
-          nodes {
-            id
-            isResolved
-            path
-            line
-            comments(first: 20) {
-              nodes {
-                id
-                databaseId
-                body
-                author { login }
-                createdAt
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-' -f owner=mhenrixon -f repo=pgbus -F pr=<PR_NUMBER>
-```
-
-For each unresolved thread, extract:
-- Thread ID (for resolving)
-- Comment body (the review feedback)
-- File path and line number (if inline)
-- Author (to understand context)
-
-Filter to only **unresolved** threads. Skip bot comments (CodeRabbit, dependabot), resolved threads, and PR description comments.
-
-If there are no unresolved review comments, report that and stop.
-
----
-
-## Phase 2: Read and Categorise Each Comment
-
-For each unresolved comment, read the full body and categorise it:
-
-| Category | Action |
-|----------|--------|
-| Valid fix needed | Implement the fix |
-| Valid test gap | Add the missing test |
-| Valid style/consistency issue | Fix it |
-| Incorrect suggestion | Push back with technical reasoning |
-| Suggestion conflicts with architecture | Push back, reference existing patterns |
-| Over-engineering / YAGNI | Push back, explain why it's unnecessary |
-| Unclear | Ask for clarification (do NOT implement) |
-
-**Before categorising**, always:
-1. Read the actual file and line being commented on
-2. Check if the suggestion is technically correct for THIS codebase
-3. Check if it would break existing functionality
-4. Check if existing patterns/conventions contradict the suggestion
-5. Check CLAUDE.md rules -- project conventions override reviewer preferences
-
----
-
-## Phase 3: Implement Accepted Fixes
-
-For all comments you've decided to accept:
-
-1. **Make the code changes** -- edit the relevant files
-2. **Run affected tests** to verify nothing breaks:
-   ```bash
-   bundle exec rspec <relevant_spec_files>
-   ```
-3. **Run validators**:
-   ```bash
-   bundle exec rubocop <changed_files>
-   ```
-4. **Commit** all fixes together with a clear message:
-   ```bash
-   git commit -m "$(cat <<'EOF'
-   fix: address PR review feedback
-
-   - Description of fix 1
-   - Description of fix 2
-   EOF
-   )"
-   ```
-5. **Push** to the remote branch:
-   ```bash
-   git push
-   ```
-
----
-
-## Phase 4: Reply to Every Comment
-
-For **each** unresolved thread, reply:
-
-### For accepted fixes:
-
-Reply with what was fixed and the commit SHA:
-
-```bash
-gh api "repos/mhenrixon/pgbus/pulls/<PR>/comments/<COMMENT_ID>/replies" \
-  --method POST \
-  -f 'body=Fixed in <SHA>. <Brief description of what changed>.'
-```
-
-### For rejected suggestions:
-
-Reply with technical reasoning:
-
-```bash
-gh api "repos/mhenrixon/pgbus/pulls/<PR>/comments/<COMMENT_ID>/replies" \
-  --method POST \
-  -f 'body=<Technical explanation of why the suggestion was not implemented>'
-```
-
-### Resolving threads (via GraphQL):
-
-After replying, resolve the thread:
-
-```bash
-gh api graphql -f query='
-  mutation($threadId: ID!) {
-    resolveReviewThread(input: {threadId: $threadId}) {
-      thread { isResolved }
-    }
-  }
-' -f threadId=<THREAD_NODE_ID>
-```
-
-### For general PR comments (not inline review threads):
-
-Reply directly:
-
-```bash
-gh pr comment <PR_NUMBER> --body "<Response addressing each point>"
-```
-
----
-
-## Phase 5: Verify Completion
-
-After processing all comments, verify no unresolved threads remain:
-
-```bash
-gh api graphql -f query='
-  query($owner: String!, $repo: String!, $pr: Int!) {
-    repository(owner: $owner, name: $repo) {
-      pullRequest(number: $pr) {
-        reviewThreads(first: 100) {
-          totalCount
-          nodes { isResolved }
-        }
-      }
-    }
-  }
-' -f owner=mhenrixon -f repo=pgbus -F pr=<PR_NUMBER>
-```
-
-Report the final tally: how many comments were accepted/fixed, how many were pushed back on, and confirm all threads are resolved.
-
----
-
-## Response Style
-
-When replying to comments:
-
-- **No performative agreement** -- never say "Great point!" or "You're absolutely right!"
-- **No gratitude** -- never say "Thanks for catching that"
-- **Be direct** -- state the fix or the reasoning, nothing more
-- **Reference commits** -- always include the short SHA when a fix was made
-- **Be specific** -- when pushing back, reference actual code, not abstract principles
-
-When pushing back:
-
-- Use technical reasoning grounded in the actual codebase
-- Reference existing patterns if the suggestion contradicts them
-- Reference CLAUDE.md rules when applicable
-- Explain what would break or what edge case the reviewer missed
-- If the suggestion is valid in principle but wrong for this context, say so
-
----
-
-## Important Notes
-
-- Always read the actual code before evaluating a comment -- reviewers sometimes misread diffs
-- If a comment reveals a genuine bug you missed, fix it without defensiveness
-- If multiple comments suggest the same change, implement it once and reference the fix in all replies
-- Bot reviewers (CodeRabbit, etc.) sometimes suggest changes that conflict with project conventions -- verify against CLAUDE.md
-- If a new round of review comments appears after your push (from re-review), report that to the user rather than entering an infinite loop
-
-Now begin by determining the PR number from `$ARGUMENTS` or the current branch.

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.