@kjanat/dreamcli 1.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 (217) hide show
  1. package/CHANGELOG.md +45 -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
package/README.md CHANGED
@@ -1,29 +1,39 @@
1
1
  # dreamcli
2
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
+
3
6
  Schema-first, fully typed TypeScript CLI framework. Zero runtime dependencies.
4
7
 
5
8
  One flag declaration configures the entire resolution pipeline:
6
9
 
7
10
  ```ts
8
- import { cli, command, flag, arg, middleware, CLIError } from 'dreamcli';
11
+ import {
12
+ cli,
13
+ command,
14
+ flag,
15
+ arg,
16
+ middleware,
17
+ CLIError,
18
+ } from '@kjanat/dreamcli';
9
19
 
10
20
  const deploy = command('deploy')
11
- .description('Deploy to an environment')
12
- .arg('target', arg.string().describe('Deploy target'))
13
- .flag(
14
- 'region',
15
- flag
16
- .enum(['us', 'eu', 'ap'])
17
- .alias('r')
18
- .env('DEPLOY_REGION')
19
- .config('deploy.region')
20
- .prompt({ kind: 'select', message: 'Which region?' })
21
- .default('us')
22
- .propagate(),
23
- )
24
- .action(({ args, flags, out }) => {
25
- out.log(`Deploying ${args.target} to ${flags.region}`);
26
- });
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
+ });
27
37
  ```
28
38
 
29
39
  By the time `action` runs, `flags.region` is `"us" | "eu" | "ap"` — not `string | undefined`.
@@ -34,36 +44,48 @@ default**. Every step is opt-in. Every step preserves types.
34
44
  ## Install
35
45
 
36
46
  ```bash
37
- npm install dreamcli
47
+ npm install @kjanat/dreamcli
38
48
  ```
39
49
 
50
+ <details><summary>bun/deno</summary>
51
+
40
52
  ```bash
41
- bun add dreamcli
53
+ bun add @kjanat/dreamcli
42
54
  ```
43
55
 
44
56
  ```bash
45
- # Deno (JSR)
46
- deno add jsr:@kjanat/dreamcli
57
+ deno add jsr:@kjanat/dreamcli # or npm:@kjanat/dreamcli
47
58
  ```
48
59
 
60
+ </details>
61
+
49
62
  ## Quick start
50
63
 
51
64
  ### Single command
52
65
 
53
66
  ```ts
54
- import { command, flag, arg } from 'dreamcli';
67
+ import { command, flag, arg } from '@kjanat/dreamcli';
55
68
 
56
69
  const greet = command('greet')
57
- .description('Greet someone')
58
- .arg('name', arg.string().describe('Who to greet'))
59
- .flag('loud', flag.boolean().alias('l').describe('Shout the greeting'))
60
- .flag('times', flag.number().default(1).describe('Repeat count'))
61
- .action(({ args, flags, out }) => {
62
- for (let i = 0; i < flags.times; i++) {
63
- const msg = `Hello, ${args.name}!`;
64
- out.log(flags.loud ? msg.toUpperCase() : msg);
65
- }
66
- });
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
+ });
67
89
 
68
90
  greet.run();
69
91
  ```
@@ -71,47 +93,65 @@ greet.run();
71
93
  ### Multi-command CLI
72
94
 
73
95
  ```ts
74
- import { cli, command, group, flag, arg } from 'dreamcli';
96
+ import {
97
+ cli,
98
+ command,
99
+ group,
100
+ flag,
101
+ arg,
102
+ } from '@kjanat/dreamcli';
75
103
 
76
104
  const deploy = command('deploy')
77
- .description('Deploy to an environment')
78
- .arg('target', arg.string())
79
- .flag('force', flag.boolean().alias('f'))
80
- .flag('region', flag.enum(['us', 'eu', 'ap']).env('DEPLOY_REGION'))
81
- .action(({ args, flags, out }) => {
82
- out.log(`Deploying ${args.target} to ${flags.region ?? 'default'}`);
83
- });
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
+ });
84
117
 
85
118
  const login = command('login')
86
- .description('Authenticate with the service')
87
- .flag('token', flag.string().describe('Auth token'))
88
- .action(({ flags, out }) => {
89
- out.log(flags.token ? 'Authenticated via token' : 'Authenticated interactively');
90
- });
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
+ });
91
128
 
92
129
  // Nested command groups
93
130
  const migrate = command('migrate')
94
- .description('Run migrations')
95
- .flag('steps', flag.number())
96
- .action(({ flags, out }) => {
97
- out.log(`migrating ${flags.steps ?? 'all'} steps`);
98
- });
131
+ .description('Run migrations')
132
+ .flag('steps', flag.number())
133
+ .action(({ flags, out }) => {
134
+ out.log(`migrating ${flags.steps ?? 'all'} steps`);
135
+ });
99
136
 
100
137
  const seed = command('seed')
101
- .description('Seed database')
102
- .action(({ out }) => {
103
- out.log('seeding');
104
- });
138
+ .description('Seed database')
139
+ .action(({ out }) => {
140
+ out.log('seeding');
141
+ });
105
142
 
106
- const db = group('db').description('Database operations').command(migrate).command(seed);
143
+ const db = group('db')
144
+ .description('Database operations')
145
+ .command(migrate)
146
+ .command(seed);
107
147
 
108
148
  cli('mycli')
109
- .version('1.0.0')
110
- .description('My awesome tool')
111
- .command(deploy)
112
- .command(login)
113
- .command(db)
114
- .run();
149
+ .version('1.0.0')
150
+ .description('My awesome tool')
151
+ .command(deploy)
152
+ .command(login)
153
+ .command(db)
154
+ .run();
115
155
 
116
156
  // mycli deploy production --force
117
157
  // mycli login --token abc123
@@ -121,28 +161,29 @@ cli('mycli')
121
161
 
122
162
  ## Why dreamcli
123
163
 
124
- Most TypeScript CLI frameworks treat the type system like decoration. You define flags in one place,
125
- then use parsed values somewhere else as a loosely typed blob. Env vars, config files, and
126
- interactive prompts live in separate universes. Testing means hacking `process.argv`.
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`.
127
168
 
