@kjanat/dreamcli 3.0.1 → 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.
Files changed (137) hide show
  1. package/CHANGELOG.md +951 -1
  2. package/README.md +7 -3
  3. package/dist/core/cli/builtins.d.mts +47 -0
  4. package/dist/core/cli/builtins.mjs +135 -0
  5. package/dist/core/cli/compiled.d.mts +29 -0
  6. package/dist/core/cli/compiled.mjs +76 -0
  7. package/dist/core/cli/dispatch.d.mts +9 -85
  8. package/dist/core/cli/help-links.d.mts +2 -14
  9. package/dist/core/cli/index.d.mts +282 -101
  10. package/dist/core/cli/index.mjs +497 -264
  11. package/dist/core/cli/planner.d.mts +13 -86
  12. package/dist/core/cli/planner.mjs +47 -30
  13. package/dist/core/cli/plugin.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +1 -1
  15. package/dist/core/cli/reserved-flags.d.mts +1 -0
  16. package/dist/core/cli/reserved-flags.mjs +158 -0
  17. package/dist/core/cli/root-help.d.mts +1 -47
  18. package/dist/core/cli/root-help.mjs +37 -47
  19. package/dist/core/cli/root-output-flags.d.mts +1 -0
  20. package/dist/core/cli/root-output-flags.mjs +169 -0
  21. package/dist/core/cli/root-surface.d.mts +1 -68
  22. package/dist/core/cli/root-surface.mjs +2 -2
  23. package/dist/core/cli/runtime-preflight.d.mts +1 -199
  24. package/dist/core/cli/runtime-preflight.mjs +67 -17
  25. package/dist/core/completion/index.d.mts +2 -2
  26. package/dist/core/completion/shells/bash.d.mts +0 -1
  27. package/dist/core/completion/shells/bash.mjs +2 -1
  28. package/dist/core/completion/shells/fish.d.mts +0 -1
  29. package/dist/core/completion/shells/fish.mjs +2 -1
  30. package/dist/core/completion/shells/powershell.d.mts +0 -1
  31. package/dist/core/completion/shells/powershell.mjs +2 -1
  32. package/dist/core/completion/shells/shared.d.mts +3 -114
  33. package/dist/core/completion/shells/shared.mjs +9 -39
  34. package/dist/core/completion/shells/zsh.d.mts +0 -1
  35. package/dist/core/completion/shells/zsh.mjs +2 -1
  36. package/dist/core/config/index.d.mts +3 -3
  37. package/dist/core/config/index.mjs +2 -2
  38. package/dist/core/config/package-json.d.mts +2 -33
  39. package/dist/core/config/package-json.mjs +1 -34
  40. package/dist/core/errors/index.d.mts +7 -7
  41. package/dist/core/execution/index.d.mts +1 -48
  42. package/dist/core/execution/index.mjs +42 -27
  43. package/dist/core/help/ansi.d.mts +0 -11
  44. package/dist/core/help/index.d.mts +3 -35
  45. package/dist/core/help/index.mjs +29 -6
  46. package/dist/core/help/theme.d.mts +1 -21
  47. package/dist/core/json-schema/index.d.mts +279 -10
  48. package/dist/core/json-schema/index.mjs +482 -237
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
  51. package/dist/core/output/activity.d.mts +1 -193
  52. package/dist/core/output/activity.mjs +1 -1
  53. package/dist/core/output/bind.d.mts +1 -37
  54. package/dist/core/output/contracts.d.mts +7 -13
  55. package/dist/core/output/contracts.mjs +1 -1
  56. package/dist/core/output/display-value.d.mts +1 -19
  57. package/dist/core/output/index.d.mts +5 -187
  58. package/dist/core/output/index.mjs +44 -9
  59. package/dist/core/output/renderers.d.mts +1 -45
  60. package/dist/core/output/writer.d.mts +0 -1
  61. package/dist/core/parse/index.d.mts +27 -5
  62. package/dist/core/parse/index.mjs +350 -227
  63. package/dist/core/parse/occurrences.d.mts +89 -0
  64. package/dist/core/parse/occurrences.mjs +114 -0
  65. package/dist/core/prompt/index.d.mts +3 -3
  66. package/dist/core/read-flags/index.d.mts +150 -0
  67. package/dist/core/read-flags/index.mjs +217 -0
  68. package/dist/core/resolve/args.d.mts +35 -4
  69. package/dist/core/resolve/args.mjs +132 -55
  70. package/dist/core/resolve/coerce.d.mts +66 -9
  71. package/dist/core/resolve/coerce.mjs +834 -270
  72. package/dist/core/resolve/config.d.mts +1 -10
  73. package/dist/core/resolve/contracts.d.mts +67 -44
  74. package/dist/core/resolve/errors.mjs +29 -21
  75. package/dist/core/resolve/flags.d.mts +36 -9
  76. package/dist/core/resolve/flags.mjs +129 -151
  77. package/dist/core/resolve/index.d.mts +8 -6
  78. package/dist/core/resolve/index.mjs +51 -18
  79. package/dist/core/resolve/path-checks.d.mts +47 -0
  80. package/dist/core/resolve/path-checks.mjs +102 -0
  81. package/dist/core/resolve/redaction.d.mts +12 -0
  82. package/dist/core/resolve/redaction.mjs +14 -0
  83. package/dist/core/resolve/stages.d.mts +85 -0
  84. package/dist/core/resolve/stages.mjs +170 -0
  85. package/dist/core/resolve/standard.d.mts +1 -24
  86. package/dist/core/resolve/standard.mjs +141 -43
  87. package/dist/core/schema/activity.d.mts +16 -16
  88. package/dist/core/schema/arg.d.mts +849 -71
  89. package/dist/core/schema/arg.mjs +727 -54
  90. package/dist/core/schema/brand.d.mts +17 -0
  91. package/dist/core/schema/cardinality.d.mts +301 -0
  92. package/dist/core/schema/cardinality.mjs +514 -0
  93. package/dist/core/schema/command.d.mts +181 -112
  94. package/dist/core/schema/command.mjs +305 -42
  95. package/dist/core/schema/flag.d.mts +515 -173
  96. package/dist/core/schema/flag.mjs +576 -78
  97. package/dist/core/schema/index.d.mts +11 -8
  98. package/dist/core/schema/index.mjs +10 -0
  99. package/dist/core/schema/middleware.d.mts +15 -12
  100. package/dist/core/schema/number-constraints.d.mts +5 -5
  101. package/dist/core/schema/prompt.d.mts +4 -4
  102. package/dist/core/schema/provenance.d.mts +99 -0
  103. package/dist/core/schema/provenance.mjs +28 -0
  104. package/dist/core/schema/run.d.mts +21 -60
  105. package/dist/core/schema/source.d.mts +179 -0
  106. package/dist/core/schema/source.mjs +206 -0
  107. package/dist/core/schema/standard.d.mts +12 -19
  108. package/dist/core/schema/stdin.d.mts +87 -0
  109. package/dist/core/schema/stdin.mjs +91 -0
  110. package/dist/core/schema/string-constraints.d.mts +16 -5
  111. package/dist/core/schema/string-constraints.mjs +18 -1
  112. package/dist/core/schema/value-parsers.d.mts +81 -9
  113. package/dist/core/schema/value-parsers.mjs +19 -1
  114. package/dist/core/schema/value.d.mts +242 -0
  115. package/dist/core/schema/value.mjs +573 -0
  116. package/dist/core/testkit/index.d.mts +28 -3
  117. package/dist/core/testkit/index.mjs +40 -26
  118. package/dist/index.d.mts +21 -16
  119. package/dist/index.mjs +10 -6
  120. package/dist/runtime/adapter.d.mts +3 -3
  121. package/dist/runtime/deno.d.mts +3 -3
  122. package/dist/runtime/detect.d.mts +2 -2
  123. package/dist/runtime/node.d.mts +3 -3
  124. package/dist/runtime/paths.d.mts +1 -31
  125. package/dist/runtime.d.mts +4 -4
  126. package/dist/strings.d.mts +1 -16
  127. package/dist/testkit.d.mts +2 -2
  128. package/dist/testkit.mjs +1 -1
  129. package/dist/version.d.mts +0 -13
  130. package/dist/version.mjs +2 -2
  131. package/dreamcli.schema.json +368 -78
  132. package/examples/interactive.ts +6 -5
  133. package/package.json +9 -9
  134. package/skills/cli-creation/SKILL.md +72 -16
  135. package/skills/cli-creation/references/pattern-cookbook.md +169 -11
  136. package/dist/core/resolve/property.d.mts +0 -51
  137. package/dist/core/resolve/property.mjs +0 -53
