@jaco-tech/dsh-web-search-searxng 0.2.0 → 0.2.2

package/README.md

@@ -13,15 +13,33 @@ Registers a `WebSearchProvider` into `ctx.web` so that the existing `web_search`
 npm install @jaco-tech/dsh-web-search-searxng
 ```
 
+Requires DeepSeek Harness 0.2.1-rc.5. The tested DSH dependency set pins
+`@deepseek-ai/dsh-web` and `@deepseek-ai/dsh-settings` exactly at `0.2.1-rc.5`.
+`@deepseek-ai/cordis` is the deliberate exception: like the first-party DSH web plugins,
+this package declares the compatible patch range `~4.0.5`. A consumer lockfile could in
+principle resolve a different 4.0.x cordis patch and create a second framework copy; this
+plugin's one-shot install is verified against cordis 4.0.5. Every DSH bump therefore needs
+a release of this package with its framework peers re-pinned (`test/peer-pins.test.mjs`
+enforces their presence and pin form). Use 0.1.x of this plugin with DSH 0.1.x.
+
 ## Configure
 
-Add to your DSH profile's `cordis.patch.yml`:
+### 1. Install the package
+
+```bash
+npm install @jaco-tech/dsh-web-search-searxng
+```
+
+### 2. Add it to your DSH profile
+
+Edit `~/.dsh/profiles/web/cordis.patch.yml` (create it if it doesn't exist) and add:
 
 ```yaml
 - insert:
     - id: web-search-searxng
       name: '@jaco-tech/dsh-web-search-searxng'
       config:
+        # Required: point at your SearXNG instance
         baseURL: 'http://your-searxng-instance:8888'
         # Optional filters:
         language: 'en'
@@ -29,7 +47,7 @@ Add to your DSH profile's `cordis.patch.yml`:
         timeRange: ''
 ```
 
-Optionally pin `ctx.web` to use this provider explicitly:
+If you have multiple search providers registered, pin `ctx.web` to use this one:
 
 ```yaml
 - replace:
@@ -38,6 +56,22 @@ Optionally pin `ctx.web` to use this provider explicitly:
         searchProvider: searxng
 ```
 
+### 3. Restart DSH
+
+Stop your running `dsh` process and start it again:
+
+```bash
+npx @deepseek-ai/dsh web
+```
+
+The plugin will be loaded automatically. The `web_search` tool in your agent will now use your SearXNG instance.
+
+### 4. (Optional) Configure via the Web UI
+
+Once DSH is running, go to **Settings → Plugins** in the Web UI. You'll see a "web-search-searxng" card where you can edit the `baseURL` and filter settings without editing YAML files.
+
+Every config field is volatile (DSH 0.2 settings model): a change is committed into the running plugin and the next search reads it, without reloading the plugin.
+
 ## How it works
 
 This is a [Cordis](https://github.com/cordiverse/cordis) plugin that implements the `WebSearchProvider` interface from `@deepseek-ai/dsh-web`:
@@ -49,7 +83,7 @@ export const inject = ["web"]
 export function apply(ctx, config) {
   ctx.web.registerSearchProvider({
     id: "searxng",
-    available() { /* URL.canParse(config.baseURL) */ },
+    available() { /* URL.canParse(config.baseURL.get()) */ },
     async search(request, signal) {
       // GET /search?q=<query>&format=json
       // maps response to WebSearchResult
@@ -86,8 +120,27 @@ Requires the `NPM_TOKEN` secret to be set in the repository.
 ```bash
 npm install
 npm run build
