relay-flow 0.2.7-alpha → 0.2.9-alpha

package/README.md

@@ -24,13 +24,13 @@ same `relay-flow-plugin` package with host-specific entrypoints.
 **OpenCode**
 
 ```sh
-opencode plugin relay-flow-plugin@0.2.7-alpha
+opencode plugin relay-flow-plugin@0.2.9-alpha
 ```
 
 **Pi**
 
 ```sh
-pi install npm:relay-flow-plugin@0.2.7-alpha
+pi install npm:relay-flow-plugin@0.2.9-alpha
 ```
 
 Pi loads the package's `pi.ts` extension from its manifest. Do not add
@@ -38,39 +38,40 @@ Pi loads the package's `pi.ts` extension from its manifest. Do not add
 
 ### 3. Initialize relay-flow
 
-Choose one task system, runner, harness, and durable executor. This example
-uses Jira, Orca, OpenCode, and the default embedded executor:
+For a first-time interactive setup, run:
 
 ```sh
-relay-flow init \
-  --task-plugin jira \
-  --runner-plugin orca \
-  --harness-plugin opencode
+relay-flow init
 ```
 
-The default executor is `goworkflows` with SQLite. To use Temporal instead,
-add `--executor-plugin temporal`, `--temporal-address <host:port>`, and
-`--temporal-namespace <name>` to the command.
-
-### 4. Authenticate the task system
+Relay-flow selects the task system, runner, harness, and durable executor,
+runs the selected task plugin's authentication flow inline, and then asks
+whether repositories should be registered now. Choosing no completes setup
+without starting a server. Choosing yes starts (or reuses) the background
+server, waits for its Unix socket, and opens the existing repository
+registration form. After registration, the server remains running; stop it
+with `relay-flow stop`.
 
-For Jira, authenticate the selected task plugin:
+The equivalent non-interactive setup keeps the independent commands available
+for scripts and existing installations. This example uses Jira, Orca,
+OpenCode, and the default embedded executor:
 
 ```sh
+relay-flow init \
+  --task-plugin jira \
+  --runner-plugin orca \
+  --harness-plugin opencode
 relay-flow task auth
+relay-flow serve --background
 ```
 
