@gaia-ai/addon-gaia-ui 0.7.0 → 0.8.0

package/dist/src/Entity/run/Data/runs.js

@@ -3,58 +3,174 @@
 // (AC-5). Runs are scoped to the selected project via the nested filter
 // `ticket_id.project_id.id` (a project may span several conductors, so the
 // ticket→project relationship is the canonical scope, not `conductor_id`).
-import { DrupalJsonApiParams } from 'drupal-jsonapi-params';
+// The query itself lives in `./query.ts` (GAIA-282); `ticketRunRows` stays a
+// no-request read of the ticket document (spec D7).
+import { loadPage } from '../../collection.js';
+import { LIST_PAGE_SIZE } from '../../cycle.js';
+import { buildRunQueryParams } from './query.js';
+import { deriveRunStatus, runStartedAge } from './status.js';
 /** Read a value as a string, or `undefined` when it is not one. */
 function str(value) {
     return typeof value === 'string' ? value : undefined;
 }
+/** In the fieldset, or the sideloaded ticket stops resolving (spec fact 5). */
+export const RUN_LIST_RELATIONSHIPS = ['ticket_id'];
+/** Requested, rendered by no column: `closed` feeds the closed predicate in
+ *  `RunsScreen.load`. */
+const RUN_PREDICATE_ATTRIBUTES = ['closed'];
+/**
+ * The run list's columns — RUN · TICKET · STATE · PHASE · AGENT · STARTED, each
+ * carrying its own fieldset entry (GAIA-294 AC 4).
+ *
+ * `Ctx` is `nowSeconds`: STATE is the derived liveness status and STARTED the
+ * relative start age, and both need a clock the row does not carry.
+ */
+export const RUN_COLUMNS = [
+    {
+        key: 'run',
+        label: 'RUN',
+        width: 8,
+        fields: ['drupal_internal__id'],
+        get: (r) => `#${r.drupalId ?? r.id.slice(0, 6)}`,
+    },
+    {
+        key: 'ticket',
+        label: 'TICKET',
+        width: 10,
+        fields: ['ticket_id'],
+        get: (r) => r.ticketIdentifier,
+    },
+    {
+        // Three fields for one column: `deriveRunStatus` reads the run's own state
+        // plus its heartbeat and claim window.
+        key: 'state',
+        label: 'STATE',
+        width: 8,
+        fields: ['state', 'heartbeat', 'claim_expires_at'],
+        get: (r, nowSeconds) => deriveRunStatus(r, nowSeconds),
+    },
+    {
+        key: 'phase',
+        label: 'PHASE',
+        width: 10,
+        fields: ['state_at_start'],
+        get: (r) => r.phase,
+    },
+    {
+        key: 'agent',
+        label: 'AGENT',
+        width: 8,
+        fields: ['agent'],
+        get: (r) => r.agent,
+    },
+    {
+        // The trailing column, unpadded. `created` is `started_at`'s documented
+        // fallback for a run that never started.
+        key: 'started',
+        label: 'STARTED',
+        width: 0,
+        fields: ['started_at', 'created'],
+        get: (r, nowSeconds) => runStartedAge(r, nowSeconds),
+    },
+];
+/**
+ * The attributes a run row needs (GAIA-292 D2), in the order the query string
+ * states them. `created` is a column field as `started_at`'s documented fallback
+ * for a run that never started, and `heartbeat` + `claim_expires_at` ride the STATE
+ * column because `deriveRunStatus` reads them.
+ *
+ * Membership is owned by the columns and proved exhaustive below; only the ORDER
+ * is declared, because `tests/Entity/run/Data/query.test.ts` pins the emitted
+ * `fields[gaia_run--gaia_run]=…` sequence and column order would hoist
+ * `heartbeat`/`claim_expires_at` to third and fourth (GAIA-294, behaviour-neutral
+ * to the bytes on the wire).
+ */
+export const RUN_LIST_ATTRIBUTES = [
+    'drupal_internal__id',
+    'state',
+    'state_at_start',
+    'agent',
+    'started_at',
+    'created',
+    'heartbeat',
+    'claim_expires_at',
+    'closed',
+];
+/** What `addFields('gaia_run--gaia_run', …)` takes. */
+export const RUN_LIST_FIELDS = [
+    ...RUN_LIST_ATTRIBUTES,
+    ...RUN_LIST_RELATIONSHIPS,
+];
+/**
+ * The sideloaded ticket renders ONE column: its identifier.
+ *
+ * Measured (GAIA-292 spec fact 4): without this, a 37-row run page shipped
+ * 191.4 KB of `included` — 12 whole ticket resources with their descriptions —
+ * out of 254.7 KB total, and took 4732 ms.
+ */
+export const RUN_TICKET_INCLUDE_FIELDS = ['identifier'];
 /**
  * Map a RAW JSON:API `data[]` entry (from `client.get`) to a run row, resolving
  * the ticket identifier from the sideloaded includes indexed by id. Mirrors
  * `mapTicketData` — the only I/O is upstream in {@link loadProjectRuns}.
+ *
+ * Every attribute and relationship is read through an accessor keyed on the
+ * fieldset, so reading one the list does not request is a compile error (AC-5).
  */
 export function mapRunData(item, ticketsById) {
     const a = item.attributes ?? {};
-    const ticketRel = item.relationships?.ticket_id?.data;
+    const text = (key) => typeof a[key] === 'string' ? a[key] : undefined;
+    const raw = (key) => a[key];
+    const rel = (key) => item.relationships?.[key]?.data;
+    const ticketRel = rel('ticket_id');
     const ticketId = Array.isArray(ticketRel)
         ? (ticketRel[0]?.id ?? null)
         : (ticketRel?.id ?? null);
     const ticket = ticketId ? ticketsById.get(ticketId) : undefined;
-    const drupalId = typeof a.drupal_internal__id === 'number' ||
-        typeof a.drupal_internal__id === 'string'
-        ? a.drupal_internal__id
+    const internal = raw('drupal_internal__id');
+    const drupalId = typeof internal === 'number' || typeof internal === 'string'
+        ? internal
         : null;
     return {
         id: item.id ?? '',
         drupalId,
         ticketId,
         ticketIdentifier: str(ticket?.attributes?.identifier) ?? (ticketId ? ticketId : '—'),
-        state: str(a.state) ?? 'unknown',
-        phase: str(a.state_at_start) ?? '—',
-        agent: str(a.agent) ?? '—',
-        startedAt: str(a.started_at) ?? str(a.created) ?? null,
-        heartbeat: str(a.heartbeat) ?? null,
-        claimExpiresAt: str(a.claim_expires_at) ?? null,
+        state: text('state') ?? 'unknown',
+        phase: text('state_at_start') ?? '—',
+        agent: text('agent') ?? '—',
+        startedAt: text('started_at') ?? text('created') ?? null,
+        heartbeat: text('heartbeat') ?? null,
+        claimExpiresAt: text('claim_expires_at') ?? null,
+        closed: typeof raw('closed') === 'boolean' ? raw('closed') : false,
     };
 }
 /**
- * List the `gaia_run` entities of a project, most-recently-started first.
- * Filtered by `ticket_id.project_id.id`, includes `ticket_id`, sorts
- * `started_at` DESC, pages 50 (deeper history via offset is a later follow-up).
+ * List the `gaia_run` entities of a project under the given criteria,
+ * most-recently-started first — ONE page of them. The query (scope, include,
+ * fieldsets, sort, closed filter) is built by {@link buildRunQueryParams}; the
+ * page (size + index) is the caller's, and `hasNext` comes from the document's
+ * `links.next`.
  */
