@kjanat/dreamcli 3.0.0-rc.6 → 3.0.0-rc.8

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 (94) hide show
  1. package/CHANGELOG.md +94 -1
  2. package/dist/core/cli/dispatch.d.mts +6 -5
  3. package/dist/core/cli/dispatch.mjs +7 -5
  4. package/dist/core/cli/help-links.d.mts +0 -1
  5. package/dist/core/cli/index.d.mts +27 -2
  6. package/dist/core/cli/index.mjs +28 -14
  7. package/dist/core/cli/planner.d.mts +3 -1
  8. package/dist/core/cli/planner.mjs +12 -12
  9. package/dist/core/cli/plugin.d.mts +1 -1
  10. package/dist/core/cli/propagate.d.mts +1 -1
  11. package/dist/core/cli/root-help.d.mts +0 -1
  12. package/dist/core/cli/root-help.mjs +38 -21
  13. package/dist/core/cli/root-surface.d.mts +0 -1
  14. package/dist/core/cli/runtime-preflight.d.mts +12 -2
  15. package/dist/core/cli/runtime-preflight.mjs +5 -4
  16. package/dist/core/completion/index.d.mts +0 -1
  17. package/dist/core/completion/index.mjs +1 -1
  18. package/dist/core/completion/shells/bash.d.mts +0 -1
  19. package/dist/core/completion/shells/bash.mjs +8 -4
  20. package/dist/core/completion/shells/fish.d.mts +0 -1
  21. package/dist/core/completion/shells/fish.mjs +6 -3
  22. package/dist/core/completion/shells/powershell.d.mts +0 -1
  23. package/dist/core/completion/shells/powershell.mjs +10 -5
  24. package/dist/core/completion/shells/shared.d.mts +13 -2
  25. package/dist/core/completion/shells/shared.mjs +24 -2
  26. package/dist/core/completion/shells/zsh.d.mts +0 -1
  27. package/dist/core/completion/shells/zsh.mjs +11 -4
  28. package/dist/core/config/index.d.mts +2 -3
  29. package/dist/core/config/index.mjs +2 -2
  30. package/dist/core/config/package-json.d.mts +27 -4
  31. package/dist/core/config/package-json.mjs +20 -19
  32. package/dist/core/errors/index.d.mts +1 -1
  33. package/dist/core/execution/index.d.mts +0 -1
  34. package/dist/core/execution/index.mjs +8 -4
  35. package/dist/core/help/ansi.mjs +3 -2
  36. package/dist/core/help/index.d.mts +22 -3
  37. package/dist/core/help/index.mjs +65 -53
  38. package/dist/core/help/theme.d.mts +68 -0
  39. package/dist/core/help/theme.mjs +46 -0
  40. package/dist/core/json-schema/index.d.mts +1 -1
  41. package/dist/core/json-schema/index.mjs +39 -8
  42. package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
  43. package/dist/core/json-schema/meta-descriptions.generated.mjs +14 -5
  44. package/dist/core/output/activity.d.mts +0 -1
  45. package/dist/core/output/contracts.d.mts +0 -1
  46. package/dist/core/output/contracts.mjs +1 -1
  47. package/dist/core/output/index.d.mts +0 -1
  48. package/dist/core/output/index.mjs +1 -1
  49. package/dist/core/output/renderers.d.mts +0 -1
  50. package/dist/core/parse/index.d.mts +40 -7
  51. package/dist/core/parse/index.mjs +209 -40
  52. package/dist/core/prompt/index.d.mts +1 -0
  53. package/dist/core/resolve/args.d.mts +1 -1
  54. package/dist/core/resolve/coerce.d.mts +1 -1
  55. package/dist/core/resolve/coerce.mjs +71 -14
  56. package/dist/core/resolve/contracts.d.mts +7 -2
  57. package/dist/core/resolve/errors.d.mts +0 -1
  58. package/dist/core/resolve/flags.d.mts +7 -2
  59. package/dist/core/resolve/flags.mjs +61 -6
  60. package/dist/core/resolve/index.d.mts +2 -2
  61. package/dist/core/resolve/index.mjs +1 -1
  62. package/dist/core/resolve/property.d.mts +3 -0
  63. package/dist/core/resolve/property.mjs +11 -3
  64. package/dist/core/schema/activity.d.mts +31 -11
  65. package/dist/core/schema/arg.d.mts +1 -2
  66. package/dist/core/schema/command.d.mts +8 -6
  67. package/dist/core/schema/command.mjs +26 -12
  68. package/dist/core/schema/flag.d.mts +439 -10
  69. package/dist/core/schema/flag.mjs +255 -3
  70. package/dist/core/schema/index.d.mts +4 -2
  71. package/dist/core/schema/middleware.d.mts +4 -3
  72. package/dist/core/schema/prompt.d.mts +5 -2
  73. package/dist/core/schema/run.d.mts +20 -1
  74. package/dist/core/schema/string-constraints.d.mts +97 -0
  75. package/dist/core/schema/string-constraints.mjs +69 -0
  76. package/dist/core/schema/value-parsers.d.mts +78 -0
  77. package/dist/core/schema/value-parsers.mjs +142 -0
  78. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  79. package/dist/core/testkit/index.d.mts +0 -31
  80. package/dist/core/testkit/index.mjs +1 -1
  81. package/dist/index.d.mts +8 -4
  82. package/dist/index.mjs +7 -7
  83. package/dist/runtime/adapter.d.mts +22 -1
  84. package/dist/runtime/adapter.mjs +3 -0
  85. package/dist/runtime/auto.d.mts +0 -1
  86. package/dist/runtime/deno.d.mts +15 -5
  87. package/dist/runtime/deno.mjs +9 -0
  88. package/dist/runtime/node.d.mts +2 -2
  89. package/dist/runtime/node.mjs +10 -0
  90. package/dist/runtime.d.mts +1 -0
  91. package/dist/testkit.d.mts +1 -0
  92. package/dist/version.mjs +2 -2
  93. package/dreamcli.schema.json +35 -6
  94. package/package.json +12 -13
