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.

packages/cli/src/utils/publishProject.ts

@@ -0,0 +1,101 @@
+import { basename, join, relative } from "node:path";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import AdmZip from "adm-zip";
+
+const IGNORED_DIRS = new Set([".git", "node_modules", "dist", ".next", "coverage"]);
+const IGNORED_FILES = new Set([".DS_Store", "Thumbs.db"]);
+
+export interface PublishArchiveResult {
+  buffer: Buffer;
+  fileCount: number;
+}
+
+export interface PublishedProjectResponse {
+  projectId: string;
+  title: string;
+  fileCount: number;
+  url: string;
+  claimToken: string;
+}
+
+function shouldIgnoreSegment(segment: string): boolean {
+  return segment.startsWith(".") || IGNORED_DIRS.has(segment) || IGNORED_FILES.has(segment);
+}
+
+function collectProjectFiles(rootDir: string, currentDir: string, paths: string[]): void {
+  for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+    if (shouldIgnoreSegment(entry.name)) continue;
+    const absolutePath = join(currentDir, entry.name);
+    const relativePath = relative(rootDir, absolutePath).replaceAll("\\", "/");
+    if (!relativePath) continue;
+
+    if (entry.isDirectory()) {
+      collectProjectFiles(rootDir, absolutePath, paths);
+      continue;
+    }
+
+    if (!statSync(absolutePath).isFile()) continue;
+    paths.push(relativePath);
+  }
+}
+
+export function createPublishArchive(projectDir: string): PublishArchiveResult {
+  const filePaths: string[] = [];
+  collectProjectFiles(projectDir, projectDir, filePaths);
+  if (!filePaths.includes("index.html")) {
+    throw new Error("Project must include an index.html file at the root before publish.");
+  }
+
+  const archive = new AdmZip();
+  for (const filePath of filePaths) {
+    archive.addFile(filePath, readFileSync(join(projectDir, filePath)));
+  }
+
+  return {
+    buffer: archive.toBuffer(),
+    fileCount: filePaths.length,
+  };
+}
+
+export function getPublishApiBaseUrl(): string {
+  return (
+    process.env["HYPERFRAMES_PUBLISHED_PROJECTS_API_URL"] ||
+    process.env["HEYGEN_API_URL"] ||
+    "https://api2.heygen.com"
+  ).replace(/\/$/, "");
+}
+
+export async function publishProjectArchive(projectDir: string): Promise<PublishedProjectResponse> {
+  const title = basename(projectDir);
+  const archive = createPublishArchive(projectDir);
+  const archiveBytes = new Uint8Array(archive.buffer.byteLength);
+  archiveBytes.set(archive.buffer);
+  const body = new FormData();
+  body.set("title", title);
+  body.set("file", new File([archiveBytes], `${title}.zip`, { type: "application/zip" }));
+  const headers: Record<string, string> = {
+    heygen_route: "canary",
+  };
+
+  const response = await fetch(`${getPublishApiBaseUrl()}/v1/hyperframes/projects/publish`, {
+    method: "POST",
+    body,
+    headers,
+    signal: AbortSignal.timeout(30_000),
+  });
+
+  const payload = await response.json().catch(() => null);
+  const message =
+    typeof payload?.message === "string" ? payload.message : "Failed to publish project";
+  if (!response.ok || !payload?.data) {
+    throw new Error(message);
+  }
+
+  return {
+    projectId: String(payload.data.project_id),
+    title: String(payload.data.title),
+    fileCount: Number(payload.data.file_count),
+    url: String(payload.data.url),
+    claimToken: String(payload.data.claim_token),
+  };
+}