@niwa-labs/proc 0.0.0-stage → 0.0.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.
- package/LICENSE +21 -0
- package/README.md +45 -2
- package/package.json +18 -4
- package/src/artifact.ts +225 -0
- package/src/box-rules.ts +40 -0
- package/src/flow.ts +146 -0
- package/src/index.ts +316 -0
- package/src/records.ts +184 -0
- package/src/refusal.ts +17 -0
- package/src/supervise.ts +152 -0
- package/test/artifact.test.ts +214 -0
- package/test/budget.test.ts +55 -0
- package/test/cancel.test.ts +81 -0
- package/test/exec.test.ts +154 -0
- package/test/flow.test.ts +107 -0
- package/test/grant.test.ts +136 -0
- package/test/live.test.ts +178 -0
- package/test/records.test.ts +46 -0
- package/test/refusal.test.ts +113 -0
- package/test/run.test.ts +273 -0
- package/test/supervise.test.ts +127 -0
- package/test/support.ts +178 -0
- package/tsconfig.json +6 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Niwa Labs contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,46 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @niwa-labs/proc
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Running commands.
|
|
4
|
+
|
|
5
|
+
- `proc.run { cmd, cwd, timeout, env?, box? }` always runs in a box from `@niwa-labs/sandbox`: it writes `cwd`, a
|
|
6
|
+
temp directory inside it (`TMPDIR`, also `TMP`, `TEMP`, removed after the run) and the places of the profiles it
|
|
7
|
+
takes; it has no network and no credentials. Because the box holds that, the action is a write in the local world.
|
|
8
|
+
`HOME` is the user's own. The box is the host's default (`proc({ box })`, by default `{ allow: ["toolchains"] }`:
|
|
9
|
+
the PATH, Homebrew and the catalog's programs, readable), what `box.allow` adds or what `box.only` puts instead: a
|
|
10
|
+
profile by its name (`git`, `bun`, `npm`, `node`, `cargo`, `uv`, the host's own), `"toolchains"`, `{ read }`,
|
|
11
|
+
`{ write }`. The places of every profile the run does not take (every harness installation's among them), the
|
|
12
|
+
user's keys (`~/.ssh`, `~/.aws`, `~/.gnupg`, `~/Library/Keychains`) and niwa's journal and secrets are closed to it.
|
|
13
|
+
A host it asks for is refused: a command that needs the network or a credential is for `proc.exec`. Going beyond
|
|
14
|
+
the default needs the caller's `box.use@<profile>`, `box.read@<path>` or `box.write@<path>` rule. A box that cannot
|
|
15
|
+
run here, or that its sandbox cannot hold as it was asked (nono by default, `proc({ sandbox: sandbox({ adapter })
|
|
16
|
+
})` for another), stops the call before a process exists, with every reason. The `box` of the result and of
|
|
17
|
+
`proc.finished` is the box's manifest: the request and where each item came from, the paths and theirs, what was
|
|
18
|
+
closed and left out, the rules taken, the policy the sandbox applies and the names of the environment.
|
|
19
|
+
- `proc.exec { cmd, cwd, timeout, env?, net?, secrets? }` runs with no box. It is irreversible and external, so a
|
|
20
|
+
grant names it. `env` values may be `secret("name")` references (`secret()` is exported by `@niwa-labs/core`)
|
|
21
|
+
and `secrets` lists secrets given as variables of their own names; values are resolved from
|
|
22
|
+
`<home>/secrets/<name>` (mode 0600) or `NIWA_SECRET_<name>`, and are never written to a record, result or error.
|
|
23
|
+
Known values are replaced in the output.
|
|
24
|
+
|
|
25
|
+
`cmd` is the program and its arguments, run as they are; a shell is `["sh", "-c", "…"]`. A command that outlasts
|
|
26
|
+
`timeout` (milliseconds), or whose call is cancelled, is stopped with the process group it leads, and so is
|
|
27
|
+
anything left running in that group once the command exits. The limit of that: a process that moved to another
|
|
28
|
+
group (`setsid`) is not reached, and a command still running when the host itself dies is not stopped by it; the
|
|
29
|
+
`do-not-repeat` contract keeps it from being run again, not from running on.
|
|
30
|
+
|
|
31
|
+
A grant names the directory a command runs in by its real path: `proc.run@/work/repo`, or `proc.run@/work/*` for
|
|
32
|
+
everything under `/work`. A character a rule cannot hold (a space, `*`, `@`, `:`, a brace, and `%` itself) is
|
|
33
|
+
written as `%` and its hex code, so `/work/My Project` is `proc.run@/work/My%20Project`.
|
|
34
|
+
|
|
35
|
+
The output is an artifact under `<home>/artifacts/<sha256>`, flushed before anything points at it. The artifact
|
|
36
|
+
keeps the first 16 MiB of the output (`outputLimit`); with `truncated: true` it holds the start of the output and
|
|
37
|
+
`tail` the end. The result and the `proc.finished` record carry the exit code, how it ended (`exited`,
|
|
38
|
+
`timed-out`, `cancelled`), whether reading the output was cut off (`outputCut`), and a bounded tail. A non-zero
|
|
39
|
+
exit is a result, not an error. A call that could not start a command, because the directory is not there or no
|
|
40
|
+
box could be had, is a `ProcRefusal`: nothing ran.
|
|
41
|
+
|
|
42
|
+
Entries: `@niwa-labs/proc` (the plugin `proc()`), `@niwa-labs/proc/records` (action references, record type,
|
|
43
|
+
`fileTarget()`), which needs core, the box schemas of the sandbox and zod.
|
|
44
|
+
`@niwa-labs/proc/flow` is the script helper `runCheck(key, { cmd, cwd, timeout?, env?, box?, report? })`: it runs a
|
|
45
|
+
check with `proc.run` (with `proc.exec` when `env` holds a secret reference), passes on a zero exit, and reads the
|
|
46
|
+
report a command prints last (`json`, `lcov` totals, `junit` suite counts). It imports nothing.
|
package/package.json
CHANGED
|
@@ -1,6 +1,20 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@niwa-labs/proc",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"license": "MIT",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": "./src/index.ts",
|
|
8
|
+
"./records": "./src/records.ts",
|
|
9
|
+
"./flow": "./src/flow.ts"
|
|
10
|
+
},
|
|
11
|
+
"dependencies": {
|
|
12
|
+
"@niwa-labs/core": "0.0.0",
|
|
13
|
+
"@niwa-labs/plugin": "0.0.0",
|
|
14
|
+
"@niwa-labs/sandbox": "0.0.0",
|
|
15
|
+
"zod": "^4.6.7"
|
|
16
|
+
},
|
|
17
|
+
"devDependencies": {
|
|
18
|
+
"@niwa-labs/testing": "0.0.0"
|
|
19
|
+
}
|
|
20
|
+
}
|
package/src/artifact.ts
ADDED
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Command output as an artifact of the host: bytes kept whole under the digest of their content.
|
|
3
|
+
*
|
|
4
|
+
* The output of a command goes to a writer of the host's artifact store as it arrives, and is made
|
|
5
|
+
* durable and named when the command is over, so a record that points at it never points at one a
|
|
6
|
+
* crash could take. The same bytes are the same artifact.
|
|
7
|
+
*
|
|
8
|
+
* Known secret values are replaced before a byte is written, and before it is kept in the tail:
|
|
9
|
+
* a secret that straddles two chunks is still found, because the end of a chunk is held back until
|
|
10
|
+
* the next one shows it cannot start a secret. The chunks of the two streams keep the order they came in.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import type { ArtifactRef, ArtifactStore, ArtifactWriter } from "@niwa-labs/core";
|
|
14
|
+
|
|
15
|
+
/** What stands where a secret was. */
|
|
16
|
+
export const REDACTED = Buffer.from("***");
|
|
17
|
+
|
|
18
|
+
/** Replaces every known secret in a stream of chunks. One per stream: the held-back end belongs to it. */
|
|
19
|
+
export class Scrubber {
|
|
20
|
+
readonly #secrets: readonly Buffer[];
|
|
21
|
+
readonly #hold: number;
|
|
22
|
+
#held: Buffer = Buffer.alloc(0);
|
|
23
|
+
|
|
24
|
+
constructor(secrets: readonly string[]) {
|
|
25
|
+
this.#secrets = secrets.filter((value) => value.length > 0).map((value) => Buffer.from(value));
|
|
26
|
+
this.#hold = Math.max(0, ...this.#secrets.map((value) => value.length - 1));
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** The part of the stream that can no longer change. */
|
|
30
|
+
push(chunk: Uint8Array): Buffer {
|
|
31
|
+
const all = this.#replace(Buffer.concat([this.#held, chunk]));
|
|
32
|
+
const keep = Math.min(all.length, this.#hold);
|
|
33
|
+
this.#held = all.subarray(all.length - keep);
|
|
34
|
+
return all.subarray(0, all.length - keep);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** The held-back end, once the stream is over. */
|
|
38
|
+
end(): Buffer {
|
|
39
|
+
const rest = this.#replace(this.#held);
|
|
40
|
+
this.#held = Buffer.alloc(0);
|
|
41
|
+
return rest;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
#replace(bytes: Buffer): Buffer {
|
|
45
|
+
let out = bytes;
|
|
46
|
+
for (const secret of this.#secrets) {
|
|
47
|
+
const parts: Buffer[] = [];
|
|
48
|
+
let from = 0;
|
|
49
|
+
for (let at = out.indexOf(secret, from); at !== -1; at = out.indexOf(secret, from)) {
|
|
50
|
+
parts.push(out.subarray(from, at), REDACTED);
|
|
51
|
+
from = at + secret.length;
|
|
52
|
+
}
|
|
53
|
+
if (parts.length > 0) out = Buffer.concat([...parts, out.subarray(from)]);
|
|
54
|
+
}
|
|
55
|
+
return out;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export interface CaptureOptions {
|
|
60
|
+
/** The store the output is kept in. */
|
|
61
|
+
readonly artifacts: ArtifactStore;
|
|
62
|
+
/** Values to remove from the output before anything is kept. */
|
|
63
|
+
readonly secrets: readonly string[];
|
|
64
|
+
/** The most bytes kept in the artifact; the rest of the output is read and dropped. */
|
|
65
|
+
readonly limit: number;
|
|
66
|
+
/** The bytes of the end of the output shown in the result. */
|
|
67
|
+
readonly tailBytes: number;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** What a finished capture gives back. */
|
|
71
|
+
export interface Captured {
|
|
72
|
+
readonly output: ArtifactRef;
|
|
73
|
+
readonly tail: string;
|
|
74
|
+
readonly truncated: boolean;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** The most bytes a stream's held-back end may keep the other stream waiting for. */
|
|
78
|
+
const HELD_LIMIT = 256 * 1024;
|
|
79
|
+
|
|
80
|
+
type Stream = "out" | "err";
|
|
81
|
+
|
|
82
|
+
/** A chunk as it came, waiting for what is held back before it to be settled. */
|
|
83
|
+
interface Piece {
|
|
84
|
+
readonly stream: Stream;
|
|
85
|
+
readonly bytes: Buffer;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* Where a known secret lies in `bytes`: the spans, merged and in order. `carry` bytes at the start
|
|
90
|
+
* are the rest of a secret whose beginning was already written as its replacement.
|
|
91
|
+
*/
|
|
92
|
+
function spansOf(secrets: readonly Buffer[], bytes: Buffer, carry: number): Array<[number, number]> {
|
|
93
|
+
const found: Array<[number, number]> = carry > 0 ? [[-1, carry]] : [];
|
|
94
|
+
for (const secret of secrets) {
|
|
95
|
+
for (let at = bytes.indexOf(secret); at !== -1; at = bytes.indexOf(secret, at + 1)) found.push([at, at + secret.length]);
|
|
96
|
+
}
|
|
97
|
+
found.sort((a, b) => a[0] - b[0]);
|
|
98
|
+
const merged: Array<[number, number]> = [];
|
|
99
|
+
for (const span of found) {
|
|
100
|
+
const last = merged[merged.length - 1];
|
|
101
|
+
if (last !== undefined && span[0] < last[1]) last[1] = Math.max(last[1], span[1]);
|
|
102
|
+
else merged.push([span[0], span[1]]);
|
|
103
|
+
}
|
|
104
|
+
return merged;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* One command's output, from the first byte to the artifact.
|
|
109
|
+
*
|
|
110
|
+
* With no secret to hold back, a chunk is kept as it comes. With one, each stream is read for
|
|
111
|
+
* secrets on its own, so one that a stream split across chunks is found even when the other
|
|
112
|
+
* stream spoke in between, and the chunks are written in the order they came: a chunk waits
|
|
113
|
+
* behind the end of an earlier one only while that end could still be the start of a secret.
|
|
114
|
+
* What is written then goes through one more scrubber, so a secret the two streams make
|
|
115
|
+
* together, where one ends and the other begins, is found too.
|
|
116
|
+
*/
|
|
117
|
+
export class OutputCapture {
|
|
118
|
+
readonly #options: CaptureOptions;
|
|
119
|
+
readonly #secrets: readonly Buffer[];
|
|
120
|
+
readonly #hold: number;
|
|
121
|
+
readonly #merged: Scrubber;
|
|
122
|
+
readonly #writer: ArtifactWriter;
|
|
123
|
+
#queue: Piece[] = [];
|
|
124
|
+
readonly #scan: Record<Stream, Buffer> = { out: Buffer.alloc(0), err: Buffer.alloc(0) };
|
|
125
|
+
readonly #carry: Record<Stream, number> = { out: 0, err: 0 };
|
|
126
|
+
#size = 0;
|
|
127
|
+
#truncated = false;
|
|
128
|
+
#tail: Buffer = Buffer.alloc(0);
|
|
129
|
+
|
|
130
|
+
constructor(options: CaptureOptions) {
|
|
131
|
+
this.#options = options;
|
|
132
|
+
this.#secrets = options.secrets.filter((value) => value.length > 0).map((value) => Buffer.from(value));
|
|
133
|
+
this.#hold = Math.max(0, ...this.#secrets.map((value) => value.length - 1));
|
|
134
|
+
this.#merged = new Scrubber(options.secrets);
|
|
135
|
+
this.#writer = options.artifacts.writer("text/plain");
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/** The bytes waiting behind a held-back end. */
|
|
139
|
+
get queued(): number {
|
|
140
|
+
return this.#scan.out.length + this.#scan.err.length;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/** Takes a chunk of one of the two streams, in the order it came. */
|
|
144
|
+
feed(stream: Stream, chunk: Uint8Array): void {
|
|
145
|
+
if (this.#secrets.length === 0) {
|
|
146
|
+
this.#keep(Buffer.from(chunk));
|
|
147
|
+
return;
|
|
148
|
+
}
|
|
149
|
+
const bytes = Buffer.from(chunk);
|
|
150
|
+
this.#queue.push({ stream, bytes });
|
|
151
|
+
this.#scan[stream] = Buffer.concat([this.#scan[stream], bytes]);
|
|
152
|
+
// A stream that stays silent while holding the start of a secret must not make the other
|
|
153
|
+
// one pile up in memory: past the limit the held-back ends are let go. A secret that was
|
|
154
|
+
// split there is then written in two parts, and is replaced only if they end up together.
|
|
155
|
+
this.#release(this.queued > HELD_LIMIT);
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/** Flushes what is held back, makes the artifact durable and gives its name. */
|
|
159
|
+
finish(): Captured {
|
|
160
|
+
this.#release(true);
|
|
161
|
+
this.#keep(this.#merged.end());
|
|
162
|
+
return { output: this.#writer.finish(), tail: new TextDecoder().decode(this.#tail), truncated: this.#truncated };
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/** Throws away what was captured: the command never got to its end. */
|
|
166
|
+
discard(): void {
|
|
167
|
+
this.#writer.discard();
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/** Writes the chunks, front first, whose bytes are settled: no secret can still start in them. */
|
|
171
|
+
#release(everything: boolean): void {
|
|
172
|
+
const state = {} as Record<Stream, { spans: Array<[number, number]>; limit: number; offset: number }>;
|
|
173
|
+
for (const stream of ["out", "err"] as const) {
|
|
174
|
+
const scan = this.#scan[stream];
|
|
175
|
+
state[stream] = {
|
|
176
|
+
spans: spansOf(this.#secrets, scan, this.#carry[stream]),
|
|
177
|
+
limit: everything ? scan.length : Math.max(0, scan.length - this.#hold),
|
|
178
|
+
offset: 0,
|
|
179
|
+
};
|
|
180
|
+
}
|
|
181
|
+
const settled: Buffer[] = [];
|
|
182
|
+
let taken = 0;
|
|
183
|
+
for (const piece of this.#queue) {
|
|
184
|
+
const at = state[piece.stream];
|
|
185
|
+
const start = at.offset;
|
|
186
|
+
const end = start + piece.bytes.length;
|
|
187
|
+
if (end > at.limit) break;
|
|
188
|
+
const scan = this.#scan[piece.stream];
|
|
189
|
+
let cursor = start;
|
|
190
|
+
for (const span of at.spans) {
|
|
191
|
+
if (span[1] <= start) continue;
|
|
192
|
+
if (span[0] >= end) break;
|
|
193
|
+
const from = Math.max(span[0], start);
|
|
194
|
+
if (cursor < from) settled.push(scan.subarray(cursor, from));
|
|
195
|
+
if (span[0] >= start) settled.push(REDACTED);
|
|
196
|
+
cursor = Math.min(span[1], end);
|
|
197
|
+
}
|
|
198
|
+
if (cursor < end) settled.push(scan.subarray(cursor, end));
|
|
199
|
+
at.offset = end;
|
|
200
|
+
taken += 1;
|
|
201
|
+
}
|
|
202
|
+
this.#queue = this.#queue.slice(taken);
|
|
203
|
+
for (const stream of ["out", "err"] as const) {
|
|
204
|
+
const { spans, offset } = state[stream];
|
|
205
|
+
// The rest of a secret whose replacement was just written is dropped when its bytes come.
|
|
206
|
+
this.#carry[stream] = Math.max(0, ...spans.filter((span) => span[0] < offset).map((span) => span[1] - offset));
|
|
207
|
+
this.#scan[stream] = this.#scan[stream].subarray(offset);
|
|
208
|
+
}
|
|
209
|
+
if (settled.length > 0) this.#keep(this.#merged.push(Buffer.concat(settled)));
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
#keep(bytes: Buffer): void {
|
|
213
|
+
if (bytes.length === 0) return;
|
|
214
|
+
const { limit, tailBytes } = this.#options;
|
|
215
|
+
const room = Math.max(0, limit - this.#size);
|
|
216
|
+
const stored = bytes.subarray(0, room);
|
|
217
|
+
if (stored.length < bytes.length) this.#truncated = true;
|
|
218
|
+
if (stored.length > 0) {
|
|
219
|
+
this.#writer.write(stored);
|
|
220
|
+
this.#size += stored.length;
|
|
221
|
+
}
|
|
222
|
+
this.#tail = Buffer.concat([this.#tail, bytes]);
|
|
223
|
+
if (this.#tail.length > tailBytes) this.#tail = this.#tail.subarray(this.#tail.length - tailBytes);
|
|
224
|
+
}
|
|
225
|
+
}
|
package/src/box-rules.ts
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The rules that widen a box, as names a grant and a script's `uses` can hold.
|
|
3
|
+
*
|
|
4
|
+
* A box is widened beyond the host's default by the caller's rules `box.use@<profile>`,
|
|
5
|
+
* `box.read@<path>`, `box.write@<path>` and `box.net@<host>`: the action that makes the box (a
|
|
6
|
+
* `proc.run`, a `session.start`) holds them against the grant. They are registered here as actions
|
|
7
|
+
* so a grant and a script can name them like any other; calling one only answers that the caller
|
|
8
|
+
* holds it, since a call its grant does not cover is refused before it runs.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import { realpathSync } from "node:fs";
|
|
12
|
+
import { resolve } from "node:path";
|
|
13
|
+
|
|
14
|
+
import { action } from "@niwa-labs/core";
|
|
15
|
+
import { plugin } from "@niwa-labs/plugin";
|
|
16
|
+
import type { Plugin } from "@niwa-labs/plugin";
|
|
17
|
+
import { placeTarget } from "@niwa-labs/sandbox";
|
|
18
|
+
|
|
19
|
+
import { boxNet, boxRead, boxUse, boxWrite } from "./records.ts";
|
|
20
|
+
|
|
21
|
+
/** The real path of a place, or the place as it is spelled when it is not there. */
|
|
22
|
+
function realOr(path: string): string {
|
|
23
|
+
try {
|
|
24
|
+
return realpathSync(path);
|
|
25
|
+
} catch {
|
|
26
|
+
return resolve(path);
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** The plugin that registers the rules of the box. */
|
|
31
|
+
export function boxRules(): Plugin {
|
|
32
|
+
return plugin("box", (api) => {
|
|
33
|
+
const held = async () => ({ held: true as const });
|
|
34
|
+
const common = { recovery: "repeat", effect: "read", world: "local", run: held } as const;
|
|
35
|
+
api.action(action(boxUse, { ...common, target: (input) => input.profile }));
|
|
36
|
+
api.action(action(boxRead, { ...common, target: (input) => placeTarget(realOr(input.path)) }));
|
|
37
|
+
api.action(action(boxWrite, { ...common, target: (input) => placeTarget(realOr(input.path)) }));
|
|
38
|
+
api.action(action(boxNet, { ...common, target: (input) => input.host }));
|
|
39
|
+
});
|
|
40
|
+
}
|
package/src/flow.ts
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The script helper of the proc module: run a check (tests, a build, a coverage measure) and read
|
|
3
|
+
* how it went.
|
|
4
|
+
*
|
|
5
|
+
* import { runCheck } from "@niwa-labs/proc/flow"
|
|
6
|
+
* const tests = await runCheck("tests", { cmd: ["bun", "test"], cwd: wt.path, timeout: "10m" })
|
|
7
|
+
* if (!tests.ok) ...
|
|
8
|
+
*
|
|
9
|
+
* It runs inside a workflow script on its globals (`scope`, `call`), read when it is called, so it
|
|
10
|
+
* imports nothing at all: a script that imports it pulls no more of niwa into its check. The call
|
|
11
|
+
* is made in a scope named by the key, so two checks need two keys and a check may run again in
|
|
12
|
+
* each round of a loop.
|
|
13
|
+
*
|
|
14
|
+
* A check runs with `proc.run`, in a box: the host's default, with what `box` adds (`allow`) or puts
|
|
15
|
+
* instead (`only`), within the run's `box.*` rules. A check whose environment holds a secret
|
|
16
|
+
* reference runs with `proc.exec`, which has no box: the run's grant has to name that action, and
|
|
17
|
+
* such a check takes no `box`.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
/** A duration as a script writes it: milliseconds, or "500ms", "30s", "5m", "2h". */
|
|
21
|
+
export type Duration = number | string;
|
|
22
|
+
|
|
23
|
+
/** A reference to a secret of the host, `secret("name")` of core: resolved where the command starts. */
|
|
24
|
+
export type SecretRef = { secret: string };
|
|
25
|
+
|
|
26
|
+
/** An artifact of the host: the whole output of a command. */
|
|
27
|
+
export type ArtifactRef = { digest: string; size: number; type: string };
|
|
28
|
+
|
|
29
|
+
/** One thing a box asks for: a profile by its name (`bun`), `"toolchains"`, or a path to read or write. */
|
|
30
|
+
export type BoxItem = string | { read: string } | { write: string };
|
|
31
|
+
|
|
32
|
+
/** A check: the command, where it runs, how long it may take, its environment, its box and the report it prints. */
|
|
33
|
+
export type Check = {
|
|
34
|
+
cmd: string[];
|
|
35
|
+
cwd: string;
|
|
36
|
+
timeout?: Duration;
|
|
37
|
+
env?: Record<string, string | SecretRef>;
|
|
38
|
+
/** What the box of the check has besides the host's default (`allow`), or instead of it (`only`). */
|
|
39
|
+
box?: { allow: BoxItem[] } | { only: BoxItem[] };
|
|
40
|
+
/**
|
|
41
|
+
* The structured report the command prints at the end of its output: `json` its last line, `junit` the
|
|
42
|
+
* counts of its test suites, `lcov` the lines found and hit.
|
|
43
|
+
*/
|
|
44
|
+
report?: "junit" | "lcov" | "json";
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
/** How a check went: whether it passed, its exit code, the end of its output, its report, and the whole output. */
|
|
48
|
+
export type CheckResult = { ok: boolean; exit: number | null; summary: string; report?: unknown; artifact: ArtifactRef };
|
|
49
|
+
|
|
50
|
+
/** What `proc.run` and `proc.exec` answer, as far as a check reads it. */
|
|
51
|
+
type ProcAnswer = { outcome: "exited" | "timed-out" | "cancelled"; exit: number | null; tail: string; output: ArtifactRef };
|
|
52
|
+
|
|
53
|
+
interface Globals {
|
|
54
|
+
call(name: string, input: unknown): Promise<unknown>;
|
|
55
|
+
scope<T>(name: string, opts: undefined, fn: () => Promise<T>): Promise<T>;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
function globals(): Globals {
|
|
59
|
+
const found = globalThis as unknown as Partial<Globals>;
|
|
60
|
+
for (const name of ["call", "scope"] as const) {
|
|
61
|
+
if (typeof found[name] !== "function") throw new Error(`@niwa-labs/proc/flow runs inside a workflow script: "${name}" is not a global here`);
|
|
62
|
+
}
|
|
63
|
+
return found as Globals;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
const UNITS: Record<string, number> = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 };
|
|
67
|
+
|
|
68
|
+
/** A duration in milliseconds. */
|
|
69
|
+
export function durationMs(duration: Duration): number {
|
|
70
|
+
if (typeof duration === "number") return duration;
|
|
71
|
+
const parsed = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h)\s*$/.exec(duration);
|
|
72
|
+
if (parsed === null) throw new TypeError(`not a duration: ${JSON.stringify(duration)} (milliseconds, or a number with ms, s, m or h)`);
|
|
73
|
+
return Math.round(Number(parsed[1]) * (UNITS[parsed[2] as string] as number));
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** How long a check may run when it does not say: ten minutes. */
|
|
77
|
+
const DEFAULT_TIMEOUT_MS = 600_000;
|
|
78
|
+
|
|
79
|
+
/** The most lines of the end of the output a summary keeps. */
|
|
80
|
+
const SUMMARY_LINES = 20;
|
|
81
|
+
|
|
82
|
+
const lines = (text: string): string[] => text.split("\n").map((line) => line.trimEnd()).filter((line) => line !== "");
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* The report a command printed, read from the end of its output: undefined when the output does not hold
|
|
86
|
+
* one. Only the end of the output is read, so a report has to come last.
|
|
87
|
+
*/
|
|
88
|
+
export function reportOf(kind: NonNullable<Check["report"]>, tail: string): unknown {
|
|
89
|
+
if (kind === "json") {
|
|
90
|
+
const last = lines(tail).at(-1);
|
|
91
|
+
if (last === undefined) return undefined;
|
|
92
|
+
try {
|
|
93
|
+
return JSON.parse(last) as unknown;
|
|
94
|
+
} catch {
|
|
95
|
+
return undefined;
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
if (kind === "lcov") {
|
|
99
|
+
let found = 0;
|
|
100
|
+
let hit = 0;
|
|
101
|
+
for (const line of lines(tail)) {
|
|
102
|
+
const lf = /^LF:(\d+)$/.exec(line);
|
|
103
|
+
const lh = /^LH:(\d+)$/.exec(line);
|
|
104
|
+
if (lf !== null) found += Number(lf[1]);
|
|
105
|
+
if (lh !== null) hit += Number(lh[1]);
|
|
106
|
+
}
|
|
107
|
+
return found === 0 ? undefined : { found, hit, coverage: hit / found };
|
|
108
|
+
}
|
|
109
|
+
let seen = false;
|
|
110
|
+
const counts = { tests: 0, failures: 0, errors: 0, skipped: 0 };
|
|
111
|
+
for (const tag of tail.match(/<testsuite\b[^>]*>/g) ?? []) {
|
|
112
|
+
seen = true;
|
|
113
|
+
for (const name of ["tests", "failures", "errors", "skipped"] as const) {
|
|
114
|
+
const value = new RegExp(`\\b${name}="(\\d+)"`).exec(tag);
|
|
115
|
+
if (value !== null) counts[name] += Number(value[1]);
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
return seen ? counts : undefined;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** Run a check and read it: it passes when the command exited with 0 in its time. */
|
|
122
|
+
export async function runCheck(key: string, check: Check): Promise<CheckResult> {
|
|
123
|
+
const g = globals();
|
|
124
|
+
const timeout = check.timeout === undefined ? DEFAULT_TIMEOUT_MS : durationMs(check.timeout);
|
|
125
|
+
const secret = Object.values(check.env ?? {}).some((value) => typeof value !== "string");
|
|
126
|
+
if (secret && check.box !== undefined) throw new TypeError(`check "${key}" holds a secret, so it runs with proc.exec, which has no box: drop its box`);
|
|
127
|
+
const input = {
|
|
128
|
+
cmd: check.cmd,
|
|
129
|
+
cwd: check.cwd,
|
|
130
|
+
timeout,
|
|
131
|
+
...(check.env === undefined ? {} : { env: check.env }),
|
|
132
|
+
...(check.box === undefined ? {} : { box: check.box }),
|
|
133
|
+
};
|
|
134
|
+
const answer = (await g.scope(key, undefined, () => g.call(secret ? "proc.exec" : "proc.run", input))) as ProcAnswer;
|
|
135
|
+
const ended =
|
|
136
|
+
answer.outcome === "timed-out" ? `timed out after ${String(timeout)} ms` : answer.outcome === "cancelled" ? "cancelled" : `exited with ${String(answer.exit)}`;
|
|
137
|
+
const summary = [ended, ...lines(answer.tail).slice(-SUMMARY_LINES)].join("\n");
|
|
138
|
+
const report = check.report === undefined ? undefined : reportOf(check.report, answer.tail);
|
|
139
|
+
return {
|
|
140
|
+
ok: answer.outcome === "exited" && answer.exit === 0,
|
|
141
|
+
exit: answer.exit,
|
|
142
|
+
summary,
|
|
143
|
+
...(report === undefined ? {} : { report }),
|
|
144
|
+
artifact: answer.output,
|
|
145
|
+
};
|
|
146
|
+
}
|