pi-llama-cpp 0.13.0 → 0.15.0

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

@@ -0,0 +1,197 @@
+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 { ServerIds } from "../../../utils/serverIds";
+import { TITLES, authRequiredMessage } from "../../strings";
+import type { ServerSettingsListOptions } from "../editorOptions";
+import { ListEditor } from "../listEditor";
+import { SettingsListFactory } from "../settingsListFactory";
+import { ServerFields } from "./fields";
+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,
+          authResolver: async (server) => {
+            // Mirror Server.getApiKey(): use ServerIds.resolve to get
+            // the provider ID (customId or llama-server=<url>), then
+            // resolve the key from the credential store.
+            return settings.resolveApiKey(
+              ServerIds.resolve(server.url, server.id),
+            );
+          },
+          ui,
+        }),
+    );
+  }
+
+  // -- abstract hooks -------------------------------------------------------
+
+  protected async buildSettingsList(): Promise<SettingsList> {
+    const builder = new ServerItemBuilder(this.dialogs);
+    const serverTimeout = this.options.serverTimeout ?? SERVER_TIMEOUT;
+    // Run auth + health probes in parallel; ⛔ wins if auth fails,
+    // otherwise fall back to the health emoji.
+    const probes = await Promise.all(
+      this.options.servers.map(async (server) => {
+        const apiKey = (await this.options.authResolver?.(server)) ?? "";
+        const [authEmoji, healthEmoji] = await Promise.all([
+          ServerDisplay.authEmoji(server.url, apiKey, serverTimeout),
+          ServerDisplay.healthEmoji(server.url, serverTimeout),
+        ]);
+        return authEmoji || healthEmoji;
+      }),
+    );
+    const items: SettingItem[] = this.options.servers.map((server, i) =>
+      builder.buildRow(
+        server,
+        i,
+        (field, value) => this.handleFieldChange(field, value),
+        probes[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 server = this.options.servers[idx];
+    const updated = server
+      ? ServerFields.byId(field).apply(server, value)
+      : server;
+    const next = server
+      ? this.options.servers.map((s, i) => (i === idx ? updated : s))
+      : this.options.servers;
+
+    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 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);
+    });
+
+    // Warn the user if the newly added server requires an API key
+    await this.warnIfAuthRequired(server);
+  }
+
+  /**
+   * Probes the server to check if it requires an API key. If so, notifies
+   * the user so they know to configure one via `/login` or `auth.json`.
+   */
+  private async warnIfAuthRequired(server: LlamaServer): Promise<void> {
+    const ui = this.options.ui;
+    if (!ui) return;
+
+    const serverTimeout = this.options.serverTimeout ?? SERVER_TIMEOUT;
+    const apiKey = (await this.options.authResolver?.(server)) ?? "";
+
+    if (await ServerDisplay.requiresApiKey(server.url, apiKey, serverTimeout)) {
+      const providerId = ServerIds.resolve(server.url, server.id);
+      ui.notify(authRequiredMessage(server.url, providerId), "warning");
+    }
+  }
+}

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

@@ -0,0 +1,95 @@
+import { ENDPOINT_PREFIX } from "../../../constants";
+import { ServerStatus } from "../../../enums/serverStatus";
+import type { LlamaServer } from "../../../interfaces/settings";
+import { checkServerHealth } from "../../../utils/health";
+import { ServerIds } from "../../../utils/serverIds";
+
+/** Emoji shown when a server requires an API key (401 on /v1/models). */
+const UNAUTHORIZED_EMOJI = "⛔";
+
+/**
+ * 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)];
+  }
+
+  /**
+   * Checks if the server requires an API key by probing `/v1/models`.
+   *
+   * @param url - The server URL to check
+   * @param apiKey - The API key to send (may be a placeholder)
+   * @param timeout - Maximum time (ms) to wait for the request
+   * @returns `true` if the server responded with 401, `false` otherwise
+   */
+  static async requiresApiKey(
+    url: string,
+    apiKey: string,
+    timeout: number,
+  ): Promise<boolean> {
+    try {
+      const response = await fetch(`${url}${ENDPOINT_PREFIX}/models`, {
+        signal: AbortSignal.timeout(timeout),
+        headers: { Authorization: `Bearer ${apiKey}` },
+      });
+      return response.status === 401;
+    } catch {
+      // Timeout or network error — the server is unreachable, so no auth
+      // indicator is needed (the health emoji will cover that).
+      return false;
+    }
+  }
+
+  /**
+   * Probes the server's `/v1/models` endpoint to check if authentication
+   * is required. Returns ⛔ when the server responds with 401, empty string
+   * otherwise.
+   *
+   * @param url - The server URL to check
+   * @param apiKey - The API key to send (may be a placeholder)
+   * @param timeout - Maximum time (ms) to wait for the request
+   * @returns The emoji indicator (⛔ if 401, "" otherwise)
+   */
+  static async authEmoji(
+    url: string,
+    apiKey: string,
+    timeout: number,
+  ): Promise<string> {
+    return (await this.requiresApiKey(url, apiKey, timeout))
+      ? UNAUTHORIZED_EMOJI
+      : "";
+  }
+}
+
+/**
+ * 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,
+    );
+  }
+}