@gaia-ai/addon-gaia-ui 0.6.1

package/dist/src/launcher.d.ts

@@ -0,0 +1,58 @@
+import { type GaiaUiOptions } from './plugin.js';
+import type { TuiAgentService } from './types.js';
+/** A dropsh program: only the `parseAsync` we drive is modelled. */
+export interface DropshProgram {
+    parseAsync(argv: string[], opts: {
+        from: 'user';
+    }): Promise<unknown>;
+}
+/** The subset of dropsh's `buildProgram` the launcher uses (injected). */
+export type DropshBuildProgram = (opts: {
+    plugins: unknown[];
+}) => DropshProgram;
+/**
+ * The resolved home control-plane connection. `authPlugins` are the dropsh auth
+ * plugin descriptors/instances (a `session` oauth2 client-credentials entry);
+ * `configPath` points dropsh's own in-process context factory at a home dropsh
+ * config (base_url + the same auth) so it can build its client WITHOUT a project
+ * `conductor.config.js` — the conductor entry synthesizes it.
+ */
+export interface HomeConnection {
+    baseUrl: string;
+    jsonapiPrefix?: string | undefined;
+    authPlugins: unknown[];
+    configPath?: string | undefined;
+    /** The dropsh auth profile the cockpit reads as. The home cockpit reads
+     *  `gaia_conductor`/`gaia_run` + tickets, which are owner-gated to `session`
+     *  (a `pm` read returns them empty) — so this pins the profile regardless of
+     *  whatever profile a prior `gaia dropsh` login left active. */
+    authProfile?: string | undefined;
+}
+export interface GaiaUiLauncherOptions {
+    /** Resolved home connection (base_url + auth + dropsh config path). */
+    connection: HomeConnection;
+    /** Repo/home root the launched agents run in. */
+    cwd: string;
+    /** Default project (opaque group), from the conductor registry. */
+    project?: string | undefined;
+    /** Herdr-backed agent host, already adapted prompt→command (injected). */
+    agents?: TuiAgentService | undefined;
+    /** Preselected new-ticket assignee (this machine's user id). */
+    currentUser?: string | undefined;
+    /** This machine's conductor `machine_id` — preselected in the new-ticket form. */
+    ownConductorMachineId?: string | undefined;
+    /** Config override for the ticket-create agent's base prompt. */
+    createPrompt?: string | undefined;
+    /** Injected dropsh `buildProgram` (the entry passes dropsh's real one). */
+    buildProgram: DropshBuildProgram;
+    /** Injected renderer factory; defaults to this package's own plugin. The
+     *  `$GAIA_UI_PLUGIN` dev override resolves a different module in the entry. */
+    renderer?: ((opts: GaiaUiOptions) => unknown) | undefined;
+}
+/**
+ * Build + run the dropsh `--format tui` program with the TUI renderer and the
+ * injected agent host. A trivial `search gaia_project` seeds the renderer's
+ * `run()`; the renderer discards the seed document and boots its own dashboard
+ * from the conductor registry (`~/.gaia/conductors.json`).
+ */
+export declare function runGaiaUi(opts: GaiaUiLauncherOptions): Promise<void>;

package/dist/src/launcher.js

