* 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>
174 lines
6.1 KiB
Go
174 lines
6.1 KiB
Go
// 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 a working extension example, see examples/bd-example-extension-go.
|
|
package beads
|
|
|
|
import (
|
|
"context"
|
|
|
|
"github.com/steveyegge/beads/internal/beads"
|
|
"github.com/steveyegge/beads/internal/storage"
|
|
"github.com/steveyegge/beads/internal/storage/dolt"
|
|
"github.com/steveyegge/beads/internal/types"
|
|
)
|
|
|
|
// Storage is the interface for beads storage operations
|
|
type Storage = beads.Storage
|
|
|
|
// Transaction provides atomic multi-operation support within a database transaction.
|
|
// Use Storage.RunInTransaction() to obtain a Transaction instance.
|
|
type Transaction = beads.Transaction
|
|
|
|
// RemoteStore provides dolt remote management and replication operations.
|
|
// Use type assertion on a Storage value to access these methods:
|
|
//
|
|
// if rs, ok := store.(beads.RemoteStore); ok {
|
|
// rs.Push(ctx)
|
|
// }
|
|
type RemoteStore = storage.RemoteStore
|
|
|
|
// SyncStore provides high-level sync operations with peers.
|
|
type SyncStore = storage.SyncStore
|
|
|
|
// VersionControlReader provides read-only version control operations.
|
|
// Write operations (Branch, Checkout, Merge, DeleteBranch) are not yet
|
|
// part of the public API. If you need them, please open an issue.
|
|
type VersionControlReader interface {
|
|
CurrentBranch(ctx context.Context) (string, error)
|
|
ListBranches(ctx context.Context) ([]string, error)
|
|
CommitExists(ctx context.Context, commitHash string) (bool, error)
|
|
GetCurrentCommit(ctx context.Context) (string, error)
|
|
Status(ctx context.Context) (*VCStatus, error)
|
|
Log(ctx context.Context, limit int) ([]CommitInfo, error)
|
|
}
|
|
|
|
// Replication and version control types from internal/storage
|
|
type (
|
|
RemoteInfo = storage.RemoteInfo
|
|
SyncResult = storage.SyncResult
|
|
SyncStatus = storage.SyncStatus
|
|
Conflict = storage.Conflict
|
|
CommitInfo = storage.CommitInfo
|
|
VCStatus = storage.Status
|
|
StatusEntry = storage.StatusEntry
|
|
)
|
|
|
|
// Open opens a Dolt-backed beads database at the given path.
|
|
// This always opens in embedded mode. Use OpenFromConfig to respect
|
|
// server mode settings from metadata.json.
|
|
func Open(ctx context.Context, dbPath string) (Storage, error) {
|
|
return dolt.New(ctx, &dolt.Config{Path: dbPath, CreateIfMissing: true})
|
|
}
|
|
|
|
// OpenFromConfig opens a beads database using configuration from metadata.json.
|
|
// Unlike Open, this respects Dolt server mode settings and database name
|
|
// configuration, connecting to the Dolt SQL server when dolt_mode is "server".
|
|
// beadsDir is the path to the .beads directory.
|
|
func OpenFromConfig(ctx context.Context, beadsDir string) (Storage, error) {
|
|
return dolt.NewFromConfigWithOptions(ctx, beadsDir, &dolt.Config{CreateIfMissing: true})
|
|
}
|
|
|
|
// FindDatabasePath finds the beads database in the current directory tree
|
|
func FindDatabasePath() string {
|
|
return beads.FindDatabasePath()
|
|
}
|
|
|
|
// FindBeadsDir finds the .beads/ directory in the current directory tree.
|
|
// Returns empty string if not found.
|
|
func FindBeadsDir() string {
|
|
return beads.FindBeadsDir()
|
|
}
|
|
|
|
// DatabaseInfo contains information about a beads database
|
|
type DatabaseInfo = beads.DatabaseInfo
|
|
|
|
// FindAllDatabases finds all beads databases in the system
|
|
func FindAllDatabases() []DatabaseInfo {
|
|
return beads.FindAllDatabases()
|
|
}
|
|
|
|
// RedirectInfo contains information about a beads directory redirect
|
|
type RedirectInfo = beads.RedirectInfo
|
|
|
|
// GetRedirectInfo checks if the current beads directory is redirected.
|
|
// Returns RedirectInfo with IsRedirected=true if a redirect is active.
|
|
func GetRedirectInfo() RedirectInfo {
|
|
return beads.GetRedirectInfo()
|
|
}
|
|
|
|
// Core types from internal/types
|
|
type (
|
|
Issue = types.Issue
|
|
Status = types.Status
|
|
IssueType = types.IssueType
|
|
Dependency = types.Dependency
|
|
DependencyType = types.DependencyType
|
|
Label = types.Label
|
|
Comment = types.Comment
|
|
Event = types.Event
|
|
EventType = types.EventType
|
|
BlockedIssue = types.BlockedIssue
|
|
TreeNode = types.TreeNode
|
|
IssueFilter = types.IssueFilter
|
|
WorkFilter = types.WorkFilter
|
|
StaleFilter = types.StaleFilter
|
|
DependencyCounts = types.DependencyCounts
|
|
IssueWithCounts = types.IssueWithCounts
|
|
IssueWithDependencyMetadata = types.IssueWithDependencyMetadata
|
|
SortPolicy = types.SortPolicy
|
|
EpicStatus = types.EpicStatus
|
|
WispFilter = types.WispFilter
|
|
)
|
|
|
|
// Status constants
|
|
const (
|
|
StatusOpen = types.StatusOpen
|
|
StatusInProgress = types.StatusInProgress
|
|
StatusBlocked = types.StatusBlocked
|
|
StatusDeferred = types.StatusDeferred
|
|
StatusClosed = types.StatusClosed
|
|
)
|
|
|
|
// IssueType constants
|
|
const (
|
|
TypeBug = types.TypeBug
|
|
TypeFeature = types.TypeFeature
|
|
TypeTask = types.TypeTask
|
|
TypeEpic = types.TypeEpic
|
|
TypeChore = types.TypeChore
|
|
)
|
|
|
|
// DependencyType constants
|
|
const (
|
|
DepBlocks = types.DepBlocks
|
|
DepRelated = types.DepRelated
|
|
DepParentChild = types.DepParentChild
|
|
DepDiscoveredFrom = types.DepDiscoveredFrom
|
|
DepConditionalBlocks = types.DepConditionalBlocks // B runs only if A fails (bd-kzda)
|
|
)
|
|
|
|
// SortPolicy constants
|
|
const (
|
|
SortPolicyHybrid = types.SortPolicyHybrid
|
|
SortPolicyPriority = types.SortPolicyPriority
|
|
SortPolicyOldest = types.SortPolicyOldest
|
|
)
|
|
|
|
// EventType 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
|
|
)
|