2026-04-17 17:43:43 +02:00
{
"$schema" : "https://json-schema.org/draft/2020-12/schema" ,
"$id" : "https://hyperframes.heygen.com/schema/hyperframes.json" ,
"title" : "Hyperframes Project Config" ,
"description" : "Per-project configuration for a Hyperframes project (hyperframes.json). Tells `hyperframes add` which registry to pull items from and where to drop them in the project tree. Created by `hyperframes init`; users may edit it to point at custom registries or reshape their project layout." ,
"type" : "object" ,
"required" : [ "registry" , "paths" ] ,
"additionalProperties" : false ,
"properties" : {
"$schema" : {
"type" : "string" ,
"format" : "uri" ,
"description" : "JSON Schema URL — https://hyperframes.heygen.com/schema/hyperframes.json."
} ,
"registry" : {
"type" : "string" ,
"format" : "uri" ,
"minLength" : 1 ,
"description" : "Base URL of the registry to pull items from. Point at the official Hyperframes registry or a custom one."
} ,
"paths" : {
"type" : "object" ,
"description" : "Target paths for each item type, relative to the project root." ,
"required" : [ "blocks" , "components" , "assets" ] ,
"additionalProperties" : false ,
"properties" : {
"blocks" : {
"type" : "string" ,
"minLength" : 1 ,
"description" : "Where `hyperframes:block` items land. Defaults to `compositions`."
} ,
"components" : {
"type" : "string" ,
"minLength" : 1 ,
"description" : "Where `hyperframes:component` items land. Defaults to `compositions/components`."
} ,
"assets" : {
"type" : "string" ,
"minLength" : 1 ,
"description" : "Where asset files (images, fonts, videos) land. Defaults to `assets`."
}
}
2026-07-16 23:01:14 -04:00
} ,
"media" : {
"type" : "object" ,
"description" : "Media handling options." ,
"additionalProperties" : false ,
"properties" : {
"autoProxy" : {
"type" : "boolean" ,
"description" : "Automatically create H.264 proxies for browser-hostile video codecs on supported preview surfaces. Defaults to true."
}
}
fix(cli): persist authoring skill in hyperframes.json for durable render attribution (#2762)
* fix(cli): persist authoring skill in hyperframes.json for durable render attribution
authoring_skill was stamped only on the first render through a workflow
passing --skill, so re-renders, `npm run render`, --batch, existing-project
renders, and general-video lost it — leaving 77-96% of real-human render
volume un-attributed and the skills-penetration metric misleadingly low.
Persist the owning skill in hyperframes.json: `init --skill` stamps it at
creation, `render` resolves the flag then falls back to the stored value, and
an explicit --skill seeds it (seed-once, never overwriting the creating
workflow's identity). Activate all render-producing creation workflows to
declare their skill at init.
Forward-only: does not rewrite historical telemetry.
* fix(cli): patch hyperframes.json in place when seeding the authoring skill
seedProjectAuthoringSkill is the only writer that touches an already existing
hyperframes.json — every other writeProjectConfig call site is guarded to write
only when the file is absent, which made the whole-file overwrite safe by
construction. Round-tripping the seed through normalizeConfig broke that: it
rebuilds the object from a field whitelist with no rest-spread, so any key
outside the schema was silently dropped, a media block was materialized in
projects that never had one, and key order was rewritten. hyperframes.json is
normally committed, so a render introduced a diff the user never asked for, and
any field added to the schema later would be deleted by a render on an older
CLI.
Parse the raw JSON, set authoringSkill, write it back, reusing the file's own
indentation. Unknown keys and formatting survive; the only delta is the key
being added. A corrupt config is now left untouched instead of clobbered.
Seed-once semantics are unchanged, still normalized so a hand-edited garbage
slug neither reaches telemetry nor wedges the seed.
Reported independently by both reviewers on #2762.
* fix(cli): create the docker build context with mkdtempSync
The `--docker` build context was created at a guessable path derived from
`Date.now()` in the world-writable OS temp dir. Another local user can
pre-create or symlink that path and have the build read a Dockerfile they
control. mkdtempSync gets a random suffix and 0o700 from the kernel, and it
creates the directory itself, so the separate mkdirSync goes away.
Pre-existing on main (alert #432, 2026-06-04, packages/cli/src/commands/render.ts),
surfaced against this branch only because the seed commit shifted line numbers in
the same file. Fixed here to unblock the CodeQL gate on #2762 rather than left for
a follow-up; the remaining 10 js/insecure-temporary-file alerts elsewhere in the
repo are untouched and still want their own pass.
* fix(cli): drop the check-then-use race when seeding the authoring skill
The seed tested for the config with existsSync and then wrote, which is a
check-then-use race: the file can be created or swapped between the check and
the write (CodeQL js/file-system-race).
Read once and branch on the failure reason instead. Only ENOENT creates a
config from scratch; any other read failure (permissions, I/O) now leaves an
existing file alone rather than overwriting it with a default, so this is also
strictly safer than the version it replaces.
Also replaces the `as Record<string, unknown>` assertion with an isJsonObject
type guard, per the repo's no-assertion convention.
Behaviour unchanged: all 4 seed regression tests still pass, and the
create/preserve/seed-once/corrupt-untouched paths were re-verified end to end.
2026-07-28 19:27:09 +08:00
} ,
"authoringSkill" : {
"type" : "string" ,
"pattern" : "^[a-z0-9][a-z0-9-]{0,63}$" ,
"description" : "Owning authoring-workflow skill slug (e.g. product-launch-video). Set by `hyperframes init --skill` or seeded from the first `hyperframes render --skill`; every render of this project is then attributed to it on anonymous telemetry, without re-passing the flag."
2026-04-17 17:43:43 +02:00
}
}
}
