@kjanat/dreamcli 3.0.0-rc.1 → 3.0.0-rc.11

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 (194) hide show
  1. package/CHANGELOG.md +227 -1
  2. package/dist/core/cli/dispatch.d.mts +6 -5
  3. package/dist/core/cli/dispatch.mjs +205 -1
  4. package/dist/core/cli/help-links.d.mts +0 -1
  5. package/dist/core/cli/help-links.mjs +41 -1
  6. package/dist/core/cli/index.d.mts +81 -8
  7. package/dist/core/cli/index.mjs +945 -1
  8. package/dist/core/cli/planner.d.mts +5 -1
  9. package/dist/core/cli/planner.mjs +300 -1
  10. package/dist/core/cli/plugin.d.mts +1 -1
  11. package/dist/core/cli/plugin.mjs +41 -1
  12. package/dist/core/cli/propagate.d.mts +1 -1
  13. package/dist/core/cli/propagate.mjs +57 -1
  14. package/dist/core/cli/root-help.d.mts +2 -1
  15. package/dist/core/cli/root-help.mjs +226 -4
  16. package/dist/core/cli/root-surface.d.mts +12 -1
  17. package/dist/core/cli/root-surface.mjs +28 -1
  18. package/dist/core/cli/runtime-preflight.d.mts +14 -2
  19. package/dist/core/cli/runtime-preflight.mjs +169 -1
  20. package/dist/core/completion/index.d.mts +0 -1
  21. package/dist/core/completion/index.mjs +90 -1
  22. package/dist/core/completion/shells/bash.d.mts +0 -1
  23. package/dist/core/completion/shells/bash.mjs +308 -3
  24. package/dist/core/completion/shells/fish.d.mts +0 -1
  25. package/dist/core/completion/shells/fish.mjs +162 -2
  26. package/dist/core/completion/shells/powershell.d.mts +0 -1
  27. package/dist/core/completion/shells/powershell.mjs +358 -2
  28. package/dist/core/completion/shells/shared.d.mts +13 -2
  29. package/dist/core/completion/shells/shared.mjs +176 -1
  30. package/dist/core/completion/shells/zsh.d.mts +0 -1
  31. package/dist/core/completion/shells/zsh.mjs +251 -2
  32. package/dist/core/config/index.d.mts +2 -3
  33. package/dist/core/config/index.mjs +246 -1
  34. package/dist/core/config/package-json.d.mts +27 -4
  35. package/dist/core/config/package-json.mjs +386 -3
  36. package/dist/core/errors/index.d.mts +3 -3
  37. package/dist/core/errors/index.mjs +87 -1
  38. package/dist/core/execution/index.d.mts +0 -1
  39. package/dist/core/execution/index.mjs +201 -1
  40. package/dist/core/help/ansi.d.mts +11 -5
  41. package/dist/core/help/ansi.mjs +121 -2
  42. package/dist/core/help/index.d.mts +22 -3
  43. package/dist/core/help/index.mjs +341 -7
  44. package/dist/core/help/theme.d.mts +68 -0
  45. package/dist/core/help/theme.mjs +46 -0
  46. package/dist/core/json-schema/index.d.mts +15 -2
  47. package/dist/core/json-schema/index.mjs +536 -12
  48. package/dist/core/json-schema/meta-descriptions.generated.d.mts +55 -38
  49. package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
  50. package/dist/core/output/activity.d.mts +0 -1
  51. package/dist/core/output/activity.mjs +452 -1
  52. package/dist/core/output/bind.mjs +56 -1
  53. package/dist/core/output/contracts.d.mts +4 -5
  54. package/dist/core/output/contracts.mjs +57 -1
  55. package/dist/core/output/display-value.mjs +32 -1
  56. package/dist/core/output/index.d.mts +21 -1
  57. package/dist/core/output/index.mjs +442 -2
  58. package/dist/core/output/renderers.d.mts +0 -1
  59. package/dist/core/output/renderers.mjs +46 -1
  60. package/dist/core/output/writer.mjs +12 -1
  61. package/dist/core/parse/index.d.mts +40 -7
  62. package/dist/core/parse/index.mjs +727 -1
  63. package/dist/core/prompt/index.d.mts +1 -1
  64. package/dist/core/prompt/index.mjs +348 -6
  65. package/dist/core/resolve/args.d.mts +1 -1
  66. package/dist/core/resolve/args.mjs +105 -1
  67. package/dist/core/resolve/coerce.d.mts +1 -1
  68. package/dist/core/resolve/coerce.mjs +336 -1
  69. package/dist/core/resolve/config.mjs +19 -1
  70. package/dist/core/resolve/contracts.d.mts +9 -4
  71. package/dist/core/resolve/errors.d.mts +0 -1
  72. package/dist/core/resolve/errors.mjs +140 -2
  73. package/dist/core/resolve/flags.d.mts +7 -2
  74. package/dist/core/resolve/flags.mjs +251 -1
  75. package/dist/core/resolve/index.d.mts +2 -2
  76. package/dist/core/resolve/index.mjs +85 -1
  77. package/dist/core/resolve/property.d.mts +4 -2
  78. package/dist/core/resolve/property.mjs +53 -1
  79. package/dist/core/schema/activity.d.mts +31 -11
  80. package/dist/core/schema/arg.d.mts +3 -4
  81. package/dist/core/schema/arg.mjs +463 -1
  82. package/dist/core/schema/command.d.mts +26 -6
  83. package/dist/core/schema/command.mjs +726 -1
  84. package/dist/core/schema/flag.d.mts +485 -19
  85. package/dist/core/schema/flag.mjs +705 -1
  86. package/dist/core/schema/index.d.mts +4 -2
  87. package/dist/core/schema/middleware.d.mts +4 -3
  88. package/dist/core/schema/middleware.mjs +41 -1
  89. package/dist/core/schema/number-constraints.mjs +60 -1
  90. package/dist/core/schema/prompt.d.mts +6 -3
  91. package/dist/core/schema/run.d.mts +20 -1
  92. package/dist/core/schema/string-constraints.d.mts +97 -0
  93. package/dist/core/schema/string-constraints.mjs +69 -0
  94. package/dist/core/schema/value-parsers.d.mts +78 -0
  95. package/dist/core/schema/value-parsers.mjs +142 -0
  96. package/dist/core/schema-dsl/runtime.mjs +271 -2
  97. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  98. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  99. package/dist/core/testkit/index.d.mts +0 -31
  100. package/dist/core/testkit/index.mjs +83 -1
  101. package/dist/index.d.mts +11 -6
  102. package/dist/index.mjs +22 -1
  103. package/dist/runtime/adapter.d.mts +38 -2
  104. package/dist/runtime/adapter.mjs +87 -1
  105. package/dist/runtime/auto.d.mts +2 -3
  106. package/dist/runtime/auto.mjs +45 -1
  107. package/dist/runtime/deno.d.mts +24 -5
  108. package/dist/runtime/deno.mjs +262 -2
  109. package/dist/runtime/detect.mjs +45 -1
  110. package/dist/runtime/index.d.mts +3 -4
  111. package/dist/runtime/node.d.mts +8 -2
  112. package/dist/runtime/node.mjs +220 -2
  113. package/dist/runtime/paths.mjs +48 -1
  114. package/dist/runtime.d.mts +4 -4
  115. package/dist/runtime.mjs +6 -1
  116. package/dist/strings.mjs +22 -1
  117. package/dist/testkit.d.mts +1 -0
  118. package/dist/testkit.mjs +5 -1
  119. package/dist/version.d.mts +7 -3
  120. package/dist/version.mjs +7 -1
  121. package/dreamcli.schema.json +36 -7
  122. package/package.json +45 -42
  123. package/dist/runtime/bun.d.mts +0 -28
  124. package/dist/runtime/bun.mjs +0 -1
  125. package/src/core/cli/dispatch.ts +0 -355
  126. package/src/core/cli/help-links.ts +0 -82
  127. package/src/core/cli/index.ts +0 -1614
  128. package/src/core/cli/planner.ts +0 -656
  129. package/src/core/cli/plugin.ts +0 -117
  130. package/src/core/cli/propagate.ts +0 -97
  131. package/src/core/cli/root-help.ts +0 -342
  132. package/src/core/cli/root-surface.ts +0 -87
  133. package/src/core/cli/runtime-preflight.ts +0 -456
  134. package/src/core/completion/index.ts +0 -138
  135. package/src/core/completion/shells/bash.ts +0 -459
  136. package/src/core/completion/shells/fish.ts +0 -259
  137. package/src/core/completion/shells/powershell.ts +0 -439
  138. package/src/core/completion/shells/shared.ts +0 -310
  139. package/src/core/completion/shells/zsh.ts +0 -381
  140. package/src/core/config/index.ts +0 -417
  141. package/src/core/config/package-json.ts +0 -560
  142. package/src/core/errors/index.ts +0 -193
  143. package/src/core/execution/index.ts +0 -265
  144. package/src/core/help/ansi.ts +0 -144
  145. package/src/core/help/index.ts +0 -563
  146. package/src/core/json-schema/index.ts +0 -910
  147. package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
  148. package/src/core/output/activity.ts +0 -575
  149. package/src/core/output/bind.ts +0 -59
  150. package/src/core/output/contracts.ts +0 -194
  151. package/src/core/output/display-value.ts +0 -48
  152. package/src/core/output/index.ts +0 -704
  153. package/src/core/output/renderers.ts +0 -125
  154. package/src/core/output/writer.ts +0 -46
  155. package/src/core/parse/index.ts +0 -742
  156. package/src/core/prompt/index.ts +0 -623
  157. package/src/core/resolve/args.ts +0 -144
  158. package/src/core/resolve/coerce.ts +0 -500
  159. package/src/core/resolve/config.ts +0 -26
  160. package/src/core/resolve/contracts.ts +0 -135
  161. package/src/core/resolve/errors.ts +0 -227
  162. package/src/core/resolve/flags.ts +0 -269
  163. package/src/core/resolve/index.ts +0 -108
  164. package/src/core/resolve/property.ts +0 -99
  165. package/src/core/schema/activity.ts +0 -240
  166. package/src/core/schema/arg.ts +0 -841
  167. package/src/core/schema/command.ts +0 -1500
  168. package/src/core/schema/flag.ts +0 -917
  169. package/src/core/schema/index.ts +0 -96
  170. package/src/core/schema/middleware.ts +0 -171
  171. package/src/core/schema/number-constraints.ts +0 -153
  172. package/src/core/schema/prompt.ts +0 -171
  173. package/src/core/schema/run.ts +0 -198
  174. package/src/core/schema-dsl/index.ts +0 -109
  175. package/src/core/schema-dsl/parse.ts +0 -262
  176. package/src/core/schema-dsl/runtime.ts +0 -609
  177. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  178. package/src/core/testkit/index.ts +0 -147
  179. package/src/index.ts +0 -181
  180. package/src/runtime/adapter.ts +0 -303
  181. package/src/runtime/auto.ts +0 -86
  182. package/src/runtime/bun.ts +0 -48
  183. package/src/runtime/deno.ts +0 -367
  184. package/src/runtime/detect.ts +0 -105
  185. package/src/runtime/index.ts +0 -21
  186. package/src/runtime/node-builtins.d.ts +0 -27
  187. package/src/runtime/node.ts +0 -289
  188. package/src/runtime/paths.ts +0 -64
  189. package/src/runtime/support.ts +0 -77
  190. package/src/runtime.ts +0 -31
  191. package/src/schema.ts +0 -16
  192. package/src/strings.ts +0 -34
  193. package/src/testkit.ts +0 -25
  194. package/src/version.ts +0 -20
