mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-04 07:19:52 +00:00
feat(cli): add hyperframes cloud render/list/get/delete commands (#1110)
* 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.
This commit is contained in:
James Russo
@@ -125,6 +125,7 @@ const subCommands = {
|
||||
snapshot: () => import("./commands/snapshot.js").then((m) => m.default),
|
||||
capture: () => import("./commands/capture.js").then((m) => m.default),
|
||||
lambda: () => import("./commands/lambda.js").then((m) => m.default),
|
||||
cloud: () => import("./commands/cloud.js").then((m) => m.default),
|
||||
auth: () => import("./commands/auth.js").then((m) => m.default),
|
||||
};
|
||||
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { padEndVisible, stripAnsi, visibleLength } from "./ansi.js";
|
||||
|
||||
describe("cloud/ansi", () => {
|
||||
describe("stripAnsi", () => {
|
||||
it("strips basic SGR codes (16-color)", () => {
|
||||
expect(stripAnsi("\x1b[32mok\x1b[39m")).toBe("ok");
|
||||
});
|
||||
|
||||
it("strips bright SGR codes", () => {
|
||||
expect(stripAnsi("\x1b[91merr\x1b[39m")).toBe("err");
|
||||
});
|
||||
|
||||
it("strips 24-bit truecolor sequences (used by c.accent)", () => {
|
||||
expect(stripAnsi("\x1b[38;2;60;230;172maccent\x1b[39m")).toBe("accent");
|
||||
});
|
||||
|
||||
it("strips reset codes", () => {
|
||||
expect(stripAnsi("\x1b[0mreset")).toBe("reset");
|
||||
});
|
||||
|
||||
it("leaves non-ANSI text alone", () => {
|
||||
expect(stripAnsi("plain")).toBe("plain");
|
||||
});
|
||||
|
||||
it("handles nested codes", () => {
|
||||
expect(stripAnsi("\x1b[1m\x1b[32mbold-green\x1b[39m\x1b[22m")).toBe("bold-green");
|
||||
});
|
||||
});
|
||||
|
||||
describe("visibleLength", () => {
|
||||
it("returns the visible-only character count", () => {
|
||||
expect(visibleLength("\x1b[32mok\x1b[39m")).toBe(2);
|
||||
expect(visibleLength("\x1b[38;2;60;230;172maccent\x1b[39m")).toBe(6);
|
||||
});
|
||||
});
|
||||
|
||||
describe("padEndVisible", () => {
|
||||
it("pads to target visible width regardless of ANSI overhead", () => {
|
||||
const padded = padEndVisible("\x1b[32mok\x1b[39m", 6);
|
||||
// visible "ok" is 2 chars; padded to 6 visible chars = "ok " plus the ANSI overhead
|
||||
expect(visibleLength(padded)).toBe(6);
|
||||
});
|
||||
|
||||
it("does not trim when input is already longer than target", () => {
|
||||
expect(padEndVisible("longer", 3)).toBe("longer");
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,32 @@
|
||||
/**
|
||||
* Strip ANSI SGR escape sequences for visible-length column alignment.
|
||||
*
|
||||
* Earlier impl used `/\[\d+m/g` which (a) missed the ESC prefix
|
||||
* (under-counting overhead by 1 per code) and (b) didn't match
|
||||
* `ESC[38;2;…m` 24-bit truecolor sequences used by `c.accent`. This
|
||||
* regex covers the full CSI SGR family.
|
||||
*
|
||||
* Constructed via `new RegExp("\\u001b...")` rather than a `/.../`
|
||||
* literal because oxlint's `no-control-regex` rule flags ESC (0x1B)
|
||||
* even in literal form, and the string-construction path keeps the
|
||||
* intent obvious without needing a per-file disable.
|
||||
*/
|
||||
|
||||
// CSI SGR: ESC `[` { params with digits + semicolons } `m`.
|
||||
// oxlint-disable-next-line no-control-regex
|
||||
const ANSI_SGR_RE = new RegExp("\\u001b\\[[\\d;]*m", "g");
|
||||
|
||||
export function stripAnsi(s: string): string {
|
||||
return s.replace(ANSI_SGR_RE, "");
|
||||
}
|
||||
|
||||
/** Length of `s` after ANSI SGR codes are stripped. */
|
||||
export function visibleLength(s: string): number {
|
||||
return stripAnsi(s).length;
|
||||
}
|
||||
|
||||
/** Like `String.prototype.padEnd` but counts visible chars only. */
|
||||
export function padEndVisible(s: string, target: number): string {
|
||||
const overhead = s.length - visibleLength(s);
|
||||
return s.padEnd(target + overhead);
|
||||
}
|
||||
@@ -0,0 +1,77 @@
|
||||
/**
|
||||
* Bridge between the existing credential resolution chain (auth/) and the
|
||||
* generated cloud client (`_gen/client.ts`). Hands the client a
|
||||
* `getAuthHeaders()` callback that resolves credentials fresh on every
|
||||
* request — so OAuth refreshes that happen between calls (e.g. during a
|
||||
* long poll loop) are picked up automatically the next time the callback
|
||||
* fires.
|
||||
*
|
||||
* Why this lives in `cloud/` instead of extending `auth/client.ts`: the
|
||||
* auth client is scoped to `/v3/users/me` (the credential-verification
|
||||
* endpoint) and we want the cloud client to be a standalone surface. The
|
||||
* shared primitives (`buildAuthHeaders`, `resolveCredential`) are pulled
|
||||
* in here without coupling the two clients.
|
||||
*/
|
||||
|
||||
import { apiBaseUrl, buildAuthHeaders } from "../auth/client.js";
|
||||
import { refreshTokens } from "../auth/oauth.js";
|
||||
import { resolveCredential, type ResolvedCredential } from "../auth/resolver.js";
|
||||
|
||||
/**
|
||||
* Build the cloud client's `getAuthHeaders` callback. Each invocation
|
||||
* re-resolves credentials so refreshes that happened since the last call
|
||||
* are picked up. When the OAuth access token is past expiry AND a
|
||||
* refresh_token is present, the token endpoint is hit before headers
|
||||
* are returned.
|
||||
*/
|
||||
export async function resolveCloudAuthHeaders(): Promise<Record<string, string>> {
|
||||
let credential = await resolveCredential();
|
||||
credential = await refreshIfNeeded(credential);
|
||||
return buildAuthHeaders(credential);
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the base URL the cloud client should hit. Honors
|
||||
* `HEYGEN_API_URL` (matches `auth/client.ts:apiBaseUrl`).
|
||||
*/
|
||||
export function resolveCloudBaseUrl(): string {
|
||||
return apiBaseUrl();
|
||||
}
|
||||
|
||||
// fallow-ignore-next-line complexity
|
||||
async function refreshIfNeeded(credential: ResolvedCredential): Promise<ResolvedCredential> {
|
||||
if (credential.type !== "oauth") return credential;
|
||||
if (!credential.refreshable || !credential.refresh_token) return credential;
|
||||
const fresh = await refreshTokens(credential.refresh_token);
|
||||
return {
|
||||
...credential,
|
||||
access_token: fresh.access_token,
|
||||
expires_at: parseDateOrUndef(fresh.expires_at),
|
||||
refreshable: false,
|
||||
...(fresh.refresh_token ? { refresh_token: fresh.refresh_token } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
function parseDateOrUndef(value: string | undefined): Date | undefined {
|
||||
if (!value) return undefined;
|
||||
const d = new Date(value);
|
||||
return Number.isNaN(d.getTime()) ? undefined : d;
|
||||
}
|
||||
|
||||
/**
|
||||
* Force-refresh the OAuth access token regardless of locally-known
|
||||
* expiry. Used by `createCloudClient`'s 401-retry path when the server
|
||||
* rejects a token that the local resolver thought was still valid (e.g.
|
||||
* server-side revocation, clock skew, IdP rotation). No-op for API-key
|
||||
* credentials.
|
||||
*
|
||||
* Throws if the credential can't be refreshed (no refresh_token, or the
|
||||
* IdP refresh call itself fails). Callers should let the throw surface
|
||||
* — the original 401 is what the user needs to see, not a confusing
|
||||
* "refresh failed" message.
|
||||
*/
|
||||
export async function forceRefreshCredentials(): Promise<void> {
|
||||
const credential = await resolveCredential();
|
||||
if (credential.type !== "oauth" || !credential.refresh_token) return;
|
||||
await refreshTokens(credential.refresh_token);
|
||||
}
|
||||
@@ -0,0 +1,112 @@
|
||||
import { mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { afterEach, beforeEach, describe, expect, it } from "vitest";
|
||||
import { downloadToFile } from "./download.js";
|
||||
|
||||
function makeBytesFetch(bytes: Uint8Array, headers: Record<string, string> = {}): typeof fetch {
|
||||
return (async () =>
|
||||
new Response(new Blob([bytes as unknown as BlobPart]), {
|
||||
status: 200,
|
||||
headers: {
|
||||
"content-type": "application/octet-stream",
|
||||
...headers,
|
||||
},
|
||||
})) as unknown as typeof fetch;
|
||||
}
|
||||
|
||||
function makeErrorFetch(status: number, statusText = "Not Found"): typeof fetch {
|
||||
return (async () => new Response("nope", { status, statusText })) as unknown as typeof fetch;
|
||||
}
|
||||
|
||||
describe("cloud/download", () => {
|
||||
let dir: string;
|
||||
beforeEach(() => {
|
||||
dir = mkdtempSync(join(tmpdir(), "hf-cloud-download-"));
|
||||
});
|
||||
afterEach(() => {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it("streams the response body to disk and returns the byte count", async () => {
|
||||
const payload = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
|
||||
const dest = join(dir, "out.bin");
|
||||
const result = await downloadToFile("https://example/x", dest, {
|
||||
fetchImpl: makeBytesFetch(payload, { "content-length": String(payload.length) }),
|
||||
});
|
||||
expect(result.path).toBe(dest);
|
||||
expect(result.bytes).toBe(payload.length);
|
||||
const written = readFileSync(dest);
|
||||
expect(written.equals(Buffer.from(payload))).toBe(true);
|
||||
expect(statSync(dest).size).toBe(payload.length);
|
||||
});
|
||||
|
||||
it("creates the destination's parent directory if missing", async () => {
|
||||
const payload = new Uint8Array([42]);
|
||||
const dest = join(dir, "nested", "subdir", "file.mp4");
|
||||
const result = await downloadToFile("https://example/x", dest, {
|
||||
fetchImpl: makeBytesFetch(payload),
|
||||
});
|
||||
expect(result.bytes).toBe(1);
|
||||
expect(readFileSync(dest).at(0)).toBe(42);
|
||||
});
|
||||
|
||||
it("reports progress with bytes downloaded and total when content-length is set", async () => {
|
||||
const payload = new Uint8Array(64);
|
||||
const dest = join(dir, "progress.bin");
|
||||
const calls: { bytes: number; total: number | undefined }[] = [];
|
||||
await downloadToFile("https://example/x", dest, {
|
||||
fetchImpl: makeBytesFetch(payload, { "content-length": "64" }),
|
||||
onProgress: (bytes, total) => calls.push({ bytes, total }),
|
||||
});
|
||||
expect(calls.length).toBeGreaterThanOrEqual(1);
|
||||
const last = calls.at(-1)!;
|
||||
expect(last.bytes).toBe(64);
|
||||
expect(last.total).toBe(64);
|
||||
});
|
||||
|
||||
it("throws on non-2xx responses", async () => {
|
||||
const dest = join(dir, "missing.bin");
|
||||
await expect(
|
||||
downloadToFile("https://example/x", dest, {
|
||||
fetchImpl: makeErrorFetch(404),
|
||||
}),
|
||||
).rejects.toThrow(/HTTP 404/);
|
||||
});
|
||||
|
||||
it("rejects truncated downloads when bytes received < content-length", async () => {
|
||||
// Returns 10 bytes but declares content-length: 20.
|
||||
const dest = join(dir, "truncated.bin");
|
||||
const lyingFetch: typeof fetch = (async () =>
|
||||
new Response(new Blob([new Uint8Array(10) as unknown as BlobPart]), {
|
||||
status: 200,
|
||||
headers: { "content-length": "20" },
|
||||
})) as unknown as typeof fetch;
|
||||
await expect(
|
||||
downloadToFile("https://example/x", dest, { fetchImpl: lyingFetch }),
|
||||
).rejects.toThrow(/Truncated download/);
|
||||
// Partial file must be cleaned up.
|
||||
expect(() => statSync(dest)).toThrow();
|
||||
});
|
||||
|
||||
it("deletes the partial file when the abort signal fires mid-stream", async () => {
|
||||
const dest = join(dir, "aborted.bin");
|
||||
// 1 MB payload should give the abort time to land mid-stream.
|
||||
const payload = new Uint8Array(1024 * 1024);
|
||||
const controller = new AbortController();
|
||||
const fetchImpl: typeof fetch = (async () =>
|
||||
new Response(new Blob([payload as unknown as BlobPart]), {
|
||||
status: 200,
|
||||
headers: { "content-length": String(payload.length) },
|
||||
})) as unknown as typeof fetch;
|
||||
// Abort almost immediately.
|
||||
queueMicrotask(() => controller.abort(new Error("user cancelled")));
|
||||
await expect(
|
||||
downloadToFile("https://example/x", dest, {
|
||||
fetchImpl,
|
||||
signal: controller.signal,
|
||||
}),
|
||||
).rejects.toThrow();
|
||||
expect(() => statSync(dest)).toThrow();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,151 @@
|
||||
/**
|
||||
* Stream a presigned `video_url` (or any HTTPS URL) into a local file.
|
||||
*
|
||||
* The presigned URLs returned by `GET /v3/hyperframes/renders/{id}` are
|
||||
* S3 URLs scoped per-request — they don't take any HeyGen auth header.
|
||||
* That's why this lives separate from the cloud client: the client
|
||||
* threads auth headers, the download path explicitly does NOT.
|
||||
*
|
||||
* Failure behavior is "all or nothing": on any error we (1) listen for
|
||||
* stream errors / aborts so awaits resolve promptly instead of hanging,
|
||||
* (2) verify the final byte count matches `content-length` when the
|
||||
* server supplied one, and (3) `unlinkSync` the partial output so a
|
||||
* subsequent retry doesn't pick up a corrupted file.
|
||||
*/
|
||||
|
||||
import { createWriteStream, mkdirSync, unlinkSync } from "node:fs";
|
||||
import { dirname } from "node:path";
|
||||
|
||||
export interface DownloadOptions {
|
||||
signal?: AbortSignal;
|
||||
/** Inject fetch (used by tests). */
|
||||
fetchImpl?: typeof fetch;
|
||||
/** Called with (bytes downloaded, total or undefined). */
|
||||
onProgress?: (bytes: number, total: number | undefined) => void;
|
||||
}
|
||||
|
||||
export interface DownloadResult {
|
||||
path: string;
|
||||
bytes: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Stream `url` into `destPath`. Creates the parent directory if needed,
|
||||
* truncates any existing file at the destination, and deletes the
|
||||
* partial output on any error so the caller never observes a corrupt
|
||||
* file at the returned path.
|
||||
*/
|
||||
// fallow-ignore-next-line complexity
|
||||
export async function downloadToFile(
|
||||
url: string,
|
||||
destPath: string,
|
||||
options: DownloadOptions = {},
|
||||
): Promise<DownloadResult> {
|
||||
const fetchImpl = options.fetchImpl ?? fetch;
|
||||
const res = await fetchImpl(url, { signal: options.signal });
|
||||
if (!res.ok) {
|
||||
throw new Error(`Failed to download ${url}: HTTP ${res.status} ${res.statusText}`);
|
||||
}
|
||||
if (!res.body) {
|
||||
throw new Error(`Failed to download ${url}: empty response body`);
|
||||
}
|
||||
|
||||
mkdirSync(dirname(destPath), { recursive: true });
|
||||
|
||||
const totalHeader = res.headers.get("content-length");
|
||||
const total = totalHeader ? Number.parseInt(totalHeader, 10) : undefined;
|
||||
const totalOpt = total !== undefined && Number.isFinite(total) ? total : undefined;
|
||||
|
||||
const file = createWriteStream(destPath);
|
||||
let bytes = 0;
|
||||
let errored = false;
|
||||
try {
|
||||
for await (const chunk of res.body as unknown as AsyncIterable<Uint8Array>) {
|
||||
if (options.signal?.aborted) {
|
||||
throw options.signal.reason instanceof Error
|
||||
? options.signal.reason
|
||||
: new Error("Download aborted");
|
||||
}
|
||||
bytes += chunk.byteLength;
|
||||
options.onProgress?.(bytes, totalOpt);
|
||||
if (!file.write(chunk)) {
|
||||
await waitForDrain(file, options.signal);
|
||||
}
|
||||
}
|
||||
if (totalOpt !== undefined && bytes !== totalOpt) {
|
||||
throw new Error(
|
||||
`Truncated download: got ${bytes} bytes, expected ${totalOpt} (content-length). ` +
|
||||
`The presigned URL may have expired mid-transfer — refetch via \`hyperframes cloud get\`.`,
|
||||
);
|
||||
}
|
||||
} catch (err) {
|
||||
errored = true;
|
||||
throw err;
|
||||
} finally {
|
||||
await closeFile(file);
|
||||
if (errored) {
|
||||
// Don't let a partial file pose as the final artifact. Best-
|
||||
// effort unlink — if it fails (already gone, permission), we
|
||||
// re-throw the original error.
|
||||
try {
|
||||
unlinkSync(destPath);
|
||||
} catch {
|
||||
/* swallow */
|
||||
}
|
||||
}
|
||||
}
|
||||
return { path: destPath, bytes };
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve when the write stream emits `drain`, or reject on `error` /
|
||||
* `close` / signal abort — avoids the hang from awaiting a one-shot
|
||||
* `drain` event that never fires because the stream tore down first.
|
||||
*/
|
||||
function waitForDrain(file: NodeJS.WritableStream, signal?: AbortSignal): Promise<void> {
|
||||
return new Promise<void>((resolve, reject) => {
|
||||
const cleanup = () => {
|
||||
file.off("drain", onDrain);
|
||||
file.off("error", onError);
|
||||
file.off("close", onClose);
|
||||
signal?.removeEventListener("abort", onAbort);
|
||||
};
|
||||
const onDrain = (): void => {
|
||||
cleanup();
|
||||
resolve();
|
||||
};
|
||||
const onError = (err: Error): void => {
|
||||
cleanup();
|
||||
reject(err);
|
||||
};
|
||||
const onClose = (): void => {
|
||||
cleanup();
|
||||
reject(new Error("write stream closed before drain"));
|
||||
};
|
||||
const onAbort = (): void => {
|
||||
cleanup();
|
||||
const reason = signal?.reason;
|
||||
reject(reason instanceof Error ? reason : new Error("Download aborted"));
|
||||
};
|
||||
file.once("drain", onDrain);
|
||||
file.once("error", onError);
|
||||
file.once("close", onClose);
|
||||
signal?.addEventListener("abort", onAbort, { once: true });
|
||||
});
|
||||
}
|
||||
|
||||
function closeFile(file: NodeJS.WritableStream): Promise<void> {
|
||||
return new Promise<void>((resolve) => {
|
||||
// Best-effort cleanup: any underlying failure has already been
|
||||
// surfaced as the original throw from the for-await loop. We
|
||||
// listen for `error` so a failing close (bad fd, late ENOSPC on
|
||||
// flush) doesn't leak an unhandled 'error' onto the stream, and
|
||||
// resolve either way so the finally block proceeds to unlinkSync.
|
||||
const done = (): void => {
|
||||
file.off("error", done);
|
||||
resolve();
|
||||
};
|
||||
file.once("error", done);
|
||||
file.end(() => done());
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,91 @@
|
||||
/**
|
||||
* Shared API-error reporter for the cloud subverbs.
|
||||
*
|
||||
* Centralizes the three-branch `instanceof HyperframesApiError` → `Error`
|
||||
* → `String` cascade so the curated `ERROR_CODE_HINTS` table is applied
|
||||
* uniformly across `render`/`list`/`get`/`delete`. Without this, each
|
||||
* subverb had to remember to consult the hint table (and most didn't,
|
||||
* which is why review finding 10 was that `hyperframes_render_not_found`
|
||||
* was unreachable from get/delete).
|
||||
*/
|
||||
|
||||
import { errorBox } from "../ui/format.js";
|
||||
import { HyperframesApiError } from "./_gen/client.js";
|
||||
|
||||
/**
|
||||
* Hints surfaced when a HyperframesApiError carries a known machine-
|
||||
* readable code. Keep entries actionable; if there's nothing useful to
|
||||
* say, leave the code out and let the message stand on its own.
|
||||
*/
|
||||
const ERROR_CODE_HINTS: Record<string, string> = {
|
||||
hyperframes_project_invalid:
|
||||
"The uploaded zip didn't validate. Confirm it contains index.html at the root (or matches --composition), and that all referenced assets are present.",
|
||||
hyperframes_project_too_large:
|
||||
"The zip exceeded the 32 MB limit. Trim large media (or pre-host them and reference by URL), then try again.",
|
||||
hyperframes_render_not_found:
|
||||
"The render_id no longer exists — either soft-deleted or never created.",
|
||||
invalid_parameter:
|
||||
"Check the listed parameter against `hyperframes cloud render --help` for the accepted values.",
|
||||
authentication_failed:
|
||||
"Run `hyperframes auth status` to confirm your credential; `hyperframes auth login` to re-auth.",
|
||||
rate_limit_exceeded: "Retry after the duration in the Retry-After header.",
|
||||
};
|
||||
|
||||
/**
|
||||
* Print an errorBox and `process.exit(1)` for any unknown error from
|
||||
* the cloud subverbs. The `stage` is the human-readable name of the
|
||||
* step that failed (e.g. "Upload failed", "Submit failed", "Could not
|
||||
* list cloud renders"). Returns `never` so call sites can `throw` from
|
||||
* the catch block without a separate exit.
|
||||
*
|
||||
* Options:
|
||||
* - `notFound`: short-circuit on a 404 with this friendly message
|
||||
* (the render-id, asset-id, etc. that wasn't found).
|
||||
* - `extraHints`: per-code overrides merged on top of
|
||||
* `ERROR_CODE_HINTS`.
|
||||
* - `suggestion`: a fallback line shown when no code-specific hint
|
||||
* matches. Use this for caller-context that's always actionable
|
||||
* (e.g. "Resume with: hyperframes cloud get hfr_X" on poll
|
||||
* errors) so the user can recover without having to remember the
|
||||
* render_id.
|
||||
*/
|
||||
// fallow-ignore-next-line complexity
|
||||
export function reportApiError(
|
||||
stage: string,
|
||||
err: unknown,
|
||||
options: {
|
||||
notFound?: string;
|
||||
extraHints?: Record<string, string>;
|
||||
suggestion?: string;
|
||||
} = {},
|
||||
): never {
|
||||
const hints = { ...ERROR_CODE_HINTS, ...options.extraHints };
|
||||
if (err instanceof HyperframesApiError) {
|
||||
if (err.status === 404 && options.notFound) {
|
||||
errorBox("Not found", options.notFound);
|
||||
process.exit(1);
|
||||
}
|
||||
const hint = err.code ? hints[err.code] : undefined;
|
||||
const title = `${stage} (HTTP ${err.status})`;
|
||||
// Priority: code-specific hint > caller suggestion > bare code
|
||||
// label > no third line. Code-specific hints win because they
|
||||
// address the specific failure mode; the caller suggestion is a
|
||||
// generic-context fallback.
|
||||
if (hint) {
|
||||
errorBox(title, err.message, hint);
|
||||
} else if (options.suggestion) {
|
||||
errorBox(title, err.message, options.suggestion);
|
||||
} else if (err.code) {
|
||||
errorBox(title, err.message, `code: ${err.code}`);
|
||||
} else {
|
||||
errorBox(title, err.message);
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
if (err instanceof Error) {
|
||||
errorBox(stage, err.message, options.suggestion);
|
||||
process.exit(1);
|
||||
}
|
||||
errorBox(stage, String(err), options.suggestion);
|
||||
process.exit(1);
|
||||
}
|
||||
@@ -0,0 +1,68 @@
|
||||
/**
|
||||
* Internal surface of the `cloud` module — only the symbols the `cloud`
|
||||
* commands consume today. Don't add re-exports speculatively; SDK
|
||||
* consumers can import directly from `_gen/client.js` or `_gen/types.js`
|
||||
* if they need the broader generated surface.
|
||||
*/
|
||||
|
||||
export { PollTimeoutError, pollUntilTerminal } from "./poll.js";
|
||||
export { DEFAULT_MAX_WAIT_MS, DEFAULT_POLL_INTERVAL_MS } from "./poll.js";
|
||||
export { downloadToFile } from "./download.js";
|
||||
|
||||
export type { HyperframesCloudClient } from "./_gen/client.js";
|
||||
export type { CreateHyperframesRenderRequest, HyperframesRenderDetail } from "./_gen/types.js";
|
||||
|
||||
import { HyperframesApiError, HyperframesCloudClient } from "./_gen/client.js";
|
||||
import { forceRefreshCredentials, resolveCloudAuthHeaders, resolveCloudBaseUrl } from "./auth.js";
|
||||
|
||||
/**
|
||||
* Convenience factory that wires the generated client to the standard
|
||||
* credential resolver and adds a 401-retry-with-refresh decorator.
|
||||
*
|
||||
* The decorator catches `HyperframesApiError(status=401)` thrown from
|
||||
* any method on the client, force-refreshes the OAuth token, and
|
||||
* retries the call exactly once. This mirrors `auth/client.ts`'s
|
||||
* `onUnauthenticatedRefresh` behavior so server-side revocations or
|
||||
* clock-skew rejections don't fail the cloud command outright when a
|
||||
* refresh would have fixed them.
|
||||
*/
|
||||
export async function createCloudClient(): Promise<HyperframesCloudClient> {
|
||||
const client = new HyperframesCloudClient({
|
||||
baseUrl: resolveCloudBaseUrl(),
|
||||
getAuthHeaders: resolveCloudAuthHeaders,
|
||||
});
|
||||
return wrapWith401Retry(client);
|
||||
}
|
||||
|
||||
function wrapWith401Retry(client: HyperframesCloudClient): HyperframesCloudClient {
|
||||
return new Proxy(client, {
|
||||
get(target, prop, receiver) {
|
||||
const value = Reflect.get(target, prop, receiver);
|
||||
if (typeof value !== "function") return value;
|
||||
// Bind so internal `this`-references in the generated client
|
||||
// resolve back to the original instance, not the Proxy.
|
||||
const original = value.bind(target) as (...args: unknown[]) => Promise<unknown>;
|
||||
// Only wrap the public endpoint methods (return Promises). Don't
|
||||
// gate on method name — the generated client has stable shape,
|
||||
// and a future endpoint would otherwise be missed.
|
||||
// fallow-ignore-next-line complexity
|
||||
return async (...args: unknown[]): Promise<unknown> => {
|
||||
try {
|
||||
return await original(...args);
|
||||
} catch (err) {
|
||||
if (err instanceof HyperframesApiError && err.status === 401) {
|
||||
// Best-effort refresh; if it fails, surface the original
|
||||
// 401 not the refresh error.
|
||||
try {
|
||||
await forceRefreshCredentials();
|
||||
} catch {
|
||||
throw err;
|
||||
}
|
||||
return await original(...args);
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
};
|
||||
},
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,93 @@
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { parseEnumFlag, parseIntFlag, parseNumericFlag } from "./parsing.js";
|
||||
|
||||
describe("cloud/parsing", () => {
|
||||
// process.exit has signature `(code?) => never` which doesn't unify
|
||||
// with vi.spyOn's mock-function inference; cast through `unknown` so
|
||||
// the test compiles. The spy itself still records calls correctly.
|
||||
let exitSpy: { mockRestore: () => void } & { mock: { calls: unknown[][] } };
|
||||
let errorSpy: { mockRestore: () => void };
|
||||
|
||||
beforeEach(() => {
|
||||
exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
|
||||
throw new Error("process.exit called");
|
||||
}) as unknown as (code?: string | number | null) => never) as unknown as typeof exitSpy;
|
||||
errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
exitSpy.mockRestore();
|
||||
errorSpy.mockRestore();
|
||||
});
|
||||
|
||||
describe("parseIntFlag", () => {
|
||||
it("returns undefined when raw is undefined", () => {
|
||||
expect(parseIntFlag(undefined, { flag: "--x" })).toBeUndefined();
|
||||
});
|
||||
|
||||
it("parses a clean integer", () => {
|
||||
expect(parseIntFlag("42", { flag: "--x" })).toBe(42);
|
||||
});
|
||||
|
||||
it("rejects trailing garbage that Number.parseInt would silently accept", () => {
|
||||
expect(() => parseIntFlag("10abc", { flag: "--x" })).toThrow("process.exit called");
|
||||
expect(exitSpy).toHaveBeenCalledWith(1);
|
||||
});
|
||||
|
||||
it("rejects decimals", () => {
|
||||
expect(() => parseIntFlag("10.5", { flag: "--x" })).toThrow("process.exit called");
|
||||
});
|
||||
|
||||
it("enforces min", () => {
|
||||
expect(() => parseIntFlag("0", { flag: "--x", min: 1 })).toThrow("process.exit called");
|
||||
});
|
||||
|
||||
it("enforces max", () => {
|
||||
expect(() => parseIntFlag("101", { flag: "--x", max: 100 })).toThrow("process.exit called");
|
||||
});
|
||||
|
||||
it("accepts negative integers when no min is set", () => {
|
||||
expect(parseIntFlag("-5", { flag: "--x" })).toBe(-5);
|
||||
});
|
||||
});
|
||||
|
||||
describe("parseNumericFlag", () => {
|
||||
it("parses decimals", () => {
|
||||
expect(parseNumericFlag("1.5", { flag: "--x" })).toBe(1.5);
|
||||
});
|
||||
|
||||
it("parses integers", () => {
|
||||
expect(parseNumericFlag("10", { flag: "--x" })).toBe(10);
|
||||
});
|
||||
|
||||
it("rejects trailing garbage that Number.parseFloat would silently accept", () => {
|
||||
expect(() => parseNumericFlag("10seconds", { flag: "--x" })).toThrow("process.exit called");
|
||||
});
|
||||
|
||||
it("rejects NaN", () => {
|
||||
expect(() => parseNumericFlag("not-a-number", { flag: "--x" })).toThrow(
|
||||
"process.exit called",
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("parseEnumFlag", () => {
|
||||
it("accepts a known value", () => {
|
||||
expect(parseEnumFlag("draft", ["draft", "standard", "high"], { flag: "--quality" })).toBe(
|
||||
"draft",
|
||||
);
|
||||
});
|
||||
|
||||
it("rejects an unknown value", () => {
|
||||
expect(() =>
|
||||
parseEnumFlag("ultra", ["draft", "standard", "high"], { flag: "--quality" }),
|
||||
).toThrow("process.exit called");
|
||||
});
|
||||
|
||||
it("returns undefined when raw is undefined", () => {
|
||||
expect(
|
||||
parseEnumFlag(undefined, ["draft", "standard", "high"], { flag: "--quality" }),
|
||||
).toBeUndefined();
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,99 @@
|
||||
/**
|
||||
* 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 "";
|
||||
}
|
||||
@@ -0,0 +1,125 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import {
|
||||
DEFAULT_MAX_WAIT_MS,
|
||||
DEFAULT_POLL_INTERVAL_MS,
|
||||
PollTimeoutError,
|
||||
isTerminal,
|
||||
pollUntilTerminal,
|
||||
} from "./poll.js";
|
||||
import type { HyperframesCloudClient } from "./_gen/client.js";
|
||||
import type { HyperframesRenderDetail } from "./_gen/types.js";
|
||||
|
||||
function makeDetail(overrides: Partial<HyperframesRenderDetail>): HyperframesRenderDetail {
|
||||
return {
|
||||
render_id: "hfr_test",
|
||||
status: "queued",
|
||||
format: "mp4",
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
/** Build a stub client that returns the supplied details in order. */
|
||||
function stubClient(details: HyperframesRenderDetail[]): HyperframesCloudClient {
|
||||
const stack = [...details];
|
||||
return {
|
||||
async getRender() {
|
||||
const next = stack.shift();
|
||||
if (!next) throw new Error("ran out of stubbed responses");
|
||||
return next;
|
||||
},
|
||||
} as unknown as HyperframesCloudClient;
|
||||
}
|
||||
|
||||
describe("cloud/poll", () => {
|
||||
describe("isTerminal", () => {
|
||||
it("treats completed/failed as terminal", () => {
|
||||
expect(isTerminal("completed")).toBe(true);
|
||||
expect(isTerminal("failed")).toBe(true);
|
||||
});
|
||||
it("treats queued/rendering as non-terminal", () => {
|
||||
expect(isTerminal("queued")).toBe(false);
|
||||
expect(isTerminal("rendering")).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("defaults", () => {
|
||||
it("matches the documented 10s / 60min defaults", () => {
|
||||
expect(DEFAULT_POLL_INTERVAL_MS).toBe(10_000);
|
||||
expect(DEFAULT_MAX_WAIT_MS).toBe(60 * 60 * 1000);
|
||||
});
|
||||
});
|
||||
|
||||
describe("pollUntilTerminal", () => {
|
||||
it("returns immediately when the first poll is terminal", async () => {
|
||||
const client = stubClient([makeDetail({ status: "completed" })]);
|
||||
const sleep = vi.fn(async () => {});
|
||||
const result = await pollUntilTerminal(client, "hfr_test", { sleep });
|
||||
expect(result.status).toBe("completed");
|
||||
expect(sleep).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("sleeps between non-terminal polls and returns on the terminal one", async () => {
|
||||
const client = stubClient([
|
||||
makeDetail({ status: "queued" }),
|
||||
makeDetail({ status: "rendering" }),
|
||||
makeDetail({ status: "completed" }),
|
||||
]);
|
||||
const sleep = vi.fn(async () => {});
|
||||
const now = (() => {
|
||||
let t = 0;
|
||||
return () => {
|
||||
t += 1000;
|
||||
return t;
|
||||
};
|
||||
})();
|
||||
const ticks: string[] = [];
|
||||
const result = await pollUntilTerminal(client, "hfr_test", {
|
||||
sleep,
|
||||
now,
|
||||
intervalMs: 5_000,
|
||||
onTick: (d) => ticks.push(d.status),
|
||||
});
|
||||
expect(result.status).toBe("completed");
|
||||
expect(ticks).toEqual(["queued", "rendering", "completed"]);
|
||||
// Two sleeps: one after queued, one after rendering. None after the
|
||||
// terminal completed response.
|
||||
expect(sleep).toHaveBeenCalledTimes(2);
|
||||
expect(sleep).toHaveBeenCalledWith(5_000);
|
||||
});
|
||||
|
||||
it("throws PollTimeoutError when elapsed exceeds maxWaitMs", async () => {
|
||||
const client = stubClient([
|
||||
makeDetail({ status: "queued" }),
|
||||
makeDetail({ status: "rendering" }),
|
||||
makeDetail({ status: "rendering" }),
|
||||
]);
|
||||
const sleep = vi.fn(async () => {});
|
||||
// Each `now()` returns +500ms; total elapses past 1s on the second
|
||||
// call, so maxWaitMs=1 triggers immediately.
|
||||
const now = (() => {
|
||||
let t = 0;
|
||||
return () => {
|
||||
t += 1000;
|
||||
return t;
|
||||
};
|
||||
})();
|
||||
await expect(
|
||||
pollUntilTerminal(client, "hfr_test", {
|
||||
sleep,
|
||||
now,
|
||||
intervalMs: 5_000,
|
||||
maxWaitMs: 1,
|
||||
}),
|
||||
).rejects.toBeInstanceOf(PollTimeoutError);
|
||||
});
|
||||
|
||||
it("aborts when the AbortSignal is fired", async () => {
|
||||
const client = stubClient([makeDetail({ status: "queued" })]);
|
||||
const controller = new AbortController();
|
||||
controller.abort(new Error("user cancelled"));
|
||||
await expect(
|
||||
pollUntilTerminal(client, "hfr_test", { signal: controller.signal }),
|
||||
).rejects.toThrow("user cancelled");
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,108 @@
|
||||
/**
|
||||
* Poll a HyperFrames render until it reaches a terminal state.
|
||||
*
|
||||
* Defaults: 10s interval, 60min cap — confirmed with the API owner. The
|
||||
* `start_to_close` timeout on the underlying Temporal workflow is the
|
||||
* same order of magnitude, so polling longer would only hide a stuck
|
||||
* workflow rather than recover from one.
|
||||
*
|
||||
* Spinner output is silenced when stdout isn't a TTY (CI, piped output)
|
||||
* so the JSON-emitting modes upstream don't get garbled.
|
||||
*/
|
||||
|
||||
import type { HyperframesCloudClient } from "./_gen/client.js";
|
||||
import type { HyperframesRenderDetail, HyperframesRenderStatus } from "./_gen/types.js";
|
||||
|
||||
export interface PollOptions {
|
||||
intervalMs?: number;
|
||||
maxWaitMs?: number;
|
||||
/** Called once per tick with the latest render state. */
|
||||
onTick?: (detail: HyperframesRenderDetail, elapsedMs: number) => void;
|
||||
/** Inject a clock for tests. */
|
||||
now?: () => number;
|
||||
/** Inject a sleep for tests. */
|
||||
sleep?: (ms: number) => Promise<void>;
|
||||
signal?: AbortSignal;
|
||||
}
|
||||
|
||||
export const DEFAULT_POLL_INTERVAL_MS = 10_000;
|
||||
export const DEFAULT_MAX_WAIT_MS = 60 * 60 * 1000;
|
||||
|
||||
const TERMINAL_STATUSES: ReadonlySet<HyperframesRenderStatus> = new Set(["completed", "failed"]);
|
||||
|
||||
export class PollTimeoutError extends Error {
|
||||
readonly lastDetail: HyperframesRenderDetail;
|
||||
constructor(lastDetail: HyperframesRenderDetail, elapsedMs: number) {
|
||||
super(
|
||||
`Render ${lastDetail.render_id} did not reach a terminal state within ${Math.round(elapsedMs / 1000)}s`,
|
||||
);
|
||||
this.name = "PollTimeoutError";
|
||||
this.lastDetail = lastDetail;
|
||||
}
|
||||
}
|
||||
|
||||
export function isTerminal(status: HyperframesRenderStatus): boolean {
|
||||
return TERMINAL_STATUSES.has(status);
|
||||
}
|
||||
|
||||
/**
|
||||
* Poll `GET /v3/hyperframes/renders/{id}` until status is `completed` or
|
||||
* `failed`, or `maxWaitMs` elapses (in which case throws
|
||||
* {@link PollTimeoutError}). Errors from the underlying request bubble
|
||||
* up immediately — they are not retried, because every error class the
|
||||
* API can return at this stage (404, 401, 5xx) is unlikely to recover
|
||||
* on a retry inside the poll window.
|
||||
*/
|
||||
export async function pollUntilTerminal(
|
||||
client: HyperframesCloudClient,
|
||||
renderId: string,
|
||||
options: PollOptions = {},
|
||||
): Promise<HyperframesRenderDetail> {
|
||||
const intervalMs = options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
|
||||
const maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
|
||||
const now = options.now ?? (() => Date.now());
|
||||
// Default sleep honors the abort signal so Ctrl+C feels immediate
|
||||
// instead of waiting out the full interval. Tests inject a no-op
|
||||
// sleep that ignores the signal — that's fine, they don't abort.
|
||||
const sleep = options.sleep ?? defaultAbortableSleep(options.signal);
|
||||
|
||||
const started = now();
|
||||
|
||||
while (true) {
|
||||
if (options.signal?.aborted) {
|
||||
throw signalAbortError(options.signal);
|
||||
}
|
||||
const detail = await client.getRender({ render_id: renderId, signal: options.signal });
|
||||
const elapsed = now() - started;
|
||||
options.onTick?.(detail, elapsed);
|
||||
|
||||
if (isTerminal(detail.status)) {
|
||||
return detail;
|
||||
}
|
||||
if (elapsed >= maxWaitMs) {
|
||||
throw new PollTimeoutError(detail, elapsed);
|
||||
}
|
||||
await sleep(intervalMs);
|
||||
}
|
||||
}
|
||||
|
||||
function signalAbortError(signal: AbortSignal): Error {
|
||||
const reason = signal.reason;
|
||||
return reason instanceof Error ? reason : new Error("Poll aborted");
|
||||
}
|
||||
|
||||
function defaultAbortableSleep(signal?: AbortSignal): (ms: number) => Promise<void> {
|
||||
// fallow-ignore-next-line complexity
|
||||
return (ms: number) =>
|
||||
new Promise<void>((resolve, reject) => {
|
||||
const onAbort = (): void => {
|
||||
clearTimeout(timer);
|
||||
reject(signalAbortError(signal!));
|
||||
};
|
||||
const timer = setTimeout(() => {
|
||||
signal?.removeEventListener("abort", onAbort);
|
||||
resolve();
|
||||
}, ms);
|
||||
signal?.addEventListener("abort", onAbort, { once: true });
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
/**
|
||||
* Shared status-string colorizer used by `cloud list/get/render`.
|
||||
* Extracted so changes to the color palette propagate atomically; without
|
||||
* this, fallow flagged the repeated switch as duplication.
|
||||
*/
|
||||
|
||||
import { c } from "../ui/colors.js";
|
||||
import type { HyperframesRenderStatus } from "./_gen/types.js";
|
||||
|
||||
export function colorStatus(status: HyperframesRenderStatus | string): string {
|
||||
switch (status) {
|
||||
case "completed":
|
||||
return c.success(status);
|
||||
case "failed":
|
||||
return c.error(status);
|
||||
case "rendering":
|
||||
return c.progress(status);
|
||||
default:
|
||||
return c.dim(status);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,69 @@
|
||||
/**
|
||||
* `hyperframes cloud` — top-level dispatcher for cloud-render subverbs.
|
||||
*
|
||||
* Each subverb lives in `./cloud/<name>.ts`. The dispatcher loads them
|
||||
* dynamically so the cloud surface doesn't impact CLI cold-start when
|
||||
* the user is running `render` / `preview` / etc.
|
||||
*
|
||||
* Auth is the existing `cli/src/auth/` chain — `cloud` subverbs call
|
||||
* into `cloud/auth.ts` which bridges `resolveCredential` +
|
||||
* `buildAuthHeaders` into the generated client. There is no new
|
||||
* credentials store and no new env var.
|
||||
*/
|
||||
|
||||
import { defineCommand } from "citty";
|
||||
import type { Example } from "./_examples.js";
|
||||
import { c } from "../ui/colors.js";
|
||||
|
||||
export const examples: Example[] = [
|
||||
["Render the current directory in the cloud", "hyperframes cloud render"],
|
||||
["Render a specific project", "hyperframes cloud render ./my-video"],
|
||||
[
|
||||
"Render at 60fps + high quality, save to a path",
|
||||
"hyperframes cloud render ./my-video --fps 60 --quality high -o ./out.mp4",
|
||||
],
|
||||
[
|
||||
"Fire-and-forget with a webhook",
|
||||
"hyperframes cloud render ./my-video --callback-url https://example.com/hf-hook --no-wait",
|
||||
],
|
||||
["Resubmit an already-uploaded zip", "hyperframes cloud render --asset-id asst_abc123"],
|
||||
[
|
||||
"Render from a public HTTPS zip",
|
||||
"hyperframes cloud render --url https://cdn.example.com/site.zip",
|
||||
],
|
||||
["List recent cloud renders", "hyperframes cloud list"],
|
||||
["Fetch one render's status + signed URLs", "hyperframes cloud get hfr_abc123"],
|
||||
["Soft-delete a render", "hyperframes cloud delete hfr_abc123"],
|
||||
];
|
||||
|
||||
const HELP = `
|
||||
${c.bold("hyperframes cloud")} ${c.dim("<subcommand> [args]")}
|
||||
|
||||
Render HyperFrames compositions on HeyGen's cloud infrastructure. The
|
||||
project zip is uploaded, the render is dispatched, and the resulting
|
||||
video is downloaded locally — without spinning up Chrome or ffmpeg
|
||||
on your machine.
|
||||
|
||||
${c.bold("SUBCOMMANDS:")}
|
||||
${c.accent("render")} ${c.dim("Submit a project (or asset_id / url) and download the result")}
|
||||
${c.accent("list")} ${c.dim("List recent renders in your account")}
|
||||
${c.accent("get")} ${c.dim("Fetch one render's status + signed URLs")}
|
||||
${c.accent("delete")} ${c.dim("Soft-delete a render (GET 404s afterward)")}
|
||||
|
||||
${c.bold("AUTH:")}
|
||||
Uses the credential you signed in with via ${c.accent("hyperframes auth login")}.
|
||||
Override the API base with ${c.accent("HEYGEN_API_URL")} (default https://api.heygen.com).
|
||||
`;
|
||||
|
||||
export default defineCommand({
|
||||
meta: { name: "cloud", description: "Render HyperFrames compositions on the HeyGen cloud" },
|
||||
subCommands: {
|
||||
render: () => import("./cloud/render.js").then((m) => m.default),
|
||||
list: () => import("./cloud/list.js").then((m) => m.default),
|
||||
get: () => import("./cloud/get.js").then((m) => m.default),
|
||||
delete: () => import("./cloud/delete.js").then((m) => m.default),
|
||||
},
|
||||
async run({ args }) {
|
||||
if (!args._?.[0]) console.log(HELP);
|
||||
},
|
||||
});
|
||||
@@ -0,0 +1,87 @@
|
||||
/**
|
||||
* `hyperframes cloud delete <render_id>` — soft-delete a cloud render.
|
||||
*
|
||||
* Subsequent GET calls return 404. The signed video URL stops working
|
||||
* shortly after. There's no undo from the CLI side.
|
||||
*/
|
||||
|
||||
import { defineCommand } from "citty";
|
||||
import { createCloudClient } from "../../cloud/index.js";
|
||||
import { reportApiError } from "../../cloud/errors.js";
|
||||
import { withMeta } from "../../utils/updateCheck.js";
|
||||
import { c } from "../../ui/colors.js";
|
||||
import { errorBox } from "../../ui/format.js";
|
||||
|
||||
export default defineCommand({
|
||||
meta: { name: "delete", description: "Soft-delete a cloud render" },
|
||||
args: {
|
||||
id: {
|
||||
type: "positional",
|
||||
required: true,
|
||||
description: "Render ID to delete",
|
||||
},
|
||||
json: {
|
||||
type: "boolean",
|
||||
description: "Emit machine-readable JSON",
|
||||
default: false,
|
||||
},
|
||||
"no-confirm": {
|
||||
type: "boolean",
|
||||
description: "Skip the interactive confirmation prompt (required for scripts and --json)",
|
||||
default: false,
|
||||
},
|
||||
},
|
||||
// fallow-ignore-next-line complexity
|
||||
async run({ args }) {
|
||||
if (!args["no-confirm"]) {
|
||||
// Don't auto-bypass the prompt just because stdin isn't a TTY
|
||||
// or `--json` was passed — both used to silently skip the
|
||||
// safety check. Force the caller to opt in via `--no-confirm`
|
||||
// so cron jobs, CI shells, and JSON consumers can't soft-delete
|
||||
// by accident.
|
||||
if (args.json || !process.stdin.isTTY) {
|
||||
errorBox(
|
||||
"Confirmation required",
|
||||
"delete cannot prompt for confirmation here — stdin isn't a TTY or --json was passed.",
|
||||
"Re-run with --no-confirm to acknowledge the irreversible delete.",
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
const ok = await confirmDelete(args.id);
|
||||
if (!ok) {
|
||||
// Distinct exit code so wrapper scripts can tell an explicit
|
||||
// decline apart from an API/system error.
|
||||
console.log(c.dim("Aborted."));
|
||||
process.exit(2);
|
||||
}
|
||||
}
|
||||
const client = await createCloudClient();
|
||||
try {
|
||||
const response = await client.deleteRender({ render_id: args.id });
|
||||
if (args.json) {
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
withMeta({ render: { render_id: response.render_id }, deleted: true }),
|
||||
null,
|
||||
2,
|
||||
),
|
||||
);
|
||||
return;
|
||||
}
|
||||
console.log(`${c.success("✓")} Deleted ${c.accent(response.render_id)}`);
|
||||
} catch (err) {
|
||||
reportApiError("Could not delete render", err, {
|
||||
notFound: `No render found with id "${args.id}".`,
|
||||
});
|
||||
}
|
||||
},
|
||||
});
|
||||
|
||||
async function confirmDelete(id: string): Promise<boolean> {
|
||||
const clack = await import("@clack/prompts");
|
||||
const answer = await clack.confirm({
|
||||
message: `Delete render ${id}? This is irreversible.`,
|
||||
initialValue: false,
|
||||
});
|
||||
return answer === true;
|
||||
}
|
||||
@@ -0,0 +1,86 @@
|
||||
/**
|
||||
* `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}`);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,144 @@
|
||||
/**
|
||||
* `hyperframes cloud list` — page through GET /v3/hyperframes/renders.
|
||||
*
|
||||
* Cursor pagination: `--limit` caps a single page (max 100 per the
|
||||
* spec), `--all` walks `next_token` until exhausted. Default page size
|
||||
* mirrors the API default (10).
|
||||
*/
|
||||
|
||||
import { defineCommand } from "citty";
|
||||
import { createCloudClient } from "../../cloud/index.js";
|
||||
import { padEndVisible } from "../../cloud/ansi.js";
|
||||
import { reportApiError } from "../../cloud/errors.js";
|
||||
import { parseIntFlag } from "../../cloud/parsing.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";
|
||||
import { errorBox } from "../../ui/format.js";
|
||||
|
||||
// Safety cap on --all to defend against a buggy backend serving the
|
||||
// same next_token in a loop. 50 pages at the maximum page size of 100
|
||||
// covers 5,000 renders — well past anyone's expected list size.
|
||||
const MAX_ALL_PAGES = 50;
|
||||
|
||||
export default defineCommand({
|
||||
meta: { name: "list", description: "List recent cloud renders" },
|
||||
args: {
|
||||
limit: {
|
||||
type: "string",
|
||||
description: "Items per page (1-100; default 10)",
|
||||
},
|
||||
token: {
|
||||
type: "string",
|
||||
description: "Resume from a previous next_token cursor",
|
||||
},
|
||||
all: {
|
||||
type: "boolean",
|
||||
description: "Fetch every page (follows next_token until exhausted)",
|
||||
default: false,
|
||||
},
|
||||
json: {
|
||||
type: "boolean",
|
||||
description: "Emit machine-readable JSON",
|
||||
default: false,
|
||||
},
|
||||
},
|
||||
// fallow-ignore-next-line complexity
|
||||
async run({ args }) {
|
||||
const limit = parseIntFlag(args.limit, { flag: "--limit", min: 1, max: 100 });
|
||||
|
||||
const client = await createCloudClient();
|
||||
|
||||
try {
|
||||
if (args.all) {
|
||||
const renders = await fetchAll(client, limit);
|
||||
emit(renders, args.json, null, false);
|
||||
} else {
|
||||
const page = await client.listRenders({ limit, token: args.token });
|
||||
emit(page.data ?? [], args.json, page.next_token ?? null, Boolean(page.has_more));
|
||||
}
|
||||
} catch (err) {
|
||||
reportApiError("Could not list cloud renders", err);
|
||||
}
|
||||
},
|
||||
});
|
||||
|
||||
// fallow-ignore-next-line complexity
|
||||
async function fetchAll(
|
||||
client: Awaited<ReturnType<typeof createCloudClient>>,
|
||||
pageSize: number | undefined,
|
||||
): Promise<HyperframesRenderDetail[]> {
|
||||
const out: HyperframesRenderDetail[] = [];
|
||||
const seenCursors = new Set<string>();
|
||||
let token: string | undefined;
|
||||
for (let page = 0; page < MAX_ALL_PAGES; page++) {
|
||||
const result = await client.listRenders({ limit: pageSize, token });
|
||||
out.push(...(result.data ?? []));
|
||||
if (!result.has_more) return out;
|
||||
// Defensive: server said `has_more: true` but didn't hand us a
|
||||
// cursor to use. Better to surface the malformed shape than
|
||||
// return a silently-truncated list.
|
||||
if (!result.next_token) {
|
||||
errorBox(
|
||||
"Pagination cursor missing",
|
||||
"Server returned has_more: true with no next_token — incomplete response.",
|
||||
"Retry the command, or report this if it persists.",
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
if (seenCursors.has(result.next_token)) {
|
||||
errorBox(
|
||||
"Pagination loop detected",
|
||||
`Server returned the same next_token (${result.next_token}) twice.`,
|
||||
"Retry the command, or report this if it persists.",
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
seenCursors.add(result.next_token);
|
||||
token = result.next_token;
|
||||
}
|
||||
errorBox(
|
||||
"Pagination cap reached",
|
||||
`Stopped after ${MAX_ALL_PAGES} pages to avoid an unbounded loop.`,
|
||||
`Re-run with a higher --limit, or paginate manually with --token.`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// fallow-ignore-next-line complexity
|
||||
function emit(
|
||||
renders: HyperframesRenderDetail[],
|
||||
asJson: boolean,
|
||||
nextToken: string | null,
|
||||
hasMore: boolean,
|
||||
): void {
|
||||
if (asJson) {
|
||||
const payload: Record<string, unknown> = { renders, has_more: hasMore };
|
||||
if (nextToken !== null) payload["next_token"] = nextToken;
|
||||
console.log(JSON.stringify(withMeta(payload), null, 2));
|
||||
return;
|
||||
}
|
||||
if (renders.length === 0) {
|
||||
console.log(c.dim("No renders found."));
|
||||
return;
|
||||
}
|
||||
const idWidth = Math.max(8, ...renders.map((r) => r.render_id.length));
|
||||
const statusWidth = Math.max(6, ...renders.map((r) => r.status.length));
|
||||
for (const r of renders) {
|
||||
const id = c.accent(r.render_id);
|
||||
const status = colorStatus(r.status);
|
||||
const created =
|
||||
r.created_at !== undefined && r.created_at !== null
|
||||
? new Date(r.created_at * 1000).toISOString()
|
||||
: "—";
|
||||
const title = r.title ? ` ${c.dim(r.title)}` : "";
|
||||
console.log(
|
||||
`${padEndVisible(id, idWidth)} ${padEndVisible(status, statusWidth)} ${c.dim(created)}${title}`,
|
||||
);
|
||||
}
|
||||
if (nextToken) {
|
||||
console.log("");
|
||||
console.log(c.dim(`More results — pass --token ${nextToken} to continue.`));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,587 @@
|
||||
/**
|
||||
* `hyperframes cloud render` — orchestrate a cloud-rendered HyperFrames
|
||||
* composition end-to-end:
|
||||
*
|
||||
* 1. Resolve the project (or reuse a pre-uploaded `--asset-id` /
|
||||
* `--url`).
|
||||
* 2. Zip the project (reuses `createPublishArchive` so the
|
||||
* file-ignore set matches the existing `publish` command exactly).
|
||||
* 3. Upload the zip via `POST /v3/assets` (multipart) — the server
|
||||
* branches on the detected `application/zip` MIME.
|
||||
* 4. Submit the render via `POST /v3/hyperframes/renders` with a
|
||||
* `project: {type:"asset_id", asset_id}` shape.
|
||||
* 5. If `--no-wait`: print the `render_id` and exit immediately.
|
||||
* Otherwise poll `GET /v3/hyperframes/renders/{id}` every
|
||||
* `--poll-interval` (default 10s, max 60min). `--callback-url`
|
||||
* can be combined with either mode: the webhook always fires when
|
||||
* the server-side render terminates, independent of whether the
|
||||
* CLI is still polling.
|
||||
* 6. On `completed`: stream the signed `video_url` to disk.
|
||||
* 7. On `failed`: print `failure_message` and exit 1.
|
||||
*
|
||||
* Auth comes from the existing `cli/src/auth/` chain via `cloud/auth.ts`.
|
||||
* The cloud HTTP client (`cloud/_gen/client.ts`) is generated from
|
||||
* `experiment-framework/openapi/external-api.json`; never hand-edit it.
|
||||
*/
|
||||
|
||||
import { defineCommand } from "citty";
|
||||
|
||||
import { c } from "../../ui/colors.js";
|
||||
import { errorBox, formatBytes, formatDuration } from "../../ui/format.js";
|
||||
import { resolveProject } from "../../utils/project.js";
|
||||
import { createPublishArchive } from "../../utils/publishProject.js";
|
||||
import {
|
||||
reportVariableIssues,
|
||||
resolveVariablesArg,
|
||||
validateVariablesAgainstProject,
|
||||
} from "../../utils/variables.js";
|
||||
import { withMeta } from "../../utils/updateCheck.js";
|
||||
import type { Example } from "../_examples.js";
|
||||
|
||||
import {
|
||||
DEFAULT_MAX_WAIT_MS,
|
||||
DEFAULT_POLL_INTERVAL_MS,
|
||||
PollTimeoutError,
|
||||
createCloudClient,
|
||||
downloadToFile,
|
||||
pollUntilTerminal,
|
||||
} from "../../cloud/index.js";
|
||||
import { reportApiError } from "../../cloud/errors.js";
|
||||
import { parseEnumFlag, parseIntFlag, parseNumericFlag } from "../../cloud/parsing.js";
|
||||
import { colorStatus } from "../../cloud/statusColor.js";
|
||||
import type {
|
||||
CreateHyperframesRenderRequest,
|
||||
HyperframesCloudClient,
|
||||
HyperframesRenderDetail,
|
||||
} from "../../cloud/index.js";
|
||||
import { isAbsolute, resolve as resolvePath } from "node:path";
|
||||
|
||||
const VALID_QUALITY = ["draft", "standard", "high"] as const;
|
||||
const VALID_FORMAT = ["mp4", "webm", "mov"] as const;
|
||||
const VALID_RESOLUTION = [
|
||||
"landscape",
|
||||
"portrait",
|
||||
"landscape-4k",
|
||||
"portrait-4k",
|
||||
"square",
|
||||
"square-4k",
|
||||
] as const;
|
||||
|
||||
const FORMAT_EXT: Record<string, string> = { mp4: ".mp4", webm: ".webm", mov: ".mov" };
|
||||
|
||||
export const examples: Example[] = [
|
||||
["Render the current directory in the cloud", "hyperframes cloud render"],
|
||||
[
|
||||
"Pick a specific composition + output path",
|
||||
"hyperframes cloud render . --composition compositions/intro.html -o ./renders/intro.mp4",
|
||||
],
|
||||
["Higher quality, 60fps", "hyperframes cloud render --quality high --fps 60"],
|
||||
[
|
||||
"Submit and exit; webhook fires when the render terminates",
|
||||
"hyperframes cloud render --callback-url https://example.com/hook --no-wait",
|
||||
],
|
||||
[
|
||||
"Override variables (parametrized render)",
|
||||
'hyperframes cloud render --variables \'{"title":"Q4 Recap","theme":"dark"}\'',
|
||||
],
|
||||
["Re-render an already-uploaded zip", "hyperframes cloud render --asset-id asst_abc123"],
|
||||
];
|
||||
|
||||
export default defineCommand({
|
||||
meta: { name: "render", description: "Render a HyperFrames composition in the cloud" },
|
||||
args: {
|
||||
dir: { type: "positional", required: false, description: "Project directory (default: .)" },
|
||||
fps: { type: "string", description: "Frames per second (1-240). Default: 30." },
|
||||
quality: { type: "string", description: "draft | standard | high (default: standard)" },
|
||||
format: { type: "string", description: "mp4 | webm | mov (default: mp4)" },
|
||||
resolution: {
|
||||
type: "string",
|
||||
description:
|
||||
"Resolution preset: landscape | portrait | landscape-4k | portrait-4k | square | square-4k",
|
||||
},
|
||||
composition: {
|
||||
type: "string",
|
||||
alias: "c",
|
||||
description: "Entry HTML file inside the zip (default: index.html)",
|
||||
},
|
||||
variables: {
|
||||
type: "string",
|
||||
description:
|
||||
'Inline JSON object overriding data-composition-variables. Example: --variables \'{"title":"X"}\'',
|
||||
},
|
||||
"variables-file": {
|
||||
type: "string",
|
||||
description: "Path to a JSON file with variable values (alternative to --variables)",
|
||||
},
|
||||
"strict-variables": {
|
||||
type: "boolean",
|
||||
description: "Fail when --variables keys are undeclared or have the wrong type",
|
||||
default: false,
|
||||
},
|
||||
title: {
|
||||
type: "string",
|
||||
description: "Free-text label echoed back in detail responses",
|
||||
},
|
||||
"callback-url": {
|
||||
type: "string",
|
||||
description:
|
||||
"HTTPS webhook fired when the render terminates. Fires regardless of whether the CLI is still polling — combine with --no-wait for true fire-and-forget.",
|
||||
},
|
||||
"callback-id": {
|
||||
type: "string",
|
||||
description: "Opaque tracking ID echoed in webhook payloads",
|
||||
},
|
||||
"asset-id": {
|
||||
type: "string",
|
||||
description:
|
||||
"Skip zip+upload and submit an already-uploaded composition. Mutually exclusive with --url and the project dir.",
|
||||
},
|
||||
url: {
|
||||
type: "string",
|
||||
description:
|
||||
"Public HTTPS URL of a composition zip. Mutually exclusive with --asset-id and the project dir.",
|
||||
},
|
||||
"no-wait": {
|
||||
type: "boolean",
|
||||
description: "Submit and exit; print the render_id to stdout",
|
||||
default: false,
|
||||
},
|
||||
output: {
|
||||
type: "string",
|
||||
alias: "o",
|
||||
description: "Destination path for the downloaded video (default: renders/<render_id>.<ext>)",
|
||||
},
|
||||
"poll-interval": {
|
||||
type: "string",
|
||||
description: `Poll cadence in seconds (default: ${DEFAULT_POLL_INTERVAL_MS / 1000})`,
|
||||
},
|
||||
"max-wait": {
|
||||
type: "string",
|
||||
description: `Max poll duration in minutes (default: ${DEFAULT_MAX_WAIT_MS / 60_000})`,
|
||||
},
|
||||
json: {
|
||||
type: "boolean",
|
||||
description: "Emit machine-readable JSON instead of human-friendly progress",
|
||||
default: false,
|
||||
},
|
||||
"idempotency-key": {
|
||||
type: "string",
|
||||
description: "Optional Idempotency-Key for safe retries (1-255 chars from [A-Za-z0-9_:.-])",
|
||||
},
|
||||
},
|
||||
// fallow-ignore-next-line complexity
|
||||
async run({ args }) {
|
||||
const asJson = Boolean(args.json);
|
||||
const fps = parseIntFlag(args.fps, { flag: "--fps", min: 1, max: 240 });
|
||||
const quality = parseEnumFlag(args.quality, VALID_QUALITY, { flag: "--quality" });
|
||||
const format = parseEnumFlag(args.format, VALID_FORMAT, { flag: "--format" });
|
||||
const resolution = parseEnumFlag(args.resolution, VALID_RESOLUTION, {
|
||||
flag: "--resolution",
|
||||
});
|
||||
const pollIntervalMs = parsePollIntervalMs(args["poll-interval"]);
|
||||
const maxWaitMs = parseMaxWaitMs(args["max-wait"]);
|
||||
validateIdempotencyKey(args["idempotency-key"]);
|
||||
|
||||
// Project resolution runs BEFORE variables resolution so a user
|
||||
// passing conflicting inputs (`dir + --asset-id`) sees the
|
||||
// structural error before any variable parsing errors.
|
||||
const project = resolveProjectInput({
|
||||
dir: args.dir,
|
||||
assetId: args["asset-id"],
|
||||
url: args.url,
|
||||
});
|
||||
|
||||
const variables = resolveVariablesAndValidateIfLocal(
|
||||
args.variables,
|
||||
args["variables-file"],
|
||||
args["strict-variables"] ?? false,
|
||||
project,
|
||||
);
|
||||
|
||||
const client = await createCloudClient();
|
||||
|
||||
const upload = await maybeUploadProject(client, project, asJson, args["idempotency-key"]);
|
||||
const submitted = await submitRender(client, {
|
||||
projectInput: upload.projectInput,
|
||||
fps,
|
||||
quality,
|
||||
format,
|
||||
resolution,
|
||||
composition: args.composition,
|
||||
variables,
|
||||
title: args.title,
|
||||
callbackUrl: args["callback-url"],
|
||||
callbackId: args["callback-id"],
|
||||
idempotencyKey: args["idempotency-key"],
|
||||
});
|
||||
|
||||
const renderId = submitted.render_id;
|
||||
if (args["no-wait"]) {
|
||||
if (asJson) {
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
withMeta({ render: { render_id: renderId, status: "queued" as const } }),
|
||||
null,
|
||||
2,
|
||||
),
|
||||
);
|
||||
} else {
|
||||
console.log("");
|
||||
console.log(`${c.success("✓")} Submitted ${c.accent(renderId)}`);
|
||||
console.log(c.dim(` Poll with: hyperframes cloud get ${renderId}`));
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
if (!asJson) {
|
||||
console.log("");
|
||||
console.log(c.dim(` Polling ${renderId} every ${pollIntervalMs / 1000}s …`));
|
||||
}
|
||||
|
||||
const detail = await pollWithProgress(client, renderId, asJson, {
|
||||
intervalMs: pollIntervalMs,
|
||||
maxWaitMs,
|
||||
});
|
||||
|
||||
if (detail.status === "failed") {
|
||||
handleFailedRender(detail, asJson);
|
||||
}
|
||||
|
||||
if (!detail.video_url) {
|
||||
errorBox(
|
||||
"Render completed but returned no video_url",
|
||||
`render_id: ${renderId}. Try \`hyperframes cloud get ${renderId}\` to inspect raw fields.`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const outputPath = resolveOutputPath(args.output, renderId, detail.format);
|
||||
const downloadResult = await streamVideo(detail.video_url, outputPath, asJson);
|
||||
|
||||
if (asJson) {
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
withMeta({
|
||||
render: detail,
|
||||
output_path: outputPath,
|
||||
bytes_written: downloadResult.bytes,
|
||||
}),
|
||||
null,
|
||||
2,
|
||||
),
|
||||
);
|
||||
}
|
||||
},
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Argument parsing — defers to cloud/parsing.ts for strict validators
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function parsePollIntervalMs(raw: string | undefined): number {
|
||||
const n = parseNumericFlag(raw, { flag: "--poll-interval", min: 1 });
|
||||
return n === undefined ? DEFAULT_POLL_INTERVAL_MS : Math.round(n * 1000);
|
||||
}
|
||||
|
||||
function parseMaxWaitMs(raw: string | undefined): number {
|
||||
const n = parseNumericFlag(raw, { flag: "--max-wait", min: 0.0001 });
|
||||
return n === undefined ? DEFAULT_MAX_WAIT_MS : Math.round(n * 60_000);
|
||||
}
|
||||
|
||||
const IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9_:.-]{1,255}$/;
|
||||
|
||||
function validateIdempotencyKey(key: string | undefined): void {
|
||||
if (key === undefined) return;
|
||||
if (!IDEMPOTENCY_KEY_RE.test(key)) {
|
||||
errorBox("Invalid --idempotency-key", `Got "${key}". Must be 1-255 chars from [A-Za-z0-9_:.-]`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Project resolution (dir | asset-id | url) — exactly one source
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
interface ProjectInputSource {
|
||||
kind: "dir" | "asset_id" | "url";
|
||||
dir?: string;
|
||||
assetId?: string;
|
||||
url?: string;
|
||||
}
|
||||
|
||||
// fallow-ignore-next-line complexity
|
||||
function resolveProjectInput(opts: {
|
||||
dir: string | undefined;
|
||||
assetId: string | undefined;
|
||||
url: string | undefined;
|
||||
}): ProjectInputSource {
|
||||
// Count every source the user explicitly supplied. The positional
|
||||
// `dir` defaults to `undefined` when omitted (not to "."), so we
|
||||
// can detect "user actually typed something" vs. "default to cwd".
|
||||
const explicit = {
|
||||
dir: opts.dir !== undefined && opts.dir !== "",
|
||||
assetId: opts.assetId !== undefined && opts.assetId !== "",
|
||||
url: opts.url !== undefined && opts.url !== "",
|
||||
};
|
||||
const count = Number(explicit.dir) + Number(explicit.assetId) + Number(explicit.url);
|
||||
if (count > 1) {
|
||||
errorBox("Conflicting inputs", "Pass only one of: project dir, --asset-id, --url.");
|
||||
process.exit(1);
|
||||
}
|
||||
if (explicit.assetId) return { kind: "asset_id", assetId: opts.assetId };
|
||||
if (explicit.url) return { kind: "url", url: opts.url };
|
||||
return { kind: "dir", dir: opts.dir ?? "." };
|
||||
}
|
||||
|
||||
function resolveVariablesAndValidateIfLocal(
|
||||
inline: string | undefined,
|
||||
filePath: string | undefined,
|
||||
strict: boolean,
|
||||
source: ProjectInputSource,
|
||||
): Record<string, unknown> | undefined {
|
||||
const variables = resolveVariablesArg(inline, filePath);
|
||||
if (!variables || Object.keys(variables).length === 0) return variables;
|
||||
// Only validate against the local composition when we actually have
|
||||
// a local project on disk. For --asset-id / --url paths the schema
|
||||
// lives on the server side, so we send the variables as-is and let
|
||||
// the API surface any mismatch via `hyperframes_project_invalid`.
|
||||
if (source.kind !== "dir") return variables;
|
||||
// `resolveProject` calls process.exit on a missing/invalid dir, so
|
||||
// there's no need to wrap this in try/catch — if it returns, the
|
||||
// index.html is present. The earlier impl had a dead try/catch.
|
||||
const { indexPath } = resolveProject(source.dir);
|
||||
const issues = validateVariablesAgainstProject(indexPath, variables);
|
||||
reportVariableIssues(issues, { strict, quiet: false });
|
||||
return variables;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Upload step (only when project is a local dir)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
interface UploadResult {
|
||||
projectInput: CreateHyperframesRenderRequest["project"];
|
||||
}
|
||||
|
||||
// fallow-ignore-next-line complexity
|
||||
async function maybeUploadProject(
|
||||
client: HyperframesCloudClient,
|
||||
source: ProjectInputSource,
|
||||
asJson: boolean,
|
||||
idempotencyKey: string | undefined,
|
||||
): Promise<UploadResult> {
|
||||
if (source.kind === "asset_id") {
|
||||
return { projectInput: { type: "asset_id", asset_id: source.assetId! } };
|
||||
}
|
||||
if (source.kind === "url") {
|
||||
return { projectInput: { type: "url", url: source.url! } };
|
||||
}
|
||||
|
||||
const project = resolveProject(source.dir);
|
||||
if (!asJson) {
|
||||
console.log("");
|
||||
console.log(`${c.accent("◆")} Zipping ${c.accent(project.name)}`);
|
||||
}
|
||||
let archive;
|
||||
try {
|
||||
archive = createPublishArchive(project.dir);
|
||||
} catch (err) {
|
||||
const msg = err instanceof Error ? err.message : String(err);
|
||||
errorBox("Zip failed", msg, "Check the project for missing files or unreadable permissions.");
|
||||
process.exit(1);
|
||||
}
|
||||
if (!asJson) {
|
||||
console.log(c.dim(` ${archive.fileCount} files · ${formatBytes(archive.buffer.byteLength)}`));
|
||||
}
|
||||
|
||||
if (!asJson) {
|
||||
console.log("");
|
||||
console.log(`${c.accent("◆")} Uploading to /v3/assets`);
|
||||
}
|
||||
const uploadStart = Date.now();
|
||||
let uploaded;
|
||||
try {
|
||||
uploaded = await client.uploadAsset({
|
||||
file: archive.buffer,
|
||||
filename: `${project.name}.zip`,
|
||||
// Tag the multipart part with application/zip so downstream
|
||||
// proxies / WAFs / any server-side path that keys off the
|
||||
// part Content-Type see the intended type. The asset
|
||||
// controller currently sniffs magic bytes from the file
|
||||
// bytes, so this is belt-and-suspenders today; without it,
|
||||
// FormData defaults to application/octet-stream.
|
||||
mimeType: "application/zip",
|
||||
idempotencyKey,
|
||||
});
|
||||
} catch (err) {
|
||||
reportApiError("Upload failed", err);
|
||||
}
|
||||
if (!asJson) {
|
||||
console.log(
|
||||
c.dim(
|
||||
` asset_id: ${c.accent(uploaded.asset_id)} · ${formatDuration(Date.now() - uploadStart)}`,
|
||||
),
|
||||
);
|
||||
}
|
||||
return { projectInput: { type: "asset_id", asset_id: uploaded.asset_id } };
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Submit step
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
interface SubmitOptions {
|
||||
projectInput: CreateHyperframesRenderRequest["project"];
|
||||
fps: number | undefined;
|
||||
quality: "draft" | "standard" | "high" | undefined;
|
||||
format: "mp4" | "webm" | "mov" | undefined;
|
||||
resolution: CreateHyperframesRenderRequest["resolution"] | undefined;
|
||||
composition: string | undefined;
|
||||
variables: Record<string, unknown> | undefined;
|
||||
title: string | undefined;
|
||||
callbackUrl: string | undefined;
|
||||
callbackId: string | undefined;
|
||||
idempotencyKey: string | undefined;
|
||||
}
|
||||
|
||||
async function submitRender(
|
||||
client: HyperframesCloudClient,
|
||||
opts: SubmitOptions,
|
||||
): Promise<{ render_id: string }> {
|
||||
const body = buildRenderBody(opts);
|
||||
try {
|
||||
return await client.createRender({ body, idempotencyKey: opts.idempotencyKey });
|
||||
} catch (err) {
|
||||
reportApiError("Submit failed", err);
|
||||
}
|
||||
}
|
||||
|
||||
// fallow-ignore-next-line complexity
|
||||
function buildRenderBody(opts: SubmitOptions): CreateHyperframesRenderRequest {
|
||||
const body: CreateHyperframesRenderRequest = { project: opts.projectInput };
|
||||
if (opts.fps !== undefined) body.fps = opts.fps;
|
||||
if (opts.quality !== undefined) body.quality = opts.quality;
|
||||
if (opts.format !== undefined) body.format = opts.format;
|
||||
if (opts.resolution !== undefined) body.resolution = opts.resolution;
|
||||
if (opts.composition !== undefined) body.composition = opts.composition;
|
||||
if (opts.variables !== undefined) body.variables = opts.variables;
|
||||
if (opts.title !== undefined) body.title = opts.title;
|
||||
if (opts.callbackUrl !== undefined) body.callback_url = opts.callbackUrl;
|
||||
if (opts.callbackId !== undefined) body.callback_id = opts.callbackId;
|
||||
return body;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Poll + progress
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
// fallow-ignore-next-line complexity
|
||||
async function pollWithProgress(
|
||||
client: HyperframesCloudClient,
|
||||
renderId: string,
|
||||
asJson: boolean,
|
||||
poll: { intervalMs: number; maxWaitMs: number },
|
||||
): Promise<HyperframesRenderDetail> {
|
||||
// ANSI carriage-return redraws only make sense on a TTY. CI logs and
|
||||
// file redirects get one append per status change instead, and JSON
|
||||
// mode stays silent altogether.
|
||||
const interactive = !asJson && process.stdout.isTTY === true;
|
||||
let lastStatus = "";
|
||||
try {
|
||||
return await pollUntilTerminal(client, renderId, {
|
||||
intervalMs: poll.intervalMs,
|
||||
maxWaitMs: poll.maxWaitMs,
|
||||
// fallow-ignore-next-line complexity
|
||||
onTick: (detail, elapsedMs) => {
|
||||
if (asJson) return;
|
||||
if (interactive) {
|
||||
if (detail.status === lastStatus) {
|
||||
process.stdout.write(`\r\x1b[2K ${formatTickLine(detail, elapsedMs)}`);
|
||||
} else {
|
||||
if (lastStatus) process.stdout.write("\n");
|
||||
process.stdout.write(` ${formatTickLine(detail, elapsedMs)}`);
|
||||
lastStatus = detail.status;
|
||||
}
|
||||
} else if (detail.status !== lastStatus) {
|
||||
// Non-TTY: one line per status transition, no carriage returns.
|
||||
console.log(` ${formatTickLine(detail, elapsedMs)}`);
|
||||
lastStatus = detail.status;
|
||||
}
|
||||
},
|
||||
});
|
||||
} catch (err) {
|
||||
if (!asJson && lastStatus && interactive) process.stdout.write("\n");
|
||||
if (err instanceof PollTimeoutError) {
|
||||
errorBox(
|
||||
"Poll timed out",
|
||||
err.message,
|
||||
`The render may still complete. Resume with: hyperframes cloud get ${renderId}`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
return reportApiError("API error during poll", err, {
|
||||
suggestion: `The render may still be running. Resume with: hyperframes cloud get ${renderId}`,
|
||||
});
|
||||
} finally {
|
||||
if (!asJson && lastStatus && interactive) process.stdout.write("\n");
|
||||
}
|
||||
}
|
||||
|
||||
function formatTickLine(detail: HyperframesRenderDetail, elapsedMs: number): string {
|
||||
const status = colorStatus(detail.status);
|
||||
return `${status} ${c.dim(formatDuration(elapsedMs))}`;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Terminal handlers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function handleFailedRender(detail: HyperframesRenderDetail, asJson: boolean): never {
|
||||
if (asJson) {
|
||||
console.log(JSON.stringify(withMeta({ render: detail }), null, 2));
|
||||
process.exit(1);
|
||||
}
|
||||
errorBox(
|
||||
"Render failed",
|
||||
detail.failure_message ?? "(no failure_message returned)",
|
||||
`Inspect: hyperframes cloud get ${detail.render_id}`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
function resolveOutputPath(output: string | undefined, renderId: string, format: string): string {
|
||||
if (output) {
|
||||
return isAbsolute(output) ? output : resolvePath(process.cwd(), output);
|
||||
}
|
||||
const ext = FORMAT_EXT[format] ?? `.${format}`;
|
||||
return resolvePath(process.cwd(), "renders", `${renderId}${ext}`);
|
||||
}
|
||||
|
||||
// fallow-ignore-next-line complexity
|
||||
async function streamVideo(
|
||||
url: string,
|
||||
destPath: string,
|
||||
asJson: boolean,
|
||||
): Promise<{ bytes: number }> {
|
||||
// `downloadToFile` already creates the parent directory and cleans
|
||||
// up the partial file on error — no pre-mkdir needed here.
|
||||
if (!asJson) {
|
||||
console.log("");
|
||||
console.log(`${c.accent("◆")} Downloading to ${c.accent(destPath)}`);
|
||||
}
|
||||
try {
|
||||
const result = await downloadToFile(url, destPath);
|
||||
if (!asJson) {
|
||||
console.log(c.dim(` ${formatBytes(result.bytes)} written`));
|
||||
}
|
||||
return { bytes: result.bytes };
|
||||
} catch (err) {
|
||||
const message = err instanceof Error ? err.message : String(err);
|
||||
errorBox(
|
||||
"Download failed",
|
||||
message,
|
||||
"The presigned URL is short-lived; re-fetch with `hyperframes cloud get`.",
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
@@ -53,7 +53,10 @@ const GROUPS: Group[] = [
|
||||
},
|
||||
{
|
||||
title: "Deploy",
|
||||
commands: [["lambda", "Deploy and drive distributed renders on AWS Lambda"]],
|
||||
commands: [
|
||||
["cloud", "Render compositions on HeyGen's cloud (no local Chrome/ffmpeg)"],
|
||||
["lambda", "Deploy and drive distributed renders on AWS Lambda"],
|
||||
],
|
||||
},
|
||||
{
|
||||
title: "AI & Integrations",
|
||||
@@ -97,12 +100,32 @@ const ROOT_EXAMPLES: Example[] = [
|
||||
// ── Per-command examples loaded from command files ────────────────────────
|
||||
// Each command file exports `examples: Example[]`. This function dynamically
|
||||
// imports them so examples live next to the command they document.
|
||||
async function loadExamples(name: string): Promise<Example[] | undefined> {
|
||||
//
|
||||
// For nested subverbs (e.g. `cloud render`), try the parent-scoped path
|
||||
// first (`commands/cloud/render.js`) so we don't collide with the
|
||||
// top-level command of the same name (`commands/render.js`).
|
||||
// fallow-ignore-next-line complexity
|
||||
async function loadExamples(name: string, parentName?: string): Promise<Example[] | undefined> {
|
||||
// Skip the parent-scoped lookup for the root command — `parentName`
|
||||
// is `'hyperframes'` for every top-level subcommand and no
|
||||
// `./commands/hyperframes/<name>.js` directory will ever exist.
|
||||
if (parentName && parentName !== "hyperframes") {
|
||||
const examples = await tryLoadExamples(`./commands/${parentName}/${name}.js`);
|
||||
if (examples) return examples;
|
||||
}
|
||||
return await tryLoadExamples(`./commands/${name}.js`);
|
||||
}
|
||||
|
||||
async function tryLoadExamples(modulePath: string): Promise<Example[] | undefined> {
|
||||
try {
|
||||
const mod = await import(`./commands/${name}.js`);
|
||||
const mod = await import(modulePath);
|
||||
return mod.examples;
|
||||
} catch {
|
||||
return undefined;
|
||||
} catch (err) {
|
||||
// Only swallow "file doesn't exist" — re-throw real load errors
|
||||
// (syntax error, broken import, init-time throw) so a developer
|
||||
// sees the diagnostic instead of getting silently wrong help.
|
||||
if ((err as NodeJS.ErrnoException).code === "ERR_MODULE_NOT_FOUND") return undefined;
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -156,6 +179,7 @@ function formatExamples(examples: Example[]): string {
|
||||
}
|
||||
|
||||
// ── Main showUsage override ────────────────────────────────────────────────
|
||||
// fallow-ignore-next-line complexity
|
||||
export async function showUsage(cmd: CommandDef, parent?: CommandDef): Promise<void> {
|
||||
if (!parent) {
|
||||
console.log(renderRootHelp() + "\n");
|
||||
@@ -168,7 +192,9 @@ export async function showUsage(cmd: CommandDef, parent?: CommandDef): Promise<v
|
||||
|
||||
const name = meta?.name;
|
||||
if (name) {
|
||||
const examples = STATIC_EXAMPLES[name] ?? (await loadExamples(name));
|
||||
const parentMeta = await (typeof parent.meta === "function" ? parent.meta() : parent.meta);
|
||||
const parentName = parentMeta?.name;
|
||||
const examples = STATIC_EXAMPLES[name] ?? (await loadExamples(name, parentName));
|
||||
if (examples) {
|
||||
console.log(formatExamples(examples) + "\n");
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user