@mrclrchtr/supi-skills 4.7.0

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

@@ -0,0 +1,287 @@
+// Shared debug event registry for SuPi extensions.
+//
+// Extensions record session-local diagnostic events here. The user-facing
+// supi-debug extension owns policy/configuration and exposes events through a
+// command/tool while this module stays dependency-free for producers.
+
+export type DebugLevel = "debug" | "info" | "warning" | "error";
+export type DebugAgentAccess = "off" | "sanitized" | "raw";
+export interface DebugRegistryConfig {
+  /** Whether producers should retain debug events. */
+  enabled: boolean;
+  /** What the agent-callable debug tool may return. */
+  agentAccess: DebugAgentAccess;
+  /** Maximum number of session-local events to keep in memory. */
+  maxEvents: number;
+}
+
+export const DEBUG_REGISTRY_DEFAULTS: DebugRegistryConfig = {
+  enabled: false,
+  agentAccess: "sanitized",
+  maxEvents: 100,
+};
+
+export interface DebugEventInput {
+  source: string;
+  level: DebugLevel;
+  category: string;
+  message: string;
+  cwd?: string;
+  data?: unknown;
+  rawData?: unknown;
+}
+
+export interface DebugEvent extends DebugEventInput {
+  id: number;
+  timestamp: number;
+  data?: unknown;
+  rawData?: unknown;
+}
+
+export interface DebugEventQuery {
+  source?: string;
+  level?: DebugLevel;
+  category?: string;
+  limit?: number;
+  includeRaw?: boolean;
+  allowRaw?: boolean;
+}
+
+export interface DebugEventView {
+  id: number;
+  timestamp: number;
+  source: string;
+  level: DebugLevel;
+  category: string;
+  message: string;
+  cwd?: string;
+  data?: unknown;
+  rawData?: unknown;
+}
+
+export interface DebugEventQueryResult {
+  events: DebugEventView[];
+  rawAccessDenied: boolean;
+}
+
+/** Receives a sanitized event whenever the registry records one. */
+export type DebugEventListener = (event: DebugEventView) => void;
+
+export interface DebugSummary {
+  total: number;
+  byLevel: Partial<Record<DebugLevel, number>>;
+  bySource: Record<string, number>;
+}
+
+interface DebugRegistryState {
+  config: DebugRegistryConfig;
+  events: DebugEvent[];
+  listeners: Set<DebugEventListener>;
+  nextId: number;
+}
+
+const REGISTRY_KEY = Symbol.for("@mrclrchtr/supi-core/debug-registry");
+const SECRET_KEY_RE = /(?:token|password|passwd|secret|api[_-]?key|authorization|credential)/i;
+const ENV_SECRET_RE =
+  /\b([A-Za-z0-9_]*(?:token|password|passwd|secret|api[_-]?key|authorization|credential)[A-Za-z0-9_]*)=(?:'[^']*'|"[^"]*"|\S+)/gi;
+const AUTH_HEADER_RE = /\b(authorization\s*[:=]\s*)(?:bearer\s+)?[^\s;&|]+/gi;
+const URL_SECRET_RE =
+  /([?&](?:token|password|passwd|secret|api[_-]?key|authorization|credential)=)[^&\s]+/gi;
+const REDACTED = "[REDACTED]";
+
+function cloneConfig(config: DebugRegistryConfig): DebugRegistryConfig {
+  return { ...config };
+}
+
+function getState(): DebugRegistryState {
+  let state = (globalThis as Record<symbol, unknown>)[REGISTRY_KEY] as
+    | DebugRegistryState
+    | undefined;
+  if (!state) {
+    state = {
+      config: cloneConfig(DEBUG_REGISTRY_DEFAULTS),
+      events: [],
+      listeners: new Set(),
+      nextId: 1,
+    };
+    (globalThis as Record<symbol, unknown>)[REGISTRY_KEY] = state;
+  }
+  // Keep the shared registry compatible with extension reloads that reuse an
+  // instance created before listeners existed.
+  if (!state.listeners) state.listeners = new Set();
+  return state;
+}
+
+function normalizeMaxEvents(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    return DEBUG_REGISTRY_DEFAULTS.maxEvents;
+  }
+  return Math.floor(value);
+}
+
+function trimToMaxEvents(state: DebugRegistryState): void {
+  const maxEvents = normalizeMaxEvents(state.config.maxEvents);
+  if (state.events.length <= maxEvents) {
+    return;
+  }
+  state.events.splice(0, state.events.length - maxEvents);
+}
+
+/** Return whether a debug level is recognized by the registry. */
+export function isDebugLevel(value: unknown): value is DebugLevel {
+  return value === "debug" || value === "info" || value === "warning" || value === "error";
+}
+
+/** Match a debug event against the supported source, level, and category filters. */
+export function matchesDebugEventQuery(
+  event: Pick<DebugEventView, "source" | "level" | "category">,
+  query: Pick<DebugEventQuery, "source" | "level" | "category">,
+): boolean {
+  if (query.source && event.source !== query.source) return false;
+  if (query.level && event.level !== query.level) return false;
+  if (query.category && event.category !== query.category) return false;
+  return true;
+}
+
+function sanitizeString(value: string): string {
+  return value
+    .replace(ENV_SECRET_RE, (_match, key: string) => `${key}=${REDACTED}`)
+    .replace(AUTH_HEADER_RE, (_match, prefix: string) => `${prefix}${REDACTED}`)
+    .replace(URL_SECRET_RE, (_match, prefix: string) => `${prefix}${REDACTED}`);
+}
+
+function redactValue(value: unknown, depth: number): unknown {
+  if (depth <= 0) return "[MaxDepth]";
+  if (typeof value === "string") return sanitizeString(value);
+  if (typeof value !== "object" || value === null) return value;
+  if (Array.isArray(value)) return value.map((item) => redactValue(item, depth - 1));
+
+  const redacted: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value)) {
+    redacted[key] = SECRET_KEY_RE.test(key) ? REDACTED : redactValue(item, depth - 1);
+  }
+  return redacted;
+}
+
+/** Configure the shared debug registry. Existing events are trimmed to the new max size. */
+export function configureDebugRegistry(config: Partial<DebugRegistryConfig>): DebugRegistryConfig {
+  const state = getState();
+  state.config = {
+    ...state.config,
+    ...config,
+    maxEvents: normalizeMaxEvents(config.maxEvents ?? state.config.maxEvents),
+  };
+  trimToMaxEvents(state);
+  return getDebugRegistryConfig();
+}
+
+/** Return the active debug registry configuration. */
+export function getDebugRegistryConfig(): DebugRegistryConfig {
+  return cloneConfig(getState().config);
+}
+
+/** Best-effort redaction helper for data exposed through sanitized debug views. */
+export function redactDebugData<T>(value: T): T {
+  return redactValue(value, 8) as T;
+}
+
+function toSanitizedView(event: DebugEvent): DebugEventView {
+  return {
+    id: event.id,
+    timestamp: event.timestamp,
+    source: event.source,
+    level: event.level,
+    category: event.category,
+    message: event.message,
+    cwd: event.cwd,
+    data: event.data,
+  };
+}
+
+/** Subscribe to sanitized events. Listeners are isolated so diagnostics cannot disrupt producers. */
+export function subscribeDebugEvents(listener: DebugEventListener): () => void {
+  const state = getState();
+  state.listeners.add(listener);
+  return () => state.listeners.delete(listener);
+}
+
+/** Record a session-local debug event if debugging is enabled. */
+export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
+  const state = getState();
+  if (!state.config.enabled) {
+    return null;
+  }
+
+  const event: DebugEvent = {
+    ...input,
+    id: state.nextId++,
+    timestamp: Date.now(),
+    data: input.data === undefined ? undefined : redactDebugData(input.data),
+  };
+  state.events.push(event);
+  trimToMaxEvents(state);
+  const view = toSanitizedView(event);
+  for (const listener of state.listeners) {
+    try {
+      listener(view);
+    } catch {
+      // Debug-event consumers must not alter producer behavior.
+    }
+  }
+  return { ...event };
+}
+
+/** Query retained debug events newest-first. Results are sanitized unless raw access is requested and allowed. */
+export function getDebugEvents(query: DebugEventQuery = {}): DebugEventQueryResult {
+  const state = getState();
+  const allowRaw = Boolean(
+    query.includeRaw && query.allowRaw && state.config.agentAccess === "raw",
+  );
+  const rawAccessDenied = Boolean(query.includeRaw && !allowRaw);
+  const limit = query.limit && query.limit > 0 ? Math.floor(query.limit) : state.config.maxEvents;
+
+  const events = state.events
+    .filter((event) => matchesDebugEventQuery(event, query))
+    .slice()
+    .reverse()
+    .slice(0, limit)
+    .map((event): DebugEventView => {
+      const view = toSanitizedView(event);
+      if (allowRaw && event.rawData !== undefined) {
+        view.rawData = event.rawData;
+      }
+      return view;
+    });
+
+  return { events, rawAccessDenied };
+}
+
+/** Return aggregate debug counts suitable for summary displays. */
+export function getDebugSummary(): DebugSummary | null {
+  const events = getState().events;
+  if (events.length === 0) {
+    return null;
+  }
+
+  const summary: DebugSummary = { total: events.length, byLevel: {}, bySource: {} };
+  for (const event of events) {
+    summary.byLevel[event.level] = (summary.byLevel[event.level] ?? 0) + 1;
+    summary.bySource[event.source] = (summary.bySource[event.source] ?? 0) + 1;
+  }
+  return summary;
+}
+
+/** Clear retained events while preserving configuration. */
+export function clearDebugEvents(): void {
+  const state = getState();
+  state.events = [];
+}
+
+/** Reset the debug registry to defaults; intended for tests. */
+export function resetDebugRegistry(): void {
+  const state = getState();
+  state.config = cloneConfig(DEBUG_REGISTRY_DEFAULTS);
+  state.events = [];
+  state.listeners.clear();
+  state.nextId = 1;
+}

