fix: make piped output human-readable instead of raw CommonMark

Two problems are fixed:

1. FORCE_COLOR leaking ANSI to pipes: When FORCE_COLOR=1 is set (common
   in VS Code terminals), ANSI escape codes leaked through to less/cat
   because isPlainOutput() treated FORCE_COLOR as higher priority than
   TTY detection. Now FORCE_COLOR only applies when stdout IS a TTY.
   Users who truly want color in pipes can use SENTRY_PLAIN_OUTPUT=0.

2. Plain mode outputs raw CommonMark: When piped, the CLI produced raw
   markdown syntax (| --- |, **bold**, [link](url), `code`) which is
   unreadable in a pager. Now plain mode:
   - renderMarkdown() parses and renders to structured plain text
     (headings, aligned tables, blockquote indentation) then strips ANSI
   - formatTable() uses renderTextTable() with box-drawing borders
     instead of buildMarkdownTable() with raw CommonMark syntax
   - renderInlineMarkdown() strips markdown syntax via stripMarkdownInline()
   - terminalLink() returns plain text (no OSC 8 sequences) when piped
   - divider() and footer/hint text use plainSafeMuted() to avoid ANSI

Architecture: isPlainOutput() extracted to plain-detect.ts to avoid
circular dependency between markdown.ts and colors.ts. Re-exported from
markdown.ts for backward compatibility.

Author: BYK

AGENTS.md

@@ -283,7 +283,8 @@ All non-trivial human output must use the markdown rendering pipeline:
 - Build markdown strings with helpers: `mdKvTable()`, `colorTag()`, `escapeMarkdownCell()`, `renderMarkdown()`
 - **NEVER** use raw `muted()` / chalk in output strings — use `colorTag("muted", text)` inside markdown
 - Tree-structured output (box-drawing characters) that can't go through `renderMarkdown()` should use the `plainSafeMuted` pattern: `isPlainOutput() ? text : muted(text)`
-- `isPlainOutput()` precedence: `SENTRY_PLAIN_OUTPUT` > `NO_COLOR` > `FORCE_COLOR` > `!isTTY`
+- `isPlainOutput()` precedence: `SENTRY_PLAIN_OUTPUT` > `NO_COLOR` > `FORCE_COLOR` (TTY only) > `!isTTY`
+- `isPlainOutput()` lives in `src/lib/formatters/plain-detect.ts` (re-exported from `markdown.ts` for compat)
 
 Reference: `formatters/trace.ts` (`formatAncestorChain`), `formatters/human.ts` (`plainSafeMuted`)
 

biome.jsonc

@@ -62,7 +62,12 @@
       // db/index.ts exports db connection utilities - not a barrel file but triggers the rule
       // api-client.ts is a barrel that re-exports from src/lib/api/ domain modules
       // to preserve the existing import path for all consumers
