@kjanat/dreamcli 3.0.0 → 4.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (147) hide show
  1. package/CHANGELOG.md +967 -1
  2. package/README.md +9 -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 +10 -9
  134. package/skills/cli-creation/SKILL.md +196 -0
  135. package/skills/cli-creation/agents/openai.yaml +4 -0
  136. package/skills/cli-creation/assets/templates/multi-command.bun-test.ts.tpl +20 -0
  137. package/skills/cli-creation/assets/templates/multi-command.test.ts.tpl +20 -0
  138. package/skills/cli-creation/assets/templates/multi-command.ts.tpl +89 -0
  139. package/skills/cli-creation/assets/templates/single-command.bun-test.ts.tpl +29 -0
  140. package/skills/cli-creation/assets/templates/single-command.test.ts.tpl +29 -0
  141. package/skills/cli-creation/assets/templates/single-command.ts.tpl +47 -0
  142. package/skills/cli-creation/references/consumer-workflow.md +65 -0
  143. package/skills/cli-creation/references/pattern-cookbook.md +451 -0
  144. package/skills/cli-creation/references/runtime-notes.md +29 -0
  145. package/skills/cli-creation/scripts/scaffold_cli.py +360 -0
  146. package/dist/core/resolve/property.d.mts +0 -51
  147. package/dist/core/resolve/property.mjs +0 -53
@@ -1,7 +1,10 @@
1
+ import { CLIError } from "../errors/index.mjs";
1
2
  import { assertNumberConstraints } from "./number-constraints.mjs";
2
- import { isStandardSchemaV1 } from "./standard.mjs";
3
3
  import { assertStringConstraints } from "./string-constraints.mjs";
4
- import { parseBytesValue, parseDateValue, parseDurationValue, parseUrlValue } from "./value-parsers.mjs";
4
+ import { bytesValue, customValue, dateValue, durationValue, flagAggregateStandard, flagValueSchema, numberValue, pathValue, standardValue, stringValue, urlValue, valueDefinitionFields } from "./value.mjs";
5
+ import { DUPLICATE_KEYS, SPLIT_FORMATS, defaultViolationError, flagCardinality, indefiniteArticle, isCollection, normalizeSplitOptions, normalizeSplitPolicy, validateDefault } from "./cardinality.mjs";
6
+ import { isStandardSchemaV1 } from "./standard.mjs";
7
+ import { normalizeStdinBinding } from "./stdin.mjs";
5
8
  //#region src/core/schema/flag.ts
6
9
  /**
7
10
  * Flag schema builder with full type inference.
@@ -13,6 +16,17 @@ import { parseBytesValue, parseDateValue, parseDurationValue, parseUrlValue } fr
13
16
  *
14
17
  * @module dreamcli/core/schema/flag
15
18
  */