@@ -0,0 +1,51 @@
+import gaiaUiPlugin from './plugin.js';
+/**
+ * Build + run the dropsh `--format tui` program with the TUI renderer and the
+ * injected agent host. A trivial `search gaia_project` seeds the renderer's
+ * `run()`; the renderer discards the seed document and boots its own dashboard
+ * from the conductor registry (`~/.gaia/conductors.json`).
+ */
+export async function runGaiaUi(opts) {
+    // Point dropsh's own in-process context factory at the home dropsh config so
+    // it resolves base_url + auth without a project config. An explicit
+    // $DROPSH_CONFIG (or a prior set) still wins.
+    if (opts.connection.configPath && !process.env.DROPSH_CONFIG) {
+        process.env.DROPSH_CONFIG = opts.connection.configPath;
+    }
+    // Pin the read profile (session) so dropsh does not fall through to a
+    // previously-active profile (`pm`) whose provider the home config omits — and
+    // whose owner-gated reads would come back empty. An explicit env still wins.
+    if (opts.connection.authProfile && !process.env.DROPSH_AUTH_PROFILE) {
+        process.env.DROPSH_AUTH_PROFILE = opts.connection.authProfile;
+    }
+    const makeRenderer = opts.renderer ?? gaiaUiPlugin;
+    const renderer = makeRenderer({
+        cwd: opts.cwd,
+        ...(opts.project !== undefined ? { project: opts.project } : {}),
+        ...(opts.agents ? { agents: opts.agents } : {}),
+        ...(opts.currentUser !== undefined
+            ? { currentUser: opts.currentUser }
+            : {}),
+        ...(opts.ownConductorMachineId !== undefined
+            ? { ownConductorMachineId: opts.ownConductorMachineId }
+            : {}),
+        ...(opts.createPrompt !== undefined
+            ? { createPrompt: opts.createPrompt }
+            : {}),
+    });
+    const program = opts.buildProgram({
+        plugins: [...opts.connection.authPlugins, renderer],
+    });
+    // Any JSON:API document with `--format tui` drives the renderer; it discards
+    // the seed and loads the dashboard itself.
+    await program.parseAsync([
+        '--format',
+        'tui',
+        'search',
+        'gaia_project',
+        '--bundle',
+        'gaia_project',
+        '--limit',
+        '1',
+    ], { from: 'user' });
+}

package/dist/src/lib/ansi.d.ts

@@ -0,0 +1,19 @@
+export declare const ANSI: {
+    reset: string;
+    bold: string;
+    dim: string;
+    cyan: string;
+    brightCyan: string;
+    inverse: string;
+};
+export declare function sanitizeDisplay(value: unknown): string;
+export declare function fitLine(value: unknown, width: number): string;
+export interface StyleVisibleLinesOptions {
+    lines: string[];
+    boldRows?: Set<number> | undefined;
+    selRow?: number;
+    offset?: number;
+    height?: number;
+    contentWidth: number;
+}
+export declare function styleVisibleLines({ lines, boldRows, selRow, offset, height, contentWidth, }: StyleVisibleLinesOptions): string[];

package/dist/src/lib/ansi.js

@@ -0,0 +1,45 @@
+export const ANSI = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    cyan: '\x1b[36m',
+    brightCyan: '\x1b[96m',
+    inverse: '\x1b[7m',
+};
+export function sanitizeDisplay(value) {
+    // Defense-in-depth so fitLine() structurally guarantees ONE physical row per field:
+    // map every C0 whitespace control (TAB, LF, VT, FF, CR) to a space — keeping
+    // words separated — then strip the remaining C0/C1 controls. A single field can
+    // therefore never carry an embedded newline/tab into a "single row".
+    return (String(value)
+        .replace(/[\t\n\v\f\r]/g, ' ')
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping the C0/C1 control range is the whole point of this sanitizer.
+        .replace(/[\x00-\x1f\x7f-\x9f]/g, ''));
+}
+export function fitLine(value, width) {
+    const text = sanitizeDisplay(value);
+    return text.length > width
+        ? `${text.slice(0, Math.max(0, width - 1))}…`
+        : text.padEnd(width);
+}
+// Fit + style the visible window: selected row inverse, heading rows bold —
+// both applied AFTER fitLine() so the ANSI wraps the sanitized text, never the
+// reverse (fitting an ANSI-wrapped string strips the ESC and leaks CSI text).
+//
+// INVARIANT (AC-4): every returned entry is exactly ONE physical row. fitLine()
+// runs sanitizeDisplay(), which maps LF/TAB to space and strips the rest of the
+// C0/C1 range, so no entry can carry an embedded newline — draw()'s fixed-height
+// window therefore emits Math.min(height, lines.length) physical rows, never
+// more. ansi.test.ts pins the primitive; Component/ticket-detail/index.test.ts
+// pins it against a real multi-line detail document.
+export function styleVisibleLines({ lines, boldRows, selRow = -1, offset = 0, height = lines.length, contentWidth, }) {
+    return lines.slice(offset, offset + height).map((line, index) => {
+        const abs = offset + index;
+        const content = `  ${fitLine(line, contentWidth)}`;
+        if (abs === selRow)
+            return `${ANSI.inverse}${content}${ANSI.reset}`;
+        if (boldRows?.has(abs))
+            return `${ANSI.bold}${content}${ANSI.reset}`;
+        return content;
+    });
+}

