ubersearch 0.0.0-development

package/src/cli.ts

@@ -0,0 +1,380 @@
+#!/usr/bin/env bun
+/**
+ * Multi-Search CLI
+ *
+ * Unified search interface for multiple search providers
+ */
+
+import { bootstrapContainer, isLifecycleProvider } from "./bootstrap/container";
+import type { ProviderRegistry } from "./core/provider";
+import { ServiceKeys } from "./core/serviceKeys";
+import type { AllSearchOutput } from "./tool/interface";
+import { getCreditStatus, multiSearch } from "./tool/multiSearchTool";
+
+// Parse command line arguments
+let args = process.argv.slice(2);
+
+// Parse --config first and remove from args (global option that can appear anywhere)
+const configIdx = args.indexOf("--config");
+let configPath: string | undefined;
+if (configIdx !== -1) {
+  configPath = args[configIdx + 1];
+  if (!configPath || configPath.startsWith("--")) {
+    console.error("Error: --config requires a file path");
+    process.exit(1);
+  }
+  args.splice(configIdx, 2);
+}
+
+// Show help
+if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+  console.log(`
+allsearch — Unified search across multiple providers
+
+USAGE:
+    allsearch <query> [options]
+    allsearch credits
+
+ARGUMENTS:
+    <query>     Search query (required, unless using 'credits' command)
+    credits     Show credit status for all engines
+    health      Run health checks on all providers
+
+OPTIONS:
+    --json                      Output results as JSON
+    --engines <engine,list>     Use specific engines (comma-separated)
+    --strategy <strategy>       Search strategy: 'all' or 'first-success' (default: all)
+    --limit <number>            Maximum results per engine
+    --include-raw               Include raw provider responses
+    --config <path>             Path to configuration file
+    --help, -h                  Show this help message
+
+EXAMPLES:
+    allsearch "best TypeScript ORM 2025"
+    allsearch "llm observability" --engines tavily,brave --json
+    allsearch "hawaii dev meetups" --strategy first-success
+    allsearch credits
+    allsearch health
+    allsearch --config /path/to/config.json credits
+    allsearch "query" --config /path/to/config.json
+
+CONFIGURATION:
+    Config files are searched in order:
+    1. ./allsearch.config.json
+    2. $XDG_CONFIG_HOME/allsearch/config.json
+    3. ~/.config/allsearch/config.json
+
+ENVIRONMENT:
+    Set API keys in environment variables:
+    - TAVILY_API_KEY      for Tavily
+    - BRAVE_API_KEY       for Brave Search
+`);
+  process.exit(0);
+}
+
+// Credits command
+if (args[0] === "credits") {
+  await showCredits(configPath);
+  process.exit(0);
+}
+
+// Health check command
+if (args[0] === "health") {
+  await runHealthChecks(configPath);
+  process.exit(0);
+}
+
+// Parse options
+const options = {
+  json: args.includes("--json"),
+  includeRaw: args.includes("--include-raw"),
+  engines: undefined as string[] | undefined,
+  strategy: undefined as "all" | "first-success" | undefined,
+  limit: undefined as number | undefined,
+};
+
+// Parse --engines
+const enginesIdx = args.indexOf("--engines");
+if (enginesIdx !== -1) {
+  const enginesArg = args[enginesIdx + 1];
+  if (enginesArg !== undefined) {
+    options.engines = enginesArg.split(",").map((e) => e.trim());
+  }
+}
+
+// Parse --strategy
+const strategyIdx = args.indexOf("--strategy");
+if (strategyIdx !== -1 && args[strategyIdx + 1]) {
+  const strategy = args[strategyIdx + 1];
+  if (strategy === "all" || strategy === "first-success") {
+    options.strategy = strategy;
+  } else {
+    console.error(`Invalid strategy: ${strategy}. Must be 'all' or 'first-success'`);
+    process.exit(1);
+  }
+}
+
+// Parse --limit
+const limitIdx = args.indexOf("--limit");
+if (limitIdx !== -1) {
+  const limitArg = args[limitIdx + 1];
+  if (limitArg !== undefined) {
+    const limit = parseInt(limitArg, 10);
+    if (Number.isNaN(limit) || limit < 1) {
+      console.error(`Invalid limit: ${limitArg}. Must be a positive number`);
+      process.exit(1);
+    }
+    options.limit = limit;
+  }
+}
+
+// Extract query (non-option arguments)
+// Filter out option flags (--*) and their values
+const optionsWithValues = ["--engines", "--strategy", "--limit", "--config"];
+const queryParts = args.filter((arg, idx) => {
+  // Skip arguments starting with --
+  if (arg.startsWith("--")) {
+    return false;
+  }
+  // Skip special commands
+  if (["credits", "health"].includes(arg)) {
+    return false;
+  }
+  // Skip values that follow option flags
+  const prevArg = args[idx - 1];
+  if (prevArg && optionsWithValues.includes(prevArg)) {
+    return false;
+  }
+  return true;
+});
+
+const query = queryParts.join(" ").trim();
+
+if (!query) {
+  console.error("Error: Query is required");
+  console.error("Run with --help for usage information");
+  process.exit(1);
+}
+
+// Execute search
+async function main() {
+  try {
+    // Bootstrap the DI container
+    const _container = await bootstrapContainer(configPath);
+
+    const result = await multiSearch(
+      {
+        query,
+        limit: options.limit,
+        engines: options.engines,
+        includeRaw: options.includeRaw,
+        strategy: options.strategy,
+      },
+      configPath,
+    );
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      printHumanReadable(result);
+    }
+  } catch (error) {
+    console.error("Search failed:", error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+/**
+ * Print results in human-readable format
+ */
+function printHumanReadable(result: AllSearchOutput) {
+  console.log(`\nQuery: "${result.query}"`);
+  console.log(`Found ${result.items.length} results\n`);
+
+  if (result.items.length === 0) {
+    console.log("No results found.");
+    return;
+  }
+
+  // Group results by engine
+  const byEngine = new Map<string, typeof result.items>();
+  for (const item of result.items) {
+    if (!byEngine.has(item.sourceEngine)) {
+      byEngine.set(item.sourceEngine, []);
+    }
+    byEngine.get(item.sourceEngine)?.push(item);
+  }
+
+  // Print results
+  for (const [engineId, items] of byEngine) {
+    if (items.length > 0) {
+      console.log(`\n${"=".repeat(60)}`);
+      console.log(`${engineId} (${items.length} results)`);
+      console.log(`${"=".repeat(60)}`);
+
+      for (let i = 0; i < items.length && i < 5; i++) {
+        const item = items[i];
+        if (!item) {
+          continue;
+        }
+        console.log(`\n${i + 1}. ${item.title}`);
+        console.log(`   ${item.url}`);
+        if (item.score) {
+          console.log(`   Score: ${item.score}`);
+        }
+        if (item.snippet) {
+          console.log(
+            `   ${item.snippet.substring(0, 200)}${item.snippet.length > 200 ? "..." : ""}`,
+          );
+        }
+      }
+
+      if (items.length > 5) {
+        console.log(`\n   ... and ${items.length - 5} more results`);
+      }
+    }
+  }
+
+  // Print engine status
+  console.log(`\n${"=".repeat(60)}`);
+  console.log("Engine Status");
+  console.log(`${"=".repeat(60)}`);
+  for (const attempt of result.enginesTried) {
+    const status = attempt.success
+      ? "✓ Success"
+      : `✗ Failed${attempt.reason ? ` (${attempt.reason})` : ""}`;
+    console.log(`${attempt.engineId.padEnd(15)} ${status}`);
+  }
+
+  // Print credit warnings
+  if (result.credits) {
+    const lowCredits = result.credits.filter((c) => c.remaining < c.quota * 0.2);
+    if (lowCredits.length > 0) {
+      console.log(`\n⚠️  Low credit warnings:`);
+      for (const credit of lowCredits) {
+        console.log(`   ${credit.engineId}: ${credit.remaining} remaining of ${credit.quota}`);
+      }
+    }
+  }
+
+  console.log();
+}
+
+/**
+ * Run health checks on all providers
+ */
+async function runHealthChecks(configPath?: string) {
+  try {
+    // Bootstrap the DI container
+    const container = await bootstrapContainer(configPath);
+    const registry = container.get<ProviderRegistry>(ServiceKeys.PROVIDER_REGISTRY);
+    const providers = registry.list();
+
+    console.log("\nProvider Health Checks");
+    console.log("=".repeat(60));
+
+    if (providers.length === 0) {
+      console.log("No providers are registered.");
+      return;
+    }
+
+    const results: Array<{
+      engineId: string;
+      status: "healthy" | "unhealthy" | "skipped";
+      message: string;
+    }> = [];
+
+    for (const provider of providers) {
+      const engineId = provider.id;
+
+      // Check if provider implements lifecycle methods
+      if (isLifecycleProvider(provider)) {
+        try {
+          await provider.healthcheck();
+          results.push({
+            engineId,
+            status: "healthy",
+            message: "Health check passed",
+          });
+          console.log(`✓ ${engineId.padEnd(15)} Healthy`);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          results.push({
+            engineId,
+            status: "unhealthy",
+            message,
+          });
+          console.log(`✗ ${engineId.padEnd(15)} Unhealthy - ${message}`);
+        }
+      } else {
+        results.push({
+          engineId,
+          status: "skipped",
+          message: "Health checks not supported",
+        });
+        console.log(`- ${engineId.padEnd(15)} Skipped (no health check support)`);
+      }
+    }
+
+    // Summary
+    const healthy = results.filter((r) => r.status === "healthy").length;
+    const unhealthy = results.filter((r) => r.status === "unhealthy").length;
+    const skipped = results.filter((r) => r.status === "skipped").length;
+
+    console.log(`\nSummary: ${healthy} healthy, ${unhealthy} unhealthy, ${skipped} skipped`);
+
+    if (unhealthy > 0) {
+      console.log("\n⚠️  Some providers are unhealthy. Check configuration and connectivity.");
+      process.exit(1);
+    } else {
+      console.log("\n✓ All providers are healthy");
+    }
+
+    console.log();
+  } catch (error) {
+    console.error("Health check failed:", error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+/**
+ * Show credit status
+ */
+async function showCredits(configPath?: string) {
+  try {
+    const credits = await getCreditStatus(configPath);
+
+    if (!credits || credits.length === 0) {
+      console.log("No credits configured or no engines enabled.");
+      return;
+    }
+
+    console.log("\nCredit Status");
+    console.log("=".repeat(60));
+
+    for (const credit of credits) {
+      const usedPercent = ((credit.used / credit.quota) * 100).toFixed(1);
+      const status = credit.isExhausted
+        ? "⚠️  EXHAUSTED"
+        : credit.remaining < credit.quota * 0.2
+          ? "⚠️  Low"
+          : "✓ OK";
+
+      console.log(`\n${credit.engineId}`);
+      console.log(`  Used:      ${credit.used} / ${credit.quota} (${usedPercent}%)`);
+      console.log(`  Remaining: ${credit.remaining}`);
+      console.log(`  Status:    ${status}`);
+    }
+
+    console.log();
+  } catch (error) {
+    console.error(
+      "Failed to load credits:",
+      error instanceof Error ? error.message : String(error),
+    );
+    process.exit(1);
+  }
+}
+
+// Run main
+main();

package/src/config/defineConfig.ts

@@ -0,0 +1,176 @@
+/**
+ * Configuration Helper Functions
+ *
+ * Provides type-safe helpers for defining allsearch configurations.
+ * Inspired by Vite's defineConfig pattern.
+ */
+
+import type { SearchProvider } from "../core/provider";
+import type { PluginDefinition } from "../plugin/types";
+import type {
+  BraveConfig,
+  EngineConfig,
+  EngineConfigBase,
+  LinkupConfig,
+  AllSearchConfig,
+  SearchxngConfig,
+  TavilyConfig,
+} from "./types";
+
+/**
+ * Extended configuration that supports plugins
+ */
+export interface ExtendedSearchConfig extends AllSearchConfig {
+  /**
+   * Custom plugins to register
+   * These will be registered before creating providers
+   */
+  plugins?: PluginDefinition[];
+}
+
+/**
+ * Configuration factory function type
+ * Allows async config creation for loading secrets, etc.
+ */
+export type ConfigFactory = () => ExtendedSearchConfig | Promise<ExtendedSearchConfig>;
+
+/**
+ * Define a allsearch configuration with full type safety
+ *
+ * @param config - Configuration object or factory function
+ * @returns The configuration (passthrough with type inference)
+ *
+ * @example
+ * ```typescript
+ * // allsearch.config.ts
+ * import { defineConfig } from 'allsearch';
+ *
+ * export default defineConfig({
+ *   defaultEngineOrder: ['tavily', 'brave'],
+ *   engines: [
+ *     defineTavily({
+ *       id: 'tavily',
+ *       enabled: true,
+ *       displayName: 'Tavily Search',
+ *       apiKeyEnv: 'TAVILY_API_KEY',
+ *       endpoint: 'https://api.tavily.com/search',
+ *       searchDepth: 'basic',
+ *       monthlyQuota: 1000,
+ *       creditCostPerSearch: 1,
+ *       lowCreditThresholdPercent: 80,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export function defineConfig(config: ExtendedSearchConfig): ExtendedSearchConfig;
+export function defineConfig(factory: ConfigFactory): ConfigFactory;
+export function defineConfig(
+  configOrFactory: ExtendedSearchConfig | ConfigFactory,
+): ExtendedSearchConfig | ConfigFactory {
+  return configOrFactory;
+}
+
+/**
+ * Helper to define a Tavily engine configuration
+ */
+export function defineTavily(
+  config: Omit<TavilyConfig, "type"> & Partial<Pick<TavilyConfig, "type">>,
+): TavilyConfig {
+  return {
+    type: "tavily",
+    ...config,
+  };
+}
+
+/**
+ * Helper to define a Brave engine configuration
+ */
+export function defineBrave(
+  config: Omit<BraveConfig, "type"> & Partial<Pick<BraveConfig, "type">>,
+): BraveConfig {
+  return {
+    type: "brave",
+    ...config,
+  };
+}
+
+/**
+ * Helper to define a Linkup engine configuration
+ */
+export function defineLinkup(
+  config: Omit<LinkupConfig, "type"> & Partial<Pick<LinkupConfig, "type">>,
+): LinkupConfig {
+  return {
+    type: "linkup",
+    ...config,
+  };
+}
+
+/**
+ * Helper to define a SearXNG engine configuration
+ */
+export function defineSearchxng(
+  config: Omit<SearchxngConfig, "type"> & Partial<Pick<SearchxngConfig, "type">>,
+): SearchxngConfig {
+  return {
+    type: "searchxng",
+    ...config,
+  };
+}
+
+/**
+ * Generic helper for custom engine types
+ *
+ * @example
+ * ```typescript
+ * interface MyCustomConfig extends EngineConfigBase {
+ *   type: 'my-custom';
+ *   customOption: string;
+ * }
+ *
+ * const myEngine = defineEngine<MyCustomConfig>({
+ *   type: 'my-custom',
+ *   id: 'my-custom',
+ *   // ...
+ * });
+ * ```
+ */
+export function defineEngine<T extends EngineConfig>(config: T): T {
+  return config;
+}
+
+/**
+ * Helper to define a custom plugin
+ *
+ * @example
+ * ```typescript
+ * const myPlugin = definePlugin({
+ *   type: 'my-search',
+ *   displayName: 'My Search',
+ *   hasLifecycle: false,
+ *   factory: (config) => new MySearchProvider(config),
+ * });
+ * ```
+ */
+export function definePlugin<TConfig extends EngineConfigBase, TProvider extends SearchProvider>(
+  plugin: PluginDefinition<TConfig, TProvider>,
+): PluginDefinition<TConfig, TProvider> {
+  return plugin;
+}
+
+/**
+ * Create a configuration with defaults
+ */
+export function createConfig(
+  engines: EngineConfig[],
+  options: Partial<Omit<ExtendedSearchConfig, "engines">> = {},
+): ExtendedSearchConfig {
+  const enabledEngines = engines.filter((e) => e.enabled);
+  return {
+    defaultEngineOrder: options.defaultEngineOrder ?? enabledEngines.map((e) => e.id),
+    engines,
+    storage: options.storage,
+    plugins: options.plugins,
+  };
+}