beads/internal/tracker/tracker.go
emma 083181e1ea feat: reimplement Notion sync on REST data sources (fix-merge PR #2759)
Adds internal/notion/ package with direct REST API client, field mapping,
and tracker adapter. Adds bd notion init/connect/status/sync commands.
Enhances tracker engine: conflict detection before pull, label sync,
no-op skip, batch push interface, RFC3339Nano timestamps. Removed dead
matchesFetchOptions function, added gosec nolint for Notion API client.

Co-Authored-By: Osamu Okano <okano.osamu@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-27 19:20:40 -07:00

107 lines
4.3 KiB
Go

package tracker
import (
"context"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/types"
)
// IssueTracker is the plugin interface that all tracker integrations must implement.
// Each external system (Linear, GitLab, Jira, etc.) provides an adapter implementing
// this interface. The SyncEngine uses it to perform bidirectional synchronization.
type IssueTracker interface {
// Name returns the lowercase identifier for this tracker (e.g., "linear", "gitlab").
Name() string
// DisplayName returns the human-readable name (e.g., "Linear", "GitLab").
DisplayName() string
// ConfigPrefix returns the config key prefix (e.g., "linear", "gitlab").
ConfigPrefix() string
// Init initializes the tracker with configuration from the beads config store.
// Called once before any sync operations.
Init(ctx context.Context, store storage.Storage) error
// Validate checks that the tracker is properly configured and can connect.
Validate() error
// Close releases any resources held by the tracker.
Close() error
// FetchIssues retrieves issues from the external tracker.
FetchIssues(ctx context.Context, opts FetchOptions) ([]TrackerIssue, error)
// FetchIssue retrieves a single issue by its external identifier.
// Returns nil, nil if the issue doesn't exist.
FetchIssue(ctx context.Context, identifier string) (*TrackerIssue, error)
// CreateIssue creates a new issue in the external tracker.
// Returns the created issue with its external ID and URL populated.
CreateIssue(ctx context.Context, issue *types.Issue) (*TrackerIssue, error)
// UpdateIssue updates an existing issue in the external tracker.
// The externalID is the tracker's internal ID (not the human-readable identifier).
UpdateIssue(ctx context.Context, externalID string, issue *types.Issue) (*TrackerIssue, error)
// FieldMapper returns the field mapper for this tracker.
FieldMapper() FieldMapper
// IsExternalRef checks if an external_ref string belongs to this tracker.
IsExternalRef(ref string) bool
// ExtractIdentifier extracts the human-readable identifier from an external_ref.
ExtractIdentifier(ref string) string
// BuildExternalRef constructs an external_ref string for a tracker issue.
BuildExternalRef(issue *TrackerIssue) string
}
// BatchPushTracker is an optional capability for trackers that can export
// multiple issues in one remote call.
type BatchPushTracker interface {
BatchPush(ctx context.Context, issues []*types.Issue, forceIDs map[string]bool) (*BatchPushResult, error)
}
// BatchPushDryRunner is an optional capability for trackers that can preview
// batch push decisions without mutating the remote system.
type BatchPushDryRunner interface {
BatchPushDryRun(ctx context.Context, issues []*types.Issue, forceIDs map[string]bool) (*BatchPushResult, error)
}
// PullStatsProvider is an optional capability for trackers that can report
// raw fetch counts separately from incremental pull candidates.
type PullStatsProvider interface {
LastPullStats() (queried int, candidates int)
}
// FieldMapper handles bidirectional conversion of issue fields between
// an external tracker and beads. Each tracker provides its own mapper.
type FieldMapper interface {
// PriorityToBeads converts a tracker priority to beads priority (0-4).
PriorityToBeads(trackerPriority interface{}) int
// PriorityToTracker converts a beads priority (0-4) to the tracker's format.
PriorityToTracker(beadsPriority int) interface{}
// StatusToBeads converts a tracker state to a beads status.
StatusToBeads(trackerState interface{}) types.Status
// StatusToTracker converts a beads status to the tracker's state format.
StatusToTracker(beadsStatus types.Status) interface{}
// TypeToBeads converts a tracker issue type to a beads issue type.
TypeToBeads(trackerType interface{}) types.IssueType
// TypeToTracker converts a beads issue type to the tracker's format.
TypeToTracker(beadsType types.IssueType) interface{}
// IssueToBeads performs a full conversion from a tracker issue to a beads issue.
// Returns the converted issue and any dependencies to be created.
IssueToBeads(trackerIssue *TrackerIssue) *IssueConversion
// IssueToTracker builds update fields from a beads issue for the external tracker.
// Returns a map of field names to values in the tracker's format.
IssueToTracker(issue *types.Issue) map[string]interface{}
}