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

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 (47) hide show
  1. package/CHANGELOG.md +71 -1
  2. package/dist/core/cli/dispatch.d.mts +6 -4
  3. package/dist/core/cli/dispatch.mjs +6 -4
  4. package/dist/core/cli/index.d.mts +27 -1
  5. package/dist/core/cli/index.mjs +32 -15
  6. package/dist/core/cli/planner.d.mts +3 -0
  7. package/dist/core/cli/planner.mjs +9 -9
  8. package/dist/core/cli/propagate.d.mts +1 -1
  9. package/dist/core/cli/root-help.mjs +32 -20
  10. package/dist/core/cli/runtime-preflight.d.mts +7 -1
  11. package/dist/core/cli/runtime-preflight.mjs +3 -3
  12. package/dist/core/completion/shells/bash.mjs +5 -2
  13. package/dist/core/completion/shells/fish.mjs +3 -1
  14. package/dist/core/completion/shells/powershell.mjs +8 -4
  15. package/dist/core/completion/shells/shared.d.mts +13 -2
  16. package/dist/core/completion/shells/shared.mjs +19 -2
  17. package/dist/core/completion/shells/zsh.mjs +8 -2
  18. package/dist/core/config/index.d.mts +2 -2
  19. package/dist/core/config/package-json.d.mts +27 -3
  20. package/dist/core/config/package-json.mjs +20 -19
  21. package/dist/core/errors/index.d.mts +1 -1
  22. package/dist/core/execution/index.mjs +13 -2
  23. package/dist/core/help/index.d.mts +22 -3
  24. package/dist/core/help/index.mjs +55 -49
  25. package/dist/core/help/theme.d.mts +68 -0
  26. package/dist/core/help/theme.mjs +46 -0
  27. package/dist/core/json-schema/index.d.mts +15 -2
  28. package/dist/core/json-schema/index.mjs +32 -4
  29. package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
  30. package/dist/core/json-schema/meta-descriptions.generated.mjs +14 -5
  31. package/dist/core/parse/index.d.mts +40 -7
  32. package/dist/core/parse/index.mjs +137 -34
  33. package/dist/core/resolve/args.d.mts +1 -1
  34. package/dist/core/resolve/coerce.d.mts +1 -1
  35. package/dist/core/resolve/contracts.d.mts +2 -2
  36. package/dist/core/resolve/index.d.mts +2 -2
  37. package/dist/core/schema/command.d.mts +2 -2
  38. package/dist/core/schema/command.mjs +23 -11
  39. package/dist/core/schema/flag.d.mts +148 -9
  40. package/dist/core/schema/flag.mjs +71 -1
  41. package/dist/core/schema/index.d.mts +2 -2
  42. package/dist/core/schema/run.d.mts +11 -0
  43. package/dist/index.d.mts +7 -6
  44. package/dist/index.mjs +3 -3
  45. package/dist/version.mjs +2 -2
  46. package/dreamcli.schema.json +33 -6
  47. package/package.json +1 -1
@@ -37,6 +37,16 @@ interface FlagConfig {
37
37
  readonly optionalFallback: OptionalFallback;
38
38
  /** The runtime kind discriminator, mirroring {@link FlagKind}. */
39
39
  readonly flagKind: FlagKind;
40
+ /**
41
+ * Whether this builder may still be passed to `flag.array()` as the
42
+ * element schema.
43
+ *
44
+ * Factories producing element-meaningful kinds start `true`. Flag-level
45
+ * modifiers (`.alias()`, `.env()`, `.prompt()`, `.default()`, …) flip it
46
+ * to `false` — those settings describe the *flag*, are never read from an
47
+ * element schema, and would otherwise be silently ignored.
48
+ */
49
+ readonly elementEligible: boolean;
40
50
  }
41
51
  /**
42
52
  * Advanced type helper used by {@linkcode FlagBuilder} modifiers to replace presence.
@@ -47,6 +57,18 @@ type WithPresence<C extends FlagConfig, P extends FlagPresence> = {
47
57
  readonly presence: P;
48
58
  readonly optionalFallback: C['optionalFallback'];
49
59
  readonly flagKind: C['flagKind'];
60
+ readonly elementEligible: false;
61
+ };
62
+ /**
63
+ * Advanced type helper: marks a builder as no longer usable as an array
64
+ * element (returned by flag-level modifiers whose settings elements ignore).
65
+ */
66
+ type WithoutElementEligibility<C extends FlagConfig> = {
67
+ readonly valueType: C['valueType'];
68
+ readonly presence: C['presence'];
69
+ readonly optionalFallback: C['optionalFallback'];
70
+ readonly flagKind: C['flagKind'];
71
+ readonly elementEligible: false;
50
72
  };
51
73
  /**
52
74
  * Compute the final value type from config — this is what handlers receive.
@@ -135,6 +157,38 @@ interface FlagAlias {
135
157
  /** Whether the alias is parser-only and hidden from user-facing surfaces. */
136
158
  readonly hidden: boolean;
137
159
  }
160
+ /**
161
+ * Negation settings for a boolean flag (set by `.negatable()`).
162
+ *
163
+ * The negated spelling and the positive form are two spellings of ONE
164
+ * logical flag: they share duplicate policy, and the last CLI occurrence
165
+ * wins across both. The negated spelling is presence-only — `--no-foo=x`
166
+ * is rejected.
167
+ */
168
+ interface FlagNegation {
169
+ /**
170
+ * Explicit negated spelling without the `--` prefix (e.g. `'no-sandbox'`).
171
+ * `undefined` synthesizes `no-<flagName>` wherever the flag name is known.
172
+ */
173
+ readonly alias: string | undefined;
174
+ /** Hide the negated spelling from help, completions, and suggestions. */
175
+ readonly hidden: boolean;
176
+ }
177
+ /**
178
+ * How repeated CLI occurrences of a singleton flag combine.
179
+ *
180
+ * - `'last'` — last occurrence wins (matches historic behavior)
181
+ * - `'first'` — first occurrence wins; later ones parse but are ignored
182
+ * - `'error'` — a second occurrence is a `ParseError` (`DUPLICATE_FLAG`)
183
+ *
184
+ * Applies to CLI token occurrences only — env/config/prompt/default
185
+ * resolution keeps its precedence semantics and never raises duplicates.
186
+ * Occurrences are counted per *logical* flag: aliases and the negated
187
+ * spelling all count toward the same flag.
188
+ *
189
+ * @defaultValue `'last'`
190
+ */
191
+ type DuplicatePolicy = 'last' | 'first' | 'error';
138
192
  /**
139
193
  * The runtime descriptor stored inside every {@linkcode FlagBuilder}. Consumers (parser,
140
194
  * help generator, resolution chain) read this to understand the flag's shape
@@ -227,6 +281,17 @@ interface FlagSchema {
227
281
  * @defaultValue `false`
228
282
  */
