@kjanat/dreamcli 1.0.0 → 2.0.1

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 (217) hide show
  1. package/CHANGELOG.md +63 -6
  2. package/LICENSE +1 -1
  3. package/README.md +296 -164
  4. package/dist/core/cli/dispatch.d.mts +85 -0
  5. package/dist/core/cli/dispatch.mjs +1 -0
  6. package/dist/core/cli/index.d.mts +418 -0
  7. package/dist/core/cli/index.mjs +1 -0
  8. package/dist/core/cli/planner.d.mts +143 -0
  9. package/dist/core/cli/planner.mjs +1 -0
  10. package/dist/core/cli/plugin.d.mts +94 -0
  11. package/dist/core/cli/plugin.mjs +1 -0
  12. package/dist/core/cli/propagate.d.mts +39 -0
  13. package/dist/core/cli/propagate.mjs +1 -0
  14. package/dist/core/cli/root-help.d.mts +28 -0
  15. package/dist/core/cli/root-help.mjs +7 -0
  16. package/dist/core/cli/root-surface.d.mts +42 -0
  17. package/dist/core/cli/root-surface.mjs +1 -0
  18. package/dist/core/cli/runtime-preflight.d.mts +149 -0
  19. package/dist/core/cli/runtime-preflight.mjs +1 -0
  20. package/dist/core/completion/index.d.mts +46 -0
  21. package/dist/core/completion/index.mjs +1 -0
  22. package/dist/core/completion/shells/bash.d.mts +24 -0
  23. package/dist/core/completion/shells/bash.mjs +3 -0
  24. package/dist/core/completion/shells/fish.d.mts +20 -0
  25. package/dist/core/completion/shells/fish.mjs +2 -0
  26. package/dist/core/completion/shells/powershell.d.mts +14 -0
  27. package/dist/core/completion/shells/powershell.mjs +2 -0
  28. package/dist/core/completion/shells/shared.d.mts +139 -0
  29. package/dist/core/completion/shells/shared.mjs +1 -0
  30. package/dist/core/completion/shells/zsh.d.mts +24 -0
  31. package/dist/core/completion/shells/zsh.mjs +2 -0
  32. package/dist/core/config/index.d.mts +161 -0
  33. package/dist/core/config/index.mjs +1 -0
  34. package/dist/core/config/package-json.d.mts +68 -0
  35. package/dist/core/config/package-json.mjs +1 -0
  36. package/dist/core/errors/index.d.mts +126 -0
  37. package/dist/core/errors/index.mjs +1 -0
  38. package/dist/core/execution/index.d.mts +49 -0
  39. package/dist/core/execution/index.mjs +1 -0
  40. package/dist/core/help/index.d.mts +49 -0
  41. package/dist/core/help/index.mjs +8 -0
  42. package/dist/core/json-schema/index.d.mts +109 -0
  43. package/dist/core/json-schema/index.mjs +55 -0
  44. package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
  45. package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
  46. package/dist/core/output/activity.d.mts +194 -0
  47. package/dist/core/output/activity.mjs +1 -0
  48. package/dist/core/output/contracts.d.mts +88 -0
  49. package/dist/core/output/contracts.mjs +1 -0
  50. package/dist/core/output/display-value.d.mts +19 -0
  51. package/dist/core/output/display-value.mjs +1 -0
  52. package/dist/core/output/index.d.mts +280 -0
  53. package/dist/core/output/index.mjs +2 -0
  54. package/dist/core/output/renderers.d.mts +46 -0
  55. package/dist/core/output/renderers.mjs +1 -0
  56. package/dist/core/output/writer.d.mts +40 -0
  57. package/dist/core/output/writer.mjs +1 -0
  58. package/dist/core/parse/index.d.mts +79 -0
  59. package/dist/core/parse/index.mjs +1 -0
  60. package/dist/core/prompt/index.d.mts +205 -0
  61. package/dist/core/prompt/index.mjs +6 -0
  62. package/dist/core/resolve/args.d.mts +8 -0
  63. package/dist/core/resolve/args.mjs +1 -0
  64. package/dist/core/resolve/coerce.d.mts +22 -0
  65. package/dist/core/resolve/coerce.mjs +1 -0
  66. package/dist/core/resolve/config.d.mts +10 -0
  67. package/dist/core/resolve/config.mjs +1 -0
  68. package/dist/core/resolve/contracts.d.mts +112 -0
  69. package/dist/core/resolve/errors.d.mts +11 -0
  70. package/dist/core/resolve/errors.mjs +2 -0
  71. package/dist/core/resolve/flags.d.mts +10 -0
  72. package/dist/core/resolve/flags.mjs +1 -0
  73. package/dist/core/resolve/index.d.mts +42 -0
  74. package/dist/core/resolve/index.mjs +1 -0
  75. package/dist/core/resolve/property.d.mts +47 -0
  76. package/dist/core/resolve/property.mjs +1 -0
  77. package/dist/core/schema/activity.d.mts +169 -0
  78. package/dist/core/schema/arg.d.mts +559 -0
  79. package/dist/core/schema/arg.mjs +1 -0
  80. package/dist/core/schema/command.d.mts +960 -0
  81. package/dist/core/schema/command.mjs +1 -0
  82. package/dist/core/schema/flag.d.mts +491 -0
  83. package/dist/core/schema/flag.mjs +1 -0
  84. package/dist/core/schema/index.d.mts +8 -0
  85. package/dist/core/schema/middleware.d.mts +122 -0
  86. package/dist/core/schema/middleware.mjs +1 -0
  87. package/dist/core/schema/prompt.d.mts +117 -0
  88. package/dist/core/schema/run.d.mts +171 -0
  89. package/dist/core/schema-dsl/runtime.d.mts +144 -0
  90. package/dist/core/schema-dsl/runtime.mjs +2 -0
  91. package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
  92. package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
  93. package/dist/core/testkit/index.d.mts +54 -0
  94. package/dist/core/testkit/index.mjs +1 -0
  95. package/dist/index.d.mts +28 -920
  96. package/dist/index.mjs +1 -10
  97. package/dist/runtime/adapter.d.mts +212 -0
  98. package/dist/{adapter-B37d9oia.mjs → runtime/adapter.mjs} +1 -1
  99. package/dist/runtime/auto.d.mts +26 -0
  100. package/dist/runtime/auto.mjs +1 -0
  101. package/dist/runtime/bun.d.mts +28 -0
  102. package/dist/runtime/bun.mjs +1 -0
  103. package/dist/runtime/deno.d.mts +76 -0
  104. package/dist/runtime/deno.mjs +2 -0
  105. package/dist/runtime/detect.d.mts +86 -0
  106. package/dist/runtime/detect.mjs +1 -0
  107. package/dist/runtime/index.d.mts +7 -0
  108. package/dist/runtime/node.d.mts +65 -0
  109. package/dist/runtime/node.mjs +2 -0
  110. package/dist/runtime/paths.d.mts +31 -0
  111. package/dist/runtime/paths.mjs +1 -0
  112. package/dist/runtime/support.d.mts +42 -0
  113. package/dist/runtime/support.mjs +1 -0
  114. package/dist/runtime.d.mts +6 -252
  115. package/dist/runtime.mjs +1 -1
  116. package/dist/testkit.d.mts +5 -24
  117. package/dist/testkit.mjs +1 -1
  118. package/dist/version.d.mts +16 -0
  119. package/dist/version.mjs +1 -0
  120. package/dreamcli.schema.json +338 -0
  121. package/examples/basic.ts +2 -2
  122. package/examples/gh/package.json +7 -11
  123. package/examples/gh/src/commands/auth.ts +2 -2
  124. package/examples/gh/src/commands/issue.ts +4 -4
  125. package/examples/gh/src/commands/pr.ts +4 -4
  126. package/examples/gh/src/docs.ts +11 -0
  127. package/examples/gh/src/lib/auth.ts +1 -1
  128. package/examples/gh/src/main.test.ts +6 -5
  129. package/examples/gh/src/main.ts +8 -6
  130. package/examples/interactive.ts +3 -3
  131. package/examples/json-mode.ts +4 -6
  132. package/examples/middleware.ts +3 -3
  133. package/examples/multi-command.ts +3 -3
  134. package/examples/spinner-progress.ts +5 -5
  135. package/examples/testing.ts +8 -6
  136. package/package.json +70 -44
  137. package/src/core/cli/dispatch.ts +4 -0
  138. package/src/core/cli/index.ts +185 -632
  139. package/src/core/cli/planner.ts +413 -0
  140. package/src/core/cli/plugin.ts +7 -1
  141. package/src/core/cli/propagate.ts +1 -1
  142. package/src/core/cli/runtime-preflight.ts +409 -0
  143. package/src/core/completion/index.ts +15 -9
  144. package/src/core/completion/shells/bash.ts +6 -3
  145. package/src/core/completion/shells/fish.ts +245 -10
  146. package/src/core/completion/shells/powershell.ts +390 -9
  147. package/src/core/completion/shells/shared.ts +4 -4
  148. package/src/core/completion/shells/zsh.ts +12 -7
  149. package/src/core/config/index.ts +7 -4
  150. package/src/core/config/package-json.ts +6 -2
  151. package/src/core/errors/index.ts +23 -8
  152. package/src/core/execution/index.ts +270 -0
  153. package/src/core/help/index.ts +13 -15
  154. package/src/core/json-schema/index.ts +193 -7
  155. package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
  156. package/src/core/output/contracts.ts +194 -0
  157. package/src/core/output/index.ts +47 -82
  158. package/src/core/output/renderers.ts +125 -0
  159. package/src/core/parse/index.ts +39 -21
  160. package/src/core/prompt/index.ts +44 -27
  161. package/src/core/resolve/args.ts +144 -0
  162. package/src/core/resolve/coerce.ts +432 -0
  163. package/src/core/resolve/config.ts +26 -0
  164. package/src/core/resolve/contracts.ts +135 -0
  165. package/src/core/resolve/errors.ts +227 -0
  166. package/src/core/resolve/flags.ts +205 -0
  167. package/src/core/resolve/index.ts +41 -1264
  168. package/src/core/resolve/property.ts +99 -0
  169. package/src/core/schema/activity.ts +3 -0
  170. package/src/core/schema/arg.ts +26 -14
  171. package/src/core/schema/command.ts +265 -38
  172. package/src/core/schema/flag.ts +120 -15
  173. package/src/core/schema/index.ts +11 -2
  174. package/src/core/schema/middleware.ts +6 -6
  175. package/src/core/schema/prompt.ts +9 -1
  176. package/src/core/schema/run.ts +25 -17
  177. package/src/core/schema-dsl/index.ts +109 -0
  178. package/src/core/schema-dsl/parse.ts +262 -0
  179. package/src/core/schema-dsl/runtime.ts +609 -0
  180. package/src/core/schema-dsl/to-json-schema.ts +102 -0
  181. package/src/core/testkit/index.ts +55 -297
  182. package/src/index.ts +10 -4
  183. package/src/runtime/adapter.ts +13 -10
  184. package/src/runtime/auto.ts +3 -3
  185. package/src/runtime/bun.ts +4 -4
  186. package/src/runtime/deno.ts +43 -29
  187. package/src/runtime/detect.ts +4 -1
  188. package/src/runtime/index.ts +1 -1
  189. package/src/runtime/node.ts +43 -21
  190. package/src/runtime/paths.ts +9 -3
  191. package/src/runtime/support.ts +20 -4
  192. package/src/runtime.ts +1 -1
  193. package/src/testkit.ts +10 -8
  194. package/dist/adapter-CCSh5juX.cjs +0 -1
  195. package/dist/adapter-DIwO-q7K.d.mts +0 -3447
  196. package/dist/adapter-DQnxxLiE.d.cts +0 -3447
  197. package/dist/auto-5cjZaF9V.mjs +0 -3
  198. package/dist/auto-B0eSgoDw.cjs +0 -3
  199. package/dist/index.cjs +0 -10
  200. package/dist/index.d.cts +0 -920
  201. package/dist/runtime.cjs +0 -1
  202. package/dist/runtime.d.cts +0 -253
  203. package/dist/testkit-CEDYPvhF.mjs +0 -14
  204. package/dist/testkit-ClIKijxC.cjs +0 -14
  205. package/dist/testkit.cjs +0 -1
  206. package/dist/testkit.d.cts +0 -25
  207. package/examples/gh/tsconfig.json +0 -37
  208. package/examples/tsconfig.json +0 -17
  209. package/src/core/cli/AGENTS.md +0 -72
  210. package/src/core/completion/AGENTS.md +0 -72
  211. package/src/core/completion/completion-test-helpers.ts +0 -48
  212. package/src/core/output/AGENTS.md +0 -69
  213. package/src/core/resolve/AGENTS.md +0 -69
  214. package/src/core/schema/AGENTS.md +0 -61
  215. package/src/core/testkit/AGENTS.md +0 -55
  216. package/src/runtime/AGENTS.md +0 -74
  217. package/src/runtime/test-helpers.ts +0 -40
