@andares/pi-toolkits 0.1.0 → 0.3.0

package/src/features/stash/stash.test.ts

@@ -0,0 +1,101 @@
+/**
+ * stash feature — PromptStash state machine tests.
+ *
+ * All branches are deterministic via injected `now`:
+ *  - empty-cache first press = stash + clear
+ *  - single press = swap; spaced second press = toggle back
+ *  - double press (within 400ms) = stash current + clear editor, old stash
+ *    discarded
+ *  - two presses beyond the window = normal swap (not clear)
+ *  - triple press: the third press is a fresh swap
+ */
+import { describe, expect, it } from "vitest";
+import { PromptStash, STASH_DOUBLE_PRESS_MS } from "./stash.js";
+
+describe("PromptStash", () => {
+	it("first press with empty cache stashes the text and clears the editor", () => {
+		const stash = new PromptStash();
+		const result = stash.press("write tests first", 1_000);
+		expect(result).toEqual({
+			text: "",
+			kind: "swap",
+			stashed: "write tests first",
+		});
+		expect(stash.peek()).toBe("write tests first");
+	});
+
+	it("swaps editor text with the stash on a normal press", () => {
+		const stash = new PromptStash();
+		stash.press("first prompt", 1_000); // stash = "first prompt"
+		// User types a new prompt, then presses the hotkey.
+		const result = stash.press("second prompt", 2_000);
+		expect(result.text).toBe("first prompt"); // old stash fills the editor
+		expect(result.stashed).toBe("second prompt"); // current text went to cache
+		expect(stash.peek()).toBe("second prompt");
+	});
+
+	it("toggles back and forth between the two prompts on spaced presses", () => {
+		const stash = new PromptStash();
+		stash.press("A", 1_000);
+		stash.press("B", 2_000); // editor gets A, cache = B
+		// Press again (outside the double-press window): swap back.
+		const back = stash.press("A", 3_000); // editor currently shows A
+		expect(back.text).toBe("B");
+		expect(back.stashed).toBe("A");
+		// And again: swap forward.
+		const forth = stash.press("B", 4_000);
+		expect(forth.text).toBe("A");
+		expect(forth.stashed).toBe("B");
+	});
+
+	it("double press within the window stashes current text and clears the editor", () => {
+		const stash = new PromptStash();
+		stash.press("old stash", 1_000); // cache = "old stash"
+		// User types "current prompt", presses once (swap), then quickly again.
+		const first = stash.press("current prompt", 2_000);
+		expect(first.text).toBe("old stash"); // editor momentarily shows old stash
+		const second = stash.press(
+			"old stash",
+			2_000 + STASH_DOUBLE_PRESS_MS - 1, // within the window
+		);
+		expect(second.kind).toBe("stash-clear");
+		expect(second.text).toBe(""); // editor cleared
+		expect(second.stashed).toBe("current prompt"); // cache kept the current prompt
+		expect(stash.peek()).toBe("current prompt");
+	});
+
+	it("exactly at the window boundary counts as a double press", () => {
+		const stash = new PromptStash();
+		stash.press("A", 1_000);
+		stash.press("B", 2_000);
+		const boundary = stash.press("A", 2_000 + STASH_DOUBLE_PRESS_MS);
+		expect(boundary.kind).toBe("stash-clear");
+	});
+
+	it("two presses beyond the window behave as a normal swap, not clear", () => {
+		const stash = new PromptStash();
+		stash.press("A", 1_000);
+		stash.press("B", 2_000);
+		const late = stash.press("A", 2_000 + STASH_DOUBLE_PRESS_MS + 1);
+		expect(late.kind).toBe("swap");
+		expect(late.text).toBe("B"); // toggled back to the previous stash
+	});
+
+	it("triple press: the third press is a fresh swap (window consumed)", () => {
+		const stash = new PromptStash();
+		stash.press("A", 1_000);
+		stash.press("B", 2_000);
+		stash.press("A", 2_050); // double press → stash-clear, window consumed
+		const third = stash.press("", 2_100); // editor is empty now
+		expect(third.kind).toBe("swap");
+		expect(third.text).toBe("B"); // the previously stashed prompt comes back
+		expect(third.stashed).toBe("");
+	});
+
+	it("peek exposes the stash without changing state", () => {
+		const stash = new PromptStash();
+		expect(stash.peek()).toBe("");
+		stash.press("hello", 1_000);
+		expect(stash.peek()).toBe("hello");
+	});
+});

