Skip to content

Commit e73304f

Browse files
committed
feat(cli): make cloud archives size-aware
1 parent 43b52f7 commit e73304f

16 files changed

Lines changed: 426 additions & 42 deletions

File tree

‎bun.lock‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/deploy/cloud.mdx‎

Lines changed: 27 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -71,9 +71,9 @@ The credential is **shared with the [`heygen` CLI](https://github.com/heygen-com
7171
```
7272
Your machine HeyGen cloud
7373
┌─────────────────────────┐ ┌─────────────────────────────────┐
74-
│ zip project │ ──POST──▶│ /v3/assets │
75-
│ (excludes .git, │ upload │ → asset_id │
76-
│ node_modules, dist…) │ │ │
74+
│ zip project │ ──PUT───▶│ direct-to-S3 asset upload │
75+
│ (.hyperframesignore + │ upload │ → asset_id │
76+
│ generated outputs) │ │ │
7777
│ │ ──POST──▶│ /v3/hyperframes/renders │
7878
│ │ submit │ → render_id (queued) │
7979
│ │ │ Chromium + FFmpeg render │
@@ -84,12 +84,33 @@ The credential is **shared with the [`heygen` CLI](https://github.com/heygen-com
8484

8585
1. **Resolve the project** — a local directory (default `.`), or skip the upload with `--asset-id` / `--url`.
8686
2. **Auto-detect the aspect ratio** from the entry HTML's `data-width`/`data-height` so you rarely set it by hand.
87-
3. **Zip** the project (same ignore set as `hyperframes publish`).
88-
4. **Upload** the zip to `POST /v3/assets`, yielding an `asset_id`.
87+
3. **Zip** the project (same ignore set as `hyperframes publish`, including `.hyperframesignore`).
88+
4. **Upload** the zip through the direct-to-S3 asset flow, yielding an `asset_id`.
8989
5. **Submit** the render to `POST /v3/hyperframes/renders`.
9090
6. **Poll** `GET /v3/hyperframes/renders/{id}` until it completes or fails (skip with `--no-wait`).
9191
7. **Download** the signed video URL to disk.
9292

93+
## Control archive size
94+
95+
Hosted cloud project uploads are limited to 200 MB. HyperFrames automatically excludes root-level `renders/` and `snapshots/` plus development-only paths such as `.git`, `node_modules`, `dist`, `.next`, `coverage`, and dotfiles.
96+
97+
Use a gitignore-style `.hyperframesignore` at the project root for additional generated or intermediate files that are not needed at render time:
98+
99+
```gitignore
100+
/snapshots2/
101+
/exports/
102+
/assets/source-master.mp4
103+
```
104+
105+
Inspect the exact archive without authenticating, uploading, or starting a render:
106+
107+
```bash
108+
hyperframes cloud render . --dry-run
109+
hyperframes cloud render . --dry-run --json
110+
```
111+
112+
The dry run reports compressed size, file count, and the ten largest included files. Rules also apply to `hyperframes publish`. Avoid broad patterns such as `assets/`: dynamically selected media may not appear as an obvious static HTML reference.
113+
93114
## Render options
94115

95116
The most-used flags — see the [CLI reference](/packages/cli#hyperframes-cloud) for the full list.
@@ -103,6 +124,7 @@ The most-used flags — see the [CLI reference](/packages/cli#hyperframes-cloud)
103124
| `--aspect-ratio` | auto | `16:9`, `9:16`, or `1:1`. Auto-detected from a local project's `data-width`/`data-height`; for `--asset-id`/`--url` it defaults to `16:9` unless set. |
104125
| `--composition` / `-c` | `index.html` | Entry HTML file inside the zip. |
105126
| `--output` / `-o` | `renders/<render_id>.<ext>` | Local destination for the download. |
127+
| `--dry-run` | off | Build and inspect a local project zip without authenticating, uploading, or rendering. |
106128

107129
```bash
108130
# Pick a composition and an output path.

‎docs/packages/cli.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1063,7 +1063,9 @@ hyperframes cloud list # browse recent renders
10631063

10641064
#### `cloud render [<projectDir>]`
10651065

1066-
End-to-end render: zips the project (excluding `.git`, `node_modules`, `dist`, `.next`, `coverage`, dotfiles), uploads it via `POST /v3/assets`, submits `POST /v3/hyperframes/renders`, polls `GET /v3/hyperframes/renders/{id}` until the render completes or fails, and streams the resulting video to disk.
1066+
End-to-end render: zips the project (excluding root `renders`/`snapshots`, `.git`, `node_modules`, `dist`, `.next`, `coverage`, dotfiles, and project `.hyperframesignore` rules), uploads it through the direct-to-S3 asset flow, submits `POST /v3/hyperframes/renders`, polls `GET /v3/hyperframes/renders/{id}` until the render completes or fails, and streams the resulting video to disk.
1067+
1068+
Use `hyperframes cloud render --dry-run` to inspect the compressed size and largest included files without authenticating, uploading, or starting a render. Project-specific `.hyperframesignore` rules use gitignore syntax and also apply to `hyperframes publish`; keep rules narrow because dynamically selected assets may not have obvious static references.
10671069

10681070
Render parameters mirror the local `hyperframes render` UX where they overlap:
10691071

@@ -1080,6 +1082,7 @@ Render parameters mirror the local `hyperframes render` UX where they overlap:
10801082
| `--strict-variables` | off | Fail when variables are undeclared or have the wrong type. |
10811083
| `--title` | — | Free-text label echoed back in detail responses. |
10821084
| `--output` / `-o` | `renders/<render_id>.<ext>` | Local destination for the downloaded video. |
1085+
| `--dry-run` | off | Build and inspect a local project zip without authenticating, uploading, or rendering. |
10831086

10841087
Lifecycle / control flags:
10851088

‎packages/cli/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
"fontkit": "^2.0.4",
4040
"giget": "^3.2.0",
4141
"hono": "^4.0.0",
42+
"ignore": "^5.3.2",
4243
"onnxruntime-node": "1.23.2",
4344
"open": "^10.0.0",
4445
"postcss": "^8.5.8",

‎packages/cli/src/cloud/errors.test.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,20 @@ describe("cloud/errors reportApiError", () => {
5050
);
5151
});
5252

