pi-llama-cpp 0.13.0 → 0.14.0

package/src/ui/editors/server/fields.ts

@@ -0,0 +1,84 @@
+import type { LlamaServer } from "../../../interfaces/settings";
+import { ServerUrl } from "../../../utils/urls";
+import { FIELDS, type Field } from "../../strings";
+import { SettingField } from "../settingField";
+import { LlamaServerBuilder } from "./builder";
+
+/**
+ * Base class for one editable field of a server row. `apply` delegates
+ * to {@link LlamaServerBuilder} so the unset-on-empty rule for `id`/
+ * `name` stays in one place. Mirrors the override side's
+ * `OverrideField`.
+ */
+export abstract class ServerField extends SettingField<LlamaServer> {
+  /** Validation function for committed values (`undefined` = accept
+   * any). */
+  readonly validate: ((raw: string) => string | null) | undefined = undefined;
+
+  /** Applies a committed value to the server, immutably (returns the
+   * updated copy). */
+  abstract apply(server: LlamaServer, value: string): LlamaServer;
+}
+
+/** The server URL (required, validated). */
+class UrlField extends ServerField {
+  readonly id = "url";
+  readonly field = FIELDS.serverUrl;
+  readonly validate = ServerUrl.parse;
+
+  currentValue(server: LlamaServer): string {
+    return server.url;
+  }
+
+  apply(server: LlamaServer, value: string): LlamaServer {
+    return LlamaServerBuilder.from(server).url(value).build();
+  }
+}
+
+/**
+ * An optional string field (`id`, `name`). Empty input omits the key —
+ * when editing an existing server this removes it, restoring the
+ * URL-based auto-detected id for `id`.
+ */
+class OptionalTextField extends ServerField {
+  readonly field: Field;
+
+  constructor(
+    readonly id: "id" | "name",
+    field: Field,
+  ) {
+    super();
+    this.field = field;
+  }
+
+  currentValue(server: LlamaServer): string {
+    return server[this.id] ?? "";
+  }
+
+  apply(server: LlamaServer, value: string): LlamaServer {
+    const builder = LlamaServerBuilder.from(server);
+    return this.id === "id"
+      ? builder.optionalId(value).build()
+      : builder.optionalName(value).build();
+  }
+}
+
+/**
+ * The field registry for servers: the complete list of editable fields
+ * (order defines the row order in the settings list) plus id-based
+ * lookup. Throws on an unknown id — the registry is static, so a miss is
+ * a programming error.
+ */
+export class ServerFields {
+  static readonly all: readonly ServerField[] = [
+    new UrlField(),
+    new OptionalTextField("id", FIELDS.providerId),
+    new OptionalTextField("name", FIELDS.displayName),
+  ];
+
+  static byId(id: string): ServerField {
+    const field = this.all.find((f) => f.id === id);
+    if (!field) throw new Error(`Unknown server field: ${id}`);
+    return field;
+  }
+}

package/src/ui/editors/server/handlers.ts

@@ -0,0 +1,32 @@
+import type { LlamaServer } from "../../../interfaces/settings";
+import { ServerFields } from "./fields";
+
+/**
+ * Applies field commits to a single server, immutably. Binds the server
+ * list and server index once in the constructor so call sites don't
+ * juggle long positional lists. Mirrors the override side's
+ * `OverrideEntryMutator`.
+ *
+ * Per-field commit behavior lives in the `ServerFields` registry
+ * (`apply` on each field class, backed by `LlamaServerBuilder`) — this
+ * class only resolves the field definition and produces the next list.
+ */
+export class ServerEntryMutator {
+  constructor(
+    private readonly servers: LlamaServer[],
+    private readonly serverIndex: number,
+  ) {}
+
+  /**
+   * Handles a field commit from a server row's submenu. Returns the
+   * next server list, or the same list when the server is missing
+   * (no-op — callers can compare by reference).
+   */
+  applyFieldChange(field: string, value: string): LlamaServer[] {
+    const server = this.servers[this.serverIndex];
+    if (!server) return this.servers;
+
+    const updated = ServerFields.byId(field).apply(server, value);
+    return this.servers.map((s, i) => (i === this.serverIndex ? updated : s));
+  }
+}

