@mrclrchtr/supi-prompt-suggestions 1.16.1

package/node_modules/@mrclrchtr/supi-core/src/settings/settings-ui.ts

@@ -0,0 +1,331 @@
+// Generic settings overlay for SuPi extensions.
+//
+// Uses pi-tui's SettingsList with scope toggle (Tab), extension grouping,
+// and search. Each extension declares its settings via registerSettings().
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  Input,
+  Key,
+  matchesKey,
+  type SelectItem,
+  SelectList,
+  type SelectListTheme,
+  type SettingItem,
+  SettingsList,
+  Text,
+} from "@earendil-works/pi-tui";
+import { getSelectableModels } from "../model-selection.ts";
+import {
+  getRegisteredSettings,
+  type SettingsScope,
+  type SettingsSection,
+} from "./settings-registry.ts";
+
+// ── Input submenu component ──────────────────────────────────
+
+/**
+ * Creates a pi-tui Input-backed submenu component with enter-to-confirm
+ * and escape-to-cancel handling.
+ *
+ * @param currentValue - Initial value for the text input.
+ * @param label - Label text displayed above the input.
+ * @param done - Callback invoked with the confirmed value, or undefined on cancel.
+ */
+export function createInputSubmenu(
+  currentValue: string,
+  label: string,
+  done: (selectedValue?: string) => void,
+): {
+  render: (width: number) => string[];
+  invalidate: () => void;
+  handleInput: (data: string) => boolean;
+} {
+  const input = new Input();
+  input.setValue(currentValue);
+
+  return {
+    render: (_width: number) => {
+      const lines = [`  ${label}`];
+      lines.push(...input.render(_width));
+      lines.push("  enter confirm • esc cancel");
+      return lines;
+    },
+    invalidate: () => {
+      input.invalidate();
+    },
+    handleInput: (data: string) => {
+      if (matchesKey(data, Key.escape)) {
+        done();
+        return true;
+      }
+      if (matchesKey(data, Key.enter)) {
+        done(input.getValue());
+        return true;
+      }
+      input.handleInput(data);
+      return true;
+    },
+  };
+}
+
+// ── Types ────────────────────────────────────────────────────
+
+interface OverlayState {
+  scope: SettingsScope;
+  cwd: string;
+}
+
+// ── Pure helpers ─────────────────────────────────────────────
+
+function getScopeLabel(scope: SettingsScope): string {
+  return scope === "project" ? "Project" : "Global";
+}
+
+function buildFlatItems(
+  sections: SettingsSection[],
+  scope: SettingsScope,
+  cwd: string,
+  ctx?: ExtensionContext,
+): SettingItem[] {
+  const items: SettingItem[] = [];
+  for (const section of sections) {
+    const sectionItems = section.loadValues(scope, cwd, ctx);
+    for (const item of sectionItems) {
+      items.push({
+        ...item,
+        id: `${section.id}.${item.id}`,
+        label: `${section.label}: ${item.label}`,
+      });
+    }
+  }
+  return items;
+}
+
+function findSectionAndId(
+  sections: SettingsSection[],
+  flatId: string,
+): { section: SettingsSection; itemId: string } | null {
+  const dotIndex = flatId.indexOf(".");
+  if (dotIndex === -1) return null;
+  const sectionId = flatId.slice(0, dotIndex);
+  const itemId = flatId.slice(dotIndex + 1);
+  const section = sections.find((s) => s.id === sectionId);
+  if (!section) return null;
+  return { section, itemId };
+}
+
+// ── Component ────────────────────────────────────────────────
+
+interface SettingsOverlayDeps {
+  ctx: ExtensionContext;
+  state: OverlayState;
+  container: Container;
+  settingsList: SettingsList | null;
+  tui: Parameters<Parameters<ExtensionContext["ui"]["custom"]>[0]>[0];
+  theme: Parameters<Parameters<ExtensionContext["ui"]["custom"]>[0]>[1];
+  done: () => void;
+}
+
+function createSettingsList(deps: SettingsOverlayDeps): SettingsList {
+  const sections = getRegisteredSettings();
+  const items = buildFlatItems(sections, deps.state.scope, deps.state.cwd, deps.ctx);
+  const onChange = (flatId: string, newValue: string) => {
+    const found = findSectionAndId(sections, flatId);
+    if (found) {
+      found.section.persistChange(
+        deps.state.scope,
+        deps.state.cwd,
+        found.itemId,
+        newValue,
+        deps.ctx,
+      );
+    }
+    // Re-read all values to reflect persisted changes, but keep the list
+    // instance (and its selectedIndex) intact.
+    const updatedItems = buildFlatItems(sections, deps.state.scope, deps.state.cwd, deps.ctx);
+    for (const updated of updatedItems) {
+      const existing = items.find((i) => i.id === updated.id);
+      if (existing && existing.currentValue !== updated.currentValue) {
+        settingsList.updateValue(updated.id, updated.currentValue);
+      }
+    }
+    deps.tui.requestRender();
+  };
+  const settingsList = new SettingsList(
+    items,
+    Math.min(items.length + 4, 20),
+    getSettingsListTheme(),
+    onChange,
+    () => deps.done(),
+    { enableSearch: true },
+  );
+  return settingsList;
+}
+
+function rebuildSettingsList(deps: SettingsOverlayDeps): SettingsList {
+  const settingsList = createSettingsList(deps);
+  deps.settingsList = settingsList;
+
+  deps.container.clear();
+  deps.container.addChild(createHeaderComponent(deps));
+  deps.container.addChild(settingsList);
+
+  return settingsList;
+}
+
+function createHeaderComponent(deps: SettingsOverlayDeps): Text {
+  const { theme, state } = deps;
+  const scopeLabel = getScopeLabel(state.scope);
+  const otherScope = state.scope === "project" ? "Global" : "Project";
+  const headerText = new Text(
+    `${theme.fg("accent", theme.bold("SuPi Settings"))}  ${theme.fg("text", `Scope: ${scopeLabel}`)} ${theme.fg("dim", `(tab → ${otherScope})`)}`,
+    0,
+    0,
+  );
+  return headerText;
+}
+
+function handleScopeToggle(deps: SettingsOverlayDeps): void {
+  deps.state.scope = deps.state.scope === "project" ? "global" : "project";
+  rebuildSettingsList(deps);
+  deps.tui.requestRender();
+}
+
+/** Minimal SelectList theme — uses identity so the parent SettingsList provides styling context. */
+const PASSTHROUGH_THEME: SelectListTheme = {
+  selectedPrefix: (text) => `› ${text}`,
+  selectedText: (text) => text,
+  description: (text) => text,
+  scrollInfo: (text) => text,
+  noMatch: (text) => text,
+};
+
+/**
+ * Create a model picker submenu for settings.
+ *
+ * Shows a scrollable list of selectable models from the scoped model set,
+ * with the current session model annotated `[current]`.  The first entry is
+ * always `"disabled"`.
+ *
+ * @param currentValue - Currently configured canonical model id or `"disabled"`.
+ * @param done - Callback invoked with the selected value, or undefined on cancel.
+ * @param ctx - Extension context for model listing.  When undefined, only
+ *   `"disabled"` is offered.
+ */
+export function createModelPickerSubmenu(
+  currentValue: string,
+  done: (selectedValue?: string) => void,
+  ctx?: ExtensionContext,
+): {
+  render: (width: number) => string[];
+  invalidate: () => void;
+  handleInput: (data: string) => boolean;
+} {
+  const items = buildModelItems(ctx);
+
+  const initialIndex =
+    currentValue === "disabled"
+      ? 0
+      : Math.max(
+          0,
+          items.findIndex((item) => item.value === currentValue),
+        );
+
+  const container = new Container();
+  container.addChild(new Text("  Select suggestion model", 1, 0));
+  container.addChild(new Text("", 1, 0));
+
+  const selectList = new SelectList(items, Math.min(items.length, 15), PASSTHROUGH_THEME);
+
+  if (initialIndex >= 0) {
+    selectList.setSelectedIndex(initialIndex);
+  }
+
+  selectList.onSelect = (item) => done(item.value);
+  selectList.onCancel = () => done();
+
+  container.addChild(selectList);
+  container.addChild(new Text("  ↑↓ navigate • enter select • esc cancel", 1, 0));
+
+  return {
+    render: (width: number) => container.render(width),
+    invalidate: () => container.invalidate(),
+    handleInput: (data: string) => {
+      selectList.handleInput(data);
+      return true;
+    },
+  };
+}
+
+/** Build selectable model items with "disabled" first. */
+function buildModelItems(ctx?: ExtensionContext): SelectItem[] {
+  const items: SelectItem[] = [
+    {
+      value: "disabled",
+      label: "disabled",
+      description: "No prompt suggestions",
+    },
+  ];
+
+  if (!ctx) return items;
+
+  const models = getSelectableModels(ctx);
+
+  for (const model of models) {
+    const suffix = model.isCurrent ? "  [current]" : "";
+    items.push({
+      value: model.canonicalId,
+      label: `${model.canonicalId}${suffix}`,
+      description: model.label !== model.canonicalId ? model.label : undefined,
+    });
+  }
+
+  return items;
+}
+
+// ── Entry point ──────────────────────────────────────────────
+
+export function openSettingsOverlay(ctx: ExtensionContext): void {
+  const sections = getRegisteredSettings();
+  if (sections.length === 0) {
+    ctx.ui.notify("No settings registered by SuPi extensions", "info");
+    return;
+  }
+
+  void ctx.ui.custom<void>((tui, theme, _kb, done) => {
+    const state: OverlayState = { scope: "project", cwd: ctx.cwd };
+    const container = new Container();
+
+    const deps: SettingsOverlayDeps = {
+      ctx,
+      state,
+      container,
+      settingsList: null,
+      tui,
+      theme,
+      done,
+    };
+
+    rebuildSettingsList(deps);
+
+    const component = {
+      render: (width: number) => container.render(width),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        if (matchesKey(data, Key.tab)) {
+          handleScopeToggle(deps);
+          return true;
+        }
+        // Delegate input to the settings list (always set after rebuildSettingsList)
+        deps.settingsList?.handleInput?.(data);
+        deps.tui.requestRender();
+        return true;
+      },
+    };
+
+    return component;
+  });
+}

