statedb

package
v0.26.2 Latest Latest
Warning

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

 Go to latest Published: Mar 16, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
const SchemaVersion = 2

SchemaVersion tracks the current database schema version. Bump this when adding migrations.

Variables

This section is empty.

Functions

func MarshalToolData 

func MarshalToolData(
	claudeSessionID string, claudeDetectedAt time.Time,
	geminiSessionID string, geminiDetectedAt time.Time,
	geminiYoloMode *bool, geminiModel string,
	openCodeSessionID string, openCodeDetectedAt time.Time,
	codexSessionID string, codexDetectedAt time.Time,
	latestPrompt string, notes string, loadedMCPNames []string,
	toolOptionsJSON json.RawMessage,
	sandboxJSON json.RawMessage, sandboxContainer string,
	sshHost string, sshRemotePath string,
	multiRepoEnabled bool, additionalPaths []string,
	multiRepoTempDir string, multiRepoWorktrees []MultiRepoWorktreeData,
) json.RawMessage

func MigrateFromJSON 

func MigrateFromJSON(jsonPath string, db *StateDB) (int, int, error)

MigrateFromJSON reads a sessions.json file and inserts all data into the StateDB. Returns the number of instances and groups migrated.

func SetGlobal 

func SetGlobal(db *StateDB)

SetGlobal sets the global StateDB instance.

Types

type GroupRow 

type GroupRow struct {
	Path        string
	Name        string
	Expanded    bool
	Order       int
	DefaultPath string
}

GroupRow represents a group row in the database.

type InstanceRow 

type InstanceRow struct {
	ID              string
	Title           string
	ProjectPath     string
	GroupPath       string
	Order           int
	Command         string
	Wrapper         string
	Tool            string
	Status          string
	TmuxSession     string
	CreatedAt       time.Time
	LastAccessed    time.Time
	ParentSessionID string
	WorktreePath    string
	WorktreeRepo    string
	WorktreeBranch  string
	ToolData        json.RawMessage // JSON blob for tool-specific data
}

InstanceRow represents a session row in the database.

type MultiRepoWorktreeData added in v0.26.2 

type MultiRepoWorktreeData struct {
	OriginalPath string
	WorktreePath string
	RepoRoot     string
	Branch       string
}

MarshalToolData creates a tool_data JSON blob from individual fields. This is the forward path: Instance fields -> JSON blob for SQLite storage. MultiRepoWorktreeData holds multi-repo worktree info for serialization.

func UnmarshalToolData 

func UnmarshalToolData(data json.RawMessage) (
	claudeSessionID string, claudeDetectedAt time.Time,
	geminiSessionID string, geminiDetectedAt time.Time,
	geminiYoloMode *bool, geminiModel string,
	openCodeSessionID string, openCodeDetectedAt time.Time,
	codexSessionID string, codexDetectedAt time.Time,
	latestPrompt string, notes string, loadedMCPNames []string,
	toolOptionsJSON json.RawMessage,
	sandboxJSON json.RawMessage, sandboxContainer string,
	sshHost string, sshRemotePath string,
	multiRepoEnabled bool, additionalPaths []string,
	multiRepoTempDir string, multiRepoWorktrees []MultiRepoWorktreeData,
)

UnmarshalToolData extracts individual fields from the tool_data JSON blob. This is the reverse path: JSON blob from SQLite -> individual Instance fields.

type RecentSessionRow added in v0.20.0 

type RecentSessionRow struct {
	ID             string // SHA-256 dedup key (title+path+tool+group)
	Title          string
	ProjectPath    string
	GroupPath      string
	Command        string
	Wrapper        string
	Tool           string
	ToolOptions    json.RawMessage // serialized ToolOptionsWrapper
	SandboxEnabled bool
	GeminiYoloMode *bool
	DeletedAt      time.Time
}

RecentSessionRow captures the config of a deleted session for quick re-creation.

type StateDB 

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

StateDB wraps a SQLite database for session/group persistence. Thread-safe for concurrent use from multiple goroutines within one process. Multiple OS processes can safely read/write via WAL mode + busy timeout.

func GetGlobal 

func GetGlobal() *StateDB

GetGlobal returns the global StateDB instance (may be nil).

func Open 

func Open(dbPath string) (*StateDB, error)

Open creates or opens a SQLite database at dbPath with WAL mode and busy timeout.

func (*StateDB) AliveInstanceCount 

func (s *StateDB) AliveInstanceCount() (int, error)

AliveInstanceCount returns how many TUI instances have fresh heartbeats.

func (*StateDB) CleanDeadInstances 

func (s *StateDB) CleanDeadInstances(timeout time.Duration) error

