@kjanat/dreamcli 2.4.1 → 3.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/CHANGELOG.md +169 -1
  2. package/README.md +14 -7
  3. package/dist/core/cli/index.d.mts +283 -81
  4. package/dist/core/cli/index.mjs +1 -1
  5. package/dist/core/cli/planner.d.mts +27 -5
  6. package/dist/core/cli/planner.mjs +1 -1
  7. package/dist/core/cli/root-help.d.mts +16 -2
  8. package/dist/core/cli/root-help.mjs +3 -5
  9. package/dist/core/cli/root-surface.d.mts +18 -3
  10. package/dist/core/cli/root-surface.mjs +1 -1
  11. package/dist/core/cli/runtime-preflight.d.mts +31 -5
  12. package/dist/core/cli/runtime-preflight.mjs +1 -1
  13. package/dist/core/completion/index.d.mts +32 -1
  14. package/dist/core/completion/index.mjs +1 -1
  15. package/dist/core/completion/shells/shared.d.mts +10 -0
  16. package/dist/core/completion/shells/shared.mjs +1 -1
  17. package/dist/core/config/index.d.mts +2 -2
  18. package/dist/core/config/package-json.d.mts +93 -20
  19. package/dist/core/config/package-json.mjs +3 -1
  20. package/dist/core/help/index.d.mts +45 -1
  21. package/dist/core/help/index.mjs +6 -6
  22. package/dist/core/json-schema/index.mjs +1 -1
  23. package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
  24. package/dist/core/parse/index.d.mts +15 -1
  25. package/dist/core/parse/index.mjs +1 -1
  26. package/dist/core/prompt/index.d.mts +11 -3
  27. package/dist/core/prompt/index.mjs +3 -3
  28. package/dist/core/resolve/coerce.mjs +1 -1
  29. package/dist/core/resolve/flags.mjs +1 -1
  30. package/dist/core/resolve/property.d.mts +2 -0
  31. package/dist/core/resolve/property.mjs +1 -1
  32. package/dist/core/schema/arg.d.mts +90 -10
  33. package/dist/core/schema/arg.mjs +1 -1
  34. package/dist/core/schema/command.d.mts +3 -1
  35. package/dist/core/schema/flag.d.mts +92 -2
  36. package/dist/core/schema/flag.mjs +1 -1
  37. package/dist/core/schema/index.d.mts +2 -1
  38. package/dist/core/schema/number-constraints.d.mts +96 -0
  39. package/dist/core/schema/number-constraints.mjs +1 -0
  40. package/dist/core/schema/prompt.d.mts +15 -0
  41. package/dist/core/schema/run.d.mts +4 -4
  42. package/dist/core/testkit/index.d.mts +9 -5
  43. package/dist/core/testkit/index.mjs +1 -1
  44. package/dist/index.d.mts +4 -3
  45. package/dist/index.mjs +1 -1
  46. package/dist/runtime/auto.mjs +1 -1
  47. package/dist/runtime/bun.mjs +1 -1
  48. package/dist/runtime/deno.mjs +2 -2
  49. package/dist/runtime/node.mjs +2 -2
  50. package/dist/version.mjs +1 -1
  51. package/examples/basic.ts +5 -1
  52. package/examples/gh/package.json +2 -7
  53. package/examples/pwsh-demo/package.json +1 -7
  54. package/examples/pwsh-demo/src/main.test.ts +1 -4
  55. package/examples/pwsh-demo/src/main.ts +14 -4
  56. package/examples/transport-launcher.ts +85 -0
  57. package/package.json +15 -24
  58. package/src/core/cli/dispatch.ts +7 -1
  59. package/src/core/cli/index.ts +521 -122
  60. package/src/core/cli/planner.ts +192 -23
  61. package/src/core/cli/root-help.ts +195 -105
  62. package/src/core/cli/root-surface.ts +25 -12
  63. package/src/core/cli/runtime-preflight.ts +43 -8
  64. package/src/core/completion/index.ts +50 -0
  65. package/src/core/completion/shells/powershell.ts +2 -2
  66. package/src/core/completion/shells/shared.ts +30 -3
  67. package/src/core/config/index.ts +12 -2
  68. package/src/core/config/package-json.ts +250 -41
  69. package/src/core/execution/index.ts +1 -4
  70. package/src/core/help/index.ts +57 -10
  71. package/src/core/json-schema/index.ts +23 -4
  72. package/src/core/json-schema/meta-descriptions.generated.ts +115 -98
  73. package/src/core/parse/index.ts +62 -1
  74. package/src/core/prompt/index.ts +54 -14
  75. package/src/core/resolve/coerce.ts +73 -5
  76. package/src/core/resolve/flags.ts +14 -0
  77. package/src/core/resolve/property.ts +4 -4
  78. package/src/core/schema/arg.ts +125 -3
  79. package/src/core/schema/command.ts +3 -1
  80. package/src/core/schema/flag.ts +120 -4
  81. package/src/core/schema/index.ts +5 -0
  82. package/src/core/schema/number-constraints.ts +153 -0
  83. package/src/core/schema/prompt.ts +15 -0
  84. package/src/core/schema/run.ts +4 -4
  85. package/src/core/testkit/index.ts +32 -8
  86. package/src/index.ts +8 -0
  87. package/src/runtime/auto.ts +0 -24
  88. package/src/runtime/bun.ts +0 -7
  89. package/src/runtime/deno.ts +0 -2
  90. package/src/runtime/node.ts +0 -11
  91. package/src/runtime/support.ts +1 -59
  92. package/src/schema.ts +16 -0
  93. package/dist/runtime/support.d.mts +0 -42
  94. package/dist/runtime/support.mjs +0 -1
