@kjanat/dreamcli 2.5.0 → 3.0.0-rc.2

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 (160) hide show
  1. package/CHANGELOG.md +153 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/dispatch.mjs +214 -1
  4. package/dist/core/cli/help-links.mjs +41 -1
  5. package/dist/core/cli/index.d.mts +109 -16
  6. package/dist/core/cli/index.mjs +901 -1
  7. package/dist/core/cli/planner.d.mts +27 -5
  8. package/dist/core/cli/planner.mjs +300 -1
  9. package/dist/core/cli/plugin.mjs +41 -1
  10. package/dist/core/cli/propagate.mjs +57 -1
  11. package/dist/core/cli/root-help.d.mts +16 -2
  12. package/dist/core/cli/root-help.mjs +208 -6
  13. package/dist/core/cli/root-surface.d.mts +18 -3
  14. package/dist/core/cli/root-surface.mjs +27 -1
  15. package/dist/core/cli/runtime-preflight.d.mts +16 -1
  16. package/dist/core/cli/runtime-preflight.mjs +168 -1
  17. package/dist/core/completion/index.d.mts +32 -1
  18. package/dist/core/completion/index.mjs +90 -1
  19. package/dist/core/completion/shells/bash.mjs +304 -3
  20. package/dist/core/completion/shells/fish.mjs +159 -2
  21. package/dist/core/completion/shells/powershell.mjs +353 -2
  22. package/dist/core/completion/shells/shared.d.mts +10 -0
  23. package/dist/core/completion/shells/shared.mjs +154 -1
  24. package/dist/core/completion/shells/zsh.mjs +244 -2
  25. package/dist/core/config/index.mjs +246 -1
  26. package/dist/core/config/package-json.mjs +385 -3
  27. package/dist/core/errors/index.mjs +87 -1
  28. package/dist/core/execution/index.mjs +189 -1
  29. package/dist/core/help/ansi.mjs +122 -2
  30. package/dist/core/help/index.d.mts +45 -1
  31. package/dist/core/help/index.mjs +329 -7
  32. package/dist/core/json-schema/index.mjs +487 -9
  33. package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
  34. package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
  35. package/dist/core/output/activity.mjs +452 -1
  36. package/dist/core/output/bind.mjs +56 -1
  37. package/dist/core/output/contracts.mjs +57 -1
  38. package/dist/core/output/display-value.mjs +32 -1
  39. package/dist/core/output/index.d.mts +21 -0
  40. package/dist/core/output/index.mjs +442 -2
  41. package/dist/core/output/renderers.mjs +46 -1
  42. package/dist/core/output/writer.mjs +12 -1
  43. package/dist/core/parse/index.d.mts +15 -1
  44. package/dist/core/parse/index.mjs +555 -1
  45. package/dist/core/prompt/index.d.mts +11 -4
  46. package/dist/core/prompt/index.mjs +348 -6
  47. package/dist/core/resolve/args.mjs +105 -1
  48. package/dist/core/resolve/coerce.mjs +279 -1
  49. package/dist/core/resolve/config.mjs +19 -1
  50. package/dist/core/resolve/errors.mjs +140 -2
  51. package/dist/core/resolve/flags.mjs +196 -1
  52. package/dist/core/resolve/index.mjs +85 -1
  53. package/dist/core/resolve/property.d.mts +2 -1
  54. package/dist/core/resolve/property.mjs +45 -1
  55. package/dist/core/schema/arg.d.mts +90 -10
  56. package/dist/core/schema/arg.mjs +463 -1
  57. package/dist/core/schema/command.d.mts +21 -1
  58. package/dist/core/schema/command.mjs +712 -1
  59. package/dist/core/schema/flag.d.mts +92 -2
  60. package/dist/core/schema/flag.mjs +453 -1
  61. package/dist/core/schema/index.d.mts +2 -1
  62. package/dist/core/schema/middleware.mjs +41 -1
  63. package/dist/core/schema/number-constraints.d.mts +96 -0
  64. package/dist/core/schema/number-constraints.mjs +60 -0
  65. package/dist/core/schema/prompt.d.mts +15 -0
  66. package/dist/core/schema/run.d.mts +4 -4
  67. package/dist/core/schema-dsl/runtime.mjs +271 -2
  68. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  69. package/dist/core/testkit/index.d.mts +9 -5
  70. package/dist/core/testkit/index.mjs +83 -1
  71. package/dist/index.d.mts +3 -1
  72. package/dist/index.mjs +22 -1
  73. package/dist/runtime/adapter.mjs +82 -1
  74. package/dist/runtime/auto.mjs +46 -1
  75. package/dist/runtime/bun.mjs +28 -1
  76. package/dist/runtime/deno.mjs +217 -2
  77. package/dist/runtime/detect.mjs +45 -1
  78. package/dist/runtime/node.mjs +169 -2
  79. package/dist/runtime/paths.mjs +48 -1
  80. package/dist/runtime.mjs +7 -1
  81. package/dist/strings.mjs +22 -1
  82. package/dist/testkit.mjs +5 -1
  83. package/dist/version.mjs +7 -1
  84. package/examples/basic.ts +5 -1
  85. package/examples/gh/package.json +2 -7
  86. package/examples/pwsh-demo/package.json +1 -7
  87. package/examples/pwsh-demo/src/main.test.ts +1 -4
  88. package/examples/pwsh-demo/src/main.ts +14 -4
  89. package/examples/transport-launcher.ts +85 -0
  90. package/package.json +23 -41
  91. package/dist/runtime/support.d.mts +0 -42
  92. package/dist/runtime/support.mjs +0 -1
  93. package/src/core/cli/dispatch.ts +0 -349
  94. package/src/core/cli/help-links.ts +0 -82
  95. package/src/core/cli/index.ts +0 -1413
  96. package/src/core/cli/planner.ts +0 -487
  97. package/src/core/cli/plugin.ts +0 -117
  98. package/src/core/cli/propagate.ts +0 -97
  99. package/src/core/cli/root-help.ts +0 -252
  100. package/src/core/cli/root-surface.ts +0 -74
  101. package/src/core/cli/runtime-preflight.ts +0 -438
  102. package/src/core/completion/index.ts +0 -88
  103. package/src/core/completion/shells/bash.ts +0 -459
  104. package/src/core/completion/shells/fish.ts +0 -259
  105. package/src/core/completion/shells/powershell.ts +0 -439
  106. package/src/core/completion/shells/shared.ts +0 -283
  107. package/src/core/completion/shells/zsh.ts +0 -381
  108. package/src/core/config/index.ts +0 -417
  109. package/src/core/config/package-json.ts +0 -560
  110. package/src/core/errors/index.ts +0 -193
  111. package/src/core/execution/index.ts +0 -268
  112. package/src/core/help/ansi.ts +0 -144
  113. package/src/core/help/index.ts +0 -516
  114. package/src/core/json-schema/index.ts +0 -891
  115. package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
  116. package/src/core/output/activity.ts +0 -575
  117. package/src/core/output/bind.ts +0 -59
  118. package/src/core/output/contracts.ts +0 -194
  119. package/src/core/output/display-value.ts +0 -48
  120. package/src/core/output/index.ts +0 -704
  121. package/src/core/output/renderers.ts +0 -125
  122. package/src/core/output/writer.ts +0 -46
  123. package/src/core/parse/index.ts +0 -681
  124. package/src/core/prompt/index.ts +0 -583
  125. package/src/core/resolve/args.ts +0 -144
  126. package/src/core/resolve/coerce.ts +0 -432
  127. package/src/core/resolve/config.ts +0 -26
  128. package/src/core/resolve/contracts.ts +0 -135
  129. package/src/core/resolve/errors.ts +0 -227
  130. package/src/core/resolve/flags.ts +0 -255
  131. package/src/core/resolve/index.ts +0 -108
  132. package/src/core/resolve/property.ts +0 -99
  133. package/src/core/schema/activity.ts +0 -240
  134. package/src/core/schema/arg.ts +0 -719
  135. package/src/core/schema/command.ts +0 -1498
  136. package/src/core/schema/flag.ts +0 -801
  137. package/src/core/schema/index.ts +0 -91
  138. package/src/core/schema/middleware.ts +0 -171
  139. package/src/core/schema/prompt.ts +0 -156
  140. package/src/core/schema/run.ts +0 -198
  141. package/src/core/schema-dsl/index.ts +0 -109
  142. package/src/core/schema-dsl/parse.ts +0 -262
  143. package/src/core/schema-dsl/runtime.ts +0 -609
  144. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  145. package/src/core/testkit/index.ts +0 -123
  146. package/src/index.ts +0 -179
  147. package/src/runtime/adapter.ts +0 -303
  148. package/src/runtime/auto.ts +0 -110
  149. package/src/runtime/bun.ts +0 -55
  150. package/src/runtime/deno.ts +0 -369
  151. package/src/runtime/detect.ts +0 -105
  152. package/src/runtime/index.ts +0 -21
  153. package/src/runtime/node-builtins.d.ts +0 -27
  154. package/src/runtime/node.ts +0 -300
  155. package/src/runtime/paths.ts +0 -64
  156. package/src/runtime/support.ts +0 -135
  157. package/src/runtime.ts +0 -31
  158. package/src/strings.ts +0 -34
  159. package/src/testkit.ts +0 -25
  160. package/src/version.ts +0 -20
