ubersearch 1.6.2 → 1.7.1

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.1",
   "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/providers/searxng/.env.example

@@ -2,7 +2,7 @@
 # Copy this file to .env and update values
 
 # Secret key for SearXNG (generate with: openssl rand -hex 32)
-SEARXNG_SECRET_KEY=your-secret-key-here
+SEARXNG_SECRET=your-secret-key-here
 
 # API key for ubersearch integration
 # Generate with: openssl rand -hex 16

package/src/bootstrap/container.ts

@@ -9,9 +9,10 @@ import type { EngineConfig, UberSearchConfig } from "../config/types";
 import { type Container, container } from "../core/container";
 import { CreditManager } from "../core/credits";
 import { FileCreditStateProvider } from "../core/credits/FileCreditStateProvider";
+import { getErrorMessage } from "../core/errorUtils";
 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";
@@ -103,8 +104,8 @@ export async function bootstrapContainer(
         registry.register(provider);
         log.debug(`Registered provider: ${engineConfig.id}`);
       } catch (error) {
-        const errorMsg = error instanceof Error ? error.message : String(error);
-        log.debug(`Failed to register provider ${engineConfig.id}: ${errorMsg}`);
+        const errorMsg = getErrorMessage(error);
+        log.warn(`Failed to register provider ${engineConfig.id}: ${errorMsg}`);
         failedProviders.push(engineConfig.id);
       }
     }
@@ -156,17 +157,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,12 @@
  * Unified search interface for multiple search providers
  */
 
-import { bootstrapContainer, isLifecycleProvider } from "./bootstrap/container";
+import { bootstrapContainer } from "./bootstrap/container";
+import { getErrorMessage } from "./core/errorUtils";
 import type { ProviderRegistry } from "./core/provider";
 import { ServiceKeys } from "./core/serviceKeys";
 import { serve as serveMcp } from "./mcp-server";
+import { isLifecycleProvider } from "./plugin/types";
 import type { UberSearchOutput } from "./tool/interface";
 import { getCreditStatus, uberSearch } from "./tool/uberSearchTool";
 
@@ -101,12 +103,6 @@ if (args[0] === "health") {
   process.exit(0);
 }
 
-// MCP server command
-if (args[0] === "mcp") {
-  await serveMcp();
-  process.exit(0);
-}
-
 // Parse options
 const options = {
   json: args.includes("--json"),
@@ -213,7 +209,7 @@ async function main() {
       printHumanReadable(result);
     }
   } catch (error) {
-    console.error("Search failed:", error instanceof Error ? error.message : String(error));
+    console.error("Search failed:", getErrorMessage(error));
     process.exit(1);
   }
 }
@@ -332,7 +328,7 @@ async function runHealthChecks(configPath?: string) {
           });
           console.log(`✓ ${engineId.padEnd(15)} Healthy`);
         } catch (error) {
-          const message = error instanceof Error ? error.message : String(error);
+          const message = getErrorMessage(error);
           results.push({
             engineId,
             status: "unhealthy",
@@ -366,7 +362,7 @@ async function runHealthChecks(configPath?: string) {
 
     console.log();
   } catch (error) {
-    console.error("Health check failed:", error instanceof Error ? error.message : String(error));
+    console.error("Health check failed:", getErrorMessage(error));
     process.exit(1);
   }
 }
@@ -402,10 +398,7 @@ async function showCredits(configPath?: string) {
 
     console.log();
   } catch (error) {
-    console.error(
-      "Failed to load credits:",
-      error instanceof Error ? error.message : String(error),
-    );
+    console.error("Failed to load credits:", getErrorMessage(error));
     process.exit(1);
   }
 }

package/src/config/load.ts

@@ -14,28 +14,12 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { getErrorMessage } from "../core/errorUtils";
+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;
 
@@ -106,7 +90,10 @@ async function loadTypeScriptConfig(path: string): Promise<ExtendedSearchConfig>
     const configOrFactory = module.default ?? module.config;
 
     if (!configOrFactory) {
-      throw new Error(`Config file must export a default configuration or named 'config' export`);
+      throw new Error(
+        `Config file at ${path} must export a config object as 'default' or 'config'. ` +
+          `Found exports: ${Object.keys(module).join(", ") || "none"}`,
+      );
     }
 
     // Handle factory functions (async config)
@@ -116,9 +103,7 @@ async function loadTypeScriptConfig(path: string): Promise<ExtendedSearchConfig>
 
     return configOrFactory as ExtendedSearchConfig;
   } catch (error) {
-    throw new Error(
-      `Failed to load TypeScript config from ${path}: ${error instanceof Error ? error.message : String(error)}`,
-    );
+    throw new Error(`Failed to load TypeScript config from ${path}: ${getErrorMessage(error)}`);
   }
 }
 
