@heyhuynhgiabuu/pi-pretty 0.2.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@heyhuynhgiabuu/pi-pretty",
-	"version": "0.2.0",
+	"version": "0.3.1",
 	"description": "Pretty terminal output for pi — syntax-highlighted file reads, colored bash output, tree-view directory listings, and more.",
 	"author": "huynhgiabuu",
 	"license": "MIT",
@@ -24,6 +24,9 @@
 	"dependencies": {
 		"@shikijs/cli": "^4.0.2"
 	},
+	"optionalDependencies": {
+		"@ff-labs/fff-node": "0.5.2"
+	},
 	"peerDependencies": {
 		"@mariozechner/pi-coding-agent": "*",
 		"@mariozechner/pi-tui": "*"

package/src/fff-helpers.ts

@@ -0,0 +1,73 @@
+/**
+ * FFF helper functions — extracted for testability.
+ *
+ * Pure functions and classes used by the FFF integration in index.ts.
+ */
+
+/**
+ * Store for FFF grep pagination cursors.
+ * Evicts oldest entry when exceeding maxSize.
+ */
+export class CursorStore {
+	private cursors = new Map<string, any>();
+	private counter = 0;
+	private maxSize: number;
+
+	constructor(maxSize = 200) {
+		this.maxSize = maxSize;
+	}
+
+	store(cursor: any): string {
+		const id = `fff_c${++this.counter}`;
+		this.cursors.set(id, cursor);
+		if (this.cursors.size > this.maxSize) {
+			const first = this.cursors.keys().next().value;
+			if (first) this.cursors.delete(first);
+		}
+		return id;
+	}
+
+	get(id: string): any | undefined {
+		return this.cursors.get(id);
+	}
+
+	get size(): number {
+		return this.cursors.size;
+	}
+}
+
+/**
+ * Convert FFF GrepResult items to ripgrep-style "file:line:content" text.
+ * This ensures pi-pretty's renderGrepResults works unchanged.
+ */
+export function fffFormatGrepText(items: any[], limit: number): string {
+	const capped = items.slice(0, limit);
+	if (!capped.length) return "No matches found";
+
+	const lines: string[] = [];
+	let currentFile = "";
+
+	for (const match of capped) {
+		if (match.relativePath !== currentFile) {
+			if (currentFile) lines.push("");
+			currentFile = match.relativePath;
+		}
+		if (match.contextBefore?.length) {
+			const startLine = match.lineNumber - match.contextBefore.length;
+			for (let i = 0; i < match.contextBefore.length; i++) {
+				lines.push(`${match.relativePath}-${startLine + i}-${match.contextBefore[i]}`);
+			}
+		}
+		const content =
+			match.lineContent.length > 500 ? `${match.lineContent.slice(0, 500)}...` : match.lineContent;
+		lines.push(`${match.relativePath}:${match.lineNumber}:${content}`);
+		if (match.contextAfter?.length) {
+			const startLine = match.lineNumber + 1;
+			for (let i = 0; i < match.contextAfter.length; i++) {
+				lines.push(`${match.relativePath}-${startLine + i}-${match.contextAfter[i]}`);
+			}
+		}
+	}
+
+	return lines.join("\n");
+}

package/src/index.ts

@@ -23,12 +23,14 @@
  *   • Large-file fallback (skip highlighting, still show line numbers)
  */
 
-import { existsSync, statSync } from "node:fs";
-import { basename, dirname, extname, relative } from "node:path";
+import { existsSync, mkdirSync, statSync } from "node:fs";
+import { basename, dirname, extname, join, relative } from "node:path";
 
 import { codeToANSI } from "@shikijs/cli";
 import type { BundledLanguage, BundledTheme } from "shiki";
 
+import { CursorStore, fffFormatGrepText } from "./fff-helpers.js";
+
 // ---------------------------------------------------------------------------
 // Config
 // ---------------------------------------------------------------------------
@@ -669,11 +671,63 @@ async function renderGrepResults(text: string, pattern: string): Promise<string>
 	return out.join("\n");
 }
 
+// ---------------------------------------------------------------------------
+// FFF integration (optional) — Fast File Finder with frecency & SIMD search
+//
+// If @ff-labs/fff-node is installed, find/grep use FFF for speed + frecency.
+// If not, falls back to wrapping SDK tools (current behavior).
+// ---------------------------------------------------------------------------
+
+const _cursorStore = new CursorStore();
+let _fffModule: any = null;
+let _fffFinder: any = null;
+let _fffPartialIndex = false;
+let _fffDbDir: string | null = null;
+const FFF_SCAN_TIMEOUT = 15_000;
+
+async function fffEnsureFinder(cwd: string): Promise<any> {
+	if (_fffFinder && !_fffFinder.isDestroyed) return _fffFinder;
+	if (!_fffModule || !_fffDbDir) return null;
+
+	const result = _fffModule.FileFinder.create({
+		basePath: cwd,
+		frecencyDbPath: join(_fffDbDir, "frecency.mdb"),
+		historyDbPath: join(_fffDbDir, "history.mdb"),
+		aiMode: true,
+	});
+
+	if (!result.ok) throw new Error(`FFF init failed: ${result.error}`);
+
+	_fffFinder = result.value;
+	const scan = await _fffFinder.waitForScan(FFF_SCAN_TIMEOUT);
+	_fffPartialIndex = scan.ok && !scan.value;
+
+	return _fffFinder;
+}
+
+function fffDestroy(): void {
+	if (_fffFinder && !_fffFinder.isDestroyed) {
+		_fffFinder.destroy();
+		_fffFinder = null;
+	}
+	_fffPartialIndex = false;
+}
+
 // ---------------------------------------------------------------------------
 // Extension entry point
 // ---------------------------------------------------------------------------
 
