relay-flow 0.2.8-alpha → 0.2.9-alpha

package/internal/runner/orca/orcacli/orcacli.go

@@ -57,8 +57,22 @@ type Client interface {
 // CLI is the production Client backed by the orca binary.
 type CLI struct{}
 
+// RepoRegistrar is the optional repository-provisioning seam used by the
+// runner adapter. Keeping it separate from Client lets existing read-only
+// test clients remain focused on the runtime operations they exercise.
+type RepoRegistrar interface {
+	AddRepo(ctx context.Context, path string) error
+}
+
 func New() *CLI { return &CLI{} }
 
+// AddRepo registers an existing local repository with Orca. Orca derives its
+// display name from the path; relay-flow keeps the user-facing registration
+// name separately.
+func (CLI) AddRepo(ctx context.Context, path string) error {
+	return run(ctx, "repo", "add", "--path", path, "--json")
+}
+
 func (CLI) ListRepos(ctx context.Context) ([]Repo, error) {
 	var res struct {
 		Result struct {
@@ -194,7 +208,13 @@ func (CLI) CreateTerminal(ctx context.Context, ticketKey, title, command string)
 }
 
 func (CLI) CloseTerminal(ctx context.Context, handle string) error {
-	return run(ctx, "terminal", "close", "--terminal", handle, "--json")
+	if err := run(ctx, "terminal", "close", "--terminal", handle, "--json"); err != nil {
+		if strings.Contains(err.Error(), "terminal_handle_stale") {
+			return ErrTerminalUnavailable
+		}
+		return err
+	}
+	return nil
 }
 
 func run(ctx context.Context, args ...string) error {

package/internal/runner/orca/orcacli/orcacli_test.go

@@ -2,6 +2,7 @@ package orcacli
 
 import (
 	"context"
+	"errors"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -30,6 +31,9 @@ func TestCLIContractsAgainstCapturedRealOutput(t *testing.T) {
 		t.Fatalf("ListWorktrees = %+v", worktrees)
 	}
 
+	if err := cli.AddRepo(ctx, "/work/new"); err != nil {
+		t.Fatal(err)
+	}
 	if err := cli.CreateWorktree(ctx, "PAY-101", "repo-1", "wt-main", "origin/alice/PAY-101"); err != nil {
 		t.Fatal(err)
 	}
@@ -80,6 +84,24 @@ func TestStrictFakeOrcaRejectsMissingFlags(t *testing.T) {
 	}
 }
 
+func TestCloseTerminalMapsStaleHandleToUnavailable(t *testing.T) {
+	installStrictFakeOrca(t)
+	cli := New()
+
+	err := cli.CloseTerminal(context.Background(), "term-stale")
+	if !errors.Is(err, ErrTerminalUnavailable) {
+		t.Fatalf("CloseTerminal(stale) = %v, want ErrTerminalUnavailable", err)
+	}
+
+	err = cli.CloseTerminal(context.Background(), "term-unknown")
+	if err == nil {
+		t.Fatal("CloseTerminal(unknown) = nil, want the CLI failure")
+	}
+	if errors.Is(err, ErrTerminalUnavailable) {
+		t.Fatalf("CloseTerminal(unknown) = %v, incorrectly classified as stale", err)
+	}
+}
+
 func TestFindExistingBranchLocalOnly(t *testing.T) {
 	repo := newGitRepo(t)
 	runGit(t, repo, "branch", "alice/PAY-101")

package/internal/runner/orca/orcacli/testdata/strict-orca.sh

@@ -4,6 +4,8 @@ set -eu
 fixture=
 if [ "$#" -eq 3 ] && [ "$1" = repo ] && [ "$2" = list ] && [ "$3" = --json ]; then
   fixture=repo-list.json
+elif [ "$#" -eq 5 ] && [ "$1" = repo ] && [ "$2" = add ] && [ "$3" = --path ] && [ "$4" = /work/new ] && [ "$5" = --json ]; then
+  fixture=repo-list.json
 elif [ "$#" -eq 3 ] && [ "$1" = worktree ] && [ "$2" = list ] && [ "$3" = --json ]; then
   fixture=worktree-list.json
 elif [ "$#" -eq 11 ] && [ "$1" = worktree ] && [ "$2" = create ] && [ "$3" = --name ] && [ "$4" = PAY-101 ] && [ "$5" = --repo ] && [ "$6" = id:repo-1 ] && [ "$7" = --parent-worktree ] && [ "$8" = worktree:wt-main ] && [ "$9" = --base-branch ] && [ "${10}" = origin/alice/PAY-101 ] && [ "${11}" = --json ]; then
@@ -20,6 +22,9 @@ elif [ "$#" -eq 8 ] && [ "$1" = terminal ] && [ "$2" = send ] && [ "$3" = --term
   fixture=terminal-send.json
 elif [ "$#" -eq 9 ] && [ "$1" = terminal ] && [ "$2" = create ] && [ "$3" = --worktree ] && [ "$4" = name:PAY-101 ] && [ "$5" = --title ] && [ "$6" = PAY-101:implement ] && [ "$7" = --command ] && [ "$8" = 'echo hello' ] && [ "$9" = --json ]; then
   fixture=terminal-create.json
+elif [ "$#" -eq 5 ] && [ "$1" = terminal ] && [ "$2" = close ] && [ "$3" = --terminal ] && [ "$4" = term-stale ] && [ "$5" = --json ]; then
+  printf '%s\n' '{"ok":false,"error":{"code":"terminal_handle_stale","message":"terminal_handle_stale"}}'
+  exit 1
 elif [ "$#" -eq 5 ] && [ "$1" = terminal ] && [ "$2" = close ] && [ "$3" = --terminal ] && [ "$4" = term-1 ] && [ "$5" = --json ]; then
   fixture=terminal-close.json
 else

package/internal/runner/runner.go

@@ -24,6 +24,15 @@ type RepoCandidate struct {
 	Path string `json:"path"`
 }
 
+// RepoRegistrar is the optional runner capability used by repository
+// registration. Runners that manage an external repository/workspace can
+// make the resource available before relay-flow persists the repo entry.
+// Runners without a provisioning primitive still use ValidateRepo through
+// the repo service.
+type RepoRegistrar interface {
+	EnsureRepo(context.Context, string, string) error
+}
+
 type Environment struct {
 	ID   string `json:"id"`
 	Path string `json:"path"`

package/internal/server/api_test.go

@@ -14,6 +14,7 @@ import (
 
 	"github.com/rajpopat27/relay-flow/internal/config"
 	"github.com/rajpopat27/relay-flow/internal/run"
+	"github.com/rajpopat27/relay-flow/internal/runner"
 	"github.com/rajpopat27/relay-flow/internal/server"
 	"github.com/rajpopat27/relay-flow/internal/task"
 	"github.com/rajpopat27/relay-flow/internal/workflow"
@@ -333,6 +334,24 @@ func TestClientRepoRegistrationFieldsUsesGetThenPost(t *testing.T) {
 	}
 }
 
+func TestRepoEnsureEndpoint(t *testing.T) {
+	fake := &fakeServices{}
+	c, cleanup := startHandler(t, fake)
+	defer cleanup()
+	code, env := do(t, c, http.MethodPost, "http://relay/repos/ensure", []byte(`{"name":"payments","path":"/srv/payments"}`))
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("POST /repos/ensure: code=%d env=%+v, want 200 ok", code, env)
+	}
+	if len(fake.ensureRepoCalls) != 1 || fake.ensureRepoCalls[0] != (runner.RepoCandidate{Name: "payments", Path: "/srv/payments"}) {
+		t.Fatalf("EnsureRepo calls = %+v", fake.ensureRepoCalls)
+	}
+
+	code, env = do(t, c, http.MethodPost, "http://relay/repos/ensure", []byte(`{"name":"payments"}`))
+	if code != http.StatusBadRequest || env.OK {
+		t.Fatalf("invalid POST /repos/ensure: code=%d env=%+v, want 400", code, env)
+	}
+}
+
 func TestRepoOperations(t *testing.T) {
 	c, cleanup := startHandler(t, &fakeServices{})
 	defer cleanup()

package/internal/server/client.go

@@ -136,6 +136,16 @@ func (c *Client) DiscoverRepos(ctx context.Context) ([]runner.RepoCandidate, err
 	return out, nil
 }
 
+// EnsureRepo asks the configured runner to make a repository resource
+// available without persisting a relay-flow repo entry.
+func (c *Client) EnsureRepo(ctx context.Context, candidate runner.RepoCandidate) error {
+	payload, err := json.Marshal(candidate)
+	if err != nil {
+		return err
+	}
+	return c.call(ctx, http.MethodPost, "/repos/ensure", payload, nil)
+}
+
 // RepoTaskFields returns the documented initial required-key metadata.
 func (c *Client) RepoTaskFields(ctx context.Context) ([]string, error) {
 	var out struct {

package/internal/server/fixture_test.go

@@ -40,6 +40,8 @@ type fakeServices struct {
 	restartErr         error
 	restarts           []string
 	registrationValues []config.RawValues
+	ensureRepoCalls    []runner.RepoCandidate
+	ensureRepoErr      error
 }
 
 func (f *fakeServices) SubmitWorkflow(_ context.Context, yaml []byte) (*workflow.Workflow, error) {
@@ -155,6 +157,11 @@ func (f *fakeServices) DiscoverRepos(context.Context) ([]runner.RepoCandidate, e
 	return []runner.RepoCandidate{{Name: "payments", Path: "/srv/payments"}}, nil
 }
 
+func (f *fakeServices) EnsureRepo(_ context.Context, candidate runner.RepoCandidate) error {
+	f.ensureRepoCalls = append(f.ensureRepoCalls, candidate)
+	return f.ensureRepoErr
+}
+
 func (f *fakeServices) TaskRegistrationFields(_ context.Context, values config.RawValues) ([]task.RegistrationField, error) {
 	f.registrationValues = append(f.registrationValues, values)
 	return []task.RegistrationField{{Key: "project", Title: "Project"}, {Key: "component", Title: "Component", Derived: true}}, nil

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) {
@@ -247,6 +256,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)

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.9-alpha",
   "description": "Graph-based agent workflow engine — tracker-agnostic, pluggable runners",
   "bin": {
     "relay-flow": "./bin/relay-flow.js",