ubersearch 0.0.0-development

package/src/core/orchestrator.ts

@@ -0,0 +1,103 @@
+/**
+ * Multi-Search Orchestrator
+ *
+ * Coordinates multiple search providers and implements different search strategies
+ */
+
+import type { AllSearchConfig } from "../config/types";
+import type { CreditManager, CreditSnapshot } from "./credits";
+import type { ProviderRegistry } from "./provider";
+import type { StrategyContext } from "./strategy/ISearchStrategy";
+import { StrategyFactory } from "./strategy/StrategyFactory";
+import type { EngineId, SearchResultItem } from "./types";
+
+export interface AllSearchOptions {
+  /** Override the default engine order */
+  engineOrderOverride?: EngineId[];
+
+  /** Maximum results per provider */
+  limit?: number;
+
+  /** Include raw provider responses */
+  includeRaw?: boolean;
+
+  /** Search strategy */
+  strategy?: "all" | "first-success";
+}
+
+export interface EngineAttempt {
+  engineId: EngineId;
+  success: boolean;
+  reason?: string;
+}
+
+export interface OrchestratorResult {
+  /** Original query */
+  query: string;
+
+  /** Combined results from all successful providers */
+  results: SearchResultItem[];
+
+  /** Metadata about engine attempts */
+  engineAttempts: EngineAttempt[];
+
+  /** Credit snapshots after the search */
+  credits: CreditSnapshot[];
+}
+
+export class AllSearchOrchestrator {
+  constructor(
+    private config: AllSearchConfig,
+    private credits: CreditManager,
+    private registry: ProviderRegistry,
+  ) {}
+
+  /**
+   * Determine the engine order to use for this search
+   */
+  private getEngineOrder(override?: EngineId[]): EngineId[] {
+    if (override?.length) {
+      return override;
+    }
+    return this.config.defaultEngineOrder;
+  }
+
+  /**
+   * Run a allsearch with the specified options
+   */
+  async run(query: string, options: AllSearchOptions = {}): Promise<OrchestratorResult> {
+    const order = this.getEngineOrder(options.engineOrderOverride);
+    const strategyName = options.strategy ?? "all";
+
+    if (order.length === 0) {
+      throw new Error("No engines configured or selected");
+    }
+
+    // Create strategy using factory
+    const strategy = StrategyFactory.createStrategy(strategyName);
+
+    // Create strategy context
+    const context: StrategyContext = {
+      creditManager: this.credits,
+      providerRegistry: this.registry,
+    };
+
+    // Execute strategy
+    const { results, attempts } = await strategy.execute(query, order, options, context);
+
+    // For 'all' strategy, sort results by score (descending)
+    if (strategyName === "all") {
+      results.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    }
+
+    // Get credit snapshots
+    const credits = this.credits.listSnapshots();
+
+    return {
+      query,
+      results,
+      engineAttempts: attempts,
+      credits,
+    };
+  }
+}

package/src/core/paths.ts

