@kjanat/dreamcli 3.0.0-rc.1 → 3.0.0-rc.10

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 (194) hide show
  1. package/CHANGELOG.md +217 -1
  2. package/dist/core/cli/dispatch.d.mts +6 -5
  3. package/dist/core/cli/dispatch.mjs +205 -1
  4. package/dist/core/cli/help-links.d.mts +0 -1
  5. package/dist/core/cli/help-links.mjs +41 -1
  6. package/dist/core/cli/index.d.mts +81 -8
  7. package/dist/core/cli/index.mjs +945 -1
  8. package/dist/core/cli/planner.d.mts +5 -1
  9. package/dist/core/cli/planner.mjs +300 -1
  10. package/dist/core/cli/plugin.d.mts +1 -1
  11. package/dist/core/cli/plugin.mjs +41 -1
  12. package/dist/core/cli/propagate.d.mts +1 -1
  13. package/dist/core/cli/propagate.mjs +57 -1
  14. package/dist/core/cli/root-help.d.mts +2 -1
  15. package/dist/core/cli/root-help.mjs +226 -4
  16. package/dist/core/cli/root-surface.d.mts +12 -1
  17. package/dist/core/cli/root-surface.mjs +28 -1
  18. package/dist/core/cli/runtime-preflight.d.mts +14 -2
  19. package/dist/core/cli/runtime-preflight.mjs +169 -1
  20. package/dist/core/completion/index.d.mts +0 -1
  21. package/dist/core/completion/index.mjs +90 -1
  22. package/dist/core/completion/shells/bash.d.mts +0 -1
  23. package/dist/core/completion/shells/bash.mjs +308 -3
  24. package/dist/core/completion/shells/fish.d.mts +0 -1
  25. package/dist/core/completion/shells/fish.mjs +162 -2
  26. package/dist/core/completion/shells/powershell.d.mts +0 -1
  27. package/dist/core/completion/shells/powershell.mjs +358 -2
  28. package/dist/core/completion/shells/shared.d.mts +13 -2
  29. package/dist/core/completion/shells/shared.mjs +176 -1
  30. package/dist/core/completion/shells/zsh.d.mts +0 -1
  31. package/dist/core/completion/shells/zsh.mjs +251 -2
  32. package/dist/core/config/index.d.mts +2 -3
  33. package/dist/core/config/index.mjs +246 -1
  34. package/dist/core/config/package-json.d.mts +27 -4
  35. package/dist/core/config/package-json.mjs +386 -3
  36. package/dist/core/errors/index.d.mts +3 -3
  37. package/dist/core/errors/index.mjs +87 -1
  38. package/dist/core/execution/index.d.mts +0 -1
  39. package/dist/core/execution/index.mjs +201 -1
  40. package/dist/core/help/ansi.d.mts +11 -5
  41. package/dist/core/help/ansi.mjs +121 -2
  42. package/dist/core/help/index.d.mts +22 -3
  43. package/dist/core/help/index.mjs +341 -7
  44. package/dist/core/help/theme.d.mts +68 -0
  45. package/dist/core/help/theme.mjs +46 -0
  46. package/dist/core/json-schema/index.d.mts +15 -2
  47. package/dist/core/json-schema/index.mjs +536 -12
  48. package/dist/core/json-schema/meta-descriptions.generated.d.mts +55 -38
  49. package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
  50. package/dist/core/output/activity.d.mts +0 -1
  51. package/dist/core/output/activity.mjs +452 -1
  52. package/dist/core/output/bind.mjs +56 -1
  53. package/dist/core/output/contracts.d.mts +4 -5
  54. package/dist/core/output/contracts.mjs +57 -1
  55. package/dist/core/output/display-value.mjs +32 -1
  56. package/dist/core/output/index.d.mts +21 -1
  57. package/dist/core/output/index.mjs +442 -2
  58. package/dist/core/output/renderers.d.mts +0 -1
  59. package/dist/core/output/renderers.mjs +46 -1
  60. package/dist/core/output/writer.mjs +12 -1
  61. package/dist/core/parse/index.d.mts +40 -7
  62. package/dist/core/parse/index.mjs +727 -1
  63. package/dist/core/prompt/index.d.mts +1 -1
  64. package/dist/core/prompt/index.mjs +348 -6
  65. package/dist/core/resolve/args.d.mts +1 -1
  66. package/dist/core/resolve/args.mjs +105 -1
  67. package/dist/core/resolve/coerce.d.mts +1 -1
  68. package/dist/core/resolve/coerce.mjs +336 -1
  69. package/dist/core/resolve/config.mjs +19 -1
  70. package/dist/core/resolve/contracts.d.mts +9 -4
  71. package/dist/core/resolve/errors.d.mts +0 -1
  72. package/dist/core/resolve/errors.mjs +140 -2
  73. package/dist/core/resolve/flags.d.mts +7 -2
  74. package/dist/core/resolve/flags.mjs +251 -1
  75. package/dist/core/resolve/index.d.mts +2 -2
  76. package/dist/core/resolve/index.mjs +85 -1
  77. package/dist/core/resolve/property.d.mts +4 -2
  78. package/dist/core/resolve/property.mjs +53 -1
  79. package/dist/core/schema/activity.d.mts +31 -11
  80. package/dist/core/schema/arg.d.mts +3 -4
  81. package/dist/core/schema/arg.mjs +463 -1
  82. package/dist/core/schema/command.d.mts +26 -6
  83. package/dist/core/schema/command.mjs +726 -1
  84. package/dist/core/schema/flag.d.mts +485 -19
  85. package/dist/core/schema/flag.mjs +705 -1
  86. package/dist/core/schema/index.d.mts +4 -2
  87. package/dist/core/schema/middleware.d.mts +4 -3
  88. package/dist/core/schema/middleware.mjs +41 -1
  89. package/dist/core/schema/number-constraints.mjs +60 -1
  90. package/dist/core/schema/prompt.d.mts +6 -3
  91. package/dist/core/schema/run.d.mts +20 -1
  92. package/dist/core/schema/string-constraints.d.mts +97 -0
  93. package/dist/core/schema/string-constraints.mjs +69 -0
  94. package/dist/core/schema/value-parsers.d.mts +78 -0
  95. package/dist/core/schema/value-parsers.mjs +142 -0
  96. package/dist/core/schema-dsl/runtime.mjs +271 -2
  97. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  98. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  99. package/dist/core/testkit/index.d.mts +0 -31
  100. package/dist/core/testkit/index.mjs +83 -1
  101. package/dist/index.d.mts +11 -6
  102. package/dist/index.mjs +22 -1
  103. package/dist/runtime/adapter.d.mts +38 -2
  104. package/dist/runtime/adapter.mjs +87 -1
  105. package/dist/runtime/auto.d.mts +2 -3
  106. package/dist/runtime/auto.mjs +45 -1
  107. package/dist/runtime/deno.d.mts +24 -5
  108. package/dist/runtime/deno.mjs +262 -2
  109. package/dist/runtime/detect.mjs +45 -1
  110. package/dist/runtime/index.d.mts +3 -4
  111. package/dist/runtime/node.d.mts +8 -2
  112. package/dist/runtime/node.mjs +220 -2
  113. package/dist/runtime/paths.mjs +48 -1
  114. package/dist/runtime.d.mts +4 -4
  115. package/dist/runtime.mjs +6 -1
  116. package/dist/strings.mjs +22 -1
  117. package/dist/testkit.d.mts +1 -0
  118. package/dist/testkit.mjs +5 -1
  119. package/dist/version.d.mts +7 -3
  120. package/dist/version.mjs +7 -1
  121. package/dreamcli.schema.json +36 -7
  122. package/package.json +45 -42
  123. package/dist/runtime/bun.d.mts +0 -28
  124. package/dist/runtime/bun.mjs +0 -1
  125. package/src/core/cli/dispatch.ts +0 -355
  126. package/src/core/cli/help-links.ts +0 -82
  127. package/src/core/cli/index.ts +0 -1614
  128. package/src/core/cli/planner.ts +0 -656
  129. package/src/core/cli/plugin.ts +0 -117
  130. package/src/core/cli/propagate.ts +0 -97
  131. package/src/core/cli/root-help.ts +0 -342
  132. package/src/core/cli/root-surface.ts +0 -87
  133. package/src/core/cli/runtime-preflight.ts +0 -456
  134. package/src/core/completion/index.ts +0 -138
  135. package/src/core/completion/shells/bash.ts +0 -459
  136. package/src/core/completion/shells/fish.ts +0 -259
  137. package/src/core/completion/shells/powershell.ts +0 -439
  138. package/src/core/completion/shells/shared.ts +0 -310
  139. package/src/core/completion/shells/zsh.ts +0 -381
  140. package/src/core/config/index.ts +0 -417
  141. package/src/core/config/package-json.ts +0 -560
  142. package/src/core/errors/index.ts +0 -193
  143. package/src/core/execution/index.ts +0 -265
  144. package/src/core/help/ansi.ts +0 -144
  145. package/src/core/help/index.ts +0 -563
  146. package/src/core/json-schema/index.ts +0 -910
  147. package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
  148. package/src/core/output/activity.ts +0 -575
  149. package/src/core/output/bind.ts +0 -59
  150. package/src/core/output/contracts.ts +0 -194
  151. package/src/core/output/display-value.ts +0 -48
  152. package/src/core/output/index.ts +0 -704
  153. package/src/core/output/renderers.ts +0 -125
  154. package/src/core/output/writer.ts +0 -46
  155. package/src/core/parse/index.ts +0 -742
  156. package/src/core/prompt/index.ts +0 -623
  157. package/src/core/resolve/args.ts +0 -144
  158. package/src/core/resolve/coerce.ts +0 -500
  159. package/src/core/resolve/config.ts +0 -26
  160. package/src/core/resolve/contracts.ts +0 -135
  161. package/src/core/resolve/errors.ts +0 -227
  162. package/src/core/resolve/flags.ts +0 -269
  163. package/src/core/resolve/index.ts +0 -108
  164. package/src/core/resolve/property.ts +0 -99
  165. package/src/core/schema/activity.ts +0 -240
  166. package/src/core/schema/arg.ts +0 -841
  167. package/src/core/schema/command.ts +0 -1500
  168. package/src/core/schema/flag.ts +0 -917
  169. package/src/core/schema/index.ts +0 -96
  170. package/src/core/schema/middleware.ts +0 -171
  171. package/src/core/schema/number-constraints.ts +0 -153
  172. package/src/core/schema/prompt.ts +0 -171
  173. package/src/core/schema/run.ts +0 -198
  174. package/src/core/schema-dsl/index.ts +0 -109
  175. package/src/core/schema-dsl/parse.ts +0 -262
  176. package/src/core/schema-dsl/runtime.ts +0 -609
  177. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  178. package/src/core/testkit/index.ts +0 -147
  179. package/src/index.ts +0 -181
  180. package/src/runtime/adapter.ts +0 -303
  181. package/src/runtime/auto.ts +0 -86
  182. package/src/runtime/bun.ts +0 -48
  183. package/src/runtime/deno.ts +0 -367
  184. package/src/runtime/detect.ts +0 -105
  185. package/src/runtime/index.ts +0 -21
  186. package/src/runtime/node-builtins.d.ts +0 -27
  187. package/src/runtime/node.ts +0 -289
  188. package/src/runtime/paths.ts +0 -64
  189. package/src/runtime/support.ts +0 -77
  190. package/src/runtime.ts +0 -31
  191. package/src/schema.ts +0 -16
  192. package/src/strings.ts +0 -34
  193. package/src/testkit.ts +0 -25
  194. package/src/version.ts +0 -20
