@allansantos-dev/smart-tool 0.0.0-stage → 0.9.0

package/web_adapters/browser/browser_service.py

@@ -0,0 +1,302 @@
+#!/usr/bin/env python3
+"""Navegador Camoufox residente: uma instância, abas reaproveitadas, protocolo JSON por linha.
+
+Entrada (stdin): {"id": str, "engine": "google|duckduckgo|startpage", "query": str, "num": int, "expires_at": epoch}
+Saída (stdout): {"ready": true} ao subir; depois {"id": str, "results": [...]} ou
+{"id": str, "error": str, "captcha": bool, "skipped": bool}.
+Encerra sozinho após IDLE_S sem pedidos, quando o stdin fecha ou quando o navegador cai.
+"""
+import asyncio
+import json
+import os
+import sys
+import time
+import urllib.parse
+import uuid
+
+TABS = 2
+IDLE_S = 300
+PAGE_OP_TIMEOUT_S = 10
+# Google flagged the IP after ~150 searches in bursts of 4; 40 sequential searches ~4 s apart passed.
+MIN_GAP_S = {"google": 4.0}
+# Startpage's Anubis challenge can hold a tab for minutes; never let it take every tab.
+MAX_CONCURRENT = {"startpage": 1}
+SESSION_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), "sessions", "browser.storage_state.json")
+
+GOOGLE_JS = (
+    "() => [...document.querySelectorAll('#search a:has(h3)')].map(a => { "
+    "const box = a.closest('[data-hveid], .g') || a.parentElement; "
+    "const s = box && box.querySelector('.VwiC3b, [data-sncf], [style*=\"line-clamp\"]'); "
+    "return {url: a.href, title: a.querySelector('h3').innerText, snippet: s ? s.innerText : ''}; })"
+)
+DDG_JS = (
+    "() => [...document.querySelectorAll('.result')].map(el => { "
+    "const a = el.querySelector('.result__a'); const s = el.querySelector('.result__snippet'); "
+    "return {url: a ? (a.getAttribute('href') || '') : '', title: a ? (a.textContent || '').trim() : '', "
+    "snippet: s ? (s.textContent || '').trim() : ''}; }).filter(r => r.url)"
+)
+STARTPAGE_JS = (
+    "() => [...document.querySelectorAll('.result')].map(el => { "
+    "const t = el.querySelector('[class*=\"result-title\" i]'); const a = t || el.querySelector('a'); "
+    "const s = el.querySelector('p, [class*=\"description\" i], [class*=\"snippet\" i]'); "
+    "return {url: a ? a.href : '', title: a ? (a.textContent || '').trim() : '', "
+    "snippet: s ? (s.textContent || '').trim() : ''}; }).filter(r => r.url)"
+)
+STARTPAGE_CHALLENGE_MARKERS = ("anubis", "verifying your request", "making sure you're not a bot")
+
+
+class Captcha(Exception):
+    pass
+
+
+class Skipped(Exception):
+    pass
+
+
+def _ddg_real_url(href):
+    parsed = urllib.parse.urlparse(href if href.startswith("http") else f"https:{href}")
+    target = urllib.parse.parse_qs(parsed.query).get("uddg")
+    return target[0] if target else href
+
+
+async def _body_text(page):
+    return (await page.evaluate("document.body ? document.body.innerText : ''"))[:3000].lower()
+
+
+async def google(page, query, timeout_s):
+    await page.goto("https://www.google.com/search?" + urllib.parse.urlencode({"hl": "en", "q": query}),
+                    wait_until="domcontentloaded", timeout=timeout_s * 1000)
+    if "/sorry/" in page.url:
+        raise Captcha("google: /sorry/ page (unusual traffic)")
+    try:
+        await page.wait_for_selector("#search a:has(h3)", timeout=min(4, timeout_s) * 1000)
+    except Exception:
+        if "unusual traffic" in await _body_text(page):
+            raise Captcha("google: unusual traffic")
+    rows = await page.evaluate(GOOGLE_JS)
+    targets = await asyncio.gather(*(_google_target(page, row["url"]) for row in rows))
+    return [{**row, "url": target} for row, target in zip(rows, targets) if target]
+
+
+async def _google_target(page, href):
+    # Result links are opaque /goto?url=... redirects; the session resolves them without following.
+    parsed = urllib.parse.urlparse(href)
+    if not parsed.netloc.endswith("google.com") or not parsed.path.startswith(("/goto", "/url")):
+        return href
+    try:
+        response = await page.context.request.get(href, max_redirects=0, timeout=5000)
+    except Exception:
+        return None
+    return response.headers.get("location")
+
+
+async def duckduckgo(page, query, timeout_s):
+    await page.goto("https://html.duckduckgo.com/html/?" + urllib.parse.urlencode({"q": query}),
+                    wait_until="domcontentloaded", timeout=timeout_s * 1000)
+    try:
+        await page.wait_for_selector(".result__a", timeout=min(8, timeout_s) * 1000)
+    except Exception:
+        if "bots use duckduckgo too" in await _body_text(page):
+            raise Captcha("duckduckgo: image challenge")
+    return [{**row, "url": _ddg_real_url(row["url"])} for row in await page.evaluate(DDG_JS)]
+
+
+async def startpage(page, query, timeout_s):
+    started = time.monotonic()
+    await page.goto("https://www.startpage.com/sp/search?" + urllib.parse.urlencode({"query": query}),
+                    wait_until="domcontentloaded", timeout=timeout_s * 1000)
+    while True:
+        rows = await page.evaluate(STARTPAGE_JS)
+        if rows:
+            return rows
+        text = await _body_text(page)
+        challenged = any(marker in text for marker in STARTPAGE_CHALLENGE_MARKERS)
+        if not challenged and time.monotonic() - started > 5:
+            return []
+        if time.monotonic() - started > timeout_s - 2:
+            return []
+        await asyncio.sleep(1)
+
+
+ENGINES = {"google": google, "duckduckgo": duckduckgo, "startpage": startpage}
+
+
+class Service:
+    def __init__(self, context, emit, exit_process):
+        self.context = context
+        self.emit = emit
+        self.exit_process = exit_process
+        self.pages = asyncio.Queue()
+        self.page_lock = asyncio.Lock()
+        self.pace_locks = {engine: asyncio.Lock() for engine in MIN_GAP_S}
+        self.last_run = {}
+        self.limits = {engine: asyncio.Semaphore(n) for engine, n in MAX_CONCURRENT.items()}
+        self.last_activity = time.monotonic()
+        self.in_flight = 0
+
+    async def start(self):
+        for _ in range(TABS):
+            self.pages.put_nowait(await self._new_page())
+
+    async def _new_page(self):
+        # Opening several tabs at once hangs Camoufox navigations; tabs are created one at a time.
+        async with self.page_lock:
+            page = await asyncio.wait_for(self.context.new_page(), PAGE_OP_TIMEOUT_S)
+            await asyncio.wait_for(page.goto("about:blank"), PAGE_OP_TIMEOUT_S)
+            return page
+
+    async def _recycle(self, page, healthy):
+        try:
+            if not healthy:
+                raise asyncio.TimeoutError
+            await asyncio.wait_for(page.goto("about:blank"), PAGE_OP_TIMEOUT_S)
+            return page
+        except Exception:
+            try:
+                await asyncio.wait_for(page.close(), PAGE_OP_TIMEOUT_S)
+            except Exception:
+                pass
+        try:
+            return await self._new_page()
+        except Exception as exc:
+            print(f"tab could not be recreated; browser shut down: {exc}", file=sys.stderr, flush=True)
+            self.exit_process(1)
+
+    async def save_session(self):
+        try:
+            os.makedirs(os.path.dirname(SESSION_PATH), exist_ok=True)
+            tmp = f"{SESSION_PATH}.{uuid.uuid4().hex}.tmp"
+            state = await asyncio.wait_for(self.context.storage_state(), PAGE_OP_TIMEOUT_S)
+            with open(tmp, "w", encoding="utf-8") as stream:
+                json.dump(state, stream)
+            os.replace(tmp, SESSION_PATH)
+        except Exception as exc:
+            print(f"session not saved: {type(exc).__name__}: {exc}", file=sys.stderr, flush=True)
+
+    def _left(self, request):
+        return float(request["expires_at"]) - time.time()
+
+    async def _pace(self, engine, request):
+        gap = MIN_GAP_S.get(engine)
+        if not gap:
+            return
+        async with self.pace_locks[engine]:
+            wait = self.last_run.get(engine, 0) + gap - time.monotonic()
+            if wait > 0:
+                if wait >= self._left(request) - 1:
+                    raise Skipped(f"{engine}: minimum interval between searches exceeds the deadline")
+                await asyncio.sleep(wait)
+            self.last_run[engine] = time.monotonic()
+
+    async def handle(self, request):
+        self.in_flight += 1
+        try:
+            self.emit(await self._run(request))
+        finally:
+            self.in_flight -= 1
+            self.last_activity = time.monotonic()
+
+    async def _run(self, request):
+        engine_name = request.get("engine")
+        if engine_name not in ENGINES:
+            return {"id": request.get("id"), "error": f"unknown engine: {engine_name!r}", "captcha": False}
+        limit = self.limits.get(engine_name)
+        try:
+            if limit:
+                await asyncio.wait_for(limit.acquire(), max(0.01, self._left(request)))
+            try:
+                return await self._run_on_tab(request, engine_name)
+            finally:
+                if limit:
+                    limit.release()
+        except asyncio.TimeoutError:
+            return self._skipped(request, f"{engine_name}: another search holds the engine past the deadline")
+        except Skipped as exc:
+            return self._skipped(request, str(exc))
+
+    def _skipped(self, request, reason):
+        return {"id": request.get("id"), "error": reason, "captcha": False, "skipped": True}
+
+    async def _run_on_tab(self, request, engine_name):
+        try:
+            page = await asyncio.wait_for(self.pages.get(), max(0.01, self._left(request)))
+        except asyncio.TimeoutError:
+            raise Skipped(f"{engine_name}: no free tab before the deadline")
+        healthy = True
+        try:
+            await self._pace(engine_name, request)
+            left = self._left(request)
+            if left < 1:
+                raise Skipped(f"{engine_name}: deadline expired before running")
+            rows = await asyncio.wait_for(ENGINES[engine_name](page, request["query"], left), left)
+            rows = [r for r in rows if str(r.get("url", "")).startswith("http")][:int(request.get("num") or 8)]
+            if rows and engine_name == "startpage":
+                await self.save_session()
+            return {"id": request["id"], "results": rows}
+        except Skipped:
+            raise
+        except Captcha as exc:
+            return {"id": request["id"], "error": str(exc), "captcha": True}
+        except Exception as exc:
+            healthy = not isinstance(exc, asyncio.TimeoutError)
+            return {"id": request["id"], "error": f"{engine_name}: {type(exc).__name__}: {exc}"[:400],
+                    "captcha": False}
+        finally:
+            self.pages.put_nowait(await self._recycle(page, healthy))
+
+
+def emit(message):
+    sys.stdout.write(json.dumps(message, ensure_ascii=False) + "\n")
+    sys.stdout.flush()
+
+
+async def main():
+    from camoufox.async_api import AsyncCamoufox
+
+    loop = asyncio.get_running_loop()
+    browser = await AsyncCamoufox(headless=True).__aenter__()
+    browser.on("disconnected", lambda *_: os._exit(1))
+    state = None
+    try:
+        with open(SESSION_PATH, encoding="utf-8") as stream:
+            state = json.load(stream)
+    except (OSError, ValueError):
+        pass
+    service = Service(await browser.new_context(storage_state=state), emit, os._exit)
+    await service.start()
+    emit({"ready": True})
+    tasks = set()
+    reader = loop.run_in_executor(None, sys.stdin.readline)
+    while True:
+        done, _ = await asyncio.wait({reader}, timeout=5)
+        if not done:
+            if service.in_flight == 0 and time.monotonic() - service.last_activity > IDLE_S:
+                break
+            continue
+        line = reader.result()
+        if not line:
+            break
+        reader = loop.run_in_executor(None, sys.stdin.readline)
+        try:
+            request = json.loads(line)
+            if not isinstance(request, dict):
+                raise ValueError("request is not an object")
+        except ValueError:
+            print(f"invalid line ignored: {line[:200]!r}", file=sys.stderr, flush=True)
+            continue
+        service.last_activity = time.monotonic()
+        task = asyncio.create_task(service.handle(request))
+        tasks.add(task)
+        task.add_done_callback(tasks.discard)
+    if tasks:
+        await asyncio.wait(tasks, timeout=10)
+    try:
+        await asyncio.wait_for(browser.close(), PAGE_OP_TIMEOUT_S)
+    finally:
+        os._exit(0)
+
+
+if __name__ == "__main__":
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+    asyncio.run(main())

