johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: doctor deletions check and onboard docs improvements

Browse Source 
- Fix doctor to treat empty deletions.jsonl as valid (0 entries OK status)
- Fix HydrateDeletionsManifest to create empty file when no deletions found
- Add --parent flag documentation to onboard command
- Add CLI --help tip throughout onboard documentation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-11-27 13:23:14 -08:00
parent bba6dd1d70
commit 3f609267d4
4 changed files with 32 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.beads/issues.jsonl
View File

@@ -17,6 +17,7 @@
{"id":"bd-8an","title":"bd import auto-detects wrong prefix from directory name instead of issue IDs","description":"When importing issues.jsonl into a fresh database, 'bd import' prints:\n\n ✓ Initialized database with prefix 'beads' (detected from issues)\n\nBut the issues all have prefix 'bd-' (e.g., bd-03r). It appears to be detecting the prefix from the directory name (.beads/) rather than from the actual issue IDs in the JSONL.\n\nThis causes import to fail with:\n validate ID prefix for bd-03r: issue ID 'bd-03r' does not match configured prefix 'beads'\n\nWorkaround: Run 'bd config set issue_prefix bd' before import, or use 'bd init --prefix bd'.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-26T22:28:01.582564-08:00","updated_at":"2025-11-26T22:28:01.582564-08:00"}
{"id":"bd-9e23","title":"Optimize Memory backend GetIssueByExternalRef with index","description":"Currently GetIssueByExternalRef in Memory storage uses O(n) linear search through all issues.\n\nCurrent code (memory.go:282-308):\nfor _, issue := range m.issues {\n if issue.ExternalRef != nil \u0026\u0026 *issue.ExternalRef == externalRef {\n return \u0026issueCopy, nil\n }\n}\n\nProposed optimization:\n- Add externalRefToID map[string]string to MemoryStorage\n- Maintain it in CreateIssue, UpdateIssue, DeleteIssue\n- Achieve O(1) lookup like SQLite's index\n\nImpact: Low (--no-db mode typically has smaller datasets)\nRelated: bd-1022","status":"closed","priority":4,"issue_type":"chore","created_at":"2025-11-02T15:32:30.242357-08:00","updated_at":"2025-11-26T11:14:49.172418-08:00","closed_at":"2025-11-26T11:14:49.172418-08:00"}
{"id":"bd-9li4","title":"Create Docker image for Agent Mail","description":"Containerize Agent Mail server for easy deployment.\n\nAcceptance Criteria:\n- Dockerfile with Python 3.14\n- Health check endpoint\n- Volume mount for storage\n- Environment variable configuration\n- Multi-arch builds (amd64, arm64)\n\nFile: deployment/agent-mail/Dockerfile","status":"closed","priority":3,"issue_type":"task","created_at":"2025-11-07T22:43:43.231964-08:00","updated_at":"2025-11-25T17:47:30.777486-08:00","closed_at":"2025-11-25T17:47:30.777486-08:00"}
{"id":"bd-azh","title":"Fix bd doctor --fix recursive message for deletions manifest","description":"When running bd doctor --fix, if the deletions manifest check fails but there are no deleted issues in git history, the fix succeeds but doesn't create the file. The check then runs again and tells user to run bd doctor --fix - the same command they just ran.\n\nFix: Create empty deletions.jsonl when hydration finds no deletions, and recognize empty file as valid in the check.\n\nFixes: https://github.com/steveyegge/beads/issues/403","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-27T12:41:09.426143-08:00","updated_at":"2025-11-27T12:41:23.521981-08:00","closed_at":"2025-11-27T12:41:23.521981-08:00"}
{"id":"bd-b8h","title":"Refactor check-health DB access to avoid repeated path resolution","description":"The runCheckHealth lightweight checks (hintsDisabled, checkVersionMismatch, checkSyncBranchQuick) each have duplicated database path resolution logic. Extract a helper function to DRY this up.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-25T19:27:35.075929-08:00","updated_at":"2025-11-25T19:50:21.272961-08:00","closed_at":"2025-11-25T19:50:21.272961-08:00"}
{"id":"bd-bgs","title":"Git history fallback doesn't escape regex special chars in IDs","description":"## Problem\n\nIn `batchCheckGitHistory`, IDs are directly interpolated into a regex pattern:\n\n```go\npatterns = append(patterns, fmt.Sprintf(\\`\"id\":\"%s\"\\`, id))\nsearchPattern := strings.Join(patterns, \"|\")\ncmd := exec.Command(\"git\", \"log\", \"--all\", \"-G\", searchPattern, ...)\n```\n\nIf an ID contains regex special characters (e.g., `bd-foo.bar` or `bd-test+1`), the pattern will be malformed or match unintended strings.\n\n## Location\n`internal/importer/importer.go:923-926`\n\n## Impact\n- False positives: IDs with `.` could match any character\n- Regex errors: IDs with `[` or `(` could cause git to fail\n- Security: potential for regex injection (low risk since IDs are validated)\n\n## Fix\nEscape regex special characters:\n\n```go\nimport \"regexp\"\n\nescapedID := regexp.QuoteMeta(id)\npatterns = append(patterns, fmt.Sprintf(\\`\"id\":\"%s\"\\`, escapedID))\n```","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-25T12:50:30.132232-08:00","updated_at":"2025-11-25T15:04:06.217695-08:00","closed_at":"2025-11-25T15:04:06.217695-08:00"}
{"id":"bd-bhd","title":"Git history fallback assumes .beads is direct child of repo root","description":"## Problem\n\n`checkGitHistoryForDeletions` assumes the repo structure:\n\n```go\nrepoRoot := filepath.Dir(beadsDir) // Assumes .beads is in repo root\njsonlPath := filepath.Join(\".beads\", \"beads.jsonl\")\n```\n\nBut `.beads` could be in a subdirectory (monorepo, nested project), and the actual JSONL filename could be different (configured via `metadata.json`).\n\n## Location\n`internal/importer/importer.go:865-869`\n\n## Impact\n- Git search will fail silently for repos with non-standard structure\n- Monorepo users won't get deletion propagation\n\n## Fix\n1. Use `git rev-parse --show-toplevel` to find actual repo root\n2. Compute relative path from repo root to JSONL\n3. Or use `git -C \u003cdir\u003e` to run from beadsDir directly","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-25T12:51:03.46856-08:00","updated_at":"2025-11-25T15:05:40.754716-08:00","closed_at":"2025-11-25T15:05:40.754716-08:00"}
@@ -58,3 +59,4 @@
{"id":"bd-ye0d","title":"troubleshoot GH#278 daemon exits every few secs","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-13T06:27:23.39509215-07:00","updated_at":"2025-11-25T17:48:43.62418-08:00","closed_at":"2025-11-25T17:48:43.62418-08:00"}
{"id":"bd-zai","title":"bd init resets metadata.json jsonl_export to beads.jsonl, ignoring existing issues.jsonl","description":"When running 'bd init --prefix bd' in a repo that already has .beads/issues.jsonl, the init command overwrites metadata.json and sets jsonl_export back to 'beads.jsonl' instead of detecting and respecting the existing issues.jsonl file.\n\nSteps to reproduce:\n1. Have a repo with .beads/issues.jsonl (canonical) and metadata.json pointing to issues.jsonl\n2. Delete beads.db and run 'bd init --prefix bd'\n3. Check metadata.json - it now says jsonl_export: beads.jsonl\n\nExpected: Init should detect existing issues.jsonl and use it.\n\nWorkaround: Manually edit metadata.json after init.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-26T22:27:41.653287-08:00","updated_at":"2025-11-26T22:27:41.653287-08:00"}
{"id":"bd-zj8e","title":"Performance Testing Documentation","description":"Create docs/performance-testing.md documenting the performance testing framework.\n\nSections:\n1. Overview - What the framework does, goals\n2. Running Benchmarks\n - make bench command\n - Running specific benchmarks\n - Interpreting output (ns/op, allocs/op)\n3. Profiling and Analysis\n - Viewing CPU profiles with pprof\n - Reading flamegraphs\n - Memory profiling\n - Finding hotspots\n4. User Diagnostics\n - bd doctor --perf usage\n - Sharing profiles with bug reports\n - Understanding the report output\n5. Comparing Performance\n - Using benchstat for before/after comparisons\n - Detecting regressions\n6. Tips for Optimization\n - Common patterns\n - When to profile vs benchmark\n\nStyle:\n- Concise, practical examples\n- Screenshots/examples of pprof output\n- Clear command-line examples\n- Focus on workflow, not theory","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-13T22:23:38.99897-08:00","updated_at":"2025-11-13T22:23:38.99897-08:00"}
{"id":"bd-zsz","title":"Add --parent flag to bd onboard output","description":"bd onboard didn't document --parent flag for epic subtasks, causing AI agents to guess wrong syntax. Added --parent example and CLI help section pointing to bd \u003ccmd\u003e --help.\n\nFixes: https://github.com/steveyegge/beads/issues/402","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-27T13:01:51.366625-08:00","updated_at":"2025-11-27T13:02:02.018003-08:00","closed_at":"2025-11-27T13:02:02.018003-08:00"}

