Terminal color support across dz display surfaces

[djdarcy]

Summary

Add terminal color support across dz display surfaces (dz list, dz tree, dz info, dz kit list, dz kit status, stderr warnings). Goal: faster at-a-glance scanning by giving distinguishing visual weight to platform markers, virtual-kit annotations, collision/alias markers, and warning routing.

This issue is the design + implementation surface; it should probably go through a /dev-workflow-process first since color decisions are cross-cutting and hard to retract once shipped.

Motivation

Observed in dz kit list dazzletools (v0.7.28): the platform column shows windows mixed with cross-platform. Without color, the eye has to read every cell to find platform-specific tools. With distinct colors, scanning is near-instant.

Same pattern applies across the display surface area:

• dz list (sectioned, v0.7.28) — section headers, virtual-kit annotations, [+] markers
• dz tree — virtual-kit branches, deprecated/relocated entries (Phase 5)
• dz info — runtime type, platform, alias provenance banners
• Warnings + errors on stderr — visually distinct from stdout

Design considerations

Library choice

Option	Pro	Con
rich	Modern, capable, broad ecosystem	Heavy dependency for a CLI tool
colorama	Mid-weight, Windows-friendly	Older API, mostly initialization helpers
Raw ANSI escapes	Minimal, no deps	Older cmd.exe doesn't render without help; Windows Terminal handles it natively

Lean: raw ANSI + lazy colorama init for older Windows hosts. Keeps the dependency surface small while supporting all common platforms. If the project ever wants tables/spinners/progress bars, rich becomes more attractive — but that's not what color alone needs.

Honoring the user

• NO_COLOR env var (no-color.org): when set (any value), all output is plain. Industry convention.
• DZ_COLOR=auto|always|never project env var (or color config key) for explicit override.
• isatty() gating: by default, color only when stdout/stderr is a terminal. Piped output stays clean.
• Codepage safety: per project CLAUDE.md, no Unicode characters in the color sequences themselves — pure ASCII text + ANSI escape codes only. Modern terminals handle ANSI; old cmd.exe needs colorama.init() lazy-loaded.

Accessibility

• Color-blind safe palette (avoid red/green-only distinctions for critical info)
• Color is auxiliary, not primary — meaning must be conveyed by text too (bold + color, not just color)
• Test against the most common deuteranopia/protanopia simulations

Proposed taxonomy (starter)

Element	Style	Rationale
Section headers (canonical kits)	bold	Structural hierarchy
Virtual-kit headers	bold + cyan	Distinct from canonical
(virtual kit '...') annotation	dim	De-emphasized metadata
Platform: windows	yellow	Platform-specific (caution color, attention-getting)
Platform: cross-platform	green	"Universally usable"
Platform: linux, macos	yellow	Platform-specific (consistent with windows)
Collision marker [*]	red	Caution, demands attention
Alias marker [+]	cyan	Informational link
Provenance banner ((resolved via ...))	dim	De-emphasized metadata
Stderr warnings	yellow	Conventional
Errors	red	Conventional

Acceptance criteria

• dz display surfaces honor NO_COLOR env var (no color when set)
• DZ_COLOR=always forces color even when piped (for deliberate logging)
• DZ_COLOR=never suppresses color even on a TTY
• Default behavior: color only when output is a TTY
• Color applied consistently: same role gets same color across surfaces
• Codepage 437/1252 / pure ASCII compliance — no Unicode chars in escape sequences
• Color taxonomy documented (in code + user docs)
• Tests for the color-emit logic (mock TTY, NO_COLOR, DZ_COLOR overrides)
• Manual visual review across: Windows Terminal, cmd.exe (legacy), PowerShell, bash-on-WSL, real Linux terminal

Phasing suggestion

This should not be a single mega-PR. Suggested commit progression:

1. Library bootstrap commit: pick library/approach (raw ANSI + colorama recommended), wire NO_COLOR + DZ_COLOR + isatty() gating into a small colors.py helper module. No display changes yet.
2. Stderr warnings + errors: first user-visible application, low blast radius.
3. Section headers + virtual-kit annotations: structural visual cues.
4. Platform markers + collision/alias markers: high-value scanning aid.
5. Provenance banners + dim metadata: polish.

