nexrall-code 0.5.106 → 0.5.108

package/dist/ui/resizeRepaint.js

@@ -0,0 +1,36 @@
+const defaultDeps = {
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+/**
+ * Fires `onSettle` once, `settleMs` after the LAST `notify()` call — i.e.
+ * once resize events have stopped arriving for that long. Any `notify()`
+ * that arrives before the window elapses restarts it, so a continuous drag
+ * (events firing every few milliseconds) never triggers `onSettle` until the
+ * user actually lets go.
+ *
+ * `deps` defaults to the real timers; tests inject fakes so the debounce
+ * window can be exercised deterministically without real elapsed time.
+ */
+export function createResizeDebouncer(settleMs, onSettle, deps = defaultDeps) {
+    let timer = null;
+    let disposed = false;
+    const notify = () => {
+        if (disposed)
+            return;
+        if (timer !== null)
+            deps.clearTimeout(timer);
+        timer = deps.setTimeout(() => {
+            timer = null;
+            onSettle();
+        }, settleMs);
+    };
+    const dispose = () => {
+        disposed = true;
+        if (timer !== null) {
+            deps.clearTimeout(timer);
+            timer = null;
+        }
+    };
+    return { notify, dispose };
+}

package/dist/ui/screen.js

@@ -0,0 +1,482 @@
+import chalk from 'chalk';
+import { visibleLen, padVis } from './theme';
+// ─── Session Screen Setup ──────────────────────────────────────────────────
+//
+// The session runs in the terminal's NORMAL screen buffer, and starts by
+// clearing both the screen and the scrollback. It deliberately does NOT use
+// the alternate screen buffer (\x1b[?1049h) that vim/less/htop use, which is
+// what this did previously.
+//
+// The alternate buffer is the wrong tool for a scrolling chat transcript, for
+// two reasons that show up immediately in normal use:
+//
+//   • It has no scrollback of its own. Once the conversation grows past one
+//     screenful the earlier turns — and the banner — are gone for good, not
+//     merely off-screen. There is nothing to scroll back to.
+//   • Because it doesn't scroll, terminals including macOS Terminal.app route
+//     a mouse-wheel scroll to the MAIN buffer sitting underneath instead. So
+//     scrolling up during a session shows whatever was on screen before `nex`
+//     started — typically a stack of empty `user@host ~ %` shell prompts —
+//     which is precisely the reported symptom.
+//
+// Clearing the normal buffer instead gives the desired behaviour directly and
+// with far less machinery: the session begins on a blank screen with the
+// banner at the top, and as the conversation grows it scrolls naturally, so
+// scrolling up reveals the banner and earlier turns and nothing else —
+// because after the clear that is genuinely all the scrollback contains.
+//
+// It also means the session's output is still there after exit, which is
+// usually what you want from a CLI (you can scroll back to what the agent
+// said), whereas the alternate buffer discarded all of it on quit.
+//
+// \x1b[2J clears the visible screen; \x1b[3J clears the scrollback (xterm's
+// XTCLEARSB — supported by Terminal.app, iTerm2, Ghostty, kitty, WezTerm,
+// VS Code's terminal and Windows Terminal); \x1b[H then homes the cursor so
+// output starts at row 1 rather than wherever the shell prompt left it.
+// Terminals that don't implement 3J simply keep their scrollback: the session
+// still renders correctly, it just doesn't get the clean-slate scrollback.
+export function prepareSessionScreen() {
+    if (!process.stdout.isTTY)
+        return;
+    process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+}
+// ─── Pinning the bottom chrome to the last row ─────────────────────────────
+/**
+ * Rows Ink's persistent bottom chrome occupies: top separator, input line,
+ * bottom separator, footer.
+ *
+ * This is the MINIMUM (one row each) — it is only correct while every one of
+ * those four rows fits on a single terminal line. Prefer bottomChromeRows()
+ * below, which accounts for the two ways that assumption breaks.
+ */
+export const BOTTOM_CHROME_ROWS = 4;
+/**
+ * Rows the bottom chrome ACTUALLY occupies, given the terminal width and the
+ * text currently in the input box.
+ *
+ * `BOTTOM_CHROME_ROWS` is a hardcoded 4, which silently under-counts in two
+ * situations that are both easy to hit — and under-counting makes padToBottom
+ * push the chrome PAST the last row, scrolling the top of the banner away:
+ *
+ *   • A narrow terminal wraps the footer. The footer string
+ *     ("auto mode on · /help for shortcuts · /agents for agents") is 55 cells,
+ *     so at any width below ~56 columns it takes two rows, not one — measured
+ *     at 40 columns: actual chrome 5, constant 4.
+ *   • Shift+Enter puts real newlines IN the input line (a feature this same
+ *     UI added), so the input row becomes as many rows as there are lines —
+ *     measured: one Shift+Enter → 5, three → 7, against a constant of 4.
+ *
+ * Deriving the number from the same strings the component renders means the
+ * two cannot drift apart the way a hand-maintained constant did.
+ */
+export function bottomChromeRows(opts = {
+    footerText: '',
+}) {
+    const columns = opts.columns ?? process.stdout.columns ?? 80;
+    // Two full-width rules now bound the input box: one above (existing) and
+    // one below (added so the footer hints sit visually separated from the
+    // input, matching the separator already drawn above the box) — see
+    // inkTerminal.tsx's second <Box borderBottom> rule.
+    const separatorRows = 2;
+    const inputRows = rowsOccupied(' '.repeat(opts.promptWidth ?? 2) + (opts.inputText ?? ''), columns);
+    const footerRows = rowsOccupied(opts.footerText, columns);
+    return separatorRows + inputRows + footerRows;
+}
+/**
+ * Terminal rows a printed string occupies, accounting for long lines
+ * soft-wrapping at the terminal's width. Counting '\n' alone undercounts (and
+ * so under-pads) whenever a line is wider than the terminal — e.g. a long
+ * working-directory path on a narrow window. Measured in cells via visibleLen,
+ * so CJK and emoji are counted correctly.
+ */
+export function rowsOccupied(text, columns = process.stdout.columns || 80) {
+    let rows = 0;
+    for (const line of text.split('\n')) {
+        const width = visibleLen(line);
+        rows += width === 0 ? 1 : Math.ceil(width / columns);
+    }
+    return rows;
+}
+/**
+ * Pure row-count arithmetic behind padToBottom() below — extracted so callers
+ * that need to RECOMPUTE the same filler amount without printing anything can
+ * do so. This exists for exactly one reason: inkTerminal.tsx's
+ * `forceFullRedraw` (resize) and `collapseStartupPadding` both raw-clear the
+ * screen (`\x1b[2J\x1b[H`) and remount `<Static>`, which replays only what is
+ * in the `items` array — any padding padToBottom printed via plain
+ * `console.log` is NOT in `items`, so it is wiped by that clear and never
+ * replayed, leaving the chrome stranded wherever the replayed items end
+ * instead of at the last row (this was a real, reproducible bug: verified via
+ * pty capture that the footer floated mid-screen, sometimes permanently, on
+ * both the very first resize AND the very first message of every session,
+ * because both paths share this exact redraw mechanism). The fix is for
+ * those callers to push a FILLER ITEM into `items` itself instead of calling
+ * `console.log` — see inkTerminal.tsx's `repadBottomChrome` — which requires
+ * the same arithmetic padToBottom uses, minus the actual printing.
+ *
+ * See padToBottom's own doc for why every constant below is what it is —
+ * this is the identical math, just factored out so both call sites can't
+ * drift apart the way a second hand-copied formula would.
+ */
+export function fillerRowCount(rowsAlreadyPrinted, footerTextValue = '', columns = process.stdout.columns ?? 80, rows = process.stdout.rows) {
+    if (!rows)
+        return 0;
+    // Two rows of headroom, not one. The first is the cursor row Ink keeps
+    // below its frame. The second is a safety margin: the tally can only measure
+    // what went through console.log, and mis-counting by even one row overflows
+    // the viewport and scrolls the top of the banner away permanently. Erring
+    // one row short is invisible (the footer sits one line above the bottom);
+    // erring one row long destroys the banner. The asymmetry justifies the
+    // margin.
+    //
+    // The chrome height is MEASURED (bottomChromeRows) rather than assumed to be
+    // 3: on a terminal narrower than the footer string the footer wraps onto a
+    // second row, and the old constant then under-counted by one and pushed the
+    // banner's top row off the screen. The input box is empty at startup, which
+    // is when this runs, so only the footer can wrap here.
+    const chromeRows = bottomChromeRows({ footerText: footerTextValue, columns });
+    const filler = rows - rowsAlreadyPrinted - chromeRows - 2;
+    // Skip padding entirely unless there is a comfortable amount of slack.
+    //
+    // When startup output nearly fills the terminal there is no gap worth
+    // closing, but there IS a real risk: any timing jitter in Ink's frame
+    // commits can then push the total one row past the viewport and scroll the
+    // banner's top away. Measured on a 24-row terminal, where startup already
+    // occupies 21 rows, padding failed roughly 1 run in 8 for exactly this
+    // reason, while adding at most two blank rows of benefit.
+    //
+    // The padding exists to close an 8-19 row gap on a roomy terminal. Below
+    // this threshold the gap is already negligible, so declining to pad trades
+    // nothing for determinism.
+    const MIN_WORTHWHILE_FILLER = 3;
+    return filler < MIN_WORTHWHILE_FILLER ? 0 : filler;
+}
+/**
+ * Prints blank rows so the input line and footer come to rest on the LAST row
+ * of the terminal, instead of floating directly beneath the banner with dead
+ * space below them.
+ *
+ * The blanks MUST go through `console.log`, not `process.stdout.write`. Ink
+ * patches console.log (patchConsole) to erase its current frame, emit the
+ * line above it, then repaint the frame below — which is exactly the "push
+ * the chrome down" behaviour wanted. A raw stdout write bypasses that
+ * bookkeeping: the text lands wherever the cursor happens to be, Ink's idea
+ * of its own frame position goes stale, and the next repaint draws the
+ * chrome back over the padding. An earlier attempt did precisely this and
+ * left the footer stranded mid-screen.
+ *
+ * This runs once at startup. Once the conversation grows past one screenful
+ * the padding is irrelevant: content then fills the viewport and the chrome
+ * stays on the last row through ordinary terminal scrolling (verified by
+ * streaming 30 lines after padding — the footer did not move).
+ *
+ * Returns whether it actually printed filler rows. A terminal is append-only:
+ * these blank rows can never be "filled in" by later output, only appended
+ * after — so the caller (chat.ts) uses this to know whether it must later
+ * collapse them via inkTerminal.tsx's `collapseStartupPadding()` once real
+ * conversation content starts, instead of leaving them permanently wedged
+ * between the banner and the first turn (see that function's own doc for the
+ * full mechanism and the pty capture that found this).
+ */
+export function padToBottom(rowsAlreadyPrinted, footerText = '') {
+    if (!process.stdout.isTTY)
+        return false;
+    const filler = fillerRowCount(rowsAlreadyPrinted, footerText);
+    if (filler <= 0)
+        return false;
+    // Emitted as ONE console.log, not `filler` separate calls. Ink's patched
+    // console.log erases its frame, writes the line, then repaints the frame
+    // below — so N calls mean N erase/repaint cycles in a tight loop, and on
+    // taller terminals the incremental erase falls behind, leaving stray
+    // separator fragments on screen and scrolling the banner's top row away.
+    // A single call is one erase/repaint for the whole block.
+    //
+    // console.log appends its own trailing newline, so `filler - 1` newlines
+    // produce exactly `filler` rows.
+    console.log('\n'.repeat(filler - 1));
+    return true;
+}
+/**
+ * Tallies the terminal rows consumed by everything written through
+ * `console.log` between `startRowCount()` and `stopRowCount()`.
+ *
+ * Startup output is conditional in several places — permission rules, loaded
+ * skills, connected MCP servers, resumed-session notices — so a hardcoded
+ * "the banner is N rows tall" constant would drift out of date the next time
+ * one of those notices is added or reworded, silently breaking the alignment
+ * again. Measuring what was actually printed cannot drift.
+ *
+ * Must be started AFTER Ink's render() has run: patchConsole replaces
+ * console.log at that point, and starting first would have Ink's patch
+ * overwrite the counting wrapper, leaving the count at zero.
+ */
+let rowCounter = null;
+export function startRowCount() {
+    if (rowCounter)
+        return;
+    const columns = process.stdout.columns || 80;
+    const originalLog = console.log;
+    const originalError = console.error;
+    const state = { rows: 0, originalLog, originalError };
+    rowCounter = state;
+    // console.log() with no arguments prints a single blank line.
+    const measure = (args) => args.length === 0 ? 1 : rowsOccupied(args.map(String).join(' '), columns);
+    console.log = (...args) => {
+        state.rows += measure(args);
+        originalLog(...args);
+    };
+    // console.error is counted too, and it is not a theoretical case: Ink patches
+    // BOTH (patchConsole), so an error printed during startup lands on screen and
+    // pushes the chrome down exactly like a console.log does — but it used to go
+    // untallied, so padToBottom under-measured and over-padded.
+    //
+    // Startup really does write here. A failing MCP server logs
+    // `[MCP] Failed to connect to server "…": …` via console.error, and it is
+    // long: measured at 277 characters, which is 3 rows at 100 columns, none of
+    // which the tally saw. Every startup error path (session-not-found, compact
+    // failures) has the same shape.
+    console.error = (...args) => {
+        state.rows += measure(args);
+        originalError(...args);
+    };
+}
+/** Stops tallying and returns the row count. Safe to call when not started. */
+export function stopRowCount() {
+    if (!rowCounter)
+        return 0;
+    const { rows, originalLog, originalError } = rowCounter;
+    console.log = originalLog;
+    console.error = originalError;
+    rowCounter = null;
+    return rows;
+}
+/**
+ * Manually adds `text`'s row height to the running tally, for output that
+ * bypasses console.log/console.error entirely and so is invisible to the
+ * patched functions above.
+ *
+ * The interactive-path welcome banner is exactly this case: it goes through
+ * `getInkTerminal()!.print()` (an Ink `<Static>` list item, so it can be
+ * regenerated on resize — see setBannerRegenerator's doc), never through
+ * console.log. Before this existed, padToBottom() was blind to the banner's
+ * ~15-18 rows entirely: it only tallied the handful of console.log lines
+ * printed AFTER the banner (permission rules, skills, "Type a message…"),
+ * computed a filler far larger than the real gap, and pushed the input
+ * box/footer clean off the bottom of the viewport — scrolling the banner's
+ * own top rows away and leaving a large empty gap above the chrome. Callers
+ * must invoke this with the exact string passed to `print()`, immediately
+ * after printing it, so the count reflects what is really on screen.
+ *
+ * A no-op when counting hasn't started (mirrors stopRowCount's safety) so
+ * call sites don't need to guard on `interactive` themselves.
+ */
+export function addRowCount(text) {
+    if (!rowCounter)
+        return;
+    const columns = process.stdout.columns || 80;
+    rowCounter.rows += rowsOccupied(text, columns);
+}
+// ─── Welcome Banner (box-drawn "Welcome back" card) ────────────────────────
+//
+// Mirrors Claude Code's startup screen: a rounded box with version header,
+// centered greeting + logo on the left, "Tips" / "What's new" on the right.
+// Pure chalk + Unicode box-drawing — no React/Ink dependency needed here,
+// since this only runs ONCE at session start, before Ink's own render() has
+// booted (see chat.ts's startChatSession: the banner call is deliberately
+// ordered after startInkTerminal() so Ink's patchConsole picks it up like
+// any other console.log call).
+const NEX_LOGO = [
+    '███╗   ██╗███████╗██╗  ██╗',
+    '████╗  ██║██╔════╝╚██╗██╔╝',
+    '██╔██╗ ██║█████╗   ╚███╔╝ ',
+    '██║╚██╗██║██╔══╝   ██╔██╗ ',
+    '██║ ╚████║███████╗██╔╝ ██╗',
+    '╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝',
+];
+/** Center `s` (already chalk-styled OK) within visible width `w`. */
+function center(s, w) {
+    const len = visibleLen(s);
+    if (len >= w)
+        return s;
+    const left = Math.floor((w - len) / 2);
+    return ' '.repeat(left) + s;
+}
+// Both truncators below iterate over grapheme-ish units and measure with
+// visibleLen (terminal cells) rather than slicing by String index, so a
+// wide CJK character is never cut in half and a two-cell glyph is never
+// counted as one cell — either mistake would leave the column a cell over
+// budget and tear the frame.
+const graphemesOf = (s) => [...s];
+/** Trim `s` to at most `w` cells, marking the cut with a trailing ellipsis. */
+function truncateEnd(s, w) {
+    if (visibleLen(s) <= w)
+        return s;
+    let out = '';
+    for (const g of graphemesOf(s)) {
+        if (visibleLen(out + g) > w - 1)
+            break;
+        out += g;
+    }
+    return out + '…';
+}
+/**
+ * Trim `s` to at most `w` cells from the START, marking the cut with a leading
+ * ellipsis — used for filesystem paths, where the tail identifies the project
+ * and the head is usually a long, uninformative home-directory prefix.
+ */
+function truncateStart(s, w) {
+    if (visibleLen(s) <= w)
+        return s;
+    const gs = graphemesOf(s);
+    let out = '';
+    for (let i = gs.length - 1; i >= 0; i--) {
+        if (visibleLen(gs[i] + out) > w - 1)
+            break;
+        out = gs[i] + out;
+    }
+    return '…' + out;
+}
+/**
+ * Renders the two-column bordered welcome card. Returns the fully composed
+ * string (caller does the single console.log) so callers/tests can inspect
+ * it without capturing stdout.
+ */
+export function renderBanner(info) {
+    // ─── Geometry ────────────────────────────────────────────────────────────
+    //
+    // The card spans the FULL terminal width and is split into two columns by a
+    // vertical rule, so the layout is derived from the terminal size rather than
+    // from fixed column widths:
+    //
+    //   │ <left column> │ <right column> │
+    //   ^ ^             ^ ^              ^ ^
+    //   │ └ PAD         │ └ PAD          │ └ PAD (1 cell each side of a column)
+    //   └ frame         └ divider        └ frame
+    //
+    // Every row is exactly `totalW` cells, so the frame, the divider and the
+    // horizontal rules all line up by construction instead of by three separate
+    // hand-maintained arithmetic expressions that can drift apart (the previous
+    // revision's rules were 2 cells wider than its content rows for exactly
+    // that reason).
+    const PAD = 1;
+    // Non-content cells in a row: the 3 frame/divider glyphs (│ … │ … │) plus
+    // PAD cells on each side of each of the 2 columns — i.e. 4 pads, not 6.
+    // Overstating this by 2 made the card render 2 cells narrower than the
+    // terminal instead of spanning it fully.
+    const CHROME = 3 + 4 * PAD;
+    // The card spans the full terminal width. A floor keeps it from collapsing
+    // below what the logo plus a usable tips column need on a very narrow
+    // window — in that case the card is wider than the terminal and the
+    // terminal soft-wraps it, which is still more legible than a crushed or
+    // torn layout.
+    const LOGO_W = Math.max(...NEX_LOGO.map(visibleLen));
+    const termW = info.columns ?? process.stdout.columns ?? 100;
+    // One cell short of the terminal, for the same reason as the input
+    // separator in inkTerminal.tsx: a row that fills the final column makes many
+    // terminals wrap immediately, turning each banner row into two and doubling
+    // the card's height (which then scrolls its own top off the screen).
+    const totalW = Math.max(LOGO_W + CHROME + 24, termW - 1);
+    // The left column hugs its content (the logo is the widest fixed element);
+    // the right column takes everything that's left, so the divider sits at a
+    // stable position and the tips get the larger share on wide terminals.
+    const headerText = `Nexrall Code v${info.version}`;
+    const LEFT_W = Math.max(LOGO_W, visibleLen(headerText));
+    const RIGHT_W = totalW - CHROME - LEFT_W;
+    const leftLines = [];
+    leftLines.push(chalk.bold.hex('#3b82f6')('Nexrall Code ') + chalk.dim(`v${info.version}`));
+    leftLines.push('');
+    leftLines.push(center(chalk.bold(`Welcome back ${info.userLabel}!`), LEFT_W));
+    leftLines.push('');
+    // Logo lines are all LOGO_W wide and LEFT_W is >= LOGO_W, so centering here
+    // keeps the logo optically centred over the column without ever shifting it
+    // off the left edge.
+    for (const l of NEX_LOGO)
+        leftLines.push(center(chalk.hex('#3b82f6')(l), LEFT_W));
+    leftLines.push('');
+    // The left column is sized to the logo, so anything longer — most often a
+    // deeply nested working directory — has to be truncated or it would push
+    // past the divider and tear the frame. Paths are truncated from the LEFT so
+    // the meaningful tail (the project directory) survives.
+    leftLines.push(chalk.dim(truncateEnd(info.modelLabel, LEFT_W)));
+    leftLines.push(chalk.dim(truncateStart(info.workDir, LEFT_W)));
+    if (info.nexrallMdLoaded)
+        leftLines.push(chalk.dim('nexrall.md loaded'));
+    const rightLines = [];
+    rightLines.push(chalk.bold.yellow('Tips for getting started'));
+    const tips = info.tips ?? [
+        'Run /init to create a nexrall.md file with instructions for Nexrall Code.',
+        'Use /help to see all slash commands.',
+    ];
+    for (const t of tips)
+        rightLines.push(...wrapText(t, RIGHT_W));
+    const whatsNew = info.whatsNew ?? [];
+    if (whatsNew.length) {
+        rightLines.push('');
+        rightLines.push(chalk.bold.yellow("What's new"));
+        for (const t of whatsNew)
+            rightLines.push(...wrapText(t, RIGHT_W));
+        rightLines.push(chalk.dim.italic('/release-notes for more'));
+    }
+    const rowCount = Math.max(leftLines.length, rightLines.length);
+    // Nexrall brand blue — deliberately NOT Claude Code's orange (#d97757):
+    // this UI mirrors Claude Code's LAYOUT (box banner, two columns) but must
+    // stay visually distinct as Nexrall's own product.
+    const border = chalk.hex('#3b82f6');
+    // Each column's full span including its padding on both sides. The
+    // horizontal rules are built from these same two numbers as the content
+    // rows, so the T-junctions (┬ ┴) always land exactly on the divider (│)
+    // rather than being positioned by separate arithmetic that can drift.
+    const leftSpan = LEFT_W + PAD * 2;
+    const rightSpan = RIGHT_W + PAD * 2;
+    const pad = ' '.repeat(PAD);
+    const rule = (l, mid, r) => border(l + '─'.repeat(leftSpan) + mid + '─'.repeat(rightSpan) + r);
+    const lines = [];
+    lines.push(rule('╭', '┬', '╮'));
+    for (let i = 0; i < rowCount; i++) {
+        const l = padVis(leftLines[i] ?? '', LEFT_W);
+        const r = padVis(rightLines[i] ?? '', RIGHT_W);
+        lines.push(border('│') + pad + l + pad + border('│') + pad + r + pad + border('│'));
+    }
+    lines.push(rule('╰', '┴', '╯'));
+    return lines.join('\n');
+}
+/** Naive word-wrap that respects visible (ANSI-stripped) width. */
+function wrapText(text, width) {
+    const words = text.split(' ');
+    const out = [];
+    let cur = '';
+    for (const w of words) {
+        const candidate = cur ? cur + ' ' + w : w;
+        if (visibleLen(candidate) > width && cur) {
+            out.push(cur);
+            cur = w;
+        }
+        else {
+            cur = candidate;
+        }
+    }
+    if (cur)
+        out.push(cur);
+    // A single "word" longer than the column (a URL, or any run of CJK, which
+    // has no spaces to break on at all) can't be wrapped by the loop above and
+    // would otherwise overflow the column and tear the frame. Hard-break any
+    // such line at the column width.
+    const fitted = [];
+    for (const line of out) {
+        if (visibleLen(line) <= width) {
+            fitted.push(line);
+            continue;
+        }
+        let chunk = '';
+        for (const g of graphemesOf(line)) {
+            if (visibleLen(chunk + g) > width) {
+                fitted.push(chunk);
+                chunk = '';
+            }
+            chunk += g;
+        }
+        if (chunk)
+            fitted.push(chunk);
+    }
+    return fitted;
+}