@sherif-fanous/pi-presets-plus 0.1.0

package/src/store/validate.ts

@@ -0,0 +1,195 @@
+/**
+ * Validation primitives for the preset storage layer.
+ *
+ * Owns shape validation of individual presets, duplicate-name detection
+ * within a list, and runtime availability checks against pi's model
+ * registry. None of these helpers throw or perform file-system I/O.
+ */
+import type { Preset, ThinkingLevel } from "../types.js";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+/** Result of a single-preset shape check. */
+interface ValidationResult {
+  ok: boolean;
+  /** Human-readable reason the preset failed validation; absent on success. */
+  reason?: string;
+}
+
+/** Allowed values for `Preset.thinkingLevel`. */
+const THINKING_LEVELS: readonly ThinkingLevel[] = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+] as const;
+
+/**
+ * Compute the availability of a preset against the live model registry.
+ *
+ * Returns:
+ * - `"no-model"`  the preset's `provider`/`model` is not registered
+ * - `"no-key"`    the model is registered but its provider has no API key
+ * - `undefined`   the preset is fully available
+ *
+ * Does not perform any network I/O: the API key check uses
+ * `hasConfiguredAuth` (synchronous, fast) rather than refreshing OAuth
+ * tokens. Activation-time code paths (later change) re-check with the
+ * async resolver.
+ */
+export function computeAvailability(
+  preset: Pick<Preset, "provider" | "model">,
+  ctx: Pick<ExtensionContext, "modelRegistry">,
+): "no-model" | "no-key" | undefined {
+  const model = ctx.modelRegistry.find(preset.provider, preset.model);
+
+  if (!model) return "no-model";
+  if (!ctx.modelRegistry.hasConfiguredAuth(model)) return "no-key";
+
+  return undefined;
+}
+
+/** Return whether activation will clamp a preset's thinking level to off. */
+export function computeClampWarning(
+  preset: Pick<Preset, "provider" | "model" | "thinkingLevel">,
+  ctx: Pick<ExtensionContext, "modelRegistry">,
+): boolean {
+  if (!preset.thinkingLevel || preset.thinkingLevel === "off") return false;
+
+  const model = ctx.modelRegistry.find(preset.provider, preset.model);
+
+  if (!model) return false;
+
+  return model.reasoning === false;
+}
+
+/**
+ * Find duplicate `name` entries in a preset array, preserving the index of
+ * each duplicate (i.e. the second and subsequent occurrences) so the
+ * loader can skip-and-warn naming the offenders.
+ *
+ * Pure: does not mutate the input array.
+ */
+export function findDuplicatePresetNames(
+  presets: readonly Preset[],
+): { name: string; index: number }[] {
+  const seenPresetNames = new Set<string>();
+  const duplicatePresetNames: { name: string; index: number }[] = [];
+
+  for (let i = 0; i < presets.length; i++) {
+    const preset = presets[i];
+
+    if (!preset) continue;
+
+    const name = preset.name;
+
+    if (seenPresetNames.has(name)) {
+      duplicatePresetNames.push({ name, index: i });
+    } else {
+      seenPresetNames.add(name);
+    }
+  }
+
+  return duplicatePresetNames;
+}
+
+/**
+ * Validate the shape of a single preset.
+ *
+ * Required fields (per the storage spec):
+ *  - `name`     non-empty string
+ *  - `provider` non-empty string
+ *  - `model`    non-empty string
+ *
+ * Optional fields are checked when present:
+ *  - `thinkingLevel`  must be in the `ThinkingLevel` enum
+ *  - `tools`          must be an array of strings
+ *  - `instructions`   must be a string
+ *  - `hotkey`         must be a string
+ *  - `order`          must be a finite number
+ *
+ * Unknown fields are accepted (forward-compat); the loader's serializer
+ * only round-trips the typed shape but extra fields are not flagged.
+ */
+export function validatePresetShape(
+  candidatePreset: unknown,
+): ValidationResult {
+  if (
+    typeof candidatePreset !== "object" ||
+    candidatePreset === null ||
+    Array.isArray(candidatePreset)
+  ) {
+    return { ok: false, reason: "Preset is not an object." };
+  }
+
+  const obj = candidatePreset as Record<string, unknown>;
+  const requireString = (
+    field: "name" | "provider" | "model",
+  ): ValidationResult | undefined => {
+    const value = obj[field];
+
+    if (typeof value !== "string" || value.length === 0) {
+      return {
+        ok: false,
+        reason: `Missing or empty required field "${field}".`,
+      };
+    }
+
+    return undefined;
+  };
+  const nameError = requireString("name");
+
+  if (nameError) return nameError;
+
+  const providerError = requireString("provider");
+
+  if (providerError) return providerError;
+
+  const modelError = requireString("model");
+
+  if (modelError) return modelError;
+
+  if (obj.thinkingLevel !== undefined) {
+    if (
+      typeof obj.thinkingLevel !== "string" ||
+      !THINKING_LEVELS.includes(obj.thinkingLevel as ThinkingLevel)
+    ) {
+      const label =
+        typeof obj.thinkingLevel === "string"
+          ? JSON.stringify(obj.thinkingLevel)
+          : typeof obj.thinkingLevel;
+
+      return {
+        ok: false,
+        reason: `Invalid thinkingLevel ${label} (expected one of ${THINKING_LEVELS.join(", ")}).`,
+      };
+    }
+  }
+
+  if (obj.tools !== undefined) {
+    if (
+      !Array.isArray(obj.tools) ||
+      obj.tools.some((tool) => typeof tool !== "string")
+    ) {
+      return { ok: false, reason: `"tools" must be an array of strings.` };
+    }
+  }
+
+  if (obj.instructions !== undefined && typeof obj.instructions !== "string") {
+    return { ok: false, reason: `"instructions" must be a string.` };
+  }
+
+  if (obj.hotkey !== undefined && typeof obj.hotkey !== "string") {
+    return { ok: false, reason: `"hotkey" must be a string.` };
+  }
+
+  if (
+    obj.order !== undefined &&
+    (typeof obj.order !== "number" || !Number.isFinite(obj.order))
+  ) {
+    return { ok: false, reason: `"order" must be a finite number.` };
+  }
+
+  return { ok: true };
+}

