@kjanat/dreamcli 4.0.0-rc.3 → 4.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.
Files changed (212) hide show
  1. package/README.md +5 -7
  2. package/dist/{runtime/adapter.d.mts → adapter-D0hbBNVB.d.mts} +2 -4
  3. package/dist/completion-D4mz6axB.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-B9ddC-Kb.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-Cp2w8vRq.mjs +17 -0
  10. package/dist/index-BziI2aKc.d.mts +5440 -0
  11. package/dist/index-DOfClfYR.d.mts +370 -0
  12. package/dist/index-DWsnGZlx.d.mts +831 -0
  13. package/dist/{core/cli/index.d.mts → index-DXROeDPC.d.mts} +116 -57
  14. package/dist/index-DndPmT8J.d.mts +275 -0
  15. package/dist/{core/json-schema/index.d.mts → index-DyoaS234.d.mts} +43 -34
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-C9SzZ7jY.mjs +52 -0
  19. package/dist/json-schema.d.mts +2 -0
  20. package/dist/json-schema.mjs +1 -0
  21. package/dist/package-json-BgE9YjjQ.mjs +3 -0
  22. package/dist/prompt.d.mts +48 -0
  23. package/dist/prompt.mjs +1 -0
  24. package/dist/rolldown-runtime-G4Kt5YOX.mjs +1 -0
  25. package/dist/runtime.d.mts +2 -6
  26. package/dist/runtime.mjs +1 -6
  27. package/dist/terminal-C8KTXjv5.mjs +6 -0
  28. package/dist/test-prompter-v__jT2yG.mjs +1 -0
  29. package/dist/testkit.d.mts +54 -6
  30. package/dist/testkit.mjs +1 -5
  31. package/dist/version.mjs +1 -7
  32. package/dreamcli.schema.json +697 -538
  33. package/package.json +29 -7
  34. package/skills/cli-creation/SKILL.md +16 -11
  35. package/CHANGELOG.md +0 -1116
  36. package/dist/core/cli/builtins.d.mts +0 -117
  37. package/dist/core/cli/builtins.mjs +0 -135
  38. package/dist/core/cli/compiled.d.mts +0 -66
  39. package/dist/core/cli/compiled.mjs +0 -76
  40. package/dist/core/cli/dispatch.d.mts +0 -115
  41. package/dist/core/cli/dispatch.mjs +0 -205
  42. package/dist/core/cli/help-links.d.mts +0 -27
  43. package/dist/core/cli/help-links.mjs +0 -41
  44. package/dist/core/cli/index.mjs +0 -1271
  45. package/dist/core/cli/planner.d.mts +0 -174
  46. package/dist/core/cli/planner.mjs +0 -323
  47. package/dist/core/cli/plugin.d.mts +0 -94
  48. package/dist/core/cli/plugin.mjs +0 -41
  49. package/dist/core/cli/propagate.d.mts +0 -39
  50. package/dist/core/cli/propagate.mjs +0 -57
  51. package/dist/core/cli/reserved-flags.d.mts +0 -19
  52. package/dist/core/cli/reserved-flags.mjs +0 -158
  53. package/dist/core/cli/root-help.d.mts +0 -53
  54. package/dist/core/cli/root-help.mjs +0 -221
  55. package/dist/core/cli/root-output-flags.d.mts +0 -74
  56. package/dist/core/cli/root-output-flags.mjs +0 -169
  57. package/dist/core/cli/root-surface.d.mts +0 -64
  58. package/dist/core/cli/root-surface.mjs +0 -28
  59. package/dist/core/cli/runtime-preflight.d.mts +0 -213
  60. package/dist/core/cli/runtime-preflight.mjs +0 -221
  61. package/dist/core/completion/index.d.mts +0 -76
  62. package/dist/core/completion/index.mjs +0 -90
  63. package/dist/core/completion/shells/bash.d.mts +0 -23
  64. package/dist/core/completion/shells/bash.mjs +0 -312
  65. package/dist/core/completion/shells/fish.d.mts +0 -19
  66. package/dist/core/completion/shells/fish.mjs +0 -164
  67. package/dist/core/completion/shells/powershell.d.mts +0 -13
  68. package/dist/core/completion/shells/powershell.mjs +0 -360
  69. package/dist/core/completion/shells/shared.d.mts +0 -164
  70. package/dist/core/completion/shells/shared.mjs +0 -147
  71. package/dist/core/completion/shells/zsh.d.mts +0 -23
  72. package/dist/core/completion/shells/zsh.mjs +0 -256
  73. package/dist/core/config/index.d.mts +0 -191
  74. package/dist/core/config/index.mjs +0 -285
  75. package/dist/core/config/package-json.d.mts +0 -179
  76. package/dist/core/config/package-json.mjs +0 -353
  77. package/dist/core/errors/index.d.mts +0 -125
  78. package/dist/core/errors/index.mjs +0 -87
  79. package/dist/core/execution/index.d.mts +0 -61
  80. package/dist/core/execution/index.mjs +0 -220
  81. package/dist/core/help/ansi.d.mts +0 -84
  82. package/dist/core/help/ansi.mjs +0 -121
  83. package/dist/core/help/index.d.mts +0 -149
  84. package/dist/core/help/index.mjs +0 -418
  85. package/dist/core/help/theme.d.mts +0 -86
  86. package/dist/core/help/theme.mjs +0 -69
  87. package/dist/core/json-schema/index.mjs +0 -1008
  88. package/dist/core/json-schema/meta-descriptions.generated.d.mts +0 -274
  89. package/dist/core/json-schema/meta-descriptions.generated.mjs +0 -136
  90. package/dist/core/output/activity.d.mts +0 -193
  91. package/dist/core/output/activity.mjs +0 -452
  92. package/dist/core/output/bind.d.mts +0 -37
  93. package/dist/core/output/bind.mjs +0 -56
  94. package/dist/core/output/contracts.d.mts +0 -82
  95. package/dist/core/output/contracts.mjs +0 -57
  96. package/dist/core/output/display-value.d.mts +0 -19
  97. package/dist/core/output/display-value.mjs +0 -32
  98. package/dist/core/output/index.d.mts +0 -344
  99. package/dist/core/output/index.mjs +0 -514
  100. package/dist/core/output/renderers.d.mts +0 -45
  101. package/dist/core/output/renderers.mjs +0 -46
  102. package/dist/core/output/writer.d.mts +0 -39
  103. package/dist/core/output/writer.mjs +0 -12
  104. package/dist/core/parse/index.d.mts +0 -178
  105. package/dist/core/parse/index.mjs +0 -850
  106. package/dist/core/parse/occurrences.d.mts +0 -90
  107. package/dist/core/parse/occurrences.mjs +0 -114
  108. package/dist/core/prompt/index.d.mts +0 -213
  109. package/dist/core/prompt/index.mjs +0 -348
  110. package/dist/core/read-flags/index.d.mts +0 -150
  111. package/dist/core/read-flags/index.mjs +0 -217
  112. package/dist/core/resolve/args.d.mts +0 -39
  113. package/dist/core/resolve/args.mjs +0 -182
  114. package/dist/core/resolve/coerce.d.mts +0 -79
  115. package/dist/core/resolve/coerce.mjs +0 -900
  116. package/dist/core/resolve/config.d.mts +0 -10
  117. package/dist/core/resolve/config.mjs +0 -19
  118. package/dist/core/resolve/contracts.d.mts +0 -146
  119. package/dist/core/resolve/errors.d.mts +0 -10
  120. package/dist/core/resolve/errors.mjs +0 -148
  121. package/dist/core/resolve/flags.d.mts +0 -74
  122. package/dist/core/resolve/flags.mjs +0 -246
  123. package/dist/core/resolve/index.d.mts +0 -44
  124. package/dist/core/resolve/index.mjs +0 -123
  125. package/dist/core/resolve/path-checks.d.mts +0 -48
  126. package/dist/core/resolve/path-checks.mjs +0 -102
  127. package/dist/core/resolve/redaction.d.mts +0 -13
  128. package/dist/core/resolve/redaction.mjs +0 -14
  129. package/dist/core/resolve/stages.d.mts +0 -86
  130. package/dist/core/resolve/stages.mjs +0 -170
  131. package/dist/core/resolve/standard.d.mts +0 -26
  132. package/dist/core/resolve/standard.mjs +0 -212
  133. package/dist/core/schema/activity.d.mts +0 -189
  134. package/dist/core/schema/arg.d.mts +0 -1461
  135. package/dist/core/schema/arg.mjs +0 -1139
  136. package/dist/core/schema/brand.d.mts +0 -17
  137. package/dist/core/schema/cardinality.d.mts +0 -302
  138. package/dist/core/schema/cardinality.mjs +0 -514
  139. package/dist/core/schema/command.d.mts +0 -1132
  140. package/dist/core/schema/command.mjs +0 -999
  141. package/dist/core/schema/flag.d.mts +0 -1495
  142. package/dist/core/schema/flag.mjs +0 -1207
  143. package/dist/core/schema/index.d.mts +0 -15
  144. package/dist/core/schema/index.mjs +0 -10
  145. package/dist/core/schema/middleware.d.mts +0 -129
  146. package/dist/core/schema/middleware.mjs +0 -41
  147. package/dist/core/schema/number-constraints.d.mts +0 -96
  148. package/dist/core/schema/number-constraints.mjs +0 -60
  149. package/dist/core/schema/prompt.d.mts +0 -135
  150. package/dist/core/schema/provenance.d.mts +0 -99
  151. package/dist/core/schema/provenance.mjs +0 -28
  152. package/dist/core/schema/run.d.mts +0 -211
  153. package/dist/core/schema/source.d.mts +0 -180
  154. package/dist/core/schema/source.mjs +0 -206
  155. package/dist/core/schema/standard.d.mts +0 -100
  156. package/dist/core/schema/standard.mjs +0 -15
  157. package/dist/core/schema/stdin.d.mts +0 -97
  158. package/dist/core/schema/stdin.mjs +0 -91
  159. package/dist/core/schema/string-constraints.d.mts +0 -108
  160. package/dist/core/schema/string-constraints.mjs +0 -86
  161. package/dist/core/schema/value-parsers.d.mts +0 -150
  162. package/dist/core/schema/value-parsers.mjs +0 -160
  163. package/dist/core/schema/value.d.mts +0 -243
  164. package/dist/core/schema/value.mjs +0 -573
  165. package/dist/core/testkit/index.d.mts +0 -63
  166. package/dist/core/testkit/index.mjs +0 -102
  167. package/dist/runtime/adapter.mjs +0 -92
  168. package/dist/runtime/auto.d.mts +0 -25
  169. package/dist/runtime/auto.mjs +0 -45
  170. package/dist/runtime/deno.d.mts +0 -99
  171. package/dist/runtime/deno.mjs +0 -265
  172. package/dist/runtime/detect.d.mts +0 -86
  173. package/dist/runtime/detect.mjs +0 -45
  174. package/dist/runtime/index.d.mts +0 -6
  175. package/dist/runtime/node.d.mts +0 -71
  176. package/dist/runtime/node.mjs +0 -228
  177. package/dist/runtime/paths.d.mts +0 -31
  178. package/dist/runtime/paths.mjs +0 -48
  179. package/dist/strings.d.mts +0 -27
  180. package/dist/strings.mjs +0 -22
  181. package/examples/basic.ts +0 -37
  182. package/examples/flag-types.ts +0 -79
  183. package/examples/gh/package.json +0 -45
  184. package/examples/gh/src/commands/auth.ts +0 -66
  185. package/examples/gh/src/commands/issue.ts +0 -120
  186. package/examples/gh/src/commands/pr.ts +0 -125
  187. package/examples/gh/src/data/issues.yaml +0 -5
  188. package/examples/gh/src/data/issues.yaml.d.ts +0 -17
  189. package/examples/gh/src/data/pull-requests.yaml +0 -7
  190. package/examples/gh/src/data/pull-requests.yaml.d.ts +0 -18
  191. package/examples/gh/src/docs.ts +0 -11
  192. package/examples/gh/src/lib/auth.ts +0 -37
  193. package/examples/gh/src/lib/utils.ts +0 -17
  194. package/examples/gh/src/main.test.ts +0 -307
  195. package/examples/gh/src/main.ts +0 -46
  196. package/examples/help-config.ts +0 -43
  197. package/examples/interactive.ts +0 -67
  198. package/examples/json-mode.ts +0 -95
  199. package/examples/middleware.ts +0 -71
  200. package/examples/multi-command.ts +0 -66
  201. package/examples/output-extras.ts +0 -46
  202. package/examples/parser-control.ts +0 -40
  203. package/examples/pwsh-demo/README.md +0 -40
  204. package/examples/pwsh-demo/package.json +0 -41
  205. package/examples/pwsh-demo/pwsh-demo.cmd +0 -3
  206. package/examples/pwsh-demo/smoke-powershell.ps1 +0 -218
  207. package/examples/pwsh-demo/src/main.test.ts +0 -45
  208. package/examples/pwsh-demo/src/main.ts +0 -140
  209. package/examples/spinner-progress.ts +0 -49
  210. package/examples/standard-schema.ts +0 -45
  211. package/examples/testing.ts +0 -147
  212. package/examples/transport-launcher.ts +0 -85
