@ff-labs/fff-bun 0.9.4-nightly.8092cfa → 0.9.4

package/README.md

@@ -29,6 +29,26 @@ The correct native binary for your platform is installed automatically via platf
 
 If the platform package isn't available, the postinstall script will attempt to download from GitHub releases as a fallback.
 
+### Standalone executables (`bun build --compile`)
+
+`@ff-labs/fff-bun` embeds the native library into single-file executables built
+with `bun build --compile`. macOS and Windows work with no extra flags:
+
+```bash
+bun build --compile ./app.ts --outfile myapp
+```
+
+On **Linux** the C library's libc (glibc vs musl) can't be detected at build
+time, so you must pass it as a build constant for the lib to embed:
+
+```bash
+bun build --compile --define FFF_LIBC='"gnu"'  ./app.ts --outfile myapp   # glibc
+bun build --compile --define FFF_LIBC='"musl"' ./app.ts --outfile myapp   # musl / Alpine
+```
+
+Without the define on Linux the library is resolved at runtime instead of being
+embedded, which works under `bun run` but not in a standalone binary.
+
 ## Quick Start
 
 Each `FileFinder` instance owns an independent native index. Create one, wait

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ff-labs/fff-bun",
-  "version": "0.9.4-nightly.8092cfa",
+  "version": "0.9.4",
   "private": false,
   "description": "High-performance fuzzy file finder for Bun - perfect for LLM agent tools",
   "type": "module",
@@ -17,7 +17,7 @@
     "examples"
   ],
   "scripts": {
-    "test": "bun test src/",
+    "test": "bun test test/",
     "typecheck": "tsc --noEmit",
     "demo": "bun ./examples/search.ts"
   },
