Terminal output that survives being piped into a file

/**
 * Whether we are talking to a human at a terminal.
 *
 * Two separate questions get conflated here, so keep them apart:
 *   isTTY. Is there a terminal on the other end at all?
 *   supportsColor, will it render ANSI, and did the user ask us not to?
 *
 * Chalk answers the second (including NO_COLOR and FORCE_COLOR). The first is
 * ours to check, and it is the one that decides whether a spinner may exist.
 */
export const isTTY = Boolean(process.stdout.isTTY && process.stderr.isTTY);

/** True only when it is a terminal AND we are allowed to draw. */
export const canAnimate = isTTY && process.env.CI !== 'true';

/**
 * Cheap, JSON-safe log lines. In CI these go to stdout because a build log with
 * no newlines is miserable to read.
 */
export const log = {
  /** The answer itself. Nothing decorative is ever written here. */
  out: (s) => process.stdout.write(s + '\n'),
  /** Progress, costs, warnings, banners. Safe to discard. */
  note: (s) => process.stderr.write(s + '\n'),
  /** Failures. Also surfaced in the exit code. */
  fail: (s) => process.stderr.write(s + '\n'),
};

import chalk from 'chalk';

// Chalk already respects NO_COLOR, FORCE_COLOR and TERM=dumb, so there is no
// configuration to do. What it deliberately does NOT do is disable colour
// because stdout is a pipe: FORCE_COLOR exists for tools that pipe into a pager.
// That is the right default for a library and the wrong default for a CLI that
// writes files, which is why we gate ourselves.

export const ui = {
  dim: (s) => (isTTY ? chalk.dim(s) : s),
  bold: (s) => (isTTY ? chalk.bold(s) : s),
  green: (s) => (isTTY ? chalk.green(s) : s),
  red: (s) => (isTTY ? chalk.red(s) : s),
  yellow: (s) => (isTTY ? chalk.yellow(s) : s),
  gray: (s) => (isTTY ? chalk.gray(s) : s),
  /** Status marks. The glyph, not the colour, carries the meaning. */
  pass: (s) => (isTTY ? chalk.green('✓') + ' ' + s : '[ok] ' + s),
  warn: (s) => (isTTY ? chalk.yellow('!') + ' ' + s : '[warn] ' + s),
  fail: (s) => (isTTY ? chalk.red('✗') + ' ' + s : '[fail] ' + s),
};

const COLOR = { pass: '\x1b[32m', warn: '\x1b[33m', fail: '\x1b[31m', skip: '\x1b[90m' };
const MARK = { pass: '✓', warn: '!', fail: '✗', skip: '·' };
const RESET = '\x1b[0m';

export function renderDoctor(report) {
  const lines = [];
  for (const c of report.checks) {
    lines.push(`${COLOR[c.level]}${MARK[c.level]}${RESET} ${c.title}, ${c.detail}`);
    if (c.hint && c.level !== 'pass') lines.push(`  ${chalk.gray(c.hint)}`);
  }
  return lines.join('\n');
}

5 passed · 1 warning(s) · 1 failed · 1 skipped

npm install figlet
node -e "import('figlet').then(f=>console.log(f.default.textSync('owl',{font:'Standard'}).toString()))"

  ____        _    
 / _ \       / /   
| | | | \ \ /\ / /   
| |_| |  \ V  V / 
 \___/ \_/\_/ /_/ 

import { existsSync } from 'node:fs';
import { join } from 'node:path';

const MARKER = join(process.env.HOME || '.', '.owl-splashed');

/**
 * Show the banner at most once per machine, never when piped, never in CI,
 * and never when the caller asked for machine-readable output.
 */
export function shouldSplash({ json, quiet }) {
  if (json || quiet) return false;
  if (process.env.CI) return false;
  if (!process.stdout.isTTY) return false;
  if (existsSync(MARKER)) return false;
  return true;
}

const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
const DELAY_MS = 400;   // show nothing at all before this

/**
 * @param {string} label   what it is doing
 * @param {number} delay   silence before the first frame
 * @returns {{ update(s: string): void; stop(): void }}
 */
export function spinner(label, delay = DELAY_MS) {
  if (!canAnimate) {
    // Non-interactive: one static line, no cursor tricks, no frames.
    return { update() {}, stop() {} };
  }
  let frame = 0;
  let timer = null;
  let current = label;

  const draw = () => {
    process.stderr.write(`\r\x1b[2K${chalk.gray(FRAMES[frame++ % FRAMES.length])} ${chalk.gray(current)}`);
  };

  timer = setTimeout(function tick() {
    draw();
    timer = setTimeout(tick, 80);
  }, delay);

  return {
    update(next) {
      current = next;
    },
    stop() {
      clearTimeout(timer);
      // Erase the line. Without this the last frame stays in your scrollback.
      process.stderr.write('\r\x1b[2K');
    },
  };
}

/**
 * Pad to the widest cell. Display width, not .length, the box-drawing and
 * unicode marks people use in file paths would otherwise skew every column.
 */
function width(s) {
  return [...String(s)].reduce((n, ch) => n + (/[\u1100-\u115F\u2E80-\uA4CF\uAC00-\uD7A3\uF900-\uFAFF\uFE30-\uFE6F\uFF00-\uFF60\uFFE0-\uFFE6]/.test(ch) ? 2 : 1), 0);
}

export function table(rows, { head } = {}) {
  const all = head ? [head, ...rows] : rows;
  const cols = Math.max(...all.map((r) => r.length));
  const pad = (s, n) => String(s) + ' '.repeat(Math.max(0, n - width(s)));

  const widths = Array.from({ length: cols }, (_, i) =>
    Math.max(...all.map((r) => width(r[i] ?? ''))),
  );
  const line = (cells) => cells.map((c, i) => pad(c ?? '', widths[i])).join('  ').trimEnd();

  return [
    head ? chalk.gray(line(head)) : null,
    head ? chalk.gray(widths.map((w) => '─'.repeat(w)).join('  ')) : null,
    ...rows.map(line),
  ].filter(Boolean).join('\n');
}

# 1. interactive: colour, alignment, no escape codes in the visible output
node bin/owl.js doctor

# 2. redirected: the file must contain no ESC characters and no spinner frames
node bin/owl.js ask "what is 2+2?" > out.txt
grep -c $'\x1b' out.txt      # must be 0
grep -c '[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏]' out.txt  # must be 0

# 3. CI: NO_COLOR is honoured, and nothing animates
NO_COLOR=1 CI=true node bin/owl.js doctor 2>&1 | cat -v | grep -c '\^['  # must be 0