relay-flow 0.0.1 → 0.2.0-alpha

package/internal/task/jira/testdata/acli_search.json

@@ -0,0 +1,120 @@
+[
+  {
+    "changelog": null,
+    "editmeta": null,
+    "expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
+    "fields": {
+      "assignee": {
+        "accountId": "712020:dad5df85-a7bd-4337-b858-0faf9012a009",
+        "accountType": "atlassian",
+        "active": true,
+        "avatarUrls": {
+          "16x16": "https://secure.gravatar.com/avatar/09110b9326675e772c94aa61fc89195b?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FRP-6.png",
+          "24x24": "https://secure.gravatar.com/avatar/09110b9326675e772c94aa61fc89195b?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FRP-6.png",
+          "32x32": "https://secure.gravatar.com/avatar/09110b9326675e772c94aa61fc89195b?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FRP-6.png",
+          "48x48": "https://secure.gravatar.com/avatar/09110b9326675e772c94aa61fc89195b?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FRP-6.png"
+        },
+        "displayName": "Raj Popat",
+        "emailAddress": "raj.popat@wolterskluwer.com",
+        "self": "https://jira-prod-us-26-3.prod.atl-paas.net/rest/api/3/user?accountId=712020%3Adad5df85-a7bd-4337-b858-0faf9012a009",
+        "timeZone": "America/New_York"
+      },
+      "issuetype": {
+        "avatarId": 10318,
+        "description": "A small, distinct piece of work.",
+        "hierarchyLevel": 0,
+        "iconUrl": "https://jira-prod-us-26-3.prod.atl-paas.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10318?size=medium",
+        "id": "10017",
+        "name": "Task",
+        "self": "https://jira-prod-us-26-3.prod.atl-paas.net/rest/api/3/issuetype/10017",
+        "subtask": false
+      },
+      "labels": [],
+      "status": {
+        "description": "",
+        "iconUrl": "https://jira-prod-us-26-3.prod.atl-paas.net/",
+        "id": "10007",
+        "name": "To Do",
+        "self": "https://jira-prod-us-26-3.prod.atl-paas.net/rest/api/3/status/10007",
+        "statusCategory": {
+          "colorName": "blue-gray",
+          "id": 2,
+          "key": "new",
+          "name": "To Do",
+          "self": "https://jira-prod-us-26-3.prod.atl-paas.net/rest/api/3/statuscategory/2"
+        }
+      },
+      "summary": "e2e: hello world program in python"
+    },
+    "fieldsToInclude": null,
+    "id": "157320",
+    "key": "GHCOS-41242",
+    "names": null,
+    "operations": null,
+    "properties": null,
+    "renderedFields": null,
+    "schema": null,
+    "self": "https://jira-prod-us-26-3.prod.atl-paas.net/rest/api/3/issue/157320",
+    "transitions": null,
+    "versionedRepresentations": null
+  },
+  {
+    "changelog": null,
+    "editmeta": null,
+    "expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
+    "fields": {
+      "assignee": {
+        "accountId": "712020:dad5df85-a7bd-4337-b858-0faf9012a009",
+        "accountType": "atlassian",
+        "active": true,
+        "avatarUrls": {
+          "16x16": "https://secure.gravatar.com/avatar/09110b9326675e772c94aa61fc89195b?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FRP-6.png",
+          "24x24": "https://secure.gravatar.com/avatar/09110b9326675e772c94aa61fc89195b?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FRP-6.png",
+          "32x32": "https://secure.gravatar.com/avatar/09110b9326675e772c94aa61fc89195b?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FRP-6.png",
+          "48x48": "https://secure.gravatar.com/avatar/09110b9326675e772c94aa61fc89195b?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FRP-6.png"
+        },
+        "displayName": "Raj Popat",
+        "emailAddress": "raj.popat@wolterskluwer.com",
+        "self": "https://jira-prod-us-26-3.prod.atl-paas.net/rest/api/3/user?accountId=712020%3Adad5df85-a7bd-4337-b858-0faf9012a009",
+        "timeZone": "America/New_York"
+      },
+      "issuetype": {
+        "avatarId": 10303,
+        "description": "A problem or error.",
+        "hierarchyLevel": 0,
+        "iconUrl": "https://jira-prod-us-26-3.prod.atl-paas.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10303?size=medium",
+        "id": "10019",
+        "name": "Bug",
+        "self": "https://jira-prod-us-26-3.prod.atl-paas.net/rest/api/3/issuetype/10019",
+        "subtask": false
+      },
+      "labels": [],
+      "status": {
+        "description": "",
+        "iconUrl": "https://jira-prod-us-26-3.prod.atl-paas.net/",
+        "id": "10007",
+        "name": "To Do",
+        "self": "https://jira-prod-us-26-3.prod.atl-paas.net/rest/api/3/status/10007",
+        "statusCategory": {
+          "colorName": "blue-gray",
+          "id": 2,
+          "key": "new",
+          "name": "To Do",
+          "self": "https://jira-prod-us-26-3.prod.atl-paas.net/rest/api/3/statuscategory/2"
+        }
+      },
+      "summary": "OpsDB Sync Validation Bug"
+    },
+    "fieldsToInclude": null,
+    "id": "155110",
+    "key": "GHCOS-41175",
+    "names": null,
+    "operations": null,
+    "properties": null,
+    "renderedFields": null,
+    "schema": null,
+    "self": "https://jira-prod-us-26-3.prod.atl-paas.net/rest/api/3/issue/155110",
+    "transitions": null,
+    "versionedRepresentations": null
+  }
+]

