@kjanat/dreamcli 2.5.0 → 3.0.0-rc.10

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 (202) hide show
  1. package/CHANGELOG.md +344 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/dispatch.d.mts +6 -5
  4. package/dist/core/cli/dispatch.mjs +205 -1
  5. package/dist/core/cli/help-links.d.mts +0 -1
  6. package/dist/core/cli/help-links.mjs +41 -1
  7. package/dist/core/cli/index.d.mts +185 -19
  8. package/dist/core/cli/index.mjs +945 -1
  9. package/dist/core/cli/planner.d.mts +32 -6
  10. package/dist/core/cli/planner.mjs +300 -1
  11. package/dist/core/cli/plugin.d.mts +1 -1
  12. package/dist/core/cli/plugin.mjs +41 -1
  13. package/dist/core/cli/propagate.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +57 -1
  15. package/dist/core/cli/root-help.d.mts +18 -3
  16. package/dist/core/cli/root-help.mjs +226 -6
  17. package/dist/core/cli/root-surface.d.mts +30 -4
  18. package/dist/core/cli/root-surface.mjs +28 -1
  19. package/dist/core/cli/runtime-preflight.d.mts +30 -3
  20. package/dist/core/cli/runtime-preflight.mjs +169 -1
  21. package/dist/core/completion/index.d.mts +32 -2
  22. package/dist/core/completion/index.mjs +90 -1
  23. package/dist/core/completion/shells/bash.d.mts +0 -1
  24. package/dist/core/completion/shells/bash.mjs +308 -3
  25. package/dist/core/completion/shells/fish.d.mts +0 -1
  26. package/dist/core/completion/shells/fish.mjs +162 -2
  27. package/dist/core/completion/shells/powershell.d.mts +0 -1
  28. package/dist/core/completion/shells/powershell.mjs +358 -2
  29. package/dist/core/completion/shells/shared.d.mts +23 -2
  30. package/dist/core/completion/shells/shared.mjs +176 -1
  31. package/dist/core/completion/shells/zsh.d.mts +0 -1
  32. package/dist/core/completion/shells/zsh.mjs +251 -2
  33. package/dist/core/config/index.d.mts +2 -3
  34. package/dist/core/config/index.mjs +246 -1
  35. package/dist/core/config/package-json.d.mts +27 -4
  36. package/dist/core/config/package-json.mjs +386 -3
  37. package/dist/core/errors/index.d.mts +3 -3
  38. package/dist/core/errors/index.mjs +87 -1
  39. package/dist/core/execution/index.d.mts +0 -1
  40. package/dist/core/execution/index.mjs +201 -1
  41. package/dist/core/help/ansi.d.mts +11 -5
  42. package/dist/core/help/ansi.mjs +121 -2
  43. package/dist/core/help/index.d.mts +65 -2
  44. package/dist/core/help/index.mjs +341 -7
  45. package/dist/core/help/theme.d.mts +68 -0
  46. package/dist/core/help/theme.mjs +46 -0
  47. package/dist/core/json-schema/index.d.mts +15 -2
  48. package/dist/core/json-schema/index.mjs +536 -12
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
  51. package/dist/core/output/activity.d.mts +0 -1
  52. package/dist/core/output/activity.mjs +452 -1
  53. package/dist/core/output/bind.mjs +56 -1
  54. package/dist/core/output/contracts.d.mts +4 -5
  55. package/dist/core/output/contracts.mjs +57 -1
  56. package/dist/core/output/display-value.mjs +32 -1
  57. package/dist/core/output/index.d.mts +21 -1
  58. package/dist/core/output/index.mjs +442 -2
  59. package/dist/core/output/renderers.d.mts +0 -1
  60. package/dist/core/output/renderers.mjs +46 -1
  61. package/dist/core/output/writer.mjs +12 -1
  62. package/dist/core/parse/index.d.mts +54 -7
  63. package/dist/core/parse/index.mjs +727 -1
  64. package/dist/core/prompt/index.d.mts +12 -4
  65. package/dist/core/prompt/index.mjs +348 -6
  66. package/dist/core/resolve/args.d.mts +1 -1
  67. package/dist/core/resolve/args.mjs +105 -1
  68. package/dist/core/resolve/coerce.d.mts +1 -1
  69. package/dist/core/resolve/coerce.mjs +336 -1
  70. package/dist/core/resolve/config.mjs +19 -1
  71. package/dist/core/resolve/contracts.d.mts +9 -4
  72. package/dist/core/resolve/errors.d.mts +0 -1
  73. package/dist/core/resolve/errors.mjs +140 -2
  74. package/dist/core/resolve/flags.d.mts +7 -2
  75. package/dist/core/resolve/flags.mjs +251 -1
  76. package/dist/core/resolve/index.d.mts +2 -2
  77. package/dist/core/resolve/index.mjs +85 -1
  78. package/dist/core/resolve/property.d.mts +6 -2
  79. package/dist/core/resolve/property.mjs +53 -1
  80. package/dist/core/schema/activity.d.mts +31 -11
  81. package/dist/core/schema/arg.d.mts +92 -13
  82. package/dist/core/schema/arg.mjs +463 -1
  83. package/dist/core/schema/command.d.mts +29 -7
  84. package/dist/core/schema/command.mjs +726 -1
  85. package/dist/core/schema/flag.d.mts +577 -21
  86. package/dist/core/schema/flag.mjs +705 -1
  87. package/dist/core/schema/index.d.mts +5 -2
  88. package/dist/core/schema/middleware.d.mts +4 -3
  89. package/dist/core/schema/middleware.mjs +41 -1
  90. package/dist/core/schema/number-constraints.d.mts +96 -0
  91. package/dist/core/schema/number-constraints.mjs +60 -0
  92. package/dist/core/schema/prompt.d.mts +21 -3
  93. package/dist/core/schema/run.d.mts +24 -5
  94. package/dist/core/schema/string-constraints.d.mts +97 -0
  95. package/dist/core/schema/string-constraints.mjs +69 -0
  96. package/dist/core/schema/value-parsers.d.mts +78 -0
  97. package/dist/core/schema/value-parsers.mjs +142 -0
  98. package/dist/core/schema-dsl/runtime.mjs +271 -2
  99. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  100. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  101. package/dist/core/testkit/index.d.mts +9 -36
  102. package/dist/core/testkit/index.mjs +83 -1
  103. package/dist/index.d.mts +12 -6
  104. package/dist/index.mjs +22 -1
  105. package/dist/runtime/adapter.d.mts +38 -2
  106. package/dist/runtime/adapter.mjs +87 -1
  107. package/dist/runtime/auto.d.mts +2 -3
  108. package/dist/runtime/auto.mjs +45 -1
  109. package/dist/runtime/deno.d.mts +24 -5
  110. package/dist/runtime/deno.mjs +262 -2
  111. package/dist/runtime/detect.mjs +45 -1
  112. package/dist/runtime/index.d.mts +3 -4
  113. package/dist/runtime/node.d.mts +8 -2
  114. package/dist/runtime/node.mjs +220 -2
  115. package/dist/runtime/paths.mjs +48 -1
  116. package/dist/runtime.d.mts +4 -4
  117. package/dist/runtime.mjs +6 -1
  118. package/dist/strings.mjs +22 -1
  119. package/dist/testkit.d.mts +1 -0
  120. package/dist/testkit.mjs +5 -1
  121. package/dist/version.d.mts +7 -3
  122. package/dist/version.mjs +7 -1
  123. package/dreamcli.schema.json +36 -7
  124. package/examples/basic.ts +5 -1
  125. package/examples/gh/package.json +2 -7
  126. package/examples/pwsh-demo/package.json +1 -7
  127. package/examples/pwsh-demo/src/main.test.ts +1 -4
  128. package/examples/pwsh-demo/src/main.ts +14 -4
  129. package/examples/transport-launcher.ts +85 -0
  130. package/package.json +43 -49
  131. package/dist/runtime/bun.d.mts +0 -28
  132. package/dist/runtime/bun.mjs +0 -1
  133. package/dist/runtime/support.d.mts +0 -42
  134. package/dist/runtime/support.mjs +0 -1
  135. package/src/core/cli/dispatch.ts +0 -349
  136. package/src/core/cli/help-links.ts +0 -82
  137. package/src/core/cli/index.ts +0 -1413
  138. package/src/core/cli/planner.ts +0 -487
  139. package/src/core/cli/plugin.ts +0 -117
  140. package/src/core/cli/propagate.ts +0 -97
  141. package/src/core/cli/root-help.ts +0 -252
  142. package/src/core/cli/root-surface.ts +0 -74
  143. package/src/core/cli/runtime-preflight.ts +0 -438
  144. package/src/core/completion/index.ts +0 -88
  145. package/src/core/completion/shells/bash.ts +0 -459
  146. package/src/core/completion/shells/fish.ts +0 -259
  147. package/src/core/completion/shells/powershell.ts +0 -439
  148. package/src/core/completion/shells/shared.ts +0 -283
  149. package/src/core/completion/shells/zsh.ts +0 -381
  150. package/src/core/config/index.ts +0 -417
  151. package/src/core/config/package-json.ts +0 -560
  152. package/src/core/errors/index.ts +0 -193
  153. package/src/core/execution/index.ts +0 -268
  154. package/src/core/help/ansi.ts +0 -144
  155. package/src/core/help/index.ts +0 -516
  156. package/src/core/json-schema/index.ts +0 -891
  157. package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
  158. package/src/core/output/activity.ts +0 -575
  159. package/src/core/output/bind.ts +0 -59
  160. package/src/core/output/contracts.ts +0 -194
  161. package/src/core/output/display-value.ts +0 -48
  162. package/src/core/output/index.ts +0 -704
  163. package/src/core/output/renderers.ts +0 -125
  164. package/src/core/output/writer.ts +0 -46
  165. package/src/core/parse/index.ts +0 -681
  166. package/src/core/prompt/index.ts +0 -583
  167. package/src/core/resolve/args.ts +0 -144
  168. package/src/core/resolve/coerce.ts +0 -432
  169. package/src/core/resolve/config.ts +0 -26
  170. package/src/core/resolve/contracts.ts +0 -135
  171. package/src/core/resolve/errors.ts +0 -227
  172. package/src/core/resolve/flags.ts +0 -255
  173. package/src/core/resolve/index.ts +0 -108
  174. package/src/core/resolve/property.ts +0 -99
  175. package/src/core/schema/activity.ts +0 -240
  176. package/src/core/schema/arg.ts +0 -719
  177. package/src/core/schema/command.ts +0 -1498
  178. package/src/core/schema/flag.ts +0 -801
  179. package/src/core/schema/index.ts +0 -91
  180. package/src/core/schema/middleware.ts +0 -171
  181. package/src/core/schema/prompt.ts +0 -156
  182. package/src/core/schema/run.ts +0 -198
  183. package/src/core/schema-dsl/index.ts +0 -109
  184. package/src/core/schema-dsl/parse.ts +0 -262
  185. package/src/core/schema-dsl/runtime.ts +0 -609
  186. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  187. package/src/core/testkit/index.ts +0 -123
  188. package/src/index.ts +0 -179
  189. package/src/runtime/adapter.ts +0 -303
  190. package/src/runtime/auto.ts +0 -110
  191. package/src/runtime/bun.ts +0 -55
  192. package/src/runtime/deno.ts +0 -369
  193. package/src/runtime/detect.ts +0 -105
  194. package/src/runtime/index.ts +0 -21
  195. package/src/runtime/node-builtins.d.ts +0 -27
  196. package/src/runtime/node.ts +0 -300
  197. package/src/runtime/paths.ts +0 -64
  198. package/src/runtime/support.ts +0 -135
  199. package/src/runtime.ts +0 -31
  200. package/src/strings.ts +0 -34
  201. package/src/testkit.ts +0 -25
  202. package/src/version.ts +0 -20