@@ -1,573 +0,0 @@
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,63 +0,0 @@
1
- import { BuiltinsConfig } from "../cli/builtins.mjs";
2
- import { FlagBuilder, FlagConfig } from "../schema/flag.mjs";
3
- import { ArgBuilder, ArgConfig } from "../schema/arg.mjs";
4
- import { CommandBuilder, RunnableCommand } from "../schema/command.mjs";
5
- import { InternalRunOptions, RunOptions, RunResult } from "../schema/run.mjs";
6
- //#region src/core/testkit/index.d.ts
7
- /**
8
- * Options for {@linkcode runCommand}.
9
- *
10
- * Extends {@linkcode RunOptions} with the CLI-root state `runCommand()` mirrors,
11
- * following the way `CLIRunOptions` extends `CLIExecuteOptions` with the fields
12
- * only that layer needs.
13
- */
14
- interface RunCommandOptions extends RunOptions {
15
- /**
16
- * Which built-in flags the harness mirrors, matching the CLI the command is
17
- * registered on.
18
- *
19
- * A command that owns a released built-in (`cli(...).builtins({ json: 'off' })`
20
- * plus a `json` flag) must be tested with the same setting, otherwise the
21
- * harness strips the token before `parse()` sees it.
22
- *
23
- * @defaultValue every built-in `'on'`, mirroring an unconfigured CLI root
24
- */
25
- readonly builtins?: BuiltinsConfig;
26
- }
27
- /**
28
- * Run a command builder against the given argv with injected options.
29
- *
30
- * This is the testkit wrapper around the shared executor:
31
- * 1. Apply the CLI root-flag layer (detect/strip `--json` and `--quiet`/`-q`) so
32
- * copied real argv works
33
- * 2. Create or reuse capture output
34
- * 3. Build standalone schema/meta defaults when CLI dispatch did not
35
- * 4. Delegate parse -> resolve -> execute to the shared executor
36
- * 5. Return the structured result with captured buffers
37
- *
38
- * Errors are normalized by the shared executor into structured {@linkcode RunResult}s
39
- * with appropriate exit codes. The function never throws.
40
- *
41
- * @param cmd - The command builder (must have an action handler)
42
- * @param argv - Raw argv strings (NOT including the command name itself).
43
- * CLI-level `--json` and `--quiet`/`-q` before the `--` separator are honored
44
- * and stripped here, just like the real CLI root — so `['--json']` enables
45
- * JSON mode and `['--quiet']` sets quiet verbosity rather than failing as
46
- * unknown flags. Equivalent to `{ jsonMode: true }` / `{ verbosity: 'quiet' }`.
47
- * Both accept an explicit value (`--json=false`), and an invalid one fails
48
- * with the same `INVALID_VALUE` error the CLI root produces. Pass
49
- * `options.builtins` to mirror a CLI that released one of these tokens to its
50
- * commands.
51
- * @param options - Injectable runtime state
52
- * @returns Structured run result with exit code and captured output
53
- */
54
- declare function runCommand<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown> = Record<string, never>>(cmd: CommandBuilder<F, A, C>, argv: readonly string[], options?: RunCommandOptions): Promise<RunResult>;
55
- /**
56
- * Execution body behind {@linkcode runCommand}, accepting the
57
- * framework-populated channel, capture, schema, and meta fields.
58
- *
59
- * @internal
60
- */
61
- declare function runCommandInternal(cmd: RunnableCommand, argv: readonly string[], options?: InternalRunOptions): Promise<RunResult>;
62
- //#endregion
63
- export { type RunCommandOptions, type RunOptions, type RunResult, runCommand, runCommandInternal };