@@ -1,9 +1,10 @@
1
1
  import { NumberConstraints } from "./number-constraints.mjs";
2
2
  import { ConfirmPromptConfig, InputPromptConfig, MultiselectPromptConfig, PROMPT_KINDS, PromptConfig, PromptConfigBase, PromptKind, PromptResult, SelectChoice, SelectPromptConfig } from "./prompt.mjs";
3
-
3
+ import { StringConstraintViolation, StringConstraints } from "./string-constraints.mjs";
4
+ import { DateFlagOptions, UrlFlagOptions } from "./value-parsers.mjs";
4
5
  //#region src/core/schema/flag.d.ts
5
6
  /** All flag presence states as a runtime array. */
6
- declare const FLAG_PRESENCES: readonly ['optional', 'required', 'defaulted'];
7
+ declare const FLAG_PRESENCES: readonly ["optional", "required", "defaulted"];
7
8
  /**
8
9
  * Presence describes whether a flag value is guaranteed to exist when the
9
10
  * action handler runs:
@@ -18,9 +19,9 @@ type FlagPresence = (typeof FLAG_PRESENCES)[number];
18
19
  * Fallback behavior when an optional flag resolves no value from any source.
19
20
  *
20
21
  * Most optional flags resolve to `undefined`; array flags instead resolve to
21
- * an empty array `[]`.
22
+ * an empty array `[]`, and key-value flags to an empty object `{}`.
22
23
  */