package/node_modules/@mrclrchtr/supi-core/src/settings-ui.ts

@@ -0,0 +1,6 @@
+// supi-core settings-ui domain — settings TUI components (imports pi-tui at runtime, heavy).
+export {
+  createInputSubmenu,
+  createModelPickerSubmenu,
+  openSettingsOverlay,
+} from "./settings/settings-ui.ts";

package/node_modules/@mrclrchtr/supi-core/src/settings.ts

@@ -0,0 +1,9 @@
+// supi-core settings domain — settings registry (lightweight, type-only pi-tui import).
+
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
+export {
+  clearRegisteredSettings,
+  getRegisteredSettings,
+  registerSettings,
+} from "./settings/settings-registry.ts";

package/node_modules/@mrclrchtr/supi-core/src/spinner-frames.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared UI constants for SuPi extensions.
+ *
+ * @module
+ */
+
+/** Braille spinner frames used across SuPi extensions for animated loaders. */
+export const BRAILLE_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/** Tick interval (ms) shared by all braille-spinner consumers. */
+export const SPINNER_INTERVAL_MS = 80;

package/node_modules/@mrclrchtr/supi-core/src/status-spinner.ts

@@ -0,0 +1,68 @@
+/**
+ * Lightweight status-bar spinner for SuPi extensions.
+ *
+ * Manages a setInterval-based animated spinner that writes to
+ * `ctx.ui.setStatus`.  Each tick advances the frame and re-renders
+ * with the current message.
+ *
+ * @module
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { BRAILLE_SPINNER_FRAMES, SPINNER_INTERVAL_MS } from "./spinner-frames.ts";
+
+/**
+ * Manages an animated braille spinner on the status bar.
+ *
+ * Usage:
+ * ```ts
+ * const spinner = new StatusSpinner(ctx, "my-package");
+ * spinner.start("generating…");
+ * // later
+ * spinner.stop();
+ * ```
+ */
+export class StatusSpinner {
+  private interval: ReturnType<typeof setInterval> | null = null;
+  private frame = 0;
+  private currentMessage = "";
+
+  constructor(
+    private ctx: ExtensionContext,
+    private source: string,
+    private frames: readonly string[] = BRAILLE_SPINNER_FRAMES,
+  ) {}
+
+  /** Start the spinner with the given message. Overwrites any active spinner. */
+  start(message: string): void {
+    this.stop();
+    this.currentMessage = message;
+    this.render();
+
+    this.interval = setInterval(() => {
+      this.frame++;
+      this.render();
+    }, SPINNER_INTERVAL_MS);
+  }
+
+  /** Update the display message without resetting the spinner. */
+  update(message: string): void {
+    this.currentMessage = message;
+  }
+
+  /** Stop the spinner and clear the status. */
+  stop(): void {
+    if (this.interval !== null) {
+      clearInterval(this.interval);
+      this.interval = null;
+    }
+    this.ctx.ui.setStatus(this.source, "");
+  }
+
+  // ── Private ──────────────────────────────────────────────────────────
+
+  private render(): void {
+    const icon = this.frames[this.frame % this.frames.length];
+    this.ctx.ui.setStatus(this.source, `${icon} ${this.currentMessage}`);
+  }
+}

