From b7c2ba7d569c68b5e63998ae60ccf87d57311324 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 18 Oct 2026 01:11:26 +0100 Subject: [PATCH] cli: add `wait ` to block until runs finish, then report them The harness resumes a session when a background command finishes, so "tell me when this run is done" needs one command that blocks and exits rather than a polling script. - `pipelines wait [run-id ...]` resolves every id up front (an unknown run is a fast client error), then polls each run to a terminal status - `succeeded`, `failed`, `canceled` or `interrupted`, blocking through a run parked on a human decision - and prints one line per run as it finishes with id, status and outcome, stage and duration. - A finished-but-unsuccessful run is still a finished run: it is reported and the command 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. - Reuses the existing `run --wait` polling machinery: the per-second `get_run` reattachment is factored into `awaitRuns`, used by `finishRun` too. No subscription or new protocol message. `--url`/`--timeout` follow the existing client conventions; `--timeout` is the overall client limit (default 0). - Read-only: sends only `get_run`, resolves no workspace, is not refused by the workspace guard and writes nothing. `--json` prints the final run envelope (one envelope for one id, an array for several). - `commands.go` and `help.go` add it to the usage inventory and EXECUTE help. Tests: `wait_test.go` (line format, batch reporting, wait-until-terminal, unknown id, timeout leaves the run active, `--json` shape) and `wait_command_test.go` (real CLI against the real websocket server and store). Packaged assets checked: no packaged template changes. No authoring skill reference file is added, so `internal/author/install.go`'s managed inventory needs no change. `internal/author/skill/references/operations.md` (the "inspect results first" run-operations list) and `docs/cli.md` (the scripted-runs `--wait` paragraph and the CLI/TUI capability-map row) are now stale and are recorded - not edited - in `docs/notes/wait-command.md` for the `docs-fold` writer. `SKILL.md` stays a task-directed index; no shared document is edited here. No protocol, server, store, TUI or Android change; no new dependency; no run started. Committed locally only, not pushed or deployed. --- docs/notes/wait-command.md | 92 ++++++++++++ internal/cli/app.go | 227 +++++++++++++++++++++++++++--- internal/cli/commands.go | 2 + internal/cli/help.go | 1 + internal/cli/wait_command_test.go | 190 +++++++++++++++++++++++++ internal/cli/wait_test.go | 173 +++++++++++++++++++++++ 6 files changed, 668 insertions(+), 17 deletions(-) create mode 100644 docs/notes/wait-command.md create mode 100644 internal/cli/wait_command_test.go create mode 100644 internal/cli/wait_test.go diff --git a/docs/notes/wait-command.md b/docs/notes/wait-command.md new file mode 100644 index 00000000..fbf18af5 --- /dev/null +++ b/docs/notes/wait-command.md @@ -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 ...]`, 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 ...]` 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`. diff --git a/internal/cli/app.go b/internal/cli/app.go index 63dad974..8311ca35 100644 --- a/internal/cli/app.go +++ b/internal/cli/app.go @@ -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. diff --git a/internal/cli/commands.go b/internal/cli/commands.go index 2c22ba22..a490e56c 100644 --- a/internal/cli/commands.go +++ b/internal/cli/commands.go @@ -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 [--json]", + "wait": "wait [run-id ...] [--timeout DURATION] [--json]", "cancel": "cancel [--json]", "decide": "decide [stage] --option KEY [--feedback TEXT] [--json]", "retry": "retry [--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 --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 --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`.", diff --git a/internal/cli/help.go b/internal/cli/help.go index 309eac5f..dd3585ef 100644 --- a/internal/cli/help.go +++ b/internal/cli/help.go @@ -26,6 +26,7 @@ EXECUTE run [name] [prompt] Fuzzy selection, multiline prompt, live inspector runs List audited runs; --pipeline filters results inspect Inspect stages, outputs, errors and status + wait ... Block until runs finish, then report each (read-only) cancel Cancel a run; changes are NOT rolled back decide [stage] Choose an option for a run waiting on a person retry Restart a failed run with its original input and directory diff --git a/internal/cli/wait_command_test.go b/internal/cli/wait_command_test.go new file mode 100644 index 00000000..73a5d406 --- /dev/null +++ b/internal/cli/wait_command_test.go @@ -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) + } +} diff --git a/internal/cli/wait_test.go b/internal/cli/wait_test.go new file mode 100644 index 00000000..81ce0da8 --- /dev/null +++ b/internal/cli/wait_test.go @@ -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) + } +}