relay-flow 0.2.8-alpha → 0.2.10-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.8-alpha
+opencode plugin relay-flow-plugin@0.2.10-alpha
 ```
 
 **Pi**
 
 ```sh
-pi install npm:relay-flow-plugin@0.2.8-alpha
+pi install npm:relay-flow-plugin@0.2.10-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.
+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.
 
-### 5. Start the server
-
-```sh
-relay-flow serve --background
-```
-
-### 6. Register a repository
+### 4. Register a repository later
 
 The repository must already exist in the selected runner. For Orca:
 
@@ -81,13 +82,18 @@ 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
 relay-flow workflow list
+relay-flow workflow list --json   # stable automation output
+relay-flow run get --ticket PAY-101 # Argo-shaped human inspection view
+relay-flow run get --ticket PAY-101 --json # stable automation output
 ```
 
 Replace the example workflow with
@@ -154,7 +160,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.8-alpha"]
+  "plugin": ["relay-flow-plugin@0.2.10-alpha"]
 }
 ```
 
@@ -163,7 +169,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.8-alpha"]
+  "plugin": ["relay-flow-plugin@0.2.10-alpha"]
 }
 ```
 
@@ -179,7 +185,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.8-alpha
+pi install npm:relay-flow-plugin@0.2.10-alpha
 ```
 
 Relay-flow does not install or configure the package automatically. Pi resolves
@@ -199,10 +205,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 +260,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
@@ -369,8 +397,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
@@ -455,6 +484,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
 
@@ -651,6 +681,17 @@ One Repo Poller per registered repo (not per workflow) fetches active parent tic
 
 ---
 
+## CLI inspection and automation
+
+Human-readable workflow and run views are intended for interactive operator
+use. Scripts should always pass `--json`; the JSON output is the stable
+machine-readable interface. `run get --ticket <key>` shows metadata,
+conditions, timing, progress, resource-duration placeholders, and the actual
+node-visit tree, including retries and revisits. Scoped `--help` is available
+at the root, group, and leaf command levels. Build information is available
+without a server through `relay-flow version`, `relay-flow --version`, and
+`relay-flow -v`.
+
 ## Development
 
 ```sh

package/cmd/relay-flow/commands_test.go

@@ -631,13 +631,16 @@ 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) TaskRegistrationFields(context.Context, config.RawValues) ([]task.RegistrationField, error) {
@@ -648,6 +651,25 @@ func (s *registerServer) TaskRegistrationFields(context.Context, config.RawValue
 	}
 	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
@@ -657,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 {
@@ -831,6 +855,91 @@ func TestRegistrationTaskConfigBuildsNestedStatusDefaults(t *testing.T) {
 	}
 }
 
+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]{