@kjanat/dreamcli 3.0.0-rc.6 → 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 (94) hide show
  1. package/CHANGELOG.md +94 -1
  2. package/dist/core/cli/dispatch.d.mts +6 -5
  3. package/dist/core/cli/dispatch.mjs +7 -5
  4. package/dist/core/cli/help-links.d.mts +0 -1
  5. package/dist/core/cli/index.d.mts +27 -2
  6. package/dist/core/cli/index.mjs +28 -14
  7. package/dist/core/cli/planner.d.mts +3 -1
  8. package/dist/core/cli/planner.mjs +12 -12
  9. package/dist/core/cli/plugin.d.mts +1 -1
  10. package/dist/core/cli/propagate.d.mts +1 -1
  11. package/dist/core/cli/root-help.d.mts +0 -1
  12. package/dist/core/cli/root-help.mjs +38 -21
  13. package/dist/core/cli/root-surface.d.mts +0 -1
  14. package/dist/core/cli/runtime-preflight.d.mts +12 -2
  15. package/dist/core/cli/runtime-preflight.mjs +5 -4
  16. package/dist/core/completion/index.d.mts +0 -1
  17. package/dist/core/completion/index.mjs +1 -1
  18. package/dist/core/completion/shells/bash.d.mts +0 -1
  19. package/dist/core/completion/shells/bash.mjs +8 -4
  20. package/dist/core/completion/shells/fish.d.mts +0 -1
  21. package/dist/core/completion/shells/fish.mjs +6 -3
  22. package/dist/core/completion/shells/powershell.d.mts +0 -1
  23. package/dist/core/completion/shells/powershell.mjs +10 -5
  24. package/dist/core/completion/shells/shared.d.mts +13 -2
  25. package/dist/core/completion/shells/shared.mjs +24 -2
  26. package/dist/core/completion/shells/zsh.d.mts +0 -1
  27. package/dist/core/completion/shells/zsh.mjs +11 -4
  28. package/dist/core/config/index.d.mts +2 -3
  29. package/dist/core/config/index.mjs +2 -2
  30. package/dist/core/config/package-json.d.mts +27 -4
  31. package/dist/core/config/package-json.mjs +20 -19
  32. package/dist/core/errors/index.d.mts +1 -1
  33. package/dist/core/execution/index.d.mts +0 -1
  34. package/dist/core/execution/index.mjs +8 -4
  35. package/dist/core/help/ansi.mjs +3 -2
  36. package/dist/core/help/index.d.mts +22 -3
  37. package/dist/core/help/index.mjs +65 -53
  38. package/dist/core/help/theme.d.mts +68 -0
  39. package/dist/core/help/theme.mjs +46 -0
  40. package/dist/core/json-schema/index.d.mts +1 -1
  41. package/dist/core/json-schema/index.mjs +39 -8
  42. package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
  43. package/dist/core/json-schema/meta-descriptions.generated.mjs +14 -5
  44. package/dist/core/output/activity.d.mts +0 -1
  45. package/dist/core/output/contracts.d.mts +0 -1
  46. package/dist/core/output/contracts.mjs +1 -1
  47. package/dist/core/output/index.d.mts +0 -1
  48. package/dist/core/output/index.mjs +1 -1
  49. package/dist/core/output/renderers.d.mts +0 -1
  50. package/dist/core/parse/index.d.mts +40 -7
  51. package/dist/core/parse/index.mjs +209 -40
  52. package/dist/core/prompt/index.d.mts +1 -0
  53. package/dist/core/resolve/args.d.mts +1 -1
  54. package/dist/core/resolve/coerce.d.mts +1 -1
  55. package/dist/core/resolve/coerce.mjs +71 -14
  56. package/dist/core/resolve/contracts.d.mts +7 -2
  57. package/dist/core/resolve/errors.d.mts +0 -1
  58. package/dist/core/resolve/flags.d.mts +7 -2
  59. package/dist/core/resolve/flags.mjs +61 -6
  60. package/dist/core/resolve/index.d.mts +2 -2
  61. package/dist/core/resolve/index.mjs +1 -1
  62. package/dist/core/resolve/property.d.mts +3 -0
  63. package/dist/core/resolve/property.mjs +11 -3
  64. package/dist/core/schema/activity.d.mts +31 -11
  65. package/dist/core/schema/arg.d.mts +1 -2
  66. package/dist/core/schema/command.d.mts +8 -6
  67. package/dist/core/schema/command.mjs +26 -12
  68. package/dist/core/schema/flag.d.mts +439 -10
  69. package/dist/core/schema/flag.mjs +255 -3
  70. package/dist/core/schema/index.d.mts +4 -2
  71. package/dist/core/schema/middleware.d.mts +4 -3
  72. package/dist/core/schema/prompt.d.mts +5 -2
  73. package/dist/core/schema/run.d.mts +20 -1
  74. package/dist/core/schema/string-constraints.d.mts +97 -0
  75. package/dist/core/schema/string-constraints.mjs +69 -0
  76. package/dist/core/schema/value-parsers.d.mts +78 -0
  77. package/dist/core/schema/value-parsers.mjs +142 -0
  78. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  79. package/dist/core/testkit/index.d.mts +0 -31
  80. package/dist/core/testkit/index.mjs +1 -1
  81. package/dist/index.d.mts +8 -4
  82. package/dist/index.mjs +7 -7
  83. package/dist/runtime/adapter.d.mts +22 -1
  84. package/dist/runtime/adapter.mjs +3 -0
  85. package/dist/runtime/auto.d.mts +0 -1
  86. package/dist/runtime/deno.d.mts +15 -5
  87. package/dist/runtime/deno.mjs +9 -0
  88. package/dist/runtime/node.d.mts +2 -2
  89. package/dist/runtime/node.mjs +10 -0
  90. package/dist/runtime.d.mts +1 -0
  91. package/dist/testkit.d.mts +1 -0
  92. package/dist/version.mjs +2 -2
  93. package/dreamcli.schema.json +35 -6
  94. package/package.json +12 -13
