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(); }
四不變式，簡退各誤其一：
(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 等。+/-/=/! 集處處可。
每命令當支四輸出級：
| Level | Flag | Audience | Content |
|---|---|---|---|
| Default | (none) | Human at terminal | Formatted, colored, informative |
| Verbose | --verbose or --ceremonial | Human wanting detail | Per-item breakdown, arrival sequences |
| Quiet | --quiet | Scripts, CI | Minimal lines, status icons, no decoration |
| JSON | --json | Machine consumers | Structured, parseable, complete |
實現模式：
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 輸出規：
得： 四清晰輸出級跨命令行為一致。
敗： verbose 過噪→改為選入（--ceremonial）而非分級冗繁。
定諸輸出函遵之調+風。防跨命令不一致。
調規例（由 campfire 報告者）：
標（非儀式）輸出調規：
得： 書 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-commandtest-cli-applicationbuild-cli-plugin