mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 04:38:33 +00:00
James Russo
08fb1de61f
## What PR 5/17 of the catalog system rollout. Adds the `hyperframes add` verb for installing blocks and components from the registry into an existing project, plus the `hyperframes.json` project config that tells `add` which registry to use and where to drop files. Stacks on #255. - **`packages/cli/src/commands/add.ts`** — new `hyperframes add <name>` command. Resolves an item, validates target paths, installs files in parallel, builds an include snippet, copies it to the clipboard. Exposes a testable `runAdd(opts)` function; the citty default wraps it with console output + exit handling - **`packages/cli/src/utils/projectConfig.ts`** — read/write/normalize `hyperframes.json`. Tolerant to missing and partial configs - **`packages/cli/src/utils/clipboard.ts`** — minimal cross-platform clipboard (pbcopy / clip.exe / wl-copy / xclip / xsel). Zero deps. Gracefully no-ops in headless environments - **`packages/cli/src/commands/init.ts`** — write `hyperframes.json` during scaffold if not already present - **`packages/cli/src/cli.ts`** + **`help.ts`** — register `add` under Getting Started (directly below `init`) Design doc: [Hyperframes Catalog System](https://www.notion.so/heygen/Hyperframes-Catalog-System-Design-Plan-341449792c69813f899dcd53b4c0383a). ## UX ```bash # Scaffold a project (now writes hyperframes.json too) npx hyperframes init my-video --example blank cd my-video # Add a block — files land, snippet copied to clipboard npx hyperframes add claude-code-window # ✓ Added claude-code-window (hyperframes:block) # compositions/claude-code-window.html # # Include snippet: # <iframe src="compositions/claude-code-window.html" data-start="0" data-duration="6"></iframe> # # Copied to clipboard — paste into your host composition. # Add a component effect npx hyperframes add shader-wipe # Headless / CI — no clipboard, JSON output for tooling npx hyperframes add shader-wipe --no-clipboard --json ``` Running `hyperframes add warm-grain` (an example) errors clearly pointing to `init --example`. ## Docs (bundled in this PR per the tracker principle) - `docs/packages/cli.mdx` — new `add` subsection under Commands (flags, examples, trigger rules) + new `hyperframes.json` section describing the config file shape ## Tests - **`packages/cli/src/commands/add.test.ts`** — 11 tests: - `remapTarget` / `buildSnippet` pure helpers (5 tests) - `runAdd` integration against a mocked `fetch` registry: block install lands files + returns snippet, component install respects `paths.components` remap, example-typed names throw `AddError` with code `example-type`, unknown names throw `AddError` with code `unknown-item` (4 tests plus 2 covering block default path and non-default path preservation) - **`packages/cli/src/utils/projectConfig.test.ts`** — 9 tests: - Write/read round-trip, partial-config normalization, corrupt-file handling, absent-file fallback to defaults, custom paths preserved - **CLI suite:** 92 passed (was 72 on #255, **+20**). Same 4 pre-existing failures unchanged ## Scope decisions - **`init.ts` full port to new resolver deferred.** The original plan bundled a removal of the `packages/cli/src/templates/` compat shim. That's ~300 more lines and isn't required for `add` to work. The compat shim from #254 still functions; a separate cleanup PR handles it - **No ajv runtime schema validation.** Manifests are trusted as schema-valid. Full validation lands when third-party registries arrive (PR 14/15). Path safety is still enforced by the installer's `assertSafeTarget` guard - **Default project paths stay under `compositions/`.** Blocks → `compositions/<name>.html`; components → `compositions/components/<name>/<file>`. Users override via `hyperframes.json#paths` ## Breaking / migration **None.** Pure additive — new command, new file types, no existing commands or flags change. `init.ts` now writes `hyperframes.json` but that's a new additional file, not a modification of existing output. ## Stacks on #255 — base branch. When #255 merges, this rebases onto `main`. ## Next in stack PR 6 — `feat(registry): seed block — claude-code-window`. First real registry item. Exercises the full `hyperframes add <name>` flow end-to-end against a committed item on `main`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
142 lines
3.9 KiB
JSON
142 lines
3.9 KiB
JSON
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"$id": "https://hyperframes.heygen.com/schema/registry-item.json",
|
|
"title": "Hyperframes Registry Item",
|
|
"description": "Manifest for a single distributable item (example, block, or component).",
|
|
"type": "object",
|
|
"required": ["name", "type", "title", "description", "files"],
|
|
"properties": {
|
|
"$schema": {
|
|
"type": "string",
|
|
"format": "uri"
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
|
|
"description": "Item name in kebab-case, must start and end with alphanumeric."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"enum": ["hyperframes:example", "hyperframes:block", "hyperframes:component"]
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"tags": {
|
|
"type": "array",
|
|
"items": { "type": "string", "minLength": 1 }
|
|
},
|
|
"author": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"license": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "SPDX license identifier (e.g. \"Apache-2.0\", \"MIT\")."
|
|
},
|
|
"minCliVersion": {
|
|
"type": "string",
|
|
"pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$",
|
|
"description": "Minimum `hyperframes` CLI version required to install this item."
|
|
},
|
|
"deprecated": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "If set, the item is deprecated; the value is the reason or migration note."
|
|
},
|
|
"dimensions": {
|
|
"type": "object",
|
|
"required": ["width", "height"],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"width": { "type": "integer", "minimum": 1 },
|
|
"height": { "type": "integer", "minimum": 1 }
|
|
}
|
|
},
|
|
"duration": {
|
|
"type": "number",
|
|
"exclusiveMinimum": 0,
|
|
"description": "Duration in seconds. Must be > 0."
|
|
},
|
|
"registryDependencies": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string",
|
|
"pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
|
|
}
|
|
},
|
|
"files": {
|
|
"type": "array",
|
|
"minItems": 1,
|
|
"items": {
|
|
"type": "object",
|
|
"required": ["path", "target", "type"],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"path": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Source path, relative to registry-item.json."
|
|
},
|
|
"target": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Destination path in the user's project, relative to project root. Must not traverse outside the project (no `..` segments, no absolute paths).",
|
|
"not": {
|
|
"anyOf": [
|
|
{ "pattern": "(^|[/\\\\])\\.\\.([/\\\\]|$)" },
|
|
{ "pattern": "^[/\\\\]" },
|
|
{ "pattern": "^[A-Za-z]:[/\\\\]" }
|
|
]
|
|
}
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"hyperframes:composition",
|
|
"hyperframes:asset",
|
|
"hyperframes:snippet",
|
|
"hyperframes:style",
|
|
"hyperframes:timeline"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"preview": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"video": { "type": "string" },
|
|
"poster": { "type": "string" }
|
|
}
|
|
},
|
|
"relatedSkill": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
}
|
|
},
|
|
"allOf": [
|
|
{
|
|
"if": {
|
|
"required": ["type"],
|
|
"properties": { "type": { "const": "hyperframes:component" } }
|
|
},
|
|
"then": {
|
|
"not": {
|
|
"anyOf": [{ "required": ["dimensions"] }, { "required": ["duration"] }]
|
|
}
|
|
},
|
|
"else": {
|
|
"required": ["dimensions", "duration"]
|
|
}
|
|
}
|
|
]
|
|
}
|