@mrclrchtr/supi-settings 4.9.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/package.json

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

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

@@ -46,13 +46,21 @@ export interface DebugTimer {
  * 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);
-  const startedAt = now();
+  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 => {
@@ -65,30 +73,35 @@ export function startDebugTimer(options: DebugTimerOptions = {}): DebugTimer {
   return {
     enabled: true,
     mark(phase) {
-      if (finished) return;
-      markAt(phase, now());
+      if (finished || failed) return;
+      try {
+        markAt(phase, now());
+      } catch {
+        failed = true;
+      }
     },
     finish(input, finalPhase) {
-      if (finished) return null;
-      if (!isDebugRegistryEnabled()) {
-        finished = true;
+      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 completedAt = now();
-      if (finalPhase) markAt(finalPhase, completedAt);
-      finished = true;
-      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 },
-      });
     },
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-settings",
-  "version": "4.9.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.9.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,