relay-flow 0.0.1 → 0.2.0-alpha

package/internal/workflow/report_test.go

@@ -0,0 +1,259 @@
+package workflow_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+// 3.2 + 3.3: structured report contract and ValidateReport behavior per
+// specs/structured-node-reporting.
+
+func fullSummary() workflow.Summary {
+	return workflow.Summary{
+		Completed:        "did the work",
+		Commits:          "abc123",
+		NotCompleted:     "None",
+		IssuesDiscovered: "None",
+		Verification:     "ran tests",
+		Notes:            "None",
+	}
+}
+
+func fullFeedback() workflow.Feedback {
+	return workflow.Feedback{
+		ReasonForNextStep: "work done",
+		RequiredActions:   "review it",
+		RelevantContext:   "None",
+		ExpectedResult:    "approval",
+	}
+}
+
+func noneFeedback() workflow.Feedback {
+	return workflow.Feedback{
+		ReasonForNextStep: "None",
+		RequiredActions:   "None",
+		RelevantContext:   "None",
+		ExpectedResult:    "None",
+	}
+}
+
+func TestValidateReportAcceptsCompleteSuccess(t *testing.T) {
+	wf := parse(t, "basicFlow", minimalValid)
+	r := workflow.Report{
+		Status:   workflow.OutcomeSuccess,
+		NextStep: "end",
+		Summary:  fullSummary(),
+		Feedback: noneFeedback(),
+	}
+	if err := wf.ValidateReport("coding", r); err != nil {
+		t.Fatalf("valid end report rejected: %v", err)
+	}
+}
+
+func TestValidateReportRequiresEverySection(t *testing.T) {
+	wf := parse(t, "basicFlow", minimalValid)
+
+	base := workflow.Report{
+		Status:   workflow.OutcomeSuccess,
+		NextStep: "end",
+		Summary:  fullSummary(),
+		Feedback: noneFeedback(),
+	}
+
+	// Empty (non-None) strings are invalid: a required section is either
+	// real content or the literal None.
+	cases := map[string]func(workflow.Report) workflow.Report{
+		"missing completed": func(r workflow.Report) workflow.Report {
+			r.Summary.Completed = ""
+			return r
+		},
+		"missing commits": func(r workflow.Report) workflow.Report {
+			r.Summary.Commits = ""
+			return r
+		},
+		"missing notCompleted": func(r workflow.Report) workflow.Report {
+			r.Summary.NotCompleted = ""
+			return r
+		},
+		"missing issuesDiscovered": func(r workflow.Report) workflow.Report {
+			r.Summary.IssuesDiscovered = ""
+			return r
+		},
+		"missing verification": func(r workflow.Report) workflow.Report {
+			r.Summary.Verification = ""
+			return r
+		},
+		"missing notes": func(r workflow.Report) workflow.Report {
+			r.Summary.Notes = ""
+			return r
+		},
+		"missing reasonForNextStep": func(r workflow.Report) workflow.Report {
+			r.Feedback.ReasonForNextStep = ""
+			return r
+		},
+		"missing requiredActions": func(r workflow.Report) workflow.Report {
+			r.Feedback.RequiredActions = ""
+			return r
+		},
+		"missing relevantContext": func(r workflow.Report) workflow.Report {
+			r.Feedback.RelevantContext = ""
+			return r
+		},
+		"missing expectedResult": func(r workflow.Report) workflow.Report {
+			r.Feedback.ExpectedResult = ""
+			return r
+		},
+		"missing nextStep": func(r workflow.Report) workflow.Report {
+			r.NextStep = ""
+			return r
+		},
+	}
+	for name, mutate := range cases {
+		t.Run(name, func(t *testing.T) {
+			if err := wf.ValidateReport("coding", mutate(base)); err == nil {
+				t.Fatal("incomplete report accepted")
+			}
+		})
+	}
+}
+
+func TestValidateReportStatusValues(t *testing.T) {
+	wf := parse(t, "basicFlow", minimalValid)
+	r := workflow.Report{NextStep: "end", Summary: fullSummary(), Feedback: noneFeedback()}
+
+	r.Status = "done"
+	if err := wf.ValidateReport("coding", r); err == nil {
+		t.Fatal("status other than success|failure accepted")
+	}
+	r.Status = workflow.OutcomeFailure
+	// failure cannot select end (only coding is a failure route); use coding.
+	r.NextStep = "coding"
+	r.Feedback = fullFeedback()
+	if err := wf.ValidateReport("coding", r); err != nil {
+		t.Fatalf("valid failure report rejected: %v", err)
+	}
+}
+
+func TestValidateReportNextStepMustMatchStatusRoute(t *testing.T) {
+	wf := parse(t, "basicFlow", minimalValid)
+
+	t.Run("target legal only for other outcome", func(t *testing.T) {
+		// end is only configured for success on coding.
+		r := workflow.Report{
+			Status:   workflow.OutcomeFailure,
+			NextStep: "end",
+			Summary:  fullSummary(),
+			Feedback: fullFeedback(),
+		}
+		if err := wf.ValidateReport("coding", r); err == nil {
+			t.Fatal("failure report selecting a success-only target accepted")
+		}
+	})
+
+	t.Run("unknown target", func(t *testing.T) {
+		r := workflow.Report{
+			Status:   workflow.OutcomeSuccess,
+			NextStep: "nowhere",
+			Summary:  fullSummary(),
+			Feedback: fullFeedback(),
+		}
+		err := wf.ValidateReport("coding", r)
+		if err == nil {
+			t.Fatal("next step naming an unconfigured target accepted")
+		}
+		// The error should surface the legal choices.
+		if !strings.Contains(err.Error(), "end") {
+			t.Fatalf("error %q does not list the legal choice end", err)
+		}
+	})
+
+	t.Run("revisit loop route accepted", func(t *testing.T) {
+		r := workflow.Report{
+			Status:   workflow.OutcomeFailure,
+			NextStep: "coding",
+			Summary:  fullSummary(),
+			Feedback: fullFeedback(),
+		}
+		if err := wf.ValidateReport("coding", r); err != nil {
+			t.Fatalf("failure self-loop rejected: %v", err)
+		}
+	})
+}
+
+func TestValidateReportEndRequiresNoneFeedback(t *testing.T) {
+	wf := parse(t, "basicFlow", minimalValid)
+
+	t.Run("end with all-None feedback accepted", func(t *testing.T) {
+		r := workflow.Report{
+			Status:   workflow.OutcomeSuccess,
+			NextStep: "end",
+			Summary:  fullSummary(),
+			Feedback: noneFeedback(),
+		}
+		if err := wf.ValidateReport("coding", r); err != nil {
+			t.Fatalf("end report with None feedback rejected: %v", err)
+		}
+	})
+
+	t.Run("end with feedback content rejected", func(t *testing.T) {
+		r := workflow.Report{
+			Status:   workflow.OutcomeSuccess,
+			NextStep: "end",
+			Summary:  fullSummary(),
+			Feedback: fullFeedback(),
+		}
+		if err := wf.ValidateReport("coding", r); err == nil {
+			t.Fatal("end report carrying feedback accepted; end has no mailbox")
+		}
+	})
+
+	t.Run("end report still requires summary", func(t *testing.T) {
+		r := workflow.Report{
+			Status:   workflow.OutcomeSuccess,
+			NextStep: "end",
+			Summary:  workflow.Summary{},
+			Feedback: noneFeedback(),
+		}
+		if err := wf.ValidateReport("coding", r); err == nil {
+			t.Fatal("end report without summary accepted")
+		}
+	})
+}
+
+func TestValidateReportCalledForBothNodeTypes(t *testing.T) {
+	hitlYaml := strings.Replace(minimalValid, "    type: agent", "    type: hitl", 1)
+	wf := parse(t, "basicFlow", hitlYaml)
+
+	valid := workflow.Report{
+		Status:   workflow.OutcomeSuccess,
+		NextStep: "end",
+		Summary:  fullSummary(),
+		Feedback: noneFeedback(),
+	}
+	if err := wf.ValidateReport("coding", valid); err != nil {
+		t.Fatalf("HITL node report rejected: %v", err)
+	}
+	invalid := valid
+	invalid.NextStep = "nowhere"
+	if err := wf.ValidateReport("coding", invalid); err == nil {
+		t.Fatal("invalid HITL report accepted; ValidateReport is shared by agent and HITL nodes")
+	}
+}
+
+func TestValidateReportNoneMeansIntentionallyEmpty(t *testing.T) {
+	wf := parse(t, "basicFlow", minimalValid)
+	s := fullSummary()
+	s.IssuesDiscovered = "None"
+	s.NotCompleted = "None"
+	r := workflow.Report{
+		Status:   workflow.OutcomeSuccess,
+		NextStep: "end",
+		Summary:  s,
+		Feedback: noneFeedback(),
+	}
+	if err := wf.ValidateReport("coding", r); err != nil {
+		t.Fatalf("report with literal None sections rejected: %v", err)
+	}
+}

