[cscheid]

Fixes #1135 (braid: bd-be8ve52f).

Problem

q2 decided whether to emit ANSI color and OSC 8 hyperlinks in several places, and the places disagreed. Render diagnostics hard-coded both to on, so NO_COLOR=1 q2 render index.qmd 2>log wrote 162 SGR sequences and 2 OSC 8 links into the log. Three other paths had their own rules:

• the -v tracing logs honored NO_COLOR but colored even when redirected to a file;
• ParseError's Display baked styling into stored strings, so render aborts leaked escapes too (a broken _quarto.yml gave 62 SGR and 2 OSC 8);
• pampa used the always-on library default.

The triage and the full audit are in claude-notes/issue-reports/1135/triage.md. The plan, with an end-to-end record, is in claude-notes/plans/2026-11-11-terminal-output-style.md.

Change

One policy, resolved once. The new quarto_util::output_style module holds a pure resolve() and a OnceLock that is set on the main thread right after argument parsing. It decides each stream separately; the first matching rule wins:

1. --color=never|always (a new global flag on q2 and hub);
2. NO_COLOR set to a non-empty value turns color off;
3. CLICOLOR_FORCE or FORCE_COLOR (non-empty, not 0) turns color on;
4. CLICOLOR=0 turns color off;
5. otherwise color is on when the stream is a tty and TERM supports color, or CLICOLOR / CI is set.

This is anstream's precedence, so q2 agrees with clap's --help.

Hyperlinks have their own rule. They need color, a tty, and a terminal that supports-hyperlinks recognizes, or an explicit FORCE_HYPERLINK. Forcing color into a pipe never adds links. get() returns plain output when init never ran (libraries, tests, WASM).

Every sink reads the policy. That covers:

• render diagnostics and the counts clause;
• CLI diagnostics;
• create / add / use;
• the tracing layer (with_ansi);
• hub, pampa, qmd-syntax-helper and quarto-preview.

No styling baked into strings. ParseError::render_with(&TextRenderOptions) is new. render() and Display are now plain. Terminal sinks render with the resolved style:

• the abort paths;
• RenderAbort::user_message;
• main, which now wraps run() and prints a parse error through terminal_style::format_error_report. Every other error prints exactly as before.

String producers (WASM entry points, ts_record) now pass plain() explicitly.

Docs. New page: docs/tools/terminal-output.qmd.

Behavior changes for reviewers

• Fewer links. Terminals that supports-hyperlinks doesn't recognize no longer get OSC 8 links unless FORCE_HYPERLINK=1 is set. Examples are tmux and macOS Terminal.app. Before this change, links appeared wherever color did.
• Updated test. json_errors::ipynb_diagnostic_hyperlinks_real_notebook pinned "hyperlinks into a captured stderr". It now asks for them with FORCE_HYPERLINK=1.
• main's error output. A parse error that reaches main no longer prints a doubled Error: header or repeats itself under Caused by:.
• --help. q2 --help follows the environment variables but not --color, because clap renders help before our flag is parsed. The docs say so.

The upstream default (TextRenderOptions::default() is styled) is out of scope here. It is filed as posit-dev/quarto-error-reporting#12.

Tests (written first, seen failing)

• 20 resolver unit tests covering the precedence table.
• 13 binary-driven q2 tests (tests/integration/terminal_output_style.rs): diagnostics, tracing, --color, the force and hyperlink variables, and the Dispatch and Scripts abort paths. Each abort path has a pipe test, which failed before the change, and a --color=always guard, which passed before and still passes, so no terminal path lost color.
• 2 binary-driven pampa tests.
• Unit tests for ParseError::{Display, render_with} and format_error_report.

Verification

• Ran the q2 render ignores NO_COLOR and prints colour codes and hyperlinks in its diagnostics #1135 repro through the binary, writing to a file: 0 SGR / 0 OSC 8, with or without NO_COLOR.
• Simulated a terminal with script. The abort and diagnostic outputs keep their before-change SGR / OSC 8 counts (I compared counts, not bytes).
• cargo xtask verify --skip-rust-tests passes, including the hub-client WASM build and the JS/TS suites.
• cargo nextest run --workspace --no-fail-fast: 19355 of 19356 pass. The one failure is local-only (R/knitr rlang_error, bd-54odm3rz) and also fails on clean main.
• Clippy -D warnings passes on all touched crates. The Windows cross-clippy of quarto-util is clean. I did not cross-check the other crates for Windows; their changes contain no platform-specific code.

🤖 Generated with Claude Code

[posit-snyk-bot]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.