recipe

type Dir ¶

type Dir struct {
	Path   string
	Source string // "project" | "user" | "--dir"
}

Dir is one entry in the recipe search path.

func SearchPath(cwd, userConfigDir, extra string) []Dir

type Entry ¶

type Entry struct {
	Name   string
	Path   string
	Source string
	Recipe *Recipe
	Err    error
}

Entry is one row of a recipe listing: a loaded recipe, or the error that stopped it loading. One malformed file must not hide every other recipe.

func List(dirs []Dir) []Entry

type Input ¶

type Input struct {
	Required    bool   `json:"required"`
	Default     string `json:"default,omitempty"`
	Description string `json:"description,omitempty"`
}

Input declares one parameter. That is the whole schema — no types, no validation expressions; a recipe that needs them should be a program calling `session`.

type Opts ¶

type Opts struct {
	Set      map[string]string // values from --set
	Target   string            // overrides the recipe's own `target:` when set
	FromStep int               // 1-based start step; 0 means "from the beginning"
	Split    Splitter          // optional; see Splitter
}

Opts are the run-time knobs Resolve applies.

type Plan ¶

type Plan struct {
	Recipe   *Recipe
	Inputs   map[string]string
	Steps    []PlanStep
	FromStep int // 1-based; 1 unless --from-step moved it
	Target   string
}

Plan is a fully resolved recipe: nothing left to decide, nothing left to look up.

func Resolve(r *Recipe, opts Opts) (*Plan, error)

type PlanStep ¶

type PlanStep struct {
	// Index is the 1-based position in the recipe file, preserved across
	// --from-step so a summary points at the step the author would recognise.
	Index   int      `json:"step"`
	Label   string   `json:"label,omitempty"`
	Argv    []string `json:"run"`
	OnError string   `json:"on_error"`
}

PlanStep is one resolved step: argv with every placeholder substituted, ready to hand to the `session` execution path unchanged.

type Recipe ¶

type Recipe struct {
	Name        string           `json:"name"`
	Description string           `json:"description,omitempty"`
	Inputs      map[string]Input `json:"inputs,omitempty"`
	Target      string           `json:"target,omitempty"`
	Steps       []Step           `json:"steps"`

	// Path is where the recipe was read from; Source names the search-path
	// entry that provided it ("project", "user", or "--dir").
	Path   string `json:"path"`
	Source string `json:"source"`
}

Recipe is a loaded, schema-valid recipe. Inputs are unresolved at this stage: Run still carries `{{placeholder}}` text, and every placeholder in it is guaranteed to name a declared input.

func Load(path, source string) (*Recipe, error)

func (r *Recipe) InputNames() []string

type Splitter ¶

type Splitter func(argv []string) (flagIdx, posIdx []int, ok bool)

Splitter classifies one step's argv AS WRITTEN — before any substitution — into the elements the command tree may parse (the command path and the step's own flags, with their values) and the elements that must arrive as data. Indices are into the argv it was given; an index in neither slice is dropped, which is how a step's own `--` is absorbed and re-emitted in the one place it belongs. ok is false when the argv names no command it can resolve, in which case Resolve leaves the argv alone and lets the command tree produce its ordinary usage error.

It reads the argv as written because that is the only text the recipe's AUTHOR wrote. What is a flag has to be decided there and never by an input value: `--set sel=--target=@2` substituted into a step's positional is data, not a second target.

The recipe package cannot implement this — flag arity lives in the command tree — so the CLI supplies it. Resolve without one keeps the argv in written order, which is what the pure tests here use.

type Step ¶

type Step struct {
	Label   string   `json:"label,omitempty"`
	Run     []string `json:"run"`
	OnError string   `json:"on_error"`
}

Step is one validated step: an argv array plus its failure policy.