Skip to content

Commit b4e9d64

Browse files
feat(cli): hyperframes publish — share projects via a public URL (#312)
## Summary This PR adds `hyperframes publish` as the OSS handoff into the persisted HyperFrames publish flow. Instead of opening a local tunnel, the CLI now: 1. zips the local project 2. uploads it to the HeyGen publish backend 3. gets back a stable `hyperframes.dev` project URL plus claim token 4. prints a claimable URL for the user Example output: ```bash $ hyperframes publish Project my-video Files 12 Public https://hyperframes.dev/p/hfp_123?claim_token=... Open the URL on hyperframes.dev to claim the project and continue editing. ``` ## User Flow The intended user flow is: 1. Run `hyperframes publish` from a local HyperFrames project. 2. The CLI uploads the project as a zip to the publish API. 3. The CLI prints a stable `hyperframes.dev` URL with the claim token attached. 4. The user opens that URL in the browser. 5. `hyperframes.dev` uses that URL to claim the published project and import it into the web app. 6. The user continues editing from a normal web session. So the CLI is only responsible for packaging, upload, and printing the URL. The browser-side claim/import flow lives in the backend and web app stack. ## Routing This PR does not expose a separate user-facing canary mode. The CLI posts to the normal publish API host: - `https://api2.heygen.com/v1/hyperframes/projects/publish` Backend routing behavior is handled server-side. If the default path routes through canary, it does so without a dedicated CLI flag; if that path is unavailable, traffic falls back to prod behavior on the backend side. ## What Changed | File | Role | |---|---| | `packages/cli/src/commands/publish.ts` | Adds the `hyperframes publish` command, confirmation prompt, lint-before-upload behavior, and user-facing output. | | `packages/cli/src/utils/publishProject.ts` | Zips the local project, filters ignored files/directories, posts the archive to the publish API, and returns the published project metadata. | | `packages/cli/src/utils/publishProject.test.ts` | Covers archive creation and successful upload response parsing. | | `packages/cli/src/cli.ts` | Registers the new `publish` command. | | `packages/cli/src/help.ts` | Adds `publish` to root help and examples. | | `docs/packages/cli.mdx` | Documents the persisted publish flow. | ## Important Behavior - Requires `index.html` at the project root. - Ignores hidden files and common non-project directories like `.git`, `node_modules`, `dist`, `.next`, and `coverage`. - Lints the project before upload and prints findings, but does not block publish on warnings. - Does **not** keep a local process alive after upload. - Does **not** open a public tunnel. - Does **not** require HeyGen OAuth inside the CLI. ## Why This Shape This keeps the OSS CLI simple and matches the current product direction: - project persistence lives in HeyGen's backend - the public URL comes from the persisted project row - claiming/importing happens on `hyperframes.dev` - the CLI should not own browser auth or long-lived sharing infrastructure ## Verification In the earlier PR worktree, this flow was verified locally with the CLI build/test path and with real backend integration. In this cleanup worktree, the narrow code/doc change was verified by inspection, but the repo-level commands are currently blocked here by missing local tool binaries and typings in the worktree environment: - `bun run --filter @hyperframes/cli test` -> `vitest: command not found` - `bun run --filter @hyperframes/cli typecheck` -> local dependency/type resolution failures outside this diff - `bun run --filter @hyperframes/cli build` -> `tsx: command not found` ## Notes This PR only covers the OSS CLI side of the flow. The full end-to-end experience depends on the corresponding backend and `hyperframes.dev` changes that store published projects, return the stable URL, and support claim/import in the web app.
1 parent 64779a0 commit b4e9d64

6 files changed

Lines changed: 308 additions & 0 deletions

File tree

docs/packages/cli.mdx

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -394,6 +394,25 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
394394
2. **Local studio mode** — if `@hyperframes/studio` is installed in your project's `node_modules`, spawns Vite with full HMR for faster iteration.
395395
3. **Monorepo mode** — if running from the Hyperframes source repo, spawns the studio dev server directly.
396396

397+
### `publish`
398+
399+
Upload the project and get back a stable `hyperframes.dev` URL:
400+
401+
```bash
402+
npx hyperframes publish [dir]
403+
npx hyperframes publish --yes
404+
```
405+
406+
| Flag | Description |
407+
|------|-------------|
408+
| `--yes` | Skip the confirmation prompt |
409+
410+
`publish` zips the current project, uploads it to the HyperFrames publish backend, and prints a stable `hyperframes.dev` URL for that stored project.
411+
412+
The printed URL already includes the claim token, so opening it on `hyperframes.dev` lets the intended user claim the uploaded project and continue editing in the web app.
413+
414+
This flow does not keep a local preview server alive and does not open a tunnel. The published URL resolves to the persisted project stored by HeyGen, so it keeps working after the CLI process exits.
415+
397416
### `lint`
398417

399418
Check a composition for common issues:

packages/cli/src/cli.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ const subCommands = {
2929
catalog: () => import("./commands/catalog.js").then((m) => m.default),
3030
play: () => import("./commands/play.js").then((m) => m.default),
3131
preview: () => import("./commands/preview.js").then((m) => m.default),
32+
publish: () => import("./commands/publish.js").then((m) => m.default),
3233
render: () => import("./commands/render.js").then((m) => m.default),
3334
lint: () => import("./commands/lint.js").then((m) => m.default),
3435
info: () => import("./commands/info.js").then((m) => m.default),
Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
import { basename, resolve } from "node:path";
2+
import { existsSync } from "node:fs";
3+
import { join } from "node:path";
4+
import { defineCommand } from "citty";
5+
import * as clack from "@clack/prompts";
6+
7+
import type { Example } from "./_examples.js";
8+
import { c } from "../ui/colors.js";
9+
import { lintProject } from "../utils/lintProject.js";
10+
import { formatLintFindings } from "../utils/lintFormat.js";
11+
import { publishProjectArchive } from "../utils/publishProject.js";
12+
13+
export const examples: Example[] = [
14+
["Publish the current project with a public URL", "hyperframes publish"],
15+
["Publish a specific directory", "hyperframes publish ./my-video"],
16+
["Skip the consent prompt (scripts)", "hyperframes publish --yes"],
17+
];
18+
19+
export default defineCommand({
20+
meta: {
21+
name: "publish",
22+
description: "Upload the project and return a stable public URL",
23+
},
24+
args: {
25+
dir: { type: "positional", description: "Project directory", required: false },
26+
yes: {
27+
type: "boolean",
28+
alias: "y",
29+
description: "Skip the publish confirmation prompt",
30+
default: false,
31+
},
32+
},
33+
async run({ args }) {
34+
const rawArg = args.dir;
35+
const dir = resolve(rawArg ?? ".");
36+
const isImplicitCwd = !rawArg || rawArg === "." || rawArg === "./";
37+
const projectName = isImplicitCwd ? basename(process.env["PWD"] ?? dir) : basename(dir);
38+
39+
const indexPath = join(dir, "index.html");
40+
if (existsSync(indexPath)) {
41+
const lintResult = lintProject({ dir, name: projectName, indexPath });
42+
if (lintResult.totalErrors > 0 || lintResult.totalWarnings > 0) {
43+
console.log();
44+
for (const line of formatLintFindings(lintResult)) console.log(line);
45+
console.log();
46+
}
47+
}
48+
49+
if (args.yes !== true) {
50+
console.log();
51+
console.log(
52+
` ${c.bold("hyperframes publish uploads this project and creates a stable public URL.")}`,
53+
);
54+
console.log(
55+
` ${c.dim("Anyone with the URL can open the published project and claim it after authenticating.")}`,
56+
);
57+
console.log();
58+
const approved = await clack.confirm({ message: "Publish this project?" });
59+
if (clack.isCancel(approved) || approved !== true) {
60+
console.log();
61+
console.log(` ${c.dim("Aborted.")}`);
62+
console.log();
63+
return;
64+
}
65+
}
66+
67+
clack.intro(c.bold("hyperframes publish"));
68+
const publishSpinner = clack.spinner();
69+
publishSpinner.start("Uploading project...");
70+
71+
try {
72+
const published = await publishProjectArchive(dir);
73+
const claimUrl = new URL(published.url);
74+
claimUrl.searchParams.set("claim_token", published.claimToken);
75+
publishSpinner.stop(c.success("Project published"));
76+
77+
console.log();
78+
console.log(` ${c.dim("Project")} ${c.accent(published.title)}`);
79+
console.log(` ${c.dim("Files")} ${String(published.fileCount)}`);
80+
console.log(` ${c.dim("Public")} ${c.accent(claimUrl.toString())}`);
81+
console.log();
82+
console.log(
83+
` ${c.dim("Open the URL on hyperframes.dev to claim the project and continue editing.")}`,
84+
);
85+
console.log();
86+
return;
87+
} catch (err: unknown) {
88+
publishSpinner.stop(c.error("Publish failed"));
89+
console.error();
90+
console.error(` ${(err as Error).message}`);
91+
console.error();
92+
process.exitCode = 1;
93+
return;
94+
}
95+
},
96+
});

packages/cli/src/help.ts

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ const GROUPS: Group[] = [
2424
["capture", "Capture a website for video production"],
2525
["catalog", "Browse and install blocks and components"],
2626
["preview", "Start the studio for previewing compositions"],
27+
["publish", "Upload a project and get a stable public URL"],
2728
["render", "Render a composition to MP4 or WebM"],
2829
],
2930
},
@@ -72,6 +73,7 @@ import type { Example } from "./commands/_examples.js";
7273
const ROOT_EXAMPLES: Example[] = [
7374
["Create a new project", "hyperframes init my-video"],
7475
["Start the live preview studio", "hyperframes preview"],
76+
["Publish to hyperframes.dev", "hyperframes publish"],
7577
["Render to MP4", "hyperframes render -o out.mp4"],
7678
["Transparent WebM overlay", "hyperframes render --format webm -o out.webm"],
7779
["Validate your composition", "hyperframes lint"],
Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
2+
import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
3+
import { tmpdir } from "node:os";
4+
import { join } from "node:path";
5+
6+
import {
7+
createPublishArchive,
8+
getPublishApiBaseUrl,
9+
publishProjectArchive,
10+
} from "./publishProject.js";
11+
12+
function makeProjectDir(): string {
13+
return mkdtempSync(join(tmpdir(), "hf-publish-"));
14+
}
15+
16+
describe("createPublishArchive", () => {
17+
it("packages the project and skips hidden files and node_modules", () => {
18+
const dir = makeProjectDir();
19+
try {
20+
writeFileSync(join(dir, "index.html"), "<html></html>", "utf-8");
21+
mkdirSync(join(dir, "assets"));
22+
writeFileSync(join(dir, "assets/logo.svg"), "<svg />", "utf-8");
23+
mkdirSync(join(dir, ".git"));
24+
writeFileSync(join(dir, ".env"), "SECRET=1", "utf-8");
25+
mkdirSync(join(dir, "node_modules"));
26+
writeFileSync(join(dir, "node_modules/ignored.js"), "console.log('ignore')", "utf-8");
27+
28+
const archive = createPublishArchive(dir);
29+
30+
expect(archive.fileCount).toBe(2);
31+
expect(archive.buffer.byteLength).toBeGreaterThan(0);
32+
} finally {
33+
rmSync(dir, { recursive: true, force: true });
34+
}
35+
});
36+
});
37+
38+
describe("publishProjectArchive", () => {
39+
beforeEach(() => {
40+
vi.stubGlobal(
41+
"fetch",
42+
vi.fn().mockResolvedValue(
43+
new Response(
44+
JSON.stringify({
45+
data: {
46+
project_id: "hfp_123",
47+
title: "demo",
48+
file_count: 2,
49+
url: "https://hyperframes.dev/p/hfp_123",
50+
claim_token: "claim-token",
51+
},
52+
}),
53+
{ status: 200 },
54+
),
55+
),
56+
);
57+
});
58+
59+
afterEach(() => {
60+
vi.unstubAllGlobals();
61+
});
62+
63+
it("uploads the archive and returns the stable project URL", async () => {
64+
const dir = makeProjectDir();
65+
try {
66+
writeFileSync(join(dir, "index.html"), "<html></html>", "utf-8");
67+
writeFileSync(join(dir, "styles.css"), "body {}", "utf-8");
68+
69+
const result = await publishProjectArchive(dir);
70+
71+
expect(getPublishApiBaseUrl()).toBe("https://api2.heygen.com");
72+
expect(result).toMatchObject({
73+
projectId: "hfp_123",
74+
url: "https://hyperframes.dev/p/hfp_123",
75+
});
76+
expect(fetch).toHaveBeenCalledTimes(1);
77+
expect(fetch).toHaveBeenCalledWith(
78+
"https://api2.heygen.com/v1/hyperframes/projects/publish",
79+
expect.objectContaining({
80+
method: "POST",
81+
headers: { heygen_route: "canary" },
82+
signal: expect.any(AbortSignal),
83+
}),
84+
);
85+
} finally {
86+
rmSync(dir, { recursive: true, force: true });
87+
}
88+
});
89+
});
Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
import { basename, join, relative } from "node:path";
2+
import { readdirSync, readFileSync, statSync } from "node:fs";
3+
import AdmZip from "adm-zip";
4+
5+
const IGNORED_DIRS = new Set([".git", "node_modules", "dist", ".next", "coverage"]);
6+
const IGNORED_FILES = new Set([".DS_Store", "Thumbs.db"]);
7+
8+
export interface PublishArchiveResult {
9+
buffer: Buffer;
10+
fileCount: number;
11+
}
12+
13+
export interface PublishedProjectResponse {
14+
projectId: string;
15+
title: string;
16+
fileCount: number;
17+
url: string;
18+
claimToken: string;
19+
}
20+
21+
function shouldIgnoreSegment(segment: string): boolean {
22+
return segment.startsWith(".") || IGNORED_DIRS.has(segment) || IGNORED_FILES.has(segment);
23+
}
24+
25+
function collectProjectFiles(rootDir: string, currentDir: string, paths: string[]): void {
26+
for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
27+
if (shouldIgnoreSegment(entry.name)) continue;
28+
const absolutePath = join(currentDir, entry.name);
29+
const relativePath = relative(rootDir, absolutePath).replaceAll("\\", "/");
30+
if (!relativePath) continue;
31+
32+
if (entry.isDirectory()) {
33+
collectProjectFiles(rootDir, absolutePath, paths);
34+
continue;
35+
}
36+
37+
if (!statSync(absolutePath).isFile()) continue;
38+
paths.push(relativePath);
39+
}
40+
}
41+
42+
export function createPublishArchive(projectDir: string): PublishArchiveResult {
43+
const filePaths: string[] = [];
44+
collectProjectFiles(projectDir, projectDir, filePaths);
45+
if (!filePaths.includes("index.html")) {
46+
throw new Error("Project must include an index.html file at the root before publish.");
47+
}
48+
49+
const archive = new AdmZip();
50+
for (const filePath of filePaths) {
51+
archive.addFile(filePath, readFileSync(join(projectDir, filePath)));
52+
}
53+
54+
return {
55+
buffer: archive.toBuffer(),
56+
fileCount: filePaths.length,
57+
};
58+
}
59+
60+
export function getPublishApiBaseUrl(): string {
61+
return (
62+
process.env["HYPERFRAMES_PUBLISHED_PROJECTS_API_URL"] ||
63+
process.env["HEYGEN_API_URL"] ||
64+
"https://api2.heygen.com"
65+
).replace(/\/$/, "");
66+
}
67+
68+
export async function publishProjectArchive(projectDir: string): Promise<PublishedProjectResponse> {
69+
const title = basename(projectDir);
70+
const archive = createPublishArchive(projectDir);
71+
const archiveBytes = new Uint8Array(archive.buffer.byteLength);
72+
archiveBytes.set(archive.buffer);
73+
const body = new FormData();
74+
body.set("title", title);
75+
body.set("file", new File([archiveBytes], `${title}.zip`, { type: "application/zip" }));
76+
const headers: Record<string, string> = {
77+
heygen_route: "canary",
78+
};
79+
80+
const response = await fetch(`${getPublishApiBaseUrl()}/v1/hyperframes/projects/publish`, {
81+
method: "POST",
82+
body,
83+
headers,
84+
signal: AbortSignal.timeout(30_000),
85+
});
86+
87+
const payload = await response.json().catch(() => null);
88+
const message =
89+
typeof payload?.message === "string" ? payload.message : "Failed to publish project";
90+
if (!response.ok || !payload?.data) {
91+
throw new Error(message);
92+
}
93+
94+
return {
95+
projectId: String(payload.data.project_id),
96+
title: String(payload.data.title),
97+
fileCount: Number(payload.data.file_count),
98+
url: String(payload.data.url),
99+
claimToken: String(payload.data.claim_token),
100+
};
101+
}

0 commit comments

Comments
 (0)