mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-05 10:14:30 +00:00
James Russo
ce5e872e51
* feat(cli): vendor initial hyperframes cloud client codegen Generated by experiment-framework/scripts/generate_hyperframes_cli_client.py (see heygen-com/experiment-framework#37896). Sets up the baseline for the sync workflow to diff against on future spec changes. The follow-up PR adds the orchestration layer (zip + upload + poll + download) and the user-facing 'hyperframes cloud render/list/get/delete' commands on top of this generated client. The fallow ignore pattern is necessary because the generated request() method is intentionally a single switch that handles all 5 endpoints in one place; refactoring it here would just be re-introduced on the next codegen run. * chore(cli): regenerate cloud client with mimeType parameter on multipart uploads Adds optional mimeType arg to uploadAsset (and any future multipart endpoints). Without it, FormData sends application/octet-stream which is correct for the documented media surface (png/jpeg/mp4/etc.) but ambiguous for the private-beta zip uploads the cloud render flow uses. Callers that pass `mimeType: "application/zip"` tag the multipart part with the right Content-Type so downstream proxies, WAFs, and any future server-side change that keys off the part MIME (instead of the current magic-byte detection) all see the intended type. Addresses review feedback on heygen-com/experiment-framework#37896. Generated by scripts/generate_hyperframes_cli_client.py with the matching update to the multipart emit path. * feat(cli): add hyperframes cloud render/list/get/delete commands Hand-rolled orchestration layer on top of the auto-generated cloud client (vendored in the previous PR): - cloud render <dir>: zip via createPublishArchive → upload to /v3/assets → submit /v3/hyperframes/renders → poll /v3/hyperframes/renders/{id} every 10s (max 60min) → stream the signed video_url to disk. - cloud render --no-wait: submit and exit with the render_id. - cloud render --asset-id / --url: skip zip+upload and use a pre-uploaded asset or public HTTPS zip. - cloud render --variables / --variables-file: same UX as the local render command; variables are validated against data-composition-variables only when there's a local project. - cloud list / cloud get / cloud delete: thin wrappers around the matching client methods, with cursor-pagination support on list. Auth comes from the existing cli/src/auth/ chain via cloud/auth.ts — no new credential store, no new env var. The cloud client receives a getAuthHeaders() callback that re-resolves credentials on every request, so OAuth refreshes mid-poll are picked up automatically. Also extracts a parent-scoped path lookup in help.ts so 'cloud render --help' surfaces the right examples instead of falling through to the top-level 'render' command's examples. * fix(cli): address 15 code-review findings on cloud commands Correctness fixes - delete: require --no-confirm when stdin isn't a TTY OR --json is passed; previously both silently auto-bypassed the irreversible- delete prompt. Explicit decline now exits 2 (distinct from API/system errors which still exit 1). - render: mutex check now counts the positional dir alongside --asset-id / --url; `cloud render ./foo --asset-id X` now errors instead of silently dropping the dir. - render: docstring updated — only --no-wait short-circuits the poll loop; --callback-url is independent (webhook fires either way). - render: removed dead try/catch around resolveProject (it calls process.exit, never throws). resolveVariablesAndValidateIfLocal also takes the resolved project source instead of re-parsing args. - render: createPublishArchive errors now surface via errorBox instead of bubbling a raw stack trace past citty. - help: loadExamples now only catches ERR_MODULE_NOT_FOUND; real load errors (syntax error, broken import) propagate so a broken cloud/render.ts no longer silently shows the local render command's examples. Also skips the parent-scoped lookup when parentName is the root command ("hyperframes"). - list: fetchAll gained a 50-page safety cap + duplicate-cursor detection so a buggy backend serving the same next_token on a loop can't OOM the CLI. - download: drain await now listens for error / close / abort so a failing write stream (ENOSPC, AbortSignal) rejects promptly instead of hanging forever. Partial files are unlinked on any error so the caller never observes a truncated MP4. content-length is verified against the actual byte count. - poll: default sleep is abort-aware so Ctrl+C feels immediate instead of waiting out the full interval. - pollWithProgress: ANSI carriage-return redraws now gated on process.stdout.isTTY — non-TTY runs (CI, file redirects) emit one line per status transition instead of polluting the log with literal escape codes. Cloud client: 401-retry-with-refresh - createCloudClient now wraps the generated client with a Proxy that catches HyperframesApiError(status=401), force-refreshes the OAuth token via forceRefreshCredentials, and retries the call exactly once. Mirrors AuthClient's onUnauthenticatedRefresh so server-side revocations and clock-skew rejections recover automatically. - auth.ts gained forceRefreshCredentials() and now updates expires_at on the refreshed credential it returns (fixed stale-expiry race). Shared helpers - cloud/errors.ts: reportApiError(stage, err, opts) is the single error-funnel. ERROR_CODE_HINTS now applies to every subverb — fixes hyperframes_render_not_found being unreachable from get/delete and cuts ~70 LOC of duplicated try/catch/instanceof from render/list/ get/delete. - cloud/parsing.ts: parseIntFlag / parseNumericFlag / parseEnumFlag strict-mode parsers reject trailing garbage that Number.parseInt silently accepts. - cloud/ansi.ts: stripAnsi / visibleLength / padEndVisible — covers ESC + 24-bit truecolor (c.accent palette) instead of the previous regex which undercounted overhead and missed truecolor. JSON-output consistency + _meta envelope - Every cloud subverb's --json output now goes through withMeta(...) so it carries the standard _meta envelope documented in cli.mdx. - Single-render outputs use {render: detail} across get, delete, render-no-wait, render-failed, and render-success. list uses {renders: [...], has_more, next_token?}. delete adds deleted: true. Tests - 25 new tests across ansi.test.ts, parsing.test.ts, plus truncation + abort-cleanup tests for download.test.ts. - 589 / 589 total CLI tests pass. * fix(cli): address Vai's review on cloud commands - render: pass mimeType: "application/zip" to uploadAsset so the multipart Content-Type is correct (was application/octet-stream). Server currently magic-byte-detects from file bytes so this is belt-and-suspenders today, but any downstream proxy / WAF / future server change that keys off the part MIME now sees the intended type instead of relying on detection. - render: poll error path now surfaces "Resume with: hyperframes cloud get <renderId>" via reportApiError's new `suggestion` option, matching the PollTimeoutError handler. The server-side render keeps running through a transient 5xx; the user just needs the right command to pick it back up. - list: fetchAll now errorBox-exits on the malformed {has_more: true, next_token: null} shape instead of silently returning a truncated list (matching the duplicate-cursor guard). - download: closeFile now listens for 'error' on the write stream in addition to the end() callback, so a late ENOSPC during flush doesn't leak an unhandled error onto the stream and resolves the finally promptly. - errors: reportApiError accepts an optional `suggestion` that's used as the errorBox third line when no code-specific hint matches — gives callers a place to surface always-actionable recovery context. - docs(cli): document --idempotency-key as the safe-retry mechanism for the upload step. The 401-retry Proxy replays POST requests on a stale token; without an idempotency key, the upload may land twice. A UUID per logical render is the recommended pattern.
100 lines
3.0 KiB
TypeScript
100 lines
3.0 KiB
TypeScript
/**
|
|
* Strict numeric parsers for CLI flags.
|
|
*
|
|
* `Number.parseInt`/`Number.parseFloat` silently truncate trailing
|
|
* garbage ("10abc" → 10), which we don't want for user-facing flags
|
|
* like `--limit`, `--fps`, `--poll-interval`. These wrappers reject
|
|
* anything that isn't a complete numeric literal.
|
|
*/
|
|
|
|
import { errorBox } from "../ui/format.js";
|
|
|
|
const INTEGER_RE = /^-?\d+$/;
|
|
const NUMERIC_RE = /^-?\d+(\.\d+)?$/;
|
|
|
|
export interface IntFlagOptions {
|
|
flag: string;
|
|
min?: number;
|
|
max?: number;
|
|
}
|
|
|
|
/**
|
|
* Parse an integer flag, exit(1) with an errorBox on any non-integer
|
|
* input (including trailing garbage like "10abc" and decimals like
|
|
* "10.5"). Returns `undefined` when `raw === undefined` so callers can
|
|
* supply their own defaults.
|
|
*/
|
|
export function parseIntFlag(raw: string | undefined, opts: IntFlagOptions): number | undefined {
|
|
if (raw === undefined) return undefined;
|
|
if (!INTEGER_RE.test(raw)) {
|
|
errorBox(`Invalid ${opts.flag}`, `Got "${raw}". Must be an integer${rangeSuffix(opts)}.`);
|
|
process.exit(1);
|
|
}
|
|
const n = Number.parseInt(raw, 10);
|
|
enforceRange(opts.flag, raw, n, opts);
|
|
return n;
|
|
}
|
|
|
|
export interface FloatFlagOptions {
|
|
flag: string;
|
|
min?: number;
|
|
max?: number;
|
|
}
|
|
|
|
/**
|
|
* Parse a non-NaN finite numeric flag, exit(1) on any non-numeric
|
|
* input. Accepts integers and decimals.
|
|
*/
|
|
export function parseNumericFlag(
|
|
raw: string | undefined,
|
|
opts: FloatFlagOptions,
|
|
): number | undefined {
|
|
if (raw === undefined) return undefined;
|
|
if (!NUMERIC_RE.test(raw)) {
|
|
errorBox(`Invalid ${opts.flag}`, `Got "${raw}". Must be a number${rangeSuffix(opts)}.`);
|
|
process.exit(1);
|
|
}
|
|
const n = Number.parseFloat(raw);
|
|
if (!Number.isFinite(n)) {
|
|
errorBox(`Invalid ${opts.flag}`, `Got "${raw}". Must be a finite number.`);
|
|
process.exit(1);
|
|
}
|
|
enforceRange(opts.flag, raw, n, opts);
|
|
return n;
|
|
}
|
|
|
|
function enforceRange(
|
|
flag: string,
|
|
raw: string,
|
|
value: number,
|
|
bounds: { min?: number; max?: number },
|
|
): void {
|
|
if (bounds.min !== undefined && value < bounds.min) {
|
|
errorBox(`Invalid ${flag}`, `Got "${raw}". Minimum is ${bounds.min}.`);
|
|
process.exit(1);
|
|
}
|
|
if (bounds.max !== undefined && value > bounds.max) {
|
|
errorBox(`Invalid ${flag}`, `Got "${raw}". Maximum is ${bounds.max}.`);
|
|
process.exit(1);
|
|
}
|
|
}
|
|
|
|
/** Parse an enum-typed flag against a closed set of allowed values. */
|
|
export function parseEnumFlag<T extends string>(
|
|
raw: string | undefined,
|
|
allowed: readonly T[],
|
|
opts: { flag: string },
|
|
): T | undefined {
|
|
if (raw === undefined) return undefined;
|
|
if ((allowed as readonly string[]).includes(raw)) return raw as T;
|
|
errorBox(`Invalid ${opts.flag}`, `Got "${raw}". Must be one of: ${allowed.join(", ")}.`);
|
|
process.exit(1);
|
|
}
|
|
|
|
function rangeSuffix(opts: { min?: number; max?: number }): string {
|
|
if (opts.min !== undefined && opts.max !== undefined) return ` (${opts.min}-${opts.max})`;
|
|
if (opts.min !== undefined) return ` (>= ${opts.min})`;
|
|
if (opts.max !== undefined) return ` (<= ${opts.max})`;
|
|
return "";
|
|
}
|