@plurnk/plurnk-execs-common 1.16.5 → 1.18.0

package/README.md

@@ -25,27 +25,31 @@ detects every other interpreter, so one executor adapts to the host.
 | `bc` 🧮                          | bc                | stdin (for example, `6 * 7`)             |
 | `awk` 🪄                         | awk               | program arg, empty stdin (`BEGIN { … }`) |
 
+Each runtime's catalog Summary includes a short executable inline body, with
+literal `\n` separators keeping the invocation on one discovery line.
+
 ### A script — the `(target)` slot
 
 The table above is the **inline** form: the body is the program. A file in the
 `(target)` slot is instead the script each interpreter reads directly, and the
-body becomes that script's stdin. A `{cwd=<directory>}` block on the heading
-selects the working directory; the body remains the program
-({§executor-subprocess-routing}).
+body becomes that script's stdin. A `[{"cwd": "<directory>"}]` block on the heading
+selects the working directory. Script arguments use `[{"args": ["arg",...]}]`;
+each string is passed literally, without shell expansion ({§executor-metadata}).
+These options work for local, Worker, and Skill script targets alike.
 
-```example
-### EXEC0 (./deploy.sh)
+````sh (./deploy.sh)
 yes
 yes
 no
+````
 
-### EXEC0 [python3] (transform.py)
+````python3 (transform.py) [{"args": ["--format","json"]}]
 3
 1
 4
 1
 5
-```
+````
 
 The first operation answers a shell script's prompts through stdin. The second
 feeds records to a Python script.
@@ -53,9 +57,8 @@ feeds records to a Python script.
 All declared tags run host code, so every invocation is proposal-gated. The
 current installed in-process evaluators are jq and SQLite; their
 `pure` or `read` invocations bypass the proposal gate but still return through
-the same next-turn stream path ({§executor-effect}). Input-processing
-transforms (`sed`, input-driven `awk`) await an EXEC input-channel contract and
-are not claimed here.
+the same next-turn stream path ({§executor-effect}). Inline programs have no
+separate input channel; script targets receive stdin from the body.
 
 ## Configuration
 

