@ff-labs/fff-bun 0.4.3-nightly.eb577ea → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ff-labs/fff-bun",
-  "version": "0.4.3-nightly.eb577ea",
+  "version": "0.5.0",
   "private": false,
   "description": "High-performance fuzzy file finder for Bun - perfect for LLM agent tools",
   "type": "module",
@@ -62,14 +62,14 @@
   },
   "homepage": "https://github.com/dmtrKovalenko/fff.nvim#readme",
   "optionalDependencies": {
-    "@ff-labs/fff-bin-darwin-arm64": "0.4.3-nightly.eb577ea",
-    "@ff-labs/fff-bin-darwin-x64": "0.4.3-nightly.eb577ea",
-    "@ff-labs/fff-bin-linux-x64-gnu": "0.4.3-nightly.eb577ea",
-    "@ff-labs/fff-bin-linux-arm64-gnu": "0.4.3-nightly.eb577ea",
-    "@ff-labs/fff-bin-linux-x64-musl": "0.4.3-nightly.eb577ea",
-    "@ff-labs/fff-bin-linux-arm64-musl": "0.4.3-nightly.eb577ea",
-    "@ff-labs/fff-bin-win32-x64": "0.4.3-nightly.eb577ea",
-    "@ff-labs/fff-bin-win32-arm64": "0.4.3-nightly.eb577ea"
+    "@ff-labs/fff-bin-darwin-arm64": "0.5.0",
+    "@ff-labs/fff-bin-darwin-x64": "0.5.0",
+    "@ff-labs/fff-bin-linux-x64-gnu": "0.5.0",
+    "@ff-labs/fff-bin-linux-arm64-gnu": "0.5.0",
+    "@ff-labs/fff-bin-linux-x64-musl": "0.5.0",
+    "@ff-labs/fff-bin-linux-arm64-musl": "0.5.0",
+    "@ff-labs/fff-bin-win32-x64": "0.5.0",
+    "@ff-labs/fff-bin-win32-arm64": "0.5.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.8",

package/src/ffi.ts

@@ -16,6 +16,7 @@ import type {
   GrepResult,
   Location,
   Result,
+  ScanProgress,
   Score,
   SearchResult,
 } from "./types";
@@ -125,6 +126,10 @@ const ffiDefinition = {
     args: [FFIType.ptr, FFIType.u64],
     returns: FFIType.ptr,
   },
+  fff_wait_for_watcher: {
+    args: [FFIType.ptr, FFIType.u64],
+    returns: FFIType.ptr,
+  },
   fff_restart_index: {
     args: [FFIType.ptr, FFIType.cstring],
     returns: FFIType.ptr,
@@ -817,16 +822,16 @@ export function ffiIsScanning(handle: NativeHandle): boolean {
   return library.symbols.fff_is_scanning(handle) as boolean;
 }
 
-// FffScanProgress { scanned_files_count: u64(8), is_scanning: bool(1+7pad) }
+// FffScanProgress { scanned_files_count: u64(8), is_scanning: bool(1), is_watcher_ready: bool(1), is_warmup_complete: bool(1) + pad }
 const SP_COUNT = 0; // u64 (8)
-const SP_SCANNING = 8; // bool (1 + 7 pad)
+const SP_SCANNING = 8; // bool (1)
+const SP_WATCHER_READY = 9; // bool (1)
+const SP_WARMUP_COMPLETE = 10; // bool (1)
 
 /**
  * Get scan progress.
  */
-export function ffiGetScanProgress(
-  handle: NativeHandle,
-): Result<{ scannedFilesCount: number; isScanning: boolean }> {
+export function ffiGetScanProgress(handle: NativeHandle): Result<ScanProgress> {
   const library = loadLibrary();
   const resultPtr = library.symbols.fff_get_scan_progress(handle);
   const envelope = readResultEnvelope(resultPtr);
@@ -837,9 +842,11 @@ export function ffiGetScanProgress(
   }
 
   const hp = asPtr(envelope.handlePtr);
-  const result = {
+  const result: ScanProgress = {
     scannedFilesCount: Number(read.u64(hp, SP_COUNT)),
     isScanning: read.u8(hp, SP_SCANNING) !== 0,
+    isWatcherReady: read.u8(hp, SP_WATCHER_READY) !== 0,
+    isWarmupComplete: read.u8(hp, SP_WARMUP_COMPLETE) !== 0,
   };
   library.symbols.fff_free_scan_progress(hp);
   return { ok: true, value: result };
@@ -854,6 +861,18 @@ export function ffiWaitForScan(handle: NativeHandle, timeoutMs: number): Result<
   return parseBoolResult(resultPtr);
 }
 
+/**
+ * Wait for the background file watcher to be ready.
+ */
+export function ffiWaitForWatcher(
+  handle: NativeHandle,
+  timeoutMs: number,
+): Result<boolean> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_wait_for_watcher(handle, BigInt(timeoutMs));
+  return parseBoolResult(resultPtr);
+}
+
 /**
  * Restart index in new path.
  */

package/src/finder.ts

@@ -24,6 +24,7 @@ import {
   ffiSearch,
   ffiTrackQuery,
   ffiWaitForScan,
+  ffiWaitForWatcher,
   isAvailable,
   type NativeHandle,
 } from "./ffi";
@@ -345,6 +346,22 @@ export class FileFinder {
     return ffiWaitForScan(guard.value, timeoutMs);
   }
 
+  /**
+   * Wait for the background file watcher to be ready.
+   *
+   * The watcher is created after the initial scan, git status, and optional
+   * warmup phases complete. Useful for tests that need to ensure filesystem
+   * events will be detected.
+   *
+   * @param timeoutMs - Maximum time to wait in milliseconds (default: 10000)
+   * @returns true if watcher is ready, false if timed out
+   */
+  waitForWatcher(timeoutMs: number = 10000): Result<boolean> {
+    const guard = this.ensureAlive();
+    if (!guard.ok) return guard;
+    return ffiWaitForWatcher(guard.value, timeoutMs);
+  }
+
   /**
    * Change the indexed directory to a new path.
    *

package/src/git-lifecycle.test.ts

@@ -127,7 +127,7 @@ describe.skipIf(process.platform === "win32")("Git lifecycle integration", () =>
   let tmpDir: string;
   let finder: FileFinder;
 
-  beforeAll(() => {
+  beforeAll(async () => {
     // Create temp directory and initialise a git repo with two committed files.
     // Use realpathSync to resolve symlinks (macOS /var -> /private/var) so
     // that git2's resolved workdir paths match the file picker's base_path.
@@ -151,6 +151,20 @@ describe.skipIf(process.platform === "win32")("Git lifecycle integration", () =>
     // Wait for the initial scan to finish
     const scanResult = finder.waitForScan(10_000);
     expect(scanResult.ok).toBe(true);
+
+    // Poll getScanProgress until the watcher is ready so that
+    // filesystem events (file creates, deletes) are detected.
+    const start = Date.now();
+    while (Date.now() - start < WATCHER_TIMEOUT_MS) {
+      const progress = finder.getScanProgress();
+      if (progress.ok && progress.value.isWatcherReady) break;
+      await sleep(POLL_INTERVAL_MS);
+    }
+    const progress = finder.getScanProgress();
+    expect(progress.ok).toBe(true);
+    if (progress.ok) {
+      expect(progress.value.isWatcherReady).toBe(true);
+    }
   });
 
   afterAll(() => {

package/src/types.ts

@@ -144,6 +144,10 @@ export interface ScanProgress {
   scannedFilesCount: number;
   /** Whether a scan is currently in progress */
   isScanning: boolean;
+  /** Whether the background file watcher is ready */
+  isWatcherReady: boolean;
+  /** Whether the warmup/bigram phase has completed */
+  isWarmupComplete: boolean;
 }
 
 /**