package/internal/task/jira/transition_defaults_test.go

@@ -0,0 +1,156 @@
+package jira
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/task"
+)
+
+// 3.5: Jira transition defaults per specs/workflow-definition "Jira
+// transition defaults are deterministic": omitted transitions default to
+// parent In Progress at start, mailbox In Progress at agent/HITL work
+// nodes, and parent Done at end; an omitted work-node parent transition
+// leaves the parent unchanged.
+//
+// This test is package-local (package jira) so it can drive the adapter's
+// ApplyTaskConfig against a test-local fake ACLI without inventing an
+// exported production constructor seam. The adapter resolves defaults
+// internally; the fake records the transitions the adapter issues.
+
+// fakeACLI is a test-local fakeable ACLI boundary recording transitions and
+// serving a fixed search batch for Poll.
+type fakeACLI struct {
+	parentTransitions []string
+	taskTransitions   []string
+	assignments       []string
+	assignErr         error
+	events            []string
+	// searchJSON is the raw Jira search response Poll serves.
+	searchJSON []byte
+}
+
+func (f *fakeACLI) transition(key, status string) {
+	if key == "PAY-101" {
+		f.parentTransitions = append(f.parentTransitions, status)
+	} else {
+		f.taskTransitions = append(f.taskTransitions, status)
+	}
+}
+
+// newSystemWithFake builds the adapter around the test-local fake ACLI. The
+// adapter owns its ACLI wiring; the test injects only the CLI seam.
+func newSystemWithFake(t *testing.T, fake *fakeACLI) task.System {
+	t.Helper()
+	sys, err := newSystemForTest(fake)
+	if err != nil {
+		t.Fatalf("adapter construction failed: %v", err)
+	}
+	return sys
+}
+
+func TestStartDefaultParentInProgress(t *testing.T) {
+	fake := &fakeACLI{}
+	sys := newSystemWithFake(t, fake)
+	parent := task.TicketRef{ID: "1", Key: "PAY-101", Title: "parent"}
+
+	// start: omitted transitionTo, parent-only target.
+	if err := sys.ApplyTaskConfig(context.Background(), task.Target{Parent: parent}, config.RawValues{}); err != nil {
+		t.Fatalf("ApplyTaskConfig start failed: %v", err)
+	}
+	if len(fake.parentTransitions) != 1 || fake.parentTransitions[0] != "In Progress" {
+		t.Fatalf("start parent transitions = %v, want [In Progress]", fake.parentTransitions)
+	}
+}
+
+func TestWorkNodeDefaultMailboxInProgressParentUnchanged(t *testing.T) {
+	fake := &fakeACLI{}
+	sys := newSystemWithFake(t, fake)
+	parent := task.TicketRef{ID: "1", Key: "PAY-101", Title: "parent"}
+	mb := task.Mailbox{ID: "2", Key: "PAY-102", Node: "coding"}
+
+	if err := sys.ApplyTaskConfig(context.Background(), task.Target{Parent: parent, Mailbox: &mb}, config.RawValues{}); err != nil {
+		t.Fatalf("ApplyTaskConfig failed: %v", err)
+	}
+	if len(fake.taskTransitions) != 1 || fake.taskTransitions[0] != "In Progress" {
+		t.Fatalf("mailbox transitions = %v, want [In Progress]", fake.taskTransitions)
+	}
+	if len(fake.parentTransitions) != 0 {
+		t.Fatalf("parent transitions = %v, want none (parent unchanged when omitted)", fake.parentTransitions)
+	}
+	if len(fake.assignments) != 0 {
+		t.Fatalf("mailbox assignments = %v, want none when assignee omitted", fake.assignments)
+	}
+}
+
+func TestWorkNodeAssignsMailboxBeforeTransition(t *testing.T) {
+	fake := &fakeACLI{}
+	sys := newSystemWithFake(t, fake)
+	parent := task.TicketRef{ID: "1", Key: "PAY-101", Title: "parent"}
+	mb := task.Mailbox{ID: "2", Key: "PAY-102", Node: "coding"}
+
+	err := sys.ApplyTaskConfig(context.Background(), task.Target{Parent: parent, Mailbox: &mb}, config.RawValues{
+		"assignee": "reviewer@example.com",
+	})
+	if err != nil {
+		t.Fatalf("ApplyTaskConfig failed: %v", err)
+	}
+	if len(fake.assignments) != 1 || fake.assignments[0] != "PAY-102:reviewer@example.com" {
+		t.Fatalf("mailbox assignments = %v, want [PAY-102:reviewer@example.com]", fake.assignments)
+	}
+	if len(fake.events) != 2 || fake.events[0] != "assign" || fake.events[1] != "transition" {
+		t.Fatalf("mailbox events = %v, want [assign transition]", fake.events)
+	}
+}
+
+func TestWorkNodeAssignmentFailurePreventsTransition(t *testing.T) {
+	fake := &fakeACLI{assignErr: errors.New("assignment failed")}
+	sys := newSystemWithFake(t, fake)
+	parent := task.TicketRef{ID: "1", Key: "PAY-101", Title: "parent"}
+	mb := task.Mailbox{ID: "2", Key: "PAY-102", Node: "coding"}
+
+	err := sys.ApplyTaskConfig(context.Background(), task.Target{Parent: parent, Mailbox: &mb}, config.RawValues{
+		"assignee": "reviewer@example.com",
+	})
+	if err == nil || len(fake.taskTransitions) != 0 {
+		t.Fatalf("ApplyTaskConfig error = %v, transitions = %v", err, fake.taskTransitions)
+	}
+}
+
+func TestEndDefaultParentDone(t *testing.T) {
+	fake := &fakeACLI{}
+	sys := newSystemWithFake(t, fake)
+	parent := task.TicketRef{ID: "1", Key: "PAY-101", Title: "parent"}
+
+	// end: omitted transitionTo. The end effective config carries no
+	// transition; the adapter must still default the parent to Done. Run
+	// orchestration applies the end node config to the parent target.
+	if err := sys.ApplyTaskConfig(context.Background(), task.Target{Parent: parent}, endConfig(config.RawValues{})); err != nil {
+		t.Fatalf("ApplyTaskConfig end failed: %v", err)
+	}
+	if len(fake.parentTransitions) != 1 || fake.parentTransitions[0] != "Done" {
+		t.Fatalf("end parent transitions = %v, want [Done]", fake.parentTransitions)
+	}
+}
+
+func TestExplicitTransitionsWin(t *testing.T) {
+	fake := &fakeACLI{}
+	sys := newSystemWithFake(t, fake)
+	parent := task.TicketRef{ID: "1", Key: "PAY-101", Title: "parent"}
+	mb := task.Mailbox{ID: "2", Key: "PAY-102", Node: "review"}
+
+	err := sys.ApplyTaskConfig(context.Background(), task.Target{Parent: parent, Mailbox: &mb}, config.RawValues{
+		"transitionTo": map[string]any{"parentStatus": "In Review", "taskStatus": "In Review"},
+	})
+	if err != nil {
+		t.Fatalf("ApplyTaskConfig failed: %v", err)
+	}
+	if len(fake.parentTransitions) != 1 || fake.parentTransitions[0] != "In Review" {
+		t.Fatalf("parent transitions = %v, want [In Review]", fake.parentTransitions)
+	}
+	if len(fake.taskTransitions) != 1 || fake.taskTransitions[0] != "In Review" {
+		t.Fatalf("mailbox transitions = %v, want [In Review]", fake.taskTransitions)
+	}
+}

