Documentation
¶
Overview ¶
Package store owns all SQL and is the only package that imports the SQLite driver. It exposes domain types; callers never see *sql.Row.
Index ¶
- Constants
- Variables
- type BlockedTicket
- type ContextReport
- type ContextTicket
- type CreateParams
- type SearchParams
- type SearchResult
- type Store
- func (s *Store) AddComment(ctx context.Context, key, author, body string) (int, error)
- func (s *Store) AllTickets(ctx context.Context, project string) ([]domain.Ticket, error)
- func (s *Store) Backup(ctx context.Context, dest string) error
- func (s *Store) ClaimTicket(ctx context.Context, key, agent string, force bool) (domain.Ticket, error)
- func (s *Store) Close() error
- func (s *Store) ContextReport(ctx context.Context, project string) (ContextReport, error)
- func (s *Store) CreateTicket(ctx context.Context, p CreateParams) (t domain.Ticket, existed bool, err error)
- func (s *Store) GetTicketFull(ctx context.Context, key string) (domain.Ticket, error)
- func (s *Store) ReleaseClaim(ctx context.Context, key, agent string, force bool) (domain.Ticket, error)
- func (s *Store) Search(ctx context.Context, p SearchParams) ([]SearchResult, error)
- func (s *Store) UpdateTicket(ctx context.Context, p UpdateParams) (domain.Ticket, string, error)
- type UpdateParams
Constants ¶
const StaleAfter = 7 * 24 * time.Hour
StaleAfter is how long an in-progress ticket may go untouched before get_context flags it (design open question #3).
Variables ¶
var ErrClaimed = errors.New("claimed by another agent")
ErrClaimed is returned when a ticket is actively claimed by another agent.
var ErrNotFound = errors.New("not found")
ErrNotFound is returned when a ticket key does not resolve.
Functions ¶
This section is empty.
Types ¶
type BlockedTicket ¶
type BlockedTicket struct {
Key string
Title string
BlockedOn []domain.Link // tickets this one is blocked by (incoming blocks)
}
BlockedTicket names a blocked ticket and what it is blocked on.
type ContextReport ¶
type ContextReport struct {
Project string // "" means all projects
InProgress []ContextTicket
Blocked []BlockedTicket
NextUp []ContextTicket
BacklogN int
DoneN int
ClaimedN int // todo tickets hidden from NextUp because actively claimed
}
ContextReport is the structured backing for the get_context tool.
type ContextTicket ¶
type ContextTicket struct {
Key string
Title string
Priority domain.Priority
Status domain.Status
ParentKey string
LastActivity string // RFC3339-ish display time of last comment
LastComment string
Stale bool // in_progress/in_review and untouched beyond StaleAfter
StaleDays int // whole days since updated_at, when Stale
ClaimedBy string // advisory owner, if any (shown for in-progress tickets)
}
ContextTicket is a ticket plus its most recent worklog excerpt.
type CreateParams ¶
type CreateParams struct {
Title string
Description string
Project string
ParentKey string
Priority domain.Priority
Labels []string
}
CreateParams carries the inputs for creating a ticket.
type SearchParams ¶
SearchParams filters and full-text-searches tickets.
type SearchResult ¶
type SearchResult struct {
Key string
Title string
Status domain.Status
Priority domain.Priority
CommentCount int
MatchedTitle bool // matched in title/description
MatchedBody bool // matched in a comment
Snippet string
}
SearchResult is a compact match for list rendering.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store wraps a SQLite connection pool.
func Open ¶
Open opens (creating if needed) the database at path, applies pragmas and migrations, and returns a ready Store.
func (*Store) AddComment ¶
AddComment appends a worklog entry and touches the ticket's updated_at. Returns the new total comment count.
func (*Store) AllTickets ¶
AllTickets returns every ticket (optionally filtered by project) as lightweight records — no comments, links, or subtasks loaded. Ordered by priority then most-recently-updated, suitable for the read-only board.
func (*Store) Backup ¶
Backup writes a consistent copy of the database to dest using VACUUM INTO. dest must not already exist.
func (*Store) ClaimTicket ¶ added in v0.2.0
func (s *Store) ClaimTicket(ctx context.Context, key, agent string, force bool) (domain.Ticket, error)
ClaimTicket places a soft, advisory claim so concurrent agents skip the ticket. The whole transaction is the guard: two agents racing to claim the same ticket serialize, and only the first wins. A claim older than domain.ClaimTTL is treated as expired and may be taken. Re-claiming a ticket you already hold renews it. force=true takes over an active claim. On contention it returns ErrClaimed wrapped with an instructive message.
func (*Store) ContextReport ¶
ContextReport assembles the working-state report. project == "" spans all.
func (*Store) CreateTicket ¶
func (s *Store) CreateTicket(ctx context.Context, p CreateParams) (t domain.Ticket, existed bool, err error)
CreateTicket inserts a new ticket, allocating its key atomically from the project counter. If an open (non-terminal) ticket in the same project has a byte-identical title, that ticket is returned with existed=true and nothing is inserted — duplicates poison get_context, and agents retry.
func (*Store) GetTicketFull ¶
GetTicketFull returns a ticket with its comments, subtasks, and links.
func (*Store) ReleaseClaim ¶ added in v0.2.0
func (s *Store) ReleaseClaim(ctx context.Context, key, agent string, force bool) (domain.Ticket, error)
ReleaseClaim drops a soft claim. Without force, only the holding agent may release it; force releases regardless. Releasing an unclaimed ticket is a no-op.
func (*Store) Search ¶
func (s *Store) Search(ctx context.Context, p SearchParams) ([]SearchResult, error)
Search runs full-text search across ticket title/description and comment bodies, merges hits per ticket, applies filters, and ranks by bm25.
func (*Store) UpdateTicket ¶
UpdateTicket applies a partial update, validating status transitions through the FSM and recording any links. Returns the refreshed ticket and a short human-readable summary of what changed.