@plurnk/plurnk-execs-common 1.5.0 โ†’ 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +25 -15
  2. package/docs/node.md +4 -2
  3. package/docs/sh.md +23 -9
  4. package/package.json +213 -16
package/README.md CHANGED
@@ -13,29 +13,39 @@ The manifest claims the subprocess tags. Per-tag `probe()` reports Node
13
13
  unconditionally because the daemon already runs on it. A cheap `command -v`
14
14
  detects every other interpreter, so one executor adapts to the host.
15
15
 
16
- | Tag | Binary | Command via |
16
+ | Tag | Binary | Inline body via |
17
17
  | -------------------------------- | ----------------- | ---------------------------------------- |
18
- | `sh` ๐Ÿš / `bash` ๐Ÿš | sh / bash | `-c <command>` |
19
- | `node` โฌข | node | `-e <command>` (always available) |
20
- | `python` / `python3` ๐Ÿ | python3 | `-c <command>` |
21
- | `perl` ๐Ÿช / `ruby` ๐Ÿ’Ž / `lua` ๐ŸŒ™ | perl / ruby / lua | `-e <command>` |
22
- | `php` ๐Ÿ˜ | php | `-r <command>` |
23
- | `deno` ๐Ÿฆ• | deno | `eval <command>` |
24
- | `bun` ๐ŸฅŸ | bun | `-e <command>` |
18
+ | `sh` ๐Ÿš / `bash` ๐Ÿš | sh / bash | `-c <body>` |
19
+ | `node` โฌข | node | `-e <body>` (always available) |
20
+ | `python` / `python3` ๐Ÿ | python3 | `-c <body>` |
21
+ | `perl` ๐Ÿช / `ruby` ๐Ÿ’Ž / `lua` ๐ŸŒ™ | perl / ruby / lua | `-e <body>` |
22
+ | `php` ๐Ÿ˜ | php | `-r <body>` |
23
+ | `deno` ๐Ÿฆ• | deno | `eval <body>` |
24
+ | `bun` ๐ŸฅŸ | bun | `-e <body>` |
25
25
  | `tcl` ๐Ÿชถ | tclsh | stdin |
26
26
  | `bc` ๐Ÿงฎ | bc | stdin (for example, `6 * 7`) |
27
27
  | `awk` ๐Ÿช„ | awk | program arg, empty stdin (`BEGIN { โ€ฆ }`) |
28
28
 
29
- ### A program with stdin โ€” the `(target)` slot
29
+ ### A script or working directory โ€” the `(target)` slot
30
30
 
31
- The table above is the **inline** form: `command` is the program. Put a program
32
- in the **`(target)` slot** instead and `command` becomes its **stdin**โ€”a shell
33
- runs `sh -c "<target>"` (the shell tokenizes it), while another interpreter
34
- runs `<interpreter> <target>` as a script file ({ยงexecutor-subprocess-routing}).
31
+ The table above is the **inline** form: the body is the program. A file in the
32
+ `(target)` slot is instead the script each interpreter reads directly, and the
33
+ body becomes that script's stdin. A directory target becomes the working
34
+ directory and the body remains the inline program
35
+ ({ยงexecutor-subprocess-routing}).
35
36
 
36
37
  ```plurnk
37
- <<EXEC[sh](./deploy.sh --prod):yes\nyes\nno:EXEC
38
- <<EXEC[python](transform.py):3\n1\n4\n1\n5:EXEC
38
+ ## EXEC0 [sh] (./deploy.sh)
39
+ yes
40
+ yes
41
+ no
42
+
43
+ ## EXEC0 [python] (transform.py)
44
+ 3
45
+ 1
46
+ 4
47
+ 1
48
+ 5
39
49
  ```
40
50
 
41
51
  The first operation answers a shell script's prompts through stdin. The second
package/docs/node.md CHANGED
@@ -16,5 +16,7 @@ on stderr.
16
16
 
17
17
  ## Working directory
18
18
 
