@plurnk/plurnk-execs-jq 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,31 @@
+# @plurnk/plurnk-execs-jq
+
+`jq` runtime executor for [plurnk-service](https://github.com/plurnk/plurnk-service)'s `exec` scheme. Drives `EXEC[jq]` by shelling the system `jq` binary to filter/transform JSON — no third-party JSON-filter library.
+
+A `@plurnk/plurnk-execs-*` sibling built on the [plurnk-execs](https://github.com/plurnk/plurnk-execs) framework.
+
+## Invocation model
+
+**body = the jq program** (defaults to `.` if empty) · **target = optional data source** — present → jq reads it; **absent → `-n` (null input)** so the body is self-contained.
+
+| EXEC | runs | does |
+|---|---|---|
+| `<<EXEC[jq]:{"a":1}:EXEC` | `jq -n '{"a":1}'` | construct / validate inline JSON |
+| `<<EXEC[jq]:[1,2,3] \| add:EXEC` | `jq -n '[1,2,3] \| add'` | pure compute, no data |
+| `<<EXEC[jq](data.json):.users[].name:EXEC` | `jq '.users[].name' data.json` | filter a file |
+| `<<EXEC[jq](data.json):EXEC` | `jq '.' data.json` | empty body → identity (pretty-print) |
+| `<<EXEC[jq](exec://…/EXEC#results):.items[]:EXEC` | filter a **prior op's output** | once the service resolves the scheme target ([plurnk-service#201](https://github.com/plurnk/plurnk-service/issues/201)) |
+
+Output → the `results` channel (`application/json`).
+
+## Effect & availability
+
+- **`effect`** — inline/`-n` → `pure`; a file-path data source → `read` (filesystem). Both **auto-run** (jq is a pure filter — no host writes or exec).
+- **`probe`** — `jq` on PATH (`jq --version`).
+- **Errors** emit a `TelemetryEvent` (`source: "exec:jq"`): `jq_error` (program/parse failure), `jq_spawn_failed`.
+
+jq is a leaf process, so cancellation is a plain signal kill — no process-group handling needed.
+
+## Tests
+
+`test:lint`, `test:unit`. jq-dependent tests auto-skip where `jq` is absent.

package/dist/Jq.d.ts

@@ -0,0 +1,9 @@
+import { BaseExecutor } from "@plurnk/plurnk-execs";
+import type { ChannelDecl, Effect, ExecArgs, ExecResult, RuntimeAvailability } from "@plurnk/plurnk-execs";
+export default class Jq extends BaseExecutor {
+    get channels(): Readonly<Record<string, ChannelDecl>>;
+    effect(target: string | null): Effect;
+    probe(): Promise<RuntimeAvailability>;
+    run({ command, cwd, signal, write, setState, emit }: ExecArgs): Promise<ExecResult>;
+}
+//# sourceMappingURL=Jq.d.ts.map

package/dist/Jq.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Jq.d.ts","sourceRoot":"","sources":["../src/Jq.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAc3G,MAAM,CAAC,OAAO,OAAO,EAAG,SAAQ,YAAY;IACxC,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAEpD;IAGQ,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM;IAI/B,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAY9C,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;CA+B5F"}

package/dist/Jq.js

@@ -0,0 +1,75 @@
+import { spawn } from "node:child_process";
+import { BaseExecutor } from "@plurnk/plurnk-execs";
+// jq executor — shells the system `jq` binary (no third-party JSON-filter lib).
+// Invocation model:
+//   body = the jq program (defaults to `.` identity if empty)
+//   target = optional data source; present → jq reads that file; absent → `-n`
+//            (null input) so the body is self-contained.
+// So `EXEC[jq](data.json):.users[].name` filters a file, `EXEC[jq]:[1,2,3]|add`
+// computes inline, `EXEC[jq](exec://…):.items[]` filters a prior op's output once
+// the service resolves the scheme target to a path (plurnk-service#201).
+//
+// jq is a leaf process (no shell, no grandchildren), so a plain signal-based
+// spawn is sufficient — no process-group machinery needed. It's a pure filter
+// (no host writes / exec), so `effect` is `pure`/`read` — always auto-run.
+export default class Jq extends BaseExecutor {
+    get channels() {
+        return { results: { mimetype: "application/json" } };
+    }
+    // Inline/`-n` → pure; a file-path data source → read (filesystem). Both auto-run.
+    effect(target) {
+        return target ? "read" : "pure";
+    }
+    async probe() {
+        return new Promise((resolve) => {
+            let out = "";
+            const child = spawn("jq", ["--version"], { signal: AbortSignal.timeout(3000) });
+            child.stdout?.on("data", (c) => { out += c.toString("utf8"); });
+            child.on("error", () => resolve({ available: false, detail: "jq not on PATH" }));
+            child.on("close", (code) => resolve(code === 0
+                ? { available: true, detail: out.trim() || "jq" }
+                : { available: false, detail: `jq --version exited ${code}` }));
+        });
+    }
+    async run({ command, cwd, signal, write, setState, emit }) {
+        const program = command.trim() || ".";
+        const path = cwd && cwd.length > 0 ? cwd : null;
+        // Target present → jq reads the file; absent → -n, the program stands alone.
+        const args = path !== null ? [program, path] : ["-n", program];
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (result, state) => {
+                if (settled)
+                    return;
+                settled = true;
+                setState("results", state);
+                resolve(result);
+            };
+            let err = "";
+            const child = spawn("jq", args, { signal });
+            child.stdout?.on("data", (c) => write("results", c.toString("utf8")));
+            child.stderr?.on("data", (c) => { err += c.toString("utf8"); });
+            child.on("error", (e) => {
+                if (e.code === "ABORT_ERR") {
+                    finish({ status: 499 }, "errored");
+                    return;
+                }
+                emit({ source: "exec:jq", kind: "jq_spawn_failed", message: e.message });
+                finish({ status: 500 }, "errored");
+            });
+            child.on("close", (code) => {
+                if (signal.aborted) {
+                    finish({ status: 499 }, "errored");
+                    return;
+                }
+                if (code === 0) {
+                    finish({ status: 200 }, "closed");
+                    return;
+                }
+                emit({ source: "exec:jq", kind: "jq_error", message: err.trim() || `jq exited ${code}` });
+                finish({ status: 500 }, "errored");
+            });
+        });
+    }
+}
+//# sourceMappingURL=Jq.js.map

package/dist/Jq.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Jq } from "./Jq.ts";
+export { default } from "./Jq.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,EAAE,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { default as Jq } from "./Jq.js";
+export { default } from "./Jq.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,EAAE,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+    "name": "@plurnk/plurnk-execs-jq",
+    "version": "0.1.0",
+    "description": "jq runtime executor for plurnk-service's exec scheme — shells the system jq binary to filter/transform JSON for EXEC[jq].",
+    "keywords": ["plurnk", "exec", "runtime", "executor", "jq", "json", "filter"],
+    "homepage": "https://github.com/plurnk/plurnk-execs-jq#readme",
+    "bugs": {
+        "url": "https://github.com/plurnk/plurnk-execs-jq/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/plurnk/plurnk-execs-jq.git"
+    },
+    "engines": {
+        "node": ">=25"
+    },
+    "license": "MIT",
+    "author": "@wikitopian",
+    "type": "module",
+    "publishConfig": {
+        "access": "public"
+    },
+    "plurnk": {
+        "kind": "exec",
+        "runtimes": [
+            { "name": "jq", "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.4.1"
+    },
+    "devDependencies": {
+        "@types/node": "^25.8.0",
+        "typescript": "^6.0.3"
+    }
+}