@@ -0,0 +1,157 @@
+/**
+ * XDG Base Directory utilities
+ *
+ * Provides standard paths following XDG Base Directory Specification
+ * https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+ */
+
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const APP_NAME = "allsearch";
+
+/**
+ * Get XDG config home directory
+ * Default: ~/.config
+ */
+export function getXdgConfigHome(): string {
+  return process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+}
+
+/**
+ * Get XDG data home directory
+ * Default: ~/.local/share
+ */
+export function getXdgDataHome(): string {
+  return process.env.XDG_DATA_HOME || join(homedir(), ".local", "share");
+}
+
+/**
+ * Get XDG state home directory
+ * Default: ~/.local/state
+ */
+export function getXdgStateHome(): string {
+  return process.env.XDG_STATE_HOME || join(homedir(), ".local", "state");
+}
+
+/**
+ * Get app config directory
+ * ~/.config/allsearch
+ */
+export function getAppConfigDir(): string {
+  return join(getXdgConfigHome(), APP_NAME);
+}
+
+/**
+ * Get app data directory
+ * ~/.local/share/allsearch
+ */
+export function getAppDataDir(): string {
+  return join(getXdgDataHome(), APP_NAME);
+}
+
+/**
+ * Get SearXNG config directory
+ * ~/.config/allsearch/searxng/config
+ */
+export function getSearxngConfigDir(): string {
+  return join(getAppConfigDir(), "searxng", "config");
+}
+
+/**
+ * Get SearXNG data directory
+ * ~/.local/share/allsearch/searxng/data
+ */
+export function getSearxngDataDir(): string {
+  return join(getAppDataDir(), "searxng", "data");
+}
+
+/**
+ * Ensure a directory exists, creating it if necessary
+ */
+export function ensureDir(dir: string): void {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Get all SearXNG paths and ensure directories exist
+ */
+export function getSearxngPaths(): { configDir: string; dataDir: string } {
+  const configDir = getSearxngConfigDir();
+  const dataDir = getSearxngDataDir();
+
+  ensureDir(configDir);
+  ensureDir(dataDir);
+
+  return { configDir, dataDir };
+}
+
+/**
+ * Get package root directory
+ * Handles both development (src/) and bundled (dist/) environments
+ */
+export 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/core/paths.js or dist/cli.js -> find dist root
+    const distIndex = currentDir.indexOf("/dist");
+    return currentDir.substring(0, distIndex + 5); // Include /dist
+  }
+  // Development: src/core/paths.ts -> go up 2 levels to package root
+  return dirname(dirname(currentDir));
+}
+
+/**
+ * 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");
+}
+
+/**
+ * Bootstrap SearXNG config by copying default settings if not present
+ * @returns true if config was bootstrapped, false if already exists
+ */
+export function bootstrapSearxngConfig(): boolean {
+  const { configDir } = getSearxngPaths();
+  const targetSettings = join(configDir, "settings.yml");
+
+  // If settings already exist, don't overwrite
+  if (existsSync(targetSettings)) {
+    return false;
+  }
+
+  const defaultSettings = getDefaultSettingsPath();
+
+  // If default settings don't exist, we can't bootstrap
+  if (!existsSync(defaultSettings)) {
+    console.warn(
+      `[SearXNG] Default settings not found at ${defaultSettings}. ` +
+        `Please create ${targetSettings} manually.`,
+    );
+    return false;
+  }
+
+  // Copy default settings to XDG config dir
+  try {
+    copyFileSync(defaultSettings, targetSettings);
+    console.log(`[SearXNG] Bootstrapped default config to ${targetSettings}`);
+    return true;
+  } catch (error) {
+    console.error(`[SearXNG] Failed to bootstrap config:`, error);
+    return false;
+  }
+}

package/src/core/provider/ILifecycleProvider.ts

@@ -0,0 +1,120 @@
+/**
+ * Lifecycle Provider Interface
+ *
+ * Separates lifecycle concerns (init, healthcheck, shutdown, validation) from search provider contract.
+ * Implemented by providers that manage their own infrastructure (Docker containers, local services).
+ * NOT implemented by external API providers (Tavily, Brave) that don't require lifecycle management.
+ *
+ * This interface follows the Interface Segregation Principle (ISP) by providing
+ * a focused contract for lifecycle-aware providers, separate from the core SearchProvider interface.
+ *
+ * @example
+ * ```typescript
+ * class DockerSearchProvider implements SearchProvider, ILifecycleProvider {
+ *   // SearchProvider methods
+ *   search(query: SearchQuery): Promise<SearchResponse> { ... }
+ *
+ *   // ILifecycleProvider methods
+ *   async init(): Promise<void> { ... }
+ *   async healthcheck(): Promise<boolean> { ... }
+ *   async shutdown(): Promise<void> { ... }
+ *   async validateConfig(): Promise<ValidationResult> { ... }
+ *   isLifecycleManaged(): boolean { return true; }
+ * }
+ * ```
+ */
+
+/**
+ * Validation result for provider configuration
+ */
+export interface ValidationResult {
+  /** Whether the configuration is valid */
+  valid: boolean;
+  /** List of validation errors (empty if valid) */
+  errors: string[];
+  /** List of validation warnings (informational) */
+  warnings: string[];
+}
+
+/**
+ * Interface for providers that manage their own lifecycle (Docker containers, local services)
+ *
+ * Separates lifecycle management from search functionality, allowing:
+ * - Clean separation of concerns (Single Responsibility Principle)
+ * - LSP compliance - SearchProvider contract remains pure
+ * - Flexibility - can use providers with or without lifecycle management
+ * - Better testability - lifecycle can be mocked/stubbed separately
+ */
+export interface ILifecycleProvider {
+  /**
+   * Initialize the provider
+   *
+   * Performs initialization tasks such as:
+   * - Starting Docker containers (if autoStart is enabled)
+   * - Establishing connections to external services
+   * - Performing health checks
+   * - Setting up required infrastructure
+   *
+   * Should be idempotent - safe to call multiple times.
+   * Should handle concurrent calls gracefully.
+   *
+   * @throws Error if initialization fails critically
+   */
+  init(): Promise<void>;
+
+  /**
+   * Check if the provider is healthy and ready to serve requests
+   *
+   * Performs health checks such as:
+   * - Container running status (for Docker providers)
+   * - Health endpoint responsiveness
+   * - Service availability checks
+   * - Resource availability validation
+   *
+   * @returns true if provider is healthy and ready, false otherwise
+   */
+  healthcheck(): Promise<boolean>;
+
+  /**
+   * Shutdown the provider cleanly
+   *
+   * Performs cleanup tasks such as:
+   * - Stopping Docker containers (if autoStop is enabled)
+   * - Closing connections
+   * - Releasing resources
+   * - Cleanup of temporary files/state
+   *
+   * Should be graceful - avoid throwing errors unless absolutely necessary.
+   * Should handle cases where provider is not running.
+   *
+   * @throws Error only for critical shutdown failures that need attention
+   */
+  shutdown(): Promise<void>;
+
+  /**
+   * Validate provider configuration
+   *
+   * Checks configuration for issues such as:
+   * - Docker availability and permissions
+   * - Compose file validity and existence
+   * - Container name validation
+   * - Health endpoint URL validity
+   * - Required environment variables
+   * - Port availability and conflicts
+   *
+   * @returns Validation result with errors and warnings
+   */
+  validateConfig(): Promise<ValidationResult>;
+
+  /**
+   * Check if this provider requires lifecycle management
+   *
+   * Returns true for providers that manage infrastructure (Docker containers, local services).
+   * Returns false for external API providers that don't require lifecycle management.
+   *
+   * This method allows consumers to determine whether lifecycle methods should be called.
+   *
+   * @returns true if provider manages its own lifecycle, false for external APIs
+   */
+  isLifecycleManaged(): boolean;
+}

