import { failCommand, failUsage } from "../../utils/commandResult.js"; /** * `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 the direct-to-S3 flow: `POST /v3/assets/ * direct-uploads` returns a presigned URL, we PUT the zip bytes * to it, then `POST /v3/assets/{asset_id}/complete` finalizes. * Cap: 200 MB. See `../../cloud/upload.ts` for the three-step * contract. (The legacy `POST /v3/assets` proxy path was 32 MB.) * 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 2s, 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 * HeyGen's external API OpenAPI spec; never hand-edit it. */ import { defineCommand } from "../../utils/defineCommand.js"; import { ASPECT_RATIO_MATCH_TOLERANCE, detectAspectRatioFromHtml, type AspectRatioDetection, type SupportedAspectRatio, } from "../../cloud/detectAspectRatio.js"; import { CANVAS_DIMENSIONS, checkOutputResolutionCompatibility, type CanvasResolution, } from "@hyperframes/core"; import { c } from "../../ui/colors.js"; import { errorBox, formatBytes, formatDuration } from "../../ui/format.js"; import { describeUnresolvedFontUse } from "../../cloud/fontFailure.js"; import { resolveDefaultFpsArg } from "../../utils/renderArgs.js"; import { resolveProject, type ProjectDir } from "../../utils/project.js"; import { readProjectConfig } from "../../utils/projectConfig.js"; import { normalizeErrorMessage } from "../../utils/errorMessage.js"; import { readStaged, type StagedFile, stagedSize, stagePublishFiles, type PublishArchiveResult, zipPublishFileMap, } 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 { describeUnresolvedFonts, embedSystemFonts } from "../../cloud/fontPreflight.js"; import { parseEnumFlag, parseIntFlag, parseNumericFlag } from "../../cloud/parsing.js"; import { uploadAssetViaDirectUpload, uploadZipViaDirectUpload } from "../../cloud/upload.js"; import { OFFLOAD_MIN_BYTES, offloadHeavyMedia, type OffloadedMedia, type OffloadOptions, } from "../../cloud/offload.js"; import { resolveCloudBaseUrl } from "../../cloud/auth.js"; import { colorStatus } from "../../cloud/statusColor.js"; import type { CreateHyperframesRenderRequest, HyperframesCloudClient, HyperframesRenderDetail, } from "../../cloud/index.js"; import { isAbsolute, relative, resolve as resolvePath } from "node:path"; import { statSync } from "node:fs"; import { compositionEntryErrorMessage, parseCompositionEntryArg, } from "../../utils/compositionEntry.js"; const VALID_QUALITY = ["draft", "standard", "high"] as const; const VALID_FORMAT = ["mp4", "webm", "mov"] as const; const VALID_RESOLUTION = ["1080p", "4k"] as const; const VALID_ASPECT_RATIO = ["16:9", "9:16", "1:1"] as const; // Mirrors the binary-byte max_bytes contract used by direct asset uploads. const DIRECT_UPLOAD_LIMIT_BYTES = 200 * 1024 * 1024; const ARCHIVE_DIAGNOSTIC_THRESHOLD_BYTES = 150 * 1024 * 1024; const LARGEST_FILE_COUNT = 10; const FORMAT_EXT: Record = { mp4: ".mp4", webm: ".webm", mov: ".mov" }; export const examples: Example[] = [ ["Render the current directory in the cloud", "hyperframes cloud render"], ["Inspect archive size without uploading", "hyperframes cloud render --dry-run"], [ "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: the composition's root data-fps, else 30.", }, quality: { type: "string", description: "draft | standard | high (default: standard)" }, format: { type: "string", description: "mp4 | webm | mov (default: mp4)" }, resolution: { type: "string", description: "Resolution tier: 1080p | 4k (default: 1080p; 4k is billed at 1.5x)", }, "aspect-ratio": { type: "string", description: "W:H; detected from the composition, so rarely needed. The render keeps the composition's own size; 4k needs 16:9, 9:16 or 1:1", }, 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.", }, // Citty parses `--no-FOO` as `--FOO=false`. A flag literally named // "no-wait" gets routed as `args.wait=false`, leaving // `args["no-wait"]` undefined and the early-return for // fire-and-forget mode unreachable. Named the arg `wait` so the // user-facing `--no-wait` flag works via citty's negation; the // run() body checks `if (!args.wait)`. wait: { type: "boolean", description: "Poll until completion and download the video (default: true). Pass `--no-wait` for fire-and-forget — submits and exits with the render_id.", default: true, }, output: { type: "string", alias: "o", description: "Destination path for the downloaded video (default: renders/.)", }, "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, }, "dry-run": { type: "boolean", description: "Build and inspect the project zip without authenticating or uploading", 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 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 explicitAspectRatio = parseAspectRatioFlag(args["aspect-ratio"]); 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, }); validateDryRunSource(project, args["dry-run"] ?? false); const fps = parseIntFlag(resolveCloudFpsArg(project, args.fps, args.composition), { flag: "--fps", min: 1, max: 240, }); // Aspect ratio is derived from the composition's authored dimensions: for // a local dir we parse the entry HTML and auto-detect, so the user rarely // needs --aspect-ratio at all. When they DO pass it, we validate it // matches the composition (the renderer can't reshape, only supersample to // a matching ratio) and fail fast on a mismatch. This also fails fast when // the --composition entry file is missing, rather than uploading a zip the // render rejects with a generic server-side error. const aspectRatio = resolveAspectRatioForSubmit( project, args.composition, explicitAspectRatio, asJson, resolution, ); if (args["dry-run"]) { if (project.kind !== "dir") throw new Error("Dry-run project must be a local directory"); reportDryRun(await prepareLocalArchive(project, args.composition, asJson), asJson); return; } const variables = resolveVariablesAndValidateIfLocal( args.variables, args["variables-file"], args["strict-variables"] ?? false, project, args.composition, ); const client = await createCloudClient(); const preparedArchive = project.kind === "dir" ? await prepareLocalArchive( project, args.composition, asJson, (file) => uploadAssetViaDirectUpload({ client, ...file }), variables && JSON.stringify(variables), ) : undefined; const upload = await maybeUploadProject( client, project, preparedArchive, asJson, args["idempotency-key"], ); const submitted = await submitRender(client, { projectInput: upload.projectInput, fps, quality, format, resolution, aspectRatio, composition: args.composition, variables, title: args.title, callbackUrl: args["callback-url"], callbackId: args["callback-id"], idempotencyKey: args["idempotency-key"], reverseSessionId: reverseSessionIdOf(project), }); const renderId = submitted.render_id; if (!args.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, project.kind === "dir" ? (project.dir ?? ".") : undefined); } if (!detail.video_url) { errorBox( "Render completed but returned no video_url", `render_id: ${renderId}. Try \`hyperframes cloud get ${renderId}\` to inspect raw fields.`, ); failCommand(); } 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_:.-]`); failUsage(); } } export function validateDryRunSource(source: ProjectInputSource, dryRun: boolean): void { if (!dryRun || source.kind === "dir") return; errorBox( "Invalid --dry-run input", "--dry-run inspects a local project directory and cannot be combined with --asset-id or --url.", ); failUsage(); } // --------------------------------------------------------------------------- // Project resolution (dir | asset-id | url) — exactly one source // --------------------------------------------------------------------------- export 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."); failUsage(); } 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 ?? "." }; } /** * Resolve the aspect ratio for the submit body, validating local inputs. * * Aspect ratio is a property of the composition (its `data-width`/`data-height`), not a render knob: at 1080p the * cloud renders at the composition's own size whatever `aspect_ratio` says, and a 4k render scales it up to a 16:9, * 9:16 or 1:1 preset, the only values the API accepts. So: * * - a detected 16:9 / 9:16 / 1:1 is sent; * - any other ratio (2:1, 4:5, …) is not sent at 1080p, where the output keeps the composition's size, and is * refused before upload at 4k, where no preset fits it; * - an explicit `--aspect-ratio W:H` that contradicts the composition is refused before upload. * * Logs are suppressed in `--json` mode so machine output stays clean. */ // fallow-ignore-next-line complexity export function resolveAspectRatioForSubmit( project: ProjectInputSource, compositionArg: string | undefined, explicit: string | undefined, asJson: boolean, resolution: "1080p" | "4k" = "1080p", ): SupportedAspectRatio | undefined { if (project.kind !== "dir") { if (explicit && isSupportedAspectRatio(explicit)) return explicit; if (explicit) refuseUnsupportedAt4k(resolution, `--aspect-ratio ${explicit}`); const reason = project.kind === "asset_id" ? "--asset-id" : "--url"; logDetection(asJson, `Auto-detect skipped (project is ${reason}); ${KEEPS_OWN_SIZE}`); return undefined; } const dir = project.dir ?? "."; const entry = parseCompositionEntryArg(compositionArg ?? "index.html", dir, statSync); if (!entry.ok) { const { title, message, hint } = compositionEntryErrorMessage(entry.error); errorBox(title, message, hint); failCommand(); } const entryRelative = entry.value ?? "index.html"; const detection = detectAspectRatioFromHtml(resolvePath(dir, entryRelative)); const dims = detection.kind === "matched" || detection.kind === "no-match" ? detection : null; if (explicit && dims && !sameRatio(explicit, dims.width / dims.height)) { errorBox( "Aspect ratio mismatch", `--aspect-ratio ${explicit} doesn't match the composition (${dims.width}×${dims.height}, ${ratioLabel(dims.width, dims.height)}).`, "The renderer keeps the composition's authored aspect ratio; it can't reshape it. Drop --aspect-ratio (it's auto-detected) or re-author the composition at the target ratio.", ); failCommand(); } if (detection.kind === "matched") { if (resolution === "4k") refuseUnfit4kPreset(detection); logDetection(asJson, summarizeDetection(detection, entryRelative)); return detection.aspectRatio; } if (detection.kind === "no-match") { refuseUnsupportedAt4k( resolution, `This composition (${detection.width}×${detection.height}, ${ratioLabel(detection.width, detection.height)})`, `Render it at 1080p, which keeps ${detection.width}×${detection.height}, or re-author it at a supported ratio.`, ); logDetection(asJson, summarizeDetection(detection, entryRelative)); return undefined; } if (explicit && isSupportedAspectRatio(explicit)) return explicit; if (explicit) refuseUnsupportedAt4k(resolution, `--aspect-ratio ${explicit}`); logDetection(asJson, `${summarizeDetection(detection, entryRelative)}; ${KEEPS_OWN_SIZE}`); return undefined; } const KEEPS_OWN_SIZE = "the render keeps the composition's own size."; const isSupportedAspectRatio = (value: string): value is SupportedAspectRatio => (VALID_ASPECT_RATIO as readonly string[]).includes(value); function sameRatio(aspect: string, ratio: number): boolean { const [w, h] = aspect.split(":").map(Number); return Math.abs(w! / h! - ratio) <= ASPECT_RATIO_MATCH_TOLERANCE; } function ratioLabel(width: number, height: number): string { if (!Number.isInteger(width) || !Number.isInteger(height)) return (width / height).toFixed(2); const gcd = (a: number, b: number): number => (b === 0 ? a : gcd(b, a % b)); const d = gcd(width, height); return `${width / d}:${height / d}`; } const PRESET_4K: Record = { "16:9": "landscape-4k", "9:16": "portrait-4k", "1:1": "square-4k", }; /** The detector matches a ratio within a tolerance; the renderer's 4K preset has to fit the exact size. */ function refuseUnfit4kPreset(detection: { aspectRatio: SupportedAspectRatio; width: number; height: number; }): void { const preset = PRESET_4K[detection.aspectRatio]; const compat = checkOutputResolutionCompatibility({ compositionWidth: detection.width, compositionHeight: detection.height, outputResolution: preset, }); if (compat.ok) return; const exact = CANVAS_DIMENSIONS[preset]; errorBox( "No 4K preset fits this composition", `${detection.width}×${detection.height} cannot render at 4K as ${detection.aspectRatio}: ${compat.message}`, `Render it at 1080p, which keeps ${detection.width}×${detection.height}, or re-author it at ${exact.width / 2}×${exact.height / 2}.`, ); failCommand(); } function refuseUnsupportedAt4k( resolution: "1080p" | "4k", subject: string, fix = "Render at 1080p, which keeps the composition's own size.", ): void { if (resolution !== "4k") return; errorBox( "No 4K preset for this aspect ratio", `${subject} is not 16:9, 9:16 or 1:1, the only ratios a 4K cloud render can scale to.`, fix, ); failCommand(); } /** `--aspect-ratio` takes any `W:H`; only 16:9, 9:16 and 1:1 are sent, the rest are checked against the composition. */ export function parseAspectRatioFlag(raw: string | undefined): string | undefined { if (raw === undefined) return undefined; const match = /^([1-9]\d*):([1-9]\d*)$/.exec(raw.trim()); if (match) return `${match[1]}:${match[2]}`; errorBox("Invalid --aspect-ratio", `Got "${raw}". Use W:H, such as 16:9, 9:16, 1:1 or 2:1.`); failUsage(); } function logDetection(asJson: boolean, message: string): void { if (asJson) return; console.log(c.dim(` ${message}`)); } // fallow-ignore-next-line complexity function summarizeDetection(detection: AspectRatioDetection, entryRelative: string): string { switch (detection.kind) { case "matched": return `Detected aspect ratio: ${detection.aspectRatio} (from ${entryRelative} dims ${detection.width}×${detection.height})`; case "no-root-div": return `No
found in ${entryRelative}`; case "no-dims": return `${entryRelative} root composition has no data-width / data-height`; case "invalid-dims": return `${entryRelative} root has invalid dims (${detection.width}×${detection.height})`; case "no-match": return `Detected aspect ratio: ${ratioLabel(detection.width, detection.height)} (from ${entryRelative} dims ${detection.width}×${detection.height}); the cloud render keeps that size`; case "read-error": return `Couldn't read ${entryRelative} for aspect-ratio detection (${detection.error})`; } } function resolveVariablesAndValidateIfLocal( inline: string | undefined, filePath: string | undefined, strict: boolean, source: ProjectInputSource, composition: string | undefined, ): Record | 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; const project = resolveProject(source.dir); const entryPath = resolvePath(project.dir, composition ?? "index.html"); const issues = validateVariablesAgainstProject(entryPath, variables); reportVariableIssues(issues, { strict, quiet: false }); return variables; } // --------------------------------------------------------------------------- // Upload step (only when project is a local dir) // --------------------------------------------------------------------------- interface UploadResult { projectInput: CreateHyperframesRenderRequest["project"]; } export interface ArchiveFileSummary { path: string; size_bytes: number; } interface PreparedLocalArchive { project: ProjectDir; /** Absent when the files left on disk alone are over the upload limit: they are never read. */ archive?: PublishArchiveResult; sizeBytes: number; fileCount: number; largestFiles: ArchiveFileSummary[]; offloaded: OffloadedMedia[]; } function summarizeLargestFiles(fileMap: Map): ArchiveFileSummary[] { return [...fileMap.entries()] .map(([path, content]) => ({ path, size_bytes: stagedSize(content) })) .sort((a, b) => b.size_bytes - a.size_bytes || a.path.localeCompare(b.path)) .slice(0, LARGEST_FILE_COUNT); } async function prepareLocalArchive( source: ProjectInputSource, composition: string | undefined, asJson: boolean, upload?: OffloadOptions["upload"], variablesText?: string, ): Promise { const project = resolveProject(source.dir); if (!asJson) { console.log(""); console.log(`${c.accent("◆")} Zipping ${c.accent(project.name)}`); } const { fileMap, entryPath } = stageProjectFiles(project, composition); const missingFonts = await embedSystemFonts({ dir: project.dir, entryFile: composition, entryPath, fileMap, }); if (missingFonts.length > 0) { errorBox("Fonts not on this computer", describeUnresolvedFonts(missingFonts)); failCommand(); } const offloaded = await offloadMedia(project, fileMap, entryPath, asJson, upload, variablesText); // Media left on disk barely compresses: past the limit, its size is the report and nothing is read. const onDiskBytes = [...fileMap.values()] .filter((file) => !Buffer.isBuffer(file)) .reduce((sum, file) => sum + stagedSize(file), 0); const archive = onDiskBytes > DIRECT_UPLOAD_LIMIT_BYTES ? undefined : zipPublishFileMap(new Map([...fileMap].map(([path, file]) => [path, readStaged(file)]))); const sizeBytes = archive?.buffer.byteLength ?? onDiskBytes; if (!asJson) { console.log(c.dim(` ${fileMap.size} files · ${formatBytes(sizeBytes)}`)); } const largestFiles = summarizeLargestFiles(fileMap); const prepared = { project, archive, sizeBytes, fileCount: fileMap.size, largestFiles, offloaded, }; if (upload) assertArchiveFits(sizeBytes, largestFiles); if (!asJson && sizeBytes >= ARCHIVE_DIAGNOSTIC_THRESHOLD_BYTES) { reportLargestFiles(prepared); } return prepared; } function stageProjectFiles( project: ProjectDir, composition: string | undefined, ): { fileMap: Map; entryPath: string } { try { const fileMap = stagePublishFiles(project.dir, OFFLOAD_MIN_BYTES); const entryPath = relative( project.dir, resolvePath(project.dir, composition ?? "index.html"), ).replaceAll("\\", "/"); if (!fileMap.has(entryPath)) { throw new Error( `Composition "${composition ?? "index.html"}" is excluded from the archive. Check .hyperframesignore.`, ); } return { fileMap, entryPath }; } catch (err) { const msg = normalizeErrorMessage(err); errorBox("Zip failed", msg, "Check the project and .hyperframesignore for missing files."); failCommand(); } } async function offloadMedia( project: ProjectDir, fileMap: Map, entryPath: string, asJson: boolean, upload: OffloadOptions["upload"], variablesText?: string, ): Promise { let offloaded: OffloadedMedia[]; try { offloaded = await offloadHeavyMedia(project.dir, fileMap, { apiBaseUrl: resolveCloudBaseUrl(), upload, entryPath, variablesText, onFile: (item) => (asJson ? console.error : console.log)(c.dim(` ${describeOffload(item, !upload)}`)), }); } catch (err) { reportApiError("Media upload failed", err); } if (!asJson) { for (const item of offloaded.filter((entry) => entry.kept_in_archive)) { console.log( c.dim( ` ${item.path} also stays in the zip: a script builds its path in a way that cannot be rewritten`, ), ); } } return offloaded; } /** --fps, else the entry's root data-fps (the owner local render uses), else the server default. */ export function resolveCloudFpsArg( source: ProjectInputSource, fps: string | undefined, composition: string | undefined, ): string | undefined { if (source.kind !== "dir") return fps; const { dir } = resolveProject(source.dir); const resolved = resolveDefaultFpsArg(fps, dir, resolvePath(dir, "index.html"), composition); // The cloud API takes whole frame rates; a fractional data-fps (29.97) leaves it to the server. return resolved !== undefined && /^\d+$/.test(resolved) ? resolved : fps; } export function assertArchiveFits(sizeBytes: number, largestFiles: ArchiveFileSummary[]): void { if (sizeBytes <= DIRECT_UPLOAD_LIMIT_BYTES) return; errorBox( "Project too large for cloud render", `The zip is ${formatBytes(sizeBytes)} after moving media to HeyGen assets, over the ${formatBytes(DIRECT_UPLOAD_LIMIT_BYTES)} upload limit. Largest files left in it:\n${largestFiles .map((file) => ` ${formatBytes(file.size_bytes).padStart(9)} ${file.path}`) .join("\n")}`, "Exclude files the render does not need with .hyperframesignore.", ); failCommand(); } function describeOffload(item: OffloadedMedia, dryRun: boolean): string { const verb = item.action === "cached" ? "already uploaded" : item.action === "reencode" ? dryRun ? "would re-encode and upload" : "re-encoded and uploaded" : dryRun ? "would upload" : "uploaded"; return `${formatBytes(item.size_bytes).padStart(9)} ${item.path} · ${verb}`; } function reportLargestFiles(prepared: PreparedLocalArchive): void { console.log(c.dim(" Largest included files:")); for (const file of prepared.largestFiles) { console.log(c.dim(` ${formatBytes(file.size_bytes).padStart(9)} ${file.path}`)); } console.log(c.dim(" Exclude verified-unneeded files with .hyperframesignore.")); } function reportDryRun(prepared: PreparedLocalArchive, asJson: boolean): void { const { sizeBytes } = prepared; if (asJson) { console.log( JSON.stringify( withMeta({ archive: { project: prepared.project.name, file_count: prepared.fileCount, size_bytes: sizeBytes, upload_limit_bytes: DIRECT_UPLOAD_LIMIT_BYTES, exceeds_upload_limit: sizeBytes > DIRECT_UPLOAD_LIMIT_BYTES, largest_files: prepared.largestFiles, offloaded_media: prepared.offloaded, }, }), null, 2, ), ); return; } if (sizeBytes < ARCHIVE_DIAGNOSTIC_THRESHOLD_BYTES) reportLargestFiles(prepared); console.log(""); console.log(`${c.success("✓")} Dry run complete — nothing uploaded`); if (sizeBytes > DIRECT_UPLOAD_LIMIT_BYTES) { console.log(c.warn(` Archive exceeds the 200 MB direct-upload limit.`)); } } // fallow-ignore-next-line complexity async function maybeUploadProject( client: HyperframesCloudClient, source: ProjectInputSource, preparedArchive: PreparedLocalArchive | undefined, asJson: boolean, idempotencyKey: string | undefined, ): Promise { 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! } }; } if (!preparedArchive) throw new Error("Local project archive was not prepared"); const { project, archive } = preparedArchive; if (!archive) throw new Error("Local project archive is over the upload limit"); if (!asJson) { console.log(""); console.log(`${c.accent("◆")} Uploading (direct-to-S3)`); } const uploadStart = Date.now(); let uploaded; try { uploaded = await uploadZipViaDirectUpload({ client, bytes: archive.buffer, filename: `${project.name}.zip`, idempotencyKey, onProgress: !asJson ? (ev) => { if (ev.phase === "initialize") { console.log(c.dim(` initializing…`)); } else if (ev.phase === "upload" && ev.percent === 0) { console.log(c.dim(` uploading to S3…`)); } else if (ev.phase === "complete") { console.log(c.dim(` finalizing…`)); } } : undefined, }); } 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; aspectRatio: CreateHyperframesRenderRequest["aspect_ratio"] | undefined; composition: string | undefined; variables: Record | undefined; title: string | undefined; callbackUrl: string | undefined; callbackId: string | undefined; idempotencyKey: string | undefined; reverseSessionId: string | undefined; } type RenderRequestBody = CreateHyperframesRenderRequest & { reverse_session_id?: string }; function reverseSessionIdOf(project: ProjectInputSource): string | undefined { return project.kind === "dir" ? readProjectConfig(project.dir ?? ".")?.reverseSessionId : 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): RenderRequestBody { const body: RenderRequestBody = { 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.aspectRatio !== undefined) body.aspect_ratio = opts.aspectRatio; 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; if (opts.reverseSessionId !== undefined) body.reverse_session_id = opts.reverseSessionId; return body; } // --------------------------------------------------------------------------- // Poll + progress // --------------------------------------------------------------------------- // fallow-ignore-next-line complexity async function pollWithProgress( client: HyperframesCloudClient, renderId: string, asJson: boolean, poll: { intervalMs: number; maxWaitMs: number }, ): Promise { // 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}`, ); failCommand(); } 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, projectDir?: string, ): never { if (asJson) { console.log(JSON.stringify(withMeta({ render: detail }), null, 2)); failCommand(); } const fontUse = projectDir && detail.failure_message ? describeUnresolvedFontUse(detail.failure_message, projectDir) : undefined; errorBox( "Render failed", [detail.failure_message ?? "(no failure_message returned)", fontUse].filter(Boolean).join("\n"), `Inspect: hyperframes cloud get ${detail.render_id}`, ); failCommand(); } 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` creates the parent directory and preserves existing output on failure. 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 = normalizeErrorMessage(err); errorBox( "Download failed", message, "The presigned URL is short-lived; re-fetch with `hyperframes cloud get`.", ); failCommand(); } }