@@ -210,8 +195,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({
@@ -219,12 +203,11 @@ function getDefaultConfig(): ExtendedSearchConfig {
     type: "searchxng",
     enabled: true,
     displayName: "SearXNG (Local)",
-    apiKeyEnv: "SEARXNG_API_KEY",
     endpoint: "http://localhost:8888/search",
     composeFile,
     containerName: "searxng",
     healthEndpoint: "http://localhost:8888/healthz",
-    defaultLimit: 15,
+    defaultLimit: 10,
     monthlyQuota: 10000,
     creditCostPerSearch: 0,
     lowCreditThresholdPercent: 80,
@@ -243,7 +226,7 @@ function getDefaultConfig(): ExtendedSearchConfig {
       displayName: "Brave Search",
       apiKeyEnv: "BRAVE_API_KEY",
       endpoint: "https://api.search.brave.com/res/v1/web/search",
-      defaultLimit: 15,
+      defaultLimit: 10,
       monthlyQuota: 2000,
       creditCostPerSearch: 1,
       lowCreditThresholdPercent: 80,
@@ -302,9 +285,7 @@ export async function loadConfig(
           rawConfig = loadJsonConfig(path);
         }
       } catch (error) {
-        throw new Error(
-          `Failed to load config file at ${path}: ${error instanceof Error ? error.message : String(error)}`,
-        );
+        throw new Error(`Failed to load config file at ${path}: ${getErrorMessage(error)}`);
       }
 
       // Resolve relative paths (like composeFile) to absolute paths
@@ -377,9 +358,7 @@ export function loadConfigSync(
       try {
         rawConfig = loadJsonConfig(path);
       } catch (error) {
-        throw new Error(
-          `Failed to parse config file at ${path}: ${error instanceof Error ? error.message : String(error)}`,
-        );
+        throw new Error(`Failed to parse config file at ${path}: ${getErrorMessage(error)}`);
       }
 
       // Resolve relative paths (like composeFile) to absolute paths

package/src/config/validation.ts

@@ -73,7 +73,28 @@ export const UberSearchConfigSchema = z
       })
       .optional(),
   })