package/node_modules/@mrclrchtr/supi-core/src/substrate-types.ts

@@ -0,0 +1,11 @@
+/** 0-based position used by LSP and code-intelligence internally. */
+export interface CodePosition {
+  line: number;
+  character: number;
+}
+
+/** Normalized location — flat replacement for LSP's nested Location/range shape. */
+export interface CodeLocation {
+  uri: string;
+  range: { start: CodePosition; end: CodePosition };
+}

package/node_modules/@mrclrchtr/supi-core/src/terminal.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared terminal title formatting and signaling utilities.
+ *
+ * Centralized place for pi title convention (π prefix), completion (✓)
+ * and waiting (●) indicators, and the audible terminal bell.
+ */
+import path from "node:path";
+
+/** Unicode checkmark shown when the agent finishes a turn. */
+export const DONE_SYMBOL = "\u2713";
+/** Unicode dot shown when waiting for user input. */
+export const WAITING_SYMBOL = "\u25CF";
+
+/** Minimal UI surface needed for title operations. */
+export interface TitleTarget {
+  ui: {
+    setTitle?(title: string): void;
+  };
+}
+
+/**
+ * Format pi's canonical terminal title from session name and cwd.
+ * Falls back gracefully when either is missing.
+ *
+ * @example
+ *   formatTitle("my-session", "/home/projects/foo")  // "π - my-session - foo"
+ *   formatTitle(undefined, "/home/projects/foo")      // "π - foo"
+ *   formatTitle("my-session")                         // "π - my-session"
+ *   formatTitle()                                     // "π"
+ */
+export function formatTitle(sessionName?: string, cwd?: string): string {
+  const base = cwd ? path.basename(cwd) : undefined;
+  if (sessionName && base) return `π - ${sessionName} - ${base}`;
+  if (sessionName) return `π - ${sessionName}`;
+  if (base) return `π - ${base}`;
+  return "π";
+}
+
+/** Sound the audible terminal bell (ASCII BEL). */
+export function signalBell(): void {
+  process.stdout.write("\x07");
+}
+
+/**
+ * Set the terminal title to indicate the agent is waiting for user input.
+ * Prefixes with ● and sounds the terminal bell.
+ */
+export function signalWaiting(ctx: TitleTarget, title: string): void {
+  ctx.ui.setTitle?.(`${WAITING_SYMBOL}  ${title}`);
+  signalBell();
+}
+
+/**
+ * Set the terminal title to indicate the agent turn has completed.
+ * Prefixes with ✓ and sounds the terminal bell.
+ */
+export function signalDone(ctx: TitleTarget, title: string): void {
+  ctx.ui.setTitle?.(`${DONE_SYMBOL} ${title}`);
+  signalBell();
+}