23
- type OptionalFallback = 'undefined' | 'empty-array';
24
+ type OptionalFallback = 'undefined' | 'empty-array' | 'empty-object';
24
25
  /**
25
26
  * Compile-time state carried through the builder chain.
26
27
  *
@@ -36,6 +37,16 @@ interface FlagConfig {
36
37
  readonly optionalFallback: OptionalFallback;
37
38
  /** The runtime kind discriminator, mirroring {@link FlagKind}. */
38
39
  readonly flagKind: FlagKind;
40
+ /**
41
+ * Whether this builder may still be passed to `flag.array()` as the
42
+ * element schema.
43
+ *
44
+ * Factories producing element-meaningful kinds start `true`. Flag-level
45
+ * modifiers (`.alias()`, `.env()`, `.prompt()`, `.default()`, …) flip it
46
+ * to `false` — those settings describe the *flag*, are never read from an
47
+ * element schema, and would otherwise be silently ignored.
48
+ */
49
+ readonly elementEligible: boolean;
39
50
  }
40
51
  /**
41
52
  * Advanced type helper used by {@linkcode FlagBuilder} modifiers to replace presence.
@@ -46,6 +57,18 @@ type WithPresence<C extends FlagConfig, P extends FlagPresence> = {
46
57
  readonly presence: P;
47
58
  readonly optionalFallback: C['optionalFallback'];
48
59
  readonly flagKind: C['flagKind'];
60
+ readonly elementEligible: false;
61
+ };
62
+ /**
63
+ * Advanced type helper: marks a builder as no longer usable as an array
64
+ * element (returned by flag-level modifiers whose settings elements ignore).
65
+ */
66
+ type WithoutElementEligibility<C extends FlagConfig> = {
67
+ readonly valueType: C['valueType'];
68
+ readonly presence: C['presence'];
69
+ readonly optionalFallback: C['optionalFallback'];
70
+ readonly flagKind: C['flagKind'];
71
+ readonly elementEligible: false;
49
72
  };
50
73
  /**
51
74
  * Compute the final value type from config — this is what handlers receive.
@@ -54,15 +77,15 @@ type WithPresence<C extends FlagConfig, P extends FlagPresence> = {
54
77
  * inference. Most apps do not need to mention it explicitly.
55
78
  *
56
79
  * - `'optional'` + `'undefined'` fallback → `T | undefined`
57
- * - `'optional'` + `'empty-array'` fallback → `T`
80
+ * - `'optional'` + `'empty-array'` / `'empty-object'` fallback → `T`
58
81
  * - `'required'` → `T`
59
82
  * - `'defaulted'` → `T`
60
83
  */
61
- type ResolvedValue<C extends FlagConfig> = C['presence'] extends 'optional' ? C['optionalFallback'] extends 'empty-array' ? C['valueType'] : C['valueType'] | undefined : C['valueType'];
84
+ type ResolvedValue<C extends FlagConfig> = C['presence'] extends 'optional' ? C['optionalFallback'] extends 'undefined' ? C['valueType'] | undefined : C['valueType'] : C['valueType'];
62
85
  /** Extract the resolved value type from a {@linkcode FlagBuilder}. */
63
86
  type InferFlag<B> = B extends FlagBuilder<infer C extends FlagConfig> ? ResolvedValue<C> : never;
64
87
  /** Extract resolved value types from a record of builders. */
65
- type InferFlags<T extends Record<string, FlagBuilder<FlagConfig>>> = { [K in keyof T]: InferFlag<T[K]> };
88
+ type InferFlags<T extends Record<string, FlagBuilder<FlagConfig>>> = { [K in keyof T]: InferFlag<T[K]>; };
66
89
  /**
67
90
  * Maps a {@linkcode FlagConfig} to the prompt config types that are compatible
68
91
  * with the flag's kind. Prevents compile-time mismatches such as
@@ -74,6 +97,7 @@ type InferFlags<T extends Record<string, FlagBuilder<FlagConfig>>> = { [K in key
74
97
  * - `'enum'` → {@link SelectPromptConfig} | {@link InputPromptConfig}
75
98
  * - `'array'` → {@link MultiselectPromptConfig}
76
99
  * - `'custom'` → all prompt kinds ({@link PromptConfig})
100
+ * - `'count'` / `'keyValue'` → `never` (not promptable)
77
101
  */
