@sherif-fanous/pi-presets-plus 0.1.0

package/src/store/api.ts

@@ -0,0 +1,262 @@
+/**
+ * High-level storage API for presets.
+ *
+ * Owns the operations the rest of the extension calls to read and mutate
+ * presets across both scopes: `loadAll`, `saveScope`, and the CRUD
+ * primitives (`addPreset`, `updatePreset`, `removePreset`,
+ * `reorderWithinScope`). Storage is cache-free — every call re-reads
+ * from disk — and mutations that would violate file invariants return an
+ * `Err` result rather than throwing.
+ */
+import {
+  annotateAndAnalyzeHotkeys,
+  type HotkeyAnalysis,
+} from "../hotkey-conflicts.js";
+import type {
+  LoadedPreset,
+  Preset,
+  PresetScope,
+  PresetsFile,
+} from "../types.js";
+import { loadFile } from "./load.js";
+import { mergeScopes } from "./merge.js";
+import { getGlobalPresetsPath, getProjectPresetsPath } from "./paths.js";
+import { atomicWrite } from "./save.js";
+import { computeClampWarning } from "./validate.js";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+/** Result of {@link loadAll}. */
+interface LoadAllResult {
+  hotkeyAnalysis: HotkeyAnalysis;
+  presets: LoadedPreset[];
+  warnings: string[];
+}
+/** Result type for mutating operations: success carries no payload. */
+type SaveResult = { ok: true } | { ok: false; reason: string };
+/** Subset of `ExtensionContext` the storage API actually needs. */
+type StorageContext = Pick<ExtensionContext, "cwd" | "modelRegistry">;
+
+/**
+ * Append a preset to the named scope.
+ *
+ * Returns an `Err` result when the new name collides with an existing
+ * preset in the same scope. Callers in later UI changes can map this to
+ * a friendly "name already exists" notification.
+ */
+export async function addPreset(
+  preset: Preset,
+  presetScope: PresetScope,
+  ctx: StorageContext,
+): Promise<SaveResult> {
+  const current = await readScope(presetScope, ctx);
+
+  if (current.some((existing) => existing.name === preset.name)) {
+    return {
+      ok: false,
+      reason: `a preset named "${preset.name}" already exists in scope "${presetScope}".`,
+    };
+  }
+
+  const next = [...current, preset];
+
+  await saveScope(presetScope, next, ctx);
+
+  return { ok: true };
+}
+
+/**
+ * Read both scope files and return the merged, ordered, scope-tagged
+ * preset list with availability computed.
+ */
+export async function loadAll(ctx: StorageContext): Promise<LoadAllResult> {
+  const [user, project] = await Promise.all([
+    loadFile(getGlobalPresetsPath()),
+    loadFile(getProjectPresetsPath(ctx.cwd)),
+  ]);
+  const presets = mergeScopes(
+    { user: user.presets, project: project.presets },
+    ctx,
+  ).map((preset) => ({
+    ...preset,
+    ...(computeClampWarning(preset, ctx)
+      ? { clampWarning: true as const }
+      : {}),
+  }));
+
+  const hotkeyAnalysis = annotateAndAnalyzeHotkeys(presets);
+
+  return {
+    hotkeyAnalysis,
+    presets,
+    warnings: [...user.warnings, ...project.warnings],
+  };
+}
+
+/**
+ * Remove a preset by name. No-op (returns `{ ok: true }`) when the named
+ * preset does not exist; this matches the "idempotent delete" expectation
+ * the spec calls out.
+ */
+export async function removePreset(
+  name: string,
+  scope: PresetScope,
+  ctx: StorageContext,
+): Promise<SaveResult> {
+  const current = await readScope(scope, ctx);
+  const next = current.filter((existing) => existing.name !== name);
+
+  if (next.length === current.length) return { ok: true };
+  await saveScope(scope, next, ctx);
+
+  return { ok: true };
+}
+
+/**
+ * Reorder presets within a scope according to the supplied name list.
+ *
+ * Defensive behavior: any names not present in `orderedNames` keep their
+ * relative file order and are appended after the explicitly-ordered
+ * entries. Names in `orderedNames` that don't match any existing preset
+ * are silently ignored — this matters when the caller's UI snapshot is
+ * slightly stale (e.g. a delete happened between picker render and reorder
+ * commit).
+ */
+export async function reorderWithinScope(
+  scope: PresetScope,
+  orderedNames: readonly string[],
+  ctx: StorageContext,
+): Promise<void> {
+  const current = await readScope(scope, ctx);
+  const byName = new Map(
+    current.map((preset) => [preset.name, preset] as const),
+  );
+  const seen = new Set<string>();
+  const ordered: Preset[] = [];
+
+  for (const name of orderedNames) {
+    const preset = byName.get(name);
+
+    if (!preset || seen.has(name)) continue;
+    ordered.push(preset);
+    seen.add(name);
+  }
+
+  for (const preset of current) {
+    if (!seen.has(preset.name)) {
+      ordered.push(preset);
+    }
+  }
+
+  await saveScope(scope, ordered, ctx);
+}
+
+/**
+ * Atomically rewrite a single scope's file with the given preset list.
+ *
+ * The serialized shape is always `{ version: 1, presets }`; only typed
+ * fields on `Preset` are emitted. Callers are responsible for ordering
+ * and uniqueness; this function just persists.
+ */
+export async function saveScope(
+  scope: PresetScope,
+  presets: readonly Preset[],
+  ctx: StorageContext,
+): Promise<void> {
+  const file: PresetsFile = {
+    version: 1,
+    presets: presets.map(serializePreset),
+  };
+  const path = pathForScope(scope, ctx);
+
+  await atomicWrite(path, `${JSON.stringify(file, null, 2)}\n`);
+}
+
+/**
+ * Replace an existing preset by name.
+ *
+ * Supports renaming: `next.name` may differ from `oldName`. Position in
+ * the file is preserved. Returns `Err` when:
+ * - no preset with `oldName` exists in `scope`
+ * - the rename would collide with another preset's name
+ */
+export async function updatePreset(
+  oldName: string,
+  scope: PresetScope,
+  next: Preset,
+  ctx: StorageContext,
+): Promise<SaveResult> {
+  const current = await readScope(scope, ctx);
+  const index = current.findIndex((existing) => existing.name === oldName);
+
+  if (index === -1) {
+    return {
+      ok: false,
+      reason: `no preset named "${oldName}" in scope "${scope}".`,
+    };
+  }
+
+  if (
+    next.name !== oldName &&
+    current.some(
+      (existing, existingIndex) =>
+        existingIndex !== index && existing.name === next.name,
+    )
+  ) {
+    return {
+      ok: false,
+      reason: `a preset named "${next.name}" already exists in scope "${scope}".`,
+    };
+  }
+
+  const updated = [...current];
+
+  updated[index] = next;
+  await saveScope(scope, updated, ctx);
+
+  return { ok: true };
+}
+
+function pathForScope(presetScope: PresetScope, ctx: StorageContext): string {
+  return presetScope === "user"
+    ? getGlobalPresetsPath()
+    : getProjectPresetsPath(ctx.cwd);
+}
+
+/**
+ * Read a single scope file, ignoring warnings. Used by the CRUD helpers
+ * which don't have a UI to surface warnings to. The next `loadAll` call
+ * (and therefore the next `/presets list` / `/presets reload`) will see
+ * any persistent warnings.
+ */
+async function readScope(
+  presetScope: PresetScope,
+  ctx: StorageContext,
+): Promise<Preset[]> {
+  const path = pathForScope(presetScope, ctx);
+  const result = await loadFile(path);
+
+  return result.presets;
+}
+
+/**
+ * Serialize a `Preset` into the on-disk shape, dropping `undefined`
+ * fields so the JSON stays clean. Round-tripping `LoadedPreset`-derived
+ * values (which carry merge metadata) strips `scope`, `shadowed`, and
+ * `unavailable` automatically.
+ */
+function serializePreset(preset: Preset): Preset {
+  const out: Preset = {
+    name: preset.name,
+    provider: preset.provider,
+    model: preset.model,
+  };
+
+  if (preset.thinkingLevel !== undefined)
+    out.thinkingLevel = preset.thinkingLevel;
+  if (preset.tools !== undefined) out.tools = [...preset.tools];
+  if (preset.instructions !== undefined) out.instructions = preset.instructions;
+  if (preset.hotkey !== undefined) out.hotkey = preset.hotkey;
+  if (preset.order !== undefined) out.order = preset.order;
+
+  return out;
+}

