fix: clear error for balance without address; print commander errors once (fixes #498)

[humble-little-bear]

Fixes #498

Bug 1: offckb balance without address → Unknown address format undefined

balance [toAddress] declared the address optional (src/cli.ts:237). When omitted, undefined flowed into balanceOf() → CKB.balance(undefined) → ccc.Address.fromString(undefined), leaking the low-level Unknown address format undefined.

Fix: make the argument required (balance <toAddress>). Commander now emits a clear error: missing required argument 'toAddress' on stderr and exits 1.

Bug 2: commander errors printed twice on stderr

configureCommanderErrors() sets exitOverride() and writes the error line once via writeErr. The runCli() catch block then called logger.failure(code, message), which in non-JSON mode routed the same message through the winston console transport to stderr again — every commander error line was emitted twice.

Fix: only call logger.failure for CommanderError in JSON mode (where writeErr is suppressed and the structured record is the single emission). In human mode commander's writeErr already printed the line exactly once.

Verified on a local build:

$ offckb balance
error: missing required argument 'toAddress'   # was: Unknown address format undefined
$ offckb balance --unknown-flag
error: unknown option '--unknown-flag'         # was printed twice
$ offckb logs --tail abc
error: option '--tail <lines>' argument 'abc' is invalid. --tail must be a positive integer   # was printed twice

Tests

Added tests/cli-errors.test.ts (5 cases): missing-argument error printed once, unknown-option printed once, invalid option value printed once, single structured record in --json mode, and a valid balance <addr> invocation still reaches balanceOf. All 4 regression cases fail on the pre-fix code and pass after.

Changeset included (@offckb/cli patch).

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6623536c-5c8b-424d-8a05-84a75fcffafc

📥 Commits

Reviewing files that changed from the base of the PR and between e0dfd20 and 190b16a.

📒 Files selected for processing (3)

• .changeset/balance-commander-errors.md
• src/cli.ts
• tests/cli-errors.test.ts

---

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes
  • The balance command now requires a destination address.
  • Prevented duplicate error messages for missing arguments, unknown options, and invalid option values.
  • Preserved structured error output when using JSON mode.
  • CLI validation errors now consistently return exit code 1.

Walkthrough

The balance command now requires toAddress. Non-JSON Commander errors are no longer logged twice. JSON mode retains structured error output. New tests cover error output, exit codes, and successful balance wiring.

Changes

CLI error handling

Layer / File(s)	Summary
Command validation and error output src/cli.ts, .changeset/balance-commander-errors.md	The balance command requires toAddress. Commander errors are emitted once in non-JSON mode and remain structured in JSON mode.
CLI error behavior tests tests/cli-errors.test.ts	Tests cover missing arguments, unknown options, invalid option values, JSON output, exit codes, duplicate output prevention, and balance command wiring.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 190b1

This localized CLI change improves missing-argument validation and prevents duplicate error output; no actionable merge-blocking risk remains beyond normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies both fixes: the balance address error and duplicate Commander error output.
Description check	✅ Passed	The description directly explains both CLI fixes, their causes, expected behavior, implementation, and regression tests.
Linked Issues check	✅ Passed	The changes satisfy issue #498 by requiring the balance address and emitting Commander errors once in human and JSON modes.
Out of Scope Changes check	✅ Passed	The changeset, CLI updates, and regression tests are directly related to the requirements in issue #498.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}