@nklisch/pi-fff-compat 0.1.1 → 0.1.2

package/extensions/fff-compat-search.ts

@@ -26,6 +26,7 @@ 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";
+import { createGenerationGuardedFinderLifecycle } from "./finder-lifecycle.js";
 
 const EXTENSION_NAME = "pi-fff-compat";
 const PACKAGE_HINT = "bundled dependency of @nklisch/pi-fff-compat";
@@ -154,9 +155,6 @@ type Truncation = {
 };
 
 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 {
@@ -195,7 +193,7 @@ function loadFffModule(): Promise<FffModule> {
   if (!fffModulePromise) {
     fffModulePromise = (async () => {
       try {
-        return (await import("@ff-labs/fff-node")) as FffModule;
+        return (await import("@ff-labs/fff-node")) as unknown as FffModule;
       } catch (error) {
         throw new Error(
           `Failed to load @ff-labs/fff-node (${PACKAGE_HINT}): ${error instanceof Error ? error.message : String(error)}`,
@@ -206,44 +204,38 @@ function loadFffModule(): Promise<FffModule> {
   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;
-    }),
-  };
+const finderLifecycle = createGenerationGuardedFinderLifecycle<FffFinder>(async (cwd) => {
+  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}`);
 
-  return finderPromise.promise;
-}
+  const candidate = created.value;
+  try {
+    const scan = await candidate.waitForScan(INITIAL_SCAN_WAIT_MS);
+    if (!scan.ok) throw new Error(`FFF scan failed: ${scan.error}`);
+    return candidate;
+  } catch (error) {
+    if (!candidate.isDestroyed) {
+      try {
+        candidate.destroy();
+      } catch {
+        // Preserve the scan/create failure; lifecycle cleanup is best effort.
+      }
+    }
+    throw error;
+  }
+});
 
-function destroyFinder(): void {
-  if (finder && !finder.isDestroyed) finder.destroy();
-  finder = null;
-  finderCwd = null;
+function ensureFinder(cwd: string): Promise<FffFinder> {
+  return finderLifecycle.ensure(cwd);
 }
 
 function truncateLine(line: string): { text: string; wasTruncated: boolean } {
@@ -408,6 +400,21 @@ const findSchema = Type.Object({
   limit: Type.Optional(Type.Number({ description: `Maximum number of results (default ${DEFAULT_FIND_LIMIT})` })),
 });
 
+function reportInitializationFailure(ctx: ExtensionContext, error: unknown): void {
+  let detail = "unknown failure";
+  try { detail = error instanceof Error ? error.message : String(error); }
+  catch { detail = "unreadable failure"; }
+  const message = `${EXTENSION_NAME} init failed: ${detail}`;
+  try {
+    ctx.ui.notify(message, "error");
+  } catch {
+    // Initialization can settle after session replacement. The old UI is then
+    // intentionally stale, so fall back to a process diagnostic without
+    // allowing either reporting sink to escape the awaited host boundary.
+    try { console.error(message); } catch { /* no safe reporting sink remains */ }
+  }
+}
+
 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)" })),
@@ -449,12 +456,12 @@ export default function fffCompatSearch(pi: ExtensionAPI) {
     try {
       await ensureFinder(activeCwd);
     } catch (error) {
-      ctx.ui.notify(`${EXTENSION_NAME} init failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+      reportInitializationFailure(ctx, error);
     }
   });
 
   pi.on("session_shutdown", async () => {
-    destroyFinder();
+    finderLifecycle.revoke();
   });
 
   pi.registerTool({

package/extensions/finder-lifecycle.ts

@@ -0,0 +1,92 @@
+export interface FinderLike {
+  readonly isDestroyed: boolean;
+  destroy(): void;
+}
+
+interface CurrentFinder<F extends FinderLike> {
+  cwd: string;
+  generation: number;
+  finder: F;
+}
+
+interface PendingFinder<F extends FinderLike> {
+  cwd: string;
+  generation: number;
+  promise: Promise<F>;
+}
+
+/**
+ * Own the asynchronous finder lifecycle separately from the Pi event seam.
+ * A scan can outlive session_shutdown; the generation check prevents that late
+ * completion from becoming the finder for a replacement session.
+ */
+export function createGenerationGuardedFinderLifecycle<F extends FinderLike>(
+  createFinder: (cwd: string) => Promise<F>,
+): {
+  ensure(cwd: string): Promise<F>;
+  revoke(): void;
+} {
+  let generation = 0;
+  let current: CurrentFinder<F> | null = null;
+  let pending: PendingFinder<F> | null = null;
+
+  function destroyQuietly(candidate: F | null): void {
+    if (candidate === null || candidate.isDestroyed) return;
+    // A stale finder has no live session context in which to report a cleanup
+    // failure. Do not let best-effort shutdown cleanup reject the host event.
+    try {
+      candidate.destroy();
+    } catch {
+      // The lifecycle is already revoked; there is no safe session state to
+      // repopulate, which is the guarantee this cleanup protects.
+    }
+  }
+
+  function revoke(): void {
+    generation++;
+    const old = current;
+    current = null;
+    destroyQuietly(old?.finder ?? null);
+  }
+
+  function ensure(cwd: string): Promise<F> {
+    if (current?.finder.isDestroyed) current = null;
+    if (current?.cwd === cwd) return Promise.resolve(current.finder);
+    if (pending?.cwd === cwd && pending.generation === generation) return pending.promise;
+
+    // A different workspace, or a new session after revocation, invalidates
+    // every earlier initialization. Its late result will be destroyed below.
+    generation++;
+    const requestedGeneration = generation;
+    const old = current;
+    current = null;
+    destroyQuietly(old?.finder ?? null);
+
+    const initialization = (async (): Promise<F> => {
+      let candidate: F | null = null;
+      try {
+        candidate = await createFinder(cwd);
+        if (requestedGeneration !== generation) {
+          throw new Error("FFF finder initialization was revoked");
+        }
+        current = { cwd, generation: requestedGeneration, finder: candidate };
+        return candidate;
+      } catch (error) {
+        // If creation itself fails after allocating a finder, the factory owns
+        // cleanup. A completed-but-invalidated candidate is closed exactly once
+        // here, before its rejected promise reaches the old session callback.
+        if (candidate !== null && current?.finder !== candidate) destroyQuietly(candidate);
+        throw error;
+      }
+    })();
+
+    let guardedPromise!: Promise<F>;
+    guardedPromise = initialization.finally(() => {
+      if (pending?.promise === guardedPromise) pending = null;
+    });
+    pending = { cwd, generation: requestedGeneration, promise: guardedPromise };
+    return guardedPromise;
+  }
+
+  return { ensure, revoke };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nklisch/pi-fff-compat",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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"