engine

func ListStates ¶

func ListStates() ([]*PromotionState, error)

ListStates reads every promotion state file under $XDG_STATE_HOME/hoist/promotions/, sorted by ID for a stable listing. A missing promotions directory is not an error: it returns (nil, nil), the same as "no promotions started yet". Reading it is purely informational — the caller (hoist resume, and the one-in-flight-per-env check at the start of hoist promote) still re-observes each promotion's steps against the remote before trusting anything about its current phase; this only recovers the set of IDs and the CloneDir/TargetEnv/Branch needed to rebuild each one's Steps and re-observe it (AGENTS.md §4.1 — Phase itself is never trusted).

func LoadState ¶

func LoadState(path string) (*PromotionState, error)

LoadState reads the state file at path. A missing file is not an error: it returns (nil, nil), since a state file is only ever a cache of History — Observe never needs it to determine truth (AGENTS.md invariant 4; see PromotionState's doc comment).

func AllDirectSteps ¶

func AllDirectSteps(g git.Git, a argo.Argo, ro rollout.Rollout, productionEnvs []string, confirmed bool, onWaiting func()) []Step

AllDirectSteps is DirectSteps plus the Argo/rollout convergence both modes share — the direct mirror of CoreSteps/AllSteps, and what `hoist promote --direct` and `hoist deploy --direct` actually drive. The split exists for the same reason the PR path's does: DirectSteps is the git-only core, useful on its own in tests that exercise the gate and the push without a cluster, while the exported pairing keeps a caller from silently driving a promotion that lands a commit and then never tells Argo about it (issue #66).

func AllSteps ¶

func AllSteps(g git.Git, f forge.Forge, a argo.Argo, ro rollout.Rollout, onWaiting func()) []Step

AllSteps returns every step a promotion drives through, in order: CoreSteps' seven (branch, commit, push, PR, CIGreen, Approved, Merged) then ArgoRefreshed, ArgoSynced and RolledOut (M5). `hoist promote` and `hoist resume` always drive AllSteps to completion.

func ConvergeSteps ¶

func ConvergeSteps(a argo.Argo, ro rollout.Rollout) []Step

ConvergeSteps is the post-landing tail both modes share: ask Argo to refresh, wait for it to agree with what landed, then watch the Deployments roll. Extracted so DirectSteps drives the identical three rather than a copy — the design has always said direct mode converges through Argo too ("Pushed -> ArgoRefreshed -> ..."), and it only ever stopped at the push because every step here used to gate on MergeSHA, which a direct push never produces (issue #66).

func CoreSteps ¶

func CoreSteps(g git.Git, f forge.Forge, onWaiting func()) []Step

CoreSteps returns the seven steps a promotion drives through up to and including the merge: Steps' four (branch, commit, push, PR) plus CIGreen, Approved and Merged. This is exactly the step list (and signature) `AllSteps` had before M5 — see steps_m4.go's own trailing comment — kept alive under a new name because M5 needed the name `AllSteps` for the ten-step list below. It exists for one caller: `findInFlight` in cmd/hoist/drive.go, which deliberately observes only through Merged when deciding whether a promotion still counts as "in flight" for AGENTS.md invariant 5 — see that function's own doc comment for the reasoning. `hoist promote` and `hoist resume` never call this directly; they always drive `AllSteps` to real completion.

func DirectSteps ¶

func DirectSteps(g git.Git, productionEnvs []string, confirmed bool, onWaiting func()) []Step

DirectSteps returns the steps a direct-mode promotion drives: the production/confirmation gate, then the same branch-and-commit steps the PR flow uses (BranchedStep, CommittedStep — unmodified), then DirectPushedStep in place of PushedStep+PROpenedStep.

productionEnvs MUST be RepoConfig.Envs.Production passed through exactly as loaded, never filtered, narrowed, or recomputed by the caller — DirectCommitGateStep's whole guarantee rests on this list actually being the one config authority that also governs PR-required and approval-required elsewhere (AGENTS.md §4.5); a caller that "helpfully" pre-filters it (e.g. "only pass the envs relevant to this repo") reintroduces exactly the config-bug risk invariant 6 asks to be structurally impossible. confirmed must be true only in direct response to the operator's own keypress + huh.Confirm gesture (internal/app/tags) or, at the CLI, its documented equivalent (cmd/hoist) — never a default, never inferred from anything else in the promotion.

func ObserveSteps ¶

func ObserveSteps(s *PromotionState, g git.Git, f forge.Forge, a argo.Argo, ro rollout.Rollout, onWaiting func()) []Step

ObserveSteps is the step list to observe a PRIOR promotion state by, chosen from the state itself rather than from what the caller happens to be doing now. Three callers ask the same question of a state file they did not create — findInFlight ("is another promotion still running for this env?"), `hoist promotions` and `resume --env`'s candidate scan — and all three used a fixed list, which for a direct state is a list it can never satisfy: a direct promotion pushes to the base branch, so PushedStep's branch on origin, PROpenedStep's PR and MergedStep's merge are all permanently unsatisfied. The consequence was not cosmetic: one completed direct run made findInFlight refuse every later promotion into that env forever, and left the finished run listed as in flight.

DirectCommitGateStep is deliberately NOT among the direct list here. The gate decides whether a direct promotion may START; re-running it while observing one that already landed would let a later config edit (an env newly listed under envs.production) turn a finished run into a permanently blocked one — a state file re-interpreted by today's config rather than observed. Refusing a new direct promotion is the gate's job, and it still runs first in DirectSteps where that decision is actually made (AGENTS.md §4.5, R-007).

through is where to stop: pass nil for the git-only core (findInFlight's own "the branch/PR collision risk is retired" boundary — see its doc comment), or a non-nil argo/rollout pair for the full list. The PR path's boundary is Merged; the direct path's is the push.

func Steps ¶

func Steps(g git.Git, f forge.Forge, onWaiting func()) []Step

Steps returns the four steps, in order, wired to g and f.

func ObserveAll ¶

func ObserveAll(ctx context.Context, steps []Step, s *PromotionState) (done bool, last StepStatus, err error)

ObserveAll re-derives every step's Observation in order, stopping at the first that is not cleanly Satisfied (Waiting or Blocked included) — the read-only half of what Drive does, without ever calling Act. done reports whether every step was Satisfied; last is the stopping point's own status (or the final step's, when done). A promotion is "in flight" exactly when done is false: still has real work ahead of it, is waiting on something external, or is blocked and needs operator attention — any of which means a second promotion for the same target env must not start (AGENTS.md §4.1: re-observe, never trust the state file's own Phase, for this question too).

The last step is checked first, as a short-circuit: MergedStep's own Observe (merged AND its branch deleted) is self-contained proof the whole promotion finished, and is deliberately the only step whose Act *removes* something an earlier step's Observe depends on for its own Satisfied condition (PushedStep's Observe requires the branch to still exist on origin — true throughout the promotion, false forever after MergedStep's cleanup runs). Without this short-circuit, ObserveAll would report a fully completed, cleaned-up promotion as stuck at Pushed — wrong, and exactly backwards from what a one-in-flight-per-env check needs: it would make a *finished* promotion block every future one for the same env, forever. ObserveAll never calls Act, so its short-circuit probes the *last* step. Drive does call Act, and for a while (pre-M5) that meant it never needed a short-circuit of its own: Merged was always the last step, so Drive simply finished the moment Merged was satisfied and was never called again. M5 added steps after Merged, so a promotion now sits waiting there across many further Drive calls — each of which, without its own short-circuit, would re-hit exactly the problem this paragraph describes for ObserveAll, except with Act: PushedStep re-pushing the branch Merged just deleted, then MergedStep deleting it again, every poll tick. Drive now carries the same probe, aimed one step earlier (at Merged rather than the last step, since Merged's own Observe is the self-contained proof either way) — see Drive's own doc comment.

func Status ¶

func Status(ctx context.Context, steps []Step, s *PromotionState) (done bool, statuses []StepStatus, err error)

Status is ObserveAll's sibling for a caller that needs to render every step's own standing, not only the stopping point: the internal/app/flight screen's step list (glyph per step, detail on whichever one is active) needs a StepStatus for each step already passed as well as the one it stopped at, which ObserveAll's single "last" return cannot carry. Status shares ObserveAll's two rules verbatim — the final-step short-circuit (see ObserveAll's doc comment: MergedStep's own Observe is self-contained proof the whole promotion finished, since PushedStep's Observe would otherwise falsely read as stuck once Merged's own Act has deleted the branch it depends on) and the stopping rule (the first step that is not cleanly Satisfied ends the walk) — only the shape of what is returned differs: statuses accumulates one entry per step actually observed, in order, rather than discarding every entry but the last.

When the short-circuit fires, statuses is the single-element slice {final step's own StepStatus} — deliberately not one entry per step, since re-observing every earlier step individually is exactly what the short-circuit exists to avoid (an already-merged, already-cleaned-up promotion would read PushedStep's Observe as false: the branch it checks is gone). A caller rendering a fully done list (done == true) should treat every step as done regardless of how many entries statuses carries, using the final entry only for its Detail — see flight.DeriveRows.

Otherwise, statuses holds exactly the steps Status reached: every entry before the last is Satisfied (the walk only continues past a step that cleanly is), and the last entry is the one Status stopped at — Blocked, Waiting, or plainly not yet Satisfied. A step whose name never appears in statuses has not been reached at all this call. The short-circuit probe above already called Observe once on the final step before the walk started (needed to even know whether to short-circuit); when the walk isn't short-circuited it reaches that same final step again in its own turn, but reuses the probe's Observation there rather than calling Observe a second time — every poll that isn't yet fully done would otherwise cost one extra, wasted remote call on the final step, every tick of the flight screen's own poll loop (PR #39 review finding #3). Both of Status's own Observe errors are returned as *StepError (Op: "observe"), not a bare fmt.Errorf, even though nothing here ever calls Act: internal/app/flight.Model's retry classifier (retryableErr, mirroring cmd/hoist/drive.go's own driveToCompletion) only retries automatically on a *StepError naming StepCIGreen or StepApproved — the two steps whose Observe alone can transiently 404/scope-error on a Checks or Comments call without the underlying condition (CI status, an approval) actually being answerable yet. A bare wrapped error carries the same message (StepError.Error()'s "<step>: <op>: <err>" format matches this function's own pre-existing "%s: observe: %w" text exactly, and Unwrap still reaches oerr, so errors.Is/the message text are both unchanged) but cannot be told apart by errors.As, which is all that classifier can use. Before this, a transient hiccup on the immediately-following Status call — after engine.Drive had itself already observed the very same step successfully as Waiting or Blocked, in cmd/hoist/wiring.go's own DriveFunc — surfaced as a plain error the flight screen read as terminal and stopped polling on for good, unlike the CLI's own driveToCompletion, which retries the identical shape of failure when Drive's own Observe hits it directly (Codex review, PR #50 round 4).