relay-flow 0.0.1 → 0.2.0-alpha

package/internal/workflow/store_test.go

@@ -0,0 +1,282 @@
+package workflow_test
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+// 3.34: workflow storage/service per specs/workflow-repo-management
+// "Workflow definitions are persisted atomically" and "Workflow replacement
+// has no concurrent versions" / "Workflow removal protects active runs".
+
+const storeValid = `
+name: basicFlow
+repos: [payments]
+nodes:
+  start:
+    onSuccess:
+      - target: coding
+  coding:
+    type: agent
+    agent: build
+    description: work
+    onSuccess:
+      - target: end
+    onFailure:
+      - target: coding
+  end: {}
+`
+
+type fakeActiveRuns struct{ active map[string]bool }
+
+func (f *fakeActiveRuns) HasActiveWorkflow(_ context.Context, name string) (bool, error) {
+	return f.active[name], nil
+}
+
+func (f *fakeActiveRuns) set(name string, on bool) { f.active[name] = on }
+
+type fakeRepoLookup struct{ repos map[string]bool }
+
+func (f fakeRepoLookup) Exists(name string) bool { return f.repos[name] }
+
+func newStore(t *testing.T) *workflow.Store {
+	t.Helper()
+	return &workflow.Store{Dir: t.TempDir()}
+}
+
+// newService builds a Service via its constructor over a temp store and the
+// fake ActiveRuns/RepoLookup consumer interfaces.
+func newService(t *testing.T, active *fakeActiveRuns, repos map[string]bool) (*workflow.Service, *workflow.Store) {
+	t.Helper()
+	store := newStore(t)
+	svc := workflow.NewService(store, active, fakeRepoLookup{repos: repos})
+	return svc, store
+}
+
+func TestStorePutGetLoadAll(t *testing.T) {
+	s := newStore(t)
+	if err := s.Put("basicFlow", []byte(storeValid)); err != nil {
+		t.Fatalf("Put failed: %v", err)
+	}
+	// File lands at <dir>/<name>.yaml with 0644.
+	fi, err := os.Stat(filepath.Join(s.Dir, "basicFlow.yaml"))
+	if err != nil {
+		t.Fatalf("workflow file not stored: %v", err)
+	}
+	if fi.Mode().Perm() != 0644 {
+		t.Fatalf("workflow file mode = %o, want 0644", fi.Mode().Perm())
+	}
+
+	wf, err := s.Get("basicFlow")
+	if err != nil {
+		t.Fatalf("Get failed: %v", err)
+	}
+	if wf.Name != "basicFlow" {
+		t.Fatalf("Get name = %q", wf.Name)
+	}
+
+	all, err := s.LoadAll()
+	if err != nil || len(all) != 1 {
+		t.Fatalf("LoadAll = %d, %v", len(all), err)
+	}
+
+	if err := s.Remove("basicFlow"); err != nil {
+		t.Fatalf("Remove failed: %v", err)
+	}
+	if _, err := s.Get("basicFlow"); err == nil {
+		t.Fatal("Get after Remove succeeded")
+	}
+}
+
+func TestServiceSubmitValidatesBeforeStoring(t *testing.T) {
+	active := &fakeActiveRuns{active: map[string]bool{}}
+	svc, store := newService(t, active, map[string]bool{"payments": true})
+
+	// Invalid YAML must fail before any file is written.
+	if _, err := svc.Submit(context.Background(), []byte("name: bad name!!")); err == nil {
+		t.Fatal("invalid workflow submitted")
+	}
+	if _, err := store.Get("bad name!!"); err == nil {
+		t.Fatal("invalid workflow was stored")
+	}
+
+	wf, err := svc.Submit(context.Background(), []byte(storeValid))
+	if err != nil {
+		t.Fatalf("valid Submit failed: %v", err)
+	}
+	if wf.Name != "basicFlow" {
+		t.Fatalf("submitted name = %q", wf.Name)
+	}
+	// Submission updates the in-memory registry: the workflow is retrievable.
+	if _, err := svc.Get("basicFlow"); err != nil {
+		t.Fatal("submitted workflow not in registry after submit")
+	}
+}
+
+func TestServiceSubmitValidatesReferencedRepoConfigBeforeStoring(t *testing.T) {
+	active := &fakeActiveRuns{active: map[string]bool{}}
+	svc, store := newService(t, active, map[string]bool{"payments": true})
+	svc.ValidateTaskConfig = func(_ context.Context, wf *workflow.Workflow) error {
+		if wf.Nodes["coding"].TaskConfig["invalid"] == true {
+			return errors.New("repo payments node coding: invalid task config")
+		}
+		return nil
+	}
+	invalid := []byte(strings.Replace(storeValid, "description: work", "description: work\n    taskConfig:\n      invalid: true", 1))
+
+	if _, err := svc.Submit(context.Background(), invalid); err == nil || !strings.Contains(err.Error(), "invalid task config") {
+		t.Fatalf("Submit error = %v", err)
+	}
+	if _, err := store.Get("basicFlow"); err == nil {
+		t.Fatal("workflow was stored despite task validation failure")
+	}
+}
+
+func TestServiceSubmitRejectsUnknownRepo(t *testing.T) {
+	active := &fakeActiveRuns{active: map[string]bool{}}
+	svc, store := newService(t, active, map[string]bool{}) // no repos registered
+	if _, err := svc.Submit(context.Background(), []byte(storeValid)); err == nil {
+		t.Fatal("workflow referencing unregistered repo accepted")
+	}
+	if _, err := store.Get("basicFlow"); err == nil {
+		t.Fatal("unknown-repo workflow stored")
+	}
+}
+
+func TestServiceReplaceRejectedWhileActive(t *testing.T) {
+	active := &fakeActiveRuns{active: map[string]bool{}}
+	svc, store := newService(t, active, map[string]bool{"payments": true})
+	if _, err := svc.Submit(context.Background(), []byte(storeValid)); err != nil {
+		t.Fatal(err)
+	}
+	before, err := store.Get("basicFlow")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Now a run is active; replacement must be rejected and the stored file
+	// and in-memory definition must remain unchanged. Change a REAL field
+	// (the coding node description), not just a comment.
+	active.set("basicFlow", true)
+	replacement := []byte(strings.Replace(storeValid, "description: work", "description: changed work", 1))
+	if _, err := svc.Submit(context.Background(), replacement); err == nil {
+		t.Fatal("replacement during active run accepted")
+	}
+	after, err := store.Get("basicFlow")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if after.Name != before.Name {
+		t.Fatal("stored definition changed during rejected replacement")
+	}
+	if after.Nodes["coding"].Description != before.Nodes["coding"].Description {
+		t.Fatalf("in-memory definition changed during rejected replacement: %q -> %q",
+			before.Nodes["coding"].Description, after.Nodes["coding"].Description)
+	}
+	rawOnDisk, rerr := os.ReadFile(filepath.Join(store.Dir, "basicFlow.yaml"))
+	if rerr == nil && strings.Contains(string(rawOnDisk), "changed work") {
+		t.Fatal("stored workflow file changed during rejected replacement")
+	}
+
+	// After completion, replacement succeeds and becomes the definition.
+	active.set("basicFlow", false)
+	if _, err := svc.Submit(context.Background(), replacement); err != nil {
+		t.Fatalf("replacement after completion rejected: %v", err)
+	}
+	installed, err := store.Get("basicFlow")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if installed.Nodes["coding"].Description != "changed work" {
+		t.Fatalf("changed definition not installed after completion: %q", installed.Nodes["coding"].Description)
+	}
+}
+
+func TestServiceFailedWritePreservesExisting(t *testing.T) {
+	active := &fakeActiveRuns{active: map[string]bool{}}
+	svc, store := newService(t, active, map[string]bool{"payments": true})
+	if _, err := svc.Submit(context.Background(), []byte(storeValid)); err != nil {
+		t.Fatal(err)
+	}
+
+	// Make the store directory read-only so the atomic replacement fails.
+	if err := os.Chmod(store.Dir, 0500); err != nil {
+		t.Fatal(err)
+	}
+	defer os.Chmod(store.Dir, 0700)
+
+	replacement := []byte(storeValid + "\n# changed\n")
+	if _, err := svc.Submit(context.Background(), replacement); err == nil {
+		t.Fatal("submission with failing write succeeded")
+	}
+	// Prior file and in-memory definition remain usable/active.
+	os.Chmod(store.Dir, 0700)
+	got, err := store.Get("basicFlow")
+	if err != nil {
+		t.Fatalf("prior workflow unusable after failed write: %v", err)
+	}
+	if got.Name != "basicFlow" {
+		t.Fatal("in-memory definition lost after failed write")
+	}
+	if _, err := svc.Get("basicFlow"); err != nil {
+		t.Fatal("in-memory definition lost after failed write")
+	}
+}
+
+func TestServiceRemoveProtectsActiveRuns(t *testing.T) {
+	active := &fakeActiveRuns{active: map[string]bool{}}
+	svc, _ := newService(t, active, map[string]bool{"payments": true})
+	if _, err := svc.Submit(context.Background(), []byte(storeValid)); err != nil {
+		t.Fatal(err)
+	}
+
+	active.set("basicFlow", true)
+	if err := svc.Remove(context.Background(), "basicFlow"); err == nil {
+		t.Fatal("removal with active run accepted")
+	}
+
+	active.set("basicFlow", false)
+	if err := svc.Remove(context.Background(), "basicFlow"); err != nil {
+		t.Fatalf("removal without active runs rejected: %v", err)
+	}
+	if _, err := svc.Get("basicFlow"); err == nil {
+		t.Fatal("removed workflow still returned by Get")
+	}
+	// Registry updated on removal: List no longer returns it.
+	for _, w := range svc.List() {
+		if w.Name == "basicFlow" {
+			t.Fatal("removed workflow still listed")
+		}
+	}
+}
+
+func TestRegistryReferencesRepoAndReplace(t *testing.T) {
+	reg := &workflow.Registry{}
+	wf, err := workflow.Parse("basicFlow", []byte(storeValid))
+	if err != nil {
+		t.Fatal(err)
+	}
+	reg.Replace(wf)
+	if !reg.ReferencesRepo("payments") {
+		t.Fatal("ReferencesRepo(payments) = false")
+	}
+	if reg.ReferencesRepo("other") {
+		t.Fatal("ReferencesRepo(other) = true")
+	}
+	if got, ok := reg.Get("basicFlow"); !ok || got.Name != "basicFlow" {
+		t.Fatalf("Registry.Get = %v, %v", got, ok)
+	}
+	reg.Remove("basicFlow")
+	if _, ok := reg.Get("basicFlow"); ok {
+		t.Fatal("Registry.Get after Remove found workflow")
+	}
+	if reg.ReferencesRepo("payments") {
+		t.Fatal("ReferencesRepo still true after removal")
+	}
+}

