@cruxy/cli 1.2.1 → 1.4.0

package/dist/tui/overlay.js

@@ -0,0 +1,105 @@
+import { createKeyReader, } from "../components/input.js";
+/**
+ * Build the lease over one real reader.
+ *
+ * `restore()` is idempotent PER HANDLE, not just in aggregate: a component that
+ * calls it twice in a `finally` must not decrement the count twice and yank the
+ * terminal out from under the loop that lent it.
+ */
+export function createKeyLease(stdin) {
+    const reader = createKeyReader(stdin);
+    let holders = 0;
+    return {
+        handle() {
+            let mine = false;
+            return {
+                begin() {
+                    if (mine)
+                        return;
+                    mine = true;
+                    if (holders++ === 0)
+                        reader.begin();
+                },
+                read() {
+                    return reader.read();
+                },
+                restore() {
+                    if (!mine)
+                        return;
+                    mine = false;
+                    if (--holders === 0)
+                        reader.restore();
+                },
+            };
+        },
+        held: () => holders > 0,
+    };
+}
+/**
+ * A {@link Frame} that paints into the renderer's overlay drawer instead of the
+ * terminal. Same contract as `components/frame.ts` — render replaces the
+ * region, `clear()` removes it entirely and is idempotent — so a component
+ * cannot tell the difference, and the `finally { frame.clear() }` every one of
+ * them already has is what takes the drawer back down.
+ */
+export function createOverlayFrame(surface) {
+    let cleared = false;
+    return {
+        render(lines) {
+            if (cleared)
+                return;
+            surface.setOverlay(lines);
+        },
+        clear() {
+            if (cleared)
+                return;
+            cleared = true;
+            surface.setOverlay(null);
+        },
+    };
+}
+/**
+ * A {@link ComponentIO} that runs a component inside the TUI viewport: frames
+ * become overlay rows, keys come from the shared lease.
+ *
+ * `caps` is a LIVE view, not a snapshot. The real capabilities object is mutated
+ * in place on SIGWINCH, and the drawer's usable width and height are both
+ * derived from it, so these have to be getters — a spread would freeze the
+ * overlay at the width it was opened with and every row would be fitted to a
+ * terminal that no longer exists. (Content composed before a resize is not
+ * re-flowed until the component's next repaint; the renderer pads and truncates
+ * every row it paints, so the intermediate frame is stale, never corrupt.)
+ *
+ * `write` is deliberately a sink. Components emit frame bytes through the frame
+ * and nothing else; anything that did reach here would be raw ANSI landing in
+ * the middle of a managed screen, so dropping it is the honest behaviour rather
+ * than forwarding corruption to the terminal.
+ */
+export function createOverlayIO(surface, lease) {
+    const host = surface.caps;
+    const caps = {
+        ...host,
+        get width() {
+            return surface.overlayWidth();
+        },
+        get height() {
+            return surface.overlayRows();
+        },
+    };
+    return {
+        caps,
+        interactive: host.interactive,
+        write: () => { },
+        keys: lease.handle(),
+        makeFrame: () => createOverlayFrame(surface),
+    };
+}
+/**
+ * Whether the screen can host a modal at all. A terminal too short for a drawer
+ * leaves {@link OverlaySurface.overlayRows} at 0, and a component painting into
+ * zero rows would read as a hang — the prompt never appears, the key loop still
+ * blocks. Callers check this and fall back to a non-overlay path instead.
+ */
+export function canOverlay(surface) {
+    return surface.caps.interactive && surface.overlayRows() > 0;
+}

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();
+        },
+    };
+}

package/dist/tui/palette.js

