@cruxy/cli 1.11.0 → 1.11.2

package/dist/tui/renderer.js

@@ -13,7 +13,8 @@ import { CONVERSATION_VIEW, cycleView, navLines, } from "./views.js";
 import { contextPanelLines, gitPanelLines, headerModel, mainWelcome, modelPanelLines, railBlocks, sidebarLines, toolsPanelLines, } from "./panels.js";
 import { limitsPanelLines } from "./limits-panel.js";
 import { installScreenGuard, } from "./restore.js";
-import { usesAltScreen } from "./supports.js";
+import { usesAltScreen, usesMouse } from "./supports.js";
+import { logger } from "../utils/logger.js";
 /**
  * The full-viewport renderer (P1) — the fourth {@link StreamRenderer}, and the
  * only one that owns the whole screen rather than a single managed line.
@@ -46,8 +47,31 @@ import { usesAltScreen } from "./supports.js";
  * `renderInput`): the real cursor parks wherever the last painted row ended,
  * which is a second, wrong caret blinking somewhere in the frame.
  */
-const ENTER_ALT_SCREEN = "\x1b[?1049h\x1b[?25l";
-const LEAVE_ALT_SCREEN = "\x1b[?25h\x1b[?1049l";
+export const ENTER_ALT_SCREEN = "\x1b[?1049h\x1b[?25l";
+export const LEAVE_ALT_SCREEN = "\x1b[?25h\x1b[?1049l";
+/**
+ * Mouse reporting on and off (cli#1): `?1000h` (button events) in the
+ * `?1006h` (SGR) encoding, and the inverse in reverse order.
+ *
+ * Without it the terminal handles the wheel itself, and on the alternate
+ * screen that means one of two wrong things: Terminal.app scrolls the WINDOW
+ * over a buffer that has no scrollback, and iTerm2 translates each notch into
+ * arrow keys, which `app.ts` deliberately leaves inert. With it, a notch
+ * arrives as a key the loop can map onto the scroll Page Up already has.
+ *
+ * WRITTEN IN THE SAME BYTES as the alternate-screen pair — appended to the
+ * enter, prepended to the leave — and nowhere else, because of what it costs
+ * when left on: a terminal in mouse-reporting mode after the process is gone
+ * turns every click into escape bytes at the shell prompt. That pair is what
+ * the restore guard replays on a signal, so the mouse is released on exactly
+ * the paths the screen is.
+ *
+ * The known trade is that native text selection needs the terminal's modifier
+ * (Shift, or Option in Terminal.app) while the TUI is up — the trade `less` and
+ * `vim` make. `CRUXY_NO_MOUSE` opts out of just this (see `usesMouse`).
+ */
+export const MOUSE_ON = "\x1b[?1000h\x1b[?1006h";
+export const MOUSE_OFF = "\x1b[?1006l\x1b[?1000l";
 /** Coalescing window for repaints (~30fps). */
 export const PAINT_INTERVAL_MS = 33;
 /**
@@ -82,6 +106,19 @@ export const VIEW_PULSE_MS = 500;
 export const SCROLLBACK_LINES = 1_000;
 /** Lines a Page Up/Down keeps in common across the jump, so context survives. */
 export const SCROLL_PAGE_OVERLAP = 2;