package/internal/task/jira/validation_test.go

@@ -0,0 +1,94 @@
+package jira
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/task"
+)
+
+type validationClient struct {
+	fakeClient
+	assignees []string
+	statuses  []string
+}
+
+func (c *validationClient) ValidateAssignee(_ context.Context, assignee string) error {
+	c.assignees = append(c.assignees, assignee)
+	if assignee == "missing" {
+		return errors.New("invalid assignee")
+	}
+	return nil
+}
+
+func (c *validationClient) ValidateStatus(_ context.Context, project, status string) error {
+	c.statuses = append(c.statuses, project+":"+status)
+	if status == "DO Done" {
+		return errors.New("invalid status")
+	}
+	return nil
+}
+
+func TestNewSystemRejectsInvalidAssignee(t *testing.T) {
+	client := &validationClient{}
+	_, err := newSystem(context.Background(), client, taskSpec(config.RawValues{"assignee": "missing"}, nil))
+	if err == nil || !strings.Contains(err.Error(), `assignee "missing"`) {
+		t.Fatalf("newSystem error = %v", err)
+	}
+	if len(client.assignees) != 1 || client.assignees[0] != "missing" {
+		t.Fatalf("validated assignees = %v", client.assignees)
+	}
+}
+
+func TestValidateConfigProbesMergedTransitionStatusesWithoutMutation(t *testing.T) {
+	client := &validationClient{}
+	sys, err := newSystem(context.Background(), client, taskSpec(config.RawValues{"assignee": "valid"}, nil))
+	if err != nil {
+		t.Fatal(err)
+	}
+	wf := config.RawValues{"transitionTo": map[string]any{"parentStatus": "In Review"}}
+	node := config.RawValues{"transitionTo": map[string]any{"taskStatus": "DO Done"}}
+	err = sys.ValidateConfig(context.Background(), wf, map[string]config.RawValues{"review": node})
+	if err == nil || !strings.Contains(err.Error(), `node "review" taskStatus "DO Done"`) {
+		t.Fatalf("ValidateConfig error = %v", err)
+	}
+	if got := wf["transitionTo"].(map[string]any); len(got) != 1 || got["parentStatus"] != "In Review" {
+		t.Fatalf("workflow config mutated: %v", wf)
+	}
+	if got := node["transitionTo"].(map[string]any); len(got) != 1 || got["taskStatus"] != "DO Done" {
+		t.Fatalf("node config mutated: %v", node)
+	}
+}
+
+func TestNewSystemRejectsInvalidRepoTransitionStatus(t *testing.T) {
+	client := &validationClient{}
+	_, err := newSystem(context.Background(), client, taskSpec(nil, config.RawValues{
+		"project": "PAY", "component": "api",
+		"transitionTo": map[string]any{"parentStatus": "DO Done"},
+	}))
+	if err == nil || !strings.Contains(err.Error(), `repo config parentStatus "DO Done"`) {
+		t.Fatalf("newSystem error = %v", err)
+	}
+}
+
+func TestValidateConfigProbesWorkflowAssignee(t *testing.T) {
+	client := &validationClient{}
+	sys, err := newSystem(context.Background(), client, taskSpec(nil, nil))
+	if err != nil {
+		t.Fatal(err)
+	}
+	err = sys.ValidateConfig(context.Background(), config.RawValues{"assignee": "missing"}, nil)
+	if err == nil || !strings.Contains(err.Error(), `workflow assignee "missing"`) {
+		t.Fatalf("ValidateConfig error = %v", err)
+	}
+}
+
+func taskSpec(root, repo config.RawValues) task.RepoSpec {
+	if repo == nil {
+		repo = config.RawValues{"project": "PAY", "component": "api"}
+	}
+	return task.RepoSpec{Name: "payments", RootConfig: root, RepoConfig: repo}
+}

