`scripts/gen-cli-help.ts` runs the source `dsh` launcher with temporary Harness and Agents homes and captures the launcher, `dsh plugin`, and every shipped profile's text help (profile names come from `PROFILE_TEMPLATES`). It recursively discovers subcommands from each page's `Commands:` section, shows identical alias help once with every invocation, and writes `docs/cli-help.md`, its Chinese page, and their pairing record. The record resolves links between the two pages as written, so a first run already matches `verify-translation-pairing`. `verify-cli-help` checks all three files and runs as the `cli-help` doc-sync leaf, which the static CI lane also runs on an unbuilt tree. `dsh plugin` now owns `-h`/`--help` and reads its own options only before the forwarded pnpm arguments: `dsh plugin --help` prints its help instead of failing on the missing `--profile`, while everything after the pnpm command (including `-h`, `--help`, and `--profile`) reaches pnpm verbatim. A `--profile` placed after the pnpm command is no longer accepted; the v0.2.1-alpha.1 upgrade guide covers the migration. Refs #4114
1.5 KiB
Agent Note: Generate the CLI reference from command help
Status: implemented
English | 中文
Problem
Launcher flags, profile options, and nested commands have separate owners. A manually maintained command reference can omit subcommands or retain obsolete defaults.
Decision
The CLI reference captures the supported dsh launcher's help, the plugin forwarder's help, and each shipped profile's help, then recursively discovers the subcommands listed in each page's Commands: section. Shipped profile names come from PROFILE_TEMPLATES. Every page retains its complete help text; identical alias help appears once with all invocation forms.
Generation uses temporary Harness and Agents homes. Help exits before application work starts and requires no server or model. The plugin forwarder exposes its own help before pnpm arguments; flags after the pnpm command remain pnpm input.
The generated bilingual pages retain CLI output in its original language. verify-cli-help compares the complete pages and pairing record and runs with the documentation checks.
Alternatives considered
A second command inventory or help-specific runtime API would duplicate the parser's definitions. Reading actual help keeps the reference tied to the same descriptions, options, defaults, and examples users receive.
Consequences
Command changes update the reference through the same generator. Reviewers can compare complete help without assembling separate command invocations.