@aragon-agent/cli 0.6.44 → 0.6.46

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

@@ -0,0 +1,85 @@
+/**
+ * The legion panel's geometry: every decision `GovernancePanel` draws (governance-mode
+ * section 10.3), made in pure code so it can be tested without a terminal.
+ *
+ * Pure and total: no Ink, no clock (`now` is injected), no I/O. ASCII ONLY.
+ *
+ * THE COMPONENT ONLY COLOURS AND PLACES. Tier, header, step strip, roster columns and
+ * cell text, overflow line and ticker are all computed here; a test that wants to know
+ * what the panel says at 80 columns asks this module and never renders.
+ *
+ * FOUR TIERS, chosen from the terminal's size alone (`selectTier`):
+ *   full      >= 100 cols and >= 26 rows   header + step strip + roster (with gauge) + ticker
+ *   standard  80-99 cols (rows >= 26)      the same without the activity column
+ *   compact   60-79 cols, or rows < 26     header with the stage name + a bare roster
+ *   minimal   < 60 cols or rows < 20       ONE line
+ * and a tier that does not fit the caller's `availableRows` steps DOWN rather than
+ * overflowing - the band clamps the panel's height, and a clipped last row is the one
+ * outcome worse than a smaller tier.
+ */
+import type { GovernanceSnapshot } from '../../governance/types.js';
+import type { Glyphs } from '../glyphs.js';
+import { type EliminatedSince, type Segment } from '../governance-status.js';
+import { type PanelTier, type RosterColumn, type RosterLine } from './governance-roster.js';
+export type { PanelTier } from './governance-roster.js';
+export declare const PANEL_TIER_COLS: {
+    readonly full: 100;
+    readonly standard: 80;
+    readonly compact: 60;
+};
+export declare const PANEL_TIER_ROWS: {
+    readonly full: 26;
+    readonly minimal: 20;
+};
+/** Roster rows shown: `clamp(rows - 16, 2, 10)` (spec 10.3). */
+export declare function maxRosterRows(rows: number): number;
+/** The tier the terminal's size asks for, before any height budget is applied. */
+export declare function selectTier(cols: number, rows: number): PanelTier;
+/** One display line: a flexible left run and an optional right-anchored run. */
+export interface PanelLine {
+    left: Segment[];
+    right: Segment[];
+    /** Cells the right run occupies (0 when there is none). */
+    rightCells: number;
+}
+export interface GovernancePanelInput {
+    cols: number;
+    rows: number;
+    snapshot: GovernanceSnapshot | null;
+    glyphs: Glyphs;
+    reducedMotion: boolean;
+    now: number;
+    /** `panel` while a stage runs; `run-strip` between stages (header + step strip only). */
+    mode?: 'panel' | 'run-strip';
+    /** Height budget the caller can spare; tiers step down to fit. Default unlimited. */
+    availableRows?: number;
+    /** First-seen-eliminated phases, so a replaced member leaves after one phase. */
+    eliminatedSince?: EliminatedSince;
+}
+export interface GovernancePanelLayout {
+    tier: PanelTier;
+    mode: 'panel' | 'run-strip';
+    /** Terminal columns this layout was built for. */
+    cols: number;
+    /** `cols` minus the margin: the budget every line is planned against. */
+    innerCols: number;
+    height: number;
+    header: PanelLine | null;
+    pipeline: PanelLine | null;
+    /** Width of the horizontal rule above and below the roster; 0 = no rules. */
+    ruleCells: number;
+    columns: RosterColumn[];
+    rosterRows: RosterLine[];
+    overflow: string | null;
+    ticker: PanelLine[];
+}
+export declare function segmentsCells(segments: readonly Segment[]): number;
+/**
+ * Plan the panel for a terminal and a snapshot.
+ *
+ * `null` snapshot, or a finished run, plans to height 0 (nothing mounts - zero rows and
+ * zero layout shift, the `TeamPanel` D-11 rule). The caller's `availableRows` is a
+ * ceiling: tiers step down until one fits, and `minimal` is a single row or, with no row to
+ * spare, nothing.
+ */
+export declare function buildGovernancePanelLayout(input: GovernancePanelInput): GovernancePanelLayout;

