Archie owns the status and action vocabulary in internal/taskstate, but the
dashboard had to keep a hand-synced copy of the display labels, pill severities
and action confirm prompts -- so a new status or action silently rendered
wrong until someone edited the frontend.
- add taskstate.Statuses() and taskstate.ActionCatalog() so the rules and their
presentation live in one place
- expose GET /api/task-meta returning {statuses, actions}
- add a client base/task-meta.js that fetches the catalog and exposes
statusLabel/statusKind/statusIds/attentionStatusIds/actionFor, with a
freeze-dried default snapshot so the dashboard renders instantly and keeps
working when archied is unreachable
- tests for the catalog, the endpoint and the client accessors
197 lines
7.6 KiB
Go
197 lines
7.6 KiB
Go
// Package taskstate owns the task lifecycle vocabulary and the rules for
|
|
// operator-initiated actions on a task.
|
|
//
|
|
// It exists because those rules had two implementations. The dashboard and
|
|
// chat both offer approve and reject, and they had drifted: rejecting from
|
|
// the dashboard left a task ClosedWontDo, cancelling the same task from chat
|
|
// left it Rejected. Two operators looking at the same queue saw different
|
|
// states for the same decision, and Rejected -- which the PR reconciler uses
|
|
// for "the pull request was closed without merging" -- no longer meant one
|
|
// thing.
|
|
//
|
|
// internal/gateway deliberately does not import internal/store, so it kept a
|
|
// hand-synced copy of the status strings with a comment asking future editors
|
|
// to keep them aligned. That is the same defect one level down. This package
|
|
// has no dependencies, so both can import it and the copy can go.
|
|
package taskstate
|
|
|
|
import (
|
|
"fmt"
|
|
"slices"
|
|
)
|
|
|
|
// Action is an operator control whose availability is determined solely by a
|
|
// task's persisted lifecycle state. The Web API returns these values with each
|
|
// task so every presentation surface derives from this table instead of
|
|
// keeping its own copy.
|
|
type Action string
|
|
|
|
const (
|
|
ActionCancel Action = "cancel"
|
|
ActionStop Action = "stop"
|
|
ActionApprove Action = "approve"
|
|
ActionReject Action = "reject"
|
|
ActionRetry Action = "retry"
|
|
ActionAbandon Action = "abandon"
|
|
ActionOpenPR Action = "open_pr"
|
|
ActionOpenIssue Action = "open_issue"
|
|
ActionArchive Action = "archive"
|
|
)
|
|
|
|
// Task lifecycle statuses. The store persists these strings, so they are
|
|
// part of the on-disk format: renaming one is a migration, not a rename.
|
|
const (
|
|
Queued = "queued"
|
|
Running = "running"
|
|
WaitingHuman = "waiting_human"
|
|
PROpen = "pr_open"
|
|
Merged = "merged"
|
|
Parked = "parked"
|
|
Dead = "dead"
|
|
|
|
// Rejected means the forge closed the pull request without merging it.
|
|
// It is an outcome archie observed, not a decision an operator made --
|
|
// use Declined for that.
|
|
Rejected = "rejected"
|
|
|
|
// Declined means an operator refused the work. Whether they said so from
|
|
// the dashboard or from chat, the task lands here.
|
|
Declined = "closed_wont_do"
|
|
)
|
|
|
|
// Terminal reports whether a status is an end state, from which no further
|
|
// work happens without an operator asking for it.
|
|
func Terminal(status string) bool {
|
|
switch status {
|
|
case Merged, Rejected, Dead, Declined:
|
|
return true
|
|
default:
|
|
return false
|
|
}
|
|
}
|
|
|
|
// Actions returns the ordered controls valid for status. Callers receive a
|
|
// fresh slice so presentation code cannot mutate the lifecycle table.
|
|
//
|
|
// Reject is deliberately present in every non-terminal state: an operator can
|
|
// refuse work no matter where it currently sits, and the refusal always lands
|
|
// in the terminal Declined state. Terminal states are already resolved, so
|
|
// they only expose archive.
|
|
func Actions(status string) []Action {
|
|
var actions []Action
|
|
switch status {
|
|
case Queued:
|
|
actions = []Action{ActionCancel, ActionReject}
|
|
case Running:
|
|
actions = []Action{ActionStop, ActionReject}
|
|
case WaitingHuman:
|
|
actions = []Action{ActionApprove, ActionReject}
|
|
case Parked:
|
|
actions = []Action{ActionRetry, ActionAbandon, ActionReject}
|
|
case PROpen:
|
|
actions = []Action{ActionOpenPR, ActionOpenIssue, ActionReject}
|
|
case Merged, Rejected, Dead, Declined:
|
|
actions = []Action{ActionArchive}
|
|
}
|
|
return actions
|
|
}
|
|
|
|
// CheckAction rejects stale, illegal and unknown operator controls.
|
|
func CheckAction(status string, action Action) error {
|
|
if slices.Contains(Actions(status), action) {
|
|
return nil
|
|
}
|
|
return fmt.Errorf("action %q is not available while task is %s", action, status)
|
|
}
|
|
|
|
// CheckApprove reports whether a task in this status can be approved.
|
|
//
|
|
// Approval releases work that is waiting on a human decision, so it is only
|
|
// meaningful from WaitingHuman. Approving anything else would either restart
|
|
// finished work or race a task that is already running.
|
|
func CheckApprove(status string) error {
|
|
if status != WaitingHuman {
|
|
return fmt.Errorf("task is %s, not awaiting approval", status)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// CheckRetry reports whether a task in this status can be retried.
|
|
//
|
|
// Only a parked task can be retried: parking is how archie says "this failed
|
|
// in a way a human might fix". A dead task has spent its retries and needs
|
|
// the cap raised or the work re-filed, not another attempt.
|
|
func CheckRetry(status string) error {
|
|
if status != Parked {
|
|
return fmt.Errorf("task is %s, not parked", status)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// CheckDecline reports whether a task in this status can be declined.
|
|
//
|
|
// The legacy chat command expresses cancel, stop, reject and abandon as one
|
|
// operation. Because Reject is now offered in every non-terminal state, that
|
|
// command is available everywhere a task is still live; unknown and terminal
|
|
// states fail closed instead of permitting an arbitrary transition.
|
|
func CheckDecline(status string) error {
|
|
for _, action := range Actions(status) {
|
|
switch action {
|
|
case ActionCancel, ActionStop, ActionReject, ActionAbandon:
|
|
return nil
|
|
}
|
|
}
|
|
return fmt.Errorf("task cannot be declined while %s", status)
|
|
}
|
|
|
|
// StatusMeta describes how to present a lifecycle status. It is the single
|
|
// source for the dashboard's label, pill severity and "needs you" grouping, so
|
|
// the frontend never has to keep a hand-synced copy of the vocabulary.
|
|
type StatusMeta struct {
|
|
ID string `json:"id"`
|
|
Label string `json:"label"`
|
|
Kind string `json:"kind"` // pill severity: idle, info, ok, warn, danger
|
|
NeedsYou bool `json:"needs_you"` // counts toward the "Needs you" filter
|
|
}
|
|
|
|
// ActionMeta describes how to present an operator control. Confirmation text
|
|
// uses "{title}" as a placeholder for the task title.
|
|
type ActionMeta struct {
|
|
ID string `json:"id"`
|
|
Label string `json:"label"`
|
|
Kind string `json:"kind"` // button variant: primary, quiet, danger, link
|
|
Confirm string `json:"confirm"` // optional confirm prompt, may be ""
|
|
}
|
|
|
|
// Statuses returns the presentation catalog for every lifecycle status, in
|
|
// display order. Callers receive a fresh slice.
|
|
func Statuses() []StatusMeta {
|
|
return []StatusMeta{
|
|
{ID: Queued, Label: "Queued", Kind: "idle"},
|
|
{ID: Running, Label: "Working", Kind: "info"},
|
|
{ID: WaitingHuman, Label: "Waiting for you", Kind: "warn", NeedsYou: true},
|
|
{ID: PROpen, Label: "In review", Kind: "ok"},
|
|
{ID: Merged, Label: "Merged", Kind: "ok"},
|
|
{ID: Parked, Label: "Parked", Kind: "warn", NeedsYou: true},
|
|
{ID: Dead, Label: "Stopped (too many retries)", Kind: "danger"},
|
|
{ID: Rejected, Label: "Rejected", Kind: "danger"},
|
|
{ID: Declined, Label: "Won't do", Kind: "idle"},
|
|
}
|
|
}
|
|
|
|
// ActionCatalog returns the presentation catalog for every operator control.
|
|
// Callers receive a fresh slice.
|
|
func ActionCatalog() []ActionMeta {
|
|
return []ActionMeta{
|
|
{ID: string(ActionCancel), Label: "Cancel", Kind: "quiet", Confirm: `Cancel "{title}"? This closes the forge issue.`},
|
|
{ID: string(ActionStop), Label: "Stop", Kind: "primary", Confirm: `Stop "{title}"? Recoverable work will remain parked.`},
|
|
{ID: string(ActionApprove), Label: "Approve", Kind: "primary"},
|
|
{ID: string(ActionReject), Label: "Reject", Kind: "quiet", Confirm: `Reject "{title}"? This closes the forge issue.`},
|
|
{ID: string(ActionRetry), Label: "Retry", Kind: "primary"},
|
|
{ID: string(ActionAbandon), Label: "Abandon", Kind: "quiet", Confirm: `Abandon "{title}"? This closes the forge issue.`},
|
|
{ID: string(ActionArchive), Label: "Archive", Kind: "quiet", Confirm: `Archive the local record for "{title}"?`},
|
|
{ID: string(ActionOpenPR), Label: "Open PR", Kind: "link"},
|
|
{ID: string(ActionOpenIssue), Label: "Open issue", Kind: "link"},
|
|
}
|
|
}
|