@plurnk/plurnk-execs 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,19 @@
+# plurnk-execs
+
+Framework + contract for `@plurnk/plurnk-execs-*` runtime executor packages. Consumed by [plurnk-service](https://github.com/plurnk/plurnk-service)'s `exec` scheme for EXEC op dispatch.
+
+## Documentation
+
+- [`SPEC.md`](./SPEC.md) — author-facing contract.
+- Constellation: [plurnk-grammar](https://github.com/plurnk/plurnk-grammar) (EXEC AST), [plurnk-providers](https://github.com/plurnk/plurnk-providers), [plurnk-schemes](https://github.com/plurnk/plurnk-schemes), [plurnk-mimetypes](https://github.com/plurnk/plurnk-mimetypes).
+
+## Exports
+
+- `SpawnArgs`, `RuntimeResolver` — types.
+- `KNOWN_RUNTIMES` — read-only set of v0 hardcoded runtime tags.
+- `isKnownRuntime(runtime)` — predicate.
+- `resolveRuntime(runtime, command)` — runtime tag + command → `SpawnArgs` for `node:child_process.spawn`.
+
+## Tests
+
+`test:lint`, `test:unit`.

package/SPEC.md

@@ -0,0 +1,77 @@
+# plurnk-execs — Specification
+
+Contract for `@plurnk/plurnk-execs-*` sibling packages — runtime executors that plurnk-service's `exec://` scheme dispatches to. Audience: implementer of a runtime executor. Consumer: [plurnk-service](https://github.com/plurnk/plurnk-service) (SPEC.md §6.8, §10).
+
+## §1 Role
+
+A runtime executor handles one or more EXEC `runtime` slot values. Today plurnk-service's `Exec` scheme hardcodes the runtime → spawn-args mapping for shell / node / python; this repo exports the same logic as `resolveRuntime`. The forward-spec is plugin discovery (one runtime per sibling); v0 ships the hardcoded path.
+
+## §2 v0 surface
+
+`resolveRuntime(runtime: string, command: string) → SpawnArgs`:
+
+```ts
+interface SpawnArgs {
+    cmd: string;
+    args: string[];
+    useShell: boolean;
+}
+```
+
+Maps:
+
+| Runtime | Spawn |
+|---|---|
+| `""` / `"sh"` / `"bash"` | `{ cmd: command, args: [], useShell: true }` |
+| `"node"` | `{ cmd: "node", args: ["-e", command], useShell: false }` |
+| `"python"` / `"python3"` | `{ cmd: "python3", args: ["-c", command], useShell: false }` |
+| any other | `{ cmd: runtime, args: ["-c", command], useShell: false }` (conservative fallback) |
+
+`resolveRuntime` never throws. Consumers gate unknown runtimes with `isKnownRuntime(runtime)` and return 501 from the scheme before invoking.
+
+`KNOWN_RUNTIMES` is the v0 hardcoded set; equivalent to the union of mapped runtimes above except the conservative fallback.
+
+## §3 Forward-spec — plugin discovery
+
+The full constellation pattern (mirroring `plurnk-mimetypes`):
+
+```json
+{
+    "name": "@plurnk/plurnk-execs-<runtime>",
+    "plurnk": {
+        "kind": "exec",
+        "runtimes": [
+            { "name": "sh", "glyph": "🐚" },
+            { "name": "bash", "glyph": "🐚" }
+        ]
+    }
+}
+```
+
+Each sibling registers one or more runtime tags. Plurnk-service scans `node_modules/@plurnk/*` at boot, finds `plurnk.kind === "exec"` packages, registers their handlers. Collision on runtime name: fail-hard.
+
+Each runtime exports a `BaseExecutor` subclass (or equivalent) with `run(args) → Promise<ExecResult>`. Args shape, result shape, AbortSignal handling — all settle as the first sub-siblings ship (`plurnk-execs-sh` would be canonical).
+
+Sub-siblings expected: `plurnk-execs-sh` (default subprocess), `plurnk-execs-node`, `plurnk-execs-python`, `plurnk-execs-search` (web search).
+
+## §4 Consumer surface (plurnk-service today)
+
+The `exec` scheme in plurnk-service:
+
+1. Calls `isKnownRuntime(runtime)` — returns 501 if false.
+2. Calls `resolveRuntime(runtime, command)` to get `SpawnArgs`.
+3. Passes args to `node:child_process.spawn` and manages the subprocess lifecycle (channels, AbortController, subscription registry, wake-on-completion).
+
+Steps 1–2 are this repo's surface. Step 3 stays in the `exec` scheme. The plug-in discovery future (§3) will absorb step 3's invocation into the executor interface, but for v0 the scheme owns the spawn/streaming machinery and consumes this repo only for the runtime-tag translation.
+
+## §5 Forbidden (for future siblings)
+
+| ❌ |
+|---|
+| Database access |
+| Imports from `@plurnk/plurnk-service/*` |
+| Mutating arguments |
+| Holding state across `run` calls beyond config |
+| Reading runtime output via `console.*` |
+| Ignoring cancellation signals |
+| Spawning processes outside the runtime's domain (e.g. an HTTP runtime spawning subprocesses) |

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { SpawnArgs, RuntimeResolver } from "./types.ts";
+export { KNOWN_RUNTIMES, isKnownRuntime, resolveRuntime } from "./runtime.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,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { KNOWN_RUNTIMES, isKnownRuntime, resolveRuntime } from "./runtime.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":"AACA,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,5 @@
+import type { SpawnArgs } from "./types.ts";
+export declare const KNOWN_RUNTIMES: ReadonlySet<string>;
+export declare const isKnownRuntime: (runtime: string) => boolean;
+export declare const resolveRuntime: (runtime: string, command: string) => SpawnArgs;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAE7C,CAAC;AAEH,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,KAAG,OAAsC,CAAC;AAExF,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,EAAE,SAAS,MAAM,KAAG,SAcjE,CAAC"}

package/dist/runtime.js

@@ -0,0 +1,25 @@
+// Runtime tag → spawn-args dispatch. Hardcoded v0 multiplexer; plugin
+// discovery (one runtime per `@plurnk/plurnk-execs-*` sibling) is the
+// forward-spec path documented in SPEC.md.
+// Runtimes plurnk-service's `Exec` scheme accepts at v0. Unknown runtimes
+// must return 501 from the scheme; `resolveRuntime` itself never throws.
+export const KNOWN_RUNTIMES = new Set([
+    "", "sh", "bash", "node", "python", "python3",
+]);
+export const isKnownRuntime = (runtime) => KNOWN_RUNTIMES.has(runtime);
+export const resolveRuntime = (runtime, command) => {
+    if (runtime === "" || runtime === "sh" || runtime === "bash") {
+        return { cmd: command, args: [], useShell: true };
+    }
+    if (runtime === "node") {
+        return { cmd: "node", args: ["-e", command], useShell: false };
+    }
+    if (runtime === "python" || runtime === "python3") {
+        return { cmd: "python3", args: ["-c", command], useShell: false };
+    }
+    // Unknown runtime: conservative `<runtime> -c <command>` fallback.
+    // Schemes should gate this off with `isKnownRuntime` and return 501,
+    // but the resolver itself stays total.
+    return { cmd: runtime, args: ["-c", command], useShell: false };
+};
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,sEAAsE;AACtE,2CAA2C;AAI3C,0EAA0E;AAC1E,yEAAyE;AACzE,MAAM,CAAC,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC;IACvD,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS;CAChD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAe,EAAW,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AAExF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAe,EAAE,OAAe,EAAa,EAAE;IAC1E,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QAC3D,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACtD,CAAC;IACD,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACrB,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACnE,CAAC;IACD,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAChD,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACtE,CAAC;IACD,mEAAmE;IACnE,qEAAqE;IACrE,uCAAuC;IACvC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACpE,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+export interface SpawnArgs {
+    /** Command to invoke (e.g. "node", "python3", or — when useShell — the raw command). */
+    cmd: string;
+    /** Args passed to the command. */
+    args: string[];
+    /** When true, the command is interpreted as a shell line (cmd is the whole line, args ignored). */
+    useShell: boolean;
+}
+/**
+ * Translate a runtime tag + command string into spawn args for `node:child_process.spawn`.
+ *
+ * Runtimes:
+ *   - `""` / `"sh"` / `"bash"`           → shell-mode invocation of the command
+ *   - `"node"`                          → `node -e <command>`
+ *   - `"python"` / `"python3"`          → `python3 -c <command>`
+ *   - any other (unknown) runtime tag    → conservative `<runtime> -c <command>` fallback
+ *
+ * Consumers check `isKnownRuntime(runtime)` before calling to enforce a 501 boundary
+ * on unconfigured runtimes; this function never throws.
+ */
+export type RuntimeResolver = (runtime: string, command: string) => SpawnArgs;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,SAAS;IACtB,wFAAwF;IACxF,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,mGAAmG;IACnG,QAAQ,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC"}

package/dist/types.js

@@ -0,0 +1,9 @@
+// Runtime executor contract. Each `@plurnk/plurnk-execs-*` sibling declares
+// one or more runtime tags (`sh`, `bash`, `python`, `search`, etc.) and
+// provides the dispatch logic for those tags.
+//
+// v0 surface: runtime tag → spawn-args translator (the only piece
+// plurnk-service's exec scheme needs migrated out of its own codebase).
+// Plugin discovery / framework registry is forward-spec — see SPEC.md.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,wEAAwE;AACxE,8CAA8C;AAC9C,EAAE;AACF,kEAAkE;AAClE,wEAAwE;AACxE,uEAAuE"}

package/package.json

@@ -0,0 +1,47 @@
+{
+    "name": "@plurnk/plurnk-execs",
+    "version": "0.1.0",
+    "description": "Framework + contract for the @plurnk/plurnk-execs-* runtime executor family.",
+    "keywords": ["plurnk", "exec", "runtime", "executor"],
+    "homepage": "https://github.com/plurnk/plurnk-execs#readme",
+    "bugs": {
+        "url": "https://github.com/plurnk/plurnk-execs/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/plurnk/plurnk-execs.git"
+    },
+    "engines": {
+        "node": ">=25"
+    },
+    "license": "MIT",
+    "author": "@wikitopian",
+    "type": "module",
+    "publishConfig": {
+        "access": "public"
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist/**/*",
+        "README.md",
+        "SPEC.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"
+    },
+    "devDependencies": {
+        "@types/node": "^25.8.0",
+        "typescript": "^6.0.3"
+    }
+}