mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* feat(cli): surface outdated CLI and skills to agents; add hyperframes update Single commit of #7094 on top of main (no merge commits through the signed GraphQL path). Includes: 2h update/skills check interval and stale-cache recheck; `_meta.checkedAt`, `_meta.skillsOutdated`, `_meta.skillsMissing`; `_meta.updateNotice`, one sentence for the agent to relay to the person, at most once a day per project (brew/npx-aware command, omitted under CI, the update-check opt-out and agent plugins); `hyperframes update [--check] [--yes] [--json]` (CLI then skills at the installed CLI's tag; brew version read back); doctor names the running binary and its channel; the hyperframes-cli skill gets one line to pass the notice on, naming no command. Keeps main's install-target skills check (#7120) in updateSkills. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): update notice names a command that moves this install - `_meta.updateNotice` (and `update --check`'s skills command) now name a command that moves the running install: a global npm/pnpm/bun/brew CLI runs its own `hyperframes update` (or just its manager's command when only the CLI is behind), since `npx hyperframes` would run a project's copy or a fresh npx one; a project-local CLI moves with its project's manager by lockfile (`npm install`/`pnpm add`/`bun add`/`yarn add hyperframes@<v>`), which `update --yes` now names too instead of `npx hyperframes@latest`. - `update`'s confirmation hint states a fact and names no step for the agent: "Updating is the person's call; `update --check` only reports." - `upgrade --json`, `upgrade --project --json` and every `skills` JSON output leave out `_meta.updateNotice` (NO_UPDATE_NOTICE), like `update`. - dailyNotice: a null/non-object file reads as empty and is repaired; a future timestamp is stale; writes go through a 0600 tmp file + rename; withMeta never throws from the notice. - Docs: --json without --yes exits 2; plugin `update` exits 1 (plugin_managed); full `_meta` sample; per-install notice commands. `update --check` says "npm registry not reached" instead of "latest". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
248 lines
10 KiB
TypeScript
248 lines
10 KiB
TypeScript
/**
|
|
* Custom help renderer for the hyperframes CLI.
|
|
*
|
|
* Root-level: grouped command categories + examples.
|
|
* Subcommands: citty's standard USAGE/ARGUMENTS/OPTIONS + appended examples.
|
|
*/
|
|
import { renderUsage } from "citty";
|
|
import type { CommandDef } from "citty";
|
|
import { stripVTControlCharacters } from "node:util";
|
|
import { c, isColorSupported } from "./ui/colors.js";
|
|
import { VERSION } from "./version.js";
|
|
|
|
// ── Root-level command groups ──────────────────────────────────────────────
|
|
interface Group {
|
|
title: string;
|
|
commands: [name: string, description: string][];
|
|
}
|
|
|
|
const GROUPS: Group[] = [
|
|
{
|
|
title: "Getting Started",
|
|
commands: [
|
|
["init", "Scaffold a new composition project"],
|
|
["add", "Install a block or component from the registry"],
|
|
["capture", "Capture a website for video production"],
|
|
["catalog", "Browse and install blocks and components"],
|
|
["preview", "Start the studio for previewing compositions"],
|
|
["present", "Open a slideshow deck in presenter mode (with audience sync)"],
|
|
["publish", "Upload a project to a stable URL (private by default)"],
|
|
["render", "Render a composition to MP4 or WebM"],
|
|
["open", "Open a project in the HyperFrames desktop app"],
|
|
["catch-up", "See what was done in the desktop app since you last looked"],
|
|
],
|
|
},
|
|
{
|
|
title: "Project",
|
|
commands: [
|
|
["lint", "Validate a composition for common mistakes"],
|
|
["check", "Run lint, runtime validation, and layout inspection as one gate"],
|
|
[
|
|
"validate",
|
|
"Runtime-validate a composition in headless Chrome (JS errors, missing assets, contrast)",
|
|
],
|
|
["beats", "Detect beats in the music track and write beats/<audio>.json"],
|
|
["audio", "Measure where sounds land: onsets, hits, loudness, silence, in film time"],
|
|
["inspect", "Inspect rendered visual layout across the timeline"],
|
|
["keyframes", "Inspect keyframes and render onion-shot diagnostics"],
|
|
["snapshot", "Capture key frames as PNG screenshots for visual verification"],
|
|
[
|
|
"media-treatment",
|
|
"Discover, apply, or clear deterministic media treatments on media elements",
|
|
],
|
|
[
|
|
"normalize-audio",
|
|
"Match one authored audio clip's loudness to another using integrated LUFS",
|
|
],
|
|
[
|
|
"grade-compare",
|
|
"Render candidate color grades onto a reference frame as one labeled comparison PNG",
|
|
],
|
|
["compare", "Render composition variants into one labeled comparison sheet"],
|
|
["diff", "Score a render or a project against the original video, frame by frame"],
|
|
[
|
|
"measure",
|
|
"Measure a video file: clock, cuts, events, frames, motion, crops, boxes, eases, look",
|
|
],
|
|
["reverse", "Open a reverse-any-video run: note it with HeyGen, then probe the video"],
|
|
["billing", "Open the HyperFrames plans or credits page and wait until it is done"],
|
|
["templates", "Pull a style template into this project (HyperFrames Pro)"],
|
|
["info", "Print project metadata"],
|
|
["compositions", "List all compositions in a project"],
|
|
["timeline", "Print the project's tracks and clips"],
|
|
["history", "List, undo and restore the project's recorded changes"],
|
|
["docs", "View inline documentation in the terminal"],
|
|
],
|
|
},
|
|
{
|
|
title: "Tooling",
|
|
commands: [
|
|
[
|
|
"benchmark",
|
|
"Render with preset fps/quality/worker configs and compare speed and file size",
|
|
],
|
|
["browser", "Manage the Chrome browser used for rendering"],
|
|
["doctor", "Check system dependencies and environment"],
|
|
["clean", "Find and remove what HyperFrames left on disk"],
|
|
["upgrade", "Check for updates and show upgrade instructions"],
|
|
["update", "Check the CLI and the skills for updates in one call, and install them"],
|
|
],
|
|
},
|
|
{
|
|
title: "Deploy",
|
|
commands: [
|
|
["cloud", "Render compositions on HeyGen's cloud (no local Chrome/ffmpeg)"],
|
|
["lambda", "Deploy and drive distributed renders on AWS Lambda"],
|
|
["cloudrun", "Deploy and drive distributed renders on Google Cloud Run"],
|
|
],
|
|
},
|
|
{
|
|
title: "AI & Integrations",
|
|
commands: [
|
|
["skills", "Install HyperFrames and GSAP skills for AI coding tools"],
|
|
[
|
|
"transcribe",
|
|
"Transcribe audio/video to word-level timestamps, or import an existing transcript",
|
|
],
|
|
["models", "List or download on-device models (models list, models install parakeet)"],
|
|
["tts", "Generate speech audio from text using a local AI model (Kokoro-82M)"],
|
|
["remove-background", "Remove background from a video or image to produce transparent media"],
|
|
],
|
|
},
|
|
{
|
|
title: "Account",
|
|
commands: [["auth", "Sign in to HeyGen and manage credentials"]],
|
|
},
|
|
{
|
|
title: "Settings",
|
|
commands: [
|
|
["feedback", "Submit feedback about your experience"],
|
|
["telemetry", "Manage usage telemetry"],
|
|
],
|
|
},
|
|
];
|
|
|
|
// ── Root-level examples ────────────────────────────────────────────────────
|
|
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"],
|
|
["Publish to hyperframes.studio", "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"],
|
|
["Inspect visual layout", "hyperframes inspect"],
|
|
["Check system dependencies", "hyperframes doctor"],
|
|
];
|
|
|
|
// ── Per-command examples loaded from command files ────────────────────────
|
|
// Each command file exports `examples: Example[]`. This function dynamically
|
|
// imports them so examples live next to the command they document.
|
|
//
|
|
// For nested subverbs (e.g. `cloud render`), try the parent-scoped path
|
|
// first (`commands/cloud/render.js`) so we don't collide with the
|
|
// top-level command of the same name (`commands/render.js`).
|
|
// fallow-ignore-next-line complexity
|
|
async function loadExamples(name: string, parentName?: string): Promise<Example[] | undefined> {
|
|
// Skip the parent-scoped lookup for the root command — `parentName`
|
|
// is `'hyperframes'` for every top-level subcommand and no
|
|
// `./commands/hyperframes/<name>.js` directory will ever exist.
|
|
if (parentName && parentName !== "hyperframes") {
|
|
const examples = await tryLoadExamples(`./commands/${parentName}/${name}.js`);
|
|
if (examples) return examples;
|
|
}
|
|
return await tryLoadExamples(`./commands/${name}.js`);
|
|
}
|
|
|
|
async function tryLoadExamples(modulePath: string): Promise<Example[] | undefined> {
|
|
try {
|
|
const mod = await import(modulePath);
|
|
return mod.examples;
|
|
} catch (err) {
|
|
// Only swallow "file doesn't exist" — re-throw real load errors
|
|
// (syntax error, broken import, init-time throw) so a developer
|
|
// sees the diagnostic instead of getting silently wrong help.
|
|
if ((err as NodeJS.ErrnoException).code === "ERR_MODULE_NOT_FOUND") return undefined;
|
|
throw err;
|
|
}
|
|
}
|
|
|
|
// Commands without their own file (e.g. listed in help but not yet a real command)
|
|
const STATIC_EXAMPLES: Record<string, Example[]> = {
|
|
skills: [["Install all skills to all supported AI tools", "hyperframes skills"]],
|
|
};
|
|
|
|
// ── Render root help ───────────────────────────────────────────────────────
|
|
function renderRootHelp(): string {
|
|
const NAME_COL = 19;
|
|
const CMD_COL = 46;
|
|
const lines: string[] = [];
|
|
|
|
lines.push(
|
|
`${c.bold("hyperframes")} ${c.dim(`v${VERSION}`)} — Create and render HTML video compositions`,
|
|
);
|
|
lines.push("");
|
|
lines.push(`${c.bold("Usage:")} hyperframes ${c.cyan("<command>")} [options]`);
|
|
lines.push("");
|
|
|
|
for (const group of GROUPS) {
|
|
lines.push(c.bold(`${group.title}:`));
|
|
for (const [name, desc] of group.commands) {
|
|
lines.push(` ${c.cyan(name.padEnd(NAME_COL))}${desc}`);
|
|
}
|
|
lines.push("");
|
|
}
|
|
|
|
lines.push(c.bold("Examples:"));
|
|
for (const [comment, command] of ROOT_EXAMPLES) {
|
|
lines.push(` ${c.dim("$")} ${command.padEnd(CMD_COL)} ${c.dim(comment)}`);
|
|
}
|
|
lines.push("");
|
|
|
|
lines.push(
|
|
`Run ${c.cyan("hyperframes help <command>")} (or ${c.cyan("<command> --help")}) for more information about a command.`,
|
|
);
|
|
|
|
return lines.join("\n");
|
|
}
|
|
|
|
// ── Format examples section (comment + command style) ────────────────────────────────
|
|
function formatExamples(examples: Example[]): string {
|
|
const lines: string[] = [];
|
|
lines.push(c.bold("Examples:"));
|
|
for (const [comment, command] of examples) {
|
|
lines.push(` ${c.gray(`# ${comment}`)}`);
|
|
lines.push(` ${command}`);
|
|
lines.push("");
|
|
}
|
|
return lines.join("\n");
|
|
}
|
|
|
|
// ── Main showUsage override ────────────────────────────────────────────────
|
|
// fallow-ignore-next-line complexity
|
|
export async function showUsage(
|
|
cmd: CommandDef,
|
|
parent?: CommandDef,
|
|
print: (text: string) => void = console.log,
|
|
): Promise<void> {
|
|
if (!parent) {
|
|
print(renderRootHelp() + "\n");
|
|
return;
|
|
}
|
|
|
|
const meta = await (typeof cmd.meta === "function" ? cmd.meta() : cmd.meta);
|
|
const usage = await renderUsage(cmd, parent);
|
|
print((isColorSupported ? usage : stripVTControlCharacters(usage)) + "\n");
|
|
|
|
const name = meta?.name;
|
|
if (name) {
|
|
const parentMeta = await (typeof parent.meta === "function" ? parent.meta() : parent.meta);
|
|
const parentName = parentMeta?.name;
|
|
const examples = STATIC_EXAMPLES[name] ?? (await loadExamples(name, parentName));
|
|
if (examples) {
|
|
print(formatExamples(examples) + "\n");
|
|
}
|
|
}
|
|
}
|