-export async function loadProjectRuns(client, projectId) {
-    const params = new DrupalJsonApiParams();
-    params.addFilter('ticket_id.project_id.id', projectId);
-    params.addInclude(['ticket_id']);
-    params.addSort('started_at', 'DESC');
-    params.addPageLimit(50);
-    const doc = (await client.get('gaia_run/gaia_run', params));
-    const ticketsById = new Map();
-    for (const inc of doc?.included ?? []) {
-        if (inc.id)
-            ticketsById.set(inc.id, inc);
-    }
-    return (doc?.data ?? []).map((item) => mapRunData(item, ticketsById));
+export async function loadProjectRuns(client, projectId, criteria, page = 0) {
+    // The window this read asks for, stated once and handed BOTH to the query
+    // builder and to the page it produces, so the offset the screen positions with
+    // is the offset the server was sent (GAIA-312 D3).
+    const window = {
+        offset: page * LIST_PAGE_SIZE,
+        limit: LIST_PAGE_SIZE,
+    };
+    const params = buildRunQueryParams(projectId, criteria, {
+        size: window.limit,
+        index: page,
+    });
+    return loadPage(client, 'gaia_run/gaia_run', params, (data, included) => {
+        const ticketsById = new Map();
+        for (const inc of included)
+            if (inc.id)
+                ticketsById.set(inc.id, inc);
+        return data.map((item) => mapRunData(item, ticketsById));
+    }, page, window);
 }
 /**
  * Newest-STARTED first, and TOTAL (GAIA-255 D5).

package/dist/src/Entity/run/Screen/run-detail.d.ts

@@ -0,0 +1,25 @@
+import { BaseScreen, type ScreenContext } from '../../../Screen/screen.js';
+import type { TicketDetailDocument } from '../../../types.js';
+export interface RunDetailInput {
+    readonly document: TicketDetailDocument;
+}
+export declare const runDetailInputContext: import("../../../Routing/context.js").ContextKey<RunDetailInput>;
+export declare class RunDetailScreen extends BaseScreen {
+    readonly frameId = "run";
+    topTab(): null;
+    static readonly route: {
+        id: string;
+        path: string;
+        parent: string;
+        fallback: {
+            routeId: string;
+        };
+        context: (_params: Readonly<Record<string, string>>, state: unknown, base: import("../../../Routing/context.js").ContextBag) => import("../../../Routing/context.js").ContextBag;
+    };
+    readonly id: string;
+    private document;
+    enter(context: ScreenContext): void;
+    render(context: ScreenContext): string[];
+    present(context: ScreenContext): import("../../../Screen/screen.js").ScreenPresentation;
+    reset(): void;
+}

package/dist/src/Entity/run/Screen/run-detail.js

@@ -0,0 +1,51 @@
+import { defineContext } from '../../../Routing/context.js';
+import { BaseScreen, presentation, } from '../../../Screen/screen.js';
+import { runDetailLines, runDetailTitle, } from '../Component/run-detail/index.js';
+export const runDetailInputContext = defineContext('run-detail-input', 'input');
+export class RunDetailScreen extends BaseScreen {
+    frameId = 'run';
+    topTab() {
+        return null;
+    }
+    static route = {
+        id: 'run.detail',
+        path: '/tickets/:ticketId/runs/:runId',
+        parent: 'ticket.detail',
+        fallback: { routeId: 'project.dashboard' },
+        context: (_params, state, base) => state
+            ? base.set(runDetailInputContext, {
+                document: state,
+            })
+            : base,
+    };
+    id = RunDetailScreen.route.id;
+    document = {};
+    enter(context) {
+        if (context.contexts?.has(runDetailInputContext))
+            this.document = context.contexts.get(runDetailInputContext).document;
+        context.requestDraw();
+    }
+    render(context) {
+        const runId = context.params?.runId;
+        if (!runId)
+            return ['Run detail requires runId'];
+        return [
+            runDetailTitle(this.document, runId),
+            '',
+            ...runDetailLines(this.document, runId).lines,
+        ];
+    }
+    present(context) {
+        const runId = context.params?.runId ?? '';
+        const rendered = runDetailLines(this.document, runId);
+        return presentation(rendered.lines, {
+            boldRows: rendered.boldRows,
+            title: runDetailTitle(this.document, runId),
+            meta: '↑↓ scroll · Esc back · q quit',
+            status: ' ↑↓ scroll · Esc back · q quit ',
+        });
+    }
+    reset() {
+        this.document = {};
+    }
+}

package/dist/src/Entity/run/Screen/runs.d.ts

@@ -0,0 +1,82 @@
+import { ListScreen } from '../../../Screen/list-screen.js';
+import { type ScreenContext, type ScreenPresentation } from '../../../Screen/screen.js';
+import { type RunCriteria } from '../Data/query.js';
+import { type RunPage, type RunRow } from '../Data/runs.js';
+export declare class RunsScreen extends ListScreen<RunRow, number> {
+    readonly frameId = "project-runs";
+    readonly topTabOverlay = true;
+    protected readonly columns: readonly [{
+        readonly key: "run";
+        readonly label: "RUN";
+        readonly width: 8;
+        readonly fields: readonly ["drupal_internal__id"];
+        readonly get: (r: RunRow) => string;
+    }, {
+        readonly key: "ticket";
+        readonly label: "TICKET";
+        readonly width: 10;
+        readonly fields: readonly ["ticket_id"];
+        readonly get: (r: RunRow) => string;
+    }, {
+        readonly key: "state";
+        readonly label: "STATE";
+        readonly width: 8;
+        readonly fields: readonly ["state", "heartbeat", "claim_expires_at"];
+        readonly get: (r: RunRow, nowSeconds: number) => string;
+    }, {
+        readonly key: "phase";
+        readonly label: "PHASE";
+        readonly width: 10;
+        readonly fields: readonly ["state_at_start"];
+        readonly get: (r: RunRow) => string;
+    }, {
+        readonly key: "agent";
+        readonly label: "AGENT";
+        readonly width: 8;
+        readonly fields: readonly ["agent"];
+        readonly get: (r: RunRow) => string;
+    }, {
+        readonly key: "started";
+        readonly label: "STARTED";
+        readonly width: 0;
+        readonly fields: readonly ["started_at", "created"];
+        readonly get: (r: RunRow, nowSeconds: number) => string;
+    }];
+    protected readonly emptyMessage = "No runs for this project.";
+    topTab(): {
+        readonly level: "project";
+        readonly tab: "runs";
+    };
+    static readonly route: {
+        id: string;
+        path: string;
+        parent: string;
+        tab: {
+            id: string;
+            label: string;
+            scope: string;
+            order: number;
+        };
+    };
+    readonly id: string;
+    private criteria;
+    saveState(): {
+        criteria: RunCriteria;
+        page: number;
+        selectedRunId: string | null;
+    };
+    restoreState(token: unknown): void;
+    /** STATE is the derived liveness status and STARTED the relative start age, so
+     *  the columns need a clock the row does not carry. */
+    protected tableContext(context: ScreenContext): number;
+    protected loadRows(context: ScreenContext, page: number): Promise<RunPage>;
+    /** Server is authoritative; the double-check protects against param-ignoring
+     *  clients/test doubles, as on the ticket list. */
+    protected filterRow(row: RunRow): boolean;
+    protected renderLoading(): string[];
+    present(context: ScreenContext): ScreenPresentation;
+    activate(index: number, context: ScreenContext): boolean;
+    select(index: number, context: ScreenContext): boolean;
+    handleInput(input: string, context: ScreenContext): boolean;
+    reset(): void;
+}