package/internal/workflow/workflow.go

@@ -0,0 +1,342 @@
+// Package workflow defines workflow values, strict parsing, validation,
+// structured reports, storage, and the workflow service.
+package workflow
+
+import (
+	"bytes"
+	"fmt"
+	"regexp"
+	"sort"
+
+	"gopkg.in/yaml.v3"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+)
+
+type NodeType string
+
+const (
+	NodeAgent NodeType = "agent"
+	NodeHITL  NodeType = "hitl"
+)
+
+type Outcome string
+
+const (
+	OutcomeSuccess Outcome = "success"
+	OutcomeFailure Outcome = "failure"
+)
+
+// Reserved lifecycle node names. The word "terminal" is runner-only.
+const (
+	StartNode = "start"
+	EndNode   = "end"
+)
+
+type Workflow struct {
+	Name               string           `yaml:"name" json:"name"`
+	Repos              []string         `yaml:"repos" json:"repos"`
+	CleanupRunnerOnEnd bool             `yaml:"cleanupRunnerOnEnd" json:"cleanupRunnerOnEnd"`
+	TaskConfig         config.RawValues `yaml:"taskConfig,omitempty" json:"taskConfig,omitempty"`
+	Nodes              map[string]Node  `yaml:"nodes" json:"nodes"`
+}
+
+type Node struct {
+	Type        NodeType         `yaml:"type,omitempty" json:"type,omitempty"`
+	Agent       string           `yaml:"agent,omitempty" json:"agent,omitempty"`
+	Description string           `yaml:"description,omitempty" json:"description,omitempty"`
+	NudgePrompt string           `yaml:"nudgePrompt,omitempty" json:"nudgePrompt,omitempty"`
+	TaskConfig  config.RawValues `yaml:"taskConfig,omitempty" json:"taskConfig,omitempty"`
+	OnSuccess   []Route          `yaml:"onSuccess,omitempty" json:"onSuccess,omitempty"`
+	OnFailure   []Route          `yaml:"onFailure,omitempty" json:"onFailure,omitempty"`
+}
+
+type Route struct {
+	Target string `yaml:"target" json:"target"`
+	When   string `yaml:"when,omitempty" json:"when,omitempty"`
+}
+
+type NudgeTemplateData struct {
+	Ticket    string
+	Workflow  string
+	Repo      string
+	Node      string
+	NextSteps string
+}
+
+var namePattern = regexp.MustCompile(`^[a-z][a-zA-Z0-9]*$`)
+
+var nudgeVarPattern = regexp.MustCompile(`\{\{([^{}]*)\}\}`)
+
+var knownNudgeVars = map[string]bool{
+	"ticket": true, "workflow": true, "repo": true, "node": true, "nextSteps": true,
+}
+
+// Parse strictly decodes a workflow YAML document. Unknown fields and
+// explicit null values inside any taskConfig are rejected. The returned
+// workflow is not yet validated.
+func Parse(name string, yamlBytes []byte) (*Workflow, error) {
+	var raw map[string]any
+	if err := yaml.Unmarshal(yamlBytes, &raw); err != nil {
+		return nil, fmt.Errorf("parse workflow %q: %w", name, err)
+	}
+	var wf Workflow
+	dec := yaml.NewDecoder(bytes.NewReader(yamlBytes))
+	dec.KnownFields(true)
+	if err := dec.Decode(&wf); err != nil {
+		return nil, fmt.Errorf("parse workflow %q: %w", name, err)
+	}
+	if wf.Nodes == nil {
+		wf.Nodes = map[string]Node{}
+	}
+	if v, present := raw["taskConfig"]; present && v == nil {
+		return nil, fmt.Errorf("parse workflow %q: taskConfig: explicit null is not allowed", name)
+	}
+	if err := rejectNullValues(wf.TaskConfig, "taskConfig"); err != nil {
+		return nil, fmt.Errorf("parse workflow %q: %w", name, err)
+	}
+	rawNodes, _ := raw["nodes"].(map[string]any)
+	for nodeName, n := range wf.Nodes {
+		if rn, ok := rawNodes[nodeName].(map[string]any); ok {
+			if v, present := rn["taskConfig"]; present && v == nil {
+				return nil, fmt.Errorf("parse workflow %q node %q: taskConfig: explicit null is not allowed", name, nodeName)
+			}
+		}
+		if err := rejectNullValues(n.TaskConfig, "nodes."+nodeName+".taskConfig"); err != nil {
+			return nil, fmt.Errorf("parse workflow %q: %w", name, err)
+		}
+	}
+	return &wf, nil
+}
+
+// rejectNullValues recursively rejects explicit YAML nulls in raw task
+// config values.
+func rejectNullValues(values map[string]any, path string) error {
+	for k, v := range values {
+		key := path + "." + k
+		if err := rejectNullValue(v, key); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func rejectNullValue(v any, key string) error {
+	if v == nil {
+		return fmt.Errorf("config key %q: explicit null is not allowed", key)
+	}
+	switch t := v.(type) {
+	case map[string]any:
+		return rejectNullValues(t, key)
+	case []any:
+		for i, elem := range t {
+			if err := rejectNullValue(elem, fmt.Sprintf("%s[%d]", key, i)); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+// Validate checks the workflow graph, identity, repos, nodes, routes, and
+// nudge templates against the workflow-definition spec.
+func (w *Workflow) Validate() error {
+	if !namePattern.MatchString(w.Name) {
+		return fmt.Errorf("workflow name %q must be lower-camel alphanumeric beginning with a lowercase letter", w.Name)
+	}
+	if len(w.Repos) == 0 {
+		return fmt.Errorf("workflow %q must list at least one repo", w.Name)
+	}
+	seen := map[string]bool{}
+	for _, r := range w.Repos {
+		if seen[r] {
+			return fmt.Errorf("workflow %q lists duplicate repo %q", w.Name, r)
+		}
+		seen[r] = true
+	}
+
+	start, ok := w.Nodes[StartNode]
+	if !ok {
+		return fmt.Errorf("workflow %q must contain a %q node", w.Name, StartNode)
+	}
+	if err := validateStart(start); err != nil {
+		return fmt.Errorf("workflow %q start: %w", w.Name, err)
+	}
+	end, ok := w.Nodes[EndNode]
+	if !ok {
+		return fmt.Errorf("workflow %q must contain an %q node", w.Name, EndNode)
+	}
+	if err := validateEnd(end); err != nil {
+		return fmt.Errorf("workflow %q end: %w", w.Name, err)
+	}
+
+	for name, n := range w.Nodes {
+		if name == StartNode || name == EndNode {
+			continue
+		}
+		if err := validateWorkNode(w.Name, name, n); err != nil {
+			return err
+		}
+	}
+	for name, n := range w.Nodes {
+		for _, r := range allRoutes(n) {
+			if r.Target == StartNode {
+				return fmt.Errorf("workflow %q node %q: routes cannot target reserved %q", w.Name, name, StartNode)
+			}
+			if _, ok := w.Nodes[r.Target]; !ok {
+				return fmt.Errorf("workflow %q node %q: route target %q does not exist", w.Name, name, r.Target)
+			}
+		}
+	}
+	if err := w.validateReachability(); err != nil {
+		return err
+	}
+	return nil
+}
+
+func validateStart(n Node) error {
+	if n.Type != "" || n.Agent != "" || n.Description != "" || n.NudgePrompt != "" {
+		return fmt.Errorf("start must not declare type, agent, description, or nudgePrompt")
+	}
+	if len(n.OnFailure) != 0 {
+		return fmt.Errorf("start must not declare failure routes")
+	}
+	if len(n.OnSuccess) != 1 {
+		return fmt.Errorf("start must declare exactly one success target, got %d", len(n.OnSuccess))
+	}
+	return nil
+}
+
+func validateEnd(n Node) error {
+	if n.Type != "" || n.Agent != "" || n.Description != "" || n.NudgePrompt != "" {
+		return fmt.Errorf("end must not declare type, agent, description, or nudgePrompt")
+	}
+	if len(n.OnSuccess) != 0 || len(n.OnFailure) != 0 {
+		return fmt.Errorf("end must not declare routes")
+	}
+	return nil
+}
+
+func validateWorkNode(wfName, name string, n Node) error {
+	if n.Type != NodeAgent && n.Type != NodeHITL {
+		return fmt.Errorf("workflow %q node %q: type must be %q or %q", wfName, name, NodeAgent, NodeHITL)
+	}
+	if n.Agent == "" {
+		return fmt.Errorf("workflow %q node %q: agent is required", wfName, name)
+	}
+	if n.Description == "" {
+		return fmt.Errorf("workflow %q node %q: description is required", wfName, name)
+	}
+	if len(n.OnSuccess) == 0 {
+		return fmt.Errorf("workflow %q node %q: at least one success route is required", wfName, name)
+	}
+	if len(n.OnFailure) == 0 {
+		return fmt.Errorf("workflow %q node %q: at least one failure route is required", wfName, name)
+	}
+	for _, m := range nudgeVarPattern.FindAllStringSubmatch(n.NudgePrompt, -1) {
+		if !knownNudgeVars[m[1]] {
+			return fmt.Errorf("workflow %q node %q: unknown nudge template variable {{%s}}", wfName, name, m[1])
+		}
+	}
+	return nil
+}
+
+func allRoutes(n Node) []Route {
+	out := make([]Route, 0, len(n.OnSuccess)+len(n.OnFailure))
+	out = append(out, n.OnSuccess...)
+	out = append(out, n.OnFailure...)
+	return out
+}
+
+// validateReachability ensures every work node is reachable from start and
+// that end is reachable. Backward edges and self-loops are allowed.
+func (w *Workflow) validateReachability() error {
+	adj := map[string][]string{}
+	for name, n := range w.Nodes {
+		for _, r := range allRoutes(n) {
+			adj[name] = append(adj[name], r.Target)
+		}
+	}
+	visited := map[string]bool{}
+	queue := []string{StartNode}
+	for len(queue) > 0 {
+		cur := queue[0]
+		queue = queue[1:]
+		if visited[cur] {
+			continue
+		}
+		visited[cur] = true
+		queue = append(queue, adj[cur]...)
+	}
+	for name := range w.Nodes {
+		if !visited[name] {
+			return fmt.Errorf("workflow %q node %q is not reachable from %q", w.Name, name, StartNode)
+		}
+	}
+	return nil
+}
+
+// StartTarget returns the single success target of the start node.
+func (w *Workflow) StartTarget() (string, error) {
+	start, ok := w.Nodes[StartNode]
+	if !ok {
+		return "", fmt.Errorf("workflow %q has no %q node", w.Name, StartNode)
+	}
+	if len(start.OnSuccess) != 1 {
+		return "", fmt.Errorf("workflow %q start must have exactly one success target, got %d", w.Name, len(start.OnSuccess))
+	}
+	return start.OnSuccess[0].Target, nil
+}
+
+// Routes returns the configured routes for a node and outcome.
+func (w *Workflow) Routes(node string, outcome Outcome) ([]Route, error) {
+	n, ok := w.Nodes[node]
+	if !ok {
+		return nil, fmt.Errorf("workflow %q has no node %q", w.Name, node)
+	}
+	switch outcome {
+	case OutcomeSuccess:
+		return n.OnSuccess, nil
+	case OutcomeFailure:
+		return n.OnFailure, nil
+	default:
+		return nil, fmt.Errorf("workflow %q node %q: unknown outcome %q", w.Name, node, outcome)
+	}
+}
+
+// RenderNudge renders the node's optional custom instructions with the
+// supported variables.
+func (w *Workflow) RenderNudge(node string, data NudgeTemplateData) (string, error) {
+	n, ok := w.Nodes[node]
+	if !ok {
+		return "", fmt.Errorf("workflow %q has no node %q", w.Name, node)
+	}
+	tmpl := n.NudgePrompt
+	out := nudgeVarPattern.ReplaceAllStringFunc(tmpl, func(m string) string {
+		varName := nudgeVarPattern.FindStringSubmatch(m)[1]
+		switch varName {
+		case "ticket":
+			return data.Ticket
+		case "workflow":
+			return data.Workflow
+		case "repo":
+			return data.Repo
+		case "node":
+			return data.Node
+		case "nextSteps":
+			return data.NextSteps
+		}
+		return m
+	})
+	return out, nil
+}
+
+// sortedTargets is a helper for deterministic error messages.
+func sortedTargets(routes []Route) []string {
+	out := make([]string, 0, len(routes))
+	for _, r := range routes {
+		out = append(out, r.Target)
+	}
+	sort.Strings(out)
+	return out
+}