@pentoshi/clai 0.10.4 → 0.11.0

package/dist/tools/web/providers/duckduckgo.js

@@ -0,0 +1,248 @@
+/**
+ * DuckDuckGo search-provider adapter.
+ *
+ * Used as the keyless default so `clai` works out of the box without
+ * any API key (Requirement 3.5). The adapter targets DuckDuckGo's
+ * lite-HTML endpoint at `https://html.duckduckgo.com/html/?q=…`,
+ * parses the response with `cheerio`, unwraps the in-page redirect
+ * shim (`/l/?uddg=<encoded>`) so callers see the destination URL, and
+ * applies the same URL filter `web.search` enforces (Requirement 7.3)
+ * before forwarding hits to the registry handler.
+ *
+ * The adapter does not need redirect-chain capture, fine-grained
+ * timing, TLS metadata, or DNS-rebinding protection beyond the
+ * per-invocation `AbortSignal`, so it deliberately bypasses the full
+ * `fetch-core` pipeline. A small `node:https.request`-based helper
+ * keeps the implementation simple while still honoring the 15-second
+ * `web.search` invocation timeout (Requirement 1.8) via the supplied
+ * `AbortSignal`.
+ *
+ * Per Requirement 6.7 the adapter issues exactly one outbound request
+ * per invocation and never retries on transient failure.
+ */
+import { Buffer } from "node:buffer";
+import https from "node:https";
+import * as cheerio from "cheerio";
+import { searchProviders } from "./provider.js";
+/** Endpoint for DuckDuckGo's keyless lite-HTML search. */
+const ENDPOINT = "https://html.duckduckgo.com/html/";
+/** User-Agent sent on the outbound DDG request. */
+const USER_AGENT = "clai-web-search/1.0";
+let httpsRequestFn = https.request;
+/**
+ * Test-only seam: swap the HTTPS transport used by the adapter. Tests use
+ * this to inject a stubbed `request` implementation that emits scripted
+ * responses; production callers never invoke it.
+ */
+export function __setDuckduckgoHttpsRequestForTesting(fn) {
+    httpsRequestFn = fn ?? https.request;
+}
+/**
+ * Cap on the bytes read from DDG's lite-HTML response. The page is
+ * typically well under 200 KiB; the cap exists purely as a memory
+ * guard so a misbehaving server cannot stream us an unbounded body.
+ */
+const MAX_RESPONSE_BYTES = 1_048_576;
+/**
+ * Issue a single GET request over HTTPS, honoring the supplied
+ * abort signal (which `web.search` arms to a 15-second timer).
+ *
+ * Reads at most {@link MAX_RESPONSE_BYTES}, decodes as UTF-8 with
+ * replacement of invalid sequences, and resolves with `{status, body}`.
+ * Network failures and aborts surface as a rejected promise so the
+ * registry handler can map them to the appropriate
+ * `WebSearchErrorKind`.
+ *
+ * Redirect-chain capture is intentionally omitted here — DDG's lite
+ * endpoint replies 200 directly in normal operation, and any 3xx is
+ * treated as an empty result by the caller.
+ */
+function httpsGetText(url, signal) {
+    return new Promise((resolve, reject) => {
+        let req;
+        try {
+            req = httpsRequestFn(url, {
+                method: "GET",
+                signal,
+                headers: {
+                    "user-agent": USER_AGENT,
+                    accept: "text/html,application/xhtml+xml",
+                    "accept-encoding": "identity",
+                },
+            }, (res) => {
+                const status = typeof res.statusCode === "number" ? res.statusCode : 0;
+                const chunks = [];
+                let received = 0;
+                let stopped = false;
+                const stop = () => {
+                    if (stopped)
+                        return;
+                    stopped = true;
+                    try {
+                        res.destroy();
+                    }
+                    catch {
+                        // ignore — we are abandoning the socket deliberately
+                    }
+                };
+                res.on("data", (chunk) => {
+                    if (stopped)
+                        return;
+                    const remaining = MAX_RESPONSE_BYTES - received;
+                    if (remaining <= 0) {
+                        stop();
+                        return;
+                    }
+                    if (chunk.byteLength > remaining) {
+                        chunks.push(chunk.subarray(0, remaining));
+                        received += remaining;
+                        stop();
+                        return;
+                    }
+                    chunks.push(chunk);
+                    received += chunk.byteLength;
+                });
+                res.once("end", () => {
+                    const body = Buffer.concat(chunks, received).toString("utf-8");
+                    resolve({ status, body });
+                });
+                res.once("close", () => {
+                    // If the body was truncated by `stop()`, `end` does not
+                    // fire — resolve from `close` so the promise still
+                    // settles.
+                    if (stopped) {
+                        const body = Buffer.concat(chunks, received).toString("utf-8");
+                        resolve({ status, body });
+                    }
+                });
+                res.once("error", (err) => {
+                    reject(err);
+                });
+            });
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
+        req.once("error", (err) => {
+            reject(err);
+        });
+        req.end();
+    });
+}
+/**
+ * Disallowed character class for hit URLs (Requirement 7.3): any
+ * whitespace or ASCII control character. The handler in `web.search`
+ * applies the same filter, so dropping here is purely an early exit.
+ */
+const URL_INVALID_CHARS_RE = /[\s\u0000-\u001f\u007f]/;
+/**
+ * Validate a candidate hit URL against the rules `web.search` enforces:
+ * non-empty string, parseable as an absolute URL, scheme `http:` or
+ * `https:`, no whitespace, no ASCII control characters.
+ */
+function isValidHitUrl(raw) {
+    if (typeof raw !== "string" || raw.length === 0)
+        return false;
+    if (URL_INVALID_CHARS_RE.test(raw))
+        return false;
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+}
+/**
+ * Strip DuckDuckGo's in-page redirect wrapper so the destination URL
+ * is what callers see.
+ *
+ * DDG renders result links as `/l/?uddg=<percent-encoded destination>`
+ * (sometimes with extra tracking parameters). For non-wrapper links —
+ * e.g. ad placements that point directly at an external URL — the
+ * input is returned as an absolute URL unchanged.
+ *
+ * Returns `undefined` when the input is empty, fails URL parsing, or
+ * is a `/l/` wrapper without a usable `uddg` parameter.
+ */
+function unwrapDdgRedirect(href) {
+    if (typeof href !== "string" || href.length === 0)
+        return undefined;
+    let parsed;
+    try {
+        // Resolve protocol-relative (`//duckduckgo.com/l/…`) and absolute
+        // path (`/l/…`) forms against the DDG endpoint so URL parsing
+        // succeeds for every shape DDG emits.
+        parsed = new URL(href, ENDPOINT);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.pathname === "/l/" && parsed.searchParams.has("uddg")) {
+        const destination = parsed.searchParams.get("uddg") ?? "";
+        if (destination.length === 0)
+            return undefined;
+        return destination;
+    }
+    return parsed.toString();
+}
+/**
+ * The DuckDuckGo {@link SearchProvider} adapter.
+ *
+ * Resolves a search query into a {@link RawProviderResponse} carrying
+ * up to `maxResults` `{title, url, snippet}` hits. URL filtering and
+ * `maxResults` truncation happen here so the registry handler does not
+ * have to re-walk the cheerio tree; the handler still re-applies the
+ * filter for defense in depth (Requirement 7.3).
+ */
+export const duckduckgoProvider = {
+    id: "duckduckgo",
+    displayName: "DuckDuckGo",
+    needsApiKey: false,
+    async search(query, maxResults, _auth, signal) {
+        const url = `${ENDPOINT}?q=${encodeURIComponent(query)}`;
+        const { status, body } = await httpsGetText(url, signal);
+        // Non-2xx responses surface to the handler with an empty hit
+        // list; the handler maps the status to the right
+        // `WebSearchErrorKind` (auth/rate-limit/server/http) per
+        // Requirements 6.1, 6.2, 6.6, and 1.9.
+        if (status < 200 || status >= 300) {
+            return { status, hits: [] };
+        }
+        let $;
+        try {
+            $ = cheerio.load(body);
+        }
+        catch (err) {
+            return {
+                status,
+                hits: [],
+                parseError: err instanceof Error ? err.message : String(err),
+            };
+        }
+        const hits = [];
+        $(".result").each((_idx, el) => {
+            if (hits.length >= maxResults)
+                return false;
+            const titleAnchor = $(el).find(".result__title a").first();
+            const titleText = titleAnchor.text().trim();
+            const href = titleAnchor.attr("href") ?? "";
+            const destination = unwrapDdgRedirect(href);
+            // Drop hits whose URL is missing/invalid before they count
+            // toward `maxResults` (Requirement 7.3).
+            if (destination === undefined || !isValidHitUrl(destination))
+                return;
+            const snippet = $(el).find(".result__snippet").first().text().trim();
+            hits.push({ title: titleText, url: destination, snippet });
+            return;
+        });
+        return { status, hits };
+    },
+};
+// Register the adapter in the shared registry so the `web.search`
+// handler can dispatch through it once `activeSearchProvider` is set
+// to `"duckduckgo"`.
+searchProviders.duckduckgo = duckduckgoProvider;
+//# sourceMappingURL=duckduckgo.js.map

package/dist/tools/web/providers/duckduckgo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duckduckgo.js","sourceRoot":"","sources":["../../../../src/tools/web/providers/duckduckgo.ts"],"names":[],"mappings":"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"}

package/dist/tools/web/providers/provider.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Search-provider adapter interface and registry stub.
+ *
+ * Concrete provider implementations (Brave, Tavily, DuckDuckGo) live next to
+ * this file and register themselves into {@link searchProviders}. The registry
+ * starts empty; it is populated by the per-provider modules so a missing
+ * import surfaces immediately as a `Cannot read property 'search'` style error
+ * rather than as a silently wrong dispatch.
+ *
+ * Shapes here match the design document's "Provider adapter interface"
+ * section verbatim.
+ */
+import { type SearchProviderId } from "../types.js";
+/**
+ * Adapter implemented by every search-provider module.
+ *
+ * The `search` method is called by `web.search` after argument validation and
+ * provider/key resolution. Implementations must:
+ *
+ * - Issue exactly one outbound HTTP request (no retry on transient failure;
+ *   Requirement 6.7).
+ * - Honor the provided {@link AbortSignal} for the 15-second invocation
+ *   timeout (Requirement 1.8).
+ * - Return a {@link RawProviderResponse} describing the HTTP outcome and the
+ *   raw, unfiltered hit list. Shape validation, URL filtering, and
+ *   `maxResults` truncation are performed by the `web.search` handler, not by
+ *   the adapter.
+ */
+export interface SearchProvider {
+    /** Stable identifier matching one of {@link SearchProviderId}. */
+    id: SearchProviderId;
+    /** Human-friendly name shown in CLI listings. */
+    displayName: string;
+    /** Whether the adapter requires an API key to dispatch a request. */
+    needsApiKey: boolean;
+    /**
+     * Environment variable the key store consults first when resolving this
+     * provider's API key (e.g. `"BRAVE_SEARCH_API_KEY"`). Omitted for keyless
+     * providers.
+     */
+    envVar?: string;
+    /**
+     * Dispatch a single search request.
+     *
+     * @param query      Already-trimmed query string; length ∈ [1, 400].
+     * @param maxResults Already-clamped result count; ∈ [1, 20].
+     * @param auth       Resolved credentials. `apiKey` is present iff
+     *                   {@link needsApiKey} is true and a key was found.
+     * @param signal     Abort signal wired to the 15-second invocation timer.
+     */
+    search(query: string, maxResults: number, auth: {
+        apiKey?: string;
+    }, signal: AbortSignal): Promise<RawProviderResponse>;
+}
+/**
+ * Provider-agnostic view of a single dispatch's outcome.
+ *
+ * Adapters surface raw HTTP status + hit array here so the `web.search`
+ * handler can map status codes to {@link import("../types.js").WebSearchErrorKind}
+ * uniformly across providers (Requirements 6.1, 6.2, 6.5, 6.6, 1.9).
+ */
+export interface RawProviderResponse {
+    /** HTTP status code returned by the provider's endpoint. */
+    status: number;
+    /**
+     * Hit list extracted from the provider response. Fields are optional
+     * because validation/filtering happens in the handler — the adapter is
+     * permitted to forward whatever the provider produced.
+     */
+    hits: Array<{
+        title?: string;
+        url?: string;
+        snippet?: string;
+    }>;
+    /**
+     * Populated when the provider returned a 2xx status but the body did not
+     * match the adapter's expected shape; surfaces as
+     * {@link import("../types.js").WebSearchErrorKind} `"parse"` (Requirement 6.5).
+     */
+    parseError?: string;
+}
+/**
+ * Registry of installed search-provider adapters, keyed by
+ * {@link SearchProviderId}.
+ *
+ * Starts empty. Concrete adapters in `./brave.ts`, `./tavily.ts`, and
+ * `./duckduckgo.ts` populate this object on module import; the
+ * `web.search` handler resolves the active provider through it.
+ */
+export declare const searchProviders: Record<SearchProviderId, SearchProvider>;
+/**
+ * Validate that an arbitrary string is one of the supported
+ * {@link SearchProviderId} values, returning the narrowed type.
+ *
+ * Mirrors `assertProvider` in `src/llm/provider.ts` so CLI surfaces such as
+ * `clai set <provider>` and `clai search-provider <id>` get the same error
+ * shape regardless of which keyspace the id belongs to (Requirement 3.7).
+ */
+export declare function assertSearchProvider(value: string): SearchProviderId;

package/dist/tools/web/providers/provider.js

@@ -0,0 +1,38 @@
+/**
+ * Search-provider adapter interface and registry stub.
+ *
+ * Concrete provider implementations (Brave, Tavily, DuckDuckGo) live next to
+ * this file and register themselves into {@link searchProviders}. The registry
+ * starts empty; it is populated by the per-provider modules so a missing
+ * import surfaces immediately as a `Cannot read property 'search'` style error
+ * rather than as a silently wrong dispatch.
+ *
+ * Shapes here match the design document's "Provider adapter interface"
+ * section verbatim.
+ */
+import { searchProviderIds, } from "../types.js";
+/**
+ * Registry of installed search-provider adapters, keyed by
+ * {@link SearchProviderId}.
+ *
+ * Starts empty. Concrete adapters in `./brave.ts`, `./tavily.ts`, and
+ * `./duckduckgo.ts` populate this object on module import; the
+ * `web.search` handler resolves the active provider through it.
+ */
+export const searchProviders = {};
+/**
+ * Validate that an arbitrary string is one of the supported
+ * {@link SearchProviderId} values, returning the narrowed type.
+ *
+ * Mirrors `assertProvider` in `src/llm/provider.ts` so CLI surfaces such as
+ * `clai set <provider>` and `clai search-provider <id>` get the same error
+ * shape regardless of which keyspace the id belongs to (Requirement 3.7).
+ */
+export function assertSearchProvider(value) {
+    const normalized = value.trim().toLowerCase();
+    if (searchProviderIds.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Unsupported search provider "${value}". Supported providers: ${searchProviderIds.join(", ")}`);
+}
+//# sourceMappingURL=provider.js.map

package/dist/tools/web/providers/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../../../src/tools/web/providers/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,iBAAiB,GAElB,MAAM,aAAa,CAAC;AAuErB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,EAA8C,CAAC;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAK,iBAAuC,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAClE,OAAO,UAA8B,CAAC;IACxC,CAAC;IACD,MAAM,IAAI,KAAK,CACb,gCAAgC,KAAK,2BAA2B,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC/F,CAAC;AACJ,CAAC"}

package/dist/tools/web/providers/tavily.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Tavily search-provider adapter for `web.search`.
+ *
+ * Implements the {@link SearchProvider} contract from `./provider.ts` and
+ * registers itself in the {@link searchProviders} registry on import. The
+ * adapter performs exactly one outbound HTTPS request per invocation
+ * (Requirement 6.7), forwards the caller-provided {@link AbortSignal} to
+ * the underlying transport so the 15-second `web.search` timeout is
+ * honored (Requirement 1.8), and returns a {@link RawProviderResponse}
+ * describing the HTTP outcome plus the raw hit list.
+ *
+ * Status-to-error-kind classification (`401/403 → auth`, `429 → rate-limit`,
+ * `5xx → server`, non-JSON → `parse`, other non-2xx → `http`) is the
+ * responsibility of the `web.search` handler; this adapter only exposes
+ * the raw HTTP `status` and the parsed (or `parseError`-flagged) hit list
+ * so that mapping can be applied uniformly across providers (Requirements
+ * 6.1, 6.2, 6.5, 6.6).
+ *
+ * Endpoint and request shape match the design's "Per-provider notes →
+ * Tavily" section (`.kiro/specs/web-search-and-fetch/design.md`):
+ *
+ *   - POST `https://api.tavily.com/search`
+ *   - Body: `{ api_key, query, max_results, search_depth: "basic" }`
+ *     where `max_results` is clamped to `[1..20]` defensively.
+ *   - Response: `{ results: [{ title, url, content }] }` mapped into
+ *     `SearchResult { title, url, snippet }`.
+ */
+import https from "node:https";
+import { type SearchProvider } from "./provider.js";
+/**
+ * Inject point for the underlying HTTPS transport so unit/property
+ * tests can drive the adapter without touching the network. The
+ * default mirrors the standard `node:https.request` signature.
+ *
+ * Kept module-private (not exported as a normal export) because the
+ * public adapter contract intentionally takes no transport argument —
+ * `web.search` always uses the default transport in production.
+ */
+type HttpsRequestFn = typeof https.request;
+/**
+ * Test-only seam: swap the HTTPS transport used by the adapter.
+ * Production callers never invoke this; tests use it to inject a
+ * stubbed `request` implementation that emits scripted responses.
+ */
+export declare function __setTavilyHttpsRequestForTesting(fn: HttpsRequestFn | undefined): void;
+/**
+ * Tavily adapter. Registered in {@link searchProviders} as a
+ * side-effect of importing this module — `web.search` resolves the
+ * active provider via the registry.
+ */
+export declare const tavilyProvider: SearchProvider;
+export {};