package/dist/src/Entity/run/Screen/runs.js

@@ -0,0 +1,169 @@
+import { ListScreen } from '../../../Screen/list-screen.js';
+import { presentation, } from '../../../Screen/screen.js';
+import { CLOSED_FILTER_VALUES, cycleValue } from '../../cycle.js';
+import { DEFAULT_RUN_CRITERIA } from '../Data/query.js';
+import { loadProjectRuns, RUN_COLUMNS, selectedRunTicketId, } from '../Data/runs.js';
+export class RunsScreen extends ListScreen {
+    frameId = 'project-runs';
+    topTabOverlay = true;
+    columns = RUN_COLUMNS;
+    emptyMessage = 'No runs for this project.';
+    topTab() {
+        return { level: 'project', tab: 'runs' };
+    }
+    static route = {
+        id: 'project.runs',
+        path: '/projects/:projectId/runs',
+        parent: 'project.dashboard',
+        tab: { id: 'runs', label: 'Runs', scope: 'project', order: 40 },
+    };
+    id = RunsScreen.route.id;
+    criteria = { ...DEFAULT_RUN_CRITERIA };
+    saveState() {
+        return {
+            criteria: { ...this.criteria },
+            page: this.page,
+            selectedRunId: this.rows[this.selectedIndex]?.id ?? null,
+        };
+    }
+    restoreState(token) {
+        if (!token || typeof token !== 'object')
+            return;
+        const saved = token;
+        if (saved.criteria) {
+            this.criteria = { ...saved.criteria };
+            // Tokens saved before GAIA-282 carry no closed; normalize so a stale
+            // token cannot smuggle undefined into a predicate testing !== null.
+            this.criteria.closed =
+                this.criteria.closed ?? DEFAULT_RUN_CRITERIA.closed;
+        }
+        // Clamped for the same reason `closed` is normalised above: a stale token
+        // must not smuggle a negative offset into the query.
+        this.restorePage(saved);
+        if (typeof saved.selectedRunId !== 'string')
+            return;
+        const index = this.rows.findIndex((row) => row.id === saved.selectedRunId);
+        if (index >= 0)
+            this.selectedIndex = index;
+    }
+    /** STATE is the derived liveness status and STARTED the relative start age, so
+     *  the columns need a clock the row does not carry. */
+    tableContext(context) {
+        return context.nowSeconds?.() ?? Math.floor(Date.now() / 1000);
+    }
+    loadRows(context, page) {
+        if (!context.services || !context.project)
+            throw new Error('Runs requires project context');
+        return loadProjectRuns(context.services.client, context.project.id, this.criteria, page);
+    }
+    /** Server is authoritative; the double-check protects against param-ignoring
+     *  clients/test doubles, as on the ticket list. */
+    filterRow(row) {
+        return this.criteria.closed === null || row.closed === this.criteria.closed;
+    }
+    renderLoading() {
+        return ['Loading runs…'];
+    }
+    present(context) {
+        const rows = this.rows;
+        // Standing segment: stated whenever rows are hidden, including the very
+        // first render (AC-4) — unconditional, as on the ticket list.
+        const closedSegment = this.criteria.closed === null
+            ? ''
+            : this.criteria.closed
+                ? 'closed: only'
+                : 'closed: hidden';
+        // The PAGE number, and only that; the collection's size is a different
+        // quantity, stated in its own segment by `countLabel` off the `meta.count`
+        // the page response carries (D6e). A page that offers a next page while
+        // showing few rows is correct rather than a bug: `links.next` is the
+        // end-of-collection signal, and a page can be full without being the last.
+        // The whole segment describes the LOADED page, not the requested index —
+        // that is what the `page` the value carries is for (D4); same reasoning,
+        // same shape and the same bottom-line home as the ticket list, which must
+        // not drift from this one. It is the same `loadedPage` the ARROW keys act
+        // on, so the number the operator reads and the number the keys move from
+        // are one value (R1).
+        //
+        // Built by `ListScreen` since GAIA-294, which is what makes "must not drift
+        // from the ticket list" a mechanism rather than a promise.
+        const paging = this.pagingSegments();
+        // The rows ON SCREEN and the size of the FILTERED COLLECTION, side by side:
+        // `7 of 1340 run(s)` when the server reported the total, `7 of ? run(s)`
+        // when it reported none (GAIA-292 D6c/D6d). Neither quantity replaces the
+        // other, so the row count never jumps; the total is read off the value the
+        // rows came with (D4/D4a) and from no second screen member — which is now
+        // structural rather than careful, because the server answered both from one
+        // query. Empty while the page loads (D6c), which is why the segments are
+        // joined rather than concatenated — an omitted count must not leave the line
+        // opening with a separator.
+        const count = this.countLabel('run');
+        return presentation(this.render(context), {
+            selectable: rows.length,
+            selectedIndex: this.selectedIndex,
+            selectedRow: rows.length ? 1 + this.selectedIndex : -1,
+            title: `${context.project?.name ?? context.project?.slug ?? ''} · runs`,
+            meta: [
+                count,
+                closedSegment,
+                'Enter ticket · Tab tabs · x closed · Esc back',
+            ]
+                .filter(Boolean)
+                .join('  ·  '),
+            status: ` ${paging.join(' · ')} · ↑↓ select · Enter ticket · Tab tabs · x closed · Esc back · q quit `,
+        });
+    }
+    activate(index, context) {
+        const id = this.readyValue
+            ? selectedRunTicketId(this.readyValue.rows, index)
+            : null;
+        if (!id || !context.navigate)
+            return false;
+        context.navigate('ticket.detail', { ticketId: id, tab: 'runs' });
+        return true;
+    }
+    select(index, context) {
+        if (index < 0 || index >= this.rows.length)
+            return false;
+        this.selectedIndex = index;
+        context.requestDraw();
+        return true;
+    }
+    handleInput(input, context) {
+        if (super.handleInput(input, context))
+            return true;
+        if (input === 'x') {
+            this.criteria = {
+                ...this.criteria,
+                closed: cycleValue(CLOSED_FILTER_VALUES, this.criteria.closed),
+            };
+            // A criteria change starts over at page one, or narrowing on page 4 lands
+            // on an empty page with no rows and no explanation (D5).
+            this.page = 0;
+            this.selectedIndex = 0;
+            this.retry(context);
+            return true;
+        }
+        // The ARROW keys since the operator's live review (D6 chose `]` / `[`); the
+        // kernel handles neither sequence itself, so the screen claims them. This
+        // screen has no search field, so there is nothing they could shadow.
+        // Both move from the page ON SCREEN, never from the requested index (R1).
+        if (this.handlePagingInput(input, context))
+            return true;
+        const rows = this.readyValue?.rows;
+        if (!rows)
+            return false;
+        if (this.handleCursorInput(input, context))
+            return true;
+        if (input === '\r' || input === '\n')
+            return this.activate(this.selectedIndex, context);
+        return false;
+    }
+    reset() {
+        // The page, the cursor and the counter — a reset means a new project or
+        // session, hence a different collection (GAIA-294).
+        this.resetList();
+        this.criteria = { ...DEFAULT_RUN_CRITERIA };
+        super.reset();
+    }
+}