package/node_modules/@mrclrchtr/supi-core/src/tool-framework.ts

@@ -0,0 +1,182 @@
+// Shared tool framework for SuPi extensions.
+//
+// Provides a standard ToolSpec→PromptSurface→registerTool pipeline so
+// individual packages do not duplicate spec interfaces, guidance derivation,
+// registration loops, or common TypeBox parameter schemas.
+
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { type TSchema, Type } from "typebox";
+import { ProgressWidget, type WidgetProgress } from "./progress-widget.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Minimum contract for a SuPi tool definition. */
+export interface SuiPiToolSpec {
+  name: string;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+  parameters: TSchema;
+}
+
+/** Derived prompt surface — what pi flattens into the system prompt. */
+export interface SuiPiToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Guidance derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Static derivation: copies spec fields into a prompt surface.
+ *
+ * Packages that need dynamic guidance (e.g. server-coverage injection) should
+ * build their own surfaces, optionally starting from the output of this helper.
+ */
+export function derivePromptSurface(spec: SuiPiToolSpec): SuiPiToolPromptSurface {
+  return {
+    description: spec.description,
+    promptSnippet: spec.promptSnippet,
+    promptGuidelines: [...spec.promptGuidelines],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+// biome-ignore lint/complexity/useMaxParams: matches pi ToolDefinition.execute signature
+export type ToolExecuteFn = (
+  toolCallId: string,
+  params: unknown,
+  signal: AbortSignal | undefined,
+  onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
+  ctx: ExtensionContext,
+) => Promise<AgentToolResult<Record<string, unknown>>>;
+
+/**
+ * Register a set of tools from specs + pre-derived surfaces.
+ *
+ * `createExecute` receives the spec and returns a pi-compatible execute
+ * function.  This keeps execute-logic package-local while the framework owns
+ * the declarative surface and registration boilerplate.
+ */
+export function registerSuiPiTools(
+  pi: ExtensionAPI,
+  specs: readonly SuiPiToolSpec[],
+  surfaces: Record<string, SuiPiToolPromptSurface>,
+  createExecute: (spec: SuiPiToolSpec) => ToolExecuteFn,
+): void {
+  for (const spec of specs) {
+    const surface = surfaces[spec.name];
+    pi.registerTool({
+      name: spec.name,
+      label: spec.label,
+      description: surface?.description ?? spec.description,
+      promptSnippet: surface?.promptSnippet ?? spec.promptSnippet,
+      promptGuidelines: surface?.promptGuidelines ?? [...spec.promptGuidelines],
+      parameters: spec.parameters,
+      execute: createExecute(spec),
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shared parameter builders
+// ---------------------------------------------------------------------------
+
+/** File path (relative or absolute). */
+export const FileParam = Type.String({ description: "File path (relative or absolute)" });
+
+/** 1-based line number. */
+export const LineParam = Type.Number({ description: "1-based line number", minimum: 1 });
+
+/** 1-based character column (UTF-16). */
+export const CharacterParam = Type.Number({
+  description: "1-based column number (UTF-16)",
+  minimum: 1,
+});
+
+/** Symbol name for discovery-based resolution. */
+export const SymbolParam = Type.String({
+  description: "Symbol name for discovery-based resolution",
+});
+
+/** Maximum results to return. */
+export const MaxResultsParam = Type.Number({ description: "Maximum results to return" });
+
+// ---------------------------------------------------------------------------
+// Progress widget runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Run an async operation with a live TUI progress widget.
+ *
+ * Automatically manages:
+ * - The {@link ProgressWidget} lifecycle
+ * - `supi:working:start` / `supi:working:end` events for tab-spinner integration
+ * - Abort signal handling
+ * - Error catching (returns `null` on failure)
+ *
+ * Falls back to running without a widget when `ctx.hasUI` is false.
+ *
+ * @param pi - The extension API (for event emission).
+ * @param ctx - The command context (for UI access and hasUI check).
+ * @param title - The progress widget title.
+ * @param runner - Async function that receives (signal, onProgress).
+ * @returns The runner result, or `null` on cancel/error.
+ */
+export async function runWithProgressWidget<T>(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  title: string,
+  runner: (signal: AbortSignal, onProgress: (p: WidgetProgress) => void) => Promise<T>,
+): Promise<T | null> {
+  if (!ctx.hasUI) {
+    // No UI — run without progress widget but still emit working events
+    pi.events.emit("supi:working:start", { source: "supi-core" });
+    try {
+      return await runner(new AbortController().signal, () => {});
+    } catch {
+      return null;
+    } finally {
+      pi.events.emit("supi:working:end", { source: "supi-core" });
+    }
+  }
+
+  return ctx.ui.custom<T | null>((tui, theme, _kb, done) => {
+    const widget = new ProgressWidget(tui, theme, title);
+    let finished = false;
+
+    const finish = (result: T | null) => {
+      if (finished) return;
+      finished = true;
+      pi.events.emit("supi:working:end", { source: "supi-core" });
+      widget.dispose();
+      done(result);
+    };
+
+    widget.onAbort = () => {
+      // Widget handles abort signal; runner resolves with cancel/error.
+    };
+
+    pi.events.emit("supi:working:start", { source: "supi-core" });
+    runner(widget.signal, (progress) => widget.updateProgress(progress))
+      .then((result) => finish(result))
+      .catch(() => finish(null));
+
+    return widget;
+  });
+}

package/node_modules/@mrclrchtr/supi-core/src/types.ts

@@ -0,0 +1,2 @@
+// supi-core types domain — shared substrate types (zero dependencies, pure types).
+export type { CodeLocation, CodePosition } from "./substrate-types.ts";