feat(cli): clean search, add extract/format flags; harden engines & proxy rotation; fix bugs; update docs

- Add structured `search [engine] [query]` CLI: --limit/--lang/--region/--site/--file, --format (json|text|markdown|ndjson), --extract N, --search-timeout; Envelope and route logs to stderr with a --quiet default (fixes stdout pollution)
- Unify engines behind a single engineSpec registry (CLI + serve share it)
- Unify the extract knob to bool-or-int `extract=N` (drop extract_top); CLI and HTTP share core batch extraction, raw/rendered fetch, and clamp helpers
- Engines: Ecosia CF captcha detection (raw + browser), Yandex progressive-result wait, Google PAA poll + Has() existence probes, Bing title/desc attribute fallbacks
- Proxy: rotate challenged proxies out of the tag pool for one retry (X-Proxy-Attempts); browser health-ping skip window; opt-in WaitStable

examples/content/js-search-with-extract/README.md

@@ -8,4 +8,4 @@ npm install
 node index.js
 ```
 
-Edit the `text`, `extractTop`, or `extractMode` in [index.js](index.js) to tune it.
+Edit the `text`, `extract` depth, or `extractMode` in [index.js](index.js) to tune it.

examples/content/js-search-with-extract/index.js

@@ -4,14 +4,13 @@ import { OpenSERP } from "@openserp/sdk";
 //   const client = new OpenSERP({ apiKey: "<YOUR_API_TOKEN>", timeoutMs: 60_000 });
 const client = new OpenSERP({ baseUrl: "http://localhost:7000", timeoutMs: 60_000 });
 
-// `extract: true` fetches the top pages and returns their cleaned content
-// alongside each result, so you get the page text in a single request.
-// `extractTop` (max 5) controls how many results are enriched.
+// `extract: N` fetches the top N pages (max 5) and returns their cleaned
+// content alongside each result, so you get the page text in a single request.
+// `extract: true` is shorthand for the top result.
 const { results } = await client.search({
   engine: "ecosia",
   text: "what is a serp api",
-  extract: true,
-  extractTop: 2,
+  extract: 2,
   extractMode: "auto",
 });