package/dist/src/lib/format.d.ts

@@ -0,0 +1,3 @@
+export declare function pad(value: unknown, width: number): string;
+/** Read a value as a string, or `undefined` when it is not one. */
+export declare function asString(value: unknown): string | undefined;

package/dist/src/lib/format.js

@@ -0,0 +1,10 @@
+export function pad(value, width) {
+    const s = String(value ?? '');
+    return s.length > width
+        ? `${s.slice(0, Math.max(0, width - 1))}…`
+        : s.padEnd(width);
+}
+/** Read a value as a string, or `undefined` when it is not one. */
+export function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}

package/dist/src/lib/scroll.d.ts

@@ -0,0 +1 @@
+export declare function scrollTo(selRow: number, offset: number, height: number): number;

package/dist/src/lib/scroll.js

@@ -0,0 +1,16 @@
+// Clamp a viewport of `height` rows starting at `offset` so the selected row
+// stays visible: scroll up when it is above the window, down when it is at or
+// below the bottom edge, leave it untouched when already inside.
+//
+// `selRow` is the ABSOLUTE physical row of the selection. List screens prepend a
+// header row (the ticket table's `IDENTIFIER …` line), so the caller must pass
+// screenView().selRow — the real row of the highlight — NOT the 0-based
+// selection index. Feeding the 0-based index here is the AC-2 off-by-one the
+// round-5 review caught: the highlight fell one row past the window bottom.
+export function scrollTo(selRow, offset, height) {
+    if (selRow < offset)
+        return selRow;
+    if (selRow >= offset + height)
+        return selRow - height + 1;
+    return offset;
+}

package/dist/src/lib/ticket-query.d.ts

@@ -0,0 +1,21 @@
+import { DrupalJsonApiParams } from 'drupal-jsonapi-params';
+/** The active search + filter criteria for the project ticket list. */
+export interface TicketCriteria {
+    query: string;
+    state: string | null;
+    type: string | null;
+}
+export declare const STATE_FILTER_VALUES: string[];
+export declare const TYPE_FILTER_VALUES: string[];
+export declare const TYPE_LABELS: Record<string, string>;
+/** Next value in a cyclic list; `null` (== "all") wraps at both ends. */
+export declare function cycleValue(values: string[], current: string | null): string | null;
+export declare function hasActiveCriteria(criteria: TicketCriteria): boolean;
+/** Human-readable active-criteria summary, or '' when none. */
+export declare function describeCriteria(criteria: TicketCriteria): string;
+/**
+ * Build the JSON:API query for a project's tickets under the given criteria.
+ * project + state + type are AND filters at the top level; the free-text search
+ * is an OR group matching identifier OR title (substring).
+ */
+export declare function buildTicketQueryParams(projectId: string, criteria: TicketCriteria): DrupalJsonApiParams;

package/dist/src/lib/ticket-query.js

