avtc-pi-settings-ui 1.0.0

package/src/schema.ts

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Schema-driven settings type definitions.
+ *
+ * A setting is fully described by a single `SettingSchema` entry.
+ * The generic infrastructure auto-generates UI, persistence, normalization,
+ * and validation from the schema alone.
+ */
+
+/** Setting type hint — drives validation and display formatting.
+ *  A bare type-id `string`: the 7 built-in TypeDefinition ids (`number`, `duration`, `compact-threshold`,
+ *  `string`, `boolean`, `model`, `thinking-level`) plus any custom type registered via `registerTypeDefinition`. */
+export type SettingType = string;
+
+/** The value slot of a preset — the raw typed value a preset selects. */
+export type PresetValue = string | number | boolean | null;
+
+/** Ordered preset pair: display label paired with its raw typed value. */
+export type PresetPair = readonly [string, PresetValue];
+
+/** A preset source element: a full [label, value] pair, OR a bare value. Bare values are
+ *  auto-paired at the resolution seam — a bare string → type-aware [s, parse(s)] (duration
+ *  "30m"→1800000, string→identity); a bare number/boolean/null → [String(v), v]. Mixed arrays
+ *  ([ ["off", null], "5m", "10m"]) are allowed. */
+export type PresetElement = PresetPair | PresetValue;
+
+/** Source of presets for a setting: a static element array OR a resolver function.
+ *  Declared at two levels — a type-def default (`TypeDefinition.presets`) overridable by the
+ *  setting's own `presets` (authoritative). The static array is resolved at the gate; the
+ *  resolver is resolved once at modal-open (the gate cannot call a resolver, so it treats a
+ *  resolver as no presets at load). */
+export type PresetsSource =
+  | readonly PresetElement[]
+  | (() => readonly PresetElement[] | Promise<readonly PresetElement[]>);
+
+/** Schema for a single setting. */
+export interface SettingSchema<T = unknown> {
+  /** Unique key (e.g. "codeReviewLoops") */
+  id: string;
+  /** Display label ("Code review loops") */
+  label: string;
+  /** Shown when selected in settings UI */
+  description?: string;
+  /** Validation/display hint */
+  type: SettingType;
+  /** Inclusive numeric floor (for `number`/`duration` types whose `TypeDefinition.bounded` is true). */
+  min?: number;
+  /** Inclusive numeric ceiling (for bounded numeric/duration types). */
+  max?: number;
+  /** Default value. Use `undefined` for intentionally absent defaults. */
+  defaultValue: T;
+  /**
+   * Presets for this setting. When set, this OVERRIDES the type-def's default presets
+   * (replace, not merge). When absent, the type-def's default presets (if any) apply.
+   * Either level may be a static pair array (resolved at the gate) or a resolver function
+   * (resolved once at modal-open). Order is the display order — immune to JS integer-index
+   * key reordering. The library derives labels, internal value strings, the label→value map,
+   * AND the null display label (the label of the pair whose value is null) from this in one
+   * atomic pass.
+   */
+  presets?: PresetsSource;
+  /** Backward-compat field names (old keys that map to this setting's canonical id). */
+  aliases?: string[];
+  /** Legacy value aliases: old value → current raw value. Resolved before value-based matching. */
+  valueAliases?: Record<string, string | number | boolean | null>;
+}
+
+/** Schema for a settings tab. */
+export interface SettingsTabSchema {
+  /** Tab label ("Review") */
+  label: string;
+  /** Ordered list of setting IDs in this tab */
+  settingIds: string[];
+}
+
+/** Full settings schema — defines all settings, tabs, and file paths. */
+export interface SettingsSchema {
+  /** All setting definitions */
+  settings: SettingSchema[];
+  /** Tab layout */
+  tabs: SettingsTabSchema[];
+  /** Where global settings file lives */
+  globalPath: (globalDir?: string) => string;
+  /** Where project settings file lives */
+  projectPath: (cwd: string) => string;
+}
+
+/** Tab definition for UI rendering. */
+export interface TabDefinition {
+  label: string;
+  settings: SettingItem[];
+}
+
+/** A single preset entry: display label paired with its raw typed value and serialized form. */
+export interface PresetItem {
+  label: string;
+  /** Raw typed value (passed to updateSetting for value-based matching). */
+  rawValue: string | number | boolean | null;
+  /** Serialized string form (for current-value index matching against currentRawValue). */
+  displayValue: string;
+}
+
+/** Single setting item in a tab. */
+export interface SettingItem {
+  id: string;
+  label: string;
+  value: string;
+  displayValue: string;
+  type: SettingType;
+  description?: string;
+  /** Cohesive preset list (labels + raw values + display strings derived from `presets` pairs). */
+  presets?: readonly PresetItem[];
+}
+
+// ── Storage levels (which persistence targets a settings handle offers) ─────────
+
+/** A persistence target a settings handle / modal may offer. */
+export type StorageLevel = "session" | "project" | "global";
+
+/** The full set of levels, in canonical order. */
+export const DEFAULT_STORAGE_LEVELS: readonly StorageLevel[] = ["session", "project", "global"];
+
+/** Valid level strings (for normalization / typo rejection). */
+export const VALID_STORAGE_LEVELS: ReadonlySet<StorageLevel> = new Set<StorageLevel>(DEFAULT_STORAGE_LEVELS);
+
+/**
+ * Normalize a consumer-supplied `storageLevels`: drop unknown/duplicate entries, fall back to
+ * the full default set when nothing valid remains. Deduping/validating BEFORE the count rule
+ * prevents duplicates or typos from silently flipping single-level → multi-level mode.
+ */
+export function normalizeStorageLevels(levels: StorageLevel[] | undefined): StorageLevel[] {
+  if (!levels || levels.length === 0) return [...DEFAULT_STORAGE_LEVELS];
+  const seen = new Set<StorageLevel>();
+  const out: StorageLevel[] = [];
+  for (const level of levels) {
+    if (VALID_STORAGE_LEVELS.has(level) && !seen.has(level)) {
+      seen.add(level);
+      out.push(level);
+    }
+  }
+  return out.length > 0 ? out : [...DEFAULT_STORAGE_LEVELS];
+}

