@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
@@ -1,355 +0,0 @@
1
- /**
2
- * Recursive command dispatch for nested command trees.
3
- *
4
- * Walks argv segments, matching command names at each level of the tree.
5
- * Returns a discriminated union describing the dispatch outcome: a matched
6
- * command with its ancestor path, a group that needs a subcommand, or an
7
- * unknown command with suggestion candidates.
8
- *
9
- * @module dreamcli/core/cli/dispatch
10
- * @internal
11
- */
12
-
13
- import { buildFlagLookup, flagExpectsValue } from '#internals/core/parse/index.ts';
14
- import type { CommandSchema, ErasedCommand } from '#internals/core/schema/command.ts';
15
- import type { FlagSchema } from '#internals/core/schema/flag.ts';
16
-
17
- /**
18
- * Flag lookup (name/alias → `[canonicalName, schema]`) used to make the
19
- * command-name scan aware of value-flag arity. Built from the flags valid at
20
- * the current dispatch level via {@link buildFlagLookup}.
21
- *
22
- * @internal
23
- */
24
- type ValueFlagLookup = ReadonlyMap<string, readonly [name: string, schema: FlagSchema]>;
25
-
26
- // --- Dispatch result types (discriminated union)
27
-
28
- /** Successful dispatch — target command found with argv path. */
29
- interface DispatchMatch {
30
- /** Discriminant — a command name in argv matched a registered command. */
31
- readonly kind: 'match';
32
- /** The matched (target) command. */
33
- readonly command: ErasedCommand;
34
- /** Root → target (inclusive). Used for `collectPropagatedFlags()`. */
35
- readonly commandPath: readonly CommandSchema[];
36
- /** argv after consuming command name segments. */
37
- readonly remainingArgv: readonly string[];
38
- }
39
-
40
- /** Target has subcommands but no handler and no subcommand was specified/matched. */
41
- interface DispatchNeedsSubcommand {
42
- /** Discriminant — command group reached without a subcommand or handler. */
43
- readonly kind: 'needs-subcommand';
44
- /** The group command that needs a subcommand. */
45
- readonly command: ErasedCommand;
46
- /** Root → group (inclusive). */
47
- readonly commandPath: readonly CommandSchema[];
48
- }
49
-
50
- /** Unknown command name at this dispatch level. */
51
- interface DispatchUnknown {
52
- /** Discriminant — no registered command matched the input token. */
53
- readonly kind: 'unknown';
54
- /** The unrecognised input token. Empty string when no token present. */
55
- readonly input: string;
56
- /** Commands available at the level where matching failed. */
57
- readonly candidates: readonly ErasedCommand[];
58
- /** Ancestor path up to (but not including) the unknown level. */
59
- readonly parentPath: readonly CommandSchema[];
60
- }
61
-
62
- /** Discriminated result of recursive command dispatch. */
63
- type DispatchResult = DispatchMatch | DispatchNeedsSubcommand | DispatchUnknown;
64
-
65
- // --- Recursive dispatch
66
-
67
- /**
68
- * Recursively walk argv, consuming command name segments from the front.
69
- *
70
- * At each level, the first non-flag token is tested as a command name
71
- * against the provided command map. If matched and the matched command
72
- * has subcommands, dispatch recurses into the child level with the
73
- * remaining argv.
74
- *
75
- * Ambiguity resolution for commands that have both an action handler AND
76
- * subcommands (e.g. `git remote` lists remotes, `git remote add` dispatches):
77
- * - If the next token matches a subcommand → descend
78
- * - If the next token is unknown and the command has a handler → match here
79
- * - If the next token is unknown and no handler → propagate unknown error
80
- * - If no next token and command has a handler → match here
81
- * - If no next token and no handler → needs-subcommand
82
- *
83
- * @param argv - Remaining argv tokens (command names + flags + args).
84
- * @param commands - Command map at the current tree level.
85
- * @param ancestorPath - Schema path from root to current level (exclusive).
86
- * @param valueFlags - Lookup of flags valid at this level, used so a
87
- * space-separated value-flag's value (`--region eu`) is not mistaken for a
88
- * command name. Empty by default (arity-unaware, legacy behaviour).
89
- * @returns Discriminated dispatch result.
90
- *
91
- * @internal
92
- */
93
- function dispatch(
94
- argv: readonly string[],
95
- commands: ReadonlyMap<string, ErasedCommand>,
96
- ancestorPath: readonly CommandSchema[] = [],
97
- valueFlags: ValueFlagLookup = new Map(),
98
- ): DispatchResult {
99
- // Find first non-flag token (potential command name).
100
- // Flags may appear before the command name (e.g. `--verbose db migrate`).
101
- // `--` terminates flag scanning — the next token is treated as a command name.
102
- // Value-flags in space-separated form (`--region eu`, `-r eu`) consume the
103
- // following token as their value, so it must be skipped rather than matched
104
- // as a command name (see #25).
105
- let cmdIdx = -1;
106
- for (let i = 0; i < argv.length; i++) {
107
- const token = argv[i];
108
- if (token === undefined) continue;
109
- if (token === '--') {
110
- // End-of-flags marker: next token (if any) is the command name.
111
- if (i + 1 < argv.length) cmdIdx = i + 1;
112
- break;
113
- }
114
- if (token.startsWith('-')) {
115
- if (consumesFollowingToken(token, valueFlags)) i++; // skip the flag's value
116
- continue;
117
- }
118
- cmdIdx = i;
119
- break;
120
- }
121
-
122
- if (cmdIdx === -1) {
123
- // No command name token found — only flags or empty argv.
124
- return {
125
- kind: 'unknown',
126
- input: '',
127
- candidates: uniqueCommands(commands),
128
- parentPath: ancestorPath,
129
- };
130
- }
131
-
132
- const cmdName = argv[cmdIdx];
133
- if (cmdName === undefined) {
134
- return {
135
- kind: 'unknown',
136
- input: '',
137
- candidates: uniqueCommands(commands),
138
- parentPath: ancestorPath,
139
- };
140
- }
141
-
142
- const matched = commands.get(cmdName);
143
- if (matched === undefined) {
144
- return {
145
- kind: 'unknown',
146
- input: cmdName,
147
- candidates: uniqueCommands(commands),
148
- parentPath: ancestorPath,
149
- };
150
- }
151
-
152
- // Remove command name token from argv, preserving order.
153
- const remaining = [...argv.slice(0, cmdIdx), ...argv.slice(cmdIdx + 1)];
154
- const currentPath = [...ancestorPath, matched.schema];
155
-
156
- // If command has subcommands, try to descend. The matched command's own
157
- // flags govern arity at the child level (e.g. `db --config x migrate`).
158
- if (matched.subcommands.size > 0) {
159
- const subResult = dispatch(
160
- remaining,
161
- matched.subcommands,
162
- currentPath,
163
- buildFlagLookup(matched.schema.flags),
164
- );
165
-
166
- switch (subResult.kind) {
167
- case 'match':
168
- // Successfully found deeper target.
169
- return subResult;
170
-
171
- case 'unknown':
172
- if (subResult.input === '') {
173
- // No subcommand specified.
174
- if (matched.schema.hasAction) {
175
- return {
176
- kind: 'match',
177
- command: matched,
178
- commandPath: currentPath,
179
- remainingArgv: remaining,
180
- };
181
- }
182
- return { kind: 'needs-subcommand', command: matched, commandPath: currentPath };
183
- }
184
-
185
- // Unknown token — might be a positional arg for this command.
186
- if (matched.schema.hasAction) {
187
- return {
188
- kind: 'match',
189
- command: matched,
190
- commandPath: currentPath,
191
- remainingArgv: remaining,
192
- };
193
- }
194
- // No handler — propagate the unknown error.
195
- return subResult;
196
-
197
- case 'needs-subcommand':
198
- // Propagate from deeper level.
199
- return subResult;
200
-
201
- default: {
202
- // Exhaustiveness guard — ensures all DispatchResult variants are handled.
203
- const _exhaustive: never = subResult;
204
- return _exhaustive;
205
- }
206
- }
207
- }
208
-
209
- // Leaf command (no subcommands).
210
- return {
211
- kind: 'match',
212
- command: matched,
213
- commandPath: currentPath,
214
- remainingArgv: remaining,
215
- };
216
- }
217
-
218
- // --- Flag-arity awareness
219
-
220
- /**
221
- * Whether a flag token consumes the following argv token as its value.
222
- *
223
- * Mirrors the parser's value-consumption rules (`parseLongFlag` /
224
- * `parseShortFlags`) so the command-name scan skips exactly the tokens the
225
- * parser would treat as flag values:
226
- * - `--flag value` → consumes when `--flag` is a known value-flag.
227
- * - `--flag=value` → self-contained, consumes nothing.
228
- * - `-abc value` → consumes only when the trailing short flag is a value-flag;
229
- * an earlier value-flag char takes the rest of the group as an inline value.
230
- *
231
- * Unknown flags conservatively consume nothing (the parser reports them later).
232
- *
233
- * @internal
234
- */
235
- function consumesFollowingToken(token: string, valueFlags: ValueFlagLookup): boolean {
236
- if (token.startsWith('--')) {
237
- if (token.includes('=')) return false;
238
- const entry = valueFlags.get(token.slice(2));
239
- return entry !== undefined && flagExpectsValue(entry[1]);
240
- }
241
-
242
- // Short flag group (`-abc`). A value attaches to the trailing flag only; an
243
- // earlier value-flag char swallows the remaining chars as an inline value.
244
- const chars = token.slice(1);
245
- for (let i = 0; i < chars.length; i++) {
246
- const entry = valueFlags.get(chars.charAt(i));
247
- if (entry === undefined) return false;
248
- if (!flagExpectsValue(entry[1])) continue;
249
- return i === chars.length - 1;
250
- }
251
- return false;
252
- }
253
-
254
- // --- "Did you mean?" suggestion
255
-
256
- /**
257
- * Levenshtein distance between two strings.
258
- * @internal
259
- */
260
- function levenshtein(a: string, b: string): number {
261
- const m = a.length;
262
- const n = b.length;
263
-
264
- // Flat (m+1)×(n+1) matrix — fully initialised, no sparse access.
265
- // Two-row rolling buffer: only the previous and current rows are needed.
266
- const w = n + 1;
267
- let prev = new Uint16Array(w);
268
- let curr = new Uint16Array(w);
269
-
270
- // Base row: distance from empty string to b[0..j]
271
- for (let j = 0; j <= n; j++) prev[j] = j;
272
-
273
- for (let i = 1; i <= m; i++) {
274
- curr[0] = i;
275
- for (let j = 1; j <= n; j++) {
276
- const cost = a.charAt(i - 1) === b.charAt(j - 1) ? 0 : 1;
277
- // All indices are in-bounds: j ∈ [1,n], j-1 ∈ [0,n-1], both < w.
278
- // prev/curr are dense Uint16Arrays of length w — no holes.
279
- const del = prev[j] ?? 0;
280
- const ins = curr[j - 1] ?? 0;
281
- const sub = prev[j - 1] ?? 0;
282
- curr[j] = Math.min(del + 1, ins + 1, sub + cost);
283
- }
284
- [prev, curr] = [curr, prev];
285
- }
286
-
287
- // After the loop, `prev` holds the last computed row (swapped at loop end).
288
- return prev[n] ?? Math.max(m, n);
289
- }
290
-
291
- /**
292
- * Find the closest command name match for a "did you mean?" suggestion.
293
- *
294
- * Searches command names and aliases. Returns `undefined` if no
295
- * sufficiently close match exists (threshold: 3).
296
- *
297
- * @internal
298
- */
299
- function findClosestCommand(input: string, commands: readonly ErasedCommand[]): string | undefined {
300
- const MAX_DISTANCE = 3;
301
- let bestName: string | undefined;
302
- let bestDist = MAX_DISTANCE + 1;
303
-
304
- for (const cmd of commands) {
305
- // Check main name
306
- const nameDist = levenshtein(input, cmd.schema.name);
307
- if (nameDist < bestDist) {
308
- bestDist = nameDist;
309
- bestName = cmd.schema.name;
310
- }
311
- // Check aliases
312
- for (const alias of cmd.schema.aliases) {
313
- const aliasDist = levenshtein(input, alias);
314
- if (aliasDist < bestDist) {
315
- bestDist = aliasDist;
316
- bestName = cmd.schema.name; // suggest canonical name
317
- }
318
- }
319
- }
320
-
321
- return bestDist <= MAX_DISTANCE ? bestName : undefined;
322
- }
323
-
324
- // --- Helpers
325
-
326
- /**
327
- * Deduplicate commands from a name+alias map.
328
- *
329
- * A map keyed by name *and* alias contains duplicate entries for aliased
330
- * commands. This returns unique commands (by schema identity).
331
- *
332
- * @internal
333
- */
334
- function uniqueCommands(commands: ReadonlyMap<string, ErasedCommand>): readonly ErasedCommand[] {
335
- const seen = new Set<ErasedCommand>();
336
- const result: ErasedCommand[] = [];
337
- for (const cmd of commands.values()) {
338
- if (!seen.has(cmd)) {
339
- seen.add(cmd);
340
- result.push(cmd);
341
- }
342
- }
343
- return result;
344
- }
345
-
346
- // --- Exports
347
-
348
- export type {
349
- DispatchMatch,
350
- DispatchNeedsSubcommand,
351
- DispatchResult,
352
- DispatchUnknown,
353
- ValueFlagLookup,
354
- };
355
- export { consumesFollowingToken, dispatch, findClosestCommand, levenshtein, uniqueCommands };
@@ -1,82 +0,0 @@
1
- /**
2
- * Root-help header hyperlink resolution.
3
- *
4
- * Stores explicit `.links()` URLs and derives missing ones from package.json
5
- * metadata (`repository` / `homepage`) once that data is available — during
6
- * runtime preflight for `.run()`, or directly from pre-loaded
7
- * `.packageJson(data)` for `.execute()`.
8
- *
9
- * @module dreamcli/core/cli/help-links
10
- * @internal
11
- */
12
-
13
- import type { PackageJsonData } from '#internals/core/config/package-json.ts';
14
- import { packageRepositoryUrl } from '#internals/core/config/package-json.ts';
15
-
16
- /**
17
- * OSC 8 hyperlink targets for the root-help header.
18
- *
19
- * Set via `CLIBuilder.links()`; fields left `undefined` are derived from
20
- * package.json metadata when `.packageJson()` is active.
21
- */
22
- interface HelpLinks {
23
- /** URL the program name links to (e.g. the repository or homepage). */
24
- readonly name: string | undefined;
25
- /** URL the version links to (e.g. the release tag). */
26
- readonly version: string | undefined;
27
- }
28
-
29
- /**
30
- * Build the release-tag URL for a version on a known forge.
31
- *
32
- * GitHub and GitLab have stable release-tag routes; other hosts return
33
- * `undefined` rather than guessing.
34
- *
35
- * @internal
36
- */
37
- function releaseTagUrl(repoUrl: string, version: string): string | undefined {
38
- let hostname: string;
39
- try {
40
- hostname = new URL(repoUrl).hostname;
41
- } catch {
42
- return undefined;
43
- }
44
- if (hostname === 'github.com') return `${repoUrl}/releases/tag/v${version}`;
45
- if (hostname === 'gitlab.com') return `${repoUrl}/-/releases/v${version}`;
46
- return undefined;
47
- }
48
-
49
- /**
50
- * Fill `undefined` link fields from package.json metadata.
51
- *
52
- * Explicit URLs always win. The name falls back to the normalized
53
- * `repository` URL, then `homepage`; the version falls back to the forge
54
- * release-tag URL when both a repository and a version are known.
55
- * Idempotent — already-resolved fields pass through unchanged.
56
- *
57
- * @internal
58
- */
59
- function deriveHelpLinks(
60
- links: HelpLinks | undefined,
61
- pkg: PackageJsonData | undefined,
62
- version: string | undefined,
63
- ): HelpLinks | undefined {
64
- if (links === undefined) return undefined;
65
- if (pkg === undefined || (links.name !== undefined && links.version !== undefined)) {
66
- return links;
67
- }
68
- const repoUrl = packageRepositoryUrl(pkg);
69
- return {
70
- name: links.name ?? repoUrl ?? pkg.homepage,
71
- version:
72
- links.version ??
73
- (repoUrl !== undefined && version !== undefined
74
- ? releaseTagUrl(repoUrl, version)
75
- : undefined),
76
- };
77
- }
78
-
79
- // --- Exports
80
-
81
- export type { HelpLinks };
82
- export { deriveHelpLinks };