@mrclrchtr/supi-consulting 0.0.0-stage → 9.0.0

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

@@ -0,0 +1,17 @@
+// supi-core config domain — config loading.
+export type {
+  AutomaticExclusionOptions,
+  SupiConfigLocation,
+  SupiConfigOptions,
+} from "./config/config.ts";
+export {
+  getSupiConfigPath,
+  loadAutomaticExclusionPatterns,
+  loadSupiConfig,
+  loadSupiConfigForScope,
+  loadSupiConfigSectionForScope,
+  readJsonFile,
+  removeSupiConfigKey,
+  replaceSupiConfigSection,
+  writeSupiConfig,
+} from "./config/config.ts";

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

@@ -0,0 +1,36 @@
+// Context provider registry for SuPi extensions.
+//
+// Extensions declare context data providers via `registerContextProvider()` during their
+// factory function. The `/supi-context` command reads them via `getRegisteredContextProviders()`.
+
+import { createRegistry } from "../registry-utils.ts";
+
+export interface ContextProvider {
+  /** Unique identifier — e.g. "lsp" */
+  id: string;
+  /** Human-readable label shown in the report */
+  label: string;
+  /** Return structured data for display, or null when unavailable. */
+  getData: () => Record<string, string | number> | null;
+}
+
+const registry = createRegistry<ContextProvider>("context-provider-registry");
+
+/**
+ * Register a context data provider for an extension.
+ * Call during the extension factory function (not async handlers).
+ * Duplicate ids replace the previous registration.
+ */
+export function registerContextProvider(provider: ContextProvider): void {
+  registry.register(provider.id, provider);
+}
+
+/** Get all registered context providers in registration order. */
+export function getRegisteredContextProviders(): ContextProvider[] {
+  return registry.getAll();
+}
+
+/** Clear the registry — used by tests. */
+export function clearRegisteredContextProviders(): void {
+  registry.clear();
+}

package/node_modules/@mrclrchtr/supi-core/src/context/context-tag.ts

@@ -0,0 +1,31 @@
+// XML context tag wrapping for SuPi extensions.
+//
+// Produces machine-parseable <extension-context> blocks that:
+// - Are LLM-friendly (structured XML)
+// - Carry metadata via attributes (source, file, turn, etc.)
+// - Can be reconstructed from session history via regex
+
+/**
+ * Wrap content in an `<extension-context>` XML tag.
+ *
+ * @param source - Extension identifier (e.g. "supi-claude-md", "supi-lsp")
+ * @param content - The text content to wrap
+ * @param attrs - Optional additional attributes (rendered as key="value")
+ * @returns Formatted XML string
+ */
+export function wrapExtensionContext(
+  source: string,
+  content: string,
+  attrs?: Record<string, string | number>,
+): string {
+  const attrParts = [`source="${source}"`];
+
+  if (attrs) {
+    for (const [key, value] of Object.entries(attrs)) {
+      attrParts.push(`${key}="${String(value)}"`);
+    }
+  }
+
+  const openTag = `<extension-context ${attrParts.join(" ")}>`;
+  return `${openTag}\n${content}\n</extension-context>`;
+}

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