229
283
  readonly propagate: boolean;
284
+ /**
285
+ * Negation settings when `kind === 'boolean'` and `.negatable()` was
286
+ * called (`undefined` otherwise). See {@link FlagNegation}.
287
+ */
288
+ readonly negation: FlagNegation | undefined;
289
+ /**
290
+ * Duplicate policy for repeated CLI occurrences. See {@link DuplicatePolicy}.
291
+ *
292
+ * @defaultValue `'last'`
293
+ */
294
+ readonly duplicates: DuplicatePolicy;
230
295
  }
231
296
  /**
232
297
  * Low-level overrides accepted by {@link createSchema}.
@@ -262,6 +327,18 @@ declare function getFlagAliasNames(schema: FlagSchema, options?: {
262
327
  readonly includeHidden?: boolean;
263
328
  readonly kind?: 'all' | 'short' | 'long';
264
329
  }): readonly string[];
330
+ /**
331
+ * Effective negated spelling for a flag, or `undefined` when not negatable.
332
+ *
333
+ * The builder cannot know its flag name, so a default (`no-<name>`) is
334
+ * synthesized here — everywhere the canonical name is known (parser, help,
335
+ * completions, collision validation).
336
+ *
337
+ * @param name - Canonical flag name.
338
+ * @param schema - Flag schema (read for {@link FlagNegation}).
339
+ * @returns The negated spelling without the `--` prefix.
340
+ */
341
+ declare function getFlagNegatedName(name: string, schema: FlagSchema): string | undefined;
265
342
  /**
266
343
  * Create a raw {@link FlagSchema} object with sensible defaults.
267
344
  *
@@ -372,7 +449,7 @@ declare class FlagBuilder<C extends FlagConfig> {
372
449
  */
373
450
  alias(name: string, options?: {
374
451
  hidden?: boolean;
375
- }): FlagBuilder<C>;
452
+ }): FlagBuilder<WithoutElementEligibility<C>>;
376
453
  /**
377
454
  * Bind to an environment variable (resolved in v0.2+).
378
455
  *
@@ -387,7 +464,7 @@ declare class FlagBuilder<C extends FlagConfig> {
387
464
  * // $ mycli request --api-key sk-456 → apiKey = 'sk-456' (CLI wins)
388
465
  * ```
389
466
  */
390
- env(varName: string): FlagBuilder<C>;
467
+ env(varName: string): FlagBuilder<WithoutElementEligibility<C>>;
391
468
  /**
392
469
  * Bind to a dotted config path (resolved in v0.2+).
393
470
  *
@@ -404,14 +481,14 @@ declare class FlagBuilder<C extends FlagConfig> {
404
481
  * // # → CLI flag wins
405
482
  * ```
406
483
  */
407
- config(path: string): FlagBuilder<C>;
484
+ config(path: string): FlagBuilder<WithoutElementEligibility<C>>;
408
485
  /**
409
486
  * Human-readable description shown in help output.
410
487
  *
411
488
  * @param description - Text displayed next to the flag in `--help`.
412
489
  * @returns The builder (for chaining).
413
490
  */
414
- describe(description: string): FlagBuilder<C>;
491
+ describe(description: string): FlagBuilder<WithoutElementEligibility<C>>;
415
492
  /**
416
493
  * Attach interactive prompt configuration for v0.3+ resolution.
417
494
  *
@@ -431,7 +508,7 @@ declare class FlagBuilder<C extends FlagConfig> {
431
508
  * // $ mycli init --name foo → skips prompt, uses CLI value
432
509
  * ```
433
510
  */
434
- prompt(config: AllowedPromptConfig<C>): FlagBuilder<C>;
511
+ prompt(config: AllowedPromptConfig<C>): FlagBuilder<WithoutElementEligibility<C>>;
435
512
  /**
436
513
  * Mark this flag as deprecated.
437
514
  *
@@ -451,7 +528,7 @@ declare class FlagBuilder<C extends FlagConfig> {
451
528
  * // ⚠ --dest is deprecated: Use --target instead
452
529
  * ```
453
530
  */
454
- deprecated(message?: string): FlagBuilder<C>;
531
+ deprecated(message?: string): FlagBuilder<WithoutElementEligibility<C>>;
455
532
  /**
456
533
  * Mark this flag as propagated to subcommands.
457
534
  *
@@ -473,7 +550,7 @@ declare class FlagBuilder<C extends FlagConfig> {
473
550
  * // # → same, inherited from parent
474
551
  * ```
475
552
  */
