Files
pipelines/internal/cli/wait_command_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

191 lines
6.2 KiB
Go

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