53+
it("points oversized projects to dry-run and .hyperframesignore", () => {
54+
const err = new HyperframesApiError({
55+
status: 413,
56+
message: "project too large",
57+
code: "hyperframes_project_too_large",
58+
});
59+
expect(() => reportApiError("Upload failed", err)).toThrow("process.exit called");
60+
expect(errorBox).toHaveBeenCalledWith(
61+
"Upload failed (HTTP 413)",
62+
"project too large",
63+
"The zip exceeded the 200 MB limit. Run `hyperframes cloud render --dry-run`, then add only verified-unneeded paths to `.hyperframesignore` or pre-host required large media.",
64+
);
65+
});
66+
5367
it("prefers the code-specific hint over a caller suggestion", () => {
5468
const err = new HyperframesApiError({
5569
status: 400,

‎packages/cli/src/cloud/errors.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ import { HyperframesApiError } from "./_gen/client.js";
1919
*/
2020
const ERROR_CODE_HINTS: Record<string, string> = {
2121
hyperframes_project_too_large:
22-
"The zip exceeded the 200 MB limit. Trim large media (or pre-host them and reference by URL), then try again.",
22+
"The zip exceeded the 200 MB limit. Run `hyperframes cloud render --dry-run`, then add only verified-unneeded paths to `.hyperframesignore` or pre-host required large media.",
2323
hyperframes_render_not_found:
2424
"The render_id no longer exists — either soft-deleted or never created.",
2525
invalid_parameter:

‎packages/cli/src/commands/cloud.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import { c } from "../ui/colors.js";
1818
export const examples: Example[] = [
1919
["Render the current directory in the cloud", "hyperframes cloud render"],
2020
["Render a specific project", "hyperframes cloud render ./my-video"],
21+
["Inspect the project zip without uploading", "hyperframes cloud render --dry-run"],
2122
[
2223
"Render at 60fps + high quality, save to a path",
2324
"hyperframes cloud render ./my-video --fps 60 --quality high -o ./out.mp4",

‎packages/cli/src/commands/cloud/render.test.ts‎

Lines changed: 77 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,19 @@
11
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
2-
import { mkdtempSync, writeFileSync } from "node:fs";
3-
import { join } from "node:path";
2+
import { spawnSync } from "node:child_process";
3+
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
4+
import { join, resolve } from "node:path";
45
import { tmpdir } from "node:os";
6+
import { fileURLToPath } from "node:url";
57

68
import {
79
resolveAspectRatioForSubmit,
10+
validateDryRunSource,
811
validateResolutionFormatCombo,
912
type ProjectInputSource,
1013
} from "./render.js";
1114

15+
const cliEntry = resolve(fileURLToPath(import.meta.url), "..", "..", "..", "cli.ts");
16+
1217
// errorBox writes to console; silence it so test output stays clean.
1318
beforeEach(() => {
1419
vi.spyOn(console, "log").mockImplementation(() => undefined);
@@ -51,6 +56,76 @@ describe("validateResolutionFormatCombo", () => {
5156
});
5257
});
5358

59+
describe("validateDryRunSource", () => {
60+
it("accepts a local directory and rejects already-uploaded sources", () => {
61+
const exit = trapExit();
62+
expect(() => validateDryRunSource({ kind: "dir", dir: "." }, true)).not.toThrow();
63+
expect(() => validateDryRunSource({ kind: "asset_id", assetId: "asst_123" }, true)).toThrow(
64+
"process.exit:1",
65+
);
66+
expect(() =>
67+
validateDryRunSource({ kind: "url", url: "https://example.com/project.zip" }, true),
68+
).toThrow("process.exit:1");
69+
expect(exit).toHaveBeenCalledTimes(2);
70+
});
71+
});
72+
73+
describe("cloud render --dry-run", () => {
74+
it("reports the real archive without contacting the cloud", () => {
75+
const dir = writeComposition(1920, 1080);
76+
try {
77+
writeFileSync(
78+
join(dir, "index.html"),
79+
`<!doctype html><html data-composition-variables='[{"id":"title","type":"string","label":"Title","default":"x"}]'><body><div data-composition-id="main" data-width="1920" data-height="1080"></div></body></html>`,
80+
"utf-8",
81+
);
82+
writeFileSync(join(dir, "asset.bin"), "archive-input", "utf-8");
83+
const result = spawnSync(
84+
"bun",
85+
[
86+
"run",
87+
cliEntry,
88+
"cloud",
89+
"render",
90+
dir,
91+
"--dry-run",
92+
"--json",
93+
"--variables",
94+
'{"extra":1}',
95+
],
96+
{
97+
encoding: "utf-8",
98+
timeout: 30_000,
99+
env: {
100+
...process.env,
101+
CI: "1",
102+
HEYGEN_API_URL: "http://127.0.0.1:1",
103+
HYPERFRAMES_NO_UPDATE_CHECK: "1",
104+
},
105+
},
106+
);
107+
108+
expect(result.status).toBe(0);
109+
const payload = JSON.parse(result.stdout) as {
110+
archive: {
111+
file_count: number;
112+
size_bytes: number;
113+
upload_limit_bytes: number;
114+
exceeds_upload_limit: boolean;
115+
largest_files: Array<{ path: string }>;
116+
};
117+
};
118+
expect(payload.archive.file_count).toBe(2);
119+
expect(payload.archive.size_bytes).toBeGreaterThan(0);
120+
expect(payload.archive.upload_limit_bytes).toBe(200 * 1024 * 1024);
121+
expect(payload.archive.exceeds_upload_limit).toBe(false);
122+
expect(payload.archive.largest_files.map((file) => file.path)).toContain("asset.bin");
123+
} finally {
124+
rmSync(dir, { recursive: true, force: true });
125+
}
126+
});
127+
});
128+
54129
describe("resolveAspectRatioForSubmit — non-local sources", () => {
55130
it("trusts an explicit flag for asset_id / url", () => {
56131
trapExit();

0 commit comments

Comments
 (0)