128
169
  dreamcli collapses all of that into a single typed schema:
129
170
 
130
171
  Approximate comparison of first-party, built-in support as documented by each project.
131
172
  Third-party plugins and custom glue can extend the other libraries.
132
173
 
133
- | Capability | Commander | Yargs | Citty | CAC | Cleye | dreamcli |
134
- | ------------------------------------------ | ------------------- | ---------------------- | --------------- | ------------- | ------------- | ------------------------------------- |
135
- | Type inference from definition | Manual `.opts<T>()` | Good | Good | Basic | Good | Full — flags, args, context |
136
- | Built-in value sources | CLI, defaults, env | CLI, env, config | CLI, defaults | CLI, defaults | CLI, defaults | CLI, env, config, prompt, default |
137
- | Schema-driven prompts | No | No | No | No | No | Integrated |
138
- | Middleware / hooks | Lifecycle hooks | Middleware | Plugins / hooks | Events | No | Yes — typed middleware |
139
- | Built-in test harness with output capture | No | No | No | No | No | `runCommand()` + capture |
140
- | Shell completions from command definitions | No | Built-in (bash/zsh) | No | No | No | Built-in (bash/zsh) |
141
- | Structured output primitives | DIY | DIY | DIY | DIY | DIY | Built-in (`--json`, tables, spinners) |
142
- | Config file support | DIY | Built-in (`.config()`) | No | No | No | Built-in (XDG discovery, JSON) |
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 |
143
184
 
144
- The closest analog is what tRPC did to API routes — individual pieces existed, the insight was
145
- wiring them so types flow end-to-end.
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.
146
187
 
147
188
  ## Features
148
189
 
@@ -164,7 +205,7 @@ Every flag supports: `.default()`, `.required()`, `.alias()`, `.env()`, `.config
164
205
 
165
206
  Each flag resolves through an ordered pipeline. Every step is opt-in:
166
207
 
167
- ```
208
+ ```text
168
209
  CLI argv → environment variable → config file → interactive prompt → default value
169
210
  ```
170
211
 
@@ -178,38 +219,47 @@ Four prompt types, declared per-flag or per-command:
178
219
  ```ts
179
220
  // Per-flag
180
221
  flag.string().prompt({ kind: 'input', message: 'Name?' });
181
- flag.boolean().prompt({ kind: 'confirm', message: 'Sure?' });
182
- flag.enum(['a', 'b']).prompt({ kind: 'select', message: 'Pick one' });
183
222
  flag
184
- .array(flag.string())
185
- .prompt({ kind: 'multiselect', message: 'Pick many', choices: [{ value: 'a' }, { value: 'b' }] });
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
+ });
186
233
 
187
234
  // Per-command (conditional — receives partially resolved flags)
188
235
  command('deploy')
189
- .flag('region', flag.enum(['us', 'eu', 'ap']))
190
- .interactive(({ flags }) => ({
191
- region: !flags.region && { kind: 'select', message: 'Which region?' },
192
- }));
236
+ .flag('region', flag.enum(['us', 'eu', 'ap']))
237
+ .interactive(({ flags }) => ({
238
+ region: !flags.region && {
239
+ kind: 'select',
240
+ message: 'Which region?',
241
+ },
242
+ }));
193
243
  ```
194
244
 
195
245
  ### Derive typed context from resolved input