@@ -9,7 +9,7 @@
9
9
  * @internal
10
10
  */
11
11
 
12
- import type { ArgSchema, FlagSchema } from '#internals/core/schema/index.ts';
12
+ import type { ArgSchema, FlagSchema, NumberConstraints } from '#internals/core/schema/index.ts';
13
13
 
14
14
  /** Flag/arg kinds that share a common coercion path. */
15
15
  const SHARED_PROPERTY_MODEL_KINDS = ['string', 'number', 'enum', 'custom'] as const;
@@ -20,7 +20,7 @@ type SharedPropertyKind = (typeof SHARED_PROPERTY_MODEL_KINDS)[number];
20
20
  /** Minimal coercion-relevant slice of a flag or arg schema, discriminated by kind. */
21
21
  type SharedPropertySchema =
22
22
  | { readonly kind: 'string' }
23
- | { readonly kind: 'number' }
23
+ | { readonly kind: 'number'; readonly numberConstraints: NumberConstraints | undefined }
24
24
  | { readonly kind: 'enum'; readonly enumValues: readonly string[] | undefined }
25
25
  | { readonly kind: 'custom'; readonly parseFn?: (raw: unknown) => unknown };
26
26
 
@@ -53,7 +53,7 @@ function toSharedFlagPropertySchema(schema: FlagSchema): SharedPropertySchema |
53
53
  case 'string':
54
54
  return { kind: 'string' };
55
55
  case 'number':
56
- return { kind: 'number' };
56
+ return { kind: 'number', numberConstraints: schema.numberConstraints };
57
57
  case 'enum':
58
58
  return { kind: 'enum', enumValues: schema.enumValues };
59
59
  case 'custom':
