@sherif-fanous/pi-presets-plus 0.1.0

package/src/hotkey-conflicts.ts

@@ -0,0 +1,136 @@
+/**
+ * Hotkey conflict annotation for loaded presets.
+ *
+ * Owns preset-vs-preset hotkey parsing and conflict marking. It does NOT own
+ * shortcut registration, notifications, or built-in keybinding checks.
+ */
+import type { LoadedPreset, PresetScope } from "./types.js";
+import {
+  isPiBuiltin,
+  parseHotkey,
+  type ParsedHotkey,
+} from "./ui/hotkey-input.js";
+
+export interface HotkeyAnalysis {
+  readonly conflicts: HotkeyConflict[];
+  /**
+   * Invalid declarations found during annotation.
+   *
+   * This is per-load diagnostic data. User-facing callers should emit these
+   * warnings only at deliberate notification boundaries (for example, once at
+   * session-start) rather than every time storage is re-read.
+   */
+  readonly invalid: HotkeyDiagnostic[];
+  readonly parsed: ReadonlyMap<LoadedPreset, ParsedHotkey>;
+}
+
+export interface HotkeyConflict {
+  readonly loser: LoadedPreset & { hotkey: string };
+  readonly winner: PresetIdentity;
+}
+
+export interface HotkeyDiagnostic {
+  readonly preset: LoadedPreset & { hotkey: string };
+  /** Short, human-readable parse failure reason safe to show in UI copy. */
+  readonly reason: string;
+}
+
+export interface PresetIdentity {
+  readonly name: string;
+  readonly scope: PresetScope;
+}
+
+/**
+ * Annotate presets with hotkey conflict markers and return parsed hotkey data.
+ *
+ * Mutates freshly-loaded presets so every UI path can read one canonical
+ * annotation without maintaining a parallel conflict map. Before recomputing,
+ * it clears all existing hotkey markers so stale annotations from a previous
+ * load cannot persist. Invalid hotkeys are reported as ignored and do not
+ * participate in conflict detection because they do not identify a valid chord.
+ */
+export function annotateAndAnalyzeHotkeys(
+  presets: LoadedPreset[],
+): HotkeyAnalysis {
+  const claimed = new Map<string, PresetIdentity>();
+  const conflicts: HotkeyConflict[] = [];
+  const invalid: HotkeyDiagnostic[] = [];
+  const parsedHotkeys = new Map<LoadedPreset, ParsedHotkey>();
+
+  for (const preset of presets) {
+    preset.hotkeyConflict = undefined;
+    preset.hotkeyShadowsBuiltin = undefined;
+
+    const { hotkey } = preset;
+
+    if (!hotkey) continue;
+
+    const presetWithHotkey: LoadedPreset & { hotkey: string } = {
+      ...preset,
+      hotkey,
+    };
+    const parsed = parseHotkey(hotkey);
+
+    if (!parsed.ok) {
+      invalid.push({ preset: presetWithHotkey, reason: parsed.reason });
+
+      continue;
+    }
+
+    parsedHotkeys.set(preset, parsed.parsed);
+
+    if (isPiBuiltin(parsed.parsed)) {
+      preset.hotkeyShadowsBuiltin = true;
+    }
+
+    // Annotate before the shadowed-skip so muted picker entries still explain the shadowing.
+    if (preset.shadowed) continue;
+
+    const winner = claimed.get(parsed.parsed.normalized);
+
+    if (winner) {
+      preset.hotkeyConflict = true;
+      conflicts.push({ loser: presetWithHotkey, winner });
+
+      continue;
+    }
+
+    claimed.set(parsed.parsed.normalized, {
+      name: preset.name,
+      scope: preset.scope,
+    });
+  }
+
+  return { conflicts, invalid, parsed: parsedHotkeys };
+}
+
+/** Returns `"<name>" (<scope>)`, including the quotes around the name. */
+export function formatPresetIdentity(identity: PresetIdentity): string {
+  return `"${identity.name}" (${identity.scope})`;
+}
+
+/**
+ * Return whether two hotkey declarations differ after commit-time cleanup.
+ *
+ * Both values are trimmed before comparison, and `undefined` is treated the
+ * same as an empty or whitespace-only string. Parseable hotkeys compare by
+ * their normalized chord, so casing and modifier order do not matter; strings
+ * that fail parsing fall back to trimmed literal comparison. This matches
+ * persistence forms where absent and cleared hotkeys both mean "no binding".
+ */
+export function hotkeyChanged(
+  prev: string | undefined,
+  next: string | undefined,
+): boolean {
+  return normalizeHotkeyForChange(prev) !== normalizeHotkeyForChange(next);
+}
+
+function normalizeHotkeyForChange(hotkey: string | undefined): string {
+  const trimmed = hotkey?.trim() ?? "";
+
+  if (trimmed.length === 0) return "";
+
+  const parsed = parseHotkey(trimmed);
+
+  return parsed.ok ? parsed.parsed.normalized : trimmed;
+}