196
246
 
197
247
  ```ts
198
- import { CLIError } from 'dreamcli';
248
+ import { CLIError } from '@kjanat/dreamcli';
199
249
 
200
250
  command('deploy')
201
- .flag('token', flag.string().env('AUTH_TOKEN'))
202
- .derive(({ flags }) => {
203
- if (!flags.token)
204
- throw new CLIError('Not authenticated', {
205
- code: 'AUTH_REQUIRED',
206
- suggest: 'Run `mycli login`',
207
- });
208
- return { token: flags.token };
209
- })
210
- .action(({ ctx }) => {
211
- ctx.token; // string — typed
212
- });
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
+ });
213
263
  ```
214
264
 
215
265
  Use `derive()` when you need typed, command-scoped access to fully resolved flags and args before
@@ -218,27 +268,32 @@ the action handler runs.
218
268
  ### Middleware with typed context
219
269
 
220
270
  ```ts
221
- import { middleware } from 'dreamcli';
271
+ import { middleware } from '@kjanat/dreamcli';
222
272
 
223
- const timing = middleware<{ startTime: number }>(async ({ next }) => {
224
- const startTime = Date.now();
225
- await next({ startTime });
226
- });
273
+ const timing = middleware<{ startTime: number }>(
274
+ async ({ next }) => {
275
+ const startTime = Date.now();
276
+ await next({ startTime });
277
+ },
278
+ );
227
279
 
228
- const trace = middleware<{ traceId: string }>(async ({ next }) =>
229
- next({ traceId: crypto.randomUUID() }),
280
+ const trace = middleware<{ traceId: string }>(
281
+ async ({ next }) =>
282
+ next({ traceId: crypto.randomUUID() }),
230
283
  );
231
284
 
232
285
  command('deploy')
233
- .middleware(timing)
234
- .middleware(trace)
235
- .action(({ ctx }) => {
236
- ctx.startTime; // number — typed
237
- ctx.traceId; // string — typed
238
- });
286
+ .middleware(timing)
287
+ .middleware(trace)
288
+ .action(({ ctx }) => {
289
+ ctx.startTime; // number — typed
290
+ ctx.traceId; // string — typed
291
+ });
239
292
  ```
240
293
 
241
- Context accumulates through the middleware chain via type intersection. No manual interface merging.
294
+ Context accumulates through the middleware chain via type intersection.
295
+ No manual interface merging.
296
+
242
297
  Use middleware when you need wrapper behavior with `next()`.
243
298
 
244
299
  ### Output channel
@@ -246,18 +301,26 @@ Use middleware when you need wrapper behavior with `next()`.
246
301
  Handlers receive `out` instead of `console`. Adapts to context automatically:
247
302
 
248
303
  ```ts
249
- .action(({ out }) => {
250
- out.log('Human-readable message');
251
- out.json({ status: 'ok', count: 42 });
252
- out.table(rows, [{ key: 'name', header: 'Name' }, { key: 'status', header: 'Status' }]);
253
-
254
- const spinner = out.spinner('Deploying...');
255
- spinner.succeed('Done');
256
-
257
- const progress = out.progress({ label: 'Uploading', total: 100 });
258
- progress.update(50);
259
- progress.done('Upload complete');
260
- })
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
+ });
261
324
  ```
262
325
 
263
326
  - TTY → pretty formatting, spinners animate
@@ -269,7 +332,7 @@ Handlers receive `out` instead of `console`. Adapts to context automatically:
269
332
  Generated from the command schema — always in sync:
270
333
 
271
334
  ```ts
272
- import { generateCompletion } from 'dreamcli';
335
+ import { generateCompletion } from '@kjanat/dreamcli';
273
336
 
274
337
  generateCompletion(myCli.schema, 'bash');
275
338
  generateCompletion(myCli.schema, 'zsh');
@@ -278,80 +341,145 @@ generateCompletion(myCli.schema, 'zsh');
278
341
  ### Config file discovery
279
342
 
280
343
  ```ts
281
- command('deploy').flag('region', flag.enum(['us', 'eu']).config('deploy.region'));
344
+ command('deploy').flag(
345
+ 'region',
346
+ flag.enum(['us', 'eu']).config('deploy.region'),
347
+ );
282
348
  ```
283
349
 
284
350
  Searches XDG-standard paths automatically. JSON built-in, plugin hook for YAML/TOML:
285
351
 
286
352
  ```ts
287
- import { configFormat } from 'dreamcli';
353
+ import { configFormat } from '@kjanat/dreamcli';
288
354
  import { parse as parseYAML } from 'yaml';
289
355
 
290
356
  cli('mycli')