package/CHANGELOG.md CHANGED
@@ -7,6 +7,339 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [3.0.0-rc.10] - 2026-07-15
11
+
12
+ ### Changed
13
+
14
+ - **`osc8()` link text is optional** — it now defaults to the link target, so
15
+ `osc8('https://x.dev')` renders as a hyperlink displaying its own URL.
16
+ Terminals without OSC 8 support still show a usable address. Passing an
17
+ explicit label is unchanged.
18
+ - **`osc8()` now delegates to `ansispeck`'s hyperlink constructor** — it emits
19
+ the **ST** (`ESC \`) terminator instead of **BEL** (`\x07`). Both are valid
20
+ OSC 8 terminators supported by modern terminals; the rendered link is
21
+ unchanged. This removes dreamcli's last hand-rolled escape-sequence code.
22
+
23
+ ## [3.0.0-rc.9] - 2026-07-11
24
+
25
+ ### Added
26
+
27
+ - **JSON help** — `--help` with `--json` emits the CLI's definition document
28
+ (the `generateSchema()` shape, `$schema`-tagged) on stdout instead of help
29
+ text, for root help, `help <command>`, and `<command> --help` alike. New
30
+ `generateCommandSchema(schema)` export produces the per-command document.
31
+
32
+ ### Changed
33
+
34
+ - **`generateSchema()` emits the default command's full definition** — the
35
+ `defaultCommand` field was a name-only string reference while the default
36
+ command's flags/args appeared nowhere in the document (it never lists in
37
+ `commands`). It is now the complete serialized command.
38
+
39
+ - **`flag.array()` rejects non-element builders at compile time** — the
40
+ element position now requires a builder carrying only value-shape settings
41
+ (kind, constraints, enum values, `parseFn`). Flag-level modifiers
42
+ (`.alias()`, `.env()`, `.default()`, `.prompt()`, `.describe()`, …) were
43
+ silently ignored on elements before; passing them is now a type error, as
44
+ is `flag.path()` / `flag.count()` / `flag.keyValue()` / nested arrays.
45
+ Type-level only — no runtime behavior change.
46
+
47
+ ## [3.0.0-rc.8] - 2026-07-11
48
+
49
+ ### Added
50
+
51
+ - **Themed help output** — root and per-command help render with a semantic
52
+ color theme (bold+underlined section titles, cyan literals, dimmed metadata,
53
+ yellow deprecations) whenever color is enabled, using the same gate as
54
+ `out.color` (TTY + color support, no `--json`, `NO_COLOR`/`FORCE_COLOR`
55
+ honored). Piped and JSON output stays byte-clean. Customize via
56
+ `.help({ theme: (c) => ({ sectionTitle: c.magenta }) })` — the factory
57
+ receives the gated ansispeck palette and is never invoked when color is off,
58
+ so custom themes cannot leak escapes. New public types: `HelpTheme`,
59
+ `HelpThemeFactory`.
60
+ - **Negatable booleans** — `flag.boolean().negatable()` accepts `--no-<name>`
61
+ as `false`. Both spellings are one logical flag (last CLI occurrence wins,
62
+ shared duplicate policy); the negated spelling is presence-only
63
+ (`--no-foo=x` errors) and renders as `--[no-]foo` in help. Custom spelling
64
+ via `{ alias }`, unadvertised via `{ hidden }`. Env/config/prompt/default
65
+ resolution is unchanged.
66
+ - **Duplicate policy** — `.duplicates('last' | 'first' | 'error')` on
67
+ singleton flags controls repeated CLI occurrences. `'error'` throws
68
+ `ParseError` code `DUPLICATE_FLAG` with `{ flag, count, values }` details;
69
+ `'first'` keeps the first value while still consuming later value tokens.
70
+ Counted per logical flag (aliases + negated + parity spellings); env/config
71
+ precedence is never a duplicate.
72
+ - **`packageRepositoryUrl(pkg, { require: true })`** — narrows the return
73
+ type to `string`, throwing a `CLIError` (code `INVALID_REPOSITORY`) at the
74
+ call site when the `repository` field is missing or not a recognisable
75
+ locator. Removes the `!` assertion for manifests known to carry a valid
76
+ repository, with the guarantee enforced at runtime rather than assumed.
77
+ - **Flag spelling parity (kebab ↔ camel)** — `--doThis` matches a flag named
78
+ `do-this` and vice versa, for names and long aliases, on by default.
79
+ Handler keys, help, completions, and suggestions stay canonical.
80
+ Automatically disabled per pair when both spellings are declared explicitly;
81
+ globally via `cli('mycli', { flags: { caseParity: false } })` (new
82
+ `cli(name, options)` overload) or `RunOptions.flags`.
83
+
84
+ ### Fixed
85
+
86
+ - `execute(argv, { flags })` overrides now reach the planner's dispatch arity
87
+ scanning, not just command parsing.
88
+ - Generated meta-schema descriptions render `@defaultValue` tags as a
89
+ `Default: <value>` paragraph instead of silently dropping them.
90
+
91
+ ## [3.0.0-rc.7] - 2026-07-10
92
+
93
+ ### Added
94
+
95
+ - **`.derive()` handlers may omit the return** — a validation-only derive with
96
+ no `return` statement (sync or async) now typechecks; previously `void` /
97
+ `Promise<void>` failed the `Output` constraint and forced an explicit
98
+ `return undefined`.
99
+ - **String constraints** — `flag.string({ nonEmpty, minLength, maxLength, pattern })`
100
+ plus chained `.nonEmpty()` / `.minLength()` / `.maxLength()` / `.pattern()`,
101
+ mirroring the numeric-constraint model. Checked in fixed order
102
+ (nonEmpty → minLength → maxLength → pattern) at both the CLI parse boundary
103
+ (`INVALID_VALUE`) and env/config/prompt resolution (`CONSTRAINT_VIOLATED`),
104
+ and emitted into the exported JSON Schema as `minLength` / `maxLength` /
105
+ `pattern`.
106
+ - **`.separator()` and `.unique()` on array flags** — `.separator(',')` splits
107
+ each CLI occurrence before element coercion, so `--region us,eu --region ap`
108
+ works alongside repetition and errors name the offending element. Env/config
109
+ string values use the same separator (default remains `','`). `.unique()`
110
+ deduplicates the final resolved array (first-seen order) regardless of
111
+ source.
112
+ - **`flag.url()`** — parses into a `URL`, with optional
113
+ `{ protocols: ['https'] }` allowlist. Help shows `<url>`.
114
+ - **`flag.path()`** — path string with opt-in filesystem checks
115
+ (`{ mustExist: true }`, `{ type: 'file' | 'directory' }`) validated after
116
+ resolution through the runtime adapter, so CLI/env/config values are checked
117
+ identically. `RuntimeAdapter` gained a `stat()` primitive (Node/Bun via
118
+ `node:fs/promises`, Deno via `Deno.stat`; test adapters default to "nothing
119
+ exists"), and `RunOptions` / `ResolveOptions` accept a `stat` injection for
120
+ process-free execution — without one, checks are skipped.
121
+ - **`flag.date()`** — strict ISO-8601 → `Date` with optional inclusive
122
+ `min` / `max` bounds. Rejects lenient `Date.parse` inputs (`'0'`,
123
+ `'March 5'`) and calendar-invalid dates (`2026-02-31`).
124
+ - **`flag.duration()`** — `'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`,
125
+ compounds (`'1h30m'`), or bare milliseconds → milliseconds.
126
+ - **`flag.bytes()`** — `'512mb'`, `'1.5gb'`, `'64kb'` or bare bytes → bytes
127
+ (binary units, case-insensitive).
128
+ - **`flag.count()`** — occurrence counter (`-vvv` → `3`, absent → `0`,
129
+ explicit `--verbose=2` supported). Takes no value token, not promptable,
130
+ and joins boolean flags in help (no `<value>` placeholder) and shell
131
+ completions.
132
+ - **`flag.keyValue()`** — repeated `KEY=VALUE` merges into
133
+ `Record<string, string>` (split at the first `=`, later keys win, unset
134
+ resolves to `{}`). Env accepts comma-separated pairs; config accepts a plain
135
+ object. New `'empty-object'` optional fallback joins arrays' `[]` as the
136
+ kinds that resolve to a value when unset.
137
+
138
+ ## [3.0.0-rc.6] - 2026-07-09
139
+
140
+ ### Added
141
+
142
+ - **Runtime terminal sizing hooks** — `RuntimeAdapter` now exposes
143
+ `getTerminalSize()` and `onTerminalResize()`. Node/Bun read
144
+ `process.stdout.getWindowSize()` (falling back to `columns` / `rows`) and
145
+ subscribe to stdout `resize`; Deno uses native `Deno.consoleSize()` and
146
+ `SIGWINCH` on non-Windows platforms.
147
+
148
+ ### Changed
149
+
150
+ - **Help output now fits the live terminal in `.run()`** — root and command help
151
+ use runtime terminal columns when no explicit `.help({ width })` or runtime
152
+ `help.width` is provided. Non-TTY or unavailable sizes still fall back to 80,
153
+ and `.execute()` remains deterministic for tests.
154
+
155
+ ## [3.0.0-rc.5] - 2026-07-08
156
+
157
+ ### Removed
158
+
159
+ - **`createBunAdapter` export** (from `@kjanat/dreamcli/runtime`). Bun exposes a
160
+ Node-compatible `process`, so the Bun adapter had been a pure passthrough to
161
+ the Node adapter since the runtime version hard-fail was dropped — it blessed
162
+ a runtime rather than abstracting distinct I/O. Auto-detection now maps Bun to
163
+ the Node adapter directly and `src/runtime/bun.ts` is gone. Runtime detection
164
+ is unchanged: `detectRuntime()` still reports `'bun'` and `RUNTIMES` still
165
+ lists it. Callers that selected the Bun adapter explicitly should use
166
+ `createNodeAdapter` (identical behavior) or rely on `createAdapter()`
167
+ auto-detection (#51).
168
+
169
+ ## [3.0.0-rc.4] - 2026-07-06
170
+
171
+ ### Added
172
+
173
+ - **`.default(cmd, { route: true })`** — expose a default command under its own
174
+ name as a routable top-level command, in addition to the bare/flags-only root
175
+ surface. `mycli` and `mycli <name>` then run the same command object, and it
176
+ is listed in the root `Commands:` section (tagged `(default)`) beside its
177
+ siblings. Lets CLIs keep both a short root shorthand and an explicit,
178
+ documented named command without duplicating the builder (#55). Opt-in only
179
+ — the surface-only default remains the default behavior. With `route: true`
180
+ the name wins over positional interpretation, so a positional value equal to
181
+ the command's own name must be passed after `--`.
182
+
183
+ ## [3.0.0-rc.3] - 2026-07-06
184
+
185
+ ### Added
186
+
187
+ - **`@kjanat/dreamcli/version` subpath** — exposes the framework's own build
188
+ identity as `DREAMCLI_VERSION` and `DREAMCLI_REVISION` (git short SHA) for
189
+ diagnostics and bug reports. Deliberately a subpath rather than root exports
190
+ so the constants stay out of root-import IDE completions; both report
191
+ `'dev'` when running unbundled source.
192
+
193
+ ## [3.0.0-rc.2] - 2026-07-06
194
+
195
+ ### Added
196
+
197
+ - **`out.color` — context-aware ANSI colors** — every handler's `out` now carries
198
+ a color palette powered by [`ansispeck`](https://github.com/kjanat/ansispeck).
199
+ Colors auto-enable only when stdout is a TTY, JSON mode is off, and the
200
+ environment supports color (`NO_COLOR`, `FORCE_COLOR`, `--no-color`, `--color`,
201
+ `CI` respected); otherwise every formatter is an identity function, so handlers
202
+ can write `out.log(out.color.green('✔ done'))` unconditionally.
203
+ `createOutput({ color })` forces the palette on/off (useful for asserting
204
+ colored output in tests), and the `Colors` type is re-exported from the root
205
+ entrypoint. First runtime dependency — kept external in `dist` (~1 kB gzipped
206
+ install).
207
+
208
+ ### Changed
209
+
210
+ - **npm package now resolves built `dist` on every runtime** — the `bun`/`deno`
211
+ → `src/*.ts` export conditions are gone and `src` is no longer published to
212
+ npm (JSR still ships source). Bun and Deno consumers previously loaded raw
213
+ source where build-time defines never ran, so `version` reported `'dev'`;
214
+ they now get the same tested output as Node, with the real version. The
215
+ export map is generated by tsdown at build time instead of hand-maintained.
216
+
217
+ ## [3.0.0-rc.1] - 2026-07-02
218
+
219
+ ### Added
220
+
221
+ - **`.completions({ as: 'flag' })`** — expose shell completion as an eager
222
+ `--completions <shell>` flag on the CLI root instead of a `completions`
223
+ subcommand. The planner intercepts the flag before dispatch, prints the script,
224
+ and exits; root help advertises `--completions <bash|zsh|fish|powershell>` in its
225
+ `Flags:` section. `.completions()` still defaults to `{ as: 'command' }`. Because
226
+ the eager flag is intercepted before dispatch, the `--completions` name is
227
+ reserved in flag mode — declaring a command/default flag of that name throws at
228
+ build time.
229
+ - **Shell auto-detection** — `--completions` with no value (flag form) resolves the
230
+ target shell from the environment: `$SHELL` (parsed as an interpreter path) wins
231
+ when it names a supported shell, otherwise the presence of `$PSModulePath` selects
232
+ PowerShell — the reliable signal for `pwsh`, which never sets `$SHELL`.
233
+ - **`detectShell(env)` / `normalizeShell(raw)`** — exported helpers behind the
234
+ detection above; `normalizeShell` accepts bare names, `$SHELL` paths, and the
235
+ `pwsh`/`powershell` pair.
236
+ - **`.help(config)` builder + extended `HelpOptions`** — configure root-help
237
+ rendering: `inlineDefault`, `showDefaultInCommands`, and `footer` (plus the
238
+ existing `width` / `hyperlinks`). Builder config is merged under runtime
239
+ `options.help` (runtime wins).
240
+ - **Numeric constraints for number flags and args** — `flag.number()` and
241
+ `arg.number()` now accept `{ min?, max?, int?, finite? }` (bounds inclusive),
242
+ and the same constraints compose via chained `.int()` / `.min(n)` / `.max(n)` /
243
+ `.finite(allow?)` methods (a later call overrides an earlier value, including
244
+ one set in the options object). The chained methods are compile-time guarded
245
+ to number-kind builders only. Constraints are enforced identically across the
246
+ parse path and the env/config/prompt resolution path (order: finite → int →
247
+ min → max): parse-time (CLI) violations throw `INVALID_VALUE`, while
248
+ env/config/prompt coercion reports `CONSTRAINT_VIOLATED` (both exit code `2`).
249
+ They are also surfaced in the exported JSON Schema as `minimum` / `maximum` and
250
+ `type: "integer"` when `int` is set. `min` / `max` must be finite — a
251
+ non-finite bound (`Infinity` / `-Infinity` / `NaN`) throws at construction. The
252
+ resolved TypeScript value type stays `number`.
253
+ - **Prompt-level defaults for `confirm` and `input` prompts** — `confirm`
254
+ prompts accept `default?: boolean` (drives the `(Y/n)` vs `(y/N)` hint and the
255
+ empty-line result, so a confirm can default to **No**), and `input` prompts
256
+ accept `default?: string` (shown in the hint as `(default: <value>)` and used
257
+ when the user presses Enter, skipping `validate`). Precedence among defaults is
258
+ prompt-level `default` > flag `.default()`. Unset `confirm` default stays
259
+ backward compatible (`true`).
260
+
261
+ ### Changed
262
+
263
+ - **BREAKING — the default command is now the root _surface_, not a named
264
+ subcommand.** `.default(cmd)` registers the command only as the default; it is no
265
+ longer added to `schema.commands`. Consequences:
266
+ - It can no longer be invoked by its own name (`mycli mycmd` does not route to it;
267
+ the token is treated as input to the default command).
268
+ - It is omitted from the root `Commands:` list by default (re-enable with
269
+ `.help({ showDefaultInCommands: true })`).
270
+ - Root `--help` renders the default command's `Arguments:`/`Flags:` inline even
271
+ when sibling commands exist (previously only when it was the sole command), and a
272
+ sole default with no subcommands shows its own usage line directly instead of a
273
+ `[command]` placeholder.
274
+ - **`finite` defaults to `true` (behavior change)** — `flag.number()` /
275
+ `arg.number()` now **reject `Infinity` and `-Infinity`**, which previously
276
+ passed straight through to handlers (`Number("Infinity")` is not `NaN`). Pass
277
+ `{ finite: false }` (or `.finite(false)`) to opt back into accepting non-finite
278
+ values. `NaN` continues to be rejected as before.
279
+ - **BREAKING — the runtime no longer hard-fails the host CLI on its version.**
280
+ Adapter construction previously threw (a bare, uncaught `Error`) when the
281
+ detected Node/Bun/Deno version was below DreamCLI's declared minimum, crashing
282
+ the consumer's CLI — including on `--help`. That check is removed: as a
283
+ dependency the consumer's package manager already enforces the `engines` range
284
+ at install time (and more softly), and when DreamCLI is bundled/inlined the
285
+ consumer — not us — owns their CLI's supported-runtime policy. `SUPPORTED_RUNTIMES`
286
+ and the generated `engines` minimums are unchanged and remain the source of
287
+ truth for docs and packaging.
288
+
289
+ ### Fixed
290
+
291
+ - **Empty `input`-prompt answer no longer clobbers a flag's `.default()`** — a
292
+ flag declared with both `.default(...)` and an `input` prompt previously
293
+ resolved to `""` when the user submitted an empty line, because empty input was
294
+ treated as a real answer that short-circuited the default fallback. An empty or
295
+ blank `input` answer with no prompt-level `default` is now treated as "no
296
+ answer", so resolution falls through to the flag's `.default()` (or, for a
297
+ required flag, the standard missing-flag error).
298
+
299
+ ### Fixed
300
+
301
+ - **Root `--help` now matches consistently with `--version`** (#29) — previously
302
+ `--help` / `-h` were intercepted at the root only when they were the very first
303
+ token, while `--version` / `-V` matched anywhere before `--`. A help flag
304
+ preceded only by flags (e.g. `mycli --verbose --help`) now shows root help,
305
+ mirroring `mycli --verbose --version`. A help flag that follows a subcommand
306
+ token still scopes to that subcommand (`mycli deploy --help` → `deploy` help);
307
+ `--version` remains a global, position-independent flag by design (there is no
308
+ per-command version). The bare `help` token now triggers root help from the same
309
+ position as `--help`, and the `--` end-of-options separator is respected for both.
310
+ - **Generated `--help` now advertises the active built-in global flags** (#32) — root
311
+ help renders a `Global options:` block listing `--help, -h` and `--json` (always),
312
+ `--version, -V` (when a version is set), and `--config <path>` (when `.config()`
313
+ enabled config discovery). Previously these framework-provided flags were invisible
314
+ in help even though they worked. `--completions` is unchanged (still advertised via
315
+ the inline surface when active).
316
+ - **Root usage no longer prints the default command's name** — the merged/sole-default
317
+ usage line rendered `Usage: <bin> <default-name> …`, teaching an invocation that does
318
+ not route (`.default()` is not a named command, so the token is consumed as the
319
+ default's first positional). It now renders under the bin name only
320
+ (`Usage: <bin> [flags] <args>`).
321
+ - **`inlineDefault: false` no longer hides a sole default command's interface** — when
322
+ the default command is the only surface (no visible subcommands and no eager
323
+ `--completions` flag), root help would collapse to a bare `Usage: <bin> [options]`
324
+ with no discoverable args/flags. The default is now always rendered inline in that
325
+ case, since suppressing it leaves no other path to its interface.
326
+
327
+ ### Fixed
328
+
329
+ - **`runCommand()` now honors a CLI-level `--json` passed in `argv`** — the testkit
330
+ gained the same root-flag layer as the real CLI: a `--json` before the `--`
331
+ separator enables JSON mode and is stripped before parsing, instead of failing
332
+ with `Unknown flag --json` (exit 2). A literal `--json` after `--` still reaches
333
+ the command unchanged. The existing `{ jsonMode: true }` option keeps working —
334
+ either source enables JSON mode. Copying a real `mycli --json …` invocation into a
335
+ test now works verbatim.
336
+ - **`createTestPrompter()` now runs an `input` prompt's `validate`** — a queued
337
+ string answer to an `input` prompt is validated exactly as the terminal prompter
338
+ does; an answer that fails validation is rejected as a cancellation rather than
339
+ injected verbatim as the resolved value, so prompt validation is integration-testable
340
+ through `runCommand(cmd, argv, { answers })`. Non-string answers stay verbatim so
341
+ downstream coercion paths remain testable.
342
+
10
343
  ## [2.5.0] - 2026-06-28
11
344
 
12
345
  ### Added
@@ -878,7 +1211,17 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
878
1211
  - MIT License.
879
1212
  - Markdownlint configuration.
880
1213
 
881
- [Unreleased]: https://github.com/kjanat/dreamcli/compare/v2.5.0...HEAD
1214
+ [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.10...HEAD
1215
+ [3.0.0-rc.10]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.9...v3.0.0-rc.10
1216
+ [3.0.0-rc.9]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.8...v3.0.0-rc.9
1217
+ [3.0.0-rc.8]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.7...v3.0.0-rc.8
1218
+ [3.0.0-rc.7]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.6...v3.0.0-rc.7
1219
+ [3.0.0-rc.6]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.5...v3.0.0-rc.6
1220
+ [3.0.0-rc.5]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.4...v3.0.0-rc.5
1221
+ [3.0.0-rc.4]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.3...v3.0.0-rc.4
1222
+ [3.0.0-rc.3]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.2...v3.0.0-rc.3
1223
+ [3.0.0-rc.2]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.1...v3.0.0-rc.2
1224
+ [3.0.0-rc.1]: https://github.com/kjanat/dreamcli/compare/v2.5.0...v3.0.0-rc.1
882
1225
  [2.5.0]: https://github.com/kjanat/dreamcli/compare/v2.4.1...v2.5.0
883
1226
  [2.4.1]: https://github.com/kjanat/dreamcli/compare/v2.4.0...v2.4.1
884
1227
  [2.4.0]: https://github.com/kjanat/dreamcli/compare/v2.3.0...v2.4.0
package/README.md CHANGED
@@ -76,7 +76,11 @@ const greet = command('greet')
76
76
  flag.number().default(1).describe('Repeat count'),
77
77
  )
78
78
  .action(({ args, flags, out }) => {
79
- for (let i = 0; i < flags.times; i++) {
79
+ const repeatCount = Number.isFinite(flags.times)
80
+ ? Math.max(0, Math.min(100, Math.floor(flags.times)))
81
+ : 1;
82
+
83
+ for (let i = 0; i < repeatCount; i++) {
80
84
  const msg = `Hello, ${args.name}!`;
81
85
  out.log(flags.loud ? msg.toUpperCase() : msg);
82
86
  }
@@ -531,7 +535,7 @@ expect(activity.activity).toContainEqual(
531
535
 
532
536
  ## Package structure
533
537
 
534
- Three subpath exports, each with a focused API surface:
538
+ The code lives behind three focused subpath exports:
535
539
 
536
540
  | Import | Purpose |
537
541
  | -------------------------- | -------------------------------------------------------------------------------------- |
@@ -539,6 +543,9 @@ Three subpath exports, each with a focused API surface:
539
543
  | `@kjanat/dreamcli/testkit` | `runCommand()`, `createCaptureOutput()`, `createTestPrompter()`, `createTestAdapter()` |
540
544
  | `@kjanat/dreamcli/runtime` | `createAdapter()`, `RuntimeAdapter`, runtime detection, platform adapters |
541
545
 
546
+ A fourth export, `@kjanat/dreamcli/schema`, ships the bundled JSON Schema (`dreamcli.schema.json`)
547
+ for editor and config validation.
548
+
542
549
  ESM-only. Source included in package (`src/`).
543
550
 
544
551
  ## Runtime support
@@ -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
  *
@@ -1 +1,205 @@
1
- import{buildFlagLookup as e,flagExpectsValue as t}from"../parse/index.mjs";function n(t,i,a=[],s=new Map){let c=-1;for(let e=0;e<t.length;e++){let n=t[e];if(n!==void 0){if(n===`--`){e+1<t.length&&(c=e+1);break}if(n.startsWith(`-`)){r(n,s)&&e++;continue}c=e;break}}if(c===-1)return{kind:`unknown`,input:``,candidates:o(i),parentPath:a};let l=t[c];if(l===void 0)return{kind:`unknown`,input:``,candidates:o(i),parentPath:a};let u=i.get(l);if(u===void 0)return{kind:`unknown`,input:l,candidates:o(i),parentPath:a};let d=[...t.slice(0,c),...t.slice(c+1)],f=[...a,u.schema];if(u.subcommands.size>0){let t=n(d,u.subcommands,f,e(u.schema.flags));switch(t.kind){case`match`:return t;case`unknown`:return t.input===``?u.schema.hasAction?{kind:`match`,command:u,commandPath:f,remainingArgv:d}:{kind:`needs-subcommand`,command:u,commandPath:f}:u.schema.hasAction?{kind:`match`,command:u,commandPath:f,remainingArgv:d}:t;case`needs-subcommand`:return t;default:return t}}return{kind:`match`,command:u,commandPath:f,remainingArgv:d}}function r(e,n){if(e.startsWith(`--`)){if(e.includes(`=`))return!1;let r=n.get(e.slice(2));return r!==void 0&&t(r[1])}let r=e.slice(1);for(let e=0;e<r.length;e++){let i=n.get(r.charAt(e));if(i===void 0)return!1;if(t(i[1]))return e===r.length-1}return!1}function i(e,t){let n=e.length,r=t.length,i=r+1,a=new Uint16Array(i),o=new Uint16Array(i);for(let e=0;e<=r;e++)a[e]=e;for(let i=1;i<=n;i++){o[0]=i;for(let n=1;n<=r;n++){let r=e.charAt(i-1)===t.charAt(n-1)?0:1,s=a[n]??0,c=o[n-1]??0,l=a[n-1]??0;o[n]=Math.min(s+1,c+1,l+r)}[a,o]=[o,a]}return a[r]??Math.max(n,r)}function a(e,t){let n,r=4;for(let a of t){let t=i(e,a.schema.name);t<r&&(r=t,n=a.schema.name);for(let t of a.schema.aliases){let o=i(e,t);o<r&&(r=o,n=a.schema.name)}}return r<=3?n:void 0}function o(e){let t=new Set,n=[];for(let r of e.values())t.has(r)||(t.add(r),n.push(r));return n}export{n as dispatch,a as findClosestCommand};
1
+ import { buildFlagLookup, flagExpectsValue } from "../parse/index.mjs";
2
+ //#region src/core/cli/dispatch.ts
3
+ /**
4
+ * Recursively walk argv, consuming command name segments from the front.
5
+ *
6
+ * At each level, the first non-flag token is tested as a command name
7
+ * against the provided command map. If matched and the matched command
8
+ * has subcommands, dispatch recurses into the child level with the
9
+ * remaining argv.
10
+ *
11
+ * Ambiguity resolution for commands that have both an action handler AND
12
+ * subcommands (e.g. `git remote` lists remotes, `git remote add` dispatches):
13
+ * - If the next token matches a subcommand → descend
14
+ * - If the next token is unknown and the command has a handler → match here
15
+ * - If the next token is unknown and no handler → propagate unknown error
16
+ * - If no next token and command has a handler → match here
17
+ * - If no next token and no handler → needs-subcommand
18
+ *
19
+ * @param argv - Remaining argv tokens (command names + flags + args).
20
+ * @param commands - Command map at the current tree level.
21
+ * @param ancestorPath - Schema path from root to current level (exclusive).
22
+ * @param valueFlags - Lookup of flags valid at this level, used so a
23
+ * space-separated value-flag's value (`--region eu`) is not mistaken for a
24
+ * command name. Empty by default (arity-unaware, legacy behaviour).
25
+ * @param parseOptions - Parser toggles (case parity) applied to descent-level
26
+ * flag lookups built inside dispatch.
27
+ * @returns Discriminated dispatch result.
28
+ *
29
+ * @internal
30
+ */
31
+ function dispatch(argv, commands, ancestorPath = [], valueFlags = /* @__PURE__ */ new Map(), parseOptions) {
32
+ let cmdIdx = -1;
33
+ for (let i = 0; i < argv.length; i++) {
34
+ const token = argv[i];
35
+ if (token === void 0) continue;
36
+ if (token === "--") {
37
+ if (i + 1 < argv.length) cmdIdx = i + 1;
38
+ break;
39
+ }
40
+ if (token.startsWith("-")) {
41
+ if (consumesFollowingToken(token, valueFlags)) i++;
42
+ continue;
43
+ }
44
+ cmdIdx = i;
45
+ break;
46
+ }
47
+ if (cmdIdx === -1) return {
48
+ kind: "unknown",
49
+ input: "",
50
+ candidates: uniqueCommands(commands),
51
+ parentPath: ancestorPath
52
+ };
53
+ const cmdName = argv[cmdIdx];
54
+ if (cmdName === void 0) return {
55
+ kind: "unknown",
56
+ input: "",
57
+ candidates: uniqueCommands(commands),
58
+ parentPath: ancestorPath
59
+ };
60
+ const matched = commands.get(cmdName);
61
+ if (matched === void 0) return {
62
+ kind: "unknown",
63
+ input: cmdName,
64
+ candidates: uniqueCommands(commands),
65
+ parentPath: ancestorPath
66
+ };
67
+ const remaining = [...argv.slice(0, cmdIdx), ...argv.slice(cmdIdx + 1)];
68
+ const currentPath = [...ancestorPath, matched.schema];
69
+ if (matched.subcommands.size > 0) {
70
+ const subResult = dispatch(remaining, matched.subcommands, currentPath, buildFlagLookup(matched.schema.flags, parseOptions), parseOptions);
71
+ switch (subResult.kind) {
72
+ case "match": return subResult;
73
+ case "unknown":
74
+ if (subResult.input === "") {
75
+ if (matched.schema.hasAction) return {
76
+ kind: "match",
77
+ command: matched,
78
+ commandPath: currentPath,
79
+ remainingArgv: remaining
80
+ };
81
+ return {
82
+ kind: "needs-subcommand",
83
+ command: matched,
84
+ commandPath: currentPath
85
+ };
86
+ }
87
+ if (matched.schema.hasAction) return {
88
+ kind: "match",
89
+ command: matched,
90
+ commandPath: currentPath,
91
+ remainingArgv: remaining
92
+ };
93
+ return subResult;
94
+ case "needs-subcommand": return subResult;
95
+ default: return subResult;
96
+ }
97
+ }
98
+ return {
99
+ kind: "match",
100
+ command: matched,
101
+ commandPath: currentPath,
102
+ remainingArgv: remaining
103
+ };
104
+ }
105
+ /**
106
+ * Whether a flag token consumes the following argv token as its value.
107
+ *
108
+ * Mirrors the parser's value-consumption rules (`parseLongFlag` /
109
+ * `parseShortFlags`) so the command-name scan skips exactly the tokens the
110
+ * parser would treat as flag values:
111
+ * - `--flag value` → consumes when `--flag` is a known value-flag.
112
+ * - `--flag=value` → self-contained, consumes nothing.
113
+ * - `-abc value` → consumes only when the trailing short flag is a value-flag;
114
+ * an earlier value-flag char takes the rest of the group as an inline value.
115
+ *
116
+ * Unknown flags conservatively consume nothing (the parser reports them later).
117
+ *
118
+ * @internal
119
+ */
120
+ function consumesFollowingToken(token, valueFlags) {
121
+ if (token.startsWith("--")) {
122
+ if (token.includes("=")) return false;
123
+ const entry = valueFlags.get(token.slice(2));
124
+ return entry !== void 0 && flagExpectsValue(entry.schema);
125
+ }
126
+ const chars = token.slice(1);
127
+ for (let i = 0; i < chars.length; i++) {
128
+ const entry = valueFlags.get(chars.charAt(i));
129
+ if (entry === void 0) return false;
130
+ if (!flagExpectsValue(entry.schema)) continue;
131
+ return i === chars.length - 1;
132
+ }
133
+ return false;
134
+ }
135
+ /**
136
+ * Levenshtein distance between two strings.
137
+ * @internal
138
+ */
139
+ function levenshtein(a, b) {
140
+ const m = a.length;
141
+ const n = b.length;
142
+ const w = n + 1;
143
+ let prev = new Uint16Array(w);
144
+ let curr = new Uint16Array(w);
145
+ for (let j = 0; j <= n; j++) prev[j] = j;
146
+ for (let i = 1; i <= m; i++) {
147
+ curr[0] = i;
148
+ for (let j = 1; j <= n; j++) {
149
+ const cost = a.charAt(i - 1) === b.charAt(j - 1) ? 0 : 1;
150
+ const del = prev[j] ?? 0;
151
+ const ins = curr[j - 1] ?? 0;
152
+ const sub = prev[j - 1] ?? 0;
153
+ curr[j] = Math.min(del + 1, ins + 1, sub + cost);
154
+ }
155
+ [prev, curr] = [curr, prev];
156
+ }
157
+ return prev[n] ?? Math.max(m, n);
158
+ }
159
+ /**
160
+ * Find the closest command name match for a "did you mean?" suggestion.
161
+ *
162
+ * Searches command names and aliases. Returns `undefined` if no
163
+ * sufficiently close match exists (threshold: 3).
164
+ *
165
+ * @internal
166
+ */
167
+ function findClosestCommand(input, commands) {
168
+ const MAX_DISTANCE = 3;
169
+ let bestName;
170
+ let bestDist = 4;
171
+ for (const cmd of commands) {
172
+ const nameDist = levenshtein(input, cmd.schema.name);
173
+ if (nameDist < bestDist) {
174
+ bestDist = nameDist;
175
+ bestName = cmd.schema.name;
176
+ }
177
+ for (const alias of cmd.schema.aliases) {
178
+ const aliasDist = levenshtein(input, alias);
179
+ if (aliasDist < bestDist) {
180
+ bestDist = aliasDist;
181
+ bestName = cmd.schema.name;
182
+ }
183
+ }
184
+ }
185
+ return bestDist <= MAX_DISTANCE ? bestName : void 0;
186
+ }
187
+ /**
188
+ * Deduplicate commands from a name+alias map.
189
+ *
190
+ * A map keyed by name *and* alias contains duplicate entries for aliased
191
+ * commands. This returns unique commands (by schema identity).
192
+ *
193
+ * @internal
194
+ */
195
+ function uniqueCommands(commands) {
196
+ const seen = /* @__PURE__ */ new Set();
197
+ const result = [];
198
+ for (const cmd of commands.values()) if (!seen.has(cmd)) {
199
+ seen.add(cmd);
200
+ result.push(cmd);
201
+ }
202
+ return result;
203
+ }
204
+ //#endregion
205
+ 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.