@mrclrchtr/supi-lsp 2.0.6 → 2.2.0

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/settings/settings-schema.ts

@@ -0,0 +1,464 @@
+// Declarative settings schema for SuPi extensions.
+//
+// Replaces the imperative config-backed buildItems/persistChange contribution
+// with a declarative field descriptor model. The shared settings module owns
+// scope inheritance, source-state resolution, value rendering, persistence,
+// and Inherit/Reset-to-default actions.
+//
+// Custom fields remain for nested or unusual config; they report the same
+// source state as declarative flat fields.
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import {
+  loadSupiConfigSectionForScope,
+  removeSupiConfigKey,
+  writeSupiConfig,
+} from "../config/config.ts";
+import {
+  isSettingsContributionCollector,
+  type SettingsScope,
+  type SettingsSection,
+  SUPI_SETTINGS_COLLECT_EVENT,
+} from "./settings-registry.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+/** Where the current effective value comes from. */
+export type ValueSource = "project" | "global" | "default";
+
+/** Structured notification fired to afterPersist. */
+export interface SettingsPersistedChange {
+  scope: SettingsScope;
+  cwd: string;
+  /** The config key that was mutated. */
+  fieldKey: string;
+  /** What happened: set an explicit value or deleted the scoped key. */
+  action: "set" | "delete";
+  /** The value written (only present for "set"). */
+  storedValue?: unknown;
+  /** The effective value after the save (merging defaults ← global ← project). */
+  effectiveValue: unknown;
+  /** Where the effective value now comes from. */
+  effectiveSource: ValueSource;
+}
+
+/** Helpers passed to custom-field persist handlers. */
+export interface ConfigHelpers {
+  set(key: string, value: unknown): void;
+  unset(key: string): void;
+}
+
+// ── Field actions ─────────────────────────────────────────────────────────
+
+/** A user-initiated action on a settings row. */
+export type SettingsFieldAction =
+  | { kind: "set"; value: string }
+  | { kind: "inherit" }
+  | { kind: "resetToDefault" };
+
+// ── Field descriptors ─────────────────────────────────────────────────────
+
+interface BaseField {
+  /** Config key in the section (e.g. "enabled", "severity"). */
+  key: string;
+  /** Display label. */
+  label: string;
+  /** Optional description shown when the row is selected. */
+  description?: string;
+}
+
+/** Boolean on/off toggle. */
+export interface BoolField extends BaseField {
+  kind: "boolean";
+}
+
+/** Enumeration of string choices (cycle via Space). */
+export interface EnumField extends BaseField {
+  kind: "enum";
+  values: string[];
+}
+
+/** Integer field; with discrete values for cycling or absent for free input. */
+export interface NumberField extends BaseField {
+  kind: "number";
+  /** Discrete choices for Space cycling; absent = free text input. */
+  values?: string[];
+}
+
+/** Comma-separated string list. */
+export interface StringListField extends BaseField {
+  kind: "stringList";
+}
+
+/** Model picker backed by the scoped model set. */
+export interface ModelPickerField extends BaseField {
+  kind: "modelPicker";
+}
+
+/**
+ * Custom / escape-hatch field for nested config or unusual controls.
+ *
+ * The field must report its display value and source so the settings UI
+ * can render consistent source badges and action menus.
+ */
+export interface CustomField extends BaseField {
+  kind: "custom";
+  /**
+   * Return the display value and its source for the given scope.
+   * Called on every scope toggle and after persistence.
+   */
+  resolve: (
+    scope: SettingsScope,
+    cwd: string,
+    ctx?: ExtensionContext,
+  ) => {
+    /** Human-readable value text, without the source badge. */
+    displayValue: string;
+    /** Value used to prefill editors/pickers; defaults to displayValue when omitted. */
+    editValue?: string;
+    source: ValueSource;
+    /** When scope is "project" and source is "project", the source after deletion. */
+    inheritanceSource?: "global" | "default";
+  };
+  /**
+   * Submenu component factory for editing (Enter).
+   * Receives the resolved display value and a done callback; return a pi-tui
+   * Component-like object. Undefined means Enter opens the action menu only.
+   */
+  submenu?: (
+    currentValue: string,
+    done: (selectedValue?: string) => void,
+    scope: SettingsScope,
+    cwd: string,
+    ctx?: ExtensionContext,
+  ) => Component;
+  /**
+   * Persist handler called on set/inherit/resetToDefault actions.
+   * Required for custom fields so they can write their nested config.
+   */
+  persist: (
+    scope: SettingsScope,
+    cwd: string,
+    action: SettingsFieldAction,
+    helpers: ConfigHelpers,
+  ) => void;
+}
+
+/** Union of all supported field kinds. */
+export type SettingsField =
+  | BoolField
+  | EnumField
+  | NumberField
+  | StringListField
+  | ModelPickerField
+  | CustomField;
+
+// ── Contribution options ──────────────────────────────────────────────────
+
+/** Options for registerDeclarativeSettings. */
+export interface DeclarativeSettingsOptions {
+  /** Stable contribution identifier — e.g. "lsp", "claude-md". */
+  id: string;
+  /** Human-readable label shown in the UI. */
+  label: string;
+  /** SuPi config section name — e.g. "lsp", "claude-md". */
+  section: string;
+  /** Package-default config values (indexable by field key). */
+  defaults: Record<string, unknown>;
+  /** Declarative field descriptors. */
+  fields: SettingsField[];
+  /** Optional live runtime sync after successful persistence. */
+  afterPersist?: (change: SettingsPersistedChange) => void;
+  /** Optional home directory for config resolution (testing). */
+  homeDir?: string;
+}
+
+// ── Scoped section interface ─────────────────────────────────────────────
+
+/** Resolved value for one field in one scope. */
+export interface ScopedFieldValue {
+  /** The field descriptor. */
+  field: SettingsField;
+  /** Display value string shown in the row (with source badge). */
+  displayValue: string;
+  /** Value used to prefill editors/pickers, without the source badge. */
+  editValue: string;
+  /** Where the value comes from. */
+  source: ValueSource;
+  /**
+   * When scope is "project" and source is "project", the source that would
+   * apply after deleting the project override ("global" or "default").
+   * Undefined otherwise.
+   */
+  inheritanceSource?: "global" | "default";
+}
+
+// ── Source resolution ─────────────────────────────────────────────────────
+
+/**
+ * Resolve the effective value and source for a flat key.
+ *
+ * For project scope: checks project → global → defaults.
+ * For global scope: checks global → defaults.
+ */
+// biome-ignore lint/complexity/useMaxParams: resolveValue needs all scope/source parameters for honest multi-tier resolution
+export function resolveValue<T extends Record<string, unknown>>(
+  key: string,
+  defaults: T,
+  projectRaw: Record<string, unknown> | null,
+  globalRaw: Record<string, unknown> | null,
+  scope: SettingsScope,
+): { value: unknown; source: ValueSource } {
+  // Check direct scope first
+  const directRaw = scope === "project" ? projectRaw : globalRaw;
+  if (directRaw && key in directRaw) {
+    return { value: directRaw[key], source: scope };
+  }
+
+  // For project scope, check global
+  if (scope === "project" && globalRaw && key in globalRaw) {
+    return { value: globalRaw[key], source: "global" };
+  }
+
+  // Fall back to defaults
+  return { value: defaults[key], source: "default" };
+}
+
+// ── Value formatting ──────────────────────────────────────────────────────
+
+/** Format a value for display. */
+export function formatValue(value: unknown, field: SettingsField): string {
+  switch (field.kind) {
+    case "boolean":
+      return value ? "on" : "off";
+    case "number":
+      return String(value ?? "");
+    case "stringList": {
+      const arr = Array.isArray(value) ? value : [];
+      return arr.length > 0 ? arr.map(String).join(", ") : "none";
+    }
+    default:
+      return String(value ?? "");
+  }
+}
+
+/** Build source-badged display text. */
+export function sourceBadge(displayValue: string, source: ValueSource): string {
+  switch (source) {
+    case "project":
+      return `${displayValue} (project)`;
+    case "global":
+      return `${displayValue} (global)`;
+    case "default":
+      return `${displayValue} (default)`;
+  }
+}
+
+/** Format the value used to prefill editors and compare concrete choices. */
+export function formatEditValue(value: unknown, field: SettingsField): string {
+  if (field.kind === "stringList") {
+    const arr = Array.isArray(value) ? value : [];
+    return arr.map(String).join(", ");
+  }
+  return formatValue(value, field);
+}
+
+// ── Persistence helpers ───────────────────────────────────────────────────
+
+function createConfigHelpers(
+  section: string,
+  scope: SettingsScope,
+  cwd: string,
+  homeDir?: string,
+): ConfigHelpers {
+  return {
+    set: (key: string, val: unknown) => {
+      writeSupiConfig({ section, scope, cwd }, { [key]: val }, { homeDir });
+    },
+    unset: (key: string) => {
+      removeSupiConfigKey({ section, scope, cwd }, key, { homeDir });
+    },
+  };
+}
+
+// ── Scoped section factory ────────────────────────────────────────────────
+
+interface NotifyAfterPersistInput {
+  options: DeclarativeSettingsOptions;
+  field: SettingsField;
+  scope: SettingsScope;
+  cwd: string;
+  action: SettingsFieldAction;
+  storedValue: unknown;
+  ctx?: ExtensionContext;
+}
+
+function notifyAfterPersist(input: NotifyAfterPersistInput): void {
+  const { options, field, scope, cwd, action, storedValue, ctx } = input;
+  if (!options.afterPersist) return;
+
+  let effectiveValue: unknown;
+  let effectiveSource: ValueSource;
+
+  if (field.kind === "custom") {
+    const resolved = field.resolve(scope, cwd, ctx);
+    effectiveValue = resolved.editValue ?? resolved.displayValue;
+    effectiveSource = resolved.source;
+  } else {
+    const projectRaw = loadSupiConfigSectionForScope(options.section, cwd, {
+      scope: "project",
+      homeDir: options.homeDir,
+    });
+    const globalRaw = loadSupiConfigSectionForScope(options.section, cwd, {
+      scope: "global",
+      homeDir: options.homeDir,
+    });
+    const resolved = resolveValue(field.key, options.defaults, projectRaw, globalRaw, scope);
+    effectiveValue = resolved.value;
+    effectiveSource = resolved.source;
+  }
+
+  const change: SettingsPersistedChange = {
+    scope,
+    cwd,
+    fieldKey: field.key,
+    action: action.kind === "set" ? "set" : "delete",
+    effectiveValue,
+    effectiveSource,
+  };
+  if (action.kind === "set") change.storedValue = storedValue;
+  options.afterPersist(change);
+}
+
+function toDeclarativeSection(options: DeclarativeSettingsOptions): SettingsSection {
+  const defaults = options.defaults as Record<string, unknown>;
+  return {
+    id: options.id,
+    label: options.label,
+    loadValues: (scope, cwd, ctx) => {
+      // Load raw section data for both scopes (no defaults)
+      const projectRaw = loadSupiConfigSectionForScope(options.section, cwd, {
+        scope: "project",
+        homeDir: options.homeDir,
+      });
+      const globalRaw = loadSupiConfigSectionForScope(options.section, cwd, {
+        scope: "global",
+        homeDir: options.homeDir,
+      });
+
+      // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: natural discriminator on field kind and source
+      return options.fields.map((field) => {
+        if (field.kind === "custom") {
+          const resolved = field.resolve(scope, cwd, ctx);
+          return {
+            field,
+            displayValue: resolved.displayValue
+              ? sourceBadge(resolved.displayValue, resolved.source)
+              : "",
+            editValue: resolved.editValue ?? resolved.displayValue,
+            source: resolved.source,
+            inheritanceSource: resolved.inheritanceSource,
+          };
+        }
+
+        const { value, source } = resolveValue(field.key, defaults, projectRaw, globalRaw, scope);
+        const displayValue = formatValue(value, field);
+
+        // Compute inheritanceSource for project-scope overrides
+        let inheritanceSource: "global" | "default" | undefined;
+        if (scope === "project" && source === "project") {
+          inheritanceSource = globalRaw && field.key in globalRaw ? "global" : "default";
+        }
+
+        return {
+          field,
+          displayValue: sourceBadge(displayValue, source),
+          editValue: formatEditValue(value, field),
+          source,
+          inheritanceSource,
+        };
+      });
+    },
+    // biome-ignore lint/complexity/useMaxParams: SettingsSection action handlers receive scope, cwd, field, action, and optional context
+    handleAction: (scope, cwd, fieldKey, action, ctx) => {
+      const field = options.fields.find((f) => f.key === fieldKey);
+      if (!field) return;
+
+      const section = options.section;
+      const helpers = createConfigHelpers(section, scope, cwd, options.homeDir);
+      let storedValue: unknown;
+
+      if (field.kind === "custom") {
+        field.persist(scope, cwd, action, helpers);
+        storedValue = action.kind === "set" ? action.value : undefined;
+        notifyAfterPersist({ options, field, scope, cwd, action, storedValue, ctx });
+        return;
+      }
+
+      switch (action.kind) {
+        case "set": {
+          storedValue = parseTypedValue(action.value, field);
+          helpers.set(field.key, storedValue);
+          break;
+        }
+        case "inherit":
+        case "resetToDefault": {
+          helpers.unset(field.key);
+          break;
+        }
+      }
+
+      notifyAfterPersist({ options, field, scope, cwd, action, storedValue, ctx });
+    },
+  };
+}
+
+// ── Typed value parsing ───────────────────────────────────────────────────
+
+/** Parse a user-supplied string value into the typed config value for the field. */
+export function parseTypedValue(value: string, field: SettingsField): unknown {
+  switch (field.kind) {
+    case "boolean":
+      return value === "on";
+    case "number": {
+      if (!/^[1-9]\d*$/.test(value.trim())) {
+        throw new Error(
+          `Invalid value for "${field.label}": "${value}". Enter a positive integer.`,
+        );
+      }
+      return Number.parseInt(value, 10);
+    }
+    case "stringList":
+      return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    default:
+      return value;
+  }
+}
+
+// ── Registration ──────────────────────────────────────────────────────────
+
+/**
+ * Register a declarative settings contribution for `/supi-settings`.
+ *
+ * Contributions are collected through PI's process-local event bus. Call this
+ * during the extension factory function, not in async session handlers.
+ */
+export function registerDeclarativeSettings(
+  pi: ExtensionAPI,
+  options: DeclarativeSettingsOptions,
+): void {
+  const section = toDeclarativeSection(options);
+  const dispose = pi.events.on(SUPI_SETTINGS_COLLECT_EVENT, (collector) => {
+    if (isSettingsContributionCollector(collector)) {
+      collector.add(section);
+    }
+  });
+
+  pi.on("session_shutdown", () => {
+    dispose();
+  });
+}

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/settings/settings-submenus.ts

