@kjanat/dreamcli 3.0.1 → 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 +951 -1
- package/README.md +7 -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 +9 -9
- package/skills/cli-creation/SKILL.md +72 -16
- package/skills/cli-creation/references/pattern-cookbook.md +169 -11
- package/dist/core/resolve/property.d.mts +0 -51
- package/dist/core/resolve/property.mjs +0 -53
|
@@ -11,8 +11,11 @@ Create runnable DreamCLI starter CLIs and extend them with typed command
|
|
|
11
11
|
patterns. This skill covers user-facing app code built **on** DreamCLI, not
|
|
12
12
|
DreamCLI framework internals.
|
|
13
13
|
|
|
14
|
-
Targets DreamCLI
|
|
15
|
-
root surface, and added a large typed-flag surface
|
|
14
|
+
Targets DreamCLI 4.0. Version 3 removed the DSL, made the default command the
|
|
15
|
+
root surface, and added a large typed-flag surface. Version 4 gave both
|
|
16
|
+
factories the same sources, so `.stdin()`, `.env()`, `.config()`, and
|
|
17
|
+
`.prompt()` are available on flags and positionals alike. Snippets below assume
|
|
18
|
+
both.
|
|
16
19
|
|
|
17
20
|
## Quick Start
|
|
18
21
|
|
|
@@ -49,7 +52,7 @@ deno doc --filter=CLIBuilder jsr:@kjanat/dreamcli 2>/dev/null # one symbol
|
|
|
49
52
|
`2>/dev/null` matters: deno writes download and type-check progress to stderr,
|
|
50
53
|
which otherwise swamps the documentation output.
|
|
51
54
|
|
|
52
|
-
Pin a version with `jsr:@kjanat/dreamcli@
|
|
55
|
+
Pin a version with `jsr:@kjanat/dreamcli@4.0.0-rc.1` when the project is not on
|
|
53
56
|
latest. `--filter` takes a declaration name; it prints nothing for a name that
|
|
54
57
|
does not exist, which is itself a useful signal.
|
|
55
58
|
|
|
@@ -96,28 +99,81 @@ Paths are relative to the dreamcli repository root.
|
|
|
96
99
|
|
|
97
100
|
## Extend the Starter
|
|
98
101
|
|
|
99
|
-
**Values.**
|
|
100
|
-
`
|
|
101
|
-
|
|
102
|
-
`
|
|
103
|
-
`flag.
|
|
104
|
-
(`{ int, min, max }`, `{ nonEmpty, pattern }
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
102
|
+
**Values.** Prefer a purpose-built kind over `flag.string()` / `arg.string()`
|
|
103
|
+
plus parsing. Both factories carry `string()`, `number()`, `boolean()`,
|
|
104
|
+
`enum(...)`, `custom(...)`, `keyValue()`, `url()`, `path()`, `date()`,
|
|
105
|
+
`duration()`, and `bytes()`. `flag` additionally carries `array()` and
|
|
106
|
+
`count()`; the arg form of `flag.array()` is `.variadic()`. Express validation
|
|
107
|
+
declaratively with constraints (`{ int, min, max }`, `{ nonEmpty, pattern }`,
|
|
108
|
+
chainable on both builders) or a Standard Schema passed to `.standard()` or to
|
|
109
|
+
`flag.custom()` / `arg.custom()`, not with hand-written checks in the action.
|
|
110
|
+
|
|
111
|
+
**Defaults.** A `.default()` value is validated where the chain declares it, so
|
|
112
|
+
a default that violates its own constraints, validator, or collection shape
|
|
113
|
+
throws `INVALID_DEFAULT` at build time. A collection default takes the shape the
|
|
114
|
+
input resolves to: an array for `flag.array()` and a variadic arg, a record for
|
|
115
|
+
`keyValue()`, a non-negative integer for `flag.count()`.
|
|
116
|
+
|
|
117
|
+
**Collections.** `flag.array()`, `flag.keyValue()`, `arg.keyValue()`, and
|
|
118
|
+
`.variadic()` aggregate from every source under one set of rules. Each source
|
|
119
|
+
decodes under its own policy, set by `.split({ cli, env, stdin })`: whole CLI
|
|
120
|
+
tokens by default, comma-delimited env values, line-delimited stdin, and native
|
|
121
|
+
arrays and objects from config. `.separator()` sets the CLI policy alone and is
|
|
122
|
+
no longer inherited by env or config. `.unique()` dedupes a list, and
|
|
123
|
+
`.duplicateKeys('last' | 'first' | 'error')` decides a repeated key on every
|
|
124
|
+
source, naming the source that carried it. A validator on the element builder
|
|
125
|
+
checks each element; one on the collection builder checks the finished value.
|
|
126
|
+
On the arg surface, `.separator()` and `.split()` require `.variadic()` or
|
|
127
|
+
`arg.keyValue()`, `.unique()` requires a variadic list, and `.duplicateKeys()`
|
|
128
|
+
requires `arg.keyValue()`. The compiler refuses every other shape and
|
|
129
|
+
`createArgSchema()` throws `INVALID_SCHEMA`.
|
|
130
|
+
|
|
131
|
+
**Argument order.** A variadic argument takes every remaining positional, so it
|
|
132
|
+
is the last one a command can declare. Anything registered behind it throws
|
|
133
|
+
`INVALID_BUILDER_STATE`.
|
|
134
|
+
|
|
135
|
+
**Sources.** Both factories declare the same sources. Chain `.stdin()`,
|
|
136
|
+
`.env()`, `.config()`, `.prompt()`, `.default()` on a flag or an argument and
|
|
137
|
+
let one resolution order (argv, stdin, env, config, prompt, default) do the
|
|
138
|
+
work. Count and key-value flags and key-value arguments are not promptable.
|
|
139
|
+
`.stdin()` takes `{ when, consume, trim }`; one command has one exclusive
|
|
140
|
+
stdin consumer unless every stdin input passes `{ consume: 'broadcast' }`. A `-`
|
|
141
|
+
occurrence on a collection splices the decoded buffer in at that position, so
|
|
142
|
+
`--tag before --tag - --tag after` over `a\nb\n` gives
|
|
143
|
+
`['before', 'a', 'b', 'after']`, and a variadic argument reads its tail the same
|
|
144
|
+
way. A `-` typed beside other occurrences with nothing piped fails with
|
|
145
|
+
`MISSING_STDIN`; a lone `-`, and a scalar `-`, fall through instead.
|
|
146
|
+
`{ trim: true }` drops one trailing line terminator from a single value, which
|
|
147
|
+
is what `arg.path({ mustExist: true }).stdin({ trim: true })` wants. Help names
|
|
148
|
+
each binding: `[stdin]`, `[stdin: '-']`, or `[stdin: when omitted]`. Stdin is
|
|
149
|
+
available to scalar, array, key-value, and variadic inputs; count flags cannot
|
|
150
|
+
read it, and key-value arguments cannot prompt.
|
|
151
|
+
|
|
152
|
+
**Provenance.** A handler receives `sources` beside `flags` and `args`, keyed
|
|
153
|
+
the same way, holding the stage that produced each value (`cli`, `stdin`, `env`
|
|
154
|
+
with its `envVar`, `config` with its `configPath`, `prompt`, `default`).
|
|
155
|
+
`wasExplicit(sources.flags.x)` is the predicate for "supplied rather than
|
|
156
|
+
defaulted"; never drop `.default()` to detect that, since it also drops
|
|
157
|
+
`defaultValue` from the exported schema.
|
|
109
158
|
|
|
110
159
|
**Cross-flag rules.** Put them in `.derive()`, which runs after resolution and
|
|
111
160
|
before the action, and return derived state to widen `ctx`.
|
|
112
161
|
|
|
162
|
+
**Diagnostics.** Values resolved through stdin, env, config, or a prompt are
|
|
163
|
+
redacted in validation messages and omit `details.value`; this includes stdin
|
|
164
|
+
selected by an explicit `-`. Only a literal CLI value is shown. The framework
|
|
165
|
+
cannot redact text your own code writes: a `flag.custom()` parse function's
|
|
166
|
+
thrown message and a Standard Schema issue message are shown verbatim, so write
|
|
167
|
+
them to describe the expectation rather than to interpolate the value.
|
|
168
|
+
|
|
113
169
|
**Output.** `out.log()` for results, `out.status()` for progress notes (stderr,
|
|
114
170
|
suppressed by `--quiet`), `out.table()` for lists, `out.json()` behind
|
|
115
171
|
`out.jsonMode`, `out.color`/`osc8()` for styling, `out.setExitCode()` when a
|
|
116
172
|
command must report normally but exit non-zero.
|
|
117
173
|
|
|
118
174
|
**Testing.** `runCommand()` from `@kjanat/dreamcli/testkit`, with `answers` for
|
|
119
|
-
prompts and `stat`/`mkdir` when `flag.path()` checks must run.
|
|
120
|
-
including trailing newlines.
|
|
175
|
+
prompts and `stat`/`mkdir` when `flag.path()` or `arg.path()` checks must run.
|
|
176
|
+
Assert output including trailing newlines.
|
|
121
177
|
|
|
122
178
|
## Resource Map
|
|
123
179
|
|
|
@@ -132,7 +188,7 @@ including trailing newlines.
|
|
|
132
188
|
- Do not modify DreamCLI core internals for consumer-app requests.
|
|
133
189
|
- Keep generated imports on `@kjanat/dreamcli` and `@kjanat/dreamcli/testkit`;
|
|
134
190
|
never reach into `#internals/*` or `dist/`.
|
|
135
|
-
- Preserve the typed resolution flow: argv, env, config, prompt, default.
|
|
191
|
+
- Preserve the typed resolution flow: argv, stdin, env, config, prompt, default.
|
|
136
192
|
- Keep stdout machine-clean: progress and status go to stderr via `out.status()`,
|
|
137
193
|
never interleaved with `out.json()`.
|
|
138
194
|
- `.default(cmd)` is the root surface and is not routable by name; add
|
|
@@ -1,23 +1,71 @@
|
|
|
1
1
|
# Pattern Cookbook
|
|
2
2
|
|
|
3
|
-
Copy-ready snippets for DreamCLI
|
|
3
|
+
Copy-ready snippets for DreamCLI 4.0. Every snippet type-checks against the
|
|
4
4
|
published types.
|
|
5
5
|
|
|
6
6
|
## Values
|
|
7
7
|
|
|
8
|
-
###
|
|
8
|
+
### Precedence chain
|
|
9
9
|
|
|
10
10
|
```ts
|
|
11
11
|
flag
|
|
12
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()
|
|
13
22
|
.env('DEPLOY_REGION')
|
|
14
23
|
.config('deploy.region')
|
|
15
24
|
.prompt({ kind: 'select', message: 'Which region?' })
|
|
16
25
|
.default('us');
|
|
17
26
|
```
|
|
18
27
|
|
|
19
|
-
Resolution order is fixed: CLI argv, env, config, prompt, default
|
|
20
|
-
|
|
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.
|
|
21
69
|
|
|
22
70
|
### Rich flag types
|
|
23
71
|
|
|
@@ -38,17 +86,62 @@ every source, feed help placeholders, and land in the exported JSON Schema.
|
|
|
38
86
|
process-free execution pass `stat` (and `mkdir` for `create`) via run options,
|
|
39
87
|
or the checks are skipped.
|
|
40
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
|
+
|
|
41
121
|
### Constraints instead of hand-written validation
|
|
42
122
|
|
|
43
123
|
```ts
|
|
44
124
|
flag.number({ int: true, min: 1, max: 65535 }); // port
|
|
45
125
|
flag.string({ nonEmpty: true, pattern: /^[a-z][a-z0-9-]*$/ }); // slug
|
|
46
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
|
|
47
129
|
```
|
|
48
130
|
|
|
49
|
-
Constraints are enforced on CLI parse (`INVALID_VALUE`) and on
|
|
50
|
-
resolution (`CONSTRAINT_VIOLATED`), both exit code 2.
|
|
51
|
-
`
|
|
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.
|
|
52
145
|
|
|
53
146
|
### Standard Schema validation
|
|
54
147
|
|
|
@@ -60,20 +153,55 @@ flag.custom(z.coerce.number().int().positive());
|
|
|
60
153
|
|
|
61
154
|
Any Standard Schema v1 validator works (Zod, Valibot, ArkType) with the output
|
|
62
155
|
type inferred. Validation runs after source resolution, so every source is
|
|
63
|
-
checked identically
|
|
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.
|
|
64
169
|
|
|
65
|
-
###
|
|
170
|
+
### Collections
|
|
66
171
|
|
|
67
172
|
```ts
|
|
68
173
|
flag
|
|
69
174
|
.array(flag.enum(['us', 'eu', 'ap']))
|
|
70
175
|
.separator(',')
|
|
71
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 }
|
|
72
181
|
```
|
|
73
182
|
|
|
74
183
|
`--region us,eu --region ap` and repetition both work. Put flag-level modifiers
|
|
75
|
-
(`.env()`, `.default()
|
|
76
|
-
|
|
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.
|
|
77
205
|
|
|
78
206
|
## Parser behavior
|
|
79
207
|
|
|
@@ -118,6 +246,33 @@ command('serve')
|
|
|
118
246
|
`.derive()` runs after resolution and before the action. It is the home for
|
|
119
247
|
rules DreamCLI cannot express declaratively, and its return value widens `ctx`.
|
|
120
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
|
+
|
|
121
276
|
## Output
|
|
122
277
|
|
|
123
278
|
### Channels
|
|
@@ -277,6 +432,7 @@ captures stdout/stderr as arrays of written chunks — assert trailing newlines.
|
|
|
277
432
|
await runCommand(deploy, ['--json'], {
|
|
278
433
|
env: { DEPLOY_REGION: 'eu' },
|
|
279
434
|
config: { deploy: { region: 'ap' } },
|
|
435
|
+
stdinData: 'piped\n', // bytes a `.stdin()` input reads; `null` for nothing piped
|
|
280
436
|
answers: ['production'], // queued prompt answers
|
|
281
437
|
stat: async (p) => (p === '/data' ? 'directory' : null),
|
|
282
438
|
});
|
|
@@ -284,6 +440,8 @@ await runCommand(deploy, ['--json'], {
|
|
|
284
440
|
|
|
285
441
|
Prompts are skipped in non-interactive contexts, so queue `answers` when a test
|
|
286
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.
|
|
287
445
|
|
|
288
446
|
### Asserting JSON output
|
|
289
447
|
|
|
@@ -1,51 +0,0 @@
|
|
|
1
|
-
import { NumberConstraints } from "../schema/number-constraints.mjs";
|
|
2
|
-
import { ArgSchema } from "../schema/arg.mjs";
|
|
3
|
-
import { StringConstraints } from "../schema/string-constraints.mjs";
|
|
4
|
-
import { FlagSchema } from "../schema/flag.mjs";
|
|
5
|
-
import "../schema/index.mjs";
|
|
6
|
-
//#region src/core/resolve/property.d.ts
|
|
7
|
-
/** Flag/arg kinds that share a common coercion path. */
|
|
8
|
-
declare const SHARED_PROPERTY_MODEL_KINDS: readonly ["string", "number", "enum", "custom"];
|
|
9
|
-
/** Union of kind discriminants that participate in shared coercion. */
|
|
10
|
-
type SharedPropertyKind = (typeof SHARED_PROPERTY_MODEL_KINDS)[number];
|
|
11
|
-
/** Minimal coercion-relevant slice of a flag or arg schema, discriminated by kind. */
|
|
12
|
-
type SharedPropertySchema = {
|
|
13
|
-
readonly kind: 'string';
|
|
14
|
-
readonly stringConstraints: StringConstraints | undefined;
|
|
15
|
-
} | {
|
|
16
|
-
readonly kind: 'number';
|
|
17
|
-
readonly numberConstraints: NumberConstraints | undefined;
|
|
18
|
-
} | {
|
|
19
|
-
readonly kind: 'enum';
|
|
20
|
-
readonly enumValues: readonly string[] | undefined;
|
|
21
|
-
} | {
|
|
22
|
-
readonly kind: 'custom';
|
|
23
|
-
readonly parseFn?: (raw: unknown) => unknown;
|
|
24
|
-
};
|
|
25
|
-
/** Contract asserting which concerns are shared vs. kept separate between flags and args. */
|
|
26
|
-
interface SharedPropertyModelContract {
|
|
27
|
-
/** Only coercion logic is shared; resolution orchestration is not. */
|
|
28
|
-
readonly scope: 'coercion';
|
|
29
|
-
/** The kind discriminants that participate in shared coercion. */
|
|
30
|
-
readonly sharedKinds: readonly SharedPropertyKind[];
|
|
31
|
-
/** Flag and arg precedence chains remain independent. */
|
|
32
|
-
readonly keepsFlagAndArgPrecedenceSeparate: true;
|
|
33
|
-
/** Fallback-on-coercion-error rules remain independent. */
|
|
34
|
-
readonly keepsFallbackRulesSeparate: true;
|
|
35
|
-
/** Required-value validation remains independent. */
|
|
36
|
-
readonly keepsRequiredValueRulesSeparate: true;
|
|
37
|
-
}
|
|
38
|
-
/** Runtime-accessible contract instance for property model tests. */
|
|
39
|
-
declare const sharedPropertyModelContract: {
|
|
40
|
-
scope: "coercion";
|
|
41
|
-
sharedKinds: readonly ["string", "number", "enum", "custom"];
|
|
42
|
-
keepsFlagAndArgPrecedenceSeparate: true;
|
|
43
|
-
keepsFallbackRulesSeparate: true;
|
|
44
|
-
keepsRequiredValueRulesSeparate: true;
|
|
45
|
-
};
|
|
46
|
-
/** Extract the shared coercion slice from a flag schema, or `undefined` for boolean/array (handled separately). */
|
|
47
|
-
declare function toSharedFlagPropertySchema(schema: FlagSchema): SharedPropertySchema | undefined;
|
|
48
|
-
/** Extract the shared coercion slice from an arg schema (all arg kinds are shared). */
|
|
49
|
-
declare function toSharedArgPropertySchema(schema: ArgSchema): SharedPropertySchema;
|
|
50
|
-
//#endregion
|
|
51
|
-
export { SHARED_PROPERTY_MODEL_KINDS, type SharedPropertyKind, type SharedPropertyModelContract, type SharedPropertySchema, sharedPropertyModelContract, toSharedArgPropertySchema, toSharedFlagPropertySchema };
|
|
@@ -1,53 +0,0 @@
|
|
|
1
|
-
//#region src/core/resolve/property.ts
|
|
2
|
-
/** Extract the shared coercion slice from a flag schema, or `undefined` for boolean/array (handled separately). */
|
|
3
|
-
function toSharedFlagPropertySchema(schema) {
|
|
4
|
-
switch (schema.kind) {
|
|
5
|
-
case "string": return {
|
|
6
|
-
kind: "string",
|
|
7
|
-
stringConstraints: schema.stringConstraints
|
|
8
|
-
};
|
|
9
|
-
case "number": return {
|
|
10
|
-
kind: "number",
|
|
11
|
-
numberConstraints: schema.numberConstraints
|
|
12
|
-
};
|
|
13
|
-
case "enum": return {
|
|
14
|
-
kind: "enum",
|
|
15
|
-
enumValues: schema.enumValues
|
|
16
|
-
};
|
|
17
|
-
case "custom": return schema.parseFn === void 0 ? { kind: "custom" } : {
|
|
18
|
-
kind: "custom",
|
|
19
|
-
parseFn: schema.parseFn
|
|
20
|
-
};
|
|
21
|
-
case "boolean":
|
|
22
|
-
case "array":
|
|
23
|
-
case "count":
|
|
24
|
-
case "keyValue": return;
|
|
25
|
-
}
|
|
26
|
-
}
|
|
27
|
-
/** Extract the shared coercion slice from an arg schema (all arg kinds are shared). */
|
|
28
|
-
function toSharedArgPropertySchema(schema) {
|
|
29
|
-
switch (schema.kind) {
|
|
30
|
-
case "string": return {
|
|
31
|
-
kind: "string",
|
|
32
|
-
stringConstraints: void 0
|
|
33
|
-
};
|
|
34
|
-
case "number": return {
|
|
35
|
-
kind: "number",
|
|
36
|
-
numberConstraints: schema.numberConstraints
|
|
37
|
-
};
|
|
38
|
-
case "enum": return {
|
|
39
|
-
kind: "enum",
|
|
40
|
-
enumValues: schema.enumValues
|
|
41
|
-
};
|
|
42
|
-
case "custom": {
|
|
43
|
-
if (schema.parseFn === void 0) return { kind: "custom" };
|
|
44
|
-
const parseFn = schema.parseFn;
|
|
45
|
-
return {
|
|
46
|
-
kind: "custom",
|
|
47
|
-
parseFn: (raw) => parseFn(typeof raw === "string" ? raw : String(raw))
|
|
48
|
-
};
|
|
49
|
-
}
|
|
50
|
-
}
|
|
51
|
-
}
|
|
52
|
-
//#endregion
|
|
53
|
-
export { toSharedArgPropertySchema, toSharedFlagPropertySchema };
|