@kjanat/dreamcli 3.0.0 → 4.0.0-rc.1
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/CHANGELOG.md +967 -1
- package/README.md +9 -3
- package/dist/core/cli/builtins.d.mts +47 -0
- package/dist/core/cli/builtins.mjs +135 -0
- package/dist/core/cli/compiled.d.mts +29 -0
- package/dist/core/cli/compiled.mjs +76 -0
- package/dist/core/cli/dispatch.d.mts +9 -85
- package/dist/core/cli/help-links.d.mts +2 -14
- package/dist/core/cli/index.d.mts +282 -101
- package/dist/core/cli/index.mjs +497 -264
- package/dist/core/cli/planner.d.mts +13 -86
- package/dist/core/cli/planner.mjs +47 -30
- package/dist/core/cli/plugin.d.mts +1 -1
- package/dist/core/cli/propagate.mjs +1 -1
- package/dist/core/cli/reserved-flags.d.mts +1 -0
- package/dist/core/cli/reserved-flags.mjs +158 -0
- package/dist/core/cli/root-help.d.mts +1 -47
- package/dist/core/cli/root-help.mjs +37 -47
- package/dist/core/cli/root-output-flags.d.mts +1 -0
- package/dist/core/cli/root-output-flags.mjs +169 -0
- package/dist/core/cli/root-surface.d.mts +1 -68
- package/dist/core/cli/root-surface.mjs +2 -2
- package/dist/core/cli/runtime-preflight.d.mts +1 -199
- package/dist/core/cli/runtime-preflight.mjs +67 -17
- package/dist/core/completion/index.d.mts +2 -2
- package/dist/core/completion/shells/bash.d.mts +0 -1
- package/dist/core/completion/shells/bash.mjs +2 -1
- package/dist/core/completion/shells/fish.d.mts +0 -1
- package/dist/core/completion/shells/fish.mjs +2 -1
- package/dist/core/completion/shells/powershell.d.mts +0 -1
- package/dist/core/completion/shells/powershell.mjs +2 -1
- package/dist/core/completion/shells/shared.d.mts +3 -114
- package/dist/core/completion/shells/shared.mjs +9 -39
- package/dist/core/completion/shells/zsh.d.mts +0 -1
- package/dist/core/completion/shells/zsh.mjs +2 -1
- package/dist/core/config/index.d.mts +3 -3
- package/dist/core/config/index.mjs +2 -2
- package/dist/core/config/package-json.d.mts +2 -33
- package/dist/core/config/package-json.mjs +1 -34
- package/dist/core/errors/index.d.mts +7 -7
- package/dist/core/execution/index.d.mts +1 -48
- package/dist/core/execution/index.mjs +42 -27
- package/dist/core/help/ansi.d.mts +0 -11
- package/dist/core/help/index.d.mts +3 -35
- package/dist/core/help/index.mjs +29 -6
- package/dist/core/help/theme.d.mts +1 -21
- package/dist/core/json-schema/index.d.mts +279 -10
- package/dist/core/json-schema/index.mjs +482 -237
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
- package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
- package/dist/core/output/activity.d.mts +1 -193
- package/dist/core/output/activity.mjs +1 -1
- package/dist/core/output/bind.d.mts +1 -37
- package/dist/core/output/contracts.d.mts +7 -13
- package/dist/core/output/contracts.mjs +1 -1
- package/dist/core/output/display-value.d.mts +1 -19
- package/dist/core/output/index.d.mts +5 -187
- package/dist/core/output/index.mjs +44 -9
- package/dist/core/output/renderers.d.mts +1 -45
- package/dist/core/output/writer.d.mts +0 -1
- package/dist/core/parse/index.d.mts +27 -5
- package/dist/core/parse/index.mjs +350 -227
- package/dist/core/parse/occurrences.d.mts +89 -0
- package/dist/core/parse/occurrences.mjs +114 -0
- package/dist/core/prompt/index.d.mts +3 -3
- package/dist/core/read-flags/index.d.mts +150 -0
- package/dist/core/read-flags/index.mjs +217 -0
- package/dist/core/resolve/args.d.mts +35 -4
- package/dist/core/resolve/args.mjs +132 -55
- package/dist/core/resolve/coerce.d.mts +66 -9
- package/dist/core/resolve/coerce.mjs +834 -270
- package/dist/core/resolve/config.d.mts +1 -10
- package/dist/core/resolve/contracts.d.mts +67 -44
- package/dist/core/resolve/errors.mjs +29 -21
- package/dist/core/resolve/flags.d.mts +36 -9
- package/dist/core/resolve/flags.mjs +129 -151
- package/dist/core/resolve/index.d.mts +8 -6
- package/dist/core/resolve/index.mjs +51 -18
- package/dist/core/resolve/path-checks.d.mts +47 -0
- package/dist/core/resolve/path-checks.mjs +102 -0
- package/dist/core/resolve/redaction.d.mts +12 -0
- package/dist/core/resolve/redaction.mjs +14 -0
- package/dist/core/resolve/stages.d.mts +85 -0
- package/dist/core/resolve/stages.mjs +170 -0
- package/dist/core/resolve/standard.d.mts +1 -24
- package/dist/core/resolve/standard.mjs +141 -43
- package/dist/core/schema/activity.d.mts +16 -16
- package/dist/core/schema/arg.d.mts +849 -71
- package/dist/core/schema/arg.mjs +727 -54
- package/dist/core/schema/brand.d.mts +17 -0
- package/dist/core/schema/cardinality.d.mts +301 -0
- package/dist/core/schema/cardinality.mjs +514 -0
- package/dist/core/schema/command.d.mts +181 -112
- package/dist/core/schema/command.mjs +305 -42
- package/dist/core/schema/flag.d.mts +515 -173
- package/dist/core/schema/flag.mjs +576 -78
- package/dist/core/schema/index.d.mts +11 -8
- package/dist/core/schema/index.mjs +10 -0
- package/dist/core/schema/middleware.d.mts +15 -12
- package/dist/core/schema/number-constraints.d.mts +5 -5
- package/dist/core/schema/prompt.d.mts +4 -4
- package/dist/core/schema/provenance.d.mts +99 -0
- package/dist/core/schema/provenance.mjs +28 -0
- package/dist/core/schema/run.d.mts +21 -60
- package/dist/core/schema/source.d.mts +179 -0
- package/dist/core/schema/source.mjs +206 -0
- package/dist/core/schema/standard.d.mts +12 -19
- package/dist/core/schema/stdin.d.mts +87 -0
- package/dist/core/schema/stdin.mjs +91 -0
- package/dist/core/schema/string-constraints.d.mts +16 -5
- package/dist/core/schema/string-constraints.mjs +18 -1
- package/dist/core/schema/value-parsers.d.mts +81 -9
- package/dist/core/schema/value-parsers.mjs +19 -1
- package/dist/core/schema/value.d.mts +242 -0
- package/dist/core/schema/value.mjs +573 -0
- package/dist/core/testkit/index.d.mts +28 -3
- package/dist/core/testkit/index.mjs +40 -26
- package/dist/index.d.mts +21 -16
- package/dist/index.mjs +10 -6
- package/dist/runtime/adapter.d.mts +3 -3
- package/dist/runtime/deno.d.mts +3 -3
- package/dist/runtime/detect.d.mts +2 -2
- package/dist/runtime/node.d.mts +3 -3
- package/dist/runtime/paths.d.mts +1 -31
- package/dist/runtime.d.mts +4 -4
- package/dist/strings.d.mts +1 -16
- package/dist/testkit.d.mts +2 -2
- package/dist/testkit.mjs +1 -1
- package/dist/version.d.mts +0 -13
- package/dist/version.mjs +2 -2
- package/dreamcli.schema.json +368 -78
- package/examples/interactive.ts +6 -5
- package/package.json +10 -9
- package/skills/cli-creation/SKILL.md +196 -0
- package/skills/cli-creation/agents/openai.yaml +4 -0
- package/skills/cli-creation/assets/templates/multi-command.bun-test.ts.tpl +20 -0
- package/skills/cli-creation/assets/templates/multi-command.test.ts.tpl +20 -0
- package/skills/cli-creation/assets/templates/multi-command.ts.tpl +89 -0
- package/skills/cli-creation/assets/templates/single-command.bun-test.ts.tpl +29 -0
- package/skills/cli-creation/assets/templates/single-command.test.ts.tpl +29 -0
- package/skills/cli-creation/assets/templates/single-command.ts.tpl +47 -0
- package/skills/cli-creation/references/consumer-workflow.md +65 -0
- package/skills/cli-creation/references/pattern-cookbook.md +451 -0
- package/skills/cli-creation/references/runtime-notes.md +29 -0
- package/skills/cli-creation/scripts/scaffold_cli.py +360 -0
- package/dist/core/resolve/property.d.mts +0 -51
- package/dist/core/resolve/property.mjs +0 -53
|
@@ -0,0 +1,573 @@
|
|
|
1
|
+
import { describeNumberConstraintViolation, validateNumberConstraints } from "./number-constraints.mjs";
|
|
2
|
+
import { describeStringConstraintViolation, validateStringConstraints } from "./string-constraints.mjs";
|
|
3
|
+
import { buildPathChecks, parseBytesValue, parseDateValue, parseDurationValue, parseUrlValue } from "./value-parsers.mjs";
|
|
4
|
+
//#region src/core/schema/value.ts
|
|
5
|
+
const STRING_TYPE_FAILURE = {
|
|
6
|
+
ok: false,
|
|
7
|
+
failure: {
|
|
8
|
+
kind: "type",
|
|
9
|
+
expected: "string"
|
|
10
|
+
}
|
|
11
|
+
};
|
|
12
|
+
const NUMBER_TYPE_FAILURE = {
|
|
13
|
+
ok: false,
|
|
14
|
+
failure: {
|
|
15
|
+
kind: "type",
|
|
16
|
+
expected: "number"
|
|
17
|
+
}
|
|
18
|
+
};
|
|
19
|
+
const BOOLEAN_TYPE_FAILURE = {
|
|
20
|
+
ok: false,
|
|
21
|
+
failure: {
|
|
22
|
+
kind: "type",
|
|
23
|
+
expected: "boolean"
|
|
24
|
+
}
|
|
25
|
+
};
|
|
26
|
+
/**
|
|
27
|
+
* Reads a raw value as a string.
|
|
28
|
+
*
|
|
29
|
+
* A prompt answer and a config scalar are stringified, since a prompt engine
|
|
30
|
+
* may hand back a non-string answer and a config file may hold `8080` where a
|
|
31
|
+
* string is declared. Argv tokens and env values are already strings.
|
|
32
|
+
*/
|
|
33
|
+
const stringCodec = {
|
|
34
|
+
name: "string",
|
|
35
|
+
decode(raw, input) {
|
|
36
|
+
if (typeof raw === "string") return {
|
|
37
|
+
ok: true,
|
|
38
|
+
value: raw
|
|
39
|
+
};
|
|
40
|
+
if (input === "prompt") return {
|
|
41
|
+
ok: true,
|
|
42
|
+
value: String(raw)
|
|
43
|
+
};
|
|
44
|
+
if (input === "config" && (typeof raw === "number" || typeof raw === "boolean")) return {
|
|
45
|
+
ok: true,
|
|
46
|
+
value: String(raw)
|
|
47
|
+
};
|
|
48
|
+
return STRING_TYPE_FAILURE;
|
|
49
|
+
}
|
|
50
|
+
};
|
|
51
|
+
/** Reads a raw value as a string, rejecting every other type from every input. */
|
|
52
|
+
const strictStringCodec = {
|
|
53
|
+
name: "string",
|
|
54
|
+
decode(raw) {
|
|
55
|
+
return typeof raw === "string" ? {
|
|
56
|
+
ok: true,
|
|
57
|
+
value: raw
|
|
58
|
+
} : STRING_TYPE_FAILURE;
|
|
59
|
+
}
|
|
60
|
+
};
|
|
61
|
+
/** Reads a raw value as a number, rejecting `NaN` and blank text from every input. */
|
|
62
|
+
const numberCodec = {
|
|
63
|
+
name: "number",
|
|
64
|
+
decode(raw) {
|
|
65
|
+
if (typeof raw === "number") return Number.isNaN(raw) ? NUMBER_TYPE_FAILURE : {
|
|
66
|
+
ok: true,
|
|
67
|
+
value: raw
|
|
68
|
+
};
|
|
69
|
+
if (typeof raw === "string" && raw.trim() !== "") {
|
|
70
|
+
const value = Number(raw);
|
|
71
|
+
if (!Number.isNaN(value)) return {
|
|
72
|
+
ok: true,
|
|
73
|
+
value
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
return NUMBER_TYPE_FAILURE;
|
|
77
|
+
}
|
|
78
|
+
};
|
|
79
|
+
/**
|
|
80
|
+
* Reads a raw value as a boolean.
|
|
81
|
+
*
|
|
82
|
+
* An argv token spells the value out as `true`/`false` or `1`/`0`. Stdin, env,
|
|
83
|
+
* config, and prompt inputs also accept `yes`/`no`, an already-boolean value,
|
|
84
|
+
* and an empty string for `false`; a prompt answer additionally accepts
|
|
85
|
+
* `y`/`n`.
|
|
86
|
+
*/
|
|
87
|
+
const booleanCodec = {
|
|
88
|
+
name: "boolean",
|
|
89
|
+
decode(raw, input) {
|
|
90
|
+
if (input === "token") {
|
|
91
|
+
if (raw === "true" || raw === "1") return {
|
|
92
|
+
ok: true,
|
|
93
|
+
value: true
|
|
94
|
+
};
|
|
95
|
+
if (raw === "false" || raw === "0") return {
|
|
96
|
+
ok: true,
|
|
97
|
+
value: false
|
|
98
|
+
};
|
|
99
|
+
return BOOLEAN_TYPE_FAILURE;
|
|
100
|
+
}
|
|
101
|
+
if (typeof raw === "boolean") return {
|
|
102
|
+
ok: true,
|
|
103
|
+
value: raw
|
|
104
|
+
};
|
|
105
|
+
if (typeof raw === "string") {
|
|
106
|
+
const lower = raw.toLowerCase();
|
|
107
|
+
if (lower === "true" || lower === "1" || lower === "yes" || input === "prompt" && lower === "y") return {
|
|
108
|
+
ok: true,
|
|
109
|
+
value: true
|
|
110
|
+
};
|
|
111
|
+
if (lower === "false" || lower === "0" || lower === "no" || lower === "" || input === "prompt" && lower === "n") return {
|
|
112
|
+
ok: true,
|
|
113
|
+
value: false
|
|
114
|
+
};
|
|
115
|
+
}
|
|
116
|
+
return BOOLEAN_TYPE_FAILURE;
|
|
117
|
+
}
|
|
118
|
+
};
|
|
119
|
+
/** Reads a raw value as one of the declared literals. */
|
|
120
|
+
function enumCodec(enumValues) {
|
|
121
|
+
return {
|
|
122
|
+
name: "enum",
|
|
123
|
+
enumValues,
|
|
124
|
+
decode(raw) {
|
|
125
|
+
if (typeof raw === "string" && enumValues?.includes(raw) === true) return {
|
|
126
|
+
ok: true,
|
|
127
|
+
value: raw
|
|
128
|
+
};
|
|
129
|
+
return {
|
|
130
|
+
ok: false,
|
|
131
|
+
failure: {
|
|
132
|
+
kind: "enum",
|
|
133
|
+
enumValues
|
|
134
|
+
}
|
|
135
|
+
};
|
|
136
|
+
}
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
/** Passes a raw value through untouched, for a custom value with no parse function. */
|
|
140
|
+
const passthroughCodec = {
|
|
141
|
+
name: "custom",
|
|
142
|
+
parseFn: void 0,
|
|
143
|
+
decode(raw) {
|
|
144
|
+
return {
|
|
145
|
+
ok: true,
|
|
146
|
+
value: raw
|
|
147
|
+
};
|
|
148
|
+
}
|
|
149
|
+
};
|
|
150
|
+
/** Reads a raw value through a parse function that accepts any raw source value. */
|
|
151
|
+
function parsedCodec(parseFn) {
|
|
152
|
+
return {
|
|
153
|
+
name: "custom",
|
|
154
|
+
parseFn,
|
|
155
|
+
decode(raw) {
|
|
156
|
+
try {
|
|
157
|
+
return {
|
|
158
|
+
ok: true,
|
|
159
|
+
value: parseFn(raw)
|
|
160
|
+
};
|
|
161
|
+
} catch (error) {
|
|
162
|
+
return {
|
|
163
|
+
ok: false,
|
|
164
|
+
failure: {
|
|
165
|
+
kind: "thrown",
|
|
166
|
+
error
|
|
167
|
+
}
|
|
168
|
+
};
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
};
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* Reads a raw value through a parse function that only ever receives strings.
|
|
175
|
+
*
|
|
176
|
+
* A config file may hold a number where a string-parsed value is declared, so a
|
|
177
|
+
* non-string raw is stringified before the parse function sees it.
|
|
178
|
+
*/
|
|
179
|
+
function stringParsedCodec(parseFn) {
|
|
180
|
+
return {
|
|
181
|
+
name: "custom",
|
|
182
|
+
parseFn,
|
|
183
|
+
decode(raw) {
|
|
184
|
+
try {
|
|
185
|
+
return {
|
|
186
|
+
ok: true,
|
|
187
|
+
value: parseFn(typeof raw === "string" ? raw : String(raw))
|
|
188
|
+
};
|
|
189
|
+
} catch (error) {
|
|
190
|
+
return {
|
|
191
|
+
ok: false,
|
|
192
|
+
failure: {
|
|
193
|
+
kind: "thrown",
|
|
194
|
+
error
|
|
195
|
+
}
|
|
196
|
+
};
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
};
|
|
200
|
+
}
|
|
201
|
+
/**
|
|
202
|
+
* Decode a raw value and apply the constraints riding on the value schema.
|
|
203
|
+
*
|
|
204
|
+
* The single entry point both the parse boundary and the resolver coercion
|
|
205
|
+
* boundary use, so the two cannot drift on what a value means.
|
|
206
|
+
*
|
|
207
|
+
* @param value - The value axis of the flag or arg receiving the raw value.
|
|
208
|
+
* @param raw - The raw token, env string, config value, or prompt answer.
|
|
209
|
+
* @param input - Which surface produced `raw`.
|
|
210
|
+
* @returns The decoded value, or the {@link ValueFailure} that rejected it.
|
|
211
|
+
*/
|
|
212
|
+
function decodeValue(value, raw, input) {
|
|
213
|
+
const decoded = value.codec.decode(stdinDecodeInput(value, raw, input), input);
|
|
214
|
+
if (!decoded.ok) return decoded;
|
|
215
|
+
const failure = checkValueConstraints(value.constraints, decoded.value);
|
|
216
|
+
return failure === void 0 ? decoded : {
|
|
217
|
+
ok: false,
|
|
218
|
+
failure
|
|
219
|
+
};
|
|
220
|
+
}
|
|
221
|
+
/**
|
|
222
|
+
* Drop the line terminator a pipe appends, for every codec that reads the text
|
|
223
|
+
* rather than keeping it.
|
|
224
|
+
*
|
|
225
|
+
* The stdin source hands over the buffer byte for byte, so `'hello\n'` stays
|
|
226
|
+
* `'hello\n'` under the string codec. Every other codec interprets the text,
|
|
227
|
+
* where a trailing terminator is framing rather than value: `'42\n'` is the
|
|
228
|
+
* number 42, `'true\n'` the boolean `true`, `'30s\n'` a duration.
|
|
229
|
+
*
|
|
230
|
+
* @param value - The value axis about to read the value.
|
|
231
|
+
* @param raw - The raw value the source produced.
|
|
232
|
+
* @param input - Which surface produced `raw`.
|
|
233
|
+
* @returns The value to decode.
|
|
234
|
+
*/
|
|
235
|
+
function stdinDecodeInput(value, raw, input) {
|
|
236
|
+
if (input !== "stdin" || keepsStdinTerminator(value) || typeof raw !== "string") return raw;
|
|
237
|
+
return stripTerminator(raw);
|
|
238
|
+
}
|
|
239
|
+
/**
|
|
240
|
+
* Drop the line terminator a pipe appends.
|
|
241
|
+
*
|
|
242
|
+
* @param text - The raw stdin buffer.
|
|
243
|
+
* @returns The text without its single trailing terminator.
|
|
244
|
+
*/
|
|
245
|
+
function stripTerminator(text) {
|
|
246
|
+
if (text.endsWith("\r\n")) return text.slice(0, -2);
|
|
247
|
+
if (text.endsWith("\n") || text.endsWith("\r")) return text.slice(0, -1);
|
|
248
|
+
return text;
|
|
249
|
+
}
|
|
250
|
+
/**
|
|
251
|
+
* Whether decoding leaves the line terminator a pipe appends on the value.
|
|
252
|
+
*
|
|
253
|
+
* @param value - The value axis about to read a stdin buffer.
|
|
254
|
+
* @returns `true` when the terminator survives decoding.
|
|
255
|
+
*/
|
|
256
|
+
function keepsStdinTerminator(value) {
|
|
257
|
+
return value.codec.name === "string";
|
|
258
|
+
}
|
|
259
|
+
/**
|
|
260
|
+
* Check a value that skipped decoding against everything the codec would have
|
|
261
|
+
* produced and the constraints would have enforced.
|
|
262
|
+
*
|
|
263
|
+
* A declared default is already the typed value, so it is validated rather than
|
|
264
|
+
* read from a raw source: it must lie in the codec's own output domain, and it
|
|
265
|
+
* must satisfy the constraints. Standard Schema and filesystem checks ride on
|
|
266
|
+
* the value schema separately and stay with their own passes.
|
|
267
|
+
*
|
|
268
|
+
* @param value - The value axis declaring the codec and the constraints.
|
|
269
|
+
* @param decoded - The already-typed value to check.
|
|
270
|
+
* @returns The {@link ValueFailure} that rejected it, or `undefined` when it passes.
|
|
271
|
+
*/
|
|
272
|
+
function validateDecodedValue(value, decoded) {
|
|
273
|
+
return checkValueDomain(value.codec, decoded) ?? checkValueConstraints(value.constraints, decoded);
|
|
274
|
+
}
|
|
275
|
+
/**
|
|
276
|
+
* Check that a value lies in the domain a codec produces.
|
|
277
|
+
*
|
|
278
|
+
* A `custom` codec's output is whatever its parse function returns, so it has
|
|
279
|
+
* no domain to check. `NaN` is left to the number constraints, which reject it
|
|
280
|
+
* with the reason a reader can act on.
|
|
281
|
+
*
|
|
282
|
+
* @param codec - The codec the value claims to belong to.
|
|
283
|
+
* @param value - The already-typed value to check.
|
|
284
|
+
* @returns The {@link ValueFailure} that rejected it, or `undefined` when it passes.
|
|
285
|
+
*/
|
|
286
|
+
function checkValueDomain(codec, value) {
|
|
287
|
+
switch (codec.name) {
|
|
288
|
+
case "string": return typeof value === "string" ? void 0 : {
|
|
289
|
+
kind: "type",
|
|
290
|
+
expected: "string"
|
|
291
|
+
};
|
|
292
|
+
case "number": return typeof value === "number" ? void 0 : {
|
|
293
|
+
kind: "type",
|
|
294
|
+
expected: "number"
|
|
295
|
+
};
|
|
296
|
+
case "boolean": return typeof value === "boolean" ? void 0 : {
|
|
297
|
+
kind: "type",
|
|
298
|
+
expected: "boolean"
|
|
299
|
+
};
|
|
300
|
+
case "enum": return typeof value === "string" && codec.enumValues?.includes(value) === true ? void 0 : {
|
|
301
|
+
kind: "enum",
|
|
302
|
+
enumValues: codec.enumValues
|
|
303
|
+
};
|
|
304
|
+
case "custom": return;
|
|
305
|
+
}
|
|
306
|
+
}
|
|
307
|
+
/**
|
|
308
|
+
* Describe a value failure in the words a message can carry.
|
|
309
|
+
*
|
|
310
|
+
* The subject the value belonged to is the caller's to name.
|
|
311
|
+
*
|
|
312
|
+
* @param failure - What the value layer rejected.
|
|
313
|
+
* @returns One clause stating the problem.
|
|
314
|
+
*/
|
|
315
|
+
function describeValueFailure(failure) {
|
|
316
|
+
switch (failure.kind) {
|
|
317
|
+
case "type": return `expected a ${failure.expected}`;
|
|
318
|
+
case "enum": return `expected one of: ${(failure.enumValues ?? []).join(", ")}`;
|
|
319
|
+
case "string-constraint": return describeStringConstraintViolation(failure.violation);
|
|
320
|
+
case "number-constraint": return describeNumberConstraintViolation(failure.violation);
|
|
321
|
+
case "thrown": return failure.error instanceof Error ? failure.error.message : String(failure.error);
|
|
322
|
+
}
|
|
323
|
+
}
|
|
324
|
+
/** Apply the constraints a value schema carries to an already-decoded value. */
|
|
325
|
+
function checkValueConstraints(constraints, value) {
|
|
326
|
+
if (constraints === void 0) return void 0;
|
|
327
|
+
if (constraints.kind === "string") {
|
|
328
|
+
if (typeof value !== "string") return void 0;
|
|
329
|
+
const violation = validateStringConstraints(value, constraints.stringConstraints);
|
|
330
|
+
return violation === void 0 ? void 0 : {
|
|
331
|
+
kind: "string-constraint",
|
|
332
|
+
value,
|
|
333
|
+
violation
|
|
334
|
+
};
|
|
335
|
+
}
|
|
336
|
+
if (typeof value !== "number") return void 0;
|
|
337
|
+
const violation = validateNumberConstraints(value, constraints.numberConstraints);
|
|
338
|
+
return violation === void 0 ? void 0 : {
|
|
339
|
+
kind: "number-constraint",
|
|
340
|
+
value,
|
|
341
|
+
violation
|
|
342
|
+
};
|
|
343
|
+
}
|
|
344
|
+
/** Assemble a value schema, defaulting every slot the caller does not set. */
|
|
345
|
+
function makeValue(codec, slots) {
|
|
346
|
+
return {
|
|
347
|
+
codec,
|
|
348
|
+
constraints: slots?.constraints,
|
|
349
|
+
standard: slots?.standard,
|
|
350
|
+
pathChecks: slots?.pathChecks,
|
|
351
|
+
valueHint: slots?.valueHint
|
|
352
|
+
};
|
|
353
|
+
}
|
|
354
|
+
/** A string value, optionally constrained. */
|
|
355
|
+
function stringValue(stringConstraints) {
|
|
356
|
+
return makeValue(stringCodec, { constraints: {
|
|
357
|
+
kind: "string",
|
|
358
|
+
stringConstraints
|
|
359
|
+
} });
|
|
360
|
+
}
|
|
361
|
+
/**
|
|
362
|
+
* A string value that accepts nothing but a string, from every input.
|
|
363
|
+
*
|
|
364
|
+
* The implicit element of an entries collection, whose values are strings on
|
|
365
|
+
* every source rather than a config scalar a string codec would stringify.
|
|
366
|
+
*/
|
|
367
|
+
function strictStringValue() {
|
|
368
|
+
return makeValue(strictStringCodec, { constraints: {
|
|
369
|
+
kind: "string",
|
|
370
|
+
stringConstraints: void 0
|
|
371
|
+
} });
|
|
372
|
+
}
|
|
373
|
+
/** A number value, optionally constrained. Finiteness applies with or without constraints. */
|
|
374
|
+
function numberValue(numberConstraints) {
|
|
375
|
+
return makeValue(numberCodec, { constraints: {
|
|
376
|
+
kind: "number",
|
|
377
|
+
numberConstraints
|
|
378
|
+
} });
|
|
379
|
+
}
|
|
380
|
+
/** A boolean value. */
|
|
381
|
+
function booleanValue() {
|
|
382
|
+
return makeValue(booleanCodec);
|
|
383
|
+
}
|
|
384
|
+
/** A value restricted to the declared literals. */
|
|
385
|
+
function enumValue(enumValues) {
|
|
386
|
+
return makeValue(enumCodec(enumValues));
|
|
387
|
+
}
|
|
388
|
+
/** A value produced by a flag-style parse function, which accepts any raw source value. */
|
|
389
|
+
function customValue(parseFn) {
|
|
390
|
+
return makeValue(parsedCodec(parseFn));
|
|
391
|
+
}
|
|
392
|
+
/** A value produced by an arg-style parse function, which only ever receives strings. */
|
|
393
|
+
function stringParsedValue(parseFn) {
|
|
394
|
+
return makeValue(stringParsedCodec(parseFn));
|
|
395
|
+
}
|
|
396
|
+
/** A value validated by a Standard Schema v1 validator instead of a parse function. */
|
|
397
|
+
function standardValue(standard) {
|
|
398
|
+
return makeValue(passthroughCodec, { standard });
|
|
399
|
+
}
|
|
400
|
+
/** A value passed through untouched. */
|
|
401
|
+
function passthroughValue() {
|
|
402
|
+
return makeValue(passthroughCodec);
|
|
403
|
+
}
|
|
404
|
+
/** A `URL` value, optionally restricted to an allowlist of protocols. */
|
|
405
|
+
function urlValue(options) {
|
|
406
|
+
return makeValue(parsedCodec((raw) => parseUrlValue(raw, options)), { valueHint: "url" });
|
|
407
|
+
}
|
|
408
|
+
/** A path string, with the filesystem checks the options ask for. */
|
|
409
|
+
function pathValue(options) {
|
|
410
|
+
const pathChecks = buildPathChecks(options);
|
|
411
|
+
return makeValue(stringCodec, {
|
|
412
|
+
constraints: {
|
|
413
|
+
kind: "string",
|
|
414
|
+
stringConstraints: void 0
|
|
415
|
+
},
|
|
416
|
+
valueHint: "path",
|
|
417
|
+
...pathChecks !== void 0 ? { pathChecks } : {}
|
|
418
|
+
});
|
|
419
|
+
}
|
|
420
|
+
/** A `Date` value parsed from strict ISO-8601, optionally bounded. */
|
|
421
|
+
function dateValue(options) {
|
|
422
|
+
return makeValue(parsedCodec((raw) => parseDateValue(raw, options)), { valueHint: "date" });
|
|
423
|
+
}
|
|
424
|
+
/** A duration in milliseconds. */
|
|
425
|
+
function durationValue() {
|
|
426
|
+
return makeValue(parsedCodec(parseDurationValue), { valueHint: "duration" });
|
|
427
|
+
}
|
|
428
|
+
/** A size in bytes. */
|
|
429
|
+
function bytesValue() {
|
|
430
|
+
return makeValue(parsedCodec(parseBytesValue), { valueHint: "size" });
|
|
431
|
+
}
|
|
432
|
+
/**
|
|
433
|
+
* Flatten a value schema into the definition fields a factory passes to
|
|
434
|
+
* `createFlagSchema()` / `createArgSchema()`.
|
|
435
|
+
*
|
|
436
|
+
* `enumValues` is not among them. Both enum definitions declare that field as
|
|
437
|
+
* required, which an all-optional record cannot satisfy, so the enum factories
|
|
438
|
+
* pass it directly.
|
|
439
|
+
*
|
|
440
|
+
* @param value - The value axis to flatten.
|
|
441
|
+
* @returns Only the fields the value actually declares.
|
|
442
|
+
*/
|
|
443
|
+
function valueDefinitionFields(value) {
|
|
444
|
+
const constraints = value.constraints;
|
|
445
|
+
const codec = value.codec;
|
|
446
|
+
return {
|
|
447
|
+
...constraints?.kind === "string" && constraints.stringConstraints !== void 0 ? { stringConstraints: constraints.stringConstraints } : {},
|
|
448
|
+
...constraints?.kind === "number" && constraints.numberConstraints !== void 0 ? { numberConstraints: constraints.numberConstraints } : {},
|
|
449
|
+
...codec.name === "custom" && codec.parseFn !== void 0 ? { parseFn: codec.parseFn } : {},
|
|
450
|
+
...value.standard !== void 0 ? { standard: value.standard } : {},
|
|
451
|
+
...value.pathChecks !== void 0 ? { pathChecks: value.pathChecks } : {},
|
|
452
|
+
...value.valueHint !== void 0 ? { valueHint: value.valueHint } : {}
|
|
453
|
+
};
|
|
454
|
+
}
|
|
455
|
+
/**
|
|
456
|
+
* Project a flag schema onto its value axis.
|
|
457
|
+
*
|
|
458
|
+
* A collection projects onto the value of each ELEMENT, so `flag.array()` and
|
|
459
|
+
* `flag.keyValue()` read their element schema's codec, constraints, validator,
|
|
460
|
+
* and path checks here. What the completed collection must satisfy lives on the
|
|
461
|
+
* cardinality axis and is read through {@link flagAggregateStandard}.
|
|
462
|
+
*
|
|
463
|
+
* @param schema - The flag schema to read.
|
|
464
|
+
* @returns The value axis of one value of the flag.
|
|
465
|
+
*/
|
|
466
|
+
function flagValueSchema(schema) {
|
|
467
|
+
switch (schema.kind) {
|
|
468
|
+
case "string": return scalarValue(schema, stringValue(schema.stringConstraints));
|
|
469
|
+
case "number": return scalarValue(schema, numberValue(schema.numberConstraints));
|
|
470
|
+
case "boolean": return scalarValue(schema, booleanValue());
|
|
471
|
+
case "enum": return scalarValue(schema, enumValue(schema.enumValues));
|
|
472
|
+
case "custom": return scalarValue(schema, schema.parseFn === void 0 ? passthroughValue() : customValue(schema.parseFn));
|
|
473
|
+
case "array": return elementValue(schema, passthroughValue);
|
|
474
|
+
case "keyValue": return elementValue(schema, strictStringValue);
|
|
475
|
+
case "count": return scalarValue(schema, numberValue({
|
|
476
|
+
int: true,
|
|
477
|
+
min: 0
|
|
478
|
+
}));
|
|
479
|
+
}
|
|
480
|
+
}
|
|
481
|
+
/**
|
|
482
|
+
* Standard Schema validator applied to a flag's completed collection.
|
|
483
|
+
*
|
|
484
|
+
* @param schema - The flag schema to read.
|
|
485
|
+
* @returns The aggregate validator, or `undefined` for a scalar flag, whose
|
|
486
|
+
* validator is the element's.
|
|
487
|
+
*/
|
|
488
|
+
function flagAggregateStandard(schema) {
|
|
489
|
+
return schema.aggregateStandard;
|
|
490
|
+
}
|
|
491
|
+
/**
|
|
492
|
+
* Project an arg schema onto its value axis.
|
|
493
|
+
*
|
|
494
|
+
* An entries arg projects onto the value of each ENTRY, so
|
|
495
|
+
* `arg.keyValue(arg.number())` reads its element schema's codec, constraints,
|
|
496
|
+
* validator, and path checks here. What the completed record must satisfy lives
|
|
497
|
+
* on the cardinality axis and is read through {@link argAggregateStandard}.
|
|
498
|
+
*
|
|
499
|
+
* @param schema - The arg schema to read.
|
|
500
|
+
* @returns The value axis of one value of the arg.
|
|
501
|
+
*/
|
|
502
|
+
function argValueSchema(schema) {
|
|
503
|
+
switch (schema.kind) {
|
|
504
|
+
case "string": return scalarValue(schema, stringValue(schema.stringConstraints));
|
|
505
|
+
case "number": return scalarValue(schema, numberValue(schema.numberConstraints));
|
|
506
|
+
case "boolean": return scalarValue(schema, booleanValue());
|
|
507
|
+
case "enum": return scalarValue(schema, enumValue(schema.enumValues));
|
|
508
|
+
case "custom": return scalarValue(schema, schema.parseFn === void 0 ? passthroughValue() : stringParsedValue(schema.parseFn));
|
|
509
|
+
case "keyValue": return argElementValue(schema);
|
|
510
|
+
}
|
|
511
|
+
}
|
|
512
|
+
/**
|
|
513
|
+
* Project an entries arg's element schema, or the implicit string element it
|
|
514
|
+
* declares none for.
|
|
515
|
+
*
|
|
516
|
+
* A validator on the arg itself is the element's when the element declares
|
|
517
|
+
* none, which is how a definition-built `{ kind: 'keyValue', standard }`
|
|
518
|
+
* validates each entry value.
|
|
519
|
+
*
|
|
520
|
+
* @param schema - The entries arg schema.
|
|
521
|
+
* @returns The value axis of one entry value.
|
|
522
|
+
*/
|
|
523
|
+
function argElementValue(schema) {
|
|
524
|
+
const element = schema.elementSchema === void 0 ? strictStringValue() : argValueSchema(schema.elementSchema);
|
|
525
|
+
return element.standard === void 0 && schema.standard !== void 0 ? {
|
|
526
|
+
...element,
|
|
527
|
+
standard: schema.standard
|
|
528
|
+
} : element;
|
|
529
|
+
}
|
|
530
|
+
/**
|
|
531
|
+
* Standard Schema validator applied to an arg's completed collection.
|
|
532
|
+
*
|
|
533
|
+
* @param schema - The arg schema to read.
|
|
534
|
+
* @returns The aggregate validator, or `undefined` when none was declared on
|
|
535
|
+
* the collection itself.
|
|
536
|
+
*/
|
|
537
|
+
function argAggregateStandard(schema) {
|
|
538
|
+
return schema.aggregateStandard;
|
|
539
|
+
}
|
|
540
|
+
/** Attach the element-level slots a schema carries alongside its codec. */
|
|
541
|
+
function scalarValue(schema, base) {
|
|
542
|
+
return {
|
|
543
|
+
...base,
|
|
544
|
+
standard: schema.standard,
|
|
545
|
+
pathChecks: schema.pathChecks,
|
|
546
|
+
valueHint: schema.valueHint
|
|
547
|
+
};
|
|
548
|
+
}
|
|
549
|
+
/**
|
|
550
|
+
* Project a collection's element schema, or the implicit element it declares
|
|
551
|
+
* none for.
|
|
552
|
+
*
|
|
553
|
+
* A validator on the collection itself is the element's when the element
|
|
554
|
+
* declares none, so a definition-built `{ kind: 'array', standard }` validates
|
|
555
|
+
* each element exactly as a variadic arg's own `standard` does.
|
|
556
|
+
*
|
|
557
|
+
* @param schema - The collection flag schema.
|
|
558
|
+
* @param implicit - The element value used when no element schema is declared.
|
|
559
|
+
* @returns The value axis of one element.
|
|
560
|
+
*/
|
|
561
|
+
function elementValue(schema, implicit) {
|
|
562
|
+
const element = schema.elementSchema === void 0 ? implicit() : flagValueSchema(schema.elementSchema);
|
|
563
|
+
return element.standard === void 0 && schema.standard !== void 0 ? {
|
|
564
|
+
...element,
|
|
565
|
+
standard: schema.standard
|
|
566
|
+
} : element;
|
|
567
|
+
}
|
|
568
|
+
/** The literals an enum value allows, or `undefined` for every other codec. */
|
|
569
|
+
function valueEnumValues(value) {
|
|
570
|
+
return value?.codec.name === "enum" ? value.codec.enumValues : void 0;
|
|
571
|
+
}
|
|
572
|
+
//#endregion
|
|
573
|
+
export { argAggregateStandard, argValueSchema, booleanValue, bytesValue, customValue, dateValue, decodeValue, describeValueFailure, durationValue, enumValue, flagAggregateStandard, flagValueSchema, keepsStdinTerminator, numberValue, passthroughValue, pathValue, standardValue, strictStringValue, stringParsedValue, stringValue, stripTerminator, urlValue, validateDecodedValue, valueDefinitionFields, valueEnumValues };
|
|
@@ -1,6 +1,27 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { BuiltinsConfig } from "../cli/builtins.mjs";
|
|
2
2
|
import { RunnableCommand } from "../schema/command.mjs";
|
|
3
|
+
import { RunOptions, RunResult } from "../schema/run.mjs";
|
|
3
4
|
//#region src/core/testkit/index.d.ts
|
|
5
|
+
/**
|
|
6
|
+
* Options for {@linkcode runCommand}.
|
|
7
|
+
*
|
|
8
|
+
* Extends {@linkcode RunOptions} with the CLI-root state `runCommand()` mirrors,
|
|
9
|
+
* following the way `CLIRunOptions` extends `CLIExecuteOptions` with the fields
|
|
10
|
+
* only that layer needs.
|
|
11
|
+
*/
|
|
12
|
+
interface RunCommandOptions extends RunOptions {
|
|
13
|
+
/**
|
|
14
|
+
* Which built-in flags the harness mirrors, matching the CLI the command is
|
|
15
|
+
* registered on.
|
|
16
|
+
*
|
|
17
|
+
* A command that owns a released built-in (`cli(...).builtins({ json: 'off' })`
|
|
18
|
+
* plus a `json` flag) must be tested with the same setting, otherwise the
|
|
19
|
+
* harness strips the token before `parse()` sees it.
|
|
20
|
+
*
|
|
21
|
+
* @defaultValue every built-in `'on'`, mirroring an unconfigured CLI root
|
|
22
|
+
*/
|
|
23
|
+
readonly builtins?: BuiltinsConfig;
|
|
24
|
+
}
|
|
4
25
|
/**
|
|
5
26
|
* Run a command builder against the given argv with injected options.
|
|
6
27
|
*
|
|
@@ -21,9 +42,13 @@ import { RunnableCommand } from "../schema/command.mjs";
|
|
|
21
42
|
* and stripped here, just like the real CLI root — so `['--json']` enables
|
|
22
43
|
* JSON mode and `['--quiet']` sets quiet verbosity rather than failing as
|
|
23
44
|
* unknown flags. Equivalent to `{ jsonMode: true }` / `{ verbosity: 'quiet' }`.
|
|
45
|
+
* Both accept an explicit value (`--json=false`), and an invalid one fails
|
|
46
|
+
* with the same `INVALID_VALUE` error the CLI root produces. Pass
|
|
47
|
+
* `options.builtins` to mirror a CLI that released one of these tokens to its
|
|
48
|
+
* commands.
|
|
24
49
|
* @param options - Injectable runtime state
|
|
25
50
|
* @returns Structured run result with exit code and captured output
|
|
26
51
|
*/
|
|
27
|
-
declare function runCommand(cmd: RunnableCommand, argv: readonly string[], options?:
|
|
52
|
+
declare function runCommand(cmd: RunnableCommand, argv: readonly string[], options?: RunCommandOptions): Promise<RunResult>;
|
|
28
53
|
//#endregion
|
|
29
|
-
export { type RunOptions, type RunResult, runCommand };
|
|
54
|
+
export { type RunCommandOptions, type RunOptions, type RunResult, runCommand };
|