feat(playbooks): lint an EDA playbook directory with -eda-dir

This commit is contained in:
sam committed 2026-09-23 22:11:01 +10:00
1 parent d01f7b3d3a
commit 69e6d276e6
7 files changed
+88 -17

No files matched your search

+2
View File
@@ -208,6 +208,8 @@ tasks:
Lint a different set of directories directly:
go run ./cmd/archie-playbooks lint -dir ./a -dir ./b
Lint an EDA playbook directory:
go run ./cmd/archie-playbooks lint -eda-dir ./eda-playbooks
cmds:
- go run ./cmd/archie-playbooks lint -dir ./playbooks
+14 -7
View File
@@ -56,25 +56,32 @@ func run(args []string, stderr io.Writer) int {
return cmd(args[1:], stderr)
}
// runLint validates one or more playbook directories against the domain
// loaders and reports collisions / malformed files / invalid bindings.
// runLint validates routing binding directories (-dir) and an EDA playbook
// directory (-eda-dir) against the loaders the daemon runs at startup.
// Exit codes: 0 clean, 1 findings, 2 usage error.
func runLint(args []string, stderr io.Writer) int {
flags := flag.NewFlagSet("archie-playbooks lint", flag.ContinueOnError)
flags.SetOutput(stderr)
var dirs multiFlag
flags.Var(&dirs, "dir", "playbook directory to lint (repeatable)")
flags.Var(&dirs, "dir", "routing binding directory to lint (repeatable)")
edaDir := flags.String("eda-dir", "", "EDA playbook directory to lint (the daemon's eda_playbook_dir)")
if err := flags.Parse(args); err != nil {
return 2 // flag.ContinueOnError already printed the message
}
if len(dirs) == 0 {
fmt.Fprintln(stderr, "lint: at least one -dir is required")
if len(dirs) == 0 && *edaDir == "" {
fmt.Fprintln(stderr, "lint: at least one -dir or an -eda-dir is required")
flags.Usage()
return 2
}
result := archieplaybooks.Lint(dirs, stderr)
return result.ExitCode
code := 0
if len(dirs) > 0 {
code = max(code, archieplaybooks.Lint(dirs, stderr).ExitCode)
}
if *edaDir != "" {
code = max(code, archieplaybooks.LintEDA(*edaDir, stderr).ExitCode)
}
return code
}
// multiFlag collects repeated -dir flags.
+13
View File
@@ -73,3 +73,16 @@ func writeFile(t *testing.T, path, content string) {
t.Fatalf("write %s: %v", path, err)
}
}
// -eda-dir alone is a complete lint request, and its findings set the exit
// code.
func TestRunLintEDADir(t *testing.T) {
dir := t.TempDir()
if err := os.WriteFile(filepath.Join(dir, "pb.yaml"), []byte("trigger:\n kind: bug\nactions:\n - position: module\n kind: nope\n"), 0o600); err != nil {
t.Fatal(err)
}
var stderr bytes.Buffer
if code := run([]string{"lint", "-eda-dir", dir}, &stderr); code != 1 {
t.Fatalf("run(lint -eda-dir) = %d, want 1; stderr: %s", code, stderr.String())
}
}
+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/",
+3 -4
View File
@@ -169,10 +169,9 @@ a case that should just be visible and fixed by a human. Instead:
exiting non-zero on any collision / malformed file / invalid binding.
A finding about one binding key leads with the key's `file:line`, read
from the `yaml.Node` the loader decodes; the linter agrees with runtime
validation by construction, which is the load-bearing property. That
agreement covers the routing loaders only: EDA playbooks under
`eda_playbook_dir` (`playbook.Load`, with its CEL and action-id checks)
have no lint path yet and are validated only at daemon startup.
validation by construction, which is the load-bearing property. `-eda-dir`
lints an `eda_playbook_dir` the same way, through `playbook.Load` with its
CEL, action-id and args checks.
Discoverable via `task lint:playbooks` or direct `go run
./cmd/archie-playbooks lint -dir ...`. The LSP/serve mode is a later
entrypoint of the SAME binary, per the shared-package decision above.
+17 -5
View File
@@ -1,17 +1,19 @@
// Package archieplaybooks is the application composition for the standalone
// playbook-validation CLI (cmd/archie-playbooks). It owns the lint mode's
// orchestration: collect the configured directories, run the domain
// validator, and shape the outcome for human consumption. All validation
// rules live in internal/domain/workflow (LoadKindWorkflowsYAML,
// LoadLabelWorkflowsYAML, LoadPlaybookDirs) -- this package only calls them
// and formats results; there is deliberately no second validation path
// here (per docs/prds/eda-playbook-engine.md and t2db.12).
// validators, and shape the outcome for human consumption. The rules live in
// internal/domain/workflow (routing binding files) and
// internal/domain/eda/playbook (EDA playbooks) -- this package only calls the
// loaders the daemon runs and formats results; there is deliberately no
// second validation path here (per docs/prds/eda-playbook-engine.md).
package archieplaybooks
import (
"fmt"
"io"
"github.com/samcharles93/archie-core/internal/domain/eda/module"
"github.com/samcharles93/archie-core/internal/domain/eda/playbook"
"github.com/samcharles93/archie-core/internal/domain/workflow"
)
@@ -48,3 +50,13 @@ func Lint(dirs []string, stderr io.Writer) Result {
}
return Result{ExitCode: 0, Findings: nil}
}
// LintEDA validates an EDA playbook directory (the daemon's eda_playbook_dir)
// with playbook.Load, the loader the daemon runs at startup.
func LintEDA(dir string, stderr io.Writer) Result {
if _, err := playbook.Load(dir, module.New()); err != nil {
fmt.Fprintln(stderr, err)
return Result{ExitCode: 1, Findings: []string{err.Error()}}
}
return Result{}
}
@@ -0,0 +1,38 @@
package archieplaybooks
import (
"io"
"path/filepath"
"strings"
"testing"
)
// LintEDA refuses exactly what the daemon's EDA loader refuses at startup.
func TestLintEDA(t *testing.T) {
tests := []struct {
name string
document string
wantErr string
}{
{name: "valid action playbook", document: "trigger:\n kind: bug\nactions:\n - position: module\n kind: log\n args:\n message: '\"hi\"'\n"},
{name: "unknown kind", document: "trigger:\n kind: bug\nactions:\n - position: module\n kind: nope\n", wantErr: "nope"},
{name: "wrongly typed arg", document: "trigger:\n kind: bug\nactions:\n - position: module\n kind: log\n args:\n message: '123'\n", wantErr: `args["message"]`},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
dir := t.TempDir()
writeFile(t, filepath.Join(dir, "pb.yaml"), tt.document)
result := LintEDA(dir, io.Discard)
if tt.wantErr == "" {
if result.ExitCode != 0 {
t.Fatalf("LintEDA exit = %d, findings %q, want clean", result.ExitCode, result.Findings)
}
return
}
joined := strings.Join(result.Findings, "\n")
if result.ExitCode != 1 || !strings.Contains(joined, "pb.yaml") || !strings.Contains(joined, tt.wantErr) {
t.Fatalf("LintEDA = exit %d, findings %q, want exit 1 naming pb.yaml and %q", result.ExitCode, joined, tt.wantErr)
}
})
}
}