task

type Backend interface {
	// Services returns the task-layer services produced by this backend.
	Services() BackendServices

	// CheckCompatibility verifies that the backend's data store is compatible
	// with this version of perles. Returns *VersionIncompatibleError if the
	// data store version is too old, nil if compatible.
	CheckCompatibility() error

	// FlushCaches invalidates all internal caches so subsequent queries
	// hit the data store instead of returning stale results.
	FlushCaches(ctx context.Context) error

	// Close releases all backend resources (database connections, etc.).
	Close() error
}

type BackendCapabilities struct {
	SupportsQuery        bool   // Can execute structured queries
	QueryLanguageName    string // "BQL", "JQL", etc. — shown in UI
	SupportsDependencies bool   // BlockedBy/Blocks tracking
	SupportsTree         bool   // Parent/child hierarchy
	SupportsComments     bool
	SupportsLabels       bool
	SupportsPriority     bool
	SupportsDesignField  bool
	SupportsNotesField   bool
}

type BackendServices struct {
	TaskExecutor      TaskExecutor
	QueryExecutor     QueryExecutor
	QueryHelpers      QueryHelpers        // nil if backend has no structured query language
	SyntaxHighlighter SyntaxHighlighter   // nil if backend has no query syntax highlighting
	Capabilities      BackendCapabilities // what the backend supports
	WatcherConfig     WatcherConfig       // file watcher configuration
	DBPath            string              // path to data store file (for watcher)
}

type Comment struct {
	ID        int       `json:"id"`
	Author    string    `json:"author"`
	Text      string    `json:"text"`
	CreatedAt time.Time `json:"created_at"`
}

type CreateResult struct {
	ID    string `json:"id"`
	Title string `json:"title"`
}

type DependencyEdge struct {
	TargetID string
	Type     string // "parent-child", "blocks", "discovered-from"
}

type DependencyGraph struct {
	Forward map[string][]DependencyEdge
	Reverse map[string][]DependencyEdge
}

type Issue struct {
	ID                 string    `json:"id"`
	TitleText          string    `json:"title"`
	DescriptionText    string    `json:"description"`
	Design             string    `json:"design"`
	AcceptanceCriteria string    `json:"acceptance_criteria"`
	Notes              string    `json:"notes"`
	Status             Status    `json:"status"`
	Priority           Priority  `json:"priority"`
	Type               IssueType `json:"type"`
	Assignee           string    `json:"assignee"`
	Labels             []string  `json:"labels"`
	CreatedAt          time.Time `json:"created_at"`
	UpdatedAt          time.Time `json:"updated_at"`
	ClosedAt           time.Time `json:"closed_at"`
	CloseReason        string    `json:"close_reason,omitempty"`
	ParentID           string    `json:"parent_id"`

	// Dependency tracking
	BlockedBy      []string `json:"blocked_by"`
	Blocks         []string `json:"blocks"`
	Children       []string `json:"children"`
	DiscoveredFrom []string `json:"discovered_from"`
	Discovered     []string `json:"discovered"`

	// Comments (populated on demand)
	Comments     []Comment `json:"comments,omitempty"`
	CommentCount int       `json:"comment_count,omitempty"`

	// Extensions allows backends to carry provider-specific data without
	// polluting the shared type. For example, beads agent fields (HookBead,
	// RoleBead, etc.) are stored here for round-tripping. UI code should
	// not read these directly.
	Extensions map[string]any `json:"extensions,omitempty"`
}

type IssueOption func(*Issue)

type IssueType string

type Priority int

type QueryExecutor interface {
	Execute(query string) ([]Issue, error)
}

type QueryHelpers interface {
	// BuildIDQuery constructs a query to fetch issues by their IDs.
	BuildIDQuery(ids []string) string

	// IsStructuredQuery returns true if the input looks like a structured query
	// (e.g. BQL) vs a plain text search.
	IsStructuredQuery(input string) bool

	// ValidateQuery validates a query string, returning an error if invalid.
	ValidateQuery(query string) error
}

type ServerDownError struct {
	Host string
	Port int
}

type Status string

type SyntaxHighlighter interface {
	// NewSyntaxLexer returns a syntax lexer for highlighting query input.
	// The returned value should implement the vimtextarea.SyntaxLexer interface.
	NewSyntaxLexer() any
}

type TaskExecutor interface {
	TaskReader
	TaskWriter
}

type TaskReader interface {
	ShowIssue(issueID string) (*Issue, error)
	GetComments(issueID string) ([]Comment, error)
}

type TaskWriter interface {
	UpdateStatus(issueID string, status Status) error
	UpdatePriority(issueID string, priority Priority) error
	UpdateType(issueID string, issueType IssueType) error
	UpdateTitle(issueID, title string) error
	UpdateDescription(issueID, description string) error
	UpdateNotes(issueID, notes string) error
	CloseIssue(issueID, reason string) error
	ReopenIssue(issueID string) error
	SetLabels(issueID string, labels []string) error
	AddComment(issueID, author, text string) error
	CreateEpic(title, description string, labels []string) (CreateResult, error)
	CreateTask(title, description, parentID, assignee string, labels []string) (CreateResult, error)
	DeleteIssues(issueIDs []string) error
	AddDependency(taskID, dependsOnID string) error
	UpdateIssue(issueID string, opts UpdateOptions) error
}

type UpdateOptions struct {
	Title       *string
	Description *string
	Notes       *string
	Priority    *Priority
	Status      *Status
	Labels      *[]string  // nil = unchanged, &[]string{} = clear all
	Assignee    *string    // nil = unchanged
	Type        *IssueType // nil = unchanged
}

type VersionIncompatibleError struct {
	Current  string // version found in the data store (or "unknown")
	Required string // minimum version required by this backend
}

type WatcherConfig struct {
	// RelevantFiles lists the base filenames that should trigger a refresh.
	// For example: ["beads.db", "beads.db-wal"] for SQLite backends.
	RelevantFiles []string

	// DebounceDuration is how long to wait after the last filesystem event
	// before publishing a change notification. Zero means use default (100ms).
	DebounceDuration time.Duration
}