78
102
  type PromptConfigByFlagKind = {
79
103
  readonly string: InputPromptConfig | SelectPromptConfig;
@@ -82,10 +106,12 @@ type PromptConfigByFlagKind = {
82
106
  readonly enum: SelectPromptConfig | InputPromptConfig;
83
107
  readonly array: MultiselectPromptConfig;
84
108
  readonly custom: PromptConfig;
109
+ readonly count: never;
110
+ readonly keyValue: never;
85
111
  };
86
112
  type AllowedPromptConfig<C extends FlagConfig> = PromptConfigByFlagKind[C['flagKind']];
87
113
  /** All flag kind discriminators as a runtime array. */
88
- declare const FLAG_KINDS: readonly ['string', 'number', 'boolean', 'enum', 'array', 'custom'];
114
+ declare const FLAG_KINDS: readonly ["string", "number", "boolean", "enum", "array", "custom", "count", "keyValue"];
89
115
  /** Discriminator for the kind of value a flag accepts. */
90
116
  type FlagKind = (typeof FLAG_KINDS)[number];
91
117
  /**
@@ -95,6 +121,35 @@ type FlagKind = (typeof FLAG_KINDS)[number];
95
121
  * value from config files. Narrow inside the function as needed.
96
122
  */
97
123
  type FlagParseFn<T> = (raw: unknown) => T;
124
+ /** Options accepted by `flag.path()`. */
125
+ interface PathFlagOptions {
126
+ /**
127
+ * Reject the value if nothing exists at the path.
128
+ * @defaultValue `false` (`true` when `type` is set)
129
+ */
130
+ readonly mustExist?: boolean;
131
+ /**
132
+ * Require the path to be a file or a directory. Implies existence.
133
+ * @defaultValue `undefined` (any kind)
134
+ */
135
+ readonly type?: 'file' | 'directory';
136
+ }
137
+ /**
138
+ * Filesystem expectations attached by `flag.path()`.
139
+ *
140
+ * Checked after resolution (not during parse) via the runtime adapter, so
141
+ * `src/core` stays free of platform I/O and all sources (CLI, env, config)
142
+ * are validated identically.
143
+ */
144
+ interface PathChecks {
145
+ /** Reject the value if nothing exists at the path. */
146
+ readonly mustExist: boolean;
147
+ /**
148
+ * Require the existing path to be a file or a directory. Implies
149
+ * existence when set.
150
+ */
151
+ readonly type: 'file' | 'directory' | undefined;
152
+ }
98
153
  /** Runtime descriptor for a flag alias. */
99
154
  interface FlagAlias {
100
155
  /** Alias name without `-` / `--` prefix. */
@@ -102,6 +157,38 @@ interface FlagAlias {
102
157
  /** Whether the alias is parser-only and hidden from user-facing surfaces. */
103
158
  readonly hidden: boolean;
104
159
  }
160
+ /**
161
+ * Negation settings for a boolean flag (set by `.negatable()`).
162
+ *
163
+ * The negated spelling and the positive form are two spellings of ONE
164
+ * logical flag: they share duplicate policy, and the last CLI occurrence
165
+ * wins across both. The negated spelling is presence-only — `--no-foo=x`
166
+ * is rejected.
167
+ */
168
+ interface FlagNegation {
169
+ /**
170
+ * Explicit negated spelling without the `--` prefix (e.g. `'no-sandbox'`).
171
+ * `undefined` synthesizes `no-<flagName>` wherever the flag name is known.
172
+ */
173
+ readonly alias: string | undefined;
174
+ /** Hide the negated spelling from help, completions, and suggestions. */
175
+ readonly hidden: boolean;
176
+ }
177
+ /**
178
+ * How repeated CLI occurrences of a singleton flag combine.
179
+ *
180
+ * - `'last'` — last occurrence wins (matches historic behavior)
181
+ * - `'first'` — first occurrence wins; later ones parse but are ignored
182
+ * - `'error'` — a second occurrence is a `ParseError` (`DUPLICATE_FLAG`)
183
+ *
184
+ * Applies to CLI token occurrences only — env/config/prompt/default
185
+ * resolution keeps its precedence semantics and never raises duplicates.
186
+ * Occurrences are counted per *logical* flag: aliases and the negated
187
+ * spelling all count toward the same flag.
188
+ *
189
+ * @defaultValue `'last'`
190
+ */
191
+ type DuplicatePolicy = 'last' | 'first' | 'error';
105
192
  /**
106
193
  * The runtime descriptor stored inside every {@linkcode FlagBuilder}. Consumers (parser,
107
194
  * help generator, resolution chain) read this to understand the flag's shape
@@ -131,8 +218,44 @@ interface FlagSchema {
131
218
  * `true`, so `Infinity` is rejected even when no constraints object is set.
132
219
  */
133
220
  readonly numberConstraints: NumberConstraints | undefined;
221
+ /**
222
+ * String constraints when `kind === 'string'` (`undefined` otherwise).
223
+ *
224
+ * Enforced at the parse and resolution boundaries, in fixed order:
225
+ * nonEmpty → minLength → maxLength → pattern.
226
+ */
227
+ readonly stringConstraints: StringConstraints | undefined;
134
228
  /** Element schema when `kind === 'array'`. */
135
229
  readonly elementSchema: FlagSchema | undefined;
230
+ /**
231
+ * Value separator when `kind === 'array'` (`undefined` otherwise).
232
+ *
233
+ * When set, each CLI occurrence is split on this separator before element
234
+ * coercion, so `--tag a,b --tag c` yields `['a', 'b', 'c']`. Env and
235
+ * config string values use this separator too (default `','`).
236
+ */
237
+ readonly separator: string | undefined;
238
+ /**
239
+ * Deduplicate resolved array values when `kind === 'array'`.
240
+ *
241
+ * Applied after all sources resolve, preserving first-seen order.
242
+ * Uses `SameValueZero` semantics (like `Set`).
243
+ */
244
+ readonly unique: boolean;
245
+ /**
246
+ * Filesystem checks for path-valued flags (set by `flag.path()`).
247
+ *
248
+ * Validated after resolution through the runtime adapter.
249
+ */
250
+ readonly pathChecks: PathChecks | undefined;
251
+ /**
252
+ * Help placeholder label (e.g. `'url'` renders as `<url>`).
253
+ *
254
+ * Set by the sugar factories (`flag.url()`, `flag.date()`, …) so help
255
+ * output names the expected value shape; `undefined` falls back to the
256
+ * kind-derived hint.
257
+ */
258
+ readonly valueHint: string | undefined;
136
259
  /** Interactive prompt configuration for v0.3+ resolution. */
137
260
  readonly prompt: PromptConfig | undefined;
138
261
  /** Custom parse function (only when `kind === 'custom'`). */
@@ -158,6 +281,17 @@ interface FlagSchema {
158
281
  * @defaultValue `false`
159
282
  */
160
283
  readonly propagate: boolean;
284
+ /**
285
+ * Negation settings when `kind === 'boolean'` and `.negatable()` was
286
+ * called (`undefined` otherwise). See {@link FlagNegation}.
287
+ */
288
+ readonly negation: FlagNegation | undefined;
289
+ /**
290
+ * Duplicate policy for repeated CLI occurrences. See {@link DuplicatePolicy}.
291
+ *
292
+ * @defaultValue `'last'`
293
+ */
294
+ readonly duplicates: DuplicatePolicy;
161
295
  }
162
296
  /**
163
297
  * Low-level overrides accepted by {@link createSchema}.
@@ -193,6 +327,18 @@ declare function getFlagAliasNames(schema: FlagSchema, options?: {
193
327
  readonly includeHidden?: boolean;
194
328
  readonly kind?: 'all' | 'short' | 'long';
195
329
  }): readonly string[];
330
+ /**
331
+ * Effective negated spelling for a flag, or `undefined` when not negatable.
332
+ *
333
+ * The builder cannot know its flag name, so a default (`no-<name>`) is
334
+ * synthesized here — everywhere the canonical name is known (parser, help,
335
+ * completions, collision validation).
336
+ *
337
+ * @param name - Canonical flag name.
338
+ * @param schema - Flag schema (read for {@link FlagNegation}).
339
+ * @returns The negated spelling without the `--` prefix.
340
+ */
341
+ declare function getFlagNegatedName(name: string, schema: FlagSchema): string | undefined;
196
342
  /**
197
343
  * Create a raw {@link FlagSchema} object with sensible defaults.
198
344
  *
@@ -303,7 +449,7 @@ declare class FlagBuilder<C extends FlagConfig> {
303
449
  */
304
450
  alias(name: string, options?: {
305
451
  hidden?: boolean;
306
- }): FlagBuilder<C>;
452
+ }): FlagBuilder<WithoutElementEligibility<C>>;
307
453
  /**
308
454
  * Bind to an environment variable (resolved in v0.2+).
309
455
  *
@@ -318,7 +464,7 @@ declare class FlagBuilder<C extends FlagConfig> {
318
464
  * // $ mycli request --api-key sk-456 → apiKey = 'sk-456' (CLI wins)
319
465
  * ```
320
466
  */
