roundel/policy

The output policy — one answer to "where is this output going?", read from a Runtime, never from process (R1, R2, R9 of roundel; U2 of the stack).

import { colorLevel, outputMode, flown } from 'roundel/policy';

FunctionsCopy Anchor Link

colorLevelCopy Anchor Link

chalk's level, obeying the user's explicit instruction in any mode (R2 revised 2026-09-08): NO_COLOR wins outright; then FORCE_COLOR=0, which supports-color settles before it looks at any flag, so FORCE_COLOR=0 --color=256 is off and not 2 — an explicit "colour off" is never undone by a level flag; then the --color flags in argv, an exact --color=256 beating a numeric FORCE_COLOR as chalk's own suite says; then FORCE_COLOR. --json is the one output the level never enters: structured text carries no escapes. The mode decides redraws (U2), never the level.

function colorLevel(rt: Runtime, opts?: ModeOptions): ColorLevel;

Returns ColorLevel

ConstantsCopy Anchor Link

flownCopy Anchor Link

What fly() decided, once, for the process: the colour level and each token's paint. Every token reads it; nothing writes it but fly(). Until then the level is 0 and every token is the identity, so a program that never declares its runtime prints plain text.

const flown: {
    level: ColorLevel;
    paint: Partial<Record<TokenName, Paint>>;
};

outputModeCopy Anchor Link

First match wins: json if asked; accessible if CLI_ACCESSIBLE; ci if CI and not a TTY; pipe if not a TTY; else tty.

const outputMode: (rt: Runtime, opts?: ModeOptions) => OutputMode;

InterfacesCopy Anchor Link

ModeOptionsCopy Anchor Link

interface ModeOptions {
    /** Whether this run was asked for `--json`: the engine's knowledge, not the process's. */
    json?: boolean;
}

RuntimeCopy Anchor Link

The slice of a runtime the policy needs. burgee's processRuntime satisfies it, so does a two-line literal in a test; nothing here imports a type from anywhere.

interface Runtime {
    env: Record<string, string | undefined>;
    isTTY: {
        stdout: boolean;
    };
    /**
     * The process arguments, when the caller owns them: `--color`, `--no-color` and
     * `--color=…` are read in `policy.ts` and nowhere else. A test literal leaves it out.
     */
    argv?: readonly string[];
    /**
     * The caller asked for quiet (burgee's `--quiet`, agent-lint-conformance R2): draw no
     * decoration — no spinner, no progress, no status line. A field and not a mode, because the
     * mode still answers where output goes; this answers whether decoration goes there at all.
     * flagstaff's `hoist` reads it. Data and errors are the caller's to print and are never quiet.
     */
    quiet?: boolean;
}

TypesCopy Anchor Link

ColorLevelCopy Anchor Link

chalk's levels: none, 16 colours, 256 colours, truecolor.

type ColorLevel = 0 | 1 | 2 | typeof MAX_LEVEL;

FormatCopy Anchor Link

One util.styleText format name: 'bold', 'red', 'redBright', 'dim'…

type Format = import('node:util').InspectColor;

OutputModeCopy Anchor Link

type OutputMode = 'tty' | 'pipe' | 'json' | 'accessible' | 'ci';

PaintCopy Anchor Link

A style as a token paints it: styleText format names, or the SGR parameters of one foreground colour (38;5;n for 256 colours, 38;2;r;g;b for truecolor), which styleText cannot express.

type Paint = readonly Format[] | {
    readonly sgr: readonly number[];
};

TokenNameCopy Anchor Link

type TokenName = 'error' | 'warn' | 'ok' | 'hint' | 'muted' | 'command' | 'flag' | 'value' | 'heading';