@qvac/harness 0.0.0 → 0.1.1

package/dist-lib/lib/web-search/engines/duckduckgo.js

@@ -0,0 +1,112 @@
+import { fetchHtml } from "../fetch-html.js";
+import { clean } from "../html-helpers.js";
+import { urlMatchesHost } from "../url-helpers.js";
+function extractDdgUrl(raw) {
+    if (raw.includes('uddg=')) {
+        const m = raw.match(/uddg=([^&]+)/);
+        if (m?.[1]) {
+            return decodeURIComponent(m[1]);
+        }
+    }
+    return raw;
+}
+function isOrganicUrl(url) {
+    return url.startsWith('http') && !urlMatchesHost(url, 'duckduckgo.com');
+}
+function parseLinksMain(html) {
+    const results = [];
+    const pat = /<div[^>]*class="[^"]*links_main[^"]*"[^>]*>[\s\S]*?<a[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>[\s\S]*?<a[^>]*class="[^"]*result__snippet[^"]*"[^>]*>([\s\S]*?)<\/a>/gi;
+    for (const m of html.matchAll(pat)) {
+        const url = extractDdgUrl(m[1] || '');
+        const title = clean(m[2] || '');
+        const content = clean(m[3] || '');
+        if (url && title && isOrganicUrl(url)) {
+            results.push({ title, url, content: content || title, position: results.length + 1 });
+        }
+    }
+    return results;
+}
+function extractLinks(html) {
+    const linkPat = /<a[^>]*class="[^"]*result__a[^"]*"[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi;
+    const links = [];
+    for (const lm of html.matchAll(linkPat)) {
+        const url = extractDdgUrl(lm[1] || '');
+        const title = clean(lm[2] || '');
+        if (url && title && isOrganicUrl(url)) {
+            links.push({ url, title });
+        }
+    }
+    return links;
+}
+function extractSnippets(html) {
+    const snipPat = /<a[^>]*class="[^"]*result__snippet[^"]*"[^>]*>([\s\S]*?)<\/a>/gi;
+    const snippets = [];
+    for (const sm of html.matchAll(snipPat)) {
+        const s = clean(sm[1] || '');
+        if (s) {
+            snippets.push(s);
+        }
+    }
+    return snippets;
+}
+function parseResultLinks(html) {
+    const links = extractLinks(html);
+    const snippets = extractSnippets(html);
+    const results = [];
+    for (let i = 0; i < links.length; i++) {
+        const link = links[i];
+        if (!link) {
+            continue;
+        }
+        results.push({
+            title: link.title,
+            url: link.url,
+            content: snippets[i] || link.title,
+            position: results.length + 1
+        });
+    }
+    return results;
+}
+function parseUddgFallback(html) {
+    const results = [];
+    const uddgPat = /uddg=([^&"]+)/gi;
+    const seen = new Set();
+    for (const um of html.matchAll(uddgPat)) {
+        try {
+            const url = decodeURIComponent(um[1] || '');
+            if (url.startsWith('http') && !seen.has(url) && !urlMatchesHost(url, 'duckduckgo.com')) {
+                seen.add(url);
+                const host = new URL(url).hostname;
+                results.push({
+                    title: host,
+                    url,
+                    content: `Result from ${host}`,
+                    position: results.length + 1,
+                    weak: true
+                });
+            }
+        }
+        catch { }
+    }
+    return results;
+}
+export async function searchDuckDuckGo(query, fetcher, signal) {
+    const body = `q=${encodeURIComponent(query)}`;
+    const html = await fetchHtml(fetcher, 'https://html.duckduckgo.com/html/', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Referer: 'https://html.duckduckgo.com/'
+        },
+        body
+    }, signal);
+    const primary = parseLinksMain(html);
+    if (primary.length > 0) {
+        return primary;
+    }
+    const secondary = parseResultLinks(html);
+    if (secondary.length > 0) {
+        return secondary;
+    }
+    return parseUddgFallback(html);
+}

package/dist-lib/lib/web-search/engines/google.d.ts

@@ -0,0 +1,3 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { Fetcher, RankedResult } from '../types.ts';
+export declare function searchGoogle(query: string, fetcher: Fetcher, signal?: BareAbortSignal): Promise<ReadonlyArray<RankedResult>>;

package/dist-lib/lib/web-search/engines/google.js

@@ -0,0 +1,92 @@
+import { fetchHtml } from "../fetch-html.js";
+import { clean } from "../html-helpers.js";
+import { urlMatchesHost } from "../url-helpers.js";
+import { GOOGLE_GSA_UA } from "../user-agents.js";
+function resolveGoogleUrl(rawUrl) {
+    if (rawUrl.startsWith('/url?q=')) {
+        return decodeURIComponent(rawUrl.slice(7).split('&')[0] || '');
+    }
+    return rawUrl;
+}
+function isGoogleSearchSelfLink(url) {
+    try {
+        const u = new URL(url);
+        const h = u.hostname.toLowerCase();
+        return (h === 'google.com' || h === 'www.google.com') && u.pathname === '/search';
+    }
+    catch {
+        return false;
+    }
+}
+function isSkippableUrl(url) {
+    return isGoogleSearchSelfLink(url) || urlMatchesHost(url, 'accounts.google.com');
+}
+function extractTitle(anchorBody) {
+    const titleMatch = anchorBody.match(/<(?:div|h3)[^>]*>([\s\S]*?)<\/(?:div|h3)>/i);
+    return titleMatch ? clean(titleMatch[1] || '') : clean(anchorBody);
+}
+function parseAnchor(am, html, snippetPat, existing) {
+    const rawUrl = resolveGoogleUrl(am[1] || '');
+    if (isSkippableUrl(rawUrl) || !rawUrl.startsWith('http')) {
+        return null;
+    }
+    const title = extractTitle(am[2] || '');
+    if (!title || title.length < 3 || existing.some((r) => r.url === rawUrl)) {
+        return null;
+    }
+    const region = html.slice(am.index, (am.index ?? 0) + 3000);
+    snippetPat.lastIndex = 0;
+    const sm = snippetPat.exec(region);
+    const content = sm ? clean(sm[1] || '') : '';
+    return { title, url: rawUrl, content, position: 0 };
+}
+function parseDataVedAnchors(html) {
+    const results = [];
+    const snippetPat = /<div[^>]*class="[^"]*VwiC3b[^"]*"[^>]*>([\s\S]*?)<\/div>/gi;
+    const anchorPat = /<a[^>]*\shref="(\/url\?q=[^"]+|https?:\/\/[^"]+)"[^>]*data-ved="[^"]*"[^>]*>([\s\S]*?)<\/a>/gi;
+    for (const am of html.matchAll(anchorPat)) {
+        const parsed = parseAnchor(am, html, snippetPat, results);
+        if (parsed) {
+            results.push({ ...parsed, position: results.length + 1 });
+        }
+    }
+    return results;
+}
+function parseH3Match(hm, existing) {
+    let rawUrl = hm[2] || '';
+    const title = clean(hm[1] || '');
+    if (!title || title.length < 3) {
+        return null;
+    }
+    rawUrl = resolveGoogleUrl(rawUrl);
+    if (!rawUrl.startsWith('http')) {
+        return null;
+    }
+    if (existing.some((r) => r.url === rawUrl)) {
+        return null;
+    }
+    return { title, url: rawUrl, content: '', position: 0 };
+}
+function parseH3Fallback(html) {
+    const results = [];
+    const h3Pat = /<h3[^>]*>([\s\S]*?)<\/h3>[\s\S]*?<a[^>]*href="(\/url\?q=[^"]+|https?:\/\/(?!google\.com)[^"]+)"[^>]*>/gi;
+    for (const hm of html.matchAll(h3Pat)) {
+        const parsed = parseH3Match(hm, results);
+        if (parsed) {
+            results.push({ ...parsed, position: results.length + 1 });
+        }
+    }
+    return results;
+}
+export async function searchGoogle(query, fetcher, signal) {
+    const url = `https://www.google.com/search?q=${encodeURIComponent(query)}&hl=en&ie=utf8&oe=utf8&filter=0`;
+    const html = await fetchHtml(fetcher, url, { headers: { 'User-Agent': GOOGLE_GSA_UA, Accept: '*/*' }, cookies: { CONSENT: 'YES+' } }, signal);
+    if (html.includes('detected unusual traffic') || html.includes('g-recaptcha')) {
+        throw new Error('Google CAPTCHA detected');
+    }
+    const primary = parseDataVedAnchors(html);
+    if (primary.length > 0) {
+        return primary;
+    }
+    return parseH3Fallback(html);
+}

package/dist-lib/lib/web-search/engines/wikipedia.d.ts

@@ -0,0 +1,3 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { Fetcher, RankedResult } from '../types.ts';
+export declare function searchWikipedia(query: string, fetcher: Fetcher, signal?: BareAbortSignal): Promise<ReadonlyArray<RankedResult>>;

package/dist-lib/lib/web-search/engines/wikipedia.js

@@ -0,0 +1,37 @@
+import { fetchJson } from "../fetch-html.js";
+import { clean } from "../html-helpers.js";
+function extractSearchItems(data) {
+    if (typeof data !== 'object' || data === null) {
+        return [];
+    }
+    const query = data.query;
+    if (typeof query !== 'object' || query === null) {
+        return [];
+    }
+    const search = query.search;
+    if (!Array.isArray(search)) {
+        return [];
+    }
+    const items = [];
+    for (const entry of search) {
+        if (typeof entry !== 'object' || entry === null) {
+            continue;
+        }
+        const { title, snippet } = entry;
+        if (typeof title === 'string' && typeof snippet === 'string') {
+            items.push({ title, snippet });
+        }
+    }
+    return items;
+}
+export async function searchWikipedia(query, fetcher, signal) {
+    const apiUrl = `https://en.wikipedia.org/w/api.php?action=query&list=search&srsearch=${encodeURIComponent(query)}&format=json&srlimit=5&utf8=1`;
+    const data = await fetchJson(fetcher, apiUrl, undefined, signal);
+    const items = extractSearchItems(data);
+    return items.map((item, idx) => ({
+        title: item.title,
+        url: `https://en.wikipedia.org/wiki/${encodeURIComponent(item.title.replace(/ /g, '_'))}`,
+        content: clean(item.snippet || item.title),
+        position: idx + 1
+    }));
+}

package/dist-lib/lib/web-search/engines/yahoo.d.ts

@@ -0,0 +1,3 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { Fetcher, RankedResult } from '../types.ts';
+export declare function searchYahoo(query: string, fetcher: Fetcher, signal?: BareAbortSignal): Promise<ReadonlyArray<RankedResult>>;

package/dist-lib/lib/web-search/engines/yahoo.js

@@ -0,0 +1,81 @@
+import { fetchHtml } from "../fetch-html.js";
+import { clean } from "../html-helpers.js";
+import { urlMatchesHost } from "../url-helpers.js";
+function decodeRuUrl(encoded) {
+    try {
+        const href = decodeURIComponent(encoded);
+        if (!href.startsWith('http')) {
+            return null;
+        }
+        if (urlMatchesHost(href, 'search.yahoo.com') || urlMatchesHost(href, 'shopping.yahoo.com')) {
+            return null;
+        }
+        return href;
+    }
+    catch {
+        return null;
+    }
+}
+function parseAlgoBlock(inner) {
+    const ruMatch = inner.match(/\/RU=(https?%3a%2f%2f[^/]*?)\/RK/i);
+    if (!ruMatch) {
+        return null;
+    }
+    const href = decodeRuUrl(ruMatch[1] || '');
+    if (!href) {
+        return null;
+    }
+    const titleMatch = inner.match(/<span[^>]*class="[^"]*fz-20[^"]*"[^>]*>([\s\S]*?)<\/span>/i);
+    const title = titleMatch ? clean(titleMatch[1] || '') : '';
+    if (!title) {
+        return null;
+    }
+    const snippetMatch = inner.match(/class="compText[^"]*"[^>]*>[\s\S]*?<p[^>]*>([\s\S]*?)<\/p>/i);
+    const content = snippetMatch ? clean(snippetMatch[1] || '') : title;
+    return { title, url: href, content, position: 0 };
+}
+function parseAlgoBlocks(html) {
+    const results = [];
+    const blocks = html.split(/algo algo-sr/i);
+    for (let i = 1; i < blocks.length; i++) {
+        const inner = blocks[i]?.slice(0, 5000) || '';
+        const parsed = parseAlgoBlock(inner);
+        if (parsed) {
+            results.push({ ...parsed, position: results.length + 1 });
+        }
+    }
+    return results;
+}
+function parseRuFallback(html) {
+    const results = [];
+    const seen = new Set();
+    const ruGlobal = /\/RU=(https?%3a%2f%2f[^/]*?)\/RK/gi;
+    for (const rm of html.matchAll(ruGlobal)) {
+        const href = decodeRuUrl(rm[1] || '');
+        if (!href || seen.has(href)) {
+            continue;
+        }
+        seen.add(href);
+        const host = new URL(href).hostname;
+        results.push({
+            title: host,
+            url: href,
+            content: `Result from ${host}`,
+            position: results.length + 1,
+            weak: true
+        });
+        if (results.length >= 15) {
+            break;
+        }
+    }
+    return results;
+}
+export async function searchYahoo(query, fetcher, signal) {
+    const url = `https://search.yahoo.com/search?p=${encodeURIComponent(query)}`;
+    const html = await fetchHtml(fetcher, url, undefined, signal);
+    const primary = parseAlgoBlocks(html);
+    if (primary.length > 0) {
+        return primary;
+    }
+    return parseRuFallback(html);
+}

package/dist-lib/lib/web-search/fetch-html.d.ts

@@ -0,0 +1,25 @@
+import { type AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { Fetcher } from './types.ts';
+export declare const ENGINE_TIMEOUT_MS = 8000;
+export declare const MAX_HTML_CHARS = 2000000;
+export declare class TimeoutError extends Error {
+    constructor(ms: number);
+}
+export declare class AbortError extends Error {
+    constructor();
+}
+type FetchOptions = {
+    readonly method?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+    readonly cookies?: Readonly<Record<string, string>>;
+    readonly accept?: string;
+    readonly timeoutMs?: number;
+};
+export declare function fetchHtml(fetcher: Fetcher, url: string, options?: FetchOptions, signal?: BareAbortSignal): Promise<string>;
+export declare class JsonParseError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export declare function fetchJson(fetcher: Fetcher, url: string, options?: FetchOptions, signal?: BareAbortSignal): Promise<unknown>;
+export {};

package/dist-lib/lib/web-search/fetch-html.js

@@ -0,0 +1,97 @@
+import { AbortController } from 'bare-abort-controller';
+import { BROWSER_UA } from "./user-agents.js";
+export const ENGINE_TIMEOUT_MS = 8000;
+export const MAX_HTML_CHARS = 2_000_000;
+export class TimeoutError extends Error {
+    constructor(ms) {
+        super(`Request timed out after ${ms}ms`);
+        this.name = 'TimeoutError';
+    }
+}
+export class AbortError extends Error {
+    constructor() {
+        super('Request cancelled');
+        this.name = 'AbortError';
+    }
+}
+function buildInit(options, signal) {
+    const headers = {
+        'User-Agent': BROWSER_UA,
+        Accept: options?.accept ?? 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+        'Accept-Language': 'en-US,en;q=0.5',
+        ...options?.headers
+    };
+    if (options?.cookies && Object.keys(options.cookies).length > 0) {
+        headers['Cookie'] = Object.entries(options.cookies)
+            .map(([k, v]) => `${k}=${v}`)
+            .join('; ');
+    }
+    const init = {
+        method: options?.method ?? 'GET',
+        headers,
+        redirect: 'follow',
+        signal
+    };
+    if (options?.body) {
+        return { ...init, body: options.body };
+    }
+    return init;
+}
+async function fetchWithTimeout(fetcher, url, options, callerSignal) {
+    if (callerSignal?.aborted) {
+        throw new AbortError();
+    }
+    let timedOut = false;
+    const ac = new AbortController();
+    const timeoutMs = options?.timeoutMs ?? ENGINE_TIMEOUT_MS;
+    const timeoutId = setTimeout(() => {
+        timedOut = true;
+        ac.abort(undefined);
+    }, timeoutMs);
+    const onCallerAbort = () => ac.abort(undefined);
+    callerSignal?.addEventListener('abort', onCallerAbort);
+    try {
+        const resp = await fetcher(url, buildInit(options, ac.signal));
+        const raw = await resp.text();
+        const text = raw.length > MAX_HTML_CHARS ? raw.slice(0, MAX_HTML_CHARS) : raw;
+        return { ok: resp.ok, status: resp.status, text };
+    }
+    catch (err) {
+        if (timedOut)
+            throw new TimeoutError(timeoutMs);
+        if (callerSignal?.aborted)
+            throw new AbortError();
+        throw err;
+    }
+    finally {
+        clearTimeout(timeoutId);
+        callerSignal?.removeEventListener('abort', onCallerAbort);
+    }
+}
+export async function fetchHtml(fetcher, url, options, signal) {
+    const { ok, status, text } = await fetchWithTimeout(fetcher, url, options, signal);
+    if (!ok) {
+        throw new Error(`HTTP ${status}`);
+    }
+    return text;
+}
+export class JsonParseError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'JsonParseError';
+    }
+}
+export async function fetchJson(fetcher, url, options, signal) {
+    const { ok, status, text } = await fetchWithTimeout(fetcher, url, { ...options, accept: options?.accept ?? 'application/json' }, signal);
+    if (!ok) {
+        throw new Error(`HTTP ${status}`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new JsonParseError(`Response was not valid JSON (${text.length} chars): ${(err instanceof Error ? err : new Error(String(err))).message}`, err);
+    }
+}

package/dist-lib/lib/web-search/format-results.d.ts

@@ -0,0 +1,3 @@
+import type { WebSearchResult } from './types.ts';
+export declare const MAX_CONTENT_CHARS = 800;
+export declare function formatResultsForPrompt(results: ReadonlyArray<WebSearchResult>): string;

package/dist-lib/lib/web-search/format-results.js

@@ -0,0 +1,14 @@
+export const MAX_CONTENT_CHARS = 800;
+export function formatResultsForPrompt(results) {
+    if (results.length === 0) {
+        return '';
+    }
+    return results
+        .map((result, index) => {
+        const content = result.content.length > MAX_CONTENT_CHARS
+            ? `${result.content.slice(0, MAX_CONTENT_CHARS)}…`
+            : result.content;
+        return `[${index + 1}] ${result.title}\nSource: ${result.url}\n${content}`;
+    })
+        .join('\n\n');
+}

package/dist-lib/lib/web-search/html-helpers.d.ts

@@ -0,0 +1,3 @@
+export declare function stripHtmlTags(text: string): string;
+export declare function decodeHtmlEntities(text: string): string;
+export declare function clean(raw: string): string;

package/dist-lib/lib/web-search/html-helpers.js

@@ -0,0 +1,24 @@
+export function stripHtmlTags(text) {
+    let out = text;
+    let prev = '';
+    while (out !== prev) {
+        prev = out;
+        out = out.replace(/<[^>]*>/g, '');
+    }
+    return out;
+}
+const NAMED_ENTITIES = {
+    '&lt;': '<',
+    '&gt;': '>',
+    '&quot;': '"',
+    '&nbsp;': ' ',
+    '&amp;': '&'
+};
+export function decodeHtmlEntities(text) {
+    return text.replace(/&(?:lt|gt|quot|nbsp|amp|#\d+);/g, (match) => match.startsWith('&#')
+        ? String.fromCodePoint(parseInt(match.slice(2, -1), 10))
+        : (NAMED_ENTITIES[match] ?? match));
+}
+export function clean(raw) {
+    return decodeHtmlEntities(stripHtmlTags(raw)).trim();
+}

package/dist-lib/lib/web-search/merge-results.d.ts

@@ -0,0 +1,2 @@
+import type { EngineOutcome, WebSearchResult } from './types.ts';
+export declare function mergeResults(engineResults: ReadonlyArray<EngineOutcome>, maxResults: number): ReadonlyArray<WebSearchResult>;

package/dist-lib/lib/web-search/merge-results.js

@@ -0,0 +1,53 @@
+import { normalizeUrl } from "./url-normalize.js";
+const WEAK_RESULT_PENALTY = 0.2;
+function scoreFor(r) {
+    const base = 1 / r.position;
+    return r.weak ? base * WEAK_RESULT_PENALTY : base;
+}
+function updateEntry(existing, r, engine) {
+    if (r.title.length > existing.title.length) {
+        existing.title = r.title;
+    }
+    if (r.content.length > existing.content.length) {
+        existing.content = r.content;
+    }
+    existing.score += scoreFor(r);
+    existing.engines.add(engine);
+}
+export function mergeResults(engineResults, maxResults) {
+    const map = new Map();
+    for (const { engine, results } of engineResults) {
+        for (const r of results) {
+            const key = normalizeUrl(r.url);
+            const existing = map.get(key);
+            if (existing) {
+                updateEntry(existing, r, engine);
+            }
+            else {
+                map.set(key, {
+                    title: r.title,
+                    url: r.url,
+                    content: r.content,
+                    score: scoreFor(r),
+                    engines: new Set([engine])
+                });
+            }
+        }
+    }
+    const sorted = Array.from(map.values()).sort((a, b) => {
+        if (b.score !== a.score) {
+            return b.score - a.score;
+        }
+        if (b.engines.size !== a.engines.size) {
+            return b.engines.size - a.engines.size;
+        }
+        return b.content.length - a.content.length;
+    });
+    return sorted.slice(0, maxResults).map((entry) => ({
+        title: entry.title,
+        url: entry.url,
+        content: entry.content,
+        score: Math.round(entry.score * 100) / 100,
+        engines: Array.from(entry.engines)
+    }));
+}

package/dist-lib/lib/web-search/orchestrator.d.ts

@@ -0,0 +1,14 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { Fetcher, WebSearchResult } from './types.ts';
+export type EngineSummaryEntry = {
+    readonly engine: string;
+    readonly status: 'ok' | 'timeout' | 'error';
+    readonly resultCount: number;
+    readonly durationMs: number;
+};
+export type SearchWebResult = {
+    readonly results: ReadonlyArray<WebSearchResult>;
+    readonly engineSummary: ReadonlyArray<EngineSummaryEntry>;
+};
+export declare function classifyEngineError(reason: unknown): 'timeout' | 'error';
+export declare function searchWeb(fetcher: Fetcher, query: string, maxResults?: number, signal?: BareAbortSignal): Promise<SearchWebResult>;

package/dist-lib/lib/web-search/orchestrator.js

@@ -0,0 +1,50 @@
+import { DEFAULT_MAX_RESULTS, ENGINES } from "./engine-registry.js";
+import { TimeoutError } from "./fetch-html.js";
+import { mergeResults } from "./merge-results.js";
+export function classifyEngineError(reason) {
+    return reason instanceof TimeoutError ? 'timeout' : 'error';
+}
+function processSettledResult(engineName, result, outcomes, engineSummary) {
+    if (result.status === 'fulfilled') {
+        outcomes.push(result.value);
+        engineSummary.push({
+            engine: engineName,
+            status: 'ok',
+            resultCount: result.value.results.length,
+            durationMs: result.value.durationMs
+        });
+    }
+    else {
+        engineSummary.push({
+            engine: engineName,
+            status: classifyEngineError(result.reason),
+            resultCount: 0,
+            durationMs: 0
+        });
+    }
+}
+export async function searchWeb(fetcher, query, maxResults = DEFAULT_MAX_RESULTS, signal) {
+    const settled = await Promise.allSettled(ENGINES.map(async ({ name, fn }) => {
+        const start = Date.now();
+        const results = await fn(query, fetcher, signal);
+        return {
+            engine: name,
+            results: [...results],
+            durationMs: Date.now() - start
+        };
+    }));
+    const outcomes = [];
+    const engineSummary = [];
+    for (let i = 0; i < ENGINES.length; i++) {
+        const engine = ENGINES[i];
+        const settledResult = settled[i];
+        if (!engine || !settledResult) {
+            continue;
+        }
+        processSettledResult(engine.name, settledResult, outcomes, engineSummary);
+    }
+    if (outcomes.length === 0) {
+        return { results: [], engineSummary };
+    }
+    return { results: mergeResults(outcomes, maxResults), engineSummary };
+}

package/dist-lib/lib/web-search/types.d.ts

@@ -0,0 +1,34 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+export interface RankedResult {
+    title: string;
+    url: string;
+    content: string;
+    position: number;
+    weak?: boolean;
+}
+export interface WebSearchResult {
+    title: string;
+    url: string;
+    content: string;
+    score?: number;
+    engines?: string[];
+}
+export interface EngineOutcome {
+    engine: string;
+    results: RankedResult[];
+    durationMs: number;
+}
+export interface FetchInit {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    redirect?: 'follow' | 'manual' | 'error';
+    signal?: BareAbortSignal;
+}
+export interface Response {
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}
+export type Fetcher = (url: string, init?: FetchInit) => Promise<Response>;
+export type SearchEngine = (query: string, fetcher: Fetcher, signal?: BareAbortSignal) => Promise<ReadonlyArray<RankedResult>>;

package/dist-lib/lib/web-search/types.js

@@ -0,0 +1 @@
+export {};

package/dist-lib/lib/web-search/url-helpers.d.ts

@@ -0,0 +1 @@
+export declare function urlMatchesHost(url: string, host: string): boolean;