@cruxy/cli 1.3.0 → 1.5.0

package/dist/tui/settings-view.js

@@ -0,0 +1,282 @@
+import { fit, fitMiddle } from "../render/layout.js";
+import { apiKeyEnvVar, effectiveSettings, envOverrideNames, loadConfig, } from "../config/index.js";
+/**
+ * The Settings view (P7 track 6): every effective setting, and — the part that
+ * makes it worth a pane — WHERE each one came from.
+ *
+ * READ-ONLY, DELIBERATELY. `cruxy config set` writes a value with validation
+ * and a file to blame, and `$EDITOR` writes the file itself; an editable pane
+ * would have to grow a form system (a focus ring, per-type input, validation
+ * surfacing, a write path, and an undo for the write) to arrive at what two
+ * existing surfaces already do correctly. What was actually missing was not
+ * editing — it was ANSWERING: `cruxy config list` prints a resolved blob in
+ * which a value someone set by hand is indistinguishable from one the schema
+ * defaulted, so "why is this on" ends in opening files and re-deriving the
+ * precedence by hand. Every row here names its origin.
+ *
+ * THIS SESSION'S VALUES, NOT THE DISK'S. Config is read once at startup and the
+ * session runs on that; a pane that re-read the files would show a value the
+ * running session is NOT using the moment someone edits one mid-session — a
+ * stale claim in the more dangerous direction, since it reads as confirmation
+ * that an edit took effect. So the rows are the startup snapshot, and
+ * {@link ViewSource.refresh} re-reads only to compare: when the disk has moved,
+ * the pane SAYS so and says that a restart is what applies it.
+ *
+ * NOTHING SECRET REACHES THIS FILE. Redaction happens in
+ * {@link effectiveSettings}, one layer down, so this module never holds a
+ * credential to leak — `credentials.json` is 0600 for a reason, and a pane on a
+ * shared screen is the least controlled surface in the product.
+ */
+/** Width of the origin column — `explicit` renders as `--config`, 8 chars. */
+const ORIGIN_COLS = 8;
+/** Bounds on the key column, so one long key can't squeeze out every value. */
+const KEY_COLS_MIN = 12;
+const KEY_COLS_MAX = 28;
+/** The word each origin renders as. The file ones name the SCOPE (`global`,
+ * `project`); the explicit one names the FLAG that caused it, because that is
+ * what the user typed and what they would remove. */
+const ORIGIN_WORDS = {
+    default: "default",
+    global: "global",
+    project: "project",
+    explicit: "--config",
+    env: "env",
+};
+/**
+ * Colour by origin, but the WORD carries the meaning — this has to survive
+ * NO_COLOR and a screen reader, where "dimmer means default" says nothing.
+ *
+ * `env` is warned rather than accented, and it is the one origin that gets a
+ * colour of its own: a file override is durable and inspectable, while an
+ * environment override lives in one shell, is invisible everywhere else, and
+ * disappears on the next login — which makes it the likeliest answer to "why is
+ * this on, I never set that".
+ */
+function styleOrigin(origin, theme) {
+    const word = ORIGIN_WORDS[origin].padStart(ORIGIN_COLS);
+    switch (origin) {
+        case "default":
+            return theme.muted(word);
+        case "env":
+            return theme.warning(word);
+        default:
+            return theme.accent(word);
+    }
+}
+/**
+ * A value as one line of text.
+ *
+ * An empty string renders as `""` and an empty array/object as `[]`/`{}`
+ * because "" and unset are different states and a blank cell shows them the
+ * same way — `routing.map: {}` in particular is what a configured-but-inert
+ * feature looks like, and it has to be distinguishable from a key that is
+ * missing entirely.
+ */
+export function formatSettingValue(value) {
+    if (typeof value === "string")
+        return value === "" ? '""' : value;
+    if (Array.isArray(value)) {
+        return value.length === 0 ? "[]" : value.map(String).join(", ");
+    }
+    if (value === null)
+        return "null";
+    if (typeof value === "object")
+        return "{}";
+    return String(value);
+}
+/** `  provider          cruxy                              default`. */
+function settingRow(setting, keyLabel, keyCols, theme, cols) {
+    // Middle-truncated like the value: these labels are dot-paths, and the TAIL
+    // is the part that names the setting — `servers.remote.headers.Authorization`
+    // right-truncated to `servers.remote.headers.Auth…` has spent 28 columns
+    // saying which section it is in and none saying which key.
+    const key = fitMiddle(keyLabel, keyCols, theme.glyph.ellipsis).padEnd(keyCols);
+    const room = Math.max(8, cols - 2 - keyCols - 2 - ORIGIN_COLS - 1);
+    const raw = formatSettingValue(setting.value);
+    // Middle-truncated: these values are paths, URLs and commands, whose tail
+    // identifies them at least as much as their head — the rule `render/diff.ts`
+    // applies to paths, for the same reason.
+    const value = fitMiddle(raw, room, theme.glyph.ellipsis).padEnd(room);
+    const styled = setting.redacted ? theme.warning(value) : value;
+    const name = setting.origin === "default" ? theme.muted(key) : theme.strong(key);
+    return `  ${name}  ${styled} ${styleOrigin(setting.origin, theme)}`;
+}
+/**
+ * The key column width: the longest label shown, clamped — and clamped again
+ * by what the pane can actually spare.
+ *
+ * The row degrades in a fixed order as the pane narrows: the VALUE gives up
+ * width first (it is truncated content, and `cruxy config get` prints it in
+ * full), then the KEY, and the origin column never yields at all — a row whose
+ * source has been squeezed off is a row with nothing this view was built to
+ * say. Below roughly 33 columns even the floors do not fit and the renderer
+ * reflows the row, which is what every other view's long lines already do.
+ */
+function keyColumn(labels, cols) {
+    const longest = labels.reduce((max, l) => Math.max(max, l.length), 0);
+    // 2 indent + key + 2 gap + value + 1 gap + origin, with the value at its floor.
+    const affordable = cols - 2 - 2 - 8 - 1 - ORIGIN_COLS;
+    return Math.max(KEY_COLS_MIN, Math.min(KEY_COLS_MAX, longest, Math.max(KEY_COLS_MIN, affordable)));
+}
+/** The label a row shows: its path minus the section heading above it. */
+function rowLabel(path) {
+    const dot = path.indexOf(".");
+    return dot === -1 ? path : path.slice(dot + 1);
+}
+/**
+ * The provenance header: which files were read, and which variables are in
+ * play. Named even when absent — "(none found)" is an answer to "why is my
+ * project config being ignored", and a header that simply omitted the row
+ * would leave the question looking unasked.
+ */
+function sourceLines(snapshot, theme, cols) {
+    const lines = [];
+    const row = (label, value, muted = false) => {
+        const text = fitMiddle(value, Math.max(8, cols - 12), theme.glyph.ellipsis);
+        return `  ${theme.strong(label.padEnd(8))}  ${muted ? theme.muted(text) : text}`;
+    };
+    const { global, project, explicit } = snapshot.sources;
+    lines.push(row("global", global ?? "(none found)", global === null));
+    if (explicit !== null) {
+        // An explicit --config REPLACES project discovery rather than layering over
+        // it, so the project row would be a lie about what was consulted.
+        lines.push(row("--config", explicit));
+    }
+    else {
+        lines.push(row("project", project ?? "(none found)", project === null));
+    }
+    const env = envOverrideNames(snapshot);
+    if (env.length > 0)
+        lines.push(row("env", env.join(", ")));
+    return lines;
+}
+/**
+ * How the provider API key resolves — PRESENCE and SOURCE, never the key.
+ *
+ * It belongs on this pane even though it is not a config value, and precisely
+ * because it is not: "why is this on" is asked about authentication more than
+ * anything else here, and config is secret-free by design, so a user scanning
+ * these rows for their key finds nothing and cannot tell whether that means
+ * unset or merely not-shown. This row says which.
+ */
+function apiKeyLine(provider, present, theme) {
+    const envVar = apiKeyEnvVar(provider);
+    const label = theme.strong("api key ".padEnd(8));
+    if (!present) {
+        return `  ${label}  ${theme.warning("not set")} ${theme.muted(`— set ${envVar} or run \`cruxy login\``)}`;
+    }
+    const source = process.env[envVar] !== undefined && process.env[envVar] !== ""
+        ? `${envVar} (env)`
+        : "credentials store (~/.cruxy/credentials.json, owner-only)";
+    return `  ${label}  ${theme.success("set")} ${theme.muted(`— ${source}`)}`;
+}
+/** The whole Settings view, as lines. Pure: no probe, no disk, no clock. */
+export function settingsViewLines(theme, cols, snapshot, opts) {
+    const lines = [theme.heading("settings")];
+    const settings = effectiveSettings(snapshot);
+    const fromFile = settings.filter((s) => s.origin !== "default" && s.origin !== "env").length;
+    const fromEnv = settings.filter((s) => s.origin === "env").length;
+    lines.push("");
+    const summary = [`${settings.length} settings`];
+    if (fromFile > 0)
+        summary.push(`${fromFile} from a file`);
+    if (fromEnv > 0)
+        summary.push(`${fromEnv} from the environment`);
+    if (fromFile === 0 && fromEnv === 0)
+        summary.push("all schema defaults");
+    lines.push(theme.muted(summary.join(theme.sep)));
+    lines.push("");
+    lines.push(...sourceLines(snapshot, theme, cols));
+    lines.push(apiKeyLine(snapshot.config.model.provider, opts.apiKeyPresent, theme));
+    // The two disk states, said as two different sentences. "Changed" means this
+    // session is running on something the files no longer say; "no longer loads"
+    // means the next session will not START until it is fixed — a much louder
+    // problem, and one the user would otherwise meet at the worst moment.
+    const drift = opts.drift;
+    if (drift?.error !== undefined) {
+        lines.push("");
+        lines.push(theme.danger(fit(`config on disk no longer loads: ${drift.error}`, cols, theme.glyph.ellipsis)));
+        lines.push(theme.muted("the rows below are what this session loaded at start"));
+    }
+    else if (drift?.changed === true) {
+        lines.push("");
+        lines.push(theme.warning("config files have changed since this session started"));
+        lines.push(theme.muted("the rows below are what this session is RUNNING on — restart cruxy to pick the new values up"));
+    }
+    lines.push("");
+    lines.push(theme.muted("read-only — `cruxy config set <key> <value>` writes a value, or edit the file above"));
+    const keyCols = keyColumn(settings.map((s) => rowLabel(s.path)), cols);
+    let section = null;
+    for (const setting of settings) {
+        const dot = setting.path.indexOf(".");
+        if (dot === -1) {
+            // A top-level scalar (`logLevel`) heads no section: it IS the whole
+            // setting, and a one-row section named after its only row reads as an
+            // outline error rather than a group.
+            section = null;
+            lines.push("");
+            lines.push(settingRow(setting, setting.path, keyCols, theme, cols));
+            continue;
+        }
+        const group = setting.path.slice(0, dot);
+        if (group !== section) {
+            section = group;
+            lines.push("");
+            lines.push(theme.strong(group));
+        }
+        lines.push(settingRow(setting, rowLabel(setting.path), keyCols, theme, cols));
+    }
+    lines.push("");
+    lines.push(theme.muted("secret-shaped values are never printed here — a config file holds no keys by design, and the credentials store is owner-only"));
+    return lines;
+}
+/**
+ * The Settings view as a registered source.
+ *
+ * `snapshot` is the SAME {@link LoadedConfig} the session was built from, not a
+ * fresh load — see the module comment. `apiKeyPresent` is a getter because
+ * onboarding can supply a key after startup, and the view is registered once.
+ *
+ * `reload` exists for the drift check and for tests; it defaults to the real
+ * loader. Its result is used ONLY for comparison — never to repaint a value —
+ * so a mid-session edit can change what the pane SAYS about the disk without
+ * ever changing what it claims this session is running.
+ */
+export function createSettingsView(snapshot, apiKeyPresent, reload = () => loadConfig()) {
+    // The startup config, serialized once, as the thing every later read is
+    // compared against. Comparing resolved configs rather than file bytes makes
+    // the check MEAN "would this session behave differently": a reformatted file,
+    // a reordered key or an added comment-shaped no-op is not drift, and
+    // reporting it as such would train the user to ignore the line.
+    const baseline = JSON.stringify(snapshot.config);
+    let drift = { changed: false };
+    return {
+        id: "settings",
+        label: "settings",
+        lines: (theme, cols) => settingsViewLines(theme, cols, snapshot, {
+            apiKeyPresent: apiKeyPresent(),
+            drift,
+        }),
+        refresh: async () => {
+            try {
+                drift = { changed: JSON.stringify(reload().config) !== baseline };
+            }
+            catch (err) {
+                // A file that no longer parses or no longer validates is the loudest
+                // thing this view can report, and it must be reported rather than
+                // thrown: the renderer swallows a failed refresh, which would leave the
+                // pane silently claiming the disk still matches.
+                drift = {
+                    changed: true,
+                    // Flattened to one line: a config error carries a multi-line list of
+                    // schema issues, and a view whose contract is `readonly string[]`
+                    // would emit one "line" containing newlines — which the renderer
+                    // windows as a single row and paints straight through the pane.
+                    error: (err instanceof Error ? err.message : String(err))
+                        .replace(/\s+/g, " ")
+                        .trim(),
+                };
+            }
+        },
+    };
+}

package/dist/tui/tasks-view.js

@@ -0,0 +1,215 @@
+import { fit } from "../render/layout.js";
+import { formatTokens } from "../render/state.js";
+import { isTerminal } from "../jobs/types.js";
+/**
+ * The status column, fixed width so the ids and labels align into something
+ * scannable — the same reason `git-view.ts` puts its verb in a column.
+ *
+ * `paused-needs-approval` shortens to `paused` because 21 characters of column
+ * would cost every other row its label. Nothing is lost: what it is paused FOR
+ * is the one thing that matters about the state, and that gets its own line.
+ */
+const STATUS_WORDS = {
+    queued: "queued",
+    running: "running",
+    "paused-needs-approval": "paused",
+    done: "done",
+    failed: "failed",
+    cancelled: "cancelled",
+};
+/** Width of the status column — `cancelled`, the longest word above. */
+const STATUS_COLS = 9;
+/**
+ * How many log lines each detailed job shows.
+ *
+ * A tail rather than the whole buffer: the buffer holds a thousand lines by
+ * default, five jobs may be live at once, and a pane that has to be scrolled
+ * past four jobs' full transcripts to reach the fifth is not a list any more.
+ * What the tail does NOT show is COUNTED, never silently dropped — see
+ * {@link tailNotice}.
+ */
+export const TASKS_VIEW_TAIL = 8;
+/**
+ * How many jobs to list before summarising the rest.
+ *
+ * `maxJobs` caps how many may be LIVE (five by default), not how many a long
+ * session may have finished, and terminal jobs are never removed from the
+ * manager's map — so this list grows without bound over a day's work. The most
+ * recent are the ones being asked about; the older ones are counted and `/jobs`
+ * still lists every one.
+ */
+export const TASKS_VIEW_MAX_JOBS = 20;
+/** Colour by state, so "what needs me" is legible before any word is read. */
+function styleStatus(status, theme) {
+    const word = STATUS_WORDS[status].padEnd(STATUS_COLS);
+    switch (status) {
+        case "running":
+            return theme.accent(word);
+        case "paused-needs-approval":
+            return theme.warning(word);
+        case "failed":
+            return theme.danger(word);
+        case "done":
+            return theme.success(word);
+        default:
+            // queued and cancelled: nothing is happening and nothing is wrong.
+            return theme.muted(word);
+    }
+}
+/** `running   job-1-ab3c  refactor the parser into two passes`. */
+function jobRow(job, theme, cols) {
+    const head = `${styleStatus(job.status, theme)} ${theme.strong(job.id)}  `;
+    const room = Math.max(8, cols - STATUS_COLS - 1 - job.id.length - 2);
+    return `${head}${fit(job.label, room, theme.glyph.ellipsis)}`;
+}
+/** `3 turns · ↑1.2k ↓340` — what the job has spent, when it has spent anything. */
+function costLine(job, theme) {
+    const input = job.usage.input_tokens;
+    const output = job.usage.output_tokens;
+    if (job.iterations === 0 && input === 0 && output === 0)
+        return null;
+    const g = theme.glyph;
+    return [
+        `${job.iterations} ${job.iterations === 1 ? "turn" : "turns"}`,
+        `${g.caretUp}${formatTokens(input)} ${g.caretDown}${formatTokens(output)}`,
+    ].join(theme.sep);
+}
+/**
+ * The two DIFFERENT truncations above a tail, said as different sentences.
+ *
+ * `dropped` is lines the ring buffer threw away — they are GONE, and no command
+ * will bring them back. `hidden` is lines the buffer still holds that this view
+ * chose not to show — `/logs <id>` prints them. Reporting only the first would
+ * let a view that is hiding 192 retained lines announce "0 rolled off" and read
+ * as the whole story; collapsing them into one number would tell a user to run
+ * a command that cannot recover what it promises. So: both, named.
+ */
+function tailNotice(dropped, hidden, id, ellipsis) {
+    const rolled = `${dropped} line(s) rolled off the buffer`;
+    if (dropped > 0 && hidden > 0) {
+        return `${ellipsis}${rolled} (gone), ${hidden} more retained — /logs ${id}`;
+    }
+    if (dropped > 0)
+        return `${ellipsis}${rolled} — gone, not hidden`;
+    if (hidden > 0)
+        return `${ellipsis}${hidden} earlier line(s) — /logs ${id}`;
+    return null;
+}
+/**
+ * Whether a job gets the log tail: the live ones, whose log is still moving,
+ * and the failed ones, whose row says what happened but not why.
+ */
+function showsTail(status) {
+    return !isTerminal(status) || status === "failed";
+}
+/** The log tail, indented one level deeper than the job's own detail lines. */
+function tailLines(log, theme, cols, id) {
+    const lines = [];
+    const shown = log.lines.slice(-TASKS_VIEW_TAIL);
+    const notice = tailNotice(log.dropped, log.lines.length - shown.length, id, theme.glyph.ellipsis);
+    if (notice !== null)
+        lines.push(`    ${theme.muted(notice)}`);
+    for (const line of shown) {
+        // Truncated, not wrapped: a log line that folds onto a second row breaks
+        // the indent that makes this read as one job's detail rather than the next
+        // job's row.
+        const text = fit(line.text, Math.max(8, cols - 4), theme.glyph.ellipsis);
+        lines.push(`    ${line.stream === "err" ? theme.danger(text) : theme.muted(text)}`);
+    }
+    return lines;
+}
+/** One job's block: its row, then whatever level 2 has to add. */
+function jobLines(job, log, theme, cols) {
+    const lines = [jobRow(job, theme, cols)];
+    if (job.pendingApproval !== undefined) {
+        lines.push(`  ${theme.warning(fit(`needs approval: ${job.pendingApproval}`, Math.max(8, cols - 2), theme.glyph.ellipsis))}`);
+    }
+    if (job.error !== undefined) {
+        lines.push(`  ${theme.danger(fit(job.error, Math.max(8, cols - 2), theme.glyph.ellipsis))}`);
+    }
+    const cost = costLine(job, theme);
+    if (cost !== null)
+        lines.push(`  ${theme.muted(cost)}`);
+    if (log !== undefined)
+        lines.push(...tailLines(log, theme, cols, job.id));
+    return lines;
+}
+/**
+ * The standing statement about what this list is and is not.
+ *
+ * On screen rather than only in a doc comment, and shown even when the list is
+ * EMPTY — empty is what every session starts with, and it is precisely then
+ * that a user wonders where yesterday's jobs went.
+ */
+function footerLines(theme) {
+    return [
+        "",
+        theme.muted("this session only — the list is never persisted, because a saved one would name jobs that session exit already killed"),
+        theme.muted("the work outlives it: a job's id is its checkpoint run id, so `cruxy rollback <id>` reaches a finished job's changes from any later session"),
+    ];
+}
+/** The whole Tasks view, as lines. Pure: no probe, no disk, no clock. */
+export function tasksViewLines(theme, cols, jobs) {
+    const lines = [theme.heading("tasks")];
+    // Disabled is not the same claim as "no jobs ran". Say which, and say how to
+    // change it — the same sentence `/jobs` prints, so the two cannot drift.
+    if (jobs === undefined) {
+        lines.push("");
+        lines.push(theme.muted("background jobs are disabled — enable with `cruxy config set jobs.enabled true`"));
+        return lines;
+    }
+    const all = jobs.list();
+    if (all.length === 0) {
+        lines.push("");
+        lines.push(theme.muted("no background jobs this session"));
+        lines.push(...footerLines(theme));
+        return lines;
+    }
+    const live = all.filter((j) => !isTerminal(j.status)).length;
+    const needing = all.filter((j) => j.pendingApproval !== undefined).length;
+    const summary = [`${all.length} this session`, `${live} live`];
+    if (needing > 0)
+        summary.push(`${needing} needing approval`);
+    lines.push("");
+    lines.push(theme.muted(summary.join(theme.sep)));
+    // Dispatch order, not most-recent-first: this is a surface someone watches
+    // for minutes at a time, and rows that reshuffle as jobs finish would move
+    // the one being read out from under them. `/jobs` orders the same way.
+    const shown = all.slice(-TASKS_VIEW_MAX_JOBS);
+    const older = all.length - shown.length;
+    if (older > 0) {
+        lines.push(theme.muted(`${theme.glyph.ellipsis}${older} older job(s) not shown — /jobs lists every one`));
+    }
+    for (const job of shown) {
+        lines.push("");
+        // `logs` is called only with an id this same snapshot yielded, and the
+        // manager never removes a job from its map — so this cannot throw on the
+        // paint path.
+        lines.push(...jobLines(job, showsTail(job.status) ? jobs.logs(job.id) : undefined, theme, cols));
+    }
+    lines.push(...footerLines(theme));
+    return lines;
+}
+/**
+ * The Tasks view as a registered source.
+ *
+ * `jobs` is undefined when the feature is off (`jobs.enabled = false`), and the
+ * view still registers: a nav whose rows appear and disappear with config makes
+ * "where is the tasks view" a question with no answer on screen, and a user who
+ * has never enabled background jobs learns here that they exist.
+ *
+ * No `refresh`. Everything the view reads is already in memory — see the module
+ * comment. What it needs instead is {@link ViewSource.live}: a job appends to
+ * its log while the foreground sits at the prompt, and no event the renderer can
+ * see accompanies it.
+ */
+export function createTasksView(jobs) {
+    return {
+        id: "tasks",
+        label: "tasks",
+        lines: (theme, cols) => tasksViewLines(theme, cols, jobs),
+        // `liveCount`, not a scan of `list()`: this runs on every paint, and the
+        // manager already keeps the count.
+        live: () => (jobs?.liveCount() ?? 0) > 0,
+    };
+}

package/dist/tui/views.js

@@ -0,0 +1,66 @@
+/** The built-in view: the streaming conversation, and the default selection. */
+export const CONVERSATION_VIEW = "conversation";
+/**
+ * The selectable views, conversation first.
+ *
+ * Conversation is prepended here rather than registered by a caller because it
+ * is the one view the renderer already owns the content for (the scrollback
+ * buffer) and the one that must always exist: it is the default, and it is
+ * unclosable, so nothing may remove it from the list a user can get back to.
+ */
+export function viewOrder(sources) {
+    return [CONVERSATION_VIEW, ...sources.map((s) => s.id)];
+}
+/** Human label for an id — conversation's is built in, the rest self-describe. */
+export function viewLabel(id, sources) {
+    if (id === CONVERSATION_VIEW)
+        return "conversation";
+    return sources.find((s) => s.id === id)?.label ?? id;
+}
+/**
+ * The id `steps` places after `from` in the nav order, wrapping.
+ *
+ * Wrapping (rather than stopping at the ends) because this is reached from a
+ * single cycling key: a ring the user can hold down to get anywhere beats two
+ * bindings that dead-end, and the list is short enough that overshooting costs
+ * one more press. Same reasoning as the mode ring in P5.
+ */
+export function cycleView(from, sources, steps) {
+    const order = viewOrder(sources);
+    const at = order.indexOf(from);
+    // An id that is no longer registered resolves to the conversation rather than
+    // to `order[-1]`: a view can be attached and re-attached, and the fallback has
+    // to be the one that always exists.
+    if (at < 0)
+        return CONVERSATION_VIEW;
+    const next = (at + (steps % order.length) + order.length) % order.length;
+    return order[next];
+}
+/**
+ * The sidebar's nav block: one row per view, the selected one marked.
+ *
+ * FOCUS IS DRAWN, not implied. When the sidebar holds the keyboard the heading
+ * says so and the selected row is highlighted rather than merely marked —
+ * otherwise "which keys go where" is invisible state, and the arrow keys
+ * silently mean two different things depending on something the screen never
+ * showed. The marker glyph stays in both states so a screen reader and a
+ * NO_COLOR terminal can still tell which row is current.
+ */
+export function navLines(theme, sources, selected, focused) {
+    // A WORD, not a glyph. This has to survive NO_COLOR, CRUXY_ASCII and a screen
+    // reader, and "focus" carries the meaning in all three where an arrow or a
+    // colour carries it in none. It also fits the 18-column sidebar.
+    const heading = focused ? "views (focus)" : "views";
+    const lines = [focused ? theme.accent(heading) : theme.strong(heading), ""];
+    for (const id of viewOrder(sources)) {
+        const label = viewLabel(id, sources);
+        const current = id === selected;
+        const row = `${current ? theme.glyph.pointer : " "} ${label}`;
+        if (!current) {
+            lines.push(theme.muted(row));
+            continue;
+        }
+        lines.push(focused ? theme.accent(row) : theme.strong(row));
+    }
+    return lines;
+}

package/dist/utils/disk.js

@@ -0,0 +1,95 @@
+import { statfsSync } from "node:fs";
+import { statfs } from "node:fs/promises";
+const GIB = 1024 ** 3;
+/** Below this, a run that shadow-copies a repo can plausibly fail. */
+const LOW_FREE_BYTES = 5 * GIB;
+/** Below this, assume the next sizeable write fails. */
+const CRITICAL_FREE_BYTES = 1 * GIB;
+export function capacityLevel(capacity) {
+    if (capacity.freeBytes < CRITICAL_FREE_BYTES)
+        return "critical";
+    if (capacity.freeBytes < LOW_FREE_BYTES)
+        return "low";
+    return "ok";
+}
+/**
+ * Turn a `statfs` result into a capacity, or `undefined` when it cannot say
+ * anything true.
+ *
+ * `blocks === 0` is the guard that matters: some pseudo-filesystems report a
+ * zero total, and a percentage derived from it is `NaN` or `Infinity` — a
+ * "0% free" that means "we have no idea" is the single worst thing this could
+ * render, because it is indistinguishable from a genuinely full disk.
+ *
+ * Exported for the test that pins that guard: it is the one branch here that
+ * cannot be reached through a real `statfs` on any machine CI runs on.
+ */
+export function capacityFromStats(stats) {
+    const blockSize = Number(stats.bsize);
+    const blocks = Number(stats.blocks);
+    const available = Number(stats.bavail);
+    if (!(blockSize > 0) || !(blocks > 0) || !(available >= 0))
+        return undefined;
+    const totalBytes = blocks * blockSize;
+    const freeBytes = available * blockSize;
+    return {
+        freeBytes,
+        totalBytes,
+        freePercent: Math.floor((freeBytes / totalBytes) * 100),
+    };
+}
+/**
+ * Capacity of the filesystem holding `path`, or `undefined` if it can't be
+ * read (a path that doesn't exist, a platform or mount that won't answer).
+ *
+ * ASYNC because a `statfs` is only microseconds on a local disk — the whole
+ * reason this is affordable — but can block for SECONDS on an unresponsive
+ * network mount, and someone will eventually run cruxy in a repo on NFS. The
+ * cost model that justifies the feature holds for the common case; the API is
+ * shaped for the uncommon one.
+ */
+export async function readDiskCapacity(path) {
+    try {
+        return capacityFromStats(await statfs(path));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The synchronous read, for the one caller that is allowed one: a command the
+ * user just typed, which has no frame to lose and every reason to print a real
+ * answer instead of "checking…". Never call this from a paint path.
+ */
+export function readDiskCapacitySync(path) {
+    try {
+        return capacityFromStats(statfsSync(path));
+    }
+    catch {
+        return undefined;
+    }
+}
+const UNITS = ["B", "KiB", "MiB", "GiB", "TiB", "PiB"];
+/**
+ * `8.1 GiB`, `465 GiB`, `912 MiB`.
+ *
+ * Binary units with binary labels. `GB` for 2^30 is the ambiguity that makes
+ * people distrust a number they were about to act on; if the unit is 1024-based
+ * the label says so.
+ */
+export function formatBytes(bytes) {
+    let value = Math.max(0, bytes);
+    let unit = 0;
+    while (value >= 1024 && unit < UNITS.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    // One decimal only while it carries information: "8.1 GiB" is a different
+    // amount from "8 GiB", "465.3 GiB" is not meaningfully different from "465".
+    const digits = unit > 0 && value < 10 ? 1 : 0;
+    return `${value.toFixed(digits)} ${UNITS[unit]}`;
+}
+/** `2% free · 8.1 GiB of 465 GiB` — the percentage first, since that's the read. */
+export function formatCapacity(capacity) {
+    return `${capacity.freePercent}% free · ${formatBytes(capacity.freeBytes)} of ${formatBytes(capacity.totalBytes)}`;
+}