cmd: add --wait polling framework (PRINFRA-125) (#34)

## Description

Adds `--wait` flag to async commands (video create, video-translate create, video-agent create). When set, the CLI polls the status endpoint with exponential backoff until the resource reaches a terminal state, then outputs the final resource JSON — same as running the corresponding `get` command after completion.

**How it works:**
1. Execute the create request, extract the resource ID from the response (via dot-notation `IDField`, e.g., `data.video_id`)
2. Poll the status endpoint (e.g., `GET /v3/videos/{video_id}`) with exponential backoff (2s initial, up to 30s, with jitter)
3. Check the status field (e.g., `data.status`) against terminal states
4. Success (`completed`) → stdout gets the final resource JSON, exit 0
5. Failure (`failed`) → stdout gets the failure response (contains error details), stderr gets structured error, exit 1
6. Timeout (`--timeout`, default 10m) → stderr gets timeout message with hint, exit 1

**PollConfig registrations** (hand-written in `cmd/heygen/poll_configs.go`):

| Command | Status Endpoint | ID Field | Terminal States |
|---|---|---|---|
| `video create` | `GET /v3/videos/{video_id}` | `data.video_id` | OK: `completed`, Fail: `failed` |
| `video-translate create` | `GET /v3/video-translations/{video_translation_id}` | `data.video_translation_ids.0` | OK: `completed`, Fail: `failed` |
| `video-agent create` | `GET /v3/videos/{video_id}` | `data.video_id` | OK: `completed`, Fail: `failed` |

PollConfigs are looked up at call time in the builder via `pollConfigs[spec.Group+"/"+spec.Name]` — Specs are never mutated. Adding polling for a new async command is one entry in `poll_configs.go`. Field names and terminal states verified against experiment-framework DTOs.

**Timeout:** Owned by `ensurePollContext` inside `ExecuteAndPoll`. The builder passes `cmd.Context()` and `Timeout` in `PollOptions`; `ensurePollContext` adds the deadline. Single timeout owner.

**Context-aware:** Ctrl-C cancellation and timeout both work. Context errors from `Execute()` (wrapped as `network_error` in CLIError) are unwrapped and translated to clean `timeout`/`canceled` CLIErrors.

**Progress:** Only emitted in `--human` mode — one line per status *change* (`Polling: status=processing (elapsed 12s)`). JSON mode keeps stderr clean for machine consumption (structured errors only).

**Failure response preserved:** `ErrPollFailed` carries the full status response. The builder outputs it to stdout (users see error details without a second API call) then returns exit 1.

**`--human` support:** The `--wait` path passes `client.APIDataField` and nil columns to the formatter — single objects render as key-value pairs, matching the corresponding `get` command.

**Batch rejection:** `video-translate create` returns a list of IDs (`video_translation_ids`). `--wait` extracts the first element via array index (`.0`). If the list has >1 element (multi-language batch), returns `batch_not_supported` error with hint to poll manually. Single-language requests work normally.

**`extractJSONPath` supports array indices:** Dot-notation paths like `data.ids.0` walk into arrays. Used for video-translate's list-based ID field.

Stacked on PR #31 (pagination) → PR #29 (retries).

Linear: PRINFRA-125

## Testing

10 executor tests: immediate success, polls-until-complete (3 status calls), failure state with response preserved, timeout during backoff, timeout during HTTP request (server blocks), create fails (no polling), status callback, extractJSONPath (nested, missing, array index, array out of bounds, non-array), batch rejection (3 IDs), single-array-element OK.

5 builder integration tests: wait success (no progress in JSON mode), wait failure (response on stdout), wait timeout, no-wait (create response only), wait on non-pollable command (unknown flag).

1 validation test: all PollConfig keys match generated Specs (catches orphaned configs).

All tests use `httptest.Server` — no real API calls. Polling delays set to 1ms in tests for fast execution.

Author: somanshreddy

cmd/heygen/builder.go

@@ -2,15 +2,18 @@ package main
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"os"
 	"strconv"
 	"strings"
+	"time"
 
 	"github.com/heygen-com/heygen-cli/internal/client"
 	"github.com/heygen-com/heygen-cli/internal/command"
 	clierrors "github.com/heygen-com/heygen-cli/internal/errors"
+	"github.com/heygen-com/heygen-cli/internal/output"
 	"github.com/spf13/cobra"
 )
 
@@ -42,6 +45,57 @@ func buildCobraCommand(spec *command.Spec, ctx *cmdContext) *cobra.Command {
 				return err
 			}
 