package/src/hotkey-reload-baseline.ts

@@ -0,0 +1,112 @@
+/**
+ * Runtime hotkey baseline used to decide whether `/reload` is still needed.
+ *
+ * Owns the in-memory snapshot of hotkeys registered for this extension runtime;
+ * it does NOT own storage reads, conflict analysis, or shortcut registration.
+ */
+import { hotkeyChanged, type PresetIdentity } from "./hotkey-conflicts.js";
+import type { LoadedPreset } from "./types.js";
+
+const acknowledgedPendingHotkeys = new Map<string, string | undefined>();
+const runtimeHotkeys = new Map<string, string | undefined>();
+
+/** Clear runtime hotkey state for tests that exercise prompt decisions. */
+export function clearRuntimeHotkeyBaseline(): void {
+  acknowledgedPendingHotkeys.clear();
+  runtimeHotkeys.clear();
+}
+
+/** Return whether deleting `identity` leaves runtime bindings out of date. */
+export function deleteNeedsHotkeyReload(identity: PresetIdentity): boolean {
+  return commitNeedsHotkeyReload(identity, undefined);
+}
+
+/** Remember a declined prompt so the same pending state is not re-prompted. */
+export function recordReloadPromptDeclined(
+  identity: PresetIdentity & { readonly hotkey?: string | undefined },
+  hotkey = identity.hotkey,
+): void {
+  acknowledgedPendingHotkeys.set(presetKey(identity), hotkey);
+}
+
+/** Return whether saving `saved` leaves runtime bindings out of date. */
+export function saveNeedsHotkeyReload(
+  initial: PresetIdentity | undefined,
+  saved: PresetIdentity & { readonly hotkey?: string | undefined },
+): boolean {
+  if (!commitNeedsHotkeyReload(saved, saved.hotkey)) return false;
+
+  const initialRuntimeHotkey = runtimeHotkeyFor(initial);
+
+  if (!hotkeyChanged(initialRuntimeHotkey, saved.hotkey)) {
+    return (
+      Boolean(initialRuntimeHotkey?.trim()) && identityChanged(initial, saved)
+    );
+  }
+
+  return true;
+}
+
+/** Capture the hotkeys that are actually represented by this runtime. */
+export function setRuntimeHotkeyBaseline(
+  presets: readonly LoadedPreset[],
+): void {
+  acknowledgedPendingHotkeys.clear();
+  runtimeHotkeys.clear();
+
+  for (const preset of presets) {
+    runtimeHotkeys.set(presetKey(preset), preset.hotkey);
+  }
+}
+
+function acknowledgedPendingHotkeyMatches(
+  identity: PresetIdentity & { readonly hotkey?: string | undefined },
+): boolean {
+  if (!acknowledgedPendingHotkeys.has(presetKey(identity))) return false;
+
+  return !hotkeyChanged(
+    acknowledgedPendingHotkeys.get(presetKey(identity)),
+    identity.hotkey,
+  );
+}
+
+function commitNeedsHotkeyReload(
+  identity: PresetIdentity,
+  hotkey: string | undefined,
+): boolean {
+  if (runtimeMatches(identity, hotkey)) {
+    acknowledgedPendingHotkeys.delete(presetKey(identity));
+
+    return false;
+  }
+
+  return !acknowledgedPendingHotkeyMatches({ ...identity, hotkey });
+}
+
+function identityChanged(
+  prev: PresetIdentity | undefined,
+  next: PresetIdentity,
+): boolean {
+  if (!prev) return false;
+
+  return prev.name !== next.name || prev.scope !== next.scope;
+}
+
+function presetKey(identity: PresetIdentity): string {
+  return `${identity.scope}:${identity.name}`;
+}
+
+function runtimeHotkeyFor(
+  identity: PresetIdentity | undefined,
+): string | undefined {
+  if (!identity) return undefined;
+
+  return runtimeHotkeys.get(presetKey(identity));
+}
+
+function runtimeMatches(
+  identity: PresetIdentity,
+  hotkey: string | undefined,
+): boolean {
+  return !hotkeyChanged(runtimeHotkeyFor(identity), hotkey);
+}