package/src/ui/editors/server/itemBuilder.ts

@@ -0,0 +1,68 @@
+import type { SettingItem } from "@earendil-works/pi-tui";
+import type { LlamaServer } from "../../../interfaces/settings";
+import { FieldMessages, HINTS, TITLES } from "../../strings";
+import { ItemBuilder } from "../itemBuilder";
+import { SettingsListFactory } from "../settingsListFactory";
+import { ServerFields, type ServerField } from "./fields";
+import { ServerDisplay } from "./utils";
+
+/**
+ * Builds `SettingItem` objects for server rows and their field-edit submenus.
+ */
+export class ServerItemBuilder extends ItemBuilder<LlamaServer, ServerField> {
+  protected get fields(): readonly ServerField[] {
+    return ServerFields.all;
+  }
+
+  /**
+   * Adds the field-edit submenu: an `InputDialog` validating against the
+   * field definition.
+   */
+  protected decorate(
+    def: ServerField,
+    server: LlamaServer,
+    base: SettingItem,
+  ): SettingItem {
+    return {
+      ...base,
+      submenu: this.dialogs.inputSubmenu(
+        TITLES.edit(def.label),
+        FieldMessages.of(def.field),
+        def.placeholder,
+        def.validate,
+      ),
+    };
+  }
+
+  /**
+   * Builds the `SettingItem` for one server row in the top-level list.
+   * Enter drills into the server's field-edit submenu.
+   */
+  buildRow(
+    server: LlamaServer,
+    index: number,
+    onChange: (field: string, value: string) => void,
+    healthEmoji: string,
+    onSubmenuChange: (open: boolean) => void,
+  ): SettingItem {
+    return {
+      id: `server-${index}`,
+      label: `${healthEmoji} ${server.url}`,
+      description: HINTS.serverRow,
+      currentValue: ServerDisplay.suffix(server),
+      submenu: (_cv, done) => {
+        // Rebuild the field items on open so they prefill with current values
+        const items = this.buildFieldItems(server);
+        onSubmenuChange(true);
+        return SettingsListFactory.create(
+          items,
+          () => {
+            onSubmenuChange(false);
+            done();
+          },
+          onChange,
+        );
+      },
+    };
+  }
+}

package/src/ui/editors/server/serverEditor.ts

