@aragon-agent/cli 0.6.38 → 0.6.39

package/dist/ui/layout/header-left.js

@@ -0,0 +1,206 @@
+/**
+ * The header's LEFT half budget (tui-shortcut-drawer-and-task-summary §4.3).
+ *
+ * ASCII ONLY: `src/ui/**` is inside the glyph scanner's scope.
+ *
+ * WHY A PLANNER (the same argument `header-hints.ts` makes one file over): the
+ * left half used to be a `<Text wrap="truncate">` over four clauses with no
+ * clause-level arithmetic anywhere, so the only thing that ever decided what got
+ * cut was the terminal. Adding a fifth clause - the task summary - to that shape
+ * produces a header where the summary silently eats the directory name on an
+ * 80-column terminal and NO ASSERTION WOULD SEE IT, because losing trailing
+ * characters is invisible to a snapshot test.
+ *
+ * THE PRIORITY ORDER IS THE DESIGN: brand, then `provider:model`, then cwd, then
+ * the summary, with the key symbol reserved up front. The summary is the only
+ * clause that is allowed to disappear entirely - it is the newest and the least
+ * load-bearing (D-2) - and it is dropped rather than rendered as `...`, because a
+ * cell holding three dots spends eight columns to say nothing.
+ */
+import { cellWidth, fitCells } from './cells.js';
+import { TASK_SUMMARY_LIMITS } from '../../fast/limits.js';
+export const HEADER_LEFT_LIMITS = {
+    /** The `AragonAgent` word mark, the same 13 `header-hints.ts` documents. */
+    brandCells: 13,
+    /** Blank cells between two left clauses. */
+    gapCells: 2,
+    /** The has-key symbol (1 cell) plus its gap, always reserved. */
+    keyCells: 3,
+    /** Below this the model clause is dropped rather than rendered as `a...`. */
+    modelMinCells: 8,
+    /** Below this the cwd clause is dropped. */
+    cwdMinCells: 8,
+    /** Below this the summary is dropped instead of rendered as `...`. */
+    summaryMinCells: 8,
+    /**
+     * The separator that belongs to the SUMMARY rather than to the general gap:
+     * two spaces, the mid dot and one space. It is reserved together with the label
+     * so a summary can never be drawn without its dot, or the dot without it.
+     */
+    summaryGapCells: 4,
+};
+/** `provider:model`, the clause `Header` prints after the word mark. */
+export function modelClause(provider, model) {
+    return `${provider}:${model}`;
+}
+/** The directory name, falling back to the whole path for a bare root. */
+export function cwdClause(cwd, basename) {
+    return basename(cwd) || cwd;
+}
+/**
+ * Allocate the left half.
+ *
+ * THE ORDER OF THE FOUR STEPS IS THE PRIORITY (D-2):
+ *  1. reserve the word mark, its gap and the key symbol - they are never cut;
+ *  2. `provider:model`, down to `modelMinCells`, then dropped;
+ *  3. cwd, down to `cwdMinCells`, then dropped;
+ *  4. the summary, capped at `TASK_SUMMARY_LIMITS.maxCells`, dropped below
+ *     `summaryMinCells` and reported as `narrow`.
+ *
+ * THE LADDER IS EXPLICIT RATHER THAN GREEDY, and that is a correction to v2's
+ * algorithm, which funded the summary out of the reserved budget and could therefore
+ * show a label on a row where the model name had already been dropped. Four
+ * presence sets are tried from most to least complete; within a set the LAST clause
+ * gives way first, each only down to its own minimum. The first set that fits wins.
+ *
+ * Every returned text already MEASURES its reported width, so `Header` renders
+ * cells rather than hoping for them.
+ */
+export function planHeaderLeft(input) {
+    const leftCells = Number.isFinite(input.leftCells) ? Math.max(0, Math.floor(input.leftCells)) : 0;
+    const empty = {
+        text: { model: '', cwd: '', summary: '' },
+        cells: { model: 0, cwd: 0, summary: 0 },
+        summaryReason: input.summaryEnabled ? 'empty' : 'disabled',
+    };
+    const gap = HEADER_LEFT_LIMITS.gapCells;
+    // Everything the planner never touches, taken off the top so no later step can
+    // borrow from it.
+    // `keyCells` already contains the gap before the symbol, so this is the whole fixed
+    // cost and every clause below pays its own gap.
+    const budget = leftCells - HEADER_LEFT_LIMITS.brandCells - HEADER_LEFT_LIMITS.keyCells;
+    if (budget <= 0) {
+        return {
+            ...empty,
+            summaryReason: input.summaryEnabled
+                ? (input.summary === null ? 'empty' : 'narrow')
+                : 'disabled',
+        };
+    }
+    const model = modelClause(input.provider, input.model);
+    const summaryText = input.summary?.text ?? '';
+    const wantsSummary = input.summaryEnabled && input.summary !== null;
+    /** Desired width and the floor this clause may be cut to. */
+    const clause = (text, floor) => ({
+        want: cellWidth(text),
+        floor: Math.min(cellWidth(text), floor),
+    });
+    const modelWanted = clause(model, HEADER_LEFT_LIMITS.modelMinCells);
+    const cwdWanted = clause(input.cwd, HEADER_LEFT_LIMITS.cwdMinCells);
+    const summaryWanted = {
+        want: Math.min(cellWidth(summaryText), TASK_SUMMARY_LIMITS.maxCells),
+        // A label is never shown below its minimum: a three-cell label is a fragment,
+        // not a label, and the cell is dropped instead.
+        floor: HEADER_LEFT_LIMITS.summaryMinCells,
+    };
+    const sets = [
+        ['model', 'cwd', ...(wantsSummary ? ['summary'] : [])],
+        ['model', 'cwd'],
+        ['model'],
+        [],
+    ];
+    const wanted = { model: modelWanted, cwd: cwdWanted, summary: summaryWanted };
+    for (const set of sets) {
+        const assigned = fitClauses(set, wanted, budget, gap);
+        if (assigned === null)
+            continue;
+        const modelCells = assigned.model ?? 0;
+        const cwdCells = assigned.cwd ?? 0;
+        const summaryCells = assigned.summary ?? 0;
+        let summaryReason = 'empty';
+        if (!input.summaryEnabled)
+            summaryReason = 'disabled';
+        else if (input.summary === null)
+            summaryReason = 'empty';
+        else if (summaryCells === 0)
+            summaryReason = 'narrow';
+        else
+            summaryReason = 'ok';
+        return {
+            text: {
+                model: modelCells > 0 ? fitCells(model, modelCells, input.ellipsis) : '',
+                cwd: cwdCells > 0 ? fitCells(input.cwd, cwdCells, input.ellipsis) : '',
+                summary: summaryCells > 0 ? fitCells(summaryText, summaryCells, input.ellipsis) : '',
+            },
+            cells: { model: modelCells, cwd: cwdCells, summary: summaryCells },
+            summaryReason,
+        };
+    }
+    return empty;
+}
+/**
+ * Fit one presence set into `budget`, cutting from the LAST clause inward.
+ *
+ * Returns `null` when the set cannot fit even at every clause's floor, which is the
+ * signal to try the next (smaller) set. `null` rather than a partial result because
+ * "the summary was dropped" and "the summary does not fit" must be the same fact to
+ * the caller, and only the set composition may express it.
+ */
+function fitClauses(set, wanted, budget, gap) {
+    const widths = { model: 0, cwd: 0, summary: 0 };
+    let cost = 0;
+    for (const key of set) {
+        widths[key] = wanted[key].want;
+        // EVERY CLAUSE PAYS ITS OWN SEPARATOR, including the first: the row renders
+        // `word mark, gap, clause, gap, clause, gap, key`, so a one-clause plan still
+        // spends a gap on each side of that clause.
+        cost += (key === 'summary' ? HEADER_LEFT_LIMITS.summaryGapCells : gap)
+            + wanted[key].want;
+    }
+    let excess = cost - budget;
+    for (let index = set.length - 1; index >= 0 && excess > 0; index -= 1) {
+        const key = set[index];
+        const room = widths[key] - wanted[key].floor;
+        if (room <= 0)
+            continue;
+        const cut = Math.min(room, excess);
+        widths[key] -= cut;
+        excess -= cut;
+    }
+    return excess > 0 ? null : widths;
+}
+/**
+ * Cells the plan actually spends, for the row invariant:
+ * `brand + gap + model + gap + cwd + gap + summary + key <= leftCells`.
+ *
+ * Exported so `header-left.test.ts` can assert the inequality against the SAME
+ * arithmetic the renderer uses instead of re-deriving it in the test (which is how
+ * the two drift apart).
+ */
+export function planHeaderLeftCells(plan) {
+    const { gapCells, brandCells, keyCells, summaryGapCells } = HEADER_LEFT_LIMITS;
+    // The word mark and the key symbol are always drawn; every clause pays its own gap.
+    // The gap before the key is INSIDE `keyCells`, so it is counted once here and never
+    // again after a clause - the double count that made a one-clause plan read two cells
+    // wider than it renders.
+    let cells = brandCells + keyCells;
+    if (plan.cells.model > 0)
+        cells += gapCells + plan.cells.model;
+    if (plan.cells.cwd > 0)
+        cells += gapCells + plan.cells.cwd;
+    // The summary's separator carries the dot, so it is wider than the general gap.
+    if (plan.cells.summary > 0)
+        cells += summaryGapCells + plan.cells.summary;
+    return cells;
+}
+/**
+ * The fixed cells a plan needs before any clause can appear: the word mark plus the
+ * key symbol and its gap.
+ *
+ * Below this the row does not "spend too much", it simply cannot show a clause - the
+ * renderer truncates the overflow and `Header`'s own `wrap="truncate"` keeps that from
+ * spilling. Stating it as a constant keeps the invariant in the tests honest:
+ * `planHeaderLeftCells(plan) <= max(leftCells, HEADER_LEFT_BASELINE)`.
+ */
+export const HEADER_LEFT_BASELINE = HEADER_LEFT_LIMITS.brandCells
+    + HEADER_LEFT_LIMITS.keyCells;

