mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 04:38:33 +00:00
feat(cli): registry resolver + installer (#254)
## What PR 3/17 of the catalog system rollout. Introduces the registry resolver/installer abstraction. No UX change — `init --template` still works identically. Stacks on #253. **New module: `packages/cli/src/registry/`** - `remote.ts` — fetches manifests (`registry.json`, `registry-item.json`) and item files from a GitHub-hosted registry. 24h cache on manifests; item files stream straight to `destDir` - `resolver.ts` — `listRegistryItems`, `loadAllItems` (parallel fetch for picker UX), `resolveItem` (single-item fetch with `Available:` error) - `installer.ts` — `assertSafeTarget` (runtime path-traversal guard) + `installItem` (parallel file download with up-front validation; all-or-nothing semantics) - `index.ts` — barrel **Registry content:** - `registry/registry.json` — top-level manifest in PR 1's `RegistryManifest` shape. 8 examples - `registry/examples/<id>/registry-item.json` — per-item manifest for each existing example, generated from legacy `templates.json` + HTML data-attribute probing - `registry/examples/templates.json` — **deleted**, replaced by the above **Compat layer:** - `packages/cli/src/templates/{remote,generators}.ts` — thin shims that delegate to `../registry/`, keeping `init.ts`'s existing imports stable. `init.ts` doesn't move to the new API until PR 5 where it's part of a larger UX pass **Tooling:** - `scripts/generate-registry-items.ts` — idempotent one-off generator for this PR, kept in-repo for future example additions (`--only <name>` flag) Design doc: [Hyperframes Catalog System](https://www.notion.so/heygen/Hyperframes-Catalog-System-Design-Plan-341449792c69813f899dcd53b4c0383a). Tracker entry in local `hyperframes-catalog-plan.md`. ## Why Every future PR (`hyperframes add`, seed blocks, seed components, custom registries) otherwise has to keep piling onto the ad-hoc fetch + `cpSync` pattern in the old `fetchRemoteTemplate`. The new module is the single place that understands the registry wire format and file layout. **This is also where PR 1's schema comes alive.** ## How ### Scope-trimmed from the plan - **No transitive dependency resolution yet.** Examples have no deps today. `resolveItem` doesn't walk `registryDependencies`; PR 5 adds that when blocks/components need it. - **No ajv schema validation yet.** TS types + runtime path-traversal guard are the only safety nets. Full JSON-Schema validation lands when the registry starts accepting third-party content (PR 14 / custom registries). - **init.ts refactor deferred to PR 5.** Compat shims keep this PR small and reviewable. PR 5 rewrites init alongside adding the `add` command. ### Safety - `assertSafeTarget` rejects absolute paths, `..` segments, Windows drive letters, and any target that `path.resolve` shows to escape `destDir`. Mirrors the PR 1 schema `pattern`/`not.anyOf` on `target`, but runs at install-time so a registry that bypasses schema validation still can't write outside the project - Up-front validation in `installItem` means a malformed item fails **before** any file is written. Atomic-ish semantics: all files land or none do ### Caching - 24h manifest cache lives at `~/.hyperframes/cache/` per existing convention, but now keyed by `<baseUrl>__<kind>__<name>.json` so PR 14 custom registries can coexist ## Test plan - [x] `bun run test` in `packages/cli`: **70 passed** (was 57 on #253, +13). Same 4 pre-existing failures (SRT/VTT whisper normalizer + `lintProject` clean-project test) — identical to main. No regressions - [x] **Resolver unit tests (8):** filter by type, parallel load with fail-safe, resolve-by-name with `Available:` error message, unreachable-registry handling - [x] **Installer unit tests (5):** accepts simple relative paths, rejects `..` segments, rejects Unix absolute paths, rejects Windows drive letters, permits `.` and dotfile-like names - [x] **Smoke test**: `hyperframes init /tmp/x --template blank` (bundled code path, unchanged) works end-to-end - [x] `bunx oxfmt --check` + `bunx oxlint`: clean - [x] Pre-commit typecheck (core + studio): clean. CLI typecheck has 2 pre-existing errors (`render.ts`, `studioServer.ts` — unrelated `"mov"` format issue on main) - [ ] **Smoke test remote fetch (`--template warm-grain`)** — verifiable only post-merge; registry paths live on `main` after this PR lands ## Breaking / migration **No end-user-visible UX change.** `init --template <name>` still works the same way. Internally, `templates.json` is gone and the CLI now reads `registry.json` + `registry-item.json` per example. Installed CLIs on old versions (`hyperframes@0.1.0`–`0.3.0`) already broke at PR 2 merge (see #253 rollout note). The next CLI release after this lands (`0.3.1`+) is the full fix. ## Commits 1. `generate-registry-items.ts` + generated manifests + deleted `templates.json` 2. Resolver + installer + compat shims 3. Unit tests (All squashed into one commit on this branch; see `git log feat/registry-resolver ^refactor/registry-examples-dir`.) ## Stacks on #253 — base branch. When #253 merges, this rebases onto `main`. ## Next in stack PR 4 — `feat(cli)!: rename --template to --example`. Single clean cut, no alias. Tiny PR (~150 lines) that mostly updates `init.ts`'s argument schema, help text, and docs. Depends on this PR so the new flag name can be applied against the refactored code path. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This commit is contained in:
James Russo
@@ -0,0 +1,24 @@
|
||||
{
|
||||
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
|
||||
"name": "decision-tree",
|
||||
"type": "hyperframes:example",
|
||||
"title": "Decision Tree",
|
||||
"description": "Animated flowchart with branching paths",
|
||||
"dimensions": {
|
||||
"width": 1920,
|
||||
"height": 1080
|
||||
},
|
||||
"duration": 15,
|
||||
"files": [
|
||||
{
|
||||
"path": "compositions/decision_tree.html",
|
||||
"target": "compositions/decision_tree.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "index.html",
|
||||
"target": "index.html",
|
||||
"type": "hyperframes:composition"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
{
|
||||
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
|
||||
"name": "kinetic-type",
|
||||
"type": "hyperframes:example",
|
||||
"title": "Kinetic Type",
|
||||
"description": "Bold kinetic typography promo",
|
||||
"dimensions": {
|
||||
"width": 1920,
|
||||
"height": 1080
|
||||
},
|
||||
"duration": 15,
|
||||
"files": [
|
||||
{
|
||||
"path": "compositions/main-graphics.html",
|
||||
"target": "compositions/main-graphics.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "index.html",
|
||||
"target": "index.html",
|
||||
"type": "hyperframes:composition"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
{
|
||||
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
|
||||
"name": "nyt-graph",
|
||||
"type": "hyperframes:example",
|
||||
"title": "NYT Graph",
|
||||
"description": "Animated data chart in print editorial style",
|
||||
"dimensions": {
|
||||
"width": 1920,
|
||||
"height": 1080
|
||||
},
|
||||
"duration": 15,
|
||||
"files": [
|
||||
{
|
||||
"path": "compositions/nyt-chart.html",
|
||||
"target": "compositions/nyt-chart.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "index.html",
|
||||
"target": "index.html",
|
||||
"type": "hyperframes:composition"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
{
|
||||
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
|
||||
"name": "play-mode",
|
||||
"type": "hyperframes:example",
|
||||
"title": "Play Mode",
|
||||
"description": "Playful elastic animations",
|
||||
"dimensions": {
|
||||
"width": 1920,
|
||||
"height": 1080
|
||||
},
|
||||
"duration": 10,
|
||||
"files": [
|
||||
{
|
||||
"path": "compositions/captions.html",
|
||||
"target": "compositions/captions.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "compositions/intro.html",
|
||||
"target": "compositions/intro.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "compositions/stats.html",
|
||||
"target": "compositions/stats.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "index.html",
|
||||
"target": "index.html",
|
||||
"type": "hyperframes:composition"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,49 @@
|
||||
{
|
||||
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
|
||||
"name": "product-promo",
|
||||
"type": "hyperframes:example",
|
||||
"title": "Product Promo",
|
||||
"description": "Multi-scene product showcase with SVG assets",
|
||||
"dimensions": {
|
||||
"width": 1920,
|
||||
"height": 1080
|
||||
},
|
||||
"duration": 20,
|
||||
"files": [
|
||||
{
|
||||
"path": "assets/figma-cursors.svg",
|
||||
"target": "assets/figma-cursors.svg",
|
||||
"type": "hyperframes:asset"
|
||||
},
|
||||
{
|
||||
"path": "assets/figma-logo-pieces.svg",
|
||||
"target": "assets/figma-logo-pieces.svg",
|
||||
"type": "hyperframes:asset"
|
||||
},
|
||||
{
|
||||
"path": "assets/figma-logo-pills.svg",
|
||||
"target": "assets/figma-logo-pills.svg",
|
||||
"type": "hyperframes:asset"
|
||||
},
|
||||
{
|
||||
"path": "compositions/scene1-logo-intro.html",
|
||||
"target": "compositions/scene1-logo-intro.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "compositions/scene2-4-canvas.html",
|
||||
"target": "compositions/scene2-4-canvas.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "compositions/scene5-logo-outro.html",
|
||||
"target": "compositions/scene5-logo-outro.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "index.html",
|
||||
"target": "index.html",
|
||||
"type": "hyperframes:composition"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
{
|
||||
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
|
||||
"name": "swiss-grid",
|
||||
"type": "hyperframes:example",
|
||||
"title": "Swiss Grid",
|
||||
"description": "Structured grid layout",
|
||||
"dimensions": {
|
||||
"width": 1920,
|
||||
"height": 1080
|
||||
},
|
||||
"duration": 10,
|
||||
"files": [
|
||||
{
|
||||
"path": "assets/swiss-grid.svg",
|
||||
"target": "assets/swiss-grid.svg",
|
||||
"type": "hyperframes:asset"
|
||||
},
|
||||
{
|
||||
"path": "compositions/captions.html",
|
||||
"target": "compositions/captions.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "compositions/graphics.html",
|
||||
"target": "compositions/graphics.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "compositions/intro.html",
|
||||
"target": "compositions/intro.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "index.html",
|
||||
"target": "index.html",
|
||||
"type": "hyperframes:composition"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,58 +0,0 @@
|
||||
{
|
||||
"templates": [
|
||||
{
|
||||
"id": "blank",
|
||||
"label": "Blank",
|
||||
"hint": "Empty composition — just the scaffolding",
|
||||
"bundled": true
|
||||
},
|
||||
{
|
||||
"id": "warm-grain",
|
||||
"label": "Warm Grain",
|
||||
"hint": "Cream aesthetic with grain texture",
|
||||
"bundled": false
|
||||
},
|
||||
{
|
||||
"id": "play-mode",
|
||||
"label": "Play Mode",
|
||||
"hint": "Playful elastic animations",
|
||||
"bundled": false
|
||||
},
|
||||
{
|
||||
"id": "swiss-grid",
|
||||
"label": "Swiss Grid",
|
||||
"hint": "Structured grid layout",
|
||||
"bundled": false
|
||||
},
|
||||
{
|
||||
"id": "vignelli",
|
||||
"label": "Vignelli",
|
||||
"hint": "Bold typography with red accents",
|
||||
"bundled": false
|
||||
},
|
||||
{
|
||||
"id": "decision-tree",
|
||||
"label": "Decision Tree",
|
||||
"hint": "Animated flowchart with branching paths",
|
||||
"bundled": false
|
||||
},
|
||||
{
|
||||
"id": "kinetic-type",
|
||||
"label": "Kinetic Type",
|
||||
"hint": "Bold kinetic typography promo",
|
||||
"bundled": false
|
||||
},
|
||||
{
|
||||
"id": "product-promo",
|
||||
"label": "Product Promo",
|
||||
"hint": "Multi-scene product showcase with SVG assets",
|
||||
"bundled": false
|
||||
},
|
||||
{
|
||||
"id": "nyt-graph",
|
||||
"label": "NYT Graph",
|
||||
"hint": "Animated data chart in print editorial style",
|
||||
"bundled": false
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
{
|
||||
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
|
||||
"name": "vignelli",
|
||||
"type": "hyperframes:example",
|
||||
"title": "Vignelli",
|
||||
"description": "Bold typography with red accents",
|
||||
"dimensions": {
|
||||
"width": 1080,
|
||||
"height": 1920
|
||||
},
|
||||
"duration": 10,
|
||||
"files": [
|
||||
{
|
||||
"path": "compositions/captions.html",
|
||||
"target": "compositions/captions.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "compositions/overlays.html",
|
||||
"target": "compositions/overlays.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "index.html",
|
||||
"target": "index.html",
|
||||
"type": "hyperframes:composition"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
{
|
||||
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
|
||||
"name": "warm-grain",
|
||||
"type": "hyperframes:example",
|
||||
"title": "Warm Grain",
|
||||
"description": "Cream aesthetic with grain texture",
|
||||
"dimensions": {
|
||||
"width": 1920,
|
||||
"height": 1080
|
||||
},
|
||||
"duration": 10,
|
||||
"files": [
|
||||
{
|
||||
"path": "compositions/captions.html",
|
||||
"target": "compositions/captions.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "compositions/graphics.html",
|
||||
"target": "compositions/graphics.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "compositions/intro.html",
|
||||
"target": "compositions/intro.html",
|
||||
"type": "hyperframes:composition"
|
||||
},
|
||||
{
|
||||
"path": "index.html",
|
||||
"target": "index.html",
|
||||
"type": "hyperframes:composition"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
{
|
||||
"$schema": "https://hyperframes.heygen.com/schema/registry.json",
|
||||
"name": "hyperframes",
|
||||
"homepage": "https://hyperframes.heygen.com",
|
||||
"items": [
|
||||
{
|
||||
"name": "warm-grain",
|
||||
"type": "hyperframes:example"
|
||||
},
|
||||
{
|
||||
"name": "play-mode",
|
||||
"type": "hyperframes:example"
|
||||
},
|
||||
{
|
||||
"name": "swiss-grid",
|
||||
"type": "hyperframes:example"
|
||||
},
|
||||
{
|
||||
"name": "vignelli",
|
||||
"type": "hyperframes:example"
|
||||
},
|
||||
{
|
||||
"name": "decision-tree",
|
||||
"type": "hyperframes:example"
|
||||
},
|
||||
{
|
||||
"name": "kinetic-type",
|
||||
"type": "hyperframes:example"
|
||||
},
|
||||
{
|
||||
"name": "product-promo",
|
||||
"type": "hyperframes:example"
|
||||
},
|
||||
{
|
||||
"name": "nyt-graph",
|
||||
"type": "hyperframes:example"
|
||||
}
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user