@@ -0,0 +1,124 @@
+// Submenu helpers for SuPi settings.
+//
+// Reusable pi-tui submenu components shared across the settings overlay
+// and available to extensions for custom settings controls.
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  Input,
+  Key,
+  matchesKey,
+  type SelectItem,
+  SelectList,
+  Text,
+} from "@earendil-works/pi-tui";
+import { getSelectableModels } from "../model-selection.ts";
+
+/**
+ * Creates a pi-tui Input-backed submenu component with enter-to-confirm
+ * and escape-to-cancel handling.
+ */
+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;
+    },
+  };
+}
+
+/**
+ * Creates a model picker submenu for settings with "disabled" as the first option.
+ */
+export function createModelPickerSubmenu(
+  currentValue: string,
+  done: (selectedValue?: string) => void,
+  ctx?: ExtensionContext,
+): {
+  render: (width: number) => string[];
+  invalidate: () => void;
+  handleInput: (data: string) => boolean;
+} {
+  const items = buildModelItems(ctx);
+  const initialIndex =
+    currentValue === "disabled"
+      ? 0
+      : Math.max(
+          0,
+          items.findIndex((item) => item.value === currentValue),
+        );
+
+  const container = new Container();
+  container.addChild(new Text("  Select model", 1, 0));
+  container.addChild(new Text("", 1, 0));
+
+  const selectList = new SelectList(items, Math.min(items.length, 15), {
+    selectedPrefix: (t) => `› ${t}`,
+    selectedText: (t) => t,
+    description: (t) => t,
+    scrollInfo: (t) => t,
+    noMatch: (t) => t,
+  });
+  if (initialIndex >= 0) selectList.setSelectedIndex(initialIndex);
+  selectList.onSelect = (item) => done(item.value);
+  selectList.onCancel = () => done();
+
+  container.addChild(selectList);
+  container.addChild(new Text("  ↑↓ navigate • enter select • esc cancel", 1, 0));
+
+  return {
+    render: (width: number) => container.render(width),
+    invalidate: () => container.invalidate(),
+    handleInput: (data: string) => {
+      selectList.handleInput(data);
+      return true;
+    },
+  };
+}
+
+/** Build selectable model items with "disabled" as the first option. */
+function buildModelItems(ctx?: ExtensionContext): SelectItem[] {
+  const items: SelectItem[] = [
+    { value: "disabled", label: "disabled", description: "No model selected" },
+  ];
+  if (!ctx) return items;
+  const models = getSelectableModels(ctx);
+  for (const model of models) {
+    const suffix = model.isCurrent ? "  [current]" : "";
+    items.push({
+      value: model.canonicalId,
+      label: `${model.canonicalId}${suffix}`,
+      description: model.label !== model.canonicalId ? model.label : undefined,
+    });
+  }
+  return items;
+}