mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* fix(cli): fixed-name outputs and history turn records replace a link, never write through it transcript.json, hyperframes.json patches, the grade-compare sheet, the batch manifest, diff and measure outputs, lambda stack state and the history turn records are written through a temp file renamed into place. A linked hyperframes.json is left alone, and the default .hyperframes/<tool> output folder is used only when every folder on the way is real. * fix(cli): measure and diff pictures and sbs.mp4 replace a link, never write through it writeImage and the diff side-by-side now have ffmpeg write into a new private folder beside the output, then rename the file over its name. measure frames already staged and renamed its PNGs.
428 lines
16 KiB
TypeScript
428 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 { lstatSync, mkdirSync, readFileSync } from "node:fs";
|
|
import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
|
|
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 {
|
|
replaceFileAtomically(projectConfigPath(projectDir), JSON.stringify(config, null, 2) + "\n");
|
|
}
|
|
|
|
/** 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] ?? " ";
|
|
const stats = lstatSync(path);
|
|
if (!stats.isFile())
|
|
throw new Error(`${path} is a link or not a plain file, so it is left alone`);
|
|
replaceFileAtomically(
|
|
path,
|
|
(text.startsWith("\uFEFF") ? "\uFEFF" : "") + JSON.stringify(parsed, null, indent) + "\n",
|
|
stats.mode & 0o777,
|
|
);
|
|
}
|
|
|
|
/** 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;
|
|
}
|
|
}
|