terminal library

Terminal output for command-line applications: a levelled logger, a spinner that degrades to plain lines off a TTY, and a colour theme that honours NO_COLOR, FORCE_COLOR, and CI.

Writes through WriteStream, the same abstraction the command framework uses, so a single captured stream observes all output in tests.

Classes

CliLogger

Mirror of the TS CliLogger interface.

ColorActionTheme

Mirror of the nested color.action object.

ColorTheme

Mirror of the TS color const object. The optional Picocolors override is the DI seam replacing the vitest module mock of picocolors.

Picocolors

The subset of picocolors' color functions used by the dotweave CLI.

Spinner

Mirror of the TS Spinner interface.

SpinnerTimer

Cancellable handle mirroring the TS setInterval id, injectable so tests can drive ticks manually (the vitest fake-timer seam).

StdioWriteStream

Adapts a dart:io io.Stdout to WriteStream, emitting the same ANSI sequences Node's clearLine/cursorTo write.

Symbols

Mirror of the TS SYMBOLS const object.

WriteStream

The slice of an output stream a CLI needs: write text, know whether it is attached to a terminal, and move the cursor for in-place updates.

Constants

SYMBOLS → const Symbols

The symbols used for terminal output.

Properties

color → ColorTheme

The color theme used for terminal output.

final

pc → Picocolors

The default picocolors instance, mirroring import pc from "picocolors".

final

Functions

createCliLogger({WriteStream? stderr, WriteStream? stdout, String? tag, ColorTheme? color, Symbols? symbols, Spinner createSpinner(WriteStream stream, String text)?}) → CliLogger

Build a logger with optional stream overrides and optional prefix tag. Tag is only cosmetic and prepends a dim "tag" prefix to every output line. The optional color/symbols/createSpinner overrides are the DI seams replacing the vitest module mocks of ./theme.ts and ./spinner.ts.

createColors({bool? enabled}) → Picocolors

picocolors' createColors, defaulting enablement to the module-level support detection.

createSpinner(WriteStream stream, String text, {ColorTheme? color, Symbols? symbols, EnvLookup? readEnv, SpinnerTimerFactory? startInterval}) → Spinner

The optional color/symbols/readEnv/startInterval overrides are the DI seams replacing the vitest theme mock, vi.stubEnv, and fake timers.

lookupPlatformEnv(String name) → String?

Default EnvLookup over Platform.environment.

resolveIsColorSupported({EnvLookup? readEnv, List<String> argv = const [], String? platform, bool? stdoutIsTTY}) → bool

picocolors' module-level isColorSupported expression: color is enabled unless NO_COLOR/--no-color disables it, and one of FORCE_COLOR, --color, win32, an interactive non-dumb terminal, or CI enables it.

Typedefs

EnvLookup = String? Function(String name)

Reads an environment variable, returning null when it is not set.

SpinnerTimerFactory = SpinnerTimer Function(Duration interval, void onTick())

Callback used by SpinnerTimerFactory.