* fix(cli): use 'where' instead of 'which' on Windows for FFmpeg and browser detection
- findFFmpeg() now uses 'where ffmpeg' on Windows, 'which ffmpeg' on Unix
- whichBinary() now uses 'where' on Windows, 'which' on Unix
Fixes FFmpeg detection failure on Windows where 'which' command doesn't exist.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* fix(cli): handle multi-line output from Windows 'where' command
Windows 'where' can return multiple paths (one per line) when there
are multiple matches on PATH. Take only the first non-empty line.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* fix(cli): extend Windows 'where' fix to whisper, tts, and clipboard modules
- whisper/manager.ts: whichBinary() now uses 'where' on Windows
- tts/synthesize.ts: findPython() now uses 'where' on Windows
- utils/clipboard.ts: detectProvider() now uses 'where' on Windows
All functions handle multi-line output from 'where' command.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
## 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)
