Documentation
¶
Overview ¶
Package state owns the run state: one small `key value` file per session under ~/.claude/f10/state, keyed by session rather than by repo because two sessions over one checkout are two runs.
This package is the only writer (`f10 state`, `f10 hook`) and holds the rules. The status line's renderer, `bin/f10-state.sh render`, is the other reader: it runs on every refresh, so it stays bash and reads the same format with the same tolerances - unknown keys ignored, a non-numeric timestamp read as stale. The render parity test pins that.
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) 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) 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: the point past which the badge stops rendering.
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 in dir is about: a run file's root, a prompt mark's, or for an open wait 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 is the list of what a session launched, beside its state file, 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 Path ¶
Path is the state file for a session: the id sanitized, since it names a file, the way the renderer sanitizes it.
func PromptedPath ¶ added in v0.46.0
PromptedPath is the mark a session's last prompt leaves beside its state file: which checkout it was typed in and when. A drive reads it to 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: run state, the conventions marker f10-inject.sh writes, the session start mark, and the session's launches.
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 session this process runs in: the explicit override, then 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 is the mark a session's start leaves beside its state file: 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
Updated time.Time `json:"updated"`
}
A Run is one session's state file, read back. Every phase holds one of the Statuses: pending, running, done, failed, partial, skipped, prior, blocked.
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, for the most-dropped call: the final `set ship done` after the PR and report. Stop states are left alone. Single-turn capture and plan promote; ship spans many turns, so it promotes only on the declared final step, or when no final or leaf is known (overstating is the cheaper error). It reports whether anything changed.
func (*Run) PhaseText ¶
PhaseText is the status with its step attached where one is known and belongs to that status: `running: implement`, `blocked at judge`. The leaf is a pipeline step, so only ship carries one, but for the judge fetch runs on a stale task before plan.
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 in the format the status line's bash renderer reads, key for key, through a temp file so the polling renderer never sees a torn file. Every value is flattened to one line: a newline would start a new key.
func (*Run) Seed ¶ added in v0.36.0
Seed begins a run for a skill invocation and resets the phases, except a chain over one task (plan, then ship) whose argument names the task already held: that carries settled phases forward, or ship would show this session's plan as `skipped`. It reports false for --help, which runs nothing, so the badge keeps the last real run.
func (*Run) Set ¶ added in v0.36.0
Set records a phase's status. A stop state keeps the leaf (the argument, else the last running one): "blocked at judge" is the answer to "ship blocked". A phase running again retires the old note and question.
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) 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.
type UsageError ¶ added in v0.36.0
type UsageError struct {
// contains filtered or unexported fields
}
A UsageError is a malformed call: an unknown phase or status, a missing argument. It is a typo in step prose, so the command exits 2 rather than leave the badge frozen without a word.
func (*UsageError) Error ¶ added in v0.36.0
func (e *UsageError) Error() string
Source Files