@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
package/CHANGELOG.md CHANGED
@@ -7,6 +7,50 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [3.0.0-rc.8] - 2026-07-11
11
+
12
+ ### Added
13
+
14
+ - **Themed help output** — root and per-command help render with a semantic
15
+ color theme (bold+underlined section titles, cyan literals, dimmed metadata,
16
+ yellow deprecations) whenever color is enabled, using the same gate as
17
+ `out.color` (TTY + color support, no `--json`, `NO_COLOR`/`FORCE_COLOR`
18
+ honored). Piped and JSON output stays byte-clean. Customize via
19
+ `.help({ theme: (c) => ({ sectionTitle: c.magenta }) })` — the factory
20
+ receives the gated ansispeck palette and is never invoked when color is off,
21
+ so custom themes cannot leak escapes. New public types: `HelpTheme`,
22
+ `HelpThemeFactory`.
23
+ - **Negatable booleans** — `flag.boolean().negatable()` accepts `--no-<name>`
24
+ as `false`. Both spellings are one logical flag (last CLI occurrence wins,
25
+ shared duplicate policy); the negated spelling is presence-only
26
+ (`--no-foo=x` errors) and renders as `--[no-]foo` in help. Custom spelling
27
+ via `{ alias }`, unadvertised via `{ hidden }`. Env/config/prompt/default
28
+ resolution is unchanged.
29
+ - **Duplicate policy** — `.duplicates('last' | 'first' | 'error')` on
30
+ singleton flags controls repeated CLI occurrences. `'error'` throws
31
+ `ParseError` code `DUPLICATE_FLAG` with `{ flag, count, values }` details;
32
+ `'first'` keeps the first value while still consuming later value tokens.
33
+ Counted per logical flag (aliases + negated + parity spellings); env/config
34
+ precedence is never a duplicate.
35
+ - **`packageRepositoryUrl(pkg, { require: true })`** — narrows the return
36
+ type to `string`, throwing a `CLIError` (code `INVALID_REPOSITORY`) at the
37
+ call site when the `repository` field is missing or not a recognisable
38
+ locator. Removes the `!` assertion for manifests known to carry a valid
39
+ repository, with the guarantee enforced at runtime rather than assumed.
40
+ - **Flag spelling parity (kebab ↔ camel)** — `--doThis` matches a flag named
41
+ `do-this` and vice versa, for names and long aliases, on by default.
42
+ Handler keys, help, completions, and suggestions stay canonical.
43
+ Automatically disabled per pair when both spellings are declared explicitly;
44
+ globally via `cli('mycli', { flags: { caseParity: false } })` (new
45
+ `cli(name, options)` overload) or `RunOptions.flags`.
46
+
47
+ ### Fixed
48
+
49
+ - `execute(argv, { flags })` overrides now reach the planner's dispatch arity
50
+ scanning, not just command parsing.
51
+ - Generated meta-schema descriptions render `@defaultValue` tags as a
52
+ `Default: <value>` paragraph instead of silently dropping them.
53
+
10
54
  ## [3.0.0-rc.7] - 2026-07-10
11
55
 
12
56
  ### Added
@@ -1130,7 +1174,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
1130
1174
  - MIT License.
1131
1175
  - Markdownlint configuration.
1132
1176
 