package/node_modules/@mrclrchtr/supi-core/src/evidence-badge.ts

@@ -0,0 +1,41 @@
+/**
+ * TUI-facing evidence badge string formatter.
+ *
+ * Pure string formatting — no pi-tui dependency. Consumes evidence
+ * completeness metadata and produces compact human-readable badges.
+ */
+
+/** Metadata describing how many evidence atoms were shown vs exist. */
+export interface EvidenceBadgeInput {
+  shownCount: number;
+  totalCount: number | null;
+  omittedCount: number | null;
+  partialReason: string | null;
+  /** Human-readable label for the badge, e.g. "references", "symbols". */
+  label: string;
+}
+
+/**
+ * Format a compact evidence completeness badge.
+ *
+ * | Input                                                | Output                                |
+ * |------------------------------------------------------|---------------------------------------|
+ * | shown=12, total=12, omitted=0, label="references"   | `12 references`                       |
+ * | shown=8,  total=20, omitted=12, label="symbols"     | `8 of 20 symbols (12 omitted)`        |
+ * | shown=5, total=null, omitted=2, reason="timeout" | `5 matches (2 collected omitted; more may exist — timeout)` |
+ */
+export function formatEvidenceBadge(input: EvidenceBadgeInput): string {
+  const { shownCount, totalCount, omittedCount, partialReason, label } = input;
+
+  if (totalCount === null) {
+    const reasonSuffix = partialReason ? ` — ${partialReason}` : "";
+    const omittedPrefix = (omittedCount ?? 0) > 0 ? `${omittedCount} collected omitted; ` : "";
+    return `${shownCount} ${label} (${omittedPrefix}more may exist${reasonSuffix})`;
+  }
+
+  if (omittedCount !== null && omittedCount > 0) {
+    return `${shownCount} of ${totalCount} ${label} (${omittedCount} omitted)`;
+  }
+
+  return `${shownCount} ${label}`;
+}

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,34 @@
+// supi-core — shared infrastructure for SuPi extensions.
+// Provides XML context tag wrapping, unified config, prompt-surface resolution,
+// and shared settings, reporting, and session utilities.
+//
+// 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 "./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 "./prompt-surface.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 "./status-spinner.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./terminal.ts";

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

@@ -0,0 +1,201 @@
+import { complete } from "@earendil-works/pi-ai/compat";
+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;
+}
+
+/**
+ * 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);
+}