feat(eda): playbook.Load findings name the offending action, when or args line
This commit is contained in:
7 files changed
+121
-24
No files matched your search
@@ -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/",
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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{}}
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -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")
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user