fix(@effect/cli): use Ansi.blackBright for Weak spans so --help is readable on dark terminals

[Zelys-DFKH]

Fixes #6200

@effect/cli marks "Weak" spans in --help output with Ansi.black, which produces ANSI code 30 (black foreground). On dark terminal backgrounds (the default in most modern terminals), the text becomes black-on-black and disappears. NO_COLOR=1 does not help; the styling is applied in the annotation layer before the renderer sees it.

The fix is in toAnsiDoc in packages/cli/src/internal/helpDoc/span.ts:

// before
case "Weak": {
  return Doc.annotate(toAnsiDoc(self.value), Ansi.black)
}

// after
case "Weak": {
  return Doc.annotate(toAnsiDoc(self.value), Ansi.blackBright)
}

Ansi.blackBright is ANSI code 90 (dark gray), readable on dark and light backgrounds. Ansi.dim would be cleaner semantically for de-emphasized text, but it is not exported by @effect/printer-ansi, so blackBright is the right call within the current API.

I added a regression test that renders a Weak span through HelpDoc.toAnsiDoc and asserts ANSI code 30 is absent. All 162 existing CLI tests pass.

Love the library. Glad to contribute!

[changeset-bot]

🦋 Changeset detected

Latest commit: dac7ad0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@effect/cli	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Zelys-DFKH]

Gentle ping — this PR fixes a UX bug where --help output is unreadable on dark terminals. Uses Ansi.blackBright for Weak spans as discussed in #6200. All CI passing and ready for review! 🎯

[IMax153]

@Zelys-DFKH please submit a screenshot of the changes on the terminal background you are quoting as an issue.

[Zelys-DFKH]

Here's the before/after on a dark terminal:

In the BEFORE block, only the cyan command names show up. All the Weak-span text (<command>, [options], descriptions, parenthetical defaults) is rendered with ESC[30m (pure black) and vanishes against the dark background. In the AFTER block, the same content comes through in ESC[90m (dark gray) and is fully readable.

On a light terminal both colors are visible, so the change is a strict improvement: dark terminals go from broken to working, light terminals see no regression.

[IMax153]

@Zelys-DFKH - two comments:

1. This looks like the output of the Effect v4 CLI, not the Effect v3 CLI - this repository contains the Effect v3 source code - the Effect v4 source code is in effect-smol. Did you mean to also open a PR there?
2. Looks like there are formatting issues (you can ignore the failing node test for now)

[Zelys-DFKH]

Hey @IMax153, fair to flag it — the demo was probably too polished for a standard bug reproduction.

It's genuine v3 output. The script ran @effect/cli@0.75.1 + effect@3.21.x, same packages ncaq used in #6200 (reproducer is already there if you want to run it). BEFORE shows Weak spans invisible at ESC[30m, AFTER shows them at ESC[90m.

Your comment sent me digging through effect-smol, which was worth it. The v4 CLI lives at packages/effect/src/unstable/cli/ — completely different architecture, no HelpDoc/Span with a Weak variant. It already uses Ansi.blackBright throughout, so there's nothing to port.

Formatting fix pushed. Appreciate you keeping a close eye on this one!