@@ -0,0 +1,73 @@
+import { fuzzyFind } from "../components/fuzzy.js";
+import { COMMAND_CATALOG } from "../cli/session-commands.js";
+import { canOverlay, createOverlayIO } from "./overlay.js";
+/** The TUI's own commands, which the shared catalogue deliberately excludes. */
+const PANEL_COMMANDS = [
+    {
+        name: "/close",
+        summary: "hide a panel or the whole rail",
+        args: "<sidebar | context | model | git | tools | rail>",
+    },
+    {
+        name: "/open",
+        summary: "show a hidden panel",
+        args: "<sidebar | context | model | git | tools | rail>",
+    },
+];
+/**
+ * Everything the palette offers: the shared catalogue, this shell's panel
+ * commands, and the project's own slash commands.
+ *
+ * Custom commands come LAST and are labelled. `resolveSlash` consults builtins
+ * first, so a custom command named `clear` can never shadow `/clear` — listing
+ * it above the builtin would show an order the dispatcher does not honour.
+ */
+export function paletteItems(slashCommands = []) {
+    const builtins = [...COMMAND_CATALOG, ...PANEL_COMMANDS].map((c) => ({
+        name: c.name,
+        summary: c.summary,
+        ...(c.args === undefined ? {} : { args: c.args }),
+    }));
+    const custom = slashCommands.map((c) => ({
+        name: `/${c.name}`,
+        summary: c.description,
+        custom: true,
+    }));
+    return [...builtins, ...custom];
+}
+/**
+ * The text a picked item puts in the input buffer.
+ *
+ * A command that takes arguments gets a trailing space, so the cursor lands
+ * where the user has to type next rather than flush against the name.
+ */
+export function paletteInsertion(item) {
+    return item.args === undefined ? item.name : `${item.name} `;
+}
+/** The row a picked item is matched and displayed as. */
+export function paletteLabel(item) {
+    const left = item.args === undefined ? item.name : `${item.name} ${item.args}`;
+    return `${left} — ${item.summary}${item.custom ? " (project)" : ""}`;
+}
+/**
+ * Open the palette. Resolves the text to insert into the input buffer, or null
+ * when the user cancelled (Esc / Ctrl-C / EOF) — which must leave the buffer
+ * exactly as it was.
+ *
+ * Returns null immediately on a terminal with no room for a drawer, rather than
+ * painting into zero rows: a modal that renders nothing while still consuming
+ * every keystroke is indistinguishable from a hang.
+ */
+export async function openPalette(renderer, lease, slashCommands = []) {
+    if (!canOverlay(renderer))
+        return null;
+    const items = paletteItems(slashCommands);
+    const result = await fuzzyFind(items, {
+        toLabel: paletteLabel,
+        title: "commands",
+        // The drawer's own budget, minus the query row, the title and the key
+        // hint `fuzzyFind` draws around the list.
+        maxVisible: Math.max(1, renderer.overlayRows() - 3),
+    }, createOverlayIO(renderer, lease));
+    return result.kind === "selected" ? paletteInsertion(result.value) : null;
+}

package/dist/tui/panels.js

