Repository navigation
feat(app): hint at flag-style usage when commands are invoked positionally - #14
Merged
Merged
Conversation
…onally When a user types `rc0 record set zone.com www A 1.2.3.4` (positional) instead of the flag form, Click exits 2 with a generic "Missing option '--name'." with no path forward. This was a reported UX wart in the v1.0.7 user-feedback triage (item #6) and was explicitly deferred to a later release in HANDOFF.md, but never landed. Switch the entry point to standalone_mode=False so we can intercept click.UsageError and append a one-line `hint:` listing the command's required flags. The hint fires for "Missing option", "Missing argument", and "Got unexpected extra argument" — the three shapes a confused positional-style user produces — and stays silent for unrelated errors like "No such option". Same exit code (2), same Click message, just an extra hint line. Existing Rc0Error and ConfirmationDeclined paths still own their exit codes (4–12); generic ClickException falls through to its own renderer. Coverage rises to 90.64%.
… sanity test Code-review pass on the usage-hint feature: - Hoist `from rc0.app import _run` from inside each integration test to the file's top-level imports — matches the existing pattern (line 13). - Drop `test_record_module_imported_for_resolution` — its assertions (record set/append are registered) are already exercised transitively by every other test in the file. - Drop the test-narrating comment about Click's option-vs-positional ordering and the verbose docstrings — the assertions are self-documenting; per CLAUDE.md keep only non-obvious WHY. - Replace the docstring on `test_hint_uses_canonical_flag_not_python_name` with the WHY (Typer's Python-name leakage) and add the same WHY to `test_run_returns_zero_on_version` (regression guard for the standalone_mode=False refactor).
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.
Summary
Closes the long-standing v1.0.7 polish item where Typer/Click's generic
Missing option '--name'.error left users with no path forward whenthey ran something like:
instead of the flag form. The CLI now appends a one-line
hint:afterClick's own message that lists the command's required flags:
The fix is global — one handler in
src/rc0/app.pycovers everycommand in the tree (record set/append/import, dnssec, tsig, …), no
per-command hooks. It fires for the three usage-error shapes a confused
positional-style user produces (
Missing option,Missing argument,Got unexpected extra argument) and stays silent for unrelated errorslike
No such option.Why
Item #6 from the v1.0.7 user-feedback triage
(
~/.claude/plans/can-you-please-analyse-quirky-kahan.md) — a realproduction user trying
rc0 record add zone.com www A 1.2.3.4got auseless error and bounced. HANDOFF.md flagged this as the v1.0.8 polish
item, but v1.0.8 ended up shipping
rc0 skill installinstead and thehint never landed. The
record add/update/replace-allrename inv2.0.0 didn't touch the underlying error class — same wart, same fix.
How
app(args=..., standalone_mode=False)soclick.UsageErrorreaches our handler instead of Click's defaultexit-2 renderer.
_format_usage_hint(exc)helper inspectsexc.ctx.command.paramsfor required
click.Optioninstances and builds the hint string.Returns
None(no hint) when there are no required options or themessage doesn't match a positional-style trigger.
Rc0Error/ConfirmationDeclinedclauses are preservedahead of the new generic
ClickExceptionclause, so the 4–12 exitcodes don't regress.
_runis a small inner helper so tests can drive the entry pointwithout subprocess.
Tests
tests/unit/test_usage_hint.py, 8 cases) — drives_format_usage_hintdirectly against syntheticUsageErrors forevery branch (each trigger, no ctx, no required opts, unrelated
message, Python-name
type_→TYPEplaceholder mapping).tests/integration/test_record_write_commands.py, 4new cases) — end-to-end via
_rununder capsys.460 tests pass. Coverage 90.64% (up from the 88% gate).
Test plan
uv run ruff check .— cleanuv run ruff format --check .— cleanuv run mypy— cleanuv run pytest— 460 passed, 90.64% coveragerc0 record set example.com www A 1.2.3.4→ hint firesrc0 record set example.com→ hint firesrc0 record set example.com --bogus-flag→ no hint (correct)rc0 --version→ exit 0 (no regression on the eager-callback path)rc0 --token bogus zone show nonexistent.example.com→ exit 4 with existingerror:line (Rc0Error path intact)