@@ -0,0 +1,514 @@
1
+ import { CLIError } from "../errors/index.mjs";
2
+ import { describeValueFailure, validateDecodedValue } from "./value.mjs";
3
+ //#region src/core/schema/cardinality.ts
4
+ /**
5
+ * The cardinality axis shared by the `flag` and `arg` factories.
6
+ *
7
+ * A {@link Cardinality} says how many values an input carries and how they
8
+ * combine: one value, many values, key/value entries, or an occurrence count.
9
+ * `flag.array()`, `flag.keyValue()`, `flag.count()`, `arg.keyValue()`, and
10
+ * `.variadic()` all normalize onto it, and the parse and resolve pipelines
11
+ * dispatch on {@link flagCardinality} / {@link argCardinality} rather than on
12
+ * the kind discriminator.
13
+ *
14
+ * Splitting is per source. {@link splitBindingOf} resolves one
15
+ * {@link SplitPolicy} for CLI tokens, one for environment values, and one for
16
+ * the stdin buffer, so a CLI separator no longer decides how an env var or a
17
+ * pipe decodes. A cardinality carries the CLI policy alone, which is the one
18
+ * the parse boundary needs; every other source reads its policy off its own
19
+ * {@link SourceBinding | source binding}.
20
+ *
21
+ * @module dreamcli/core/schema/cardinality
22
+ * @internal
23
+ */
24
+ /** All split formats as a runtime array. */
25
+ const SPLIT_FORMATS = [
26
+ "whole",
27
+ "delimiter",
28
+ "lines",
29
+ "json"
30
+ ];
31
+ /** The whole-value policy, shared by every source that declares none. */
32
+ const WHOLE = { format: "whole" };
33
+ /** The line policy stdin collections take by default. */
34
+ const LINES = { format: "lines" };
35
+ /** The comma policy environment collections take by default. */
36
+ const ENV_DEFAULT = {
37
+ format: "delimiter",
38
+ delimiter: ","
39
+ };
40
+ /** The formats a bare string names, none of which carry a delimiter. */
41
+ const NAMED_SPLIT_POLICIES = {
42
+ whole: WHOLE,
43
+ lines: LINES,
44
+ json: { format: "json" }
45
+ };
46
+ /** Which formats each source accepts. */
47
+ const ALLOWED_SPLIT_FORMATS = {
48
+ cli: ["whole", "delimiter"],
49
+ env: [
50
+ "whole",
51
+ "delimiter",
52
+ "json"
53
+ ],
54
+ stdin: [
55
+ "whole",
56
+ "delimiter",
57
+ "lines",
58
+ "json"
59
+ ]
60
+ };
61
+ /**
62
+ * Read a bare string as the format it names, or as the delimiter to split on.
63
+ *
64
+ * @param setting - The string a caller passed for one source.
65
+ * @returns The policy the string stands for.
66
+ */
67
+ function splitPolicyFromString(setting) {
68
+ return Object.hasOwn(NAMED_SPLIT_POLICIES, setting) ? NAMED_SPLIT_POLICIES[setting] ?? WHOLE : {
69
+ format: "delimiter",
70
+ delimiter: setting
71
+ };
72
+ }
73
+ /**
74
+ * Normalize one source's split setting.
75
+ *
76
+ * @param source - Which source the setting belongs to.
77
+ * @param setting - The policy, a format name, or a delimiter.
78
+ * @returns The normalized policy.
79
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a format the source does
80
+ * not accept, or an empty delimiter.
81
+ */
82
+ function normalizeSplitPolicy(source, setting) {
83
+ if (typeof setting === "string") return normalizeSplitPolicyObject(source, splitPolicyFromString(setting));
84
+ if (typeof setting !== "object" || setting === null) throw new CLIError(`Split policy for ${source} must be a string or object`, {
85
+ code: "INVALID_SCHEMA",
86
+ details: {
87
+ source,
88
+ received: setting === null ? "null" : typeof setting
89
+ },
90
+ suggest: "Pass a format name, delimiter string, or split-policy object"
91
+ });
92
+ return normalizeSplitPolicyObject(source, setting);
93
+ }
94
+ /** Validate and normalize an object-form split policy from a typed or JavaScript caller. */
95
+ function normalizeSplitPolicyObject(source, setting) {
96
+ const policy = setting;
97
+ if (typeof policy.format !== "string") throw new CLIError(`Split policy for ${source} requires a string format`, {
98
+ code: "INVALID_SCHEMA",
99
+ details: {
100
+ source,
101
+ field: "format",
102
+ received: typeof policy.format
103
+ },
104
+ suggest: "Pass a supported split format"
105
+ });
106
+ const allowed = ALLOWED_SPLIT_FORMATS[source];
107
+ if (!allowed.includes(policy.format)) throw new CLIError(`Split format '${String(policy.format)}' is not available for ${source}`, {
108
+ code: "INVALID_SCHEMA",
109
+ details: {
110
+ source,
111
+ format: policy.format,
112
+ allowed: [...allowed]
113
+ },
114
+ suggest: `Use one of: ${allowed.filter((format) => format !== "delimiter").join(", ")}, or a delimiter string`
115
+ });
116
+ if (policy.format !== "delimiter") return { format: policy.format };
117
+ if (typeof policy.delimiter !== "string") throw new CLIError(`Split delimiter for ${source} must be a string`, {
118
+ code: "INVALID_SCHEMA",
119
+ details: {
120
+ source,
121
+ format: policy.format,
122
+ received: typeof policy.delimiter
123
+ },
124
+ suggest: "Pass a delimiter string, for example ','"
125
+ });
126
+ if (policy.delimiter.length === 0) throw new CLIError(`Split delimiter for ${source} must not be empty`, {
127
+ code: "INVALID_SCHEMA",
128
+ details: {
129
+ source,
130
+ format: policy.format
131
+ },
132
+ suggest: "Pass a non-empty delimiter, for example ','"
133
+ });
134
+ return {
135
+ format: "delimiter",
136
+ delimiter: policy.delimiter
137
+ };
138
+ }
139
+ /**
140
+ * Normalize `.split()` options into the fields a schema stores.
141
+ *
142
+ * A source the options leave out keeps the policy already stored, so successive
143
+ * `.split()` calls each set one source instead of clearing the others.
144
+ *
145
+ * @param options - Per-source split settings.
146
+ * @param stored - The binding already on the schema, when there is one.
147
+ * @returns The CLI delimiter and the stored non-CLI binding.
148
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a format a source does not
149
+ * accept, or an empty delimiter.
150
+ */
151
+ function normalizeSplitOptions(options, stored) {
152
+ const cli = options.cli === void 0 ? void 0 : normalizeSplitPolicy("cli", options.cli);
153
+ const env = options.env === void 0 ? stored?.env : normalizeSplitPolicy("env", options.env);
154
+ const stdin = options.stdin === void 0 ? stored?.stdin : normalizeSplitPolicy("stdin", options.stdin);
155
+ return {
156
+ separator: cli !== void 0 && cli.format === "delimiter" ? cli.delimiter : void 0,
157
+ setsSeparator: cli !== void 0,
158
+ split: env === void 0 && stdin === void 0 ? void 0 : {
159
+ env,
160
+ stdin
161
+ }
162
+ };
163
+ }
164
+ /**
165
+ * Resolve the split policy of every source from the stored fields.
166
+ *
167
+ * @param separator - The CLI delimiter carrier.
168
+ * @param split - The stored non-CLI policies.
169
+ * @returns One policy per source, defaults filled in.
170
+ */
171
+ function splitBindingOf(separator, split) {
172
+ return {
173
+ cli: separator === void 0 ? WHOLE : {
174
+ format: "delimiter",
175
+ delimiter: separator
176
+ },
177
+ env: split?.env ?? ENV_DEFAULT,
178
+ stdin: split?.stdin ?? LINES
179
+ };
180
+ }
181
+ /** All duplicate-key policies as a runtime array. */
182
+ const DUPLICATE_KEYS = [
183
+ "first",
184
+ "last",
185
+ "error"
186
+ ];
187
+ /** The single-value cardinality, shared by every scalar input. */
188
+ const ONE = { kind: "one" };
189
+ /** The occurrence-count cardinality. */
190
+ const COUNT = { kind: "count" };
191
+ /**
192
+ * Project a flag schema onto its cardinality axis.
193
+ *
194
+ * @param schema - The flag schema to read.
195
+ * @returns How the flag's values combine.
196
+ */
197
+ function flagCardinality(schema) {
198
+ switch (schema.kind) {
199
+ case "array": return {
200
+ kind: "many",
201
+ unique: schema.unique,
202
+ cliSplit: splitBindingOf(schema.separator, schema.split).cli
203
+ };
204
+ case "keyValue": return {
205
+ kind: "entries",
206
+ duplicateKeys: schema.duplicateKeys,
207
+ cliSplit: splitBindingOf(schema.separator, schema.split).cli
208
+ };
209
+ case "count": return COUNT;
210
+ case "string":
211
+ case "number":
212
+ case "boolean":
213
+ case "enum":
214
+ case "custom": return ONE;
215
+ }
216
+ }
217
+ /**
218
+ * Project an arg schema onto its cardinality axis.
219
+ *
220
+ * A `keyValue` arg aggregates entries whether or not it is variadic: the
221
+ * non-variadic form reads one `k=v` token, the variadic form the whole tail.
222
+ *
223
+ * @param schema - The arg schema to read.
224
+ * @returns How the arg's values combine.
225
+ */
226
+ function argCardinality(schema) {
227
+ if (schema.kind === "keyValue") return {
228
+ kind: "entries",
229
+ duplicateKeys: schema.duplicateKeys,
230
+ cliSplit: splitBindingOf(schema.separator, schema.split).cli
231
+ };
232
+ if (schema.variadic) return {
233
+ kind: "many",
234
+ unique: schema.unique,
235
+ cliSplit: splitBindingOf(schema.separator, schema.split).cli
236
+ };
237
+ return ONE;
238
+ }
239
+ /** Whether a cardinality aggregates several values. */
240
+ function isCollection(cardinality) {
241
+ return cardinality.kind === "many" || cardinality.kind === "entries";
242
+ }
243
+ /**
244
+ * Split text into the elements of a `many` collection.
245
+ *
246
+ * @param policy - The source's split policy.
247
+ * @param text - The raw source text.
248
+ * @returns The elements, or why the text was unreadable.
249
+ */
250
+ function splitManyText(policy, text) {
251
+ switch (policy.format) {
252
+ case "whole": return {
253
+ ok: true,
254
+ parts: text.length === 0 ? [] : [text]
255
+ };
256
+ case "delimiter": return {
257
+ ok: true,
258
+ parts: splitDelimited(text, policy.delimiter)
259
+ };
260
+ case "lines": return {
261
+ ok: true,
262
+ parts: splitLines(text)
263
+ };
264
+ case "json": {
265
+ const parsed = parseJson(text);
266
+ if (!parsed.ok) return parsed;
267
+ if (!Array.isArray(parsed.value)) return {
268
+ ok: false,
269
+ failure: {
270
+ kind: "json-shape",
271
+ expected: "array"
272
+ }
273
+ };
274
+ return {
275
+ ok: true,
276
+ parts: parsed.value
277
+ };
278
+ }
279
+ }
280
+ }
281
+ /**
282
+ * Split text into the pairs of an `entries` collection.
283
+ *
284
+ * Delimited and line-separated text carries `KEY=VALUE` segments split at the
285
+ * first `=`; JSON text carries an object.
286
+ *
287
+ * @param policy - The source's split policy.
288
+ * @param text - The raw source text.
289
+ * @returns The pairs, or why the text was unreadable.
290
+ */
291
+ function splitEntriesText(policy, text) {
292
+ if (policy.format === "json") {
293
+ const parsed = parseJson(text);
294
+ if (!parsed.ok) return parsed;
295
+ const record = parsed.value;
296
+ if (typeof record !== "object" || record === null || Array.isArray(record)) return {
297
+ ok: false,
298
+ failure: {
299
+ kind: "json-shape",
300
+ expected: "object"
301
+ }
302
+ };
303
+ return {
304
+ ok: true,
305
+ parts: Object.entries(record)
306
+ };
307
+ }
308
+ const segments = policy.format === "whole" ? text.length === 0 ? [] : [text] : policy.format === "lines" ? splitLines(text) : splitDelimited(text, policy.delimiter);
309
+ const pairs = [];
310
+ for (const segment of segments) {
311
+ const pair = splitEntryPair(segment);
312
+ if (pair === void 0) return {
313
+ ok: false,
314
+ failure: {
315
+ kind: "pair",
316
+ raw: segment
317
+ }
318
+ };
319
+ pairs.push(pair);
320
+ }
321
+ return {
322
+ ok: true,
323
+ parts: pairs
324
+ };
325
+ }
326
+ /**
327
+ * Split one `KEY=VALUE` token at the first `=`.
328
+ *
329
+ * @param raw - The token to split.
330
+ * @returns The pair, or `undefined` when the token has no `=` or an empty key.
331
+ */
332
+ function splitEntryPair(raw) {
333
+ const equals = raw.indexOf("=");
334
+ if (equals <= 0) return void 0;
335
+ return [raw.slice(0, equals), raw.slice(equals + 1)];
336
+ }
337
+ /** Split on a literal delimiter, dropping empty segments. */
338
+ function splitDelimited(text, delimiter) {
339
+ return text.split(delimiter).filter((part) => part.length > 0);
340
+ }
341
+ /**
342
+ * Split text on line terminators.
343
+ *
344
+ * A final terminator frames the last line rather than starting an empty one, so
345
+ * the single empty element it produces is removed and genuine blank lines
346
+ * survive: `'a\nb\n'` gives `['a', 'b']` and `'a\nb\n\n'` gives `['a', 'b', '']`.
347
+ *
348
+ * @param text - The raw source text.
349
+ * @returns One element per line.
350
+ */
351
+ function splitLines(text) {
352
+ if (text.length === 0) return [];
353
+ const parts = text.split(/\r\n|\n|\r/);
354
+ if (parts.length > 1 && parts[parts.length - 1] === "") parts.pop();
355
+ return parts;
356
+ }
357
+ /** Parse JSON text, reporting the thrown error rather than throwing it. */
358
+ function parseJson(text) {
359
+ try {
360
+ return {
361
+ ok: true,
362
+ value: JSON.parse(text)
363
+ };
364
+ } catch (error) {
365
+ return {
366
+ ok: false,
367
+ failure: {
368
+ kind: "json",
369
+ error
370
+ }
371
+ };
372
+ }
373
+ }
374
+ /** Deduplicate a resolved array, preserving first-seen order. */
375
+ function dedupe(values) {
376
+ return [...new Set(values)];
377
+ }
378
+ /**
379
+ * Fold ordered pairs into a record under a duplicate-key policy.
380
+ *
381
+ * `Object.fromEntries` defines own data properties, so a `'__proto__'` key is
382
+ * stored verbatim instead of reaching the prototype setter.
383
+ *
384
+ * @param pairs - The pairs in occurrence order.
385
+ * @param duplicateKeys - What a repeated key means.
386
+ * @returns The record, or the key that repeated under `'error'` and where.
387
+ */
388
+ function foldEntries(pairs, duplicateKeys) {
389
+ const kept = /* @__PURE__ */ new Map();
390
+ for (const [at, [key, value]] of pairs.entries()) {
391
+ if (kept.has(key)) {
392
+ if (duplicateKeys === "error") return {
393
+ ok: false,
394
+ duplicateKey: key,
395
+ at
396
+ };
397
+ if (duplicateKeys === "first") continue;
398
+ }
399
+ kept.set(key, value);
400
+ }
401
+ return {
402
+ ok: true,
403
+ value: Object.fromEntries(kept)
404
+ };
405
+ }
406
+ /**
407
+ * Validate a declared default against the value and cardinality axes.
408
+ *
409
+ * A default is already the typed value, so it is validated rather than decoded.
410
+ * Only synchronous verdicts are reachable here: a Standard Schema validator
411
+ * that returns a promise is left to the resolution-time pass, as are filesystem
412
+ * checks.
413
+ *
414
+ * @param element - The value axis of each element (of the value itself for `'one'`).
415
+ * @param cardinality - How the input's values combine.
416
+ * @param aggregate - Standard Schema validator applied to the completed collection.
417
+ * @param value - The declared default.
418
+ * @returns The violation, or `undefined` when the default is valid so far.
419
+ */
420
+ function validateDefault(element, cardinality, aggregate, value) {
421
+ switch (cardinality.kind) {
422
+ case "one": return validateDefaultElement(element, void 0, value);
423
+ case "count": return typeof value === "number" && Number.isInteger(value) && value >= 0 ? void 0 : {
424
+ kind: "shape",
425
+ expected: "count"
426
+ };
427
+ case "many":
428
+ if (!Array.isArray(value)) return {
429
+ kind: "shape",
430
+ expected: "array"
431
+ };
432
+ for (const [index, entry] of value.entries()) {
433
+ const violation = validateDefaultElement(element, String(index), entry);
434
+ if (violation !== void 0) return violation;
435
+ }
436
+ return validateDefaultStandard(aggregate, void 0, value);
437
+ case "entries":
438
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return {
439
+ kind: "shape",
440
+ expected: "object"
441
+ };
442
+ for (const [key, entry] of Object.entries(value)) {
443
+ const violation = validateDefaultElement(element, key, entry);
444
+ if (violation !== void 0) return violation;
445
+ }
446
+ return validateDefaultStandard(aggregate, void 0, value);
447
+ }
448
+ }
449
+ /** Apply the element constraints and the element validator to one default entry. */
450
+ function validateDefaultElement(element, at, value) {
451
+ const failure = validateDecodedValue(element, value);
452
+ if (failure !== void 0) return {
453
+ kind: "element",
454
+ at,
455
+ value,
456
+ failure
457
+ };
458
+ return validateDefaultStandard(element.standard, at, value);
459
+ }
460
+ /** Apply a validator whose verdict is available synchronously. */
461
+ function validateDefaultStandard(validator, at, value) {
462
+ if (validator === void 0) return void 0;
463
+ const result = validator["~standard"].validate(value);
464
+ if (result instanceof Promise) return void 0;
465
+ if (result.issues === void 0) return void 0;
466
+ return {
467
+ kind: "standard",
468
+ at,
469
+ value,
470
+ issues: result.issues.map((issue) => issue.message)
471
+ };
472
+ }
473
+ /** Vowel-initial kind names, for the article a message puts before one. */
474
+ const VOWEL_INITIAL = /^[aeiou]/i;
475
+ /**
476
+ * The English article that precedes a kind name.
477
+ *
478
+ * @param word - The kind name a message names an input by.
479
+ * @returns `'an'` before a vowel, `'a'` otherwise.
480
+ */
481
+ function indefiniteArticle(word) {
482
+ return VOWEL_INITIAL.test(word) ? "an" : "a";
483
+ }
484
+ /**
485
+ * Build the construction-time error for a default value that cannot hold.
486
+ *
487
+ * @param subject - How the input is spelled, `--tag` or `<files>`.
488
+ * @param details - Structured identification of the input.
489
+ * @param violation - What the default failed.
490
+ * @returns The error to throw.
491
+ */
492
+ function defaultViolationError(subject, details, violation) {
493
+ const at = "at" in violation && violation.at !== void 0 ? ` at ${violation.at}` : "";
494
+ const reason = describeDefaultViolation(violation);
495
+ return new CLIError(`Default value for ${subject}${at} is invalid: ${reason}`, {
496
+ code: "INVALID_DEFAULT",
497
+ details: {
498
+ ...details,
499
+ ...at === "" ? {} : { at: "at" in violation ? violation.at : void 0 },
500
+ reason
501
+ },
502
+ suggest: `Change the default so it satisfies what ${subject} accepts`
503
+ });
504
+ }
505
+ /** State the reason a default was rejected. */
506
+ function describeDefaultViolation(violation) {
507
+ switch (violation.kind) {
508
+ case "shape": return violation.expected === "count" ? "expected a non-negative integer" : `expected an ${violation.expected}`;
509
+ case "element": return describeValueFailure(violation.failure);
510
+ case "standard": return violation.issues.join("; ");
511
+ }
512
+ }
513
+ //#endregion
514
+ export { DUPLICATE_KEYS, SPLIT_FORMATS, argCardinality, dedupe, defaultViolationError, flagCardinality, foldEntries, indefiniteArticle, isCollection, normalizeSplitOptions, normalizeSplitPolicy, splitBindingOf, splitEntriesText, splitEntryPair, splitLines, splitManyText, validateDefault };