@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
package/CHANGELOG.md CHANGED
@@ -7,6 +7,74 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [3.0.0-rc.9] - 2026-07-11
11
+
12
+ ### Added
13
+
14
+ - **JSON help** — `--help` with `--json` emits the CLI's definition document
15
+ (the `generateSchema()` shape, `$schema`-tagged) on stdout instead of help
16
+ text, for root help, `help <command>`, and `<command> --help` alike. New
17
+ `generateCommandSchema(schema)` export produces the per-command document.
18
+
19
+ ### Changed
20
+
21
+ - **`generateSchema()` emits the default command's full definition** — the
22
+ `defaultCommand` field was a name-only string reference while the default
23
+ command's flags/args appeared nowhere in the document (it never lists in
24
+ `commands`). It is now the complete serialized command.
25
+
26
+ - **`flag.array()` rejects non-element builders at compile time** — the
27
+ element position now requires a builder carrying only value-shape settings
28
+ (kind, constraints, enum values, `parseFn`). Flag-level modifiers
29
+ (`.alias()`, `.env()`, `.default()`, `.prompt()`, `.describe()`, …) were
30
+ silently ignored on elements before; passing them is now a type error, as
31
+ is `flag.path()` / `flag.count()` / `flag.keyValue()` / nested arrays.
32
+ Type-level only — no runtime behavior change.
33
+
34
+ ## [3.0.0-rc.8] - 2026-07-11
35
+
36
+ ### Added
37
+
38
+ - **Themed help output** — root and per-command help render with a semantic
39
+ color theme (bold+underlined section titles, cyan literals, dimmed metadata,
40
+ yellow deprecations) whenever color is enabled, using the same gate as
41
+ `out.color` (TTY + color support, no `--json`, `NO_COLOR`/`FORCE_COLOR`
42
+ honored). Piped and JSON output stays byte-clean. Customize via
43
+ `.help({ theme: (c) => ({ sectionTitle: c.magenta }) })` — the factory
44
+ receives the gated ansispeck palette and is never invoked when color is off,
45
+ so custom themes cannot leak escapes. New public types: `HelpTheme`,
46
+ `HelpThemeFactory`.
47
+ - **Negatable booleans** — `flag.boolean().negatable()` accepts `--no-<name>`
48
+ as `false`. Both spellings are one logical flag (last CLI occurrence wins,
49
+ shared duplicate policy); the negated spelling is presence-only
50
+ (`--no-foo=x` errors) and renders as `--[no-]foo` in help. Custom spelling
51
+ via `{ alias }`, unadvertised via `{ hidden }`. Env/config/prompt/default
52
+ resolution is unchanged.
53
+ - **Duplicate policy** — `.duplicates('last' | 'first' | 'error')` on
54
+ singleton flags controls repeated CLI occurrences. `'error'` throws
55
+ `ParseError` code `DUPLICATE_FLAG` with `{ flag, count, values }` details;
56
+ `'first'` keeps the first value while still consuming later value tokens.
57
+ Counted per logical flag (aliases + negated + parity spellings); env/config
58
+ precedence is never a duplicate.
59
+ - **`packageRepositoryUrl(pkg, { require: true })`** — narrows the return
60
+ type to `string`, throwing a `CLIError` (code `INVALID_REPOSITORY`) at the
61
+ call site when the `repository` field is missing or not a recognisable
62
+ locator. Removes the `!` assertion for manifests known to carry a valid
63
+ repository, with the guarantee enforced at runtime rather than assumed.
64
+ - **Flag spelling parity (kebab ↔ camel)** — `--doThis` matches a flag named
65
+ `do-this` and vice versa, for names and long aliases, on by default.
66
+ Handler keys, help, completions, and suggestions stay canonical.
67
+ Automatically disabled per pair when both spellings are declared explicitly;
68
+ globally via `cli('mycli', { flags: { caseParity: false } })` (new
69
+ `cli(name, options)` overload) or `RunOptions.flags`.
70
+
71
+ ### Fixed
72
+
73
+ - `execute(argv, { flags })` overrides now reach the planner's dispatch arity
74
+ scanning, not just command parsing.
75
+ - Generated meta-schema descriptions render `@defaultValue` tags as a
76
+ `Default: <value>` paragraph instead of silently dropping them.
77
+
10
78
  ## [3.0.0-rc.7] - 2026-07-10
11
79
 
12
80
  ### Added
@@ -1130,7 +1198,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
1130
1198
  - MIT License.
1131
1199
  - Markdownlint configuration.
1132
1200
 
