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

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 +46 -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 +19 -7
  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 +5 -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 +1 -1
  28. package/dist/core/json-schema/index.mjs +14 -1
  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 +103 -1
  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 +6 -5
  44. package/dist/index.mjs +2 -2
  45. package/dist/version.mjs +2 -2
  46. package/dreamcli.schema.json +32 -5
  47. package/package.json +1 -1
@@ -1,4 +1,5 @@
1
1
  import { CLIError } from "../errors/index.mjs";
2
+ import { getFlagNegatedName } from "./flag.mjs";
2
3
  //#region src/core/schema/command.ts
3
4
  /**
4
5
  * Validate a new arg entry against invariants before adding it to the command.
@@ -39,21 +40,32 @@ function formatFlagToken(name, kind) {
39
40
  }
40
41
  function describeFlagForm(form) {
41
42
  if (form.kind === "canonical") return `canonical flag ${formatFlagToken(form.name, form.kind)}`;
43
+ if (form.kind === "negation") return `${form.hidden ? "hidden " : ""}negated spelling ${formatFlagToken(form.name, form.kind)}`;
42
44
  const aliasType = form.name.length === 1 ? "short alias" : "long alias";
43
45
  return `${form.hidden ? "hidden " : ""}${aliasType} ${formatFlagToken(form.name, form.kind)}`;
44
46
  }
45
47
  function listFlagForms(name, schema) {
46
- return [{
47
- owner: name,
48
- name,
49
- kind: "canonical",
50
- hidden: false
51
- }, ...schema.aliases.map((alias) => ({
52
- owner: name,
53
- name: alias.name,
54
- kind: "alias",
55
- hidden: alias.hidden
56
- }))];
48
+ const negatedName = getFlagNegatedName(name, schema);
49
+ return [
50
+ {
51
+ owner: name,
52
+ name,
53
+ kind: "canonical",
54
+ hidden: false
55
+ },
56
+ ...schema.aliases.map((alias) => ({
57
+ owner: name,
58
+ name: alias.name,
59
+ kind: "alias",
60
+ hidden: alias.hidden
61
+ })),
62
+ ...negatedName !== void 0 && schema.negation !== void 0 ? [{
63
+ owner: name,
64
+ name: negatedName,
65
+ kind: "negation",
66
+ hidden: schema.negation.hidden
67
+ }] : []
68
+ ];
57
69
  }
58
70
  function throwFlagCollisionError(commandName, form, existing, options) {
59
71
  const inherited = options?.inherited ?? false;
@@ -135,6 +135,38 @@ interface FlagAlias {
135
135
  /** Whether the alias is parser-only and hidden from user-facing surfaces. */
136
136
  readonly hidden: boolean;
137
137
  }
138
+ /**
139
+ * Negation settings for a boolean flag (set by `.negatable()`).
140
+ *
141
+ * The negated spelling and the positive form are two spellings of ONE
142
+ * logical flag: they share duplicate policy, and the last CLI occurrence
143
+ * wins across both. The negated spelling is presence-only — `--no-foo=x`
144
+ * is rejected.
145
+ */
146
+ interface FlagNegation {
147
+ /**
148
+ * Explicit negated spelling without the `--` prefix (e.g. `'no-sandbox'`).
149
+ * `undefined` synthesizes `no-<flagName>` wherever the flag name is known.
150
+ */
151
+ readonly alias: string | undefined;
152
+ /** Hide the negated spelling from help, completions, and suggestions. */
153
+ readonly hidden: boolean;
154
+ }
155
+ /**
156
+ * How repeated CLI occurrences of a singleton flag combine.
157
+ *
158
+ * - `'last'` — last occurrence wins (matches historic behavior)
159
+ * - `'first'` — first occurrence wins; later ones parse but are ignored
160
+ * - `'error'` — a second occurrence is a `ParseError` (`DUPLICATE_FLAG`)
161
+ *
162
+ * Applies to CLI token occurrences only — env/config/prompt/default
163
+ * resolution keeps its precedence semantics and never raises duplicates.
164
+ * Occurrences are counted per *logical* flag: aliases and the negated
165
+ * spelling all count toward the same flag.
166
+ *
167
+ * @defaultValue `'last'`
168
+ */
169
+ type DuplicatePolicy = 'last' | 'first' | 'error';
138
170
  /**
139
171
  * The runtime descriptor stored inside every {@linkcode FlagBuilder}. Consumers (parser,
140
172
  * help generator, resolution chain) read this to understand the flag's shape
@@ -227,6 +259,17 @@ interface FlagSchema {
227
259
  * @defaultValue `false`
228
260
  */
229
261
  readonly propagate: boolean;
262
+ /**
263
+ * Negation settings when `kind === 'boolean'` and `.negatable()` was
264
+ * called (`undefined` otherwise). See {@link FlagNegation}.
265
+ */
266
+ readonly negation: FlagNegation | undefined;
267
+ /**
268
+ * Duplicate policy for repeated CLI occurrences. See {@link DuplicatePolicy}.
269
+ *
270
+ * @defaultValue `'last'`
271
+ */
272
+ readonly duplicates: DuplicatePolicy;
230
273
  }
