@mrclrchtr/supi-settings 4.8.0 → 4.10.0

package/README.md

@@ -6,56 +6,96 @@
 
 # @mrclrchtr/supi-settings
 
-SuPi Settings adds a unified `/supi-settings` command to the [pi coding agent](https://github.com/earendil-works/pi). It gives SuPi extensions one shared TUI for project and global configuration.
+SuPi Settings is a Pi extension and a small public UI library. It adds one interactive screen for the project and global settings that loaded SuPi extensions contribute.
+
+This package is part of the SuPi release stack.
 
 ## Install
 
+Install the Pi extension:
+
 ```bash
 pi install npm:@mrclrchtr/supi-settings
 ```
 
+If Pi is open, run `/reload` after installation.
+
 For local development:
 
 ```bash
 pi install ./packages/supi-settings
 ```
 
-## What you get
+## What it adds
+
+The extension registers one slash command:
+
+- **`/supi-settings`** — open a searchable settings screen
+
+The package does not register a tool, a shortcut, or its own setting. The screen contains settings from other loaded SuPi extensions. If no extension contributes settings, Pi shows `No settings registered by SuPi extensions`.
+
+The screen is available in Pi interactive TUI mode. Print, JSON, and RPC modes do not provide this custom screen.
+
+## Use the settings screen
+
+The screen starts in project scope.
 
-After install, pi gets one new slash command:
+| Input | Action |
+|---|---|
+| Type text | Filter by section, setting, key, or displayed value |
+| Up or Down | Move through the settings |
+| Enter | Open the actions for the selected setting |
+| Space | Cycle a boolean, enum, or fixed numeric choice |
+| Tab | Switch between project and global scope |
+| Escape | Close the current menu or the settings screen |
 
-- **`/supi-settings`** — open a searchable settings screen for registered SuPi extension settings
+Each value can have a `(project)`, `(global)`, or `(default)` source badge.
 
-The screen matches Pi's `/settings` layout and groups settings by extension. It shows current values with source badges like `(project)`, `(global)`, and `(default)`. Use `Tab` to switch between **project** and **global** scopes. Row actions can set a scoped value or delete it with **Inherit** / **Reset to default**.
+In project scope, a project value overrides a global value or the package default. **Inherit from global** and **Use default** delete the project value. In global scope, **Reset to default** deletes the global value.
 
-## How it works
+Free-text, list, model, and custom settings open a matching editor or picker when the contributing module provides one.
 
-`supi-settings` is the command package for the shared settings registry in `@mrclrchtr/supi-core`.
+## Storage and boundaries
 
-Other SuPi extensions register asynchronous Settings Modules during extension startup. This package reads their source-aware snapshots, routes `set` and `unset` actions, and shows module-reported failures or reload notices. Fixed SuPi config sections use the shared config adapter; dynamic modules can own other stores without exposing them to this UI.
+Each contributing settings module owns its reads, writes, validation, refresh behavior, and notices. The screen waits for a write to finish and then reads a new snapshot. A failure in one module does not hide settings from modules that loaded successfully.
 
-If no installed SuPi extension has registered settings, `/supi-settings` reports that there are no settings to edit.
+Modules that use the standard `@mrclrchtr/supi-core` config adapter store values in:
 
-## Typical settings sections
+- global: `~/.pi/agent/supi/config.json`
+- project: `<cwd>/.pi/supi/config.json`
+
+A custom module can use a different store. SuPi Settings does not call a model or a remote service itself, but a contributed module controls its own operations. Pi extensions run with the permissions of the Pi process.
+
+## Public API
+
+Add the package as a dependency when another extension needs the reusable UI helpers:
+
+```bash
+pnpm add @mrclrchtr/supi-settings
+```
+
+Import only from the explicit API subpath:
+
+```ts
+import {
+  createInputSubmenu,
+  createModelPickerSubmenu,
+  openSettingsOverlay,
+} from "@mrclrchtr/supi-settings/api";
+```
 
-Depending on which SuPi packages are installed, the overlay may include settings for:
+The API exports:
 
-- `supi-lsp` — language-server enablement and diagnostics behavior
-- `supi-claude-md` — subdirectory `CLAUDE.md` / `AGENTS.md` discovery
-- `supi-bash-timeout` — default bash timeout injection
-- `supi-cache` — prompt-cache monitoring and history collection
-- `supi-debug` — debug event capture and retention
-- `supi-insights` — report-generation options
-- `supi-skills` — skill load and model-invocation controls
+- `openSettingsOverlay(pi, ctx)` — collect the current settings modules and open the screen.
+- `createInputSubmenu(currentValue, label, done)` — create a free-text submenu with confirm and cancel handling.
+- `createModelPickerSubmenu(currentValue, done, ctx?, options?)` — create a picker from static choices and models that match Pi's configured `enabledModels` patterns. The picker includes `disabled` by default.
 
-## Package surfaces
+The `@mrclrchtr/supi-settings/extension` subpath exports the Pi extension factory that registers `/supi-settings`.
 
-- `@mrclrchtr/supi-settings/extension` — pi extension entrypoint, registers `/supi-settings`
-- `@mrclrchtr/supi-settings/api` — settings UI and submenu helpers
+Settings modules use `registerSettings()` and the `SettingsModule` types from `@mrclrchtr/supi-core/settings`. Their `read()` and `apply()` methods are asynchronous. The screen collects the modules when the command opens.
 
 ## Source layout
 
-- `src/extension.ts` — pi extension entrypoint
-- `src/api.ts` — reusable settings UI surface
+- `src/extension.ts` — Pi extension entrypoint
+- `src/api.ts` — public UI exports
 - `src/ui/` — settings screen, scoped list, action menu, and submenus
-- `@mrclrchtr/supi-core/settings` owns the registry, schema, scope resolution, and persistence

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -48,7 +48,7 @@ Config file locations:
 ### Shared registries
 
 - context-provider registry for `/supi-context`
-- debug-event registry for producers that want shared debug capture
+- debug-event registry and monotonic phase timers for producers that want shared debug capture
 - settings registry used by `/supi-settings`
 
 ### Project and session helpers
@@ -108,5 +108,7 @@ export default function myExtension(pi: ExtensionAPI) {
 
 - `src/api.ts` — exported library surface
 - `src/config.ts` — shared config loading and writing
+- `src/debug-registry.ts` — Debug domain surface, event state, retention, redaction, listeners, and queries
+- `src/debug-timing.ts` — monotonic total and phase timers for Debug Event Producers
 - `src/settings/` — settings registry, schema, scope resolution, and persistence
 - `src/report.ts` — shared text/report rendering helpers

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.8.0",
+  "version": "4.10.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

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

@@ -4,6 +4,9 @@
 // supi-debug extension owns policy/configuration and exposes events through a
 // command/tool while this module stays dependency-free for producers.
 
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-timing.ts";
+
 export type DebugLevel = "debug" | "info" | "warning" | "error";
 export type DebugAgentAccess = "off" | "sanitized" | "raw";
 export interface DebugRegistryConfig {
@@ -180,6 +183,11 @@ 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;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-settings",
-  "version": "4.8.0",
+  "version": "4.10.0",
   "description": "One project/global settings UI for SuPi packages",
   "license": "MIT",
   "repository": {
@@ -30,7 +30,7 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "4.8.0"
+    "@mrclrchtr/supi-core": "4.10.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/ui/scoped-settings-list.ts

@@ -1,14 +1,7 @@
 // Source-aware settings list with scope actions and custom submenus.
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import {
-  Input,
-  Key,
-  matchesKey,
-  truncateToWidth,
-  visibleWidth,
-  wrapTextWithAnsi,
-} from "@earendil-works/pi-tui";
+import { Input, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { SettingsAction, SettingsModule, SettingsScope } from "@mrclrchtr/supi-core/settings";
 import type { ThemeAccessor } from "./settings-action-menu.ts";
 import {
@@ -16,8 +9,14 @@ import {
   createActionMenuComponent,
   getConcreteChoices,
 } from "./settings-action-menu.ts";
+import { renderDescriptionViewport } from "./settings-list-layout.ts";
 import { type LoadedSettingsModule, readSettingsModules } from "./settings-module-reader.ts";
-import { filterSettingsRows, rowsFromModules, type ScopedRow } from "./settings-row-model.ts";
+import {
+  filterSettingsRows,
+  maxVisibleSectionCount,
+  rowsFromModules,
+  type ScopedRow,
+} from "./settings-row-model.ts";
 import { createInputSubmenu, createModelPickerSubmenu } from "./settings-submenus.ts";
 
 interface SubmenuState {
@@ -27,7 +26,6 @@ interface SubmenuState {
     handleInput?: (data: string) => void;
   };
 }
-
 export class ScopedSettingsList {
   private modules: SettingsModule[];
   private scope: SettingsScope;
@@ -139,6 +137,7 @@ export class ScopedSettingsList {
       Math.max(...displayRows.map((row) => visibleWidth(row.field.field.label))),
     );
     let previousSection: string | undefined;
+    let visibleSectionCount = 0;
     for (let i = start; i < end; i++) {
       const row = displayRows[i];
       if (!row) continue;
@@ -146,6 +145,7 @@ export class ScopedSettingsList {
         lines.push(
           truncateToWidth(`  ${this.theme.fg("muted", this.theme.bold(row.moduleLabel))}`, width),
         );
+        visibleSectionCount++;
         previousSection = row.moduleLabel;
       }
       const isSelected = i === this.selectedIndex;
@@ -159,14 +159,16 @@ export class ScopedSettingsList {
       const valueText = this.theme.fg(isSelected ? "accent" : "muted", value);
       lines.push(truncateToWidth(`${prefix}${labelText}  ${valueText}`, width));
     }
+    const reservedSectionCount = maxVisibleSectionCount(displayRows, maxVisible);
+    for (let i = visibleSectionCount; i < reservedSectionCount; i++) lines.push("");
     if (start > 0 || end < displayRows.length) {
       lines.push(this.theme.fg("dim", `  (${this.selectedIndex + 1}/${displayRows.length})`));
     }
     const description = displayRows[this.selectedIndex]?.field.field.description;
-    if (description) {
+    if (displayRows.some((row) => row.field.field.description)) {
       lines.push("");
-      for (const line of wrapTextWithAnsi(description, Math.max(1, width - 4))) {
-        lines.push(this.theme.fg("dim", `  ${line}`));
+      for (const line of renderDescriptionViewport(description, width)) {
+        lines.push(line ? this.theme.fg("dim", `  ${line}`) : "");
       }
     }
     lines.push("");

package/src/ui/settings-list-layout.ts

@@ -0,0 +1,19 @@
+import { truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+const DESCRIPTION_VIEWPORT_HEIGHT = 4;
+
+/** Render a fixed-height description preview so selection changes do not resize the menu. */
+export function renderDescriptionViewport(
+  description: string | undefined,
+  width: number,
+): string[] {
+  const contentWidth = Math.max(1, width - 4);
+  const wrapped = description ? wrapTextWithAnsi(description, contentWidth) : [];
+  const visible = wrapped.slice(0, DESCRIPTION_VIEWPORT_HEIGHT);
+  if (wrapped.length > DESCRIPTION_VIEWPORT_HEIGHT) {
+    const lastIndex = DESCRIPTION_VIEWPORT_HEIGHT - 1;
+    visible[lastIndex] = truncateToWidth(`${visible[lastIndex] ?? ""}…`, contentWidth, "…");
+  }
+  while (visible.length < DESCRIPTION_VIEWPORT_HEIGHT) visible.push("");
+  return visible;
+}

package/src/ui/settings-row-model.ts

@@ -17,6 +17,22 @@ export function rowsFromModules(loaded: LoadedSettingsModule[]): ScopedRow[] {
   );
 }
 
+/** Return the largest section-header count for any row window of the given size. */
+export function maxVisibleSectionCount(rows: ScopedRow[], windowSize: number): number {
+  let maximum = 0;
+  for (let start = 0; start <= rows.length - windowSize; start++) {
+    let count = 0;
+    let previousSection: string | undefined;
+    for (const row of rows.slice(start, start + windowSize)) {
+      if (row.moduleLabel === previousSection) continue;
+      count++;
+      previousSection = row.moduleLabel;
+    }
+    maximum = Math.max(maximum, count);
+  }
+  return maximum;
+}
+
 export function filterSettingsRows(rows: ScopedRow[], query: string): ScopedRow[] {
   if (!query) return rows;
   const normalized = query.toLowerCase();

package/src/ui/settings-ui.ts

@@ -9,6 +9,7 @@ import { Container, Key, matchesKey, Text } from "@earendil-works/pi-tui";
 import {
   createSettingsContributionCollector,
   type SettingsCollectionDiagnostic,
+  type SettingsModule,
   type SettingsScope,
   SUPI_SETTINGS_COLLECT_EVENT,
 } from "@mrclrchtr/supi-core/settings";
@@ -37,14 +38,22 @@ function latestStatus(diagnostics: SettingsCollectionDiagnostic[]): OverlayStatu
   return latest ? { kind: latest.kind, message: latest.message } : undefined;
 }
 
+/** Keep the skill catalog after the smaller fixed settings sections. */
+function orderSettingsModules(modules: SettingsModule[]): SettingsModule[] {
+  const skills = modules.find((module) => module.id === "skills");
+  if (!skills) return modules;
+  return [...modules.filter((module) => module.id !== skills.id), skills];
+}
+
 export async function openSettingsOverlay(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
   const collection = collectSettingsModules(pi);
-  if (collection.modules.length === 0) {
+  const modules = orderSettingsModules(collection.modules);
+  if (modules.length === 0) {
     ctx.ui.notify("No settings registered by SuPi extensions", "info");
     return;
   }
 
-  const initial = await readSettingsModules(collection.modules, {
+  const initial = await readSettingsModules(modules, {
     scope: "project",
     cwd: ctx.cwd,
     ctx,
@@ -61,7 +70,7 @@ export async function openSettingsOverlay(pi: ExtensionAPI, ctx: ExtensionContex
 
     const container = new Container();
     const scopedList = new ScopedSettingsList(
-      collection.modules,
+      modules,
       initial.loaded,
       state.scope,
       state.cwd,