feat(sdk): Expose create_instance2 function with more potions

dmtrKovalenko · dmtrKovalenko · commit eee1053b7fc1 · 2026-04-22T11:55:14.000-07:00
This includes log path and content cache budget
diff --git a/crates/fff-c/include/fff.h b/crates/fff-c/include/fff.h
diff --git a/crates/fff-c/src/lib.rs b/crates/fff-c/src/lib.rs
@@ -104,26 +104,76 @@ fn default_i32(val: i32, default: i32) -> i32 {
     if val == 0 { default } else { val }
 }
 
-/// Create a new file finder instance.
+/// Create a new file finder instance (legacy signature).
+///
+/// @deprecated prefer `fff_create_instance2`, which also exposes log file and
+/// cache-budget configuration. This function delegates to `fff_create_instance2`
+/// with NULL log paths and auto cache budget, so behaviour is unchanged.
+///
+/// ## Safety
+/// See `fff_create_instance2`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn fff_create_instance(
+    base_path: *const c_char,
+    frecency_db_path: *const c_char,
+    history_db_path: *const c_char,
+    use_unsafe_no_lock: bool,
+    enable_mmap_cache: bool,
+    enable_content_indexing: bool,
+    watch: bool,
+    ai_mode: bool,
+) -> *mut FffResult {
+    unsafe {
+        fff_create_instance2(
+            base_path,
+            frecency_db_path,
+            history_db_path,
+            use_unsafe_no_lock,
+            enable_mmap_cache,
+            enable_content_indexing,
+            watch,
+            ai_mode,
+            std::ptr::null(),
+            std::ptr::null(),
+            0,
+            0,
+            0,
+        )
+    }
+}
+
+/// Create a new file finder instance (v2, with full options).
 ///
 /// Returns an opaque pointer that must be passed to all other `fff_*` calls
 /// and eventually freed with `fff_destroy`.
 ///
 /// # Parameters
 ///
-/// * `base_path`                – directory to index (required)
-/// * `frecency_db_path`         – path to frecency LMDB database (NULL/empty to skip)
-/// * `history_db_path`          – path to query history LMDB database (NULL/empty to skip)
-/// * `use_unsafe_no_lock`       – use MDB_NOLOCK for LMDB (useful in single-process setups)
-/// * `enable_mmap_cache`        – pre-populate mmap caches after the initial scan
-/// * `enable_content_indexing`  – build content index after the initial scan
-/// * `watch`                    – start a background file-system watcher for live updates
-/// * `ai_mode`                  – enable AI-agent optimizations (auto-track frecency on modifications)
+/// * `base_path`                   – directory to index (required)
+/// * `frecency_db_path`            – frecency LMDB database path (NULL/empty to skip)
+/// * `history_db_path`             – query history LMDB database path (NULL/empty to skip)
+/// * `use_unsafe_no_lock`          – use MDB_NOLOCK for LMDB (useful in single-process setups)
+/// * `enable_mmap_cache`           – pre-populate mmap caches after the initial scan
+/// * `enable_content_indexing`     – build content index after the initial scan
+/// * `watch`                       – start a background file-system watcher for live updates
+/// * `ai_mode`                     – enable AI-agent optimizations
+/// * `log_file_path`               – tracing log file path (NULL/empty to skip).
+///   Only the first successful call in a process installs the subscriber;
+///   subsequent calls are no-ops at the log layer.
+/// * `log_level`                   – `"trace"`, `"debug"`, `"info"`, `"warn"`, `"error"`
+///   (NULL/empty defaults to `"info"`). Ignored when `log_file_path` is not set.
+/// * `cache_budget_max_files`      – content cache file-count cap (0 = auto)
+/// * `cache_budget_max_bytes`      – content cache byte cap (0 = auto)
+/// * `cache_budget_max_file_size`  – per-file byte cap (0 = auto)
+///
+/// When all three `cache_budget_*` values are 0 the budget is auto-computed
+/// from repo size after the initial scan. Otherwise an explicit budget is
+/// used: any field left at 0 falls back to its `unlimited()` default.
 ///
 /// ## Safety
 /// String parameters must be valid null-terminated UTF-8 or NULL.
 #[unsafe(no_mangle)]
