@kjanat/dreamcli 0.0.0 → 2.0.0

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 (205) hide show
  1. package/CHANGELOG.md +706 -0
  2. package/LICENSE +22 -0
  3. package/README.md +502 -0
  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 -0
  96. package/dist/index.mjs +1 -0
  97. package/dist/runtime/adapter.d.mts +212 -0
  98. package/dist/runtime/adapter.mjs +1 -0
  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 +7 -0
  115. package/dist/runtime.mjs +1 -0
  116. package/dist/testkit.d.mts +6 -0
  117. package/dist/testkit.mjs +1 -0
  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 +33 -0
  122. package/examples/gh/package.json +44 -0
  123. package/examples/gh/src/commands/auth.ts +66 -0
  124. package/examples/gh/src/commands/issue.ts +120 -0
  125. package/examples/gh/src/commands/pr.ts +125 -0
  126. package/examples/gh/src/data/issues.yaml +5 -0
  127. package/examples/gh/src/data/issues.yaml.d.ts +17 -0
  128. package/examples/gh/src/data/pull-requests.yaml +7 -0
  129. package/examples/gh/src/data/pull-requests.yaml.d.ts +18 -0
  130. package/examples/gh/src/docs.ts +11 -0
  131. package/examples/gh/src/lib/auth.ts +37 -0
  132. package/examples/gh/src/lib/utils.ts +17 -0
  133. package/examples/gh/src/main.test.ts +307 -0
  134. package/examples/gh/src/main.ts +40 -0
  135. package/examples/interactive.ts +66 -0
  136. package/examples/json-mode.ts +91 -0
  137. package/examples/middleware.ts +71 -0
  138. package/examples/multi-command.ts +66 -0
  139. package/examples/spinner-progress.ts +49 -0
  140. package/examples/testing.ts +147 -0
  141. package/package.json +149 -2
  142. package/src/core/cli/dispatch.ts +286 -0
  143. package/src/core/cli/index.ts +978 -0
  144. package/src/core/cli/planner.ts +413 -0
  145. package/src/core/cli/plugin.ts +117 -0
  146. package/src/core/cli/propagate.ts +97 -0
  147. package/src/core/cli/root-help.ts +269 -0
  148. package/src/core/cli/root-surface.ts +74 -0
  149. package/src/core/cli/runtime-preflight.ts +409 -0
  150. package/src/core/completion/index.ts +88 -0
  151. package/src/core/completion/shells/bash.ts +459 -0
  152. package/src/core/completion/shells/fish.ts +259 -0
  153. package/src/core/completion/shells/powershell.ts +405 -0
  154. package/src/core/completion/shells/shared.ts +283 -0
  155. package/src/core/completion/shells/zsh.ts +381 -0
  156. package/src/core/config/index.ts +407 -0
  157. package/src/core/config/package-json.ts +220 -0
  158. package/src/core/errors/index.ts +193 -0
  159. package/src/core/execution/index.ts +270 -0
  160. package/src/core/help/index.ts +557 -0
  161. package/src/core/json-schema/index.ts +891 -0
  162. package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
  163. package/src/core/output/activity.ts +568 -0
  164. package/src/core/output/contracts.ts +194 -0
  165. package/src/core/output/display-value.ts +48 -0
  166. package/src/core/output/index.ts +669 -0
  167. package/src/core/output/renderers.ts +125 -0
  168. package/src/core/output/writer.ts +46 -0
  169. package/src/core/parse/index.ts +661 -0
  170. package/src/core/prompt/index.ts +583 -0
  171. package/src/core/resolve/args.ts +144 -0
  172. package/src/core/resolve/coerce.ts +432 -0
  173. package/src/core/resolve/config.ts +26 -0
  174. package/src/core/resolve/contracts.ts +135 -0
  175. package/src/core/resolve/errors.ts +227 -0
  176. package/src/core/resolve/flags.ts +205 -0
  177. package/src/core/resolve/index.ts +108 -0
  178. package/src/core/resolve/property.ts +99 -0
  179. package/src/core/schema/activity.ts +240 -0
  180. package/src/core/schema/arg.ts +719 -0
  181. package/src/core/schema/command.ts +1490 -0
  182. package/src/core/schema/flag.ts +756 -0
  183. package/src/core/schema/index.ts +91 -0
  184. package/src/core/schema/middleware.ts +171 -0
  185. package/src/core/schema/prompt.ts +156 -0
  186. package/src/core/schema/run.ts +195 -0
  187. package/src/core/schema-dsl/index.ts +109 -0
  188. package/src/core/schema-dsl/parse.ts +262 -0
  189. package/src/core/schema-dsl/runtime.ts +609 -0
  190. package/src/core/schema-dsl/to-json-schema.ts +102 -0
  191. package/src/core/testkit/index.ts +123 -0
  192. package/src/index.ts +170 -0
  193. package/src/runtime/adapter.ts +303 -0
  194. package/src/runtime/auto.ts +110 -0
  195. package/src/runtime/bun.ts +55 -0
  196. package/src/runtime/deno.ts +369 -0
  197. package/src/runtime/detect.ts +105 -0
  198. package/src/runtime/index.ts +21 -0
  199. package/src/runtime/node-builtins.d.ts +23 -0
  200. package/src/runtime/node.ts +300 -0
  201. package/src/runtime/paths.ts +62 -0
  202. package/src/runtime/support.ts +135 -0
  203. package/src/runtime.ts +31 -0
  204. package/src/testkit.ts +25 -0
  205. package/src/version.ts +20 -0
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+ ===========
3
+
4
+ Copyright (c) 2026 Kaj Kowalski
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,502 @@
1
+ # dreamcli
2
+
3
+ [![NPM](https://img.shields.io/npm/v/@kjanat/dreamcli?logo=npm&labelColor=CB3837&color=black)][npm]
4
+ [![JSR](https://img.shields.io/jsr/v/@kjanat/dreamcli?logoColor=083344&logo=jsr&logoSize=auto&label=&labelColor=f7df1e&color=black)][jsr]
5
+
6
+ Schema-first, fully typed TypeScript CLI framework. Zero runtime dependencies.
7
+
8
+ One flag declaration configures the entire resolution pipeline:
9
+
10
+ ```ts
11
+ import {
12
+ cli,
13
+ command,
14
+ flag,
15
+ arg,
16
+ middleware,
17
+ CLIError,
18
+ } from '@kjanat/dreamcli';
19
+
20
+ const deploy = command('deploy')
21
+ .description('Deploy to an environment')
22
+ .arg('target', arg.string().describe('Deploy target'))
23
+ .flag(
24
+ 'region',
25
+ flag
26
+ .enum(['us', 'eu', 'ap'])
27
+ .alias('r')
28
+ .env('DEPLOY_REGION')
29
+ .config('deploy.region')
30
+ .prompt({ kind: 'select', message: 'Which region?' })
31
+ .default('us')
32
+ .propagate(),
33
+ )
34
+ .action(({ args, flags, out }) => {
35
+ out.log(`Deploying ${args.target} to ${flags.region}`);
36
+ });
37
+ ```
38
+
39
+ By the time `action` runs, `flags.region` is `"us" | "eu" | "ap"` — not `string | undefined`.
40
+
41
+ The value is resolved through a documented chain: **CLI → env → config → interactive prompt →
42
+ default**. Every step is opt-in. Every step preserves types.
43
+
44
+ ## Install
45
+
46
+ ```bash
47
+ npm install @kjanat/dreamcli
48
+ ```
49
+
50
+ <details><summary>bun/deno</summary>
51
+
52
+ ```bash
53
+ bun add @kjanat/dreamcli
54
+ ```
55
+
56
+ ```bash
57
+ deno add jsr:@kjanat/dreamcli # or npm:@kjanat/dreamcli
58
+ ```
59
+
60
+ </details>
61
+
62
+ ## Quick start
63
+
64
+ ### Single command
65
+
66
+ ```ts
67
+ import { command, flag, arg } from '@kjanat/dreamcli';
68
+
69
+ const greet = command('greet')
70
+ .description('Greet someone')
71
+ .arg('name', arg.string().describe('Who to greet'))
72
+ .flag(
73
+ 'loud',
74
+ flag
75
+ .boolean()
76
+ .alias('l')
77
+ .describe('Shout the greeting'),
78
+ )
79
+ .flag(
80
+ 'times',
81
+ flag.number().default(1).describe('Repeat count'),
82
+ )
83
+ .action(({ args, flags, out }) => {
84
+ for (let i = 0; i < flags.times; i++) {
85
+ const msg = `Hello, ${args.name}!`;
86
+ out.log(flags.loud ? msg.toUpperCase() : msg);
87
+ }
88
+ });
89
+
90
+ greet.run();
91
+ ```
92
+
93
+ ### Multi-command CLI
94
+
95
+ ```ts
96
+ import {
97
+ cli,
98
+ command,
99
+ group,
100
+ flag,
101
+ arg,
102
+ } from '@kjanat/dreamcli';
103
+
104
+ const deploy = command('deploy')
105
+ .description('Deploy to an environment')
106
+ .arg('target', arg.string())
107
+ .flag('force', flag.boolean().alias('f'))
108
+ .flag(
109
+ 'region',
110
+ flag.enum(['us', 'eu', 'ap']).env('DEPLOY_REGION'),
111
+ )
112
+ .action(({ args, flags, out }) => {
113
+ out.log(
114
+ `Deploying ${args.target} to ${flags.region ?? 'default'}`,
115
+ );
116
+ });
117
+
118
+ const login = command('login')
119
+ .description('Authenticate with the service')
120
+ .flag('token', flag.string().describe('Auth token'))
121
+ .action(({ flags, out }) => {
122
+ out.log(
123
+ flags.token
124
+ ? 'Authenticated via token'
125
+ : 'Authenticated interactively',
126
+ );
127
+ });
128
+
129
+ // Nested command groups
130
+ const migrate = command('migrate')
131
+ .description('Run migrations')
132
+ .flag('steps', flag.number())
133
+ .action(({ flags, out }) => {
134
+ out.log(`migrating ${flags.steps ?? 'all'} steps`);
135
+ });
136
+
137
+ const seed = command('seed')
138
+ .description('Seed database')
139
+ .action(({ out }) => {
140
+ out.log('seeding');
141
+ });
142
+
143
+ const db = group('db')
144
+ .description('Database operations')
145
+ .command(migrate)
146
+ .command(seed);
147
+
148
+ cli('mycli')
149
+ .version('1.0.0')
150
+ .description('My awesome tool')
151
+ .command(deploy)
152
+ .command(login)
153
+ .command(db)
154
+ .run();
155
+
156
+ // mycli deploy production --force
157
+ // mycli login --token abc123
158
+ // mycli db migrate --steps 3
159
+ // mycli db seed
160
+ ```
161
+
162
+ ## Why dreamcli
163
+
164
+ Most TypeScript CLI frameworks treat the type system like decoration.
165
+ You define flags in one place, then use parsed values somewhere else as a loosely typed blob.
166
+ Env vars, config files, and interactive prompts live in separate universes.
167
+ Testing means hacking `process.argv`.
168
+
169
+ dreamcli collapses all of that into a single typed schema:
170
+
171
+ Approximate comparison of first-party, built-in support as documented by each project.
172
+ Third-party plugins and custom glue can extend the other libraries.
173
+
174
+ | Capability | dreamcli | Commander | Yargs | Citty | CAC | Cleye |
175
+ | ------------------------------------------ | ------------------------------------- | ------------------- | ---------------------- | --------------- | ------------- | ------------- |
176
+ | Type inference from definition | Full — flags, args, context | Manual `.opts<T>()` | Good | Good | Basic | Good |
177
+ | Built-in value sources | CLI, env, config, prompt, default | CLI, defaults, env | CLI, env, config | CLI, defaults | CLI, defaults | CLI, defaults |
178
+ | Schema-driven prompts | Integrated | No | No | No | No | No |
179
+ | Middleware / hooks | Yes — typed middleware | Lifecycle hooks | Middleware | Plugins / hooks | Events | No |
180
+ | Built-in test harness with output capture | `runCommand()` + capture | No | No | No | No | No |
181
+ | Shell completions from command definitions | Built-in (bash/zsh/fish/powershell) | No | Built-in (bash/zsh) | No | No | No |
182
+ | Structured output primitives | Built-in (`--json`, tables, spinners) | DIY | DIY | DIY | DIY | DIY |
183
+ | Config file support | Built-in (XDG discovery, JSON) | DIY | Built-in (`.config()`) | No | No | No |
184
+
185
+ The closest analog is what tRPC did to API routes — individual pieces existed,
186
+ the insight was wiring them so types flow end-to-end.
187
+
188
+ ## Features
189
+
190
+ ### Flag types
191
+
192
+ ```ts
193
+ flag.string(); // string | undefined
194
+ flag.number(); // number | undefined
195
+ flag.boolean(); // boolean (defaults to false)
196
+ flag.enum(['us', 'eu', 'ap']); // "us" | "eu" | "ap" | undefined
197
+ flag.array(flag.string()); // string[] | undefined
198
+ flag.custom((v) => new URL(v)); // URL | undefined
199
+ ```
200
+
201
+ Every flag supports: `.default()`, `.required()`, `.alias()`, `.env()`, `.config()`, `.describe()`,
202
+ `.prompt()`, `.deprecated()`, `.propagate()`.
203
+
204
+ ### Resolution chain
205
+
206
+ Each flag resolves through an ordered pipeline. Every step is opt-in:
207
+
208
+ ```text
209
+ CLI argv → environment variable → config file → interactive prompt → default value
210
+ ```
211
+
212
+ Required flags that don't resolve produce a structured error before the action handler runs. In
213
+ non-interactive contexts (CI, piped stdin), prompts are automatically skipped.
214
+
215
+ ### Interactive prompts
216
+
217
+ Four prompt types, declared per-flag or per-command:
218
+
219
+ ```ts
220
+ // Per-flag
221
+ flag.string().prompt({ kind: 'input', message: 'Name?' });
222
+ flag
223
+ .boolean()
224
+ .prompt({ kind: 'confirm', message: 'Sure?' });
225
+ flag
226
+ .enum(['a', 'b'])
227
+ .prompt({ kind: 'select', message: 'Pick one' });
228
+ flag.array(flag.string()).prompt({
229
+ kind: 'multiselect',
230
+ message: 'Pick many',
231
+ choices: [{ value: 'a' }, { value: 'b' }],
232
+ });
233
+
234
+ // Per-command (conditional — receives partially resolved flags)
235
+ command('deploy')
236
+ .flag('region', flag.enum(['us', 'eu', 'ap']))
237
+ .interactive(({ flags }) => ({
238
+ region: !flags.region && {
239
+ kind: 'select',
240
+ message: 'Which region?',
241
+ },
242
+ }));
243
+ ```
244
+
245
+ ### Derive typed context from resolved input
246
+
247
+ ```ts
248
+ import { CLIError } from '@kjanat/dreamcli';
249
+
250
+ command('deploy')
251
+ .flag('token', flag.string().env('AUTH_TOKEN'))
252
+ .derive(({ flags }) => {
253
+ if (!flags.token)
254
+ throw new CLIError('Not authenticated', {
255
+ code: 'AUTH_REQUIRED',
256
+ suggest: 'Run `mycli login`',
257
+ });
258
+ return { token: flags.token };
259
+ })
260
+ .action(({ ctx }) => {
261
+ ctx.token; // string — typed
262
+ });
263
+ ```
264
+
265
+ Use `derive()` when you need typed, command-scoped access to fully resolved flags and args before
266
+ the action handler runs.
267
+
268
+ ### Middleware with typed context
269
+
270
+ ```ts
271
+ import { middleware } from '@kjanat/dreamcli';
272
+
273
+ const timing = middleware<{ startTime: number }>(
274
+ async ({ next }) => {
275
+ const startTime = Date.now();
276
+ await next({ startTime });
277
+ },
278
+ );
279
+
280
+ const trace = middleware<{ traceId: string }>(
281
+ async ({ next }) =>
282
+ next({ traceId: crypto.randomUUID() }),
283
+ );
284
+
285
+ command('deploy')
286
+ .middleware(timing)
287
+ .middleware(trace)
288
+ .action(({ ctx }) => {
289
+ ctx.startTime; // number — typed
290
+ ctx.traceId; // string — typed
291
+ });
292
+ ```
293
+
294
+ Context accumulates through the middleware chain via type intersection.
295
+ No manual interface merging.
296
+
297
+ Use middleware when you need wrapper behavior with `next()`.
298
+
299
+ ### Output channel
300
+
301
+ Handlers receive `out` instead of `console`. Adapts to context automatically:
302
+
303
+ ```ts
304
+ cli('mycli')
305
+ // ... omitted for brevity
306
+ .action(({ out }) => {
307
+ out.log('Human-readable message');
308
+ out.json({ status: 'ok', count: 42 });
309
+ out.table(rows, [
310
+ { key: 'name', header: 'Name' },
311
+ { key: 'status', header: 'Status' },
312
+ ]);
313
+
314
+ const spinner = out.spinner('Deploying...');
315
+ spinner.succeed('Done');
316
+
317
+ const progress = out.progress({
318
+ label: 'Uploading',
319
+ total: 100,
320
+ });
321
+ progress.update(50);
322
+ progress.done('Upload complete');
323
+ });
324
+ ```
325
+
326
+ - TTY → pretty formatting, spinners animate
327
+ - Piped → minimal stable output, spinners suppressed
328
+ - `--json` → structured JSON to stdout, everything else to stderr
329
+
330
+ ### Shell completions
331
+
332
+ Generated from the command schema — always in sync:
333
+
334
+ ```ts
335
+ import { generateCompletion } from '@kjanat/dreamcli';
336
+
337
+ generateCompletion(myCli.schema, 'bash');
338
+ generateCompletion(myCli.schema, 'zsh');
339
+ ```
340
+
341
+ ### Config file discovery
342
+
343
+ ```ts
344
+ command('deploy').flag(
345
+ 'region',
346
+ flag.enum(['us', 'eu']).config('deploy.region'),
347
+ );
348
+ ```
349
+
350
+ Searches XDG-standard paths automatically. JSON built-in, plugin hook for YAML/TOML:
351
+
352
+ ```ts
353
+ import { configFormat } from '@kjanat/dreamcli';
354
+ import { parse as parseYAML } from 'yaml';
355
+
356
+ cli('mycli')
357
+ .config('mycli')
358
+ .configLoader(configFormat(['yaml', 'yml'], parseYAML));
359
+ ```
360
+
361
+ ### Structured errors
362
+
363
+ ```ts
364
+ throw new CLIError('Deployment failed', {
365
+ code: 'DEPLOY_FAILED',
366
+ exitCode: 1,
367
+ suggest: 'Check your credentials with `mycli login`',
368
+ details: { target, region },
369
+ });
370
+ ```
371
+
372
+ Parse and validation errors include "did you mean?" suggestions.\
373
+ In `--json` mode, errors serialize to machine-readable JSON.
374
+
375
+ ## Testing
376
+
377
+ `dreamcli`'s test harness runs commands in-process with full control over inputs and outputs. No
378
+ subprocesses, no `process.argv` mutation, no mocking.
379
+
380
+ ```ts
381
+ import { arg, command, flag } from '@kjanat/dreamcli';
382
+ import {
383
+ runCommand,
384
+ createTestPrompter,
385
+ PROMPT_CANCEL,
386
+ } from '@kjanat/dreamcli/testkit';
387
+
388
+ const greet = command('greet')
389
+ .arg('name', arg.string())
390
+ .flag('loud', flag.boolean())
391
+ .action(({ args, flags, out }) => {
392
+ const message = `Hello, ${args.name}!`;
393
+ out.log(flags.loud ? message.toUpperCase() : message);
394
+ });
395
+
396
+ const deploy = command('deploy')
397
+ .arg('target', arg.string())
398
+ .flag(
399
+ 'region',
400
+ flag
401
+ .enum(['us', 'eu', 'ap'])
402
+ .env('DEPLOY_REGION')
403
+ .config('deploy.region')
404
+ .required()
405
+ .prompt({ kind: 'select', message: 'Which region?' }),
406
+ )
407
+ .action(({ args, flags, out }) => {
408
+ out.log(`Deploying ${args.target} to ${flags.region}`);
409
+ });
410
+
411
+ const build = command('build').action(({ out }) => {
412
+ const spinner = out.spinner('Building');
413
+ spinner.succeed('Done');
414
+ });
415
+
416
+ // Basic execution
417
+ const basic = await runCommand(greet, ['Alice', '--loud']);
418
+
419
+ expect(basic.exitCode).toBe(0);
420
+ expect(basic.stdout).toEqual(['HELLO, ALICE!\n']);
421
+ expect(basic.stderr).toEqual([]);
422
+ expect(basic.error).toBeUndefined();
423
+
424
+ // Resolve from environment
425
+ const fromEnv = await runCommand(deploy, ['production'], {
426
+ env: { DEPLOY_REGION: 'eu' },
427
+ });
428
+ expect(fromEnv.stdout).toEqual([
429
+ 'Deploying production to eu\n',
430
+ ]);
431
+
432
+ // Resolve from config
433
+ const fromConfig = await runCommand(
434
+ deploy,
435
+ ['production'],
436
+ {
437
+ config: { deploy: { region: 'us' } },
438
+ },
439
+ );
440
+ expect(fromConfig.stdout).toEqual([
441
+ 'Deploying production to us\n',
442
+ ]);
443
+
444
+ // Resolve from prompt answers
445
+ const fromPrompt = await runCommand(
446
+ deploy,
447
+ ['production'],
448
+ {
449
+ answers: ['ap'],
450
+ },
451
+ );
452
+ expect(fromPrompt.stdout).toEqual([
453
+ 'Deploying production to ap\n',
454
+ ]);
455
+
456
+ // Simulate prompt cancellation
457
+ const cancelled = await runCommand(deploy, ['production'], {
458
+ prompter: createTestPrompter([PROMPT_CANCEL]),
459
+ });
460
+ expect(cancelled.exitCode).not.toBe(0);
461
+
462
+ // Activity events (spinners, progress)
463
+ const activity = await runCommand(build, []);
464
+ expect(activity.activity).toContainEqual(
465
+ expect.objectContaining({ type: 'spinner:start' }),
466
+ );
467
+ ```
468
+
469
+ `RunOptions` accepts: `env`, `config`, `stdinData`, `answers`, `prompter`, `help`, `jsonMode`,
470
+ `verbosity`, and `isTTY`. Every dimension of command behavior is controllable from tests.
471
+
472
+ ## Package structure
473
+
474
+ Three subpath exports, each with a focused API surface:
475
+
476
+ | Import | Purpose |
477
+ | -------------------------- | -------------------------------------------------------------------------------------- |
478
+ | `@kjanat/dreamcli` | Schema builders, CLI runner, output, parsing, resolution, errors |
479
+ | `@kjanat/dreamcli/testkit` | `runCommand()`, `createCaptureOutput()`, `createTestPrompter()`, `createTestAdapter()` |
480
+ | `@kjanat/dreamcli/runtime` | `createAdapter()`, `RuntimeAdapter`, runtime detection, platform adapters |
481
+
482
+ ESM-only. Source included in package (`src/`).
483
+
484
+ ## Runtime support
485
+
486
+ | Runtime | Status |
487
+ | ------------------ | ----------------------------------- |
488
+ | Node.js >= 22.22.2 | Supported |
489
+ | Bun >= 1.3.11 | Supported |
490
+ | Deno >= 2.6.0 | Supported (JSR: `@kjanat/dreamcli`) |
491
+
492
+ Runtime detection is automatic.
493
+ The core framework never imports platform-specific APIs directly — a thin `RuntimeAdapter` interface
494
+ handles the divergent edges (argv, env, filesystem, TTY detection, exit behavior).
495
+
496
+ ## License
497
+
498
+ [MIT][LICENSE] © 2026 Kaj Kowalski
499
+
500
+ [LICENSE]: https://github.com/kjanat/dreamcli/blob/master/LICENSE
501
+ [npm]: https://npm.im/@kjanat/dreamcli
502
+ [jsr]: https://jsr.io/@kjanat/dreamcli
@@ -0,0 +1,85 @@
1
+ import { CommandSchema, ErasedCommand } from "../schema/command.mjs";
2
+
3
+ //#region src/core/cli/dispatch.d.ts
4
+ /** Successful dispatch — target command found with argv path. */
5
+ interface DispatchMatch {
6
+ /** Discriminant — a command name in argv matched a registered command. */
7
+ readonly kind: 'match';
8
+ /** The matched (target) command. */
9
+ readonly command: ErasedCommand;
10
+ /** Root → target (inclusive). Used for `collectPropagatedFlags()`. */
11
+ readonly commandPath: readonly CommandSchema[];
12
+ /** argv after consuming command name segments. */
13
+ readonly remainingArgv: readonly string[];
14
+ }
15
+ /** Target has subcommands but no handler and no subcommand was specified/matched. */
16
+ interface DispatchNeedsSubcommand {
17
+ /** Discriminant — command group reached without a subcommand or handler. */
18
+ readonly kind: 'needs-subcommand';
19
+ /** The group command that needs a subcommand. */
20
+ readonly command: ErasedCommand;
21
+ /** Root → group (inclusive). */
22
+ readonly commandPath: readonly CommandSchema[];
23
+ }
24
+ /** Unknown command name at this dispatch level. */
25
+ interface DispatchUnknown {
26
+ /** Discriminant — no registered command matched the input token. */
27
+ readonly kind: 'unknown';
28
+ /** The unrecognised input token. Empty string when no token present. */
29
+ readonly input: string;
30
+ /** Commands available at the level where matching failed. */
31
+ readonly candidates: readonly ErasedCommand[];
32
+ /** Ancestor path up to (but not including) the unknown level. */
33
+ readonly parentPath: readonly CommandSchema[];
34
+ }
35
+ /** Discriminated result of recursive command dispatch. */
36
+ type DispatchResult = DispatchMatch | DispatchNeedsSubcommand | DispatchUnknown;
37
+ /**
38
+ * Recursively walk argv, consuming command name segments from the front.
39
+ *
40
+ * At each level, the first non-flag token is tested as a command name
41
+ * against the provided command map. If matched and the matched command
42
+ * has subcommands, dispatch recurses into the child level with the
43
+ * remaining argv.
44
+ *
45
+ * Ambiguity resolution for commands that have both an action handler AND
46
+ * subcommands (e.g. `git remote` lists remotes, `git remote add` dispatches):
47
+ * - If the next token matches a subcommand → descend
48
+ * - If the next token is unknown and the command has a handler → match here
49
+ * - If the next token is unknown and no handler → propagate unknown error
50
+ * - If no next token and command has a handler → match here
51
+ * - If no next token and no handler → needs-subcommand
52
+ *
53
+ * @param argv - Remaining argv tokens (command names + flags + args).
54
+ * @param commands - Command map at the current tree level.
55
+ * @param ancestorPath - Schema path from root to current level (exclusive).
56
+ * @returns Discriminated dispatch result.
57
+ *
58
+ * @internal
59
+ */
60
+ declare function dispatch(argv: readonly string[], commands: ReadonlyMap<string, ErasedCommand>, ancestorPath?: readonly CommandSchema[]): DispatchResult;
61
+ /**
62
+ * Levenshtein distance between two strings.
63
+ * @internal
64
+ */
65
+ declare function levenshtein(a: string, b: string): number;
66
+ /**
67
+ * Find the closest command name match for a "did you mean?" suggestion.
68
+ *
69
+ * Searches command names and aliases. Returns `undefined` if no
70
+ * sufficiently close match exists (threshold: 3).
71
+ *
72
+ * @internal
73
+ */
74
+ declare function findClosestCommand(input: string, commands: readonly ErasedCommand[]): string | undefined;
75
+ /**
76
+ * Deduplicate commands from a name+alias map.
77
+ *
78
+ * A map keyed by name *and* alias contains duplicate entries for aliased
79
+ * commands. This returns unique commands (by schema identity).
80
+ *
81
+ * @internal
82
+ */
83
+ declare function uniqueCommands(commands: ReadonlyMap<string, ErasedCommand>): readonly ErasedCommand[];
84
+ //#endregion
85
+ export { type DispatchMatch, type DispatchNeedsSubcommand, type DispatchResult, type DispatchUnknown, dispatch, findClosestCommand, levenshtein, uniqueCommands };
@@ -0,0 +1 @@
1
+ function e(t,n,i=[]){let a=-1;for(let e=0;e<t.length;e++){let n=t[e];if(n===`--`){e+1<t.length&&(a=e+1);break}if(n!==void 0&&!n.startsWith(`-`)){a=e;break}}if(a===-1)return{kind:`unknown`,input:``,candidates:r(n),parentPath:i};let o=t[a];if(o===void 0)return{kind:`unknown`,input:``,candidates:r(n),parentPath:i};let s=n.get(o);if(s===void 0)return{kind:`unknown`,input:o,candidates:r(n),parentPath:i};let c=[...t.slice(0,a),...t.slice(a+1)],l=[...i,s.schema];if(s.subcommands.size>0){let t=e(c,s.subcommands,l);switch(t.kind){case`match`:return t;case`unknown`:return t.input===``?s.schema.hasAction?{kind:`match`,command:s,commandPath:l,remainingArgv:c}:{kind:`needs-subcommand`,command:s,commandPath:l}:s.schema.hasAction?{kind:`match`,command:s,commandPath:l,remainingArgv:c}:t;case`needs-subcommand`:return t;default:return t}}return{kind:`match`,command:s,commandPath:l,remainingArgv:c}}function t(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 n(e,n){let r,i=4;for(let a of n){let n=t(e,a.schema.name);n<i&&(i=n,r=a.schema.name);for(let n of a.schema.aliases){let o=t(e,n);o<i&&(i=o,r=a.schema.name)}}return i<=3?r:void 0}function r(e){let t=new Set,n=[];for(let r of e.values())t.has(r)||(t.add(r),n.push(r));return n}export{e as dispatch,n as findClosestCommand};