ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-11 06:30:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(cli): registry resolver + installer (#254)

Browse Source 
## 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
2026-04-13 20:41:23 -07:00
committed by GitHub
parent 69d9f08061
commit 969474e843
23 changed files with 1023 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/cli/src/templates/remote.ts
+26 -78
View File
@@ -1,24 +1,18 @@
/**
* Remote Template Fetching
*
* Downloads templates from the hyperframes GitHub repository using giget.
* Templates live in the `registry/examples/` directory of the repo.
*/
// Compat shim — fetchRemoteTemplate delegates to the registry resolver +
// installer (packages/cli/src/registry/). Kept so init.ts and external imports
// that reference this path keep working. Deletable once init.ts is fully
// ported to call the resolver directly.
import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
import { existsSync } from "node:fs";
import { join } from "node:path";
import { homedir } from "node:os";
import { installItem, listRegistryItems, loadAllItems, resolveItem } from "../registry/index.js";
const REPO = "heygen-com/hyperframes";
// Exported for regression testing — see remote.test.ts.
// Re-exported for the existing remote.test.ts regression guard. These paths
// describe the repo layout under the default registry URL; updating them in
// sync with any future move prevents silent breakage of installed CLIs.
export const TEMPLATES_DIR = "registry/examples";
export const MANIFEST_FILENAME = "templates.json";
/** Cache directory for remote template metadata. */
const CACHE_DIR = join(homedir(), ".hyperframes", "cache");
const MANIFEST_CACHE_PATH = join(CACHE_DIR, "remote-templates.json");
const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
export interface RemoteTemplateInfo {
id: string;
label: string;
@@ -26,79 +20,33 @@ export interface RemoteTemplateInfo {
bundled: boolean;
}
interface ManifestCache {
fetchedAt: number;
templates: RemoteTemplateInfo[];
}
/**
* Fetch the remote template manifest from GitHub.
* Caches the result for 24 hours to avoid rate limits.
* List available remote templates — kept for backwards compat with external
* imports. Internally, `resolveTemplateList` in generators.ts is what init.ts
* uses, and it goes through the registry resolver directly.
*/
export async function listRemoteTemplates(): Promise<RemoteTemplateInfo[]> {
// Check cache first
if (existsSync(MANIFEST_CACHE_PATH)) {
try {
const cached: ManifestCache = JSON.parse(readFileSync(MANIFEST_CACHE_PATH, "utf-8"));
if (Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
return cached.templates;
}
} catch {
// Cache corrupt — refetch
}
}
// Fetch from GitHub raw content
const url = `https://raw.githubusercontent.com/${REPO}/main/${TEMPLATES_DIR}/${MANIFEST_FILENAME}`;
try {
const res = await fetch(url, { signal: AbortSignal.timeout(5_000) });
if (!res.ok) {
throw new Error(`HTTP ${res.status}`);
}
const data = (await res.json()) as { templates: RemoteTemplateInfo[] };
const templates = data.templates;
// Write cache
mkdirSync(CACHE_DIR, { recursive: true });
const cache: ManifestCache = { fetchedAt: Date.now(), templates };
writeFileSync(MANIFEST_CACHE_PATH, JSON.stringify(cache), "utf-8");
return templates;
} catch {
// Offline or rate-limited — return empty (caller should fall back to bundled)
return [];
}
const entries = await listRegistryItems({ type: "hyperframes:example" });
const items = await loadAllItems(entries);
return items.map((item) => ({
id: item.name,
label: item.title,
hint: item.description,
bundled: false,
}));
}
/**
* Download a template from GitHub into destDir using giget.
* Fetches from `registry/examples/<templateId>` in the hyperframes repo.
* Download a template into destDir. Delegates to the registry installer.
*/
export async function fetchRemoteTemplate(
templateId: string,
destDir: string,
options?: { ref?: string },
): Promise<void> {
// Validate against manifest before downloading
const known = await listRemoteTemplates();
if (known.length > 0 && !known.some((t) => t.id === templateId)) {
const available = known.map((t) => t.id).join(", ");
throw new Error(`Template "${templateId}" not found. Available: ${available}`);
}
export async function fetchRemoteTemplate(templateId: string, destDir: string): Promise<void> {
const item = await resolveItem(templateId);
await installItem(item, { destDir });
const { downloadTemplate } = await import("giget");
const ref = options?.ref ?? "main";
const source = `github:${REPO}/${TEMPLATES_DIR}/${templateId}#${ref}`;
await downloadTemplate(source, {
dir: destDir,
force: true,
});
// Safety check — giget can succeed with empty dir if path doesn't exist
// Safety check — an item with no index.html isn't a valid example.
if (!existsSync(join(destDir, "index.html"))) {
throw new Error(
`Template "${templateId}" downloaded but missing index.html. The template may be malformed.`,
`Template "${templateId}" installed but missing index.html. The registry item may be malformed.`,
);
}
}