mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-10 22:20:14 +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,143 @@
|
||||
import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
|
||||
import type { RegistryItem, RegistryManifest } from "@hyperframes/core";
|
||||
import { listRegistryItems, loadAllItems, resolveItem } from "./resolver.js";
|
||||
|
||||
const MANIFEST: RegistryManifest = {
|
||||
$schema: "https://hyperframes.heygen.com/schema/registry.json",
|
||||
name: "test",
|
||||
homepage: "https://example.com",
|
||||
items: [
|
||||
{ name: "alpha", type: "hyperframes:example" },
|
||||
{ name: "beta", type: "hyperframes:example" },
|
||||
{ name: "gamma", type: "hyperframes:block" },
|
||||
],
|
||||
};
|
||||
|
||||
function buildItem(name: string, type: "hyperframes:example" | "hyperframes:block"): RegistryItem {
|
||||
if (type === "hyperframes:example") {
|
||||
return {
|
||||
name,
|
||||
type,
|
||||
title: name.toUpperCase(),
|
||||
description: `${name} desc`,
|
||||
dimensions: { width: 1920, height: 1080 },
|
||||
duration: 10,
|
||||
files: [{ path: "index.html", target: "index.html", type: "hyperframes:composition" }],
|
||||
};
|
||||
}
|
||||
return {
|
||||
name,
|
||||
type,
|
||||
title: name.toUpperCase(),
|
||||
description: `${name} desc`,
|
||||
dimensions: { width: 1080, height: 1350 },
|
||||
duration: 6,
|
||||
files: [
|
||||
{
|
||||
path: `${name}.html`,
|
||||
target: `compositions/${name}.html`,
|
||||
type: "hyperframes:composition",
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
function mockFetch(overrides: Record<string, unknown> = {}): void {
|
||||
vi.stubGlobal(
|
||||
"fetch",
|
||||
vi.fn(async (urlInput: string | URL) => {
|
||||
const url = typeof urlInput === "string" ? urlInput : urlInput.toString();
|
||||
if (url.endsWith("/registry.json") && !overrides.registryFails) {
|
||||
return new Response(JSON.stringify(MANIFEST), { status: 200 });
|
||||
}
|
||||
const m = /\/(examples|blocks|components)\/([^/]+)\/registry-item\.json$/.exec(url);
|
||||
if (m && !(overrides.missing as string[] | undefined)?.includes(m[2]!)) {
|
||||
const type = m[1] === "examples" ? "hyperframes:example" : "hyperframes:block";
|
||||
return new Response(JSON.stringify(buildItem(m[2]!, type)), { status: 200 });
|
||||
}
|
||||
return new Response("not found", { status: 404 });
|
||||
}),
|
||||
);
|
||||
}
|
||||
|
||||
function uniqueBaseUrl(): string {
|
||||
// Unique per-test so the 24h on-disk cache doesn't pollute sibling tests.
|
||||
return `https://test.invalid/${crypto.randomUUID()}`;
|
||||
}
|
||||
|
||||
describe("registry resolver", () => {
|
||||
beforeEach(() => mockFetch());
|
||||
afterEach(() => vi.unstubAllGlobals());
|
||||
|
||||
describe("listRegistryItems", () => {
|
||||
it("returns all items when no filter is given", async () => {
|
||||
const items = await listRegistryItems(undefined, { baseUrl: uniqueBaseUrl() });
|
||||
expect(items.map((i) => i.name)).toEqual(["alpha", "beta", "gamma"]);
|
||||
});
|
||||
|
||||
it("filters by type", async () => {
|
||||
const baseUrl = uniqueBaseUrl();
|
||||
const examples = await listRegistryItems({ type: "hyperframes:example" }, { baseUrl });
|
||||
expect(examples.map((i) => i.name)).toEqual(["alpha", "beta"]);
|
||||
|
||||
const blocks = await listRegistryItems({ type: "hyperframes:block" }, { baseUrl });
|
||||
expect(blocks.map((i) => i.name)).toEqual(["gamma"]);
|
||||
});
|
||||
|
||||
it("returns empty on unreachable registry", async () => {
|
||||
vi.stubGlobal(
|
||||
"fetch",
|
||||
vi.fn(async () => new Response("oops", { status: 500 })),
|
||||
);
|
||||
const items = await listRegistryItems(undefined, { baseUrl: uniqueBaseUrl() });
|
||||
expect(items).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("loadAllItems", () => {
|
||||
it("loads manifests in parallel", async () => {
|
||||
const baseUrl = uniqueBaseUrl();
|
||||
const entries = await listRegistryItems(undefined, { baseUrl });
|
||||
const items = await loadAllItems(entries, { baseUrl });
|
||||
expect(items.map((i) => i.name).sort()).toEqual(["alpha", "beta", "gamma"]);
|
||||
expect(items.find((i) => i.name === "alpha")?.title).toBe("ALPHA");
|
||||
});
|
||||
|
||||
it("skips items whose manifest fails to load (warning, not failure)", async () => {
|
||||
mockFetch({ missing: ["beta"] });
|
||||
const baseUrl = uniqueBaseUrl();
|
||||
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
|
||||
const entries = await listRegistryItems(undefined, { baseUrl });
|
||||
const items = await loadAllItems(entries, { baseUrl });
|
||||
expect(items.map((i) => i.name).sort()).toEqual(["alpha", "gamma"]);
|
||||
expect(warn).toHaveBeenCalled();
|
||||
warn.mockRestore();
|
||||
});
|
||||
});
|
||||
|
||||
describe("resolveItem", () => {
|
||||
it("returns the full manifest for a known item", async () => {
|
||||
const baseUrl = uniqueBaseUrl();
|
||||
const item = await resolveItem("alpha", { baseUrl });
|
||||
expect(item.name).toBe("alpha");
|
||||
expect(item.type).toBe("hyperframes:example");
|
||||
expect(item.files).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("throws with an `Available:` list when the name is unknown", async () => {
|
||||
const baseUrl = uniqueBaseUrl();
|
||||
await expect(resolveItem("nonexistent", { baseUrl })).rejects.toThrow(
|
||||
/Available: alpha, beta, gamma/,
|
||||
);
|
||||
});
|
||||
|
||||
it("throws a clear message when the registry itself is unreachable", async () => {
|
||||
vi.stubGlobal(
|
||||
"fetch",
|
||||
vi.fn(async () => new Response("down", { status: 500 })),
|
||||
);
|
||||
const baseUrl = uniqueBaseUrl();
|
||||
await expect(resolveItem("alpha", { baseUrl })).rejects.toThrow(/unreachable/);
|
||||
});
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user