@sigrun/tui 0.4.1 → 0.5.0

package/dist/ui/picker.js

@@ -0,0 +1,130 @@
+/**
+ * The picker overlay (Task C3, UI refresh): a centred `showOverlay` box —
+ * a title line, a one-line fuzzy filter, and a `SelectList`. Typing
+ * re-filters (pi-tui's `fuzzyFilter` over label + detail), Enter picks,
+ * Esc closes, and a mouse click picks (SelectList's own mouse handling).
+ *
+ * Conversation/model/command pickers are built by the app from the
+ * sidebar tree, `listModels()`, and the slash catalog respectively.
+ */
+import { fuzzyFilter, Key, matchesKey, SelectList, } from "@earendil-works/pi-tui";
+const MAX_VISIBLE = 10;
+function plainSelectListTheme() {
+    const identity = (text) => text;
+    return {
+        selectedPrefix: identity,
+        selectedText: identity,
+        description: identity,
+        scrollInfo: identity,
+        noMatch: identity,
+    };
+}
+class Picker {
+    #items;
+    #options;
+    #selectTheme;
+    #muted;
+    #query = "";
+    #filtered;
+    #list;
+    #overlay;
+    constructor(items, options) {
+        this.#items = items;
+        this.#options = options;
+        const theme = options.theme;
+        this.#selectTheme =
+            theme === undefined
+                ? plainSelectListTheme()
+                : {
+                    selectedPrefix: (text) => theme.fg("accent")(text),
+                    selectedText: (text) => theme.bold(text),
+                    description: (text) => theme.fg("muted")(text),
+                    scrollInfo: (text) => theme.fg("muted")(text),
+                    noMatch: (text) => theme.fg("muted")(text),
+                };
+        this.#muted =
+            theme === undefined ? (text) => text : (text) => theme.fg("muted")(text);
+        this.#filtered = items;
+        this.#list = this.#buildList();
+    }
+    /** The overlay handle is installed by {@link openPicker} after show. */
+    setOverlay(overlay) {
+        this.#overlay = overlay;
+    }
+    #buildList() {
+        const list = new SelectList(this.#filtered.map((item, index) => ({
+            value: String(index),
+            label: item.label,
+            ...(item.detail === undefined ? {} : { description: item.detail }),
+        })), MAX_VISIBLE, this.#selectTheme);
+        list.onSelect = (item) => {
+            const picked = this.#filtered[Number(item.value)];
+            if (picked === undefined)
+                return;
+            this.#close();
+            this.#options.onPick(picked.value);
+        };
+        list.onCancel = () => this.#close();
+        return list;
+    }
+    #close() {
+        this.#overlay?.hide();
+        this.#options.onClose?.();
+    }
+    #refilter() {
+        const filtered = this.#query === ""
+            ? this.#items
+            : fuzzyFilter([...this.#items], this.#query, (item) => item.detail === undefined ? item.label : `${item.label} ${item.detail}`);
+        this.#filtered = filtered;
+        this.#list = this.#buildList();
+    }
+    handleInput(data) {
+        // C-g is the emacs cancel: close like Esc (the emacs keymap passes it
+        // through while an overlay owns the keys).
+        if (data === "\x07") {
+            this.#close();
+            return;
+        }
+        if (matchesKey(data, Key.backspace) || matchesKey(data, "backspace")) {
+            if (this.#query !== "") {
+                this.#query = this.#query.slice(0, -1);
+                this.#refilter();
+            }
+            return;
+        }
+        // One printable character extends the filter; everything else
+        // (arrows, Enter, Esc, mouse) is the list's own input.
+        if (data.length === 1 && data >= " ") {
+            this.#query += data;
+            this.#refilter();
+            return;
+        }
+        this.#list.handleInput(data);
+    }
+    render(width) {
+        return [
+            this.#muted(this.#options.title),
+            this.#muted(`filter: ${this.#query}`),
+            ...this.#list.render(width),
+        ];
+    }
+    /** The click is additive: delegate to the list under the filter rows. */
+    handleMouse(event) {
+        if (event.y < 2)
+            return { handled: true };
+        return this.#list.handleMouse({ ...event, y: event.y - 2 });
+    }
+    invalidate() {
+        this.#list.invalidate();
+    }
+}
+/** Open a centred picker overlay; Enter/click picks, Esc closes. */
+export function openPicker(tui, items, options) {
+    const picker = new Picker(items, options);
+    const overlay = tui.showOverlay(picker, {
+        anchor: "center",
+        width: "60%",
+        maxHeight: "60%",
+    });
+    picker.setOverlay(overlay);
+}