@@ -0,0 +1,8 @@
+// supi-core context domain — context providers and XML tags.
+export type { ContextProvider } from "./context/context-provider-registry.ts";
+export {
+  clearRegisteredContextProviders,
+  getRegisteredContextProviders,
+  registerContextProvider,
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";

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

@@ -0,0 +1,11 @@
+/** Maximum UTF-16 code-unit length of one debug identity string. */
+export const MAX_DEBUG_IDENTITY_STRING = 512;
+
+/** Marker appended to a truncated debug identity string. */
+export const DEBUG_IDENTITY_TRUNCATION_MARKER = "…";
+
+/** Bound one debug identity string, including its truncation marker. */
+export function truncateDebugIdentity(value: string): string {
+  if (value.length <= MAX_DEBUG_IDENTITY_STRING) return value;
+  return `${value.slice(0, MAX_DEBUG_IDENTITY_STRING - 1)}${DEBUG_IDENTITY_TRUNCATION_MARKER}`;
+}

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

@@ -0,0 +1,313 @@
+// 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";
+
+/** Custom session-entry type used to persist sanitized debug events. */
+export const DEBUG_EVENT_ENTRY_TYPE = "supi-debug-event";
+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 {
+  /** Opaque identity for events directly owned by one public Tool call. */
+  operationId?: string;
+  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 {
+  /** Match one exact Debug Operation ID. */
+  operationId?: string;
+  source?: string;
+  level?: DebugLevel;
+  category?: string;
+  limit?: number;
+  includeRaw?: boolean;
+  allowRaw?: boolean;
+}
+
+export interface DebugEventView {
+  id: number;
+  timestamp: number;
+  operationId?: string;
+  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 DEBUG_OPERATION_ID_RE = /^op-[A-Za-z0-9_-]{21}[AQgw]$/;
+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";
+}
+
+/** Return whether a value has the exact 16-byte base64url Debug Operation ID form. */
+export function isDebugOperationId(value: unknown): value is string {
+  return typeof value === "string" && DEBUG_OPERATION_ID_RE.test(value);
+}
+
+/** Match a debug event against the supported exact filters. */
+export function matchesDebugEventQuery(
+  event: Pick<DebugEventView, "operationId" | "source" | "level" | "category">,
+  query: Pick<DebugEventQuery, "operationId" | "source" | "level" | "category">,
+): boolean {
+  if (query.operationId && event.operationId !== query.operationId) return false;
+  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);
+}
+
+/** Return whether the Debug Registry currently retains producer events. */
+export function isDebugRegistryEnabled(): boolean {
+  return getState().config.enabled;
+}
+
+/** 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,
+    operationId: event.operationId,
+    source: event.source,
+    level: event.level,
+    category: event.category,
+    message: event.message,
+    cwd: event.cwd,
+    data: event.data === undefined ? undefined : redactDebugData(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 (input.operationId !== undefined && !isDebugOperationId(input.operationId)) {
+    return null;
+  }
+  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);
+  for (const listener of state.listeners) {
+    try {
+      listener(toSanitizedView(event));
+    } catch {
+      // Debug-event consumers must not alter producer behavior.
+    }
+  }
+  return {
+    ...event,
+    data: event.data === undefined ? undefined : redactDebugData(event.data),
+  };
+}
+
+/** 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/debug-timing.ts

@@ -0,0 +1,120 @@
+import { performance } from "node:perf_hooks";
+import {
+  type DebugEvent,
+  type DebugEventInput,
+  isDebugRegistryEnabled,
+  recordDebugEvent,
+} from "./debug-registry.ts";
+
+/** Monotonic duration data added to a timed debug event. */
+export interface DebugTiming {
+  readonly durationMs: number;
+  readonly phasesMs: Readonly<Record<string, number>>;
+}
+
+/** Debug event input whose data can receive the reserved `timing` field. */
+export interface TimedDebugEventInput extends Omit<DebugEventInput, "data"> {
+  readonly data?: Readonly<Record<string, unknown>>;
+}
+
+/** Test seam for the monotonic clock used by a debug timer. */
+export interface DebugTimerOptions {
+  readonly now?: () => number;
+}
+
+/** Lazy timed-event input that is not evaluated when Debug is disabled. */
+export type TimedDebugEventFactory = () => TimedDebugEventInput;
+
+/** One-shot debug timer with optional sequential phase measurements. */
+export interface DebugTimer {
+  /** Whether this timer sampled Debug as enabled when it started. */
+  readonly enabled: boolean;
+  /** Finish the current phase and start the next unnamed interval. */
+  mark(phase: string): void;
+  /** Record one event. A second call returns `null` without recording another event. */
+  finish(
+    input: TimedDebugEventInput | TimedDebugEventFactory,
+    finalPhase?: string,
+  ): DebugEvent | null;
+}
+
+/**
+ * Start a monotonic timer for one debug event.
+ *
+ * Each `mark(name)` stores the interval since the previous mark. `finish()`
+ * stores the total duration and can name the final interval. Repeated phase
+ * names are accumulated. Event data reserves the `timing` field. When Debug is
+ * disabled at start, this returns a no-op timer and does not read the clock.
+ * Pass a factory to `finish()` to avoid event-data construction when disabled.
+ * Clock, event-construction, and registry failures are isolated from the
+ * measured operation and make the timer a no-op.
+ */
+export function startDebugTimer(options: DebugTimerOptions = {}): DebugTimer {
+  if (!isDebugRegistryEnabled()) return DISABLED_DEBUG_TIMER;
+  const now = options.now ?? performance.now.bind(performance);
+  let startedAt: number;
+  try {
+    startedAt = now();
+  } catch {
+    return DISABLED_DEBUG_TIMER;
+  }
+  let previousAt = startedAt;
+  let finished = false;
+  let failed = false;
+  const phases = new Map<string, number>();
+
+  const markAt = (phase: string, current: number): void => {
+    const name = phase.trim();
+    if (!name) return;
+    phases.set(name, (phases.get(name) ?? 0) + Math.max(0, current - previousAt));
+    previousAt = current;
+  };
+
+  return {
+    enabled: true,
+    mark(phase) {
+      if (finished || failed) return;
+      try {
+        markAt(phase, now());
+      } catch {
+        failed = true;
+      }
+    },
+    finish(input, finalPhase) {
+      if (finished || failed) return null;
+      finished = true;
+      try {
+        if (!isDebugRegistryEnabled()) return null;
+        const completedAt = now();
+        if (finalPhase) markAt(finalPhase, completedAt);
+        const phasesMs = Object.fromEntries(
+          [...phases.entries()].map(([name, value]) => [name, duration(value)]),
+        );
+        const timing: DebugTiming = {
+          durationMs: duration(completedAt - startedAt),
+          phasesMs,
+        };
+        const eventInput = typeof input === "function" ? input() : input;
+        return recordDebugEvent({
+          ...eventInput,
+          data: { ...eventInput.data, timing },
+        });
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+const DISABLED_DEBUG_TIMER: DebugTimer = Object.freeze({
+  enabled: false,
+  mark() {},
+  finish() {
+    return null;
+  },
+});
+
+function duration(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.round(Math.max(0, value) * 10) / 10;
+}

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

@@ -0,0 +1,14 @@
+// Debug domain entry for `@mrclrchtr/supi-core/debug`.
+//
+// Kept separate from debug-registry.ts so debug-timing.ts can import the
+// registry without creating an import cycle through the barrel re-export.
+
+export {
+  DEBUG_IDENTITY_TRUNCATION_MARKER,
+  MAX_DEBUG_IDENTITY_STRING,
+  truncateDebugIdentity,
+} from "./debug-identity.ts";
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-registry.ts";
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-timing.ts";

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,64 @@
+// 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 reads these contributions and renders them
+// alongside the built-in metrics. Extensions can use PI's status API as a
+// fallback when the custom footer is not installed.
+
+import { createRegistry } from "./registry-utils.ts";
+
+/** Event emitted when a dynamic footer contribution needs a new render. */
+export const FOOTER_INVALIDATE_EVENT = "supi:footer:invalidate";
+
+/** 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.
+   * A same-key Pi status is treated as this contribution's built-in-footer fallback.
+   */
+  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();
+  },
+};