carts

package
v0.6.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 4, 2026 License: MIT Imports: 17 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func EnsureServer

func EnsureServer(cartsDir string) (int, error)

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

func FormatIssueDetail(i *Issue) string

FormatIssueDetail formats an issue for detailed display.

func FormatIssueJSON

func FormatIssueJSON(i *Issue) ([]byte, error)

FormatIssueJSON returns the JSON representation of an issue.

func FormatIssueListJSON

func FormatIssueListJSON(issues []*Issue) ([]byte, error)

FormatIssueListJSON returns the JSON representation of a list of issues.

func FormatIssueRow

func FormatIssueRow(i *Issue) string

FormatIssueRow formats an issue as a single-line row for table display.

func GenerateID

func GenerateID(title, description string, createdAt time.Time) string

GenerateID creates a deterministic content-based hash ID.

func StopServer

func StopServer(cartsDir string) error

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 BlockerInfo struct {
	CartID    string   `json:"cart_id"`
	CartTitle string   `json:"cart_title"`
	BlockedBy []string `json:"blocked_by_ids"`
}

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

func LoadCartsFromDir(cartsDir string) ([]*Issue, error)

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.

func (*Issue) Validate

func (i *Issue) Validate() error

Validate checks required fields and value constraints.

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 IssueType

type IssueType string

IssueType categorizes the work item.

const (
	TypeBug     IssueType = "bug"
	TypeFeature IssueType = "feature"
	TypeTask    IssueType = "task"
	TypeEpic    IssueType = "epic"
	TypeChore   IssueType = "chore"
)

func (IssueType) IsValid

func (t IssueType) IsValid() bool

type Learning

type Learning struct {
	Highlight string `json:"highlight"`
	Why       string `json:"why"`
	Source    string `json:"source"`
	Who       string `json:"who"`
}

type MurmurEvidence

type MurmurEvidence struct {
	ID         string `json:"id"`
	Content    string `json:"content"`
	Topic      string `json:"topic"`
	Importance string `json:"importance"`
	Timestamp  string `json:"timestamp"`
}

type NextStep

type NextStep struct {
	Task     string `json:"task"`
	Assignee string `json:"assignee,omitempty"`
	Priority string `json:"priority,omitempty"`
	FromCart string `json:"from_cart"`
}

type ProgressSummary

type ProgressSummary struct {
	TotalCarts     int            `json:"total_carts"`
	ByStatus       map[string]int `json:"by_status"`
	ByType         map[string]int `json:"by_type"`
	CompletionRate float64        `json:"completion_rate"`
	SessionCount   int            `json:"session_count"`
	MurmurCount    int            `json:"murmur_count"`
}

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.

const (
	StatusOpen       Status = "open"
	StatusInProgress Status = "in_progress"
	StatusClosed     Status = "closed"
)

func (Status) IsValid

func (s Status) IsValid() bool

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store wraps a DoltDB connection for carts CRUD operations.

func Init

func Init(ctx context.Context, cartsDir, committerName, committerEmail string) (*Store, error)

Init initializes a new carts store in the given directory.

func New

func New(ctx context.Context, cfg *Config) (*Store, error)

New creates or connects to a carts DoltDB store.

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) Close

func (s *Store) Close() error

Close closes the database connection.

func (*Store) CloseIssue

func (s *Store) CloseIssue(ctx context.Context, id string) error

CloseIssue sets a cart's status to closed.

func (*Store) Create

func (s *Store) Create(ctx context.Context, opts CreateOpts) (*Issue, error)

Create creates a new cart and returns it.

func (*Store) DropIssue

func (s *Store) DropIssue(ctx context.Context, id string) error

DropIssue abandons a cart: sets status back to open and clears assignee.

func (*Store) Get

func (s *Store) Get(ctx context.Context, id string) (*Issue, error)

Get retrieves a cart by ID.

func (*Store) GetDependencies

func (s *Store) GetDependencies(ctx context.Context, issueID string) ([]*Dependency, error)

GetDependencies returns dependencies for a cart.

func (*Store) List

func (s *Store) List(ctx context.Context, filter IssueFilter) ([]*Issue, error)

List returns carts matching the filter.

func (*Store) Ready

func (s *Store) Ready(ctx context.Context) ([]*Issue, error)

Ready returns open, unblocked carts.

func (*Store) RemoveDep

func (s *Store) RemoveDep(ctx context.Context, issueID, dependsOnID string) error

RemoveDep removes a dependency.

func (*Store) Reopen

func (s *Store) Reopen(ctx context.Context, id string) error

Reopen sets a closed cart back to open.

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

func (s *Store) StartIssue(ctx context.Context, id, assignee string) error

StartIssue claims a cart: sets status to in_progress and assigns it.

func (*Store) Update

func (s *Store) Update(ctx context.Context, id string, opts UpdateOpts) (*Issue, error)

Update modifies a cart's fields.

type TimeRange

type TimeRange struct {
	Since string `json:"since"`
	Until string `json:"until"`
}

type Transaction

type Transaction struct {
	// contains filtered or unexported fields
}

Transaction wraps a SQL transaction for Dolt commit tracking.

func (*Transaction) Exec

func (tx *Transaction) Exec(ctx context.Context, _ string, query string, args ...any) (sql.Result, error)

Exec executes a query within the transaction and marks it dirty.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL