Color Support Reporter

A small CLI that reports the available color output level for both stdout and stderr, honoring command-line overrides and environment configuration before falling back to automatic detection.

Capabilities

Respects explicit color level flags

• Given argv of ['--color=256'] and no relevant env vars, formatReport(summarizeColorSupport({ argv: ['--color=256'], env: {} })) returns text that includes stdout: level=2 (flag) and stderr: level=2 (flag), and the sample line contains ANSI escape codes for colored text. @test

Disables colors when requested

• Given argv of ['--no-color'] and env of { FORCE_COLOR: '3' }, both streams report level=0 (flag) and the sample line contains no ANSI color codes. @test

Honors FORCE_COLOR when no flag is set

• Given empty argv and env of { FORCE_COLOR: '1' }, both streams report at least level=1 (env), and the sample line uses basic color styling. @test

Implementation

@generates

The CLI must treat flags as the highest-precedence override, then environment values, then per-stream detection. When options are omitted, default to process.argv.slice(2), process.env, and the provided streams (falling back to process.stdout and process.stderr). The sample line should apply styling only when the stdout level is greater than 0.

API

/**
 * Builds a per-stream color support summary using argv/env overrides before falling back to detection.
 */
export function summarizeColorSupport(options?: {
  argv?: string[];
  env?: Record<string, string | undefined>;
  stdout?: NodeJS.WriteStream;
  stderr?: NodeJS.WriteStream;
}): {
  stdout: { level: 0 | 1 | 2 | 3; source: 'flag' | 'env' | 'detected' };
  stderr: { level: 0 | 1 | 2 | 3; source: 'flag' | 'env' | 'detected' };
  sample: { text: string; appliesColors: boolean };
};

/**
 * Produces human-readable lines such as:
 * stdout: level=2 (flag)
 * stderr: level=2 (flag)
 * sample: <colored or plain text>
 */
export function formatReport(report: ReturnType<typeof summarizeColorSupport>): string;

Dependencies { .dependencies }

chalk { .dependency }

Provides terminal color detection, flag/env overrides, and styling helpers.