@heyhuynhgiabuu/pi-pretty 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@heyhuynhgiabuu/pi-pretty",
-	"version": "0.3.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",

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

@@ -29,6 +29,8 @@ 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
 // ---------------------------------------------------------------------------
@@ -676,25 +678,6 @@ async function renderGrepResults(text: string, pattern: string): Promise<string>
 // If not, falls back to wrapping SDK tools (current behavior).
 // ---------------------------------------------------------------------------
 
-class CursorStore {
-	private cursors = new Map<string, any>();
-	private counter = 0;
-
-	store(cursor: any): string {
-		const id = `fff_c${++this.counter}`;
-		this.cursors.set(id, cursor);
-		if (this.cursors.size > 200) {
-			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);
-	}
-}
-
 const _cursorStore = new CursorStore();
 let _fffModule: any = null;
 let _fffFinder: any = null;
@@ -730,47 +713,21 @@ function fffDestroy(): void {
 	_fffPartialIndex = false;
 }
 
-/**
- * Convert FFF GrepResult items to ripgrep-style "file:line:content" text.
- * This ensures pi-pretty's renderGrepResults works unchanged.
- */
-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");
-}
-
 // ---------------------------------------------------------------------------
 // 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;
@@ -780,16 +737,31 @@ export default function piPrettyExtension(pi: any): void {
 
 	let sdk: any;
 
-	try {
-		sdk = require("@mariozechner/pi-coding-agent");
+	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;
 
@@ -802,16 +774,24 @@ export default function piPrettyExtension(pi: any): void {
 	// ===================================================================
 
 	const getAgentDir = (sdk as any).getAgentDir;
-	try {
-		_fffModule = require("@ff-labs/fff-node");
-		if (getAgentDir) {
-			_fffDbDir = join(getAgentDir(), "fff");
-			try {
-				mkdirSync(_fffDbDir, { recursive: true });
-			} catch {}
+	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 */
 		}
-	} 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) => {

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();
+		});
+	});
+});