@aria-cli/tools 1.0.0

package/tests/providers/brave.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { BraveSearchProvider } from "../../src/providers/brave.js";
+import type { SearchResult } from "../../src/providers/search-provider.js";
+
+describe("BraveSearchProvider", () => {
+  let provider: BraveSearchProvider;
+
+  beforeEach(() => {
+    provider = new BraveSearchProvider();
+    vi.stubEnv("BRAVE_API_KEY", "BSA-test-key-12345");
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  it("has correct provider metadata", () => {
+    expect(provider.name).toBe("brave");
+    expect(provider.requiresApiKey).toBe(true);
+    expect(provider.priority).toBe(1);
+  });
+
+  it("isAvailable returns true when BRAVE_API_KEY is set", () => {
+    const available = provider.isAvailable();
+    expect(available).toBe(true);
+  });
+
+  it("isAvailable returns false when BRAVE_API_KEY is missing", () => {
+    vi.stubEnv("BRAVE_API_KEY", "");
+    const freshProvider = new BraveSearchProvider();
+    expect(freshProvider.isAvailable()).toBe(false);
+  });
+
+  it("returns SearchResult[] on success", async () => {
+    const mockResults: SearchResult[] = [
+      {
+        title: "Brave Search",
+        url: "https://search.brave.com",
+        content: "Brave Search is an independent search engine with its own index.",
+        score: 0.97,
+      },
+      {
+        title: "Brave Browser",
+        url: "https://brave.com",
+        content: "Browse privately. Search privately. And ditch Big Tech.",
+        score: 0.85,
+      },
+    ];
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          web: {
+            results: mockResults.map((r) => ({
+              title: r.title,
+              url: r.url,
+              description: r.content,
+              relevance_score: r.score,
+            })),
+          },
+        }),
+      }),
+    );
+
+    const results = await provider.search("private search engine");
+    expect(results).toBeInstanceOf(Array);
+    expect(results.length).toBeGreaterThan(0);
+    for (const result of results) {
+      expect(result).toHaveProperty("title");
+      expect(result).toHaveProperty("url");
+      expect(result).toHaveProperty("content");
+      expect(typeof result.title).toBe("string");
+      expect(typeof result.url).toBe("string");
+      expect(typeof result.content).toBe("string");
+    }
+  });
+
+  it("respects domain filtering options", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ web: { results: [] } }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    await provider.search("test", { domains: ["example.com"], excludeDomains: ["spam.com"] });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("handles API errors (4xx/5xx)", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 500,
+        statusText: "Internal Server Error",
+      }),
+    );
+
+    await expect(provider.search("test query")).rejects.toThrow();
+  });
+
+  it("handles 403 forbidden (invalid API key)", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 403,
+        statusText: "Forbidden",
+      }),
+    );
+
+    await expect(provider.search("test query")).rejects.toThrow();
+  });
+
+  it("returns empty array for no results", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({ web: { results: [] } }),
+      }),
+    );
+
+    const results = await provider.search("xyzzy_nonexistent_query_12345");
+    expect(results).toEqual([]);
+  });
+
+  it("handles network timeout", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockRejectedValue(new DOMException("The operation was aborted", "AbortError")),
+    );
+
+    await expect(provider.search("test query")).rejects.toThrow();
+  });
+
+  it("passes timeRange option correctly", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ web: { results: [] } }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    await provider.search("recent events", { timeRange: "week" });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const callUrl = fetchMock.mock.calls[0][0] as string;
+    // Brave uses query params, so the URL should contain freshness
+    expect(callUrl).toContain("freshness");
+  });
+});

package/tests/providers/duckduckgo.test.ts

