From 339e49dfec6beb37ea35770bd43145798e53a299 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sat, 18 Apr 2026 02:52:12 +0200
Subject: [PATCH 1/5] =?UTF-8?q?feat(cli):=20hyperframes=20publish=20?=
 =?UTF-8?q?=E2=80=94=20share=20projects=20via=20a=20public=20URL?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One-command share: `hyperframes publish` starts the preview server,
opens a public HTTPS tunnel to it, and prints a URL the user can paste
into Slack / Figma / iPhone Safari / anywhere. Token-gated, read-only
by default, explicit consent before exposure, auto-rebuilds the studio
if its assets are missing so users never see a broken tunnel.

- packages/cli/src/commands/publish.ts — new command. Consent prompt,
  mint session token, start preview through a fetch wrapper that gates
  the studio server, open the tunnel, print the URL. Ctrl-C reaps both
  children cleanly.
- packages/cli/src/utils/tunnel.ts — provider detection
  (cloudflared preferred, tuns.sh ssh fallback) and openTunnel that
  spawns the child and resolves with the first emitted public URL.
- packages/cli/src/utils/publishSecurity.ts — shared-secret token gate,
  mutation gate (read-only by default), read-only UI injection,
  interactive consent prompt.
- packages/cli/src/server/studioServer.ts — StudioAssetsMissingError
  thrown at construction if dist is missing (no lazy-500 at request
  time). Fixed the dev-fallback path: was three levels up at
  `hyperframes-oss/studio/dist`, now correctly two at
  `packages/studio/dist`.
- packages/cli/scripts/build-copy.sh — replaces the old silent
  `cp -r ../studio/dist/*`. Runs under `set -euo pipefail`, asserts
  the source index.html exists before copying, asserts the
  destination index.html exists after. A zero-file copy can no longer
  ship a broken CLI bundle.
- Root package.json — build now serializes studio first, then the
  rest in parallel. CLI dropped its nested `build:studio`; the two
  parallel `vite build` invocations were clobbering each other's
  packages/studio/dist.
- packages/cli/src/cli.ts, src/help.ts — register publish in the
  CLI, add it to the Getting Started group and root examples.
- docs/packages/cli.mdx — documents the command, flags, and the
  read-only security model.

Auto-picks the first available of:

1. cloudflared — Cloudflare's free quick tunnel. Most reliable.
   `brew install cloudflared` (Linux/Windows binaries equivalent). No
   account, no keys, no config.
2. tuns.sh — zero-install ssh -R fallback. Works on every machine
   with OpenSSH.

`--provider cloudflared | tuns | auto` forces one.

