feat(formula): make primitives discoverable to coding agents (GH#3621) (#3781)
* feat(formula): add bd formula schema reflection-driven primitive index (beads-9ib)
Generates internal/formula/schema_gen.go from types.go via go:generate,
exposing all 18 exported structs (Formula, Step, LoopSpec, OnCompleteSpec,
etc.) with field types, json/toml tags, required-flag, and doc comments.
Surfaced via:
bd formula schema # list every primitive
bd formula schema loop # show LoopSpec fields
bd formula primitives on_complete # alias + snake_case match
bd formula schema --json # machine-readable
Lookup prefers exact match over Spec/Rule(s) suffix-strip, so "gate"
resolves to Gate (not GateRule). Fields tagged json:"-" (Step.SourceFormula,
Step.SourceLocation) are excluded.
TestSchemaGenIsCurrent re-runs the AST walker in-memory and byte-diffs
against the committed schema_gen.go, so a new struct in types.go without
a regen will fail CI.
Item 2 of GH#3621.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(formula): point bd formula --help at the primitive index (beads-lnf)
Extends the cobra Long descriptions on `formula`, `formula list`, and
`formula show` so an agent reading any of them is told that
`bd formula schema` (alias `primitives`), the curated
`examples/formulas/primitives/` directory, and the website primitives
reference exist. Without these pointers, agents land on the formula
surface and conclude there is no primitive index — which is the exact
failure mode GH#3621 is closing.
Adds cmd/bd/testdata/formula_help.txt as the regression gate: a
scripttest that runs `bd formula --help` (plus `--help` on the list
and show subcommands) and asserts the four pointers are present. If
someone deletes a pointer, the snapshot fails.
website/docs/cli-reference/formula.md is auto-generated from the Long
descriptions via `bd help --doc formula`, so the website doc inherits
the pointers on its next regeneration with no manual edit.
Item 1 of GH#3621.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(formula): curated primitive examples + smoke harness (beads-0sp)
Adds examples/formulas/primitives/ with one minimal `.formula.toml` per
empirically wired primitive in internal/formula/types.go:
loop-count LoopSpec.count expand body 3x → .iter1.work…
loop-range LoopSpec.range/var {n} substitutes into title
children-epic Step.Children epic + children w/ sibling needs
branch-fanin ComposeRules.Branch fork-join, deploy depends on 3 sibs
condition Step.Condition var-driven step inclusion
gate-timer Step.Gate sibling gate-typed issue blocks step
Each fixture has a header doc-comment explaining the primitive in
plain language; README.md indexes them with a one-line description
each and points back at `bd formula schema`.
cmd/bd/formula_primitives_test.go is the smoke harness: for each
fixture it parses, cooks through the full transformation pipeline
(loops → branches → gates → advice → expansions → conditions), and
asserts the primitive's observable effect on the cooked subgraph
(issue IDs, blocking deps, substituted titles, gate await_type).
Cooks against an in-memory subgraph rather than a Dolt-backed temp
DB so the harness exercises the primitive transformation, not the
persistence/auto-export infrastructure.
A subtest fails if a fixture is added to the directory without a
registered assertion in cases[] — the harness exists to prove
primitives are wired, not just that fixtures parse.
Explicitly omits an `on_complete` fixture; that primitive is a
runtime no-op as of v1.0.3 and ships with beads-i02's resolution,
not this epic.
Item 3 of GH#3621.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(formula): satisfy CI gosec G306 + regen CLI doc for new help text
Two CI fixes for the formula primitives PR:
- internal/formula/cmd/schemagen/main.go:26 — drop WriteFile perms
from 0644 to 0600 (gosec G306).
- website/docs/cli-reference/formula.md and the v1.0.0 mirror —
regenerated from the updated `bd formula --help` Long text via
scripts/generate-cli-docs.sh, using a CGO_ENABLED=0 bd build to
match CI.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(formula): distinguish schema from wired primitives
* fix(formula): regen schema_gen.go for rebase onto current main
Upstream main's Formula struct gained an Intent field after PR #3781 was
opened; regenerate schema_gen.go via go generate so
TestSchemaGenIsCurrent passes after rebasing the PR's commits onto
current main.
Maintainer fix-merge for gastownhall/beads#3781.
Agent-Signature: claude-fable-5-medium on behalf of matt wilkie
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
This commit is contained in:
parent
8fc3c963d7
commit
7be354810f
25 changed files with 2263 additions and 49 deletions
|
|
@ -32,8 +32,16 @@ Search paths (in order):
|
|||
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
|
||||
|
||||
Commands:
|
||||
list List available formulas from all search paths
|
||||
show Show formula details, steps, and composition rules`,
|
||||
list List available formulas from all search paths
|
||||
show Show formula details, steps, and composition rules
|
||||
schema Show the formula schema index (alias: primitives)
|
||||
|
||||
Discovering primitives:
|
||||
bd formula schema # list every declared formula struct
|
||||
bd formula schema loop # show LoopSpec fields, types, and tags
|
||||
bd formula primitives gate # alias; same handler as 'schema'
|
||||
examples/formulas/primitives/ # curated, smoke-tested wired fixtures
|
||||
website/docs/workflows/formulas.md # narrative reference`,
|
||||
}
|
||||
|
||||
// formulaListCmd lists all available formulas.
|
||||
|
|
@ -50,6 +58,9 @@ Search paths (in order of priority):
|
|||
|
||||
Formulas in earlier paths shadow those with the same name in later paths.
|
||||
|
||||
To list the declared formula schema structs an agent can write inside a .formula.toml,
|
||||
use 'bd formula schema' (alias: 'bd formula primitives').
|
||||
|
||||
Examples:
|
||||
bd formula list
|
||||
bd formula list --json
|
||||
|
|
@ -73,6 +84,9 @@ Displays:
|
|||
- Composition rules (extends, aspects, expansions)
|
||||
- Bond points for external composition
|
||||
|
||||
To inspect the structure of an individual primitive (e.g. LoopSpec, Gate)
|
||||
rather than a user-authored formula, use 'bd formula schema <primitive>'.
|
||||
|
||||
Examples:
|
||||
bd formula show shiny
|
||||
bd formula show rule-of-five
|
||||
|
|
|
|||
236
cmd/bd/formula_primitives_test.go
Normal file
236
cmd/bd/formula_primitives_test.go
Normal file
|
|
@ -0,0 +1,236 @@
|
|||
package main
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/steveyegge/beads/internal/types"
|
||||
)
|
||||
|
||||
// TestFormulaPrimitiveExamples is the smoke harness for
|
||||
// examples/formulas/primitives/. Each entry parses a fixture, cooks it
|
||||
// through the full transformation pipeline, and asserts the primitive's
|
||||
// observable effect on the resulting subgraph.
|
||||
//
|
||||
// A new fixture added to the directory without a registered case here is
|
||||
// a deliberate failure (subTestForUnregisteredFixtures): the harness
|
||||
// exists to prove primitives are wired, not that fixtures parse.
|
||||
func TestFormulaPrimitiveExamples(t *testing.T) {
|
||||
primDir := primitivesDir(t)
|
||||
|
||||
cases := []struct {
|
||||
name string
|
||||
vars map[string]string // non-nil enables Step.Condition filtering with formula defaults merged in
|
||||
assert func(t *testing.T, sg *TemplateSubgraph)
|
||||
}{
|
||||
{
|
||||
name: "loop-count",
|
||||
assert: func(t *testing.T, sg *TemplateSubgraph) {
|
||||
for _, want := range []string{
|
||||
"loop-count.process.iter1.work",
|
||||
"loop-count.process.iter2.work",
|
||||
"loop-count.process.iter3.work",
|
||||
} {
|
||||
if !hasIssueID(sg, want) {
|
||||
t.Errorf("missing issue %q; have %v", want, allIssueIDs(sg))
|
||||
}
|
||||
}
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "loop-range",
|
||||
assert: func(t *testing.T, sg *TemplateSubgraph) {
|
||||
for _, want := range []string{"Move 1", "Move 2", "Move 3"} {
|
||||
if !hasIssueTitle(sg, want) {
|
||||
t.Errorf("missing title %q; have %v", want, allIssueTitles(sg))
|
||||
}
|
||||
}
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "children-epic",
|
||||
assert: func(t *testing.T, sg *TemplateSubgraph) {
|
||||
// Children get the parent step's ID prefixed to their own.
|
||||
for _, want := range []string{
|
||||
"children-epic.ship-feature",
|
||||
"children-epic.ship-feature.draft",
|
||||
"children-epic.ship-feature.polish",
|
||||
} {
|
||||
if !hasIssueID(sg, want) {
|
||||
t.Errorf("missing issue %q; have %v", want, allIssueIDs(sg))
|
||||
}
|
||||
}
|
||||
if !hasBlockingDep(sg, "children-epic.ship-feature.polish", "children-epic.ship-feature.draft") {
|
||||
t.Errorf("polish must block on draft; deps: %v", allDeps(sg))
|
||||
}
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "branch-fanin",
|
||||
assert: func(t *testing.T, sg *TemplateSubgraph) {
|
||||
for _, src := range []string{"test", "lint", "build"} {
|
||||
if !hasBlockingDep(sg, "branch-fanin.deploy", "branch-fanin."+src) {
|
||||
t.Errorf("deploy must block on %s; deps: %v", src, allDeps(sg))
|
||||
}
|
||||
}
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "condition",
|
||||
vars: map[string]string{}, // trigger filtering with formula's deploy=false default
|
||||
assert: func(t *testing.T, sg *TemplateSubgraph) {
|
||||
children := childIssueIDs(sg, "condition")
|
||||
if len(children) != 2 {
|
||||
t.Errorf("default deploy=false → want 2 child issues, got %d: %v", len(children), children)
|
||||
}
|
||||
if hasIssueID(sg, "condition.deploy") {
|
||||
t.Error("deploy must be excluded when deploy=false")
|
||||
}
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "condition-true",
|
||||
vars: map[string]string{"deploy": "true"},
|
||||
assert: func(t *testing.T, sg *TemplateSubgraph) {
|
||||
children := childIssueIDs(sg, "condition")
|
||||
if len(children) != 3 {
|
||||
t.Errorf("deploy=true → want 3 child issues, got %d: %v", len(children), children)
|
||||
}
|
||||
if !hasIssueID(sg, "condition.deploy") {
|
||||
t.Error("deploy must be included when deploy=true")
|
||||
}
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "gate-timer",
|
||||
assert: func(t *testing.T, sg *TemplateSubgraph) {
|
||||
gate := findGate(sg)
|
||||
if gate == nil {
|
||||
t.Fatalf("no gate-typed sibling issue in subgraph; issues: %v", allIssueIDs(sg))
|
||||
}
|
||||
if gate.AwaitType != "timer" {
|
||||
t.Errorf("gate.AwaitType = %q, want %q", gate.AwaitType, "timer")
|
||||
}
|
||||
if !hasBlockingDep(sg, "gate-timer.verify", gate.ID) {
|
||||
t.Errorf("verify must block on gate %s; deps: %v", gate.ID, allDeps(sg))
|
||||
}
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
registered := map[string]bool{}
|
||||
for _, c := range cases {
|
||||
// "condition-true" is a second pass on the "condition" fixture.
|
||||
formulaName := strings.TrimSuffix(c.name, "-true")
|
||||
registered[formulaName] = true
|
||||
|
||||
t.Run(c.name, func(t *testing.T) {
|
||||
sg, err := resolveAndCookFormulaWithVars(formulaName, []string{primDir}, c.vars)
|
||||
if err != nil {
|
||||
t.Fatalf("cook %q: %v", formulaName, err)
|
||||
}
|
||||
c.assert(t, sg)
|
||||
})
|
||||
}
|
||||
|
||||
t.Run("every_fixture_has_a_registered_case", func(t *testing.T) {
|
||||
entries, err := os.ReadDir(primDir)
|
||||
if err != nil {
|
||||
t.Fatalf("readdir %s: %v", primDir, err)
|
||||
}
|
||||
for _, e := range entries {
|
||||
if !strings.HasSuffix(e.Name(), ".formula.toml") && !strings.HasSuffix(e.Name(), ".formula.json") {
|
||||
continue
|
||||
}
|
||||
name := strings.TrimSuffix(e.Name(), ".formula.toml")
|
||||
name = strings.TrimSuffix(name, ".formula.json")
|
||||
if !registered[name] {
|
||||
t.Errorf("fixture %q has no smoke assertion in cases[]; add one or delete the fixture", e.Name())
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
func primitivesDir(t *testing.T) string {
|
||||
t.Helper()
|
||||
dir, err := filepath.Abs(filepath.Join("..", "..", "examples", "formulas", "primitives"))
|
||||
if err != nil {
|
||||
t.Fatalf("abs path: %v", err)
|
||||
}
|
||||
if _, err := os.Stat(dir); err != nil {
|
||||
t.Fatalf("primitives dir missing: %v", err)
|
||||
}
|
||||
return dir
|
||||
}
|
||||
|
||||
func hasIssueID(sg *TemplateSubgraph, id string) bool {
|
||||
for _, i := range sg.Issues {
|
||||
if i.ID == id {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func hasIssueTitle(sg *TemplateSubgraph, title string) bool {
|
||||
for _, i := range sg.Issues {
|
||||
if i.Title == title {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func hasBlockingDep(sg *TemplateSubgraph, from, to string) bool {
|
||||
for _, d := range sg.Dependencies {
|
||||
if d.IssueID == from && d.DependsOnID == to && d.Type == "blocks" {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func findGate(sg *TemplateSubgraph) *types.Issue {
|
||||
for _, i := range sg.Issues {
|
||||
if i.IssueType == "gate" {
|
||||
return i
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func childIssueIDs(sg *TemplateSubgraph, rootID string) []string {
|
||||
var out []string
|
||||
for _, i := range sg.Issues {
|
||||
if i.ID != rootID {
|
||||
out = append(out, i.ID)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func allIssueIDs(sg *TemplateSubgraph) []string {
|
||||
out := make([]string, 0, len(sg.Issues))
|
||||
for _, i := range sg.Issues {
|
||||
out = append(out, i.ID)
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func allIssueTitles(sg *TemplateSubgraph) []string {
|
||||
out := make([]string, 0, len(sg.Issues))
|
||||
for _, i := range sg.Issues {
|
||||
out = append(out, i.Title)
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func allDeps(sg *TemplateSubgraph) []string {
|
||||
out := make([]string, 0, len(sg.Dependencies))
|
||||
for _, d := range sg.Dependencies {
|
||||
out = append(out, d.IssueID+" -> "+d.DependsOnID+" ("+string(d.Type)+")")
|
||||
}
|
||||
return out
|
||||
}
|
||||
134
cmd/bd/formula_schema.go
Normal file
134
cmd/bd/formula_schema.go
Normal file
|
|
@ -0,0 +1,134 @@
|
|||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"strings"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
"github.com/steveyegge/beads/internal/formula"
|
||||
"github.com/steveyegge/beads/internal/ui"
|
||||
)
|
||||
|
||||
var formulaSchemaCmd = &cobra.Command{
|
||||
Use: "schema [primitive]",
|
||||
Aliases: []string{"primitives"},
|
||||
Short: "Show the formula schema index (every exported struct in types.go)",
|
||||
Long: `Show the formula schema index: every exported struct declared
|
||||
in a .formula.toml/.formula.json, with field names, types, and tags.
|
||||
|
||||
The index is generated from internal/formula/types.go via go:generate; the
|
||||
struct definitions are the source of truth, so this list cannot drift. It is
|
||||
structural reference, not proof that every declared runtime behavior is wired.
|
||||
|
||||
Examples:
|
||||
bd formula schema # list every declared schema struct
|
||||
bd formula schema loop # show LoopSpec fields
|
||||
bd formula primitives gate # alias; shows Gate fields
|
||||
bd formula schema --json # machine-readable index
|
||||
|
||||
Curated smoke-tested fixtures for wired primitives live in
|
||||
examples/formulas/primitives/ (with a smoke harness that proves they work).`,
|
||||
Args: cobra.MaximumNArgs(1),
|
||||
Run: runFormulaSchema,
|
||||
}
|
||||
|
||||
func runFormulaSchema(cmd *cobra.Command, args []string) {
|
||||
if len(args) == 0 {
|
||||
runFormulaSchemaList()
|
||||
return
|
||||
}
|
||||
runFormulaSchemaShow(args[0])
|
||||
}
|
||||
|
||||
func runFormulaSchemaList() {
|
||||
if jsonOutput {
|
||||
outputJSON(formula.Primitives)
|
||||
return
|
||||
}
|
||||
|
||||
fmt.Printf("Formula schema structs (%d):\n\n", len(formula.Primitives))
|
||||
for _, p := range formula.Primitives {
|
||||
fmt.Printf(" %-18s %s\n", p.Name, firstDocLine(p.Doc))
|
||||
}
|
||||
fmt.Printf("\n%s\n", ui.RenderMuted("Show fields: bd formula schema <name>"))
|
||||
fmt.Printf("%s\n", ui.RenderMuted("Wired examples: examples/formulas/primitives/"))
|
||||
fmt.Printf("%s\n", ui.RenderMuted("Note: schema output is structural; smoke-tested examples are the verified authoring surface."))
|
||||
}
|
||||
|
||||
func runFormulaSchemaShow(name string) {
|
||||
p := formula.PrimitiveByName(name)
|
||||
if p == nil {
|
||||
fmt.Fprintf(os.Stderr, "Error: unknown primitive %q\n\n", name)
|
||||
fmt.Fprintf(os.Stderr, "Available primitives:\n")
|
||||
for _, prim := range formula.Primitives {
|
||||
fmt.Fprintf(os.Stderr, " %s\n", prim.Name)
|
||||
}
|
||||
os.Exit(1)
|
||||
}
|
||||
|
||||
if jsonOutput {
|
||||
outputJSON(p)
|
||||
return
|
||||
}
|
||||
|
||||
fmt.Printf("%s\n", ui.RenderAccent(p.Name))
|
||||
if p.Doc != "" {
|
||||
for _, line := range strings.Split(p.Doc, "\n") {
|
||||
fmt.Printf(" %s\n", line)
|
||||
}
|
||||
}
|
||||
|
||||
if len(p.Fields) == 0 {
|
||||
fmt.Printf("\n %s\n", ui.RenderMuted("(no exposed fields)"))
|
||||
return
|
||||
}
|
||||
|
||||
fmt.Printf("\nFields:\n")
|
||||
maxName, maxType := 0, 0
|
||||
for _, f := range p.Fields {
|
||||
if n := len(f.JSONName); n > maxName {
|
||||
maxName = n
|
||||
}
|
||||
if n := len(f.Type); n > maxType {
|
||||
maxType = n
|
||||
}
|
||||
}
|
||||
if maxName < 8 {
|
||||
maxName = 8
|
||||
}
|
||||
if maxType < 8 {
|
||||
maxType = 8
|
||||
}
|
||||
|
||||
for _, f := range p.Fields {
|
||||
req := ""
|
||||
if f.Required {
|
||||
req = " " + ui.RenderFail("required")
|
||||
}
|
||||
fmt.Printf(" %-*s %-*s%s\n", maxName, f.JSONName, maxType, f.Type, req)
|
||||
if f.Doc != "" {
|
||||
for _, line := range strings.Split(f.Doc, "\n") {
|
||||
fmt.Printf(" %s\n", ui.RenderMuted(line))
|
||||
}
|
||||
}
|
||||
if f.TOMLName != "" && f.TOMLName != f.JSONName {
|
||||
fmt.Printf(" %s\n", ui.RenderMuted(fmt.Sprintf("toml: %s", f.TOMLName)))
|
||||
}
|
||||
fmt.Println()
|
||||
}
|
||||
}
|
||||
|
||||
func firstDocLine(doc string) string {
|
||||
if doc == "" {
|
||||
return ""
|
||||
}
|
||||
if i := strings.IndexByte(doc, '\n'); i >= 0 {
|
||||
return doc[:i]
|
||||
}
|
||||
return doc
|
||||
}
|
||||
|
||||
func init() {
|
||||
formulaCmd.AddCommand(formulaSchemaCmd)
|
||||
}
|
||||
126
cmd/bd/formula_schema_test.go
Normal file
126
cmd/bd/formula_schema_test.go
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/steveyegge/beads/internal/formula"
|
||||
)
|
||||
|
||||
func TestFormulaSchemaList_HumanOutput(t *testing.T) {
|
||||
prevJSON := jsonOutput
|
||||
jsonOutput = false
|
||||
defer func() { jsonOutput = prevJSON }()
|
||||
|
||||
out := captureStdout(t, func() error {
|
||||
runFormulaSchemaList()
|
||||
return nil
|
||||
})
|
||||
|
||||
for _, prim := range formula.Primitives {
|
||||
if !strings.Contains(out, prim.Name) {
|
||||
t.Errorf("primitive %s missing from list output", prim.Name)
|
||||
}
|
||||
}
|
||||
if !strings.Contains(out, "examples/formulas/primitives/") {
|
||||
t.Error("list output must point users at examples/formulas/primitives/")
|
||||
}
|
||||
}
|
||||
|
||||
func TestFormulaSchemaList_JSON(t *testing.T) {
|
||||
prevJSON := jsonOutput
|
||||
jsonOutput = true
|
||||
defer func() { jsonOutput = prevJSON }()
|
||||
|
||||
out := captureStdout(t, func() error {
|
||||
runFormulaSchemaList()
|
||||
return nil
|
||||
})
|
||||
|
||||
// outputJSON injects a schema_version on objects but passes arrays
|
||||
// through unchanged. Primitives is a slice → we get a bare JSON array.
|
||||
var got []formula.PrimitiveDoc
|
||||
if err := json.Unmarshal([]byte(out), &got); err != nil {
|
||||
t.Fatalf("invalid JSON: %v\noutput: %s", err, out)
|
||||
}
|
||||
if len(got) != len(formula.Primitives) {
|
||||
t.Errorf("got %d primitives, want %d", len(got), len(formula.Primitives))
|
||||
}
|
||||
}
|
||||
|
||||
func TestFormulaSchemaShow_RendersFields(t *testing.T) {
|
||||
prevJSON := jsonOutput
|
||||
jsonOutput = false
|
||||
defer func() { jsonOutput = prevJSON }()
|
||||
|
||||
out := captureStdout(t, func() error {
|
||||
runFormulaSchemaShow("loop")
|
||||
return nil
|
||||
})
|
||||
|
||||
for _, want := range []string{"LoopSpec", "count", "until", "max", "range", "var", "body", "[]*Step"} {
|
||||
if !strings.Contains(out, want) {
|
||||
t.Errorf("loop output missing %q\nfull output:\n%s", want, out)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestFormulaSchemaShow_AliasResolution(t *testing.T) {
|
||||
prevJSON := jsonOutput
|
||||
jsonOutput = false
|
||||
defer func() { jsonOutput = prevJSON }()
|
||||
|
||||
for _, input := range []string{"on_complete", "OnComplete", "OnCompleteSpec"} {
|
||||
out := captureStdout(t, func() error {
|
||||
runFormulaSchemaShow(input)
|
||||
return nil
|
||||
})
|
||||
if !strings.Contains(out, "OnCompleteSpec") {
|
||||
t.Errorf("%q did not resolve to OnCompleteSpec; output:\n%s", input, out)
|
||||
}
|
||||
if !strings.Contains(out, "for_each") {
|
||||
t.Errorf("%q output missing for_each field", input)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestFormulaSchemaCmd_AliasRegistered(t *testing.T) {
|
||||
// `bd formula primitives` must route to the same handler as `bd formula schema`.
|
||||
found := false
|
||||
for _, alias := range formulaSchemaCmd.Aliases {
|
||||
if alias == "primitives" {
|
||||
found = true
|
||||
break
|
||||
}
|
||||
}
|
||||
if !found {
|
||||
t.Fatalf("formulaSchemaCmd.Aliases = %v, want to contain \"primitives\"", formulaSchemaCmd.Aliases)
|
||||
}
|
||||
}
|
||||
|
||||
func TestFormulaSchemaShow_JSON(t *testing.T) {
|
||||
prevJSON := jsonOutput
|
||||
jsonOutput = true
|
||||
defer func() { jsonOutput = prevJSON }()
|
||||
|
||||
out := captureStdout(t, func() error {
|
||||
runFormulaSchemaShow("loop")
|
||||
return nil
|
||||
})
|
||||
|
||||
// Single-primitive output goes through outputJSON which injects
|
||||
// schema_version into objects. Decode into a generic map and assert
|
||||
// the payload fields are present.
|
||||
var got map[string]interface{}
|
||||
if err := json.Unmarshal([]byte(out), &got); err != nil {
|
||||
t.Fatalf("invalid JSON: %v\noutput: %s", err, out)
|
||||
}
|
||||
if got["name"] != "LoopSpec" {
|
||||
t.Errorf("name = %v, want LoopSpec", got["name"])
|
||||
}
|
||||
fields, ok := got["fields"].([]interface{})
|
||||
if !ok || len(fields) == 0 {
|
||||
t.Fatalf("fields missing or empty in JSON output: %v", got["fields"])
|
||||
}
|
||||
}
|
||||
|
|
@ -213,17 +213,24 @@ func captureStdout(t *testing.T, fn func() error) string {
|
|||
r, w, _ := os.Pipe()
|
||||
os.Stdout = w
|
||||
|
||||
done := make(chan string, 1)
|
||||
go func() {
|
||||
var buf bytes.Buffer
|
||||
_, _ = buf.ReadFrom(r)
|
||||
done <- buf.String()
|
||||
}()
|
||||
|
||||
err := fn()
|
||||
|
||||
w.Close()
|
||||
var buf bytes.Buffer
|
||||
buf.ReadFrom(r)
|
||||
os.Stdout = oldStdout
|
||||
out := <-done
|
||||
_ = r.Close()
|
||||
|
||||
if err != nil {
|
||||
t.Errorf("unexpected error: %v", err)
|
||||
}
|
||||
return buf.String()
|
||||
return out
|
||||
}
|
||||
|
||||
// captureStderr captures stderr output from fn and returns it as a string.
|
||||
|
|
|
|||
19
cmd/bd/testdata/formula_help.txt
vendored
Normal file
19
cmd/bd/testdata/formula_help.txt
vendored
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
# Test that bd formula --help surfaces the primitive-discoverability pointers.
|
||||
#
|
||||
# Failure of any of these assertions means an agent reading 'bd formula --help'
|
||||
# would not be told that 'bd formula schema' / 'bd formula primitives' /
|
||||
# examples/formulas/primitives/ exist. That is the exact failure mode GH#3621
|
||||
# is closing, so this test is the regression gate.
|
||||
bd formula --help
|
||||
stdout 'bd formula schema'
|
||||
stdout 'bd formula primitives'
|
||||
stdout 'examples/formulas/primitives/'
|
||||
stdout 'website/docs/workflows/formulas.md'
|
||||
|
||||
# The list and show subcommands also point at the schema index so agents
|
||||
# arriving via either subcommand find the primitive surface.
|
||||
bd formula list --help
|
||||
stdout 'bd formula schema'
|
||||
|
||||
bd formula show --help
|
||||
stdout 'bd formula schema'
|
||||
|
|
@ -244,6 +244,7 @@ Reference for bd Latest. Generated from `bd help --all`.
|
|||
- [bd formula](#bd-formula) — Manage workflow formulas
|
||||
- [bd formula convert](#bd-formula-convert) — Convert formula from JSON to TOML
|
||||
- [bd formula list](#bd-formula-list) — List available formulas
|
||||
- [bd formula schema](#bd-formula-schema) — Show the formula schema index (every exported struct in types.go)
|
||||
- [bd formula show](#bd-formula-show) — Show formula details
|
||||
- [bd github](#bd-github) — GitHub integration commands
|
||||
- [bd github pull](#bd-github-pull) — Pull specific items from GitHub
|
||||
|
|
@ -5697,8 +5698,16 @@ Search paths (in order):
|
|||
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
|
||||
|
||||
Commands:
|
||||
list List available formulas from all search paths
|
||||
show Show formula details, steps, and composition rules
|
||||
list List available formulas from all search paths
|
||||
show Show formula details, steps, and composition rules
|
||||
schema Show the formula schema index (alias: primitives)
|
||||
|
||||
Discovering primitives:
|
||||
bd formula schema # list every declared formula struct
|
||||
bd formula schema loop # show LoopSpec fields, types, and tags
|
||||
bd formula primitives gate # alias; same handler as 'schema'
|
||||
examples/formulas/primitives/ # curated, smoke-tested wired fixtures
|
||||
website/docs/workflows/formulas.md # narrative reference
|
||||
|
||||
```
|
||||
bd formula
|
||||
|
|
@ -5747,6 +5756,9 @@ Search paths (in order of priority):
|
|||
|
||||
Formulas in earlier paths shadow those with the same name in later paths.
|
||||
|
||||
To list the declared formula schema structs an agent can write inside a .formula.toml,
|
||||
use 'bd formula schema' (alias: 'bd formula primitives').
|
||||
|
||||
Examples:
|
||||
bd formula list
|
||||
bd formula list --json
|
||||
|
|
@ -5763,6 +5775,30 @@ bd formula list [flags]
|
|||
--type string Filter by type (workflow, expansion, aspect, convoy)
|
||||
```
|
||||
|
||||
#### bd formula schema
|
||||
|
||||
Show the formula schema index: every exported struct declared
|
||||
in a .formula.toml/.formula.json, with field names, types, and tags.
|
||||
|
||||
The index is generated from internal/formula/types.go via go:generate; the
|
||||
struct definitions are the source of truth, so this list cannot drift. It is
|
||||
structural reference, not proof that every declared runtime behavior is wired.
|
||||
|
||||
Examples:
|
||||
bd formula schema # list every declared schema struct
|
||||
bd formula schema loop # show LoopSpec fields
|
||||
bd formula primitives gate # alias; shows Gate fields
|
||||
bd formula schema --json # machine-readable index
|
||||
|
||||
Curated smoke-tested fixtures for wired primitives live in
|
||||
examples/formulas/primitives/ (with a smoke harness that proves they work).
|
||||
|
||||
```
|
||||
bd formula schema [primitive]
|
||||
```
|
||||
|
||||
**Aliases:** primitives
|
||||
|
||||
#### bd formula show
|
||||
|
||||
Show detailed information about a formula.
|
||||
|
|
@ -5774,6 +5810,9 @@ Displays:
|
|||
- Composition rules (extends, aspects, expansions)
|
||||
- Bond points for external composition
|
||||
|
||||
To inspect the structure of an individual primitive (e.g. LoopSpec, Gate)
|
||||
rather than a user-authored formula, use 'bd formula schema <primitive>'.
|
||||
|
||||
Examples:
|
||||
bd formula show shiny
|
||||
bd formula show rule-of-five
|
||||
|
|
|
|||
54
examples/formulas/primitives/README.md
Normal file
54
examples/formulas/primitives/README.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
# Formula primitive examples
|
||||
|
||||
One curated `.formula.toml` per *empirically wired* primitive in
|
||||
`internal/formula/types.go`. Each fixture is minimal, self-documenting,
|
||||
and exercises exactly one primitive.
|
||||
|
||||
## What's here
|
||||
|
||||
| Fixture | Primitive | One-line behavior |
|
||||
|-------------------------------|--------------------|-------------------|
|
||||
| `loop-count.formula.toml` | `LoopSpec.count` | Body expanded N times into `.iterN.<id>` step IDs. |
|
||||
| `loop-range.formula.toml` | `LoopSpec.range` | Body expanded over a numeric range; `loop.var` substitutes into title/description. |
|
||||
| `children-epic.formula.toml` | `Step.children` | Nested steps form an epic with sibling `needs` honored. |
|
||||
| `branch-fanin.formula.toml` | `ComposeRules.branch` | Fork-join: parallel steps fan in to a single join step. |
|
||||
| `condition.formula.toml` | `Step.condition` | Variable-driven step inclusion at cook time. |
|
||||
| `gate-timer.formula.toml` | `Step.gate` | Sibling `gate`-typed issue with `await_type` blocks the target step. |
|
||||
|
||||
For the full schema index - every exported struct declared in
|
||||
`internal/formula/types.go`, with field types and tags -
|
||||
run:
|
||||
|
||||
```sh
|
||||
bd formula schema # list every declared schema struct
|
||||
bd formula schema loop # show LoopSpec fields
|
||||
bd formula primitives gate # alias
|
||||
bd formula schema --json # machine-readable
|
||||
```
|
||||
|
||||
Treat `bd formula schema` as structural reference. Treat this directory
|
||||
as the verified authoring surface: every fixture here is smoke-tested for
|
||||
an observable parse-to-cook effect.
|
||||
|
||||
## Smoke harness
|
||||
|
||||
`cmd/bd/formula_primitives_test.go` walks this directory, parses and
|
||||
cooks every fixture, and asserts each primitive's observable effect on
|
||||
the cooked subgraph. A new fixture added here without a registered
|
||||
assertion is a deliberate test failure: the harness exists to prove
|
||||
primitives are wired, not just that fixtures parse.
|
||||
|
||||
Run with `make test`, or in isolation:
|
||||
|
||||
```sh
|
||||
go test -tags gms_pure_go -run TestFormulaPrimitiveExamples ./cmd/bd/
|
||||
```
|
||||
|
||||
## What's NOT here
|
||||
|
||||
* `on_complete` — runtime no-op for every valid configuration as of
|
||||
v1.0.3 (tracked in `beads-i02`). Its fixture and smoke test ship with
|
||||
that issue's resolution PR, not here.
|
||||
* Anything in `internal/formula/types.go` without a verified end-to-end
|
||||
parse → cook → pour audit. New primitives earn a fixture once they're
|
||||
empirically wired, not when they're declared.
|
||||
35
examples/formulas/primitives/branch-fanin.formula.toml
Normal file
35
examples/formulas/primitives/branch-fanin.formula.toml
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
# Compose.Branch — fork-join parallel execution with a join step.
|
||||
#
|
||||
# `compose.branch` creates a fork-join pattern: every step in `steps` runs
|
||||
# after `from` completes, and `join` runs after every parallel step
|
||||
# completes. The smoke harness asserts `deploy` blocks on each of `test`,
|
||||
# `lint`, and `build`.
|
||||
formula = "branch-fanin"
|
||||
description = "Compose.Branch: deploy fans in after parallel test/lint/build."
|
||||
version = 1
|
||||
type = "workflow"
|
||||
|
||||
[[steps]]
|
||||
id = "prepare"
|
||||
title = "Prepare workspace"
|
||||
|
||||
[[steps]]
|
||||
id = "test"
|
||||
title = "Run tests"
|
||||
|
||||
[[steps]]
|
||||
id = "lint"
|
||||
title = "Run linter"
|
||||
|
||||
[[steps]]
|
||||
id = "build"
|
||||
title = "Build artifacts"
|
||||
|
||||
[[steps]]
|
||||
id = "deploy"
|
||||
title = "Deploy build"
|
||||
|
||||
[[compose.branch]]
|
||||
from = "prepare"
|
||||
steps = ["test", "lint", "build"]
|
||||
join = "deploy"
|
||||
24
examples/formulas/primitives/children-epic.formula.toml
Normal file
24
examples/formulas/primitives/children-epic.formula.toml
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
# Step.Children — nested steps form an epic with sub-tasks.
|
||||
#
|
||||
# A step with `children` becomes an epic; each child becomes a sub-issue
|
||||
# whose parent is the outer step. `needs` between siblings still wires
|
||||
# blocking dependencies. The smoke harness asserts the parent epic + 2
|
||||
# children exist and that `polish` blocks on `draft` (sibling needs).
|
||||
formula = "children-epic"
|
||||
description = "Step.Children: epic step with two children where polish needs draft."
|
||||
version = 1
|
||||
type = "workflow"
|
||||
|
||||
[[steps]]
|
||||
id = "ship-feature"
|
||||
title = "Ship the feature"
|
||||
type = "epic"
|
||||
|
||||
[[steps.children]]
|
||||
id = "draft"
|
||||
title = "Draft the implementation"
|
||||
|
||||
[[steps.children]]
|
||||
id = "polish"
|
||||
title = "Polish and document"
|
||||
needs = ["draft"]
|
||||
30
examples/formulas/primitives/condition.formula.toml
Normal file
30
examples/formulas/primitives/condition.formula.toml
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
# Step.Condition — variable-driven step inclusion.
|
||||
#
|
||||
# A step with `condition` is filtered out at cook time when the condition
|
||||
# evaluates to false against the current variable bindings. With the
|
||||
# default {{deploy}} = "false", the deploy step is excluded (2 child
|
||||
# issues). Override at cook time with --var deploy=true to include it
|
||||
# (3 child issues). The smoke harness exercises both branches.
|
||||
formula = "condition"
|
||||
description = "Step.Condition: deploy step is included only when deploy var is true."
|
||||
version = 1
|
||||
type = "workflow"
|
||||
|
||||
[vars.deploy]
|
||||
description = "Whether to include the deploy step"
|
||||
default = "false"
|
||||
|
||||
[[steps]]
|
||||
id = "build"
|
||||
title = "Build the project"
|
||||
|
||||
[[steps]]
|
||||
id = "test"
|
||||
title = "Run tests"
|
||||
needs = ["build"]
|
||||
|
||||
[[steps]]
|
||||
id = "deploy"
|
||||
title = "Deploy to production"
|
||||
needs = ["test"]
|
||||
condition = "{{deploy}} == true"
|
||||
25
examples/formulas/primitives/gate-timer.formula.toml
Normal file
25
examples/formulas/primitives/gate-timer.formula.toml
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
# Step.Gate — async wait condition that blocks a step until satisfied.
|
||||
#
|
||||
# A step with `gate` is split at cook time into two issues:
|
||||
# * a sibling `gate`-typed issue capturing the wait (await_type, timeout)
|
||||
# * the original step, with a blocking dep on the gate issue
|
||||
# The smoke harness asserts the gate issue exists with await_type=timer
|
||||
# and that the target step blocks on it.
|
||||
formula = "gate-timer"
|
||||
description = "Step.Gate: timer gate blocks the verify step until it elapses."
|
||||
version = 1
|
||||
type = "workflow"
|
||||
|
||||
[[steps]]
|
||||
id = "deploy"
|
||||
title = "Deploy build"
|
||||
|
||||
[[steps]]
|
||||
id = "verify"
|
||||
title = "Verify deployment after soak"
|
||||
depends_on = ["deploy"]
|
||||
|
||||
[steps.gate]
|
||||
type = "timer"
|
||||
await_id = "soak-30m"
|
||||
timeout = "30m"
|
||||
21
examples/formulas/primitives/loop-count.formula.toml
Normal file
21
examples/formulas/primitives/loop-count.formula.toml
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
# Loop.count — fixed-iteration loop.
|
||||
#
|
||||
# A step with `loop.count = N` is replaced at cook time by N copies of its
|
||||
# `loop.body`. Each copy gets the iteration index baked into its step ID:
|
||||
# the body step `work` becomes `process.iter1.work`, `process.iter2.work`,
|
||||
# `process.iter3.work`. The smoke harness asserts those three IDs exist.
|
||||
formula = "loop-count"
|
||||
description = "Loop.count: expand body 3 times into .iter1.work, .iter2.work, .iter3.work."
|
||||
version = 1
|
||||
type = "workflow"
|
||||
|
||||
[[steps]]
|
||||
id = "process"
|
||||
title = "Process items"
|
||||
|
||||
[steps.loop]
|
||||
count = 3
|
||||
|
||||
[[steps.loop.body]]
|
||||
id = "work"
|
||||
title = "Do unit of work"
|
||||
22
examples/formulas/primitives/loop-range.formula.toml
Normal file
22
examples/formulas/primitives/loop-range.formula.toml
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
# Loop.range — computed-bound loop with an iteration variable.
|
||||
#
|
||||
# `loop.range = "1..3"` plus `loop.var = "n"` exposes {n} = 1, 2, 3 to the
|
||||
# body's title and description. The body step `move` becomes three issues
|
||||
# titled "Move 1", "Move 2", "Move 3" — the smoke harness asserts those
|
||||
# substituted titles appear.
|
||||
formula = "loop-range"
|
||||
description = "Loop.range with var=n exposes {n} for title substitution."
|
||||
version = 1
|
||||
type = "workflow"
|
||||
|
||||
[[steps]]
|
||||
id = "moves"
|
||||
title = "Tower moves"
|
||||
|
||||
[steps.loop]
|
||||
range = "1..3"
|
||||
var = "n"
|
||||
|
||||
[[steps.loop.body]]
|
||||
id = "move"
|
||||
title = "Move {n}"
|
||||
30
internal/formula/cmd/schemagen/main.go
Normal file
30
internal/formula/cmd/schemagen/main.go
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
// Command schemagen regenerates internal/formula/schema_gen.go from
|
||||
// internal/formula/types.go. Driven by the //go:generate directive in
|
||||
// internal/formula/schema.go; not invoked at runtime.
|
||||
package main
|
||||
|
||||
import (
|
||||
"flag"
|
||||
"fmt"
|
||||
"os"
|
||||
|
||||
"github.com/steveyegge/beads/internal/formula/schemagen"
|
||||
)
|
||||
|
||||
func main() {
|
||||
var (
|
||||
typesPath = flag.String("types", "types.go", "path to types.go")
|
||||
outPath = flag.String("out", "schema_gen.go", "output path")
|
||||
)
|
||||
flag.Parse()
|
||||
|
||||
src, err := schemagen.Generate(*typesPath)
|
||||
if err != nil {
|
||||
fmt.Fprintf(os.Stderr, "schemagen: %v\n", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
if err := os.WriteFile(*outPath, src, 0600); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "schemagen: write %s: %v\n", *outPath, err)
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
91
internal/formula/schema.go
Normal file
91
internal/formula/schema.go
Normal file
|
|
@ -0,0 +1,91 @@
|
|||
package formula
|
||||
|
||||
//go:generate go run ./cmd/schemagen -types types.go -out schema_gen.go
|
||||
|
||||
// PrimitiveDoc describes one exported struct (a "primitive") in this package.
|
||||
// The slice Primitives in schema_gen.go is generated from types.go and serves
|
||||
// as the discoverability index surfaced by `bd formula schema`.
|
||||
type PrimitiveDoc struct {
|
||||
// Name is the Go struct name (e.g. "Formula", "LoopSpec").
|
||||
Name string `json:"name"`
|
||||
|
||||
// Doc is the struct's leading doc comment, trimmed.
|
||||
Doc string `json:"doc,omitempty"`
|
||||
|
||||
// Fields are the struct's exported, JSON-visible fields, in source order.
|
||||
Fields []FieldDoc `json:"fields,omitempty"`
|
||||
}
|
||||
|
||||
// FieldDoc describes one exported field of a primitive struct.
|
||||
// Fields tagged json:"-" are excluded from the schema entirely.
|
||||
type FieldDoc struct {
|
||||
// Name is the Go field name.
|
||||
Name string `json:"name"`
|
||||
|
||||
// Type is the Go type rendered as source (e.g. "string", "[]*Step",
|
||||
// "map[string]*VarDef").
|
||||
Type string `json:"type"`
|
||||
|
||||
// JSONName is the field name used in JSON output. Falls back to Name
|
||||
// when the json tag is absent.
|
||||
JSONName string `json:"json_name,omitempty"`
|
||||
|
||||
// TOMLName is the field name used in TOML output. Falls back to JSONName
|
||||
// when no toml tag is present.
|
||||
TOMLName string `json:"toml_name,omitempty"`
|
||||
|
||||
// Required is true when the field has no `,omitempty` option in its json
|
||||
// tag. This is a structural signal, not a guarantee the parser enforces
|
||||
// presence.
|
||||
Required bool `json:"required,omitempty"`
|
||||
|
||||
// Doc is the field's leading doc comment, trimmed.
|
||||
Doc string `json:"doc,omitempty"`
|
||||
}
|
||||
|
||||
// PrimitiveByName returns the PrimitiveDoc that matches name, or nil.
|
||||
// Matching is case-insensitive and ignores underscores/dashes; an exact
|
||||
// (normalized) match wins over a suffix-stripped match. So "gate" returns
|
||||
// Gate, "gaterule" returns GateRule, and "loop" or "on_complete" return
|
||||
// LoopSpec / OnCompleteSpec via the Spec/Rule suffix fallback.
|
||||
func PrimitiveByName(name string) *PrimitiveDoc {
|
||||
if name == "" {
|
||||
return nil
|
||||
}
|
||||
target := normalizePrimitiveName(name)
|
||||
for i := range Primitives {
|
||||
if normalizePrimitiveName(Primitives[i].Name) == target {
|
||||
return &Primitives[i]
|
||||
}
|
||||
}
|
||||
for i := range Primitives {
|
||||
if stripPrimitiveSuffix(normalizePrimitiveName(Primitives[i].Name)) == target {
|
||||
return &Primitives[i]
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func normalizePrimitiveName(s string) string {
|
||||
out := make([]byte, 0, len(s))
|
||||
for i := 0; i < len(s); i++ {
|
||||
c := s[i]
|
||||
if c == '_' || c == '-' || c == ' ' {
|
||||
continue
|
||||
}
|
||||
if c >= 'A' && c <= 'Z' {
|
||||
c += 'a' - 'A'
|
||||
}
|
||||
out = append(out, c)
|
||||
}
|
||||
return string(out)
|
||||
}
|
||||
|
||||
func stripPrimitiveSuffix(s string) string {
|
||||
for _, suf := range []string{"spec", "rules", "rule"} {
|
||||
if len(s) > len(suf) && s[len(s)-len(suf):] == suf {
|
||||
return s[:len(s)-len(suf)]
|
||||
}
|
||||
}
|
||||
return s
|
||||
}
|
||||
824
internal/formula/schema_gen.go
Normal file
824
internal/formula/schema_gen.go
Normal file
|
|
@ -0,0 +1,824 @@
|
|||
// Code generated by internal/formula/cmd/schemagen. DO NOT EDIT.
|
||||
|
||||
package formula
|
||||
|
||||
// Primitives is the discoverability index of every exported struct in
|
||||
// types.go. Surfaced via `bd formula schema`. Regenerate with `go generate ./...`.
|
||||
var Primitives = []PrimitiveDoc{
|
||||
{
|
||||
Name: "AdviceRule",
|
||||
Doc: `AdviceRule defines a step transformation rule.
|
||||
Advice operators insert steps before, after, or around matching targets.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "Target",
|
||||
Type: "string",
|
||||
JSONName: "target",
|
||||
Required: true,
|
||||
Doc: `Target is a glob pattern matching step IDs to apply advice to.
|
||||
Examples: "*.implement", "design", "shiny.*"`,
|
||||
},
|
||||
{
|
||||
Name: "Before",
|
||||
Type: "*AdviceStep",
|
||||
JSONName: "before",
|
||||
Doc: `Before inserts a step before the target.`,
|
||||
},
|
||||
{
|
||||
Name: "After",
|
||||
Type: "*AdviceStep",
|
||||
JSONName: "after",
|
||||
Doc: `After inserts a step after the target.`,
|
||||
},
|
||||
{
|
||||
Name: "Around",
|
||||
Type: "*AroundAdvice",
|
||||
JSONName: "around",
|
||||
Doc: `Around wraps the target with before and after steps.`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "AdviceStep",
|
||||
Doc: `AdviceStep defines a step to insert via advice.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "ID",
|
||||
Type: "string",
|
||||
JSONName: "id",
|
||||
Required: true,
|
||||
Doc: `ID is the step identifier. Supports {step.id} substitution.`,
|
||||
},
|
||||
{
|
||||
Name: "Title",
|
||||
Type: "string",
|
||||
JSONName: "title",
|
||||
Doc: `Title is the step title. Supports {step.id} substitution.`,
|
||||
},
|
||||
{
|
||||
Name: "Description",
|
||||
Type: "string",
|
||||
JSONName: "description",
|
||||
Doc: `Description is the step description.`,
|
||||
},
|
||||
{
|
||||
Name: "Type",
|
||||
Type: "string",
|
||||
JSONName: "type",
|
||||
Doc: `Type is the issue type (task, bug, etc).`,
|
||||
},
|
||||
{
|
||||
Name: "Args",
|
||||
Type: "map[string]string",
|
||||
JSONName: "args",
|
||||
Doc: `Args are additional context passed to the step.`,
|
||||
},
|
||||
{
|
||||
Name: "Output",
|
||||
Type: "map[string]string",
|
||||
JSONName: "output",
|
||||
Doc: `Output defines expected outputs from this step.`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "AroundAdvice",
|
||||
Doc: `AroundAdvice wraps a target with before and after steps.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "Before",
|
||||
Type: "[]*AdviceStep",
|
||||
JSONName: "before",
|
||||
Doc: `Before is a list of steps to insert before the target.`,
|
||||
},
|
||||
{
|
||||
Name: "After",
|
||||
Type: "[]*AdviceStep",
|
||||
JSONName: "after",
|
||||
Doc: `After is a list of steps to insert after the target.`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "BondPoint",
|
||||
Doc: `BondPoint is a named attachment site for composition.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "ID",
|
||||
Type: "string",
|
||||
JSONName: "id",
|
||||
Required: true,
|
||||
Doc: `ID is the unique identifier for this bond point.`,
|
||||
},
|
||||
{
|
||||
Name: "Description",
|
||||
Type: "string",
|
||||
JSONName: "description",
|
||||
Doc: `Description explains what should be attached here.`,
|
||||
},
|
||||
{
|
||||
Name: "AfterStep",
|
||||
Type: "string",
|
||||
JSONName: "after_step",
|
||||
Doc: `AfterStep is the step ID after which to attach.
|
||||
Mutually exclusive with BeforeStep.`,
|
||||
},
|
||||
{
|
||||
Name: "BeforeStep",
|
||||
Type: "string",
|
||||
JSONName: "before_step",
|
||||
Doc: `BeforeStep is the step ID before which to attach.
|
||||
Mutually exclusive with AfterStep.`,
|
||||
},
|
||||
{
|
||||
Name: "Parallel",
|
||||
Type: "bool",
|
||||
JSONName: "parallel",
|
||||
Doc: `Parallel makes attached steps run in parallel with the anchor step.`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "BranchRule",
|
||||
Doc: `BranchRule defines parallel execution paths that rejoin.
|
||||
Creates a fork-join pattern: from -> [parallel steps] -> join.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "From",
|
||||
Type: "string",
|
||||
JSONName: "from",
|
||||
Required: true,
|
||||
Doc: `From is the step ID that precedes the parallel paths.
|
||||
All branch steps will depend on this step.`,
|
||||
},
|
||||
{
|
||||
Name: "Steps",
|
||||
Type: "[]string",
|
||||
JSONName: "steps",
|
||||
Required: true,
|
||||
Doc: `Steps are the step IDs that run in parallel.
|
||||
These steps will all depend on From.`,
|
||||
},
|
||||
{
|
||||
Name: "Join",
|
||||
Type: "string",
|
||||
JSONName: "join",
|
||||
Required: true,
|
||||
Doc: `Join is the step ID that follows all parallel paths.
|
||||
This step will depend on all Steps completing.`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "ComposeRules",
|
||||
Doc: `ComposeRules define how formulas can be bonded together.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "BondPoints",
|
||||
Type: "[]*BondPoint",
|
||||
JSONName: "bond_points",
|
||||
Doc: `BondPoints are named locations where other formulas can attach.`,
|
||||
},
|
||||
{
|
||||
Name: "Hooks",
|
||||
Type: "[]*Hook",
|
||||
JSONName: "hooks",
|
||||
Doc: `Hooks are automatic attachments triggered by labels or conditions.`,
|
||||
},
|
||||
{
|
||||
Name: "Expand",
|
||||
Type: "[]*ExpandRule",
|
||||
JSONName: "expand",
|
||||
Doc: `Expand applies an expansion template to a single target step.
|
||||
The target step is replaced by the expanded template steps.`,
|
||||
},
|
||||
{
|
||||
Name: "Map",
|
||||
Type: "[]*MapRule",
|
||||
JSONName: "map",
|
||||
Doc: `Map applies an expansion template to all steps matching a pattern.
|
||||
Each matching step is replaced by the expanded template steps.`,
|
||||
},
|
||||
{
|
||||
Name: "Branch",
|
||||
Type: "[]*BranchRule",
|
||||
JSONName: "branch",
|
||||
Doc: `Branch defines fork-join parallel execution patterns.
|
||||
Each rule creates dependencies for parallel paths that rejoin.`,
|
||||
},
|
||||
{
|
||||
Name: "Gate",
|
||||
Type: "[]*GateRule",
|
||||
JSONName: "gate",
|
||||
Doc: `Gate defines conditional waits before steps.
|
||||
Each rule adds a condition that must be satisfied at runtime.`,
|
||||
},
|
||||
{
|
||||
Name: "Aspects",
|
||||
Type: "[]string",
|
||||
JSONName: "aspects",
|
||||
Doc: `Aspects lists aspect formula names to apply to this formula.
|
||||
Aspects are applied after expansions, adding before/after/around
|
||||
steps to matching targets based on the aspect's advice rules.
|
||||
Example: ["security-audit", "logging"]`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "ExpandRule",
|
||||
Doc: `ExpandRule applies an expansion template to a single target step.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "Target",
|
||||
Type: "string",
|
||||
JSONName: "target",
|
||||
Required: true,
|
||||
Doc: `Target is the step ID to expand.`,
|
||||
},
|
||||
{
|
||||
Name: "With",
|
||||
Type: "string",
|
||||
JSONName: "with",
|
||||
Required: true,
|
||||
Doc: `With is the name of the expansion formula to apply.`,
|
||||
},
|
||||
{
|
||||
Name: "Vars",
|
||||
Type: "map[string]string",
|
||||
JSONName: "vars",
|
||||
Doc: `Vars are variable overrides for the expansion.`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "Formula",
|
||||
Doc: `Formula is the root structure for .formula.json files.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "Formula",
|
||||
Type: "string",
|
||||
JSONName: "formula",
|
||||
Required: true,
|
||||
Doc: `Formula is the unique identifier/name for this formula.
|
||||
Convention: mol-<name> for molecules, exp-<name> for expansions.`,
|
||||
},
|
||||
{
|
||||
Name: "Description",
|
||||
Type: "string",
|
||||
JSONName: "description",
|
||||
Doc: `Description explains what this formula does.`,
|
||||
},
|
||||
{
|
||||
Name: "Version",
|
||||
Type: "int",
|
||||
JSONName: "version",
|
||||
Required: true,
|
||||
Doc: `Version is the schema version (currently 1).`,
|
||||
},
|
||||
{
|
||||
Name: "Type",
|
||||
Type: "FormulaType",
|
||||
JSONName: "type",
|
||||
Required: true,
|
||||
Doc: `Type categorizes the formula: workflow, expansion, or aspect.`,
|
||||
},
|
||||
{
|
||||
Name: "Extends",
|
||||
Type: "[]string",
|
||||
JSONName: "extends",
|
||||
Doc: `Extends is a list of parent formulas to inherit from.
|
||||
The child formula inherits all vars, steps, and compose rules.
|
||||
Child definitions override parent definitions with the same ID.`,
|
||||
},
|
||||
{
|
||||
Name: "Vars",
|
||||
Type: "map[string]*VarDef",
|
||||
JSONName: "vars",
|
||||
Doc: `Vars defines template variables with defaults and validation.`,
|
||||
},
|
||||
{
|
||||
Name: "Steps",
|
||||
Type: "[]*Step",
|
||||
JSONName: "steps",
|
||||
Doc: `Steps defines the work items to create.`,
|
||||
},
|
||||
{
|
||||
Name: "Template",
|
||||
Type: "[]*Step",
|
||||
JSONName: "template",
|
||||
Doc: `Template defines expansion template steps (for TypeExpansion formulas).
|
||||
Template steps use {target} and {target.description} placeholders
|
||||
that get substituted when the expansion is applied to a target step.`,
|
||||
},
|
||||
{
|
||||
Name: "Compose",
|
||||
Type: "*ComposeRules",
|
||||
JSONName: "compose",
|
||||
Doc: `Compose defines composition/bonding rules.`,
|
||||
},
|
||||
{
|
||||
Name: "Advice",
|
||||
Type: "[]*AdviceRule",
|
||||
JSONName: "advice",
|
||||
Doc: `Advice defines step transformations (before/after/around).
|
||||
Applied during cooking to insert steps around matching targets.`,
|
||||
},
|
||||
{
|
||||
Name: "Pointcuts",
|
||||
Type: "[]*Pointcut",
|
||||
JSONName: "pointcuts",
|
||||
Doc: `Pointcuts defines target patterns for aspect formulas.
|
||||
Used with TypeAspect to specify which steps the aspect applies to.`,
|
||||
},
|
||||
{
|
||||
Name: "Phase",
|
||||
Type: "string",
|
||||
JSONName: "phase",
|
||||
Doc: `Phase indicates the recommended instantiation phase: "liquid" (pour) or "vapor" (wisp).
|
||||
If "vapor", bd pour will warn and suggest using bd mol wisp instead.
|
||||
Patrol and release workflows should typically use "vapor" since they're operational.`,
|
||||
},
|
||||
{
|
||||
Name: "Pour",
|
||||
Type: "bool",
|
||||
JSONName: "pour",
|
||||
Doc: `Pour controls whether steps are materialized as individual child issues.
|
||||
If true, each step becomes a DB row with dependency tracking (checkpoint recovery).
|
||||
If false (default), only the root issue is created; steps are read inline at prime time.
|
||||
Reserve pour=true for critical, infrequent work (e.g. releases) where step-level
|
||||
tracking is worth the DB overhead. Patrol formulas should NOT set this.`,
|
||||
},
|
||||
{
|
||||
Name: "Source",
|
||||
Type: "string",
|
||||
JSONName: "source",
|
||||
Doc: `Source tracks where this formula was loaded from (set by parser).`,
|
||||
},
|
||||
{
|
||||
Name: "Intent",
|
||||
Type: "string",
|
||||
JSONName: "intent",
|
||||
Doc: `Intent is an optional caller-defined hint about the formula's runtime
|
||||
intent (e.g. "mail_only"). Opaque to bd; consumed by downstream tools.`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "Gate",
|
||||
Doc: `Gate defines an async wait condition for formula steps.
|
||||
When a step has a Gate, bd cook creates a gate issue that blocks the step.
|
||||
The gate must be closed (manually or via watchers) to unblock the step.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "Type",
|
||||
Type: "string",
|
||||
JSONName: "type",
|
||||
Required: true,
|
||||
Doc: `Type is the condition type: gh:run, gh:pr, timer, human, mail.`,
|
||||
},
|
||||
{
|
||||
Name: "ID",
|
||||
Type: "string",
|
||||
JSONName: "id",
|
||||
Doc: `ID is the condition identifier (e.g., workflow name for gh:run).`,
|
||||
},
|
||||
{
|
||||
Name: "AwaitID",
|
||||
Type: "string",
|
||||
JSONName: "await_id",
|
||||
Doc: `AwaitID is the runtime condition identifier. This is preferred by
|
||||
formula authors because it maps directly to Issue.AwaitID.`,
|
||||
},
|
||||
{
|
||||
Name: "Timeout",
|
||||
Type: "string",
|
||||
JSONName: "timeout",
|
||||
Doc: `Timeout is how long to wait before escalation (e.g., "1h", "24h").`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "GateRule",
|
||||
Doc: `GateRule defines a condition that must be satisfied before a step proceeds.
|
||||
Gates are evaluated at runtime by the patrol executor.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "Before",
|
||||
Type: "string",
|
||||
JSONName: "before",
|
||||
Required: true,
|
||||
Doc: `Before is the step ID that the gate applies to.
|
||||
The condition must be satisfied before this step can start.`,
|
||||
},
|
||||
{
|
||||
Name: "Condition",
|
||||
Type: "string",
|
||||
JSONName: "condition",
|
||||
Required: true,
|
||||
Doc: `Condition is the expression to evaluate.
|
||||
Format matches condition evaluator syntax (e.g., "tests.status == 'complete'").`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "Hook",
|
||||
Doc: `Hook defines automatic formula attachment based on conditions.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "Trigger",
|
||||
Type: "string",
|
||||
JSONName: "trigger",
|
||||
Required: true,
|
||||
Doc: `Trigger is what activates this hook.
|
||||
Formats: "label:security", "type:bug", "priority:0-1".`,
|
||||
},
|
||||
{
|
||||
Name: "Attach",
|
||||
Type: "string",
|
||||
JSONName: "attach",
|
||||
Required: true,
|
||||
Doc: `Attach is the formula to attach when triggered.`,
|
||||
},
|
||||
{
|
||||
Name: "At",
|
||||
Type: "string",
|
||||
JSONName: "at",
|
||||
Doc: `At is the bond point to attach at (default: end).`,
|
||||
},
|
||||
{
|
||||
Name: "Vars",
|
||||
Type: "map[string]string",
|
||||
JSONName: "vars",
|
||||
Doc: `Vars are variable overrides for the attached formula.`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "LoopSpec",
|
||||
Doc: `LoopSpec defines iteration over a body of steps.
|
||||
One of Count, Until, or Range must be specified.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "Count",
|
||||
Type: "int",
|
||||
JSONName: "count",
|
||||
Doc: `Count is the fixed number of iterations.
|
||||
When set, the loop body is expanded Count times.`,
|
||||
},
|
||||
{
|
||||
Name: "Until",
|
||||
Type: "string",
|
||||
JSONName: "until",
|
||||
Doc: `Until is a condition that ends the loop.
|
||||
Format matches condition evaluator syntax (e.g., "step.status == 'complete'").`,
|
||||
},
|
||||
{
|
||||
Name: "Max",
|
||||
Type: "int",
|
||||
JSONName: "max",
|
||||
Doc: `Max is the maximum iterations for conditional loops.
|
||||
Required when Until is set, to prevent unbounded loops.`,
|
||||
},
|
||||
{
|
||||
Name: "Range",
|
||||
Type: "string",
|
||||
JSONName: "range",
|
||||
Doc: `Range specifies a computed range for iteration.
|
||||
Format: "start..end" where start and end can be:
|
||||
- Integers: "1..10"
|
||||
- Expressions: "1..2^{disks}" (evaluated at cook time)
|
||||
- Variables: "{start}..{count}" (substituted from Vars)
|
||||
Supports: + - * / ^ (power) and parentheses.`,
|
||||
},
|
||||
{
|
||||
Name: "Var",
|
||||
Type: "string",
|
||||
JSONName: "var",
|
||||
Doc: `Var is the variable name exposed to body steps.
|
||||
For Range loops, this is set to the current iteration value.
|
||||
Example: var: "move_num" with range: "1..7" exposes {move_num}=1,2,...,7`,
|
||||
},
|
||||
{
|
||||
Name: "Body",
|
||||
Type: "[]*Step",
|
||||
JSONName: "body",
|
||||
Required: true,
|
||||
Doc: `Body contains the steps to repeat.`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "MapRule",
|
||||
Doc: `MapRule applies an expansion template to all matching steps.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "Select",
|
||||
Type: "string",
|
||||
JSONName: "select",
|
||||
Required: true,
|
||||
Doc: `Select is a glob pattern matching step IDs to expand.
|
||||
Examples: "*.implement", "shiny.*"`,
|
||||
},
|
||||
{
|
||||
Name: "With",
|
||||
Type: "string",
|
||||
JSONName: "with",
|
||||
Required: true,
|
||||
Doc: `With is the name of the expansion formula to apply.`,
|
||||
},
|
||||
{
|
||||
Name: "Vars",
|
||||
Type: "map[string]string",
|
||||
JSONName: "vars",
|
||||
Doc: `Vars are variable overrides for the expansion.`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "OnCompleteSpec",
|
||||
Doc: `OnCompleteSpec defines actions triggered when a step completes.
|
||||
Used for runtime expansion over step output (the for-each construct).
|
||||
|
||||
Example YAML:
|
||||
|
||||
step: survey-workers
|
||||
on_complete:
|
||||
for_each: output.workers
|
||||
bond: mol-worker-arm
|
||||
vars:
|
||||
worker_name: "{item.name}"
|
||||
rig: "{item.rig}"
|
||||
parallel: true`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "ForEach",
|
||||
Type: "string",
|
||||
JSONName: "for_each",
|
||||
Doc: `ForEach is the path to the iterable collection in step output.
|
||||
Format: "output.<field>" or "output.<field>.<nested>"
|
||||
The collection must be an array at runtime.`,
|
||||
},
|
||||
{
|
||||
Name: "Bond",
|
||||
Type: "string",
|
||||
JSONName: "bond",
|
||||
Doc: `Bond is the formula to instantiate for each item.
|
||||
A new molecule is created for each element in the ForEach collection.`,
|
||||
},
|
||||
{
|
||||
Name: "Vars",
|
||||
Type: "map[string]string",
|
||||
JSONName: "vars",
|
||||
Doc: `Vars are variable bindings for each iteration.
|
||||
Supports placeholders:
|
||||
- {item} - the current item value (for primitives)
|
||||
- {item.field} - a field from the current item (for objects)
|
||||
- {index} - the zero-based iteration index`,
|
||||
},
|
||||
{
|
||||
Name: "Parallel",
|
||||
Type: "bool",
|
||||
JSONName: "parallel",
|
||||
Doc: `Parallel runs all bonded molecules concurrently (default behavior).
|
||||
Set to true to make this explicit.`,
|
||||
},
|
||||
{
|
||||
Name: "Sequential",
|
||||
Type: "bool",
|
||||
JSONName: "sequential",
|
||||
Doc: `Sequential runs bonded molecules one at a time.
|
||||
Each molecule starts only after the previous one completes.
|
||||
Mutually exclusive with Parallel.`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "Pointcut",
|
||||
Doc: `Pointcut defines a target pattern for advice application.
|
||||
Used in aspect formulas to specify which steps the advice applies to.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "Glob",
|
||||
Type: "string",
|
||||
JSONName: "glob",
|
||||
Doc: `Glob is a glob pattern to match step IDs.
|
||||
Examples: "*.implement", "shiny.*", "review"`,
|
||||
},
|
||||
{
|
||||
Name: "Type",
|
||||
Type: "string",
|
||||
JSONName: "type",
|
||||
Doc: `Type matches steps by their type field.
|
||||
Examples: "task", "bug", "epic"`,
|
||||
},
|
||||
{
|
||||
Name: "Label",
|
||||
Type: "string",
|
||||
JSONName: "label",
|
||||
Doc: `Label matches steps that have a specific label.`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "Step",
|
||||
Doc: `Step defines a work item to create when the formula is instantiated.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "ID",
|
||||
Type: "string",
|
||||
JSONName: "id",
|
||||
Required: true,
|
||||
Doc: `ID is the unique identifier within this formula.
|
||||
Used for dependency references and bond points.`,
|
||||
},
|
||||
{
|
||||
Name: "Title",
|
||||
Type: "string",
|
||||
JSONName: "title",
|
||||
Required: true,
|
||||
Doc: `Title is the issue title (supports {{variable}} substitution).`,
|
||||
},
|
||||
{
|
||||
Name: "Description",
|
||||
Type: "string",
|
||||
JSONName: "description",
|
||||
Doc: `Description is the issue description (supports substitution).`,
|
||||
},
|
||||
{
|
||||
Name: "Notes",
|
||||
Type: "string",
|
||||
JSONName: "notes",
|
||||
Doc: `Notes are additional notes for the issue (supports substitution).`,
|
||||
},
|
||||
{
|
||||
Name: "Type",
|
||||
Type: "string",
|
||||
JSONName: "type",
|
||||
Doc: `Type is the issue type: task, bug, feature, epic, chore.`,
|
||||
},
|
||||
{
|
||||
Name: "Priority",
|
||||
Type: "*int",
|
||||
JSONName: "priority",
|
||||
Doc: `Priority is the issue priority (0-4).`,
|
||||
},
|
||||
{
|
||||
Name: "Labels",
|
||||
Type: "[]string",
|
||||
JSONName: "labels",
|
||||
Doc: `Labels are applied to the created issue.`,
|
||||
},
|
||||
{
|
||||
Name: "Metadata",
|
||||
Type: "map[string]interface{}",
|
||||
JSONName: "metadata",
|
||||
Doc: `Metadata is carried through to the created issue's Metadata field as
|
||||
JSON. Lets formulas pre-declare keys that downstream tooling can project
|
||||
without a post-pour compose step.`,
|
||||
},
|
||||
{
|
||||
Name: "DependsOn",
|
||||
Type: "[]string",
|
||||
JSONName: "depends_on",
|
||||
Doc: `DependsOn lists step IDs this step blocks on (within the formula).`,
|
||||
},
|
||||
{
|
||||
Name: "Needs",
|
||||
Type: "[]string",
|
||||
JSONName: "needs",
|
||||
Doc: `Needs is a simpler alias for DependsOn - lists sibling step IDs that must complete first.
|
||||
Either Needs or DependsOn can be used; they are merged during cooking.`,
|
||||
},
|
||||
{
|
||||
Name: "WaitsFor",
|
||||
Type: "string",
|
||||
JSONName: "waits_for",
|
||||
Doc: `WaitsFor specifies a fanout gate type for this step.
|
||||
Values: "all-children" (wait for all dynamic children) or "any-children" (wait for first).
|
||||
When set, the cooked issue gets a "gate:<value>" label.`,
|
||||
},
|
||||
{
|
||||
Name: "Assignee",
|
||||
Type: "string",
|
||||
JSONName: "assignee",
|
||||
Doc: `Assignee is the default assignee (supports substitution).`,
|
||||
},
|
||||
{
|
||||
Name: "Expand",
|
||||
Type: "string",
|
||||
JSONName: "expand",
|
||||
Doc: `Expand references an expansion formula to inline here.
|
||||
When set, this step is replaced by the expansion's template steps.
|
||||
See ApplyInlineExpansions in expand.go for implementation.`,
|
||||
},
|
||||
{
|
||||
Name: "ExpandVars",
|
||||
Type: "map[string]string",
|
||||
JSONName: "expand_vars",
|
||||
Doc: `ExpandVars are variable overrides for the expansion.
|
||||
Merged with the expansion formula's default vars during inline expansion.`,
|
||||
},
|
||||
{
|
||||
Name: "Condition",
|
||||
Type: "string",
|
||||
JSONName: "condition",
|
||||
Doc: `Condition makes this step optional based on a variable.
|
||||
Format: "{{var}}" (truthy), "!{{var}}" (negated), "{{var}} == value", "{{var}} != value".
|
||||
Evaluated at cook/pour time via FilterStepsByCondition.`,
|
||||
},
|
||||
{
|
||||
Name: "Children",
|
||||
Type: "[]*Step",
|
||||
JSONName: "children",
|
||||
Doc: `Children are nested steps (for creating epic hierarchies).`,
|
||||
},
|
||||
{
|
||||
Name: "Gate",
|
||||
Type: "*Gate",
|
||||
JSONName: "gate",
|
||||
Doc: `Gate defines an async wait condition for this step.
|
||||
When set, bd cook creates a gate issue that blocks this step.
|
||||
Close the gate issue (bd close bd-xxx.gate-stepid) to unblock.`,
|
||||
},
|
||||
{
|
||||
Name: "Loop",
|
||||
Type: "*LoopSpec",
|
||||
JSONName: "loop",
|
||||
Doc: `Loop defines iteration for this step.
|
||||
When set, the step becomes a container that expands its body.`,
|
||||
},
|
||||
{
|
||||
Name: "OnComplete",
|
||||
Type: "*OnCompleteSpec",
|
||||
JSONName: "on_complete",
|
||||
Doc: `OnComplete defines actions triggered when this step completes.
|
||||
Used for runtime expansion over step output (the for-each construct).`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "VarDef",
|
||||
Doc: `VarDef defines a template variable with optional validation.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "Description",
|
||||
Type: "string",
|
||||
JSONName: "description",
|
||||
Doc: `Description explains what this variable is for.`,
|
||||
},
|
||||
{
|
||||
Name: "Default",
|
||||
Type: "*string",
|
||||
JSONName: "default",
|
||||
Doc: `Default is the value to use if not provided.
|
||||
nil means no default (variable must be provided if referenced).
|
||||
Non-nil (including &"") means the variable has an explicit default.`,
|
||||
},
|
||||
{
|
||||
Name: "Required",
|
||||
Type: "bool",
|
||||
JSONName: "required",
|
||||
Doc: `Required indicates the variable must be provided (no default).`,
|
||||
},
|
||||
{
|
||||
Name: "Enum",
|
||||
Type: "[]string",
|
||||
JSONName: "enum",
|
||||
Doc: `Enum lists the allowed values (if non-empty).`,
|
||||
},
|
||||
{
|
||||
Name: "Pattern",
|
||||
Type: "string",
|
||||
JSONName: "pattern",
|
||||
Doc: `Pattern is a regex pattern the value must match.`,
|
||||
},
|
||||
{
|
||||
Name: "Type",
|
||||
Type: "string",
|
||||
JSONName: "type",
|
||||
Doc: `Type is the expected value type: string (default), int, bool.`,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "WaitsForSpec",
|
||||
Doc: `WaitsForSpec holds the parsed waits_for field.`,
|
||||
Fields: []FieldDoc{
|
||||
{
|
||||
Name: "Gate",
|
||||
Type: "string",
|
||||
JSONName: "Gate",
|
||||
Required: true,
|
||||
Doc: `Gate is the gate type: "all-children" or "any-children"`,
|
||||
},
|
||||
{
|
||||
Name: "SpawnerID",
|
||||
Type: "string",
|
||||
JSONName: "SpawnerID",
|
||||
Required: true,
|
||||
Doc: `SpawnerID is the step ID whose children to wait for.
|
||||
Empty means infer from context (typically first step in needs).`,
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
52
internal/formula/schema_gen_test.go
Normal file
52
internal/formula/schema_gen_test.go
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
package formula_test
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"runtime"
|
||||
"testing"
|
||||
|
||||
"github.com/steveyegge/beads/internal/formula/schemagen"
|
||||
)
|
||||
|
||||
// TestSchemaGenIsCurrent re-runs the schemagen walker over types.go
|
||||
// in-memory and asserts the result byte-equals the committed schema_gen.go.
|
||||
// Failure means someone changed types.go without running `go generate`.
|
||||
func TestSchemaGenIsCurrent(t *testing.T) {
|
||||
_, thisFile, _, ok := runtime.Caller(0)
|
||||
if !ok {
|
||||
t.Fatal("runtime.Caller failed")
|
||||
}
|
||||
pkgDir := filepath.Dir(thisFile)
|
||||
typesPath := filepath.Join(pkgDir, "types.go")
|
||||
committedPath := filepath.Join(pkgDir, "schema_gen.go")
|
||||
|
||||
want, err := os.ReadFile(committedPath)
|
||||
if err != nil {
|
||||
t.Fatalf("read %s: %v", committedPath, err)
|
||||
}
|
||||
|
||||
got, err := schemagen.Generate(typesPath)
|
||||
if err != nil {
|
||||
t.Fatalf("schemagen.Generate: %v", err)
|
||||
}
|
||||
|
||||
if string(got) != string(want) {
|
||||
t.Fatalf("schema_gen.go is stale relative to types.go.\n"+
|
||||
"Run `go generate ./...` from %s and commit the result.\n"+
|
||||
"first diff at byte %d", pkgDir, firstDiff(got, want))
|
||||
}
|
||||
}
|
||||
|
||||
func firstDiff(a, b []byte) int {
|
||||
n := len(a)
|
||||
if len(b) < n {
|
||||
n = len(b)
|
||||
}
|
||||
for i := 0; i < n; i++ {
|
||||
if a[i] != b[i] {
|
||||
return i
|
||||
}
|
||||
}
|
||||
return n
|
||||
}
|
||||
90
internal/formula/schema_test.go
Normal file
90
internal/formula/schema_test.go
Normal file
|
|
@ -0,0 +1,90 @@
|
|||
package formula
|
||||
|
||||
import "testing"
|
||||
|
||||
func TestPrimitiveByName_ExactBeatsSuffixStrip(t *testing.T) {
|
||||
// "gate" must resolve to Gate (the field-bearing struct), not GateRule.
|
||||
// Same logic for any other Foo / FooRule / FooSpec collision.
|
||||
cases := []struct {
|
||||
input string
|
||||
want string
|
||||
}{
|
||||
{"Gate", "Gate"},
|
||||
{"gate", "Gate"},
|
||||
{"gaterule", "GateRule"},
|
||||
{"gate_rule", "GateRule"},
|
||||
}
|
||||
for _, c := range cases {
|
||||
got := PrimitiveByName(c.input)
|
||||
if got == nil {
|
||||
t.Errorf("PrimitiveByName(%q) = nil, want %s", c.input, c.want)
|
||||
continue
|
||||
}
|
||||
if got.Name != c.want {
|
||||
t.Errorf("PrimitiveByName(%q) = %s, want %s", c.input, got.Name, c.want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestPrimitiveByName_SuffixStripFallback(t *testing.T) {
|
||||
cases := []struct {
|
||||
input string
|
||||
want string
|
||||
}{
|
||||
{"loop", "LoopSpec"},
|
||||
{"Loop", "LoopSpec"},
|
||||
{"loop_spec", "LoopSpec"},
|
||||
{"on_complete", "OnCompleteSpec"},
|
||||
{"OnComplete", "OnCompleteSpec"},
|
||||
{"branch", "BranchRule"},
|
||||
{"compose", "ComposeRules"},
|
||||
{"map", "MapRule"},
|
||||
{"expand", "ExpandRule"},
|
||||
{"advice", "AdviceRule"},
|
||||
{"waits_for", "WaitsForSpec"},
|
||||
}
|
||||
for _, c := range cases {
|
||||
got := PrimitiveByName(c.input)
|
||||
if got == nil {
|
||||
t.Errorf("PrimitiveByName(%q) = nil, want %s", c.input, c.want)
|
||||
continue
|
||||
}
|
||||
if got.Name != c.want {
|
||||
t.Errorf("PrimitiveByName(%q) = %s, want %s", c.input, got.Name, c.want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestPrimitiveByName_Unknown(t *testing.T) {
|
||||
for _, in := range []string{"", "bogus", "thing-that-does-not-exist", "step!!!"} {
|
||||
if got := PrimitiveByName(in); got != nil {
|
||||
t.Errorf("PrimitiveByName(%q) = %s, want nil", in, got.Name)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestPrimitivesIndex_NonEmpty(t *testing.T) {
|
||||
if len(Primitives) == 0 {
|
||||
t.Fatal("Primitives is empty; did go generate run?")
|
||||
}
|
||||
// Spot-check a few that should always be present.
|
||||
for _, name := range []string{"Formula", "Step", "LoopSpec", "OnCompleteSpec"} {
|
||||
if PrimitiveByName(name) == nil {
|
||||
t.Errorf("expected %s in Primitives index", name)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestPrimitivesIndex_StepExcludesSourceFields(t *testing.T) {
|
||||
// Step.SourceFormula and Step.SourceLocation are tagged json:"-"
|
||||
// and must never appear in the public schema.
|
||||
step := PrimitiveByName("Step")
|
||||
if step == nil {
|
||||
t.Fatal("Step missing from Primitives")
|
||||
}
|
||||
for _, f := range step.Fields {
|
||||
if f.Name == "SourceFormula" || f.Name == "SourceLocation" {
|
||||
t.Errorf("Step exposes internal field %s; json:\"-\" fields must be filtered", f.Name)
|
||||
}
|
||||
}
|
||||
}
|
||||
291
internal/formula/schemagen/schemagen.go
Normal file
291
internal/formula/schemagen/schemagen.go
Normal file
|
|
@ -0,0 +1,291 @@
|
|||
// Package schemagen walks an internal/formula types.go file and produces
|
||||
// the body of internal/formula/schema_gen.go (a `var Primitives` index of
|
||||
// every exported struct). The package is consumed both by the standalone
|
||||
// generator binary in cmd/schemagen and by the TestSchemaGenIsCurrent test
|
||||
// in internal/formula.
|
||||
package schemagen
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"fmt"
|
||||
"go/ast"
|
||||
"go/format"
|
||||
"go/parser"
|
||||
"go/printer"
|
||||
"go/token"
|
||||
"sort"
|
||||
"strconv"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// Primitive is the in-memory representation of one PrimitiveDoc. Kept
|
||||
// distinct from formula.PrimitiveDoc to avoid an import cycle: this package
|
||||
// generates the source that defines formula.Primitives.
|
||||
type Primitive struct {
|
||||
Name string
|
||||
Doc string
|
||||
Fields []Field
|
||||
}
|
||||
|
||||
// Field is the in-memory representation of one FieldDoc.
|
||||
type Field struct {
|
||||
Name string
|
||||
Type string
|
||||
JSONName string
|
||||
TOMLName string
|
||||
Required bool
|
||||
Doc string
|
||||
}
|
||||
|
||||
// Generate parses typesPath and returns gofmt'd source for schema_gen.go.
|
||||
// The output is deterministic given the same input.
|
||||
func Generate(typesPath string) ([]byte, error) {
|
||||
prims, err := Parse(typesPath)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return Render(prims)
|
||||
}
|
||||
|
||||
// Parse extracts every exported struct in typesPath, sorted by name.
|
||||
func Parse(typesPath string) ([]Primitive, error) {
|
||||
fset := token.NewFileSet()
|
||||
file, err := parser.ParseFile(fset, typesPath, nil, parser.ParseComments)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("parse %s: %w", typesPath, err)
|
||||
}
|
||||
|
||||
var prims []Primitive
|
||||
for _, decl := range file.Decls {
|
||||
gen, ok := decl.(*ast.GenDecl)
|
||||
if !ok || gen.Tok != token.TYPE {
|
||||
continue
|
||||
}
|
||||
for _, spec := range gen.Specs {
|
||||
ts, ok := spec.(*ast.TypeSpec)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
if !ts.Name.IsExported() {
|
||||
continue
|
||||
}
|
||||
st, ok := ts.Type.(*ast.StructType)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
doc := extractDoc(ts.Doc, gen.Doc)
|
||||
fields := collectFields(fset, st)
|
||||
prims = append(prims, Primitive{
|
||||
Name: ts.Name.Name,
|
||||
Doc: doc,
|
||||
Fields: fields,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
sort.Slice(prims, func(i, j int) bool {
|
||||
return prims[i].Name < prims[j].Name
|
||||
})
|
||||
return prims, nil
|
||||
}
|
||||
|
||||
func collectFields(fset *token.FileSet, st *ast.StructType) []Field {
|
||||
if st.Fields == nil {
|
||||
return nil
|
||||
}
|
||||
var fields []Field
|
||||
for _, f := range st.Fields.List {
|
||||
jsonTag, tomlTag := extractTags(f.Tag)
|
||||
// Skip fields explicitly excluded from JSON serialization — these
|
||||
// are internal implementation details (e.g. Step.SourceFormula).
|
||||
if jsonTag.name == "-" {
|
||||
continue
|
||||
}
|
||||
typeStr := renderType(fset, f.Type)
|
||||
doc := extractDoc(f.Doc, nil)
|
||||
for _, name := range f.Names {
|
||||
if !name.IsExported() {
|
||||
continue
|
||||
}
|
||||
jsonName := jsonTag.name
|
||||
if jsonName == "" {
|
||||
jsonName = name.Name
|
||||
}
|
||||
tomlName := tomlTag.name
|
||||
if tomlName == "" {
|
||||
tomlName = jsonName
|
||||
}
|
||||
required := !jsonTag.omitempty && jsonTag.name != "-"
|
||||
fields = append(fields, Field{
|
||||
Name: name.Name,
|
||||
Type: typeStr,
|
||||
JSONName: jsonName,
|
||||
TOMLName: tomlName,
|
||||
Required: required,
|
||||
Doc: doc,
|
||||
})
|
||||
}
|
||||
}
|
||||
return fields
|
||||
}
|
||||
|
||||
type structTag struct {
|
||||
name string
|
||||
omitempty bool
|
||||
}
|
||||
|
||||
func extractTags(tag *ast.BasicLit) (jsonTag, tomlTag structTag) {
|
||||
if tag == nil {
|
||||
return
|
||||
}
|
||||
raw, err := strconv.Unquote(tag.Value)
|
||||
if err != nil {
|
||||
return
|
||||
}
|
||||
st := newReflectStructTag(raw)
|
||||
if v, ok := st.lookup("json"); ok {
|
||||
jsonTag = parseTagValue(v)
|
||||
}
|
||||
if v, ok := st.lookup("toml"); ok {
|
||||
tomlTag = parseTagValue(v)
|
||||
}
|
||||
return
|
||||
}
|
||||
|
||||
func parseTagValue(v string) structTag {
|
||||
parts := strings.Split(v, ",")
|
||||
t := structTag{name: parts[0]}
|
||||
for _, p := range parts[1:] {
|
||||
if p == "omitempty" {
|
||||
t.omitempty = true
|
||||
}
|
||||
}
|
||||
return t
|
||||
}
|
||||
|
||||
// reflectStructTag is a tiny stand-in for reflect.StructTag.Lookup that
|
||||
// avoids depending on reflect at codegen time. Behavior matches the stdlib:
|
||||
// keys are space-separated, values are double-quoted.
|
||||
type reflectStructTag string
|
||||
|
||||
func newReflectStructTag(s string) reflectStructTag { return reflectStructTag(s) }
|
||||
|
||||
func (t reflectStructTag) lookup(key string) (string, bool) {
|
||||
tag := string(t)
|
||||
for tag != "" {
|
||||
i := 0
|
||||
for i < len(tag) && tag[i] == ' ' {
|
||||
i++
|
||||
}
|
||||
tag = tag[i:]
|
||||
if tag == "" {
|
||||
break
|
||||
}
|
||||
i = 0
|
||||
for i < len(tag) && tag[i] > ' ' && tag[i] != ':' && tag[i] != '"' {
|
||||
i++
|
||||
}
|
||||
if i == 0 || i+1 >= len(tag) || tag[i] != ':' || tag[i+1] != '"' {
|
||||
break
|
||||
}
|
||||
name := tag[:i]
|
||||
tag = tag[i+1:]
|
||||
i = 1
|
||||
for i < len(tag) && tag[i] != '"' {
|
||||
if tag[i] == '\\' {
|
||||
i++
|
||||
}
|
||||
i++
|
||||
}
|
||||
if i >= len(tag) {
|
||||
break
|
||||
}
|
||||
quoted := tag[:i+1]
|
||||
tag = tag[i+1:]
|
||||
if name == key {
|
||||
value, err := strconv.Unquote(quoted)
|
||||
if err != nil {
|
||||
return "", false
|
||||
}
|
||||
return value, true
|
||||
}
|
||||
}
|
||||
return "", false
|
||||
}
|
||||
|
||||
func renderType(fset *token.FileSet, expr ast.Expr) string {
|
||||
var buf bytes.Buffer
|
||||
cfg := printer.Config{Mode: printer.RawFormat, Tabwidth: 8}
|
||||
if err := cfg.Fprint(&buf, fset, expr); err != nil {
|
||||
return fmt.Sprintf("<unprintable: %v>", err)
|
||||
}
|
||||
return buf.String()
|
||||
}
|
||||
|
||||
func extractDoc(primary, fallback *ast.CommentGroup) string {
|
||||
g := primary
|
||||
if g == nil {
|
||||
g = fallback
|
||||
}
|
||||
if g == nil {
|
||||
return ""
|
||||
}
|
||||
return strings.TrimRight(g.Text(), "\n")
|
||||
}
|
||||
|
||||
// Render emits a gofmt'd schema_gen.go body from prims.
|
||||
func Render(prims []Primitive) ([]byte, error) {
|
||||
var buf bytes.Buffer
|
||||
buf.WriteString("// Code generated by internal/formula/cmd/schemagen. DO NOT EDIT.\n")
|
||||
buf.WriteString("\n")
|
||||
buf.WriteString("package formula\n")
|
||||
buf.WriteString("\n")
|
||||
buf.WriteString("// Primitives is the discoverability index of every exported struct in\n")
|
||||
buf.WriteString("// types.go. Surfaced via `bd formula schema`. Regenerate with `go generate ./...`.\n")
|
||||
buf.WriteString("var Primitives = []PrimitiveDoc{\n")
|
||||
for _, p := range prims {
|
||||
buf.WriteString("\t{\n")
|
||||
fmt.Fprintf(&buf, "\t\tName: %q,\n", p.Name)
|
||||
if p.Doc != "" {
|
||||
fmt.Fprintf(&buf, "\t\tDoc: %s,\n", goStringLit(p.Doc))
|
||||
}
|
||||
if len(p.Fields) > 0 {
|
||||
buf.WriteString("\t\tFields: []FieldDoc{\n")
|
||||
for _, f := range p.Fields {
|
||||
buf.WriteString("\t\t\t{\n")
|
||||
fmt.Fprintf(&buf, "\t\t\t\tName: %q,\n", f.Name)
|
||||
fmt.Fprintf(&buf, "\t\t\t\tType: %q,\n", f.Type)
|
||||
fmt.Fprintf(&buf, "\t\t\t\tJSONName: %q,\n", f.JSONName)
|
||||
if f.TOMLName != "" && f.TOMLName != f.JSONName {
|
||||
fmt.Fprintf(&buf, "\t\t\t\tTOMLName: %q,\n", f.TOMLName)
|
||||
}
|
||||
if f.Required {
|
||||
buf.WriteString("\t\t\t\tRequired: true,\n")
|
||||
}
|
||||
if f.Doc != "" {
|
||||
fmt.Fprintf(&buf, "\t\t\t\tDoc: %s,\n", goStringLit(f.Doc))
|
||||
}
|
||||
buf.WriteString("\t\t\t},\n")
|
||||
}
|
||||
buf.WriteString("\t\t},\n")
|
||||
}
|
||||
buf.WriteString("\t},\n")
|
||||
}
|
||||
buf.WriteString("}\n")
|
||||
return format.Source(buf.Bytes())
|
||||
}
|
||||
|
||||
// goStringLit emits a Go string literal — backtick-quoted when the content
|
||||
// is "clean" (no backticks, no control chars except newline), otherwise
|
||||
// double-quoted via strconv.Quote so escapes survive.
|
||||
func goStringLit(s string) string {
|
||||
if strings.ContainsRune(s, '`') {
|
||||
return strconv.Quote(s)
|
||||
}
|
||||
for _, r := range s {
|
||||
if r < 0x20 && r != '\n' && r != '\t' {
|
||||
return strconv.Quote(s)
|
||||
}
|
||||
}
|
||||
return "`" + s + "`"
|
||||
}
|
||||
|
|
@ -22,8 +22,16 @@ Search paths (in order):
|
|||
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
|
||||
|
||||
Commands:
|
||||
list List available formulas from all search paths
|
||||
show Show formula details, steps, and composition rules
|
||||
list List available formulas from all search paths
|
||||
show Show formula details, steps, and composition rules
|
||||
schema Show the formula schema index (alias: primitives)
|
||||
|
||||
Discovering primitives:
|
||||
bd formula schema # list every declared formula struct
|
||||
bd formula schema loop # show LoopSpec fields, types, and tags
|
||||
bd formula primitives gate # alias; same handler as 'schema'
|
||||
examples/formulas/primitives/ # curated, smoke-tested wired fixtures
|
||||
website/docs/workflows/formulas.md # narrative reference
|
||||
|
||||
```
|
||||
bd formula [flags]
|
||||
|
|
@ -72,6 +80,9 @@ Search paths (in order of priority):
|
|||
|
||||
Formulas in earlier paths shadow those with the same name in later paths.
|
||||
|
||||
To list the declared formula schema structs an agent can write inside a .formula.toml,
|
||||
use 'bd formula schema' (alias: 'bd formula primitives').
|
||||
|
||||
Examples:
|
||||
bd formula list
|
||||
bd formula list --json
|
||||
|
|
@ -88,6 +99,30 @@ bd formula list [flags]
|
|||
--type string Filter by type (workflow, expansion, aspect, convoy)
|
||||
```
|
||||
|
||||
### bd formula schema
|
||||
|
||||
Show the formula schema index: every exported struct declared
|
||||
in a .formula.toml/.formula.json, with field names, types, and tags.
|
||||
|
||||
The index is generated from internal/formula/types.go via go:generate; the
|
||||
struct definitions are the source of truth, so this list cannot drift. It is
|
||||
structural reference, not proof that every declared runtime behavior is wired.
|
||||
|
||||
Examples:
|
||||
bd formula schema # list every declared schema struct
|
||||
bd formula schema loop # show LoopSpec fields
|
||||
bd formula primitives gate # alias; shows Gate fields
|
||||
bd formula schema --json # machine-readable index
|
||||
|
||||
Curated smoke-tested fixtures for wired primitives live in
|
||||
examples/formulas/primitives/ (with a smoke harness that proves they work).
|
||||
|
||||
```
|
||||
bd formula schema [primitive]
|
||||
```
|
||||
|
||||
**Aliases:** primitives
|
||||
|
||||
### bd formula show
|
||||
|
||||
Show detailed information about a formula.
|
||||
|
|
@ -99,6 +134,9 @@ Displays:
|
|||
- Composition rules (extends, aspects, expansions)
|
||||
- Bond points for external composition
|
||||
|
||||
To inspect the structure of an individual primitive (e.g. LoopSpec, Gate)
|
||||
rather than a user-authored formula, use 'bd formula schema <primitive>'.
|
||||
|
||||
Examples:
|
||||
bd formula show shiny
|
||||
bd formula show rule-of-five
|
||||
|
|
|
|||
|
|
@ -117,16 +117,10 @@ position = "before"
|
|||
|
||||
### Hooks
|
||||
|
||||
Execute actions on step completion:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "build"
|
||||
title = "Build project"
|
||||
|
||||
[steps.on_complete]
|
||||
run = "make build"
|
||||
```
|
||||
Step-completion hooks are not currently exposed as runnable formula
|
||||
actions. The historical `on_complete.run` example was invalid: `run` is
|
||||
not a formula field, and `on_complete` runtime expansion is tracked
|
||||
separately until it is wired end to end.
|
||||
|
||||
### Pinning Work
|
||||
|
||||
|
|
|
|||
|
|
@ -22,8 +22,16 @@ Search paths (in order):
|
|||
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
|
||||
|
||||
Commands:
|
||||
list List available formulas from all search paths
|
||||
show Show formula details, steps, and composition rules
|
||||
list List available formulas from all search paths
|
||||
show Show formula details, steps, and composition rules
|
||||
schema Show the formula schema index (alias: primitives)
|
||||
|
||||
Discovering primitives:
|
||||
bd formula schema # list every declared formula struct
|
||||
bd formula schema loop # show LoopSpec fields, types, and tags
|
||||
bd formula primitives gate # alias; same handler as 'schema'
|
||||
examples/formulas/primitives/ # curated, smoke-tested wired fixtures
|
||||
website/docs/workflows/formulas.md # narrative reference
|
||||
|
||||
```
|
||||
bd formula
|
||||
|
|
@ -72,6 +80,9 @@ Search paths (in order of priority):
|
|||
|
||||
Formulas in earlier paths shadow those with the same name in later paths.
|
||||
|
||||
To list the declared formula schema structs an agent can write inside a .formula.toml,
|
||||
use 'bd formula schema' (alias: 'bd formula primitives').
|
||||
|
||||
Examples:
|
||||
bd formula list
|
||||
bd formula list --json
|
||||
|
|
@ -88,6 +99,30 @@ bd formula list [flags]
|
|||
--type string Filter by type (workflow, expansion, aspect, convoy)
|
||||
```
|
||||
|
||||
### bd formula schema
|
||||
|
||||
Show the formula schema index: every exported struct declared
|
||||
in a .formula.toml/.formula.json, with field names, types, and tags.
|
||||
|
||||
The index is generated from internal/formula/types.go via go:generate; the
|
||||
struct definitions are the source of truth, so this list cannot drift. It is
|
||||
structural reference, not proof that every declared runtime behavior is wired.
|
||||
|
||||
Examples:
|
||||
bd formula schema # list every declared schema struct
|
||||
bd formula schema loop # show LoopSpec fields
|
||||
bd formula primitives gate # alias; shows Gate fields
|
||||
bd formula schema --json # machine-readable index
|
||||
|
||||
Curated smoke-tested fixtures for wired primitives live in
|
||||
examples/formulas/primitives/ (with a smoke harness that proves they work).
|
||||
|
||||
```
|
||||
bd formula schema [primitive]
|
||||
```
|
||||
|
||||
**Aliases:** primitives
|
||||
|
||||
### bd formula show
|
||||
|
||||
Show detailed information about a formula.
|
||||
|
|
@ -99,6 +134,9 @@ Displays:
|
|||
- Composition rules (extends, aspects, expansions)
|
||||
- Bond points for external composition
|
||||
|
||||
To inspect the structure of an individual primitive (e.g. LoopSpec, Gate)
|
||||
rather than a user-authored formula, use 'bd formula schema <primitive>'.
|
||||
|
||||
Examples:
|
||||
bd formula show shiny
|
||||
bd formula show rule-of-five
|
||||
|
|
|
|||
|
|
@ -256,24 +256,10 @@ The `max` field is required for `until` loops to prevent unbounded iteration.
|
|||
|
||||
## Runtime Expansion (on_complete)
|
||||
|
||||
Steps can trigger dynamic work when they complete using `on_complete` with `for_each`:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "survey"
|
||||
title = "Survey available workers"
|
||||
|
||||
[steps.on_complete]
|
||||
for_each = "output.workers"
|
||||
bond = "worker-arm"
|
||||
parallel = true
|
||||
|
||||
[steps.on_complete.vars]
|
||||
worker_name = "{item.name}"
|
||||
rig = "{item.rig}"
|
||||
```
|
||||
|
||||
This creates a new molecule from the `worker-arm` formula for each item in the `output.workers` array. Use `sequential = true` instead of `parallel` to run them one at a time.
|
||||
`on_complete` is present in the formula schema, but runtime expansion is
|
||||
not wired end to end in the current release. Do not author new formulas
|
||||
that depend on `on_complete` creating follow-up molecules until the
|
||||
runtime implementation ships with a smoke-tested primitive example.
|
||||
|
||||
## Formula Inheritance
|
||||
|
||||
|
|
|
|||
|
|
@ -117,16 +117,10 @@ position = "before"
|
|||
|
||||
### Hooks
|
||||
|
||||
Execute actions on step completion:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "build"
|
||||
title = "Build project"
|
||||
|
||||
[steps.on_complete]
|
||||
run = "make build"
|
||||
```
|
||||
Step-completion hooks are not currently exposed as runnable formula
|
||||
actions. The historical `on_complete.run` example was invalid: `run` is
|
||||
not a formula field, and `on_complete` runtime expansion is tracked
|
||||
separately until it is wired end to end.
|
||||
|
||||
### Pinning Work
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue