@aria-cli/tools 1.0.9 → 1.0.11

package/src/__tests__/web-tools.test.ts

@@ -1,619 +0,0 @@
-/**
- * @aria/tools - Web tool tests (web_search + browse)
- *
- * Tests for the web_search (SearchProviderRouter) and browse (Readability+Turndown) tool executors.
- * All external calls (search providers, fetch) are mocked -- no real network traffic.
- */
-
-import * as dns from "node:dns";
-import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import type { ToolContext } from "../types.js";
-import { executeWebSearch, executeBrowse } from "../executors/web.js";
-import { isPrivateAddress } from "../security/ssrf.js";
-import { searchCache, browseCache } from "../cache/web-cache.js";
-
-vi.mock("node:dns", () => ({
-  promises: {
-    lookup: vi.fn(),
-  },
-}));
-
-// Helper to create a minimal ToolContext
-const createContext = (env: Record<string, string> = {}): ToolContext => ({
-  workingDir: "/tmp/test",
-  env,
-  confirm: async () => true,
-});
-
-describe("web_search", () => {
-  let originalFetch: typeof global.fetch;
-
-  beforeEach(() => {
-    originalFetch = global.fetch;
-    searchCache.clear();
-  });
-
-  afterEach(() => {
-    global.fetch = originalFetch;
-    vi.restoreAllMocks();
-  });
-
-  it("uses DuckDuckGo fallback when no API keys are set", async () => {
-    // With SearchProviderRouter, DuckDuckGo is always available as fallback.
-    // No longer requires TAVILY_API_KEY to be set.
-    const savedKey = process.env.TAVILY_API_KEY;
-    delete process.env.TAVILY_API_KEY;
-
-    // Mock fetch to respond as DuckDuckGo would
-    const mockFetch = vi.fn().mockResolvedValue(
-      new Response(JSON.stringify({ results: [] }), {
-        status: 200,
-        headers: { "Content-Type": "application/json" },
-      }),
-    );
-    vi.stubGlobal("fetch", mockFetch);
-
-    try {
-      const ctx = createContext({});
-      const result = await executeWebSearch({ query: "test" }, ctx);
-
-      // Should succeed via DuckDuckGo fallback, or fail with search error (not missing key)
-      if (result.success) {
-        expect(result.data).toHaveProperty("query", "test");
-      } else {
-        expect(result.message).toContain("Web search failed");
-      }
-    } finally {
-      if (savedKey !== undefined) {
-        process.env.TAVILY_API_KEY = savedKey;
-      }
-    }
-  });
-
-  it("returns formatted results from mocked Tavily provider", async () => {
-    const tavilyResponse = {
-      results: [
-        {
-          title: "TypeScript Handbook",
-          url: "https://www.typescriptlang.org/docs/handbook",
-          content: "The TypeScript Handbook is the official guide to TypeScript.",
-          score: 0.95,
-        },
-        {
-          title: "TypeScript Tutorial",
-          url: "https://www.typescriptlang.org/docs/tutorial",
-          content: "Learn TypeScript from scratch with this tutorial.",
-          score: 0.88,
-        },
-      ],
-    };
-
-    const mockFetch = vi.fn().mockResolvedValue(
-      new Response(JSON.stringify(tavilyResponse), {
-        status: 200,
-        headers: { "Content-Type": "application/json" },
-      }),
-    );
-    vi.stubGlobal("fetch", mockFetch);
-
-    const ctx = createContext({ TAVILY_API_KEY: "tvly-test-key-123" });
-    const result = await executeWebSearch({ query: "typescript guide" }, ctx);
-
-    expect(result.success).toBe(true);
-    expect(result.message).toContain("2 results");
-    expect(result.message).toContain("typescript guide");
-
-    const data = result.data as {
-      query: string;
-      results: Array<{ title: string; url: string; content: string }>;
-    };
-    expect(data.query).toBe("typescript guide");
-    expect(data.results).toHaveLength(2);
-    expect(data.results[0]).toMatchObject({
-      title: "TypeScript Handbook",
-      url: "https://www.typescriptlang.org/docs/handbook",
-      content: expect.stringContaining("TypeScript Handbook"),
-    });
-    expect(data.results[1]).toMatchObject({
-      title: "TypeScript Tutorial",
-      url: "https://www.typescriptlang.org/docs/tutorial",
-    });
-  });
-
-  it("routes through Tavily provider when TAVILY_API_KEY is set", async () => {
-    const mockFetch = vi.fn().mockResolvedValue(
-      new Response(JSON.stringify({ results: [] }), {
-        status: 200,
-        headers: { "Content-Type": "application/json" },
-      }),
-    );
-    vi.stubGlobal("fetch", mockFetch);
-
-    const ctx = createContext({ TAVILY_API_KEY: "tvly-key" });
-    await executeWebSearch({ query: "test query", limit: 3 }, ctx);
-
-    // Verify the Tavily API was called (through the provider)
-    expect(mockFetch).toHaveBeenCalledWith(
-      "https://api.tavily.com/search",
-      expect.objectContaining({
-        method: "POST",
-        body: expect.any(String),
-      }),
-    );
-
-    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
-    expect(body.api_key).toBe("tvly-key");
-    expect(body.query).toBe("test query");
-    expect(body.max_results).toBe(3);
-  });
-
-  it("defaults limit to 10 when not specified", async () => {
-    const mockFetch = vi
-      .fn()
-      .mockResolvedValue(new Response(JSON.stringify({ results: [] }), { status: 200 }));
-    vi.stubGlobal("fetch", mockFetch);
-
-    const ctx = createContext({ TAVILY_API_KEY: "tvly-key" });
-    await executeWebSearch({ query: "test" }, ctx);
-
-    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
-    expect(body.max_results).toBe(10);
-  });
-
-  it("handles provider API error response", async () => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue(
-        new Response("Unauthorized", {
-          status: 401,
-          statusText: "Unauthorized",
-        }),
-      ),
-    );
-
-    const ctx = createContext({ TAVILY_API_KEY: "tvly-bad-key" });
-    const result = await executeWebSearch({ query: "test" }, ctx);
-
-    // With SearchProviderRouter, a 401 from Tavily triggers fallback to DuckDuckGo.
-    // DuckDuckGo also gets the 401 mock, so all providers fail.
-    expect(result.success).toBe(false);
-    expect(result.message).toContain("Web search failed");
-  });
-
-  it("handles network error from all providers", async () => {
-    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("Network unreachable")));
-
-    const ctx = createContext({ TAVILY_API_KEY: "tvly-key" });
-    const result = await executeWebSearch({ query: "test" }, ctx);
-
-    expect(result.success).toBe(false);
-    expect(result.message).toContain("Web search failed");
-  });
-
-  it("merges ctx.env API keys into process.env for providers", async () => {
-    const mockFetch = vi
-      .fn()
-      .mockResolvedValue(new Response(JSON.stringify({ results: [] }), { status: 200 }));
-    vi.stubGlobal("fetch", mockFetch);
-
-    // ctx.env should be preferred — SearchProviderRouter reads from process.env,
-    // but executeWebSearch merges ctx.env into process.env temporarily
-    const ctx = createContext({ TAVILY_API_KEY: "ctx-key" });
-    await executeWebSearch({ query: "test" }, ctx);
-
-    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
-    expect(body.api_key).toBe("ctx-key");
-  });
-
-  it("handles context abort as cancellation", async () => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockImplementation((_url: string, options?: RequestInit) => {
-        return new Promise((_resolve, reject) => {
-          const signal = options?.signal;
-          if (signal) {
-            signal.addEventListener("abort", () => {
-              const abortError = new Error("The operation was aborted");
-              abortError.name = "AbortError";
-              reject(abortError);
-            });
-          }
-        });
-      }),
-    );
-
-    const ctx = createContext({ TAVILY_API_KEY: "tvly-key" });
-    const abortController = new AbortController();
-    const ctxWithAbort = { ...ctx, abortSignal: abortController.signal };
-
-    // Abort immediately to trigger the cancellation path
-    setTimeout(() => abortController.abort(), 10);
-    const result = await executeWebSearch({ query: "test" }, ctxWithAbort);
-
-    expect(result.success).toBe(false);
-    expect(result.message).toContain("cancelled");
-  });
-});
-
-describe("browse", () => {
-  let originalFetch: typeof global.fetch;
-
-  beforeEach(() => {
-    originalFetch = global.fetch;
-    browseCache.clear();
-    // Default DNS mock: resolve to a public IP
-    vi.mocked(dns.promises.lookup).mockResolvedValue({
-      address: "93.184.216.34",
-      family: 4,
-    });
-  });
-
-  afterEach(() => {
-    global.fetch = originalFetch;
-    vi.restoreAllMocks();
-  });
-
-  it("returns text content from a valid HTML page", async () => {
-    const html = `
-      <html>
-        <head><title>Example Page</title></head>
-        <body>
-          <h1>Hello World</h1>
-          <p>This is a test page with some content.</p>
-        </body>
-      </html>
-    `;
-
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue(
-        new Response(html, {
-          status: 200,
-          headers: { "Content-Type": "text/html" },
-        }),
-      ),
-    );
-
-    const ctx = createContext();
-    const result = await executeBrowse({ url: "https://example.com" }, ctx);
-
-    expect(result.success).toBe(true);
-    expect(result.message).toContain("Browsed");
-
-    const data = result.data as { url: string; title: string; content: string };
-    expect(data.url).toBe("https://example.com");
-    expect(data.title).toBe("Example Page");
-    expect(data.content).toContain("Hello World");
-    expect(data.content).toContain("test page");
-    // Should not contain HTML tags
-    expect(data.content).not.toContain("<h1>");
-    expect(data.content).not.toContain("<p>");
-  });
-
-  it("strips script and style blocks from HTML via Readability+Turndown", async () => {
-    const html = `
-      <html>
-        <head>
-          <title>Test</title>
-          <style>body { color: red; }</style>
-        </head>
-        <body>
-          <script>alert('xss');</script>
-          <p>Visible content only</p>
-          <script type="text/javascript">console.log('hidden');</script>
-        </body>
-      </html>
-    `;
-
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue(
-        new Response(html, {
-          status: 200,
-          headers: { "Content-Type": "text/html" },
-        }),
-      ),
-    );
-
-    const ctx = createContext();
-    const result = await executeBrowse({ url: "https://example.com" }, ctx);
-
-    expect(result.success).toBe(true);
-    const data = result.data as { content: string };
-    // Content is now wrapped with external content boundary markers
-    expect(data.content).toContain("Visible content only");
-    expect(data.content).not.toContain("alert(");
-    expect(data.content).not.toContain("console.log(");
-    expect(data.content).not.toContain("color: red");
-  });
-
-  it("returns error for invalid URL", async () => {
-    const ctx = createContext();
-    const result = await executeBrowse({ url: "not-a-valid-url" }, ctx);
-
-    expect(result.success).toBe(false);
-    expect(result.message).toContain("Invalid URL");
-  });
-
-  it("returns error for missing URL", async () => {
-    const ctx = createContext();
-    const result = await executeBrowse({ url: "" }, ctx);
-
-    expect(result.success).toBe(false);
-    expect(result.message).toContain("URL is required");
-  });
-
-  it("returns error for non-http protocols", async () => {
-    const ctx = createContext();
-    const result = await executeBrowse({ url: "ftp://files.example.com/doc" }, ctx);
-
-    expect(result.success).toBe(false);
-    expect(result.message).toContain("protocol");
-  });
-
-  it("returns error on HTTP error response", async () => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue(
-        new Response("Not Found", {
-          status: 404,
-          statusText: "Not Found",
-        }),
-      ),
-    );
-
-    const ctx = createContext();
-    const result = await executeBrowse({ url: "https://example.com/missing" }, ctx);
-
-    expect(result.success).toBe(false);
-    expect(result.message).toContain("404");
-  });
-
-  it("handles timeout", async () => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockImplementation((_url: string, options?: RequestInit) => {
-        return new Promise((_resolve, reject) => {
-          const signal = options?.signal;
-          if (signal) {
-            signal.addEventListener("abort", () => {
-              const abortError = new Error("The operation was aborted");
-              abortError.name = "AbortError";
-              reject(abortError);
-            });
-          }
-        });
-      }),
-    );
-
-    const ctx = createContext();
-    const result = await executeBrowse({ url: "https://slow.example.com", timeoutMs: 50 }, ctx);
-
-    expect(result.success).toBe(false);
-    expect(result.message).toContain("timed out");
-  });
-
-  it("handles network error", async () => {
-    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("Connection refused")));
-
-    const ctx = createContext();
-    const result = await executeBrowse({ url: "https://unreachable.example.com" }, ctx);
-
-    expect(result.success).toBe(false);
-    expect(result.message).toContain("Connection refused");
-  });
-
-  it("truncates long content to 50000 characters", async () => {
-    const longText = "A".repeat(60_000);
-    const html = `<html><head><title>Big</title></head><body><p>${longText}</p></body></html>`;
-
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue(
-        new Response(html, {
-          status: 200,
-          headers: { "Content-Type": "text/html" },
-        }),
-      ),
-    );
-
-    const ctx = createContext();
-    const result = await executeBrowse({ url: "https://example.com/long" }, ctx);
-
-    expect(result.success).toBe(true);
-    const data = result.data as { content: string };
-    // Content is now truncated at 50K + wrapped with external content boundary
-    // The boundary markers add ~100 chars, truncation notice adds ~20 chars
-    expect(data.content).toContain("[Content truncated]");
-  });
-
-  it("marks content as truncated when response exceeds byte limit", async () => {
-    const longText = "A".repeat(2 * 1024 * 1024 + 4096);
-    const html = `<html><head><title>Huge</title></head><body><p>${longText}</p></body></html>`;
-
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue(
-        new Response(html, {
-          status: 200,
-          headers: { "Content-Type": "text/html" },
-        }),
-      ),
-    );
-
-    const ctx = createContext();
-    const result = await executeBrowse({ url: "https://example.com/huge-truncated" }, ctx);
-
-    expect(result.success).toBe(true);
-    const data = result.data as { content: string };
-    expect(data.content).toContain("[Content truncated]");
-  });
-
-  it("decodes HTML entities", async () => {
-    const html = `
-      <html>
-        <head><title>Entities</title></head>
-        <body>
-          <p>Tom &amp; Jerry &lt;3 &gt; &quot;friends&quot; &#39;forever&#39;</p>
-        </body>
-      </html>
-    `;
-
-    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response(html, { status: 200 })));
-
-    const ctx = createContext();
-    const result = await executeBrowse({ url: "https://example.com/entities" }, ctx);
-
-    expect(result.success).toBe(true);
-    const data = result.data as { content: string };
-    // Depending on extraction path, content may be decoded text or raw HTML fallback.
-    expect(data.content).toMatch(/Tom\s+(?:&|&amp;)\s+Jerry/);
-    expect(data.content).toMatch(/(?:<3|&lt;3)/);
-    expect(data.content).toMatch(/(?:"friends"|&quot;friends&quot;)/);
-    expect(data.content).toMatch(/(?:'forever'|&#39;forever&#39;)/);
-  });
-
-  it("returns empty title when no <title> tag present", async () => {
-    const html = "<html><body><p>No title here</p></body></html>";
-
-    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response(html, { status: 200 })));
-
-    const ctx = createContext();
-    const result = await executeBrowse({ url: "https://example.com/notitle" }, ctx);
-
-    expect(result.success).toBe(true);
-    const data = result.data as { title: string };
-    expect(data.title).toBe("");
-  });
-
-  it("rejects URLs that resolve to private IP addresses", async () => {
-    vi.mocked(dns.promises.lookup).mockResolvedValue({
-      address: "127.0.0.1",
-      family: 4,
-    });
-
-    const ctx = createContext();
-    const result = await executeBrowse({ url: "https://internal.example.com" }, ctx);
-
-    expect(result.success).toBe(false);
-    expect(result.message).toContain("private network");
-  });
-});
-
-describe("isPrivateAddress", () => {
-  it("blocks IPv4 loopback (127.x.x.x)", () => {
-    expect(isPrivateAddress("127.0.0.1")).toBe(true);
-    expect(isPrivateAddress("127.255.255.255")).toBe(true);
-  });
-
-  it("blocks AWS metadata endpoint (169.254.169.254)", () => {
-    expect(isPrivateAddress("169.254.169.254")).toBe(true);
-    expect(isPrivateAddress("169.254.0.1")).toBe(true);
-  });
-
-  it("blocks RFC 1918 10.x.x.x", () => {
-    expect(isPrivateAddress("10.0.0.1")).toBe(true);
-    expect(isPrivateAddress("10.255.255.255")).toBe(true);
-  });
-
-  it("blocks RFC 1918 172.16-31.x.x", () => {
-    expect(isPrivateAddress("172.16.0.1")).toBe(true);
-    expect(isPrivateAddress("172.31.255.255")).toBe(true);
-    // 172.15.x and 172.32.x are NOT private
-    expect(isPrivateAddress("172.15.0.1")).toBe(false);
-    expect(isPrivateAddress("172.32.0.1")).toBe(false);
-  });
-
-  it("blocks RFC 1918 192.168.x.x", () => {
-    expect(isPrivateAddress("192.168.1.1")).toBe(true);
-    expect(isPrivateAddress("192.168.0.0")).toBe(true);
-  });
-
-  it("blocks IPv6 loopback (::1)", () => {
-    expect(isPrivateAddress("::1")).toBe(true);
-  });
-
-  it("blocks IPv6 private (fc00::/7)", () => {
-    expect(isPrivateAddress("fc00::1")).toBe(true);
-    expect(isPrivateAddress("fd12:3456:789a::1")).toBe(true);
-  });
-
-  it("blocks unspecified addresses", () => {
-    expect(isPrivateAddress("0.0.0.0")).toBe(true);
-    expect(isPrivateAddress("::")).toBe(true);
-    expect(isPrivateAddress("[::]")).toBe(true);
-  });
-
-  it("allows public IP addresses", () => {
-    expect(isPrivateAddress("8.8.8.8")).toBe(false);
-    expect(isPrivateAddress("93.184.216.34")).toBe(false);
-    expect(isPrivateAddress("1.1.1.1")).toBe(false);
-  });
-});
-
-describe("SSRF protection", () => {
-  let originalFetch: typeof global.fetch;
-
-  beforeEach(() => {
-    originalFetch = global.fetch;
-  });
-
-  afterEach(() => {
-    global.fetch = originalFetch;
-    vi.restoreAllMocks();
-  });
-
-  const privateIPs = [
-    { ip: "127.0.0.1", label: "loopback", family: 4 },
-    { ip: "169.254.169.254", label: "AWS metadata", family: 4 },
-    { ip: "10.0.0.1", label: "RFC 1918 (10.x)", family: 4 },
-    { ip: "192.168.1.1", label: "RFC 1918 (192.168.x)", family: 4 },
-    { ip: "172.16.0.1", label: "RFC 1918 (172.16.x)", family: 4 },
-    { ip: "::1", label: "IPv6 loopback", family: 6 },
-  ];
-
-  for (const { ip, label, family } of privateIPs) {
-    it(`browse rejects hostname resolving to ${label} (${ip})`, async () => {
-      vi.mocked(dns.promises.lookup).mockResolvedValue({
-        address: ip,
-        family,
-      });
-
-      const ctx = createContext();
-      const result = await executeBrowse({ url: "https://attacker.example.com" }, ctx);
-
-      expect(result.success).toBe(false);
-      expect(result.message).toContain("private network");
-      expect(result.message).toContain(ip);
-    });
-  }
-
-  it("browse allows hostname resolving to public IP", async () => {
-    vi.mocked(dns.promises.lookup).mockResolvedValue({
-      address: "8.8.8.8",
-      family: 4,
-    });
-
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue(new Response("<html><body>OK</body></html>", { status: 200 })),
-    );
-
-    const ctx = createContext();
-    const result = await executeBrowse({ url: "https://safe.example.com" }, ctx);
-
-    expect(result.success).toBe(true);
-  });
-
-  it("browse returns error when DNS resolution fails", async () => {
-    vi.mocked(dns.promises.lookup).mockRejectedValue(
-      new Error("getaddrinfo ENOTFOUND bad.example.com"),
-    );
-
-    const ctx = createContext();
-    const result = await executeBrowse({ url: "https://bad.example.com" }, ctx);
-
-    expect(result.success).toBe(false);
-    expect(result.message).toContain("DNS resolution failed");
-  });
-});

package/src/ask-user-interaction.ts

@@ -1,33 +0,0 @@
-export interface AskUserQuestion {
-  question: string;
-  options?: string[];
-}
-
-const ASK_USER_PAUSE_REQUIRED_CODE = "ASK_USER_PAUSE_REQUIRED" as const;
-
-export class AskUserPauseRequiredError extends Error {
-  readonly code = ASK_USER_PAUSE_REQUIRED_CODE;
-  readonly questions: AskUserQuestion[];
-
-  constructor(
-    questions: AskUserQuestion[],
-    message = "ask_user requires additional answers before this run can continue.",
-  ) {
-    super(message);
-    this.name = "AskUserPauseRequiredError";
-    this.questions = questions.map((question) => ({
-      question: question.question,
-      ...(Array.isArray(question.options) ? { options: [...question.options] } : {}),
-    }));
-  }
-}
-
-export function isAskUserPauseRequiredError(error: unknown): error is AskUserPauseRequiredError {
-  if (error instanceof AskUserPauseRequiredError) return true;
-  if (!error || typeof error !== "object") return false;
-  const candidate = error as { code?: unknown; name?: unknown; questions?: unknown };
-  return (
-    candidate.code === ASK_USER_PAUSE_REQUIRED_CODE ||
-    (candidate.name === "AskUserPauseRequiredError" && Array.isArray(candidate.questions))
-  );
-}