476
- propagate(): FlagBuilder<C>;
553
+ propagate(): FlagBuilder<WithoutElementEligibility<C>>;
477
554
  /**
478
555
  * Require an integer value. Composes with other numeric constraints.
479
556
  *
@@ -636,6 +713,53 @@ declare class FlagBuilder<C extends FlagConfig> {
636
713
  unique(this: FlagBuilder<C & {
637
714
  readonly flagKind: 'array';
638
715
  }>, value?: boolean): FlagBuilder<C>;
716
+ /**
717
+ * Accept a negated spelling (`--no-<name>`) that sets the flag to `false`.
718
+ *
719
+ * Both spellings are ONE logical flag: the last CLI occurrence wins across
720
+ * them, and they share the duplicate policy. The negated spelling is
721
+ * presence-only — `--no-<name>=true` is rejected. Help renders the flag as
722
+ * `--[no-]<name>` (or lists a custom alias); env/config/prompt/default
723
+ * resolution is unaffected.
724
+ *
725
+ * @param options - Optional custom spelling (`alias`, without `--`) and
726
+ * `hidden` to keep the negated spelling parseable but unadvertised.
727
+ * @returns The builder (for chaining).
728
+ *
729
+ * @example
730
+ * ```ts
731
+ * flag.boolean().default(true).negatable()
732
+ * // $ mycli build --no-sandbox → sandbox = false
733
+ * // $ mycli build --sandbox → sandbox = true
734
+ * ```
735
+ */
736
+ negatable(this: FlagBuilder<C & {
737
+ readonly flagKind: 'boolean';
738
+ }>, options?: {
739
+ alias?: string;
740
+ hidden?: boolean;
741
+ }): FlagBuilder<WithoutElementEligibility<C>>;
742
+ /**
743
+ * Set how repeated CLI occurrences of this flag combine.
744
+ *
745
+ * Counted per logical flag — aliases and the negated spelling all count
746
+ * toward the same flag. CLI tokens only: env/config/prompt/default
747
+ * resolution keeps its precedence semantics. Not available on `array`,
748
+ * `count`, or `keyValue` flags, which inherently accumulate.
749
+ *
750
+ * @param policy - `'last'` (default), `'first'`, or `'error'`.
751
+ * @returns The builder (for chaining).
752
+ *
753
+ * @example
754
+ * ```ts
755
+ * flag.enum(['session', 'same-dir', 'worktree']).duplicates('error')
756
+ * // $ mycli run --spawn session --spawn worktree
757
+ * // # → Error: Flag --spawn may only be specified once
758
+ * ```
759
+ */
760
+ duplicates(this: FlagBuilder<C & {
761
+ readonly flagKind: 'boolean' | 'string' | 'number' | 'enum' | 'custom';
762
+ }>, policy: DuplicatePolicy): FlagBuilder<WithoutElementEligibility<C>>;
639
763
  }
640
764
  /**
641
765
  * Factory that creates {@link FlagBuilder} instances seeded with the correct
@@ -666,6 +790,7 @@ interface FlagFactory {
666
790
  readonly presence: 'optional';
667
791
  readonly optionalFallback: 'undefined';
668
792
  readonly flagKind: 'string';
793
+ readonly elementEligible: true;
669
794
  }>;
670
795
  /**
671
796
  * Number-valued flag, with optional numeric constraints.
@@ -694,6 +819,7 @@ interface FlagFactory {
694
819
  readonly presence: 'optional';
695
820
  readonly optionalFallback: 'undefined';
696
821
  readonly flagKind: 'number';
822
+ readonly elementEligible: true;
697
823
  }>;
698
824
  /**
699
825
  * Boolean flag. Implicitly defaults to `false` — the only flag kind where
@@ -706,6 +832,7 @@ interface FlagFactory {
706
832
  readonly presence: 'defaulted';
707
833
  readonly optionalFallback: 'undefined';
708
834
  readonly flagKind: 'boolean';
835
+ readonly elementEligible: true;
709
836
  }>;
710
837
  /**
711
838
  * Enum flag with literal type inference.
@@ -727,6 +854,7 @@ interface FlagFactory {
727
854
  readonly presence: 'optional';
728
855
  readonly optionalFallback: 'undefined';
729
856
  readonly flagKind: 'enum';
857
+ readonly elementEligible: true;
730
858
  }>;
731
859
  /**
732
860
  * Array flag — collects multiple values of the same element type.
@@ -740,11 +868,14 @@ interface FlagFactory {
740
868
  * @param element - {@link FlagBuilder} describing the element type.
741
869
  * @returns A {@link FlagBuilder} for arrays of the element type.
742
870
  */
