@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.
- package/CHANGELOG.md +706 -0
- package/LICENSE +22 -0
- package/README.md +502 -0
- 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 -0
- package/dist/index.mjs +1 -0
- package/dist/runtime/adapter.d.mts +212 -0
- package/dist/runtime/adapter.mjs +1 -0
- 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 +7 -0
- package/dist/runtime.mjs +1 -0
- package/dist/testkit.d.mts +6 -0
- package/dist/testkit.mjs +1 -0
- package/dist/version.d.mts +16 -0
- package/dist/version.mjs +1 -0
- package/dreamcli.schema.json +338 -0
- package/examples/basic.ts +33 -0
- package/examples/gh/package.json +44 -0
- package/examples/gh/src/commands/auth.ts +66 -0
- package/examples/gh/src/commands/issue.ts +120 -0
- package/examples/gh/src/commands/pr.ts +125 -0
- package/examples/gh/src/data/issues.yaml +5 -0
- package/examples/gh/src/data/issues.yaml.d.ts +17 -0
- package/examples/gh/src/data/pull-requests.yaml +7 -0
- package/examples/gh/src/data/pull-requests.yaml.d.ts +18 -0
- package/examples/gh/src/docs.ts +11 -0
- package/examples/gh/src/lib/auth.ts +37 -0
- package/examples/gh/src/lib/utils.ts +17 -0
- package/examples/gh/src/main.test.ts +307 -0
- package/examples/gh/src/main.ts +40 -0
- package/examples/interactive.ts +66 -0
- package/examples/json-mode.ts +91 -0
- package/examples/middleware.ts +71 -0
- package/examples/multi-command.ts +66 -0
- package/examples/spinner-progress.ts +49 -0
- package/examples/testing.ts +147 -0
- package/package.json +149 -2
- package/src/core/cli/dispatch.ts +286 -0
- package/src/core/cli/index.ts +978 -0
- package/src/core/cli/planner.ts +413 -0
- package/src/core/cli/plugin.ts +117 -0
- package/src/core/cli/propagate.ts +97 -0
- package/src/core/cli/root-help.ts +269 -0
- package/src/core/cli/root-surface.ts +74 -0
- package/src/core/cli/runtime-preflight.ts +409 -0
- package/src/core/completion/index.ts +88 -0
- package/src/core/completion/shells/bash.ts +459 -0
- package/src/core/completion/shells/fish.ts +259 -0
- package/src/core/completion/shells/powershell.ts +405 -0
- package/src/core/completion/shells/shared.ts +283 -0
- package/src/core/completion/shells/zsh.ts +381 -0
- package/src/core/config/index.ts +407 -0
- package/src/core/config/package-json.ts +220 -0
- package/src/core/errors/index.ts +193 -0
- package/src/core/execution/index.ts +270 -0
- package/src/core/help/index.ts +557 -0
- package/src/core/json-schema/index.ts +891 -0
- package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
- package/src/core/output/activity.ts +568 -0
- package/src/core/output/contracts.ts +194 -0
- package/src/core/output/display-value.ts +48 -0
- package/src/core/output/index.ts +669 -0
- package/src/core/output/renderers.ts +125 -0
- package/src/core/output/writer.ts +46 -0
- package/src/core/parse/index.ts +661 -0
- package/src/core/prompt/index.ts +583 -0
- 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 +108 -0
- package/src/core/resolve/property.ts +99 -0
- package/src/core/schema/activity.ts +240 -0
- package/src/core/schema/arg.ts +719 -0
- package/src/core/schema/command.ts +1490 -0
- package/src/core/schema/flag.ts +756 -0
- package/src/core/schema/index.ts +91 -0
- package/src/core/schema/middleware.ts +171 -0
- package/src/core/schema/prompt.ts +156 -0
- package/src/core/schema/run.ts +195 -0
- 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 +123 -0
- package/src/index.ts +170 -0
- package/src/runtime/adapter.ts +303 -0
- package/src/runtime/auto.ts +110 -0
- package/src/runtime/bun.ts +55 -0
- package/src/runtime/deno.ts +369 -0
- package/src/runtime/detect.ts +105 -0
- package/src/runtime/index.ts +21 -0
- package/src/runtime/node-builtins.d.ts +23 -0
- package/src/runtime/node.ts +300 -0
- package/src/runtime/paths.ts +62 -0
- package/src/runtime/support.ts +135 -0
- package/src/runtime.ts +31 -0
- package/src/testkit.ts +25 -0
- 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]
|
|
4
|
+
[][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};
|