@aria-cli/tools 1.0.0

package/tests/providers/jina.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { JinaSearchProvider } from "../../src/providers/jina.js";
+import type { SearchResult } from "../../src/providers/search-provider.js";
+
+describe("JinaSearchProvider", () => {
+  let provider: JinaSearchProvider;
+
+  beforeEach(() => {
+    provider = new JinaSearchProvider();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("has correct provider metadata", () => {
+    expect(provider.name).toBe("jina");
+    expect(provider.requiresApiKey).toBe(false);
+    expect(provider.priority).toBe(5);
+  });
+
+  it("isAvailable returns true (no API key required)", () => {
+    // Jina's free tier doesn't require an API key
+    const available = provider.isAvailable();
+    expect(available).toBe(true);
+  });
+
+  it("returns SearchResult[] on success", async () => {
+    const mockResults: SearchResult[] = [
+      {
+        title: "TypeScript Handbook",
+        url: "https://www.typescriptlang.org/docs/handbook",
+        content: "The TypeScript Handbook is a comprehensive guide to the TypeScript language.",
+        score: 0.95,
+      },
+      {
+        title: "TypeScript GitHub",
+        url: "https://github.com/microsoft/TypeScript",
+        content: "TypeScript is a superset of JavaScript that compiles to clean JavaScript output.",
+        score: 0.88,
+      },
+    ];
+
+    // Mock global fetch to simulate Jina API response
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: mockResults.map((r) => ({
+            title: r.title,
+            url: r.url,
+            content: r.content,
+            score: r.score,
+          })),
+        }),
+      }),
+    );
+
+    const results = await provider.search("TypeScript");
+    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 () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: [{ title: "Result 1", url: "https://example.com/1", content: "Content 1" }],
+        }),
+      }),
+    );
+
+    const results = await provider.search("TypeScript", { limit: 1 });
+    expect(results.length).toBeLessThanOrEqual(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 429 rate limit errors", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 429,
+        statusText: "Too Many Requests",
+      }),
+    );
+
+    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 () => ({ 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 fetch network failure", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new TypeError("Failed to fetch")));
+
+    await expect(provider.search("test query")).rejects.toThrow();
+  });
+});

package/tests/providers/router.test.ts

