* 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>
199 lines
5.1 KiB
Markdown
199 lines
5.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
go get github.com/steveyegge/beads@latest
|
|
```
|
|
|
|
## Basic Usage
|
|
|
|
```go
|
|
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
|
|
|
|
```bash
|
|
# 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 issue
|
|
- `CreateIssues(ctx, issues, actor)` - Batch create issues
|
|
- `GetIssue(ctx, id)` - Get issue by ID
|
|
- `UpdateIssue(ctx, id, updates, actor)` - Update issue fields
|
|
- `CloseIssue(ctx, id, reason, actor)` - Close an issue
|
|
- `SearchIssues(ctx, query, filter)` - Search with filters
|
|
|
|
### Dependencies
|
|
- `AddDependency(ctx, dep, actor)` - Add dependency between issues
|
|
- `RemoveDependency(ctx, issueID, dependsOnID, actor)` - Remove dependency
|
|
- `GetDependencies(ctx, issueID)` - Get what this issue depends on
|
|
- `GetDependents(ctx, issueID)` - Get what depends on this issue
|
|
- `GetDependencyTree(ctx, issueID, maxDepth, showAllPaths)` - Visualize tree
|
|
|
|
### Labels
|
|
- `AddLabel(ctx, issueID, label, actor)` - Add label to issue
|
|
- `RemoveLabel(ctx, issueID, label, actor)` - Remove label
|
|
- `GetLabels(ctx, issueID)` - Get all labels for an issue
|
|
- `GetIssuesByLabel(ctx, label)` - Find issues with label
|
|
|
|
### Ready Work & Blocking
|
|
- `GetReadyWork(ctx, filter)` - Find issues with no blockers
|
|
- `GetBlockedIssues(ctx)` - Find blocked issues with blocker info
|
|
- `GetEpicsEligibleForClosure(ctx)` - Find completable epics
|
|
|
|
### Comments & Events
|
|
- `AddIssueComment(ctx, issueID, author, text)` - Add comment
|
|
- `GetIssueComments(ctx, issueID)` - Get all comments
|
|
- `GetEvents(ctx, issueID, limit)` - Get audit trail
|
|
|
|
### Statistics
|
|
- `GetStatistics(ctx)` - Get aggregate metrics
|
|
|
|
## Types
|
|
|
|
All types are exported via the `beads` package:
|
|
|
|
```go
|
|
// 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:
|
|
|
|
```go
|
|
// 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
|
|
|
|
1. **Context** - Always pass `context.Context` for cancellation support
|
|
2. **Actor** - Provide meaningful actor strings for audit trail
|
|
3. **Error handling** - Check all errors; database operations can fail
|
|
4. **Close** - Always `defer store.Close()` after opening
|
|
5. **Transactions** - For complex multi-step operations, consider using the underlying database connection directly
|
|
|
|
## See Also
|
|
|
|
- [bd-example-extension-go](../bd-example-extension-go/README.md) - Working extension example
|
|
- [beads.go](../../beads.go) - Public API source
|
|
- [internal/storage/storage.go](../../internal/storage/storage.go) - Storage interface
|