fix(cli): piped --help no longer glues flag names to descriptions

[DavidWells]

Split from #8300 (2 of 9).

What

The help renderer separated flag names from descriptions with only an ANSI color code. Piped output — netlify build --help | grep dry — read:

--dryDry run: show instructions without running them (default: false)

Now every row is padded with real whitespace, in every terminal. Also replaces a @ts-expect-error with a typed noBaseOptions getter.

Why it helps agents

--help is the CLI's primary self-documentation surface, and agents read it exclusively through pipes. Glued term+description corrupts the data they parse to learn flags.

Testing

• New unit tests rendering help without a TTY; committed help snapshots unchanged
• typecheck ✓ lint ✓ 408 unit tests ✓

[github-actions]

📊 Benchmark results

Comparing with 3c41e72

• Dependency count: 1,127 (no change)
• Package size: 379 MB ⬇️ 0.00% decrease vs. 3c41e72
• Number of ts-expect-error directives: 358 ⬇️ 0.28% decrease vs. 3c41e72

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes

  • Improved help output spacing and alignment, making option descriptions easier to read.
  • Fixed spacing for short and long option labels so descriptions stay consistently separated.
  • Updated help behavior so option sections are handled more reliably when base options are disabled.

• Tests

  • Added coverage for help formatting in non-terminal environments to verify spacing and section visibility.

Walkthrough

This PR adds a public noBaseOptions getter to BaseCommand, replacing a previous TypeScript suppression needed to read the private flag during help rendering. It also adjusts the padding calculation in the help formatting logic (formatItem) to use a Math.max-based formula affecting padEnd and helper.wrap calls, changing spacing/alignment of help output. A new unit test file validates help text spacing, column alignment, and noBaseOptions state changes after calling noHelpOptions().

Estimated code review effort: 2 (Simple) | ~12 minutes

Changes

File	Change Summary
src/commands/base-command.ts	Added public noBaseOptions getter; updated help term length calculation and formatItem padding logic
tests/unit/commands/help-format.test.ts	New test file validating help output spacing and noBaseOptions toggling

Related PRs: None identified.

Suggested labels: type: bug, area: cli-help

Suggested reviewers: None identified.

🐰 A rabbit tweaks the spacing, byte by byte,
Padding columns till they align just right,
A getter now open, no more hidden peek,
Tests confirm the help text does what we seek.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main fix: piped CLI help no longer glues flag names to descriptions.
Description check	✅ Passed	The description matches the changeset and explains the help-formatting fix, typed getter, and tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch split/help-pipe-format

---

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.}

[coderabbitai]

🧹 Nitpick comments (1)

src/commands/base-command.ts (1)

374-376: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Padding fix looks correct; consider using the new getter consistently.

The Math.max(termWidth + HELP_SEPARATOR_WIDTH - ..., term.length + 2) formula correctly guarantees a minimum 2-space gap even when the term exceeds the computed column width, fixing the concatenation bug (--dryDry...). The helper.wrap indent correctly compensates for the bang prefix length.

One nit: line 406 (if (command.#noBaseOptions === false)) still reads the private field directly, right next to the new command.noBaseOptions getter used at line 361. Since the getter now exists precisely to expose this state publicly, using it here too would be more consistent.

♻️ Optional consistency tweak

-      if (command.#noBaseOptions === false) {
+      if (command.noBaseOptions === false) {

Also applies to: 406-406

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/commands/base-command.ts` around lines 374 - 376, Use the new
command.noBaseOptions getter consistently instead of reading
command.#noBaseOptions directly in base-command.ts. Update the conditional in
the relevant command/help flow to reference the getter, matching the existing
usage near the earlier check and keeping the encapsulation consistent.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/commands/base-command.ts`:
- Around line 374-376: Use the new command.noBaseOptions getter consistently
instead of reading command.#noBaseOptions directly in base-command.ts. Update
the conditional in the relevant command/help flow to reference the getter,
matching the existing usage near the earlier check and keeping the encapsulation
consistent.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f7007dc3-43f3-4636-9509-3bbc83e1d73e

📥 Commits

Reviewing files that changed from the base of the PR and between 3c41e72 and 853b667.

📒 Files selected for processing (2)

• src/commands/base-command.ts
• tests/unit/commands/help-format.test.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• netlify/blueprints (manual)