package/dist/ui/layout/governance-panel.js

@@ -0,0 +1,358 @@
+/**
+ * The legion panel's geometry: every decision `GovernancePanel` draws (governance-mode
+ * section 10.3), made in pure code so it can be tested without a terminal.
+ *
+ * Pure and total: no Ink, no clock (`now` is injected), no I/O. ASCII ONLY.
+ *
+ * THE COMPONENT ONLY COLOURS AND PLACES. Tier, header, step strip, roster columns and
+ * cell text, overflow line and ticker are all computed here; a test that wants to know
+ * what the panel says at 80 columns asks this module and never renders.
+ *
+ * FOUR TIERS, chosen from the terminal's size alone (`selectTier`):
+ *   full      >= 100 cols and >= 26 rows   header + step strip + roster (with gauge) + ticker
+ *   standard  80-99 cols (rows >= 26)      the same without the activity column
+ *   compact   60-79 cols, or rows < 26     header with the stage name + a bare roster
+ *   minimal   < 60 cols or rows < 20       ONE line
+ * and a tier that does not fit the caller's `availableRows` steps DOWN rather than
+ * overflowing - the band clamps the panel's height, and a clipped last row is the one
+ * outcome worse than a smaller tier.
+ */
+import { formatCost, formatDuration, formatTokens } from '../../agent/usage.js';
+import { activeStepKey, isFinishedRun, isPausePending, isRetired, segment, shortRunId, signedDeltaText, sortRoster, teamTokens, workingCount, } from '../governance-status.js';
+import { GOV_TITLE, PANEL_BOARD_HINT, PANEL_HEALTH_LABEL, PANEL_LEDGER_LABEL, PANEL_TOKEN_UNIT, PIPELINE_LABEL, STATUS_WORD, moreText, phaseLongText, pausingText, phaseText, workingCountText, } from '../governance-copy.js';
+import { cellWidth, fitCells } from './cells.js';
+import { PANEL_MARGIN_CELLS, buildRosterLine, columnPlan, markerCells, } from './governance-roster.js';
+export const PANEL_TIER_COLS = { full: 100, standard: 80, compact: 60 };
+export const PANEL_TIER_ROWS = { full: 26, minimal: 20 };
+/** Roster rows shown: `clamp(rows - 16, 2, 10)` (spec 10.3). */
+export function maxRosterRows(rows) {
+    const free = Number.isFinite(rows) ? Math.floor(rows) - 16 : 0;
+    return Math.min(10, Math.max(2, free));
+}
+/** The tier the terminal's size asks for, before any height budget is applied. */
+export function selectTier(cols, rows) {
+    if (cols < PANEL_TIER_COLS.compact || rows < PANEL_TIER_ROWS.minimal)
+        return 'minimal';
+    if (rows < PANEL_TIER_ROWS.full || cols < PANEL_TIER_COLS.standard)
+        return 'compact';
+    return cols >= PANEL_TIER_COLS.full ? 'full' : 'standard';
+}
+const NEXT_SMALLER = {
+    full: 'standard',
+    standard: 'compact',
+    compact: 'minimal',
+    minimal: null,
+};
+const EMPTY = {
+    tier: 'minimal',
+    mode: 'panel',
+    cols: 0,
+    innerCols: 0,
+    height: 0,
+    header: null,
+    pipeline: null,
+    ruleCells: 0,
+    columns: [],
+    rosterRows: [],
+    overflow: null,
+    ticker: [],
+};
+function nonNegativeInt(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+export function segmentsCells(segments) {
+    return segments.reduce((sum, part) => sum + cellWidth(part.text), 0);
+}
+function line(left, right = []) {
+    return { left, right, rightCells: segmentsCells(right) };
+}
+const SEPARATOR = ' ';
+/** The parts joined by the glyph tier's middle dot, the dot itself in `muted`. */
+function joined(parts, glyphs) {
+    const out = [];
+    parts.forEach((part, index) => {
+        if (index > 0)
+            out.push(segment(`${SEPARATOR}${glyphs.midDot}${SEPARATOR}`, 'muted'));
+        out.push(part);
+    });
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Header
+// ---------------------------------------------------------------------------
+function stageWord(snapshot) {
+    const key = activeStepKey(snapshot);
+    return key === null ? '' : PIPELINE_LABEL[key];
+}
+function statusSegments(snapshot) {
+    // A pending `/gov pause` outranks the plain status: the run is still executing, and the
+    // one thing the user needs to see is that the stop is coming and nothing is killed.
+    if (isPausePending(snapshot)) {
+        return [segment(pausingText(stageWord(snapshot)), 'warn', true)];
+    }
+    if (snapshot.status === 'paused')
+        return [segment(STATUS_WORD.paused, 'warn', true)];
+    if (snapshot.status === 'escalated')
+        return [segment(STATUS_WORD.escalated, 'warn', true)];
+    return [];
+}
+/** The right-hand figures, most expendable last: cost, then tokens, then health. */
+function headerFigures(snapshot, withCost) {
+    const figures = [];
+    if (snapshot.health !== null) {
+        figures.push([
+            segment(`${PANEL_HEALTH_LABEL} `, 'muted'),
+            segment(String(Math.round(snapshot.health)), 'text', true),
+        ]);
+    }
+    figures.push([segment(`${formatTokens(teamTokens(snapshot))} ${PANEL_TOKEN_UNIT}`, 'muted')]);
+    if (withCost && snapshot.usage.costUsd !== null) {
+        figures.push([segment(formatCost(snapshot.usage.costUsd), 'muted')]);
+    }
+    return figures;
+}
+function spaced(figures) {
+    const out = [];
+    figures.forEach((figure, index) => {
+        if (index > 0)
+            out.push(segment('   ', 'muted'));
+        out.push(...figure);
+    });
+    return out;
+}
+function buildHeader(snapshot, inner, now, glyphs, withCost) {
+    const elapsed = formatDuration(Math.max(0, now - snapshot.startedAt));
+    const parts = [
+        segment(`run ${shortRunId(snapshot.runId)}`, 'muted'),
+        segment(phaseLongText(snapshot.phase, snapshot.phaseCount), 'text'),
+    ];
+    // `pausing after REVIEW` already names the stage; saying it twice is noise on a short row.
+    const stage = isPausePending(snapshot) ? '' : stageWord(snapshot);
+    if (stage !== '')
+        parts.push(segment(stage, 'primary', true));
+    parts.push(segment(elapsed, 'muted'));
+    const title = [segment(GOV_TITLE, 'govern', true), ...statusSegments(snapshot).flatMap((s) => [
+            segment(' ', 'muted'),
+            s,
+        ])];
+    const left = [...title, segment('  ', 'muted'), ...joined(parts, glyphs)];
+    const figures = headerFigures(snapshot, withCost);
+    while (figures.length > 0) {
+        const right = spaced(figures);
+        if (segmentsCells(left) + segmentsCells(right) + 2 <= inner)
+            return line(left, right);
+        figures.pop();
+    }
+    return line(left);
+}
+/** Compact header: the stage name replaces the step strip (spec 10.3). */
+function buildCompactHeader(snapshot, inner, now, glyphs) {
+    const parts = [segment(phaseText(snapshot.phase, snapshot.phaseCount), 'text')];
+    const stage = isPausePending(snapshot) ? '' : stageWord(snapshot);
+    if (stage !== '')
+        parts.push(segment(stage, 'primary', true));
+    parts.push(segment(formatDuration(Math.max(0, now - snapshot.startedAt)), 'muted'));
+    const title = [segment(GOV_TITLE, 'govern', true), ...statusSegments(snapshot).flatMap((s) => [
+            segment(' ', 'muted'),
+            s,
+        ])];
+    const left = [...title, segment(' ', 'muted'), ...joined(parts, glyphs)];
+    if (snapshot.health === null)
+        return line(left);
+    const right = [
+        segment(`${PANEL_HEALTH_LABEL} `, 'muted'),
+        segment(String(Math.round(snapshot.health)), 'text', true),
+    ];
+    return segmentsCells(left) + segmentsCells(right) + 2 <= inner ? line(left, right) : line(left);
+}
+// ---------------------------------------------------------------------------
+// Step strip
+// ---------------------------------------------------------------------------
+function stepSegments(snapshot, glyphs) {
+    return snapshot.pipeline.map((step) => {
+        const label = PIPELINE_LABEL[step.key];
+        if (step.state === 'done') {
+            return [segment(label, 'ok'), segment(` ${glyphs.check}`, 'ok')];
+        }
+        if (step.state === 'active')
+            return [segment(`${glyphs.cursor}${label}`, 'govern', true)];
+        return [segment(label, 'muted')];
+    });
+}
+function flattenSteps(steps, glyphs, leadingGap) {
+    const out = leadingGap
+        ? [segment(`${glyphs.ellipsis} ${glyphs.hrule} `, 'muted')]
+        : [];
+    steps.forEach((step, index) => {
+        if (index > 0)
+            out.push(segment(` ${glyphs.hrule} `, 'border'));
+        out.push(...step);
+    });
+    return out;
+}
+/**
+ * The step strip, with the rework note right-anchored. A strip too wide for the row loses
+ * its OLDEST steps first (they are the ones already done), marked with a leading ellipsis,
+ * so the current step and what is still to come always stay visible.
+ */
+function buildPipeline(snapshot, inner, glyphs) {
+    const steps = stepSegments(snapshot, glyphs);
+    if (steps.length === 0)
+        return null;
+    const note = snapshot.reworkNote === null ? [] : [segment(snapshot.reworkNote, 'warn')];
+    const noteCells = segmentsCells(note);
+    const activeIndex = Math.max(0, snapshot.pipeline.findIndex((s) => s.state === 'active'));
+    for (const withNote of note.length > 0 ? [true, false] : [false]) {
+        const budget = inner - (withNote ? noteCells + 2 : 0);
+        for (let start = 0; start <= Math.min(activeIndex, steps.length - 1); start += 1) {
+            const left = flattenSteps(steps.slice(start), glyphs, start > 0);
+            if (segmentsCells(left) <= budget)
+                return line(left, withNote ? note : []);
+        }
+    }
+    return line(flattenSteps(steps.slice(activeIndex), glyphs, activeIndex > 0));
+}
+// ---------------------------------------------------------------------------
+// Ticker
+// ---------------------------------------------------------------------------
+function tickerEntry(row) {
+    const amount = signedDeltaText(row.delta, row.provisional);
+    return `${row.agentId} ${amount} ${row.code} ${row.reason}`.replace(/\s+/g, ' ').trim();
+}
+/**
+ * The ledger ticker: the most recent entries, newest first, joined by a middle dot.
+ *
+ * An ALERT outranks it. A budget warning or an escalation is the one thing the panel
+ * cannot afford to scroll past, and the row is already the panel's quiet last line.
+ */
+function buildTicker(snapshot, inner, glyphs) {
+    const alert = snapshot.alerts[0];
+    if (alert !== undefined) {
+        const text = fitCells(`${glyphs.warn} ${alert}`, inner, glyphs.ellipsis);
+        return [line([segment(text, 'warn')])];
+    }
+    if (snapshot.recent.length === 0)
+        return [];
+    const label = `${PANEL_LEDGER_LABEL}  `;
+    const separator = `  ${glyphs.midDot}  `;
+    const budget = Math.max(0, inner - cellWidth(label));
+    let body = '';
+    // Sorted by time here rather than trusting the producer's order: the ticker's whole
+    // meaning is "newest first".
+    for (const row of [...snapshot.recent].sort((a, b) => b.at - a.at)) {
+        const next = body === '' ? tickerEntry(row) : `${body}${separator}${tickerEntry(row)}`;
+        if (body !== '' && cellWidth(next) > budget)
+            break;
+        body = next;
+    }
+    const shown = fitCells(body, budget, glyphs.ellipsis);
+    return [line([segment(label, 'muted'), segment(shown, 'text')])];
+}
+// ---------------------------------------------------------------------------
+// Minimal tier
+// ---------------------------------------------------------------------------
+function minimalCandidates(snapshot, glyphs) {
+    const status = isPausePending(snapshot)
+        ? ` ${STATUS_WORD.pausing}`
+        : snapshot.status === 'paused' || snapshot.status === 'escalated'
+            ? ` ${STATUS_WORD[snapshot.status]}`
+            : '';
+    const stage = stageWord(snapshot);
+    const base = `${GOV_TITLE}${status} ${phaseText(snapshot.phase, snapshot.phaseCount)}`;
+    const staged = stage === '' ? base : `${base} ${stage}`;
+    const dot = ` ${glyphs.midDot} `;
+    const working = workingCountText(workingCount(snapshot));
+    const health = snapshot.health === null
+        ? ''
+        : `${dot}${PANEL_HEALTH_LABEL} ${Math.round(snapshot.health)}`;
+    return [
+        `${staged}${dot}${working}${health}${dot}${PANEL_BOARD_HINT}`,
+        `${staged}${dot}${working}${health}`,
+        `${staged}${dot}${working}`,
+        staged,
+        base,
+        GOV_TITLE,
+    ];
+}
+function buildMinimal(snapshot, inner, glyphs) {
+    const fits = (candidate) => cellWidth(candidate) <= inner;
+    const text = minimalCandidates(snapshot, glyphs).find(fits)
+        ?? fitCells(GOV_TITLE, inner, glyphs.ellipsis);
+    const split = text.indexOf(' ');
+    const head = split < 0 ? text : text.slice(0, split);
+    const rest = split < 0 ? '' : text.slice(split);
+    return line([segment(head, 'govern', true), ...(rest === '' ? [] : [segment(rest, 'muted')])]);
+}
+function selectRoster(snapshot, rows, since) {
+    const present = sortRoster(snapshot.roster)
+        .filter((row) => !isRetired(row, snapshot.phase, since));
+    const cap = maxRosterRows(rows);
+    if (present.length <= cap)
+        return { visible: present, hidden: 0 };
+    // One row of the cap is spent on the `+N more` line, so a hidden roster never makes
+    // the panel taller than the budget `maxRosterRows` promised.
+    const shown = Math.max(1, cap - 1);
+    return { visible: present.slice(0, shown), hidden: present.length - shown };
+}
+function buildTier(input, tier) {
+    const snapshot = input.snapshot;
+    const cols = nonNegativeInt(input.cols);
+    const inner = Math.max(0, cols - PANEL_MARGIN_CELLS);
+    const mode = input.mode ?? 'panel';
+    const base = { ...EMPTY, tier, mode, cols, innerCols: inner };
+    if (tier === 'minimal') {
+        return { ...base, height: 1, header: buildMinimal(snapshot, inner, input.glyphs) };
+    }
+    const compact = tier === 'compact';
+    const header = compact
+        ? buildCompactHeader(snapshot, inner, input.now, input.glyphs)
+        : buildHeader(snapshot, inner, input.now, input.glyphs, tier === 'full');
+    const pipeline = compact ? null : buildPipeline(snapshot, inner, input.glyphs);
+    if (mode === 'run-strip') {
+        return { ...base, height: 1 + Number(pipeline !== null), header, pipeline };
+    }
+    const columns = columnPlan(tier, inner, markerCells(input.glyphs));
+    const { visible, hidden } = selectRoster(snapshot, input.rows, input.eliminatedSince ?? {});
+    const rosterRows = visible.map((row) => buildRosterLine({
+        columns, row, glyphs: input.glyphs, now: input.now, reducedMotion: input.reducedMotion,
+    }));
+    const ticker = compact ? [] : buildTicker(snapshot, inner, input.glyphs);
+    const ruled = !compact && rosterRows.length > 0;
+    const overflow = hidden > 0 ? fitCells(moreText(hidden), inner, input.glyphs.ellipsis) : null;
+    const height = 1 + Number(pipeline !== null) + 2 * Number(ruled) + rosterRows.length
+        + Number(overflow !== null) + ticker.length;
+    return {
+        ...base,
+        height,
+        header,
+        pipeline,
+        ruleCells: ruled ? inner : 0,
+        columns,
+        rosterRows,
+        overflow,
+        ticker,
+    };
+}
+/**
+ * Plan the panel for a terminal and a snapshot.
+ *
+ * `null` snapshot, or a finished run, plans to height 0 (nothing mounts - zero rows and
+ * zero layout shift, the `TeamPanel` D-11 rule). The caller's `availableRows` is a
+ * ceiling: tiers step down until one fits, and `minimal` is a single row or, with no row to
+ * spare, nothing.
+ */
+export function buildGovernancePanelLayout(input) {
+    if (input.snapshot === null || isFinishedRun(input.snapshot.status))
+        return EMPTY;
+    const available = input.availableRows === undefined
+        ? Infinity
+        : nonNegativeInt(input.availableRows);
+    let tier = selectTier(nonNegativeInt(input.cols), nonNegativeInt(input.rows));
+    while (tier !== null) {
+        const layout = buildTier(input, tier);
+        if (layout.height <= available)
+            return layout;
+        tier = NEXT_SMALLER[tier];
+    }
+    return { ...EMPTY, cols: nonNegativeInt(input.cols) };
+}

package/dist/ui/layout/governance-roster.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Roster geometry and cell text for the legion panel (governance-mode section 10.3).
+ *
+ * Pure and total: no Ink, no clock, no terminal. ASCII ONLY.
+ *
+ * WHY COMPUTED FIXED-WIDTH COLUMNS. Same lesson as `team-row.ts`, whose header records
+ * it at length: a fixed-height parent makes Yoga size a flex column to its widest CHILD,
+ * so a row placed by `flexGrow` stops short of the terminal and the cells to its right
+ * lose their absolute offsets. Every column below therefore has a COMPUTED integer width
+ * and exactly ONE column is elastic; it sits between the fixed cluster on its left and
+ * the fixed `delta` cell on its right, so the score change always lands in the row's
+ * last column whatever the activity text says.
+ *
+ * `columnPlan` is TOTAL: for any width (including 0 and 400) the widths never sum past
+ * the width it was given. `governance-panel-layout.test.ts` runs it for every width.
+ */
+import type { RosterRow } from '../../governance/types.js';
+import type { Glyphs } from '../glyphs.js';
+import { type Segment } from '../governance-status.js';
+export type PanelTier = 'full' | 'standard' | 'compact' | 'minimal';
+export type RosterColumnKey = 'marker' | 'id' | 'role' | 'state' | 'gauge' | 'score' | 'prov' | 'tag' | 'wp' | 'activity' | 'delta' | 'note';
+export interface RosterColumn {
+    key: RosterColumnKey;
+    /** Final integer width in terminal columns (the elastic column's is what is left). */
+    width: number;
+    elastic: boolean;
+    align: 'left' | 'right';
+}
+/** One leading margin column, drawn by the component. */
+export declare const PANEL_MARGIN_CELLS = 1;
+/**
+ * The row's columns for a tier at `inner` columns (the terminal width minus the margin).
+ *
+ * THE DROP LADDER IS THE SPECIFICATION, in the order the cells give way: the activity
+ * text first (the only column whose loss costs nothing structural - the work-package cell
+ * becomes the elastic one), then the tag, gauge, provisional, role and delta cells. The
+ * elastic column keeps at least its floor; when even the fixed cluster does not fit,
+ * `squeeze` trims from the right so the sum stays inside `inner` for any input.
+ */
+export declare function columnPlan(tier: PanelTier, inner: number, markerCells: number): RosterColumn[];
+export declare function columnsWidth(columns: readonly RosterColumn[]): number;
+export interface RosterCell {
+    key: RosterColumnKey;
+    width: number;
+    elastic: boolean;
+    align: 'left' | 'right';
+    segments: Segment[];
+}
+export interface RosterLine {
+    /** `row.id`; stable across snapshots so React keys do not churn. */
+    key: string;
+    kind: 'agent' | 'eliminated';
+    cells: RosterCell[];
+}
+export interface RosterLineInput {
+    columns: readonly RosterColumn[];
+    row: RosterRow;
+    glyphs: Glyphs;
+    now: number;
+    reducedMotion: boolean;
+}
+/** One roster row's cells, text already clamped to its cell. */
+export declare function buildRosterLine(input: RosterLineInput): RosterLine;
+/** The marker cell's width in the current glyph tier: 1 + widest marker + 1. */
+export declare function markerCells(glyphs: Glyphs): number;