Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { validRegistryItem } from "./validation.js";
import { registryRoot, registryTargetPath, publishRegistryFile } from "./publication.js";
import type { DownloadByteBudget } from "../capture/readBoundedResponse.js";
/**
* Registry installer — copies item files into a destination project.
*
* The top-level directory used under the source registry is determined by the
* item's `type` (examples/blocks/components). Target paths are validated at
* runtime to reject traversal even if the registry JSON schema was bypassed.
*/
import { createHash } from "node:crypto";
import { existsSync, readFileSync } from "node:fs";
import { resolve, relative, isAbsolute } from "node:path";
import type { FileTarget, RegistryItem } from "@hyperframes/core";
import { fetchItemFile, DEFAULT_REGISTRY_URL } from "./remote.js";
import {
applyVariableDefaults,
InvalidVariableValuesError,
type ApplyResult,
} from "./variableDefaults.js";
export interface InstallOptions {
/** Project root where files land. Every target resolves relative to this. */
destDir: string;
/** Base URL of the registry. Defaults to the official public registry. */
baseUrl?: string;
/** Overwrite files the project has changed since they were installed. */
force?: boolean;
/**
* `--vars` values to bake into a COMPONENT's declared defaults. A block
* carries its values on the mount element instead, so this is ignored there:
* per-mount values are strictly better when a mount exists.
*/
variableValues?: Record<string, unknown> | null;
}
export interface InstallResult {
/** Absolute paths of files actually written. */
written: string[];
/** Absolute paths left alone because the project had changed them. */
preserved: string[];
/** Variable ids whose default was rewritten in an installed component. */
variablesApplied: string[];
/** Ids the item does not declare, and ids it declares but cannot accept. */
variablesUnknown: string[];
}
/**
* What each installed file looked like when we installed it.
*
* Reinstalling an item used to overwrite whatever was on disk, so a project
* that had tuned a block's colours lost that work to the next `add`. Comparing
* the file against the hash we recorded is what tells an untouched file, which
* is safe to replace, apart from an edited one, which is not.
*/
const INSTALL_RECORD = "hyperframes.lock.json";
type InstallRecord = Record<string, string>;
function digest(contents: Buffer | string): string {
return createHash("sha256").update(contents).digest("hex");
}
function readInstallRecord(destDir: string): InstallRecord {
const path = registryTargetPath(destDir, INSTALL_RECORD);
if (!existsSync(path)) return {};
try {
const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
// A hand-edited or truncated record must not take the project's files with
// it: an unreadable record means "provenance unknown", which is the
// cautious answer everywhere it is used.
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
const record: InstallRecord = {};
for (const [target, hash] of Object.entries(parsed as Record<string, unknown>)) {
if (typeof hash === "string") record[target] = hash;
}
return record;
} catch {
return {};
}
}
function writeInstallRecord(destDir: string, record: InstallRecord): void {
const sorted = Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
publishRegistryFile(destDir, INSTALL_RECORD, `${JSON.stringify(sorted, null, 2)}\n`);
}
/** Re-record files an install wrote and its caller then rewrote, so they still read as unedited. */
export function recordRewrittenInstall(destDir: string, written: string[]): void {
if (written.length === 0) return;
const root = registryRoot(destDir);
const record = readInstallRecord(root);
const rewritten = new Set(written);
for (const target of Object.keys(record)) {
let path: string;
try {
path = registryTargetPath(root, target);
} catch {
continue; // a key that no longer resolves, or that the installer would refuse
}
if (rewritten.has(path)) record[target] = digest(readFileSync(path));
}
writeInstallRecord(root, record);
}
/**
* Has the project changed this file since we installed it?
*
* A file we have no record of counts as changed. That covers the project that
* wrote the file itself, and the one that installed before this record existed;
* both would rather keep their file than have it silently replaced.
*/
export function hasLocalEdits(
record: InstallRecord,
target: string,
onDisk: Buffer | string,
): boolean {
const installed = record[target];
if (!installed) return true;
return installed !== digest(onDisk);
}
/** An install must leave this file alone: the project changed it, and `--force` was not given. */
function keptByProject(
record: InstallRecord,
destPath: string,
target: string,
force: boolean | undefined,
): boolean {
return !force && existsSync(destPath) && hasLocalEdits(record, target, readFileSync(destPath));
}
/**
* Reject target paths that would escape `destDir`. Mirrors the pattern check
* in `packages/core/schemas/registry-item.json#files.items.target`, but runs at
* install time so a registry that bypasses schema validation still can't write
* outside the project.
*/
function assertSafeTarget(destDir: string, target: string): void {
if (isAbsolute(target)) {
throw new Error(`Unsafe target "${target}": absolute paths are not allowed.`);
}
if (/(^|[/\\])\.\.([/\\]|$)/.test(target)) {
throw new Error(`Unsafe target "${target}": path segments may not contain "..".`);
}
if (/^[A-Za-z]:[/\\]/.test(target)) {
throw new Error(`Unsafe target "${target}": Windows drive letters are not allowed.`);
}
const resolved = resolve(destDir, target);
const rel = relative(resolve(destDir), resolved);
if (rel.startsWith("..") || isAbsolute(rel)) {
throw new Error(`Unsafe target "${target}": resolves outside destDir ${destDir}.`);
}
}
/** A component's pasteable markup: the file whose declared defaults `--vars` edits. */
function isInstalledComponentSnippet(item: RegistryItem, file: FileTarget): boolean {
return item.type === "hyperframes:component" && file.target.toLowerCase().endsWith(".html");
}
function isInstalledRegistryBlockComposition(item: RegistryItem, file: FileTarget): boolean {
return (
item.type === "hyperframes:block" &&
file.type === "hyperframes:composition" &&
file.target.toLowerCase().endsWith(".html")
);
}
function addRegistryItemMarker(source: string, item: RegistryItem): string {
if (/^\s*<!--\s*hyperframes-registry-item:[^>]*-->/i.test(source.slice(0, 512))) {
return source;
}
return `<!-- hyperframes-registry-item: ${item.name} -->\n${source}`;
}
export interface FileOutcome {
destPath: string;
target: string;
preserved: boolean;
hash: string | null;
vars: ApplyResult | null;
/** What to write; null for a preserved file. */
bytes: Buffer | null;
}
/**
* Check `--vars` against the file that declares them. A block's values ride on
* its mount, so only a component's own declaration is rewritten.
*/
function bakeVariables(
item: RegistryItem,
file: FileTarget,
bytes: Buffer,
values: Record<string, unknown> | null | undefined,
): { bytes: Buffer; vars: ApplyResult | null } {
const component = isInstalledComponentSnippet(item, file);
if (!values || !(component || isInstalledRegistryBlockComposition(item, file))) {
return { bytes, vars: null };
}
const vars = applyVariableDefaults(bytes.toString("utf8"), values);
const rewrite = component && vars.applied.length > 0;
return { bytes: rewrite ? Buffer.from(vars.html) : bytes, vars };
}
/** Fetch and post-process one file; publishItem writes it once the whole plan is ready. */
async function prepareOneFile(
item: RegistryItem,
file: FileTarget,
destDir: string,
baseUrl: string,
record: InstallRecord,
options: InstallOptions,
budget: DownloadByteBudget,
): Promise<FileOutcome> {
const destPath = registryTargetPath(destDir, file.target);
// Decided before fetching rather than after: a file we are going to keep
// should never be overwritten and then put back, because a crash in
// between would lose it for real.
if (keptByProject(record, destPath, file.target, options.force)) {
return { destPath, target: file.target, preserved: true, hash: null, vars: null, bytes: null };
}
let bytes = await fetchItemFile(item, file, baseUrl, budget);
if (isInstalledRegistryBlockComposition(item, file)) {
bytes = Buffer.from(addRegistryItemMarker(bytes.toString("utf8"), item));
}
const baked = bakeVariables(item, file, bytes, options.variableValues);
bytes = baked.bytes;
const vars = baked.vars;
// Hash what will land, marker and baked defaults included, or the next
// install reads its own output as the project's edit.
return {
destPath,
target: file.target,
preserved: false,
hash: digest(bytes),
vars,
bytes,
};
}
/**
* Install a resolved `RegistryItem` into `destDir` by fetching each file in
* parallel and writing it to its validated target path.
*/
export async function installItem(
item: RegistryItem,
options: InstallOptions,
): Promise<InstallResult> {
return publishItem(await prepareItem(item, options));
}
/** An item fetched and checked, with nothing written yet. */
export interface PreparedItem {
root: string;
outcomes: FileOutcome[];
force: boolean;
}
/** Fetch and check every file of an item without writing, so a caller can refuse a whole plan. */
export async function prepareItem(
item: RegistryItem,
options: InstallOptions,
): Promise<PreparedItem> {
if (!validRegistryItem(item, item.name, item.type)) throw new Error("Invalid registry item");
const baseUrl = options.baseUrl ?? DEFAULT_REGISTRY_URL;
const destDir = resolve(options.destDir);
// Validate all targets up-front so a malformed item fails before any write.
for (const file of item.files) {
assertSafeTarget(destDir, file.target);
}
const root = registryRoot(destDir);
validatePhysicalTargets(root, item.files);
const record = readInstallRecord(root);
const budget = { remainingBytes: 512 * 1024 * 1024 };
const outcomes = await installFileBatches(item.files, (file) =>
prepareOneFile(item, file, root, baseUrl, record, options, budget),
);
const invalid = outcomes.flatMap((o) => o.vars?.invalid ?? []);
if (invalid.length > 0) throw new InvalidVariableValuesError(invalid);
return { root, outcomes, force: options.force ?? false };
}
/** Write a prepared item and record what landed. */
export function publishItem({ root, outcomes: prepared, force }: PreparedItem): InstallResult {
// Read now, not at prepare time: another item published in between has recorded its own files.
const record = readInstallRecord(root);
// Asked again at write time: a save made while the rest of the plan downloaded is still an edit.
const outcomes = prepared.map((o) =>
o.bytes && keptByProject(record, o.destPath, o.target, force)
? { ...o, preserved: true, hash: null, vars: null, bytes: null }
: o,
);
for (const outcome of outcomes) {
if (outcome.bytes) publishRegistryFile(root, outcome.target, outcome.bytes);
}
const written = outcomes.filter((o) => !o.preserved).map((o) => o.destPath);
const preserved = outcomes.filter((o) => o.preserved).map((o) => o.destPath);
if (written.length > 0) {
for (const outcome of outcomes) {
if (outcome.hash) record[outcome.target] = outcome.hash;
}
writeInstallRecord(root, record);
}
const vars = outcomes.map((o) => o.vars).filter((v): v is ApplyResult => v !== null);
return {
written,
preserved,
variablesApplied: vars.flatMap((v) => v.applied),
// An id nothing declared is only genuinely unknown once every file has had
// a chance at it, so intersect rather than union.
variablesUnknown: vars.length
? vars.reduce<string[]>(
(acc, v) => acc.filter((id) => v.unknown.includes(id)),
vars[0]!.unknown,
)
: [],
};
}
function validatePhysicalTargets(root: string, files: FileTarget[]): void {
const targets = new Set<string>();
const aliasKey = (path: string): string =>
process.platform === "win32" || process.platform === "darwin"
? path.normalize("NFC").toLowerCase()
: path;
const recordKey = aliasKey(registryTargetPath(root, INSTALL_RECORD));
for (const file of files) {
const path = registryTargetPath(root, file.target);
const key = aliasKey(path);
if (targets.has(key) || key === recordKey)
throw new Error("Unsafe target: duplicate or reserved install record");
targets.add(key);
}
}
async function installFileBatches(
files: FileTarget[],
prepare: (file: FileTarget) => Promise<FileOutcome>,
): Promise<FileOutcome[]> {
const outcomes: FileOutcome[] = [];
for (let at = 0; at < files.length; at += 4) {
const batch = await Promise.allSettled(files.slice(at, at + 4).map(prepare));
for (const result of batch) {
if (result.status === "rejected") throw result.reason;
outcomes.push(result.value);
}
}
return outcomes;
}