19
- Runs in the workspace project root by default. `EXEC[node](./dir):โ€ฆ` sets the
20
- working directory; relative module and filesystem paths resolve against it.
19
+ Runs in the workspace project root by default. A directory target sets the
20
+ working directory; a file target runs that JavaScript file and receives the
21
+ body as stdin. Relative module and filesystem paths resolve against the selected
22
+ working directory.
package/docs/sh.md CHANGED
@@ -1,6 +1,7 @@
1
1
  # sh
2
2
 
3
- A shell command line, run via `sh -c`. Bare `EXEC` (no runtime tag) defaults to `sh`, so `<<EXEC:ls -la:EXEC` and `<<EXEC[sh]:ls -la:EXEC` are equivalent.
3
+ A shell command line, run via `sh -c`. Bare `EXEC` (no runtime tag) defaults
4
+ to `sh`, so `## EXEC0` and `## EXEC0 [sh]` are equivalent headings.
4
5
 
5
6
  ## Environment
6
7
 
@@ -10,14 +11,20 @@ read plurnk's credentials. The project's environment passes through.
10
11
 
11
12
  ## Working directory
12
13
 
13
- `EXEC[sh](./dir):โ€ฆ` runs in `./dir`. With no target, the command runs in the
14
- workspace project root where file operations writeโ€”not in the daemon's own
15
- working directory.
14
+ The target in this operation makes `./dir` the working directory for its body:
15
+
16
+ ```plurnk
17
+ ## EXEC0 [sh] (./dir)
18
+ pwd
19
+ ```
20
+
21
+ With no target, the command runs in the workspace project root where file
22
+ operations writeโ€”not in the daemon's own working directory.
16
23
 
17
24
  The target's filesystem type selects its role:
18
25
 
19
26
  - A directory becomes the working directory.
20
- - A file is the script to run. `<<EXEC[sh](greet.sh)::EXEC` runs it with an
27
+ - A file is the script to run. `## EXEC0 [sh] (greet.sh)` runs it with an
21
28
  empty stdin; a nonempty body becomes stdin.
22
29
 
23
30
  The interpreter reads a targeted file directly, so it needs no executable bit.
@@ -39,10 +46,17 @@ because either may carry the useful diagnostic.
39
46
  For a long-running command, the `<L>` slot carries `<TIMEOUT_SECONDS, POLL_SECONDS>` (both seconds):
40
47
 
41
48
  ```plurnk
42
- <<EXEC<1800>:npm run build:EXEC
43
- <<EXEC<1800,300>:npm run e2e:EXEC
44
- <<EXEC<-1,300>:npm run test:EXEC
45
- <<EXEC<-1,0>:tail -f app.log:EXEC
49
+ ## EXEC0 <1800>
50
+ npm run build
51
+
52
+ ## EXEC0 <1800,300>
53
+ npm run e2e
54
+
55
+ ## EXEC0 <-1,300>
56
+ npm run test
57
+
58
+ ## EXEC0 <-1,0>
59
+ tail -f app.log
46
60
  ```
47
61
 
48
62
  The first coordinate is the timeout: a positive value kills at that deadline;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@plurnk/plurnk-execs-common",
3
- "version": "1.5.0",
3
+ "version": "1.6.0",
4
4
  "description": "Universal subprocess executor for plurnk-service's exec scheme โ€” one package exposing the shell + node + python floor plus whichever host interpreters (perl, ruby, php, lua, awk, bc, โ€ฆ) are present.",