package/src/snippets/vendored/subscribe-to-dialog-coordinator.ts

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Dialog coordinator forwarding — drop-in integration with avtc-pi-ui-components DialogCoordinator.
+ *
+ * Copy this file into your extension's src/snippets/vendored/ directory, then:
+ *   1. Call subscribeToDialogCoordinator(pi) in your extension entry point
+ *   2. Call withCoordinator(fn) around any blocking ctx.ui.* call
+ *
+ * If avtc-pi-ui-components is not installed or the coordinator event never fires,
+ * all functions pass through (no-op).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Shared VALUE, stored on globalThis so it survives jiti `moduleCache: false` re-imports
+ * (which create distinct module instances and would otherwise split a module-level
+ * `let` between the setter in subscribeToDialogCoordinator() and the getter in
+ * withCoordinator()).
+ *
+ * `coordinator` is idempotent across subscribers — there is one DialogCoordinator,
+ * so one object. Listener unsubs are NOT shared: each subscribeToDialogCoordinator()
+ * call owns its own local closure unsubs.
+ */
+interface DialogCoordinatorForwardingState {
+  coordinator: { enqueueOrShow<T>(fn: () => Promise<T>): Promise<T> } | null;
+}
+const STATE_KEY = "__piDialogCoordinatorForwarding";
+type GlobalWithState = typeof globalThis & { [STATE_KEY]?: DialogCoordinatorForwardingState };
+function _state(): DialogCoordinatorForwardingState {
+  const g = globalThis as GlobalWithState;
+  if (!g[STATE_KEY]) {
+    g[STATE_KEY] = { coordinator: null };
+  }
+  const state = g[STATE_KEY];
+  return state;
+}
+
+/**
+ * Reset module state — called during test cleanup.
+ */
+export function _resetState(): void {
+  _state().coordinator = null;
+}
+
+/**
+ * Subscribe to dialog-coordinator:ready event emitted by avtc-pi-ui-components.
+ * Call once per extension entry point.
+ *
+ * Reload-safe: session_shutdown fires before reload, cleaning all listeners.
+ */
+export function subscribeToDialogCoordinator(pi: ExtensionAPI): void {
+  if (!pi.events) return; // graceful no-op for incomplete test mocks
+
+  const unsubs: Array<() => void> = [];
+
+  // Listen for dialog-coordinator:ready (emitted by avtc-pi-ui-components in session_start)
+  unsubs.push(
+    pi.events.on("dialog-coordinator:ready", (data: unknown) => {
+      const api = data as {
+        coordinator?: { enqueueOrShow<T>(fn: () => Promise<T>): Promise<T> };
+      };
+      if (api?.coordinator && typeof api.coordinator.enqueueOrShow === "function") {
+        _state().coordinator = api.coordinator;
+      }
+    }),
+  );
+
+  // Reset on session shutdown (fires before reload) — clean ONLY this subscriber's
+  // EventBus listener (pi.on listeners are torn down by pi), then clear shared value
+  // (hygiene; provider re-emits on next session_start).
+  pi.on("session_shutdown", () => {
+    for (const unsub of unsubs) {
+      if (typeof unsub === "function") unsub();
+    }
+    unsubs.length = 0;
+    _state().coordinator = null;
+  });
+}
+
+/**
+ * Wrap an async UI call with dialog coordination.
+ * The call is serialized through the shared queue: if another dialog is currently
+ * showing, this call waits and is shown only after the active dialog resolves.
+ * If no coordinator is installed, the call is executed immediately (no-op).
+ *
+ * @param fn - Async function that blocks on user input (e.g. ctx.ui.select, ctx.ui.custom)
+ * @returns A promise that resolves with whatever `fn` returns.
+ */
+export async function withCoordinator<T>(fn: () => Promise<T>): Promise<T> {
+  const coordinator = _state().coordinator;
+  if (coordinator) {
+    return coordinator.enqueueOrShow(fn);
+  }
+  return fn();
+}

