Repository navigation
fix(cli): report an invalid catalog --type as a usage error - #7678
Merged
miguel-heygen merged 2 commits intoNov 14, 2026
Merged
Conversation
`catalog --type widget` exited 1 with a runtime_error. A bad flag value is a usage mistake, so it now throws CliUsageError: exit 2, and under --json a usage_error envelope with the same message. Closes heygen-com#7669 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01M3Xbw44WYGyVqg4AjkzFxj
miguel-heygen
approved these changes
Nov 14, 2026
miguel-heygen
left a comment
Collaborator
There was a problem hiding this comment.
Review at 5c51c969. There were no other reviews when I posted.
What's right
- The fix.
catalog.ts:229throwsCliUsageErrorwith the unchanged message, so it goes through the same top-level envelope ascheck's flag errors. - Placement. The throw sits before the registry read (
:234), so a bad--typefails without any network call.
Tests and checks (run locally with bun on PATH)
- The new row. The "flag checks a command makes itself" table in
cli.agentMode.test.tspasses, 57 of 57. - Mutation. With
catalog.tsreverted tomain, the new row fails withexpected 1 to be 2, as the body says. - By hand (
bun run src/cli.ts catalog …):--type widgetexits 2 and prints the message to stderr.--type widget --jsonexits 2, and stdout holds only{"ok":false,"error":{"code":"usage_error",…}}.--type Blockexits 2, since the check is case-sensitive like before.
Nits (non-blocking)
--type=(empty) still means "no filter". It lists all 448 items and exits 0, becauseelse if (args.type)treats""as absent. #7673 made empty values invalid forcheck's numeric flags.args.type !== undefinedhere would match that. This is pre-existing and outside this PR's scope.- The same family elsewhere in
catalog. "No searchable words in query" (:355-381) still ends withfinishCommand(1). Arguably it's a usage mistake too, but the body is upfront that other sites weren't swept, so it's fine as a follow-up.
CI
- This is a fork PR, so its runs were waiting on maintainer approval. I approved them after reading the diff, which touches two files and nothing under
.github/. - All 70 check runs finished: 51 succeeded and 19 were skipped, with nothing failing,
Commentsincluded. - Every required check that ran is green:
Build,Typecheck,Test,Test reachability,Test: runtime contract,regression,Tests on windows-latest,Render on windows-latest,Studio and player capturesandSemantic PR title. Skills: manifest in syncandStudio: edit accuracy gatewere skipped because they aren't affected.
Verdict: APPROVE
Reasoning: A one-line move from finishCommand(1) to CliUsageError that matches the CLI's usage-error contract. The new row fails without the fix, and required CI is green.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
hyperframes catalog --type <value>with a value other thanblockorcomponentnow fails as a usage error: exit 2, and under--jsonausage_errorenvelope carrying the same message.Why
A bad flag value is a usage mistake. The CLI's contract for those, which
cli.agentMode.test.tsenforces, is exit 2 with ausage_error.catalogprinted the message and calledfinishCommand(1), so agents saw aruntime_errorand could not tell a typo from a failure.Related work
Fixes #7669
How
The invalid-value branch in
packages/cli/src/commands/catalog.tsthrowsCliUsageErrorwith the existing message, the waycheck.tsdoes. The message text is unchanged.Test plan
catalog --type widgetto the "flag checks a command makes itself" table incli.agentMode.test.ts. It checks for exit 2, ausage_errorenvelope, the message, and nothing else on stdout. The new row fails onmain(expected 1 to be 2) and passes with the fix.cli.agentMode.test.tsandcommands/catalog.test.tsboth pass (590 tests).catalog --type widgetwith and without--json, before and after the fix. Both now exit 2.Not covered
--json) run, the message now comes after the command's help text. The CLI prints usage for anyCliUsageErrorwithout ahint(cli.ts, around line 665), assnapshot --at xalready does. I kept that default rather than add a hint just for this case.finishCommand(1)-on-bad-value pattern. This PR only changescatalog --type.