@foxfirecodes/pi-stash 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# @foxfirecodes/pi-stash
+
+## 0.1.0
+
+### Minor Changes
+
+- Add prompt stash/restore shortcut with configurable keybinding.
+- Replace an existing stash when the stash shortcut is pressed with editor text present.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 foxfirecodes
+
+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,55 @@
+# pi-stash
+
+Pi package that adds a prompt stash shortcut for the interactive editor.
+
+## Behavior
+
+Press the stash keybinding to push the current prompt aside and clear the editor. Press it again with an empty editor to restore the stashed prompt. If the editor has text while a prompt is already stashed, pressing the stash keybinding replaces the old stash with the current editor text.
+
+You can also send another message while a prompt is stashed; pi-stash will restore the stashed prompt back into the editor immediately after that message is submitted.
+
+This is useful when you have a longer prompt drafted but want to quickly ask or send something else first.
+
+## Keybinding
+
+The default keybinding is `ctrl+s`.
+
+You can customize it with the `--pi-stash-key` extension flag:
+
+```bash
+pi --pi-stash-key ctrl+x
+```
+
+Or with an environment variable:
+
+```bash
+PI_STASH_KEY=ctrl+x pi
+```
+
+The key string uses pi's key format, for example `ctrl+x`, `ctrl+shift+s`, or `alt+s`. If your terminal swallows `ctrl+s` for flow control, choose a different key or disable XON/XOFF flow control in your shell.
+
+## Install
+
+```bash
+pi install npm:@foxfirecodes/pi-stash
+```
+
+## Development
+
+From this checkout:
+
+```bash
+pi install .
+```
+
+Or try it for one run:
+
+```bash
+pi -e /path/to/pi-extensions/packages/pi-stash
+```
+
+To run automated tests:
+
+```bash
+pnpm test
+```

package/extensions/pi-stash.js

@@ -0,0 +1,93 @@
+const DEFAULT_STASH_KEY = "ctrl+s";
+const KEYBIND_FLAG = "pi-stash-key";
+const STATUS_ID = "pi-stash";
+
+function configuredKeybind(pi) {
+  const flagValue = pi.getFlag(KEYBIND_FLAG);
+  return typeof flagValue === "string" ? flagValue : DEFAULT_STASH_KEY;
+}
+
+function formatStatus(ctx, keybind) {
+  const text = `stash:${keybind}`;
+  return ctx.ui.theme?.fg ? ctx.ui.theme.fg("accent", text) : text;
+}
+
+export default function piStash(pi) {
+  let stashedPrompt;
+  let restoreAfterNextMessage = false;
+  let keybind = DEFAULT_STASH_KEY;
+
+  function updateStatus(ctx) {
+    if (!ctx.hasUI) return;
+    ctx.ui.setStatus(
+      STATUS_ID,
+      stashedPrompt === undefined ? undefined : formatStatus(ctx, keybind),
+    );
+  }
+
+  function restorePrompt(ctx, { notify = true } = {}) {
+    if (!ctx.hasUI || stashedPrompt === undefined) return false;
+
+    const prompt = stashedPrompt;
+    stashedPrompt = undefined;
+    restoreAfterNextMessage = false;
+
+    ctx.ui.setEditorText(prompt);
+    updateStatus(ctx);
+
+    if (notify) {
+      ctx.ui.notify("Restored stashed prompt.", "info");
+    }
+
+    return true;
+  }
+
+  function stashOrRestorePrompt(ctx) {
+    if (!ctx.hasUI) return;
+
+    const currentPrompt = ctx.ui.getEditorText();
+    if (currentPrompt.trim()) {
+      stashedPrompt = currentPrompt;
+      restoreAfterNextMessage = true;
+
+      ctx.ui.setEditorText("");
+      updateStatus(ctx);
+      ctx.ui.notify(
+        `Prompt stashed. Press ${keybind} again or send the next message to restore it.`,
+        "info",
+      );
+      return;
+    }
+
+    if (restorePrompt(ctx)) return;
+
+    ctx.ui.notify("No prompt to stash.", "info");
+  }
+
+  pi.registerFlag(KEYBIND_FLAG, {
+    description: `Keybinding for pi-stash prompt stash/restore (default: ${DEFAULT_STASH_KEY})`,
+    type: "string",
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    keybind = configuredKeybind(pi);
+    pi.registerShortcut(keybind, {
+      description: "Stash or restore the current prompt",
+      handler: stashOrRestorePrompt,
+    });
+    updateStatus(ctx);
+  });
+
+  pi.on("input", async (event, ctx) => {
+    if (
+      event.source !== "interactive" ||
+      !restoreAfterNextMessage ||
+      stashedPrompt === undefined
+    ) {
+      return { action: "continue" };
+    }
+
+    restorePrompt(ctx);
+    return { action: "continue" };
+  });
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@foxfirecodes/pi-stash",
+  "version": "0.1.0",
+  "description": "Pi extension that adds a shortcut to stash and restore the current prompt.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "prompt",
+    "shortcut",
+    "stash"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/foxfirecodes/pi-extensions.git",
+    "directory": "packages/pi-stash"
+  },
+  "bugs": {
+    "url": "https://github.com/foxfirecodes/pi-extensions/issues"
+  },
+  "homepage": "https://github.com/foxfirecodes/pi-extensions/tree/main/packages/pi-stash#readme",
+  "pi": {
+    "extensions": [
+      "./extensions/pi-stash.js"
+    ]
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
+}

package/test/pi-stash.test.js

