Skip to content

feat: beads-rust tracker plugin and improvements#179

Merged
subsy merged 24 commits intomainfrom
feat/beads-rust-tracker-plugin
Jan 21, 2026
Merged

feat: beads-rust tracker plugin and improvements#179
subsy merged 24 commits intomainfrom
feat/beads-rust-tracker-plugin

Conversation

@subsy
Copy link
Copy Markdown
Owner

@subsy subsy commented Jan 21, 2026

Summary

This PR introduces a new beads-rust (br) tracker plugin for ralph-tui, along with several improvements and fixes:

New Features

  • Beads-Rust Tracker Plugin - Full integration with the br CLI for issue tracking

    • Detection, task listing, single task retrieval via JSON output
    • Support for parent-child filtering via getChildIds() helper
    • Epic and PRD context support
    • Complete test coverage (91.5% for the plugin)
  • Land-the-Plane Skill - Session completion protocol extracted to a global skill

    • 8-step landing sequence for AI agents
    • Ensures all work is committed and pushed before session end

Bug Fixes

  • Progress.md Notes Filtering - Fixed issue where tool output (line numbers like 00123|, XML markers) appeared in progress notes

    • Added isToolOutputLine() helper to filter out Read tool output
    • Comprehensive tests for the filtering logic
  • Beads-BV Epic Filtering - Fixed epic child filtering in beads-bv tracker

Documentation

  • Updated AGENTS.md and CLAUDE.md with beads-rust (br) command reference
  • Removed outdated beads Go (bd) and beads viewer (bv) documentation

Tests

  • Added progress.test.ts with 24 tests for notes extraction and file operations
  • Added beads-bv/index.test.ts with 10 unit tests
  • Added comprehensive beads-rust/index.test.ts with 48 tests

Test plan

  • bun run typecheck passes
  • bun run build succeeds
  • bun test passes (all new tests)
  • Manual testing with beads-rust tracker

Summary by CodeRabbit

  • New Features

    • Added a beads-rust tracker integration with PRD-driven template and OpenCode event output handling.
  • Improvements

    • Improved progress-note extraction to filter tool output and limit noise.
    • Safer fallback when primary recommendations yield no tasks.
  • Documentation

    • Major rewrites and new docs/READMEs/tutorials for trackers and skills.
  • Tests

    • Large expansion of tests for progress handling, trackers and output parsing.
  • Chores

    • Tracked beads data, added config/metadata/issues export and updated CI/test orchestration.

✏️ Tip: You can customize this high-level summary in your review settings.

AI Agent added 20 commits January 20, 2026 20:40
- beads-bv: Fall back to base beads getNextTask() when bv's global
  top-N recommendations don't include any tasks from the current epic
- output-parser: Add OpenCode-specific JSONL parsing for historical
  iteration logs and streaming output (text, tool_use, tool_result,
  step_start, step_finish, error event types)
The Notes field in progress.md was capturing Read tool output with line
numbers (e.g., "00588| const foo...") because extractCompletionNotes()
simply grabbed the last 500 chars before <promise>COMPLETE</promise>.

Added isToolOutputLine() helper that filters:
- Read tool line-numbered output (00001|, 123|, etc.)
- XML tool markers (<file>, </file>, <function_results>)
- Closing XML tags (</invoke>, etc.)
- Code punctuation artifacts (}, });, |)

Now progress.md notes contain meaningful agent summary text.

