@cruxy/cli 1.2.0 → 1.3.0

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