@aria-cli/tools 1.0.9 → 1.0.11

package/src/providers/brave.ts

@@ -1,80 +0,0 @@
-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

@@ -1,199 +0,0 @@
-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

@@ -1,85 +0,0 @@
-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

@@ -1,77 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,70 +0,0 @@
-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

@@ -1,121 +0,0 @@
-import { log } from "@aria-cli/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)`,
-    );
-  }
-}