beads/beads.go
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

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
)