321
- env(varName: string): FlagBuilder<C>;
467
+ env(varName: string): FlagBuilder<WithoutElementEligibility<C>>;
322
468
  /**
323
469
  * Bind to a dotted config path (resolved in v0.2+).
324
470
  *
@@ -335,14 +481,14 @@ declare class FlagBuilder<C extends FlagConfig> {
335
481
  * // # → CLI flag wins
336
482
  * ```
337
483
  */
338
- config(path: string): FlagBuilder<C>;
484
+ config(path: string): FlagBuilder<WithoutElementEligibility<C>>;
339
485
  /**
340
486
  * Human-readable description shown in help output.
341
487
  *
342
488
  * @param description - Text displayed next to the flag in `--help`.
343
489
  * @returns The builder (for chaining).
344
490
  */
345
- describe(description: string): FlagBuilder<C>;
491
+ describe(description: string): FlagBuilder<WithoutElementEligibility<C>>;
346
492
  /**
347
493
  * Attach interactive prompt configuration for v0.3+ resolution.
348
494
  *
@@ -362,7 +508,7 @@ declare class FlagBuilder<C extends FlagConfig> {
362
508
  * // $ mycli init --name foo → skips prompt, uses CLI value
363
509
  * ```
364
510
  */
365
- prompt(config: AllowedPromptConfig<C>): FlagBuilder<C>;
511
+ prompt(config: AllowedPromptConfig<C>): FlagBuilder<WithoutElementEligibility<C>>;
366
512
  /**
367
513
  * Mark this flag as deprecated.
368
514
  *
@@ -382,7 +528,7 @@ declare class FlagBuilder<C extends FlagConfig> {
382
528
  * // ⚠ --dest is deprecated: Use --target instead
383
529
  * ```
384
530
  */
385
- deprecated(message?: string): FlagBuilder<C>;
531
+ deprecated(message?: string): FlagBuilder<WithoutElementEligibility<C>>;
386
532
  /**
387
533
  * Mark this flag as propagated to subcommands.
388
534
  *
@@ -404,7 +550,7 @@ declare class FlagBuilder<C extends FlagConfig> {
404
550
  * // # → same, inherited from parent
405
551
  * ```
406
552
  */
