@plurnk/plurnk-execs-search 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PossumTech Laboratories
+
+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,44 @@
+# @plurnk/plurnk-execs-search
+
+Web search runtime executor for [plurnk-service](https://github.com/plurnk/plurnk-service)'s `exec` scheme. Dispatches an `<<EXEC[search]:pie recipes:EXEC` op to a [SearXNG](https://docs.searxng.org/) instance and returns its native JSON results.
+
+The first non-subprocess `@plurnk/plurnk-execs-*` sibling, built on the [plurnk-execs](https://github.com/plurnk/plurnk-execs) framework.
+
+## Runtime tags
+
+Each tag maps to a SearXNG search category (`categories=`):
+
+| Tag | Glyph | Category |
+|---|---|---|
+| `search` | 🔎 | general |
+| `images` | 🖼 | images |
+| `videos` | 🎬 | videos |
+| `news` | 📰 | news |
+| `map` | 🗺 | map |
+| `music` | 🎵 | music |
+| `it` | 💻 | it |
+| `science` | 🔬 | science |
+| `social` | 💬 | social media |
+| `downloadable` | 📥 | files |
+
+Engine, language, and time-range selection ride the query string via SearXNG's native `!bang` and `:lang` syntax (e.g. `<<EXEC[search]:!gh node streams:EXEC`). External bangs (`!!`) are refused — they redirect rather than return results.
+
+## Configuration (environment)
+
+| Var | Required | Default | Notes |
+|---|---|---|---|
+| `PLURNK_EXECS_SEARCH_SEARXNG_URL` | yes | — | base URL of the SearXNG instance (its `/search` endpoint must allow `format=json`) |
+| `PLURNK_EXECS_SEARCH_LANGUAGE` | no | `en` | |
+| `PLURNK_EXECS_SEARCH_LIMIT` | no | `12` | results kept |
+| `PLURNK_EXECS_SEARCH_TIMEOUT` | no | `10000` | request timeout (ms) |
+| `PLURNK_EXECS_SEARCH_SAFESEARCH` | no | instance default | `0` / `1` / `2` |
+
+## Output
+
+Writes the SearXNG `results` array (sliced to the limit, native shape verbatim) as JSON to the `results` channel. The model reads `exec://<coord>/EXEC#results`.
+
+Failures emit a `TelemetryEvent` (`source: "exec:<tag>"`): `searxng_not_configured`, `searxng_unreachable`, `searxng_timeout`, `searxng_http_<n>`, `external_bang_refused`.
+
+## Tests
+
+`test:lint`, `test:unit`.

package/dist/Search.d.ts

@@ -0,0 +1,7 @@
+import { BaseExecutor } from "@plurnk/plurnk-execs";
+import type { ChannelDecl, ExecArgs, ExecResult } from "@plurnk/plurnk-execs";
+export default class Search extends BaseExecutor {
+    get channels(): Readonly<Record<string, ChannelDecl>>;
+    run({ runtime, command, signal, write, setState, emit }: ExecArgs): Promise<ExecResult>;
+}
+//# sourceMappingURL=Search.d.ts.map

package/dist/Search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Search.d.ts","sourceRoot":"","sources":["../src/Search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAqC9E,MAAM,CAAC,OAAO,OAAO,MAAO,SAAQ,YAAY;IAC5C,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAEpD;IAEK,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;CAiEhG"}

package/dist/Search.js

@@ -0,0 +1,100 @@
+import { BaseExecutor } from "@plurnk/plurnk-execs";
+// Runtime tag → SearXNG `categories=` value. The flat tag set this sibling
+// claims (package.json `plurnk.runtimes[]`) maps 1:1 onto SearXNG's category
+// tabs (`categories_as_tabs` in its settings.yml). `search` is the general
+// default; `social` and `downloadable` are honest renamings of SearXNG's
+// "social media" and "files" categories. Engine / language / time selection
+// rides the query string via SearXNG's native `!bang` / `:lang` syntax.
+const CATEGORY = Object.freeze({
+    search: "general",
+    images: "images",
+    videos: "videos",
+    news: "news",
+    map: "map",
+    music: "music",
+    it: "it",
+    science: "science",
+    social: "social media",
+    downloadable: "files",
+});
+const DEFAULT_LANGUAGE = "en";
+const DEFAULT_LIMIT = 12;
+const DEFAULT_TIMEOUT_MS = 10_000;
+const preview = (q) => (q.length > 60 ? `${q.slice(0, 60)}…` : q);
+// Web search executor (the first non-subprocess runtime). Dispatches a query to
+// a configured SearXNG instance and writes its native JSON results to the
+// `results` channel. Stateless: configuration comes from the environment, read
+// per run.
+//
+//   PLURNK_EXECS_SEARCH_SEARXNG_URL   (required) base URL of the instance
+//   PLURNK_EXECS_SEARCH_LANGUAGE      (default "en")
+//   PLURNK_EXECS_SEARCH_LIMIT         (default 12)   results kept
+//   PLURNK_EXECS_SEARCH_TIMEOUT       (default 10000) ms
+//   PLURNK_EXECS_SEARCH_SAFESEARCH    (optional 0|1|2)
+export default class Search extends BaseExecutor {
+    get channels() {
+        return { results: { mimetype: "application/json" } };
+    }
+    async run({ runtime, command, signal, write, setState, emit }) {
+        const category = CATEGORY[runtime];
+        // A tag we never claimed means the scheme misrouted — a contract
+        // violation, not an expected runtime failure. Fail hard.
+        if (category === undefined)
+            throw new Error(`plurnk-execs-search received unclaimed runtime tag '${runtime}'`);
+        const query = command.trim();
+        const fail = (kind, message, status = 500) => {
+            emit({ source: `exec:${runtime}`, kind, message });
+            setState("results", "errored");
+            return { status };
+        };
+        // External bangs (`!!`) redirect to an upstream site instead of
+        // returning JSON — incompatible with a results executor (SPEC §2.2).
+        if (query.startsWith("!!")) {
+            return fail("external_bang_refused", `external bang refused: "${preview(query)}"`, 400);
+        }
+        const base = process.env.PLURNK_EXECS_SEARCH_SEARXNG_URL;
+        if (!base)
+            return fail("searxng_not_configured", "PLURNK_EXECS_SEARCH_SEARXNG_URL is not set");
+        const language = process.env.PLURNK_EXECS_SEARCH_LANGUAGE || DEFAULT_LANGUAGE;
+        const limit = Number(process.env.PLURNK_EXECS_SEARCH_LIMIT) || DEFAULT_LIMIT;
+        const timeout = Number(process.env.PLURNK_EXECS_SEARCH_TIMEOUT) || DEFAULT_TIMEOUT_MS;
+        const safesearch = process.env.PLURNK_EXECS_SEARCH_SAFESEARCH;
+        const url = new URL("/search", base);
+        url.searchParams.set("q", query);
+        url.searchParams.set("format", "json");
+        url.searchParams.set("categories", category);
+        url.searchParams.set("language", language);
+        if (safesearch)
+            url.searchParams.set("safesearch", safesearch);
+        let response;
+        try {
+            response = await fetch(url, { signal: AbortSignal.any([signal, AbortSignal.timeout(timeout)]) });
+        }
+        catch (err) {
+            // Caller cancellation is normal flow, not telemetry-worthy.
+            if (signal.aborted) {
+                setState("results", "errored");
+                return { status: 499 };
+            }
+            const e = err;
+            if (e.name === "TimeoutError") {
+                return fail("searxng_timeout", `SearXNG timeout after ${timeout}ms — host=${url.host} query="${preview(query)}"`);
+            }
+            // Node's fetch throws a bare "fetch failed" and tucks the real
+            // reason under err.cause — surface it so logs say ENOTFOUND /
+            // ECONNREFUSED / CERT_* rather than nothing actionable.
+            const code = e.cause?.code ?? e.code ?? "UNKNOWN";
+            const detail = e.cause?.message ?? err.message;
+            return fail("searxng_unreachable", `SearXNG fetch failed [${code}] — ${detail}; host=${url.host} query="${preview(query)}"`);
+        }
+        if (!response.ok) {
+            return fail(`searxng_http_${response.status}`, `SearXNG ${response.status} ${response.statusText} — host=${url.host} query="${preview(query)}"`);
+        }
+        const data = await response.json();
+        const results = (data.results ?? []).slice(0, limit);
+        write("results", JSON.stringify(results));
+        setState("results", "closed");
+        return { status: 200 };
+    }
+}
+//# sourceMappingURL=Search.js.map

package/dist/Search.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Search } from "./Search.ts";
+export { default } from "./Search.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { default as Search } from "./Search.js";
+export { default } from "./Search.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC"}