package/src/hotkeys.ts

@@ -0,0 +1,104 @@
+/**
+ * Per-preset shortcut registration for pi-presets-plus.
+ *
+ * Owns session-start shortcut registration, conflict/invalid notifications,
+ * and shortcut activation guardrails. It does NOT own hotkey parsing,
+ * conflict marking, persistent storage, or the core preset apply implementation.
+ */
+import { apply } from "./activation/apply.js";
+import {
+  formatPresetIdentity,
+  type HotkeyAnalysis,
+} from "./hotkey-conflicts.js";
+import type { LoadedPreset } from "./types.js";
+import { isPiBuiltin } from "./ui/hotkey-input.js";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@mariozechner/pi-coding-agent";
+import type { KeyId } from "@mariozechner/pi-tui";
+
+export type CurrentPresetsLoader = (
+  ctx: ExtensionContext,
+) => Promise<LoadedPreset[]>;
+
+export function registerHotkeys(
+  pi: ExtensionAPI,
+  ctx: Pick<ExtensionContext, "ui">,
+  presets: LoadedPreset[],
+  hotkeyAnalysis: HotkeyAnalysis,
+  loadCurrentPresets: CurrentPresetsLoader,
+): void {
+  for (const conflict of hotkeyAnalysis.conflicts) {
+    ctx.ui.notify(
+      `${formatPresetSubject(conflict.loser)} hotkey "${conflict.loser.hotkey}" conflicts with preset ${formatPresetIdentity(conflict.winner)}. The first registered wins.`,
+      "warning",
+    );
+  }
+
+  for (const invalid of hotkeyAnalysis.invalid) {
+    ctx.ui.notify(
+      `${formatPresetSubject(invalid.preset)}: invalid hotkey "${invalid.preset.hotkey}" — ignored (${invalid.reason}). It will not be registered or considered for conflicts until fixed.`,
+      "warning",
+    );
+  }
+
+  // Registration is intentionally one-shot because pi exposes no
+  // unregisterShortcut API. loadAll() marks conflicts on every read for the
+  // picker; this notification pass only explains the session-start bindings.
+  for (const preset of presets) {
+    const parsed = hotkeyAnalysis.parsed.get(preset);
+
+    if (!parsed) continue;
+    if (preset.shadowed || preset.hotkeyConflict === true) continue;
+
+    if (isPiBuiltin(parsed)) {
+      ctx.ui.notify(
+        `${formatPresetSubject(preset)} hotkey "${preset.hotkey}" shadows a Pi built-in. The preset binding will take precedence.`,
+        "info",
+      );
+    }
+
+    const registeredName = preset.name;
+    const registeredScope = preset.scope;
+
+    pi.registerShortcut(parsed.normalized as KeyId, {
+      description: `Activate preset "${registeredName}"`,
+      handler: async (handlerCtx) => {
+        try {
+          // Re-read on every press so edits/removals made after session-start
+          // are honored without re-registering shortcuts. This trades a small
+          // amount of I/O for correctness until pi exposes unregister support.
+          const currentPresets = await loadCurrentPresets(handlerCtx);
+          const current = currentPresets.find(
+            (candidate) =>
+              candidate.name === registeredName &&
+              candidate.scope === registeredScope,
+          );
+
+          if (!current) {
+            handlerCtx.ui.notify(
+              `Preset "${registeredName}" no longer exists.`,
+              "warning",
+            );
+
+            return;
+          }
+
+          const result = await apply(current, handlerCtx, pi);
+
+          if (!result.ok) handlerCtx.ui.notify(result.reason, "error");
+        } catch (err) {
+          handlerCtx.ui.notify(
+            `pi-presets-plus failed to activate preset "${registeredName}" from hotkey: ${err instanceof Error ? err.message : String(err)}.`,
+            "error",
+          );
+        }
+      },
+    });
+  }
+}
+
+function formatPresetSubject(preset: Pick<LoadedPreset, "name">): string {
+  return `Preset "${preset.name}"`;
+}