package/web_adapters/browser/crawl4ai_search.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+# Uso: python crawl4ai_search.py "<url semente>" [--max-pages 5]
+# Saida: JSON no stdout -- {"pages": [{"url": ..., "markdown": ...}, ...]}
+# Tier 4 do web_search do Smart Tool: crawl multi-pagina (BFS, mesmo dominio) a partir
+# de uma URL ja resolvida pelo chamador (nao faz busca — quem decide a URL semente e o
+# daemon, via Tier 1, antes de invocar este script).
+import asyncio
+import ipaddress
+import json
+import socket
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from crawl4ai import AsyncWebCrawler, BFSDeepCrawlStrategy, CacheMode, CrawlerRunConfig
+from crawl4ai.async_crawler_strategy import AsyncPlaywrightCrawlerStrategy
+from crawl4ai.deep_crawling.filters import FilterChain, URLFilter
+from playwright.async_api import Error as PlaywrightError
+
+sys.stdout.reconfigure(encoding="utf-8")
+sys.stderr.reconfigure(encoding="utf-8")
+
+MAX_REDIRECT_HOPS = 5
+
+
+def _is_safe_target(url):
+    # Mesma checagem do daemon (_is_safe_crawl_target): resolve o host de
+    # verdade via DNS, não confia só na string da URL, recusa IP privado/
+    # loopback/link-local/reservado/multicast. Duplicada aqui (não importada
+    # do daemon) porque este script é quem de fato faz a navegação de rede —
+    # a validação do daemon sozinha não cobre redirect HTTP nem link
+    # descoberto durante o crawl, só a URL semente original.
+    try:
+        parsed = urllib.parse.urlparse(url)
+    except ValueError:
+        return False
+    if parsed.scheme not in ("http", "https") or not parsed.hostname:
+        return False
+    try:
+        addrs = socket.getaddrinfo(parsed.hostname, None)
+    except socket.gaierror:
+        return False
+    for _family, _type, _proto, _canonname, sockaddr in addrs:
+        try:
+            ip = ipaddress.ip_address(sockaddr[0])
+        except ValueError:
+            return False
+        if not ip.is_global:
+            return False
+    return True
+
+
+class _NoAutoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None  # deixa o 3xx virar HTTPError em vez de seguir automaticamente
+
+
+_NO_REDIRECT_OPENER = urllib.request.build_opener(_NoAutoRedirect)
+
+
+def resolve_safe_final_url(url, max_hops=MAX_REDIRECT_HOPS):
+    # Segue a cadeia de redirect manualmente, validando CADA salto antes de
+    # seguir — sem isto, uma URL semente pública (que passa a validação
+    # inicial) responder com "302 Location: http://127.0.0.1:.../status"
+    # levaria o browser real a seguir o redirect sem qualquer checagem, já
+    # que o navegador do Crawl4AI segue 3xx de forma transparente.
+    current = url
+    for _ in range(max_hops + 1):
+        if not _is_safe_target(current):
+            raise ValueError(f"URL rejected (internal/reserved network target): {current}")
+        req = urllib.request.Request(current, headers={"User-Agent": "Mozilla/5.0"})
+        try:
+            resp = _NO_REDIRECT_OPENER.open(req, timeout=10)
+            resp.close()
+            return current
+        except urllib.error.HTTPError as e:
+            if e.code not in (301, 302, 303, 307, 308):
+                return current  # erro não-redirect (404 etc.) — deixa o crawler real reportar
+            location = e.headers.get("Location")
+            if not location:
+                raise ValueError("Redirect without a Location header")
+            current = urllib.parse.urljoin(current, location)
+    raise ValueError("Too many redirects while resolving the seed URL")
+
+
+class _SSRFSafeURLFilter(URLFilter):
+    # Primeira triagem, barata, de cada link descoberto no BFS antes de
+    # sequer abrir uma página pra ele — a defesa real (que cobre redirect
+    # HTTP em qualquer salto e navegação por meta-refresh/JS, que este
+    # filtro de string não alcança) é o route guard via Playwright abaixo.
+    def apply(self, url):
+        try:
+            return _is_safe_target(url)
+        except Exception:
+            return False
+
+
+_MAX_ROUTE_REDIRECT_HOPS = 5
+
+
+async def _abort_route(route):
+    try:
+        await route.abort()
+    except PlaywrightError:
+        # O contexto pode fechar enquanto um sub-recurso ainda está em rota.
+        # Nesse estado a requisição já foi descartada pelo navegador.
+        pass
+
+
+async def _ssrf_route_guard(route):
+    # Cobre a navegação (inicial, redirect HTTP em qualquer salto, e
+    # meta-refresh/JS) e sub-recursos da PÁGINA em que foi instalado — o que
+    # `page.route()` alcança. Novas páginas/abas (popup, target="_blank") e
+    # WebSocket ficam fora do alcance dessa API e são bloqueados por outros
+    # mecanismos (ver `_install_ssrf_route_guard`), não por este guard.
+    # Playwright não emite um novo evento de rota pro destino de um redirect
+    # HTTP — o browser segue o 3xx internamente — por isso a cadeia é seguida
+    # manualmente via route.fetch(max_redirects=0), validando cada salto
+    # antes de buscar o próximo; route.fulfill só ocorre quando o destino
+    # final também é seguro, e qualquer salto reprovado aborta a requisição.
+    current_url = route.request.url
+    for _ in range(_MAX_ROUTE_REDIRECT_HOPS + 1):
+        try:
+            # to_thread pra não bloquear o event loop enquanto outras páginas
+            # do mesmo lote (arun_many) carregam em paralelo.
+            safe = await asyncio.to_thread(_is_safe_target, current_url)
+        except Exception:
+            safe = False
+        if not safe:
+            await _abort_route(route)
+            return
+        try:
+            response = await route.fetch(url=current_url, max_redirects=0)
+        except Exception:
+            await _abort_route(route)
+            return
+        if response.status in (301, 302, 303, 307, 308):
+            location = response.headers.get("location")
+            if not location:
+                await _abort_route(route)
+                return
+            current_url = urllib.parse.urljoin(current_url, location)
+            continue
+        try:
+            await route.fulfill(response=response)
+        except PlaywrightError:
+            await _abort_route(route)
+        return
+    await _abort_route(route)
+
+
+async def _ssrf_ws_guard(ws_route):
+    # page.route() não intercepta WebSocket (API separada do Playwright) —
+    # sem isto, JS na página estabeleceria a conexão TCP direto, sem passar
+    # por _is_safe_target nenhuma vez. Extração de markdown não depende de
+    # WebSocket, então a conexão é sempre fechada sem nunca chamar
+    # connect_to_server (o servidor real nunca é contatado).
+    await ws_route.close()
+
+
+async def _install_ssrf_route_guard(page, context=None, config=None):
+    # Registrar no context (não no page) cobre também popup/nova aba
+    # (window.open, target="_blank") desde a primeira requisição — routing
+    # por Page só existe depois que a página já foi criada, tarde o
+    # bastante pra uma navegação inicial disparada por popup escapar sem
+    # checagem.
+    target = context if context is not None else page
+    if getattr(target, "_ssrf_guard_installed", False):
+        return
+    target._ssrf_guard_installed = True
+    # As duas chamadas abaixo não são atômicas — depende deste hook disparar
+    # estritamente antes de qualquer goto()/JS no context (garantia do
+    # crawl4ai enquanto cada página nasce em about:blank sem reaproveitar
+    # sessão/context já em uso; deixaria de valer se o script um dia passar
+    # a configurar reuso de sessão/context no BrowserConfig).
+    await asyncio.gather(
+        target.route("**/*", _ssrf_route_guard),
+        target.route_web_socket("**/*", _ssrf_ws_guard),
+    )
+
+
+def parse_args(argv):
+    max_pages = 5
+    url_parts = []
+    i = 0
+    while i < len(argv):
+        if argv[i] == "--max-pages" and i + 1 < len(argv):
+            max_pages = int(argv[i + 1])
+            i += 2
+        else:
+            url_parts.append(argv[i])
+            i += 1
+    if not url_parts:
+        raise ValueError('Usage: python crawl4ai_search.py "<seed url>" [--max-pages 5]')
+    return " ".join(url_parts), max_pages
+
+
+async def crawl(seed_url, max_pages):
+    safe_seed_url = resolve_safe_final_url(seed_url)
+    config = CrawlerRunConfig(
+        deep_crawl_strategy=BFSDeepCrawlStrategy(
+            max_depth=2, max_pages=max_pages, filter_chain=FilterChain([_SSRFSafeURLFilter()]),
+        ),
+        cache_mode=CacheMode.BYPASS,
+        page_timeout=30000,
+    )
+    strategy = AsyncPlaywrightCrawlerStrategy()
+    strategy.set_hook("on_page_context_created", _install_ssrf_route_guard)
+    async with AsyncWebCrawler(crawler_strategy=strategy) as crawler:
+        results = await crawler.arun(url=safe_seed_url, config=config)
+        return [
+            {"url": r.url, "markdown": r.markdown.raw_markdown}
+            for r in results
+            if r.success and r.markdown and r.markdown.raw_markdown
+        ]
+
+
+def main():
+    seed_url, max_pages = parse_args(sys.argv[1:])
+    pages = asyncio.run(crawl(seed_url, max_pages))
+    if not pages:
+        print("No page extracted: the target may have blocked the crawler or has no content.", file=sys.stderr)
+        sys.exit(1)
+    sys.stdout.buffer.write(json.dumps({"pages": pages}, ensure_ascii=False).encode("utf-8"))
+    sys.stdout.buffer.write(b"\n")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except SystemExit:
+        raise
+    except Exception as exc:
+        print(str(exc), file=sys.stderr)
+        sys.exit(1)

