ubersearch 1.6.2 → 1.7.0

package/README.md

@@ -69,8 +69,10 @@ ubersearch "query" [options]
 Options:
   --json                        Output results as JSON
   --engines engine1,engine2     Use specific engines
-  --strategy all|first-success  Search strategy (default: all)
+  --strategy all|first-success  Search strategy (default: first-success)
   --limit number                Max results per engine
+  --categories categories       Categories filter for SearXNG (e.g., "it,science")
+  --config path                 Config file path
   --include-raw                 Include raw provider responses
   --help, -h                    Show help
   health                        Run provider health checks (starts Docker-backed ones if needed)
@@ -286,7 +288,7 @@ tavily (10 results)
 
 ## Search Strategies
 
-### All (Default)
+### All
 
 Queries all configured/enabled providers and combines results.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ubersearch",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "module": "src/index.ts",
   "type": "module",
   "bin": {
@@ -41,9 +41,9 @@
   },
   "scripts": {
     "prepare": "git config core.hooksPath scripts/hooks",
-    "lint": "bunx biome check .",
-    "lint:fix": "bunx biome check --write .",
-    "format": "bunx biome format --write .",
+    "lint": "bunx biome check src/ test/ scripts/ docs/ *.json *.md",
+    "lint:fix": "bunx biome check --write src/ test/ scripts/ docs/ *.json *.md",
+    "format": "bunx biome format --write src/ test/ scripts/ docs/ *.json *.md",
     "test": "SKIP_DOCKER_TESTS=true bun test --preload ./test/setup.ts test/",
     "test:unit": "bun test --preload ./test/setup.ts test/unit/",
     "test:integration": "bun test --preload ./test/setup.ts test/integration/",
@@ -55,7 +55,7 @@
     "mcp": "bun run src/cli.ts mcp",
     "mcp:test": "bun run scripts/test-mcp.ts",
     "build": "bun run scripts/build.ts",
-    "build:binary": "bun build --compile --minify src/cli.ts --outfile dist/ubersearch",
+    "build:binary": "bun build --compile --minify src/cli.ts --outfile dist/ubersearch && bun run scripts/copy-searxng-assets.ts",
     "semantic-release": "semantic-release",
     "semantic-release:dry-run": "semantic-release --dry-run",
     "release": "bun run build && bun run semantic-release"

package/src/bootstrap/container.ts

@@ -11,7 +11,7 @@ import { CreditManager } from "../core/credits";
 import { FileCreditStateProvider } from "../core/credits/FileCreditStateProvider";
 import { createLogger } from "../core/logger";
 import { UberSearchOrchestrator } from "../core/orchestrator";
-import type { ILifecycleProvider, SearchProvider } from "../core/provider";
+import type { SearchProvider } from "../core/provider";
 import { ProviderRegistry } from "../core/provider";
 import { ProviderFactory } from "../core/provider/ProviderFactory";
 import { ServiceKeys } from "../core/serviceKeys";
@@ -156,17 +156,3 @@ export async function bootstrapContainer(
 function createProvider(engineConfig: EngineConfig): SearchProvider {
   return ProviderFactory.createProvider(engineConfig, container);
 }
-
-/**
- * Helper function to check if a provider implements ILifecycleProvider
- */
-export function isLifecycleProvider(provider: unknown): provider is ILifecycleProvider {
-  return (
-    provider != null &&
-    typeof provider === "object" &&
-    "init" in provider &&
-    typeof provider.init === "function" &&
-    "healthcheck" in provider &&
-    typeof provider.healthcheck === "function"
-  );
-}

package/src/cli.ts

@@ -5,10 +5,11 @@
  * Unified search interface for multiple search providers
  */
 
-import { bootstrapContainer, isLifecycleProvider } from "./bootstrap/container";
+import { bootstrapContainer } from "./bootstrap/container";
 import type { ProviderRegistry } from "./core/provider";
 import { ServiceKeys } from "./core/serviceKeys";
 import { serve as serveMcp } from "./mcp-server";
+import { isLifecycleProvider } from "./plugin/types.js";
 import type { UberSearchOutput } from "./tool/interface";
 import { getCreditStatus, uberSearch } from "./tool/uberSearchTool";
 

package/src/config/load.ts

@@ -14,28 +14,11 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { getBundledSearxngComposePath } from "../core/paths";
 import { PluginRegistry, registerBuiltInPlugins } from "../plugin";
 import type { ConfigFactory, ExtendedSearchConfig } from "./defineConfig";
 import { formatValidationErrors, validateConfigSafe } from "./validation";
 
-/**
- * Get package root directory
- * Handles both development (src/) and bundled (dist/) environments
- */
-function getPackageRoot(): string {
-  const currentFile = fileURLToPath(import.meta.url);
-  const currentDir = dirname(currentFile);
-
-  // Check if we're in dist/ or src/
-  if (currentDir.includes("/dist")) {
-    // Bundled: dist/cli.js -> go up 1 level
-    return dirname(currentDir);
-  }
-  // Development: src/config/load.ts -> go up 2 levels
-  return dirname(dirname(currentDir));
-}
-
 /** Supported config file extensions */
 const CONFIG_EXTENSIONS = [".ts", ".json"] as const;
 
@@ -210,8 +193,7 @@ function getDefaultConfig(): ExtendedSearchConfig {
   const defaultEngineOrder: string[] = [];
 
   // Always add SearXNG first - it's free and unlimited (requires Docker)
-  const packageRoot = getPackageRoot();
-  const composeFile = join(packageRoot, "providers", "searxng", "docker-compose.yml");
+  const composeFile = getBundledSearxngComposePath();
 
   defaultEngineOrder.push("searchxng");
   engines.push({

package/src/core/credits/CreditManager.ts

@@ -100,6 +100,24 @@ export class CreditManager {
     return result;
   }
 
+  /**
+   * Refund credits for a failed search
+   * @note This does NOT persist the state - call saveState() separately
+   */
+  refund(engineId: EngineId): void {
+    const config = this.engines.get(engineId);
+    if (!config) {
+      throw new Error(`Unknown engine: ${engineId}`);
+    }
+
+    const record = this.state[engineId];
+    if (!record) {
+      throw new Error(`No credit record for engine: ${engineId}`);
+    }
+
+    record.used = Math.max(0, record.used - config.creditCostPerSearch);
+  }
+
   /**
    * Check if engine has sufficient credits
    */

package/src/core/docker/dockerComposeHelper.ts

@@ -4,13 +4,13 @@
  * Manages Docker Compose services for local providers
  */
 
-import { exec, execSync } from "node:child_process";
+import { execFile } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { getSearxngPaths } from "../paths";
 
-const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
 
 /**
  * Get or generate a persistent SearXNG secret key
@@ -30,9 +30,7 @@ function getSearxngSecret(configDir: string): string {
   }
 
   // Generate a new secret using crypto
-  const secret = [...Array(64)]
-    .map(() => Math.floor(Math.random() * 16).toString(16))
-    .join("");
+  const secret = [...Array(64)].map(() => Math.floor(Math.random() * 16).toString(16)).join("");
   try {
     writeFileSync(secretFile, secret, { mode: 0o600 });
   } catch {
@@ -59,15 +57,15 @@ export class DockerComposeHelper {
     args: string[],
     options: DockerComposeOptions = {},
   ): Promise<string> {
-    const cmd = `docker compose -f "${this.composeFile}" ${args.join(" ")}`;
     const cwd = options.cwd || this.getComposeDir();
     const timeout = options.timeout || 30000;
+    const cmdArgs = ["compose", "-f", this.composeFile, ...args];
 
     try {
       // Get SearXNG paths and ensure directories exist
       const { configDir, dataDir } = getSearxngPaths();
 
-      const { stdout, stderr } = await execAsync(cmd, {
+      const { stdout, stderr } = await execFileAsync("docker", cmdArgs, {
         cwd,
         timeout,
         env: {
@@ -90,7 +88,7 @@ export class DockerComposeHelper {
 
       const errorDetails = [
         `Docker Compose command ${timedOut ? "timed out" : "failed"}: ${errorMessage}`,
-        `Command: ${cmd}`,
+        `Command: docker compose -f ${this.composeFile} ${args.join(" ")}`,
       ];
       if (err.stdout) {
         errorDetails.push(`Output: ${err.stdout}`);
@@ -192,7 +190,7 @@ export class DockerComposeHelper {
    */
   static async isDockerAvailable(): Promise<boolean> {
     try {
-      await execAsync("docker version", { timeout: 5000 });
+      await execFileAsync("docker", ["version"], { timeout: 5000 });
       return true;
     } catch {
       return false;

package/src/core/docker/dockerLifecycleManager.ts

@@ -63,21 +63,20 @@ export class DockerLifecycleManager {
    * @throws Error if container startup fails
    */
   async init(): Promise<void> {
-    if (this.initPromise) {
-      return this.initPromise;
-    }
+    // Atomic check-and-set pattern to prevent race conditions
+    if (!this.initPromise) {
+      if (!this.config.autoStart || !this.dockerHelper) {
+        this.initialized = true;
+        return;
+      }
 
-    if (!this.config.autoStart || !this.dockerHelper) {
-      this.initialized = true;
-      return;
+      this.initPromise = this.performInit().catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        log.debug("Initialization failed:", message);
+        this.initialized = false;
+        throw error;
+      });
     }
-
-    this.initPromise = this.performInit().catch((error) => {
-      const message = error instanceof Error ? error.message : String(error);
-      log.debug("Initialization failed:", message);
-      this.initialized = false;
-      throw error;
-    });
     return this.initPromise;
   }
 
@@ -162,20 +161,20 @@ export class DockerLifecycleManager {
     // Try health endpoint first - works for any running instance
     // (even if started manually, via different docker-compose, or k8s, etc.)
     if (this.config.healthEndpoint) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 3000);
       try {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), 3000);
-
         const response = await fetch(this.config.healthEndpoint, {
           signal: controller.signal,
         });
 
-        clearTimeout(timeoutId);
         if (response.ok) {
           return true;
         }
       } catch {
         // Health endpoint failed, fall through to Docker check
+      } finally {
+        clearTimeout(timeoutId);
       }
     }
 
@@ -269,6 +268,23 @@ export class DockerLifecycleManager {
     const errors: string[] = [];
     const warnings: string[] = [];
 
+    // Validate config fields first (these don't require Docker)
+
+    // Check health endpoint if configured
+    if (this.config.healthEndpoint) {
+      try {
+        // Try to parse the URL
+        new URL(this.config.healthEndpoint);
+      } catch {
+        warnings.push(`Health endpoint URL is invalid: ${this.config.healthEndpoint}`);
+      }
+    }
+
+    // Check container name if specified
+    if (this.config.containerName && !/^[a-zA-Z0-9_-]+$/.test(this.config.containerName)) {
+      warnings.push(`Container name contains invalid characters: ${this.config.containerName}`);
+    }
+
     // Check Docker is available
     const dockerAvailable = await DockerComposeHelper.isDockerAvailable();
     if (!dockerAvailable) {
@@ -297,21 +313,6 @@ export class DockerLifecycleManager {
       }
     }
 
-    // Check health endpoint if configured
-    if (this.config.healthEndpoint) {
-      try {
-        // Try to parse the URL
-        new URL(this.config.healthEndpoint);
-      } catch {
-        warnings.push(`Health endpoint URL is invalid: ${this.config.healthEndpoint}`);
-      }
-    }
-
-    // Check container name if specified
-    if (this.config.containerName && !/^[a-zA-Z0-9_-]+$/.test(this.config.containerName)) {
-      warnings.push(`Container name contains invalid characters: ${this.config.containerName}`);
-    }
-
     return {
       valid: errors.length === 0,
       errors,
@@ -333,6 +334,13 @@ export class DockerLifecycleManager {
     return this.initialized;
   }
 
+  /**
+   * Check if initialization is currently in progress
+   */
+  isInitializing(): boolean {
+    return this.initPromise !== null;
+  }
+
   /**
    * Check if container is running
    *

package/src/core/paths.ts

@@ -7,7 +7,7 @@
 
 import { copyFileSync, existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const APP_NAME = "ubersearch";
@@ -108,17 +108,58 @@ export function getPackageRoot(): string {
   return dirname(dirname(currentDir));
 }
 
+/**
+ * Get candidate runtime roots where bundled SearXNG assets may live.
+ *
+ * This covers:
+ * - source checkouts (`<root>/providers/searxng`)
+ * - built JS output (`<root>/dist/providers/searxng`)
+ * - compiled binaries with copied assets next to the executable
+ */
+function getRuntimeRoots(): string[] {
+  const roots = new Set<string>();
+
+  roots.add(resolve(getPackageRoot()));
+  roots.add(resolve(dirname(process.execPath)));
+  roots.add(resolve(process.cwd()));
+
+  return [...roots];
+}
+
+function getBundledSearxngAssetCandidates(relativePath: string): string[] {
+  const candidates = new Set<string>();
+
+  for (const root of getRuntimeRoots()) {
+    candidates.add(join(root, "providers", "searxng", relativePath));
+    candidates.add(join(root, "dist", "providers", "searxng", relativePath));
+  }
+
+  return [...candidates];
+}
+
+function resolveBundledSearxngAsset(relativePath: string): string {
+  const candidates = getBundledSearxngAssetCandidates(relativePath);
+  const existing = candidates.find((candidate) => existsSync(candidate));
+
+  if (existing) {
+    return existing;
+  }
+
+  return candidates[0] ?? join(getPackageRoot(), "providers", "searxng", relativePath);
+}
+
+/**
+ * Get the bundled SearXNG docker-compose file path.
+ */
+export function getBundledSearxngComposePath(): string {
+  return resolveBundledSearxngAsset("docker-compose.yml");
+}
+
 /**
  * Get the bundled default settings.yml path
  */
 export function getDefaultSettingsPath(): string {
-  const packageRoot = getPackageRoot();
-  // In bundled mode, look in dist/providers/searxng/
-  // In dev mode, look in providers/searxng/
-  if (packageRoot.endsWith("/dist")) {
-    return join(packageRoot, "providers", "searxng", "config", "settings.yml");
-  }
-  return join(packageRoot, "providers", "searxng", "config", "settings.yml");
+  return resolveBundledSearxngAsset(join("config", "settings.yml"));
 }
 
 /**

package/src/core/strategy/AllProvidersStrategy.ts

@@ -81,8 +81,8 @@ export class AllProvidersStrategy implements ISearchStrategy {
         continue;
       }
 
-      // Check credit availability
-      if (!context.creditManager.hasSufficientCredits(engineId)) {
+      // Charge credits before search (atomic check+deduct to avoid race conditions)
+      if (!context.creditManager.charge(engineId)) {
         attempts.push({ engineId, success: false, reason: "out_of_credit" });
         continue;
       }
@@ -98,13 +98,6 @@ export class AllProvidersStrategy implements ISearchStrategy {
           }),
         );
 
-        // Deduct credits
-        if (!context.creditManager.charge(engineId)) {
-          // This shouldn't happen because we checked above, but handle gracefully
-          attempts.push({ engineId, success: false, reason: "out_of_credit" });
-          continue;
-        }
-
         // Record success
         attempts.push({ engineId, success: true });
 
@@ -115,6 +108,9 @@ export class AllProvidersStrategy implements ISearchStrategy {
           results.push(...response.items);
         }
       } catch (error) {
+        // Refund credits for failed search
+        context.creditManager.refund(engineId);
+
         // Record failure
         if (error instanceof SearchError) {
           attempts.push({ engineId, success: false, reason: error.reason });
@@ -163,7 +159,8 @@ export class AllProvidersStrategy implements ISearchStrategy {
         continue;
       }
 
-      if (!context.creditManager.hasSufficientCredits(engineId)) {
+      // Charge credits before search (atomic check+deduct to avoid race conditions)
+      if (!context.creditManager.charge(engineId)) {
         ineligibleAttempts.push({ engineId, success: false, reason: "out_of_credit" });
         continue;
       }
@@ -215,6 +212,9 @@ export class AllProvidersStrategy implements ISearchStrategy {
       const { response, error } = settledResult.value;
 
       if (error) {
+        // Refund credits for failed search
+        context.creditManager.refund(engineId);
+
         // Search threw an error
         if (error instanceof SearchError) {
           attempts.push({ engineId, success: false, reason: error.reason });
@@ -226,12 +226,6 @@ export class AllProvidersStrategy implements ISearchStrategy {
       }
 
       if (response) {
-        // Deduct credits
-        if (!context.creditManager.charge(engineId)) {
-          attempts.push({ engineId, success: false, reason: "out_of_credit" });
-          continue;
-        }
-
         // Record success
         attempts.push({ engineId, success: true });
 

package/src/core/strategy/FirstSuccessStrategy.ts

@@ -53,8 +53,8 @@ export class FirstSuccessStrategy implements ISearchStrategy {
         continue;
       }
 
-      // Check credit availability
-      if (!context.creditManager.hasSufficientCredits(engineId)) {
+      // Charge credits before search (atomic check+deduct to avoid race conditions)
+      if (!context.creditManager.charge(engineId)) {
         attempts.push({ engineId, success: false, reason: "out_of_credit" });
         continue;
       }
@@ -70,18 +70,15 @@ export class FirstSuccessStrategy implements ISearchStrategy {
           }),
         );
 
-        // Deduct credits
-        if (!context.creditManager.charge(engineId)) {
-          attempts.push({ engineId, success: false, reason: "out_of_credit" });
-          continue;
-        }
-
         // Record success
         attempts.push({ engineId, success: true });
 
         // Return immediately with results from this provider
         return { results: response.items, attempts };
       } catch (error) {
+        // Refund credits for failed search
+        context.creditManager.refund(engineId);
+
         // Record failure and continue to next provider
         if (error instanceof SearchError) {
           attempts.push({ engineId, success: false, reason: error.reason });

package/src/mcp-server.ts

@@ -7,32 +7,27 @@
  */
 
 import { bootstrapContainer, getCreditStatus, uberSearch } from "./app/index";
-import { isLifecycleProvider } from "./bootstrap/container";
 import type { ProviderRegistry } from "./core/provider";
 import { ServiceKeys } from "./core/serviceKeys";
+import { isLifecycleProvider } from "./plugin/types.js";
 
 interface MCPRequest {
   jsonrpc: string;
   id?: number | string;
   method: string;
-  params?: any;
+  params?: Record<string, unknown>;
 }
 
 interface MCPTool {
   name: string;
   description: string;
-  inputSchema: any;
-}
-
-interface MCPToolCallParams {
-  name: string;
-  arguments: Record<string, any>;
+  inputSchema: Record<string, unknown>;
 }
 
 interface MCPResponse {
   jsonrpc: string;
   id?: number | string;
-  result?: any;
+  result?: unknown;
   error?: {
     code?: number;
     message: string;
@@ -168,23 +163,29 @@ Example: "it,science" for tech and academic results`,
     }
 
     if (request.method === "tools/call") {
-      const { name, arguments: args } = request.params as MCPToolCallParams;
+      const params = request.params ?? {};
+      const name = String(params.name ?? "");
+      const args =
+        typeof params.arguments === "object" && params.arguments !== null
+          ? (params.arguments as Record<string, string>)
+          : ({} as Record<string, string>);
 
       try {
-        let result: any;
+        let result: unknown;
         if (name === "uber_search") {
-          const engines = args.engines
-            ? args.engines.split(",").map((e: string) => e.trim())
-            : undefined;
+          const engines = args.engines ? args.engines.split(",").map((e) => e.trim()) : undefined;
           const categories = args.categories
-            ? args.categories.split(",").map((c: string) => c.trim())
+            ? args.categories.split(",").map((c) => c.trim())
             : undefined;
           result = await withTimeout(
             uberSearch({
-              query: args.query,
-              limit: args.limit,
+              query: args.query ?? "",
+              limit: args.limit ? Number(args.limit) : undefined,
               engines,
-              strategy: args.strategy,
+              strategy:
+                args.strategy === "all" || args.strategy === "first-success"
+                  ? args.strategy
+                  : undefined,
               categories,
             }),
             60000,

package/src/providers/searchxng.ts

@@ -79,7 +79,7 @@ export class SearchxngProvider
     let isHealthy = await this.healthcheck();
 
     if (!isHealthy) {
-      const isInitializing = !!(await (this.lifecycleManager as any).initPromise);
+      const isInitializing = this.lifecycleManager.isInitializing();
       if (!isInitializing) {
         try {
           log.debug("Container not healthy, attempting auto-start...");