Files
hyperframes/packages/cli/src/commands/publish.ts
T
Miguel Ángel b4e9d64e29 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.
2026-04-23 04:11:34 +02:00

97 lines
3.3 KiB
TypeScript

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;
}
},
});