serve

package
v0.3.35 Latest Latest
Warning

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

 Go to latest Published: Jun 25, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package serve exposes read-only questmaster runtime snapshots over a local transport. It is a presentation layer over the existing quest, runtime, and tracker readers; it never owns orchestration state.

Index

Constants

View Source 
const (
	ServeProtocolVersion = 1
)

Variables

This section is empty.

Functions

func DefaultSocketPath 

func DefaultSocketPath() string

DefaultSocketPath returns the default local socket path for qm serve.

Types

type BoardGroup 

type BoardGroup struct {
	Repo   string       `json:"repo"`
	Quests []BoardQuest `json:"quests"`
}

BoardGroup is one repo/project section on the board.

type BoardQuest 

type BoardQuest struct {
	Quest   quest.Quest          `json:"quest"`
	Runtime QuestRuntimeSnapshot `json:"runtime"`
}

BoardQuest pairs the authored quest JSON with its derived runtime.

type BoardSnapshot 

type BoardSnapshot struct {
	ObservedAt time.Time    `json:"observed_at"`
	Groups     []BoardGroup `json:"groups"`
}

BoardSnapshot is the native quest board's read model.

type Change 

type Change struct {
	Topics     []string
	QuestIDs   []string
	SessionIDs []string
	Clock      bool
}

Change is a topic-level invalidation produced by serve's file watcher or by the serve-side clock for elapsed/runtime fields. It names the smallest existing wire surfaces that need to be re-snapshotted; the payload shape remains the existing topic response.

func (Change) Affects 

func (c Change) Affects(topic, subscribedQuestID string) bool

Affects reports whether the change should wake a subscriber for topic.

type ChangeSource 

type ChangeSource interface {
	Subscribe(context.Context) (<-chan Change, func())
	Close() error
}

ChangeSource publishes file-watch and clock invalidations to subscribers.

type CurrentSession 

type CurrentSession struct {
	ID          string `json:"id"`
	Title       string `json:"title,omitempty"`
	SessionType string `json:"session_type,omitempty"`
}

CurrentSession identifies the session the current process is attached to, when QUESTMASTER_SESSION gives serve that context.

type Envelope 

type Envelope struct {
	ProtocolVersion int             `json:"protocol_version"`
	Type            string          `json:"type"`
	ID              json.RawMessage `json:"id,omitempty"`
	OK              *bool           `json:"ok,omitempty"`
	Topic           string          `json:"topic,omitempty"`
	Data            any             `json:"data,omitempty"`
	Error           string          `json:"error,omitempty"`
}

Envelope is one JSON line sent by serve.

type FileChangeSource 

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

FileChangeSource watches the durable qm files that feed serve's read models. It does not own state; it only turns filesystem events into topic invalidations.

func NewFileChangeSource 

func NewFileChangeSource(ctx context.Context, snapshotter *Snapshotter, clockInterval time.Duration) (*FileChangeSource, error)

NewFileChangeSource creates and starts the serve file watcher. clockInterval drives only elapsed/runtime clock fields; state changes are watcher-driven.

func (*FileChangeSource) Close 

func (s *FileChangeSource) Close() error

func (*FileChangeSource) Subscribe 

func (s *FileChangeSource) Subscribe(ctx context.Context) (<-chan Change, func())

type MutationCommandRunner 

type MutationCommandRunner interface {
	RunMutationCommand(context.Context, []string, []byte) ([]byte, error)
}

MutationCommandRunner runs a qm command for serve mutations that belong to the CLI/session lifecycle path.

type QuestRuntimeSnapshot 

type QuestRuntimeSnapshot struct {
	Sessions       []string               `json:"sessions"`
	SessionDetails []QuestSessionSnapshot `json:"session_details,omitempty"`
	Adventurers    []QuestSessionSnapshot `json:"adventurers,omitempty"`
	Agent          string                 `json:"agent"`
	Gates          map[string]string      `json:"gates,omitempty"`
	GatesAt        map[string]time.Time   `json:"gates_at,omitempty"`
	ObservedAt     time.Time              `json:"observed_at"`
	Loop           *quest.LoopRuntime     `json:"loop,omitempty"`
}

QuestRuntimeSnapshot is the serve-facing runtime shape. The core quest package still exposes the legacy Adventurers field; serve keeps that field for compatibility and also exposes the same rows under the canonical session_details name.

type QuestSessionSnapshot 

type QuestSessionSnapshot struct {
	ID    string             `json:"id"`
	Agent string             `json:"agent,omitempty"`
	State string             `json:"state,omitempty"`
	Since time.Time          `json:"since,omitempty"`
	Loop  *quest.LoopRuntime `json:"loop,omitempty"`
}

QuestSessionSnapshot is one attached session's live quest activity.

type QuestSnapshot 

type QuestSnapshot struct {
	Quest      *quest.Quest         `json:"quest"`
	Runtime    QuestRuntimeSnapshot `json:"runtime"`
	ObservedAt time.Time            `json:"observed_at"`
}

QuestSnapshot is the native quest viewer's read model.

type RepoSnapshot 