package/src/core/provider/ProviderFactory.ts

@@ -0,0 +1,120 @@
+/**
+ * Provider Factory
+ *
+ * Factory for creating search provider instances based on configuration.
+ * Delegates to PluginRegistry for provider creation, enabling new providers
+ * to be added without modifying this code.
+ */
+
+import type { EngineConfig } from "../../config/types";
+import { areBuiltInPluginsRegistered, PluginRegistry, registerBuiltInPlugins } from "../../plugin";
+import type { Container } from "../container";
+import type { SearchProvider } from "../provider";
+
+/**
+ * Factory for creating provider instances based on configuration
+ *
+ * Uses the PluginRegistry to create providers, allowing new provider types
+ * to be added by registering plugins rather than modifying factory code.
+ *
+ * @class ProviderFactory
+ * @example
+ * ```typescript
+ * // Ensure plugins are registered first
+ * await ProviderFactory.ensurePluginsRegistered();
+ *
+ * // Create a provider
+ * const provider = ProviderFactory.createProvider(config, container);
+ * ```
+ */
+let initialized = false;
+
+/**
+ * Ensure built-in plugins are registered
+ * Call this before creating providers if not loading via loadConfig()
+ */
+async function ensurePluginsRegistered(): Promise<void> {
+  if (!initialized) {
+    const registry = PluginRegistry.getInstance();
+    if (!areBuiltInPluginsRegistered(registry)) {
+      await registerBuiltInPlugins(registry);
+    }
+    initialized = true;
+  }
+}
+
+/**
+ * Synchronously ensure built-in plugins are registered
+ * Uses sync registration (no lifecycle hooks called)
+ */
+function ensurePluginsRegisteredSync(): void {
+  if (!initialized) {
+    const registry = PluginRegistry.getInstance();
+    if (!areBuiltInPluginsRegistered(registry)) {
+      registerBuiltInPlugins(registry);
+    }
+    initialized = true;
+  }
+}
+
+/**
+ * Creates a search provider instance based on the provided configuration
+ *
+ * @param {EngineConfig} config - The engine configuration (must include 'type' field)
+ * @param {Container} container - DI container for dependency injection
+ * @returns {SearchProvider} An instance of the requested provider
+ * @throws {Error} If the provider type is not registered
+ *
+ * @example
+ * ```typescript
+ * const provider = ProviderFactory.createProvider(config, container);
+ * ```
+ */
+function createProvider(config: EngineConfig, container: Container): SearchProvider {
+  // Ensure built-in plugins are registered (sync)
+  ensurePluginsRegisteredSync();
+
+  const registry = PluginRegistry.getInstance();
+
+  return registry.createProvider(config, { container });
+}
+
+/**
+ * Create multiple providers from an array of configs
+ */
+function createProviders(configs: EngineConfig[], container: Container): SearchProvider[] {
+  return configs.map((config) => createProvider(config, container));
+}
+
+/**
+ * Check if a provider type is supported
+ */
+function isTypeSupported(type: string): boolean {
+  ensurePluginsRegisteredSync();
+  return PluginRegistry.getInstance().has(type);
+}
+
+/**
+ * Get all supported provider types
+ */
+function getSupportedTypes(): string[] {
+  ensurePluginsRegisteredSync();
+  return PluginRegistry.getInstance().getTypes();
+}
+
+/**
+ * Reset initialization state (for testing)
+ */
+function reset(): void {
+  initialized = false;
+}
+
+export const ProviderFactory = {
+  ensurePluginsRegistered,
+  ensurePluginsRegisteredSync,
+  createProvider,
+  createProviders,
+  isTypeSupported,
+  getSupportedTypes,
+  reset,
+};

