From e0923a565a5fc9994c1fae4ad67d63ea71d791b2 Mon Sep 17 00:00:00 2001 From: Simon Klee Date: Wed, 4 Nov 2026 18:18:19 +0100 Subject: [PATCH] docs(cli-rs): record the command tree deviations Help and completion layout (Q12 b), usage error output, and the deferred --wizard (O-11). --- .../cli-rs/parity/deviations/G01-help-layout.md | 13 +++++++++++++ .../cli-rs/parity/deviations/G10-usage-errors.md | 16 ++++++++++++++++ packages/cli-rs/parity/deviations/G15-wizard.md | 9 +++++++++ 3 files changed, 38 insertions(+) create mode 100644 packages/cli-rs/parity/deviations/G01-help-layout.md create mode 100644 packages/cli-rs/parity/deviations/G10-usage-errors.md create mode 100644 packages/cli-rs/parity/deviations/G15-wizard.md diff --git a/packages/cli-rs/parity/deviations/G01-help-layout.md b/packages/cli-rs/parity/deviations/G01-help-layout.md new file mode 100644 index 00000000000..435a4c699fa --- /dev/null +++ b/packages/cli-rs/parity/deviations/G01-help-layout.md @@ -0,0 +1,13 @@ +# G01: help and completion layout + +TypeScript: Effect CLI renders help as `DESCRIPTION`, `USAGE`, `ARGUMENTS`, `FLAGS`, `GLOBAL FLAGS`, and +`SUBCOMMANDS` sections, with types such as `string` and `choice` after each flag and choices in the +description. `--completions` prints Effect CLI's own scripts. + +Rust: clap renders help as the description, `Usage:`, `Commands:`, `Arguments:`, `Flags:`, and `Global flags:`, +with value names such as `` and `` and `[possible values: ...]` and `[default: ...]` after the +description. `--completions` prints `clap_complete` scripts for the same shells (`sh` is bash, `pwsh` is +PowerShell). + +Reason: user decision Q12 (b): the same commands, flags, and descriptions, with a layout that may differ. The +commands, aliases, flags, types, and descriptions are proven equal by `crates/cli/src/tests/tree.rs`. diff --git a/packages/cli-rs/parity/deviations/G10-usage-errors.md b/packages/cli-rs/parity/deviations/G10-usage-errors.md new file mode 100644 index 00000000000..c57da5bf533 --- /dev/null +++ b/packages/cli-rs/parity/deviations/G10-usage-errors.md @@ -0,0 +1,16 @@ +# G10: usage errors + +TypeScript: a usage error prints the command's full help to stdout and `ERROR` with the message to stderr, then +exits 1. When an action flag (`--help`, `--version`, `--wizard`, `--completions`) is present, it runs even if +the rest of the line has a parse error (`opencode api --version` prints the version). An action flag followed +by a boolean literal still runs (`--version false`). + +Rust: a usage error prints the message and a short usage line to stderr, then exits 1; stdout stays empty. +Messages for the rules `args::normalize` and `args::validate` keep (`2 occurrences`, `omit the value`, +`Unrecognized flag: --x in command ...`, `key=value`) use the TypeScript wording. Other errors (unknown flag, +missing argument, invalid choice or number, a repeated value flag) use clap's wording and suggestions. A parse +error wins over an action flag, and `--version false` does not print the version. + +Reason: the layout of help and errors may differ (Q12 b). The exit code and the stream of the error are the +same, which is what scripts check. The action-flag cases need a malformed line and are not worth a second +parser. diff --git a/packages/cli-rs/parity/deviations/G15-wizard.md b/packages/cli-rs/parity/deviations/G15-wizard.md new file mode 100644 index 00000000000..1abcff553c4 --- /dev/null +++ b/packages/cli-rs/parity/deviations/G15-wizard.md @@ -0,0 +1,9 @@ +# G15: `--wizard` + +TypeScript: `--wizard` on any command walks through its arguments and flags with prompts, prints the resulting +command line, and runs it after confirmation. + +Rust: `--wizard` is accepted on every command and exits 1 with "--wizard is not supported yet (plan step +C.15)". + +Reason: orchestrator decision O-11 defers the wizard to C.15, which needs the C.p prompt kit.