@pi-unipi/utility 0.1.1 → 0.2.3

package/src/tui/name-badge-state.ts

@@ -0,0 +1,299 @@
+/**
+ * @pi-unipi/utility — Name Badge State Manager
+ *
+ * Manages the name badge overlay lifecycle:
+ * - Toggle visibility (persisted via pi.appendEntry)
+ * - Poll for session name changes every 1s
+ * - Restore visibility on session start
+ * - Generate session name via background agent event
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { UNIPI_EVENTS, emitEvent } from "@pi-unipi/core";
+import { NameBadgeComponent } from "./name-badge.js";
+import { readBadgeSettings } from "./badge-settings.js";
+
+/** Overlay handle from ctx.ui.custom() */
+interface OverlayHandle {
+  requestRender?: () => void;
+  hide?: () => void;
+  setHidden?: (hidden: boolean) => void;
+  isHidden?: () => boolean;
+  focus?: () => void;
+  unfocus?: () => void;
+  isFocused?: () => boolean;
+}
+
+/** Persisted badge state */
+interface BadgePersistedState {
+  visible: boolean;
+}
+
+/** Entry type for persistence */
+const BADGE_ENTRY_TYPE = "name-badge";
+
+/** Polling interval in ms */
+const POLL_INTERVAL_MS = 1000;
+
+/** Name generation timeout in ms */
+const GEN_TIMEOUT_MS = 30_000;
+
+/**
+ * NameBadgeState — manages the name badge overlay.
+ *
+ * Usage:
+ *   const state = new NameBadgeState();
+ *   // In session_start: state.restore(pi, ctx);
+ *   // In session_shutdown: state.hide();
+ *   // Commands: state.toggle(pi, ctx), state.generate(pi, ctx);
+ */
+export class NameBadgeState {
+  private visible = false;
+  private currentName: string | null = null;
+  private overlayHandle: OverlayHandle | null = null;
+  private pollTimer: ReturnType<typeof setInterval> | null = null;
+  private component: NameBadgeComponent | null = null;
+  private genTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  /** Whether the badge is currently visible */
+  isVisible(): boolean {
+    return this.visible;
+  }
+
+  /**
+   * Toggle badge visibility.
+   * If hidden → show + start polling.
+   * If visible → hide + stop polling.
+   */
+  async toggle(
+    pi: ExtensionAPI,
+    ctx: { hasUI: boolean; ui: any; cwd?: string },
+  ): Promise<boolean> {
+    if (this.visible) {
+      this.hide();
+      this.persist(pi, false);
+      return false;
+    } else {
+      await this.show(pi, ctx);
+      this.persist(pi, true);
+      return true;
+    }
+  }
+
+  /**
+   * Show the badge overlay and start polling.
+   */
+  async show(
+    pi: ExtensionAPI,
+    ctx: { hasUI: boolean; ui: any; cwd?: string },
+  ): Promise<void> {
+    if (this.overlayHandle) return; // Already showing
+
+    const name = this.safeGetName(pi);
+    this.currentName = name;
+    this.visible = true;
+
+    // Store tui reference for requestRender wiring
+    let tuiRef: any = null;
+
+    ctx.ui.custom(
+      (tui: any, theme: any, _keybindings: any, _done: any) => {
+        tuiRef = tui;
+        const component = new NameBadgeComponent(name);
+        component.setTheme(theme);
+        this.component = component;
+
+        return {
+          render: (w: number) => component.render(w),
+          invalidate: () => component.invalidate(),
+          // No handleInput — display-only overlay
+        };
+      },
+      {
+        overlay: true,
+        overlayOptions: {
+          anchor: "top-center",
+          width: "100%",
+          nonCapturing: true,
+          visible: (termWidth: number) => termWidth >= 20,
+        },
+        onHandle: (handle: OverlayHandle) => {
+          this.overlayHandle = handle;
+          // Wire requestRender now that handle exists
+          if (tuiRef) {
+            (this.overlayHandle as any).requestRender = () => tuiRef.requestRender();
+          }
+        },
+      },
+    );
+
+    this.startPolling(pi);
+  }
+
+  /**
+   * Hide the badge overlay and stop polling.
+   */
+  hide(): void {
+    this.stopPolling();
+    this.clearGenTimeout();
+
+    if (this.overlayHandle) {
+      try {
+        // Use hide() to permanently remove the overlay
+        if (typeof this.overlayHandle.hide === "function") {
+          this.overlayHandle.hide();
+        } else if (typeof this.overlayHandle.setHidden === "function") {
+          this.overlayHandle.setHidden(true);
+        }
+      } catch {
+        // Handle may already be invalid
+      }
+      this.overlayHandle = null;
+    }
+
+    this.component = null;
+    this.visible = false;
+    this.currentName = null;
+  }
+
+  /**
+   * Restore badge visibility from persisted state.
+   * Call on session_start.
+   */
+  async restore(
+    pi: ExtensionAPI,
+    ctx: { hasUI: boolean; ui: any; cwd?: string },
+  ): Promise<void> {
+    try {
+      const entries = (ctx as any).sessionManager?.getEntries?.() ?? [];
+      const badgeEntry = entries.findLast(
+        (e: any) => e.type === "custom" && e.customType === BADGE_ENTRY_TYPE,
+      );
+
+      if (badgeEntry?.data?.visible) {
+        await this.show(pi, ctx);
+      }
+    } catch {
+      // If we can't read entries, just don't restore
+    }
+  }
+
+  /**
+   * Generate a session name via background agent.
+   * Emits BADGE_GENERATE_REQUEST event for subagents to handle.
+   * Also enables the badge overlay if not visible.
+   */
+  async generate(
+    pi: ExtensionAPI,
+    ctx: { hasUI: boolean; ui: any; cwd?: string },
+    conversationSummary?: string,
+  ): Promise<void> {
+    // Enable badge if not visible
+    if (!this.visible) {
+      await this.show(pi, ctx);
+      this.persist(pi, true);
+    }
+
+    // Clear any previous generation timeout
+    this.clearGenTimeout();
+
+    // Emit event for subagents to spawn background agent
+    emitEvent(pi, UNIPI_EVENTS.BADGE_GENERATE_REQUEST, {
+      source: "command",
+      conversationSummary,
+    });
+
+    // Set timeout — if name not set within 30s, give up
+    this.genTimeout = setTimeout(() => {
+      this.genTimeout = null;
+      // If name is still null after timeout, the agent didn't respond
+      if (this.currentName === null) {
+        // Badge stays with placeholder — no error needed
+      }
+    }, GEN_TIMEOUT_MS);
+  }
+
+  /**
+   * Directly set the session name via pi API.
+   * Used by the set_session_name tool.
+   */
+  setSessionName(pi: ExtensionAPI, name: string): void {
+    try {
+      pi.setSessionName(name);
+      // Update component immediately (don't wait for poll)
+      this.currentName = name;
+      this.component?.setName(name);
+      this.overlayHandle?.requestRender?.();
+      // Clear generation timeout if active
+      this.clearGenTimeout();
+    } catch {
+      // Best effort
+    }
+  }
+
+  // ─── Private ────────────────────────────────────────────────────────
+
+  /**
+   * Start polling for name changes.
+   */
+  private startPolling(pi: ExtensionAPI): void {
+    if (this.pollTimer) return;
+
+    this.pollTimer = setInterval(() => {
+      const name = this.safeGetName(pi);
+
+      // Check if generation timeout should be cleared
+      if (name !== null && this.genTimeout) {
+        this.clearGenTimeout();
+      }
+
+      if (name !== this.currentName) {
+        this.currentName = name;
+        this.component?.setName(name);
+        this.overlayHandle?.requestRender?.();
+      }
+    }, POLL_INTERVAL_MS);
+  }
+
+  /**
+   * Stop polling.
+   */
+  private stopPolling(): void {
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+
+  /**
+   * Clear generation timeout.
+   */
+  private clearGenTimeout(): void {
+    if (this.genTimeout) {
+      clearTimeout(this.genTimeout);
+      this.genTimeout = null;
+    }
+  }
+
+  /**
+   * Safely get session name, returning null on error.
+   */
+  private safeGetName(pi: ExtensionAPI): string | null {
+    try {
+      return pi.getSessionName() ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Persist badge visibility state.
+   */
+  private persist(pi: ExtensionAPI, visible: boolean): void {
+    try {
+      pi.appendEntry(BADGE_ENTRY_TYPE, { visible } satisfies BadgePersistedState);
+    } catch {
+      // Persistence is best-effort
+    }
+  }
+}

package/src/tui/name-badge.ts

@@ -0,0 +1,117 @@
+/**
+ * @pi-unipi/utility — Name Badge Component
+ *
+ * Pure render component for the session name badge overlay.
+ * Displays a bordered box with opaque background and session name.
+ * Display-only — no input handling, no focus.
+ */
+
+import type { Component } from "@mariozechner/pi-tui";
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import type { Theme } from "@mariozechner/pi-coding-agent";
+
+/** Placeholder text when no session name is set */
+const PLACEHOLDER = "Set a name";
+
+/**
+ * Pad content to exact visible width.
+ */
+function padVisible(content: string, targetWidth: number): string {
+  const vw = visibleWidth(content);
+  const pad = Math.max(0, targetWidth - vw);
+  return content + " ".repeat(pad);
+}
+
+/**
+ * NameBadgeComponent — bordered box HUD overlay showing session name.
+ *
+ * Renders a proper box with opaque background:
+ * ╭──────────╮
+ * │   Best   │
+ * ╰──────────╯
+ */
+export class NameBadgeComponent implements Component {
+  private name: string | null;
+  private theme: Theme | null = null;
+  private cachedLines: string[] | null = null;
+  private cachedWidth = -1;
+
+  constructor(name: string | null) {
+    this.name = name;
+  }
+
+  /** Update the displayed name */
+  setName(name: string | null): void {
+    if (name !== this.name) {
+      this.name = name;
+      this.invalidate();
+    }
+  }
+
+  /** Store theme reference for reactive color updates */
+  setTheme(theme: Theme): void {
+    this.theme = theme;
+    this.invalidate();
+  }
+
+  /** Clear cached render lines */
+  invalidate(): void {
+    this.cachedLines = null;
+    this.cachedWidth = -1;
+  }
+
+  render(width: number): string[] {
+    // Return cached if width unchanged
+    if (this.cachedLines && this.cachedWidth === width) {
+      return this.cachedLines;
+    }
+
+    const lines = this.renderBadge(width);
+    this.cachedLines = lines;
+    this.cachedWidth = width;
+    return this.cachedLines;
+  }
+
+  private renderBadge(width: number): string[] {
+    // Determine display text and color
+    let displayText: string;
+    let fgColor: string;
+    if (this.name) {
+      displayText = this.name;
+      fgColor = "accent";
+    } else {
+      displayText = PLACEHOLDER;
+      fgColor = "muted";
+    }
+
+    // Full-width box: borders take 2 cols
+    const innerWidth = Math.max(1, width - 2);
+    const maxTextWidth = Math.max(1, innerWidth - 4); // 2-cell pad each side
+
+    // Truncate name if needed
+    if (visibleWidth(displayText) > maxTextWidth) {
+      displayText = truncateToWidth(displayText, maxTextWidth - 1, "…");
+    }
+
+    // Center text within inner width
+    const textVw = visibleWidth(displayText);
+    const leftPad = Math.floor((innerWidth - textVw) / 2);
+    const rightPad = innerWidth - textVw - leftPad;
+
+    const border = (s: string) => this.theme ? this.theme.fg("accent" as any, s) : s;
+    const bgFn = (s: string) => this.theme ? this.theme.bg("customMessageBg" as any, s) : s;
+
+    const nameStyled = this.theme
+      ? this.theme.fg(fgColor as any, displayText)
+      : displayText;
+
+    // Build lines with opaque background spanning full width
+    const topLine = bgFn(border("╭" + "─".repeat(innerWidth) + "╮"));
+    const contentLine = bgFn(
+      border("│") + " ".repeat(leftPad) + nameStyled + " ".repeat(rightPad) + border("│"),
+    );
+    const bottomLine = bgFn(border("╰" + "─".repeat(innerWidth) + "╯"));
+
+    return [topLine, contentLine, bottomLine];
+  }
+}

package/src/tui/settings-inspector.ts

@@ -0,0 +1,303 @@
+/**
+ * @pi-unipi/utility — Settings Inspector
+ *
+ * Reusable settings inspector overlay pattern.
+ * Split-pane layout: list left, editor right.
+ * Search/filter, keyboard navigation, JSON editing.
+ *
+ * Note: This is a data model and rendering helper. The actual TUI
+ * rendering depends on the host environment (pi's TUI API).
+ */
+
+import type {
+  SettingSchema,
+  SettingsInspectorState,
+} from "../types.js";
+
+/** Navigation actions */
+export type InspectorAction =
+  | { type: "navigate"; direction: "up" | "down" | "first" | "last" }
+  | { type: "search"; query: string }
+  | { type: "select"; index: number }
+  | { type: "edit"; value: unknown }
+  | { type: "toggle_edit" }
+  | { type: "save" }
+  | { type: "cancel" };
+
+/** Result of applying an action */
+export interface InspectorUpdate {
+  state: SettingsInspectorState;
+  changed: boolean;
+  saved: boolean;
+}
+
+/** Create initial inspector state */
+export function createSettingsInspector(
+  schemas: SettingSchema[],
+  initialValues?: Record<string, unknown>,
+): SettingsInspectorState {
+  const values: Record<string, unknown> = {};
+  for (const schema of schemas) {
+    values[schema.key] = initialValues?.[schema.key] ?? schema.default;
+  }
+
+  return {
+    schemas,
+    values,
+    selectedIndex: 0,
+    searchQuery: "",
+    editMode: false,
+  };
+}
+
+/** Get filtered schemas based on search query */
+export function getFilteredSchemas(
+  state: SettingsInspectorState,
+): SettingSchema[] {
+  if (!state.searchQuery.trim()) {
+    return state.schemas;
+  }
+
+  const query = state.searchQuery.toLowerCase();
+  return state.schemas.filter(
+    (s) =>
+      s.key.toLowerCase().includes(query) ||
+      s.description.toLowerCase().includes(query),
+  );
+}
+
+/** Get the currently selected schema */
+export function getSelectedSchema(
+  state: SettingsInspectorState,
+): SettingSchema | undefined {
+  const filtered = getFilteredSchemas(state);
+  return filtered[state.selectedIndex];
+}
+
+/** Get current value for a key */
+export function getValue(
+  state: SettingsInspectorState,
+  key: string,
+): unknown {
+  return state.values[key];
+}
+
+/** Apply an action to the inspector state */
+export function applyAction(
+  state: SettingsInspectorState,
+  action: InspectorAction,
+): InspectorUpdate {
+  const newState: SettingsInspectorState = {
+    ...state,
+    values: { ...state.values },
+  };
+  let changed = false;
+  let saved = false;
+
+  const filtered = getFilteredSchemas(newState);
+
+  switch (action.type) {
+    case "navigate": {
+      const maxIndex = Math.max(0, filtered.length - 1);
+      switch (action.direction) {
+        case "up":
+          newState.selectedIndex = Math.max(0, newState.selectedIndex - 1);
+          break;
+        case "down":
+          newState.selectedIndex = Math.min(maxIndex, newState.selectedIndex + 1);
+          break;
+        case "first":
+          newState.selectedIndex = 0;
+          break;
+        case "last":
+          newState.selectedIndex = maxIndex;
+          break;
+      }
+      changed = newState.selectedIndex !== state.selectedIndex;
+      break;
+    }
+
+    case "search": {
+      newState.searchQuery = action.query;
+      newState.selectedIndex = 0;
+      changed = true;
+      break;
+    }
+
+    case "select": {
+      const maxIndex = Math.max(0, filtered.length - 1);
+      newState.selectedIndex = Math.max(0, Math.min(maxIndex, action.index));
+      changed = newState.selectedIndex !== state.selectedIndex;
+      break;
+    }
+
+    case "edit": {
+      const selected = getSelectedSchema(newState);
+      if (selected) {
+        newState.values[selected.key] = action.value;
+        changed = true;
+      }
+      break;
+    }
+
+    case "toggle_edit": {
+      newState.editMode = !newState.editMode;
+      changed = true;
+      break;
+    }
+
+    case "save": {
+      saved = true;
+      changed = true;
+      break;
+    }
+
+    case "cancel": {
+      newState.editMode = false;
+      changed = true;
+      break;
+    }
+  }
+
+  return { state: newState, changed, saved };
+}
+
+/** Validate a value against its schema */
+export function validateValue(
+  schema: SettingSchema,
+  value: unknown,
+): string | undefined {
+  if (value === undefined || value === null) {
+    if (schema.required) {
+      return `Required field: ${schema.key}`;
+    }
+    return undefined;
+  }
+
+  switch (schema.type) {
+    case "string":
+      if (typeof value !== "string") {
+        return `Expected string for ${schema.key}`;
+      }
+      break;
+    case "number":
+      if (typeof value !== "number" || Number.isNaN(value)) {
+        return `Expected number for ${schema.key}`;
+      }
+      break;
+    case "boolean":
+      if (typeof value !== "boolean") {
+        return `Expected boolean for ${schema.key}`;
+      }
+      break;
+    case "object":
+      if (typeof value !== "object" || Array.isArray(value)) {
+        return `Expected object for ${schema.key}`;
+      }
+      break;
+    case "array":
+      if (!Array.isArray(value)) {
+        return `Expected array for ${schema.key}`;
+      }
+      break;
+  }
+
+  return undefined;
+}
+
+/** Validate all values against schemas */
+export function validateAll(
+  state: SettingsInspectorState,
+): Record<string, string> {
+  const errors: Record<string, string> = {};
+  for (const schema of state.schemas) {
+    const error = validateValue(schema, state.values[schema.key]);
+    if (error) {
+      errors[schema.key] = error;
+    }
+  }
+  return errors;
+}
+
+/** Export state values as JSON */
+export function exportToJSON(state: SettingsInspectorState): string {
+  return JSON.stringify(state.values, null, 2);
+}
+
+/** Import values from JSON string */
+export function importFromJSON(
+  state: SettingsInspectorState,
+  json: string,
+): { state: SettingsInspectorState; errors: Record<string, string> } {
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(json);
+  } catch (err) {
+    return {
+      state,
+      errors: { _parse: `Invalid JSON: ${(err as Error).message}` },
+    };
+  }
+
+  const newState: SettingsInspectorState = {
+    ...state,
+    values: { ...state.values },
+  };
+
+  const errors: Record<string, string> = {};
+  for (const schema of state.schemas) {
+    if (parsed[schema.key] !== undefined) {
+      const error = validateValue(schema, parsed[schema.key]);
+      if (error) {
+        errors[schema.key] = error;
+      } else {
+        newState.values[schema.key] = parsed[schema.key];
+      }
+    }
+  }
+
+  return { state: newState, errors };
+}
+
+/** Format a setting for display */
+export function formatSetting(
+  schema: SettingSchema,
+  value: unknown,
+): string {
+  const displayValue = value === undefined ? "(unset)" : JSON.stringify(value);
+  const requiredMark = schema.required ? "*" : "";
+  return `${schema.key}${requiredMark}: ${displayValue}\n  ${schema.description}`;
+}
+
+/** Render the inspector as markdown (for non-TUI environments) */
+export function renderAsMarkdown(
+  state: SettingsInspectorState,
+): string {
+  const filtered = getFilteredSchemas(state);
+  const lines = [
+    "## ⚙️ Settings",
+    "",
+    state.searchQuery ? `*Filter: "${state.searchQuery}"*` : "",
+    "",
+  ];
+
+  for (let i = 0; i < filtered.length; i++) {
+    const schema = filtered[i];
+    const value = state.values[schema.key];
+    const selected = i === state.selectedIndex ? "> " : "  ";
+    const required = schema.required ? " **(required)**" : "";
+
+    lines.push(
+      `${selected}**${schema.key}**${required} \`${schema.type}\``,
+      `    ${schema.description}`,
+      `    Value: \`${JSON.stringify(value)}\``,
+      "",
+    );
+  }
+
+  if (filtered.length === 0) {
+    lines.push("*No settings match your search.*");
+  }
+
+  return lines.join("\n");
+}