Files
pipelines/internal/cli/wait_test.go
T
alan b7c2ba7d56 cli: add wait <run-id> 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> [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.
2026-10-18 01:11:26 +01:00

174 lines
6.5 KiB
Go

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)
}
}