291
- .config('mycli')
292
- .configLoader(configFormat(['yaml', 'yml'], parseYAML));
357
+ .config('mycli')
358
+ .configLoader(configFormat(['yaml', 'yml'], parseYAML));
293
359
  ```
294
360
 
295
361
  ### Structured errors
296
362
 
297
363
  ```ts
298
364
  throw new CLIError('Deployment failed', {
299
- code: 'DEPLOY_FAILED',
300
- exitCode: 1,
301
- suggest: 'Check your credentials with `mycli login`',
302
- details: { target, region },
365
+ code: 'DEPLOY_FAILED',
366
+ exitCode: 1,
367
+ suggest: 'Check your credentials with `mycli login`',
368
+ details: { target, region },
303
369
  });
304
370
  ```
305
371
 
306
- Parse and validation errors include "did you mean?" suggestions. In `--json` mode, errors serialize
307
- to machine-readable JSON.
372
+ Parse and validation errors include "did you mean?" suggestions.\
373
+ In `--json` mode, errors serialize to machine-readable JSON.
308
374
 
309
375
  ## Testing
310
376
 
311
- dreamcli's test harness runs commands in-process with full control over inputs and outputs. No
377
+ `dreamcli`'s test harness runs commands in-process with full control over inputs and outputs. No
312
378
  subprocesses, no `process.argv` mutation, no mocking.
313
379
 
314
380
  ```ts
315
- import { runCommand, createTestPrompter, PROMPT_CANCEL } from 'dreamcli/testkit';
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
+ });
316
415
 
317
416
  // Basic execution
318
- const result = await runCommand(greet, ['Alice', '--loud']);
319
-
320
- expect(result.exitCode).toBe(0);
321
- expect(result.stdout).toEqual(['HELLO, ALICE!\n']);
322
- expect(result.stderr).toEqual([]);
323
- expect(result.error).toBeUndefined();
324
-
325
- // With environment, config, and prompt answers
326
- const result = await runCommand(deploy, ['production'], {
327
- env: { DEPLOY_REGION: 'eu' },
328
- config: { deploy: { region: 'us' } },
329
- answers: ['ap'], // prompt answers consumed in order
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' },
330
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
+ ]);
331
455
 
332
456
  // Simulate prompt cancellation
333
- const result = await runCommand(cmd, [], {
334
- prompter: createTestPrompter([PROMPT_CANCEL]),
457
+ const cancelled = await runCommand(deploy, ['production'], {
458
+ prompter: createTestPrompter([PROMPT_CANCEL]),
335
459
  });
460
+ expect(cancelled.exitCode).not.toBe(0);
336
461
 
337
462
  // Activity events (spinners, progress)
338
- expect(result.activity).toContainEqual(expect.objectContaining({ type: 'spinner:start' }));
463
+ const activity = await runCommand(build, []);
464
+ expect(activity.activity).toContainEqual(
465
+ expect.objectContaining({ type: 'spinner:start' }),
466
+ );
339
467
  ```
340
468
 
341
- `RunOptions` accepts: `env`, `config`, `answers`, `prompter`, `help`, `json`, `verbosity`,
342
- `adapter`, and more. Every dimension of CLI behavior is controllable from tests.
469
+ `RunOptions` accepts: `env`, `config`, `stdinData`, `answers`, `prompter`, `help`, `jsonMode`,
470
+ `verbosity`, and `isTTY`. Every dimension of command behavior is controllable from tests.
343
471
 
344
472
  ## Package structure
345
473
 
346
474
  Three subpath exports, each with a focused API surface:
347
475
 
348
- | Import | Purpose |
349
- | ------------------ | -------------------------------------------------------------------------------------- |
350
- | `dreamcli` | Schema builders, CLI runner, output, parsing, resolution, errors |
351
- | `dreamcli/testkit` | `runCommand()`, `createCaptureOutput()`, `createTestPrompter()`, `createTestAdapter()` |
352
- | `dreamcli/runtime` | `createAdapter()`, `RuntimeAdapter`, runtime detection, platform adapters |
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 |
353
481
 
354
- Dual ESM/CJS. Source included in package (`src/`).
482
+ ESM-only. Source included in package (`src/`).
355
483
 
356
484
  ## Runtime support
357
485
 
@@ -361,10 +489,14 @@ Dual ESM/CJS. Source included in package (`src/`).
361
489
  | Bun >= 1.3.11 | Supported |
362
490
  | Deno >= 2.6.0 | Supported (JSR: `@kjanat/dreamcli`) |
363
491
 
364
- Runtime detection is automatic. The core framework never imports platform-specific APIs directly — a
365
- thin `RuntimeAdapter` interface handles the divergent edges (argv, env, filesystem, TTY detection,
366
- exit behavior).
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).
367
495
 
368
496
  ## License
369
497
 
370
- [MIT](LICENSE)
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