mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
WaterrrForever
f8c33cab72
* feat(skills): probe and bump stale CLI pins during project resume
The entry skill now keeps a resumed project's pinned CLI current instead of
leaving that to a notice nobody acts on. On resuming a project with pinned
scripts, run the read-only probe 'npx hyperframes@latest upgrade --project
. --check'; when it (or the stale-pin stderr notice, or _meta.updateAvailable
from a pinned run) reports the project behind, apply the bump and verify
with 'hyperframes check'. A failed check reverts the bump and keeps the
project on its pinned version, preserving the reproducibility contract the
pin exists for.
The probe matters because the stale-pin notice only exists in >= 0.7.59:
a pinned run of an older CLI prints no warning at all, so a notice-only
trigger never fires for exactly the projects most behind. The probe runs
unpinned, so its behavior never depends on the project's CLI age.
Telemetry: the fleet converges to new releases within about a week via the
background auto-updater and ephemeral npx, but pinned projects form a
persistent stale tail (~10% of weekly actives, e.g. 6.3k users still on
0.6.x three weeks after 0.7.0).
Both skill surfaces now pass an explicit dir ('--project .') because a bare
'--project' followed by another flag consumes that flag as its directory
value and no-ops; the parsing fix is a separate CLI change.
* fix(cli): stop bare --project from eating the next flag as its directory
citty parses --project as a string option, so 'upgrade --project --check'
arrived with project="--check": the dir resolved to a nonexistent path and
the command no-opd with 'No package.json found' while --check was lost.
The documented default-cwd behavior only worked when --project was the
final token — and the trap-prone form is exactly what the scaffolded
template CLAUDE.md instructs.
A leading dash can never be a real directory argument, so resolveProjectArgs
now reclaims the eaten token as the flag the user wrote (--check / --json),
falls back to the current directory, and drops unrelated eaten flags rather
than treating them as paths. Templates and skill references switch to the
explicit-dir form ('--project .'), which behaves correctly on every release
including ones that predate this fix.
* feat(skills): report a successful pin bump in the run summary
Review follow-up on the stale-pin rule: 'hyperframes check' validates
composition structure, not render-output equivalence, so a check-passing
bump can still shift a project's rendered output. The bump stays the right
default for stale projects, but it must not be silent — the summary now
names the old and new version so the user knows the reproducibility
trade was made.
78 lines
4.1 KiB
Markdown
78 lines
4.1 KiB
Markdown
# info, upgrade, compositions, docs, benchmark, telemetry, asset preprocessing
|
|
|
|
Catch-all reference for commands that don't fit the main dev loop.
|
|
|
|
## info
|
|
|
|
```bash
|
|
npx hyperframes info # project metadata
|
|
npx hyperframes info ./my-video # specific project
|
|
npx hyperframes info --json
|
|
```
|
|
|
|
Prints **project** metadata: name, resolution, duration, element counts by type, track count, and total project size. Project-level — not environment. For environment health use `doctor`.
|
|
|
|
## upgrade
|
|
|
|
```bash
|
|
npx hyperframes upgrade # check + interactive prompt
|
|
npx hyperframes upgrade --check # check and exit, no prompt (agent-friendly)
|
|
npx hyperframes upgrade --check --json # machine-readable: current / latest / updateAvailable
|
|
npx hyperframes upgrade --yes # print upgrade commands without prompting
|
|
```
|
|
|
|
Compares the installed CLI version against npm latest.
|
|
|
|
`--project [dir]` bumps a **project's** pinned scripts instead of the global install: it rewrites every `npx …hyperframes@<version>…` in `<dir>/package.json` (default cwd) to npm-latest. Always invoke it unpinned (`npx hyperframes@latest upgrade --project`) — a project scaffolded on an old CLI stays frozen otherwise. `--project . --check` reports the delta without writing; add `--json` for `{ changed, from, to, path }`. Pass the dir explicitly whenever another flag follows `--project` — on older releases a bare `--project` consumes the next flag as its directory value.
|
|
|
|
## compositions, docs
|
|
|
|
```bash
|
|
npx hyperframes compositions # list compositions in project
|
|
npx hyperframes compositions --json
|
|
npx hyperframes docs # list available topics
|
|
npx hyperframes docs rendering # print one topic inline in the terminal
|
|
```
|
|
|
|
`compositions` lists every `data-composition-id` in the project (including sub-comps) with duration, resolution, and element count.
|
|
|
|
`docs` prints inline documentation **in the terminal** — it does not open a browser. Topics: `data-attributes`, `examples`, `rendering`, `gsap`, `troubleshooting`, `compositions`. Run without a topic to see the list.
|
|
|
|
## benchmark
|
|
|
|
```bash
|
|
npx hyperframes benchmark # run the preset matrix in current project
|
|
npx hyperframes benchmark ./my-video # specific project
|
|
npx hyperframes benchmark --runs 5 # repeat each config N times (default 3)
|
|
npx hyperframes benchmark --json
|
|
```
|
|
|
|
Renders the project with 5 preset configurations — `30fps draft 2w`, `30fps standard 2w`, `30fps high 2w`, `30fps standard 4w`, `60fps standard 4w` — and prints a comparison of render speed and output file size. Use it to find the fastest acceptable preset for your machine. Not a single-render-with-stage-breakdown.
|
|
|
|
## telemetry
|
|
|
|
```bash
|
|
npx hyperframes telemetry status # show telemetry state
|
|
npx hyperframes telemetry disable # disable anonymous usage telemetry
|
|
npx hyperframes telemetry enable # re-enable telemetry
|
|
```
|
|
|
|
Telemetry is anonymous usage counters only. Disable globally with `HYPERFRAMES_NO_TELEMETRY=1` if env-var control is preferred over the subcommand.
|
|
|
|
Events include two fingerprint properties used to distinguish managed-sandbox runs from real laptops — no PII, no env-var **values**, only existence checks:
|
|
|
|
- **`sandbox_runtime`**: `gvisor` / `firecracker` / `docker` / `kvm` / `wsl` / `null`. gVisor via kernel string + `/proc/version`. Firecracker via `/dev/vsock` + DMI sys_vendor. Docker via `/.dockerenv` + cgroup.
|
|
- **`agent_runtime`**: `claude_code` / `codex` / `cursor` / `copilot_agent` / `jules` / `replit` / `devin` / `aider` / `gemini_cli` / `hermes` / `openclaw` / `null`. Detected by the existence of well-known vendor env vars; the values themselves are never read.
|
|
|
|
## Asset Preprocessing
|
|
|
|
```bash
|
|
npx hyperframes tts
|
|
npx hyperframes transcribe
|
|
npx hyperframes remove-background
|
|
```
|
|
|
|
These produce assets (narration audio, word-level transcripts, transparent video) that get dropped into a composition. Each may download its own model on first run.
|
|
|
|
For voice selection, Whisper model rules, output format choice, and the TTS → transcript → captions chain, invoke the `media-use` skill. This skill stays focused on the dev loop.
|