mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-14 18:01:20 +08:00
James
61bd39e95c
PR 4/17 of the catalog system rollout. Single clean cut — the old flag is gone, replaced by --example. Alias changes from -t to -e. BREAKING CHANGE: --template is no longer accepted. Use --example <name> instead. When the old flag is used, the CLI exits 1 with a rename hint that includes the corrected command line. ## What - Rename the init command's --template flag to --example (alias -e) - Accept --template as a recognized-but-errored flag so users get a clear diagnostic instead of citty silently ignoring it and producing a blank project - Update all user-visible strings that referenced "template" as a user-facing concept in the init flow: - picker prompt: "Pick a template" → "Pick an example" - step comment: "Pick template" → "Pick example" - offline-fallback suggestion: "Use --template blank" → "Use --example blank" - New init.test.ts covering: --example scaffolds, --template exits 1 with the rename message ## Docs (bundled in this PR per the tracker principle) - docs/templates.mdx — all --template references - docs/quickstart.mdx — agent-mode + video-mode examples - docs/packages/cli.mdx — --help table, prose, alias (-e) - packages/cli/src/docs/templates.md — help-topic doc - No updates needed in README.md or CONTRIBUTING.md (they don't reference the flag) The user-facing renames of the templates.mdx page, nav entry, and directory routes are deferred to PR 11 (catalog discoverability UX) as planned. ## Why Two motivations: (1) "examples" matches shadcn + Remotion convention for full-project scaffolds and frees "template" for future parameterization work (string templating, placeholder substitution); (2) once hyperframes add lands in PR 5, "template" vs "block" vs "component" would be three subtly different concepts — renaming the old one to "example" makes the taxonomy self-explaining. ## How - citty silently ignores unknown flags. That meant naively removing --template would cause hyperframes init my-video --template warm-grain to silently fall through and scaffold a blank project. Very confusing. So --template stays declared but its run handler immediately errors with a rename hint including the corrected command. This is user guidance, not backwards compat — the old flag has no working behavior. - Internal names (templateId local, getStaticTemplateDir function, BUNDLED_TEMPLATES constant) are unchanged in this PR. They're implementation details; their rename is scheduled for PR 5 when the compat shims in packages/cli/src/templates/ are fully removed. ## Test plan - [x] bun run test in packages/cli: 72 passed (was 70 on #254, +2 new init.test.ts cases). Same 4 pre-existing failures unchanged - [x] Manual smoke: init /tmp/x --example blank succeeds; init /tmp/y --template blank errors with rename hint and exits 1 - [x] bunx oxfmt + bunx oxlint on changed files: clean - [x] Pre-commit typecheck (core + studio): clean - Also fixes an incidental regression from the PR 3 simplify-fix commit: the resolver test for loadAllItems' warning path was still spying on console.warn after the onWarn callback refactor. Now uses the callback directly. ## Stacks on #254 (PR 3 — registry resolver + installer). ## Next in stack PR 5 — feat(cli): add command + hyperframes.json. The big UX PR where init.ts gets fully ported to the new resolver, the compat shims are removed, and users gain the add verb for installing blocks and components into existing projects. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>