feat(fff-bun): allow an explicit native library via FFF_C_LIB

packages/fff-bun/README.md

@@ -29,6 +29,20 @@ 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.
 
+### Platforms without a prebuilt package
+
+On a platform that has no `@ff-labs/fff-bin-*` package, build the C library from
+source and point `@ff-labs/fff-bun` at it with `FFF_C_LIB`:
+
+```bash
+cargo build --release -p fff-c
+FFF_C_LIB=target/release/libfff_c.so bun ./app.ts
+```
+
+`FFF_C_LIB` is checked before the platform package and the local dev build, so it
+also works for a regular `bun add @ff-labs/fff-bun` install. If the path does not
+exist, resolution fails with an explicit error rather than silently falling back.
+
 ### Standalone executables (`bun build --compile`)
 
 `@ff-labs/fff-bun` embeds the native library into single-file executables built

packages/fff-bun/package.json

@@ -33,7 +33,8 @@
     "darwin",
     "linux",
     "win32",
-    "android"
+    "android",
+    "freebsd"
   ],
   "cpu": [
     "x64",

packages/fff-bun/src/download.ts

@@ -2,8 +2,9 @@
  * Binary resolution utilities for fff
  *
  * Resolves the native library from:
- * 1. Platform-specific npm package (e.g. @ff-labs/fff-bin-darwin-arm64)
- * 2. Local dev build (target/release or target/debug)
+ * 1. The FFF_C_LIB environment variable (explicit path to libfff_c.so/.dylib/.dll)
+ * 2. Platform-specific npm package (e.g. @ff-labs/fff-bin-darwin-arm64)
+ * 3. Local dev build (target/release or target/debug)
  */
 
 import { existsSync } from "node:fs";
@@ -54,7 +55,13 @@ export function binaryExists(): boolean {
  * in the same directory.
  */
 function resolveFromNpmPackage(): string | null {
-  const packageName = getNpmPackageName();
+  let packageName: string;
+  try {
+    packageName = getNpmPackageName();
+  } catch {
+    // Unsupported platform, or no platform package mapped for it.
+    return null;
+  }
 
   try {
     // Use createRequire to resolve the platform package's location
@@ -105,12 +112,23 @@ function isDevWorkspace(): boolean {
  * Find the native library binary.
  *
  * Resolution order:
+ * - FFF_C_LIB (if set) always wins
  * - Dev workspace: local dev build first, then npm package
  * - Production: npm package first, then dev build
  *
  * @returns Absolute path to the library, or null if not found
  */
 export function findBinary(): string | null {
+  // Explicit override for platforms without a prebuilt package (for example a
+  // libfff_c.so built from source on FreeBSD, or any custom build).
+  const override = process.env["FFF_C_LIB"];
+  if (override) {
+    if (!existsSync(override)) {
+      throw new Error(`FFF_C_LIB points to a file that does not exist: ${override}`);
+    }
+    return override;
+  }
+
   if (isDevWorkspace()) {
     // 1. Local bin/ directory (populated by `make prepare-bun`)
     const binPath = join(getPackageDir(), "bin", getLibFilename());

packages/fff-bun/src/platform.ts

@@ -20,6 +20,8 @@ export function getTriple(): string {
     osName = detectLinuxLibc();
   } else if (platform === "win32") {
     osName = "pc-windows-msvc";
+  } else if (platform === "freebsd") {
+    osName = "unknown-freebsd";
   } else {
     throw new Error(`Unsupported platform: ${platform}`);
   }