2 Commits

Include renames

Author	SHA1	Message	Date
James Russo	969474e843	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)	2026-04-13 20:41:23 -07:00
James RussoandClaude Opus 4.6	eb338ae859	feat(core): add registry schema + TS types (#252) ... * feat(core): add registry schema + TS types PR 1/17 of the catalog system rollout. Foundation for a shadcn-style registry with three item tiers: examples (full projects), blocks (sub-compositions), components (effect snippets). ## What - TS types: RegistryItem (discriminated union of ExampleItem/BlockItem/ ComponentItem), RegistryManifest, FileTarget, ItemType, FileType - JSON Schemas: schemas/registry.json, schemas/registry-item.json - Compile-time exhaustiveness asserts on ITEM_TYPES/FILE_TYPES so adding to the TS union without updating the constant stops compiling - Drift-guard test: schema enums must equal ITEM_TYPES/FILE_TYPES by set-equality; exactly 2 distinct type enums in registry-item.json - Public API via new ./registry export path plus re-exports from root; schemas exposed via ./schemas/registry.json export for external tooling ## Why - Every downstream PR (resolver, installer, hyperframes add, docs codegen, CI previews, skill, catalog command) builds on these types - Getting the shape right now avoids painful migrations later ## How - Discriminated union enforces that components do not have dimensions or duration and examples/blocks must have them (schema mirrors via if/then/else on the type discriminant) - target path pattern rejects .. segments, Unix absolute paths, and Windows drive letters (defense-in-depth; CLI validates at runtime in PR 3) - name pattern requires alphanumeric start and end (no trailing hyphens) - Optional metadata: version, author, license, deprecated, minCliVersion - additionalProperties: false on nested objects (catches typos on critical fields) but relaxed on top-level RegistryItem (allows third-party custom metadata in PR 15 custom registries) ## Test plan - [x] Unit tests: 11 new tests covering type guards, discriminant narrowing, schema/TS drift guards, schema \$id sanity, optional metadata acceptance, and compile-time checks (via @ts-expect-error) - [x] bun run test in packages/core: 445 passed (was 434 on main, +11 from this PR) - [x] bunx oxfmt and bunx oxlint: clean - [x] bun run typecheck: clean - [ ] Manual testing: N/A (types + schemas only) - [ ] Documentation updated: per-item doc pages land in PR 9 (codegen from these manifests); guide updates in PR 10+ ## Breaking / migration None. Pure additive — new module, new export paths, no existing surface touched. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(core): remove version field + hyperframes:demo file type Address review feedback from Miguel: - Remove `version` from RegistryItemBase + schema. Per shadcn model, the registry is versioned by git tags, not per-item. The adversarial review added it; the original design doc was correct. - Remove `hyperframes:demo` from FileType union + FILE_TYPES constant + schema. Demo files exist on disk for the CI preview pipeline but are NOT installed to user projects and should not appear in registry-item.json files[]. Neither shadcn nor Remotion has a dedicated demo file type — demos are just compositions. - Add `required: ["type"]` to the if-condition in the schema's allOf discriminant (Miguel's nit — makes the condition self- contained) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(ci): add shader-transitions to Dockerfile.test PR #251 added packages/shader-transitions/ to the workspace but didn't update Dockerfile.test to COPY its package.json. This caused `bun install --frozen-lockfile` to fail in the regression Docker build: bun saw a lockfile referencing @hyperframes/shader-transitions but the package.json wasn't present in the container, so it wanted to remove the entry — triggering "lockfile had changes." Verified: Docker build passes with `--no-cache` after this fix. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-13 20:18:37 -07:00