feat(formatters): add plain output mode with isTTY detection and env var overrides

Gate all markdown rendering behind isPlainOutput(): skip marked.parse() and
return raw CommonMark when stdout is not a TTY. Override with env vars:
- SENTRY_PLAIN_OUTPUT=1/0 — explicit project-specific control (highest priority)
- NO_COLOR=1/0 — widely-supported standard (secondary)
- process.stdout.isTTY — auto-detect (fallback)

Both env vars treat '0', 'false', '' as falsy; everything else as truthy
(case-insensitive). SENTRY_PLAIN_OUTPUT takes precedence over NO_COLOR.

Add renderInlineMarkdown() using marked.parseInline() for inline-only
rendering of individual cell values without block wrapping.

Migrate streaming formatters to dual-mode output:
- formatLogRow / formatLogsHeader: plain emits markdown table rows/header
- formatTraceRow / formatTracesHeader: same

This means piping to a file produces valid CommonMark; live TTY sessions
get the existing ANSI-rendered output unchanged.

Author: BYK

src/lib/formatters/log.ts

@@ -7,7 +7,12 @@
 import type { DetailedSentryLog, SentryLog } from "../../types/index.js";
 import { buildTraceUrl } from "../sentry-urls.js";
 import { cyan, muted, red, yellow } from "./colors.js";