Also includes updates to AGENTS.md and CLAUDE.md.
Uninstalled beads from this repository:
- Stopped daemon
- Removed git hooks (pre-commit, post-merge, pre-push, post-checkout, prepare-commit-msg)
- Removed merge driver configuration
- Removed .gitattributes
- Removed .beads directory
- Removed .git/beads-worktrees
- Removed .beads/ from .gitignore to enable version control
- Initialized beads_rust workspace with br init
- Database (beads.db) stays local, config and issues.jsonl are tracked
- Fix beads-rust tracker to not use --parent flag (br doesn't support it)
  - getTasks() now uses getChildIds() to filter by parent in-memory
  - getNextTask() uses same approach with br ready
  - getPrdContext() uses epic's dependents field for child count
- Update AGENTS.md and CLAUDE.md with beads-rust (br) instructions
  - Replace all bd/bv references with br commands
  - Document br CLI: create, list, ready, show, dep, sync
  - Add priority levels, issue types, JSON output examples
- Configure issue_prefix to 'ralph-tui' in .beads/config.yaml
- Add test epic and tasks for tracker plugin testing
- Fixed test assertions to match actual implementation behavior
- Beads-rust tracker uses in-memory filtering for parent IDs rather than CLI flags
- getTasks() correctly filters parent tasks via getChildIds() lookup
- getNextTask() correctly filters ready tasks by parent via getChildIds()
- getPrdContext() correctly extracts completion stats from epic's dependents
- All 31 CRUD operation tests now pass with 89% function coverage
- Verified typecheck and build succeed
Replaced the inline "Landing the Plane" section with a reference to
the /land-the-plane skill. The skill is installed globally at:
- ~/.claude/skills/land-the-plane/
- ~/.factory/skills/land-the-plane/
- ~/.config/opencode/skill/land-the-plane/

The skill provides a comprehensive session completion checklist with:
- Pre-flight checklist
- 8-step landing sequence
- Quality gate verification
- Git push enforcement
- Hand-off template
- Add comprehensive tests for progress.ts notes extraction
  - Test tool output filtering (line numbers, XML markers)
  - Test insights extraction from agent output
  - Test file operations (append, read, clear, truncation)
  - Test codebase patterns extraction

- Add unit tests for BeadsBvTrackerPlugin
  - Test plugin metadata and capabilities
  - Test template content
  - Test reasoning methods initial state
  - Test TaskReasoning interface exports
@vercel
Copy link
Copy Markdown

vercel bot commented Jan 21, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Review Updated (UTC)
ralph-tui Ignored Ignored Preview Jan 21, 2026 1:04pm

Request Review

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Jan 21, 2026

Walkthrough

Adds a new beads‑rust tracker plugin (with CLI integration, PRD/template support and tests), commits a tracked .beads/ directory with metadata and issue records, tightens progress-note extraction and tests, adjusts beads‑bv getNextTask fallback, and extends the TUI output parser to handle OpenCode JSONL events.

Changes

Cohort / File(s) Summary
Beads directory config
\.beads/.gitignore, \.beads/config.yaml, \.beads/metadata.json, \.beads/issues.jsonl
Track .beads/ in repo: add config (issue_prefix), metadata pointing to beads.db & issues.jsonl, ignore DB/lock/tmp artifacts and provide an initial JSONL dump of issues.
Git attrs / ignore
\.gitattributes, \.gitignore
Remove .beads/ from .gitignore and drop the custom merge driver entry for .beads/issues.jsonl.
Tracker: beads‑rust
src/plugins/trackers/builtin/beads-rust/index.ts, .../index.test.ts, template.hbs, README.md
New plugin: detection (.beads + br), execBr wrapper, mappings for br JSON → TrackerTask, getTasks/getTask/getEpics/getNextTask, complete/update/sync, PRD context loading, template rendering & caching; comprehensive tests and a Handlebars template. Exports BeadsRustDetectResult, execBr, BeadsRustTrackerPlugin, createBeadsRustTracker.
Tracker registry / exports
src/plugins/trackers/builtin/index.ts
Register and export createBeadsRustTracker and add 'beads-rust' to builtinTrackers.
Tracker: beads‑bv
src/plugins/trackers/builtin/beads-bv/index.ts, .../index.test.ts
getNextTask now falls back to base implementation when bv yields no matches; add unit tests validating metadata, template behaviour and reasoning types.
TUI output parsing
src/tui/output-parser.ts, src/tui/output-parser.test.ts
Add OpenCode detection, OpenCodeEvent types, parsing and display/stream formatting; integrate into both streaming and non‑streaming flows and add tests for OpenCode JSONL handling.
Progress logging & tests
src/logs/progress.ts, src/logs/progress.test.ts
Add isToolOutputLine helper; refine extractCompletionNotes to ignore tool output and pick up to five meaningful lines; add extensive tests for notes, insights and file I/O.
Documentation & guides
AGENTS.md, CLAUDE.md, skills/ralph-tui-create-beads-rust/SKILL.md, skills/ralph-tui-create-beads/SKILL.md, src/plugins/trackers/builtin/beads-rust/README.md, website/content/docs/plugins/trackers/beads-rust.mdx, website/lib/navigation.ts, website/content/docs/plugins/trackers/beads-bv.mdx, website/content/docs/plugins/trackers/beads.mdx
Large documentation updates to introduce beads‑rust workflows, PRD-driven guidance, README, skill docs, website page and nav entry; also remove default ralph label in examples and mark label filtering optional.
Build / templates
package.json, src/plugins/trackers/builtin/.../template.hbs
Add build:templates step to copy beads‑rust template into dist and include new template asset.
CI workflow
.github/workflows/ci.yml
Split plugin tests (isolate beads-bv and beads-rust runs) and update coverage uploads to include separate lcov files for these plugins.

Sequence Diagram(s)

sequenceDiagram
    participant TUI as TUI
    participant Plugin as BeadsRustTrackerPlugin
    participant BR as br CLI
    participant FS as File System

    TUI->>Plugin: getTasks(filter)
    Plugin->>Plugin: verify .beads exists & locate br
    Plugin->>BR: execBr(['list','--format=json', ...filters])
    BR-->>Plugin: JSON output
    Plugin->>Plugin: parse & map tasks → TrackerTask[]
    Plugin->>FS: read `.beads/metadata.json` / `.beads/issues.jsonl`
    FS-->>Plugin: metadata / issue records
    Plugin->>Plugin: attach parents/dependencies & PRD context
    Plugin-->>TUI: return TrackerTask[]

    TUI->>Plugin: completeTask(taskId, notes)
    Plugin->>BR: execBr(['close', taskId, ...])
    BR-->>Plugin: success
    Plugin->>FS: append progress to `.beads/progress.md`
    Plugin-->>TUI: updated task
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

Poem

🐇 I hopped in with a rust-made kit and handy br,

PRDs tucked neat, templates guiding each small spar,
I sifted noisy notes, five true lines I chose,
OpenCode sang while BV learned fallback prose,
A rabbit cheers — tracked, tidy, ready for the bar.

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'feat: beads-rust tracker plugin and improvements' clearly and concisely summarizes the primary change—introducing a new beads-rust tracker plugin with related enhancements and fixes.
Docstring Coverage ✅ Passed Docstring coverage is 82.35% which is sufficient. The required threshold is 80.00%.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing touches
  • 📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

🤖 Fix all issues with AI agents
In `@AGENTS.md`:
- Around line 146-192: The UBS section is wrapped in a stray code fence (the
leading "````markdown" and trailing "````") causing the whole block to render as
code; remove those fence lines so the "## UBS Quick Reference for AI Agents"
header and its subsequent lists render as normal Markdown (locate the opening
"````markdown" before the header and the matching closing "````" after the
anti-patterns/example and delete both lines).
- Around line 140-144: The jq filter in the example uses the wrong field name
`.dep_type`; update the command `br show <epic-id> --json | jq '.dependents[] |
select(.dep_type == "parent-child")'` to use the actual JSON field
`dependency_type` (i.e., replace `.dep_type` with `.dependency_type`) so the
filter matches the br plugin output.

In `@CLAUDE.md`:
- Around line 138-144: Update the jq example in the Parent-Child Relationships
section to use the actual JSON field name: replace the selector that checks
`.dep_type` with `.dependency_type` so the command `br show <epic-id> --json |
jq '.dependents[] | select(.dependency_type == "parent-child")'` will work
against the real schema; ensure the text mentions `.dependency_type`
consistently where `.dep_type` appears.

In `@src/plugins/trackers/builtin/beads-rust/index.ts`:
- Around line 355-361: When parentId is provided, do not bypass filtering when
getChildIds returns an empty Set; instead always apply the child-id filter so an
empty set yields no tasks. Update the logic in getTasks (and the analogous block
in getNextTask) to replace the conditional that skips filtering on empty
childIds with unconditional filtering (i.e., set tasks to tasks.filter(t =>
childIds.has(t.id)) even when childIds.size === 0), ensuring unrelated tasks
cannot leak through.
- Around line 669-675: The code currently derives fullPath from external_ref
without preventing path traversal; update the logic around
externalRef/prdPath/fullPath to always resolve the PRD path against
this.workingDir (use path.resolve(this.workingDir, prdPath) even when prdPath
starts with '/') and then verify the resolved path is inside this.workingDir
(e.g., compare path.relative(this.workingDir, resolvedPath) and reject if it
begins with '..' or is absolute outside the dir); if the check fails return
null. Ensure you reference externalRef, prdPath, fullPath, this.workingDir and
resolve in the change so the code disallows absolute or ../ escapes.
🧹 Nitpick comments (2)
src/tui/output-parser.ts (2)

60-62: Consider case-insensitive comparison for consistency.

The Droid check uses includes('droid') which is case-insensitive due to toLowerCase(), but the OpenCode check uses strict equality. This could miss agent names like 'OpenCode' or 'OPENCODE'.

Suggested fix
 function isOpenCodeAgent(agentPlugin?: string): boolean {
-  return agentPlugin?.toLowerCase() === 'opencode';
+  return agentPlugin?.toLowerCase().includes('opencode') ?? false;
 }

86-104: Reuse the existing OpenCode parser function to avoid duplication.

The existing parseOpenCodeJsonlLine function in src/plugins/agents/opencode/outputParser.ts is significantly more robust. It handles ANSI escape sequence stripping and JSON extraction from noisy input, whereas the current implementation in this file does neither. Duplicating this logic risks divergent behaviour over time. Since the existing function is exported, import and reuse it instead.

AI Agent added 2 commits January 21, 2026 12:12
- Fix jq filter: .dep_type → .dependency_type in AGENTS.md and CLAUDE.md
- Remove stray markdown code fences around UBS section
- Fix parentId filtering to always apply even when childIds is empty
- Add path traversal protection for PRD paths in getPrdContext()
- Fix constants import in beads-bv (node:fs not node:fs/promises)
- Add README.md for beads-rust tracker plugin documenting:
  - Features and capabilities
  - Prerequisites and detection
  - Usage examples and configuration
  - PRD context injection
  - Differences from beads (Go version)
  - Troubleshooting guide

- Add ralph-tui-create-beads-rust skill for users with br CLI
  - Adapted from ralph-tui-create-beads for beads-rust commands
  - Uses br create/dep/sync instead of bd equivalents
  - Documents sync workflow for JSONL export
  - Includes command comparison table
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Fix all issues with AI agents
In `@src/plugins/trackers/builtin/beads-rust/README.md`:
- Around line 18-19: Update the placeholder GitHub links currently pointing to
"https://github.com/your-org/beads-rust" in
src/plugins/trackers/builtin/beads-rust/README.md (lines shown around the
beads-rust CLI and releases) to the canonical repository
"https://github.com/delightful-ai/beads-rs" and update the releases link to
"https://github.com/delightful-ai/beads-rs/releases"; also make the same
replacements in the other occurrences mentioned (around line 161 in this README
and in ./website/content/docs/plugins/trackers/beads-rust.mdx) so all references
to the old org/name are replaced with delightful-ai/beads-rs and
delightful-ai/beads-rs/releases.

- Remove --labels="ralph,..." from all beads tracker documentation
- Labels are now optional (empty array by default)
- Update website docs, plugin README, and skill files
- Fix CI test isolation: run beads-bv test separately due to ES module
  mock conflicts with other plugin tests
- Add beads-bv.lcov to Codecov upload list
- Update beads-rust GitHub links to canonical repo:
  https://github.com/Dicklesworthstone/beads_rust
@codecov
Copy link
Copy Markdown

codecov bot commented Jan 21, 2026

Codecov Report

❌ Patch coverage is 71.67785% with 211 lines in your changes missing coverage. Please review.
✅ Project coverage is 42.16%. Comparing base (2f8b65d) to head (57eb754).
⚠️ Report is 25 commits behind head on main.

Files with missing lines Patch % Lines
src/plugins/trackers/builtin/beads-rust/index.ts 70.79% 179 Missing ⚠️
src/tui/output-parser.ts 85.00% 15 Missing ⚠️
src/logs/progress.ts 43.47% 13 Missing ⚠️
src/plugins/trackers/builtin/beads-bv/index.ts 33.33% 4 Missing ⚠️
Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main     #179      +/-   ##
==========================================
+ Coverage   40.95%   42.16%   +1.21%     
==========================================
  Files          72       73       +1     
  Lines       19994    20731     +737     
==========================================
+ Hits         8188     8742     +554     
- Misses      11806    11989     +183     
Files with missing lines Coverage Δ
src/plugins/trackers/builtin/index.ts 94.44% <100.00%> (+0.69%) ⬆️
src/plugins/trackers/builtin/beads-bv/index.ts 12.76% <33.33%> (+4.54%) ⬆️
src/logs/progress.ts 53.30% <43.47%> (-1.29%) ⬇️
src/tui/output-parser.ts 94.32% <85.00%> (-3.06%) ⬇️
src/plugins/trackers/builtin/beads-rust/index.ts 70.79% <70.79%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Fix all issues with AI agents
In @.github/workflows/ci.yml:
- Around line 86-93: The current CI step uses the find ... -exec bun test {} \;
pattern which runs bun test per-file and repeatedly overwrites
coverage/lcov.info (see the find ... -exec bun test {} \; invocation and the cp
coverage/lcov.info coverage-parts/plugins.lcov step), losing earlier coverage;
change the command to batch tests into a single bun invocation (e.g. gather
matching paths and pass them all to bun test via xargs or a single bun test with
multiple file arguments) so coverage is produced once for all plugin tests
before copying coverage/lcov.info to coverage-parts/plugins.lcov; ensure the
adjusted pipeline preserves the existing tee logging and still allows the
beads-bv test to run separately.
🧹 Nitpick comments (2)
src/plugins/trackers/builtin/beads-rust/README.md (1)

157-161: Consider robustness of relative paths in Related links.

The relative paths (../../../README.md, ../../../../skills/...) work but are fragile if the directory structure changes.

This is minor since README files are typically read in context, but you could consider using absolute paths from the repository root in comments or linking to published documentation URLs instead.

website/content/docs/plugins/trackers/beads.mdx (1)

189-214: Consider clarifying label match semantics (any vs all).
A brief note on whether comma-separated labels are treated as OR or AND would remove ambiguity.

Add comprehensive tests for OpenCode JSONL parsing:
- text events display
- tool_use events with name/tool fields
- tool_result error handling (isError and is_error)
- successful tool_result hiding
- error events
- step_start/step_finish hiding
- parseAgentOutput integration tests

Improves output-parser.ts patch coverage from 80% to 95%.

Also fix CI plugin test coverage:
- Run beads-bv and beads-rust tests in isolation (both mock node:fs/promises)
- Batch remaining plugin tests in single bun invocation
- Add beads-rust.lcov to Codecov upload
@subsy subsy merged commit 5fb1ab5 into main Jan 21, 2026
9 checks passed
sakaman pushed a commit to sakaman/ralph-tui that referenced this pull request Feb 15, 2026
feat: beads-rust tracker plugin and improvements
@coderabbitai coderabbitai bot mentioned this pull request Mar 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant