@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,5 +1,11 @@
1
+ import { schemaBrand } from "./brand.mjs";
1
2
  import { NumberConstraints } from "./number-constraints.mjs";
3
+ import { ConfirmPromptConfig, InputPromptConfig, MultiselectPromptConfig, PromptConfig, SelectPromptConfig } from "./prompt.mjs";
2
4
  import { InferStandardOutput, StandardSchemaV1 } from "./standard.mjs";
5
+ import { StdinBinding, StdinConsume, StdinOptions, StdinWhen } from "./stdin.mjs";
6
+ import { StringConstraints } from "./string-constraints.mjs";
7
+ import { DateFlagOptions, PathChecks, PathFlagOptions, UrlFlagOptions } from "./value-parsers.mjs";
8
+ import { DuplicateKeys, SourceSplitBinding, SplitBinding, SplitFormat, SplitOptions, SplitPolicy, SplitSetting } from "./cardinality.mjs";
3
9
  //#region src/core/schema/arg.d.ts
4
10
  /** All arg presence states as a runtime array. */
5
11
  declare const ARG_PRESENCES: readonly ["required", "optional", "defaulted"];
@@ -24,26 +30,62 @@ interface ArgConfig {
24
30
  readonly variadic: boolean;
25
31
  /** The runtime kind discriminator, mirroring {@link ArgKind}. */
26
32
  readonly argKind: ArgKind;
33
+ /**
34
+ * Whether this builder may still be passed to `arg.keyValue()` as its entry
35
+ * value. Factories start `true`; the modifiers that describe the positional
36
+ * itself (`.env()`, `.prompt()`, `.optional()`, `.stdin()`, …) flip it to
37
+ * `false`, since an entry value is never read for those settings.
38
+ */
39
+ readonly elementEligible: boolean;
27
40
  }
28
41
  /**
29
42
  * Advanced type helper used by {@linkcode ArgBuilder} modifiers to replace presence.
30
43
  * Most consumers rely on inference and never reference this directly.
31
44
  */
32
45
  type WithArgPresence<C extends ArgConfig, P extends ArgPresence> = {
33
- readonly valueType: C['valueType'];
46
+ readonly valueType: C["valueType"];
34
47
  readonly presence: P;
35
- readonly variadic: C['variadic'];
36
- readonly argKind: C['argKind'];
48
+ readonly variadic: C["variadic"];
49
+ readonly argKind: C["argKind"];
50
+ readonly elementEligible: false;
37
51
  };
38
52
  /**
39
53
  * Advanced type helper used by {@linkcode ArgBuilder.variadic | ArgBuilder.variadic()}.
40
54
  * Most consumers rely on inference and never reference this directly.
41
55
  */
42
56
  type WithVariadic<C extends ArgConfig> = {
43
- readonly valueType: C['valueType'];
44
- readonly presence: C['presence'];
57
+ readonly valueType: C["valueType"];
58
+ readonly presence: C["presence"];
45
59
  readonly variadic: true;
46
- readonly argKind: C['argKind'];
60
+ readonly argKind: C["argKind"];
61
+ readonly elementEligible: false;
62
+ };
63
+ /**
64
+ * Advanced type helper: marks a builder as no longer usable as an entry value
65
+ * (returned by the modifiers whose settings an entry value ignores).
66
+ */
67
+ type WithoutArgElementEligibility<C extends ArgConfig> = {
68
+ readonly valueType: C["valueType"];
69
+ readonly presence: C["presence"];
70
+ readonly variadic: C["variadic"];
71
+ readonly argKind: C["argKind"];
72
+ readonly elementEligible: false;
73
+ };
74
+ /**
75
+ * The element config `arg.keyValue()` assumes when given no element builder: an
76
+ * unconstrained string.
77
+ */
78
+ type StringArgElementConfig = {
79
+ /** Element value type. */
80
+ readonly valueType: string;
81
+ /** Elements carry no presence of their own. */
82
+ readonly presence: "required";
83
+ /** Elements are never variadic on their own. */
84
+ readonly variadic: false;
85
+ /** Element kind discriminator. */
86
+ readonly argKind: "string";
87
+ /** Elements are element-eligible by construction. */
88
+ readonly elementEligible: true;
47
89
  };
48
90
  /**
49
91
  * Compute the final value type from config — this is what handlers receive.
@@ -51,18 +93,53 @@ type WithVariadic<C extends ArgConfig> = {
51
93
  * Advanced type helper: this powers {@link InferArg} and action-handler
52
94
  * inference. Most apps do not need to mention it explicitly.
53
95
  *
54
- * Variadic args always produce an array. Non-variadic:
96
+ * A `keyValue` arg always produces a record, variadic or not, because it
97
+ * aggregates entries rather than a list. Variadic args of every other kind
98
+ * produce an array. Non-variadic:
55
99
  * - `'optional'` → `T | undefined`
56
100
  * - `'required'` → `T`
57
101
  * - `'defaulted'` → `T`
58
102
  */
59
- type ResolvedArgValue<C extends ArgConfig> = C['variadic'] extends true ? C['valueType'][] : C['presence'] extends 'optional' ? C['valueType'] | undefined : C['valueType'];
103
+ type ResolvedArgValue<C extends ArgConfig> = C["argKind"] extends "keyValue" ? C["valueType"] : C["variadic"] extends true ? C["valueType"][] : C["presence"] extends "optional" ? C["valueType"] | undefined : C["valueType"];
104
+ /**
105
+ * The value `.default()` accepts for an arg.
106
+ *
107
+ * A default stands in for what the arg resolves to, so an arg that aggregates
108
+ * takes the completed array or record and every other arg takes one value.
109
+ */
110
+ type ArgDefaultValue<C extends ArgConfig> = C["argKind"] extends "keyValue" ? C["valueType"] : C["variadic"] extends true ? readonly C["valueType"][] : C["valueType"];
111
+ /**
112
+ * Maps an {@linkcode ArgKind} to the prompt config types compatible with it,
113
+ * mirroring the flag table for the kinds args have.
114
+ *
115
+ * - `'string'` → {@link InputPromptConfig} | {@link SelectPromptConfig}
116
+ * - `'number'` → {@link InputPromptConfig}
117
+ * - `'boolean'` → {@link ConfirmPromptConfig}
118
+ * - `'enum'` → {@link SelectPromptConfig} | {@link InputPromptConfig}
119
+ * - `'custom'` → all prompt kinds ({@link PromptConfig})
120
+ * - `'keyValue'` → `never` (not promptable)
121
+ */
122
+ type PromptConfigByArgKind = {
123
+ readonly string: InputPromptConfig | SelectPromptConfig;
124
+ readonly number: InputPromptConfig;
125
+ readonly boolean: ConfirmPromptConfig;
126
+ readonly enum: SelectPromptConfig | InputPromptConfig;
127
+ readonly custom: PromptConfig;
128
+ readonly keyValue: never;
129
+ };
130
+ /**
131
+ * Prompt configuration compatible with an {@link ArgConfig}.
132
+ *
133
+ * A variadic arg collects several values, so it takes the multiselect a
134
+ * `flag.array()` takes; every other arg takes what its kind takes.
135
+ */
136
+ type AllowedArgPromptConfig<C extends ArgConfig> = C["argKind"] extends "keyValue" ? never : C["variadic"] extends true ? MultiselectPromptConfig : PromptConfigByArgKind[C["argKind"]];
60
137
  /** Extract the resolved value type from an {@linkcode ArgBuilder}. */
61
138
  type InferArg<B> = B extends ArgBuilder<infer C extends ArgConfig> ? ResolvedArgValue<C> : never;
