@mrclrchtr/supi-prompt-suggestions 1.16.1

package/node_modules/@mrclrchtr/supi-core/src/footer-registry.ts

@@ -0,0 +1,57 @@
+// Shared footer contribution registry for SuPi extensions.
+//
+// Extensions register pre-styled text chunks with a placement hint
+// ("stats" for the metrics line, "status" for the extension status line).
+// The custom footer in supi-extras (or PI's built-in footer) reads these
+// contributions and renders them alongside the built-in metrics.
+
+import { createRegistry } from "./registry-utils.ts";
+
+/** Where the contribution should appear in the footer. */
+export type FooterPlacement = "stats" | "stats-end" | "status";
+
+/** A single footer contribution registered by an extension. */
+export interface FooterContribution {
+  /** Unique key for this contribution. Re-registering with the same key replaces it. */
+  key: string;
+  /** Which footer line this belongs on. */
+  placement: FooterPlacement;
+  /**
+   * Sort order within the placement (lower values render further left). Default: 100.
+   * Priority 0 is reserved for the turn cache-hit part so it stays adjacent to CH.
+   */
+  priority?: number;
+  /** Return the pre-styled text for this contribution. Called on every render. */
+  render: () => string;
+}
+
+const registry = createRegistry<FooterContribution>("footer-contributions");
+
+function sortByPriority(a: FooterContribution, b: FooterContribution): number {
+  return (a.priority ?? 100) - (b.priority ?? 100);
+}
+
+export const footerContributions = {
+  /** Register or replace a footer contribution. */
+  register(contribution: FooterContribution): void {
+    registry.register(contribution.key, contribution);
+  },
+
+  /** Remove a contribution (e.g. on session_shutdown or when disabled). */
+  unregister(key: string): void {
+    registry.unregister(key);
+  },
+
+  /** Get contributions for a specific placement, sorted by priority. */
+  getByPlacement(placement: FooterPlacement): FooterContribution[] {
+    return registry
+      .getAll()
+      .filter((c) => c.placement === placement)
+      .sort(sortByPriority);
+  },
+
+  /** Remove all contributions (primarily for tests). */
+  clear(): void {
+    registry.clear();
+  },
+};

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

@@ -0,0 +1,40 @@
+// supi-core — shared infrastructure for SuPi extensions.
+// Provides XML context tag wrapping, unified config system, context-message utilities,
+// settings registry for supi-wide TUI settings, and a shared tool-spec/registration framework.
+//
+// Convenience barrel — re-exports all domain entry points.
+// For lighter imports, use one of the domain subpaths directly
+// (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
+
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./abort-utils.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./config.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./context.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./debug-registry.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./footer-registry.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./model-selection.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./path.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./project.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./report.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./session.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./settings.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./settings-ui.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./status-spinner.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./terminal.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./tool-framework.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./types.ts";

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

