mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-16 05:01:03 +03:00
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:
@@ -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.
|
||||
Reference in New Issue
Block a user