package/src/store/load.ts

@@ -0,0 +1,175 @@
+/**
+ * Single-file loader for preset storage.
+ *
+ * Owns reading one scope file from disk and turning it into a list of
+ * valid presets plus human-readable warnings; it does NOT own merging
+ * across scopes, availability computation, or any mutation.
+ */
+import { readFile } from "node:fs/promises";
+
+import type { Preset } from "../types.js";
+import { findDuplicatePresetNames, validatePresetShape } from "./validate.js";
+
+/** Output of {@link loadFile}. */
+interface LoadFileResult {
+  /** Presets that passed shape and uniqueness checks, in file order. */
+  presets: Preset[];
+  /** Human-readable warnings; safe to surface verbatim via `ctx.ui.notify`. */
+  warnings: string[];
+}
+
+/**
+ * Read and parse a single preset file.
+ *
+ * Behavior is fully described by the storage spec:
+ *
+ *  | Condition                    | Result                                  |
+ *  | ---------------------------- | --------------------------------------- |
+ *  | file does not exist          | `{ presets: [], warnings: [] }`         |
+ *  | other read error             | `{ presets: [], warnings: [...] }`      |
+ *  | invalid JSON                 | `{ presets: [], warnings: [...] }`      |
+ *  | top-level not an object      | `{ presets: [], warnings: [...] }`      |
+ *  | unsupported `version`        | `{ presets: [], warnings: [...] }`      |
+ *  | missing `presets` array      | `{ presets: [], warnings: [...] }`      |
+ *  | per-preset shape error       | skip preset, warn, keep the rest        |
+ *  | duplicate name within file   | skip later occurrences, warn, keep first|
+ */
+export async function loadFile(path: string): Promise<LoadFileResult> {
+  let rawData: string;
+
+  try {
+    rawData = await readFile(path, "utf-8");
+  } catch (err) {
+    // `ENOENT` is the only error that does not warrant a warning: a
+    // missing file is the normal "no presets configured yet" state.
+    if (isNotFoundError(err)) return emptyResult();
+
+    return emptyResult(
+      `Failed to read preset file ${path}: ${describeError(err)}`,
+    );
+  }
+
+  let parsedData: unknown;
+
+  try {
+    parsedData = JSON.parse(rawData);
+  } catch (err) {
+    return emptyResult(
+      `The preset file ${path} contains invalid JSON: ${describeError(err)}`,
+    );
+  }
+
+  if (
+    typeof parsedData !== "object" ||
+    parsedData === null ||
+    Array.isArray(parsedData)
+  ) {
+    return emptyResult(
+      `The preset file ${path} top-level must be an object with a "version" and "presets" field.`,
+    );
+  }
+
+  const obj = parsedData as Record<string, unknown>;
+
+  if (obj.version !== 1) {
+    return emptyResult(
+      `The preset file ${path} declares unsupported version ${JSON.stringify(obj.version)}; expected 1. File ignored and left untouched.`,
+    );
+  }
+
+  if (!Array.isArray(obj.presets)) {
+    return emptyResult(
+      `The preset file ${path} is missing a top-level "presets" array.`,
+    );
+  }
+
+  const warnings: string[] = [];
+  const validatedPresets: Preset[] = [];
+  const rawPresets: unknown[] = obj.presets;
+
+  // First pass: shape validation. Skip-and-warn on individual offenders so
+  // one broken preset never disables the whole file.
+  for (let i = 0; i < rawPresets.length; i++) {
+    const candidatePreset = rawPresets[i];
+    const result = validatePresetShape(candidatePreset);
+
+    if (!result.ok) {
+      const label = describeInvalidPreset(candidatePreset, i);
+
+      warnings.push(
+        `Preset ${label} in ${path} skipped: ${result.reason ?? "Invalid shape"}.`,
+      );
+
+      continue;
+    }
+
+    // validatePresetShape narrows to "object with required fields"; cast is safe.
+    validatedPresets.push(candidatePreset as Preset);
+  }
+
+  // Second pass: duplicate name detection. The first occurrence wins.
+  const duplicatePresetNames = findDuplicatePresetNames(validatedPresets);
+
+  if (duplicatePresetNames.length > 0) {
+    const dropIndices = new Set(
+      duplicatePresetNames.map((duplicate) => duplicate.index),
+    );
+    const uniquePresets: Preset[] = [];
+
+    for (let i = 0; i < validatedPresets.length; i++) {
+      if (dropIndices.has(i)) {
+        const dropped = validatedPresets[i];
+
+        if (dropped) {
+          warnings.push(
+            `Preset "${dropped.name}" in ${path} skipped: duplicate name (first occurrence kept).`,
+          );
+        }
+
+        continue;
+      }
+
+      const keep = validatedPresets[i];
+
+      if (keep) uniquePresets.push(keep);
+    }
+
+    return { presets: uniquePresets, warnings };
+  }
+
+  return { presets: validatedPresets, warnings };
+}
+
+function describeError(err: unknown): string {
+  if (err instanceof Error) return err.message;
+
+  return String(err);
+}
+
+/** Best-effort label for an invalid preset entry in warning text. */
+function describeInvalidPreset(preset: unknown, index: number): string {
+  if (
+    typeof preset === "object" &&
+    preset !== null &&
+    !Array.isArray(preset) &&
+    typeof (preset as { name?: unknown }).name === "string" &&
+    (preset as { name: string }).name.length > 0
+  ) {
+    return `"${(preset as { name: string }).name}"`;
+  }
+
+  return `at index ${index}`;
+}
+
+/** Empty result used whenever the file cannot be read or is malformed. */
+function emptyResult(warning?: string): LoadFileResult {
+  return { presets: [], warnings: warning ? [warning] : [] };
+}
+
+function isNotFoundError(err: unknown): boolean {
+  if (typeof err !== "object" || err === null || !("code" in err)) {
+    return false;
+  }
+
+  return err.code === "ENOENT";
+}

