@hy-sde-org/dsh-web-search-public 0.1.0-rc.6

package/CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing
+
+## Prerequisites
+
+- Node.js 22.19 or newer
+- npm
+
+Install exactly from the lockfile:
+
+```bash
+npm ci
+```
+
+## Validation
+
+Every behavioral change needs a direct regression test covering normal, edge, and failure
+behavior. Run the same checks as CI:
+
+```bash
+npm run check
+npm test
+npm run build
+npm run lint:package
+npm pack --dry-run
+npm audit --omit=dev
+```
+
+Parser tests must use fixture HTML, never the live web — a challenged or redesigned engine
+page must not make the suite red. Live scraping is covered by the opt-in real test only:
+
+```bash
+DSH_WEB_SEARCH_REAL_E2E=1 npm run test:real
+```
+
+The real test needs outbound network access, tolerates engine bot challenges (including the
+403 response Ecosia returns for headless clients), and treats a changed organic-result set as
+expected — record the observed engine behavior (per-engine result counts, challenge states)
+in the commit message when you validate a parser change against live sites.
+
+## Public release
+
+The package is published as a prebuilt public npm artifact. Do not publish TypeScript sources
+or ask users to approve a Git dependency’s build script.
+
+Run the non-publishing release gate from a clean worktree:
+
+```bash
+npm run release:check
+```
+
+The release owner must be a member of the npm `deepseek-ai` organization, enable 2FA, and log
+in locally. Never send an npm password, OTP, or token through chat or commit it to the
+repository. To run the same gate and publish the exact `package.json` version:
+
+```bash
+npm login
+npm run release:publish
+```
+
+The script refuses a dirty worktree, an unexpected package name, a missing npm login, and a
+version that already exists. It runs the complete validation suite, shows the tarball
+contents, prompts for confirmation, and publishes with `--access public` to the public npm
+registry.
+
+After publication, verify the registry artifact rather than the local checkout:
+
+```bash
+npm view @hy-sde-org/dsh-web-search-public version
+dsh plugin --profile web add @hy-sde-org/dsh-web-search-public
+dsh web --dump-config
+```
+
+## Design constraints
+
+- Keep the chain credential-free. Never add an API-key path, even as a fallback.
+- Keep engines strictly sequential and fail-forward: zero results, a timed-out engine, and a
+  failed request all advance to the next engine; only an all-engine failure may throw.
+- Keep every engine secret-free and header-lean: the browser-shaped `userAgent` constant and
+  an `accept` header, nothing more.
+- Keep parsers tolerant: a challenged or redesigned page must parse to zero organic results,
+  never throw into the chain.
+- Keep tests fixture-based; the live suite is opt-in (`DSH_WEB_SEARCH_REAL_E2E=1`).
+- Preserve the web seam contracts: providers return fully-formed `WebSearchSource[]` and the
+  consumer sets `truncated`; never mark results truncated yourself.
+- Preserve `redirect: "error"` on every engine fetch.
+- Preserve the oh-my-pi attribution and its MIT notice ([THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)) whenever engine code is changed or extended.
+
+Changes to these constraints require updating this file and [docs/operations.md](docs/operations.md).

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+Copyright (c) 2025-2026 Can Bölük
+Copyright (c) 2026 hy-sde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+# dsh-web-search-public — credential-free web search for DeepSeek Harness
+
+A zero-API-key web search provider for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
+The model-facing `web_search` tool runs a **sequential chain — Startpage first, then
+DuckDuckGo → Ecosia → Google → Mojeek** — and returns the first engine that yields organic
+results. No API keys, no accounts, no fetch provider, no setup.
+
+| Identity | Value |
+| --- | --- |
+| Package | `@hy-sde-org/dsh-web-search-public` |
+| Plugin id | `web-search-public` |
+| Provider id | `public` |
+| Engines (in order) | `startpage`, `duckduckgo`, `ecosia`, `google`, `mojeek` |
+> **Based on [oh-my-pi](https://github.com/can1357/oh-my-pi)** — the credential-free engine
+> chain and per-engine scrapers are ported from oh-my-pi’s `web/search/providers`
+> (`public.ts`, `startpage.ts`, `duckduckgo.ts`, `ecosia.ts`, `google.ts`, `mojeek.ts`),
+> adapted to the DeepSeek Harness `ctx.web` seam with sequential fail-forward semantics.
+> oh-my-pi is MIT-licensed (Mario Zechner, Can Bölük); see
+> [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).
+
+## Why
+
+DeepSeek Harness ships search providers that need an API key (DeepSeek, Exa, Perplexity).
+This bundle is the credential-free default: each search is an anonymous request to a public
+search engine, and the chain fails forward. If Startpage is down, rate-limited, or serves a
+bot challenge, the chain automatically tries DuckDuckGo, then Ecosia, then Google, then
+Mojeek. The first engine that returns at least one organic result wins; engines return
+zero results (rather than errors) when challenged, so the chain keeps moving instead of
+failing.
+
+## Prerequisites
+
+- Node.js 22.19 or newer with npm and pnpm on `PATH`;
+- DeepSeek Harness `0.1.0-rc.6` including the standard `dsh` CLI;
+- no API keys — nothing else.
+
+Install the Harness CLI and pnpm before continuing:
+
+```bash
+npm install --global @deepseek-ai/dsh@0.1.0-rc.6 pnpm
+dsh --version
+```
+
+## Quick start
+
+### Route A — published npm package (recommended)
+
+```bash
+dsh plugin --profile web add @hy-sde-org/dsh-web-search-public
+```
+
+### Route B — from source (validate this checkout or hack on the plugin)
+
+```bash
+git clone <this-repository-url> dsh-web-search-public
+cd dsh-web-search-public
+npm ci
+PACKAGE_TARBALL="$(npm pack --silent)"
+dsh plugin --profile web add "$PWD/$PACKAGE_TARBALL"
+cd ..
+```
+
+`npm pack` runs the normal `prepack` build and produces a tarball containing `dist/`. A direct
+`github:<this-repo>` dependency does not contain built output and is not a supported install
+path — always install the built tarball (or the published package).
+
+### Verify the composed configuration
+
+```bash
+dsh web --dump-config
+```
+
+The composed tree must show `web.config.searchProvider: public` and a `web-search-public`
+plugin row loading `@hy-sde-org/dsh-web-search-public`.
+
+### Run
+
+```bash
+dsh web
+```
+
+Ask the agent to `web_search` something. The tool returns rendered sources from the first
+engine that answered.
+
+### Uninstall
+
+```bash
+dsh plugin --profile web remove @hy-sde-org/dsh-web-search-public
+```
+
+> **Already shipped?** If your harness checkout already mounts `web-search-public` in its base
+> bundle (a future release may adopt this package as the shipped default), skip installation
+> — it is already the active provider. Adding this bundle on top would duplicate the loader
+> row and fail at boot (“duplicate loader entry id”).
+
+## What the bundle does
+
+The package declares a DSH bundle (`dsh.bundle.patch` → `cordis.patch.yml`), so `dsh plugin`
+installs it and applies its patch layer to the profile:
+
+1. sets `web.config.searchProvider` to `public` (making the credential-free chain the default),
+2. inserts the `web-search-public` plugin row.
+
+The keyed DeepSeek route (`web-search-deepseek`, provider id `deepseek-official`) is **not**
+disabled — deployments that prefer it keep their explicit choice by setting
+`web.searchProvider: deepseek-official` and providing the `DEEPSEEK_API_KEY` credential.
+No fetch provider is mounted and `tool-web` keeps `fetch: false`: the model can search, not
+fetch arbitrary URLs, which defers SSRF exposure entirely.
+
+## How the chain works
+
+`PublicSearchProvider.search()` walks `engines` in configured order:
+
+```text
+startpage ──► duckduckgo ──► ecosia ──► google ──► mojeek
+   │              │            │         │          │
+   ▼              ▼            ▼         ▼          ▼
+ 1+ results    1+ results   1+ results  1+ results  1+ results  → return them
+   │              │            │         │          │
+   ▼              ▼            ▼         ▼          ▼
+  0               0           0         0           0           → all failed → WEB_PROVIDER_ERROR
+```
+
+On each step the provider opens a fresh `AbortSignal.timeout(timeoutMs)` race, so a hung
+engine cannot pin the call past its budget. The worst case for the default order is
+`5 × timeoutMs` = 50 seconds; `dsh-tool-web` books a 60-second search budget for that.
+
+- `available()` is `true` whenever at least one engine is configured — the chain is always
+  usable, which is the point.
+- A caller abort (`signal.aborted`) aborts the in-flight engine and throws `WEB_ABORTED`.
+- Only if **every** engine fails does the provider throw `WEB_PROVIDER_ERROR` with each
+  engine’s reason (`id: <reason>; …`). Zero organic results, a timed-out engine, and a failed
+  HTTP request all count as “this engine has nothing” and move to the next one.
+
+## Configuration
+
+All options are optional; constants fill the defaults. Configure via the plugin row’s
+`config:` in your profile patch, or programmatically via `ctx.plugin(...)`.
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `engines` | `startpage, duckduckgo, ecosia, google, mojeek` | engine ids tried in order; unlisted engines stay disabled |
+| `timeoutMs` | `10000` | per-engine transport timeout; the chain worst case is `engines × timeoutMs` |
+| `userAgent` | browser-shaped constant | User-Agent sent to the engines (deliberately not the product UA) |
+
+```yaml
+- id: web-search-public
+  name: '@hy-sde-org/dsh-web-search-public'
+  config:
+    engines: [startpage, duckduckgo, google, mojeek]   # drop Ecosia, reorder
+    timeoutMs: 8000
+```
+
+`PublicEngineId` values are the exported engine ids; any id outside the known set is dropped
+at startup, and a zero-engine config makes `available()` false (surfacing
+`WEB_PROVIDER_CONFIGURED_UNAVAILABLE`).
+
+## Errors
+
+Search failures use the web seam’s `WEB_*` codes:
+
+| Code | Meaning |
+| --- | --- |
+| `WEB_PROVIDER_ERROR` | every engine failed; message lists `id: reason; …` |
+| `WEB_ABORTED` | caller aborted mid-search |
+| `WEB_PROVIDER_CONFIGURED_UNAVAILABLE` | configured provider not available |
+| `WEB_PROVIDER_CONFIGURED_MISSING` | configured provider id not registered |
+
+## Privacy and security notes
+
+- **No credentials.** The provider never reads a key, so a leak cannot happen. Engines
+  receive the query, the browser-shaped User-Agent, and nothing else.
+- **Treat queries as public.** Each query is sent to public search engines as an anonymous
+  request; do not search for secrets or PII you would not paste into a public search box.
+- **No fetch provider.** `tool-web` `fetch: false` stays: the model cannot be pointed at
+  arbitrary URLs, so SSRF and unsafe-content surfaces stay closed.
+- **Redirect policy.** All engine fetches use `redirect: "error"` — redirects are treated as
+  failures and advance the chain rather than leak the caller onto an external location.
+- **Challenges are expected.** Startpage, Ecosia, and Google frequently serve bot checks;
+  the parsers treat challenged pages as zero results and the chain advances. See
+  [docs/operations.md](docs/operations.md) for runtime expectations.
+
+## Compatibility
+
+| Component | Supported contract |
+| --- | --- |
+| Node.js | 22.19 or newer |
+| DeepSeek Harness | `0.1.0-rc.6` (`@deepseek-ai/dsh-web`, `@deepseek-ai/cordis` peer range) |
+| Seam | `ctx.web` `WebSearchProvider` (no key, no fetch provider) |
+
+DeepSeek Harness is a developer preview. Upstream seam-contract changes require a new
+package release and contract review.
+
+## Development
+
+```bash
+npm ci
+npm run check
+npm test
+npm run build
+npm pack --dry-run
+```
+
+The default suite runs parser and provider contract tests against fixture HTML (no network).
+For live-network validation of the scrapers against current engine markup, run the opt-in
+real test — it exercises Startpage, DuckDuckGo, and Mojeek for organic results and verifies
+bot-challenged engines (Ecosia/Google) fail forward instead of crashing:
+
+```bash
+DSH_WEB_SEARCH_REAL_E2E=1 npm run test:real
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the release checklist and design constraints, and
+[docs/operations.md](docs/operations.md) for runtime behavior and troubleshooting.
+
+## License and attribution
+
+This package is licensed MIT — the same license as its upstream
+[oh-my-pi](https://github.com/can1357/oh-my-pi). The credential-free engine chain and its
+per-engine scrapers are ported from oh-my-pi (MIT License, © Mario Zechner 2025, © Can
+Bölük 2025-2026); the upstream copyright holders are recorded in LICENSE next to this
+package’s own notice, and the upstream notice text is reproduced in full in
+[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).
+
+This plugin is a separate installable package; the harness remains the property of its own
+project.

package/SECURITY.md

@@ -0,0 +1,25 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please use GitHub’s private security-advisory flow for this repository. Do not open a public
+issue containing credentials, unpublished exploit details, or customer data.
+
+Include the affected version, a minimal reproduction, impact, and any suggested mitigation.
+Rotate any credential that may have been exposed during testing.
+
+## Deployment assumptions
+
+- The plugin never reads, stores, or transmits credentials: searches are anonymous requests
+  to public search engines. There is nothing to leak.
+- Queries are sent verbatim to the configured public engines, so treat a query as public
+  text. Do not search for secrets, tokens, or PII.
+- No fetch provider is mounted (`tool-web` `fetch: false`), so the model cannot be pointed at
+  arbitrary URLs; SSRF surfaces stay closed.
+- All engine fetches use `redirect: "error"`, so a hostile response cannot redirect the
+  provider onto an external location.
+- Parsed snippets and titles are rendered to the model as citations; they are public
+  third-party text and are neither trusted nor executed.
+
+See [docs/operations.md](docs/operations.md) for runtime expectations and troubleshooting.
+

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,44 @@
+# Third-party notices
+
+This package includes code and design derived from
+[oh-my-pi](https://github.com/can1357/oh-my-pi), specifically the credential-free engine
+chain and per-engine scrapers originally at:
+
+- `packages/coding-agent/src/web/search/providers/public.ts`
+- `packages/coding-agent/src/web/search/providers/startpage.ts`
+- `packages/coding-agent/src/web/search/providers/duckduckgo.ts`
+- `packages/coding-agent/src/web/search/providers/ecosia.ts`
+- `packages/coding-agent/src/web/search/providers/google.ts`
+- `packages/coding-agent/src/web/search/providers/mojeek.ts`
+
+The ported portions are adapted to the DeepSeek Harness `ctx.web` seam with sequential
+fail-forward semantics (Startpage first, then DuckDuckGo → Ecosia → Google → Mojeek).
+
+oh-my-pi is distributed under the following MIT License:
+
+```text
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+Copyright (c) 2025-2026 Can Bölük
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+All other code in this package is MIT (see LICENSE).

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# Make the credential-free public search chain the default web-search provider:
+# Startpage first, then DuckDuckGo -> Ecosia -> Google -> Mojeek as sequential
+# fallbacks. The chain needs no API key and no fetch provider. The keyed DeepSeek
+# route (web-search-deepseek) is left untouched, so deployments that explicitly
+# choose their own provider via `web.searchProvider` keep that choice.
+- id: web
+  config:
+    searchProvider: public
+
+- insert:
+    - id: web-search-public
+      name: '@hy-sde-org/dsh-web-search-public'

package/dist/engines/duckduckgo.d.ts

@@ -0,0 +1,18 @@
+/**
+ * DuckDuckGo engine: static HTML endpoint, no credentials, parseable without JS.
+ * @module @hy-sde-org/dsh-web-search-public/engines/duckduckgo
+ */
+import type { WebSearchRequest, WebSearchSource } from '@deepseek-ai/dsh-web';
+import type { PublicEngine, PublicEngineId } from '../types.ts';
+/** A `WebSearchSource` may use `title`/optional fields; built via guarded assignment. */
+export declare class DuckDuckGoEngine implements PublicEngine {
+    private readonly userAgent;
+    readonly id: PublicEngineId;
+    constructor(userAgent: string);
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchSource[]>;
+}
+/** Unwrap DuckDuckGo's `uddg` redirect parameter; other http(s) hrefs pass through. */
+export declare function unwrapDdgHref(href: string): string | undefined;
+/** Parse DuckDuckGo's static HTML results page into sources. Exported for contract tests. */
+export declare function parseDuckDuckGo(html: string, limit: number): WebSearchSource[];
+//# sourceMappingURL=duckduckgo.d.ts.map

package/dist/engines/duckduckgo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duckduckgo.d.ts","sourceRoot":"","sources":["../../src/engines/duckduckgo.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAM/D,yFAAyF;AACzF,qBAAa,gBAAiB,YAAW,YAAY;IAGvC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAFtC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAe;gBAEb,SAAS,EAAE,MAAM;IAExC,MAAM,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;CAU1F;AAED,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO9D;AAED,6FAA6F;AAC7F,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE,CAY9E"}

package/dist/engines/duckduckgo.js

@@ -0,0 +1,77 @@
+/**
+ * DuckDuckGo engine: static HTML endpoint, no credentials, parseable without JS.
+ * @module @hy-sde-org/dsh-web-search-public/engines/duckduckgo
+ */
+import { anchors, cleanText, elementText, elementsByClass, isUsableUrl, stripNoise } from "./html.js";
+import { fetchHtml } from "./http.js";
+const HTML_ENDPOINT = 'https://html.duckduckgo.com/html/';
+/** A `WebSearchSource` may use `title`/optional fields; built via guarded assignment. */
+export class DuckDuckGoEngine {
+    userAgent;
+    id = 'duckduckgo';
+    constructor(userAgent) {
+        this.userAgent = userAgent;
+    }
+    async search(request, signal) {
+        const html = await fetchHtml({
+            url: HTML_ENDPOINT,
+            method: 'POST',
+            body: new URLSearchParams({ q: request.query, kl: 'us-en' }).toString(),
+            userAgent: this.userAgent,
+            signal,
+        });
+        return parseDuckDuckGo(html, request.maxResults ?? 10);
+    }
+}
+/** Unwrap DuckDuckGo's `uddg` redirect parameter; other http(s) hrefs pass through. */
+export function unwrapDdgHref(href) {
+    if (href.startsWith('//duckduckgo.com/l/?uddg=')) {
+        const target = new URL(href, 'https://duckduckgo.com').searchParams.get('uddg');
+        if (target === null)
+            return undefined;
+        return isUsableUrl(target) ? target : undefined;
+    }
+    return isUsableUrl(href) ? href : undefined;
+}
+/** Parse DuckDuckGo's static HTML results page into sources. Exported for contract tests. */
+export function parseDuckDuckGo(html, limit) {
+    const doc = stripNoise(html);
+    const rows = elementsByClass(doc, 'result', 'div');
+    const sources = [];
+    for (let i = 0; i < rows.length && sources.length < limit; i += 1) {
+        const row = rows[i];
+        if (row === undefined)
+            continue;
+        const end = rows[i + 1]?.start ?? doc.length;
+        const source = parseDuckDuckGoRow(doc.slice(row.end, end));
+        if (source !== undefined)
+            sources.push(source);
+    }
+    return sources;
+}
+function parseDuckDuckGoRow(slice) {
+    const titleAnchor = anchors(slice).find(anchor => (anchor.attrs.class ?? '').split(/\s+/).includes('result__a'));
+    if (titleAnchor === undefined)
+        return undefined;
+    // Paid results arrive as `//duckduckgo.com/y.js?...` ad redirects carrying
+    // `ad_provider`/`ad_domain` query params; skip them, keeping only organic rows.
+    if (/^\/\/duckduckgo\.com\/y\.js\?/.test(titleAnchor.href)
+        || /[?&](ad_provider|ad_domain)=/.test(titleAnchor.href))
+        return undefined;
+    const url = unwrapDdgHref(titleAnchor.href);
+    if (url === undefined)
+        return undefined;
+    const title = cleanText(titleAnchor.text);
+    const snippetTag = elementsByClass(slice, 'result__snippet').find(tag => tag.tag === 'a' || tag.tag === 'div');
+    const snippet = snippetTag === undefined ? undefined : elementText(slice, snippetTag);
+    const dateTag = elementsByClass(slice, 'result__timestamp').at(0);
+    const date = dateTag === undefined ? undefined : elementText(slice, dateTag);
+    const iso = date === undefined ? undefined : /^\d{4}-\d{2}-\d{2}/.exec(date.trim())?.[0];
+    return {
+        url,
+        ...(title.length > 0 ? { title } : {}),
+        ...(snippet !== undefined && snippet.length > 0 ? { snippet } : {}),
+        ...(iso !== undefined ? { publishedAt: iso } : {}),
+    };
+}
+//# sourceMappingURL=duckduckgo.js.map

package/dist/engines/duckduckgo.js.map

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

package/dist/engines/ecosia.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Ecosia engine: credential-free Google-indexed results served as static HTML
+ * (browser-backed in friction: may be slower or bot-challenged).
+ * @module @hy-sde-org/dsh-web-search-public/engines/ecosia
+ */
+import type { WebSearchRequest, WebSearchSource } from '@deepseek-ai/dsh-web';
+import type { PublicEngine, PublicEngineId } from '../types.ts';
+export declare class EcosiaEngine implements PublicEngine {
+    private readonly userAgent;
+    readonly id: PublicEngineId;
+    constructor(userAgent: string);
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchSource[]>;
+}
+/** Parse Ecosia's server-rendered result page. Exported for contract tests. */
+export declare function parseEcosia(html: string, limit: number): WebSearchSource[];
+//# sourceMappingURL=ecosia.d.ts.map

package/dist/engines/ecosia.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ecosia.d.ts","sourceRoot":"","sources":["../../src/engines/ecosia.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAM/D,qBAAa,YAAa,YAAW,YAAY;IAGnC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAFtC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAW;gBAET,SAAS,EAAE,MAAM;IAExC,MAAM,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;CAK1F;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE,CAkB1E"}

package/dist/engines/ecosia.js

@@ -0,0 +1,42 @@
+/**
+ * Ecosia engine: credential-free Google-indexed results served as static HTML
+ * (browser-backed in friction: may be slower or bot-challenged).
+ * @module @hy-sde-org/dsh-web-search-public/engines/ecosia
+ */
+import { anchors, dedupeSources, elementText, elementsByClass, isUsableUrl, stripNoise } from "./html.js";
+import { fetchHtml } from "./http.js";
+const SEARCH_URL = 'https://www.ecosia.org/search';
+export class EcosiaEngine {
+    userAgent;
+    id = 'ecosia';
+    constructor(userAgent) {
+        this.userAgent = userAgent;
+    }
+    async search(request, signal) {
+        const url = `${SEARCH_URL}?${new URLSearchParams({ q: request.query, method: 'index' })}`;
+        const html = await fetchHtml({ url, userAgent: this.userAgent, signal });
+        return parseEcosia(html, request.maxResults ?? 10);
+    }
+}
+/** Parse Ecosia's server-rendered result page. Exported for contract tests. */
+export function parseEcosia(html, limit) {
+    const doc = stripNoise(html);
+    const links = anchors(doc)
+        .filter(anchor => isUsableUrl(anchor.href) && /(?:^|\s)result__a(?:$|\s)/.test(anchor.attrs.class ?? ''));
+    const snippetTags = elementsByClass(doc, 'result__quote');
+    const sources = [];
+    for (let i = 0; i < links.length && sources.length < limit; i += 1) {
+        const link = links[i];
+        if (link === undefined)
+            continue;
+        const snippetTag = snippetTags[i];
+        const snippet = snippetTag === undefined ? undefined : elementText(doc, snippetTag);
+        sources.push({
+            url: link.href,
+            ...(link.text.length > 0 ? { title: link.text } : {}),
+            ...(snippet !== undefined && snippet.length > 0 ? { snippet } : {}),
+        });
+    }
+    return dedupeSources(sources);
+}
+//# sourceMappingURL=ecosia.js.map

package/dist/engines/ecosia.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ecosia.js","sourceRoot":"","sources":["../../src/engines/ecosia.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACzG,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAErC,MAAM,UAAU,GAAG,+BAA+B,CAAA;AAElD,MAAM,OAAO,YAAY;IAGM;IAFpB,EAAE,GAAmB,QAAQ,CAAA;IAEtC,YAA6B,SAAiB;QAAjB,cAAS,GAAT,SAAS,CAAQ;IAAG,CAAC;IAElD,KAAK,CAAC,MAAM,CAAC,OAAyB,EAAE,MAAoB;QAC1D,MAAM,GAAG,GAAG,GAAG,UAAU,IAAI,IAAI,eAAe,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAA;QACzF,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAA;QACxE,OAAO,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC,CAAA;IACpD,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,KAAa;IACrD,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,CAAA;IAC5B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC;SACvB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,2BAA2B,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAA;IAC3G,MAAM,WAAW,GAAG,eAAe,CAAC,GAAG,EAAE,eAAe,CAAC,CAAA;IACzD,MAAM,OAAO,GAAsB,EAAE,CAAA;IACrC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;QACrB,IAAI,IAAI,KAAK,SAAS;YAAE,SAAQ;QAChC,MAAM,UAAU,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;QACjC,MAAM,OAAO,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,UAAU,CAAC,CAAA;QACnF,OAAO,CAAC,IAAI,CAAC;YACX,GAAG,EAAE,IAAI,CAAC,IAAI;YACd,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpE,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,aAAa,CAAC,OAAO,CAAC,CAAA;AAC/B,CAAC"}

package/dist/engines/google.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Google engine: credential-free scrape of the classic results page. Google is
+ * the most bot-challenged engine in the chain, so this engine is expected to
+ * frequently advance the chain rather than succeed.
+ * @module @hy-sde-org/dsh-web-search-public/engines/google
+ */
+import type { WebSearchRequest, WebSearchSource } from '@deepseek-ai/dsh-web';
+import type { PublicEngine, PublicEngineId } from '../types.ts';
+export declare class GoogleEngine implements PublicEngine {
+    private readonly userAgent;
+    readonly id: PublicEngineId;
+    constructor(userAgent: string);
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchSource[]>;
+}
+/** Resolve Google's `/url?q=` redirect wrapper; other usable URLs pass through. Exported for tests. */
+export declare function unwrapGoogleHref(href: string): string | undefined;
+/** Parse Google's classic results page. Exported for contract tests. */
+export declare function parseGoogle(html: string, limit: number): WebSearchSource[];
+//# sourceMappingURL=google.d.ts.map

package/dist/engines/google.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google.d.ts","sourceRoot":"","sources":["../../src/engines/google.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAS/D,qBAAa,YAAa,YAAW,YAAY;IAGnC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAFtC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAW;gBAET,SAAS,EAAE,MAAM;IAExC,MAAM,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;CAW1F;AAED,uGAAuG;AACvG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWjE;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE,CAiC1E"}