@nklisch/pi-fff-compat 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# @nklisch/pi-fff-compat
+
+Exposes the fast [FFF](https://github.com/ff-labs/fff) file index through
+Pi-native `find`/`grep` semantics. Upstream `@ff-labs/pi-fff` is excellent for
+fuzzy/smart discovery, but its `ffind`/`ffgrep` behavior intentionally differs
+from Pi's built-ins; this package provides the conservative compatibility
+surface: **glob-only file lookup and exact regex/literal grep, no fuzzy
+fallback** — backed by the same real-time FFF index.
+
+```sh
+pi install npm:@nklisch/pi-fff-compat
+```
+
+## Modes
+
+| Mode | Tools | How |
+| --- | --- | --- |
+| Default (additive) | `fast_find`, `fast_grep` alongside the built-ins | install and go |
+| Override | registers as `find`/`grep` themselves | `PI_FFF_COMPAT_OVERRIDE=1` |
+| Disabled | nothing | `PI_FFF_COMPAT_DISABLE=1` |
+
+## Commands
+
+- `/fff-compat` — index health, indexed file count, watcher/scan status.
+- `/fff-compat-rescan` — trigger a manual rescan.
+
+## Watcher & inotify budget
+
+FFF maintains a real-time native watcher with one watch per indexed file.
+Scanning very large trees (e.g. a home directory) can exhaust
+`fs.inotify.max_user_watches` and leave the index silently stale on unwatched
+files. Two independent knobs:
+
+- `PI_FFF_COMPAT_HOME_SCAN=1` — opt into home-dir scanning (default off; raise
+  `fs.inotify.max_user_watches` when enabling).
+- `PI_FFF_COMPAT_DISABLE_WATCH=1` — scan once, no live watcher (index goes
+  stale until rescan).
+
+The index itself, frecency, and git-aware filtering come from
+[`@ff-labs/fff-node`](https://www.npmjs.com/package/@ff-labs/fff-node), loaded
+as a normal dependency.

package/extensions/fff-compat-search.test.ts

@@ -0,0 +1,76 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import fffCompatSearch from "./fff-compat-search";
+
+type ToolDef = { name: string; description?: string };
+type CommandDef = { description?: string };
+
+function load() {
+  const tools: string[] = [];
+  const commands: string[] = [];
+  const pi = {
+    registerTool: (tool: ToolDef) => {
+      tools.push(tool.name);
+    },
+    registerCommand: (name: string, _options: CommandDef) => {
+      commands.push(name);
+    },
+    on: () => {},
+  };
+  fffCompatSearch(pi as never);
+  return { tools, commands };
+}
+
+const ENV_VARS = ["PI_FFF_COMPAT_OVERRIDE", "PI_FFF_COMPAT_DISABLE"] as const;
+const saved = new Map<string, string | undefined>();
+
+afterEach(() => {
+  for (const name of ENV_VARS) {
+    if (saved.has(name)) {
+      const value = saved.get(name);
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  }
+  saved.clear();
+});
+
+function setEnv(name: (typeof ENV_VARS)[number], value: string | undefined) {
+  if (!saved.has(name)) saved.set(name, process.env[name]);
+  if (value === undefined) delete process.env[name];
+  else process.env[name] = value;
+}
+
+describe("pi-fff-compat registration", () => {
+  test("default mode registers additive fast_find/fast_grep tools", () => {
+    setEnv("PI_FFF_COMPAT_OVERRIDE", undefined);
+    setEnv("PI_FFF_COMPAT_DISABLE", undefined);
+    const { tools } = load();
+    expect(tools).toContain("fast_find");
+    expect(tools).toContain("fast_grep");
+    expect(tools).not.toContain("find");
+    expect(tools).not.toContain("grep");
+  });
+
+  test("override mode registers as find/grep", () => {
+    setEnv("PI_FFF_COMPAT_OVERRIDE", "1");
+    const { tools } = load();
+    expect(tools).toContain("find");
+    expect(tools).toContain("grep");
+    expect(tools).not.toContain("fast_find");
+  });
+
+  test("disable env registers nothing", () => {
+    setEnv("PI_FFF_COMPAT_DISABLE", "1");
+    const { tools, commands } = load();
+    expect(tools).toHaveLength(0);
+    expect(commands).toHaveLength(0);
+  });
+
+  test("status and rescan commands are always registered", () => {
+    setEnv("PI_FFF_COMPAT_OVERRIDE", undefined);
+    setEnv("PI_FFF_COMPAT_DISABLE", undefined);
+    const { commands } = load();
+    expect(commands).toContain("fff-compat");
+    expect(commands).toContain("fff-compat-rescan");
+  });
+});

package/extensions/fff-compat-search.ts

@@ -0,0 +1,641 @@
+/**
+ * FFF compatibility search for Pi.
+ *
+ * Upstream @ff-labs/pi-fff is excellent for fuzzy/smart discovery, but its
+ * fffind/ffgrep semantics intentionally differ from Pi's built-in find/grep.
+ * This extension exposes the same fast FFF index through a conservative surface:
+ * glob-only file lookup and exact regex/literal grep with no fuzzy fallback.
+ *
+ * Default mode registers fast_find/fast_grep alongside the built-ins. Set
+ * PI_FFF_COMPAT_OVERRIDE=1 before Pi starts to register these exact
+ * compatibility tools as find/grep instead.
+ *
+ * Watcher & inotify budget:
+ *   FFF maintains a real-time native inotify watcher with one watch per
+ *   indexed file. Scanning the home directory (millions of files, mostly
+ *   caches) blows past fs.inotify.max_user_watches and leaves the index
+ *   silently stale on files it couldn't watch. Two independent knobs:
+ *     PI_FFF_COMPAT_HOME_SCAN=1   — opt into home-dir scanning (default off).
+ *     PI_FFF_COMPAT_DISABLE_WATCH=1 — scan once, no live watcher at all
+ *                                     (index goes stale until rescan).
+ *   Also raise fs.inotify.max_user_watches (see /etc/sysctl.d) when enabling
+ *   home scanning or working in very large trees.
+ */
+
+import { statSync } from "node:fs";
+import path from "node:path";
+import { Type } from "@earendil-works/pi-ai";
+import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const EXTENSION_NAME = "pi-fff-compat";
+const PACKAGE_HINT = "bundled dependency of @nklisch/pi-fff-compat";
+const OVERRIDE_ENV = "PI_FFF_COMPAT_OVERRIDE";
+const DISABLE_ENV = "PI_FFF_COMPAT_DISABLE";
+// Home-dir scanning watches every file under ~ (caches, runtimes, browser
+// profiles, etc.), which on this machine is ~1.2M files — far beyond the
+// kernel inotify budget and almost entirely churn-prone noise. Off by
+// default; set PI_FFF_COMPAT_HOME_SCAN=1 to opt in (also raise
+// fs.inotify.max_user_watches).
+const HOME_SCAN_ENV = "PI_FFF_COMPAT_HOME_SCAN";
+// FFF's native watcher already debounces and batches events, but maintaining
+// one inotify watch per indexed file is what exhausts the kernel budget. Set
+// PI_FFF_COMPAT_DISABLE_WATCH=1 for a one-shot scan with no live tracking —
+// the index then goes stale on changes until a manual /fff-compat-rescan.
+const DISABLE_WATCH_ENV = "PI_FFF_COMPAT_DISABLE_WATCH";
+const DEFAULT_FIND_LIMIT = 1000;
+const DEFAULT_GREP_LIMIT = 100;
+const MAX_OUTPUT_BYTES = 50 * 1024;
+const MAX_OUTPUT_LINES = 2000;
+const GREP_MAX_LINE_LENGTH = 500;
+const INITIAL_SCAN_WAIT_MS = 15_000;
+
+type Result<T> = { ok: true; value: T } | { ok: false; error: string };
+
+type FffFileItem = {
+  relativePath: string;
+  fileName: string;
+};
+
+type FffSearchResult = {
+  items: FffFileItem[];
+  totalMatched: number;
+  totalFiles: number;
+};
+
+type FffGrepCursor = unknown;
+
+type FffGrepMatch = {
+  relativePath: string;
+  fileName: string;
+  lineNumber: number;
+  col: number;
+  lineContent: string;
+  contextBefore?: string[];
+  contextAfter?: string[];
+};
+
+type FffGrepResult = {
+  items: FffGrepMatch[];
+  totalMatched: number;
+  totalFiles: number;
+  totalFilesSearched: number;
+  filteredFileCount: number;
+  nextCursor: FffGrepCursor | null;
+  regexFallbackError?: string;
+};
+
+type FffScanProgress = {
+  scannedFilesCount: number;
+  isScanning: boolean;
+  isWatcherReady: boolean;
+  isWarmupComplete: boolean;
+};
+
+type FffHealth = {
+  version: string;
+  git: { repositoryFound: boolean; workdir?: string };
+  filePicker: { initialized: boolean; indexedFiles?: number; basePath?: string };
+};
+
+type FffFinder = {
+  readonly isDestroyed: boolean;
+  destroy(): void;
+  glob(pattern: string, options?: { pageIndex?: number; pageSize?: number; maxThreads?: number }): Result<FffSearchResult>;
+  grep(
+    query: string,
+    options?: {
+      mode?: "plain" | "regex" | "fuzzy";
+      smartCase?: boolean;
+      pageSize?: number;
+      maxMatchesPerFile?: number;
+      beforeContext?: number;
+      afterContext?: number;
+      cursor?: FffGrepCursor | null;
+    },
+  ): Result<FffGrepResult>;
+  waitForScan(timeoutMs?: number): Promise<Result<boolean>>;
+  scanFiles(): Result<void>;
+  getScanProgress(): Result<FffScanProgress>;
+  healthCheck(testPath?: string): Result<FffHealth>;
+};
+
+type FffModule = {
+  FileFinder: {
+    create(options: Record<string, unknown>): Result<FffFinder>;
+  };
+};
+
+type FindInput = {
+  pattern: string;
+  path?: string;
+  limit?: number;
+};
+
+type GrepInput = {
+  pattern: string;
+  path?: string;
+  glob?: string;
+  ignoreCase?: boolean;
+  literal?: boolean;
+  context?: number;
+  limit?: number;
+};
+
+type ToolNames = {
+  find: string;
+  grep: string;
+};
+
+type Truncation = {
+  content: string;
+  truncated: boolean;
+  omittedLines: number;
+  omittedBytes: number;
+};
+
+let fffModulePromise: Promise<FffModule> | null = null;
+let finder: FffFinder | null = null;
+let finderCwd: string | null = null;
+let finderPromise: { cwd: string; promise: Promise<FffFinder> } | null = null;
+let activeCwd = process.cwd();
+
+function envFlagEnabled(value: string | undefined): boolean {
+  const normalized = value?.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+
+function toPosixPath(value: string): string {
+  return value.replace(/\\/g, "/");
+}
+
+function stripTrailingSlash(value: string): string {
+  return value.replace(/\/+$/, "");
+}
+
+function isInsideOrEqual(parent: string, child: string): boolean {
+  const relative = path.relative(parent, child);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function resolveWorkspacePath(cwd: string, input: string | undefined, fallback = "."): string {
+  const raw = input?.trim() || fallback;
+  const absolute = path.resolve(cwd, raw);
+  if (!isInsideOrEqual(cwd, absolute)) {
+    throw new Error(`Path must stay inside the workspace: ${input}`);
+  }
+  return absolute;
+}
+
+function relativeToWorkspace(cwd: string, absolute: string): string {
+  const relative = toPosixPath(path.relative(cwd, absolute));
+  return relative === "" ? "." : relative;
+}
+
+function loadFffModule(): Promise<FffModule> {
+  if (!fffModulePromise) {
+    fffModulePromise = (async () => {
+      try {
+        return (await import("@ff-labs/fff-node")) as FffModule;
+      } catch (error) {
+        throw new Error(
+          `Failed to load @ff-labs/fff-node (${PACKAGE_HINT}): ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    })();
+  }
+  return fffModulePromise;
+}
+
+async function ensureFinder(cwd: string): Promise<FffFinder> {
+  if (finder && !finder.isDestroyed && finderCwd === cwd) return finder;
+  if (finderPromise && finderPromise.cwd === cwd) return finderPromise.promise;
+
+  finderPromise = {
+    cwd,
+    promise: (async () => {
+      destroyFinder();
+      const { FileFinder } = await loadFffModule();
+      const created = FileFinder.create({
+        basePath: cwd,
+        frecencyDbPath: process.env.FFF_FRECENCY_DB,
+        historyDbPath: process.env.FFF_HISTORY_DB,
+        aiMode: true,
+        enableHomeDirScanning: envFlagEnabled(process.env[HOME_SCAN_ENV]),
+        enableFsRootScanning: envFlagEnabled(process.env.FFF_ENABLE_ROOT_SCAN),
+        disableWatch: envFlagEnabled(process.env[DISABLE_WATCH_ENV]),
+      });
+      if (!created.ok) throw new Error(`Failed to create FFF finder: ${created.error}`);
+
+      finder = created.value;
+      finderCwd = cwd;
+
+      const scan = await finder.waitForScan(INITIAL_SCAN_WAIT_MS);
+      if (!scan.ok) throw new Error(`FFF scan failed: ${scan.error}`);
+      return finder;
+    })().finally(() => {
+      finderPromise = null;
+    }),
+  };
+
+  return finderPromise.promise;
+}
+
+function destroyFinder(): void {
+  if (finder && !finder.isDestroyed) finder.destroy();
+  finder = null;
+  finderCwd = null;
+}
+
+function truncateLine(line: string): { text: string; wasTruncated: boolean } {
+  const sanitized = line.replace(/\r/g, "").replace(/\n$/, "");
+  if (sanitized.length <= GREP_MAX_LINE_LENGTH) return { text: sanitized, wasTruncated: false };
+  return { text: `${sanitized.slice(0, GREP_MAX_LINE_LENGTH)}...`, wasTruncated: true };
+}
+
+function truncateOutput(text: string): Truncation {
+  const lines = text.split("\n");
+  const lineLimited = lines.length > MAX_OUTPUT_LINES;
+  const byLines = lineLimited ? lines.slice(0, MAX_OUTPUT_LINES).join("\n") : text;
+
+  const buffer = Buffer.from(byLines, "utf8");
+  const byteLimited = buffer.length > MAX_OUTPUT_BYTES;
+  const content = byteLimited ? buffer.subarray(0, MAX_OUTPUT_BYTES).toString("utf8").replace(/\uFFFD$/, "") : byLines;
+
+  return {
+    content,
+    truncated: lineLimited || byteLimited,
+    omittedLines: lineLimited ? lines.length - MAX_OUTPUT_LINES : 0,
+    omittedBytes: byteLimited ? buffer.length - MAX_OUTPUT_BYTES : 0,
+  };
+}
+
+function appendNotices(output: string, notices: string[]): string {
+  return notices.length > 0 ? `${output}\n\n[${notices.join(". ")}]` : output;
+}
+
+function normalizePositiveLimit(value: number | undefined, fallback: number): number {
+  return Number.isFinite(value) && value !== undefined ? Math.max(1, Math.floor(value)) : fallback;
+}
+
+function fdStyleGlob(pattern: string): string {
+  const trimmed = toPosixPath(pattern.trim());
+  if (!trimmed) return "**/*";
+  if (trimmed === "**" || trimmed.startsWith("**/") || trimmed.startsWith("/")) return trimmed;
+  // Pi's built-in find uses fd --glob. Bare patterns match basenames anywhere
+  // under the search root, and path-containing relative patterns are matched
+  // against the full path from any depth. `**/` gives FFF glob the same shape.
+  return `**/${trimmed}`;
+}
+
+function joinGlobWithSearchRoot(searchRootRel: string, pattern: string): string {
+  const normalizedPattern = pattern.startsWith("/") ? pattern.slice(1) : pattern;
+  if (searchRootRel === ".") return normalizedPattern;
+  return `${stripTrailingSlash(searchRootRel)}/${normalizedPattern}`;
+}
+
+function outputPathRelativeToSearchRoot(cwd: string, searchRootAbs: string, fffRelativePath: string): string {
+  const searchRootRel = relativeToWorkspace(cwd, searchRootAbs);
+  if (searchRootRel === ".") return fffRelativePath;
+
+  const prefix = `${stripTrailingSlash(searchRootRel)}/`;
+  if (fffRelativePath.startsWith(prefix)) return fffRelativePath.slice(prefix.length);
+  if (fffRelativePath === stripTrailingSlash(searchRootRel)) return path.basename(fffRelativePath);
+  return toPosixPath(path.relative(searchRootAbs, path.join(cwd, fffRelativePath)));
+}
+
+function grepPathConstraint(cwd: string, absolutePath: string): { constraint: string | null; isDirectory: boolean } {
+  let stat;
+  try {
+    stat = statSync(absolutePath);
+  } catch {
+    throw new Error(`Path not found: ${absolutePath}`);
+  }
+
+  const relative = relativeToWorkspace(cwd, absolutePath);
+  const isDirectory = stat.isDirectory();
+  if (relative === ".") return { constraint: null, isDirectory };
+  return { constraint: isDirectory ? `${stripTrailingSlash(relative)}/` : relative, isDirectory };
+}
+
+function buildGrepQuery(cwd: string, input: GrepInput, searchPathAbs: string, searchPattern: string): string {
+  const parts: string[] = [];
+  const pathConstraint = grepPathConstraint(cwd, searchPathAbs).constraint;
+  if (pathConstraint) parts.push(pathConstraint);
+  if (input.glob?.trim()) parts.push(input.glob.trim());
+  parts.push(searchPattern);
+  return parts.join(" ");
+}
+
+function escapeRegexLiteral(value: string): string {
+  return value.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+}
+
+function grepModeAndPattern(input: GrepInput): { mode: "plain" | "regex"; pattern: string } {
+  if (!input.ignoreCase) {
+    return input.literal === true ? { mode: "plain", pattern: input.pattern } : { mode: "regex", pattern: input.pattern };
+  }
+
+  const inner = input.literal === true ? escapeRegexLiteral(input.pattern) : input.pattern;
+  return { mode: "regex", pattern: `(?i:${inner})` };
+}
+
+function formatGrepPath(cwd: string, searchPathAbs: string, searchPathIsDirectory: boolean, fffRelativePath: string): string {
+  if (!searchPathIsDirectory) return path.basename(searchPathAbs);
+  return outputPathRelativeToSearchRoot(cwd, searchPathAbs, fffRelativePath);
+}
+
+function formatGrepMatches(cwd: string, searchPathAbs: string, searchPathIsDirectory: boolean, matches: FffGrepMatch[], contextLines: number): { output: string; linesTruncated: boolean } {
+  let linesTruncated = false;
+  const outputLines: string[] = [];
+  const sorted = [...matches].sort((a, b) => {
+    const byPath = a.relativePath.localeCompare(b.relativePath);
+    if (byPath !== 0) return byPath;
+    const byLine = a.lineNumber - b.lineNumber;
+    if (byLine !== 0) return byLine;
+    return a.col - b.col;
+  });
+
+  for (const match of sorted) {
+    const displayPath = formatGrepPath(cwd, searchPathAbs, searchPathIsDirectory, match.relativePath);
+    if (contextLines > 0) {
+      const before = match.contextBefore ?? [];
+      before.forEach((line, index) => {
+        const lineNumber = match.lineNumber - before.length + index;
+        const truncated = truncateLine(line);
+        if (truncated.wasTruncated) linesTruncated = true;
+        outputLines.push(`${displayPath}-${lineNumber}- ${truncated.text}`);
+      });
+    }
+
+    const matchLine = truncateLine(match.lineContent);
+    if (matchLine.wasTruncated) linesTruncated = true;
+    outputLines.push(`${displayPath}:${match.lineNumber}: ${matchLine.text}`);
+
+    if (contextLines > 0) {
+      const after = match.contextAfter ?? [];
+      after.forEach((line, index) => {
+        const lineNumber = match.lineNumber + index + 1;
+        const truncated = truncateLine(line);
+        if (truncated.wasTruncated) linesTruncated = true;
+        outputLines.push(`${displayPath}-${lineNumber}- ${truncated.text}`);
+      });
+    }
+  }
+
+  return { output: outputLines.join("\n"), linesTruncated };
+}
+
+function toolNames(): ToolNames {
+  return envFlagEnabled(process.env[OVERRIDE_ENV]) ? { find: "find", grep: "grep" } : { find: "fast_find", grep: "fast_grep" };
+}
+
+function usageHint(names: ToolNames, overriding: boolean): string {
+  const toolLabel = overriding ? "the built-in-looking find/grep tools" : `${names.find}/${names.grep}`;
+  return [
+    "FFF search tools are available in this session; choose the exact or fuzzy surface intentionally.",
+    `Use ${toolLabel} for fast, deterministic search when you want normal Pi find/grep semantics backed by the FFF index.`,
+    `Use ${names.find} for glob-only file searches. It returns paths relative to the requested search directory and is the fast replacement for ordinary find-style glob lookup.`,
+    `Use ${names.grep} for exact content search. It is regex by default, literal only when literal=true, honors ignoreCase, and intentionally has no fuzzy fallback.`,
+    "Use fffind for fuzzy/conceptual file discovery: vague file names, feature names, path fragments, typo-tolerant lookup, and git/frecency-ranked exploration. Do not treat it as an exhaustive deterministic glob result.",
+    "Use ffgrep for fuzzy/smart content discovery: broad identifiers, likely related terms, fast exploratory lookup, and frecency-ranked matches. It may fuzzy-fallback when exact matches fail, so prefer the compatibility grep for exact verification.",
+    `Prefer workspace-relative paths with ${names.find}/${names.grep}; the compatibility layer rejects paths outside the workspace because the FFF index is workspace-scoped.`,
+  ].join("\n");
+}
+
+const findSchema = Type.Object({
+  pattern: Type.String({ description: "Glob pattern to match files, e.g. '*.ts', '**/*.json', or 'src/**/*.spec.ts'" }),
+  path: Type.Optional(Type.String({ description: "Directory to search in (default: current directory)" })),
+  limit: Type.Optional(Type.Number({ description: `Maximum number of results (default ${DEFAULT_FIND_LIMIT})` })),
+});
+
+const grepSchema = Type.Object({
+  pattern: Type.String({ description: "Search pattern" }),
+  path: Type.Optional(Type.String({ description: "Directory or file to search in (default: current directory)" })),
+  glob: Type.Optional(Type.String({ description: "Include/exclude glob for files, passed with ripgrep-style semantics" })),
+  ignoreCase: Type.Optional(Type.Boolean({ description: "Case-insensitive search" })),
+  literal: Type.Optional(Type.Boolean({ description: "Treat pattern as a literal string instead of regex" })),
+  context: Type.Optional(Type.Number({ description: "Context lines before and after each match" })),
+  limit: Type.Optional(Type.Number({ description: `Maximum number of matching lines (default ${DEFAULT_GREP_LIMIT})` })),
+});
+
+export default function fffCompatSearch(pi: ExtensionAPI) {
+  if (envFlagEnabled(process.env[DISABLE_ENV])) return;
+
+  const names = toolNames();
+  const overriding = names.find === "find" || names.grep === "grep";
+  const injectedUsageHint = usageHint(names, overriding);
+
+  pi.on("before_agent_start", async (event) => {
+    return {
+      systemPrompt: `${event.systemPrompt}\n\n${injectedUsageHint}`,
+    };
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    activeCwd = ctx.cwd;
+    if (overriding) {
+      ctx.ui.notify(`${EXTENSION_NAME}: overriding built-in find/grep with deterministic FFF-backed tools`, "warning");
+    }
+    if (envFlagEnabled(process.env[HOME_SCAN_ENV])) {
+      ctx.ui.notify(
+        `${EXTENSION_NAME}: home-dir scanning is ON (PI_FFF_COMPAT_HOME_SCAN=1). Ensure fs.inotify.max_user_watches is large enough or the index will silently go stale.`,
+        "warning",
+      );
+    }
+    if (envFlagEnabled(process.env[DISABLE_WATCH_ENV])) {
+      ctx.ui.notify(`${EXTENSION_NAME}: live watcher disabled (PI_FFF_COMPAT_DISABLE_WATCH=1); index goes stale until /fff-compat-rescan`, "info");
+    }
+
+    try {
+      await ensureFinder(activeCwd);
+    } catch (error) {
+      ctx.ui.notify(`${EXTENSION_NAME} init failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+    }
+  });
+
+  pi.on("session_shutdown", async () => {
+    destroyFinder();
+  });
+
+  pi.registerTool({
+    name: names.find,
+    label: names.find,
+    description: `Search for files by glob pattern using the FFF index while preserving Pi find semantics. Returns paths relative to the search directory. Respects the indexed/gitignored file set. Output is truncated to ${DEFAULT_FIND_LIMIT} results or ${MAX_OUTPUT_BYTES / 1024}KB.`,
+    promptSnippet: "Fast deterministic glob file search backed by FFF",
+    promptGuidelines: [
+      `Use ${names.find} when you need deterministic glob-style file search with FFF speed; use fffind for fuzzy/conceptual file discovery.`,
+    ],
+    parameters: findSchema,
+    async execute(_toolCallId, params: FindInput, signal, _onUpdate, ctx: ExtensionContext) {
+      if (signal?.aborted) throw new Error("Operation aborted");
+      const cwd = ctx.cwd || activeCwd;
+      const f = await ensureFinder(cwd);
+      const searchRootAbs = resolveWorkspacePath(cwd, params.path, ".");
+      let stat;
+      try {
+        stat = statSync(searchRootAbs);
+      } catch {
+        throw new Error(`Path not found: ${searchRootAbs}`);
+      }
+      if (!stat.isDirectory()) throw new Error(`Path is not a directory: ${searchRootAbs}`);
+
+      const effectiveLimit = normalizePositiveLimit(params.limit, DEFAULT_FIND_LIMIT);
+      const searchRootRel = relativeToWorkspace(cwd, searchRootAbs);
+      const fffGlob = joinGlobWithSearchRoot(searchRootRel, fdStyleGlob(params.pattern));
+      const result = f.glob(fffGlob, { pageIndex: 0, pageSize: effectiveLimit });
+      if (!result.ok) throw new Error(result.error);
+      if (signal?.aborted) throw new Error("Operation aborted");
+
+      if (result.value.items.length === 0) {
+        return { content: [{ type: "text", text: "No files found matching pattern" }], details: undefined };
+      }
+
+      const outputPaths = result.value.items
+        .map((item) => outputPathRelativeToSearchRoot(cwd, searchRootAbs, item.relativePath))
+        .sort((a, b) => a.localeCompare(b));
+      const truncated = truncateOutput(outputPaths.join("\n"));
+      const notices: string[] = [];
+      const details: Record<string, unknown> = {
+        backend: "fff.glob",
+        totalMatched: result.value.totalMatched,
+        totalFiles: result.value.totalFiles,
+        glob: fffGlob,
+      };
+
+      if (result.value.totalMatched > result.value.items.length) {
+        notices.push(`${effectiveLimit} results limit reached`);
+        details.resultLimitReached = effectiveLimit;
+      }
+      if (truncated.truncated) {
+        notices.push(`${MAX_OUTPUT_BYTES / 1024}KB output limit reached`);
+        details.truncation = truncated;
+      }
+
+      return {
+        content: [{ type: "text", text: appendNotices(truncated.content, notices) }],
+        details,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: names.grep,
+    label: names.grep,
+    description: `Search file contents using the FFF index while preserving Pi grep semantics: regex by default, literal only when literal=true, ignoreCase honored, no fuzzy fallback. Returns matching lines with file paths and line numbers. Output is truncated to ${DEFAULT_GREP_LIMIT} matches or ${MAX_OUTPUT_BYTES / 1024}KB.`,
+    promptSnippet: "Fast deterministic content search backed by FFF",
+    promptGuidelines: [
+      `Use ${names.grep} when you need exact grep-style content search with FFF speed; use ffgrep for fuzzy/smart discovery.`,
+      `Set literal=true on ${names.grep} for fixed-string searches; regex is the default to match Pi's built-in grep semantics.`,
+    ],
+    parameters: grepSchema,
+    async execute(_toolCallId, params: GrepInput, signal, _onUpdate, ctx: ExtensionContext) {
+      if (signal?.aborted) throw new Error("Operation aborted");
+      const cwd = ctx.cwd || activeCwd;
+      const f = await ensureFinder(cwd);
+      const searchPathAbs = resolveWorkspacePath(cwd, params.path, ".");
+      const { isDirectory } = grepPathConstraint(cwd, searchPathAbs);
+      const effectiveLimit = normalizePositiveLimit(params.limit, DEFAULT_GREP_LIMIT);
+      const contextLines = Math.max(0, Math.floor(params.context ?? 0));
+      const mode = grepModeAndPattern(params);
+      const query = buildGrepQuery(cwd, params, searchPathAbs, mode.pattern);
+
+      const result = f.grep(query, {
+        mode: mode.mode,
+        smartCase: false,
+        pageSize: effectiveLimit,
+        maxMatchesPerFile: effectiveLimit,
+        beforeContext: contextLines,
+        afterContext: contextLines,
+      });
+      if (!result.ok) throw new Error(result.error);
+      if (result.value.regexFallbackError) throw new Error(`Invalid regex: ${result.value.regexFallbackError}`);
+      if (signal?.aborted) throw new Error("Operation aborted");
+
+      if (result.value.items.length === 0) {
+        return { content: [{ type: "text", text: "No matches found" }], details: undefined };
+      }
+
+      const formatted = formatGrepMatches(cwd, searchPathAbs, isDirectory, result.value.items, contextLines);
+      const truncated = truncateOutput(formatted.output);
+      const notices: string[] = [];
+      const details: Record<string, unknown> = {
+        backend: "fff.grep",
+        mode: mode.mode,
+        totalMatched: result.value.totalMatched,
+        totalFiles: result.value.totalFiles,
+        totalFilesSearched: result.value.totalFilesSearched,
+        filteredFileCount: result.value.filteredFileCount,
+      };
+
+      if (result.value.nextCursor) {
+        notices.push(`${effectiveLimit} matches limit reached. Use limit=${effectiveLimit * 2} for more, or refine pattern`);
+        details.matchLimitReached = effectiveLimit;
+      }
+      if (formatted.linesTruncated) {
+        notices.push(`Some lines truncated to ${GREP_MAX_LINE_LENGTH} chars. Use read tool to see full lines`);
+        details.linesTruncated = true;
+      }
+      if (truncated.truncated) {
+        notices.push(`${MAX_OUTPUT_BYTES / 1024}KB output limit reached`);
+        details.truncation = truncated;
+      }
+
+      return {
+        content: [{ type: "text", text: appendNotices(truncated.content, notices) }],
+        details,
+      };
+    },
+  });
+
+  pi.registerCommand("fff-compat", {
+    description: "Show FFF compatibility search status",
+    handler: async (_args, ctx) => {
+      try {
+        const f = await ensureFinder(ctx.cwd);
+        const health = f.healthCheck();
+        if (!health.ok) {
+          ctx.ui.notify(`FFF compat health failed: ${health.error}`, "error");
+          return;
+        }
+        const progress = f.getScanProgress();
+        const homeScan = envFlagEnabled(process.env[HOME_SCAN_ENV]);
+        const watchDisabled = envFlagEnabled(process.env[DISABLE_WATCH_ENV]);
+        const lines = [
+          `Mode: ${overriding ? "override find/grep" : `${names.find}/${names.grep}`}`,
+          `FFF v${health.value.version}`,
+          `Base: ${health.value.filePicker.basePath ?? ctx.cwd}`,
+          `Indexed: ${health.value.filePicker.indexedFiles ?? "unknown"} files`,
+          `Git: ${health.value.git.repositoryFound ? `yes (${health.value.git.workdir ?? "unknown"})` : "no"}`,
+          `Home scan: ${homeScan ? "on (PI_FFF_COMPAT_HOME_SCAN=1)" : "off (workspace only)"}`,
+          `Watcher: ${watchDisabled ? "disabled (PI_FFF_COMPAT_DISABLE_WATCH=1)" : "enabled"}`,
+        ];
+        if (progress.ok) {
+          lines.push(
+            `Scanning: ${progress.value.isScanning ? "yes" : "no"} (${progress.value.scannedFilesCount} scanned, warmup ${progress.value.isWarmupComplete ? "done" : "pending"})`,
+            `Watcher ready: ${progress.value.isWatcherReady ? "yes" : "no"}`,
+          );
+        }
+        ctx.ui.notify(lines.join("\n"), "info");
+      } catch (error) {
+        ctx.ui.notify(`FFF compat unavailable: ${error instanceof Error ? error.message : String(error)}`, "error");
+      }
+    },
+  });
+
+  pi.registerCommand("fff-compat-rescan", {
+    description: "Trigger a rescan for FFF compatibility search",
+    handler: async (_args, ctx) => {
+      try {
+        const f = await ensureFinder(ctx.cwd);
+        const result = f.scanFiles();
+        if (!result.ok) {
+          ctx.ui.notify(`FFF compat rescan failed: ${result.error}`, "error");
+          return;
+        }
+        ctx.ui.notify("FFF compat rescan triggered", "info");
+      } catch (error) {
+        ctx.ui.notify(`FFF compat rescan unavailable: ${error instanceof Error ? error.message : String(error)}`, "error");
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@nklisch/pi-fff-compat",
+  "version": "0.1.0",
+  "description": "Fast FFF-backed file search through Pi-native find/grep semantics — glob-only file lookup and exact regex/literal grep with no fuzzy fallback.",
+  "author": {
+    "name": "nklisch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nklisch/pi-extensions.git",
+    "directory": "packages/pi-fff-compat"
+  },
+  "bugs": {
+    "url": "https://github.com/nklisch/pi-extensions/issues"
+  },
+  "homepage": "https://github.com/nklisch/pi-extensions/tree/main/packages/pi-fff-compat#readme",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "fff",
+    "search",
+    "find",
+    "grep",
+    "ripgrep"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "private": false,
+  "dependencies": {
+    "@ff-labs/fff-node": ">=0.9.6 <1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.82.0",
+    "@earendil-works/pi-coding-agent": "0.82.0"
+  },
+  "scripts": {
+    "test": "bun test extensions/*.test.ts"
+  }
+}