package/src/store/merge.ts

@@ -0,0 +1,69 @@
+/**
+ * Scope merge for preset storage.
+ *
+ * Owns combining the per-scope loader outputs into the single ordered
+ * `LoadedPreset[]` exposed by `loadAll`, including scope tagging,
+ * shadowing, and availability tagging. Pure: no I/O, no logging.
+ */
+import type { LoadedPreset, Preset } from "../types.js";
+import { computeAvailability } from "./validate.js";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+/** Per-scope inputs to {@link mergeScopes}. */
+interface MergeScopesInput {
+  /** Presets from the global / user-scope file, in file order. */
+  user: readonly Preset[];
+  /** Presets from the project-scope file, in file order. */
+  project: readonly Preset[];
+}
+
+/**
+ * Merge two scopes into a single ordered list.
+ *
+ * Globals are emitted first, then projects, each preserving file order.
+ * Globals that share a name with a project entry are tagged
+ * `shadowed: true` (still emitted, never dropped). Availability is
+ * computed for every entry.
+ */
+export function mergeScopes(
+  input: MergeScopesInput,
+  ctx: Pick<ExtensionContext, "modelRegistry">,
+): LoadedPreset[] {
+  const projectNames = new Set(input.project.map((preset) => preset.name));
+  const out: LoadedPreset[] = [];
+
+  for (const userPreset of input.user) {
+    out.push({
+      ...userPreset,
+      scope: "user",
+      ...(projectNames.has(userPreset.name) ? { shadowed: true } : {}),
+      ...availabilityField(userPreset, ctx),
+    });
+  }
+
+  for (const projectPreset of input.project) {
+    out.push({
+      ...projectPreset,
+      scope: "project",
+      ...availabilityField(projectPreset, ctx),
+    });
+  }
+
+  return out;
+}
+
+/**
+ * Spread-helper that returns either `{}` or `{ unavailable: <reason> }`.
+ *
+ * Keeps `LoadedPreset.unavailable` cleanly absent for available presets
+ * (rather than serializing `unavailable: undefined`) and avoids the
+ * caller having to do conditional assignment at every call site.
+ */
+function availabilityField(
+  preset: Pick<Preset, "provider" | "model">,
+  ctx: Pick<ExtensionContext, "modelRegistry">,
+): { unavailable?: "no-key" | "no-model" } {
+  const reason = computeAvailability(preset, ctx);
+
+  return reason ? { unavailable: reason } : {};
+}