package/internal/task/task.go

@@ -0,0 +1,84 @@
+// Package task defines task-system values and the System contract. Run IDs,
+// node visits, reports, and orchestration inputs belong to run, not here.
+package task
+
+import (
+	"context"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+)
+
+type Ticket struct {
+	ID             string
+	Key            string
+	Title          string
+	WorkflowClaims []string
+	Fields         map[string]any
+}
+
+type TicketRef struct {
+	ID    string `json:"id"`
+	Key   string `json:"key"`
+	Title string `json:"title"`
+}
+
+func (t Ticket) Ref() TicketRef {
+	return TicketRef{ID: t.ID, Key: t.Key, Title: t.Title}
+}
+
+type Mailbox struct {
+	ID   string `json:"id"`
+	Key  string `json:"key"`
+	Node string `json:"node"`
+}
+
+type MailboxSpec struct {
+	Node        string           `json:"node"`
+	Title       string           `json:"title"`
+	Description string           `json:"description"`
+	TaskConfig  config.RawValues `json:"taskConfig,omitempty"`
+}
+
+type Target struct {
+	Parent  TicketRef
+	Mailbox *Mailbox
+}
+
+// System is the task-system contract. One instance is created per
+// registered repo and is safe for concurrent use.
+//
+// Poll returns active parent tickets only; mailbox subtasks are never
+// routed as workflow runs. EnsureMailboxes is the sole mailbox discovery
+// operation: it finds existing child mailboxes, creates only missing ones,
+// and returns the complete node-to-mailbox map. Each method is idempotent
+// where the task system permits; adapters own reconciliation when one
+// method requires multiple remote calls.
+type System interface {
+	Poll(ctx context.Context) ([]Ticket, error)
+	CompileFilter(workflowTaskConfig config.RawValues) (func(Ticket) bool, error)
+	Claim(ctx context.Context, ticket TicketRef, workflow string) error
+
+	ValidateConfig(ctx context.Context, workflowTaskConfig config.RawValues, nodeTaskConfigs map[string]config.RawValues) error
+	EnsureMailboxes(ctx context.Context, parent TicketRef, workflow string, specs []MailboxSpec) (map[string]Mailbox, error)
+	ApplyTaskConfig(ctx context.Context, target Target, taskConfig config.RawValues) error
+	CompleteMailbox(ctx context.Context, mailbox Mailbox) error
+	HasComment(ctx context.Context, target Target, marker string) (bool, error)
+	Comment(ctx context.Context, target Target, body, marker string) error
+	ResetForRecovery(ctx context.Context, parent TicketRef, mailboxes []Mailbox, taskConfig config.RawValues) error
+}
+
+// LifecycleDefaults is an optional adapter capability: a System whose
+// taskConfig carries lifecycle-dependent defaults (e.g. Jira's deterministic
+// transitionTo defaults) exposes them here. The lifecycle-aware caller
+// (run orchestration) merges the returned raw values into the effective node
+// config before ApplyTaskConfig based on whether the node is start, a work
+// node, or end. Core never learns adapter vocabulary; the adapter never
+// learns lifecycle steps. The System interface is unchanged.
+type LifecycleDefaults interface {
+	// StartDefaults are merged under the start node's taskConfig.
+	StartDefaults() config.RawValues
+	// WorkDefaults are merged under every work node's taskConfig.
+	WorkDefaults() config.RawValues
+	// EndDefaults are merged under the end node's taskConfig.
+	EndDefaults() config.RawValues
+}

