quack-search 0.0.4 → 0.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 DuckDuckGo web search library for JS runtimes, written in Go
 
-### Installation
+## Installation
 
 ```bash
 bun add quack-search
@@ -12,7 +12,7 @@ npm install quack-search
 yarn add quack-search
 ```
 
-### Usage
+## Usage
 
 ```ts
 import { search, fetchContent } from 'quack-search';
@@ -27,7 +27,56 @@ if (!page.success) {
 }
 ```
 
-#### _Open to Contributions_
+## Supported Platforms
+
+- macOS (x64, ARM64)
+- Linux (x64, ARM64)
+- Windows (x64, ARM64)
+
+## Advanced: CI / Docker / Offline Environments
+
+For constrained environments where automatic download isn't possible:
+
+### Option 1: Environment Variable
+
+Pre-install the binary and point to it:
+```bash
+export QUACK_BINARY_PATH=/usr/local/bin/quack
+```
+
+### Option 2: Explicit Download
+
+Download at build time (e.g., in a Dockerfile):
+```ts
+import { downloadBinary } from 'quack-search';
+
+await downloadBinary({ 
+  targetDir: '/app/bin',
+  version: 'v0.1.0', // or 'latest'
+  verbose: true 
+});
+```
+
+### Option 3: Platform Package
+
+Install the platform-specific package directly:
+```bash
+npm install quack-search-linux-x64
+```
+
+### Diagnostics
+
+```ts
+import { checkBinaryStatus } from 'quack-search';
+
+const status = checkBinaryStatus();
+console.log(status);
+// { found: true, path: '/path/to/quack', source: 'node_modules', platform: 'darwin', arch: 'arm64' }
+```
+
+## Contributing
+
+Open to contributions! See the [repository](https://github.com/adistrim/quack).
 
 ## License
 MIT License. See [LICENSE](LICENSE) file for details.

package/dist/core/binary.d.ts

@@ -1 +1,48 @@
+export type SupportedPlatform = "darwin-arm64" | "darwin-x64" | "linux-x64" | "linux-arm64" | "windows-x64" | "windows-arm64";
+export declare function getPlatformTarget(): SupportedPlatform;
+export declare function getBinaryName(): string;
+export declare class QuackBinaryError extends Error {
+    readonly code: string;
+    readonly hint?: string | undefined;
+    constructor(message: string, code: string, hint?: string | undefined);
+    toString(): string;
+}
+interface BinaryResolutionResult {
+    path: string;
+    source: "env" | "node_modules" | "local";
+}
+/**
+ * Attempts to resolve the quack binary using multiple strategies:
+ * 1. QUACK_BINARY_PATH environment variable (explicit override)
+ * 2. Platform-specific npm package in node_modules
+ * 3. Local binary in package directory (for development/bundled)
+ */
 export declare function resolveBinaryPath(): string;
+export declare function tryResolveBinary(): BinaryResolutionResult;
+export interface BinaryStatus {
+    found: boolean;
+    path?: string;
+    source?: "env" | "node_modules" | "local";
+    error?: string;
+    platform: string;
+    arch: string;
+}
+/**
+ * Check if the binary is available without throwing.
+ * Useful for diagnostics and graceful degradation.
+ */
+export declare function checkBinaryStatus(): BinaryStatus;
+/**
+ * Ensures the binary is available. Throws QuackBinaryError if not.
+ * Call this at startup or before critical operations to fail fast.
+ *
+ * @example
+ * ```ts
+ * import { ensureBinary } from 'quack-search';
+ *
+ * // Fail fast at app startup
+ * ensureBinary();
+ * ```
+ */
+export declare function ensureBinary(): void;
+export {};

package/dist/core/binary.js

@@ -1,24 +1,211 @@
-import { platform, arch } from "node:process";
-import { dirname, join } from "node:path";
-import { createRequire } from "node:module";
-const require = createRequire(import.meta.url);
-function resolveBinaryPackage() {
-    if (platform === "darwin" && arch === "arm64") {
-        return "quack-search-darwin-arm64";
+import { platform, arch, env } from "node:process";
+import { join, dirname, resolve } from "node:path";
+import { existsSync, accessSync, constants } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+export function getPlatformTarget() {
+    const key = `${platform}-${arch}`;
+    const supported = {
+        "darwin-arm64": "darwin-arm64",
+        "darwin-x64": "darwin-x64",
+        "linux-x64": "linux-x64",
+        "linux-arm64": "linux-arm64",
+        "win32-x64": "windows-x64",
+        "win32-arm64": "windows-arm64",
+    };
+    const target = supported[key];
+    if (!target) {
+        throw new QuackBinaryError(`Unsupported platform: ${platform} ${arch}`, "UNSUPPORTED_PLATFORM", `quack-search supports: darwin-arm64, darwin-x64, linux-x64, linux-arm64, windows-x64, windows-arm64.\n` +
+            `You can provide a custom binary via QUACK_BINARY_PATH environment variable.`);
     }
-    if (platform === "darwin" && arch === "x64") {
-        return "quack-search-darwin-x64";
-    }
-    if (platform === "linux" && arch === "x64") {
-        return "quack-search-linux-x64";
+    return target;
+}
+export function getBinaryName() {
+    return platform === "win32" ? "quack.exe" : "quack";
+}
+// ---------- Error Handling ----------
+export class QuackBinaryError extends Error {
+    code;
+    hint;
+    constructor(message, code, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.name = "QuackBinaryError";
     }
-    if (platform === "win32" && arch === "x64") {
-        return "quack-search-windows-x64";
+    toString() {
+        let msg = `${this.name}: ${this.message}`;
+        if (this.hint) {
+            msg += `\n\nHint: ${this.hint}`;
+        }
+        return msg;
     }
-    throw new Error(`unsupported platform: ${platform} ${arch}`);
 }
+/**
+ * Attempts to resolve the quack binary using multiple strategies:
+ * 1. QUACK_BINARY_PATH environment variable (explicit override)
+ * 2. Platform-specific npm package in node_modules
+ * 3. Local binary in package directory (for development/bundled)
+ */
 export function resolveBinaryPath() {
-    const pkgName = resolveBinaryPackage();
-    const pkgEntry = require.resolve(pkgName);
-    return pkgEntry;
+    const result = tryResolveBinary();
+    return result.path;
+}
+export function tryResolveBinary() {
+    // Explicit env var override
+    const envPath = env.QUACK_BINARY_PATH;
+    if (envPath) {
+        if (!existsSync(envPath)) {
+            throw new QuackBinaryError(`Binary not found at QUACK_BINARY_PATH: ${envPath}`, "ENV_BINARY_NOT_FOUND", `Ensure the file exists and is executable.`);
+        }
+        assertExecutable(envPath);
+        return { path: envPath, source: "env" };
+    }
+    // Looking in node_modules for platform-specific package
+    const nodeModulesPath = tryResolveFromNodeModules();
+    if (nodeModulesPath) {
+        return { path: nodeModulesPath, source: "node_modules" };
+    }
+    // Look for local binary
+    const localPath = tryResolveLocalBinary();
+    if (localPath) {
+        return { path: localPath, source: "local" };
+    }
+    // all failure state
+    const targetPlatform = getPlatformTarget();
+    const packageName = `quack-search-${targetPlatform}`;
+    throw new QuackBinaryError(`Could not find quack binary for ${platform} ${arch}`, "BINARY_NOT_FOUND", `To fix this, try one of:\n` +
+        `  1. Install the platform package: npm install ${packageName}\n` +
+        `  2. Set QUACK_BINARY_PATH to point to your quack binary\n` +
+        `  3. Download the binary from: https://github.com/adistrim/quack/releases\n\n` +
+        `If you're using Docker or a bundler, set QUACK_BINARY_PATH explicitly.`);
+}
+// resolve binary from platform-specific package in node_modules
+function tryResolveFromNodeModules() {
+    const targetPlatform = getPlatformTarget();
+    const packageName = `quack-search-${targetPlatform}`;
+    const binaryName = getBinaryName();
+    const thisDir = getModuleDir();
+    //.  node_modules locations to check
+    const searchPaths = [
+        // hoisted in monorepo (relative to this package)
+        join(thisDir, "..", "..", "..", "node_modules", packageName, "bin", binaryName),
+        // direct
+        join(thisDir, "..", "..", "node_modules", packageName, "bin", binaryName),
+        // peer location
+        join(thisDir, "..", "..", packageName, "bin", binaryName),
+        // pnpm-style
+        join(thisDir, "..", "..", "..", ".pnpm", "node_modules", packageName, "bin", binaryName),
+    ];
+    // Also check process.cwd() based paths for runtime resolution
+    const cwd = process.cwd();
+    searchPaths.push(join(cwd, "node_modules", packageName, "bin", binaryName), join(cwd, "..", "node_modules", packageName, "bin", binaryName));
+    for (const searchPath of searchPaths) {
+        const resolved = resolve(searchPath);
+        if (existsSync(resolved)) {
+            try {
+                assertExecutable(resolved);
+                return resolved;
+            }
+            catch {
+                // next
+            }
+        }
+    }
+    return null;
+}
+function tryResolveLocalBinary() {
+    const binaryName = getBinaryName();
+    const thisDir = getModuleDir();
+    // Check for local bin directory (useful for development or bundled distributions)
+    const localPaths = [
+        join(thisDir, "..", "..", "bin", binaryName),
+        join(thisDir, "..", "bin", binaryName),
+        join(thisDir, "bin", binaryName),
+    ];
+    // Also check user cache directory (auto-downloaded binaries)
+    const cacheDir = getCacheDir();
+    localPaths.push(join(cacheDir, binaryName));
+    for (const localPath of localPaths) {
+        const resolved = resolve(localPath);
+        if (existsSync(resolved)) {
+            try {
+                assertExecutable(resolved);
+                return resolved;
+            }
+            catch {
+                // Not executable, try next
+            }
+        }
+    }
+    return null;
+}
+function getCacheDir() {
+    const home = homedir();
+    if (platform === "win32") {
+        return join(env.LOCALAPPDATA || join(home, "AppData", "Local"), "quack-search");
+    }
+    return join(env.XDG_CACHE_HOME || join(home, ".cache"), "quack-search");
+}
+function assertExecutable(filePath) {
+    try {
+        accessSync(filePath, constants.X_OK);
+    }
+    catch {
+        throw new QuackBinaryError(`Binary exists but is not executable: ${filePath}`, "BINARY_NOT_EXECUTABLE", `Run: chmod +x "${filePath}"`);
+    }
+}
+function getModuleDir() {
+    // Support both Bun and Node.js
+    if (typeof import.meta.dir === "string") {
+        return import.meta.dir;
+    }
+    return dirname(fileURLToPath(import.meta.url));
+}
+/**
+ * Check if the binary is available without throwing.
+ * Useful for diagnostics and graceful degradation.
+ */
+export function checkBinaryStatus() {
+    const base = { platform, arch };
+    try {
+        const result = tryResolveBinary();
+        return {
+            ...base,
+            found: true,
+            path: result.path,
+            source: result.source,
+        };
+    }
+    catch (err) {
+        return {
+            ...base,
+            found: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Ensures the binary is available. Throws QuackBinaryError if not.
+ * Call this at startup or before critical operations to fail fast.
+ *
+ * @example
+ * ```ts
+ * import { ensureBinary } from 'quack-search';
+ *
+ * // Fail fast at app startup
+ * ensureBinary();
+ * ```
+ */
+export function ensureBinary() {
+    const status = checkBinaryStatus();
+    if (!status.found) {
+        const targetPlatform = getPlatformTarget();
+        const packageName = `quack-search-${targetPlatform}`;
+        throw new QuackBinaryError(`Quack binary not available for ${status.platform} ${status.arch}`, "BINARY_NOT_AVAILABLE", `To fix this:\n` +
+            `  1. Install platform package: npm install ${packageName}\n` +
+            `  2. Or set QUACK_BINARY_PATH environment variable\n` +
+            `  3. Or download explicitly: await downloadBinary()\n\n` +
+            `For Docker/CI: Set QUACK_BINARY_PATH or call downloadBinary() at build time.`);
+    }
 }

package/dist/core/download.d.ts

@@ -0,0 +1,49 @@
+import { type SupportedPlatform } from "./binary";
+/**
+ * Internal: Ensures binary is ready, downloading automatically if needed.
+ * This is called internally before any core execution.
+ * Users should never need to call this directly.
+ */
+export declare function ensureBinaryReady(): Promise<string>;
+/**
+ * Resets the bootstrap state. Useful for testing or forcing re-download.
+ * @internal
+ */
+export declare function resetBootstrap(): void;
+export interface DownloadOptions {
+    /** Target directory for the binary. Defaults to package bin directory. */
+    targetDir?: string;
+    /** Specific version to download. Defaults to 'latest'. */
+    version?: string;
+    /** Override platform detection. */
+    platform?: SupportedPlatform;
+    /** Show progress output. */
+    verbose?: boolean;
+}
+export interface DownloadResult {
+    binaryPath: string;
+    version: string;
+    platform: SupportedPlatform;
+}
+/**
+ * Downloads the quack binary for the current platform.
+ * Use this for explicit binary setup in Docker, CI, or bundled environments.
+ *
+ * @example
+ * ```ts
+ * import { downloadBinary } from 'quack-search';
+ *
+ * // Download to default location
+ * const result = await downloadBinary();
+ * console.log(`Binary downloaded to: ${result.binaryPath}`);
+ *
+ * // Download to custom location
+ * await downloadBinary({ targetDir: '/app/bin' });
+ * ```
+ */
+export declare function downloadBinary(options?: DownloadOptions): Promise<DownloadResult>;
+/**
+ * Check if a binary download is needed.
+ * Returns true if no binary is currently available.
+ */
+export declare function needsDownload(): boolean;

package/dist/core/download.js

@@ -0,0 +1,228 @@
+import { existsSync, mkdirSync, chmodSync, createWriteStream, unlinkSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { getPlatformTarget, getBinaryName, QuackBinaryError, checkBinaryStatus } from "./binary";
+const GITHUB_RELEASE_BASE = "https://github.com/adistrim/quack/releases/download";
+// Cache directory for auto-downloaded binaries (~/.cache/quack-search/)
+function getCacheDir() {
+    const home = homedir();
+    if (process.platform === "win32") {
+        return join(process.env.LOCALAPPDATA || join(home, "AppData", "Local"), "quack-search");
+    }
+    return join(process.env.XDG_CACHE_HOME || join(home, ".cache"), "quack-search");
+}
+// ---------- Internal Bootstrap (Prisma-style auto-download) ----------
+let bootstrapPromise = null;
+/**
+ * Internal: Ensures binary is ready, downloading automatically if needed.
+ * This is called internally before any core execution.
+ * Users should never need to call this directly.
+ */
+export async function ensureBinaryReady() {
+    // Return cached promise if bootstrap is in progress
+    if (bootstrapPromise) {
+        return bootstrapPromise;
+    }
+    bootstrapPromise = doBootstrap();
+    try {
+        return await bootstrapPromise;
+    }
+    catch (err) {
+        // Reset on failure so next call can retry
+        bootstrapPromise = null;
+        throw err;
+    }
+}
+async function doBootstrap() {
+    // check binary is already available 
+    const status = checkBinaryStatus();
+    if (status.found && status.path) {
+        return status.path;
+    }
+    // download to cache directory
+    const cacheDir = getCacheDir();
+    const platform = getPlatformTarget();
+    const binaryName = getBinaryName();
+    const cachePath = join(cacheDir, binaryName);
+    // Check if already in cache (may have been downloaded previously)
+    if (existsSync(cachePath)) {
+        try {
+            const { accessSync, constants } = await import("node:fs");
+            accessSync(cachePath, constants.X_OK);
+            return cachePath;
+        }
+        catch {
+            // Cache exists but not executable, will re-download
+        }
+    }
+    // Download to cache
+    try {
+        const result = await downloadBinary({
+            targetDir: cacheDir,
+            version: "latest",
+            platform,
+            verbose: false,
+        });
+        return result.binaryPath;
+    }
+    catch (downloadErr) {
+        // Provide clear, actionable error
+        throw new QuackBinaryError(`Could not find or download quack binary for ${process.platform} ${process.arch}`, "BOOTSTRAP_FAILED", `Automatic download failed. To fix this:\n` +
+            `  1. Check your internet connection\n` +
+            `  2. Or install manually: npm install quack-search-${platform}\n` +
+            `  3. Or set QUACK_BINARY_PATH to a pre-downloaded binary\n\n` +
+            `Original error: ${downloadErr instanceof Error ? downloadErr.message : String(downloadErr)}`);
+    }
+}
+/**
+ * Resets the bootstrap state. Useful for testing or forcing re-download.
+ * @internal
+ */
+export function resetBootstrap() {
+    bootstrapPromise = null;
+}
+/**
+ * Downloads the quack binary for the current platform.
+ * Use this for explicit binary setup in Docker, CI, or bundled environments.
+ *
+ * @example
+ * ```ts
+ * import { downloadBinary } from 'quack-search';
+ *
+ * // Download to default location
+ * const result = await downloadBinary();
+ * console.log(`Binary downloaded to: ${result.binaryPath}`);
+ *
+ * // Download to custom location
+ * await downloadBinary({ targetDir: '/app/bin' });
+ * ```
+ */
+export async function downloadBinary(options = {}) {
+    const { targetDir = getDefaultBinDir(), version = "latest", platform = getPlatformTarget(), verbose = false, } = options;
+    const binaryName = getBinaryName();
+    const targetPath = join(targetDir, binaryName);
+    // Ensure target directory exists
+    if (!existsSync(targetDir)) {
+        mkdirSync(targetDir, { recursive: true });
+    }
+    // Resolve version (could fetch latest tag from GitHub API)
+    const resolvedVersion = version === "latest" ? await fetchLatestVersion() : version;
+    // Build download URL
+    const downloadUrl = buildDownloadUrl(platform, resolvedVersion);
+    if (verbose) {
+        console.log(`Downloading quack binary...`);
+        console.log(`  Platform: ${platform}`);
+        console.log(`  Version: ${resolvedVersion}`);
+        console.log(`  URL: ${downloadUrl}`);
+        console.log(`  Target: ${targetPath}`);
+    }
+    // Download the binary
+    await downloadFile(downloadUrl, targetPath);
+    // Make executable (non-Windows)
+    if (process.platform !== "win32") {
+        chmodSync(targetPath, 0o755);
+    }
+    if (verbose) {
+        console.log(`Binary downloaded successfully!`);
+    }
+    return {
+        binaryPath: targetPath,
+        version: resolvedVersion,
+        platform,
+    };
+}
+async function fetchLatestVersion() {
+    try {
+        const response = await fetch("https://api.github.com/repos/adistrim/quack/releases/latest", {
+            headers: {
+                Accept: "application/vnd.github.v3+json",
+                "User-Agent": "quack-search",
+            },
+        });
+        if (!response.ok) {
+            throw new QuackBinaryError(`Failed to fetch latest version: GitHub API returned ${response.status}`, "VERSION_FETCH_FAILED", `Specify an explicit version instead, e.g.: downloadBinary({ version: 'v0.1.0' })`);
+        }
+        const data = (await response.json());
+        if (!data.tag_name) {
+            throw new QuackBinaryError("Invalid response from GitHub API: missing tag_name", "VERSION_PARSE_FAILED", `Specify an explicit version instead, e.g.: downloadBinary({ version: 'v0.1.0' })`);
+        }
+        return data.tag_name;
+    }
+    catch (err) {
+        if (err instanceof QuackBinaryError) {
+            throw err;
+        }
+        throw new QuackBinaryError("Failed to fetch latest version from GitHub", "VERSION_FETCH_FAILED", `Network error or GitHub unavailable. Specify an explicit version, e.g.: downloadBinary({ version: 'v0.1.0' })`);
+    }
+}
+function buildDownloadUrl(platform, version) {
+    // Map platform to release asset naming convention
+    const assetMap = {
+        "darwin-arm64": "quack-darwin-arm64",
+        "darwin-x64": "quack-darwin-x64",
+        "linux-x64": "quack-linux-x64",
+        "linux-arm64": "quack-linux-arm64",
+        "windows-x64": "quack-windows-x64.exe",
+        "windows-arm64": "quack-windows-arm64.exe",
+    };
+    const assetName = assetMap[platform];
+    return `${GITHUB_RELEASE_BASE}/${version}/${assetName}`;
+}
+async function downloadFile(url, targetPath) {
+    const response = await fetch(url, {
+        headers: {
+            "User-Agent": "quack-search",
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 404) {
+            throw new QuackBinaryError(`Binary not found at ${url}`, "DOWNLOAD_NOT_FOUND", `The release may not exist or the platform is not supported.\n` +
+                `Check available releases at: https://github.com/adistrim/quack/releases`);
+        }
+        throw new QuackBinaryError(`Failed to download binary: HTTP ${response.status}`, "DOWNLOAD_FAILED", `URL: ${url}`);
+    }
+    const body = response.body;
+    if (!body) {
+        throw new QuackBinaryError("Empty response body", "DOWNLOAD_EMPTY");
+    }
+    // Remove existing file if present
+    if (existsSync(targetPath)) {
+        unlinkSync(targetPath);
+    }
+    // Stream to file
+    const fileStream = createWriteStream(targetPath);
+    // Convert web stream to node stream for pipeline
+    const reader = body.getReader();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            fileStream.write(value);
+        }
+        fileStream.end();
+        await new Promise((resolve, reject) => {
+            fileStream.on("finish", resolve);
+            fileStream.on("error", reject);
+        });
+    }
+    catch (err) {
+        fileStream.close();
+        if (existsSync(targetPath)) {
+            unlinkSync(targetPath);
+        }
+        throw new QuackBinaryError("Failed to write binary file", "DOWNLOAD_WRITE_FAILED", err instanceof Error ? err.message : String(err));
+    }
+}
+function getDefaultBinDir() {
+    // Default to bin directory relative to this package
+    const thisDir = dirname(new URL(import.meta.url).pathname);
+    return join(thisDir, "..", "..", "bin");
+}
+/**
+ * Check if a binary download is needed.
+ * Returns true if no binary is currently available.
+ */
+export function needsDownload() {
+    return !checkBinaryStatus().found;
+}

package/dist/core/runner.d.ts

@@ -1,2 +1,11 @@
 import type { CoreRequest, CoreResponse } from "../types/core";
+export declare class QuackRuntimeError extends Error {
+    readonly code: string;
+    readonly details?: string | undefined;
+    constructor(message: string, code: string, details?: string | undefined);
+}
+/**
+ * Runs the core binary with auto-bootstrap.
+ * Binary is automatically downloaded if not present.
+ */
 export declare function runCore(payload: CoreRequest, timeoutMs?: number): Promise<CoreResponse>;

package/dist/core/runner.js

@@ -1,15 +1,37 @@
 import { spawn } from "node:child_process";
-import { resolveBinaryPath } from "./binary";
-export function runCore(payload, timeoutMs = 30_000) {
-    return new Promise((resolve, reject) => {
-        let binaryPath;
-        try {
-            binaryPath = resolveBinaryPath();
-        }
-        catch (err) {
-            reject(err);
-            return;
+import { QuackBinaryError } from "./binary";
+import { ensureBinaryReady } from "./download";
+export class QuackRuntimeError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "QuackRuntimeError";
+    }
+}
+/**
+ * Runs the core binary with auto-bootstrap.
+ * Binary is automatically downloaded if not present.
+ */
+export async function runCore(payload, timeoutMs = 30_000) {
+    // Auto-bootstrap: ensures binary exists, downloads if needed
+    let binaryPath;
+    try {
+        binaryPath = await ensureBinaryReady();
+    }
+    catch (err) {
+        if (err instanceof QuackBinaryError) {
+            throw err;
         }
+        throw new QuackRuntimeError("Failed to prepare quack binary", "BOOTSTRAP_FAILED", err instanceof Error ? err.message : String(err));
+    }
+    // Execute the binary
+    return executeCore(binaryPath, payload, timeoutMs);
+}
+function executeCore(binaryPath, payload, timeoutMs) {
+    return new Promise((resolve, reject) => {
         const proc = spawn(binaryPath, {
             stdio: ["pipe", "pipe", "pipe"],
         });
@@ -17,7 +39,7 @@ export function runCore(payload, timeoutMs = 30_000) {
         let stderr = "";
         const timeout = setTimeout(() => {
             proc.kill();
-            reject(new Error("core process timed out"));
+            reject(new QuackRuntimeError(`Core process timed out after ${timeoutMs}ms`, "TIMEOUT", `Binary: ${binaryPath}`));
         }, timeoutMs);
         proc.stdout.on("data", (d) => {
             stdout += d.toString();
@@ -27,12 +49,22 @@ export function runCore(payload, timeoutMs = 30_000) {
         });
         proc.on("error", (err) => {
             clearTimeout(timeout);
-            reject(err);
+            // Handle common spawn errors with actionable messages
+            if (err.code === "ENOENT") {
+                reject(new QuackRuntimeError(`Binary not found or not executable: ${binaryPath}`, "ENOENT", `The binary path was resolved but the file doesn't exist or isn't accessible.\n` +
+                    `Check that the binary exists and has execute permissions.`));
+                return;
+            }
+            if (err.code === "EACCES") {
+                reject(new QuackRuntimeError(`Permission denied executing binary: ${binaryPath}`, "EACCES", `Run: chmod +x "${binaryPath}"`));
+                return;
+            }
+            reject(new QuackRuntimeError(`Failed to spawn core process: ${err.message}`, "SPAWN_ERROR", `Binary: ${binaryPath}`));
         });
         proc.on("close", (code) => {
             clearTimeout(timeout);
             if (code !== 0) {
-                reject(new Error(stderr || "core process failed"));
+                reject(new QuackRuntimeError(stderr || `Core process exited with code ${code}`, "PROCESS_FAILED", `Exit code: ${code}, Binary: ${binaryPath}`));
                 return;
             }
             let parsed;
@@ -40,15 +72,15 @@ export function runCore(payload, timeoutMs = 30_000) {
                 parsed = JSON.parse(stdout);
             }
             catch {
-                reject(new Error("invalid JSON returned from core"));
+                reject(new QuackRuntimeError("Invalid JSON returned from core", "INVALID_RESPONSE", `Raw output: ${stdout.slice(0, 200)}${stdout.length > 200 ? "..." : ""}`));
                 return;
             }
             if (parsed.error) {
-                reject(new Error(parsed.error));
+                reject(new QuackRuntimeError(parsed.error, "CORE_ERROR"));
                 return;
             }
             if (!parsed.results && !parsed.fetch) {
-                reject(new Error("empty response from core"));
+                reject(new QuackRuntimeError("Empty response from core", "EMPTY_RESPONSE"));
                 return;
             }
             resolve(parsed);

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 export { search } from "./api/search";
 export { fetchContent } from "./api/fetch";
-export type { SearchOptions } from "./types/core";
+export type { SearchOptions, SearchResult, FetchResult } from "./types/core";
+export { checkBinaryStatus, ensureBinary, resolveBinaryPath, QuackBinaryError, getPlatformTarget, type BinaryStatus, type SupportedPlatform, } from "./core/binary";
+export { QuackRuntimeError } from "./core/runner";
+export { downloadBinary, needsDownload, type DownloadOptions, type DownloadResult, } from "./core/download";

package/dist/index.js

@@ -1,42 +1,400 @@
 // @bun
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = import.meta.require;
+
 // src/core/runner.ts
 import { spawn } from "child_process";
 
 // src/core/binary.ts
-import { platform, arch } from "process";
-import { createRequire } from "module";
-var require2 = createRequire(import.meta.url);
-function resolveBinaryPackage() {
-  if (platform === "darwin" && arch === "arm64") {
-    return "quack-search-darwin-arm64";
-  }
-  if (platform === "darwin" && arch === "x64") {
-    return "quack-search-darwin-x64";
+import { platform, arch, env } from "process";
+import { join, dirname, resolve } from "path";
+import { existsSync, accessSync, constants } from "fs";
+import { fileURLToPath } from "url";
+import { homedir } from "os";
+function getPlatformTarget() {
+  const key = `${platform}-${arch}`;
+  const supported = {
+    "darwin-arm64": "darwin-arm64",
+    "darwin-x64": "darwin-x64",
+    "linux-x64": "linux-x64",
+    "linux-arm64": "linux-arm64",
+    "win32-x64": "windows-x64",
+    "win32-arm64": "windows-arm64"
+  };
+  const target = supported[key];
+  if (!target) {
+    throw new QuackBinaryError(`Unsupported platform: ${platform} ${arch}`, "UNSUPPORTED_PLATFORM", `quack-search supports: darwin-arm64, darwin-x64, linux-x64, linux-arm64, windows-x64, windows-arm64.
+` + `You can provide a custom binary via QUACK_BINARY_PATH environment variable.`);
   }
-  if (platform === "linux" && arch === "x64") {
-    return "quack-search-linux-x64";
+  return target;
+}
+function getBinaryName() {
+  return platform === "win32" ? "quack.exe" : "quack";
+}
+
+class QuackBinaryError extends Error {
+  code;
+  hint;
+  constructor(message, code, hint) {
+    super(message);
+    this.code = code;
+    this.hint = hint;
+    this.name = "QuackBinaryError";
   }
-  if (platform === "win32" && arch === "x64") {
-    return "quack-search-windows-x64";
+  toString() {
+    let msg = `${this.name}: ${this.message}`;
+    if (this.hint) {
+      msg += `
+
+Hint: ${this.hint}`;
+    }
+    return msg;
   }
-  throw new Error(`unsupported platform: ${platform} ${arch}`);
 }
 function resolveBinaryPath() {
-  const pkgName = resolveBinaryPackage();
-  const pkgEntry = require2.resolve(pkgName);
-  return pkgEntry;
+  const result = tryResolveBinary();
+  return result.path;
 }
+function tryResolveBinary() {
+  const envPath = env.QUACK_BINARY_PATH;
+  if (envPath) {
+    if (!existsSync(envPath)) {
+      throw new QuackBinaryError(`Binary not found at QUACK_BINARY_PATH: ${envPath}`, "ENV_BINARY_NOT_FOUND", `Ensure the file exists and is executable.`);
+    }
+    assertExecutable(envPath);
+    return { path: envPath, source: "env" };
+  }
+  const nodeModulesPath = tryResolveFromNodeModules();
+  if (nodeModulesPath) {
+    return { path: nodeModulesPath, source: "node_modules" };
+  }
+  const localPath = tryResolveLocalBinary();
+  if (localPath) {
+    return { path: localPath, source: "local" };
+  }
+  const targetPlatform = getPlatformTarget();
+  const packageName = `quack-search-${targetPlatform}`;
+  throw new QuackBinaryError(`Could not find quack binary for ${platform} ${arch}`, "BINARY_NOT_FOUND", `To fix this, try one of:
+` + `  1. Install the platform package: npm install ${packageName}
+` + `  2. Set QUACK_BINARY_PATH to point to your quack binary
+` + `  3. Download the binary from: https://github.com/adistrim/quack/releases
 
-// src/core/runner.ts
-function runCore(payload, timeoutMs = 30000) {
-  return new Promise((resolve, reject) => {
-    let binaryPath;
+` + `If you're using Docker or a bundler, set QUACK_BINARY_PATH explicitly.`);
+}
+function tryResolveFromNodeModules() {
+  const targetPlatform = getPlatformTarget();
+  const packageName = `quack-search-${targetPlatform}`;
+  const binaryName = getBinaryName();
+  const thisDir = getModuleDir();
+  const searchPaths = [
+    join(thisDir, "..", "..", "..", "node_modules", packageName, "bin", binaryName),
+    join(thisDir, "..", "..", "node_modules", packageName, "bin", binaryName),
+    join(thisDir, "..", "..", packageName, "bin", binaryName),
+    join(thisDir, "..", "..", "..", ".pnpm", "node_modules", packageName, "bin", binaryName)
+  ];
+  const cwd = process.cwd();
+  searchPaths.push(join(cwd, "node_modules", packageName, "bin", binaryName), join(cwd, "..", "node_modules", packageName, "bin", binaryName));
+  for (const searchPath of searchPaths) {
+    const resolved = resolve(searchPath);
+    if (existsSync(resolved)) {
+      try {
+        assertExecutable(resolved);
+        return resolved;
+      } catch {}
+    }
+  }
+  return null;
+}
+function tryResolveLocalBinary() {
+  const binaryName = getBinaryName();
+  const thisDir = getModuleDir();
+  const localPaths = [
+    join(thisDir, "..", "..", "bin", binaryName),
+    join(thisDir, "..", "bin", binaryName),
+    join(thisDir, "bin", binaryName)
+  ];
+  const cacheDir = getCacheDir();
+  localPaths.push(join(cacheDir, binaryName));
+  for (const localPath of localPaths) {
+    const resolved = resolve(localPath);
+    if (existsSync(resolved)) {
+      try {
+        assertExecutable(resolved);
+        return resolved;
+      } catch {}
+    }
+  }
+  return null;
+}
+function getCacheDir() {
+  const home = homedir();
+  if (platform === "win32") {
+    return join(env.LOCALAPPDATA || join(home, "AppData", "Local"), "quack-search");
+  }
+  return join(env.XDG_CACHE_HOME || join(home, ".cache"), "quack-search");
+}
+function assertExecutable(filePath) {
+  try {
+    accessSync(filePath, constants.X_OK);
+  } catch {
+    throw new QuackBinaryError(`Binary exists but is not executable: ${filePath}`, "BINARY_NOT_EXECUTABLE", `Run: chmod +x "${filePath}"`);
+  }
+}
+function getModuleDir() {
+  if (typeof import.meta.dir === "string") {
+    return import.meta.dir;
+  }
+  return dirname(fileURLToPath(import.meta.url));
+}
+function checkBinaryStatus() {
+  const base = { platform, arch };
+  try {
+    const result = tryResolveBinary();
+    return {
+      ...base,
+      found: true,
+      path: result.path,
+      source: result.source
+    };
+  } catch (err) {
+    return {
+      ...base,
+      found: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+function ensureBinary() {
+  const status = checkBinaryStatus();
+  if (!status.found) {
+    const targetPlatform = getPlatformTarget();
+    const packageName = `quack-search-${targetPlatform}`;
+    throw new QuackBinaryError(`Quack binary not available for ${status.platform} ${status.arch}`, "BINARY_NOT_AVAILABLE", `To fix this:
+` + `  1. Install platform package: npm install ${packageName}
+` + `  2. Or set QUACK_BINARY_PATH environment variable
+` + `  3. Or download explicitly: await downloadBinary()
+
+` + `For Docker/CI: Set QUACK_BINARY_PATH or call downloadBinary() at build time.`);
+  }
+}
+
+// src/core/download.ts
+import { existsSync as existsSync2, mkdirSync, chmodSync, createWriteStream, unlinkSync } from "fs";
+import { join as join2, dirname as dirname2 } from "path";
+import { homedir as homedir2 } from "os";
+var GITHUB_RELEASE_BASE = "https://github.com/adistrim/quack/releases/download";
+function getCacheDir2() {
+  const home = homedir2();
+  if (process.platform === "win32") {
+    return join2(process.env.LOCALAPPDATA || join2(home, "AppData", "Local"), "quack-search");
+  }
+  return join2(process.env.XDG_CACHE_HOME || join2(home, ".cache"), "quack-search");
+}
+var bootstrapPromise = null;
+async function ensureBinaryReady() {
+  if (bootstrapPromise) {
+    return bootstrapPromise;
+  }
+  bootstrapPromise = doBootstrap();
+  try {
+    return await bootstrapPromise;
+  } catch (err) {
+    bootstrapPromise = null;
+    throw err;
+  }
+}
+async function doBootstrap() {
+  const status = checkBinaryStatus();
+  if (status.found && status.path) {
+    return status.path;
+  }
+  const cacheDir = getCacheDir2();
+  const platform2 = getPlatformTarget();
+  const binaryName = getBinaryName();
+  const cachePath = join2(cacheDir, binaryName);
+  if (existsSync2(cachePath)) {
     try {
-      binaryPath = resolveBinaryPath();
-    } catch (err) {
-      reject(err);
-      return;
+      const { accessSync: accessSync2, constants: constants2 } = await import("fs");
+      accessSync2(cachePath, constants2.X_OK);
+      return cachePath;
+    } catch {}
+  }
+  try {
+    const result = await downloadBinary({
+      targetDir: cacheDir,
+      version: "latest",
+      platform: platform2,
+      verbose: false
+    });
+    return result.binaryPath;
+  } catch (downloadErr) {
+    throw new QuackBinaryError(`Could not find or download quack binary for ${process.platform} ${process.arch}`, "BOOTSTRAP_FAILED", `Automatic download failed. To fix this:
+  1. Check your internet connection
+  2. Or install manually: npm install quack-search-${platform2}
+  3. Or set QUACK_BINARY_PATH to a pre-downloaded binary
+
+Original error: ${downloadErr instanceof Error ? downloadErr.message : String(downloadErr)}`);
+  }
+}
+async function downloadBinary(options = {}) {
+  const {
+    targetDir = getDefaultBinDir(),
+    version = "latest",
+    platform: platform2 = getPlatformTarget(),
+    verbose = false
+  } = options;
+  const binaryName = getBinaryName();
+  const targetPath = join2(targetDir, binaryName);
+  if (!existsSync2(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+  const resolvedVersion = version === "latest" ? await fetchLatestVersion() : version;
+  const downloadUrl = buildDownloadUrl(platform2, resolvedVersion);
+  if (verbose) {
+    console.log(`Downloading quack binary...`);
+    console.log(`  Platform: ${platform2}`);
+    console.log(`  Version: ${resolvedVersion}`);
+    console.log(`  URL: ${downloadUrl}`);
+    console.log(`  Target: ${targetPath}`);
+  }
+  await downloadFile(downloadUrl, targetPath);
+  if (process.platform !== "win32") {
+    chmodSync(targetPath, 493);
+  }
+  if (verbose) {
+    console.log(`Binary downloaded successfully!`);
+  }
+  return {
+    binaryPath: targetPath,
+    version: resolvedVersion,
+    platform: platform2
+  };
+}
+async function fetchLatestVersion() {
+  try {
+    const response = await fetch("https://api.github.com/repos/adistrim/quack/releases/latest", {
+      headers: {
+        Accept: "application/vnd.github.v3+json",
+        "User-Agent": "quack-search"
+      }
+    });
+    if (!response.ok) {
+      throw new QuackBinaryError(`Failed to fetch latest version: GitHub API returned ${response.status}`, "VERSION_FETCH_FAILED", `Specify an explicit version instead, e.g.: downloadBinary({ version: 'v0.1.0' })`);
+    }
+    const data = await response.json();
+    if (!data.tag_name) {
+      throw new QuackBinaryError("Invalid response from GitHub API: missing tag_name", "VERSION_PARSE_FAILED", `Specify an explicit version instead, e.g.: downloadBinary({ version: 'v0.1.0' })`);
+    }
+    return data.tag_name;
+  } catch (err) {
+    if (err instanceof QuackBinaryError) {
+      throw err;
+    }
+    throw new QuackBinaryError("Failed to fetch latest version from GitHub", "VERSION_FETCH_FAILED", `Network error or GitHub unavailable. Specify an explicit version, e.g.: downloadBinary({ version: 'v0.1.0' })`);
+  }
+}
+function buildDownloadUrl(platform2, version) {
+  const assetMap = {
+    "darwin-arm64": "quack-darwin-arm64",
+    "darwin-x64": "quack-darwin-x64",
+    "linux-x64": "quack-linux-x64",
+    "linux-arm64": "quack-linux-arm64",
+    "windows-x64": "quack-windows-x64.exe",
+    "windows-arm64": "quack-windows-arm64.exe"
+  };
+  const assetName = assetMap[platform2];
+  return `${GITHUB_RELEASE_BASE}/${version}/${assetName}`;
+}
+async function downloadFile(url, targetPath) {
+  const response = await fetch(url, {
+    headers: {
+      "User-Agent": "quack-search"
+    }
+  });
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new QuackBinaryError(`Binary not found at ${url}`, "DOWNLOAD_NOT_FOUND", `The release may not exist or the platform is not supported.
+Check available releases at: https://github.com/adistrim/quack/releases`);
+    }
+    throw new QuackBinaryError(`Failed to download binary: HTTP ${response.status}`, "DOWNLOAD_FAILED", `URL: ${url}`);
+  }
+  const body = response.body;
+  if (!body) {
+    throw new QuackBinaryError("Empty response body", "DOWNLOAD_EMPTY");
+  }
+  if (existsSync2(targetPath)) {
+    unlinkSync(targetPath);
+  }
+  const fileStream = createWriteStream(targetPath);
+  const reader = body.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      fileStream.write(value);
+    }
+    fileStream.end();
+    await new Promise((resolve2, reject) => {
+      fileStream.on("finish", resolve2);
+      fileStream.on("error", reject);
+    });
+  } catch (err) {
+    fileStream.close();
+    if (existsSync2(targetPath)) {
+      unlinkSync(targetPath);
+    }
+    throw new QuackBinaryError("Failed to write binary file", "DOWNLOAD_WRITE_FAILED", err instanceof Error ? err.message : String(err));
+  }
+}
+function getDefaultBinDir() {
+  const thisDir = dirname2(new URL(import.meta.url).pathname);
+  return join2(thisDir, "..", "..", "bin");
+}
+function needsDownload() {
+  return !checkBinaryStatus().found;
+}
+
+// src/core/runner.ts
+class QuackRuntimeError extends Error {
+  code;
+  details;
+  constructor(message, code, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "QuackRuntimeError";
+  }
+}
+async function runCore(payload, timeoutMs = 30000) {
+  let binaryPath;
+  try {
+    binaryPath = await ensureBinaryReady();
+  } catch (err) {
+    if (err instanceof QuackBinaryError) {
+      throw err;
     }
+    throw new QuackRuntimeError("Failed to prepare quack binary", "BOOTSTRAP_FAILED", err instanceof Error ? err.message : String(err));
+  }
+  return executeCore(binaryPath, payload, timeoutMs);
+}
+function executeCore(binaryPath, payload, timeoutMs) {
+  return new Promise((resolve2, reject) => {
     const proc = spawn(binaryPath, {
       stdio: ["pipe", "pipe", "pipe"]
     });
@@ -44,7 +402,7 @@ function runCore(payload, timeoutMs = 30000) {
     let stderr = "";
     const timeout = setTimeout(() => {
       proc.kill();
-      reject(new Error("core process timed out"));
+      reject(new QuackRuntimeError(`Core process timed out after ${timeoutMs}ms`, "TIMEOUT", `Binary: ${binaryPath}`));
     }, timeoutMs);
     proc.stdout.on("data", (d) => {
       stdout += d.toString();
@@ -54,30 +412,39 @@ function runCore(payload, timeoutMs = 30000) {
     });
     proc.on("error", (err) => {
       clearTimeout(timeout);
-      reject(err);
+      if (err.code === "ENOENT") {
+        reject(new QuackRuntimeError(`Binary not found or not executable: ${binaryPath}`, "ENOENT", `The binary path was resolved but the file doesn't exist or isn't accessible.
+` + `Check that the binary exists and has execute permissions.`));
+        return;
+      }
+      if (err.code === "EACCES") {
+        reject(new QuackRuntimeError(`Permission denied executing binary: ${binaryPath}`, "EACCES", `Run: chmod +x "${binaryPath}"`));
+        return;
+      }
+      reject(new QuackRuntimeError(`Failed to spawn core process: ${err.message}`, "SPAWN_ERROR", `Binary: ${binaryPath}`));
     });
     proc.on("close", (code) => {
       clearTimeout(timeout);
       if (code !== 0) {
-        reject(new Error(stderr || "core process failed"));
+        reject(new QuackRuntimeError(stderr || `Core process exited with code ${code}`, "PROCESS_FAILED", `Exit code: ${code}, Binary: ${binaryPath}`));
         return;
       }
       let parsed;
       try {
         parsed = JSON.parse(stdout);
       } catch {
-        reject(new Error("invalid JSON returned from core"));
+        reject(new QuackRuntimeError("Invalid JSON returned from core", "INVALID_RESPONSE", `Raw output: ${stdout.slice(0, 200)}${stdout.length > 200 ? "..." : ""}`));
         return;
       }
       if (parsed.error) {
-        reject(new Error(parsed.error));
+        reject(new QuackRuntimeError(parsed.error, "CORE_ERROR"));
         return;
       }
       if (!parsed.results && !parsed.fetch) {
-        reject(new Error("empty response from core"));
+        reject(new QuackRuntimeError("Empty response from core", "EMPTY_RESPONSE"));
         return;
       }
-      resolve(parsed);
+      resolve2(parsed);
     });
     proc.stdin.write(JSON.stringify(payload));
     proc.stdin.end();
@@ -103,5 +470,13 @@ async function fetchContent(url, timeoutMs) {
 }
 export {
   search,
-  fetchContent
+  resolveBinaryPath,
+  needsDownload,
+  getPlatformTarget,
+  fetchContent,
+  ensureBinary,
+  downloadBinary,
+  checkBinaryStatus,
+  QuackRuntimeError,
+  QuackBinaryError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quack-search",
-  "version": "0.0.4",
+  "version": "0.1.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,10 +20,12 @@
     "typescript": "^5"
   },
   "optionalDependencies": {
-    "quack-search-darwin-arm64": "0.0.4",
-    "quack-search-darwin-x64": "0.0.4",
-    "quack-search-linux-x64": "0.0.4",
-    "quack-search-windows-x64": "0.0.4"
+    "quack-search-darwin-arm64": "0.1.1",
+    "quack-search-darwin-x64": "0.1.1",
+    "quack-search-linux-x64": "0.1.1",
+    "quack-search-linux-arm64": "0.1.1",
+    "quack-search-windows-x64": "0.1.1",
+    "quack-search-windows-arm64": "0.1.1"
   },
   "repository": {
     "type": "git",