@kjanat/dreamcli 3.0.1 → 4.0.0-rc.2

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 +962 -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 +173 -119
  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 +30 -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 +12 -11
  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
@@ -1,57 +1,347 @@
1
+ import { CLIError } from "../errors/index.mjs";
1
2
  import { assertNumberConstraints } from "./number-constraints.mjs";
3
+ import { assertStringConstraints } from "./string-constraints.mjs";
4
+ import { argAggregateStandard, argValueSchema, booleanValue, bytesValue, dateValue, durationValue, numberValue, pathValue, standardValue, stringParsedValue, stringValue, urlValue, valueDefinitionFields } from "./value.mjs";
5
+ import { DUPLICATE_KEYS, argCardinality, defaultViolationError, indefiniteArticle, isCollection, normalizeSplitOptions, normalizeSplitPolicy, validateDefault } from "./cardinality.mjs";
2
6
  import { isStandardSchemaV1 } from "./standard.mjs";
7
+ import { normalizeStdinBinding } from "./stdin.mjs";
3
8
  //#region src/core/schema/arg.ts
4
9
  /**
5
10
  * Positional argument schema builder with full type inference.
6
11
  *
7
- * Each factory (`arg.string()`, `arg.number()`, `arg.enum()`, `arg.custom()`) returns an
8
- * immutable {@linkcode ArgBuilder} whose generic parameter tracks the value type,
9
- * presence state, and variadic flag through the fluent chain.
12
+ * Each factory (`arg.string()`, `arg.number()`, `arg.enum()`, `arg.custom()`,
13
+ * `arg.url()`, `arg.path()`, `arg.date()`, `arg.duration()`, `arg.bytes()`)
14
+ * returns an immutable {@linkcode ArgBuilder} whose generic parameter tracks the
15
+ * value type, presence state, and variadic flag through the fluent chain.
10
16
  *
11
17
  * @module dreamcli/core/schema/arg
12
18
  */
