Documentation
¶
Overview ¶
Package carts provides work item tracking backed by DoltDB. Modeled after Claude Code's task system: simple CRUD, dependency graph, status machine.
Index ¶
- func EnsureServer(cartsDir string) (int, error)
- func FormatIssueDetail(i *Issue) string
- func FormatIssueJSON(i *Issue) ([]byte, error)
- func FormatIssueListJSON(issues []*Issue) ([]byte, error)
- func FormatIssueRow(i *Issue) string
- func GenerateID(title, description string, createdAt time.Time) string
- func StopServer(cartsDir string) error
- type AnalysisOutput
- type AnalyzeInput
- type BlockerInfo
- type CartSummary
- type Config
- type CreateOpts
- type Dependency
- type DependencyType
- type Issue
- type IssueFilter
- type IssueType
- type Learning
- type MurmurEvidence
- type NextStep
- type ProgressSummary
- type Pyramid
- type PyramidSummary
- type SessionEvidence
- type Status
- type Store
- func (s *Store) AddDep(ctx context.Context, issueID, dependsOnID string, depType DependencyType) error
- func (s *Store) Close() error
- func (s *Store) CloseIssue(ctx context.Context, id string) error
- func (s *Store) Create(ctx context.Context, opts CreateOpts) (*Issue, error)
- func (s *Store) DropIssue(ctx context.Context, id string) error
- func (s *Store) Get(ctx context.Context, id string) (*Issue, error)
- func (s *Store) GetDependencies(ctx context.Context, issueID string) ([]*Dependency, error)
- func (s *Store) List(ctx context.Context, filter IssueFilter) ([]*Issue, error)
- func (s *Store) Ready(ctx context.Context) ([]*Issue, error)
- func (s *Store) RemoveDep(ctx context.Context, issueID, dependsOnID string) error
- func (s *Store) Reopen(ctx context.Context, id string) error
- func (s *Store) RunInTransaction(ctx context.Context, commitMsg string, fn func(tx *Transaction) error) error
- func (s *Store) StartIssue(ctx context.Context, id, assignee string) error
- func (s *Store) Update(ctx context.Context, id string, opts UpdateOpts) (*Issue, error)
- type TimeRange
- type Transaction
- type UpdateOpts
- type WorkItem
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnsureServer ¶
EnsureServer ensures a dolt sql-server is running for the carts database. If a server is already running (PID file exists and process alive), it returns the port. Otherwise it starts a new server on an ephemeral port.
func FormatIssueDetail ¶
FormatIssueDetail formats an issue for detailed display.
func FormatIssueJSON ¶
FormatIssueJSON returns the JSON representation of an issue.
func FormatIssueListJSON ¶
FormatIssueListJSON returns the JSON representation of a list of issues.
func FormatIssueRow ¶
FormatIssueRow formats an issue as a single-line row for table display.
func GenerateID ¶
GenerateID creates a deterministic content-based hash ID.
func StopServer ¶
StopServer stops a running dolt server for the given carts directory.
Types ¶
type AnalysisOutput ¶
type AnalysisOutput struct {
TimeRange TimeRange `json:"time_range"`
Headline string `json:"headline"`
Guidance string `json:"guidance"`
Pyramid PyramidSummary `json:"pyramid"`
Progress ProgressSummary `json:"progress"`
CartsByStatus map[string][]CartSummary `json:"carts_by_status"`
WorkItems []WorkItem `json:"work_items"`
Blockers []BlockerInfo `json:"blockers"`
Learnings []Learning `json:"learnings"`
NextSteps []NextStep `json:"next_steps"`
}
AnalysisOutput is the structured dump for AI consumption. Answers: where are we, what's blocking, what we learned, what's next.
func Analyze ¶
func Analyze(input AnalyzeInput) (*AnalysisOutput, error)
Analyze takes carts + dependencies and enriches them with ledger session/murmur data. Caller is responsible for loading carts from whatever source (DoltDB, JSON files, etc).
type AnalyzeInput ¶
type AnalyzeInput struct {
Carts []*Issue
Dependencies map[string][]*Dependency // cart ID → deps
LedgerPath string
Since time.Time
Until time.Time
}
AnalyzeInput holds everything Analyze needs. The caller decides where carts and dependencies come from — DoltDB in production, JSON files in tests.
type BlockerInfo ¶
type CartSummary ¶
type CartSummary struct {
ID string `json:"id"`
Title string `json:"title"`
Assignee string `json:"assignee"`
Type string `json:"type"`
Priority int `json:"priority"`
Pyramid Pyramid `json:"pyramid"`
}
CartSummary is a compact view of a cart for status-grouped listings.
type Config ¶
type Config struct {
CartsDir string
Database string
CommitterName string
CommitterEmail string
ServerHost string
ServerPort int
}
Config holds the store configuration.
type CreateOpts ¶
type CreateOpts struct {
Title string
Description string
IssueType IssueType
Priority int
Assignee string
Creator string
Source string
}
CreateOpts holds options for creating a new cart.
type Dependency ¶
type Dependency struct {
IssueID string `json:"issue_id"`
DependsOnID string `json:"depends_on_id"`
Type DependencyType `json:"type"`
CreatedAt time.Time `json:"created_at"`
}
Dependency represents a relationship between two carts (the dependency graph).
type DependencyType ¶
type DependencyType string
DependencyType categorizes dependency relationships.
const ( DepBlocks DependencyType = "blocks" DepRelated DependencyType = "related" DepDiscoveredFrom DependencyType = "discovered-from" )
func (DependencyType) IsValid ¶
func (d DependencyType) IsValid() bool
type Issue ¶
type Issue struct {
ID string `json:"id"`
Title string `json:"title"`
Description string `json:"description,omitempty"`
Status Status `json:"status"`
Priority int `json:"priority"`
IssueType IssueType `json:"issue_type"`
Assignee string `json:"assignee,omitempty"`
Creator string `json:"creator,omitempty"`
Source string `json:"source,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
ClosedAt *time.Time `json:"closed_at,omitempty"`
// Populated on Show/Get for display
Dependencies []*Dependency `json:"dependencies,omitempty"`
}
Issue represents a cart — a trackable work item.
func LoadCartsFromDir ¶
LoadCartsFromDir reads cart JSON files from a directory (e.g. digital twin output).
func (*Issue) SetDefaults ¶
func (i *Issue) SetDefaults()
SetDefaults applies defaults for omitted fields.
type IssueFilter ¶
type IssueFilter struct {
Status string // single status or comma-separated
Assignee string
Priority *int
IssueType string
CreatedSince *time.Time // created_at >= since
CreatedUntil *time.Time // created_at <= until
Limit int
}
IssueFilter holds filter criteria for listing carts.
type MurmurEvidence ¶
type ProgressSummary ¶
type Pyramid ¶
type Pyramid struct {
L2 string `json:"l2"` // 2 words: scan-level
L4 string `json:"l4"` // 4 words: triage-level
L8 string `json:"l8"` // 8 words: context-level
L16 string `json:"l16,omitempty"` // 16 words: detail-level (omitted at cart level)
}
Pyramid holds multi-resolution summaries for progressive disclosure. AI coworkers scan L2 (2 words) for hundreds of items, then zoom into L4/L8/L16 only for items that need attention.
Inspired by StrongDM's "Pyramid Summaries" technique for agentic factories.
type PyramidSummary ¶
type PyramidSummary struct {
Overall Pyramid `json:"overall"`
ByStatus map[string]Pyramid `json:"by_status"`
}
PyramidSummary is the top-level pyramid view of an analysis.
type SessionEvidence ¶
type SessionEvidence struct {
DirName string `json:"dir_name"`
Outcome string `json:"outcome"`
QualityScore float64 `json:"quality_score"`
Summary string `json:"summary"`
KeyActions []string `json:"key_actions,omitempty"`
Decisions []sessionsummary.Decision `json:"decisions,omitempty"`
ActionItems []sessionsummary.ActionItem `json:"action_items,omitempty"`
OpenQuestions []sessionsummary.OpenQuestion `json:"open_questions,omitempty"`
FilesChanged []sessionsummary.FileSummary `json:"files_changed,omitempty"`
AhaMoments []sessionsummary.AhaMoment `json:"aha_moments,omitempty"`
}
SessionEvidence is the relevant subset of summary.json for analysis.
type Status ¶
type Status string
Status represents the lifecycle state. Mirrors Claude Code: pending → in_progress → completed.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store wraps a DoltDB connection for carts CRUD operations.
func OpenFromTeamContext ¶
func OpenFromTeamContext(ctx context.Context, teamContextDir, committerName, committerEmail string) (*Store, error)
OpenFromTeamContext resolves the carts directory from team context and opens the store.
func (*Store) AddDep ¶
func (s *Store) AddDep(ctx context.Context, issueID, dependsOnID string, depType DependencyType) error
AddDep adds a dependency between two carts.
func (*Store) CloseIssue ¶
CloseIssue sets a cart's status to closed.
func (*Store) GetDependencies ¶
GetDependencies returns dependencies for a cart.
func (*Store) RunInTransaction ¶
func (s *Store) RunInTransaction(ctx context.Context, commitMsg string, fn func(tx *Transaction) error) error
RunInTransaction executes fn within a SQL transaction, then creates a Dolt commit.
func (*Store) StartIssue ¶
StartIssue claims a cart: sets status to in_progress and assigns it.
type Transaction ¶
type Transaction struct {
// contains filtered or unexported fields
}
Transaction wraps a SQL transaction for Dolt commit tracking.
type UpdateOpts ¶
type UpdateOpts struct {
Title *string
Description *string
IssueType *IssueType
Priority *int
Status *Status
Assignee *string
}
UpdateOpts holds options for updating a cart. Nil fields are not changed.
type WorkItem ¶
type WorkItem struct {
Cart *Issue `json:"cart"`
Session *SessionEvidence `json:"session,omitempty"`
Murmurs []MurmurEvidence `json:"murmurs,omitempty"`
}
WorkItem joins a cart with its session and murmur evidence.