guardian-framework 0.1.0

package/templates/pi/extensions/redaction.ts

@@ -0,0 +1,128 @@
+/**
+ * Redaction Extension for pi
+ *
+ * Automatically redacts sensitive data from tool results, terminal output,
+ * and agent responses. Prevents accidental leakage of API keys, tokens,
+ * and credentials in conversation history and exported files.
+ *
+ * Patterns detected:
+ *   - OpenAI keys (sk-proj-...)
+ *   - Anthropic keys (sk-ant-...)
+ *   - AWS access keys (AKIA...)
+ *   - GitHub tokens (ghp_, gho_, ghs_, gh_r_, github_pat_)
+ *   - Google API keys (AIza...)
+ *   - Slack tokens (xoxb-...)
+ *   - Stripe keys (sk_live_, pk_live_, sk_test_)
+ *   - JWTs (eyJ...)
+ *   - Bearer tokens
+ *   - Environment variable assignments (API_KEY=..., SECRET=...)
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+// ── Redaction patterns ──
+
+const PATTERNS: Array<{ kind: string; re: RegExp }> = [
+	{ kind: "openai-key", re: /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/g },
+	{ kind: "anthropic-key", re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
+	{ kind: "aws-access-key", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
+	{ kind: "github-token", re: /\bgh[opsur]_[A-Za-z0-9]{36,}\b/g },
+	{ kind: "github-pat", re: /\bgithub_pat_[A-Za-z0-9_]{40,}\b/g },
+	{ kind: "google-api-key", re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+	{ kind: "slack-token", re: /\bxox[bpsare]-[A-Za-z0-9-]{10,}\b/g },
+	{ kind: "stripe-key", re: /\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{24,}\b/g },
+	{ kind: "jwt", re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g },
+	{ kind: "bearer", re: /\bBearer\s+[A-Za-z0-9._-]{20,}/g },
+	{
+		kind: "env-assign",
+		re: /\b((?:[A-Z][A-Z0-9_]*)?(?:API[_-]?KEY|SECRET(?:[_-]?KEY)?|ACCESS[_-]?TOKEN|AUTH[_-]?TOKEN|PASSWORD|PASSWD|PRIVATE[_-]?KEY|CLIENT[_-]?SECRET)[A-Z0-9_]*)\s*[:=]\s*(["']?)([^\s"';|&]+)\2/gi,
+	},
+];
+
+/**
+ * Redact sensitive data from text. Returns the redacted string.
+ */
+export function redactSensitive(text: string): string {
+	let out = text;
+	for (const { kind, re } of PATTERNS) {
+		if (kind === "env-assign") {
+			out = out.replace(
+				re,
+				(_m: string, name: string, q: string, _val: string) => `${name}=${q}<REDACTED>${q}`,
+			);
+		} else {
+			out = out.replace(re, `<REDACTED:${kind}>`);
+		}
+	}
+	return out;
+}
+
+/**
+ * Count redactions made (for logging/telemetry-free reporting).
+ */
+export function countRedactions(text: string): number {
+	let count = 0;
+	for (const { re } of PATTERNS) {
+		const matches = text.match(re);
+		if (matches) count += matches.length;
+	}
+	return count;
+}
+
+// ── Main extension ──
+
+export default function (pi: ExtensionAPI) {
+	// Redact sensitive data from tool results before showing to user
+	pi.on("tool_result", async (event) => {
+		if (!event.result) return;
+
+		// Redact from text results
+		if (typeof event.result === "string") {
+			event.result = redactSensitive(event.result);
+		}
+
+		// Redact from structured results
+		if (typeof event.result === "object" && event.result !== null) {
+			const result = event.result as Record<string, unknown>;
+			for (const [key, value] of Object.entries(result)) {
+				if (typeof value === "string") {
+					result[key] = redactSensitive(value);
+				}
+			}
+		}
+	});
+
+	// Redact from user input (in case they paste a key)
+	pi.on("input", async (event) => {
+		const input = (event as { input?: string }).input;
+		if (!input) return;
+		const redacted = redactSensitive(input);
+		if (redacted !== input) {
+			const count = countRedactions(event.input) - countRedactions(redacted);
+			if (count > 0) {
+				event.input = redacted;
+				// Note: pi extensions can't easily notify without ctx.ui,
+				// but the redaction is applied silently for safety
+			}
+		}
+	});
+
+	// Register /redact command for testing
+	pi.registerCommand("redact", {
+		description: "Test redaction on provided text (for debugging)",
+		handler: async (args, ctx) => {
+			const text = args.join(" ");
+			if (!text) {
+				ctx.ui.notify("Usage: /redact <text to test>", "info");
+				return;
+			}
+			const redacted = redactSensitive(text);
+			const count = countRedactions(text);
+			if (count === 0) {
+				ctx.ui.notify("No sensitive patterns detected.", "success");
+			} else {
+				ctx.ui.notify(`Redacted ${count} sensitive pattern(s):\n\n${redacted}`, "warn");
+			}
+		},
+	});
+}

