design-cli-outputDesign terminal output for a CLI tool with chalk colors, Unicode glyphs, multiple verbosity levels (human, verbose, quiet, JSON), and consistent voice rules. Covers color palette selection, status indicator design, reporter function architecture, ceremony/narrative output variants, and cross-terminal compatibility. Use when building a new CLI reporter modul…
Independent GitHub snapshot · Automated classification · Original documentation governs
Konsistente, mehrstufige Terminal-Ausgabe fuer ein Kommandozeilen-Tool entwerfen.
Chalk nutzen um ein benanntes Paletten-Objekt zu erstellen.
Chalk hinter einem No-Color-Fallback laden. Der Fallback muss fuer jede Aufruf-Form einstehen die die Palette nutzt, und das ist mehr als Strings durchzureichen:
// A factory returns a *function*; a direct style returns a string. Enumerate
// this list against the installed chalk, not from memory — chalk 6 added the
// three underline* variants, and a list that omits them is wrong for those names.
const FACTORIES = new Set(['ansi256', 'bgAnsi256', 'bgHex', 'bgRgb', 'hex',
'rgb', 'underlineAnsi256', 'underlineHex', 'underlineRgb']);
function makeChalkStub() {
return new Proxy((text) => text, {
get(target, prop) {
if (prop === 'then') return undefined; // must not be a thenable
if (prop === 'level') return 0; // no color support, truthfully
if (typeof prop === 'symbol') return Reflect.get(target, prop);
return FACTORIES.has(prop) ? () => makeChalkStub() : makeChalkStub();
},
});
}
let chalk;
try { chalk = (await import('chalk')).default; }
catch { chalk = makeChalkStub(); }
Vier Invarianten, von denen jede ein kuerzerer Stub falsch macht:
(text) => text, nicht {}. Verkettung
(chalk.bold.cyan('x')) braucht jeden Schritt sowohl indexierbar als auch
aufrufbar.new Proxy({}, { get: () => (s) => s })
erfuellt die direkten Styles und bricht die Factories: chalk.hex('#FF6B35')
ist dann der String '#FF6B35', und ihn aufzurufen wirft
TypeError: ... is not a function. Paletten werden beim Modul-Load gebaut, also
nimmt dieser Fallback das Tool zur Import-Zeit herunter — genau in der Situation
in der das Degradieren auf Klartext der Zweck war.then ist undefined. Ein Stub der jede Property mit einer Funktion
beantwortet laesst await chalk fuer immer haengen: die Runtime ruft .then
und wartet auf einen Callback den niemand aufruft. Node meldet
Detected unsettled top-level await und beendet mit 13.level ist eine Zahl. Capability-Gates lesen chalk.level >= 1; ein
truthy Stub oeffnet sie ohne Farb-Unterstuetzung dahinter.Die Palette aus dem Objekt bauen das diesen Import ueberlebt hat.
Standard-Palette (transaktionale Ausgabe):
// Status colors
const ok = chalk.green; // success
const fail = chalk.red; // errors
const warn = chalk.yellow; // warnings
const info = chalk.cyan; // identifiers, names
const dim = chalk.dim; // secondary info, paths
const bold = chalk.bold; // headers
Warme Palette (Zeremonie/narrative Ausgabe):
const C = {
flame: chalk.hex('#FF6B35'), // active elements, fire
amber: chalk.hex('#FFB347'), // arriving items, warm highlights
spark: chalk.hex('#FFF4E0'), // individual items (sparks/skills)
ember: chalk.hex('#8B4513'), // cold/dormant states
warm: chalk.hex('#D4A574'), // neutral warm text
dim: chalk.dim, // background, secondary
fail: chalk.red, // errors stay red (honest)
};
Paletten-Design-Regeln:
chalk.hex('#FF6B35'))Erwartet: Ein Paletten-Objekt mit benannten Eintraegen, und ein Fallback der ausgefuehrt und nicht bloss geschrieben wurde.
Bei Fehler: Den Fallback-Pfad direkt ausueben; die Palette ist der falsche Ort um zu entdecken dass er kaputt ist. Mit dem Stub im Scope:
console.assert(chalk.dim('x') === 'x'); // direct style
console.assert(chalk.hex('#fff')('x') === 'x'); // factory — the usual defect
console.assert(chalk.bold.cyan('x') === 'x'); // chain
console.assert(chalk.level === 0); // capability gate stays shut
await chalk; // must not hang
NO_COLOR=1 deckt das nicht ab. Es uebt ein funktionierendes chalk aus das
sich entscheidet keine Escapes zu senden; der Fallback uebt ein chalk aus das
nicht importiert werden konnte. Die zwei Pfade teilen keinen Code. Siehe
Erweiterte Beispiele
fuer den annotierten Produktions-Stub, eine Reproduktion des Defekts und eine
lauffaehige Version der obigen Pruefungen.
Unicode-Glyphen oder ASCII-Zeichen fuer Status-Kommunikation auswaehlen:
ASCII (maximale Kompatibilitaet):
+ created/installed (green)
- removed/deleted (red)
= skipped/unchanged (dim)
! error/warning (red)
Unicode (reicher, braucht UTF-8-Terminal):
✦ item/skill/practice (spark)
◉ active/burning state
◎ cooling/embers state
○ cold/dormant state
◌ available/not installed
✗ failed item
✓ success (use sparingly — not all terminals render it well)
Auswahlkriterien:
--ascii-Flag oder NO_COLOR-Detection anbietenErwartet: Ein Glyphen-Set das Status auf einen Blick kommuniziert ohne sich allein auf Farbe zu verlassen.
Bei Fehler: Wenn ein Glyph beim Testen als ? oder Box gerendert wird, durch das ASCII-Aequivalent ersetzen. Das +/-/=/!-Set funktioniert ueberall.
Jeder Befehl sollte vier Ausgabe-Stufen unterstuetzen:
| Stufe | Flag | Zielgruppe | Inhalt |
|---|---|---|---|
| Default | (keine) | Mensch am Terminal | Formatiert, gefaerbt, informativ |
| Verbose | --verbose oder --ceremonial | Mensch der Detail will | Per-Item-Aufschluesselung, Ankunfts-Sequenzen |
| Quiet | --quiet | Skripte, CI | Minimale Zeilen, Status-Icons, keine Dekoration |
| JSON | --json | Maschinen-Konsumenten | Strukturiert, parsebar, vollstaendig |
Implementations-Muster:
function output(data, options) {
if (options.json) {
console.log(JSON.stringify(data, null, 2));
return;
}
if (options.quiet) {
for (const item of data.items) {
const icon = item.ok ? '+' : '!';
console.log(`${icon} ${item.id}`);
}
return;
}
// Default (or verbose) human output
printFormatted(data, { verbose: options.verbose });
}
JSON-Ausgabe-Regeln:
Erwartet: Vier klare Ausgabe-Stufen mit konsistentem Verhalten ueber Befehle.
Bei Fehler: Wenn der Verbose-Modus zu laut ist, ihn opt-in machen (--ceremonial) statt einer abgestuften Verbosity-Stufe.
Den Ton und Stil definieren dem alle Ausgabe-Funktionen folgen. Dies verhindert Inkonsistenz ueber Befehle.
Beispiel-Stimmregeln (vom campfire-Reporter):
Stimmregeln fuer Standard- (Nicht-Zeremonie) Ausgabe:
Erwartet: Ein geschriebener Satz von 3-7 Stimmregeln denen Ausgabe-Funktionen folgen muessen.
Bei Fehler: Wenn Regeln willkuerlich erscheinen, sie testen: dieselbe Ausgabe mit und ohne jede Regel schreiben. Wenn das Entfernen einer Regel die Ausgabe-Qualitaet nicht aendert, wird die Regel nicht gebraucht.
Ausgabe in ein Reporter-Modul mit fokussierten Funktionen organisieren:
// reporter.js — standard output
export function printResults(results) { ... }
export function printItemTable(items) { ... }
export function printDetections(detections) { ... }
export function printAudit(auditResults) { ... }
export function printDryRun() { ... }
export function warn(msg) { ... }
export function error(msg) { ... }
export { chalk };
Jede Funktion folgt derselben Struktur:
Fuer Zeremonie-Ausgabe ein separates Modul erstellen:
// campfire-reporter.js — warm narrative output
export function printArrival({ teamId, agents, results, ceremonial }) { ... }
export function printScatter({ teamId, agents, results }) { ... }
export function printTend(fires) { ... }
export function printCampfireList({ teams, state, reg }) { ... }
export function printFireSummary({ team, fireData, reg }) { ... }
export function printJson(data) { ... }
Erwartet: Reporter-Funktionen die unabhaengig nutzbar sind — jede behandelt ihre eigene Formatierung ohne von Caller-State abzuhaengen.
Bei Fehler: Wenn Funktionen ueber ~50 Zeilen wachsen, Helfer extrahieren. Eine Reporter-Funktion sollte einfach in Isolation reviewbar sein.
Verifizieren dass Ausgabe in unterschiedlichen Kontexten korrekt rendert:
# With colors (interactive terminal)
node cli/index.js list --domains
# Without colors (piped)
node cli/index.js list --domains | cat
# With NO_COLOR environment variable
NO_COLOR=1 node cli/index.js list --domains
# JSON mode (parseable)
node cli/index.js campfire --json | jq .
# In CI (typically no TTY)
CI=true node cli/index.js audit
# The no-color fallback. A failed import cannot be provoked with an env var, so
# assert on the stub itself in the suite rather than reaching it through the CLI.
# Pass a glob, not a directory: `node --test <dir>` stopped expanding at Node 22.
node --test 'cli/test/*.test.js'
Pruefen auf:
jq . pipen zur Verifikation)Erwartet: Ausgabe ist in allen sechs Kontexten korrekt.
Bei Fehler: Wenn ANSI-Codes lecken, sicherstellen dass chalk NO_COLOR
respektiert. Wenn Unicode bricht, einen ASCII-Fallback-Modus bereitstellen. Zu
beachten: eine gruene Suite sagt in keine Richtung etwas ueber Farbe aus —
Test-Runner pipen stdout, was chalk.level auf 0 setzt, also sind gefaerbte und
ungefaerbte Ausgabe byte-identisch und die Assertions halten mit vollstaendig
kaputter Farbe. Zu beweisen dass Farbe funktioniert braucht FORCE_COLOR=3 und
eine Assertion auf einer Escape-Sequenz.
level === 0 und await alle geprueftjq parsebarnew Proxy({}, { get: () => (s) => s }) liest sich vollstaendig und deckt chalk.dim und chalk.red tatsaechlich ab, aber jede Factory gibt dann einen String zurueck den der Caller sofort aufzurufen versucht. Weil Paletten beim Modul-Load gebaut werden, landet der TypeError zur Import-Zeit — der Fallback versagt am haertesten in dem einen Fall fuer den er existiert. Schritt 1 listet die vier Invarianten die ein Stub erfuellen muss.--json-Modus nur gueltiges JSON ausgeben. Eine einzelne verirrte Zeile (wie "DRY RUN") bricht JSON-Parser. Wenn der Befehl beides zeigen muss, sie klar trennen oder den menschlichen Text im JSON-Modus unterdruecken.Math.max(...items.map(i => i.id.length)) nutzen um Padding dynamisch zu berechnen.+, OK, ERR).--quiet-Modus fuegt sie Rauschen hinzu. Zeremonie-Ausgabe hinter explizite Flags sperren.scaffold-cli-command — die Befehle die diese Ausgabe nutzentest-cli-application — Tests dass Ausgabe Erwartungen entsprichtbuild-cli-plugin — Plugins berichten Ergebnisse durch dieses Ausgabe-System