@aria-cli/tools 1.0.0

package/src/providers/brave.ts

@@ -0,0 +1,80 @@
+import type {
+  SearchProvider,
+  SearchOptions,
+  SearchResult,
+  SearchProviderEnv,
+} from "./search-provider.js";
+import { createProviderAbortSignal, resolveSearchProviderEnv } from "./search-provider.js";
+
+export class BraveSearchProvider implements SearchProvider {
+  readonly name = "brave";
+  readonly requiresApiKey = true;
+  readonly priority = 1;
+
+  constructor(
+    private readonly env: SearchProviderEnv | Record<string, string | undefined> = process.env,
+  ) {}
+
+  isAvailable(): boolean {
+    const apiKey = resolveSearchProviderEnv(this.env).BRAVE_API_KEY;
+    return Boolean(apiKey && apiKey.trim().length > 0);
+  }
+
+  async search(query: string, options?: SearchOptions): Promise<SearchResult[]> {
+    const apiKey = resolveSearchProviderEnv(this.env).BRAVE_API_KEY;
+    if (!apiKey) {
+      throw new Error("BRAVE_API_KEY environment variable is not set");
+    }
+
+    const limit = options?.limit ?? 5;
+
+    const url = new URL("https://api.search.brave.com/res/v1/web/search");
+    url.searchParams.set("q", query);
+    url.searchParams.set("count", String(limit));
+
+    // Handle timeRange option (map to Brave's freshness parameter)
+    if (options?.timeRange) {
+      const freshnessMap: Record<string, string> = {
+        day: "pd",
+        week: "pw",
+        month: "pm",
+        year: "py",
+      };
+      const freshness = freshnessMap[options.timeRange];
+      if (freshness) {
+        url.searchParams.set("freshness", freshness);
+      }
+    }
+
+    const { signal, cleanup } = createProviderAbortSignal(30_000, options?.signal);
+
+    try {
+      const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: {
+          Accept: "application/json",
+          "X-Subscription-Token": apiKey,
+        },
+        signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`Brave Search API error: ${response.status} ${response.statusText}`);
+      }
+
+      const json = await response.json();
+      const webResults = json.web?.results || [];
+
+      return webResults.map(
+        (r: { title: string; url: string; description: string; relevance_score?: number }) => ({
+          title: r.title,
+          url: r.url,
+          content: r.description,
+          score: r.relevance_score,
+        }),
+      );
+    } finally {
+      cleanup();
+    }
+  }
+}

package/src/providers/duckduckgo.ts