@@ -0,0 +1,207 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { DuckDuckGoSearchProvider } from "../../src/providers/duckduckgo.js";
+import type { SearchResult } from "../../src/providers/search-provider.js";
+
+describe("DuckDuckGoSearchProvider", () => {
+  let provider: DuckDuckGoSearchProvider;
+
+  beforeEach(() => {
+    provider = new DuckDuckGoSearchProvider();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("has correct provider metadata", () => {
+    expect(provider.name).toBe("duckduckgo");
+    expect(provider.requiresApiKey).toBe(false);
+    expect(provider.priority).toBe(6);
+  });
+
+  it("isAvailable returns true (no API key required)", () => {
+    // DuckDuckGo is a free, keyless search provider
+    const available = provider.isAvailable();
+    expect(available).toBe(true);
+  });
+
+  it("returns SearchResult[] on success", async () => {
+    // Mock HTML response that simulates DuckDuckGo search results page
+    const mockHtml = `<html><body>
+      <div class="result">
+        <a class="result__a" href="https://example.com/privacy">DuckDuckGo - Privacy, simplified.</a>
+        Some text
+        <a class="result__snippet">The Internet privacy company that empowers you to seamlessly take control of your personal information online.</a>
+      </div>
+      <div class="result">
+        <a class="result__a" href="https://example.com/api">DuckDuckGo Search API</a>
+        Some text
+        <a class="result__snippet">DuckDuckGo Instant Answer API.</a>
+      </div>
+    </body></html>`;
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        text: async () => mockHtml,
+      }),
+    );
+
+    const results = await provider.search("privacy search engine");
+    expect(results).toBeInstanceOf(Array);
+    expect(results.length).toBeGreaterThan(0);
+    for (const result of results) {
+      expect(result).toHaveProperty("title");
+      expect(result).toHaveProperty("url");
+      expect(result).toHaveProperty("content");
+      expect(typeof result.title).toBe("string");
+      expect(typeof result.url).toBe("string");
+      expect(typeof result.content).toBe("string");
+    }
+  });
+
+  it("resolves DuckDuckGo redirect links via uddg parameter", async () => {
+    const mockHtml = `<html><body>
+      <div class="result">
+        <a class="result__a" href="//duckduckgo.com/l/?uddg=https%3A%2F%2Fexample.com%2Fprivacy%3Fa%3D1%26b%3D2&amp;rut=abc">
+          DuckDuckGo Privacy
+        </a>
+        <a class="result__snippet">Privacy link snippet</a>
+      </div>
+      <div class="result">
+        <a class="result__a" href="https://duckduckgo.com/l/?uddg=https%3A%2F%2Fexample.org%2Fdocs&amp;rut=def">
+          Example Docs
+        </a>
+        <a class="result__snippet">Docs snippet</a>
+      </div>
+    </body></html>`;
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        text: async () => mockHtml,
+      }),
+    );
+
+    const results = await provider.search("privacy search engine");
+    expect(results).toHaveLength(2);
+    expect(results[0]).toMatchObject({
+      title: "DuckDuckGo Privacy",
+      url: "https://example.com/privacy?a=1&b=2",
+      content: "Privacy link snippet",
+    });
+    expect(results[1]).toMatchObject({
+      title: "Example Docs",
+      url: "https://example.org/docs",
+      content: "Docs snippet",
+    });
+  });
+
+  it("respects limit option", async () => {
+    const mockHtml = `
+      <html>
+        <body>
+          <div class="result">
+            <a class="result__a" href="https://example.com">Only result</a>
+            <a class="result__snippet">Content</a>
+          </div>
+        </body>
+      </html>
+    `;
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        text: async () => mockHtml,
+      }),
+    );
+
+    const results = await provider.search("test", { limit: 1 });
+    expect(results.length).toBeLessThanOrEqual(1);
+  });
+
+  it("handles API errors (4xx/5xx)", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 503,
+        statusText: "Service Unavailable",
+      }),
+    );
+
+    await expect(provider.search("test query")).rejects.toThrow();
+  });
+
+  it("returns empty array for no results", async () => {
+    const mockHtml = `
+      <html>
+        <body>
+          <div class="no-results">No results found</div>
+        </body>
+      </html>
+    `;
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        text: async () => mockHtml,
+      }),
+    );
+
+    const results = await provider.search("xyzzy_nonexistent_query_12345");
+    expect(results).toEqual([]);
+  });
+
+  it("throws when results exist but no usable URLs can be extracted", async () => {
+    const mockHtml = `<html><body>
+      <div class="result">
+        <a class="result__a" href="https://duckduckgo.com/?q=privacy">Internal DuckDuckGo Link</a>
+        <a class="result__snippet">Snippet</a>
+      </div>
+    </body></html>`;
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        text: async () => mockHtml,
+      }),
+    );
+
+    await expect(provider.search("privacy")).rejects.toThrow("Could not resolve any result URLs");
+  });
+
+  it("handles network timeout", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockRejectedValue(new DOMException("The operation was aborted", "AbortError")),
+    );
+
+    await expect(provider.search("test query")).rejects.toThrow();
+  });
+
+  it("handles malformed response body", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => {
+          throw new SyntaxError("Unexpected end of JSON input");
+        },
+      }),
+    );
+
+    await expect(provider.search("test query")).rejects.toThrow();
+  });
+});