231
274
  /**
232
275
  * Low-level overrides accepted by {@link createSchema}.
@@ -262,6 +305,18 @@ declare function getFlagAliasNames(schema: FlagSchema, options?: {
262
305
  readonly includeHidden?: boolean;
263
306
  readonly kind?: 'all' | 'short' | 'long';
264
307
  }): readonly string[];
308
+ /**
309
+ * Effective negated spelling for a flag, or `undefined` when not negatable.
310
+ *
311
+ * The builder cannot know its flag name, so a default (`no-<name>`) is
312
+ * synthesized here — everywhere the canonical name is known (parser, help,
313
+ * completions, collision validation).
314
+ *
315
+ * @param name - Canonical flag name.
316
+ * @param schema - Flag schema (read for {@link FlagNegation}).
317
+ * @returns The negated spelling without the `--` prefix.
318
+ */
319
+ declare function getFlagNegatedName(name: string, schema: FlagSchema): string | undefined;
265
320
  /**
266
321
  * Create a raw {@link FlagSchema} object with sensible defaults.
267
322
  *
@@ -636,6 +691,53 @@ declare class FlagBuilder<C extends FlagConfig> {
636
691
  unique(this: FlagBuilder<C & {
637
692
  readonly flagKind: 'array';
638
693
  }>, value?: boolean): FlagBuilder<C>;
694
+ /**
695
+ * Accept a negated spelling (`--no-<name>`) that sets the flag to `false`.
696
+ *
697
+ * Both spellings are ONE logical flag: the last CLI occurrence wins across
698
+ * them, and they share the duplicate policy. The negated spelling is
699
+ * presence-only — `--no-<name>=true` is rejected. Help renders the flag as
700
+ * `--[no-]<name>` (or lists a custom alias); env/config/prompt/default
701
+ * resolution is unaffected.
702
+ *
703
+ * @param options - Optional custom spelling (`alias`, without `--`) and
704
+ * `hidden` to keep the negated spelling parseable but unadvertised.
705
+ * @returns The builder (for chaining).
706
+ *
707
+ * @example
708
+ * ```ts
709
+ * flag.boolean().default(true).negatable()
710
+ * // $ mycli build --no-sandbox → sandbox = false
711
+ * // $ mycli build --sandbox → sandbox = true
712
+ * ```
713
+ */
714
+ negatable(this: FlagBuilder<C & {
715
+ readonly flagKind: 'boolean';
716
+ }>, options?: {
717
+ alias?: string;
718
+ hidden?: boolean;
719
+ }): FlagBuilder<C>;
720
+ /**
721
+ * Set how repeated CLI occurrences of this flag combine.
722
+ *
723
+ * Counted per logical flag — aliases and the negated spelling all count
724
+ * toward the same flag. CLI tokens only: env/config/prompt/default
725
+ * resolution keeps its precedence semantics. Not available on `array`,
726
+ * `count`, or `keyValue` flags, which inherently accumulate.
727
+ *
728
+ * @param policy - `'last'` (default), `'first'`, or `'error'`.
729
+ * @returns The builder (for chaining).
730
+ *
731
+ * @example
732
+ * ```ts
733
+ * flag.enum(['session', 'same-dir', 'worktree']).duplicates('error')
734
+ * // $ mycli run --spawn session --spawn worktree
735
+ * // # → Error: Flag --spawn may only be specified once
736
+ * ```
737
+ */
738
+ duplicates(this: FlagBuilder<C & {
739
+ readonly flagKind: 'boolean' | 'string' | 'number' | 'enum' | 'custom';
740
+ }>, policy: DuplicatePolicy): FlagBuilder<C>;
639
741
  }
640
742
  /**
641
743
  * Factory that creates {@link FlagBuilder} instances seeded with the correct
@@ -935,4 +1037,4 @@ interface FlagFactory {
935
1037
  */
936
1038
  declare const flag: FlagFactory;
937
1039
  //#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 };
1040
+ 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";
@@ -32,4 +33,4 @@ import { ConfigAdapter, ConfigDiscoveryOptions, ConfigDiscoveryResult, ConfigFou
32
33
  import { CLIBuilder, CLIOptions, CLIRunOptions, CLISchema, ConfigSettings, DefaultCommandOptions, InferNameOption, ManifestPresetSettings, ManifestSettings, PackageJsonSettings, ResolvedManifestSettings, cli } from "./core/cli/index.mjs";
33
34
  import { JsonSchemaOptions, definitionMetaSchema, 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, 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";
@@ -19,4 +19,4 @@ import { plugin } from "./core/cli/plugin.mjs";
19
19
  import { buildConfigSearchPaths, configFormat, discoverConfig } from "./core/config/index.mjs";
20
20
  import { CLIBuilder, cli } from "./core/cli/index.mjs";
21
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, 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.8";
4
4
  /** Git short SHA (e.g. `"f9b5f1a"`). `"dev"` when running unbundled. */
5
- const DREAMCLI_REVISION = "e87f393";
5
+ const DREAMCLI_REVISION = "e934880";
6
6
  //#endregion
7
7
  export { DREAMCLI_REVISION, DREAMCLI_VERSION };
@@ -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.8",
4
4
  "description": "Schema-first, fully typed TypeScript CLI framework",
5
5
  "keywords": [
6
6
  "dreamcli",