@ff-labs/fff-bun 0.1.0-nightly.00750c2

package/src/download.ts

@@ -0,0 +1,252 @@
+/**
+ * Binary resolution utilities for fff
+ *
+ * Resolves the native binary from:
+ * 1. Platform-specific npm package (e.g. @ff-labs/fff-bun-darwin-arm64) - primary
+ * 2. Local bin/ directory (legacy or manual download)
+ * 3. Local dev build (target/release or target/debug)
+ * 4. GitHub releases (fallback, requires network)
+ */
+
+import { existsSync, mkdirSync, writeFileSync, chmodSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import {
+  getTriple,
+  getLibExtension,
+  getLibFilename,
+  getNpmPackageName,
+} from "./platform";
+
+const GITHUB_REPO = "dmtrKovalenko/fff.nvim";
+
+/**
+ * Get the current file's directory
+ */
+function getCurrentDir(): string {
+  const url = import.meta.url;
+  if (url.startsWith("file://")) {
+    return dirname(fileURLToPath(url));
+  }
+  return dirname(url);
+}
+
+/**
+ * Get the package root directory
+ */
+function getPackageDir(): string {
+  const currentDir = getCurrentDir();
+  return dirname(currentDir);
+}
+
+/**
+ * Get the directory where binaries are stored (legacy/fallback)
+ */
+export function getBinDir(): string {
+  return join(getPackageDir(), "bin");
+}
+
+/**
+ * Get the full path to the native library in bin/ (legacy/fallback)
+ */
+export function getBinaryPath(): string {
+  const binDir = getBinDir();
+  return join(binDir, getLibFilename());
+}
+
+/**
+ * Check if the binary exists in any known location
+ */
+export function binaryExists(): boolean {
+  return findBinary() !== null;
+}
+
+/**
+ * Try to resolve the binary from the platform-specific npm package.
+ *
+ * When users install @ff-labs/bun, npm/bun automatically installs the matching
+ * optionalDependency (e.g. @ff-labs/fff-bun-darwin-arm64). We resolve the binary
+ * path by requiring that package's package.json and looking for the binary
+ * in the same directory.
+ */
+function resolveFromNpmPackage(): string | null {
+  const packageName = getNpmPackageName();
+
+  try {
+    // Use createRequire to resolve the platform package's location
+    const require = createRequire(join(getPackageDir(), "package.json"));
+    const packageJsonPath = require.resolve(`${packageName}/package.json`);
+    const packageDir = dirname(packageJsonPath);
+    const binaryPath = join(packageDir, getLibFilename());
+
+    if (existsSync(binaryPath)) {
+      return binaryPath;
+    }
+  } catch {
+    // Package not installed - this is expected on unsupported platforms
+    // or when installed without optional dependencies
+  }
+
+  return null;
+}
+
+/**
+ * Get the development binary path (for local development)
+ */
+export function getDevBinaryPath(): string | null {
+  const packageDir = getPackageDir();
+  const workspaceRoot = join(packageDir, "..", "..");
+
+  const possiblePaths = [
+    join(workspaceRoot, "target", "release", getLibFilename()),
+    join(workspaceRoot, "target", "debug", getLibFilename()),
+  ];
+
+  for (const path of possiblePaths) {
+    if (existsSync(path)) {
+      return path;
+    }
+  }
+
+  return null;
+}
+
+function isDevWorkspace(): boolean {
+  const packageDir = getPackageDir();
+  const workspaceRoot = join(packageDir, "..", "..");
+  return existsSync(join(workspaceRoot, "Cargo.toml"));
+}
+
+export function findBinary(): string | null {
+  if (isDevWorkspace()) {
+    // 1. Local bin/ directory (populated by `make prepare-bun`)
+    const installedPath = getBinaryPath();
+    if (existsSync(installedPath)) return installedPath;
+
+    // 2. Local dev build (target/release or target/debug)
+    const devPath = getDevBinaryPath();
+    if (devPath) return devPath;
+
+    // 3. Fallback to npm package
+    const npmPath = resolveFromNpmPackage();
+    if (npmPath) return npmPath;
+
+    return null;
+  }
+
+  // Production: npm package first
+  // 1. Try platform-specific npm package first
+  const npmPath = resolveFromNpmPackage();
+  if (npmPath) return npmPath;
+
+  // 2. Try local bin/ directory (legacy or manual download)
+  const installedPath = getBinaryPath();
+  if (existsSync(installedPath)) return installedPath;
+
+  // 3. Try local dev build
+  return getDevBinaryPath();
+}
+
+/**
+ * Download the binary from GitHub releases as a fallback.
+ * This is only used when the platform npm package is not available.
+ *
+ * @param tag - The release tag to download (e.g. commit hash), or "latest"
+ */
+export async function downloadBinary(tag?: string): Promise<string> {
+  const resolvedTag = tag || "latest";
+  const triple = getTriple();
+  const ext = getLibExtension();
+
+  // Resolve "latest" tag via GitHub API
+  let releaseTag = resolvedTag;
+  if (releaseTag === "latest") {
+    console.log("fff: Fetching latest release tag from GitHub...");
+    releaseTag = await fetchLatestReleaseTag();
+  }
+
+  const binaryName = `c-lib-${triple}.${ext}`;
+  const baseUrl = `https://github.com/${GITHUB_REPO}/releases/download/${releaseTag}`;
+  const binaryUrl = `${baseUrl}/${binaryName}`;
+
+  console.log(`fff: Downloading native library for ${triple}...`);
+  console.log(`fff: Release: ${releaseTag}`);
+
+  const binaryResponse = await fetch(binaryUrl);
+  if (!binaryResponse.ok) {
+    throw new Error(
+      `Failed to download binary: ${binaryResponse.status} ${binaryResponse.statusText}\nURL: ${binaryUrl}`,
+    );
+  }
+
+  const binaryBuffer = Buffer.from(await binaryResponse.arrayBuffer());
+
+  const binDir = getBinDir();
+  if (!existsSync(binDir)) {
+    mkdirSync(binDir, { recursive: true });
+  }
+
+  const binaryPath = getBinaryPath();
+  writeFileSync(binaryPath, binaryBuffer);
+
+  // Make executable on Unix
+  if (process.platform !== "win32") {
+    chmodSync(binaryPath, 0o755);
+  }
+
+  console.log(`fff: Binary downloaded to ${binaryPath}`);
+  return releaseTag;
+}
+
+/**
+ * Fetch the latest release tag from GitHub
+ */
+async function fetchLatestReleaseTag(): Promise<string> {
+  const url = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
+
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/vnd.github.v3+json",
+      "User-Agent": "fff-bun-client",
+    },
+  });
+
+  if (!response.ok) {
+    const allReleasesUrl = `https://api.github.com/repos/${GITHUB_REPO}/releases`;
+    const allResponse = await fetch(allReleasesUrl, {
+      headers: {
+        Accept: "application/vnd.github.v3+json",
+        "User-Agent": "fff-bun-client",
+      },
+    });
+
+    if (!allResponse.ok) {
+      throw new Error(`Failed to fetch releases: ${allResponse.status}`);
+    }
+
+    const releases = (await allResponse.json()) as Array<{ tag_name: string }>;
+    if (releases.length === 0) {
+      throw new Error("No releases found");
+    }
+
+    return releases[0].tag_name;
+  }
+
+  const release = (await response.json()) as { tag_name: string };
+  return release.tag_name;
+}
+
+/**
+ * Ensure the binary exists, downloading from GitHub if necessary.
+ */
+export async function ensureBinary(): Promise<string> {
+  const existingPath = findBinary();
+  if (existingPath) {
+    return existingPath;
+  }
+
+  // Fallback: download from GitHub
+  await downloadBinary();
+  return getBinaryPath();
+}

