@cruxy/cli 1.3.0 → 1.4.0

package/dist/tui/app.js

@@ -2,6 +2,7 @@ import { DEFAULT_MODE, MODE_LABELS, modeAutoApproves, } from "../agent/index.js"
 import { completeLine } from "../components/autocomplete.js";
 import { SHARED_COMMANDS, SHARED_HELP, announceMode, dispatchCommand, } from "../cli/session-commands.js";
 import { selectList } from "../components/select.js";
+import { viewLabel, viewOrder } from "./views.js";
 import { canOverlay, createKeyLease, createOverlayIO, } from "./overlay.js";
 import { openPalette } from "./palette.js";
 import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
@@ -41,6 +42,7 @@ export const TUI_COMMANDS = [
     ...SHARED_COMMANDS,
     "/close",
     "/open",
+    "/view",
 ].sort();
 const HELP = [
     "commands:",
@@ -48,9 +50,12 @@ const HELP = [
     "  /close <panel>   hide a panel (sidebar | context | model | git | tools)",
     "                   or a whole column (rail = all four rail panels)",
     "  /open <panel>    show a hidden panel",
+    "  /view [name]     show a main-pane view, or list them",
     "  Tab              complete a slash command",
     "  Ctrl+K           open the command palette",
+    "  Ctrl+B           focus the sidebar nav (arrows switch view, Esc leaves)",
     "  Shift+Tab        cycle mode (manual · auto-approve · plan · full-auto)",
+    "  PgUp / PgDn      scroll the pane; Esc returns to the live view",
     "  Ctrl+D           leave cruxy",
 ];
 /**
@@ -98,6 +103,43 @@ function panelArg(input, command) {
     const match = CLOSABLE_PANELS.find((p) => p === arg);
     return match ? { label: PANEL_LABELS[match], panels: [match] } : null;
 }
+/**
+ * Keys the focused sidebar nav claims (P7 track 2). Returns whether it took
+ * the key — anything it declines falls through to the input line untouched.
+ *
+ * The set is deliberately small. Up/down move the selection and Enter is not
+ * needed to commit it: selecting a view IS the action, and a two-step
+ * move-then-confirm would make the arrows do nothing visible on their own.
+ * Esc and Ctrl+B both hand the keyboard back, so the way out is whichever of
+ * the two the user reaches for first.
+ *
+ * A PRINTABLE CHARACTER RETURNS FOCUS AND IS NOT SWALLOWED. Someone who starts
+ * typing has stopped navigating, and losing the first letter of a prompt to a
+ * focus mode they forgot they were in is the failure that makes people stop
+ * using the binding.
+ */
+function handleNavKey(key, renderer) {
+    switch (key.kind) {
+        case "up":
+            renderer.cycleView(-1);
+            return true;
+        case "down":
+            renderer.cycleView(1);
+            return true;
+        case "escape":
+        case "ctrl-b":
+        case "enter":
+            renderer.focusSidebar(false);
+            return true;
+        case "char":
+            // Claim the focus change only; the character itself falls through to the
+            // editor on this same keypress.
+            renderer.focusSidebar(false);
+            return false;
+        default:
+            return false;
+    }
+}
 /**
  * Read one line from the TUI's input row. Takes raw stdin for the duration and
  * always releases it. Resolves `null` on Ctrl+D / EOF.
@@ -110,11 +152,27 @@ async function readLine(keys, renderer, hooks) {
     try {
         for (;;) {
             const key = await keys.read();
+            // FOCUS IS A ROUTING DECISION, resolved before the editor sees anything
+            // (P7 track 2). While the sidebar holds the keyboard the arrows move the
+            // view selection instead of the cursor — but only the keys that mean
+            // something there are claimed, so scrolling, the palette and the mode ring
+            // keep working exactly as they do at the input line. A view is persistent
+            // and NON-EXCLUSIVE; this is not a modal, and nothing here blocks.
+            if (renderer.sidebarHasFocus() && handleNavKey(key, renderer)) {
+                paint();
+                continue;
+            }
             switch (key.kind) {
                 case "enter": {
                     const text = editor.text;
                     editor.text = "";
                     editor.cursor = 0;
+                    // Submitting returns to the live view (P7 track 1). Scrollback holds
+                    // its position against output arriving on its own, which is the point
+                    // — but the user asking for that output is not "on its own", and
+                    // answering into a pane they cannot see is the one case where holding
+                    // still is wrong.
+                    renderer.scrollToLive();
                     paint();
                     return text;
                 }
@@ -205,9 +263,37 @@ async function readLine(keys, renderer, hooks) {
                     hooks.cycleMode();
                     paint();
                     break;
+                case "page-up":
+                case "page-down":
+                    // Scroll the conversation (P7 track 1). Like Shift+Tab, this leaves
+                    // the line being typed completely alone: reading back over what was
+                    // said is the most ordinary thing to do WHILE composing a reply, and
+                    // a scroll that cost the draft would be unusable for exactly that.
+                    //
+                    // No `paint()`: the input row has not changed, and the renderer
+                    // schedules its own repaint for the rows that did.
+                    renderer.scrollPage(key.kind === "page-up" ? 1 : -1);
+                    break;
+                case "escape":
+                    // Esc leaves the scrolled view — a mode needs a visible exit, and the
+                    // notice names this key. It stays inert at the live tail rather than
+                    // being claimed unconditionally, so the binding remains free for
+                    // whatever a later track wants Esc to mean when nothing is scrolled.
+                    renderer.scrollToLive();
+                    break;
+                case "ctrl-b":
+                    // Take the keyboard to the sidebar nav (P7 track 2). Refused when the
+                    // sidebar is closed or dropped for width, and SAID rather than
+                    // silently ignored: focus the user cannot see would make the arrows
+                    // change meaning with nothing on screen to account for it.
+                    if (!renderer.focusSidebar(true)) {
+                        renderer.println(renderer.theme.muted("(no sidebar to focus — /open sidebar, or widen the terminal)"));
+                    }
+                    paint();
+                    break;
                 default:
-                    // escape / arrows up-down / ctrl-k: no binding yet, deliberately
-                    // inert rather than leaking a control char into the buffer.
+                    // arrows: no binding yet, deliberately inert rather than leaking a
+                    // control char into the buffer.
                     break;
             }
         }
@@ -255,6 +341,10 @@ async function dispatch(input, session, renderer, out, slashCommands, checkpoint
         handlePanel(trimmed, "/open", true, renderer);
         return null;
     }
+    if (trimmed === "/view" || trimmed.startsWith("/view ")) {
+        handleView(trimmed, renderer);
+        return null;
+    }
     // Everything else is the SHARED implementation (P5 track 5). P1 forked this
     // loop out of `repl.ts` and left every one of these behind — including
     // `/plan`, which was then the only way to reach plan mode at all.
@@ -281,6 +371,39 @@ async function dispatch(input, session, renderer, out, slashCommands, checkpoint
     }
     return null;
 }
+/**
+ * `/view [name]` — select a main-pane view, or list what there is (P7 track 2).
+ *
+ * Exists so switching views never depends on the sidebar. The nav is the
+ * discoverable path, but it can be closed or dropped for width, and a UI whose
+ * only route to a surface can vanish is one that strands people. This is also
+ * the scriptable path, which is what makes the register testable end to end.
+ */
+function handleView(input, renderer) {
+    const t = renderer.theme;
+    const sources = renderer.viewSources();
+    const arg = input.slice("/view".length).trim().toLowerCase();
+    const ids = viewOrder(sources);
+    if (arg === "") {
+        renderer.println(t.muted("views:"));
+        for (const id of ids) {
+            const mark = id === renderer.view() ? t.glyph.pointer : " ";
+            renderer.println(t.muted(`  ${mark} ${viewLabel(id, sources)}`));
+        }
+        return;
+    }
+    // Matched on the id AND the label, because the sidebar shows the label and
+    // that is what a user will type back. They are the same string for every
+    // view so far; keeping both accepted means they can diverge without the
+    // command quietly becoming wrong.
+    const target = ids.find((id) => id === arg || viewLabel(id, sources).toLowerCase() === arg);
+    if (target === undefined || !renderer.setView(target)) {
+        renderer.println(t.muted(`unknown view: ${arg}`));
+        renderer.println(t.muted(`try: ${ids.map((id) => viewLabel(id, sources)).join(" | ")}`));
+        return;
+    }
+    renderer.println(t.muted(`showing ${viewLabel(target, sources)}`));
+}
 /** `/close <panel>` and `/open <panel>` share everything but the target state. */
 function handlePanel(input, command, open, renderer) {
     const t = renderer.theme;

package/dist/tui/git-status.js

@@ -1,4 +1,4 @@
-import { getGitInfoAsync } from "../utils/git.js";
+import { getGitInfoAsync, getGitTreeAsync, } from "../utils/git.js";
 export class GitStatusCache {
     cwd;
     probe;
@@ -61,3 +61,48 @@ export class GitStatusCache {
         }
     }
 }
+/**
+ * The same discipline across every declared root (P7 track 3).
+ *
+ * The rail names ONE branch because it has one line to do it in; the Overview
+ * view reports every root, because writes fan across all of them when
+ * checkpoints are on and a primary-only answer would under-report what a turn
+ * touched. That is more subprocesses, not a different rule — so this is a fan
+ * over {@link GitStatusCache} rather than a second implementation of it, and
+ * `current` stays the pure field read the paint path is allowed to call.
+ *
+ * Probes run CONCURRENTLY. They are independent processes against independent
+ * working trees, and serialising them would make a four-root workspace four
+ * times slower to settle for no gain.
+ */
+export class WorkspaceGitCache {
+    caches = new Map();
+    /**
+     * Probes with {@link getGitTreeAsync} by default, not the rail's cheaper
+     * {@link getGitInfoAsync} (P7 track 4): its consumers are the Overview and
+     * Git views, and the Git view needs the per-file list. The rail keeps the two
+     * -subprocess probe, because one line of branch-and-count has no use for a
+     * third.
+     */
+    constructor(paths, probe = getGitTreeAsync) {
+        for (const p of paths)
+            this.caches.set(p, new GitStatusCache(p, probe));
+    }
+    /**
+     * Last known state for one root — a field read, safe from the paint path.
+     * An unknown path reads as unprobed rather than throwing: the workspace can
+     * gain a root (`/add-root`) between this cache being built and a paint.
+     */
+    current(absPath) {
+        return this.caches.get(absPath)?.current();
+    }
+    /** Mark every root as possibly changed. Cheap and idempotent. */
+    invalidate() {
+        for (const c of this.caches.values())
+            c.invalidate();
+    }
+    /** Re-probe every stale root, in parallel, and resolve when all have settled. */
+    async refresh() {
+        await Promise.all([...this.caches.values()].map((c) => c.refresh()));
+    }
+}

package/dist/tui/git-view.js

@@ -0,0 +1,121 @@
+import { formatStat } from "../render/diff.js";
+import { fitMiddle } from "../render/layout.js";
+/** Verb column, fixed width so the paths align into a scannable column. */
+const VERBS = {
+    added: "added",
+    modified: "modified",
+    deleted: "deleted",
+    renamed: "renamed",
+    untracked: "new",
+    conflicted: "conflict",
+};
+const VERB_COLS = 8;
+/**
+ * How many files to list per root before summarising the rest.
+ *
+ * A cap rather than the whole list because a `node_modules` accident produces
+ * thousands of untracked paths, and a pane that has to be scrolled past them to
+ * reach the next root is worse than one that says how many it held back. The
+ * remainder is COUNTED, never silently dropped.
+ */
+export const GIT_VIEW_MAX_FILES = 200;
+/** Colour by what happened, so the shape of a change is legible before the path. */
+function styleVerb(status, theme) {
+    const verb = VERBS[status].padEnd(VERB_COLS);
+    switch (status) {
+        case "deleted":
+            return theme.danger(verb);
+        case "added":
+        case "untracked":
+            return theme.success(verb);
+        case "conflicted":
+            return theme.warning(verb);
+        default:
+            return theme.muted(verb);
+    }
+}
+/** `modified src/x.ts  +12/-3` — verb, path, then the counts when known. */
+function fileRow(file, theme, cols) {
+    const stat = formatStat(file, theme);
+    // The path is middle-truncated so the basename — the part that identifies the
+    // file — survives a narrow pane, the same rule `render/diff.ts` applies.
+    const room = Math.max(8, cols - VERB_COLS - 2 - (stat === "" ? 0 : 9));
+    const path = fitMiddle(file.path, room, theme.glyph.ellipsis);
+    return `${styleVerb(file.status, theme)} ${path}${stat === "" ? "" : ` ${stat}`}`;
+}
+/** One root's block: its heading, then its files or why there are none. */
+function rootLines(root, theme, cols, multiRoot) {
+    const lines = [];
+    if (multiRoot) {
+        const mark = root.primary ? theme.accent(theme.glyph.pointer) : " ";
+        lines.push(`${mark} ${theme.strong(root.name)}`);
+    }
+    // The tri-state, drawn as three different sentences. "Not probed" and "not a
+    // repo" are not the same claim, and neither is "clean" — see `status-view.ts`.
+    if (root.state === undefined) {
+        lines.push(theme.muted(`  checking${theme.glyph.ellipsis}`));
+        return lines;
+    }
+    if (root.state === null) {
+        lines.push(theme.muted("  not a git repo"));
+        return lines;
+    }
+    const { branch, files } = root.state;
+    lines.push(`  ${theme.strong(branch)}`);
+    if (files === undefined) {
+        // The cheap probe ran, so dirtiness is known but the list was never asked
+        // for. Say that rather than render an empty list as "nothing changed".
+        lines.push(theme.muted(root.state.changed > 0
+            ? `  ${root.state.changed} changed — file list not loaded`
+            : "  clean"));
+        return lines;
+    }
+    if (files.length === 0) {
+        lines.push(theme.success("  clean"));
+        return lines;
+    }
+    for (const file of files.slice(0, GIT_VIEW_MAX_FILES)) {
+        lines.push(`  ${fileRow(file, theme, Math.max(8, cols - 2))}`);
+    }
+    const hidden = files.length - GIT_VIEW_MAX_FILES;
+    if (hidden > 0) {
+        lines.push(theme.muted(`  ${theme.glyph.ellipsis}${hidden} more`));
+    }
+    return lines;
+}
+/** The whole Git view, as lines. Pure: no probe, no disk, no clock. */
+export function gitViewLines(theme, cols, roots) {
+    const lines = [theme.heading("git")];
+    if (roots.length === 0) {
+        lines.push(theme.muted("no declared roots"));
+        return lines;
+    }
+    const multiRoot = roots.length > 1;
+    for (const root of roots) {
+        lines.push("");
+        lines.push(...rootLines(root, theme, cols, multiRoot));
+    }
+    return lines;
+}
+/**
+ * The Git view as a registered source.
+ *
+ * `roots` is a callback rather than an array so `/add-root` mid-session is
+ * reflected without re-registering the view — the workspace is the owner of
+ * that list, and copying it here would make this the second place it lives.
+ */
+export function createGitView(roots, git) {
+    return {
+        id: "git",
+        label: "git",
+        lines: (theme, cols) => gitViewLines(theme, cols, roots().map((r) => ({
+            name: r.name,
+            primary: r.primary,
+            state: git.current(r.absPath),
+        }))),
+        refresh: async () => {
+            git.invalidate();
+            await git.refresh();
+        },
+    };
+}

package/dist/tui/index.js

@@ -2,8 +2,13 @@ export { budgetColumns, bodyRows, columnOf, composeScreen, droppedForWidth, fitB
 export { COLUMN_LABELS, PANEL_LABELS, contextPanelLines, gitPanelLines, headerModel, modelPanelLines, mainWelcome, railBlocks, sidebarLines, toolsPanelLines, } from "./panels.js";
 export { ContextGauge, readContext, } from "./context-gauge.js";
 export { ToolVersions, parseVersion, } from "./tool-versions.js";
-export { GitStatusCache, } from "./git-status.js";
-export { TuiRenderer, PAINT_INTERVAL_MS, SCROLLBACK_LINES, } from "./renderer.js";
+export { GitStatusCache, WorkspaceGitCache, } from "./git-status.js";
+export { createOverviewView } from "./overview.js";
+export { createGitView, gitViewLines, GIT_VIEW_MAX_FILES, } from "./git-view.js";
+export { createTasksView, tasksViewLines, TASKS_VIEW_MAX_JOBS, TASKS_VIEW_TAIL, } from "./tasks-view.js";
+export { createSettingsView, settingsViewLines, formatSettingValue, } from "./settings-view.js";
+export { TuiRenderer, PAINT_INTERVAL_MS, VIEW_PULSE_MS, SCROLL_PAGE_OVERLAP, SCROLLBACK_LINES, } from "./renderer.js";
+export { CONVERSATION_VIEW, cycleView, navLines, viewLabel, viewOrder, } from "./views.js";
 export { runTui, renderInput, TUI_COMMANDS } from "./app.js";
 export { openPalette, paletteItems, paletteInsertion, paletteLabel, } from "./palette.js";
 export { canOverlay, createKeyLease, createOverlayFrame, createOverlayIO, } from "./overlay.js";

package/dist/tui/layout.js

@@ -123,6 +123,51 @@ export function fitBlock(lines, rows, width) {
         out.push(" ".repeat(Math.max(0, width)));
     return out;
 }
+/**
+ * Window `rows` lines out of a block, `offset` display lines up from the end
+ * (P7 track 1). `offset === 0` is the tail view {@link fitBlock} gives, and the
+ * two agree line-for-line there.
+ *
+ * The offset is measured from the BOTTOM because that is the edge the user is
+ * anchored to: the live tail is the home position, and "how far back am I" is
+ * the question both the clamp and the notice need answered. Measuring from the
+ * top would make every append renumber the position.
+ *
+ * Clamping belongs here rather than at the key handler because only this
+ * function knows the content: the handler would have to re-derive the wrapped
+ * line count to bound a keypress, which is the calculation this already did.
+ */
+export function scrollWindow(lines, rows, offset) {
+    const visible = Math.max(0, rows);
+    // Everything above the last `visible` lines is reachable, and no further: the
+    // top of the document is the top of the window, never a screen of blank rows
+    // above it.
+    const maxOffset = Math.max(0, lines.length - visible);
+    const clamped = Math.min(Math.max(0, Math.floor(offset)), maxOffset);
+    const end = lines.length - clamped;
+    const start = Math.max(0, end - visible);
+    return {
+        lines: lines.slice(start, end),
+        offset: clamped,
+        hiddenBelow: clamped,
+        hiddenAbove: start,
+    };
+}
+/**
+ * The scrollback notice: how far back the view is, and how to get out of it.
+ *
+ * Shown only while scrolled, and it costs a row from the window rather than
+ * overlaying one — the same trade {@link stackPanels} makes for its overflow
+ * notice, for the same reason: silently hiding a line to report hidden lines
+ * would be the one dishonest way to draw this.
+ *
+ * It names the key because a scrolled view is a mode, and a mode the user
+ * cannot see the exit from is a trap — there is no scrollbar here to drag.
+ */
+export function scrollNotice(hiddenBelow, theme) {
+    const glyph = theme.unicode ? "↓" : "v";
+    return theme.warning(`${glyph} ${hiddenBelow} more line${hiddenBelow === 1 ? "" : "s"} below · PgDn / Esc to return`);
+}
 /** Rows the overflow notice costs when at least one panel is dropped. */
 const OVERFLOW_ROWS = 1;
 /**

package/dist/tui/overview.js

@@ -0,0 +1,49 @@
+import { buildSessionStatus } from "../agent/status.js";
+import { sessionStatusLines } from "../render/status-view.js";
+/**
+ * The Overview view (P7 track 3) — the first concrete {@link ViewSource}.
+ *
+ * There is almost nothing here, and that is the result rather than an accident.
+ * `sessionStatusLines` already composed this screen for `/status`, and
+ * `buildSessionStatus` already assembles what it renders; the only thing that
+ * was missing was somewhere for it to LIVE. As a command it printed once into
+ * the scrollback and was gone by the next turn — a standing description of the
+ * session that could not stand.
+ *
+ * LIVE VS PER-PAINT, decided per fact rather than per view:
+ *
+ *  - **Per-paint** — turns, mode, model, served tier, context occupancy,
+ *    sandbox, checkpoints, job counts, tool count. Every one is a field read or
+ *    a filter over an in-memory array, so recomputing them at 30fps costs
+ *    nothing measurable and they are never a frame stale.
+ *  - **Cached, off the paint path** — branch and change count, per root. These
+ *    cost two subprocesses each, ~45ms warm and worse on Windows, and the pane
+ *    repaints on every frame and every resize. {@link WorkspaceGitCache} does
+ *    the probing after a turn; {@link lines} only ever reads the last settled
+ *    value.
+ *
+ * The rule the split enforces: nothing in `lines` may spawn, block, or touch
+ * the disk. Anything that needs to is a cache read here and a `refresh` there.
+ */
+export function createOverviewView(session, git, 
+/**
+ * The tier the gateway last said served a request — a getter, not a value,
+ * because it changes per turn and the view is registered once. Supplied by
+ * the renderer, the only object that sees the stream's routing frame.
+ */
+servedTier = () => undefined) {
+    return {
+        id: "overview",
+        label: "overview",
+        lines: (theme, cols) => sessionStatusLines(buildSessionStatus(session, (absPath) => git.current(absPath), servedTier()), theme, cols),
+        /**
+         * Re-probe every root after a turn. Invalidate-then-refresh because a turn
+         * is exactly when the tree may have moved; the cache coalesces, so the ten
+         * writes a turn makes still cost one probe per root.
+         */
+        refresh: async () => {
+            git.invalidate();
+            await git.refresh();
+        },
+    };
+}