package/src/types.ts

@@ -0,0 +1,169 @@
+/**
+ * Shared type definitions for pi-presets-plus.
+ *
+ * Owns the persistent preset shapes (`Preset`, `PresetsFile`), scope and
+ * loader output types (`PresetScope`, `LoadedPreset`), the activation
+ * state shape, and a local `ThinkingLevel` that extends `pi-ai`'s level
+ * set with the explicit `"off"` value used by pi.
+ */
+
+/**
+ * A preset enriched with merge/availability metadata.
+ *
+ * Returned by the storage merge step (`mergeScopes`). `shadowed` and
+ * `unavailable` are computed at load time and may change across reloads;
+ * callers must not assume they survive a `ctx.reload()`.
+ */
+export interface LoadedPreset extends Preset {
+  /** Origin file's scope; assigned by the loader. */
+  scope: PresetScope;
+  /**
+   * `true` for a global preset whose name is also defined in the project
+   * file (the project entry wins at activation time).
+   */
+  shadowed?: boolean;
+  /**
+   * Reason the preset cannot be activated, computed at load time:
+   * - `"no-model"` — model id not registered for the named provider
+   * - `"no-key"`   — model is registered but its provider has no API key
+   *
+   * Undefined when the preset is fully available.
+   */
+  unavailable?: "no-key" | "no-model";
+  /**
+   * True when the preset requests extended thinking for a model that will
+   * clamp it to off at activation time. Computed in memory; never persisted.
+   */
+  clampWarning?: true;
+  /** True when another preset claimed this preset's hotkey first. */
+  hotkeyConflict?: true | undefined;
+  /**
+   * True when the parsed hotkey matches a Pi built-in keybinding. Computed by
+   * `annotateAndAnalyzeHotkeys` alongside `hotkeyConflict` at load time so
+   * consumers can surface the derived shadowing state.
+   */
+  hotkeyShadowsBuiltin?: true | undefined;
+}
+
+/**
+ * A preset definition as it appears in either scope's JSON file.
+ *
+ * Required fields: `name`, `provider`, `model`. All other fields are
+ * optional and accepted by the loader unchanged; behavior that consumes
+ * them (instructions injection, hotkey binding, ordering) lands in later
+ * changes. Storage validates the shape and round-trips unknown-but-typed
+ * fields verbatim.
+ */
+export interface Preset {
+  /** Unique within a single file; merge-time shadowing is by name. */
+  name: string;
+  /** Provider id (e.g. `"anthropic"`, `"openai"`). */
+  provider: string;
+  /** Model id within `provider` (e.g. `"claude-opus-4.5"`). */
+  model: string;
+  /** Reasoning level. Defaults to `"off"` at apply time (later change). */
+  thinkingLevel?: ThinkingLevel;
+  /** Active tools at apply time. Omit / empty = session tools pass through unchanged. */
+  tools?: string[];
+  /** Free-form text appended to the system prompt at apply time. */
+  instructions?: string;
+  /** Hotkey id; honored by a later change. */
+  hotkey?: string;
+  /** User-controlled cycle order; default = file order. */
+  order?: number;
+}
+
+/**
+ * In-memory snapshot of the preset fields drift detection compares against.
+ *
+ * Cached on `ActivePresetState` at apply / restore time so per-turn drift
+ * detection never has to re-read the on-disk preset files. Refreshed on
+ * apply, on session restore, and on `/presets reload` (via re-apply) — never
+ * on `turn_start` or `model_select`.
+ */
+export interface PresetDriftSnapshot {
+  provider: string;
+  model: string;
+  thinkingLevel?: ThinkingLevel;
+  tools?: readonly string[];
+}
+
+/** Baseline Pi state captured before a preset overlay starts. */
+export interface PresetOverlayBaseline {
+  model: { provider: string; id: string } | null;
+  thinkingLevel: ThinkingLevel;
+  tools: string[];
+}
+
+/**
+ * On-disk JSON shape for a single preset file (either scope).
+ *
+ * `version: 1` is the current schema version. Files declaring a different
+ * version are treated as empty + warned by the loader (and never rewritten),
+ * leaving room for forward-compatible schema evolution.
+ */
+export interface PresetsFile {
+  version: 1;
+  presets: Preset[];
+}
+
+/** In-memory active-preset state for change `add-preset-activation`. */
+export type ActivePresetState =
+  | {
+      name: string;
+      scope: PresetScope;
+      restore: {
+        kind: "baseline";
+        baseline: PresetOverlayBaseline;
+        lastApplied: LastAppliedPresetEffects;
+        owned: PresetOverlayOwnership;
+        applyCount: number;
+      };
+      dirty: boolean;
+      declared: PresetDriftSnapshot;
+    }
+  | {
+      name: string;
+      scope: PresetScope;
+      restore: { kind: "unknown" };
+      dirty: boolean;
+      declared: PresetDriftSnapshot;
+    };
+
+/**
+ * Origin scope for a loaded preset.
+ *
+ * - `"user"` — the global file under `<agent-dir>/presets-plus/presets.json`
+ * - `"project"` — the per-cwd file under `<cwd>/.pi/presets-plus/presets.json`
+ */
+export type PresetScope = "user" | "project";
+
+/**
+ * Reasoning level recorded on a preset.
+ *
+ * Mirrors pi-coding-agent's `getThinkingLevel()` / `setThinkingLevel()` API,
+ * which extends `pi-ai`'s `ThinkingLevel` with the explicit `"off"` value.
+ * Storage accepts the literal set verbatim; per-model clamping happens at
+ * activation time in a later change.
+ */
+export type ThinkingLevel =
+  | "off"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+
+/** Last values written by presets-plus inside the active overlay. */
+interface LastAppliedPresetEffects {
+  model: { provider: string; id: string };
+  thinkingLevel: ThinkingLevel;
+  tools?: string[];
+}
+
+/** Tracks which Pi channels are owned by the active preset overlay. */
+interface PresetOverlayOwnership {
+  model: true;
+  thinkingLevel: true;
+  tools: boolean;
+}

