mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* feat(cli): reverse start notes a reverse run with HeyGen and cloud render carries its session `npx hyperframes reverse start <video> [--dir <project>]` probes the video (the same JSON as `measure probe`), then, when signed in, calls POST /v1/hyperframes/reverse/start and saves the returned session id in the project's hyperframes.json. It never stops the run: signed out, offline, a 404 from a server without the route, or a malformed answer all continue with the probe and no session. `cloud render` sends `reverse_session_id` only when the project holds one, which only a successful /reverse/start writes. `init` now treats a folder holding only hyperframes.json as empty, so `reverse start --dir x` followed by `init x` works and keeps the session. The reverse-any-video skill opens with `reverse start` instead of `auth status` + `measure probe`, with a fallback for older CLIs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(cli): keep the comment share of touched files from rising Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): reverse start keeps unknown-plan sessions, prints the attributed upgrade link, takes only rvs ids - A `plan: "unknown"` answer is a valid session: saved, `recorded: true`, printed as `plan: null`; it never blocks and never falls back to the client-side plan read. - On Free, `reverse.upgrade_url` is printed: the server's link, else the plans page with `feature=reverse&rs=<session>` (the fields checkout reads). The skill passes that exact link on instead of `billing subscribe`. - Session ids must match the render endpoint's pattern (`rvs_<lowercase uuid>`). A saved value that does not is ignored: not sent on `cloud render`, and `reverse start` opens a fresh session. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(skills): name no CLI version for reverse start's fallback 0.9.4 shipped without `reverse start` and skills go live from main before the CLI release, so the fallback is described as "a CLI without it" instead of a version number. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
425 lines
16 KiB
TypeScript
425 lines
16 KiB
TypeScript
/**
|
|
* Read and write `hyperframes.json` — the per-project config that tells
|
|
* `hyperframes add` which registry to pull items from and where to drop them
|
|
* in the user's project tree.
|
|
*
|
|
* The file is created by `hyperframes init` and optionally edited by users to
|
|
* point at custom registries or reshape their project layout.
|
|
*/
|
|
|
|
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
import { join, resolve } from "node:path";
|
|
import { DEFAULT_REGISTRY_URL } from "../registry/index.js";
|
|
import { normalizeSkillSlug } from "../telemetry/skill.js";
|
|
import { writeNewFileSync } from "./writeNewFile.js";
|
|
|
|
export const PROJECT_CONFIG_FILENAME = "hyperframes.json";
|
|
const PROJECT_CONFIG_SCHEMA_URL = "https://hyperframes.heygen.com/schema/hyperframes.json";
|
|
|
|
export interface ProjectConfigPaths {
|
|
/** Where `hyperframes:block` items land, relative to project root. */
|
|
blocks: string;
|
|
/** Where `hyperframes:component` items land, relative to project root. */
|
|
components: string;
|
|
/** Where asset files (images, fonts, videos) land, relative to project root. */
|
|
assets: string;
|
|
}
|
|
|
|
export interface ProjectConfigMedia {
|
|
/**
|
|
* Auto-transcode browser-hostile video codecs (e.g. HEVC) to a cached
|
|
* alpha-aware authoring proxy for supported preview surfaces. Render always uses the
|
|
* original file regardless of this setting. Default true.
|
|
*/
|
|
autoProxy?: boolean;
|
|
}
|
|
|
|
/**
|
|
* One catalog item installed into this project by `hyperframes add`.
|
|
*
|
|
* Installed files are plain composition HTML with no provenance marker, so
|
|
* this manifest is the only record that a file came from the registry. It is
|
|
* what lets a render report which catalog items a finished video actually
|
|
* used, instead of only which ones were once downloaded.
|
|
*/
|
|
export interface RegistryItemRecord {
|
|
/** Registry item name, e.g. "data-chart". */
|
|
name: string;
|
|
/** Registry item type, e.g. "hyperframes:block". */
|
|
type: string;
|
|
/** Primary installed file, relative to the project root. */
|
|
target: string;
|
|
}
|
|
|
|
export interface ProjectConfig {
|
|
$schema?: string;
|
|
/** Base URL of the registry to pull items from. */
|
|
registry: string;
|
|
/** Target paths for each item type. */
|
|
paths: ProjectConfigPaths;
|
|
/** Media handling options (e.g. auto-proxying of browser-hostile codecs). */
|
|
media?: ProjectConfigMedia;
|
|
/**
|
|
* Owning authoring skill slug (e.g. "hyperframes"). Stamped
|
|
* by `hyperframes init --skill` or seeded from the first `hyperframes render
|
|
* --skill`, then read back so every later render of this project — re-render,
|
|
* `npm run render`, `--batch`, preview — is attributed to it on anonymous
|
|
* telemetry without the caller re-passing the flag.
|
|
*/
|
|
authoringSkill?: string;
|
|
/**
|
|
* Catalog items installed by `hyperframes add`, in install order. Append-only
|
|
* and deduped by name; removing an item from the project does not prune it,
|
|
* so a later render still reports it as installed-but-unused rather than
|
|
* silently forgetting it was ever tried.
|
|
*/
|
|
registryItems?: RegistryItemRecord[];
|
|
/**
|
|
* The reverse session `hyperframes reverse start` got from the server. Only a
|
|
* server that answered that call accepts it, so `cloud render` sends it only
|
|
* when it is here.
|
|
*/
|
|
reverseSessionId?: string;
|
|
}
|
|
|
|
export const DEFAULT_PROJECT_CONFIG: ProjectConfig = {
|
|
$schema: PROJECT_CONFIG_SCHEMA_URL,
|
|
registry: DEFAULT_REGISTRY_URL,
|
|
paths: {
|
|
blocks: "compositions",
|
|
components: "compositions/components",
|
|
assets: "assets",
|
|
},
|
|
media: {
|
|
autoProxy: true,
|
|
},
|
|
};
|
|
|
|
/** Path to the config file for a project rooted at `projectDir`. */
|
|
export function projectConfigPath(projectDir: string): string {
|
|
return join(resolve(projectDir), PROJECT_CONFIG_FILENAME);
|
|
}
|
|
|
|
/**
|
|
* Why a project-config read produced no config.
|
|
*
|
|
* Most callers only need "did I get one", but a caller reporting on the config
|
|
* must not treat a broken file as an absent one: a project whose config cannot
|
|
* be read is not a project without a config, and collapsing the two enrolls a
|
|
* failure into whatever the empty case means.
|
|
*/
|
|
export type ProjectConfigReadStatus = "ok" | "missing" | "unreadable";
|
|
|
|
/** Read `hyperframes.json`, distinguishing an absent file from a broken one. */
|
|
export function readProjectConfigWithStatus(projectDir: string): {
|
|
status: ProjectConfigReadStatus;
|
|
config?: ProjectConfig;
|
|
} {
|
|
const path = projectConfigPath(projectDir);
|
|
let text: string;
|
|
try {
|
|
text = readFileSync(path, "utf-8");
|
|
} catch (error) {
|
|
// Anything other than "not there" (permissions, I/O) is a real failure to
|
|
// read a config that may well exist.
|
|
return { status: isFileNotFound(error) ? "missing" : "unreadable" };
|
|
}
|
|
try {
|
|
return {
|
|
status: "ok",
|
|
config: normalizeConfig(JSON.parse(text.replace(/^\uFEFF/, "")) as Partial<ProjectConfig>),
|
|
};
|
|
} catch {
|
|
return { status: "unreadable" };
|
|
}
|
|
}
|
|
|
|
/** Read `hyperframes.json` from a project directory. */
|
|
export function readProjectConfig(projectDir: string): ProjectConfig | undefined {
|
|
// Missing file or corrupt JSON → no config.
|
|
return readProjectConfigWithStatus(projectDir).config;
|
|
}
|
|
|
|
/**
|
|
* Return a valid config — fills in any missing fields with defaults. Used
|
|
* when a user's config file is present but partial (e.g. they only set
|
|
* `registry` and rely on default paths).
|
|
*/
|
|
export function normalizeConfig(partial: Partial<ProjectConfig>): ProjectConfig {
|
|
return {
|
|
$schema: partial.$schema ?? DEFAULT_PROJECT_CONFIG.$schema,
|
|
registry: partial.registry ?? DEFAULT_PROJECT_CONFIG.registry,
|
|
paths: {
|
|
blocks: partial.paths?.blocks ?? DEFAULT_PROJECT_CONFIG.paths.blocks,
|
|
components: partial.paths?.components ?? DEFAULT_PROJECT_CONFIG.paths.components,
|
|
assets: partial.paths?.assets ?? DEFAULT_PROJECT_CONFIG.paths.assets,
|
|
},
|
|
media: {
|
|
autoProxy:
|
|
typeof partial.media?.autoProxy === "boolean"
|
|
? partial.media.autoProxy
|
|
: DEFAULT_PROJECT_CONFIG.media?.autoProxy,
|
|
},
|
|
// Slug-gate on read so a hand-edited or corrupt value never reaches the
|
|
// telemetry stream; an invalid slug simply drops the attribution.
|
|
authoringSkill: normalizeSkillSlug(partial.authoringSkill),
|
|
// Whitelist rebuild - an omission here silently drops the manifest on
|
|
// every config round-trip, which would read as "this project never
|
|
// installed a catalog item".
|
|
registryItems: normalizeRegistryItems(partial.registryItems),
|
|
reverseSessionId: normalizeReverseSessionId(partial.reverseSessionId),
|
|
};
|
|
}
|
|
|
|
const REVERSE_SESSION_ID = /^rvs_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
|
|
|
|
export function normalizeReverseSessionId(raw: unknown): string | undefined {
|
|
return typeof raw === "string" && REVERSE_SESSION_ID.test(raw) ? raw : undefined;
|
|
}
|
|
|
|
/**
|
|
* Keep only well-formed records. A hand-edited or partially-written manifest
|
|
* degrades to the entries that still parse rather than failing a command that
|
|
* merely wanted to read the registry URL.
|
|
*/
|
|
function normalizeRegistryItems(raw: unknown): RegistryItemRecord[] | undefined {
|
|
if (!Array.isArray(raw)) return undefined;
|
|
const items = raw.filter(
|
|
(entry): entry is RegistryItemRecord =>
|
|
isJsonObject(entry) &&
|
|
typeof entry.name === "string" &&
|
|
entry.name !== "" &&
|
|
typeof entry.type === "string" &&
|
|
typeof entry.target === "string",
|
|
);
|
|
return items.length > 0 ? items : undefined;
|
|
}
|
|
|
|
/** Write `hyperframes.json` to a project directory. Overwrites if present. */
|
|
export function writeProjectConfig(
|
|
projectDir: string,
|
|
config: ProjectConfig = DEFAULT_PROJECT_CONFIG,
|
|
): void {
|
|
const path = projectConfigPath(projectDir);
|
|
writeFileSync(path, JSON.stringify(config, null, 2) + "\n", "utf-8");
|
|
}
|
|
|
|
/** Create `hyperframes.json` without replacing an existing file or following a symlink. */
|
|
export function createProjectConfig(
|
|
projectDir: string,
|
|
config: ProjectConfig = DEFAULT_PROJECT_CONFIG,
|
|
): void {
|
|
writeNewFileSync(projectConfigPath(projectDir), JSON.stringify(config, null, 2) + "\n");
|
|
}
|
|
|
|
/**
|
|
* Load the project config for the given directory, falling back to defaults
|
|
* if missing. Mutates nothing on disk. Used by commands that want to operate
|
|
* with or without an explicit config.
|
|
*/
|
|
export function loadProjectConfig(projectDir: string): ProjectConfig {
|
|
return readProjectConfig(projectDir) ?? DEFAULT_PROJECT_CONFIG;
|
|
}
|
|
|
|
/**
|
|
* Resolve whether auto-proxying of browser-hostile video codecs (HEVC, etc.)
|
|
* is enabled for a project's live-preview surfaces. A caller's explicit
|
|
* `--proxy`/`--no-proxy` flag always wins over the project config, in either
|
|
* direction. Falls back to the committed `hyperframes.json`
|
|
* `media.autoProxy` setting, and finally to `true` when neither is set.
|
|
* Render is never affected by this setting: it always uses the original file.
|
|
*/
|
|
export function resolveAutoProxy(projectDir: string, flagValue: boolean | undefined): boolean {
|
|
if (typeof flagValue === "boolean") {
|
|
return flagValue;
|
|
}
|
|
return loadProjectConfig(projectDir).media?.autoProxy ?? true;
|
|
}
|
|
|
|
/** A parsed JSON value that can carry arbitrary keys — narrowed, not asserted. */
|
|
function isJsonObject(value: unknown): value is Record<string, unknown> {
|
|
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
}
|
|
|
|
/** Write a patched config back with the file's own indentation and byte order mark. */
|
|
function rewriteConfig(path: string, text: string, parsed: Record<string, unknown>): void {
|
|
const indent = /\n([ \t]+)"/.exec(text)?.[1] ?? " ";
|
|
writeFileSync(
|
|
path,
|
|
(text.startsWith("\uFEFF") ? "\uFEFF" : "") + JSON.stringify(parsed, null, indent) + "\n",
|
|
"utf-8",
|
|
);
|
|
}
|
|
|
|
/** True when a thrown filesystem error reports the path as absent. */
|
|
function isFileNotFound(error: unknown): boolean {
|
|
return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
|
|
}
|
|
|
|
/**
|
|
* Persist the owning authoring-skill slug into `hyperframes.json` so every
|
|
* later render of this project — re-render, `npm run render`, `--batch`,
|
|
* preview — is attributed to the workflow that created it, without the caller
|
|
* re-passing `--skill`.
|
|
*
|
|
* Seed-once: an existing stamp is never overwritten (the creating workflow owns
|
|
* the identity; a one-off `--skill` on a later render still governs that
|
|
* render's telemetry but does not rewrite the project's owner). An invalid or
|
|
* empty slug is ignored. Best effort: a read-only or missing project directory
|
|
* never fails the render it rode in on.
|
|
*
|
|
* One of the writers that touch an ALREADY EXISTING `hyperframes.json` (the
|
|
* others are {@link recordProjectRegistryItems} and
|
|
* {@link recordProjectReverseSession}; absent-only callers use
|
|
* {@link createProjectConfig}), so it must not
|
|
* round-trip through {@link normalizeConfig}:
|
|
* that rebuilds the object from a field whitelist, which would drop keys it
|
|
* does not know about and materialize defaults the user never wrote. The file
|
|
* is normally committed, so a render must not introduce a diff beyond the one
|
|
* key being added. Patch the parsed JSON in place instead, reusing the file's
|
|
* own indentation.
|
|
*/
|
|
export function seedProjectAuthoringSkill(projectDir: string, rawSkill: unknown): void {
|
|
const skill = normalizeSkillSlug(rawSkill);
|
|
if (!skill) return;
|
|
const path = projectConfigPath(projectDir);
|
|
|
|
// Read once and branch on why the read failed, rather than testing for the
|
|
// file first: an `existsSync`-then-write pair is a check-then-use race, and
|
|
// only a genuinely absent config may be created from scratch — any other
|
|
// read failure (permissions, I/O) must leave an existing file alone instead
|
|
// of overwriting it with a default.
|
|
let text: string;
|
|
try {
|
|
text = readFileSync(path, "utf-8");
|
|
} catch (error) {
|
|
if (isFileNotFound(error)) {
|
|
try {
|
|
createProjectConfig(projectDir, { ...DEFAULT_PROJECT_CONFIG, authoringSkill: skill });
|
|
} catch {
|
|
// Read-only or missing project directory — best effort.
|
|
}
|
|
}
|
|
return;
|
|
}
|
|
|
|
try {
|
|
const parsed: unknown = JSON.parse(text.replace(/^\uFEFF/, ""));
|
|
// A malformed config is left untouched rather than clobbered by a render.
|
|
if (!isJsonObject(parsed)) return;
|
|
// Seed-once. Normalized so a hand-edited garbage slug neither reaches
|
|
// telemetry nor wedges the seed — the next `--skill` render heals it.
|
|
if (normalizeSkillSlug(parsed.authoringSkill)) return;
|
|
parsed.authoringSkill = skill;
|
|
rewriteConfig(path, text, parsed);
|
|
} catch {
|
|
// Corrupt JSON, or a read-only file: attribution is best-effort telemetry,
|
|
// never a render blocker.
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Append installed catalog items to `hyperframes.json` so a later render can
|
|
* report which of them the finished video actually used.
|
|
*
|
|
* Same in-place patch discipline as {@link seedProjectAuthoringSkill}, and for
|
|
* the same reason: this writes an ALREADY EXISTING, normally committed config,
|
|
* so it must not round-trip through {@link normalizeConfig} (a whitelist
|
|
* rebuild would drop unknown keys and materialize defaults the user never
|
|
* wrote). Existing entries are kept and deduped by name, so re-adding an item
|
|
* does not grow the file and a manually pruned entry is not resurrected twice.
|
|
*
|
|
* Best effort throughout: a read-only project, a missing config, or corrupt
|
|
* JSON must never fail the `add` it rode in on.
|
|
*/
|
|
export function recordProjectRegistryItems(
|
|
projectDir: string,
|
|
items: readonly RegistryItemRecord[],
|
|
): void {
|
|
if (items.length === 0) return;
|
|
const path = projectConfigPath(projectDir);
|
|
|
|
let text: string;
|
|
try {
|
|
text = readFileSync(path, "utf-8");
|
|
} catch {
|
|
// No config to patch. `add` outside an initialized project is a valid
|
|
// flow; it simply leaves no manifest behind.
|
|
return;
|
|
}
|
|
|
|
try {
|
|
const parsed: unknown = JSON.parse(text.replace(/^\uFEFF/, ""));
|
|
if (!isJsonObject(parsed)) return;
|
|
const existing = normalizeRegistryItems(parsed.registryItems) ?? [];
|
|
const byName = new Map(existing.map((item) => [item.name, item]));
|
|
for (const item of items) byName.set(item.name, item);
|
|
// Compare by value, not identity: `add` always constructs fresh record
|
|
// objects, so an identity check would never match and re-adding an
|
|
// unchanged item would rewrite the file on every install.
|
|
const merged = [...byName.values()];
|
|
const unchanged =
|
|
merged.length === existing.length &&
|
|
merged.every((item, index) => {
|
|
const prior = existing[index];
|
|
return (
|
|
prior !== undefined &&
|
|
prior.name === item.name &&
|
|
prior.type === item.type &&
|
|
prior.target === item.target
|
|
);
|
|
});
|
|
if (unchanged) return;
|
|
parsed.registryItems = merged;
|
|
rewriteConfig(path, text, parsed);
|
|
} catch {
|
|
// Corrupt JSON or a read-only file: the manifest is telemetry provenance,
|
|
// never an install blocker.
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Save the reverse session into the project, creating the folder and a default
|
|
* `hyperframes.json` when neither exists yet (`init` keeps that file). An
|
|
* existing config is patched in place, like {@link seedProjectAuthoringSkill}.
|
|
* Returns the config path, or undefined when nothing could be written.
|
|
*/
|
|
export function recordProjectReverseSession(
|
|
projectDir: string,
|
|
sessionId: string,
|
|
authoringSkill: string,
|
|
): string | undefined {
|
|
if (!normalizeReverseSessionId(sessionId)) return undefined;
|
|
const path = projectConfigPath(projectDir);
|
|
let text: string;
|
|
try {
|
|
text = readFileSync(path, "utf-8");
|
|
} catch (error) {
|
|
if (!isFileNotFound(error)) return undefined;
|
|
try {
|
|
mkdirSync(resolve(projectDir), { recursive: true });
|
|
createProjectConfig(projectDir, {
|
|
...DEFAULT_PROJECT_CONFIG,
|
|
authoringSkill: normalizeSkillSlug(authoringSkill),
|
|
reverseSessionId: sessionId,
|
|
});
|
|
return path;
|
|
} catch {
|
|
return undefined;
|
|
}
|
|
}
|
|
try {
|
|
const parsed: unknown = JSON.parse(text.replace(/^\uFEFF/, ""));
|
|
if (!isJsonObject(parsed)) return undefined;
|
|
parsed.reverseSessionId = sessionId;
|
|
if (!normalizeSkillSlug(parsed.authoringSkill)) {
|
|
const skill = normalizeSkillSlug(authoringSkill);
|
|
if (skill) parsed.authoringSkill = skill;
|
|
}
|
|
rewriteConfig(path, text, parsed);
|
|
return path;
|
|
} catch {
|
|
return undefined;
|
|
}
|
|
}
|