package/internal/workflow/report.go

@@ -0,0 +1,85 @@
+package workflow
+
+import (
+	"fmt"
+	"strings"
+)
+
+// Structured report contract. All strings are required; the literal "None"
+// represents an intentionally empty section.
+const None = "None"
+
+type Summary struct {
+	Completed        string `json:"completed"`
+	Commits          string `json:"commits"`
+	NotCompleted     string `json:"notCompleted"`
+	IssuesDiscovered string `json:"issuesDiscovered"`
+	Verification     string `json:"verification"`
+	Notes            string `json:"notes"`
+}
+
+type Feedback struct {
+	ReasonForNextStep string `json:"reasonForNextStep"`
+	RequiredActions   string `json:"requiredActions"`
+	RelevantContext   string `json:"relevantContext"`
+	ExpectedResult    string `json:"expectedResult"`
+}
+
+type Report struct {
+	Status   Outcome  `json:"status"`
+	NextStep string   `json:"nextStep"`
+	Summary  Summary  `json:"summary"`
+	Feedback Feedback `json:"feedback"`
+}
+
+// ValidateReport verifies every section, the outcome, and that NextStep
+// names exactly one configured target for that outcome. When NextStep is
+// end, every feedback field must be None. It is pure and is called both at
+// the server boundary and inside durable execution.
+func (w *Workflow) ValidateReport(node string, report Report) error {
+	if _, ok := w.Nodes[node]; !ok {
+		return fmt.Errorf("workflow %q has no node %q", w.Name, node)
+	}
+	if report.Status != OutcomeSuccess && report.Status != OutcomeFailure {
+		return fmt.Errorf("report status %q must be %q or %q", report.Status, OutcomeSuccess, OutcomeFailure)
+	}
+	for _, field := range []struct{ name, value string }{
+		{"summary.completed", report.Summary.Completed},
+		{"summary.commits", report.Summary.Commits},
+		{"summary.notCompleted", report.Summary.NotCompleted},
+		{"summary.issuesDiscovered", report.Summary.IssuesDiscovered},
+		{"summary.verification", report.Summary.Verification},
+		{"summary.notes", report.Summary.Notes},
+		{"feedback.reasonForNextStep", report.Feedback.ReasonForNextStep},
+		{"feedback.requiredActions", report.Feedback.RequiredActions},
+		{"feedback.relevantContext", report.Feedback.RelevantContext},
+		{"feedback.expectedResult", report.Feedback.ExpectedResult},
+		{"nextStep", report.NextStep},
+	} {
+		if field.value == "" {
+			return fmt.Errorf("report section %s is required (use %q for an intentionally empty section)", field.name, None)
+		}
+	}
+	routes, err := w.Routes(node, report.Status)
+	if err != nil {
+		return err
+	}
+	legal := false
+	for _, r := range routes {
+		if r.Target == report.NextStep {
+			legal = true
+			break
+		}
+	}
+	if !legal {
+		return fmt.Errorf("report nextStep %q is not a configured %s target for node %q; valid targets: %s",
+			report.NextStep, report.Status, node, strings.Join(sortedTargets(routes), ", "))
+	}
+	if report.NextStep == EndNode {
+		f := report.Feedback
+		if f.ReasonForNextStep != None || f.RequiredActions != None || f.RelevantContext != None || f.ExpectedResult != None {
+			return fmt.Errorf("report selects %q: every feedback field must be %q because end has no mailbox", EndNode, None)
+		}
+	}
+	return nil
+}