@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.
- package/CHANGELOG.md +45 -6
- package/LICENSE +1 -1
- package/README.md +296 -164
- package/dist/core/cli/dispatch.d.mts +85 -0
- package/dist/core/cli/dispatch.mjs +1 -0
- package/dist/core/cli/index.d.mts +418 -0
- package/dist/core/cli/index.mjs +1 -0
- package/dist/core/cli/planner.d.mts +143 -0
- package/dist/core/cli/planner.mjs +1 -0
- package/dist/core/cli/plugin.d.mts +94 -0
- package/dist/core/cli/plugin.mjs +1 -0
- package/dist/core/cli/propagate.d.mts +39 -0
- package/dist/core/cli/propagate.mjs +1 -0
- package/dist/core/cli/root-help.d.mts +28 -0
- package/dist/core/cli/root-help.mjs +7 -0
- package/dist/core/cli/root-surface.d.mts +42 -0
- package/dist/core/cli/root-surface.mjs +1 -0
- package/dist/core/cli/runtime-preflight.d.mts +149 -0
- package/dist/core/cli/runtime-preflight.mjs +1 -0
- package/dist/core/completion/index.d.mts +46 -0
- package/dist/core/completion/index.mjs +1 -0
- package/dist/core/completion/shells/bash.d.mts +24 -0
- package/dist/core/completion/shells/bash.mjs +3 -0
- package/dist/core/completion/shells/fish.d.mts +20 -0
- package/dist/core/completion/shells/fish.mjs +2 -0
- package/dist/core/completion/shells/powershell.d.mts +14 -0
- package/dist/core/completion/shells/powershell.mjs +2 -0
- package/dist/core/completion/shells/shared.d.mts +139 -0
- package/dist/core/completion/shells/shared.mjs +1 -0
- package/dist/core/completion/shells/zsh.d.mts +24 -0
- package/dist/core/completion/shells/zsh.mjs +2 -0
- package/dist/core/config/index.d.mts +161 -0
- package/dist/core/config/index.mjs +1 -0
- package/dist/core/config/package-json.d.mts +68 -0
- package/dist/core/config/package-json.mjs +1 -0
- package/dist/core/errors/index.d.mts +126 -0
- package/dist/core/errors/index.mjs +1 -0
- package/dist/core/execution/index.d.mts +49 -0
- package/dist/core/execution/index.mjs +1 -0
- package/dist/core/help/index.d.mts +49 -0
- package/dist/core/help/index.mjs +8 -0
- package/dist/core/json-schema/index.d.mts +109 -0
- package/dist/core/json-schema/index.mjs +55 -0
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
- package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
- package/dist/core/output/activity.d.mts +194 -0
- package/dist/core/output/activity.mjs +1 -0
- package/dist/core/output/contracts.d.mts +88 -0
- package/dist/core/output/contracts.mjs +1 -0
- package/dist/core/output/display-value.d.mts +19 -0
- package/dist/core/output/display-value.mjs +1 -0
- package/dist/core/output/index.d.mts +280 -0
- package/dist/core/output/index.mjs +2 -0
- package/dist/core/output/renderers.d.mts +46 -0
- package/dist/core/output/renderers.mjs +1 -0
- package/dist/core/output/writer.d.mts +40 -0
- package/dist/core/output/writer.mjs +1 -0
- package/dist/core/parse/index.d.mts +79 -0
- package/dist/core/parse/index.mjs +1 -0
- package/dist/core/prompt/index.d.mts +205 -0
- package/dist/core/prompt/index.mjs +6 -0
- package/dist/core/resolve/args.d.mts +8 -0
- package/dist/core/resolve/args.mjs +1 -0
- package/dist/core/resolve/coerce.d.mts +22 -0
- package/dist/core/resolve/coerce.mjs +1 -0
- package/dist/core/resolve/config.d.mts +10 -0
- package/dist/core/resolve/config.mjs +1 -0
- package/dist/core/resolve/contracts.d.mts +112 -0
- package/dist/core/resolve/errors.d.mts +11 -0
- package/dist/core/resolve/errors.mjs +2 -0
- package/dist/core/resolve/flags.d.mts +10 -0
- package/dist/core/resolve/flags.mjs +1 -0
- package/dist/core/resolve/index.d.mts +42 -0
- package/dist/core/resolve/index.mjs +1 -0
- package/dist/core/resolve/property.d.mts +47 -0
- package/dist/core/resolve/property.mjs +1 -0
- package/dist/core/schema/activity.d.mts +169 -0
- package/dist/core/schema/arg.d.mts +559 -0
- package/dist/core/schema/arg.mjs +1 -0
- package/dist/core/schema/command.d.mts +960 -0
- package/dist/core/schema/command.mjs +1 -0
- package/dist/core/schema/flag.d.mts +491 -0
- package/dist/core/schema/flag.mjs +1 -0
- package/dist/core/schema/index.d.mts +8 -0
- package/dist/core/schema/middleware.d.mts +122 -0
- package/dist/core/schema/middleware.mjs +1 -0
- package/dist/core/schema/prompt.d.mts +117 -0
- package/dist/core/schema/run.d.mts +171 -0
- package/dist/core/schema-dsl/runtime.d.mts +144 -0
- package/dist/core/schema-dsl/runtime.mjs +2 -0
- package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
- package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
- package/dist/core/testkit/index.d.mts +54 -0
- package/dist/core/testkit/index.mjs +1 -0
- package/dist/index.d.mts +28 -920
- package/dist/index.mjs +1 -10
- package/dist/runtime/adapter.d.mts +212 -0
- package/dist/{adapter-B37d9oia.mjs → runtime/adapter.mjs} +1 -1
- package/dist/runtime/auto.d.mts +26 -0
- package/dist/runtime/auto.mjs +1 -0
- package/dist/runtime/bun.d.mts +28 -0
- package/dist/runtime/bun.mjs +1 -0
- package/dist/runtime/deno.d.mts +76 -0
- package/dist/runtime/deno.mjs +2 -0
- package/dist/runtime/detect.d.mts +86 -0
- package/dist/runtime/detect.mjs +1 -0
- package/dist/runtime/index.d.mts +7 -0
- package/dist/runtime/node.d.mts +65 -0
- package/dist/runtime/node.mjs +2 -0
- package/dist/runtime/paths.d.mts +31 -0
- package/dist/runtime/paths.mjs +1 -0
- package/dist/runtime/support.d.mts +42 -0
- package/dist/runtime/support.mjs +1 -0
- package/dist/runtime.d.mts +6 -252
- package/dist/runtime.mjs +1 -1
- package/dist/testkit.d.mts +5 -24
- package/dist/testkit.mjs +1 -1
- package/dist/version.d.mts +16 -0
- package/dist/version.mjs +1 -0
- package/dreamcli.schema.json +338 -0
- package/examples/basic.ts +2 -2
- package/examples/gh/package.json +7 -11
- package/examples/gh/src/commands/auth.ts +2 -2
- package/examples/gh/src/commands/issue.ts +4 -4
- package/examples/gh/src/commands/pr.ts +4 -4
- package/examples/gh/src/docs.ts +11 -0
- package/examples/gh/src/lib/auth.ts +1 -1
- package/examples/gh/src/main.test.ts +6 -5
- package/examples/gh/src/main.ts +8 -6
- package/examples/interactive.ts +3 -3
- package/examples/json-mode.ts +4 -6
- package/examples/middleware.ts +3 -3
- package/examples/multi-command.ts +3 -3
- package/examples/spinner-progress.ts +5 -5
- package/examples/testing.ts +8 -6
- package/package.json +70 -44
- package/src/core/cli/dispatch.ts +4 -0
- package/src/core/cli/index.ts +185 -632
- package/src/core/cli/planner.ts +413 -0
- package/src/core/cli/plugin.ts +7 -1
- package/src/core/cli/propagate.ts +1 -1
- package/src/core/cli/runtime-preflight.ts +409 -0
- package/src/core/completion/index.ts +15 -9
- package/src/core/completion/shells/bash.ts +6 -3
- package/src/core/completion/shells/fish.ts +245 -10
- package/src/core/completion/shells/powershell.ts +390 -9
- package/src/core/completion/shells/shared.ts +4 -4
- package/src/core/completion/shells/zsh.ts +12 -7
- package/src/core/config/index.ts +7 -4
- package/src/core/config/package-json.ts +6 -2
- package/src/core/errors/index.ts +23 -8
- package/src/core/execution/index.ts +270 -0
- package/src/core/help/index.ts +13 -15
- package/src/core/json-schema/index.ts +193 -7
- package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
- package/src/core/output/contracts.ts +194 -0
- package/src/core/output/index.ts +47 -82
- package/src/core/output/renderers.ts +125 -0
- package/src/core/parse/index.ts +39 -21
- package/src/core/prompt/index.ts +44 -27
- package/src/core/resolve/args.ts +144 -0
- package/src/core/resolve/coerce.ts +432 -0
- package/src/core/resolve/config.ts +26 -0
- package/src/core/resolve/contracts.ts +135 -0
- package/src/core/resolve/errors.ts +227 -0
- package/src/core/resolve/flags.ts +205 -0
- package/src/core/resolve/index.ts +41 -1264
- package/src/core/resolve/property.ts +99 -0
- package/src/core/schema/activity.ts +3 -0
- package/src/core/schema/arg.ts +26 -14
- package/src/core/schema/command.ts +265 -38
- package/src/core/schema/flag.ts +120 -15
- package/src/core/schema/index.ts +11 -2
- package/src/core/schema/middleware.ts +6 -6
- package/src/core/schema/prompt.ts +9 -1
- package/src/core/schema/run.ts +25 -17
- package/src/core/schema-dsl/index.ts +109 -0
- package/src/core/schema-dsl/parse.ts +262 -0
- package/src/core/schema-dsl/runtime.ts +609 -0
- package/src/core/schema-dsl/to-json-schema.ts +102 -0
- package/src/core/testkit/index.ts +55 -297
- package/src/index.ts +10 -4
- package/src/runtime/adapter.ts +13 -10
- package/src/runtime/auto.ts +3 -3
- package/src/runtime/bun.ts +4 -4
- package/src/runtime/deno.ts +43 -29
- package/src/runtime/detect.ts +4 -1
- package/src/runtime/index.ts +1 -1
- package/src/runtime/node.ts +43 -21
- package/src/runtime/paths.ts +9 -3
- package/src/runtime/support.ts +20 -4
- package/src/runtime.ts +1 -1
- package/src/testkit.ts +10 -8
- package/dist/adapter-CCSh5juX.cjs +0 -1
- package/dist/adapter-DIwO-q7K.d.mts +0 -3447
- package/dist/adapter-DQnxxLiE.d.cts +0 -3447
- package/dist/auto-5cjZaF9V.mjs +0 -3
- package/dist/auto-B0eSgoDw.cjs +0 -3
- package/dist/index.cjs +0 -10
- package/dist/index.d.cts +0 -920
- package/dist/runtime.cjs +0 -1
- package/dist/runtime.d.cts +0 -253
- package/dist/testkit-CEDYPvhF.mjs +0 -14
- package/dist/testkit-ClIKijxC.cjs +0 -14
- package/dist/testkit.cjs +0 -1
- package/dist/testkit.d.cts +0 -25
- package/examples/gh/tsconfig.json +0 -37
- package/examples/tsconfig.json +0 -17
- package/src/core/cli/AGENTS.md +0 -72
- package/src/core/completion/AGENTS.md +0 -72
- package/src/core/completion/completion-test-helpers.ts +0 -48
- package/src/core/output/AGENTS.md +0 -69
- package/src/core/resolve/AGENTS.md +0 -69
- package/src/core/schema/AGENTS.md +0 -61
- package/src/core/testkit/AGENTS.md +0 -55
- package/src/runtime/AGENTS.md +0 -74
- package/src/runtime/test-helpers.ts +0 -40
package/README.md
CHANGED
|
@@ -1,29 +1,39 @@
|
|
|
1
1
|
# dreamcli
|
|
2
2
|
|
|
3
|
+
[][npm]
|
|
4
|
+
[][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 {
|
|
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
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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
|
-
#
|
|
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
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
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 {
|
|
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
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
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
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
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
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
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
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
138
|
+
.description('Seed database')
|
|
139
|
+
.action(({ out }) => {
|
|
140
|
+
out.log('seeding');
|
|
141
|
+
});
|
|
105
142
|
|
|
106
|
-
const db = group('db')
|
|
143
|
+
const db = group('db')
|
|
144
|
+
.description('Database operations')
|
|
145
|
+
.command(migrate)
|
|
146
|
+
.command(seed);
|
|
107
147
|
|
|
108
148
|
cli('mycli')
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
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.
|
|
125
|
-
then use parsed values somewhere else as a loosely typed blob.
|
|
126
|
-
interactive prompts live in separate universes.
|
|
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 |
|
|
134
|
-
| ------------------------------------------ | ------------------- | ---------------------- | --------------- | ------------- | ------------- |
|
|
135
|
-
| Type inference from definition | Manual `.opts<T>()` | Good | Good | Basic | Good |
|
|
136
|
-
| Built-in value sources | CLI, defaults, env | CLI, env, config | CLI, defaults | CLI, defaults | CLI, defaults |
|
|
137
|
-
| Schema-driven prompts | No | No | No | No | No |
|
|
138
|
-
| Middleware / hooks | Lifecycle hooks | Middleware | Plugins / hooks | Events | No |
|
|
139
|
-
| Built-in test harness with output capture | No | No | No | No | No |
|
|
140
|
-
| Shell completions from command definitions | No | Built-in (bash/zsh) | No | No | No |
|
|
141
|
-
| Structured output primitives | DIY | DIY | DIY | DIY | DIY |
|
|
142
|
-
| Config file support | DIY | Built-in (`.config()`) | No | No | No |
|
|
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,
|
|
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
|
-
|
|
185
|
-
|
|
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
|
-
|
|
190
|
-
|
|
191
|
-
|
|
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
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
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 }>(
|
|
224
|
-
|
|
225
|
-
|
|
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 }>(
|
|
229
|
-
|
|
280
|
+
const trace = middleware<{ traceId: string }>(
|
|
281
|
+
async ({ next }) =>
|
|
282
|
+
next({ traceId: crypto.randomUUID() }),
|
|
230
283
|
);
|
|
231
284
|
|
|
232
285
|
command('deploy')
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
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.
|
|
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
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
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(
|
|
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
|
-
|
|
292
|
-
|
|
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
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
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
|
|
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 {
|
|
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
|
|
319
|
-
|
|
320
|
-
expect(
|
|
321
|
-
expect(
|
|
322
|
-
expect(
|
|
323
|
-
expect(
|
|
324
|
-
|
|
325
|
-
//
|
|
326
|
-
const
|
|
327
|
-
|
|
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
|
|
334
|
-
|
|
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
|
-
|
|
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`, `
|
|
342
|
-
`
|
|
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
|
|
349
|
-
|
|
|
350
|
-
|
|
|
351
|
-
|
|
|
352
|
-
|
|
|
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
|
-
|
|
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.
|
|
365
|
-
|
|
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]
|
|
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
|