package/src/ffi.ts

@@ -0,0 +1,450 @@
+/**
+ * Bun FFI bindings for the fff-c native library
+ *
+ * This module uses Bun's native FFI 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`.
+ */
+
+import { dlopen, FFIType, ptr, CString, read, type Pointer } from "bun:ffi";
+import { findBinary, ensureBinary } from "./download";
+import type { Result } from "./types";
+import { err } from "./types";
+
+// Define the FFI symbols
+const ffiDefinition = {
+  // Lifecycle
+  fff_create: {
+    args: [FFIType.cstring],
+    returns: FFIType.ptr,
+  },
+  fff_destroy: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+
+  // Search
+  fff_search: {
+    args: [FFIType.ptr, FFIType.cstring, FFIType.cstring],
+    returns: FFIType.ptr,
+  },
+
+  // Live grep (content search)
+  fff_live_grep: {
+    args: [FFIType.ptr, FFIType.cstring, FFIType.cstring],
+    returns: FFIType.ptr,
+  },
+
+  // File index
+  fff_scan_files: {
+    args: [FFIType.ptr],
+    returns: FFIType.ptr,
+  },
+  fff_is_scanning: {
+    args: [FFIType.ptr],
+    returns: FFIType.bool,
+  },
+  fff_get_scan_progress: {
+    args: [FFIType.ptr],
+    returns: FFIType.ptr,
+  },
+  fff_wait_for_scan: {
+    args: [FFIType.ptr, FFIType.u64],
+    returns: FFIType.ptr,
+  },
+  fff_restart_index: {
+    args: [FFIType.ptr, FFIType.cstring],
+    returns: FFIType.ptr,
+  },
+
+  // Frecency
+  fff_track_access: {
+    args: [FFIType.ptr, FFIType.cstring],
+    returns: FFIType.ptr,
+  },
+
+  // Git
+  fff_refresh_git_status: {
+    args: [FFIType.ptr],
+    returns: FFIType.ptr,
+  },
+
+  // Query tracking
+  fff_track_query: {
+    args: [FFIType.ptr, FFIType.cstring, FFIType.cstring],
+    returns: FFIType.ptr,
+  },
+  fff_get_historical_query: {
+    args: [FFIType.ptr, FFIType.u64],
+    returns: FFIType.ptr,
+  },
+
+  // Utilities
+  fff_health_check: {
+    args: [FFIType.ptr, FFIType.cstring],
+    returns: FFIType.ptr,
+  },
+
+  // Memory management
+  fff_free_result: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+  fff_free_string: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+} as const;
+
+type FFFLibrary = ReturnType<typeof dlopen<typeof ffiDefinition>>;
+
+// Library instance (lazy loaded)
+let lib: FFFLibrary | null = null;
+
+/**
+ * Load the native library
+ */
+function loadLibrary(): FFFLibrary {
+  if (lib) return lib;
+
+  const binaryPath = findBinary();
+  if (!binaryPath) {
+    throw new Error(
+      "fff native library not found. Run `bunx fff download` or build from source with `cargo build --release -p fff-c`"
+    );
+  }
+
+  lib = dlopen(binaryPath, ffiDefinition);
+  return lib;
+}
+
+/**
+ * Encode a string for FFI (null-terminated)
+ */
+function encodeString(s: string): Uint8Array {
+  return new TextEncoder().encode(s + "\0");
+}
+
+/**
+ * Read a C string from a pointer
+ * Note: read.ptr() returns number but CString expects Pointer - we cast through unknown
+ */
+function readCString(pointer: Pointer | number | null): string | null {
+  if (pointer === null || pointer === 0) return null;
+  // CString constructor accepts Pointer, but read.ptr returns number
+  // Cast through unknown for runtime compatibility
+  return new CString(pointer as unknown as Pointer).toString();
+}
+
+/**
+ * Convert snake_case keys to camelCase recursively
+ */
+function snakeToCamel(obj: unknown): unknown {
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map(snakeToCamel);
+
+  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()
+    );
+    result[camelKey] = snakeToCamel(value);
+  }
+  return result;
+}
+
+/**
+ * Parse a FffResult from the FFI return value.
+ *
+ * The result is a pointer to a struct:
+ *   { success: bool, data: *char, error: *char, handle: *void }
+ *
+ * Layout (with alignment padding):
+ *   offset  0: success (bool, 1 byte + 7 padding)
+ *   offset  8: data pointer (8 bytes)
+ *   offset 16: error pointer (8 bytes)
+ *   offset 24: handle pointer (8 bytes)
+ */
+function parseResult<T>(resultPtr: Pointer | null): Result<T> {
+  if (resultPtr === null) {
+    return err("FFI returned null pointer");
+  }
+
+  const success = read.u8(resultPtr, 0) !== 0;
+  const dataPtr = read.ptr(resultPtr, 8);
+  const errorPtr = read.ptr(resultPtr, 16);
+
+  const library = loadLibrary();
+
+  if (success) {
+    const data = readCString(dataPtr);
+    // Free the result
+    library.symbols.fff_free_result(resultPtr);
+
+    if (data === null || data === "") {
+      return { ok: true, value: undefined as T };
+    }
+
+    try {
+      const parsed = JSON.parse(data);
+      // Convert snake_case to camelCase for TypeScript consumers
+      const transformed = snakeToCamel(parsed) as T;
+      return { ok: true, value: transformed };
+    } catch {
+      // For simple values like "true" or numbers
+      return { ok: true, value: data as T };
+    }
+  } else {
+    const errorMsg = readCString(errorPtr) || "Unknown error";
+    // Free the result
+    library.symbols.fff_free_result(resultPtr);
+    return err(errorMsg);
+  }
+}
+
+/**
+ * Opaque native handle type. Callers must not inspect or modify this value.
+ */
+export type NativeHandle = Pointer;
+
+/**
+ * Create a new file finder instance.
+ *
+ * Returns the opaque native handle on success. The handle must be passed to
+ * all subsequent FFI calls and freed with `ffiDestroy`.
+ */
+export function ffiCreate(optsJson: string): Result<NativeHandle> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_create(ptr(encodeString(optsJson)));
+
+  if (resultPtr === null) {
+    return err("FFI returned null pointer");
+  }
+
+  const success = read.u8(resultPtr, 0) !== 0;
+  const errorPtr = read.ptr(resultPtr, 16);
+  const handlePtr = read.ptr(resultPtr, 24);
+
+  if (success) {
+    const handle = handlePtr as unknown as Pointer;
+    library.symbols.fff_free_result(resultPtr);
+
+    if (!handle || handle === (0 as unknown as Pointer)) {
+      return err("fff_create returned null handle");
+    }
+
+    return { ok: true, value: handle };
+  } else {
+    const errorMsg = readCString(errorPtr) || "Unknown error";
+    library.symbols.fff_free_result(resultPtr);
+    return err(errorMsg);
+  }
+}
+
+/**
+ * Destroy and clean up an instance.
+ */
+export function ffiDestroy(handle: NativeHandle): void {
+  const library = loadLibrary();
+  library.symbols.fff_destroy(handle);
+}
+
+/**
+ * Perform fuzzy search.
+ */
+export function ffiSearch(
+  handle: NativeHandle,
+  query: string,
+  optsJson: string
+): Result<unknown> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_search(
+    handle,
+    ptr(encodeString(query)),
+    ptr(encodeString(optsJson))
+  );
+  return parseResult<unknown>(resultPtr);
+}
+
+/**
+ * Trigger file scan.
+ */
+export function ffiScanFiles(handle: NativeHandle): Result<void> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_scan_files(handle);
+  return parseResult<void>(resultPtr);
+}
+
+/**
+ * Check if scanning.
+ */
+export function ffiIsScanning(handle: NativeHandle): boolean {
+  const library = loadLibrary();
+  return library.symbols.fff_is_scanning(handle) as boolean;
+}
+
+/**
+ * Get scan progress.
+ */
+export function ffiGetScanProgress(handle: NativeHandle): Result<unknown> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_get_scan_progress(handle);
+  return parseResult<unknown>(resultPtr);
+}
+
+/**
+ * Wait for scan to complete.
+ */
+export function ffiWaitForScan(
+  handle: NativeHandle,
+  timeoutMs: number
+): Result<boolean> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_wait_for_scan(
+    handle,
+    BigInt(timeoutMs)
+  );
+  const result = parseResult<boolean | string>(resultPtr);
+  if (!result.ok) return result;
+  // JSON.parse("true") returns boolean true, but we also handle
+  // the string case defensively.
+  return { ok: true, value: result.value === true || result.value === "true" };
+}
+
+/**
+ * Restart index in new path.
+ */
+export function ffiRestartIndex(
+  handle: NativeHandle,
+  newPath: string
+): Result<void> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_restart_index(
+    handle,
+    ptr(encodeString(newPath))
+  );
+  return parseResult<void>(resultPtr);
+}
+
+/**
+ * Track file access.
+ */
+export function ffiTrackAccess(
+  handle: NativeHandle,
+  filePath: string
+): Result<boolean> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_track_access(
+    handle,
+    ptr(encodeString(filePath))
+  );
+  const result = parseResult<boolean | string>(resultPtr);
+  if (!result.ok) return result;
+  return { ok: true, value: result.value === true || result.value === "true" };
+}
+
+/**
+ * Refresh git status.
+ */
+export function ffiRefreshGitStatus(handle: NativeHandle): Result<number> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_refresh_git_status(handle);
+  const result = parseResult<number | string>(resultPtr);
+  if (!result.ok) return result;
+  // JSON.parse("3") returns 3 (number), parseInt handles both
+  return { ok: true, value: typeof result.value === "number" ? result.value : parseInt(result.value, 10) };
+}
+
+/**
+ * Track query completion.
+ */
+export function ffiTrackQuery(
+  handle: NativeHandle,
+  query: string,
+  filePath: string
+): Result<boolean> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_track_query(
+    handle,
+    ptr(encodeString(query)),
+    ptr(encodeString(filePath))
+  );
+  const result = parseResult<boolean | string>(resultPtr);
+  if (!result.ok) return result;
+  return { ok: true, value: result.value === true || result.value === "true" };
+}
+
+/**
+ * Get historical query.
+ */
+export function ffiGetHistoricalQuery(
+  handle: NativeHandle,
+  offset: number
+): Result<string | null> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_get_historical_query(
+    handle,
+    BigInt(offset)
+  );
+  const result = parseResult<string | null>(resultPtr);
+  if (!result.ok) return result;
+  if (result.value === null || result.value === "null") return { ok: true, value: null };
+  return result as Result<string>;
+}
+
+/**
+ * Health check.
+ *
+ * `handle` can be null for a limited check (version + git only).
+ */
+export function ffiHealthCheck(
+  handle: NativeHandle | null,
+  testPath: string
+): Result<unknown> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_health_check(
+    handle ?? (0 as unknown as Pointer),
+    ptr(encodeString(testPath))
+  );
+  return parseResult<unknown>(resultPtr);
+}
+
+/**
+ * Live grep - search file contents.
+ */
+export function ffiLiveGrep(
+  handle: NativeHandle,
+  query: string,
+  optsJson: string
+): Result<unknown> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_live_grep(
+    handle,
+    ptr(encodeString(query)),
+    ptr(encodeString(optsJson))
+  );
+  return parseResult<unknown>(resultPtr);
+}
+
+/**
+ * Ensure the library is loaded (for preloading).
+ */
+export async function ensureLoaded(): Promise<void> {
+  await ensureBinary();
+  loadLibrary();
+}
+
+/**
+ * Check if the library is available.
+ */
+export function isAvailable(): boolean {
+  try {
+    loadLibrary();
+    return true;
+  } catch {
+    return false;
+  }
+}