743
- array<E extends FlagConfig>(element: FlagBuilder<E>): FlagBuilder<{
871
+ array<E extends FlagConfig & {
872
+ readonly elementEligible: true;
873
+ }>(element: FlagBuilder<E>): FlagBuilder<{
744
874
  readonly valueType: E['valueType'][];
745
875
  readonly presence: 'optional';
746
876
  readonly optionalFallback: 'empty-array';
747
877
  readonly flagKind: 'array';
878
+ readonly elementEligible: false;
748
879
  }>;
749
880
  /**
750
881
  * Custom-parsed flag. The parse function receives the raw value and must
@@ -780,6 +911,7 @@ interface FlagFactory {
780
911
  readonly presence: 'optional';
781
912
  readonly optionalFallback: 'undefined';
782
913
  readonly flagKind: 'custom';
914
+ readonly elementEligible: true;
783
915
  }>;
784
916
  /**
785
917
  * URL-valued flag. Parses into a `URL`; invalid URLs are rejected with an
@@ -799,6 +931,7 @@ interface FlagFactory {
799
931
  readonly presence: 'optional';
800
932
  readonly optionalFallback: 'undefined';
801
933
  readonly flagKind: 'custom';
934
+ readonly elementEligible: true;
802
935
  }>;
803
936
  /**
804
937
  * Path-valued flag. The value stays a `string`; optional filesystem
@@ -821,6 +954,7 @@ interface FlagFactory {
821
954
  readonly presence: 'optional';
822
955
  readonly optionalFallback: 'undefined';
823
956
  readonly flagKind: 'string';
957
+ readonly elementEligible: false;
824
958
  }>;
825
959
  /**
826
960
  * Date-valued flag. Accepts strict ISO-8601 (`2026-07-10`,
@@ -846,6 +980,7 @@ interface FlagFactory {
846
980
  readonly presence: 'optional';
847
981
  readonly optionalFallback: 'undefined';
848
982
  readonly flagKind: 'custom';
983
+ readonly elementEligible: true;
849
984
  }>;
850
985
  /**
851
986
  * Duration flag. Accepts `'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`,
@@ -864,6 +999,7 @@ interface FlagFactory {
864
999
  readonly presence: 'optional';
865
1000
  readonly optionalFallback: 'undefined';
866
1001
  readonly flagKind: 'custom';
1002
+ readonly elementEligible: true;
867
1003
  }>;
868
1004
  /**
869
1005
  * Byte-size flag. Accepts `'512mb'`, `'1.5gb'`, `'64kb'`, `'100b'` or a
@@ -882,6 +1018,7 @@ interface FlagFactory {
882
1018
  readonly presence: 'optional';
883
1019
  readonly optionalFallback: 'undefined';
884
1020
  readonly flagKind: 'custom';
1021
+ readonly elementEligible: true;
885
1022
  }>;
886
1023
  /**
887
1024
  * Count flag — resolves to how many times the flag appears. `-vvv`,
@@ -904,6 +1041,7 @@ interface FlagFactory {
904
1041
  readonly presence: 'defaulted';
905
1042
  readonly optionalFallback: 'undefined';
906
1043
  readonly flagKind: 'count';
1044
+ readonly elementEligible: false;
907
1045
  }>;
908
1046
  /**
909
1047
  * Key-value flag — repeated `KEY=VALUE` occurrences merge into a
@@ -927,6 +1065,7 @@ interface FlagFactory {
927
1065
  readonly presence: 'optional';
928
1066
  readonly optionalFallback: 'empty-object';
929
1067
  readonly flagKind: 'keyValue';
1068
+ readonly elementEligible: false;
930
1069
  }>;
931
1070
  }
932
1071
  /**
@@ -935,4 +1074,4 @@ interface FlagFactory {
935
1074
  */
936
1075
  declare const flag: FlagFactory;
937
1076
  //#endregion
938
- export { type AllowedPromptConfig, type ConfirmPromptConfig, type DateFlagOptions, FLAG_KINDS, FLAG_PRESENCES, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FlagSchemaOverrides, type InferFlag, type InferFlags, type InputPromptConfig, type MultiselectPromptConfig, type OptionalFallback, PROMPT_KINDS, type PathChecks, type PathFlagOptions, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type ResolvedValue, type SelectChoice, type SelectPromptConfig, type StringConstraintViolation, type StringConstraints, type UrlFlagOptions, type WithPresence, createSchema, flag, getFlagAliasNames, normalizeFlagAlias, normalizeFlagAliases };
1077
+ export { type AllowedPromptConfig, type ConfirmPromptConfig, type DateFlagOptions, type DuplicatePolicy, FLAG_KINDS, FLAG_PRESENCES, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagNegation, type FlagParseFn, type FlagPresence, type FlagSchema, type FlagSchemaOverrides, type InferFlag, type InferFlags, type InputPromptConfig, type MultiselectPromptConfig, type OptionalFallback, PROMPT_KINDS, type PathChecks, type PathFlagOptions, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type ResolvedValue, type SelectChoice, type SelectPromptConfig, type StringConstraintViolation, type StringConstraints, type UrlFlagOptions, type WithPresence, createSchema, flag, getFlagAliasNames, getFlagNegatedName, normalizeFlagAlias, normalizeFlagAliases };
@@ -54,6 +54,21 @@ function getFlagAliasNames(schema, options) {
54
54
  }).map((alias) => alias.name);
55
55
  }
56
56
  /**
57
+ * Effective negated spelling for a flag, or `undefined` when not negatable.
58
+ *
59
+ * The builder cannot know its flag name, so a default (`no-<name>`) is
60
+ * synthesized here — everywhere the canonical name is known (parser, help,
61
+ * completions, collision validation).
62
+ *
63
+ * @param name - Canonical flag name.
64
+ * @param schema - Flag schema (read for {@link FlagNegation}).
65
+ * @returns The negated spelling without the `--` prefix.
66
+ */
67
+ function getFlagNegatedName(name, schema) {
68
+ if (schema.negation === void 0) return void 0;
69
+ return schema.negation.alias ?? `no-${name}`;
70
+ }
71
+ /**
57
72
  * Create a raw {@link FlagSchema} object with sensible defaults.
58
73
  *
59
74
  * Most consumers should prefer the higher-level {@link flag} factory,
@@ -99,6 +114,8 @@ function createSchema(kind, overrides) {
99
114
  parseFn: void 0,
100
115
  deprecated: void 0,
101
116
  propagate: false,
117
+ negation: void 0,
118
+ duplicates: "last",
102
119
  ...rest,
103
120
  aliases
104
121
  };
@@ -559,6 +576,59 @@ var FlagBuilder = class FlagBuilder {
559
576
  unique: value
560
577
  });
561
578
  }
579
+ /**
580
+ * Accept a negated spelling (`--no-<name>`) that sets the flag to `false`.
581
+ *
582
+ * Both spellings are ONE logical flag: the last CLI occurrence wins across
583
+ * them, and they share the duplicate policy. The negated spelling is
584
+ * presence-only — `--no-<name>=true` is rejected. Help renders the flag as
585
+ * `--[no-]<name>` (or lists a custom alias); env/config/prompt/default
586
+ * resolution is unaffected.
587
+ *
588
+ * @param options - Optional custom spelling (`alias`, without `--`) and
589
+ * `hidden` to keep the negated spelling parseable but unadvertised.
590
+ * @returns The builder (for chaining).
591
+ *
592
+ * @example
593
+ * ```ts
594
+ * flag.boolean().default(true).negatable()
595
+ * // $ mycli build --no-sandbox → sandbox = false
596
+ * // $ mycli build --sandbox → sandbox = true
597
+ * ```
598
+ */
599
+ negatable(options) {
600
+ return new FlagBuilder({
601
+ ...this.schema,
602
+ negation: {
603
+ alias: options?.alias,
604
+ hidden: options?.hidden ?? false
605
+ }
606
+ });
607
+ }
608
+ /**
609
+ * Set how repeated CLI occurrences of this flag combine.
610
+ *
611
+ * Counted per logical flag — aliases and the negated spelling all count
612
+ * toward the same flag. CLI tokens only: env/config/prompt/default
613
+ * resolution keeps its precedence semantics. Not available on `array`,
614
+ * `count`, or `keyValue` flags, which inherently accumulate.
615
+ *
616
+ * @param policy - `'last'` (default), `'first'`, or `'error'`.
617
+ * @returns The builder (for chaining).
618
+ *
619
+ * @example
620
+ * ```ts
621
+ * flag.enum(['session', 'same-dir', 'worktree']).duplicates('error')
622
+ * // $ mycli run --spawn session --spawn worktree
623
+ * // # → Error: Flag --spawn may only be specified once
624
+ * ```
625
+ */
626
+ duplicates(policy) {
627
+ return new FlagBuilder({
628
+ ...this.schema,
629
+ duplicates: policy
630
+ });
631
+ }
562
632
  };