@@ -0,0 +1,199 @@
+import type { SearchProvider, SearchOptions, SearchResult } from "./search-provider.js";
+import { createProviderAbortSignal } from "./search-provider.js";
+
+export class DuckDuckGoSearchProvider implements SearchProvider {
+  readonly name = "duckduckgo";
+  readonly requiresApiKey = false;
+  readonly priority = 6;
+
+  isAvailable(): boolean {
+    // DuckDuckGo is always available (no API key required)
+    return true;
+  }
+
+  async search(query: string, options?: SearchOptions): Promise<SearchResult[]> {
+    const limit = options?.limit ?? 5;
+
+    // DuckDuckGo HTML search endpoint (we'll parse the HTML response)
+    // The Instant Answer API doesn't provide web search results, only factoids
+    const url = new URL("https://html.duckduckgo.com/html/");
+    url.searchParams.set("q", query);
+
+    const { signal, cleanup } = createProviderAbortSignal(30_000, options?.signal);
+
+    try {
+      const response = await fetch(url.toString(), {
+        method: "GET",
+        signal,
+        headers: {
+          "User-Agent": "Mozilla/5.0 (compatible; ARIA/1.0)",
+        },
+      });
+
+      if (!response.ok) {
+        throw new Error(`DuckDuckGo Search error: ${response.status} ${response.statusText}`);
+      }
+
+      const html = await response.text();
+
+      // Parse HTML to extract search results
+      // DuckDuckGo HTML results have result__a (title/url) and result__snippet (description)
+      const results: SearchResult[] = [];
+
+      // First pass: extract all result__a links (title + url)
+      const linkMap = new Map<string, { title: string; url: string }>();
+      const linkRegex =
+        /<a(?=[^>]*\bclass=(["'])[^"']*\bresult__a\b[^"']*\1)(?=[^>]*\bhref=(["'])(.*?)\2)[^>]*>([\s\S]*?)<\/a>/gi;
+      let match;
+      let resultAnchorCount = 0;
+      while ((match = linkRegex.exec(html)) !== null) {
+        const rawHref = match[3];
+        const rawTitle = match[4];
+        if (!rawHref || !rawTitle) {
+          continue;
+        }
+        resultAnchorCount++;
+        const url = this.resolveDuckDuckGoResultUrl(rawHref);
+        if (!url) {
+          continue;
+        }
+        const title = this.stripHtmlTags(rawTitle);
+        if (!title) {
+          continue;
+        }
+        linkMap.set(url, { title, url });
+      }
+
+      // If DDG returned result anchors but we extracted zero usable URLs, parsing is stale.
+      // Throw to allow router fallback rather than silently returning empty results.
+      if (resultAnchorCount > 0 && linkMap.size === 0) {
+        throw new Error("Could not resolve any result URLs from DuckDuckGo response");
+      }
+
+      // Second pass: extract snippets
+      const snippetRegex =
+        /<(?:a|div|span)(?=[^>]*\bclass=(["'])[^"']*\bresult__snippet\b[^"']*\1)[^>]*>([\s\S]*?)<\/(?:a|div|span)>/gi;
+      const snippets: string[] = [];
+      while ((match = snippetRegex.exec(html)) !== null) {
+        const rawSnippet = match[2];
+        snippets.push(this.stripHtmlTags(rawSnippet ?? ""));
+      }
+
+      // Combine results (matching by order, which should align)
+      const linkEntries = Array.from(linkMap.values());
+      for (let i = 0; i < Math.min(linkEntries.length, limit); i++) {
+        const link = linkEntries[i];
+        if (!link) {
+          continue;
+        }
+        const snippet = snippets[i] || link.title;
+        results.push({
+          title: link.title,
+          url: link.url,
+          content: snippet,
+        });
+      }
+
+      return results;
+    } finally {
+      cleanup();
+    }
+  }
+
+  /**
+   * Strip HTML tags from a string
+   */
+  private stripHtmlTags(html: string): string {
+    return html
+      .replace(/<[^>]*>/g, "")
+      .replace(/&nbsp;/g, " ")
+      .replace(/&amp;/g, "&")
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .replace(/&quot;/g, '"')
+      .replace(/&#39;/g, "'")
+      .trim();
+  }
+
+  /**
+   * Decode HTML entities in URLs
+   */
+  private decodeHtmlEntities(text: string): string {
+    return text
+      .replace(/&amp;/g, "&")
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .replace(/&quot;/g, '"')
+      .replace(/&#39;/g, "'");
+  }
+
+  private resolveDuckDuckGoResultUrl(rawHref: string): string | null {
+    const decodedHref = this.decodeHtmlEntities(rawHref).trim();
+    if (!decodedHref) {
+      return null;
+    }
+
+    let absoluteHref = decodedHref;
+    if (absoluteHref.startsWith("//")) {
+      absoluteHref = `https:${absoluteHref}`;
+    } else if (absoluteHref.startsWith("/")) {
+      absoluteHref = `https://duckduckgo.com${absoluteHref}`;
+    }
+
+    let parsed: URL;
+    try {
+      parsed = new URL(absoluteHref);
+    } catch {
+      return null;
+    }
+
+    const hostname = parsed.hostname.toLowerCase();
+    if (hostname === "duckduckgo.com" || hostname.endsWith(".duckduckgo.com")) {
+      const redirected = parsed.searchParams.get("uddg");
+      if (!redirected) {
+        return null;
+      }
+      return this.normalizeResultUrl(redirected);
+    }
+
+    return this.normalizeResultUrl(absoluteHref);
+  }
+
+  private normalizeResultUrl(candidate: string): string | null {
+    let value = candidate.trim();
+    if (!value) {
+      return null;
+    }
+
+    if (value.startsWith("//")) {
+      value = `https:${value}`;
+    }
+
+    // Some uddg values are encoded multiple times; decode at most twice.
+    for (let i = 0; i < 2; i++) {
+      try {
+        const decoded = decodeURIComponent(value);
+        if (decoded === value) {
+          break;
+        }
+        value = decoded;
+      } catch {
+        break;
+      }
+    }
+
+    try {
+      const parsed = new URL(value);
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return null;
+      }
+      const hostname = parsed.hostname.toLowerCase();
+      if (hostname === "duckduckgo.com" || hostname.endsWith(".duckduckgo.com")) {
+        return null;
+      }
+      return parsed.toString();
+    } catch {
+      return null;
+    }
+  }
+}

package/src/providers/exa.ts

@@ -0,0 +1,85 @@
+import type {
+  SearchProvider,
+  SearchOptions,
+  SearchResult,
+  SearchProviderEnv,
+} from "./search-provider.js";
+import { createProviderAbortSignal, resolveSearchProviderEnv } from "./search-provider.js";
+
+export class ExaSearchProvider implements SearchProvider {
+  readonly name = "exa";
+  readonly requiresApiKey = true;
+  readonly priority = 3;
+
+  constructor(
+    private readonly env: SearchProviderEnv | Record<string, string | undefined> = process.env,
+  ) {}
+
+  isAvailable(): boolean {
+    const apiKey = resolveSearchProviderEnv(this.env).EXA_API_KEY;
+    return Boolean(apiKey && apiKey.trim().length > 0);
+  }
+
+  async search(query: string, options?: SearchOptions): Promise<SearchResult[]> {
+    const apiKey = resolveSearchProviderEnv(this.env).EXA_API_KEY;
+    if (!apiKey) {
+      throw new Error("EXA_API_KEY environment variable is not set");
+    }
+
+    const limit = options?.limit ?? 5;
+
+    const body: Record<string, unknown> = {
+      query,
+      numResults: limit,
+      useAutoprompt: true,
+      contents: {
+        text: true,
+      },
+    };
+
+    // Domain filtering
+    if (options?.domains) {
+      body.includeDomains = options.domains;
+    }
+    if (options?.excludeDomains) {
+      body.excludeDomains = options.excludeDomains;
+    }
+
+    const { signal, cleanup } = createProviderAbortSignal(30_000, options?.signal);
+
+    try {
+      const response = await fetch("https://api.exa.ai/search", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": apiKey,
+        },
+        body: JSON.stringify(body),
+        signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`Exa Search API error: ${response.status} ${response.statusText}`);
+      }
+
+      const json = await response.json();
+      const results = (json.results || []) as Array<{
+        title: string;
+        url: string;
+        text?: string;
+        score?: number;
+        publishedDate?: string;
+      }>;
+
+      return results.map((r) => ({
+        title: r.title,
+        url: r.url,
+        content: r.text || "",
+        score: r.score,
+        publishedDate: r.publishedDate,
+      }));
+    } finally {
+      cleanup();
+    }
+  }
+}

package/src/providers/firecrawl.ts

@@ -0,0 +1,77 @@
+import type {
+  SearchProvider,
+  SearchOptions,
+  SearchResult,
+  SearchProviderEnv,
+} from "./search-provider.js";
+import { createProviderAbortSignal, resolveSearchProviderEnv } from "./search-provider.js";
+
+export class FirecrawlSearchProvider implements SearchProvider {
+  readonly name = "firecrawl";
+  readonly requiresApiKey = true;
+  readonly priority = 2;
+
+  constructor(
+    private readonly env: SearchProviderEnv | Record<string, string | undefined> = process.env,
+  ) {}
+
+  isAvailable(): boolean {
+    const apiKey = resolveSearchProviderEnv(this.env).FIRECRAWL_API_KEY;
+    return Boolean(apiKey && apiKey.trim().length > 0);
+  }
+
+  async search(query: string, options?: SearchOptions): Promise<SearchResult[]> {
+    const apiKey = resolveSearchProviderEnv(this.env).FIRECRAWL_API_KEY;
+    if (!apiKey) {
+      throw new Error("FIRECRAWL_API_KEY environment variable is not set");
+    }
+
+    const limit = options?.limit ?? 5;
+
+    const body: Record<string, unknown> = {
+      query,
+      limit,
+    };
+
+    const { signal, cleanup } = createProviderAbortSignal(30_000, options?.signal);
+
+    try {
+      const response = await fetch("https://api.firecrawl.dev/v1/search", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(body),
+        signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`Firecrawl Search API error: ${response.status} ${response.statusText}`);
+      }
+
+      const json = await response.json();
+
+      // Firecrawl can return 200 with success: false
+      if (json.success === false) {
+        throw new Error(`Firecrawl API error: ${json.error || "Unknown error"}`);
+      }
+
+      const results = (json.data || []) as Array<{
+        title: string;
+        url: string;
+        markdown?: string;
+        score?: number;
+      }>;
+
+      return results.map((r) => ({
+        title: r.title,
+        url: r.url,
+        content: r.markdown || "",
+        score: r.score,
+      }));
+    } finally {
+      cleanup();
+    }
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,8 @@
+export type { SearchOptions, SearchResult, SearchProvider } from "./search-provider.js";
+export { JinaSearchProvider } from "./jina.js";
+export { DuckDuckGoSearchProvider } from "./duckduckgo.js";
+export { TavilySearchProvider } from "./tavily.js";
+export { BraveSearchProvider } from "./brave.js";
+export { ExaSearchProvider } from "./exa.js";
+export { FirecrawlSearchProvider } from "./firecrawl.js";
+export { SearchProviderRouter } from "./router.js";

package/src/providers/jina.ts

@@ -0,0 +1,70 @@
+import type {
+  SearchProvider,
+  SearchOptions,
+  SearchResult,
+  SearchProviderEnv,
+} from "./search-provider.js";
+import { createProviderAbortSignal, resolveSearchProviderEnv } from "./search-provider.js";
+
+export class JinaSearchProvider implements SearchProvider {
+  readonly name = "jina";
+  readonly requiresApiKey = false;
+  readonly priority = 5;
+
+  constructor(
+    private readonly env: SearchProviderEnv | Record<string, string | undefined> = process.env,
+  ) {}
+
+  isAvailable(): boolean {
+    // Jina works without an API key (20 req/min), or with a key (200 req/min)
+    return true;
+  }
+
+  async search(query: string, options?: SearchOptions): Promise<SearchResult[]> {
+    const apiKey = resolveSearchProviderEnv(this.env).JINA_API_KEY;
+    const limit = options?.limit ?? 5;
+
+    const url = new URL("https://s.jina.ai/");
+    url.searchParams.set("q", query);
+
+    const headers: HeadersInit = {
+      Accept: "application/json",
+    };
+
+    if (apiKey) {
+      headers.Authorization = `Bearer ${apiKey}`;
+    }
+
+    const { signal, cleanup } = createProviderAbortSignal(30_000, options?.signal);
+
+    try {
+      const response = await fetch(url.toString(), {
+        method: "GET",
+        headers,
+        signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`Jina Search API error: ${response.status} ${response.statusText}`);
+      }
+
+      const json = await response.json();
+      const results = (json.data || []) as Array<{
+        title: string;
+        url: string;
+        content: string;
+        score?: number;
+      }>;
+
+      // Apply limit client-side
+      return results.slice(0, limit).map((r) => ({
+        title: r.title,
+        url: r.url,
+        content: r.content,
+        score: r.score,
+      }));
+    } finally {
+      cleanup();
+    }
+  }
+}

package/src/providers/router.ts

@@ -0,0 +1,121 @@
+import { log } from "@aria/types";
+import type {
+  SearchProvider,
+  SearchOptions,
+  SearchResult,
+  SearchProviderEnv,
+} from "./search-provider.js";
+import { resolveSearchProviderEnv } from "./search-provider.js";
+
+export class SearchProviderRouter {
+  constructor(
+    private _providers: SearchProvider[],
+    private readonly env: SearchProviderEnv | Record<string, string | undefined> = process.env,
+  ) {}
+
+  /**
+   * Resolves the best available search provider.
+   * Priority:
+   * 1. Explicit override via ARIA_SEARCH_PROVIDER env var
+   * 2. Highest-priority available provider (lowest priority number)
+   * @throws {Error} if no providers are available or override is invalid
+   */
+  resolve(): SearchProvider {
+    const env = resolveSearchProviderEnv(this.env);
+    // 1. Check for explicit override
+    const override = env.ARIA_SEARCH_PROVIDER;
+    if (override) {
+      const provider = this._providers.find((p) => p.name === override);
+      if (!provider) {
+        throw new Error(
+          `ARIA_SEARCH_PROVIDER override '${override}' not found in provider registry`,
+        );
+      }
+      // Verify the overridden provider is actually available (e.g., has API key)
+      if (!provider.isAvailable()) {
+        // Fall through to default priority-based routing
+        log.debug(
+          `[SearchProviderRouter] ARIA_SEARCH_PROVIDER override '${override}' is not available, falling back to priority routing`,
+        );
+      } else {
+        return provider;
+      }
+    }
+
+    // 2. Select first available provider by priority (lower number = higher priority)
+    const sorted = [...this._providers].sort((a, b) => a.priority - b.priority);
+    const available = sorted.find((p) => p.isAvailable());
+
+    if (!available) {
+      throw new Error(
+        "No search providers available. Set at least one API key (BRAVE_API_KEY, TAVILY_API_KEY, etc.)",
+      );
+    }
+
+    return available;
+  }
+
+  /**
+   * Performs a search with automatic fallback.
+   * Tries providers in priority order (resolved provider first, then others).
+   * Circuit breaker: stops at first successful response.
+   * @throws {AggregateError} if all providers fail
+   */
+  async search(query: string, options?: SearchOptions): Promise<SearchResult[]> {
+    if (options?.signal?.aborted) {
+      throw new Error("Search aborted");
+    }
+
+    const env = resolveSearchProviderEnv(this.env);
+    // Get all available providers sorted by priority
+    const availableProviders = [...this._providers]
+      .filter((p) => p.isAvailable())
+      .sort((a, b) => a.priority - b.priority);
+
+    if (availableProviders.length === 0) {
+      throw new Error("No search providers available");
+    }
+
+    // Honor ARIA_SEARCH_PROVIDER override: try the override provider first
+    const override = env.ARIA_SEARCH_PROVIDER;
+    if (override) {
+      const overrideProvider = availableProviders.find((p) => p.name === override);
+      if (overrideProvider) {
+        // Move override provider to front of the list
+        const reordered = [
+          overrideProvider,
+          ...availableProviders.filter((p) => p.name !== override),
+        ];
+        availableProviders.length = 0;
+        availableProviders.push(...reordered);
+      }
+    }
+
+    const errors: Error[] = [];
+
+    // Try each provider in order
+    for (const provider of availableProviders) {
+      if (options?.signal?.aborted) {
+        throw new Error("Search aborted");
+      }
+      try {
+        const results = await provider.search(query, options);
+        return results; // Circuit breaker: return on first success
+      } catch (error) {
+        if (options?.signal?.aborted) {
+          throw error instanceof Error ? error : new Error("Search aborted");
+        }
+        errors.push(
+          error instanceof Error ? error : new Error(`Unknown error from ${provider.name}`),
+        );
+        // Continue to next provider
+      }
+    }
+
+    // All providers failed
+    throw new AggregateError(
+      errors,
+      `All search providers failed (tried ${availableProviders.length} providers)`,
+    );
+  }
+}