62
139
  /** Extract resolved value types from a record of builders. */
63
140
  type InferArgs<T extends Record<string, ArgBuilder<ArgConfig>>> = { [K in keyof T]: InferArg<T[K]>; };
64
141
  /** All arg kind discriminators as a runtime array. */
65
- declare const ARG_KINDS: readonly ["string", "number", "enum", "custom"];
142
+ declare const ARG_KINDS: readonly ["string", "number", "boolean", "enum", "custom", "keyValue"];
66
143
  /** Discriminator for the kind of value an arg accepts. */
67
144
  type ArgKind = (typeof ARG_KINDS)[number];
68
145
  /** Custom parse function for `arg.custom()`. */
@@ -72,18 +149,20 @@ type ArgParseFn<T> = (raw: string) => T;
72
149
  * help generator) read this to understand the arg's shape without touching
73
150
  * generics.
74
151
  */
75
- interface ArgSchema {
152
+ interface ArgSchema<K extends ArgKind = ArgKind> {
153
+ /** Type-only seal produced by {@link createArgSchema}. */
154
+ readonly [schemaBrand]: "arg";
76
155
  /** What kind of value this arg accepts. */
77
- readonly kind: ArgKind;
156
+ readonly kind: K;
78
157
  /** Current presence state. */
79
158
  readonly presence: ArgPresence;
80
159
  /** Whether this arg consumes all remaining positionals. */
81
160
  readonly variadic: boolean;
82
161
  /**
83
- * Whether this arg may read from stdin during resolution.
84
- * @defaultValue `false`
162
+ * Stdin binding set by `.stdin()` (`undefined` when the arg never reads
163
+ * stdin). See {@link StdinBinding}.
85
164
  */
86
- readonly stdinMode: boolean;
165
+ readonly stdin: StdinBinding | undefined;
87
166
  /** Runtime default value (if any). */
88
167
  readonly defaultValue: unknown;
89
168
  /** Human-readable description for help text. */
@@ -97,8 +176,27 @@ interface ArgSchema {
97
176
  * @see {@link ArgBuilder.env} for the builder method.
98
177
  */
99
178
  readonly envVar: string | undefined;
179
+ /**
180
+ * Dotted config path for config resolution (e.g. `'deploy.region'`).
181
+ *
182
+ * @see {@link ArgBuilder.config} for the builder method.
183
+ */
184
+ readonly configPath: string | undefined;
185
+ /**
186
+ * Interactive prompt configuration.
187
+ *
188
+ * @see {@link ArgBuilder.prompt} for the builder method.
189
+ */
190
+ readonly prompt: PromptConfig | undefined;
100
191
  /** Allowed literal values when `kind === 'enum'`. */
101
192
  readonly enumValues: readonly string[] | undefined;
193
+ /**
194
+ * Element schema when `kind === 'keyValue'`.
195
+ *
196
+ * Describes the value of each entry, so `arg.keyValue(arg.number())` decodes
197
+ * `A=1` to the number `1`. `undefined` leaves entry values as strings.
198
+ */
199
+ readonly elementSchema: ArgSchema | undefined;
102
200
  /**
103
201
  * Numeric constraints when `kind === 'number'` (`undefined` otherwise).
104
202
  *
@@ -106,17 +204,75 @@ interface ArgSchema {
106
204
  * `true`, so `Infinity` is rejected even when no constraints object is set.
107
205
  */
108
206
  readonly numberConstraints: NumberConstraints | undefined;
207
+ /**
208
+ * String constraints when `kind === 'string'` (`undefined` otherwise).
209
+ *
210
+ * Enforced at the parse and resolution boundaries, in fixed order:
211
+ * nonEmpty → minLength → maxLength → pattern. A `defaultValue` is a typed
212
+ * value, so it is validated against them when the schema is built.
213
+ */
214
+ readonly stringConstraints: StringConstraints | undefined;
215
+ /**
216
+ * Filesystem checks for path-valued args (set by `arg.path()`).
217
+ *
218
+ * Validated after resolution through the runtime adapter, so CLI, stdin,
219
+ * env, and defaulted values are all checked. Only meaningful when
220
+ * `kind === 'string'`.
221
+ */
222
+ readonly pathChecks: PathChecks | undefined;
223
+ /**
224
+ * Help placeholder label (e.g. `'url'`).
225
+ *
226
+ * Set by the sugar factories (`arg.url()`, `arg.date()`, …) so tooling
227
+ * reading the schema knows the expected value shape. Help renders a
228
+ * positional by its own name, so this does not change the usage line.
229
+ */
230
+ readonly valueHint: string | undefined;
109
231
  /** Custom parse function (only when `kind === 'custom'`). */
110
232
  readonly parseFn: ArgParseFn<unknown> | undefined;
111
233
  /**
112
- * Standard Schema v1 validator applied to the resolved value.
234
+ * CLI value separator for a collection (`undefined` otherwise).
235
+ *
236
+ * When set, each positional token is split on this separator before element
237
+ * coercion. Other sources decode through {@link ArgSchema.split}.
238
+ */
239
+ readonly separator: string | undefined;
240
+ /**
241
+ * Env and stdin split policies for a collection (`undefined` otherwise).
242
+ *
243
+ * A source the binding leaves out takes its default: comma-delimited for env,
244
+ * line-delimited for stdin.
245
+ */
246
+ readonly split: SourceSplitBinding | undefined;
247
+ /**
248
+ * How a repeated key combines when `kind === 'keyValue'`.
249
+ *
250
+ * @defaultValue `'last'`
251
+ */
252
+ readonly duplicateKeys: DuplicateKeys;
253
+ /**
254
+ * Deduplicate the resolved values of a variadic arg.
255
+ *
256
+ * Applied after all sources resolve, preserving first-seen order. Uses
257
+ * `SameValueZero` semantics (like `Set`).
258
+ */
259
+ readonly unique: boolean;
260
+ /**
261
+ * Standard Schema v1 validator applied to each resolved value.
113
262
  *
114
263
  * When set, the value from any source (CLI, env, stdin, default) is
115
264
  * validated after resolution via `~standard.validate`. Sync and async
116
265
  * validators are both awaited; issues surface as a `CONSTRAINT_VIOLATED`
117
- * {@link ValidationError}. Only meaningful when `kind === 'custom'`.
266
+ * {@link ValidationError}. A variadic arg validates every element with it.
118
267
  */
119
268
  readonly standard: StandardSchemaV1 | undefined;
269
+ /**
270
+ * Standard Schema v1 validator applied to the completed collection.
271
+ *
272
+ * Set by `.standard()` on a builder that already aggregates, so the array or
273
+ * record is validated as a whole after every element passed.
274
+ */
275
+ readonly aggregateStandard: StandardSchemaV1 | undefined;
120
276
  /**
121
277
  * Deprecation marker.
122
278
  *
@@ -129,6 +285,169 @@ interface ArgSchema {
129
285
  */
130
286
  readonly deprecated: string | true | undefined;
131
287
  }
288
+ /** Definition fields accepted by every arg kind. */
289
+ interface ArgDefinitionBase {
290
+ /**
291
+ * Presence state.
292
+ * @defaultValue `'required'`
293
+ */
294
+ readonly presence?: ArgPresence | undefined;
295
+ /**
296
+ * Whether this arg consumes all remaining positionals.
297
+ * @defaultValue `false`
298
+ */
299
+ readonly variadic?: boolean | undefined;
300
+ /**
301
+ * Stdin binding. See {@link StdinOptions}.
302
+ * @defaultValue `undefined`
303
+ */
304
+ readonly stdin?: StdinOptions | undefined;
305
+ /**
306
+ * Runtime default value.
307
+ * @defaultValue `undefined`
308
+ */
309
+ readonly defaultValue?: unknown;
310
+ /**
311
+ * Human-readable description for help text.
312
+ * @defaultValue `undefined`
313
+ */
314
+ readonly description?: string | undefined;
315
+ /**
316
+ * Environment variable name for env resolution.
317
+ * @defaultValue `undefined`
318
+ */
319
+ readonly envVar?: string | undefined;
320
+ /**
321
+ * Dotted config path for config resolution (e.g. `'deploy.region'`).
322
+ * @defaultValue `undefined`
323
+ */
324
+ readonly configPath?: string | undefined;
325
+ /**
326
+ * Interactive prompt configuration.
327
+ * @defaultValue `undefined`
328
+ */
329
+ readonly prompt?: PromptConfig | undefined;
330
+ /**
331
+ * Help placeholder label (`'url'`, `'path'`, …).
332
+ * @defaultValue `undefined`
333
+ */
334
+ readonly valueHint?: string | undefined;
335
+ /**
336
+ * CLI value separator each positional token is split on.
337
+ * @defaultValue `undefined`
338
+ */
339
+ readonly separator?: string | undefined;
340
+ /**
341
+ * Env and stdin split policies.
342
+ * @defaultValue `undefined`
343
+ */
344
+ readonly split?: SourceSplitBinding | undefined;
345
+ /**
346
+ * Deduplicate the resolved values of a variadic arg.
347
+ * @defaultValue `false`
348
+ */
349
+ readonly unique?: boolean | undefined;
350
+ /**
351
+ * Standard Schema v1 validator applied to each resolved value.
352
+ * @defaultValue `undefined`
353
+ */
354
+ readonly standard?: StandardSchemaV1 | undefined;
355
+ /**
356
+ * Standard Schema v1 validator applied to a completed collection.
357
+ * @defaultValue `undefined`
358
+ */
359
+ readonly aggregateStandard?: StandardSchemaV1 | undefined;
360
+ /**
361
+ * Deprecation marker. `true` deprecates without a message, a string carries
362
+ * the migration guidance.
363
+ * @defaultValue `undefined`
364
+ */
365
+ readonly deprecated?: string | true | undefined;
366
+ }
367
+ /** Definition of a `string` arg. */
368
+ interface StringArgDefinition extends ArgDefinitionBase {
369
+ /** Kind discriminator. */
370
+ readonly kind: "string";
371
+ /**
372
+ * String constraints enforced at the parse and resolution boundaries.
373
+ * @defaultValue `undefined`
374
+ */
375
+ readonly stringConstraints?: StringConstraints | undefined;
376
+ /**
377
+ * Filesystem checks applied after resolution.
378
+ * @defaultValue `undefined`
379
+ */
380
+ readonly pathChecks?: PathChecks | undefined;
381
+ }
382
+ /** Definition of a `number` arg. */
383
+ interface NumberArgDefinition extends ArgDefinitionBase {
384
+ /** Kind discriminator. */
385
+ readonly kind: "number";
386
+ /**
387
+ * Numeric constraints enforced at the parse and resolution boundaries.
388
+ * @defaultValue `undefined`
389
+ */
390
+ readonly numberConstraints?: NumberConstraints | undefined;
391
+ }
392
+ /** Definition of an `enum` arg. */
393
+ interface EnumArgDefinition extends ArgDefinitionBase {
394
+ /** Kind discriminator. */
395
+ readonly kind: "enum";
396
+ /** Allowed literal values. */
397
+ readonly enumValues: readonly string[];
398
+ }
399
+ /** Definition of a `custom` arg. */
400
+ interface CustomArgDefinition extends ArgDefinitionBase {
401
+ /** Kind discriminator. */
402
+ readonly kind: "custom";
403
+ /**
404
+ * Parse function applied to the raw value.
405
+ * @defaultValue `undefined`
406
+ */
407
+ readonly parseFn?: ArgParseFn<unknown> | undefined;
408
+ }
409
+ /** Definition of a `boolean` arg. */
410
+ interface BooleanArgDefinition extends ArgDefinitionBase {
411
+ /** Kind discriminator. */
412
+ readonly kind: "boolean";
413
+ }
414
+ /** Definition of a `keyValue` arg. */
415
+ interface KeyValueArgDefinition extends ArgDefinitionBase {
416
+ /** Kind discriminator. */
417
+ readonly kind: "keyValue";
418
+ /**
419
+ * How a repeated key combines. See {@link DuplicateKeys}.
420
+ * @defaultValue `'last'`
421
+ */
422
+ readonly duplicateKeys?: DuplicateKeys | undefined;
423
+ /**
424
+ * Schema describing the value of each entry, as a definition or an already
425
+ * built {@link ArgSchema}.
426
+ * @defaultValue `undefined`, which leaves entry values as strings
427
+ */
428
+ readonly elementSchema?: ArgDefinition | ArgSchema | undefined;
429
+ }
430
+ /** Maps each {@link ArgKind} to its definition shape. */
431
+ interface ArgDefinitionByKind {
432
+ /** Definition shape for `string` args. */
433
+ readonly string: StringArgDefinition;
434
+ /** Definition shape for `number` args. */
435
+ readonly number: NumberArgDefinition;
436
+ /** Definition shape for `boolean` args. */
437
+ readonly boolean: BooleanArgDefinition;
438
+ /** Definition shape for `enum` args. */
439
+ readonly enum: EnumArgDefinition;
440
+ /** Definition shape for `custom` args. */
441
+ readonly custom: CustomArgDefinition;
442
+ /** Definition shape for `keyValue` args. */
443
+ readonly keyValue: KeyValueArgDefinition;
444
+ }
445
+ /** Definition of an arg of kind `K`, including the kind discriminator. */
446
+ type ArgDefinition<K extends ArgKind = ArgKind> = ArgDefinitionByKind[K];
447
+ /** Definition of an arg of kind `K` with the kind discriminator removed. */
448
+ type ArgDefinitionOverrides<K extends ArgKind = ArgKind> = Omit<ArgDefinitionByKind[K], "kind">;
449
+ /** Positional factory arguments, requiring fields that the selected kind requires. */
450
+ type ArgDefinitionArguments<K extends ArgKind> = K extends "enum" ? [overrides: ArgDefinitionOverrides<K>] : [overrides?: ArgDefinitionOverrides<K>];
132
451
  /**
133
452
  * Create a raw {@link ArgSchema} object with sensible defaults.
134
453
  *
@@ -137,13 +456,14 @@ interface ArgSchema {
137
456
  * modifiers. `createArgSchema()` exists for advanced schema composition,
138
457
  * targeted tests, or custom builders that need the plain runtime descriptor.
139
458
  *
140
- * `overrides` are shallow-merged on top of the default shape, so callers are
141
- * responsible for preserving invariants such as variadic ordering and
142
- * compatible `parseFn` / `kind` combinations.
459
+ * Fields are shallow-merged on top of the default shape, so callers are
460
+ * responsible for preserving invariants such as variadic ordering.
143
461
  *
144
462
  * @param kind - Discriminator for the value type this arg accepts.
145
- * @param overrides - Partial schema fields shallow-merged onto defaults.
463
+ * @param overrides - Definition fields for `kind`, shallow-merged onto defaults.
146
464
  * @returns A fully populated {@link ArgSchema}.
465
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when a field belongs to a
466
+ * different {@link ArgKind}.
147
467
  *
148
468
  * @example
149
469
  * ```ts
@@ -153,7 +473,28 @@ interface ArgSchema {
153
473
  * });
154
474
  * ```
155
475
  */
156
- declare function createArgSchema(kind: ArgKind, overrides?: Partial<ArgSchema>): ArgSchema;
476
+ declare function createArgSchema<K extends ArgKind>(kind: K, ...overrides: ArgDefinitionArguments<K>): ArgSchema<K>;
477
+ /**
478
+ * Create a raw {@link ArgSchema} object from a single definition object.
479
+ *
480
+ * An already-built {@link ArgSchema} is accepted and re-normalized into a
481
+ * deep-equal schema.
482
+ *
483
+ * @param definition - Kind discriminator plus the fields valid for that kind.
484
+ * @returns A fully populated {@link ArgSchema}.
485
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when a field belongs to a
486
+ * different {@link ArgKind}.
487
+ *
488
+ * @example
489
+ * ```ts
490
+ * const schema = createArgSchema({
491
+ * kind: 'enum',
492
+ * enumValues: ['us', 'eu', 'ap'],
493
+ * description: 'Target region',
494
+ * });
495
+ * ```
496
+ */
497
+ declare function createArgSchema<K extends ArgKind>(definition: ArgDefinition<K> | ArgSchema<K>): ArgSchema<K>;
157
498
  /**
158
499
  * Immutable positional argument schema builder.
159
500
  *
@@ -199,13 +540,6 @@ declare function createArgSchema(kind: ArgKind, overrides?: Partial<ArgSchema>):
199
540
  * ```
200
541
  */
201
542
  declare class ArgBuilder<C extends ArgConfig> {
202
- /** @internal Runtime schema descriptor. */
203
- readonly schema: ArgSchema;
204
- /**
205
- * @internal Type brand — exists only in the type system (`declare`
206
- * produces no runtime property). Used by {@linkcode InferArg} / {@linkcode InferArgs}.
207
- */
208
- readonly _config: C;
209
543
  /**
210
544
  * Create an arg builder from a pre-built schema descriptor.
211
545
  *
@@ -215,7 +549,7 @@ declare class ArgBuilder<C extends ArgConfig> {
215
549
  /**
216
550
  * Mark the arg as required (this is the default for positional args).
217
551
  * Produces an error if no value resolves from any configured source
218
- * (CLI → stdin → env → default).
552
+ * (CLI → stdin → env → config → prompt → default).
219
553
  *
220
554
  * @example
221
555
  * ```ts
@@ -230,7 +564,7 @@ declare class ArgBuilder<C extends ArgConfig> {
230
564
  *
231
565
  * @returns The builder (for chaining).
232
566
  */
233
- required(): ArgBuilder<WithArgPresence<C, 'required'>>;
567
+ required(): ArgBuilder<WithArgPresence<C, "required">>;
234
568
  /**
235
569
  * Mark the arg as optional. Handlers receive `undefined` when absent.
236
570
  *
@@ -250,23 +584,28 @@ declare class ArgBuilder<C extends ArgConfig> {
250
584
  *
251
585
  * @returns The builder (for chaining).
252
586
  */
253
- optional(): ArgBuilder<WithArgPresence<C, 'optional'>>;
587
+ optional(): ArgBuilder<WithArgPresence<C, "optional">>;
254
588
  /**
255
589
  * Provide a default value. The arg becomes "always present" — handlers
256
590
  * will never see `undefined`.
257
591
  *
258
- * The generic constraint `V extends C['valueType']` ensures the default
259
- * matches the arg's declared type.
592
+ * The generic constraint {@link ArgDefaultValue} ensures the default matches
593
+ * what the arg resolves to: an array for a variadic arg, a record for a
594
+ * `keyValue` one, and a single value otherwise.
260
595
  *
261
- * Resolution order when extra sources are configured: CLI → stdin → env → **default**.
596
+ * Resolution order when extra sources are configured:
597
+ * CLI → stdin → env → config → prompt → **default**.
262
598
  *
263
599
  * @param value - Fallback used when no CLI value or env var resolves.
264
600
  * @returns The builder (for chaining).
601
+ * @throws {CLIError} With code `'INVALID_DEFAULT'` when the value is one the
602
+ * arg could never hold.
265
603
  *
266
604
  * @example
267
605
  * ```ts
268
606
  * arg.string().default('production')
269
607
  * arg.number().default(3000)
608
+ * arg.string().variadic().default(['a', 'b'])
270
609
  *
271
610
  * // In a command — default kicks in when CLI and env are both absent:
272
611
  * command('deploy')
@@ -282,12 +621,14 @@ declare class ArgBuilder<C extends ArgConfig> {
282
621
  * // $ mycli deploy production → 'production' (CLI)
283
622
  * ```
284
623
  */
285
- default<V extends C['valueType']>(value: V): ArgBuilder<WithArgPresence<C, 'defaulted'>>;
624
+ default<V extends ArgDefaultValue<C>>(value: V): ArgBuilder<WithArgPresence<C, "defaulted">>;
286
625
  /**
287
626
  * Mark this arg as variadic — it consumes all remaining positional
288
627
  * arguments. The inferred type becomes `T[]`.
289
628
  *
290
- * A variadic arg must be the last positional in a command.
629
+ * A variadic arg is the last positional a command can declare. Registering
630
+ * another positional after it throws `INVALID_BUILDER_STATE` from `.arg()`
631
+ * and from `createCommandSchema()`.
291
632
  *
292
633
  * @example
293
634
  * ```ts
@@ -309,30 +650,162 @@ declare class ArgBuilder<C extends ArgConfig> {
309
650
  */
310
651
  variadic(): ArgBuilder<WithVariadic<C>>;
311
652
  /**
312
- * Allow this arg to resolve from stdin when CLI input is missing.
653
+ * Split each positional token on a separator before element coercion, so
654
+ * `mycli build a,b c` collects `['a', 'b', 'c']` into a variadic arg.
655
+ *
656
+ * The separator is the CLI policy alone. Env values split on `','` and the
657
+ * stdin buffer on line terminators unless `.split()` says otherwise.
658
+ *
659
+ * Available on an arg that aggregates, so call it after `.variadic()` or on
660
+ * `arg.keyValue()`.
661
+ *
662
+ * @param value - Separator string (e.g. `','`).
663
+ * @returns The builder (for chaining).
664
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on an arg carrying a single
665
+ * value.
666
+ */
667
+ separator(this: ArgBuilder<C & {
668
+ readonly variadic: true;
669
+ }> | ArgBuilder<C & {
670
+ readonly argKind: "keyValue";
671
+ }>, value: string): ArgBuilder<C>;
672
+ /**
673
+ * Set how each source decodes into elements.
674
+ *
675
+ * CLI tokens accept `'whole'` and a delimiter; env values also accept
676
+ * `'json'`; the stdin buffer accepts every format, including `'lines'`. The
677
+ * strings `'whole'`, `'lines'`, and `'json'` name their format, and every
678
+ * other string is the delimiter to split on. A source left out keeps what it
679
+ * already had, or its default: whole CLI tokens, comma-delimited env values,
680
+ * line-delimited stdin. For stdin, `'whole'` passes the complete buffer to a
681
+ * string element, including its final line terminator.
682
+ *
683
+ * Available on an arg that aggregates, so call it after `.variadic()` or on
684
+ * `arg.keyValue()`.
685
+ *
686
+ * @param options - Per-source split settings.
687
+ * @returns The builder (for chaining).
688
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a format the source does
689
+ * not accept, an empty delimiter, or an arg carrying a single value.
690
+ *
691
+ * @example
692
+ * ```ts
693
+ * arg.string().variadic().split({ env: { format: 'json' } })
694
+ * // FILES='["a.ts","b.ts"]' → ['a.ts', 'b.ts']
695
+ * ```
696
+ */
697
+ split(this: ArgBuilder<C & {
698
+ readonly variadic: true;
699
+ }> | ArgBuilder<C & {
700
+ readonly argKind: "keyValue";
701
+ }>, options: SplitOptions): ArgBuilder<C>;
702
+ /**
703
+ * Deduplicate the resolved values of a variadic arg, preserving first-seen
704
+ * order. Applied after all sources resolve, using `SameValueZero` semantics.
705
+ *
706
+ * Available on a variadic arg of a list kind, so call it after `.variadic()`.
707
+ *
708
+ * @param value - Whether to deduplicate.
709
+ * @defaultValue `true`
710
+ * @returns The builder (for chaining).
711
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on an arg that resolves to
712
+ * one value or to a record.
713
+ */
714
+ unique(this: ArgBuilder<C & {
715
+ readonly variadic: true;
716
+ readonly argKind: ListArgKind;
717
+ }>, value?: boolean): ArgBuilder<C>;
718
+ /**
719
+ * Set how a repeated key combines.
720
+ *
721
+ * @param policy - `'last'` (default), `'first'`, or `'error'`.
722
+ * @returns The builder (for chaining).
723
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on an arg that is not
724
+ * `arg.keyValue()`.
725
+ *
726
+ * @example
727
+ * ```ts
728
+ * arg.keyValue().variadic().duplicateKeys('error').env('VARS')
729
+ * // $ VARS='A=1,A=2' mycli run
730
+ * // # → Duplicate key '<redacted>' from env VARS for argument <vars> (CONSTRAINT_VIOLATED)
731
+ * ```
732
+ */
733
+ duplicateKeys(this: ArgBuilder<C & {
734
+ readonly argKind: "keyValue";
735
+ }>, policy: DuplicateKeys): ArgBuilder<C>;
736
+ /**
737
+ * Validate the resolved value with a Standard Schema v1 validator.
313
738
  *
314
- * Resolution order becomes: CLI value -> stdin -> env -> default.
315
- * Only one arg per command may enable stdin mode.
739
+ * On a single-value builder the validator sees each value; on a builder that
740
+ * already aggregates (`.variadic()` or `arg.keyValue()`) it sees the
741
+ * completed array or record, after every element passed its own validator.
316
742
  *
743
+ * The builder this is called on is what decides, so where the call sits
744
+ * relative to `.variadic()` chooses between the two.
745
+ *
746
+ * @param schema - A Standard Schema v1 validator.
747
+ * @returns The builder (for chaining).
748
+ *
749
+ * @example
750
+ * ```ts
751
+ * import { z } from 'zod';
752
+ * arg.string().standard(z.string().min(1)).variadic() // each element
753
+ * arg.string().variadic().standard(z.array(z.string())) // the whole array
754
+ * ```
755
+ */
756
+ standard(schema: StandardSchemaV1): ArgBuilder<C>;
757
+ /**
758
+ * Let this arg read its value from piped stdin.
759
+ *
760
+ * An explicit `-` in the arg's slot is CLI-sourced with bytes from stdin and
761
+ * keeps CLI precedence. An absent positional takes the stdin fallback stage,
762
+ * which sits between CLI and env, so an arg set in the environment still
763
+ * reads stdin and stdin wins. The whole buffer becomes the value, byte for
764
+ * byte for a string arg; every other kind drops the single line terminator a
765
+ * pipe appends before decoding, and `{ trim: true }` drops it for a string
766
+ * arg too.
767
+ *
768
+ * On an arg that aggregates, a `-` among the tail tokens splices what the
769
+ * buffer decodes to into that position, so `mycli build a - b` over
770
+ * `'x\ny\n'` collects `['a', 'x', 'y', 'b']`. Each `-` stands for the whole
771
+ * source, so two of them splice the buffer twice. A `-` typed beside other
772
+ * tokens with nothing piped fails with `MISSING_STDIN`; a tail of nothing but
773
+ * `-` falls through to the later sources.
774
+ *
775
+ * A stdin-enabled arg cannot receive a literal `-` as its value, since the
776
+ * token names the source.
777
+ *
778
+ * One command may declare a single exclusive stdin consumer; pass
779
+ * `{ consume: 'broadcast' }` on every input that should share the buffer.
780
+ *
781
+ * @param options - When to read stdin, how to share it, and whether to trim.
317
782
  * @returns The builder (for chaining).
318
783
  *
319
784
  * @example
320
785
  * ```ts
321
786
  * arg.string().describe('Input text').stdin()
322
- * // $ echo "hello" | mycli transform → input = 'hello' (from stdin)
787
+ * // $ echo "hello" | mycli transform → input = 'hello\n' (from stdin)
788
+ * // $ mycli transform - → input reads stdin
323
789
  * // $ mycli transform "hello" → input = 'hello' (from CLI)
790
+ *
791
+ * arg.string().stdin({ when: 'dash' })
792
+ * // only an explicit `-` reads stdin
793
+ *
794
+ * arg.path({ mustExist: true }).stdin({ trim: true })
795
+ * // $ echo ./dist | mycli clean → path = './dist', checked on disk
324
796
  * ```
325
797
  */
326
- stdin(): ArgBuilder<C>;
798
+ stdin(options?: StdinOptions): ArgBuilder<WithoutArgElementEligibility<C>>;
327
799
  /**
328
800
  * Bind to an environment variable.
329
801
  *
330
- * When the arg is not provided on the CLI, the resolver checks this
331
- * env var before falling back to the default value. The env string is
332
- * coerced to the arg's declared kind (passthrough for strings, parsed
802
+ * When the arg is not provided on the CLI or by stdin, the resolver checks
803
+ * this env var before config, prompt, and the default value. The env string
804
+ * is coerced to the arg's declared kind (passthrough for strings, parsed
333
805
  * for numbers, run through `parseFn` for custom args).
334
806
  *
335
- * Resolution order when extra sources are configured: **CLI → stdin → env → default**.
807
+ * Resolution order when extra sources are configured:
808
+ * **CLI → stdin → env → config → prompt → default**.
336
809
  *
337
810
  * Help output shows `[env: VAR]` next to the arg description.
338
811
  *
@@ -350,7 +823,50 @@ declare class ArgBuilder<C extends ArgConfig> {
350
823
  * });
351
824
  * ```
352
825
  */
353
- env(varName: string): ArgBuilder<C>;
826
+ env(varName: string): ArgBuilder<WithoutArgElementEligibility<C>>;
827
+ /**
828
+ * Bind to a dotted config path.
829
+ *
830
+ * The config value is read after CLI, stdin, and env, and is coerced to the
831
+ * arg's declared kind the same way a flag's config value is.
832
+ *
833
+ * @param path - Dotted config key (e.g. `'deploy.region'`).
834
+ * @returns The builder (for chaining).
835
+ *
836
+ * @example
837
+ * ```ts
838
+ * arg.string().config('deploy.region').default('us-east-1')
839
+ * // Config file: { "deploy": { "region": "eu-west-1" } }
840
+ * // $ mycli deploy → region = 'eu-west-1'
841
+ * // $ mycli deploy ap-south-1 → CLI positional wins
842
+ * ```
843
+ */
844
+ config(path: string): ArgBuilder<WithoutArgElementEligibility<C>>;
845
+ /**
846
+ * Attach interactive prompt configuration.
847
+ *
848
+ * When CLI, stdin, env, and config all produce nothing, the prompt engine
849
+ * uses this config to ask the user. In non-interactive contexts the prompt
850
+ * is skipped and resolution falls through to the default or the missing-arg
851
+ * error.
852
+ *
853
+ * The compatible kinds follow the value and the cardinality: a variadic arg
854
+ * takes the `multiselect` a `flag.array()` takes, and every other arg takes
855
+ * what its kind takes on the flag surface.
856
+ *
857
+ * @param config - {@link PromptConfig} describing the interactive prompt.
858
+ * @returns The builder (for chaining).
859
+ *
860
+ * @example
861
+ * ```ts
862
+ * arg.string().prompt({ kind: 'input', message: 'Target:' })
863
+ * // $ mycli deploy → prompts "Target:"
864
+ * // $ mycli deploy production → skips the prompt
865
+ *
866
+ * arg.string().variadic().prompt({ kind: 'multiselect', message: 'Targets:' })
867
+ * ```
868
+ */
869
+ prompt(config: AllowedArgPromptConfig<C>): ArgBuilder<WithoutArgElementEligibility<C>>;
354
870
  /**
355
871
  * Human-readable description shown in help output.
356
872
  *
@@ -366,7 +882,7 @@ declare class ArgBuilder<C extends ArgConfig> {
366
882
  * // <target> Deploy target
367
883
  * ```
368
884
  */
369
- describe(description: string): ArgBuilder<C>;
885
+ describe(description: string): ArgBuilder<WithoutArgElementEligibility<C>>;
370
886
  /**
371
887
  * Mark this arg as deprecated.
372
888
  *
@@ -388,7 +904,7 @@ declare class ArgBuilder<C extends ArgConfig> {
388
904
  * // <target> Deploy target [deprecated: use --target flag instead]
389
905
  * ```
390
906
  */
391
- deprecated(message?: string): ArgBuilder<C>;
907
+ deprecated(message?: string): ArgBuilder<WithoutArgElementEligibility<C>>;
392
908
  /**
393
909
  * Require an integer value. Composes with other numeric constraints.
394
910
  *
@@ -403,7 +919,7 @@ declare class ArgBuilder<C extends ArgConfig> {
403
919
  * ```
404
920
  */
405
921
  int(this: ArgBuilder<C & {
406
- readonly argKind: 'number';
922
+ readonly argKind: "number";
407
923
  }>, value?: boolean): ArgBuilder<C>;
408
924
  /**
409
925
  * Set an inclusive lower bound. Composes with other numeric constraints;
@@ -420,7 +936,7 @@ declare class ArgBuilder<C extends ArgConfig> {
420
936
  * ```
421
937
  */
422
938
  min(this: ArgBuilder<C & {
423
- readonly argKind: 'number';
939
+ readonly argKind: "number";
424
940
  }>, value: number): ArgBuilder<C>;
425
941
  /**
426
942
  * Set an inclusive upper bound. Composes with other numeric constraints;
@@ -435,7 +951,7 @@ declare class ArgBuilder<C extends ArgConfig> {
435
951
  * ```
436
952
  */
437
953
  max(this: ArgBuilder<C & {
438
- readonly argKind: 'number';
954
+ readonly argKind: "number";
439
955
  }>, value: number): ArgBuilder<C>;
440
956
  /**
441
957
  * Require (or, with `false`, allow) a finite value. Finiteness is enforced
@@ -452,20 +968,81 @@ declare class ArgBuilder<C extends ArgConfig> {
452
968
  * ```
453
969
  */
454
970
  finite(this: ArgBuilder<C & {
455
- readonly argKind: 'number';
971
+ readonly argKind: "number";
456
972
  }>, allow?: boolean): ArgBuilder<C>;
973
+ /**
974
+ * Reject empty strings. Composes with other string constraints.
975
+ *
976
+ * @param value - Whether to reject empty strings.
977
+ * @defaultValue `true`
978
+ * @returns The builder (for chaining).
979
+ *
980
+ * @example
981
+ * ```ts
982
+ * arg.string().nonEmpty() // rejects '', accepts 'x'
983
+ * ```
984
+ */
985
+ nonEmpty(this: ArgBuilder<C & {
986
+ readonly argKind: "string";
987
+ }>, value?: boolean): ArgBuilder<C>;
988
+ /**
989
+ * Set an inclusive minimum length (UTF-16 code units). Composes with other
990
+ * string constraints; a later call overrides an earlier `minLength`.
991
+ *
992
+ * @param value - Inclusive minimum length.
993
+ * @returns The builder (for chaining).
994
+ *
995
+ * @example
996
+ * ```ts
997
+ * arg.string().minLength(3) // rejects 'ab', accepts 'abc'
998
+ * ```
999
+ */
1000
+ minLength(this: ArgBuilder<C & {
1001
+ readonly argKind: "string";
1002
+ }>, value: number): ArgBuilder<C>;
1003
+ /**
1004
+ * Set an inclusive maximum length (UTF-16 code units). Composes with other
1005
+ * string constraints; a later call overrides an earlier `maxLength`.
1006
+ *
1007
+ * @param value - Inclusive maximum length.
1008
+ * @returns The builder (for chaining).
1009
+ *
1010
+ * @example
1011
+ * ```ts
1012
+ * arg.string().maxLength(8) // rejects 9+ chars
1013
+ * ```
1014
+ */
1015
+ maxLength(this: ArgBuilder<C & {
1016
+ readonly argKind: "string";
1017
+ }>, value: number): ArgBuilder<C>;
1018
+ /**
1019
+ * Require the value to match a regular expression. Anchor with `^`/`$`
1020
+ * for full-string matching. Composes with other string constraints.
1021
+ *
1022
+ * @param value - Pattern the value must match.
1023
+ * @returns The builder (for chaining).
1024
+ *
1025
+ * @example
1026
+ * ```ts
1027
+ * arg.string().pattern(/^ghp_/) // rejects 'abc', accepts 'ghp_x'
1028
+ * ```
1029
+ */
1030
+ pattern(this: ArgBuilder<C & {
1031
+ readonly argKind: "string";
1032
+ }>, value: RegExp): ArgBuilder<C>;
457
1033
  }
458
1034
  /**
459
1035
  * Arg factory functions — the public API for creating positional arguments.
460
1036
  *
461
1037
  * Each method returns an {@linkcode ArgBuilder} seeded with the correct {@linkcode ArgKind}
462
1038
  * and initial type-level config. Chain modifiers (`.optional()`, `.env()`,
463
- * `.default()`, `.variadic()`, `.stdin()`, `.describe()`, `.deprecated()`) to refine.
1039
+ * `.config()`, `.prompt()`, `.default()`, `.variadic()`, `.stdin()`,
1040
+ * `.describe()`, `.deprecated()`) to refine.
464
1041
  *
465
1042
  * All args are **required** by default. Resolution order when extra
466
- * sources are configured: **CLI → stdin → env → default**.
1043
+ * sources are configured: **CLI → stdin → env → config → prompt → default**.
467
1044
  *
468
- * @example Overview — all three kinds with common modifier patterns
1045
+ * @example Overview of common kinds with common modifier patterns
469
1046
  * ```ts
470
1047
  * command('process')
471
1048
  * // String arg with env fallback
@@ -497,7 +1074,18 @@ declare class ArgBuilder<C extends ArgConfig> {
497
1074
  */
498
1075
  interface ArgFactory {
499
1076
  /**
500
- * String-valued positional argument. Required by default.
1077
+ * String-valued positional argument, with optional string constraints.
1078
+ * Required by default.
1079
+ *
1080
+ * Constraints are enforced at the parse and resolution boundaries, in
1081
+ * fixed order: nonEmpty → minLength → maxLength → pattern. A `.default()`
1082
+ * value is validated against them where the chain declares it. They also
1083
+ * compose via chained methods (`.nonEmpty()`, `.minLength()`,
1084
+ * `.maxLength()`, `.pattern()`), which override values set here.
1085
+ *
1086
+ * @param constraints - Optional string constraints.
1087
+ * @defaultValue `undefined` (no constraints)
1088
+ * @returns A required string {@link ArgBuilder}.
501
1089
  *
502
1090
  * @example
503
1091
  * ```ts
@@ -505,19 +1093,20 @@ interface ArgFactory {
505
1093
  * arg.string().optional() // string | undefined
506
1094
  * arg.string().env('TARGET') // falls back to $TARGET
507
1095
  * arg.string().default('production') // always present
1096
+ * arg.string({ nonEmpty: true }) // rejects ''
1097
+ * arg.string({ pattern: /^ghp_/ }) // token shapes
508
1098
  *
509
1099
  * // In a command:
510
1100
  * command('deploy')
511
1101
  * .arg('target', arg.string().env('DEPLOY_TARGET').describe('Deploy target'))
512
1102
  * ```
513
- *
514
- * @returns A required string {@link ArgBuilder}.
515
1103
  */
516
- string(): ArgBuilder<{
1104
+ string(constraints?: StringConstraints): ArgBuilder<{
517
1105
  readonly valueType: string;
518
- readonly presence: 'required';
1106
+ readonly presence: "required";
519
1107
  readonly variadic: false;
520
- readonly argKind: 'string';
1108
+ readonly argKind: "string";
1109
+ readonly elementEligible: true;
521
1110
  }>;
522
1111
  /**
523
1112
  * Number-valued positional argument. Required by default.
@@ -550,9 +1139,69 @@ interface ArgFactory {
550
1139
  */
551
1140
  number(constraints?: NumberConstraints): ArgBuilder<{
552
1141
  readonly valueType: number;
553
- readonly presence: 'required';
1142
+ readonly presence: "required";
1143
+ readonly variadic: false;
1144
+ readonly argKind: "number";
1145
+ readonly elementEligible: true;
1146
+ }>;
1147
+ /**
1148
+ * Boolean positional argument. Required by default.
1149
+ *
1150
+ * A positional carries no presence semantics, so the token spells the value
1151
+ * out: `true`/`false` or `1`/`0` from argv, and also `yes`/`no` or an empty
1152
+ * string from env, config, stdin, and a prompt.
1153
+ *
1154
+ * @returns A required boolean {@link ArgBuilder}.
1155
+ *
1156
+ * @example
1157
+ * ```ts
1158
+ * command('feature')
1159
+ * .arg('enabled', arg.boolean().describe('Whether the feature is on'))
1160
+ * // $ mycli feature true → enabled = true
1161
+ * // $ mycli feature nope → ParseError: Invalid boolean value 'nope'
1162
+ * ```
1163
+ */
1164
+ boolean(): ArgBuilder<{
1165
+ readonly valueType: boolean;
1166
+ readonly presence: "required";
554
1167
  readonly variadic: false;
555
- readonly argKind: 'number';
1168
+ readonly argKind: "boolean";
1169
+ readonly elementEligible: true;
1170
+ }>;
1171
+ /**
1172
+ * Key-value positional argument. Required by default.
1173
+ *
1174
+ * Consumes `KEY=VALUE` tokens and resolves to a record, split at the
1175
+ * **first** `=`. The non-variadic form reads one token, the variadic form
1176
+ * aggregates the whole tail. Later occurrences of the same key win, which
1177
+ * `.duplicateKeys()` changes. Not promptable.
1178
+ *
1179
+ * An element builder gives each entry value its own codec, constraints, and
1180
+ * checks, so `arg.keyValue(arg.path())` checks every value on disk.
1181
+ *
1182
+ * @param element - {@link ArgBuilder} describing the value of each entry.
1183
+ * @defaultValue an unconstrained string element
1184
+ * @returns A required key-value {@link ArgBuilder} for records of the element type.
1185
+ *
1186
+ * @example
1187
+ * ```ts
1188
+ * command('run')
1189
+ * .arg('vars', arg.keyValue().variadic().describe('Template variables'))
1190
+ * // $ mycli run A=1 B=2 → vars = { A: '1', B: '2' }
1191
+ *
1192
+ * command('scale')
1193
+ * .arg('replicas', arg.keyValue(arg.number().int().min(0)).variadic())
1194
+ * // $ mycli scale web=3 api=2 → replicas = { web: 3, api: 2 }
1195
+ * ```
1196
+ */
1197
+ keyValue<E extends ArgConfig & {
1198
+ readonly elementEligible: true;
1199
+ } = StringArgElementConfig>(element?: ArgBuilder<E>): ArgBuilder<{
1200
+ readonly valueType: Record<string, E["valueType"]>;
1201
+ readonly presence: "required";
1202
+ readonly variadic: false;
1203
+ readonly argKind: "keyValue";
1204
+ readonly elementEligible: false;
556
1205
  }>;
557
1206
  /**
558
1207
  * Enum-valued positional argument. Required by default.
@@ -579,9 +1228,10 @@ interface ArgFactory {
579
1228
  */
580
1229
  enum<const T extends readonly [string, ...string[]]>(values: T): ArgBuilder<{
581
1230
  readonly valueType: T[number];
582
- readonly presence: 'required';
1231
+ readonly presence: "required";
583
1232
  readonly variadic: false;
584
- readonly argKind: 'enum';
1233
+ readonly argKind: "enum";
1234
+ readonly elementEligible: true;
585
1235
  }>;
586
1236
  /**
587
1237
  * Custom positional argument validated by a Standard Schema v1 validator
@@ -604,9 +1254,10 @@ interface ArgFactory {
604
1254
  */
605
1255
  custom<S extends StandardSchemaV1>(schema: S): ArgBuilder<{
606
1256
  readonly valueType: InferStandardOutput<S>;
607
- readonly presence: 'required';
1257
+ readonly presence: "required";
608
1258
  readonly variadic: false;
609
- readonly argKind: 'custom';
1259
+ readonly argKind: "custom";
1260
+ readonly elementEligible: true;
610
1261
  }>;
611
1262
  /**
612
1263
  * Custom-parsed positional argument. Required by default.
@@ -635,9 +1286,127 @@ interface ArgFactory {
635
1286
  */
636
1287
  custom<T>(parseFn: ArgParseFn<T>): ArgBuilder<{
637
1288
  readonly valueType: T;
638
- readonly presence: 'required';
1289
+ readonly presence: "required";
1290
+ readonly variadic: false;
1291
+ readonly argKind: "custom";
1292
+ readonly elementEligible: true;
1293
+ }>;
1294
+ /**
1295
+ * URL-valued positional argument. Parses into a `URL`; invalid URLs are
1296
+ * rejected with an `INVALID_VALUE` error naming the argument.
1297
+ *
1298
+ * @param options - Optional protocol allowlist (without trailing colon).
1299
+ * @returns A required `URL` {@link ArgBuilder}.
1300
+ *
1301
+ * @example
1302
+ * ```ts
1303
+ * arg.url() // any URL
1304
+ * arg.url({ protocols: ['https'] }) // https only
1305
+ *
1306
+ * // In a command:
1307
+ * command('fetch')
1308
+ * .arg('endpoint', arg.url().env('API_URL').describe('Service endpoint'))
1309
+ * ```
1310
+ */
1311
+ url(options?: UrlFlagOptions): ArgBuilder<{
1312
+ readonly valueType: URL;
1313
+ readonly presence: "required";
1314
+ readonly variadic: false;
1315
+ readonly argKind: "custom";
1316
+ readonly elementEligible: true;
1317
+ }>;
1318
+ /**
1319
+ * Path-valued positional argument. The value stays a `string`; optional
1320
+ * filesystem checks run **after resolution** through the runtime adapter,
1321
+ * so CLI, stdin, env, and defaulted values are all validated.
1322
+ *
1323
+ * A variadic path arg checks every value it collects. Help renders a
1324
+ * positional by its own name, so the `'path'` value hint on the schema does
1325
+ * not reach the usage line.
1326
+ *
1327
+ * @param options - Optional existence/type checks. `type` implies
1328
+ * existence unless `mustExist` is explicitly `false`.
1329
+ * @returns A required path-string {@link ArgBuilder}.
1330
+ *
1331
+ * @example
1332
+ * ```ts
1333
+ * arg.path() // any string
1334
+ * arg.path({ mustExist: true }) // rejects missing paths
1335
+ * arg.path({ type: 'directory' }) // must exist and be a directory
1336
+ * arg.path({ type: 'directory', create: true })
1337
+ * // created recursively when missing
1338
+ * ```
1339
+ */
1340
+ path(options?: PathFlagOptions): ArgBuilder<{
1341
+ readonly valueType: string;
1342
+ readonly presence: "required";
639
1343
  readonly variadic: false;
640
- readonly argKind: 'custom';
1344
+ readonly argKind: "string";
1345
+ readonly elementEligible: true;
1346
+ }>;
1347
+ /**
1348
+ * Date-valued positional argument. Accepts strict ISO-8601 (`2026-07-10`,
1349
+ * `2026-07-10T14:30:00Z`) and parses into a `Date`. Lenient `Date.parse`
1350
+ * inputs (`'0'`, `'March 5'`) and calendar-invalid dates (`2026-02-31`)
1351
+ * are rejected.
1352
+ *
1353
+ * Returns `Date` (not `Temporal`) because the supported runtimes do not
1354
+ * all ship Temporal yet; use `arg.custom()` with `Temporal.PlainDate.from`
1355
+ * where the target runtime has it.
1356
+ *
1357
+ * @param options - Optional inclusive `min`/`max` date bounds.
1358
+ * @returns A required `Date` {@link ArgBuilder}.
1359
+ *
1360
+ * @example
1361
+ * ```ts
1362
+ * arg.date()
1363
+ * arg.date({ min: new Date('2020-01-01') })
1364
+ * ```
1365
+ */
1366
+ date(options?: DateFlagOptions): ArgBuilder<{
1367
+ readonly valueType: Date;
1368
+ readonly presence: "required";
1369
+ readonly variadic: false;
1370
+ readonly argKind: "custom";
1371
+ readonly elementEligible: true;
1372
+ }>;
1373
+ /**
1374
+ * Duration positional argument. Accepts `'30s'`, `'5m'`, `'1.5h'`,
1375
+ * `'250ms'`, `'2d'`, compounds like `'1h30m'`, or a bare millisecond
1376
+ * count, and resolves to **milliseconds**.
1377
+ *
1378
+ * @returns A required duration {@link ArgBuilder} in milliseconds.
1379
+ *
1380
+ * @example
1381
+ * ```ts
1382
+ * arg.duration().default(30_000) // `mycli wait 45s` → 45000
1383
+ * ```
1384
+ */
1385
+ duration(): ArgBuilder<{
1386
+ readonly valueType: number;
1387
+ readonly presence: "required";
1388
+ readonly variadic: false;
1389
+ readonly argKind: "custom";
1390
+ readonly elementEligible: true;
1391
+ }>;
1392
+ /**
1393
+ * Byte-size positional argument. Accepts `'512mb'`, `'1.5gb'`, `'64kb'`,
1394
+ * `'100b'` or a bare byte count, and resolves to **bytes**. Units are
1395
+ * binary (`1kb` = 1024) and case-insensitive.
1396
+ *
1397
+ * @returns A required size {@link ArgBuilder} in bytes.
1398
+ *
1399
+ * @example
1400
+ * ```ts
1401
+ * arg.bytes().default(10 * 1024 ** 2) // `mycli split 512kb` → 524288
1402
+ * ```
1403
+ */
1404
+ bytes(): ArgBuilder<{
1405
+ readonly valueType: number;
1406
+ readonly presence: "required";
1407
+ readonly variadic: false;
1408
+ readonly argKind: "custom";
1409
+ readonly elementEligible: true;
641
1410
  }>;
642
1411
  }
643
1412
  /**
@@ -647,12 +1416,21 @@ interface ArgFactory {
647
1416
  * an {@linkcode ArgBuilder}, then chain modifiers and pass the result to
648
1417
  * `command().arg(name, builder)`.
649
1418
  *
650
- * Four kinds are available:
1419
+ * Six base kinds are available:
651
1420
  * - `arg.string()` — raw string (most common)
652
1421
  * - `arg.number()` — parsed to number, errors on NaN
1422
+ * - `arg.boolean()` reads an explicit true/false token
653
1423
  * - `arg.enum(values)` — constrained to listed literals
1424
+ * - `arg.keyValue()` merges `KEY=VALUE` tokens into a record
654
1425
  * - `arg.custom(fn)` — arbitrary parse function, infers return type
655
1426
  *
1427
+ * Five sugar factories build on them, mirroring their flag counterparts:
1428
+ * - `arg.url()` parses to `URL`, with an optional protocol allowlist
1429
+ * - `arg.path()` keeps the string and adds optional filesystem checks
1430
+ * - `arg.date()` parses strict ISO-8601 to `Date`
1431
+ * - `arg.duration()` resolves `'1h30m'` and friends to milliseconds
1432
+ * - `arg.bytes()` resolves `'512mb'` and friends to bytes
1433
+ *
656
1434
  * @example
657
1435
  * ```ts
658
1436
  * import { command, arg } from '@kjanat/dreamcli';
@@ -670,4 +1448,4 @@ interface ArgFactory {
670
1448
  */
671
1449
  declare const arg: ArgFactory;
672
1450
  //#endregion
673
- export { ARG_KINDS, ARG_PRESENCES, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type InferArg, type InferArgs, type ResolvedArgValue, type WithArgPresence, type WithVariadic, arg, createArgSchema };
1451
+ export { ARG_KINDS, ARG_PRESENCES, type AllowedArgPromptConfig, ArgBuilder, type ArgConfig, type ArgDefaultValue, type ArgDefinition, type ArgDefinitionBase, type ArgDefinitionByKind, type ArgDefinitionOverrides, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type BooleanArgDefinition, type CustomArgDefinition, type DuplicateKeys, type EnumArgDefinition, type InferArg, type InferArgs, type KeyValueArgDefinition, type NumberArgDefinition, type PromptConfigByArgKind, type ResolvedArgValue, type SourceSplitBinding, type SplitBinding, type SplitFormat, type SplitOptions, type SplitPolicy, type SplitSetting, type StdinBinding, type StdinConsume, type StdinOptions, type StdinWhen, type StringArgDefinition, type StringArgElementConfig, type WithArgPresence, type WithVariadic, type WithoutArgElementEligibility, arg, createArgSchema };