@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.
- package/CHANGELOG.md +169 -1
- package/README.md +14 -7
- package/dist/core/cli/index.d.mts +283 -81
- package/dist/core/cli/index.mjs +1 -1
- package/dist/core/cli/planner.d.mts +27 -5
- package/dist/core/cli/planner.mjs +1 -1
- package/dist/core/cli/root-help.d.mts +16 -2
- package/dist/core/cli/root-help.mjs +3 -5
- package/dist/core/cli/root-surface.d.mts +18 -3
- package/dist/core/cli/root-surface.mjs +1 -1
- package/dist/core/cli/runtime-preflight.d.mts +31 -5
- package/dist/core/cli/runtime-preflight.mjs +1 -1
- package/dist/core/completion/index.d.mts +32 -1
- package/dist/core/completion/index.mjs +1 -1
- package/dist/core/completion/shells/shared.d.mts +10 -0
- package/dist/core/completion/shells/shared.mjs +1 -1
- package/dist/core/config/index.d.mts +2 -2
- package/dist/core/config/package-json.d.mts +93 -20
- package/dist/core/config/package-json.mjs +3 -1
- package/dist/core/help/index.d.mts +45 -1
- package/dist/core/help/index.mjs +6 -6
- package/dist/core/json-schema/index.mjs +1 -1
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
- package/dist/core/parse/index.d.mts +15 -1
- package/dist/core/parse/index.mjs +1 -1
- package/dist/core/prompt/index.d.mts +11 -3
- package/dist/core/prompt/index.mjs +3 -3
- package/dist/core/resolve/coerce.mjs +1 -1
- package/dist/core/resolve/flags.mjs +1 -1
- package/dist/core/resolve/property.d.mts +2 -0
- package/dist/core/resolve/property.mjs +1 -1
- package/dist/core/schema/arg.d.mts +90 -10
- package/dist/core/schema/arg.mjs +1 -1
- package/dist/core/schema/command.d.mts +3 -1
- package/dist/core/schema/flag.d.mts +92 -2
- package/dist/core/schema/flag.mjs +1 -1
- package/dist/core/schema/index.d.mts +2 -1
- package/dist/core/schema/number-constraints.d.mts +96 -0
- package/dist/core/schema/number-constraints.mjs +1 -0
- package/dist/core/schema/prompt.d.mts +15 -0
- package/dist/core/schema/run.d.mts +4 -4
- package/dist/core/testkit/index.d.mts +9 -5
- package/dist/core/testkit/index.mjs +1 -1
- package/dist/index.d.mts +4 -3
- package/dist/index.mjs +1 -1
- package/dist/runtime/auto.mjs +1 -1
- package/dist/runtime/bun.mjs +1 -1
- package/dist/runtime/deno.mjs +2 -2
- package/dist/runtime/node.mjs +2 -2
- package/dist/version.mjs +1 -1
- package/examples/basic.ts +5 -1
- package/examples/gh/package.json +2 -7
- package/examples/pwsh-demo/package.json +1 -7
- package/examples/pwsh-demo/src/main.test.ts +1 -4
- package/examples/pwsh-demo/src/main.ts +14 -4
- package/examples/transport-launcher.ts +85 -0
- package/package.json +15 -24
- package/src/core/cli/dispatch.ts +7 -1
- package/src/core/cli/index.ts +521 -122
- package/src/core/cli/planner.ts +192 -23
- package/src/core/cli/root-help.ts +195 -105
- package/src/core/cli/root-surface.ts +25 -12
- package/src/core/cli/runtime-preflight.ts +43 -8
- package/src/core/completion/index.ts +50 -0
- package/src/core/completion/shells/powershell.ts +2 -2
- package/src/core/completion/shells/shared.ts +30 -3
- package/src/core/config/index.ts +12 -2
- package/src/core/config/package-json.ts +250 -41
- package/src/core/execution/index.ts +1 -4
- package/src/core/help/index.ts +57 -10
- package/src/core/json-schema/index.ts +23 -4
- package/src/core/json-schema/meta-descriptions.generated.ts +115 -98
- package/src/core/parse/index.ts +62 -1
- package/src/core/prompt/index.ts +54 -14
- package/src/core/resolve/coerce.ts +73 -5
- package/src/core/resolve/flags.ts +14 -0
- package/src/core/resolve/property.ts +4 -4
- package/src/core/schema/arg.ts +125 -3
- package/src/core/schema/command.ts +3 -1
- package/src/core/schema/flag.ts +120 -4
- package/src/core/schema/index.ts +5 -0
- package/src/core/schema/number-constraints.ts +153 -0
- package/src/core/schema/prompt.ts +15 -0
- package/src/core/schema/run.ts +4 -4
- package/src/core/testkit/index.ts +32 -8
- package/src/index.ts +8 -0
- package/src/runtime/auto.ts +0 -24
- package/src/runtime/bun.ts +0 -7
- package/src/runtime/deno.ts +0 -2
- package/src/runtime/node.ts +0 -11
- package/src/runtime/support.ts +1 -59
- package/src/schema.ts +16 -0
- package/dist/runtime/support.d.mts +0 -42
- 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': {
|
package/src/core/schema/arg.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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
|
*
|
package/src/core/schema/flag.ts
CHANGED
|
@@ -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
|
-
|
|
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<{
|
package/src/core/schema/index.ts
CHANGED
|
@@ -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.
|
package/src/core/schema/run.ts
CHANGED
|
@@ -155,10 +155,10 @@ export interface RunOptions {
|
|
|
155
155
|
/**
|
|
156
156
|
* Structured result from {@linkcode runCommand}.
|
|
157
157
|
*
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
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
|