563
633
  /**
564
634
  * Flag schema factory. Call `flag.<kind>()` to create an immutable
@@ -632,4 +702,4 @@ const flag = {
632
702
  }
633
703
  };
634
704
  //#endregion
635
- export { FlagBuilder, createSchema, flag, getFlagAliasNames, normalizeFlagAlias, normalizeFlagAliases };
705
+ export { FlagBuilder, createSchema, flag, getFlagAliasNames, getFlagNegatedName, normalizeFlagAlias, normalizeFlagAliases };
@@ -4,8 +4,8 @@ import { ARG_KINDS, ARG_PRESENCES, ArgBuilder, ArgConfig, ArgFactory, ArgKind, A
4
4
  import { ConfirmPromptConfig, InputPromptConfig, MultiselectPromptConfig, PROMPT_KINDS, PromptConfig, PromptConfigBase, PromptKind, PromptResult, SelectChoice, SelectPromptConfig } from "./prompt.mjs";
5
5
  import { StringConstraintViolation, StringConstraints, describeStringConstraintViolation, validateStringConstraints } from "./string-constraints.mjs";
6
6
  import { DateFlagOptions, UrlFlagOptions } from "./value-parsers.mjs";
7
- import { FLAG_KINDS, FLAG_PRESENCES, FlagAlias, FlagBuilder, FlagConfig, FlagFactory, FlagKind, FlagParseFn, FlagPresence, FlagSchema, FlagSchemaOverrides, InferFlag, InferFlags, PathChecks, PathFlagOptions, ResolvedValue, WithPresence, createSchema, flag } from "./flag.mjs";
7
+ import { DuplicatePolicy, FLAG_KINDS, FLAG_PRESENCES, FlagAlias, FlagBuilder, FlagConfig, FlagFactory, FlagKind, FlagNegation, FlagParseFn, FlagPresence, FlagSchema, FlagSchemaOverrides, InferFlag, InferFlags, PathChecks, PathFlagOptions, ResolvedValue, WithPresence, createSchema, flag, getFlagNegatedName } from "./flag.mjs";
8
8
  import { ErasedMiddlewareHandler, Middleware, MiddlewareHandler, MiddlewareParams, middleware } from "./middleware.mjs";
9
9
  import { RunOptions, RunResult } from "./run.mjs";
10
10
  import { ActionHandler, ActionParams, AnyCommandBuilder, CommandArgEntry, CommandBuilder, CommandConfig, CommandExample, CommandMeta, CommandSchema, DeriveHandler, DeriveParams, ErasedCommand, ErasedDeriveHandler, ErasedInteractiveResolver, InteractiveParams, InteractiveResolver, InteractiveResult, Out, command, group } from "./command.mjs";
11
- 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 DateFlagOptions, 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 PathChecks, type PathFlagOptions, 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 StringConstraintViolation, type StringConstraints, type TableColumn, type TableFormat, type TableOptions, type TableStream, type UrlFlagOptions, type WithArgPresence, type WithPresence, type WithVariadic, arg, command, createArgSchema, createSchema, describeNumberConstraintViolation, describeStringConstraintViolation, flag, group, middleware, validateNumberConstraints, validateStringConstraints };
11
+ 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 DateFlagOptions, type DeriveHandler, type DeriveParams, type DuplicatePolicy, type ErasedCommand, type ErasedDeriveHandler, type ErasedInteractiveResolver, type ErasedMiddlewareHandler, FLAG_KINDS, FLAG_PRESENCES, type Fallback, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagNegation, 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 PathChecks, type PathFlagOptions, 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 StringConstraintViolation, type StringConstraints, type TableColumn, type TableFormat, type TableOptions, type TableStream, type UrlFlagOptions, type WithArgPresence, type WithPresence, type WithVariadic, arg, command, createArgSchema, createSchema, describeNumberConstraintViolation, describeStringConstraintViolation, flag, getFlagNegatedName, group, middleware, validateNumberConstraints, validateStringConstraints };
@@ -6,6 +6,7 @@ import { CLIPlugin } from "../cli/plugin.mjs";
6
6
  import { CLIError } from "../errors/index.mjs";
7
7
  import { HelpOptions } from "../help/index.mjs";
8
8
  import { CommandMeta, CommandSchema, Out } from "./command.mjs";
9
+ import { ParseOptions } from "../parse/index.mjs";
9
10
  //#region src/core/schema/run.d.ts
10
11
  /**
11
12
  * Options accepted by `runCommand()` and internal command execution paths.
@@ -111,6 +112,16 @@ interface RunOptions {
111
112
  * Used when `--help` is detected.
112
113
  */
113
114
  readonly help?: HelpOptions;
