@phuetz/code-buddy 1.6.1 → 2.0.0

package/dist/tools/web-search.d.ts

@@ -1,5 +1,17 @@
+import { type AxiosRequestConfig } from 'axios';
 import { ToolResult } from '../types/index.js';
-export type SearchProvider = 'brave' | 'perplexity' | 'serper' | 'duckduckgo' | 'brave-mcp';
+export type SearchProvider = 'brave' | 'perplexity' | 'serper' | 'duckduckgo' | 'brave-mcp' | 'searxng';
+/**
+ * Injectable HTTP GET boundary. Defaults to `axios.get`; the SearXNG provider
+ * routes through this so tests can supply a fake without any real network.
+ */
+export type WebSearchHttpGet = (url: string, config?: AxiosRequestConfig) => Promise<{
+    data: unknown;
+}>;
+export interface WebSearchToolDeps {
+    /** Override the HTTP GET boundary (used by the SearXNG provider). */
+    httpGet?: WebSearchHttpGet;
+}
 /**
  * Web search mode (Codex-inspired prompt injection mitigation).
  * - 'disabled' — no web search allowed
@@ -52,6 +64,13 @@ export interface SearchResult {
     /** Age/published info (Brave only) */
     published?: string;
 }
+/** One provider attempt from `searchStructured` (journal / Deep Research). */
+export interface StructuredSearchAttempt {
+    provider: SearchProvider;
+    hitsIn: number;
+    usableUrls: number;
+    error?: string;
+}
 export interface PerplexitySearchResult {
     content: string;
     citations: string[];
@@ -64,7 +83,12 @@ declare function resolvePerplexityBaseUrl(apiKey?: string): string;
  * Web Search Tool — Enterprise-aligned provider chain
  *
  * Provider resolution (auto mode):
- *   Brave MCP → Brave API → Perplexity → Serper → DuckDuckGo
+ *   SearXNG (when SEARXNG_URL set) → Brave MCP → Brave API → Perplexity → Serper → DuckDuckGo
+ *
+ * SearXNG, when configured, is PREFERRED (first in the chain): it needs no API
+ * key and is privacy-respecting, matching Code Buddy's local-first stance. When
+ * `SEARXNG_URL` is unset it is never tried and the chain is byte-identical to
+ * the historical Brave→Perplexity→Serper→DuckDuckGo order.
  *
  * Supports country, search_lang, ui_lang, freshness (Brave), Perplexity AI search.
  */
@@ -75,9 +99,14 @@ export declare class WebSearchTool {
     private serperApiKey;
     private braveApiKey;
     private perplexityApiKey;
-    constructor();
+    private searxngUrl;
+    private readonly httpGet;
+    constructor(deps?: WebSearchToolDeps);
     private failedQueries;
     private static readonly FAILED_QUERY_TTL;
+    private lastStructuredAttempts;
+    /** Last `searchStructured` provider attempts (empty until the first call). */
+    getLastStructuredAttempts(): StructuredSearchAttempt[];
     search(query: string, options?: WebSearchOptions): Promise<ToolResult>;
     /**
      * Perplexity AI search — returns synthesized answer with citations
@@ -85,7 +114,42 @@ export declare class WebSearchTool {
     searchPerplexity(query: string, options?: WebSearchOptions): Promise<ToolResult>;
     private buildProviderChain;
     private searchWithProvider;
+    /**
+     * Resolve a single provider into structured `SearchResult[]` (no formatting,
+     * no caching). Shared by `searchWithProvider` (which formats+caches) and
+     * `searchStructured` (which returns the raw hits). Extracted verbatim from the
+     * original `searchWithProvider` switch — behaviour is unchanged.
+     */
+    private resolveProviderResults;
+    /**
+     * Structured search — same mode gate and provider fallback chain as `search()`,
+     * but returns raw `SearchResult[]` (title/url/snippet) instead of a formatted
+     * string. Used by deterministic pipelines (Deep Research) that need the top-K
+     * URLs. Additive: `search()` is untouched. Returns [] on disabled mode or when
+     * every provider fails (never throws).
+     */
+    searchStructured(query: string, options?: WebSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Like {@link searchStructured} but returns THIS call's provider attempts.
+     * Parallel Deep Research queries must not share a mutable attempts array —
+     * mixing them produced a 17 KB CAPTCHA dump on a 0-source failure.
+     */
+    searchStructuredTraced(query: string, options?: WebSearchOptions): Promise<{
+        results: SearchResult[];
+        attempts: StructuredSearchAttempt[];
+    }>;
     private buildCacheKey;
+    /**
+     * Query a SearXNG instance's JSON search endpoint
+     * (`GET {SEARXNG_URL}/search?q=…&format=json`) and map `results[]`
+     * (`title`/`url`/`content`) to `SearchResult[]`.
+     *
+     * Never swallows transport errors: a timeout / unreachable instance / non-2xx
+     * throws so the caller's fallback chain moves to the next provider. Invalid
+     * JSON or an empty payload yields `[]` (→ "No results" → next provider). The
+     * `httpGet` boundary is injectable so tests run without real network.
+     */
+    private searchSearXNG;
     private isBraveMCPAvailable;
     private searchViaBraveMCP;
     private searchBraveAPI;
@@ -94,9 +158,6 @@ export declare class WebSearchTool {
     private searchDuckDuckGo;
     fetchPage(url: string, _prompt?: string): Promise<ToolResult>;
     private formatPerplexityResult;
-    private isWeatherQuery;
-    private getWeatherEmoji;
-    private formatWeatherResults;
     private formatResults;
     private extractTextFromHtml;
     private stripHtml;

package/dist/tools/web-search.js

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { getErrorMessage } from '../types/index.js';
 import { logger } from '../utils/logger.js';
 import { assertSafeUrl } from '../security/ssrf-guard.js';
+import { safeFetchFollow } from '../security/safe-fetch.js';
 // Global search mode and domain policy (configurable via TOML / runtime)
 let _globalSearchMode = 'live';
 let _domainPolicy = {};
@@ -82,11 +83,49 @@ function resolvePerplexityBaseUrl(apiKey) {
         return PERPLEXITY_DIRECT_BASE_URL;
     return DEFAULT_PERPLEXITY_BASE_URL; // OpenRouter key or unknown
 }
+/**
+ * Validate + normalize the `SEARXNG_URL` env value.
+ *
+ * SearXNG is an operator-configured, trusted endpoint (like `OLLAMA_HOST` /
+ * `VLLM_BASE_URL`), and its canonical deployment is loopback
+ * (`http://localhost:8888`) — so we deliberately do NOT run it through the
+ * SSRF guard (which fails closed on loopback/private IPs). Instead we require a
+ * well-formed http(s) URL; anything else disables the provider (never throws).
+ *
+ * @returns the trimmed URL (no trailing slash) if valid, else `undefined`.
+ */
+function normalizeSearxngUrl(raw) {
+    if (!raw)
+        return undefined;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        logger.warn('SEARXNG_URL is not a valid URL — SearXNG search provider disabled', { value: trimmed });
+        return undefined;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        logger.warn('SEARXNG_URL must be an http(s) URL — SearXNG search provider disabled', {
+            protocol: parsed.protocol,
+        });
+        return undefined;
+    }
+    return trimmed.replace(/\/+$/, '');
+}
 /**
  * Web Search Tool — Enterprise-aligned provider chain
  *
  * Provider resolution (auto mode):
- *   Brave MCP → Brave API → Perplexity → Serper → DuckDuckGo
+ *   SearXNG (when SEARXNG_URL set) → Brave MCP → Brave API → Perplexity → Serper → DuckDuckGo
+ *
+ * SearXNG, when configured, is PREFERRED (first in the chain): it needs no API
+ * key and is privacy-respecting, matching Code Buddy's local-first stance. When
+ * `SEARXNG_URL` is unset it is never tried and the chain is byte-identical to
+ * the historical Brave→Perplexity→Serper→DuckDuckGo order.
  *
  * Supports country, search_lang, ui_lang, freshness (Brave), Perplexity AI search.
  */
@@ -98,11 +137,18 @@ export class WebSearchTool {
     serperApiKey;
     braveApiKey;
     perplexityApiKey;
-    constructor() {
+    searxngUrl;
+    // Injectable HTTP GET boundary (SearXNG only) — defaults to axios.get
+    httpGet;
+    constructor(deps = {}) {
+        this.httpGet = deps.httpGet ?? ((url, config) => axios.get(url, config));
         this.serperApiKey = process.env.SERPER_API_KEY;
         this.braveApiKey = process.env.BRAVE_API_KEY;
         this.perplexityApiKey = process.env.PERPLEXITY_API_KEY || process.env.OPENROUTER_API_KEY;
+        this.searxngUrl = normalizeSearxngUrl(process.env.SEARXNG_URL);
         const providers = [];
+        if (this.searxngUrl)
+            providers.push('searxng');
         if (this.braveApiKey)
             providers.push('brave');
         if (this.perplexityApiKey)
@@ -118,6 +164,11 @@ export class WebSearchTool {
     // Cache failed queries to avoid repeated timeouts (TTL: 2 minutes)
     failedQueries = new Map();
     static FAILED_QUERY_TTL = 120000;
+    lastStructuredAttempts = [];
+    /** Last `searchStructured` provider attempts (empty until the first call). */
+    getLastStructuredAttempts() {
+        return this.lastStructuredAttempts.slice();
+    }
     async search(query, options = {}) {
         // Mode check (Codex-inspired prompt injection mitigation)
         const effectiveMode = options.mode ?? _globalSearchMode;
@@ -209,6 +260,11 @@ export class WebSearchTool {
     // ============================================================================
     buildProviderChain() {
         const chain = [];
+        // SearXNG is PREFERRED when configured: no API key, privacy-respecting
+        // meta-search (local-first). When SEARXNG_URL is unset this branch is
+        // skipped and the chain is byte-identical to the historical order.
+        if (this.searxngUrl)
+            chain.push('searxng');
         // Brave MCP is checked dynamically
         chain.push('brave-mcp');
         if (this.braveApiKey)
@@ -221,8 +277,25 @@ export class WebSearchTool {
         return chain;
     }
     async searchWithProvider(provider, query, count, options, cacheKey) {
+        const results = await this.resolveProviderResults(provider, query, count, options);
+        if (results.length === 0) {
+            return { success: true, output: `No results found for: "${query}"` };
+        }
+        this.cache.set(cacheKey, { results, timestamp: Date.now() });
+        return { success: true, output: this.formatResults(results, query) };
+    }
+    /**
+     * Resolve a single provider into structured `SearchResult[]` (no formatting,
+     * no caching). Shared by `searchWithProvider` (which formats+caches) and
+     * `searchStructured` (which returns the raw hits). Extracted verbatim from the
+     * original `searchWithProvider` switch — behaviour is unchanged.
+     */
+    async resolveProviderResults(provider, query, count, options) {
         let results;
         switch (provider) {
+            case 'searxng':
+                results = await this.searchSearXNG(query, count, options);
+                break;
             case 'brave-mcp':
                 if (!(await this.isBraveMCPAvailable())) {
                     throw new Error('Brave MCP not connected');
@@ -255,11 +328,79 @@ export class WebSearchTool {
             default:
                 throw new Error(`Unknown provider: ${provider}`);
         }
-        if (results.length === 0) {
-            return { success: true, output: `No results found for: "${query}"` };
+        return results;
+    }
+    /**
+     * Structured search — same mode gate and provider fallback chain as `search()`,
+     * but returns raw `SearchResult[]` (title/url/snippet) instead of a formatted
+     * string. Used by deterministic pipelines (Deep Research) that need the top-K
+     * URLs. Additive: `search()` is untouched. Returns [] on disabled mode or when
+     * every provider fails (never throws).
+     */
+    async searchStructured(query, options = {}) {
+        const { results } = await this.searchStructuredTraced(query, options);
+        return results;
+    }
+    /**
+     * Like {@link searchStructured} but returns THIS call's provider attempts.
+     * Parallel Deep Research queries must not share a mutable attempts array —
+     * mixing them produced a 17 KB CAPTCHA dump on a 0-source failure.
+     */
+    async searchStructuredTraced(query, options = {}) {
+        const attempts = [];
+        const effectiveMode = options.mode ?? _globalSearchMode;
+        if (effectiveMode === 'disabled') {
+            this.lastStructuredAttempts = attempts;
+            return { results: [], attempts };
         }
-        this.cache.set(cacheKey, { results, timestamp: Date.now() });
-        return { success: true, output: this.formatResults(results, query) };
+        let effectiveOptions = options;
+        if (effectiveMode === 'cached' && !options.provider) {
+            effectiveOptions = {
+                ...options,
+                provider: this.braveApiKey ? 'brave' : this.perplexityApiKey ? 'perplexity' : 'duckduckgo',
+            };
+        }
+        const count = Math.max(1, Math.min(MAX_SEARCH_COUNT, effectiveOptions.maxResults ?? DEFAULT_SEARCH_COUNT));
+        const chain = effectiveOptions.provider ? [effectiveOptions.provider] : this.buildProviderChain();
+        for (const provider of chain) {
+            try {
+                const results = await this.resolveProviderResults(provider, query, count, effectiveOptions);
+                const filtered = results.filter((r) => typeof r.url === 'string' && r.url.trim().length > 0 && isDomainAllowed(r.url));
+                attempts.push({
+                    provider,
+                    hitsIn: results.length,
+                    usableUrls: filtered.length,
+                });
+                logger.info('[web-search] structured provider', {
+                    provider,
+                    hitsIn: results.length,
+                    usableUrls: filtered.length,
+                });
+                if (filtered.length > 0) {
+                    this.lastStructuredAttempts = attempts.slice();
+                    return { results: filtered, attempts };
+                }
+                logger.debug(`Structured search provider ${provider} returned no usable URLs, trying next`, {
+                    raw: results.length,
+                });
+            }
+            catch (error) {
+                const message = getErrorMessage(error);
+                attempts.push({
+                    provider,
+                    hitsIn: 0,
+                    usableUrls: 0,
+                    error: message,
+                });
+                logger.debug(`Structured search provider ${provider} failed, trying next`, { error: message });
+            }
+        }
+        logger.warn('[web-search] structured search empty', {
+            query,
+            attempts,
+        });
+        this.lastStructuredAttempts = attempts.slice();
+        return { results: [], attempts };
     }
     buildCacheKey(query, count, options) {
         const parts = [
@@ -273,6 +414,66 @@ export class WebSearchTool {
         return parts.join(':');
     }
     // ============================================================================
+    // SearXNG (self-hosted meta-search, no API key)
+    // ============================================================================
+    /**
+     * Query a SearXNG instance's JSON search endpoint
+     * (`GET {SEARXNG_URL}/search?q=…&format=json`) and map `results[]`
+     * (`title`/`url`/`content`) to `SearchResult[]`.
+     *
+     * Never swallows transport errors: a timeout / unreachable instance / non-2xx
+     * throws so the caller's fallback chain moves to the next provider. Invalid
+     * JSON or an empty payload yields `[]` (→ "No results" → next provider). The
+     * `httpGet` boundary is injectable so tests run without real network.
+     */
+    async searchSearXNG(query, count, options) {
+        if (!this.searxngUrl) {
+            // Only reachable if `searxng` is force-selected while unconfigured — the
+            // auto chain never adds it in that case. Throwing routes to the next
+            // provider (or surfaces a clear error) instead of a `!`-deref crash.
+            throw new Error('SearXNG provider is not configured (SEARXNG_URL unset)');
+        }
+        const url = new URL(`${this.searxngUrl}/search`);
+        url.searchParams.set('q', query);
+        url.searchParams.set('format', 'json');
+        url.searchParams.set('categories', 'general');
+        url.searchParams.set('pageno', '1');
+        url.searchParams.set('safesearch', options.safeSearch ? '1' : '0');
+        if (options.search_lang)
+            url.searchParams.set('language', options.search_lang);
+        const response = await this.httpGet(url.toString(), {
+            headers: {
+                'Accept': 'application/json',
+                'User-Agent': 'CodeBuddyCLI/1.0 (+https://github.com/code-buddy)',
+            },
+            timeout: DEFAULT_TIMEOUT_MS,
+        });
+        const payload = (response?.data ?? {});
+        const rawResults = Array.isArray(payload.results) ? payload.results : [];
+        const results = [];
+        for (const entry of rawResults) {
+            const entryUrl = entry && typeof entry.url === 'string' ? entry.url : '';
+            if (!entryUrl)
+                continue;
+            const title = typeof entry.title === 'string' && entry.title.trim() ? entry.title.trim() : entryUrl;
+            const snippet = typeof entry.content === 'string' ? entry.content.trim() : '';
+            const published = typeof entry.publishedDate === 'string' && entry.publishedDate.trim()
+                ? entry.publishedDate.trim()
+                : undefined;
+            results.push({
+                title,
+                url: entryUrl,
+                snippet,
+                siteName: resolveSiteName(entryUrl),
+                published,
+            });
+            if (results.length >= count)
+                break;
+        }
+        logger.debug('SearXNG search completed', { query, resultCount: results.length });
+        return results;
+    }
+    // ============================================================================
     // Brave MCP
     // ============================================================================
     async isBraveMCPAvailable() {
@@ -509,15 +710,25 @@ export class WebSearchTool {
                     error: `URL blocked by SSRF guard: ${ssrfCheck.reason}`,
                 };
             }
-            const response = await axios.get(url, {
-                headers: {
-                    'User-Agent': 'Mozilla/5.0 (compatible; CodeBuddyCLI/1.0; +https://github.com/code-buddy)',
-                    'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
-                },
-                timeout: DEFAULT_TIMEOUT_MS,
-                maxRedirects: 5,
-            });
-            const html = response.data;
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+            let response;
+            try {
+                response = await safeFetchFollow(url, {
+                    signal: controller.signal,
+                    headers: {
+                        'User-Agent': 'Mozilla/5.0 (compatible; CodeBuddyCLI/1.0; +https://github.com/code-buddy)',
+                        'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+                    },
+                });
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+            if (!response.ok) {
+                throw new Error(`Page request failed with HTTP ${response.status}`);
+            }
+            const html = await response.text();
             const text = this.extractTextFromHtml(html);
             const maxLength = 8000;
             const truncatedText = text.length > maxLength
@@ -553,62 +764,14 @@ export class WebSearchTool {
         lines.push('-'.repeat(50));
         return lines.join('\n');
     }
-    isWeatherQuery(query) {
-        const weatherKeywords = ['météo', 'meteo', 'weather', 'température', 'temperature', 'forecast', 'prévisions'];
-        const q = query.toLowerCase();
-        return weatherKeywords.some(kw => q.includes(kw));
-    }
-    getWeatherEmoji(text) {
-        const t = text.toLowerCase();
-        if (t.includes('soleil') || t.includes('sunny') || t.includes('ensoleillé'))
-            return '☀️';
-        if (t.includes('pluie') || t.includes('rain') || t.includes('averse'))
-            return '🌧️';
-        if (t.includes('nuage') || t.includes('cloud') || t.includes('couvert'))
-            return '☁️';
-        if (t.includes('neige') || t.includes('snow'))
-            return '❄️';
-        if (t.includes('orage') || t.includes('thunder') || t.includes('storm'))
-            return '⛈️';
-        if (t.includes('brouillard') || t.includes('fog'))
-            return '🌫️';
-        if (t.includes('vent') || t.includes('wind'))
-            return '💨';
-        if (t.includes('éclaircies') || t.includes('partly'))
-            return '⛅';
-        return '🌡️';
-    }
-    formatWeatherResults(results, query) {
-        const lines = [];
-        const location = query.replace(/météo|meteo|weather/gi, '').trim();
-        lines.push(`\n🌍 Météo ${location || 'actuelle'}`);
-        lines.push('═'.repeat(40));
-        lines.push('');
-        for (const result of results.slice(0, 4)) {
-            const emoji = this.getWeatherEmoji(result.snippet);
-            if (!result.url && result.snippet) {
-                lines.push(`${emoji} ${result.title}: ${result.snippet}`);
-                lines.push('');
-            }
-            else if (result.url) {
-                lines.push(`${emoji} **${result.title}**`);
-                if (result.snippet) {
-                    const cleanSnippet = result.snippet.replace(/·/g, '|').replace(/\s+/g, ' ').trim();
-                    lines.push(`   ${cleanSnippet}`);
-                }
-                lines.push(`   🔗 ${result.url}`);
-                lines.push('');
-            }
-        }
-        lines.push('─'.repeat(40));
-        return lines.join('\n');
-    }
+    // NOTE: the old hardcoded weather presentation (isWeatherQuery/
+    // getWeatherEmoji/formatWeatherResults — a French card faked from generic
+    // search results, with no weather data behind it) was removed 2026-07-03.
+    // Weather questions are served by the dedicated `weather` tool (real
+    // Open-Meteo data); weather-ish searches now get normal result formatting.
     formatResults(results, query) {
         // Apply domain policy filter (Codex-inspired allowlist/denylist)
         const filtered = results.filter(r => !r.url || isDomainAllowed(r.url));
-        if (this.isWeatherQuery(query)) {
-            return this.formatWeatherResults(filtered, query);
-        }
         results = filtered;
         const lines = [];
         lines.push(`\n🔍 Résultats pour: "${query}"`);

package/dist/tools/workspace-tools.d.ts

@@ -0,0 +1,39 @@
+import type { ToolResult } from '../types/index.js';
+import { type Workspace, type WorkspaceConfigOptions, type WorkspaceRepo } from '../workspace/workspace-config.js';
+import { type SearchResult } from './search.js';
+import type { ITool, IToolExecutionContext, IToolMetadata, IValidationResult, ToolSchema } from './registry/types.js';
+interface WorkspaceSearchOptions {
+    maxResults: number;
+    glob?: string;
+    timeoutMs: number;
+    signal: AbortSignal;
+}
+export interface WorkspaceToolDependencies {
+    workspaceProvider?: (options?: WorkspaceConfigOptions) => Workspace | null;
+    searchRepo?: (repo: WorkspaceRepo, query: string, options: WorkspaceSearchOptions) => Promise<SearchResult[]>;
+}
+export declare class WorkspaceSearchTool implements ITool {
+    readonly name = "workspace_search";
+    readonly description = "Search text across the opt-in multi-repository workspace with bounded, repository-prefixed results.";
+    private readonly workspaceProvider;
+    private readonly searchRepo;
+    constructor(dependencies?: WorkspaceToolDependencies);
+    execute(input: Record<string, unknown>, context?: IToolExecutionContext): Promise<ToolResult>;
+    getSchema(): ToolSchema;
+    validate(input: unknown): IValidationResult;
+    getMetadata(): IToolMetadata;
+    isAvailable(): boolean;
+}
+export declare class WorkspaceReadTool implements ITool {
+    readonly name = "workspace_read";
+    readonly description = "Read a bounded file from a named repository in the opt-in multi-repository workspace.";
+    private readonly workspaceProvider;
+    constructor(dependencies?: Pick<WorkspaceToolDependencies, 'workspaceProvider'>);
+    execute(input: Record<string, unknown>, context?: IToolExecutionContext): Promise<ToolResult>;
+    getSchema(): ToolSchema;
+    validate(input: unknown): IValidationResult;
+    getMetadata(): IToolMetadata;
+    isAvailable(): boolean;
+}
+export declare function createWorkspaceTools(): ITool[];
+export {};