package/CHANGELOG.md CHANGED
@@ -7,6 +7,97 @@ 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
+
54
+ ## [3.0.0-rc.7] - 2026-07-10
55
+
56
+ ### Added
57
+
58
+ - **`.derive()` handlers may omit the return** — a validation-only derive with
59
+ no `return` statement (sync or async) now typechecks; previously `void` /
60
+ `Promise<void>` failed the `Output` constraint and forced an explicit
61
+ `return undefined`.
62
+ - **String constraints** — `flag.string({ nonEmpty, minLength, maxLength, pattern })`
63
+ plus chained `.nonEmpty()` / `.minLength()` / `.maxLength()` / `.pattern()`,
64
+ mirroring the numeric-constraint model. Checked in fixed order
65
+ (nonEmpty → minLength → maxLength → pattern) at both the CLI parse boundary
66
+ (`INVALID_VALUE`) and env/config/prompt resolution (`CONSTRAINT_VIOLATED`),
67
+ and emitted into the exported JSON Schema as `minLength` / `maxLength` /
68
+ `pattern`.
69
+ - **`.separator()` and `.unique()` on array flags** — `.separator(',')` splits
70
+ each CLI occurrence before element coercion, so `--region us,eu --region ap`
71
+ works alongside repetition and errors name the offending element. Env/config
72
+ string values use the same separator (default remains `','`). `.unique()`
73
+ deduplicates the final resolved array (first-seen order) regardless of
74
+ source.
75
+ - **`flag.url()`** — parses into a `URL`, with optional
76
+ `{ protocols: ['https'] }` allowlist. Help shows `<url>`.
77
+ - **`flag.path()`** — path string with opt-in filesystem checks
78
+ (`{ mustExist: true }`, `{ type: 'file' | 'directory' }`) validated after
79
+ resolution through the runtime adapter, so CLI/env/config values are checked
80
+ identically. `RuntimeAdapter` gained a `stat()` primitive (Node/Bun via
81
+ `node:fs/promises`, Deno via `Deno.stat`; test adapters default to "nothing
82
+ exists"), and `RunOptions` / `ResolveOptions` accept a `stat` injection for
83
+ process-free execution — without one, checks are skipped.
84
+ - **`flag.date()`** — strict ISO-8601 → `Date` with optional inclusive
85
+ `min` / `max` bounds. Rejects lenient `Date.parse` inputs (`'0'`,
86
+ `'March 5'`) and calendar-invalid dates (`2026-02-31`).
87
+ - **`flag.duration()`** — `'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`,
88
+ compounds (`'1h30m'`), or bare milliseconds → milliseconds.
89
+ - **`flag.bytes()`** — `'512mb'`, `'1.5gb'`, `'64kb'` or bare bytes → bytes
90
+ (binary units, case-insensitive).
91
+ - **`flag.count()`** — occurrence counter (`-vvv` → `3`, absent → `0`,
92
+ explicit `--verbose=2` supported). Takes no value token, not promptable,
93
+ and joins boolean flags in help (no `<value>` placeholder) and shell
94
+ completions.
95
+ - **`flag.keyValue()`** — repeated `KEY=VALUE` merges into
96
+ `Record<string, string>` (split at the first `=`, later keys win, unset
97
+ resolves to `{}`). Env accepts comma-separated pairs; config accepts a plain
98
+ object. New `'empty-object'` optional fallback joins arrays' `[]` as the
99
+ kinds that resolve to a value when unset.
100
+
10
101
  ## [3.0.0-rc.6] - 2026-07-09
11
102
 
12
103
  ### Added
@@ -1083,7 +1174,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
1083
1174
  - MIT License.
1084
1175
  - Markdownlint configuration.
1085
1176
 
1086
- [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.6...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
1179
+ [3.0.0-rc.7]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.6...v3.0.0-rc.7
1087
1180
  [3.0.0-rc.6]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.5...v3.0.0-rc.6
1088
1181
  [3.0.0-rc.5]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.4...v3.0.0-rc.5
1089
1182
  [3.0.0-rc.4]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.3...v3.0.0-rc.4
@@ -1,15 +1,14 @@
1
- import { FlagSchema } from "../schema/flag.mjs";
2
1
  import { CommandSchema, ErasedCommand } from "../schema/command.mjs";
3
-
2
+ import { FlagLookupEntry, ParseOptions } from "../parse/index.mjs";
4
3
  //#region src/core/cli/dispatch.d.ts
5
4
  /**
6
- * Flag lookup (name/alias → `[canonicalName, schema]`) used to make the
5
+ * Flag lookup (spelling → {@link FlagLookupEntry}) used to make the
7
6
  * command-name scan aware of value-flag arity. Built from the flags valid at
8
7
  * the current dispatch level via {@link buildFlagLookup}.
9
8
  *
10
9
  * @internal
11
10
  */
12
- type ValueFlagLookup = ReadonlyMap<string, readonly [name: string, schema: FlagSchema]>;
11
+ type ValueFlagLookup = ReadonlyMap<string, FlagLookupEntry>;
13
12
  /** Successful dispatch — target command found with argv path. */
14
13
  interface DispatchMatch {
15
14
  /** Discriminant — a command name in argv matched a registered command. */
@@ -65,11 +64,13 @@ type DispatchResult = DispatchMatch | DispatchNeedsSubcommand | DispatchUnknown;
65
64
  * @param valueFlags - Lookup of flags valid at this level, used so a
66
65
  * space-separated value-flag's value (`--region eu`) is not mistaken for a
67
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.
68
69
  * @returns Discriminated dispatch result.
69
70
  *
70
71
  * @internal
71
72
  */
72
- 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;
73
74
  /**
74
75
  * Whether a flag token consumes the following argv token as its value.
75
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;
@@ -211,4 +213,4 @@ function uniqueCommands(commands) {
211
213
  return result;
212
214
  }
213
215
  //#endregion
214
- export { dispatch, findClosestCommand };
216
+ export { consumesFollowingToken, dispatch, findClosestCommand, levenshtein, uniqueCommands };
@@ -1,5 +1,4 @@
1
1
  import { PackageJsonData } from "../config/package-json.mjs";
2
-
3
2
  //#region src/core/cli/help-links.d.ts
4
3
  /**
5
4
  * OSC 8 hyperlink targets for the root-help header.
@@ -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";
@@ -10,7 +13,6 @@ import { CompletionOptions } from "../completion/shells/shared.mjs";
10
13
  import { Shell } from "../completion/index.mjs";
11
14
  import { FormatLoader } from "../config/index.mjs";
12
15
  import { formatRootHelp } from "./root-help.mjs";
13
-
14
16
  //#region src/core/cli/index.d.ts
15
17
  /**
16
18
  * Runtime descriptor for the CLI program.
@@ -97,6 +99,12 @@ interface CLISchema {
97
99
  * under runtime `options.help` (runtime wins) before rendering.
98
100
  */
99
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;
100
108
  /** Registered CLI plugins. */
101
109
  readonly plugins: readonly CLIPlugin[];
102
110
  }
@@ -145,6 +153,17 @@ interface HelpConfig {
145
153
  readonly width?: number;
146
154
  /** Emit OSC 8 hyperlinks in the header when supported. */
147
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;
148
167
  }
149
168
  /**
150
169
  * Config discovery settings for automatic config file loading.
@@ -754,6 +773,12 @@ interface CLIOptions {
754
773
  * @defaultValue `false`
755
774
  */
756
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;
757
782
  }
758
783
  /**
759
784
  * Create a new CLI program builder.
@@ -774,7 +799,7 @@ interface CLIOptions {
774
799
  * .run();
775
800
  * ```
776
801
  */
777
- declare function cli(name: string): CLIBuilder;
802
+ declare function cli(name: string, options?: Omit<CLIOptions, 'name'>): CLIBuilder;
778
803
  /** Create a new CLI program builder from an options object. */
779
804
  declare function cli(options: CLIOptions): CLIBuilder;
780
805
  //#endregion
@@ -1,18 +1,18 @@
1
- import { getFlagAliasNames } from "../schema/flag.mjs";
2
1
  import { CLIError } from "../errors/index.mjs";
3
- import { SHELLS, detectShell, generateCompletion, normalizeShell } from "../completion/index.mjs";
4
- import { formatHelp } from "../help/index.mjs";
5
- import { clearRequestedExitCode, createCaptureOutput, createOutput } from "../output/index.mjs";
2
+ import { getFlagAliasNames } from "../schema/flag.mjs";
6
3
  import { arg } from "../schema/arg.mjs";
7
4
  import { command } from "../schema/command.mjs";
8
5
  import { includesBeforeSeparator } from "../parse/index.mjs";
6
+ import { SHELLS, detectShell, generateCompletion, normalizeShell } from "../completion/index.mjs";
7
+ import { formatHelp } from "../help/index.mjs";
8
+ import { clearRequestedExitCode, createCaptureOutput, createOutput } from "../output/index.mjs";
9
9
  import { buildRunResult, executeCommand } from "../execution/index.mjs";
10
10
  import { runCommand } from "../testkit/index.mjs";
11
11
  import { stripTrailing } from "../../strings.mjs";
12
12
  import { createAdapter } from "../../runtime/auto.mjs";
13
13
  import { deriveHelpLinks } from "./help-links.mjs";
14
14
  import { planInvocation } from "./planner.mjs";
15
- import "./plugin.mjs";
15
+ import { plugin } from "./plugin.mjs";
16
16
  import { formatRootHelp } from "./root-help.mjs";
17
17
  import { prepareRuntimePreflight } from "./runtime-preflight.mjs";
18
18
  //#region src/core/cli/index.ts
@@ -119,11 +119,13 @@ function buildCommandRunOptions(options, helpOptions, meta) {
119
119
  ...options?.stdinData !== void 0 ? { stdinData: options.stdinData } : {},
120
120
  ...options?.prompter !== void 0 ? { prompter: options.prompter } : {},
121
121
  ...options?.answers !== void 0 ? { answers: options.answers } : {},
122
+ ...options?.stat !== void 0 ? { stat: options.stat } : {},
122
123
  ...options?.verbosity !== void 0 ? { verbosity: options.verbosity } : {},
123
124
  ...options?.jsonMode !== void 0 ? { jsonMode: options.jsonMode } : {},
124
125
  ...options?.isTTY !== void 0 ? { isTTY: options.isTTY } : {},
125
126
  ...options?.out !== void 0 ? { out: options.out } : {},
126
- ...options?.captured !== void 0 ? { captured: options.captured } : {}
127
+ ...options?.captured !== void 0 ? { captured: options.captured } : {},
128
+ ...options?.flags !== void 0 ? { flags: options.flags } : {}
127
129
  };
128
130
  }
