@aliou/pi-utils-settings 0.0.1

package/README.md

@@ -0,0 +1,152 @@
+# @aliou/pi-utils-settings
+
+Shared settings infrastructure for [pi](https://github.com/mariozechner/pi-coding-agent) extensions. Provides config loading, a settings UI command with Local/Global tabs, and reusable TUI components.
+
+This is a utility library, not a pi extension. It is meant to be used as a dependency by extensions that need a settings UI or JSON config management.
+
+## Install
+
+```bash
+pnpm add @aliou/pi-utils-settings
+```
+
+## API
+
+### ConfigLoader
+
+Generic JSON config loader with global + project scopes, deep merge, and versioned migrations.
+
+```typescript
+import { ConfigLoader, type Migration } from "@aliou/pi-utils-settings";
+
+interface MyConfig {
+  features?: { darkMode?: boolean };
+}
+
+interface ResolvedConfig {
+  features: { darkMode: boolean };
+}
+
+const migrations: Migration<MyConfig>[] = [
+  {
+    name: "v1-upgrade",
+    shouldRun: (config) => !config.features,
+    run: (config) => ({ ...config, features: {} }),
+  },
+];
+
+const configLoader = new ConfigLoader<MyConfig, ResolvedConfig>(
+  "my-extension", // reads ~/.pi/agent/extensions/my-extension.json + .pi/extensions/my-extension.json
+  { features: { darkMode: false } }, // defaults
+  { migrations },
+);
+
+await configLoader.load();
+const config = configLoader.getConfig(); // ResolvedConfig (defaults merged with global + project)
+```
+
+An optional `afterMerge` hook runs after the deep merge for logic that can't be expressed as a simple merge (e.g., one field replacing another):
+
+```typescript
+new ConfigLoader("my-ext", defaults, {
+  afterMerge: (resolved, global, project) => {
+    if (project?.customField) {
+      resolved.derivedField = project.customField;
+    }
+    return resolved;
+  },
+});
+```
+
+### registerSettingsCommand
+
+Creates a `/name:settings` command with Local/Global tabs, draft-based editing, and Ctrl+S to save.
+
+All changes (boolean toggles, enum cycling, submenu edits) are held in memory as drafts. Nothing is written to disk until the user presses Ctrl+S. Esc exits without saving. Dirty tabs show a `*` marker.
+
+```typescript
+import { registerSettingsCommand, type SettingsSection } from "@aliou/pi-utils-settings";
+
+registerSettingsCommand<MyConfig, ResolvedConfig>(pi, {
+  commandName: "my-ext:settings",
+  title: "My Extension Settings",
+  configStore: configLoader, // implements ConfigStore interface
+  buildSections: (tabConfig, resolved, { setDraft }) => [
+    {
+      label: "General",
+      items: [
+        {
+          id: "features.darkMode",
+          label: "Dark mode",
+          description: "Enable dark mode",
+          currentValue: (tabConfig?.features?.darkMode ?? resolved.features.darkMode) ? "on" : "off",
+          values: ["on", "off"],
+        },
+      ],
+    },
+  ],
+});
+```
+
+### Submenu support
+
+Items can open submenus by providing a `submenu` factory. Use `setDraft` inside submenu `onSave` to keep changes in the draft (same save model as simple values):
+
+```typescript
+import { ArrayEditor, setNestedValue } from "@aliou/pi-utils-settings";
+
+{
+  id: "tags",
+  label: "Tags",
+  currentValue: `${tags.length} items`,
+  submenu: (_val, done) => {
+    let latest = [...tags];
+    return new ArrayEditor({
+      label: "Tags",
+      items: [...tags],
+      theme: getSettingsListTheme(),
+      onSave: (items) => {
+        latest = items;
+        const updated = structuredClone(tabConfig ?? {}) as MyConfig;
+        setNestedValue(updated, "tags", items);
+        setDraft(updated);
+      },
+      onDone: () => done(`${latest.length} items`),
+    });
+  },
+}
+```
+
+### ConfigStore interface
+
+Extensions with custom config loaders can implement `ConfigStore` directly instead of using `ConfigLoader`:
+
+```typescript
+interface ConfigStore<TConfig, TResolved> {
+  getConfig(): TResolved;
+  getRawConfig(scope: "global" | "project"): TConfig | null;
+  hasConfig(scope: "global" | "project"): boolean;
+  save(scope: "global" | "project", config: TConfig): Promise<void>;
+}
+```
+
+### Components
+
+- **SectionedSettings**: Grouped settings list with search filtering and cursor preservation on update.
+- **ArrayEditor**: String array editor with add/remove/reorder.
+
+### Helpers
+
+- `setNestedValue(obj, "a.b.c", value)`: Set a deeply nested value by dot-separated path.
+- `getNestedValue(obj, "a.b.c")`: Get a deeply nested value by dot-separated path.
+- `displayToStorageValue(id, displayValue)`: Convert display values (`"enabled"/"disabled"`, `"on"/"off"`) to storage values (`true/false`).
+
+## Exports
+
+```typescript
+export { ConfigLoader, type ConfigStore, type Migration } from "./config-loader";
+export { registerSettingsCommand, type SettingsCommandOptions } from "./settings-command";
+export { SectionedSettings, type SectionedSettingsOptions, type SettingsSection } from "./components/sectioned-settings";
+export { ArrayEditor, type ArrayEditorOptions } from "./components/array-editor";
+export { setNestedValue, getNestedValue, displayToStorageValue } from "./helpers";
+```

package/components/array-editor.ts

@@ -0,0 +1,213 @@
+import type { Component, SettingsListTheme } from "@mariozechner/pi-tui";
+import {
+  Input,
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+} from "@mariozechner/pi-tui";
+
+/**
+ * A submenu component for editing string arrays inside a SettingsList.
+ *
+ * Modes:
+ * - list: navigate items, delete with 'd', add with 'a', edit with 'e'/Enter
+ * - add: text input for new item, confirm with Enter, cancel with Escape
+ * - edit: text input pre-filled with current value, Enter saves, Escape cancels
+ */
+
+export interface ArrayEditorOptions {
+  label: string;
+  items: string[];
+  theme: SettingsListTheme;
+  onSave: (items: string[]) => void;
+  onDone: () => void;
+  /** Max visible items before scrolling */
+  maxVisible?: number;
+}
+
+export class ArrayEditor implements Component {
+  private items: string[];
+  private label: string;
+  private theme: SettingsListTheme;
+  private onSave: (items: string[]) => void;
+  private onDone: () => void;
+  private selectedIndex = 0;
+  private maxVisible: number;
+  private mode: "list" | "add" | "edit" = "list";
+  private input: Input;
+  private editIndex = -1;
+
+  constructor(options: ArrayEditorOptions) {
+    this.items = [...options.items];
+    this.label = options.label;
+    this.theme = options.theme;
+    this.onSave = options.onSave;
+    this.onDone = options.onDone;
+    this.maxVisible = options.maxVisible ?? 10;
+    this.input = new Input();
+    this.input.onSubmit = (value: string) => {
+      if (this.mode === "edit") {
+        this.submitEdit(value);
+      } else {
+        this.submitAdd(value);
+      }
+    };
+    this.input.onEscape = () => {
+      this.mode = "list";
+      this.editIndex = -1;
+    };
+  }
+
+  private submitAdd(value: string) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      this.mode = "list";
+      return;
+    }
+    this.items.push(trimmed);
+    this.selectedIndex = this.items.length - 1;
+    this.save();
+    this.mode = "list";
+    this.input.setValue("");
+  }
+
+  private submitEdit(value: string) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      // Empty value = cancel edit
+      this.mode = "list";
+      this.editIndex = -1;
+      return;
+    }
+    this.items[this.editIndex] = trimmed;
+    this.save();
+    this.mode = "list";
+    this.editIndex = -1;
+    this.input.setValue("");
+  }
+
+  private deleteSelected() {
+    if (this.items.length === 0) return;
+    this.items.splice(this.selectedIndex, 1);
+    if (this.selectedIndex >= this.items.length) {
+      this.selectedIndex = Math.max(0, this.items.length - 1);
+    }
+    this.save();
+  }
+
+  private startEdit() {
+    if (this.items.length === 0) return;
+    this.editIndex = this.selectedIndex;
+    this.mode = "edit";
+    this.input.setValue(this.items[this.selectedIndex] as string);
+  }
+
+  private save() {
+    this.onSave([...this.items]);
+  }
+
+  invalidate() {}
+
+  render(width: number): string[] {
+    const lines: string[] = [];
+
+    // Header
+    lines.push(this.theme.label(` ${this.label}`, true));
+    lines.push("");
+
+    if (this.mode === "add" || this.mode === "edit") {
+      return [...lines, ...this.renderInputMode(width)];
+    }
+
+    return [...lines, ...this.renderListMode(width)];
+  }
+
+  private renderListMode(width: number): string[] {
+    const lines: string[] = [];
+
+    if (this.items.length === 0) {
+      lines.push(this.theme.hint("  (empty)"));
+    } else {
+      const startIndex = Math.max(
+        0,
+        Math.min(
+          this.selectedIndex - Math.floor(this.maxVisible / 2),
+          this.items.length - this.maxVisible,
+        ),
+      );
+      const endIndex = Math.min(
+        startIndex + this.maxVisible,
+        this.items.length,
+      );
+
+      for (let i = startIndex; i < endIndex; i++) {
+        const item = this.items[i];
+        if (!item) continue;
+        const isSelected = i === this.selectedIndex;
+        const prefix = isSelected ? this.theme.cursor : "  ";
+        const prefixWidth = visibleWidth(prefix);
+        const maxItemWidth = width - prefixWidth - 2;
+        const text = this.theme.value(
+          truncateToWidth(item, maxItemWidth, ""),
+          isSelected,
+        );
+        lines.push(prefix + text);
+      }
+
+      if (startIndex > 0 || endIndex < this.items.length) {
+        lines.push(
+          this.theme.hint(`  (${this.selectedIndex + 1}/${this.items.length})`),
+        );
+      }
+    }
+
+    lines.push("");
+    lines.push(
+      this.theme.hint("  a: add · e/Enter: edit · d: delete · Esc: back"),
+    );
+
+    return lines;
+  }
+
+  private renderInputMode(width: number): string[] {
+    const lines: string[] = [];
+    const label = this.mode === "edit" ? "  Edit item:" : "  New item:";
+    lines.push(this.theme.hint(label));
+    lines.push(`  ${this.input.render(width - 4).join("")}`);
+    lines.push("");
+    lines.push(this.theme.hint("  Enter: confirm · Esc: cancel"));
+    return lines;
+  }
+
+  handleInput(data: string) {
+    if (this.mode === "add" || this.mode === "edit") {
+      this.input.handleInput(data);
+      return;
+    }
+
+    // List mode
+    if (matchesKey(data, Key.up) || data === "k") {
+      if (this.items.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === 0
+          ? this.items.length - 1
+          : this.selectedIndex - 1;
+    } else if (matchesKey(data, Key.down) || data === "j") {
+      if (this.items.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === this.items.length - 1
+          ? 0
+          : this.selectedIndex + 1;
+    } else if (data === "a" || data === "A") {
+      this.mode = "add";
+      this.input.setValue("");
+    } else if (data === "e" || data === "E" || matchesKey(data, Key.enter)) {
+      this.startEdit();
+    } else if (data === "d" || data === "D") {
+      this.deleteSelected();
+    } else if (matchesKey(data, Key.escape)) {
+      this.onDone();
+    }
+  }
+}

package/components/sectioned-settings.ts

@@ -0,0 +1,379 @@
+import type { Component } from "@mariozechner/pi-tui";
+import {
+  Input,
+  Key,
+  matchesKey,
+  type SettingItem,
+  type SettingsListTheme,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from "@mariozechner/pi-tui";
+
+/**
+ * A sectioned settings list. Items are grouped under section headers.
+ * Cursor skips section headers and only lands on items.
+ *
+ * Supports the same SettingItem interface as pi-tui's SettingsList,
+ * including value cycling and submenus.
+ */
+
+export interface SettingsSection {
+  label: string;
+  items: SettingItem[];
+}
+
+export interface SectionedSettingsOptions {
+  enableSearch?: boolean;
+  /** Extra text appended to the hint line (e.g. "Ctrl+S to save"). */
+  hintSuffix?: string;
+}
+
+interface FlatEntry {
+  type: "section" | "item";
+  sectionLabel?: string;
+  item?: SettingItem;
+}
+
+export class SectionedSettings implements Component {
+  private sections: SettingsSection[];
+  private flatEntries: FlatEntry[];
+  private filteredEntries: FlatEntry[];
+  private theme: SettingsListTheme;
+  private selectedIndex: number; // index into selectable items only
+  private maxVisible: number;
+  private onChange: (id: string, newValue: string) => void;
+  private onCancel: () => void;
+  private searchInput?: Input;
+  private searchEnabled: boolean;
+  private hintSuffix: string;
+  private submenuComponent: Component | null = null;
+  private submenuItemIndex: number | null = null;
+
+  constructor(
+    sections: SettingsSection[],
+    maxVisible: number,
+    theme: SettingsListTheme,
+    onChange: (id: string, newValue: string) => void,
+    onCancel: () => void,
+    options: SectionedSettingsOptions = {},
+  ) {
+    this.sections = sections;
+    this.maxVisible = maxVisible;
+    this.theme = theme;
+    this.onChange = onChange;
+    this.onCancel = onCancel;
+    this.searchEnabled = options.enableSearch ?? false;
+    this.hintSuffix = options.hintSuffix ?? "";
+    this.selectedIndex = 0;
+
+    if (this.searchEnabled) {
+      this.searchInput = new Input();
+    }
+
+    this.flatEntries = this.buildFlatEntries(sections);
+    this.filteredEntries = this.flatEntries;
+  }
+
+  private buildFlatEntries(sections: SettingsSection[]): FlatEntry[] {
+    const entries: FlatEntry[] = [];
+    for (const section of sections) {
+      entries.push({ type: "section", sectionLabel: section.label });
+      for (const item of section.items) {
+        entries.push({ type: "item", item });
+      }
+    }
+    return entries;
+  }
+
+  private getSelectableItems(): SettingItem[] {
+    return this.filteredEntries
+      .filter((e) => e.type === "item" && e.item)
+      .map((e) => e.item as SettingItem);
+  }
+
+  /**
+   * Replace all sections while preserving the cursor position.
+   * The cursor is restored by matching the previously selected item's ID.
+   * If the item no longer exists, the index is clamped to the valid range.
+   *
+   * Use this instead of creating a new SectionedSettings instance when
+   * only values or item counts change (e.g., after saving a setting).
+   */
+  updateSections(sections: SettingsSection[]): void {
+    const currentId = this.getSelectableItems()[this.selectedIndex]?.id;
+
+    this.sections = sections;
+    this.flatEntries = this.buildFlatEntries(sections);
+    this.filterEntries(this.searchInput?.getValue() ?? "");
+
+    // Restore cursor by item ID.
+    if (currentId) {
+      const items = this.getSelectableItems();
+      const idx = items.findIndex((i) => i.id === currentId);
+      if (idx >= 0) {
+        this.selectedIndex = idx;
+        return;
+      }
+    }
+
+    // Fallback: clamp to valid range.
+    const count = this.getSelectableItems().length;
+    this.selectedIndex = Math.min(this.selectedIndex, Math.max(0, count - 1));
+  }
+
+  updateValue(id: string, newValue: string): void {
+    for (const section of this.sections) {
+      const item = section.items.find((i) => i.id === id);
+      if (item) {
+        item.currentValue = newValue;
+        return;
+      }
+    }
+  }
+
+  /** Returns true when a submenu is open (caller should not intercept input). */
+  hasActiveSubmenu(): boolean {
+    return this.submenuComponent !== null;
+  }
+
+  invalidate(): void {
+    this.submenuComponent?.invalidate?.();
+  }
+
+  render(width: number): string[] {
+    if (this.submenuComponent) {
+      return this.submenuComponent.render(width);
+    }
+    return this.renderMainList(width);
+  }
+
+  private renderMainList(width: number): string[] {
+    const lines: string[] = [];
+
+    if (this.searchEnabled && this.searchInput) {
+      lines.push(...this.searchInput.render(width));
+      lines.push("");
+    }
+
+    const allItems = this.getSelectableItems();
+
+    if (allItems.length === 0) {
+      lines.push(
+        this.theme.hint(
+          this.searchEnabled
+            ? "  No matching settings"
+            : "  No settings available",
+        ),
+      );
+      this.addHintLine(lines);
+      return lines;
+    }
+
+    // Calculate max label width for alignment
+    const maxLabelWidth = Math.min(
+      30,
+      Math.max(...allItems.map((item) => visibleWidth(item.label))),
+    );
+
+    // Build visible entries with their "selectable index"
+    let selectableIdx = -1;
+    const rendered: Array<{
+      line: string;
+      isSelected: boolean;
+      description?: string;
+    }> = [];
+
+    for (const entry of this.filteredEntries) {
+      if (entry.type === "section") {
+        // Section header - add blank line before (except first)
+        if (rendered.length > 0) {
+          rendered.push({ line: "", isSelected: false });
+        }
+        rendered.push({
+          line: this.theme.hint(`  ${entry.sectionLabel}`),
+          isSelected: false,
+        });
+        continue;
+      }
+
+      const item = entry.item;
+      if (!item) continue;
+
+      selectableIdx++;
+      const isSelected = selectableIdx === this.selectedIndex;
+      const prefix = isSelected ? this.theme.cursor : "  ";
+      const prefixWidth = visibleWidth(prefix);
+
+      const labelPadded =
+        item.label +
+        " ".repeat(Math.max(0, maxLabelWidth - visibleWidth(item.label)));
+      const labelText = this.theme.label(labelPadded, isSelected);
+
+      const separator = "  ";
+      const usedWidth = prefixWidth + maxLabelWidth + visibleWidth(separator);
+      const valueMaxWidth = width - usedWidth - 2;
+      const valueText = this.theme.value(
+        truncateToWidth(item.currentValue, valueMaxWidth, ""),
+        isSelected,
+      );
+
+      rendered.push({
+        line: prefix + labelText + separator + valueText,
+        isSelected,
+        description: isSelected ? item.description : undefined,
+      });
+    }
+
+    // Scrolling: find the rendered index of the selected item
+    const selectedRenderedIdx = rendered.findIndex((r) => r.isSelected);
+    const totalLines = rendered.length;
+    const startLine = Math.max(
+      0,
+      Math.min(
+        selectedRenderedIdx - Math.floor(this.maxVisible / 2),
+        totalLines - this.maxVisible,
+      ),
+    );
+    const endLine = Math.min(startLine + this.maxVisible, totalLines);
+
+    for (let i = startLine; i < endLine; i++) {
+      const r = rendered[i];
+      if (r) lines.push(r.line);
+    }
+
+    // Scroll indicator
+    if (startLine > 0 || endLine < totalLines) {
+      lines.push(
+        this.theme.hint(`  (${this.selectedIndex + 1}/${allItems.length})`),
+      );
+    }
+
+    // Description for selected item
+    const selectedItem = allItems[this.selectedIndex];
+    if (selectedItem?.description) {
+      lines.push("");
+      const wrappedDesc = wrapTextWithAnsi(selectedItem.description, width - 4);
+      for (const line of wrappedDesc) {
+        lines.push(this.theme.description(`  ${line}`));
+      }
+    }
+
+    this.addHintLine(lines);
+    return lines;
+  }
+
+  handleInput(data: string): void {
+    if (this.submenuComponent) {
+      this.submenuComponent.handleInput?.(data);
+      return;
+    }
+
+    const items = this.getSelectableItems();
+
+    if (matchesKey(data, Key.up)) {
+      if (items.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === 0 ? items.length - 1 : this.selectedIndex - 1;
+    } else if (matchesKey(data, Key.down)) {
+      if (items.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === items.length - 1 ? 0 : this.selectedIndex + 1;
+    } else if (matchesKey(data, Key.enter) || data === " ") {
+      this.activateItem();
+    } else if (matchesKey(data, Key.escape)) {
+      this.onCancel();
+    } else if (this.searchEnabled && this.searchInput) {
+      const sanitized = data.replace(/ /g, "");
+      if (!sanitized) return;
+      this.searchInput.handleInput(sanitized);
+      this.applyFilter(this.searchInput.getValue());
+    }
+  }
+
+  private activateItem(): void {
+    const items = this.getSelectableItems();
+    const item = items[this.selectedIndex];
+    if (!item) return;
+
+    if (item.submenu) {
+      this.submenuItemIndex = this.selectedIndex;
+      this.submenuComponent = item.submenu(
+        item.currentValue,
+        (selectedValue) => {
+          if (selectedValue !== undefined) {
+            item.currentValue = selectedValue;
+            this.onChange(item.id, selectedValue);
+          }
+          this.closeSubmenu();
+        },
+      );
+    } else if (item.values && item.values.length > 0) {
+      const currentIndex = item.values.indexOf(item.currentValue);
+      const nextIndex = (currentIndex + 1) % item.values.length;
+      const newValue = item.values[nextIndex] as string;
+      item.currentValue = newValue;
+      this.onChange(item.id, newValue);
+    }
+  }
+
+  private closeSubmenu(): void {
+    this.submenuComponent = null;
+    if (this.submenuItemIndex !== null) {
+      this.selectedIndex = this.submenuItemIndex;
+      this.submenuItemIndex = null;
+    }
+  }
+
+  /**
+   * Apply search filter to entries without resetting the cursor.
+   * Used by updateSections() to preserve selection.
+   */
+  private filterEntries(query: string): void {
+    if (!query) {
+      this.filteredEntries = this.flatEntries;
+      return;
+    }
+
+    const filtered: FlatEntry[] = [];
+    let currentSection: FlatEntry | null = null;
+    let sectionHasMatch = false;
+
+    for (const entry of this.flatEntries) {
+      if (entry.type === "section") {
+        currentSection = entry;
+        sectionHasMatch = false;
+        continue;
+      }
+
+      if (entry.item) {
+        const label = entry.item.label.toLowerCase();
+        const q = query.toLowerCase();
+        if (label.includes(q)) {
+          if (currentSection && !sectionHasMatch) {
+            filtered.push(currentSection);
+            sectionHasMatch = true;
+          }
+          filtered.push(entry);
+        }
+      }
+    }
+
+    this.filteredEntries = filtered;
+  }
+
+  /** Apply search filter and reset cursor to the first item. */
+  private applyFilter(query: string): void {
+    this.filterEntries(query);
+    this.selectedIndex = 0;
+  }
+
+  private addHintLine(lines: string[]): void {
+    const suffix = this.hintSuffix ? ` \u00B7 ${this.hintSuffix}` : "";
+    const base = this.searchEnabled
+      ? "  Type to search \u00B7 Enter/Space to change \u00B7 Esc to close"
+      : "  Enter/Space to change \u00B7 Esc to close";
+    lines.push("");
+    lines.push(this.theme.hint(base + suffix));
+  }
+}

package/config-loader.ts

@@ -0,0 +1,212 @@
+/**
+ * Generic JSON config loader for pi extensions.
+ *
+ * Loads config from two files (global + project), deep-merges with defaults,
+ * and optionally applies versioned migrations.
+ *
+ * Global:  ~/.pi/agent/extensions/{name}.json
+ * Project: .pi/extensions/{name}.json
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+
+/**
+ * A migration that transforms a config from one version to another.
+ * Migrations are applied in order during load(). If any migration
+ * returns a modified config, the result is saved back to disk.
+ */
+export interface Migration<TConfig> {
+  /** Name for logging on failure. */
+  name: string;
+  /** Return true if this migration should run on the given config. */
+  shouldRun: (config: TConfig) => boolean;
+  /**
+   * Transform the config. Receives the file path for backup/logging.
+   * Return the migrated config.
+   */
+  run: (config: TConfig, filePath: string) => Promise<TConfig> | TConfig;
+}
+
+/**
+ * Interface for settings storage, used by registerSettingsCommand.
+ * ConfigLoader implements this. Extensions with custom loaders can
+ * implement this interface directly.
+ */
+export interface ConfigStore<TConfig extends object, TResolved extends object> {
+  getConfig(): TResolved;
+  getRawConfig(scope: "global" | "project"): TConfig | null;
+  hasConfig(scope: "global" | "project"): boolean;
+  save(scope: "global" | "project", config: TConfig): Promise<void>;
+}
+
+export class ConfigLoader<TConfig extends object, TResolved extends object>
+  implements ConfigStore<TConfig, TResolved>
+{
+  private globalConfig: TConfig | null = null;
+  private projectConfig: TConfig | null = null;
+  private resolved: TResolved | null = null;
+
+  private readonly globalPath: string;
+  private readonly projectPath: string;
+  private readonly defaults: TResolved;
+  private readonly migrations: Migration<TConfig>[];
+  private readonly afterMerge?: (
+    resolved: TResolved,
+    global: TConfig | null,
+    project: TConfig | null,
+  ) => TResolved;
+
+  constructor(
+    extensionName: string,
+    defaults: TResolved,
+    options?: {
+      migrations?: Migration<TConfig>[];
+      /**
+       * Post-merge hook. Called after deep merge with both raw configs.
+       * Use for logic that can't be expressed as a simple merge
+       * (e.g., one field replacing another).
+       */
+      afterMerge?: (
+        resolved: TResolved,
+        global: TConfig | null,
+        project: TConfig | null,
+      ) => TResolved;
+    },
+  ) {
+    this.globalPath = resolve(
+      getAgentDir(),
+      `extensions/${extensionName}.json`,
+    );
+    this.projectPath = resolve(
+      process.cwd(),
+      `.pi/extensions/${extensionName}.json`,
+    );
+    this.defaults = defaults;
+    this.migrations = options?.migrations ?? [];
+    this.afterMerge = options?.afterMerge;
+  }
+
+  /**
+   * Load (or reload) config from disk. Applies migrations if needed.
+   * Must be called before getConfig() or getRawConfig().
+   */
+  async load(): Promise<void> {
+    this.globalConfig = await this.readFile(this.globalPath);
+    this.projectConfig = await this.readFile(this.projectPath);
+
+    if (this.globalConfig) {
+      this.globalConfig = await this.applyMigrations(
+        this.globalConfig,
+        this.globalPath,
+      );
+    }
+    if (this.projectConfig) {
+      this.projectConfig = await this.applyMigrations(
+        this.projectConfig,
+        this.projectPath,
+      );
+    }
+
+    this.resolved = this.merge();
+  }
+
+  getConfig(): TResolved {
+    if (!this.resolved) {
+      throw new Error("Config not loaded. Call load() first.");
+    }
+    return this.resolved;
+  }
+
+  getRawConfig(scope: "global" | "project"): TConfig | null {
+    return scope === "global" ? this.globalConfig : this.projectConfig;
+  }
+
+  hasConfig(scope: "global" | "project"): boolean {
+    return scope === "global"
+      ? this.globalConfig !== null
+      : this.projectConfig !== null;
+  }
+
+  /** Save config and reload all state. */
+  async save(scope: "global" | "project", config: TConfig): Promise<void> {
+    const path = scope === "global" ? this.globalPath : this.projectPath;
+    await this.writeFile(path, config);
+    await this.load();
+  }
+
+  // --- Internal ---
+
+  private async applyMigrations(
+    config: TConfig,
+    filePath: string,
+  ): Promise<TConfig> {
+    let current = config;
+    let changed = false;
+
+    for (const migration of this.migrations) {
+      if (!migration.shouldRun(current)) continue;
+      try {
+        current = await migration.run(current, filePath);
+        changed = true;
+      } catch (error) {
+        console.error(
+          `[settings] Migration "${migration.name}" failed for ${filePath}: ${error}`,
+        );
+      }
+    }
+
+    if (changed) {
+      try {
+        await this.writeFile(filePath, current);
+      } catch {
+        // Save failed — use migrated version in memory only.
+      }
+    }
+
+    return current;
+  }
+
+  private merge(): TResolved {
+    const merged = structuredClone(this.defaults);
+    if (this.globalConfig) this.deepMerge(merged, this.globalConfig);
+    if (this.projectConfig) this.deepMerge(merged, this.projectConfig);
+    if (this.afterMerge) {
+      return this.afterMerge(merged, this.globalConfig, this.projectConfig);
+    }
+    return merged;
+  }
+
+  private deepMerge(target: object, source: object): void {
+    const t = target as Record<string, unknown>;
+    const s = source as Record<string, unknown>;
+    for (const key in s) {
+      if (s[key] === undefined) continue;
+      if (
+        typeof s[key] === "object" &&
+        !Array.isArray(s[key]) &&
+        s[key] !== null
+      ) {
+        if (!t[key] || typeof t[key] !== "object") t[key] = {};
+        this.deepMerge(t[key] as object, s[key] as object);
+      } else {
+        t[key] = s[key];
+      }
+    }
+  }
+
+  private async readFile(path: string): Promise<TConfig | null> {
+    try {
+      const content = await readFile(path, "utf-8");
+      return JSON.parse(content) as TConfig;
+    } catch {
+      return null;
+    }
+  }
+
+  private async writeFile(path: string, config: TConfig): Promise<void> {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+  }
+}

package/helpers.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared helpers for settings management.
+ */
+
+/**
+ * Set a deeply nested value on an object using a dotted path.
+ * Creates intermediate objects as needed.
+ *
+ * Example: setNestedValue(obj, "features.debug", true)
+ * sets obj.features.debug = true, creating obj.features if needed.
+ */
+export function setNestedValue(
+  obj: object,
+  path: string,
+  value: unknown,
+): void {
+  const parts = path.split(".");
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path traversal
+  let target: any = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const key = parts[i] as string;
+    if (!target[key] || typeof target[key] !== "object") target[key] = {};
+    target = target[key];
+  }
+  target[parts[parts.length - 1] as string] = value;
+}
+
+/**
+ * Get a deeply nested value from an object using a dotted path.
+ * Returns undefined if any intermediate key is missing.
+ */
+export function getNestedValue(obj: object, path: string): unknown {
+  const parts = path.split(".");
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic path traversal
+  let target: any = obj;
+  for (const part of parts) {
+    if (target == null) return undefined;
+    target = target[part];
+  }
+  return target;
+}
+
+/**
+ * Map a UI display value to its storage representation.
+ *
+ * "enabled" / "on"  -> true
+ * "disabled" / "off" -> false
+ * anything else      -> the string as-is (for enums like "pnpm")
+ */
+export function displayToStorageValue(displayValue: string): unknown {
+  switch (displayValue) {
+    case "enabled":
+    case "on":
+      return true;
+    case "disabled":
+    case "off":
+      return false;
+    default:
+      return displayValue;
+  }
+}

package/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @aliou/pi-utils-settings
+ *
+ * Shared settings infrastructure for pi extensions:
+ * - ConfigLoader: load/save/merge JSON configs from global + project paths
+ * - registerSettingsCommand: create a settings command with Local/Global tabs
+ * - SectionedSettings: sectioned settings list component
+ * - ArrayEditor: string array editor submenu component
+ * - Helpers: nested value access, display-to-storage value mapping
+ */
+
+export {
+  ArrayEditor,
+  type ArrayEditorOptions,
+} from "./components/array-editor";
+export {
+  SectionedSettings,
+  type SectionedSettingsOptions,
+  type SettingsSection,
+} from "./components/sectioned-settings";
+export {
+  ConfigLoader,
+  type ConfigStore,
+  type Migration,
+} from "./config-loader";
+export {
+  displayToStorageValue,
+  getNestedValue,
+  setNestedValue,
+} from "./helpers";
+export {
+  registerSettingsCommand,
+  type SettingsCommandOptions,
+} from "./settings-command";

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@aliou/pi-utils-settings",
+  "version": "0.0.1",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "description": "Shared settings UI and config loader for pi extensions",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aliou/pi-extensions",
+    "directory": "packages/settings"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "*.ts",
+    "components",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": ">=0.51.0"
+  }
+}

package/settings-command.ts

@@ -0,0 +1,285 @@
+/**
+ * Settings command registration helper.
+ *
+ * Creates a /{name}:settings command with Local/Global tabs.
+ * Changes are tracked in memory. Ctrl+S saves, Esc exits without saving.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { getSettingsListTheme } from "@mariozechner/pi-coding-agent";
+import { Key, matchesKey } from "@mariozechner/pi-tui";
+import {
+  SectionedSettings,
+  type SettingsSection,
+} from "./components/sectioned-settings";
+import type { ConfigStore } from "./config-loader";
+import { displayToStorageValue, setNestedValue } from "./helpers";
+
+type Tab = "local" | "global";
+
+export interface SettingsCommandOptions<
+  TConfig extends object,
+  TResolved extends object,
+> {
+  /** Command name, e.g. "toolchain:settings" */
+  commandName: string;
+  /** Command description for the command palette. */
+  commandDescription?: string;
+  /** Title shown at the top of the settings UI. */
+  title: string;
+  /** Config store (ConfigLoader or custom implementation). */
+  configStore: ConfigStore<TConfig, TResolved>;
+  /**
+   * Build the sections for the current tab.
+   * Called on initial render, tab switch, and after saving.
+   *
+   * Use ctx.setDraft in submenu onSave callbacks to store changes
+   * in the draft. All changes (toggles, enums, submenus) are only
+   * persisted to disk on Ctrl+S.
+   */
+  buildSections: (
+    tabConfig: TConfig | null,
+    resolved: TResolved,
+    ctx: { setDraft: (config: TConfig) => void },
+  ) => SettingsSection[];
+  /**
+   * Custom change handler. Receives the setting ID, new display value,
+   * and a clone of the current tab config. Return the updated config,
+   * or null to skip the change.
+   *
+   * If not provided, the default handler maps boolean display values
+   * (enabled/disabled, on/off) to true/false and sets via dotted path.
+   * Enum strings (e.g. "pnpm") are stored as-is.
+   */
+  onSettingChange?: (
+    id: string,
+    newValue: string,
+    config: TConfig,
+  ) => TConfig | null;
+  /**
+   * Called after save succeeds. Use this to reload runtime state
+   * that was captured at extension init time.
+   */
+  onSave?: () => void | Promise<void>;
+}
+
+function defaultChangeHandler<TConfig extends object>(
+  id: string,
+  newValue: string,
+  config: TConfig,
+): TConfig {
+  const updated = structuredClone(config);
+  setNestedValue(updated, id, displayToStorageValue(newValue));
+  return updated;
+}
+
+/**
+ * Find whether an item in the given sections has a submenu.
+ * Used to distinguish value cycling (track draft) from submenu close (refresh only).
+ */
+function isSubmenuItem(sections: SettingsSection[], id: string): boolean {
+  for (const section of sections) {
+    for (const item of section.items) {
+      if (item.id === id && item.submenu) return true;
+    }
+  }
+  return false;
+}
+
+export function registerSettingsCommand<
+  TConfig extends object,
+  TResolved extends object,
+>(pi: ExtensionAPI, options: SettingsCommandOptions<TConfig, TResolved>): void {
+  const {
+    commandName,
+    title,
+    configStore,
+    buildSections,
+    onSettingChange,
+    onSave,
+  } = options;
+  const description =
+    options.commandDescription ??
+    `Configure ${commandName.split(":")[0]} (local/global)`;
+  const extensionLabel = commandName.split(":")[0] ?? title;
+
+  pi.registerCommand(commandName, {
+    description,
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+
+      let activeTab: Tab = configStore.hasConfig("project")
+        ? "local"
+        : "global";
+
+      await ctx.ui.custom((tui, theme, _kb, done) => {
+        let settings: SectionedSettings | null = null;
+        let currentSections: SettingsSection[] = [];
+        const settingsTheme = getSettingsListTheme();
+
+        // Per-tab draft configs. null = no changes from disk.
+        const drafts: Record<Tab, TConfig | null> = {
+          local: null,
+          global: null,
+        };
+
+        // --- Helpers ---
+
+        function tabScope(): "global" | "project" {
+          return activeTab === "local" ? "project" : "global";
+        }
+
+        /** Get the effective config for the active tab (draft or disk). */
+        function getTabConfig(): TConfig | null {
+          return drafts[activeTab] ?? configStore.getRawConfig(tabScope());
+        }
+
+        function isDirty(): boolean {
+          return drafts.local !== null || drafts.global !== null;
+        }
+
+        function getSections(): SettingsSection[] {
+          const tabConfig = getTabConfig();
+          const resolved = configStore.getConfig();
+          currentSections = buildSections(tabConfig, resolved, {
+            setDraft: (config) => {
+              drafts[activeTab] = config;
+            },
+          });
+          return currentSections;
+        }
+
+        function refresh(): void {
+          settings?.updateSections(getSections());
+          tui.requestRender();
+        }
+
+        function buildSettingsComponent(tab: Tab): SectionedSettings {
+          return new SectionedSettings(
+            getSections(),
+            15,
+            settingsTheme,
+            (id, newValue) => {
+              handleChange(tab, id, newValue);
+            },
+            () => done(undefined),
+            { enableSearch: true, hintSuffix: "Ctrl+S to save" },
+          );
+        }
+
+        // --- Change handler (in-memory only) ---
+
+        function handleChange(tab: Tab, id: string, newValue: string): void {
+          // Submenu items handle their own saving.
+          if (isSubmenuItem(currentSections, id)) {
+            refresh();
+            return;
+          }
+
+          const current = getTabConfig();
+          const handler = onSettingChange ?? defaultChangeHandler;
+          const updated = handler(
+            id,
+            newValue,
+            structuredClone(current ?? ({} as TConfig)),
+          );
+          if (!updated) return;
+
+          // Store in draft, don't write to disk yet.
+          drafts[tab] = updated;
+          tui.requestRender();
+        }
+
+        // --- Save handler (Ctrl+S) ---
+
+        async function save(): Promise<void> {
+          let saved = false;
+
+          for (const tab of ["local", "global"] as const) {
+            const draft = drafts[tab];
+            if (!draft) continue;
+
+            const scope = tab === "local" ? "project" : "global";
+            try {
+              await configStore.save(scope, draft);
+              drafts[tab] = null;
+              saved = true;
+            } catch (error) {
+              ctx.ui.notify(`Failed to save ${tab}: ${error}`, "error");
+            }
+          }
+
+          if (saved) {
+            ctx.ui.notify(`${extensionLabel}: saved`, "info");
+            if (onSave) await onSave();
+            // Rebuild with fresh disk data.
+            settings = buildSettingsComponent(activeTab);
+          }
+
+          tui.requestRender();
+        }
+
+        // --- Tab rendering ---
+
+        function renderTabs(): string[] {
+          const dirtyMark = (tab: Tab) => (drafts[tab] ? " *" : "");
+
+          const localLabel =
+            activeTab === "local"
+              ? theme.bg(
+                  "selectedBg",
+                  theme.fg("accent", ` Local${dirtyMark("local")} `),
+                )
+              : theme.fg("dim", ` Local${dirtyMark("local")} `);
+          const globalLabel =
+            activeTab === "global"
+              ? theme.bg(
+                  "selectedBg",
+                  theme.fg("accent", ` Global${dirtyMark("global")} `),
+                )
+              : theme.fg("dim", ` Global${dirtyMark("global")} `);
+
+          return ["", `  ${localLabel}  ${globalLabel}`, ""];
+        }
+
+        function handleTabSwitch(data: string): boolean {
+          if (matchesKey(data, Key.tab) || matchesKey(data, Key.shift("tab"))) {
+            activeTab = activeTab === "local" ? "global" : "local";
+            settings = buildSettingsComponent(activeTab);
+            tui.requestRender();
+            return true;
+          }
+          return false;
+        }
+
+        // --- Init ---
+
+        settings = buildSettingsComponent(activeTab);
+
+        return {
+          render(width: number) {
+            const lines: string[] = [];
+            lines.push(theme.fg("accent", theme.bold(title)));
+            lines.push(...renderTabs());
+            lines.push(...(settings?.render(width) ?? []));
+            return lines;
+          },
+          invalidate() {
+            settings?.invalidate?.();
+          },
+          handleInput(data: string) {
+            // Ctrl+S: save all dirty tabs.
+            if (matchesKey(data, Key.ctrl("s"))) {
+              if (isDirty()) void save();
+              return;
+            }
+
+            if (!settings?.hasActiveSubmenu() && handleTabSwitch(data)) return;
+            settings?.handleInput?.(data);
+            tui.requestRender();
+          },
+        };
+      });
+    },
+  });
+}