@jaco-tech/dsh-web-search-searxng 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT
+
+Copyright (c) 2026 Jaco
+
+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,95 @@
+# dsh-web-search-searxng
+
+[![dsh-plugin](https://img.shields.io/badge/dsh-plugin-blue)](https://github.com/topics/dsh-plugin)
+[![CI/CD](https://github.com/jaco-tech/dsh-web-search-searxng/actions/workflows/ci.yml/badge.svg)](https://github.com/jaco-tech/dsh-web-search-searxng/actions/workflows/ci.yml)
+
+SearXNG-backed search provider plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
+
+Registers a `WebSearchProvider` into `ctx.web` so that the existing `web_search` model tool routes through your [SearXNG](https://github.com/searxng/searxng) instance. No auth, no API key, no model calls — just a plain HTTP GET against SearXNG's JSON endpoint.
+
+## Status
+
+⚠️ **Not yet published to npm.** The CI/CD workflow builds on every push and publishes automatically when a `v*` tag is pushed. Once the first release is cut:
+
+```bash
+npm install @jaco-tech/dsh-web-search-searxng
+```
+
+## Configure
+
+Add to your DSH profile's `cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: web-search-searxng
+      name: '@jaco-tech/dsh-web-search-searxng'
+      config:
+        baseURL: 'http://your-searxng-instance:8888'
+        # Optional filters:
+        language: 'en'
+        categories: 'general'
+        timeRange: ''
+```
+
+Optionally pin `ctx.web` to use this provider explicitly:
+
+```yaml
+- replace:
+    - id: web
+      config:
+        searchProvider: searxng
+```
+
+## How it works
+
+This is a [Cordis](https://github.com/cordiverse/cordis) plugin that implements the `WebSearchProvider` interface from `@deepseek-ai/dsh-web`:
+
+```typescript
+export const name = "web-search-searxng"
+export const inject = ["web"]
+
+export function apply(ctx, config) {
+  ctx.web.registerSearchProvider({
+    id: "searxng",
+    available() { /* URL.canParse(config.baseURL) */ },
+    async search(request, signal) {
+      // GET /search?q=<query>&format=json
+      // maps response to WebSearchResult
+    }
+  })
+}
+```
+
+The existing `@deepseek-ai/dsh-tool-web` consumer calls `ctx.web.search()` — your SearXNG instance serves the results automatically.
+
+## Provider interface
+
+| Method | Behavior |
+|---|---|
+| `available()` | Returns `true` when `baseURL` is a valid URL |
+| `search(request, signal?)` | `GET /search` with `q`, `format=json`, optional `language`/`categories`/`time_range` params. Dedupes results by URL. Surfaces `answers` and `infoboxes` as provider-generated answer text. |
+
+## Upstream
+
+This plugin communicates with [SearXNG](https://github.com/searxng/searxng) via its JSON API (`/search?format=json`). SearXNG is a free internet metasearch engine which aggregates results from more than 70 search services. You need a running SearXNG instance to use this plugin.
+
+## Release process
+
+```bash
+# Tag and push — the CI workflow builds and publishes to npm automatically
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+Requires the `NPM_TOKEN` secret to be set in the repository.
+
+## Development
+
+```bash
+npm install
+npm run build
+```
+
+## License
+
+MIT

package/lib/index.js

@@ -0,0 +1,162 @@
+import z from "@deepseek-ai/schemastery";
+import { WebError } from "@deepseek-ai/dsh-web";
+//#endregion
+//#region provider
+/**
+ * Stable id this search provider registers under.
+ */
+const SEARXNG_PROVIDER_ID = "searxng";
+/**
+ * Project one SearXNG result item to a normalized source, omitting absent
+ * optional fields.
+ */
+function projectSource(item) {
+    return {
+        url: item.url,
+        ...(item.title != null && item.title.length > 0) ? { title: item.title } : {},
+        ...(item.content != null && item.content.length > 0) ? { snippet: item.content } : {},
+        ...(item.publishedDate != null && item.publishedDate.length > 0) ? { publishedAt: item.publishedDate } : {},
+    };
+}
+/**
+ * Map a SearXNG JSON response to the seam's normalized `WebSearchResult`.
+ * Dedupes by URL (SearXNG may return the same URL from multiple engines).
+ */
+function mapSearXngResponse(body, maxResults) {
+    const seen = new Set();
+    const sources = [];
+    const items = body.results ?? [];
+    for (const item of items) {
+        if (!item.url || item.url.length === 0 || seen.has(item.url))
+            continue;
+        seen.add(item.url);
+        sources.push(projectSource(item));
+    }
+    const truncated = maxResults !== void 0 && sources.length > maxResults;
+    if (truncated)
+        sources.length = maxResults;
+    // SearXNG may return an answer or infobox — surface as provider-generated
+    // answer text.
+    let content;
+    if (body.answers != null && body.answers.length > 0) {
+        content = body.answers.join("\n");
+    }
+    else if (body.infoboxes != null && body.infoboxes.length > 0) {
+        content = body.infoboxes.map((infobox) => infobox.content ?? infobox.infobox ?? "").filter(Boolean).join("\n\n");
+    }
+    return { ...content !== void 0 ? { content } : {}, sources, truncated };
+}
+/**
+ * The SearXNG-backed search provider. Every operation issues a plain GET
+ * against the instance's JSON endpoint and maps the response directly to the
+ * seam's normalized `WebSearchResult`. No auth, no API key, no model calls.
+ */
+class SearXngSearchProvider {
+    resolveOptions;
+    id = SEARXNG_PROVIDER_ID;
+    constructor(resolveOptions) {
+        this.resolveOptions = resolveOptions;
+    }
+    available() {
+        const options = this.resolveOptions();
+        return URL.canParse(options.baseURL);
+    }
+    async search(request, signal) {
+        const options = this.resolveOptions();
+        throwIfAborted(signal);
+        const url = new URL(`${options.baseURL}/search`);
+        url.searchParams.set("q", request.query);
+        url.searchParams.set("format", "json");
+        if (options.language)
+            url.searchParams.set("language", options.language);
+        if (options.categories)
+            url.searchParams.set("categories", options.categories);
+        if (options.timeRange)
+            url.searchParams.set("time_range", options.timeRange);
+        url.searchParams.set("pageno", "1");
+        throwIfAborted(signal);
+        let response;
+        try {
+            response = await fetch(url.toString(), {
+                method: "GET",
+                headers: {
+                    accept: "application/json",
+                    "user-agent": "deepseek-harness/0.0.1",
+                },
+                ...signal !== void 0 ? { signal } : {},
+            });
+        }
+        catch (error) {
+            if (signal?.aborted === true || isAbortError(error))
+                throw aborted(signal, error);
+            throw new WebError(`SearXNG search request failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+        }
+        if (!response.ok) {
+            let message = `SearXNG API error (HTTP ${response.status})`;
+            try {
+                const parsed = (await response.json());
+                if (parsed.message != null && parsed.message.length > 0)
+                    message = parsed.message;
+            }
+            catch { /* ignore parse failure on error body */ }
+            throw new WebError(message, "WEB_PROVIDER_ERROR");
+        }
+        try {
+            return mapSearXngResponse((await response.json()), request.maxResults);
+        }
+        catch (error) {
+            if (signal?.aborted === true || isAbortError(error))
+                throw aborted(signal, error);
+            if (error instanceof WebError)
+                throw error;
+            throw new WebError(`SearXNG returned an unprocessable response: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+        }
+    }
+}
+//#endregion
+//#region plugin
+/**
+ * Register a SearXNG-backed search provider in `ctx.web`. No auth, no API
+ * key — just point `baseURL` at your SearXNG instance.
+ *
+ * ## Usage
+ *
+ * ```yaml
+ * # cordis.patch.yml
+ * - insert:
+ *     - id: web-search-searxng
+ *       name: '@jaco-tech/dsh-web-search-searxng'
+ *       config:
+ *         baseURL: 'http://your-searxng-instance:8888'
+ *         language: 'en'
+ * ```
+ * @module @jaco-tech/dsh-web-search-searxng
+ */
+/** Cordis plugin name used by loader diagnostics. */
+const name = "web-search-searxng";
+/** The web seam this provider registers into. */
+const inject = ["web"];
+const Config = z.object({
+    baseURL: z.string().required(),
+    language: z.string().default(""),
+    categories: z.string().default(""),
+    timeRange: z.string().default(""),
+});
+function apply(ctx, config) {
+    const current = () => config;
+    ctx.web.registerSearchProvider(new SearXngSearchProvider(() => current()));
+}
+//#endregion
+//#region helpers
+function throwIfAborted(signal) {
+    if (signal?.aborted === true)
+        throw aborted(signal);
+}
+function aborted(signal, fallback) {
+    return new WebError("SearXNG search aborted", "WEB_ABORTED", { cause: signal?.aborted === true ? signal.reason : fallback });
+}
+function isAbortError(error) {
+    return error instanceof DOMException && error.name === "AbortError";
+}
+//#endregion
+export { Config, SEARXNG_PROVIDER_ID, SearXngSearchProvider, apply, inject, name, mapSearXngResponse };

package/lib/types/index.d.ts

@@ -0,0 +1,82 @@
+import z from "@deepseek-ai/schemastery";
+import type { Context } from "@deepseek-ai/cordis";
+import type { WebSearchProvider, WebSearchRequest, WebSearchResult } from "@deepseek-ai/dsh-web";
+interface SearXngResultItem {
+    url: string;
+    title?: string | null;
+    content?: string | null;
+    publishedDate?: string | null;
+    engine?: string;
+    category?: string;
+    score?: number;
+}
+interface SearXngResponseBody {
+    query: string;
+    results?: SearXngResultItem[];
+    answers?: string[];
+    infoboxes?: Array<{
+        content?: string;
+        infobox?: string;
+        url?: string;
+    }>;
+    suggestions?: string[];
+    unresponsive_engines?: string[];
+}
+/**
+ * Stable id this search provider registers under.
+ */
+declare const SEARXNG_PROVIDER_ID = "searxng";
+/**
+ * Map a SearXNG JSON response to the seam's normalized `WebSearchResult`.
+ * Dedupes by URL (SearXNG may return the same URL from multiple engines).
+ */
+declare function mapSearXngResponse(body: SearXngResponseBody, maxResults?: number): WebSearchResult;
+/**
+ * The SearXNG-backed search provider. Every operation issues a plain GET
+ * against the instance's JSON endpoint and maps the response directly to the
+ * seam's normalized `WebSearchResult`. No auth, no API key, no model calls.
+ */
+declare class SearXngSearchProvider implements WebSearchProvider {
+    readonly resolveOptions: () => Config;
+    readonly id = "searxng";
+    constructor(resolveOptions: () => Config);
+    available(): boolean;
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+}
+/**
+ * Register a SearXNG-backed search provider in `ctx.web`. No auth, no API
+ * key — just point `baseURL` at your SearXNG instance.
+ *
+ * ## Usage
+ *
+ * ```yaml
+ * # cordis.patch.yml
+ * - insert:
+ *     - id: web-search-searxng
+ *       name: '@jaco-tech/dsh-web-search-searxng'
+ *       config:
+ *         baseURL: 'http://your-searxng-instance:8888'
+ *         language: 'en'
+ * ```
+ * @module @jaco-tech/dsh-web-search-searxng
+ */
+/** Cordis plugin name used by loader diagnostics. */
+declare const name = "web-search-searxng";
+/** The web seam this provider registers into. */
+declare const inject: string[];
+/**
+ * Plugin configuration. `baseURL` is required (point at your SearXNG instance).
+ */
+interface Config {
+    /** Base URL of the SearXNG instance (without trailing /search). */
+    baseURL: string;
+    /** Language filter (e.g. "en", "nl", "fr"). Empty = no filter. */
+    language?: string;
+    /** Categories filter (e.g. "general", "news", "images"). Empty = no filter. */
+    categories?: string;
+    /** Time range filter (e.g. "day", "week", "month", "year"). Empty = no filter. */
+    timeRange?: string;
+}
+declare const Config: z<Config>;
+declare function apply(ctx: Context, config: Config): void;
+export { Config, SEARXNG_PROVIDER_ID, SearXngSearchProvider, apply, inject, name, mapSearXngResponse };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@jaco-tech/dsh-web-search-searxng",
+  "description": "SearXNG-backed search provider for the DeepSeek Harness web capability seam (ctx.web). No auth, no API key.",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jaco-tech/dsh-web-search-searxng.git"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "searxng",
+    "web-search",
+    "cordis-plugin"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/dsh-web": "^0.1.0-rc.7",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-web": "^0.1.0-rc.7",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  }
+}