Merge wait-cmd: add pipelines wait <run-id> to block until runs finish, then report them

Adds a read-only CLI command that blocks until each named run reaches a terminal
status (including through a human stage) and reports each run's id, status,
outcome, stage and duration; batches several ids in one command and exits 0 even
for an unsuccessful run. Reuses the existing run --wait polling machinery.
Includes tests and a docs/notes record of the docs the docs-fold writer should
update.
This commit is contained in:
2026-10-18 01:12:57 +01:00
6 changed files with 668 additions and 17 deletions
+92
View File
@@ -0,0 +1,92 @@
# `pipelines wait`: block until runs finish, then report them
## What this item changed
A new read-only CLI command, `pipelines wait <run-id> [run-id ...]`, in
`internal/cli/`. The harness that runs the operator's work resumes a session when
a *background command finishes*, so "tell me when this run is done" has to be one
command that blocks and exits rather than a polling script.
- `internal/cli/app.go`
- `wait` resolves every id up front (so an unknown run is a fast client error,
never something discovered after the others finish), then polls each run to a
terminal status and prints one line per run as it finishes.
- The polling is the *same* machinery the `run --wait` path already used: the
per-second `get_run` reattachment is factored into `awaitRuns`, and
`finishRun` now uses it too. The transport is unchanged — no subscription and
no new protocol message.
- Terminal statuses are `succeeded`, `failed`, `canceled` and `interrupted`; a
run parked on a human decision (`waiting`) is *not* terminal for `wait`, so a
wait blocks through it. `run --wait` keeps its existing active set
(queued/running) unchanged.
- A finished-but-unsuccessful run is still a finished run: `wait` prints it and
exits 0. The exit is non-zero only for a client-side failure — an unknown id,
a connection that cannot be established, or `--timeout` expiring while a run
is still active. A timeout reports the still-active runs, changes nothing, and
is never treated as a run's outcome.
- `--timeout DURATION` is the overall client limit (default `0` = wait until the
runs finish); the per-request transport timeout falls back to the usual 30 s
bound. `--url` follows the existing convention.
- `--json` prints the final run envelope instead of the line: one envelope for
one id, an array for several.
- It is read-only: it sends only `get_run`, resolves no workspace, is not
refused by the workspace guard and writes nothing.
- `internal/cli/commands.go` and `internal/cli/help.go` add the command to the
help inventory and the EXECUTE section.
- Tests: `internal/cli/wait_test.go` (line format, batch reporting, wait-until-
terminal, unknown id, timeout leaves the run active, `--json` envelope shape)
and `internal/cli/wait_command_test.go` (the real CLI against the real
websocket server and store: terminal reporting, blocking until terminal, a
batch, an unknown id, a timeout that leaves the run `queued`, and a run whose
recorded workspace is absent).
No protocol, server, store, TUI or Android change; no new dependency; no run is
started. State: committed locally only, not deployed.
## Shared documents this change makes stale
The note is written here rather than edited in place; the `docs-fold` writer
should update these when it next folds notes.
- `docs/cli.md` — the "Scripted runs" section (beside the `--wait` paragraph at
the end of the `cd ~/repos/project` block, and the
`| Run history/inspection | runs --json, inspect ID --json |` row of the
"CLI/TUI capability map") should gain the `wait` command. Suggested text to add
after the `--wait`/`--wait-timeout` paragraph:
> `pipelines wait <run-id> [run-id ...]` blocks until each run reaches a
> terminal status — `succeeded`, `failed`, `canceled` or `interrupted`, and
> also through a run waiting on a person — then prints one line per run with its
> id, status and outcome, its final stage and how long it took, and exits 0 even
> for a run that finished unsuccessfully. Several ids are waited together in one
> command. The exit is non-zero only for a client-side failure: an unknown run
> id, a connection that could not be established, or `--timeout` expiring while
> a run is still active. A timeout says the run is still active and that nothing
> was cancelled; it never cancels, retries or otherwise touches a run, and is
> never reported as its outcome. It is read-only: it needs no workspace, is not
> refused by the workspace guard and writes nothing. `--json` prints the final
> run envelope instead of the line (one envelope for one id, an array for
> several). `--timeout` is the overall client limit and defaults to 0 (wait
> until the runs finish), independent of the per-request `--timeout`.
and extend the capability-map row to
`| Run history/inspection | runs --json, inspect ID --json, wait ID [...] |`.
- `internal/author/skill/references/operations.md` — the "Inspect results first"
run-operations list (around the `CLI_PREFIX inspect RUN_ID --json` bullet) should
add a `CLI_PREFIX wait RUN_ID [RUN_ID ...]` bullet: it blocks until every named
run is terminal (or the client `--timeout` passes) and reports each run's id,
status, outcome, stage and duration; it is read-only, needs no workspace, exits
0 even for a failed run, and a timeout never cancels or changes a run. Add a
dated evidence bullet naming `internal/cli/wait_test.go` and
`internal/cli/wait_command_test.go`.
## Not stale
- `internal/author/install.go`'s managed file inventory needs no change: no
reference file is added.
- `internal/author/skill/references/SKILL.md` stays a task-directed index; the
wait command belongs in `operations.md`.
- `internal/server/AGENTS.md` and the root `AGENTS.md` already describe the CLI,
the workspace guard and the polling path, so neither area map needs a new entry.
- `README.md` carries no per-command CLI inventory that names `wait`.
+210 -17
View File
@@ -90,7 +90,14 @@ func (a App) flags(command string) (*flag.FlagSet, *options) {
f.SetOutput(a.Err)
f.StringVar(&o.url, "url", envOr("PIPELINES_URL", "ws://127.0.0.1:8080/connect"), "Pipeline server WebSocket URL")
f.BoolVar(&o.json, "json", false, "Machine-readable JSON; no interactive picker/editor")
f.DurationVar(&o.timeout, "timeout", 30*time.Second, "Timeout per server request")
if command == "wait" {
// A wait blocks until the runs reach a terminal status, so its --timeout
// is the overall client limit (0 is the default and waits until they
// finish), not a per-request transport timeout.
f.DurationVar(&o.timeout, "timeout", 0, "Give up after this long while a run is still active (0 waits until it finishes)")
} else {
f.DurationVar(&o.timeout, "timeout", 30*time.Second, "Timeout per server request")
}
switch command {
case "provider-check":
f.StringVar(&o.harness, "harness", "opencode", "Provider-check harness: opencode or configured pi")
@@ -314,7 +321,7 @@ func (a App) Run(ctx context.Context, args []string) error {
}
return err
}
if o.timeout <= 0 || o.waitTimeout < 0 || o.version < 0 || o.expected < 0 {
if o.timeout < 0 || (o.timeout == 0 && command != "wait") || o.waitTimeout < 0 || o.version < 0 || o.expected < 0 {
return fmt.Errorf("timeout must be positive, wait-timeout nonnegative, and versions nonnegative")
}
pos := f.Args()
@@ -449,7 +456,13 @@ func (a App) Run(ctx context.Context, args []string) error {
return nil
}
// Connect only for server operations. Keep each RPC bounded, not the interactive session.
dialCtx, cancel := context.WithTimeout(ctx, o.timeout)
// `wait` uses --timeout as its overall wait limit, so its per-request transport
// timeout falls back to the usual bound.
requestTimeout := o.timeout
if requestTimeout <= 0 {
requestTimeout = 30 * time.Second
}
dialCtx, cancel := context.WithTimeout(ctx, requestTimeout)
c, err := client.Open(dialCtx, o.url)
cancel()
if err != nil {
@@ -475,7 +488,7 @@ func (a App) Run(ctx context.Context, args []string) error {
}
})
call := func(request protocol.Message) (protocol.Message, error) {
requestCtx, cancel := context.WithTimeout(ctx, o.timeout)
requestCtx, cancel := context.WithTimeout(ctx, requestTimeout)
defer cancel()
return c.Call(requestCtx, request)
}
@@ -1020,6 +1033,8 @@ func (a App) Run(ctx context.Context, args []string) error {
return a.output(r)
case "run":
return a.run(ctx, pos, o, call, resolve)
case "wait":
return a.wait(ctx, pos, o, call)
}
return nil
}
@@ -1296,22 +1311,19 @@ func (a App) finishRun(ctx context.Context, r protocol.Message, o *options, call
defer timer.Stop()
deadline = timer.C
}
for r.RunDetail.Status == "running" || r.RunDetail.Status == "queued" {
select {
case <-ctx.Done():
return ctx.Err()
case <-deadline:
final := r
err = a.awaitRuns(ctx, []protocol.Message{r}, deadline, call, runInProgress, func(terminal protocol.Message) error {
final = terminal
return nil
})
if err != nil {
var limit *waitLimitError
if errors.As(err, &limit) {
return fmt.Errorf("client wait limit reached for run %d; it remains active and was not canceled; inspect it read-only with pipelines inspect %d --json, and to keep waiting rerun with --wait reusing the original --request-key instead of starting a duplicate run", r.RunDetail.ID, r.RunDetail.ID)
case <-time.After(time.Second):
}
r, err = call(protocol.Message{Type: protocol.GetRun, RunID: r.RunDetail.ID})
if err != nil {
return err
}
if r.RunDetail == nil {
return fmt.Errorf("missing run detail")
}
return err
}
r = final
}
if err = a.output(r); err != nil {
return err
@@ -1322,6 +1334,187 @@ func (a App) finishRun(ctx context.Context, r protocol.Message, o *options, call
return nil
}
// wait polls every named run to a terminal status and reports each as it
// finishes, reusing the run --wait reattachment (GetRun) rather than a second
// mechanism. It is read-only: it resolves no workspace, never cancels, retries
// or otherwise changes a run, and a timeout is never treated as a run's
// outcome.
func (a App) wait(ctx context.Context, pos []string, o *options, call callFunc) error {
if len(pos) == 0 {
return fmt.Errorf("wait requires at least one run ID; use pipelines help wait")
}
// Resolve every id up front so an unknown run is a fast client error rather
// than something a wait would discover only after the others finish.
initial := make([]protocol.Message, 0, len(pos))
for _, value := range pos {
id, err := strconv.ParseInt(value, 10, 64)
if err != nil || id <= 0 {
return fmt.Errorf("run ID must be positive: %q", value)
}
r, err := call(protocol.Message{Type: protocol.GetRun, RunID: id})
if err != nil {
return err
}
if r.RunDetail == nil {
return fmt.Errorf("server did not return run detail for %d", id)
}
initial = append(initial, r)
}
// --timeout bounds the whole wait; 0 (the default) waits until every run
// finishes. Reaching the limit reports the still-active runs and changes
// nothing.
var deadline <-chan time.Time
if o.timeout > 0 {
timer := time.NewTimer(o.timeout)
defer timer.Stop()
deadline = timer.C
}
terminal := make([]protocol.Message, 0, len(initial))
err := a.awaitRuns(ctx, initial, deadline, call, runUnfinished, func(r protocol.Message) error {
terminal = append(terminal, r)
if o.json {
return nil
}
_, writeErr := fmt.Fprintln(a.Out, waitLine(r.RunDetail))
return writeErr
})
if err != nil {
var limit *waitLimitError
if errors.As(err, &limit) {
return fmt.Errorf("wait limit reached; %s still active and not canceled - nothing was changed; rerun pipelines wait to keep waiting", limit.Runs())
}
return err
}
if o.json {
if len(terminal) == 1 {
return a.output(terminal[0])
}
return a.output(terminal)
}
return nil
}
// awaitRuns polls every run that active reports as unfinished until each is
// terminal, using the same GetRun reattachment the run --wait path uses, and
// calls onTerminal for each as it finishes (including runs already terminal at
// entry, in the order supplied). A deadline that passes first returns a
// *waitLimitError naming the runs still active; ctx ending first returns
// ctx.Err(). It never cancels, retries or otherwise changes a run.
func (a App) awaitRuns(ctx context.Context, runs []protocol.Message, deadline <-chan time.Time, call callFunc, active func(string) bool, onTerminal func(protocol.Message) error) error {
remaining := make([]protocol.Message, 0, len(runs))
for _, r := range runs {
if active(r.RunDetail.Status) {
remaining = append(remaining, r)
continue
}
if err := onTerminal(r); err != nil {
return err
}
}
for len(remaining) > 0 {
select {
case <-ctx.Done():
return ctx.Err()
case <-deadline:
return &waitLimitError{IDs: runIDs(remaining)}
case <-time.After(time.Second):
}
next := remaining[:0]
for _, r := range remaining {
refreshed, err := call(protocol.Message{Type: protocol.GetRun, RunID: r.RunDetail.ID})
if err != nil {
return err
}
if refreshed.RunDetail == nil {
return fmt.Errorf("server did not return run detail for %d", r.RunDetail.ID)
}
if active(refreshed.RunDetail.Status) {
next = append(next, refreshed)
continue
}
if err := onTerminal(refreshed); err != nil {
return err
}
}
remaining = next
}
return nil
}
// runInProgress is the active set the run --wait path stops at: a run is still
// being worked on while it is queued or running.
func runInProgress(status string) bool {
return status == protocol.RunStatusQueued || status == protocol.RunStatusRunning
}
// runUnfinished is the active set `pipelines wait` blocks on: the same as
// runInProgress plus a run parked on a human decision (waiting), which has not
// finished either.
func runUnfinished(status string) bool {
return runInProgress(status) || status == protocol.RunStatusWaiting
}
// runIDs extracts the ids of the runs still active when a wait limit passed.
func runIDs(runs []protocol.Message) []int64 {
ids := make([]int64, 0, len(runs))
for _, r := range runs {
ids = append(ids, r.RunDetail.ID)
}
return ids
}
// waitLimitError reports that the client's wait limit was reached while the
// named runs were still active. The runs are untouched: a wait never cancels,
// retries or changes a run, and a timeout is never treated as its outcome.
type waitLimitError struct{ IDs []int64 }
func (e *waitLimitError) Error() string {
return "wait limit reached while run(s) " + e.Runs() + " were still active"
}
// Runs renders the still-active run ids for display.
func (e *waitLimitError) Runs() string {
parts := make([]string, 0, len(e.IDs))
for _, id := range e.IDs {
parts = append(parts, "run "+strconv.FormatInt(id, 10))
}
return strings.Join(parts, ", ")
}
// waitLine is the one-line terminal report `pipelines wait` prints: the run id,
// its status and outcome, its stage and how long it took.
func waitLine(d *protocol.RunDetail) string {
line := fmt.Sprintf("run %d · %s", d.ID, d.Status)
if outcome := strings.TrimSpace(d.Outcome); outcome != "" {
line += " (" + outcome + ")"
}
if stage := strings.TrimSpace(d.CurrentStage); stage != "" {
line += " · " + stage
}
if elapsed := runElapsed(d.CreatedAt, d.FinishedAt); elapsed != "" {
line += " · " + elapsed
}
return line
}
// runElapsed renders a run's wall-clock duration from its stored timestamps. An
// unparseable or missing start yields "" so the line omits the duration rather
// than inventing one; an empty finish uses the current time.
func runElapsed(start, end string) string {
first, err := time.Parse(time.RFC3339, start)
if err != nil {
return ""
}
last, err := time.Parse(time.RFC3339, end)
if err != nil {
if end != "" {
return ""
}
last = time.Now()
}
return max(time.Duration(0), last.Sub(first)).Round(time.Second).String()
}
// providerCheckDocker runs the provider check inside the profile's existing
// Compose service so a Docker-linked profile never falls back to a host harness.
// It streams the child's stdout/stderr and returns its exact exit code.
+2
View File
@@ -20,6 +20,7 @@ var usage = map[string]string{
"run": "run [name|id] [prompt] [--title TITLE] [--model PROVIDER/MODEL] [--stage-model STAGE=PROVIDER/MODEL ...] [--json [--wait [--wait-timeout DURATION]]]",
"runs": "runs [--pipeline NAME] [--json]",
"inspect": "inspect <run-id> [--json]",
"wait": "wait <run-id> [run-id ...] [--timeout DURATION] [--json]",
"cancel": "cancel <run-id> [--json]",
"decide": "decide <run-id> [stage] --option KEY [--feedback TEXT] [--json]",
"retry": "retry <run-id> [--json [--wait [--wait-timeout DURATION]]]",
@@ -50,6 +51,7 @@ var notes = map[string]string{
"run": "Runs in your current directory after action confirmation (--yes skips it). Select a pipeline and compose a multiline task with Ctrl+S. Stage tools are enabled automatically; no file list or typed RUN confirmation. Cancellation does not undo edits. --title sets an explicit run title; without it the title is derived from the prompt. --model PROVIDER/MODEL overrides the model for every stage of that run; --stage-model STAGE=PROVIDER/MODEL overrides one stage and is repeatable, with a repeated key last-wins. Precedence is per-stage > whole-run > the model pinned in the pipeline version; overrides apply to that run only and never change the pinned definition. An unknown stage key or a malformed provider/model is refused before the run starts, naming the valid stage keys. In JSON mode --wait polls until terminal; --wait-timeout bounds only the client wait after admission and is independent of per-request --timeout. A reached wait limit leaves the run active: inspect read-only with `inspect <run-id> --json`, or reattach with --wait reusing the original --request-key (never an automatic replay or cancel).",
"retry": "Start a new attempt of a failed run with the same initial input, directory, pipeline version, and edit scope. Original history is retained. Already-completed side effects are not undone. --wait/--wait-timeout behave as for run: a reached wait limit leaves the new run active; inspect read-only with `inspect <run-id> --json`, or reattach with --wait and the original --request-key instead of starting a duplicate retry.",
"title": "Rename a run's operator-facing title after the fact without touching its input, steps or execution. The title is collapsed to a single bounded line and recorded as explicitly set. `pipelines runs` and `pipelines inspect` then show it.",
"wait": "Block until each named run reaches a terminal status - succeeded, failed, canceled or interrupted, and also through a run waiting on a person - then print one line per run with its id, status and outcome, its stage and how long it took, and exit 0 even for a run that finished unsuccessfully. Several ids wait together in one command. The exit is non-zero only for a client-side failure: an unknown run id, a connection that could not be established, or --timeout expiring while a run is still active; a timeout says so plainly, never cancels, retries or otherwise touches a run, and is never reported as its outcome. Read-only: it needs no workspace, is not refused by the workspace guard and writes nothing. --json prints the final run envelope instead of the line (one envelope for one id, an array for several).",
"decide": "Choose an option for a run waiting on a human stage. The run must be `waiting`; the option must be one of that stage's non-error edges. The stage is inferred from the run's current stage unless named. The choice and optional --feedback are recorded as the step's evidence (visible in inspect and the TUI) and the run resumes along the chosen edge. An unknown option is refused with the valid list; a repeated decision for an already-decided visit does not double-apply. Works across a server restart because the wait is persisted.",
"debug": "Open a fresh configured harness conversation to investigate a run using inspect/show/runs CLI queries. --harness opencode|pi|nvim chooses another configured harness or read-only nvim packet. Does not resume implementation or retry. --json returns the prompt without launching anything.",
"rpc": "Accepts a JSON protocol envelope; '-' reads stdin. Every TUI server operation is available here too. Mutating commands are not dry runs. The omni-search command is `search` (fields query, optional kind and limit) and answers with ranked `search_results`.",
+1
View File
@@ -26,6 +26,7 @@ EXECUTE
run [name] [prompt] Fuzzy selection, multiline prompt, live inspector
runs List audited runs; --pipeline filters results
inspect <run-id> Inspect stages, outputs, errors and status
wait <run-id> ... Block until runs finish, then report each (read-only)
cancel <run-id> Cancel a run; changes are NOT rolled back
decide <run-id> [stage] Choose an option for a run waiting on a person
retry <run-id> Restart a failed run with its original input and directory
+190
View File
@@ -0,0 +1,190 @@
package cli_test
import (
"context"
"encoding/json"
"fmt"
"path/filepath"
"strings"
"testing"
"time"
"git.a-wan.net/alan/pipelines/internal/pipeline"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// seedRun creates one run directly in the store against a fresh submitted
// definition, without starting a stage executor, so the wait command is tested
// against real runs over the real websocket transport.
func seedRun(t *testing.T, store *pipeline.Store, key string) int64 {
t.Helper()
return seedRunIn(t, store, key, t.TempDir())
}
// seedRunIn is seedRun with an explicit recorded workspace, so a test can pin a
// path that is not present on this machine.
func seedRunIn(t *testing.T, store *pipeline.Store, key, workspace string) int64 {
t.Helper()
ctx := context.Background()
items, err := store.List(ctx)
if err != nil {
t.Fatal(err)
}
if len(items) == 0 {
if _, err := store.Submit(ctx, "waiting", pipeline.Template([]string{"worker"}, true)); err != nil {
t.Fatal(err)
}
if items, err = store.List(ctx); err != nil {
t.Fatal(err)
}
}
detail, err := store.Get(ctx, items[0].ID, 1)
if err != nil {
t.Fatal(err)
}
id, _, err := store.CreateRun(ctx, detail, key, workspace, false, nil, map[string]any{"prompt": "wait test"})
if err != nil {
t.Fatal(err)
}
return id
}
// A run that finished unsuccessfully is still a finished run: one line is
// printed for it and the command exits 0.
func TestCLIWaitReportsTerminalRunWithoutFailing(t *testing.T) {
run, store, _ := setup(t)
ctx := context.Background()
id := seedRun(t, store, "wait-failed")
if err := store.FinishRun(ctx, id, "failed", "error", "boom", map[string]any{}); err != nil {
t.Fatal(err)
}
output, err := run("wait", fmt.Sprint(id), "--timeout", "5s")
if err != nil {
t.Fatalf("a failed run must not fail the wait: %v", err)
}
t.Logf("pipelines wait %d:\n%s", id, strings.TrimSpace(output))
line := fmt.Sprintf("run %d · failed (error)", id)
if !strings.Contains(output, line) {
t.Fatalf("wait output missing %q:\n%s", line, output)
}
}
// The wait blocks while the run is active and returns as soon as it goes
// terminal.
func TestCLIWaitBlocksUntilTerminal(t *testing.T) {
run, store, _ := setup(t)
ctx := context.Background()
id := seedRun(t, store, "wait-active")
go func() {
time.Sleep(1200 * time.Millisecond)
_ = store.FinishRun(ctx, id, "succeeded", "success", "", map[string]any{})
}()
start := time.Now()
output, err := run("wait", fmt.Sprint(id), "--timeout", "15s")
if err != nil {
t.Fatal(err)
}
if elapsed := time.Since(start); elapsed < time.Second {
t.Fatalf("wait returned before the run was terminal: %s", elapsed)
}
if !strings.Contains(output, fmt.Sprintf("run %d · succeeded (success)", id)) {
t.Fatalf("wait output = %q", output)
}
}
// Several ids are waited together and every one is reported.
func TestCLIWaitReportsEveryRunInABatch(t *testing.T) {
run, store, _ := setup(t)
ctx := context.Background()
first := seedRun(t, store, "wait-batch-1")
second := seedRun(t, store, "wait-batch-2")
if err := store.FinishRun(ctx, first, "succeeded", "success", "", map[string]any{}); err != nil {
t.Fatal(err)
}
if err := store.FinishRun(ctx, second, "canceled", "", "canceled", map[string]any{}); err != nil {
t.Fatal(err)
}
output, err := run("wait", fmt.Sprint(first), fmt.Sprint(second), "--timeout", "5s")
if err != nil {
t.Fatal(err)
}
for _, want := range []string{
fmt.Sprintf("run %d · succeeded (success)", first),
fmt.Sprintf("run %d · canceled", second),
} {
if !strings.Contains(output, want) {
t.Fatalf("batch wait output missing %q:\n%s", want, output)
}
}
}
// An unknown run id exits non-zero and does not hang.
func TestCLIWaitRefusesUnknownRunWithoutHanging(t *testing.T) {
run, _, _ := setup(t)
start := time.Now()
_, err := run("wait", "999999", "--timeout", "5s")
if err == nil || !strings.Contains(err.Error(), "run not found") {
t.Fatalf("unknown run not refused: %v", err)
}
if elapsed := time.Since(start); elapsed > 3*time.Second {
t.Fatalf("unknown run hung for %s", elapsed)
}
}
// A timeout says the run is still active and leaves it untouched.
func TestCLIWaitTimeoutLeavesRunUntouched(t *testing.T) {
run, store, _ := setup(t)
ctx := context.Background()
id := seedRun(t, store, "wait-timeout")
_, err := run("wait", fmt.Sprint(id), "--timeout", "300ms")
if err == nil || !strings.Contains(err.Error(), "still active") || !strings.Contains(err.Error(), "not canceled") {
t.Fatalf("timeout not reported plainly: %v", err)
}
detail, err := store.GetRun(ctx, id)
if err != nil {
t.Fatal(err)
}
if detail.Status != "queued" || detail.FinishedAt != "" {
t.Fatalf("timeout changed the run: %+v", detail.RunSummary)
}
}
// A wait resolves no workspace and is not refused by the workspace guard: it
// reports a run whose recorded workspace is not present on this machine,
// read-only.
func TestCLIWaitNeedsNoWorkspace(t *testing.T) {
run, store, _ := setup(t)
ctx := context.Background()
id := seedRunIn(t, store, "wait-no-workspace", filepath.Join(t.TempDir(), "removed"))
if err := store.FinishRun(ctx, id, "succeeded", "success", "", map[string]any{}); err != nil {
t.Fatal(err)
}
output, err := run("wait", fmt.Sprint(id), "--timeout", "5s")
if err != nil {
t.Fatalf("wait needed the workspace: %v", err)
}
if !strings.Contains(output, fmt.Sprintf("run %d · succeeded (success)", id)) {
t.Fatalf("wait output = %q", output)
}
}
// --json prints the final run envelope instead of the line.
func TestCLIWaitJSONPrintsRunEnvelope(t *testing.T) {
run, store, _ := setup(t)
ctx := context.Background()
id := seedRun(t, store, "wait-json")
if err := store.FinishRun(ctx, id, "failed", "error", "boom", map[string]any{}); err != nil {
t.Fatal(err)
}
output, err := run("wait", fmt.Sprint(id), "--json", "--timeout", "5s")
if err != nil {
t.Fatal(err)
}
var envelope protocol.Message
if err := json.Unmarshal([]byte(output), &envelope); err != nil {
t.Fatalf("--json output is not an envelope: %v\n%s", err, output)
}
if envelope.Type != protocol.Run || envelope.RunDetail == nil || envelope.RunDetail.ID != id || envelope.RunDetail.Status != "failed" {
t.Fatalf("--json envelope = %+v", envelope)
}
}
+173
View File
@@ -0,0 +1,173 @@
package cli
import (
"bytes"
"context"
"encoding/json"
"errors"
"strings"
"testing"
"time"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// runMessage builds the GetRun envelope a real server returns for one run.
func runMessage(id int64, status, outcome, stage, created, finished string) protocol.Message {
return protocol.Message{Type: protocol.Run, RunDetail: &protocol.RunDetail{RunSummary: protocol.RunSummary{
ID: id,
Status: status,
Outcome: outcome,
CurrentStage: stage,
CreatedAt: created,
FinishedAt: finished,
}}}
}
// The report line carries the run id, status, outcome, stage and duration.
func TestWaitLineReportsStatusOutcomeStageAndDuration(t *testing.T) {
line := waitLine(runMessage(12, "succeeded", "success", "reviewer", "2026-10-09T00:00:00Z", "2026-10-09T00:01:02Z").RunDetail)
for _, want := range []string{"run 12", "succeeded", "success", "reviewer", "1m2s"} {
if !strings.Contains(line, want) {
t.Fatalf("wait line %q missing %q", line, want)
}
}
// A run with no recorded outcome or stage still renders a single line.
plain := waitLine(runMessage(13, "canceled", "", "", "2026-10-09T00:00:00Z", "2026-10-09T00:00:09Z").RunDetail)
if plain != "run 13 · canceled · 9s" {
t.Fatalf("sparse wait line = %q", plain)
}
// A missing start time omits the duration rather than inventing one.
if got := waitLine(runMessage(14, "failed", "error", "worker", "", "2026-10-09T00:00:09Z").RunDetail); got != "run 14 · failed (error) · worker" {
t.Fatalf("undated wait line = %q", got)
}
}
// Every named run is reported, and a run that finished unsuccessfully is still
// a finished run: the wait exits 0 and says what happened.
func TestWaitReportsEachRunAndDoesNotFailOnUnsuccessfulRuns(t *testing.T) {
var out bytes.Buffer
app := App{Out: &out, Err: &out}
done := map[int64]protocol.Message{
2: runMessage(2, "succeeded", "success", "reviewer", "2026-10-09T00:00:00Z", "2026-10-09T00:01:02Z"),
3: runMessage(3, "failed", "error", "worker", "2026-10-09T00:00:00Z", "2026-10-09T00:00:09Z"),
}
call := func(request protocol.Message) (protocol.Message, error) { return done[request.RunID], nil }
if err := app.wait(context.Background(), []string{"2", "3"}, &options{}, call); err != nil {
t.Fatalf("a finished failed run must not fail the wait: %v", err)
}
text := out.String()
for _, want := range []string{
"run 2 · succeeded (success) · reviewer · 1m2s",
"run 3 · failed (error) · worker · 9s",
} {
if !strings.Contains(text, want) {
t.Fatalf("wait output missing %q:\n%s", want, text)
}
}
}
// The wait returns as soon as the run goes terminal, using the same GetRun
// reattachment as run --wait.
func TestWaitReturnsWhenRunGoesTerminal(t *testing.T) {
var out bytes.Buffer
app := App{Out: &out, Err: &out}
reads := 0
call := func(protocol.Message) (protocol.Message, error) {
reads++
if reads <= 1 {
return runMessage(5, "running", "", "worker", "", ""), nil
}
return runMessage(5, "succeeded", "success", "worker", "2026-10-09T00:00:00Z", "2026-10-09T00:00:04Z"), nil
}
start := time.Now()
if err := app.wait(context.Background(), []string{"5"}, &options{}, call); err != nil {
t.Fatal(err)
}
if elapsed := time.Since(start); elapsed > 3*time.Second {
t.Fatalf("wait did not return promptly after terminal: %s", elapsed)
}
if !strings.Contains(out.String(), "run 5 · succeeded (success) · worker · 4s") {
t.Fatalf("wait output = %q", out.String())
}
if reads != 2 {
t.Fatalf("expected the initial read plus one poll, got %d", reads)
}
}
// An unknown run id is a client error and never blocks.
func TestWaitRefusesUnknownRunWithoutHanging(t *testing.T) {
app := App{Out: &bytes.Buffer{}, Err: &bytes.Buffer{}}
call := func(protocol.Message) (protocol.Message, error) {
return protocol.Message{}, errors.New("run not found")
}
start := time.Now()
err := app.wait(context.Background(), []string{"999"}, &options{}, call)
if err == nil || !strings.Contains(err.Error(), "run not found") {
t.Fatalf("unknown run not refused: %v", err)
}
if elapsed := time.Since(start); elapsed > time.Second {
t.Fatalf("unknown run hung for %s", elapsed)
}
}
// A timeout says the run is still active and never cancels, re-reads or reports
// the run as its outcome.
func TestWaitTimeoutLeavesRunActiveAndSaysSo(t *testing.T) {
var out bytes.Buffer
app := App{Out: &out, Err: &out}
reads := 0
call := func(protocol.Message) (protocol.Message, error) {
reads++
return runMessage(7, "running", "", "worker", "", ""), nil
}
err := app.wait(context.Background(), []string{"7"}, &options{timeout: 50 * time.Millisecond}, call)
if err == nil {
t.Fatal("timeout not reported")
}
for _, want := range []string{"still active", "not canceled", "run 7"} {
if !strings.Contains(err.Error(), want) {
t.Fatalf("timeout message %q missing %q", err.Error(), want)
}
}
if reads != 1 {
t.Fatalf("timeout re-read the run %d times", reads)
}
if out.Len() != 0 {
t.Fatalf("timeout printed a report as if it were an outcome: %q", out.String())
}
}
// --json prints the final run envelope: one envelope for one id, an array for
// several.
func TestWaitJSONPrintsFinalRunEnvelope(t *testing.T) {
done := map[int64]protocol.Message{
2: runMessage(2, "succeeded", "success", "reviewer", "2026-10-09T00:00:00Z", "2026-10-09T00:00:01Z"),
3: runMessage(3, "failed", "error", "worker", "2026-10-09T00:00:00Z", "2026-10-09T00:00:02Z"),
}
call := func(request protocol.Message) (protocol.Message, error) { return done[request.RunID], nil }
var single bytes.Buffer
if err := (App{Out: &single, Err: &single}).wait(context.Background(), []string{"2"}, &options{json: true}, call); err != nil {
t.Fatal(err)
}
var envelope protocol.Message
if err := json.Unmarshal(single.Bytes(), &envelope); err != nil {
t.Fatalf("single-id --json is not one envelope: %v\n%s", err, single.String())
}
if envelope.Type != protocol.Run || envelope.RunDetail == nil || envelope.RunDetail.ID != 2 {
t.Fatalf("single-id --json envelope = %+v", envelope)
}
var many bytes.Buffer
if err := (App{Out: &many, Err: &many}).wait(context.Background(), []string{"2", "3"}, &options{json: true}, call); err != nil {
t.Fatal(err)
}
var envelopes []protocol.Message
if err := json.Unmarshal(many.Bytes(), &envelopes); err != nil {
t.Fatalf("multi-id --json is not an array: %v\n%s", err, many.String())
}
if len(envelopes) != 2 || envelopes[0].RunDetail.ID != 2 || envelopes[1].RunDetail.ID != 3 {
t.Fatalf("multi-id --json envelopes = %+v", envelopes)
}
}