package/src/features/stash/stash.ts

@@ -0,0 +1,83 @@
+/**
+ * prompt stash — pure state machine.
+ *
+ * One cache slot for one prompt. The hotkey (ctrl+alt+y — chosen for
+ * compatibility across pi, Linux terminals, Windows Terminal and Windows OS,
+ * see README) swaps the editor text with the stashed prompt:
+ *
+ *   press                    → stash current text, fill editor with old stash
+ *   press again (later)      → toggles back (swap again)
+ *   press twice quickly      → stash current text AND clear the editor
+ *                              (the just-swapped-out prompt is discarded)
+ *
+ * With an empty stash, a single press already stashes the current text and
+ * clears the editor (there is nothing to swap in).
+ *
+ * The double-press window is short (400ms) so two deliberate presses toggle
+ * normally, while a quick double-tap performs the stash-and-clear action.
+ */
+import type { KeyId } from "@earendil-works/pi-tui";
+
+/**
+ * Stash hotkey.
+ *
+ * Compatibility rationale (verified against pi 0.84 keybindings, live
+ * matchesKey probes and terminal/OS behavior):
+ *  - pi: no default binding for ctrl+alt+<letter> (only ctrl+alt+] is taken);
+ *    extension shortcuts dispatch first while the editor is focused
+ *  - terminals: alt encodes as ESC-prefix, so ctrl+alt+y arrives as "\x1b\x19"
+ *    and is distinguishable from ctrl+y WITHOUT kitty keyboard protocol
+ *    (verified via matchesKey). ctrl+shift+<letter> was rejected because on
+ *    terminals without kitty protocol it collapses to ctrl+<letter> — for m
+ *    that is Enter, which would submit the prompt. Plain ctrl+<letter> is
+ *    fully occupied by pi defaults or terminal control chars (ctrl+q is the
+ *    only free one but carries XON flow-control baggage).
+ *  - Windows Terminal: no default ctrl+alt+letter binding
+ *  - Windows OS: only ctrl+alt+del is reserved at the system level
+ *  - Linux desktops: ctrl+alt+t/l/d/arrows and F-keys (TTY) are taken; y is free
+ */
+export const STASH_KEY: KeyId = "ctrl+alt+y";
+
+/** Two presses within this window count as the "stash and clear" action. */
+export const STASH_DOUBLE_PRESS_MS = 400;
+
+export interface StashPressResult {
+	/** Text to place in the editor. */
+	text: string;
+	/** What this press did. */
+	kind: "swap" | "stash-clear";
+	/** Stash content after this press (for status/logging). */
+	stashed: string;
+}
+
+export class PromptStash {
+	private cache = "";
+	private lastPressAt = 0;
+
+	constructor(private readonly doublePressMs = STASH_DOUBLE_PRESS_MS) {}
+
+	/**
+	 * Handle one hotkey press with the given current editor text.
+	 * `now` is injectable for deterministic tests.
+	 */
+	press(current: string, now = Date.now()): StashPressResult {
+		if (
+			this.lastPressAt !== 0 &&
+			now - this.lastPressAt <= this.doublePressMs
+		) {
+			// Double press: keep the just-stashed prompt in the cache and clear
+			// the editor (discard the prompt that was momentarily swapped in).
+			this.lastPressAt = 0;
+			return { text: "", kind: "stash-clear", stashed: this.cache };
+		}
+		this.lastPressAt = now;
+		const previous = this.cache;
+		this.cache = current;
+		return { text: previous, kind: "swap", stashed: current };
+	}
+
+	/** Current stash content without touching state. */
+	peek(): string {
+		return this.cache;
+	}
+}

package/src/index.ts

@@ -6,11 +6,20 @@
  *
  * Current features:
  *  - ask — read-only Q&A mode (/ask)
+ *  - favorites — model favorites (ctrl+F/ctrl+J in /model, favorites-only cycling)
+ *  - stash — prompt stash (ctrl+alt+y swap / double-press stash-and-clear)
+ *  - review — third-party code review with a configured review model (third-review)
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerAsk } from "./features/ask/index.js";
+import { registerFavorites } from "./features/favorites/index.js";
+import { registerReview } from "./features/review/index.js";
+import { registerStash } from "./features/stash/index.js";
 
 export default function piToolkits(pi: ExtensionAPI): void {
 	registerAsk(pi);
+	registerFavorites(pi);
+	registerReview(pi);
+	registerStash(pi);
 	// registerXxx(pi); // future features
 }