feat(eda): playbook.Load findings name the offending action, when or args line

This commit is contained in:
sam committed 2026-09-23 22:42:14 +10:00
1 parent 63be83e0cf
commit 068d89ebb4
7 files changed
+121 -24

No files matched your search

+1 -1
View File
@@ -232,7 +232,7 @@
"url": "/dev/prds/eda-playbook-engine/",
"title": "EDA playbook engine -- design",
"section": "PRDs",
"body": "# EDA playbook engine -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Beads epic:** `archie-core-t2db`\n\n## Problem\n\n\"Which workflow runs for which trigger\" is hardcoded Go: a literal\nlabel vocabulary (`workintake.labelKinds`) and a literal label-\u003eworkflow map\n(`workflow/routing.go`), extended only by adding a Go case or shipping a\nskill whose `metadata.archie.workflow` overrides one *named* built-in\nworkflow. Extending the system to a new trigger, a new action, or a new\nevent source means a feature branch, a code change in a hardcoded\npath, and new Go tests -- for every addition. That is the barrier this\ndocument exists to remove.\n\nThe goal: triggers, the actions they run, and the\nconditions that connect them should be **drop-in and load**, not **drop-in\nand touch application code**. Yaegi-evaluated Go is the unit of imperative\n\"do a thing\" logic; YAML playbooks are pure orchestration data -- no logic,\njust \"on this event, with this data, call these actions, in this order,\nunder these conditions.\" The daemon's event coordinator doesn't know what a\n`bugfix` or `image-gen` action does, it resolves the name against a\nregistry and pipes typed data through.\n\nThis is explicitly **not** scoped to code-generation workflows. A playbook\naction can be any registered capability -- run a codegen workflow, send a\nmessage on a channel, open something on a forge, generate an image -- so\nlong as it's implemented behind one of the typed engine families below.\n\n## Relationship to existing decisions\n\n- `docs/prds/event-sources-and-reactions.md` ruled\n that reactions in the two epics it covers are **producer-only** (no veto,\n no mutation of in-flight work) and explicitly rejected a single generic\n `Source` interface as \"the untyped-hook shape the plugin engine rule\n exists to prevent.\" **This document extends that scope**: playbooks can\n dispatch to multiple typed action kinds, not just \"produce a\n `TaskEnvelope`.\" It does not relitigate producer-only-ness (still no\n veto/mutation of in-flight work here) and it does not introduce one\n generic interface -- see \"Typed positions, not one generic hook\" below,\n which is how it stays compliant with the plugin engine rule instead of\n reopening that document's #4.\n- `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`\n governs every extension point\n introduced here. Every position below is a typed domain contract with an\n owning registry, not a generic callback map. This is a hard constraint,\n confirmed against the existing rule text before writing this doc.\n- Yaegi is already a proven in-process extension mechanism\n (`internal/plugin`, `internal/domain/workflow/wfeval/yaegi.go`,\n `internal/gate/gateeval/yaegi.go`, `internal/skill/plugin.go`) -- this\n design generalizes its existing role, it does not introduce a new\n execution mechanism.\n- `internal/domain/workflow/skillbuild.BuildRegistry` already composes a\n `workflow.Registry` from a skills catalog, plugin-defined overriding\n built-in. The playbook loader described here supersedes label routing\n specifically; it does not replace `skillbuild`'s workflow-composition role,\n it becomes an additional input the daemon composes at startup.\n- Webhook event intake is a separate design. This\n document defines the router each webhook-sourced event should be able to\n reach; it does not redesign webhook receipt itself.\n\n## Shape: four logic positions, each a typed engine family\n\nEvery entrypoint kind (mechanism, action, loop, schedule, route, trigger) is itself a schema emitter: defining a new kind produces the\ngenerated contract downstream tooling consumes. The kinds slot into a fixed\nhierarchy of logic positions:\n\n```\nWorkflow -\u003e Module -\u003e Channel (telegram/whatsapp/email/...)\n -\u003e Forge (GitHub/Gitea/GitLab/...)\n```\n\nEach position is its own typed engine family per the plugin engine rule:\nidentity + capability-specific operations, an owning `Registry`/`Manager`,\nexplicit lifecycle where the implementation owns resources, narrow host\naccess. Concretely:\n\n- **Workflow** -- already exists (`internal/domain/workflow`). A playbook\n action of kind `workflow` invokes a registered `workflow.Registry` entry\n by name, unchanged from the existing execution path.\n- **Module** -- the new general-purpose action position. A `Module` is a\n Yaegi-evaluated implementation of a generated interface (args in, typed\n result out) for one declared action kind (e.g. `image-gen`, `notify`,\n `open-pr-comment`). This is the position that makes actions \"not\n restricted to code-generation.\" Full design (schema-per-kind, the\n registry shape, the trust boundary, the recommended first slice):\n `docs/prds/module-position.md`.\n- **Channel** -- already exists as `channels.Channel` (telegram, email,\n webhook). A playbook action of kind `channel` sends through Line truncated
"body": "# EDA playbook engine -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Beads epic:** `archie-core-t2db`\n\n## Problem\n\n\"Which workflow runs for which trigger\" is hardcoded Go: a literal\nlabel vocabulary (`workintake.labelKinds`) and a literal label-\u003eworkflow map\n(`workflow/routing.go`), extended only by adding a Go case or shipping a\nskill whose `metadata.archie.workflow` overrides one *named* built-in\nworkflow. Extending the system to a new trigger, a new action, or a new\nevent source means a feature branch, a code change in a hardcoded\npath, and new Go tests -- for every addition. That is the barrier this\ndocument exists to remove.\n\nThe goal: triggers, the actions they run, and the\nconditions that connect them should be **drop-in and load**, not **drop-in\nand touch application code**. Yaegi-evaluated Go is the unit of imperative\n\"do a thing\" logic; YAML playbooks are pure orchestration data -- no logic,\njust \"on this event, with this data, call these actions, in this order,\nunder these conditions.\" The daemon's event coordinator doesn't know what a\n`bugfix` or `image-gen` action does, it resolves the name against a\nregistry and pipes typed data through.\n\nThis is explicitly **not** scoped to code-generation workflows. A playbook\naction can be any registered capability -- run a codegen workflow, send a\nmessage on a channel, open something on a forge, generate an image -- so\nlong as it's implemented behind one of the typed engine families below.\n\n## Relationship to existing decisions\n\n- `docs/prds/event-sources-and-reactions.md` ruled\n that reactions in the two epics it covers are **producer-only** (no veto,\n no mutation of in-flight work) and explicitly rejected a single generic\n `Source` interface as \"the untyped-hook shape the plugin engine rule\n exists to prevent.\" **This document extends that scope**: playbooks can\n dispatch to multiple typed action kinds, not just \"produce a\n `TaskEnvelope`.\" It does not relitigate producer-only-ness (still no\n veto/mutation of in-flight work here) and it does not introduce one\n generic interface -- see \"Typed positions, not one generic hook\" below,\n which is how it stays compliant with the plugin engine rule instead of\n reopening that document's #4.\n- `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`\n governs every extension point\n introduced here. Every position below is a typed domain contract with an\n owning registry, not a generic callback map. This is a hard constraint,\n confirmed against the existing rule text before writing this doc.\n- Yaegi is already a proven in-process extension mechanism\n (`internal/plugin`, `internal/domain/workflow/wfeval/yaegi.go`,\n `internal/gate/gateeval/yaegi.go`, `internal/skill/plugin.go`) -- this\n design generalizes its existing role, it does not introduce a new\n execution mechanism.\n- `internal/domain/workflow/skillbuild.BuildRegistry` already composes a\n `workflow.Registry` from a skills catalog, plugin-defined overriding\n built-in. The playbook loader described here supersedes label routing\n specifically; it does not replace `skillbuild`'s workflow-composition role,\n it becomes an additional input the daemon composes at startup.\n- Webhook event intake is a separate design. This\n document defines the router each webhook-sourced event should be able to\n reach; it does not redesign webhook receipt itself.\n\n## Shape: four logic positions, each a typed engine family\n\nEvery entrypoint kind (mechanism, action, loop, schedule, route, trigger) is itself a schema emitter: defining a new kind produces the\ngenerated contract downstream tooling consumes. The kinds slot into a fixed\nhierarchy of logic positions:\n\n```\nWorkflow -\u003e Module -\u003e Channel (telegram/whatsapp/email/...)\n -\u003e Forge (GitHub/Gitea/GitLab/...)\n```\n\nEach position is its own typed engine family per the plugin engine rule:\nidentity + capability-specific operations, an owning `Registry`/`Manager`,\nexplicit lifecycle where the implementation owns resources, narrow host\naccess. Concretely:\n\n- **Workflow** -- already exists (`internal/domain/workflow`). A playbook\n action of kind `workflow` invokes a registered `workflow.Registry` entry\n by name, unchanged from the existing execution path.\n- **Module** -- the new general-purpose action position. A `Module` is a\n Yaegi-evaluated implementation of a generated interface (args in, typed\n result out) for one declared action kind (e.g. `image-gen`, `notify`,\n `open-pr-comment`). This is the position that makes actions \"not\n restricted to code-generation.\" Full design (schema-per-kind, the\n registry shape, the trust boundary, the recommended first slice):\n `docs/prds/module-position.md`.\n- **Channel** -- already exists as `channels.Channel` (telegram, email,\n webhook). A playbook action of kind `channel` sends through Line truncated
},
{
"url": "/dev/prds/embedded-nats/",
+2 -2
View File
@@ -184,8 +184,8 @@ a case that should just be visible and fixed by a human. Instead:
opened or saved it lints the file's saved directory with the loader the
daemon runs for it (a file with a top-level `trigger` key is an EDA
playbook, anything else a routing binding file) and publishes the findings
for that file as error diagnostics. A routing finding sits on its key's
line; an EDA finding carries no line yet and sits on the first line.
for that file as error diagnostics, each on the line of the key, action,
`when` or args key it names; a file-level finding sits on the first line.
Unsaved edits are not validated. Hover and completion are later additions.
The startup log-and-refuse path exists for what the linter/LSP structurally
+1 -1
View File
@@ -81,7 +81,7 @@ func (s *server) DidClose(ctx context.Context, p *protocol.DidCloseTextDocumentP
// diagnose lints the directory holding u's file and returns the findings that
// belong to that file: a finding naming another file of the directory belongs
// there, and one naming this file without a line (an EDA load error) goes on
// there, and one naming this file without a line (a file-level error) goes on
// its first line.
func diagnose(u uri.URI) *protocol.PublishDiagnosticsParams {
out := &protocol.PublishDiagnosticsParams{URI: u, Diagnostics: []protocol.Diagnostic{}}
+2 -2
View File
@@ -81,10 +81,10 @@ func TestServePublishesDiagnostics(t *testing.T) {
wantLine: 1,
},
{
name: "eda playbook finding without a line",
name: "eda playbook finding on its action line",
files: map[string]string{"pb.yaml": "trigger:\n kind: bug\nactions:\n - position: module\n kind: nope\n"},
open: "pb.yaml",
wantLine: 0,
wantLine: 3,
},
}
for _, tt := range tests {
@@ -0,0 +1,59 @@
package playbook
import (
"path/filepath"
"strconv"
"strings"
"testing"
)
// An action-level finding names the line of the offending action, `when`
// or args key, compiler-style, so the lint tool and the language server can
// point at it.
func TestLoadFindingsCarryTheOffendingLine(t *testing.T) {
const head = "trigger:\n kind: bug\nactions:\n"
tests := []struct {
name string
actions string
line int
}{
{
name: "unknown kind on the second action",
actions: " - position: module\n kind: log\n - position: module\n kind: nope\n",
line: 6,
},
{
name: "when that does not compile",
actions: " - position: module\n kind: log\n when: 'event.x =='\n",
line: 6,
},
{
name: "args value of the wrong type",
actions: " - position: module\n kind: log\n args:\n level: '\"info\"'\n message: '123'\n",
line: 8,
},
{
name: "args key the kind does not declare",
actions: " - position: module\n kind: log\n args:\n mesage: '\"x\"'\n",
line: 7,
},
{
name: "workflow action naming no workflow",
actions: " - position: workflow\n when: 'true'\n",
line: 4,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
dir := t.TempDir()
path := writeFile(t, dir, "pb.yaml", head+tt.actions)
_, err := Load(dir, testSchemas(t))
if err == nil {
t.Fatal("Load = nil, want a finding")
}
if want := filepath.Clean(path) + ":" + strconv.Itoa(tt.line) + ":"; !strings.Contains(err.Error(), want) {
t.Fatalf("Load error = %q, want it to name %q", err, want)
}
})
}
}
+54 -16
View File
@@ -140,6 +140,44 @@ type rawAction struct {
Kind string `yaml:"kind"`
When string `yaml:"when"`
Args map[string]string `yaml:"args"`
// Source lines, so a finding names where the author wrote it: the
// action's first line, its `when` key, and each args key.
line int
whenLine int
argLines map[string]int
}
// UnmarshalYAML decodes the action as plain data and records its source
// lines.
func (a *rawAction) UnmarshalYAML(n *yaml.Node) error {
type plain rawAction
if err := n.Decode((*plain)(a)); err != nil {
return err
}
a.line = n.Line
for i := 0; i+1 < len(n.Content); i += 2 {
key, val := n.Content[i], n.Content[i+1]
switch key.Value {
case "when":
a.whenLine = key.Line
case "args":
a.argLines = make(map[string]int, len(val.Content)/2)
for j := 0; j+1 < len(val.Content); j += 2 {
a.argLines[val.Content[j].Value] = val.Content[j].Line
}
}
}
return nil
}
// at is path:line, the compiler-style location a finding leads with; a zero
// line (a hand-built action) leaves the bare path.
func at(path string, line int) string {
if line == 0 {
return path
}
return fmt.Sprintf("%s:%d", path, line)
}
// Module action ids are stricter than workflow ids because they must also be
@@ -294,14 +332,14 @@ func compileActions(path string, raw []rawAction, schemas KindSchemas) ([]Action
if len(raw) == 1 && strings.TrimSpace(a.Workflow) != "" {
pos = "workflow"
} else {
return nil, fmt.Errorf("playbook %s: action %d must declare a position (%q or %q)", path, i+1, "workflow", "module")
return nil, fmt.Errorf("playbook %s: action %d must declare a position (%q or %q)", at(path, a.line), i+1, "workflow", "module")
}
}
if pos != "workflow" && pos != "module" {
return nil, fmt.Errorf("playbook %s: action %d position %q is not supported (want %q or %q)", path, i+1, pos, "workflow", "module")
return nil, fmt.Errorf("playbook %s: action %d position %q is not supported (want %q or %q)", at(path, a.line), i+1, pos, "workflow", "module")
}
a.Position = pos
if err := validateActionShapeField(path, i, pos, a); err != nil {
if err := validateActionShapeField(at(path, a.line), i, pos, a); err != nil {
return nil, err
}
if pos == "workflow" {
@@ -352,7 +390,7 @@ func compileWorkflowActions(path string, raw []rawAction) ([]Action, error) {
}
a := raw[0]
if strings.TrimSpace(a.Workflow) == "" {
return nil, fmt.Errorf("playbook %s: workflow-kind action must name a workflow", path)
return nil, fmt.Errorf("playbook %s: workflow-kind action must name a workflow", at(path, a.line))
}
env := expr.NewEnv()
@@ -363,13 +401,13 @@ func compileWorkflowActions(path string, raw []rawAction) ([]Action, error) {
env: env,
}
if strings.TrimSpace(a.When) != "" {
prg, err := compileExpr(path, "when condition", a.When, env)
prg, err := compileExpr(at(path, a.whenLine), "when condition", a.When, env)
if err != nil {
return nil, err
}
action.When = prg
}
args, err := compileArgs(path, "", "", a.Args, env, nil)
args, err := compileArgs(path, a.argLines, "", "", a.Args, env, nil)
if err != nil {
return nil, err
}
@@ -392,11 +430,11 @@ func compileModuleActions(path string, raw []rawAction, schemas KindSchemas) ([]
label := actionLabel(i, a.ID)
kind := strings.TrimSpace(a.Kind)
if kind == "" {
return nil, fmt.Errorf("playbook %s: %s must name a kind", path, label)
return nil, fmt.Errorf("playbook %s: %s must name a kind", at(path, a.line), label)
}
argsType, resultType, ok := schemas.KindSchema(kind)
if !ok {
return nil, fmt.Errorf("playbook %s: %s has unknown module kind %q", path, label, kind)
return nil, fmt.Errorf("playbook %s: %s has unknown module kind %q", at(path, a.line), label, kind)
}
env := expr.NewEnv(declared...)
@@ -407,13 +445,13 @@ func compileModuleActions(path string, raw []rawAction, schemas KindSchemas) ([]
env: env,
}
if strings.TrimSpace(a.When) != "" {
prg, err := compileExpr(path, label+" when condition", a.When, env)
prg, err := compileExpr(at(path, a.whenLine), label+" when condition", a.When, env)
if err != nil {
return nil, err
}
action.When = prg
}
args, err := compileArgs(path, label, kind, a.Args, env, argsType)
args, err := compileArgs(path, a.argLines, label, kind, a.Args, env, argsType)
if err != nil {
return nil, err
}
@@ -477,12 +515,12 @@ func checkArgType(path, label, kind string, argsSchema reflect.Type, key string,
// nil and keep free-form args. Each program goes through the same
// compile/reference validation as `when`, with label naming the offending
// action and the args key naming the offending field.
func compileArgs(path, label, kind string, raw map[string]string, env *expr.Env, argsSchema reflect.Type) (map[string]*expr.Program, error) {
func compileArgs(path string, lines map[string]int, label, kind string, raw map[string]string, env *expr.Env, argsSchema reflect.Type) (map[string]*expr.Program, error) {
if len(raw) == 0 {
return nil, nil
}
if argsSchema != nil {
if err := validateArgsKeys(path, label, kind, argsSchema, raw); err != nil {
if err := validateArgsKeys(path, lines, label, kind, argsSchema, raw); err != nil {
return nil, err
}
}
@@ -493,12 +531,12 @@ func compileArgs(path, label, kind string, raw map[string]string, env *expr.Env,
sort.Strings(keys)
args := make(map[string]*expr.Program, len(raw))
for _, key := range keys {
prg, err := compileExpr(path, argsLabel(label, key), raw[key], env)
prg, err := compileExpr(at(path, lines[key]), argsLabel(label, key), raw[key], env)
if err != nil {
return nil, err
}
if argsSchema != nil {
if err := checkArgType(path, label, kind, argsSchema, key, prg); err != nil {
if err := checkArgType(at(path, lines[key]), label, kind, argsSchema, key, prg); err != nil {
return nil, err
}
}
@@ -513,7 +551,7 @@ func compileArgs(path, label, kind string, raw map[string]string, env *expr.Env,
// YAML spelling (Message -> message), and the YAML key is compared verbatim:
// the decoder also matches literal lower-case keys, so `Message` is rejected
// here rather than loading and then failing at dispatch.
func validateArgsKeys(path, label, kind string, argsSchema reflect.Type, raw map[string]string) error {
func validateArgsKeys(path string, lines map[string]int, label, kind string, argsSchema reflect.Type, raw map[string]string) error {
t := argsSchema
if t.Kind() == reflect.Pointer {
t = t.Elem()
@@ -533,7 +571,7 @@ func validateArgsKeys(path, label, kind string, argsSchema reflect.Type, raw map
}
for _, key := range keys {
if _, ok := fields[key]; !ok {
return fmt.Errorf("playbook %s: %s args[%q] is not a declared Args field", path, loc, key)
return fmt.Errorf("playbook %s: %s args[%q] is not a declared Args field", at(path, lines[key]), loc, key)
}
}
return nil
@@ -701,7 +701,7 @@ func TestCompileArgsReportsFirstKeyDeterministically(t *testing.T) {
"a.bad": "event.missing ==",
}
for range 64 {
_, err := compileArgs("pb.yaml", "", "", raw, env, nil)
_, err := compileArgs("pb.yaml", nil, "", "", raw, env, nil)
if err == nil {
t.Fatal("compileArgs = nil, want error")
}
@@ -727,7 +727,7 @@ func TestValidateArgsKeysReportsFirstKeyDeterministically(t *testing.T) {
"a.bad": "x",
}
for range 64 {
err := validateArgsKeys("pb.yaml", "", "log", argsType, raw)
err := validateArgsKeys("pb.yaml", nil, "", "log", argsType, raw)
if err == nil {
t.Fatal("validateArgsKeys = nil, want error")
}