129
131
  /**
@@ -513,8 +515,9 @@ var CLIBuilder = class CLIBuilder {
513
515
  });
514
516
  else out.log(script);
515
517
  });
518
+ const withCompletions = this.command(cmd);
516
519
  return new CLIBuilder({
517
- ...this.command(cmd).schema,
520
+ ...withCompletions.schema,
518
521
  hasBuiltInCompletions: true
519
522
  });
520
523
  }
@@ -551,12 +554,15 @@ var CLIBuilder = class CLIBuilder {
551
554
  ...this.schema.helpConfig,
552
555
  ...options?.help,
553
556
  binName: options?.help?.binName ?? this.schema.name,
554
- 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
555
559
  };
560
+ const flagSettings = options?.flags ?? this.schema.flagSettings;
556
561
  const effectiveOptions = {
557
562
  ...options,
558
563
  plugins: this.schema.plugins,
559
- ...jsonMode ? { jsonMode } : {}
564
+ ...jsonMode ? { jsonMode } : {},
565
+ ...flagSettings !== void 0 ? { flags: flagSettings } : {}
560
566
  };
561
567
  const output = {
562
568
  jsonMode,
@@ -564,7 +570,10 @@ var CLIBuilder = class CLIBuilder {
564
570
  verbosity: options?.verbosity ?? "normal"
565
571
  };
566
572
  const planned = planInvocation({
567
- schema: this.schema,
573
+ schema: options?.flags !== void 0 ? {
574
+ ...this.schema,
575
+ flagSettings
576
+ } : this.schema,
568
577
  argv,
569
578
  help: helpOptions,
570
579
  output
@@ -904,10 +913,14 @@ function isPackageJsonData(value) {
904
913
  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
905
914
  return "name" in value || "version" in value || "description" in value || "bin" in value || "homepage" in value || "repository" in value;
906
915
  }
907
- function cli(nameOrOptions) {
916
+ function cli(nameOrOptions, extraOptions) {
917
+ const options = typeof nameOrOptions === "string" ? {
918
+ name: nameOrOptions,
919
+ ...extraOptions
920
+ } : nameOrOptions;
908
921
  return new CLIBuilder({
909
- name: typeof nameOrOptions === "string" ? nameOrOptions : nameOrOptions.name ?? "cli",
910
- inheritName: typeof nameOrOptions === "string" ? false : nameOrOptions.inherit ?? false,
922
+ name: options.name ?? "cli",
923
+ inheritName: options.inherit ?? false,
911
924
  version: void 0,
912
925
  description: void 0,
913
926
  commands: [],
@@ -919,8 +932,9 @@ function cli(nameOrOptions) {
919
932
  hasBuiltInCompletions: false,
920
933
  completionsFlag: void 0,
921
934
  helpConfig: void 0,
935
+ flagSettings: options.flags,
922
936
  plugins: []
923
937
  });
924
938
  }
925
939
  //#endregion
926
- export { CLIBuilder, cli };
940
+ export { CLIBuilder, cli, formatRootHelp, plugin };
@@ -3,9 +3,9 @@ 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
9
  //#region src/core/cli/planner.d.ts
10
10
  /**
11
11
  * Structural subset of CLISchema used by the planner.
@@ -33,6 +33,8 @@ interface PlannerSchemaLike {
33
33
  readonly shells: readonly Shell[];
34
34
  readonly options: CompletionOptions | undefined;
35
35
  } | undefined;
36
+ /** Flag-parsing behavior settings (case parity) applied to flag lookups. */
37
+ readonly flagSettings?: ParseOptions | undefined;
36
38
  /** Plugins forwarded into every matched execution plan. */