-pub unsafe extern "C" fn fff_create_instance(
+pub unsafe extern "C" fn fff_create_instance2(
     base_path: *const c_char,
     frecency_db_path: *const c_char,
     history_db_path: *const c_char,
@@ -132,12 +182,24 @@ pub unsafe extern "C" fn fff_create_instance(
     enable_content_indexing: bool,
     watch: bool,
     ai_mode: bool,
+    log_file_path: *const c_char,
+    log_level: *const c_char,
+    cache_budget_max_files: u64,
+    cache_budget_max_bytes: u64,
+    cache_budget_max_file_size: u64,
 ) -> *mut FffResult {
     let base_path_str = match unsafe { cstr_to_str(base_path) } {
         Some(s) if !s.is_empty() => s.to_string(),
         _ => return FffResult::err("base_path is null or empty"),
     };
 
+    if let Some(log_path) = unsafe { optional_cstr(log_file_path) } {
+        let level = unsafe { optional_cstr(log_level) };
+        if let Err(e) = fff::log::init_tracing(log_path, level) {
+            return FffResult::err(&format!("Failed to init tracing: {}", e));
+        }
+    }
+
     let frecency_path = unsafe { optional_cstr(frecency_db_path) }.map(|s| s.to_string());
     let history_path = unsafe { optional_cstr(history_db_path) }.map(|s| s.to_string());
 
@@ -185,6 +247,12 @@ pub unsafe extern "C" fn fff_create_instance(
         FFFMode::Neovim
     };
 
+    let cache_budget = fff::ContentCacheBudget::from_overrides(
+        cache_budget_max_files as usize,
+        cache_budget_max_bytes,
+        cache_budget_max_file_size,
+    );
+
     // Initialize file picker (writes directly into shared_picker)
     if let Err(e) = FilePicker::new_with_shared_state(
         shared_picker.clone(),
@@ -195,7 +263,7 @@ pub unsafe extern "C" fn fff_create_instance(
             enable_content_indexing,
             watch,
             mode,
-            cache_budget: None,
+            cache_budget,
         },
     ) {
         return FffResult::err(&format!("Failed to init file picker: {}", e));
diff --git a/crates/fff-core/src/types.rs b/crates/fff-core/src/types.rs
@@ -722,6 +722,31 @@ impl ContentCacheBudget {
         }
     }
 
+    /// Build a budget from caller-supplied overrides.
+    ///
+    /// Each argument is a cap; `0` means "use the library default for that
+    /// cap" (inherits from [`Self::default`], which is `new_for_repo(30_000)`).
+    /// Returns `None` when every cap is `0`, signalling to the picker that it
+    /// should auto-size the budget from the final scanned file count rather
+    /// than applying an explicit override.
+    pub fn from_overrides(max_files: usize, max_bytes: u64, max_file_size: u64) -> Option<Self> {
+        if max_files == 0 && max_bytes == 0 && max_file_size == 0 {
+            return None;
+        }
+
+        let mut budget = Self::default();
+        if max_files > 0 {
+            budget.max_files = max_files;
+        }
+        if max_bytes > 0 {
+            budget.max_bytes = max_bytes;
+        }
+        if max_file_size > 0 {
+            budget.max_file_size = max_file_size;
+        }
+        Some(budget)
+    }
+
     pub fn reset(&self) {
         self.cached_count.store(0, Ordering::Relaxed);
         self.cached_bytes.store(0, Ordering::Relaxed);
diff --git a/packages/fff-bun/src/ffi.ts b/packages/fff-bun/src/ffi.ts
@@ -44,7 +44,7 @@ function grepModeToU8(mode?: string): number {
 }
 
 const ffiDefinition = {
-  fff_create_instance: {
+  fff_create_instance2: {
     args: [
       FFIType.cstring, // base_path
       FFIType.cstring, // frecency_db_path
@@ -54,6 +54,11 @@ const ffiDefinition = {
       FFIType.bool, // enable_content_indexing
       FFIType.bool, // watch
       FFIType.bool, // ai_mode
+      FFIType.cstring, // log_file_path
+      FFIType.cstring, // log_level
+      FFIType.u64, // cache_budget_max_files
+      FFIType.u64, // cache_budget_max_bytes
+      FFIType.u64, // cache_budget_max_file_size
     ],
     returns: FFIType.ptr,
   },
@@ -425,9 +430,14 @@ export function ffiCreate(
   enableContentIndexing: boolean,
   watch: boolean,
   aiMode: boolean,
+  logFilePath: string,
+  logLevel: string,
+  cacheBudgetMaxFiles: bigint,
+  cacheBudgetMaxBytes: bigint,
+  cacheBudgetMaxFileSize: bigint,
 ): Result<NativeHandle> {
   const library = loadLibrary();
-  const resultPtr = library.symbols.fff_create_instance(
+  const resultPtr = library.symbols.fff_create_instance2(
     ptr(encodeString(basePath)),
     ptr(encodeString(frecencyDbPath)),
     ptr(encodeString(historyDbPath)),
@@ -436,6 +446,11 @@ export function ffiCreate(
     enableContentIndexing,
     watch,
     aiMode,
+    ptr(encodeString(logFilePath)),
+    ptr(encodeString(logLevel)),
+    cacheBudgetMaxFiles,
+    cacheBudgetMaxBytes,
+    cacheBudgetMaxFileSize,
   );
 
   if (resultPtr === null) {
diff --git a/packages/fff-bun/src/finder.ts b/packages/fff-bun/src/finder.ts
@@ -117,6 +117,11 @@ export class FileFinder {
       !(options.disableContentIndexing ?? options.disableMmapCache ?? false),
       !(options.disableWatch ?? false),
       options.aiMode ?? false,
+      options.logFilePath ?? "",
+      options.logLevel ?? "",
+      BigInt(options.cacheBudgetMaxFiles ?? 0),
+      BigInt(options.cacheBudgetMaxBytes ?? 0),
+      BigInt(options.cacheBudgetMaxFileSize ?? 0),
     );
 
     if (!result.ok) {
diff --git a/packages/fff-bun/src/types.ts b/packages/fff-bun/src/types.ts
@@ -50,6 +50,26 @@ export interface InitOptions {
   disableWatch?: boolean;
   /** enables optimizations for AI agent assistants. Provide as true if running via mcp/agent */
   aiMode?: boolean;
+  /**
+   * Path to the tracing log file. When set, the shared FFF tracing subscriber
+   * is installed on first init and file output is written here. Omit to leave
+   * logging uninitialized.
+   */
+  logFilePath?: string;
+  /**
+   * Log level for the tracing subscriber: "trace", "debug", "info", "warn",
+   * or "error". Defaults to "info". Ignored when `logFilePath` is not set.
+   */
+  logLevel?: "trace" | "debug" | "info" | "warn" | "error";
+  /**
+   * Override for the content cache file-count cap. When omitted, the picker
+   * auto-sizes the budget from the final scanned file count.
+   */
+  cacheBudgetMaxFiles?: number;
+  /** Override for the content cache byte cap. See `cacheBudgetMaxFiles`. */
+  cacheBudgetMaxBytes?: number;
+  /** Override for the per-file byte cap in the content cache. */
+  cacheBudgetMaxFileSize?: number;
 }
 
 /**
diff --git a/packages/fff-node/src/ffi.ts b/packages/fff-node/src/ffi.ts
@@ -334,11 +334,16 @@ export function ffiCreate(
   enableContentIndexing: boolean,
   watch: boolean,
   aiMode: boolean,
+  logFilePath: string,
+  logLevel: string,
+  cacheBudgetMaxFiles: number,
+  cacheBudgetMaxBytes: number,
+  cacheBudgetMaxFileSize: number,
 ): Result<NativeHandle> {
   loadLibrary();
 
   const { rawPtr, struct: structData } = callRaw(
-    "fff_create_instance",
+    "fff_create_instance2",
     [
       DataType.String, // base_path
       DataType.String, // frecency_db_path
@@ -348,6 +353,11 @@ export function ffiCreate(
       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,
@@ -358,6 +368,11 @@ export function ffiCreate(
       enableContentIndexing,
       watch,
       aiMode,
+      logFilePath,
+      logLevel,
+      cacheBudgetMaxFiles,
+      cacheBudgetMaxBytes,
+      cacheBudgetMaxFileSize,
     ],
   );
 
@@ -367,7 +382,7 @@ export function ffiCreate(
     if (success) {
       const handle = structData.handle;
       if (isNullPointer(handle)) {
-        return err("fff_create_instance returned null handle");
+        return err("fff_create_instance2 returned null handle");
       }
       return { ok: true, value: handle };
     } else {
diff --git a/packages/fff-node/src/finder.ts b/packages/fff-node/src/finder.ts
@@ -116,6 +116,11 @@ export class FileFinder {
       !(options.disableContentIndexing ?? options.disableMmapCache ?? false),
       !(options.disableWatch ?? false),
       options.aiMode ?? false,
+      options.logFilePath ?? "",
+      options.logLevel ?? "",
+      options.cacheBudgetMaxFiles ?? 0,
+      options.cacheBudgetMaxBytes ?? 0,
+      options.cacheBudgetMaxFileSize ?? 0,
     );
 
     if (!result.ok) {
diff --git a/packages/fff-node/src/types.ts b/packages/fff-node/src/types.ts
@@ -51,6 +51,26 @@ export interface InitOptions {
   disableWatch?: boolean;
   /** enables optimizations for AI agent assistants. Provide as true if running via mcp/agent */
   aiMode?: boolean;
+  /**
+   * Path to the tracing log file. When set, the shared FFF tracing subscriber
+   * is installed on first init and file output is written here. Omit to leave
+   * logging uninitialized.
+   */
+  logFilePath?: string;
+  /**
+   * Log level for the tracing subscriber: "trace", "debug", "info", "warn",
+   * or "error". Defaults to "info". Ignored when `logFilePath` is not set.
+   */
+  logLevel?: "trace" | "debug" | "info" | "warn" | "error";
+  /**
+   * Override for the content cache file-count cap. When omitted, the picker
+   * auto-sizes the budget from the final scanned file count.
+   */
+  cacheBudgetMaxFiles?: number;
+  /** Override for the content cache byte cap. See `cacheBudgetMaxFiles`. */
+  cacheBudgetMaxBytes?: number;
+  /** Override for the per-file byte cap in the content cache. */
+  cacheBudgetMaxFileSize?: number;
 }
 
 /**