package/package.json

@@ -0,0 +1,64 @@
+{
+    "name": "@plurnk/plurnk-execs-search",
+    "version": "0.1.0",
+    "description": "Web search runtime executor for plurnk-service's exec scheme — dispatches search/news/images/… runtime tags to a SearXNG instance.",
+    "keywords": ["plurnk", "exec", "runtime", "executor", "search", "searxng", "web"],
+    "homepage": "https://github.com/plurnk/plurnk-execs-search#readme",
+    "bugs": {
+        "url": "https://github.com/plurnk/plurnk-execs-search/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/plurnk/plurnk-execs-search.git"
+    },
+    "engines": {
+        "node": ">=25"
+    },
+    "license": "MIT",
+    "author": "@wikitopian",
+    "type": "module",
+    "publishConfig": {
+        "access": "public"
+    },
+    "plurnk": {
+        "kind": "exec",
+        "runtimes": [
+            { "name": "search", "glyph": "🔎" },
+            { "name": "images", "glyph": "🖼" },
+            { "name": "videos", "glyph": "🎬" },
+            { "name": "news", "glyph": "📰" },
+            { "name": "map", "glyph": "🗺" },
+            { "name": "music", "glyph": "🎵" },
+            { "name": "it", "glyph": "💻" },
+            { "name": "science", "glyph": "🔬" },
+            { "name": "social", "glyph": "💬" },
+            { "name": "downloadable", "glyph": "📥" }
+        ]
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist/**/*",
+        "README.md"
+    ],
+    "scripts": {
+        "test:lint": "tsc --noEmit",
+        "test:unit": "node --test src/**/*.test.ts",
+        "test": "npm run test:lint && npm run test:unit",
+        "build:dist": "tsc -p tsconfig.build.json",
+        "build": "npm run build:dist",
+        "prepare": "npm run build"
+    },
+    "dependencies": {
+        "@plurnk/plurnk-execs": "0.2.0"
+    },
+    "devDependencies": {
+        "@types/node": "^25.8.0",
+        "typescript": "^6.0.3"
+    }
+}