package/src/ui/confirm.ts

@@ -0,0 +1,126 @@
+/**
+ * Small custom confirmation overlay shared by preset TUI surfaces.
+ *
+ * Owns yes/no keyboard handling for extension-local confirmations; it does
+ * NOT own the action being confirmed or any persistence side effects.
+ */
+import { centerText, renderDialogFrame, wrapBody } from "./frame.js";
+import type {
+  ExtensionCommandContext,
+  Theme,
+} from "@mariozechner/pi-coding-agent";
+import {
+  Key,
+  matchesKey,
+  type Component,
+  type Focusable,
+} from "@mariozechner/pi-tui";
+
+class ConfirmComponent implements Component, Focusable {
+  private selected: "no" | "yes" = "no";
+  private resolved = false;
+  private _focused = false;
+
+  constructor(
+    private readonly title: string,
+    private readonly message: string,
+    private readonly theme: Theme,
+    private readonly done: (result: boolean) => void,
+  ) {}
+
+  get focused(): boolean {
+    return this._focused;
+  }
+
+  set focused(value: boolean) {
+    this._focused = value;
+  }
+
+  handleInput(input: string): void {
+    if (matchesKey(input, Key.escape)) {
+      this.finish(false);
+
+      return;
+    }
+
+    if (matchesKey(input, Key.left) || matchesKey(input, Key.right)) {
+      this.selected = this.selected === "yes" ? "no" : "yes";
+
+      return;
+    }
+
+    if (input.toLowerCase() === "y") {
+      this.finish(true);
+
+      return;
+    }
+
+    if (input.toLowerCase() === "n") {
+      this.finish(false);
+
+      return;
+    }
+
+    if (matchesKey(input, Key.enter) || input === " ") {
+      this.finish(this.selected === "yes");
+    }
+  }
+
+  invalidate(): void {
+    // No cached layout or external data to invalidate.
+  }
+
+  render(width: number): string[] {
+    const frameWidth = Math.max(2, width);
+    const bodyWidth = Math.max(1, frameWidth - 2);
+    const messageLines = wrapBody(this.message, bodyWidth - 4);
+    const buttons = [
+      this.renderButton("yes", "Yes"),
+      this.renderButton("no", "No"),
+    ].join("   ");
+
+    return renderDialogFrame({
+      bodyLines: [
+        ...messageLines.map((line) => `  ${line}`),
+        "",
+        centerText(buttons, bodyWidth),
+      ],
+      footer: this.theme.fg("dim", " ←/→ choose · Enter confirm · Esc cancel "),
+      title: this.theme.fg("accent", this.theme.bold(this.title)),
+      width: frameWidth,
+    });
+  }
+
+  private finish(result: boolean): void {
+    if (this.resolved) return;
+    this.resolved = true;
+    this.done(result);
+  }
+
+  private renderButton(value: "no" | "yes", label: string): string {
+    const text = this.selected === value ? `● ${label}` : `○ ${label}`;
+
+    return this.selected === value ? this.theme.fg("accent", text) : text;
+  }
+}
+
+export async function openConfirm(
+  ctx: Pick<ExtensionCommandContext, "ui">,
+  title: string,
+  message: string,
+): Promise<boolean> {
+  return ctx.ui.custom<boolean>(
+    (_tui, theme, _keybindings, done) =>
+      new ConfirmComponent(title, message, theme, done),
+    {
+      overlay: true,
+      overlayOptions: {
+        anchor: "center",
+        margin: 2,
+        maxHeight: "50%",
+        minWidth: 48,
+        width: "50%",
+      },
+    },
+  );
+}