407
- propagate(): FlagBuilder<C>;
553
+ propagate(): FlagBuilder<WithoutElementEligibility<C>>;
408
554
  /**
409
555
  * Require an integer value. Composes with other numeric constraints.
410
556
  *
@@ -470,6 +616,150 @@ declare class FlagBuilder<C extends FlagConfig> {
470
616
  finite(this: FlagBuilder<C & {
471
617
  readonly flagKind: 'number';
472
618
  }>, allow?: boolean): FlagBuilder<C>;
619
+ /**
620
+ * Reject empty strings. Composes with other string constraints.
621
+ *
622
+ * @param value - Whether to reject empty strings.
623
+ * @defaultValue `true`
624
+ * @returns The builder (for chaining).
625
+ *
626
+ * @example
627
+ * ```ts
628
+ * flag.string().nonEmpty() // rejects '', accepts 'x'
629
+ * ```
630
+ */
631
+ nonEmpty(this: FlagBuilder<C & {
632
+ readonly flagKind: 'string';
633
+ }>, value?: boolean): FlagBuilder<C>;
634
+ /**
635
+ * Set an inclusive minimum length (UTF-16 code units). Composes with other
636
+ * string constraints; a later call overrides an earlier `minLength`.
637
+ *
638
+ * @param value - Inclusive minimum length.
639
+ * @returns The builder (for chaining).
640
+ *
641
+ * @example
642
+ * ```ts
643
+ * flag.string().minLength(3) // rejects 'ab', accepts 'abc'
644
+ * ```
645
+ */
646
+ minLength(this: FlagBuilder<C & {
647
+ readonly flagKind: 'string';
648
+ }>, value: number): FlagBuilder<C>;
649
+ /**
650
+ * Set an inclusive maximum length (UTF-16 code units). Composes with other
651
+ * string constraints; a later call overrides an earlier `maxLength`.
652
+ *
653
+ * @param value - Inclusive maximum length.
654
+ * @returns The builder (for chaining).
655
+ *
656
+ * @example
657
+ * ```ts
658
+ * flag.string().maxLength(8) // rejects 9+ chars
659
+ * ```
660
+ */
661
+ maxLength(this: FlagBuilder<C & {
662
+ readonly flagKind: 'string';
663
+ }>, value: number): FlagBuilder<C>;
664
+ /**
665
+ * Require the value to match a regular expression. Anchor with `^`/`$`
666
+ * for full-string matching. Composes with other string constraints.
667
+ *
668
+ * @param value - Pattern the value must match.
669
+ * @returns The builder (for chaining).
670
+ *
671
+ * @example
672
+ * ```ts
673
+ * flag.string().pattern(/^ghp_/) // rejects 'abc', accepts 'ghp_x'
674
+ * ```
675
+ */
676
+ pattern(this: FlagBuilder<C & {
677
+ readonly flagKind: 'string';
678
+ }>, value: RegExp): FlagBuilder<C>;
679
+ /**
680
+ * Split each CLI occurrence on a separator before element coercion, so
681
+ * `--tag a,b --tag c` resolves to `['a', 'b', 'c']`. Elements are coerced
682
+ * (and rejected) individually with the element schema's own error format.
683
+ *
684
+ * Env and config string values are split on the same separator (their
685
+ * default split is `','` even without this modifier).
686
+ *
687
+ * @param value - Separator string (e.g. `','`).
688
+ * @returns The builder (for chaining).
689
+ *
690
+ * @example
691
+ * ```ts
692
+ * flag.array(flag.enum(['us', 'eu', 'ap'])).separator(',')
693
+ * // --region us,eu --region ap → ['us', 'eu', 'ap']
694
+ * ```
695
+ */
696
+ separator(this: FlagBuilder<C & {
697
+ readonly flagKind: 'array';
698
+ }>, value: string): FlagBuilder<C>;
699
+ /**
700
+ * Deduplicate the resolved array, preserving first-seen order. Applied
701
+ * after all sources resolve, using `SameValueZero` semantics (like `Set`).
702
+ *
703
+ * @param value - Whether to deduplicate.
704
+ * @defaultValue `true`
705
+ * @returns The builder (for chaining).
706
+ *
707
+ * @example
708
+ * ```ts
709
+ * flag.array(flag.string()).separator(',').unique()
710
+ * // --tag a,a --tag a → ['a']
711
+ * ```
712
+ */
713
+ unique(this: FlagBuilder<C & {
714
+ readonly flagKind: 'array';
715
+ }>, value?: boolean): FlagBuilder<C>;
716
+ /**
717
+ * Accept a negated spelling (`--no-<name>`) that sets the flag to `false`.
718
+ *
719
+ * Both spellings are ONE logical flag: the last CLI occurrence wins across
720
+ * them, and they share the duplicate policy. The negated spelling is
721
+ * presence-only — `--no-<name>=true` is rejected. Help renders the flag as
722
+ * `--[no-]<name>` (or lists a custom alias); env/config/prompt/default
723
+ * resolution is unaffected.
724
+ *
725
+ * @param options - Optional custom spelling (`alias`, without `--`) and
726
+ * `hidden` to keep the negated spelling parseable but unadvertised.
727
+ * @returns The builder (for chaining).
728
+ *
729
+ * @example
730
+ * ```ts
731
+ * flag.boolean().default(true).negatable()
732
+ * // $ mycli build --no-sandbox → sandbox = false
733
+ * // $ mycli build --sandbox → sandbox = true
734
+ * ```
735
+ */
736
+ negatable(this: FlagBuilder<C & {
737
+ readonly flagKind: 'boolean';
738
+ }>, options?: {
739
+ alias?: string;
740
+ hidden?: boolean;
741
+ }): FlagBuilder<WithoutElementEligibility<C>>;
742
+ /**
743
+ * Set how repeated CLI occurrences of this flag combine.
744
+ *
745
+ * Counted per logical flag — aliases and the negated spelling all count
746
+ * toward the same flag. CLI tokens only: env/config/prompt/default
747
+ * resolution keeps its precedence semantics. Not available on `array`,
748
+ * `count`, or `keyValue` flags, which inherently accumulate.
749
+ *
750
+ * @param policy - `'last'` (default), `'first'`, or `'error'`.
751
+ * @returns The builder (for chaining).
752
+ *
753
+ * @example
754
+ * ```ts
755
+ * flag.enum(['session', 'same-dir', 'worktree']).duplicates('error')
756
+ * // $ mycli run --spawn session --spawn worktree
757
+ * // # → Error: Flag --spawn may only be specified once
758
+ * ```
759
+ */
760
+ duplicates(this: FlagBuilder<C & {
761
+ readonly flagKind: 'boolean' | 'string' | 'number' | 'enum' | 'custom';
762
+ }>, policy: DuplicatePolicy): FlagBuilder<WithoutElementEligibility<C>>;
473
763
  }
