* docs: fix broken xref to docs/EXTENDING.md in extension example The extension example README referenced docs/EXTENDING.md in three places, but that file was deliberately deleted in the SQLite -> Dolt migration (see CHANGELOG entry "Deleted deprecated docs - removed EXTENDING.md and MULTI_REPO_HYDRATION.md (SQLite-era, no longer applicable)"). Anyone following the example hits a broken link. Removed all three references. The example README is itself the canonical reference for the extension pattern, so no redirect target is needed. Note: other docs in the repo still reference the deleted EXTENDING.md (docs/ADVANCED.md, docs/CONFIG.md, examples/library-usage/README.md, website/docs/reference/advanced.md). Those are out of scope for this fix and should be addressed in follow-up issues. Tracking bead: mybd-q71 GH: #3683 PR: builds on follow-up audit from PR #3706 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: fix remaining broken xrefs to deleted EXTENDING.md across repo Round 1 (commitddeff314c) only fixed the extension example README because the original prompt scoped that PR narrowly. The bead (mybd-q71) acceptance is repo-wide ("no broken xrefs anywhere"), so this follow-up sweeps the rest in the same PR per the project's "one issue per PR" rule. Per-file treatment (EXTENDING.md was deleted in commit508387377before v1.0.0 was tagged, so even the v1.0.0 versioned snapshot has been broken since release): - docs/ADVANCED.md (3 refs): * Note in Extensible Database section: drop trailing "See EXTENDING.md for details" — the surrounding sentence about Dolt-era alternatives stands on its own. * Bold "See EXTENDING.md for complete documentation" line: redirect to the canonical working example (examples/bd-example-extension-go). * Next Steps bullet: same redirect. - docs/CONFIG.md (2 refs): * Namespace doc for compact_*: replace "(see EXTENDING.md)" with "(used by `bd admin compact`)" — the doc itself describes the keys, no external reference needed. * See Also bullet: replace with link to docs/ADVANCED.md (Extensible Database section). - examples/library-usage/README.md (1 ref): * See Also bullet: replace EXTENDING.md link with link to the sibling bd-example-extension-go example. - website/docs/reference/advanced.md (1 ref): * Custom Tables section: replace EXTENDING.md link with link to the bd-example-extension-go README on GitHub. - website/versioned_docs/version-1.0.0/reference/advanced.md (1 ref): * Same fix as the live docs. EXTENDING.md was deleted before v1.0.0 release (commit508387377is an ancestor of tag v1.0.0), so this versioned snapshot has been broken since cut and a fix here doesn't violate frozen-in-time correctness — the link was never valid in the v1.0.0 release. - website/static/llms-full.txt (1 ref, auto-generated artifact): * Updated to match the corrected source so the on-disk artifact isn't broken until next regeneration. - beads.go and internal/beads/beads.go (package doc comments): * Replaced "see docs/EXTENDING.md" / "see EXTENDING.md" with a pointer to examples/bd-example-extension-go. These were real broken pointers in published Go source comments. CHANGELOG.md historical entries left untouched (intentional history). cmd/bd/info.go:747 left untouched (it's a programmatic CHANGELOG entry rendered by `bd info`, equivalent to a CHANGELOG line). Verification: grep -rn 'EXTENDING\.md' --include='*.md' . returns only CHANGELOG.md hits. Tracking bead: mybd-q71 GH: #3683 PR: #3713 (round 2) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: CI Bot <ci@beads.test> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
5.1 KiB
5.1 KiB
Beads Library Usage Example
This example demonstrates using Beads as a Go library in external projects (like VC).
Why Use Beads as a Library?
Instead of spawning bd CLI processes:
- ✅ Direct API access - Call functions directly instead of parsing JSON output
- ✅ Type safety - Compile-time checking of types and interfaces
- ✅ Performance - No process spawn overhead
- ✅ Transactions - Access to database transactions for complex operations
- ✅ Shared database - Multiple components can use same database connection
- ✅ Error handling - Proper Go error types instead of parsing stderr
Installation
In your Go project:
go get github.com/steveyegge/beads@latest
Basic Usage
package main
import (
"context"
"log"
"github.com/steveyegge/beads"
)
func main() {
ctx := context.Background()
// Find and open database
dbPath := beads.FindDatabasePath()
store, err := beads.Open(ctx, dbPath)
if err != nil {
log.Fatal(err)
}
defer store.Close()
// Get ready work
ready, err := store.GetReadyWork(ctx, beads.WorkFilter{
Status: beads.StatusOpen,
Limit: 10,
})
if err != nil {
log.Fatal(err)
}
// Process ready issues...
}
Running This Example
# From this directory
cd examples/library-usage
# Make sure there's a Beads database
bd init --prefix demo
# Run the example
go run main.go
Available Operations
The beads.Storage interface provides:
Issues
CreateIssue(ctx, issue, actor)- Create a new issueCreateIssues(ctx, issues, actor)- Batch create issuesGetIssue(ctx, id)- Get issue by IDUpdateIssue(ctx, id, updates, actor)- Update issue fieldsCloseIssue(ctx, id, reason, actor)- Close an issueSearchIssues(ctx, query, filter)- Search with filters
Dependencies
AddDependency(ctx, dep, actor)- Add dependency between issuesRemoveDependency(ctx, issueID, dependsOnID, actor)- Remove dependencyGetDependencies(ctx, issueID)- Get what this issue depends onGetDependents(ctx, issueID)- Get what depends on this issueGetDependencyTree(ctx, issueID, maxDepth, showAllPaths)- Visualize tree
Labels
AddLabel(ctx, issueID, label, actor)- Add label to issueRemoveLabel(ctx, issueID, label, actor)- Remove labelGetLabels(ctx, issueID)- Get all labels for an issueGetIssuesByLabel(ctx, label)- Find issues with label
Ready Work & Blocking
GetReadyWork(ctx, filter)- Find issues with no blockersGetBlockedIssues(ctx)- Find blocked issues with blocker infoGetEpicsEligibleForClosure(ctx)- Find completable epics
Comments & Events
AddIssueComment(ctx, issueID, author, text)- Add commentGetIssueComments(ctx, issueID)- Get all commentsGetEvents(ctx, issueID, limit)- Get audit trail
Statistics
GetStatistics(ctx)- Get aggregate metrics
Types
All types are exported via the beads package:
// Core types
beads.Issue
beads.Status (Open, InProgress, Closed, Blocked)
beads.IssueType (Bug, Feature, Task, Epic, Chore)
beads.Priority (0-4)
// Relationships
beads.Dependency
beads.DependencyType (Blocks, Related, ParentChild, DiscoveredFrom)
// Metadata
beads.Label
beads.Comment
beads.Event
// Queries
beads.IssueFilter
beads.WorkFilter
beads.BlockedIssue
beads.EpicStatus
beads.Statistics
VC Integration Example
For VC (VibeCoder), the integration would look like:
// In VC's storage layer
type VCStorage struct {
beads beads.Storage
}
func NewVCStorage(ctx context.Context, dbPath string) (*VCStorage, error) {
store, err := beads.Open(ctx, dbPath)
if err != nil {
return nil, err
}
return &VCStorage{beads: store}, nil
}
// Claim ready work for executor
func (s *VCStorage) ClaimWork(ctx context.Context, executorID string) (*beads.Issue, error) {
ready, err := s.beads.GetReadyWork(ctx, beads.WorkFilter{
Status: beads.StatusOpen,
Limit: 1,
})
if err != nil {
return nil, err
}
if len(ready) == 0 {
return nil, nil // No work available
}
issue := ready[0]
// Claim it
updates := map[string]interface{}{
"status": beads.StatusInProgress,
"assignee": executorID,
}
if err := s.beads.UpdateIssue(ctx, issue.ID, updates, executorID); err != nil {
return nil, err
}
return issue, nil
}
Best Practices
- Context - Always pass
context.Contextfor cancellation support - Actor - Provide meaningful actor strings for audit trail
- Error handling - Check all errors; database operations can fail
- Close - Always
defer store.Close()after opening - Transactions - For complex multi-step operations, consider using the underlying database connection directly
See Also
- bd-example-extension-go - Working extension example
- beads.go - Public API source
- internal/storage/storage.go - Storage interface