@@ -0,0 +1,328 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { SearchProviderRouter } from "../../src/providers/router.js";
+import { JinaSearchProvider } from "../../src/providers/jina.js";
+import { DuckDuckGoSearchProvider } from "../../src/providers/duckduckgo.js";
+import { TavilySearchProvider } from "../../src/providers/tavily.js";
+import { BraveSearchProvider } from "../../src/providers/brave.js";
+import { ExaSearchProvider } from "../../src/providers/exa.js";
+import { FirecrawlSearchProvider } from "../../src/providers/firecrawl.js";
+import type { SearchProvider, SearchResult } from "../../src/providers/search-provider.js";
+
+/**
+ * Helper to create a mock provider with controllable availability and search behavior.
+ */
+function createMockProvider(
+  overrides: Partial<SearchProvider> & { name: string; priority: number },
+): SearchProvider {
+  return {
+    requiresApiKey: false,
+    isAvailable: () => true,
+    search: vi.fn().mockResolvedValue([]),
+    ...overrides,
+  };
+}
+
+describe("SearchProviderRouter", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  describe("resolve()", () => {
+    it("selects highest-priority available provider", () => {
+      // Lower priority number = higher priority
+      const brave = createMockProvider({ name: "brave", priority: 1, isAvailable: () => true });
+      const firecrawl = createMockProvider({
+        name: "firecrawl",
+        priority: 2,
+        isAvailable: () => true,
+      });
+      const jina = createMockProvider({ name: "jina", priority: 5, isAvailable: () => true });
+
+      const router = new SearchProviderRouter([jina, brave, firecrawl]);
+      const selected = router.resolve();
+
+      expect(selected.name).toBe("brave");
+    });
+
+    it("skips unavailable providers", () => {
+      const brave = createMockProvider({ name: "brave", priority: 1, isAvailable: () => false });
+      const firecrawl = createMockProvider({
+        name: "firecrawl",
+        priority: 2,
+        isAvailable: () => true,
+      });
+      const jina = createMockProvider({ name: "jina", priority: 5, isAvailable: () => true });
+
+      const router = new SearchProviderRouter([brave, firecrawl, jina]);
+      const selected = router.resolve();
+
+      expect(selected.name).toBe("firecrawl");
+    });
+
+    it("respects ARIA_SEARCH_PROVIDER override", () => {
+      vi.stubEnv("ARIA_SEARCH_PROVIDER", "jina");
+
+      const brave = createMockProvider({ name: "brave", priority: 1, isAvailable: () => true });
+      const jina = createMockProvider({ name: "jina", priority: 5, isAvailable: () => true });
+
+      const router = new SearchProviderRouter([brave, jina]);
+      const selected = router.resolve();
+
+      expect(selected.name).toBe("jina");
+    });
+
+    it("throws if ARIA_SEARCH_PROVIDER override names unavailable provider", () => {
+      vi.stubEnv("ARIA_SEARCH_PROVIDER", "nonexistent");
+
+      const jina = createMockProvider({ name: "jina", priority: 5, isAvailable: () => true });
+      const router = new SearchProviderRouter([jina]);
+
+      expect(() => router.resolve()).toThrow();
+    });
+
+    it("falls back to Jina when no API keys set", () => {
+      // All API-key providers are unavailable; Jina (no key required) should be selected
+      const brave = createMockProvider({
+        name: "brave",
+        priority: 1,
+        requiresApiKey: true,
+        isAvailable: () => false,
+      });
+      const tavily = createMockProvider({
+        name: "tavily",
+        priority: 4,
+        requiresApiKey: true,
+        isAvailable: () => false,
+      });
+      const jina = createMockProvider({
+        name: "jina",
+        priority: 5,
+        requiresApiKey: false,
+        isAvailable: () => true,
+      });
+      const duckduckgo = createMockProvider({
+        name: "duckduckgo",
+        priority: 6,
+        requiresApiKey: false,
+        isAvailable: () => true,
+      });
+
+      const router = new SearchProviderRouter([brave, tavily, jina, duckduckgo]);
+      const selected = router.resolve();
+
+      // Jina has higher priority (5) than DuckDuckGo (6), so it should be selected
+      expect(selected.name).toBe("jina");
+    });
+
+    it("throws when no providers are available", () => {
+      const unavailable = createMockProvider({
+        name: "dead",
+        priority: 1,
+        isAvailable: () => false,
+      });
+
+      const router = new SearchProviderRouter([unavailable]);
+
+      expect(() => router.resolve()).toThrow();
+    });
+  });
+
+  describe("search()", () => {
+    it("delegates search to resolved provider", async () => {
+      const mockResults: SearchResult[] = [
+        { title: "Test", url: "https://test.com", content: "Test content" },
+      ];
+      const provider = createMockProvider({
+        name: "mock",
+        priority: 1,
+        search: vi.fn().mockResolvedValue(mockResults),
+      });
+
+      const router = new SearchProviderRouter([provider]);
+      const results = await router.search("test query");
+
+      expect(results).toEqual(mockResults);
+      expect(provider.search).toHaveBeenCalledWith("test query", undefined);
+    });
+
+    it("passes options through to the provider", async () => {
+      const searchFn = vi.fn().mockResolvedValue([]);
+      const provider = createMockProvider({
+        name: "mock",
+        priority: 1,
+        search: searchFn,
+      });
+
+      const router = new SearchProviderRouter([provider]);
+      await router.search("test", { limit: 5, topic: "news" });
+
+      expect(searchFn).toHaveBeenCalledWith("test", { limit: 5, topic: "news" });
+    });
+
+    it("passes abort signal through to providers", async () => {
+      const searchFn = vi.fn().mockResolvedValue([]);
+      const provider = createMockProvider({
+        name: "mock",
+        priority: 1,
+        search: searchFn,
+      });
+      const signal = new AbortController().signal;
+
+      const router = new SearchProviderRouter([provider]);
+      await router.search("test", { limit: 5, signal });
+
+      expect(searchFn).toHaveBeenCalledWith("test", { limit: 5, signal });
+    });
+
+    it("short-circuits when abort signal is already aborted", async () => {
+      const searchFn = vi.fn().mockResolvedValue([]);
+      const provider = createMockProvider({
+        name: "mock",
+        priority: 1,
+        search: searchFn,
+      });
+      const controller = new AbortController();
+      controller.abort();
+
+      const router = new SearchProviderRouter([provider]);
+      await expect(router.search("test", { signal: controller.signal })).rejects.toThrow(
+        "Search aborted",
+      );
+      expect(searchFn).not.toHaveBeenCalled();
+    });
+
+    it("falls back to DuckDuckGo when Jina fails", async () => {
+      const jinaSearch = vi.fn().mockRejectedValue(new Error("Jina API error"));
+      const ddgResults: SearchResult[] = [
+        { title: "DDG Result", url: "https://ddg.com", content: "Fallback content" },
+      ];
+      const ddgSearch = vi.fn().mockResolvedValue(ddgResults);
+
+      const jina = createMockProvider({
+        name: "jina",
+        priority: 5,
+        search: jinaSearch,
+      });
+      const ddg = createMockProvider({
+        name: "duckduckgo",
+        priority: 6,
+        search: ddgSearch,
+      });
+
+      // Only these two free providers available
+      const router = new SearchProviderRouter([jina, ddg]);
+      const results = await router.search("test query");
+
+      expect(results).toEqual(ddgResults);
+    });
+
+    it("circuit breaker: tries in priority order, skips failing providers", async () => {
+      const braveSearch = vi.fn().mockRejectedValue(new Error("Brave down"));
+      const firecrawlSearch = vi.fn().mockRejectedValue(new Error("Firecrawl down"));
+      const exaResults: SearchResult[] = [
+        { title: "Exa Result", url: "https://exa.ai/r", content: "Found via Exa" },
+      ];
+      const exaSearch = vi.fn().mockResolvedValue(exaResults);
+
+      const brave = createMockProvider({ name: "brave", priority: 1, search: braveSearch });
+      const firecrawl = createMockProvider({
+        name: "firecrawl",
+        priority: 2,
+        search: firecrawlSearch,
+      });
+      const exa = createMockProvider({ name: "exa", priority: 3, search: exaSearch });
+
+      const router = new SearchProviderRouter([brave, firecrawl, exa]);
+      const results = await router.search("important query");
+
+      // Should have tried brave first, then firecrawl, then exa
+      expect(braveSearch).toHaveBeenCalledTimes(1);
+      expect(firecrawlSearch).toHaveBeenCalledTimes(1);
+      expect(exaSearch).toHaveBeenCalledTimes(1);
+      expect(results).toEqual(exaResults);
+    });
+
+    it("all providers unavailable throws AggregateError", async () => {
+      const provider1 = createMockProvider({
+        name: "p1",
+        priority: 1,
+        search: vi.fn().mockRejectedValue(new Error("p1 failed")),
+      });
+      const provider2 = createMockProvider({
+        name: "p2",
+        priority: 2,
+        search: vi.fn().mockRejectedValue(new Error("p2 failed")),
+      });
+
+      const router = new SearchProviderRouter([provider1, provider2]);
+
+      try {
+        await router.search("doomed query");
+        expect.unreachable("Should have thrown");
+      } catch (err) {
+        // Should aggregate all provider errors
+        expect(err).toBeInstanceOf(AggregateError);
+        const aggErr = err as AggregateError;
+        expect(aggErr.errors).toHaveLength(2);
+        expect(aggErr.errors[0]).toBeInstanceOf(Error);
+        expect(aggErr.errors[1]).toBeInstanceOf(Error);
+      }
+    });
+
+    it("does not retry a provider that already failed in this search", async () => {
+      const failingSearch = vi.fn().mockRejectedValue(new Error("always fails"));
+      const successSearch = vi
+        .fn()
+        .mockResolvedValue([{ title: "OK", url: "https://ok.com", content: "Success" }]);
+
+      const failing = createMockProvider({ name: "failing", priority: 1, search: failingSearch });
+      const success = createMockProvider({ name: "success", priority: 2, search: successSearch });
+
+      const router = new SearchProviderRouter([failing, success]);
+      await router.search("test");
+
+      // Failing provider should only be called once, not retried
+      expect(failingSearch).toHaveBeenCalledTimes(1);
+      expect(successSearch).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("integration with real provider classes", () => {
+    it("can instantiate router with all real provider classes", () => {
+      const router = new SearchProviderRouter([
+        new BraveSearchProvider(),
+        new FirecrawlSearchProvider(),
+        new ExaSearchProvider(),
+        new TavilySearchProvider(),
+        new JinaSearchProvider(),
+        new DuckDuckGoSearchProvider(),
+      ]);
+
+      // Just verify construction doesn't throw
+      expect(router).toBeDefined();
+    });
+
+    it("resolve() with real providers picks based on availability", () => {
+      // Without any API keys set, only keyless providers are available
+      vi.stubEnv("BRAVE_API_KEY", "");
+      vi.stubEnv("FIRECRAWL_API_KEY", "");
+      vi.stubEnv("EXA_API_KEY", "");
+      vi.stubEnv("TAVILY_API_KEY", "");
+
+      const router = new SearchProviderRouter([
+        new BraveSearchProvider(),
+        new FirecrawlSearchProvider(),
+        new ExaSearchProvider(),
+        new TavilySearchProvider(),
+        new JinaSearchProvider(),
+        new DuckDuckGoSearchProvider(),
+      ]);
+
+      const selected = router.resolve();
+
+      // Should select Jina (priority 5) or DuckDuckGo (priority 6) — both keyless
+      expect(["jina", "duckduckgo"]).toContain(selected.name);
+    });
+  });
+});

package/tests/providers/tavily.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { TavilySearchProvider } from "../../src/providers/tavily.js";
+import type { SearchResult } from "../../src/providers/search-provider.js";
+
+describe("TavilySearchProvider", () => {
+  let provider: TavilySearchProvider;
+
+  beforeEach(() => {
+    provider = new TavilySearchProvider();
+    // Simulate TAVILY_API_KEY being set for tests that need it
+    vi.stubEnv("TAVILY_API_KEY", "tvly-test-key-12345");
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  it("has correct provider metadata", () => {
+    expect(provider.name).toBe("tavily");
+    expect(provider.requiresApiKey).toBe(true);
+    expect(provider.priority).toBe(4);
+  });
+
+  it("isAvailable returns true when TAVILY_API_KEY is set", () => {
+    const available = provider.isAvailable();
+    expect(available).toBe(true);
+  });
+
+  it("isAvailable returns false when TAVILY_API_KEY is missing", () => {
+    vi.stubEnv("TAVILY_API_KEY", "");
+    const freshProvider = new TavilySearchProvider();
+    expect(freshProvider.isAvailable()).toBe(false);
+  });
+
+  it("returns SearchResult[] on success", async () => {
+    const mockResults: SearchResult[] = [
+      {
+        title: "Tavily AI Search",
+        url: "https://tavily.com",
+        content: "Tavily is an AI-native search engine optimized for LLMs and AI agents.",
+        score: 0.98,
+      },
+      {
+        title: "Tavily API Documentation",
+        url: "https://docs.tavily.com",
+        content: "Complete API reference for Tavily search endpoints.",
+        score: 0.91,
+      },
+    ];
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          results: mockResults.map((r) => ({
+            title: r.title,
+            url: r.url,
+            content: r.content,
+            score: r.score,
+          })),
+        }),
+      }),
+    );
+
+    const results = await provider.search("AI 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("includes score in results when available", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          results: [
+            { title: "Result", url: "https://example.com", content: "Content", score: 0.95 },
+          ],
+        }),
+      }),
+    );
+
+    const results = await provider.search("test");
+    expect(results[0].score).toBe(0.95);
+  });
+
+  it("passes topic option to API", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ results: [] }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    await provider.search("latest news", { topic: "news" });
+
+    // Verify the fetch call included the topic parameter
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const callArgs = fetchMock.mock.calls[0];
+    const body = JSON.parse(callArgs[1]?.body as string);
+    expect(body.topic).toBe("news");
+  });
+
+  it("handles API errors (4xx/5xx)", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 401,
+        statusText: "Unauthorized",
+      }),
+    );
+
+    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("handles 422 validation error from API", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 422,
+        statusText: "Unprocessable Entity",
+        json: async () => ({ detail: "Invalid query parameter" }),
+      }),
+    );
+
+    await expect(provider.search("")).rejects.toThrow();
+  });
+});