474
764
  /**
475
765
  * Factory that creates {@link FlagBuilder} instances seeded with the correct
@@ -477,15 +767,30 @@ declare class FlagBuilder<C extends FlagConfig> {
477
767
  */
478
768
  interface FlagFactory {
479
769
  /**
480
- * String-valued flag.
770
+ * String-valued flag, with optional string constraints.
481
771
  *
772
+ * Constraints are enforced at the parse and resolution boundaries, in
773
+ * fixed order: nonEmpty → minLength → maxLength → pattern. They also
774
+ * compose via chained methods (`.nonEmpty()`, `.minLength()`,
775
+ * `.maxLength()`, `.pattern()`), which override values set here.
776
+ *
777
+ * @param constraints - Optional string constraints.
778
+ * @defaultValue `undefined` (no constraints)
482
779
  * @returns A {@link FlagBuilder} for `string` values.
780
+ *
781
+ * @example
782
+ * ```ts
783
+ * flag.string() // any string
784
+ * flag.string({ nonEmpty: true }) // rejects ''
785
+ * flag.string({ pattern: /^ghp_/ }) // token shapes
786
+ * ```
483
787
  */
484
- string(): FlagBuilder<{
788
+ string(constraints?: StringConstraints): FlagBuilder<{
485
789
  readonly valueType: string;
486
790
  readonly presence: 'optional';
487
791
  readonly optionalFallback: 'undefined';
488
792
  readonly flagKind: 'string';
793
+ readonly elementEligible: true;
489
794
  }>;
490
795
  /**
491
796
  * Number-valued flag, with optional numeric constraints.
@@ -514,6 +819,7 @@ interface FlagFactory {
514
819
  readonly presence: 'optional';
515
820
  readonly optionalFallback: 'undefined';
516
821
  readonly flagKind: 'number';
822
+ readonly elementEligible: true;
517
823
  }>;
518
824
  /**
519
825
  * Boolean flag. Implicitly defaults to `false` — the only flag kind where
@@ -526,6 +832,7 @@ interface FlagFactory {
526
832
  readonly presence: 'defaulted';
527
833
  readonly optionalFallback: 'undefined';
528
834
  readonly flagKind: 'boolean';
835
+ readonly elementEligible: true;
529
836
  }>;
530
837
  /**
531
838
  * Enum flag with literal type inference.
@@ -547,6 +854,7 @@ interface FlagFactory {
547
854
  readonly presence: 'optional';
548
855
  readonly optionalFallback: 'undefined';
549
856
  readonly flagKind: 'enum';
857
+ readonly elementEligible: true;
550
858
  }>;
551
859
  /**
552
860
  * Array flag — collects multiple values of the same element type.
@@ -560,11 +868,14 @@ interface FlagFactory {
560
868
  * @param element - {@link FlagBuilder} describing the element type.
561
869
  * @returns A {@link FlagBuilder} for arrays of the element type.
562
870
  */
563
- array<E extends FlagConfig>(element: FlagBuilder<E>): FlagBuilder<{
871
+ array<E extends FlagConfig & {
872
+ readonly elementEligible: true;
873
+ }>(element: FlagBuilder<E>): FlagBuilder<{
564
874
  readonly valueType: E['valueType'][];
565
875
  readonly presence: 'optional';
566
876
  readonly optionalFallback: 'empty-array';
567
877
  readonly flagKind: 'array';
878
+ readonly elementEligible: false;
568
879
  }>;
569
880
  /**
570
881
  * Custom-parsed flag. The parse function receives the raw value and must
@@ -600,6 +911,161 @@ interface FlagFactory {
600
911
  readonly presence: 'optional';
601
912
  readonly optionalFallback: 'undefined';
602
913
  readonly flagKind: 'custom';
914
+ readonly elementEligible: true;
915
+ }>;
916
+ /**
917
+ * URL-valued flag. Parses into a `URL`; invalid URLs are rejected with an
918
+ * `INVALID_VALUE` error naming the flag.
919
+ *
920
+ * @param options - Optional protocol allowlist (without trailing colon).
921
+ * @returns A {@link FlagBuilder} for `URL` values.
922
+ *
923
+ * @example
924
+ * ```ts
925
+ * flag.url() // any URL
926
+ * flag.url({ protocols: ['https'] }) // https only
927
+ * ```
928
+ */
929
+ url(options?: UrlFlagOptions): FlagBuilder<{
930
+ readonly valueType: URL;
931
+ readonly presence: 'optional';
932
+ readonly optionalFallback: 'undefined';
933
+ readonly flagKind: 'custom';
934
+ readonly elementEligible: true;
935
+ }>;
936
+ /**
937
+ * Path-valued flag. The value stays a `string`; optional filesystem
938
+ * checks run **after resolution** through the runtime adapter, so CLI,
939
+ * env, and config values are validated identically.
940
+ *
941
+ * @param options - Optional existence/type checks. `type` implies
942
+ * existence.
943
+ * @returns A {@link FlagBuilder} for path strings.
944
+ *
945
+ * @example
946
+ * ```ts
947
+ * flag.path() // any string, help shows <path>
948
+ * flag.path({ mustExist: true }) // rejects missing paths
949
+ * flag.path({ type: 'directory' }) // must exist and be a directory
950
+ * ```
951
+ */
952
+ path(options?: PathFlagOptions): FlagBuilder<{
953
+ readonly valueType: string;
954
+ readonly presence: 'optional';
955
+ readonly optionalFallback: 'undefined';
956
+ readonly flagKind: 'string';
957
+ readonly elementEligible: false;
958
+ }>;
959
+ /**
960
+ * Date-valued flag. Accepts strict ISO-8601 (`2026-07-10`,
961
+ * `2026-07-10T14:30:00Z`) and parses into a `Date`. Lenient `Date.parse`
962
+ * inputs (`'0'`, `'March 5'`) and calendar-invalid dates (`2026-02-31`)
963
+ * are rejected.
964
+ *
965
+ * Returns `Date` (not `Temporal`) because the supported runtimes do not
966
+ * all ship Temporal yet; use `flag.custom()` with `Temporal.PlainDate.from`
967
+ * where the target runtime has it.
968
+ *
969
+ * @param options - Optional inclusive `min`/`max` date bounds.
970
+ * @returns A {@link FlagBuilder} for `Date` values.
971
+ *
972
+ * @example
973
+ * ```ts
974
+ * flag.date()
975
+ * flag.date({ min: new Date('2020-01-01') })
976
+ * ```
977
+ */
978
+ date(options?: DateFlagOptions): FlagBuilder<{
979
+ readonly valueType: Date;
980
+ readonly presence: 'optional';
981
+ readonly optionalFallback: 'undefined';
982
+ readonly flagKind: 'custom';
983
+ readonly elementEligible: true;
984
+ }>;
985
+ /**
986
+ * Duration flag. Accepts `'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`,
987
+ * compounds like `'1h30m'`, or a bare millisecond count, and resolves to
988
+ * **milliseconds**.
989
+ *
990
+ * @returns A {@link FlagBuilder} for duration values in milliseconds.
991
+ *
992
+ * @example
993
+ * ```ts
994
+ * flag.duration().default(30_000) // --timeout 45s → 45000
995
+ * ```
996
+ */
997
+ duration(): FlagBuilder<{
998
+ readonly valueType: number;
999
+ readonly presence: 'optional';
1000
+ readonly optionalFallback: 'undefined';
1001
+ readonly flagKind: 'custom';
1002
+ readonly elementEligible: true;
1003
+ }>;
1004
+ /**
1005
+ * Byte-size flag. Accepts `'512mb'`, `'1.5gb'`, `'64kb'`, `'100b'` or a
1006
+ * bare byte count, and resolves to **bytes**. Units are binary
1007
+ * (`1kb` = 1024) and case-insensitive.
1008
+ *
1009
+ * @returns A {@link FlagBuilder} for sizes in bytes.
1010
+ *
1011
+ * @example
1012
+ * ```ts
1013
+ * flag.bytes().default(10 * 1024 ** 2) // --max-size 512kb → 524288
1014
+ * ```
1015
+ */
1016
+ bytes(): FlagBuilder<{
1017
+ readonly valueType: number;
1018
+ readonly presence: 'optional';
1019
+ readonly optionalFallback: 'undefined';
1020
+ readonly flagKind: 'custom';
1021
+ readonly elementEligible: true;
1022
+ }>;
1023
+ /**
1024
+ * Count flag — resolves to how many times the flag appears. `-vvv`,
1025
+ * `-v -v -v`, and `--verbose --verbose --verbose` all yield `3`; absent
1026
+ * yields `0`. An explicit value (`--verbose=2`, env, config) sets the
1027
+ * count directly.
1028
+ *
1029
+ * Not promptable.
1030
+ *
1031
+ * @returns A {@link FlagBuilder} for occurrence counts (defaulted to `0`).
1032
+ *
1033
+ * @example
1034
+ * ```ts
1035
+ * flag.count().alias('v').describe('Increase verbosity')
1036
+ * // $ mycli build -vv → verbose = 2
1037
+ * ```
1038
+ */
1039
+ count(): FlagBuilder<{
1040
+ readonly valueType: number;
1041
+ readonly presence: 'defaulted';
1042
+ readonly optionalFallback: 'undefined';
1043
+ readonly flagKind: 'count';
1044
+ readonly elementEligible: false;
1045
+ }>;
1046
+ /**
1047
+ * Key-value flag — repeated `KEY=VALUE` occurrences merge into a
1048
+ * `Record<string, string>` (docker/kubectl `--env` style). The value is
1049
+ * split at the **first** `=`, so `--env A=b=c` yields `{ A: 'b=c' }`.
1050
+ * Later occurrences of the same key win. Absent resolves to `{}`.
1051
+ *
1052
+ * Env vars accept separator-joined pairs (`A=1,B=2`); config files accept
1053
+ * a plain object. Not promptable.
1054
+ *
1055
+ * @returns A {@link FlagBuilder} for `Record<string, string>` values.
1056
+ *
1057
+ * @example
1058
+ * ```ts
1059
+ * flag.keyValue().alias('e').describe('Environment variables')
1060
+ * // $ mycli run -e A=1 -e B=2 → env = { A: '1', B: '2' }
1061
+ * ```
1062
+ */
1063
+ keyValue(): FlagBuilder<{
1064
+ readonly valueType: Record<string, string>;
1065
+ readonly presence: 'optional';
1066
+ readonly optionalFallback: 'empty-object';
1067
+ readonly flagKind: 'keyValue';
1068
+ readonly elementEligible: false;
603
1069
  }>;
604
1070
  }
605
1071
  /**
@@ -608,4 +1074,4 @@ interface FlagFactory {
608
1074
  */
609
1075
  declare const flag: FlagFactory;
610
1076
  //#endregion
611
- export { type AllowedPromptConfig, type ConfirmPromptConfig, FLAG_KINDS, FLAG_PRESENCES, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FlagSchemaOverrides, type InferFlag, type InferFlags, type InputPromptConfig, type MultiselectPromptConfig, type OptionalFallback, PROMPT_KINDS, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type ResolvedValue, type SelectChoice, type SelectPromptConfig, type WithPresence, createSchema, flag, getFlagAliasNames, normalizeFlagAlias, normalizeFlagAliases };
1077
+ 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 PromptKind, type PromptResult, type ResolvedValue, type SelectChoice, type SelectPromptConfig, type StringConstraintViolation, type StringConstraints, type UrlFlagOptions, type WithPresence, createSchema, flag, getFlagAliasNames, getFlagNegatedName, normalizeFlagAlias, normalizeFlagAliases };