type RepoSnapshot struct {
	Identity string `json:"identity,omitempty"`
	Name     string `json:"name,omitempty"`
	Color    string `json:"color,omitempty"`
}

RepoSnapshot carries tracker repo grouping metadata.

type Request 

type Request struct {
	ID      json.RawMessage `json:"id,omitempty"`
	Method  string          `json:"method"`
	Topics  []string        `json:"topics,omitempty"`
	QuestID string          `json:"quest_id,omitempty"`
	Data    json.RawMessage `json:"data,omitempty"`
}

Request is one JSON line sent by a client.

type Server 

type Server struct {
	SocketPath    string
	Snapshotter   *Snapshotter
	ClockInterval time.Duration

	// Interval is kept as a deprecated alias for ClockInterval so older tests
	// and scripts do not silently switch cadence.
	Interval time.Duration

	ChangeSource ChangeSource

	// MutationRunner is injectable for tests; production re-execs this binary
	// for CLI-owned session lifecycle mutations.
	MutationRunner MutationCommandRunner
	TmuxClient     *tmux.Client
	DirQuerier     dirsuggest.DirQuerier
}

Server serves read-only snapshots over a Unix domain socket.

func (*Server) Serve 

func (s *Server) Serve(ctx context.Context) error

Serve starts the local socket server and runs until ctx is canceled.

type SessionSnapshot 

type SessionSnapshot struct {
	ID             string             `json:"id"`
	Title          string             `json:"title,omitempty"`
	Status         string             `json:"status"`
	State          string             `json:"state,omitempty"`
	ElapsedMS      int64              `json:"elapsed_ms"`
	ElapsedSince   *time.Time         `json:"elapsed_since,omitempty"`
	LatestActivity string             `json:"latest_activity,omitempty"`
	LastKind       string             `json:"last_kind,omitempty"`
	WorktreePath   string             `json:"worktree_path,omitempty"`
	PrimaryAgent   string             `json:"primary_agent,omitempty"`
	SessionType    string             `json:"session_type,omitempty"`
	ParentID       string             `json:"parent_id,omitempty"`
	WorkerCount    int                `json:"worker_count"`
	IsCurrent      bool               `json:"is_current"`
	QuestID        string             `json:"quest_id,omitempty"`
	QuestTitle     string             `json:"quest_title,omitempty"`
	QuestLoop      *quest.LoopRuntime `json:"quest_loop,omitempty"`
	Repo           RepoSnapshot       `json:"repo,omitempty"`
	DisplayColor   string             `json:"display_color,omitempty"`
}

SessionSnapshot is one tracker row with live activity already applied.

type Snapshotter 

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

Snapshotter builds the read-only data surfaces served to clients.

func NewSnapshotter 

func NewSnapshotter(store *state.Store, tmuxClient *tmux.Client, now func() time.Time) *Snapshotter

NewSnapshotter creates a snapshot reader from existing qm services.

func (*Snapshotter) Board 

func (s *Snapshotter) Board(context.Context) (BoardSnapshot, error)

Board returns quests grouped in the same project order as the TUI board, with runtime injected from the shared runtime derivation.

func (*Snapshotter) BoardForChange 

func (s *Snapshotter) BoardForChange(change Change) (BoardSnapshot, error)

func (*Snapshotter) Invalidate 

func (s *Snapshotter) Invalidate(change Change)

func (*Snapshotter) Quest 

func (s *Snapshotter) Quest(_ context.Context, id string) (QuestSnapshot, error)

Quest returns one authored quest JSON document plus its live runtime.

func (*Snapshotter) QuestDir 

func (s *Snapshotter) QuestDir() string

QuestDir returns the durable quest JSON/HTML store read by serve.

func (*Snapshotter) QuestForChange 

func (s *Snapshotter) QuestForChange(id string, change Change) (QuestSnapshot, error)

func (*Snapshotter) RuntimeDir 

func (s *Snapshotter) RuntimeDir() string

RuntimeDir returns the durable auto-gate sidecar directory read by serve.

func (*Snapshotter) SessionQuestID 

func (s *Snapshotter) SessionQuestID(sessionID string) string

SessionQuestID returns the quest currently stamped on a session, if any.

func (*Snapshotter) SessionQuestIndex 

func (s *Snapshotter) SessionQuestIndex() map[string]string

SessionQuestIndex returns the current session->quest attachment map. It is used only to classify future file events, especially deletes and detaches.

func (*Snapshotter) StateRoot 

func (s *Snapshotter) StateRoot() string

StateRoot returns the durable session-state root read by serve.

func (*Snapshotter) Tracker 

func (s *Snapshotter) Tracker(context.Context) (TrackerSnapshot, error)

Tracker returns the tracker row model with hook-driven activity applied.

func (*Snapshotter) TrackerForChange 

func (s *Snapshotter) TrackerForChange(change Change) (TrackerSnapshot, error)

type TrackerSnapshot 

type TrackerSnapshot struct {
	ObservedAt time.Time         `json:"observed_at"`
	Current    *CurrentSession   `json:"current,omitempty"`
	Sessions   []SessionSnapshot `json:"sessions"`
}

TrackerSnapshot is the native tracker's read model.

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.