@@ -58,14 +58,14 @@
   },
   "homepage": "https://github.com/dmtrKovalenko/fff#readme",
   "optionalDependencies": {
-    "@ff-labs/fff-bin-darwin-arm64": "0.9.4-nightly.8092cfa",
-    "@ff-labs/fff-bin-darwin-x64": "0.9.4-nightly.8092cfa",
-    "@ff-labs/fff-bin-linux-x64-gnu": "0.9.4-nightly.8092cfa",
-    "@ff-labs/fff-bin-linux-arm64-gnu": "0.9.4-nightly.8092cfa",
-    "@ff-labs/fff-bin-linux-x64-musl": "0.9.4-nightly.8092cfa",
-    "@ff-labs/fff-bin-linux-arm64-musl": "0.9.4-nightly.8092cfa",
-    "@ff-labs/fff-bin-win32-x64": "0.9.4-nightly.8092cfa",
-    "@ff-labs/fff-bin-win32-arm64": "0.9.4-nightly.8092cfa"
+    "@ff-labs/fff-bin-darwin-arm64": "0.9.4",
+    "@ff-labs/fff-bin-darwin-x64": "0.9.4",
+    "@ff-labs/fff-bin-linux-x64-gnu": "0.9.4",
+    "@ff-labs/fff-bin-linux-arm64-gnu": "0.9.4",
+    "@ff-labs/fff-bin-linux-x64-musl": "0.9.4",
+    "@ff-labs/fff-bin-linux-arm64-musl": "0.9.4",
+    "@ff-labs/fff-bin-win32-x64": "0.9.4",
+    "@ff-labs/fff-bin-win32-arm64": "0.9.4"
   },
   "devDependencies": {
     "@types/bun": "^1.3.8",

package/src/embed.d.ts

@@ -0,0 +1,17 @@
+// Native library imports embedded via `bun build --compile` (type: "file").
+// Each resolves to the embedded file's path string at runtime.
+declare module "*.so" {
+  const path: string;
+  export default path;
+}
+declare module "*.dylib" {
+  const path: string;
+  export default path;
+}
+declare module "*.dll" {
+  const path: string;
+  export default path;
+}
+
+// Build-time constant injected via `bun build --define FFF_LIBC='"musl"'`.
+declare const FFF_LIBC: "gnu" | "musl";

package/src/embedded.ts

@@ -0,0 +1,53 @@
+/**
+ * Tools for standalone-executable native library embedding.
+ *
+ * `bun build --compile` only bundles files referenced by statically analyzable
+ * imports. Runtime resolution (./download.ts) is invisible to the bundler, so
+ * we additionally reference the platform's native lib through a `type: "file"`
+ * import. Bun then embeds it and returns a `$bunfs` path inside the compiled
+ * binary (and the real on-disk path under `bun run`).
+ *
+ * Linux libc cannot be detected at build time, so it is supplied via the
+ * FFF_LIBC build constant (`bun build --define FFF_LIBC='"musl"'`), defaulting
+ * to glibc. macOS/Windows need no define.
+ */
+
+async function importFile(promise: Promise<{ default: string }>): Promise<string | null> {
+  try {
+    return (await promise).default;
+  } catch {
+    return null;
+  }
+}
+
+async function resolveEmbeddedLibPath(): Promise<string | null> {
+  if (process.platform === "darwin") {
+    return importFile(
+      import(`@ff-labs/fff-bin-darwin-${process.arch}/libfff_c.dylib`, {
+        with: { type: "file" },
+      }),
+    );
+  }
+
+  if (process.platform === "win32") {
+    return importFile(
+      import(`@ff-labs/fff-bin-win32-${process.arch}/fff_c.dll`, {
+        with: { type: "file" },
+      }),
+    );
+  }
+
+  if (process.platform === "linux") {
+    return importFile(
+      import(
+        `@ff-labs/fff-bin-linux-${process.arch}-${typeof FFF_LIBC === "string" ? FFF_LIBC : "gnu"}/libfff_c.so`,
+        { with: { type: "file" } }
+      ),
+    );
+  }
+
+  return null;
+}
+
+// Resolved once at module init so loadLibrary() can stay synchronous.
+export const embeddedLibPath: string | null = await resolveEmbeddedLibPath();

package/src/ffi.ts

@@ -10,6 +10,7 @@
 
 import { CString, dlopen, FFIType, type Pointer, ptr, read } from "bun:ffi";
 import { findBinary } from "./download";
+import { embeddedLibPath } from "./embedded";
 import type {
   DirItem,
   DirSearchResult,
@@ -290,17 +291,36 @@ let lib: FFFLibrary | null = null;
 function loadLibrary(): FFFLibrary {
   if (lib) return lib;
 
-  const binaryPath = findBinary();
+  const isEmbedded = embeddedLibPath?.includes("$bunfs") ?? false;
+  const binaryPath = isEmbedded
+    ? embeddedLibPath
+    : (findBinary() ?? embeddedLibPath);
   if (!binaryPath) {
-    throw new Error(
-      "fff native library not found. Build from source with `cargo build --release -p fff-c` or install the platform package.",
-    );
+    throw new Error(libNotFoundMessage());
   }
 
   lib = dlopen(binaryPath, ffiDefinition);
   return lib;
 }
 
+function libNotFoundMessage(): string {
+  if (import.meta.url.includes("$bunfs")) {
+    if (process.platform === "linux") {
+      return [
+        "You are running bun --compile with fff native library which CAN NOT resolve a binary",
+        "On Linux the libc must be supplied at compile time so the native lib is bundled.",
+        "Rebuild with:",
+        "  bun build --compile --define FFF_LIBC='\"gnu\"'  ...   # glibc",
+        "  bun build --compile --define FFF_LIBC='\"musl\"' ...   # musl / Alpine",
+      ].join("\n");
+    }
+
+    return "fff native library was not embedded into this executable. Rebuild with `bun build --compile` and ensure the @ff-labs/fff-bin-* package for this platform is installed.";
+  }
+
+  return "fff native library not found. Build from source with `cargo build --release -p fff-c` or install the platform package.";
+}
+
 /**
  * Encode a string for FFI (null-terminated)
  */
@@ -329,7 +349,9 @@ function snakeToCamel(obj: unknown): unknown {
 
   const result: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
-    const camelKey = key.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+    const camelKey = key.replace(/_([a-z])/g, (_, letter) =>
+      letter.toUpperCase(),
+    );
     result[camelKey] = snakeToCamel(value);
   }
   return result;
@@ -424,7 +446,8 @@ function parseJsonResult<T>(resultPtr: Pointer | null): Result<T> {
   const jsonStr = readCString(envelope.handlePtr);
   library.symbols.fff_free_string(asPtr(envelope.handlePtr));
 
-  if (jsonStr === null || jsonStr === "") return { ok: true, value: undefined as T };
+  if (jsonStr === null || jsonStr === "")
+    return { ok: true, value: undefined as T };
 
   try {
     return { ok: true, value: snakeToCamel(JSON.parse(jsonStr)) as T };
@@ -725,7 +748,9 @@ function readDirItemStruct(p: number): DirItem {
 /**
  * Parse an FffDirSearchResult from a raw FffResult pointer, then free native memory.
  */
-function parseDirSearchResult(resultPtr: Pointer | null): Result<DirSearchResult> {
+function parseDirSearchResult(
+  resultPtr: Pointer | null,
+): Result<DirSearchResult> {
   if (resultPtr === null) {
     return err("FFI returned null pointer");
   }
@@ -828,7 +853,9 @@ function readMixedItemStruct(p: number): MixedItem {
 /**
  * Parse an FffMixedSearchResult from a raw FffResult pointer, then free native memory.
  */
-function parseMixedSearchResult(resultPtr: Pointer | null): Result<MixedSearchResult> {
+function parseMixedSearchResult(
+  resultPtr: Pointer | null,
+): Result<MixedSearchResult> {
   if (resultPtr === null) {
     return err("FFI returned null pointer");
   }
@@ -860,7 +887,10 @@ function parseMixedSearchResult(resultPtr: Pointer | null): Result<MixedSearchRe
   } else if (locTag === 3) {
     location = {
       type: "range",
-      start: { line: read.i32(hp, MSR_LOC_LINE), col: read.i32(hp, MSR_LOC_COL) },
+      start: {
+        line: read.i32(hp, MSR_LOC_LINE),
+        col: read.i32(hp, MSR_LOC_COL),
+      },
       end: {
         line: read.i32(hp, MSR_LOC_END_LINE),
         col: read.i32(hp, MSR_LOC_END_COL),
@@ -1006,10 +1036,16 @@ function readGrepMatchStruct(p: number): GrepMatch {
     match.fuzzyScore = read.u16(pp, GM_FUZZY_SCORE);
   }
   if (ctxBeforeCount > 0) {
-    match.contextBefore = readCStringArray(read.ptr(pp, GM_CTX_BEFORE), ctxBeforeCount);
+    match.contextBefore = readCStringArray(
+      read.ptr(pp, GM_CTX_BEFORE),
+      ctxBeforeCount,
+    );
   }
   if (ctxAfterCount > 0) {
-    match.contextAfter = readCStringArray(read.ptr(pp, GM_CTX_AFTER), ctxAfterCount);
+    match.contextAfter = readCStringArray(
+      read.ptr(pp, GM_CTX_AFTER),
+      ctxAfterCount,
+    );
   }
   if (read.u8(pp, GM_IS_DEFINITION) !== 0) {
     match.isDefinition = true;
@@ -1291,18 +1327,30 @@ export function ffiGetScanProgress(handle: NativeHandle): Result<ScanProgress> {
 /**
  * Wait for scan to complete.
  */
-export function ffiWaitForScan(handle: NativeHandle, timeoutMs: number): Result<boolean> {
+export function ffiWaitForScan(
+  handle: NativeHandle,
+  timeoutMs: number,
+): Result<boolean> {
   const library = loadLibrary();
-  const resultPtr = library.symbols.fff_wait_for_scan(handle, BigInt(timeoutMs));
+  const resultPtr = library.symbols.fff_wait_for_scan(
+    handle,
+    BigInt(timeoutMs),
+  );
   return parseBoolResult(resultPtr);
 }
 
 /**
  * Restart index in new path.
  */
-export function ffiRestartIndex(handle: NativeHandle, newPath: string): Result<void> {
+export function ffiRestartIndex(
+  handle: NativeHandle,
+  newPath: string,
+): Result<void> {
   const library = loadLibrary();
-  const resultPtr = library.symbols.fff_restart_index(handle, ptr(encodeString(newPath)));
+  const resultPtr = library.symbols.fff_restart_index(
+    handle,
+    ptr(encodeString(newPath)),
+  );
   return parseVoidResult(resultPtr);
 }
 
@@ -1340,7 +1388,10 @@ export function ffiGetHistoricalQuery(
   offset: number,
 ): Result<string | null> {
   const library = loadLibrary();
-  const resultPtr = library.symbols.fff_get_historical_query(handle, BigInt(offset));
+  const resultPtr = library.symbols.fff_get_historical_query(
+    handle,
+    BigInt(offset),
+  );
   return parseStringResult(resultPtr);
 }
 

package/src/git-lifecycle.test.ts

@@ -1,367 +0,0 @@
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { execSync } from "node:child_process";
-import {
-  mkdirSync,
-  mkdtempSync,
-  realpathSync,
-  rmSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { FileItem } from "./fff-api";
-import { FileFinder } from "./index";
-
-/**
- * Integration test: full git lifecycle with a real repository.
- *
- * Creates a temporary git repo, initialises a FileFinder instance pointing at
- * it, then walks through:
- *   1. Initial scan – committed files should have status "clean"
- *   2. Add a new untracked file – should appear as "untracked"
- *   3. Stage the new file – should appear as "staged_new"
- *   4. Commit – should become "clean"
- *   5. Modify a tracked file – should become "modified"
- *   6. Stage the modification – should become "staged_modified"
- *   7. Commit again – back to "clean"
- *   8. Delete a file – should disappear from the index
- */
-
-const POLL_INTERVAL_MS = 100;
-const WATCHER_TIMEOUT_MS = 5_000; // generous CI timeout; polls exit early on fast machines
-
-function git(cwd: string, ...args: string[]) {
-  const escaped = args.map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(" ");
-  execSync(`git ${escaped}`, {
-    cwd,
-    stdio: "pipe",
-    env: {
-      ...process.env,
-      GIT_AUTHOR_NAME: "test",
-      GIT_AUTHOR_EMAIL: "test@test.com",
-      GIT_COMMITTER_NAME: "test",
-      GIT_COMMITTER_EMAIL: "test@test.com",
-    },
-  });
-}
-
-function sleep(ms: number) {
-  return new Promise((r) => setTimeout(r, ms));
-}
-
-function findFile(finder: FileFinder, name: string): FileItem | undefined {
-  const result = finder.fileSearch(name, { pageSize: 200 });
-  if (!result.ok) throw new Error(`search failed: ${result.error}`);
-  return result.value.items.find((item) => item.fileName === name);
-}
-
-/** Poll until a file appears in the index, or the timeout is exceeded. */
-async function waitForFile(
-  finder: FileFinder,
-  name: string,
-): Promise<FileItem | undefined> {
-  const start = Date.now();
-  while (Date.now() - start < WATCHER_TIMEOUT_MS) {
-    const file = findFile(finder, name);
-    if (file !== undefined) return file;
-    await sleep(POLL_INTERVAL_MS);
-  }
-  return findFile(finder, name);
-}
-
-/** Poll until a file has the expected git status, or the timeout is exceeded. */
-async function waitForFileStatus(
-  finder: FileFinder,
-  name: string,
-  status: string,
-): Promise<FileItem | undefined> {
-  const start = Date.now();
-  while (Date.now() - start < WATCHER_TIMEOUT_MS) {
-    const file = findFile(finder, name);
-    if (file?.gitStatus === status) return file;
-    await sleep(POLL_INTERVAL_MS);
-  }
-  return findFile(finder, name);
-}
-
-/** Poll until a file is gone from the index, or the timeout is exceeded. */
-async function waitForFileGone(finder: FileFinder, name: string): Promise<boolean> {
-  const start = Date.now();
-  while (Date.now() - start < WATCHER_TIMEOUT_MS) {
-    if (findFile(finder, name) === undefined) return true;
-    await sleep(POLL_INTERVAL_MS);
-  }
-  return findFile(finder, name) === undefined;
-}
-
-/** Poll until the total file count reaches the expected value, or the timeout is exceeded. */
-async function waitForFileCount(finder: FileFinder, count: number): Promise<number> {
-  const start = Date.now();
-  while (Date.now() - start < WATCHER_TIMEOUT_MS) {
-    const result = finder.fileSearch("", { pageSize: 200 });
-    if (result.ok && result.value.totalFiles === count) return count;
-    await sleep(POLL_INTERVAL_MS);
-  }
-  const result = finder.fileSearch("", { pageSize: 200 });
-  return result.ok ? result.value.totalFiles : -1;
-}
-
-/** Poll grep until predicate on totalMatched is satisfied, or the timeout is exceeded. */
-async function waitForGrep(
-  finder: FileFinder,
-  pattern: string,
-  options: { mode: "plain" | "regex" },
-  predicate: (totalMatched: number) => boolean,
-) {
-  const start = Date.now();
-  while (Date.now() - start < WATCHER_TIMEOUT_MS) {
-    const result = finder.grep(pattern, options);
-    if (result.ok && predicate(result.value.totalMatched)) return result;
-    await sleep(POLL_INTERVAL_MS);
-  }
-  return finder.grep(pattern, options);
-}
-
-describe.skipIf(process.platform === "win32")("Git lifecycle integration", () => {
-  let tmpDir: string;
-  let finder: FileFinder;
-
-  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.
-    tmpDir = realpathSync(mkdtempSync(join(tmpdir(), "fff-git-test-")));
-
-    git(tmpDir, "init", "-b", "main");
-    // Need at least one commit for status to work properly
-    writeFileSync(join(tmpDir, "hello.txt"), "hello world\n");
-    writeFileSync(join(tmpDir, "readme.md"), "# Test Project\n");
-    mkdirSync(join(tmpDir, "src"));
-    writeFileSync(join(tmpDir, "src", "main.rs"), 'fn main() { println?."hi"); }\n');
-    git(tmpDir, "add", "-A");
-    git(tmpDir, "commit", "-m", "initial commit");
-
-    // Create the FileFinder instance
-    const result = FileFinder.create({ basePath: tmpDir });
-    expect(result.ok).toBe(true);
-    if (!result.ok) throw new Error(result.error);
-    finder = result.value;
-
-    // Wait for the initial scan to finish
-    const scanResult = finder.waitForScanBlocking(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(() => {
-    finder?.destroy();
-    if (tmpDir) {
-      rmSync(tmpDir, { recursive: true, force: true });
-    }
-  });
-
-  test("initial scan indexes all committed files", () => {
-    const result = finder.fileSearch("", { pageSize: 200 });
-    expect(result.ok).toBe(true);
-    if (!result.ok) return;
-
-    const names = result.value.items.map((i) => i.relativePath).sort();
-    expect(names).toContain("hello.txt");
-    expect(names).toContain("readme.md");
-    expect(names).toContain("src/main.rs");
-    expect(result.value.totalFiles).toBe(3);
-  });
-
-  test("committed files have clean git status", async () => {
-    const hello = await waitForFileStatus(finder, "hello.txt", "clean");
-    expect(hello).toBeDefined();
-    expect(hello?.gitStatus).toBe("clean");
-
-    const main = await waitForFileStatus(finder, "main.rs", "clean");
-    expect(main).toBeDefined();
-    expect(main?.gitStatus).toBe("clean");
-  });
-
-  test("new untracked file appears with 'untracked' status", async () => {
-    writeFileSync(join(tmpDir, "new_file.ts"), "export const x = 1;\n");
-
-    const newFile = await waitForFileStatus(finder, "new_file.ts", "untracked");
-    expect(newFile).toBeDefined();
-    expect(newFile?.gitStatus).toBe("untracked");
-
-    // Total should now be 4
-    const total = await waitForFileCount(finder, 4);
-    expect(total).toBe(4);
-  });
-
-  test("staging a new file changes status to 'staged_new'", async () => {
-    git(tmpDir, "add", "new_file.ts");
-
-    const newFile = await waitForFileStatus(finder, "new_file.ts", "staged_new");
-    expect(newFile).toBeDefined();
-    expect(newFile?.gitStatus).toBe("staged_new");
-  });
-
-  test("committing makes the file 'clean'", async () => {
-    git(tmpDir, "commit", "-m", "add new_file");
-
-    const newFile = await waitForFileStatus(finder, "new_file.ts", "clean");
-    expect(newFile).toBeDefined();
-    expect(newFile?.gitStatus).toBe("clean");
-  });
-
-  test("modifying a tracked file changes status to 'modified'", async () => {
-    writeFileSync(join(tmpDir, "hello.txt"), "hello world\nupdated content\n");
-
-    const hello = await waitForFileStatus(finder, "hello.txt", "modified");
-    expect(hello).toBeDefined();
-    expect(hello?.gitStatus).toBe("modified");
-  });
-
-  test("staging a modification changes status to 'staged_modified'", async () => {
-    git(tmpDir, "add", "hello.txt");
-
-    const hello = await waitForFileStatus(finder, "hello.txt", "staged_modified");
-    expect(hello).toBeDefined();
-    expect(hello?.gitStatus).toBe("staged_modified");
-  });
-
-  test("committing the modification returns to 'clean'", async () => {
-    git(tmpDir, "commit", "-m", "update hello");
-
-    const hello = await waitForFileStatus(finder, "hello.txt", "clean");
-    expect(hello).toBeDefined();
-    expect(hello?.gitStatus).toBe("clean");
-  });
-
-  test("deleting a file removes it from the index", async () => {
-    unlinkSync(join(tmpDir, "new_file.ts"));
-
-    const gone = await waitForFileGone(finder, "new_file.ts");
-    expect(gone).toBe(true);
-
-    // Total should be back to 3
-    const total = await waitForFileCount(finder, 3);
-    expect(total).toBe(3);
-  });
-
-  test("adding a file in a subdirectory works", async () => {
-    writeFileSync(join(tmpDir, "src", "utils.rs"), "pub fn helper() {}\n");
-
-    const utils = await waitForFileStatus(finder, "utils.rs", "untracked");
-    expect(utils).toBeDefined();
-    expect(utils?.relativePath).toBe("src/utils.rs");
-    expect(utils?.gitStatus).toBe("untracked");
-  });
-
-  test("live grep finds content in a newly added file", async () => {
-    writeFileSync(
-      join(tmpDir, "src", "searchtarget.rs"),
-      'const UNIQUE_NEEDLE: &str = "xylophone_waterfall_97";\n',
-    );
-
-    await waitForFile(finder, "searchtarget.rs");
-
-    const result = await waitForGrep(
-      finder,
-      "xylophone_waterfall_97",
-      { mode: "plain" },
-      (n) => n > 0,
-    );
-    expect(result?.ok).toBe(true);
-    if (!result?.ok) return;
-
-    expect(result.value.totalMatched).toBeGreaterThan(0);
-    const match = result.value.items.find(
-      (m) => m.relativePath === "src/searchtarget.rs",
-    );
-    expect(match).toBeDefined();
-    expect(match!.lineContent).toContain("xylophone_waterfall_97");
-  });
-
-  test("live grep no longer finds content after file is deleted", async () => {
-    unlinkSync(join(tmpDir, "src", "searchtarget.rs"));
-
-    const result = await waitForGrep(
-      finder,
-      "xylophone_waterfall_97",
-      { mode: "plain" },
-      (n) => n === 0,
-    );
-    expect(result?.ok).toBe(true);
-    if (!result?.ok) return;
-
-    expect(result.value.totalMatched).toBe(0);
-    expect(result.value.items.length).toBe(0);
-  });
-
-  test("file in a newly created directory is discoverable", async () => {
-    // Create a brand-new directory that didn't exist during the initial scan,
-    // then add a file inside it. The watcher must dynamically pick up the new
-    // directory and index the file.
-    mkdirSync(join(tmpDir, "lib"));
-    writeFileSync(
-      join(tmpDir, "lib", "helpers.ts"),
-      "export function add(a: number, b: number) { return a + b; }\n",
-    );
-
-    const helpers = await waitForFile(finder, "helpers.ts");
-    expect(helpers).toBeDefined();
-    expect(helpers?.relativePath).toBe("lib/helpers.ts");
-  });
-
-  test("files in gitignored directories are not indexed", async () => {
-    // Commit a .gitignore rule first so it's established repo state before
-    // the ignored directory is created. This tests the watch-level filtering
-    // (is_path_ignored in the debouncer callback), not a rescan triggered
-    // by a .gitignore change.
-    writeFileSync(join(tmpDir, ".gitignore"), "build_output/\n");
-    git(tmpDir, "add", ".gitignore");
-    git(tmpDir, "commit", "-m", "add gitignore");
-
-    // Wait for the watcher to settle after the commit.
-    await waitForFile(finder, ".gitignore");
-
-    // Now create the ignored directory and add a file inside it.
-    mkdirSync(join(tmpDir, "build_output"));
-    writeFileSync(join(tmpDir, "build_output", "artifact.bin"), "should not appear\n");
-
-    // Create a non-ignored file as a synchronisation barrier — once it's
-    // indexed, the watcher has processed the same batch of events.
-    writeFileSync(join(tmpDir, "canary.txt"), "visible\n");
-    const canary = await waitForFile(finder, "canary.txt");
-    expect(canary).toBeDefined();
-
-    // The ignored file must NOT appear in the index.
-    const artifact = findFile(finder, "artifact.bin");
-    expect(artifact).toBeUndefined();
-  });
-
-  test("full add-commit cycle for subdirectory file", async () => {
-    git(tmpDir, "add", "src/utils.rs");
-
-    let utils = await waitForFileStatus(finder, "utils.rs", "staged_new");
-    expect(utils).toBeDefined();
-    expect(utils?.gitStatus).toBe("staged_new");
-
-    git(tmpDir, "commit", "-m", "add utils");
-
-    utils = await waitForFileStatus(finder, "utils.rs", "clean");
-    expect(utils).toBeDefined();
-    expect(utils?.gitStatus).toBe("clean");
-  });
-});

package/src/index.test.ts

@@ -1,503 +0,0 @@
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import fs from "node:fs";
-import path from "node:path";
-import { findBinary } from "./download";
-import { FileFinder } from "./index";
-import { getLibExtension, getLibFilename, getTriple } from "./platform";
-
-// Cross-platform path normalization helpers
-const normalizePath = (path: string | null | undefined): string | null => {
-  if (!path) return null;
-  // Convert backslashes to forward slashes for consistent comparison
-  return path.replace(/\\/g, "/");
-};
-
-const testDir = process.cwd();
-
-describe("Platform Detection", () => {
-  test("getTriple returns valid triple", () => {
-    const triple = getTriple();
-    expect(triple).toMatch(
-      /^(x86_64|aarch64|arm)-(apple-darwin|unknown-linux-(gnu|musl)|pc-windows-msvc)$/,
-    );
-  });
-
-  test("getLibExtension returns correct extension", () => {
-    const ext = getLibExtension();
-    const platform = process.platform;
-
-    if (platform === "darwin") {
-      expect(ext).toBe("dylib");
-    } else if (platform === "win32") {
-      expect(ext).toBe("dll");
-    } else {
-      expect(ext).toBe("so");
-    }
-  });
-
-  test("getLibFilename returns correct filename", () => {
-    const filename = getLibFilename();
-    const ext = getLibExtension();
-
-    if (process.platform === "win32") {
-      expect(filename).toBe(`fff_c.${ext}`);
-    } else {
-      expect(filename).toBe(`libfff_c.${ext}`);
-    }
-  });
-});
-
-describe("Binary Detection", () => {
-  test("findBinary returns a path", () => {
-    const path = findBinary();
-    expect(path).not.toBeNull();
-  });
-});
-
-describe("FileFinder - Health Check", () => {
-  test("healthCheckStatic works without an instance", () => {
-    const result = FileFinder.healthCheckStatic();
-    expect(result.ok).toBe(true);
-
-    if (result.ok) {
-      expect(result.value.version).toBeDefined();
-      expect(result.value.git.available).toBe(true);
-      expect(result.value.filePicker.initialized).toBe(false);
-    }
-  });
-});
-
-describe("FileFinder - Full Lifecycle", () => {
-  let finder: FileFinder;
-
-  beforeAll(() => {
-    const result = FileFinder.create({ basePath: testDir });
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      finder = result.value;
-    }
-  });
-
-  afterAll(() => {
-    finder?.destroy();
-  });
-
-  test("create succeeds with valid path", () => {
-    expect(finder).toBeDefined();
-    expect(finder.isDestroyed).toBe(false);
-  });
-
-  test("isScanning returns a boolean", () => {
-    const scanning = finder.isScanning();
-    expect(typeof scanning).toBe("boolean");
-  });
-
-  test("getScanProgress returns valid data", () => {
-    const result = finder.getScanProgress();
-    expect(result.ok).toBe(true);
-
-    if (result.ok) {
-      expect(typeof result.value.scannedFilesCount).toBe("number");
-      expect(typeof result.value.isScanning).toBe("boolean");
-    }
-  });
-
-  test("waitForScanBlocking completes", () => {
-    // Small timeout - scan should be fast or already done
-    const result = finder.waitForScanBlocking(500);
-    expect(result.ok).toBe(true);
-  });
-
-  test("search with empty query returns all files", () => {
-    // First check scan progress to see if files were indexed
-    const progress = finder.getScanProgress();
-    if (progress.ok) {
-    }
-
-    const result = finder.fileSearch("");
-    expect(result.ok).toBe(true);
-
-    if (result.ok) {
-      if (result.value.items.length > 0) {
-        // Log first few paths to see format on Windows
-        // Items are strings (file paths), not objects
-        const _samplePaths = result.value.items
-          .slice(0, 3)
-          .map((item) =>
-            normalizePath(typeof item === "string" ? item : item.relativePath),
-          );
-      }
-      // Empty query should return files (frecency-sorted)
-      expect(result.value.totalFiles).toBeGreaterThan(0);
-    } else {
-    }
-  });
-
-  test("search returns a valid result structure", () => {
-    const result = finder.fileSearch("Cargo.toml");
-    expect(result.ok).toBe(true);
-
-    if (result.ok) {
-      expect(typeof result.value.totalMatched).toBe("number");
-      expect(typeof result.value.totalFiles).toBe("number");
-      expect(Array.isArray(result.value.items)).toBe(true);
-      expect(Array.isArray(result.value.scores)).toBe(true);
-    }
-  });
-
-  test("search returns empty for non-matching query", () => {
-    const result = finder.fileSearch("xyznonexistentfilenamexyz123456");
-    expect(result.ok).toBe(true);
-
-    if (result.ok) {
-      expect(result.value.totalMatched).toBe(0);
-      expect(result.value.items.length).toBe(0);
-    }
-  });
-
-  test("search respects pageSize option", () => {
-    const result = finder.fileSearch("ts", { pageSize: 3 });
-    expect(result.ok).toBe(true);
-
-    if (result.ok) {
-      expect(result.value.items.length).toBeLessThanOrEqual(3);
-    }
-  });
-
-  test("glob filters by extension via raw pattern", () => {
-    const result = finder.glob("**/*.ts", { pageSize: 50 });
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value.items.length).toBeGreaterThan(0);
-      for (const item of result.value.items) {
-        expect(item.relativePath.endsWith(".ts")).toBe(true);
-      }
-    }
-  });
-
-  test("glob returns empty result for non-matching pattern", () => {
-    const result = finder.glob("**/this-extension-does-not-exist-anywhere.zzz");
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value.items.length).toBe(0);
-    }
-  });
-
-  test("glob rejects empty pattern", () => {
-    const result = finder.glob("");
-    expect(result.ok).toBe(false);
-  });
-
-  test("glob respects pageSize", () => {
-    const result = finder.glob("**/*.ts", { pageSize: 2 });
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value.items.length).toBeLessThanOrEqual(2);
-    }
-  });
-
-  test("glob pageIndex offsets results", () => {
-    // pageIndex is a raw item offset (not a page-count multiplier). Verify
-    // by skipping the first item and checking the second result begins
-    // where page0[1] left off.
-    const page0 = finder.glob("**/*.ts", { pageSize: 5, pageIndex: 0 });
-    const page1 = finder.glob("**/*.ts", { pageSize: 5, pageIndex: 1 });
-    expect(page0.ok).toBe(true);
-    expect(page1.ok).toBe(true);
-    if (
-      page0.ok &&
-      page1.ok &&
-      page0.value.items.length > 1 &&
-      page1.value.items.length > 0
-    ) {
-      expect(page1.value.items[0]!.relativePath).toBe(page0.value.items[1]!.relativePath);
-    }
-  });
-
-  test("glob directory-prefix pattern matches only that subtree", () => {
-    const result = finder.glob("src/**/*.ts", { pageSize: 100 });
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      for (const item of result.value.items) {
-        expect(item.relativePath.startsWith("src/")).toBe(true);
-        expect(item.relativePath.endsWith(".ts")).toBe(true);
-      }
-    }
-  });
-
-  test("glob result items carry expected fields", () => {
-    const result = finder.glob("**/*.ts", { pageSize: 1 });
-    expect(result.ok).toBe(true);
-    if (result.ok && result.value.items.length > 0) {
-      const item = result.value.items[0];
-      expect(typeof item.relativePath).toBe("string");
-      expect(typeof item.fileName).toBe("string");
-      expect(item.relativePath.length).toBeGreaterThan(0);
-    }
-  });
-
-  test("glob literal extension pattern (no leading **) still filters", () => {
-    const result = finder.glob("*.ts", { pageSize: 100 });
-    expect(result.ok).toBe(true);
-    // Don't assert non-zero — depends on whether top-level .ts files exist.
-    // Just assert all returned items match.
-    if (result.ok) {
-      for (const item of result.value.items) {
-        expect(item.relativePath.endsWith(".ts")).toBe(true);
-      }
-    }
-  });
-
-  test("grep plain text returns matching lines", () => {
-    const result = finder.grep("fff-core", {
-      mode: "plain",
-    });
-    expect(result.ok).toBe(true);
-
-    if (result.ok) {
-      if (result.value.items.length > 0) {
-        // Log sample match to verify content on Windows
-        const first = result.value.items[0];
-        const _normalizedPath = normalizePath(first.relativePath);
-      }
-
-      expect(result.value.totalMatched).toBeGreaterThan(0);
-      expect(result.value.items.length).toBeGreaterThan(0);
-
-      const first = result.value.items[0];
-      expect(typeof first.relativePath).toBe("string");
-      // Normalize path for cross-platform validation
-      const normalizedFirstPath = normalizePath(first.relativePath);
-      expect(normalizedFirstPath).toBeTruthy();
-      expect(typeof first.lineNumber).toBe("number");
-      expect(first.lineNumber).toBeGreaterThan(0);
-      expect(typeof first.lineContent).toBe("string");
-      expect(first.lineContent.toLowerCase()).toContain("fff-core");
-      expect(Array.isArray(first.matchRanges)).toBe(true);
-      expect(first.matchRanges.length).toBeGreaterThan(0);
-
-      expect(typeof result.value.totalFilesSearched).toBe("number");
-      expect(typeof result.value.totalFiles).toBe("number");
-      expect(typeof result.value.filteredFileCount).toBe("number");
-    } else {
-    }
-  });
-
-  test("grep respects pageSize option", () => {
-    // Cap to one match per file so pageSize bounds the total deterministically.
-    const unbounded = finder.grep("import", {
-      mode: "plain",
-      maxMatchesPerFile: 1,
-    });
-    expect(unbounded.ok).toBe(true);
-    if (!unbounded.ok) return;
-    expect(unbounded.value.items.length).toBeGreaterThan(2);
-
-    const limited = finder.grep("import", {
-      mode: "plain",
-      maxMatchesPerFile: 1,
-      pageSize: 2,
-    });
-    expect(limited.ok).toBe(true);
-    if (!limited.ok) return;
-    expect(limited.value.items.length).toBeLessThanOrEqual(2);
-    expect(limited.value.items.length).toBeLessThan(unbounded.value.items.length);
-    expect(limited.value.nextCursor).not.toBeNull();
-  });
-
-  test("grep fuzzy mode returns results with scores", () => {
-    // Intentional typo: "depdnency" instead of "dependency" to exercise fuzzy matching
-    const result = finder.grep("depdnency", {
-      mode: "fuzzy",
-    });
-    expect(result.ok).toBe(true);
-
-    if (result.ok) {
-      expect(result.value.totalMatched).toBeGreaterThan(0);
-      expect(result.value.items.length).toBeGreaterThan(0);
-
-      const first = result.value.items[0];
-      expect(typeof first.relativePath).toBe("string");
-      // Normalize path for cross-platform validation
-      const normalizedFirstPath = normalizePath(first.relativePath);
-      expect(normalizedFirstPath).toBeTruthy();
-      expect(typeof first.lineNumber).toBe("number");
-      expect(typeof first.lineContent).toBe("string");
-      // Fuzzy mode should produce a fuzzyScore on each match
-      expect(typeof first.fuzzyScore).toBe("number");
-    }
-  });
-
-  test("healthCheck shows initialized state", () => {
-    const result = finder.healthCheck();
-    expect(result.ok).toBe(true);
-
-    if (result.ok) {
-      expect(result.value.filePicker.initialized).toBe(true);
-      expect(result.value.filePicker.basePath).toBeDefined();
-      // Normalize basePath for cross-platform comparison
-      const normalizedBasePath = normalizePath(result.value.filePicker.basePath || "");
-      const normalizedTestDir = normalizePath(testDir);
-      expect(normalizedBasePath).toBe(normalizedTestDir);
-      expect(typeof result.value.filePicker.indexedFiles).toBe("number");
-    }
-  });
-
-  test("healthCheck detects git repository", () => {
-    const result = finder.healthCheck(testDir);
-    expect(result.ok).toBe(true);
-
-    if (result.ok) {
-      expect(result.value.git.available).toBe(true);
-      expect(typeof result.value.git.repositoryFound).toBe("boolean");
-    }
-  });
-
-  test("destroy and re-create works", () => {
-    finder.destroy();
-    expect(finder.isDestroyed).toBe(true);
-
-    const result = FileFinder.create({ basePath: testDir });
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      finder = result.value;
-    }
-    expect(finder.isDestroyed).toBe(false);
-  });
-
-  test("multiple instances can coexist", () => {
-    const result2 = FileFinder.create({ basePath: testDir });
-    expect(result2.ok).toBe(true);
-
-    if (result2.ok) {
-      const finder2 = result2.value;
-
-      // Both should work independently
-      const search1 = finder.fileSearch("Cargo");
-      const search2 = finder2.fileSearch("Cargo");
-
-      expect(search1.ok).toBe(true);
-      expect(search2.ok).toBe(true);
-
-      // Destroying one should not affect the other
-      finder2.destroy();
-
-      const search3 = finder.fileSearch("Cargo");
-      expect(search3.ok).toBe(true);
-    }
-  });
-});
-
-describe("FileFinder - Directory Search", () => {
-  let finder: FileFinder;
-  const tmpDir = path.join(testDir, "__test_dirs__");
-  const sep = path.sep;
-
-  beforeAll(() => {
-    fs.mkdirSync(path.join(tmpDir, "alpha", "nested"), { recursive: true });
-    fs.mkdirSync(path.join(tmpDir, "beta"), { recursive: true });
-    fs.writeFileSync(path.join(tmpDir, "alpha", "file.txt"), "x");
-    fs.writeFileSync(path.join(tmpDir, "alpha", "nested", "deep.txt"), "x");
-    fs.writeFileSync(path.join(tmpDir, "beta", "file.txt"), "x");
-
-    const result = FileFinder.create({ basePath: testDir });
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      finder = result.value;
-    }
-    finder.waitForScanBlocking(5000);
-  });
-
-  afterAll(() => {
-    finder?.destroy();
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  test("known directories are returned with correct paths", () => {
-    const result = finder.directorySearch("__test_dirs__");
-    expect(result.ok).toBe(true);
-    if (!result.ok) return;
-
-    const paths = result.value.items.map((i) => i.relativePath);
-    expect(paths).toContain(`__test_dirs__${sep}alpha${sep}`);
-    expect(paths).toContain(`__test_dirs__${sep}beta${sep}`);
-    expect(paths).toContain(`__test_dirs__${sep}alpha${sep}nested${sep}`);
-  });
-
-  test("nested directory uses native separators and correct dirName", () => {
-    const result = finder.directorySearch("nested");
-    expect(result.ok).toBe(true);
-    if (!result.ok) return;
-
-    const nested = result.value.items.find((i) => i.relativePath.includes("nested"));
-    expect(nested).toBeDefined();
-    expect(nested!.relativePath).toBe(`__test_dirs__${sep}alpha${sep}nested${sep}`);
-    expect(nested!.dirName).toBe(`nested${sep}`);
-  });
-});
-
-describe("FileFinder - Error Handling", () => {
-  test("search fails on destroyed instance", () => {
-    const createResult = FileFinder.create({ basePath: testDir });
-    expect(createResult.ok).toBe(true);
-    if (!createResult.ok) return;
-
-    const f = createResult.value;
-    f.destroy();
-
-    const result = f.fileSearch("test");
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error).toContain("destroyed");
-    }
-  });
-
-  test("getScanProgress fails on destroyed instance", () => {
-    const createResult = FileFinder.create({ basePath: testDir });
-    expect(createResult.ok).toBe(true);
-    if (!createResult.ok) return;
-
-    const f = createResult.value;
-    f.destroy();
-
-    const result = f.getScanProgress();
-    expect(result.ok).toBe(false);
-  });
-
-  test("create fails with invalid path", () => {
-    // Use a cross-platform invalid path
-    const invalidPath =
-      process.platform === "win32"
-        ? "C:\\nonexistent\\path\\that\\does\\not\\exist"
-        : "/nonexistent/path/that/does/not/exist";
-
-    const result = FileFinder.create({
-      basePath: invalidPath,
-    });
-
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error).toContain("Failed");
-    }
-  });
-});
-
-describe("Result Type Helpers", () => {
-  test("ok helper creates success result", async () => {
-    const { ok } = await import("./fff-api");
-    const result = ok(42);
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value).toBe(42);
-    }
-  });
-
-  test("err helper creates error result", async () => {
-    const { err } = await import("./fff-api");
-    const result = err<number>("something went wrong");
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error).toBe("something went wrong");
-    }
-  });
-});