@edxeth/fff-node 0.7.2-edxeth.0

package/dist/src/ffi.js

@@ -0,0 +1,1141 @@
+/**
+ * Node.js FFI bindings for the fff-c native library using ffi-rs
+ *
+ * This module uses ffi-rs to call into the Rust C library.
+ * All functions follow the Result pattern for error handling.
+ *
+ * The API is instance-based: `ffiCreate` returns an opaque handle that must
+ * be passed to all subsequent calls and freed with `ffiDestroy`.
+ *
+ * ## Memory management
+ *
+ * Every `fff_*` function returning `*mut FffResult` allocates with Rust's Box.
+ * We MUST call `fff_free_result` to properly deallocate (not libc::free).
+ *
+ * ## FffResult struct reading
+ *
+ * The FffResult struct layout (#[repr(C)]):
+ *   offset  0: success (bool, 1 byte + 7 padding)
+ *   offset  8: data pointer (8 bytes) - *mut c_char (JSON string or null)
+ *   offset 16: error pointer (8 bytes) - *mut c_char (error message or null)
+ *   offset 24: handle pointer (8 bytes) - *mut c_void (instance handle or null)
+ *
+ * ## Two-step approach for reading + freeing
+ *
+ * ffi-rs auto-dereferences struct retType pointers, losing the original pointer.
+ * We solve this by:
+ * 1. Calling the C function with `retType: DataType.External` to get the raw pointer
+ * 2. Using `restorePointer` to read the struct fields from the raw pointer
+ * 3. Calling `fff_free_result` with the original raw pointer
+ *
+ * ## Null pointer detection
+ *
+ * `isNullPointer` from ffi-rs correctly detects null C pointers wrapped as
+ * V8 External objects. We use this instead of truthy checks.
+ */
+import { close, DataType, isNullPointer, load, open, restorePointer, wrapPointer, } from "ffi-rs";
+import { findBinary } from "./binary.js";
+import { createGrepCursor, err } from "./types.js";
+const LIBRARY_KEY = "fff_c";
+/** Grep mode constants matching the C API (u8). */
+const GREP_MODE_PLAIN = 0;
+const GREP_MODE_REGEX = 1;
+const GREP_MODE_FUZZY = 2;
+/** Map string mode to u8 */
+function grepModeToU8(mode) {
+    switch (mode) {
+        case "regex":
+            return GREP_MODE_REGEX;
+        case "fuzzy":
+            return GREP_MODE_FUZZY;
+        default:
+            return GREP_MODE_PLAIN;
+    }
+}
+// Track whether the library is loaded
+let isLoaded = false;
+/**
+ * Struct type definition for FffResult used with restorePointer.
+ *
+ * Uses U8 for the bool success field (correct alignment with ffi-rs).
+ * Uses External for ALL pointer fields to avoid hangs on null char* pointers
+ * (ffi-rs hangs when trying to read DataType.String from null char*).
+ */
+const FFF_RESULT_STRUCT = {
+    success: DataType.U8,
+    error: DataType.External,
+    handle: DataType.External,
+    int_value: DataType.I64,
+};
+/**
+ * Load the native library using ffi-rs
+ */
+function loadLibrary() {
+    if (isLoaded)
+        return;
+    const binaryPath = findBinary();
+    if (!binaryPath) {
+        throw new Error("fff native library not found. Run `npx @ff-labs/fff-node download` or build from source with `cargo build --release -p fff-c`");
+    }
+    open({ library: LIBRARY_KEY, path: binaryPath });
+    isLoaded = true;
+}
+/**
+ * Convert snake_case keys to camelCase recursively
+ */
+function snakeToCamel(obj) {
+    if (obj === null || obj === undefined)
+        return obj;
+    if (typeof obj !== "object")
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map(snakeToCamel);
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const camelKey = key.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+        result[camelKey] = snakeToCamel(value);
+    }
+    return result;
+}
+/**
+ * Read a C string (char*) from an ffi-rs External pointer.
+ *
+ * Uses restorePointer + wrapPointer to dereference the char* and read the
+ * null-terminated string. Returns null if the pointer is null.
+ */
+function readCString(ptr) {
+    if (isNullPointer(ptr))
+        return null;
+    try {
+        const [str] = restorePointer({
+            retType: [DataType.String],
+            paramsValue: wrapPointer([ptr]),
+        });
+        return str;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Call a C function that returns `*mut FffResult` and get both the raw pointer
+ * (for freeing) and the parsed struct fields.
+ *
+ * Step 1: Call function with `DataType.External` retType → raw pointer
+ * Step 2: Use `restorePointer` to read struct fields from the raw pointer
+ */
+function callRaw(funcName, paramsType, paramsValue) {
+    const rawPtr = load({
+        library: LIBRARY_KEY,
+        funcName,
+        retType: DataType.External,
+        paramsType,
+        paramsValue,
+        freeResultMemory: false,
+    });
+    const [structData] = restorePointer({
+        retType: [FFF_RESULT_STRUCT],
+        paramsValue: wrapPointer([rawPtr]),
+    });
+    return { rawPtr, struct: structData };
+}
+/**
+ * Free a FffResult pointer by calling fff_free_result.
+ *
+ * This frees the FffResult struct and its data/error strings using Rust's
+ * Box::from_raw and CString::from_raw. The handle field is NOT freed.
+ */
+function freeResult(resultPtr) {
+    try {
+        load({
+            library: LIBRARY_KEY,
+            funcName: "fff_free_result",
+            retType: DataType.Void,
+            paramsType: [DataType.External],
+            paramsValue: [resultPtr],
+        });
+    }
+    catch {
+        // Ignore cleanup errors
+    }
+}
+/**
+ * Read the FffResult envelope from a raw call. Returns the parsed struct + raw pointer.
+ * On error, frees the result and returns a Result error.
+ */
+function readResultEnvelope(funcName, paramsType, paramsValue) {
+    loadLibrary();
+    const { rawPtr, struct: structData } = callRaw(funcName, paramsType, paramsValue);
+    if (structData.success === 0) {
+        const errorStr = readCString(structData.error);
+        freeResult(rawPtr);
+        return err(errorStr || "Unknown error");
+    }
+    return { rawPtr, struct: structData };
+}
+/** Call a function returning FffResult with void payload. */
+function callVoidResult(funcName, paramsType, paramsValue) {
+    const res = readResultEnvelope(funcName, paramsType, paramsValue);
+    if ("ok" in res)
+        return res;
+    freeResult(res.rawPtr);
+    return { ok: true, value: undefined };
+}
+/** Call a function returning FffResult with int_value payload. */
+function callIntResult(funcName, paramsType, paramsValue) {
+    const res = readResultEnvelope(funcName, paramsType, paramsValue);
+    if ("ok" in res)
+        return res;
+    const value = Number(res.struct.int_value);
+    freeResult(res.rawPtr);
+    return { ok: true, value };
+}
+/** Call a function returning FffResult with bool in int_value. */
+function callBoolResult(funcName, paramsType, paramsValue) {
+    const res = readResultEnvelope(funcName, paramsType, paramsValue);
+    if ("ok" in res)
+        return res;
+    const value = Number(res.struct.int_value) !== 0;
+    freeResult(res.rawPtr);
+    return { ok: true, value };
+}
+/** Call a function returning FffResult with a C string in handle. */
+function callStringResult(funcName, paramsType, paramsValue) {
+    const res = readResultEnvelope(funcName, paramsType, paramsValue);
+    if ("ok" in res)
+        return res;
+    const handlePtr = res.struct.handle;
+    freeResult(res.rawPtr);
+    if (isNullPointer(handlePtr))
+        return { ok: true, value: null };
+    const str = readCString(handlePtr);
+    freeString(handlePtr);
+    return { ok: true, value: str };
+}
+/** Call a function returning FffResult with a JSON string in handle. */
+function callJsonResult(funcName, paramsType, paramsValue) {
+    const res = readResultEnvelope(funcName, paramsType, paramsValue);
+    if ("ok" in res)
+        return res;
+    const handlePtr = res.struct.handle;
+    freeResult(res.rawPtr);
+    if (isNullPointer(handlePtr))
+        return { ok: true, value: undefined };
+    const jsonStr = readCString(handlePtr);
+    freeString(handlePtr);
+    if (jsonStr === null || jsonStr === "")
+        return { ok: true, value: undefined };
+    try {
+        return { ok: true, value: snakeToCamel(JSON.parse(jsonStr)) };
+    }
+    catch {
+        return { ok: true, value: jsonStr };
+    }
+}
+/** Free a C string via fff_free_string. */
+function freeString(ptr) {
+    try {
+        load({
+            library: LIBRARY_KEY,
+            funcName: "fff_free_string",
+            retType: DataType.Void,
+            paramsType: [DataType.External],
+            paramsValue: [ptr],
+        });
+    }
+    catch {
+        // Ignore
+    }
+}
+/**
+ * Create a new file finder instance.
+ */
+export function ffiCreate(basePath, frecencyDbPath, historyDbPath, useUnsafeNoLock, enableMmapCache, enableContentIndexing, watch, aiMode, logFilePath, logLevel, cacheBudgetMaxFiles, cacheBudgetMaxBytes, cacheBudgetMaxFileSize) {
+    loadLibrary();
+    const { rawPtr, struct: structData } = callRaw("fff_create_instance2", [
+        DataType.String, // base_path
+        DataType.String, // frecency_db_path
+        DataType.String, // history_db_path
+        DataType.Boolean, // use_unsafe_no_lock
+        DataType.Boolean, // enable_mmap_cache
+        DataType.Boolean, // enable_content_indexing
+        DataType.Boolean, // watch
+        DataType.Boolean, // ai_mode
+        DataType.String, // log_file_path
+        DataType.String, // log_level
+        DataType.U64, // cache_budget_max_files
+        DataType.U64, // cache_budget_max_bytes
+        DataType.U64, // cache_budget_max_file_size
+    ], [
+        basePath,
+        frecencyDbPath,
+        historyDbPath,
+        useUnsafeNoLock,
+        enableMmapCache,
+        enableContentIndexing,
+        watch,
+        aiMode,
+        logFilePath,
+        logLevel,
+        cacheBudgetMaxFiles,
+        cacheBudgetMaxBytes,
+        cacheBudgetMaxFileSize,
+    ]);
+    const success = structData.success !== 0;
+    try {
+        if (success) {
+            const handle = structData.handle;
+            if (isNullPointer(handle)) {
+                return err("fff_create_instance2 returned null handle");
+            }
+            return { ok: true, value: handle };
+        }
+        else {
+            const errorStr = readCString(structData.error);
+            return err(errorStr || "Unknown error");
+        }
+    }
+    finally {
+        freeResult(rawPtr);
+    }
+}
+/**
+ * Destroy and clean up an instance.
+ */
+export function ffiDestroy(handle) {
+    loadLibrary();
+    load({
+        library: LIBRARY_KEY,
+        funcName: "fff_destroy",
+        retType: DataType.Void,
+        paramsType: [DataType.External],
+        paramsValue: [handle],
+    });
+}
+// ---------------------------------------------------------------------------
+// Struct type definitions for restorePointer (must match #[repr(C)] layout)
+// ---------------------------------------------------------------------------
+const FFF_FILE_ITEM_STRUCT = {
+    relative_path: DataType.External,
+    file_name: DataType.External,
+    git_status: DataType.External,
+    size: DataType.U64,
+    modified: DataType.U64,
+    access_frecency_score: DataType.I64,
+    modification_frecency_score: DataType.I64,
+    total_frecency_score: DataType.I64,
+    is_binary: DataType.U8,
+};
+const FFF_SCORE_STRUCT = {
+    total: DataType.I32,
+    base_score: DataType.I32,
+    filename_bonus: DataType.I32,
+    special_filename_bonus: DataType.I32,
+    frecency_boost: DataType.I32,
+    distance_penalty: DataType.I32,
+    current_file_penalty: DataType.I32,
+    combo_match_boost: DataType.I32,
+    exact_match: DataType.U8,
+    match_type: DataType.External,
+};
+const FFF_SEARCH_RESULT_STRUCT = {
+    items: DataType.External,
+    scores: DataType.External,
+    count: DataType.U32,
+    total_matched: DataType.U32,
+    total_files: DataType.U32,
+    // FffLocation inlined (flattened)
+    location_tag: DataType.U8,
+    location_line: DataType.I32,
+    location_col: DataType.I32,
+    location_end_line: DataType.I32,
+    location_end_col: DataType.I32,
+};
+// FffDirItem struct (#[repr(C)]): char* (8) + char* (8) + i32 (4) + 4 padding = 24 bytes
+const FFF_DIR_ITEM_STRUCT = {
+    relative_path: DataType.External,
+    dir_name: DataType.External,
+    max_access_frecency: DataType.I32,
+};
+const FFF_DIR_SEARCH_RESULT_STRUCT = {
+    items: DataType.External,
+    scores: DataType.External,
+    count: DataType.U32,
+    total_matched: DataType.U32,
+    total_dirs: DataType.U32,
+};
+// FffMixedItem struct (#[repr(C)]): u8 (1) + 7 padding + char* (8) + char* (8) + char* (8)
+//   + u64 (8) + u64 (8) + i64 (8) + i64 (8) + i64 (8) + bool (1) + 7 padding = 80 bytes
+const FFF_MIXED_ITEM_STRUCT = {
+    item_type: DataType.U8,
+    relative_path: DataType.External,
+    display_name: DataType.External,
+    git_status: DataType.External,
+    size: DataType.U64,
+    modified: DataType.U64,
+    access_frecency_score: DataType.I64,
+    modification_frecency_score: DataType.I64,
+    total_frecency_score: DataType.I64,
+    is_binary: DataType.U8,
+};
+const FFF_MIXED_SEARCH_RESULT_STRUCT = {
+    items: DataType.External,
+    scores: DataType.External,
+    count: DataType.U32,
+    total_matched: DataType.U32,
+    total_files: DataType.U32,
+    total_dirs: DataType.U32,
+    // FffLocation inlined (flattened)
+    location_tag: DataType.U8,
+    location_line: DataType.I32,
+    location_col: DataType.I32,
+    location_end_line: DataType.I32,
+    location_end_col: DataType.I32,
+};
+// FffGrepMatch (144 bytes) — ordered by alignment: ptrs, u64s, u32s, u16, bools
+const FFF_GREP_MATCH_STRUCT = {
+    relative_path: DataType.External,
+    file_name: DataType.External,
+    git_status: DataType.External,
+    line_content: DataType.External,
+    match_ranges: DataType.External,
+    context_before: DataType.External,
+    context_after: DataType.External,
+    size: DataType.U64,
+    modified: DataType.U64,
+    total_frecency_score: DataType.I64,
+    access_frecency_score: DataType.I64,
+    modification_frecency_score: DataType.I64,
+    line_number: DataType.U64,
+    byte_offset: DataType.U64,
+    col: DataType.U32,
+    match_ranges_count: DataType.U32,
+    context_before_count: DataType.U32,
+    context_after_count: DataType.U32,
+    fuzzy_score: DataType.U32, // actually u16 in C, but ffi-rs doesn't have U16 — reads as u32 with padding
+    has_fuzzy_score: DataType.U8,
+    is_binary: DataType.U8,
+    is_definition: DataType.U8,
+};
+const FFF_GREP_RESULT_STRUCT = {
+    items: DataType.External,
+    count: DataType.U32,
+    total_matched: DataType.U32,
+    total_files_searched: DataType.U32,
+    total_files: DataType.U32,
+    filtered_file_count: DataType.U32,
+    next_file_offset: DataType.U32,
+    regex_fallback_error: DataType.External,
+};
+const FFF_MATCH_RANGE_STRUCT = {
+    start: DataType.U32,
+    end: DataType.U32,
+};
+// ---------------------------------------------------------------------------
+// Struct reading helpers
+// ---------------------------------------------------------------------------
+function readFileItemFromRaw(raw) {
+    return {
+        relativePath: readCString(raw.relative_path) ?? "",
+        fileName: readCString(raw.file_name) ?? "",
+        gitStatus: readCString(raw.git_status) ?? "",
+        size: Number(raw.size),
+        modified: Number(raw.modified),
+        accessFrecencyScore: Number(raw.access_frecency_score),
+        modificationFrecencyScore: Number(raw.modification_frecency_score),
+        totalFrecencyScore: Number(raw.total_frecency_score),
+    };
+}
+function readScoreFromRaw(raw) {
+    return {
+        total: raw.total,
+        baseScore: raw.base_score,
+        filenameBonus: raw.filename_bonus,
+        specialFilenameBonus: raw.special_filename_bonus,
+        frecencyBoost: raw.frecency_boost,
+        distancePenalty: raw.distance_penalty,
+        currentFilePenalty: raw.current_file_penalty,
+        comboMatchBoost: raw.combo_match_boost,
+        exactMatch: raw.exact_match !== 0,
+        matchType: readCString(raw.match_type) ?? "",
+    };
+}
+function readDirItemFromRaw(raw) {
+    return {
+        relativePath: readCString(raw.relative_path) ?? "",
+        dirName: readCString(raw.dir_name) ?? "",
+        maxAccessFrecency: raw.max_access_frecency,
+    };
+}
+function readMixedItemFromRaw(raw) {
+    if (raw.item_type === 1) {
+        // Directory
+        return {
+            type: "directory",
+            item: {
+                relativePath: readCString(raw.relative_path) ?? "",
+                dirName: readCString(raw.display_name) ?? "",
+                maxAccessFrecency: Number(raw.access_frecency_score),
+            },
+        };
+    }
+    // File (item_type === 0)
+    return {
+        type: "file",
+        item: {
+            relativePath: readCString(raw.relative_path) ?? "",
+            fileName: readCString(raw.display_name) ?? "",
+            gitStatus: readCString(raw.git_status) ?? "",
+            size: Number(raw.size),
+            modified: Number(raw.modified),
+            accessFrecencyScore: Number(raw.access_frecency_score),
+            modificationFrecencyScore: Number(raw.modification_frecency_score),
+            totalFrecencyScore: Number(raw.total_frecency_score),
+        },
+    };
+}
+/**
+ * Call an accessor function that returns a pointer to a struct element,
+ * then read the struct from that pointer.
+ */
+function callAccessor(funcName, resultPtr, index, structDef) {
+    loadLibrary();
+    const elemPtr = load({
+        library: LIBRARY_KEY,
+        funcName,
+        retType: DataType.External,
+        paramsType: [DataType.External, DataType.U32],
+        paramsValue: [resultPtr, index],
+    });
+    const [raw] = restorePointer({
+        retType: [structDef],
+        paramsValue: wrapPointer([elemPtr]),
+    });
+    return raw;
+}
+/**
+ * Offset a pointer by `bytes` using the C API helper.
+ */
+function ptrOffset(base, bytes) {
+    return load({
+        library: LIBRARY_KEY,
+        funcName: "fff_ptr_offset",
+        retType: DataType.External,
+        paramsType: [DataType.External, DataType.U64],
+        paramsValue: [base, bytes],
+    });
+}
+/**
+ * Read a C string array (char**) of `count` elements.
+ */
+function readCStringArray(ptrArray, count) {
+    if (count === 0 || isNullPointer(ptrArray))
+        return [];
+    const result = [];
+    for (let i = 0; i < count; i++) {
+        const elemPtr = ptrOffset(ptrArray, i * 8);
+        const [charPtr] = restorePointer({
+            retType: [DataType.External],
+            paramsValue: [elemPtr],
+        });
+        result.push(readCString(charPtr) ?? "");
+    }
+    return result;
+}
+function readGrepMatchFromRaw(raw) {
+    // Read match_ranges array via pointer offsets
+    const matchRanges = [];
+    for (let i = 0; i < raw.match_ranges_count; i++) {
+        const rangePtr = ptrOffset(raw.match_ranges, i * 8); // FffMatchRange is 8 bytes
+        const [rangeRaw] = restorePointer({
+            retType: [FFF_MATCH_RANGE_STRUCT],
+            paramsValue: wrapPointer([rangePtr]),
+        });
+        matchRanges.push([rangeRaw.start, rangeRaw.end]);
+    }
+    const match = {
+        relativePath: readCString(raw.relative_path) ?? "",
+        fileName: readCString(raw.file_name) ?? "",
+        gitStatus: readCString(raw.git_status) ?? "",
+        lineContent: readCString(raw.line_content) ?? "",
+        size: Number(raw.size),
+        modified: Number(raw.modified),
+        totalFrecencyScore: Number(raw.total_frecency_score),
+        accessFrecencyScore: Number(raw.access_frecency_score),
+        modificationFrecencyScore: Number(raw.modification_frecency_score),
+        isBinary: raw.is_binary !== 0,
+        lineNumber: Number(raw.line_number),
+        col: raw.col,
+        byteOffset: Number(raw.byte_offset),
+        matchRanges,
+    };
+    if (raw.has_fuzzy_score !== 0) {
+        match.fuzzyScore = raw.fuzzy_score;
+    }
+    if (raw.context_before_count > 0) {
+        match.contextBefore = readCStringArray(raw.context_before, raw.context_before_count);
+    }
+    if (raw.context_after_count > 0) {
+        match.contextAfter = readCStringArray(raw.context_after, raw.context_after_count);
+    }
+    if (raw.is_definition !== 0) {
+        match.isDefinition = true;
+    }
+    return match;
+}
+/**
+ * Parse an FffGrepResult from `FffResult.handle`, then free native memory.
+ */
+function parseGrepResult(rawPtr) {
+    loadLibrary();
+    const [envelope] = restorePointer({
+        retType: [FFF_RESULT_STRUCT],
+        paramsValue: wrapPointer([rawPtr]),
+    });
+    const success = envelope.success !== 0;
+    if (!success) {
+        const errorMsg = readCString(envelope.error) || "Unknown error";
+        freeResult(rawPtr);
+        return err(errorMsg);
+    }
+    const handlePtr = envelope.handle;
+    freeResult(rawPtr);
+    if (isNullPointer(handlePtr)) {
+        return err("grep returned null result");
+    }
+    const [gr] = restorePointer({
+        retType: [FFF_GREP_RESULT_STRUCT],
+        paramsValue: wrapPointer([handlePtr]),
+    });
+    const count = gr.count;
+    const regexFallbackError = readCString(gr.regex_fallback_error) ?? undefined;
+    const items = [];
+    for (let i = 0; i < count; i++) {
+        const rawMatch = callAccessor("fff_grep_result_get_match", handlePtr, i, FFF_GREP_MATCH_STRUCT);
+        items.push(readGrepMatchFromRaw(rawMatch));
+    }
+    // Free native grep result
+    load({
+        library: LIBRARY_KEY,
+        funcName: "fff_free_grep_result",
+        retType: DataType.Void,
+        paramsType: [DataType.External],
+        paramsValue: [handlePtr],
+    });
+    const grepResult = {
+        items,
+        totalMatched: gr.total_matched,
+        totalFilesSearched: gr.total_files_searched,
+        totalFiles: gr.total_files,
+        filteredFileCount: gr.filtered_file_count,
+        nextCursor: gr.next_file_offset > 0 ? createGrepCursor(gr.next_file_offset) : null,
+    };
+    if (regexFallbackError) {
+        grepResult.regexFallbackError = regexFallbackError;
+    }
+    return { ok: true, value: grepResult };
+}
+/**
+ * Parse an FffSearchResult from `FffResult.handle`, then free native memory.
+ */
+function parseSearchResult(rawPtr) {
+    loadLibrary();
+    // Read FffResult envelope
+    const [envelope] = restorePointer({
+        retType: [FFF_RESULT_STRUCT],
+        paramsValue: wrapPointer([rawPtr]),
+    });
+    const success = envelope.success !== 0;
+    if (!success) {
+        const errorMsg = readCString(envelope.error) || "Unknown error";
+        freeResult(rawPtr);
+        return err(errorMsg);
+    }
+    const handlePtr = envelope.handle;
+    // Free the FffResult envelope (does NOT free handle)
+    freeResult(rawPtr);
+    if (isNullPointer(handlePtr)) {
+        return err("fff_search returned null search result");
+    }
+    // Read FffSearchResult struct
+    const [sr] = restorePointer({
+        retType: [FFF_SEARCH_RESULT_STRUCT],
+        paramsValue: wrapPointer([handlePtr]),
+    });
+    const count = sr.count;
+    // Read location
+    let location;
+    if (sr.location_tag === 1) {
+        location = { type: "line", line: sr.location_line };
+    }
+    else if (sr.location_tag === 2) {
+        location = { type: "position", line: sr.location_line, col: sr.location_col };
+    }
+    else if (sr.location_tag === 3) {
+        location = {
+            type: "range",
+            start: { line: sr.location_line, col: sr.location_col },
+            end: { line: sr.location_end_line, col: sr.location_end_col },
+        };
+    }
+    // Read items and scores via accessor functions
+    const items = [];
+    const scores = [];
+    for (let i = 0; i < count; i++) {
+        const rawItem = callAccessor("fff_search_result_get_item", handlePtr, i, FFF_FILE_ITEM_STRUCT);
+        items.push(readFileItemFromRaw(rawItem));
+        const rawScore = callAccessor("fff_search_result_get_score", handlePtr, i, FFF_SCORE_STRUCT);
+        scores.push(readScoreFromRaw(rawScore));
+    }
+    // Free native search result
+    load({
+        library: LIBRARY_KEY,
+        funcName: "fff_free_search_result",
+        retType: DataType.Void,
+        paramsType: [DataType.External],
+        paramsValue: [handlePtr],
+    });
+    const result = {
+        items,
+        scores,
+        totalMatched: sr.total_matched,
+        totalFiles: sr.total_files,
+    };
+    if (location) {
+        result.location = location;
+    }
+    return { ok: true, value: result };
+}
+/**
+ * Parse an FffDirSearchResult from `FffResult.handle`, then free native memory.
+ */
+function parseDirSearchResult(rawPtr) {
+    loadLibrary();
+    // Read FffResult envelope
+    const [envelope] = restorePointer({
+        retType: [FFF_RESULT_STRUCT],
+        paramsValue: wrapPointer([rawPtr]),
+    });
+    const success = envelope.success !== 0;
+    if (!success) {
+        const errorMsg = readCString(envelope.error) || "Unknown error";
+        freeResult(rawPtr);
+        return err(errorMsg);
+    }
+    const handlePtr = envelope.handle;
+    // Free the FffResult envelope (does NOT free handle)
+    freeResult(rawPtr);
+    if (isNullPointer(handlePtr)) {
+        return err("fff_search_directories returned null search result");
+    }
+    // Read FffDirSearchResult struct
+    const [sr] = restorePointer({
+        retType: [FFF_DIR_SEARCH_RESULT_STRUCT],
+        paramsValue: wrapPointer([handlePtr]),
+    });
+    const count = sr.count;
+    // Read items and scores via accessor functions
+    const items = [];
+    const scores = [];
+    for (let i = 0; i < count; i++) {
+        const rawItem = callAccessor("fff_dir_search_result_get_item", handlePtr, i, FFF_DIR_ITEM_STRUCT);
+        items.push(readDirItemFromRaw(rawItem));
+        const rawScore = callAccessor("fff_dir_search_result_get_score", handlePtr, i, FFF_SCORE_STRUCT);
+        scores.push(readScoreFromRaw(rawScore));
+    }
+    // Free native dir search result
+    load({
+        library: LIBRARY_KEY,
+        funcName: "fff_free_dir_search_result",
+        retType: DataType.Void,
+        paramsType: [DataType.External],
+        paramsValue: [handlePtr],
+    });
+    return {
+        ok: true,
+        value: {
+            items,
+            scores,
+            totalMatched: sr.total_matched,
+            totalDirs: sr.total_dirs,
+        },
+    };
+}
+/**
+ * Parse an FffMixedSearchResult from `FffResult.handle`, then free native memory.
+ */
+function parseMixedSearchResult(rawPtr) {
+    loadLibrary();
+    // Read FffResult envelope
+    const [envelope] = restorePointer({
+        retType: [FFF_RESULT_STRUCT],
+        paramsValue: wrapPointer([rawPtr]),
+    });
+    const success = envelope.success !== 0;
+    if (!success) {
+        const errorMsg = readCString(envelope.error) || "Unknown error";
+        freeResult(rawPtr);
+        return err(errorMsg);
+    }
+    const handlePtr = envelope.handle;
+    // Free the FffResult envelope (does NOT free handle)
+    freeResult(rawPtr);
+    if (isNullPointer(handlePtr)) {
+        return err("fff_search_mixed returned null search result");
+    }
+    // Read FffMixedSearchResult struct
+    const [sr] = restorePointer({
+        retType: [FFF_MIXED_SEARCH_RESULT_STRUCT],
+        paramsValue: wrapPointer([handlePtr]),
+    });
+    const count = sr.count;
+    // Read location
+    let location;
+    if (sr.location_tag === 1) {
+        location = { type: "line", line: sr.location_line };
+    }
+    else if (sr.location_tag === 2) {
+        location = { type: "position", line: sr.location_line, col: sr.location_col };
+    }
+    else if (sr.location_tag === 3) {
+        location = {
+            type: "range",
+            start: { line: sr.location_line, col: sr.location_col },
+            end: { line: sr.location_end_line, col: sr.location_end_col },
+        };
+    }
+    // Read items and scores via accessor functions
+    const items = [];
+    const scores = [];
+    for (let i = 0; i < count; i++) {
+        const rawItem = callAccessor("fff_mixed_search_result_get_item", handlePtr, i, FFF_MIXED_ITEM_STRUCT);
+        items.push(readMixedItemFromRaw(rawItem));
+        const rawScore = callAccessor("fff_mixed_search_result_get_score", handlePtr, i, FFF_SCORE_STRUCT);
+        scores.push(readScoreFromRaw(rawScore));
+    }
+    // Free native mixed search result
+    load({
+        library: LIBRARY_KEY,
+        funcName: "fff_free_mixed_search_result",
+        retType: DataType.Void,
+        paramsType: [DataType.External],
+        paramsValue: [handlePtr],
+    });
+    const result = {
+        items,
+        scores,
+        totalMatched: sr.total_matched,
+        totalFiles: sr.total_files,
+        totalDirs: sr.total_dirs,
+    };
+    if (location) {
+        result.location = location;
+    }
+    return { ok: true, value: result };
+}
+/**
+ * Perform fuzzy search.
+ */
+export function ffiSearch(handle, query, currentFile, maxThreads, pageIndex, pageSize, comboBoostMultiplier, minComboCount) {
+    loadLibrary();
+    const rawPtr = load({
+        library: LIBRARY_KEY,
+        funcName: "fff_search",
+        retType: DataType.External,
+        paramsType: [
+            DataType.External, // handle
+            DataType.String, // query
+            DataType.String, // current_file
+            DataType.U32, // max_threads
+            DataType.U32, // page_index
+            DataType.U32, // page_size
+            DataType.I32, // combo_boost_multiplier
+            DataType.U32, // min_combo_count
+        ],
+        paramsValue: [
+            handle,
+            query,
+            currentFile,
+            maxThreads,
+            pageIndex,
+            pageSize,
+            comboBoostMultiplier,
+            minComboCount,
+        ],
+        freeResultMemory: false,
+    });
+    return parseSearchResult(rawPtr);
+}
+/**
+ * Perform fuzzy directory search.
+ */
+export function ffiSearchDirectories(handle, query, currentFile, maxThreads, pageIndex, pageSize) {
+    loadLibrary();
+    const rawPtr = load({
+        library: LIBRARY_KEY,
+        funcName: "fff_search_directories",
+        retType: DataType.External,
+        paramsType: [
+            DataType.External, // handle
+            DataType.String, // query
+            DataType.String, // current_file
+            DataType.U32, // max_threads
+            DataType.U32, // page_index
+            DataType.U32, // page_size
+        ],
+        paramsValue: [handle, query, currentFile ?? "", maxThreads, pageIndex, pageSize],
+        freeResultMemory: false,
+    });
+    return parseDirSearchResult(rawPtr);
+}
+/**
+ * Perform mixed (files + directories) fuzzy search.
+ */
+export function ffiSearchMixed(handle, query, currentFile, maxThreads, pageIndex, pageSize, comboBoostMultiplier, minComboCount) {
+    loadLibrary();
+    const rawPtr = load({
+        library: LIBRARY_KEY,
+        funcName: "fff_search_mixed",
+        retType: DataType.External,
+        paramsType: [
+            DataType.External, // handle
+            DataType.String, // query
+            DataType.String, // current_file
+            DataType.U32, // max_threads
+            DataType.U32, // page_index
+            DataType.U32, // page_size
+            DataType.I32, // combo_boost_multiplier
+            DataType.U32, // min_combo_count
+        ],
+        paramsValue: [
+            handle,
+            query,
+            currentFile,
+            maxThreads,
+            pageIndex,
+            pageSize,
+            comboBoostMultiplier,
+            minComboCount,
+        ],
+        freeResultMemory: false,
+    });
+    return parseMixedSearchResult(rawPtr);
+}
+/**
+ * Live grep - search file contents.
+ */
+export function ffiLiveGrep(handle, query, mode, maxFileSize, maxMatchesPerFile, smartCase, fileOffset, pageLimit, timeBudgetMs, beforeContext, afterContext, classifyDefinitions) {
+    loadLibrary();
+    const rawPtr = load({
+        library: LIBRARY_KEY,
+        funcName: "fff_live_grep",
+        retType: DataType.External,
+        paramsType: [
+            DataType.External, // handle
+            DataType.String, // query
+            DataType.U8, // mode
+            DataType.U64, // max_file_size
+            DataType.U32, // max_matches_per_file
+            DataType.Boolean, // smart_case
+            DataType.U32, // file_offset
+            DataType.U32, // page_limit
+            DataType.U64, // time_budget_ms
+            DataType.U32, // before_context
+            DataType.U32, // after_context
+            DataType.Boolean, // classify_definitions
+        ],
+        paramsValue: [
+            handle,
+            query,
+            grepModeToU8(mode),
+            maxFileSize,
+            maxMatchesPerFile,
+            smartCase,
+            fileOffset,
+            pageLimit,
+            timeBudgetMs,
+            beforeContext,
+            afterContext,
+            classifyDefinitions,
+        ],
+        freeResultMemory: false,
+    });
+    return parseGrepResult(rawPtr);
+}
+/**
+ * Multi-pattern grep - Aho-Corasick multi-needle search.
+ */
+export function ffiMultiGrep(handle, patternsJoined, constraints, maxFileSize, maxMatchesPerFile, smartCase, fileOffset, pageLimit, timeBudgetMs, beforeContext, afterContext, classifyDefinitions) {
+    loadLibrary();
+    const rawPtr = load({
+        library: LIBRARY_KEY,
+        funcName: "fff_multi_grep",
+        retType: DataType.External,
+        paramsType: [
+            DataType.External, // handle
+            DataType.String, // patterns_joined
+            DataType.String, // constraints
+            DataType.U64, // max_file_size
+            DataType.U32, // max_matches_per_file
+            DataType.Boolean, // smart_case
+            DataType.U32, // file_offset
+            DataType.U32, // page_limit
+            DataType.U64, // time_budget_ms
+            DataType.U32, // before_context
+            DataType.U32, // after_context
+            DataType.Boolean, // classify_definitions
+        ],
+        paramsValue: [
+            handle,
+            patternsJoined,
+            constraints,
+            maxFileSize,
+            maxMatchesPerFile,
+            smartCase,
+            fileOffset,
+            pageLimit,
+            timeBudgetMs,
+            beforeContext,
+            afterContext,
+            classifyDefinitions,
+        ],
+        freeResultMemory: false,
+    });
+    return parseGrepResult(rawPtr);
+}
+/**
+ * Trigger file scan.
+ */
+export function ffiScanFiles(handle) {
+    return callVoidResult("fff_scan_files", [DataType.External], [handle]);
+}
+/**
+ * Check if scanning.
+ */
+export function ffiIsScanning(handle) {
+    loadLibrary();
+    return load({
+        library: LIBRARY_KEY,
+        funcName: "fff_is_scanning",
+        retType: DataType.Boolean,
+        paramsType: [DataType.External],
+        paramsValue: [handle],
+    });
+}
+/**
+ * Get the base path of the file picker.
+ */
+export function ffiGetBasePath(handle) {
+    return callStringResult("fff_get_base_path", [DataType.External], [handle]);
+}
+// FffScanProgress struct definition
+const FFF_SCAN_PROGRESS_STRUCT = {
+    scanned_files_count: DataType.U64,
+    is_scanning: DataType.U8,
+};
+/**
+ * Get scan progress.
+ */
+export function ffiGetScanProgress(handle) {
+    loadLibrary();
+    const res = readResultEnvelope("fff_get_scan_progress", [DataType.External], [handle]);
+    if ("ok" in res)
+        return res;
+    const handlePtr = res.struct.handle;
+    freeResult(res.rawPtr);
+    if (isNullPointer(handlePtr))
+        return err("scan progress returned null");
+    const [sp] = restorePointer({
+        retType: [FFF_SCAN_PROGRESS_STRUCT],
+        paramsValue: wrapPointer([handlePtr]),
+    });
+    const result = {
+        scannedFilesCount: Number(sp.scanned_files_count),
+        isScanning: sp.is_scanning !== 0,
+    };
+    // Free native scan progress
+    load({
+        library: LIBRARY_KEY,
+        funcName: "fff_free_scan_progress",
+        retType: DataType.Void,
+        paramsType: [DataType.External],
+        paramsValue: [handlePtr],
+    });
+    return { ok: true, value: result };
+}
+/**
+ * Wait for a tree scan to complete.
+ */
+export function ffiWaitForScan(handle, timeoutMs) {
+    return callBoolResult("fff_wait_for_scan", [DataType.External, DataType.U64], [handle, timeoutMs]);
+}
+/**
+ * Restart index in new path.
+ */
+export function ffiRestartIndex(handle, newPath) {
+    return callVoidResult("fff_restart_index", [DataType.External, DataType.String], [handle, newPath]);
+}
+/**
+ * Refresh git status.
+ */
+export function ffiRefreshGitStatus(handle) {
+    return callIntResult("fff_refresh_git_status", [DataType.External], [handle]);
+}
+/**
+ * Track query completion.
+ */
+export function ffiTrackQuery(handle, query, filePath) {
+    return callBoolResult("fff_track_query", [DataType.External, DataType.String, DataType.String], [handle, query, filePath]);
+}
+/**
+ * Get historical query.
+ */
+export function ffiGetHistoricalQuery(handle, offset) {
+    return callStringResult("fff_get_historical_query", [DataType.External, DataType.U64], [handle, offset]);
+}
+/**
+ * Health check.
+ *
+ * `handle` can be null for a limited check (version + git only).
+ * When null, we pass DataType.U64 with value 0 as a null pointer workaround
+ * since ffi-rs does not accept `null` for External parameters.
+ */
+export function ffiHealthCheck(handle, testPath) {
+    if (handle === null) {
+        // Use U64(0) as a null pointer since ffi-rs rejects null for External params
+        return callJsonResult("fff_health_check", [DataType.U64, DataType.String], [0, testPath]);
+    }
+    return callJsonResult("fff_health_check", [DataType.External, DataType.String], [handle, testPath]);
+}
+/**
+ * Ensure the library is loaded.
+ *
+ * Loads the native library from the platform-specific npm package
+ * or a local dev build. Throws if the binary is not found.
+ */
+export function ensureLoaded() {
+    loadLibrary();
+}
+/**
+ * Check if the library is available.
+ */
+export function isAvailable() {
+    try {
+        loadLibrary();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Close the library and release ffi-rs resources.
+ * Call this when completely done with the library.
+ */
+export function closeLibrary() {
+    if (isLoaded) {
+        close(LIBRARY_KEY);
+        isLoaded = false;
+    }
+}
+//# sourceMappingURL=ffi.js.map