* /{engdocs,examples,go.mod}: bump go version
* deps: bump golang.org/x/text to v0.39.0 (GO-2026-5970)
govulncheck against today's vuln DB flags GO-2026-5970 (infinite loop on
invalid input in x/text, reachable via internal/routing), published after
this PR's original clean scan. Bump x/text to the fixed v0.39.0 (with its
MVS sibling x/* minimums) and re-tidy examples/library-usage, which
builds against the parent via a replace directive and would otherwise
fail with missing go.sum entries.
examples/bd-example-extension-go is left untouched: it already fails
'go build' (needs go mod tidy) at the PR's base state, so its tidy is
pre-existing follow-up work, not fallout from this bump.
Verified: CGO_ENABLED=0 go build -tags gms_pure_go ./cmd/bd; both
example modules build; go test ./internal/routing; govulncheck now
reports 0 affecting vulnerabilities.
Agent-Signature: claude-fable-5-high on behalf of maphew
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
|
||
|---|---|---|
| .. | ||
| go.mod | ||
| go.sum | ||
| main.go | ||
| main_test.go | ||
| README.md | ||
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 the workspace and open its configured Dolt implementation
beadsDir := beads.FindBeadsDir()
store, err := beads.OpenBestAvailable(ctx, beadsDir)
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 fieldsUpdateIssueChecked(ctx, id, updates, actor, opts)- Update with an optional optimistic-concurrency (CAS) precondition (opts.ExpectedVersion); see Concurrency belowCloseIssue(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
Concurrency & Metadata
UpdateIssueChecked(ctx, id, updates, actor, opts)- LikeUpdateIssue, but whenopts.ExpectedVersionis set the update proceeds only if the issue's currentRowVersionstill matches, else it refuses withbeads.ErrVersionMismatch. The version read and the write share one transaction (a true compare-and-swap).RowVersionis surfaced read-only onIssuereads.MergeMetadata(ctx, issueID, key, value, actor)- Atomically merge a single key into an issue's metadata JSON. Two concurrent merges of different keys both survive rather than clobbering each other.
Implementer note (interface change):
UpdateIssueCheckedandMergeMetadataare now required methods on thebeads.Storageinterface. Code that only consumesbeads.Storageneeds no change, but any external type that implementsbeads.Storage(a custom store, mock, or proxy) must add these two methods to compile. If you only need the base behavior,UpdateIssueCheckedwith a nilopts.ExpectedVersionis identical toUpdateIssue, andMergeMetadatacan be layered over a read-modify-write of the issue's metadata.
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, beadsDir string) (*VCStorage, error) {
store, err := beads.OpenBestAvailable(ctx, beadsDir)
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 - Legacy SQLite extension example
- beads.go - Public API source
- internal/storage/storage.go - Storage interface