@leo-alvarenga/pi-qol 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leonardo A. Alvarenga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# pi-qol
+
+Small quality-of-life features for [pi](https://github.com/earendil-works/pi-coding-agent), individually toggleable via a single config file.
+
+## Install
+
+```sh
+pi install npm:@leo-alvarenga/pi-qol
+# or from this repo:
+pi -e ./packages/pi-qol
+```
+
+## Config
+
+All features are enabled by default. Disable any feature in `~/.pi/agent/pi-qol.json` (file is optional):
+
+```jsonc
+{
+  "external-editor-cwd": { "disabled": true },
+}
+```
+
+Run `/reload` after editing any config.
+
+---
+
+## Feature: `external-editor-cwd`
+
+Edit the current prompt in your external editor. The file is written to the current working directory so your editor can pick up project context (`.editorconfig`, LSP, etc.).
+
+**Default key:** `ctrl+shift+e` (Can be set to override the default "Open in Editor" keybinding)
+
+### Choosing the key
+
+```jsonc
+{ "external-editor-cwd": { "keybinding": "native" } }        // take over pi's ctrl+g
+{ "external-editor-cwd": { "keybinding": "ctrl+shift+e" } }  // default
+{ "external-editor-cwd": { "keybinding": "alt+e" } }         // any valid key id
+```
+
+Any invalid value is reported at session start and the extension falls back to `ctrl+shift+e`.
+
+#### `"native"` mode
+
+pi's built-in editor shortcut (`ctrl+g`) is in a reserved list that prevents extensions from claiming it while it is active. Setting `keybinding: "native"` writes `"app.editor.external": []` into `~/.pi/agent/keybindings.json` to release that binding, then prompts you to run `/reload` once. After that single reload, `ctrl+g` opens this extension's editor instead.
+
+- The file reformat is intentional: pi rejects comments in `keybindings.json` anyway
+- Reverting: remove the `[]` entry and switch `keybinding` away from `"native"`
+
+### Editor selection
+
+Follows pi's own order: `settings.json:externalEditor` → `$VISUAL` → `$EDITOR` → `nano` (`notepad` on Windows).
+
+### Behaviour
+
+1. The current prompt is written to `./prompt.md` (or `./prompt-<id>.md` if the file already exists) in the working directory
+2. The TUI suspends and hands the terminal to the editor
+3. **Exit 0:** the file is read back into the prompt editor and deleted
+4. **Non-zero exit or spawn failure:** the file is kept and its path is shown in a warning; your text is safe
+5. **Unwritable cwd:** the file is written to the OS temp dir instead
+6. `super+` bindings require a terminal with [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) support
+7. The shortcut requires the prompt editor to have focus. Extensions that replace the editor component must forward `onExtensionShortcut` for this to work

package/extensions/features/external-editor-cwd/index.ts

@@ -0,0 +1,225 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { randomBytes } from "node:crypto";
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { KeyId } from "@earendil-works/pi-tui";
+
+import type { FeatureConfig } from "../../lib/config";
+import { resolveEditorCommand, spawnEditor } from "../../lib/editor";
+import {
+  getBoundKeys,
+  unbindAction,
+  type UnbindResult,
+} from "../../lib/keybindings";
+import { normalizeKeyId } from "../../lib/keys";
+import type { QolFeature } from "../../lib/types";
+
+type Deps = {
+  unbindAction: (actionIds: string[]) => UnbindResult;
+  getBoundKeys: (actionIds: string[]) => (string[] | undefined)[];
+};
+
+type PromptFile = { path: string; inCwd: boolean };
+
+const DEFAULT_KEY = "ctrl+shift+e";
+
+// app.editor.external is in RESERVED_KEYBINDINGS_FOR_EXTENSION_CONFLICTS with default ctrl+g
+const BUILTIN_ACTIONS = ["app.editor.external", "tui.altScreen.searchNext"];
+const BUILTIN_EDITOR_KEY = "ctrl+g";
+
+let running = false;
+let file: PromptFile | null = null;
+
+/**
+ * Resolve which key to register (or null to skip) based on the user's config.
+ * Exported for testing with injected deps
+ */
+export function resolveKeyBinding(
+  options: FeatureConfig,
+  notices: string[],
+  deps: Deps = { getBoundKeys, unbindAction },
+): string | null {
+  const raw = options["keybinding"];
+
+  if (Array.isArray(raw)) return null;
+  if (raw === undefined) return DEFAULT_KEY;
+
+  if (typeof raw !== "string") {
+    notices.push(
+      `invalid keybinding value (expected string), using ${DEFAULT_KEY}`,
+    );
+
+    return DEFAULT_KEY;
+  }
+
+  if (raw === "native") {
+    const bound = deps.getBoundKeys(BUILTIN_ACTIONS);
+
+    // undefined entry = not in keybindings.json (pi default ctrl+g active); [] = explicitly unbound
+    const ctrlGBound = bound.some((b) => b === undefined || b.length > 0);
+
+    if (!ctrlGBound) return BUILTIN_EDITOR_KEY;
+    const result = deps.unbindAction(BUILTIN_ACTIONS);
+
+    if (!result.ok) {
+      notices.push(result.reason);
+
+      return DEFAULT_KEY;
+    }
+
+    notices.push(
+      `unbound pi's built-in editor key; run \`/reload\` to activate \`${BUILTIN_EDITOR_KEY}\``,
+    );
+
+    return DEFAULT_KEY;
+  }
+
+  const canonical = normalizeKeyId(raw);
+  if (!canonical) {
+    notices.push(`invalid keybinding "${raw}", using ${DEFAULT_KEY}`);
+
+    return DEFAULT_KEY;
+  }
+
+  if (canonical === BUILTIN_EDITOR_KEY) {
+    notices.push(
+      `\`${BUILTIN_EDITOR_KEY}\` is reserved by pi's built-in editor; set \`keybinding: "native"\` to take it over`,
+    );
+
+    return DEFAULT_KEY;
+  }
+
+  return canonical;
+}
+
+function createPromptFile(cwd: string, text: string): PromptFile {
+  const getName = (random?: boolean) =>
+    `prompt${random ? `-${randomBytes(6).toString("base64url")}` : ""}.md`;
+
+  const names = [getName(), getName(true)];
+
+  for (const name of names) {
+    const filePath = join(cwd, name);
+
+    try {
+      writeFileSync(filePath, text, { flag: "wx", encoding: "utf8" });
+
+      return { path: filePath, inCwd: true };
+    } catch (err: unknown) {
+      const code = (err as { code?: string }).code;
+
+      if (code === "EEXIST") continue;
+      if (code === "EACCES" || code === "EROFS" || code === "EPERM") break;
+
+      throw err;
+    }
+  }
+
+  const filePath = join(tmpdir(), getName(true));
+
+  writeFileSync(filePath, text, "utf8");
+  return { path: filePath, inCwd: false };
+}
+
+function rmPromptFile(file: PromptFile): void {
+  try {
+    rmSync(file.path, { force: true });
+  } catch {
+    // ignore
+  }
+}
+
+async function openEditor(ctx: ExtensionContext): Promise<void> {
+  if (ctx.mode !== "tui" || !ctx.hasUI) {
+    ctx.ui.notify(
+      "pi-qol: external editor needs the interactive TUI",
+      "warning",
+    );
+
+    return;
+  }
+
+  if (running) return;
+  running = true;
+
+  try {
+    if (file) rmPromptFile(file);
+
+    file = createPromptFile(ctx.cwd, ctx.ui.getEditorText());
+
+    if (!file.inCwd) {
+      ctx.ui.notify(
+        `pi-qol: cwd not writable, using temp file: ${file.path}`,
+        "warning",
+      );
+    }
+
+    const command = resolveEditorCommand();
+
+    let exit: number | null = null;
+    await ctx.ui.custom<null>(async (tui, _theme, _kb, done) => {
+      if (file) {
+        tui.stop();
+        try {
+          exit = await spawnEditor(command, file.path);
+        } finally {
+          tui.start();
+          tui.requestRender(true);
+        }
+      }
+
+      done(null);
+      return { render: () => [], invalidate() {} };
+    });
+
+    if (exit === 0) {
+      ctx.ui.setEditorText(readFileSync(file.path, "utf8"));
+
+      rmPromptFile(file);
+    } else {
+      ctx.ui.notify(
+        exit === null
+          ? `pi-qol: could not launch "${command}". Prompt kept at ${file.path}`
+          : `pi-qol: editor exited with code ${exit}. Prompt kept at ${file.path}`,
+        "warning",
+      );
+    }
+  } finally {
+    running = false;
+  }
+}
+
+function register(pi: ExtensionAPI, options: FeatureConfig): void {
+  const notices: string[] = [];
+  const key = resolveKeyBinding(options, notices);
+
+  if (key) {
+    pi.registerShortcut(key as KeyId, {
+      handler: openEditor,
+      description: "Edit prompt in external editor (cwd file)",
+    });
+  }
+
+  pi.on("session_start", (_event, ctx) => {
+    if (!ctx.hasUI) return;
+
+    for (const notice of notices.splice(0)) {
+      ctx.ui.notify(`pi-qol: ${notice}`, "warning");
+    }
+  });
+
+  pi.on("session_shutdown", () => {
+    if (file) rmPromptFile(file);
+  });
+}
+
+const feature: QolFeature = {
+  register,
+  name: "external-editor-cwd",
+};
+
+export default feature;

package/extensions/index.ts

@@ -0,0 +1,25 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { featureOptions, isFeatureEnabled, readQolConfig } from "./lib/config";
+import type { QolFeature } from "./lib/types";
+
+import externalEditorCwd from "./features/external-editor-cwd";
+
+const FEATURES: QolFeature[] = [externalEditorCwd];
+
+export default function (pi: ExtensionAPI) {
+  const config = readQolConfig();
+  for (const feature of FEATURES) {
+    if (!isFeatureEnabled(config, feature.name)) continue;
+
+    try {
+      feature.register(pi, featureOptions(config, feature.name));
+    } catch (error) {
+      // One broken feature must not take the others down with it
+      console.warn(
+        `pi-qol: feature "${feature.name}" failed to register:`,
+        error,
+      );
+    }
+  }
+}

package/extensions/lib/config.ts

@@ -0,0 +1,29 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { readJsonObject } from "./json";
+
+export type QolConfig = Record<string, FeatureConfig | undefined>;
+export type FeatureConfig = { disabled?: boolean; [option: string]: unknown };
+
+export const QOL_CONFIG_FILE = "pi-qol.json";
+
+export function getQolConfigPath(): string {
+  return join(getAgentDir(), QOL_CONFIG_FILE);
+}
+
+export function readQolConfig(): QolConfig {
+  return readJsonObject(getQolConfigPath()) as QolConfig;
+}
+
+/** All features are enabled unless explicitly disabled. */
+export function isFeatureEnabled(config: QolConfig, feature: string): boolean {
+  return config[feature]?.disabled !== true;
+}
+
+/** Options for one feature; `{}` when absent, so features never handle undefined. */
+export function featureOptions(
+  config: QolConfig,
+  feature: string,
+): FeatureConfig {
+  return config[feature] ?? {};
+}

package/extensions/lib/editor.ts

@@ -0,0 +1,42 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { readJsonObject } from "./json";
+
+/** `settings.json:externalEditor` -> $VISUAL -> $EDITOR -> "notepad" (win32) | "nano" */
+export function resolveEditorCommand(): string {
+  const settings = readJsonObject(join(getAgentDir(), "settings.json"));
+
+  const configured = settings["externalEditor"];
+
+  if (typeof configured === "string" && configured.trim() !== "") {
+    return configured.trim();
+  }
+
+  const env = process.env["VISUAL"] || process.env["EDITOR"];
+  if (env) return env;
+
+  return process.platform === "win32" ? "notepad" : "nano";
+}
+
+/**
+ * Hand the terminal to the editor for `filePath` and resolve with its exit code
+ * (null when the editor could not be spawned).
+ * Caller is responsible for stopping/starting the TUI first
+ */
+export function spawnEditor(
+  command: string,
+  filePath: string,
+): Promise<number | null> {
+  const [editor, ...args] = command.split(" ");
+
+  return new Promise((resolve) => {
+    const child = spawn(editor!, [...args, filePath], {
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+
+    child.on("error", () => resolve(null));
+    child.on("close", (code) => resolve(code));
+  });
+}

package/extensions/lib/json.ts

@@ -0,0 +1,21 @@
+import { readFileSync } from "node:fs";
+
+/** Read a JSON object from disk (BOM-tolerant). Missing, unreadable, or malformed input yields {}. Never throws */
+export function readJsonObject(path: string): Record<string, unknown> {
+  try {
+    const raw = readFileSync(path, "utf8").replace(/^\uFEFF/, "");
+    const parsed = JSON.parse(raw);
+
+    if (
+      parsed !== null &&
+      typeof parsed === "object" &&
+      !Array.isArray(parsed)
+    ) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    // missing, unreadable, or malformed
+  }
+
+  return {};
+}

package/extensions/lib/keybindings.ts

@@ -0,0 +1,85 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { readJsonObject } from "./json";
+
+export type UnbindResult =
+  | { ok: false; reason: string }
+  | { ok: true; replaced: (string | string[] | undefined)[] };
+
+export function getKeybindingsPath(): string {
+  return join(getAgentDir(), "keybindings.json");
+}
+
+export function readKeybindings(): Record<string, unknown> {
+  return readJsonObject(getKeybindingsPath());
+}
+
+/** Keys currently bound to one pi action id, or undefined when unset. `[]` stays [] */
+export function getBoundKeys(actionIds: string[]): (string[] | undefined)[] {
+  return actionIds.map((actionId) => {
+    const raw = readKeybindings()[actionId];
+    if (typeof raw === "string") return [raw];
+
+    if (Array.isArray(raw) && raw.every((v) => typeof v === "string")) {
+      return raw as string[];
+    }
+
+    return undefined;
+  });
+}
+
+/** Set `actionId` to [] in keybindings.json, preserving every other entry */
+export function unbindAction(actionIds: string[]): UnbindResult {
+  const path = getKeybindingsPath();
+  let current: Record<string, unknown> = {};
+
+  try {
+    const raw = readFileSync(path, "utf8").replace(/^\uFEFF/, "");
+    try {
+      const parsed = JSON.parse(raw);
+
+      if (
+        parsed !== null &&
+        typeof parsed === "object" &&
+        !Array.isArray(parsed)
+      ) {
+        current = parsed as Record<string, unknown>;
+      }
+    } catch {
+      return { ok: false, reason: "keybindings.json is not valid JSON" };
+    }
+  } catch (err: unknown) {
+    const code = (err as { code?: string }).code;
+
+    // ENOENT: file doesn't exist, we'll create it
+    if (code !== "ENOENT") {
+      return { ok: false, reason: String(err) };
+    }
+  }
+
+  const replaced: (string | string[] | undefined)[] = [];
+
+  for (const actionId of actionIds) {
+    const previous = current[actionId];
+    current[actionId] = [];
+
+    replaced.push(
+      typeof previous === "string"
+        ? previous
+        : Array.isArray(previous)
+          ? (previous as string[])
+          : undefined,
+    );
+
+    current[actionId] = [];
+  }
+
+  try {
+    writeFileSync(path, JSON.stringify(current, null, 2) + "\n", "utf8");
+  } catch (err: unknown) {
+    return { ok: false, reason: String(err) };
+  }
+
+  return { ok: true, replaced };
+}

package/extensions/lib/keys.ts

@@ -0,0 +1,38 @@
+import { Key } from "@earendil-works/pi-tui";
+
+// Built from pi-tui's own table so we never maintain a hand-copied key list.
+const BASE_KEYS = new Map<string, string>();
+
+for (const value of Object.values(Key)) {
+  if (typeof value === "string") BASE_KEYS.set(value.toLowerCase(), value);
+}
+
+for (const c of "abcdefghijklmnopqrstuvwxyz0123456789") BASE_KEYS.set(c, c);
+
+const MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
+const MAX_PARTS = 5; // 4 modifiers + 1 key
+
+/** Canonical key id, or null when the string is not a valid keybinding. */
+export function normalizeKeyId(value: string): string | null {
+  const parts = value.trim().split("+");
+
+  if (parts.length === 0 || parts.length > MAX_PARTS) return null;
+
+  const key = BASE_KEYS.get(parts.at(-1)!.toLowerCase());
+  if (!key) return null;
+
+  const modifiers: string[] = [];
+  for (const raw of parts.slice(0, -1)) {
+    const modifier = raw.trim().toLowerCase();
+    if (!MODIFIERS.has(modifier) || modifiers.includes(modifier)) return null;
+
+    modifiers.push(modifier);
+  }
+
+  return [...modifiers, key].join("+");
+}
+
+/** True when `value` names a valid key id. */
+export function isValidKeyId(value: string): boolean {
+  return normalizeKeyId(value) !== null;
+}

package/extensions/lib/types.ts

@@ -0,0 +1,8 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { FeatureConfig } from "./config";
+
+/** A self-contained QoL feature. `name` must match its `pi-qol.json` key. */
+export interface QolFeature {
+  name: string;
+  register(pi: ExtensionAPI, options: FeatureConfig): void;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@leo-alvarenga/pi-qol",
+  "version": "0.1.1",
+  "description": "Small quality-of-life features for pi, individually toggleable",
+  "author": "Leonardo A. Alvarenga",
+  "license": "MIT",
+  "repository": "github.com/leo-alvarenga/pi-mono",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-extension",
+    "pi-package",
+    "pi"
+  ],
+  "files": [
+    "extensions",
+    "!extensions/lib/test",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}