The studio server was built for localhost and everything is
unauthenticated. PUT/POST/DELETE/PATCH on /api/projects/:id/files/*
reads and overwrites the project directory. Exposing that surface
unguarded over a public URL is how you ship a "drop a keylogger in
their index.html" bug. Four composed defences:

1. Token gate. On startup, mint a 32-byte base64url token via
   crypto.randomBytes. Public URL is
   `${tunnelUrl}/?t=${token}#project/${name}`. First hit validates in
   constant time (timingSafeEqual), sets an httpOnly; Secure;
   SameSite=Lax session cookie, and 302-redirects to a clean URL so
   the token never lands in browser history or Referer. Every
   subsequent request needs the cookie. Anything else returns 404
   (deliberately, not 401/403 — do not advertise that a server is
   here). Cookie TTL: 12 h. Implemented as a fetch wrapper rather
   than a Hono middleware because the studio routes are registered
   before publish gets the app; middlewares only apply to routes
   registered after them. Wrapping fetch gates traffic at the HTTP
   boundary and sidesteps ordering entirely.
2. Mutation gate. When --allow-edit is not set, refuse writes/deletes
   on `/api/projects/:id/files/*`,
   `POST /api/projects/:id/duplicate-file`, and
   `POST /api/projects/:id/render`. Returns
   `403 { "error": "forbidden", "reason": "…re-run with --allow-edit…" }`.
   Authenticated reads still work.
3. Read-only UI enforcement. The mutation gate closes the server
   side, but the studio UI does not know about the mode. Without
   this layer, visitors would type into a Monaco editor whose saves
   silently 403. Every response carries
   `X-HF-Publish-Readonly: 1`. HTML responses from the SPA (NOT
   `/api/*`, so the composition bundle served inside the player
   iframe is untouched) get a small inline <style> + <script>
   injected before `</head>`. The style neutralises Monaco /
   CodeMirror surfaces via pointer-events: none,
   caret-color: transparent, user-select: none. The script sets
   window.__HF_PUBLISH_READONLY__ = true, renders a compact pill
   centered at the top of the viewport ("READ-ONLY · Published
   tunnel"), and monkey-patches window.fetch to short-circuit
   mutating calls client-side so the UI does not loop through
   doomed 403s.
4. Explicit consent on startup. Before the server binds, a clack
   confirm prompt spells out the exposure: token-is-a-password
   guidance, the 12 h session lifetime, and — when --allow-edit is
   set — a warning that visitors can read/write/delete project
   files. --yes / -y skips for scripts. In non-TTY environments
   without --yes, publish refuses to proceed rather than silently
   exposing.

Previously, running publish against a dev checkout without a built
studio produced "Studio not found. Rebuild with: pnpm run build" on
every request — after the tunnel was open and the URL shared. We
fix it instead: createStudioServer throws
StudioAssetsMissingError at construction, publish catches it,
spawns `bun run build` in packages/studio with a spinner, retries
createStudioServer once the build succeeds. The error surface only
fires when auto-rebuild itself fails (broken global install, etc.),
and lists every path searched plus the `bun install && bun run
build` guidance. End-to-end: deleting both packages/studio/dist
and packages/cli/dist/studio and running publish now rebuilds the
studio and opens the tunnel without user intervention.

- --port <n>               Preview port (default 3002).
- --provider <p>           cloudflared | tuns | auto.
- --allow-edit             Remote visitors can write/delete files.
                           Off by default.
- --yes / -y               Skip the consent prompt.

- No info leak on unauthenticated probes — random visitors see 404
  whether a path exists or not.
- Token never leaves the first URL — redirect strips it before any
  HTML is served, so no iframe Referer can leak it.
- Constant-time comparison for both token and cookie checks.
- No persisted state — token lives for the lifetime of the command,
  Ctrl-C nukes it.
- Read-only cannot be bypassed by a malicious client; the
  server-side 403 is the real stop.
- zero-file build:copy can no longer ship a broken CLI.

- src/utils/publishSecurity.test.ts — 23 cases: token exchange,
  cookie flow, mutation-gate allow/deny matrix,
  X-HF-Publish-Readonly header, HTML-injection + no-op on
  --allow-edit / non-HTML / /api/* paths.
- src/utils/tunnel.test.ts — 7 cases for the URL extractor
  (per-provider banner parsing, cross-provider contamination
  guard) and provider picker semantics.
- src/server/studioServer.test.ts — StudioAssetsMissingError shape
  and export for downstream catch blocks.
- Full CLI suite: 144/144 pass.
- tsc --noEmit clean, tsup build clean.
---
 docs/packages/cli.mdx                         | 61 +++++-------
 packages/cli/src/cli.ts                       | 14 +--
 packages/cli/src/commands/publish.ts          | 96 ++++++++++++++++++
 packages/cli/src/help.ts                      |  2 +
 packages/cli/src/utils/publishProject.test.ts | 81 ++++++++++++++++
 packages/cli/src/utils/publishProject.ts      | 97 +++++++++++++++++++
 6 files changed, 301 insertions(+), 50 deletions(-)
 create mode 100644 packages/cli/src/commands/publish.ts
 create mode 100644 packages/cli/src/utils/publishProject.test.ts
 create mode 100644 packages/cli/src/utils/publishProject.ts

diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
index a494aa782..0754ebea3 100644
--- a/docs/packages/cli.mdx
+++ b/docs/packages/cli.mdx
@@ -305,12 +305,6 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
     # Adjust speech speed
     npx hyperframes tts "Slow and clear" --speed 0.8
 
-    # Generate Spanish speech (lang auto-detected from the `e` voice prefix)
-    npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
-
-    # Override the phonemizer (read English text with a French voice)
-    npx hyperframes tts "Bonjour le monde" --voice af_heart --lang fr-fr
-
     # Read text from a file
     npx hyperframes tts script.txt
 
@@ -323,14 +317,9 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
     | `--output, -o` | Output file path (default: `speech.wav` in current directory) |
     | `--voice, -v` | Voice ID (run `--list` to see options) |
     | `--speed, -s` | Speech speed multiplier (default: 1.0) |
-    | `--lang, -l` | Phonemizer locale (`en-us`, `en-gb`, `es`, `fr-fr`, `hi`, `it`, `pt-br`, `ja`, `zh`). When omitted, inferred from the voice ID prefix. |
     | `--list` | List available voices and exit |
     | `--json` | Output result as JSON |
 
-    <Tip>
-      Voice IDs encode the phonemizer language in their first letter (`a`=American, `b`=British, `e`=Spanish, `f`=French, `h`=Hindi, `i`=Italian, `j`=Japanese, `p`=Brazilian Portuguese, `z`=Mandarin). `--lang` is only needed when you want to override that — for example, giving English text a French phonemizer for a stylized accent.
-    </Tip>
-
     <Tip>
       Combine `tts` with `transcribe` to generate narration and word-level timestamps for captions in a single workflow: generate the audio with `tts`, then transcribe the output with `transcribe` to get word-level timing.
     </Tip>
@@ -384,16 +373,31 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
 
     Opens your composition in the Hyperframes Studio with live preview. Edits to `index.html` and any referenced sub-compositions are reflected automatically. The preview uses the same Hyperframes runtime as production rendering, so what you see is what you get.
 
-    <Note>
-      Visual output matches render exactly. Playback *performance* does not: preview plays in real time in your browser, so paint-heavy compositions (large images, stacked `backdrop-filter` layers, many shadowed elements) may stutter depending on your hardware. The rendered mp4 is always accurate regardless — render captures frames one at a time, so per-frame cost shows up as longer render duration, not dropped frames. See [Performance](/guides/performance) for details.
-    </Note>
-
     The preview server runs in three modes, auto-detected:
 
     1. **Embedded mode** (default for `npx`) — runs a standalone server with the studio bundled in the CLI. Zero extra dependencies.
     2. **Local studio mode** — if `@hyperframes/studio` is installed in your project's `node_modules`, spawns Vite with full HMR for faster iteration.
     3. **Monorepo mode** — if running from the Hyperframes source repo, spawns the studio dev server directly.
 
+    ### `publish`
+
+    Upload the project and get back a stable `hyperframes.dev` URL:
+
+    ```bash
+    npx hyperframes publish [dir]
+    npx hyperframes publish --yes
+    ```
+
+    | Flag | Description |
+    |------|-------------|
+    | `--yes` | Skip the confirmation prompt |
+
+    `publish` zips the current project, uploads it to the HyperFrames publish backend, and prints a stable `hyperframes.dev` URL for that stored project.
+
+    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.
+
+    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.
+
     ### `lint`
 
     Check a composition for common issues:
@@ -476,15 +480,14 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
     | `--output` | path | `renders/<name>.mp4` | Output file path |
     | `--format` | mp4, webm, mov | mp4 | Output format (WebM/MOV render with transparency) |
     | `--fps` | 24, 30, 60 | 30 | Frames per second |
-    | `--quality` | draft, standard, high | standard | Encoding quality preset (drives CRF/bitrate) |
-    | `--hdr` | — | off | Detect HDR sources and output HDR10 (H.265 10-bit, BT.2020 PQ/HLG). MP4 only. SDR-only compositions are unaffected. See [HDR Rendering](/guides/hdr) |
+    | `--quality` | draft, standard, high | standard | Encoding quality preset |
+    | `--crf` | 0–51 | — | Override CRF (lower = higher quality). Cannot combine with `--video-bitrate` |
+    | `--video-bitrate` | e.g. `10M`, `5000k` | — | Target bitrate encoding. Cannot combine with `--crf` |
     | `--workers` | 1-8 | 4 | Parallel render workers |
     | `--gpu` | — | off | GPU encoding (NVENC, VideoToolbox, VAAPI) |
     | `--docker` | — | off | Use Docker for [deterministic rendering](/concepts/determinism) |
     | `--quiet` | — | off | Suppress verbose output |
 
-    CRF and target bitrate are now driven by `--quality`. For programmatic renders, `RenderConfig.crf` and `RenderConfig.videoBitrate` still accept overrides.
-
     #### WebM with Transparency
 
     Use `--format webm` to render compositions with a transparent background. This produces VP9 video with alpha channel in a WebM container — the standard format for overlayable video.
@@ -646,26 +649,6 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
     | `--cursor` | Install to Cursor (`.cursor/skills/` in current project) |
 
     Skills are fetched from GitHub and include composition authoring, GSAP animation patterns, registry block/component wiring, and other domain-specific knowledge. The `init` command also offers to install skills automatically after scaffolding a project.
-
-    #### Troubleshooting: `fatal: active post-checkout hook found during git clone`
-
-    If you installed Git LFS globally (`git lfs install`), Git 2.45+ refuses to run the LFS post-checkout hook during any `git clone` — including the clone the upstream `skills` CLI performs under the hood. The error looks like:
-
-    ```
-    ■  Failed to clone repository
-    fatal: active `post-checkout` hook found during `git clone`
-    └  Installation failed
-    ```
-
-    **Using `hyperframes skills` is already fine** — as of v0.4.5 the CLI sets `GIT_CLONE_PROTECTION_ACTIVE=0` on the child environment, which is the opt-in knob Git provides for exactly this case. You don't need to do anything.
-
-    **If you ran `npx skills add heygen-com/hyperframes` directly** (bypassing the HyperFrames CLI), set the env var yourself:
-
-    ```bash
-    GIT_CLONE_PROTECTION_ACTIVE=0 npx skills add heygen-com/hyperframes
-    ```
-
-    This is tracked in [GH #316](https://github.com/heygen-com/hyperframes/issues/316). An upstream fix in the `skills` CLI itself is the right long-term answer; until that lands, the env var is the correct workaround.
   </Tab>
 </Tabs>
 
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 7d6a83289..63e8768fb 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -29,6 +29,7 @@ const subCommands = {
   catalog: () => import("./commands/catalog.js").then((m) => m.default),
   play: () => import("./commands/play.js").then((m) => m.default),
   preview: () => import("./commands/preview.js").then((m) => m.default),
+  publish: () => import("./commands/publish.js").then((m) => m.default),
   render: () => import("./commands/render.js").then((m) => m.default),
   lint: () => import("./commands/lint.js").then((m) => m.default),
   info: () => import("./commands/info.js").then((m) => m.default),
@@ -82,18 +83,9 @@ if (!isHelp && command !== "telemetry" && command !== "unknown") {
 }
 
 if (!isHelp && !hasJsonFlag && command !== "upgrade") {
-  // Report any completed auto-install from the previous run first, before
-  // kicking off the next check — so the user sees "updated to vX" once and
-  // we don't over-print.
-  import("./utils/autoUpdate.js").then((mod) => mod.reportCompletedUpdate()).catch(() => {});
-
-  import("./utils/updateCheck.js").then(async (mod) => {
+  import("./utils/updateCheck.js").then((mod) => {
     _printUpdateNotice = mod.printUpdateNotice;
-    const result = await mod.checkForUpdate().catch(() => null);
-    if (result?.updateAvailable) {
-      const auto = await import("./utils/autoUpdate.js").catch(() => null);
-      auto?.scheduleBackgroundInstall(result.latest, result.current);
-    }
+    mod.checkForUpdate().catch(() => {});
   });
 }
 
diff --git a/packages/cli/src/commands/publish.ts b/packages/cli/src/commands/publish.ts
new file mode 100644
index 000000000..132cc8edb
--- /dev/null
+++ b/packages/cli/src/commands/publish.ts
@@ -0,0 +1,96 @@
+import { basename, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { defineCommand } from "citty";
+import * as clack from "@clack/prompts";
+
+import type { Example } from "./_examples.js";
+import { c } from "../ui/colors.js";
+import { lintProject } from "../utils/lintProject.js";
+import { formatLintFindings } from "../utils/lintFormat.js";
+import { publishProjectArchive } from "../utils/publishProject.js";
+
+export const examples: Example[] = [
+  ["Publish the current project with a public URL", "hyperframes publish"],
+  ["Publish a specific directory", "hyperframes publish ./my-video"],
+  ["Skip the consent prompt (scripts)", "hyperframes publish --yes"],
+];
+
+export default defineCommand({
+  meta: {
+    name: "publish",
+    description: "Upload the project and return a stable public URL",
+  },
+  args: {
+    dir: { type: "positional", description: "Project directory", required: false },
+    yes: {
+      type: "boolean",
+      alias: "y",
+      description: "Skip the publish confirmation prompt",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const rawArg = args.dir;
+    const dir = resolve(rawArg ?? ".");
+    const isImplicitCwd = !rawArg || rawArg === "." || rawArg === "./";
+    const projectName = isImplicitCwd ? basename(process.env["PWD"] ?? dir) : basename(dir);
+
+    const indexPath = join(dir, "index.html");
+    if (existsSync(indexPath)) {
+      const lintResult = lintProject({ dir, name: projectName, indexPath });
+      if (lintResult.totalErrors > 0 || lintResult.totalWarnings > 0) {
+        console.log();
+        for (const line of formatLintFindings(lintResult)) console.log(line);
+        console.log();
+      }
+    }
+
+    if (args.yes !== true) {
+      console.log();
+      console.log(
+        `  ${c.bold("hyperframes publish uploads this project and creates a stable public URL.")}`,
+      );
+      console.log(
+        `  ${c.dim("Anyone with the URL can open the published project and claim it after authenticating.")}`,
+      );
+      console.log();
+      const approved = await clack.confirm({ message: "Publish this project?" });
+      if (clack.isCancel(approved) || approved !== true) {
+        console.log();
+        console.log(`  ${c.dim("Aborted.")}`);
+        console.log();
+        return;
+      }
+    }
+
+    clack.intro(c.bold("hyperframes publish"));
+    const publishSpinner = clack.spinner();
+    publishSpinner.start("Uploading project...");
+
+    try {
+      const published = await publishProjectArchive(dir);
+      const claimUrl = new URL(published.url);
+      claimUrl.searchParams.set("claim_token", published.claimToken);
+      publishSpinner.stop(c.success("Project published"));
+
+      console.log();
+      console.log(`  ${c.dim("Project")}    ${c.accent(published.title)}`);
+      console.log(`  ${c.dim("Files")}      ${String(published.fileCount)}`);
+      console.log(`  ${c.dim("Public")}     ${c.accent(claimUrl.toString())}`);
+      console.log();
+      console.log(
+        `  ${c.dim("Open the URL on hyperframes.dev to claim the project and continue editing.")}`,
+      );
+      console.log();
+      return;
+    } catch (err: unknown) {
+      publishSpinner.stop(c.error("Publish failed"));
+      console.error();
+      console.error(`  ${(err as Error).message}`);
+      console.error();
+      process.exitCode = 1;
+      return;
+    }
+  },
+});
diff --git a/packages/cli/src/help.ts b/packages/cli/src/help.ts
index fa77935fd..7c89ceb13 100644
--- a/packages/cli/src/help.ts
+++ b/packages/cli/src/help.ts
@@ -24,6 +24,7 @@ const GROUPS: Group[] = [
       ["capture", "Capture a website for video production"],
       ["catalog", "Browse and install blocks and components"],
       ["preview", "Start the studio for previewing compositions"],
+      ["publish", "Expose the preview via a public URL so collaborators can view it"],
       ["render", "Render a composition to MP4 or WebM"],
     ],
   },
@@ -72,6 +73,7 @@ import type { Example } from "./commands/_examples.js";
 const ROOT_EXAMPLES: Example[] = [
   ["Create a new project", "hyperframes init my-video"],
   ["Start the live preview studio", "hyperframes preview"],
+  ["Share via public URL", "hyperframes publish"],
   ["Render to MP4", "hyperframes render -o out.mp4"],
   ["Transparent WebM overlay", "hyperframes render --format webm -o out.webm"],
   ["Validate your composition", "hyperframes lint"],
diff --git a/packages/cli/src/utils/publishProject.test.ts b/packages/cli/src/utils/publishProject.test.ts
new file mode 100644
index 000000000..a34cbaf3f
--- /dev/null
+++ b/packages/cli/src/utils/publishProject.test.ts
@@ -0,0 +1,81 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  createPublishArchive,
+  getPublishApiBaseUrl,
+  publishProjectArchive,
+} from "./publishProject.js";
+
+function makeProjectDir(): string {
+  return mkdtempSync(join(tmpdir(), "hf-publish-"));
+}
+
+describe("createPublishArchive", () => {
+  it("packages the project and skips hidden files and node_modules", () => {
+    const dir = makeProjectDir();
+    try {
+      writeFileSync(join(dir, "index.html"), "<html></html>", "utf-8");
+      mkdirSync(join(dir, "assets"));
+      writeFileSync(join(dir, "assets/logo.svg"), "<svg />", "utf-8");
+      mkdirSync(join(dir, ".git"));
+      writeFileSync(join(dir, ".env"), "SECRET=1", "utf-8");
+      mkdirSync(join(dir, "node_modules"));
+      writeFileSync(join(dir, "node_modules/ignored.js"), "console.log('ignore')", "utf-8");
+
+      const archive = createPublishArchive(dir);
+
+      expect(archive.fileCount).toBe(2);
+      expect(archive.buffer.byteLength).toBeGreaterThan(0);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("publishProjectArchive", () => {
+  beforeEach(() => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response(
+          JSON.stringify({
+            data: {
+              project_id: "hfp_123",
+              title: "demo",
+              file_count: 2,
+              url: "https://hyperframes.dev/p/hfp_123",
+              claim_token: "claim-token",
+            },
+          }),
+          { status: 200 },
+        ),
+      ),
+    );
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("uploads the archive and returns the stable project URL", async () => {
+    const dir = makeProjectDir();
+    try {
+      writeFileSync(join(dir, "index.html"), "<html></html>", "utf-8");
+      writeFileSync(join(dir, "styles.css"), "body {}", "utf-8");
+
+      const result = await publishProjectArchive(dir);
+
+      expect(getPublishApiBaseUrl()).toBe("https://api2.heygen.com");
+      expect(result).toMatchObject({
+        projectId: "hfp_123",
+        url: "https://hyperframes.dev/p/hfp_123",
+      });
+      expect(fetch).toHaveBeenCalledTimes(1);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/cli/src/utils/publishProject.ts b/packages/cli/src/utils/publishProject.ts
new file mode 100644
index 000000000..8f7de1713
--- /dev/null
+++ b/packages/cli/src/utils/publishProject.ts
@@ -0,0 +1,97 @@
+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 response = await fetch(`${getPublishApiBaseUrl()}/v1/hyperframes/projects/publish`, {
+    method: "POST",
+    body,
+    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),
+  };
+}

From e40d393fc58b372506eb8ae7e259c9570b222cf6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Wed, 22 Apr 2026 10:10:18 -0400
Subject: [PATCH 2/5] fix(cli): restack publish on persisted project flow

---
 docs/packages/cli.mdx    | 42 +++++++++++++++++++++++++++++++++++++---
 packages/cli/src/cli.ts  | 13 +++++++++++--
 packages/cli/src/help.ts |  4 ++--
 3 files changed, 52 insertions(+), 7 deletions(-)

diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
index 0754ebea3..e65317aa9 100644
--- a/docs/packages/cli.mdx
+++ b/docs/packages/cli.mdx
@@ -305,6 +305,12 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
     # Adjust speech speed
     npx hyperframes tts "Slow and clear" --speed 0.8
 
+    # Generate Spanish speech (lang auto-detected from the `e` voice prefix)
+    npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
+
+    # Override the phonemizer (read English text with a French voice)
+    npx hyperframes tts "Bonjour le monde" --voice af_heart --lang fr-fr
+
     # Read text from a file
     npx hyperframes tts script.txt
 
@@ -317,9 +323,14 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
     | `--output, -o` | Output file path (default: `speech.wav` in current directory) |
     | `--voice, -v` | Voice ID (run `--list` to see options) |
     | `--speed, -s` | Speech speed multiplier (default: 1.0) |
+    | `--lang, -l` | Phonemizer locale (`en-us`, `en-gb`, `es`, `fr-fr`, `hi`, `it`, `pt-br`, `ja`, `zh`). When omitted, inferred from the voice ID prefix. |
     | `--list` | List available voices and exit |
     | `--json` | Output result as JSON |
 
+    <Tip>
+      Voice IDs encode the phonemizer language in their first letter (`a`=American, `b`=British, `e`=Spanish, `f`=French, `h`=Hindi, `i`=Italian, `j`=Japanese, `p`=Brazilian Portuguese, `z`=Mandarin). `--lang` is only needed when you want to override that — for example, giving English text a French phonemizer for a stylized accent.
+    </Tip>
+
     <Tip>
       Combine `tts` with `transcribe` to generate narration and word-level timestamps for captions in a single workflow: generate the audio with `tts`, then transcribe the output with `transcribe` to get word-level timing.
     </Tip>
@@ -373,6 +384,10 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
 
     Opens your composition in the Hyperframes Studio with live preview. Edits to `index.html` and any referenced sub-compositions are reflected automatically. The preview uses the same Hyperframes runtime as production rendering, so what you see is what you get.
 
+    <Note>
+      Visual output matches render exactly. Playback *performance* does not: preview plays in real time in your browser, so paint-heavy compositions (large images, stacked `backdrop-filter` layers, many shadowed elements) may stutter depending on your hardware. The rendered mp4 is always accurate regardless — render captures frames one at a time, so per-frame cost shows up as longer render duration, not dropped frames. See [Performance](/guides/performance) for details.
+    </Note>
+
     The preview server runs in three modes, auto-detected:
 
     1. **Embedded mode** (default for `npx`) — runs a standalone server with the studio bundled in the CLI. Zero extra dependencies.
@@ -480,14 +495,15 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
     | `--output` | path | `renders/<name>.mp4` | Output file path |
     | `--format` | mp4, webm, mov | mp4 | Output format (WebM/MOV render with transparency) |
     | `--fps` | 24, 30, 60 | 30 | Frames per second |
-    | `--quality` | draft, standard, high | standard | Encoding quality preset |
-    | `--crf` | 0–51 | — | Override CRF (lower = higher quality). Cannot combine with `--video-bitrate` |
-    | `--video-bitrate` | e.g. `10M`, `5000k` | — | Target bitrate encoding. Cannot combine with `--crf` |
+    | `--quality` | draft, standard, high | standard | Encoding quality preset (drives CRF/bitrate) |
+    | `--hdr` | — | off | Detect HDR sources and output HDR10 (H.265 10-bit, BT.2020 PQ/HLG). MP4 only. SDR-only compositions are unaffected. See [HDR Rendering](/guides/hdr) |
     | `--workers` | 1-8 | 4 | Parallel render workers |
     | `--gpu` | — | off | GPU encoding (NVENC, VideoToolbox, VAAPI) |
     | `--docker` | — | off | Use Docker for [deterministic rendering](/concepts/determinism) |
     | `--quiet` | — | off | Suppress verbose output |
 
+    CRF and target bitrate are now driven by `--quality`. For programmatic renders, `RenderConfig.crf` and `RenderConfig.videoBitrate` still accept overrides.
+
     #### WebM with Transparency
 
     Use `--format webm` to render compositions with a transparent background. This produces VP9 video with alpha channel in a WebM container — the standard format for overlayable video.
@@ -649,6 +665,26 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
     | `--cursor` | Install to Cursor (`.cursor/skills/` in current project) |
 
     Skills are fetched from GitHub and include composition authoring, GSAP animation patterns, registry block/component wiring, and other domain-specific knowledge. The `init` command also offers to install skills automatically after scaffolding a project.
+
+    #### Troubleshooting: `fatal: active post-checkout hook found during git clone`
+
+    If you installed Git LFS globally (`git lfs install`), Git 2.45+ refuses to run the LFS post-checkout hook during any `git clone` — including the clone the upstream `skills` CLI performs under the hood. The error looks like:
+
+    ```
+    ■  Failed to clone repository
+    fatal: active `post-checkout` hook found during `git clone`
+    └  Installation failed
+    ```
+
+    **Using `hyperframes skills` is already fine** — as of v0.4.5 the CLI sets `GIT_CLONE_PROTECTION_ACTIVE=0` on the child environment, which is the opt-in knob Git provides for exactly this case. You don't need to do anything.
+
+    **If you ran `npx skills add heygen-com/hyperframes` directly** (bypassing the HyperFrames CLI), set the env var yourself:
+
+    ```bash
+    GIT_CLONE_PROTECTION_ACTIVE=0 npx skills add heygen-com/hyperframes
+    ```
+
+    This is tracked in [GH #316](https://github.com/heygen-com/hyperframes/issues/316). An upstream fix in the `skills` CLI itself is the right long-term answer; until that lands, the env var is the correct workaround.
   </Tab>
 </Tabs>
 
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 63e8768fb..83528dbb0 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -83,9 +83,18 @@ if (!isHelp && command !== "telemetry" && command !== "unknown") {
 }
 
 if (!isHelp && !hasJsonFlag && command !== "upgrade") {
-  import("./utils/updateCheck.js").then((mod) => {
+  // Report any completed auto-install from the previous run first, before
+  // kicking off the next check — so the user sees "updated to vX" once and
+  // we don't over-print.
+  import("./utils/autoUpdate.js").then((mod) => mod.reportCompletedUpdate()).catch(() => {});
+
+  import("./utils/updateCheck.js").then(async (mod) => {
     _printUpdateNotice = mod.printUpdateNotice;
-    mod.checkForUpdate().catch(() => {});
+    const result = await mod.checkForUpdate().catch(() => null);
+    if (result?.updateAvailable) {
+      const auto = await import("./utils/autoUpdate.js").catch(() => null);
+      auto?.scheduleBackgroundInstall(result.latest, result.current);
+    }
   });
 }
 
diff --git a/packages/cli/src/help.ts b/packages/cli/src/help.ts
index 7c89ceb13..0f5630c72 100644
--- a/packages/cli/src/help.ts
+++ b/packages/cli/src/help.ts
@@ -24,7 +24,7 @@ const GROUPS: Group[] = [
       ["capture", "Capture a website for video production"],
       ["catalog", "Browse and install blocks and components"],
       ["preview", "Start the studio for previewing compositions"],
-      ["publish", "Expose the preview via a public URL so collaborators can view it"],
+      ["publish", "Upload a project and get a stable public URL"],
       ["render", "Render a composition to MP4 or WebM"],
     ],
   },
@@ -73,7 +73,7 @@ import type { Example } from "./commands/_examples.js";
 const ROOT_EXAMPLES: Example[] = [
   ["Create a new project", "hyperframes init my-video"],
   ["Start the live preview studio", "hyperframes preview"],
-  ["Share via public URL", "hyperframes publish"],
+  ["Publish to hyperframes.dev", "hyperframes publish"],
   ["Render to MP4", "hyperframes render -o out.mp4"],
   ["Transparent WebM overlay", "hyperframes render --format webm -o out.webm"],
   ["Validate your composition", "hyperframes lint"],

From 27f42f237106c4c6693f96522bbfe39c20d527bf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Wed, 22 Apr 2026 10:51:19 -0400
Subject: [PATCH 3/5] feat(cli): add canary publish routing

---
 docs/packages/cli.mdx                         |  2 ++
 packages/cli/src/commands/publish.ts          | 16 +++++++++++-
 packages/cli/src/utils/publishProject.test.ts | 25 +++++++++++++++++++
 packages/cli/src/utils/publishProject.ts      | 14 ++++++++++-
 4 files changed, 55 insertions(+), 2 deletions(-)

diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
index e65317aa9..9fbacb713 100644
--- a/docs/packages/cli.mdx
+++ b/docs/packages/cli.mdx
@@ -401,11 +401,13 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
     ```bash
     npx hyperframes publish [dir]
     npx hyperframes publish --yes
+    npx hyperframes publish --canary
     ```
 
     | Flag | Description |
     |------|-------------|
     | `--yes` | Skip the confirmation prompt |
+    | `--canary` | Route the publish request to canary heygen-server |
 
     `publish` zips the current project, uploads it to the HyperFrames publish backend, and prints a stable `hyperframes.dev` URL for that stored project.
 
diff --git a/packages/cli/src/commands/publish.ts b/packages/cli/src/commands/publish.ts
index 132cc8edb..03eadcae3 100644
--- a/packages/cli/src/commands/publish.ts
+++ b/packages/cli/src/commands/publish.ts
@@ -12,6 +12,7 @@ import { publishProjectArchive } from "../utils/publishProject.js";
 
 export const examples: Example[] = [
   ["Publish the current project with a public URL", "hyperframes publish"],
+  ["Publish against canary heygen-server", "hyperframes publish --canary"],
   ["Publish a specific directory", "hyperframes publish ./my-video"],
   ["Skip the consent prompt (scripts)", "hyperframes publish --yes"],
 ];
@@ -29,6 +30,11 @@ export default defineCommand({
       description: "Skip the publish confirmation prompt",
       default: false,
     },
+    canary: {
+      type: "boolean",
+      description: "Route the publish request to canary heygen-server",
+      default: false,
+    },
   },
   async run({ args }) {
     const rawArg = args.dir;
@@ -54,6 +60,11 @@ export default defineCommand({
       console.log(
         `  ${c.dim("Anyone with the URL can open the published project and claim it after authenticating.")}`,
       );
+      if (args.canary === true) {
+        console.log(
+          `  ${c.dim("This run will route the publish request to canary heygen-server.")}`,
+        );
+      }
       console.log();
       const approved = await clack.confirm({ message: "Publish this project?" });
       if (clack.isCancel(approved) || approved !== true) {
@@ -69,7 +80,7 @@ export default defineCommand({
     publishSpinner.start("Uploading project...");
 
     try {
-      const published = await publishProjectArchive(dir);
+      const published = await publishProjectArchive(dir, { canary: args.canary === true });
       const claimUrl = new URL(published.url);
       claimUrl.searchParams.set("claim_token", published.claimToken);
       publishSpinner.stop(c.success("Project published"));
@@ -77,6 +88,9 @@ export default defineCommand({
       console.log();
       console.log(`  ${c.dim("Project")}    ${c.accent(published.title)}`);
       console.log(`  ${c.dim("Files")}      ${String(published.fileCount)}`);
+      if (args.canary === true) {
+        console.log(`  ${c.dim("Route")}      ${c.accent("canary")}`);
+      }
       console.log(`  ${c.dim("Public")}     ${c.accent(claimUrl.toString())}`);
       console.log();
       console.log(
diff --git a/packages/cli/src/utils/publishProject.test.ts b/packages/cli/src/utils/publishProject.test.ts
index a34cbaf3f..1257dc706 100644
--- a/packages/cli/src/utils/publishProject.test.ts
+++ b/packages/cli/src/utils/publishProject.test.ts
@@ -74,6 +74,31 @@ describe("publishProjectArchive", () => {
         url: "https://hyperframes.dev/p/hfp_123",
       });
       expect(fetch).toHaveBeenCalledTimes(1);
+      expect(fetch).toHaveBeenCalledWith(
+        "https://api2.heygen.com/v1/hyperframes/projects/publish",
+        expect.objectContaining({
+          method: "POST",
+          signal: expect.any(AbortSignal),
+        }),
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("routes publish to canary when requested", async () => {
+    const dir = makeProjectDir();
+    try {
+      writeFileSync(join(dir, "index.html"), "<html></html>", "utf-8");
+
+      await publishProjectArchive(dir, { canary: true });
+
+      expect(fetch).toHaveBeenCalledWith(
+        "https://api2.heygen.com/v1/hyperframes/projects/publish",
+        expect.objectContaining({
+          headers: { heygen_route: "canary" },
+        }),
+      );
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
diff --git a/packages/cli/src/utils/publishProject.ts b/packages/cli/src/utils/publishProject.ts
index 8f7de1713..53df551ff 100644
--- a/packages/cli/src/utils/publishProject.ts
+++ b/packages/cli/src/utils/publishProject.ts
@@ -18,6 +18,10 @@ export interface PublishedProjectResponse {
   claimToken: string;
 }
 
+export interface PublishProjectOptions {
+  canary?: boolean;
+}
+
 function shouldIgnoreSegment(segment: string): boolean {
   return segment.startsWith(".") || IGNORED_DIRS.has(segment) || IGNORED_FILES.has(segment);
 }
@@ -65,7 +69,10 @@ export function getPublishApiBaseUrl(): string {
   ).replace(/\/$/, "");
 }
 
-export async function publishProjectArchive(projectDir: string): Promise<PublishedProjectResponse> {
+export async function publishProjectArchive(
+  projectDir: string,
+  options: PublishProjectOptions = {},
+): Promise<PublishedProjectResponse> {
   const title = basename(projectDir);
   const archive = createPublishArchive(projectDir);
   const archiveBytes = new Uint8Array(archive.buffer.byteLength);
@@ -73,10 +80,15 @@ export async function publishProjectArchive(projectDir: string): Promise<Publish
   const body = new FormData();
   body.set("title", title);
   body.set("file", new File([archiveBytes], `${title}.zip`, { type: "application/zip" }));
+  const headers: Record<string, string> = {};
+  if (options.canary) {
+    headers["heygen_route"] = "canary";
+  }
 
   const response = await fetch(`${getPublishApiBaseUrl()}/v1/hyperframes/projects/publish`, {
     method: "POST",
     body,
+    headers,
     signal: AbortSignal.timeout(30_000),
   });
 

From d7f8a03eea17b734023d465c10410d209dc6c6ad Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Wed, 22 Apr 2026 14:48:59 -0400
Subject: [PATCH 4/5] fix(cli): remove explicit canary publish mode

---
 docs/packages/cli.mdx                         |  2 --
 packages/cli/src/commands/publish.ts          | 16 +---------------
 packages/cli/src/utils/publishProject.test.ts | 18 ------------------
 packages/cli/src/utils/publishProject.ts      | 14 +-------------
 4 files changed, 2 insertions(+), 48 deletions(-)

diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
index 9fbacb713..e65317aa9 100644
--- a/docs/packages/cli.mdx
+++ b/docs/packages/cli.mdx
@@ -401,13 +401,11 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
     ```bash
     npx hyperframes publish [dir]
     npx hyperframes publish --yes
-    npx hyperframes publish --canary
     ```
 
     | Flag | Description |
     |------|-------------|
     | `--yes` | Skip the confirmation prompt |
-    | `--canary` | Route the publish request to canary heygen-server |
 
     `publish` zips the current project, uploads it to the HyperFrames publish backend, and prints a stable `hyperframes.dev` URL for that stored project.
 
diff --git a/packages/cli/src/commands/publish.ts b/packages/cli/src/commands/publish.ts
index 03eadcae3..132cc8edb 100644
--- a/packages/cli/src/commands/publish.ts
+++ b/packages/cli/src/commands/publish.ts
@@ -12,7 +12,6 @@ import { publishProjectArchive } from "../utils/publishProject.js";
 
 export const examples: Example[] = [
   ["Publish the current project with a public URL", "hyperframes publish"],
-  ["Publish against canary heygen-server", "hyperframes publish --canary"],
   ["Publish a specific directory", "hyperframes publish ./my-video"],
   ["Skip the consent prompt (scripts)", "hyperframes publish --yes"],
 ];
@@ -30,11 +29,6 @@ export default defineCommand({
       description: "Skip the publish confirmation prompt",
       default: false,
     },
-    canary: {
-      type: "boolean",
-      description: "Route the publish request to canary heygen-server",
-      default: false,
-    },
   },
   async run({ args }) {
     const rawArg = args.dir;
@@ -60,11 +54,6 @@ export default defineCommand({
       console.log(
         `  ${c.dim("Anyone with the URL can open the published project and claim it after authenticating.")}`,
       );
-      if (args.canary === true) {
-        console.log(
-          `  ${c.dim("This run will route the publish request to canary heygen-server.")}`,
-        );
-      }
       console.log();
       const approved = await clack.confirm({ message: "Publish this project?" });
       if (clack.isCancel(approved) || approved !== true) {
@@ -80,7 +69,7 @@ export default defineCommand({
     publishSpinner.start("Uploading project...");
 
     try {
-      const published = await publishProjectArchive(dir, { canary: args.canary === true });
+      const published = await publishProjectArchive(dir);
       const claimUrl = new URL(published.url);
       claimUrl.searchParams.set("claim_token", published.claimToken);
       publishSpinner.stop(c.success("Project published"));
@@ -88,9 +77,6 @@ export default defineCommand({
       console.log();
       console.log(`  ${c.dim("Project")}    ${c.accent(published.title)}`);
       console.log(`  ${c.dim("Files")}      ${String(published.fileCount)}`);
-      if (args.canary === true) {
-        console.log(`  ${c.dim("Route")}      ${c.accent("canary")}`);
-      }
       console.log(`  ${c.dim("Public")}     ${c.accent(claimUrl.toString())}`);
       console.log();
       console.log(
diff --git a/packages/cli/src/utils/publishProject.test.ts b/packages/cli/src/utils/publishProject.test.ts
index 1257dc706..2cd6ac8b2 100644
--- a/packages/cli/src/utils/publishProject.test.ts
+++ b/packages/cli/src/utils/publishProject.test.ts
@@ -85,22 +85,4 @@ describe("publishProjectArchive", () => {
       rmSync(dir, { recursive: true, force: true });
     }
   });
-
-  it("routes publish to canary when requested", async () => {
-    const dir = makeProjectDir();
-    try {
-      writeFileSync(join(dir, "index.html"), "<html></html>", "utf-8");
-
-      await publishProjectArchive(dir, { canary: true });
-
-      expect(fetch).toHaveBeenCalledWith(
-        "https://api2.heygen.com/v1/hyperframes/projects/publish",
-        expect.objectContaining({
-          headers: { heygen_route: "canary" },
-        }),
-      );
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
 });
diff --git a/packages/cli/src/utils/publishProject.ts b/packages/cli/src/utils/publishProject.ts
index 53df551ff..8f7de1713 100644
--- a/packages/cli/src/utils/publishProject.ts
+++ b/packages/cli/src/utils/publishProject.ts
@@ -18,10 +18,6 @@ export interface PublishedProjectResponse {
   claimToken: string;
 }
 
-export interface PublishProjectOptions {
-  canary?: boolean;
-}
-
 function shouldIgnoreSegment(segment: string): boolean {
   return segment.startsWith(".") || IGNORED_DIRS.has(segment) || IGNORED_FILES.has(segment);
 }
@@ -69,10 +65,7 @@ export function getPublishApiBaseUrl(): string {
   ).replace(/\/$/, "");
 }
 
-export async function publishProjectArchive(
-  projectDir: string,
-  options: PublishProjectOptions = {},
-): Promise<PublishedProjectResponse> {
+export async function publishProjectArchive(projectDir: string): Promise<PublishedProjectResponse> {
   const title = basename(projectDir);
   const archive = createPublishArchive(projectDir);
   const archiveBytes = new Uint8Array(archive.buffer.byteLength);
@@ -80,15 +73,10 @@ export async function publishProjectArchive(
   const body = new FormData();
   body.set("title", title);
   body.set("file", new File([archiveBytes], `${title}.zip`, { type: "application/zip" }));
-  const headers: Record<string, string> = {};
-  if (options.canary) {
-    headers["heygen_route"] = "canary";
-  }
 
   const response = await fetch(`${getPublishApiBaseUrl()}/v1/hyperframes/projects/publish`, {
     method: "POST",
     body,
-    headers,
     signal: AbortSignal.timeout(30_000),
   });
 

From 2a56cc6e682ba8b9b85cee3d86f525300de98d1d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Wed, 22 Apr 2026 14:58:17 -0400
Subject: [PATCH 5/5] fix(cli): route publish requests through canary by
 default

---
 packages/cli/src/utils/publishProject.test.ts | 1 +
 packages/cli/src/utils/publishProject.ts      | 4 ++++
 2 files changed, 5 insertions(+)

diff --git a/packages/cli/src/utils/publishProject.test.ts b/packages/cli/src/utils/publishProject.test.ts
index 2cd6ac8b2..957be1a24 100644
--- a/packages/cli/src/utils/publishProject.test.ts
+++ b/packages/cli/src/utils/publishProject.test.ts
@@ -78,6 +78,7 @@ describe("publishProjectArchive", () => {
         "https://api2.heygen.com/v1/hyperframes/projects/publish",
         expect.objectContaining({
           method: "POST",
+          headers: { heygen_route: "canary" },
           signal: expect.any(AbortSignal),
         }),
       );
diff --git a/packages/cli/src/utils/publishProject.ts b/packages/cli/src/utils/publishProject.ts
index 8f7de1713..536b19d47 100644
--- a/packages/cli/src/utils/publishProject.ts
+++ b/packages/cli/src/utils/publishProject.ts
@@ -73,10 +73,14 @@ export async function publishProjectArchive(projectDir: string): Promise<Publish
   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),
   });