docs(cli-rs): record the command tree deviations

Help and completion layout (Q12 b), usage error output, and the deferred --wizard (O-11).
This commit is contained in:
Simon Klee
2026-11-04 18:18:19 +01:00
Unverified
parent 01ab034b56
commit e0923a565a
3 changed files with 38 additions and 0 deletions
@@ -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 `<string>` and `<choice>` 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`.
@@ -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.
@@ -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.