mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-16 14:27:26 +00:00
* fix(studio): reload the preview only when a file it loaded changes * test(studio): read the owner id from the new change-owner shape * refactor(studio): drop a comment the parser name already says * fix(studio): keep reloading until the preview is built, and count what its document names * style(studio): format the reference pattern and name the kept reload * fix(studio-server): scan preview references in linear time and refresh all thumbnails on a merged reload * fix(studio): keep a waiting film change when a file the preview never loaded arrives behind it * test(studio): name the preview ownership test for what it checks * chore(ci): allow the watchIgnore removals and trim the new comments * fix(studio-server): reload the preview when a folder holding a file it loaded moves in or out * perf(studio-server): check a changed folder in one lookup and cover every reference form * fix(studio-server): record read folders for a project at the filesystem root * fix(studio-server): reload the preview when the file a symlinked asset points at changes * fix(studio-server): resolve symlinks on every preview read and key projects by their real folder * fix(studio-server): record every link a preview read passes through, resolved as the system does
355 lines
14 KiB
TypeScript
355 lines
14 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 { 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-workflow skill slug (e.g. "product-launch-video"). 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[];
|
|
}
|
|
|
|
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) 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),
|
|
};
|
|
}
|
|
|
|
/**
|
|
* 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);
|
|
}
|
|
|
|
/** 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 two writers that touch an ALREADY EXISTING `hyperframes.json` (the
|
|
* other is {@link recordProjectRegistryItems}; 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);
|
|
// 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;
|
|
const indent = /\n([ \t]+)"/.exec(text)?.[1] ?? " ";
|
|
writeFileSync(path, JSON.stringify(parsed, null, indent) + "\n", "utf-8");
|
|
} 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);
|
|
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;
|
|
const indent = /\n([ \t]+)"/.exec(text)?.[1] ?? " ";
|
|
writeFileSync(path, JSON.stringify(parsed, null, indent) + "\n", "utf-8");
|
|
} catch {
|
|
// Corrupt JSON or a read-only file: the manifest is telemetry provenance,
|
|
// never an install blocker.
|
|
}
|
|
}
|