package/dist/ui/layout/shortcut-panel-layout.d.ts

@@ -0,0 +1,191 @@
+/**
+ * The shortcut drawer's geometry and row layout
+ * (tui-shortcut-drawer-and-task-summary §4.5).
+ *
+ * ASCII ONLY: `src/ui/**` is inside the glyph scanner's scope, so every symbol
+ * this module emits arrives as a `glyphs` field and is never spelled here.
+ *
+ * PURE AND TOTAL. No Ink, no clock, no terminal: the drawer component renders
+ * what this returns, `OverlayFrame` slices the window this function DERIVED, and
+ * `shortcut-panel-layout.test.ts` pins the arithmetic directly. That split is the
+ * whole defence against P0-1, which was not a rendering bug: v1 hand-fixed the key
+ * column at 21 cells, which left six cells for the keyword at 80 columns, so every
+ * keyword was truncated to `promp...` while a "does not overflow" assertion stayed
+ * green. The column is therefore DERIVED from the table, and a keyword that does
+ * not fit makes its row STACK rather than be cut.
+ *
+ * THERE IS EXACTLY ONE WINDOW AUTHORITY: `cursor`. v1 took both `cursor` and
+ * `scrollOffset`, which meant paging could leave the selected row - and the detail
+ * line that belongs to it - off screen. Paging now moves the CURSOR by a page and
+ * the window is the smallest one containing it.
+ */
+import { type OverlayWindow } from './overlay-window.js';
+import { type ShortcutEntry } from '../shortcuts.js';
+export declare const SHORTCUT_PANEL_LIMITS: {
+    /** Below this the drawer is full width: a 30-cell bar on a 40-cell screen is noise. */
+    readonly minSplitCols: 64;
+    /** Fraction of the terminal the drawer takes when it IS a drawer. */
+    readonly widthFraction: 0.34;
+    readonly minWidth: 30;
+    readonly maxWidth: 46;
+    /** Rail (1 cell) + `paddingLeft` (1 cell) that `OverlayFrame` spends below 48 columns. */
+    readonly railCells: 2;
+    /** Border (2 cells) + `paddingX` (2 cells) that `OverlayFrame` spends at or above 48. */
+    readonly boxCells: 4;
+    /**
+     * The key column is DERIVED: `min(longestKeys, ceil(listCells * 0.55))`.
+     *
+     * A hard 21 is what turned `prompt library` into `promp...` at 80 columns. The
+     * share is a ceiling, not a target: a table of short keys gets a narrow key
+     * column and the leftover width goes to the keyword.
+     */
+    readonly keyColumnShare: 0.55;
+    /** The keyword column must be at least this wide, or the row stacks. */
+    readonly keywordMinCells: 8;
+    /** Hard ceiling for a keyword string; a longer one is a spec bug, not a width problem. */
+    readonly keywordMaxCells: 10;
+    /** Gap between the key column and the keyword column. */
+    readonly keyGapCells: 1;
+    /** Indent for the selected row's detail lines, and for a stacked keyword. */
+    readonly detailIndent: 2;
+    /** Title + footer rows are chrome and are spent out of the row budget. */
+    readonly chromeRows: 2;
+    /** The task section is capped so the key list always gets the majority of the panel. */
+    readonly taskMaxRows: 2;
+    /**
+     * ABOVE THIS BODY HEIGHT THE GROUP HEADERS GET THEIR OWN ROWS.
+     *
+     * Below it they are dropped entirely - not compressed into `---- GROUP ----`
+     * separators, which was v2's rule and left FOUR entry rows visible on an
+     * 80x24 terminal (title + task + rule + five separators = 9 of 13 body rows).
+     * See `spec.md`'s `## 实施过程发现的方案缺陷` note 1: the ordering still runs
+     * COMPOSE -> RUN -> PANELS -> SESSION -> VIEW, and the requirement ("list every
+     * shortcut from top to bottom") is met by the entries themselves.
+     */
+    readonly groupHeaderMinRows: 18;
+    /** The longest detail line the selected row may grow to. */
+    readonly detailMaxRows: 2;
+};
+/**
+ * The drawer's width in columns.
+ *
+ * `cols < 64` is FULL WIDTH on purpose: at 40 columns a right-aligned 30-cell bar
+ * spends 10 of the user's columns on empty space. The clamp mirrors
+ * `rail.ts::todoRailWidth` (same shape, same reason).
+ */
+export declare function shortcutPanelWidth(cols: number): number;
+/**
+ * Cells the drawer may draw on INSIDE its frame.
+ *
+ * THE FORM IS DECIDED BY THE TERMINAL, exactly as `OverlayFrame` decides it
+ * (`cols >= BORDERLESS_COLS`), so this function takes the same `cols` the frame
+ * receives. Passing the panel's own width instead would make a 46-cell drawer on
+ * a 200-column terminal fall back to the rail form for ever, because 46 < 48.
+ */
+export declare function shortcutPanelContentCells(cols: number): number;
+/** One rendered row. `text` already measures at most the panel's content width. */
+export interface ShortcutRow {
+    /** `entry` = key + keyword on one row; `stacked` = key alone, keyword below. */
+    kind: 'task' | 'rule' | 'group' | 'entry' | 'stacked' | 'keyword' | 'detail';
+    text: string;
+    /** Which entry a `detail` / `keyword` row belongs to; `null` for every other kind. */
+    entryId: string | null;
+    tone: 'accent' | 'primary' | 'muted' | 'dim';
+}
+/** The task section's inputs, already flattened by the caller. */
+export interface ShortcutTaskSection {
+    /** The label, or `null` when there is none yet. */
+    text: string | null;
+    /** `model` / `fallback`, so the row can be coloured by provenance. */
+    tone: 'model' | 'fallback' | null;
+    /** Why it is a fallback, or `null`. */
+    reason: string | null;
+    /** `provider:model`, or `''`. */
+    by: string;
+    /** Age in ms, or `null` when unknown. */
+    ageMs: number | null;
+    /** `false` when `taskSummary.enabled` is off. */
+    enabled: boolean;
+    /** A call is in flight. */
+    pending: boolean;
+}
+export interface BuildShortcutRowsInput {
+    cols: number;
+    /** Body rows available INSIDE the frame (`OverlayFrame` already subtracted its chrome). */
+    rows: number;
+    /** Index into the FILTERED entry list. The one authority for the window. */
+    cursor: number;
+    /**
+     * THE ENTRIES ARRIVE FILTERED AND WITH THEIR AVAILABILITY, so this module takes
+     * neither a `query` nor a `context` for them (review fix RF-2). It used to accept
+     * both - and `detailsExpanded` as well - and read none of them, which is the exact
+     * "second source of truth that silently does nothing" its own 0-3 rule forbids: a
+     * caller could pass `query: 'git'` and get the unfiltered list with nothing
+     * failing.
+     */
+    entries: readonly ShortcutEntry[];
+    task: ShortcutTaskSection;
+    /** Per-entry availability, so an unavailable row renders dim and explains itself. */
+    entryAvailable?: (entry: ShortcutEntry) => boolean;
+    /** The sentence appended to an unavailable row's detail line. */
+    unavailableReason?: string;
+    glyphs: {
+        ellipsis: string;
+        cursor: string;
+        hrule: string;
+        midDot: string;
+    };
+}
+export interface BuildShortcutRowsResult {
+    rows: ShortcutRow[];
+    window: OverlayWindow;
+    /** Row index of the selected entry; equal to `window.start + 0` at the top. */
+    cursorRow: number;
+    /** Total rows the panel holds, which is what the frame's position indicator counts. */
+    total: number;
+    /** The footer string; `OverlayFrame`'s `hint`, and chrome rather than a row. */
+    hint: string;
+}
+/** Column widths for one geometry. Exported so the tests can assert them directly. */
+export interface ShortcutColumns {
+    /** The panel's own width. */
+    width: number;
+    /** Content cells inside the frame. */
+    available: number;
+    /** Cells left for a list row after the cursor column is spent. */
+    listCells: number;
+    keyCells: number;
+    keywordCells: number;
+    /** True when no entry fits the two-column form and every row stacks. */
+    stacked: boolean;
+}
+/**
+ * Derive the two columns (P0-1).
+ *
+ * `stacked` is a GLOBAL flag only when the keyword column is too narrow for any
+ * keyword at all; otherwise stacking is decided per row, so one long binding
+ * (`Shift+Up / Shift+Down`, 20 cells) does not cost the other thirty rows a line.
+ */
+export declare function shortcutColumns(cols: number, entries: readonly ShortcutEntry[], glyphs: {
+    cursor: string;
+}): ShortcutColumns;
+/**
+ * The footer, built by DROPPING clauses from the right (never by re-wording).
+ *
+ * `Esc close` is never dropped: it is the one thing a user must be able to find on
+ * a terminal too narrow to explain anything else. The rest go in a fixed order so
+ * the footer is stable across resizes instead of shuffling.
+ */
+export declare function shortcutFooter(cols: number, glyphs: {
+    midDot: string;
+}, opts?: {
+    canRefresh: boolean;
+}): string;
+/**
+ * Build every row the drawer can show, and derive the window from the cursor.
+ *
+ * @param input.cols Terminal columns (the frame receives the same number).
+ * @param input.rows Body rows inside the frame - `overlayBodyRows(maxRows, cols)`.
+ * @param input.cursor Index into `input.entries`; clamped, never trusted.
+ */
+export declare function buildShortcutRows(input: BuildShortcutRowsInput): BuildShortcutRowsResult;