Console capabilities

Platform spec feature

Console capabilities

Back to Terminal and console ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (3)

1. 0020-no-color-semantics NO_COLOR disables color Accepted

   Any non-empty NO_COLOR strips ANSI emission.

   Context

   Users and CI expect no-color.org semantics for accessibility and logs.

   Decision

   Rule	Detail
   NO_COLOR	Non-empty value must force ShouldEmitAnsi() false
   Reference	no-color.org

   Consequences

   Capability probes and markup render paths consult the same gate.

   Verification anchors

   CapabilitiesTests.bd; Console/Capabilities.bd.

   Open full ADR page

2. 0021-colorterm-truecolor-upgrade COLORTERM upgrades to TrueColor Accepted

   COLORTERM presence selects TrueColor when color allowed.

   Context

   Modern terminals advertise truecolor via COLORTERM without breaking NO_COLOR.

   Decision

   Rule	Detail
   Probe	COLORTERM set → TrueColor when color not stripped
   FORCE_COLOR	May enable emission on non-TTY stdout

   Consequences

   EffectiveColorModel reflects env probes before SGR downgrade (see D-CORE-TERM-0003).

   Verification anchors

   CapabilitiesTests.bd.

   Open full ADR page

3. 0022-lossy-color-downgrade Lossy color downgrade Accepted

   RGB downgrades through palette ladders automatically.

   Context

   Callers should not manually pick CSI color modes per terminal.

   Decision

   Rule	Detail
   Downgrade	RGB → indexed → basic is lossy
   API	No per-sequence model selector on public helpers

   Consequences

   Styled output remains readable on Basic16 hosts without author branches.

   Verification anchors

   AnsiSgrGoldenTests.bd; capability + SGR integration.

   Open full ADR page

Articles

• Contracts and edge cases MUST rules for capability probing and color stripping. article Standard Reviewed Thu May 21
• Design model Capability record, color models, and environment-driven probing. article Standard Reviewed Thu May 21
• Examples Checking capabilities before custom styling. article Standard Reviewed Thu May 21
• Flow and algorithm Probe and strip algorithms for terminal capabilities. article Standard Reviewed Thu May 21
• Verification and traceability Tests and sources for capability probing. article Standard Reviewed Thu May 21

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 3 SpecSection(s) · 1 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  Terminal and console

  Parent area

• Feature
  ANSI escape model

  ShouldEmitAnsi gates escape emission

What this feature specifies

Console.Capabilities and Platform.Terminal probe whether styled output is appropriate: TTY detection on fd 1, environment flags (NO_COLOR, FORCE_COLOR, COLORTERM, TERM), and the effective color model used by Ansi.Sgr downgrade logic.

Contract statement

• ShouldEmitAnsi() must return false when NO_COLOR is set (non-empty value per EnvFlagSet).
• When not forced, non-TTY stdout must suppress ANSI emission.
• FORCE_COLOR must enable emission even when stdout is not a TTY.
• EffectiveColorModel must return Basic16 when color is stripped, otherwise the probed model (Basic8, Basic16, Indexed256, TrueColor).
• Platform.Terminal.ForcePlainText() should align with dumb terminals (TERM=dumb) and piped stdout unless FORCE_COLOR is set.

Implementation anchors

• compiler/corelib/packages/console/src/Console/Capabilities.bd
• compiler/corelib/packages/console/src/Platform/Terminal.bd
• Tests: CapabilitiesTests.bd

Decisions

No open decisions. Closed choices are normative ADRs under adr/ (D-CORE-TERM-0020 … D-CORE-TERM-0022); use the reader ADRs tab for expandable detail.

Articles

• NO_COLOR disables colorAny non-empty NO_COLOR strips ANSI emission.
• Contracts and edge casesMUST rules for capability probing and color stripping.
• Design modelCapability record, color models, and environment-driven probing.
• ExamplesChecking capabilities before custom styling.
• Flow and algorithmProbe and strip algorithms for terminal capabilities.
• Verification and traceabilityTests and sources for capability probing.