core types + interfaces: error taxonomy, RequestSpec, Formatter, Resolver, Provider (PRINFRA-120) by somanshreddy · Pull Request #1 · heygen-com/heygen-cli

somanshreddy · 2026-03-30T18:10:45Z

Description

Defines the core types and interfaces that the rest of the CLI is built on. Every command, the HTTP executor, the output system, and the auth/config layers all depend on these.

What's introduced:

CLIError — the single error type used everywhere. Carries an error code, message, optional hint, and an exit code (0 = success, 1 = general, 2 = usage, 3 = auth). All errors rendered to stderr go through this type, ensuring consistent JSON output.
RequestSpec — the contract between commands and the HTTP layer. A command describes what API call to make (endpoint, method, query params, body fields) by filling in a RequestSpec. The executor handles the actual HTTP call. This separation is what makes codegen possible — generated commands just produce data structs.
CredentialResolver — interface for finding the API key. Today it checks one env var; later implementations will search the OS keychain and a credentials file in priority order.
Provider — interface for non-secret settings like the API base URL. Separate from credentials because config and secrets have different storage and security needs.
Formatter — interface for rendering output. Data() writes successful responses to stdout, Error() writes failures to stderr. Different implementations (JSON today, TUI tables later) can slot in without changing any command code.

Testing

Error type tests cover exit code mapping for all HTTP statuses, the JSON envelope shape, field omission for empty values, and all constructor functions.

Linear: PRINFRA-120

somanshreddy · 2026-03-30T18:10:59Z

This stack of pull requests is managed by Graphite. Learn more about stacking.

somanshreddy · 2026-03-30T21:08:49Z

+// the framework executor converts them to HTTP requests.
+//
+// All fields are defined even if not all are used yet — the codegen pipeline
+// and framework features (pagination, polling, upload) depend on this shape.


The full struct is defined upfront (including Pollable, PollConfig, FilePath, BodyEncoding) even though only a subset is used by video list. This avoids reshaping the core type when codegen, pagination, polling, and multipart upload are added.

somanshreddy · 2026-03-30T21:09:04Z