-export default function piPrettyExtension(pi: any): void {
+/**
+ * Dependencies that can be injected for testing.
+ * In production, omit `deps` — the extension uses require() to load them.
+ */
+export interface PiPrettyDeps {
+	sdk: any;
+	TextComponent: any;
+	fffModule?: any;
+}
+
+export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 	let createReadTool: any;
 	let createBashTool: any;
 	let createLsTool: any;
@@ -681,16 +735,33 @@ export default function piPrettyExtension(pi: any): void {
 	let createGrepTool: any;
 	let TextComponent: any;
 
-	try {
-		const sdk = require("@mariozechner/pi-coding-agent");
+	let sdk: any;
+
+	if (deps) {
+		// Test path: use injected dependencies, reset module state
+		sdk = deps.sdk;
 		createReadTool = sdk.createReadToolDefinition ?? sdk.createReadTool;
 		createBashTool = sdk.createBashToolDefinition ?? sdk.createBashTool;
 		createLsTool = sdk.createLsToolDefinition ?? sdk.createLsTool;
 		createFindTool = sdk.createFindToolDefinition ?? sdk.createFindTool;
 		createGrepTool = sdk.createGrepToolDefinition ?? sdk.createGrepTool;
-		TextComponent = require("@mariozechner/pi-tui").Text;
-	} catch {
-		return;
+		TextComponent = deps.TextComponent;
+		_fffModule = deps.fffModule ?? null;
+		_fffFinder = null;
+		_fffPartialIndex = false;
+		_fffDbDir = null;
+	} else {
+		try {
+			sdk = require("@mariozechner/pi-coding-agent");
+			createReadTool = sdk.createReadToolDefinition ?? sdk.createReadTool;
+			createBashTool = sdk.createBashToolDefinition ?? sdk.createBashTool;
+			createLsTool = sdk.createLsToolDefinition ?? sdk.createLsTool;
+			createFindTool = sdk.createFindToolDefinition ?? sdk.createFindTool;
+			createGrepTool = sdk.createGrepToolDefinition ?? sdk.createGrepTool;
+			TextComponent = require("@mariozechner/pi-tui").Text;
+		} catch {
+			return;
+		}
 	}
 	if (!createReadTool || !TextComponent) return;
 
@@ -698,6 +769,66 @@ export default function piPrettyExtension(pi: any): void {
 	const home = process.env.HOME ?? "";
 	const sp = (p: string) => shortPath(cwd, home, p);
 
+	// ===================================================================
+	// FFF initialization (optional — graceful fallback to SDK)
+	// ===================================================================
+
+	const getAgentDir = (sdk as any).getAgentDir;
+	if (!deps) {
+		// Only try require() in production — tests inject fffModule via deps
+		try {
+			_fffModule = require("@ff-labs/fff-node");
+			if (getAgentDir) {
+				_fffDbDir = join(getAgentDir(), "fff");
+				try {
+					mkdirSync(_fffDbDir, { recursive: true });
+				} catch {}
+			}
+		} catch {
+			/* FFF not installed — SDK tools will be used */
+		}
+	} else if (_fffModule && getAgentDir) {
+		_fffDbDir = join(getAgentDir(), "fff");
+		try {
+			mkdirSync(_fffDbDir, { recursive: true });
+		} catch {}
+	}
+
+	pi.on("session_start", async (_event: any, ctx: any) => {
+		// Try dynamic import if sync require failed (ESM-only package)
+		if (!_fffModule) {
+			try {
+				// @ts-ignore — optional dependency, may not be installed
+				_fffModule = await import("@ff-labs/fff-node");
+			} catch {}
+		}
+		if (!_fffModule) return;
+
+		if (!_fffDbDir) {
+			const agentDir = getAgentDir?.() ?? join(home, ".pi/agent");
+			_fffDbDir = join(agentDir, "fff");
+			try {
+				mkdirSync(_fffDbDir, { recursive: true });
+			} catch {}
+		}
+
+		try {
+			await fffEnsureFinder(ctx.cwd);
+			if (_fffPartialIndex) {
+				ctx.ui?.notify?.("FFF: scan timed out — using partial index. Run /fff-rescan when ready.", "warning");
+			} else {
+				ctx.ui?.setStatus?.("fff", "FFF indexed");
+				setTimeout(() => ctx.ui?.setStatus?.("fff", undefined), 3000);
+			}
+		} catch (e: any) {
+			ctx.ui?.notify?.(`FFF init failed: ${e.message}`, "error");
+		}
+	});
+
+	pi.on("session_shutdown", async () => {
+		fffDestroy();
+	});
+
 	// ===================================================================
 	// read — syntax-highlighted file content
 	// ===================================================================
@@ -1013,6 +1144,43 @@ export default function piPrettyExtension(pi: any): void {
 			name: "find",
 
 			async execute(tid: string, params: any, sig: any, upd: any, ctx: any) {
+				// Try FFF first (frecency-ranked, SIMD-accelerated)
+				if (_fffFinder && !_fffFinder.isDestroyed) {
+					try {
+						const effectiveLimit = Math.max(1, params.limit ?? 200);
+						let query = params.pattern ?? "";
+						if (params.path) query = `${params.path} ${query}`;
+
+						const searchResult = _fffFinder.fileSearch(query, { pageSize: effectiveLimit });
+						if (searchResult.ok) {
+							const items = searchResult.value.items.slice(0, effectiveLimit);
+							let textContent = items.map((i: any) => i.relativePath).join("\n");
+							const matchCount = items.length;
+
+							const notices: string[] = [];
+							if (_fffPartialIndex) notices.push("Warning: partial file index");
+							if (items.length >= effectiveLimit) notices.push(`${effectiveLimit} limit reached`);
+							if (searchResult.value.totalMatched > items.length) {
+								notices.push(`${searchResult.value.totalMatched} total matches`);
+							}
+							if (notices.length) textContent += `\n\n[${notices.join(". ")}]`;
+
+							return {
+								content: [{ type: "text", text: textContent }],
+								details: {
+									_type: "findResult",
+									text: textContent,
+									pattern: params.pattern ?? "",
+									matchCount,
+								},
+							};
+						}
+					} catch {
+						/* fall through to SDK */
+					}
+				}
+
+				// SDK fallback
 				const result = await origFind.execute(tid, params, sig, upd, ctx);
 
 				const textContent = result.content
@@ -1082,6 +1250,58 @@ export default function piPrettyExtension(pi: any): void {
 			name: "grep",
 
 			async execute(tid: string, params: any, sig: any, upd: any, ctx: any) {
+				// Try FFF first (SIMD-accelerated, frecency-ranked)
+				if (_fffFinder && !_fffFinder.isDestroyed) {
+					try {
+						const effectiveLimit = Math.max(1, params.limit ?? 100);
+						let query = params.pattern ?? "";
+						if (params.glob) query = `${params.glob} ${query}`;
+						else if (params.path) query = `${params.path} ${query}`;
+
+						const mode = params.literal ? "plain" : "regex";
+
+						const grepResult = _fffFinder.grep(query, {
+							mode,
+							smartCase: !params.ignoreCase,
+							maxMatchesPerFile: Math.min(effectiveLimit, 50),
+							cursor: null,
+							beforeContext: params.context ?? 0,
+							afterContext: params.context ?? 0,
+						});
+
+						if (grepResult.ok) {
+							const result = grepResult.value;
+							let textContent = fffFormatGrepText(result.items, effectiveLimit);
+							const matchCount = Math.min(result.items.length, effectiveLimit);
+
+							const notices: string[] = [];
+							if (_fffPartialIndex) notices.push("Warning: partial file index");
+							if (result.items.length >= effectiveLimit) notices.push(`${effectiveLimit} limit reached`);
+							if ((result as any).regexFallbackError) {
+								notices.push(`Regex failed: ${(result as any).regexFallbackError}, used literal match`);
+							}
+							if (result.nextCursor) {
+								const cursorId = _cursorStore.store(result.nextCursor);
+								notices.push(`More results available. Use cursor="${cursorId}" to continue`);
+							}
+							if (notices.length) textContent += `\n\n[${notices.join(". ")}]`;
+
+							return {
+								content: [{ type: "text", text: textContent }],
+								details: {
+									_type: "grepResult",
+									text: textContent,
+									pattern: params.pattern ?? "",
+									matchCount,
+								},
+							};
+						}
+					} catch {
+						/* fall through to SDK */
+					}
+				}
+
+				// SDK fallback
 				const result = await origGrep.execute(tid, params, sig, upd, ctx);
 
 				const textContent = result.content
@@ -1156,4 +1376,227 @@ export default function piPrettyExtension(pi: any): void {
 			},
 		});
 	}
+
+	// ===================================================================
+	// multi_grep — FFF-only OR-logic multi-pattern search
+	// ===================================================================
+
+	if (_fffModule) {
+		pi.registerTool({
+			name: "multi_grep",
+			label: "multi_grep (fff)",
+			description: [
+				"Search file contents for lines matching ANY of multiple patterns (OR logic).",
+				"Uses SIMD-accelerated Aho-Corasick multi-pattern matching. Faster than regex alternation.",
+				"Patterns are literal text — never escape special characters.",
+				"Use the constraints parameter for file filtering ('*.rs', 'src/', '!test/').",
+			].join(" "),
+			promptSnippet:
+				"Multi-pattern OR search across file contents (FFF: SIMD-accelerated, frecency-ranked)",
+			promptGuidelines: [
+				"Use multi_grep when you need to find multiple identifiers at once (OR logic).",
+				"Include all naming conventions: snake_case, PascalCase, camelCase variants.",
+				"Patterns are literal text. Never escape special characters.",
+				"Use the constraints parameter for file type/path filtering, not inside patterns.",
+			],
+
+			parameters: {
+				type: "object",
+				properties: {
+					patterns: {
+						type: "array",
+						items: { type: "string" },
+						description: "Patterns to search for (OR logic — matches lines containing ANY pattern).",
+					},
+					constraints: {
+						type: "string",
+						description: "File constraints, e.g. '*.{ts,tsx} !test/' to filter files.",
+					},
+					context: {
+						type: "number",
+						description: "Number of context lines before and after each match (default: 0)",
+					},
+					limit: {
+						type: "number",
+						description: "Maximum number of matches to return (default: 100)",
+					},
+				},
+				required: ["patterns"],
+			},
+
+			async execute(_tid: string, params: any, sig: any, _upd: any, _ctx: any) {
+				if (sig?.aborted) return { content: [{ type: "text", text: "Aborted" }], details: {} };
+
+				if (!params.patterns || params.patterns.length === 0) {
+					return {
+						content: [{ type: "text", text: "Error: patterns array must have at least 1 element" }],
+						details: { error: "empty patterns" },
+					};
+				}
+
+				if (!_fffFinder || _fffFinder.isDestroyed) {
+					return {
+						content: [{ type: "text", text: "FFF not initialized. Wait for session start or run /fff-rescan." }],
+						details: {},
+					};
+				}
+
+				try {
+					const effectiveLimit = Math.max(1, params.limit ?? 100);
+
+					const grepResult = _fffFinder.multiGrep({
+						patterns: params.patterns,
+						constraints: params.constraints,
+						maxMatchesPerFile: Math.min(effectiveLimit, 50),
+						smartCase: true,
+						cursor: null,
+						beforeContext: params.context ?? 0,
+						afterContext: params.context ?? 0,
+					});
+
+					if (!grepResult.ok) {
+						return {
+							content: [{ type: "text", text: `multi_grep error: ${grepResult.error}` }],
+							details: { error: grepResult.error },
+						};
+					}
+
+					const result = grepResult.value;
+					let textContent = fffFormatGrepText(result.items, effectiveLimit);
+					const matchCount = Math.min(result.items.length, effectiveLimit);
+
+					const notices: string[] = [];
+					if (_fffPartialIndex) notices.push("Warning: partial file index");
+					if (result.items.length >= effectiveLimit) notices.push(`${effectiveLimit} limit reached`);
+					if (result.nextCursor) {
+						const cursorId = _cursorStore.store(result.nextCursor);
+						notices.push(`More results: cursor="${cursorId}"`);
+					}
+					if (notices.length) textContent += `\n\n[${notices.join(". ")}]`;
+
+					return {
+						content: [{ type: "text", text: textContent }],
+						details: {
+							_type: "grepResult",
+							text: textContent,
+							pattern: params.patterns.join(" | "),
+							matchCount,
+						},
+					};
+				} catch (e: any) {
+					return {
+						content: [{ type: "text", text: `multi_grep error: ${e.message}` }],
+						details: { error: e.message },
+					};
+				}
+			},
+
+			renderCall(args: any, theme: any, ctx: any) {
+				resolveBaseBackground(theme);
+				const patterns = args?.patterns ?? [];
+				const constraints = args?.constraints;
+				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
+				let content =
+					theme.fg("toolTitle", theme.bold("multi_grep")) +
+					" " +
+					theme.fg("accent", patterns.map((p: string) => `"${p}"`).join(", "));
+				if (constraints) content += theme.fg("muted", ` (${constraints})`);
+				text.setText(content);
+				return text;
+			},
+
+			renderResult(result: any, _opt: any, theme: any, ctx: any) {
+				resolveBaseBackground(theme);
+				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
+
+				if (ctx.isError) {
+					const e = result.content?.[0]?.text ?? "Error";
+					text.setText(`\n${theme.fg("error", e)}`);
+					return text;
+				}
+
+				const d = result.details;
+				if (d?._type === "grepResult" && d.text) {
+					const key = `mgrep:${d.pattern}:${d.matchCount}:${termW()}`;
+					if (ctx.state._mgk !== key) {
+						ctx.state._mgk = key;
+						const info = `${FG_DIM}${d.matchCount} matches${RST}`;
+						ctx.state._mgt = `  ${info}`;
+
+						renderGrepResults(d.text, d.pattern)
+							.then((rendered: string) => {
+								if (ctx.state._mgk !== key) return;
+								ctx.state._mgt = `  ${info}\n${rendered}`;
+								ctx.invalidate();
+							})
+							.catch(() => {});
+					}
+					text.setText(ctx.state._mgt ?? `  ${FG_DIM}${d.matchCount} matches${RST}`);
+					return text;
+				}
+
+				const fallback = result.content?.[0]?.text ?? "searched";
+				text.setText(`  ${theme.fg("dim", String(fallback).slice(0, 120))}`);
+				return text;
+			},
+		});
+	}
+
+	// ===================================================================
+	// FFF commands
+	// ===================================================================
+
+	if (_fffModule) {
+		pi.registerCommand("fff-health", {
+			description: "Show FFF file finder health and indexer status",
+			handler: async (_args: any, ctx: any) => {
+				if (!_fffFinder || _fffFinder.isDestroyed) {
+					ctx.ui?.notify?.("FFF not initialized", "warning");
+					return;
+				}
+
+				const health = _fffFinder.healthCheck();
+				if (!health.ok) {
+					ctx.ui?.notify?.(`Health check failed: ${health.error}`, "error");
+					return;
+				}
+
+				const h = health.value;
+				const lines = [
+					`FFF v${h.version}`,
+					`Git: ${h.git.repositoryFound ? `yes (${h.git.workdir ?? "unknown"})` : "no"}`,
+					`Picker: ${h.filePicker.initialized ? `${h.filePicker.indexedFiles ?? 0} files` : "not initialized"}`,
+					`Frecency: ${h.frecency.initialized ? "active" : "disabled"}`,
+					`Query tracker: ${h.queryTracker.initialized ? "active" : "disabled"}`,
+					`Partial index: ${_fffPartialIndex ? "yes (scan timed out)" : "no"}`,
+				];
+
+				const progress = _fffFinder.getScanProgress();
+				if (progress.ok) {
+					lines.push(`Scanning: ${progress.value.isScanning ? "yes" : "no"} (${progress.value.scannedFilesCount} files)`);
+				}
+
+				ctx.ui?.notify?.(lines.join("\n"), "info");
+			},
+		});
+
+		pi.registerCommand("fff-rescan", {
+			description: "Trigger FFF to rescan files",
+			handler: async (_args: any, ctx: any) => {
+				if (!_fffFinder || _fffFinder.isDestroyed) {
+					ctx.ui?.notify?.("FFF not initialized", "warning");
+					return;
+				}
+
+				const result = _fffFinder.scanFiles();
+				if (!result.ok) {
+					ctx.ui?.notify?.(`Rescan failed: ${result.error}`, "error");
+					return;
+				}
+
+				_fffPartialIndex = false;
+				ctx.ui?.notify?.("FFF rescan triggered", "info");
+			},
+		});
+	}
 }

package/test/fff-integration.test.ts

@@ -0,0 +1,455 @@
+/**
+ * Tests for pi-pretty FFF integration vs SDK fallback.
+ *
+ * 1. Unit tests for CursorStore + fffFormatGrepText (extracted helpers)
+ * 2. Integration tests via dependency injection (PiPrettyDeps)
+ *    - SDK fallback path (no FFF)
+ *    - FFF path (FFF injected)
+ *    - Graceful degradation (FFF fails → SDK fallback)
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { CursorStore, fffFormatGrepText } from "../src/fff-helpers.js";
+import piPrettyExtension, { type PiPrettyDeps } from "../src/index.js";
+
+// =========================================================================
+// 1. Unit tests — pure functions
+// =========================================================================
+
+describe("CursorStore", () => {
+	it("stores and retrieves a cursor", () => {
+		const store = new CursorStore();
+		const cursor = { page: 2, offset: 50 };
+		const id = store.store(cursor);
+		expect(id).toMatch(/^fff_c\d+$/);
+		expect(store.get(id)).toBe(cursor);
+	});
+
+	it("returns undefined for unknown id", () => {
+		expect(new CursorStore().get("fff_c999")).toBeUndefined();
+	});
+
+	it("increments ids sequentially", () => {
+		const store = new CursorStore();
+		const n1 = Number.parseInt(store.store("a").slice(5), 10);
+		const n2 = Number.parseInt(store.store("b").slice(5), 10);
+		expect(n2).toBe(n1 + 1);
+	});
+
+	it("evicts oldest when exceeding maxSize", () => {
+		const store = new CursorStore(3);
+		const id1 = store.store("a");
+		store.store("b"); store.store("c");
+		expect(store.size).toBe(3);
+		store.store("d");
+		expect(store.size).toBe(3);
+		expect(store.get(id1)).toBeUndefined();
+	});
+
+	it("default maxSize is 200", () => {
+		const store = new CursorStore();
+		const ids: string[] = [];
+		for (let i = 0; i < 201; i++) ids.push(store.store(i));
+		expect(store.size).toBe(200);
+		expect(store.get(ids[0])).toBeUndefined();
+		expect(store.get(ids[200])).toBe(200);
+	});
+});
+
+describe("fffFormatGrepText", () => {
+	it("empty → 'No matches found'", () => {
+		expect(fffFormatGrepText([], 100)).toBe("No matches found");
+	});
+
+	it("single match → file:line:content", () => {
+		const items = [{ relativePath: "src/a.ts", lineNumber: 42, lineContent: "const x = 1;" }];
+		expect(fffFormatGrepText(items, 100)).toBe("src/a.ts:42:const x = 1;");
+	});
+
+	it("groups by file with blank separator", () => {
+		const items = [
+			{ relativePath: "a.ts", lineNumber: 1, lineContent: "L1" },
+			{ relativePath: "a.ts", lineNumber: 5, lineContent: "L5" },
+			{ relativePath: "b.ts", lineNumber: 10, lineContent: "LB" },
+		];
+		expect(fffFormatGrepText(items, 100).split("\n")).toEqual(["a.ts:1:L1", "a.ts:5:L5", "", "b.ts:10:LB"]);
+	});
+
+	it("truncates >500 char lines", () => {
+		const items = [{ relativePath: "a.ts", lineNumber: 1, lineContent: "x".repeat(600) }];
+		expect(fffFormatGrepText(items, 100)).toBe(`a.ts:1:${"x".repeat(500)}...`);
+	});
+
+	it("respects limit", () => {
+		const items = [
+			{ relativePath: "a.ts", lineNumber: 1, lineContent: "one" },
+			{ relativePath: "a.ts", lineNumber: 2, lineContent: "two" },
+			{ relativePath: "a.ts", lineNumber: 3, lineContent: "three" },
+		];
+		expect(fffFormatGrepText(items, 2).split("\n")).toHaveLength(2);
+	});
+
+	it("contextBefore with dash format", () => {
+		const items = [{
+			relativePath: "a.ts", lineNumber: 5, lineContent: "match",
+			contextBefore: ["before1", "before2"],
+		}];
+		const lines = fffFormatGrepText(items, 100).split("\n");
+		expect(lines[0]).toBe("a.ts-3-before1");
+		expect(lines[1]).toBe("a.ts-4-before2");
+		expect(lines[2]).toBe("a.ts:5:match");
+	});
+
+	it("contextAfter with dash format", () => {
+		const items = [{
+			relativePath: "a.ts", lineNumber: 5, lineContent: "match",
+			contextAfter: ["after1"],
+		}];
+		const lines = fffFormatGrepText(items, 100).split("\n");
+		expect(lines[0]).toBe("a.ts:5:match");
+		expect(lines[1]).toBe("a.ts-6-after1");
+	});
+});
+
+// =========================================================================
+// 2. Integration tests — via PiPrettyDeps injection
+// =========================================================================
+
+// Mock SDK tool factories
+function mockToolFactory(exec: ReturnType<typeof vi.fn>) {
+	return (_cwd: string) => ({
+		name: "mock",
+		description: "mock",
+		parameters: { type: "object", properties: {} },
+		execute: exec,
+	});
+}
+
+// Mock FFF finder
+function mkFinder(overrides?: Record<string, any>) {
+	return {
+		isDestroyed: false,
+		waitForScan: vi.fn().mockResolvedValue({ ok: true, value: true }),
+		fileSearch: vi.fn().mockReturnValue({
+			ok: true,
+			value: {
+				items: [{ relativePath: "src/index.ts" }, { relativePath: "src/main.ts" }],
+				totalMatched: 2,
+			},
+		}),
+		grep: vi.fn().mockReturnValue({
+			ok: true,
+			value: {
+				items: [{ relativePath: "src/index.ts", lineNumber: 42, lineContent: "const x = 1;" }],
+				totalMatched: 1,
+				nextCursor: null,
+			},
+		}),
+		multiGrep: vi.fn().mockReturnValue({
+			ok: true,
+			value: {
+				items: [
+					{ relativePath: "src/index.ts", lineNumber: 10, lineContent: "import {foo}" },
+					{ relativePath: "src/main.ts", lineNumber: 5, lineContent: "const baz" },
+				],
+				totalMatched: 2,
+				nextCursor: null,
+			},
+		}),
+		destroy: vi.fn(),
+		...overrides,
+	};
+}
+
+describe("piPrettyExtension integration", () => {
+	let tools: Map<string, any>;
+	let events: Map<string, Function>;
+	let mockPi: any;
+
+	// SDK execute mocks
+	const findExec = vi.fn();
+	const grepExec = vi.fn();
+	const readExec = vi.fn();
+	const bashExec = vi.fn();
+	const lsExec = vi.fn();
+
+	function makeDeps(withFFF: boolean, finderOverrides?: Record<string, any>): PiPrettyDeps {
+		const finder = mkFinder(finderOverrides);
+		return {
+			sdk: {
+				createReadToolDefinition: mockToolFactory(readExec),
+				createBashToolDefinition: mockToolFactory(bashExec),
+				createLsToolDefinition: mockToolFactory(lsExec),
+				createFindToolDefinition: mockToolFactory(findExec),
+				createGrepToolDefinition: mockToolFactory(grepExec),
+				getAgentDir: () => "/tmp/pi-pretty-test",
+			},
+			TextComponent: class { private t = ""; setText(v: string) { this.t = v; } getText() { return this.t; } },
+			fffModule: withFFF
+				? { FileFinder: { create: vi.fn().mockReturnValue({ ok: true, value: finder }) } }
+				: undefined,
+		};
+	}
+
+	beforeEach(() => {
+		tools = new Map();
+		events = new Map();
+		mockPi = {
+			registerTool: vi.fn((t: any) => tools.set(t.name, t)),
+			registerCommand: vi.fn((c: any) => {}),
+			on: vi.fn((e: string, h: Function) => events.set(e, h)),
+		};
+
+		for (const fn of [findExec, grepExec, readExec, bashExec, lsExec]) fn.mockReset();
+		findExec.mockResolvedValue({ content: [{ type: "text", text: "src/index.ts\nsrc/main.ts" }] });
+		grepExec.mockResolvedValue({ content: [{ type: "text", text: "src/index.ts:10:const x = 1;" }] });
+		readExec.mockResolvedValue({ content: [{ type: "text", text: "content" }] });
+		bashExec.mockResolvedValue({ content: [{ type: "text", text: "output" }] });
+		lsExec.mockResolvedValue({ content: [{ type: "text", text: "f1\nf2" }] });
+	});
+
+	function load(withFFF = false, finderOverrides?: Record<string, any>) {
+		const deps = makeDeps(withFFF, finderOverrides);
+		piPrettyExtension(mockPi, deps);
+	}
+
+	async function loadWithFFF(finderOverrides?: Record<string, any>) {
+		load(true, finderOverrides);
+		const start = events.get("session_start")!;
+		expect(start, "session_start not registered").toBeDefined();
+		await start({}, { cwd: "/tmp/test" });
+	}
+
+	// ---- registration --------------------------------------------------
+
+	describe("tool registration", () => {
+		it("registers core tools (find, grep, read, bash, ls)", () => {
+			load();
+			for (const n of ["find", "grep", "read", "bash", "ls"]) {
+				expect(tools.has(n), `missing: ${n}`).toBe(true);
+			}
+		});
+
+		it("registers multi_grep when FFF available", () => {
+			load(true);
+			expect(tools.has("multi_grep")).toBe(true);
+		});
+
+		it("NO multi_grep when FFF unavailable", () => {
+			load(false);
+			expect(tools.has("multi_grep")).toBe(false);
+		});
+
+		it("registers session_start + session_shutdown", () => {
+			load();
+			expect(events.has("session_start")).toBe(true);
+			expect(events.has("session_shutdown")).toBe(true);
+		});
+	});
+
+	// ---- find: SDK fallback (no FFF) -----------------------------------
+
+	describe("find — SDK fallback", () => {
+		it("delegates to SDK when FFF not loaded", async () => {
+			load(false);
+			const r = await tools.get("find")!.execute("t1", { pattern: "*.ts" }, null, null, {});
+			expect(findExec).toHaveBeenCalledOnce();
+			expect(r.details._type).toBe("findResult");
+			expect(r.details.pattern).toBe("*.ts");
+		});
+
+		it("counts matches from SDK text", async () => {
+			findExec.mockResolvedValue({ content: [{ type: "text", text: "a.ts\nb.ts\nc.ts" }] });
+			load(false);
+			const r = await tools.get("find")!.execute("t1", { pattern: "*.ts" }, null, null, {});
+			expect(r.details.matchCount).toBe(3);
+		});
+	});
+
+	// ---- grep: SDK fallback (no FFF) -----------------------------------
+
+	describe("grep — SDK fallback", () => {
+		it("delegates to SDK when FFF not loaded", async () => {
+			load(false);
+			const r = await tools.get("grep")!.execute("t1", { pattern: "TODO" }, null, null, {});
+			expect(grepExec).toHaveBeenCalledOnce();
+			expect(r.details._type).toBe("grepResult");
+		});
+
+		it("counts ripgrep-style matches", async () => {
+			grepExec.mockResolvedValue({
+				content: [{ type: "text", text: "a.ts:1:TODO\na.ts:5:TODO\nb.ts:10:TODO" }],
+			});
+			load(false);
+			const r = await tools.get("grep")!.execute("t1", { pattern: "TODO" }, null, null, {});
+			expect(r.details.matchCount).toBe(3);
+		});
+	});
+
+	// ---- find: FFF path ------------------------------------------------
+
+	describe("find — FFF path", () => {
+		it("uses FFF fileSearch when initialized", async () => {
+			await loadWithFFF();
+			const r = await tools.get("find")!.execute("t1", { pattern: "*.ts" }, null, null, {});
+			expect(findExec).not.toHaveBeenCalled();
+			expect(r.details._type).toBe("findResult");
+			expect(r.content[0].text).toContain("src/index.ts");
+		});
+
+		it("falls back to SDK on FFF { ok: false }", async () => {
+			await loadWithFFF({
+				fileSearch: vi.fn().mockReturnValue({ ok: false, error: "fail" }),
+			});
+			await tools.get("find")!.execute("t1", { pattern: "*.ts" }, null, null, {});
+			expect(findExec).toHaveBeenCalledOnce();
+		});
+
+		it("falls back to SDK on FFF throw", async () => {
+			await loadWithFFF({
+				fileSearch: vi.fn().mockImplementation(() => { throw new Error("crash"); }),
+			});
+			await tools.get("find")!.execute("t1", { pattern: "*.ts" }, null, null, {});
+			expect(findExec).toHaveBeenCalledOnce();
+		});
+
+		it("respects limit param", async () => {
+			const fileSearch = vi.fn().mockReturnValue({
+				ok: true,
+				value: { items: Array.from({ length: 50 }, (_, i) => ({ relativePath: `f${i}.ts` })), totalMatched: 50 },
+			});
+			await loadWithFFF({ fileSearch });
+			await tools.get("find")!.execute("t1", { pattern: "*.ts", limit: 5 }, null, null, {});
+			expect(fileSearch).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ pageSize: 5 }));
+		});
+
+		it("includes path in search query", async () => {
+			const fileSearch = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0 } });
+			await loadWithFFF({ fileSearch });
+			await tools.get("find")!.execute("t1", { pattern: "*.ts", path: "src/" }, null, null, {});
+			expect(fileSearch).toHaveBeenCalledWith("src/ *.ts", expect.any(Object));
+		});
+
+		it("shows partial-index + limit notices", async () => {
+			await loadWithFFF({
+				waitForScan: vi.fn().mockResolvedValue({ ok: true, value: false }),
+				fileSearch: vi.fn().mockReturnValue({
+					ok: true,
+					value: { items: Array.from({ length: 200 }, (_, i) => ({ relativePath: `f${i}` })), totalMatched: 500 },
+				}),
+			});
+			const text = (await tools.get("find")!.execute("t1", { pattern: "*" }, null, null, {})).content[0].text;
+			expect(text).toContain("partial file index");
+			expect(text).toContain("200 limit reached");
+			expect(text).toContain("500 total matches");
+		});
+	});
+
+	// ---- grep: FFF path ------------------------------------------------
+
+	describe("grep — FFF path", () => {
+		it("uses FFF grep when initialized", async () => {
+			await loadWithFFF();
+			const r = await tools.get("grep")!.execute("t1", { pattern: "TODO" }, null, null, {});
+			expect(grepExec).not.toHaveBeenCalled();
+			expect(r.content[0].text).toContain("src/index.ts:42:const x = 1;");
+		});
+
+		it("literal=true → mode=plain", async () => {
+			const grep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
+			await loadWithFFF({ grep });
+			await tools.get("grep")!.execute("t1", { pattern: "foo", literal: true }, null, null, {});
+			expect(grep).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ mode: "plain" }));
+		});
+
+		it("no literal → mode=regex", async () => {
+			const grep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
+			await loadWithFFF({ grep });
+			await tools.get("grep")!.execute("t1", { pattern: "foo.*bar" }, null, null, {});
+			expect(grep).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ mode: "regex" }));
+		});
+
+		it("glob prepended to query", async () => {
+			const grep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
+			await loadWithFFF({ grep });
+			await tools.get("grep")!.execute("t1", { pattern: "TODO", glob: "*.ts" }, null, null, {});
+			expect(grep).toHaveBeenCalledWith("*.ts TODO", expect.any(Object));
+		});
+
+		it("falls back to SDK on throw", async () => {
+			await loadWithFFF({ grep: vi.fn().mockImplementation(() => { throw new Error("crash"); }) });
+			const r = await tools.get("grep")!.execute("t1", { pattern: "TODO" }, null, null, {});
+			expect(grepExec).toHaveBeenCalledOnce();
+			expect(r.details._type).toBe("grepResult");
+		});
+
+		it("cursor notice when nextCursor present", async () => {
+			await loadWithFFF({
+				grep: vi.fn().mockReturnValue({
+					ok: true,
+					value: { items: [{ relativePath: "a.ts", lineNumber: 1, lineContent: "hit" }], totalMatched: 1, nextCursor: { p: 2 } },
+				}),
+			});
+			const text = (await tools.get("grep")!.execute("t1", { pattern: "hit" }, null, null, {})).content[0].text;
+			expect(text).toContain("More results available");
+			expect(text).toMatch(/cursor="fff_c\d+"/);
+		});
+	});
+
+	// ---- multi_grep (FFF only) -----------------------------------------
+
+	describe("multi_grep", () => {
+		it("error for empty patterns", async () => {
+			await loadWithFFF();
+			const r = await tools.get("multi_grep")!.execute("t1", { patterns: [] }, null, null, null);
+			expect(r.content[0].text).toContain("patterns array must have at least 1 element");
+		});
+
+		it("error when FFF not initialized (no session_start)", async () => {
+			load(true);
+			const r = await tools.get("multi_grep")!.execute("t1", { patterns: ["foo"] }, null, null, null);
+			expect(r.content[0].text).toContain("FFF not initialized");
+		});
+
+		it("returns multiGrep results", async () => {
+			await loadWithFFF();
+			const r = await tools.get("multi_grep")!.execute("t1", { patterns: ["foo", "bar"] }, null, null, null);
+			expect(r.details._type).toBe("grepResult");
+			expect(r.content[0].text).toContain("src/index.ts");
+		});
+
+		it("aborted signal → Aborted", async () => {
+			await loadWithFFF();
+			const r = await tools.get("multi_grep")!.execute("t1", { patterns: ["x"] }, { aborted: true }, null, null);
+			expect(r.content[0].text).toBe("Aborted");
+		});
+
+		it("multiGrep failure → error text", async () => {
+			await loadWithFFF({
+				multiGrep: vi.fn().mockReturnValue({ ok: false, error: "compile failed" }),
+			});
+			const r = await tools.get("multi_grep")!.execute("t1", { patterns: ["[bad"] }, null, null, null);
+			expect(r.content[0].text).toContain("compile failed");
+		});
+
+		it("passes constraints and context", async () => {
+			const multiGrep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
+			await loadWithFFF({ multiGrep });
+			await tools.get("multi_grep")!.execute("t1", { patterns: ["a", "b"], constraints: "*.ts", context: 2 }, null, null, null);
+			expect(multiGrep).toHaveBeenCalledWith(expect.objectContaining({
+				patterns: ["a", "b"], constraints: "*.ts", beforeContext: 2, afterContext: 2,
+			}));
+		});
+	});
+
+	// ---- session lifecycle ---------------------------------------------
+
+	describe("session lifecycle", () => {
+		it("shutdown → subsequent find falls back to SDK", async () => {
+			await loadWithFFF();
+			await events.get("session_shutdown")!();
+			await tools.get("find")!.execute("t1", { pattern: "*.ts" }, null, null, {});
+			expect(findExec).toHaveBeenCalledOnce();
+		});
+	});
+});