-      "includes": ["src/lib/db/index.ts", "src/lib/api-client.ts"],
+      // markdown.ts re-exports isPlainOutput from plain-detect.ts for backward compat
+      "includes": [
+        "src/lib/db/index.ts",
+        "src/lib/api-client.ts",
+        "src/lib/formatters/markdown.ts"
+      ],
       "linter": {
         "rules": {
           "performance": {

src/lib/formatters/colors.ts

@@ -6,6 +6,7 @@
 
 import chalk from "chalk";
 import type { IssueLevel, IssueStatus } from "../../types/index.js";
+import { isPlainOutput } from "./plain-detect.js";
 
 // Color Palette (Full Sentinel palette)
 
@@ -57,6 +58,9 @@ export const boldUnderline = (text: string): string =>
  * @returns Text wrapped in OSC 8 hyperlink escape sequences
  */
 export function terminalLink(text: string, url: string = text): string {
+  if (isPlainOutput()) {
+    return text;
+  }
   // OSC 8 ; params ; URI BEL  text  OSC 8 ; ; BEL
   // \x1b] opens the OSC sequence; \x07 (BEL) terminates it.
   // Using BEL instead of ST (\x1b\\) for broad terminal compatibility.

src/lib/formatters/markdown.ts

@@ -13,76 +13,21 @@
  * Pre-rendered ANSI escape codes embedded in markdown source are preserved
  * — `string-width` correctly treats them as zero-width.
  *
- * ## Output mode resolution (highest → lowest priority)
+ * ## Output mode resolution
  *
- * 1. `SENTRY_PLAIN_OUTPUT=1` → plain (raw CommonMark)
- * 2. `SENTRY_PLAIN_OUTPUT=0` → rendered (force rich, even when piped)
- * 3. `NO_COLOR=1` (or any truthy value) → plain
- * 4. `NO_COLOR=0` (or any falsy value) → rendered
- * 5. `!process.stdout.isTTY` → plain
- * 6. default (TTY, no overrides) → rendered
+ * See {@link isPlainOutput} in `plain-detect.ts` for the full priority chain.
  */
 
 import chalk from "chalk";
 import { highlight as cliHighlight } from "cli-highlight";
 import { marked, type Token, type Tokens } from "marked";
 import stringWidth from "string-width";
 import { COLORS, muted, terminalLink } from "./colors.js";
+import { isPlainOutput, stripAnsi } from "./plain-detect.js";
 import { type Alignment, renderTextTable } from "./text-table.js";
 
-// ──────────────────────────── Environment ─────────────────────────────
-
-/**
- * Returns true if an env var value should be treated as "truthy" for
- * purposes of enabling/disabling output modes.
- *
- * Falsy values: `"0"`, `"false"`, `""` (case-insensitive).
- * Everything else (e.g. `"1"`, `"true"`, `"yes"`) is truthy.
- */
-function isTruthyEnv(val: string): boolean {
-  const normalized = val.toLowerCase().trim();
-  return normalized !== "0" && normalized !== "false" && normalized !== "";
-}
-
-/**
- * Determines whether output should be plain CommonMark markdown (no ANSI).
- *
- * Evaluated fresh on each call so tests can flip env vars between assertions
- * and changes to `process.stdout.isTTY` are picked up immediately.
- *
- * Priority (highest first):
- * 1. `SENTRY_PLAIN_OUTPUT` — explicit project-specific override (custom
- *    semantics: `"0"` / `"false"` / `""` force color on)
- * 2. `NO_COLOR` — follows the no-color.org spec: any **non-empty** value
- *    disables color, regardless of its content (including `"0"` / `"false"`)
- * 3. `FORCE_COLOR` — follows chalk/supports-color convention: `"0"` forces
- *    color off (plain), any other non-empty value (e.g. `"1"`) forces color on.
- * 4. `process.stdout.isTTY` — auto-detect interactive terminal
- */
-export function isPlainOutput(): boolean {
-  const plain = process.env.SENTRY_PLAIN_OUTPUT;
-  if (plain !== undefined) {
-    return isTruthyEnv(plain);
-  }
-
-  // no-color.org spec: presence of a non-empty value disables color.
-  // Unlike SENTRY_PLAIN_OUTPUT, "0" and "false" still mean "disable color".
-  const noColor = process.env.NO_COLOR;
-  if (noColor !== undefined) {
-    return noColor !== "";
-  }
-
-  // FORCE_COLOR follows the chalk/supports-color convention:
-  //   "0" → force disable color (plain output)
-  //   "1"/"2"/"3" or any other non-empty, non-"0" → force enable color
-  // Checked after NO_COLOR so that NO_COLOR always wins if both are set.
-  const forceColor = process.env.FORCE_COLOR;
-  if (forceColor !== undefined && forceColor !== "") {
-    return forceColor === "0";
-  }
-
-  return !process.stdout.isTTY;
-}
+// Re-export isPlainOutput so existing importers don't break
+export { isPlainOutput } from "./plain-detect.js";
 
 // ──────────────────────────── Escape helpers ──────────────────────────
 
@@ -150,7 +95,7 @@ export function mdTableHeader(cols: readonly string[]): string {
  */
 export function mdRow(cells: readonly string[]): string {
   if (isPlainOutput()) {
-    return `| ${cells.map(stripColorTags).join(" | ")} |\n`;
+    return `| ${cells.map(stripMarkdownInline).join(" | ")} |\n`;
   }
   const out = cells.map((c) =>
     renderInline(marked.lexer(c).flatMap(flattenInline)).replace(
@@ -191,10 +136,11 @@ export function mdKvTable(
 }
 
 /**
- * Render a muted horizontal rule.
+ * Render a horizontal rule. Muted (dimmed) in TTY mode, plain in pipes.
  */
 export function divider(width = 80): string {
-  return muted("\u2500".repeat(width));
+  const line = "\u2500".repeat(width);
+  return isPlainOutput() ? line : muted(line);
 }
 
 // ──────────────────────── Inline token rendering ─────────────────────
@@ -265,6 +211,25 @@ export function stripColorTags(text: string): string {
   return result;
 }
 
+/**
+ * Strip inline markdown syntax to produce plain text.
+ *
+ * Removes bold/italic markers, link syntax (keeps display text), code
+ * backticks, and color tags. Used for plain-mode output that should be
+ * human-readable without any markdown artifacts.
+ */
+export function stripMarkdownInline(md: string): string {
+  let text = stripColorTags(md);
+  // Links: [text](url) → text
+  text = text.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1");
+  // Bold/italic: **text** or __text__ → text, *text* or _text_ → text
+  text = text.replace(/\*{1,2}([^*]+)\*{1,2}/g, "$1");
+  text = text.replace(/_{1,2}([^_]+)_{1,2}/g, "$1");
+  // Code spans: `text` → text
+  text = text.replace(/`([^`]+)`/g, "$1");
+  return text;
+}
+
 /**
  * Render an inline HTML token as a color-tagged string.
  *
@@ -554,9 +519,6 @@ function renderList(list: Tokens.List, depth = 0): string {
  *
  * Converts marked's `Tokens.Table` into headers + rows + alignments and
  * delegates to `renderTextTable()` for column fitting and box drawing.
- *
- * Empty header rows (e.g. from {@link mdKvTable} without a heading) are
- * auto-hidden by `renderTextTable` — no explicit detection needed here.
  */
 function renderTableToken(table: Tokens.Table): string {
   const headers = table.header.map((cell) => renderInline(cell.tokens));
@@ -580,37 +542,42 @@ function renderTableToken(table: Tokens.Table): string {
 // ──────────────────────── Public API ─────────────────────────────────
 
 /**
- * Render a full markdown document as styled terminal output, or return
- * the raw CommonMark string when in plain mode.
+ * Render a full markdown document as styled terminal output.
+ *
+ * In TTY mode: uses `marked.lexer()` to tokenize and a custom block/inline
+ * renderer for ANSI output. Tables are rendered with Unicode box-drawing
+ * borders via the text-table module.
  *
- * Uses `marked.lexer()` to tokenize and a custom block/inline renderer
- * for ANSI output. Tables are rendered with Unicode box-drawing borders
- * via the text-table module.
+ * In plain mode: parses and renders the same way (preserving structural
+ * formatting — headings, aligned tables, blockquote indentation, lists),
+ * then strips ANSI codes. This produces human-readable output rather than
+ * raw CommonMark source.
  *
  * @param md - Markdown source text
- * @returns Styled terminal string (TTY) or raw CommonMark (non-TTY / plain mode)
+ * @returns Styled terminal string (TTY) or clean plain text (non-TTY / plain mode)
  */
 export function renderMarkdown(md: string): string {
   if (isPlainOutput()) {
-    // Strip color tags so <red>text</red> doesn't leak as literal markup in
-    // piped / CI / redirected output (documented "plain mode" contract).
-    return stripColorTags(md).trimEnd();
+    // Parse and render to get structural formatting (headings, tables, lists),
+    // then strip ANSI codes. This produces human-readable output with aligned
+    // tables and proper heading emphasis, without ANSI escape sequences.
+    const tokens = marked.lexer(md);
+    return stripAnsi(renderBlocks(tokens)).trimEnd();
   }
   const tokens = marked.lexer(md);
   return renderBlocks(tokens).trimEnd();
 }
 
 /**
  * Render inline markdown (bold, code spans, emphasis, links) as styled
- * terminal output, or return the raw markdown string when in plain mode.
+ * terminal output, or return plain text when in plain mode.
  *
  * @param md - Inline markdown text
- * @returns Styled string (TTY) or raw markdown text (non-TTY / plain mode)
+ * @returns Styled string (TTY) or plain text with markdown syntax stripped (non-TTY / plain mode)
  */
 export function renderInlineMarkdown(md: string): string {
   if (isPlainOutput()) {
-    // Strip color tags for the same reason as renderMarkdown.
-    return stripColorTags(md);
+    return stripMarkdownInline(md);
   }
   const tokens = marked.lexer(md);
   return renderInline(tokens.flatMap(flattenInline));

src/lib/formatters/output.ts

@@ -29,6 +29,7 @@
 import type { Writer } from "../../types/index.js";
 import { muted } from "./colors.js";
 import { formatJson, writeJson } from "./json.js";
+import { isPlainOutput } from "./plain-detect.js";
 
 // ---------------------------------------------------------------------------
 // Shared option types
@@ -326,17 +327,22 @@ export function writeOutput<T>(
   stdout.write(`${text}\n`);
 
   if (options.hint) {
-    stdout.write(`\n${muted(options.hint)}\n`);
+    stdout.write(`\n${plainSafeMuted(options.hint)}\n`);
   }
 
   if (options.footer) {
     writeFooter(stdout, options.footer);
   }
 }
 
-/** Format footer text (muted, with surrounding newlines). */
+/** Apply muted styling only in TTY mode; return plain text when piped. */
+function plainSafeMuted(text: string): string {
+  return isPlainOutput() ? text : muted(text);
+}
+
+/** Format footer text (muted in TTY, plain when piped, with surrounding newlines). */
 export function formatFooter(text: string): string {
-  return `\n${muted(text)}\n`;
+  return `\n${plainSafeMuted(text)}\n`;
 }
 
 /**

src/lib/formatters/plain-detect.ts

@@ -0,0 +1,87 @@
+/**
+ * Plain-output detection and ANSI stripping utilities.
+ *
+ * Extracted to its own module to avoid circular dependencies between
+ * `markdown.ts` (which imports from `colors.ts`) and `colors.ts`
+ * (which needs `isPlainOutput()` to gate terminal hyperlinks).
+ *
+ * ## Output mode resolution (highest → lowest priority)
+ *
+ * 1. `SENTRY_PLAIN_OUTPUT=1` → plain
+ * 2. `SENTRY_PLAIN_OUTPUT=0` → rendered (force rich, even when piped)
+ * 3. `NO_COLOR` (any non-empty value) → plain
+ * 4. `FORCE_COLOR=0` → plain (only when stdout is a TTY)
+ * 5. `FORCE_COLOR=1` on a TTY → rendered
+ * 6. `!process.stdout.isTTY` → plain
+ * 7. default (TTY, no overrides) → rendered
+ */
+
+/**
+ * Returns true if an env var value should be treated as "truthy" for
+ * purposes of enabling/disabling output modes.
+ *
+ * Falsy values: `"0"`, `"false"`, `""` (case-insensitive).
+ * Everything else (e.g. `"1"`, `"true"`, `"yes"`) is truthy.
+ */
+function isTruthyEnv(val: string): boolean {
+  const normalized = val.toLowerCase().trim();
+  return normalized !== "0" && normalized !== "false" && normalized !== "";
+}
+
+/**
+ * Determines whether output should be plain (no ANSI codes, no raw
+ * markdown syntax).
+ *
+ * Evaluated fresh on each call so tests can flip env vars between assertions
+ * and changes to `process.stdout.isTTY` are picked up immediately.
+ *
+ * Priority (highest first):
+ * 1. `SENTRY_PLAIN_OUTPUT` — explicit project-specific override (custom
+ *    semantics: `"0"` / `"false"` / `""` force color on)
+ * 2. `NO_COLOR` — follows the no-color.org spec: any **non-empty** value
+ *    disables color, regardless of its content (including `"0"` / `"false"`)
+ * 3. `FORCE_COLOR` — follows chalk/supports-color convention, but only
+ *    applies to interactive terminals. When stdout is piped, FORCE_COLOR
+ *    is ignored so that `cmd | less` always produces clean output.
+ *    Users who truly want color in pipes can use `SENTRY_PLAIN_OUTPUT=0`.
+ * 4. `process.stdout.isTTY` — auto-detect interactive terminal
+ */
+export function isPlainOutput(): boolean {
+  const plain = process.env.SENTRY_PLAIN_OUTPUT;
+  if (plain !== undefined) {
+    return isTruthyEnv(plain);
+  }
+
+  // no-color.org spec: presence of a non-empty value disables color.
+  // Unlike SENTRY_PLAIN_OUTPUT, "0" and "false" still mean "disable color".
+  const noColor = process.env.NO_COLOR;
+  if (noColor !== undefined) {
+    return noColor !== "";
+  }
+
+  // FORCE_COLOR only applies to interactive terminals. When stdout is
+  // piped/redirected, FORCE_COLOR is ignored so that `cmd | less` always
+  // produces clean output without ANSI codes.
+  const forceColor = process.env.FORCE_COLOR;
+  if (process.stdout.isTTY && forceColor !== undefined && forceColor !== "") {
+    return forceColor === "0";
+  }
+
+  return !process.stdout.isTTY;
+}
+
+/**
+ * Strip ANSI escape sequences from a string.
+ *
+ * Handles SGR codes (`\x1b[...m`) and OSC 8 terminal hyperlink sequences
+ * (`\x1b]8;;url\x07text\x1b]8;;\x07`).
+ */
+export function stripAnsi(text: string): string {
+  return (
+    text
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape detection requires matching \x1b and \x07
+      .replace(/\x1b\[[0-9;]*m/g, "")
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: OSC 8 hyperlink sequences use \x1b and \x07
+      .replace(/\x1b\]8;;[^\x07]*\x07/g, "")
+  );
+}