mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +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)
153 lines
4.6 KiB
Plaintext
153 lines
4.6 KiB
Plaintext
---
|
|
title: Contributing
|
|
description: "How to contribute to Hyperframes."
|
|
---
|
|
|
|
Thanks for your interest in contributing to Hyperframes! This guide covers everything you need to get set up, run tests, and submit a pull request.
|
|
|
|
## Getting Started
|
|
|
|
<Steps>
|
|
<Step title="Fork and clone">
|
|
Fork the repository on GitHub, then clone your fork:
|
|
```bash
|
|
git clone https://github.com/YOUR_USERNAME/hyperframes.git
|
|
cd hyperframes
|
|
```
|
|
</Step>
|
|
<Step title="Install dependencies">
|
|
Hyperframes uses [bun](https://bun.sh/) for package management:
|
|
```bash
|
|
bun install
|
|
```
|
|
</Step>
|
|
<Step title="Build all packages">
|
|
Build the monorepo to ensure everything compiles:
|
|
```bash
|
|
bun run build
|
|
```
|
|
</Step>
|
|
<Step title="Run the studio">
|
|
Start the development server to verify your setup:
|
|
```bash
|
|
bun run dev
|
|
```
|
|
If the studio opens at `http://localhost:3000` with a preview, your environment is ready.
|
|
</Step>
|
|
<Step title="Create a branch">
|
|
Create a feature branch for your work:
|
|
```bash
|
|
git checkout -b my-feature
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Development
|
|
|
|
### Common Commands
|
|
|
|
```bash
|
|
bun install # Install all dependencies
|
|
bun run dev # Start the studio (composition editor + live preview)
|
|
bun run build # Build all packages
|
|
bun run --filter '*' typecheck # Type-check all packages
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
<CodeGroup>
|
|
```bash Core
|
|
bun run --filter @hyperframes/core test
|
|
```
|
|
```bash Engine
|
|
bun run --filter @hyperframes/engine test
|
|
```
|
|
```bash Runtime Contract
|
|
bun run --filter @hyperframes/core test:hyperframe-runtime-ci
|
|
```
|
|
```bash Producer (Docker)
|
|
cd packages/producer && bun run docker:build:test && bun run docker:test
|
|
```
|
|
</CodeGroup>
|
|
|
|
### Running All Tests
|
|
|
|
```bash
|
|
bun run --filter '*' test
|
|
```
|
|
|
|
## Packages
|
|
|
|
| Package | Path | Description |
|
|
|---------|------|-------------|
|
|
| [`@hyperframes/core`](/packages/core) | `packages/core` | Types, HTML generation, runtime, linter |
|
|
| [`@hyperframes/engine`](/packages/engine) | `packages/engine` | Seekable page-to-video capture engine |
|
|
| [`@hyperframes/producer`](/packages/producer) | `packages/producer` | Full rendering pipeline (capture + encode) |
|
|
| [`@hyperframes/studio`](/packages/studio) | `packages/studio` | Composition editor UI |
|
|
| [`hyperframes`](/packages/cli) | `packages/cli` | CLI for creating, previewing, and rendering |
|
|
|
|
## What to Work On
|
|
|
|
Not sure where to start? Here are some ideas:
|
|
|
|
- **Good first issues** — look for issues labeled `good first issue` on GitHub
|
|
- **Documentation** — improve docs, add examples, fix typos
|
|
- **Linter rules** — add new rules to catch more composition mistakes
|
|
- **Examples** — create new starter examples
|
|
- **Bug fixes** — check the issue tracker for reported bugs
|
|
|
|
## Pull Requests
|
|
|
|
### Commit Format
|
|
|
|
Use [conventional commit](https://www.conventionalcommits.org/) format for all commits and PR titles:
|
|
|
|
```
|
|
feat: add timeline export
|
|
fix: resolve seek overflow at composition boundary
|
|
docs: add GSAP easing examples
|
|
refactor: extract frame buffer pool into shared module
|
|
test: add regression test for nested composition timing
|
|
```
|
|
|
|
### CI Requirements
|
|
|
|
All of the following must pass before your PR can be merged:
|
|
|
|
- **Build** — `bun run build` succeeds
|
|
- **Type check** — `bun run --filter '*' typecheck` reports no errors
|
|
- **Tests** — all test suites pass
|
|
- **Semantic PR title** — PR title follows conventional commit format
|
|
|
|
### Review Process
|
|
|
|
- PRs require at least 1 approval from a maintainer
|
|
- Keep PRs focused — one feature or fix per PR
|
|
- Include a clear description of what changed and why
|
|
- Add tests for new features and bug fixes
|
|
|
|
## Reporting Issues
|
|
|
|
- Use [GitHub Issues](https://github.com/heygen-com/hyperframes/issues) for bug reports and feature requests
|
|
- Search existing issues before creating a new one
|
|
- For bug reports, include:
|
|
- Steps to reproduce
|
|
- Expected behavior vs. actual behavior
|
|
- Hyperframes version (`npx hyperframes info`)
|
|
- Operating system and Node.js version
|
|
|
|
## Community
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="GitHub Issues" icon="github" href="https://github.com/heygen-com/hyperframes/issues">
|
|
Report bugs, request features, and discuss ideas.
|
|
</Card>
|
|
<Card title="Code of Conduct" icon="handshake" href="https://github.com/heygen-com/hyperframes/blob/main/CODE_OF_CONDUCT.md">
|
|
Our community standards and expectations.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
## License
|
|
|
|
By contributing, you agree that your contributions will be licensed under the [MIT License](https://github.com/heygen-com/hyperframes/blob/main/LICENSE).
|