@aliou/pi-utils-settings 0.0.1 → 0.2.0

package/config-loader.ts

@@ -1,17 +1,30 @@
 /**
  * Generic JSON config loader for pi extensions.
  *
- * Loads config from two files (global + project), deep-merges with defaults,
- * and optionally applies versioned migrations.
+ * Loads config from configurable scopes (global, local, memory),
+ * deep-merges with defaults, and optionally applies versioned migrations.
  *
  * Global:  ~/.pi/agent/extensions/{name}.json
- * Project: .pi/extensions/{name}.json
+ * Local:   {project}/.pi/extensions/{name}.json (walks up to find .pi)
+ * Memory:  In-memory only, not persisted, resets on reload
+ *
+ * Merge priority (lowest to highest): defaults -> global -> local -> memory
  */
 
+import { existsSync, statSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { getAgentDir } from "@mariozechner/pi-coding-agent";
 
+/**
+ * Available configuration scopes.
+ * - global: User-wide settings in ~/.pi/agent/extensions/
+ * - local: Project-specific settings in {project}/.pi/extensions/
+ * - memory: Ephemeral settings, not persisted, reset on reload
+ */
+export type Scope = "global" | "local" | "memory";
+
 /**
  * A migration that transforms a config from one version to another.
  * Migrations are applied in order during load(). If any migration
@@ -36,76 +49,127 @@ export interface Migration<TConfig> {
  */
 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>;
+  getRawConfig(scope: Scope): TConfig | null;
+  hasScope(scope: Scope): boolean;
+  hasConfig(scope: Scope): boolean;
+  getEnabledScopes(): Scope[];
+  save(scope: Scope, config: TConfig): Promise<void>;
+}
+
+/**
+ * Walk up from cwd to find the project root (.pi directory).
+ * Stops at home directory.
+ * Returns the path to .pi/extensions/{name}.json, or null if no .pi found.
+ */
+function findLocalConfigPath(extensionName: string): string | null {
+  let dir = process.cwd();
+  const home = homedir();
+
+  while (true) {
+    const piDir = resolve(dir, ".pi");
+    if (existsSync(piDir) && statSync(piDir).isDirectory()) {
+      return resolve(piDir, `extensions/${extensionName}.json`);
+    }
+
+    // Stop at home directory
+    if (dir === home) break;
+
+    const parent = resolve(dir, "..");
+    // Stop if we can't go higher
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return null;
 }
 
 export class ConfigLoader<TConfig extends object, TResolved extends object>
   implements ConfigStore<TConfig, TResolved>
 {
   private globalConfig: TConfig | null = null;
-  private projectConfig: TConfig | null = null;
+  private localConfig: TConfig | null = null;
+  private memoryConfig: TConfig | null = null;
   private resolved: TResolved | null = null;
 
-  private readonly globalPath: string;
-  private readonly projectPath: string;
+  private readonly scopes: Scope[];
+  private readonly globalPath: string | null;
+  private readonly localPath: string | null;
   private readonly defaults: TResolved;
   private readonly migrations: Migration<TConfig>[];
   private readonly afterMerge?: (
     resolved: TResolved,
     global: TConfig | null,
-    project: TConfig | null,
+    local: TConfig | null,
+    memory: TConfig | null,
   ) => TResolved;
 
   constructor(
     extensionName: string,
     defaults: TResolved,
     options?: {
+      /**
+       * Enabled scopes. Default: ["global", "local"]
+       * Merge priority (lowest to highest): defaults -> global -> local -> memory
+       */
+      scopes?: Scope[];
       migrations?: Migration<TConfig>[];
       /**
-       * Post-merge hook. Called after deep merge with both raw configs.
+       * Post-merge hook. Called after deep merge with all 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,
+        local: TConfig | null,
+        memory: TConfig | null,
       ) => TResolved;
     },
   ) {
-    this.globalPath = resolve(
-      getAgentDir(),
-      `extensions/${extensionName}.json`,
-    );
-    this.projectPath = resolve(
-      process.cwd(),
-      `.pi/extensions/${extensionName}.json`,
-    );
+    this.scopes = options?.scopes ?? ["global", "local"];
     this.defaults = defaults;
     this.migrations = options?.migrations ?? [];
     this.afterMerge = options?.afterMerge;
+
+    // Set up paths based on enabled scopes
+    this.globalPath = this.scopes.includes("global")
+      ? resolve(getAgentDir(), `extensions/${extensionName}.json`)
+      : null;
+
+    this.localPath = this.scopes.includes("local")
+      ? findLocalConfigPath(extensionName)
+      : null;
   }
 
   /**
    * Load (or reload) config from disk. Applies migrations if needed.
    * Must be called before getConfig() or getRawConfig().
+   *
+   * Note: Memory config is reset to null on reload (ephemeral).
    */
   async load(): Promise<void> {
-    this.globalConfig = await this.readFile(this.globalPath);
-    this.projectConfig = await this.readFile(this.projectPath);
+    // Load from disk
+    this.globalConfig = this.globalPath
+      ? await this.readFile(this.globalPath)
+      : null;
+    this.localConfig = this.localPath
+      ? await this.readFile(this.localPath)
+      : null;
 
-    if (this.globalConfig) {
+    // Reset memory on reload (ephemeral)
+    this.memoryConfig = null;
+
+    // Apply migrations to disk configs
+    if (this.globalConfig && this.globalPath) {
       this.globalConfig = await this.applyMigrations(
         this.globalConfig,
         this.globalPath,
       );
     }
-    if (this.projectConfig) {
-      this.projectConfig = await this.applyMigrations(
-        this.projectConfig,
-        this.projectPath,
+    if (this.localConfig && this.localPath) {
+      this.localConfig = await this.applyMigrations(
+        this.localConfig,
+        this.localPath,
       );
     }
 
@@ -119,21 +183,60 @@ export class ConfigLoader<TConfig extends object, TResolved extends object>
     return this.resolved;
   }
 
-  getRawConfig(scope: "global" | "project"): TConfig | null {
-    return scope === "global" ? this.globalConfig : this.projectConfig;
+  getRawConfig(scope: Scope): TConfig | null {
+    switch (scope) {
+      case "global":
+        return this.globalConfig;
+      case "local":
+        return this.localConfig;
+      case "memory":
+        return this.memoryConfig;
+    }
   }
 
-  hasConfig(scope: "global" | "project"): boolean {
-    return scope === "global"
-      ? this.globalConfig !== null
-      : this.projectConfig !== null;
+  hasScope(scope: Scope): boolean {
+    return this.scopes.includes(scope);
   }
 
-  /** Save config and reload all state. */
-  async save(scope: "global" | "project", config: TConfig): Promise<void> {
-    const path = scope === "global" ? this.globalPath : this.projectPath;
+  hasConfig(scope: Scope): boolean {
+    if (!this.hasScope(scope)) return false;
+    return this.getRawConfig(scope) !== null;
+  }
+
+  getEnabledScopes(): Scope[] {
+    return [...this.scopes];
+  }
+
+  /** Save config and reload state (except memory which just updates in place). */
+  async save(scope: Scope, config: TConfig): Promise<void> {
+    if (!this.hasScope(scope)) {
+      throw new Error(`Scope "${scope}" is not enabled`);
+    }
+
+    if (scope === "memory") {
+      // Memory is ephemeral, just store in place and re-merge
+      this.memoryConfig = config;
+      this.resolved = this.merge();
+      return;
+    }
+
+    const path = scope === "global" ? this.globalPath : this.localPath;
+    if (!path) {
+      throw new Error(`No path configured for scope "${scope}"`);
+    }
+
     await this.writeFile(path, config);
-    await this.load();
+
+    // Reload disk configs but preserve memory
+    const savedMemory = this.memoryConfig;
+    this.globalConfig = this.globalPath
+      ? await this.readFile(this.globalPath)
+      : null;
+    this.localConfig = this.localPath
+      ? await this.readFile(this.localPath)
+      : null;
+    this.memoryConfig = savedMemory;
+    this.resolved = this.merge();
   }
 
   // --- Internal ---
@@ -161,7 +264,7 @@ export class ConfigLoader<TConfig extends object, TResolved extends object>
       try {
         await this.writeFile(filePath, current);
       } catch {
-        // Save failed — use migrated version in memory only.
+        // Save failed - use migrated version in memory only.
       }
     }
 
@@ -170,10 +273,19 @@ export class ConfigLoader<TConfig extends object, TResolved extends object>
 
   private merge(): TResolved {
     const merged = structuredClone(this.defaults);
+
+    // Merge in priority order: global -> local -> memory
     if (this.globalConfig) this.deepMerge(merged, this.globalConfig);
-    if (this.projectConfig) this.deepMerge(merged, this.projectConfig);
+    if (this.localConfig) this.deepMerge(merged, this.localConfig);
+    if (this.memoryConfig) this.deepMerge(merged, this.memoryConfig);
+
     if (this.afterMerge) {
-      return this.afterMerge(merged, this.globalConfig, this.projectConfig);
+      return this.afterMerge(
+        merged,
+        this.globalConfig,
+        this.localConfig,
+        this.memoryConfig,
+      );
     }
     return merged;
   }

package/index.ts

@@ -22,6 +22,7 @@ export {
   ConfigLoader,
   type ConfigStore,
   type Migration,
+  type Scope,
 } from "./config-loader";
 export {
   displayToStorageValue,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-utils-settings",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "type": "module",
   "private": false,
   "license": "MIT",

package/settings-command.ts

@@ -1,7 +1,7 @@
 /**
  * Settings command registration helper.
  *
- * Creates a /{name}:settings command with Local/Global tabs.
+ * Creates a /{name}:settings command with tabs for each enabled scope.
  * Changes are tracked in memory. Ctrl+S saves, Esc exits without saving.
  */
 
@@ -12,10 +12,19 @@ import {
   SectionedSettings,
   type SettingsSection,
 } from "./components/sectioned-settings";
-import type { ConfigStore } from "./config-loader";
-import { displayToStorageValue, setNestedValue } from "./helpers";
-
-type Tab = "local" | "global";
+import type { ConfigStore, Scope } from "./config-loader";
+import {
+  displayToStorageValue,
+  getNestedValue,
+  setNestedValue,
+} from "./helpers";
+
+/** Display labels for each scope */
+const SCOPE_LABELS: Record<Scope, string> = {
+  global: "Global",
+  local: "Local",
+  memory: "Memory",
+};
 
 export interface SettingsCommandOptions<
   TConfig extends object,
@@ -36,11 +45,18 @@ export interface SettingsCommandOptions<
    * 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.
+   *
+   * For memory scope, tabConfig is null when no overrides exist yet.
+   * Use resolved values as display values in that case.
    */
   buildSections: (
     tabConfig: TConfig | null,
     resolved: TResolved,
-    ctx: { setDraft: (config: TConfig) => void },
+    ctx: {
+      setDraft: (config: TConfig) => void;
+      scope: Scope;
+      isInherited: (path: string) => boolean;
+    },
   ) => SettingsSection[];
   /**
    * Custom change handler. Receives the setting ID, new display value,
@@ -100,7 +116,7 @@ export function registerSettingsCommand<
   } = options;
   const description =
     options.commandDescription ??
-    `Configure ${commandName.split(":")[0]} (local/global)`;
+    `Configure ${commandName.split(":")[0]} settings`;
   const extensionLabel = commandName.split(":")[0] ?? title;
 
   pi.registerCommand(commandName, {
@@ -108,34 +124,50 @@ export function registerSettingsCommand<
     handler: async (_args, ctx) => {
       if (!ctx.hasUI) return;
 
-      let activeTab: Tab = configStore.hasConfig("project")
-        ? "local"
-        : "global";
+      const enabledScopes = configStore.getEnabledScopes();
+      if (enabledScopes.length === 0) {
+        ctx.ui.notify("No scopes configured", "error");
+        return;
+      }
+
+      // Default to first scope with existing config, else first enabled scope
+      // Safe: we check enabledScopes.length > 0 above
+      let activeScope: Scope =
+        enabledScopes.find((s) => configStore.hasConfig(s)) ??
+        (enabledScopes[0] as Scope);
 
       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,
-        };
+        // Per-scope draft configs. null = no changes from disk/memory.
+        const drafts: Partial<Record<Scope, TConfig | null>> = {};
+        for (const scope of enabledScopes) {
+          drafts[scope] = null;
+        }
 
         // --- Helpers ---
 
-        function tabScope(): "global" | "project" {
-          return activeTab === "local" ? "project" : "global";
+        /** Get the effective config for the active scope (draft or stored). */
+        function getTabConfig(): TConfig | null {
+          return drafts[activeScope] ?? configStore.getRawConfig(activeScope);
         }
 
-        /** Get the effective config for the active tab (draft or disk). */
-        function getTabConfig(): TConfig | null {
-          return drafts[activeTab] ?? configStore.getRawConfig(tabScope());
+        /**
+         * For memory scope: check if a path has a value in memory config.
+         * If not, it's inherited from lower-priority scopes.
+         */
+        function isInherited(path: string): boolean {
+          if (activeScope !== "memory") return false;
+          const memoryConfig =
+            drafts.memory ?? configStore.getRawConfig("memory");
+          if (!memoryConfig) return true; // No memory config = all inherited
+          return getNestedValue(memoryConfig, path) === undefined;
         }
 
         function isDirty(): boolean {
-          return drafts.local !== null || drafts.global !== null;
+          return enabledScopes.some((scope) => drafts[scope] !== null);
         }
 
         function getSections(): SettingsSection[] {
@@ -143,8 +175,10 @@ export function registerSettingsCommand<
           const resolved = configStore.getConfig();
           currentSections = buildSections(tabConfig, resolved, {
             setDraft: (config) => {
-              drafts[activeTab] = config;
+              drafts[activeScope] = config;
             },
+            scope: activeScope,
+            isInherited,
           });
           return currentSections;
         }
@@ -154,13 +188,13 @@ export function registerSettingsCommand<
           tui.requestRender();
         }
 
-        function buildSettingsComponent(tab: Tab): SectionedSettings {
+        function buildSettingsComponent(scope: Scope): SectionedSettings {
           return new SectionedSettings(
             getSections(),
             15,
             settingsTheme,
             (id, newValue) => {
-              handleChange(tab, id, newValue);
+              handleChange(scope, id, newValue);
             },
             () => done(undefined),
             { enableSearch: true, hintSuffix: "Ctrl+S to save" },
@@ -169,14 +203,23 @@ export function registerSettingsCommand<
 
         // --- Change handler (in-memory only) ---
 
-        function handleChange(tab: Tab, id: string, newValue: string): void {
+        function handleChange(
+          scope: Scope,
+          id: string,
+          newValue: string,
+        ): void {
           // Submenu items handle their own saving.
           if (isSubmenuItem(currentSections, id)) {
             refresh();
             return;
           }
 
-          const current = getTabConfig();
+          // For memory scope with no existing config, start from merged config
+          let current = getTabConfig();
+          if (scope === "memory" && current === null) {
+            current = configStore.getConfig() as unknown as TConfig;
+          }
+
           const handler = onSettingChange ?? defaultChangeHandler;
           const updated = handler(
             id,
@@ -186,7 +229,7 @@ export function registerSettingsCommand<
           if (!updated) return;
 
           // Store in draft, don't write to disk yet.
-          drafts[tab] = updated;
+          drafts[scope] = updated;
           tui.requestRender();
         }
 
@@ -195,25 +238,27 @@ export function registerSettingsCommand<
         async function save(): Promise<void> {
           let saved = false;
 
-          for (const tab of ["local", "global"] as const) {
-            const draft = drafts[tab];
+          for (const scope of enabledScopes) {
+            const draft = drafts[scope];
             if (!draft) continue;
 
-            const scope = tab === "local" ? "project" : "global";
             try {
               await configStore.save(scope, draft);
-              drafts[tab] = null;
+              drafts[scope] = null;
               saved = true;
             } catch (error) {
-              ctx.ui.notify(`Failed to save ${tab}: ${error}`, "error");
+              ctx.ui.notify(
+                `Failed to save ${SCOPE_LABELS[scope]}: ${error}`,
+                "error",
+              );
             }
           }
 
           if (saved) {
             ctx.ui.notify(`${extensionLabel}: saved`, "info");
             if (onSave) await onSave();
-            // Rebuild with fresh disk data.
-            settings = buildSettingsComponent(activeTab);
+            // Rebuild with fresh data.
+            settings = buildSettingsComponent(activeScope);
           }
 
           tui.requestRender();
@@ -222,30 +267,37 @@ export function registerSettingsCommand<
         // --- 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}`, ""];
+          // Single scope = no tabs needed
+          if (enabledScopes.length === 1) {
+            return [""];
+          }
+
+          const tabLabels = enabledScopes.map((scope) => {
+            const label = SCOPE_LABELS[scope];
+            const dirtyMark = drafts[scope] ? " *" : "";
+            const fullLabel = ` ${label}${dirtyMark} `;
+
+            if (scope === activeScope) {
+              return theme.bg("selectedBg", theme.fg("accent", fullLabel));
+            }
+            return theme.fg("dim", fullLabel);
+          });
+
+          return ["", `  ${tabLabels.join("  ")}`, ""];
         }
 
         function handleTabSwitch(data: string): boolean {
+          // Single scope = no tab switching
+          if (enabledScopes.length <= 1) return false;
+
           if (matchesKey(data, Key.tab) || matchesKey(data, Key.shift("tab"))) {
-            activeTab = activeTab === "local" ? "global" : "local";
-            settings = buildSettingsComponent(activeTab);
+            const currentIndex = enabledScopes.indexOf(activeScope);
+            const direction = matchesKey(data, Key.shift("tab")) ? -1 : 1;
+            const nextIndex =
+              (currentIndex + direction + enabledScopes.length) %
+              enabledScopes.length;
+            activeScope = enabledScopes[nextIndex] as Scope;
+            settings = buildSettingsComponent(activeScope);
             tui.requestRender();
             return true;
           }
@@ -254,7 +306,7 @@ export function registerSettingsCommand<
 
         // --- Init ---
 
-        settings = buildSettingsComponent(activeTab);
+        settings = buildSettingsComponent(activeScope);
 
         return {
           render(width: number) {