@@ -0,0 +1,161 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import type { SettingItem, SettingsList } from "@earendil-works/pi-tui";
+import { SERVER_TIMEOUT } from "../../../constants";
+import type { LlamaServer } from "../../../interfaces/settings";
+import type { LlamaSettingsManager } from "../../../managers/settings";
+import { TITLES } from "../../strings";
+import type { ServerSettingsListOptions } from "../editorOptions";
+import { ListEditor } from "../listEditor";
+import { SettingsListFactory } from "../settingsListFactory";
+import { ServerEntryMutator } from "./handlers";
+import { ServerItemBuilder } from "./itemBuilder";
+import { ServerDisplay } from "./utils";
+import { ServerWizard } from "./wizard";
+
+/**
+ * Wrapper around a `SettingsList` of servers that adds `a` (add) and `d`
+ * (delete) support at the list level.
+ *
+ * - **a** opens the add wizard — a sequence of framed `InputDialog`s
+ *   (URL → optional ID → optional name, mirroring `/login`'s sequential
+ *   prompts). Esc at any step aborts without persisting; the server is
+ *   saved only after the final step.
+ * - **d** opens a `ConfirmDialog` (Delete/Cancel select list).
+ * - **Enter** on a server row drills into its field-edit submenu.
+ * - **Esc** closes the editor.
+ */
+export class ServerSettingsList extends ListEditor<ServerSettingsListOptions> {
+  constructor(options: ServerSettingsListOptions) {
+    super(options);
+    void this.buildSettingsList().then((list) => {
+      this.settingsList = list;
+      this.options.tui.requestRender();
+    });
+  }
+
+  /**
+   * Opens the editor in a modal `ui.custom` dialog seeded with the
+   * current `llamaSettings.servers` and resolves when the user closes
+   * it (Esc). Writes go through `settings.setLlamaSetting()`; write
+   * errors are notified via `ui` and the editor stays open with the
+   * pre-mutation list.
+   */
+  static async show(
+    ui: ExtensionUIContext,
+    settings: LlamaSettingsManager,
+  ): Promise<void> {
+    const servers = await settings.getLlamaServers();
+    const { serverTimeout } = await settings.resolveTimeouts();
+
+    await ui.custom<void>(
+      (tui, theme, keybindings, done) =>
+        new ServerSettingsList({
+          tui,
+          theme,
+          keybindings,
+          servers,
+          persist: (next) => settings.setLlamaSetting("servers", next),
+          done: () => done(undefined),
+          onError: (message) => ui.notify(message, "error"),
+          serverTimeout,
+        }),
+    );
+  }
+
+  // -- abstract hooks -------------------------------------------------------
+
+  protected async buildSettingsList(): Promise<SettingsList> {
+    const builder = new ServerItemBuilder(this.dialogs);
+    const serverTimeout = this.options.serverTimeout ?? SERVER_TIMEOUT;
+    const healthEmojis = await Promise.all(
+      this.options.servers.map((server) =>
+        ServerDisplay.healthEmoji(server.url, serverTimeout),
+      ),
+    );
+    const items: SettingItem[] = this.options.servers.map((server, i) =>
+      builder.buildRow(
+        server,
+        i,
+        (field, value) => this.handleFieldChange(field, value),
+        healthEmojis[i],
+        // Opening delegates input to the submenu; closing flushes a
+        // rebuild deferred by a field commit (see commitFieldChange)
+        (open) => this.trackSubmenu(open),
+      ),
+    );
+
+    return SettingsListFactory.create(items, () => {
+      this.options.done();
+    });
+  }
+
+  /** Handle a field commit from a server row's submenu. */
+  private handleFieldChange(field: string, value: string): void {
+    const idx = this.selectedIndex;
+    const next = new ServerEntryMutator(
+      this.options.servers,
+      idx,
+    ).applyFieldChange(field, value);
+
+    this.commitFieldChange(next, idx, () => {
+      // Refresh the row's suffix in place; the full rebuild (row labels
+      // with health emoji, fresh server snapshots for the field submenu)
+      // is deferred until the submenu closes (see commitFieldChange)
+      const updated = next[idx];
+      if (updated) {
+        this.settingsList?.updateValue(
+          `server-${idx}`,
+          ServerDisplay.suffix(updated),
+        );
+      }
+    });
+  }
+
+  protected beginAdd(): void {
+    const wizard = new ServerWizard(this.dialogs, (dialog) =>
+      this.openDialog(dialog),
+    );
+    wizard.start(
+      (server) => {
+        this.closeDialog();
+        void this.saveNewServer(server);
+      },
+      () => this.closeDialog(),
+    );
+  }
+
+  protected deleteSelected(): void {
+    const idx = this.selectedIndex;
+    const next = this.options.servers.filter((_, i) => i !== idx);
+    void this.persistSnapshot(next, () => {
+      void this.rebuildList(idx);
+    });
+  }
+
+  protected readonly emptyHintKey = "emptyServers" as const;
+
+  protected getCurrentCount(): number {
+    return this.options.servers.length;
+  }
+
+  protected getRowId(index: number): string {
+    return `server-${index}`;
+  }
+
+  protected getRowLabel(index: number): string {
+    return this.options.servers[index]?.url ?? "";
+  }
+
+  protected get deleteTitle(): string {
+    return TITLES.deleteServer;
+  }
+
+  // -- wizard helpers --------------------------------------------------------
+
+  private async saveNewServer(server: LlamaServer): Promise<void> {
+    const next = [...this.options.servers, server];
+    await this.persistSnapshot(next, () => {
+      void this.rebuildList(next.length - 1);
+    });
+  }
+}

package/src/ui/editors/server/utils.ts

