feat(formatters): add StreamingTable for bordered streaming log/trace output

Add StreamingTable class to text-table.ts that renders incrementally:
header (top border + column names + separator), row-by-row with side
borders, and footer (bottom border) on stream end.

Log streaming (--follow) now uses bordered tables in TTY mode:
- createLogStreamingTable() factory with pre-configured column hints
- SIGINT handler prints bottom border before exit
- Plain mode (non-TTY) still emits raw markdown rows for pipe safety

Trace streaming gets createTraceStreamingTable() factory (not yet wired
to command — traces don't have --follow yet, but the factory is ready).

Extract buildLogRowCells() and export buildTraceRowCells() so both
streaming (StreamingTable.row) and batch (formatLogTable/formatTraceTable)
paths share the same cell-building logic.

Author: BYK

src/commands/log/list.ts

@@ -12,9 +12,12 @@ import { listLogs } from "../../lib/api-client.js";
 import { validateLimit } from "../../lib/arg-parsing.js";
 import { AuthError, stringifyUnknown } from "../../lib/errors.js";
 import {
+  buildLogRowCells,
+  createLogStreamingTable,
   formatLogRow,
   formatLogsHeader,
   formatLogTable,
+  isPlainOutput,
   writeFooter,
   writeJson,
 } from "../../lib/formatters/index.js";
@@ -74,12 +77,24 @@ function parseFollow(value: string): number {
 
 /**
  * Write logs to output in the appropriate format.
+ *
+ * When a StreamingTable is provided (TTY mode), renders rows through the
+ * bordered table. Otherwise falls back to plain markdown rows.
  */
-function writeLogs(stdout: Writer, logs: SentryLog[], asJson: boolean): void {
+function writeLogs(
+  stdout: Writer,
+  logs: SentryLog[],
+  asJson: boolean,
+  table?: import("../../lib/formatters/text-table.js").StreamingTable
+): void {
   if (asJson) {
     for (const log of logs) {
       writeJson(stdout, log);
     }
+  } else if (table) {
+    for (const log of logs) {
+      stdout.write(table.row(buildLogRowCells(log)));
+    }
   } else {
     for (const log of logs) {
       stdout.write(formatLogRow(log));
@@ -158,7 +173,12 @@ async function executeFollowMode(options: FollowModeOptions): Promise<void> {
     stderr.write("\n");
   }
 
-  // Track if header has been printed (for human mode)
+  // In TTY mode, use a bordered StreamingTable for aligned columns.
+  // In plain mode, use raw markdown rows for pipe-friendly output.
+  const plain = flags.json || isPlainOutput();
+  const table = plain ? undefined : createLogStreamingTable();
+
+  // Track if header has been printed (for human/plain mode)
   let headerPrinted = false;
 
   // Initial fetch: only last minute for follow mode (we want recent logs, not historical)
@@ -170,13 +190,21 @@ async function executeFollowMode(options: FollowModeOptions): Promise<void> {
 
   // Print header before initial logs (human mode only)
   if (!flags.json && initialLogs.length > 0) {
-    stdout.write(formatLogsHeader());
+    stdout.write(table ? table.header() : formatLogsHeader());
     headerPrinted = true;
   }
 
   // Reverse for chronological order (API returns newest first, tail -f shows oldest first)
   const chronologicalInitial = [...initialLogs].reverse();
-  writeLogs(stdout, chronologicalInitial, flags.json);
+  writeLogs(stdout, chronologicalInitial, flags.json, table);
+
+  // Print bottom border on Ctrl+C so the table closes cleanly
+  if (table) {
+    process.once("SIGINT", () => {
+      stdout.write(table.footer());
+      process.exit(0);
+    });
+  }
 
   // Track newest timestamp (logs are sorted -timestamp, so first is newest)
   // Use current time as fallback to avoid fetching old logs when initial fetch is empty
@@ -200,13 +228,13 @@ async function executeFollowMode(options: FollowModeOptions): Promise<void> {
       if (newestLog) {
         // Print header before first logs if not already printed
         if (!(flags.json || headerPrinted)) {
-          stdout.write(formatLogsHeader());
+          stdout.write(table ? table.header() : formatLogsHeader());
           headerPrinted = true;
         }
 
         // Reverse for chronological order (oldest first for tail -f style)
         const chronologicalNew = [...newLogs].reverse();
-        writeLogs(stdout, chronologicalNew, flags.json);
+        writeLogs(stdout, chronologicalNew, flags.json, table);
 
         // Update timestamp AFTER successful write to avoid losing logs on write failure
         lastTimestamp = newestLog.timestamp_precise;

src/lib/formatters/log.ts

@@ -8,15 +8,14 @@ import type { DetailedSentryLog, SentryLog } from "../../types/index.js";
 import { buildTraceUrl } from "../sentry-urls.js";
 import {
   colorTag,
-  divider,
   escapeMarkdownCell,
   escapeMarkdownInline,
-  isPlainOutput,
   mdKvTable,
   mdRow,
   mdTableHeader,
   renderMarkdown,
 } from "./markdown.js";
+import { StreamingTable, type StreamingTableOptions } from "./text-table.js";
 
 /** Markdown color tag names for log severity levels */
 const SEVERITY_TAGS: Record<string, Parameters<typeof colorTag>[0]> = {
@@ -66,39 +65,70 @@ function formatTimestamp(timestamp: string): string {
 }
 
 /**
- * Format a single log entry for human-readable output.
+ * Extract cell values for a log row (shared by streaming and batch paths).
  *
- * 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
+ * @param padSeverity - Whether to pad severity to 7 chars for alignment
+ * @returns `[timestamp, severity, message]` strings
+ */
+export function buildLogRowCells(
+  log: SentryLog,
+  padSeverity = true
+): [string, string, string] {
+  const timestamp = formatTimestamp(log.timestamp);
+  const level = padSeverity
+    ? formatSeverity(log.severity)
+    : formatSeverityLabel(log.severity);
+  const message = escapeMarkdownCell(log.message ?? "");
+  const trace = log.trace ? ` \`[${log.trace.slice(0, 8)}]\`` : "";
+  return [timestamp, level, `${message}${trace}`];
+}
+
+/**
+ * Format a single log entry as a plain markdown table row.
+ * Used for non-TTY / piped output where StreamingTable isn't appropriate.
  *
  * @param log - The log entry to format
  * @returns Formatted log line with newline
  */
 export function formatLogRow(log: SentryLog): string {
-  const timestamp = formatTimestamp(log.timestamp);
-  // Use formatSeverity() for per-level ANSI color (red/yellow/cyan/muted),
-  // matching the batch-mode formatLogTable path.
-  const level = formatSeverity(log.severity);
-  const message = escapeMarkdownCell(log.message ?? "");
-  const trace = log.trace ? ` \`[${log.trace.slice(0, 8)}]\`` : "";
-  return mdRow([timestamp, level, `${message}${trace}`]);
+  return mdRow(buildLogRowCells(log));
+}
+
+/** Hint rows for column width estimation in streaming mode. */
+const LOG_HINT_ROWS: string[][] = [
+  ["2026-01-15 23:59:59", "WARNING", "A typical log message with some detail"],
+];
+
+/**
+ * Create a StreamingTable configured for log output.
+ *
+ * @param options - Override default table options
+ * @returns A StreamingTable with log-specific column configuration
+ */
+export function createLogStreamingTable(
+  options: Partial<StreamingTableOptions> = {}
+): StreamingTable {
+  return new StreamingTable([...LOG_TABLE_COLS], {
+    hintRows: LOG_HINT_ROWS,
+    // Timestamp and Level are fixed-width; Message gets the rest
+    shrinkable: [false, false, true],
+    truncate: false,
+    ...options,
+  });
 }
 
 /**
- * Format column header for logs list (used in streaming/follow mode).
+ * Format column header for logs list in plain (non-TTY) mode.
  *
- * In plain mode: emits a proper markdown table header + separator row so that
+ * Emits a proper markdown table header + separator row so that
  * the streamed rows compose into a valid CommonMark document when redirected.
- * In rendered mode: emits an ANSI-muted text header with a rule separator.
+ * In TTY mode, use {@link createLogStreamingTable} instead.
  *
  * @returns Header string (includes trailing newline)
  */
 export function formatLogsHeader(): string {
-  if (isPlainOutput()) {
-    return `${mdTableHeader(LOG_TABLE_COLS)}\n`;
-  }
-  return `${mdRow(LOG_TABLE_COLS.map((c) => `**${c}**`))}${divider(80)}\n`;
+  return `${mdTableHeader(LOG_TABLE_COLS)}\n`;
 }
 
 /**
@@ -111,16 +141,7 @@ export function formatLogsHeader(): string {
  */
 export function formatLogTable(logs: SentryLog[]): string {
   const rows = logs
-    .map((log) => {
-      const timestamp = formatTimestamp(log.timestamp);
-      // formatSeverity wraps the padEnd label inside a color tag, so .trim()
-      // on the result would be a no-op. Use formatSeverityLabel (no padding)
-      // for the batch table which handles its own column sizing.
-      const severity = formatSeverityLabel(log.severity);
-      const message = escapeMarkdownCell(log.message ?? "");
-      const trace = log.trace ? ` \`[${log.trace.slice(0, 8)}]\`` : "";
-      return mdRow([timestamp, severity, `${message}${trace}`]).trimEnd();
-    })
+    .map((log) => mdRow(buildLogRowCells(log, false)).trimEnd())
     .join("\n");
 
   return renderMarkdown(`${mdTableHeader(LOG_TABLE_COLS)}\n${rows}`);

src/lib/formatters/text-table.ts

@@ -537,3 +537,178 @@ function horizontalLine(
   const segments = columnWidths.map((w) => chars.horizontal.repeat(w));
   return `${chars.left}${segments.join(chars.junction)}${chars.right}`;
 }
+
+/** Options for creating a streaming table. */
+export type StreamingTableOptions = {
+  /** Border style. @default "rounded" */
+  borderStyle?: BorderStyle;
+  /** Horizontal cell padding (each side). @default 1 */
+  cellPadding?: number;
+  /** Maximum table width in columns. @default process.stdout.columns or 80 */
+  maxWidth?: number;
+  /** Per-column alignment (indexed by column). Defaults to "left". */
+  alignments?: Array<Alignment | null>;
+  /** Per-column minimum content widths. Columns will not shrink below these. */
+  minWidths?: number[];
+  /** Per-column shrinkable flags. Non-shrinkable columns keep intrinsic width. */
+  shrinkable?: boolean[];
+  /** Truncate cells to one line with "…" instead of wrapping. @default true */
+  truncate?: boolean;
+  /**
+   * Hint rows used for column width measurement.
+   * Pass representative sample data so column widths are computed correctly
+   * without needing the full dataset upfront.
+   */
+  hintRows?: string[][];
+};
+
+/**
+ * A bordered table that renders incrementally — header first, then one row
+ * at a time, then a bottom border at the end. Column widths are fixed at
+ * construction time based on headers + optional hint rows.
+ *
+ * Usage:
+ * ```ts
+ * const table = new StreamingTable(["Time", "Level", "Message"], opts);
+ * writer.write(table.header());
+ * writer.write(table.row(["2026-02-28 10:00", "ERROR", "something broke"]));
+ * writer.write(table.footer());
+ * ```
+ *
+ * In plain-output mode (non-TTY), emits raw CommonMark markdown table syntax
+ * so piped/redirected output remains a valid document.
+ */
+export class StreamingTable {
+  /** @internal */ readonly columnWidths: number[];
+  /** @internal */ readonly border: BorderCharacters;
+  /** @internal */ readonly cellPadding: number;
+  /** @internal */ readonly alignments: Array<Alignment | null>;
+  /** @internal */ readonly headers: string[];
+  /** @internal */ readonly truncate: boolean;
+
+  constructor(headers: string[], options: StreamingTableOptions = {}) {
+    const {
+      borderStyle = "rounded",
+      cellPadding = 1,
+      maxWidth = process.stdout.columns || 80,
+      alignments = [],
+      minWidths = [],
+      shrinkable = [],
+      truncate = true,
+      hintRows = [],
+    } = options;
+
+    this.headers = headers;
+    this.border = BorderChars[borderStyle];
+    this.cellPadding = cellPadding;
+    this.alignments = alignments;
+    this.truncate = truncate;
+
+    const colCount = headers.length;
+    const intrinsicWidths = measureIntrinsicWidths(
+      headers,
+      hintRows,
+      colCount,
+      { cellPadding, minWidths }
+    );
+
+    const borderOverhead = 2 + (colCount - 1);
+    const maxContentWidth = Math.max(colCount, maxWidth - borderOverhead);
+    this.columnWidths = fitColumns(intrinsicWidths, maxContentWidth, {
+      cellPadding,
+      fitter: "balanced",
+      minWidths,
+      shrinkable,
+    });
+  }
+
+  /**
+   * Render the top border, header row, and header separator.
+   * Call once at the start of streaming.
+   */
+  header(): string {
+    const { border, columnWidths, cellPadding, alignments, headers } = this;
+    const hz = border.horizontal;
+    const lines: string[] = [];
+
+    // Top border
+    lines.push(
+      horizontalLine(columnWidths, {
+        left: border.topLeft,
+        junction: border.topT,
+        right: border.topRight,
+        horizontal: hz,
+      })
+    );
+
+    // Header cells
+    const wrappedHeader = wrapRow(headers, columnWidths, cellPadding, false);
+    const rowHeight = Math.max(1, ...wrappedHeader.map((c) => c.length));
+    for (let line = 0; line < rowHeight; line++) {
+      const cellTexts: string[] = [];
+      for (let c = 0; c < columnWidths.length; c++) {
+        const cellLines = wrappedHeader[c] ?? [""];
+        const text = cellLines[line] ?? "";
+        const align = alignments[c] ?? "left";
+        const colW = columnWidths[c] ?? 3;
+        cellTexts.push(padCell(text, colW, align, cellPadding));
+      }
+      lines.push(
+        `${border.vertical}${cellTexts.join(border.vertical)}${border.vertical}`
+      );
+    }
+
+    // Header separator
+    lines.push(
+      horizontalLine(columnWidths, {
+        left: border.leftT,
+        junction: border.cross,
+        right: border.rightT,
+        horizontal: hz,
+      })
+    );
+
+    return `${lines.join("\n")}\n`;
+  }
+
+  /**
+   * Render a single data row with side borders.
+   * Call once per data item as it arrives.
+   */
+  row(cells: string[]): string {
+    const { border, columnWidths, cellPadding, alignments, truncate } = this;
+    const wrappedCells = wrapRow(cells, columnWidths, cellPadding, truncate);
+    const rowHeight = Math.max(1, ...wrappedCells.map((c) => c.length));
+    const lines: string[] = [];
+
+    for (let line = 0; line < rowHeight; line++) {
+      const cellTexts: string[] = [];
+      for (let c = 0; c < columnWidths.length; c++) {
+        const cellLines = wrappedCells[c] ?? [""];
+        const text = cellLines[line] ?? "";
+        const align = alignments[c] ?? "left";
+        const colW = columnWidths[c] ?? 3;
+        cellTexts.push(padCell(text, colW, align, cellPadding));
+      }
+      lines.push(
+        `${border.vertical}${cellTexts.join(border.vertical)}${border.vertical}`
+      );
+    }
+
+    return `${lines.join("\n")}\n`;
+  }
+
+  /**
+   * Render the bottom border.
+   * Call once when the stream ends.
+   */
+  footer(): string {
+    const { border, columnWidths } = this;
+    return `${horizontalLine(columnWidths, {
+      left: border.bottomLeft,
+      junction: border.bottomT,
+      right: border.bottomRight,
+      horizontal: border.horizontal,
+    })}\n`;
+  }
+}