pi-snippets 1.0.0

package/README.md

@@ -0,0 +1,109 @@
+# Pi Snippets
+
+Zero-keystroke snippet auto-expander for [pi](https://pi.dev).
+
+Type a trigger word and it instantly expands on the last keystroke — no delimiter,
+no confirmation needed. Just natural typing flow.
+
+## Quick Start
+
+```bash
+# Install from a local clone
+pi install ./pi-snippets
+
+# Or test without installing
+pi -e ./pi-snippets/extensions/index.ts
+
+# Install from npm (once published)
+pi install npm:pi-snippets
+```
+
+## Getting Started
+
+**No snippets are bundled.** You start with a blank slate and add exactly what you need.
+
+## Adding Snippets
+
+### Using `/add` (recommended)
+
+Add snippets directly from inside pi — no file editing, no `/reload`:
+
+```
+/add eml : user@example.com
+/add lgtm : Looks good to me! 👍
+/add sum : Summarize the following:
+
+```
+
+Remove snippets with the interactive `/remove` command — a TUI picker lets you check off which ones to delete.
+
+The snippet takes effect **instantly** — start typing the trigger immediately.
+Saved to `~/.pi/agent/snippets.json` so it persists across sessions.
+
+### Editing the file directly
+
+You can also edit `~/.pi/agent/snippets.json` directly:
+
+```json
+{
+  "sig": "Best regards,\nJane Doe",
+  "sum": "Summarize the following:\n\n",
+  "lgtm": "Looks good to me! 👍"
+}
+```
+
+Then `/reload` inside pi (or restart).
+
+### Project-level (shared with your team)
+
+Create `.pi/snippets.json` in your project root and commit it to git.
+Project snippets only load when the project is trusted.
+
+### Priority (later sources override earlier ones)
+
+1. Project (`.pi/snippets.json`, trusted projects only) — highest priority
+2. User global (`~/.pi/agent/snippets.json`)
+3. Bundled defaults (shipped with this package) — lowest priority (fallback)
+
+## How It Works
+
+The extension replaces pi's input editor with a custom editor that intercepts every
+keystroke. As soon as you finish typing a trigger word, it expands instantly — the
+last character of the trigger itself fires the expansion.
+
+- **Instant expansion:** No delimiter required — the moment you type the final
+  character of a trigger word, it expands to your defined text.
+- **Word-boundary safe:** The trigger must be a complete whitespace-delimited token
+  (or at the very start of input). Typing `sig` inside `design` won't trigger
+  expansion because `sig` is not at a word boundary.
+- **Compatible:** Works alongside other extensions. Wraps any existing custom editor
+  via `getEditorComponent()` to preserve composability.
+
+## Trigger Guidelines
+
+Choose triggers that are **not common English words or prefixes of other triggers**
+to avoid accidental or premature expansion:
+
+- ✅ `sig`, `tpl`, `dbg` — abbreviation-like, unlikely to be typed by accident
+- ⚠️ `fix`, `todo`, `bug` — common words that might trigger mid-sentence
+- ⚠️ `db` / `dbg` — overlapping prefixes can cause the shorter trigger to fire early
+- ❌ `a`, `i`, `q` — single-letter triggers are very prone to false positives
+
+Multi-character, abbreviation-style triggers work best. Avoid triggers that are
+prefixes of each other.
+
+## Publishing to npm
+
+```bash
+cd pi-snippets
+npm publish --access public
+```
+
+Then users install with:
+```bash
+pi install npm:pi-snippets
+```
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,451 @@
+/**
+ * Pi Snippet Auto-Expander
+ *
+ * Zero-keystroke snippet expansion: type a trigger word and it expands
+ * instantly on the last keystroke — no delimiter, no confirmation.
+ *
+ * Expansion fires as soon as you finish typing a complete trigger word.
+ * The trigger must be at a word boundary (preceded by whitespace or at
+ * the start of input) to prevent mid-word false positives.
+ *
+ * Three-tier config (later sources override earlier ones):
+ *   1. Project           (.pi/snippets.json, trusted projects only)  ← highest
+ *   2. User global       (~/.pi/agent/snippets.json)
+ *   3. Bundled defaults  (snippets.json shipped with this package)   ← lowest
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  CONFIG_DIR_NAME,
+  CustomEditor,
+  DynamicBorder,
+  type KeybindingsManager,
+} from "@earendil-works/pi-coding-agent";
+import { matchesKey, Key, truncateToWidth } from "@earendil-works/pi-tui";
+import type { TUI, EditorTheme } from "@earendil-works/pi-tui";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ── Snippet loading ────────────────────────────────────────────
+
+interface LoadResult {
+  map: Map<string, string>;
+  errors: string[];
+}
+
+function loadSnippetMap(
+  extensionDir: string,
+  cwd: string,
+  isTrusted: boolean,
+): LoadResult {
+  const map = new Map<string, string>();
+  const errors: string[] = [];
+
+  function mergeFile(filePath: string, label: string): void {
+    if (!existsSync(filePath)) return;
+    try {
+      const raw = readFileSync(filePath, "utf-8");
+      const data = JSON.parse(raw);
+      if (typeof data !== "object" || data === null) {
+        errors.push(`${label}: expected a JSON object, got ${typeof data}`);
+        return;
+      }
+      for (const [key, value] of Object.entries(data)) {
+        if (typeof value === "string" && value.length > 0) {
+          map.set(key, value);
+        }
+      }
+    } catch (err: any) {
+      errors.push(`${label} (${filePath}): ${err.message}`);
+    }
+  }
+
+  // 1. Bundled defaults (lowest priority — loaded first, overridden by later sources)
+  mergeFile(resolve(extensionDir, "..", "snippets.json"), "bundled");
+
+  // 2. User global overrides
+  mergeFile(
+    resolve(homedir(), CONFIG_DIR_NAME, "agent", "snippets.json"),
+    "user-global",
+  );
+
+  // 3. Project overrides (highest priority — loaded last, wins over all) (only if trusted)
+  if (isTrusted) {
+    mergeFile(
+      resolve(cwd, CONFIG_DIR_NAME, "snippets.json"),
+      "project",
+    );
+  }
+
+  return { map, errors };
+}
+
+// ── Snippet Editor ─────────────────────────────────────────────
+
+class SnippetEditor extends CustomEditor {
+  private snippets: Map<string, string>;
+  private innerEditor: CustomEditor | null;
+
+  constructor(
+    tui: TUI,
+    theme: EditorTheme,
+    kb: KeybindingsManager,
+    snippets: Map<string, string>,
+    innerEditor: CustomEditor | null = null,
+  ) {
+    super(tui, theme, kb);
+    this.snippets = snippets;
+    this.innerEditor = innerEditor;
+  }
+
+  handleInput(data: string): void {
+    // On every printable keystroke, check if we just completed a trigger word.
+    // The trigger must be preceded by whitespace or be at the start of input
+    // — this prevents mid-word false positives like "unpredictable" firing on "npr".
+    if (data.length === 1 && /[a-zA-Z0-9_]/.test(data)) {
+      const potentialText = this.getText() + data;
+
+      for (const [trigger, expansion] of this.snippets) {
+        if (potentialText.endsWith(trigger)) {
+          const prefixIndex = potentialText.length - trigger.length;
+          const isWordStart =
+            prefixIndex === 0 || /\s/.test(potentialText[prefixIndex - 1]);
+
+          if (isWordStart) {
+            // Expand immediately — no delimiter needed
+            this.setText(potentialText.slice(0, prefixIndex) + expansion);
+            return; // Don't let super insert the raw keystroke
+          }
+        }
+      }
+    }
+
+    // All other keys (backspace, arrows, enter, etc.) pass through normally.
+    // If we're wrapping another custom editor, delegate to it first.
+    if (this.innerEditor) {
+      this.innerEditor.handleInput(data);
+    } else {
+      super.handleInput(data);
+    }
+  }
+}
+
+// ── Module-level state ─────────────────────────────────────────
+// Hoisted so the /add and /remove commands can update the editor live.
+
+let currentSnippets: Map<string, string> | null = null;
+let baseEditorFactory: ReturnType<
+  import("@earendil-works/pi-coding-agent").ExtensionUIContext["getEditorComponent"]
+> = null;
+
+function rebuildEditor(
+  ctx: { ui: { setEditorComponent: Function; getEditorComponent: Function } },
+): void {
+  ctx.ui.setEditorComponent((tui: TUI, theme: EditorTheme, kb: KeybindingsManager) => {
+    const inner = baseEditorFactory ? baseEditorFactory(tui, theme, kb) : null;
+    return new SnippetEditor(tui, theme, kb, currentSnippets!, inner);
+  });
+}
+
+// ── Persistent snippet storage ─────────────────────────────────
+
+function userSnippetsPath(): string {
+  return resolve(homedir(), CONFIG_DIR_NAME, "agent", "snippets.json");
+}
+
+function writeUserSnippet(trigger: string, expansion: string): void {
+  const filePath = userSnippetsPath();
+  let data: Record<string, string> = {};
+
+  if (existsSync(filePath)) {
+    try {
+      const raw = readFileSync(filePath, "utf-8");
+      data = JSON.parse(raw);
+      if (typeof data !== "object" || data === null) {
+        data = {};
+      }
+    } catch {
+      data = {}; // corrupt file → start fresh
+    }
+  }
+
+  data[trigger] = expansion;
+
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8");
+}
+
+function removeUserSnippets(triggers: string[]): void {
+  const filePath = userSnippetsPath();
+  if (!existsSync(filePath)) return;
+
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    const data = JSON.parse(raw);
+    if (typeof data !== "object" || data === null) return;
+
+    for (const trigger of triggers) {
+      delete data[trigger];
+    }
+
+    writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8");
+  } catch {
+    // If we can't write, the in-memory state still reflects the removal
+  }
+}
+
+// ── Extension entry point ──────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+  // ── /add command ──
+  pi.registerCommand("add", {
+    description:
+      "Add a snippet (e.g. /add eml : user@email.com)",
+    handler: async (args, ctx) => {
+      if (!args || !args.includes(":")) {
+        ctx.ui.notify(
+          "Usage: /add <trigger> : <expansion>\n" +
+            "  trigger   — word that expands when typed\n" +
+            "  expansion — text to replace it with",
+          "warning",
+        );
+        return;
+      }
+
+      const colonIndex = args.indexOf(":");
+      const trigger = args.slice(0, colonIndex).trim();
+      const expansion = args.slice(colonIndex + 1).trim();
+
+      if (!trigger) {
+        ctx.ui.notify("Snippet trigger cannot be empty.", "error");
+        return;
+      }
+      if (!expansion) {
+        ctx.ui.notify("Snippet expansion cannot be empty.", "error");
+        return;
+      }
+      if (/\s/.test(trigger)) {
+        ctx.ui.notify(
+          "Snippet trigger must be a single word (no spaces).",
+          "error",
+        );
+        return;
+      }
+
+      try {
+        // Persist to user-global snippets file
+        writeUserSnippet(trigger, expansion);
+
+        // Update in-memory map so it takes effect immediately
+        if (currentSnippets) {
+          currentSnippets.set(trigger, expansion);
+        }
+
+        // Rebuild the editor with the updated snippet map
+        rebuildEditor(ctx);
+
+        ctx.ui.notify(
+          `✓ Snippet added: "${trigger}" → "${expansion}"`,
+          "info",
+        );
+      } catch (err: any) {
+        ctx.ui.notify(`Failed to save snippet: ${err.message}`, "error");
+      }
+    },
+  });
+
+  // ── /remove command ──
+  pi.registerCommand("remove", {
+    description:
+      "Remove snippets interactively — choose from a list with multi-select",
+    handler: async (_args, ctx) => {
+      if (!currentSnippets || currentSnippets.size === 0) {
+        ctx.ui.notify("No snippets to remove.", "warning");
+        return;
+      }
+
+      const entries: { trigger: string; expansion: string }[] = [];
+      for (const [trigger, expansion] of currentSnippets) {
+        entries.push({ trigger, expansion });
+      }
+
+      const result = await ctx.ui.custom<number[] | null>(
+        (tui, theme, _kb, done) => {
+          let selected = 0;
+          const checked = new Set<number>();
+
+          const renderList = (w: number): string[] => {
+            const lines: string[] = [];
+            const maxPreview = Math.max(w - 14, 10);
+
+            // Top border
+            lines.push(
+              ...new DynamicBorder((s: string) => theme.fg("accent", s)).render(w),
+            );
+
+            // Title
+            lines.push(
+              truncateToWidth(
+                theme.fg("accent", theme.bold("Remove Snippets")),
+                w,
+              ),
+            );
+
+            // Items
+            for (let i = 0; i < entries.length; i++) {
+              const { trigger, expansion } = entries[i];
+              const cursor = i === selected ? theme.fg("accent", "▶") : " ";
+              const mark = checked.has(i)
+                ? theme.fg("success", "[✓]")
+                : theme.fg("dim", "[ ]");
+              const preview =
+                expansion.length > maxPreview
+                  ? expansion.slice(0, maxPreview - 1) + "…"
+                  : expansion;
+
+              lines.push(
+                truncateToWidth(
+                  ` ${cursor} ${mark} ${theme.fg("accent", trigger)} → ${theme.fg("dim", preview)}`,
+                  w,
+                ),
+              );
+            }
+
+            // Help bar
+            lines.push("");
+            lines.push(
+              truncateToWidth(
+                theme.fg(
+                  "dim",
+                  "↑↓ navigate  Space toggle  A select all  Enter remove  Esc cancel",
+                ),
+                w,
+              ),
+            );
+
+            // Bottom border
+            lines.push(
+              ...new DynamicBorder((s: string) => theme.fg("accent", s)).render(w),
+            );
+
+            return lines;
+          };
+
+          let cachedW = -1;
+          let cachedLines: string[] = [];
+
+          return {
+            render(w: number): string[] {
+              if (w !== cachedW) {
+                cachedW = w;
+                cachedLines = renderList(w);
+              }
+              return cachedLines;
+            },
+            invalidate(): void {
+              cachedW = -1;
+            },
+            handleInput(data: string): void {
+              let changed = false;
+              if (matchesKey(data, Key.up)) {
+                if (selected > 0) {
+                  selected--;
+                  changed = true;
+                }
+              } else if (matchesKey(data, Key.down)) {
+                if (selected < entries.length - 1) {
+                  selected++;
+                  changed = true;
+                }
+              } else if (matchesKey(data, Key.space)) {
+                if (checked.has(selected)) {
+                  checked.delete(selected);
+                } else {
+                  checked.add(selected);
+                }
+                changed = true;
+              } else if (data === "a" || data === "A") {
+                if (checked.size === entries.length) {
+                  checked.clear();
+                } else {
+                  for (let i = 0; i < entries.length; i++) checked.add(i);
+                }
+                changed = true;
+              } else if (matchesKey(data, Key.enter)) {
+                done(Array.from(checked));
+                return;
+              } else if (matchesKey(data, Key.escape)) {
+                done(null);
+                return;
+              }
+              if (changed) {
+                cachedW = -1;
+                tui.requestRender();
+              }
+            },
+          };
+        },
+      );
+
+      if (result === null) return; // cancelled
+
+      if (result.length === 0) {
+        ctx.ui.notify("No snippets selected for removal.", "info");
+        return;
+      }
+
+      // Remove selected snippets from in-memory map
+      const removed: string[] = [];
+      for (const idx of result) {
+        const { trigger } = entries[idx];
+        if (currentSnippets) currentSnippets.delete(trigger);
+        removed.push(trigger);
+      }
+
+      // Persist removal to user-global file
+      removeUserSnippets(removed);
+
+      // Rebuild editor with updated snippet map
+      rebuildEditor(ctx);
+
+      ctx.ui.notify(
+        `✓ Removed ${removed.length} snippet(s): ${removed.join(", ")}`,
+        "info",
+      );
+    },
+  });
+
+  // ── Lifecycle ──
+  pi.on("session_start", (_event, ctx) => {
+    // Resolve the extension's own directory to find bundled snippets.json
+    const extensionDir = dirname(fileURLToPath(import.meta.url));
+    const { map: snippets, errors } = loadSnippetMap(
+      extensionDir,
+      ctx.cwd,
+      ctx.isProjectTrusted(),
+    );
+
+    // Report any parse errors
+    for (const err of errors) {
+      ctx.ui.notify(`[snippets] ${err}`, "warning");
+    }
+
+    // Stash state so /add can update it live
+    currentSnippets = snippets;
+    baseEditorFactory = ctx.ui.getEditorComponent();
+    rebuildEditor(ctx);
+  });
+
+  // Clean up on shutdown: restore default editor
+  pi.on("session_shutdown", (_event, ctx) => {
+    currentSnippets = null;
+    baseEditorFactory = null;
+    ctx.ui.setEditorComponent(undefined);
+  });
+}

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "pi-snippets",
+  "version": "1.0.0",
+  "description": "Zero-keystroke snippet auto-expander for pi — type a trigger word, hit space, and it expands",
+  "keywords": ["pi-package", "pi-snippets", "pi-extension", "snippets", "text-expander"],
+  "license": "MIT",
+  "author": "",
+  "pi": {
+    "extensions": ["./extensions"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  }
+}

package/snippets.json

@@ -0,0 +1 @@
+{}