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
為命令行具設一致之多層終端輸出。
以 chalk 建名板物。
載 chalk 於無色退路之後。 退路須代板所用之諸呼形，非唯傳字符串而已：
// 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(); }
四恒則，短樁各失其一：
Proxy 之標的可呼 — (text) => text，非 {}。連鎖（chalk.bold.cyan('x')）須每節皆可索且可呼。new Proxy({}, { get: () => (s) => s }) 足直式而破廠函：chalk.hex('#FF6B35') 遂為字符串 '#FF6B35'，呼之則擲 TypeError: ... is not a function。板建於模載之時，故此退路於入模之際即傾其具——正當以純文本降格為旨之境。then 為 undefined。 若樁以函答諸屬，則 await chalk 永懸：運行時呼 .then 而候無人施之回調。Node 報 Detected unsettled top-level await 而退 13。level 為數。 能力關讀 chalk.level >= 1；真值之樁啟之，而其後無色可用。以歷此入而存者建板。
標板（交易輸出）：
// 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
溫板（儀式/敘述輸出）：
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)
};
板設之則：
chalk.hex('#FF6B35')）得： 板物附名項，且其退路已執，非徒書之。
敗則： 直試退路之途；板非發其壞之所。樁在域中則：
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 不覆此。彼試可用之 chalk 而擇不出逸碼；退路試入模已敗之 chalk。二途無共碼。全註之產樁、疵之重現、及上諸察之可執本，見
Extended Examples。
擇 Unicode 字符或 ASCII 字為狀通：
ASCII（最大兼容）：
+ created/installed (green)
- removed/deleted (red)
= skipped/unchanged (dim)
! error/warning (red)
Unicode（豐，需 UTF-8 終端）：
✦ 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)
擇之則：
--ascii 旗或 NO_COLOR 察二者皆供得： 字符集，一目可通狀而不唯賴色。
敗則： 若測中字符渲為 ? 或方塊，替以 ASCII 等。+/-/=/! 集處處可。
各命令宜支四輸出級：
| 級 | 旗 | 受眾 | 內容 |
|---|---|---|---|
| 默 | （無） | 終端之人 | 格式、著色、資訊 |
| 詳 | --verbose 或 --ceremonial | 欲詳之人 | 逐項細、至序 |
| 靜 | --quiet | 腳本、CI | 最少行、狀圖、無飾 |
| JSON | --json | 機消費者 | 結構、可解、全 |
實模：
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 輸出之則：
得： 四清輸出級，跨命令行為一致。
敗則： 若詳模過噪，設為自選（--ceremonial）而非漸進級。
定諸輸出函從之語調式。防跨命令不一致。
語則例（由營火報告）：
標（非儀式）輸出之語則：
得： 書 3-7 語則，諸輸出函宜從。
敗則： 若則似妄，驗之：書同輸出有無各則。若除則不變質，則非需。
組輸出入報告模，附聚能：
// 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 };
各函從同結構：
儀式輸出建獨模：
// 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) { ... }
得： 報告函獨可用——各理自格式無賴呼狀。
敗則： 若函長於約 50 行，抽助者。報告函宜易獨察。
驗輸出於異脈正渲：
# 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'
察：
jq . 驗）得： 六境輸出皆正。
敗則： 若 ANSI 漏，確 chalk 守 NO_COLOR。若 Unicode 壞，供 ASCII 退模。又須知綠試集於色無所證：試行者管 stdout，chalk.level 遂為 0，著色與未著色之輸出逐字節同，故色全壞而諸斷言猶立。證色可用須 FORCE_COLOR=3 及對逸碼之斷言。
level === 0、await 皆察jq 可解new Proxy({}, { get: () => (s) => s }) 讀似完備，且誠覆 chalk.dim 與 chalk.red，然諸廠函遂返字符串，而呼者即刻呼之。板建於模載，故 TypeError 落於入模之時——退路正於其所以存之一境敗之最劇。第一步列樁須足之四恒則。--json 模唯出有效 JSON。一孤行（如「DRY RUN」）破 JSON 解。若命令宜示二者，明分或於 JSON 模抑人文本。Math.max(...items.map(i => i.id.length)) 動算墊。+、OK、ERR）。--quiet 模，添噪。儀式輸出置明旗後。scaffold-cli-command — 用此輸出之命令test-cli-application — 測輸出合期build-cli-plugin — 插件經此輸出系報結