package/src/snippets/vendored/subscribe-to-notifications.ts

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Notification forwarding — drop-in integration with pi-notification.
+ *
+ * Copy this file into your extension's src/snippets/vendored/ directory, then:
+ *   1. Call subscribeToNotificationApi(pi) in your extension entry point
+ *   2. Call requestAttention(source, detail) before any blocking UI call
+ *   3. Call the returned cancel function when unblocked
+ *
+ * If pi-notification is not installed, all functions are no-ops.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Shared VALUES, stored on globalThis so they survive jiti `moduleCache: false` re-imports
+ * (which create distinct module instances and would otherwise split module-level `let`
+ * variables between the setter in extension.ts and the getter in select-with-note.ts).
+ *
+ * Only idempotent VALUES live here — there is one provider (so one requestAttention fn)
+ * and one active session (so one lastMessage), observed identically by every
+ * subscriber. Listener unsubs are NOT shared: each subscribeToNotificationApi() call
+ * owns its own local closure unsubs, so multiple subscribers (ui-components,
+ * ask-user-question, feature-flow) don't clobber each other's cleanup.
+ */
+interface NotificationForwardingState {
+  requestAttention: ((source: string, detail?: string) => (() => void) | undefined) | null;
+  lastMessage: string;
+}
+const STATE_KEY = "__piNotificationForwarding";
+type GlobalWithState = typeof globalThis & { [STATE_KEY]?: NotificationForwardingState };
+function _state(): NotificationForwardingState {
+  const g = globalThis as GlobalWithState;
+  if (!g[STATE_KEY]) {
+    g[STATE_KEY] = { requestAttention: null, lastMessage: "" };
+  }
+  const state = g[STATE_KEY];
+  return state;
+}
+
+/**
+ * Extract the last assistant text from a message_end event.
+ * Handles string content and array content (filters to text blocks, takes last).
+ * Returns empty string if no suitable text found.
+ */
+type MessageContentBlock = { type: string; text?: string };
+
+export function extractLastAssistantText(event: {
+  message?: { role?: string; content?: string | MessageContentBlock[] };
+}): string {
+  if (event.message?.role !== "assistant") return "";
+
+  const content = event.message.content;
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    const textBlocks = content.filter((b): b is MessageContentBlock & { type: "text" } => b.type === "text");
+    const last = textBlocks[textBlocks.length - 1];
+    if (last) {
+      return last.text ?? "";
+    }
+  }
+  return "";
+}
+
+/**
+ * Get the last captured assistant message text.
+ * Returns empty string if no message has been captured yet.
+ */
+export function getLastMessage(): string {
+  return _state().lastMessage;
+}
+
+/**
+ * Reset module state — called on session shutdown and during test cleanup.
+ * Clears shared values; listener cleanup is each subscriber's own responsibility
+ * (via its session_shutdown handler).
+ */
+export function _resetNotificationState(): void {
+  const s = _state();
+  s.lastMessage = "";
+  s.requestAttention = null;
+}
+
+/**
+ * Subscribe to pi-notification:ready event and message_end events.
+ * Call once per extension entry point (all will set the same shared reference).
+ *
+ * Reload-safe: session_shutdown fires before reload, cleaning all listeners.
+ */
+export function subscribeToNotificationApi(pi: ExtensionAPI): void {
+  const unsubs: Array<() => void> = [];
+
+  const unsub = pi.events.on("pi-notification:ready", (data: unknown) => {
+    const api = data as {
+      requestAttention?: (source: string, detail?: string) => (() => void) | undefined;
+    };
+    if (typeof api.requestAttention === "function" && api.requestAttention) {
+      _state().requestAttention = api.requestAttention;
+    }
+  });
+  unsubs.push(unsub);
+
+  // Capture last assistant message for notification context.
+  // Note: pi.on (extension lifecycle events) returns void — these listeners are torn down
+  // by pi when it discards the extension runner on reload/session-end, so no manual unsub.
+  if (typeof pi.on === "function") {
+    pi.on("message_end", (event: { message?: { role?: string; content?: string | MessageContentBlock[] } }) => {
+      const text = extractLastAssistantText(event);
+      if (text) _state().lastMessage = text;
+    });
+  }
+
+  // Reset on session shutdown (fires before reload) — clean ONLY this subscriber's
+  // EventBus listener (pi.on listeners are torn down by pi), then clear shared values
+  // (hygiene; provider re-emits on next session_start).
+  pi.on("session_shutdown", () => {
+    for (const unsub of unsubs) unsub();
+    unsubs.length = 0;
+    const s = _state();
+    s.lastMessage = "";
+    s.requestAttention = null;
+  });
+}
+
+/**
+ * Request attention before blocking on user input.
+ * Returns a cancel function, or undefined if pi-notification is not installed.
+ */
+export function requestAttention(source: string, detail: string): (() => void) | undefined {
+  return _state().requestAttention?.(source, detail);
+}
+
+/**
+ * Wrap an async UI call with requestAttention/cancelAttention.
+ * If pi-notification is not installed, just calls the function directly.
+ *
+ * @param source - Who is requesting attention (e.g. "permission", "ask_user_question")
+ * @param detail - Optional detail (e.g. tool name, question summary)
+ * @param fn - Async function that blocks on user input
+ */
+export async function withAttention<T>(source: string, detail: string, fn: () => Promise<T>): Promise<T> {
+  const cancelAttention = requestAttention(source, detail);
+  try {
+    return await fn();
+  } finally {
+    cancelAttention?.();
+  }
+}