package/web_adapters/browser/requirements.txt

@@ -0,0 +1,2 @@
+camoufox==0.5.6
+crawl4ai==0.9.3

package/web_adapters/node/adapter-common.mjs

@@ -0,0 +1,40 @@
+// Partes comuns dos adaptadores de busca em Node: texto de HTML e argumentos de linha de comando.
+
+const ENTITIES = {
+  amp: '&', lt: '<', gt: '>', quot: '"', '#39': "'", '#x27': "'", nbsp: ' ',
+};
+
+function decodeEntities(s) {
+  return s.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z0-9#]+);/g, (m, code) => {
+    if (code[0] === '#') {
+      const num = code[1] === 'x' || code[1] === 'X'
+        ? parseInt(code.slice(2), 16)
+        : parseInt(code.slice(1), 10);
+      return Number.isNaN(num) ? m : String.fromCodePoint(num);
+    }
+    return ENTITIES[code] ?? m;
+  });
+}
+
+export function stripTags(html) {
+  return decodeEntities(html.replace(/<[^>]+>/g, '')).trim();
+}
+
+// `defaults` lists the accepted --flags; a numeric default makes the flag numeric.
+export function parseArgs(argv, usage, defaults) {
+  const values = { ...defaults };
+  const queryParts = [];
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i].startsWith('--') ? argv[i].slice(2) : null;
+    if (flag !== null && flag in defaults && i + 1 < argv.length) {
+      const raw = argv[++i];
+      values[flag] = typeof defaults[flag] === 'number' ? Number(raw) || defaults[flag] : raw;
+    } else {
+      queryParts.push(argv[i]);
+    }
+  }
+  if (queryParts.length === 0) {
+    throw new Error(usage);
+  }
+  return { query: queryParts.join(' '), ...values };
+}

