@kjanat/dreamcli 3.0.0-rc.4 → 3.0.0-rc.7

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 (93) hide show
  1. package/CHANGELOG.md +82 -1
  2. package/dist/core/cli/dispatch.d.mts +0 -1
  3. package/dist/core/cli/dispatch.mjs +1 -1
  4. package/dist/core/cli/help-links.d.mts +0 -1
  5. package/dist/core/cli/index.d.mts +0 -1
  6. package/dist/core/cli/index.mjs +16 -7
  7. package/dist/core/cli/planner.d.mts +0 -1
  8. package/dist/core/cli/planner.mjs +3 -3
  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 +6 -1
  13. package/dist/core/cli/root-surface.d.mts +0 -1
  14. package/dist/core/cli/runtime-preflight.d.mts +5 -1
  15. package/dist/core/cli/runtime-preflight.mjs +2 -1
  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 +3 -2
  20. package/dist/core/completion/shells/fish.d.mts +0 -1
  21. package/dist/core/completion/shells/fish.mjs +3 -2
  22. package/dist/core/completion/shells/powershell.d.mts +0 -1
  23. package/dist/core/completion/shells/powershell.mjs +2 -1
  24. package/dist/core/completion/shells/shared.d.mts +1 -1
  25. package/dist/core/completion/shells/shared.mjs +5 -0
  26. package/dist/core/completion/shells/zsh.d.mts +0 -1
  27. package/dist/core/completion/shells/zsh.mjs +3 -2
  28. package/dist/core/config/index.d.mts +0 -1
  29. package/dist/core/config/index.mjs +2 -2
  30. package/dist/core/config/package-json.d.mts +0 -1
  31. package/dist/core/execution/index.d.mts +0 -1
  32. package/dist/core/execution/index.mjs +3 -2
  33. package/dist/core/help/ansi.mjs +3 -2
  34. package/dist/core/help/index.d.mts +1 -1
  35. package/dist/core/help/index.mjs +12 -6
  36. package/dist/core/json-schema/index.d.mts +1 -1
  37. package/dist/core/json-schema/index.mjs +25 -7
  38. package/dist/core/output/activity.d.mts +0 -1
  39. package/dist/core/output/contracts.d.mts +0 -1
  40. package/dist/core/output/contracts.mjs +1 -1
  41. package/dist/core/output/index.d.mts +0 -1
  42. package/dist/core/output/index.mjs +1 -1
  43. package/dist/core/output/renderers.d.mts +0 -1
  44. package/dist/core/parse/index.d.mts +1 -1
  45. package/dist/core/parse/index.mjs +75 -9
  46. package/dist/core/prompt/index.d.mts +1 -0
  47. package/dist/core/resolve/args.d.mts +1 -1
  48. package/dist/core/resolve/coerce.d.mts +1 -1
  49. package/dist/core/resolve/coerce.mjs +71 -14
  50. package/dist/core/resolve/contracts.d.mts +6 -1
  51. package/dist/core/resolve/errors.d.mts +0 -1
  52. package/dist/core/resolve/flags.d.mts +7 -2
  53. package/dist/core/resolve/flags.mjs +61 -6
  54. package/dist/core/resolve/index.d.mts +1 -1
  55. package/dist/core/resolve/index.mjs +1 -1
  56. package/dist/core/resolve/property.d.mts +3 -0
  57. package/dist/core/resolve/property.mjs +11 -3
  58. package/dist/core/schema/activity.d.mts +31 -11
  59. package/dist/core/schema/arg.d.mts +1 -2
  60. package/dist/core/schema/command.d.mts +8 -6
  61. package/dist/core/schema/command.mjs +3 -1
  62. package/dist/core/schema/flag.d.mts +337 -10
  63. package/dist/core/schema/flag.mjs +185 -3
  64. package/dist/core/schema/index.d.mts +4 -2
  65. package/dist/core/schema/middleware.d.mts +4 -3
  66. package/dist/core/schema/prompt.d.mts +5 -2
  67. package/dist/core/schema/run.d.mts +9 -1
  68. package/dist/core/schema/string-constraints.d.mts +97 -0
  69. package/dist/core/schema/string-constraints.mjs +69 -0
  70. package/dist/core/schema/value-parsers.d.mts +78 -0
  71. package/dist/core/schema/value-parsers.mjs +142 -0
  72. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  73. package/dist/core/testkit/index.d.mts +0 -31
  74. package/dist/core/testkit/index.mjs +1 -1
  75. package/dist/index.d.mts +5 -2
  76. package/dist/index.mjs +5 -5
  77. package/dist/runtime/adapter.d.mts +38 -2
  78. package/dist/runtime/adapter.mjs +5 -0
  79. package/dist/runtime/auto.d.mts +2 -3
  80. package/dist/runtime/auto.mjs +4 -5
  81. package/dist/runtime/deno.d.mts +24 -5
  82. package/dist/runtime/deno.mjs +45 -0
  83. package/dist/runtime/index.d.mts +3 -4
  84. package/dist/runtime/node.d.mts +8 -2
  85. package/dist/runtime/node.mjs +51 -0
  86. package/dist/runtime.d.mts +4 -4
  87. package/dist/runtime.mjs +2 -3
  88. package/dist/testkit.d.mts +1 -0
  89. package/dist/version.mjs +2 -2
  90. package/dreamcli.schema.json +3 -1
  91. package/package.json +13 -15
  92. package/dist/runtime/bun.d.mts +0 -28
  93. package/dist/runtime/bun.mjs +0 -28