@@ -0,0 +1,413 @@
1
+ /**
2
+ * Internal planner contract for CLI dispatch outcomes.
3
+ *
4
+ * Captures the stable seam between CLI-facing invocation planning and the
5
+ * lower-level execution pipeline. This module is now the explicit invocation
6
+ * planner seam: it owns root interception, command dispatch, default-command
7
+ * fallback, propagated-flag merging, and match handoff shaping.
8
+ *
9
+ * @module dreamcli/core/cli/planner
10
+ * @internal
11
+ */
12
+
13
+ import { CLIError, ParseError } from '#internals/core/errors/index.ts';
14
+ import type { HelpOptions } from '#internals/core/help/index.ts';
15
+ import type { OutputPolicy } from '#internals/core/output/contracts.ts';
16
+ import type { CommandMeta, CommandSchema, ErasedCommand } from '#internals/core/schema/command.ts';
17
+ import { dispatch, findClosestCommand } from './dispatch.ts';
18
+ import type { CLIPlugin } from './plugin.ts';
19
+ import { collectPropagatedFlags } from './propagate.ts';
20
+
21
+ /**
22
+ * Structural subset of CLISchema used by the planner.
23
+ *
24
+ * Decouples invocation planning from the full CLIBuilder surface so the
25
+ * planner can be tested and reasoned about without constructing a real CLI.
26
+ * @internal
27
+ */
28
+ interface PlannerSchemaLike {
29
+ /** CLI program name used in help text and error messages. */
30
+ readonly name: string;
31
+ /** Declared version string; `undefined` disables `--version` interception. */
32
+ readonly version: string | undefined;
33
+ /** Registered top-level commands available for dispatch. */
34
+ readonly commands: readonly ErasedCommand[];
35
+ /** Fallback command when no subcommand token matches. */
36
+ readonly defaultCommand: ErasedCommand | undefined;
37
+ /** Plugins forwarded into every matched execution plan. */
38
+ readonly plugins: readonly CLIPlugin[];
39
+ }
40
+
41
+ /** Root-level help interception outcome. */
42
+ interface RootHelpOutcome {
43
+ /** Discriminant — argv matched `--help` / `-h` before any command. */
44
+ readonly kind: 'root-help';
45
+ /** Help options to render root-level usage. */
46
+ readonly help: HelpOptions;
47
+ }
48
+
49
+ /** Root-level version interception outcome. */
50
+ interface RootVersionOutcome {
51
+ /** Discriminant — argv matched `--version` / `-V` and schema declares a version. */
52
+ readonly kind: 'root-version';
53
+ /** Resolved version string to render. */
54
+ readonly version: string;
55
+ }
56
+
57
+ /** CLI-level dispatch failure before command execution starts. */
58
+ interface DispatchErrorOutcome {
59
+ /** Discriminant — dispatch could not resolve a command from argv. */
60
+ readonly kind: 'dispatch-error';
61
+ /** Structured error with suggestion text for the caller to render. */
62
+ readonly error: CLIError;
63
+ }
64
+
65
+ /** Successful planner handoff to the shared command execution path. */
66
+ interface PlannerMatchOutcome {
67
+ /** Discriminant — dispatch found a matching command for argv. */
68
+ readonly kind: 'match';
69
+ /** Fully resolved execution plan ready for the executor pipeline. */
70
+ readonly plan: CommandExecutionPlan;
71
+ }
72
+
73
+ /**
74
+ * Stable planner result union for the re-foundation workstream.
75
+ *
76
+ * `CLIBuilder.execute()` still renders and executes these outcomes, but
77
+ * planning itself is intentionally bounded to this union.
78
+ */
79
+ type DispatchOutcome =
80
+ | RootHelpOutcome
81
+ | RootVersionOutcome
82
+ | DispatchErrorOutcome
83
+ | PlannerMatchOutcome;
84
+
85
+ /**
86
+ * Concrete execution handoff produced by a successful planner match.
87
+ *
88
+ * `mergedSchema` is the exact command schema the executor sees after
89
+ * propagated ancestor flags are collected and child definitions shadow them.
90
+ */
91
+ interface CommandExecutionPlan {
92
+ /** Type-erased command instance that owns the handler. */
93
+ readonly command: ErasedCommand;
94
+ /** Command schema with propagated ancestor flags merged in. */
95
+ readonly mergedSchema: CommandSchema;
96
+ /** Remaining argv tokens after command dispatch consumed the command path. */
97
+ readonly argv: readonly string[];
98
+ /** CLI-level metadata (program name, bin, version) for the handler context. */
99
+ readonly meta: CommandMeta;
100
+ /** Plugins to run through the execution lifecycle. */
101
+ readonly plugins: readonly CLIPlugin[];
102
+ /** Output policy (json mode, TTY, verbosity) governing handler rendering. */
103
+ readonly output: OutputPolicy;
104
+ /** Help options for rendering per-command help; `undefined` when unavailable. */
105
+ readonly help: HelpOptions | undefined;
106
+ }
107
+
108
+ interface BuildCommandExecutionPlanOptions {
109
+ readonly command: ErasedCommand;
110
+ readonly commandPath: readonly CommandSchema[];
111
+ readonly argv: readonly string[];
112
+ readonly meta: CommandMeta;
113
+ readonly plugins: readonly CLIPlugin[];
114
+ readonly output: OutputPolicy;
115
+ readonly help: HelpOptions | undefined;
116
+ }
117
+
118
+ /**
119
+ * Dispatch resolved a group command that requires a subcommand selection.
120
+ *
121
+ * The caller should render subcommand-level help for the matched group.
122
+ * @internal
123
+ */
124
+ interface NeedsSubcommandOutcome {
125
+ /** Discriminant — group command matched but no leaf subcommand was selected. */
126
+ readonly kind: 'needs-subcommand';
127
+ /** The group command that was matched. */
128
+ readonly command: ErasedCommand;
129
+ /** Full ancestor path from root to this group, used for propagated flag collection. */
130
+ readonly commandPath: readonly CommandSchema[];
131
+ /** Help options scoped to the group command's bin path. */
132
+ readonly help: HelpOptions;
133
+ }
134
+
135
+ /** Full planner result including the `needs-subcommand` variant used by CLIBuilder. @internal */
136
+ type InvocationPlan = DispatchOutcome | NeedsSubcommandOutcome;
137
+
138
+ /** Options bag for {@linkcode planInvocation}. @internal */
139
+ interface PlanInvocationOptions {
140
+ /** CLI schema subset driving dispatch decisions. */
141
+ readonly schema: PlannerSchemaLike;
142
+ /** Raw argv tokens (typically `adapter.argv.slice(2)`). */
143
+ readonly argv: readonly string[];
144
+ /** Root-level help configuration for rendering. */
145
+ readonly help: HelpOptions;
146
+ /** Output policy propagated into matched execution plans. */
147
+ readonly output: OutputPolicy;
148
+ }
149
+
150
+ function buildMeta(
151
+ schema: PlannerSchemaLike,
152
+ helpOptions: HelpOptions,
153
+ commandName: string,
154
+ ): CommandMeta {
155
+ return {
156
+ name: schema.name,
157
+ bin: helpOptions.binName ?? schema.name,
158
+ version: schema.version,
159
+ command: commandName,
160
+ };
161
+ }
162
+
163
+ /** Build a name+alias lookup map for top-level commands. @internal */
164
+ function buildRootCommandMap(
165
+ commands: readonly ErasedCommand[],
166
+ ): ReadonlyMap<string, ErasedCommand> {
167
+ const rootCommands = new Map<string, ErasedCommand>();
168
+
169
+ const addRoute = (route: string, command: ErasedCommand): void => {
170
+ const existing = rootCommands.get(route);
171
+ if (existing !== undefined) {
172
+ throw new CLIError(
173
+ `Duplicate root command route '${route}' (${existing.schema.name} and ${command.schema.name})`,
174
+ {
175
+ code: 'DUPLICATE_COMMAND',
176
+ suggest: 'Ensure root command names and aliases are unique',
177
+ },
178
+ );
179
+ }
180
+
181
+ rootCommands.set(route, command);
182
+ };
183
+
184
+ for (const cmd of commands) {
185
+ addRoute(cmd.schema.name, cmd);
186
+ for (const alias of cmd.schema.aliases) {
187
+ addRoute(alias, cmd);
188
+ }
189
+ }
190
+ return rootCommands;
191
+ }
192
+
193
+ /**
194
+ * Merge propagated ancestor flags into the matched command schema.
195
+ *
196
+ * Child flag definitions win when names collide, matching current CLI
197
+ * dispatch semantics and the future planner contract.
198
+ */
199
+ function mergeCommandSchema(
200
+ command: ErasedCommand,
201
+ commandPath: readonly CommandSchema[],
202
+ ): CommandSchema {
203
+ const propagated = collectPropagatedFlags(commandPath);
204
+ if (Object.keys(propagated).length === 0) {
205
+ return command.schema;
206
+ }
207
+
208
+ return {
209
+ ...command.schema,
210
+ flags: { ...propagated, ...command.schema.flags },
211
+ };
212
+ }
213
+
214
+ /** Build the planner handoff for a matched command invocation. */
215
+ function buildCommandExecutionPlan(
216
+ options: BuildCommandExecutionPlanOptions,
217
+ ): CommandExecutionPlan {
218
+ return {
219
+ command: options.command,
220
+ mergedSchema: mergeCommandSchema(options.command, options.commandPath),
221
+ argv: options.argv,
222
+ meta: options.meta,
223
+ plugins: options.plugins,
224
+ output: options.output,
225
+ help: options.help,
226
+ };
227
+ }
228
+
229
+ function buildPlannerMatchOutcome(
230
+ schema: PlannerSchemaLike,
231
+ command: ErasedCommand,
232
+ commandPath: readonly CommandSchema[],
233
+ argv: readonly string[],
234
+ help: HelpOptions,
235
+ output: OutputPolicy,
236
+ ): PlannerMatchOutcome {
237
+ return {
238
+ kind: 'match',
239
+ plan: buildCommandExecutionPlan({
240
+ command,
241
+ commandPath,
242
+ argv,
243
+ meta: buildMeta(schema, help, command.schema.name),
244
+ plugins: schema.plugins,
245
+ output,
246
+ help,
247
+ }),
248
+ };
249
+ }
250
+
251
+ /**
252
+ * Decide what to do with an argv invocation before any command executes.
253
+ *
254
+ * Handles root interception (`--help`, `--version`, bare `help` token),
255
+ * dispatches into the command tree, falls back to the default command, and
256
+ * produces structured errors for unknown commands/flags.
257
+ * @internal
258
+ */
259
+ function planInvocation(options: PlanInvocationOptions): InvocationPlan {
260
+ const filteredArgv = options.argv.includes('--json')
261
+ ? options.argv.filter((arg) => arg !== '--json')
262
+ : options.argv;
263
+
264
+ if (
265
+ options.schema.version !== undefined &&
266
+ (filteredArgv.includes('--version') || filteredArgv.includes('-V'))
267
+ ) {
268
+ return {
269
+ kind: 'root-version',
270
+ version: options.schema.version,
271
+ };
272
+ }
273
+
274
+ const firstArg = filteredArgv[0];
275
+ if (firstArg === '--help' || firstArg === '-h') {
276
+ return {
277
+ kind: 'root-help',
278
+ help: options.help,
279
+ };
280
+ }
281
+
282
+ if (firstArg === 'help') {
283
+ const hasRealHelpCommand = options.schema.commands.some(
284
+ (command) => command.schema.name === 'help' || command.schema.aliases.includes('help'),
285
+ );
286
+ if (!hasRealHelpCommand) {
287
+ const rest = filteredArgv.slice(1);
288
+ if (rest.length === 0) {
289
+ return {
290
+ kind: 'root-help',
291
+ help: options.help,
292
+ };
293
+ }
294
+
295
+ return planInvocation({
296
+ ...options,
297
+ argv: [...rest, '--help'],
298
+ });
299
+ }
300
+ }
301
+
302
+ if (firstArg === undefined && options.schema.defaultCommand === undefined) {
303
+ return {
304
+ kind: 'root-help',
305
+ help: options.help,
306
+ };
307
+ }
308
+
309
+ if (options.schema.commands.length === 0) {
310
+ return {
311
+ kind: 'dispatch-error',
312
+ error: new CLIError('No commands registered', {
313
+ code: 'NO_ACTION',
314
+ suggest: 'Add commands via .command() before calling .run()',
315
+ }),
316
+ };
317
+ }
318
+
319
+ const result = dispatch(filteredArgv, buildRootCommandMap(options.schema.commands));
320
+ const defaultCommand = options.schema.defaultCommand;
321
+
322
+ switch (result.kind) {
323
+ case 'unknown': {
324
+ if (defaultCommand !== undefined && result.parentPath.length === 0) {
325
+ const suggestion =
326
+ result.input !== '' ? findClosestCommand(result.input, result.candidates) : undefined;
327
+ if (suggestion === undefined) {
328
+ return buildPlannerMatchOutcome(
329
+ options.schema,
330
+ defaultCommand,
331
+ [defaultCommand.schema],
332
+ filteredArgv,
333
+ options.help,
334
+ options.output,
335
+ );
336
+ }
337
+ }
338
+
339
+ if (result.input === '') {
340
+ const unknownFlag = filteredArgv.find((token) => token.startsWith('-'));
341
+ if (unknownFlag === undefined) {
342
+ return {
343
+ kind: 'root-help',
344
+ help: options.help,
345
+ };
346
+ }
347
+
348
+ return {
349
+ kind: 'dispatch-error',
350
+ error: new ParseError(`Unknown flag ${unknownFlag}`, {
351
+ code: 'UNKNOWN_FLAG',
352
+ suggest: `Run '${options.schema.name} --help' for available commands`,
353
+ }),
354
+ };
355
+ }
356
+
357
+ const suggestion = findClosestCommand(result.input, result.candidates);
358
+ const scopePath =
359
+ result.parentPath.length > 0
360
+ ? `${options.schema.name} ${result.parentPath.map((schema) => schema.name).join(' ')}`
361
+ : options.schema.name;
362
+
363
+ return {
364
+ kind: 'dispatch-error',
365
+ error: new ParseError(`Unknown command: ${result.input}`, {
366
+ code: 'UNKNOWN_COMMAND',
367
+ suggest:
368
+ suggestion !== undefined
369
+ ? `Did you mean '${suggestion}'?`
370
+ : `Run '${scopePath} --help' for available commands`,
371
+ }),
372
+ };
373
+ }
374
+
375
+ case 'needs-subcommand': {
376
+ const ancestorNames = result.commandPath.slice(0, -1).map((schema) => schema.name);
377
+ return {
378
+ kind: 'needs-subcommand',
379
+ command: result.command,
380
+ commandPath: result.commandPath,
381
+ help: {
382
+ ...options.help,
383
+ binName: [options.schema.name, ...ancestorNames].join(' '),
384
+ },
385
+ };
386
+ }
387
+
388
+ case 'match':
389
+ return buildPlannerMatchOutcome(
390
+ options.schema,
391
+ result.command,
392
+ result.commandPath,
393
+ result.remainingArgv,
394
+ options.help,
395
+ options.output,
396
+ );
397
+ }
398
+ }
399
+
400
+ export type {
401
+ CommandExecutionPlan,
402
+ DispatchErrorOutcome,
403
+ DispatchOutcome,
404
+ InvocationPlan,
405
+ NeedsSubcommandOutcome,
406
+ OutputPolicy,
407
+ PlanInvocationOptions,
408
+ PlannerMatchOutcome,
409
+ PlannerSchemaLike,
410
+ RootHelpOutcome,
411
+ RootVersionOutcome,
412
+ };
413
+ export { buildCommandExecutionPlan, buildRootCommandMap, mergeCommandSchema, planInvocation };
@@ -79,6 +79,12 @@ interface CLIPlugin {
79
79
  *
80
80
  * @example
81
81
  * ```ts
82
+ * import { cli, command, plugin } from '@kjanat/dreamcli';
83
+ *
84
+ * const deploy = command('deploy').action(({ out }) => {
85
+ * out.log('deploying');
86
+ * });
87
+ *
82
88
  * const trace = plugin(
83
89
  * {
84
90
  * beforeParse: ({ argv, out }) => {
@@ -91,7 +97,7 @@ interface CLIPlugin {
91
97
  * 'trace',
92
98
  * );
93
99
  *
94
- * cli('mycli').plugin(trace).command(deploy);
100
+ * cli('mycli').plugin(trace).command(deploy).run();
95
101
  * ```
96
102
  *
97
103
  * @returns A frozen {@link CLIPlugin} definition.
@@ -16,7 +16,7 @@ import type { CommandSchema, FlagSchema } from '#internals/core/schema/index.ts'
16
16
  /**
17
17
  * Collect propagated flags from a command path.
18
18
  *
19
- * The command path is an ordered array of `CommandSchema` from the root
19
+ * The command path is an ordered array of {@linkcode CommandSchema} from the root
20
20
  * ancestor to the target command that will actually execute. Each ancestor's
21
21
  * flags marked `propagate: true` are accumulated. If a descendant (including
22
22
  * the target) defines a flag with the same name — regardless of whether the