1133
- [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.7...HEAD
1201
+ [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.9...HEAD
1202
+ [3.0.0-rc.9]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.8...v3.0.0-rc.9
1203
+ [3.0.0-rc.8]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.7...v3.0.0-rc.8
1134
1204
  [3.0.0-rc.7]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.6...v3.0.0-rc.7
1135
1205
  [3.0.0-rc.6]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.5...v3.0.0-rc.6
1136
1206
  [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
@@ -5,6 +5,7 @@ import { command } from "../schema/command.mjs";
5
5
  import { includesBeforeSeparator } from "../parse/index.mjs";
6
6
  import { SHELLS, detectShell, generateCompletion, normalizeShell } from "../completion/index.mjs";
7
7
  import { formatHelp } from "../help/index.mjs";
8
+ import { generateCommandSchema, generateSchema } from "../json-schema/index.mjs";
8
9
  import { clearRequestedExitCode, createCaptureOutput, createOutput } from "../output/index.mjs";
9
10
  import { buildRunResult, executeCommand } from "../execution/index.mjs";
10
11
  import { runCommand } from "../testkit/index.mjs";
@@ -124,7 +125,8 @@ function buildCommandRunOptions(options, helpOptions, meta) {
124
125
  ...options?.jsonMode !== void 0 ? { jsonMode: options.jsonMode } : {},
125
126
  ...options?.isTTY !== void 0 ? { isTTY: options.isTTY } : {},
126
127
  ...options?.out !== void 0 ? { out: options.out } : {},
127
- ...options?.captured !== void 0 ? { captured: options.captured } : {}
128
+ ...options?.captured !== void 0 ? { captured: options.captured } : {},
129
+ ...options?.flags !== void 0 ? { flags: options.flags } : {}
128
130
  };
129
131
  }
130
132
  /**
@@ -553,12 +555,15 @@ var CLIBuilder = class CLIBuilder {
553
555
  ...this.schema.helpConfig,
554
556
  ...options?.help,
555
557
  binName: options?.help?.binName ?? this.schema.name,
556
- hyperlinks: options?.help?.hyperlinks ?? this.schema.helpConfig?.hyperlinks ?? out.isTTY
558
+ hyperlinks: options?.help?.hyperlinks ?? this.schema.helpConfig?.hyperlinks ?? out.isTTY,
559
+ colors: options?.help?.colors ?? out.color
557
560
  };
561
+ const flagSettings = options?.flags ?? this.schema.flagSettings;
558
562
  const effectiveOptions = {
559
563
  ...options,
560
564
  plugins: this.schema.plugins,
561
- ...jsonMode ? { jsonMode } : {}
565
+ ...jsonMode ? { jsonMode } : {},
566
+ ...flagSettings !== void 0 ? { flags: flagSettings } : {}
562
567
  };
563
568
  const output = {
564
569
  jsonMode,
@@ -566,7 +571,10 @@ var CLIBuilder = class CLIBuilder {
566
571
  verbosity: options?.verbosity ?? "normal"
567
572
  };
568
573
  const planned = planInvocation({
569
- schema: this.schema,
574
+ schema: options?.flags !== void 0 ? {
575
+ ...this.schema,
576
+ flagSettings
577
+ } : this.schema,
570
578
  argv,
571
579
  help: helpOptions,
572
580
  output
@@ -609,14 +617,16 @@ var CLIBuilder = class CLIBuilder {
609
617
  error: void 0
610
618
  }, captured);
611
619
  }
612
- case "root-help": {
613
- const helpText = formatRootHelp(resolveHelpLinksSchema(this.schema), planned.help);
614
- out.log(helpText);
620
+ case "root-help":
621
+ if (jsonMode) out.json(generateSchema(this.schema));
622
+ else {
623
+ const helpText = formatRootHelp(resolveHelpLinksSchema(this.schema), planned.help);
624
+ out.log(helpText);
625
+ }
615
626
  return buildRunResult({
616
627
  exitCode: 0,
617
628
  error: void 0
618
629
  }, captured);
619
- }
620
630
  case "dispatch-error":
621
631
  if (jsonMode) out.json({ error: planned.error.toJSON() });
622
632
  else {
@@ -627,14 +637,16 @@ var CLIBuilder = class CLIBuilder {
627
637
  exitCode: planned.error.exitCode,
628
638
  error: planned.error
629
639
  }, captured);
630
- case "needs-subcommand": {
631
- const helpText = formatHelp(planned.command.schema, planned.help);
632
- out.log(helpText);
640
+ case "needs-subcommand":
641
+ if (jsonMode) out.json(generateCommandSchema(planned.command.schema));
642
+ else {
643
+ const helpText = formatHelp(planned.command.schema, planned.help);
644
+ out.log(helpText);
645
+ }
633
646
  return buildRunResult({
634
647
  exitCode: 0,
635
648
  error: void 0
636
649
  }, captured);
637
- }
638
650
  case "match": {
639
651
  const commandRunOptions = buildCommandRunOptions(effectiveOptions, planned.plan.help ?? helpOptions, planned.plan.meta);
640
652
  if (planned.plan.command._command === void 0) return planned.plan.command._execute(planned.plan.argv, {
@@ -906,10 +918,14 @@ function isPackageJsonData(value) {
906
918
  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
907
919
  return "name" in value || "version" in value || "description" in value || "bin" in value || "homepage" in value || "repository" in value;
908
920
  }
909
- function cli(nameOrOptions) {
921
+ function cli(nameOrOptions, extraOptions) {
922
+ const options = typeof nameOrOptions === "string" ? {
923
+ name: nameOrOptions,
924
+ ...extraOptions
925
+ } : nameOrOptions;
910
926
  return new CLIBuilder({
911
- name: typeof nameOrOptions === "string" ? nameOrOptions : nameOrOptions.name ?? "cli",
912
- inheritName: typeof nameOrOptions === "string" ? false : nameOrOptions.inherit ?? false,
927
+ name: options.name ?? "cli",
928
+ inheritName: options.inherit ?? false,
913
929
  version: void 0,
914
930
  description: void 0,
915
931
  commands: [],
@@ -921,6 +937,7 @@ function cli(nameOrOptions) {
921
937
  hasBuiltInCompletions: false,
922
938
  completionsFlag: void 0,
923
939
  helpConfig: void 0,
940
+ flagSettings: options.flags,
924
941
  plugins: []
925
942
  });
926
943
  }
@@ -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":