@@ -87,34 +87,54 @@ interface ProgressHandle {
87
87
  * without polluting stdout/stderr arrays.
88
88
  */
89
89
  type ActivityEvent = {
90
- /** Spinner created and started. */readonly type: 'spinner:start'; /** Initial spinner text. */
90
+ /** Spinner created and started. */
91
+ readonly type: 'spinner:start';
92
+ /** Initial spinner text. */
91
93
  readonly text: string;
92
94
  } | {
93
- /** Spinner text changed. */readonly type: 'spinner:update'; /** Updated spinner text. */
95
+ /** Spinner text changed. */
96
+ readonly type: 'spinner:update';
97
+ /** Updated spinner text. */
94
98
  readonly text: string;
95
99
  } | {
96
- /** Spinner completed successfully. */readonly type: 'spinner:succeed'; /** Success message. */
100
+ /** Spinner completed successfully. */
101
+ readonly type: 'spinner:succeed';
102
+ /** Success message. */
97
103
  readonly text: string;
98
104
  } | {
99
- /** Spinner stopped with an error. */readonly type: 'spinner:fail'; /** Failure message. */
105
+ /** Spinner stopped with an error. */
106
+ readonly type: 'spinner:fail';
107
+ /** Failure message. */
100
108
  readonly text: string;
101
109
  } | {
102
- /** Spinner stopped without a final status. */readonly type: 'spinner:stop';
110
+ /** Spinner stopped without a final status. */
111
+ readonly type: 'spinner:stop';
103
112
  } | {
104
- /** Progress bar created and started. */readonly type: 'progress:start'; /** Bar label. */
105
- readonly label: string; /** Known total, or `undefined` for indeterminate. */
113
+ /** Progress bar created and started. */
114
+ readonly type: 'progress:start';
115
+ /** Bar label. */
116
+ readonly label: string;
117
+ /** Known total, or `undefined` for indeterminate. */
106
118
  readonly total: number | undefined;
107
119
  } | {
108
- /** Progress bar advanced. */readonly type: 'progress:increment'; /** Amount advanced. */
120
+ /** Progress bar advanced. */
121
+ readonly type: 'progress:increment';
122
+ /** Amount advanced. */
109
123
  readonly delta: number;
110
124
  } | {
111
- /** Progress bar set to an absolute value. */readonly type: 'progress:update'; /** New absolute value. */
125
+ /** Progress bar set to an absolute value. */
126
+ readonly type: 'progress:update';
127
+ /** New absolute value. */
112
128
  readonly value: number;
113
129
  } | {
114
- /** Progress bar completed. */readonly type: 'progress:done'; /** Completion message, if any. */
130
+ /** Progress bar completed. */
131
+ readonly type: 'progress:done';
132
+ /** Completion message, if any. */
115
133
  readonly text: string | undefined;
116
134
  } | {
117
- /** Progress bar stopped with an error. */readonly type: 'progress:fail'; /** Failure message, if any. */
135
+ /** Progress bar stopped with an error. */
136
+ readonly type: 'progress:fail';
137
+ /** Failure message, if any. */
118
138
  readonly text: string | undefined;
119
139
  };
120
140
  /**
@@ -1,5 +1,4 @@
1
1
  import { NumberConstraints } from "./number-constraints.mjs";
2
-
3
2
  //#region src/core/schema/arg.d.ts
4
3
  /** All arg presence states as a runtime array. */
5
4
  declare const ARG_PRESENCES: readonly ['required', 'optional', 'defaulted'];
@@ -60,7 +59,7 @@ type ResolvedArgValue<C extends ArgConfig> = C['variadic'] extends true ? C['val
60
59
  /** Extract the resolved value type from an {@linkcode ArgBuilder}. */
61
60
  type InferArg<B> = B extends ArgBuilder<infer C extends ArgConfig> ? ResolvedArgValue<C> : never;
62
61
  /** Extract resolved value types from a record of builders. */
63
- type InferArgs<T extends Record<string, ArgBuilder<ArgConfig>>> = { [K in keyof T]: InferArg<T[K]> };
62
+ type InferArgs<T extends Record<string, ArgBuilder<ArgConfig>>> = { [K in keyof T]: InferArg<T[K]>; };
64
63
  /** All arg kind discriminators as a runtime array. */
65
64
  declare const ARG_KINDS: readonly ['string', 'number', 'enum', 'custom'];
66
65
  /** Discriminator for the kind of value an arg accepts. */
@@ -5,7 +5,6 @@ import { FlagBuilder, FlagConfig, FlagSchema, InferFlags } from "./flag.mjs";
5
5
  import { ErasedMiddlewareHandler, Middleware } from "./middleware.mjs";
6
6
  import { RunOptions, RunResult } from "./run.mjs";
7
7
  import { Colors } from "ansispeck";
8
-
9
8
  //#region src/core/schema/command.d.ts
10
9
  /**
11
10
  * Widen the context type when adding middleware.
@@ -22,7 +21,7 @@ type WidenContext<C extends Record<string, unknown>, Output extends Record<strin
22
21
  /**
23
22
  * Widen the context type when adding command-scoped derived context.
24
23
  *
25
- * Validation-only derive handlers return `undefined`, preserving `C`.
24
+ * Validation-only derive handlers return `undefined` (or nothing), preserving `C`.
26
25
  * Context-producing derive handlers return an object that merges into `C`
27
26
  * using the same first-call replacement rules as middleware.
28
27
  */
@@ -331,12 +330,13 @@ type DeriveParams<F extends Record<string, FlagBuilder<FlagConfig>>, A extends R
331
330
  *
332
331
  * Derive handlers may:
333
332
  * - validate resolved input and throw {@linkcode CLIError}
334
- * - return `undefined` to continue without changing context
333
+ * - return nothing (or `undefined`) to continue without changing context
335
334
  * - return an object whose properties merge into `ctx` downstream
336
335
  *
336
+ * Handlers may be async; the resolved value follows the same rules.
337
337
  * They cannot wrap downstream execution; use {@linkcode middleware} for that.
338
338
  */
339
- type DeriveHandler<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown> = Record<string, never>, Output extends Record<string, unknown> | undefined = undefined> = (params: DeriveParams<F, A, C>) => Output | Promise<Output>;
339
+ type DeriveHandler<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown> = Record<string, never>, Output extends Record<string, unknown> | undefined | void = undefined> = (params: DeriveParams<F, A, C>) => Output | Promise<Output>;
340
340
  /**
341
341
  * Type-erased derive handler stored on the command builder.
342
342
  *
@@ -598,9 +598,11 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
598
598
  * Derive runs after full resolution and before the action handler.
599
599
  * It receives typed `{ args, flags, ctx, out, meta }` and may either:
600
600
  *
601
- * - return `undefined` for validation-only behavior
601
+ * - return nothing (or `undefined`) for validation-only behavior
602
602
  * - return an object to merge additional properties into `ctx`
603
603
  *
604
+ * Handlers may be async — the runtime awaits them before continuing.
605
+ *
604
606
  * Unlike middleware, derive cannot wrap downstream execution and does not
605
607
  * use `next()`. Use {@linkcode middleware} for timing, logging, retries, cleanup,
606
608
  * or error-boundary patterns.
@@ -629,7 +631,7 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
629
631
  * @param handler - Derive function receiving typed args/flags/ctx.
630
632
  * @returns The builder (for chaining).
631
633
  */
632
- derive<Output extends Record<string, unknown> | undefined>(handler: DeriveHandler<F, A, C, Output>): CommandBuilder<F, A, WidenDerivedContext<C, Output>>;
634
+ derive<Output extends Record<string, unknown> | undefined | void>(handler: DeriveHandler<F, A, C, Output>): CommandBuilder<F, A, WidenDerivedContext<C, Output>>;
633
635
  /**
634
636
  * Register middleware to run before the action handler.
635
637
  *
@@ -219,9 +219,11 @@ var CommandBuilder = class CommandBuilder {
219
219
  * Derive runs after full resolution and before the action handler.
220
220
  * It receives typed `{ args, flags, ctx, out, meta }` and may either:
221
221
  *
222
- * - return `undefined` for validation-only behavior
222
+ * - return nothing (or `undefined`) for validation-only behavior
223
223
  * - return an object to merge additional properties into `ctx`
224
224
  *
225
+ * Handlers may be async — the runtime awaits them before continuing.
226
+ *
225
227
  * Unlike middleware, derive cannot wrap downstream execution and does not
226
228
  * use `next()`. Use {@linkcode middleware} for timing, logging, retries, cleanup,
227
229
  * or error-boundary patterns.
@@ -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. */
@@ -131,8 +164,44 @@ interface FlagSchema {
131
164
  * `true`, so `Infinity` is rejected even when no constraints object is set.
132
165
  */
133
166
  readonly numberConstraints: NumberConstraints | undefined;
167
+ /**
168
+ * String constraints when `kind === 'string'` (`undefined` otherwise).
169
+ *
170
+ * Enforced at the parse and resolution boundaries, in fixed order:
171
+ * nonEmpty → minLength → maxLength → pattern.
172
+ */
173
+ readonly stringConstraints: StringConstraints | undefined;
134
174
  /** Element schema when `kind === 'array'`. */
135
175
  readonly elementSchema: FlagSchema | undefined;
176
+ /**
177
+ * Value separator when `kind === 'array'` (`undefined` otherwise).
178
+ *
179
+ * When set, each CLI occurrence is split on this separator before element
180
+ * coercion, so `--tag a,b --tag c` yields `['a', 'b', 'c']`. Env and
181
+ * config string values use this separator too (default `','`).
182
+ */
183
+ readonly separator: string | undefined;
184
+ /**
185
+ * Deduplicate resolved array values when `kind === 'array'`.
186
+ *
187
+ * Applied after all sources resolve, preserving first-seen order.
188
+ * Uses `SameValueZero` semantics (like `Set`).
189
+ */
190
+ readonly unique: boolean;
191
+ /**
192
+ * Filesystem checks for path-valued flags (set by `flag.path()`).
193
+ *
194
+ * Validated after resolution through the runtime adapter.
195
+ */
196
+ readonly pathChecks: PathChecks | undefined;
197
+ /**
198
+ * Help placeholder label (e.g. `'url'` renders as `<url>`).
199
+ *
200
+ * Set by the sugar factories (`flag.url()`, `flag.date()`, …) so help
201
+ * output names the expected value shape; `undefined` falls back to the
202
+ * kind-derived hint.
203
+ */
204
+ readonly valueHint: string | undefined;
136
205
  /** Interactive prompt configuration for v0.3+ resolution. */
137
206
  readonly prompt: PromptConfig | undefined;
138
207
  /** Custom parse function (only when `kind === 'custom'`). */
@@ -470,6 +539,103 @@ declare class FlagBuilder<C extends FlagConfig> {
470
539
  finite(this: FlagBuilder<C & {
471
540
  readonly flagKind: 'number';
472
541
  }>, allow?: boolean): FlagBuilder<C>;
542
+ /**
543
+ * Reject empty strings. Composes with other string constraints.
544
+ *
545
+ * @param value - Whether to reject empty strings.
546
+ * @defaultValue `true`
547
+ * @returns The builder (for chaining).
548
+ *
549
+ * @example
550
+ * ```ts
551
+ * flag.string().nonEmpty() // rejects '', accepts 'x'
552
+ * ```
553
+ */
554
+ nonEmpty(this: FlagBuilder<C & {
555
+ readonly flagKind: 'string';
556
+ }>, value?: boolean): FlagBuilder<C>;
557
+ /**
558
+ * Set an inclusive minimum length (UTF-16 code units). Composes with other
559
+ * string constraints; a later call overrides an earlier `minLength`.
560
+ *
561
+ * @param value - Inclusive minimum length.
562
+ * @returns The builder (for chaining).
563
+ *
564
+ * @example
565
+ * ```ts
566
+ * flag.string().minLength(3) // rejects 'ab', accepts 'abc'
567
+ * ```
568
+ */
569
+ minLength(this: FlagBuilder<C & {
570
+ readonly flagKind: 'string';
571
+ }>, value: number): FlagBuilder<C>;
572
+ /**
573
+ * Set an inclusive maximum length (UTF-16 code units). Composes with other
574
+ * string constraints; a later call overrides an earlier `maxLength`.
575
+ *
576
+ * @param value - Inclusive maximum length.
577
+ * @returns The builder (for chaining).
578
+ *
579
+ * @example
580
+ * ```ts
581
+ * flag.string().maxLength(8) // rejects 9+ chars
582
+ * ```
583
+ */
584
+ maxLength(this: FlagBuilder<C & {
585
+ readonly flagKind: 'string';
586
+ }>, value: number): FlagBuilder<C>;
587
+ /**
588
+ * Require the value to match a regular expression. Anchor with `^`/`$`
589
+ * for full-string matching. Composes with other string constraints.
590
+ *
591
+ * @param value - Pattern the value must match.
592
+ * @returns The builder (for chaining).
593
+ *
594
+ * @example
595
+ * ```ts
596
+ * flag.string().pattern(/^ghp_/) // rejects 'abc', accepts 'ghp_x'
597
+ * ```
598
+ */
599
+ pattern(this: FlagBuilder<C & {
600
+ readonly flagKind: 'string';
601
+ }>, value: RegExp): FlagBuilder<C>;
602
+ /**
603
+ * Split each CLI occurrence on a separator before element coercion, so
604
+ * `--tag a,b --tag c` resolves to `['a', 'b', 'c']`. Elements are coerced
605
+ * (and rejected) individually with the element schema's own error format.
606
+ *
607
+ * Env and config string values are split on the same separator (their
608
+ * default split is `','` even without this modifier).
609
+ *
610
+ * @param value - Separator string (e.g. `','`).
611
+ * @returns The builder (for chaining).
612
+ *
613
+ * @example
614
+ * ```ts
615
+ * flag.array(flag.enum(['us', 'eu', 'ap'])).separator(',')
616
+ * // --region us,eu --region ap → ['us', 'eu', 'ap']
617
+ * ```
618
+ */
619
+ separator(this: FlagBuilder<C & {
620
+ readonly flagKind: 'array';
621
+ }>, value: string): FlagBuilder<C>;
622
+ /**
623
+ * Deduplicate the resolved array, preserving first-seen order. Applied
624
+ * after all sources resolve, using `SameValueZero` semantics (like `Set`).
625
+ *
626
+ * @param value - Whether to deduplicate.
627
+ * @defaultValue `true`
628
+ * @returns The builder (for chaining).
629
+ *
630
+ * @example
631
+ * ```ts
632
+ * flag.array(flag.string()).separator(',').unique()
633
+ * // --tag a,a --tag a → ['a']
634
+ * ```
635
+ */
636
+ unique(this: FlagBuilder<C & {
637
+ readonly flagKind: 'array';
638
+ }>, value?: boolean): FlagBuilder<C>;
473
639
  }
474
640
  /**
475
641
  * Factory that creates {@link FlagBuilder} instances seeded with the correct
@@ -477,11 +643,25 @@ declare class FlagBuilder<C extends FlagConfig> {
477
643
  */
478
644
  interface FlagFactory {
479
645
  /**
480
- * String-valued flag.
646
+ * String-valued flag, with optional string constraints.
481
647
  *
648
+ * Constraints are enforced at the parse and resolution boundaries, in
649
+ * fixed order: nonEmpty → minLength → maxLength → pattern. They also
650
+ * compose via chained methods (`.nonEmpty()`, `.minLength()`,
651
+ * `.maxLength()`, `.pattern()`), which override values set here.
652
+ *
653
+ * @param constraints - Optional string constraints.
654
+ * @defaultValue `undefined` (no constraints)
482
655
  * @returns A {@link FlagBuilder} for `string` values.
656
+ *
657
+ * @example
658
+ * ```ts
659
+ * flag.string() // any string
660
+ * flag.string({ nonEmpty: true }) // rejects ''
661
+ * flag.string({ pattern: /^ghp_/ }) // token shapes
662
+ * ```
483
663
  */
484
- string(): FlagBuilder<{
664
+ string(constraints?: StringConstraints): FlagBuilder<{
485
665
  readonly valueType: string;
486
666
  readonly presence: 'optional';
487
667
  readonly optionalFallback: 'undefined';
@@ -601,6 +781,153 @@ interface FlagFactory {
601
781
  readonly optionalFallback: 'undefined';
602
782
  readonly flagKind: 'custom';
603
783
  }>;
784
+ /**
785
+ * URL-valued flag. Parses into a `URL`; invalid URLs are rejected with an
786
+ * `INVALID_VALUE` error naming the flag.
787
+ *
788
+ * @param options - Optional protocol allowlist (without trailing colon).
789
+ * @returns A {@link FlagBuilder} for `URL` values.
790
+ *
791
+ * @example
792
+ * ```ts
793
+ * flag.url() // any URL
794
+ * flag.url({ protocols: ['https'] }) // https only
795
+ * ```
796
+ */
797
+ url(options?: UrlFlagOptions): FlagBuilder<{
798
+ readonly valueType: URL;
799
+ readonly presence: 'optional';
800
+ readonly optionalFallback: 'undefined';
801
+ readonly flagKind: 'custom';
802
+ }>;
803
+ /**
804
+ * Path-valued flag. The value stays a `string`; optional filesystem
805
+ * checks run **after resolution** through the runtime adapter, so CLI,
806
+ * env, and config values are validated identically.
807
+ *
808
+ * @param options - Optional existence/type checks. `type` implies
809
+ * existence.
810
+ * @returns A {@link FlagBuilder} for path strings.
811
+ *
812
+ * @example
813
+ * ```ts
814
+ * flag.path() // any string, help shows <path>
815
+ * flag.path({ mustExist: true }) // rejects missing paths
816
+ * flag.path({ type: 'directory' }) // must exist and be a directory
817
+ * ```
818
+ */
819
+ path(options?: PathFlagOptions): FlagBuilder<{
820
+ readonly valueType: string;
821
+ readonly presence: 'optional';
822
+ readonly optionalFallback: 'undefined';
823
+ readonly flagKind: 'string';
824
+ }>;
825
+ /**
826
+ * Date-valued flag. Accepts strict ISO-8601 (`2026-07-10`,
827
+ * `2026-07-10T14:30:00Z`) and parses into a `Date`. Lenient `Date.parse`
828
+ * inputs (`'0'`, `'March 5'`) and calendar-invalid dates (`2026-02-31`)
829
+ * are rejected.
830
+ *
831
+ * Returns `Date` (not `Temporal`) because the supported runtimes do not
832
+ * all ship Temporal yet; use `flag.custom()` with `Temporal.PlainDate.from`
833
+ * where the target runtime has it.
834
+ *
835
+ * @param options - Optional inclusive `min`/`max` date bounds.
836
+ * @returns A {@link FlagBuilder} for `Date` values.
837
+ *
838
+ * @example
839
+ * ```ts
840
+ * flag.date()
841
+ * flag.date({ min: new Date('2020-01-01') })
842
+ * ```
843
+ */
844
+ date(options?: DateFlagOptions): FlagBuilder<{
845
+ readonly valueType: Date;
846
+ readonly presence: 'optional';
847
+ readonly optionalFallback: 'undefined';
848
+ readonly flagKind: 'custom';
849
+ }>;
850
+ /**
851
+ * Duration flag. Accepts `'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`,
852
+ * compounds like `'1h30m'`, or a bare millisecond count, and resolves to
853
+ * **milliseconds**.
854
+ *
855
+ * @returns A {@link FlagBuilder} for duration values in milliseconds.
856
+ *
857
+ * @example
858
+ * ```ts
859
+ * flag.duration().default(30_000) // --timeout 45s → 45000
860
+ * ```
861
+ */
862
+ duration(): FlagBuilder<{
863
+ readonly valueType: number;
864
+ readonly presence: 'optional';
865
+ readonly optionalFallback: 'undefined';
866
+ readonly flagKind: 'custom';
867
+ }>;
868
+ /**
869
+ * Byte-size flag. Accepts `'512mb'`, `'1.5gb'`, `'64kb'`, `'100b'` or a
870
+ * bare byte count, and resolves to **bytes**. Units are binary
871
+ * (`1kb` = 1024) and case-insensitive.
872
+ *
873
+ * @returns A {@link FlagBuilder} for sizes in bytes.
874
+ *
875
+ * @example
876
+ * ```ts
877
+ * flag.bytes().default(10 * 1024 ** 2) // --max-size 512kb → 524288
878
+ * ```
879
+ */
880
+ bytes(): FlagBuilder<{
881
+ readonly valueType: number;
882
+ readonly presence: 'optional';
883
+ readonly optionalFallback: 'undefined';
884
+ readonly flagKind: 'custom';
885
+ }>;
886
+ /**
887
+ * Count flag — resolves to how many times the flag appears. `-vvv`,
888
+ * `-v -v -v`, and `--verbose --verbose --verbose` all yield `3`; absent
889
+ * yields `0`. An explicit value (`--verbose=2`, env, config) sets the
890
+ * count directly.
891
+ *
892
+ * Not promptable.
893
+ *
894
+ * @returns A {@link FlagBuilder} for occurrence counts (defaulted to `0`).
895
+ *
896
+ * @example
897
+ * ```ts
898
+ * flag.count().alias('v').describe('Increase verbosity')
899
+ * // $ mycli build -vv → verbose = 2
900
+ * ```
901
+ */
902
+ count(): FlagBuilder<{
903
+ readonly valueType: number;
904
+ readonly presence: 'defaulted';
905
+ readonly optionalFallback: 'undefined';
906
+ readonly flagKind: 'count';
907
+ }>;
908
+ /**
909
+ * Key-value flag — repeated `KEY=VALUE` occurrences merge into a
910
+ * `Record<string, string>` (docker/kubectl `--env` style). The value is
911
+ * split at the **first** `=`, so `--env A=b=c` yields `{ A: 'b=c' }`.
912
+ * Later occurrences of the same key win. Absent resolves to `{}`.
913
+ *
914
+ * Env vars accept separator-joined pairs (`A=1,B=2`); config files accept
915
+ * a plain object. Not promptable.
916
+ *
917
+ * @returns A {@link FlagBuilder} for `Record<string, string>` values.
918
+ *
919
+ * @example
920
+ * ```ts
921
+ * flag.keyValue().alias('e').describe('Environment variables')
922
+ * // $ mycli run -e A=1 -e B=2 → env = { A: '1', B: '2' }
923
+ * ```
924
+ */
925
+ keyValue(): FlagBuilder<{
926
+ readonly valueType: Record<string, string>;
927
+ readonly presence: 'optional';
928
+ readonly optionalFallback: 'empty-object';
929
+ readonly flagKind: 'keyValue';
930
+ }>;
604
931
  }
605
932
  /**
606
933
  * Flag schema factory. Call `flag.<kind>()` to create an immutable
@@ -608,4 +935,4 @@ interface FlagFactory {
608
935
  */
609
936
  declare const flag: FlagFactory;
610
937
  //#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 };
938
+ export { type AllowedPromptConfig, type ConfirmPromptConfig, type DateFlagOptions, 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 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, normalizeFlagAlias, normalizeFlagAliases };