package/dist/src/Entity/statistics/Screen/dashboard.d.ts

@@ -0,0 +1,42 @@
+import { AsyncScreen } from '../../../Screen/async-screen.js';
+import { type ScreenAction, type ScreenContext, type ScreenPresentation } from '../../../Screen/screen.js';
+import { type StatisticsResult } from '../Data/statistics.js';
+export declare class DashboardScreen extends AsyncScreen<StatisticsResult> {
+    readonly frameId = "dashboard";
+    topTab(context: ScreenContext): {
+        readonly level: "project";
+        readonly tab: "dashboard";
+    } | {
+        readonly level: "root";
+        readonly tab: "dashboard";
+    };
+    reload(context: ScreenContext): void;
+    static readonly route: {
+        id: string;
+        path: string;
+        fallback: {
+            routeId: string;
+        };
+        tab: {
+            id: string;
+            label: string;
+            scope: string;
+            scopes: string[];
+            order: number;
+        };
+    };
+    readonly id: string;
+    private status;
+    actionForInput(input: string, context: ScreenContext): ScreenAction | undefined;
+    protected load(context: ScreenContext): Promise<StatisticsResult>;
+    protected renderLoading(): string[];
+    protected renderReady(result: StatisticsResult, context: ScreenContext): string[];
+    renderNonInteractive(context: ScreenContext): string[];
+    nonInteractive(context: ScreenContext): {
+        stream?: "stderr";
+        exitCode?: number;
+        lines: string[];
+    };
+    present(context: ScreenContext): ScreenPresentation;
+    reset(): void;
+}