package/CHANGELOG.md CHANGED
@@ -7,6 +7,222 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [3.0.0-rc.11] - 2026-07-15
11
+
12
+ ### Fixed
13
+
14
+ - **JSR publish** — the Deno import map pinned `ansispeck` below `0.2.0`,
15
+ so the JSR build resolved an ansispeck whose `createColors` rejected
16
+ `osc8`'s two-argument call and failed type checking. The map now tracks
17
+ `^0.2.0` alongside the npm dependency. (rc.10 published to npm only.)
18
+
19
+ ## [3.0.0-rc.10] - 2026-07-15
20
+
21
+ ### Changed
22
+
23
+ - **`osc8()` link text is optional** — it now defaults to the link target, so
24
+ `osc8('https://x.dev')` renders as a hyperlink displaying its own URL.
25
+ Terminals without OSC 8 support still show a usable address. Passing an
26
+ explicit label is unchanged.
27
+ - **`osc8()` now delegates to `ansispeck`'s hyperlink constructor** — it emits
28
+ the **ST** (`ESC \`) terminator instead of **BEL** (`\x07`). Both are valid
29
+ OSC 8 terminators supported by modern terminals; the rendered link is
30
+ unchanged. This removes dreamcli's last hand-rolled escape-sequence code.
31
+
32
+ ## [3.0.0-rc.9] - 2026-07-11
33
+
34
+ ### Added
35
+
36
+ - **JSON help** — `--help` with `--json` emits the CLI's definition document
37
+ (the `generateSchema()` shape, `$schema`-tagged) on stdout instead of help
38
+ text, for root help, `help <command>`, and `<command> --help` alike. New
39
+ `generateCommandSchema(schema)` export produces the per-command document.
40
+
41
+ ### Changed
42
+
43
+ - **`generateSchema()` emits the default command's full definition** — the
44
+ `defaultCommand` field was a name-only string reference while the default
45
+ command's flags/args appeared nowhere in the document (it never lists in
46
+ `commands`). It is now the complete serialized command.
47
+
48
+ - **`flag.array()` rejects non-element builders at compile time** — the
49
+ element position now requires a builder carrying only value-shape settings
50
+ (kind, constraints, enum values, `parseFn`). Flag-level modifiers
51
+ (`.alias()`, `.env()`, `.default()`, `.prompt()`, `.describe()`, …) were
52
+ silently ignored on elements before; passing them is now a type error, as
53
+ is `flag.path()` / `flag.count()` / `flag.keyValue()` / nested arrays.
54
+ Type-level only — no runtime behavior change.
55
+
56
+ ## [3.0.0-rc.8] - 2026-07-11
57
+
58
+ ### Added
59
+
60
+ - **Themed help output** — root and per-command help render with a semantic
61
+ color theme (bold+underlined section titles, cyan literals, dimmed metadata,
62
+ yellow deprecations) whenever color is enabled, using the same gate as
63
+ `out.color` (TTY + color support, no `--json`, `NO_COLOR`/`FORCE_COLOR`
64
+ honored). Piped and JSON output stays byte-clean. Customize via
65
+ `.help({ theme: (c) => ({ sectionTitle: c.magenta }) })` — the factory
66
+ receives the gated ansispeck palette and is never invoked when color is off,
67
+ so custom themes cannot leak escapes. New public types: `HelpTheme`,
68
+ `HelpThemeFactory`.
69
+ - **Negatable booleans** — `flag.boolean().negatable()` accepts `--no-<name>`
70
+ as `false`. Both spellings are one logical flag (last CLI occurrence wins,
71
+ shared duplicate policy); the negated spelling is presence-only
72
+ (`--no-foo=x` errors) and renders as `--[no-]foo` in help. Custom spelling
73
+ via `{ alias }`, unadvertised via `{ hidden }`. Env/config/prompt/default
74
+ resolution is unchanged.
75
+ - **Duplicate policy** — `.duplicates('last' | 'first' | 'error')` on
76
+ singleton flags controls repeated CLI occurrences. `'error'` throws
77
+ `ParseError` code `DUPLICATE_FLAG` with `{ flag, count, values }` details;
78
+ `'first'` keeps the first value while still consuming later value tokens.
79
+ Counted per logical flag (aliases + negated + parity spellings); env/config
80
+ precedence is never a duplicate.
81
+ - **`packageRepositoryUrl(pkg, { require: true })`** — narrows the return
82
+ type to `string`, throwing a `CLIError` (code `INVALID_REPOSITORY`) at the
83
+ call site when the `repository` field is missing or not a recognisable
84
+ locator. Removes the `!` assertion for manifests known to carry a valid
85
+ repository, with the guarantee enforced at runtime rather than assumed.
86
+ - **Flag spelling parity (kebab ↔ camel)** — `--doThis` matches a flag named
87
+ `do-this` and vice versa, for names and long aliases, on by default.
88
+ Handler keys, help, completions, and suggestions stay canonical.
89
+ Automatically disabled per pair when both spellings are declared explicitly;
90
+ globally via `cli('mycli', { flags: { caseParity: false } })` (new
91
+ `cli(name, options)` overload) or `RunOptions.flags`.
92
+
93
+ ### Fixed
94
+
95
+ - `execute(argv, { flags })` overrides now reach the planner's dispatch arity
96
+ scanning, not just command parsing.
97
+ - Generated meta-schema descriptions render `@defaultValue` tags as a
98
+ `Default: <value>` paragraph instead of silently dropping them.
99
+
100
+ ## [3.0.0-rc.7] - 2026-07-10
101
+
102
+ ### Added
103
+
104
+ - **`.derive()` handlers may omit the return** — a validation-only derive with
105
+ no `return` statement (sync or async) now typechecks; previously `void` /
106
+ `Promise<void>` failed the `Output` constraint and forced an explicit
107
+ `return undefined`.
108
+ - **String constraints** — `flag.string({ nonEmpty, minLength, maxLength, pattern })`
109
+ plus chained `.nonEmpty()` / `.minLength()` / `.maxLength()` / `.pattern()`,
110
+ mirroring the numeric-constraint model. Checked in fixed order
111
+ (nonEmpty → minLength → maxLength → pattern) at both the CLI parse boundary
112
+ (`INVALID_VALUE`) and env/config/prompt resolution (`CONSTRAINT_VIOLATED`),
113
+ and emitted into the exported JSON Schema as `minLength` / `maxLength` /
114
+ `pattern`.
115
+ - **`.separator()` and `.unique()` on array flags** — `.separator(',')` splits
116
+ each CLI occurrence before element coercion, so `--region us,eu --region ap`
117
+ works alongside repetition and errors name the offending element. Env/config
118
+ string values use the same separator (default remains `','`). `.unique()`
119
+ deduplicates the final resolved array (first-seen order) regardless of
120
+ source.
121
+ - **`flag.url()`** — parses into a `URL`, with optional
122
+ `{ protocols: ['https'] }` allowlist. Help shows `<url>`.
123
+ - **`flag.path()`** — path string with opt-in filesystem checks
124
+ (`{ mustExist: true }`, `{ type: 'file' | 'directory' }`) validated after
125
+ resolution through the runtime adapter, so CLI/env/config values are checked
126
+ identically. `RuntimeAdapter` gained a `stat()` primitive (Node/Bun via
127
+ `node:fs/promises`, Deno via `Deno.stat`; test adapters default to "nothing
128
+ exists"), and `RunOptions` / `ResolveOptions` accept a `stat` injection for
129
+ process-free execution — without one, checks are skipped.
130
+ - **`flag.date()`** — strict ISO-8601 → `Date` with optional inclusive
131
+ `min` / `max` bounds. Rejects lenient `Date.parse` inputs (`'0'`,
132
+ `'March 5'`) and calendar-invalid dates (`2026-02-31`).
133
+ - **`flag.duration()`** — `'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`,
134
+ compounds (`'1h30m'`), or bare milliseconds → milliseconds.
135
+ - **`flag.bytes()`** — `'512mb'`, `'1.5gb'`, `'64kb'` or bare bytes → bytes
136
+ (binary units, case-insensitive).
137
+ - **`flag.count()`** — occurrence counter (`-vvv` → `3`, absent → `0`,
138
+ explicit `--verbose=2` supported). Takes no value token, not promptable,
139
+ and joins boolean flags in help (no `<value>` placeholder) and shell
140
+ completions.
141
+ - **`flag.keyValue()`** — repeated `KEY=VALUE` merges into
142
+ `Record<string, string>` (split at the first `=`, later keys win, unset
143
+ resolves to `{}`). Env accepts comma-separated pairs; config accepts a plain
144
+ object. New `'empty-object'` optional fallback joins arrays' `[]` as the
145
+ kinds that resolve to a value when unset.
146
+
147
+ ## [3.0.0-rc.6] - 2026-07-09
148
+
149
+ ### Added
150
+
151
+ - **Runtime terminal sizing hooks** — `RuntimeAdapter` now exposes
152
+ `getTerminalSize()` and `onTerminalResize()`. Node/Bun read
153
+ `process.stdout.getWindowSize()` (falling back to `columns` / `rows`) and
154
+ subscribe to stdout `resize`; Deno uses native `Deno.consoleSize()` and
155
+ `SIGWINCH` on non-Windows platforms.
156
+
157
+ ### Changed
158
+
159
+ - **Help output now fits the live terminal in `.run()`** — root and command help
160
+ use runtime terminal columns when no explicit `.help({ width })` or runtime
161
+ `help.width` is provided. Non-TTY or unavailable sizes still fall back to 80,
162
+ and `.execute()` remains deterministic for tests.
163
+
164
+ ## [3.0.0-rc.5] - 2026-07-08
165
+
166
+ ### Removed
167
+
168
+ - **`createBunAdapter` export** (from `@kjanat/dreamcli/runtime`). Bun exposes a
169
+ Node-compatible `process`, so the Bun adapter had been a pure passthrough to
170
+ the Node adapter since the runtime version hard-fail was dropped — it blessed
171
+ a runtime rather than abstracting distinct I/O. Auto-detection now maps Bun to
172
+ the Node adapter directly and `src/runtime/bun.ts` is gone. Runtime detection
173
+ is unchanged: `detectRuntime()` still reports `'bun'` and `RUNTIMES` still
174
+ lists it. Callers that selected the Bun adapter explicitly should use
175
+ `createNodeAdapter` (identical behavior) or rely on `createAdapter()`
176
+ auto-detection (#51).
177
+
178
+ ## [3.0.0-rc.4] - 2026-07-06
179
+
180
+ ### Added
181
+
182
+ - **`.default(cmd, { route: true })`** — expose a default command under its own
183
+ name as a routable top-level command, in addition to the bare/flags-only root
184
+ surface. `mycli` and `mycli <name>` then run the same command object, and it
185
+ is listed in the root `Commands:` section (tagged `(default)`) beside its
186
+ siblings. Lets CLIs keep both a short root shorthand and an explicit,
187
+ documented named command without duplicating the builder (#55). Opt-in only
188
+ — the surface-only default remains the default behavior. With `route: true`
189
+ the name wins over positional interpretation, so a positional value equal to
190
+ the command's own name must be passed after `--`.
191
+
192
+ ## [3.0.0-rc.3] - 2026-07-06
193
+
194
+ ### Added
195
+
196
+ - **`@kjanat/dreamcli/version` subpath** — exposes the framework's own build
197
+ identity as `DREAMCLI_VERSION` and `DREAMCLI_REVISION` (git short SHA) for
198
+ diagnostics and bug reports. Deliberately a subpath rather than root exports
199
+ so the constants stay out of root-import IDE completions; both report
200
+ `'dev'` when running unbundled source.
201
+
202
+ ## [3.0.0-rc.2] - 2026-07-06
203
+
204
+ ### Added
205
+
206
+ - **`out.color` — context-aware ANSI colors** — every handler's `out` now carries
207
+ a color palette powered by [`ansispeck`](https://github.com/kjanat/ansispeck).
208
+ Colors auto-enable only when stdout is a TTY, JSON mode is off, and the
209
+ environment supports color (`NO_COLOR`, `FORCE_COLOR`, `--no-color`, `--color`,
210
+ `CI` respected); otherwise every formatter is an identity function, so handlers
211
+ can write `out.log(out.color.green('✔ done'))` unconditionally.
212
+ `createOutput({ color })` forces the palette on/off (useful for asserting
213
+ colored output in tests), and the `Colors` type is re-exported from the root
214
+ entrypoint. First runtime dependency — kept external in `dist` (~1 kB gzipped
215
+ install).
216
+
217
+ ### Changed
218
+
219
+ - **npm package now resolves built `dist` on every runtime** — the `bun`/`deno`
220
+ → `src/*.ts` export conditions are gone and `src` is no longer published to
221
+ npm (JSR still ships source). Bun and Deno consumers previously loaded raw
222
+ source where build-time defines never ran, so `version` reported `'dev'`;
223
+ they now get the same tested output as Node, with the real version. The
224
+ export map is generated by tsdown at build time instead of hand-maintained.
225
+
10
226
  ## [3.0.0-rc.1] - 2026-07-02
11
227
 
12
228
  ### Added
@@ -1004,7 +1220,17 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
1004
1220
  - MIT License.
1005
1221
  - Markdownlint configuration.
1006
1222
 
1007
- [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.1...HEAD
1223
+ [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.11...HEAD
1224
+ [3.0.0-rc.11]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.10...v3.0.0-rc.11
1225
+ [3.0.0-rc.10]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.9...v3.0.0-rc.10
1226
+ [3.0.0-rc.9]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.8...v3.0.0-rc.9
1227
+ [3.0.0-rc.8]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.7...v3.0.0-rc.8
1228
+ [3.0.0-rc.7]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.6...v3.0.0-rc.7
1229
+ [3.0.0-rc.6]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.5...v3.0.0-rc.6
1230
+ [3.0.0-rc.5]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.4...v3.0.0-rc.5
1231
+ [3.0.0-rc.4]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.3...v3.0.0-rc.4
1232
+ [3.0.0-rc.3]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.2...v3.0.0-rc.3
1233
+ [3.0.0-rc.2]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.1...v3.0.0-rc.2
1008
1234
  [3.0.0-rc.1]: https://github.com/kjanat/dreamcli/compare/v2.5.0...v3.0.0-rc.1
1009
1235
  [2.5.0]: https://github.com/kjanat/dreamcli/compare/v2.4.1...v2.5.0
1010
1236
  [2.4.1]: https://github.com/kjanat/dreamcli/compare/v2.4.0...v2.4.1
@@ -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.
@@ -1 +1,41 @@
1
- import{packageRepositoryUrl as e}from"../config/package-json.mjs";function t(e,t){let n;try{n=new URL(e).hostname}catch{return}if(n===`github.com`)return`${e}/releases/tag/v${t}`;if(n===`gitlab.com`)return`${e}/-/releases/v${t}`}function n(n,r,i){if(n===void 0)return;if(r===void 0||n.name!==void 0&&n.version!==void 0)return n;let a=e(r);return{name:n.name??a??r.homepage,version:n.version??(a!==void 0&&i!==void 0?t(a,i):void 0)}}export{n as deriveHelpLinks};
1
+ import { packageRepositoryUrl } from "../config/package-json.mjs";
2
+ //#region src/core/cli/help-links.ts
3
+ /**
4
+ * Build the release-tag URL for a version on a known forge.
5
+ *
6
+ * GitHub and GitLab have stable release-tag routes; other hosts return
7
+ * `undefined` rather than guessing.
8
+ *
9
+ * @internal
10
+ */
11
+ function releaseTagUrl(repoUrl, version) {
12
+ let hostname;
13
+ try {
14
+ hostname = new URL(repoUrl).hostname;
15
+ } catch {
16
+ return;
17
+ }
18
+ if (hostname === "github.com") return `${repoUrl}/releases/tag/v${version}`;
19
+ if (hostname === "gitlab.com") return `${repoUrl}/-/releases/v${version}`;
20
+ }
21
+ /**
22
+ * Fill `undefined` link fields from package.json metadata.
23
+ *
24
+ * Explicit URLs always win. The name falls back to the normalized
25
+ * `repository` URL, then `homepage`; the version falls back to the forge
26
+ * release-tag URL when both a repository and a version are known.
27
+ * Idempotent — already-resolved fields pass through unchanged.
28
+ *
29
+ * @internal
30
+ */
31
+ function deriveHelpLinks(links, pkg, version) {
32
+ if (links === void 0) return void 0;
33
+ if (pkg === void 0 || links.name !== void 0 && links.version !== void 0) return links;
34
+ const repoUrl = packageRepositoryUrl(pkg);
35
+ return {
36
+ name: links.name ?? repoUrl ?? pkg.homepage,
37
+ version: links.version ?? (repoUrl !== void 0 && version !== void 0 ? releaseTagUrl(repoUrl, version) : void 0)
38
+ };
39
+ }
40
+ //#endregion
41
+ export { deriveHelpLinks };