voxpelli.com
A flat-YAML task tracker that is just files. No daemon, no database, no git hooks.
diarie.dev
issue-tracker
cli
nodejs
agent-friendly
1/**
2 * format.js — output.
3 *
4 * Deliberately NOT `markdown-or-chalk`, which the node-cli-template uses. Measured:
5 * it costs 83 transitive packages and ~10 MB, and drags in `yargs@16` via
6 * `cli-highlight` — the very library `peowly` was chosen to avoid. Almost all of
7 * that weight is a markdown renderer for syntax-highlighted code fences. diarie
8 * emits a task list, some counts, and validation errors. It renders no code.
9 *
10 * If diarie ever grows output worth rendering as markdown, revisit — the finding is
11 * logged in UPSTREAM-markdown-or-chalk.md, not buried here.
12 *
13 * The stdout/stderr split is load-bearing, not stylistic:
14 *
15 * stdout = THE ANSWER (parsed by hooks, skills, `jq`)
16 * stderr = ASIDES (advisory; ten call sites pipe it to /dev/null)
17 *
18 * The tracker's absent-store bug survived for months precisely because it put its
19 * only real signal on stderr. Anything a caller must not miss goes to stdout and is
20 * reflected in the exit code. Nothing important is ever whispered.
21 */
22
23import { stderr, stdout } from 'node:process';
24
25/**
26 * Print the answer as JSON. Two-space indent — these get read by humans in
27 * terminals at least as often as by `jq`.
28 *
29 * @param {unknown} value
30 * @returns {void}
31 */
32export function jsonOut (value) {
33 stdout.write(JSON.stringify(value, undefined, 2) + '\n');
34}
35
36/**
37 * Print the answer as text.
38 *
39 * @param {string} text
40 * @returns {void}
41 */
42export function textOut (text) {
43 stdout.write(text.endsWith('\n') ? text : text + '\n');
44}
45
46/**
47 * An aside — advisory only. NEVER the sole carrier of something a caller must act
48 * on; see the header. If you find yourself wanting to warn() about a condition the
49 * caller must handle, it belongs on stdout with a non-zero exit instead.
50 *
51 * @param {string} message
52 * @returns {void}
53 */
54export function warn (message) {
55 stderr.write(`diarie: ${message}\n`);
56}