@ff-labs/pi-fff 0.11.0 → 0.11.1-nightly.12142b0

package/README.md

@@ -83,8 +83,11 @@ This extension registers FFF-powered tools (`fffind`, `ffgrep`, `fff-multi-grep`
 
 Search file contents. Smart case, plain text by default, regex optional.
 
+Set `definitions_only: true` to search for matching declarations. If the completed search finds none, the tool reports that and returns ordinary matches. Cursors remember the search or fallback state. The optional `fff-multi-grep` tool accepts the same flag. Omitting the flag keeps ordinary search behavior.
+
 Parameters:
 - `pattern` — search text or regex
+- `definitions_only` — prefer declarations; fall back to ordinary matches with a notice when none exist
 - `path` — directory/file constraint (e.g. `src/`, `*.ts`)
 - `ignoreCase` — force case-insensitive
 - `literal` — treat as literal string (default: true)
@@ -107,6 +110,7 @@ OR-logic multi-pattern content search. SIMD-accelerated Aho-Corasick.
 
 Parameters:
 - `patterns` — array of literal patterns (OR logic)
+- `definitions_only` — prefer declarations with the same fallback behavior
 - `constraints` — file constraints (e.g. `*.{ts,tsx} !test/`)
 - `context` — context lines
 - `limit` — max matches (default: 100)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ff-labs/pi-fff",
   "public": true,
-  "version": "0.11.0",
+  "version": "0.11.1-nightly.12142b0",
   "description": "pi extension: FFF-powered fuzzy file and content search",
   "type": "module",
   "license": "MIT",
@@ -41,8 +41,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@ff-labs/fff-bun": "0.11.0",
-    "@ff-labs/fff-node": "0.11.0"
+    "@ff-labs/fff-bun": "0.11.1-nightly.12142b0",
+    "@ff-labs/fff-node": "0.11.1-nightly.12142b0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/src/index.ts

@@ -89,10 +89,19 @@ function toolNameList(names: ToolNames): string[] {
 // Cursor store — simple bounded Map for pagination cursors
 // ---------------------------------------------------------------------------
 
-const cursorCache = new Map<string, GrepCursor>();
+interface ToolGrepCursor {
+  cursor: GrepCursor;
+  finder: FileFinderApi;
+  definitionsOnly: boolean;
+  foundDefinitions: boolean;
+  mode?: GrepMode;
+  query?: string;
+}
+
+const cursorCache = new Map<string, ToolGrepCursor>();
 let cursorCounter = 0;
 
-function storeCursor(cursor: GrepCursor): string {
+function storeCursor(cursor: ToolGrepCursor): string {
   const id = `fff_c${++cursorCounter}`;
   cursorCache.set(id, cursor);
   if (cursorCache.size > 200) {
@@ -102,7 +111,7 @@ function storeCursor(cursor: GrepCursor): string {
   return id;
 }
 
-function getCursor(id: string): GrepCursor | undefined {
+function getCursor(id: string): ToolGrepCursor | undefined {
   return cursorCache.get(id);
 }
 
@@ -546,7 +555,6 @@ export default function fffExtension(pi: ExtensionAPI) {
   }
 
   function destroyFinder() {
-    stopHomeScanStatus();
     if (mainFinder && !mainFinder.isDestroyed) {
       mainFinder.destroy();
       mainFinder = null;
@@ -556,6 +564,8 @@ export default function fffExtension(pi: ExtensionAPI) {
     auxPool?.destroy();
     auxPool = null;
     pickers = null;
+    // UI teardown last: a throwing ctx must not leak the native finders (#948).
+    stopHomeScanStatus();
   }
 
   async function resolveFinderForPath(
@@ -854,8 +864,11 @@ export default function fffExtension(pi: ExtensionAPI) {
     }
   });
 
-  pi.on("session_shutdown", async () => {
+  // A ctx captured from a replaced session is stale and throws on access (#948).
+  pi.on("session_shutdown", async (_event, ctx) => {
+    uiCtx = ctx;
     destroyFinder();
+    uiCtx = null;
   });
 
   // --- Shared render helpers ---
@@ -954,7 +967,15 @@ export default function fffExtension(pi: ExtensionAPI) {
 
   // --- grep tool ---
 
+  const definitionsOnlySchema = Type.Optional(
+    Type.Boolean({
+      description:
+        "Return matching declarations. If none are found, report that and return other matches.",
+    }),
+  );
+
   const grepSchema = Type.Object({
+    definitions_only: definitionsOnlySchema,
     pattern: Type.String({
       description: "Search pattern (literal text or regex)",
     }),
@@ -996,6 +1017,7 @@ export default function fffExtension(pi: ExtensionAPI) {
     promptSnippet: "Grep contents",
     promptGuidelines: (names) => [
       `${names.grep}: prefer bare identifiers as patterns. Literal queries are most efficient.`,
+      `${names.grep}: use definitions_only: true to find declarations; if none are found, the tool returns other matches with a notice.`,
       `${names.grep}: use path for include ('src/', '*.ts') and exclude for noise ('test/,*.min.js').`,
       `${names.grep}: caseSensitive: true when you need exact case (smart-case otherwise).`,
       `${names.grep}: after 1-2 greps, read the top match instead of more greps.`,
@@ -1006,25 +1028,31 @@ export default function fffExtension(pi: ExtensionAPI) {
       if (signal?.aborted) throw new Error("Operation aborted");
 
       const pattern = params.pattern;
-      const aux = await resolveFinderForPath(params.path, pattern, params.exclude);
+      const resumed = params.cursor ? getCursor(params.cursor) : undefined;
+      const aux = resumed
+        ? null
+        : await resolveFinderForPath(params.path, pattern, params.exclude);
 
-      const picker = aux ? aux.finder : await ensureFinder(activeCwd);
+      const picker =
+        resumed?.finder ?? (aux ? aux.finder : await ensureFinder(activeCwd));
+      if (picker.isDestroyed)
+        throw new Error("Search cursor expired. Start a new search without the cursor.");
       const effectiveLimit = Math.max(1, params.limit ?? DEFAULT_GREP_LIMIT);
       // pageSize caps TOTAL matches across all files (soft cap: the current file
       // is always finished first). maxMatchesPerFile stays decoupled at the engine
       // default so same-file overflow remains reachable via cursor (#825).
       const pageSize = Math.min(effectiveLimit, GREP_PAGE_SIZE_MAX);
       const context = clampContext(params.context);
-      const query = aux
-        ? aux.query
-        : buildQuery(params.path, pattern, params.exclude, activeCwd);
+      let query =
+        resumed?.query ??
+        (aux ? aux.query : buildQuery(params.path, pattern, params.exclude, activeCwd));
 
       // Auto-detect: regex if the pattern has regex metacharacters AND parses
       // as a valid regex, otherwise plain literal. The fuzzy fallback below
       // only kicks in for plain mode — regex queries are intentional.
       const hasRegexSyntax = pattern !== pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
-      let mode: GrepMode = hasRegexSyntax ? "regex" : "plain";
+      let mode: GrepMode = resumed?.mode ?? (hasRegexSyntax ? "regex" : "plain");
       if (mode === "regex") {
         try {
           new RegExp(pattern);
@@ -1059,21 +1087,42 @@ export default function fffExtension(pi: ExtensionAPI) {
       // (case-insensitive when pattern is all lowercase).
       const smartCase = params.caseSensitive !== true;
 
-      const grepResult = picker.grep(query, {
+      let definitionsOnly = resumed?.definitionsOnly ?? params.definitions_only ?? false;
+      const preferDefinitions = definitionsOnly;
+      const foundDefinitions = resumed?.foundDefinitions ?? false;
+      const options = {
         mode,
         smartCase,
         maxMatchesPerFile: GREP_MAX_MATCHES_PER_FILE,
         pageSize,
-        cursor: (params.cursor ? getCursor(params.cursor) : null) ?? null,
+        cursor: resumed?.cursor ?? null,
         beforeContext: context,
         afterContext: context,
-        classifyDefinitions: true,
         timeBudgetMs: GREP_TIME_BUDGET_MS,
+      };
+      const grepResult = picker.grep(query, {
+        ...options,
+        classifyDefinitions: definitionsOnly ? "definition_only" : "classify",
       });
 
       if (!grepResult.ok) throw new Error(grepResult.error);
 
       let result = grepResult.value;
+      const definitionsFallback =
+        definitionsOnly &&
+        !foundDefinitions &&
+        result.items.length === 0 &&
+        !result.nextCursor;
+      if (definitionsFallback) {
+        const fallback = picker.grep(query, {
+          ...options,
+          cursor: null,
+          classifyDefinitions: "classify",
+        });
+        if (!fallback.ok) throw new Error(fallback.error);
+        result = fallback.value;
+        definitionsOnly = false;
+      }
       let fuzzyNotice: string | null = null;
 
       // if we hit the timeout do not run the fuzzy fallback
@@ -1081,7 +1130,7 @@ export default function fffExtension(pi: ExtensionAPI) {
       if (
         result.items.length === 0 &&
         !result.nextCursor &&
-        !params.cursor &&
+        (!params.cursor || definitionsFallback) &&
         mode !== "regex"
       ) {
         // When the caller pinned a specific file (path has an extension), the
@@ -1091,7 +1140,7 @@ export default function fffExtension(pi: ExtensionAPI) {
         // excluded / out-of-scope directories.
         const lastSeg = params.path?.split(/[\\/]/).pop() ?? "";
         const pathTargetsFile = /\.[a-zA-Z][a-zA-Z0-9]{0,9}$/.test(lastSeg);
-        const fuzzyQuery = pathTargetsFile ? pattern : query;
+        const fuzzyQuery = pathTargetsFile && !preferDefinitions ? pattern : query;
         const fuzzy = picker.grep(fuzzyQuery, {
           mode: "fuzzy",
           smartCase,
@@ -1100,13 +1149,15 @@ export default function fffExtension(pi: ExtensionAPI) {
           cursor: null,
           beforeContext: 0,
           afterContext: 0,
-          classifyDefinitions: true,
+          classifyDefinitions: definitionsOnly ? "definition_only" : "classify",
           timeBudgetMs: GREP_TIME_BUDGET_MS,
         });
 
         if (fuzzy.ok && fuzzy.value.items.length > 0) {
           fuzzyNotice = `0 exact matches. Maybe you meant this?`;
           result = fuzzy.value;
+          mode = "fuzzy";
+          query = fuzzyQuery;
         }
       }
 
@@ -1116,11 +1167,27 @@ export default function fffExtension(pi: ExtensionAPI) {
         notices.push(`Invalid regex: ${result.regexFallbackError}, used literal match`);
       }
       if (result.nextCursor) {
-        notices.push(`Continue with cursor="${storeCursor(result.nextCursor)}"`);
+        const cursor = storeCursor({
+          cursor: result.nextCursor,
+          finder: picker,
+          definitionsOnly,
+          foundDefinitions:
+            foundDefinitions || (definitionsOnly && result.items.length > 0),
+          mode,
+          query,
+        });
+        notices.push(`Continue with cursor="${cursor}"`);
       }
 
       if (notices.length > 0) output += `\n\n[${notices.join(". ")}]`;
       if (fuzzyNotice) output = `[${fuzzyNotice}]\n${output}`;
+      if (definitionsFallback) {
+        const notice =
+          result.items.length > 0 || result.nextCursor
+            ? "No matching definitions found. Showing other matches:"
+            : "No matching definitions or other matches found.";
+        output = `[${notice}]\n${output}`;
+      }
 
       return {
         content: [{ type: "text", text: output }],
@@ -1300,6 +1367,7 @@ export default function fffExtension(pi: ExtensionAPI) {
 
   if (enableMultiGrep) {
     const multiGrepSchema = Type.Object({
+      definitions_only: definitionsOnlySchema,
       patterns: Type.Array(Type.String(), {
         description:
           "Literal patterns (OR). Include snake_case/camelCase/PascalCase variants.",
@@ -1328,6 +1396,7 @@ export default function fffExtension(pi: ExtensionAPI) {
         `${names.multiGrep}: use when searching for several identifiers at once.`,
         `${names.multiGrep}: include all naming-convention variants (snake/camel/Pascal).`,
         `${names.multiGrep}: patterns are literal. Use constraints for file filters.`,
+        `${names.multiGrep}: use definitions_only: true to find declarations; if none are found, the tool returns other matches with a notice.`,
       ],
       parameters: multiGrepSchema,
 
@@ -1336,36 +1405,76 @@ export default function fffExtension(pi: ExtensionAPI) {
         if (!params.patterns?.length)
           throw new Error("patterns array must have at least 1 element");
 
-        const f = await ensureFinder(activeCwd);
+        const resumed = params.cursor ? getCursor(params.cursor) : undefined;
+        const f = resumed?.finder ?? (await ensureFinder(activeCwd));
+        if (f.isDestroyed)
+          throw new Error(
+            "Search cursor expired. Start a new search without the cursor.",
+          );
         const effectiveLimit = Math.max(1, params.limit ?? DEFAULT_GREP_LIMIT);
         const pageSize = Math.min(effectiveLimit, GREP_PAGE_SIZE_MAX);
         const context = clampContext(params.context);
 
-        const grepResult = f.multiGrep({
+        let definitionsOnly =
+          resumed?.definitionsOnly ?? params.definitions_only ?? false;
+        const foundDefinitions = resumed?.foundDefinitions ?? false;
+        const options = {
           patterns: params.patterns,
           constraints: params.constraints,
           maxMatchesPerFile: GREP_MAX_MATCHES_PER_FILE,
           pageSize,
           smartCase: true,
-          cursor: (params.cursor ? getCursor(params.cursor) : null) ?? null,
+          cursor: resumed?.cursor ?? null,
           beforeContext: context,
           afterContext: context,
+        };
+        const grepResult = f.multiGrep({
+          ...options,
+          classifyDefinitions: definitionsOnly ? "definition_only" : "off",
         });
 
         if (!grepResult.ok) throw new Error(grepResult.error);
 
-        const result = grepResult.value;
+        let result = grepResult.value;
+        const definitionsFallback =
+          definitionsOnly &&
+          !foundDefinitions &&
+          result.items.length === 0 &&
+          !result.nextCursor;
+        if (definitionsFallback) {
+          const fallback = f.multiGrep({
+            ...options,
+            cursor: null,
+            classifyDefinitions: "off",
+          });
+          if (!fallback.ok) throw new Error(fallback.error);
+          result = fallback.value;
+          definitionsOnly = false;
+        }
         let output = formatGrepOutput(result);
 
         const notices: string[] = [];
         if (result.items.length >= effectiveLimit)
           notices.push(`${effectiveLimit}+ matches (refine patterns)`);
-        if (result.nextCursor)
-          notices.push(
-            `More available. cursor="${storeCursor(result.nextCursor)}" to continue`,
-          );
+        if (result.nextCursor) {
+          const cursor = storeCursor({
+            cursor: result.nextCursor,
+            finder: f,
+            definitionsOnly,
+            foundDefinitions:
+              foundDefinitions || (definitionsOnly && result.items.length > 0),
+          });
+          notices.push(`More available. cursor="${cursor}" to continue`);
+        }
 
         if (notices.length > 0) output += `\n\n[${notices.join(". ")}]`;
+        if (definitionsFallback) {
+          const notice =
+            result.items.length > 0 || result.nextCursor
+              ? "No matching definitions found. Showing other matches:"
+              : "No matching definitions or other matches found.";
+          output = `[${notice}]\n${output}`;
+        }
 
         return {
           content: [{ type: "text", text: output }],