@@ -0,0 +1,72 @@
+import { DrupalJsonApiParams } from 'drupal-jsonapi-params';
+// Ticket states from web/modules/custom/gaia_core/gaia_core.workflows.yml
+// (feature/bug/chore workflows) plus the import/backlog states seen on tickets.
+// Hardcoded so the cycle is deterministic and independent of the loaded page.
+export const STATE_FILTER_VALUES = [
+    'triage',
+    'backlog',
+    'todo',
+    'spec',
+    'diagnose',
+    'coding',
+    'review',
+    'done',
+    'cancelled',
+];
+export const TYPE_FILTER_VALUES = [
+    'gaia_feature',
+    'gaia_bug',
+    'gaia_chore',
+];
+export const TYPE_LABELS = {
+    gaia_feature: 'feature',
+    gaia_bug: 'bug',
+    gaia_chore: 'chore',
+};
+/** Next value in a cyclic list; `null` (== "all") wraps at both ends. */
+export function cycleValue(values, current) {
+    if (current == null)
+        return values[0] ?? null;
+    const i = values.indexOf(current);
+    if (i < 0 || i === values.length - 1)
+        return null;
+    return values[i + 1] ?? null;
+}
+export function hasActiveCriteria(criteria) {
+    return (Boolean(criteria.query) || criteria.state != null || criteria.type != null);
+}
+/** Human-readable active-criteria summary, or '' when none. */
+export function describeCriteria(criteria) {
+    const parts = [];
+    if (criteria.query)
+        parts.push(`search:"${criteria.query}"`);
+    if (criteria.state)
+        parts.push(`status:${criteria.state}`);
+    if (criteria.type)
+        parts.push(`type:${TYPE_LABELS[criteria.type] ?? criteria.type}`);
+    return parts.join(' · ');
+}
+/**
+ * Build the JSON:API query for a project's tickets under the given criteria.
+ * project + state + type are AND filters at the top level; the free-text search
+ * is an OR group matching identifier OR title (substring).
+ */
+export function buildTicketQueryParams(projectId, criteria) {
+    const params = new DrupalJsonApiParams();
+    params.addFilter('project_id.id', projectId);
+    if (criteria.query) {
+        params.addGroup('search', 'OR');
+        params.addFilter('identifier', criteria.query, 'CONTAINS', 'search');
+        params.addFilter('title', criteria.query, 'CONTAINS', 'search');
+    }
+    if (criteria.state)
+        params.addFilter('state', criteria.state);
+    if (criteria.type)
+        params.addFilter('workflow', criteria.type);
+    // Sideload the parent ticket + assigned conductor so the row can render the
+    // parent identifier / conductor label from `included` (GAIA-193, AC-5).
+    params.addInclude(['parent_id', 'conductor_id']);
+    params.addSort('changed', 'DESC');
+    params.addPageLimit(50);
+    return params;
+}

package/dist/src/plugin.d.ts

@@ -0,0 +1,13 @@
+import type { RendererServices, TuiOptions } from './types.js';
+/** Options the launcher passes into the factory (a superset of the injected
+ *  intent-level agent service so `gaia ui` can drive launch/list/focus/…). */
+export type GaiaUiOptions = TuiOptions;
+export default function gaiaUiPlugin(options?: GaiaUiOptions): {
+    id: string;
+    requiredModules: string[];
+    renderers: {
+        id: string;
+        interactive: boolean;
+        run: (document: unknown, context: unknown, services: RendererServices) => Promise<void>;
+    }[];
+};

package/dist/src/plugin.js

@@ -0,0 +1,17 @@
+import { runTicketTui } from './Kernel/tui-kernel.js';
+// The dropsh `tui` renderer plugin: a single interactive renderer that hands off
+// to the TUI kernel. The conductor's plugin resolver auto-picks the default
+// export, so the factory is the module default.
+export default function gaiaUiPlugin(options = {}) {
+    return {
+        id: 'gaia-ticket-renderer',
+        requiredModules: [],
+        renderers: [
+            {
+                id: 'tui',
+                interactive: true,
+                run: (document, context, services) => runTicketTui(document, context, services, options),
+            },
+        ],
+    };
+}

package/dist/src/preset.d.ts

@@ -0,0 +1,2 @@
+import type { GaiaPreset } from '@gaia-ai/core';
+export declare const connectionPlugins: GaiaPreset['connectionPlugins'];

package/dist/src/preset.js

@@ -0,0 +1,7 @@
+import gaiaUiPlugin from './index.js';
+export const connectionPlugins = (acc, opts) => [
+    ...acc,
+    // The tui renderer plugin is a DropSHPlugin structurally (id + renderers);
+    // its concrete renderer types are wider than dropsh's exported interface.
+    gaiaUiPlugin(opts),
+];

package/dist/src/types.d.ts

