Documentation
¶
Overview ¶
Package planfile is the plan file (§6.4): the mirror of a plan the engine keeps in the repo, as .brigada/plans/<plan-id>.yaml on a branch of the project's remote. The file holds the graph, the task states, the branches and the open questions — never transcripts. The store is authoritative; the file is a mirror that may lag, and it exists so a lost store can be rebuilt from the repo (`brigada recover`).
The YAML is hand-rolled in one fixed layout, with no dependency: the shape is ours, the writer is the reader's inverse, and Parse refuses anything the writer would not have written (full-line comments and blank lines aside).
Index ¶
Constants ¶
const Dir = ".brigada/plans"
Dir is where plan files live in the repo.
Variables ¶
var ErrNoDefaultBranch = errors.New("the remote has no default branch yet")
ErrNoDefaultBranch is the push that committed to the default branch of a remote that has none yet.
Functions ¶
func Describe ¶
Describe says what changed from the file the remote holds to the one about to replace it, in a phrase for the commit message: "created", "state active -> done", "task build running -> reviewing". old is nil for a first push; a change in no state or branch (rounds, a question) reads "updated".
func Push ¶
Push puts the plan's file on the target branch: it fetches the branch into a scratch repository (the engine's own environment, §5: no assumption about the host beyond git and the remote's credentials), writes the file, commits it with a stable identity and a message naming the plan and what changed, and pushes. A file already identical on the branch is not committed again. Any failure is the caller's to log: the mirror is best-effort, and the next change pushes again.
The scratch repository names the project URL as its remote "origin" and talks to that name, never to the bare URL: git config scoped by remote URL (includeIf "hasconfig:remote.*.url:...") and the hooks, credential helpers and other settings set through it then apply here as they do in a clone.
Types ¶
type ExtraRepo ¶
ExtraRepo is one extra repository of a task (§5.8): its name, canonical repository identity and ref (” = the default branch).
type Fetched ¶
Fetched is what Fetch read from a plans branch: the plans whose files parsed, and a line for each file that did not — recover rebuilds what it can and says what it could not.
func Fetch ¶
Fetch reads every plan file on the target branch, the reverse of Push: it fetches the branch into a scratch repository and parses each .brigada/plans/*.yaml with the strict reader. A remote without the branch holds no plans, which is not an error. A file whose name is not <id>.yaml for the id it holds is skipped, never trusted.
type Plan ¶
type Plan struct {
ID int64
Title string
Repo string // the project's repo URL
State string // the plan's state word: active, done, …
Created time.Time
Updated time.Time
Tasks []Task
}
Plan is one plan as the file shows it (§6.1, §6.2).
func Parse ¶
Parse reads a plan file back: the inverse of Render, strict. Full-line comments and blank lines may stand anywhere; every other line must be the one the layout expects next, or Parse names the line and stops. It is what recover reads plan files with (Fetch, §6.4), and what the mirror's commit message reads the file it is about to replace with.
type Target ¶
type Target struct {
URL string // the remote, as the project names it (product §5 rule 6)
Branch string
// Default marks Branch as the repo's default branch (§6.4's option):
// the file is committed there, and a remote without it is an error —
// the mirror never creates the default branch. Any other branch is
// created, as an orphan, when the remote lacks it.
Default bool
}
Target is where a plan file goes: a branch of the repo's remote.
type Task ¶
type Task struct {
Tier string // the foreman's tier; empty means standard
Effort string
// ReviewTier and ReviewEffort are the task's own tier and effort for its
// reviews (§7, §8); empty = the engine default.
ReviewTier string
ReviewEffort string
// Caps are the task's own round-cap overrides (§6.1), keyed
// fix_rounds, review_rounds and restart; nil = the engine defaults.
Caps map[string]int
ID int64
Name string // ” = unnamed
Title string
Class string
Deps []string
Base string // the dep whose branch the work starts from; ” = the default branch
Continue string // the dep whose author's session the first work job resumes (§6.1); ” = fresh
// Skills names the task's skills in the order it recorded them
// (§5.10); the file carries names alone, never texts.
Skills []string
State string
Branch string // the result branch (§6.4); ” until the task pushed one
Rounds int // fix and review rounds spent (§7)
Question string // the open question (§3), ” when there is none
// ExtraRepos are the read-only repositories the task was given (§5.8),
// as the task recorded them: the canonical identity, never a URL that
// could carry a credential.
ExtraRepos []ExtraRepo
}
Task is one task of a plan. Deps name tasks of the same plan, so only a named task can be depended on (§6.1); ID is the store's row id, kept so an unnamed task is still identifiable.
Source Files