-import { escapeMarkdownCell, renderMarkdown } from "./markdown.js";
+import {
+  escapeMarkdownCell,
+  isPlainOutput,
+  renderInlineMarkdown,
+  renderMarkdown,
+} from "./markdown.js";
 
 /** Color functions for log severity levels */
 const SEVERITY_COLORS: Record<string, (text: string) => string> = {
@@ -55,27 +60,45 @@ function formatTimestamp(timestamp: string): string {
 /**
  * Format a single log entry for human-readable output.
  *
- * Format: "TIMESTAMP  SEVERITY  MESSAGE [trace_id]"
- * Example: "2024-01-30 14:32:15  ERROR    Failed to connect [abc12345]"
+ * In plain mode (non-TTY / `SENTRY_PLAIN_OUTPUT=1`): emits a markdown table
+ * row so streamed output composes into a valid CommonMark document.
+ * In rendered mode (TTY): emits padded ANSI-colored text for live display.
  *
  * @param log - The log entry to format
  * @returns Formatted log line with newline
  */
 export function formatLogRow(log: SentryLog): string {
+  if (isPlainOutput()) {
+    const timestamp = formatTimestamp(log.timestamp);
+    const severity = renderInlineMarkdown(
+      `**${(log.severity ?? "info").toUpperCase()}**`
+    );
+    const message = escapeMarkdownCell(log.message ?? "");
+    const trace = log.trace
+      ? ` ${renderInlineMarkdown(`\`[${log.trace.slice(0, 8)}]\``)}`
+      : "";
+    return `| ${timestamp} | ${severity} | ${message}${trace} |\n`;
+  }
+
   const timestamp = formatTimestamp(log.timestamp);
   const severity = formatSeverity(log.severity);
   const message = log.message ?? "";
   const trace = log.trace ? muted(` [${log.trace.slice(0, 8)}]`) : "";
-
   return `${timestamp}  ${severity}  ${message}${trace}\n`;
 }
 
 /**
  * Format column header for logs list (used in streaming/follow mode).
  *
- * @returns Header line with column titles and separator
+ * In plain mode: emits a markdown table header + separator row.
+ * In rendered mode: emits an ANSI-muted text header with a rule separator.
+ *
+ * @returns Header string (includes trailing newline)
  */
 export function formatLogsHeader(): string {
+  if (isPlainOutput()) {
+    return "| Timestamp | Level | Message |\n| --- | --- | --- |\n";
+  }
   const header = muted("TIMESTAMP            LEVEL    MESSAGE");
   return `${header}\n${muted("─".repeat(80))}\n`;
 }

src/lib/formatters/markdown.ts

@@ -2,12 +2,22 @@
  * Markdown-to-Terminal Renderer
  *
  * Central utility for rendering markdown content as styled terminal output
- * using `marked` + `marked-terminal`. Provides a single `renderMarkdown()`
- * function that all formatters can use for rich text output.
+ * using `marked` + `marked-terminal`. Provides `renderMarkdown()` and
+ * `renderInlineMarkdown()` for rich text output, with automatic plain-mode
+ * fallback when stdout is not a TTY or the user has opted out of rich output.
  *
  * Pre-rendered ANSI escape codes embedded in markdown source (e.g. inside
  * table cells) survive the pipeline — `cli-table3` computes column widths
  * via `string-width`, which correctly treats ANSI codes as zero-width.
+ *
+ * ## Output mode resolution (highest → lowest priority)
+ *
+ * 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
  */
 
 import chalk from "chalk";
@@ -67,6 +77,43 @@ marked.use(
   })
 );
 
+/**
+ * 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
+ * 2. `NO_COLOR` — widely-supported standard for disabling styled output
+ * 3. `process.stdout.isTTY` — auto-detect interactive terminal
+ */
+export function isPlainOutput(): boolean {
+  const plain = process.env.SENTRY_PLAIN_OUTPUT;
+  if (plain !== undefined) {
+    return isTruthyEnv(plain);
+  }
+
+  const noColor = process.env.NO_COLOR;
+  if (noColor !== undefined) {
+    return isTruthyEnv(noColor);
+  }
+
+  return !process.stdout.isTTY;
+}
+
 /**
  * Escape a string for safe use inside a markdown table cell.
  *
@@ -81,7 +128,8 @@ export function escapeMarkdownCell(value: string): string {
 }
 
 /**
- * Render a markdown string as styled terminal output.
+ * Render a full markdown document as styled terminal output, or return the
+ * raw CommonMark string when in plain mode.
  *
  * Supports the full CommonMark spec:
  * - Headings, bold, italic, strikethrough
@@ -96,8 +144,30 @@ export function escapeMarkdownCell(value: string): string {
  * Pre-rendered ANSI escape codes in the input are preserved.
  *
  * @param md - Markdown source text
- * @returns Styled terminal string with trailing whitespace trimmed
+ * @returns Styled terminal string (TTY) or raw CommonMark (non-TTY / plain mode)
  */
 export function renderMarkdown(md: string): string {
+  if (isPlainOutput()) {
+    return md.trimEnd();
+  }
   return (marked.parse(md) as string).trimEnd();
 }
+
+/**
+ * Render inline markdown (bold, code spans, emphasis, links) as styled
+ * terminal output, or return the raw markdown string when in plain mode.
+ *
+ * Unlike `renderMarkdown()`, this uses `marked.parseInline()` which handles
+ * only inline-level constructs — no paragraph wrapping, no block elements.
+ * Suitable for styling individual table cell values in streaming formatters
+ * that write rows incrementally rather than as a complete table.
+ *
+ * @param md - Inline markdown text
+ * @returns Styled string (TTY) or raw markdown text (non-TTY / plain mode)
+ */
+export function renderInlineMarkdown(md: string): string {
+  if (isPlainOutput()) {
+    return md;
+  }
+  return marked.parseInline(md) as string;
+}

src/lib/formatters/trace.ts

@@ -7,7 +7,12 @@
 import type { TraceSpan, TransactionListItem } from "../../types/index.js";
 import { muted } from "./colors.js";
 import { formatRelativeTime } from "./human.js";
-import { escapeMarkdownCell, renderMarkdown } from "./markdown.js";
+import {
+  escapeMarkdownCell,
+  isPlainOutput,
+  renderInlineMarkdown,
+  renderMarkdown,
+} from "./markdown.js";
 
 /**
  * Format a duration in milliseconds to a human-readable string.
@@ -44,9 +49,15 @@ export function formatTraceDuration(ms: number): string {
 /**
  * Format column header for traces list (used before per-row output).
  *
- * @returns Header line with column titles and separator
+ * In plain mode: emits a markdown table header + separator row.
+ * In rendered mode: emits an ANSI-muted text header with a rule separator.
+ *
+ * @returns Header string (includes trailing newline)
  */
 export function formatTracesHeader(): string {
+  if (isPlainOutput()) {
+    return "| Trace ID | Transaction | Duration | When |\n| --- | --- | ---: | --- |\n";
+  }
   const header = muted(
     "TRACE ID                          TRANSACTION                    DURATION    WHEN"
   );
@@ -65,10 +76,22 @@ const DURATION_WIDTH = 10;
 /**
  * Format a single transaction row for the traces list.
  *
+ * In plain mode (non-TTY / `SENTRY_PLAIN_OUTPUT=1`): emits a markdown table
+ * row so streamed output composes into a valid CommonMark document.
+ * In rendered mode (TTY): emits padded ANSI-colored text for live display.
+ *
  * @param item - Transaction list item from the API
  * @returns Formatted row string with newline
  */
 export function formatTraceRow(item: TransactionListItem): string {
+  if (isPlainOutput()) {
+    const traceId = renderInlineMarkdown(`\`${item.trace}\``);
+    const transaction = escapeMarkdownCell(item.transaction || "unknown");
+    const duration = formatTraceDuration(item["transaction.duration"]);
+    const when = formatRelativeTime(item.timestamp).trim();
+    return `| ${traceId} | ${transaction} | ${duration} | ${when} |\n`;
+  }
+
   const traceId = item.trace.slice(0, TRACE_ID_WIDTH).padEnd(TRACE_ID_WIDTH);
   const transaction = (item.transaction || "unknown")
     .slice(0, MAX_TRANSACTION_LENGTH)