115
+ /**
116
+ * Flag-parsing behavior settings.
117
+ *
118
+ * `caseParity` accepts the kebab↔camel counterpart spelling of each flag
119
+ * name/alias (`--doThis` for `do-this`, and vice versa). The CLI layer
120
+ * threads `cli(name, { flags })` settings here automatically.
121
+ *
122
+ * @defaultValue `{ caseParity: true }`
123
+ */
124
+ readonly flags?: ParseOptions;
114
125
  /**
115
126
  * Command schema with propagated flags merged in.
116
127
  *
package/dist/index.d.mts CHANGED
@@ -4,10 +4,8 @@ import { ArgBuilder, ArgConfig, ArgFactory, ArgKind, ArgParseFn, ArgPresence, Ar
4
4
  import { ConfirmPromptConfig, InputPromptConfig, MultiselectPromptConfig, PromptConfig, PromptConfigBase, PromptKind, PromptResult, SelectChoice, SelectPromptConfig } from "./core/schema/prompt.mjs";
5
5
  import { StringConstraintViolation, StringConstraints } from "./core/schema/string-constraints.mjs";
6
6
  import { DateFlagOptions, UrlFlagOptions } from "./core/schema/value-parsers.mjs";
7
- import { FlagBuilder, FlagConfig, FlagFactory, FlagKind, FlagParseFn, FlagPresence, FlagSchema, InferFlag, InferFlags, PathChecks, PathFlagOptions, ResolvedValue, WithPresence, createSchema, flag } from "./core/schema/flag.mjs";
7
+ import { DuplicatePolicy, FlagBuilder, FlagConfig, FlagFactory, FlagKind, FlagNegation, FlagParseFn, FlagPresence, FlagSchema, InferFlag, InferFlags, PathChecks, PathFlagOptions, ResolvedValue, WithPresence, createSchema, flag, getFlagNegatedName } from "./core/schema/flag.mjs";
8
8
  import { Middleware, MiddlewareHandler, MiddlewareParams, middleware } from "./core/schema/middleware.mjs";
9
- import "./core/schema/index.mjs";
10
- import { ParseResult, Token, parse, tokenize } from "./core/parse/index.mjs";
11
9
  import { WriteFn } from "./core/output/writer.mjs";
12
10
  import { Verbosity } from "./core/output/contracts.mjs";
13
11
  import { OutputOptions, createOutput } from "./core/output/index.mjs";
@@ -16,11 +14,14 @@ import { DeprecationWarning, ResolveOptions, ResolveResult } from "./core/resolv
16
14
  import { resolve } from "./core/resolve/index.mjs";
17
15
  import { BeforeParseParams, CLIPlugin, CLIPluginHooks, PluginCommandContext, ResolvedCommandParams, plugin } from "./core/cli/plugin.mjs";
18
16
  import { CLIError, CLIErrorJSON, CLIErrorOptions, ErrorCode, ParseError, ParseErrorCode, ParseErrorOptions, ValidationError, ValidationErrorCode, ValidationErrorOptions, isCLIError, isParseError, isValidationError } from "./core/errors/index.mjs";
17
+ import { HelpTheme, HelpThemeFactory } from "./core/help/theme.mjs";
19
18
  import { osc8, visibleWidth } from "./core/help/ansi.mjs";
20
19
  import { HelpOptions, formatHelp } from "./core/help/index.mjs";
21
20
  import { RunResult } from "./core/schema/run.mjs";
22
21
  import { ActionHandler, ActionParams, AnyCommandBuilder, CommandArgEntry, CommandBuilder, CommandConfig, CommandExample, CommandMeta, CommandSchema, DeriveHandler, DeriveParams, InteractiveParams, InteractiveResolver, InteractiveResult, Out, command, group } from "./core/schema/command.mjs";
23
- import { ManifestDiscoveryOptions, PackageJsonAdapter, PackageJsonData, PackageRepository, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl } from "./core/config/package-json.mjs";
22
+ import "./core/schema/index.mjs";
23
+ import { ParseOptions, ParseResult, Token, parse, tokenize } from "./core/parse/index.mjs";
24
+ import { ManifestDiscoveryOptions, PackageJsonAdapter, PackageJsonData, PackageRepository, PackageRepositoryUrlOptions, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl } from "./core/config/package-json.mjs";
24
25
  import { HelpLinks } from "./core/cli/help-links.mjs";
25
26
  import { CompletionOptions } from "./core/completion/shells/shared.mjs";
26
27
  import { generateBashCompletion } from "./core/completion/shells/bash.mjs";
@@ -30,6 +31,6 @@ import { generateZshCompletion } from "./core/completion/shells/zsh.mjs";
30
31
  import { SHELLS, Shell, generateCompletion } from "./core/completion/index.mjs";
31
32
  import { ConfigAdapter, ConfigDiscoveryOptions, ConfigDiscoveryResult, ConfigFound, ConfigNotFound, FormatLoader, buildConfigSearchPaths, configFormat, discoverConfig } from "./core/config/index.mjs";
32
33
  import { CLIBuilder, CLIOptions, CLIRunOptions, CLISchema, ConfigSettings, DefaultCommandOptions, InferNameOption, ManifestPresetSettings, ManifestSettings, PackageJsonSettings, ResolvedManifestSettings, cli } from "./core/cli/index.mjs";
33
- import { JsonSchemaOptions, definitionMetaSchema, generateInputSchema, generateSchema } from "./core/json-schema/index.mjs";
34
+ import { JsonSchemaOptions, definitionMetaSchema, generateCommandSchema, generateInputSchema, generateSchema } from "./core/json-schema/index.mjs";
34
35
  import { Colors } from "ansispeck";
35
- export { type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type BeforeParseParams, CLIBuilder, CLIError, type CLIErrorJSON, type CLIErrorOptions, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type Colors, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type CompletionOptions, type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type ConfigSettings, type ConfirmPromptConfig, type DateFlagOptions, type DefaultCommandOptions, type DeprecationWarning, type DeriveHandler, type DeriveParams, type ErrorCode, type Fallback, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FormatLoader, type HelpLinks, type HelpOptions, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InferNameOption, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type JsonSchemaOptions, type ManifestDiscoveryOptions, type ManifestPresetSettings, type ManifestSettings, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type NumberConstraintViolation, type NumberConstraints, type Out, type OutputOptions, type PackageJsonAdapter, type PackageJsonData, type PackageJsonSettings, type PackageRepository, ParseError, type ParseErrorCode, type ParseErrorOptions, type ParseResult, type PathChecks, type PathFlagOptions, type PluginCommandContext, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptEngine, type PromptKind, type PromptResult, type ReadFn, type ResolveOptions, type ResolveResult, type ResolvedArgValue, type ResolvedCommandParams, type ResolvedManifestSettings, type ResolvedMultiselectPromptConfig, type ResolvedPromptConfig, type ResolvedSelectPromptConfig, type ResolvedValue, type RunResult, SHELLS, type SelectChoice, type SelectPromptConfig, type Shell, type SpinnerHandle, type SpinnerOptions, type StringConstraintViolation, type StringConstraints, type TableColumn, type TableFormat, type TableOptions, type TableStream, type Token, type UrlFlagOptions, ValidationError, type ValidationErrorCode, type ValidationErrorOptions, type Verbosity, type WithArgPresence, type WithPresence, type WithVariadic, type WriteFn, arg, buildConfigSearchPaths, cli, command, configFormat, createArgSchema, createOutput, createSchema, createTerminalPrompter, definitionMetaSchema, discoverConfig, discoverManifest, discoverPackageJson, flag, formatHelp, generateBashCompletion, generateCompletion, generateFishCompletion, generateInputSchema, generatePowerShellCompletion, generateSchema, generateZshCompletion, group, inferCliName, isCLIError, isParseError, isValidationError, middleware, osc8, packageRepositoryUrl, parse, plugin, resolve, resolvePromptConfig, tokenize, visibleWidth };
36
+ export { type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type BeforeParseParams, CLIBuilder, CLIError, type CLIErrorJSON, type CLIErrorOptions, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type Colors, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type CompletionOptions, type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type ConfigSettings, type ConfirmPromptConfig, type DateFlagOptions, type DefaultCommandOptions, type DeprecationWarning, type DeriveHandler, type DeriveParams, type DuplicatePolicy, type ErrorCode, type Fallback, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagNegation, type FlagParseFn, type FlagPresence, type FlagSchema, type FormatLoader, type HelpLinks, type HelpOptions, type HelpTheme, type HelpThemeFactory, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InferNameOption, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type JsonSchemaOptions, type ManifestDiscoveryOptions, type ManifestPresetSettings, type ManifestSettings, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type NumberConstraintViolation, type NumberConstraints, type Out, type OutputOptions, type PackageJsonAdapter, type PackageJsonData, type PackageJsonSettings, type PackageRepository, type PackageRepositoryUrlOptions, ParseError, type ParseErrorCode, type ParseErrorOptions, type ParseOptions, type ParseResult, type PathChecks, type PathFlagOptions, type PluginCommandContext, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptEngine, type PromptKind, type PromptResult, type ReadFn, type ResolveOptions, type ResolveResult, type ResolvedArgValue, type ResolvedCommandParams, type ResolvedManifestSettings, type ResolvedMultiselectPromptConfig, type ResolvedPromptConfig, type ResolvedSelectPromptConfig, type ResolvedValue, type RunResult, SHELLS, type SelectChoice, type SelectPromptConfig, type Shell, type SpinnerHandle, type SpinnerOptions, type StringConstraintViolation, type StringConstraints, type TableColumn, type TableFormat, type TableOptions, type TableStream, type Token, type UrlFlagOptions, ValidationError, type ValidationErrorCode, type ValidationErrorOptions, type Verbosity, type WithArgPresence, type WithPresence, type WithVariadic, type WriteFn, arg, buildConfigSearchPaths, cli, command, configFormat, createArgSchema, createOutput, createSchema, createTerminalPrompter, definitionMetaSchema, discoverConfig, discoverManifest, discoverPackageJson, flag, formatHelp, generateBashCompletion, generateCommandSchema, generateCompletion, generateFishCompletion, generateInputSchema, generatePowerShellCompletion, generateSchema, generateZshCompletion, getFlagNegatedName, group, inferCliName, isCLIError, isParseError, isValidationError, middleware, osc8, packageRepositoryUrl, parse, plugin, resolve, resolvePromptConfig, tokenize, visibleWidth };
package/dist/index.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  import { CLIError, ParseError, ValidationError, isCLIError, isParseError, isValidationError } from "./core/errors/index.mjs";
2
- import { FlagBuilder, createSchema, flag } from "./core/schema/flag.mjs";
2
+ import { FlagBuilder, createSchema, flag, getFlagNegatedName } from "./core/schema/flag.mjs";
3
3
  import { ArgBuilder, arg, createArgSchema } from "./core/schema/arg.mjs";
4
4
  import { CommandBuilder, command, group } from "./core/schema/command.mjs";
5
5
  import { middleware } from "./core/schema/middleware.mjs";
@@ -11,6 +11,7 @@ import { generateZshCompletion } from "./core/completion/shells/zsh.mjs";
11
11
  import { SHELLS, generateCompletion } from "./core/completion/index.mjs";
12
12
  import { osc8, visibleWidth } from "./core/help/ansi.mjs";
13
13
  import { formatHelp } from "./core/help/index.mjs";
14
+ import { definitionMetaSchema, generateCommandSchema, generateInputSchema, generateSchema } from "./core/json-schema/index.mjs";
14
15
  import { createOutput } from "./core/output/index.mjs";
15
16
  import { createTerminalPrompter, resolvePromptConfig } from "./core/prompt/index.mjs";
16
17
  import { resolve } from "./core/resolve/index.mjs";
@@ -18,5 +19,4 @@ import { discoverManifest, discoverPackageJson, inferCliName, packageRepositoryU
18
19
  import { plugin } from "./core/cli/plugin.mjs";
19
20
  import { buildConfigSearchPaths, configFormat, discoverConfig } from "./core/config/index.mjs";
20
21
  import { CLIBuilder, cli } from "./core/cli/index.mjs";
21
- import { definitionMetaSchema, generateInputSchema, generateSchema } from "./core/json-schema/index.mjs";
22
- export { ArgBuilder, CLIBuilder, CLIError, CommandBuilder, FlagBuilder, ParseError, SHELLS, ValidationError, arg, buildConfigSearchPaths, cli, command, configFormat, createArgSchema, createOutput, createSchema, createTerminalPrompter, definitionMetaSchema, discoverConfig, discoverManifest, discoverPackageJson, flag, formatHelp, generateBashCompletion, generateCompletion, generateFishCompletion, generateInputSchema, generatePowerShellCompletion, generateSchema, generateZshCompletion, group, inferCliName, isCLIError, isParseError, isValidationError, middleware, osc8, packageRepositoryUrl, parse, plugin, resolve, resolvePromptConfig, tokenize, visibleWidth };
22
+ export { ArgBuilder, CLIBuilder, CLIError, CommandBuilder, FlagBuilder, ParseError, SHELLS, ValidationError, arg, buildConfigSearchPaths, cli, command, configFormat, createArgSchema, createOutput, createSchema, createTerminalPrompter, definitionMetaSchema, discoverConfig, discoverManifest, discoverPackageJson, flag, formatHelp, generateBashCompletion, generateCommandSchema, generateCompletion, generateFishCompletion, generateInputSchema, generatePowerShellCompletion, generateSchema, generateZshCompletion, getFlagNegatedName, group, inferCliName, isCLIError, isParseError, isValidationError, middleware, osc8, packageRepositoryUrl, parse, plugin, resolve, resolvePromptConfig, tokenize, visibleWidth };
package/dist/version.mjs CHANGED
@@ -1,7 +1,7 @@
1
1
  //#region src/version.ts
2
2
  /** Package version (e.g. `"0.9.1"`). `"dev"` when running unbundled. */