13
cmd/bd/doctor.go
View File

@@ -2078,10 +2078,17 @@ func checkDeletionsManifest(path string) doctorCheck {
deletionsPath := filepath.Join(beadsDir, "deletions.jsonl")
// Check if deletions.jsonl exists and has content
// Check if deletions.jsonl exists
info, err := os.Stat(deletionsPath)
if err == nil && info.Size() > 0 {
// Count entries
if err == nil {
// File exists - count entries (empty file is valid, means no deletions)
if info.Size() == 0 {
return doctorCheck{
Name: "Deletions Manifest",
Status: statusOK,
Message: "Present (0 entries)",
}
}
file, err := os.Open(deletionsPath) // #nosec G304 - controlled path
if err == nil {
defer file.Close()

7
cmd/bd/doctor/fix/deletions.go
View File

@@ -67,7 +67,12 @@ func HydrateDeletionsManifest(path string) error {
}
if len(deletedIDs) == 0 {
fmt.Println(" No new deleted issues found in git history")
// Create empty deletions manifest to signal hydration is complete
// This prevents the check from re-warning after --fix runs
if err := deletions.WriteDeletions(deletionsPath, nil); err != nil {
return fmt.Errorf("failed to create empty deletions manifest: %w", err)
}
fmt.Println(" No deleted issues found in git history (created empty manifest)")
return nil
}

14
cmd/bd/onboard.go
View File

@@ -63,6 +63,7 @@ bd stale --days 30 --json # Forgotten issues
# Create and manage
bd create "Title" -t bug|feature|task -p 0-4 --json
bd create "Subtask" --parent <epic-id> --json # Hierarchical subtask
bd update <id> --status in_progress --json
bd close <id> --reason "Done" --json
@@ -128,12 +129,18 @@ Use the beads MCP server for native function calls instead of shell commands:
- **README.md** - User-facing documentation
- **docs/CLI_REFERENCE.md** - Complete command reference
## CLI Help
Run ` + "`bd <command> --help`" + ` to see all available flags for any command.
For example: ` + "`bd create --help`" + ` shows ` + "`--parent`" + `, ` + "`--deps`" + `, ` + "`--assignee`" + `, etc.
## Important Rules
- ✅ Use bd for ALL task tracking
- ✅ Always use ` + "`--json`" + ` flag for programmatic use
- ✅ Run ` + "`bd sync`" + ` at end of sessions
- ✅ Test with ` + "`BEADS_DB=/tmp/test.db`" + `
- ✅ Run ` + "`bd <cmd> --help`" + ` to discover available flags
- ❌ Do NOT create markdown TODO lists
- ❌ Do NOT create test issues in production DB
- ❌ Do NOT commit ` + "`.beads/beads.db`" + ` (JSONL only)
@@ -164,6 +171,7 @@ bd ready --json
` + "```bash" + `
bd create "Issue title" -t bug|feature|task -p 0-4 --json
bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
bd create "Subtask" --parent <epic-id> --json # Hierarchical subtask (gets ID like epic-id.1)
` + "```" + `
**Claim and update:**
@@ -263,6 +271,11 @@ history/
- ✅ Preserves planning history for archeological research
- ✅ Reduces noise when browsing the project
### CLI Help
Run ` + "`bd <command> --help`" + ` to see all available flags for any command.
For example: ` + "`bd create --help`" + ` shows ` + "`--parent`" + `, ` + "`--deps`" + `, ` + "`--assignee`" + `, etc.
### Important Rules
- ✅ Use bd for ALL task tracking
@@ -270,6 +283,7 @@ history/
- ✅ Link discovered work with ` + "`discovered-from`" + ` dependencies
- ✅ Check ` + "`bd ready`" + ` before asking "what should I work on?"
- ✅ Store AI planning docs in ` + "`history/`" + ` directory
- ✅ Run ` + "`bd <cmd> --help`" + ` to discover available flags
- ❌ Do NOT create markdown TODO lists
- ❌ Do NOT use external issue trackers
- ❌ Do NOT duplicate tracking systems