package/tests/providers/exa.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { ExaSearchProvider } from "../../src/providers/exa.js";
+import type { SearchResult } from "../../src/providers/search-provider.js";
+
+describe("ExaSearchProvider", () => {
+  let provider: ExaSearchProvider;
+
+  beforeEach(() => {
+    provider = new ExaSearchProvider();
+    vi.stubEnv("EXA_API_KEY", "exa-test-key-12345");
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  it("has correct provider metadata", () => {
+    expect(provider.name).toBe("exa");
+    expect(provider.requiresApiKey).toBe(true);
+    expect(provider.priority).toBe(3);
+  });
+
+  it("isAvailable returns true when EXA_API_KEY is set", () => {
+    const available = provider.isAvailable();
+    expect(available).toBe(true);
+  });
+
+  it("isAvailable returns false when EXA_API_KEY is missing", () => {
+    vi.stubEnv("EXA_API_KEY", "");
+    const freshProvider = new ExaSearchProvider();
+    expect(freshProvider.isAvailable()).toBe(false);
+  });
+
+  it("returns SearchResult[] on success", async () => {
+    const mockResults: SearchResult[] = [
+      {
+        title: "Exa - Neural Search",
+        url: "https://exa.ai",
+        content: "Exa is a search engine designed for AI applications with neural retrieval.",
+        score: 0.96,
+        publishedDate: "2025-12-01",
+      },
+      {
+        title: "Exa API Documentation",
+        url: "https://docs.exa.ai",
+        content: "Build with Exa's neural search API for content discovery.",
+        score: 0.89,
+      },
+    ];
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          results: mockResults.map((r) => ({
+            title: r.title,
+            url: r.url,
+            text: r.content,
+            score: r.score,
+            publishedDate: r.publishedDate,
+          })),
+        }),
+      }),
+    );
+
+    const results = await provider.search("neural search API");
+    expect(results).toBeInstanceOf(Array);
+    expect(results.length).toBeGreaterThan(0);
+    for (const result of results) {
+      expect(result).toHaveProperty("title");
+      expect(result).toHaveProperty("url");
+      expect(result).toHaveProperty("content");
+      expect(typeof result.title).toBe("string");
+      expect(typeof result.url).toBe("string");
+      expect(typeof result.content).toBe("string");
+    }
+  });
+
+  it("includes publishedDate when available", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          results: [
+            {
+              title: "Article",
+              url: "https://example.com/article",
+              text: "Content",
+              score: 0.9,
+              publishedDate: "2025-11-15",
+            },
+          ],
+        }),
+      }),
+    );
+
+    const results = await provider.search("test");
+    expect(results[0].publishedDate).toBe("2025-11-15");
+  });
+
+  it("handles API errors (4xx/5xx)", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 500,
+        statusText: "Internal Server Error",
+      }),
+    );
+
+    await expect(provider.search("test query")).rejects.toThrow();
+  });
+
+  it("handles 401 unauthorized (bad API key)", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 401,
+        statusText: "Unauthorized",
+        json: async () => ({ error: "Invalid API key" }),
+      }),
+    );
+
+    await expect(provider.search("test query")).rejects.toThrow();
+  });
+
+  it("returns empty array for no results", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({ results: [] }),
+      }),
+    );
+
+    const results = await provider.search("xyzzy_nonexistent_query_12345");
+    expect(results).toEqual([]);
+  });
+
+  it("handles network timeout", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockRejectedValue(new DOMException("The operation was aborted", "AbortError")),
+    );
+
+    await expect(provider.search("test query")).rejects.toThrow();
+  });
+
+  it("supports domain filtering through options", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ results: [] }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    await provider.search("test", {
+      domains: ["arxiv.org", "github.com"],
+      excludeDomains: ["pinterest.com"],
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const callArgs = fetchMock.mock.calls[0];
+    const body = JSON.parse(callArgs[1]?.body as string);
+    expect(body.includeDomains).toEqual(["arxiv.org", "github.com"]);
+    expect(body.excludeDomains).toEqual(["pinterest.com"]);
+  });
+});

