@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.
Files changed (137) hide show
  1. package/CHANGELOG.md +951 -1
  2. package/README.md +7 -3
  3. package/dist/core/cli/builtins.d.mts +47 -0
  4. package/dist/core/cli/builtins.mjs +135 -0
  5. package/dist/core/cli/compiled.d.mts +29 -0
  6. package/dist/core/cli/compiled.mjs +76 -0
  7. package/dist/core/cli/dispatch.d.mts +9 -85
  8. package/dist/core/cli/help-links.d.mts +2 -14
  9. package/dist/core/cli/index.d.mts +282 -101
  10. package/dist/core/cli/index.mjs +497 -264
  11. package/dist/core/cli/planner.d.mts +13 -86
  12. package/dist/core/cli/planner.mjs +47 -30
  13. package/dist/core/cli/plugin.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +1 -1
  15. package/dist/core/cli/reserved-flags.d.mts +1 -0
  16. package/dist/core/cli/reserved-flags.mjs +158 -0
  17. package/dist/core/cli/root-help.d.mts +1 -47
  18. package/dist/core/cli/root-help.mjs +37 -47
  19. package/dist/core/cli/root-output-flags.d.mts +1 -0
  20. package/dist/core/cli/root-output-flags.mjs +169 -0
  21. package/dist/core/cli/root-surface.d.mts +1 -68
  22. package/dist/core/cli/root-surface.mjs +2 -2
  23. package/dist/core/cli/runtime-preflight.d.mts +1 -199
  24. package/dist/core/cli/runtime-preflight.mjs +67 -17
  25. package/dist/core/completion/index.d.mts +2 -2
  26. package/dist/core/completion/shells/bash.d.mts +0 -1
  27. package/dist/core/completion/shells/bash.mjs +2 -1
  28. package/dist/core/completion/shells/fish.d.mts +0 -1
  29. package/dist/core/completion/shells/fish.mjs +2 -1
  30. package/dist/core/completion/shells/powershell.d.mts +0 -1
  31. package/dist/core/completion/shells/powershell.mjs +2 -1
  32. package/dist/core/completion/shells/shared.d.mts +3 -114
  33. package/dist/core/completion/shells/shared.mjs +9 -39
  34. package/dist/core/completion/shells/zsh.d.mts +0 -1
  35. package/dist/core/completion/shells/zsh.mjs +2 -1
  36. package/dist/core/config/index.d.mts +3 -3
  37. package/dist/core/config/index.mjs +2 -2
  38. package/dist/core/config/package-json.d.mts +2 -33
  39. package/dist/core/config/package-json.mjs +1 -34
  40. package/dist/core/errors/index.d.mts +7 -7
  41. package/dist/core/execution/index.d.mts +1 -48
  42. package/dist/core/execution/index.mjs +42 -27
  43. package/dist/core/help/ansi.d.mts +0 -11
  44. package/dist/core/help/index.d.mts +3 -35
  45. package/dist/core/help/index.mjs +29 -6
  46. package/dist/core/help/theme.d.mts +1 -21
  47. package/dist/core/json-schema/index.d.mts +279 -10
  48. package/dist/core/json-schema/index.mjs +482 -237
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
  51. package/dist/core/output/activity.d.mts +1 -193
  52. package/dist/core/output/activity.mjs +1 -1
  53. package/dist/core/output/bind.d.mts +1 -37
  54. package/dist/core/output/contracts.d.mts +7 -13
  55. package/dist/core/output/contracts.mjs +1 -1
  56. package/dist/core/output/display-value.d.mts +1 -19
  57. package/dist/core/output/index.d.mts +5 -187
  58. package/dist/core/output/index.mjs +44 -9
  59. package/dist/core/output/renderers.d.mts +1 -45
  60. package/dist/core/output/writer.d.mts +0 -1
  61. package/dist/core/parse/index.d.mts +27 -5
  62. package/dist/core/parse/index.mjs +350 -227
  63. package/dist/core/parse/occurrences.d.mts +89 -0
  64. package/dist/core/parse/occurrences.mjs +114 -0
  65. package/dist/core/prompt/index.d.mts +3 -3
  66. package/dist/core/read-flags/index.d.mts +150 -0
  67. package/dist/core/read-flags/index.mjs +217 -0
  68. package/dist/core/resolve/args.d.mts +35 -4
  69. package/dist/core/resolve/args.mjs +132 -55
  70. package/dist/core/resolve/coerce.d.mts +66 -9
  71. package/dist/core/resolve/coerce.mjs +834 -270
  72. package/dist/core/resolve/config.d.mts +1 -10
  73. package/dist/core/resolve/contracts.d.mts +67 -44
  74. package/dist/core/resolve/errors.mjs +29 -21
  75. package/dist/core/resolve/flags.d.mts +36 -9
  76. package/dist/core/resolve/flags.mjs +129 -151
  77. package/dist/core/resolve/index.d.mts +8 -6
  78. package/dist/core/resolve/index.mjs +51 -18
  79. package/dist/core/resolve/path-checks.d.mts +47 -0
  80. package/dist/core/resolve/path-checks.mjs +102 -0
  81. package/dist/core/resolve/redaction.d.mts +12 -0
  82. package/dist/core/resolve/redaction.mjs +14 -0
  83. package/dist/core/resolve/stages.d.mts +85 -0
  84. package/dist/core/resolve/stages.mjs +170 -0
  85. package/dist/core/resolve/standard.d.mts +1 -24
  86. package/dist/core/resolve/standard.mjs +141 -43
  87. package/dist/core/schema/activity.d.mts +16 -16
  88. package/dist/core/schema/arg.d.mts +849 -71
  89. package/dist/core/schema/arg.mjs +727 -54
  90. package/dist/core/schema/brand.d.mts +17 -0
  91. package/dist/core/schema/cardinality.d.mts +301 -0
  92. package/dist/core/schema/cardinality.mjs +514 -0
  93. package/dist/core/schema/command.d.mts +181 -112
  94. package/dist/core/schema/command.mjs +305 -42
  95. package/dist/core/schema/flag.d.mts +515 -173
  96. package/dist/core/schema/flag.mjs +576 -78
  97. package/dist/core/schema/index.d.mts +11 -8
  98. package/dist/core/schema/index.mjs +10 -0
  99. package/dist/core/schema/middleware.d.mts +15 -12
  100. package/dist/core/schema/number-constraints.d.mts +5 -5
  101. package/dist/core/schema/prompt.d.mts +4 -4
  102. package/dist/core/schema/provenance.d.mts +99 -0
  103. package/dist/core/schema/provenance.mjs +28 -0
  104. package/dist/core/schema/run.d.mts +21 -60
  105. package/dist/core/schema/source.d.mts +179 -0
  106. package/dist/core/schema/source.mjs +206 -0
  107. package/dist/core/schema/standard.d.mts +12 -19
  108. package/dist/core/schema/stdin.d.mts +87 -0
  109. package/dist/core/schema/stdin.mjs +91 -0
  110. package/dist/core/schema/string-constraints.d.mts +16 -5
  111. package/dist/core/schema/string-constraints.mjs +18 -1
  112. package/dist/core/schema/value-parsers.d.mts +81 -9
  113. package/dist/core/schema/value-parsers.mjs +19 -1
  114. package/dist/core/schema/value.d.mts +242 -0
  115. package/dist/core/schema/value.mjs +573 -0
  116. package/dist/core/testkit/index.d.mts +28 -3
  117. package/dist/core/testkit/index.mjs +40 -26
  118. package/dist/index.d.mts +21 -16
  119. package/dist/index.mjs +10 -6
  120. package/dist/runtime/adapter.d.mts +3 -3
  121. package/dist/runtime/deno.d.mts +3 -3
  122. package/dist/runtime/detect.d.mts +2 -2
  123. package/dist/runtime/node.d.mts +3 -3
  124. package/dist/runtime/paths.d.mts +1 -31
  125. package/dist/runtime.d.mts +4 -4
  126. package/dist/strings.d.mts +1 -16
  127. package/dist/testkit.d.mts +2 -2
  128. package/dist/testkit.mjs +1 -1
  129. package/dist/version.d.mts +0 -13
  130. package/dist/version.mjs +2 -2
  131. package/dreamcli.schema.json +368 -78
  132. package/examples/interactive.ts +6 -5
  133. package/package.json +9 -9
  134. package/skills/cli-creation/SKILL.md +72 -16
  135. package/skills/cli-creation/references/pattern-cookbook.md +169 -11
  136. package/dist/core/resolve/property.d.mts +0 -51
  137. 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 3.x. Version 3 removed the DSL, made the default command the
