Documentation
¶
Overview ¶
Package gig is a lightweight task management SDK backed by SQLite.
File Layout ¶
gig.go – Domain types: Task, Status, Priority, Event, Attribute, etc. store.go – Store constructor (Open/Close), ID generation, event system task.go – Task mutations: Create, Get, Update, Close, Reopen, Claim query.go – Task queries: List, Search, Ready, Blocked, Children, GetTree dependency.go – Dependency DAG: Add, Remove, cycle detection, tree visualization attribute.go – Custom attributes: Define, Set, Get, type validation comment.go – Comments: Add, List event.go – Event queries: Events, EventsSince hook.go – Shell hook execution from config config.go – Config loading (gig.yaml), defaults, paths export.go – JSONL export/import for sync util.go – Time parsing, label serialization helpers
Package gig provides an embeddable task management system with SQLite storage, dependency tracking, and an event-driven hook system.
Index ¶
- Variables
- func DefaultConfigPath() string
- func DefaultDBPath() string
- func DefaultGigHome() string
- func GenerateID(prefix string, hashLen int) string
- func MaterializeHooks(gigHome string) (agentDir, gitDir string, err error)
- func SaveConfig(path string, cfg *Config) error
- type AttrDefinition
- type AttrType
- type Attribute
- type Checkpoint
- type CheckpointParams
- type ClaimResult
- type Comment
- type Config
- type CreateParams
- type DepType
- type Dependency
- type Diagnostic
- type DiagnosticLevel
- type DoctorReport
- type Event
- type EventType
- type HookConfig
- type HookDef
- type ListParams
- type Option
- type Priority
- type Status
- type Store
- func (s *Store) AddCheckpoint(taskID, author string, params CheckpointParams) (*Checkpoint, error)
- func (s *Store) AddComment(taskID, author, content string) (*Comment, error)
- func (s *Store) AddDependency(fromID, toID string, depType DepType) error
- func (s *Store) Attrs(taskID string) ([]*Attribute, error)
- func (s *Store) Blocked() ([]*Task, error)
- func (s *Store) CancelTask(id string, reason string, actor string) error
- func (s *Store) Children(id string) ([]*Task, error)
- func (s *Store) Claim(id string, assignee string) (*ClaimResult, error)
- func (s *Store) Close() error
- func (s *Store) CloseMany(ids []string, reason string, actor string) error
- func (s *Store) CloseTask(id string, reason string, actor string) error
- func (s *Store) Create(p CreateParams) (*Task, error)
- func (s *Store) DB() *sql.DB
- func (s *Store) DefineAttr(key string, attrType AttrType, description string) error
- func (s *Store) DeleteAttr(taskID, key string) error
- func (s *Store) DeleteTask(id string, actor string) error
- func (s *Store) DepTree(id string) (string, error)
- func (s *Store) DetectCycles() ([][]string, error)
- func (s *Store) Doctor() (*DoctorReport, error)
- func (s *Store) EnableHooks()
- func (s *Store) Events(taskID string) ([]*Event, error)
- func (s *Store) EventsSince(since time.Time) ([]*Event, error)
- func (s *Store) ExportEvents(path string) error
- func (s *Store) ExportJSONL(path string) error
- func (s *Store) Get(id string) (*Task, error)
- func (s *Store) GetAttr(taskID, key string) (*Attribute, error)
- func (s *Store) GetAttrDef(key string) (*AttrDefinition, error)
- func (s *Store) GetFull(id string) (*Task, error)
- func (s *Store) GetTree(id string) (*Task, error)
- func (s *Store) ImportJSONL(path string) error
- func (s *Store) LatestCheckpoint(taskID string) (*Checkpoint, error)
- func (s *Store) List(p ListParams) ([]*Task, error)
- func (s *Store) ListAttrDefs() ([]*AttrDefinition, error)
- func (s *Store) ListCheckpoints(taskID string) ([]*Checkpoint, error)
- func (s *Store) ListComments(taskID string) ([]*Comment, error)
- func (s *Store) ListDependencies(id string) ([]*Dependency, error)
- func (s *Store) ListDependents(id string) ([]*Dependency, error)
- func (s *Store) Off(eventType EventType)
- func (s *Store) On(eventType EventType, fn func(Event))
- func (s *Store) Prefix() string
- func (s *Store) Ready(parentID string) ([]*Task, error)
- func (s *Store) RemoveDependency(fromID, toID string) error
- func (s *Store) Reopen(id string, actor string) error
- func (s *Store) RunHooks(event Event)
- func (s *Store) Search(query string) ([]*Task, error)
- func (s *Store) SetAttr(taskID, key, value string) error
- func (s *Store) UndefineAttr(key string) error
- func (s *Store) Update(id string, p UpdateParams, actor string) (*Task, error)
- func (s *Store) UpdateStatus(id string, status Status, actor string) error
- type Task
- type TaskType
- type UpdateParams
Constants ¶
This section is empty.
Variables ¶
var HookFS embed.FS
var ValidAttrTypes = []AttrType{AttrString, AttrBoolean, AttrObject}
ValidAttrTypes is the set of valid attribute types.
var ValidStatuses = []Status{StatusOpen, StatusInProgress, StatusBlocked, StatusDeferred, StatusClosed, StatusCancelled}
ValidStatuses is the set of all valid status values.
var ValidTaskTypes = []TaskType{TypeTask, TypeBug, TypeFeature, TypeEpic, TypeChore}
ValidTaskTypes is the set of all valid task type values.
Functions ¶
func DefaultConfigPath ¶
func DefaultConfigPath() string
DefaultConfigPath returns the default config file path.
func DefaultGigHome ¶
func DefaultGigHome() string
DefaultGigHome returns the default gig home directory (~/.gig). Respects GIG_HOME env var.
func GenerateID ¶
GenerateID produces a short, prefix-based ID like "gig-a3f8". The hash is derived from a UUID + current timestamp to ensure uniqueness.
func MaterializeHooks ¶
MaterializeHooks writes the embedded hook scripts to gigHome/hooks/. Returns the absolute paths to the agent and git hook directories. Idempotent: always overwrites with the version from the binary.
func SaveConfig ¶
SaveConfig writes the config to a YAML file.
Types ¶
type AttrDefinition ¶
type AttrDefinition struct {
Key string `json:"key"`
Type AttrType `json:"type"`
Description string `json:"description,omitempty"`
CreatedAt time.Time `json:"created_at"`
}
AttrDefinition describes an allowed custom attribute key and its type.
type Attribute ¶
type Attribute struct {
TaskID string `json:"task_id"`
Key string `json:"key"`
Value string `json:"value"`
Type AttrType `json:"type"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
Attribute is a typed key-value pair attached to a task.
func (*Attribute) BoolValue ¶
BoolValue returns the attribute value as a bool. Returns false if not "true".
func (*Attribute) ObjectValue ¶
ObjectValue parses the JSON value into a map.
func (*Attribute) StringValue ¶
StringValue returns the raw string value.
type Checkpoint ¶
type Checkpoint struct {
ID string `json:"id"`
TaskID string `json:"task_id"`
Author string `json:"author,omitempty"`
Done string `json:"done"`
Decisions string `json:"decisions,omitempty"`
Next string `json:"next,omitempty"`
Blockers string `json:"blockers,omitempty"`
Files []string `json:"files,omitempty"`
CreatedAt time.Time `json:"created_at"`
}
Checkpoint is a structured progress snapshot attached to a task.
type CheckpointParams ¶
type CheckpointParams struct {
Done string // What was accomplished
Decisions string // Key decisions and reasoning
Next string // What should happen next
Blockers string // Current blockers, if any
Files []string // File paths touched or referenced
}
CheckpointParams holds the inputs for creating a checkpoint.
type ClaimResult ¶ added in v0.6.1
type ClaimResult struct {
ParentProgressed bool // true if parent was auto-moved to in_progress
ParentID string // parent task ID (if progressed)
}
ClaimResult holds information about what happened during a Claim.
type Comment ¶
type Comment struct {
ID string `json:"id"`
TaskID string `json:"task_id"`
Author string `json:"author,omitempty"`
Content string `json:"content"`
CreatedAt time.Time `json:"created_at"`
}
Comment is a note attached to a task.
type Config ¶
type Config struct {
Prefix string `yaml:"prefix"`
DBPath string `yaml:"db_path"`
HashLen int `yaml:"hash_length"`
SyncRepo string `yaml:"sync_repo"`
DefaultView string `yaml:"default_view"` // "list" or "tree" (default: "list")
ShowAll bool `yaml:"show_all"` // if true, include closed tasks by default
Hooks HookConfig `yaml:"hooks"`
}
Config represents the gig.yaml configuration file.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns a Config with sensible defaults.
func LoadConfig ¶
LoadConfig reads and parses a gig.yaml file. Returns DefaultConfig if the file doesn't exist.
type CreateParams ¶
type CreateParams struct {
Title string
Description string
Type TaskType
Priority Priority
ParentID string
Assignee string
Labels []string
Notes string
Estimate int
DueAt *time.Time
CreatedBy string
Metadata string
}
CreateParams holds the inputs for creating a new task.
type Dependency ¶
type Dependency struct {
FromID string `json:"from_id"`
ToID string `json:"to_id"`
Type DepType `json:"type"`
CreatedAt time.Time `json:"created_at"`
}
Dependency represents a directional relationship between tasks.
type Diagnostic ¶
type Diagnostic struct {
Level DiagnosticLevel `json:"level"`
Check string `json:"check"`
Message string `json:"message"`
}
Diagnostic represents a single health check result.
type DiagnosticLevel ¶
type DiagnosticLevel string
DiagnosticLevel indicates the severity of a diagnostic finding.
const ( DiagOK DiagnosticLevel = "ok" DiagWarn DiagnosticLevel = "warn" DiagFail DiagnosticLevel = "fail" )
type DoctorReport ¶
type DoctorReport struct {
Diagnostics []Diagnostic `json:"diagnostics"`
}
DoctorReport contains the full results of a health check.
func (*DoctorReport) HasIssues ¶
func (r *DoctorReport) HasIssues() bool
HasIssues returns true if the report contains any warnings or failures.
type Event ¶
type Event struct {
ID int64 `json:"id"`
TaskID string `json:"task_id"`
Type EventType `json:"event_type"`
Actor string `json:"actor,omitempty"`
Field string `json:"field,omitempty"`
OldValue string `json:"old_value,omitempty"`
NewValue string `json:"new_value,omitempty"`
Timestamp time.Time `json:"timestamp"`
}
Event records a change that happened to a task.
type EventType ¶
type EventType string
EventType describes what happened to a task.
const ( EventCreated EventType = "created" EventUpdated EventType = "updated" EventStatusChanged EventType = "status_changed" EventCommented EventType = "commented" EventAssigned EventType = "assigned" EventClosed EventType = "closed" EventDependencyAdded EventType = "dependency_added" EventDependencyRemoved EventType = "dependency_removed" EventDeleted EventType = "deleted" )
type HookConfig ¶
type HookConfig struct {
OnStatusChange []HookDef `yaml:"on_status_change"`
OnCreate []HookDef `yaml:"on_create"`
OnComment []HookDef `yaml:"on_comment"`
OnClose []HookDef `yaml:"on_close"`
OnAssign []HookDef `yaml:"on_assign"`
}
HookConfig maps event types to lists of hook definitions.
type HookDef ¶
type HookDef struct {
Command string `yaml:"command"`
Filter map[string]string `yaml:"filter,omitempty"`
}
HookDef defines a single hook command with optional filter.
type ListParams ¶
type ListParams struct {
Status *Status
Assignee string
Priority *Priority
ParentID *string // pointer so we can distinguish "not set" from "root tasks"
Type *TaskType
Label string
AttrFilter map[string]string // filter by custom attributes: key→value
ExcludeStatuses []Status // tasks with these statuses are excluded
Limit int
Offset int
}
ListParams controls filtering and pagination for List queries.
type Option ¶
type Option func(*Store)
Option configures a Store during Open.
func WithConfig ¶
WithConfig attaches a parsed Config to the store.
func WithHashLength ¶
WithHashLength sets the hash portion length of generated IDs (3-8, default: 4).
type Priority ¶
type Priority int
Priority represents task urgency (0 = critical, 4 = backlog).
type Status ¶
type Status string
Status represents the lifecycle state of a task.
func (Status) IsTerminal ¶
IsTerminal returns true if the status represents a final state (closed or cancelled).
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is the main entry point for the gig SDK. It holds the database connection, configuration, and event listeners.
func Open ¶
Open creates or opens a gig database at the given path. It runs pending migrations and enables WAL mode and foreign keys.
func (*Store) AddCheckpoint ¶
func (s *Store) AddCheckpoint(taskID, author string, params CheckpointParams) (*Checkpoint, error)
AddCheckpoint creates a structured progress snapshot on a task.
func (*Store) AddComment ¶
AddComment creates a comment on a task.
func (*Store) AddDependency ¶
AddDependency creates a dependency: fromID depends on toID. It checks for cycles before inserting.
func (*Store) CancelTask ¶
CancelTask sets a task to cancelled with a reason. Also triggers auto-unblock. Cancelling a parent cascades to all non-terminal children.
func (*Store) Claim ¶
func (s *Store) Claim(id string, assignee string) (*ClaimResult, error)
Claim atomically sets assignee and status to in_progress. If the task has a parent that is open, it is auto-progressed to in_progress.
func (*Store) Create ¶
func (s *Store) Create(p CreateParams) (*Task, error)
Create inserts a new task and returns it.
func (*Store) DefineAttr ¶
DefineAttr registers a new attribute key with its type. This must be called before SetAttr can use that key.
func (*Store) DeleteAttr ¶
DeleteAttr removes a custom attribute from a task.
func (*Store) DeleteTask ¶
DeleteTask permanently removes a task and its children from the database. Comments, dependencies, and custom attributes are removed via CASCADE. Events are preserved as an audit trail.
func (*Store) DetectCycles ¶
DetectCycles finds all cycles in the dependency graph. Returns a slice of cycles, where each cycle is a slice of task IDs.
func (*Store) Doctor ¶
func (s *Store) Doctor() (*DoctorReport, error)
Doctor runs health checks on the store and returns a report.
func (*Store) EnableHooks ¶
func (s *Store) EnableHooks()
EnableHooks wires up the store's event system to fire shell hooks. Call this after opening a store with a config that has hooks defined.
func (*Store) EventsSince ¶
EventsSince returns all events after the given timestamp.
func (*Store) ExportEvents ¶
ExportEvents exports all events to a JSONL file.
func (*Store) ExportJSONL ¶
ExportJSONL exports all tasks to a JSONL file, sorted deterministically by ID.
func (*Store) GetAttrDef ¶
func (s *Store) GetAttrDef(key string) (*AttrDefinition, error)
GetAttrDef retrieves a single attribute definition.
func (*Store) GetFull ¶ added in v0.6.0
GetFull retrieves a task with its custom attributes populated.
func (*Store) ImportJSONL ¶
ImportJSONL imports tasks from a JSONL file using upsert semantics. Existing tasks are updated, new tasks are inserted. Foreign key checks are deferred during import to handle parent ordering.
func (*Store) LatestCheckpoint ¶
func (s *Store) LatestCheckpoint(taskID string) (*Checkpoint, error)
LatestCheckpoint returns the most recent checkpoint for a task, or nil if none exist.
func (*Store) List ¶
func (s *Store) List(p ListParams) ([]*Task, error)
List returns tasks matching the given filters.
func (*Store) ListAttrDefs ¶
func (s *Store) ListAttrDefs() ([]*AttrDefinition, error)
ListAttrDefs returns all defined attribute types.
func (*Store) ListCheckpoints ¶
func (s *Store) ListCheckpoints(taskID string) ([]*Checkpoint, error)
ListCheckpoints returns all checkpoints for a task, oldest first.
func (*Store) ListComments ¶
ListComments returns all comments for a task, oldest first.
func (*Store) ListDependencies ¶
func (s *Store) ListDependencies(id string) ([]*Dependency, error)
ListDependencies returns what a task depends on (its blockers).
func (*Store) ListDependents ¶
func (s *Store) ListDependents(id string) ([]*Dependency, error)
ListDependents returns tasks that depend on the given task.
func (*Store) Ready ¶
Ready returns open/in_progress tasks that have no unresolved blockers. Ready returns open tasks that have no unresolved blockers — i.e. tasks available to be picked up. If parentID is non-empty, only returns children (direct and nested) of that task.
func (*Store) RemoveDependency ¶
RemoveDependency removes a dependency between two tasks.
func (*Store) RunHooks ¶
RunHooks executes shell hooks matching the given event. Hooks are non-blocking (fire-and-forget goroutines).
func (*Store) SetAttr ¶
SetAttr sets a custom attribute value on a task. The attribute key must be defined first via DefineAttr. The value is validated against the definition's type.
func (*Store) UndefineAttr ¶
UndefineAttr removes an attribute definition and all its values across all tasks.
type Task ¶
type Task struct {
ID string `json:"id"`
ParentID string `json:"parent_id,omitempty"`
Title string `json:"title"`
Description string `json:"description,omitempty"`
Status Status `json:"status"`
Priority Priority `json:"priority"`
Assignee string `json:"assignee,omitempty"`
Type TaskType `json:"type"`
Labels []string `json:"labels,omitempty"`
Notes string `json:"notes,omitempty"`
Estimate int `json:"estimate,omitempty"` // minutes
DueAt *time.Time `json:"due_at,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
ClosedAt *time.Time `json:"closed_at,omitempty"`
CloseReason string `json:"close_reason,omitempty"`
CreatedBy string `json:"created_by,omitempty"`
Metadata string `json:"metadata,omitempty"` // arbitrary JSON
// Populated by GetTree — not stored in DB directly.
Children []*Task `json:"children,omitempty"`
// Populated by GetFull — not stored in DB directly.
Attrs map[string]string `json:"attrs,omitempty"`
}
Task is the primary entity in gig.
type UpdateParams ¶
type UpdateParams struct {
Title *string
Description *string
Priority *Priority
Assignee *string
Labels *[]string
Notes *string
Estimate *int
DueAt *time.Time
Metadata *string
ParentID *string // set parent (non-empty ID)
Orphan bool // remove parent (set parent_id to NULL)
}
UpdateParams holds optional fields for updating a task. Pointer fields: nil means "don't change", non-nil means "set to this value".
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
gig
command
|
|
|
examples
|
|
|
gig-controller
command
gig-controller is a web-based kanban board that demonstrates the gig SDK.
|
gig-controller is a web-based kanban board that demonstrates the gig SDK. |
|
internal
|
|
|
migrate
Package migrate handles schema versioning for the gig SQLite database.
|
Package migrate handles schema versioning for the gig SQLite database. |
|
Package ui provides an embedded web-based kanban board for gig.
|
Package ui provides an embedded web-based kanban board for gig. |