Files
hyperframes/packages/cli/src/utils/projectConfig.ts
T
Miguel Ángel e00baefb5c fix(studio): reload the preview only when a file it loaded changes (#4570)
* 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
2026-09-27 10:05:53 +00:00

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