Documentation
¶
Overview ¶
Package workflow holds the orchestration logic for spec pipeline transitions — advance, revert, eject, resume. It mutates the spec file on disk, runs transition effects, and records activity, returning structured results. It performs no terminal I/O: callers (the CLI and the TUI) decide how to render outcomes. This keeps cmd/ thin and makes the state machine unit-testable against adapter fakes.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrGatesNotMet = errors.New("gate conditions not met")
ErrGatesNotMet is returned by Advance when the target stage's gate conditions fail. The returned AdvanceResult carries the specific failures so callers can render them.
Functions ¶
This section is empty.
Types ¶
type AdvanceInput ¶
type AdvanceInput struct {
SpecID string
SpecPath string // resolved spec file inside the repo clone
SpecDir string // the specs/ directory inside the repo clone
TargetStage string // "" advances to the immediate next stage
DryRun bool
}
AdvanceInput describes a requested advance.
type AdvanceResult ¶
type AdvanceResult struct {
SpecID string `json:"spec_id"`
PreviousStage string `json:"previous_stage"`
NewStage string `json:"new_stage"`
Skipped []string `json:"skipped,omitempty"`
DryRun bool `json:"dry_run,omitempty"`
Archived bool `json:"archived,omitempty"`
SyncedOut bool `json:"synced_out,omitempty"`
GateFailures []pipeline.GateResult `json:"gate_failures,omitempty"`
Effects []EffectOutcome `json:"effects,omitempty"`
// CommitMsg is the git commit message for the mutation, or "" when there
// is nothing to commit (dry-run or gate failure).
CommitMsg string `json:"-"`
}
AdvanceResult is the render-ready outcome of an advance.
func Advance ¶
func Advance(ctx context.Context, d Deps, in AdvanceInput) (*AdvanceResult, error)
Advance validates and moves a spec to the next (or target) stage, evaluates gates, and runs transition effects. On gate failure it returns the populated result and ErrGatesNotMet without mutating the spec.
type Deps ¶
type Deps struct {
Config *config.ResolvedConfig
Registry *adapter.Registry
DB *store.DB
Role string
}
Deps carries the collaborators a workflow operation needs. DB may be nil; activity logging and DB-backed effects degrade to no-ops in that case.
type EffectOutcome ¶
type EffectOutcome struct {
Message string `json:"message,omitempty"`
Skipped bool `json:"skipped,omitempty"`
Err string `json:"error,omitempty"`
}
EffectOutcome is a render-ready summary of one executed (or previewed) transition effect. It mirrors effects.Result without exposing the executor.
type EjectInput ¶
EjectInput describes a request to block (eject) a spec.
type EjectResult ¶
type EjectResult struct {
SpecID string `json:"spec_id"`
PreviousStage string `json:"previous_stage"`
Reason string `json:"reason"`
CommitMsg string `json:"-"`
}
EjectResult is the render-ready outcome of an eject.
func Eject ¶
func Eject(ctx context.Context, d Deps, in EjectInput) (*EjectResult, error)
Eject transitions a spec to blocked status, records a blocker, notifies the team (best-effort), and logs activity. Returns an error if already blocked.
type ResumeInput ¶
type ResumeInput struct {
SpecID string
SpecPath string
ResumeStage string // explicit target; "" means detect from escape-hatch log
}
ResumeInput describes a request to unblock a spec.
type ResumeResult ¶
type ResumeResult struct {
SpecID string `json:"spec_id"`
ResumeStage string `json:"resume_stage"`
CommitMsg string `json:"-"`
}
ResumeResult is the render-ready outcome of a resume.
func Resume ¶
func Resume(ctx context.Context, d Deps, in ResumeInput) (*ResumeResult, error)
Resume returns a blocked spec to a prior stage. When ResumeStage is empty the caller is expected to have detected the pre-block stage; an empty stage here is an error.
type RevertInput ¶
type RevertInput struct {
SpecID string
SpecPath string
SpecDir string
TargetStage string
Reason string
}
RevertInput describes a requested reversion.
type RevertResult ¶
type RevertResult struct {
SpecID string `json:"spec_id"`
PreviousStage string `json:"previous_stage"`
TargetStage string `json:"target_stage"`
Reason string `json:"reason"`
Effects []EffectOutcome `json:"effects,omitempty"`
CommitMsg string `json:"-"`
}
RevertResult is the render-ready outcome of a reversion.
func Revert ¶
func Revert(ctx context.Context, d Deps, in RevertInput) (*RevertResult, error)
Revert sends a spec back to an earlier stage with a reason, runs revert/enter effects, and records activity.
Source Files