cmd: add video download command (PRINFRA-139) (#38)

## Description

Adds `heygen video download <video-id>` — a hand-written command that fetches video metadata from the API, extracts the CDN URL, and streams the file to disk. Supports downloading the regular video or the captioned version via `--asset`.

**Flow:**
1. `GET /v3/videos/{video_id}` via the authenticated API client → extracts the asset URL from the response
2. HTTP GET to the CDN URL via a dedicated client (pre-signed URL, no auth needed, 10-minute timeout)

**`--asset` flag:** Selects which file to download from the API response. The video response includes multiple downloadable URLs (`video_url`, `captioned_video_url`, etc.). Phase 1 supports two values:
- `video` (default) — `data.video_url`, the rendered video
- `captioned` — `data.captioned_video_url`, the video with captions burned in

Invalid values get exit code 2 listing valid options. If the video is completed but the requested asset URL is null (e.g., captioned version wasn't generated), exit 1 with an asset-specific hint. The `assetTypes` map is extensible — Phase 2 can add `subtitle`, `thumbnail`, `gif` as one-line entries.

**Output path:** Defaults to `{video-id}.mp4` in the current directory. Override with `--output-path custom.mp4`. The video ID is sanitized with `filepath.Base()` to prevent path traversal.

**Safe file writes:** Downloads to a temp file in the same directory, then atomic-renames on success. If the download fails mid-stream, any existing file at the destination is preserved — no data loss.

**Status-aware errors:**
- Video still processing → exit 1 with hint: "Use --wait when creating"
- Video failed → exit 1 with hint: "Check details with: heygen video get {id}"
- Video not found → exit 1 with standard API error

**Success output:** JSON to stdout with `asset`, `message`, and `path` fields — agents know which asset was downloaded and where.

**Command wiring:** Introduces `attachCustomCommands()` and `findGroup()` helpers in root.go for attaching hand-written commands to generated group nodes.

Stacked on PR #34 (polling).
Linear: PRINFRA-139

## Testing

11 tests covering: success with file content verification, default filename, custom `--output-path`, existing file preserved on download failure, video not found (404), video still processing (hint to use --wait), CDN download failure (no partial file left), auth required (exit 3), `--asset captioned` downloads correct file, `--asset foo` returns exit 2 with valid options, captioned URL null on completed video returns exit 1 with hint.

All tests use `t.TempDir()` with absolute paths — no `os.Chdir`, safe for `t.Parallel()`. All use `httptest.Server` — no real API calls.

Author: somanshreddy

cmd/heygen/root.go

@@ -51,6 +51,7 @@ Exit Codes:
 	root.AddCommand(newAuthCmd(ctx))
 	root.AddCommand(newConfigCmd(ctx))
 	registerGroups(root, ctx, gen.Groups)
+	attachCustomCommands(root, ctx)
 	installFlattenedHelp(root)
 
 	return root
@@ -81,6 +82,7 @@ func newRootCmdWithSpecs(version string, formatter output.Formatter, groups map[
 	root.AddCommand(newAuthCmd(ctx))
 	root.AddCommand(newConfigCmd(ctx))
 	registerGroups(root, ctx, groups)
+	attachCustomCommands(root, ctx)
 	installFlattenedHelp(root)
 
 	return root
@@ -106,6 +108,12 @@ func registerGroups(root *cobra.Command, ctx *cmdContext, groups map[string][]*c
 	}
 }
 
+func attachCustomCommands(root *cobra.Command, ctx *cmdContext) {
+	if videoGroup := findGroup(root, "video"); videoGroup != nil {
+		videoGroup.AddCommand(newVideoDownloadCmd(ctx))
+	}
+}
+
 func registerSpecCommand(groupCmd *cobra.Command, spec *command.Spec, ctx *cmdContext) {
 	path := commandPathParts(spec)
 	if len(path) == 0 {
@@ -121,6 +129,15 @@ func registerSpecCommand(groupCmd *cobra.Command, spec *command.Spec, ctx *cmdCo
 	parent.AddCommand(buildCobraCommand(spec, ctx))
 }
 
+func findGroup(root *cobra.Command, name string) *cobra.Command {
+	for _, child := range root.Commands() {
+		if child.Name() == name {
+			return child
+		}
+	}
+	return nil
+}
+
 func ensureIntermediateCommand(parent *cobra.Command, token string) *cobra.Command {
 	for _, child := range parent.Commands() {
 		if child.Name() == token {

cmd/heygen/video_download.go

@@ -0,0 +1,203 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/heygen-com/heygen-cli/internal/command"
+	clierrors "github.com/heygen-com/heygen-cli/internal/errors"
+	"github.com/spf13/cobra"
+)
+
+var downloadClient = &http.Client{Timeout: 10 * time.Minute}
+
+type assetInfo struct {
+	field string
+	ext   string
+	label string
+}
+
+var assetTypes = map[string]assetInfo{
+	"video":     {field: "video_url", ext: ".mp4", label: "video"},
+	"captioned": {field: "captioned_video_url", ext: ".mp4", label: "captioned video"},
+}
+
+func newVideoDownloadCmd(ctx *cmdContext) *cobra.Command {
+	var outputPath string
+	var asset string
+
+	cmd := &cobra.Command{
+		Use:   "download <video-id>",
+		Short: "Download a video file or related asset to disk",
+		Args:  cobra.ExactArgs(1),
+		Example: "heygen video download <video-id>\n" +
+			"heygen video download <video-id> --asset captioned\n" +
+			"heygen video download <video-id> --output-path my-video.mp4",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			videoID := args[0]
+			info, ok := assetTypes[asset]
+			if !ok {
+				return clierrors.NewUsage(
+					fmt.Sprintf("invalid --asset value %q: must be one of: video, captioned", asset))
+			}
+
+			spec := &command.Spec{
+				Endpoint: "/v3/videos/{video_id}",
+				Method:   http.MethodGet,
+			}
+			inv := &command.Invocation{
+				PathParams:  map[string]string{"video_id": videoID},
+				QueryParams: make(url.Values),
+			}
+			result, err := ctx.client.Execute(spec, inv)
+			if err != nil {
+				return err
+			}
+
+			assetURL, err := extractAssetURL(result, videoID, info)
+			if err != nil {
+				return err
+			}
+
+			dest := outputPath
+			if dest == "" {
+				// Sanitize: strip directory components from video ID to prevent
+				// path traversal. Handles IDs with / or \ safely.
+				dest = filepath.Base(videoID) + info.ext
+			}
+
+			if err := downloadFile(cmd.Context(), assetURL, dest); err != nil {
+				return err
+			}
+
+			data, err := json.Marshal(map[string]string{
+				"asset":   asset,
+				"message": fmt.Sprintf("Downloaded %s to %s", info.label, dest),
+				"path":    dest,
+			})
+			if err != nil {
+				return clierrors.New(fmt.Sprintf("failed to encode response: %v", err))
+			}
+
+			return ctx.formatter.Data(data, "", nil)
+		},
+	}
+
+	cmd.Flags().StringVar(&asset, "asset", "video", "Asset to download: video, captioned")
+	cmd.Flags().StringVar(&outputPath, "output-path", "", "Output file path (default: {video-id}.mp4)")
+	return cmd
+}
+
+func extractAssetURL(raw json.RawMessage, videoID string, info assetInfo) (string, error) {
+	var resp struct {
+		Data map[string]json.RawMessage `json:"data"`
+	}
+	if err := json.Unmarshal(raw, &resp); err != nil {
+		return "", clierrors.New("failed to parse video response")
+	}
+
+	var status string
+	if rawStatus, ok := resp.Data["status"]; ok {
+		_ = json.Unmarshal(rawStatus, &status)
+	}
+
+	var assetURL string
+	if rawURL, ok := resp.Data[info.field]; ok {
+		_ = json.Unmarshal(rawURL, &assetURL)
+	}
+
+	if assetURL == "" {
+		switch status {
+		case "failed", "error":
+			return "", &clierrors.CLIError{
+				Code:     "video_failed",
+				Message:  fmt.Sprintf("video rendering failed (status: %s)", status),
+				Hint:     "Check details with: heygen video get " + videoID,
+				ExitCode: clierrors.ExitGeneral,
+			}
+		case "completed":
+			return "", &clierrors.CLIError{
+				Code:     "asset_not_available",
+				Message:  fmt.Sprintf("%s not available for this video", info.label),
+				Hint:     assetHint(info.field),
+				ExitCode: clierrors.ExitGeneral,
+			}
+		default:
+			msg := fmt.Sprintf("%s URL not available", info.label)
+			if status != "" {
+				msg = fmt.Sprintf("%s URL not available (status: %s)", info.label, status)
+			}
+			return "", &clierrors.CLIError{
+				Code:     "video_not_ready",
+				Message:  msg,
+				Hint:     "Use --wait when creating: heygen video create ... --wait",
+				ExitCode: clierrors.ExitGeneral,
+			}
+		}
+	}
+
+	return assetURL, nil
+}
+
+func assetHint(field string) string {
+	switch field {
+	case "captioned_video_url":
+		return "Video may not have been created with captions enabled."
+	default:
+		return ""
+	}
+}
+
+func downloadFile(ctx context.Context, videoURL, dest string) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, videoURL, nil)
+	if err != nil {
+		return clierrors.New(fmt.Sprintf("failed to build download request: %v", err))
+	}
+
+	resp, err := downloadClient.Do(req)
+	if err != nil {
+		return clierrors.New(fmt.Sprintf("failed to download video: %v", err))
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return clierrors.New(fmt.Sprintf("download failed with HTTP %d", resp.StatusCode))
+	}
+
+	// Write to a temp file in the same directory, then rename on success.
+	// This prevents destroying an existing file on partial download failure.
+	dir := filepath.Dir(dest)
+	tmp, err := os.CreateTemp(dir, ".heygen-download-*.tmp")
+	if err != nil {
+		return clierrors.New(fmt.Sprintf("failed to create temp file in %q: %v", dir, err))
+	}
+	tmpPath := tmp.Name()
+
+	_, copyErr := io.Copy(tmp, resp.Body)
+	closeErr := tmp.Close()
+	if copyErr != nil {
+		_ = os.Remove(tmpPath)
+		return clierrors.New(fmt.Sprintf("download interrupted: %v", copyErr))
+	}
+	if closeErr != nil {
+		_ = os.Remove(tmpPath)
+		return clierrors.New(fmt.Sprintf("failed to finalize download: %v", closeErr))
+	}
+
+	// Atomic rename. On Windows this may fail if dest is open elsewhere;
+	// os.Rename across filesystems also fails, but temp file is in the
+	// same directory so this is safe.
+	if err := os.Rename(tmpPath, dest); err != nil {
+		_ = os.Remove(tmpPath)
+		return clierrors.New(fmt.Sprintf("failed to move download to %q: %v", dest, err))
+	}
+
+	return nil
+}