@kjanat/dreamcli 3.0.0-rc.1 → 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 (194) hide show
  1. package/CHANGELOG.md +217 -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,213 @@ 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
+
10
217
  ## [3.0.0-rc.1] - 2026-07-02
11
218
 
12
219
  ### Added
@@ -1004,7 +1211,16 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
1004
1211
  - MIT License.
1005
1212
  - Markdownlint configuration.
1006
1213
 
1007
- [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.1...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
1008
1224
  [3.0.0-rc.1]: https://github.com/kjanat/dreamcli/compare/v2.5.0...v3.0.0-rc.1
1009
1225
  [2.5.0]: https://github.com/kjanat/dreamcli/compare/v2.4.1...v2.5.0
1010
1226
  [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 };