package/internal/workflow/service.go

@@ -0,0 +1,142 @@
+package workflow
+
+import (
+	"context"
+	"fmt"
+	"sync"
+)
+
+// ActiveRuns reports whether any run of a workflow is active.
+type ActiveRuns interface {
+	HasActiveWorkflow(context.Context, string) (bool, error)
+}
+
+// RepoLookup reports whether a repo is registered.
+type RepoLookup interface {
+	Exists(string) bool
+}
+
+// Service manages workflow submission, removal, and lookup over the store
+// and registry.
+type Service struct {
+	store  *Store
+	reg    *Registry
+	repos  RepoLookup
+	active ActiveRuns
+	// Gate, when non-nil, is the lifecycle mutex shared with
+	// RunManager.EnsureRun (design.md decision 23): Submit/Remove hold it
+	// while checking active runs and swapping disk + in-memory definitions,
+	// so a run never starts against a workflow being replaced or removed.
+	// A plain *sync.Mutex — no lock service.
+	Gate *sync.Mutex
+	// Rebind, when non-nil, is invoked under Gate after the in-memory
+	// workflow registry changes (submit or remove). The composition root
+	// wires it to repo.Registry.BindWorkflows so poller/router bindings are
+	// rebuilt atomically with the workflow swap (spec: "Repo.Workflows
+	// bindings are rebuilt on submit/remove/startup"). Nil in tests that
+	// do not wire repos.
+	Rebind func() error
+	// ValidateTaskConfig validates the workflow against each referenced repo's
+	// task system before storage. The composition root supplies this callback;
+	// keeping it here avoids widening RepoLookup beyond its documented query.
+	ValidateTaskConfig func(context.Context, *Workflow) error
+}
+
+func NewService(store *Store, active ActiveRuns, repos RepoLookup) *Service {
+	return &Service{store: store, reg: &Registry{}, active: active, repos: repos}
+}
+
+// Registry exposes the in-memory workflow set for wiring (startup load).
+func (s *Service) Registry() *Registry {
+	return s.reg
+}
+
+// Submit creates or replaces a workflow. It parses, validates, and checks
+// repos and active runs before atomically replacing the file; the in-memory
+// replacement cannot fail afterward. There is no workflow versioning.
+//
+// When Gate is set, the ENTIRE Submit operation (parse, repo validation,
+// active-run check, disk + in-memory swap, binding rebuild) holds the
+// shared lifecycle mutex so no concurrent EnsureRun can resolve a stale
+// definition and no concurrent repo registration can invalidate the
+// repo-existence check (design.md decision 23).
+func (s *Service) Submit(ctx context.Context, yamlBytes []byte) (*Workflow, error) {
+	if s.Gate != nil {
+		s.Gate.Lock()
+		defer s.Gate.Unlock()
+	}
+	wf, err := Parse("", yamlBytes)
+	if err != nil {
+		return nil, err
+	}
+	if err := wf.Validate(); err != nil {
+		return nil, err
+	}
+	for _, repo := range wf.Repos {
+		if !s.repos.Exists(repo) {
+			return nil, fmt.Errorf("workflow %q references unregistered repo %q", wf.Name, repo)
+		}
+	}
+	if s.ValidateTaskConfig != nil {
+		if err := s.ValidateTaskConfig(ctx, wf); err != nil {
+			return nil, err
+		}
+	}
+	active, err := s.active.HasActiveWorkflow(ctx, wf.Name)
+	if err != nil {
+		return nil, fmt.Errorf("check active runs for workflow %q: %w", wf.Name, err)
+	}
+	if active {
+		return nil, fmt.Errorf("workflow %q has active runs; replacement is rejected", wf.Name)
+	}
+	if err := s.store.Put(wf.Name, yamlBytes); err != nil {
+		return nil, err
+	}
+	s.reg.Replace(wf)
+	if s.Rebind != nil {
+		if err := s.Rebind(); err != nil {
+			return nil, fmt.Errorf("rebind workflows for %q: %w", wf.Name, err)
+		}
+	}
+	return wf, nil
+}
+
+// Remove deletes a workflow definition. Removal is rejected while any run
+// of the workflow is active.
+func (s *Service) Remove(ctx context.Context, name string) error {
+	if s.Gate != nil {
+		s.Gate.Lock()
+		defer s.Gate.Unlock()
+	}
+	active, err := s.active.HasActiveWorkflow(ctx, name)
+	if err != nil {
+		return fmt.Errorf("check active runs for workflow %q: %w", name, err)
+	}
+	if active {
+		return fmt.Errorf("workflow %q has active runs; removal is rejected", name)
+	}
+	if err := s.store.Remove(name); err != nil {
+		return err
+	}
+	s.reg.Remove(name)
+	if s.Rebind != nil {
+		if err := s.Rebind(); err != nil {
+			return fmt.Errorf("rebind workflows after removing %q: %w", name, err)
+		}
+	}
+	return nil
+}
+
+// Get returns the workflow from the registry.
+func (s *Service) Get(name string) (*Workflow, error) {
+	wf, ok := s.reg.Get(name)
+	if !ok {
+		return nil, fmt.Errorf("workflow %q not found", name)
+	}
+	return wf, nil
+}
+
+// List returns all registered workflows.
+func (s *Service) List() []*Workflow {
+	return s.reg.List()
+}