1133
- [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.7...HEAD
1177
+ [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.8...HEAD
1178
+ [3.0.0-rc.8]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.7...v3.0.0-rc.8
1134
1179
  [3.0.0-rc.7]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.6...v3.0.0-rc.7
1135
1180
  [3.0.0-rc.6]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.5...v3.0.0-rc.6
1136
1181
  [3.0.0-rc.5]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.4...v3.0.0-rc.5
@@ -1,14 +1,14 @@
1
- import { FlagSchema } from "../schema/flag.mjs";
2
1
  import { CommandSchema, ErasedCommand } from "../schema/command.mjs";
2
+ import { FlagLookupEntry, ParseOptions } from "../parse/index.mjs";
3
3
  //#region src/core/cli/dispatch.d.ts
4
4
  /**
5
- * Flag lookup (name/alias → `[canonicalName, schema]`) used to make the
5
+ * Flag lookup (spelling → {@link FlagLookupEntry}) used to make the
6
6
  * command-name scan aware of value-flag arity. Built from the flags valid at
7
7
  * the current dispatch level via {@link buildFlagLookup}.
8
8
  *
9
9
  * @internal
10
10
  */
11
- type ValueFlagLookup = ReadonlyMap<string, readonly [name: string, schema: FlagSchema]>;
11
+ type ValueFlagLookup = ReadonlyMap<string, FlagLookupEntry>;
12
12
  /** Successful dispatch — target command found with argv path. */
13
13
  interface DispatchMatch {
14
14
  /** Discriminant — a command name in argv matched a registered command. */
@@ -64,11 +64,13 @@ type DispatchResult = DispatchMatch | DispatchNeedsSubcommand | DispatchUnknown;
64
64
  * @param valueFlags - Lookup of flags valid at this level, used so a
65
65
  * space-separated value-flag's value (`--region eu`) is not mistaken for a
66
66
  * command name. Empty by default (arity-unaware, legacy behaviour).
67
+ * @param parseOptions - Parser toggles (case parity) applied to descent-level
68
+ * flag lookups built inside dispatch.
67
69
  * @returns Discriminated dispatch result.
68
70
  *
69
71
  * @internal
70
72
  */
71
- declare function dispatch(argv: readonly string[], commands: ReadonlyMap<string, ErasedCommand>, ancestorPath?: readonly CommandSchema[], valueFlags?: ValueFlagLookup): DispatchResult;
73
+ declare function dispatch(argv: readonly string[], commands: ReadonlyMap<string, ErasedCommand>, ancestorPath?: readonly CommandSchema[], valueFlags?: ValueFlagLookup, parseOptions?: ParseOptions): DispatchResult;
72
74
  /**
73
75
  * Whether a flag token consumes the following argv token as its value.
74
76
  *
@@ -33,11 +33,13 @@ import { buildFlagLookup, flagExpectsValue } from "../parse/index.mjs";
33
33
  * @param valueFlags - Lookup of flags valid at this level, used so a
34
34
  * space-separated value-flag's value (`--region eu`) is not mistaken for a
35
35
  * command name. Empty by default (arity-unaware, legacy behaviour).
36
+ * @param parseOptions - Parser toggles (case parity) applied to descent-level
37
+ * flag lookups built inside dispatch.
36
38
  * @returns Discriminated dispatch result.
37
39
  *
38
40
  * @internal
39
41
  */
40
- function dispatch(argv, commands, ancestorPath = [], valueFlags = /* @__PURE__ */ new Map()) {
42
+ function dispatch(argv, commands, ancestorPath = [], valueFlags = /* @__PURE__ */ new Map(), parseOptions) {
41
43
  let cmdIdx = -1;
42
44
  for (let i = 0; i < argv.length; i++) {
43
45
  const token = argv[i];
@@ -76,7 +78,7 @@ function dispatch(argv, commands, ancestorPath = [], valueFlags = /* @__PURE__ *
76
78
  const remaining = [...argv.slice(0, cmdIdx), ...argv.slice(cmdIdx + 1)];
77
79
  const currentPath = [...ancestorPath, matched.schema];
78
80
  if (matched.subcommands.size > 0) {
79
- const subResult = dispatch(remaining, matched.subcommands, currentPath, buildFlagLookup(matched.schema.flags));
81
+ const subResult = dispatch(remaining, matched.subcommands, currentPath, buildFlagLookup(matched.schema.flags, parseOptions), parseOptions);
80
82
  switch (subResult.kind) {
81
83
  case "match": return subResult;
82
84
  case "unknown":
@@ -130,13 +132,13 @@ function consumesFollowingToken(token, valueFlags) {
130
132
  if (token.startsWith("--")) {
131
133
  if (token.includes("=")) return false;
132
134
  const entry = valueFlags.get(token.slice(2));
133
- return entry !== void 0 && flagExpectsValue(entry[1]);
135
+ return entry !== void 0 && flagExpectsValue(entry.schema);
134
136
  }
135
137
  const chars = token.slice(1);
136
138
  for (let i = 0; i < chars.length; i++) {
137
139
  const entry = valueFlags.get(chars.charAt(i));
138
140
  if (entry === void 0) return false;
139
- if (!flagExpectsValue(entry[1])) continue;
141
+ if (!flagExpectsValue(entry.schema)) continue;
140
142
  return i === chars.length - 1;
141
143
  }
142
144
  return false;
@@ -1,8 +1,11 @@
1
1
  import { ArgBuilder, ArgConfig } from "../schema/arg.mjs";
2
2
  import { FlagBuilder, FlagConfig } from "../schema/flag.mjs";
3
3
  import { BeforeParseParams, CLIPlugin, CLIPluginHooks, PluginCommandContext, ResolvedCommandParams, plugin } from "./plugin.mjs";
4
+ import { HelpThemeFactory } from "../help/theme.mjs";
5
+ import "../help/index.mjs";
4
6
  import { RunOptions, RunResult } from "../schema/run.mjs";
5
7
  import { CommandBuilder, ErasedCommand } from "../schema/command.mjs";
8
+ import { ParseOptions } from "../parse/index.mjs";
6
9
  import { RuntimeAdapter } from "../../runtime/adapter.mjs";
7
10
  import { PackageJsonData } from "../config/package-json.mjs";
8
11
  import { HelpLinks } from "./help-links.mjs";
@@ -96,6 +99,12 @@ interface CLISchema {
96
99
  * under runtime `options.help` (runtime wins) before rendering.
97
100
  */
98
101
  readonly helpConfig: HelpConfig | undefined;
102
+ /**
103
+ * Flag-parsing behavior settings ({@link ParseOptions}).
104
+ *
105
+ * Set via the `cli(name, { flags })` / `cli({ flags })` factory forms.
106
+ */
107
+ readonly flagSettings: ParseOptions | undefined;
99
108
  /** Registered CLI plugins. */
100
109
  readonly plugins: readonly CLIPlugin[];
101
110
  }
@@ -144,6 +153,17 @@ interface HelpConfig {
144
153
  readonly width?: number;
145
154
  /** Emit OSC 8 hyperlinks in the header when supported. */
146
155
  readonly hyperlinks?: boolean;
156
+ /**
157
+ * Theme overrides for help output, merged over the built-in theme.
158
+ *
159
+ * The factory receives the gated ansispeck palette (same instance as
160
+ * `out.color`), so overrides follow the output channel's color policy.
161
+ * It is never invoked when color is off — themed help cannot leak escapes
162
+ * into piped, `--json`, or `NO_COLOR` output.
163
+ *
164
+ * @defaultValue `undefined` (built-in theme)
165
+ */
166
+ readonly theme?: HelpThemeFactory;
147
167
  }
148
168
  /**
149
169
  * Config discovery settings for automatic config file loading.
@@ -753,6 +773,12 @@ interface CLIOptions {
753
773
  * @defaultValue `false`
754
774
  */
755
775
  readonly inherit?: boolean;
776
+ /**
777
+ * Flag-parsing behavior settings (e.g. `{ caseParity: false }` to accept
778
+ * only declared flag spellings). Shares the {@link ParseOptions} contract
779
+ * used by `parse()` and `RunOptions.flags`.
780
+ */
781
+ readonly flags?: ParseOptions;
756
782
  }
757
783
  /**
758
784
  * Create a new CLI program builder.
@@ -773,7 +799,7 @@ interface CLIOptions {
773
799
  * .run();
774
800
  * ```
775
801
  */
776
- declare function cli(name: string): CLIBuilder;
802
+ declare function cli(name: string, options?: Omit<CLIOptions, 'name'>): CLIBuilder;
777
803
  /** Create a new CLI program builder from an options object. */
778
804
  declare function cli(options: CLIOptions): CLIBuilder;
779
805
  //#endregion
@@ -124,7 +124,8 @@ function buildCommandRunOptions(options, helpOptions, meta) {
124
124
  ...options?.jsonMode !== void 0 ? { jsonMode: options.jsonMode } : {},
125
125
  ...options?.isTTY !== void 0 ? { isTTY: options.isTTY } : {},
126
126
  ...options?.out !== void 0 ? { out: options.out } : {},
127
- ...options?.captured !== void 0 ? { captured: options.captured } : {}
127
+ ...options?.captured !== void 0 ? { captured: options.captured } : {},
128
+ ...options?.flags !== void 0 ? { flags: options.flags } : {}
128
129
  };
129
130
  }
130
131
  /**
@@ -553,12 +554,15 @@ var CLIBuilder = class CLIBuilder {
553
554
  ...this.schema.helpConfig,
554
555
  ...options?.help,
555
556
  binName: options?.help?.binName ?? this.schema.name,
556
- hyperlinks: options?.help?.hyperlinks ?? this.schema.helpConfig?.hyperlinks ?? out.isTTY
557
+ hyperlinks: options?.help?.hyperlinks ?? this.schema.helpConfig?.hyperlinks ?? out.isTTY,
558
+ colors: options?.help?.colors ?? out.color
557
559
  };
560
+ const flagSettings = options?.flags ?? this.schema.flagSettings;
558
561
  const effectiveOptions = {
559
562
  ...options,
560
563
  plugins: this.schema.plugins,
561
- ...jsonMode ? { jsonMode } : {}
564
+ ...jsonMode ? { jsonMode } : {},
565
+ ...flagSettings !== void 0 ? { flags: flagSettings } : {}
562
566
  };
563
567
  const output = {
564
568
  jsonMode,
@@ -566,7 +570,10 @@ var CLIBuilder = class CLIBuilder {
566
570
  verbosity: options?.verbosity ?? "normal"
567
571
  };
568
572
  const planned = planInvocation({
569
- schema: this.schema,
573
+ schema: options?.flags !== void 0 ? {
574
+ ...this.schema,
575
+ flagSettings
576
+ } : this.schema,
570
577
  argv,
571
578
  help: helpOptions,
572
579
  output
@@ -906,10 +913,14 @@ function isPackageJsonData(value) {
906
913
  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
907
914
  return "name" in value || "version" in value || "description" in value || "bin" in value || "homepage" in value || "repository" in value;
908
915
  }
909
- function cli(nameOrOptions) {
916
+ function cli(nameOrOptions, extraOptions) {
917
+ const options = typeof nameOrOptions === "string" ? {
918
+ name: nameOrOptions,
919
+ ...extraOptions
920
+ } : nameOrOptions;
910
921
  return new CLIBuilder({
911
- name: typeof nameOrOptions === "string" ? nameOrOptions : nameOrOptions.name ?? "cli",
912
- inheritName: typeof nameOrOptions === "string" ? false : nameOrOptions.inherit ?? false,
922
+ name: options.name ?? "cli",
923
+ inheritName: options.inherit ?? false,
913
924
  version: void 0,
914
925
  description: void 0,
915
926
  commands: [],
@@ -921,6 +932,7 @@ function cli(nameOrOptions) {
921
932
  hasBuiltInCompletions: false,
922
933
  completionsFlag: void 0,
923
934
  helpConfig: void 0,
935
+ flagSettings: options.flags,
924
936
  plugins: []
925
937
  });
926
938
  }
@@ -3,6 +3,7 @@ import { CLIPlugin } from "./plugin.mjs";
3
3
  import { CLIError } from "../errors/index.mjs";
4
4
  import { HelpOptions } from "../help/index.mjs";
5
5
  import { CommandMeta, CommandSchema, ErasedCommand } from "../schema/command.mjs";
6
+ import { ParseOptions } from "../parse/index.mjs";
6
7
  import { CompletionOptions } from "../completion/shells/shared.mjs";
7
8
  import { Shell } from "../completion/index.mjs";
8
9
  //#region src/core/cli/planner.d.ts
@@ -32,6 +33,8 @@ interface PlannerSchemaLike {
32
33
  readonly shells: readonly Shell[];
33
34
  readonly options: CompletionOptions | undefined;
34
35
  } | undefined;
36
+ /** Flag-parsing behavior settings (case parity) applied to flag lookups. */
37
+ readonly flagSettings?: ParseOptions | undefined;
35
38
  /** Plugins forwarded into every matched execution plan. */
36
39
  readonly plugins: readonly CLIPlugin[];
37
40
  }
@@ -75,8 +75,8 @@ function buildPlannerMatchOutcome(schema, command, commandPath, argv, help, outp
75
75
  function canDelegateUnknownRootToDefault(command, input) {
76
76
  return input === "" || command.schema.args.length > 0;
77
77
  }
78
- function findUnknownFlagBeforePositional(argv, flags) {
79
- const lookup = buildFlagLookup(flags);
78
+ function findUnknownFlagBeforePositional(argv, flags, parseOptions) {
79
+ const lookup = buildFlagLookup(flags, parseOptions);
80
80
  for (let index = 0; index < argv.length; index++) {
81
81
  const token = argv[index];
82
82
  if (token === void 0 || token === "--") return void 0;
@@ -86,7 +86,7 @@ function findUnknownFlagBeforePositional(argv, flags) {
86
86
  const name = token.slice(2, equalsIndex === -1 ? void 0 : equalsIndex);
87
87
  const entry = lookup.get(name);
88
88
  if (entry === void 0) return equalsIndex === -1 ? token : `--${name}`;
89
- if (equalsIndex === -1 && flagExpectsValue(entry[1])) index++;
89
+ if (equalsIndex === -1 && flagExpectsValue(entry.schema)) index++;
90
90
  continue;
91
91
  }
92
92
  const chars = token.slice(1);
@@ -94,7 +94,7 @@ function findUnknownFlagBeforePositional(argv, flags) {
94
94
  const char = chars.charAt(charIndex);
95
95
  const entry = lookup.get(char);
96
96
  if (entry === void 0) return `-${char}`;
97
- if (!flagExpectsValue(entry[1])) continue;
97
+ if (!flagExpectsValue(entry.schema)) continue;
98
98
  if (charIndex === chars.length - 1) index++;
99
99
  break;
100
100
  }
@@ -128,13 +128,13 @@ function scanRootHead(head, valueFlags) {
128
128
  const equalsIndex = token.indexOf("=");
129
129
  const name = token.slice(2, equalsIndex === -1 ? void 0 : equalsIndex);
130
130
  const entry = valueFlags?.get(name);
131
- if (entry !== void 0 && equalsIndex === -1 && flagExpectsValue(entry[1])) index++;
131
+ if (entry !== void 0 && equalsIndex === -1 && flagExpectsValue(entry.schema)) index++;
132
132
  continue;
133
133
  }
134
134
  const chars = token.slice(1);
135
135
  for (let charIndex = 0; charIndex < chars.length; charIndex++) {
136
136
  const entry = valueFlags?.get(chars.charAt(charIndex));
137
- if (entry === void 0 || !flagExpectsValue(entry[1])) continue;
137
+ if (entry === void 0 || !flagExpectsValue(entry.schema)) continue;
138
138
  if (charIndex === chars.length - 1) index++;
139
139
  break;
140
140
  }
@@ -205,7 +205,7 @@ function planInvocation(options) {
205
205
  const filteredHead = head.includes("--json") ? head.filter((arg) => arg !== "--json") : head;
206
206
  const filteredArgv = separatorIndex === -1 ? filteredHead : [...filteredHead, ...tail];
207
207
  const defaultCommand = options.schema.defaultCommand;
208
- const rootValueFlags = defaultCommand !== void 0 ? buildFlagLookup(defaultCommand.schema.flags) : void 0;
208
+ const rootValueFlags = defaultCommand !== void 0 ? buildFlagLookup(defaultCommand.schema.flags, options.schema.flagSettings) : void 0;
209
209
  if (options.schema.version !== void 0 && (includesBeforeSeparator(options.argv, "--version") || includesBeforeSeparator(options.argv, "-V"))) return {
210
210
  kind: "root-version",
211
211
  version: options.schema.version
@@ -243,12 +243,12 @@ function planInvocation(options) {
243
243
  kind: "root-help",
244
244
  help: options.help
245
245
  };
246
- const result = dispatch(filteredArgv, buildRootCommandMap(defaultCommand !== void 0 && options.schema.defaultCommandRouted ? [...options.schema.commands, defaultCommand] : options.schema.commands), [], rootValueFlags);
246
+ const result = dispatch(filteredArgv, buildRootCommandMap(defaultCommand !== void 0 && options.schema.defaultCommandRouted ? [...options.schema.commands, defaultCommand] : options.schema.commands), [], rootValueFlags, options.schema.flagSettings);
247
247
  switch (result.kind) {
248
248
  case "unknown": {
249
249
  if (defaultCommand !== void 0 && result.parentPath.length === 0) {
250
250
  if ((result.input !== "" ? findClosestCommand(result.input, result.candidates) : void 0) === void 0 && canDelegateUnknownRootToDefault(defaultCommand, result.input)) return buildPlannerMatchOutcome(options.schema, defaultCommand, [defaultCommand.schema], filteredArgv, options.help, options.output);
251
- const unknownFlag = findUnknownFlagBeforePositional(filteredArgv, defaultCommand.schema.flags);
251
+ const unknownFlag = findUnknownFlagBeforePositional(filteredArgv, defaultCommand.schema.flags, options.schema.flagSettings);
252
252
  if (unknownFlag !== void 0) return {
253
253
  kind: "dispatch-error",
254
254
  error: new ParseError(`Unknown flag ${unknownFlag}`, {
@@ -1,6 +1,6 @@
1
1
  import { FlagSchema } from "../schema/flag.mjs";
2
- import "../schema/index.mjs";
3
2
  import { CommandSchema } from "../schema/command.mjs";
3
+ import "../schema/index.mjs";
4
4
  //#region src/core/cli/propagate.d.ts
5
5
  /**
6
6
  * Collect propagated flags from a command path.
@@ -1,6 +1,7 @@
1
1
  import { command } from "../schema/command.mjs";
2
2
  import { resolveRootSurface } from "./root-surface.mjs";
3
3
  import { osc8, padEnd, wrapText } from "../help/ansi.mjs";
4
+ import { resolveHelpTheme } from "../help/theme.mjs";
4
5
  import { formatFlagEntriesBlock, formatHelpSections } from "../help/index.mjs";
5
6
  //#region src/core/cli/root-help.ts
6
7
  /**
@@ -30,16 +31,18 @@ function formatRootHelp(schema, options) {
30
31
  const hyperlinks = options?.hyperlinks === true;
31
32
  const inlineDefault = options?.inlineDefault ?? true;
32
33
  const showDefaultInCommands = options?.showDefaultInCommands ?? false;
34
+ const theme = resolveHelpTheme(options?.colors, options?.theme);
33
35
  const surface = resolveRootSurface(schema);
34
36
  const defaultCommand = surface.visibleDefaultCommand;
35
37
  const defaultIsSoleSurface = !surface.hasVisibleSubcommands && schema.completionsFlag === void 0;
36
38
  const inlineDefaultCommand = inlineDefault || defaultIsSoleSurface ? defaultCommand : void 0;
37
39
  const surfaceCommand = resolveSurfaceCommand(schema, inlineDefaultCommand);
38
40
  const inline = surfaceCommand !== void 0;
39
- const sections = [formatHeader(schema, hyperlinks)];
41
+ const sections = [formatHeader(schema, hyperlinks, theme)];
40
42
  if (schema.description !== void 0) sections.push(schema.description);
41
43
  const placeholder = surface.hasVisibleSubcommands ? defaultCommand !== void 0 ? "[command]" : "<command>" : "";
42
- const rootUsage = placeholder.length > 0 ? `Usage: ${binName} ${placeholder} [options]` : `Usage: ${binName} [options]`;
44
+ const usageTitle = theme.sectionTitle("Usage:");
45
+ const rootUsage = placeholder.length > 0 ? `${usageTitle} ${theme.usageBin(binName)} ${theme.placeholder(placeholder)} ${theme.placeholder("[options]")}` : `${usageTitle} ${theme.usageBin(binName)} ${theme.placeholder("[options]")}`;
43
46
  let surfaceSections = [];
44
47
  if (inline && surfaceCommand !== void 0) surfaceSections = [...formatHelpSections(surfaceCommand, {
45
48
  ...options,
@@ -47,16 +50,16 @@ function formatRootHelp(schema, options) {
47
50
  isDefaultHelp: true
48
51
  })];
49
52
  const surfaceUsage = surfaceSections.shift();
50
- if (inline && surfaceUsage !== void 0 && inlineDefaultCommand !== void 0) sections.push(surface.hasVisibleSubcommands ? mergeUsageSections(rootUsage, surfaceUsage) : surfaceUsage);
53
+ if (inline && surfaceUsage !== void 0 && inlineDefaultCommand !== void 0) sections.push(surface.hasVisibleSubcommands ? mergeUsageSections(rootUsage, surfaceUsage, usageTitle) : surfaceUsage);
51
54
  else sections.push(rootUsage);
52
55
  const listDefaultInCommands = defaultCommand !== void 0 && (surface.defaultRouted || showDefaultInCommands);
53
56
  const listedCommands = listDefaultInCommands ? [...surface.visibleSubcommands, defaultCommand] : surface.visibleSubcommands;
54
- if (listedCommands.length > 0) sections.push(formatRootCommandsSection(listedCommands, listDefaultInCommands ? defaultCommand?.name : void 0, width));
57
+ if (listedCommands.length > 0) sections.push(formatRootCommandsSection(listedCommands, listDefaultInCommands ? defaultCommand?.name : void 0, width, theme));
55
58
  if (inline && surfaceCommand !== void 0) {
56
59
  if (surfaceCommand.description !== void 0 && surfaceCommand.description === schema.description && surfaceSections[0] === surfaceCommand.description) surfaceSections.shift();
57
60
  sections.push(...surfaceSections);
58
61
  }
59
- const globalOptions = formatGlobalOptionsSection(schema, width);
62
+ const globalOptions = formatGlobalOptionsSection(schema, width, theme);
60
63
  if (globalOptions.length > 0) sections.push(globalOptions);
61
64
  if (options?.footer ?? surface.hasVisibleSubcommands) {
62
65
  const footerPlaceholder = surface.hasVisibleSubcommands ? defaultCommand !== void 0 ? " [command]" : " <command>" : "";
@@ -114,7 +117,9 @@ function completionsFlagSchema(shells) {
114
117
  prompt: void 0,
115
118
  parseFn: void 0,
116
119
  deprecated: void 0,
117
- propagate: false
120
+ propagate: false,
121
+ negation: void 0,
122
+ duplicates: "last"
118
123
  };
119
124
  }
120
125
  /**
@@ -128,14 +133,16 @@ function completionsFlagSchema(shells) {
128
133
  *
129
134
  * @param schema - The CLI schema.
130
135
  * @param hyperlinks - Whether OSC 8 hyperlinks may be emitted.
136
+ * @param theme - Theme applied to the name and version (inside any hyperlink).
131
137
  * @returns The header line.
132
138
  * @internal
133
139
  */
134
- function formatHeader(schema, hyperlinks) {
140
+ function formatHeader(schema, hyperlinks, theme) {
135
141
  const links = hyperlinks ? schema.helpLinks : void 0;
136
- const name = links?.name !== void 0 ? osc8(links.name, schema.name) : schema.name;
142
+ const styledName = theme.headerName(schema.name);
143
+ const name = links?.name !== void 0 ? osc8(links.name, styledName) : styledName;
137
144
  if (schema.version === void 0) return name;
138
- const version = `v${schema.version}`;
145
+ const version = theme.headerVersion(`v${schema.version}`);
139
146
  return `${name} ${links?.version !== void 0 ? osc8(links.version, version) : version}`;
140
147
  }
141
148
  /**
@@ -144,11 +151,12 @@ function formatHeader(schema, hyperlinks) {
144
151
  * @param visibleCommands - Non-hidden top-level commands.
145
152
  * @param defaultName - Name of the default command (appends " (default)" tag).
146
153
  * @param width - Terminal width for description wrapping.
154
+ * @param theme - Theme applied to the title, command names, and default tag.
147
155
  * @returns Formatted commands block.
148
156
  * @internal
149
157
  */
150
- function formatRootCommandsSection(visibleCommands, defaultName, width) {
151
- const lines = ["Commands:"];
158
+ function formatRootCommandsSection(visibleCommands, defaultName, width, theme) {
159
+ const lines = [theme.sectionTitle("Commands:")];
152
160
  const GAP = 2;
153
161
  const DEFAULT_TAG = " (default)";
154
162
  let maxNameLen = 0;
@@ -159,7 +167,7 @@ function formatRootCommandsSection(visibleCommands, defaultName, width) {
159
167
  }
160
168
  const descCol = 2 + maxNameLen + GAP;
161
169
  for (const cmd of visibleCommands) {
162
- const padded = padEnd(` ${cmd.name === defaultName ? `${cmd.name}${DEFAULT_TAG}` : cmd.name}`, descCol);
170
+ const padded = padEnd(` ${cmd.name === defaultName ? `${theme.command(cmd.name)}${theme.annotation(DEFAULT_TAG)}` : theme.command(cmd.name)}`, descCol);
163
171
  const desc = cmd.description ?? "";
164
172
  if (desc.length === 0) lines.push(padded.trimEnd());
165
173
  else lines.push(`${padded}${wrapText(desc, width, descCol)}`);
@@ -176,38 +184,42 @@ function formatRootCommandsSection(visibleCommands, defaultName, width) {
176
184
  *
177
185
  * @param schema - The CLI schema (read for `version` and `configSettings`).
178
186
  * @param width - Terminal width for description wrapping.
187
+ * @param theme - Theme applied to the title and flag forms.
179
188
  * @returns Formatted `Global options:` block (always non-empty).
180
189
  * @internal
181
190
  */
182
- function formatGlobalOptionsSection(schema, width) {
191
+ function formatGlobalOptionsSection(schema, width, theme) {
183
192
  const entries = [{
184
- left: "-h, --help",
193
+ left: theme.flag("-h, --help"),
185
194
  description: "Show this help message and exit"
186
195
  }];
187
196
  if (schema.version !== void 0) entries.push({
188
- left: "-V, --version",
197
+ left: theme.flag("-V, --version"),
189
198
  description: "Print the version number and exit"
190
199
  });
191
200
  entries.push({
192
- left: "--json",
201
+ left: theme.flag("--json"),
193
202
  description: "Emit machine-readable JSON output"
194
203
  });
195
204
  if (schema.configSettings !== void 0) entries.push({
196
- left: "--config <path>",
205
+ left: `${theme.flag("--config")} ${theme.placeholder("<path>")}`,
197
206
  description: "Load configuration from the given file"
198
207
  });
199
- return formatFlagEntriesBlock("Global options:", entries, width);
208
+ return formatFlagEntriesBlock(theme.sectionTitle("Global options:"), entries, width);
200
209
  }
201
210
  /**
202
211
  * Merge root and default-command usage lines into a single block.
203
212
  *
204
213
  * @param rootUsage - The root usage line (e.g. `Usage: mycli [command] [options]`).
205
214
  * @param commandUsage - The default command's usage line.
215
+ * @param usageTitle - The themed `Usage:` title — byte-identical in both lines
216
+ * within one render, so the styled prefix strips cleanly.
206
217
  * @returns Combined usage block with aligned continuation.
207
218
  * @internal
208
219
  */
209
- function mergeUsageSections(rootUsage, commandUsage) {
210
- const commandSuffix = commandUsage.startsWith("Usage: ") ? commandUsage.slice(7) : commandUsage;
220
+ function mergeUsageSections(rootUsage, commandUsage, usageTitle) {
221
+ const usagePrefix = `${usageTitle} `;
222
+ const commandSuffix = commandUsage.startsWith(usagePrefix) ? commandUsage.slice(usagePrefix.length) : commandUsage;
211
223
  return `${rootUsage}\n${" ".repeat(7)}${commandSuffix}`;
212
224
  }
213
225
  //#endregion
@@ -3,7 +3,10 @@ import "../output/index.mjs";
3
3
  import { PromptEngine } from "../prompt/index.mjs";
4
4
  import { CLIPlugin } from "./plugin.mjs";
5
5
  import { CLIError } from "../errors/index.mjs";
6
+ import { HelpThemeFactory } from "../help/theme.mjs";
7
+ import "../help/index.mjs";
6
8
  import { CommandSchema, ErasedCommand } from "../schema/command.mjs";
9
+ import { ParseOptions } from "../parse/index.mjs";
7
10
  import { RuntimeAdapter } from "../../runtime/adapter.mjs";
8
11
  import { PackageJsonData } from "../config/package-json.mjs";
9
12
  import { HelpLinks } from "./help-links.mjs";
@@ -80,7 +83,10 @@ interface RuntimePreflightSchemaLike {
80
83
  readonly footer?: boolean;
81
84
  readonly width?: number;
82
85
  readonly hyperlinks?: boolean;
86
+ readonly theme?: HelpThemeFactory;
83
87
  } | undefined;
88
+ /** Flag-parsing behavior settings (e.g. case parity). */
89
+ readonly flagSettings: ParseOptions | undefined;
84
90
  /** Plugins forwarded into the execution pipeline. */
85
91
  readonly plugins: readonly CLIPlugin[];
86
92
  }
@@ -173,7 +179,7 @@ declare function extractConfigFlag(argv: readonly string[]): {
173
179
  readonly filteredArgv: readonly string[];
174
180
  };
175
181
  /** Check whether a single command's args declare stdin-mode and argv leaves them unresolved. @internal */
176
- declare function commandInvocationNeedsStdin(schema: CommandSchema, argv: readonly string[]): boolean;
182
+ declare function commandInvocationNeedsStdin(schema: CommandSchema, argv: readonly string[], flagSettings?: ParseOptions): boolean;
177
183
  /** Plan the invocation and check whether the matched command needs stdin data. @internal */
178
184
  declare function invocationNeedsStdin(schema: RuntimePreflightSchemaLike, argv: readonly string[]): boolean;
179
185
  /**
@@ -49,10 +49,10 @@ function extractConfigFlag(argv) {
49
49
  };
50
50
  }
51
51
  /** Check whether a single command's args declare stdin-mode and argv leaves them unresolved. @internal */
52
- function commandInvocationNeedsStdin(schema, argv) {
52
+ function commandInvocationNeedsStdin(schema, argv, flagSettings) {
53
53
  if (argv.includes("--help") || argv.includes("-h")) return false;
54
54
  try {
55
- const parsed = parse(schema, argv);
55
+ const parsed = parse(schema, argv, flagSettings);
56
56
  return schema.args.some(({ name, schema: argSchema }) => {
57
57
  const parsedValue = parsed.args[name];
58
58
  return argSchema.stdinMode && (parsedValue === void 0 || parsedValue === "-");
@@ -71,7 +71,7 @@ function invocationNeedsStdin(schema, argv) {
71
71
  output: PRECHECK_OUTPUT
72
72
  });
73
73
  switch (plan.kind) {
74
- case "match": return commandInvocationNeedsStdin(plan.plan.mergedSchema, plan.plan.argv);
74
+ case "match": return commandInvocationNeedsStdin(plan.plan.mergedSchema, plan.plan.argv, schema.flagSettings);
75
75
  case "dispatch-error":
76
76
  case "needs-subcommand":
77
77
  case "root-help":
@@ -1,6 +1,6 @@
1
1
  import { getFlagAliasNames } from "../../schema/flag.mjs";
2
2
  import { flagExpectsValue } from "../../parse/index.mjs";
3
- import { quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
3
+ import { getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
4
4
  //#region src/core/completion/shells/bash.ts
5
5
  /**
6
6
  * Generate a bash completion script for the CLI.
@@ -242,7 +242,8 @@ function escapeBashDollarQuote(value) {
242
242
  return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n");
243
243
  }
244
244
  /**
245
- * Collect all `--flag` words (long + short aliases) for a flag record.
245
+ * Collect all `--flag` words (long + short aliases + visible negated
246
+ * spellings) for a flag record.
246
247
  *
247
248
  * @internal
248
249
  */
@@ -251,6 +252,8 @@ function collectFlagWords(flags) {
251
252
  for (const [name, schema] of Object.entries(flags)) {
252
253
  words.push(`--${name}`);
253
254
  for (const alias of getFlagAliasNames(schema)) words.push(alias.length === 1 ? `-${alias}` : `--${alias}`);
255
+ const negated = getVisibleNegatedName(name, schema);
256
+ if (negated !== void 0) words.push(`--${negated}`);
254
257
  }
255
258
  return words.join(" ");
256
259
  }
@@ -1,6 +1,6 @@
1
1
  import { getFlagAliasNames } from "../../schema/flag.mjs";
2
2
  import { flagExpectsValue } from "../../parse/index.mjs";
3
- import { quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
3
+ import { getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
4
4
  //#region src/core/completion/shells/fish.ts
5
5
  /**
6
6
  * Generate a fish completion script for the CLI.
@@ -111,6 +111,8 @@ function appendFishFlagCompletions(lines, commandName, pathIsFuncName, path, fla
111
111
  for (const alias of getFlagAliasNames(schema, { kind: "short" })) parts.push(`-s ${quoteShellArg(alias)}`);
112
112
  parts.push(`-l ${quoteShellArg(name)}`);
113
113
  for (const alias of getFlagAliasNames(schema, { kind: "long" })) parts.push(`-l ${quoteShellArg(alias)}`);
114
+ const negated = getVisibleNegatedName(name, schema);
115
+ if (negated !== void 0) parts.push(`-l ${quoteShellArg(negated)}`);
114
116
  parts.push(`-d ${quoteShellArg(schema.description ?? name)}`);
115
117
  if (flagExpectsValue(schema)) parts.push("-r", "-f");
116
118
  if (schema.kind === "enum" && schema.enumValues !== void 0) {
@@ -1,6 +1,6 @@
1
- import { getFlagAliasNames } from "../../schema/flag.mjs";
1
+ import { getFlagAliasNames, getFlagNegatedName } from "../../schema/flag.mjs";
2
2
  import { flagExpectsValue } from "../../parse/index.mjs";
3
- import { resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
3
+ import { getVisibleNegatedName, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
4
4
  //#region src/core/completion/shells/powershell.ts
5
5
  /**
6
6
  * Generate a PowerShell completion script for the CLI.
@@ -90,10 +90,13 @@ function appendPowerShellPathEntry(lines, path, commands, flags) {
90
90
  lines.push(" )");
91
91
  lines.push(" Flags = @(");
92
92
  for (const [name, schema] of Object.entries(flags)) {
93
+ const visibleNegated = getVisibleNegatedName(name, schema);
94
+ const parseNegated = getFlagNegatedName(name, schema);
93
95
  const forms = dedupeValues([
94
96
  `--${name}`,
95
97
  ...getFlagAliasNames(schema, { kind: "short" }).map((alias) => `-${alias}`),
96
- ...getFlagAliasNames(schema, { kind: "long" }).map((alias) => `--${alias}`)
98
+ ...getFlagAliasNames(schema, { kind: "long" }).map((alias) => `--${alias}`),
99
+ ...visibleNegated !== void 0 ? [`--${visibleNegated}`] : []
97
100
  ]);
98
101
  const parseForms = dedupeValues([
99
102
  `--${name}`,
@@ -104,7 +107,8 @@ function appendPowerShellPathEntry(lines, path, commands, flags) {
104
107
  ...getFlagAliasNames(schema, {
105
108
  kind: "long",
106
109
  includeHidden: true
107
- }).map((alias) => `--${alias}`)
110
+ }).map((alias) => `--${alias}`),
111
+ ...parseNegated !== void 0 ? [`--${parseNegated}`] : []
108
112
  ]);
109
113
  lines.push(" @{");
110
114
  lines.push(`\t\t\t\tCanonicalName = ${quotePowerShellString(name)}`);