Skip to content

fix(cli): report an invalid catalog --type as a usage error - #7678

Merged
miguel-heygen merged 2 commits into
heygen-com:mainfrom
jvarah:fix/catalog-type-usage-error
Nov 14, 2026
Merged

miguel-heygen merged 2 commits into
heygen-com:mainfrom
jvarah:fix/catalog-type-usage-error

Conversation

@jvarah

@jvarah jvarah commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

What

hyperframes catalog --type <value> with a value other than block or component now fails as a usage error: exit 2, and under --json a usage_error envelope carrying the same message.

$ hyperframes catalog --type widget --json 2>/dev/null; echo "exit code: $?"
# before
{"ok":false,"error":{"code":"runtime_error","message":"Invalid --type: \"widget\". Use \"block\" or \"component\"."}}
exit code: 1
# after
{"ok":false,"error":{"code":"usage_error","message":"Invalid --type: \"widget\". Use \"block\" or \"component\"."}}
exit code: 2

Why

A bad flag value is a usage mistake. The CLI's contract for those, which cli.agentMode.test.ts enforces, is exit 2 with a usage_error. catalog printed the message and called finishCommand(1), so agents saw a runtime_error and could not tell a typo from a failure.

Related work

Fixes #7669

How

The invalid-value branch in packages/cli/src/commands/catalog.ts throws CliUsageError with the existing message, the way check.ts does. The message text is unchanged.

Test plan

  • Unit tests added/updated: added catalog --type widget to the "flag checks a command makes itself" table in cli.agentMode.test.ts. It checks for exit 2, a usage_error envelope, the message, and nothing else on stdout. The new row fails on main (expected 1 to be 2) and passes with the fix. cli.agentMode.test.ts and commands/catalog.test.ts both pass (590 tests).
  • Manual testing performed: ran catalog --type widget with and without --json, before and after the fix. Both now exit 2.
  • Documentation updated (if applicable): not needed. No flag or documented behavior changes, only the exit code of an invalid value.
  • Comments follow CONTRIBUTING.md "Comments": no new comments.

Not covered

  • In a human (non---json) run, the message now comes after the command's help text. The CLI prints usage for any CliUsageError without a hint (cli.ts, around line 665), as snapshot --at x already does. I kept that default rather than add a hint just for this case.
  • I didn't sweep other commands for the same finishCommand(1)-on-bad-value pattern. This PR only changes catalog --type.

claude and others added 2 commits November 13, 2026 22:25
`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 miguel-heygen left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review at 5c51c969. There were no other reviews when I posted.

What's right

  • The fix. catalog.ts:229 throws CliUsageError with the unchanged message, so it goes through the same top-level envelope as check's flag errors.
  • Placement. The throw sits before the registry read (:234), so a bad --type fails 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.ts passes, 57 of 57.
  • Mutation. With catalog.ts reverted to main, the new row fails with expected 1 to be 2, as the body says.
  • By hand (bun run src/cli.ts catalog …):
    • --type widget exits 2 and prints the message to stderr.
    • --type widget --json exits 2, and stdout holds only {"ok":false,"error":{"code":"usage_error",…}}.
    • --type Block exits 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, because else if (args.type) treats "" as absent. #7673 made empty values invalid for check's numeric flags. args.type !== undefined here 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 with finishCommand(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, Comments included.
  • 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 captures and Semantic PR title.
  • Skills: manifest in sync and Studio: edit accuracy gate were 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.

@miguel-heygen
miguel-heygen added this pull request to the merge queue Nov 14, 2026
Merged via the queue into heygen-com:main with commit affa03b Nov 14, 2026
70 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

cli: invalid catalog --type exits 1 with runtime_error instead of a usage error (exit 2)

3 participants