@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,8 +1,11 @@
1
+ import { schemaBrand } from "./brand.mjs";
1
2
  import { NumberConstraints } from "./number-constraints.mjs";
2
- import { InferStandardOutput, StandardSchemaV1 } from "./standard.mjs";
3
3
  import { ConfirmPromptConfig, InputPromptConfig, MultiselectPromptConfig, PROMPT_KINDS, PromptConfig, PromptConfigBase, PromptKind, PromptResult, SelectChoice, SelectPromptConfig } from "./prompt.mjs";
4
+ import { InferStandardOutput, StandardSchemaV1 } from "./standard.mjs";
5
+ import { STDIN_CONSUMES, STDIN_WHENS, StdinBinding, StdinConsume, StdinOptions, StdinWhen } from "./stdin.mjs";
4
6
  import { StringConstraintViolation, StringConstraints } from "./string-constraints.mjs";
5
- import { DateFlagOptions, UrlFlagOptions } from "./value-parsers.mjs";
7
+ import { DateFlagOptions, PathChecks, PathFlagOptions, UrlFlagOptions } from "./value-parsers.mjs";
8
+ import { DUPLICATE_KEYS, DuplicateKeys, SPLIT_FORMATS, SourceSplitBinding, SplitBinding, SplitFormat, SplitOptions, SplitPolicy, SplitSetting } from "./cardinality.mjs";
6
9
  //#region src/core/schema/flag.d.ts
7
10
  /** All flag presence states as a runtime array. */
8
11
  declare const FLAG_PRESENCES: readonly ["optional", "required", "defaulted"];
@@ -22,7 +25,7 @@ type FlagPresence = (typeof FLAG_PRESENCES)[number];
22
25
  * Most optional flags resolve to `undefined`; array flags instead resolve to
23
26
  * an empty array `[]`, and key-value flags to an empty object `{}`.
24
27
  */
25
- type OptionalFallback = 'undefined' | 'empty-array' | 'empty-object';
28
+ type OptionalFallback = "undefined" | "empty-array" | "empty-object";
26
29
  /**
27
30
  * Compile-time state carried through the builder chain.
28
31
  *
@@ -54,10 +57,10 @@ interface FlagConfig {
54
57
  * Most consumers rely on inference and never reference this directly.
55
58
  */
56
59
  type WithPresence<C extends FlagConfig, P extends FlagPresence> = {
57
- readonly valueType: C['valueType'];
60
+ readonly valueType: C["valueType"];
58
61
  readonly presence: P;
59
- readonly optionalFallback: C['optionalFallback'];
60
- readonly flagKind: C['flagKind'];
62
+ readonly optionalFallback: C["optionalFallback"];
63
+ readonly flagKind: C["flagKind"];
61
64
  readonly elementEligible: false;
62
65
  };
63
66
  /**
@@ -65,10 +68,10 @@ type WithPresence<C extends FlagConfig, P extends FlagPresence> = {
65
68
  * element (returned by flag-level modifiers whose settings elements ignore).
66
69
  */
67
70
  type WithoutElementEligibility<C extends FlagConfig> = {
68
- readonly valueType: C['valueType'];
69
- readonly presence: C['presence'];
70
- readonly optionalFallback: C['optionalFallback'];
71
- readonly flagKind: C['flagKind'];
71
+ readonly valueType: C["valueType"];
72
+ readonly presence: C["presence"];
73
+ readonly optionalFallback: C["optionalFallback"];
74
+ readonly flagKind: C["flagKind"];
72
75
  readonly elementEligible: false;
73
76
  };
74
77
  /**
@@ -82,7 +85,23 @@ type WithoutElementEligibility<C extends FlagConfig> = {
82
85
  * - `'required'` → `T`
83
86
  * - `'defaulted'` → `T`
84
87
  */
85
- type ResolvedValue<C extends FlagConfig> = C['presence'] extends 'optional' ? C['optionalFallback'] extends 'undefined' ? C['valueType'] | undefined : C['valueType'] : C['valueType'];
88
+ type ResolvedValue<C extends FlagConfig> = C["presence"] extends "optional" ? C["optionalFallback"] extends "undefined" ? C["valueType"] | undefined : C["valueType"] : C["valueType"];
89
+ /**
90
+ * The element config a collection factory assumes when given no element
91
+ * builder: an unconstrained string.
92
+ */
93
+ type StringElementConfig = {
94
+ /** Element value type. */
95
+ readonly valueType: string;
96
+ /** Elements carry no presence of their own. */
97
+ readonly presence: "optional";
98
+ /** Elements carry no fallback of their own. */
99
+ readonly optionalFallback: "undefined";
100
+ /** Element kind discriminator. */
101
+ readonly flagKind: "string";
102
+ /** Elements are element-eligible by construction. */
103
+ readonly elementEligible: true;
104
+ };
86
105
  /** Extract the resolved value type from a {@linkcode FlagBuilder}. */
87
106
  type InferFlag<B> = B extends FlagBuilder<infer C extends FlagConfig> ? ResolvedValue<C> : never;
88
107
  /** Extract resolved value types from a record of builders. */
@@ -111,7 +130,7 @@ type PromptConfigByFlagKind = {
111
130
  readonly keyValue: never;
112
131
  };
113
132
  /** Prompt configuration compatible with the kind carried by a {@link FlagConfig}. */
114
- type AllowedPromptConfig<C extends FlagConfig> = PromptConfigByFlagKind[C['flagKind']];
133
+ type AllowedPromptConfig<C extends FlagConfig> = PromptConfigByFlagKind[C["flagKind"]];
115
134
  /** All flag kind discriminators as a runtime array. */
116
135
  declare const FLAG_KINDS: readonly ["string", "number", "boolean", "enum", "array", "custom", "count", "keyValue"];
117
136
  /** Discriminator for the kind of value a flag accepts. */
@@ -123,63 +142,6 @@ type FlagKind = (typeof FLAG_KINDS)[number];
123
142
  * value from config files. Narrow inside the function as needed.
124
143
  */
125
144
  type FlagParseFn<T> = (raw: unknown) => T;
126
- /** Options accepted by `flag.path()` for any-kind or file paths. */
127
- interface FilePathFlagOptions {
128
- /**
129
- * Reject the value if nothing exists at the path.
130
- * @defaultValue `false` (`true` when `type` is set)
131
- */
132
- readonly mustExist?: boolean;
133
- /**
134
- * Require the path to be a file or a directory. Implies existence
135
- * unless `mustExist` is explicitly `false`, in which case a missing
136
- * path passes and only an existing path is type-checked.
137
- * @defaultValue `undefined` (any kind)
138
- */
139
- readonly type?: 'file';
140
- /** Directory creation is only available with `type: 'directory'`. */
141
- readonly create?: never;
142
- }
143
- /** Options accepted by `flag.path()` for directory paths. */
144
- interface DirectoryPathFlagOptions {
145
- /**
146
- * Reject the value if nothing exists at the path.
147
- * @defaultValue `false` (`true` when `type` is set)
148
- */
149
- readonly mustExist?: boolean;
150
- /**
151
- * Require the path to be a directory. Implies existence unless
152
- * `mustExist` is explicitly `false`, in which case a missing path
153
- * passes and only an existing path is type-checked.
154
- */
155
- readonly type: 'directory';
156
- /**
157
- * Create the directory (recursively) when nothing exists at the path.
158
- * An existing non-directory path still fails the type check.
159
- * @defaultValue `false`
160
- */
161
- readonly create?: boolean;
162
- }
163
- /** Options accepted by `flag.path()`. */
164
- type PathFlagOptions = FilePathFlagOptions | DirectoryPathFlagOptions;
165
- /**
166
- * Filesystem expectations attached by `flag.path()`.
167
- *
168
- * Checked after resolution (not during parse) via the runtime adapter, so
169
- * `src/core` stays free of platform I/O and all sources (CLI, env, config)
170
- * are validated identically.
171
- */
172
- interface PathChecks {
173
- /** Reject the value if nothing exists at the path. */
174
- readonly mustExist: boolean;
175
- /**
176
- * Require the existing path to be a file or a directory. Implies
177
- * existence when set, unless `mustExist` is `false`.
178
- */
179
- readonly type: 'file' | 'directory' | undefined;
180
- /** Create the directory (recursively) when nothing exists at the path. */
181
- readonly create: boolean;
182
- }
183
145
  /** Runtime descriptor for a flag alias. */