3
- const DREAMCLI_VERSION = "3.0.0-rc.7";
3
+ const DREAMCLI_VERSION = "3.0.0-rc.9";
4
4
  /** Git short SHA (e.g. `"f9b5f1a"`). `"dev"` when running unbundled. */
5
- const DREAMCLI_REVISION = "e87f393";
5
+ const DREAMCLI_REVISION = "6a62e80";
6
6
  //#endregion
7
7
  export { DREAMCLI_REVISION, DREAMCLI_VERSION };
@@ -22,7 +22,7 @@
22
22
  "description": "Program description (shown in root help)."
23
23
  },
24
24
  "defaultCommand": {
25
- "type": "string",
25
+ "$ref": "#/$defs/command",
26
26
  "description": "Default command dispatched when no subcommand matches.\n\nWhen set, the CLI root behaves like a hybrid command group: subcommands\ndispatch by name as usual, but empty argv or flags-only argv falls\nthrough to this command instead of showing root help.\n\nSet via the .default() builder method."
27
27
  },
28
28
  "commands": {
@@ -174,7 +174,19 @@
174
174
  },
175
175
  "propagate": {
176
176
  "const": true,
177
- "description": "Whether this flag propagates to subcommands in nested command trees.\n\nWhen `true`, the flag is automatically available to all descendant\ncommands. A child command that defines a flag with the same name\nshadows the propagated parent flag."
177
+ "description": "Whether this flag propagates to subcommands in nested command trees.\n\nWhen `true`, the flag is automatically available to all descendant\ncommands. A child command that defines a flag with the same name\nshadows the propagated parent flag.\n\nDefault: `false`"
178
+ },
179
+ "negation": {
180
+ "$ref": "#/$defs/negation",
181
+ "description": "Negation settings when `kind === 'boolean'` and `.negatable()` was\ncalled (`undefined` otherwise). See FlagNegation."
182
+ },
183
+ "duplicates": {
184
+ "enum": [
185
+ "last",
186
+ "first",
187
+ "error"
188
+ ],
189
+ "description": "How repeated CLI occurrences of a singleton flag combine.\n\n- `'last'` — last occurrence wins (matches historic behavior)\n- `'first'` — first occurrence wins; later ones parse but are ignored\n- `'error'` — a second occurrence is a `ParseError` (`DUPLICATE_FLAG`)\n\nApplies to CLI token occurrences only — env/config/prompt/default\nresolution keeps its precedence semantics and never raises duplicates.\nOccurrences are counted per *logical* flag: aliases and the negated\nspelling all count toward the same flag.\n\nDefault: `'last'`"
178
190
  }
