relay-flow 0.2.8-alpha → 0.2.10-alpha

package/internal/server/observability.go

@@ -0,0 +1,109 @@
+package server
+
+import (
+	"context"
+	"sort"
+
+	"github.com/rajpopat27/relay-flow/internal/run"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+// WorkflowSummary is a read-only consumer DTO for compact workflow listing.
+// The embedded definition keeps the existing JSON fields available while the
+// additive fields provide the one-request execution summary used by the CLI.
+type WorkflowSummary struct {
+	*workflow.Workflow
+	Repositories []string `json:"repositories,omitempty"`
+	NodeCount    int      `json:"nodeCount"`
+	ActiveRuns   int      `json:"activeRuns"`
+	LatestRun    *run.Run `json:"latestRun,omitempty"`
+}
+
+// WorkflowDetail is a read-only query DTO. It deliberately contains domain
+// values only; no executor, database, runner, or task-system implementation
+// type crosses the Unix-socket boundary.
+type WorkflowDetail struct {
+	*workflow.Workflow
+	Valid      bool      `json:"valid"`
+	ActiveRuns int       `json:"activeRuns"`
+	RecentRuns []run.Run `json:"recentRuns"`
+}
+
+// WorkflowSummaryQueries is an optional server capability. Keeping it
+// separate from Deps preserves the small existing service contract for test
+// fakes and older composition roots.
+type WorkflowSummaryQueries interface {
+	ListWorkflowSummaries(context.Context) ([]WorkflowSummary, error)
+}
+
+type WorkflowDetailQueries interface {
+	GetWorkflowDetail(context.Context, string) (WorkflowDetail, error)
+}
+
+type RunDetailQueries interface {
+	GetRunDetail(context.Context, string) (run.RunDetail, error)
+}
+
+// BuildWorkflowSummaries computes all summaries from one workflow list and one
+// run list. The helper is used by the composition root and is intentionally
+// independent of a durable executor implementation.
+func BuildWorkflowSummaries(workflows []*workflow.Workflow, runs []run.Run) []WorkflowSummary {
+	latest := map[string]run.Run{}
+	active := map[string]int{}
+	for _, candidate := range runs {
+		if current, ok := latest[candidate.Workflow]; !ok || newerRun(candidate, current) {
+			latest[candidate.Workflow] = candidate
+		}
+		if candidate.State != run.StateCompleted && candidate.State != run.StateCanceled {
+			active[candidate.Workflow]++
+		}
+	}
+	out := make([]WorkflowSummary, 0, len(workflows))
+	for _, wf := range workflows {
+		if wf == nil {
+			continue
+		}
+		repos := append([]string(nil), wf.Repos...)
+		sort.Strings(repos)
+		var latestRun *run.Run
+		if candidate, ok := latest[wf.Name]; ok {
+			copy := candidate
+			latestRun = &copy
+		}
+		out = append(out, WorkflowSummary{
+			Workflow: wf, Repositories: repos, NodeCount: len(wf.Nodes),
+			ActiveRuns: active[wf.Name], LatestRun: latestRun,
+		})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out
+}
+
+func newerRun(candidate, current run.Run) bool {
+	if candidate.StartedAt.After(current.StartedAt) {
+		return true
+	}
+	return candidate.StartedAt.Equal(current.StartedAt) && candidate.UpdatedAt.After(current.UpdatedAt)
+}
+
+// BuildWorkflowDetail builds the static-definition plus recent execution
+// summary response without changing workflow validation or execution.
+func BuildWorkflowDetail(wf *workflow.Workflow, runs []run.Run) WorkflowDetail {
+	recent := append([]run.Run(nil), runs...)
+	sort.SliceStable(recent, func(i, j int) bool {
+		if recent[i].UpdatedAt.Equal(recent[j].UpdatedAt) {
+			return recent[i].StartedAt.After(recent[j].StartedAt)
+		}
+		return recent[i].UpdatedAt.After(recent[j].UpdatedAt)
+	})
+	if len(recent) > 5 {
+		recent = recent[:5]
+	}
+	active := 0
+	for _, candidate := range runs {
+		if candidate.State != run.StateCompleted && candidate.State != run.StateCanceled {
+			active++
+		}
+	}
+	return WorkflowDetail{Workflow: wf, Valid: wf != nil, ActiveRuns: active, RecentRuns: recent}
+}

package/internal/server/observability_test.go

@@ -0,0 +1,60 @@
+package server
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/run"
+	"github.com/rajpopat27/relay-flow/internal/task"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+func TestWorkflowSummaryKeepsDefinitionFieldsOnJSONRoundTrip(t *testing.T) {
+	definition := &workflow.Workflow{Name: "basicFlow", Repos: []string{"payments"}, Nodes: map[string]workflow.Node{"start": {}, "end": {}}}
+	summary := WorkflowSummary{Workflow: definition, Repositories: []string{"payments"}, NodeCount: 2, ActiveRuns: 1}
+	raw, err := json.Marshal(summary)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var decoded WorkflowSummary
+	if err := json.Unmarshal(raw, &decoded); err != nil {
+		t.Fatal(err)
+	}
+	if decoded.Workflow == nil || decoded.Name != definition.Name || decoded.NodeCount != 2 || decoded.ActiveRuns != 1 {
+		t.Fatalf("decoded summary = %#v", decoded)
+	}
+	arrayRaw, err := json.Marshal([]WorkflowSummary{summary})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var legacy []*workflow.Workflow
+	if err := json.Unmarshal(arrayRaw, &legacy); err != nil || len(legacy) != 1 || legacy[0].Name != definition.Name {
+		t.Fatalf("legacy workflow decode = %#v, err=%v", legacy, err)
+	}
+	baseRaw, err := json.Marshal([]*workflow.Workflow{definition})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var fallback []WorkflowSummary
+	if err := json.Unmarshal(baseRaw, &fallback); err != nil || len(fallback) != 1 || fallback[0].Workflow == nil || fallback[0].Name != definition.Name {
+		t.Fatalf("fallback summary decode = %#v, err=%v", fallback, err)
+	}
+}
+
+func TestBuildWorkflowSummariesUsesLatestRunAndActiveCount(t *testing.T) {
+	start := time.Now().UTC().Add(-time.Hour)
+	workflows := []*workflow.Workflow{
+		{Name: "basicFlow", Repos: []string{"payments"}, Nodes: map[string]workflow.Node{
+			"start": {}, "end": {},
+		}},
+	}
+	runs := []run.Run{
+		{Workflow: "basicFlow", State: run.StateCompleted, StartedAt: start, UpdatedAt: start.Add(10 * time.Minute), Ticket: task.TicketRef{Key: "PAY-1"}},
+		{Workflow: "basicFlow", State: run.StateWaiting, StartedAt: start.Add(time.Minute), UpdatedAt: start.Add(20 * time.Minute), Ticket: task.TicketRef{Key: "PAY-2"}},
+	}
+	got := BuildWorkflowSummaries(workflows, runs)
+	if len(got) != 1 || got[0].ActiveRuns != 1 || got[0].LatestRun == nil || got[0].LatestRun.Ticket.Key != "PAY-2" {
+		t.Fatalf("summaries = %#v", got)
+	}
+}

package/internal/server/server.go

@@ -85,6 +85,7 @@ func New(deps Deps) http.Handler {
 	mux.HandleFunc("/workflows", s.handleWorkflows)
 	mux.HandleFunc("/workflows/", s.handleWorkflowByName)
 	mux.HandleFunc("/repos/discover", s.handleReposDiscover)
+	mux.HandleFunc("/repos/ensure", s.handleRepoEnsure)
 	mux.HandleFunc("/repos/task-fields", s.handleRepoTaskFields)
 	mux.HandleFunc("/repos", s.handleRepos)
 	mux.HandleFunc("/repos/", s.handleRepoByName)
@@ -99,6 +100,14 @@ type server struct {
 	deps Deps
 }
 
+// repoEnsurer is implemented by the composition root when the selected
+// runner can provision a repository resource. It is intentionally separate
+// from Deps so existing task/run service seams do not need a runner-specific
+// method.
+type repoEnsurer interface {
+	EnsureRepo(context.Context, runner.RepoCandidate) error
+}
+
 // --- envelope helpers ---
 
 func writeOK(w http.ResponseWriter, status int, data any) {
@@ -122,6 +131,8 @@ func mapErr(w http.ResponseWriter, err error) {
 	switch {
 	case errors.Is(err, run.ErrRestartConflict):
 		writeErr(w, http.StatusConflict, "conflict", err.Error())
+	case errors.Is(err, run.ErrNotFound):
+		writeErr(w, http.StatusNotFound, "notFound", err.Error())
 	case errors.Is(err, ErrNotFound):
 		writeErr(w, http.StatusNotFound, "notFound", err.Error())
 	case errors.Is(err, ErrConflict):
@@ -182,6 +193,18 @@ func (s *server) handleStop(w http.ResponseWriter, r *http.Request) {
 func (s *server) handleWorkflows(w http.ResponseWriter, r *http.Request) {
 	switch r.Method {
 	case http.MethodGet:
+		// The summary DTO embeds the original definition, so returning it is
+		// additive for clients that still decode []workflow.Workflow. Older
+		// composition roots without this optional capability use the base list.
+		if queries, ok := s.deps.(WorkflowSummaryQueries); ok {
+			summaries, err := queries.ListWorkflowSummaries(r.Context())
+			if err != nil {
+				mapErr(w, err)
+				return
+			}
+			writeOK(w, http.StatusOK, summaries)
+			return
+		}
 		wfs, err := s.deps.ListWorkflows(r.Context())
 		if err != nil {
 			mapErr(w, err)
@@ -216,6 +239,15 @@ func (s *server) handleWorkflowByName(w http.ResponseWriter, r *http.Request) {
 	}
 	switch r.Method {
 	case http.MethodGet:
+		if queries, ok := s.deps.(WorkflowDetailQueries); ok {
+			detail, err := queries.GetWorkflowDetail(r.Context(), name)
+			if err != nil {
+				mapErr(w, err)
+				return
+			}
+			writeOK(w, http.StatusOK, detail)
+			return
+		}
 		wf, err := s.deps.GetWorkflow(r.Context(), name)
 		if err != nil {
 			mapErr(w, err)
@@ -247,6 +279,38 @@ func (s *server) handleReposDiscover(w http.ResponseWriter, r *http.Request) {
 	writeOK(w, http.StatusOK, candidates)
 }
 
+func (s *server) handleRepoEnsure(w http.ResponseWriter, r *http.Request) {
+	if !methodOnly(w, r, http.MethodPost) {
+		return
+	}
+	ensurer, ok := s.deps.(repoEnsurer)
+	if !ok {
+		mapErr(w, fmt.Errorf("%w: runner repository provisioning is unavailable", ErrInvalid))
+		return
+	}
+	body, err := readBody(r)
+	if err != nil {
+		writeErr(w, http.StatusBadRequest, "invalid", err.Error())
+		return
+	}
+	var candidate runner.RepoCandidate
+	if err := decodeStrict(body, &candidate); err != nil {
+		writeErr(w, http.StatusBadRequest, "invalid", err.Error())
+		return
+	}
+	candidate.Name = strings.TrimSpace(candidate.Name)
+	candidate.Path = strings.TrimSpace(candidate.Path)
+	if candidate.Name == "" || candidate.Path == "" {
+		writeErr(w, http.StatusBadRequest, "invalid", "repository name and path are required")
+		return
+	}
+	if err := ensurer.EnsureRepo(r.Context(), candidate); err != nil {
+		mapErr(w, err)
+		return
+	}
+	writeOK(w, http.StatusOK, candidate)
+}
+
 func (s *server) handleRepoTaskFields(w http.ResponseWriter, r *http.Request) {
 	if r.Method == http.MethodGet {
 		fields, err := s.deps.TaskRegistrationFields(r.Context(), nil)
@@ -503,6 +567,10 @@ func (s *server) handleRuns(w http.ResponseWriter, r *http.Request) {
 	filter.Repo = q.Get("repo")
 	filter.Workflow = q.Get("workflow")
 	filter.Ticket = q.Get("ticket")
+	if active := q.Get("active"); active != "" {
+		value := active == "1" || strings.EqualFold(active, "true")
+		filter.Active = &value
+	}
 	runs, err := s.deps.ListRuns(r.Context(), filter)
 	if err != nil {
 		mapErr(w, err)
@@ -521,6 +589,15 @@ func (s *server) handleRunByTicket(w http.ResponseWriter, r *http.Request) {
 		if !methodOnly(w, r, http.MethodGet) {
 			return
 		}
+		if queries, ok := s.deps.(RunDetailQueries); ok {
+			detail, err := queries.GetRunDetail(r.Context(), parts[0])
+			if err != nil {
+				mapErr(w, err)
+				return
+			}
+			writeOK(w, http.StatusOK, detail)
+			return
+		}
 		rn, err := s.deps.GetRunByTicket(r.Context(), parts[0])
 		if err != nil {
 			mapErr(w, err)

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

@@ -15,7 +15,7 @@
           "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",
+        "emailAddress": "test.user@example.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"
       },
@@ -48,7 +48,7 @@
     },
     "fieldsToInclude": null,
     "id": "157320",
-    "key": "GHCOS-41242",
+    "key": "DEMO-41242",
     "names": null,
     "operations": null,
     "properties": null,
@@ -74,7 +74,7 @@
           "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",
+        "emailAddress": "test.user@example.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"
       },
@@ -107,7 +107,7 @@
     },
     "fieldsToInclude": null,
     "id": "155110",
-    "key": "GHCOS-41175",
+    "key": "DEMO-41175",
     "names": null,
     "operations": null,
     "properties": null,

package/internal/workflow/workflow.go

@@ -62,6 +62,7 @@ type NudgeTemplateData struct {
 	Workflow   string
 	Repo       string
 	Node       string
+	Mailbox    string
 	NextSteps  string
 }
 
@@ -70,7 +71,7 @@ var namePattern = regexp.MustCompile(`^[a-z][a-zA-Z0-9]*$`)
 var nudgeVarPattern = regexp.MustCompile(`\{\{([^{}]*)\}\}`)
 
 var knownNudgeVars = map[string]bool{
-	"taskSystem": true, "ticket": true, "workflow": true, "repo": true, "node": true, "nextSteps": true,
+	"taskSystem": true, "ticket": true, "workflow": true, "repo": true, "node": true, "mailbox": true, "nextSteps": true,
 }
 
 // Parse strictly decodes a workflow YAML document. Unknown fields and
@@ -326,6 +327,8 @@ func (w *Workflow) RenderNudge(node string, data NudgeTemplateData) (string, err
 			return data.Repo
 		case "node":
 			return data.Node
+		case "mailbox":
+			return data.Mailbox
 		case "nextSteps":
 			return data.NextSteps
 		}

package/internal/workflow/workflow_test.go

@@ -350,7 +350,7 @@ func TestValidateGraphReachability(t *testing.T) {
 
 func TestValidateNudgeTemplate(t *testing.T) {
 	t.Run("supported variables", func(t *testing.T) {
-		yaml := strings.Replace(minimalValid, "    description: Do the coding work.", "    description: Do the coding work.\n    nudgePrompt: \"{{taskSystem}} {{ticket}} {{workflow}} {{repo}} {{node}} {{nextSteps}}\"", 1)
+		yaml := strings.Replace(minimalValid, "    description: Do the coding work.", "    description: Do the coding work.\n    nudgePrompt: \"{{taskSystem}} {{ticket}} {{workflow}} {{repo}} {{node}} {{mailbox}} {{nextSteps}}\"", 1)
 		wf := parse(t, "basicFlow", yaml)
 		if err := wf.Validate(); err != nil {
 			t.Fatalf("supported nudge variables rejected: %v", err)
@@ -389,16 +389,16 @@ func TestCleanupRunnerOnEndDefaultsFalse(t *testing.T) {
 }
 
 func TestRenderNudge(t *testing.T) {
-	yaml := strings.Replace(minimalValid, "    description: Do the coding work.", "    description: Do the coding work.\n    nudgePrompt: \"task={{taskSystem}} ticket={{ticket}} wf={{workflow}} repo={{repo}} node={{node}} steps={{nextSteps}}\"", 1)
+	yaml := strings.Replace(minimalValid, "    description: Do the coding work.", "    description: Do the coding work.\n    nudgePrompt: \"task={{taskSystem}} ticket={{ticket}} wf={{workflow}} repo={{repo}} node={{node}} mailbox={{mailbox}} steps={{nextSteps}}\"", 1)
 	wf := parse(t, "basicFlow", yaml)
 	for _, taskSystem := range []string{"jira", "linear"} {
 		out, err := wf.RenderNudge("coding", workflow.NudgeTemplateData{
-			TaskSystem: taskSystem, Ticket: "PAY-101", Workflow: "basicFlow", Repo: "payments", Node: "coding", NextSteps: "end",
+			TaskSystem: taskSystem, Ticket: "PAY-101", Workflow: "basicFlow", Repo: "payments", Node: "coding", Mailbox: "PAY-101.1", NextSteps: "end",
 		})
 		if err != nil {
 			t.Fatalf("RenderNudge(%s) failed: %v", taskSystem, err)
 		}
-		want := "task=" + taskSystem + " ticket=PAY-101 wf=basicFlow repo=payments node=coding steps=end"
+		want := "task=" + taskSystem + " ticket=PAY-101 wf=basicFlow repo=payments node=coding mailbox=PAY-101.1 steps=end"
 		if out != want {
 			t.Fatalf("RenderNudge(%s) = %q, want %q", taskSystem, out, want)
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-flow",
-  "version": "0.2.8-alpha",
+  "version": "0.2.10-alpha",
   "description": "Graph-based agent workflow engine — tracker-agnostic, pluggable runners",
   "bin": {
     "relay-flow": "./bin/relay-flow.js",