5
5
  "keywords": [
6
6
  "plurnk",
@@ -37,71 +37,268 @@
37
37
  {
38
38
  "name": "sh",
39
39
  "glyph": "๐Ÿš",
40
- "example": "<<EXEC:uname -sr:EXEC\n<<EXEC[sh](build.sh)::EXEC\n<<EXEC<-1,300>:npm run test:EXEC"
40
+ "invocation": {
41
+ "body": {
42
+ "role": "shell program; stdin with a targeted script file",
43
+ "required": false
44
+ },
45
+ "target": {
46
+ "role": "script file",
47
+ "required": false,
48
+ "kind": "resource",
49
+ "directory": "cwd"
50
+ },
51
+ "example": {
52
+ "body": "pwd"
53
+ }
54
+ }
41
55
  },
42
56
  {
43
57
  "name": "bash",
44
- "glyph": "๐Ÿš"
58
+ "glyph": "๐Ÿš",
59
+ "invocation": {
60
+ "body": {
61
+ "role": "Bash program; stdin with a targeted script file",
62
+ "required": false
63
+ },
64
+ "target": {
65
+ "role": "script file",
66
+ "required": false,
67
+ "kind": "resource",
68
+ "directory": "cwd"
69
+ },
70
+ "example": {
71
+ "body": "npm test"
72
+ }
73
+ }
45
74
  },
46
75
  {
47
76
  "name": "node",
48
77
  "glyph": "โฌข",
49
- "example": "<<EXEC[node]:console.log(new Date(Date.now() + 14 * 86_400_000).toISOString().slice(0, 10)):EXEC"
78
+ "invocation": {
79
+ "body": {
80
+ "role": "JavaScript program; stdin with a targeted script file",
81
+ "required": false
82
+ },
83
+ "target": {
84
+ "role": "script file",
85
+ "required": false,
86
+ "kind": "resource",
87
+ "directory": "cwd"
88
+ },
89
+ "example": {
90
+ "body": "console.log(process.version);"
91
+ }
92
+ }
50
93
  },
51
94
  {
52
95
  "name": "python",
53
96
  "glyph": "๐Ÿ",
54
- "example": "<<EXEC[python]:print(sum(range(101))):EXEC"
97
+ "invocation": {
98
+ "body": {
99
+ "role": "Python program; stdin with a targeted script file",
100
+ "required": false
101
+ },
102
+ "target": {
103
+ "role": "script file",
104
+ "required": false,
105
+ "kind": "resource",
106
+ "directory": "cwd"
107
+ },
108
+ "example": {
109
+ "body": "print(\"hello\")"
110
+ }
111
+ }
55
112
  },
56
113
  {
57
114
  "name": "python3",
58
115
  "glyph": "๐Ÿ",
59
- "example": "<<EXEC[python3]:print(sum(range(101))):EXEC"
116
+ "invocation": {
117
+ "body": {
118
+ "role": "Python program; stdin with a targeted script file",
119
+ "required": false
120
+ },
121
+ "target": {
122
+ "role": "script file",
123
+ "required": false,
124
+ "kind": "resource",
125
+ "directory": "cwd"
126
+ },
127
+ "example": {
128
+ "body": "print(\"hello\")"
129
+ }
130
+ }
60
131
  },
61
132
  {
62
133
  "name": "perl",
63
134
  "glyph": "๐Ÿช",
64
- "example": "<<EXEC[perl]:print join(',', 1..5):EXEC"
135
+ "invocation": {
136
+ "body": {
137
+ "role": "Perl program; stdin with a targeted script file",
138
+ "required": false
139
+ },
140
+ "target": {
141
+ "role": "script file",
142
+ "required": false,
143
+ "kind": "resource",
144
+ "directory": "cwd"
145
+ },
146
+ "example": {
147
+ "body": "print \"hello\\n\";"
148
+ }
149
+ }
65
150
  },
66
151
  {
67
152
  "name": "ruby",
68
153
  "glyph": "๐Ÿ’Ž",
69
- "example": "<<EXEC[ruby]:puts (1..5).sum:EXEC"
154
+ "invocation": {
155
+ "body": {
156
+ "role": "Ruby program; stdin with a targeted script file",
157
+ "required": false
158
+ },
159
+ "target": {
160
+ "role": "script file",
161
+ "required": false,
162
+ "kind": "resource",
163
+ "directory": "cwd"
164
+ },
165
+ "example": {
166
+ "body": "puts \"hello\""
167
+ }
168
+ }
70
169
  },
71
170
  {
72
171
  "name": "php",
73
172
  "glyph": "๐Ÿ˜",
74
- "example": "<<EXEC[php]:echo array_sum([1,2,3]);:EXEC"
173
+ "invocation": {
174
+ "body": {
175
+ "role": "PHP program; stdin with a targeted script file",
176
+ "required": false
177
+ },
178
+ "target": {
179
+ "role": "script file",
180
+ "required": false,
181
+ "kind": "resource",
182
+ "directory": "cwd"
183
+ },
184
+ "example": {
185
+ "body": "<?php echo \"hello\\n\";"
186
+ }
187
+ }
75
188
  },
76
189
  {
77
190
  "name": "lua",
78
191
  "glyph": "๐ŸŒ™",
79
- "example": "<<EXEC[lua]:print(('hi'):upper()):EXEC"
192
+ "invocation": {
193
+ "body": {
194
+ "role": "Lua program; stdin with a targeted script file",
195
+ "required": false
196
+ },
197
+ "target": {
198
+ "role": "script file",
199
+ "required": false,
200
+ "kind": "resource",
201
+ "directory": "cwd"
202
+ },
203
+ "example": {
204
+ "body": "print(\"hello\")"
205
+ }
206
+ }
80
207
  },
81
208
  {
82
209
  "name": "deno",
83
210
  "glyph": "๐Ÿฆ•",
84
- "example": "<<EXEC[deno]:console.log(Deno.version.deno):EXEC"
211
+ "invocation": {
212
+ "body": {
213
+ "role": "Deno program; stdin with a targeted script file",
214
+ "required": false
215
+ },
216
+ "target": {
217
+ "role": "script file",
218
+ "required": false,
219
+ "kind": "resource",
220
+ "directory": "cwd"
221
+ },
222
+ "example": {
223
+ "body": "console.log(Deno.version.deno);"
224
+ }
225
+ }
85
226
  },
86
227
  {
87
228
  "name": "bun",
88
229
  "glyph": "๐ŸฅŸ",
89
- "example": "<<EXEC[bun]:console.log(Bun.version):EXEC"
230
+ "invocation": {
231
+ "body": {
232
+ "role": "Bun program; stdin with a targeted script file",
233
+ "required": false
234
+ },
235
+ "target": {
236
+ "role": "script file",
237
+ "required": false,
238
+ "kind": "resource",
239
+ "directory": "cwd"
240
+ },
241
+ "example": {
242
+ "body": "console.log(Bun.version);"
243
+ }
244
+ }
90
245
  },
91
246
  {
92
247
  "name": "tcl",
93
248
  "glyph": "๐Ÿชถ",
94
- "example": "<<EXEC[tcl]:puts [expr {2**10}]:EXEC"
249
+ "invocation": {
250
+ "body": {
251
+ "role": "Tcl program; stdin with a targeted script file",
252
+ "required": false
253
+ },
254
+ "target": {
255
+ "role": "script file",
256
+ "required": false,
257
+ "kind": "resource",
258
+ "directory": "cwd"
259
+ },
260
+ "example": {
261
+ "body": "puts \"hello\""
262
+ }
263
+ }
95
264
  },
96
265
  {
97
266
  "name": "bc",
98
267
  "glyph": "๐Ÿงฎ",
99
- "example": "<<EXEC[bc]:scale=4; 22/7:EXEC"
268
+ "invocation": {
269
+ "body": {
270
+ "role": "bc program; stdin with a targeted script file",
271
+ "required": false
272
+ },
273
+ "target": {
274
+ "role": "script file",
275
+ "required": false,
276
+ "kind": "resource",
277
+ "directory": "cwd"
278
+ },
279
+ "example": {
280
+ "body": "2 + 2"
281
+ }
282
+ }
100
283
  },
101
284
  {
102
285
  "name": "awk",
103
286
  "glyph": "๐Ÿช„",
104
- "example": "<<EXEC[awk]:BEGIN { print 6 * 7 }:EXEC"
287
+ "invocation": {
288
+ "body": {
289
+ "role": "AWK program; stdin with a targeted script file",
290
+ "required": false
291
+ },
292
+ "target": {
293
+ "role": "script file",
294
+ "required": false,
295
+ "kind": "resource",
296
+ "directory": "cwd"
297
+ },
298
+ "example": {
299
+ "body": "BEGIN { print \"hello\" }"
300
+ }
301
+ }
105
302
  }
106
303
  ]
107
304
  },
@@ -130,6 +327,6 @@
130
327
  "prepublishOnly": "npm audit --audit-level=moderate && npm test"
131
328
  },
132
329
  "peerDependencies": {
133
- "@plurnk/plurnk-execs": "^1.5.0"
330
+ "@plurnk/plurnk-execs": "^1.6.0"
134
331
  }
135
332
  }