mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-05 17:30:50 +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.
87 lines
2.8 KiB
TypeScript
87 lines
2.8 KiB
TypeScript
/**
|
|
* `hyperframes cloud get <render_id>` — fetch detail for a single render.
|
|
*
|
|
* Includes the signed `video_url` and `thumbnail_url` when status is
|
|
* `completed`. The signed URLs are short-lived; don't paste them into
|
|
* docs / chat — fetch them on demand.
|
|
*/
|
|
|
|
import { defineCommand } from "citty";
|
|
import { createCloudClient } from "../../cloud/index.js";
|
|
import { reportApiError } from "../../cloud/errors.js";
|
|
import { colorStatus } from "../../cloud/statusColor.js";
|
|
import { withMeta } from "../../utils/updateCheck.js";
|
|
import type { HyperframesRenderDetail } from "../../cloud/index.js";
|
|
import { c } from "../../ui/colors.js";
|
|
|
|
export default defineCommand({
|
|
meta: { name: "get", description: "Fetch detail for one cloud render" },
|
|
args: {
|
|
id: {
|
|
type: "positional",
|
|
required: true,
|
|
description: "Render ID (returned by `cloud render` / `cloud list`)",
|
|
},
|
|
json: {
|
|
type: "boolean",
|
|
description: "Emit machine-readable JSON",
|
|
default: false,
|
|
},
|
|
},
|
|
async run({ args }) {
|
|
const client = await createCloudClient();
|
|
try {
|
|
const detail = await client.getRender({ render_id: args.id });
|
|
if (args.json) {
|
|
console.log(JSON.stringify(withMeta({ render: detail }), null, 2));
|
|
return;
|
|
}
|
|
printHuman(detail);
|
|
} catch (err) {
|
|
reportApiError("Could not fetch render", err, {
|
|
notFound: `No render found with id "${args.id}".`,
|
|
});
|
|
}
|
|
},
|
|
});
|
|
|
|
// fallow-ignore-next-line complexity
|
|
function printHuman(detail: HyperframesRenderDetail): void {
|
|
const rows: [string, string | undefined][] = [
|
|
["Render ID:", c.accent(detail.render_id)],
|
|
["Status: ", colorStatus(detail.status)],
|
|
["Format: ", detail.format],
|
|
["Quality: ", detail.quality ?? undefined],
|
|
["Fps: ", detail.fps?.toString()],
|
|
["Resolution:", detail.resolution ?? undefined],
|
|
["Composition:", detail.composition ?? undefined],
|
|
["Title: ", detail.title ?? undefined],
|
|
["Callback ID:", detail.callback_id ?? undefined],
|
|
[
|
|
"Duration: ",
|
|
detail.duration !== undefined && detail.duration !== null
|
|
? `${detail.duration.toFixed(2)}s`
|
|
: undefined,
|
|
],
|
|
[
|
|
"Created: ",
|
|
detail.created_at !== undefined && detail.created_at !== null
|
|
? new Date(detail.created_at * 1000).toISOString()
|
|
: undefined,
|
|
],
|
|
[
|
|
"Completed:",
|
|
detail.completed_at !== undefined && detail.completed_at !== null
|
|
? new Date(detail.completed_at * 1000).toISOString()
|
|
: undefined,
|
|
],
|
|
["Video URL:", detail.video_url ?? undefined],
|
|
["Thumbnail:", detail.thumbnail_url ?? undefined],
|
|
["Failure: ", detail.failure_message ?? undefined],
|
|
];
|
|
for (const [label, value] of rows) {
|
|
if (value === undefined) continue;
|
|
console.log(`${c.bold(label)} ${value}`);
|
|
}
|
|
}
|