@@ -72,7 +72,7 @@ function toSharedArgPropertySchema(schema: ArgSchema): SharedPropertySchema {
72
72
  case 'string':
73
73
  return { kind: 'string' };
74
74
  case 'number':
75
- return { kind: 'number' };
75
+ return { kind: 'number', numberConstraints: schema.numberConstraints };
76
76
  case 'enum':
77
77
  return { kind: 'enum', enumValues: schema.enumValues };
78
78
  case 'custom': {
@@ -8,6 +8,8 @@
8
8
  * @module dreamcli/core/schema/arg
9
9
  */
10
10
 
11
+ import { assertNumberConstraints, type NumberConstraints } from './number-constraints.ts';
12
+
11
13
  // --- Type-level configuration (phantom state tracked through the chain)
12
14
 
13
15
  /** All arg presence states as a runtime array. */
@@ -33,6 +35,8 @@ interface ArgConfig {
33
35
  readonly presence: ArgPresence;
34
36
  /** Whether this arg consumes remaining positionals. */
35
37
  readonly variadic: boolean;
38
+ /** The runtime kind discriminator, mirroring {@link ArgKind}. */
39
+ readonly argKind: ArgKind;
36
40
  }
37
41
 
38
42
  // --- Type-level helpers
@@ -45,6 +49,7 @@ type WithArgPresence<C extends ArgConfig, P extends ArgPresence> = {
45
49
  readonly valueType: C['valueType'];
46
50
  readonly presence: P;
47
51
  readonly variadic: C['variadic'];
52
+ readonly argKind: C['argKind'];
48
53
  };
49
54
 
50
55
  /**
@@ -55,6 +60,7 @@ type WithVariadic<C extends ArgConfig> = {
55
60
  readonly valueType: C['valueType'];
56
61
  readonly presence: C['presence'];
57
62
  readonly variadic: true;
63
+ readonly argKind: C['argKind'];
58
64
  };
59
65
 
60
66
  /**
@@ -125,6 +131,13 @@ interface ArgSchema {
125
131
  readonly envVar: string | undefined;
126
132
  /** Allowed literal values when `kind === 'enum'`. */
127
133
  readonly enumValues: readonly string[] | undefined;
134
+ /**
135
+ * Numeric constraints when `kind === 'number'` (`undefined` otherwise).
136
+ *
137
+ * Enforced at the parse and resolution boundaries. `finite` defaults to
138
+ * `true`, so `Infinity` is rejected even when no constraints object is set.
139
+ */
140
+ readonly numberConstraints: NumberConstraints | undefined;
128
141
  /** Custom parse function (only when `kind === 'custom'`). */
129
142
  readonly parseFn: ArgParseFn<unknown> | undefined;
130
143
  /**
@@ -174,6 +187,7 @@ function createArgSchema(kind: ArgKind, overrides?: Partial<ArgSchema>): ArgSche
174
187
  description: undefined,
175
188
  envVar: undefined,
176
189
  enumValues: undefined,
190
+ numberConstraints: undefined,
177
191
  parseFn: undefined,
178
192
  deprecated: undefined,
179
193
  ...overrides,
@@ -478,6 +492,91 @@ class ArgBuilder<C extends ArgConfig> {
478
492
  deprecated: message ?? true,
479
493
  });
480
494
  }
495
+
496
+ // -- Numeric constraint modifiers ----------------------------------------
497
+ //
498
+ // Compile-time guarded via a `this` parameter so they are only callable on
499
+ // number-kind builders. They merge onto the single `numberConstraints`
500
+ // representation, overriding any value set by `arg.number({ … })`.
501
+
502
+ /**
503
+ * Require an integer value. Composes with other numeric constraints.
504
+ *
505
+ * @param value - Whether to require an integer.
506
+ * @defaultValue `true`
507
+ * @returns The builder (for chaining).
508
+ *
509
+ * @example
510
+ * ```ts
511
+ * arg.number().int() // rejects 3.7, accepts 3
512
+ * arg.number({ int: true }).int(false) // re-allows non-integers
513
+ * ```
514
+ */
515
+ int(this: ArgBuilder<C & { readonly argKind: 'number' }>, value = true): ArgBuilder<C> {
516
+ return new ArgBuilder({
517
+ ...this.schema,
518
+ numberConstraints: { ...this.schema.numberConstraints, int: value },
519
+ });
520
+ }
521
+
522
+ /**
523
+ * Set an inclusive lower bound. Composes with other numeric constraints;
524
+ * a later call overrides an earlier `min` (including one from the options
525
+ * object).
526
+ *
527
+ * @param value - Inclusive minimum.
528
+ * @returns The builder (for chaining).
529
+ *
530
+ * @example
531
+ * ```ts
532
+ * arg.number().min(0) // rejects -1, accepts 0
533
+ * arg.number({ min: 0 }).min(5) // effective min is 5
534
+ * ```
535
+ */
536
+ min(this: ArgBuilder<C & { readonly argKind: 'number' }>, value: number): ArgBuilder<C> {
537
+ const numberConstraints = { ...this.schema.numberConstraints, min: value };
538
+ assertNumberConstraints(numberConstraints);
539
+ return new ArgBuilder({ ...this.schema, numberConstraints });
540
+ }
541
+
542
+ /**
543
+ * Set an inclusive upper bound. Composes with other numeric constraints;
544
+ * a later call overrides an earlier `max`.
545
+ *
546
+ * @param value - Inclusive maximum.
547
+ * @returns The builder (for chaining).
548
+ *
549
+ * @example
550
+ * ```ts
551
+ * arg.number().max(100) // rejects 101, accepts 100
552
+ * ```
553
+ */
554
+ max(this: ArgBuilder<C & { readonly argKind: 'number' }>, value: number): ArgBuilder<C> {
555
+ const numberConstraints = { ...this.schema.numberConstraints, max: value };
556
+ assertNumberConstraints(numberConstraints);
557
+ return new ArgBuilder({ ...this.schema, numberConstraints });
558
+ }
559
+
560
+ /**
561
+ * Require (or, with `false`, allow) a finite value. Finiteness is enforced
562
+ * by default, so this is mainly used as `.finite(false)` to re-allow
563
+ * `Infinity` / `-Infinity`.
564
+ *
565
+ * @param allow - Whether to require a finite value.
566
+ * @defaultValue `true`
567
+ * @returns The builder (for chaining).
568
+ *
569
+ * @example
570
+ * ```ts
571
+ * arg.number().finite(false) // accepts Infinity
572
+ * ```
573
+ */
574
+ finite(this: ArgBuilder<C & { readonly argKind: 'number' }>, allow = true): ArgBuilder<C> {
575
+ return new ArgBuilder({
576
+ ...this.schema,
577
+ numberConstraints: { ...this.schema.numberConstraints, finite: allow },
578
+ });
579
+ }
481
580
  }
482
581
 
483
582
  // --- Factory namespace
@@ -544,6 +643,7 @@ interface ArgFactory {
544
643
  readonly valueType: string;
545
644
  readonly presence: 'required';
546
645
  readonly variadic: false;
646
+ readonly argKind: 'string';
547
647
  }>;
548
648
 
549
649
  /**
@@ -566,12 +666,20 @@ interface ArgFactory {
566
666
  * // $ mycli serve → 3000
567
667
  * ```
568
668
  *
669
+ * Constraints are enforced at the parse and resolution boundaries and also
670
+ * compose via chained methods (`.int()`, `.min()`, `.max()`, `.finite()`),
671
+ * which override values set here. The resolved value type stays `number`.
672
+ *
673
+ * @param constraints - Optional numeric constraints. `finite` defaults to
674
+ * `true`, so `Infinity` / `-Infinity` are rejected unless `finite: false`.
675
+ * @defaultValue `undefined` (finite-only, no bounds, non-integer allowed)
569
676
  * @returns A required number {@link ArgBuilder}.
570
677
  */
571
- number(): ArgBuilder<{
678
+ number(constraints?: NumberConstraints): ArgBuilder<{
572
679
  readonly valueType: number;
573
680
  readonly presence: 'required';
574
681
  readonly variadic: false;
682
+ readonly argKind: 'number';
575
683
  }>;
576
684
 
577
685
  /**
@@ -603,6 +711,7 @@ interface ArgFactory {
603
711
  readonly valueType: T[number];
604
712
  readonly presence: 'required';
605
713
  readonly variadic: false;
714
+ readonly argKind: 'enum';
606
715
  }>;
607
716
 
608
717
  /**
@@ -634,6 +743,7 @@ interface ArgFactory {
634
743
  readonly valueType: T;
635
744
  readonly presence: 'required';
636
745
  readonly variadic: false;
746
+ readonly argKind: 'custom';
637
747
  }>;
638
748
  }
639
749
 
@@ -670,16 +780,26 @@ const arg: ArgFactory = {
670
780
  readonly valueType: string;
671
781
  readonly presence: 'required';
672
782
  readonly variadic: false;
783
+ readonly argKind: 'string';
673
784
  }> {
674
785
  return new ArgBuilder(createArgSchema('string'));
675
786
  },
676
787
 
677
- number(): ArgBuilder<{
788
+ number(constraints?: NumberConstraints): ArgBuilder<{
678
789
  readonly valueType: number;
679
790
  readonly presence: 'required';
680
791
  readonly variadic: false;
792
+ readonly argKind: 'number';
681
793
  }> {
682
- return new ArgBuilder(createArgSchema('number'));
794
+ if (constraints !== undefined) {
795
+ assertNumberConstraints(constraints);
796
+ }
797
+ return new ArgBuilder(
798
+ createArgSchema(
799
+ 'number',
800
+ constraints !== undefined ? { numberConstraints: constraints } : {},
801
+ ),
802
+ );
683
803
  },
684
804
 
685
805
  enum<const T extends readonly [string, ...string[]]>(
@@ -688,6 +808,7 @@ const arg: ArgFactory = {
688
808
  readonly valueType: T[number];
689
809
  readonly presence: 'required';
690
810
  readonly variadic: false;
811
+ readonly argKind: 'enum';
691
812
  }> {
692
813
  return new ArgBuilder(createArgSchema('enum', { enumValues: values }));
693
814
  },
@@ -696,6 +817,7 @@ const arg: ArgFactory = {
696
817
  readonly valueType: T;
697
818
  readonly presence: 'required';
698
819
  readonly variadic: false;
820
+ readonly argKind: 'custom';
699
821
  }> {
700
822
  return new ArgBuilder(createArgSchema('custom', { parseFn: parseFn as ArgParseFn<unknown> }));
701
823
  },
@@ -1191,7 +1191,9 @@ class CommandBuilder<
1191
1191
  * The builder controls the flag's type, presence, aliases, env/config
1192
1192
  * bindings, and description. See {@link FlagBuilder} for available modifiers.
1193
1193
  *
1194
- * @param name - Flag name (used as `--name` on CLI and `flags.*` in handler).
1194
+ * @param name - Flag name: the `--name` CLI token and the matching key on `flags`
1195
+ * in the handler. The name is preserved as-is (no camelCasing); read non-identifier
1196
+ * names such as `'dry-run'` with bracket access (`flags['dry-run']`).
1195
1197
  * @param builder - Configured {@linkcode FlagBuilder} from {@linkcode flag | flag.string()},
1196
1198
  * `flag.boolean()`, `flag.number()`, `flag.enum()`, `flag.array()`, or `flag.custom()`.
1197
1199
  *
@@ -9,6 +9,7 @@
9
9
  * @module dreamcli/core/schema/flag
10
10
  */
11
11
 
12
+ import { assertNumberConstraints, type NumberConstraints } from './number-constraints.ts';
12
13
  import type {
13
14
  ConfirmPromptConfig,
14
15
  InputPromptConfig,
@@ -165,6 +166,13 @@ interface FlagSchema {
165
166
  readonly description: string | undefined;
166
167
  /** Allowed literal values when `kind === 'enum'`. */
167
168
  readonly enumValues: readonly string[] | undefined;
169
+ /**
170
+ * Numeric constraints when `kind === 'number'` (`undefined` otherwise).
171
+ *
172
+ * Enforced at the parse and resolution boundaries. `finite` defaults to
173
+ * `true`, so `Infinity` is rejected even when no constraints object is set.
174
+ */
175
+ readonly numberConstraints: NumberConstraints | undefined;
168
176
  /** Element schema when `kind === 'array'`. */
169
177
  readonly elementSchema: FlagSchema | undefined;
170
178
  /** Interactive prompt configuration for v0.3+ resolution. */
@@ -295,6 +303,7 @@ function createSchema(kind: FlagKind, overrides?: FlagSchemaOverrides): FlagSche
295
303
  configPath: undefined,
296
304
  description: undefined,
297
305
  enumValues: undefined,
306
+ numberConstraints: undefined,
298
307
  elementSchema: undefined,
299
308
  prompt: undefined,
300
309
  parseFn: undefined,
@@ -561,6 +570,91 @@ class FlagBuilder<C extends FlagConfig> {
561
570
  propagate: true,
562
571
  });
563
572
  }
573
+
574
+ // -- Numeric constraint modifiers ----------------------------------------
575
+ //
576
+ // Compile-time guarded via a `this` parameter so they are only callable on
577
+ // number-kind builders. They merge onto the single `numberConstraints`
578
+ // representation, overriding any value set by `flag.number({ … })`.
579
+
580
+ /**
581
+ * Require an integer value. Composes with other numeric constraints.
582
+ *
583
+ * @param value - Whether to require an integer.
584
+ * @defaultValue `true`
585
+ * @returns The builder (for chaining).
586
+ *
587
+ * @example
588
+ * ```ts
589
+ * flag.number().int() // rejects 3.7, accepts 3
590
+ * flag.number({ int: true }).int(false) // re-allows non-integers
591
+ * ```
592
+ */
593
+ int(this: FlagBuilder<C & { readonly flagKind: 'number' }>, value = true): FlagBuilder<C> {
594
+ return new FlagBuilder({
595
+ ...this.schema,
596
+ numberConstraints: { ...this.schema.numberConstraints, int: value },
597
+ });
598
+ }
599
+
600
+ /**
601
+ * Set an inclusive lower bound. Composes with other numeric constraints;
602
+ * a later call overrides an earlier `min` (including one from the options
603
+ * object).
604
+ *
605
+ * @param value - Inclusive minimum.
606
+ * @returns The builder (for chaining).
607
+ *
608
+ * @example
609
+ * ```ts
610
+ * flag.number().min(0) // rejects -1, accepts 0
611
+ * flag.number({ min: 0 }).min(5) // effective min is 5
612
+ * ```
613
+ */
614
+ min(this: FlagBuilder<C & { readonly flagKind: 'number' }>, value: number): FlagBuilder<C> {
615
+ const numberConstraints = { ...this.schema.numberConstraints, min: value };
616
+ assertNumberConstraints(numberConstraints);
617
+ return new FlagBuilder({ ...this.schema, numberConstraints });
618
+ }
619
+
620
+ /**
621
+ * Set an inclusive upper bound. Composes with other numeric constraints;
622
+ * a later call overrides an earlier `max`.
623
+ *
624
+ * @param value - Inclusive maximum.
625
+ * @returns The builder (for chaining).
626
+ *
627
+ * @example
628
+ * ```ts
629
+ * flag.number().max(100) // rejects 101, accepts 100
630
+ * ```
631
+ */
632
+ max(this: FlagBuilder<C & { readonly flagKind: 'number' }>, value: number): FlagBuilder<C> {
633
+ const numberConstraints = { ...this.schema.numberConstraints, max: value };
634
+ assertNumberConstraints(numberConstraints);
635
+ return new FlagBuilder({ ...this.schema, numberConstraints });
636
+ }
637
+
638
+ /**
639
+ * Require (or, with `false`, allow) a finite value. Finiteness is enforced
640
+ * by default, so this is mainly used as `.finite(false)` to re-allow
641
+ * `Infinity` / `-Infinity`.
642
+ *
643
+ * @param allow - Whether to require a finite value.
644
+ * @defaultValue `true`
645
+ * @returns The builder (for chaining).
646
+ *
647
+ * @example
648
+ * ```ts
649
+ * flag.number().finite(false) // accepts Infinity
650
+ * ```
651
+ */
652
+ finite(this: FlagBuilder<C & { readonly flagKind: 'number' }>, allow = true): FlagBuilder<C> {
653
+ return new FlagBuilder({
654
+ ...this.schema,
655
+ numberConstraints: { ...this.schema.numberConstraints, finite: allow },
656
+ });
657
+ }
564
658
  }
565
659
 
566
660
  // --- Factory namespace
@@ -583,11 +677,28 @@ interface FlagFactory {
583
677
  }>;
584
678
 
585
679
  /**
586
- * Number-valued flag.
680
+ * Number-valued flag, with optional numeric constraints.
681
+ *
682
+ * Constraints are enforced at the parse and resolution boundaries. The
683
+ * resolved value type stays `number` — constraints are runtime + schema, not
684
+ * type-level. Bounds are inclusive.
587
685
  *
686
+ * Constraints also compose via chained methods (`.int()`, `.min()`,
687
+ * `.max()`, `.finite()`), which override values set here.
688
+ *
689
+ * @param constraints - Optional numeric constraints. `finite` defaults to
690
+ * `true`, so `Infinity` / `-Infinity` are rejected unless `finite: false`.
691
+ * @defaultValue `undefined` (finite-only, no bounds, non-integer allowed)
588
692
  * @returns A {@link FlagBuilder} for `number` values.
693
+ *
694
+ * @example
695
+ * ```ts
696
+ * flag.number() // finite numbers only
697
+ * flag.number({ int: true, min: 0 }) // non-negative integers
698
+ * flag.number({ finite: false }) // also accepts Infinity
699
+ * ```
589
700
  */
590
- number(): FlagBuilder<{
701
+ number(constraints?: NumberConstraints): FlagBuilder<{
591
702
  readonly valueType: number;
592
703
  readonly presence: 'optional';
593
704
  readonly optionalFallback: 'undefined';
@@ -703,13 +814,18 @@ const flag: FlagFactory = {
703
814
  return new FlagBuilder(createSchema('string'));
704
815
  },
705
816
 
706
- number(): FlagBuilder<{
817
+ number(constraints?: NumberConstraints): FlagBuilder<{
707
818
  readonly valueType: number;
708
819
  readonly presence: 'optional';
709
820
  readonly optionalFallback: 'undefined';
710
821
  readonly flagKind: 'number';
711
822
  }> {
712
- return new FlagBuilder(createSchema('number'));
823
+ if (constraints !== undefined) {
824
+ assertNumberConstraints(constraints);
825
+ }
826
+ return new FlagBuilder(
827
+ createSchema('number', constraints !== undefined ? { numberConstraints: constraints } : {}),
828
+ );
713
829
  },
714
830
 
715
831
  boolean(): FlagBuilder<{
@@ -88,4 +88,9 @@ export type {
88
88
  MiddlewareParams,
89
89
  } from './middleware.ts';
90
90
  export { middleware } from './middleware.ts';
91
+ export type { NumberConstraints, NumberConstraintViolation } from './number-constraints.ts';
92
+ export {
93
+ describeNumberConstraintViolation,
94
+ validateNumberConstraints,
95
+ } from './number-constraints.ts';
91
96
  export type { RunOptions, RunResult } from './run.ts';
@@ -0,0 +1,153 @@
1
+ /**
2
+ * Numeric constraints for number-valued flags and args.
3
+ *
4
+ * A single, shared representation and validator so the parse path
5
+ * (`core/parse`) and the resolver coercion path (`core/resolve/coerce`) cannot
6
+ * drift: both import {@link validateNumberConstraints} and apply the checks in
7
+ * the same order (finite → int → min → max).
8
+ *
9
+ * @module dreamcli/core/schema/number-constraints
10
+ */
11
+
12
+ /**
13
+ * Runtime numeric constraints attached to a number flag/arg schema.
14
+ *
15
+ * Bounds are **inclusive**. All fields are optional; an absent field means "no
16
+ * constraint" except for {@link NumberConstraints.finite | finite}, which
17
+ * defaults to `true` (so `Infinity` / `-Infinity` are rejected unless opted
18
+ * back in).
19
+ */
20
+ interface NumberConstraints {
21
+ /**
22
+ * Inclusive lower bound. Values below this are rejected.
23
+ * @defaultValue `undefined` (no lower bound)
24
+ */
25
+ readonly min?: number;
26
+ /**
27
+ * Inclusive upper bound. Values above this are rejected.
28
+ * @defaultValue `undefined` (no upper bound)
29
+ */
30
+ readonly max?: number;
31
+ /**
32
+ * Require an integer value. Non-integers (e.g. `3.7`) are rejected.
33
+ * @defaultValue `false`
34
+ */
35
+ readonly int?: boolean;
36
+ /**
37
+ * Require a finite value. When `true`, `Infinity` / `-Infinity` are rejected.
38
+ * @defaultValue `true`
39
+ */
40
+ readonly finite?: boolean;
41
+ }
42
+
43
+ /**
44
+ * A failed numeric constraint, discriminated by which rule was violated.
45
+ *
46
+ * `min` / `max` carry the offending bound so callers can render it.
47
+ */
48
+ type NumberConstraintViolation =
49
+ | { readonly kind: 'finite' }
50
+ | { readonly kind: 'int' }
51
+ | { readonly kind: 'min'; readonly bound: number }
52
+ | { readonly kind: 'max'; readonly bound: number };
53
+
54
+ /** Default for {@link NumberConstraints.finite} — reject `Infinity` unless opted out. */
55
+ const DEFAULT_FINITE = true;
56
+
57
+ /**
58
+ * Validate a numeric value against constraints.
59
+ *
60
+ * The single source of truth for numeric-constraint checks, shared by the
61
+ * parse and coerce paths. Checks run in a fixed order — **finite → int → min →
62
+ * max** — and the first failure is returned. `NaN` is always rejected as a
63
+ * `finite` violation, regardless of the `finite` option (a non-finite value can
64
+ * otherwise slip past `min`/`max`, since `NaN < x` and `NaN > x` are both false).
65
+ *
66
+ * @param value - The numeric value to validate.
67
+ * @param constraints - Constraints to enforce, or `undefined` for defaults.
68
+ * @returns The first {@link NumberConstraintViolation}, or `undefined` if valid.
69
+ */
70
+ function validateNumberConstraints(
71
+ value: number,
72
+ constraints: NumberConstraints | undefined,
73
+ ): NumberConstraintViolation | undefined {
74
+ if (Number.isNaN(value)) {
75
+ return { kind: 'finite' };
76
+ }
77
+ const finite = constraints?.finite ?? DEFAULT_FINITE;
78
+ if (finite && !Number.isFinite(value)) {
79
+ return { kind: 'finite' };
80
+ }
81
+ if (constraints?.int === true && !Number.isInteger(value)) {
82
+ return { kind: 'int' };
83
+ }
84
+ if (constraints?.min !== undefined && value < constraints.min) {
85
+ return { kind: 'min', bound: constraints.min };
86
+ }
87
+ if (constraints?.max !== undefined && value > constraints.max) {
88
+ return { kind: 'max', bound: constraints.max };
89
+ }
90
+ return undefined;
91
+ }
92
+
93
+ /**
94
+ * Render a terse, human-readable reason for a constraint violation.
95
+ *
96
+ * @param violation - The violation to describe.
97
+ * @returns A message suffix such as `must be an integer` or `must be >= 0`.
98
+ */
99
+ function describeNumberConstraintViolation(violation: NumberConstraintViolation): string {
100
+ switch (violation.kind) {
101
+ case 'finite':
102
+ return 'must be a finite number';
103
+ case 'int':
104
+ return 'must be an integer';
105
+ case 'min':
106
+ return `must be >= ${violation.bound}`;
107
+ case 'max':
108
+ return `must be <= ${violation.bound}`;
109
+ }
110
+ }
111
+
112
+ /**
113
+ * Assert that a constraints object is well-formed at schema-construction time.
114
+ *
115
+ * `min` / `max` must be finite — an infinite or `NaN` bound is meaningless (omit
116
+ * the field for "no bound") and would serialize to `null` in the emitted JSON
117
+ * Schema. An inverted range (`min > max`) is also rejected, since it makes the
118
+ * flag/arg permanently unsatisfiable. Throws so the misconfiguration surfaces
119
+ * where the flag/arg is declared, not at parse time.
120
+ *
121
+ * @param constraints - The constraints to validate.
122
+ * @throws RangeError if `min` or `max` is non-finite (`Infinity` / `-Infinity` /
123
+ * `NaN`), or if `min` exceeds `max`.
124
+ */
125
+ function assertNumberConstraints(constraints: NumberConstraints): void {
126
+ if (constraints.min !== undefined && !Number.isFinite(constraints.min)) {
127
+ throw new RangeError(
128
+ `number constraint 'min' must be a finite number (got ${constraints.min}); omit it for no lower bound`,
129
+ );
130
+ }
131
+ if (constraints.max !== undefined && !Number.isFinite(constraints.max)) {
132
+ throw new RangeError(
133
+ `number constraint 'max' must be a finite number (got ${constraints.max}); omit it for no upper bound`,
134
+ );
135
+ }
136
+ if (
137
+ constraints.min !== undefined &&
138
+ constraints.max !== undefined &&
139
+ constraints.min > constraints.max
140
+ ) {
141
+ throw new RangeError(
142
+ `number constraint 'min' (${constraints.min}) must not exceed 'max' (${constraints.max})`,
143
+ );
144
+ }
145
+ }
146
+
147
+ export type { NumberConstraints, NumberConstraintViolation };
148
+ export {
149
+ assertNumberConstraints,
150
+ DEFAULT_FINITE,
151
+ describeNumberConstraintViolation,
152
+ validateNumberConstraints,
153
+ };
@@ -36,6 +36,12 @@ interface PromptConfigBase {
36
36
  interface ConfirmPromptConfig extends PromptConfigBase {
37
37
  /** Discriminator identifying this as a yes/no confirmation prompt. */
38
38
  readonly kind: 'confirm';
39
+ /**
40
+ * Value used when the user submits an empty line (presses Enter). Also
41
+ * drives the displayed hint: `true` → `(Y/n)`, `false` → `(y/N)`.
42
+ * @defaultValue `true`
43
+ */
44
+ readonly default?: boolean;
39
45
  }
40
46
 
41
47
  /** Free-text input prompt — maps to `string` and `number` flags. Part of {@link PromptConfig}. */
@@ -44,6 +50,15 @@ interface InputPromptConfig extends PromptConfigBase {
44
50
  readonly kind: 'input';
45
51
  /** Placeholder text shown before user types (informational only). */
46
52
  readonly placeholder?: string;
53
+ /**
54
+ * Value used when the user submits an empty line (presses Enter), shown in
55
+ * the hint as `(default: <value>)`. When set, an empty submission resolves
56
+ * to this value without running {@link InputPromptConfig.validate | validate}.
57
+ * When omitted, an empty submission is treated as "no answer" so resolution
58
+ * falls through to the flag's `.default()`.
59
+ * @defaultValue `undefined`
60
+ */
61
+ readonly default?: string;
47
62
  /**
48
63
  * Inline validation function. Return `true` if valid, or a string
49
64
  * error message if invalid. Called before coercion to flag kind.
@@ -155,10 +155,10 @@ export interface RunOptions {
155
155
  /**
156
156
  * Structured result from {@linkcode runCommand}.
157
157
  *
158
- * Contains the exit code, captured stdout/stderr output, recorded
159
- * {@linkcode ActivityEvent | activity events}, and an `error` field.
160
- * `error` is `undefined` when execution completed without throwing, even if
161
- * the handler requested a non-zero status via {@linkcode Out.setExitCode}.
158
+ * Contains the exit code, captured stdout/stderr output, recorded
159
+ * {@linkcode ActivityEvent | activity events}, and an `error` field.
160
+ * `error` is `undefined` when execution completed without throwing, even if
161
+ * the handler requested a non-zero status via {@linkcode Out.setExitCode}.
162
162
  *
163
163
  * @example
164
164
  * ```ts