Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { join, posix, relative, resolve } from "node:path";
import { failCommand, setCommandExitCode } from "../utils/commandResult.js";
import { existsSync } from "node:fs";
import { defineCommand } from "citty";
import * as clack from "@clack/prompts";
import type { Example } from "./_examples.js";
import { c } from "../ui/colors.js";
import {
definitiveEntryMismatchComposition,
hasDefinitiveEntryMismatch,
lintProject,
} from "../utils/lintProject.js";
import { formatLintStartupMessage } from "../utils/lintFormat.js";
import { envCredentialVar } from "../auth/resolver.js";
import {
buildPublishFileMap,
publishProjectArchive,
resolvePublishCredential,
zipPublishFileMap,
} from "../utils/publishProject.js";
import { bakeMediaProxies } from "../utils/publishProxyBake.js";
import type { ResolvedCredential } from "../auth/resolver.js";
import { resolveAutoProxy } from "../utils/projectConfig.js";
import {
ensureProjectId,
readProjectLink,
readTeamProject,
writeTeamProject,
} from "../utils/projectLink.js";
export const examples: Example[] = [
["Publish the current project privately to a stable URL", "hyperframes publish"],
["Publish a specific directory", "hyperframes publish ./my-video"],
["Make the claimed project public to anyone", "hyperframes publish --public"],
["Update an existing published project in place", "hyperframes publish --update <url|id>"],
["Publish to a shared team space", "hyperframes publish --space <space-id>"],
["Skip the consent prompt (scripts)", "hyperframes publish --yes"],
["Skip baking H.264 proxies for browser-hostile video codecs", "hyperframes publish --no-proxy"],
["Show full lint findings instead of the summary line", "hyperframes publish --lint-verbose"],
];
/** Extract a project id from a published URL (with or without scheme, query, or hash) or accept a bare id. */
export function parseUpdateTarget(value: string): string {
const trimmed = value.trim();
// Pull the id straight out of a `/p/<id>` path — works for full URLs, scheme-less URLs
// (which `new URL` rejects), and links carrying `?query`/`#hash`.
const pathMatch = trimmed.match(/\/p\/([^/?#]+)/);
if (pathMatch?.[1]) return pathMatch[1];
try {
const segment = new URL(trimmed).pathname.split("/").filter(Boolean).pop();
if (segment) return segment;
} catch {
// Not a URL — treat as a bare id.
}
return trimmed;
}
export default defineCommand({
meta: {
name: "publish",
description: "Upload the project to a stable URL (private by default)",
},
args: {
dir: { type: "positional", description: "Project directory", required: false },
yes: {
type: "boolean",
alias: "y",
description: "Skip the publish confirmation prompt",
default: false,
},
public: {
type: "boolean",
description: "Make the claimed project public to anyone, not just the claimer",
default: false,
},
update: {
type: "string",
description: "Update an existing published project in place (its URL or id)",
},
space: {
type: "string",
description: "Publish into a shared team space (its id) so teammates update one link",
},
proxy: {
type: "boolean",
description:
"Bake H.264 proxies for browser-hostile video codecs (e.g. HEVC) into the published archive. Default: on, unless disabled via hyperframes.json media.autoProxy. Pass --no-proxy to skip.",
},
"lint-verbose": {
type: "boolean",
description: "Show full lint findings before publishing (default: a one-line summary)",
default: false,
},
},
async run({ args }) {
const rawArg = args.dir;
const dir = resolve(rawArg ?? ".");
const indexPath = join(dir, "index.html");
if (existsSync(indexPath)) {
const lintResult = await lintProject(dir);
const definitiveEntryMismatch = hasDefinitiveEntryMismatch(lintResult);
if (lintResult.totalErrors > 0 || lintResult.totalWarnings > 0) {
console.log();
const verbose = Boolean(args["lint-verbose"]) || definitiveEntryMismatch;
for (const line of formatLintStartupMessage(
lintResult,
verbose ? { kind: "verbose" } : { kind: "summary" },
))
console.log(line);
console.log();
}
if (definitiveEntryMismatch) {
const candidate = definitiveEntryMismatchComposition(lintResult);
console.log(c.error(" Aborting publish because the default index.html entry is blank."));
if (candidate && posix.basename(candidate) === "index.html") {
const candidateDir = posix.dirname(candidate);
const target = `<project>/${candidateDir}`;
console.log(
c.dim(
` Move or mount the authored file, or publish its directory directly: hyperframes publish ${target}. Only use the directory form when its assets are self-contained under that directory; otherwise mount it from the project root.`,
),
);
} else if (candidate) {
console.log(
c.dim(
` Move or mount ${candidate} as a project index.html before publishing; publish accepts project directories, not individual HTML files.`,
),
);
}
console.log();
failCommand();
}
}
if (args.yes !== true) {
console.log();
if (args.public === true) {
console.log(
` ${c.bold("hyperframes publish uploads this project and requests public visibility at a stable URL.")}`,
);
console.log(` ${c.dim("Anyone with the URL can open a claimed public project.")}`);
} else {
console.log(
` ${c.bold("hyperframes publish uploads this project privately to a stable URL.")}`,
);
console.log(
` ${c.dim("Viewing requires authentication and access. Pass --public to allow anyone with the URL.")}`,
);
}
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;
}
}
const updateTarget =
typeof args.update === "string" && args.update.trim()
? parseUpdateTarget(args.update)
: undefined;
const spaceOverride =
typeof args.space === "string" && args.space.trim() ? args.space.trim() : undefined;
// Resolved once and passed to the upload: a second lookup after the bake could fall back
// from an expired login to a saved API key and silently drop --update / --space.
let credential: ResolvedCredential | null;
try {
credential = await resolvePublishCredential();
} catch (err: unknown) {
console.error();
console.error(` ${(err as Error).message}`);
console.error();
setCommandExitCode(1);
return;
}
// --update / --space only take effect for a login (an API-key publish is never owned).
// Fail loudly rather than silently minting a fresh URL.
if (updateTarget || spaceOverride) {
if (credential?.type !== "oauth") {
const flag = updateTarget ? "--update" : "--space";
const envKey = credential && envCredentialVar(credential.source);
console.log();
console.log(
` ${c.error(
!credential
? `${flag} requires authentication. Run 'hyperframes auth login' first.`
: envKey
? `${flag} requires a login; ${envKey} cannot own a project. Unset it and run 'hyperframes auth login'.`
: `${flag} requires a login; an API key cannot own a project. Run 'hyperframes auth login'.`,
)}`,
);
console.log();
setCommandExitCode(1);
return;
}
}
const committedTeam = readTeamProject(dir);
// Stable id: explicit --update wins, else the committed team id, else this machine's stored/minted id.
const requestedProjectId = updateTarget ?? committedTeam?.projectId ?? ensureProjectId(dir);
// Team space: explicit --space wins, else the committed space id, else the personal space.
const spaceId = spaceOverride ?? committedTeam?.spaceId;
// Continuity cue: if this directory was published before, show where it lives so the
// user knows a re-publish updates that same link (when logged in).
const priorLink = readProjectLink(dir);
if (priorLink?.url) {
console.log();
console.log(` ${c.dim(`Previously published at ${priorLink.url}`)}`);
}
clack.intro(c.bold("hyperframes publish"));
const publishSpinner = clack.spinner();
publishSpinner.start("Preparing project...");
try {
// Resolution order (per hyperframes.json's `media.autoProxy`): an
// explicit --proxy/--no-proxy flag wins in either direction, else the
// committed config, else on by default.
const proxyFlagValue = typeof args.proxy === "boolean" ? args.proxy : undefined;
const autoProxy = resolveAutoProxy(dir, proxyFlagValue);
const fileMap = buildPublishFileMap(dir);
let proxyBakeManifest: Awaited<ReturnType<typeof bakeMediaProxies>> | undefined;
if (autoProxy) {
proxyBakeManifest = await bakeMediaProxies(dir, fileMap);
}
const archive = zipPublishFileMap(fileMap);
publishSpinner.message("Uploading project...");
const published = await publishProjectArchive(dir, {
public: args.public === true,
projectId: requestedProjectId,
spaceId,
archive,
credential,
});
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)}`);
if (proxyBakeManifest) {
console.log(
` ${c.dim("Proxies")} ${String(proxyBakeManifest.proxied.length)} baked`,
);
if (proxyBakeManifest.skippedAlpha.length > 0) {
console.log(
` ${c.dim("Proxy note")} ${String(proxyBakeManifest.skippedAlpha.length)} alpha source(s) kept original`,
);
}
}
if (published.claimed) {
// The server returns the same id on an in-place update, a fresh id on create.
const updatedInPlace = published.projectId === requestedProjectId;
console.log(` ${c.dim("URL")} ${c.accent(published.url)}`);
// The CLI only ever states what it ASKED for: no response field carries the project's
// actual visibility. A re-publish without --public sends no visibility at all, so the
// server keeps whatever the project already had — saying "Private" there would claim
// a state we neither requested nor observed.
const requestedVisibility =
args.public === true
? "Public — anyone with the URL"
: updatedInPlace
? "Unchanged — keeps this project's current setting"
: "Private — authentication and access required";
console.log(` ${c.dim("Requested visibility")} ${c.accent(requestedVisibility)}`);
console.log(
` ${c.dim("Status")} ${c.accent(updatedInPlace ? "Updated existing project" : "Created new project")}`,
);
if (args.public !== true) {
console.log(
` ${c.dim("Tip")} ${c.dim("Re-publish with --public to allow anyone with the URL.")}`,
);
}
// Warn whenever we aimed at a KNOWN existing project (an explicit --update target or
// a committed team id) but the server created a fresh one instead — so a teammate
// whose space doesn't own the committed project doesn't silently lose the shared link.
if ((updateTarget || committedTeam) && !updatedInPlace) {
const targetDesc = updateTarget ? "The requested project" : "The committed team project";
console.log();
console.log(
` ${c.dim(`${targetDesc} was not updated (not found, or your space can't access it); a new project was created above instead.`)}`,
);
}
// Persist a committable descriptor so a team converges on this link. This is a
// convenience: wrap it so a read-only project dir can't turn a successful publish
// into a "Publish failed" (the outer catch owns publish failures only).
if (
committedTeam === null ||
(spaceId !== undefined && committedTeam.spaceId !== spaceId)
) {
try {
const file = writeTeamProject(dir, { projectId: published.projectId, spaceId });
console.log();
console.log(
` ${c.dim(`Wrote ${relative(dir, file) || file} — commit it so your team publishes to this link.`)}`,
);
} catch {
// Convenience file only; never shadow a successful publish with a local write failure.
}
}
console.log();
} else {
const claimUrl = new URL(published.url);
claimUrl.searchParams.set("claim_token", published.claimToken);
console.log(` ${c.dim("Claim URL")} ${c.accent(claimUrl.toString())}`);
console.log(` ${c.dim("Access")} ${c.accent("Sign in required to claim")}`);
console.log();
console.log(
` ${c.dim("Open the claim URL on hyperframes.dev, sign in, and claim the project to continue editing.")}`,
);
console.log();
const visibilityTip =
args.public === true
? "--public applies to the claimed project; this claim URL still requires sign-in."
: "Run 'hyperframes auth login' first for a stable link you can re-publish to; add --public to allow signed-out viewing.";
console.log(` ${c.dim(`Tip: ${visibilityTip}`)}`);
console.log();
}
return;
} catch (err: unknown) {
publishSpinner.stop(c.error("Publish failed"));
console.error();
console.error(` ${(err as Error).message}`);
console.error();
setCommandExitCode(1);
return;
}
},
});