pi-llama-cpp 0.13.0 → 0.15.0

package/src/ui/editors/listEditor.ts

@@ -0,0 +1,300 @@
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { SettingsList } from "@earendil-works/pi-tui";
+import type { LlamaServer } from "../../interfaces/settings";
+import { BaseDialog } from "../dialog/base";
+import { DialogFactory } from "../dialog/factory";
+import { HINTS } from "../strings";
+import type { SettingsListEditorOptions } from "./editorOptions";
+
+// ─── Abstract base class ──────────────────────────────────────────────────
+
+/**
+ * Base class for SettingsList-based editors that manage a list of servers
+ * with add/delete support at the top level.
+ *
+ * Subclasses must implement:
+ * - {@link buildSettingsList} — how to build the top-level list items
+ * - {@link beginAdd} — how to start the add wizard
+ * - {@link deleteSelected} — how to delete the selected entry
+ * - {@link getRowLabel} — display name for a row at the given index
+ * - {@link emptyHintKey} — which hint to show when the list is empty
+ * - {@link deleteTitle} — dialog title for the delete confirmation
+ */
+export abstract class ListEditor<
+  O extends SettingsListEditorOptions = SettingsListEditorOptions,
+> implements Component {
+  protected settingsList: SettingsList | null = null;
+  protected isFocused = false;
+  /** The currently open modal dialog (add wizard, input, or confirm),
+   * when one is up: input/render/invalidate/focus all delegate to it
+   * until it is cleared via {@link closeDialog}. */
+  protected activeDialog: BaseDialog | undefined;
+  /** Dialog factory holding `theme`/`tui` once for all dialog construction. */
+  protected readonly dialogs: DialogFactory;
+  /** Whether a row's field submenu is open. While open, input is delegated
+   * to the settingsList and list rebuilds are deferred: rebuilding would
+   * discard the submenu and kick the user back to the list. */
+  protected submenuOpen = false;
+  /** Row index of a rebuild deferred by {@link commitFieldChange} while a
+   * submenu was open; flushed by {@link trackSubmenu} on close. */
+  private deferredRebuild: number | null = null;
+  /** Selected row index. Mirrors the `SettingsList`'s selection, which is
+   * `private` in pi-tui's typings and thus unreachable — so this copy is
+   * advanced by the same wrap-around logic the list applies internally
+   * (both handle the same up/down keypress). Kept in sync explicitly in
+   * {@link rebuildList} via `selectItem`. */
+  protected selectedIndex = 0;
+
+  constructor(protected readonly options: O) {
+    this.dialogs = new DialogFactory(options.theme, options.tui);
+  }
+
+  // -- abstract hooks -------------------------------------------------------
+
+  /** Build the top-level SettingsList from the current data snapshot. */
+  protected abstract buildSettingsList(): SettingsList | Promise<SettingsList>;
+
+  /** Start the add wizard (called when user presses "a"). */
+  protected abstract beginAdd(): void;
+
+  /** Delete the currently selected entry (called after confirmation). */
+  protected abstract deleteSelected(): void;
+
+  /** Hint line key for the empty-list state. */
+  protected abstract readonly emptyHintKey:
+    | "emptyServers"
+    | "emptyOverrideEntries";
+
+  /** Returns the id for a row at the given index. */
+  protected abstract getRowId(index: number): string;
+
+  /** Returns the display label for a row at the given index. */
+  protected abstract getRowLabel(index: number): string;
+
+  /** Title for the delete confirmation dialog (e.g. "Delete server"). */
+  protected abstract get deleteTitle(): string;
+
+  /** Returns the number of items in the current list. Override when the
+   * list items don't directly correspond to `options.servers`. */
+  protected getCount(): number {
+    return this.options.servers.length;
+  }
+
+  // -- hooks -----------------------------------------------------------------
+
+  /**
+   * Closes this editor on Esc. The base implementation ends the whole
+   * dialog (`options.done`) — correct for top-level editors. Drill-down
+   * subclasses that live inside another editor's submenu override this
+   * to step back one level instead (their `options.done` still points
+   * at the top-level close inherited through the shared options).
+   */
+  protected close(): void {
+    this.options.done();
+  }
+
+  // -- Focusable ------------------------------------------------------------
+
+  get focused(): boolean {
+    return this.isFocused;
+  }
+
+  set focused(value: boolean) {
+    this.isFocused = value;
+    if (this.activeDialog) this.activeDialog.focused = value;
+  }
+
+  // -- Component ------------------------------------------------------------
+
+  invalidate(): void {
+    this.settingsList?.invalidate();
+    this.activeDialog?.invalidate();
+  }
+
+  handleInput(data: string): void {
+    // Delegate to the open modal dialog, if any
+    if (this.delegateToDialogInput(data)) return;
+
+    // Delegate to settingsList if a submenu is open
+    if (this.submenuOpen && this.settingsList) {
+      this.settingsList.handleInput(data);
+      return;
+    }
+
+    // Top-level keybindings. Up/down mirror the wrap-around the
+    // `SettingsList` applies internally to the same keypress (its
+    // selection is private — see the {@link selectedIndex} doc); the
+    // trailing forward to `settingsList.handleInput` is what actually
+    // moves the rendered cursor.
+    const kb = this.options.keybindings;
+    if (kb.matches(data, "tui.select.cancel")) {
+      this.close();
+      return;
+    }
+    if (kb.matches(data, "tui.select.up")) {
+      this.selectedIndex =
+        this.selectedIndex === 0 ? this.getCount() - 1 : this.selectedIndex - 1;
+    }
+    if (kb.matches(data, "tui.select.down")) {
+      this.selectedIndex =
+        this.selectedIndex === this.getCount() - 1 ? 0 : this.selectedIndex + 1;
+    }
+    if (data === "a") {
+      this.beginAdd();
+      return;
+    }
+    if (data === "d") {
+      this.beginConfirm();
+      return;
+    }
+    if (this.settingsList) {
+      this.settingsList.handleInput(data);
+    }
+  }
+
+  render(width: number): string[] {
+    // Delegate to the open modal dialog, if any
+    if (this.activeDialog) return this.activeDialog.render(width);
+
+    // Empty list hint
+    if (!this.settingsList) return ["Loading..."];
+    const lines = this.settingsList.render(width);
+    if (this.getCount() === 0) {
+      lines[lines.length - 1] = getSettingsListTheme().hint(
+        HINTS[this.emptyHintKey],
+      );
+    }
+    return lines;
+  }
+
+  // -- helpers ---------------------------------------------------------------
+
+  /**
+   * If a dialog is open, delegates input to it and returns true;
+   * otherwise returns false. Used to short-circuit handleInput.
+   */
+  private delegateToDialogInput(data: string): boolean {
+    if (this.activeDialog) {
+      this.activeDialog.handleInput(data);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Rebuilds the list and places the cursor on `targetIndex`.
+   * Subclasses call this after add/delete/persist to refresh the UI.
+   */
+  protected async rebuildList(targetIndex: number): Promise<void> {
+    const list = await this.buildSettingsList();
+    this.settingsList = list;
+    const count = this.getCount();
+    if (count === 0) {
+      this.selectedIndex = 0;
+      this.options.tui.requestRender();
+      return;
+    }
+    this.selectedIndex = Math.min(targetIndex, count - 1);
+    this.settingsList.selectItem(this.getRowId(this.selectedIndex));
+    // Rebuilding is async (health checks); request a render only once the
+    // new list is in place, otherwise the old frame stays on screen
+    this.options.tui.requestRender();
+  }
+
+  /**
+   * Tracks a row's field submenu opening or closing. While a submenu is
+   * open, {@link rebuildList} would discard it and kick the user back to
+   * the list — so a rebuild deferred by {@link commitFieldChange} is
+   * flushed here on close instead of running mid-edit.
+   */
+  protected trackSubmenu(open: boolean): void {
+    this.submenuOpen = open;
+    if (open) return;
+    const index = this.deferredRebuild;
+    this.deferredRebuild = null;
+    if (index !== null) void this.rebuildList(index);
+  }
+
+  /**
+   * Opens a modal dialog: input/render delegate to it until
+   * {@link closeDialog}. Focus follows the editor's.
+   */
+  protected openDialog(dialog: BaseDialog): void {
+    this.activeDialog = dialog;
+    dialog.focused = this.isFocused;
+    this.options.tui.requestRender();
+  }
+
+  /** Closes the open modal dialog and returns to the list. */
+  protected closeDialog(): void {
+    this.activeDialog = undefined;
+    this.options.tui.requestRender();
+  }
+
+  /**
+   * Opens the delete confirmation dialog.
+   */
+  protected beginConfirm(): void {
+    const idx = this.selectedIndex;
+    const name = this.getRowLabel(idx);
+    if (!name) return;
+
+    this.openDialog(
+      this.dialogs.confirmDelete(
+        this.deleteTitle,
+        name,
+        () => {
+          this.closeDialog();
+          void this.deleteSelected();
+        },
+        () => this.closeDialog(),
+      ),
+    );
+  }
+
+  /**
+   * Persists `next`; on success adopts it and runs `onSuccess`;
+   * on failure notifies and stays in list mode.
+   *
+   * Callers must close any open dialog *before* the async persist:
+   * render() returns the list once `activeDialog` is cleared, so
+   * leaving the dialog open would blank the screen mid-save.
+   */
+  protected async persistSnapshot(
+    next: LlamaServer[],
+    onSuccess: () => void,
+  ): Promise<void> {
+    try {
+      await this.options.persist(next);
+    } catch (err) {
+      this.options.onError(String(err));
+      this.options.tui.requestRender();
+      return;
+    }
+    this.options.servers = next;
+    onSuccess();
+  }
+
+  /**
+   * Handles a field commit from an open row submenu: persists `next` and,
+   * on success, refreshes the open submenu UI in place via `refresh`, then
+   * defers the full list rebuild of row `deferIndex` until the submenu
+   * closes (rebuilding now would discard the submenu and kick the user
+   * back to the list — see {@link trackSubmenu}). No-op when
+   * `next` is the current list (unchanged, callers compare by reference).
+   */
+  protected commitFieldChange(
+    next: LlamaServer[],
+    deferIndex: number | null,
+    refresh: () => void,
+  ): void {
+    if (next === this.options.servers) return;
+    void this.persistSnapshot(next, () => {
+      refresh();
+      if (deferIndex !== null && this.submenuOpen)
+        this.deferredRebuild = deferIndex;
+      this.options.tui.requestRender();
+    });
+  }
+}

package/src/ui/editors/override/entry.ts

@@ -0,0 +1,24 @@
+import type { LlamaServer, ModelOverride } from "../../../interfaces/settings";
+
+/**
+ * One override entry: the pattern key and its override object. Owns the
+ * canonical construction from a server's overrides map, so the editor
+ * and the mutator share a single entry representation. Row rendering
+ * (summary) is registry-driven — see `OverrideSummary`.
+ */
+export class OverrideEntry {
+  constructor(
+    readonly pattern: string,
+    readonly override: ModelOverride,
+  ) {}
+
+  /**
+   * Entries of a server's overrides map, in map iteration order (the
+   * order the entry list renders and mutates by).
+   */
+  static listFrom(server: LlamaServer | undefined): OverrideEntry[] {
+    return Object.entries(server?.overrides ?? {}).map(
+      ([pattern, override]) => new OverrideEntry(pattern, override),
+    );
+  }
+}

package/src/ui/editors/override/entryEditor.ts

@@ -0,0 +1,248 @@
+import type { SettingItem, SettingsList } from "@earendil-works/pi-tui";
+import type { LlamaServer, ModelOverride } from "../../../interfaces/settings";
+import { FIELDS, FieldMessages, HINTS, TITLES } from "../../strings";
+import type { OverrideSettingsListOptions } from "../editorOptions";
+import { ListEditor } from "../listEditor";
+import { SettingsListFactory } from "../settingsListFactory";
+import { OverrideEntry } from "./entry";
+import { OverrideFields, OverrideSummary } from "./fields/index";
+import { OverrideItemBuilder } from "./itemBuilder";
+
+/**
+ * The override entries of a single server, as a list view with add/delete.
+ */
+export class OverrideEntryListEditor extends ListEditor<OverrideSettingsListOptions> {
+  /** Currently open field submenu, so commits can refresh its rows */
+  private fieldList: SettingsList | null = null;
+
+  constructor(
+    /** Shared options object — `persistSnapshot` updates `options.servers`
+     * in place so later drill-downs (and sibling editors) see the change */
+    options: OverrideSettingsListOptions,
+    private readonly serverIndex: number,
+    /** Closes this editor (called on Esc in the entry list) */
+    private readonly done: () => void,
+  ) {
+    super(options);
+    this.settingsList = this.buildSettingsList();
+  }
+
+  // -- hooks ---------------------------------------------------------------
+
+  /** Esc steps back to the server list, not out of the whole dialog —
+   * `options.done` is the top-level close (shared options object). */
+  protected close(): void {
+    this.done();
+  }
+
+  // -- abstract hooks -------------------------------------------------------
+
+  protected buildSettingsList(): SettingsList {
+    const builder = new OverrideItemBuilder(this.dialogs);
+    const items: SettingItem[] = this.entries().map((entry, i) => ({
+      id: `entry-${i}`,
+      label: entry.pattern,
+      description: HINTS.overrideEntryRow,
+      currentValue: OverrideSummary.of(entry.override),
+      submenu: (_cv, done) => {
+        const current = this.entries()[i] ?? entry;
+        const fieldItems = builder.buildFieldItems(current);
+        const fieldList = SettingsListFactory.create(
+          fieldItems,
+          () => {
+            this.fieldList = null;
+            done();
+            // Flushes any rebuild deferred by a pattern rename
+            // (see commitFieldChange)
+            this.trackSubmenu(false);
+          },
+          (field, value) => void this.handleFieldChange(i, field, value),
+        );
+        this.fieldList = fieldList;
+        this.trackSubmenu(true);
+        return fieldList;
+      },
+    }));
+
+    return SettingsListFactory.create(items, () => {
+      this.done();
+    });
+  }
+
+  /** Handle a field commit from a row's submenu. */
+  private handleFieldChange(
+    entryIndex: number,
+    field: string,
+    value: string,
+  ): void {
+    const result = this.applyFieldChange(entryIndex, field, value);
+    if (!result) return;
+
+    this.commitFieldChange(
+      result.next,
+      // The entry row's label is the pattern, and SettingsList labels
+      // can't be patched in place — defer the rebuild until the submenu
+      // closes so the user stays inside it (see commitFieldChange)
+      field === "pattern" ? entryIndex : null,
+      () => {
+        // Refresh the entry row's summary in place
+        this.settingsList?.updateValue(
+          `entry-${entryIndex}`,
+          OverrideSummary.of(result.updatedOverride),
+        );
+        // Refresh the committed row in the open field submenu. Passing
+        // `value` as the pattern makes the pattern field display the new
+        // pattern; other fields only read the override.
+        this.fieldList?.updateValue(
+          field,
+          OverrideFields.byId(field).displayValue(
+            new OverrideEntry(value, result.updatedOverride),
+          ),
+        );
+      },
+    );
+  }
+
+  protected beginAdd(): void {
+    this.openDialog(
+      this.dialogs.input({
+        title: TITLES.addOverride,
+        message: FieldMessages.of(FIELDS.pattern),
+        placeholder: FIELDS.pattern.placeholder,
+        validate: OverrideFields.byId("pattern").validate,
+        onSubmit: (value) => {
+          this.closeDialog();
+          void this.saveAdd(value);
+        },
+        onCancel: () => this.closeDialog(),
+      }),
+    );
+  }
+
+  protected deleteSelected(): void {
+    const idx = this.selectedIndex;
+    const next = this.removeEntry(idx);
+    void this.persistSnapshot(next, () => {
+      this.rebuildList(idx);
+      this.options.onChanged?.();
+      this.options.tui.requestRender();
+    });
+  }
+
+  protected readonly emptyHintKey = "emptyOverrideEntries" as const;
+
+  protected getCount(): number {
+    return this.entries().length;
+  }
+
+  protected getRowId(index: number): string {
+    return `entry-${index}`;
+  }
+
+  protected getRowLabel(index: number): string {
+    return this.entries()[index]?.pattern ?? "";
+  }
+
+  protected get deleteTitle(): string {
+    return TITLES.deleteOverride;
+  }
+
+  // -- helpers ---------------------------------------------------------------
+
+  /** The server's override entries, in map iteration order. */
+  private entries(): OverrideEntry[] {
+    return OverrideEntry.listFrom(this.options.servers[this.serverIndex]);
+  }
+
+  /** Handles a field commit from an override entry's submenu. Returns
+   * `null` when the entry doesn't exist (stale index — no-op). */
+  private applyFieldChange(
+    entryIndex: number,
+    field: string,
+    value: string,
+  ): { next: LlamaServer[]; updatedOverride: ModelOverride } | null {
+    const entry = this.entries()[entryIndex];
+    if (!entry) return null;
+
+    // Pattern field: rename the pattern key, keep the override object
+    if (field === "pattern") {
+      return {
+        next: this.updateEntry(entryIndex, value, entry.override),
+        updatedOverride: entry.override,
+      };
+    }
+
+    // Other fields: let the field definition apply itself
+    const updatedOverride: ModelOverride = { ...entry.override };
+    OverrideFields.byId(field).apply(updatedOverride, value);
+
+    return {
+      next: this.updateEntry(entryIndex, entry.pattern, updatedOverride),
+      updatedOverride,
+    };
+  }
+
+  /** Adds a new override entry with a uniquified pattern. */
+  private addEntry(pattern: string): LlamaServer[] {
+    const server = this.options.servers[this.serverIndex];
+    if (!server) return this.options.servers;
+
+    const existing = new Set(Object.keys(server.overrides ?? {}));
+    let uniquePattern = pattern;
+    let n = 2;
+    while (existing.has(uniquePattern)) {
+      uniquePattern = `${pattern}-${n++}`;
+    }
+
+    return this.withServer((s) => ({
+      ...s,
+      overrides: { ...s.overrides, [uniquePattern]: {} },
+    }));
+  }
+
+  /** Removes the entry at `entryIndex`. */
+  private removeEntry(entryIndex: number): LlamaServer[] {
+    return this.withServer((s) => ({
+      ...s,
+      overrides: Object.fromEntries(
+        Object.entries(s.overrides ?? {}).filter((_, j) => j !== entryIndex),
+      ),
+    }));
+  }
+
+  /** Returns the servers with the target server replaced by
+   * `fn(server)`. Immutable. */
+  private withServer(fn: (server: LlamaServer) => LlamaServer): LlamaServer[] {
+    return this.options.servers.map((server, i) =>
+      i === this.serverIndex ? fn(server) : server,
+    );
+  }
+
+  /** Replaces the entry at `entryIndex` with `pattern → override` in a
+   * single mutation — used both for renaming the pattern and for editing
+   * its fields. The entry keeps its position in the map's iteration
+   * order. Immutable. */
+  private updateEntry(
+    entryIndex: number,
+    pattern: string,
+    override: ModelOverride,
+  ): LlamaServer[] {
+    return this.withServer((s) => ({
+      ...s,
+      overrides: Object.fromEntries(
+        Object.entries(s.overrides ?? {}).map(([k, v], j) =>
+          j === entryIndex ? [pattern, override] : [k, v],
+        ),
+      ),
+    }));
+  }
+
+  private async saveAdd(pattern: string): Promise<void> {
+    const next = this.addEntry(pattern);
+    await this.persistSnapshot(next, () => {
+      this.rebuildList(this.entries().length - 1);
+      this.options.onChanged?.();
+      this.options.tui.requestRender();
+    });
+  }
+}

package/src/ui/editors/override/fields/base.ts

@@ -0,0 +1,53 @@
+import type { ModelOverride } from "../../../../interfaces/settings";
+import { SettingField } from "../../settingField";
+import { OverrideEntry } from "../entry";
+
+/** Type of a field: "input" for free-text, "finite" for fixed options */
+export type FieldType = "input" | "finite";
+
+/** Validation function for input fields */
+export type InputValidator = (raw: string) => string | null;
+
+/**
+ * Abstract base class for one editable field of a model override entry
+ * (Template Method): each subclass owns its display format, validation
+ * and apply logic in a single place, so the parse/format round-trips
+ * can't drift. Extends the shared {@link SettingField} base (id, label,
+ * description, placeholder from the FIELDS registry).
+ */
+export abstract class OverrideField extends SettingField<OverrideEntry> {
+  /** Field type: "input" for free-text, "finite" for fixed options. */
+  abstract readonly type: FieldType;
+
+  /**
+   * Canonical display label for this field — the single source of truth
+   * for both the field rows' `currentValue` and the post-commit refresh
+   * of an open field submenu, so the two can't drift.
+   */
+  abstract displayValue(entry: OverrideEntry): string;
+
+  /** Current value shown in the row — defaults to `displayValue`. */
+  currentValue(entry: OverrideEntry): string {
+    return this.displayValue(entry);
+  }
+
+  /** For "input" fields: validation function for committed values. */
+  abstract readonly validate: InputValidator;
+
+  /** For "finite" fields: the fixed options (undefined for "input"). */
+  readonly options: readonly string[] | undefined = undefined;
+
+  /** Applies a committed value to the override object. The pattern key
+   * rename is handled separately by the mutator (default: no-op). */
+  apply(_override: ModelOverride, _value: string): void {
+    // no-op — override in subclasses that need to mutate the override
+  }
+
+  /** One `term: value` part of the entry-row summary (see
+   * {@link OverrideSummary.of}), or `null` when the field shouldn't
+   * appear (unset/zero values — each field decides). The pattern is the
+   * row label, so it never contributes a part; the default is `null`. */
+  summaryPart(_override: ModelOverride): string | null {
+    return null;
+  }
+}

package/src/ui/editors/override/fields/capabilities.ts

@@ -0,0 +1,36 @@
+import type { ModelOverride } from "../../../../interfaces/settings";
+import { FIELDS } from "../../../strings";
+import { OverrideEntry } from "../entry";
+import type { InputValidator } from "./base";
+import { OverrideField } from "./base";
+
+/** The override's `capabilities` list (finite: fixed label options). */
+export class CapabilitiesField extends OverrideField {
+  readonly id = "capabilities";
+  readonly type = "finite";
+  readonly field = FIELDS.capabilities;
+  override readonly options = ["text", "text | image"];
+
+  displayValue(entry: OverrideEntry): string {
+    return entry.override.capabilities?.join(" | ") ?? "text";
+  }
+
+  readonly validate: InputValidator = (raw) =>
+    this.options?.includes(raw) ? raw : null;
+
+  apply(override: ModelOverride, value: string): void {
+    override.capabilities =
+      value === "text | image"
+        ? ["text", "image"]
+        : value === "text"
+          ? ["text"]
+          : undefined;
+  }
+
+  /** Appears in the summary only when non-empty. */
+  override summaryPart(override: ModelOverride): string | null {
+    return override.capabilities?.length
+      ? `capabilities: ${override.capabilities.join(",")}`
+      : null;
+  }
+}