Documentation
¶
Overview ¶
Package state owns the run state: one `key value` file per session, keyed by session rather than by repo because two sessions over one checkout are two runs. The status line's renderer, `bin/f10-state.sh render`, reads the same format in bash on every refresh; the render parity test pins the two.
Index ¶
- Constants
- Variables
- func AppendLaunch(dir, session string, l Launch) error
- func Clear(dir, session string)
- func Dir() string
- func FileRoot(dir, name string) string
- func Glyph(status string) string
- func LaunchesPath(dir, session string) string
- func MarkPrompt(dir, session, root string, at time.Time) error
- func Path(dir, session string) string
- func PromptedPath(dir, session string) string
- func Prune(dir string, now time.Time)
- func RootOf(cwd string) string
- func Session() string
- func SplitPipeline(s string) []string
- func StartedPath(dir, session string) string
- func Stopped(status string) bool
- func TTL() time.Duration
- func WaitPath(dir, session string) string
- type Launch
- type Prompt
- type Run
- func (r *Run) Backstop() bool
- func (r *Run) Live(now time.Time, ttl time.Duration) bool
- func (r *Run) PhaseText(phase string) string
- func (r *Run) PlanWritten(task string)
- func (r *Run) Save(dir string, now time.Time) error
- func (r *Run) Seed(skill, args, cwd string) bool
- func (r *Run) Set(phase, status, leaf string) error
- func (r *Run) SetAsk(text string) error
- func (r *Run) SetDone(step string, now time.Time) error
- func (r *Run) SetFinal(step string) error
- func (r *Run) SetNote(reason, next string) error
- func (r *Run) SetPipeline(steps []string) error
- func (r *Run) SetTask(id, url string) error
- func (r *Run) SetWait(task string) error
- func (r *Run) Show(w io.Writer, now time.Time)
- func (r *Run) Status(phase string) string
- type UsageError
Constants ¶
const ( LaunchStart = "start" LaunchDrive = "drive" )
Launch kinds: a task `f10 start` opened, or a drive by its number.
const DefaultTTL = 24 * time.Hour
DefaultTTL is how long a run counts as live with nothing reporting.
const PipelineSep = " → "
PipelineSep joins a recorded pipeline's steps, as `pipelines:` strings spell them: a step name may hold spaces (`review (local)`).
Variables ¶
var Phases = []string{"capture", "plan", "ship"}
Phases in the order the badge draws them.
var Statuses = []string{"pending", "running", "done", "failed", "partial", "skipped", "prior", "blocked"}
Statuses a phase can hold, in the order the usage text lists them.
Functions ¶
func AppendLaunch ¶ added in v0.46.0
AppendLaunch adds one launch to session's list. One short line in one append write, so two parallel starts in a session never tear a line.
func Clear ¶ added in v0.36.0
func Clear(dir, session string)
Clear drops a session's state file. Absent is fine.
func FileRoot ¶ added in v0.46.0
FileRoot is the checkout a per-session file is about, an open wait taking its session's; "" for any other file, or a session with neither.
func Glyph ¶ added in v0.36.0
Glyph is the status line's default shape for a status; the renderer's F10_STATE_GLYPHS override applies to the status line only.
func LaunchesPath ¶ added in v0.46.0
LaunchesPath lists what a session launched, so a bare status in the main checkout can show it.
func MarkPrompt ¶ added in v0.46.0
MarkPrompt writes session's mark. It never touches the run file, so a session f10 does not run leaves no run behind.
func PromptedPath ¶ added in v0.46.0
PromptedPath is the mark a session's last prompt leaves: which checkout and when, so a drive can tell a turn that ran between two looks from one never taken.
func Prune ¶ added in v0.36.0
Prune drops the per-session files of long-dead sessions; .conventions is the marker f10-inject.sh writes.
func RootOf ¶ added in v0.46.0
RootOf is the checkout root a cwd is in; outside git, the cwd itself.
func Session ¶
func Session() string
Session is the override, else the id Claude Code exports into every Bash tool call; empty from a plain terminal. A hook names its session in the payload instead.
func SplitPipeline ¶ added in v0.42.0
SplitPipeline reads a recorded pipeline back into its steps.
func StartedPath ¶ added in v0.36.0
StartedPath marks when the session loaded the plugin, for doctor to compare with the install's update time.
Types ¶
type Launch ¶ added in v0.46.0
type Launch struct {
Kind string
Value string // the task as typed for start, the drive's number for drive
}
A Launch is one thing a session set going: a start's task, or a drive.
type Prompt ¶ added in v0.46.0
A Prompt is one session's mark: the checkout root and the prompt's time.
func LastPrompt ¶ added in v0.46.0
LastPrompt is the newest mark any session left in root, false for none.
type Run ¶
type Run struct {
Session string `json:"session"`
Task string `json:"task,omitempty"`
URL string `json:"url,omitempty"`
Root string `json:"root,omitempty"` // checkout root the run is about
Skill string `json:"skill,omitempty"` // the skill that began the run
Capture string `json:"capture"`
Plan string `json:"plan"`
Ship string `json:"ship"`
Leaf string `json:"leaf,omitempty"` // the pipeline step running, or stopped on
// Leaf's place in Pipeline, counted from 1, so a step the pipeline
// names twice (`judge`, `pr`) is told apart; 0 is unknown
At int `json:"at,omitempty"`
Final string `json:"final,omitempty"` // the ship pipeline's declared last step
// the ship pipeline's steps as declared, in order
Pipeline []string `json:"pipeline,omitempty"`
Note string `json:"note,omitempty"` // why the run stopped
Next string `json:"next,omitempty"` // what unblocks it
Ask string `json:"ask,omitempty"` // the question a driven run stopped on, options included
// Wait is the base task a driven ship stopped for, its branch without
// code yet: a drive parks the task and sends ship again once it has some
Wait string `json:"wait,omitempty"`
// Done is the phaseless step (catchup) whose report is out, DoneAt when;
// a reader compares DoneAt, since any later write moves Updated alone
Done string `json:"done,omitempty"`
DoneAt time.Time `json:"done_at,omitzero"`
Updated time.Time `json:"updated"`
}
A Run is one session's state file, read back; each phase holds a Statuses.
func Fresh ¶ added in v0.36.0
Fresh is the run a session has before anything reported: every phase pending.
func List ¶
List reads every live run in dir, newest first. A missing directory is an empty list: no run has ever reported on this machine.
func Load ¶
Load reads one state file. A missing file is os.ErrNotExist, unwrapped enough for errors.Is.
func LoadOrFresh ¶ added in v0.36.0
LoadOrFresh reads the session's file, or starts a fresh run when there is none. The bool says whether a file was read.
func (*Run) Backstop ¶ added in v0.36.0
Backstop is the Stop hook's promotion of a running phase, for the most dropped call: the final `set ship done`. Ship spans many turns, so it promotes only on the declared final step, or with no final or leaf known, overstating being the cheaper error. True when anything changed.
func (*Run) PhaseText ¶
PhaseText is the status with its step where one belongs to it: `running: implement`, `blocked at judge`. The leaf is a pipeline step, so only ship carries one, except plan's judge, which fetch runs before planning.
func (*Run) PlanWritten ¶ added in v0.36.0
PlanWritten is the plan step's output landing: plan done, unreported, and the file's name is the task id.
func (*Run) Save ¶ added in v0.36.0
Save writes the run as the status line's bash renderer reads it, through a temp file so the polling renderer never sees a torn file; values are flattened to one line, since a newline would start a new key.
func (*Run) Seed ¶ added in v0.36.0
Seed begins a run for a skill invocation. A chain over the task already held (plan, then ship) carries settled phases forward, or ship would show this session's plan as `skipped`; --help runs nothing and reports false, so the badge keeps the last real run.
func (*Run) Set ¶ added in v0.36.0
Set records a phase's status. A stop keeps the leaf, the argument else the last running one, since "blocked at judge" is the answer to "ship blocked"; running again retires the note, question and done signal, which a stop keeps for the driven catchup that wrote it before restoring.
func (*Run) SetAsk ¶ added in v0.36.0
SetAsk records the questionnaire a driven run stopped on, options included: no one is in its pane to answer.
func (*Run) SetDone ¶ added in v0.47.0
SetDone records that a phaseless step (catchup) reported at now: the drive reads it as the step's end, and an idle agent without it stopped without reporting. It touches no phase, so the badge a ship run left stands.
func (*Run) SetFinal ¶ added in v0.36.0
SetFinal declares the ship pipeline's last step, for the Stop backstop: a turn ending on it is a dropped `set ship done`; mid-pipeline is a pause.
func (*Run) SetPipeline ¶ added in v0.42.0
SetPipeline declares the ship pipeline's steps, in order; its last is the final step.
func (*Run) SetTask ¶ added in v0.36.0
SetTask records the task the run is about. A tracker task id means the task predates this run, so an unreported capture becomes `prior`; `done` and `running` stay, since capture reports those itself.
func (*Run) SetWait ¶ added in v0.49.0
SetWait records the base task a driven ship stopped for, its branch without code yet. Not an ask: no one is asked, and a drive waits on it.
type UsageError ¶ added in v0.36.0
type UsageError struct {
// contains filtered or unexported fields
}
A UsageError is a typo in step prose (an unknown phase or status, a missing argument), so the command exits 2 rather than leave the badge frozen.
func (*UsageError) Error ¶ added in v0.36.0
func (e *UsageError) Error() string
Source Files