184
146
  interface FlagAlias {
185
147
  /** Alias name without `-` / `--` prefix. */
@@ -218,21 +180,28 @@ interface FlagNegation {
218
180
  *
219
181
  * @defaultValue `'last'`
220
182
  */
221
- type DuplicatePolicy = 'last' | 'first' | 'error';
183
+ type DuplicatePolicy = "last" | "first" | "error";
222
184
  /**
223
185
  * The runtime descriptor stored inside every {@linkcode FlagBuilder}. Consumers (parser,
224
186
  * help generator, resolution chain) read this to understand the flag's shape
225
187
  * without touching generics.
226
188
  */
227
- interface FlagSchema {
189
+ interface FlagSchema<K extends FlagKind = FlagKind> {
190
+ /** Type-only seal produced by {@link createFlagSchema}. */
191
+ readonly [schemaBrand]: "flag";
228
192
  /** What kind of value this flag accepts. */
229
- readonly kind: FlagKind;
193
+ readonly kind: K;
230
194
  /** Current presence state. */
231
195
  readonly presence: FlagPresence;
232
196
  /** Runtime default value (if any). */
233
197
  readonly defaultValue: unknown;
234
198
  /** Short/long aliases (e.g. `[{ name: 'f', hidden: false }]` for `--force`). */
235
199
  readonly aliases: readonly FlagAlias[];
200
+ /**
201
+ * Stdin binding set by `.stdin()` (`undefined` when the flag never reads
202
+ * stdin). See {@link StdinBinding}.
203
+ */
204
+ readonly stdin: StdinBinding | undefined;
236
205
  /** Environment variable name for v0.2+ resolution. */
237
206
  readonly envVar: string | undefined;
238
207
  /** Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`). */
@@ -255,16 +224,29 @@ interface FlagSchema {
255
224
  * nonEmpty → minLength → maxLength → pattern.
256
225
  */
257
226
  readonly stringConstraints: StringConstraints | undefined;
258
- /** Element schema when `kind === 'array'`. */
227
+ /** Element schema when `kind === 'array'` or `kind === 'keyValue'`. */
259
228
  readonly elementSchema: FlagSchema | undefined;
260
229
  /**
261
- * Value separator when `kind === 'array'` (`undefined` otherwise).
230
+ * CLI value separator for a collection kind (`undefined` otherwise).
262
231
  *
263
232
  * When set, each CLI occurrence is split on this separator before element
264
- * coercion, so `--tag a,b --tag c` yields `['a', 'b', 'c']`. Env and
265
- * config string values use this separator too (default `','`).
233
+ * coercion, so `--tag a,b --tag c` yields `['a', 'b', 'c']`. Other sources
234
+ * decode through {@link FlagSchema.split}.
266
235
  */
267
236
  readonly separator: string | undefined;
237
+ /**
238
+ * Env and stdin split policies for a collection kind (`undefined` otherwise).
239
+ *
240
+ * A source the binding leaves out takes its default: comma-delimited for env,
241
+ * line-delimited for stdin.
242
+ */
243
+ readonly split: SourceSplitBinding | undefined;
244
+ /**
245
+ * How a repeated key combines when `kind === 'keyValue'`.
246
+ *
247
+ * @defaultValue `'last'`
248
+ */
249
+ readonly duplicateKeys: DuplicateKeys;
268
250
  /**
269
251
  * Deduplicate resolved array values when `kind === 'array'`.
270
252
  *
@@ -291,14 +273,22 @@ interface FlagSchema {
291
273
  /** Custom parse function (only when `kind === 'custom'`). */
292
274
  readonly parseFn: FlagParseFn<unknown> | undefined;
293
275
  /**
294
- * Standard Schema v1 validator applied to the resolved value.
276
+ * Standard Schema v1 validator applied to each resolved value.
295
277
  *
296
278
  * When set, the value from any source (CLI, env, config, prompt, default)
297
279
  * is validated after resolution via `~standard.validate`. Sync and async
298
280
  * validators are both awaited; issues surface as a `CONSTRAINT_VIOLATED`
299
- * {@link ValidationError}. Only meaningful when `kind === 'custom'`.
281
+ * {@link ValidationError}. On a collection this validates every element,
282
+ * whether it rides here or on {@link FlagSchema.elementSchema}.
300
283
  */
301
284
  readonly standard: StandardSchemaV1 | undefined;
285
+ /**
286
+ * Standard Schema v1 validator applied to the completed collection.
287
+ *
288
+ * Set by `.standard()` on a collection builder, so the array or record the
289
+ * aggregation produced is validated as a whole after every element passed.
290
+ */
291
+ readonly aggregateStandard: StandardSchemaV1 | undefined;
302
292
  /**
303
293
  * Deprecation marker.
304
294
  *
@@ -332,15 +322,212 @@ interface FlagSchema {
332
322
  */
333
323
  readonly duplicates: DuplicatePolicy;
334
324
  }
335
- /**
336
- * Low-level overrides accepted by {@link createSchema}.
337
- *
338
- * `aliases` accepts both legacy string input and structured {@link FlagAlias}
339
- * objects so tests and internal fixtures can be migrated incrementally.
340
- */
341
- type FlagSchemaOverrides = Omit<Partial<FlagSchema>, 'aliases'> & {
342
- readonly aliases?: readonly (string | FlagAlias)[];
343
- };
325
+ /** Definition fields accepted by every flag kind. */
326
+ interface FlagDefinitionBase {
327
+ /**
328
+ * Presence state.
329
+ * @defaultValue `'optional'`
330
+ */
331
+ readonly presence?: FlagPresence | undefined;
332
+ /**
333
+ * Runtime default value.
334
+ * @defaultValue `undefined`
335
+ */
336
+ readonly defaultValue?: unknown;
337
+ /**
338
+ * Short/long aliases as bare names or {@link FlagAlias} records.
339
+ * @defaultValue `[]`
340
+ */
341
+ readonly aliases?: readonly (string | FlagAlias)[] | undefined;
342
+ /**
343
+ * Stdin binding. See {@link StdinOptions}.
344
+ * @defaultValue `undefined`
345
+ */
346
+ readonly stdin?: StdinOptions | undefined;
347
+ /**
348
+ * Environment variable name for env resolution.
349
+ * @defaultValue `undefined`
350
+ */
351
+ readonly envVar?: string | undefined;
352
+ /**
353
+ * Dotted config path for config resolution (e.g. `'deploy.region'`).
354
+ * @defaultValue `undefined`
355
+ */
356
+ readonly configPath?: string | undefined;
357
+ /**
358
+ * Human-readable description for help text.
359
+ * @defaultValue `undefined`
360
+ */
361
+ readonly description?: string | undefined;
362
+ /**
363
+ * Help placeholder label (`'url'` renders as `<url>`).
364
+ * @defaultValue `undefined`
365
+ */
366
+ readonly valueHint?: string | undefined;
367
+ /**
368
+ * Interactive prompt configuration.
369
+ * @defaultValue `undefined`
370
+ */
371
+ readonly prompt?: PromptConfig | undefined;
372
+ /**
373
+ * Standard Schema v1 validator applied to each resolved value.
374
+ * @defaultValue `undefined`
375
+ */
376
+ readonly standard?: StandardSchemaV1 | undefined;
377
+ /**
378
+ * Standard Schema v1 validator applied to a completed collection.
379
+ * @defaultValue `undefined`
380
+ */
381
+ readonly aggregateStandard?: StandardSchemaV1 | undefined;
382
+ /**
383
+ * Deprecation marker. `true` deprecates without a message, a string carries
384
+ * the migration guidance.
385
+ * @defaultValue `undefined`
386
+ */
387
+ readonly deprecated?: string | true | undefined;
388
+ /**
389
+ * Whether the flag propagates to descendant commands.
390
+ * @defaultValue `false`
391
+ */
392
+ readonly propagate?: boolean | undefined;
393
+ /**
394
+ * How repeated CLI occurrences combine. See {@link DuplicatePolicy}.
395
+ * @defaultValue `'last'`
396
+ */
397
+ readonly duplicates?: DuplicatePolicy | undefined;
398
+ }
399
+ /** Definition of a `string` flag. */
400
+ interface StringFlagDefinition extends FlagDefinitionBase {
401
+ /** Kind discriminator. */
402
+ readonly kind: "string";
403
+ /**
404
+ * String constraints enforced at the parse and resolution boundaries.
405
+ * @defaultValue `undefined`
406
+ */
407
+ readonly stringConstraints?: StringConstraints | undefined;
408
+ /**
409
+ * Filesystem checks applied after resolution.
410
+ * @defaultValue `undefined`
411
+ */
412
+ readonly pathChecks?: PathChecks | undefined;
413
+ }
414
+ /** Definition of a `number` flag. */
415
+ interface NumberFlagDefinition extends FlagDefinitionBase {
416
+ /** Kind discriminator. */
417
+ readonly kind: "number";
418
+ /**
419
+ * Numeric constraints enforced at the parse and resolution boundaries.
420
+ * @defaultValue `undefined`
421
+ */
422
+ readonly numberConstraints?: NumberConstraints | undefined;
423
+ }
424
+ /** Definition of a `boolean` flag. */
425
+ interface BooleanFlagDefinition extends FlagDefinitionBase {
426
+ /** Kind discriminator. */
427
+ readonly kind: "boolean";
428
+ /**
429
+ * Negated-spelling settings. See {@link FlagNegation}.
430
+ * @defaultValue `undefined`
431
+ */
432
+ readonly negation?: FlagNegation | undefined;
433
+ }
434
+ /** Definition of an `enum` flag. */
435
+ interface EnumFlagDefinition extends FlagDefinitionBase {
436
+ /** Kind discriminator. */
437
+ readonly kind: "enum";
438
+ /** Allowed literal values. */
439
+ readonly enumValues: readonly string[];
440
+ }
441
+ /** Definition of an `array` flag. */
442
+ interface ArrayFlagDefinition extends FlagDefinitionBase {
443
+ /** Kind discriminator. */
444
+ readonly kind: "array";
445
+ /**
446
+ * Element definition or an already-built element schema.
447
+ * @defaultValue `undefined`
448
+ */
449
+ readonly elementSchema?: FlagDefinition | FlagSchema | undefined;
450
+ /**
451
+ * Value separator each CLI occurrence is split on.
452
+ * @defaultValue `undefined`
453
+ */
454
+ readonly separator?: string | undefined;
455
+ /**
456
+ * Env and stdin split policies.
457
+ * @defaultValue `undefined`
458
+ */
459
+ readonly split?: SourceSplitBinding | undefined;
460
+ /**
461
+ * Deduplicate the resolved array, preserving first-seen order.
462
+ * @defaultValue `false`
463
+ */
464
+ readonly unique?: boolean | undefined;
465
+ }
466
+ /** Definition of a `custom` flag. */
467
+ interface CustomFlagDefinition extends FlagDefinitionBase {
468
+ /** Kind discriminator. */
469
+ readonly kind: "custom";
470
+ /**
471
+ * Parse function applied to the raw value.
472
+ * @defaultValue `undefined`
473
+ */
474
+ readonly parseFn?: FlagParseFn<unknown> | undefined;
475
+ }
476
+ /** Definition of a `count` flag. */
477
+ interface CountFlagDefinition extends FlagDefinitionBase {
478
+ /** Kind discriminator. */
479
+ readonly kind: "count";
480
+ }
481
+ /** Definition of a `keyValue` flag. */
482
+ interface KeyValueFlagDefinition extends FlagDefinitionBase {
483
+ /** Kind discriminator. */
484
+ readonly kind: "keyValue";
485
+ /**
486
+ * Element definition or an already-built element schema for each entry value.
487
+ * @defaultValue `undefined`
488
+ */
489
+ readonly elementSchema?: FlagDefinition | FlagSchema | undefined;
490
+ /**
491
+ * Pair separator each CLI occurrence is split on.
492
+ * @defaultValue `undefined`
493
+ */
494
+ readonly separator?: string | undefined;
495
+ /**
496
+ * Env and stdin split policies.
497
+ * @defaultValue `undefined`
498
+ */
499
+ readonly split?: SourceSplitBinding | undefined;
500
+ /**
501
+ * How a repeated key combines. See {@link DuplicateKeys}.
502
+ * @defaultValue `'last'`
503
+ */
504
+ readonly duplicateKeys?: DuplicateKeys | undefined;
505
+ }
506
+ /** Maps each {@link FlagKind} to its definition shape. */
507
+ interface FlagDefinitionByKind {
508
+ /** Definition shape for `string` flags. */
509
+ readonly string: StringFlagDefinition;
510
+ /** Definition shape for `number` flags. */
511
+ readonly number: NumberFlagDefinition;
512
+ /** Definition shape for `boolean` flags. */
513
+ readonly boolean: BooleanFlagDefinition;
514
+ /** Definition shape for `enum` flags. */
515
+ readonly enum: EnumFlagDefinition;
516
+ /** Definition shape for `array` flags. */
517
+ readonly array: ArrayFlagDefinition;
518
+ /** Definition shape for `custom` flags. */
519
+ readonly custom: CustomFlagDefinition;
520
+ /** Definition shape for `count` flags. */
521
+ readonly count: CountFlagDefinition;
522
+ /** Definition shape for `keyValue` flags. */
523
+ readonly keyValue: KeyValueFlagDefinition;
524
+ }
525
+ /** Definition of a flag of kind `K`, including the kind discriminator. */
526
+ type FlagDefinition<K extends FlagKind = FlagKind> = FlagDefinitionByKind[K];
527
+ /** Definition of a flag of kind `K` with the kind discriminator removed. */
528
+ type FlagDefinitionOverrides<K extends FlagKind = FlagKind> = Omit<FlagDefinitionByKind[K], "kind">;
529
+ /** Positional factory arguments, requiring fields that the selected kind requires. */
530
+ type FlagDefinitionArguments<K extends FlagKind> = K extends "enum" ? [overrides: FlagDefinitionOverrides<K>] : [overrides?: FlagDefinitionOverrides<K>];
344
531
  /**
345
532
  * Normalise an alias input into a full {@link FlagAlias} object.
346
533
  *
@@ -364,7 +551,7 @@ declare function normalizeFlagAliases(aliases: readonly (string | FlagAlias)[]):
364
551
  */
365
552
  declare function getFlagAliasNames(schema: FlagSchema, options?: {
366
553
  readonly includeHidden?: boolean;
367
- readonly kind?: 'all' | 'short' | 'long';
554
+ readonly kind?: "all" | "short" | "long";
368
555
  }): readonly string[];
369
556
  /**
370
557
  * Effective negated spelling for a flag, or `undefined` when not negatable.
@@ -378,31 +565,57 @@ declare function getFlagAliasNames(schema: FlagSchema, options?: {
378
565
  * @returns The negated spelling without the `--` prefix.
379
566
  */
380
567
  declare function getFlagNegatedName(name: string, schema: FlagSchema): string | undefined;
568
+ /** Flag kinds that can read from stdin: every scalar, plus the collections. */
569
+ declare const STDIN_CAPABLE_FLAG_KINDS: readonly ["string", "number", "boolean", "enum", "custom", "array", "keyValue"];
570
+ type StdinCapableFlagKind = (typeof STDIN_CAPABLE_FLAG_KINDS)[number];
381
571
  /**
382
572
  * Create a raw {@link FlagSchema} object with sensible defaults.
383
573
  *
384
- * Most consumers should prefer the higher-level {@link flag} factory,
385
- * which returns an immutable {@link FlagBuilder} with type inference and
386
- * safe modifier chaining. `createSchema()` is the low-level escape hatch
387
- * for advanced schema composition, tests, or custom factories that need to
388
- * work directly with the runtime descriptor.
574
+ * Most consumers should prefer the higher-level {@link flag} factory, which
575
+ * returns an immutable {@link FlagBuilder} with type inference and safe
576
+ * modifier chaining. `createFlagSchema()` is the low-level escape hatch for
577
+ * advanced schema composition, tests, or custom factories that need the plain
578
+ * runtime descriptor.
389
579
  *
390
- * `overrides` are shallow-merged on top of the default shape, so callers are
580
+ * Fields are shallow-merged on top of the default shape, so callers are
391
581
  * responsible for keeping the resulting schema internally consistent.
392
582
  *
393
583
  * @param kind - Discriminator for the value type this flag accepts.
394
- * @param overrides - Partial {@link FlagSchema} fields merged onto defaults.
584
+ * @param overrides - Definition fields for `kind`, shallow-merged onto defaults.
395
585
  * @returns A fully populated {@link FlagSchema}.
586
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when a field belongs to a
587
+ * different {@link FlagKind}.
396
588
  *
397
589
  * @example
398
590
  * ```ts
399
- * const schema = createSchema('enum', {
591
+ * const schema = createFlagSchema('enum', {
400
592
  * enumValues: ['us', 'eu', 'ap'],
401
593
  * description: 'Deployment region',
402
594
  * });
403
595
  * ```
404
596
  */
405
- declare function createSchema(kind: FlagKind, overrides?: FlagSchemaOverrides): FlagSchema;
597
+ declare function createFlagSchema<K extends FlagKind>(kind: K, ...overrides: FlagDefinitionArguments<K>): FlagSchema<K>;
598
+ /**
599
+ * Create a raw {@link FlagSchema} object from a single definition object.
600
+ *
601
+ * An already-built {@link FlagSchema} is accepted and re-normalized into a
602
+ * deep-equal schema.
603
+ *
604
+ * @param definition - Kind discriminator plus the fields valid for that kind.
605
+ * @returns A fully populated {@link FlagSchema}.
606
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when a field belongs to a
607
+ * different {@link FlagKind}.
608
+ *
609
+ * @example
610
+ * ```ts
611
+ * const schema = createFlagSchema({
612
+ * kind: 'array',
613
+ * elementSchema: { kind: 'string' },
614
+ * separator: ',',
615
+ * });
616
+ * ```
617
+ */
618
+ declare function createFlagSchema<K extends FlagKind>(definition: FlagDefinition<K> | FlagSchema<K>): FlagSchema<K>;
406
619
  /**
407
620
  * Immutable flag schema builder.
408
621
  *
@@ -420,13 +633,6 @@ declare function createSchema(kind: FlagKind, overrides?: FlagSchemaOverrides):
420
633
  * ```
421
634
  */
422
635
  declare class FlagBuilder<C extends FlagConfig> {
423
- /** @internal Runtime schema descriptor. */
424
- readonly schema: FlagSchema;
425
- /**
426
- * @internal Type brand — exists only in the type system (`declare`
427
- * produces no runtime property). Used by {@linkcode InferFlag} / {@linkcode InferFlags}.
428
- */
429
- readonly _config: C;
430
636
  /**
431
637
  * Create a flag builder from a pre-built schema descriptor.
432
638
  *
@@ -451,7 +657,7 @@ declare class FlagBuilder<C extends FlagConfig> {
451
657
  * // $ mycli serve --port 443 → port = 443
452
658
  * ```
453
659
  */
454
- default<V extends C['valueType']>(value: V): FlagBuilder<WithPresence<C, 'defaulted'>>;
660
+ default<V extends C["valueType"]>(value: V): FlagBuilder<WithPresence<C, "defaulted">>;
455
661
  /**
456
662
  * Mark the flag as required. If not resolved from any source the framework
457
663
  * will emit a `ValidationError` before the action handler runs.
@@ -468,7 +674,7 @@ declare class FlagBuilder<C extends FlagConfig> {
468
674
  * // # → target = 'staging'
469
675
  * ```
470
676
  */
471
- required(): FlagBuilder<WithPresence<C, 'required'>>;
677
+ required(): FlagBuilder<WithPresence<C, "required">>;
472
678
  /**
473
679
  * Add a short or long alias (e.g. `'f'` for `--force`, `'verbose'` as an
474
680
  * alternative long name).
@@ -492,6 +698,9 @@ declare class FlagBuilder<C extends FlagConfig> {
492
698
  /**
493
699
  * Bind to an environment variable (resolved in v0.2+).
494
700
  *
701
+ * The env value is read after CLI and stdin, and before config, the prompt,
702
+ * and the default: CLI → stdin → **env** → config → prompt → default.
703
+ *
495
704
  * @param varName - Environment variable name (e.g. `'PORT'`).
496
705
  * @returns The builder (for chaining).
497
706
  *
@@ -504,9 +713,60 @@ declare class FlagBuilder<C extends FlagConfig> {
504
713
  * ```
505
714
  */
506
715
  env(varName: string): FlagBuilder<WithoutElementEligibility<C>>;
716
+ /**
717
+ * Let this flag read its value from piped stdin.
718
+ *
719
+ * An explicit `--<name> -` is CLI-sourced with bytes from stdin and keeps
720
+ * CLI precedence. An absent flag takes the stdin fallback stage, which sits
721
+ * between CLI and env, so a flag set in the environment still reads stdin
722
+ * and stdin wins. The whole buffer becomes the value, byte for byte for a
723
+ * string flag; every other kind drops the single line terminator a pipe
724
+ * appends before decoding, and `{ trim: true }` drops it for a string flag
725
+ * too.
726
+ *
727
+ * A collection reads the buffer as elements instead: `--tag -` splices what
728
+ * stdin decodes into the position the `-` occupies, so
729
+ * `--tag before --tag - --tag after` over `'a\nb\n'` resolves to
730
+ * `['before', 'a', 'b', 'after']`. `.split({ stdin })` sets the decoding.
731
+ * Each `-` stands for the whole source, so `--tag - --tag -` splices the
732
+ * buffer twice. A `-` typed beside other occurrences with nothing piped fails
733
+ * with `MISSING_STDIN`; occurrences of nothing but `-` fall through to the
734
+ * later sources.
735
+ *
736
+ * A stdin-enabled flag cannot receive a literal `-` as its value, since the
737
+ * token names the source.
738
+ *
739
+ * Available on every flag kind except `count`. One command may declare a
740
+ * single exclusive stdin consumer; pass `{ consume: 'broadcast' }` on every
741
+ * input that should share the buffer.
742
+ *
743
+ * @param options - When to read stdin, how to share it, and whether to trim.
744
+ * @returns The builder (for chaining).
745
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a `count` flag.
746
+ *
747
+ * @example
748
+ * ```ts
749
+ * flag.string().stdin().describe('Message body')
750
+ * // $ echo hi | mycli send → body = 'hi\n'
751
+ * // $ mycli send --body - → body reads stdin
752
+ * // $ mycli send --body hello → body = 'hello'
753
+ *
754
+ * flag.string().stdin({ when: 'dash' })
755
+ * // only `--body -` reads stdin
756
+ *
757
+ * flag.path({ mustExist: true }).stdin({ trim: true })
758
+ * // $ echo ./dist | mycli clean → path = './dist', checked on disk
759
+ * ```
760
+ */
761
+ stdin(this: FlagBuilder<C & {
762
+ readonly flagKind: StdinCapableFlagKind;
763
+ }>, options?: StdinOptions): FlagBuilder<WithoutElementEligibility<C>>;
507
764
  /**
508
765
  * Bind to a dotted config path (resolved in v0.2+).
509
766
  *
767
+ * The config value is read after CLI, stdin, and env, and before the prompt
768
+ * and the default: CLI → stdin → env → **config** → prompt → default.
769
+ *
510
770
  * @param path - Dotted config key (e.g. `'deploy.region'`).
511
771
  * @returns The builder (for chaining).
512
772
  *
@@ -531,7 +791,7 @@ declare class FlagBuilder<C extends FlagConfig> {
531
791
  /**
532
792
  * Attach interactive prompt configuration for v0.3+ resolution.
533
793
  *
534
- * When a flag value is not resolved from CLI, env, or config, the
794
+ * When a flag value is not resolved from CLI, stdin, env, or config, the
535
795
  * prompt engine uses this config to interactively ask the user.
536
796
  * In non-interactive contexts (CI, piped stdin) prompts are skipped
537
797
  * and resolution falls through to default or required validation.
@@ -604,7 +864,7 @@ declare class FlagBuilder<C extends FlagConfig> {
604
864
  * ```
605
865
  */
606
866
  int(this: FlagBuilder<C & {
607
- readonly flagKind: 'number';
867
+ readonly flagKind: "number";
608
868
  }>, value?: boolean): FlagBuilder<C>;
609
869
  /**
610
870
  * Set an inclusive lower bound. Composes with other numeric constraints;
@@ -621,7 +881,7 @@ declare class FlagBuilder<C extends FlagConfig> {
621
881
  * ```
622
882
  */
623
883
  min(this: FlagBuilder<C & {
624
- readonly flagKind: 'number';
884
+ readonly flagKind: "number";
625
885
  }>, value: number): FlagBuilder<C>;
626
886
  /**
627
887
  * Set an inclusive upper bound. Composes with other numeric constraints;
@@ -636,7 +896,7 @@ declare class FlagBuilder<C extends FlagConfig> {
636
896
  * ```
637
897
  */
638
898
  max(this: FlagBuilder<C & {
639
- readonly flagKind: 'number';
899
+ readonly flagKind: "number";
640
900
  }>, value: number): FlagBuilder<C>;
641
901
  /**
642
902
  * Require (or, with `false`, allow) a finite value. Finiteness is enforced
@@ -653,7 +913,7 @@ declare class FlagBuilder<C extends FlagConfig> {
653
913
  * ```
654
914
  */
655
915
  finite(this: FlagBuilder<C & {
656
- readonly flagKind: 'number';
916
+ readonly flagKind: "number";
657
917
  }>, allow?: boolean): FlagBuilder<C>;
658
918
  /**
659
919
  * Reject empty strings. Composes with other string constraints.
@@ -668,7 +928,7 @@ declare class FlagBuilder<C extends FlagConfig> {
668
928
  * ```
669
929
  */
670
930
  nonEmpty(this: FlagBuilder<C & {
671
- readonly flagKind: 'string';
931
+ readonly flagKind: "string";
672
932
  }>, value?: boolean): FlagBuilder<C>;
673
933
  /**
674
934
  * Set an inclusive minimum length (UTF-16 code units). Composes with other
@@ -683,7 +943,7 @@ declare class FlagBuilder<C extends FlagConfig> {
683
943
  * ```
684
944
  */
685
945
  minLength(this: FlagBuilder<C & {
686
- readonly flagKind: 'string';
946
+ readonly flagKind: "string";
687
947
  }>, value: number): FlagBuilder<C>;
688
948
  /**
689
949
  * Set an inclusive maximum length (UTF-16 code units). Composes with other
@@ -698,7 +958,7 @@ declare class FlagBuilder<C extends FlagConfig> {
698
958
  * ```
699
959
  */
700
960
  maxLength(this: FlagBuilder<C & {
701
- readonly flagKind: 'string';
961
+ readonly flagKind: "string";
702
962
  }>, value: number): FlagBuilder<C>;
703
963
  /**
704
964
  * Require the value to match a regular expression. Anchor with `^`/`$`
@@ -713,18 +973,20 @@ declare class FlagBuilder<C extends FlagConfig> {
713
973
  * ```
714
974
  */
715
975
  pattern(this: FlagBuilder<C & {
716
- readonly flagKind: 'string';
976
+ readonly flagKind: "string";
717
977
  }>, value: RegExp): FlagBuilder<C>;
718
978
  /**
719
979
  * Split each CLI occurrence on a separator before element coercion, so
720
980
  * `--tag a,b --tag c` resolves to `['a', 'b', 'c']`. Elements are coerced
721
981
  * (and rejected) individually with the element schema's own error format.
722
982
  *
723
- * Env and config string values are split on the same separator (their
724
- * default split is `','` even without this modifier).
983
+ * The separator is the CLI policy alone. Env values split on `','` and the
984
+ * stdin buffer on line terminators unless `.split()` says otherwise.
725
985
  *
726
986
  * @param value - Separator string (e.g. `','`).
727
987
  * @returns The builder (for chaining).
988
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a flag that carries a
989
+ * single value.
728
990
  *
729
991
  * @example
730
992
  * ```ts
@@ -733,8 +995,76 @@ declare class FlagBuilder<C extends FlagConfig> {
733
995
  * ```
734
996
  */
735
997
  separator(this: FlagBuilder<C & {
736
- readonly flagKind: 'array';
998
+ readonly flagKind: "array" | "keyValue";
737
999
  }>, value: string): FlagBuilder<C>;
1000
+ /**
1001
+ * Set how each source decodes into elements.
1002
+ *
1003
+ * CLI tokens accept `'whole'` and a delimiter; env values also accept
1004
+ * `'json'`; the stdin buffer accepts every format, including `'lines'`. The
1005
+ * strings `'whole'`, `'lines'`, and `'json'` name their format, and every
1006
+ * other string is the delimiter to split on. A source left out keeps what it
1007
+ * already had, or its default: whole CLI tokens (or the `.separator()`
1008
+ * delimiter), comma-delimited env values, line-delimited stdin. A config
1009
+ * value is a native array or object, and a config string decodes under the
1010
+ * env policy. For stdin, `'whole'` passes the complete buffer to a string
1011
+ * element, including its final line terminator.
1012
+ *
1013
+ * @param options - Per-source split settings.
1014
+ * @returns The builder (for chaining).
1015
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a format the source does
1016
+ * not accept, an empty delimiter, or a flag that carries a single value.
1017
+ *
1018
+ * @example
1019
+ * ```ts
1020
+ * flag.array(flag.string()).split({ cli: ',', env: { format: 'json' } }).env('TAGS')
1021
+ * // --tag a,b → ['a', 'b']
1022
+ * // TAGS='["a","b"]' → ['a', 'b']
1023
+ * ```
1024
+ */
1025
+ split(this: FlagBuilder<C & {
1026
+ readonly flagKind: "array" | "keyValue";
1027
+ }>, options: SplitOptions): FlagBuilder<C>;
1028
+ /**
1029
+ * Set how a repeated key combines.
1030
+ *
1031
+ * Applies to repeated CLI occurrences, delimited env pairs, and spliced stdin
1032
+ * reads in the same occurrence order. JSON decoding does not preserve
1033
+ * repeated object member names, so it cannot reliably expose them here.
1034
+ *
1035
+ * @param policy - `'last'` (default), `'first'`, or `'error'`.
1036
+ * @returns The builder (for chaining).
1037
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a flag that is not
1038
+ * `keyValue`.
1039
+ *
1040
+ * @example
1041
+ * ```ts
1042
+ * flag.keyValue().duplicateKeys('error').env('VARS')
1043
+ * // $ VARS='A=1,A=2' mycli run
1044
+ * // # → Duplicate key '<redacted>' from env VARS for flag --env (CONSTRAINT_VIOLATED)
1045
+ * ```
1046
+ */
1047
+ duplicateKeys(this: FlagBuilder<C & {
1048
+ readonly flagKind: "keyValue";
1049
+ }>, policy: DuplicateKeys): FlagBuilder<C>;
1050
+ /**
1051
+ * Validate the resolved value with a Standard Schema v1 validator.
1052
+ *
1053
+ * On a scalar builder the validator sees each value; on a collection builder
1054
+ * it sees the completed array or record, after every element passed its own
1055
+ * validator. `flag.array(flag.string().standard(s))` validates elements,
1056
+ * `flag.array(flag.string()).standard(s)` validates the array.
1057
+ *
1058
+ * @param schema - A Standard Schema v1 validator.
1059
+ * @returns The builder (for chaining).
1060
+ *
1061
+ * @example
1062
+ * ```ts
1063
+ * import { z } from 'zod';
1064
+ * flag.array(flag.string()).standard(z.array(z.string()).min(1))
1065
+ * ```
1066
+ */
1067
+ standard(schema: StandardSchemaV1): FlagBuilder<C>;
738
1068
  /**
739
1069
  * Deduplicate the resolved array, preserving first-seen order. Applied
740
1070
  * after all sources resolve, using `SameValueZero` semantics (like `Set`).
@@ -742,6 +1072,8 @@ declare class FlagBuilder<C extends FlagConfig> {
742
1072
  * @param value - Whether to deduplicate.
743
1073
  * @defaultValue `true`
744
1074
  * @returns The builder (for chaining).
1075
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a flag that is not
1076
+ * `array`.
745
1077
  *
746
1078
  * @example
747
1079
  * ```ts
@@ -750,7 +1082,7 @@ declare class FlagBuilder<C extends FlagConfig> {
750
1082
  * ```
751
1083
  */
752
1084
  unique(this: FlagBuilder<C & {
753
- readonly flagKind: 'array';
1085
+ readonly flagKind: "array";
754
1086
  }>, value?: boolean): FlagBuilder<C>;
755
1087
  /**
756
1088
  * Accept a negated spelling (`--no-<name>`) that sets the flag to `false`.
@@ -764,6 +1096,8 @@ declare class FlagBuilder<C extends FlagConfig> {
764
1096
  * @param options - Optional custom spelling (`alias`, without `--`) and
765
1097
  * `hidden` to keep the negated spelling parseable but unadvertised.
766
1098
  * @returns The builder (for chaining).
1099
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a flag that is not
1100
+ * `boolean`.
767
1101
  *
768
1102
  * @example
769
1103
  * ```ts
@@ -773,7 +1107,7 @@ declare class FlagBuilder<C extends FlagConfig> {
773
1107
  * ```
774
1108
  */
775
1109
  negatable(this: FlagBuilder<C & {
776
- readonly flagKind: 'boolean';
1110
+ readonly flagKind: "boolean";
777
1111
  }>, options?: {
778
1112
  alias?: string;
779
1113
  hidden?: boolean;
@@ -797,7 +1131,7 @@ declare class FlagBuilder<C extends FlagConfig> {
797
1131
  * ```
798
1132
  */
799
1133
  duplicates(this: FlagBuilder<C & {
800
- readonly flagKind: 'boolean' | 'string' | 'number' | 'enum' | 'custom';
1134
+ readonly flagKind: "boolean" | "string" | "number" | "enum" | "custom";
801
1135
  }>, policy: DuplicatePolicy): FlagBuilder<WithoutElementEligibility<C>>;
802
1136
  }
803
1137
  /**
@@ -826,9 +1160,9 @@ interface FlagFactory {
826
1160
  */
827
1161
  string(constraints?: StringConstraints): FlagBuilder<{
828
1162
  readonly valueType: string;
829
- readonly presence: 'optional';
830
- readonly optionalFallback: 'undefined';
831
- readonly flagKind: 'string';
1163
+ readonly presence: "optional";
1164
+ readonly optionalFallback: "undefined";
1165
+ readonly flagKind: "string";
832
1166
  readonly elementEligible: true;
833
1167
  }>;
834
1168
  /**
@@ -855,9 +1189,9 @@ interface FlagFactory {
855
1189
  */
856
1190
  number(constraints?: NumberConstraints): FlagBuilder<{
857
1191
  readonly valueType: number;
858
- readonly presence: 'optional';
859
- readonly optionalFallback: 'undefined';
860
- readonly flagKind: 'number';
1192
+ readonly presence: "optional";
1193
+ readonly optionalFallback: "undefined";
1194
+ readonly flagKind: "number";
861
1195
  readonly elementEligible: true;
862
1196
  }>;
863
1197
  /**
@@ -868,9 +1202,9 @@ interface FlagFactory {
868
1202
  */
869
1203
  boolean(): FlagBuilder<{
870
1204
  readonly valueType: boolean;
871
- readonly presence: 'defaulted';
872
- readonly optionalFallback: 'undefined';
873
- readonly flagKind: 'boolean';
1205
+ readonly presence: "defaulted";
1206
+ readonly optionalFallback: "undefined";
1207
+ readonly flagKind: "boolean";
874
1208
  readonly elementEligible: true;
875
1209
  }>;
876
1210
  /**
@@ -890,9 +1224,9 @@ interface FlagFactory {
890
1224
  */
891
1225
  enum<const T extends readonly [string, ...string[]]>(values: T): FlagBuilder<{
892
1226
  readonly valueType: T[number];
893
- readonly presence: 'optional';
894
- readonly optionalFallback: 'undefined';
895
- readonly flagKind: 'enum';
1227
+ readonly presence: "optional";
1228
+ readonly optionalFallback: "undefined";
1229
+ readonly flagKind: "enum";
896
1230
  readonly elementEligible: true;
897
1231
  }>;
898
1232
  /**
@@ -910,10 +1244,10 @@ interface FlagFactory {
910
1244
  array<E extends FlagConfig & {
911
1245
  readonly elementEligible: true;
912
1246
  }>(element: FlagBuilder<E>): FlagBuilder<{
913
- readonly valueType: E['valueType'][];
914
- readonly presence: 'optional';
915
- readonly optionalFallback: 'empty-array';
916
- readonly flagKind: 'array';
1247
+ readonly valueType: E["valueType"][];
1248
+ readonly presence: "optional";
1249
+ readonly optionalFallback: "empty-array";
1250
+ readonly flagKind: "array";
917
1251
  readonly elementEligible: false;
918
1252
  }>;
919
1253
  /**
@@ -936,9 +1270,9 @@ interface FlagFactory {
936
1270
  */
937
1271
  custom<S extends StandardSchemaV1>(schema: S): FlagBuilder<{
938
1272
  readonly valueType: InferStandardOutput<S>;
939
- readonly presence: 'optional';
940
- readonly optionalFallback: 'undefined';
941
- readonly flagKind: 'custom';
1273
+ readonly presence: "optional";
1274
+ readonly optionalFallback: "undefined";
1275
+ readonly flagKind: "custom";
942
1276
  readonly elementEligible: true;
943
1277
  }>;
944
1278
  /**
@@ -972,9 +1306,9 @@ interface FlagFactory {
972
1306
  */
973
1307
  custom<T>(parseFn: FlagParseFn<T>): FlagBuilder<{
974
1308
  readonly valueType: T;
975
- readonly presence: 'optional';
976
- readonly optionalFallback: 'undefined';
977
- readonly flagKind: 'custom';
1309
+ readonly presence: "optional";
1310
+ readonly optionalFallback: "undefined";
1311
+ readonly flagKind: "custom";
978
1312
  readonly elementEligible: true;
979
1313
  }>;
980
1314
  /**
@@ -992,15 +1326,15 @@ interface FlagFactory {
992
1326
  */
993
1327
  url(options?: UrlFlagOptions): FlagBuilder<{
994
1328
  readonly valueType: URL;
995
- readonly presence: 'optional';
996
- readonly optionalFallback: 'undefined';
997
- readonly flagKind: 'custom';
1329
+ readonly presence: "optional";
1330
+ readonly optionalFallback: "undefined";
1331
+ readonly flagKind: "custom";
998
1332
  readonly elementEligible: true;
999
1333
  }>;
1000
1334
  /**
1001
1335
  * Path-valued flag. The value stays a `string`; optional filesystem
1002
1336
  * checks run **after resolution** through the runtime adapter, so CLI,
1003
- * env, and config values are validated identically.
1337
+ * env, config, prompted, and defaulted values are all validated.
1004
1338
  *
1005
1339
  * @param options - Optional existence/type checks. `type` implies
1006
1340
  * existence unless `mustExist` is explicitly `false`.
@@ -1019,10 +1353,10 @@ interface FlagFactory {
1019
1353
  */
1020
1354
  path(options?: PathFlagOptions): FlagBuilder<{
1021
1355
  readonly valueType: string;
1022
- readonly presence: 'optional';
1023
- readonly optionalFallback: 'undefined';
1024
- readonly flagKind: 'string';
1025
- readonly elementEligible: false;
1356
+ readonly presence: "optional";
1357
+ readonly optionalFallback: "undefined";
1358
+ readonly flagKind: "string";
1359
+ readonly elementEligible: true;
1026
1360
  }>;
1027
1361
  /**
1028
1362
  * Date-valued flag. Accepts strict ISO-8601 (`2026-07-10`,
@@ -1045,9 +1379,9 @@ interface FlagFactory {
1045
1379
  */
1046
1380
  date(options?: DateFlagOptions): FlagBuilder<{
1047
1381
  readonly valueType: Date;
1048
- readonly presence: 'optional';
1049
- readonly optionalFallback: 'undefined';
1050
- readonly flagKind: 'custom';
1382
+ readonly presence: "optional";
1383
+ readonly optionalFallback: "undefined";
1384
+ readonly flagKind: "custom";
1051
1385
  readonly elementEligible: true;
1052
1386
  }>;
1053
1387
  /**
@@ -1064,9 +1398,9 @@ interface FlagFactory {
1064
1398
  */
1065
1399
  duration(): FlagBuilder<{
1066
1400
  readonly valueType: number;
1067
- readonly presence: 'optional';
1068
- readonly optionalFallback: 'undefined';
1069
- readonly flagKind: 'custom';
1401
+ readonly presence: "optional";
1402
+ readonly optionalFallback: "undefined";
1403
+ readonly flagKind: "custom";
1070
1404
  readonly elementEligible: true;
1071
1405
  }>;
1072
1406
  /**
@@ -1083,9 +1417,9 @@ interface FlagFactory {
1083
1417
  */
1084
1418
  bytes(): FlagBuilder<{
1085
1419
  readonly valueType: number;
1086
- readonly presence: 'optional';
1087
- readonly optionalFallback: 'undefined';
1088
- readonly flagKind: 'custom';
1420
+ readonly presence: "optional";
1421
+ readonly optionalFallback: "undefined";
1422
+ readonly flagKind: "custom";
1089
1423
  readonly elementEligible: true;
1090
1424
  }>;
1091
1425
  /**
@@ -1106,21 +1440,27 @@ interface FlagFactory {
1106
1440
  */
1107
1441
  count(): FlagBuilder<{
1108
1442
  readonly valueType: number;
1109
- readonly presence: 'defaulted';
1110
- readonly optionalFallback: 'undefined';
1111
- readonly flagKind: 'count';
1443
+ readonly presence: "defaulted";
1444
+ readonly optionalFallback: "undefined";
1445
+ readonly flagKind: "count";
1112
1446
  readonly elementEligible: false;
1113
1447
  }>;
1114
1448
  /**
1115
1449
  * Key-value flag — repeated `KEY=VALUE` occurrences merge into a
1116
1450
  * `Record<string, string>` (docker/kubectl `--env` style). The value is
1117
1451
  * split at the **first** `=`, so `--env A=b=c` yields `{ A: 'b=c' }`.
1118
- * Later occurrences of the same key win. Absent resolves to `{}`.
1452
+ * Later occurrences of the same key win, which `.duplicateKeys()` changes.
1453
+ * Absent resolves to `{}`.
1119
1454
  *
1120
- * Env vars accept separator-joined pairs (`A=1,B=2`); config files accept
1121
- * a plain object. Not promptable.
1455
+ * Env vars accept comma-delimited pairs (`A=1,B=2`); config files accept a
1456
+ * plain object; `.split()` sets any of that per source. Not promptable.
1122
1457
  *
1123
- * @returns A {@link FlagBuilder} for `Record<string, string>` values.
1458
+ * An element builder gives each entry value its own codec, constraints, and
1459
+ * checks, so `flag.keyValue(flag.path())` checks every value on disk.
1460
+ *
1461
+ * @param element - {@link FlagBuilder} describing the value of each entry.
1462
+ * @defaultValue an unconstrained string element
1463
+ * @returns A {@link FlagBuilder} for records of the element type.
1124
1464
  *
1125
1465
  * @example
1126
1466
  * ```ts
@@ -1128,11 +1468,13 @@ interface FlagFactory {
1128
1468
  * // $ mycli run -e A=1 -e B=2 → env = { A: '1', B: '2' }
1129
1469
  * ```
1130
1470
  */
1131
- keyValue(): FlagBuilder<{
1132
- readonly valueType: Record<string, string>;
1133
- readonly presence: 'optional';
1134
- readonly optionalFallback: 'empty-object';
1135
- readonly flagKind: 'keyValue';
1471
+ keyValue<E extends FlagConfig & {
1472
+ readonly elementEligible: true;
1473
+ } = StringElementConfig>(element?: FlagBuilder<E>): FlagBuilder<{
1474
+ readonly valueType: Record<string, E["valueType"]>;
1475
+ readonly presence: "optional";
1476
+ readonly optionalFallback: "empty-object";
1477
+ readonly flagKind: "keyValue";
1136
1478
  readonly elementEligible: false;
1137
1479
  }>;
1138
1480
  }
@@ -1142,4 +1484,4 @@ interface FlagFactory {
1142
1484
  */
1143
1485
  declare const flag: FlagFactory;
1144
1486
  //#endregion
1145
- export { type AllowedPromptConfig, type ConfirmPromptConfig, type DateFlagOptions, type DuplicatePolicy, FLAG_KINDS, FLAG_PRESENCES, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagNegation, type FlagParseFn, type FlagPresence, type FlagSchema, type FlagSchemaOverrides, type InferFlag, type InferFlags, type InputPromptConfig, type MultiselectPromptConfig, type OptionalFallback, PROMPT_KINDS, type PathChecks, type PathFlagOptions, type PromptConfig, type PromptConfigBase, type PromptConfigByFlagKind, type PromptKind, type PromptResult, type ResolvedValue, type SelectChoice, type SelectPromptConfig, type StringConstraintViolation, type StringConstraints, type UrlFlagOptions, type WithPresence, type WithoutElementEligibility, createSchema, flag, getFlagAliasNames, getFlagNegatedName, normalizeFlagAlias, normalizeFlagAliases };
1487
+ export { type AllowedPromptConfig, type ArrayFlagDefinition, type BooleanFlagDefinition, type ConfirmPromptConfig, type CountFlagDefinition, type CustomFlagDefinition, DUPLICATE_KEYS, type DateFlagOptions, type DuplicateKeys, type DuplicatePolicy, type EnumFlagDefinition, FLAG_KINDS, FLAG_PRESENCES, type FlagAlias, FlagBuilder, type FlagConfig, type FlagDefinition, type FlagDefinitionBase, type FlagDefinitionByKind, type FlagDefinitionOverrides, type FlagFactory, type FlagKind, type FlagNegation, type FlagParseFn, type FlagPresence, type FlagSchema, type InferFlag, type InferFlags, type InputPromptConfig, type KeyValueFlagDefinition, type MultiselectPromptConfig, type NumberFlagDefinition, type OptionalFallback, PROMPT_KINDS, type PathChecks, type PathFlagOptions, type PromptConfig, type PromptConfigBase, type PromptConfigByFlagKind, type PromptKind, type PromptResult, type ResolvedValue, SPLIT_FORMATS, STDIN_CONSUMES, STDIN_WHENS, type SelectChoice, type SelectPromptConfig, type SourceSplitBinding, type SplitBinding, type SplitFormat, type SplitOptions, type SplitPolicy, type SplitSetting, type StdinBinding, type StdinConsume, type StdinOptions, type StdinWhen, type StringConstraintViolation, type StringConstraints, type StringElementConfig, type StringFlagDefinition, type UrlFlagOptions, type WithPresence, type WithoutElementEligibility, createFlagSchema, flag, getFlagAliasNames, getFlagNegatedName, normalizeFlagAlias, normalizeFlagAliases };