-For Beads, skip this command and initialize/authenticate the Beads workspace
+For Beads, skip `task auth` and initialize/authenticate the Beads workspace
 with `bd` and, when needed, Dolt. See [Beads task system](#beads-task-system)
-below.
-
-### 5. Start the server
-
-```sh
-relay-flow serve --background
-```
+below. The default executor is `goworkflows` with SQLite. To use Temporal
+instead, add `--executor-plugin temporal`, `--temporal-address <host:port>`,
+and `--temporal-namespace <name>` to the command.
 
-### 6. Register a repository
+### 4. Register a repository later
 
 The repository must already exist in the selected runner. For Orca:
 
@@ -81,9 +82,11 @@ relay-flow repo register
 
 For Herdr, register the repository path directly; relay-flow creates ticket
 worktrees lazily. The interactive registration asks for the task-system values
-required by the selected task plugin.
+required by the selected task plugin. `repo register` remains the standalone
+escape hatch for adding repositories after initialization and requires a
+running `relay-flow serve --background`.
 
-### 7. Submit a workflow
+### 5. Submit a workflow
 
 ```sh
 relay-flow workflow submit --file examples/minimal-jira-task-workflow.yaml
@@ -154,7 +157,7 @@ OpenCode plugin configuration uses both entrypoints. The server entrypoint is li
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["relay-flow-plugin@0.2.7-alpha"]
+  "plugin": ["relay-flow-plugin@0.2.9-alpha"]
 }
 ```
 
@@ -163,7 +166,7 @@ The native HITL approval entrypoint is listed in `.opencode/tui.json`:
 ```json
 {
   "$schema": "https://opencode.ai/tui.json",
-  "plugin": ["relay-flow-plugin@0.2.7-alpha"]
+  "plugin": ["relay-flow-plugin@0.2.9-alpha"]
 }
 ```
 
@@ -179,7 +182,7 @@ Pi plugin: install the same published package manually in Pi's global package
 settings before starting a Pi harness session:
 
 ```sh
-pi install npm:relay-flow-plugin@0.2.7-alpha
+pi install npm:relay-flow-plugin@0.2.9-alpha
 ```
 
 Relay-flow does not install or configure the package automatically. Pi resolves
@@ -199,10 +202,30 @@ internal and is never part of either plugin payload.
 
 ```sh
 relay-flow init
-relay-flow task auth
 ```
 
-`init` selects the task system, runner, harness, and durable executor (singleton options are automatic), writes machine config, and initializes the selected execution backend. `task auth` delegates authentication to that selected task plug-in. Jira prompts for its site, email, and masked API token, validates `/myself`, and owns the system-wide `credentials.yaml`; for scripts, pass `task auth --site`, `--email`, and `--token`. A normal init rerun refuses existing state. `relay-flow init --force` updates safe stopped instances while preserving durable and repo state.
+On a new interactive home, `init` selects the task system, runner, harness,
+and durable executor, runs the selected task plug-in's authentication flow,
+and asks whether to register repositories. It writes machine config and the
+selected execution backend only after authentication succeeds. A skipped
+repository setup does not start the server; selecting it starts or reuses the
+background server, waits for socket readiness, and invokes the same
+`repo register` form described below. The server remains running after a
+successful guided registration.
+
+For scripts and existing installations, keep the independent sequence:
+
+```sh
+relay-flow init --task-plugin jira --runner-plugin orca --harness-plugin opencode
+relay-flow task auth --site https://company.atlassian.net --email you@example.com --token "$JIRA_API_TOKEN"
+relay-flow serve --background
+```
+
+`task auth` delegates to the selected task plug-in. Jira prompts for its site,
+email, and masked API token when flags are omitted, validates `/myself`, and
+owns the system-wide `credentials.yaml`. A normal init rerun refuses existing
+state. `relay-flow init --force` updates safe stopped instances while
+preserving durable and repo state; it does not launch repository onboarding.
 
 For Beads, select the plugin explicitly when scripting setup:
 
@@ -234,9 +257,11 @@ workflows/<name>.yaml 0644  submitted workflow definitions
 
 ### Register a repo
 
-`repo register` and `workflow submit` are server-backed commands: start the
-server first, otherwise they fail with `dial unix ~/.relay-flow/server.sock:
-connect: no such file or directory`.
+The guided first-run flow can start the server and open repository registration
+for you. `repo register` remains a server-backed standalone command for later
+additions: if no server is running, start it with
+`relay-flow serve --background` (or rerun interactive `relay-flow init` for a
+new home).
 
 ```sh
 relay-flow serve --background
@@ -255,11 +280,23 @@ orca repo add --path /work/payments   # displayName becomes "payments"
 relay-flow repo register
 ```
 
-Shows a multi-select titled `Select repositories`; use Space to select Orca repos and Enter to confirm. Enter the Jira project once. Each repo is registered sequentially with its Orca name/path and a Jira component derived from that repo name. Earlier registrations remain if a later one fails.
+Shows a multi-select titled `Select repositories`; use Space to select Orca repos and Enter to confirm. Enter the Jira project once, then choose the repository's start, work, and end statuses from the statuses discovered for that project. Each repo is registered sequentially with its Orca name/path and a Jira component derived from that repo name. Earlier registrations remain if a later one fails.
 
 Each Jira poll uses REST v3 enhanced search and requests linked-issue status with the candidate fields. Tickets with any unfinished inward `Blocks` issue are filtered before routing; no per-ticket blocker lookup is made.
 
-For scripted Jira registration, use `relay-flow repo register --name <name> --path <path> --set project=<project>`. Component is always derived from `--name` and cannot be overridden. Registration is rejected while another repo already holds the same canonical task scope.
+For scripted Jira registration, pass all three repository status defaults explicitly:
+
+```sh
+relay-flow repo register \
+  --name payments \
+  --path /work/payments \
+  --set project=PAY \
+  --set statusDefaults.start="Open" \
+  --set statusDefaults.work="Working" \
+  --set statusDefaults.end="Closed"
+```
+
+The values must be statuses available to the Jira project. Component is always derived from `--name` and cannot be overridden. Registration is rejected while another repo already holds the same canonical task scope.
 
 ### Beads task system
 
@@ -357,8 +394,9 @@ Task, runner, harness, and durable executor plugins are selected machine-wide. A
 
 ### Run
 
-The server must already be running for `repo register` and `workflow submit`;
-the same process polls repos and drives runs.
+The guided first-run flow starts or reuses the server before `repo register`.
+Outside that flow, `repo register` and `workflow submit` require the server to
+already be running; the same process polls repos and drives runs.
 
 ```sh
 relay-flow serve              # normal start; requires an initialized database
@@ -443,6 +481,7 @@ Rules enforced at submit:
 - The graph must be fully reachable from `start`; unknown fields are rejected; `runnerPlugin`/`harnessPlugin`/`closeOn`/legacy `tasks`/`runner` keys are rejected.
 - Only `agent` and `hitl` nodes receive mailbox subtasks; `start` and `end` never do.
 - `cleanupRunnerOnEnd` is the only workflow cleanup knob and takes priority over terminal retention after `end`; the word `terminal` refers to runner terminals only.
+- `nudgePrompt` supports `{{taskSystem}}`, `{{ticket}}`, `{{workflow}}`, `{{repo}}`, `{{node}}`, `{{mailbox}}`, and `{{nextSteps}}`; unsupported variables are rejected at submission.
 
 ### Task-config merge
 

package/cmd/relay-flow/commands_test.go

@@ -631,19 +631,45 @@ func insertRun(t *testing.T, path, id, state string) {
 // 8.4: fully-flagged repo register never prompts and produces the same
 // repo entry the interactive run would post.
 type registerServer struct {
-	ackServer  // embed for the unreachable stubs
-	fields     []string
-	gotInput   *repo.RegisterInput
-	gotInputs  []repo.RegisterInput
-	successful []repo.RegisterInput
-	failName   string
-	calls      int
+	ackServer   // embed for the unreachable stubs
+	fields      []string
+	gotInput    *repo.RegisterInput
+	gotInputs   []repo.RegisterInput
+	successful  []repo.RegisterInput
+	failName    string
+	calls       int
+	candidates  []runner.RepoCandidate
+	ensureCalls []runner.RepoCandidate
+	registered  []repo.Info
 }
 
-func (s *registerServer) TaskFields(context.Context) ([]string, error) {
+func (s *registerServer) TaskRegistrationFields(context.Context, config.RawValues) ([]task.RegistrationField, error) {
 	s.calls++
-	return s.fields, nil
+	out := make([]task.RegistrationField, 0, len(s.fields))
+	for _, field := range s.fields {
+		out = append(out, task.RegistrationField{Key: field, Title: field, Derived: field == "component"})
+	}
+	return out, nil
+}
+func (s *registerServer) DiscoverRepos(context.Context) ([]runner.RepoCandidate, error) {
+	return append([]runner.RepoCandidate(nil), s.candidates...), nil
+}
+
+func (s *registerServer) EnsureRepo(_ context.Context, candidate runner.RepoCandidate) error {
+	s.ensureCalls = append(s.ensureCalls, candidate)
+	for _, existing := range s.candidates {
+		if existing.Path == candidate.Path {
+			return nil
+		}
+	}
+	s.candidates = append(s.candidates, candidate)
+	return nil
+}
+
+func (s *registerServer) ListRepos(context.Context) ([]repo.Info, error) {
+	return append([]repo.Info(nil), s.registered...), nil
 }
+
 func (s *registerServer) RegisterRepo(_ context.Context, in repo.RegisterInput) (repo.Info, error) {
 	s.calls++
 	cp := in
@@ -653,7 +679,9 @@ func (s *registerServer) RegisterRepo(_ context.Context, in repo.RegisterInput)
 		return repo.Info{}, errors.New("registration failed")
 	}
 	s.successful = append(s.successful, cp)
-	return repo.Info{Name: in.Name, Path: in.Path, TaskConfig: in.TaskConfig}, nil
+	info := repo.Info{Name: in.Name, Path: in.Path, TaskConfig: in.TaskConfig}
+	s.registered = append(s.registered, info)
+	return info, nil
 }
 
 func serveRegister(t *testing.T, home string, fields []string) *registerServer {
@@ -767,7 +795,152 @@ func TestRepoRegisterFlagsNonInteractive(t *testing.T) {
 	}
 }
 
-func TestRepoMultiSelectAndSharedJiraMapping(t *testing.T) {
+func TestRegistrationSelectRequiresExplicitChoiceWithoutDefault(t *testing.T) {
+	field := task.RegistrationField{Key: "statusDefaults.start", Options: []string{"Open", "Working"}}
+	options := registrationSelectOptions(field)
+	if len(options) != 3 {
+		t.Fatalf("options = %d, want empty choice plus two statuses", len(options))
+	}
+	var selected string
+	selectField := huh.NewSelect[string]().Options(options...).Value(&selected)
+	var out bytes.Buffer
+	if err := selectField.RunAccessible(&out, strings.NewReader("1\n")); err != nil {
+		t.Fatal(err)
+	}
+	if selected != "" {
+		t.Fatalf("empty choice selected %q, want empty value", selected)
+	}
+	if err := selectField.RunAccessible(&out, strings.NewReader("2\n")); err != nil {
+		t.Fatal(err)
+	}
+	if selected != "Open" {
+		t.Fatalf("explicit status selection = %q, want Open", selected)
+	}
+}
+
+func TestRegistrationTaskConfigBuildsNestedStatusDefaults(t *testing.T) {
+	registration := task.Registration{Fields: []task.RegistrationField{
+		{Key: "project", Title: "Project"},
+		{Key: "component", Title: "Component", Derived: true},
+		{Key: "statusDefaults.start", Title: "Start", Options: []string{"Open", "Working", "Closed"}},
+		{Key: "statusDefaults.work", Title: "Work", Options: []string{"Open", "Working", "Closed"}},
+		{Key: "statusDefaults.end", Title: "End", Options: []string{"Open", "Working", "Closed"}},
+	}}
+	got, err := registrationTaskConfig(registration, kvFlags{
+		"project":              "PAY",
+		"statusDefaults.start": "Open",
+		"statusDefaults.work":  "Working",
+		"statusDefaults.end":   "Closed",
+	}, "payments")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defaults, ok := got["statusDefaults"].(map[string]any)
+	if !ok || defaults["start"] != "Open" || defaults["work"] != "Working" || defaults["end"] != "Closed" {
+		t.Fatalf("nested statusDefaults = %#v", got["statusDefaults"])
+	}
+	for _, tc := range []struct {
+		name string
+		sets kvFlags
+		want string
+	}{
+		{name: "invalid status", sets: kvFlags{"project": "PAY", "statusDefaults.start": "Missing"}, want: "not one of the available choices"},
+		{name: "derived component", sets: kvFlags{"project": "PAY", "component": "other"}, want: "derived"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if _, err := registrationTaskConfig(registration, tc.sets, "payments"); err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("registration error = %v, want %q", err, tc.want)
+			}
+		})
+	}
+}
+
+func TestRepoAddValidationRejectsDuplicateNormalizedPathAndName(t *testing.T) {
+	candidates := []runner.RepoCandidate{{Name: "payments", Path: "/work/payments"}}
+	if err := validateAddedRepo(runner.RepoCandidate{Name: "new", Path: "/work/payments/."}, candidates, nil); err == nil || !strings.Contains(err.Error(), "already discovered") {
+		t.Fatalf("duplicate discovered path error = %v", err)
+	}
+	registered := []repo.Info{{Name: "checkout", Path: "/work/checkout"}}
+	if err := validateAddedRepo(runner.RepoCandidate{Name: " checkout ", Path: "/work/new"}, candidates, registered); err == nil || !strings.Contains(err.Error(), "already registered") {
+		t.Fatalf("duplicate registered name error = %v", err)
+	}
+	for _, candidate := range []runner.RepoCandidate{{Name: "", Path: "/work/new"}, {Name: "new", Path: ""}} {
+		if err := validateAddedRepo(candidate, nil, nil); err == nil {
+			t.Fatalf("validateAddedRepo(%+v) accepted missing input", candidate)
+		}
+	}
+}
+
+func TestInteractiveRepoSelectionPreservesSelectionsAndAddsMultiple(t *testing.T) {
+	home := t.TempDir()
+	deps := serveRegister(t, home, nil)
+	deps.candidates = []runner.RepoCandidate{{Name: "existing", Path: "/work/existing"}}
+	client := server.NewClient(filepath.Join(home, ".relay-flow", "server.sock"))
+
+	selectionSteps := [][]int{{0, addRepositorySelection}, {0, 1, addRepositorySelection}, {0, 1, 2}}
+	addSteps := []runner.RepoCandidate{
+		{Name: "new-one", Path: filepath.Join(t.TempDir(), "new-one")},
+		{Name: "new-two", Path: filepath.Join(t.TempDir(), "new-two")},
+	}
+	selectionCalls := 0
+	addCalls := 0
+	candidates, selected, err := selectReposInteractiveWithPrompts(
+		context.Background(), client, deps.candidates, nil,
+		func(got []runner.RepoCandidate, selected []int) ([]int, error) {
+			wantSelected := [][]int{nil, {0, 1}, {0, 1, 2}}[selectionCalls]
+			if fmt.Sprint(selected) != fmt.Sprint(wantSelected) {
+				t.Fatalf("selection %d started with %v, want %v", selectionCalls, selected, wantSelected)
+			}
+			if selectionCalls >= len(selectionSteps) {
+				t.Fatalf("unexpected selection call %d with candidates %+v", selectionCalls, got)
+			}
+			step := append([]int(nil), selectionSteps[selectionCalls]...)
+			selectionCalls++
+			return step, nil
+		},
+		func() (runner.RepoCandidate, error) {
+			if addCalls >= len(addSteps) {
+				return runner.RepoCandidate{}, errors.New("unexpected add prompt")
+			}
+			step := addSteps[addCalls]
+			addCalls++
+			return step, nil
+		},
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if selectionCalls != 3 || addCalls != 2 || len(deps.ensureCalls) != 2 {
+		t.Fatalf("selection calls=%d add calls=%d ensure calls=%v", selectionCalls, addCalls, deps.ensureCalls)
+	}
+	if len(candidates) != 3 || len(selected) != 3 || fmt.Sprint(selected) != "[0 1 2]" {
+		t.Fatalf("final candidates=%+v selected=%v", candidates, selected)
+	}
+	if candidates[1].Name != "new-one" || candidates[2].Name != "new-two" {
+		t.Fatalf("final candidate names=%+v", candidates)
+	}
+}
+
+func TestRepoSelectionOptionsIncludeVisibleAddAction(t *testing.T) {
+	options := repoSelectionOptions([]runner.RepoCandidate{{Name: "payments", Path: "/work/payments"}})
+	if len(options) != 2 {
+		t.Fatalf("options = %d, want candidate plus Add action", len(options))
+	}
+	var selected []int
+	field := repoMultiSelect(options, &selected)
+	var out bytes.Buffer
+	if err := field.RunAccessible(&out, strings.NewReader("2\n")); err != nil {
+		t.Fatal(err)
+	}
+	if len(selected) != 1 || selected[0] != addRepositorySelection {
+		t.Fatalf("selected = %v, want Add action sentinel", selected)
+	}
+	if !strings.Contains(out.String(), "Add repository") {
+		t.Fatalf("output %q missing Add repository", out.String())
+	}
+}
+
+func TestRepoMultiSelectAndPluginMapping(t *testing.T) {
 	selected := []int{0, 1}
 	field := repoMultiSelect([]huh.Option[int]{
 		huh.NewOption("payments", 0),
@@ -783,9 +956,10 @@ func TestRepoMultiSelectAndSharedJiraMapping(t *testing.T) {
 	if fmt.Sprint(selected) != "[0 1]" {
 		t.Fatalf("selected = %v, want [0 1]", selected)
 	}
-	if got := registrationSharedFields([]string{"project", "component"}); fmt.Sprint(got) != "[project]" {
-		t.Fatalf("prompted fields = %v, want project only", got)
-	}
+	registration := task.Registration{Fields: []task.RegistrationField{
+		{Key: "project", Title: "Project"},
+		{Key: "component", Title: "Component", Derived: true},
+	}}
 
 	home := t.TempDir()
 	deps := serveRegister(t, home, []string{"project", "component"})
@@ -794,8 +968,8 @@ func TestRepoMultiSelectAndSharedJiraMapping(t *testing.T) {
 		{Name: "payments", Path: "/srv/payments"},
 		{Name: "checkout", Path: "/srv/checkout"},
 	}
-	if err := registerSelectedRepos(context.Background(), client, candidates, selected,
-		[]string{"project", "component"}, kvFlags{"project": "PAY"}); err != nil {
+	if err := registerSelectedReposDynamic(context.Background(), client, candidates, selected,
+		registration, kvFlags{"project": "PAY"}); err != nil {
 		t.Fatal(err)
 	}
 	if len(deps.successful) != 2 {
@@ -818,8 +992,12 @@ func TestRepoRegistrationPartialFailureKeepsPriorSuccess(t *testing.T) {
 		{Name: "checkout", Path: "/srv/checkout"},
 		{Name: "later", Path: "/srv/later"},
 	}
-	err := registerSelectedRepos(context.Background(), client, candidates, []int{0, 1, 2},
-		[]string{"project", "component"}, kvFlags{"project": "PAY"})
+	registration := task.Registration{Fields: []task.RegistrationField{
+		{Key: "project", Title: "Project"},
+		{Key: "component", Title: "Component", Derived: true},
+	}}
+	err := registerSelectedReposDynamic(context.Background(), client, candidates, []int{0, 1, 2},
+		registration, kvFlags{"project": "PAY"})
 	if err == nil || !strings.Contains(err.Error(), "checkout") {
 		t.Fatalf("partial failure = %v, want failed repo name", err)
 	}
@@ -1012,7 +1190,9 @@ func (s *ackServer) CancelRun(context.Context, string, string) error { panic("un
 func (s *ackServer) DiscoverRepos(context.Context) ([]runner.RepoCandidate, error) {
 	panic("unreachable")
 }
-func (s *ackServer) TaskFields(context.Context) ([]string, error) { panic("unreachable") }
+func (s *ackServer) TaskRegistrationFields(context.Context, config.RawValues) ([]task.RegistrationField, error) {
+	panic("unreachable")
+}
 func (s *ackServer) RegisterRepo(context.Context, repo.RegisterInput) (repo.Info, error) {
 	panic("unreachable")
 }