package/src/index.ts

@@ -0,0 +1,171 @@
+/**
+ * pi-presets-plus extension entry point.
+ *
+ * Owns lifecycle wiring with the pi host: command registration, custom
+ * message renderers, session-start pre-warming and restore, instruction
+ * injection, and self-call guards. It does NOT own storage, activation,
+ * or UI internals — those live in their dedicated modules.
+ */
+
+import {
+  clearActive,
+  getActive,
+  setActive,
+} from "./activation/active-state.js";
+import {
+  handleModelSelectDrift,
+  syncDirtyFromCurrentState,
+} from "./activation/drift-handlers.js";
+import { snapshotPresetForDrift } from "./activation/drift.js";
+import {
+  getArgumentCompletions,
+  handlePresetsCommand,
+  surfaceWarnings,
+} from "./commands/presets/index.js";
+import { applyPresetFlag, registerPresetFlag } from "./flag.js";
+import { setRuntimeHotkeyBaseline } from "./hotkey-reload-baseline.js";
+import { registerHotkeys, type CurrentPresetsLoader } from "./hotkeys.js";
+import { ACTIVATED_MESSAGE_TYPE, renderActivatedMessage } from "./messages.js";
+import { loadAll } from "./store/api.js";
+import type { LoadedPreset, PresetScope } from "./types.js";
+import { updateStatus } from "./ui/status.js";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@mariozechner/pi-coding-agent";
+
+interface ActiveEntryData {
+  name: string | null;
+  scope?: PresetScope;
+}
+
+export default function presetsPlus(pi: ExtensionAPI) {
+  pi.registerMessageRenderer(ACTIVATED_MESSAGE_TYPE, renderActivatedMessage);
+  registerPresetFlag(pi);
+
+  pi.registerCommand("presets", {
+    description:
+      "Browse and switch presets that bundle a model, thinking level, tools, and system prompt. Run `/presets` to open the picker, or use `reload`, `clear`, or `status`.",
+    getArgumentCompletions: (prefix) => getArgumentCompletions(prefix),
+    handler: (args, ctx) => handlePresetsCommand(args, ctx, pi),
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    try {
+      const { hotkeyAnalysis, presets, warnings } = await loadAll(ctx);
+
+      surfaceWarnings(ctx, warnings);
+      restoreActiveFromBranch(ctx, presets);
+      await applyPresetFlag(pi, ctx, presets);
+
+      const loadCurrentPresets: CurrentPresetsLoader = async (handlerCtx) =>
+        (await loadAll(handlerCtx)).presets;
+
+      setRuntimeHotkeyBaseline(presets);
+      registerHotkeys(pi, ctx, presets, hotkeyAnalysis, loadCurrentPresets);
+
+      updateStatus(ctx, getActive(), (name, scope) =>
+        presets.find(
+          (preset) => preset.name === name && preset.scope === scope,
+        ),
+      );
+    } catch (err) {
+      ctx.ui.notify(
+        `pi-presets-plus failed to load preset files: ${err instanceof Error ? err.message : String(err)}.`,
+        "error",
+      );
+    }
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    const active = getActive();
+
+    if (!active) return undefined;
+
+    // Don't re-surface warnings here. They were already shown at
+    // session_start and on /presets reload; emitting them on every
+    // agent turn would be noisy when a preset file has issues.
+    const { presets } = await loadAll(ctx);
+
+    const preset = presets.find(
+      (candidate) =>
+        candidate.name === active.name && candidate.scope === active.scope,
+    );
+
+    if (!preset?.instructions) return undefined;
+
+    return { systemPrompt: `${event.systemPrompt}\n\n${preset.instructions}` };
+  });
+
+  pi.on("model_select", async (event, ctx) => {
+    await handleModelSelectDrift(event, ctx, pi);
+  });
+
+  pi.on("thinking_level_select", async (_event, ctx) => {
+    await syncDirtyFromCurrentState(ctx, pi);
+  });
+
+  pi.on("turn_start", async (_event, ctx) => {
+    await syncDirtyFromCurrentState(ctx, pi);
+  });
+}
+
+function restoreActiveFromBranch(
+  ctx: Pick<ExtensionContext, "sessionManager" | "ui">,
+  presets: readonly LoadedPreset[],
+): void {
+  const activeEntry = [...ctx.sessionManager.getBranch()]
+    .reverse()
+    .find(
+      (entry): entry is Extract<typeof entry, { type: "custom" }> =>
+        entry.type === "custom" && entry.customType === "presets-plus:active",
+    );
+
+  if (!activeEntry) {
+    clearActive();
+
+    return;
+  }
+
+  const data = activeEntry.data as ActiveEntryData | undefined;
+
+  if (!data || data.name === null) {
+    clearActive();
+
+    return;
+  }
+
+  const preset = presets.find(
+    (candidate) =>
+      candidate.name === data.name &&
+      candidate.scope === (data.scope ?? "user"),
+  );
+
+  if (!preset) {
+    ctx.ui.notify(
+      `Restored session referenced preset "${data.name}" which is not loaded. Not attaching.`,
+      "warning",
+    );
+    clearActive();
+
+    return;
+  }
+
+  if (preset.unavailable) {
+    ctx.ui.notify(
+      `Restored session referenced preset "${data.name}" which is unavailable (${preset.unavailable}). Not attaching.`,
+      "warning",
+    );
+    clearActive();
+
+    return;
+  }
+
+  setActive({
+    declared: snapshotPresetForDrift(preset),
+    dirty: false,
+    name: preset.name,
+    restore: { kind: "unknown" },
+    scope: preset.scope,
+  });
+}

package/src/messages.ts

@@ -0,0 +1,34 @@
+/**
+ * Custom conversation message types and renderers for pi-presets-plus.
+ *
+ * Owns the message shapes and how they appear in the conversation log; it
+ * does NOT send messages or own activation logic.
+ */
+import type { ThinkingLevel } from "./types.js";
+import type { MessageRenderer } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+
+export const ACTIVATED_MESSAGE_TYPE = "presets-plus:activated";
+
+interface ActivatedMessageDetails {
+  name: string;
+  model: string;
+  thinkingLevel: ThinkingLevel;
+}
+
+export function formatActivatedMessage(
+  details: ActivatedMessageDetails,
+  theme: Parameters<MessageRenderer<ActivatedMessageDetails>>[2],
+): string {
+  return theme.fg("muted", `Preset ${details.name} applied`);
+}
+
+export const renderActivatedMessage: MessageRenderer<
+  ActivatedMessageDetails
+> = (message, _options, theme) => {
+  const details = message.details;
+
+  if (!details) return undefined;
+
+  return new Text(formatActivatedMessage(details, theme));
+};