@mrclrchtr/supi-settings 1.8.1

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

@@ -0,0 +1,255 @@
+// 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 type DebugNotifyLevel = "off" | "warning" | "error";
+
+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;
+  /** Minimum level that should notify the user; interpreted by UI extensions. */
+  notifyLevel: DebugNotifyLevel;
+}
+
+export const DEBUG_REGISTRY_DEFAULTS: DebugRegistryConfig = {
+  enabled: false,
+  agentAccess: "sanitized",
+  maxEvents: 100,
+  notifyLevel: "off",
+};
+
+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;
+}
+
+export interface DebugSummary {
+  total: number;
+  byLevel: Partial<Record<DebugLevel, number>>;
+  bySource: Record<string, number>;
+}
+
+interface DebugRegistryState {
+  config: DebugRegistryConfig;
+  events: DebugEvent[];
+  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: [],
+      nextId: 1,
+    };
+    (globalThis as Record<symbol, unknown>)[REGISTRY_KEY] = state;
+  }
+  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);
+}
+
+function matchesQuery(event: DebugEvent, query: DebugEventQuery): 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;
+}
+
+/** 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);
+  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) => matchesQuery(event, query))
+    .slice()
+    .reverse()
+    .slice(0, limit)
+    .map((event): DebugEventView => {
+      const view: DebugEventView = {
+        id: event.id,
+        timestamp: event.timestamp,
+        source: event.source,
+        level: event.level,
+        category: event.category,
+        message: event.message,
+        cwd: event.cwd,
+        data: event.data,
+      };
+      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.nextId = 1;
+}

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

@@ -0,0 +1,30 @@
+// 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 "./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 "./path.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./project.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 "./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/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/project-roots.ts

@@ -0,0 +1,170 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const IGNORED_DIRECTORIES = new Set(["node_modules", ".git", ".pnpm"]);
+
+/**
+ * Walk a project directory tree, calling `onDirectory` for each directory.
+ * Skips `node_modules`, `.git`, and `.pnpm`.
+ * Stops at depth 0.
+ */
+export function walkProject(
+  directory: string,
+  depth: number,
+  onDirectory: (directory: string, entryNames: Set<string>) => void,
+): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  const entryNames = new Set(entries.map((entry) => entry.name));
+  onDirectory(directory, entryNames);
+
+  if (depth <= 0) return;
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (IGNORED_DIRECTORIES.has(entry.name)) continue;
+    walkProject(path.join(directory, entry.name), depth - 1, onDirectory);
+  }
+}
+
+/**
+ * Search upward from `startDir` for any of the `markers` files/dirs.
+ * Returns the directory containing the first found marker, or `fallback`.
+ */
+export function findProjectRoot(startDir: string, markers: string[], fallback: string): string {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    for (const marker of markers) {
+      if (fs.existsSync(path.join(dir, marker))) {
+        return dir;
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return fallback;
+}
+
+/**
+ * Deduplicate overlapping roots, keeping only the topmost (shortest path) roots.
+ */
+export function dedupeTopmostRoots(roots: string[]): string[] {
+  const accepted: string[] = [];
+
+  for (const root of [...new Set(roots.map((entry) => path.resolve(entry)))].sort(byPathDepth)) {
+    const isChild = accepted.some((parent) => root !== parent && isWithin(parent, root));
+    if (!isChild) {
+      accepted.push(root);
+    }
+  }
+
+  return accepted;
+}
+
+/**
+ * Minimal shape accepted by `buildKnownRootsMap`.
+ * Structurally compatible with `DetectedProjectServer` and similar
+ * `{ name, root }` records — callers may pass a wider type safely.
+ */
+export type KnownRootEntry = { name: string; root: string };
+
+/**
+ * Build a map of language/server name to sorted, deduplicated root paths.
+ *
+ * Accepts an array of detected project entries (e.g. from LSP project discovery)
+ * and groups them by name with roots sorted by specificity.
+ */
+export function buildKnownRootsMap(detected: KnownRootEntry[]): Map<string, string[]> {
+  const next = new Map<string, string[]>();
+
+  for (const entry of detected) {
+    const roots = next.get(entry.name) ?? [];
+    if (!roots.includes(entry.root)) roots.push(entry.root);
+    next.set(entry.name, sortRootsBySpecificity(roots));
+  }
+
+  return next;
+}
+
+/**
+ * Merge a new root into an existing list, deduplicating and sorting.
+ *
+ * Returns the original reference when the root is already present.
+ */
+export function mergeKnownRoots(roots: string[], root: string): string[] {
+  if (roots.includes(root)) return roots;
+  return sortRootsBySpecificity([...roots, root]);
+}
+
+/**
+ * Resolve the most specific known root that contains `filePath`.
+ *
+ * Searches the given roots list (presumed sorted by specificity) and returns
+ * the first root that contains or equals `filePath`.
+ *
+ * @returns The matching root string, or `null` when none match.
+ */
+export function resolveKnownRoot(filePath: string, roots: string[]): string | null {
+  const resolvedPath = path.resolve(filePath);
+  return roots.find((root) => isWithinOrEqual(root, resolvedPath)) ?? null;
+}
+
+/**
+ * Sort roots by specificity (deepest/longest first), then alphabetically.
+ *
+ * Deduplicates by resolved path before sorting.
+ */
+export function sortRootsBySpecificity(roots: string[]): string[] {
+  return [...new Set(roots.map((root) => path.resolve(root)))].sort(
+    (a, b) => b.length - a.length || a.localeCompare(b),
+  );
+}
+
+/**
+ * Check if `child` is strictly inside `parent`.
+ *
+ * Returns `true` when `child` is a subdirectory of `parent`.
+ * Returns `false` for the same path.
+ */
+export function isWithin(parent: string, child: string): boolean {
+  const relative = path.relative(parent, child);
+  return relative !== "" && !relative.startsWith(`..${path.sep}`) && relative !== "..";
+}
+
+/**
+ * Check if `filePath` is inside `root` or is the same path.
+ *
+ * Combines exact-path equality with `isWithin` semantics.
+ */
+export function isWithinOrEqual(root: string, filePath: string): boolean {
+  const relative = path.relative(root, filePath);
+  return relative === "" || isWithin(root, filePath);
+}
+
+/**
+ * Comparator for sorting paths by depth (shallowest first), then alphabetically.
+ *
+ * Useful with `.sort()` on arrays of path strings.
+ */
+export function byPathDepth(a: string, b: string): number {
+  const depthDiff = segmentCount(a) - segmentCount(b);
+  return depthDiff !== 0 ? depthDiff : a.localeCompare(b);
+}
+
+/**
+ * Count path segments in a resolved absolute path.
+ *
+ * @example segmentCount("/a/b/c") // 3
+ */
+export function segmentCount(target: string): number {
+  return path.resolve(target).split(path.sep).filter(Boolean).length;
+}

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

@@ -0,0 +1,15 @@
+// supi-core project domain — project root discovery and traversal.
+export type { KnownRootEntry } from "./project-roots.ts";
+export {
+  buildKnownRootsMap,
+  byPathDepth,
+  dedupeTopmostRoots,
+  findProjectRoot,
+  isWithin,
+  isWithinOrEqual,
+  mergeKnownRoots,
+  resolveKnownRoot,
+  segmentCount,
+  sortRootsBySpecificity,
+  walkProject,
+} from "./project-roots.ts";

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

@@ -0,0 +1,86 @@
+// Shared registry utility for SuPi extensions.
+//
+// Provides a globalThis-backed registry pattern so that all jiti module instances
+// (resolved through different node_modules symlinks) share the same Map.
+// Without this, each symlink path gets its own module copy and its own Map,
+// so registrations from one instance are invisible to consumers in another.
+
+import * as path from "node:path";
+
+const SYMBOL_PREFIX = "@mrclrchtr/supi-core/";
+
+function getGlobalRegistryMap<T>(name: string): Map<string, T> {
+  const key = Symbol.for(SYMBOL_PREFIX + name);
+  let map = (globalThis as Record<symbol, unknown>)[key] as Map<string, T> | undefined;
+  if (!map) {
+    map = new Map<string, T>();
+    (globalThis as Record<symbol, unknown>)[key] = map;
+  }
+  return map;
+}
+
+/**
+ * Create a named registry backed by `globalThis` + `Symbol.for`.
+ *
+ * The registry is lazily initialized on first access and shared across all
+ * jiti module instances via the global symbol namespace.
+ *
+ * @typeParam T - The value type stored in the registry.
+ * @param name - Unique registry name (used to construct the `Symbol.for` key).
+ * @returns An object with `register`, `getAll`, and `clear` functions.
+ */
+export function createRegistry<T>(name: string) {
+  const getMap = (): Map<string, T> => getGlobalRegistryMap<T>(name);
+
+  return {
+    /**
+     * Register a value by id. Duplicate ids silently replace the previous registration.
+     */
+    register: (id: string, value: T): void => {
+      getMap().set(id, value);
+    },
+
+    /**
+     * Get all registered values in registration order.
+     */
+    getAll: (): T[] => {
+      return Array.from(getMap().values());
+    },
+
+    /**
+     * Clear all entries from the registry (primarily for tests).
+     */
+    clear: (): void => {
+      getMap().clear();
+    },
+  };
+}
+
+/**
+ * Create a named session-state registry keyed by normalized cwd.
+ *
+ * This helper is intended for session-scoped runtime services that should be
+ * shared across duplicate jiti module instances while keeping package-specific
+ * state unions and convenience wrappers local to the calling package.
+ */
+export function createSessionStateRegistry<TState>(name: string) {
+  const getMap = (): Map<string, TState> => getGlobalRegistryMap<TState>(name);
+  const normalizeCwd = (cwd: string): string => path.resolve(cwd);
+
+  return {
+    /** Get the current state for one session cwd. */
+    get: (cwd: string): TState | undefined => {
+      return getMap().get(normalizeCwd(cwd));
+    },
+
+    /** Store the current state for one session cwd. */
+    set: (cwd: string, state: TState): void => {
+      getMap().set(normalizeCwd(cwd), state);
+    },
+
+    /** Clear the current state for one session cwd. */
+    clear: (cwd: string): void => {
+      getMap().delete(normalizeCwd(cwd));
+    },
+  };
+}

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

@@ -0,0 +1,29 @@
+// Generic session-file tree-walking utilities.
+
+import type { FileEntry, SessionEntry } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Resolve the active branch path using PI's append-only tree semantics.
+ *
+ * The active branch is the path from the **last entry** (current leaf)
+ * back to the root via `parentId`. This follows PI's tree structure where
+ * entries are append-only and the last entry in the file is always the
+ * current leaf of the active branch.
+ */
+export function getActiveBranchEntries(entries: FileEntry[]): SessionEntry[] {
+  const sessionEntries = entries.filter((e): e is SessionEntry => e.type !== "session");
+  const byId = new Map(sessionEntries.map((entry) => [entry.id, entry]));
+  const leaf = sessionEntries.at(-1);
+  if (!leaf) return [];
+
+  const path: SessionEntry[] = [];
+  const visited = new Set<string>();
+  let current: SessionEntry | undefined = leaf;
+  while (current) {
+    if (visited.has(current.id)) break;
+    visited.add(current.id);
+    path.unshift(current);
+    current = current.parentId ? byId.get(current.parentId) : undefined;
+  }
+  return path;
+}

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

@@ -0,0 +1,4 @@
+// supi-core session domain — session utilities and registries.
+
+export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
+export { getActiveBranchEntries } from "./session-utils.ts";

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

@@ -0,0 +1,15 @@
+// /supi-settings command registration.
+//
+// Thin wrapper that registers the command and delegates to openSettingsOverlay.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { openSettingsOverlay } from "./settings-ui.ts";
+
+export function registerSettingsCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("supi-settings", {
+    description: "Manage SuPi extension settings",
+    handler: async (_args, ctx) => {
+      openSettingsOverlay(ctx);
+    },
+  });
+}