+			// Poll config is looked up at call time, not attached to Spec.
+			// Spec is immutable (generated); poll configs are hand-written in cmd/.
+			pc := pollConfigs[spec.Group+"/"+spec.Name]
+			if pc != nil {
+				wait, _ := cmd.Flags().GetBool("wait")
+				if wait {
+					timeout, _ := cmd.Flags().GetDuration("timeout")
+
+					// Let ExecuteAndPoll own the timeout via ensurePollContext.
+					// Don't wrap cmd.Context() with WithTimeout here.
+					pollSpec := *spec
+					pollSpec.PollConfig = pc
+
+					opts := client.PollOptions{
+						Timeout:   timeout,
+						BaseDelay: 2 * time.Second,
+						MaxDelay:  30 * time.Second,
+					}
+					// Only emit progress in human mode. JSON mode keeps stderr
+					// clean for machine consumption (structured errors only).
+					if _, ok := ctx.formatter.(*output.HumanFormatter); ok {
+						var lastStatus string
+						opts.OnStatus = func(status string, elapsed time.Duration) {
+							if status == lastStatus {
+								return
+							}
+							fmt.Fprintf(cmd.ErrOrStderr(), "Polling: status=%s (elapsed %s)\n", status, elapsed.Round(time.Second))
+							lastStatus = status
+						}
+					}
+
+					result, err := ctx.client.ExecuteAndPoll(cmd.Context(), &pollSpec, inv, opts)
+					if err != nil {
+						var failErr *client.ErrPollFailed
+						if errors.As(err, &failErr) {
+							// Output the failure response (contains error details),
+							// then signal failure via CLIError for exit code 1.
+							if fmtErr := ctx.formatter.Data(failErr.Data, "data", nil); fmtErr != nil {
+								return fmtErr
+							}
+							return clierrors.New(failErr.Error())
+						}
+						return err
+					}
+
+					// --wait result is a single resource from the GET endpoint.
+					// Columns are nil — HumanFormatter renders single objects as
+					// key-value pairs, not tables. This matches `heygen video get`.
+					return ctx.formatter.Data(result, "data", nil)
+				}
+			}
 			result, err := ctx.client.Execute(spec, inv)
 			if err != nil {
 				return err
@@ -56,6 +110,10 @@ func buildCobraCommand(spec *command.Spec, ctx *cmdContext) *cobra.Command {
 		registerFlag(cmd, flag)
 	}
 
+	if pollConfigs[spec.Group+"/"+spec.Name] != nil {
+		cmd.Flags().Bool("wait", false, "Poll until the operation completes or fails")
+		cmd.Flags().Duration("timeout", 10*time.Minute, "Max time to wait when using --wait")
+	}
 	// Add -d/--data for commands with JSON request bodies
 	if spec.BodyEncoding == "json" {
 		cmd.Flags().StringVarP(&rawData, "data", "d", "",

cmd/heygen/builder_test.go

@@ -31,6 +31,18 @@ var videoListSpec = &command.Spec{
 	Examples: []string{"heygen video list --limit 10"},
 }
 
+// videoCreateWaitSpec has Group/Name matching pollConfigs["video/create"],
+// so the builder picks up PollConfig at call time — no need to set it here.
+var videoCreateWaitSpec = &command.Spec{
+	Group:        "video",
+	Name:         "create",
+	Summary:      "Create a video",
+	Endpoint:     "/v3/videos",
+	Method:       "POST",
+	BodyEncoding: "json",
+	Examples:     []string{"heygen video create --wait"},
+}
+
 func TestGenBuilder_VideoList_Success(t *testing.T) {
 	srv := setupTestServer(t, map[string]testHandler{
 		"GET /v3/videos": {
@@ -90,6 +102,177 @@ func TestGenBuilder_VideoList_Flags(t *testing.T) {
 	}
 }
 
+func TestGenBuilder_VideoCreate_Wait_Success(t *testing.T) {
+	var statusCalls int
+	srv := setupTestServer(t, map[string]testHandler{
+		"POST /v3/videos": {
+			StatusCode: 200,
+			Body:       `{"data":{"video_id":"vid_123"}}`,
+		},
+		"GET /v3/videos/vid_123": {
+			StatusCode: 200,
+			ValidateRequest: func(t *testing.T, r *http.Request) {
+				t.Helper()
+				statusCalls++
+			},
+			Body: `{"data":{"video_id":"vid_123","status":"processing"}}`,
+		},
+	})
+	defer srv.Close()
+
+	originalHandler := srv.Config.Handler
+	srv.Config.Handler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodGet && r.URL.Path == "/v3/videos/vid_123" {
+			statusCalls++
+			w.WriteHeader(http.StatusOK)
+			if statusCalls < 2 {
+				_, _ = w.Write([]byte(`{"data":{"video_id":"vid_123","status":"processing"}}`))
+				return
+			}
+			_, _ = w.Write([]byte(`{"data":{"video_id":"vid_123","status":"completed","video_url":"https://cdn.test/video.mp4"}}`))
+			return
+		}
+		originalHandler.ServeHTTP(w, r)
+	})
+
+	res := runGenCommand(t, srv.URL, "test-key", videoCreateWaitSpec, "create", "--wait")
+
+	if res.ExitCode != 0 {
+		t.Fatalf("ExitCode = %d, want 0\nstderr: %s", res.ExitCode, res.Stderr)
+	}
+
+	var parsed map[string]any
+	if err := json.Unmarshal([]byte(res.Stdout), &parsed); err != nil {
+		t.Fatalf("stdout is not valid JSON: %v\nstdout: %s", err, res.Stdout)
+	}
+	data := parsed["data"].(map[string]any)
+	if data["status"] != "completed" {
+		t.Fatalf("status = %v, want completed", data["status"])
+	}
+	// JSON mode: no progress on stderr (keeps it machine-readable).
+	// Progress is only emitted in --human mode.
+	if strings.Contains(res.Stderr, "Polling:") {
+		t.Fatalf("stderr should not contain progress in JSON mode: %s", res.Stderr)
+	}
+}
+
+func TestGenBuilder_VideoCreate_Wait_Failure(t *testing.T) {
+	srv := setupTestServer(t, map[string]testHandler{
+		"POST /v3/videos": {
+			StatusCode: 200,
+			Body:       `{"data":{"video_id":"vid_123"}}`,
+		},
+		"GET /v3/videos/vid_123": {
+			StatusCode: 200,
+			Body:       `{"data":{"video_id":"vid_123","status":"failed"}}`,
+		},
+	})
+	defer srv.Close()
+
+	res := runGenCommand(t, srv.URL, "test-key", videoCreateWaitSpec, "create", "--wait")
+
+	if res.ExitCode != 1 {
+		t.Fatalf("ExitCode = %d, want 1\nstderr: %s", res.ExitCode, res.Stderr)
+	}
+	if !strings.Contains(res.Stderr, "operation reached terminal failure state: failed") {
+		t.Fatalf("stderr = %s, want failure message", res.Stderr)
+	}
+	// Failure response should be output to stdout so users can see error details
+	var parsed map[string]any
+	if err := json.Unmarshal([]byte(res.Stdout), &parsed); err != nil {
+		t.Fatalf("stdout should contain failure response: %v\nstdout: %s", err, res.Stdout)
+	}
+	data := parsed["data"].(map[string]any)
+	if data["status"] != "failed" {
+		t.Fatalf("status = %v, want failed", data["status"])
+	}
+}
+
+func TestGenBuilder_VideoCreate_Wait_Timeout(t *testing.T) {
+	srv := setupTestServer(t, map[string]testHandler{
+		"POST /v3/videos": {
+			StatusCode: 200,
+			Body:       `{"data":{"video_id":"vid_123"}}`,
+		},
+		"GET /v3/videos/vid_123": {
+			StatusCode: 200,
+			Body:       `{"data":{"video_id":"vid_123","status":"processing"}}`,
+		},
+	})
+	defer srv.Close()
+
+	res := runGenCommand(t, srv.URL, "test-key", videoCreateWaitSpec, "create", "--wait", "--timeout", "20ms")
+
+	if res.ExitCode != 1 {
+		t.Fatalf("ExitCode = %d, want 1\nstderr: %s", res.ExitCode, res.Stderr)
+	}
+	if !strings.Contains(res.Stderr, "polling timed out before the operation completed") {
+		t.Fatalf("stderr = %s, want timeout message", res.Stderr)
+	}
+}
+
+func TestGenBuilder_VideoCreate_NoWait(t *testing.T) {
+	var statusCalled bool
+	srv := setupTestServer(t, map[string]testHandler{
+		"POST /v3/videos": {
+			StatusCode: 200,
+			Body:       `{"data":{"video_id":"vid_123","status":"pending"}}`,
+		},
+		"GET /v3/videos/vid_123": {
+			StatusCode: 200,
+			ValidateRequest: func(t *testing.T, r *http.Request) {
+				t.Helper()
+				statusCalled = true
+			},
+			Body: `{"data":{"video_id":"vid_123","status":"completed"}}`,
+		},
+	})
+	defer srv.Close()
+
+	res := runGenCommand(t, srv.URL, "test-key", videoCreateWaitSpec, "create")
+
+	if res.ExitCode != 0 {
+		t.Fatalf("ExitCode = %d, want 0\nstderr: %s", res.ExitCode, res.Stderr)
+	}
+	if statusCalled {
+		t.Fatal("status endpoint should not be called without --wait")
+	}
+	var parsed map[string]any
+	if err := json.Unmarshal([]byte(res.Stdout), &parsed); err != nil {
+		t.Fatalf("stdout is not valid JSON: %v\nstdout: %s", err, res.Stdout)
+	}
+	data := parsed["data"].(map[string]any)
+	if data["status"] != "pending" {
+		t.Fatalf("status = %v, want pending", data["status"])
+	}
+}
+
+func TestGenBuilder_VideoCreate_WaitNotAvailable(t *testing.T) {
+	nonPollable := &command.Spec{
+		Group:    "video",
+		Name:     "get",
+		Summary:  "Get video",
+		Endpoint: "/v3/videos/{video_id}",
+		Method:   "GET",
+		Args: []command.ArgSpec{
+			{Name: "video-id", Param: "video_id"},
+		},
+		Examples: []string{"heygen video get <video-id>"},
+	}
+
+	srv := setupTestServer(t, map[string]testHandler{})
+	defer srv.Close()
+
+	res := runGenCommand(t, srv.URL, "test-key", nonPollable, "get", "vid_123", "--wait")
+
+	if res.ExitCode != 2 {
+		t.Fatalf("ExitCode = %d, want 2\nstderr: %s", res.ExitCode, res.Stderr)
+	}
+	if !strings.Contains(res.Stderr, "unknown flag: --wait") {
+		t.Fatalf("stderr = %s, want unknown flag error", res.Stderr)
+	}
+}
+
 func TestGenBuilder_PostWithBodyFlags(t *testing.T) {
 	var gotBody map[string]any
 
@@ -407,6 +590,9 @@ func runGeneratedRootCommand(t *testing.T, serverURL, apiKey string, groups map[
 
 	t.Setenv("HEYGEN_API_KEY", apiKey)
 	t.Setenv("HEYGEN_API_BASE", serverURL)
+	if _, ok := os.LookupEnv("HEYGEN_CONFIG_DIR"); !ok {
+		t.Setenv("HEYGEN_CONFIG_DIR", t.TempDir())
+	}
 
 	root := newRootCmdWithSpecs("test", formatter, groups)
 	root.SetOut(&stdout)

cmd/heygen/poll_configs.go

@@ -0,0 +1,35 @@
+package main
+
+import "github.com/heygen-com/heygen-cli/internal/command"
+
+// pollConfigs maps "group/spec.Name" to PollConfig for async commands.
+// Keys use the full spec name to avoid collisions within a group.
+var pollConfigs = map[string]*command.PollConfig{
+	"video/create": {
+		StatusEndpoint: "/v3/videos/{video_id}",
+		StatusField:    "data.status",
+		TerminalOK:     []string{"completed"},
+		TerminalFail:   []string{"failed"},
+		IDField:        "data.video_id",
+	},
+	// The create response returns video_translation_ids (plural, always a list
+	// even for single-language requests). We extract the first element with ".0".
+	// Batch mode (multiple languages) is not supported by --wait.
+	"video-translate/create": {
+		StatusEndpoint: "/v3/video-translations/{video_translation_id}",
+		StatusField:    "data.status",
+		TerminalOK:     []string{"completed"},
+		TerminalFail:   []string{"failed"},
+		IDField:        "data.video_translation_ids.0",
+	},
+	// video-agent returns session_id + video_id. We poll the video status.
+	// video_id can be null in future multi-turn flows — extractJSONPath
+	// will return an error, which is correct (can't poll without an ID).
+	"video-agent/create": {
+		StatusEndpoint: "/v3/videos/{video_id}",
+		StatusField:    "data.status",
+		TerminalOK:     []string{"completed"},
+		TerminalFail:   []string{"failed"},
+		IDField:        "data.video_id",
+	},
+}

cmd/heygen/poll_configs_test.go

@@ -0,0 +1,28 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/heygen-com/heygen-cli/gen"
+)
+
+func TestPollConfigs_AllReferencedCommandsExist(t *testing.T) {
+	for key := range pollConfigs {
+		found := false
+		for group, specs := range gen.Groups {
+			for _, spec := range specs {
+				if key == group+"/"+spec.Name {
+					found = true
+					break
+				}
+			}
+			if found {
+				break
+			}
+		}
+
+		if !found {
+			t.Errorf("poll config key %q does not match any generated spec", key)
+		}
+	}
+}