@@ -0,0 +1,45 @@
+import { ServerStatus } from "../../../enums/serverStatus";
+import type { LlamaServer } from "../../../interfaces/settings";
+import { checkServerHealth } from "../../../utils/health";
+import { ServerIds } from "../../../utils/serverIds";
+
+/**
+ * Display concerns for a server row in the top-level list: the dim
+ * `(...)` suffix after the URL and the health-status icon.
+ */
+export class ServerDisplay {
+  /**
+   * Formats the dim `(...)` suffix shown after a server's URL:
+   * `(<id> - <name>)`, with the auto-detected URL-based id used when no
+   * custom id override exists (mirrors `Server.providerId`). Returns the
+   * empty string when there is nothing to show.
+   */
+  static suffix(server: LlamaServer): string {
+    if (!server.id && !server.name) return "";
+    const id = ServerIds.resolve(server.url, server.id);
+    return server.name ? `(${id} - ${server.name})` : `(${server.id})`;
+  }
+
+  /**
+   * Checks the health of a server and returns the corresponding emoji.
+   *
+   * Delegates the probe/classification to the shared `checkServerHealth`
+   * (`utils/health`) — this wrapper only maps the status to its icon.
+   *
+   * @param url - The server URL to check
+   * @param timeout - Maximum time (ms) to wait for the health check
+   * @returns The health emoji for the server status
+   */
+  static async healthEmoji(url: string, timeout: number): Promise<string> {
+    return SERVER_STATUS_ICONS[await checkServerHealth(url, timeout)];
+  }
+}
+
+/**
+ * Emoji indicators for server health status.
+ */
+const SERVER_STATUS_ICONS: Record<ServerStatus, string> = {
+  [ServerStatus.READY]: "🟢",
+  [ServerStatus.TIMEOUT]: "🟡",
+  [ServerStatus.UNREACHABLE]: "🔴",
+};

package/src/ui/editors/server/wizard.ts

@@ -0,0 +1,110 @@
+import type { LlamaServer } from "../../../interfaces/settings";
+import type { DialogFactory } from "../../dialog/factory";
+import type { InputDialog } from "../../dialog/input";
+import { FieldMessages, TITLES } from "../../strings";
+import { ServerFields, type ServerField } from "./fields";
+
+/** Wizard step spec: which registry field this step prompts for, plus an
+ * optional note override for the prompt. */
+interface WizardStepSpec {
+  def: ServerField;
+  note?: string;
+}
+
+/**
+ * State machine for the add-server wizard (URL → optional ID → optional name).
+ *
+ * The wizard state is just a growing `LlamaServer`: each step applies its
+ * committed value through the field definition's `apply` (backed by
+ * {@link LlamaServerBuilder}, so the unset-on-empty rule for `id`/`name`
+ * is shared with field edits).
+ *
+ * Usage:
+ * ```ts
+ * const wizard = new ServerWizard(dialogs);
+ * wizard.start(onComplete, onCancel);
+ * wizard.next(value);  // advances through the steps
+ * wizard.cancel();
+ * ```
+ */
+export class ServerWizard {
+  /**
+   * Ordered pipeline of wizard steps: URL (required, validated) → optional
+   * ID → optional name. Steps reference the shared `ServerFields` registry
+   * — the single source of truth for each field's label, placeholder,
+   * validator and apply logic — so the wizard can't drift from field edits
+   * on existing servers.
+   */
+  private static readonly STEPS: WizardStepSpec[] = [
+    { def: ServerFields.byId("url") },
+    { def: ServerFields.byId("id"), note: "(optional)" },
+    { def: ServerFields.byId("name"), note: "(optional)" },
+  ];
+
+  private server: LlamaServer = { url: "" };
+  private stepIndex = 0;
+  private dialog: InputDialog | null = null;
+  private onComplete: ((server: LlamaServer) => void) | null = null;
+  private onCancel: (() => void) | null = null;
+
+  constructor(
+    private readonly dialogs: DialogFactory,
+    /** Called each time a step dialog is created — the containing editor
+     * re-opens it via `openDialog` so input keeps flowing to the current
+     * step. */
+    private readonly onDialog: (dialog: InputDialog) => void,
+  ) {}
+
+  /** Start the wizard at the first step (URL). Focus is managed by the
+   * caller (the containing editor's `openDialog`). */
+  start(onComplete: (server: LlamaServer) => void, onCancel: () => void): void {
+    this.onComplete = onComplete;
+    this.onCancel = onCancel;
+    this.server = { url: "" };
+    this.stepIndex = 0;
+    this.showStep();
+  }
+
+  /**
+   * Commit the current step's value and advance. When the final step
+   * completes, hands the built server to the completion callback.
+   */
+  next(value: string): void {
+    const spec = ServerWizard.STEPS[this.stepIndex];
+    if (!spec) return;
+
+    this.server = spec.def.apply(this.server, value);
+    this.stepIndex += 1;
+
+    if (this.stepIndex >= ServerWizard.STEPS.length) {
+      this.dialog = null;
+      this.onComplete?.(this.server);
+      return;
+    }
+
+    this.showStep();
+    this.dialogs.requestRender();
+  }
+
+  /** Abort the wizard and call the cancel callback. */
+  cancel(): void {
+    this.dialog = null;
+    this.stepIndex = 0;
+    this.onCancel?.();
+  }
+
+  // -- internal helpers ------------------------------------------------------
+
+  private showStep(): void {
+    const spec = ServerWizard.STEPS[this.stepIndex];
+    this.dialog = this.dialogs.input({
+      title: TITLES.addServerStep((this.stepIndex + 1) as 1 | 2 | 3),
+      message: FieldMessages.of(spec.def.field, spec.note),
+      placeholder: spec.def.placeholder,
+      validate: spec.def.validate,
+      onSubmit: (v) => this.next(v),
+      onCancel: () => this.cancel(),
+    });
+    this.onDialog(this.dialog);
+  }
+}