19
+ /** All arg kind discriminators as a runtime array. */
20
+ const ARG_KINDS = [
21
+ "string",
22
+ "number",
23
+ "boolean",
24
+ "enum",
25
+ "custom",
26
+ "keyValue"
27
+ ];
28
+ /** Fields only an arg that aggregates can carry. */
29
+ const COLLECTION_ARG_FIELDS = ["separator", "split"];
13
30
  /**
14
- * Create a raw {@link ArgSchema} object with sensible defaults.
31
+ * Fields that are only meaningful on one {@link ArgKind}, mapped to that kind.
32
+ */
33
+ const KIND_SPECIFIC_ARG_FIELDS = [
34
+ ["enumValues", "enum"],
35
+ ["numberConstraints", "number"],
36
+ ["stringConstraints", "string"],
37
+ ["pathChecks", "string"],
38
+ ["parseFn", "custom"],
39
+ ["duplicateKeys", "keyValue"],
40
+ ["elementSchema", "keyValue"]
41
+ ];
42
+ /** Every runtime key carried by a normalized {@link ArgSchema}. */
43
+ const NORMALIZED_ARG_SCHEMA_KEYS = [
44
+ "kind",
45
+ "presence",
46
+ "variadic",
47
+ "stdin",
48
+ "defaultValue",
49
+ "description",
50
+ "envVar",
51
+ "configPath",
52
+ "prompt",
53
+ "enumValues",
54
+ "elementSchema",
55
+ "numberConstraints",
56
+ "stringConstraints",
57
+ "pathChecks",
58
+ "valueHint",
59
+ "parseFn",
60
+ "separator",
61
+ "split",
62
+ "duplicateKeys",
63
+ "unique",
64
+ "standard",
65
+ "aggregateStandard",
66
+ "deprecated"
67
+ ];
68
+ /**
69
+ * Whether an element input already carries every normalized schema key.
70
+ *
71
+ * @param element - Element definition or schema.
72
+ * @returns `true` when the value is already a built {@link ArgSchema}.
73
+ */
74
+ function isNormalizedArgSchema(element) {
75
+ return NORMALIZED_ARG_SCHEMA_KEYS.every((key) => Object.hasOwn(element, key));
76
+ }
77
+ /**
78
+ * Reject positional-only fields on a key-value entry's value schema.
79
+ *
80
+ * Entry values use only their codec, constraints, validator, path checks, and
81
+ * value hint. Sources, presence, collection settings, metadata, and another
82
+ * key-value layer would otherwise be accepted and silently ignored.
83
+ *
84
+ * @param schema - Normalized schema proposed as an entry value.
85
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on an unsupported shape.
86
+ * @internal
87
+ */
88
+ function assertValidArgElementSchema(schema) {
89
+ if (schema.kind === "keyValue") throw new CLIError("Arg element schema kind 'keyValue' is not supported", {
90
+ code: "INVALID_SCHEMA",
91
+ details: {
92
+ kind: schema.kind,
93
+ field: "kind"
94
+ },
95
+ suggest: "Use a scalar value kind for the key-value element"
96
+ });
97
+ for (const [field, allowed] of [
98
+ ["presence", "required"],
99
+ ["variadic", false],
100
+ ["stdin", void 0],
101
+ ["defaultValue", void 0],
102
+ ["description", void 0],
103
+ ["envVar", void 0],
104
+ ["configPath", void 0],
105
+ ["prompt", void 0],
106
+ ["elementSchema", void 0],
107
+ ["separator", void 0],
108
+ ["split", void 0],
109
+ ["duplicateKeys", "last"],
110
+ ["unique", false],
111
+ ["aggregateStandard", void 0],
112
+ ["deprecated", void 0]
113
+ ]) {
114
+ if (schema[field] === allowed) continue;
115
+ throw new CLIError(`Arg element schema field '${String(field)}' is not supported`, {
116
+ code: "INVALID_SCHEMA",
117
+ details: {
118
+ kind: schema.kind,
119
+ field
120
+ },
121
+ suggest: `Drop '${String(field)}' from the key-value element`
122
+ });
123
+ }
124
+ }
125
+ /**
126
+ * Normalize an entries arg's element input into a built {@link ArgSchema}.
127
+ *
128
+ * An already-built schema is returned unchanged, so repeated normalization
129
+ * preserves element identity.
130
+ *
131
+ * @param element - Element definition or schema.
132
+ * @returns The element as a fully populated {@link ArgSchema}.
133
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when a nested element field
134
+ * belongs to a different {@link ArgKind}.
135
+ */
136
+ function normalizeArgElementSchema(element) {
137
+ if (isNormalizedArgSchema(element)) {
138
+ assertValidArgDefinition(element.kind, element);
139
+ assertValidArgElementSchema(element);
140
+ return element;
141
+ }
142
+ const { kind, ...fields } = element;
143
+ assertValidArgDefinition(kind, fields);
144
+ const schema = buildArgSchema(kind, normalizeArgDefinitionFields(fields));
145
+ assertValidArgElementSchema(schema);
146
+ return schema;
147
+ }
148
+ /**
149
+ * Resolve a definition's nested `elementSchema` into a built {@link ArgSchema}.
150
+ *
151
+ * @param fields - Definition fields excluding the kind discriminator.
152
+ * @returns The same fields with `elementSchema` normalized.
153
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when a nested element field
154
+ * belongs to a different {@link ArgKind}.
155
+ */
156
+ function normalizeArgDefinitionFields(fields) {
157
+ const { elementSchema, ...rest } = fields;
158
+ if (elementSchema === void 0) return rest;
159
+ return {
160
+ ...rest,
161
+ elementSchema: normalizeArgElementSchema(elementSchema)
162
+ };
163
+ }
164
+ /**
165
+ * Reject a definition that carries a field belonging to another {@link ArgKind}.
166
+ *
167
+ * A field set to `undefined` counts as absent, and `duplicateKeys` counts as
168
+ * absent when `'last'`, so re-feeding a built {@link ArgSchema} back through
169
+ * {@link createArgSchema} stays valid: a built schema always carries that
170
+ * default, whatever its kind. The compile-time `this` parameter on
171
+ * `.duplicateKeys()` is what rejects `.duplicateKeys('last')` on a scalar, since
172
+ * the runtime cannot tell that call apart from a round-tripped default.
173
+ *
174
+ * @param kind - Declared kind of the definition.
175
+ * @param fields - Definition fields excluding the kind discriminator.
176
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on an unknown kind or a kind
177
+ * mismatch.
178
+ */
179
+ function assertValidArgDefinition(kind, fields) {
180
+ assertKnownArgKind(kind);
181
+ for (const [field, requiredKind] of KIND_SPECIFIC_ARG_FIELDS) {
182
+ if (kind === requiredKind) continue;
183
+ if (fields[field] === void 0) continue;
184
+ if (field === "duplicateKeys" && fields[field] === "last") continue;
185
+ throw new CLIError(`Arg schema field '${field}' requires kind '${requiredKind}', received kind '${kind}'`, {
186
+ code: "INVALID_SCHEMA",
187
+ details: {
188
+ kind,
189
+ field,
190
+ requiredKind
191
+ },
192
+ suggest: `Drop '${field}' or declare the arg as kind '${requiredKind}'`
193
+ });
194
+ }
195
+ if (kind === "enum" && fields.enumValues === void 0) throw new CLIError("Arg schema kind 'enum' requires field 'enumValues'", {
196
+ code: "INVALID_SCHEMA",
197
+ details: {
198
+ kind,
199
+ field: "enumValues"
200
+ },
201
+ suggest: "Pass the allowed values in 'enumValues'"
202
+ });
203
+ if (fields.duplicateKeys !== void 0 && !DUPLICATE_KEYS.includes(fields.duplicateKeys)) throw new CLIError(`Unknown duplicate-key policy '${String(fields.duplicateKeys)}'`, {
204
+ code: "INVALID_SCHEMA",
205
+ details: {
206
+ duplicateKeys: fields.duplicateKeys,
207
+ allowed: [...DUPLICATE_KEYS]
208
+ },
209
+ suggest: `Use one of: ${DUPLICATE_KEYS.join(", ")}`
210
+ });
211
+ const aggregates = kind === "keyValue" || fields.variadic === true;
212
+ if (fields.aggregateStandard !== void 0 && !aggregates) throw new CLIError(`Arg schema field 'aggregateStandard' requires a collection, received a non-variadic '${kind}' arg`, {
213
+ code: "INVALID_SCHEMA",
214
+ details: {
215
+ kind,
216
+ field: "aggregateStandard"
217
+ },
218
+ suggest: "Add 'variadic: true', declare the arg as kind 'keyValue', or use 'standard'"
219
+ });
220
+ if (kind === "keyValue" && fields.prompt !== void 0) throw new CLIError("Arg schema field 'prompt' is not available on kind 'keyValue'", {
221
+ code: "INVALID_SCHEMA",
222
+ details: {
223
+ kind,
224
+ field: "prompt"
225
+ },
226
+ suggest: "Drop 'prompt' from the keyValue argument"
227
+ });
228
+ for (const field of COLLECTION_ARG_FIELDS) {
229
+ if (fields[field] === void 0 || aggregates) continue;
230
+ throw new CLIError(`Arg schema field '${field}' requires a collection, received a non-variadic '${kind}' arg`, {
231
+ code: "INVALID_SCHEMA",
232
+ details: {
233
+ kind,
234
+ field
235
+ },
236
+ suggest: `Add 'variadic: true', declare the arg as kind 'keyValue', or drop '${field}'`
237
+ });
238
+ }
239
+ if (fields.unique === true && (kind === "keyValue" || fields.variadic !== true)) throw new CLIError("Arg schema field 'unique' requires a variadic arg of a list kind", {
240
+ code: "INVALID_SCHEMA",
241
+ details: {
242
+ kind,
243
+ field: "unique"
244
+ },
245
+ suggest: "Add 'variadic: true' on a list kind, or drop 'unique'"
246
+ });
247
+ }
248
+ /**
249
+ * Reject a discriminator outside {@link ARG_KINDS}.
15
250
  *
16
- * Most consumers should prefer the higher-level {@link arg} factory, which
17
- * returns an immutable {@link ArgBuilder} with type inference and fluent
18
- * modifiers. `createArgSchema()` exists for advanced schema composition,
19
- * targeted tests, or custom builders that need the plain runtime descriptor.
251
+ * The types admit only a declared kind, so this catches an untyped JavaScript
252
+ * caller before an unknown discriminator reaches an exhaustive `switch` that
253
+ * has no arm for it.
20
254
  *
21
- * `overrides` are shallow-merged on top of the default shape, so callers are
22
- * responsible for preserving invariants such as variadic ordering and
23
- * compatible `parseFn` / `kind` combinations.
255
+ * @param kind - Declared kind of the definition.
256
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on an unknown kind.
257
+ */
258
+ function assertKnownArgKind(kind) {
259
+ if (ARG_KINDS.includes(kind)) return;
260
+ throw new CLIError(`Unknown arg kind '${String(kind)}'`, {
261
+ code: "INVALID_SCHEMA",
262
+ details: {
263
+ kind,
264
+ allowed: [...ARG_KINDS]
265
+ },
266
+ suggest: `Use one of: ${ARG_KINDS.join(", ")}`
267
+ });
268
+ }
269
+ /**
270
+ * Merge definition fields onto the {@link ArgSchema} defaults.
271
+ *
272
+ * A field set to `undefined` falls back to its default for the fields
273
+ * {@link ArgSchema} declares as non-nullable.
24
274
  *
25
275
  * @param kind - Discriminator for the value type this arg accepts.
26
- * @param overrides - Partial schema fields shallow-merged onto defaults.
276
+ * @param overrides - Definition fields shallow-merged onto the defaults.
27
277
  * @returns A fully populated {@link ArgSchema}.
28
- *
29
- * @example
30
- * ```ts
31
- * const schema = createArgSchema('custom', {
32
- * description: 'Hex color',
33
- * parseFn: (raw) => `#${raw}`,
34
- * });
35
- * ```
36
278
  */
