@zle13/pi-prompt-snippets 0.2.0 → 0.3.0

package/README.md

@@ -30,8 +30,9 @@ Then restart Pi or run `/reload` in your active session.
   - `↑` / `↓` (or custom selection keybindings like `Ctrl+P` / `Ctrl+N`) to navigate items.
   - `Space` to toggle snippet active / inactive.
   - `Tab` to preview the highlighted snippet (shows name, placement, order, source origin, filename, and prompt body). Press `Tab` or `Esc` (or `Ctrl+G` / `Ctrl+C`) to return to the list with cursor position preserved.
+  - `Ctrl+E` to manage snippets: create, edit, duplicate, delete your files, hide bundled snippets, or restore hiding files. Sources (`bundled`, `global`, `project`) appear beside each snippet.
   - `Enter` to apply your selection.
-  - `Esc` to cancel and discard changes.
+  - `Esc` to cancel and discard **toggle changes only**. Explicitly saved snippet edits remain saved.
 - **Keybinding Integration:** Respects custom `tui.select.*` actions from `~/.pi/agent/keybindings.json` (such as `tui.select.up`, `tui.select.down`, `tui.select.pageUp`, `tui.select.pageDown`, `tui.select.confirm`, and `tui.select.cancel`).
 - **Active Snippet Indicator:** Active snippets appear as a widget above the editor:
   - `↑ prepend: ...` (accent color) — inserted before your message.
@@ -71,6 +72,18 @@ Files are re-scanned whenever the menu opens or a message is sent, so edits take
 
 ## Customizing, Overriding & Disabling Snippets
 
+### Manage without leaving Pi
+
+Press **Alt+S → Ctrl+E**. Management acts on the highlighted snippet; **New snippet** and **Restore hidden snippet** are available even when the list is empty.
+
+- **New / Duplicate:** choose Global or This project (trusted projects only). The last chosen location is remembered for this extension runtime. Set a unique `.md` filename; existing files are never silently overwritten.
+- **Edit:** opens a details screen. Select name, description, placement, order, or prompt body to edit that field. Each field shows its heading followed by a separate, dimmed **Tip:** line explaining what to enter (including placement and prompt body). **Order** is a whole number: lower values appear first within the prepend or append group (10 before 20; ties sort by name), not a model instruction priority. Existing text fields are prefilled; new snippets start with an empty, required name. The body uses Pi's multiline editor. Returning from a field only updates the draft; choose **Save snippet** to write it, or **Discard changes** to leave the file untouched.
+- **Bundled edits:** choose a location for an override with the same filename. Bundled files are never modified.
+- **Delete:** confirms the exact user-file path and warns about lower-priority versions becoming visible. Deleting an override is not the same as hiding its bundled/global version.
+- **Hide:** bundled snippets can be hidden globally or for this project. **Restore hidden snippet** removes a confirmed bodyless hiding file to reveal the lower-priority version. Snippets disabled in `prompt-snippets.json`, or disabled files containing a prompt body, remain managed manually.
+
+Saving or deleting returns to the toggle list with pending selections and cursor position preserved where possible. Changes take effect immediately, even if you later cancel the toggle menu. Files changed externally while a draft is open are not overwritten; discard and reopen the draft to refresh. Symlinked snippet files/directories are read-only to management; edit those manually.
+
 ### 1. Add Your Own Snippets
 
 Create any `.md` file in `~/.pi/agent/snippets/` (for all projects) or `.pi/snippets/` (for the current project):

package/extensions/management-store.ts