package/dist/Common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Common.d.ts","sourceRoot":"","sources":["../src/Common.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAkC3E,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAAwC,CAAC;AAenF,MAAM,CAAC,OAAO,OAAO,MAAO,SAAQ,kBAAkB;IAClD,UAAmB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,GAAG,IAAW,GAAG,SAAS,CAmBtG;IAEc,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAOnD;CACJ"}
+{"version":3,"file":"Common.d.ts","sourceRoot":"","sources":["../src/Common.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAmC3E,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAAwC,CAAC;AAenF,MAAM,CAAC,OAAO,OAAO,MAAO,SAAQ,kBAAkB;IAClD,UAAmB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,GAAG,IAAW,GAAG,SAAS,CActG;IAEc,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAOnD;CACJ"}

package/dist/Common.js

@@ -13,7 +13,7 @@ const RECIPES = Object.freeze({
     bun: { bin: "bun", arg: (c) => ["-e", c] },
     tcl: { bin: "tclsh", stdin: true },
     bc: { bin: "bc", stdin: true },
-    awk: { bin: "awk", bare: true },
+    awk: { bin: "awk", bare: true, script: (target) => ["-f", target] },
 });
 // Exposed for tests / consumers wanting the candidate set.
 export const RUNTIME_TAGS = Object.freeze(Object.keys(RECIPES));
@@ -34,15 +34,10 @@ export default class Common extends SubprocessExecutor {
         if (r === undefined)
             throw new Error(`plurnk-execs-common received unclaimed runtime tag '${runtime}'`);
         // With a target the program IS the target and the body is its stdin
-        // ({§executor-subprocess-routing}), run as one script-file positional for every
-        // interpreter: the interpreter
-        // READS the file, so no exec bit is consulted and none is ever set.
-        // The old shell `-c` arm made the shell execve() the target instead
-        // (PATH lookup on bare names, +x demanded on EDIT-created scripts) and
-        // doubled as an unsanctioned command-line side door — commands belong
-        // in the body.
+        // ({§executor-subprocess-routing}). The interpreter reads the file;
+        // no executable bit is consulted or changed.
         if (target !== null) {
-            return { cmd: r.bin, args: [target], useShell: false, stdin: command };
+            return { cmd: r.bin, args: r.script?.(target) ?? [target], useShell: false, stdin: command };
         }
         // Trailing newline so line-oriented readers (bc, tclsh) evaluate the
         // final line before EOF rather than erroring on an unterminated line.

package/dist/Common.js.map

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

package/docs/awk.md

@@ -0,0 +1,30 @@
+# awk
+
+For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
+returned execution address; `[{"eof": true}]` closes stdin. See the
+[live-input example](node.md#live-input), including newline framing.
+
+The body is the AWK program, passed as the one positional argument with an
+empty stdin: with no input file it only runs `BEGIN` blocks. To process data,
+name the file(s) in `[{"args": [...]}]`, or run a script target and feed it the body
+as stdin.
+
+````awk [{"args": ["data.csv"]}] <!-- the body is the program -->
+BEGIN { FS = "," }
+NR > 1 { total += $3 }
+END { printf "rows=%d total=%.2f\n", NR - 1, total }
+````
+
+````awk (tools/summarize.awk) <!-- the script runs; the body is its stdin -->
+alpha,1
+beta,2
+````
+
+Output goes to `#stdout`, diagnostics to `#stderr`; `exit 1` in the program
+closes with status 500. `[{"cwd": "<directory>"}]` selects the working directory
+for relative file arguments. AWK is the right tool for column arithmetic and
+line reshaping over text; for JSON use `jq`, for anything else `node` or `sh`.
+
+`[{"env": {"NAME": "value"}}]` on the same fence line sets variables for this run
+alone, over the entries in your `env` registry; names are the shell's, and plurnk's own
+(`PLURNK_*`, provider credentials) are refused by name.

package/docs/bc.md

@@ -0,0 +1,22 @@
+# bc
+
+For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
+returned execution address; `[{"eof": true}]` closes stdin. See the
+[live-input example](node.md#live-input), including newline framing.
+
+The body is a `bc` program fed on stdin (a trailing newline is added, so the last
+line evaluates). Arbitrary precision: set `scale` before dividing, or every
+quotient is truncated to an integer.
+
+````bc <!-- the body is the program -->
+scale=6
+22/7
+2^64
+````
+
+Each expression prints its value on its own line to `#stdout`; `#stderr`
+carries parse errors such as `syntax error`. The exit status is 0 even when
+a line failed to parse, so read `#stderr` when a result is missing. A script
+target (`bc (rates.bc)`) runs that file with the body as stdin.
+Use bc for exact decimal or big-integer arithmetic; for anything with strings,
+loops over data, or JSON, reach for `awk`, `node`, or `sh`.

package/docs/bun.md

@@ -0,0 +1,22 @@
+# bun
+
+For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
+returned execution address; `[{"eof": true}]` closes stdin. See the
+[live-input example](node.md#live-input), including newline framing.
+
+The body is TypeScript or JavaScript, run with `bun -e`. A script target runs
+that file and receives the body as stdin; `[{"args": [...]}]` passes literal
+arguments, readable as `Bun.argv` or `process.argv`.
+
+````bun <!-- the body is the program -->
+const file = Bun.file("package.json");
+console.log((await file.json()).name);
+````
+
+````bun (scripts/build.ts) [{"args": ["--watch=false"]}]
+````
+
+`console.log` streams to `#stdout`, `console.error` to `#stderr`; an uncaught
+error or `process.exit(1)` closes with status 500. Prefer `node` unless the
+project is a Bun project: node is always present, bun only when the host
+has it.

package/docs/deno.md

@@ -0,0 +1,23 @@
+# deno
+
+For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
+returned execution address; `[{"eof": true}]` closes stdin. See the
+[live-input example](node.md#live-input), including newline framing.
+
+The body is TypeScript or JavaScript, run with `deno eval` (permissions are
+Deno's defaults for `eval`; import what you need from the project or a URL).
+A script target runs that file and receives the body as stdin;
+`[{"args": [...]}]` passes literal arguments, readable as `Deno.args`.
+
+````deno <!-- the body is the program -->
+const versions: Record<string, string> = Deno.version;
+console.log(JSON.stringify(versions));
+````
+
+````deno (scripts/check.ts) [{"args": ["--strict"]}]
+````
+
+`console.log` streams to `#stdout`, `console.error` to `#stderr`; an uncaught
+error or `Deno.exit(1)` closes with status 500. Prefer `node` when the task
+does not need Deno specifically: node is always present, deno only when the
+host has it.

package/docs/lua.md

@@ -0,0 +1,23 @@
+# lua
+
+For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
+returned execution address; `[{"eof": true}]` closes stdin. See the
+[live-input example](node.md#live-input), including newline framing.
+
+The body is Lua code, run with `lua -e`. A script target runs that file and
+receives the body as stdin; `[{"args": [...]}]` passes literal script arguments,
+readable through the `arg` table.
+
+````lua <!-- the body is the program -->
+local t = { 3, 1, 2 }
+table.sort(t)
+print(table.concat(t, ","))
+````
+
+````lua (scripts/lint.lua) [{"args": ["src/main.lua"]}]
+````
+
+`print` streams to `#stdout`, `io.stderr:write` to `#stderr`; `error(...)`
+or `os.exit(1)` closes with status 500. The standalone interpreter is the
+host's `lua` on PATH; project modules resolve through its ordinary
+`package.path` from the working directory.

package/docs/node.md

@@ -2,6 +2,37 @@
 
 A JavaScript snippet, run via `node -e`. Node is the daemon's own runtime, so it's always available (no PATH probe).
 
+````node <!-- the body is the snippet -->
+const os = require("node:os");
+console.log(JSON.stringify({ platform: os.platform(), cpus: os.cpus().length }));
+````
+
+## Live input
+
+`[{"stdin": "open"}]` keeps stdin open for later SENDs to the receipt's execution
+address. Without it, initial input ends with EOF as usual.
+
+````node [{"stdin": "open"}]
+process.stdin.on("data", chunk => process.stdout.write(chunk));
+````
+
+Using the address returned by that invocation (here `node:///ab3d5678`):
+
+````SEND (node:///ab3d5678)
+hello
+
+````
+
+The blank line before the closing fence supplies a newline after `hello`.
+SEND adds no newline of its own. Its receipt acknowledges pipe delivery, not
+program completion. READ that same address to inspect stdout while it runs.
+
+````SEND (node:///ab3d5678) [{"eof": true}]
+````
+
+EOF closes stdin, not the process. KILL terminates the execution. Any worker
+in the workspace can send input to the same execution address.
+
 ## Environment
 
 The same scoped environment as `sh`: the daemon's own secrets (`PLURNK_*`, provider keys) are stripped, so `process.env` inside the snippet sees the project's environment, not plurnk's.
@@ -9,17 +40,25 @@ The same scoped environment as `sh`: the daemon's own secrets (`PLURNK_*`, provi
 ## Output
 
 Whatever the snippet writes to stdout streams to `#stdout`; stderr streams to
-`#stderr`. Both are text under the emitted `node:///<loop>/<turn>/<sequence>`
-address. To return structured data, use `console.log(JSON.stringify(value))`
-and READ that address. A thrown error exits nonzero (status 500) with its stack
-on stderr.
+`#stderr`. Both are text under the receipt's `stream` address, such as
+`node:///ab3d5678`. On completion, the harness adds a READ of each channel's
+first page (up to 16 lines). READ the stream address for additional lines;
+the log READ holds only its recorded page. To return structured data, use
+`console.log(JSON.stringify(value))`. A thrown error exits nonzero (status 500)
+with its stack on stderr. The receipt's own body is the snippet as you sent
+it, never output; a non-200 receipt with no `stream` address ran nothing.
 
 ## Working directory
 
 Runs in the workspace project root by default, or the daemon's own cwd in a
-workspace without one; a `{cwd=<directory>}` block on the heading selects
+workspace without one; a `[{"cwd": "<directory>"}]` block on the opening fence line selects
 another. The target is a script, never a command or a directory:
-`### EXEC0 [node] (tool.js)` runs that JavaScript file and receives the body as
-stdin; anything else is refused before anything runs. Relative module and
-filesystem paths resolve against the working directory. The receipt always
-names it.
+`node (tool.js)` runs that JavaScript file and receives the body as
+stdin. `[{"args": ["--format","json"]}]` passes literal script arguments, also for
+`worker://` and `skill://` targets. Relative imports resolve from the script;
+ordinary relative filesystem paths resolve from cwd. The receipt names cwd
+when it differs from the project root.
+
+`[{"env": {"NAME": "value"}}]` on the same fence line sets variables for this run
+alone, over the entries in your `env` registry; names are the shell's, and plurnk's own
+(`PLURNK_*`, provider credentials) are refused by name.

package/docs/perl.md

@@ -0,0 +1,23 @@
+# perl
+
+For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
+returned execution address; `[{"eof": true}]` closes stdin. See the
+[live-input example](node.md#live-input), including newline framing.
+
+The body is Perl code, run with `perl -e`. A script target runs that file and
+receives the body as stdin; `[{"args": [...]}]` passes literal script arguments.
+
+````perl <!-- the body is the program -->
+use strict; use warnings;
+my %count; $count{$_}++ for qw(a b a c a);
+printf "%s=%d\n", $_, $count{$_} for sort keys %count;
+````
+
+````perl (tools/rename.pl) [{"args": ["--dry-run"]}]
+````
+
+stdout streams to `#stdout`, stderr to `#stderr`; `die` or a nonzero `exit`
+closes with status 500. The environment is scoped exactly as for `sh`
+(plurnk's own settings and provider keys are stripped). Use `-n`/`-p`-style
+one-liners by writing the loop yourself, or run a script target over the
+files you name in `{args}`.

package/docs/python3.md

@@ -0,0 +1,26 @@
+# python3
+
+For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
+returned execution address; `[{"eof": true}]` closes stdin. See the
+[live-input example](node.md#live-input), including newline framing.
+
+The body is Python code, run with `python3 -c`. A script target instead runs
+that file and receives the body as stdin. Script arguments and working directory
+are optional header metadata:
+
+````python3 <!-- the body is the program -->
+import json, sys
+print(json.dumps({"python": list(sys.version_info[:2])}))
+````
+
+````python3 (tools/report.py) [{"args": ["--help"]}]
+````
+
+Each argument is a literal string, without shell expansion. `[{"cwd": "<directory>"}]`
+selects the working directory; otherwise it remains the workspace root. The
+same options apply to local and `worker://` script targets. Native skill files
+retain their sibling imports and source-relative assets.
+
+`[{"env": {"NAME": "value"}}]` on the same fence line sets variables for this run
+alone, over the entries in your `env` registry; names are the shell's, and plurnk's own
+(`PLURNK_*`, provider credentials) are refused by name.

package/docs/ruby.md

@@ -0,0 +1,26 @@
+# ruby
+
+For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
+returned execution address; `[{"eof": true}]` closes stdin. See the
+[live-input example](node.md#live-input), including newline framing.
+
+The body is Ruby code, run with `ruby -e`. A script target runs that file and
+receives the body as stdin; `[{"args": [...]}]` passes literal `ARGV` entries.
+
+````ruby <!-- the body is the program -->
+require "json"
+words = %w[alpha beta alpha]
+puts JSON.generate(words.tally)
+````
+
+````ruby (bin/migrate.rb) [{"args": ["--check"]}]
+````
+
+`puts` and `print` stream to `#stdout`, `warn` to `#stderr`; an unrescued
+exception or `exit 1` closes with status 500 with the backtrace on stderr.
+Gems resolve from the project's ordinary Ruby environment; `[{"cwd": "<directory>"}]`
+selects the working directory when the project's `Gemfile` lives elsewhere.
+
+`[{"env": {"NAME": "value"}}]` on the same fence line sets variables for this run
+alone, over the entries in your `env` registry; names are the shell's, and plurnk's own
+(`PLURNK_*`, provider credentials) are refused by name.

package/docs/sh.md

@@ -1,7 +1,15 @@
 # sh
 
-A bare `EXEC` is the shell. The body is the command line, run via `sh -c`,
-character-perfect including whitespace. `[sh]` names the shell explicitly.
+For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
+returned execution address; `[{"eof": true}]` closes stdin. See the
+[live-input example](node.md#live-input), including newline framing.
+
+The `sh` fence runs the body via `sh -c`, character-perfect including whitespace.
+
+````sh <!-- the body is the script itself -->
+printf 'hello\n' > hello.txt
+wc -l hello.txt
+````
 
 ## Environment
 
@@ -13,51 +21,76 @@ read plurnk's credentials. The project's environment passes through.
 
 The working directory is the workspace project root — where file operations
 write — or, in a workspace without one, the directory the shell would run in
-anyway. A `{cwd=<directory>}` block on the heading overrides it for its body:
+anyway. A `[{"cwd": "<directory>"}]` block on the opening fence line overrides it for its body:
 
-```example
-### EXEC0 {cwd=./dir}
+````sh [{"cwd": "./dir"}]
 pwd
-```
+````
 
 The receipt always names the directory the command ran in.
 
-A script target runs that script: `### EXEC0 (greet.sh)` runs it with an empty
+`env` on the same line sets variables for this run alone, over the entries in
+your `env` registry; plurnk's own names (`PLURNK_*`, provider credentials) are
+refused by name:
+
+````sh [{"env": {"LC_ALL": "C"}}]
+sort names.txt
+````
+
+A script target runs that script: `sh (greet.sh)` runs it with an empty
 stdin; a nonempty body becomes its stdin. The interpreter reads the script
 directly, so it needs no executable bit; a script path authored inside a shell
 body still follows the kernel's ordinary executable-bit rules.
 
+Script arguments go in `[{"args": ["--release","two words"]}]`: each string is
+one literal argument, without shell expansion. The same options apply to
+local, `worker://`, and `skill://` script targets across the common interpreters.
+
 The target is a program — a script — never a command and never a directory. A
 target that is not a script is refused before anything runs.
 
 ## Channels
 
 Every shell invocation is host-effecting and proposes for review before it
-runs. Output then streams under the emitted
-`sh:///<loop>/<turn>/<sequence>` address: `#stdout` is the default channel and
-`#stderr` is the second; both are `text/stream`. While it runs, Child Streams
-reports each channel's size and growth and READ can inspect any range. On
-completion, one terminal delta becomes visible. A nonzero exit closes with
-status 500; inspect both channels
-because either may carry the useful diagnostic.
+runs. Output then streams under the receipt's `stream` address, such as
+`sh:///ab3d5678`: `#stdout` is the default channel and
+`#stderr` is the second; both are `text/stream`. While it runs, the packet's
+`## Delegation` streams list reports each channel's size and growth and READ can
+inspect any range. On
+completion, the harness adds one `_plurnk` READ per channel: its first page
+(up to 16 lines), `range` extent, and terminal exit status. READ the `stream`
+address for more; the `log:///…/READ` item holds only its recorded page:
+
+````READ (sh:///ab3d5678#stdout) <17,40>
+````
+
+A nonzero exit closes with status 500; inspect both channels because either
+may carry the useful diagnostic.
+
+The `log:///…/sh` receipt's own body is the program exactly as you sent it,
+never output: output lives on the stream and in the harness READs. A receipt
+with a non-200 status and no `stream` address ran nothing; its body is still
+your program, and its Problem says why it was refused.
 
 ## Deadlines & polling — `<timeout, poll>`
 
-For a long-running command, the `<L>` slot carries `<TIMEOUT_SECONDS, POLL_SECONDS>` (both seconds):
+For a long-running command, the `<L>` slot carries `<timeout, poll>` in minutes:
 
-```example
-### EXEC0 <1800>
+````sh <30>
 npm run build
+````
 
-### EXEC0 <1800,300>
+````sh <30,5>
 npm run e2e
+````
 
-### EXEC0 <-1,300>
+````sh <-1,5>
 npm run test
+````
 
-### EXEC0 <-1,0>
+````sh <-1,0>
 tail -f app.log
-```
+````
 
 The first coordinate is the timeout: a positive value kills at that deadline;
 `-1` declines the deadline and the process outlives the loop — it runs until it

package/docs/tcl.md

@@ -0,0 +1,23 @@
+# tcl
+
+For continuing input, launch with `[{"stdin": "open"}]`, then SEND exact text to the
+returned execution address; `[{"eof": true}]` closes stdin. See the
+[live-input example](node.md#live-input), including newline framing.
+
+The body is a Tcl script fed to `tclsh` on stdin (a trailing newline is added).
+A script target runs that file and receives the body as stdin; `[{"args": [...]}]`
+passes literal arguments, readable as `$argv`.
+
+````tcl <!-- the body is the program -->
+set words {alpha beta alpha}
+foreach w $words { dict incr count $w }
+puts [dict get $count alpha]
+````
+
+````tcl (tests/all.tcl) [{"args": ["-verbose","bps"]}]
+````
+
+`puts` streams to `#stdout`, `puts stderr ...` to `#stderr`; an uncaught error
+or `exit 1` closes with status 500 with the Tcl error info on stderr. tclsh
+evaluates the script line by line, so an incomplete command at the end is an
+error, not a silent no-op.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@plurnk/plurnk-execs-common",
-    "version": "1.16.5",
+    "version": "1.18.0",
     "description": "Universal subprocess executor for plurnk-service's exec scheme — one package exposing the shell, Node.js, Python 3, and supported host interpreters.",
     "keywords": [
         "plurnk",
@@ -67,7 +67,9 @@
                         "required": false,
                         "kind": "script"
                     },
-                    "signature": "JavaScript code"
+                    "example": {
+                        "body": "console.log(42)"
+                    }
                 }
             },
             {
@@ -84,7 +86,9 @@
                         "required": false,
                         "kind": "script"
                     },
-                    "signature": "Python code"
+                    "example": {
+                        "body": "print(42)"
+                    }
                 }
             },
             {
@@ -101,7 +105,9 @@
                         "required": false,
                         "kind": "script"
                     },
-                    "signature": "Perl code"
+                    "example": {
+                        "body": "print 42;"
+                    }
                 }
             },
             {
@@ -118,7 +124,9 @@
                         "required": false,
                         "kind": "script"
                     },
-                    "signature": "Ruby code"
+                    "example": {
+                        "body": "puts 42"
+                    }
                 }
             },
             {
@@ -135,7 +143,9 @@
                         "required": false,
                         "kind": "script"
                     },
-                    "signature": "Lua code"
+                    "example": {
+                        "body": "print(42)"
+                    }
                 }
             },
             {
@@ -152,7 +162,9 @@
                         "required": false,
                         "kind": "script"
                     },
-                    "signature": "TypeScript or JavaScript code"
+                    "example": {
+                        "body": "console.log(42)"
+                    }
                 }
             },
             {
@@ -169,7 +181,9 @@
                         "required": false,
                         "kind": "script"
                     },
-                    "signature": "TypeScript or JavaScript code"
+                    "example": {
+                        "body": "console.log(42)"
+                    }
                 }
             },
             {
@@ -186,7 +200,9 @@
                         "required": false,
                         "kind": "script"
                     },
-                    "signature": "Tcl code"
+                    "example": {
+                        "body": "puts 42"
+                    }
                 }
             },
             {
@@ -203,7 +219,9 @@
                         "required": false,
                         "kind": "script"
                     },
-                    "signature": "bc expression or code"
+                    "example": {
+                        "body": "6 * 7"
+                    }
                 }
             },
             {
@@ -220,7 +238,9 @@
                         "required": false,
                         "kind": "script"
                     },
-                    "signature": "AWK code"
+                    "example": {
+                        "body": "BEGIN { print 42 }"
+                    }
                 }
             }
         ]
@@ -250,6 +270,6 @@
         "prepublishOnly": "npm audit --audit-level=moderate && npm test"
     },
     "peerDependencies": {
-        "@plurnk/plurnk-execs": "^1.16.5"
+        "@plurnk/plurnk-execs": "^1.18.0"
     }
 }