37
39
  readonly plugins: readonly CLIPlugin[];
38
40
  }
@@ -1,7 +1,7 @@
1
- import { collectPropagatedFlags } from "./propagate.mjs";
2
1
  import { CLIError, ParseError } from "../errors/index.mjs";
3
- import { normalizeShell } from "../completion/index.mjs";
4
2
  import { buildFlagLookup, flagExpectsValue, includesBeforeSeparator } from "../parse/index.mjs";
3
+ import { collectPropagatedFlags } from "./propagate.mjs";
4
+ import { normalizeShell } from "../completion/index.mjs";
5
5
  import { dispatch, findClosestCommand } from "./dispatch.mjs";
6
6
  //#region src/core/cli/planner.ts
7
7
  function buildMeta(schema, helpOptions, commandName) {
@@ -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}`, {
@@ -297,4 +297,4 @@ function planInvocation(options) {
297
297
  }
298
298
  }
299
299
  //#endregion
300
- export { planInvocation };
300
+ export { buildCommandExecutionPlan, buildRootCommandMap, mergeCommandSchema, planInvocation };
@@ -1,6 +1,6 @@
1
1
  import { DeprecationWarning } from "../resolve/contracts.mjs";
2
+ import "../resolve/index.mjs";
2
3
  import { CommandMeta, CommandSchema, Out } from "../schema/command.mjs";
3
-
4
4
  //#region src/core/cli/plugin.d.ts
5
5
  /** Shared hook payload for a concrete command execution. */
6
6
  interface PluginCommandContext {
@@ -1,6 +1,6 @@
1
1
  import { FlagSchema } from "../schema/flag.mjs";
2
2
  import { CommandSchema } from "../schema/command.mjs";
3
-
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,5 @@
1
1
  import { HelpOptions } from "../help/index.mjs";
2
2
  import { CommandSchema } from "../schema/command.mjs";
3
-
4
3
  //#region src/core/cli/root-help.d.ts
5
4
  /** Structural subset of `CLISchema` — avoids circular imports through the barrel. */
6
5
  interface CLISchemaLike {