179
191
  },
180
192
  "required": [
@@ -183,6 +195,21 @@
183
195
  ],
184
196
  "description": "The runtime descriptor stored inside every FlagBuilder. Consumers (parser,\nhelp generator, resolution chain) read this to understand the flag's shape\nwithout touching generics."
185
197
  },
198
+ "negation": {
199
+ "type": "object",
200
+ "additionalProperties": false,
201
+ "properties": {
202
+ "alias": {
203
+ "type": "string",
204
+ "description": "Explicit negated spelling without the `--` prefix (e.g. `'no-sandbox'`).\n`undefined` synthesizes `no-<flagName>` wherever the flag name is known."
205
+ },
206
+ "hidden": {
207
+ "const": true,
208
+ "description": "Hide the negated spelling from help, completions, and suggestions."
209
+ }
210
+ },
211
+ "description": "Negation settings for a boolean flag (set by `.negatable()`).\n\nThe negated spelling and the positive form are two spellings of ONE\nlogical flag: they share duplicate policy, and the last CLI occurrence\nwins across both. The negated spelling is presence-only — `--no-foo=x`\nis rejected."
212
+ },
186
213
  "arg": {
187
214
  "type": "object",
188
215
  "additionalProperties": false,
@@ -214,7 +241,7 @@
214
241
  },
215
242
  "stdinMode": {
216
243
  "const": true,
217
- "description": "Whether this arg may read from stdin during resolution."
244
+ "description": "Whether this arg may read from stdin during resolution.\n\nDefault: `false`"
218
245
  },
219
246
  "defaultValue": {
220
247
  "description": "Runtime default value (if any)."
@@ -283,11 +310,11 @@
283
310
  },
284
311
  "min": {
285
312
  "type": "integer",
286
- "description": "Minimum number of selections required."
313
+ "description": "Minimum number of selections required.\n\nDefault: `0`"
287
314
  },
288
315
  "max": {
289
316
  "type": "integer",
290
- "description": "Maximum number of selections allowed."
317
+ "description": "Maximum number of selections allowed.\n\nDefault: `Infinity`"
291
318
  }
292
319
  },
293
320
  "required": [
@@ -306,7 +333,7 @@
306
333
  },
307
334
  "label": {
308
335
  "type": "string",
309
- "description": "Display label shown to the user."
336
+ "description": "Display label shown to the user.\n\nDefault: value"
310
337
  },
311
338
  "description": {
312
339
  "type": "string",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kjanat/dreamcli",
3
- "version": "3.0.0-rc.7",
3
+ "version": "3.0.0-rc.9",
4
4
  "description": "Schema-first, fully typed TypeScript CLI framework",
5
5
  "keywords": [
6
6
  "dreamcli",