beads/examples/library-usage/README.md
matt wilkie 57a4cab9f0
docs: fix broken xref to docs/EXTENDING.md in extension example (#3713)
* 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 (commit ddeff314c) 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 commit 508387377
before 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 (commit 508387377 is 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>
2026-05-05 13:18:43 -07:00

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