CleanDeadInstances removes heartbeat entries that haven't been updated within timeout.

func (*StateDB) Close 

func (s *StateDB) Close() error

Close checkpoints WAL and closes the database.

func (*StateDB) DB 

func (s *StateDB) DB() *sql.DB

DB returns the underlying sql.DB for advanced use cases (e.g., testing).

func (*StateDB) DeleteGroup 

func (s *StateDB) DeleteGroup(path string) error

DeleteGroup removes a group by path.

func (*StateDB) DeleteInstance 

func (s *StateDB) DeleteInstance(id string) error

DeleteInstance removes an instance by ID.

func (*StateDB) ElectPrimary added in v0.11.1 

func (s *StateDB) ElectPrimary(timeout time.Duration) (bool, error)

ElectPrimary attempts to make this instance the primary. Returns true if this instance is now (or already was) the primary. Uses a transaction to atomically clear stale primaries and claim if available.

func (*StateDB) GetMeta 

func (s *StateDB) GetMeta(key string) (string, error)

GetMeta gets a value from the metadata table. Returns "" if not found.

func (*StateDB) Heartbeat 

func (s *StateDB) Heartbeat() error

Heartbeat updates the heartbeat timestamp for this process.

func (*StateDB) IsEmpty 

func (s *StateDB) IsEmpty() (bool, error)

IsEmpty returns true if the instances table has no rows.

func (*StateDB) LastModified 

func (s *StateDB) LastModified() (int64, error)

LastModified returns the last_modified timestamp from metadata.

func (*StateDB) LoadGroups 

func (s *StateDB) LoadGroups() ([]*GroupRow, error)

LoadGroups returns all groups ordered by sort_order.

func (*StateDB) LoadInstances 

func (s *StateDB) LoadInstances() ([]*InstanceRow, error)

LoadInstances returns all instances ordered by sort_order.

func (*StateDB) LoadRecentSessions added in v0.20.0 

func (s *StateDB) LoadRecentSessions() ([]*RecentSessionRow, error)

LoadRecentSessions returns all recent sessions ordered by most recently deleted.

func (*StateDB) Migrate 

func (s *StateDB) Migrate() error

Migrate creates tables if they don't exist and runs any pending migrations.

func (*StateDB) ReadAllStatuses 

func (s *StateDB) ReadAllStatuses() (map[string]StatusRow, error)

ReadAllStatuses returns status + acknowledged flag for every instance.

func (*StateDB) RegisterInstance 

func (s *StateDB) RegisterInstance(isPrimary bool) error

RegisterInstance records this process as an active TUI instance.

func (*StateDB) ResignPrimary added in v0.11.1 

func (s *StateDB) ResignPrimary() error

ResignPrimary clears the is_primary flag for this process.

func (*StateDB) SaveGroups 

func (s *StateDB) SaveGroups(groups []*GroupRow) error

SaveGroups replaces all groups in a single transaction.

func (*StateDB) SaveInstance 

func (s *StateDB) SaveInstance(inst *InstanceRow) error

SaveInstance inserts or replaces a single instance.

func (*StateDB) SaveInstances 

func (s *StateDB) SaveInstances(insts []*InstanceRow) error

SaveInstances inserts or replaces multiple instances in a single transaction. It also removes any rows from the database that are not in the provided list, ensuring deleted sessions don't reappear on reload.

func (*StateDB) SaveRecentSession added in v0.20.0 

func (s *StateDB) SaveRecentSession(row *RecentSessionRow) error

SaveRecentSession inserts or replaces a recent session entry, then prunes to 20.

func (*StateDB) SetAcknowledged 

func (s *StateDB) SetAcknowledged(id string, ack bool) error

SetAcknowledged sets or clears the acknowledged flag for an instance.

func (*StateDB) SetMeta 

func (s *StateDB) SetMeta(key, value string) error

SetMeta sets a key-value pair in the metadata table.

func (*StateDB) Touch 

func (s *StateDB) Touch() error

Touch updates a metadata timestamp that other instances can poll to detect changes.

func (*StateDB) UnregisterInstance 

func (s *StateDB) UnregisterInstance() error

UnregisterInstance removes this process from the heartbeat table.

func (*StateDB) UpdateInstanceField 

func (s *StateDB) UpdateInstanceField(id, field string, value any) error

UpdateInstanceField updates a single column for a given instance. field must be a valid column name (caller is responsible for safety).

func (*StateDB) WriteStatus 

func (s *StateDB) WriteStatus(id, status, tool string) error

WriteStatus updates the status and tool for an instance.

type StatusRow 

type StatusRow struct {
	Status       string
	Tool         string
	Acknowledged bool
}

StatusRow holds status + acknowledgment for a session.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.