Files
hyperframes/packages/cli/src/utils/projectConfig.ts
T
Wenbo ZhuandClaude Opus 5.5 7d3c225207 feat(cli): reverse start records a reverse run; cloud render carries its session (#7016)
* 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>
2026-11-02 16:47:05 +00:00

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