@aria-cli/tools 1.0.18 → 1.0.31

package/dist-cjs/providers/duckduckgo.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuckDuckGoSearchProvider = void 0;
+const search_provider_js_1 = require("./search-provider.js");
+class DuckDuckGoSearchProvider {
+    name = "duckduckgo";
+    requiresApiKey = false;
+    priority = 6;
+    isAvailable() {
+        // DuckDuckGo is always available (no API key required)
+        return true;
+    }
+    async search(query, options) {
+        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 } = (0, search_provider_js_1.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 = [];
+            // First pass: extract all result__a links (title + url)
+            const linkMap = new Map();
+            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 = [];
+            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
+     */
+    stripHtmlTags(html) {
+        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
+     */
+    decodeHtmlEntities(text) {
+        return text
+            .replace(/&amp;/g, "&")
+            .replace(/&lt;/g, "<")
+            .replace(/&gt;/g, ">")
+            .replace(/&quot;/g, '"')
+            .replace(/&#39;/g, "'");
+    }
+    resolveDuckDuckGoResultUrl(rawHref) {
+        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;
+        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);
+    }
+    normalizeResultUrl(candidate) {
+        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;
+        }
+    }
+}
+exports.DuckDuckGoSearchProvider = DuckDuckGoSearchProvider;
+//# sourceMappingURL=duckduckgo.js.map

package/dist-cjs/providers/exa.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExaSearchProvider = void 0;
+const search_provider_js_1 = require("./search-provider.js");
+class ExaSearchProvider {
+    env;
+    name = "exa";
+    requiresApiKey = true;
+    priority = 3;
+    constructor(env = process.env) {
+        this.env = env;
+    }
+    isAvailable() {
+        const apiKey = (0, search_provider_js_1.resolveSearchProviderEnv)(this.env).EXA_API_KEY;
+        return Boolean(apiKey && apiKey.trim().length > 0);
+    }
+    async search(query, options) {
+        const apiKey = (0, search_provider_js_1.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 = {
+            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 } = (0, search_provider_js_1.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 || []);
+            return results.map((r) => ({
+                title: r.title,
+                url: r.url,
+                content: r.text || "",
+                score: r.score,
+                publishedDate: r.publishedDate,
+            }));
+        }
+        finally {
+            cleanup();
+        }
+    }
+}
+exports.ExaSearchProvider = ExaSearchProvider;
+//# sourceMappingURL=exa.js.map

package/dist-cjs/providers/firecrawl.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FirecrawlSearchProvider = void 0;
+const search_provider_js_1 = require("./search-provider.js");
+class FirecrawlSearchProvider {
+    env;
+    name = "firecrawl";
+    requiresApiKey = true;
+    priority = 2;
+    constructor(env = process.env) {
+        this.env = env;
+    }
+    isAvailable() {
+        const apiKey = (0, search_provider_js_1.resolveSearchProviderEnv)(this.env).FIRECRAWL_API_KEY;
+        return Boolean(apiKey && apiKey.trim().length > 0);
+    }
+    async search(query, options) {
+        const apiKey = (0, search_provider_js_1.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 = {
+            query,
+            limit,
+        };
+        const { signal, cleanup } = (0, search_provider_js_1.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 || []);
+            return results.map((r) => ({
+                title: r.title,
+                url: r.url,
+                content: r.markdown || "",
+                score: r.score,
+            }));
+        }
+        finally {
+            cleanup();
+        }
+    }
+}
+exports.FirecrawlSearchProvider = FirecrawlSearchProvider;
+//# sourceMappingURL=firecrawl.js.map

package/dist-cjs/providers/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchProviderRouter = exports.FirecrawlSearchProvider = exports.ExaSearchProvider = exports.BraveSearchProvider = exports.TavilySearchProvider = exports.DuckDuckGoSearchProvider = exports.JinaSearchProvider = void 0;
+var jina_js_1 = require("./jina.js");
+Object.defineProperty(exports, "JinaSearchProvider", { enumerable: true, get: function () { return jina_js_1.JinaSearchProvider; } });
+var duckduckgo_js_1 = require("./duckduckgo.js");
+Object.defineProperty(exports, "DuckDuckGoSearchProvider", { enumerable: true, get: function () { return duckduckgo_js_1.DuckDuckGoSearchProvider; } });
+var tavily_js_1 = require("./tavily.js");
+Object.defineProperty(exports, "TavilySearchProvider", { enumerable: true, get: function () { return tavily_js_1.TavilySearchProvider; } });
+var brave_js_1 = require("./brave.js");
+Object.defineProperty(exports, "BraveSearchProvider", { enumerable: true, get: function () { return brave_js_1.BraveSearchProvider; } });
+var exa_js_1 = require("./exa.js");
+Object.defineProperty(exports, "ExaSearchProvider", { enumerable: true, get: function () { return exa_js_1.ExaSearchProvider; } });
+var firecrawl_js_1 = require("./firecrawl.js");
+Object.defineProperty(exports, "FirecrawlSearchProvider", { enumerable: true, get: function () { return firecrawl_js_1.FirecrawlSearchProvider; } });
+var router_js_1 = require("./router.js");
+Object.defineProperty(exports, "SearchProviderRouter", { enumerable: true, get: function () { return router_js_1.SearchProviderRouter; } });
+//# sourceMappingURL=index.js.map

package/dist-cjs/providers/jina.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JinaSearchProvider = void 0;
+const search_provider_js_1 = require("./search-provider.js");
+class JinaSearchProvider {
+    env;
+    name = "jina";
+    requiresApiKey = false;
+    priority = 5;
+    constructor(env = process.env) {
+        this.env = env;
+    }
+    isAvailable() {
+        // Jina works without an API key (20 req/min), or with a key (200 req/min)
+        return true;
+    }
+    async search(query, options) {
+        const apiKey = (0, search_provider_js_1.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 = {
+            Accept: "application/json",
+        };
+        if (apiKey) {
+            headers.Authorization = `Bearer ${apiKey}`;
+        }
+        const { signal, cleanup } = (0, search_provider_js_1.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 || []);
+            // 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();
+        }
+    }
+}
+exports.JinaSearchProvider = JinaSearchProvider;
+//# sourceMappingURL=jina.js.map

package/dist-cjs/providers/router.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchProviderRouter = void 0;
+const types_1 = require("@aria-cli/types");
+const search_provider_js_1 = require("./search-provider.js");
+class SearchProviderRouter {
+    _providers;
+    env;
+    constructor(_providers, env = process.env) {
+        this._providers = _providers;
+        this.env = 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() {
+        const env = (0, search_provider_js_1.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
+                types_1.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, options) {
+        if (options?.signal?.aborted) {
+            throw new Error("Search aborted");
+        }
+        const env = (0, search_provider_js_1.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 = [];
+        // 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)`);
+    }
+}
+exports.SearchProviderRouter = SearchProviderRouter;
+//# sourceMappingURL=router.js.map

package/dist-cjs/providers/search-provider.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSearchProviderEnv = resolveSearchProviderEnv;
+exports.createProviderAbortSignal = createProviderAbortSignal;
+function resolveSearchProviderEnv(env = process.env) {
+    return {
+        ARIA_SEARCH_PROVIDER: env.ARIA_SEARCH_PROVIDER,
+        BRAVE_API_KEY: env.BRAVE_API_KEY,
+        FIRECRAWL_API_KEY: env.FIRECRAWL_API_KEY,
+        EXA_API_KEY: env.EXA_API_KEY,
+        TAVILY_API_KEY: env.TAVILY_API_KEY,
+        JINA_API_KEY: env.JINA_API_KEY,
+    };
+}
+function createProviderAbortSignal(timeoutMs, callerSignal) {
+    const controller = new AbortController();
+    const onCallerAbort = () => controller.abort();
+    if (callerSignal) {
+        if (callerSignal.aborted) {
+            controller.abort();
+        }
+        else {
+            callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+        }
+    }
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            clearTimeout(timeout);
+            if (callerSignal) {
+                callerSignal.removeEventListener("abort", onCallerAbort);
+            }
+        },
+    };
+}
+//# sourceMappingURL=search-provider.js.map

package/dist-cjs/providers/tavily.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TavilySearchProvider = void 0;
+const search_provider_js_1 = require("./search-provider.js");
+class TavilySearchProvider {
+    env;
+    name = "tavily";
+    requiresApiKey = true;
+    priority = 4;
+    constructor(env = process.env) {
+        this.env = env;
+    }
+    isAvailable() {
+        const apiKey = (0, search_provider_js_1.resolveSearchProviderEnv)(this.env).TAVILY_API_KEY;
+        return Boolean(apiKey && apiKey.trim().length > 0);
+    }
+    async search(query, options) {
+        const apiKey = (0, search_provider_js_1.resolveSearchProviderEnv)(this.env).TAVILY_API_KEY;
+        if (!apiKey) {
+            throw new Error("TAVILY_API_KEY environment variable is not set");
+        }
+        const limit = options?.limit ?? 5;
+        const body = {
+            api_key: apiKey,
+            query,
+            max_results: limit,
+            ...(options?.topic && { topic: options.topic }),
+            ...(options?.domains && { include_domains: options.domains }),
+            ...(options?.excludeDomains && { exclude_domains: options.excludeDomains }),
+        };
+        const { signal, cleanup } = (0, search_provider_js_1.createProviderAbortSignal)(30_000, options?.signal);
+        try {
+            const response = await fetch("https://api.tavily.com/search", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(body),
+                signal,
+            });
+            if (!response.ok) {
+                throw new Error(`Tavily Search API error: ${response.status} ${response.statusText}`);
+            }
+            const json = await response.json();
+            const results = (json.results || []);
+            return results.map((r) => ({
+                title: r.title,
+                url: r.url,
+                content: r.content,
+                score: r.score,
+            }));
+        }
+        finally {
+            cleanup();
+        }
+    }
+}
+exports.TavilySearchProvider = TavilySearchProvider;
+//# sourceMappingURL=tavily.js.map