19
+ /** All flag kind discriminators as a runtime array. */
20
+ const FLAG_KINDS = [
21
+ "string",
22
+ "number",
23
+ "boolean",
24
+ "enum",
25
+ "array",
26
+ "custom",
27
+ "count",
28
+ "keyValue"
29
+ ];
16
30
  /**
17
31
  * Normalise an alias input into a full {@link FlagAlias} object.
18
32
  *
@@ -69,37 +83,303 @@ function getFlagNegatedName(name, schema) {
69
83
  if (schema.negation === void 0) return void 0;
70
84
  return schema.negation.alias ?? `no-${name}`;
71
85
  }
86
+ /** Every runtime key carried by a normalized {@link FlagSchema}. */
87
+ const NORMALIZED_FLAG_SCHEMA_KEYS = [
88
+ "kind",
89
+ "presence",
90
+ "defaultValue",
91
+ "aliases",
92
+ "stdin",
93
+ "envVar",
94
+ "configPath",
95
+ "description",
96
+ "enumValues",
97
+ "numberConstraints",
98
+ "stringConstraints",
99
+ "elementSchema",
100
+ "separator",
101
+ "split",
102
+ "duplicateKeys",
103
+ "unique",
104
+ "pathChecks",
105
+ "valueHint",
106
+ "prompt",
107
+ "parseFn",
108
+ "standard",
109
+ "aggregateStandard",
110
+ "deprecated",
111
+ "propagate",
112
+ "negation",
113
+ "duplicates"
114
+ ];
72
115
  /**
73
- * Create a raw {@link FlagSchema} object with sensible defaults.
116
+ * Whether an element input already carries every normalized schema key.
74
117
  *
75
- * Most consumers should prefer the higher-level {@link flag} factory,
76
- * which returns an immutable {@link FlagBuilder} with type inference and
77
- * safe modifier chaining. `createSchema()` is the low-level escape hatch
78
- * for advanced schema composition, tests, or custom factories that need to
79
- * work directly with the runtime descriptor.
118
+ * @param element - Element definition or schema.
119
+ * @returns `true` when the value is already a built {@link FlagSchema}.
120
+ */
121
+ function isNormalizedFlagSchema(element) {
122
+ return NORMALIZED_FLAG_SCHEMA_KEYS.every((key) => key in element);
123
+ }
124
+ /** Reject flag-level fields on a collection factory's element builder. */
125
+ function assertEligibleFlagElementBuilder(schema) {
126
+ if (COLLECTION_FLAG_KINDS.includes(schema.kind) || schema.kind === "count") throw new CLIError(`Flag element schema kind '${schema.kind}' is not supported`, {
127
+ code: "INVALID_SCHEMA",
128
+ details: {
129
+ kind: schema.kind,
130
+ field: "kind"
131
+ },
132
+ suggest: "Use a scalar value kind for the collection element"
133
+ });
134
+ const defaults = [
135
+ ["presence", schema.kind === "boolean" ? "defaulted" : "optional"],
136
+ ["defaultValue", schema.kind === "boolean" ? false : void 0],
137
+ ["stdin", void 0],
138
+ ["envVar", void 0],
139
+ ["configPath", void 0],
140
+ ["description", void 0],
141
+ ["elementSchema", void 0],
142
+ ["separator", void 0],
143
+ ["split", void 0],
144
+ ["duplicateKeys", "last"],
145
+ ["unique", false],
146
+ ["prompt", void 0],
147
+ ["aggregateStandard", void 0],
148
+ ["deprecated", void 0],
149
+ ["propagate", false],
150
+ ["negation", void 0],
151
+ ["duplicates", "last"]
152
+ ];
153
+ for (const [field, allowed] of defaults) {
154
+ if (schema[field] === allowed) continue;
155
+ throw new CLIError(`Flag element schema field '${String(field)}' is not supported`, {
156
+ code: "INVALID_SCHEMA",
157
+ details: {
158
+ kind: schema.kind,
159
+ field
160
+ },
161
+ suggest: `Drop '${String(field)}' from the collection element`
162
+ });
163
+ }
164
+ if (schema.aliases.length !== 0) throw new CLIError("Flag element schema field 'aliases' is not supported", {
165
+ code: "INVALID_SCHEMA",
166
+ details: {
167
+ kind: schema.kind,
168
+ field: "aliases"
169
+ },
170
+ suggest: "Drop 'aliases' from the collection element"
171
+ });
172
+ }
173
+ /**
174
+ * Normalise an array flag's element input into a built {@link FlagSchema}.
80
175
  *
81
- * `overrides` are shallow-merged on top of the default shape, so callers are
82
- * responsible for keeping the resulting schema internally consistent.
176
+ * An already-built schema is returned unchanged, so repeated normalization
177
+ * preserves element identity.
178
+ *
179
+ * @param element - Element definition or schema.
180
+ * @returns The element as a fully populated {@link FlagSchema}.
181
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when a field belongs to a
182
+ * different {@link FlagKind}.
183
+ */
184
+ function normalizeFlagElementSchema(element) {
185
+ if (isNormalizedFlagSchema(element)) {
186
+ assertValidFlagDefinition(element.kind, element);
187
+ return element;
188
+ }
189
+ const { kind, ...fields } = element;
190
+ assertValidFlagDefinition(kind, fields);
191
+ return buildFlagSchema(kind, normalizeFlagDefinitionFields(fields));
192
+ }
193
+ /**
194
+ * Resolve a definition's nested `elementSchema` into a built {@link FlagSchema}.
195
+ *
196
+ * @param fields - Definition fields excluding the kind discriminator.
197
+ * @returns The same fields with `elementSchema` normalized.
198
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when a nested element field
199
+ * belongs to a different {@link FlagKind}.
200
+ */
201
+ function normalizeFlagDefinitionFields(fields) {
202
+ const { elementSchema, ...rest } = fields;
203
+ if (elementSchema === void 0) return rest;
204
+ return {
205
+ ...rest,
206
+ elementSchema: normalizeFlagElementSchema(elementSchema)
207
+ };
208
+ }
209
+ /** Flag kinds that can read from stdin: every scalar, plus the collections. */
210
+ const STDIN_CAPABLE_FLAG_KINDS = [
211
+ "string",
212
+ "number",
213
+ "boolean",
214
+ "enum",
215
+ "custom",
216
+ "array",
217
+ "keyValue"
218
+ ];
219
+ /** The collection kinds, which carry an element schema and split policies. */
220
+ const COLLECTION_FLAG_KINDS = ["array", "keyValue"];
221
+ /**
222
+ * Fields that are only meaningful on some {@link FlagKind}s, mapped to them.
223
+ */
224
+ const KIND_SPECIFIC_FLAG_FIELDS = [
225
+ ["enumValues", ["enum"]],
226
+ ["numberConstraints", ["number"]],
227
+ ["stringConstraints", ["string"]],
228
+ ["pathChecks", ["string"]],
229
+ ["elementSchema", COLLECTION_FLAG_KINDS],
230
+ ["separator", COLLECTION_FLAG_KINDS],
231
+ ["split", COLLECTION_FLAG_KINDS],
232
+ ["aggregateStandard", COLLECTION_FLAG_KINDS],
233
+ ["parseFn", ["custom"]],
234
+ ["negation", ["boolean"]]
235
+ ];
236
+ /**
237
+ * Reject a definition that carries a field belonging to another {@link FlagKind}.
238
+ *
239
+ * A field set to `undefined` counts as absent, `unique` counts as absent when
240
+ * `false`, and `duplicateKeys` counts as absent when `'last'`, so re-feeding a
241
+ * built {@link FlagSchema} back through {@link createFlagSchema} stays valid: a
242
+ * built schema always carries those defaults, whatever its kind. The compile-time
243
+ * `this` parameter on `.unique()` and `.duplicateKeys()` is what rejects
244
+ * `.duplicateKeys('last')` on a scalar, since the runtime cannot tell that call
245
+ * apart from a round-tripped default.
246
+ *
247
+ * @param kind - Declared kind of the definition.
248
+ * @param fields - Definition fields excluding the kind discriminator.
249
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on an unknown kind or a kind
250
+ * mismatch.
251
+ * @internal
252
+ */
253
+ function assertValidFlagDefinition(kind, fields) {
254
+ assertKnownFlagKind(kind);
255
+ for (const [field, requiredKinds] of KIND_SPECIFIC_FLAG_FIELDS) {
256
+ if (requiredKinds.includes(kind)) continue;
257
+ if (fields[field] === void 0) continue;
258
+ throw invalidFlagFieldError(kind, field, requiredKinds);
259
+ }
260
+ if (kind !== "array" && fields.unique === true) throw invalidFlagFieldError(kind, "unique", ["array"]);
261
+ if (kind !== "keyValue" && fields.duplicateKeys !== void 0 && fields.duplicateKeys !== "last") throw invalidFlagFieldError(kind, "duplicateKeys", ["keyValue"]);
262
+ if (fields.duplicateKeys !== void 0 && !DUPLICATE_KEYS.includes(fields.duplicateKeys)) throw new CLIError(`Unknown duplicate-key policy '${String(fields.duplicateKeys)}'`, {
263
+ code: "INVALID_SCHEMA",
264
+ details: {
265
+ duplicateKeys: fields.duplicateKeys,
266
+ allowed: [...DUPLICATE_KEYS]
267
+ },
268
+ suggest: `Use one of: ${DUPLICATE_KEYS.join(", ")}`
269
+ });
270
+ if (kind === "enum" && fields.enumValues === void 0) throw new CLIError("Flag schema kind 'enum' requires field 'enumValues'", {
271
+ code: "INVALID_SCHEMA",
272
+ details: {
273
+ kind,
274
+ field: "enumValues"
275
+ },
276
+ suggest: "Pass the allowed values in 'enumValues'"
277
+ });
278
+ if ((kind === "array" || kind === "count" || kind === "keyValue") && fields.duplicates !== void 0 && fields.duplicates !== "last") throw new CLIError(`Flag schema field 'duplicates' is not supported on kind '${kind}'`, {
279
+ code: "INVALID_SCHEMA",
280
+ details: {
281
+ kind,
282
+ field: "duplicates"
283
+ },
284
+ suggest: `Drop 'duplicates'; kind '${kind}' accumulates every occurrence`
285
+ });
286
+ if ((kind === "count" || kind === "keyValue") && fields.prompt !== void 0) throw new CLIError(`Flag schema field 'prompt' is not available on kind '${kind}'`, {
287
+ code: "INVALID_SCHEMA",
288
+ details: {
289
+ kind,
290
+ field: "prompt"
291
+ },
292
+ suggest: `Drop 'prompt' from the ${kind} flag`
293
+ });
294
+ if (fields.stdin !== void 0) assertStdinCapableKind(kind);
295
+ }
296
+ /**
297
+ * Reject a discriminator outside {@link FLAG_KINDS}.
298
+ *
299
+ * The types admit only a declared kind, so this catches an untyped JavaScript
300
+ * caller before an unknown discriminator reaches an exhaustive `switch` that
301
+ * has no arm for it.
302
+ *
303
+ * @param kind - Declared kind of the definition.
304
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on an unknown kind.
305
+ * @internal
306
+ */
307
+ function assertKnownFlagKind(kind) {
308
+ if (FLAG_KINDS.includes(kind)) return;
309
+ throw new CLIError(`Unknown flag kind '${String(kind)}'`, {
310
+ code: "INVALID_SCHEMA",
311
+ details: {
312
+ kind,
313
+ allowed: [...FLAG_KINDS]
314
+ },
315
+ suggest: `Use one of: ${FLAG_KINDS.join(", ")}`
316
+ });
317
+ }
318
+ /**
319
+ * Reject a stdin binding on a flag kind that has no value to read.
320
+ *
321
+ * A `count` flag carries occurrences rather than a value, so both construction
322
+ * paths refuse the binding with the same error.
323
+ *
324
+ * @param kind - Declared kind of the flag.
325
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a kind that cannot read stdin.
326
+ */
327
+ function assertStdinCapableKind(kind) {
328
+ if (STDIN_CAPABLE_FLAG_KINDS.some((allowed) => allowed === kind)) return;
329
+ throw new CLIError(`Flag schema field 'stdin' is not available on kind '${kind}'`, {
330
+ code: "INVALID_SCHEMA",
331
+ details: {
332
+ kind,
333
+ field: "stdin",
334
+ allowedKinds: [...STDIN_CAPABLE_FLAG_KINDS]
335
+ },
336
+ suggest: `Drop 'stdin' or declare the flag as one of: ${STDIN_CAPABLE_FLAG_KINDS.join(", ")}`
337
+ });
338
+ }
339
+ /**
340
+ * Build the `'INVALID_SCHEMA'` error for a field used on the wrong kind.
341
+ *
342
+ * @param kind - Declared kind of the definition.
343
+ * @param field - Offending field name.
344
+ * @param requiredKind - Kind the field belongs to.
345
+ * @returns The error to throw.
346
+ */
347
+ function invalidFlagFieldError(kind, field, requiredKinds) {
348
+ const listed = requiredKinds.map((required) => `'${required}'`).join(" or ");
349
+ return new CLIError(`Flag schema field '${field}' requires kind ${listed}, received kind '${kind}'`, {
350
+ code: "INVALID_SCHEMA",
351
+ details: {
352
+ kind,
353
+ field,
354
+ requiredKinds: [...requiredKinds]
355
+ },
356
+ suggest: `Drop '${field}' or declare the flag as kind ${listed}`
357
+ });
358
+ }
359
+ /**
360
+ * Merge already-normalized schema fields onto the {@link FlagSchema} defaults.
361
+ *
362
+ * A field set to `undefined` falls back to its default for the fields
363
+ * {@link FlagSchema} declares as non-nullable.
83
364
  *
84
365
  * @param kind - Discriminator for the value type this flag accepts.
85
- * @param overrides - Partial {@link FlagSchema} fields merged onto defaults.
366
+ * @param overrides - Schema fields shallow-merged onto the defaults.
86
367
  * @returns A fully populated {@link FlagSchema}.
87
- *
88
- * @example
89
- * ```ts
90
- * const schema = createSchema('enum', {
91
- * enumValues: ['us', 'eu', 'ap'],
92
- * description: 'Deployment region',
93
- * });
94
- * ```
95
368
  */