package/src/ui/editors/settingField.ts

@@ -0,0 +1,37 @@
+import type { Field } from "../strings";
+
+/**
+ * Base class for one editable field of an entry (Template Method): the
+ * user-facing strings come from the shared `FIELDS` registry
+ * (`strings.ts`), and the `ItemBuilder` template fills the common
+ * `SettingItem` columns from this class while domain subclasses own the
+ * value/apply behavior.
+ *
+ * Both field registries (`ServerFields`, `OverrideFields`) extend this
+ * class, so the two editors share one field idiom instead of parallel
+ * interface/class shapes.
+ */
+export abstract class SettingField<TEntry> {
+  /** Unique id used as `SettingItem.id`. */
+  abstract readonly id: string;
+  /** User-facing strings from the shared FIELDS registry. */
+  abstract readonly field: Field;
+
+  /** Row label (from the shared FIELDS registry). */
+  get label(): string {
+    return this.field.label;
+  }
+
+  /** Row description in the containing `SettingsList`. */
+  get description(): string {
+    return this.field.description;
+  }
+
+  /** Example value shown dim as `e.g., <placeholder>` in input dialogs. */
+  get placeholder(): string | undefined {
+    return this.field.placeholder;
+  }
+
+  /** Current value shown in the entry's field row. */
+  abstract currentValue(entry: TEntry): string;
+}

package/src/ui/editors/settingsListFactory.ts

@@ -0,0 +1,33 @@
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import { SettingsList, type SettingItem } from "@earendil-works/pi-tui";
+
+/**
+ * Factory for creating `SettingsList` instances with the standard
+ * geometry formula and theme.
+ *
+ * All call sites use this factory instead of constructing `SettingsList`
+ * directly, so the height formula (`Math.min(n + 2, 15)`) and theme
+ * lookup live in a single place and can't drift apart.
+ */
+export class SettingsListFactory {
+  /**
+   * Creates a `SettingsList` with the standard geometry formula and theme.
+   *
+   * @param items — The list items to display.
+   * @param onEscape — Called when the user presses Esc to close the list.
+   * @param onSelect — Optional callback for field commits (defaults to a no-op).
+   */
+  static create(
+    items: SettingItem[],
+    onEscape: () => void,
+    onSelect?: (field: string, value: string) => void,
+  ): SettingsList {
+    return new SettingsList(
+      items,
+      Math.min(items.length + 2, 15),
+      getSettingsListTheme(),
+      onSelect ?? (() => {}),
+      onEscape,
+    );
+  }
+}