package/src/store/paths.ts

@@ -0,0 +1,38 @@
+/**
+ * Path resolution for preset storage files.
+ *
+ * Owns resolving the absolute on-disk location of each scope's presets
+ * file (global under the agent dir, project under `<cwd>/.pi/`); it does
+ * NOT perform any I/O.
+ */
+import { join } from "node:path";
+
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+
+/** File name for the preset list within `PRESETS_PLUS_SUBDIR`. */
+const PRESETS_FILE_NAME = "presets.json";
+/** Subdirectory under both scopes that contains preset-related files. */
+const PRESETS_PLUS_SUBDIR = "presets-plus";
+/** Project-scope parent directory under the project root. */
+const PROJECT_PI_DIR = ".pi";
+
+/**
+ * Absolute path to the global / user-scope preset file.
+ *
+ * Uses pi's `getAgentDir()` by default (typically `~/.pi/agent`); pass an
+ * override only from tests that want to point at a tmp dir without
+ * patching environment variables.
+ */
+export function getGlobalPresetsPath(agentDir: string = getAgentDir()): string {
+  return join(agentDir, PRESETS_PLUS_SUBDIR, PRESETS_FILE_NAME);
+}
+
+/**
+ * Absolute path to the project-scope preset file for the given working dir.
+ *
+ * Mirrors pi's convention of placing project-local config under `<cwd>/.pi/`.
+ * The caller is expected to pass `ctx.cwd` from the extension context.
+ */
+export function getProjectPresetsPath(cwd: string): string {
+  return join(cwd, PROJECT_PI_DIR, PRESETS_PLUS_SUBDIR, PRESETS_FILE_NAME);
+}