-  .passthrough();
+  .passthrough()
+  .refine(
+    (config) => {
+      const ids = config.engines.map((e: { id: string }) => e.id);
+      return new Set(ids).size === ids.length;
+    },
+    {
+      message: "Duplicate engine IDs found in engines array",
+    },
+  )
+  .refine(
+    (config) => {
+      if (!config.defaultEngineOrder) {
+        return true;
+      }
+      const engineIds = new Set(config.engines.map((e: { id: string }) => e.id));
+      return config.defaultEngineOrder.every((id: string) => engineIds.has(id));
+    },
+    {
+      message: "defaultEngineOrder contains engine IDs not defined in engines array",
+    },
+  );
 
 // CLI input schema
 export const CliInputSchema = z.object({

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/credits/FileCreditStateProvider.ts

@@ -112,7 +112,7 @@ export class FileCreditStateProvider implements CreditStateProvider {
       // Write file using Bun's async API
       await Bun.write(this.statePath, JSON.stringify(state, null, 2));
     } catch (error) {
-      log.warn(`Failed to save credit state to ${this.statePath}:`, error);
+      log.error(`Failed to save credit state to ${this.statePath}:`, error);
     }
   }
 

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 { dirname, 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,8 @@ 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 bytes = crypto.getRandomValues(new Uint8Array(32));
+  const secret = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
   try {
     writeFileSync(secretFile, secret, { mode: 0o600 });
   } catch {
@@ -59,19 +58,21 @@ 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: {
-          ...process.env,
+          PATH: process.env.PATH,
+          HOME: process.env.HOME,
+          DOCKER_HOST: process.env.DOCKER_HOST,
           SEARXNG_CONFIG: configDir,
           SEARXNG_DATA: dataDir,
           SEARXNG_SECRET: getSearxngSecret(configDir),
@@ -90,7 +91,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}`);
@@ -107,7 +108,7 @@ export class DockerComposeHelper {
    * Get directory containing compose file
    */
   private getComposeDir(): string {
-    return require("node:path").dirname(this.composeFile);
+    return dirname(this.composeFile);
   }
 
   /**
@@ -175,13 +176,19 @@ export class DockerComposeHelper {
   async isRunning(service?: string, options?: DockerComposeOptions): Promise<boolean> {
     try {
       const output = await this.ps(options);
+      const lines = output.split("\n").filter((l) => l.trim());
 
       if (service) {
-        return output.includes(service) && !output.includes("Exit");
+        return lines.some((line) => {
+          const lower = line.toLowerCase();
+          return (
+            lower.includes(service.toLowerCase()) && /\bup\b/i.test(line) && !/exit/i.test(line)
+          );
+        });
       }
 
       // Check if any services are running
-      return output.includes("Up");
+      return lines.some((line) => /\bup\b/i.test(line));
     } catch (_error) {
       return false;
     }
@@ -192,7 +199,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

@@ -20,6 +20,7 @@
  * ```
  */
 
+import { getErrorMessage } from "../errorUtils";
 import { createLogger } from "../logger";
 import { bootstrapSearxngConfig } from "../paths";
 import { DockerComposeHelper } from "./dockerComposeHelper";
@@ -63,21 +64,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 = getErrorMessage(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;
   }
 
@@ -89,11 +89,19 @@ export class DockerLifecycleManager {
     timeoutMs: number,
     operation: string,
   ): Promise<T> {
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
     const timeoutPromise = new Promise<never>((_, reject) => {
-      setTimeout(() => reject(new Error(`${operation} timed out after ${timeoutMs}ms`)), timeoutMs);
+      timeoutId = setTimeout(
+        () => reject(new Error(`${operation} timed out after ${timeoutMs}ms`)),
+        timeoutMs,
+      );
     });
 
-    return Promise.race([promise, timeoutPromise]);
+    try {
+      return await Promise.race([promise, timeoutPromise]);
+    } finally {
+      clearTimeout(timeoutId);
+    }
   }
 
   private async performInit(): Promise<void> {
@@ -142,7 +150,7 @@ export class DockerLifecycleManager {
 
       this.initialized = true;
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = getErrorMessage(error);
       log.debug("Failed to start container:", message);
       throw error;
     } finally {
@@ -162,20 +170,23 @@ 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
+        log.debug(`Health endpoint returned non-ok status: ${response.status}`);
+      } catch (error) {
+        const msg = getErrorMessage(error);
+        log.debug(`Health endpoint check failed: ${msg}`);
+        // Fall through to Docker status check
+      } finally {
+        clearTimeout(timeoutId);
       }
     }
 
@@ -244,7 +255,7 @@ export class DockerLifecycleManager {
       );
       log.debug("Container stopped.");
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = getErrorMessage(error);
       log.debug("Failed to stop container:", message);
       // Don't throw on shutdown errors
     }
@@ -269,6 +280,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) {
@@ -290,28 +318,13 @@ export class DockerLifecycleManager {
         const projectRoot = this.config.projectRoot || process.cwd();
         await this.dockerHelper.ps({ cwd: projectRoot });
       } catch (error: unknown) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = getErrorMessage(error);
         if (message.includes("config")) {
           errors.push(`Invalid compose file: ${message}`);
         }
       }
     }
 
-    // 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 +346,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
    *
@@ -349,7 +369,7 @@ export class DockerLifecycleManager {
         cwd: projectRoot,
       });
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = getErrorMessage(error);
       log.debug("Error checking if container is running:", message);
       return false;
     }

package/src/core/errorUtils.ts

@@ -0,0 +1,6 @@
+/**
+ * Safely extracts an error message from an unknown error value.
+ */
+export function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}