@@ -0,0 +1,182 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import piStash from "../extensions/pi-stash.js";
+
+function createPi({ flagValue } = {}) {
+  const handlers = new Map();
+  const shortcuts = [];
+  const flags = [];
+
+  return {
+    flags,
+    handlers,
+    shortcuts,
+    on(event, handler) {
+      const list = handlers.get(event) ?? [];
+      list.push(handler);
+      handlers.set(event, list);
+    },
+    registerFlag(name, options) {
+      flags.push({ name, options });
+    },
+    getFlag(name) {
+      assert.equal(name, "pi-stash-key");
+      return flagValue;
+    },
+    registerShortcut(shortcut, options) {
+      shortcuts.push({ shortcut, options });
+    },
+  };
+}
+
+function createContext(initialText = "") {
+  let editorText = initialText;
+  const notifications = [];
+  const statuses = new Map();
+
+  return {
+    ctx: {
+      hasUI: true,
+      ui: {
+        getEditorText() {
+          return editorText;
+        },
+        setEditorText(nextText) {
+          editorText = nextText;
+        },
+        notify(message, type) {
+          notifications.push({ message, type });
+        },
+        setStatus(id, text) {
+          statuses.set(id, text);
+        },
+        theme: {
+          fg(_color, text) {
+            return text;
+          },
+        },
+      },
+    },
+    notifications,
+    statuses,
+    get editorText() {
+      return editorText;
+    },
+  };
+}
+
+async function loadExtension({ flagValue } = {}) {
+  const pi = createPi({ flagValue });
+  piStash(pi);
+
+  assert.equal(pi.flags.length, 1);
+  assert.equal(pi.flags[0].name, "pi-stash-key");
+
+  const sessionStartHandlers = pi.handlers.get("session_start") ?? [];
+  assert.equal(sessionStartHandlers.length, 1);
+
+  const context = createContext();
+  await sessionStartHandlers[0]({}, context.ctx);
+
+  return { pi, context };
+}
+
+test("registers a default ctrl+s stash shortcut", async () => {
+  const { pi } = await loadExtension();
+
+  assert.equal(pi.shortcuts.length, 1);
+  assert.equal(pi.shortcuts[0].shortcut, "ctrl+s");
+  assert.equal(typeof pi.shortcuts[0].options.handler, "function");
+});
+
+test("uses the pi-stash-key flag when provided", async () => {
+  const { pi } = await loadExtension({ flagValue: "ctrl+x" });
+
+  assert.equal(pi.shortcuts.length, 1);
+  assert.equal(pi.shortcuts[0].shortcut, "ctrl+x");
+});
+
+test("stashes current editor text and restores it on the next shortcut press", async () => {
+  const { pi } = await loadExtension();
+  const context = createContext("draft prompt");
+  const handler = pi.shortcuts[0].options.handler;
+
+  await handler(context.ctx);
+
+  assert.equal(context.editorText, "");
+  assert.equal(context.statuses.get("pi-stash"), "stash:ctrl+s");
+
+  await handler(context.ctx);
+
+  assert.equal(context.editorText, "draft prompt");
+  assert.equal(context.statuses.get("pi-stash"), undefined);
+});
+
+test("overwrites an existing stash when the editor has text", async () => {
+  const { pi } = await loadExtension();
+  const context = createContext("first draft");
+  const handler = pi.shortcuts[0].options.handler;
+
+  await handler(context.ctx);
+  context.ctx.ui.setEditorText("second draft");
+
+  await handler(context.ctx);
+
+  assert.equal(context.editorText, "");
+  assert.equal(context.statuses.get("pi-stash"), "stash:ctrl+s");
+
+  await handler(context.ctx);
+
+  assert.equal(context.editorText, "second draft");
+  assert.equal(context.statuses.get("pi-stash"), undefined);
+});
+
+test("restores stashed prompt after the next interactive message is sent", async () => {
+  const { pi } = await loadExtension();
+  const context = createContext("draft prompt");
+  const shortcutHandler = pi.shortcuts[0].options.handler;
+  const inputHandler = pi.handlers.get("input")[0];
+
+  await shortcutHandler(context.ctx);
+  context.ctx.ui.setEditorText("quick question");
+
+  const result = await inputHandler(
+    { text: "quick question", images: [], source: "interactive" },
+    context.ctx,
+  );
+
+  assert.deepEqual(result, { action: "continue" });
+  assert.equal(context.editorText, "draft prompt");
+  assert.equal(context.statuses.get("pi-stash"), undefined);
+});
+
+test("does not restore for extension-injected messages", async () => {
+  const { pi } = await loadExtension();
+  const context = createContext("draft prompt");
+  const shortcutHandler = pi.shortcuts[0].options.handler;
+  const inputHandler = pi.handlers.get("input")[0];
+
+  await shortcutHandler(context.ctx);
+  context.ctx.ui.setEditorText("");
+
+  await inputHandler(
+    { text: "generated", images: [], source: "extension" },
+    context.ctx,
+  );
+
+  assert.equal(context.editorText, "");
+  assert.equal(context.statuses.get("pi-stash"), "stash:ctrl+s");
+});
+
+test("does not stash an empty prompt", async () => {
+  const { pi } = await loadExtension();
+  const context = createContext("   ");
+  const handler = pi.shortcuts[0].options.handler;
+
+  await handler(context.ctx);
+
+  assert.equal(context.editorText, "   ");
+  assert.equal(context.statuses.get("pi-stash"), undefined);
+  assert.equal(context.notifications.at(-1).message, "No prompt to stash.");
+});