+npm test      # hermetic: loads lib/ into a real cordis Context next to dsh-web's ctx.web
 ```
 
+Verify a one-shot scratch install of DSH plus this package's `npm pack` tarball:
+
+```bash
+repo=$PWD
+scratch=$(mktemp -d)
+tarball=$(npm pack --pack-destination "$scratch" --silent)
+printf '%s\n' \
+  "{\"private\":true,\"dependencies\":{\"@deepseek-ai/dsh\":\"0.2.1-rc.5\",\"@jaco-tech/dsh-web-search-searxng\":\"file:./$tarball\"}}" \
+  > "$scratch/package.json"
+(cd "$scratch" && npm install --no-audit --no-fund)
+node "$repo/test/installed-tree-identity.mjs" "$scratch"
+```
+
+The final check is hermetic (it only reads the installed tree). It requires exactly one
+installed copy each of `@deepseek-ai/dsh-web`,
+`@deepseek-ai/dsh-settings`, and `@deepseek-ai/cordis`, and requires
+`@deepseek-ai/cordis-plugin-group` to be present.
+
 ## License
 
 MIT

package/lib/index.js

@@ -1,6 +1,5 @@
 import z from "@deepseek-ai/schemastery";
 import { WebError } from "@deepseek-ai/dsh-web";
-import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 //#endregion
 //#region provider
 /**
@@ -55,6 +54,11 @@ function mapSearXngResponse(body, maxResults) {
 class SearXngSearchProvider {
     resolveOptions;
     id = SEARXNG_PROVIDER_ID;
+    /**
+     * @param resolveOptions - the options for the NEXT operation, snapshotted
+     * once at each operation's entry, so a settings change applies to the next
+     * search without re-registering the provider.
+     */
     constructor(resolveOptions) {
         this.resolveOptions = resolveOptions;
     }
@@ -138,20 +142,18 @@ 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(""),
+    baseURL: z.string().required().volatile(),
+    language: z.string().default("").volatile(),
+    categories: z.string().default("").volatile(),
+    timeRange: z.string().default("").volatile(),
 });
-/** Settings namespace for the DSH Web UI (Settings → Plugins). */
-const WEB_SEARCH_SEARXNG_SETTINGS_NAMESPACE = settingsNamespace("web-search-searxng");
 function apply(ctx, config) {
-    let current = () => config;
-    installSettingsSection(ctx, WEB_SEARCH_SEARXNG_SETTINGS_NAMESPACE, Config, config, {
-        setSource: (source) => { current = source; },
-        onChange: () => { },
-    });
-    ctx.web.registerSearchProvider(new SearXngSearchProvider(() => current()));
+    ctx.web.registerSearchProvider(new SearXngSearchProvider(() => ({
+        baseURL: config.baseURL.get(),
+        language: config.language.get(),
+        categories: config.categories.get(),
+        timeRange: config.timeRange.get(),
+    })));
 }
 //#endregion
 //#region helpers
@@ -165,5 +167,4 @@ function aborted(signal, 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

@@ -1,5 +1,5 @@
 import z from "@deepseek-ai/schemastery";
-import type { Context } from "@deepseek-ai/cordis";
+import type { Context, Volatile } from "@deepseek-ai/cordis";
 import type { WebSearchProvider, WebSearchRequest, WebSearchResult } from "@deepseek-ai/dsh-web";
 interface SearXngResultItem {
     url: string;
@@ -37,9 +37,14 @@ declare function mapSearXngResponse(body: SearXngResponseBody, maxResults?: numb
  * seam's normalized `WebSearchResult`. No auth, no API key, no model calls.
  */
 declare class SearXngSearchProvider implements WebSearchProvider {
-    readonly resolveOptions: () => Config;
+    readonly resolveOptions: () => SearXngOptions;
     readonly id = "searxng";
-    constructor(resolveOptions: () => Config);
+    /**
+     * @param resolveOptions - the options for the NEXT operation, snapshotted
+     * once at each operation's entry, so a settings change applies to the next
+     * search without re-registering the provider.
+     */
+    constructor(resolveOptions: () => SearXngOptions);
     available(): boolean;
     search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
 }
@@ -64,19 +69,43 @@ declare class SearXngSearchProvider implements WebSearchProvider {
 declare const name = "web-search-searxng";
 /** The web seam this provider registers into. */
 declare const inject: string[];
+/** One search's resolved options. */
+interface SearXngOptions {
+    /** 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;
+}
 /**
  * Plugin configuration. `baseURL` is required (point at your SearXNG instance).
+ * Every field is volatile: DSH commits a settings change into the running
+ * plugin, and the next search reads it.
  */
 interface Config {
     /** Base URL of the SearXNG instance (without trailing /search). */
-    baseURL: string;
+    baseURL: Volatile<string>;
     /** Language filter (e.g. "en", "nl", "fr"). Empty = no filter. */
-    language?: string;
+    language: Volatile<string>;
     /** Categories filter (e.g. "general", "news", "images"). Empty = no filter. */
-    categories?: string;
+    categories: Volatile<string>;
     /** Time range filter (e.g. "day", "week", "month", "year"). Empty = no filter. */
-    timeRange?: string;
+    timeRange: Volatile<string>;
 }
-declare const Config: z<Config>;
+declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    baseURL: z<string, string, "volatile-defined">;
+    language: z<string, string, "volatile-defined">;
+    categories: z<string, string, "volatile-defined">;
+    timeRange: z<string, string, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    baseURL: z<string, string, "volatile-defined">;
+    language: z<string, string, "volatile-defined">;
+    categories: z<string, string, "volatile-defined">;
+    timeRange: z<string, string, "volatile-defined">;
+}>>, "plain">;
 declare function apply(ctx: Context, config: Config): void;
+export type { SearXngOptions };
 export { Config, SEARXNG_PROVIDER_ID, SearXngSearchProvider, apply, inject, name, mapSearXngResponse };

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.2.0",
+  "version": "0.2.2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,21 +32,22 @@
     "cordis-plugin"
   ],
   "peerDependencies": {
-    "@deepseek-ai/dsh-web": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.7",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-web": "0.2.1-rc.5",
+    "@deepseek-ai/cordis": "~4.0.5"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/schemastery": "~3.18.5"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-web": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.7",
-    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-web": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-settings": "0.2.1-rc.5",
+    "@deepseek-ai/cordis": "~4.0.5",
     "typescript": "^5.7.0"
   },
   "scripts": {
     "build": "tsc",
+    "test": "npm run build && node --test test/peer-pins.test.mjs test/smoke.test.mjs",
     "prepublishOnly": "tsc"
   }
-}
+}