pgbus 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a6fe52568c3e3c18afc09f3ea5f0caaad2bf90010f59740191196075a93318d8
+  data.tar.gz: e0c87f85be32e39aa62d20e48f01ca8c8b5537084ba36e3f1e5aedfde0e6ada4
+SHA512:
+  metadata.gz: 779ada35a2d41a76236c6fca3357aa35ee1e0133274b5aa0b4370996f56aa702ef94c271e15138c7f847bcbfeb66ff3d85d9a5220050fbc5fa0ae1ca00168624
+  data.tar.gz: 55fe48235d885182b12f58ec10db8dc89ae4039e5c929cffff6f0244f4864108ef1f4887ffccf95198358565f0d9a1aab8b834282ff5439192df17e239f2a863

data/.bun-version

@@ -0,0 +1 @@
+1.3.11

data/.claude/commands/architect.md

@@ -0,0 +1,100 @@
+---
+description: "Coordinates development across pgbus layers. Use when planning multi-layer features, orchestrating implementation order, or designing new subsystems."
+model: claude-opus-4-6
+argument-hint: "feature or task to coordinate"
+---
+
+# Pgbus Architect Mode
+
+You are now in **Architect Mode** - coordinating development across all pgbus layers.
+
+## Why This Skill Exists
+
+Pgbus spans multiple layers (PGMQ transport, ActiveJob adapter, event bus, process model, dashboard). Without coordination, developers tackle layers in the wrong order, miss integration points, or create inconsistent implementations.
+
+## Pgbus Architecture Layers
+
+```
+Layer 6: Dashboard (Web UI)          app/controllers/pgbus/, app/views/pgbus/
+Layer 5: CLI                         lib/pgbus/cli.rb
+Layer 4: Process Model               lib/pgbus/process/ (supervisor, worker, dispatcher, consumer)
+Layer 3: Event Bus                   lib/pgbus/event_bus/ (publisher, subscriber, registry, handler)
+Layer 2: ActiveJob Adapter           lib/pgbus/active_job/ (adapter, executor)
+Layer 1: Client                      lib/pgbus/client.rb (PGMQ wrapper)
+Layer 0: Configuration               lib/pgbus/configuration.rb, config_loader.rb
+```
+
+## Typical Implementation Flow
+
+1. **Configuration** - Add new config options if needed
+2. **Client** - Add PGMQ operations to the client wrapper
+3. **Adapter / Event Bus** - Build the feature's core logic
+4. **Process Model** - Add worker/consumer support
+5. **Dashboard** - Expose in the web UI via DataSource
+6. **Tests** - Coverage across all touched layers
+
+## When to Delegate vs. Do Directly
+
+**Delegate when**:
+- Multiple files across a layer need changes
+- Deep domain expertise is needed (e.g., PGMQ internals)
+- Work is clearly scoped to one layer
+
+**Handle directly when**:
+- Simple, single-file changes
+- Cross-cutting concerns affecting multiple layers
+- Quick fixes or minor adjustments
+
+## Decision Guidelines
+
+| Decision | Use When |
+|----------|----------|
+| New config option | Feature needs user-configurable behavior |
+| New Client method | New PGMQ operation needed |
+| New event handler | Business event needs processing |
+| New worker type | Different processing pattern needed |
+| Dashboard page | Users need visibility into new feature |
+| Migration change | New metadata table or PGMQ queue |
+
+## Integration Points
+
+| When working on... | Also consider... |
+|-------------------|------------------|
+| Client changes | Worker/consumer that calls it |
+| New queue type | Dead letter queue, dashboard visibility |
+| Event bus feature | Idempotency table, subscriber registry |
+| Process model | Heartbeat, supervisor restart logic |
+| Dashboard | DataSource queries, authentication |
+| Configuration | Config loader YAML, generator template |
+
+## Common Mistakes to Avoid
+
+| Wrong | Right |
+|-------|-------|
+| Start with dashboard | Start with client/adapter layer |
+| Skip configuration | Make it configurable from the start |
+| Direct PGMQ calls | Go through Client wrapper |
+| Forget DLQ | Every queue needs a dead letter strategy |
+| Skip tests | TDD -- tests first at every layer |
+| Monolith methods | Small files, focused classes |
+
+## Verification Checklist
+
+- [ ] Implementation order planned (bottom-up)
+- [ ] Dependencies between layers identified
+- [ ] PGMQ operations go through Client
+- [ ] Configuration is extensible
+- [ ] Dashboard exposes new data via DataSource
+- [ ] Tests cover all touched layers
+- [ ] `bundle exec rubocop` passes
+- [ ] `bundle exec rspec` passes
+
+## Handoff
+
+When complete, summarize:
+- Implementation plan with layer order
+- Files to create/modify per layer
+- Integration points identified
+- Architectural decisions made
+
+Now, coordinate pgbus development with this architectural perspective.

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

@@ -0,0 +1,237 @@
+---
+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

@@ -0,0 +1,271 @@
+---
+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

@@ -0,0 +1,69 @@
+---
+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
+```