@@ -0,0 +1,211 @@
+import { complete } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TSchema } from "typebox";
+import { Value } from "typebox/value";
+
+// Shared LLM utilities for SuPi extensions.
+//
+// Provides retry logic, structured LLM call helpers, and other
+// common patterns for extensions that interact with AI models.
+
+/**
+ * Options for {@link withRetry}.
+ */
+export interface WithRetryOptions {
+  /** Maximum number of retry attempts after the initial call. Default: 2 */
+  retries?: number;
+  /** Base delay in milliseconds for exponential backoff. Default: 1000 */
+  baseDelayMs?: number;
+  /** AbortSignal to cancel retry loops. */
+  signal?: AbortSignal;
+  /** Called with each failed attempt's attempt index and error. */
+  logger?: (attempt: number, error: unknown) => void;
+  /** Called before each retry delay with attempt index and computed delay. */
+  onRetry?: (attempt: number, delayMs: number) => void;
+}
+
+/**
+ * Attempt an async operation with retries and exponential backoff.
+ *
+ * If the signal is already aborted on entry, the operation is skipped entirely.
+ * If the signal aborts during a delay, the delay is cancelled immediately.
+ *
+ * @param fn - The async operation to retry.
+ * @param options - Optional configuration for retries, backoff, signal, and callbacks.
+ * @returns The result on success, or `null` if all attempts fail or the signal aborts.
+ */
+/**
+ * Create a promise that resolves after `ms` milliseconds, or rejects if
+ * the signal fires before the timeout elapses.
+ */
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    if (signal) {
+      const onAbort = () => {
+        clearTimeout(timer);
+        reject(new DOMException("Aborted", "AbortError"));
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+
+/**
+ * Attempt an async operation with retries and exponential backoff.
+ *
+ * If the signal is already aborted on entry, the operation is skipped entirely.
+ * If the signal aborts during a delay, the delay is cancelled immediately.
+ *
+ * @param fn - The async operation to retry.
+ * @param options - Optional configuration for retries, backoff, signal, and callbacks.
+ * @returns The result on success, or `null` if all attempts fail or the signal aborts.
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options?: WithRetryOptions,
+): Promise<T | null> {
+  const { retries = 2, baseDelayMs = 1000, signal, logger, onRetry } = options ?? {};
+
+  if (signal?.aborted) return null;
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      logger?.(attempt, err);
+      if (attempt >= retries || signal?.aborted) continue;
+
+      const delayMs = baseDelayMs * 2 ** attempt;
+      onRetry?.(attempt, delayMs);
+
+      try {
+        await delay(delayMs, signal);
+      } catch {
+        // delay() only rejects on abort
+        return null;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extract and validate JSON from LLM response content blocks.
+ *
+ * Finds the first JSON object `{...}` in the combined text content,
+ * parses it, and validates against a TypeBox schema.
+ *
+ * @param content - The LLM response content blocks.
+ * @param schema - TypeBox schema to validate against.
+ * @returns The parsed and validated result, or `null` if extraction or validation fails.
+ */
+export function extractJsonFromResponse<T extends TSchema>(
+  content: ReadonlyArray<{ type: string; text?: string }>,
+  schema: T,
+): { parsed: import("typebox").Static<T> } | null {
+  const text = content
+    .filter((c): c is { type: "text"; text: string } => c.type === "text")
+    .map((c) => c.text)
+    .join("");
+
+  const jsonMatch = text.match(/\{[\s\S]*\}/);
+  if (!jsonMatch) return null;
+
+  try {
+    const parsed = JSON.parse(jsonMatch[0]);
+    if (Value.Check(schema, parsed)) {
+      return { parsed } as { parsed: import("typebox").Static<T> };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// ── callWithJsonResponse ───────────────────────────────────────────────────
+
+/**
+ * Options for {@link callWithJsonResponse}.
+ */
+export interface CallWithJsonResponseOptions {
+  /** The prompt to send to the LLM. */
+  prompt: string;
+  /** Optional data context appended to the prompt. */
+  dataContext?: string;
+  /** Maximum tokens for the response. Default: 4096 */
+  maxTokens?: number;
+  /** System prompt for the LLM call. Default: "" */
+  systemPrompt?: string;
+  /** Number of retries for the LLM call. Default: 2 */
+  retries?: number;
+}
+
+/**
+ * Call the LLM with a prompt and validate the JSON response against a TypeBox schema.
+ *
+ * Handles model resolution, auth, retry via `withRetry`, text extraction,
+ * JSON regex matching, and TypeBox validation.
+ *
+ * Returns `null` when:
+ * - No model is available
+ * - All retries fail
+ * - Response contains no valid JSON
+ * - JSON doesn't match the schema
+ * - The request is aborted
+ *
+ * @param ctx - The extension context for model resolution and auth.
+ * @param options - Call options including prompt, schema, and retry config.
+ * @param schema - TypeBox schema to validate the JSON response against.
+ * @returns The parsed and validated result, or `null`.
+ */
+export async function callWithJsonResponse<T extends TSchema>(
+  ctx: ExtensionContext,
+  options: CallWithJsonResponseOptions,
+  schema: T,
+): Promise<{ parsed: import("typebox").Static<T> } | null> {
+  const { prompt, dataContext, maxTokens = 4096, systemPrompt = "", retries = 2 } = options;
+
+  const model = ctx.model ?? ctx.modelRegistry.getAvailable()[0] ?? null;
+  if (!model) return null;
+
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+  if (!auth.ok || !auth.apiKey) return null;
+
+  const fullPrompt = dataContext
+    ? `${prompt}
+
+DATA:
+${dataContext}`
+    : prompt;
+
+  const response = await withRetry(
+    async () => {
+      return complete(
+        model,
+        {
+          systemPrompt,
+          messages: [
+            {
+              role: "user",
+              content: [{ type: "text", text: fullPrompt }],
+              timestamp: Date.now(),
+            },
+          ],
+        },
+        {
+          apiKey: auth.apiKey,
+          headers: auth.headers,
+          signal: ctx.signal,
+          maxTokens,
+        },
+      );
+    },
+    { retries, baseDelayMs: 1000, signal: ctx.signal },
+  );
+
+  if (!response) return null;
+
+  return extractJsonFromResponse(response.content, schema);
+}

package/node_modules/@mrclrchtr/supi-core/src/model-selection.ts

@@ -0,0 +1,134 @@
+/**
+ * Shared model-selection helpers for SuPi extensions.
+ *
+ * Provides scoped-model listing using PI's `enabledModels` configuration,
+ * matching the same semantics as the `@mrclrchtr/supi-review` model picker.
+ *
+ * @module
+ */
+
+import type { Model } from "@earendil-works/pi-ai";
+import { type ExtensionContext, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+/** A selectable model entry with display metadata. */
+export interface ModelSelection {
+  /** Canonical `provider/model-id` string. */
+  canonicalId: string;
+  /** Provider name, e.g. `"anthropic"`. */
+  provider: string;
+  /** Model id, e.g. `"claude-sonnet-4-5"`. */
+  id: string;
+  // biome-ignore lint/suspicious/noExplicitAny: Model<any> is pi's canonical type
+  model: Model<any>;
+  /** Human-readable label (model name or canonicalId). */
+  label: string;
+  /** Optional description (canonicalId when different from label). */
+  description?: string;
+  /** Whether this model is the current session model. */
+  isCurrent: boolean;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+/** Build the canonical `provider/model-id` string. */
+export function toCanonicalModelId(
+  model: Pick<NonNullable<ExtensionContext["model"]>, "provider" | "id">,
+): string {
+  return `${model.provider}/${model.id}`;
+}
+
+/**
+ * List selectable models from PI's scoped model configuration.
+ *
+ * Only models that match the configured `enabledModels` patterns are offered.
+ * The current session model is included only when it is inside that scoped set.
+ * Returns an empty array when no scoped model patterns are configured.
+ */
+export function getSelectableModels(
+  ctx: Pick<ExtensionContext, "cwd" | "modelRegistry" | "model">,
+  enabledModelPatterns = SettingsManager.create(ctx.cwd).getEnabledModels(),
+): ModelSelection[] {
+  if (!enabledModelPatterns || enabledModelPatterns.length === 0) {
+    return [];
+  }
+
+  const byCanonicalId = new Map<string, ModelSelection>();
+  const availableModels = filterByEnabledModels(
+    enabledModelPatterns,
+    ctx.modelRegistry.getAvailable(),
+  );
+
+  const addModel = (
+    // biome-ignore lint/suspicious/noExplicitAny: Model<any> is pi's canonical type
+    model: Model<any>,
+    isCurrent: boolean,
+  ) => {
+    const canonicalId = toCanonicalModelId(model);
+    const existing = byCanonicalId.get(canonicalId);
+    if (existing) {
+      if (isCurrent) existing.isCurrent = true;
+      return;
+    }
+
+    byCanonicalId.set(canonicalId, {
+      canonicalId,
+      provider: model.provider,
+      id: model.id,
+      model,
+      label: model.name ?? canonicalId,
+      description: canonicalId,
+      isCurrent,
+    });
+  };
+
+  if (ctx.model && matchModelPatterns(ctx.model, enabledModelPatterns)) {
+    addModel(ctx.model, true);
+  }
+
+  for (const model of availableModels) {
+    addModel(
+      model,
+      ctx.model ? toCanonicalModelId(model) === toCanonicalModelId(ctx.model) : false,
+    );
+  }
+
+  return Array.from(byCanonicalId.values()).sort((a, b) => {
+    if (a.isCurrent !== b.isCurrent) return a.isCurrent ? -1 : 1;
+    return a.canonicalId.localeCompare(b.canonicalId);
+  });
+}
+
+// ── Private helpers ────────────────────────────────────────────────────────
+
+function filterByEnabledModels<T extends { provider: string; id: string }>(
+  patterns: string[],
+  models: T[],
+): T[] {
+  return models.filter((model) => matchModelPatterns(model, patterns));
+}
+
+function matchModelPatterns(model: { provider: string; id: string }, patterns: string[]): boolean {
+  return patterns.some((pattern) => matchModelPattern(model, pattern));
+}
+
+function matchModelPattern(model: { provider: string; id: string }, pattern: string): boolean {
+  const canonicalId = `${model.provider}/${model.id}`;
+  if (pattern.includes("/")) {
+    return simpleGlobMatch(canonicalId, pattern);
+  }
+  return simpleGlobMatch(model.id, pattern) || simpleGlobMatch(canonicalId, pattern);
+}
+
+function simpleGlobMatch(text: string, pattern: string): boolean {
+  if (!pattern.includes("*") && !pattern.includes("?")) {
+    return text.toLowerCase() === pattern.toLowerCase();
+  }
+
+  const regex = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*/g, ".*")
+    .replace(/\?/g, ".");
+  return new RegExp(`^${regex}$`, "i").test(text);
+}

package/node_modules/@mrclrchtr/supi-core/src/path-utils.ts

@@ -0,0 +1,40 @@
+import * as path from "node:path";
+
+/** Strip pi's optional leading `@` file-path prefix from a tool input. */
+export function stripToolPathPrefix(target: string): string {
+  return target.startsWith("@") ? target.slice(1) : target;
+}
+
+/**
+ * Resolve a tool-style file path from a session cwd.
+ *
+ * Built-in pi file tools accept a leading `@` prefix in path arguments, so
+ * shared SuPi path helpers normalize that prefix before resolving relative
+ * paths.
+ */
+export function resolveToolPath(cwd: string, target: string): string {
+  return path.resolve(cwd, stripToolPathPrefix(target));
+}
+
+/** Convert a file path to a file:// URI. */
+export function fileToUri(filePath: string): string {
+  const resolved = path.resolve(filePath);
+  if (process.platform === "win32") {
+    return `file:///${resolved.replace(/\\/g, "/")}`;
+  }
+  return `file://${resolved}`;
+}
+
+/** Convert a file:// URI to a file path. */
+export function uriToFile(uri: string): string {
+  if (!uri.startsWith("file://")) return uri;
+  let filePath = decodeURIComponent(uri.slice(7));
+  if (
+    process.platform === "win32" &&
+    filePath.startsWith("/") &&
+    /^[A-Za-z]:/.test(filePath.slice(1))
+  ) {
+    filePath = filePath.slice(1);
+  }
+  return filePath;
+}

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

@@ -0,0 +1,2 @@
+// supi-core path domain — file and URI path utilities.
+export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";

package/node_modules/@mrclrchtr/supi-core/src/progress-widget.ts

@@ -0,0 +1,189 @@
+// Generic progress widget for SuPi long-running operations.
+//
+// Provides a TUI-based progress display with animated loader, turn counts,
+// tool usage, and activity descriptions.
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { CancellableLoader, Container, Text } from "@earendil-works/pi-tui";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+/** What the reviewer is currently doing and on what. */
+export interface CurrentFocus {
+  /** Display label for the active tool (e.g. "Reading", "Searching", "Finding"). */
+  label: string;
+  /** Context detail (e.g. file path, search pattern, directory). */
+  detail: string;
+}
+
+/** Progress state for widget display, compatible with child-session updates. */
+export interface WidgetProgress {
+  /** Number of agent turns completed. */
+  turns: number;
+  /** Number of tool executions started. */
+  toolUses: number;
+  /** Token usage stats, if available. */
+  tokens?: {
+    input: number;
+    output: number;
+    total: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+  /** Per-tool execution counts keyed by short display label (e.g. "diffs", "reads", "greps"). */
+  toolCounts?: Record<string, number>;
+  /** Number of distinct files inspected so far (via read_snapshot_diff / read_snapshot_file). */
+  filesInspected?: number;
+  /** Total files in the review snapshot. */
+  filesTotal?: number;
+  /** Current tool + context for the progress narrative line. */
+  currentFocus?: CurrentFocus;
+  /** Elapsed time in milliseconds since the operation started. */
+  elapsedMs?: number;
+}
+
+// ── Widget ─────────────────────────────────────────────────────────────────
+
+/**
+ * TUI progress widget for long-running operations.
+ *
+ * Two-line layout: top line shows the narrative (current focus + file progress),
+ * bottom line shows stats (tokens, elapsed time, turns, tool counts).
+ */
+export class ProgressWidget extends Container {
+  private message: string;
+  private progress: WidgetProgress = { turns: 0, toolUses: 0 };
+  private loader: CancellableLoader;
+  private tui: { requestRender(): void };
+  private theme: Theme;
+
+  constructor(tui: { requestRender(): void }, theme: Theme, message: string) {
+    super();
+    this.tui = tui;
+    this.theme = theme;
+    this.message = message;
+    this.loader = new CancellableLoader(
+      tui as ConstructorParameters<typeof CancellableLoader>[0],
+      (text: string) => theme.fg("accent", text),
+      (text: string) => theme.fg("muted", text),
+      message,
+    );
+
+    this.renderContent();
+  }
+
+  /** AbortSignal that fires when the user presses Escape. */
+  get signal(): AbortSignal {
+    return this.loader.signal;
+  }
+
+  /** Callback invoked when the user presses Escape. */
+  set onAbort(fn: (() => void) | undefined) {
+    this.loader.onAbort = fn;
+  }
+
+  /** Delegate keyboard input to the loader. */
+  handleInput(data: string): void {
+    this.loader.handleInput(data);
+  }
+
+  /** Update progress state and request a re-render. */
+  updateProgress(progress: WidgetProgress): void {
+    this.progress = progress;
+    this.renderContent();
+    this.tui.requestRender();
+  }
+
+  /** Clean up the widget. */
+  dispose(): void {
+    this.loader.dispose();
+  }
+
+  private renderContent(): void {
+    this.clear();
+    this.renderTopLine();
+    this.renderBottomLine();
+  }
+
+  private renderTopLine(): void {
+    const topParts: string[] = [];
+
+    if (this.progress.currentFocus) {
+      const { label, detail } = this.progress.currentFocus;
+      topParts.push(detail ? `${label}: ${detail}` : label);
+    }
+
+    if (this.progress.filesTotal && this.progress.filesTotal > 0) {
+      const inspected = this.progress.filesInspected ?? 0;
+      topParts.push(`${inspected}/${this.progress.filesTotal} files`);
+    }
+
+    const loaderMessage =
+      topParts.length > 0 ? `${this.message} · ${topParts.join(" · ")}` : this.message;
+    this.loader.setMessage(loaderMessage);
+    this.addChild(this.loader);
+  }
+
+  private renderBottomLine(): void {
+    const stats: string[] = [];
+
+    this.appendTokenStats(stats);
+
+    if (this.progress.elapsedMs !== undefined && this.progress.elapsedMs >= 1000) {
+      stats.push(formatElapsed(this.progress.elapsedMs));
+    }
+
+    if (this.progress.turns > 0) {
+      stats.push(`⟳ ${this.progress.turns}`);
+    }
+
+    if (this.progress.toolCounts) {
+      const parts = Object.entries(this.progress.toolCounts)
+        .filter(([, count]) => count > 0)
+        .sort(([, a], [, b]) => b - a)
+        .map(([label, count]) => `${count} ${label}`);
+      if (parts.length > 0) stats.push(parts.join(" · "));
+    }
+
+    if (stats.length > 0) {
+      this.addChild(new Text(this.theme.fg("dim", `  ${stats.join(" · ")}`), 1, 0));
+    }
+  }
+
+  private appendTokenStats(stats: string[]): void {
+    const tokens = this.progress.tokens;
+    if (!tokens) return;
+
+    stats.push(`↑ ${formatTokens(tokens.input)}`);
+    if (tokens.cacheRead !== undefined && tokens.cacheRead > 0) {
+      stats.push(`↲ ${formatTokens(tokens.cacheRead)}`);
+    }
+    if (tokens.cacheWrite !== undefined && tokens.cacheWrite > 0) {
+      stats.push(`↱ ${formatTokens(tokens.cacheWrite)}`);
+    }
+    stats.push(`↓ ${formatTokens(tokens.output)}`);
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+export function formatTokens(count: number): string {
+  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
+  return String(count);
+}
+
+export function formatElapsed(ms: number): string {
+  const totalSec = Math.floor(ms / 1000);
+  const hours = Math.floor(totalSec / 3600);
+  const minutes = Math.floor((totalSec % 3600) / 60);
+  const seconds = totalSec % 60;
+
+  if (hours > 0) {
+    return `${hours}h ${minutes}m ${seconds}s`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m ${seconds}s`;
+  }
+  return `${seconds}s`;
+}