@hs-x/cli 0.4.11 → 0.4.13

package/dist/dev/stream-renderer.js

@@ -13,14 +13,41 @@
  * surface (`setFilter` / `pause` / `setPrompt`) that the keyboard controller
  * in keyboard.ts drives. Non-TTY output is untouched: no status line, no
  * escape codes, every event printed.
+ *
+ * Details mode (`d` / ↑) swaps the stream for a browser: a list of the
+ * retained matching events on one side and the untruncated details of the
+ * selected one on the other, in the spirit of a clipboard-history picker.
+ * Up/down move the selection, page keys scroll the detail pane, and new
+ * events keep arriving in the list while the selection stays pinned.
+ *
+ * The browser lives in the terminal's alternate screen buffer (the way
+ * `less` and `vim` do). Repaints happen in place there, so neither
+ * navigation nor arriving events grow the scrollback — some terminals
+ * (alacritty-based ones such as Zed's) push a cleared primary screen into
+ * history, which turned every keypress into a screenful to scroll past.
+ * Leaving restores the stream exactly as it was and appends whatever
+ * arrived meanwhile, so nothing is repainted on the way out.
  */
-import { detectColor, detectUnicode, makeStyle, symbolsFor, wrapVisible, } from '../reporter/style.js';
-import { devEventFingerprint, formatDevStreamEvent, renderDevEventDetails, } from './stream-event-format.js';
+import { detectColor, detectUnicode, makeStyle, padVisible, symbolsFor, truncateVisible, wrapVisible, } from '../reporter/style.js';
+import { copyTextToClipboard } from './clipboard.js';
+import { devEventFingerprint, formatDevDetailsListRow, formatDevStreamEvent, renderDevEventDetails, } from './stream-event-format.js';
 import { EMPTY_FILTER, describeFilter, isEmptyFilter, matchesFilter, } from './stream-filter.js';
+import { renderDevTraceMarkdown, selectDevTrace } from './trace-markdown.js';
 const ERASE_LINE = '\r\x1b[2K';
-const CLEAR_SCREEN = '\x1b[2J\x1b[H';
+/**
+ * Home the cursor and erase to the end of the screen. Unlike `ESC[2J` this
+ * never pushes the visible rows into scrollback, so filter repaints overwrite
+ * the view in place instead of stacking screenfuls of history.
+ */
+const REPAINT_SCREEN = '\x1b[H\x1b[0J';
+const ALT_SCREEN_ENTER = '\x1b[?1049h\x1b[?25l';
+const ALT_SCREEN_LEAVE = '\x1b[?25h\x1b[?1049l';
 const HISTORY_LIMIT = 500;
 const HISTORY_EVENT_MAX_LINES = 12;
+/** Terminals at least this wide get the list beside the detail pane. */
+const SIDE_BY_SIDE_MIN_COLUMNS = 90;
+/** Stacked layout: the list keeps a few rows and the detail pane takes the rest. */
+const STACKED_LIST_MAX_ROWS = 8;
 export function startDevStreamRenderer(opts) {
     const stderr = opts.stderr ?? process.stderr;
     const env = opts.env ?? process.env;
@@ -28,6 +55,7 @@ export function startDevStreamRenderer(opts) {
     const color = detectColor(env, isTTY);
     const style = makeStyle(color, detectUnicode(env));
     const sym = symbolsFor(style.unicode);
+    const copyText = opts.copyText ?? copyTextToClipboard;
     // Cursor control is a terminal capability, independent of color. NO_COLOR
     // must remove SGR styling without hiding prompts, filters, pause state, or
     // the key map. Piped/non-TTY output remains plain append-only text.
@@ -40,8 +68,9 @@ export function startDevStreamRenderer(opts) {
     let prompt;
     let statusShown = false;
     let lastStatusWidth = 0;
-    let detailEntry;
-    let detailPending = 0;
+    let details;
+    let detailsRepaintQueued = false;
+    let stopped = false;
     let lastWritten;
     const pauseBuffer = [];
     const startupBuffer = [];
@@ -60,6 +89,15 @@ export function startDevStreamRenderer(opts) {
         const terminalRows = stderr.rows;
         return typeof terminalRows === 'number' && terminalRows > 0 ? terminalRows : 24;
     };
+    const matchingEntries = () => history.filter((entry) => matchesFilter(filter, entry.event));
+    const detailEntries = () => {
+        const matching = matchingEntries();
+        if (!details?.related)
+            return matching;
+        const related = new Set(selectDevTrace(history, details.selected).entries);
+        return matching.filter((entry) => related.has(entry));
+    };
+    const separator = style.dim(` ${sym.bullet} `);
     // Compose from plain segments and paint at the end, so the line can be
     // fitted to the terminal width without ever cutting through an ANSI code —
     // a wrapped status line is unerasable and smears on every redraw.
@@ -71,25 +109,40 @@ export function startDevStreamRenderer(opts) {
             return line.length > width ? line.slice(0, Math.max(0, width)) : line;
         }
         const scope = describeFilter(filter);
-        const segments = detailEntry
-            ? [
-                {
-                    text: `detail: ${detailEntry.event.lane}`,
-                    painted: `${style.dim('detail:')} ${style.orange(detailEntry.event.lane)}`,
-                },
-            ]
-            : [
-                {
+        const segments = [];
+        if (details) {
+            const matching = detailEntries();
+            const index = Math.max(0, matching.indexOf(details.selected));
+            const position = `${index + 1}/${matching.length}`;
+            segments.push({
+                text: `event ${position} ${details.selected.event.lane}`,
+                painted: `${style.dim('event')} ${position} ${style.orange(details.selected.event.lane)}`,
+            });
+            if (!isEmptyFilter(filter)) {
+                segments.push({
                     text: `view: ${scope}`,
-                    painted: `${style.dim('view:')} ${isEmptyFilter(filter) ? style.dim(scope) : style.orange(scope)}`,
-                },
-            ];
-        if (detailEntry && detailPending > 0) {
-            const text = `${detailPending} new`;
-            segments.push({ text, painted: style.dim(text) });
+                    painted: `${style.dim('view:')} ${style.orange(scope)}`,
+                });
+            }
+            if (details.pending > 0) {
+                const text = `${details.pending} new`;
+                segments.push({ text, painted: style.yellow(text) });
+            }
+            if (details.related) {
+                segments.push({ text: 'trace', painted: style.cyan('trace') });
+            }
+            if (details.notice) {
+                segments.push({ text: details.notice, painted: style.green(details.notice) });
+            }
         }
-        else if (!detailEntry && hidden > 0) {
-            segments.push({ text: `${hidden} hidden`, painted: style.dim(`${hidden} hidden`) });
+        else {
+            segments.push({
+                text: `view: ${scope}`,
+                painted: `${style.dim('view:')} ${isEmptyFilter(filter) ? style.dim(scope) : style.orange(scope)}`,
+            });
+            if (hidden > 0) {
+                segments.push({ text: `${hidden} hidden`, painted: style.dim(`${hidden} hidden`) });
+            }
         }
         if (paused) {
             const bufferedCount = retainedCount(pauseBuffer);
@@ -109,11 +162,17 @@ export function startDevStreamRenderer(opts) {
         }
         // Keep the footer focused on the less-obvious view controls. Help and quit
         // remain available from the keyboard without occupying persistent space.
-        const hintTiers = detailEntry
-            ? ['[d] back']
+        const arrows = style.unicode ? '↑↓' : 'up/down';
+        const hintTiers = details
+            ? [
+                `[${arrows}] move  [y] copy trace  [t] related  [pgup/pgdn] scroll  [esc] back`,
+                `[${arrows}] move  [y] copy  [t] related  [esc] back`,
+                '[y] copy  [t] related  [esc] back',
+                '[esc] back',
+            ]
             : [
-                '[f] lane  [e] errors  [/] search  [d] details  [c] reset  [p] pause',
-                '[f] [e] [/] [d] [c] [p]',
+                `[${arrows}] browse  [f] lane  [e] errors  [/] search  [c] reset  [p] pause`,
+                `[${arrows}] [f] [e] [/] [c] [p]`,
             ];
         for (const hints of hintTiers) {
             const cost = sepWidth + hints.length;
@@ -131,7 +190,7 @@ export function startDevStreamRenderer(opts) {
             used = prefixWidth + cut.length;
         }
         lastStatusWidth = used;
-        return `  ${style.orange(sym.rail)} ${kept.map((segment) => segment.painted).join(style.dim(` ${sym.bullet} `))}`;
+        return `  ${style.orange(sym.rail)} ${kept.map((segment) => segment.painted).join(separator)}`;
     };
     const drawStatus = () => {
         if (!statusEnabled || statusHeld)
@@ -146,6 +205,11 @@ export function startDevStreamRenderer(opts) {
     const onResize = () => {
         if (!statusEnabled)
             return;
+        if (details) {
+            // The primary screen is untouched underneath; only the browser repaints.
+            renderDetails();
+            return;
+        }
         lastWritten = undefined;
         if (statusShown) {
             stderr.write(ERASE_LINE);
@@ -195,9 +259,16 @@ export function startDevStreamRenderer(opts) {
         if (previous?.fingerprint === fingerprint) {
             previous.event = event;
             previous.count += 1;
+            previous.lastTs = event.ts;
             return { entry: previous, repeated: true };
         }
-        const entry = { event, fingerprint, count: 1 };
+        const entry = {
+            event,
+            fingerprint,
+            count: 1,
+            firstTs: event.ts,
+            lastTs: event.ts,
+        };
         history.push(entry);
         if (history.length <= HISTORY_LIMIT)
             return { entry, repeated: false };
@@ -220,7 +291,7 @@ export function startDevStreamRenderer(opts) {
             return;
         }
         eraseStatus();
-        const matching = history.filter((entry) => matchesFilter(filter, entry.event));
+        const matching = matchingEntries();
         const rowBudget = Math.max(8, rows() - 4);
         const selected = [];
         let usedRows = 0;
@@ -245,8 +316,8 @@ export function startDevStreamRenderer(opts) {
         const count = matching.length === selected.length
             ? `${matchingCount} recent event${matchingCount === 1 ? '' : 's'}`
             : `latest ${selectedCount} of ${matchingCount} recent events`;
-        stderr.write(CLEAR_SCREEN);
-        stderr.write(`  ${style.bold('hs-x dev logs')} ${style.dim(style.unicode ? '·' : '-')} ${isEmptyFilter(filter) ? style.dim(scope) : style.orange(scope)} ${style.dim(style.unicode ? '·' : '-')} ${style.dim(count)}\n`);
+        stderr.write(REPAINT_SCREEN);
+        stderr.write(`  ${style.bold('hs-x dev logs')} ${separator}${isEmptyFilter(filter) ? style.dim(scope) : style.orange(scope)}${separator}${style.dim(count)}\n`);
         if (selected.length === 0) {
             const detail = filter.texts.length > 0
                 ? `No events match ${filter.texts.map((text) => `“${text}”`).join(' or ')}. Search is case-insensitive.`
@@ -268,11 +339,169 @@ export function startDevStreamRenderer(opts) {
             : undefined;
         drawStatus();
     };
+    /** One compact list row: the stream line's headline, no continuations. */
+    const listRow = (entry, selected, width) => {
+        const pointer = selected ? style.orange(style.unicode ? '▸' : '>') : ' ';
+        return truncateVisible(`${pointer} ${formatDevDetailsListRow(entry.event, entry.count, style)}`, width);
+    };
+    /**
+     * Paint the details browser: header, the list beside (or above) the detail
+     * pane, then the status line. Everything is derived from retained history,
+     * so it can be repainted after any change — selection, scroll, new event,
+     * filter, resize — without tracking what is on screen.
+     */
+    const renderDetails = () => {
+        if (!details || !statusEnabled || statusHeld)
+            return;
+        const matching = detailEntries();
+        if (matching.length === 0) {
+            if (details.related) {
+                details.related = false;
+                details.notice = 'no related events match the active filter';
+                renderDetails();
+                return;
+            }
+            closeDetails();
+            return;
+        }
+        let index = matching.indexOf(details.selected);
+        if (index < 0) {
+            // The pinned entry was evicted from history or no longer matches.
+            index = matching.length - 1;
+            details.selected = matching[index];
+            details.scroll = 0;
+        }
+        const isNewest = index === matching.length - 1;
+        if (isNewest)
+            details.pending = 0;
+        const width = columns();
+        const height = rows();
+        // Header, blank rule, and the status line on the last row (written
+        // without a newline so the alternate screen never scrolls).
+        const bodyRows = Math.max(6, height - 3);
+        const sideBySide = width >= SIDE_BY_SIDE_MIN_COLUMNS;
+        const listWidth = sideBySide ? Math.min(56, Math.max(36, Math.floor(width * 0.38))) : width - 1;
+        const listRows = sideBySide
+            ? bodyRows
+            : Math.min(matching.length, Math.max(3, Math.min(STACKED_LIST_MAX_ROWS, Math.floor(bodyRows * 0.35))));
+        const detailWidth = sideBySide ? width - listWidth - 3 : width;
+        const detailRows = sideBySide ? bodyRows : bodyRows - listRows - 1;
+        if (index < details.listTop)
+            details.listTop = index;
+        if (index >= details.listTop + listRows)
+            details.listTop = index - listRows + 1;
+        details.listTop = Math.max(0, Math.min(details.listTop, matching.length - listRows));
+        const listLines = [];
+        for (let row = 0; row < listRows; row += 1) {
+            const entry = matching[details.listTop + row];
+            listLines.push(entry ? listRow(entry, entry === details.selected, listWidth) : '');
+        }
+        const above = details.listTop;
+        const below = Math.max(0, matching.length - (details.listTop + listRows));
+        if (above > 0 && listLines.length > 0) {
+            listLines[0] = truncateVisible(`  ${style.dim(`… ${above} older`)}`, listWidth);
+        }
+        if (below > 0 && listLines.length > 1) {
+            listLines[listLines.length - 1] = truncateVisible(`  ${style.dim(`… ${below} newer`)}`, listWidth);
+        }
+        const detailLines = renderDevEventDetails(details.selected.event, details.selected.count, style, detailWidth, { firstTs: details.selected.firstTs, lastTs: details.selected.lastTs }).split('\n');
+        const maxScroll = Math.max(0, detailLines.length - detailRows);
+        details.scroll = Math.max(0, Math.min(details.scroll, maxScroll));
+        const pane = detailLines.slice(details.scroll, details.scroll + detailRows);
+        if (details.scroll > 0 && pane.length > 0) {
+            pane[0] = `  ${style.dim(`… ${plural(details.scroll, 'line')} above  (pgup)`)}`;
+        }
+        const remaining = detailLines.length - (details.scroll + pane.length);
+        if (remaining > 0 && pane.length > 1) {
+            pane[pane.length - 1] = `  ${style.dim(`… ${plural(remaining, 'line')} more  (pgdn)`)}`;
+        }
+        const paneLines = pane.map((line) => truncateVisible(line, detailWidth));
+        const position = `${index + 1} of ${matching.length}`;
+        const scope = details.related ? 'trace' : details.selected.event.lane;
+        const header = `  ${style.bold('hs-x dev event')}${separator}${style.orange(scope)}${separator}${style.dim(position)}`;
+        const out = [truncateVisible(header, width - 1), ''];
+        if (sideBySide) {
+            const rail = style.dim(sym.rail);
+            for (let row = 0; row < bodyRows; row += 1) {
+                const left = padVisible(listLines[row] ?? '', listWidth);
+                const right = paneLines[row] ?? '';
+                out.push(`${left} ${rail} ${right}`.trimEnd());
+            }
+        }
+        else {
+            out.push(...listLines);
+            out.push(`  ${style.dim((style.unicode ? '─' : '-').repeat(Math.max(8, width - 4)))}`);
+            out.push(...paneLines);
+        }
+        statusShown = false; // the repaint below erases the whole alternate screen
+        stderr.write(REPAINT_SCREEN);
+        stderr.write(`${out.join('\n')}\n`);
+        drawStatus();
+    };
+    // Bursts (a HubSpot poll batch, a stack trace) arrive as many synchronous
+    // emits; repaint the browser once after the burst instead of per event.
+    const queueDetailsRepaint = () => {
+        if (detailsRepaintQueued)
+            return;
+        detailsRepaintQueued = true;
+        queueMicrotask(() => {
+            detailsRepaintQueued = false;
+            if (!stopped && details)
+                renderDetails();
+        });
+    };
+    const openDetails = () => {
+        const latest = matchingEntries().at(-1);
+        if (!latest)
+            return false;
+        // Erase the primary status line first so it is not restored twice: the
+        // alternate screen switch saves the primary buffer and cursor as they are.
+        eraseStatus();
+        stderr.write(ALT_SCREEN_ENTER);
+        details = {
+            selected: latest,
+            listTop: 0,
+            scroll: 0,
+            pending: 0,
+            arrivals: [],
+            related: false,
+            notice: undefined,
+        };
+        renderDetails();
+        return true;
+    };
+    const closeDetails = () => {
+        if (!details)
+            return;
+        const { arrivals } = details;
+        details = undefined;
+        statusShown = false; // the alternate screen's status line vanishes with it
+        stderr.write(ALT_SCREEN_LEAVE);
+        hidden = retainedCount(history.filter((entry) => !matchesFilter(filter, entry.event)));
+        // The stream is back exactly as it was; append what arrived meanwhile.
+        for (const entry of arrivals) {
+            if (!matchesFilter(filter, entry.event))
+                continue;
+            if (paused)
+                pauseBuffer.push(entry);
+            else if (lastWritten?.entry === entry)
+                rewriteLastEvent(entry);
+            else
+                writeEvent(entry);
+        }
+        drawStatus();
+    };
     const onEvent = (event) => {
         const remembered = remember(event);
         if (statusHeld) {
             if (!statusEnabled) {
-                startupBuffer.push({ event, fingerprint: remembered.entry.fingerprint, count: 1 });
+                startupBuffer.push({
+                    event,
+                    fingerprint: remembered.entry.fingerprint,
+                    count: 1,
+                    firstTs: event.ts,
+                    lastTs: event.ts,
+                });
             }
             else if (!remembered.repeated) {
                 startupBuffer.push(remembered.entry);
@@ -285,15 +514,22 @@ export function startDevStreamRenderer(opts) {
                 drawStatus();
             return;
         }
-        if (detailEntry) {
-            detailPending += 1;
-            if (statusEnabled)
-                drawStatus();
+        if (details) {
+            details.pending += 1;
+            if (!details.arrivals.includes(remembered.entry))
+                details.arrivals.push(remembered.entry);
+            queueDetailsRepaint();
             return;
         }
         if (paused) {
             if (!statusEnabled) {
-                pauseBuffer.push({ event, fingerprint: remembered.entry.fingerprint, count: 1 });
+                pauseBuffer.push({
+                    event,
+                    fingerprint: remembered.entry.fingerprint,
+                    count: 1,
+                    firstTs: event.ts,
+                    lastTs: event.ts,
+                });
             }
             else if (!remembered.repeated) {
                 pauseBuffer.push(remembered.entry);
@@ -310,6 +546,18 @@ export function startDevStreamRenderer(opts) {
     const unsubscribe = opts.bus.subscribe(onEvent);
     if (statusEnabled)
         drawStatus();
+    const applyFilter = (next) => {
+        filter = next;
+        if (details) {
+            // Stay in the browser: the list re-derives from the new filter and the
+            // selection snaps to the newest match if the pinned event dropped out.
+            details.listTop = 0;
+            hidden = retainedCount(history.filter((entry) => !matchesFilter(filter, entry.event)));
+            renderDetails();
+            return;
+        }
+        refreshHistoryView();
+    };
     return {
         ready() {
             if (!statusHeld)
@@ -329,17 +577,9 @@ export function startDevStreamRenderer(opts) {
         },
         hasStatusLine: () => statusEnabled,
         getFilter: () => filter,
-        setFilter(next) {
-            filter = next;
-            detailEntry = undefined;
-            detailPending = 0;
-            refreshHistoryView();
-        },
+        setFilter: applyFilter,
         resetFilter() {
-            filter = initialFilter;
-            detailEntry = undefined;
-            detailPending = 0;
-            refreshHistoryView();
+            applyFilter(initialFilter);
         },
         setPaused(next) {
             if (paused === next)
@@ -356,13 +596,11 @@ export function startDevStreamRenderer(opts) {
         },
         isPaused: () => paused,
         toggleLatestDetails() {
-            if (detailEntry) {
-                detailEntry = undefined;
-                detailPending = 0;
-                refreshHistoryView();
+            if (details) {
+                closeDetails();
                 return;
             }
-            const latest = history.findLast((entry) => matchesFilter(filter, entry.event));
+            const latest = matchingEntries().at(-1);
             if (!latest) {
                 eraseStatus();
                 stderr.write(`  ${style.dim('No matching event is available for details.')}\n`);
@@ -374,14 +612,76 @@ export function startDevStreamRenderer(opts) {
                 stderr.write(`${renderDevEventDetails(latest.event, latest.count, style, columns())}\n`);
                 return;
             }
-            detailEntry = latest;
-            detailPending = 0;
-            eraseStatus();
-            stderr.write(CLEAR_SCREEN);
-            stderr.write(`  ${style.bold('hs-x dev event')} ${style.dim(style.unicode ? '·' : '-')} ${style.orange(latest.event.lane)} ${style.dim(style.unicode ? '·' : '-')} ${style.dim('latest matching event')}\n`);
-            stderr.write(`${renderDevEventDetails(latest.event, latest.count, style, columns())}\n`);
-            lastWritten = undefined;
-            drawStatus();
+            openDetails();
+        },
+        isShowingDetails: () => details !== undefined,
+        moveDetailsSelection(delta) {
+            if (!details) {
+                if (!statusEnabled || !openDetails())
+                    return;
+                // Entering with ↑ lands on the newest event; the move itself is the
+                // gesture, so a single press does not additionally step older.
+                return;
+            }
+            const matching = detailEntries();
+            const index = matching.indexOf(details.selected);
+            const next = Math.max(0, Math.min(matching.length - 1, (index < 0 ? matching.length - 1 : index) + delta));
+            const target = matching[next];
+            if (!target)
+                return;
+            if (target !== details.selected) {
+                details.selected = target;
+                details.scroll = 0;
+                details.notice = undefined;
+            }
+            renderDetails();
+        },
+        jumpDetailsSelection(edge) {
+            if (!details) {
+                if (!statusEnabled || !openDetails())
+                    return;
+                if (edge === 'last')
+                    return;
+            }
+            if (!details)
+                return;
+            const matching = detailEntries();
+            const target = edge === 'first' ? matching[0] : matching.at(-1);
+            if (!target)
+                return;
+            if (target !== details.selected) {
+                details.selected = target;
+                details.scroll = 0;
+                details.notice = undefined;
+            }
+            renderDetails();
+        },
+        scrollDetails(delta) {
+            if (!details)
+                return;
+            details.scroll = Math.max(0, details.scroll + delta);
+            details.notice = undefined;
+            renderDetails();
+        },
+        toggleRelatedDetails() {
+            if (!details)
+                return;
+            details.related = !details.related;
+            details.listTop = 0;
+            details.scroll = 0;
+            details.notice = details.related ? 'showing related events' : undefined;
+            renderDetails();
+        },
+        copyDetailsTrace() {
+            if (!details)
+                return;
+            const selection = selectDevTrace(history, details.selected);
+            const markdown = renderDevTraceMarkdown(selection, details.selected);
+            const result = copyText(markdown);
+            details.notice = result.ok
+                ? `copied ${selection.entries.length}-event trace as Markdown`
+                : `copy failed: ${result.reason}`;
+            renderDetails();
         },
         setPrompt(next) {
             prompt = next;
@@ -395,10 +695,18 @@ export function startDevStreamRenderer(opts) {
             drawStatus();
         },
         stop() {
+            stopped = true;
             unsubscribe();
             if (statusEnabled && typeof stderr.off === 'function') {
                 stderr.off('resize', onResize);
             }
+            if (details) {
+                // Never leave the terminal stranded in the alternate screen.
+                details = undefined;
+                statusShown = false;
+                stderr.write(ALT_SCREEN_LEAVE);
+                return;
+            }
             eraseStatus();
         },
     };
@@ -412,6 +720,9 @@ function truncateRenderedEvent(rendered, maxLines, style) {
         `    ${style.dim(`… ${lines.length - maxLines + 1} more lines`)}`,
     ].join('\n');
 }
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
 function retainedCount(entries) {
     return entries.reduce((total, entry) => total + entry.count, 0);
 }