@kjanat/dreamcli 3.0.0 → 4.0.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +967 -1
- package/README.md +9 -3
- package/dist/core/cli/builtins.d.mts +47 -0
- package/dist/core/cli/builtins.mjs +135 -0
- package/dist/core/cli/compiled.d.mts +29 -0
- package/dist/core/cli/compiled.mjs +76 -0
- package/dist/core/cli/dispatch.d.mts +9 -85
- package/dist/core/cli/help-links.d.mts +2 -14
- package/dist/core/cli/index.d.mts +282 -101
- package/dist/core/cli/index.mjs +497 -264
- package/dist/core/cli/planner.d.mts +13 -86
- package/dist/core/cli/planner.mjs +47 -30
- package/dist/core/cli/plugin.d.mts +1 -1
- package/dist/core/cli/propagate.mjs +1 -1
- package/dist/core/cli/reserved-flags.d.mts +1 -0
- package/dist/core/cli/reserved-flags.mjs +158 -0
- package/dist/core/cli/root-help.d.mts +1 -47
- package/dist/core/cli/root-help.mjs +37 -47
- package/dist/core/cli/root-output-flags.d.mts +1 -0
- package/dist/core/cli/root-output-flags.mjs +169 -0
- package/dist/core/cli/root-surface.d.mts +1 -68
- package/dist/core/cli/root-surface.mjs +2 -2
- package/dist/core/cli/runtime-preflight.d.mts +1 -199
- package/dist/core/cli/runtime-preflight.mjs +67 -17
- package/dist/core/completion/index.d.mts +2 -2
- package/dist/core/completion/shells/bash.d.mts +0 -1
- package/dist/core/completion/shells/bash.mjs +2 -1
- package/dist/core/completion/shells/fish.d.mts +0 -1
- package/dist/core/completion/shells/fish.mjs +2 -1
- package/dist/core/completion/shells/powershell.d.mts +0 -1
- package/dist/core/completion/shells/powershell.mjs +2 -1
- package/dist/core/completion/shells/shared.d.mts +3 -114
- package/dist/core/completion/shells/shared.mjs +9 -39
- package/dist/core/completion/shells/zsh.d.mts +0 -1
- package/dist/core/completion/shells/zsh.mjs +2 -1
- package/dist/core/config/index.d.mts +3 -3
- package/dist/core/config/index.mjs +2 -2
- package/dist/core/config/package-json.d.mts +2 -33
- package/dist/core/config/package-json.mjs +1 -34
- package/dist/core/errors/index.d.mts +7 -7
- package/dist/core/execution/index.d.mts +1 -48
- package/dist/core/execution/index.mjs +42 -27
- package/dist/core/help/ansi.d.mts +0 -11
- package/dist/core/help/index.d.mts +3 -35
- package/dist/core/help/index.mjs +29 -6
- package/dist/core/help/theme.d.mts +1 -21
- package/dist/core/json-schema/index.d.mts +279 -10
- package/dist/core/json-schema/index.mjs +482 -237
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
- package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
- package/dist/core/output/activity.d.mts +1 -193
- package/dist/core/output/activity.mjs +1 -1
- package/dist/core/output/bind.d.mts +1 -37
- package/dist/core/output/contracts.d.mts +7 -13
- package/dist/core/output/contracts.mjs +1 -1
- package/dist/core/output/display-value.d.mts +1 -19
- package/dist/core/output/index.d.mts +5 -187
- package/dist/core/output/index.mjs +44 -9
- package/dist/core/output/renderers.d.mts +1 -45
- package/dist/core/output/writer.d.mts +0 -1
- package/dist/core/parse/index.d.mts +27 -5
- package/dist/core/parse/index.mjs +350 -227
- package/dist/core/parse/occurrences.d.mts +89 -0
- package/dist/core/parse/occurrences.mjs +114 -0
- package/dist/core/prompt/index.d.mts +3 -3
- package/dist/core/read-flags/index.d.mts +150 -0
- package/dist/core/read-flags/index.mjs +217 -0
- package/dist/core/resolve/args.d.mts +35 -4
- package/dist/core/resolve/args.mjs +132 -55
- package/dist/core/resolve/coerce.d.mts +66 -9
- package/dist/core/resolve/coerce.mjs +834 -270
- package/dist/core/resolve/config.d.mts +1 -10
- package/dist/core/resolve/contracts.d.mts +67 -44
- package/dist/core/resolve/errors.mjs +29 -21
- package/dist/core/resolve/flags.d.mts +36 -9
- package/dist/core/resolve/flags.mjs +129 -151
- package/dist/core/resolve/index.d.mts +8 -6
- package/dist/core/resolve/index.mjs +51 -18
- package/dist/core/resolve/path-checks.d.mts +47 -0
- package/dist/core/resolve/path-checks.mjs +102 -0
- package/dist/core/resolve/redaction.d.mts +12 -0
- package/dist/core/resolve/redaction.mjs +14 -0
- package/dist/core/resolve/stages.d.mts +85 -0
- package/dist/core/resolve/stages.mjs +170 -0
- package/dist/core/resolve/standard.d.mts +1 -24
- package/dist/core/resolve/standard.mjs +141 -43
- package/dist/core/schema/activity.d.mts +16 -16
- package/dist/core/schema/arg.d.mts +849 -71
- package/dist/core/schema/arg.mjs +727 -54
- package/dist/core/schema/brand.d.mts +17 -0
- package/dist/core/schema/cardinality.d.mts +301 -0
- package/dist/core/schema/cardinality.mjs +514 -0
- package/dist/core/schema/command.d.mts +181 -112
- package/dist/core/schema/command.mjs +305 -42
- package/dist/core/schema/flag.d.mts +515 -173
- package/dist/core/schema/flag.mjs +576 -78
- package/dist/core/schema/index.d.mts +11 -8
- package/dist/core/schema/index.mjs +10 -0
- package/dist/core/schema/middleware.d.mts +15 -12
- package/dist/core/schema/number-constraints.d.mts +5 -5
- package/dist/core/schema/prompt.d.mts +4 -4
- package/dist/core/schema/provenance.d.mts +99 -0
- package/dist/core/schema/provenance.mjs +28 -0
- package/dist/core/schema/run.d.mts +21 -60
- package/dist/core/schema/source.d.mts +179 -0
- package/dist/core/schema/source.mjs +206 -0
- package/dist/core/schema/standard.d.mts +12 -19
- package/dist/core/schema/stdin.d.mts +87 -0
- package/dist/core/schema/stdin.mjs +91 -0
- package/dist/core/schema/string-constraints.d.mts +16 -5
- package/dist/core/schema/string-constraints.mjs +18 -1
- package/dist/core/schema/value-parsers.d.mts +81 -9
- package/dist/core/schema/value-parsers.mjs +19 -1
- package/dist/core/schema/value.d.mts +242 -0
- package/dist/core/schema/value.mjs +573 -0
- package/dist/core/testkit/index.d.mts +28 -3
- package/dist/core/testkit/index.mjs +40 -26
- package/dist/index.d.mts +21 -16
- package/dist/index.mjs +10 -6
- package/dist/runtime/adapter.d.mts +3 -3
- package/dist/runtime/deno.d.mts +3 -3
- package/dist/runtime/detect.d.mts +2 -2
- package/dist/runtime/node.d.mts +3 -3
- package/dist/runtime/paths.d.mts +1 -31
- package/dist/runtime.d.mts +4 -4
- package/dist/strings.d.mts +1 -16
- package/dist/testkit.d.mts +2 -2
- package/dist/testkit.mjs +1 -1
- package/dist/version.d.mts +0 -13
- package/dist/version.mjs +2 -2
- package/dreamcli.schema.json +368 -78
- package/examples/interactive.ts +6 -5
- package/package.json +10 -9
- package/skills/cli-creation/SKILL.md +196 -0
- package/skills/cli-creation/agents/openai.yaml +4 -0
- package/skills/cli-creation/assets/templates/multi-command.bun-test.ts.tpl +20 -0
- package/skills/cli-creation/assets/templates/multi-command.test.ts.tpl +20 -0
- package/skills/cli-creation/assets/templates/multi-command.ts.tpl +89 -0
- package/skills/cli-creation/assets/templates/single-command.bun-test.ts.tpl +29 -0
- package/skills/cli-creation/assets/templates/single-command.test.ts.tpl +29 -0
- package/skills/cli-creation/assets/templates/single-command.ts.tpl +47 -0
- package/skills/cli-creation/references/consumer-workflow.md +65 -0
- package/skills/cli-creation/references/pattern-cookbook.md +451 -0
- package/skills/cli-creation/references/runtime-notes.md +29 -0
- package/skills/cli-creation/scripts/scaffold_cli.py +360 -0
- package/dist/core/resolve/property.d.mts +0 -51
- package/dist/core/resolve/property.mjs +0 -53
|
@@ -0,0 +1,451 @@
|
|
|
1
|
+
# Pattern Cookbook
|
|
2
|
+
|
|
3
|
+
Copy-ready snippets for DreamCLI 4.0. Every snippet type-checks against the
|
|
4
|
+
published types.
|
|
5
|
+
|
|
6
|
+
## Values
|
|
7
|
+
|
|
8
|
+
### Precedence chain
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
flag
|
|
12
|
+
.enum(['us', 'eu', 'ap'])
|
|
13
|
+
.stdin()
|
|
14
|
+
.env('DEPLOY_REGION')
|
|
15
|
+
.config('deploy.region')
|
|
16
|
+
.prompt({ kind: 'select', message: 'Which region?' })
|
|
17
|
+
.default('us');
|
|
18
|
+
|
|
19
|
+
arg
|
|
20
|
+
.enum(['us', 'eu', 'ap'])
|
|
21
|
+
.stdin()
|
|
22
|
+
.env('DEPLOY_REGION')
|
|
23
|
+
.config('deploy.region')
|
|
24
|
+
.prompt({ kind: 'select', message: 'Which region?' })
|
|
25
|
+
.default('us');
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Resolution order is fixed: CLI argv, stdin, env, config, prompt, default, and
|
|
29
|
+
both flags and positionals walk it. Declare the sources a value may come from;
|
|
30
|
+
never merge them by hand in the action.
|
|
31
|
+
|
|
32
|
+
### Reading piped stdin
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
flag.string().stdin(); // `--body -` or an absent flag reads the pipe
|
|
36
|
+
arg.string().stdin(); // `-` or an omitted slot reads the pipe
|
|
37
|
+
flag.string().stdin({ when: 'dash' }); // only an explicit `-`
|
|
38
|
+
arg.string().stdin({ when: 'missing' }); // only an omitted slot; `-` stays literal
|
|
39
|
+
flag.string().stdin({ consume: 'broadcast' }); // shares the buffer with other inputs
|
|
40
|
+
flag.string().stdin({ trim: true }); // drops one trailing line terminator
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Available on every flag kind but `count`, which counts occurrences rather than
|
|
44
|
+
reading a value and throws `INVALID_SCHEMA`, and on every arg kind. A `-` stays
|
|
45
|
+
CLI-sourced and outranks every later stage; an absent input takes the stdin
|
|
46
|
+
stage, which sits ahead of env. One command has one exclusive stdin consumer,
|
|
47
|
+
and a second `.stdin()` input of either surface throws `DUPLICATE_STDIN_INPUT`
|
|
48
|
+
unless every one of them passes `{ consume: 'broadcast' }`.
|
|
49
|
+
|
|
50
|
+
A `string` input keeps the buffer byte for byte, so `echo hi | mycli` gives
|
|
51
|
+
`'hi\n'`; every other kind drops one trailing line terminator before decoding.
|
|
52
|
+
`{ trim: true }` drops it for a `string` too, which is what a piped path wants:
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
arg.path({ mustExist: true }).stdin({ trim: true });
|
|
56
|
+
// echo ./dist | mycli clean → the check runs against './dist'
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
It applies to a single value. A collection's terminators separate its elements,
|
|
60
|
+
so `.split({ stdin })` decides those.
|
|
61
|
+
|
|
62
|
+
A collection reads the buffer as elements and splices them where a `-`
|
|
63
|
+
occurrence sits. A `-` typed beside other occurrences with nothing piped fails
|
|
64
|
+
with `MISSING_STDIN`, rather than shortening the collection;
|
|
65
|
+
occurrences of nothing but `-`, and a scalar `-`, fall through to the later
|
|
66
|
+
sources instead. A stdin-enabled input can never receive a literal `-` as its
|
|
67
|
+
value, since the token names the source; `{ when: 'missing' }` is the one
|
|
68
|
+
binding that leaves it literal.
|
|
69
|
+
|
|
70
|
+
### Rich flag types
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
flag.url({ protocols: ['https'] }); // URL
|
|
74
|
+
flag.path({ type: 'directory', create: true }); // string, mkdir -p when missing
|
|
75
|
+
flag.date({ min: new Date('2020-01-01') }); // Date, strict ISO-8601
|
|
76
|
+
flag.duration(); // number (ms) — '30s', '1h30m', '250ms'
|
|
77
|
+
flag.bytes(); // number — '512mb', '1.5gb'
|
|
78
|
+
flag.count().alias('v'); // number — -vvv is 3
|
|
79
|
+
flag.keyValue(); // Record<string, string> — repeated KEY=VALUE
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Prefer these over `flag.string()` plus hand-rolled parsing: they validate at
|
|
83
|
+
every source, feed help placeholders, and land in the exported JSON Schema.
|
|
84
|
+
|
|
85
|
+
`flag.path()` checks run through the runtime adapter after resolution. In
|
|
86
|
+
process-free execution pass `stat` (and `mkdir` for `create`) via run options,
|
|
87
|
+
or the checks are skipped.
|
|
88
|
+
|
|
89
|
+
### Rich arg types
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
arg.url({ protocols: ['https'] }); // URL
|
|
93
|
+
arg.path({ mustExist: true }); // string, checked after resolution
|
|
94
|
+
arg.date({ min: new Date('2020-01-01') }); // Date, strict ISO-8601
|
|
95
|
+
arg.duration(); // number (ms)
|
|
96
|
+
arg.bytes(); // number
|
|
97
|
+
arg.url().variadic(); // URL[], each value validated
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Same option objects, parsers, and error codes as the flag kinds above. Required
|
|
101
|
+
by default; add `.optional()` or `.default()` to change that. `arg.path()` needs
|
|
102
|
+
the same `stat`/`mkdir` injection as `flag.path()`, and a variadic path arg
|
|
103
|
+
checks every value it collects.
|
|
104
|
+
|
|
105
|
+
There is no `arg.array()` (use `.variadic()`) and no `arg.count()`, which counts
|
|
106
|
+
flag occurrences. `arg.boolean()` and `arg.keyValue()` do exist:
|
|
107
|
+
`arg.boolean()` consumes an explicit `true`/`false` token, and
|
|
108
|
+
`arg.keyValue(element)` consumes `KEY=VALUE` tokens into a record, taking the
|
|
109
|
+
same kind of element builder as `flag.keyValue(element)`. `.stdin()`,
|
|
110
|
+
`.env()`, `.config()`, and `.prompt()` are all available on an argument,
|
|
111
|
+
`.variadic()` included: a `-` among the tail tokens splices the decoded buffer
|
|
112
|
+
in at that position, so `printf 'x\ny\n' | mycli build a - b` collects
|
|
113
|
+
`['a', 'x', 'y', 'b']`, and an empty tail takes the whole buffer.
|
|
114
|
+
Prompts are unavailable on key-value arguments, and count flags cannot read
|
|
115
|
+
stdin.
|
|
116
|
+
|
|
117
|
+
A variadic argument is the last positional a command can declare. Registering
|
|
118
|
+
another one behind it throws `INVALID_BUILDER_STATE` on both construction
|
|
119
|
+
paths, since it could never be filled.
|
|
120
|
+
|
|
121
|
+
### Constraints instead of hand-written validation
|
|
122
|
+
|
|
123
|
+
```ts
|
|
124
|
+
flag.number({ int: true, min: 1, max: 65535 }); // port
|
|
125
|
+
flag.string({ nonEmpty: true, pattern: /^[a-z][a-z0-9-]*$/ }); // slug
|
|
126
|
+
flag.number().finite(false); // opt back into Infinity
|
|
127
|
+
arg.string({ nonEmpty: true, pattern: /^[a-z][a-z0-9-]*$/ }); // same on positionals
|
|
128
|
+
arg.number().int().min(1); // chainable, same as flag
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Constraints are enforced on CLI parse (`INVALID_VALUE`) and on
|
|
132
|
+
env/config/prompt/stdin resolution (`CONSTRAINT_VIOLATED`), both exit code 2.
|
|
133
|
+
A `.default()` value is checked against them where the chain declares it, and a
|
|
134
|
+
violation throws `INVALID_DEFAULT`, whichever order the chain is written in.
|
|
135
|
+
`finite` defaults to `true`, so `Infinity` is rejected unless you opt out:
|
|
136
|
+
|
|
137
|
+
```ts
|
|
138
|
+
flag.string({ minLength: 3 }).default('ab'); // INVALID_DEFAULT
|
|
139
|
+
flag.string().default('ab').minLength(3); // same verdict
|
|
140
|
+
flag.number({ finite: false }).default(Number.POSITIVE_INFINITY); // fine
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Asynchronous validators and `flag.path()` / `arg.path()` filesystem checks stay
|
|
144
|
+
at resolution time, so a default goes through those when the command runs.
|
|
145
|
+
|
|
146
|
+
### Standard Schema validation
|
|
147
|
+
|
|
148
|
+
```ts
|
|
149
|
+
import { z } from 'zod';
|
|
150
|
+
|
|
151
|
+
flag.custom(z.coerce.number().int().positive());
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Any Standard Schema v1 validator works (Zod, Valibot, ArkType) with the output
|
|
155
|
+
type inferred. Validation runs after source resolution, so every source is
|
|
156
|
+
checked identically.
|
|
157
|
+
|
|
158
|
+
On a collection, where the validator sits decides what it sees:
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
flag.array(flag.string().standard(slug)); // each element: --tag[1] failed validation: …
|
|
162
|
+
flag.array(flag.string()).standard(nonEmptyList); // the finished array
|
|
163
|
+
arg.string().standard(slug).variadic(); // each element
|
|
164
|
+
arg.string().variadic().standard(nonEmptyList); // the finished array
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
On an argument the position in the chain is what decides it, because
|
|
168
|
+
`.variadic()` is what makes the argument aggregate.
|
|
169
|
+
|
|
170
|
+
### Collections
|
|
171
|
+
|
|
172
|
+
```ts
|
|
173
|
+
flag
|
|
174
|
+
.array(flag.enum(['us', 'eu', 'ap']))
|
|
175
|
+
.separator(',')
|
|
176
|
+
.unique();
|
|
177
|
+
|
|
178
|
+
flag.keyValue().duplicateKeys('error'); // -e A=1 -e A=2 fails
|
|
179
|
+
arg.keyValue().variadic(); // mycli render a=1 b=2 → { a: '1', b: '2' }
|
|
180
|
+
arg.keyValue(arg.number().int()).variadic(); // mycli scale web=3 → { web: 3 }
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
`--region us,eu --region ap` and repetition both work. Put flag-level modifiers
|
|
184
|
+
(`.env()`, `.default()`) on the array, never on the element, which is a compile
|
|
185
|
+
error.
|
|
186
|
+
|
|
187
|
+
On the arg surface these four are collection modifiers, so each states the shape
|
|
188
|
+
it needs and the compiler refuses it elsewhere. `.separator()` and `.split()`
|
|
189
|
+
want a variadic argument or `arg.keyValue()`, `.unique()` a variadic argument of
|
|
190
|
+
a list kind, and `.duplicateKeys()` `arg.keyValue()`. `createArgSchema()` throws
|
|
191
|
+
`INVALID_SCHEMA` on the same combinations.
|
|
192
|
+
|
|
193
|
+
Each source decodes under its own policy, and a CLI separator is not inherited:
|
|
194
|
+
|
|
195
|
+
```ts
|
|
196
|
+
flag.array(flag.string()).split({ cli: ',', env: 'json', stdin: 'lines' }).env('TAGS').stdin();
|
|
197
|
+
// --tag a,b → ['a', 'b']
|
|
198
|
+
// TAGS='["a","b"]' → ['a', 'b']
|
|
199
|
+
// printf 'a\nb\n' | … → ['a', 'b']
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Defaults without `.split()`: whole CLI tokens, comma-delimited env values,
|
|
203
|
+
line-delimited stdin, native arrays and objects from config. A `-` occurrence
|
|
204
|
+
splices the decoded buffer in at that position.
|
|
205
|
+
|
|
206
|
+
## Parser behavior
|
|
207
|
+
|
|
208
|
+
### Negatable booleans
|
|
209
|
+
|
|
210
|
+
```ts
|
|
211
|
+
flag.boolean().default(true).negatable(); // --sandbox / --no-sandbox
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
One logical flag with two spellings; help renders `--[no-]sandbox`. The negated
|
|
215
|
+
spelling is presence-only (`--no-sandbox=false` errors).
|
|
216
|
+
|
|
217
|
+
### Duplicate policy
|
|
218
|
+
|
|
219
|
+
```ts
|
|
220
|
+
flag.enum(['session', 'worktree']).duplicates('error');
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Config-style flags should reject repeats rather than silently taking the last
|
|
224
|
+
value. `'error'` throws `ParseError` code `DUPLICATE_FLAG`; `'first'` keeps the
|
|
225
|
+
first. Counted per logical flag, including aliases and negated spellings.
|
|
226
|
+
|
|
227
|
+
### Cross-flag rules
|
|
228
|
+
|
|
229
|
+
```ts
|
|
230
|
+
command('serve')
|
|
231
|
+
.flag('port', flag.number({ int: true }))
|
|
232
|
+
.flag('socket', flag.string())
|
|
233
|
+
.derive(({ flags }) => {
|
|
234
|
+
if (flags.port !== undefined && flags.socket !== undefined) {
|
|
235
|
+
throw new CLIError('--port and --socket are mutually exclusive', {
|
|
236
|
+
code: 'INVALID_FLAG_COMBINATION',
|
|
237
|
+
});
|
|
238
|
+
}
|
|
239
|
+
return { mode: flags.socket !== undefined ? 'socket' : 'tcp' } as const;
|
|
240
|
+
})
|
|
241
|
+
.action(({ ctx }) => {
|
|
242
|
+
ctx.mode; // typed, available to the action
|
|
243
|
+
});
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
`.derive()` runs after resolution and before the action. It is the home for
|
|
247
|
+
rules DreamCLI cannot express declaratively, and its return value widens `ctx`.
|
|
248
|
+
|
|
249
|
+
### Explicit versus defaulted
|
|
250
|
+
|
|
251
|
+
```ts
|
|
252
|
+
import { command, flag, wasExplicit } from '@kjanat/dreamcli';
|
|
253
|
+
|
|
254
|
+
command('serve')
|
|
255
|
+
.flag('port', flag.number({ int: true }).env('PORT').default(3000))
|
|
256
|
+
.derive(({ flags, sources }) => {
|
|
257
|
+
if (flags.port !== undefined && sources.flags.port?.stage === 'env') {
|
|
258
|
+
// the environment supplied it, not the command line
|
|
259
|
+
}
|
|
260
|
+
return { overridden: wasExplicit(sources.flags.port) };
|
|
261
|
+
})
|
|
262
|
+
.action(({ ctx }) => {
|
|
263
|
+
ctx.overridden; // boolean
|
|
264
|
+
});
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
`sources` is keyed like `flags` and `args`, and each entry names the stage that
|
|
268
|
+
produced the value: `cli`, `stdin`, `env` with its `envVar`, `config` with its
|
|
269
|
+
`configPath`, `prompt`, or `default`. An explicit `-` reports
|
|
270
|
+
`{ stage: 'cli', via: 'stdin', trigger: 'dash' }`, so a piped value is
|
|
271
|
+
distinguishable from a typed one. `wasExplicit()` is the predicate for
|
|
272
|
+
"anything but the default", which is what a mutually-exclusive rule or an
|
|
273
|
+
explicit-wins merge needs. Never drop `.default()` to detect this: that also
|
|
274
|
+
drops `defaultValue` from `--help --json` and the exported schema.
|
|
275
|
+
|
|
276
|
+
## Output
|
|
277
|
+
|
|
278
|
+
### Channels
|
|
279
|
+
|
|
280
|
+
```ts
|
|
281
|
+
.action(({ out }) => {
|
|
282
|
+
out.log('primary result'); // stdout (stderr in --json)
|
|
283
|
+
out.status('working on it'); // stderr, hidden by --quiet
|
|
284
|
+
out.warn('deprecated flag used');// stderr, always shown
|
|
285
|
+
out.error('could not reach api');// stderr, always shown
|
|
286
|
+
});
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
Keep stdout free of progress chatter so pipes stay clean. `--quiet`/`-q` is a
|
|
290
|
+
global flag; it silences `status` and `info` but never warnings or errors.
|
|
291
|
+
|
|
292
|
+
### JSON mode branching
|
|
293
|
+
|
|
294
|
+
```ts
|
|
295
|
+
.action(({ out }) => {
|
|
296
|
+
const data = { service: 'api', healthy: true };
|
|
297
|
+
|
|
298
|
+
if (out.jsonMode) {
|
|
299
|
+
out.json(data);
|
|
300
|
+
return;
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
out.log('Service api is healthy');
|
|
304
|
+
});
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
Never mix human text into stdout in the same branch as `out.json()`.
|
|
308
|
+
|
|
309
|
+
### Tables
|
|
310
|
+
|
|
311
|
+
```ts
|
|
312
|
+
out.table(rows, [
|
|
313
|
+
{ key: 'name', header: 'Service' },
|
|
314
|
+
{ key: 'status', header: 'Status' },
|
|
315
|
+
]);
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
Text table for humans, array for `--json`. Columns are optional
|
|
319
|
+
(`out.table(rows)` infers them); pass `{ format: 'text', stream: 'stderr' }` to
|
|
320
|
+
force a human table alongside JSON stdout.
|
|
321
|
+
|
|
322
|
+
### Colors and hyperlinks
|
|
323
|
+
|
|
324
|
+
```ts
|
|
325
|
+
.action(({ out }) => {
|
|
326
|
+
out.log(out.color.green('✔ done'));
|
|
327
|
+
if (out.isHyperlinkSupported) out.log(osc8('https://example.com', 'docs'));
|
|
328
|
+
});
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
Every `out.color` formatter is an identity function when color is off (piped,
|
|
332
|
+
`NO_COLOR`, `--json`), so no branching is needed. Hyperlinks garble piped
|
|
333
|
+
output, so gate them on `out.isHyperlinkSupported`.
|
|
334
|
+
|
|
335
|
+
### Exit code without an error
|
|
336
|
+
|
|
337
|
+
```ts
|
|
338
|
+
.action(({ out }) => {
|
|
339
|
+
out.log('3 of 5 checks failed');
|
|
340
|
+
out.setExitCode(1);
|
|
341
|
+
});
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
For check/status commands: keeps normal output, avoids an error payload in
|
|
345
|
+
`--json`, still signals scripts.
|
|
346
|
+
|
|
347
|
+
### Structured errors
|
|
348
|
+
|
|
349
|
+
```ts
|
|
350
|
+
throw new CLIError('Deployment target not found', {
|
|
351
|
+
code: 'NOT_FOUND',
|
|
352
|
+
exitCode: 1,
|
|
353
|
+
suggest: 'Run: mycli deploy --help',
|
|
354
|
+
details: { requested: name },
|
|
355
|
+
});
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
Serializes cleanly in `--json` mode and prints a suggestion line otherwise.
|
|
359
|
+
|
|
360
|
+
## Surface
|
|
361
|
+
|
|
362
|
+
### Help configuration
|
|
363
|
+
|
|
364
|
+
```ts
|
|
365
|
+
cli('mycli').help({
|
|
366
|
+
flagOrder: 'declaration', // or a sortFlags comparator
|
|
367
|
+
theme: (c) => ({ sectionTitle: c.magenta }),
|
|
368
|
+
footer: false,
|
|
369
|
+
});
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
The theme factory receives the gated palette and never runs when color is off,
|
|
373
|
+
so a custom theme cannot leak escapes into piped output.
|
|
374
|
+
|
|
375
|
+
### Examples that know the program name
|
|
376
|
+
|
|
377
|
+
```ts
|
|
378
|
+
command('deploy').example(({ name }) => `${name} deploy production --force`, 'Force a deploy');
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
The builder form resolves at render time, so examples stay truthful under
|
|
382
|
+
symlinks, `inheritName`, and `npx` versus a global install.
|
|
383
|
+
|
|
384
|
+
### Default command
|
|
385
|
+
|
|
386
|
+
```ts
|
|
387
|
+
cli('mycli').default(serve); // root surface only: `mycli --port 80`
|
|
388
|
+
cli('mycli').default(serve, { route: true }); // also `mycli serve`
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
A plain `.default()` is the root surface and is not routable by name; the token
|
|
392
|
+
would be read as its first positional.
|
|
393
|
+
|
|
394
|
+
### Completions
|
|
395
|
+
|
|
396
|
+
```ts
|
|
397
|
+
cli('mycli').completions(); // mycli completions <shell>
|
|
398
|
+
cli('mycli').completions({ as: 'flag' }); // mycli --completions (shell auto-detected)
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
### Config discovery
|
|
402
|
+
|
|
403
|
+
```ts
|
|
404
|
+
cli('mycli')
|
|
405
|
+
.config('mycli')
|
|
406
|
+
.configLoader(configFormat(['yaml', 'yml'], parseYaml));
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
Discovery probes project scope (cwd and every ancestor: `.mycli.json`,
|
|
410
|
+
`mycli.config.json`, `.config/mycli.json`), then user scope (XDG/AppData, plus
|
|
411
|
+
`~/Library/Application Support` on macOS), then `/etc`. First match wins; files
|
|
412
|
+
are never merged. `--config <path>` overrides everything.
|
|
413
|
+
|
|
414
|
+
## Testing
|
|
415
|
+
|
|
416
|
+
### In-process command test
|
|
417
|
+
|
|
418
|
+
```ts
|
|
419
|
+
import { runCommand } from '@kjanat/dreamcli/testkit';
|
|
420
|
+
|
|
421
|
+
const result = await runCommand(deploy, ['production', '--force']);
|
|
422
|
+
expect(result.exitCode).toBe(0);
|
|
423
|
+
expect(result.stdout).toEqual(['Deploying production to us\n']);
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
Prefer `runCommand()` over subprocess tests: faster, deterministic, and it
|
|
427
|
+
captures stdout/stderr as arrays of written chunks — assert trailing newlines.
|
|
428
|
+
|
|
429
|
+
### Injecting the environment
|
|
430
|
+
|
|
431
|
+
```ts
|
|
432
|
+
await runCommand(deploy, ['--json'], {
|
|
433
|
+
env: { DEPLOY_REGION: 'eu' },
|
|
434
|
+
config: { deploy: { region: 'ap' } },
|
|
435
|
+
stdinData: 'piped\n', // bytes a `.stdin()` input reads; `null` for nothing piped
|
|
436
|
+
answers: ['production'], // queued prompt answers
|
|
437
|
+
stat: async (p) => (p === '/data' ? 'directory' : null),
|
|
438
|
+
});
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
Prompts are skipped in non-interactive contexts, so queue `answers` when a test
|
|
442
|
+
exercises one. Without `stat`, `flag.path()` checks are skipped entirely.
|
|
443
|
+
`stdinData` feeds `.stdin()` flags and args alike, so a test never has to spawn
|
|
444
|
+
a pipe.
|
|
445
|
+
|
|
446
|
+
### Asserting JSON output
|
|
447
|
+
|
|
448
|
+
```ts
|
|
449
|
+
const result = await runCommand(status, ['--json']);
|
|
450
|
+
expect(JSON.parse(result.stdout.join(''))).toEqual({ healthy: true });
|
|
451
|
+
```
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Runtime Notes
|
|
2
|
+
|
|
3
|
+
## Bun-first commands
|
|
4
|
+
|
|
5
|
+
- Run CLI entrypoint: `bun mycli.ts --help`
|
|
6
|
+
- Run tests: `bun test mycli.test.ts`
|
|
7
|
+
|
|
8
|
+
The scaffolder prints path-aware run commands; use those exact printed paths when `--out` is not `.`.
|
|
9
|
+
The scaffolder auto-detects test style:
|
|
10
|
+
|
|
11
|
+
- Bun project + no detected Vitest usage: generate `bun:test` template.
|
|
12
|
+
- Otherwise: generate Vitest template.
|
|
13
|
+
- Package manager detection checks lockfiles (including `pnpm-*.yaml/.yml`) and manifest `packageManager` entries in `package.json`, `package.json5`, and `package.yaml/.yml`.
|
|
14
|
+
|
|
15
|
+
If Vitest template is generated inside a Bun project, `bun test` still runs those tests in this workflow.
|
|
16
|
+
|
|
17
|
+
## npm/Node alternative
|
|
18
|
+
|
|
19
|
+
- Run CLI entrypoint: `npx tsx mycli.ts --help`
|
|
20
|
+
- Run tests: `npx vitest run mycli.test.ts`
|
|
21
|
+
|
|
22
|
+
## Deno alternative
|
|
23
|
+
|
|
24
|
+
- Run CLI entrypoint: `deno run -A mycli.ts --help`
|
|
25
|
+
- Run tests: use Bun/Node test tooling unless the project already has Deno test wiring.
|
|
26
|
+
|
|
27
|
+
## Prompt behavior
|
|
28
|
+
|
|
29
|
+
DreamCLI skips prompts in non-interactive contexts (CI/piped input). When tests depend on prompts, inject answers with `runCommand(..., { answers: [...] })`.
|