@@ -1,3 +1,4 @@
1
+ import { NumberConstraints } from "./number-constraints.mjs";
1
2
  import { ConfirmPromptConfig, InputPromptConfig, MultiselectPromptConfig, PROMPT_KINDS, PromptConfig, PromptConfigBase, PromptKind, PromptResult, SelectChoice, SelectPromptConfig } from "./prompt.mjs";
2
3
 
3
4
  //#region src/core/schema/flag.d.ts
@@ -123,6 +124,13 @@ interface FlagSchema {
123
124
  readonly description: string | undefined;
124
125
  /** Allowed literal values when `kind === 'enum'`. */
125
126
  readonly enumValues: readonly string[] | undefined;
127
+ /**
128
+ * Numeric constraints when `kind === 'number'` (`undefined` otherwise).
129
+ *
130
+ * Enforced at the parse and resolution boundaries. `finite` defaults to
131
+ * `true`, so `Infinity` is rejected even when no constraints object is set.
132
+ */
133
+ readonly numberConstraints: NumberConstraints | undefined;
126
134
  /** Element schema when `kind === 'array'`. */
127
135
  readonly elementSchema: FlagSchema | undefined;
128
136
  /** Interactive prompt configuration for v0.3+ resolution. */
@@ -397,6 +405,71 @@ declare class FlagBuilder<C extends FlagConfig> {
397
405
  * ```
398
406
  */
399
407
  propagate(): FlagBuilder<C>;
408
+ /**
409
+ * Require an integer value. Composes with other numeric constraints.
410
+ *
411
+ * @param value - Whether to require an integer.
412
+ * @defaultValue `true`
413
+ * @returns The builder (for chaining).
414
+ *
415
+ * @example
416
+ * ```ts
417
+ * flag.number().int() // rejects 3.7, accepts 3
418
+ * flag.number({ int: true }).int(false) // re-allows non-integers
419
+ * ```
420
+ */
421
+ int(this: FlagBuilder<C & {
422
+ readonly flagKind: 'number';
423
+ }>, value?: boolean): FlagBuilder<C>;
424
+ /**
425
+ * Set an inclusive lower bound. Composes with other numeric constraints;
426
+ * a later call overrides an earlier `min` (including one from the options
427
+ * object).
428
+ *
429
+ * @param value - Inclusive minimum.
430
+ * @returns The builder (for chaining).
431
+ *
432
+ * @example
433
+ * ```ts
434
+ * flag.number().min(0) // rejects -1, accepts 0
435
+ * flag.number({ min: 0 }).min(5) // effective min is 5
436
+ * ```
437
+ */
438
+ min(this: FlagBuilder<C & {
439
+ readonly flagKind: 'number';
440
+ }>, value: number): FlagBuilder<C>;
441
+ /**
442
+ * Set an inclusive upper bound. Composes with other numeric constraints;
443
+ * a later call overrides an earlier `max`.
444
+ *
445
+ * @param value - Inclusive maximum.
446
+ * @returns The builder (for chaining).
447
+ *
448
+ * @example
449
+ * ```ts
450
+ * flag.number().max(100) // rejects 101, accepts 100
451
+ * ```
452
+ */
453
+ max(this: FlagBuilder<C & {
454
+ readonly flagKind: 'number';
455
+ }>, value: number): FlagBuilder<C>;
456
+ /**
457
+ * Require (or, with `false`, allow) a finite value. Finiteness is enforced
458
+ * by default, so this is mainly used as `.finite(false)` to re-allow
459
+ * `Infinity` / `-Infinity`.
460
+ *
461
+ * @param allow - Whether to require a finite value.
462
+ * @defaultValue `true`
463
+ * @returns The builder (for chaining).
464
+ *
465
+ * @example
466
+ * ```ts
467
+ * flag.number().finite(false) // accepts Infinity
468
+ * ```
469
+ */
470
+ finite(this: FlagBuilder<C & {
471
+ readonly flagKind: 'number';
472
+ }>, allow?: boolean): FlagBuilder<C>;
400
473
  }
401
474
  /**
402
475
  * Factory that creates {@link FlagBuilder} instances seeded with the correct
@@ -415,11 +488,28 @@ interface FlagFactory {
415
488
  readonly flagKind: 'string';
416
489
  }>;
417
490
  /**
418
- * Number-valued flag.
491
+ * Number-valued flag, with optional numeric constraints.
492
+ *
493
+ * Constraints are enforced at the parse and resolution boundaries. The
494
+ * resolved value type stays `number` — constraints are runtime + schema, not
495
+ * type-level. Bounds are inclusive.
419
496
  *
497
+ * Constraints also compose via chained methods (`.int()`, `.min()`,
498
+ * `.max()`, `.finite()`), which override values set here.
499
+ *
500
+ * @param constraints - Optional numeric constraints. `finite` defaults to
501
+ * `true`, so `Infinity` / `-Infinity` are rejected unless `finite: false`.
502
+ * @defaultValue `undefined` (finite-only, no bounds, non-integer allowed)
420
503
  * @returns A {@link FlagBuilder} for `number` values.
504
+ *
505
+ * @example
506
+ * ```ts
507
+ * flag.number() // finite numbers only
508
+ * flag.number({ int: true, min: 0 }) // non-negative integers
509
+ * flag.number({ finite: false }) // also accepts Infinity
510
+ * ```
421
511
  */
422
- number(): FlagBuilder<{
512
+ number(constraints?: NumberConstraints): FlagBuilder<{
423
513
  readonly valueType: number;
424
514
  readonly presence: 'optional';
425
515
  readonly optionalFallback: 'undefined';
@@ -1 +1,453 @@
1
- function e(e){return typeof e==`string`?{name:e,hidden:!1}:{name:e.name,hidden:e.hidden}}function t(t){return t.map(e)}function n(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 r(e,n){let r=n?.aliases===void 0?[]:t(n.aliases),{aliases:i,...a}=n??{};return{kind:e,presence:`optional`,defaultValue:void 0,envVar:void 0,configPath:void 0,description:void 0,enumValues:void 0,elementSchema:void 0,prompt:void 0,parseFn:void 0,deprecated:void 0,propagate:!1,...a,aliases:r}}var i=class e{schema;constructor(e){this.schema=e}default(t){return new e({...this.schema,presence:`defaulted`,defaultValue:t})}required(){return new e({...this.schema,presence:`required`})}alias(t,n){return new e({...this.schema,aliases:[...this.schema.aliases,{name:t,hidden:n?.hidden??!1}]})}env(t){return new e({...this.schema,envVar:t})}config(t){return new e({...this.schema,configPath:t})}describe(t){return new e({...this.schema,description:t})}prompt(t){return new e({...this.schema,prompt:t})}deprecated(t){return new e({...this.schema,deprecated:t??!0})}propagate(){return new e({...this.schema,propagate:!0})}};const a={string(){return new i(r(`string`))},number(){return new i(r(`number`))},boolean(){return new i(r(`boolean`,{presence:`defaulted`,defaultValue:!1}))},enum(e){return new i(r(`enum`,{enumValues:e}))},array(e){return new i(r(`array`,{elementSchema:e.schema}))},custom(e){return new i(r(`custom`,{parseFn:e}))}};export{i as FlagBuilder,r as createSchema,a as flag,n as getFlagAliasNames};
1
+ import { assertNumberConstraints } from "./number-constraints.mjs";
2
+ //#region src/core/schema/flag.ts
3
+ /**
4
+ * Flag schema builder with full type inference.
5
+ *
6
+ * Each factory (`flag.string()`, `flag.boolean()`, etc.) returns an immutable
7
+ * {@linkcode FlagBuilder} whose generic parameter tracks the value type and presence
8
+ * state. Chained modifiers (`.default()`, `.required()`, `.alias()`, …) return
9
+ * new builders with updated type-level and runtime state.
10
+ *
11
+ * @module dreamcli/core/schema/flag
12
+ */
13
+ /**
14
+ * Normalise an alias input into a full {@link FlagAlias} object.
15
+ *
16
+ * @param alias - Raw alias name or structured alias object.
17
+ * @returns Normalised alias record.
18
+ */
19
+ function normalizeFlagAlias(alias) {
20
+ if (typeof alias === "string") return {
21
+ name: alias,
22
+ hidden: false
23
+ };
24
+ return {
25
+ name: alias.name,
26
+ hidden: alias.hidden
27
+ };
28
+ }
29
+ /**
30
+ * Normalise alias input into immutable alias records.
31
+ *
32
+ * @param aliases - Alias input values.
33
+ * @returns Normalised alias objects.
34
+ */
35
+ function normalizeFlagAliases(aliases) {
36
+ return aliases.map(normalizeFlagAlias);
37
+ }
38
+ /**
39
+ * List alias names for a flag schema.
40
+ *
41
+ * @param schema - Flag schema whose aliases should be listed.
42
+ * @param options - Visibility and length filtering.
43
+ * @returns Alias names in registration order.
44
+ */
45
+ function getFlagAliasNames(schema, options) {
46
+ const includeHidden = options?.includeHidden ?? false;
47
+ const kind = options?.kind ?? "all";
48
+ return schema.aliases.filter((alias) => includeHidden || !alias.hidden).filter((alias) => {
49
+ if (kind === "short") return alias.name.length === 1;
50
+ if (kind === "long") return alias.name.length > 1;
51
+ return true;
52
+ }).map((alias) => alias.name);
53
+ }
54
+ /**
55
+ * Create a raw {@link FlagSchema} object with sensible defaults.
56
+ *
57
+ * Most consumers should prefer the higher-level {@link flag} factory,
58
+ * which returns an immutable {@link FlagBuilder} with type inference and
59
+ * safe modifier chaining. `createSchema()` is the low-level escape hatch
60
+ * for advanced schema composition, tests, or custom factories that need to
61
+ * work directly with the runtime descriptor.
62
+ *
63
+ * `overrides` are shallow-merged on top of the default shape, so callers are
64
+ * responsible for keeping the resulting schema internally consistent.
65
+ *
66
+ * @param kind - Discriminator for the value type this flag accepts.
67
+ * @param overrides - Partial {@link FlagSchema} fields merged onto defaults.
68
+ * @returns A fully populated {@link FlagSchema}.
69
+ *
70
+ * @example
71
+ * ```ts
72
+ * const schema = createSchema('enum', {
73
+ * enumValues: ['us', 'eu', 'ap'],
74
+ * description: 'Deployment region',
75
+ * });
76
+ * ```
77
+ */
78
+ function createSchema(kind, overrides) {
79
+ const aliases = overrides?.aliases !== void 0 ? normalizeFlagAliases(overrides.aliases) : [];
80
+ const { aliases: _ignoredAliases, ...rest } = overrides ?? {};
81
+ return {
82
+ kind,
83
+ presence: "optional",
84
+ defaultValue: void 0,
85
+ envVar: void 0,
86
+ configPath: void 0,
87
+ description: void 0,
88
+ enumValues: void 0,
89
+ numberConstraints: void 0,
90
+ elementSchema: void 0,
91
+ prompt: void 0,
92
+ parseFn: void 0,
93
+ deprecated: void 0,
94
+ propagate: false,
95
+ ...rest,
96
+ aliases
97
+ };
98
+ }
99
+ /**
100
+ * Immutable flag schema builder.
101
+ *
102
+ * The type parameter `C` is a phantom that tracks the value type and presence
103
+ * through the fluent chain. Each modifier returns a **new** builder — the
104
+ * original is never mutated.
105
+ *
106
+ * @example
107
+ * ```ts
108
+ * const port = flag.number().default(8080);
109
+ * type Port = InferFlag<typeof port>; // number
110
+ *
111
+ * const region = flag.enum(['us', 'eu', 'ap']);
112
+ * type Region = InferFlag<typeof region>; // 'us' | 'eu' | 'ap' | undefined
113
+ * ```
114
+ */
115
+ var FlagBuilder = class FlagBuilder {
116
+ /** @internal Runtime schema descriptor. */
117
+ schema;
118
+ /**
119
+ * Create a flag builder from a pre-built schema descriptor.
120
+ *
121
+ * @param schema - Runtime descriptor seeding this builder's state.
122
+ */
123
+ constructor(schema) {
124
+ this.schema = schema;
125
+ }
126
+ /**
127
+ * Provide a default value. The flag becomes "always present" — handlers
128
+ * will never see `undefined`.
129
+ *
130
+ * The generic constraint `V extends C['valueType']` ensures the default
131
+ * matches the flag's declared type.
132
+ *
133
+ * @param value - Fallback value used when no source provides one.
134
+ * @returns The builder (for chaining).
135
+ *
136
+ * @example
137
+ * ```ts
138
+ * flag.number().default(8080).describe('Port to listen on')
139
+ *
140
+ * // $ mycli serve → port = 8080
141
+ * // $ mycli serve --port 443 → port = 443
142
+ * ```
143
+ */
144
+ default(value) {
145
+ return new FlagBuilder({
146
+ ...this.schema,
147
+ presence: "defaulted",
148
+ defaultValue: value
149
+ });
150
+ }
151
+ /**
152
+ * Mark the flag as required. If not resolved from any source the framework
153
+ * will emit a `ValidationError` before the action handler runs.
154
+ *
155
+ * @returns The builder (for chaining).
156
+ *
157
+ * @example
158
+ * ```ts
159
+ * flag.string().required().describe('Deploy target')
160
+ *
161
+ * // $ mycli deploy
162
+ * // # → Error: Missing required flag --target
163
+ * // $ mycli deploy --target staging
164
+ * // # → target = 'staging'
165
+ * ```
166
+ */
167
+ required() {
168
+ return new FlagBuilder({
169
+ ...this.schema,
170
+ presence: "required"
171
+ });
172
+ }
173
+ /**
174
+ * Add a short or long alias (e.g. `'f'` for `--force`, `'verbose'` as an
175
+ * alternative long name).
176
+ *
177
+ * @param name - Single-char short alias or alternative long name.
178
+ * @param options - Optional alias metadata. Hidden aliases remain parseable
179
+ * but are omitted from help, completions, and suggestions.
180
+ * @returns The builder (for chaining).
181
+ *
182
+ * @example
183
+ * ```ts
184
+ * flag.boolean().alias('v').describe('Enable verbose output')
185
+ *
186
+ * // $ mycli build -v → verbose = true
187
+ * // $ mycli build --verbose → verbose = true
188
+ * ```
189
+ */
190
+ alias(name, options) {
191
+ return new FlagBuilder({
192
+ ...this.schema,
193
+ aliases: [...this.schema.aliases, {
194
+ name,
195
+ hidden: options?.hidden ?? false
196
+ }]
197
+ });
198
+ }
199
+ /**
200
+ * Bind to an environment variable (resolved in v0.2+).
201
+ *
202
+ * @param varName - Environment variable name (e.g. `'PORT'`).
203
+ * @returns The builder (for chaining).
204
+ *
205
+ * @example
206
+ * ```ts
207
+ * flag.string().env('API_KEY').describe('Service API key')
208
+ *
209
+ * // $ API_KEY=sk-123 mycli request → apiKey = 'sk-123'
210
+ * // $ mycli request --api-key sk-456 → apiKey = 'sk-456' (CLI wins)
211
+ * ```
212
+ */
213
+ env(varName) {
214
+ return new FlagBuilder({
215
+ ...this.schema,
216
+ envVar: varName
217
+ });
218
+ }
219
+ /**
220
+ * Bind to a dotted config path (resolved in v0.2+).
221
+ *
222
+ * @param path - Dotted config key (e.g. `'deploy.region'`).
223
+ * @returns The builder (for chaining).
224
+ *
225
+ * @example
226
+ * ```ts
227
+ * flag.string().config('deploy.region').default('us-east-1')
228
+ * // Config file: { "deploy": { "region": "eu-west-1" } }
229
+ * // $ mycli deploy
230
+ * // # → region = 'eu-west-1' (from config)
231
+ * // $ mycli deploy --region ap-south-1
232
+ * // # → CLI flag wins
233
+ * ```
234
+ */
235
+ config(path) {
236
+ return new FlagBuilder({
237
+ ...this.schema,
238
+ configPath: path
239
+ });
240
+ }
241
+ /**
242
+ * Human-readable description shown in help output.
243
+ *
244
+ * @param description - Text displayed next to the flag in `--help`.
245
+ * @returns The builder (for chaining).
246
+ */
247
+ describe(description) {
248
+ return new FlagBuilder({
249
+ ...this.schema,
250
+ description
251
+ });
252
+ }
253
+ /**
254
+ * Attach interactive prompt configuration for v0.3+ resolution.
255
+ *
256
+ * When a flag value is not resolved from CLI, env, or config, the
257
+ * prompt engine uses this config to interactively ask the user.
258
+ * In non-interactive contexts (CI, piped stdin) prompts are skipped
259
+ * and resolution falls through to default or required validation.
260
+ *
261
+ * @param config - {@link PromptConfig} describing the interactive prompt.
262
+ * @returns The builder (for chaining).
263
+ *
264
+ * @example
265
+ * ```ts
266
+ * flag.string().prompt({ kind: 'input', message: 'Enter value:' })
267
+ *
268
+ * // $ mycli init → prompts "Enter value:" interactively
269
+ * // $ mycli init --name foo → skips prompt, uses CLI value
270
+ * ```
271
+ */
272
+ prompt(config) {
273
+ return new FlagBuilder({
274
+ ...this.schema,
275
+ prompt: config
276
+ });
277
+ }
278
+ /**
279
+ * Mark this flag as deprecated.
280
+ *
281
+ * When used, a warning is emitted to stderr. Help text shows
282
+ * `[deprecated]` or `[deprecated: <reason>]`.
283
+ *
284
+ * Does not change the flag's type-level config — it's metadata only.
285
+ *
286
+ * @param message - Optional migration reason/guidance.
287
+ * @returns The builder (for chaining).
288
+ *
289
+ * @example
290
+ * ```ts
291
+ * flag.string().deprecated('Use --target instead')
292
+ *
293
+ * // $ mycli deploy --dest staging
294
+ * // ⚠ --dest is deprecated: Use --target instead
295
+ * ```
296
+ */
297
+ deprecated(message) {
298
+ return new FlagBuilder({
299
+ ...this.schema,
300
+ deprecated: message ?? true
301
+ });
302
+ }
303
+ /**
304
+ * Mark this flag as propagated to subcommands.
305
+ *
306
+ * Propagated flags are automatically available to all descendant
307
+ * commands in a nested command tree. A child command that defines
308
+ * a flag with the same name shadows the propagated parent flag.
309
+ *
310
+ * Does not change the flag's type-level config — it's metadata only.
311
+ *
312
+ * @returns The builder (for chaining).
313
+ *
314
+ * @example
315
+ * ```ts
316
+ * flag.boolean().alias('v').propagate().describe('Enable verbose output')
317
+ *
318
+ * // $ mycli --verbose deploy staging
319
+ * // # → verbose = true in deploy handler
320
+ * // $ mycli deploy --verbose staging
321
+ * // # → same, inherited from parent
322
+ * ```
323
+ */
324
+ propagate() {
325
+ return new FlagBuilder({
326
+ ...this.schema,
327
+ propagate: true
328
+ });
329
+ }
330
+ /**
331
+ * Require an integer value. Composes with other numeric constraints.
332
+ *
333
+ * @param value - Whether to require an integer.
334
+ * @defaultValue `true`
335
+ * @returns The builder (for chaining).
336
+ *
337
+ * @example
338
+ * ```ts
339
+ * flag.number().int() // rejects 3.7, accepts 3
340
+ * flag.number({ int: true }).int(false) // re-allows non-integers
341
+ * ```
342
+ */
343
+ int(value = true) {
344
+ return new FlagBuilder({
345
+ ...this.schema,
346
+ numberConstraints: {
347
+ ...this.schema.numberConstraints,
348
+ int: value
349
+ }
350
+ });
351
+ }
352
+ /**
353
+ * Set an inclusive lower bound. Composes with other numeric constraints;
354
+ * a later call overrides an earlier `min` (including one from the options
355
+ * object).
356
+ *
357
+ * @param value - Inclusive minimum.
358
+ * @returns The builder (for chaining).
359
+ *
360
+ * @example
361
+ * ```ts
362
+ * flag.number().min(0) // rejects -1, accepts 0
363
+ * flag.number({ min: 0 }).min(5) // effective min is 5
364
+ * ```
365
+ */
366
+ min(value) {
367
+ const numberConstraints = {
368
+ ...this.schema.numberConstraints,
369
+ min: value
370
+ };
371
+ assertNumberConstraints(numberConstraints);
372
+ return new FlagBuilder({
373
+ ...this.schema,
374
+ numberConstraints
375
+ });
376
+ }
377
+ /**
378
+ * Set an inclusive upper bound. Composes with other numeric constraints;
379
+ * a later call overrides an earlier `max`.
380
+ *
381
+ * @param value - Inclusive maximum.
382
+ * @returns The builder (for chaining).
383
+ *
384
+ * @example
385
+ * ```ts
386
+ * flag.number().max(100) // rejects 101, accepts 100
387
+ * ```
388
+ */
389
+ max(value) {
390
+ const numberConstraints = {
391
+ ...this.schema.numberConstraints,
392
+ max: value
393
+ };
394
+ assertNumberConstraints(numberConstraints);
395
+ return new FlagBuilder({
396
+ ...this.schema,
397
+ numberConstraints
398
+ });
399
+ }
400
+ /**
401
+ * Require (or, with `false`, allow) a finite value. Finiteness is enforced
402
+ * by default, so this is mainly used as `.finite(false)` to re-allow
403
+ * `Infinity` / `-Infinity`.
404
+ *
405
+ * @param allow - Whether to require a finite value.
406
+ * @defaultValue `true`
407
+ * @returns The builder (for chaining).
408
+ *
409
+ * @example
410
+ * ```ts
411
+ * flag.number().finite(false) // accepts Infinity
412
+ * ```
413
+ */
414
+ finite(allow = true) {
415
+ return new FlagBuilder({
416
+ ...this.schema,
417
+ numberConstraints: {
418
+ ...this.schema.numberConstraints,
419
+ finite: allow
420
+ }
421
+ });
422
+ }
423
+ };
424
+ /**
425
+ * Flag schema factory. Call `flag.<kind>()` to create an immutable
426
+ * {@link FlagBuilder} with full type inference and safe modifier chaining.
427
+ */
428
+ const flag = {
429
+ string() {
430
+ return new FlagBuilder(createSchema("string"));
431
+ },
432
+ number(constraints) {
433
+ if (constraints !== void 0) assertNumberConstraints(constraints);
434
+ return new FlagBuilder(createSchema("number", constraints !== void 0 ? { numberConstraints: constraints } : {}));
435
+ },
436
+ boolean() {
437
+ return new FlagBuilder(createSchema("boolean", {
438
+ presence: "defaulted",
439
+ defaultValue: false
440
+ }));
441
+ },
442
+ enum(values) {
443
+ return new FlagBuilder(createSchema("enum", { enumValues: values }));
444
+ },
445
+ array(element) {
446
+ return new FlagBuilder(createSchema("array", { elementSchema: element.schema }));
447
+ },
448
+ custom(parseFn) {
449
+ return new FlagBuilder(createSchema("custom", { parseFn }));
450
+ }
451
+ };
452
+ //#endregion
453
+ export { FlagBuilder, createSchema, flag, getFlagAliasNames };
@@ -1,8 +1,9 @@
1
1
  import { ActivityEvent, Fallback, ProgressHandle, ProgressOptions, SpinnerHandle, SpinnerOptions, TableColumn, TableFormat, TableOptions, TableStream } from "./activity.mjs";
2
+ import { NumberConstraintViolation, NumberConstraints, describeNumberConstraintViolation, validateNumberConstraints } from "./number-constraints.mjs";
2
3
  import { ARG_KINDS, ARG_PRESENCES, ArgBuilder, ArgConfig, ArgFactory, ArgKind, ArgParseFn, ArgPresence, ArgSchema, InferArg, InferArgs, ResolvedArgValue, WithArgPresence, WithVariadic, arg, createArgSchema } from "./arg.mjs";
3
4
  import { ConfirmPromptConfig, InputPromptConfig, MultiselectPromptConfig, PROMPT_KINDS, PromptConfig, PromptConfigBase, PromptKind, PromptResult, SelectChoice, SelectPromptConfig } from "./prompt.mjs";
4
5
  import { FLAG_KINDS, FLAG_PRESENCES, FlagAlias, FlagBuilder, FlagConfig, FlagFactory, FlagKind, FlagParseFn, FlagPresence, FlagSchema, FlagSchemaOverrides, InferFlag, InferFlags, ResolvedValue, WithPresence, createSchema, flag } from "./flag.mjs";
5
6
  import { ErasedMiddlewareHandler, Middleware, MiddlewareHandler, MiddlewareParams, middleware } from "./middleware.mjs";
6
7
  import { RunOptions, RunResult } from "./run.mjs";
7
8
  import { ActionHandler, ActionParams, AnyCommandBuilder, CommandArgEntry, CommandBuilder, CommandConfig, CommandExample, CommandMeta, CommandSchema, DeriveHandler, DeriveParams, ErasedCommand, ErasedDeriveHandler, ErasedInteractiveResolver, InteractiveParams, InteractiveResolver, InteractiveResult, Out, command, group } from "./command.mjs";
8
- export { ARG_KINDS, ARG_PRESENCES, type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type ConfirmPromptConfig, type DeriveHandler, type DeriveParams, type ErasedCommand, type ErasedDeriveHandler, type ErasedInteractiveResolver, type ErasedMiddlewareHandler, FLAG_KINDS, FLAG_PRESENCES, type Fallback, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FlagSchemaOverrides, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type Out, PROMPT_KINDS, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type ResolvedArgValue, type ResolvedValue, type RunOptions, type RunResult, type SelectChoice, type SelectPromptConfig, type SpinnerHandle, type SpinnerOptions, type TableColumn, type TableFormat, type TableOptions, type TableStream, type WithArgPresence, type WithPresence, type WithVariadic, arg, command, createArgSchema, createSchema, flag, group, middleware };
9
+ export { ARG_KINDS, ARG_PRESENCES, type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type ConfirmPromptConfig, type DeriveHandler, type DeriveParams, type ErasedCommand, type ErasedDeriveHandler, type ErasedInteractiveResolver, type ErasedMiddlewareHandler, FLAG_KINDS, FLAG_PRESENCES, type Fallback, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FlagSchemaOverrides, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type NumberConstraintViolation, type NumberConstraints, type Out, PROMPT_KINDS, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type ResolvedArgValue, type ResolvedValue, type RunOptions, type RunResult, type SelectChoice, type SelectPromptConfig, type SpinnerHandle, type SpinnerOptions, type TableColumn, type TableFormat, type TableOptions, type TableStream, type WithArgPresence, type WithPresence, type WithVariadic, arg, command, createArgSchema, createSchema, describeNumberConstraintViolation, flag, group, middleware, validateNumberConstraints };
@@ -1 +1,41 @@
1
- function e(e){return{_handler:e}}export{e as middleware};
1
+ //#region src/core/schema/middleware.ts
2
+ /**
3
+ * Create a middleware definition.
4
+ *
5
+ * Middleware runs before the action handler and can add typed context,
6
+ * short-circuit execution, or wrap downstream processing.
7
+ *
8
+ * @param handler - Function receiving `{ args, flags, ctx, out, meta, next }`.
9
+ * Call `next(additions)` to continue the chain with added context.
10
+ * Omitting the `next()` call short-circuits (e.g., for auth guards).
11
+ * @returns {@linkcode Middleware} to attach via `CommandBuilder.middleware()`.
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * // Auth guard — adds user to context or throws
16
+ * const auth = middleware(async ({ next }) => {
17
+ * const user = await getUser();
18
+ * if (!user) throw new CLIError('Not authenticated', { code: 'AUTH_REQUIRED' });
19
+ * return next({ user });
20
+ * });
21
+ *
22
+ * // Timing wrapper — measures downstream execution
23
+ * const timing = middleware(async ({ out, next }) => {
24
+ * const start = Date.now();
25
+ * await next({});
26
+ * out.info(`Done in ${Date.now() - start}ms`);
27
+ * });
28
+ *
29
+ * command('deploy')
30
+ * .middleware(timing)
31
+ * .middleware(auth)
32
+ * .action(({ ctx }) => {
33
+ * console.log(ctx.user.name); // typed!
34
+ * });
35
+ * ```
36
+ */
37
+ function middleware(handler) {
38
+ return { _handler: handler };
39
+ }
40
+ //#endregion
41
+ export { middleware };