package/src/core/provider.ts

@@ -0,0 +1,61 @@
+/**
+ * Provider abstraction layer
+ */
+
+import type { EngineId, SearchQuery, SearchResponse } from "./types";
+
+export interface ProviderMetadata {
+  id: EngineId;
+  displayName: string;
+  docsUrl?: string;
+}
+
+/**
+ * Abstract interface that all search providers must implement
+ */
+export interface SearchProvider {
+  readonly id: EngineId;
+  getMetadata(): ProviderMetadata;
+  search(query: SearchQuery): Promise<SearchResponse>;
+}
+
+/**
+ * Interface for providers that manage lifecycle (init, healthcheck, shutdown)
+ */
+export interface ILifecycleProvider {
+  init(): Promise<void>;
+  healthcheck(): Promise<boolean>;
+  shutdown(): Promise<void>;
+  validateConfig(): Promise<{
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+  }>;
+  isLifecycleManaged(): boolean;
+}
+
+/**
+ * Registry to manage all available providers
+ */
+export class ProviderRegistry {
+  private providers = new Map<EngineId, SearchProvider>();
+
+  register(provider: SearchProvider): void {
+    if (this.providers.has(provider.id)) {
+      throw new Error(`Provider already registered: ${provider.id}`);
+    }
+    this.providers.set(provider.id, provider);
+  }
+
+  get(id: EngineId): SearchProvider | undefined {
+    return this.providers.get(id);
+  }
+
+  list(): SearchProvider[] {
+    return Array.from(this.providers.values());
+  }
+
+  has(id: EngineId): boolean {
+    return this.providers.has(id);
+  }
+}

package/src/core/serviceKeys.ts

@@ -0,0 +1,45 @@
+/**
+ * Service Keys for Dependency Injection Container
+ *
+ * Centralized constants for all service identifiers used with the DI container.
+ * Using constants instead of magic strings prevents typos and enables IDE support.
+ *
+ * @example
+ * ```typescript
+ * import { ServiceKeys } from '../core/serviceKeys';
+ *
+ * // Register service
+ * container.singleton(ServiceKeys.CONFIG, () => config);
+ *
+ * // Resolve service
+ * const config = container.get<AllSearchConfig>(ServiceKeys.CONFIG);
+ * ```
+ */
+
+/**
+ * All service keys used in the DI container
+ */
+export const ServiceKeys = {
+  /** Application configuration */
+  CONFIG: "config",
+
+  /** Credit state persistence provider */
+  CREDIT_STATE_PROVIDER: "creditStateProvider",
+
+  /** Credit manager for tracking usage */
+  CREDIT_MANAGER: "creditManager",
+
+  /** Registry of all search providers */
+  PROVIDER_REGISTRY: "providerRegistry",
+
+  /** Factory for creating search strategies */
+  STRATEGY_FACTORY: "strategyFactory",
+
+  /** Main search orchestrator */
+  ORCHESTRATOR: "orchestrator",
+} as const;
+
+/**
+ * Type representing any valid service key
+ */
+export type ServiceKey = (typeof ServiceKeys)[keyof typeof ServiceKeys];