15
- root surface, and added a large typed-flag surface; snippets below assume it.
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@3.0.0` when the project is not on
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.** Add typed args with `arg.string()`, `arg.number()`, `arg.enum(...)`,
100
- `arg.custom(...)`; `.variadic()` for repeated positionals. Prefer a purpose-built
101
- flag kind over `flag.string()` plus parsing: `flag.url()`, `flag.path()`,
102
- `flag.date()`, `flag.duration()`, `flag.bytes()`, `flag.count()`,
103
- `flag.keyValue()`. Express validation declaratively with constraints
104
- (`{ int, min, max }`, `{ nonEmpty, pattern }`) or a Standard Schema passed to
105
- `flag.custom()`, not with hand-written checks in the action.
106
-
107
- **Sources.** Declare `.env()`, `.config()`, `.prompt()`, `.default()` on the flag
108
- and let resolution order (argv, env, config, prompt, default) do the work.
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. Assert output
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.x. Every snippet type-checks against the
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
- ### Flag precedence chain
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. Declare the
20
- sources a value may come from; never merge them by hand in the action.
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 env/config/prompt
50
- resolution (`CONSTRAINT_VIOLATED`), both exit code 2. `finite` defaults to
51
- `true`, so `Infinity` is rejected unless you opt out.
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; array flags validate per element.
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
- ### Array flags
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()`, …) on the array, never on the element — that is a
76
- compile error.
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 };