package/tests/providers/firecrawl.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { FirecrawlSearchProvider } from "../../src/providers/firecrawl.js";
+import type { SearchResult } from "../../src/providers/search-provider.js";
+
+describe("FirecrawlSearchProvider", () => {
+  let provider: FirecrawlSearchProvider;
+
+  beforeEach(() => {
+    provider = new FirecrawlSearchProvider();
+    vi.stubEnv("FIRECRAWL_API_KEY", "fc-test-key-12345");
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  it("has correct provider metadata", () => {
+    expect(provider.name).toBe("firecrawl");
+    expect(provider.requiresApiKey).toBe(true);
+    expect(provider.priority).toBe(2);
+  });
+
+  it("isAvailable returns true when FIRECRAWL_API_KEY is set", () => {
+    const available = provider.isAvailable();
+    expect(available).toBe(true);
+  });
+
+  it("isAvailable returns false when FIRECRAWL_API_KEY is missing", () => {
+    vi.stubEnv("FIRECRAWL_API_KEY", "");
+    const freshProvider = new FirecrawlSearchProvider();
+    expect(freshProvider.isAvailable()).toBe(false);
+  });
+
+  it("returns SearchResult[] on success", async () => {
+    const mockResults: SearchResult[] = [
+      {
+        title: "Firecrawl - Web Scraping API",
+        url: "https://firecrawl.dev",
+        content:
+          "Firecrawl turns entire websites into clean, LLM-ready markdown or structured data.",
+        score: 0.94,
+      },
+      {
+        title: "Firecrawl Documentation",
+        url: "https://docs.firecrawl.dev",
+        content: "API reference and guides for using Firecrawl's web scraping and search.",
+        score: 0.87,
+      },
+    ];
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          success: true,
+          data: mockResults.map((r) => ({
+            title: r.title,
+            url: r.url,
+            markdown: r.content,
+            score: r.score,
+          })),
+        }),
+      }),
+    );
+
+    const results = await provider.search("web scraping API");
+    expect(results).toBeInstanceOf(Array);
+    expect(results.length).toBeGreaterThan(0);
+    for (const result of results) {
+      expect(result).toHaveProperty("title");
+      expect(result).toHaveProperty("url");
+      expect(result).toHaveProperty("content");
+      expect(typeof result.title).toBe("string");
+      expect(typeof result.url).toBe("string");
+      expect(typeof result.content).toBe("string");
+    }
+  });
+
+  it("respects limit option", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        success: true,
+        data: [{ title: "Single Result", url: "https://example.com", markdown: "Content" }],
+      }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const results = await provider.search("test", { limit: 3 });
+    expect(results.length).toBeLessThanOrEqual(3);
+
+    // Verify limit was passed in the request body
+    const callArgs = fetchMock.mock.calls[0];
+    const body = JSON.parse(callArgs[1]?.body as string);
+    expect(body.limit).toBe(3);
+  });
+
+  it("handles API errors (4xx/5xx)", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 500,
+        statusText: "Internal Server Error",
+      }),
+    );
+
+    await expect(provider.search("test query")).rejects.toThrow();
+  });
+
+  it("handles API success:false response", async () => {
+    // Firecrawl can return 200 with success: false in the body
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          success: false,
+          error: "Rate limit exceeded",
+        }),
+      }),
+    );
+
+    await expect(provider.search("test query")).rejects.toThrow();
+  });
+
+  it("returns empty array for no results", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({ success: true, data: [] }),
+      }),
+    );
+
+    const results = await provider.search("xyzzy_nonexistent_query_12345");
+    expect(results).toEqual([]);
+  });
+
+  it("handles network timeout", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockRejectedValue(new DOMException("The operation was aborted", "AbortError")),
+    );
+
+    await expect(provider.search("test query")).rejects.toThrow();
+  });
+
+  it("handles 402 payment required (quota exceeded)", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 402,
+        statusText: "Payment Required",
+        json: async () => ({ error: "Credit limit exceeded" }),
+      }),
+    );
+
+    await expect(provider.search("test query")).rejects.toThrow();
+  });
+});