@@ -0,0 +1,235 @@
+import { relativeAge, shortId } from "../session/index.js";
+import { RAIL_PANELS, } from "./layout.js";
+/**
+ * Panel content.
+ *
+ * Each builder is a pure `(theme, state) => string[]`, so swapping a
+ * placeholder for the real thing is a body change with no reach into layout or
+ * paint. Every builder takes its own state explicitly — the shape `sidebarLines`
+ * established — rather than reading a shared blob, so a panel can only render
+ * what it was actually handed.
+ *
+ * A panel whose state is absent says so rather than showing invented data: a
+ * fabricated token count or branch name is indistinguishable from a broken real
+ * one, and the whole rail is a claim about live state.
+ */
+/** Human labels for the panels, used by `/close`, `/open`, and `/help`. */
+export const PANEL_LABELS = {
+    sidebar: "sidebar",
+    context: "context",
+    model: "model",
+    git: "git",
+    tools: "tools",
+};
+/** Human labels for the columns, for messages that are about width. */
+export const COLUMN_LABELS = {
+    sidebar: "sidebar",
+    main: "main",
+    rail: "rail",
+};
+/** Titles drawn at the top of each rail panel. */
+const RAIL_TITLES = {
+    context: "context",
+    model: "model",
+    git: "git",
+    tools: "tools",
+};
+/** A panel's title row, styled as a heading. */
+function title(text, theme) {
+    return [theme.strong(text), ""];
+}
+/**
+ * Left column — the project's saved sessions (P2), newest first.
+ *
+ * Reads the same `listSessions` the `--resume` picker does, so the sidebar and
+ * the picker can never disagree about what exists or in what order. The active
+ * session is marked, so "which of these am I in" is answerable at a glance.
+ *
+ * The column is narrow (18 columns), so each session takes two lines: its short
+ * id and age, then its title. The layout truncates per line, which keeps the id
+ * — the part you would type into `--resume` — always fully visible.
+ */
+export function sidebarLines(theme, sessions = [], activeSessionId, now = Date.now()) {
+    const lines = title("sessions", theme);
+    if (sessions.length === 0) {
+        lines.push(theme.muted("no saved sessions"));
+        lines.push(theme.muted("for this project yet."));
+        return lines;
+    }
+    for (const s of sessions) {
+        const active = s.sessionId === activeSessionId;
+        const mark = active ? theme.accent(theme.glyph.pointer) : " ";
+        const head = `${mark} ${shortId(s.sessionId)} ${relativeAge(s.updatedAt, now)}`;
+        lines.push(active ? theme.strong(head) : head);
+        lines.push(theme.muted(`  ${s.title}`));
+    }
+    return lines;
+}
+/** A panel with no state yet: says so, rather than inventing a plausible value. */
+function pending(theme) {
+    return [theme.muted("not wired yet")];
+}
+/** One rail panel: its title, then whatever its own track supplied. */
+function railPanel(id, theme, lines) {
+    const body = lines !== undefined && lines.length > 0 ? [...lines] : pending(theme);
+    return { id, lines: [theme.strong(RAIL_TITLES[id]), ...body] };
+}
+/**
+ * Right column — the four panels, in draw order, for the ones the user has open.
+ *
+ * Returns BLOCKS rather than a flat line array: the rail is a stack of fixed
+ * panels, and the caller has to be able to drop whole panels (and say how many)
+ * when the terminal is too short. Flattening here would throw away exactly the
+ * boundary that makes honest overflow reporting possible — see `stackPanels`.
+ */
+export function railBlocks(theme, state = {}, open = new Set(RAIL_PANELS)) {
+    return RAIL_PANELS.filter((id) => open.has(id)).map((id) => railPanel(id, theme, state[id]));
+}
+/**
+ * The git panel's body (P4 track 2): branch, then clean-or-changed.
+ *
+ * Two lines rather than one because they cannot share a row honestly at
+ * {@link RAIL_COLS}: a branch alone can use the full width, and pairing it with
+ * a count would truncate whichever came second. Branch first — it says WHERE the
+ * work is happening, which is the question the panel exists to answer.
+ *
+ * The dirty state is a WORD, not a colour or a glyph: colour is unavailable
+ * under NO_COLOR and a bare marker is meaningless to a screen reader, so
+ * "clean" / "3 changed" carries the meaning and the styling only reinforces it.
+ *
+ * `undefined` (not probed yet) and `null` (not a repo) are different facts and
+ * are said differently — a repo whose probe has not landed must not read as
+ * "not a repo".
+ */
+export function gitPanelLines(theme, state) {
+    if (state === undefined)
+        return [theme.muted(`checking${theme.glyph.ellipsis}`)];
+    if (state === null)
+        return [theme.muted("not a git repo")];
+    const { branch, dirty, changed } = state;
+    return [
+        theme.strong(branch),
+        dirty ? theme.warning(`${changed} changed`) : theme.success(`clean`),
+    ];
+}
+/**
+ * How the served tier was chosen, in words. The wire values (`explicit` /
+ * `auto` / `auto_degraded`) are not shown raw — `auto_degraded` in particular
+ * is the one line here a user must be able to act on, and it has to say that a
+ * budget downgrade happened rather than leave them to decode an enum.
+ */
+function describeRoutingMode(mode) {
+    switch (mode) {
+        case "explicit":
+            return "as configured";
+        case "auto":
+            return "auto-routed";
+        case "auto_degraded":
+            return "downgraded (budget)";
+        default:
+            // A mode the gateway did not send, or one added after this build. The
+            // tier is still real; only the explanation is missing.
+            return "served";
+    }
+}
+/**
+ * The model panel's body (P4 track 4): which tier is actually running, and why.
+ *
+ * BEFORE THE FIRST TURN there is no served tier — the gateway has not answered
+ * — so the panel shows the CONFIGURED value and says it is unresolved. Blank
+ * would be worse than useless here: `auto` is the default, and a user looking
+ * at an empty model panel cannot tell configuration from breakage.
+ */
+export function modelPanelLines(theme, state) {
+    const { configured, served } = state;
+    if (served === undefined) {
+        return [theme.strong(configured), theme.muted("not resolved yet")];
+    }
+    return [
+        theme.strong(served.tier),
+        // A budget downgrade is the one case the user may need to act on, so it
+        // reads as a warning; everything else is ordinary reporting.
+        served.mode === "auto_degraded"
+            ? theme.warning(describeRoutingMode(served.mode))
+            : theme.muted(describeRoutingMode(served.mode)),
+    ];
+}
+/**
+ * The TUI header's right side: provider, what was configured, and — once the
+ * gateway has answered with something different — what actually ran.
+ *
+ * `cruxy/auto` is what P1 shipped and it never changed for the life of the
+ * process, so a run routed to `kavi` still read `auto` forever. Showing both
+ * sides of an `auto → kavi` resolution keeps the configured value visible
+ * (it is what the user set) while making the real one legible.
+ */
+export function headerModel(theme, provider, state) {
+    const { configured, served } = state;
+    if (served === undefined || served.tier === configured) {
+        return `${provider}/${served?.tier ?? configured}`;
+    }
+    return `${provider}/${configured} ${theme.glyph.arrow} ${served.tier}`;
+}
+/**
+ * The tools panel's body (P4 track 5): one row per tool, each independent.
+ *
+ * A row is one of three things and they are three different claims: a version
+ * (probed and found), "…" (still probing), or "—" (probed and absent). Merging
+ * the last two would tell a user their toolchain is missing while the probe is
+ * still running, which is the one wrong answer this panel can give.
+ *
+ * Rows fill in as their own probes land, so a slow pnpm never holds back git.
+ */
+export function toolsPanelLines(theme, rows) {
+    return rows.map((row) => {
+        if (row.version === undefined) {
+            return theme.muted(`${row.name} ${theme.glyph.ellipsis}`);
+        }
+        if (row.version === null) {
+            // Words, not a dash. "git —" is ambiguous to anyone — it could as easily
+            // read as "no version reported" as "absent" — and it carries nothing at
+            // all to a screen reader. "not found" fits the 24-column rail anyway.
+            return theme.muted(`${row.name} not found`);
+        }
+        return `${theme.strong(row.name)} ${theme.muted(row.version)}`;
+    });
+}
+/** Compact token count for the narrow rail: 34_512 → "34k", 900 → "900". */
+function shortTokens(n) {
+    return n >= 1000 ? `${Math.round(n / 1000)}k` : `${n}`;
+}
+/**
+ * The context panel's body (P4 track 3).
+ *
+ * THE WORDING IS THE FEATURE. Both numbers are estimates — a chars/4 heuristic
+ * over a budget that is a local config default, not the served model's real
+ * window — so the panel is written to claim exactly that much and no more:
+ *
+ *  - "~" on the figure, because the numerator is a heuristic;
+ *  - "budget", never "window", because the denominator is a setting in this
+ *    CLI's config. Under `model: "auto"` the served tier varies per request and
+ *    the real window varies with it; calling 100k "the window" would assert
+ *    something no request has to honour;
+ *  - no progress bar. A filled bar reads as a measurement, and this is not one.
+ *    Two plain numbers can be wrong without also looking precise.
+ *
+ * The compaction threshold is shown because it is the only actionable thing
+ * here: it says when the CLI will start folding history away.
+ */
+export function contextPanelLines(theme, reading) {
+    if (reading === undefined) {
+        return [theme.muted(`measuring${theme.glyph.ellipsis}`)];
+    }
+    const { used, total, compactAt } = reading;
+    const figure = `~${shortTokens(used)} / ${shortTokens(total)} budget`;
+    // Past the threshold the next turn compacts, which is worth flagging — but as
+    // a statement of what happens next, not as an alarm about a guessed number.
+    // Compared on `used`, not the clamped fraction: the clamp is for display, and
+    // a history that has overrun the budget must not compare as merely "at" it.
+    const style = used >= compactAt ? theme.warning : theme.strong;
+    return [style(figure), theme.muted(`compacts at ${shortTokens(compactAt)}`)];
+}
+/** The opening lines of the main column, before any turn has run. */
+export function mainWelcome(theme, hint) {
+    return [theme.muted(hint), ""];
+}