@@ -0,0 +1,98 @@
+/** A dropsh `toResource(...)` wrapper — see tests/test-support.ts. */
+export interface Resource {
+    id: string;
+    type: string;
+    attr(key: string): unknown;
+    rel(key: string): string | null;
+    rels(key: string): string[];
+}
+/** A dropsh collection query builder (fluent). */
+export interface Collection {
+    where(path: string, op: string, value: unknown): Collection;
+    sort(field: string, direction: string): Collection;
+    page(size: number): Collection;
+    first(): Promise<Resource | null>;
+    list(): Promise<Resource[]>;
+}
+/** The dropsh JSON:API client exposed as `services.client`. */
+export interface DropshClient {
+    collection(type: string): Collection;
+    get(path: string, params?: unknown): Promise<unknown>;
+}
+/** A JSON:API relationship linkage. */
+export interface JsonApiRelationship {
+    data?: {
+        id: string;
+    } | Array<{
+        id: string;
+    }> | null;
+}
+/** A JSON:API resource object (the ticket entity + its sideloaded includes). */
+export interface JsonApiResource {
+    type?: string;
+    id?: string;
+    attributes?: Record<string, unknown>;
+    relationships?: Record<string, JsonApiRelationship | undefined>;
+}
+/** A ticket-detail document: primary resource + sideloaded includes. */
+export interface TicketDetailDocument {
+    data?: JsonApiResource;
+    included?: JsonApiResource[];
+}
+/** A hosted agent as reported by the injected agent service (herdr-backed in
+ *  production). `id` is the host-owned stable handle, `group` the project it was
+ *  launched under, `label` a human tag for the list. */
+export interface HostedAgent {
+    id: string;
+    group: string;
+    label: string;
+}
+/**
+ * Intent-level agent hosting the TUI drives (GAIA-190). The TUI says launch /
+ * list / focus / hide / kill by an opaque `group` (the project) + an `id` — it
+ * never names panes, tabs, splits or zoom. The host (herdr) owns all layout.
+ * We don't know what the next herdr does; this intent contract survives a
+ * different pane model unchanged.
+ */
+export interface TuiAgentService {
+    /** Start an agent for a group; the host places + shows it. */
+    launch(opts: {
+        group: string;
+        cwd: string;
+        prompt: string;
+        env: Record<string, string | undefined>;
+        isNew?: boolean | undefined;
+        label?: string | undefined;
+    }): Promise<HostedAgent>;
+    /** The live agents of a group (source of truth for the list + restart). */
+    list(group: string): Promise<HostedAgent[]>;
+    /** Bring an agent to the foreground. */
+    focus(id: string): Promise<void>;
+    /** Stop showing a group's agents, back to the caller. Durable — never kills. */
+    hide(group: string): Promise<void>;
+    /** Terminate an agent for good. */
+    kill(id: string): Promise<void>;
+}
+/** The dropsh renderer `services` bag the TUI consumes. */
+export interface RendererServices {
+    client: DropshClient;
+    baseUrl?: string;
+    project?: string;
+    /** Intent-level agent host for `gaia ui` ticket-agents (herdr-backed). */
+    agents?: TuiAgentService;
+    /** This machine's user id — preselected as the new-ticket assignee. */
+    currentUser?: string;
+    /** This machine's conductor `machine_id` — preselected in the new-ticket form. */
+    ownConductorMachineId?: string;
+    /** Config override for the ticket-create agent's base prompt. */
+    createPrompt?: string;
+}
+/** Options passed by the factory into the kernel. */
+export interface TuiOptions {
+    project?: string;
+    cwd?: string;
+    agents?: TuiAgentService;
+    currentUser?: string;
+    ownConductorMachineId?: string;
+    createPrompt?: string;
+}

package/dist/src/types.js

@@ -0,0 +1,5 @@
+// Shared shapes for the dropsh renderer inputs + the JSON:API documents the TUI
+// reads. These model the *contract* the plugin consumes at runtime (the dropsh
+// client, its `toResource(...)` wrappers, and the ticket-detail document) so the
+// modules stay strictly typed without leaking `any`.
+export {};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@gaia-ai/addon-gaia-ui",
+  "version": "0.6.1",
+  "description": "GAIA TUI: interactive terminal UI (project dashboard, ticket list, ticket detail) as a dropsh `tui` renderer plugin.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./preset": "./dist/src/preset.js"
+  },
+  "files": [
+    "dist/src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.key-tec.de/keytec/gaia.git",
+    "directory": "gaia-cli/addons/gaia-ui"
+  },
+  "dependencies": {
+    "drupal-jsonapi-params": "^3.0.1"
+  },
+  "peerDependencies": {
+    "@gaia-ai/core": "^0.6.1"
+  }
+}