WaterrrForever
d287e5244c
* 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.
11 KiB
name, description
| name | description |
|---|---|
| hyperframes-cli | Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local, HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering. |
HyperFrames CLI
Run commands as npx hyperframes ... unless project instructions provide a wrapper. Obey the wrapper when present. The CLI requires Node.js 22 or newer and FFmpeg.
Development loop
- Scaffold:
npx hyperframes init <project>or capture a site. In non-TTY mode, pass--non-interactive --example=<name>. - Author: write the composition using
/hyperframes-core. - Get fast feedback while editing: run
npx hyperframes lintafter the first HTML pass and after structural changes. - Run the final gate: run
npx hyperframes check; it reruns lint before opening the browser. Do not prepend a redundant standalone lint invocation. Add--snapshotsfor annotated overview frames and finding crops. - Inspect sub-compositions: when
index.htmlmountsdata-composition-src, capture midpoint snapshots and inspect each mounted scene. - Open the final Studio preview: run
npx hyperframes preview, hand the timeline project URL to the user, and ask whether to revise or render. - Render only after approval: use draft quality for iteration and high quality for delivery.
- Verify the output: confirm the file exists, is non-empty, and has a plausible duration.
# Fast iteration check; repeat while authoring as needed.
npx hyperframes lint
# Required final gate; includes lint.
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4
check runs lint first, then uses one browser session and one seek pass to audit runtime errors, failed requests, layout, *.motion.json assertions, and WCAG contrast. Persistent findings gate the exit code; transient entrance or exit findings are informational. Use --strict to gate warnings. validate, inspect, and layout remain aliases for compatibility but must not appear in new instructions or scripts.
Two different preview surfaces
Do not confuse these states:
| Surface | When it may open | Purpose |
|---|---|---|
| Storyboard board | Before composition checks, only when storyboard: yes |
Review plan cards and wireframe sketches. Open ?view=storyboard#project/<name>. |
| Final composition preview | After check passes |
Review the assembled timeline before render. Open #project/<name>. |
The early board is not approval of the final video. Rendering always requires the final approval defined by hyperframes-core/references/review-loop.md.
Sub-composition smoke test
Static audits cannot catch every mount failure. When the project uses sub-compositions, capture at least one visible midpoint for each host slot:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Treat tiny unstyled content, canvas-sized icons, missing hero elements, or timeline-registration timeouts as render-blocking mount defects. See hyperframes-core/references/sub-compositions.md for the corresponding fixes.
Agent conventions
-
Prefer
--jsonfor agent and CI calls. Server-moderender,preview, andplaydo not provide ordinary JSON output;preview --selection --jsonandpreview --context --jsonare query-mode exceptions. -
doctor --jsonalways exits zero. Gate on its payload:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
Non-TTY mode is automatic.
initrequires--examplethere; use--non-interactiveto force deterministic behavior on a TTY. -
Use one
HYPERFRAMES_RUN_IDfor all commands in the same verification loop. -
Use
--strict,--strict-all, and--strict-variableswhen the corresponding warnings, variables, or CI conditions must gate the render. -
JSON paths redact the home directory as
$HOME; do not try to reverse the redaction. -
When a hosted cloud project approaches or exceeds the 200 MB upload limit, use
cloud render --dry-run --jsonand follow the.hyperframesignoreinvestigation inreferences/cloud.md. Never ignore an asset merely because it is large. -
Never render merely because checks pass. Pause at the final preview and wait for approval.
Studio-directed edits
When the user refers to “this element” or the current selection, query Studio instead of guessing:
npx hyperframes preview --context --json --context-fields selection
Use selection.target.hfId when available, otherwise its selector and source file. If the result reports no-selection, ask the user to click the element and rerun. Request only the context slices you need; use --context-detail full only for computed styles or editable text metadata. Full behavior and failure codes live in references/preview-render.md.
Render choices
| Need | Command |
|---|---|
| Fast local iteration | npx hyperframes render --quality draft |
| Final local delivery | npx hyperframes render --quality high --output out.mp4 |
| Reproducible container render | npx hyperframes render --docker --strict --output out.mp4 |
| Local variable-driven batch render | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| HeyGen-hosted zero-infrastructure render | npx hyperframes cloud render |
| Self-managed distributed AWS render | npx hyperframes lambda render <project> --width 1920 --height 1080 --wait |
| Self-managed distributed GCP render | npx hyperframes cloudrun render <project> --width 1920 --height 1080 --wait |
Skill attribution is automatic — the examples above need no --skill. A project scaffolded by a workflow (hyperframes init --skill=<workflow>) records its owning skill in hyperframes.json, and every later render inherits it on anonymous telemetry: re-renders, npm run render, and --batch alike. Pass --skill=<slug> explicitly only to stamp a project that was not created through a workflow (its first render then persists it).
Use cloud rendering when the user wants hosted rendering without local Chrome, FFmpeg, or AWS. Use Lambda only when AWS ownership is a requirement. Use Cloud Run only when GCP ownership is a requirement. Read the matching reference before running any cloud path.
After verifying a successful render, send one feedback report unless telemetry is disabled or the user opted out:
npx hyperframes feedback --rating <0-10> --comment "<specific result or friction>"
Keep clean-run feedback concise. For any bug or friction, capture a reproduction packet before submitting; do not send only a symptom summary. Include the rerunnable command (relative to the project directory — feedback is submitted to a public channel, so do not paste absolute paths, home-directory prefixes, or user/machine identifiers), expected versus actual behavior, exact error (also strip absolute paths from stack traces — keep basename + line, drop the leading directory), whether output completed/fell back/failed, workaround, and repro-project status. For a rating ≤ 7 that describes a visual defect (black frame, flicker, corrupt output, wrong frame, blank output, other visual anomaly), also include a COMPOSITION_STRUCTURE: block — a privacy-preserving structural anatomy (element census + attribute presence + timeline shape) so maintainers can pattern-match against known bug families without the composition ZIP. Agents auto-fill this via the composition-census helper; the human user does not fill it by hand. If the issue did not reproduce again, say so and still include the last failing command and logs. Use --file-issue only with consent: it publishes a minimal reproduction to a public URL. The required packet format and privacy warning live in references/preview-render.md.
Read the matching reference before running a command
The following references and owning skills are mandatory command contracts, not optional background reading. Before running a command in the table, read its matching row.
| Need | Reference |
|---|---|
init, capture, skills |
references/init-and-scaffold.md |
lint, check, motion sidecars, snapshot |
references/lint-validate-inspect.md |
compare, grade-compare, variable-driven render --batch |
references/compare-and-batch.md |
beats for an existing project's Studio beat grid |
references/beats.md |
preview, play, render, publish, Studio context, feedback |
references/preview-render.md |
doctor, browser management |
references/doctor-browser.md |
auth, HeyGen-hosted cloud rendering, and template variables |
references/cloud.md |
| AWS Lambda deployment and rendering | references/lambda.md |
| Google Cloud Run deployment and rendering | references/cloudrun.md |
info, upgrade, compositions, docs, benchmark, telemetry, media preprocessing |
references/upgrade-info-misc.md |
For composition variables, also read /hyperframes-core → references/variables-and-media.md. For hyperframes add and hyperframes catalog, use /hyperframes-registry. Before hyperframes present, read /slideshow; before hyperframes keyframes, read /hyperframes-keyframes. For TTS, transcription, captions, or background removal choices, use /media-use.
The specialized commands are deliberately documented by their owning workflows:
npx hyperframes present <project-dir> --port 3004 --no-open
npx hyperframes beats <project-dir> --json
npx hyperframes keyframes <project-dir> --json
present serves a navigable deck with presenter and audience synchronization. beats is the standalone Studio beat-grid utility defined in references/beats.md. keyframes surfaces seek-safe animation and motion-path diagnostics.