* security: pin build toolchain to go1.26.7 go1.26.5 carries 8 stdlib advisories, 7 of them reachable from the shipped bd binary. Verified with govulncheck in call-graph mode against ./cmd/bd, toolchain pinned so the analysis cannot drift: GO-2026-6218 net/url quadratic resolvePath GO-2026-6091 html/template JS-regexp context tracking GO-2026-6090 crypto/tls post-handshake message flood GO-2026-6089 net/http ReadHeaderTimeout on the h2c check GO-2026-6088 encoding/xml recursion depth GO-2026-5972 encoding/asn1 recursion depth GO-2026-5026 net/http vendored x/net/idna punycode GO-2026-5942 net dnsmessage SVCB/HTTPS RR (linked, uncalled) `bd serve` is a real HTTP server and bd makes TLS client connections, so these are live paths rather than dead weight: httpapi.Serve reaches four of them directly. go1.26.6 fixes all eight; 1.26.7 adds one more net/http fix. After the bump the same scan reports zero. The `go` directive stays at 1.26.5 so importers of the module keep their current floor; `toolchain` is what we actually build with. release.yml builds the shipped binaries with a bare `go build` under the default GOTOOLCHAIN=auto, which honors the toolchain line. The Makefile needed the second half of this. It pinned GOTOOLCHAIN from the `go` directive, which is the importer floor, not the build version - left alone it would have held every make target (the test suite, the npm and MCP package gates, local `make build`) at 1.26.5 while the release binaries moved to 1.26.7, which is both a silent downgrade and a split between what CI tests and what we ship. It now reads `toolchain` first and falls back to `go` when there is no toolchain directive, preserving the original reason for pinning: one exact version so the compile tools and coverage instrumentation cannot disagree. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * security: bump x/crypto, x/mod, klauspost/compress, moby/go-archive Four advisories, none reachable from the shipped bd binary; these are hygiene bumps that also clear the Dependabot board. golang.org/x/crypto v0.54.0 -> v0.55.0 GO-2026-6303 golang.org/x/mod v0.37.0 -> v0.40.0 GO-2026-6179/6180 github.com/klauspost/compress v1.18.5 -> v1.18.7 GO-2026-5841 github.com/moby/go-archive v0.2.0 -> v0.3.3 CVE-2026-17106 (#140) Reachability, from `go list -deps ./cmd/bd` plus govulncheck call-graph mode: x/crypto/ssh proper enters only through testcontainers (test-only); the compress advisory is in the s2 codec, which is not linked into bd at all (bd links zstd/gzip/flate/huff0 via dolt); the x/mod sumdb/tlog code is required but never called; go-archive is testcontainers-only and absent from the binary's package graph entirely. go-archive goes to v0.3.3, not the advisory's minimum v0.3.0: v0.3.0's hardened extraction rejected absolute symlinks and hardlinks and broke device nodes and implied directories, all fixed across v0.3.1-v0.3.3. MVS carries x/net, x/text, x/tools and x/telemetry along. No replace directives, and the dolt pin is untouched - dolt requires older versions of all three x/ modules, so beads' go.mod already wins the version selection. The examples/ modules reach the parent through a `replace` directive, so their recorded graph goes stale on any root go.mod change and both failed scripts/build-examples.sh with the documented "updates to go.mod needed". Re-tidied here rather than left for the advisory job to warn about; the diff is purely the mirror of the bumps above. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * security: bump oapi-codegen to v2.7.1 and kin-openapi to v0.144.0 Clears the board's one critical (#133, GHSA-r277-6w6q-xmqw, CVSS 9.1) plus #142, #141, #134 and the low #132. All five are codegen-tool-only: kin-openapi reaches the module graph solely through the go.mod `tool` directive for oapi-codegen, no beads source file imports kin-openapi, oapi-codegen or openapi3filter, and `go list -deps ./cmd/bd` contains none of them. The critical is a fail-open bug in openapi3filter's ValidationHandler.Load(), middleware this repo never runs - request validation in internal/httpapi is hand-rolled. Dependabot scopes the alert "runtime" because it cannot model Go tool-directive semantics. Both must move together: oapi-codegen v2.6.0 does not compile against kin-openapi v0.144.0 (pkg/codegen/schema.go:909, openapi3.MappingRef vs string). v2.7.1 is the minimum-fix pair, chosen over the latest 2.8.0/0.149.0 to keep codegen churn off a release branch. The `make api-gen` regen diff is two lines of real change: the generated BearerTokenScopes constant picks up a generated named context-key type instead of being an untyped string. The identifier has no references outside types.gen.go. `make api-check` is green - regeneration is idempotent, pinning.go's compile-time welds hold, and TestWireTagBijection passes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * security: refresh beads-mcp uv.lock (clears all 19 pip alerts) `uv lock --upgrade` with fastmcp still pinned ==3.4.5. Every one of the 19 Dependabot alerts on integrations/beads-mcp/uv.lock is a fastmcp transitive, and each lands at or above its first-patched version: mcp 1.25.0 -> 1.29.1 #129 #128 #127 (high) cryptography 48.0.0 -> 50.0.1 #137 #138 #82 #139 pyjwt 2.12.1 -> 2.13.0 #79 #136 #81 #78 #135 joserfc 1.6.5 -> 1.7.4 #113 #109 python-multipart 0.0.27 -> 0.0.32 #88 #87 #86 #85 idna 3.11 -> 3.19 #68 Real exposure was already low: beads-mcp runs stdio transport only (server.py's mcp.run_async(transport="stdio")), so the three high mcp-SDK alerts - WebSocket Host/Origin validation, HTTP session principal handling, task-handler cross-access - are all HTTP/WS-transport bugs this server never reaches, and the auth libraries ride along with fastmcp's extras rather than being used by beads-mcp's own code. The lock governs dev and CI installs; PyPI users resolve fresh and already get patched versions. mcp 1.25 -> 1.29 is the only behaviorally interesting jump. The full package gate is green: uv sync --locked, ruff, mypy, 228 passed / 5 skipped, uv build. The resolved lock is byte-identical under uv 0.9.5 and CI's uv 0.11.16. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * chore(nix): update vendorHash for go.sum changes The go.mod/go.sum bumps in this branch invalidate the proxyVendor fixed-output hash in default.nix, which fails the nix-build gate. The workflow that repairs this automatically only fires for dependabot PRs targeting main, so it does not cover this branch. Recomputed with scripts/update-nix-vendorhash.sh's flow and verified: `nix build .#default` completes green, which also confirms the new `toolchain go1.26.7` directive is compatible with default.nix's GOTOOLCHAIN = "local". Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.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...
}
Filtering ready work by status
WorkFilter offers two status fields:
Statusfilters to exactly one status.Statusesfilters to any of the given statuses (OR semantics) in a single query, so multi-status callers avoid oneGetReadyWorkround trip per status. Custom statuses participate like built-ins.
Status takes precedence: when it is set, Statuses is ignored. When both
are empty, the default of ('open', 'in_progress') applies.
// One query for open OR blocked ready work
ready, err := store.GetReadyWork(ctx, beads.WorkFilter{
Statuses: []beads.Status{beads.StatusOpen, beads.StatusBlocked},
Limit: 10,
})
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