package/dist/ui/settings.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The TUI Settings view (UI-blocks U4 Task 4, spec §13.4): the settings
+ * panel's terminal twin — the section list from `GET
+ * /v1/settings/sections` as a picker (the search IS the picker's fuzzy
+ * filter: typing "naming" filters the index to General → Naming model;
+ * picking it opens the section's form), each section rendered as a
+ * block form ({@link SurfaceState} + {@link SurfaceView} over the
+ * section's `/v1/ext/<slug>/surfaces/<id>` mount — ONE renderer across
+ * core and extensions, the same code path the webui's SurfaceView
+ * runs).
+ *
+ * Scope rulings (plan Task 4):
+ * - **Interface** (client prefs) has no TUI-local state yet — the view
+ *   renders it as its (empty) surface form; the prefs live in the
+ *   webui's localStorage by design (§13.4's "client-side" ruling).
+ * - **Providers** (the §7.6 credential flows) renders as its settings
+ *   surface form; the per-provider readiness rows and the write-only
+ *   credential editor are the webui's cove — the credential routes
+ *   stay reachable through the API, and the TUI does not render the
+ *   readiness list (a TUI cove is the follow-up).
+ * - **Extensions**: an extension WITHOUT a declared settings section
+ *   keeps its raw-JSON reachability as a NOTICE in the section list
+ *   (one line naming its `/v1/extensions/<slug>/settings` routes —
+ *   the raw JSON editor is the webui's cove).
+ *
+ * The pending-restart callout (§13.2/§13.3) renders above the section
+ * body: the keys the General section's `meta` block carries, with the
+ * Restart action when the server is supervised AND the session is an
+ * admin (the app's `restart()` runs the §13.3 flow), otherwise the
+ * text "Restart sigrun to apply".
+ */
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { filterSettingsIndex } from "@sigrun/shared/views";
+import type { SettingsSectionEntry, SigrunClient } from "../api.js";
+import type { TuiTheme } from "../theme.js";
+export { filterSettingsIndex };
+/** The settings view (the app's `/settings` mount). */
+export declare class SettingsView implements Component {
+    #private;
+    constructor(client: SigrunClient, options: {
+        readonly tui: TUI;
+        readonly theme: TuiTheme;
+        readonly unicode: boolean;
+        readonly onRestart: () => Promise<void>;
+        readonly onClose: () => void;
+    });
+    /** Load the sections list + the admin/supervised flags. */
+    load(): Promise<void>;
+    /** The open section's id (undefined = the section list; tests read it). */
+    get openSectionId(): string | undefined;
+    /** The pending-restart keys the General section's meta carried. */
+    get pendingRestart(): readonly string[];
+    /** The section picker (the search: the picker's fuzzy filter is the
+     *  index query — typing "naming" filters to the Naming model row). */
+    openSearch(): void;
+    /** Open one section (mount its surface). When a search hit carries
+     *  `focusKey`, the matching field takes the focus after load (the
+     *  search's resolve half — "naming" lands on the naming model row). */
+    openSection(section: SettingsSectionEntry, focusKey?: string): Promise<void>;
+    /** Back to the section list (Esc). Returns true when a section was open. */
+    closeSection(): boolean;
+    /** The callout's Restart action (the app wires it). */
+    restart(): Promise<void>;
+    render(width: number): string[];
+    handleInput(data: string): void;
+    dispose(): void;
+    invalidate(): void;
+}

package/dist/ui/settings.js

@@ -0,0 +1,254 @@
+/**
+ * The TUI Settings view (UI-blocks U4 Task 4, spec §13.4): the settings
+ * panel's terminal twin — the section list from `GET
+ * /v1/settings/sections` as a picker (the search IS the picker's fuzzy
+ * filter: typing "naming" filters the index to General → Naming model;
+ * picking it opens the section's form), each section rendered as a
+ * block form ({@link SurfaceState} + {@link SurfaceView} over the
+ * section's `/v1/ext/<slug>/surfaces/<id>` mount — ONE renderer across
+ * core and extensions, the same code path the webui's SurfaceView
+ * runs).
+ *
+ * Scope rulings (plan Task 4):
+ * - **Interface** (client prefs) has no TUI-local state yet — the view
+ *   renders it as its (empty) surface form; the prefs live in the
+ *   webui's localStorage by design (§13.4's "client-side" ruling).
+ * - **Providers** (the §7.6 credential flows) renders as its settings
+ *   surface form; the per-provider readiness rows and the write-only
+ *   credential editor are the webui's cove — the credential routes
+ *   stay reachable through the API, and the TUI does not render the
+ *   readiness list (a TUI cove is the follow-up).
+ * - **Extensions**: an extension WITHOUT a declared settings section
+ *   keeps its raw-JSON reachability as a NOTICE in the section list
+ *   (one line naming its `/v1/extensions/<slug>/settings` routes —
+ *   the raw JSON editor is the webui's cove).
+ *
+ * The pending-restart callout (§13.2/§13.3) renders above the section
+ * body: the keys the General section's `meta` block carries, with the
+ * Restart action when the server is supervised AND the session is an
+ * admin (the app's `restart()` runs the §13.3 flow), otherwise the
+ * text "Restart sigrun to apply".
+ */
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { filterSettingsIndex } from "@sigrun/shared/views";
+import { SurfaceState } from "../blocks/surface.js";
+import { SurfaceView } from "../blocks/surface-view.js";
+import { createExtSurfaceTransport } from "../blocks/ext-transport.js";
+import { openPicker } from "./picker.js";
+// The index filter is `@sigrun/shared`'s (U4 Task 4 round-2) — ONE
+// implementation across the channels; the re-export keeps the view's
+// pre-round-2 import surface.
+export { filterSettingsIndex };
+/** The settings view (the app's `/settings` mount). */
+export class SettingsView {
+    #client;
+    #tui;
+    #theme;
+    #unicode;
+    /** The app's restart action (§13.3) — the callout's Restart. */
+    #onRestart;
+    #onClose;
+    #sections = [];
+    #index = [];
+    #error;
+    /** The open section's surface (undefined = the section list). */
+    #surface;
+    /** Section-less loaded extensions (the raw-JSON notice lines). */
+    #sectionlessExtensions = [];
+    /** The pending-restart block (the General section's `meta`). */
+    #pendingRestart = [];
+    #supervised = false;
+    /** Admin defaults FALSE (the routes are admin-gated — an unknown
+     *  principal must not see the Restart affordance). */
+    #admin = false;
+    constructor(client, options) {
+        this.#client = client;
+        this.#tui = options.tui;
+        this.#theme = options.theme;
+        this.#unicode = options.unicode;
+        this.#onRestart = options.onRestart;
+        this.#onClose = options.onClose;
+    }
+    /** Load the sections list + the admin/supervised flags. */
+    async load() {
+        try {
+            const [sections, whoami, meta, extensions] = await Promise.all([
+                this.#client.listSettingsSections(),
+                this.#client.whoami().catch(() => undefined),
+                this.#client.getBootMeta().catch(() => undefined),
+                this.#client.listExtensions().catch(() => undefined),
+            ]);
+            this.#admin = whoami?.admin === true;
+            this.#sections = sections.sections.filter((section) => section.scope !== "user" || section.admin !== true || this.#admin);
+            const allowed = new Set(this.#sections.map((section) => `${section.slug}\u0000${section.id}`));
+            this.#index = sections.index.filter((entry) => allowed.has(`${entry.slug}\u0000${entry.sectionId}`));
+            this.#supervised = meta?.supervised === true;
+            // Section-less loaded extensions (the raw-JSON notice lines):
+            // every listed extension whose slug declares NO settings section.
+            const withSections = new Set(sections.sections.filter((entry) => entry.slug !== "core").map((entry) => entry.slug));
+            this.#sectionlessExtensions = (extensions?.extensions ?? [])
+                .map((extension) => extension.name)
+                .filter((name) => !withSections.has(name));
+        }
+        catch (cause) {
+            this.#error = cause instanceof Error ? cause.message : String(cause);
+        }
+        this.#tui.requestRender();
+    }
+    /** The open section's id (undefined = the section list; tests read it). */
+    get openSectionId() {
+        return this.#surface?.id;
+    }
+    /** The pending-restart keys the General section's meta carried. */
+    get pendingRestart() {
+        return this.#pendingRestart;
+    }
+    /** The section picker (the search: the picker's fuzzy filter is the
+     *  index query — typing "naming" filters to the Naming model row). */
+    openSearch() {
+        const items = this.#index.map((entry) => ({
+            label: entry.label,
+            detail: `${entry.slug === "core" ? "" : `${entry.slug} · `}${entry.sectionId}`,
+            value: entry,
+        }));
+        openPicker(this.#tui, items, {
+            title: "Settings",
+            onPick: (entry) => {
+                const section = this.#sections.find((candidate) => candidate.slug === entry.slug && candidate.id === entry.sectionId);
+                if (section !== undefined)
+                    void this.openSection(section, entry.key);
+            },
+        });
+    }
+    /** Open one section (mount its surface). When a search hit carries
+     *  `focusKey`, the matching field takes the focus after load (the
+     *  search's resolve half — "naming" lands on the naming model row). */
+    async openSection(section, focusKey) {
+        this.#surface?.state.dispose();
+        const token = this.#client.token;
+        const user = this.#client.user;
+        const transport = createExtSurfaceTransport({
+            slug: section.slug,
+            id: section.id,
+            baseUrl: this.#baseUrl(),
+            ...(token === undefined ? {} : { token }),
+            ...(user === undefined ? {} : { user }),
+            fetch: this.#client.fetch,
+        });
+        const state = new SurfaceState(transport.transport);
+        const view = new SurfaceView(state, {
+            theme: this.#theme,
+            unicode: this.#unicode,
+        });
+        this.#surface = { state, view, id: section.id };
+        state.onChange(() => {
+            // The core sections' meta block feeds the callout (the
+            // pendingRestart diff lands on EVERY core section's meta — a
+            // save in Advanced flips the callout without reopening).
+            if (section.slug === "core") {
+                const meta = state.view.data.meta;
+                if (typeof meta === "object" &&
+                    meta !== null &&
+                    !Array.isArray(meta) &&
+                    Array.isArray(meta.pendingRestart)) {
+                    this.#pendingRestart = meta.pendingRestart.filter((key) => typeof key === "string");
+                    // The surface's `supervised` is authoritative for the
+                    // callout once the section loaded (the load() value is
+                    // the fallback for an unopened General).
+                    const supervised = meta.supervised;
+                    if (typeof supervised === "boolean")
+                        this.#supervised = supervised;
+                }
+            }
+            this.#tui.requestRender();
+        });
+        await state.load();
+        if (focusKey !== undefined)
+            view.focusField(focusKey);
+        this.#tui.requestRender();
+    }
+    /** Back to the section list (Esc). Returns true when a section was open. */
+    closeSection() {
+        if (this.#surface === undefined)
+            return false;
+        this.#surface.state.dispose();
+        this.#surface = undefined;
+        this.#tui.requestRender();
+        return true;
+    }
+    /** The callout's Restart action (the app wires it). */
+    async restart() {
+        await this.#onRestart();
+    }
+    /** The transport's base URL (the client's — the client owns it). */
+    #baseUrl() {
+        return this.#client.baseUrl;
+    }
+    render(width) {
+        const lines = [];
+        lines.push(truncateToWidth(this.#theme.bold("Settings"), width));
+        if (this.#error !== undefined) {
+            lines.push(truncateToWidth(this.#theme.fg("bad")(`error: ${this.#error}`), width));
+            return lines;
+        }
+        // The pending-restart callout (§13.2/§13.3): the keys, plus the
+        // Restart affordance when supervised + admin.
+        if (this.#pendingRestart.length > 0) {
+            lines.push(truncateToWidth(this.#theme.fg("warn")(`Restart sigrun to apply: ${this.#pendingRestart.join(", ")}`), width));
+            if (this.#supervised && this.#admin) {
+                lines.push(truncateToWidth(this.#theme.dim("press ctrl+r to restart now"), width));
+            }
+        }
+        if (this.#surface === undefined) {
+            // The section list (the picker's items carry the search).
+            if (this.#sections.length === 0) {
+                lines.push(truncateToWidth(this.#theme.dim("loading…"), width));
+                return lines;
+            }
+            lines.push(truncateToWidth(this.#theme.dim("/ to search · Enter opens · Esc closes"), width));
+            for (const section of this.#sections.filter((entry) => entry.scope !== "user")) {
+                lines.push(truncateToWidth(`  ${section.title}${section.slug === "core" ? "" : `  (${section.slug})`}`, width));
+            }
+            const personal = this.#sections.filter((entry) => entry.scope === "user");
+            if (personal.length > 0) {
+                lines.push(truncateToWidth(this.#theme.bold("My settings"), width));
+                for (const section of personal) {
+                    lines.push(truncateToWidth(`  ${section.title}${section.slug === "core" ? "" : `  (${section.slug})`}`, width));
+                }
+            }
+            // Extensions WITHOUT a declared section keep their raw-JSON
+            // routes reachable (the docblock's ruling): one notice line
+            // per section-less extension naming its routes.
+            for (const slug of this.#sectionlessExtensions) {
+                // A plain (unstyled) line: the dim theme's escape codes would
+                // break substring matching against the wire contract, and the
+                // notice is informational, not chrome.
+                lines.push(truncateToWidth(`  ${slug}: no settings section — raw JSON at GET/PUT /v1/extensions/${slug}/settings`, width));
+            }
+            return lines;
+        }
+        // The open section: its surface view renders below the callout.
+        lines.push(...this.#surface.view.render(width));
+        return lines;
+    }
+    handleInput(data) {
+        if (this.#surface !== undefined) {
+            // The restart affordance is ctrl+r — a bare "r" is ordinary
+            // text in a focused editor field and must type through.
+            if (data === "\x12" && this.#supervised && this.#admin && this.#pendingRestart.length > 0) {
+                void this.restart();
+                return;
+            }
+            this.#surface.view.handleInput?.(data);
+            return;
+        }
+    }
+    dispose() {
+        this.#surface?.state.dispose();
+        this.#surface = undefined;
+        this.#onClose();
+    }
+    invalidate() {
+        this.#surface?.view.invalidate();
+    }
+}

package/dist/ui/sidebar.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The sidebar (Task 6; restyled in C2, UI refresh): the conversation
+ * TREE — rows come from B1's `buildConversationTree` (fork children
+ * indent two spaces + `↳ `), names are single-line via B1's
+ * `displayName` + pi-tui's `truncateToWidth`, ages right-align via B1's
+ * `formatAge`, and the active row highlights accent-fg + bold. Archived
+ * conversations stay hidden (the tree's `includeArchived: false`; the
+ * server has no delete, archive is the hide). `+ New conversation` is
+ * always the last row.
+ *
+ * The listing itself carries every field the rows need (`name`,
+ * `archived`, `pinned`, `parent`, `lastActivityAt` ride
+ * `ConversationSummary` — A1), so {@link refresh} makes ONE request: no
+ * per-row meta fetch. The app re-refreshes on a 10 s poll (an unref'd
+ * `setInterval` the launcher clears on dispose).
+ *
+ * Keyboard-first (mouse is additive): `cursor` / `moveCursor` /
+ * `confirm()` are the C3 action layer's seam; a click on a row selects
+ * it (`MouseRegion` per row). Selection reports to {@link onSelect}: a
+ * conversation id, or `"new"` for the `+ New conversation` row
+ * (creation is the app's job — the sidebar never calls
+ * createConversation itself).
+ */
+import { type Component } from "@earendil-works/pi-tui";
+import { type TuiTheme } from "../theme.js";
+import type { SigrunClient } from "../api.js";
+/** The sidebar selection: a conversation id, the `+ new` action, or an
+ *  extension VIEW (UI-blocks U3 Task 5 — the app opens it in the main
+ *  pane). */
+export type SidebarSelection = number | "new" | {
+    readonly view: {
+        readonly slug: string;
+        readonly id: string;
+    };
+};
+/** One display row: a conversation, or the trailing `+ New` action. */
+interface SidebarRow {
+    /** The conversation id; -1 for the `+ New conversation` action row. */
+    readonly id: number;
+    /** The display name (displayName — unnamed → "New conversation"). */
+    readonly name: string;
+    /** The tree depth (fork children render indented). */
+    readonly depth: number;
+    /** The right-aligned age column ("" when never used). */
+    readonly age: string;
+    /** Whether this row is the active conversation. */
+    readonly active: boolean;
+}
+export interface SidebarOptions {
+    /** The token theme; defaults to the plain (identity) fallback. */
+    readonly theme?: TuiTheme;
+    /** The clock seam for age rendering (tests pin it). */
+    readonly now?: () => Date;
+}
+export declare class Sidebar implements Component {
+    #private;
+    /** Selection callback: the conversation id, or `"new"` for `+ new`. */
+    onSelect?: (selection: SidebarSelection) => void;
+    constructor(client: SigrunClient, options?: SidebarOptions);
+    /** The conversation rows, in display order (the app's boot default
+     * reads `rows[0]`); the trailing `+ New conversation` action row is
+     * NOT part of this list — it renders last via {@link #newRow}. */
+    get rows(): readonly SidebarRow[];
+    /** The cursor's row index (0-based over {@link rows}). */
+    get cursor(): number;
+    /**
+     * Re-fetch the listing and rebuild the rows from the tree (summary
+     * fields only — no per-row meta fetch). The cursor follows its
+     * conversation when it still exists.
+     */
+    refresh(): Promise<void>;
+    /**
+     * The extension views (U3 Task 5): refetch `GET /v1/extensions` and
+     * rebuild the VIEWS group (one row per declared view surface, in
+     * declaration order, status "ok" only). Panels live in the side pane,
+     * not here. Failures keep the last good list (a flaky server must
+     * never blank the sidebar).
+     */
+    refreshViews(): Promise<void>;
+    /** The extension view rows (the app's openExtView reads them). */
+    get views(): readonly {
+        slug: string;
+        id: string;
+        title: string;
+    }[];
+    /** Select the Nth extension view (the action layer's seam). */
+    confirmView(index: number): void;
+    /** Mark the active conversation (accent fg + bold); pass `undefined` to clear. */
+    setActive(id: number | undefined): void;
+    /** Move the cursor by `delta` rows, clamped to the list. */
+    moveCursor(delta: number): void;
+    /** Select the cursor's row (Enter — the action layer's seam). */
+    confirm(): void;
+    /** The keyboard seam: arrows move, Enter confirms (pre-C3 minimal). */
+    handleInput(data: string): void;
+    render(width: number): string[];
+    invalidate(): void;
+}
+export {};