96
- function createSchema(kind, overrides) {
369
+ function buildFlagSchema(kind, overrides) {
370
+ const schema = assembleFlagSchema(kind, overrides);
371
+ assertValidFlagDefault(void 0, schema);
372
+ return schema;
373
+ }
374
+ /** Merge the normalized fields onto the defaults, without validating the result. */
375
+ function assembleFlagSchema(kind, overrides) {
97
376
  const aliases = overrides?.aliases !== void 0 ? normalizeFlagAliases(overrides.aliases) : [];
98
- const { aliases: _ignoredAliases, ...rest } = overrides ?? {};
377
+ const { aliases: _ignoredAliases, presence, stdin, unique, propagate, duplicates, duplicateKeys, ...rest } = overrides ?? {};
99
378
  return {
100
379
  kind,
101
- presence: "optional",
380
+ presence: presence ?? "optional",
102
381
  defaultValue: void 0,
382
+ stdin: stdin === void 0 ? void 0 : normalizeStdinBinding(stdin),
103
383
  envVar: void 0,
104
384
  configPath: void 0,
105
385
  description: void 0,
@@ -108,21 +388,55 @@ function createSchema(kind, overrides) {
108
388
  stringConstraints: void 0,
109
389
  elementSchema: void 0,
110
390
  separator: void 0,
111
- unique: false,
391
+ split: void 0,
392
+ duplicateKeys: duplicateKeys ?? "last",
393
+ unique: unique ?? false,
112
394
  pathChecks: void 0,
113
395
  valueHint: void 0,
114
396
  prompt: void 0,
115
397
  parseFn: void 0,
116
398
  standard: void 0,
399
+ aggregateStandard: void 0,
117
400
  deprecated: void 0,
118
- propagate: false,
401
+ propagate: propagate ?? false,
119
402
  negation: void 0,
120
- duplicates: "last",
403
+ duplicates: duplicates ?? "last",
121
404
  ...rest,
122
405
  aliases
123
406
  };
124
407
  }
125
408
  /**
409
+ * Reject a declared default the flag could never hold.
410
+ *
411
+ * A default is a typed value, so it is validated rather than decoded: string
412
+ * and number constraints, element and aggregate Standard Schema verdicts
413
+ * available synchronously, and the shape the cardinality requires. Filesystem
414
+ * checks and asynchronous validators stay with the resolution-time pass.
415
+ *
416
+ * @param name - Canonical flag name, when one is known.
417
+ * @param schema - The flag schema carrying the default.
418
+ * @throws {CLIError} With code `'INVALID_DEFAULT'` when the default is invalid.
419
+ */
420
+ function assertValidFlagDefault(name, schema) {
421
+ if (schema.defaultValue === void 0) return;
422
+ const violation = validateDefault(flagValueSchema(schema), flagCardinality(schema), flagAggregateStandard(schema), schema.defaultValue);
423
+ if (violation === void 0) return;
424
+ throw defaultViolationError(name === void 0 ? `${indefiniteArticle(schema.kind)} ${schema.kind} flag` : `flag --${name}`, {
425
+ kind: schema.kind,
426
+ ...name === void 0 ? {} : { flag: name }
427
+ }, violation);
428
+ }
429
+ function createFlagSchema(kindOrDefinition, overrides) {
430
+ if (typeof kindOrDefinition === "string") {
431
+ const fields = overrides ?? {};
432
+ assertValidFlagDefinition(kindOrDefinition, fields);
433
+ return buildFlagSchema(kindOrDefinition, normalizeFlagDefinitionFields(fields));
434
+ }
435
+ const { kind, ...fields } = kindOrDefinition;
436
+ assertValidFlagDefinition(kind, fields);
437
+ return buildFlagSchema(kind, normalizeFlagDefinitionFields(fields));
438
+ }
439
+ /**
126
440
  * Immutable flag schema builder.
127
441
  *
128
442
  * The type parameter `C` is a phantom that tracks the value type and presence
@@ -168,11 +482,13 @@ var FlagBuilder = class FlagBuilder {
168
482
  * ```
169
483
  */
170
484
  default(value) {
171
- return new FlagBuilder({
485
+ const schema = {
172
486
  ...this.schema,
173
487
  presence: "defaulted",
174
488
  defaultValue: value
175
- });
489
+ };
490
+ assertValidFlagDefault(void 0, schema);
491
+ return new FlagBuilder(schema);
176
492
  }
177
493
  /**
178
494
  * Mark the flag as required. If not resolved from any source the framework
@@ -225,6 +541,9 @@ var FlagBuilder = class FlagBuilder {
225
541
  /**
226
542
  * Bind to an environment variable (resolved in v0.2+).
227
543
  *
544
+ * The env value is read after CLI and stdin, and before config, the prompt,
545
+ * and the default: CLI → stdin → **env** → config → prompt → default.
546
+ *
228
547
  * @param varName - Environment variable name (e.g. `'PORT'`).
229
548
  * @returns The builder (for chaining).
230
549
  *
@@ -243,8 +562,63 @@ var FlagBuilder = class FlagBuilder {
243
562
  });
244
563
  }
245
564
  /**
565
+ * Let this flag read its value from piped stdin.
566
+ *
567
+ * An explicit `--<name> -` is CLI-sourced with bytes from stdin and keeps
568
+ * CLI precedence. An absent flag takes the stdin fallback stage, which sits
569
+ * between CLI and env, so a flag set in the environment still reads stdin
570
+ * and stdin wins. The whole buffer becomes the value, byte for byte for a
571
+ * string flag; every other kind drops the single line terminator a pipe
572
+ * appends before decoding, and `{ trim: true }` drops it for a string flag
573
+ * too.
574
+ *
575
+ * A collection reads the buffer as elements instead: `--tag -` splices what
576
+ * stdin decodes into the position the `-` occupies, so
577
+ * `--tag before --tag - --tag after` over `'a\nb\n'` resolves to
578
+ * `['before', 'a', 'b', 'after']`. `.split({ stdin })` sets the decoding.
579
+ * Each `-` stands for the whole source, so `--tag - --tag -` splices the
580
+ * buffer twice. A `-` typed beside other occurrences with nothing piped fails
581
+ * with `MISSING_STDIN`; occurrences of nothing but `-` fall through to the
582
+ * later sources.
583
+ *
584
+ * A stdin-enabled flag cannot receive a literal `-` as its value, since the
585
+ * token names the source.
586
+ *
587
+ * Available on every flag kind except `count`. One command may declare a
588
+ * single exclusive stdin consumer; pass `{ consume: 'broadcast' }` on every
589
+ * input that should share the buffer.
590
+ *
591
+ * @param options - When to read stdin, how to share it, and whether to trim.
592
+ * @returns The builder (for chaining).
593
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a `count` flag.
594
+ *
595
+ * @example
596
+ * ```ts
597
+ * flag.string().stdin().describe('Message body')
598
+ * // $ echo hi | mycli send → body = 'hi\n'
599
+ * // $ mycli send --body - → body reads stdin
600
+ * // $ mycli send --body hello → body = 'hello'
601
+ *
602
+ * flag.string().stdin({ when: 'dash' })
603
+ * // only `--body -` reads stdin
604
+ *
605
+ * flag.path({ mustExist: true }).stdin({ trim: true })
606
+ * // $ echo ./dist | mycli clean → path = './dist', checked on disk
607
+ * ```
608
+ */
609
+ stdin(options) {
610
+ assertStdinCapableKind(this.schema.kind);
611
+ return new FlagBuilder({
612
+ ...this.schema,
613
+ stdin: normalizeStdinBinding(options)
614
+ });
615
+ }
616
+ /**
246
617
  * Bind to a dotted config path (resolved in v0.2+).
247
618
  *
619
+ * The config value is read after CLI, stdin, and env, and before the prompt
620
+ * and the default: CLI → stdin → env → **config** → prompt → default.
621
+ *
248
622
  * @param path - Dotted config key (e.g. `'deploy.region'`).
249
623
  * @returns The builder (for chaining).
250
624
  *
@@ -279,7 +653,7 @@ var FlagBuilder = class FlagBuilder {
279
653
  /**
280
654
  * Attach interactive prompt configuration for v0.3+ resolution.
281
655
  *
282
- * When a flag value is not resolved from CLI, env, or config, the
656
+ * When a flag value is not resolved from CLI, stdin, env, or config, the
283
657
  * prompt engine uses this config to interactively ask the user.
284
658
  * In non-interactive contexts (CI, piped stdin) prompts are skipped
285
659
  * and resolution falls through to default or required validation.
@@ -367,7 +741,7 @@ var FlagBuilder = class FlagBuilder {
367
741
  * ```
368
742
  */
369
743
  int(value = true) {
370
- return new FlagBuilder({
744
+ return nextFlag({
371
745
  ...this.schema,
372
746
  numberConstraints: {
373
747
  ...this.schema.numberConstraints,
@@ -395,7 +769,7 @@ var FlagBuilder = class FlagBuilder {
395
769
  min: value
396
770
  };
397
771
  assertNumberConstraints(numberConstraints);
398
- return new FlagBuilder({
772
+ return nextFlag({
399
773
  ...this.schema,
400
774
  numberConstraints
401
775
  });
@@ -418,7 +792,7 @@ var FlagBuilder = class FlagBuilder {
418
792
  max: value
419
793
  };
420
794
  assertNumberConstraints(numberConstraints);
421
- return new FlagBuilder({
795
+ return nextFlag({
422
796
  ...this.schema,
423
797
  numberConstraints
424
798
  });
@@ -438,7 +812,7 @@ var FlagBuilder = class FlagBuilder {
438
812
  * ```
439
813
  */
440
814
  finite(allow = true) {
441
- return new FlagBuilder({
815
+ return nextFlag({
442
816
  ...this.schema,
443
817
  numberConstraints: {
444
818
  ...this.schema.numberConstraints,
@@ -459,7 +833,7 @@ var FlagBuilder = class FlagBuilder {
459
833
  * ```
460
834
  */
461
835
  nonEmpty(value = true) {
462
- return new FlagBuilder({
836
+ return nextFlag({
463
837
  ...this.schema,
464
838
  stringConstraints: {
465
839
  ...this.schema.stringConstraints,
@@ -485,7 +859,7 @@ var FlagBuilder = class FlagBuilder {
485
859
  minLength: value
486
860
  };
487
861
  assertStringConstraints(stringConstraints);
488
- return new FlagBuilder({
862
+ return nextFlag({
489
863
  ...this.schema,
490
864
  stringConstraints
491
865
  });
@@ -508,7 +882,7 @@ var FlagBuilder = class FlagBuilder {
508
882
  maxLength: value
509
883
  };
510
884
  assertStringConstraints(stringConstraints);
511
- return new FlagBuilder({
885
+ return nextFlag({
512
886
  ...this.schema,
513
887
  stringConstraints
514
888
  });
@@ -526,7 +900,7 @@ var FlagBuilder = class FlagBuilder {
526
900
  * ```
527
901
  */
528
902
  pattern(value) {
529
- return new FlagBuilder({
903
+ return nextFlag({
530
904
  ...this.schema,
531
905
  stringConstraints: {
532
906
  ...this.schema.stringConstraints,
@@ -539,11 +913,13 @@ var FlagBuilder = class FlagBuilder {
539
913
  * `--tag a,b --tag c` resolves to `['a', 'b', 'c']`. Elements are coerced
540
914
  * (and rejected) individually with the element schema's own error format.
541
915
  *
542
- * Env and config string values are split on the same separator (their
543
- * default split is `','` even without this modifier).
916
+ * The separator is the CLI policy alone. Env values split on `','` and the
917
+ * stdin buffer on line terminators unless `.split()` says otherwise.
544
918
  *
545
919
  * @param value - Separator string (e.g. `','`).
546
920
  * @returns The builder (for chaining).
921
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a flag that carries a
922
+ * single value.
547
923
  *
548
924
  * @example
549
925
  * ```ts
@@ -552,19 +928,103 @@ var FlagBuilder = class FlagBuilder {
552
928
  * ```
553
929
  */
554
930
  separator(value) {
555
- if (value.length === 0) throw new RangeError("array separator must not be empty");
556
- return new FlagBuilder({
931
+ normalizeSplitPolicy("cli", value);
932
+ return nextFlag({
557
933
  ...this.schema,
558
934
  separator: value
559
935
  });
560
936
  }
561
937
  /**
938
+ * Set how each source decodes into elements.
939
+ *
940
+ * CLI tokens accept `'whole'` and a delimiter; env values also accept
941
+ * `'json'`; the stdin buffer accepts every format, including `'lines'`. The
942
+ * strings `'whole'`, `'lines'`, and `'json'` name their format, and every
943
+ * other string is the delimiter to split on. A source left out keeps what it
944
+ * already had, or its default: whole CLI tokens (or the `.separator()`
945
+ * delimiter), comma-delimited env values, line-delimited stdin. A config
946
+ * value is a native array or object, and a config string decodes under the
947
+ * env policy. For stdin, `'whole'` passes the complete buffer to a string
948
+ * element, including its final line terminator.
949
+ *
950
+ * @param options - Per-source split settings.
951
+ * @returns The builder (for chaining).
952
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a format the source does
953
+ * not accept, an empty delimiter, or a flag that carries a single value.
954
+ *
955
+ * @example
956
+ * ```ts
957
+ * flag.array(flag.string()).split({ cli: ',', env: { format: 'json' } }).env('TAGS')
958
+ * // --tag a,b → ['a', 'b']
959
+ * // TAGS='["a","b"]' → ['a', 'b']
960
+ * ```
961
+ */
962
+ split(options) {
963
+ const normalized = normalizeSplitOptions(options, this.schema.split);
964
+ return nextFlag({
965
+ ...this.schema,
966
+ ...normalized.setsSeparator ? { separator: normalized.separator } : {},
967
+ split: normalized.split
968
+ });
969
+ }
970
+ /**
971
+ * Set how a repeated key combines.
972
+ *
973
+ * Applies to repeated CLI occurrences, delimited env pairs, and spliced stdin
974
+ * reads in the same occurrence order. JSON decoding does not preserve
975
+ * repeated object member names, so it cannot reliably expose them here.
976
+ *
977
+ * @param policy - `'last'` (default), `'first'`, or `'error'`.
978
+ * @returns The builder (for chaining).
979
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a flag that is not
980
+ * `keyValue`.
981
+ *
982
+ * @example
983
+ * ```ts
984
+ * flag.keyValue().duplicateKeys('error').env('VARS')
985
+ * // $ VARS='A=1,A=2' mycli run
986
+ * // # → Duplicate key '<redacted>' from env VARS for flag --env (CONSTRAINT_VIOLATED)
987
+ * ```
988
+ */
989
+ duplicateKeys(policy) {
990
+ return nextFlag({
991
+ ...this.schema,
992
+ duplicateKeys: policy
993
+ });
994
+ }
995
+ /**
996
+ * Validate the resolved value with a Standard Schema v1 validator.
997
+ *
998
+ * On a scalar builder the validator sees each value; on a collection builder
999
+ * it sees the completed array or record, after every element passed its own
1000
+ * validator. `flag.array(flag.string().standard(s))` validates elements,
1001
+ * `flag.array(flag.string()).standard(s)` validates the array.
1002
+ *
1003
+ * @param schema - A Standard Schema v1 validator.
1004
+ * @returns The builder (for chaining).
1005
+ *
1006
+ * @example
1007
+ * ```ts
1008
+ * import { z } from 'zod';
1009
+ * flag.array(flag.string()).standard(z.array(z.string()).min(1))
1010
+ * ```
1011
+ */
1012
+ standard(schema) {
1013
+ const aggregate = isCollection(flagCardinality(this.schema));
1014
+ return nextFlag({
1015
+ ...this.schema,
1016
+ ...aggregate ? { aggregateStandard: schema } : { standard: schema }
1017
+ });
1018
+ }
1019
+ /**
562
1020
  * Deduplicate the resolved array, preserving first-seen order. Applied
563
1021
  * after all sources resolve, using `SameValueZero` semantics (like `Set`).
564
1022
  *
565
1023
  * @param value - Whether to deduplicate.
566
1024
  * @defaultValue `true`
567
1025
  * @returns The builder (for chaining).
1026
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a flag that is not
1027
+ * `array`.
568
1028
  *
569
1029
  * @example
570
1030
  * ```ts
@@ -573,7 +1033,7 @@ var FlagBuilder = class FlagBuilder {
573
1033
  * ```
574
1034
  */
575
1035
  unique(value = true) {
576
- return new FlagBuilder({
1036
+ return nextFlag({
577
1037
  ...this.schema,
578
1038
  unique: value
579
1039
  });
@@ -590,6 +1050,8 @@ var FlagBuilder = class FlagBuilder {
590
1050
  * @param options - Optional custom spelling (`alias`, without `--`) and
591
1051
  * `hidden` to keep the negated spelling parseable but unadvertised.
592
1052
  * @returns The builder (for chaining).
1053
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a flag that is not
1054
+ * `boolean`.
593
1055
  *
594
1056
  * @example
595
1057
  * ```ts
@@ -599,7 +1061,7 @@ var FlagBuilder = class FlagBuilder {
599
1061
  * ```
600
1062
  */
601
1063
  negatable(options) {
602
- return new FlagBuilder({
1064
+ return nextFlag({
603
1065
  ...this.schema,
604
1066
  negation: {
605
1067
  alias: options?.alias,
@@ -626,84 +1088,120 @@ var FlagBuilder = class FlagBuilder {
626
1088
  * ```
627
1089
  */
628
1090
  duplicates(policy) {
629
- return new FlagBuilder({
1091
+ return nextFlag({
630
1092
  ...this.schema,
631
1093
  duplicates: policy
632
1094
  });
633
1095
  }
634
1096
  };
635
1097
  /**
1098
+ * Continue a builder chain, rejecting a schema the change just invalidated.
1099
+ *
1100
+ * The `this` constraint on each modifier states to the compiler which kinds
1101
+ * carry the field it sets; this states the same rule to a caller who reaches
1102
+ * the builder from JavaScript, with the error {@link createFlagSchema} already
1103
+ * gives, so what a builder produces is always a definition the framework can
1104
+ * read back.
1105
+ *
1106
+ * A constraint added after `.default()` still governs the default, so the
1107
+ * verdict is the same whichever order the chain was written in.
1108
+ *
1109
+ * @param schema - The schema the modifier produced.
1110
+ * @returns A builder over that schema.
1111
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when the field does not belong
1112
+ * on the flag, or `'INVALID_DEFAULT'` when the default no longer holds.
1113
+ * @internal
1114
+ */
1115
+ function nextFlag(schema) {
1116
+ assertValidFlagDefinition(schema.kind, schema);
1117
+ assertValidFlagDefault(void 0, schema);
1118
+ return new FlagBuilder(schema);
1119
+ }
1120
+ /**
636
1121
  * Flag schema factory. Call `flag.<kind>()` to create an immutable
637
1122
  * {@link FlagBuilder} with full type inference and safe modifier chaining.
638
1123
  */
639
1124
  const flag = {
640
1125
  string(constraints) {
641
1126
  if (constraints !== void 0) assertStringConstraints(constraints);
642
- return new FlagBuilder(createSchema("string", constraints !== void 0 ? { stringConstraints: constraints } : {}));
1127
+ return new FlagBuilder(createFlagSchema("string", valueDefinitionFields(stringValue(constraints))));
643
1128
  },
644
1129
  number(constraints) {
645
1130
  if (constraints !== void 0) assertNumberConstraints(constraints);
646
- return new FlagBuilder(createSchema("number", constraints !== void 0 ? { numberConstraints: constraints } : {}));
1131
+ return new FlagBuilder(createFlagSchema("number", valueDefinitionFields(numberValue(constraints))));
647
1132
  },
648
1133
  boolean() {
649
- return new FlagBuilder(createSchema("boolean", {
1134
+ return new FlagBuilder(createFlagSchema("boolean", {
650
1135
  presence: "defaulted",
651
1136
  defaultValue: false
652
1137
  }));
653
1138
  },
654
1139
  enum(values) {
655
- return new FlagBuilder(createSchema("enum", { enumValues: values }));
1140
+ return new FlagBuilder(createFlagSchema("enum", { enumValues: values }));
656
1141
  },
657
1142
  array(element) {
658
- return new FlagBuilder(createSchema("array", { elementSchema: element.schema }));
1143
+ assertFlagElementBuilder("array", element);
1144
+ return new FlagBuilder(createFlagSchema("array", { elementSchema: element.schema }));
659
1145
  },
660
1146
  custom(parseFnOrSchema) {
661
- if (isStandardSchemaV1(parseFnOrSchema)) return new FlagBuilder(createSchema("custom", { standard: parseFnOrSchema }));
662
- return new FlagBuilder(createSchema("custom", { parseFn: parseFnOrSchema }));
1147
+ if (isStandardSchemaV1(parseFnOrSchema)) return new FlagBuilder(createFlagSchema("custom", valueDefinitionFields(standardValue(parseFnOrSchema))));
1148
+ return new FlagBuilder(createFlagSchema("custom", valueDefinitionFields(customValue(parseFnOrSchema))));
663
1149
  },
664
1150
  url(options) {
665
- return new FlagBuilder(createSchema("custom", {
666
- parseFn: (raw) => parseUrlValue(raw, options),
667
- valueHint: "url"
668
- }));
1151
+ return new FlagBuilder(createFlagSchema("custom", valueDefinitionFields(urlValue(options))));
669
1152
  },
670
1153
  path(options) {
671
- return new FlagBuilder(createSchema("string", {
672
- pathChecks: options?.mustExist === true || options?.type !== void 0 ? {
673
- mustExist: options.mustExist ?? true,
674
- type: options.type,
675
- create: options.type === "directory" && options.create === true
676
- } : void 0,
677
- valueHint: "path"
678
- }));
1154
+ return new FlagBuilder(createFlagSchema("string", valueDefinitionFields(pathValue(options))));
679
1155
  },
680
1156
  date(options) {
681
- return new FlagBuilder(createSchema("custom", {
682
- parseFn: (raw) => parseDateValue(raw, options),
683
- valueHint: "date"
684
- }));
1157
+ return new FlagBuilder(createFlagSchema("custom", valueDefinitionFields(dateValue(options))));
685
1158
  },
686
1159
  duration() {
687
- return new FlagBuilder(createSchema("custom", {
688
- parseFn: parseDurationValue,
689
- valueHint: "duration"
690
- }));
1160
+ return new FlagBuilder(createFlagSchema("custom", valueDefinitionFields(durationValue())));
691
1161
  },
692
1162
  bytes() {
693
- return new FlagBuilder(createSchema("custom", {
694
- parseFn: parseBytesValue,
695
- valueHint: "size"
696
- }));
1163
+ return new FlagBuilder(createFlagSchema("custom", valueDefinitionFields(bytesValue())));
697
1164
  },
698
1165
  count() {
699
- return new FlagBuilder(createSchema("count", {
1166
+ return new FlagBuilder(createFlagSchema("count", {
700
1167
  presence: "defaulted",
701
1168
  defaultValue: 0
702
1169
  }));
703
1170
  },
704
- keyValue() {
705
- return new FlagBuilder(createSchema("keyValue", { valueHint: "key=value" }));
1171
+ keyValue(element) {
1172
+ if (element !== void 0) assertFlagElementBuilder("keyValue", element);
1173
+ return new FlagBuilder(createFlagSchema("keyValue", {
1174
+ valueHint: "key=value",
1175
+ ...element !== void 0 ? { elementSchema: element.schema } : {}
1176
+ }));
706
1177
  }
707
1178
  };
1179
+ /**
1180
+ * Reject a collection factory handed something other than a flag builder.
1181
+ *
1182
+ * The types demand one, so this catches an untyped JavaScript caller before the
1183
+ * factory reads `.schema` off a value that has none.
1184
+ *
1185
+ * @param factory - Name of the factory being called.
1186
+ * @param element - What the caller passed as the element.
1187
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when it is not a
1188
+ * {@link FlagBuilder}.
1189
+ * @internal
1190
+ */
1191
+ function assertFlagElementBuilder(factory, element) {
1192
+ if (element instanceof FlagBuilder) {
1193
+ assertEligibleFlagElementBuilder(element.schema);
1194
+ return;
1195
+ }
1196
+ throw new CLIError(`flag.${factory}() requires an element builder`, {
1197
+ code: "INVALID_SCHEMA",
1198
+ details: {
1199
+ factory,
1200
+ field: "element",
1201
+ received: typeof element
1202
+ },
1203
+ suggest: `Pass an element builder, as in flag.${factory}(flag.string())`
1204
+ });
1205
+ }
708
1206
  //#endregion
709
- export { FlagBuilder, createSchema, flag, getFlagAliasNames, getFlagNegatedName, normalizeFlagAlias, normalizeFlagAliases };
1207
+ export { DUPLICATE_KEYS, FLAG_KINDS, FlagBuilder, SPLIT_FORMATS, createFlagSchema, flag, getFlagAliasNames, getFlagNegatedName, normalizeFlagAlias, normalizeFlagAliases };