fix(cli): suggest the closest flag on unknown-flag errors and drop the dry-run hint

Merged
AS
16d ago
+278-69

Summary

A mistyped flag produced an error whose only guidance was the generic validation advice, including "Use --dry-run to preview the request", which cannot fix a typo and is offered even on commands that have no --dry-run. Cobra suggests the nearest command for a mistyped command name but has no equivalent for flags, so the CLI never said which flag was meant.

$ cli create-user --nam x
Error (validation_error): unknown flag: --nam
Reason: CLI_VALIDATION
Fix:
  - Use --dry-run to preview the request and check parameters
  - Run the command with --help for runnable examples, or --usage for the machine-readable surface

Changes

  • Flag suggestions. flagutil.UnknownFlagSuggestionHint compares the unknown name against the command's visible local and inherited flags using the same rule cobra applies to commands: edit distance at most two, or a flag that starts with the typed name. A flag that is a prefix of the typed name also qualifies when the typed name is at most twice as long, so --output still points at --out (previously a hard-coded special case) without --identity-file matching --id. Flag, enum-value, and lost-key suggestions share one nearest ranker; only the tie policy differs per caller.
  • Parse-error hints. The flag error handler wraps parse errors in the existing hints error type with the suggestion plus a Run '<command> --help' ... or --usage pointer and asks the classifier to skip the built-in validation type hints. Reason, exit code, and JSON envelope shape are unchanged; declared reason rules and command-level manifest hints still apply.
  • Test in the existing CLI error test file: --output-formt and --Output-Format yield Did you mean --output-format?; a missing flag value keeps the --help/--usage pointer with no suggestion; none show the dry-run line.
  • README documents the hint source and the omission.
$ cli create-user --nam x
Error (validation_error): unknown flag: --nam
Reason: CLI_VALIDATION
Fix:
  - Did you mean --name?
  - Run 'cli create-user --help' for usage and examples, or --usage for the machine-readable surface

Not covered

Unknown command errors still receive the generic validation hints. Cobra already attaches its own "Did you mean this?" suggestion there, so the only remaining oddity is the dry-run line, which this change leaves alone.

Summary by cubic

Mistyped flags now name the closest valid flag instead of only showing generic validation advice, and the --dry-run hint is dropped because it cannot fix a typo and is offered even on commands without it.

  • UnknownFlagSuggestionHint compares the unknown flag against visible local and inherited flags using cobra's rule for commands: edit distance at most two, or a prefix relationship in either direction; when several flags qualify, only those at the smallest edit distance are named, so --output points at --out alone rather than every --output-* flag. The prefix rule subsumes the previous hard-coded --output → --out special case, and ranking flows through a shared nearest helper also used for enum-value and lost-key suggestions.
  • Flag parse errors now carry the suggestion plus a Run '<command> --help' pointer (and --usage), preserve any hints from an existing flag error handler, and skip built-in validation type hints; reason, exit code, and JSON envelope shape are unchanged. Matching is case-insensitive so case-only typos resolve, and the reverse-prefix rule is bounded so a long typo is not matched by a short flag it happens to start with.
  • Unknown command errors still show generic hints, since cobra already appends its own suggestion there.