@ff-labs/bun 0.1.0

package/README.md

@@ -0,0 +1,200 @@
+# fff - Fast File Finder
+
+High-performance fuzzy file finder for Bun, powered by Rust. Perfect for LLM agent tools that need to search through codebases.
+
+## Features
+
+- **Blazing fast** - Rust-powered fuzzy search with parallel processing
+- **Smart ranking** - Frecency-based scoring (frequency + recency)
+- **Git-aware** - Shows file git status in results
+- **Query history** - Learns from your search patterns
+- **Type-safe** - Full TypeScript support with Result types
+
+## Installation
+
+```bash
+bun add fff
+```
+
+The native binary will be downloaded automatically during installation.
+
+## Quick Start
+
+```typescript
+import { FileFinder } from "fff";
+
+// Initialize with a directory
+const result = FileFinder.init({ basePath: "/path/to/project" });
+if (!result.ok) {
+  console.error(result.error);
+  process.exit(1);
+}
+
+// Wait for initial scan
+FileFinder.waitForScan(5000);
+
+// Search for files
+const search = FileFinder.search("main.ts");
+if (search.ok) {
+  for (const item of search.value.items) {
+    console.log(item.relativePath);
+  }
+}
+
+// Cleanup when done
+FileFinder.destroy();
+```
+
+## API Reference
+
+### `FileFinder.init(options)`
+
+Initialize the file finder.
+
+```typescript
+interface InitOptions {
+  basePath: string;           // Directory to index (required)
+  frecencyDbPath?: string;    // Custom frecency DB path
+  historyDbPath?: string;     // Custom history DB path
+  useUnsafeNoLock?: boolean;  // Faster but less safe DB mode
+  skipDatabases?: boolean;    // Skip frecency/history (simpler mode)
+}
+
+const result = FileFinder.init({ basePath: "/my/project" });
+```
+
+### `FileFinder.search(query, options?)`
+
+Search for files.
+
+```typescript
+interface SearchOptions {
+  maxThreads?: number;          // Parallel threads (0 = auto)
+  currentFile?: string;         // Deprioritize this file
+  comboBoostMultiplier?: number; // Query history boost
+  minComboCount?: number;        // Min history matches
+  pageIndex?: number;            // Pagination offset
+  pageSize?: number;             // Results per page
+}
+
+const result = FileFinder.search("main.ts", { pageSize: 10 });
+if (result.ok) {
+  console.log(`Found ${result.value.totalMatched} files`);
+}
+```
+
+### Query Syntax
+
+- `foo bar` - Match files containing "foo" and "bar"
+- `src/` - Match files in src directory
+- `file.ts:42` - Match file.ts with line 42
+- `file.ts:42:10` - Match with line and column
+
+### `FileFinder.trackAccess(filePath)`
+
+Track file access for frecency scoring.
+
+```typescript
+// Call when user opens a file
+FileFinder.trackAccess("/path/to/file.ts");
+```
+
+### `FileFinder.trackQuery(query, selectedFile)`
+
+Track query completion for smart suggestions.
+
+```typescript
+// Call when user selects a file from search
+FileFinder.trackQuery("main", "/path/to/main.ts");
+```
+
+### `FileFinder.healthCheck(testPath?)`
+
+Get diagnostic information.
+
+```typescript
+const health = FileFinder.healthCheck();
+if (health.ok) {
+  console.log(`Version: ${health.value.version}`);
+  console.log(`Indexed: ${health.value.filePicker.indexedFiles} files`);
+}
+```
+
+### Other Methods
+
+- `FileFinder.scanFiles()` - Trigger rescan
+- `FileFinder.isScanning()` - Check scan status
+- `FileFinder.getScanProgress()` - Get scan progress
+- `FileFinder.waitForScan(timeoutMs)` - Wait for scan
+- `FileFinder.restartIndex(newPath)` - Change indexed directory
+- `FileFinder.refreshGitStatus()` - Refresh git cache
+- `FileFinder.getHistoricalQuery(offset)` - Get past queries
+- `FileFinder.shortenPath(path, maxSize, strategy)` - Shorten paths
+- `FileFinder.destroy()` - Cleanup resources
+
+## Result Types
+
+All methods return a `Result<T>` type for explicit error handling:
+
+```typescript
+type Result<T> = 
+  | { ok: true; value: T }
+  | { ok: false; error: string };
+
+const result = FileFinder.search("foo");
+if (result.ok) {
+  // result.value is SearchResult
+} else {
+  // result.error is string
+}
+```
+
+## Search Result Types
+
+```typescript
+interface SearchResult {
+  items: FileItem[];
+  scores: Score[];
+  totalMatched: number;
+  totalFiles: number;
+  location?: Location;
+}
+
+interface FileItem {
+  path: string;
+  relativePath: string;
+  fileName: string;
+  size: number;
+  modified: number;
+  gitStatus: string; // 'clean', 'modified', 'untracked', etc.
+}
+```
+
+## Building from Source
+
+If prebuilt binaries aren't available for your platform:
+
+```bash
+# Clone the repository
+git clone https://github.com/dmtrKovalenko/fff.nvim
+cd fff.nvim
+
+# Build the C library
+cargo build --release -p fff-c
+
+# The binary will be at target/release/libfff_c.{so,dylib,dll}
+```
+
+## CLI Tools
+
+```bash
+# Download binary manually
+bunx fff download [version]
+
+# Show platform info
+bunx fff info
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@ff-labs/bun",
+  "version": "0.1.0",
+  "private": false,
+  "nativeBinaryHash": "6c641aa",
+  "description": "High-performance fuzzy file finder for Bun - perfect for LLM agent tools",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "bin": {
+    "fff": "./scripts/cli.cjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "scripts"
+  ],
+  "scripts": {
+    "postinstall": "bun ./scripts/postinstall.ts",
+    "download": "bun ./scripts/cli.ts download",
+    "test": "bun test src/",
+    "typecheck": "tsc --noEmit",
+    "demo": "bun ./examples/search.ts"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dmtrKovalenko/fff.nvim.git",
+    "directory": "packages/fff"
+  },
+  "keywords": [
+    "file-finder",
+    "fuzzy-search",
+    "bun",
+    "ffi",
+    "llm-tools",
+    "agent-tools",
+    "fast",
+    "rust"
+  ],
+  "author": "Dmitry Kovalenko",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/dmtrKovalenko/fff.nvim/issues"
+  },
+  "homepage": "https://github.com/dmtrKovalenko/fff.nvim#readme",
+  "devDependencies": {
+    "@types/bun": "^1.3.8",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0"
+  }
+}

package/scripts/cli.cjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Wrapper script for npm - delegates to Bun
+const { execSync } = require("child_process");
+const { join } = require("path");
+
+const script = join(__dirname, "cli.ts");
+const args = process.argv.slice(2).join(" ");
+
+try {
+  execSync(`bun ${script} ${args}`, { 
+    stdio: "inherit",
+    cwd: process.cwd()
+  });
+} catch (error) {
+  process.exit(error.status || 1);
+}

package/scripts/cli.ts

@@ -0,0 +1,131 @@
+#!/usr/bin/env bun
+/**
+ * CLI tool for fff package management
+ *
+ * Usage:
+ *   bunx fff download [hash]    - Download native binary
+ *   bunx fff info               - Show platform and binary info
+ *   bunx fff check              - Check for updates
+ */
+
+import { 
+  downloadBinary, 
+  getBinaryPath, 
+  findBinary, 
+  getInstalledHash,
+  checkForUpdate 
+} from "../src/download";
+import { getTriple, getLibExtension, getLibFilename } from "../src/platform";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+interface PackageJson {
+  version: string;
+  nativeBinaryHash?: string;
+}
+
+async function getPackageInfo(): Promise<PackageJson> {
+  const currentDir = dirname(fileURLToPath(import.meta.url));
+  const packageJsonPath = join(currentDir, "..", "package.json");
+  
+  try {
+    return await Bun.file(packageJsonPath).json();
+  } catch {
+    return { version: "unknown" };
+  }
+}
+
+async function main() {
+  switch (command) {
+    case "download": {
+      const hash = args[1];
+      console.log("fff: Downloading native library...");
+      try {
+        const resolvedHash = await downloadBinary(hash);
+        console.log(`fff: Download complete! (${resolvedHash})`);
+      } catch (error) {
+        console.error("fff: Download failed:", error);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "check": {
+      console.log("fff: Checking for updates...");
+      try {
+        const { currentHash, latestHash, updateAvailable } = await checkForUpdate();
+        console.log(`  Installed: ${currentHash || "not installed"}`);
+        console.log(`  Latest:    ${latestHash}`);
+        if (updateAvailable) {
+          console.log("");
+          console.log("  Update available! Run: bunx fff download");
+        } else {
+          console.log("");
+          console.log("  You're up to date!");
+        }
+      } catch (error) {
+        console.error("fff: Failed to check for updates:", error);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "info": {
+      const pkg = await getPackageInfo();
+      const installedHash = await getInstalledHash();
+      
+      console.log("fff - Fast File Finder");
+      console.log(`Package version: ${pkg.version}`);
+      console.log(`Binary hash: ${installedHash || "not installed"}`);
+      console.log("");
+      console.log("Platform Information:");
+      console.log(`  Triple: ${getTriple()}`);
+      console.log(`  Extension: ${getLibExtension()}`);
+      console.log(`  Library name: ${getLibFilename()}`);
+      console.log("");
+      console.log("Binary Status:");
+      const existing = findBinary();
+      if (existing) {
+        console.log(`  Found: ${existing}`);
+      } else {
+        console.log(`  Not found`);
+        console.log(`  Expected path: ${getBinaryPath()}`);
+      }
+      break;
+    }
+
+    case "version":
+    case "--version":
+    case "-v": {
+      const pkg = await getPackageInfo();
+      console.log(pkg.version);
+      break;
+    }
+
+    case "help":
+    case "--help":
+    case "-h":
+    default: {
+      const pkg = await getPackageInfo();
+      console.log(`fff - Fast File Finder CLI v${pkg.version}`);
+      console.log("");
+      console.log("Usage:");
+      console.log("  bunx fff download [hash]   Download native binary");
+      console.log("  bunx fff check             Check for updates");
+      console.log("  bunx fff info              Show platform and binary info");
+      console.log("  bunx fff version           Show version");
+      console.log("  bunx fff help              Show this help message");
+      console.log("");
+      console.log("Examples:");
+      console.log("  bunx fff download          Download binary for configured hash");
+      console.log("  bunx fff download latest   Download latest release");
+      console.log("  bunx fff download abc1234  Download specific commit hash");
+      break;
+    }
+  }
+}
+
+main();

package/scripts/postinstall.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env bun
+/**
+ * Postinstall script - automatically downloads the native binary
+ */
+
+import { downloadBinary, findBinary, getInstalledHash } from "../src/download";
+
+async function main() {
+  // Check if binary already exists (dev build or previous download)
+  const existing = findBinary();
+  if (existing) {
+    const hash = await getInstalledHash();
+    console.log(`fff: Native library found at ${existing}`);
+    if (hash) {
+      console.log(`fff: Version: ${hash}`);
+    }
+    return;
+  }
+
+  console.log("fff: Native library not found, downloading...");
+
+  try {
+    const hash = await downloadBinary();
+    console.log(`fff: Native library installed successfully! (${hash})`);
+  } catch (error) {
+    console.error("fff: Failed to download native library:", error);
+    console.error("");
+    console.error("fff: You can build from source instead:");
+    console.error("  cd node_modules/fff && cargo build --release -p fff-c");
+    console.error("");
+    console.error("fff: Or run `bunx fff download` after fixing network issues.");
+    // Don't exit with error - allow install to complete
+    // The error will surface when the user tries to use the library
+  }
+}
+
+main();