Documentation
¶
Overview ¶
Package beads provides a minimal public API for extending bd with custom orchestration.
Most extensions should use direct SQL queries against bd's database. This package exports only the essential types and functions needed for Go-based extensions that want to use bd's storage layer programmatically.
For detailed guidance on extending bd, see EXTENDING.md.
Index ¶
- Constants
- Variables
- func ComputeRepoID() (string, error)
- func FindBeadsDir() string
- func FindDatabasePath() string
- func FindJSONLPath(dbPath string) string
- func FollowRedirect(beadsDir string) string
- func GetCloneID() (string, error)
- type BlockedIssue
- type Comment
- type DatabaseInfo
- type Dependency
- type DependencyType
- type EpicStatus
- type Event
- type EventType
- type Issue
- type IssueFilter
- type IssueType
- type Label
- type RedirectInfo
- type SortPolicy
- type Statistics
- type Status
- type Storage
- type Transaction
- type TreeNode
- type WorkFilter
Constants ¶
const ( StatusOpen = types.StatusOpen StatusInProgress = types.StatusInProgress StatusBlocked = types.StatusBlocked StatusDeferred = types.StatusDeferred StatusClosed = types.StatusClosed )
Status constants
const ( TypeBug = types.TypeBug TypeFeature = types.TypeFeature TypeTask = types.TypeTask TypeEpic = types.TypeEpic TypeChore = types.TypeChore TypeMolecule = types.TypeMolecule )
IssueType constants
const ( DepBlocks = types.DepBlocks DepRelated = types.DepRelated DepParentChild = types.DepParentChild DepDiscoveredFrom = types.DepDiscoveredFrom DepConditionalBlocks = types.DepConditionalBlocks // B runs only if A fails )
DependencyType constants
const ( SortPolicyHybrid = types.SortPolicyHybrid SortPolicyPriority = types.SortPolicyPriority SortPolicyOldest = types.SortPolicyOldest )
SortPolicy constants
const ( EventCreated = types.EventCreated EventUpdated = types.EventUpdated EventStatusChanged = types.EventStatusChanged EventCommented = types.EventCommented EventClosed = types.EventClosed EventReopened = types.EventReopened EventDependencyAdded = types.EventDependencyAdded EventDependencyRemoved = types.EventDependencyRemoved EventLabelAdded = types.EventLabelAdded EventLabelRemoved = types.EventLabelRemoved EventCompacted = types.EventCompacted )
EventType constants
const CanonicalDatabaseName = "beads.db"
CanonicalDatabaseName is the required database filename for all beads repositories
const RedirectFileName = "redirect"
RedirectFileName is the name of the file that redirects to another .beads directory
Variables ¶
var LegacyDatabaseNames = []string{"bd.db", "issues.db", "bugs.db"}
LegacyDatabaseNames are old names that should be migrated
Functions ¶
func ComputeRepoID ¶
ComputeRepoID generates a unique identifier for this git repository
func FindBeadsDir ¶
func FindBeadsDir() string
FindBeadsDir finds the .beads/ directory in the current directory tree Returns empty string if not found. Supports both database and JSONL-only mode. Stops at the git repository root to avoid finding unrelated directories. Validates that the directory contains actual project files. Redirect files are supported: if a .beads/redirect file exists, its contents are used as the actual .beads directory path. For worktrees, prioritizes local .beads if present, otherwise uses main repo.
func FindDatabasePath ¶
func FindDatabasePath() string
FindDatabasePath discovers the bd database path using bd's standard search order:
- $BEADS_DIR environment variable (points to .beads directory)
- $BEADS_DB environment variable (points directly to database file, deprecated)
- .beads/*.db in current directory or ancestors
Redirect files are supported: if a .beads/redirect file exists, its contents are used as the actual .beads directory path.
Returns empty string if no database is found.
func FindJSONLPath ¶
FindJSONLPath returns the expected JSONL file path for the given database path. It searches for existing *.jsonl files in the database directory and returns the first one found, preferring issues.jsonl over beads.jsonl.
This function does not create directories or files - it only discovers paths. Use this when you need to know where bd stores its JSONL export.
func FollowRedirect ¶
FollowRedirect checks if a .beads directory contains a redirect file and follows it. If a redirect file exists, it returns the target .beads directory path. If no redirect exists or there's an error, it returns the original path unchanged.
The redirect file should contain a single path (relative or absolute) to the target .beads directory. Relative paths are resolved from the parent directory of the original .beads directory (i.e., the project root).
Redirect chains are not followed - only one level of redirection is supported. This prevents infinite loops and keeps the behavior predictable.
func GetCloneID ¶
GetCloneID generates a unique ID for this specific clone (not shared with other clones)
Types ¶
type BlockedIssue ¶
type BlockedIssue = types.BlockedIssue
BlockedIssue represents an issue with blocking dependencies.
type DatabaseInfo ¶
type DatabaseInfo struct {
Path string // Full path to the .db file
BeadsDir string // Parent .beads directory
IssueCount int // Number of issues (-1 if unknown)
}
DatabaseInfo contains information about a discovered beads database
func FindAllDatabases ¶
func FindAllDatabases() []DatabaseInfo
FindAllDatabases scans the directory hierarchy for the closest .beads directory. Returns a slice with at most one DatabaseInfo - the closest database to CWD. Stops searching upward as soon as a .beads directory is found, because in multi-workspace setups, nested .beads directories are intentional and separate - parent directories are out of scope. Redirect files are supported: if a .beads/redirect file exists, its contents are used as the actual .beads directory path.
type Dependency ¶
type Dependency = types.Dependency
Dependency represents a relationship between issues.
type DependencyType ¶
type DependencyType = types.DependencyType
DependencyType represents the type of dependency (blocks, related, parent-child, discovered-from).
type EpicStatus ¶
type EpicStatus = types.EpicStatus
EpicStatus represents the status of an epic issue.
type IssueFilter ¶
type IssueFilter = types.IssueFilter
IssueFilter represents filtering criteria for issue queries.
type RedirectInfo ¶
type RedirectInfo struct {
// IsRedirected is true if the local .beads has a redirect file
IsRedirected bool
// LocalDir is the local .beads directory (the one with the redirect file)
LocalDir string
// TargetDir is the actual .beads directory being used (after following redirect)
TargetDir string
}
RedirectInfo contains information about a beads directory redirect.
func GetRedirectInfo ¶
func GetRedirectInfo() RedirectInfo
GetRedirectInfo checks if the current beads directory is redirected. It searches for the local .beads/ directory and checks if it contains a redirect file. Returns RedirectInfo with IsRedirected=true if a redirect is active.
type SortPolicy ¶
type SortPolicy = types.SortPolicy
SortPolicy determines how ready work is ordered.
type Transaction ¶
type Transaction = storage.Transaction
Transaction provides atomic multi-operation support within a database transaction. Use Storage.RunInTransaction() to obtain a Transaction instance.
type WorkFilter ¶
type WorkFilter = types.WorkFilter
WorkFilter represents filtering criteria for work queries.
Source Files