+/**
+ * Display lines one wheel notch scrolls (cli#1). Three is what most terminals
+ * and pagers move per notch; a whole page per notch would make the wheel a
+ * coarser Page Up rather than the fine control it is everywhere else.
+ */
+export const WHEEL_LINES = 3;
+/**
+ * The most rows a view gives up to command output pinned beneath it (cli#7b),
+ * as a fraction of the pane. Half: the view stays readable, and `/help` — the
+ * longest thing this carries — still shows most of itself, with the notice row
+ * saying where the rest is.
+ */
+export const NOTICE_ROWS_FRACTION = 0.5;
 export class TuiRenderer {
     caps;
     theme;
@@ -95,6 +132,8 @@ export class TuiRenderer {
     guard;
     /** Whether this renderer took the alternate screen and owes the inverse. */
     altScreen;
+    /** Whether it turned mouse reporting on with it, and owes that inverse too. */
+    mouse;
     /** Lines the opening banner occupies — the buffer's contents at construction. */
     openingLines;
     /** Logical lines committed since construction, INCLUDING ones rolled off. */
@@ -130,6 +169,15 @@ export class TuiRenderer {
     views = [];
     /** Which view owns the main column. Always a real id — see {@link setView}. */
     selectedView = CONVERSATION_VIEW;
+    /**
+     * App-authored lines printed while a view other than the conversation owned
+     * the main column (cli#7b), pinned under that view until the user moves on.
+     * Every one of them is ALSO in the scrollback: this is a second showing, not
+     * a second home. Empty whenever the conversation is selected.
+     */
+    notices = [];
+    /** Hands the console back to the logger; see the constructor. */
+    releaseLogger = null;
     /** Whether the sidebar nav holds the keyboard rather than the input line. */
     sidebarFocused = false;
     /** Working-tree state for the git panel (P4 track 2); absent → panel unwired. */
@@ -205,8 +253,9 @@ export class TuiRenderer {
         // The inverse is owed from this line onward, which is why track 1 landed
         // first: `close()` is not the only way out of this constructor's reach.
         this.altScreen = opts.altScreen ?? usesAltScreen(caps);
+        this.mouse = this.altScreen && (opts.mouse ?? usesMouse(caps));
         if (this.altScreen)
-            out.write(ENTER_ALT_SCREEN);
+            out.write(ENTER_ALT_SCREEN + (this.mouse ? MOUSE_ON : ""));
         // ABSOLUTE rows (Q4 track 2). This renderer owns the viewport outright, so
         // it has no reason to infer where its rows are from where the cursor was
         // left — and every reason not to. A frame this tall repaints thirty times a
@@ -216,6 +265,16 @@ export class TuiRenderer {
         this.frame = createFrame((text) => this.out.write(text), caps, {
             absolute: true,
         });
+        // THE LOGGER WRITES INTO THIS FRAME from here on (cli#1, the second
+        // contributor). Both standard streams are this terminal, and a diagnostic
+        // written to stderr while the frame owns every row lands inside it: the
+        // retention notice at boot did, and a hook's or an MCP server's warning
+        // mid-turn does. Routed through `println` they are conversation lines —
+        // visible, scrollable, and pinned under a view like any other command
+        // output — instead of bytes the next repaint erases. Released with the
+        // screen, in `releaseScreen`, so the exit path's own prints reach the
+        // normal buffer.
+        this.releaseLogger = logger.capture((_channel, text) => this.println(text));
         // Installed here, not in `close()`'s vicinity, because the window it covers
         // opens with the first paint: from this line on there is a shell on screen
         // that only this object knows how to take down.
@@ -414,9 +473,24 @@ export class TuiRenderer {
             return true;
         this.selectedView = id;
         this.scrollOffset = 0;
+        // Notices belong to the view they were pinned under. Leaving it — for the
+        // conversation, which holds them all anyway, or for another view — drops
+        // them, so a "showing git" cannot follow the user onto the tasks pane.
+        this.notices = [];
         this.schedulePaint();
         return true;
     }
+    /**
+     * Drop the command output pinned under the selected view (cli#7b). The app
+     * calls this when a line is submitted: the user has moved on, and the next
+     * command's output must not stack under the last one's.
+     */
+    dismissNotices() {
+        if (this.closed || this.notices.length === 0)
+            return;
+        this.notices = [];
+        this.schedulePaint();
+    }
     /** Move `steps` around the view ring and select what lands. */
     cycleView(steps) {
         const next = cycleView(this.selectedView, this.views, steps);
@@ -561,11 +635,42 @@ export class TuiRenderer {
     overlayWidth() {
         return this.viewportWidth();
     }
-    /** Append an app-authored line to the conversation (help text, command replies). */
+    /**
+     * Append an app-authored line to the conversation (help text, command
+     * replies, a routed diagnostic).
+     *
+     * WHILE A VIEW HIDES THE CONVERSATION the line is also pinned under that view
+     * (cli#7b). Before this, `/help`, `/view`'s listing, a Tab completion's
+     * suggestions and the "showing …" confirmation all went into a buffer the
+     * screen was not showing, and the command read as having done nothing. The
+     * conversation stays the record; the view keeps the column; the line is
+     * simply shown where the user is looking.
+     */
     println(line = "") {
         if (this.closed)
             return;
         this.pushLines([line]);
+        if (this.selectedView !== CONVERSATION_VIEW)
+            this.notices.push(line);
+        this.schedulePaint();
+    }
+    /**
+     * Empty the scrollback (cli#2) — the visible half of `/clear`.
+     *
+     * `Session.clear` empties the history the model sees and the log records the
+     * event, and both were always right. What stayed wrong was the screen: the
+     * whole transcript remained above a muted "history cleared", so a reset that
+     * had worked read as one that had not. The buffer goes, the partial line
+     * goes, the scroll position goes; `committed` stays, because the exit tail's
+     * "N earlier lines" counts what was ever shown, and these were.
+     */
+    clearScrollback() {
+        if (this.closed)
+            return;
+        this.buffer = [];
+        this.partial = "";
+        this.notices = [];
+        this.scrollOffset = 0;
         this.schedulePaint();
     }
     // ── StreamRenderer ────────────────────────────────────────────────────────
@@ -880,12 +985,16 @@ export class TuiRenderer {
      * handed over.
      */
     releaseScreen() {
+        // The console comes back first, so anything the exit path logs after this
+        // line reaches the terminal rather than a renderer that is closing.
+        this.releaseLogger?.();
+        this.releaseLogger = null;
         this.closed = true;
         this.frame.clear();
         // The exact inverse of the constructor's pair, and the last bytes this
         // renderer ever writes to the managed screen.
         if (this.altScreen)
-            this.out.write(LEAVE_ALT_SCREEN);
+            this.out.write((this.mouse ? MOUSE_OFF : "") + LEAVE_ALT_SCREEN);
     }
     /**
      * Echo the tail of the conversation into the normal buffer (Q4 track 3).
@@ -1306,10 +1415,21 @@ export class TuiRenderer {
         // A view's lines are reflowed here rather than trusted at `mainCols`: the
         // contract asks a view to lay out to the width it is given, and reflow makes
         // that a courtesy rather than a rule it can break the grid by ignoring.
+        //
+        // Command output pinned under a view (cli#7b) rides the same rule the plan
+        // checklist does under the conversation: appended, so the column's tail
+        // rule keeps it on screen, and capped so it cannot evict the view. When the
+        // cap cuts it, the first pinned row says how much is above and where it
+        // all is — the conversation, one Esc away. Absent while scrolled, like the
+        // plan, so a reader holding history still is not moved by it.
+        const notices = active === undefined || scrolled ? [] : this.noticeBlock(rows, mainCols);
         const body = active !== undefined
-            ? active
-                .lines(this.theme, mainCols)
-                .flatMap((line) => (line === "" ? [""] : reflow(line, mainCols)))
+            ? [
+                ...active
+                    .lines(this.theme, mainCols)
+                    .flatMap((line) => (line === "" ? [""] : reflow(line, mainCols))),
+                ...(notices.length === 0 ? [] : ["", ...notices]),
+            ]
             : plan.length === 0
                 ? wrapped
                 : [...wrapped, "", ...plan];
@@ -1337,11 +1457,13 @@ export class TuiRenderer {
             // one because they answer different questions — "where am I" and "what
             // else have I run" — and because the sessions list is destined to become
             // a view of its own, at which point this reduces to the nav.
-            sidebar: [
-                ...navLines(this.theme, this.views, this.selectedView, this.sidebarFocused),
-                "",
-                ...sidebarLines(this.theme, this.sessions, this.activeSessionId),
-            ],
+            //
+            // Composed to the row budget HERE (cli#7a), the way the rail is: the nav
+            // takes what it needs, the list gets what is left. Handing the layout an
+            // over-long column and letting its tail rule cut it was what removed the
+            // nav heading and the first view rows at 30 rows — and with them the
+            // pointer Ctrl+B was moving.
+            sidebar: this.sidebarBlock(rows),
             main,
             rail: stacked.lines,
             status: this.statusLine(width),
@@ -1349,6 +1471,57 @@ export class TuiRenderer {
             overlay: drawer,
         };
     }
+    /**
+     * The sidebar column, fitted to `rows` (cli#7a): the nav whole, then the
+     * session list in whatever remains, with one blank row between them when
+     * there is room for both. The nav is never cut here — `fitHead` in the
+     * layout trims it only on a terminal too short to hold it at all.
+     */
+    sidebarBlock(rows) {
+        const nav = navLines(this.theme, this.views, this.selectedView, this.sidebarFocused);
+        const remaining = rows - nav.length - 1;
+        if (remaining <= 0)
+            return nav;
+        return [
+            ...nav,
+            "",
+            ...sidebarLines(this.theme, this.sessions, this.activeSessionId, Date.now(), remaining),
+        ];
+    }
+    /**
+     * The pinned command output for the selected view, wrapped at the column
+     * width and capped at {@link NOTICE_ROWS_FRACTION} of the pane. The cap
+     * keeps the NEWEST rows — the most recent command's output is the one just
+     * asked for — and charges its first row to say what was cut.
+     */
+    noticeBlock(rows, cols) {
+        if (this.notices.length === 0)
+            return [];
+        const wrapped = [];
+        for (const line of this.notices) {
+            if (line === "")
+                wrapped.push("");
+            else
+                wrapped.push(...reflow(line, cols));
+        }
+        const cap = Math.max(1, Math.floor(rows * NOTICE_ROWS_FRACTION));
+        if (wrapped.length <= cap)
+            return wrapped;
+        const shown = Math.max(0, cap - 1);
+        const hidden = wrapped.length - shown;
+        return [
+            noticeOverflow(hidden, this.theme),
+            ...wrapped.slice(wrapped.length - shown),
+        ];
+    }
+}
+/**
+ * The heading row a pinned-notice block spends when it cannot show every line.
+ * Short enough to survive the narrowest main column (36 at 80 wide with both
+ * side columns up): a marker truncated mid-word would not name the way out.
+ */
+function noticeOverflow(hidden, theme) {
+    return theme.muted(`${theme.glyph.ellipsis}${hidden} more above${theme.sep}Esc to see all`);
 }
 /** Row-wise equality for overlay content — `null` and `[]` both mean "no drawer". */
 function sameLines(a, b) {

package/dist/tui/supports.js

@@ -40,3 +40,18 @@ export function supportsTui(caps) {
 export function usesAltScreen(caps, env = process.env) {
     return supportsTui(caps) && !isSet(env.CRUXY_NO_ALT_SCREEN);
 }
+/**
+ * Whether the TUI turns MOUSE REPORTING on (cli#1), so the wheel scrolls the
+ * pane instead of the terminal's window.
+ *
+ * Gated on {@link usesAltScreen}: the mouse is enabled and released in the
+ * same byte pair as the alternate screen, and there is no pair to ride without
+ * it. `CRUXY_NO_MOUSE` opts out on its own, same set-and-non-empty rule,
+ * because reporting has a cost the alternate screen does not: while it is on,
+ * native text selection needs the terminal's modifier (Shift, or Option in
+ * Terminal.app). Someone who selects text constantly can turn the wheel off
+ * without giving up the TUI.
+ */
+export function usesMouse(caps, env = process.env) {
+    return usesAltScreen(caps, env) && !isSet(env.CRUXY_NO_MOUSE);
+}

package/dist/utils/logger.js

@@ -1,3 +1,4 @@
+import { format } from "node:util";
 import { shouldUseColor } from "../errors/format.js";
 import { themeForColor } from "../theme/index.js";
 export const LOG_LEVELS = ["debug", "info", "warn", "error", "silent"];
@@ -12,6 +13,48 @@ class Logger {
     level = "info";
     /** Diagnostics go to stderr, so the theme resolves against stderr's color. */
     theme = themeForColor(shouldUseColor(process.stderr));
+    /** The surface that currently owns the terminal, or null for the console. */
+    sink = null;
+    /**
+     * Route every line through `sink` instead of the console, until the returned
+     * release is called.
+     *
+     * This exists for the full-screen TUI. While it is up, the frame owns every
+     * row of the terminal and BOTH standard streams point at that same terminal —
+     * so a `warn` written to stderr does not go "to the side", it lands inside
+     * the frame at wherever the cursor was parked, and the next repaint erases
+     * it. The retention notice at boot, a hook's announcement and an MCP server's
+     * failure mid-turn all did exactly that. The renderer installs itself here
+     * for as long as it holds the screen and hands the console back when it
+     * releases it, on the clean path and the signal path alike.
+     *
+     * The level filter still applies: a captured `debug` is dropped at the
+     * default level just as an uncaptured one is. Only the destination changes.
+     *
+     * The release is a no-op once a later capture has replaced this one, so two
+     * surfaces releasing out of order cannot strand the console.
+     */
+    capture(sink) {
+        this.sink = sink;
+        return () => {
+            if (this.sink === sink)
+                this.sink = null;
+        };
+    }
+    /** Whether a surface has captured the streams. */
+    captured() {
+        return this.sink !== null;
+    }
+    emit(channel, args) {
+        if (this.sink !== null) {
+            this.sink(channel, format(...args));
+            return;
+        }
+        if (channel === "print")
+            console.log(...args);
+        else
+            console.error(...args);
+    }
     setLevel(level) {
         this.level = level;
     }
@@ -23,23 +66,26 @@ class Logger {
     }
     debug(...args) {
         if (this.enabled("debug"))
-            console.error(this.theme.muted("debug"), ...args);
+            this.emit("debug", [this.theme.muted("debug"), ...args]);
     }
     info(...args) {
         if (this.enabled("info"))
-            console.error(...args);
+            this.emit("info", args);
     }
     warn(...args) {
         if (this.enabled("warn"))
-            console.error(this.theme.warning("warn"), ...args);
+            this.emit("warn", [this.theme.warning("warn"), ...args]);
     }
     error(...args) {
         if (this.enabled("error"))
-            console.error(this.theme.danger("error"), ...args);
+            this.emit("error", [this.theme.danger("error"), ...args]);
     }
-    /** Primary user-facing output — always written to stdout. */
+    /**
+     * Primary user-facing output — stdout, or the capturing surface while one
+     * holds the screen (stdout IS that screen).
+     */
     print(...args) {
-        console.log(...args);
+        this.emit("print", args);
     }
 }
 export const logger = new Logger();

package/dist/utils/process-owner.js

@@ -0,0 +1,107 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+/** The token when the platform lookup failed: liveness falls back to pid-only. */
+export const UNKNOWN_TOKEN = "unknown";
+/** The start-time token for `pid`, or {@link UNKNOWN_TOKEN} when unobtainable. */
+export function startToken(pid) {
+    try {
+        if (process.platform === "linux")
+            return linuxToken(pid);
+        if (process.platform === "darwin")
+            return darwinToken(pid);
+        if (process.platform === "win32")
+            return win32Token(pid);
+    }
+    catch {
+        // fall through — the platform said no; degrade to pid-only
+    }
+    return UNKNOWN_TOKEN;
+}
+/** This process's own stamp. Computed once — a process's identity never changes. */
+export function selfStamp() {
+    if (!self) {
+        self = {
+            pid: process.pid,
+            token: startToken(process.pid),
+            startedAt: new Date(Date.now() - process.uptime() * 1000).toISOString(),
+        };
+    }
+    return self;
+}
+let self;
+/** Whether a process with `pid` exists (EPERM counts: it exists, just not ours). */
+export function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/**
+ * Classify a stamp against the live process table. Order matters: `self` is
+ * decided by pid AND token, so a stamp our own pid inherited from a crashed
+ * predecessor (pid recycled onto us) still reads as stale.
+ */
+export function describeOwner(stamp) {
+    const me = selfStamp();
+    if (stamp.pid === me.pid) {
+        return stamp.token === me.token ? "self" : "stale";
+    }
+    if (!pidAlive(stamp.pid))
+        return "stale";
+    // Alive by pid. If both sides have a real token and they differ, the pid was
+    // recycled. An unknown token on either side cannot prove that, so the stamp
+    // is treated as live — the documented pid-only degradation.
+    if (stamp.token === UNKNOWN_TOKEN)
+        return "live";
+    const now = startToken(stamp.pid);
+    if (now === UNKNOWN_TOKEN)
+        return "live";
+    return now === stamp.token ? "live" : "stale";
+}
+// ── platform lookups ──────────────────────────────────────────────────────────
+function linuxToken(pid) {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    // The comm field is parenthesised and may itself contain spaces or parens;
+    // everything after the LAST `)` is the fixed-position numeric tail, in which
+    // starttime is the 20th entry (field 22 of the whole line).
+    const tail = stat
+        .slice(stat.lastIndexOf(")") + 2)
+        .trim()
+        .split(/\s+/);
+    const starttime = tail[19];
+    if (!starttime)
+        throw new Error("unexpected /proc stat shape");
+    let boot = "";
+    try {
+        boot = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+    }
+    catch {
+        // Older kernels / locked-down containers: the token is still per-boot in
+        // practice (ticks since boot), just not provably so across reboots.
+    }
+    return `linux:${boot}:${starttime}`;
+}
+function darwinToken(pid) {
+    const out = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 2000,
+    }).trim();
+    if (out === "")
+        throw new Error("no such process");
+    return `darwin:${out.replace(/\s+/g, " ")}`;
+}
+function win32Token(pid) {
+    const out = execFileSync("powershell", [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToString('o')`,
+    ], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 }).trim();
+    if (out === "")
+        throw new Error("no such process");
+    return `win32:${out}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "1.11.0",
+  "version": "1.11.2",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {
@@ -32,8 +32,9 @@
     "commander": "^12.1.0",
     "fastembed": "^2.1.0",
     "picocolors": "^1.1.1",
+    "tar": "^7.5.22",
     "tinyglobby": "^0.2.10",
-    "undici": "^6.21.0",
+    "undici": "^6.28.1",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.5",
     "@cruxy/sdk": "0.8.0"