@@ -77,7 +100,6 @@ export function formatTraceRow(item: TransactionListItem): string {
     DURATION_WIDTH
   );
   const when = formatRelativeTime(item.timestamp);
-
   return `${traceId}  ${transaction}  ${duration}  ${when}\n`;
 }
 

test/lib/formatters/log.test.ts

@@ -2,14 +2,46 @@
  * Tests for log formatters
  */
 
-import { describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import {
   formatLogDetails,
   formatLogRow,
   formatLogsHeader,
 } from "../../../src/lib/formatters/log.js";
 import type { DetailedSentryLog, SentryLog } from "../../../src/types/index.js";
 
+/** Force rendered (TTY) mode for a describe block */
+function useRenderedMode() {
+  let savedPlain: string | undefined;
+  beforeEach(() => {
+    savedPlain = process.env.SENTRY_PLAIN_OUTPUT;
+    process.env.SENTRY_PLAIN_OUTPUT = "0";
+  });
+  afterEach(() => {
+    if (savedPlain === undefined) {
+      delete process.env.SENTRY_PLAIN_OUTPUT;
+    } else {
+      process.env.SENTRY_PLAIN_OUTPUT = savedPlain;
+    }
+  });
+}
+
+/** Force plain mode for a describe block */
+function usePlainMode() {
+  let savedPlain: string | undefined;
+  beforeEach(() => {
+    savedPlain = process.env.SENTRY_PLAIN_OUTPUT;
+    process.env.SENTRY_PLAIN_OUTPUT = "1";
+  });
+  afterEach(() => {
+    if (savedPlain === undefined) {
+      delete process.env.SENTRY_PLAIN_OUTPUT;
+    } else {
+      process.env.SENTRY_PLAIN_OUTPUT = savedPlain;
+    }
+  });
+}
+
 function createTestLog(overrides: Partial<SentryLog> = {}): SentryLog {
   return {
     "sentry.item_id": "test-id-123",
@@ -28,7 +60,9 @@ function stripAnsi(str: string): string {
   return str.replace(/\x1b\[[0-9;]*m/g, "");
 }
 
-describe("formatLogRow", () => {
+describe("formatLogRow (rendered mode)", () => {
+  useRenderedMode();
+
   test("formats basic log entry", () => {
     const log = createTestLog();
     const result = formatLogRow(log);
@@ -116,7 +150,9 @@ describe("formatLogRow", () => {
   });
 });
 
-describe("formatLogsHeader", () => {
+describe("formatLogsHeader (rendered mode)", () => {
+  useRenderedMode();
+
   test("contains column titles", () => {
     const result = stripAnsi(formatLogsHeader());
 
@@ -138,6 +174,65 @@ describe("formatLogsHeader", () => {
   });
 });
 
+describe("formatLogRow (plain mode)", () => {
+  usePlainMode();
+
+  test("emits a markdown table row", () => {
+    const log = createTestLog();
+    const result = formatLogRow(log);
+    expect(result).toMatch(/^\|.+\|.+\|.+\|\n$/);
+  });
+
+  test("contains timestamp, severity, message", () => {
+    const log = createTestLog({
+      severity: "error",
+      message: "connection failed",
+    });
+    const result = formatLogRow(log);
+    expect(result).toContain("connection failed");
+    expect(result).toContain("ERROR");
+    expect(result).toMatch(/\d{4}-\d{2}-\d{2}/);
+  });
+
+  test("contains trace ID as inline code", () => {
+    const log = createTestLog({ trace: "abc123def456" });
+    const result = formatLogRow(log);
+    expect(result).toContain("[abc123de]");
+  });
+
+  test("omits trace cell when trace is null", () => {
+    const log = createTestLog({ trace: null });
+    const result = formatLogRow(log);
+    expect(result).not.toContain("[");
+  });
+
+  test("escapes pipe characters in message", () => {
+    const log = createTestLog({ message: "a|b" });
+    const result = formatLogRow(log);
+    // Raw pipe in message must be escaped so it doesn't break the table
+    expect(result).toContain("a\\|b");
+  });
+
+  test("ends with newline", () => {
+    const result = formatLogRow(createTestLog());
+    expect(result).toEndWith("\n");
+  });
+});
+
+describe("formatLogsHeader (plain mode)", () => {
+  usePlainMode();
+
+  test("emits markdown table header and separator", () => {
+    const result = formatLogsHeader();
+    expect(result).toContain("| Timestamp | Level | Message |");
+    expect(result).toContain("| --- | --- | --- |");
+  });
+
+  test("ends with newline", () => {
+    expect(formatLogsHeader()).toEndWith("\n");
+  });
+});
+
 function createDetailedTestLog(
   overrides: Partial<DetailedSentryLog> = {}
 ): DetailedSentryLog {