37
- function createArgSchema(kind, overrides) {
279
+ function buildArgSchema(kind, overrides) {
280
+ const schema = assembleArgSchema(kind, overrides);
281
+ assertValidArgDefault(void 0, schema);
282
+ return schema;
283
+ }
284
+ /** Merge the definition fields onto the defaults, without validating the result. */
285
+ function assembleArgSchema(kind, overrides) {
286
+ const { presence, variadic, stdin, unique, duplicateKeys, ...rest } = overrides ?? {};
38
287
  return {
39
288
  kind,
40
- presence: "required",
41
- variadic: false,
42
- stdinMode: false,
289
+ presence: presence ?? "required",
290
+ variadic: variadic ?? false,
291
+ stdin: stdin === void 0 ? void 0 : normalizeStdinBinding(stdin),
43
292
  defaultValue: void 0,
44
293
  description: void 0,
45
294
  envVar: void 0,
295
+ configPath: void 0,
296
+ prompt: void 0,
46
297
  enumValues: void 0,
298
+ elementSchema: void 0,
47
299
  numberConstraints: void 0,
300
+ stringConstraints: void 0,
301
+ pathChecks: void 0,
302
+ valueHint: void 0,
48
303
  parseFn: void 0,
304
+ separator: void 0,
305
+ split: void 0,
306
+ duplicateKeys: duplicateKeys ?? "last",
307
+ unique: unique ?? false,
49
308
  standard: void 0,
309
+ aggregateStandard: void 0,
50
310
  deprecated: void 0,
51
- ...overrides
311
+ ...rest
52
312
  };
53
313
  }
54
314
  /**
315
+ * Reject a declared default the arg could never hold.
316
+ *
317
+ * A default is a typed value, so it is validated rather than decoded: string
318
+ * and number constraints, element and aggregate Standard Schema verdicts
319
+ * available synchronously, and the shape the cardinality requires. Filesystem
320
+ * checks and asynchronous validators stay with the resolution-time pass.
321
+ *
322
+ * @param name - Positional arg name, when one is known.
323
+ * @param schema - The arg schema carrying the default.
324
+ * @throws {CLIError} With code `'INVALID_DEFAULT'` when the default is invalid.
325
+ */
326
+ function assertValidArgDefault(name, schema) {
327
+ if (schema.defaultValue === void 0) return;
328
+ const violation = validateDefault(argValueSchema(schema), argCardinality(schema), argAggregateStandard(schema), schema.defaultValue);
329
+ if (violation === void 0) return;
330
+ throw defaultViolationError(name === void 0 ? `${indefiniteArticle(schema.kind)} ${schema.kind} argument` : `argument <${name}>`, {
331
+ kind: schema.kind,
332
+ ...name === void 0 ? {} : { arg: name }
333
+ }, violation);
334
+ }
335
+ function createArgSchema(kindOrDefinition, overrides) {
336
+ if (typeof kindOrDefinition === "string") {
337
+ assertValidArgDefinition(kindOrDefinition, overrides ?? {});
338
+ return buildArgSchema(kindOrDefinition, normalizeArgDefinitionFields(overrides ?? {}));
339
+ }
340
+ const { kind, ...fields } = kindOrDefinition;
341
+ assertValidArgDefinition(kind, fields);
342
+ return buildArgSchema(kind, normalizeArgDefinitionFields(fields));
343
+ }
344
+ /**
55
345
  * Immutable positional argument schema builder.
56
346
  *
57
347
  * The type parameter `C` is a phantom that tracks the value type, presence,
@@ -109,7 +399,7 @@ var ArgBuilder = class ArgBuilder {
109
399
  /**
110
400
  * Mark the arg as required (this is the default for positional args).
111
401
  * Produces an error if no value resolves from any configured source
112
- * (CLI → stdin → env → default).
402
+ * (CLI → stdin → env → config → prompt → default).
113
403
  *
114
404
  * @example
115
405
  * ```ts
@@ -159,18 +449,23 @@ var ArgBuilder = class ArgBuilder {
159
449
  * Provide a default value. The arg becomes "always present" — handlers
160
450
  * will never see `undefined`.
161
451
  *
162
- * The generic constraint `V extends C['valueType']` ensures the default
163
- * matches the arg's declared type.
452
+ * The generic constraint {@link ArgDefaultValue} ensures the default matches
453
+ * what the arg resolves to: an array for a variadic arg, a record for a
454
+ * `keyValue` one, and a single value otherwise.
164
455
  *
165
- * Resolution order when extra sources are configured: CLI → stdin → env → **default**.
456
+ * Resolution order when extra sources are configured:
457
+ * CLI → stdin → env → config → prompt → **default**.
166
458
  *
167
459
  * @param value - Fallback used when no CLI value or env var resolves.
168
460
  * @returns The builder (for chaining).
461
+ * @throws {CLIError} With code `'INVALID_DEFAULT'` when the value is one the
462
+ * arg could never hold.
169
463
  *
170
464
  * @example
171
465
  * ```ts
172
466
  * arg.string().default('production')
173
467
  * arg.number().default(3000)
468
+ * arg.string().variadic().default(['a', 'b'])
174
469
  *
175
470
  * // In a command — default kicks in when CLI and env are both absent:
176
471
  * command('deploy')
@@ -187,17 +482,21 @@ var ArgBuilder = class ArgBuilder {
187
482
  * ```
188
483
  */
189
484
  default(value) {
190
- return new ArgBuilder({
485
+ const schema = {
191
486
  ...this.schema,
192
487
  presence: "defaulted",
193
488
  defaultValue: value
194
- });
489
+ };
490
+ assertValidArgDefault(void 0, schema);
491
+ return new ArgBuilder(schema);
195
492
  }
196
493
  /**
197
494
  * Mark this arg as variadic — it consumes all remaining positional
198
495
  * arguments. The inferred type becomes `T[]`.
199
496
  *
200
- * A variadic arg must be the last positional in a command.
497
+ * A variadic arg is the last positional a command can declare. Registering
498
+ * another positional after it throws `INVALID_BUILDER_STATE` from `.arg()`
499
+ * and from `createCommandSchema()`.
201
500
  *
202
501
  * @example
203
502
  * ```ts
@@ -218,41 +517,193 @@ var ArgBuilder = class ArgBuilder {
218
517
  * @returns The builder (for chaining).
219
518
  */
220
519
  variadic() {
221
- return new ArgBuilder({
520
+ return nextArg({
222
521
  ...this.schema,
223
522
  variadic: true
224
523
  });
225
524
  }
226
525
  /**
227
- * Allow this arg to resolve from stdin when CLI input is missing.
526
+ * Split each positional token on a separator before element coercion, so
527
+ * `mycli build a,b c` collects `['a', 'b', 'c']` into a variadic arg.
528
+ *
529
+ * The separator is the CLI policy alone. Env values split on `','` and the
530
+ * stdin buffer on line terminators unless `.split()` says otherwise.
531
+ *
532
+ * Available on an arg that aggregates, so call it after `.variadic()` or on
533
+ * `arg.keyValue()`.
534
+ *
535
+ * @param value - Separator string (e.g. `','`).
536
+ * @returns The builder (for chaining).
537
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on an arg carrying a single
538
+ * value.
539
+ */
540
+ separator(value) {
541
+ normalizeSplitPolicy("cli", value);
542
+ return nextArg({
543
+ ...this.schema,
544
+ separator: value
545
+ });
546
+ }
547
+ /**
548
+ * Set how each source decodes into elements.
549
+ *
550
+ * CLI tokens accept `'whole'` and a delimiter; env values also accept
551
+ * `'json'`; the stdin buffer accepts every format, including `'lines'`. The
552
+ * strings `'whole'`, `'lines'`, and `'json'` name their format, and every
553
+ * other string is the delimiter to split on. A source left out keeps what it
554
+ * already had, or its default: whole CLI tokens, comma-delimited env values,
555
+ * line-delimited stdin. For stdin, `'whole'` passes the complete buffer to a
556
+ * string element, including its final line terminator.
557
+ *
558
+ * Available on an arg that aggregates, so call it after `.variadic()` or on
559
+ * `arg.keyValue()`.
560
+ *
561
+ * @param options - Per-source split settings.
562
+ * @returns The builder (for chaining).
563
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a format the source does
564
+ * not accept, an empty delimiter, or an arg carrying a single value.
565
+ *
566
+ * @example
567
+ * ```ts
568
+ * arg.string().variadic().split({ env: { format: 'json' } })
569
+ * // FILES='["a.ts","b.ts"]' → ['a.ts', 'b.ts']
570
+ * ```
571
+ */
572
+ split(options) {
573
+ const normalized = normalizeSplitOptions(options, this.schema.split);
574
+ return nextArg({
575
+ ...this.schema,
576
+ ...normalized.setsSeparator ? { separator: normalized.separator } : {},
577
+ split: normalized.split
578
+ });
579
+ }
580
+ /**
581
+ * Deduplicate the resolved values of a variadic arg, preserving first-seen
582
+ * order. Applied after all sources resolve, using `SameValueZero` semantics.
583
+ *
584
+ * Available on a variadic arg of a list kind, so call it after `.variadic()`.
585
+ *
586
+ * @param value - Whether to deduplicate.
587
+ * @defaultValue `true`
588
+ * @returns The builder (for chaining).
589
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on an arg that resolves to
590
+ * one value or to a record.
591
+ */
592
+ unique(value = true) {
593
+ if (this.schema.kind === "keyValue" || this.schema.variadic !== true) assertValidArgDefinition(this.schema.kind, {
594
+ ...this.schema,
595
+ unique: true
596
+ });
597
+ return nextArg({
598
+ ...this.schema,
599
+ unique: value
600
+ });
601
+ }
602
+ /**
603
+ * Set how a repeated key combines.
604
+ *
605
+ * @param policy - `'last'` (default), `'first'`, or `'error'`.
606
+ * @returns The builder (for chaining).
607
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on an arg that is not
608
+ * `arg.keyValue()`.
609
+ *
610
+ * @example
611
+ * ```ts
612
+ * arg.keyValue().variadic().duplicateKeys('error').env('VARS')
613
+ * // $ VARS='A=1,A=2' mycli run
614
+ * // # → Duplicate key '<redacted>' from env VARS for argument <vars> (CONSTRAINT_VIOLATED)
615
+ * ```
616
+ */
617
+ duplicateKeys(policy) {
618
+ return nextArg({
619
+ ...this.schema,
620
+ duplicateKeys: policy
621
+ });
622
+ }
623
+ /**
624
+ * Validate the resolved value with a Standard Schema v1 validator.
625
+ *
626
+ * On a single-value builder the validator sees each value; on a builder that
627
+ * already aggregates (`.variadic()` or `arg.keyValue()`) it sees the
628
+ * completed array or record, after every element passed its own validator.
629
+ *
630
+ * The builder this is called on is what decides, so where the call sits
631
+ * relative to `.variadic()` chooses between the two.
632
+ *
633
+ * @param schema - A Standard Schema v1 validator.
634
+ * @returns The builder (for chaining).
635
+ *
636
+ * @example
637
+ * ```ts
638
+ * import { z } from 'zod';
639
+ * arg.string().standard(z.string().min(1)).variadic() // each element
640
+ * arg.string().variadic().standard(z.array(z.string())) // the whole array
641
+ * ```
642
+ */
643
+ standard(schema) {
644
+ const aggregate = isCollection(argCardinality(this.schema));
645
+ return nextArg({
646
+ ...this.schema,
647
+ ...aggregate ? { aggregateStandard: schema } : { standard: schema }
648
+ });
649
+ }
650
+ /**
651
+ * Let this arg read its value from piped stdin.
652
+ *
653
+ * An explicit `-` in the arg's slot is CLI-sourced with bytes from stdin and
654
+ * keeps CLI precedence. An absent positional takes the stdin fallback stage,
655
+ * which sits between CLI and env, so an arg set in the environment still
656
+ * reads stdin and stdin wins. The whole buffer becomes the value, byte for
657
+ * byte for a string arg; every other kind drops the single line terminator a
658
+ * pipe appends before decoding, and `{ trim: true }` drops it for a string
659
+ * arg too.
228
660
  *
229
- * Resolution order becomes: CLI value -> stdin -> env -> default.
230
- * Only one arg per command may enable stdin mode.
661
+ * On an arg that aggregates, a `-` among the tail tokens splices what the
662
+ * buffer decodes to into that position, so `mycli build a - b` over
663
+ * `'x\ny\n'` collects `['a', 'x', 'y', 'b']`. Each `-` stands for the whole
664
+ * source, so two of them splice the buffer twice. A `-` typed beside other
665
+ * tokens with nothing piped fails with `MISSING_STDIN`; a tail of nothing but
666
+ * `-` falls through to the later sources.
231
667
  *
668
+ * A stdin-enabled arg cannot receive a literal `-` as its value, since the
669
+ * token names the source.
670
+ *
671
+ * One command may declare a single exclusive stdin consumer; pass
672
+ * `{ consume: 'broadcast' }` on every input that should share the buffer.
673
+ *
674
+ * @param options - When to read stdin, how to share it, and whether to trim.
232
675
  * @returns The builder (for chaining).
233
676
  *
234
677
  * @example
235
678
  * ```ts
236
679
  * arg.string().describe('Input text').stdin()
237
- * // $ echo "hello" | mycli transform → input = 'hello' (from stdin)
680
+ * // $ echo "hello" | mycli transform → input = 'hello\n' (from stdin)
681
+ * // $ mycli transform - → input reads stdin
238
682
  * // $ mycli transform "hello" → input = 'hello' (from CLI)
683
+ *
684
+ * arg.string().stdin({ when: 'dash' })
685
+ * // only an explicit `-` reads stdin
686
+ *
687
+ * arg.path({ mustExist: true }).stdin({ trim: true })
688
+ * // $ echo ./dist | mycli clean → path = './dist', checked on disk
239
689
  * ```
240
690
  */
241
- stdin() {
691
+ stdin(options) {
242
692
  return new ArgBuilder({
243
693
  ...this.schema,
244
- stdinMode: true
694
+ stdin: normalizeStdinBinding(options)
245
695
  });
246
696
  }
247
697
  /**
248
698
  * Bind to an environment variable.
249
699
  *
250
- * When the arg is not provided on the CLI, the resolver checks this
251
- * env var before falling back to the default value. The env string is
252
- * coerced to the arg's declared kind (passthrough for strings, parsed
700
+ * When the arg is not provided on the CLI or by stdin, the resolver checks
701
+ * this env var before config, prompt, and the default value. The env string
702
+ * is coerced to the arg's declared kind (passthrough for strings, parsed
253
703
  * for numbers, run through `parseFn` for custom args).
254
704
  *
255
- * Resolution order when extra sources are configured: **CLI → stdin → env → default**.
705
+ * Resolution order when extra sources are configured:
706
+ * **CLI → stdin → env → config → prompt → default**.
256
707
  *
257
708
  * Help output shows `[env: VAR]` next to the arg description.
258
709
  *
@@ -277,6 +728,59 @@ var ArgBuilder = class ArgBuilder {
277
728
  });
278
729
  }
279
730
  /**
731
+ * Bind to a dotted config path.
732
+ *
733
+ * The config value is read after CLI, stdin, and env, and is coerced to the
734
+ * arg's declared kind the same way a flag's config value is.
735
+ *
736
+ * @param path - Dotted config key (e.g. `'deploy.region'`).
737
+ * @returns The builder (for chaining).
738
+ *
739
+ * @example
740
+ * ```ts
741
+ * arg.string().config('deploy.region').default('us-east-1')
742
+ * // Config file: { "deploy": { "region": "eu-west-1" } }
743
+ * // $ mycli deploy → region = 'eu-west-1'
744
+ * // $ mycli deploy ap-south-1 → CLI positional wins
745
+ * ```
746
+ */
747
+ config(path) {
748
+ return new ArgBuilder({
749
+ ...this.schema,
750
+ configPath: path
751
+ });
752
+ }
753
+ /**
754
+ * Attach interactive prompt configuration.
755
+ *
756
+ * When CLI, stdin, env, and config all produce nothing, the prompt engine
757
+ * uses this config to ask the user. In non-interactive contexts the prompt
758
+ * is skipped and resolution falls through to the default or the missing-arg
759
+ * error.
760
+ *
761
+ * The compatible kinds follow the value and the cardinality: a variadic arg
762
+ * takes the `multiselect` a `flag.array()` takes, and every other arg takes
763
+ * what its kind takes on the flag surface.
764
+ *
765
+ * @param config - {@link PromptConfig} describing the interactive prompt.
766
+ * @returns The builder (for chaining).
767
+ *
768
+ * @example
769
+ * ```ts
770
+ * arg.string().prompt({ kind: 'input', message: 'Target:' })
771
+ * // $ mycli deploy → prompts "Target:"
772
+ * // $ mycli deploy production → skips the prompt
773
+ *
774
+ * arg.string().variadic().prompt({ kind: 'multiselect', message: 'Targets:' })
775
+ * ```
776
+ */
777
+ prompt(config) {
778
+ return new ArgBuilder({
779
+ ...this.schema,
780
+ prompt: config
781
+ });
782
+ }
783
+ /**
280
784
  * Human-readable description shown in help output.
281
785
  *
282
786
  * @param description - Text displayed next to the arg in `--help`.
@@ -338,7 +842,7 @@ var ArgBuilder = class ArgBuilder {
338
842
  * ```
339
843
  */
340
844
  int(value = true) {
341
- return new ArgBuilder({
845
+ return nextArg({
342
846
  ...this.schema,
343
847
  numberConstraints: {
344
848
  ...this.schema.numberConstraints,
@@ -366,7 +870,7 @@ var ArgBuilder = class ArgBuilder {
366
870
  min: value
367
871
  };
368
872
  assertNumberConstraints(numberConstraints);
369
- return new ArgBuilder({
873
+ return nextArg({
370
874
  ...this.schema,
371
875
  numberConstraints
372
876
  });
@@ -389,7 +893,7 @@ var ArgBuilder = class ArgBuilder {
389
893
  max: value
390
894
  };
391
895
  assertNumberConstraints(numberConstraints);
392
- return new ArgBuilder({
896
+ return nextArg({
393
897
  ...this.schema,
394
898
  numberConstraints
395
899
  });
@@ -409,7 +913,7 @@ var ArgBuilder = class ArgBuilder {
409
913
  * ```
410
914
  */
411
915
  finite(allow = true) {
412
- return new ArgBuilder({
916
+ return nextArg({
413
917
  ...this.schema,
414
918
  numberConstraints: {
415
919
  ...this.schema.numberConstraints,
@@ -417,20 +921,140 @@ var ArgBuilder = class ArgBuilder {
417
921
  }
418
922
  });
419
923
  }
924
+ /**
925
+ * Reject empty strings. Composes with other string constraints.
926
+ *
927
+ * @param value - Whether to reject empty strings.
928
+ * @defaultValue `true`
929
+ * @returns The builder (for chaining).
930
+ *
931
+ * @example
932
+ * ```ts
933
+ * arg.string().nonEmpty() // rejects '', accepts 'x'
934
+ * ```
935
+ */
936
+ nonEmpty(value = true) {
937
+ return nextArg({
938
+ ...this.schema,
939
+ stringConstraints: {
940
+ ...this.schema.stringConstraints,
941
+ nonEmpty: value
942
+ }
943
+ });
944
+ }
945
+ /**
946
+ * Set an inclusive minimum length (UTF-16 code units). Composes with other
947
+ * string constraints; a later call overrides an earlier `minLength`.
948
+ *
949
+ * @param value - Inclusive minimum length.
950
+ * @returns The builder (for chaining).
951
+ *
952
+ * @example
953
+ * ```ts
954
+ * arg.string().minLength(3) // rejects 'ab', accepts 'abc'
955
+ * ```
956
+ */
957
+ minLength(value) {
958
+ const stringConstraints = {
959
+ ...this.schema.stringConstraints,
960
+ minLength: value
961
+ };
962
+ assertStringConstraints(stringConstraints);
963
+ return nextArg({
964
+ ...this.schema,
965
+ stringConstraints
966
+ });
967
+ }
968
+ /**
969
+ * Set an inclusive maximum length (UTF-16 code units). Composes with other
970
+ * string constraints; a later call overrides an earlier `maxLength`.
971
+ *
972
+ * @param value - Inclusive maximum length.
973
+ * @returns The builder (for chaining).
974
+ *
975
+ * @example
976
+ * ```ts
977
+ * arg.string().maxLength(8) // rejects 9+ chars
978
+ * ```
979
+ */
980
+ maxLength(value) {
981
+ const stringConstraints = {
982
+ ...this.schema.stringConstraints,
983
+ maxLength: value
984
+ };
985
+ assertStringConstraints(stringConstraints);
986
+ return nextArg({
987
+ ...this.schema,
988
+ stringConstraints
989
+ });
990
+ }
991
+ /**
992
+ * Require the value to match a regular expression. Anchor with `^`/`$`
993
+ * for full-string matching. Composes with other string constraints.
994
+ *
995
+ * @param value - Pattern the value must match.
996
+ * @returns The builder (for chaining).
997
+ *
998
+ * @example
999
+ * ```ts
1000
+ * arg.string().pattern(/^ghp_/) // rejects 'abc', accepts 'ghp_x'
1001
+ * ```
1002
+ */
1003
+ pattern(value) {
1004
+ return nextArg({
1005
+ ...this.schema,
1006
+ stringConstraints: {
1007
+ ...this.schema.stringConstraints,
1008
+ pattern: value
1009
+ }
1010
+ });
1011
+ }
420
1012
  };
421
1013
  /**
1014
+ * Continue a builder chain, rejecting a schema the change just invalidated.
1015
+ *
1016
+ * The `this` constraint on each modifier states to the compiler which kinds
1017
+ * carry the field it sets; this states the same rule to a caller who reaches
1018
+ * the builder from JavaScript, with the error {@link createArgSchema} already
1019
+ * gives, so what a builder produces is always a definition the framework can
1020
+ * read back.
1021
+ *
1022
+ * A constraint added after `.default()` still governs the default, so the
1023
+ * verdict is the same whichever order the chain was written in.
1024
+ *
1025
+ * @param schema - The schema the modifier produced.
1026
+ * @returns A builder over that schema.
1027
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when the field does not belong
1028
+ * on the arg, or `'INVALID_DEFAULT'` when the default no longer holds.
1029
+ * @internal
1030
+ */
1031
+ function nextArg(schema) {
1032
+ assertValidArgDefinition(schema.kind, schema);
1033
+ assertValidArgDefault(void 0, schema);
1034
+ return new ArgBuilder(schema);
1035
+ }
1036
+ /**
422
1037
  * Positional argument schema factory.
423
1038
  *
424
1039
  * Entry point for defining args on a command. Use `arg.<kind>()` to create
425
1040
  * an {@linkcode ArgBuilder}, then chain modifiers and pass the result to
426
1041
  * `command().arg(name, builder)`.
427
1042
  *
428
- * Four kinds are available:
1043
+ * Six base kinds are available:
429
1044
  * - `arg.string()` — raw string (most common)
430
1045
  * - `arg.number()` — parsed to number, errors on NaN
1046
+ * - `arg.boolean()` reads an explicit true/false token
431
1047
  * - `arg.enum(values)` — constrained to listed literals
1048
+ * - `arg.keyValue()` merges `KEY=VALUE` tokens into a record
432
1049
  * - `arg.custom(fn)` — arbitrary parse function, infers return type
433
1050
  *
1051
+ * Five sugar factories build on them, mirroring their flag counterparts:
1052
+ * - `arg.url()` parses to `URL`, with an optional protocol allowlist
1053
+ * - `arg.path()` keeps the string and adds optional filesystem checks
1054
+ * - `arg.date()` parses strict ISO-8601 to `Date`
1055
+ * - `arg.duration()` resolves `'1h30m'` and friends to milliseconds
1056
+ * - `arg.bytes()` resolves `'512mb'` and friends to bytes
1057
+ *
434
1058
  * @example
435
1059
  * ```ts
436
1060
  * import { command, arg } from '@kjanat/dreamcli';
@@ -447,20 +1071,69 @@ var ArgBuilder = class ArgBuilder {
447
1071
  * ```
448
1072
  */
449
1073
  const arg = {
450
- string() {
451
- return new ArgBuilder(createArgSchema("string"));
1074
+ string(constraints) {
1075
+ if (constraints !== void 0) assertStringConstraints(constraints);
1076
+ return new ArgBuilder(createArgSchema("string", valueDefinitionFields(stringValue(constraints))));
452
1077
  },
453
1078
  number(constraints) {
454
1079
  if (constraints !== void 0) assertNumberConstraints(constraints);
455
- return new ArgBuilder(createArgSchema("number", constraints !== void 0 ? { numberConstraints: constraints } : {}));
1080
+ return new ArgBuilder(createArgSchema("number", valueDefinitionFields(numberValue(constraints))));
1081
+ },
1082
+ boolean() {
1083
+ return new ArgBuilder(createArgSchema("boolean", valueDefinitionFields(booleanValue())));
1084
+ },
1085
+ keyValue(element) {
1086
+ if (element !== void 0) assertArgElementBuilder("keyValue", element);
1087
+ return new ArgBuilder(createArgSchema("keyValue", {
1088
+ valueHint: "key=value",
1089
+ ...element !== void 0 ? { elementSchema: element.schema } : {}
1090
+ }));
456
1091
  },
457
1092
  enum(values) {
458
1093
  return new ArgBuilder(createArgSchema("enum", { enumValues: values }));
459
1094
  },
460
1095
  custom(parseFnOrSchema) {
461
- if (isStandardSchemaV1(parseFnOrSchema)) return new ArgBuilder(createArgSchema("custom", { standard: parseFnOrSchema }));
462
- return new ArgBuilder(createArgSchema("custom", { parseFn: parseFnOrSchema }));
1096
+ if (isStandardSchemaV1(parseFnOrSchema)) return new ArgBuilder(createArgSchema("custom", valueDefinitionFields(standardValue(parseFnOrSchema))));
1097
+ return new ArgBuilder(createArgSchema("custom", valueDefinitionFields(stringParsedValue(parseFnOrSchema))));
1098
+ },
1099
+ url(options) {
1100
+ return new ArgBuilder(createArgSchema("custom", valueDefinitionFields(urlValue(options))));
1101
+ },
1102
+ path(options) {
1103
+ return new ArgBuilder(createArgSchema("string", valueDefinitionFields(pathValue(options))));
1104
+ },
1105
+ date(options) {
1106
+ return new ArgBuilder(createArgSchema("custom", valueDefinitionFields(dateValue(options))));
1107
+ },
1108
+ duration() {
1109
+ return new ArgBuilder(createArgSchema("custom", valueDefinitionFields(durationValue())));
1110
+ },
1111
+ bytes() {
1112
+ return new ArgBuilder(createArgSchema("custom", valueDefinitionFields(bytesValue())));
463
1113
  }
464
1114
  };
1115
+ /**
1116
+ * Reject a collection factory handed something other than an arg builder.
1117
+ *
1118
+ * The types demand one, so this catches an untyped JavaScript caller before the
1119
+ * factory reads `.schema` off a value that has none.
1120
+ *
1121
+ * @param factory - Name of the factory being called.
1122
+ * @param element - What the caller passed as the element.
1123
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when it is not an
1124
+ * {@link ArgBuilder}.
1125
+ */
1126
+ function assertArgElementBuilder(factory, element) {
1127
+ if (element instanceof ArgBuilder) return;
1128
+ throw new CLIError(`arg.${factory}() requires an element builder`, {
1129
+ code: "INVALID_SCHEMA",
1130
+ details: {
1131
+ factory,
1132
+ field: "element",
1133
+ received: typeof element
1134
+ },
1135
+ suggest: `Pass an element builder, as in arg.${factory}(arg.string())`
1136
+ });
1137
+ }
465
1138
  //#endregion
466
- export { ArgBuilder, arg, createArgSchema };
1139
+ export { ARG_KINDS, ArgBuilder, arg, createArgSchema };