@plurnk/plurnk-execs 0.1.0 → 0.3.0

package/README.md

@@ -9,10 +9,12 @@ Framework + contract for `@plurnk/plurnk-execs-*` runtime executor packages. Con
 
 ## 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`.
+- `BaseExecutor` — abstract base a `@plurnk/plurnk-execs-*` sibling subclasses: declares its output channels and implements `run(args) → ExecResult`.
+- `SubprocessExecutor` — concrete `BaseExecutor` for subprocess runtimes (sh/node/python): spawns via `resolveRuntime`, streams stdout/stderr, honors cancellation, reports exit code. Siblings subclass it.
+- `discover(options?)` — scans `node_modules/@plurnk/` for `plurnk.kind === "exec"` packages and builds the runtime-tag registry (fail-hard on tag collision).
+- `ExecArgs`, `ExecResult`, `ChannelDecl`, `ChannelState`, `ExecutorMetadata`, `ExecInfo`, `ExecRegistry`, `Discovery`, `DiscoverOptions` — contract types.
+- `TelemetryEvent`, `ContentOffset`, `LogCoordinate` — local mirror of grammar's telemetry envelope (the `emit` sink's payload).
+- `resolveRuntime(runtime, command)`, `isKnownRuntime(runtime)`, `KNOWN_RUNTIMES`, `SpawnArgs`, `RuntimeResolver` — subprocess-family helper for the consumer's legacy spawn path (§4).
 
 ## Tests
 

package/SPEC.md

@@ -1,77 +1,136 @@
 # 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).
+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). Contract shape settled in plurnk-service#174.
 
 ## §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.
+A runtime executor handles one or more EXEC `runtime` slot values (`sh`, `node`, `python`, `search`, `news`, …). It is a `BaseExecutor` subclass that declares its output channels and implements `run()`; the framework discovers it from its `package.json` `plurnk` block. The consuming scheme owns all I/O and lifecycle machinery (db, channels, subscriptions, AbortController bridging, wake-on-completion) and hands the executor sinks — the executor stays stateless across runs beyond its construction metadata.
 