+
+// Formatter is the interface for CLI output rendering.
+// JSONFormatter outputs structured JSON. TUIFormatter (future) adds tables and progress bars.
+type Formatter interface {


Only JSONFormatter exists today. A TUIFormatter implementing this same interface will add --human mode with lipgloss tables and bubbletea spinners — no changes to commands needed.

somanshreddy · 2026-03-30T21:09:05Z

+
+// Resolver resolves API credentials.
+// EnvResolver reads from the HEYGEN_API_KEY env var.
+// Future: OS keyring and file-based credential storage with priority chain.


Currently only EnvResolver exists. The plan is to add KeyringResolver (OS keychain via go-keyring) and FileResolver (~/.heygen/credentials) with a priority chain: env > keyring > file.

this is actualy how I solved it before as well

wondering though what do other CLIs do? do we need the keyring resolver immediately or get away with just looking at the file

Good question. Here's how others handle it:

Stripe CLI: env var (STRIPE_API_KEY) → config file (~/.config/stripe/config.toml) → interactive stripe login (device auth flow). No keyring.

gh CLI: env var (GH_TOKEN) → config file (~/.config/gh/hosts.yml). No keyring.

AWS CLI: env var → ~/.aws/credentials file → instance metadata. No keyring.

None of the major CLIs use OS keyring.

File-based storage is the industry standard. We can skip keyring entirely and go: env var → config file (~/.heygen/credentials).

For this PR, env-only is intentional. File-based storage comes in future PRs (auth/config milestone).

somanshreddy · 2026-03-30T21:09:06Z

+// EnvProvider reads from env vars. FileProvider (future) reads ~/.heygen/config.toml.
+type Provider interface {
+	APIKey() string
+	BaseURL() string


Provider intentionally does NOT include APIKey() — credentials are auth.Resolver's job. This prevents two sources of truth for API keys when keyring/file storage is added.

…Resolver, Provider Stable types and interfaces that codegen and framework features build against: - CLIError with exit codes (0/1/2/3), ToErrorEnvelope for JSON output - APIError matching HeyGen's standard error envelope - FromAPIError mapping HTTP status → exit code - RequestSpec: []QueryParam, []FieldSpec, BodyEncoding, FilePath, *PollConfig - output.Formatter interface (Data + Error) - auth.CredentialResolver interface (priority chain for API keys) - config.Provider interface (non-secret settings, BaseURL only) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Industry research shows none of the major CLIs (Stripe, gh, AWS, gcloud) use OS keyring. File-based storage with 0600 permissions is the standard. Removes keyring mentions from auth resolver comment and git conventions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

linear · 2026-03-31T05:51:55Z

PRINFRA-120 CLI M0: Repo scaffold + core types

Set up the Go repository and define the core type contracts that M1 and M2 depend on.

Scope

Initialize Go module (github.com/heygen-com/heygen-cli)
Cobra root command (heygen) with --version and --help
Directory structure: cmd/heygen/, cmd/, internal/, gen/, codegen/
Makefile with build, test, lint, fmt targets
.goreleaser.yaml skeleton (6 targets)
CI pipeline (GitHub Actions): lint, test, build matrix
Core type definitions (shared contracts):
- RequestSpec struct (endpoint, method, params, body, pagination/polling fields, columns)
- CommandSpec struct (group, name, flags, columns — generated commands produce these)
- CLIError type + exit code mapping (0/1/2/3)
- Formatter interface (FormatOne, FormatList, FormatError)

Why first

These types are the shared contracts consumed by M1 (codegen, framework) and M2 (auth, config). They must be stable before parallel work begins.

Acceptance Criteria

go build produces a working heygen binary
heygen --version and heygen --help work
Core types compile and have doc comments
CI passes on all targets

somanshreddy · 2026-03-31T05:53:50Z

Merge activity

Mar 31, 5:53 AM UTC: A user started a stack merge that includes this pull request via Graphite.
Mar 31, 5:54 AM UTC: @somanshreddy merged this pull request with Graphite.

…-122) (#2) ## Description Implements the interfaces from PR #1 — this is where the actual behavior lives. **Components:** - **EnvCredentialResolver** — reads `HEYGEN_API_KEY` from the environment. If missing, returns an auth error (exit 3) with a hint telling the user what to set. - **EnvProvider** — reads `HEYGEN_API_BASE` from the environment, defaults to `https://api.heygen.com`. Used to override the API URL in tests and staging. - **Client** — wraps Go's `net/http` with automatic `x-api-key` and `User-Agent` header injection on every request. The `WithHTTPClient` option is how tests swap in a mock server. - **Executor** — takes a RequestSpec and turns it into a real HTTP call. Handles URL construction, path parameter substitution (e.g. `/v3/videos/{video_id}`), query param encoding, JSON body marshaling, and error parsing. Returns raw JSON on success or a CLIError on failure, with the API's request ID attached when available. - **JSONFormatter** — the default output renderer. Pretty-prints successful JSON to stdout, renders errors as `{"error": {...}}` envelopes to stderr. Rejects non-JSON responses as errors (the CLI's contract is structured output). **How they connect:** The root command's startup hook creates an EnvProvider, resolves credentials via EnvCredentialResolver, then builds a Client configured with the provider's base URL. Commands use the Client's Executor to run their RequestSpecs, and the Formatter to write the result. ## Testing All tests use Go's `httptest.Server` — no real API calls. Coverage includes header injection, retry scenarios, query param encoding with repeated keys, path param substitution, POST body marshaling, error envelope parsing for 400/401/500, network errors, and invalid JSON rejection. Linear: [PRINFRA-122](https://linear.app/heygen/issue/PRINFRA-122)

…RA-142) (#3) ## Description Wires everything from PRs #1 and #2 into a working CLI. After this, `heygen video list` works end-to-end against the real HeyGen API. **What happens when you run `heygen video list --limit 5`:** 1. `main.go` creates a JSON formatter before anything else — so even early failures (bad auth, bad flags) get structured JSON error output, never plain text. 2. Cobra parses the command and flags. Unknown commands and bad flags are caught and returned as usage errors (exit 2). 3. The root command's startup hook runs: creates a config provider, resolves the API key, and builds an HTTP client. 4. The `video list` command validates `--limit` is 1-100, builds a RequestSpec, and hands it to the executor. 5. The executor makes the HTTP call and returns raw JSON. The formatter pretty-prints it to stdout. 6. If anything fails at any step, the error flows back to `main.go` where it's classified (auth → exit 3, usage → exit 2, everything else → exit 1) and rendered as a JSON envelope to stderr. **Test harness:** `runCommand()` in the test helper mirrors this exact flow — fresh Cobra tree, buffer-backed formatter, same error classification. Tests assert on exit codes and the JSON envelope shape, not just whether an error occurred. ## Testing 10 command tests using httptest mocks: - Success with valid JSON response - Missing auth (exit 3 with hint) - API 401 and 400 responses (correct exit codes, request ID preserved) - Flags passed correctly as query params - Limit validation (exit 2 for 0, -5, 999) - Unknown flag and unknown command (exit 2) - Server error (exit 1) Manual smoke test: `HEYGEN_API_KEY=<key> ./bin/heygen video list --limit 2` returns real video JSON. Linear: [PRINFRA-142](https://linear.app/heygen/issue/PRINFRA-142)

This was referenced Mar 30, 2026

implementations: auth, HTTP client, executor, JSON formatter (PRINFRA-122) #2

Merged

walking skeleton: Cobra root, video list command, test harness (PRINFRA-142) #3

Merged

add CI: build, test, lint on PRs and main pushes #4

Merged

somanshreddy marked this pull request as ready for review March 30, 2026 21:00

somanshreddy force-pushed the 03-30-m0_core_types branch from 32f2730 to bb0b001 Compare March 30, 2026 21:05

somanshreddy changed the title ~~[M0] core types + interfaces: the stable contracts~~ core types + interfaces: error taxonomy, RequestSpec, Formatter, Resolver, Provider Mar 30, 2026

somanshreddy commented Mar 30, 2026

View reviewed changes

somanshreddy force-pushed the 03-30-m0_core_types branch 2 times, most recently from 740533d to 0b271fa Compare March 30, 2026 22:10

somanshreddy force-pushed the 03-30-m0_core_types branch from 0b271fa to 5059ec9 Compare March 30, 2026 22:24

somanshreddy self-assigned this Mar 30, 2026

jrusso1020 approved these changes Mar 31, 2026

View reviewed changes

somanshreddy changed the title ~~core types + interfaces: error taxonomy, RequestSpec, Formatter, Resolver, Provider~~ core types + interfaces: error taxonomy, RequestSpec, Formatter, Resolver, Provider (PRINFRA-120) Mar 31, 2026

somanshreddy merged commit 5a34029 into main Mar 31, 2026
9 checks passed

somanshreddy deleted the 03-30-m0_core_types branch March 31, 2026 05:54

somanshreddy added this to the M0: Walking Skeleton milestone Apr 3, 2026

somanshreddy mentioned this pull request May 11, 2026

fix: add billing link to insufficient_credit error hint #139

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

core types + interfaces: error taxonomy, RequestSpec, Formatter, Resolver, Provider (PRINFRA-120)#1

core types + interfaces: error taxonomy, RequestSpec, Formatter, Resolver, Provider (PRINFRA-120)#1
somanshreddy merged 2 commits into
mainfrom
03-30-m0_core_types

somanshreddy commented Mar 30, 2026 •

edited

Loading

Uh oh!

somanshreddy commented Mar 30, 2026 •

edited

Loading

Uh oh!

somanshreddy Mar 30, 2026

Uh oh!

somanshreddy Mar 30, 2026

Uh oh!

somanshreddy Mar 30, 2026

Uh oh!

jrusso1020 Mar 30, 2026

Uh oh!

somanshreddy Mar 31, 2026

Uh oh!

somanshreddy Mar 30, 2026

Uh oh!

linear Bot commented Mar 31, 2026

Scope

Why first

Acceptance Criteria

Uh oh!

somanshreddy commented Mar 31, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

somanshreddy commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

Uh oh!

somanshreddy commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

somanshreddy Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

somanshreddy Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

somanshreddy Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

jrusso1020 Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

somanshreddy Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

somanshreddy Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

linear Bot commented Mar 31, 2026

Scope

Why first

Acceptance Criteria

Uh oh!

somanshreddy commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

somanshreddy commented Mar 30, 2026 •

edited

Loading

somanshreddy commented Mar 30, 2026 •

edited

Loading

somanshreddy commented Mar 31, 2026 •

edited

Loading