@@ -0,0 +1,338 @@
+/**
+ * Storage helpers for writable prompt snippets (global and project scopes).
+ *
+ * Bundled snippets are never written: mutations refuse symlinks (directories
+ * and files) and refuse any target resolving inside the bundled snippets
+ * directory. `expected` is the exact prior raw content from `readSnapshot`
+ * (`null` = create only); a mismatched snapshot fails instead of clobbering
+ * concurrent changes. Every check/write window runs inside
+ * `withFileMutationQueue`, which serializes operations on the same file.
+ */
+
+import { lstatSync, mkdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from "node:fs";
+import type { Stats } from "node:fs";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { parseSnippet, resolveBundledSnippetsDir } from "./loader.js";
+import type { LoadSnippetsOptions, SnippetPlacement } from "./types.js";
+
+/** Scopes that may be written. Bundled snippets are read-only. */
+export type WritableScope = "global" | "project";
+
+/** A complete snippet definition as produced by editor UIs. */
+export interface SnippetDraft {
+	/** Filename identifier, must be a safe basename ending in .md */
+	id: string;
+	/** Display name (single line, non-empty) */
+	name: string;
+	/** Short description shown in menu (single line, may be empty) */
+	description: string;
+	/** Placement before or after user message */
+	placement: SnippetPlacement;
+	/** Sort order within placement group (safe integer) */
+	order: number;
+	/** Prompt content inserted into message (non-empty) */
+	body: string;
+}
+
+/** Tombstone frontmatter written by hideSnippet; the loader parses it as disabled. */
+const TOMBSTONE_RAW = "---\ndisabled: true\n---\n";
+
+const LINE_TERMINATOR = /[\n\r\u2028\u2029]/;
+
+interface NormalizedDraft {
+	id: string;
+	name: string;
+	description: string;
+	placement: SnippetPlacement;
+	order: number;
+	body: string;
+}
+
+function isEnoent(error: unknown): boolean {
+	return typeof error === "object" && error !== null && (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+/** Resolve `<agentDir>/snippets` or `<cwd>/.pi/snippets`; project needs a trusted cwd. */
+export function snippetDirectory(options: LoadSnippetsOptions, scope: WritableScope): string {
+	if (scope !== "global" && scope !== "project") {
+		throw new Error(`Unknown writable snippet scope: ${String(scope)}`);
+	}
+	if (scope === "global") {
+		let agentDir: string;
+		try {
+			agentDir = options.agentDir ?? getAgentDir();
+		} catch {
+			agentDir = options.agentDir ?? join(process.env.HOME || "", ".pi", "agent");
+		}
+		return join(agentDir, "snippets");
+	}
+	if (!options.cwd) {
+		throw new Error("Project snippets require a working directory (options.cwd)");
+	}
+	if (options.isProjectTrusted === false) {
+		throw new Error("Project snippets are unavailable because this project is not trusted");
+	}
+	return join(options.cwd, CONFIG_DIR_NAME || ".pi", "snippets");
+}
+
+/** Exact raw content of a snippet file, or `null` only for ENOENT. Refuses symlinks. */
+export function readSnapshot(path: string): string | null {
+	let stats: Stats;
+	try {
+		stats = lstatSync(path);
+	} catch (error) {
+		if (isEnoent(error)) return null;
+		throw error;
+	}
+	if (stats.isSymbolicLink()) {
+		throw new Error(`Refusing to read a symlink: ${path}`);
+	}
+	if (!stats.isFile()) {
+		throw new Error(`Snippet path is not a regular file: ${path}`);
+	}
+	return readFileSync(path, "utf-8");
+}
+
+/** Create (`expected: null`) or replace (`expected: prior raw`) a snippet file. */
+export async function saveSnippet(
+	options: LoadSnippetsOptions,
+	scope: WritableScope,
+	draft: SnippetDraft,
+	expected: string | null,
+): Promise<void> {
+	if (expected !== null && typeof expected !== "string") {
+		throw new Error("expected must be null (create only) or the exact prior raw file content");
+	}
+	const normalized = normalizeDraft(draft);
+	const raw = serializeSnippet(normalized);
+	verifyRoundTrip(normalized, raw, scope);
+	const dir = snippetDirectory(options, scope);
+	const filePath = join(dir, normalized.id);
+	await withFileMutationQueue(filePath, async () => {
+		assertWritableSnippetDirectory(dir, options, true);
+		const current = readSnapshot(filePath);
+		if (expected === null) {
+			if (current !== null) {
+				throw new Error(
+					`Snippet already exists: ${normalized.id}. Pass its current content as expected to replace it.`,
+				);
+			}
+		} else if (current === null) {
+			throw new Error(`Snippet was removed before this save (stale expected content): ${normalized.id}`);
+		} else if (current !== expected) {
+			throw new Error(`Snippet changed since it was read (stale expected content): ${normalized.id}`);
+		}
+		writeFileSync(filePath, raw, "utf-8");
+	});
+}
+
+/** Delete a snippet file; the exact prior raw content is required. */
+export async function deleteSnippet(
+	options: LoadSnippetsOptions,
+	scope: WritableScope,
+	id: string,
+	expected: string,
+): Promise<void> {
+	if (typeof expected !== "string") {
+		throw new Error("deleteSnippet requires the exact prior raw file content as expected");
+	}
+	const validatedId = validateSnippetId(id);
+	const dir = snippetDirectory(options, scope);
+	const filePath = join(dir, validatedId);
+	await withFileMutationQueue(filePath, async () => {
+		assertWritableSnippetDirectory(dir, options, false);
+		const current = readSnapshot(filePath);
+		if (current === null) {
+			throw new Error(`Snippet not found: ${validatedId}`);
+		}
+		if (current !== expected) {
+			throw new Error(`Snippet changed since it was read (stale expected content): ${validatedId}`);
+		}
+		unlinkSync(filePath);
+	});
+}
+
+/**
+ * Replace a snippet file with a `disabled: true` tombstone in a writable
+ * scope. Hiding a bundled snippet writes the tombstone under the bundled
+ * filename in the global/project scope, which makes the loader skip it; the
+ * bundled directory is never touched. Reveal with `deleteSnippet` or
+ * `saveSnippet` using the tombstone content as `expected`.
+ */
+export async function hideSnippet(
+	options: LoadSnippetsOptions,
+	scope: WritableScope,
+	id: string,
+	expected: string | null,
+): Promise<void> {
+	if (expected !== null && typeof expected !== "string") {
+		throw new Error("expected must be null (create only) or the exact prior raw file content");
+	}
+	const validatedId = validateSnippetId(id);
+	const dir = snippetDirectory(options, scope);
+	const filePath = join(dir, validatedId);
+	await withFileMutationQueue(filePath, async () => {
+		assertWritableSnippetDirectory(dir, options, true);
+		const current = readSnapshot(filePath);
+		if (expected === null) {
+			if (current !== null) {
+				throw new Error(
+					`File already exists: ${validatedId}. Pass its current content as expected to replace it with a disable tombstone.`,
+				);
+			}
+		} else if (current === null) {
+			throw new Error(`Snippet was removed before this change (stale expected content): ${validatedId}`);
+		} else if (current !== expected) {
+			throw new Error(`Snippet changed since it was read (stale expected content): ${validatedId}`);
+		}
+		writeFileSync(filePath, TOMBSTONE_RAW, "utf-8");
+	});
+}
+
+function validateSnippetId(id: unknown): string {
+	if (typeof id !== "string" || id.length === 0) {
+		throw new Error("Snippet filename must be a non-empty string");
+	}
+	if (id.length > 200) {
+		throw new Error(`Snippet filename is too long (max 200 characters): ${id}`);
+	}
+	if (!/\.md$/i.test(id)) {
+		throw new Error(`Snippet filename must end with .md: ${id}`);
+	}
+	if (id.startsWith(".")) {
+		throw new Error(`Snippet filename must not start with a dot: ${id}`);
+	}
+	if (/[/\\:]/.test(id)) {
+		throw new Error(`Snippet filename must be a plain basename without path separators: ${id}`);
+	}
+	if (/[\0-\x1f]/.test(id)) {
+		throw new Error(`Snippet filename must not contain control characters: ${JSON.stringify(id)}`);
+	}
+	return id;
+}
+
+function singleLineField(value: unknown, field: string, required: boolean): string {
+	if (typeof value !== "string") {
+		throw new Error(`Snippet ${field} must be a string`);
+	}
+	if (LINE_TERMINATOR.test(value)) {
+		throw new Error(`Snippet ${field} must be a single line`);
+	}
+	const trimmed = value.trim();
+	if (required && !trimmed) {
+		throw new Error(`Snippet ${field} must be a non-empty string`);
+	}
+	return trimmed;
+}
+
+function normalizeDraft(draft: SnippetDraft): NormalizedDraft {
+	if (!draft || typeof draft !== "object") {
+		throw new Error("Snippet draft must be an object");
+	}
+	const id = validateSnippetId(draft.id);
+	const name = singleLineField(draft.name, "name", true);
+	const description = singleLineField(draft.description, "description", false);
+	if (draft.placement !== "prepend" && draft.placement !== "append") {
+		throw new Error(`Snippet placement must be "prepend" or "append", got: ${String(draft.placement)}`);
+	}
+	if (!Number.isSafeInteger(draft.order)) {
+		throw new Error(`Snippet order must be a safe integer, got: ${String(draft.order)}`);
+	}
+	const body = typeof draft.body === "string" ? draft.body.trim() : "";
+	if (!body) {
+		throw new Error("Snippet body must be a non-empty string");
+	}
+	return { id, name, description, placement: draft.placement, order: draft.order, body };
+}
+
+/**
+ * Encode a frontmatter value so the loader's `key: value` parser (which trims
+ * the value and strips one leading and one trailing quote) returns it
+ * unchanged: values that start or end with a quote are wrapped in an extra
+ * pair of double quotes.
+ */
+function encodeFrontmatterValue(value: string): string {
+	if (value === "") return "";
+	if (/^["']/.test(value) || /["']$/.test(value)) return `"${value}"`;
+	return value;
+}
+
+function serializeSnippet(draft: NormalizedDraft): string {
+	return [
+		"---",
+		`name: ${encodeFrontmatterValue(draft.name)}`,
+		`description: ${encodeFrontmatterValue(draft.description)}`,
+		`placement: ${draft.placement}`,
+		`order: ${draft.order}`,
+		"---",
+		draft.body,
+		"",
+	].join("\n");
+}
+
+/** Fail unless the serialized raw parses back to exactly the drafted fields. */
+function verifyRoundTrip(draft: NormalizedDraft, raw: string, scope: WritableScope): void {
+	const { snippet, disabled } = parseSnippet(draft.id, raw, scope, "");
+	const parsed = disabled ? null : snippet;
+	if (!parsed) {
+		throw new Error(`Serialized snippet ${draft.id} does not parse as an enabled snippet`);
+	}
+	if (
+		parsed.name !== draft.name ||
+		parsed.description !== draft.description ||
+		parsed.placement !== draft.placement ||
+		parsed.order !== draft.order ||
+		parsed.body !== draft.body
+	) {
+		throw new Error(`Serialized frontmatter for ${draft.id} would not round-trip through the snippet loader`);
+	}
+}
+
+function isSameOrInside(candidate: string, parent: string): boolean {
+	if (candidate === parent) return true;
+	const rel = relative(parent, candidate);
+	return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+/**
+ * Ensure the snippet directory is writable: refuse symlink directories and
+ * non-directories, and refuse any target resolving inside the bundled
+ * snippets directory. Checks run against the deepest existing ancestor so
+ * they happen before any directory is created.
+ */
+function assertWritableSnippetDirectory(dir: string, options: LoadSnippetsOptions, create: boolean): void {
+	let probe = dir;
+	let stats: Stats | undefined;
+	for (;;) {
+		try {
+			stats = lstatSync(probe);
+			break;
+		} catch (error) {
+			if (!isEnoent(error)) throw error;
+			const parent = dirname(probe);
+			if (parent === probe) break;
+			probe = parent;
+		}
+	}
+
+	if (stats && probe === dir && stats.isSymbolicLink()) {
+		throw new Error(`Refusing to write snippets through a symlink directory: ${dir}`);
+	}
+	if (stats && probe === dir && !stats.isDirectory()) {
+		throw new Error(`Snippet directory path is not a directory: ${dir}`);
+	}
+
+	const bundledDir = resolveBundledSnippetsDir(options.bundledDir);
+	if (stats && bundledDir) {
+		const bundledReal = realpathSync(bundledDir);
+		const resolved = realpathSync(probe);
+		if (isSameOrInside(resolved, bundledReal)) {
+			throw new Error(`Refusing to modify bundled snippets via ${dir}`);
+		}
+	}
+
+	if (create && (!stats || probe !== dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
+}

package/extensions/management-ui.ts

@@ -0,0 +1,209 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Input, Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { loadSnippets, parseSnippet } from "./loader.js";
+import {
+	deleteSnippet, hideSnippet, readSnapshot, saveSnippet, snippetDirectory,
+	type SnippetDraft, type WritableScope,
+} from "./management-store.js";
+import type { LoadSnippetsOptions, Snippet } from "./types.js";
+
+const FIELD_HELP = {
+	name: "Display name in the snippet menu. Use a short, recognizable label, e.g. Concise answers.",
+	description: "Optional subtitle explaining when to use this snippet. Not sent to the model.",
+	placement: "Prepend inserts instructions before your message; append inserts them after your message.",
+	order: "Whole number controlling sequence within the prepend or append group. Lower numbers appear first: 10 before 20. Ties sort by name. This is not instruction priority.",
+	body: "The instructions inserted into your message when this snippet is active. Multiple lines are allowed.",
+	id: "Unique .md filename, e.g. concise-answers.md. This is the snippet ID; matching filenames override lower-priority sources. No folders.",
+};
+
+/** A prefilled single-line input, with the host's confirm/cancel bindings. */
+async function editText(ctx: ExtensionContext, title: string, value: string, help: string): Promise<string | undefined> {
+	return ctx.ui.custom<string | undefined>((tui, theme, keybindings, done) => {
+		const input = new Input();
+		input.setValue(value);
+		let finished = false;
+		const finish = (result: string | undefined) => {
+			if (finished) return;
+			finished = true;
+			done(result);
+		};
+		input.onSubmit = finish;
+		input.onEscape = () => finish(undefined);
+		return {
+			get focused() { return input.focused; },
+			set focused(value: boolean) { input.focused = value; },
+			render(width: number) {
+				return [
+					truncateToWidth(theme.fg("accent", title), width),
+					...wrapTextWithAnsi(theme.fg("dim", `Tip: ${help}`), width),
+					"",
+					...input.render(width),
+					truncateToWidth(theme.fg("dim", "Enter accept field • Esc back • Save in the details screen to persist"), width),
+				];
+			},
+			invalidate() { input.invalidate(); },
+			handleInput(data: string) {
+				if (finished) return;
+				if (keybindings.matches(data, "tui.select.cancel") || matchesKey(data, Key.escape)) finish(undefined);
+				else if (keybindings.matches(data, "tui.select.confirm")) finish(input.getValue());
+				else input.handleInput(data);
+				tui.requestRender();
+			},
+		};
+	});
+}
+
+export function createSnippetManager() {
+	let lastScope: WritableScope = "global";
+
+	async function chooseScope(ctx: ExtensionContext, options: LoadSnippetsOptions): Promise<WritableScope | undefined> {
+		const scopes: WritableScope[] = options.isProjectTrusted === false ? ["global"] : [lastScope, lastScope === "global" ? "project" : "global"];
+		const labels = scopes.map((scope) => `${scope === "global" ? "Global" : "This project"} — ${snippetDirectory(options, scope)}`);
+		const choice = await ctx.ui.select("Save location", labels);
+		if (choice === undefined) return;
+		lastScope = scopes[labels.indexOf(choice)];
+		return lastScope;
+	}
+
+	async function editDraft(ctx: ExtensionContext, options: LoadSnippetsOptions, original?: Snippet, duplicate = false) {
+		const scope = original && !duplicate && original.source !== "bundled" ? original.source : await chooseScope(ctx, options);
+		if (!scope) return;
+		const isEdit = original && !duplicate && original.source !== "bundled";
+		let expected: string | null = null;
+		let source = original;
+		if (isEdit) {
+			const path = join(snippetDirectory(options, scope), original.id);
+			expected = readSnapshot(path);
+			if (expected === null) throw new Error("Snippet was removed. Reopen management to refresh.");
+			source = parseSnippet(original.id, expected, scope, path).snippet ?? undefined;
+			if (!source) throw new Error("Snippet is now hidden or invalid. Reopen management to refresh.");
+		}
+		const draft: SnippetDraft = {
+			id: source ? (duplicate ? source.id.replace(/\.md$/i, "-copy.md") : source.id) : "new-snippet.md",
+			name: source ? `${source.name}${duplicate ? " (copy)" : ""}` : "",
+			description: source?.description ?? "",
+			placement: source?.placement ?? "append",
+			order: source?.order ?? 10,
+			body: source?.body ?? "",
+		};
+		const initial = JSON.stringify(draft);
+		while (true) {
+			const fields = [
+				`Name: ${draft.name || "(required)"}`,
+				`Description: ${draft.description || "(none)"}`,
+				`Placement: ${draft.placement}`,
+				`Order: ${draft.order}`,
+				`Prompt body: ${draft.body.split("\n")[0] || "(empty)"}`,
+				...(!original || duplicate ? [`Filename: ${draft.id}`] : []),
+				"Save snippet", "Discard changes",
+			];
+			const path = join(snippetDirectory(options, scope), draft.id);
+			const choice = await ctx.ui.select(`Snippet details [${scope}] — ${path}`, fields);
+			const field = fields.indexOf(choice ?? "");
+			if (choice === undefined || choice === "Discard changes") {
+				if (JSON.stringify(draft) === initial || await ctx.ui.confirm("Discard unsaved snippet?", "No file changes have been saved.")) return;
+				continue;
+			}
+			if (choice === "Save snippet") {
+				try {
+					await saveSnippet(options, scope, draft, expected);
+					const effective = loadSnippets(options).find((s) => s.id === draft.id);
+					ctx.ui.notify(`Saved ${path}${effective?.source !== scope ? " (hidden by configuration or a higher-priority snippet)" : ""}`, "info");
+					return;
+				} catch (error) {
+					ctx.ui.notify(String(error), "error");
+					continue;
+				}
+			}
+			if (field === 2) {
+				const placement = await ctx.ui.select(`Edit placement\n${ctx.ui.theme.fg("dim", `Tip: ${FIELD_HELP.placement}`)}`, ["prepend", "append"]);
+				if (placement === "prepend" || placement === "append") draft.placement = placement;
+			} else if (field === 4) {
+				const body = await ctx.ui.editor(`Edit prompt body\n${ctx.ui.theme.fg("dim", `Tip: ${FIELD_HELP.body} Return to details, then Save snippet.`)}`, draft.body);
+				if (body !== undefined) draft.body = body;
+			} else if (field >= 0) {
+				const key = (["name", "description", "", "order", "", "id"] as const)[field];
+				if (!key) continue;
+				const value = await editText(ctx, `Edit ${key === "id" ? "filename" : key}`, String(draft[key]), FIELD_HELP[key]);
+				if (value === undefined) continue;
+				if (key === "order") {
+					const order = value.trim() ? Number(value) : NaN;
+					if (Number.isSafeInteger(order)) draft.order = order;
+					else ctx.ui.notify("Order must be a whole number", "warning");
+				} else draft[key] = value;
+			}
+		}
+	}
+
+	async function restoreHidden(ctx: ExtensionContext, options: LoadSnippetsOptions) {
+		const hidden: { scope: WritableScope; id: string; raw: string; label: string }[] = [];
+		for (const scope of ["global", "project"] as const) {
+			if (scope === "project" && options.isProjectTrusted === false) continue;
+			const dir = snippetDirectory(options, scope);
+			let files;
+			try { files = readdirSync(dir, { withFileTypes: true }); } catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+				throw error;
+			}
+			for (const entry of files.sort((a, b) => a.name.localeCompare(b.name))) {
+				if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md")) continue;
+				const id = entry.name;
+				let raw: string | null;
+				try { raw = readSnapshot(join(dir, id)); } catch {
+					// An unrelated unreadable or concurrently replaced file must not block restoration.
+					continue;
+				}
+				// Only offer tombstones, never delete a disabled user snippet's prompt body.
+				const body = raw?.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/)?.[1];
+				if (raw !== null && body?.trim() === "" && parseSnippet(id, raw, scope, join(dir, id)).disabled) {
+					hidden.push({ scope, id, raw, label: `${id} [${scope}]` });
+				}
+			}
+		}
+		if (!hidden.length) {
+			ctx.ui.notify("No file-hidden snippets. Snippets disabled in prompt-snippets.json must be restored there.", "info");
+			return;
+		}
+		const choice = await ctx.ui.select("Restore hidden snippet", hidden.map((h) => h.label));
+		const item = hidden.find((h) => h.label === choice);
+		if (!item || !await ctx.ui.confirm("Remove hiding file?", `${join(snippetDirectory(options, item.scope), item.id)}\nRemoves this file to reveal any lower-priority snippet. Configuration may still hide it.`)) return;
+		await deleteSnippet(options, item.scope, item.id, item.raw);
+		ctx.ui.notify("Hiding file removed", "info");
+	}
+
+	return async function manageSnippet(ctx: ExtensionContext, options: LoadSnippetsOptions, selectedId?: string) {
+		try {
+			const selected = loadSnippets(options).find((s) => s.id === selectedId);
+			const actions = ["New snippet", ...(selected ? ["Edit snippet", "Duplicate snippet", selected.source === "bundled" ? "Hide snippet" : "Delete snippet"] : []), "Restore hidden snippet", "Back to snippets"];
+			const action = await ctx.ui.select(selected ? `Manage: ${selected.name} [${selected.source}] — ${selected.filePath}` : "Manage snippets", actions);
+			if (action === "New snippet") await editDraft(ctx, options);
+			else if (action === "Edit snippet" && selected) await editDraft(ctx, options, selected);
+			else if (action === "Duplicate snippet" && selected) await editDraft(ctx, options, selected, true);
+			else if (action === "Restore hidden snippet") await restoreHidden(ctx, options);
+			else if (action === "Hide snippet" && selected) {
+				const scope = await chooseScope(ctx, options);
+				if (!scope) return;
+				const path = join(snippetDirectory(options, scope), selected.id);
+				if (!await ctx.ui.confirm("Hide bundled snippet?", `Create ${path}\nThe bundled file is never modified. Use Restore hidden snippet to undo.`)) return;
+				await hideSnippet(options, scope, selected.id, null);
+				ctx.ui.notify(`Hidden ${selected.name} [${scope}]`, "info");
+			} else if (action === "Delete snippet" && selected && selected.source !== "bundled") {
+				const path = join(snippetDirectory(options, selected.source), selected.id);
+				const expected = readSnapshot(path);
+				if (expected === null) throw new Error("Snippet was already removed");
+				// Resolve a preview without the selected layer; configurations still apply.
+				const lower = selected.source === "project"
+					? loadSnippets({ ...options, isProjectTrusted: false }).find((s) => s.id === selected.id)
+					: undefined;
+				const reveal = lower ? `Restore ${lower.source} version: ${lower.name}.` : "Any lower-priority version will become visible unless disabled by configuration.";
+				if (!await ctx.ui.confirm("Delete snippet file?", `${path}\n${reveal}\nThis cannot be undone.`)) return;
+				await deleteSnippet(options, selected.source, selected.id, expected);
+				ctx.ui.notify(`Deleted ${path}`, "info");
+			}
+		} catch (error) {
+			ctx.ui.notify(String(error), "error");
+		}
+	};
+}

package/extensions/prompt-snippets.ts

@@ -15,6 +15,7 @@ import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { loadSnippets } from "./loader.js";
+import { createSnippetManager } from "./management-ui.js";
 import type { LoadSnippetsOptions, Snippet } from "./types.js";
 
 const WIDGET_ID = "prompt-snippets";
@@ -26,6 +27,8 @@ export function createPromptSnippetsExtension(extensionOptions: LoadSnippetsOpti
 	return function promptSnippetsExtension(pi: ExtensionAPI) {
 		let snippets: Snippet[] = [];
 		let enabled = new Set<string>();
+		const manageSnippet = createSnippetManager();
+		let menuOpen = false;
 
 		function getSnippets(ctx: ExtensionContext): Snippet[] {
 			const isTrusted = typeof ctx.isProjectTrusted === "function" ? ctx.isProjectTrusted() : true;
@@ -59,220 +62,248 @@ export function createPromptSnippetsExtension(extensionOptions: LoadSnippetsOpti
 		}
 
 		async function openMenu(ctx: ExtensionContext) {
-			if (ctx.mode !== "tui") {
-				ctx.ui.notify("Snippet menu requires interactive mode", "warning");
+			if (!ctx.hasUI || ctx.mode !== "tui") {
+				if (ctx.hasUI) ctx.ui.notify("Snippet menu requires interactive mode", "warning");
 				return;
 			}
 
-			snippets = getSnippets(ctx);
-			enabled = new Set([...enabled].filter((id) => snippets.some((s) => s.id === id)));
-
-			if (snippets.length === 0) {
-				ctx.ui.notify("No snippets found in bundled, global, or project snippet directories", "warning");
-				updateWidget(ctx);
-				return;
-			}
-
-			const working = new Set(enabled);
-
-			const confirmed = await ctx.ui.custom<boolean>((tui, theme, keybindings, done) => {
-				const prepends = snippets.filter((s) => s.placement === "prepend");
-				const appends = snippets.filter((s) => s.placement === "append");
-				const items = [...prepends, ...appends];
-
-				let mode: "list" | "preview" = "list";
+			if (menuOpen) return;
+			menuOpen = true;
+			try {
+				snippets = getSnippets(ctx);
+				enabled = new Set([...enabled].filter((id) => snippets.some((s) => s.id === id)));
+				const working = new Set(enabled);
 				let cursor = 0;
 				let listScroll = 0;
-				let previewScroll = 0;
-
-				const isUp = (data: string) =>
-					Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.up") : matchesKey(data, Key.up));
-				const isDown = (data: string) =>
-					Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.down") : matchesKey(data, Key.down));
-				const isPageUp = (data: string) =>
-					Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.pageUp") : matchesKey(data, Key.pageUp));
-				const isPageDown = (data: string) =>
-					Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.pageDown") : matchesKey(data, Key.pageDown));
-				const isConfirm = (data: string) =>
-					Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.confirm") : matchesKey(data, Key.enter));
-				const isCancel = (data: string) =>
-					Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.cancel") : matchesKey(data, Key.escape));
-
-				const itemRow = (snippet: Snippet, idx: number, width: number): string => {
-					const pointer = idx === cursor ? theme.fg("accent", "> ") : "  ";
-					const checkbox = working.has(snippet.id) ? theme.fg("success", "[x]") : theme.fg("dim", "[ ]");
-					const desc = snippet.description ? theme.fg("dim", ` — ${snippet.description}`) : "";
-					return truncateToWidth(`${pointer}${checkbox} ${theme.bold(snippet.name)}${desc}`, width);
-				};
-
-				const buildListRows = (width: number): { text: string; itemIndex: number | null }[] => {
-					const rows: { text: string; itemIndex: number | null }[] = [];
-					if (prepends.length > 0) {
-						rows.push({ text: theme.fg("dim", "↑ PREPEND — added before your message"), itemIndex: null });
-						prepends.forEach((s, i) => rows.push({ text: itemRow(s, i, width), itemIndex: i }));
-					}
-					if (prepends.length > 0 && appends.length > 0) {
-						rows.push({ text: "", itemIndex: null });
-					}
-					if (appends.length > 0) {
-						rows.push({ text: theme.fg("dim", "↓ APPEND — added after your message"), itemIndex: null });
-						appends.forEach((s, i) =>
-							rows.push({
-								text: itemRow(s, prepends.length + i, width),
-								itemIndex: prepends.length + i,
-							}),
-						);
-					}
-					return rows;
-				};
-
-				const buildPreviewRows = (snippet: Snippet, width: number): string[] => {
-					const rows: string[] = [];
-					rows.push(truncateToWidth(theme.bold(snippet.name), width));
-					const sourceInfo = snippet.source ? ` · [${snippet.source}]` : "";
-					rows.push(
-						truncateToWidth(
-							theme.fg("dim", `${snippet.placement} · order ${snippet.order}${sourceInfo} · ${snippet.id}`),
-							width,
-						),
-					);
-					rows.push(theme.fg("dim", "─".repeat(Math.min(width, 40))));
-					for (const line of snippet.body.split("\n")) {
-						for (const wrapped of wrapTextWithAnsi(line, width)) {
-							rows.push(truncateToWidth(wrapped, width));
-						}
-					}
-					return rows;
-				};
-
-				const viewport = (
-					lines: string[],
-					scroll: number,
-					maxView: number,
-					focusRow?: number,
-				): { out: string[]; scroll: number } => {
-					const clipped = lines.length > maxView;
-					const view = clipped ? Math.max(1, maxView - 2) : maxView;
-
-					let s = Math.min(Math.max(0, scroll), Math.max(0, lines.length - view));
-					if (focusRow !== undefined) {
-						if (focusRow < s) s = focusRow;
-						else if (focusRow >= s + view) s = focusRow - view + 1;
-					}
 
-					const visible = lines.slice(s, s + view);
-					if (!clipped) return { out: visible, scroll: s };
-
-					const above = s;
-					const below = lines.length - (s + view);
-					return {
-						out: [
-							above > 0 ? theme.fg("dim", `  ↑ ${above} more`) : "",
-							...visible,
-							below > 0 ? theme.fg("dim", `  ↓ ${below} more`) : "",
-						],
-						scroll: s,
-					};
-				};
-
-				return {
-					render(width: number): string[] {
-						const maxView = Math.max(5, tui.terminal.rows - 10);
-
-						let content: string[];
-						let title: string;
-						let hints: string;
-						if (mode === "list") {
-							const rows = buildListRows(width);
-							const cursorRow = rows.findIndex((r) => r.itemIndex === cursor);
-							const v = viewport(
-								rows.map((r) => r.text),
-								listScroll,
-								maxView,
-								cursorRow >= 0 ? cursorRow : 0,
+				while (true) {
+					const confirmed = await ctx.ui.custom<boolean | { manage: true; id?: string }>((tui, theme, keybindings, done) => {
+						const prepends = snippets.filter((s) => s.placement === "prepend");
+						const appends = snippets.filter((s) => s.placement === "append");
+						const items = [...prepends, ...appends];
+
+						let mode: "list" | "preview" = "list";
+						let previewScroll = 0;
+						let finished = false;
+						const finish = (result: boolean | { manage: true; id?: string }) => {
+							if (finished) return;
+							finished = true;
+							done(result);
+						};
+
+						const isUp = (data: string) =>
+							Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.up") : matchesKey(data, Key.up));
+						const isDown = (data: string) =>
+							Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.down") : matchesKey(data, Key.down));
+						const isPageUp = (data: string) =>
+							Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.pageUp") : matchesKey(data, Key.pageUp));
+						const isPageDown = (data: string) =>
+							Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.pageDown") : matchesKey(data, Key.pageDown));
+						const isConfirm = (data: string) =>
+							Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.confirm") : matchesKey(data, Key.enter));
+						const isCancel = (data: string) =>
+							Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.cancel") : matchesKey(data, Key.escape));
+
+						const itemRow = (snippet: Snippet, idx: number, width: number): string => {
+							const pointer = idx === cursor ? theme.fg("accent", "> ") : "  ";
+							const checkbox = working.has(snippet.id) ? theme.fg("success", "[x]") : theme.fg("dim", "[ ]");
+							const desc = snippet.description ? theme.fg("dim", ` — ${snippet.description}`) : "";
+							return truncateToWidth(`${pointer}${checkbox} ${theme.bold(snippet.name)} ${theme.fg("dim", `[${snippet.source}]`)}${desc}`, width);
+						};
+
+						const buildListRows = (width: number): { text: string; itemIndex: number | null }[] => {
+							const rows: { text: string; itemIndex: number | null }[] = [];
+							if (prepends.length > 0) {
+								rows.push({ text: theme.fg("dim", "↑ PREPEND — added before your message"), itemIndex: null });
+								prepends.forEach((s, i) => rows.push({ text: itemRow(s, i, width), itemIndex: i }));
+							}
+							if (prepends.length > 0 && appends.length > 0) {
+								rows.push({ text: "", itemIndex: null });
+							}
+							if (appends.length > 0) {
+								rows.push({ text: theme.fg("dim", "↓ APPEND — added after your message"), itemIndex: null });
+								appends.forEach((s, i) =>
+									rows.push({
+										text: itemRow(s, prepends.length + i, width),
+										itemIndex: prepends.length + i,
+									}),
+								);
+							}
+							if (items.length === 0) rows.push({ text: truncateToWidth("No snippets. Press Ctrl+E to create one or restore hidden snippets.", width), itemIndex: null });
+							return rows;
+						};
+
+						const buildPreviewRows = (snippet: Snippet, width: number): string[] => {
+							const rows: string[] = [];
+							rows.push(truncateToWidth(theme.bold(snippet.name), width));
+							const sourceInfo = snippet.source ? ` · [${snippet.source}]` : "";
+							rows.push(
+								truncateToWidth(
+									theme.fg("dim", `${snippet.placement} · order ${snippet.order}${sourceInfo} · ${snippet.id}`),
+									width,
+								),
 							);
-							content = v.out;
-							listScroll = v.scroll;
-							title = "Prompt snippets";
-							hints = "↑↓ navigate • Space toggle • Tab preview • Enter apply • Esc cancel";
-						} else {
-							const snippet = items[cursor];
-							const rows = buildPreviewRows(snippet, width);
-							const v = viewport(rows, previewScroll, maxView);
-							content = v.out;
-							previewScroll = v.scroll;
-							title = `Preview: ${snippet.name}`;
-							hints = "↑↓ scroll • Tab/Esc back";
-						}
-
-						return [
-							theme.fg("accent", "─".repeat(width)),
-							truncateToWidth(` ${theme.fg("accent", theme.bold(title))}`, width),
-							"",
-							...content,
-							"",
-							truncateToWidth(theme.fg("dim", ` ${hints}`), width),
-							theme.fg("accent", "─".repeat(width)),
-						];
-					},
-					invalidate() {},
-					handleInput(data: string) {
-						const maxView = Math.max(5, tui.terminal.rows - 10);
-						const pageSize = Math.max(1, maxView - 2);
-
-						if (mode === "list") {
-							if (isUp(data)) {
-								cursor = (cursor - 1 + items.length) % items.length;
-								tui.requestRender();
-							} else if (isDown(data)) {
-								cursor = (cursor + 1) % items.length;
-								tui.requestRender();
-							} else if (isPageUp(data)) {
-								cursor = Math.max(0, cursor - pageSize);
-								tui.requestRender();
-							} else if (isPageDown(data)) {
-								cursor = Math.min(items.length - 1, cursor + pageSize);
-								tui.requestRender();
-							} else if (matchesKey(data, Key.space)) {
-								const id = items[cursor].id;
-								if (working.has(id)) working.delete(id);
-								else working.add(id);
-								tui.requestRender();
-							} else if (matchesKey(data, Key.tab)) {
-								mode = "preview";
-								previewScroll = 0;
-								tui.requestRender();
-							} else if (isConfirm(data)) {
-								done(true);
-							} else if (isCancel(data)) {
-								done(false);
+							rows.push(theme.fg("dim", "─".repeat(Math.min(width, 40))));
+							for (const line of snippet.body.split("\n")) {
+								for (const wrapped of wrapTextWithAnsi(line, width)) {
+									rows.push(truncateToWidth(wrapped, width));
+								}
 							}
-						} else {
-							if (isUp(data)) {
-								previewScroll = Math.max(0, previewScroll - 1);
-								tui.requestRender();
-							} else if (isDown(data)) {
-								previewScroll++;
-								tui.requestRender();
-							} else if (isPageUp(data)) {
-								previewScroll = Math.max(0, previewScroll - pageSize);
-								tui.requestRender();
-							} else if (isPageDown(data)) {
-								previewScroll += pageSize;
-								tui.requestRender();
-							} else if (matchesKey(data, Key.tab) || isCancel(data)) {
-								mode = "list";
-								tui.requestRender();
+							return rows;
+						};
+
+						const viewport = (
+							lines: string[],
+							scroll: number,
+							maxView: number,
+							focusRow?: number,
+						): { out: string[]; scroll: number } => {
+							const clipped = lines.length > maxView;
+							const view = clipped ? Math.max(1, maxView - 2) : maxView;
+
+							let s = Math.min(Math.max(0, scroll), Math.max(0, lines.length - view));
+							if (focusRow !== undefined) {
+								if (focusRow < s) s = focusRow;
+								else if (focusRow >= s + view) s = focusRow - view + 1;
 							}
-						}
-					},
-				};
-			});
 
-			if (confirmed) {
-				enabled = working;
+							const visible = lines.slice(s, s + view);
+							if (!clipped) return { out: visible, scroll: s };
+
+							const above = s;
+							const below = lines.length - (s + view);
+							return {
+								out: [
+									above > 0 ? theme.fg("dim", `  ↑ ${above} more`) : "",
+									...visible,
+									below > 0 ? theme.fg("dim", `  ↓ ${below} more`) : "",
+								],
+								scroll: s,
+							};
+						};
+
+						return {
+							render(width: number): string[] {
+								const maxView = Math.max(5, tui.terminal.rows - 10);
+
+								let content: string[];
+								let title: string;
+								let hints: string;
+								if (mode === "list") {
+									const rows = buildListRows(width);
+									const cursorRow = rows.findIndex((r) => r.itemIndex === cursor);
+									const v = viewport(
+										rows.map((r) => truncateToWidth(r.text, width)),
+										listScroll,
+										maxView,
+										cursorRow >= 0 ? cursorRow : 0,
+									);
+									content = v.out;
+									listScroll = v.scroll;
+									title = "Prompt snippets";
+									hints = "↑↓ navigate • Space toggle • Tab preview • Enter apply • Esc cancel";
+								} else {
+									const snippet = items[cursor];
+									const rows = buildPreviewRows(snippet, width);
+									const v = viewport(rows, previewScroll, maxView);
+									content = v.out;
+									previewScroll = v.scroll;
+									title = `Preview: ${snippet.name}`;
+									hints = "↑↓ scroll • Tab/Esc back";
+								}
+
+								return [
+									theme.fg("accent", "─".repeat(width)),
+									truncateToWidth(` ${theme.fg("accent", theme.bold(title))}`, width),
+									"",
+									...content,
+									"",
+									truncateToWidth(theme.fg("dim", ` ${hints}`), width),
+									...(mode === "list" ? [truncateToWidth(theme.fg("dim", " Ctrl+E manage snippets (new / edit / delete)"), width)] : []),
+									theme.fg("accent", "─".repeat(width)),
+								];
+							},
+							invalidate() {},
+							handleInput(data: string) {
+								if (finished) return;
+								const maxView = Math.max(5, tui.terminal.rows - 10);
+								const pageSize = Math.max(1, maxView - 2);
+
+								if (mode === "list") {
+									if (matchesKey(data, Key.ctrl("e"))) {
+										finish({ manage: true, id: items[cursor]?.id });
+									} else if (isConfirm(data)) {
+										finish(true);
+									} else if (isCancel(data)) {
+										finish(false);
+									} else if (items.length === 0) {
+										return;
+									} else if (isUp(data)) {
+										cursor = (cursor - 1 + items.length) % items.length;
+										tui.requestRender();
+									} else if (isDown(data)) {
+										cursor = (cursor + 1) % items.length;
+										tui.requestRender();
+									} else if (isPageUp(data)) {
+										cursor = Math.max(0, cursor - pageSize);
+										tui.requestRender();
+									} else if (isPageDown(data)) {
+										cursor = Math.min(items.length - 1, cursor + pageSize);
+										tui.requestRender();
+									} else if (matchesKey(data, Key.space)) {
+										const id = items[cursor].id;
+										if (working.has(id)) working.delete(id);
+										else working.add(id);
+										tui.requestRender();
+									} else if (matchesKey(data, Key.tab)) {
+										mode = "preview";
+										previewScroll = 0;
+										tui.requestRender();
+									}
+								} else {
+									if (isUp(data)) {
+										previewScroll = Math.max(0, previewScroll - 1);
+										tui.requestRender();
+									} else if (isDown(data)) {
+										previewScroll++;
+										tui.requestRender();
+									} else if (isPageUp(data)) {
+										previewScroll = Math.max(0, previewScroll - pageSize);
+										tui.requestRender();
+									} else if (isPageDown(data)) {
+										previewScroll += pageSize;
+										tui.requestRender();
+									} else if (matchesKey(data, Key.tab) || isCancel(data)) {
+										mode = "list";
+										tui.requestRender();
+									}
+								}
+							},
+						};
+					});
+
+					if (typeof confirmed === "object" && confirmed?.manage) {
+						await manageSnippet(ctx, {
+							...extensionOptions,
+							cwd: ctx.cwd,
+							isProjectTrusted: typeof ctx.isProjectTrusted === "function" ? ctx.isProjectTrusted() : true,
+						}, confirmed.id);
+						snippets = getSnippets(ctx);
+						const ids = new Set(snippets.map((s) => s.id));
+						for (const id of working) if (!ids.has(id)) working.delete(id);
+						enabled = new Set([...enabled].filter((id) => ids.has(id)));
+						const selectedIndex = snippets.findIndex((s) => s.id === confirmed.id);
+						cursor = selectedIndex >= 0 ? selectedIndex : Math.max(0, Math.min(cursor, snippets.length - 1));
+						updateWidget(ctx);
+						continue;
+					}
+					if (confirmed) enabled = working;
+					break;
+				}
+			} finally {
+				menuOpen = false;
+				updateWidget(ctx);
 			}
-			updateWidget(ctx);
 		}
 
 		pi.on("session_start", (_event, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zle13/pi-prompt-snippets",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Mix-and-match prompt snippets that prepend or append rules to messages in Pi",
   "type": "module",
   "keywords": [