Each commit ships independently and the tester checklist verifies the relevant surface.

References

• Reported via /obsidian after v0.7.28 push: private/claude/notes/cli/2026-04-28__17-13-35__both_dz-kit-list-formatting-parity-and-color.md
• Related: drill-in column parity (filed separately, smaller scope)
• Phase 5 graduation may add new render needs (deprecation banners) — color taxonomy should leave room
• Industry convention: no-color.org, colorama, rich

[djdarcy]

v0.7.37 — Closes #49 (terminal color taxonomy)

Shipped in the v0.7.37 commit. Tier 1 final commit of the master closeout plan. Terminal color lands in dazzlecmd-lib (not just dazzlecmd) so every consumer — dazzlecmd, amdead, wtf-windows, and any future personal aggregator — inherits color emphasis on the standard meta-command render surfaces for free.

What shipped

• New dazzlecmd_lib.colors module — 8-color ANSI palette (RESET/BOLD/DIM/RED/GREEN/YELLOW/CYAN/BRIGHT_RED); should_use_color(stream) env-aware TTY probe with documented precedence; colorize(text, *codes) wrapper; colorize_for(stream, text, *codes) for the explicit-stream pattern; and semantic stderr wrappers warn(text) (YELLOW) and error(text) (BRIGHT_RED) that default the stream to sys.stderr so call sites collapse to one-liners.

• dazzlecmd-lib[color] optional extra — colorama as a Windows-only optional dep for legacy cmd.exe. Modern Windows 1511+ doesn't need it (native VT processing).

• Per-surface color:

  • render_list: section headers BOLD, virtual-kit annotation DIM, [*] shadow marker BOLD+RED, [+] dual-presence marker CYAN, flat-fallback header row BOLD.
  • render_info: alias provenance line DIM (qualified + standard variants), "Shadow status:" banner BOLD+YELLOW.
  • render_tree: root header BOLD, kit names BOLD, markers ([always_active]/[aggregator]/[disabled]/[virtual]) DIM, [shadowed] BOLD+RED, virtual-kit alias arrows DIM.
  • render_kit_list: kit names BOLD, (always active) DIM, cross-platform DIM (OS-specific values plain so they stand out), (not found) DIM.
  • render_kit_status: kit names BOLD.
  • Stderr user-facing paths in default_meta_commands.py, cli_helpers.py, and dazzlecmd's _cmd_setup — YELLOW advisories, BRIGHT_RED errors, via warn / error wrappers.

Acceptance criteria status

• NO_COLOR env var honored (any value → no color)
• DZ_COLOR=always forces color through pipes (Windows colorama strip=False)
• DZ_COLOR=never suppresses TTY color
• Default: color only on TTY
• Consistent role-to-color mapping across all render surfaces
• Codepage 437/1252 / pure ASCII compliance — only 7-bit ANSI escape bytes
• Color taxonomy documented (module docstring, CHANGELOG, checklist)
• Tests: 33 in tests/test_colors.py covering env precedence, isatty fallback, colorize_for, warn/error, public constants regression guard
• Manual visual review across terminals — checklist tests/checklists/v0.7.37__Tier1B__color-taxonomy.md ready; user-driven cross-shell run pending

Color detection precedence

1. NO_COLOR set (any value, including empty) → no color (community standard).
2. DZ_COLOR=always OR FORCE_COLOR=1 → color on (overrides isatty).
3. DZ_COLOR=never → no color.
4. Fallback: stream.isatty().

Tests

• 1012 passed, 13 skipped (up from 979 in v0.7.36; +33 new in tests/test_colors.py).
• Live verification: DZ_COLOR=always dz list / dz tree / dz info <virtual-alias> / dz setup nonexistent all emit correct ANSI bytes; dz list | cat -v plain by default.

Design

2026-05-11__04-14-42__dev-workflow-process__v0-7-37-color-taxonomy.md

Next

Tier 1 of the 0.7.x master closeout plan closes with this commit. Remaining Phase 4e tail items (#50): v0.7.25 test checklist backfill, wtf-windows upstream PR, virtual md kit — all deferred to Tier 0/7 of the master plan.