Skip to content

fix(cli): report argument errors through the --json contract - #411

Open
ArcueidMP wants to merge 7 commits into
Tencent:mainfrom
ArcueidMP:codex/issue-387-cli-errors
Open

ArcueidMP wants to merge 7 commits into
Tencent:mainfrom
ArcueidMP:codex/issue-387-cli-errors

Conversation

@ArcueidMP

Copy link
Copy Markdown
Contributor

With --json, a command-line parsing failure currently prints clap's usage error to stderr and leaves stdout empty, so a caller reading the JSON contract sees no error at all. The case from the issue, --session given before the subcommand, is also misreported: clap suggests --version and prints Usage: bsk --version <COMMAND>.

Fixes #387.

  • When --json appears in argv before --, clap failures are written to stdout as the usual flat error: code: "invalid_params", exit_code: 1, data.reason: "cli_parse_error". message is clap's summary on one line; data.details keeps the full clap text with tips and usage. The flag is read from raw argv because clap can stop before it reaches --json; a --json inside a value (--selector=--json) or after -- does not count.
  • A misplaced --session / --tab-id gets a rebuilt clap error: the tip says the option belongs after a supporting subcommand, and the usage line is that of the command being parsed instead of one built around --version. The same text is the JSON hint.
  • Human output, exit codes and help are otherwise unchanged: usage errors stay on stderr with exit 1, and --help / --version print text and exit 0 even with --json.
  • Document flag placement and the parse-error shape in the CLI README. The new tests also run in the Windows job, since the report came from PowerShell with redirected stdout.
$ bsk --session s1 click --selector '#submit' --json
{
  "code": "invalid_params",
  "message": "unexpected argument '--session' found",
  "hint": "--session and --tab-id are command-specific options; place them after a subcommand that supports them, e.g. `bsk click --session <id> --tab-id <tab> --selector '#submit'`; run `bsk <cmd> --help` for supported options",
  "exit_code": 1,
  "data": {
    "details": "error: unexpected argument '--session' found\n\n  tip: --session and --tab-id are command-specific options; ...\n\nUsage: bsk [OPTIONS] <COMMAND>\n\nFor more information, try '--help'.",
    "reason": "cli_parse_error"
  }
}

--session and --tab-id are not made global, which the issue suggests first. Most commands require them and some do not accept them. A clap global argument cannot be required and would collide with each command's own --session, so commands would lose clap's per-command validation and help, and commands such as status would silently accept a session. --json, --quiet and --verbose were already global; a parse test now covers both placements.

Testing

  • cargo test -p bsk --test cli_usage_errors --test cli_parse --locked: process-level coverage of stdout/stderr separation, exit codes, redirected stdout, non-UTF-8 argv, forced color, nested subcommands, and the -- / --flag=--json cases
  • cargo test -p bsk --locked
  • cargo fmt --all -- --check, cargo clippy -p bsk --all-targets --locked -- -D warnings

Keep the CLI README's flag-placement and parse-error section alongside the
new structured extraction section.
Keep both Unreleased fixes: the CLI parse-error entry for Tencent#387 and the DSH
tool-registration entry for Tencent#444.
Keep the global output flag parse test next to main's renamed background
session test.
The focus mapping cases from Tencent#447 still looked up browser_session after Tencent#446 renamed the tool, so they failed on main as well.
Keep upstream's explicit bsk_session registration check and move the issue Tencent#387 changelog entry back under Unreleased after 0.3.3.

This branch has not been deployed

No deployments
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.

[Bug] A global flag before the subcommand fails on stderr only, with empty stdout

1 participant