@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 +1,705 @@
1
- import{assertNumberConstraints as e}from"./number-constraints.mjs";function t(e){return typeof e==`string`?{name:e,hidden:!1}:{name:e.name,hidden:e.hidden}}function n(e){return e.map(t)}function r(e,t){let n=t?.includeHidden??!1,r=t?.kind??`all`;return e.aliases.filter(e=>n||!e.hidden).filter(e=>r===`short`?e.name.length===1:r===`long`?e.name.length>1:!0).map(e=>e.name)}function i(e,t){let r=t?.aliases===void 0?[]:n(t.aliases),{aliases:i,...a}=t??{};return{kind:e,presence:`optional`,defaultValue:void 0,envVar:void 0,configPath:void 0,description:void 0,enumValues:void 0,numberConstraints:void 0,elementSchema:void 0,prompt:void 0,parseFn:void 0,deprecated:void 0,propagate:!1,...a,aliases:r}}var a=class t{schema;constructor(e){this.schema=e}default(e){return new t({...this.schema,presence:`defaulted`,defaultValue:e})}required(){return new t({...this.schema,presence:`required`})}alias(e,n){return new t({...this.schema,aliases:[...this.schema.aliases,{name:e,hidden:n?.hidden??!1}]})}env(e){return new t({...this.schema,envVar:e})}config(e){return new t({...this.schema,configPath:e})}describe(e){return new t({...this.schema,description:e})}prompt(e){return new t({...this.schema,prompt:e})}deprecated(e){return new t({...this.schema,deprecated:e??!0})}propagate(){return new t({...this.schema,propagate:!0})}int(e=!0){return new t({...this.schema,numberConstraints:{...this.schema.numberConstraints,int:e}})}min(n){let r={...this.schema.numberConstraints,min:n};return e(r),new t({...this.schema,numberConstraints:r})}max(n){let r={...this.schema.numberConstraints,max:n};return e(r),new t({...this.schema,numberConstraints:r})}finite(e=!0){return new t({...this.schema,numberConstraints:{...this.schema.numberConstraints,finite:e}})}};const o={string(){return new a(i(`string`))},number(t){return t!==void 0&&e(t),new a(i(`number`,t===void 0?{}:{numberConstraints:t}))},boolean(){return new a(i(`boolean`,{presence:`defaulted`,defaultValue:!1}))},enum(e){return new a(i(`enum`,{enumValues:e}))},array(e){return new a(i(`array`,{elementSchema:e.schema}))},custom(e){return new a(i(`custom`,{parseFn:e}))}};export{a as FlagBuilder,i as createSchema,o as flag,r as getFlagAliasNames};
1
+ import { assertNumberConstraints } from "./number-constraints.mjs";
2
+ import { assertStringConstraints } from "./string-constraints.mjs";
3
+ import { parseBytesValue, parseDateValue, parseDurationValue, parseUrlValue } from "./value-parsers.mjs";
4
+ //#region src/core/schema/flag.ts
5
+ /**
6
+ * Flag schema builder with full type inference.
7
+ *
8
+ * Each factory (`flag.string()`, `flag.boolean()`, etc.) returns an immutable
9
+ * {@linkcode FlagBuilder} whose generic parameter tracks the value type and presence
10
+ * state. Chained modifiers (`.default()`, `.required()`, `.alias()`, …) return
11
+ * new builders with updated type-level and runtime state.
12
+ *
13
+ * @module dreamcli/core/schema/flag
14
+ */
15
+ /**
16
+ * Normalise an alias input into a full {@link FlagAlias} object.
17
+ *
18
+ * @param alias - Raw alias name or structured alias object.
19
+ * @returns Normalised alias record.
20
+ */
21
+ function normalizeFlagAlias(alias) {
22
+ if (typeof alias === "string") return {
23
+ name: alias,
24
+ hidden: false
25
+ };
26
+ return {
27
+ name: alias.name,
28
+ hidden: alias.hidden
29
+ };
30
+ }
31
+ /**
32
+ * Normalise alias input into immutable alias records.
33
+ *
34
+ * @param aliases - Alias input values.
35
+ * @returns Normalised alias objects.
36
+ */
37
+ function normalizeFlagAliases(aliases) {
38
+ return aliases.map(normalizeFlagAlias);
39
+ }
40
+ /**
41
+ * List alias names for a flag schema.
42
+ *
43
+ * @param schema - Flag schema whose aliases should be listed.
44
+ * @param options - Visibility and length filtering.
45
+ * @returns Alias names in registration order.
46
+ */
47
+ function getFlagAliasNames(schema, options) {
48
+ const includeHidden = options?.includeHidden ?? false;
49
+ const kind = options?.kind ?? "all";
50
+ return schema.aliases.filter((alias) => includeHidden || !alias.hidden).filter((alias) => {
51
+ if (kind === "short") return alias.name.length === 1;
52
+ if (kind === "long") return alias.name.length > 1;
53
+ return true;
54
+ }).map((alias) => alias.name);
55
+ }
56
+ /**
57
+ * Effective negated spelling for a flag, or `undefined` when not negatable.
58
+ *
59
+ * The builder cannot know its flag name, so a default (`no-<name>`) is
60
+ * synthesized here — everywhere the canonical name is known (parser, help,
61
+ * completions, collision validation).
62
+ *
63
+ * @param name - Canonical flag name.
64
+ * @param schema - Flag schema (read for {@link FlagNegation}).
65
+ * @returns The negated spelling without the `--` prefix.
66
+ */
67
+ function getFlagNegatedName(name, schema) {
68
+ if (schema.negation === void 0) return void 0;
69
+ return schema.negation.alias ?? `no-${name}`;
70
+ }
71
+ /**
72
+ * Create a raw {@link FlagSchema} object with sensible defaults.
73
+ *
74
+ * Most consumers should prefer the higher-level {@link flag} factory,
75
+ * which returns an immutable {@link FlagBuilder} with type inference and
76
+ * safe modifier chaining. `createSchema()` is the low-level escape hatch
77
+ * for advanced schema composition, tests, or custom factories that need to
78
+ * work directly with the runtime descriptor.
79
+ *
80
+ * `overrides` are shallow-merged on top of the default shape, so callers are
81
+ * responsible for keeping the resulting schema internally consistent.
82
+ *
83
+ * @param kind - Discriminator for the value type this flag accepts.
84
+ * @param overrides - Partial {@link FlagSchema} fields merged onto defaults.
85
+ * @returns A fully populated {@link FlagSchema}.
86
+ *
87
+ * @example
88
+ * ```ts
89
+ * const schema = createSchema('enum', {
90
+ * enumValues: ['us', 'eu', 'ap'],
91
+ * description: 'Deployment region',
92
+ * });
93
+ * ```
94
+ */
95
+ function createSchema(kind, overrides) {
96
+ const aliases = overrides?.aliases !== void 0 ? normalizeFlagAliases(overrides.aliases) : [];
97
+ const { aliases: _ignoredAliases, ...rest } = overrides ?? {};
98
+ return {
99
+ kind,
100
+ presence: "optional",
101
+ defaultValue: void 0,
102
+ envVar: void 0,
103
+ configPath: void 0,
104
+ description: void 0,
105
+ enumValues: void 0,
106
+ numberConstraints: void 0,
107
+ stringConstraints: void 0,
108
+ elementSchema: void 0,
109
+ separator: void 0,
110
+ unique: false,
111
+ pathChecks: void 0,
112
+ valueHint: void 0,
113
+ prompt: void 0,
114
+ parseFn: void 0,
115
+ deprecated: void 0,
116
+ propagate: false,
117
+ negation: void 0,
118
+ duplicates: "last",
119
+ ...rest,
120
+ aliases
121
+ };
122
+ }
123
+ /**
124
+ * Immutable flag schema builder.
125
+ *
126
+ * The type parameter `C` is a phantom that tracks the value type and presence
127
+ * through the fluent chain. Each modifier returns a **new** builder — the
128
+ * original is never mutated.
129
+ *
130
+ * @example
131
+ * ```ts
132
+ * const port = flag.number().default(8080);
133
+ * type Port = InferFlag<typeof port>; // number
134
+ *
135
+ * const region = flag.enum(['us', 'eu', 'ap']);
136
+ * type Region = InferFlag<typeof region>; // 'us' | 'eu' | 'ap' | undefined
137
+ * ```
138
+ */
139
+ var FlagBuilder = class FlagBuilder {
140
+ /** @internal Runtime schema descriptor. */
141
+ schema;
142
+ /**
143
+ * Create a flag builder from a pre-built schema descriptor.
144
+ *
145
+ * @param schema - Runtime descriptor seeding this builder's state.
146
+ */
147
+ constructor(schema) {
148
+ this.schema = schema;
149
+ }
150
+ /**
151
+ * Provide a default value. The flag becomes "always present" — handlers
152
+ * will never see `undefined`.
153
+ *
154
+ * The generic constraint `V extends C['valueType']` ensures the default
155
+ * matches the flag's declared type.
156
+ *
157
+ * @param value - Fallback value used when no source provides one.
158
+ * @returns The builder (for chaining).
159
+ *
160
+ * @example
161
+ * ```ts
162
+ * flag.number().default(8080).describe('Port to listen on')
163
+ *
164
+ * // $ mycli serve → port = 8080
165
+ * // $ mycli serve --port 443 → port = 443
166
+ * ```
167
+ */
168
+ default(value) {
169
+ return new FlagBuilder({
170
+ ...this.schema,
171
+ presence: "defaulted",
172
+ defaultValue: value
173
+ });
174
+ }
175
+ /**
176
+ * Mark the flag as required. If not resolved from any source the framework
177
+ * will emit a `ValidationError` before the action handler runs.
178
+ *
179
+ * @returns The builder (for chaining).
180
+ *
181
+ * @example
182
+ * ```ts
183
+ * flag.string().required().describe('Deploy target')
184
+ *
185
+ * // $ mycli deploy
186
+ * // # → Error: Missing required flag --target
187
+ * // $ mycli deploy --target staging
188
+ * // # → target = 'staging'
189
+ * ```
190
+ */
191
+ required() {
192
+ return new FlagBuilder({
193
+ ...this.schema,
194
+ presence: "required"
195
+ });
196
+ }
197
+ /**
198
+ * Add a short or long alias (e.g. `'f'` for `--force`, `'verbose'` as an
199
+ * alternative long name).
200
+ *
201
+ * @param name - Single-char short alias or alternative long name.
202
+ * @param options - Optional alias metadata. Hidden aliases remain parseable
203
+ * but are omitted from help, completions, and suggestions.
204
+ * @returns The builder (for chaining).
205
+ *
206
+ * @example
207
+ * ```ts
208
+ * flag.boolean().alias('v').describe('Enable verbose output')
209
+ *
210
+ * // $ mycli build -v → verbose = true
211
+ * // $ mycli build --verbose → verbose = true
212
+ * ```
213
+ */
214
+ alias(name, options) {
215
+ return new FlagBuilder({
216
+ ...this.schema,
217
+ aliases: [...this.schema.aliases, {
218
+ name,
219
+ hidden: options?.hidden ?? false
220
+ }]
221
+ });
222
+ }
223
+ /**
224
+ * Bind to an environment variable (resolved in v0.2+).
225
+ *
226
+ * @param varName - Environment variable name (e.g. `'PORT'`).
227
+ * @returns The builder (for chaining).
228
+ *
229
+ * @example
230
+ * ```ts
231
+ * flag.string().env('API_KEY').describe('Service API key')
232
+ *
233
+ * // $ API_KEY=sk-123 mycli request → apiKey = 'sk-123'
234
+ * // $ mycli request --api-key sk-456 → apiKey = 'sk-456' (CLI wins)
235
+ * ```
236
+ */
237
+ env(varName) {
238
+ return new FlagBuilder({
239
+ ...this.schema,
240
+ envVar: varName
241
+ });
242
+ }
243
+ /**
244
+ * Bind to a dotted config path (resolved in v0.2+).
245
+ *
246
+ * @param path - Dotted config key (e.g. `'deploy.region'`).
247
+ * @returns The builder (for chaining).
248
+ *
249
+ * @example
250
+ * ```ts
251
+ * flag.string().config('deploy.region').default('us-east-1')
252
+ * // Config file: { "deploy": { "region": "eu-west-1" } }
253
+ * // $ mycli deploy
254
+ * // # → region = 'eu-west-1' (from config)
255
+ * // $ mycli deploy --region ap-south-1
256
+ * // # → CLI flag wins
257
+ * ```
258
+ */
259
+ config(path) {
260
+ return new FlagBuilder({
261
+ ...this.schema,
262
+ configPath: path
263
+ });
264
+ }
265
+ /**
266
+ * Human-readable description shown in help output.
267
+ *
268
+ * @param description - Text displayed next to the flag in `--help`.
269
+ * @returns The builder (for chaining).
270
+ */
271
+ describe(description) {
272
+ return new FlagBuilder({
273
+ ...this.schema,
274
+ description
275
+ });
276
+ }
277
+ /**
278
+ * Attach interactive prompt configuration for v0.3+ resolution.
279
+ *
280
+ * When a flag value is not resolved from CLI, env, or config, the
281
+ * prompt engine uses this config to interactively ask the user.
282
+ * In non-interactive contexts (CI, piped stdin) prompts are skipped
283
+ * and resolution falls through to default or required validation.
284
+ *
285
+ * @param config - {@link PromptConfig} describing the interactive prompt.
286
+ * @returns The builder (for chaining).
287
+ *
288
+ * @example
289
+ * ```ts
290
+ * flag.string().prompt({ kind: 'input', message: 'Enter value:' })
291
+ *
292
+ * // $ mycli init → prompts "Enter value:" interactively
293
+ * // $ mycli init --name foo → skips prompt, uses CLI value
294
+ * ```
295
+ */
296
+ prompt(config) {
297
+ return new FlagBuilder({
298
+ ...this.schema,
299
+ prompt: config
300
+ });
301
+ }
302
+ /**
303
+ * Mark this flag as deprecated.
304
+ *
305
+ * When used, a warning is emitted to stderr. Help text shows
306
+ * `[deprecated]` or `[deprecated: <reason>]`.
307
+ *
308
+ * Does not change the flag's type-level config — it's metadata only.
309
+ *
310
+ * @param message - Optional migration reason/guidance.
311
+ * @returns The builder (for chaining).
312
+ *
313
+ * @example
314
+ * ```ts
315
+ * flag.string().deprecated('Use --target instead')
316
+ *
317
+ * // $ mycli deploy --dest staging
318
+ * // ⚠ --dest is deprecated: Use --target instead
319
+ * ```
320
+ */
321
+ deprecated(message) {
322
+ return new FlagBuilder({
323
+ ...this.schema,
324
+ deprecated: message ?? true
325
+ });
326
+ }
327
+ /**
328
+ * Mark this flag as propagated to subcommands.
329
+ *
330
+ * Propagated flags are automatically available to all descendant
331
+ * commands in a nested command tree. A child command that defines
332
+ * a flag with the same name shadows the propagated parent flag.
333
+ *
334
+ * Does not change the flag's type-level config — it's metadata only.
335
+ *
336
+ * @returns The builder (for chaining).
337
+ *
338
+ * @example
339
+ * ```ts
340
+ * flag.boolean().alias('v').propagate().describe('Enable verbose output')
341
+ *
342
+ * // $ mycli --verbose deploy staging
343
+ * // # → verbose = true in deploy handler
344
+ * // $ mycli deploy --verbose staging
345
+ * // # → same, inherited from parent
346
+ * ```
347
+ */
348
+ propagate() {
349
+ return new FlagBuilder({
350
+ ...this.schema,
351
+ propagate: true
352
+ });
353
+ }
354
+ /**
355
+ * Require an integer value. Composes with other numeric constraints.
356
+ *
357
+ * @param value - Whether to require an integer.
358
+ * @defaultValue `true`
359
+ * @returns The builder (for chaining).
360
+ *
361
+ * @example
362
+ * ```ts
363
+ * flag.number().int() // rejects 3.7, accepts 3
364
+ * flag.number({ int: true }).int(false) // re-allows non-integers
365
+ * ```
366
+ */
367
+ int(value = true) {
368
+ return new FlagBuilder({
369
+ ...this.schema,
370
+ numberConstraints: {
371
+ ...this.schema.numberConstraints,
372
+ int: value
373
+ }
374
+ });
375
+ }
376
+ /**
377
+ * Set an inclusive lower bound. Composes with other numeric constraints;
378
+ * a later call overrides an earlier `min` (including one from the options
379
+ * object).
380
+ *
381
+ * @param value - Inclusive minimum.
382
+ * @returns The builder (for chaining).
383
+ *
384
+ * @example
385
+ * ```ts
386
+ * flag.number().min(0) // rejects -1, accepts 0
387
+ * flag.number({ min: 0 }).min(5) // effective min is 5
388
+ * ```
389
+ */
390
+ min(value) {
391
+ const numberConstraints = {
392
+ ...this.schema.numberConstraints,
393
+ min: value
394
+ };
395
+ assertNumberConstraints(numberConstraints);
396
+ return new FlagBuilder({
397
+ ...this.schema,
398
+ numberConstraints
399
+ });
400
+ }
401
+ /**
402
+ * Set an inclusive upper bound. Composes with other numeric constraints;
403
+ * a later call overrides an earlier `max`.
404
+ *
405
+ * @param value - Inclusive maximum.
406
+ * @returns The builder (for chaining).
407
+ *
408
+ * @example
409
+ * ```ts
410
+ * flag.number().max(100) // rejects 101, accepts 100
411
+ * ```
412
+ */
413
+ max(value) {
414
+ const numberConstraints = {
415
+ ...this.schema.numberConstraints,
416
+ max: value
417
+ };
418
+ assertNumberConstraints(numberConstraints);
419
+ return new FlagBuilder({
420
+ ...this.schema,
421
+ numberConstraints
422
+ });
423
+ }
424
+ /**
425
+ * Require (or, with `false`, allow) a finite value. Finiteness is enforced
426
+ * by default, so this is mainly used as `.finite(false)` to re-allow
427
+ * `Infinity` / `-Infinity`.
428
+ *
429
+ * @param allow - Whether to require a finite value.
430
+ * @defaultValue `true`
431
+ * @returns The builder (for chaining).
432
+ *
433
+ * @example
434
+ * ```ts
435
+ * flag.number().finite(false) // accepts Infinity
436
+ * ```
437
+ */
438
+ finite(allow = true) {
439
+ return new FlagBuilder({
440
+ ...this.schema,
441
+ numberConstraints: {
442
+ ...this.schema.numberConstraints,
443
+ finite: allow
444
+ }
445
+ });
446
+ }
447
+ /**
448
+ * Reject empty strings. Composes with other string constraints.
449
+ *
450
+ * @param value - Whether to reject empty strings.
451
+ * @defaultValue `true`
452
+ * @returns The builder (for chaining).
453
+ *
454
+ * @example
455
+ * ```ts
456
+ * flag.string().nonEmpty() // rejects '', accepts 'x'
457
+ * ```
458
+ */
459
+ nonEmpty(value = true) {
460
+ return new FlagBuilder({
461
+ ...this.schema,
462
+ stringConstraints: {
463
+ ...this.schema.stringConstraints,
464
+ nonEmpty: value
465
+ }
466
+ });
467
+ }
468
+ /**
469
+ * Set an inclusive minimum length (UTF-16 code units). Composes with other
470
+ * string constraints; a later call overrides an earlier `minLength`.
471
+ *
472
+ * @param value - Inclusive minimum length.
473
+ * @returns The builder (for chaining).
474
+ *
475
+ * @example
476
+ * ```ts
477
+ * flag.string().minLength(3) // rejects 'ab', accepts 'abc'
478
+ * ```
479
+ */
480
+ minLength(value) {
481
+ const stringConstraints = {
482
+ ...this.schema.stringConstraints,
483
+ minLength: value
484
+ };
485
+ assertStringConstraints(stringConstraints);
486
+ return new FlagBuilder({
487
+ ...this.schema,
488
+ stringConstraints
489
+ });
490
+ }
491
+ /**
492
+ * Set an inclusive maximum length (UTF-16 code units). Composes with other
493
+ * string constraints; a later call overrides an earlier `maxLength`.
494
+ *
495
+ * @param value - Inclusive maximum length.
496
+ * @returns The builder (for chaining).
497
+ *
498
+ * @example
499
+ * ```ts
500
+ * flag.string().maxLength(8) // rejects 9+ chars
501
+ * ```
502
+ */
503
+ maxLength(value) {
504
+ const stringConstraints = {
505
+ ...this.schema.stringConstraints,
506
+ maxLength: value
507
+ };
508
+ assertStringConstraints(stringConstraints);
509
+ return new FlagBuilder({
510
+ ...this.schema,
511
+ stringConstraints
512
+ });
513
+ }
514
+ /**
515
+ * Require the value to match a regular expression. Anchor with `^`/`$`
516
+ * for full-string matching. Composes with other string constraints.
517
+ *
518
+ * @param value - Pattern the value must match.
519
+ * @returns The builder (for chaining).
520
+ *
521
+ * @example
522
+ * ```ts
523
+ * flag.string().pattern(/^ghp_/) // rejects 'abc', accepts 'ghp_x'
524
+ * ```
525
+ */
526
+ pattern(value) {
527
+ return new FlagBuilder({
528
+ ...this.schema,
529
+ stringConstraints: {
530
+ ...this.schema.stringConstraints,
531
+ pattern: value
532
+ }
533
+ });
534
+ }
535
+ /**
536
+ * Split each CLI occurrence on a separator before element coercion, so
537
+ * `--tag a,b --tag c` resolves to `['a', 'b', 'c']`. Elements are coerced
538
+ * (and rejected) individually with the element schema's own error format.
539
+ *
540
+ * Env and config string values are split on the same separator (their
541
+ * default split is `','` even without this modifier).
542
+ *
543
+ * @param value - Separator string (e.g. `','`).
544
+ * @returns The builder (for chaining).
545
+ *
546
+ * @example
547
+ * ```ts
548
+ * flag.array(flag.enum(['us', 'eu', 'ap'])).separator(',')
549
+ * // --region us,eu --region ap → ['us', 'eu', 'ap']
550
+ * ```
551
+ */
552
+ separator(value) {
553
+ if (value.length === 0) throw new RangeError("array separator must not be empty");
554
+ return new FlagBuilder({
555
+ ...this.schema,
556
+ separator: value
557
+ });
558
+ }
559
+ /**
560
+ * Deduplicate the resolved array, preserving first-seen order. Applied
561
+ * after all sources resolve, using `SameValueZero` semantics (like `Set`).
562
+ *
563
+ * @param value - Whether to deduplicate.
564
+ * @defaultValue `true`
565
+ * @returns The builder (for chaining).
566
+ *
567
+ * @example
568
+ * ```ts
569
+ * flag.array(flag.string()).separator(',').unique()
570
+ * // --tag a,a --tag a → ['a']
571
+ * ```
572
+ */
573
+ unique(value = true) {
574
+ return new FlagBuilder({
575
+ ...this.schema,
576
+ unique: value
577
+ });
578
+ }
579
+ /**
580
+ * Accept a negated spelling (`--no-<name>`) that sets the flag to `false`.
581
+ *
582
+ * Both spellings are ONE logical flag: the last CLI occurrence wins across
583
+ * them, and they share the duplicate policy. The negated spelling is
584
+ * presence-only — `--no-<name>=true` is rejected. Help renders the flag as
585
+ * `--[no-]<name>` (or lists a custom alias); env/config/prompt/default
586
+ * resolution is unaffected.
587
+ *
588
+ * @param options - Optional custom spelling (`alias`, without `--`) and
589
+ * `hidden` to keep the negated spelling parseable but unadvertised.
590
+ * @returns The builder (for chaining).
591
+ *
592
+ * @example
593
+ * ```ts
594
+ * flag.boolean().default(true).negatable()
595
+ * // $ mycli build --no-sandbox → sandbox = false
596
+ * // $ mycli build --sandbox → sandbox = true
597
+ * ```
598
+ */
599
+ negatable(options) {
600
+ return new FlagBuilder({
601
+ ...this.schema,
602
+ negation: {
603
+ alias: options?.alias,
604
+ hidden: options?.hidden ?? false
605
+ }
606
+ });
607
+ }
608
+ /**
609
+ * Set how repeated CLI occurrences of this flag combine.
610
+ *
611
+ * Counted per logical flag — aliases and the negated spelling all count
612
+ * toward the same flag. CLI tokens only: env/config/prompt/default
613
+ * resolution keeps its precedence semantics. Not available on `array`,
614
+ * `count`, or `keyValue` flags, which inherently accumulate.
615
+ *
616
+ * @param policy - `'last'` (default), `'first'`, or `'error'`.
617
+ * @returns The builder (for chaining).
618
+ *
619
+ * @example
620
+ * ```ts
621
+ * flag.enum(['session', 'same-dir', 'worktree']).duplicates('error')
622
+ * // $ mycli run --spawn session --spawn worktree
623
+ * // # → Error: Flag --spawn may only be specified once
624
+ * ```
625
+ */
626
+ duplicates(policy) {
627
+ return new FlagBuilder({
628
+ ...this.schema,
629
+ duplicates: policy
630
+ });
631
+ }
632
+ };
633
+ /**
634
+ * Flag schema factory. Call `flag.<kind>()` to create an immutable
635
+ * {@link FlagBuilder} with full type inference and safe modifier chaining.
636
+ */
637
+ const flag = {
638
+ string(constraints) {
639
+ if (constraints !== void 0) assertStringConstraints(constraints);
640
+ return new FlagBuilder(createSchema("string", constraints !== void 0 ? { stringConstraints: constraints } : {}));
641
+ },
642
+ number(constraints) {
643
+ if (constraints !== void 0) assertNumberConstraints(constraints);
644
+ return new FlagBuilder(createSchema("number", constraints !== void 0 ? { numberConstraints: constraints } : {}));
645
+ },
646
+ boolean() {
647
+ return new FlagBuilder(createSchema("boolean", {
648
+ presence: "defaulted",
649
+ defaultValue: false
650
+ }));
651
+ },
652
+ enum(values) {
653
+ return new FlagBuilder(createSchema("enum", { enumValues: values }));
654
+ },
655
+ array(element) {
656
+ return new FlagBuilder(createSchema("array", { elementSchema: element.schema }));
657
+ },
658
+ custom(parseFn) {
659
+ return new FlagBuilder(createSchema("custom", { parseFn }));
660
+ },
661
+ url(options) {
662
+ return new FlagBuilder(createSchema("custom", {
663
+ parseFn: (raw) => parseUrlValue(raw, options),
664
+ valueHint: "url"
665
+ }));
666
+ },
667
+ path(options) {
668
+ return new FlagBuilder(createSchema("string", {
669
+ pathChecks: options?.mustExist === true || options?.type !== void 0 ? {
670
+ mustExist: options.mustExist ?? true,
671
+ type: options.type
672
+ } : void 0,
673
+ valueHint: "path"
674
+ }));
675
+ },
676
+ date(options) {
677
+ return new FlagBuilder(createSchema("custom", {
678
+ parseFn: (raw) => parseDateValue(raw, options),
679
+ valueHint: "date"
680
+ }));
681
+ },
682
+ duration() {
683
+ return new FlagBuilder(createSchema("custom", {
684
+ parseFn: parseDurationValue,
685
+ valueHint: "duration"
686
+ }));
687
+ },
688
+ bytes() {
689
+ return new FlagBuilder(createSchema("custom", {
690
+ parseFn: parseBytesValue,
691
+ valueHint: "size"
692
+ }));
693
+ },
694
+ count() {
695
+ return new FlagBuilder(createSchema("count", {
696
+ presence: "defaulted",
697
+ defaultValue: 0
698
+ }));
699
+ },
700
+ keyValue() {
701
+ return new FlagBuilder(createSchema("keyValue", { valueHint: "key=value" }));
702
+ }
703
+ };
704
+ //#endregion
705
+ export { FlagBuilder, createSchema, flag, getFlagAliasNames, getFlagNegatedName, normalizeFlagAlias, normalizeFlagAliases };