* feat: export DependencyAddOptions from the root package Transaction.AddDependencyWithOptions and Transaction.CycleThroughEdges are both on the public Transaction interface, but the options type lived only in internal/storage — so the designed bulk path (SkipCycleCheck per edge + one whole-graph CycleThroughEdges pass before commit, bd-6dnrw.8) was uncallable by embedders. Gas City's native graph-apply pours molecule-sized batches (67 nodes / ~100 blocking edges) whose per-edge recursive cycle queries cannot finish inside a 120s per-command budget (observed 2026-07-17: the batch died at the deadline mid-edges twice, then fell back to per-bead creates — a 9-minute pour). Root-alias the type, with a compile-time proof that the alias satisfies the Transaction method. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(beads): mirror SkipCycleCheck whole-graph guardrail on public alias The exported beads.DependencyAddOptions alias documented only the happy path, dropping the imperative guardrail carried on the internal storage.DependencyAddOptions it aliases. Mirror that contract on the public surface: callers setting SkipCycleCheck MUST run Transaction.CycleThroughEdges before commit and fail on new blocks/conditional-blocks/parent-child cycles, so embedders reading the root-package doc do not skip the per-edge check with nothing replacing it and silently commit cycles. Maintainer review fixup for adopt-pr of PR #4870 (minor Contract & Interface Fidelity finding). No behavior change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Test User <test@test.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
198 lines
7.2 KiB
Go
198 lines
7.2 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/configfile"
|
|
"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
|
|
|
|
func configuredBackendUnavailable(backend string) error {
|
|
switch backend {
|
|
case configfile.BackendPostgres, configfile.BackendMySQL, configfile.BackendSQLite:
|
|
return configfile.RemovedBackendError(backend)
|
|
default:
|
|
return configfile.UnknownBackendError(backend)
|
|
}
|
|
}
|
|
|
|
// Transaction provides atomic multi-operation support within a database transaction.
|
|
// Use Storage.RunInTransaction() to obtain a Transaction instance.
|
|
type Transaction = beads.Transaction
|
|
|
|
// DependencyAddOptions controls transaction-scoped dependency insertion for
|
|
// Transaction.AddDependencyWithOptions. Exported so embedders' bulk graph
|
|
// writers can set SkipCycleCheck per edge and run one whole-graph
|
|
// Transaction.CycleThroughEdges pass before commit (bd-6dnrw.8) instead of
|
|
// paying the recursive per-edge cycle query — which cannot finish inside a
|
|
// per-command budget on molecule-sized graphs (observed: a 67-node/100-edge
|
|
// batch blowing a 120s deadline mid-transaction, gascity 2026-07-17).
|
|
//
|
|
// Callers that set SkipCycleCheck MUST run Transaction.CycleThroughEdges before
|
|
// commit and fail on new blocks/conditional-blocks/parent-child cycles
|
|
// (waits-for is excluded); skipping the per-edge check trades per-edge cost for
|
|
// one whole-graph check, never graph integrity.
|
|
type DependencyAddOptions = storage.DependencyAddOptions
|
|
|
|
// 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 the Dolt implementation using configuration from
|
|
// metadata.json. Unlike Open, this respects Dolt server mode settings and database
|
|
// name configuration.
|
|
// 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
|
|
)
|