Mark required CLI flags in help output

[leopoldsedev]

Prefix mandatory options with (required) using existing Commander metadata while preserving standard help descriptions and annotations.

Human comments

What was wrong

bb <command> --help gave no indication which options are mandatory. Commander already knows: .requiredOption() sets option.mandatory, and the CLI relies on it to fail with error: required option '--project <id>' not specified. But the default help formatter never reads that flag — it annotates defaults, choices, presets and env vars only. So the information existed and was simply not rendered, and the only way to discover a required flag was to run the command and read the error.

What changed

apps/cli/src/index.ts: the root program now sets a configureHelp({ optionDescription }) override that prefixes (required) to the description of any option with option.mandatory, delegating to Help.prototype.optionDescription for the rest. Commander propagates configureHelp to subcommands, so one override at the root covers every command group.

--prompt <prompt> (required) Initial prompt for the thread
--json Print machine-readable JSON output
--project <id> (required) Project ID
--environment <id-or-path> Existing environment ID or unmanaged workspace path

The marker goes first so it stays scannable when descriptions wrap, and so it does not collide with Commander's trailing (default: …) / (choices: …) annotations. Help text is otherwise untouched and there are no other behavioral changes.

How you verified

Added marks mandatory flags in help without marking optional flags to apps/cli/src/__tests__/startup-graph.test.ts. It asserts the marker on bb thread spawn's --project and --prompt, its absence on the optional --provider, and its absence on bb thread list's optional --project — so it catches both a missing marker and an over-eager one. The test matches on the flag plus the marker rather than on description wording, so it does not break when descriptions are reworded.

• Fails on main without the index.ts change (--project matcher fails), passes with it.
• npx vitest run src/__tests__/startup-graph.test.ts in apps/cli — 8 passed.
• turbo run typecheck --filter=@bb/cli — clean.
• Manual: bb thread spawn --help, bb thread list --help, bb --help.

AGENT GENERATED