@yusukeshib/pi-stash 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yusukeshib
+
+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,86 @@
+# pi-stash
+
+A personal stash of reusable prompt fragments for the [Pi coding agent](https://pi.dev).
+
+Jot a prompt down whenever you think of it mid-task, then pop it into the editor
+when you actually need it. Think of it as a stack-like scratchpad for prompts —
+the ad-hoc, mutable companion to static prompt templates.
+
+![pi-stash pop menu](./assets/demo.png)
+
+## Why
+
+You're deep in a task and a thought hits you: *"oh, I should also have it rename
+that module"* or *"remember to ask for tests after this."*
+
+What do you do with that thought right now?
+
+- **Queue it as a follow-up?** Too eager — follow-ups fire automatically the
+  moment the current turn ends, whether or not you're ready, and in an order you
+  don't fully control.
+- **Keep it in your head?** You'll forget it the second the agent comes back
+  with something interesting.
+- **Paste it into a scratch file?** Now you're juggling another window.
+
+Sometimes you just want to **park a prompt somewhere** and then **pull it out
+whenever you feel like it** — on your own timing, by hand. Not auto-run, not
+queued the instant the turn ends, just stashed and waiting until *you* decide
+it's time.
+
+That's the whole point of `pi-stash`:
+
+- **Push** the thought the moment it strikes, so you don't lose it or break flow.
+- **Pop** it back into the editor at exactly the moment you want it — not a
+  second sooner.
+- **Pick any one, in any order.** Your stash is a menu, not a queue. Pop the
+  third thing first, skip the rest, come back for them later — follow-ups can't
+  do that.
+
+You stay in control of *what* gets said, *when*, and *in what order*.
+
+## Install
+
+```bash
+pi install npm:@yusukeshib/pi-stash
+```
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `/stash <text>` | **Push** — save the given text onto the stash. |
+| `/stash` | **Pop** — pick a saved entry, insert it into the editor, and remove it from the stash. Run repeatedly to stack several fragments together. |
+| `/stash-clear` | Delete every stashed entry (with confirm). |
+
+## How it works
+
+`pi-stash` is not a set of predefined `/name` templates. It is a backlog you
+build up by hand during real work:
+
+1. While working, you think "I should also ask it to update the docs" — instead
+   of derailing now, run `/stash update the docs and changelog`.
+2. Later, when you're ready, run `/stash`, pick that entry, and it drops into
+   the editor. The entry is popped (removed) so the stash stays current.
+3. Pop multiple entries in a row to compose a larger prompt from fragments.
+
+## Storage
+
+Entries live in a single global JSON file, **shared across every Pi session on
+the machine** (not per-project, not per-session):
+
+```
+~/.pi/agent/prompt-stash.json
+```
+
+Override the location with the `PI_STASH_PATH` environment variable:
+
+```bash
+export PI_STASH_PATH="$HOME/.config/pi/stash.json"
+```
+
+> Note: the store is read-modify-written on each command. If two sessions edit
+> the stash at the exact same moment, the last write wins.
+
+## License
+
+MIT © yusukeshib

package/extensions/index.ts

@@ -0,0 +1,116 @@
+/**
+ * pi-stash — a personal stash of reusable prompt fragments for the Pi coding
+ * agent. Jot a prompt down whenever you think of it, then later pull up the
+ * list and pop one into the editor to compose your next message.
+ *
+ * Unlike file-based prompt templates (static `/name` commands), this is an
+ * ad-hoc, mutable, stack-like backlog you build up by hand during real work.
+ *
+ * Commands:
+ *   /stash <text>  Push: save the given text onto the stash.
+ *   /stash         Pop: pick a saved entry → insert it into the editor and
+ *                  remove it from the stash. Run repeatedly to stack fragments.
+ *   /stash-clear   Delete every entry (with confirm).
+ *
+ * Storage: a single global JSON file, shared across every Pi session on the
+ * machine (not per-project, not per-session). Default location:
+ *   ~/.pi/agent/prompt-stash.json
+ * Override with the PI_STASH_PATH environment variable.
+ */
+
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+interface StashEntry {
+	text: string;
+	addedAt: number;
+}
+
+const STORE_PATH = process.env.PI_STASH_PATH || join(homedir(), ".pi", "agent", "prompt-stash.json");
+const PREVIEW_LEN = 72;
+
+function load(): StashEntry[] {
+	try {
+		const raw = readFileSync(STORE_PATH, "utf8");
+		const parsed = JSON.parse(raw);
+		if (Array.isArray(parsed)) {
+			return parsed.filter((e): e is StashEntry => e && typeof e.text === "string");
+		}
+	} catch {
+		// missing or corrupt → empty stash
+	}
+	return [];
+}
+
+function save(entries: StashEntry[]): void {
+	mkdirSync(dirname(STORE_PATH), { recursive: true });
+	writeFileSync(STORE_PATH, `${JSON.stringify(entries, null, 2)}\n`, "utf8");
+}
+
+/** One-line, length-bounded preview for select menus. */
+function preview(text: string, index: number): string {
+	const oneLine = text.replace(/\s+/g, " ").trim();
+	const body = oneLine.length > PREVIEW_LEN ? `${oneLine.slice(0, PREVIEW_LEN - 1)}…` : oneLine;
+	// Number prefix keeps labels unique so indexOf() round-trips reliably.
+	return `${String(index + 1).padStart(2, " ")}. ${body}`;
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("stash", {
+		description: "Push text (with arg) or pop an entry into the editor (no arg)",
+		handler: async (args, ctx) => {
+			const text = (args ?? "").trim();
+
+			// PUSH: /stash <text>
+			if (text) {
+				const entries = load();
+				if (entries.some((e) => e.text === text)) {
+					ctx.ui.notify("Already in stash", "info");
+					return;
+				}
+				entries.push({ text, addedAt: Date.now() });
+				save(entries);
+				ctx.ui.notify(`Stashed (${entries.length} total)`, "info");
+				return;
+			}
+
+			// POP: /stash → pick, insert into editor, remove from stash
+			const entries = load();
+			if (entries.length === 0) {
+				ctx.ui.notify("Stash is empty. Add one with /stash <text>", "info");
+				return;
+			}
+			const labels = entries.map((e, i) => preview(e.text, i));
+			const choice = await ctx.ui.select("Pop prompt:", labels);
+			if (choice === undefined) return; // cancelled / timed out
+			const idx = labels.indexOf(choice);
+			if (idx < 0) return;
+
+			const chosen = entries[idx].text;
+			const current = ctx.ui.getEditorText() ?? "";
+			const next = current.trim().length > 0 ? `${current}\n${chosen}` : chosen;
+			ctx.ui.setEditorText(next);
+
+			// pop = remove the chosen entry
+			entries.splice(idx, 1);
+			save(entries);
+		},
+	});
+
+	pi.registerCommand("stash-clear", {
+		description: "Delete every stashed prompt",
+		handler: async (_args, ctx) => {
+			const entries = load();
+			if (entries.length === 0) {
+				ctx.ui.notify("Stash is already empty", "info");
+				return;
+			}
+			const ok = await ctx.ui.confirm("Clear the entire stash?", `${entries.length} entries will be deleted`);
+			if (!ok) return;
+			save([]);
+			ctx.ui.notify("Stash cleared", "info");
+		},
+	});
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@yusukeshib/pi-stash",
+  "version": "0.1.0",
+  "description": "A personal stash of reusable prompt fragments for the Pi coding agent. Push prompts you think of mid-task, then pop them into the editor when you need them.",
+  "type": "module",
+  "license": "MIT",
+  "author": "yusukeshib",
+  "homepage": "https://github.com/yusukeshib/pi-stash#readme",
+  "bugs": {
+    "url": "https://github.com/yusukeshib/pi-stash/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yusukeshib/pi-stash.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "prompt",
+    "stash",
+    "snippets",
+    "productivity"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "extensions",
+    "assets",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "extensions/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/yusukeshib/pi-stash/main/assets/demo.png"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run typecheck"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0"
+  }
+}