package/internal/workflow/store.go

@@ -0,0 +1,136 @@
+package workflow
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+)
+
+// Store persists workflow definitions as YAML files under Dir. The workflow
+// file is the durable definition.
+type Store struct {
+	Dir string
+}
+
+func (s *Store) path(name string) string {
+	return filepath.Join(s.Dir, name+".yaml")
+}
+
+// LoadAll reads and parses every stored workflow file.
+func (s *Store) LoadAll() ([]*Workflow, error) {
+	entries, err := os.ReadDir(s.Dir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("read workflow dir %s: %w", s.Dir, err)
+	}
+	var out []*Workflow
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".yaml") {
+			continue
+		}
+		name := strings.TrimSuffix(e.Name(), ".yaml")
+		wf, err := s.Get(name)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, wf)
+	}
+	return out, nil
+}
+
+// Get reads and parses one stored workflow by name.
+func (s *Store) Get(name string) (*Workflow, error) {
+	raw, err := os.ReadFile(s.path(name))
+	if err != nil {
+		return nil, fmt.Errorf("read workflow %q: %w", name, err)
+	}
+	return Parse(name, raw)
+}
+
+// Put atomically writes the workflow file with mode 0644.
+func (s *Store) Put(name string, yamlBytes []byte) error {
+	if err := os.MkdirAll(s.Dir, 0o755); err != nil {
+		return fmt.Errorf("create workflow dir %s: %w", s.Dir, err)
+	}
+	if err := config.WriteAtomic(s.path(name), yamlBytes, 0o644); err != nil {
+		return fmt.Errorf("store workflow %q: %w", name, err)
+	}
+	return nil
+}
+
+// Remove deletes the workflow file.
+func (s *Store) Remove(name string) error {
+	if err := os.Remove(s.path(name)); err != nil {
+		return fmt.Errorf("remove workflow %q: %w", name, err)
+	}
+	return nil
+}
+
+// Registry is the in-memory workflow set. The registry has no repo index;
+// repo bindings are the only derived repo-to-workflow index.
+type Registry struct {
+	mu   sync.RWMutex
+	byID map[string]*Workflow
+}
+
+func (r *Registry) get(name string) (*Workflow, bool) {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	wf, ok := r.byID[name]
+	return wf, ok
+}
+
+// Get returns the workflow by name.
+func (r *Registry) Get(name string) (*Workflow, bool) {
+	return r.get(name)
+}
+
+// List returns all registered workflows sorted by name.
+func (r *Registry) List() []*Workflow {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	out := make([]*Workflow, 0, len(r.byID))
+	for _, wf := range r.byID {
+		out = append(out, wf)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out
+}
+
+// ReferencesRepo reports whether any registered workflow lists the repo.
+func (r *Registry) ReferencesRepo(repo string) bool {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	for _, wf := range r.byID {
+		for _, rr := range wf.Repos {
+			if rr == repo {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// Replace creates or replaces the workflow in the registry.
+func (r *Registry) Replace(wf *Workflow) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.byID == nil {
+		r.byID = map[string]*Workflow{}
+	}
+	r.byID[wf.Name] = wf
+}
+
+// Remove deletes the workflow from the registry.
+func (r *Registry) Remove(name string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	delete(r.byID, name)
+}