package/src/store/save.ts

@@ -0,0 +1,75 @@
+/**
+ * Atomic file writes for preset storage.
+ *
+ * Owns the durable write primitive (`mkdir -p` → tmp file → `fsync` →
+ * `rename`) used everywhere presets-plus persists user-visible state, so
+ * the destination is never observed in a partially-written form.
+ */
+import { mkdir, open, rename, unlink } from "node:fs/promises";
+import { dirname } from "node:path";
+
+/**
+ * Subset of `node:fs/promises` we depend on. Exposed so tests can inject
+ * a stub that simulates rename failures (Node's ESM exports of native
+ * modules are not spy-able via vitest).
+ */
+interface AtomicWriteFs {
+  mkdir: typeof mkdir;
+  open: typeof open;
+  rename: typeof rename;
+  unlink: typeof unlink;
+}
+
+const defaultFs: AtomicWriteFs = { mkdir, open, rename, unlink };
+
+/**
+ * Atomically write `contents` to `target`.
+ *
+ * Throws on I/O failure; the destination is never partially written. The
+ * caller is responsible for serializing concurrent writes within the
+ * same process if it wants stricter ordering than last-write-wins.
+ *
+ * @param fs Override the underlying `node:fs/promises` calls (for tests).
+ */
+export async function atomicWrite(
+  target: string,
+  contents: string,
+  fs: AtomicWriteFs = defaultFs,
+): Promise<void> {
+  const dir = dirname(target);
+
+  await fs.mkdir(dir, { recursive: true });
+
+  const temporaryFilePath = makeTmpPath(target);
+  let renamed = false;
+  const fileHandle = await fs.open(temporaryFilePath, "w");
+
+  try {
+    try {
+      await fileHandle.writeFile(contents);
+      await fileHandle.sync();
+    } finally {
+      await fileHandle.close();
+    }
+
+    await fs.rename(temporaryFilePath, target);
+    renamed = true;
+  } finally {
+    if (!renamed) {
+      // Best effort: don't mask the original error if cleanup fails.
+      await fs.unlink(temporaryFilePath).catch(() => undefined);
+    }
+  }
+}
+
+/**
+ * Build a tmp file path co-located with `target` so the rename is on the
+ * same filesystem and therefore guaranteed atomic.
+ *
+ * Uses `process.pid` and a high-resolution timestamp to avoid collisions
+ * between concurrent writers; `process.hrtime.bigint()` is monotonic
+ * within a single process so the suffix never repeats per call.
+ */
+export function makeTmpPath(target: string): string {
+  return `${target}.tmp.${process.pid}.${process.hrtime.bigint().toString(36)}`;
+}