@@ -1,6 +1,7 @@
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
7
  declare const FLAG_PRESENCES: readonly ['optional', 'required', 'defaulted'];
@@ -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
  *
@@ -54,15 +55,15 @@ type WithPresence<C extends FlagConfig, P extends FlagPresence> = {
54
55
  * inference. Most apps do not need to mention it explicitly.
55
56
  *
56
57
  * - `'optional'` + `'undefined'` fallback → `T | undefined`
57
- * - `'optional'` + `'empty-array'` fallback → `T`
58
+ * - `'optional'` + `'empty-array'` / `'empty-object'` fallback → `T`
58
59
  * - `'required'` → `T`
59
60
  * - `'defaulted'` → `T`
60
61
  */
61
- type ResolvedValue<C extends FlagConfig> = C['presence'] extends 'optional' ? C['optionalFallback'] extends 'empty-array' ? C['valueType'] : C['valueType'] | undefined : C['valueType'];
62
+ type ResolvedValue<C extends FlagConfig> = C['presence'] extends 'optional' ? C['optionalFallback'] extends 'undefined' ? C['valueType'] | undefined : C['valueType'] : C['valueType'];
62
63
  /** Extract the resolved value type from a {@linkcode FlagBuilder}. */
63
64
  type InferFlag<B> = B extends FlagBuilder<infer C extends FlagConfig> ? ResolvedValue<C> : never;
64
65
  /** 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]> };
66
+ type InferFlags<T extends Record<string, FlagBuilder<FlagConfig>>> = { [K in keyof T]: InferFlag<T[K]>; };
66
67
  /**
67
68
  * Maps a {@linkcode FlagConfig} to the prompt config types that are compatible
68
69
  * with the flag's kind. Prevents compile-time mismatches such as
@@ -74,6 +75,7 @@ type InferFlags<T extends Record<string, FlagBuilder<FlagConfig>>> = { [K in key
74
75
  * - `'enum'` → {@link SelectPromptConfig} | {@link InputPromptConfig}
75
76
  * - `'array'` → {@link MultiselectPromptConfig}
76
77
  * - `'custom'` → all prompt kinds ({@link PromptConfig})
78
+ * - `'count'` / `'keyValue'` → `never` (not promptable)
77
79
  */
78
80
  type PromptConfigByFlagKind = {
79
81
  readonly string: InputPromptConfig | SelectPromptConfig;
@@ -82,10 +84,12 @@ type PromptConfigByFlagKind = {
82
84
  readonly enum: SelectPromptConfig | InputPromptConfig;
83
85
  readonly array: MultiselectPromptConfig;
84
86
  readonly custom: PromptConfig;
87
+ readonly count: never;
88
+ readonly keyValue: never;
85
89
  };
86
90
  type AllowedPromptConfig<C extends FlagConfig> = PromptConfigByFlagKind[C['flagKind']];
87
91
  /** All flag kind discriminators as a runtime array. */
88
- declare const FLAG_KINDS: readonly ['string', 'number', 'boolean', 'enum', 'array', 'custom'];
92
+ declare const FLAG_KINDS: readonly ['string', 'number', 'boolean', 'enum', 'array', 'custom', 'count', 'keyValue'];
89
93
  /** Discriminator for the kind of value a flag accepts. */
90
94
  type FlagKind = (typeof FLAG_KINDS)[number];
91
95
  /**
@@ -95,6 +99,35 @@ type FlagKind = (typeof FLAG_KINDS)[number];
95
99
  * value from config files. Narrow inside the function as needed.
96
100
  */
97
101
  type FlagParseFn<T> = (raw: unknown) => T;
102
+ /** Options accepted by `flag.path()`. */
103
+ interface PathFlagOptions {
104
+ /**
105
+ * Reject the value if nothing exists at the path.
106
+ * @defaultValue `false` (`true` when `type` is set)
107
+ */
108
+ readonly mustExist?: boolean;
109
+ /**
110
+ * Require the path to be a file or a directory. Implies existence.
111
+ * @defaultValue `undefined` (any kind)
112
+ */
113
+ readonly type?: 'file' | 'directory';
114
+ }
115
+ /**
116
+ * Filesystem expectations attached by `flag.path()`.
117
+ *
118
+ * Checked after resolution (not during parse) via the runtime adapter, so
119
+ * `src/core` stays free of platform I/O and all sources (CLI, env, config)
120
+ * are validated identically.
121
+ */
122
+ interface PathChecks {
123
+ /** Reject the value if nothing exists at the path. */
124
+ readonly mustExist: boolean;
125
+ /**
126
+ * Require the existing path to be a file or a directory. Implies
127
+ * existence when set.
128
+ */
129
+ readonly type: 'file' | 'directory' | undefined;
130
+ }
98
131
  /** Runtime descriptor for a flag alias. */
99
132
  interface FlagAlias {
100
133
  /** Alias name without `-` / `--` prefix. */
@@ -102,6 +135,38 @@ interface FlagAlias {
102
135
  /** Whether the alias is parser-only and hidden from user-facing surfaces. */
103
136
  readonly hidden: boolean;
104
137
  }
138
+ /**
139
+ * Negation settings for a boolean flag (set by `.negatable()`).
140
+ *
141
+ * The negated spelling and the positive form are two spellings of ONE
142
+ * logical flag: they share duplicate policy, and the last CLI occurrence
143
+ * wins across both. The negated spelling is presence-only — `--no-foo=x`
144
+ * is rejected.
145
+ */
146
+ interface FlagNegation {
147
+ /**
148
+ * Explicit negated spelling without the `--` prefix (e.g. `'no-sandbox'`).
149
+ * `undefined` synthesizes `no-<flagName>` wherever the flag name is known.
150
+ */
151
+ readonly alias: string | undefined;
152
+ /** Hide the negated spelling from help, completions, and suggestions. */
153
+ readonly hidden: boolean;
154
+ }
155
+ /**
156
+ * How repeated CLI occurrences of a singleton flag combine.
157
+ *
158
+ * - `'last'` — last occurrence wins (matches historic behavior)
159
+ * - `'first'` — first occurrence wins; later ones parse but are ignored
160
+ * - `'error'` — a second occurrence is a `ParseError` (`DUPLICATE_FLAG`)
161
+ *
162
+ * Applies to CLI token occurrences only — env/config/prompt/default
163
+ * resolution keeps its precedence semantics and never raises duplicates.
164
+ * Occurrences are counted per *logical* flag: aliases and the negated
165
+ * spelling all count toward the same flag.
166
+ *
167
+ * @defaultValue `'last'`
168
+ */
169
+ type DuplicatePolicy = 'last' | 'first' | 'error';
105
170
  /**
106
171
  * The runtime descriptor stored inside every {@linkcode FlagBuilder}. Consumers (parser,
107
172
  * help generator, resolution chain) read this to understand the flag's shape
@@ -131,8 +196,44 @@ interface FlagSchema {
131
196
  * `true`, so `Infinity` is rejected even when no constraints object is set.
132
197
  */
133
198
  readonly numberConstraints: NumberConstraints | undefined;
199
+ /**
200
+ * String constraints when `kind === 'string'` (`undefined` otherwise).
201
+ *
202
+ * Enforced at the parse and resolution boundaries, in fixed order:
203
+ * nonEmpty → minLength → maxLength → pattern.
204
+ */
205
+ readonly stringConstraints: StringConstraints | undefined;
134
206
  /** Element schema when `kind === 'array'`. */
135
207
  readonly elementSchema: FlagSchema | undefined;
208
+ /**
209
+ * Value separator when `kind === 'array'` (`undefined` otherwise).
210
+ *
211
+ * When set, each CLI occurrence is split on this separator before element
212
+ * coercion, so `--tag a,b --tag c` yields `['a', 'b', 'c']`. Env and
213
+ * config string values use this separator too (default `','`).
214
+ */
215
+ readonly separator: string | undefined;
216
+ /**
217
+ * Deduplicate resolved array values when `kind === 'array'`.
218
+ *
219
+ * Applied after all sources resolve, preserving first-seen order.
220
+ * Uses `SameValueZero` semantics (like `Set`).
221
+ */
222
+ readonly unique: boolean;
223
+ /**
224
+ * Filesystem checks for path-valued flags (set by `flag.path()`).
225
+ *
226
+ * Validated after resolution through the runtime adapter.
227
+ */
228
+ readonly pathChecks: PathChecks | undefined;
229
+ /**
230
+ * Help placeholder label (e.g. `'url'` renders as `<url>`).
231
+ *
232
+ * Set by the sugar factories (`flag.url()`, `flag.date()`, …) so help
233
+ * output names the expected value shape; `undefined` falls back to the
234
+ * kind-derived hint.
235
+ */
236
+ readonly valueHint: string | undefined;
136
237
  /** Interactive prompt configuration for v0.3+ resolution. */
137
238
  readonly prompt: PromptConfig | undefined;
138
239
  /** Custom parse function (only when `kind === 'custom'`). */
@@ -158,6 +259,17 @@ interface FlagSchema {
158
259
  * @defaultValue `false`
159
260
  */
160
261
  readonly propagate: boolean;
262
+ /**
263
+ * Negation settings when `kind === 'boolean'` and `.negatable()` was
264
+ * called (`undefined` otherwise). See {@link FlagNegation}.
265
+ */
266
+ readonly negation: FlagNegation | undefined;
267
+ /**
268
+ * Duplicate policy for repeated CLI occurrences. See {@link DuplicatePolicy}.
269
+ *
270
+ * @defaultValue `'last'`
271
+ */
272
+ readonly duplicates: DuplicatePolicy;
161
273
  }
162
274
  /**
163
275
  * Low-level overrides accepted by {@link createSchema}.
@@ -193,6 +305,18 @@ declare function getFlagAliasNames(schema: FlagSchema, options?: {
193
305
  readonly includeHidden?: boolean;
194
306
  readonly kind?: 'all' | 'short' | 'long';
195
307
  }): readonly string[];
308
+ /**
309
+ * Effective negated spelling for a flag, or `undefined` when not negatable.
310
+ *
311
+ * The builder cannot know its flag name, so a default (`no-<name>`) is
312
+ * synthesized here — everywhere the canonical name is known (parser, help,
313
+ * completions, collision validation).
314
+ *
315
+ * @param name - Canonical flag name.
316
+ * @param schema - Flag schema (read for {@link FlagNegation}).
317
+ * @returns The negated spelling without the `--` prefix.
318
+ */
319
+ declare function getFlagNegatedName(name: string, schema: FlagSchema): string | undefined;
196
320
  /**
197
321
  * Create a raw {@link FlagSchema} object with sensible defaults.
198
322
  *
@@ -470,6 +594,150 @@ declare class FlagBuilder<C extends FlagConfig> {
470
594
  finite(this: FlagBuilder<C & {
471
595
  readonly flagKind: 'number';
472
596
  }>, allow?: boolean): FlagBuilder<C>;
597
+ /**
598
+ * Reject empty strings. Composes with other string constraints.
599
+ *
600
+ * @param value - Whether to reject empty strings.
601
+ * @defaultValue `true`
602
+ * @returns The builder (for chaining).
603
+ *
604
+ * @example
605
+ * ```ts
606
+ * flag.string().nonEmpty() // rejects '', accepts 'x'
607
+ * ```
608
+ */
609
+ nonEmpty(this: FlagBuilder<C & {
610
+ readonly flagKind: 'string';
611
+ }>, value?: boolean): FlagBuilder<C>;
612
+ /**
613
+ * Set an inclusive minimum length (UTF-16 code units). Composes with other
614
+ * string constraints; a later call overrides an earlier `minLength`.
615
+ *
616
+ * @param value - Inclusive minimum length.
617
+ * @returns The builder (for chaining).
618
+ *
619
+ * @example
620
+ * ```ts
621
+ * flag.string().minLength(3) // rejects 'ab', accepts 'abc'
622
+ * ```
623
+ */
624
+ minLength(this: FlagBuilder<C & {
625
+ readonly flagKind: 'string';
626
+ }>, value: number): FlagBuilder<C>;
627
+ /**
628
+ * Set an inclusive maximum length (UTF-16 code units). Composes with other
629
+ * string constraints; a later call overrides an earlier `maxLength`.
630
+ *
631
+ * @param value - Inclusive maximum length.
632
+ * @returns The builder (for chaining).
633
+ *
634
+ * @example
635
+ * ```ts
636
+ * flag.string().maxLength(8) // rejects 9+ chars
637
+ * ```
638
+ */
639
+ maxLength(this: FlagBuilder<C & {
640
+ readonly flagKind: 'string';
641
+ }>, value: number): FlagBuilder<C>;
642
+ /**
643
+ * Require the value to match a regular expression. Anchor with `^`/`$`
644
+ * for full-string matching. Composes with other string constraints.
645
+ *
646
+ * @param value - Pattern the value must match.
647
+ * @returns The builder (for chaining).
648
+ *
649
+ * @example
650
+ * ```ts
651
+ * flag.string().pattern(/^ghp_/) // rejects 'abc', accepts 'ghp_x'
652
+ * ```
653
+ */
654
+ pattern(this: FlagBuilder<C & {
655
+ readonly flagKind: 'string';
656
+ }>, value: RegExp): FlagBuilder<C>;
657
+ /**
658
+ * Split each CLI occurrence on a separator before element coercion, so
659
+ * `--tag a,b --tag c` resolves to `['a', 'b', 'c']`. Elements are coerced
660
+ * (and rejected) individually with the element schema's own error format.
661
+ *
662
+ * Env and config string values are split on the same separator (their
663
+ * default split is `','` even without this modifier).
664
+ *
665
+ * @param value - Separator string (e.g. `','`).
666
+ * @returns The builder (for chaining).
667
+ *
668
+ * @example
669
+ * ```ts
670
+ * flag.array(flag.enum(['us', 'eu', 'ap'])).separator(',')
671
+ * // --region us,eu --region ap → ['us', 'eu', 'ap']
672
+ * ```
673
+ */
674
+ separator(this: FlagBuilder<C & {
675
+ readonly flagKind: 'array';
676
+ }>, value: string): FlagBuilder<C>;
677
+ /**
678
+ * Deduplicate the resolved array, preserving first-seen order. Applied
679
+ * after all sources resolve, using `SameValueZero` semantics (like `Set`).
680
+ *
681
+ * @param value - Whether to deduplicate.
682
+ * @defaultValue `true`
683
+ * @returns The builder (for chaining).
684
+ *
685
+ * @example
686
+ * ```ts
687
+ * flag.array(flag.string()).separator(',').unique()
688
+ * // --tag a,a --tag a → ['a']
689
+ * ```
690
+ */
691
+ unique(this: FlagBuilder<C & {
692
+ readonly flagKind: 'array';
693
+ }>, value?: boolean): FlagBuilder<C>;
694
+ /**
695
+ * Accept a negated spelling (`--no-<name>`) that sets the flag to `false`.
696
+ *
697
+ * Both spellings are ONE logical flag: the last CLI occurrence wins across
698
+ * them, and they share the duplicate policy. The negated spelling is
699
+ * presence-only — `--no-<name>=true` is rejected. Help renders the flag as
700
+ * `--[no-]<name>` (or lists a custom alias); env/config/prompt/default
701
+ * resolution is unaffected.
702
+ *
703
+ * @param options - Optional custom spelling (`alias`, without `--`) and
704
+ * `hidden` to keep the negated spelling parseable but unadvertised.
705
+ * @returns The builder (for chaining).
706
+ *
707
+ * @example
708
+ * ```ts
709
+ * flag.boolean().default(true).negatable()
710
+ * // $ mycli build --no-sandbox → sandbox = false
711
+ * // $ mycli build --sandbox → sandbox = true
712
+ * ```
713
+ */
714
+ negatable(this: FlagBuilder<C & {
715
+ readonly flagKind: 'boolean';
716
+ }>, options?: {
717
+ alias?: string;
718
+ hidden?: boolean;
719
+ }): FlagBuilder<C>;
720
+ /**
721
+ * Set how repeated CLI occurrences of this flag combine.
722
+ *
723
+ * Counted per logical flag — aliases and the negated spelling all count
724
+ * toward the same flag. CLI tokens only: env/config/prompt/default
725
+ * resolution keeps its precedence semantics. Not available on `array`,
726
+ * `count`, or `keyValue` flags, which inherently accumulate.
727
+ *
728
+ * @param policy - `'last'` (default), `'first'`, or `'error'`.
729
+ * @returns The builder (for chaining).
730
+ *
731
+ * @example
732
+ * ```ts
733
+ * flag.enum(['session', 'same-dir', 'worktree']).duplicates('error')
734
+ * // $ mycli run --spawn session --spawn worktree
735
+ * // # → Error: Flag --spawn may only be specified once
736
+ * ```
737
+ */
738
+ duplicates(this: FlagBuilder<C & {
739
+ readonly flagKind: 'boolean' | 'string' | 'number' | 'enum' | 'custom';
740
+ }>, policy: DuplicatePolicy): FlagBuilder<C>;
473
741
  }
474
742
  /**
475
743
  * Factory that creates {@link FlagBuilder} instances seeded with the correct
@@ -477,11 +745,25 @@ declare class FlagBuilder<C extends FlagConfig> {
477
745
  */
478
746
  interface FlagFactory {
479
747
  /**
480
- * String-valued flag.
748
+ * String-valued flag, with optional string constraints.
481
749
  *
750
+ * Constraints are enforced at the parse and resolution boundaries, in
751
+ * fixed order: nonEmpty → minLength → maxLength → pattern. They also
752
+ * compose via chained methods (`.nonEmpty()`, `.minLength()`,
753
+ * `.maxLength()`, `.pattern()`), which override values set here.
754
+ *
755
+ * @param constraints - Optional string constraints.
756
+ * @defaultValue `undefined` (no constraints)
482
757
  * @returns A {@link FlagBuilder} for `string` values.
758
+ *
759
+ * @example
760
+ * ```ts
761
+ * flag.string() // any string
762
+ * flag.string({ nonEmpty: true }) // rejects ''
763
+ * flag.string({ pattern: /^ghp_/ }) // token shapes
764
+ * ```
483
765
  */
484
- string(): FlagBuilder<{
766
+ string(constraints?: StringConstraints): FlagBuilder<{
485
767
  readonly valueType: string;
486
768
  readonly presence: 'optional';
487
769
  readonly optionalFallback: 'undefined';
@@ -601,6 +883,153 @@ interface FlagFactory {
601
883
  readonly optionalFallback: 'undefined';
602
884
  readonly flagKind: 'custom';
603
885
  }>;
886
+ /**
887
+ * URL-valued flag. Parses into a `URL`; invalid URLs are rejected with an
888
+ * `INVALID_VALUE` error naming the flag.
889
+ *
890
+ * @param options - Optional protocol allowlist (without trailing colon).
891
+ * @returns A {@link FlagBuilder} for `URL` values.
892
+ *
893
+ * @example
894
+ * ```ts
895
+ * flag.url() // any URL
896
+ * flag.url({ protocols: ['https'] }) // https only
897
+ * ```
898
+ */
899
+ url(options?: UrlFlagOptions): FlagBuilder<{
900
+ readonly valueType: URL;
901
+ readonly presence: 'optional';
902
+ readonly optionalFallback: 'undefined';
903
+ readonly flagKind: 'custom';
904
+ }>;
905
+ /**
906
+ * Path-valued flag. The value stays a `string`; optional filesystem
907
+ * checks run **after resolution** through the runtime adapter, so CLI,
908
+ * env, and config values are validated identically.
909
+ *
910
+ * @param options - Optional existence/type checks. `type` implies
911
+ * existence.
912
+ * @returns A {@link FlagBuilder} for path strings.
913
+ *
914
+ * @example
915
+ * ```ts
916
+ * flag.path() // any string, help shows <path>
917
+ * flag.path({ mustExist: true }) // rejects missing paths
918
+ * flag.path({ type: 'directory' }) // must exist and be a directory
919
+ * ```
920
+ */
921
+ path(options?: PathFlagOptions): FlagBuilder<{
922
+ readonly valueType: string;
923
+ readonly presence: 'optional';
924
+ readonly optionalFallback: 'undefined';
925
+ readonly flagKind: 'string';
926
+ }>;
927
+ /**
928
+ * Date-valued flag. Accepts strict ISO-8601 (`2026-07-10`,
929
+ * `2026-07-10T14:30:00Z`) and parses into a `Date`. Lenient `Date.parse`
930
+ * inputs (`'0'`, `'March 5'`) and calendar-invalid dates (`2026-02-31`)
931
+ * are rejected.
932
+ *
933
+ * Returns `Date` (not `Temporal`) because the supported runtimes do not
934
+ * all ship Temporal yet; use `flag.custom()` with `Temporal.PlainDate.from`
935
+ * where the target runtime has it.
936
+ *
937
+ * @param options - Optional inclusive `min`/`max` date bounds.
938
+ * @returns A {@link FlagBuilder} for `Date` values.
939
+ *
940
+ * @example
941
+ * ```ts
942
+ * flag.date()
943
+ * flag.date({ min: new Date('2020-01-01') })
944
+ * ```
945
+ */
946
+ date(options?: DateFlagOptions): FlagBuilder<{
947
+ readonly valueType: Date;
948
+ readonly presence: 'optional';
949
+ readonly optionalFallback: 'undefined';
950
+ readonly flagKind: 'custom';
951
+ }>;
952
+ /**
953
+ * Duration flag. Accepts `'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`,
954
+ * compounds like `'1h30m'`, or a bare millisecond count, and resolves to
955
+ * **milliseconds**.
956
+ *
957
+ * @returns A {@link FlagBuilder} for duration values in milliseconds.
958
+ *
959
+ * @example
960
+ * ```ts
961
+ * flag.duration().default(30_000) // --timeout 45s → 45000
962
+ * ```
963
+ */
964
+ duration(): FlagBuilder<{
965
+ readonly valueType: number;
966
+ readonly presence: 'optional';
967
+ readonly optionalFallback: 'undefined';
968
+ readonly flagKind: 'custom';
969
+ }>;
970
+ /**
971
+ * Byte-size flag. Accepts `'512mb'`, `'1.5gb'`, `'64kb'`, `'100b'` or a
972
+ * bare byte count, and resolves to **bytes**. Units are binary
973
+ * (`1kb` = 1024) and case-insensitive.
974
+ *
975
+ * @returns A {@link FlagBuilder} for sizes in bytes.
976
+ *
977
+ * @example
978
+ * ```ts
979
+ * flag.bytes().default(10 * 1024 ** 2) // --max-size 512kb → 524288
980
+ * ```
981
+ */
982
+ bytes(): FlagBuilder<{
983
+ readonly valueType: number;
984
+ readonly presence: 'optional';
985
+ readonly optionalFallback: 'undefined';
986
+ readonly flagKind: 'custom';
987
+ }>;
988
+ /**
989
+ * Count flag — resolves to how many times the flag appears. `-vvv`,
990
+ * `-v -v -v`, and `--verbose --verbose --verbose` all yield `3`; absent
991
+ * yields `0`. An explicit value (`--verbose=2`, env, config) sets the
992
+ * count directly.
993
+ *
994
+ * Not promptable.
995
+ *
996
+ * @returns A {@link FlagBuilder} for occurrence counts (defaulted to `0`).
997
+ *
998
+ * @example
999
+ * ```ts
1000
+ * flag.count().alias('v').describe('Increase verbosity')
1001
+ * // $ mycli build -vv → verbose = 2
1002
+ * ```
1003
+ */
1004
+ count(): FlagBuilder<{
1005
+ readonly valueType: number;
1006
+ readonly presence: 'defaulted';
1007
+ readonly optionalFallback: 'undefined';
1008
+ readonly flagKind: 'count';
1009
+ }>;
1010
+ /**
1011
+ * Key-value flag — repeated `KEY=VALUE` occurrences merge into a
1012
+ * `Record<string, string>` (docker/kubectl `--env` style). The value is
1013
+ * split at the **first** `=`, so `--env A=b=c` yields `{ A: 'b=c' }`.
1014
+ * Later occurrences of the same key win. Absent resolves to `{}`.
1015
+ *
1016
+ * Env vars accept separator-joined pairs (`A=1,B=2`); config files accept
1017
+ * a plain object. Not promptable.
1018
+ *
1019
+ * @returns A {@link FlagBuilder} for `Record<string, string>` values.
1020
+ *
1021
+ * @example
1022
+ * ```ts
1023
+ * flag.keyValue().alias('e').describe('Environment variables')
1024
+ * // $ mycli run -e A=1 -e B=2 → env = { A: '1', B: '2' }
1025
+ * ```
1026
+ */
1027
+ keyValue(): FlagBuilder<{
1028
+ readonly valueType: Record<string, string>;
1029
+ readonly presence: 'optional';
1030
+ readonly optionalFallback: 'empty-object';
1031
+ readonly flagKind: 'keyValue';
1032
+ }>;
604
1033
  }
605
1034
  /**
606
1035
  * Flag schema factory. Call `flag.<kind>()` to create an immutable
@@ -608,4 +1037,4 @@ interface FlagFactory {
608
1037
  */
609
1038
  declare const flag: FlagFactory;
610
1039
  //#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 };
1040
+ 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 };