package/templates/pi/extensions/session-persistence.ts

@@ -0,0 +1,174 @@
+/**
+ * Session Persistence Extension for pi
+ *
+ * Provides structured session lifecycle with:
+ * - Lazy-loaded message history
+ * - Auto-derived session titles
+ * - Per-session state isolation (todos, read cache)
+ * - Atomic JSON storage with temp-file writes
+ *
+ * Storage: guardian-sessions.json in workspace root
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+// ── Types ──
+
+interface SessionMeta {
+	id: string;
+	title: string;
+	createdAt: number;
+	updatedAt: number;
+}
+
+interface StoredSession {
+	sessions: SessionMeta[];
+	activeId: string | null;
+}
+
+const STORE_FILE = "guardian-sessions.json";
+const MAX_SESSIONS = 50;
+
+// ── Storage helpers ──
+
+function storePath(cwd: string): string {
+	return path.join(cwd, STORE_FILE);
+}
+
+function loadStore(cwd: string): StoredSession {
+	const p = storePath(cwd);
+	if (!fs.existsSync(p)) {
+		return { sessions: [], activeId: null };
+	}
+	try {
+		return JSON.parse(fs.readFileSync(p, "utf-8")) as StoredSession;
+	} catch {
+		return { sessions: [], activeId: null };
+	}
+}
+
+function saveStore(cwd: string, store: StoredSession): void {
+	const p = storePath(cwd);
+	const tmp = `${p}.tmp`;
+	fs.writeFileSync(tmp, JSON.stringify(store, null, 2), "utf-8");
+	fs.renameSync(tmp, p);
+}
+
+function newSessionId(): string {
+	const ts = Date.now().toString(36);
+	const rand = Math.random().toString(36).slice(2, 8);
+	return `s-${ts}-${rand}`;
+}
+
+// Derive title from first user message, stripping context blocks
+function deriveTitle(firstUserMessage: string): string {
+	const text = firstUserMessage
+		.replace(/<terminal-context[\s\S]*?<\/terminal-context>/g, "")
+		.replace(/<selection[\s\S]*?<\/selection>/g, "")
+		.replace(/<file[\s\S]*?<\/file>/g, "")
+		.replace(/<snippet[\s\S]*?<\/snippet>/g, "")
+		.trim();
+	if (!text) return "New session";
+	const first = text.split("\n")[0].trim();
+	return first.length > 40 ? `${first.slice(0, 40)}…` : first;
+}
+
+// ── Main extension ──
+
+export default function (pi: ExtensionAPI) {
+	let currentSession: SessionMeta | null = null;
+
+	pi.on("session_start", async (_event, ctx) => {
+		const store = loadStore(ctx.cwd);
+
+		// Restore active session or create new one
+		if (store.activeId) {
+			const existing = store.sessions.find((s) => s.id === store.activeId);
+			if (existing) {
+				currentSession = existing;
+				ctx.ui.setStatus("session", `📂 ${existing.title}`);
+				return;
+			}
+		}
+
+		// Create new session
+		currentSession = {
+			id: newSessionId(),
+			title: "New session",
+			createdAt: Date.now(),
+			updatedAt: Date.now(),
+		};
+
+		store.sessions.unshift(currentSession);
+
+		// Trim old sessions
+		if (store.sessions.length > MAX_SESSIONS) {
+			store.sessions = store.sessions.slice(0, MAX_SESSIONS);
+		}
+
+		store.activeId = currentSession.id;
+		saveStore(ctx.cwd, store);
+
+		ctx.ui.setStatus("session", `📂 ${currentSession.title}`);
+	});
+
+	// Update session title after first user message
+	pi.on("input", async (event, ctx) => {
+		if (!currentSession) return;
+		if (currentSession.title !== "New session") return;
+
+		const input = (event as { input?: string }).input;
+		if (!input) return;
+		const title = deriveTitle(input);
+		currentSession.title = title;
+		currentSession.updatedAt = Date.now();
+
+		const store = loadStore(ctx.cwd);
+		const idx = store.sessions.findIndex((s) => s.id === currentSession?.id);
+		if (idx >= 0) {
+			store.sessions[idx] = currentSession;
+			saveStore(ctx.cwd, store);
+		}
+
+		ctx.ui.setStatus("session", `📂 ${title}`);
+	});
+
+	// Track session activity
+	pi.on("tool_result", async (_event, ctx) => {
+		if (!currentSession) return;
+		currentSession.updatedAt = Date.now();
+
+		const store = loadStore(ctx.cwd);
+		const idx = store.sessions.findIndex((s) => s.id === currentSession?.id);
+		if (idx >= 0) {
+			store.sessions[idx] = currentSession;
+			saveStore(ctx.cwd, store);
+		}
+	});
+
+	// /sessions command — list sessions
+	pi.registerCommand("sessions", {
+		description: "List all sessions",
+		handler: async (_args, ctx) => {
+			const store = loadStore(ctx.cwd);
+			if (store.sessions.length === 0) {
+				ctx.ui.notify("No sessions.", "info");
+				return;
+			}
+			const lines = store.sessions.map((s) => {
+				const marker = s.id === currentSession?.id ? "▶ " : "  ";
+				const age = Date.now() - s.updatedAt;
+				const ageStr =
+					age < 60_000
+						? "just now"
+						: age < 3_600_000
+							? `${Math.floor(age / 60_000)}m ago`
+							: `${Math.floor(age / 3_600_000)}h ago`;
+				return `${marker}${s.title} (${ageStr})`;
+			});
+			ctx.ui.notify(`Sessions:\n\n${lines.join("\n")}`, "info");
+		},
+	});
+}

package/templates/pi/extensions/slash-commands.ts

@@ -0,0 +1,229 @@
+/**
+ * Slash Commands Extension for pi
+ *
+ * Intercepts user input starting with `/` and transforms slash commands into
+ * structured actions. Supports:
+ *   /init   — Workspace initialization prompt
+ *   /plan   — Plan mode toggle
+ *   /validate — Run all validators
+ *   /scope  — Classify task scope
+ *   /snippet — Snippet management (#handle expansion)
+ *
+ * Also handles `#handle` token expansion for snippets.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+// ── Snippet types ──
+
+interface Snippet {
+	id: string;
+	handle: string;
+	name: string;
+	description: string;
+	content: string;
+}
+
+const SNIPPETS_FILE = "guardian-snippets.json";
+const HANDLE_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+function loadSnippets(cwd: string): Snippet[] {
+	const snippetsPath = path.join(cwd, SNIPPETS_FILE);
+	if (!fs.existsSync(snippetsPath)) return [];
+	try {
+		return JSON.parse(fs.readFileSync(snippetsPath, "utf-8")) as Snippet[];
+	} catch {
+		return [];
+	}
+}
+
+function saveSnippets(cwd: string, snippets: Snippet[]): void {
+	const tmpPath = path.join(cwd, `${SNIPPETS_FILE}.tmp`);
+	const finalPath = path.join(cwd, SNIPPETS_FILE);
+	fs.writeFileSync(tmpPath, JSON.stringify(snippets, null, 2), "utf-8");
+	fs.renameSync(tmpPath, finalPath);
+}
+
+function newSnippetId(): string {
+	return `sn-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}
+
+function normalizeHandle(raw: string): string {
+	return raw
+		.trim()
+		.toLowerCase()
+		.replace(/\s+/g, "-")
+		.replace(/[^a-z0-9-]/g, "")
+		.replace(/-+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+// Expand #handle tokens in text
+function expandSnippetTokens(
+	text: string,
+	snippets: Snippet[],
+): { body: string; blocks: string[] } {
+	const byHandle = new Map(snippets.map((s) => [s.handle, s]));
+	const matched = new Map<string, Snippet>();
+
+	const re = /(^|\s)#([a-z0-9][a-z0-9-]*)\b/gi;
+	const body = text.replace(re, (full, lead: string, raw: string) => {
+		const h = raw.toLowerCase();
+		const snip = byHandle.get(h);
+		if (!snip) return full;
+		matched.set(snip.id, snip);
+		return lead;
+	});
+
+	const blocks = Array.from(matched.values()).map(
+		(s) => `<snippet name="${s.handle}">\n${s.content}\n</snippet>`,
+	);
+	return {
+		body: body.replace(/[ \t]+\n/g, "\n").trim(),
+		blocks,
+	};
+}
+
+// ── Command definitions ──
+
+const INIT_PROMPT = `Scan this workspace and produce a project memory file (.pi/PROJECT.md) with:
+- One-paragraph project description
+- Build / test / dev commands
+- Architecture overview (subsystems, data flow, key dirs)
+- Conventions worth knowing (naming, patterns, gotchas)
+- Paths to entry points
+Cap under 200 lines.`;
+
+const VALIDATE_PROMPT = `Run all Guardian validators. For each validator:
+1. Run the script: .pi/scripts/validate-<name>.sh
+2. Report pass/fail with output
+3. If any fail, suggest fixes
+Validators to run: [check manifest for configured validators]`;
+
+const SCOPE_PROMPT = `Classify the following task scope:
+- Estimate files affected and lines changed
+- Determine required validators (ci, architecture, security, etc.)
+- Assess risk level (simple, moderate, complex, critical)
+
+Task: {task_description}`;
+
+// ── Main extension ──
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", async () => {
+		// Load snippets at session start
+		const snippets = loadSnippets(process.cwd());
+		if (snippets.length > 0) {
+			pi.appendEntry({
+				key: "guardian:snippets",
+				value: snippets.map((s) => `#${s.handle} — ${s.description}`),
+			});
+		}
+	});
+
+	// Intercept user input for slash commands and snippet expansion
+	pi.on("input", async (event, ctx) => {
+		const input = (event as { input?: string }).input;
+		if (!input) return;
+		const trimmed = input.trim();
+
+		// Handle #handle snippet expansion
+		if (trimmed.startsWith("#")) {
+			const snippets = loadSnippets(ctx.cwd);
+			const { body, blocks } = expandSnippetTokens(input, snippets);
+			if (blocks.length > 0) {
+				event.input = [...blocks, body].join("\n\n");
+				return;
+			}
+		}
+
+		// Handle /command
+		if (!trimmed.startsWith("/")) return;
+		const [cmd, ...args] = trimmed.slice(1).split(/\s+/);
+		const argStr = args.join(" ");
+
+		switch (cmd) {
+			case "init":
+				event.input = INIT_PROMPT;
+				ctx.ui.setStatus("command", "/init — workspace scan");
+				break;
+
+			case "validate":
+				event.input = VALIDATE_PROMPT;
+				ctx.ui.setStatus("command", "/validate — running validators");
+				break;
+
+			case "scope":
+				event.input = SCOPE_PROMPT.replace("{task_description}", argStr || "current task");
+				ctx.ui.setStatus("command", "/scope — classifying task");
+				break;
+
+			case "plan":
+				// Plan mode is handled by plan-mode.ts extension
+				ctx.ui.notify("Plan mode: use the plan-mode extension for /plan commands", "info");
+				break;
+
+			case "snippet": {
+				const snippets = loadSnippets(ctx.cwd);
+				if (args[0] === "list") {
+					if (snippets.length === 0) {
+						ctx.ui.notify(
+							"No snippets configured. Use /snippet add <handle> to create one.",
+							"info",
+						);
+					} else {
+						const list = snippets
+							.map((s) => `#${s.handle} — ${s.name}: ${s.description}`)
+							.join("\n");
+						ctx.ui.notify(`Snippets:\n\n${list}`, "info");
+					}
+				} else if (args[0] === "add" && args.length >= 2) {
+					const handle = normalizeHandle(args[1]);
+					if (!HANDLE_RE.test(handle)) {
+						ctx.ui.notify(
+							`Invalid handle: "${args[1]}". Use lowercase letters, numbers, and hyphens.`,
+							"error",
+						);
+						break;
+					}
+					const name = args.slice(2).join(" ") || handle;
+					const content = await ctx.ui.input("Snippet content", "Enter the snippet body...");
+					if (!content) break;
+					snippets.push({
+						id: newSnippetId(),
+						handle,
+						name,
+						description: name,
+						content,
+					});
+					saveSnippets(ctx.cwd, snippets);
+					ctx.ui.notify(`Snippet #${handle} created.`, "success");
+				} else if (args[0] === "remove" && args.length >= 2) {
+					const handle = normalizeHandle(args[1]);
+					const before = snippets.length;
+					const filtered = snippets.filter((s) => s.handle !== handle);
+					if (filtered.length === before) {
+						ctx.ui.notify(`Snippet #${handle} not found.`, "error");
+					} else {
+						saveSnippets(ctx.cwd, filtered);
+						ctx.ui.notify(`Snippet #${handle} removed.`, "success");
+					}
+				} else {
+					ctx.ui.notify(
+						"Usage: /snippet list | /snippet add <handle> [name] | /snippet remove <handle>",
+						"info",
+					);
+				}
+				// Don't send to agent — command handled
+				event.input = "(snippet command handled — no agent response needed)";
+				break;
+			}
+
+			default:
+				// Unknown command — let it through as normal text
+				break;
+		}
+	});
+}