-## §2 v0 surface
+The framework ships `SubprocessExecutor` (§4), the concrete `BaseExecutor` for subprocess runtimes (sh/node/python). plurnk-service's exec scheme still consumes the lower-level `resolveRuntime` / `SpawnArgs` helper on its legacy `streamShellCommand` path; its migration onto `SubprocessExecutor` is phased and on service's own timeline (plurnk-service#174 Q2). Both paths coexist until that cutover.
 
-`resolveRuntime(runtime: string, command: string) → SpawnArgs`:
+## §2 Executor contract
 
 ```ts
-interface SpawnArgs {
-    cmd: string;
-    args: string[];
-    useShell: boolean;
+abstract class BaseExecutor {
+    readonly runtime: string;   // matched tag — "sh" / "search" / "news" / …
+    readonly glyph: string;
+    constructor(metadata: { runtime: string; glyph: string });
+
+    // Channels this executor writes to; the scheme seeds the exec entry from
+    // these (§2.1). Subprocess runtimes declare { stdout, stderr }; search
+    // declares { results }.
+    abstract get channels(): Readonly<Record<string, ChannelDecl>>;
+
+    abstract run(args: ExecArgs): Promise<ExecResult>;
+}
+
+interface ChannelDecl { mimetype: string; defaultState?: ChannelState; }
+type ChannelState = "active" | "closed" | "errored";
+
+interface ExecArgs {
+    runtime: string;            // matched tag; multi-tag executors branch on it
+    command: string;            // EXEC body: shell line / source / search query
+    cwd: string | null;         // subprocess working dir; null/ignored for logical runtimes
+    signal: AbortSignal;        // cancellation — executors must honor it
+    write: (channel: string, chunk: string) => void;          // write a chunk to a declared channel
+    setState: (channel: string, state: ChannelState) => void; // drive a declared channel's lifecycle
+    emit: (event: TelemetryEvent) => void;                    // emit telemetry/error (§2.2)
+}
+
+interface ExecResult {
+    status: number;             // 200 ok / 499 aborted / 500 error
+    exitCode?: number;          // subprocess family only
 }
 ```
 
-Maps:
+`run()` must not throw for an expected runtime failure: surface it through `emit` + an `errored` channel state + a non-200 `status`.
 
-| 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) |
+### §2.1 Channel topology is executor-declared
+
+The executor declares its channels; the consuming scheme seeds the exec entry from `executor.channels` rather than from a static scheme-level manifest (plurnk-service#174 Q1). This keeps channel names honest — `search` exposes `{ results: { mimetype: "application/json" } }`, and the model reads `exec://<coord>/EXEC#results` instead of an overloaded `#stdout`. `write` / `setState` are generic over channel name; writing to an undeclared channel is a contract violation.
+
+### §2.2 Availability probe
 
-`resolveRuntime` never throws. Consumers gate unknown runtimes with `isKnownRuntime(runtime)` and return 501 from the scheme before invoking.
+```ts
+interface RuntimeAvailability { available: boolean; detail?: string; }
+
+abstract class BaseExecutor {
+    async probe(): Promise<RuntimeAvailability> { return { available: true }; }  // default: available
+}
+```
 
-`KNOWN_RUNTIMES` is the v0 hardcoded set; equivalent to the union of mapped runtimes above except the conservative fallback.
+`probe()` reports whether the runtime's *environment* is usable here — distinct from whether the *package* is installed (`discover()`). Pure / in-process runtimes (node, sqlite) inherit the available default; runtimes depending on an external binary (`python` → `python3 --version`) or config (`search` → `SEARXNG_URL`) override. `SubprocessExecutor` probes its `binary` getter (`null` = always available).
 
-## §3 Forward-spec — plugin discovery
+Consumer contract (plurnk-service#181): probe **once at boot, per package** (not per tag — stamp all of a package's tags with the one result), **concurrently under a per-probe timeout**, and **cache**. `probe()` MAY reject; the consumer treats rejection as `{ available: false, detail: <error> }`, so a buggy probe degrades only its runtime. The model is offered a positive list of available runtimes; an attempt at an unavailable one returns **501 carrying `detail`** (so `detail` is model-facing — terse and actionable). A configured default runtime that probes unavailable is a **fail-hard boot error**.
 
-The full constellation pattern (mirroring `plurnk-mimetypes`):
+### §2.3 Telemetry
+
+Runtime failures are emitted as a grammar `TelemetryEvent` via the `emit` sink (plurnk-service#174 Q3); the scheme routes it to the engine's telemetry buffer — the same path grammar's `parse_error` takes. Events are not encoded into `stderr` (that pollutes program output) nor returned on `ExecResult` (that loses mid-run events).
+
+- `source`: `"exec:<runtime>"` (e.g. `"exec:search"`) or `"scheme:exec"`.
+- `kind`: producer-minted — `runtime_not_configured`, `spawn_failed`, `exited_nonzero`, `aborted`, and runtime-specific kinds (search: `searxng_unreachable`, `searxng_http_<n>`).
+- `message`: terse, factual. `position`: typically null at the runtime layer.
+
+The envelope is mirrored locally (`TelemetryEvent`, `ContentOffset`, `LogCoordinate`) so the framework needs no `@plurnk/plurnk-grammar` dependency; grammar's `dist/schema/TelemetryEvent.json` is the source of truth.
+
+## §3 Discovery
+
+`discover(options?) → { registry }`. Scans `<cwd>/node_modules/@plurnk/` (or explicit `packageDirs`) for packages declaring `plurnk.kind === "exec"`, and registers each runtime tag from `plurnk.runtimes[]`:
 
 ```json
 {
-    "name": "@plurnk/plurnk-execs-<runtime>",
+    "name": "@plurnk/plurnk-execs-search",
     "plurnk": {
         "kind": "exec",
         "runtimes": [
-            { "name": "sh", "glyph": "🐚" },
-            { "name": "bash", "glyph": "🐚" }
+            { "name": "search", "glyph": "🔎" },
+            { "name": "news",   "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.
+A package may claim multiple tags backed by one handler. Tags form a **flat global namespace**; `registry` maps tag → `{ runtime, glyph, packageName }`. Unlike plurnk-mimetypes (last-loaded wins), a tag **collision is fail-hard**: two packages claiming the same runtime is an unresolvable install ambiguity the operator must fix.
 
-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).
+Each runtime exports its `BaseExecutor` subclass; the consumer instantiates it per matched tag with the tag + glyph from the registry. (Module-export convention for the subclass settles as the first siblings ship.)
+
+## §4 Subprocess helper (legacy path)
+
+`resolveRuntime(runtime, command) → SpawnArgs` and `isKnownRuntime(runtime)` / `KNOWN_RUNTIMES` translate a subprocess runtime tag into `node:child_process.spawn` arguments:
+
+```ts
+interface SpawnArgs { cmd: string; args: string[]; useShell: boolean; }
+```
+
+| 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) |
 
-Sub-siblings expected: `plurnk-execs-sh` (default subprocess), `plurnk-execs-node`, `plurnk-execs-python`, `plurnk-execs-search` (web search).
+`resolveRuntime` never throws; consumers gate unknown runtimes with `isKnownRuntime` and return 501 before invoking.
 
-## §4 Consumer surface (plurnk-service today)
+The framework wraps this in **`SubprocessExecutor extends BaseExecutor`** — declares `{ stdout, stderr }` channels and implements `run()` (spawn via `resolveRuntime`, stream into the channels, honor `signal`, `emit` `spawn_failed` on a failed start, return `{ status, exitCode }`). The `plurnk-execs-sh` / `-node` / `-python` siblings subclass it and differ only in their claimed `runtimes[]` tags. plurnk-service consumes `resolveRuntime` directly on its legacy path today and adopts `SubprocessExecutor` when it migrates.
 
-The `exec` scheme in plurnk-service:
+## §5 Consumer surface (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).
+Per plurnk-service#174, the exec scheme:
 
-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.
+1. Resolves the runtime tag against the discovery registry; routes `search` (and future siblings) through the executor's `run()`.
+2. Seeds the exec entry's channels from `executor.channels`.
+3. Provides the `write` / `setState` / `emit` sinks bound to its channel-write, channel-state, and engine-telemetry machinery; bridges its AbortController to `args.signal`; maps the `ExecResult` to close-status + wake summary.
+4. Keeps the legacy `streamShellCommand` path (via `resolveRuntime`) for subprocess runtimes until the `SubprocessExecutor` migration.
 
-## §5 Forbidden (for future siblings)
+## §6 Forbidden (for siblings)
 
 | ❌ |
 |---|
 | Database access |
 | Imports from `@plurnk/plurnk-service/*` |
-| Mutating arguments |
-| Holding state across `run` calls beyond config |
+| Mutating `ExecArgs` |
+| Holding state across `run` calls beyond construction metadata |
 | Reading runtime output via `console.*` |
-| Ignoring cancellation signals |
-| Spawning processes outside the runtime's domain (e.g. an HTTP runtime spawning subprocesses) |
+| Ignoring `args.signal` |
+| Writing to an undeclared channel |
+| Spawning processes outside the runtime's domain (e.g. an HTTP/search runtime spawning subprocesses) |

package/dist/BaseExecutor.d.ts

@@ -0,0 +1,10 @@
+import type { ChannelDecl, ExecArgs, ExecResult, ExecutorMetadata, RuntimeAvailability } from "./types.ts";
+export default abstract class BaseExecutor {
+    readonly runtime: string;
+    readonly glyph: string;
+    constructor({ runtime, glyph }: ExecutorMetadata);
+    abstract get channels(): Readonly<Record<string, ChannelDecl>>;
+    abstract run(args: ExecArgs): Promise<ExecResult>;
+    probe(): Promise<RuntimeAvailability>;
+}
+//# sourceMappingURL=BaseExecutor.d.ts.map

package/dist/BaseExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseExecutor.d.ts","sourceRoot":"","sources":["../src/BaseExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAW3G,MAAM,CAAC,OAAO,CAAC,QAAQ,OAAO,YAAY;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,gBAAgB;IAUhD,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAO/D,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;IAY3C,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC;CAG9C"}

package/dist/BaseExecutor.js

@@ -0,0 +1,31 @@
+// Base class for runtime executors (parallel to plurnk-mimetypes' BaseHandler).
+// A `@plurnk/plurnk-execs-*` sibling subclasses this and implements `run()`.
+// The framework instantiates one executor per matched runtime tag, injecting
+// the tag + glyph from the package's `plurnk.runtimes[]` manifest entry.
+//
+// The consuming scheme owns all I/O and lifecycle machinery (db, channels,
+// subscriptions, AbortController bridging, wake-on-completion). The executor
+// receives sinks via ExecArgs and nothing more — it stays stateless across
+// runs beyond its construction metadata (SPEC §5).
+export default class BaseExecutor {
+    runtime;
+    glyph;
+    constructor({ runtime, glyph }) {
+        this.runtime = runtime;
+        this.glyph = glyph;
+    }
+    // Whether this runtime's execution environment is usable in the current
+    // deployment. Default: available (pure / in-process runtimes — e.g. node,
+    // sqlite, where the daemon itself satisfies the dependency). Subclasses
+    // that depend on an external binary or external config override.
+    //
+    // The consumer probes once at boot, per package, runs probes concurrently
+    // under a per-probe timeout, and caches the result. Unlike `run()`, this
+    // MAY reject — the consumer treats a rejection as `{ available: false }` —
+    // but returning a crafted `{ available: false, detail }` for an expected
+    // miss gives a better model-facing reason than a raw error.
+    async probe() {
+        return { available: true };
+    }
+}
+//# sourceMappingURL=BaseExecutor.js.map

package/dist/BaseExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseExecutor.js","sourceRoot":"","sources":["../src/BaseExecutor.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,6EAA6E;AAC7E,6EAA6E;AAC7E,yEAAyE;AACzE,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,2EAA2E;AAC3E,mDAAmD;AACnD,MAAM,CAAC,OAAO,OAAgB,YAAY;IAC7B,OAAO,CAAS;IAChB,KAAK,CAAS;IAEvB,YAAY,EAAE,OAAO,EAAE,KAAK,EAAoB;QAC5C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;IAgBD,wEAAwE;IACxE,0EAA0E;IAC1E,wEAAwE;IACxE,iEAAiE;IACjE,EAAE;IACF,0EAA0E;IAC1E,yEAAyE;IACzE,2EAA2E;IAC3E,yEAAyE;IACzE,4DAA4D;IAC5D,KAAK,CAAC,KAAK;QACP,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC/B,CAAC;CACJ"}

package/dist/SubprocessExecutor.d.ts

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

package/dist/SubprocessExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubprocessExecutor.d.ts","sourceRoot":"","sources":["../src/SubprocessExecutor.ts"],"names":[],"mappings":"AACA,OAAO,YAAY,MAAM,mBAAmB,CAAC;AAE7C,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAWzF,MAAM,CAAC,OAAO,OAAO,kBAAmB,SAAQ,YAAY;IACxD,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAKpD;IAKD,SAAS,KAAK,MAAM,IAAI,MAAM,GAAG,IAAI,CAEpC;IAEc,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAqBpD,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;CAwC/F"}

package/dist/SubprocessExecutor.js

@@ -0,0 +1,89 @@
+import { spawn } from "node:child_process";
+import BaseExecutor from "./BaseExecutor.js";
+import { resolveRuntime } from "./runtime.js";
+// Concrete BaseExecutor for subprocess runtimes (sh, node, python, …). Spawns
+// via resolveRuntime, streams the process's stdout/stderr into the declared
+// channels, honors cancellation, and reports the exit code. The sibling
+// packages (plurnk-execs-sh / -node / -python) subclass this and differ only
+// in which runtime tags they claim in their `plurnk.runtimes[]` manifest.
+//
+// This is the destination of plurnk-service's legacy `streamShellCommand`
+// (service#174 Q2): the scheme migrates onto it on its own timeline; until
+// then both paths coexist.
+export default class SubprocessExecutor extends BaseExecutor {
+    get channels() {
+        return {
+            stdout: { mimetype: "text/stream" },
+            stderr: { mimetype: "text/stream" },
+        };
+    }
+    // The executable this runtime depends on, for probe(). `null` = nothing to
+    // check (always available — e.g. node, where the daemon already IS the
+    // runtime). Subclasses naming an external interpreter override this.
+    get binary() {
+        return null;
+    }
+    async probe() {
+        const bin = this.binary;
+        if (bin === null)
+            return { available: true };
+        return new Promise((resolve) => {
+            let settled = false;
+            const done = (r) => { if (!settled) {
+                settled = true;
+                resolve(r);
+            } };
+            let out = "";
+            const child = spawn(bin, ["--version"], { signal: AbortSignal.timeout(3000) });
+            child.stdout?.on("data", (chunk) => { out += chunk.toString("utf8"); });
+            child.on("error", (err) => done({
+                available: false,
+                detail: err.code === "ABORT_ERR"
+                    ? `${bin} probe timed out`
+                    : `${bin} not found on PATH`,
+            }));
+            child.on("close", (code) => done(code === 0
+                ? { available: true, detail: out.trim().split("\n")[0] || undefined }
+                : { available: false, detail: `${bin} --version exited ${code}` }));
+        });
+    }
+    run({ runtime, command, cwd, signal, write, setState, emit }) {
+        const { cmd, args, useShell } = resolveRuntime(runtime, command);
+        return new Promise((resolve) => {
+            // Abort and close both fire on signal-kill; settle exactly once so
+            // channel state isn't transitioned twice.
+            let settled = false;
+            const finish = (result, state) => {
+                if (settled)
+                    return;
+                settled = true;
+                setState("stdout", state);
+                setState("stderr", state);
+                resolve(result);
+            };
+            const child = spawn(cmd, args, { shell: useShell, signal, cwd: cwd ?? undefined });
+            child.stdout?.on("data", (chunk) => write("stdout", chunk.toString("utf8")));
+            child.stderr?.on("data", (chunk) => write("stderr", chunk.toString("utf8")));
+            child.on("error", (err) => {
+                if (err.code === "ABORT_ERR") {
+                    finish({ status: 499, exitCode: -1 }, "errored");
+                    return;
+                }
+                // The process could not be started — a framework-level failure
+                // the model benefits from seeing as telemetry (a nonzero exit,
+                // by contrast, is the program's own result and lives on stderr).
+                emit({ source: `exec:${runtime}`, kind: "spawn_failed", message: err.message });
+                finish({ status: 500, exitCode: -1 }, "errored");
+            });
+            child.on("close", (code, killedBySignal) => {
+                if (killedBySignal !== null) {
+                    finish({ status: 499, exitCode: code ?? -1 }, "errored");
+                    return;
+                }
+                const ok = code === 0;
+                finish({ status: ok ? 200 : 500, exitCode: code ?? -1 }, ok ? "closed" : "errored");
+            });
+        });
+    }
+}
+//# sourceMappingURL=SubprocessExecutor.js.map

package/dist/SubprocessExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubprocessExecutor.js","sourceRoot":"","sources":["../src/SubprocessExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,YAAY,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,8EAA8E;AAC9E,4EAA4E;AAC5E,wEAAwE;AACxE,6EAA6E;AAC7E,0EAA0E;AAC1E,EAAE;AACF,0EAA0E;AAC1E,2EAA2E;AAC3E,2BAA2B;AAC3B,MAAM,CAAC,OAAO,OAAO,kBAAmB,SAAQ,YAAY;IACxD,IAAI,QAAQ;QACR,OAAO;YACH,MAAM,EAAE,EAAE,QAAQ,EAAE,aAAa,EAAE;YACnC,MAAM,EAAE,EAAE,QAAQ,EAAE,aAAa,EAAE;SACtC,CAAC;IACN,CAAC;IAED,2EAA2E;IAC3E,uEAAuE;IACvE,qEAAqE;IACrE,IAAc,MAAM;QAChB,OAAO,IAAI,CAAC;IAChB,CAAC;IAEQ,KAAK,CAAC,KAAK;QAChB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;QACxB,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAC7C,OAAO,IAAI,OAAO,CAAsB,CAAC,OAAO,EAAE,EAAE;YAChD,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,MAAM,IAAI,GAAG,CAAC,CAAsB,EAAQ,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;gBAAC,OAAO,GAAG,IAAI,CAAC;gBAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAAC,CAAC,CAAC,CAAC,CAAC;YACjG,IAAI,GAAG,GAAG,EAAE,CAAC;YACb,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC/E,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,GAAG,GAAG,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAChF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC;gBAC5B,SAAS,EAAE,KAAK;gBAChB,MAAM,EAAG,GAA6B,CAAC,IAAI,KAAK,WAAW;oBACvD,CAAC,CAAC,GAAG,GAAG,kBAAkB;oBAC1B,CAAC,CAAC,GAAG,GAAG,oBAAoB;aACnC,CAAC,CAAC,CAAC;YACJ,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC;gBACvC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,SAAS,EAAE;gBACrE,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,GAAG,qBAAqB,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;QAC5E,CAAC,CAAC,CAAC;IACP,CAAC;IAED,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAY;QAClE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjE,OAAO,IAAI,OAAO,CAAa,CAAC,OAAO,EAAE,EAAE;YACvC,mEAAmE;YACnE,0CAA0C;YAC1C,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,MAAM,MAAM,GAAG,CAAC,MAAkB,EAAE,KAA2B,EAAQ,EAAE;gBACrE,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,GAAG,IAAI,CAAC;gBACf,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;gBAC1B,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;gBAC1B,OAAO,CAAC,MAAM,CAAC,CAAC;YACpB,CAAC,CAAC;YAEF,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,SAAS,EAAE,CAAC,CAAC;YACnF,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACrF,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAErF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;gBACtB,IAAK,GAA6B,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;oBACtD,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;oBACjD,OAAO;gBACX,CAAC;gBACD,+DAA+D;gBAC/D,+DAA+D;gBAC/D,iEAAiE;gBACjE,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,OAAO,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;gBAChF,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;YACrD,CAAC,CAAC,CAAC;YAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE;gBACvC,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;oBAC1B,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,IAAI,CAAC,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;oBACzD,OAAO;gBACX,CAAC;gBACD,MAAM,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;gBACtB,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YACxF,CAAC,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;IACP,CAAC;CACJ"}

package/dist/TelemetryEvent.d.ts

@@ -0,0 +1,18 @@
+export interface TelemetryEvent {
+    readonly source: string;
+    readonly kind: string;
+    readonly message?: string | null;
+    readonly position?: ContentOffset | LogCoordinate | null;
+    readonly [k: string]: unknown;
+}
+export interface ContentOffset {
+    readonly type: "content-offset";
+    readonly line: number;
+    readonly column: number;
+}
+export interface LogCoordinate {
+    readonly type: "log-coordinate";
+    readonly coordinate: string;
+    readonly op?: string;
+}
+//# sourceMappingURL=TelemetryEvent.d.ts.map

package/dist/TelemetryEvent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TelemetryEvent.d.ts","sourceRoot":"","sources":["../src/TelemetryEvent.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,aAAa,GAAG,IAAI,CAAC;IACzD,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist/TelemetryEvent.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=TelemetryEvent.js.map

package/dist/TelemetryEvent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TelemetryEvent.js","sourceRoot":"","sources":["../src/TelemetryEvent.ts"],"names":[],"mappings":""}

package/dist/discover.d.ts

@@ -0,0 +1,3 @@
+import type { Discovery, DiscoverOptions } from "./types.ts";
+export declare function discover(options?: DiscoverOptions): Promise<Discovery>;
+//# sourceMappingURL=discover.d.ts.map

package/dist/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAY,MAAM,YAAY,CAAC;AAkBvE,wBAAsB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,SAAS,CAAC,CAkBhF"}

package/dist/discover.js

@@ -0,0 +1,92 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+// Scan installed executor packages and build the runtime-tag registry the
+// consuming scheme dispatches on. Parallel to plurnk-mimetypes' discover().
+//
+// Default scan target: `<cwd>/node_modules/@plurnk/`. Tests and unusual
+// layouts can pass `packageDirs` explicitly to skip the scan.
+//
+// A package is recognized as an executor when its `package.json` declares
+// `plurnk.kind === "exec"` and exposes one or more runtime tags via
+// `plurnk.runtimes: { name, glyph? }[]` (SPEC §3). Each entry registers its
+// tag separately; one package can claim many tags backed by the same handler
+// (e.g. the search sibling claims `search`, `news`, `images`, …).
+//
+// Tags are a flat global namespace. Unlike plurnk-mimetypes (last-loaded
+// wins), a tag collision here is a FAIL-HARD install error: two packages
+// claiming the same runtime is an unresolvable ambiguity the operator must
+// fix (SPEC §3, plurnk-execs#1).
+export async function discover(options = {}) {
+    const dirs = options.packageDirs ?? await defaultPackageDirs(options.cwd ?? process.cwd());
+    const registry = new Map();
+    for (const dir of dirs) {
+        for (const info of await readExecInfos(dir)) {
+            const existing = registry.get(info.runtime);
+            if (existing !== undefined) {
+                throw new Error(`exec runtime collision: '${info.runtime}' claimed by both `
+                    + `${existing.packageName} and ${info.packageName}`);
+            }
+            registry.set(info.runtime, info);
+        }
+    }
+    return { registry };
+}
+async function defaultPackageDirs(cwd) {
+    const scope = path.join(cwd, "node_modules", "@plurnk");
+    let entries;
+    try {
+        entries = await fs.readdir(scope, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => path.join(scope, entry.name));
+}
+// Produce one ExecInfo per declared runtime tag. Returns [] for non-executor
+// packages or invalid declarations.
+async function readExecInfos(dir) {
+    const pkgPath = path.join(dir, "package.json");
+    let raw;
+    try {
+        raw = await fs.readFile(pkgPath, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (typeof pkg !== "object" || pkg === null)
+        return [];
+    const record = pkg;
+    const plurnk = record.plurnk;
+    if (typeof plurnk !== "object" || plurnk === null)
+        return [];
+    const plurnkRec = plurnk;
+    if (plurnkRec.kind !== "exec")
+        return [];
+    if (!Array.isArray(plurnkRec.runtimes))
+        return [];
+    const packageName = typeof record.name === "string" ? record.name : "";
+    const infos = [];
+    for (const entry of plurnkRec.runtimes) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const e = entry;
+        if (typeof e.name !== "string" || e.name === "")
+            continue;
+        infos.push({
+            runtime: e.name,
+            glyph: typeof e.glyph === "string" ? e.glyph : "",
+            packageName,
+        });
+    }
+    return infos;
+}
+//# sourceMappingURL=discover.js.map

package/dist/discover.js.map

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

package/dist/index.d.ts

@@ -1,3 +1,7 @@
-export type { SpawnArgs, RuntimeResolver } from "./types.ts";
+export { default as BaseExecutor } from "./BaseExecutor.ts";
+export { default as SubprocessExecutor } from "./SubprocessExecutor.ts";
+export { discover } from "./discover.ts";
 export { KNOWN_RUNTIMES, isKnownRuntime, resolveRuntime } from "./runtime.ts";
+export type { ChannelState, ChannelDecl, ExecutorMetadata, ExecArgs, ExecResult, RuntimeAvailability, ExecInfo, ExecRegistry, Discovery, DiscoverOptions, SpawnArgs, RuntimeResolver, } from "./types.ts";
+export type { TelemetryEvent, ContentOffset, LogCoordinate } from "./TelemetryEvent.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9E,YAAY,EACR,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,QAAQ,EACR,UAAU,EACV,mBAAmB,EACnB,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,eAAe,EACf,SAAS,EACT,eAAe,GAClB,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,2 +1,7 @@
+// Framework surface
+export { default as BaseExecutor } from "./BaseExecutor.js";
+export { default as SubprocessExecutor } from "./SubprocessExecutor.js";
+export { discover } from "./discover.js";
+// Runtime-tag → spawn-args helper (subprocess family; legacy scheme path)
 export { KNOWN_RUNTIMES, isKnownRuntime, resolveRuntime } from "./runtime.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,0EAA0E;AAC1E,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/types.d.ts

@@ -1,3 +1,43 @@
+import type { TelemetryEvent } from "./TelemetryEvent.ts";
+export type ChannelState = "active" | "closed" | "errored";
+export interface ChannelDecl {
+    mimetype: string;
+    defaultState?: ChannelState;
+}
+export interface ExecutorMetadata {
+    runtime: string;
+    glyph: string;
+}
+export interface ExecArgs {
+    runtime: string;
+    command: string;
+    cwd: string | null;
+    signal: AbortSignal;
+    write: (channel: string, chunk: string) => void;
+    setState: (channel: string, state: ChannelState) => void;
+    emit: (event: TelemetryEvent) => void;
+}
+export interface ExecResult {
+    status: number;
+    exitCode?: number;
+}
+export interface RuntimeAvailability {
+    available: boolean;
+    detail?: string;
+}
+export interface ExecInfo {
+    runtime: string;
+    glyph: string;
+    packageName: string;
+}
+export type ExecRegistry = ReadonlyMap<string, ExecInfo>;
+export interface Discovery {
+    registry: ExecRegistry;
+}
+export interface DiscoverOptions {
+    cwd?: string;
+    packageDirs?: string[];
+}
 export interface SpawnArgs {
     /** Command to invoke (e.g. "node", "python3", or — when useShell — the raw command). */
     cmd: string;

package/dist/types.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAM3D,MAAM,WAAW,WAAW;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,YAAY,CAAC;CAC/B;AAKD,MAAM,WAAW,gBAAgB;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACjB;AAOD,MAAM,WAAW,QAAQ;IAGrB,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,EAAE,MAAM,CAAC;IAGhB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnB,MAAM,EAAE,WAAW,CAAC;IAEpB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhD,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAGzD,IAAI,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CACzC;AAKD,MAAM,WAAW,UAAU;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAOD,MAAM,WAAW,mBAAmB;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,QAAQ;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACvB;AAID,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEzD,MAAM,WAAW,SAAS;IACtB,QAAQ,EAAE,YAAY,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAG5B,GAAG,CAAC,EAAE,MAAM,CAAC;IAGb,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAID,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

@@ -1,9 +1,12 @@
 // 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.
+// one or more runtime tags (`sh`, `bash`, `python`, `search`, `news`, …) in
+// its `package.json` `plurnk.runtimes[]` block, and provides a BaseExecutor
+// subclass implementing the dispatch 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.
+// The framework surface is `BaseExecutor.run()` + `discover()`. The runtime
+// tag → spawn-args translator (`SpawnArgs` / `resolveRuntime`) is retained as
+// a subprocess-family helper: plurnk-service's exec scheme still consumes it
+// on its legacy subprocess path until the deferred SubprocessExecutor
+// migration (service#174 Q2). See SPEC.md.
 export {};
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +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"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,4EAA4E;AAC5E,4EAA4E;AAC5E,qDAAqD;AACrD,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,6EAA6E;AAC7E,sEAAsE;AACtE,2CAA2C"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@plurnk/plurnk-execs",
-    "version": "0.1.0",
+    "version": "0.3.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",