feat(help): wrap the short help page

[jdx]

Stacked on #1284.

What

-h never wrapped. A description longer than the terminal left room for simply ran off the end. mise's -j, --jobs — 63 characters of help plus [default: 8] [env: MISE_JOBS] — came out as one 110-column line:

  -j, --jobs <JOBS>      How many jobs to run in parallel; values below 1 are treated as 1 [default: 8] [env: MISE_JOBS]

The wide page has wrapped since it existed; -h is the form most people type. Now:

  -j, --jobs <JOBS>      How many jobs to run in parallel; values below 1 are
                         treated as 1 [default: 8] [env: MISE_JOBS]

Continuations sit under the description, and the block layout takes over on the same terms the wide page uses: a description with breaks of its own, or a column so deep there is no room left to say anything.

The one decision worth reviewing

Annotations join the description before the wrap, not after it. Appending them afterward would put [env: …] back out past the column that the wrapping had just brought the text into — which is the shape the old unwrapped line had, so it would have been wrapping that didn't help. Joining first means [default: 8] [env: MISE_JOBS] wraps along with the sentence, as above.

Two consequences follow from that, both intentional:

• An entry with no description but some annotation now carries it in the description column rather than flush against the usage, because that is where the text goes. Visible on a bare deprecated flag: --old [deprecated: …].
• Arguments are laid out for the page being rendered rather than reusing the model's pass, which had computed the wide page's column and preferred the long description — the wrong text at the wrong width for -h.

Two more renderer disagreements settled

Same as #1284, this turned up places where the three implementations had quietly disagreed for want of a spec exercising them:

• A deprecation label now trails the annotations rather than sitting between the description and them. Go put it right after the description, usage-argv put it last.
• An argument's deprecation label stays off the narrow page, which is what usage-lib always did and what the other two now do.

Verification

• benches/gate/tests/help.rs — mise's 211 commands, -h and --help, byte for byte: green.
• benches/gate/tests/fleet.rs — the seven jdx CLIs plus external shadows: green.
• go test ./... including go/conformance, which renders the Rust reference and compares: green.
• render-oracle reports no new divergences (the one it lists, an-explicit-synopsis-replaces-the-root-line, is the pre-existing declared one where the Tera templates don't read a spec-level usage).
• No corpus vectors needed regenerating.
• Off the gated benchmark: bench.startup runs usage --help, the long page, which this does not touch.

Four test assertions needed updating because they pinned unwrapped text. Each now reads the page with its layout collapsed rather than pinning where a break falls, which is what those tests were actually about.

This PR description was generated by Claude Code.

---

Note

Medium Risk
User-facing -h layout changes across three renderers, so wrapping, annotation order, and column fallback can shift help text for every CLI. No auth or data-handling impact.

Overview
Short help now wraps the way --help already did. Descriptions that used to run off the terminal (and annotations like [env: …] that used to sit past the wrap) are joined first, then wrapped into the usage column, with the same block-layout fallback when there is no room.

The three renderers (Rust usage_argv, Go argv, usage-lib templates) share that rule. Arguments get their own short-page layout pass instead of reusing the long page’s column and text. Deprecation labels trail other annotations; argument deprecation stays off the narrow page.

Tests that asserted exact inline strings now collapse whitespace so they check content, not wrap points.

^{Reviewed by Cursor Bugbot for commit 40e1e7c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 1a1ada3d-5ca1-44a9-81b8-056a4991a93d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁▃█▇▇▇▇▇▇▇▇▇▇▇	339,024,502 → 339,385,298	+0.11%	29.55 → 29.63ms	+0.25%
startup	▃▁▃▃▂▁▁▁▁▁▂▃██	885,962 → 885,268	-0.08%	0.93 → 0.87ms	-6.76%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

Shadow comparison

Parsing mise use -g node@20 against a shadow of mise's committed spec.
Reported, not gated: the shadow grows as the derive learns to express more, so
what to watch is the ratio rather than either column.

framework	stripped binary, bytes
usage	1320528
bpaf	2493280
clap	3101832

framework	instructions, cold parse	vs usage
usage	8336	—
clap	6315224	757x
bpaf	21909147	2628x

                                              min       p01       p10    median
usage-rs: argv -> struct                      412       418       423       430  ns
clap: build tree + parse -> struct         519209    519808    521383    525819  ns
bpaf: build parser + parse -> struct      1562032   1562032   1573424   1597510  ns

usage: argv -> struct                             489 ns      0.49 µs
clap: build tree + parse -> struct             533679 ns    533.68 µs
clap: parse -> struct, tree reused              23901 ns     23.90 µs
clap: build tree only                          326736 ns    326.74 µs

_{40e1e7c40df9 vs 66f4c13827cf · measured on the runner, not pushed to the history.}