package/web_adapters/node/ddg-search.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// Uso: node ddg-search.mjs "consulta" [--num 8] [--region br-pt]
+// Saída: JSON no stdout — [{ title, url, snippet }, ...]
+import { parseArgs, stripTags } from './adapter-common.mjs';
+
+function realUrlFromDdgHref(href) {
+  const match = /uddg=([^&]+)/.exec(href);
+  if (!match) return href.startsWith('//') ? `https:${href}` : href;
+  try {
+    return decodeURIComponent(match[1]);
+  } catch {
+    return match[1];
+  }
+}
+
+async function main() {
+  const { query, num, region } = parseArgs(process.argv.slice(2),
+    'Usage: node ddg-search.mjs "query" [--num 8] [--region br-pt]', { num: 8, region: null });
+
+  const params = new URLSearchParams({ q: query });
+  if (region) params.set('kl', region);
+  const url = `https://html.duckduckgo.com/html/?${params.toString()}`;
+
+  const res = await fetch(url, {
+    headers: {
+      'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0 Safari/537.36',
+      'Accept-Language': 'pt-BR,pt;q=0.9,en;q=0.8',
+    },
+    signal: AbortSignal.timeout(15000),
+  });
+
+  if (!res.ok) {
+    throw new Error(`DuckDuckGo answered HTTP ${res.status}`);
+  }
+
+  const html = await res.text();
+
+  // Um resultado patrocinado usa a mesma classe `result__a` no link de título que um
+  // resultado orgânico — só o container (`<div class="result ... result--ad ...">`)
+  // distingue os dois. Por isso a extração é por bloco (do início de um `<div
+  // class="result ` até o início do próximo), não por duas regexes globais pareadas por
+  // posição: título+snippet do mesmo bloco nunca desalinha com o resultado seguinte, e um
+  // bloco com `result--ad` na própria classe é descartado antes de extrair.
+  const BLOCK_START = '<div class="result ';
+  const startPositions = [];
+  for (let i = html.indexOf(BLOCK_START); i !== -1; i = html.indexOf(BLOCK_START, i + BLOCK_START.length)) {
+    startPositions.push(i);
+  }
+
+  const titleRe = /<a[^>]*class="result__a"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/;
+  const snippetRe = /<a[^>]*class="result__snippet"[^>]*href="[^"]+"[^>]*>([\s\S]*?)<\/a>/;
+
+  const results = [];
+  for (let i = 0; i < startPositions.length && results.length < num; i++) {
+    const start = startPositions[i];
+    const end = i + 1 < startPositions.length ? startPositions[i + 1] : html.length;
+    const block = html.slice(start, end);
+
+    const classEnd = block.indexOf('"', BLOCK_START.length);
+    const classAttr = block.slice(BLOCK_START.length, classEnd);
+    if (classAttr.split(/\s+/).includes('result--ad')) continue;
+
+    const titleMatch = titleRe.exec(block);
+    if (!titleMatch) continue;
+    const snippetMatch = snippetRe.exec(block);
+
+    results.push({
+      title: stripTags(titleMatch[2]),
+      url: realUrlFromDdgHref(titleMatch[1]),
+      snippet: snippetMatch ? stripTags(snippetMatch[1]) : '',
+    });
+  }
+
+  if (results.length === 0) {
+    throw new Error('No result extracted: DuckDuckGo may have blocked or changed the HTML. Try again or rephrase the query.');
+  }
+
+  process.stdout.write(JSON.stringify(results, null, 2));
+}
+
+// Nunca chamar process.exit() aqui: com stdout/stderr em pipe (caso do
+// subprocess.run que consome este script), abortar o processo enquanto ainda
+// há handles assíncronos pendentes (ex.: o timer do AbortSignal.timeout do
+// fetch) pode disparar um crash nativo do libuv no Windows. Só marcar o
+// exit code e deixar o event loop drenar sozinho.
+main().catch((err) => {
+  console.error(String(err?.message ?? err));
+  process.exitCode = 1;
+});