@mrclrchtr/supi-debug 0.1.0

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

@@ -0,0 +1,226 @@
+// 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 SettingItem,
+  SettingsList,
+  Text,
+} from "@earendil-works/pi-tui";
+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,
+): SettingItem[] {
+  const items: SettingItem[] = [];
+  for (const section of sections) {
+    const sectionItems = section.loadValues(scope, cwd);
+    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 {
+  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);
+  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);
+    }
+    // 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);
+    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();
+}
+
+// ── 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 = {
+      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/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/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@mrclrchtr/supi-debug",
+  "version": "0.1.0",
+  "description": "SuPi Debug extension — shared debug event inspection for SuPi extensions",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrclrchtr/supi.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "README.md"
+  ],
+  "dependencies": {
+    "@mrclrchtr/supi-core": "workspace:*"
+  },
+  "bundledDependencies": [
+    "@mrclrchtr/supi-core"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.5",
+    "@mrclrchtr/supi-test-utils": "workspace:*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/debug.ts"
+    ]
+  },
+  "main": "src/index.ts"
+}

package/src/debug.ts

@@ -0,0 +1,351 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  clearDebugEvents,
+  configureDebugRegistry,
+  DEBUG_REGISTRY_DEFAULTS,
+  type DebugAgentAccess,
+  type DebugEventQuery,
+  type DebugEventView,
+  type DebugLevel,
+  type DebugNotifyLevel,
+  getDebugEvents,
+  getDebugSummary,
+  loadSupiConfig,
+  registerConfigSettings,
+  registerContextProvider,
+} from "@mrclrchtr/supi-core";
+import { Type } from "typebox";
+import { maybeLogLoadStatus } from "../status-log.ts";
+import { formatDataLines } from "./format.ts";
+import { registerDebugMessageRenderer } from "./renderer.ts";
+
+const DEBUG_SECTION = "debug";
+const DEBUG_REPORT_TYPE = "supi-debug-report";
+
+interface DebugConfig {
+  enabled: boolean;
+  agentAccess: DebugAgentAccess;
+  maxEvents: number;
+  notifyLevel: DebugNotifyLevel;
+}
+
+const DEBUG_DEFAULTS: DebugConfig = { ...DEBUG_REGISTRY_DEFAULTS };
+
+type DebugToolParams = DebugEventQuery;
+
+function normalizeAgentAccess(value: string): DebugAgentAccess {
+  return value === "off" || value === "raw" ? value : "sanitized";
+}
+
+function normalizeNotifyLevel(value: string): DebugNotifyLevel {
+  return value === "warning" || value === "error" ? value : "off";
+}
+
+function normalizeMaxEvents(value: string | number): number {
+  const parsed = typeof value === "number" ? value : Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : DEBUG_DEFAULTS.maxEvents;
+}
+
+function normalizeEnabled(value: unknown): boolean {
+  if (typeof value === "boolean") {
+    return value;
+  }
+
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (
+      normalized === "true" ||
+      normalized === "on" ||
+      normalized === "1" ||
+      normalized === "yes"
+    ) {
+      return true;
+    }
+    if (
+      normalized === "false" ||
+      normalized === "off" ||
+      normalized === "0" ||
+      normalized === "no" ||
+      normalized === ""
+    ) {
+      return false;
+    }
+    return DEBUG_DEFAULTS.enabled;
+  }
+
+  if (value === 1) return true;
+  if (value === 0) return false;
+  return DEBUG_DEFAULTS.enabled;
+}
+
+function loadDebugConfig(cwd: string): DebugConfig {
+  const config = loadSupiConfig(DEBUG_SECTION, cwd, DEBUG_DEFAULTS);
+  return {
+    enabled: normalizeEnabled(config.enabled),
+    agentAccess: normalizeAgentAccess(String(config.agentAccess)),
+    maxEvents: normalizeMaxEvents(config.maxEvents),
+    notifyLevel: normalizeNotifyLevel(String(config.notifyLevel)),
+  };
+}
+
+function applyDebugConfig(cwd: string): DebugConfig {
+  const config = loadDebugConfig(cwd);
+  configureDebugRegistry(config);
+  return config;
+}
+
+function syncLiveDebugRegistry(cwd: string): DebugConfig {
+  const config = applyDebugConfig(cwd);
+  if (!config.enabled) {
+    clearDebugEvents();
+  }
+  return config;
+}
+
+function registerDebugSettings(): void {
+  registerConfigSettings({
+    id: "debug",
+    label: "Debug",
+    section: DEBUG_SECTION,
+    defaults: DEBUG_DEFAULTS,
+    buildItems: (settings) => [
+      {
+        id: "enabled",
+        label: "Enabled",
+        description: "Enable/disable session-local SuPi debug event capture",
+        currentValue: settings.enabled ? "on" : "off",
+        values: ["on", "off"],
+      },
+      {
+        id: "agentAccess",
+        label: "Agent Access",
+        description: "Control whether the agent can fetch sanitized or raw debug events",
+        currentValue: normalizeAgentAccess(String(settings.agentAccess)),
+        values: ["off", "sanitized", "raw"],
+      },
+      {
+        id: "maxEvents",
+        label: "Max Events",
+        description: "Maximum session-local debug events retained in memory",
+        currentValue: String(normalizeMaxEvents(settings.maxEvents)),
+        values: ["50", "100", "250", "500"],
+      },
+      {
+        id: "notifyLevel",
+        label: "Notify Level",
+        description: "Minimum debug event severity that may notify the user",
+        currentValue: normalizeNotifyLevel(String(settings.notifyLevel)),
+        values: ["off", "warning", "error"],
+      },
+    ],
+    // biome-ignore lint/complexity/useMaxParams: ConfigSettingsOptions interface callback
+    persistChange: (_scope, cwd, settingId, value, helpers) => {
+      if (settingId === "enabled") {
+        helpers.set("enabled", value === "on");
+      } else if (settingId === "agentAccess") {
+        helpers.set("agentAccess", normalizeAgentAccess(value));
+      } else if (settingId === "maxEvents") {
+        helpers.set("maxEvents", normalizeMaxEvents(value));
+      } else if (settingId === "notifyLevel") {
+        helpers.set("notifyLevel", normalizeNotifyLevel(value));
+      }
+
+      syncLiveDebugRegistry(cwd);
+    },
+  });
+}
+
+function parseCommandArgs(args: string): DebugEventQuery {
+  const query: DebugEventQuery = {};
+  const parts = args.trim().split(/\s+/).filter(Boolean);
+  for (const part of parts) {
+    const [key, value] = part.split("=", 2);
+    if (!value) continue;
+    if (key === "source") query.source = value;
+    if (key === "category") query.category = value;
+    if (key === "level" && isDebugLevel(value)) query.level = value;
+    if (key === "limit") query.limit = normalizeMaxEvents(value);
+  }
+  return query;
+}
+
+function isDebugLevel(value: string): value is DebugLevel {
+  return value === "debug" || value === "info" || value === "warning" || value === "error";
+}
+
+function pushFormattedData(lines: string[], label: string, value: unknown): void {
+  const dataLines = formatDataLines(value);
+  if (dataLines.length === 0) return;
+  if (dataLines.length === 1) {
+    lines.push(`  ${label}: ${dataLines[0]}`);
+  } else {
+    lines.push(`  ${label}:`);
+    for (const dl of dataLines) {
+      lines.push(`    ${dl}`);
+    }
+  }
+}
+
+function formatEvents(events: DebugEventView[], rawAccessDenied: boolean): string[] {
+  if (events.length === 0) {
+    return ["No matching debug events available."];
+  }
+
+  const lines: string[] = [];
+  for (const event of events) {
+    lines.push(
+      `[${new Date(event.timestamp).toISOString()}] ${event.level.toUpperCase()} ${event.source}/${event.category}: ${event.message}`,
+    );
+    if (event.cwd) lines.push(`  cwd: ${event.cwd}`);
+    pushFormattedData(lines, "data", event.data);
+    pushFormattedData(lines, "rawData", event.rawData);
+  }
+  if (rawAccessDenied) {
+    lines.push("");
+    lines.push("Raw debug data was requested but is not enabled in SuPi Debug settings.");
+  }
+  return lines;
+}
+
+function formatEventLines(query: DebugEventQuery): string[] {
+  const { events, rawAccessDenied } = getDebugEvents(query);
+  return formatEvents(events, rawAccessDenied);
+}
+
+function buildSummaryData(): Record<string, string | number> | null {
+  const summary = getDebugSummary();
+  if (!summary) return null;
+
+  const data: Record<string, string | number> = { total: summary.total };
+  for (const [level, count] of Object.entries(summary.byLevel)) {
+    if (count !== undefined) data[`level:${level}`] = count;
+  }
+  for (const [source, count] of Object.entries(summary.bySource)) {
+    data[`source:${source}`] = count;
+  }
+  return data;
+}
+
+function toolAccessAllowed(config: DebugConfig): boolean {
+  return config.enabled && config.agentAccess !== "off";
+}
+
+function buildToolResult(params: DebugToolParams, config: DebugConfig) {
+  if (!config.enabled) {
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: "SuPi debug event capture is disabled. Enable Debug in /supi-settings to retain events.",
+        },
+      ],
+      isError: true,
+      details: { enabled: false },
+    };
+  }
+
+  if (!toolAccessAllowed(config)) {
+    return {
+      content: [{ type: "text" as const, text: "Agent access to SuPi debug events is disabled." }],
+      isError: true,
+      details: { enabled: true, agentAccess: config.agentAccess },
+    };
+  }
+
+  const query: DebugEventQuery = {
+    source: params.source,
+    level: params.level,
+    category: params.category,
+    limit: params.limit,
+    includeRaw: params.includeRaw,
+    allowRaw: config.agentAccess === "raw",
+  };
+  const result = getDebugEvents(query);
+  const lines = formatEventLines(query);
+  return {
+    content: [{ type: "text" as const, text: lines.join("\n") }],
+    details: {
+      enabled: true,
+      agentAccess: config.agentAccess,
+      rawAccessDenied: result.rawAccessDenied,
+      events: result.events,
+    },
+  };
+}
+
+/** Register the shared SuPi debug command, settings, context summary, and agent tool. */
+export default function debugExtension(pi: ExtensionAPI) {
+  applyDebugConfig(process.cwd());
+  registerDebugSettings();
+  registerDebugMessageRenderer(pi);
+
+  registerContextProvider({
+    id: "debug",
+    label: "Debug",
+    getData: buildSummaryData,
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    clearDebugEvents();
+    applyDebugConfig(ctx.cwd);
+    maybeLogLoadStatus(pi, ctx.cwd);
+  });
+
+  pi.registerCommand("supi-debug", {
+    description: "Show recent SuPi debug events",
+    handler: async (args, ctx) => {
+      const config = applyDebugConfig(ctx.cwd);
+      if (!config.enabled) {
+        pi.sendMessage({
+          customType: DEBUG_REPORT_TYPE,
+          content: "SuPi debug event capture is disabled. Enable Debug in /supi-settings.",
+          display: true,
+        });
+        return;
+      }
+
+      const query = parseCommandArgs(args);
+      const { events, rawAccessDenied } = getDebugEvents(query);
+      const lines = formatEvents(events, rawAccessDenied);
+      pi.sendMessage({
+        customType: DEBUG_REPORT_TYPE,
+        content: lines.join("\n"),
+        display: true,
+        details: { events, rawAccessDenied },
+      });
+    },
+  });
+
+  pi.registerTool({
+    name: "supi_debug",
+    label: "SuPi Debug",
+    description: "Fetch recent session-local SuPi extension debug events for troubleshooting.",
+    promptSnippet:
+      "Fetch recent SuPi extension debug events when troubleshooting extension behavior.",
+    promptGuidelines: [
+      "Use supi_debug when the user asks to inspect SuPi extension failures, fallback reasons, or recent debug events.",
+      "supi_debug returns sanitized events by default; request raw data only when the user explicitly wants raw diagnostics and settings allow it.",
+    ],
+    parameters: Type.Object({
+      source: Type.Optional(Type.String({ description: "Filter by extension source, e.g. rtk" })),
+      level: Type.Optional(
+        Type.Union([
+          Type.Literal("debug"),
+          Type.Literal("info"),
+          Type.Literal("warning"),
+          Type.Literal("error"),
+        ]),
+      ),
+      category: Type.Optional(Type.String({ description: "Filter by event category" })),
+      limit: Type.Optional(Type.Number({ description: "Maximum number of events to return" })),
+      includeRaw: Type.Optional(
+        Type.Boolean({ description: "Request raw event data when settings permit it" }),
+      ),
+    }),
+    // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const config = applyDebugConfig(ctx.cwd);
+      return buildToolResult(params as DebugToolParams, config);
+    },
+  });
+}