@kjanat/dreamcli 3.0.1 → 4.0.0-rc.2
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 +962 -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 +173 -119
- 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 +30 -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 +12 -11
- 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
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,960 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
### Release checklist
|
|
11
|
+
|
|
12
|
+
- [ ] Set the intended version in `package.json` and `deno.json`, add the dated
|
|
13
|
+
changelog section, and update every comparison link.
|
|
14
|
+
- [ ] Update first-party DreamCLI pins in documentation and import-map
|
|
15
|
+
configuration; do not rewrite versions that belong to transitive lockfile
|
|
16
|
+
metadata.
|
|
17
|
+
- [ ] Run `runner run -s schema:emit version:check ci smoke`.
|
|
18
|
+
- [ ] Pack with `bun pm pack --quiet --ignore-scripts` and inspect the tarball's
|
|
19
|
+
files and version.
|
|
20
|
+
- [ ] Confirm generators and formatters leave no unexpected worktree changes.
|
|
21
|
+
- [ ] Commit and push the release preparation, then verify the target commit is
|
|
22
|
+
signed, `master` matches the remote, and every required check is green.
|
|
23
|
+
- [ ] Confirm the exact `v<version>` tag does not already exist and npm and JSR
|
|
24
|
+
do not already contain that version before publishing the GitHub release.
|
|
25
|
+
|
|
26
|
+
## [4.0.0-rc.2] - 2026-08-17
|
|
27
|
+
|
|
28
|
+
### Fixed
|
|
29
|
+
|
|
30
|
+
- **Published testkit declarations accept command builders again**
|
|
31
|
+
(https://github.com/kjanat/dreamcli/issues/122). `runCommand()` now exposes a declaration-safe
|
|
32
|
+
generic `CommandBuilder` parameter while keeping its execution pipeline type-erased internally.
|
|
33
|
+
Package builds also compile the public testing example against the emitted declarations so
|
|
34
|
+
internal-member stripping cannot silently break this contract again.
|
|
35
|
+
|
|
36
|
+
## [4.0.0-rc.1] - 2026-08-12
|
|
37
|
+
|
|
38
|
+
### Added
|
|
39
|
+
|
|
40
|
+
- **Handlers can see where each value came from**
|
|
41
|
+
([#90](https://github.com/kjanat/dreamcli/issues/90)). `ActionParams`,
|
|
42
|
+
`DeriveParams`, and `MiddlewareParams` gain `sources`, keyed like `flags` and
|
|
43
|
+
`args`, holding the full record resolution already produced:
|
|
44
|
+
`{ stage: 'cli' }`, `{ stage: 'cli', via: 'stdin', trigger: 'dash' }`,
|
|
45
|
+
`{ stage: 'stdin', via: 'stdin', trigger: 'fallback' }`,
|
|
46
|
+
`{ stage: 'env', envVar }`, `{ stage: 'config', configPath }`,
|
|
47
|
+
`{ stage: 'prompt' }`, or `{ stage: 'default' }`. An input that resolved no
|
|
48
|
+
value has no record. `wasExplicit(record)` derives the explicit-versus-defaulted
|
|
49
|
+
question from it without dropping `.default()`, which would also drop
|
|
50
|
+
`defaultValue` from the definition document. `ResolveResult.provenance` carries
|
|
51
|
+
the same records for a direct `resolve()` caller, and `readFlags()` hands them
|
|
52
|
+
to a new `onSources` receiver, typed against the definitions record.
|
|
53
|
+
`ResolutionProvenance`, `ResolutionProvenanceRecord`, `InputSources`,
|
|
54
|
+
`SourcesOf`, and `wasExplicit` are exported from the package root. The existing
|
|
55
|
+
`ResolutionProvenance` name continues to describe one input's winning stage;
|
|
56
|
+
`ResolutionProvenanceRecord` names the complete `ResolveResult.provenance`
|
|
57
|
+
object.
|
|
58
|
+
|
|
59
|
+
- **`arg.keyValue()` takes an element builder**
|
|
60
|
+
([#87](https://github.com/kjanat/dreamcli/issues/87)). Entry values used to be
|
|
61
|
+
strings on the positional surface while `flag.keyValue(element)` gave them a
|
|
62
|
+
codec. `arg.keyValue(arg.number().int().min(0))` now resolves
|
|
63
|
+
`mycli scale web=3` to `{ web: 3 }`, with the element's constraints, path
|
|
64
|
+
checks, and Standard Schema validator applied to every entry, from every
|
|
65
|
+
source. The element is guarded the same way flags guard theirs: `ArgConfig`
|
|
66
|
+
gains `elementEligible`, so a builder already described as a positional
|
|
67
|
+
(`.optional()`, `.env()`, `.stdin()`, `.describe()`, …) is refused in element
|
|
68
|
+
position at compile time. `ArgSchema` gains `elementSchema`, which serializes
|
|
69
|
+
into definition documents under the new `ArgElementFragmentV1` shape and the
|
|
70
|
+
`$defs.argElement` meta-schema definition.
|
|
71
|
+
|
|
72
|
+
- **Help names the stdin source.** An input that declares `.stdin()` renders
|
|
73
|
+
`[stdin]` beside the existing `[env: X]`, `[config: y]`, and `[prompt]`
|
|
74
|
+
annotations, on the flag table and the argument table alike. The narrower
|
|
75
|
+
triggers say which one applies: `[stdin: '-']` for `{ when: 'dash' }` and
|
|
76
|
+
`[stdin: when omitted]` for `{ when: 'missing' }`. Completion scripts are
|
|
77
|
+
unchanged; they carry the plain description.
|
|
78
|
+
|
|
79
|
+
- **A dedicated error code for a dash with nothing piped.**
|
|
80
|
+
`ValidationErrorCode` gains `MISSING_STDIN`, which replaces the borrowed
|
|
81
|
+
`REQUIRED_FLAG` / `REQUIRED_ARG` on the one failure that is neither: a `-`
|
|
82
|
+
typed beside other occurrences of a collection when the stream is empty. Those
|
|
83
|
+
two keep their own meaning, a required input no source filled.
|
|
84
|
+
|
|
85
|
+
- **A variadic argument reads stdin from its tail.** `.stdin()` and
|
|
86
|
+
`.variadic()` now compose. A `-` among the tail tokens stands for the whole
|
|
87
|
+
stdin source at that position, so
|
|
88
|
+
`printf 'x\ny\n' | mycli build a - b` collects `['a', 'x', 'y', 'b']`, and an
|
|
89
|
+
empty tail under a binding that covers a missing input takes the whole buffer.
|
|
90
|
+
`arg.keyValue().variadic().stdin()` aggregates entries across the typed tokens
|
|
91
|
+
and the pipe under its `.duplicateKeys()` policy. Each `-` stands for all of
|
|
92
|
+
the buffer, so two of them splice it twice, and the stream is still read at
|
|
93
|
+
most once per invocation. The preflight that decides whether to read stdin
|
|
94
|
+
counts an empty tail as an absent input, which is what makes
|
|
95
|
+
`printf 'x\ny\n' | mycli build` reach the fallback stage under `.run()`.
|
|
96
|
+
|
|
97
|
+
- **`.stdin({ trim: true })` drops the terminator a pipe appends.** Codecs that
|
|
98
|
+
preserve text terminators, including `string` and `path`, keep the buffer byte
|
|
99
|
+
for byte by default. `trim` drops one trailing `\n`, `\r\n`, or `\r` from a
|
|
100
|
+
single value before anything decodes or checks it, so
|
|
101
|
+
`echo ./dist | mycli clean` satisfies `arg.path({ mustExist: true })`. It
|
|
102
|
+
applies to both surfaces, to an explicit `-` and to the implicit fallback, and
|
|
103
|
+
to `readFlags()` and `runCommand()`. Other decoding codecs already remove one
|
|
104
|
+
framing terminator and are unaffected, so no value ever loses two. A collection's
|
|
105
|
+
terminators separate its elements, so `.split({ stdin })` still decides those.
|
|
106
|
+
The binding serializes as `stdin.trim` in definition documents, alongside
|
|
107
|
+
`when` and `consume`.
|
|
108
|
+
|
|
109
|
+
- **Stability policy and a 4.0 upgrade guide** — the
|
|
110
|
+
[stability page](https://dreamcli.kjanat.dev/reference/stability) now places
|
|
111
|
+
every export of the root, `/testkit`, `/runtime`, and `/version` entrypoints
|
|
112
|
+
in one of thirteen categories, each with the rules it carries into a minor
|
|
113
|
+
release: sealed framework values, consumer input options, transparent input
|
|
114
|
+
definitions, implementer ports, externally governed protocols, structural
|
|
115
|
+
consumer configuration, closed unions and discriminated results, open unions,
|
|
116
|
+
framework-produced callback payloads, closed constructible DTOs, serialized
|
|
117
|
+
formats, classes and functions, and internal surface.
|
|
118
|
+
[Upgrading From 3.x To 4.0](https://dreamcli.kjanat.dev/guide/upgrading-v4)
|
|
119
|
+
walks the breaking changes below with before and after code.
|
|
120
|
+
|
|
121
|
+
- **Definition types and normalization factories for flags, args, commands, and
|
|
122
|
+
the CLI** — `createFlagSchema()`, `createCommandSchema()`, and
|
|
123
|
+
`createCLISchema()` join the existing `createArgSchema()`. The flag and arg
|
|
124
|
+
factories take a plain definition object, or a kind plus that kind's fields;
|
|
125
|
+
the command and CLI factories take complete definition objects. Each returns
|
|
126
|
+
the normalized schema; feeding a built schema back in produces a deep-equal
|
|
127
|
+
schema, and a field belonging to another kind throws `INVALID_SCHEMA`.
|
|
128
|
+
`createCommandSchema()` normalizes nested flags, args, and subcommands, and
|
|
129
|
+
`createCLISchema()` normalizes commands and config settings for a description
|
|
130
|
+
of a program with no execution graph attached. Each level ships its definition
|
|
131
|
+
types: `FlagDefinition`,
|
|
132
|
+
`FlagDefinitionBase`, `FlagDefinitionByKind`, `FlagDefinitionOverrides`, and
|
|
133
|
+
the per-kind members `StringFlagDefinition`, `NumberFlagDefinition`,
|
|
134
|
+
`BooleanFlagDefinition`, `EnumFlagDefinition`, `ArrayFlagDefinition`,
|
|
135
|
+
`CustomFlagDefinition`, `CountFlagDefinition`, `KeyValueFlagDefinition`;
|
|
136
|
+
`ArgDefinition`, `ArgDefinitionBase`, `ArgDefinitionByKind`,
|
|
137
|
+
`ArgDefinitionOverrides`, `StringArgDefinition`, `NumberArgDefinition`,
|
|
138
|
+
`EnumArgDefinition`, `CustomArgDefinition`; `CommandDefinition` with
|
|
139
|
+
`CommandArgEntryDefinition`; and `CLIDefinition` with
|
|
140
|
+
`ConfigSettingsDefinition`. All of them are exported from the package root.
|
|
141
|
+
|
|
142
|
+
- **`.builtins()` takes `--help`, `--json`, or `--quiet` over to the commands**
|
|
143
|
+
([#86](https://github.com/kjanat/dreamcli/issues/86)). A CLI whose `--json`
|
|
144
|
+
names the document it operates on, whose `-q` means something domain-specific,
|
|
145
|
+
or whose `--help` is a routable topic browser can now claim the token.
|
|
146
|
+
`cli('mycli').builtins({ json: 'off' })` releases every spelling that built-in
|
|
147
|
+
answers to. The root stops reading and stripping it from argv, root help stops
|
|
148
|
+
listing it under `Global options:`, the `RESERVED_FLAG` guard stops reserving
|
|
149
|
+
it, and a command may declare it as an ordinary flag that parses and reaches
|
|
150
|
+
the handler. Releasing `help` also disables command-level `--help`/`-h`, the
|
|
151
|
+
bare `help` token, the `--help` footer hint, the
|
|
152
|
+
`Run '<bin> --help' for available commands` suggestion on dispatch errors, and
|
|
153
|
+
the synthetic `--help` in generated completion scripts. `version` and
|
|
154
|
+
`completions` have no entry, since `.version()` and `.completions()` are
|
|
155
|
+
opt-in and a CLI declines those by omission. Every built-in defaults to
|
|
156
|
+
`'on'`, repeated calls merge with the last mode per built-in winning, and
|
|
157
|
+
`RunOptions.jsonMode` / `RunOptions.verbosity` keep working regardless, since
|
|
158
|
+
only argv-driven activation is disabled. The state is normalized onto
|
|
159
|
+
`CLISchema.builtins` by both `.builtins()` and the `builtins` field of
|
|
160
|
+
`createCLISchema()`, an invalid mode throws `INVALID_SCHEMA`, and
|
|
161
|
+
`BuiltinsConfig`, `Builtins`, `BuiltinName`, and `BuiltinMode` are exported
|
|
162
|
+
from the package root. `runCommand()` from `/testkit` takes the same
|
|
163
|
+
`builtins` option so a command owning a released flag can be tested; its
|
|
164
|
+
options type is now `RunCommandOptions`. The `RESERVED_FLAG` error offers
|
|
165
|
+
`.builtins({ <name>: 'off' })` alongside renaming, and a version discovered by
|
|
166
|
+
`.manifest()` filesystem walking now runs the same guard at `.run()` time
|
|
167
|
+
instead of silently shadowing a command's `version` flag. That startup failure
|
|
168
|
+
is reported the way every other `.run()` startup failure is: the message and
|
|
169
|
+
its suggestion go to stderr, `--json` puts the serialized error on stdout, and
|
|
170
|
+
the process exits with the error's exit code rather than rejecting the
|
|
171
|
+
`.run()` promise.
|
|
172
|
+
|
|
173
|
+
- **Definition format v1 — versioned, typed documents** — `generateSchema()`
|
|
174
|
+
and `generateCommandSchema()` now emit `schemaVersion: 1`, so a consumer can
|
|
175
|
+
tell which format it is reading before parsing the rest. Both return typed
|
|
176
|
+
documents instead of `Record<string, unknown>`: `DefinitionDocumentV1` for a
|
|
177
|
+
whole CLI, `CommandDefinitionDocumentV1` for a single command, with
|
|
178
|
+
`DefinitionDocument` and `CommandDefinitionDocument` aliasing the current
|
|
179
|
+
version. Documents are distinct from the fragments nested inside them.
|
|
180
|
+
`CommandDefinitionFragmentV1`, `FlagDefinitionFragmentV1`,
|
|
181
|
+
`ArgDefinitionFragmentV1`, `ExampleDefinitionFragmentV1`,
|
|
182
|
+
`PromptDefinitionFragmentV1`, `PromptChoiceFragmentV1`,
|
|
183
|
+
`FlagNegationFragmentV1`, `FlagStringConstraintsFragmentV1`, and
|
|
184
|
+
`FlagPathChecksFragmentV1` carry no `schemaVersion` and take the version of
|
|
185
|
+
the document they sit in. `generateInputSchema()` is standard JSON Schema and
|
|
186
|
+
stays outside the family, typed as `InputSchemaDocument` with
|
|
187
|
+
`InputSchemaBranch` and `InputSchemaProperty`. Every one of these is exported
|
|
188
|
+
from the package root, and the returned documents remain assignable to
|
|
189
|
+
`Record<string, unknown>`. `--help` in `--json` mode serializes through
|
|
190
|
+
`generateCommandSchema()`, so that output gains `schemaVersion: 1` as its
|
|
191
|
+
first key.
|
|
192
|
+
|
|
193
|
+
- **`readFlags()` evaluates a record of flag builders outside a CLI**
|
|
194
|
+
([#107](https://github.com/kjanat/dreamcli/issues/107)). A build script or a
|
|
195
|
+
small tool that wants typed options without commands, handlers, or output
|
|
196
|
+
channels hands its flags straight to `readFlags()` and awaits the resolved
|
|
197
|
+
values, typed by `InferFlags`:
|
|
198
|
+
|
|
199
|
+
```ts
|
|
200
|
+
const options = await readFlags({
|
|
201
|
+
watch: flag.boolean().alias('w').env('WATCH'),
|
|
202
|
+
minify: flag.boolean().env('MINIFY').default(true),
|
|
203
|
+
target: flag.enum(['node', 'browser']).env('TARGET').default('node'),
|
|
204
|
+
});
|
|
205
|
+
|
|
206
|
+
options.watch; // boolean
|
|
207
|
+
options.target; // 'node' | 'browser'
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
Each object key is the canonical flag name, and evaluation runs through the
|
|
211
|
+
same command schema, parser, coercion, resolver, and validation a command
|
|
212
|
+
uses. Aliases, negated spellings, duplicate policy, case parity, unknown-flag
|
|
213
|
+
rejection, collisions between names, aliases and negated forms, the CLI,
|
|
214
|
+
stdin, env, config, prompt, default precedence, constraints, Standard Schema
|
|
215
|
+
validators, and `flag.path()` checks all behave as they do inside `.action()`.
|
|
216
|
+
`argv`, `env`, `stdinData`, `stat`, and `mkdir` fall back to the detected
|
|
217
|
+
`RuntimeAdapter`, while
|
|
218
|
+
`config` and `prompter` stay caller-supplied, since standalone flag reading
|
|
219
|
+
has no application name to discover a file from and opens no terminal session.
|
|
220
|
+
`ReadFlagsOptions` extends `ResolveOptions` with `argv`, `adapter`, `parse`,
|
|
221
|
+
`strict`, `help`, and `onDeprecation`. The adapter is built on the first fact
|
|
222
|
+
the caller left
|
|
223
|
+
out, so a call given `argv` and `env` reads nothing from the host unless a
|
|
224
|
+
`flag.path()` check needs the adapter's filesystem primitives. Failures throw
|
|
225
|
+
`ParseError` and `ValidationError` instead of exiting, a colliding record, the
|
|
226
|
+
definition key `__proto__`, and a record whose prototype is replaced (an
|
|
227
|
+
object-literal `__proto__` key, or `Object.create(base)`, whose inherited
|
|
228
|
+
definitions are never read) each throw `CLIError` before argv is read, and
|
|
229
|
+
`.deprecated()` notices reach `onDeprecation` rather than a warning stream,
|
|
230
|
+
since there is no output channel on this path.
|
|
231
|
+
|
|
232
|
+
A pre-separator `--help` or `-h` prints generated help for the record to the
|
|
233
|
+
adapter's stdout and exits with code 0, with the script named from the
|
|
234
|
+
adapter's argv in the usage line. The built-in yields to a definition that
|
|
235
|
+
claims the `help` or `h` spelling through a name, alias, negated form, or
|
|
236
|
+
case-parity counterpart, and `help: 'off'` removes it entirely; `json` and
|
|
237
|
+
`quiet` are never reserved, so a record may declare them as ordinary flags.
|
|
238
|
+
`strict: false` drops undeclared argv content instead of rejecting it: unknown
|
|
239
|
+
long flags with their inline `=value`, unknown short-group characters,
|
|
240
|
+
positional arguments, and the `--` separator, while value tokens of declared
|
|
241
|
+
flags survive under the parser's own consumption rules and misuse of a
|
|
242
|
+
declared flag keeps its diagnostics.
|
|
243
|
+
|
|
244
|
+
Positional arguments are not part of this API, and there is no
|
|
245
|
+
synchronous variant: prompts, async validators, and filesystem checks make the
|
|
246
|
+
result a promise. `readFlags`, `ReadFlagsOptions`, and `FlagMap` are exported
|
|
247
|
+
from the package root, and
|
|
248
|
+
[Standalone Flag Evaluation](https://dreamcli.kjanat.dev/guide/read-flags)
|
|
249
|
+
walks the API with the build-script case it was added for.
|
|
250
|
+
|
|
251
|
+
- **Purpose-built positional argument kinds and string constraints**
|
|
252
|
+
([#87](https://github.com/kjanat/dreamcli/issues/87)). A base URL, an input
|
|
253
|
+
file, or a cutoff date reads naturally as a positional, and until now the only
|
|
254
|
+
route was `arg.custom()` re-implementing what `flag.url()` already did.
|
|
255
|
+
`arg.url(options?)`, `arg.path(options?)`, `arg.date(options?)`,
|
|
256
|
+
`arg.duration()`, and `arg.bytes()` mirror their flag counterparts: same value
|
|
257
|
+
types, same option objects (`UrlFlagOptions`, `PathFlagOptions`,
|
|
258
|
+
`DateFlagOptions`), same parsers. `arg.string()` takes a `StringConstraints`
|
|
259
|
+
object, and string-kind `ArgBuilder`s carry `.nonEmpty()`, `.minLength()`,
|
|
260
|
+
`.maxLength()`, and `.pattern()` alongside the numeric `.int()`, `.min()`,
|
|
261
|
+
`.max()`, and `.finite()` they already had. Both factories run the same parse
|
|
262
|
+
functions and the same constraint validator, so a value a flag accepts an
|
|
263
|
+
argument accepts, and a rejection carries the same code and the same reason,
|
|
264
|
+
differing in the subject: `for flag --x` versus `for argument <x>`.
|
|
265
|
+
|
|
266
|
+
String constraints are enforced on CLI parse (`INVALID_VALUE`) and on stdin,
|
|
267
|
+
env, config, and prompt resolution (`CONSTRAINT_VIOLATED`), both exit code
|
|
268
|
+
`2`; as with flags, a `.default()` value is checked where it is declared and a
|
|
269
|
+
violation throws `INVALID_DEFAULT`. `arg.path()`
|
|
270
|
+
checks run after resolution through the runtime adapter's `stat`/`mkdir`, the
|
|
271
|
+
same seam `flag.path()` uses, so a piped, env-sourced, config-sourced,
|
|
272
|
+
prompted, or defaulted path is checked like one typed on the command line. A
|
|
273
|
+
variadic argument validates every value it collects, path checks included.
|
|
274
|
+
Argument values sourced from anywhere but argv stay redacted in the message,
|
|
275
|
+
as in `Invalid value '<redacted>' from stdin for argument <x>` and
|
|
276
|
+
`Invalid number value '<redacted>' from config deploy.port for argument <x>`,
|
|
277
|
+
so the flag and argument messages are equivalent apart from their subjects.
|
|
278
|
+
|
|
279
|
+
`ArgSchema` and the arg definition types carry `stringConstraints`,
|
|
280
|
+
`pathChecks`, and `valueHint`. The first two are string-kind gated the way the
|
|
281
|
+
flag schema gates them. Args serialize `numberConstraints`,
|
|
282
|
+
`stringConstraints`, `pathChecks`, and `valueHint` into the definition
|
|
283
|
+
document, which previously emitted none of them, and `generateInputSchema()`
|
|
284
|
+
now surfaces arg string constraints as `minLength` / `maxLength` / `pattern`.
|
|
285
|
+
The meta-schema hoists the `numberConstraints`, `stringConstraints`, and
|
|
286
|
+
`pathChecks` fragments into `$defs` so the flag and arg definitions reference
|
|
287
|
+
one copy. All of it is additive at `schemaVersion: 1`. Help still renders a
|
|
288
|
+
positional by its own name rather than its `valueHint`, so
|
|
289
|
+
`mycli copy <src> <dst>` does not collapse into `<path> <path>`.
|
|
290
|
+
|
|
291
|
+
The flag-only surface stays flag-only, and
|
|
292
|
+
[the arguments guide](https://dreamcli.kjanat.dev/guide/arguments#flag-only-surface)
|
|
293
|
+
lists it with the reason for each entry. `boolean`, `count`, `negatable`,
|
|
294
|
+
`alias`, `duplicates`, `separator`, `unique`, and `propagate` are bound to
|
|
295
|
+
flag syntax; `array` is served by `.variadic()`. `keyValue` merges repeated
|
|
296
|
+
occurrences into one record, which a positional slot cannot express, and
|
|
297
|
+
`arg.custom()` with a Standard Schema validator is the documented route.
|
|
298
|
+
`.config()` and `.prompt()` are no longer among them: both surfaces now
|
|
299
|
+
declare the same sources, described in the unified source model entry below.
|
|
300
|
+
|
|
301
|
+
- **A unified source model — every input uses the same source order** — flags and
|
|
302
|
+
args now declare sources from the same set and resolve declared sources through
|
|
303
|
+
one ordered chain:
|
|
304
|
+
`CLI -> stdin -> env -> config -> prompt -> default`. `arg.config(path)` and
|
|
305
|
+
`arg.prompt(config)` join `arg.env()`, so a positional reads a dotted config
|
|
306
|
+
key and asks the user exactly as a flag does; the arg prompt table mirrors the
|
|
307
|
+
flag one (`PromptConfigByArgKind`, `AllowedArgPromptConfig`), and an
|
|
308
|
+
incompatible pairing throws `CONSTRAINT_VIOLATED` naming `<arg>`. Help
|
|
309
|
+
annotates a positional with `[config: PATH]` and `[prompt]` beside the
|
|
310
|
+
`[env: VAR]` it already showed.
|
|
311
|
+
`flag.string().stdin()` becomes legal on `string`, `number`, `boolean`,
|
|
312
|
+
`enum`, and `custom` flags, giving `echo hi | mycli send` and
|
|
313
|
+
`mycli send --body -` the meaning `arg.stdin()` already had. `.stdin()` takes
|
|
314
|
+
`{ when: 'dash' | 'missing' | 'dash-or-missing', consume: 'exclusive' |
|
|
315
|
+
'broadcast' }` on both surfaces, defaulting to `dash-or-missing` and
|
|
316
|
+
`exclusive`. `StdinBinding`, `StdinOptions`, `StdinWhen`, and `StdinConsume`
|
|
317
|
+
are exported from the package root, and `StdinBindingFragmentV1` names the
|
|
318
|
+
serialized form.
|
|
319
|
+
|
|
320
|
+
An explicit `-` is CLI-sourced with bytes from stdin and keeps CLI precedence;
|
|
321
|
+
an absent input takes the stdin fallback stage, which sits ahead of env, so a
|
|
322
|
+
flag set in the environment still reads a pipe and the pipe wins. The `-`
|
|
323
|
+
sentinel now survives the parse boundary for every kind, so
|
|
324
|
+
`flag.number().stdin()` accepts `--port -` where it used to reject `-` as a
|
|
325
|
+
malformed number. `readFlags()` carries the same contract and reads stdin only
|
|
326
|
+
through the adapter, only when a declared `.stdin()` flag would actually
|
|
327
|
+
select it; `runCommand()` feeds the identical path from its `stdinData`
|
|
328
|
+
option. Stdin is read at most once per invocation, and only when resolution
|
|
329
|
+
will select it: `when: 'dash'` reads on `-` alone, `when: 'missing'` reads on
|
|
330
|
+
an absent input alone, and env, config, prompt, and a default never suppress
|
|
331
|
+
the read.
|
|
332
|
+
|
|
333
|
+
One command has one exclusive stdin consumer. Declaring a second stdin input
|
|
334
|
+
of any kind, flag or arg, throws `DUPLICATE_STDIN_INPUT` on both construction
|
|
335
|
+
paths; `{ consume: 'broadcast' }` on every stdin input opts into sharing one
|
|
336
|
+
buffer among them. The definition document carries the binding as
|
|
337
|
+
`stdin: { when, consume }` on flags and args, with a `stdin` entry in the
|
|
338
|
+
meta-schema `$defs`, and the arg fragment gains `configPath` and `prompt`.
|
|
339
|
+
|
|
340
|
+
- **Cardinality is its own axis, with per-source splitting.** How many values an
|
|
341
|
+
input carries (`one`, `many`, `entries`, `count`) is now decided separately
|
|
342
|
+
from what each value means, so every source fills a collection by the same
|
|
343
|
+
rules. `.split({ cli, env, stdin })` on `flag.array()`, `flag.keyValue()`, and
|
|
344
|
+
the arg builders sets each source's decoding independently: a delimiter or
|
|
345
|
+
`'whole'` for CLI tokens, a delimiter, `'whole'`, or `{ format: 'json' }` for
|
|
346
|
+
env values, and `'lines'`, `'whole'`, a delimiter, or `{ format: 'json' }` for
|
|
347
|
+
the stdin buffer. Defaults are whole CLI tokens (or the `.separator()`
|
|
348
|
+
delimiter), comma-delimited env values, and line-delimited stdin; a config
|
|
349
|
+
value stays a native array or object, and a config string decodes under the
|
|
350
|
+
env policy. JSON is never guessed. `SplitOptions`, `SplitSetting`,
|
|
351
|
+
`SplitPolicy`, `SplitBinding`, `SourceSplitBinding`, and `SplitFormat` are
|
|
352
|
+
exported from the package root, and the definition document carries `split` on
|
|
353
|
+
flag and arg fragments as `SourceSplitFragmentV1` / `SplitPolicyFragmentV1`.
|
|
354
|
+
|
|
355
|
+
- **Collections read stdin, and `-` splices into occurrence order.**
|
|
356
|
+
`flag.array()` and `flag.keyValue()` accept `.stdin()`, and a `-` occurrence
|
|
357
|
+
stands for the whole stdin source at the position it holds:
|
|
358
|
+
`--tag before --tag - --tag after` over `a\nb\n` resolves to
|
|
359
|
+
`['before', 'a', 'b', 'after']`. An explicit `-` and the implicit fallback
|
|
360
|
+
decode identically, entries splice the same way, and the duplicate-key policy
|
|
361
|
+
applies across the whole spliced order. Broadcast consumers each decode the
|
|
362
|
+
one shared buffer under their own binding, so a line-split array flag and a
|
|
363
|
+
JSON key-value flag can read the same pipe.
|
|
364
|
+
|
|
365
|
+
- **`.duplicateKeys()` on key-value inputs.** `'last'` (the default), `'first'`,
|
|
366
|
+
or `'error'` decides what a repeated key means, on every source rather than
|
|
367
|
+
only on repeated CLI occurrences. A repeat under `'error'` reports
|
|
368
|
+
`CONSTRAINT_VIOLATED` naming the key. `DuplicateKeys` is exported from the
|
|
369
|
+
package root and the policy is serialized as `duplicateKeys`.
|
|
370
|
+
|
|
371
|
+
- **`arg.boolean()` and `arg.keyValue()`.** A positional carries no presence
|
|
372
|
+
semantics, so `arg.boolean()` consumes an explicit `true`/`false` (or `1`/`0`)
|
|
373
|
+
token through the shared boolean codec, widening to `yes`/`no` and an empty
|
|
374
|
+
string only for env, config, stdin, and prompt values. `arg.keyValue()`
|
|
375
|
+
consumes `KEY=VALUE` tokens and resolves to `Record<string, string>`, splitting
|
|
376
|
+
at the first `=`; the variadic form aggregates the whole tail into one record.
|
|
377
|
+
`BooleanArgDefinition` and `KeyValueArgDefinition` join the definition types,
|
|
378
|
+
and `ArgKind` gains `'boolean'` and `'keyValue'`.
|
|
379
|
+
|
|
380
|
+
- **Element-level sugar inside collections.** Path checks and constraints belong
|
|
381
|
+
to the element, so `flag.array(flag.path({ mustExist: true }))` checks every
|
|
382
|
+
collected element and `flag.keyValue(flag.path())` checks every entry value.
|
|
383
|
+
`flag.keyValue()` takes an optional element builder, and `flag.path()` is now
|
|
384
|
+
element-eligible.
|
|
385
|
+
|
|
386
|
+
- **`.standard()` on both builders, split into element and aggregate
|
|
387
|
+
validation.** A validator declared on an element builder
|
|
388
|
+
(`flag.array(flag.string().standard(s))`) validates each item or entry value;
|
|
389
|
+
one declared on a builder that already aggregates
|
|
390
|
+
(`flag.array(flag.string()).standard(s)`, `arg.string().variadic().standard(s)`)
|
|
391
|
+
validates the completed array or record after every element passed. Element
|
|
392
|
+
issues name the element (`--tag[1]`, `--vars.KEY`). Sync and async validators
|
|
393
|
+
are both awaited, and every source runs the same pipeline.
|
|
394
|
+
|
|
395
|
+
- **`.unique()` and `.separator()` on args.** A variadic arg deduplicates with
|
|
396
|
+
the same `SameValueZero` semantics an array flag uses, and splits each
|
|
397
|
+
positional token on the CLI separator it declares.
|
|
398
|
+
|
|
399
|
+
### Changed
|
|
400
|
+
|
|
401
|
+
- **Breaking: flag diagnostics redact every value resolved outside a literal
|
|
402
|
+
CLI value.** A
|
|
403
|
+
stdin, environment, config, or prompt value that failed to coerce used to be
|
|
404
|
+
printed and stored under `details.value` on the flag surface, while the
|
|
405
|
+
argument surface already redacted it. Both surfaces now report
|
|
406
|
+
`Invalid value '<redacted>' from env API_TOKEN for flag --token: must match
|
|
407
|
+
/^ghp_/` and omit `value` from `details`. Everything that identifies the
|
|
408
|
+
failure stays: the input name, the source, the expected type, the constraint
|
|
409
|
+
that failed with its bound or pattern, the allowed enum values, and a custom
|
|
410
|
+
parse function's own message. A Standard Schema validator's
|
|
411
|
+
`CONSTRAINT_VIOLATED` failure follows
|
|
412
|
+
the same rule: `details.value` is recorded only for a value typed on the
|
|
413
|
+
command line, and omitted for one a pipe, an explicit `-`, the environment, a
|
|
414
|
+
config file, or a prompt supplied. A literal CLI value is untouched, since it
|
|
415
|
+
is already on the user's screen. Every coercion failure now also carries
|
|
416
|
+
`source: 'env' | 'config' | 'stdin' | 'prompt'` in `details`, which is what
|
|
417
|
+
labels an issue `[env API_TOKEN]` in an aggregate error and what now gives the
|
|
418
|
+
argument surface the same label the flag surface had. The `flag.path()` and
|
|
419
|
+
`arg.path()` filesystem checks read the same rule, so a path a pipe, an
|
|
420
|
+
explicit `-`, the environment, a config file, a prompt, or a declared default
|
|
421
|
+
supplied reports `Path '<redacted>' for flag --key does not exist` and omits
|
|
422
|
+
`value` from `details`; a path typed on the command line is still quoted in
|
|
423
|
+
full. Every element of a collection of paths is checked and redacted
|
|
424
|
+
individually.
|
|
425
|
+
|
|
426
|
+
- **Breaking: a positional declared after a variadic one is a build error.** A
|
|
427
|
+
variadic argument consumes every remaining positional, so anything registered
|
|
428
|
+
behind it could never be filled and a second variadic one had nothing left to
|
|
429
|
+
collect. Both silently produced an argument that stayed empty. `.arg()` and
|
|
430
|
+
`createCommandSchema()` now throw `INVALID_BUILDER_STATE`
|
|
431
|
+
(`Argument <target> comes after variadic argument <files>, which consumes
|
|
432
|
+
every remaining positional`), with the command under `command`, the offending
|
|
433
|
+
argument under `arg`, and the greedy one under `variadicArg`, so a definition
|
|
434
|
+
tree names the nested command that declared the pair. Move the variadic
|
|
435
|
+
argument last.
|
|
436
|
+
|
|
437
|
+
- **Breaking: an explicit `-` with nothing piped is an error inside a
|
|
438
|
+
collection.** `--tag a --tag - --tag b` with an empty pipe used to resolve to
|
|
439
|
+
`['a', 'b']`, dropping the occurrence the user typed. It now fails with
|
|
440
|
+
`MISSING_STDIN` and the message
|
|
441
|
+
`No piped stdin for the '-' occurrence of flag --tag`. Occurrences of nothing
|
|
442
|
+
but `-` are unchanged: they are the whole value, so they still fall through to
|
|
443
|
+
env, config, prompt, and the default, exactly as an absent input does, and the
|
|
444
|
+
implicit `when: 'missing'` fallback that simply does not fire stays silent. A
|
|
445
|
+
scalar `-` falls through for the same reason. Only a collection could be
|
|
446
|
+
silently shortened, so only a collection errors.
|
|
447
|
+
|
|
448
|
+
- **Breaking: the arg collection modifiers require a collection.**
|
|
449
|
+
`createArgSchema('string', { unique: true })` and its siblings used to build,
|
|
450
|
+
storing a field nothing would read. They now state their requirement to the
|
|
451
|
+
compiler and throw `INVALID_SCHEMA` from `createArgSchema()`: `separator` and
|
|
452
|
+
`split` want a variadic argument or `arg.keyValue()`, `unique` a variadic
|
|
453
|
+
argument of a list kind, and `duplicateKeys` `arg.keyValue()`. The values a
|
|
454
|
+
schema already stores as its own default, `unique: false` and
|
|
455
|
+
`duplicateKeys: 'last'`, stay accepted on any kind, so a built `ArgSchema` fed
|
|
456
|
+
back through the factory round-trips. This mirrors the `array | keyValue`
|
|
457
|
+
restriction the flag surface already had. Drop the field, or add
|
|
458
|
+
`variadic: true` alongside it. The matching builder methods are new in 4.0, so
|
|
459
|
+
only definitions composed as data change.
|
|
460
|
+
|
|
461
|
+
- **Breaking: `.stdin()` and `.variadic()` on one argument is now legal.** The
|
|
462
|
+
pairing threw `INVALID_BUILDER_STATE`; the tail-splicing entry under Added
|
|
463
|
+
describes what it does instead. Code that relied on the throw has nothing to
|
|
464
|
+
catch.
|
|
465
|
+
|
|
466
|
+
- **Breaking: declared defaults are validated.** A `.default()` value is
|
|
467
|
+
already the typed value, so it is validated rather than decoded: the codec's
|
|
468
|
+
own domain, string and number constraints, element and aggregate Standard
|
|
469
|
+
Schema validators, the shape the cardinality requires, and the collection rules
|
|
470
|
+
all apply to it. Purely synchronous violations throw `INVALID_DEFAULT` where
|
|
471
|
+
the chain declares them, so `flag.string({ minLength: 3 }).default('ab')` and
|
|
472
|
+
`flag.number().default(Number.POSITIVE_INFINITY)` now fail at construction
|
|
473
|
+
instead of reaching a handler; a constraint added after the default
|
|
474
|
+
(`flag.string().default('ab').minLength(3)`) is checked too, as is a validator
|
|
475
|
+
(`.standard()`). On the definition path, where no compiler stands in the way,
|
|
476
|
+
the domain check also rejects a default of the wrong primitive type and an
|
|
477
|
+
`enum` default outside `enumValues`. Asynchronous
|
|
478
|
+
validators and `flag.path()` filesystem checks stay at resolution time, where
|
|
479
|
+
command resolution awaits the validator or probes the path. Code relying on a default that violates
|
|
480
|
+
its own declaration either fixes the default or widens the constraint
|
|
481
|
+
(`flag.number({ finite: false })` still accepts `Infinity`).
|
|
482
|
+
|
|
483
|
+
- **Breaking: `.separator()` sets the CLI delimiter alone.** Env and config
|
|
484
|
+
string values used to inherit it, so `.separator('|')` silently changed how an
|
|
485
|
+
env var decoded. Env values split on `','` unless `.split({ env })` says
|
|
486
|
+
otherwise. The stdin buffer splits on line terminators by default;
|
|
487
|
+
`.split({ stdin })` can select `'whole'`, `'json'`, or a delimiter instead.
|
|
488
|
+
Config arrays and objects remain native; config strings use the env split policy.
|
|
489
|
+
`.separator('|')` becomes `.split({ cli: '|', env: '|' })` where the old
|
|
490
|
+
coupling was intended.
|
|
491
|
+
|
|
492
|
+
- **Breaking: `FlagSchema` and `ArgSchema` carry the cardinality axis.**
|
|
493
|
+
`FlagSchema` gains `split`, `duplicateKeys`, and `aggregateStandard`;
|
|
494
|
+
`ArgSchema` gains `separator`, `split`, `duplicateKeys`, `unique`, and
|
|
495
|
+
`aggregateStandard`. `elementSchema` and `separator` are valid on `keyValue`
|
|
496
|
+
as well as `array` flags, `standard` is valid on every kind, `aggregateStandard`
|
|
497
|
+
only on a kind that aggregates, and `stdin` is valid on scalar and collection kinds.
|
|
498
|
+
Definition documents serialize the new fields additively at `schemaVersion: 1`,
|
|
499
|
+
which has not shipped, with `split` and `splitPolicy` entries in the
|
|
500
|
+
meta-schema `$defs`.
|
|
501
|
+
|
|
502
|
+
- **Breaking: `.default()` on a variadic arg takes the array.** The type
|
|
503
|
+
parameter followed the element type, so the only value that compiled was a
|
|
504
|
+
single element, which is not what a variadic arg resolves to. It now follows
|
|
505
|
+
`ArgDefaultValue`, the value the arg actually produces:
|
|
506
|
+
`arg.string().variadic().default(['a', 'b'])`, and a record for
|
|
507
|
+
`arg.keyValue()`. `ArgDefaultValue` is exported from the package root.
|
|
508
|
+
|
|
509
|
+
- **Breaking: `ArgSchema.stdinMode` is now `ArgSchema.stdin`** — the boolean
|
|
510
|
+
carried no room for the trigger and sharing modes the unified source model
|
|
511
|
+
needs, so it is replaced by `stdin: StdinBinding | undefined`. `.stdin()` is
|
|
512
|
+
unchanged for callers who pass no options and keeps its exact resolution
|
|
513
|
+
behavior. Code reading the schema directly reads `schema.stdin !== undefined`
|
|
514
|
+
where `schema.stdinMode` used to be, and a definition passed to
|
|
515
|
+
`createArgSchema()` or `createCommandSchema()` writes `stdin: {}` instead of
|
|
516
|
+
`stdinMode: true`. The definition document changes to match: the arg fragment
|
|
517
|
+
emits `stdin: { when, consume }` in place of `stdinMode: true`, at
|
|
518
|
+
`schemaVersion: 1`, which has not shipped.
|
|
519
|
+
|
|
520
|
+
- **Breaking: `DUPLICATE_STDIN_ARG` is now `DUPLICATE_STDIN_INPUT`** — the rule
|
|
521
|
+
covers flags as well as args, and a flag-versus-flag conflict reporting an
|
|
522
|
+
arg-shaped code would be a lie. The message reads `Only one input may consume
|
|
523
|
+
stdin exclusively; <name> already consumes stdin`, naming the input that was
|
|
524
|
+
declared first. `details` names the offending input under `flag` or `arg` and
|
|
525
|
+
the existing one under `existingFlag` or `existingArg`.
|
|
526
|
+
|
|
527
|
+
- **Breaking: stdin values reach non-string codecs without their trailing line
|
|
528
|
+
terminator** — the stdin source hands the whole buffer over byte for byte, so
|
|
529
|
+
`echo hi | mycli` still gives a `string` input `'hi\n'`. Every other codec
|
|
530
|
+
interprets the text, where a terminator a pipe appended is framing rather than
|
|
531
|
+
value, so one trailing `\n`, `\r\n`, or `\r` is dropped before decoding.
|
|
532
|
+
`echo true | mycli` now resolves a boolean input to `true`, `echo 1h30m` to a
|
|
533
|
+
duration, and `echo eu` to an enum member; all three used to fail. A number
|
|
534
|
+
input is unaffected, since `Number()` already ignored the terminator. Stdin
|
|
535
|
+
also stops borrowing the prompt widening table: it accepts exactly what an env
|
|
536
|
+
value accepts, so the prompt-only `y` and `n` boolean spellings are rejected.
|
|
537
|
+
|
|
538
|
+
- **Breaking: a number input rejects blank text instead of reading it as zero.**
|
|
539
|
+
`Number('')` and `Number(' ')` are both `0`, so `PORT= mycli serve`,
|
|
540
|
+
`printf '\n' | mycli serve`, and a config key holding `""` all resolved a
|
|
541
|
+
number input to `0` without a word. All three now fail with `TYPE_MISMATCH`
|
|
542
|
+
and the same `Invalid number value '<redacted>' from …` diagnostic any other
|
|
543
|
+
unreadable value gets, and `mycli serve --port ''` fails at the parse boundary
|
|
544
|
+
where it quotes the token. Whitespace around a real number is still ignored,
|
|
545
|
+
so `' 42 '` and `'42\n'` are unaffected. A `count` flag already guarded this;
|
|
546
|
+
the number codec now does too. Set the variable, or drop it and let the
|
|
547
|
+
default apply.
|
|
548
|
+
|
|
549
|
+
- **Breaking: `CLISchema.commands` and `CLISchema.defaultCommand` hold
|
|
550
|
+
`CommandSchema`** — both used to hold `ErasedCommand` wrappers carrying the
|
|
551
|
+
action handler and an `_execute` function. The execution graph now lives
|
|
552
|
+
beside the schema instead of inside it, so `app.schema.commands[0]` is the
|
|
553
|
+
command schema itself: read `app.schema.commands[0].name` where
|
|
554
|
+
`app.schema.commands[0].schema.name` used to be needed. `ErasedCommand` is
|
|
555
|
+
gone.
|
|
556
|
+
|
|
557
|
+
- **Breaking: `CLISchema.plugins` removed** — plugins are execution state, not
|
|
558
|
+
a description of the program, and `.plugin()` no longer writes to the schema.
|
|
559
|
+
Registration, order, and hook behavior are unchanged.
|
|
560
|
+
|
|
561
|
+
- **Breaking: `CLIBuilder` is factory-only** — its constructor is private, so
|
|
562
|
+
`new CLIBuilder(schema)` no longer compiles. Call `cli(name)` or
|
|
563
|
+
`cli({ ... })`; every builder method still returns a new builder.
|
|
564
|
+
|
|
565
|
+
- **Breaking: `CommandSchema.middleware` removed** — the executor builds the
|
|
566
|
+
handler chain from the builder's ordered execution steps, so registration
|
|
567
|
+
order, handler identity, and runtime behavior are unchanged.
|
|
568
|
+
`CommandDefinition` no longer accepts a `middleware` key, and
|
|
569
|
+
`createCommandSchema()` no longer emits one.
|
|
570
|
+
|
|
571
|
+
- **Breaking: `FlagSchema`, `ArgSchema`, and `CommandSchema` are sealed** — all
|
|
572
|
+
three carry a private brand, so an object literal assembled by hand no longer
|
|
573
|
+
type-checks where a schema is expected. Call `createFlagSchema()`,
|
|
574
|
+
`createArgSchema()`, or `createCommandSchema()` with a definition object to
|
|
575
|
+
obtain one; spreading a built schema keeps the brand, so
|
|
576
|
+
`{ ...schema, description }` still type-checks. `createSchema()` was renamed
|
|
577
|
+
to `createFlagSchema()`, which validates its fields against the kind and
|
|
578
|
+
normalizes a nested `elementSchema`.
|
|
579
|
+
|
|
580
|
+
- **Breaking: `createCommandSchema()` validates what the builder validates** — a
|
|
581
|
+
definition whose flags share a name, an alias, or a negated spelling on one
|
|
582
|
+
command now throws `FLAG_NAME_COLLISION`, and a flag spelled the same way as
|
|
583
|
+
one propagated from an ancestor command throws `PROPAGATED_FLAG_COLLISION`.
|
|
584
|
+
The whole tree is checked, nested subcommands included. Commands built with
|
|
585
|
+
`command()` already refused these at `.flag()` and `.command()`; a definition
|
|
586
|
+
composed as data used to build without complaint and then answer the shared
|
|
587
|
+
spelling with one flag only. Two flags both aliased `v` still parsed under
|
|
588
|
+
`--verbose` and `--version`, help listed `-v` on both, and `-v` set the
|
|
589
|
+
second. The arg invariants moved with them, so a definition declaring a
|
|
590
|
+
positional after a variadic one throws `INVALID_BUILDER_STATE`, and a second
|
|
591
|
+
stdin-backed input throws `DUPLICATE_STDIN_INPUT`, matching `.arg()`.
|
|
592
|
+
Previously, both combinations built without complaint. Two stdin-backed args
|
|
593
|
+
each resolved to the
|
|
594
|
+
whole of stdin, and a positional behind a variadic one silently never filled. Every arg error names the
|
|
595
|
+
command in `details`, since a definition tree reaches them at any depth and
|
|
596
|
+
the arg name alone does not say which command declared it. A flag or arg
|
|
597
|
+
named `__proto__` now throws `INVALID_SCHEMA` from both the factory and the
|
|
598
|
+
builder, the check `readFlags()` already applied to its definitions record.
|
|
599
|
+
The factory and `.arg()` used to accept the key, which sets a prototype rather
|
|
600
|
+
than an entry, so the flag or the value the user typed disappeared; `.flag()`
|
|
601
|
+
used to report `FLAG_NAME_COLLISION` against a flag the command never
|
|
602
|
+
declared. A flag record whose prototype is replaced throws `INVALID_SCHEMA`
|
|
603
|
+
too, since only its own keys are read: an object-literal `__proto__` key lands
|
|
604
|
+
there, and so does `Object.create(base)`, whose inherited flags the factory
|
|
605
|
+
silently dropped. `createCLISchema()` normalizes its commands through the same
|
|
606
|
+
factory and inherits every check, and `readFlags()` reports the same errors it
|
|
607
|
+
always did.
|
|
608
|
+
|
|
609
|
+
- **Breaking: `CLISchema` and `ConfigSettings` are sealed** — both carry a
|
|
610
|
+
private brand, so an object literal assembled by hand no longer type-checks
|
|
611
|
+
where either is expected. Call `cli()` for an executable program or
|
|
612
|
+
`createCLISchema()` for a description; spreading a built schema keeps the
|
|
613
|
+
brand, so `{ ...app.schema, name }` still type-checks. `createCLISchema()`
|
|
614
|
+
throws `INVALID_SCHEMA` on an empty name, which `cli('')` now does too.
|
|
615
|
+
|
|
616
|
+
- **Breaking: `createArgSchema()` validates its fields against the kind** — the
|
|
617
|
+
second parameter is now `ArgDefinitionOverrides<K>` rather than
|
|
618
|
+
`Partial<ArgSchema>`, so `enumValues` on a `string` arg (and the other
|
|
619
|
+
kind-scoped fields) stops compiling and throws `INVALID_SCHEMA` at runtime.
|
|
620
|
+
`enumValues` is required on an `enum` arg. A single definition object
|
|
621
|
+
(`createArgSchema({ kind: 'enum', enumValues })`) is accepted as well.
|
|
622
|
+
|
|
623
|
+
- **Breaking: `Out` gained a required `verbosity` member** — action handlers
|
|
624
|
+
can read `out.verbosity`, and `resolveRenderContext()` exposes the same
|
|
625
|
+
`verbosity` decision for custom content built before `.run()` (including
|
|
626
|
+
`--`-aware `--quiet`/`-q` detection). A hand-rolled `Out` object literal
|
|
627
|
+
stops compiling until it declares one; migrate to a real channel from the
|
|
628
|
+
testkit and spy on it instead:
|
|
629
|
+
|
|
630
|
+
```ts
|
|
631
|
+
const [out] = createCaptureOutput();
|
|
632
|
+
vi.spyOn(out, 'info');
|
|
633
|
+
```
|
|
634
|
+
|
|
635
|
+
Do not spread a channel (`{ ...out, info: vi.fn() }`) — its methods are
|
|
636
|
+
non-enumerable bound copies, so the spread result has none of them.
|
|
637
|
+
|
|
638
|
+
- **Breaking: `Out` and `RenderContext` are sealed** — both interfaces now
|
|
639
|
+
carry a private brand, so implementing or structurally constructing them
|
|
640
|
+
outside the framework no longer type-checks. They are framework-created,
|
|
641
|
+
non-exhaustive values: obtain instances from action parameters,
|
|
642
|
+
`createOutput()`, `createCaptureOutput()`, or `resolveRenderContext()`, and
|
|
643
|
+
expect new readonly members in minor releases. Helpers that only need a
|
|
644
|
+
subset can accept `Pick<Out, 'info' | 'status'>`-style capability types.
|
|
645
|
+
|
|
646
|
+
- **Breaking: internal execution fields left `RunOptions` and
|
|
647
|
+
`CLIRunOptions`** — `out`, `captured`, `mergedSchema`, `meta`, and `plugins`
|
|
648
|
+
were framework-populated fields marked `@internal` yet shipped on the public
|
|
649
|
+
option types. They now live on unexported internal execution options; code
|
|
650
|
+
passing them to `runCommand()` or `.execute()` stops compiling. Inject
|
|
651
|
+
writers via `createCaptureOutput()` options or `OutputOptions.stdout`/
|
|
652
|
+
`stderr` instead of replacing the channel wholesale.
|
|
653
|
+
|
|
654
|
+
- **Breaking: `.execute()` takes `CLIExecuteOptions`**. The new root export
|
|
655
|
+
carries the process-free option surface and has no `adapter` member; passing
|
|
656
|
+
one to `.execute()` stops compiling. `CLIRunOptions` now extends
|
|
657
|
+
`CLIExecuteOptions` with `adapter`, and `.run()` remains the only method that
|
|
658
|
+
accepts it.
|
|
659
|
+
|
|
660
|
+
- **Breaking: `CommandConfig` and the root `AnyCommandBuilder` export removed**.
|
|
661
|
+
`CommandConfig` described the builder's type-level accumulator shape but no
|
|
662
|
+
signature referenced it. `AnyCommandBuilder` is `@internal` erasure machinery
|
|
663
|
+
that appears only on `CommandBuilder`'s underscore members, so the package
|
|
664
|
+
root no longer exports the name.
|
|
665
|
+
|
|
666
|
+
- **Breaking: the canonical `$schema`/`$id` for definition documents is
|
|
667
|
+
self-hosted and format-versioned** —
|
|
668
|
+
`https://dreamcli.kjanat.dev/schemas/definition/v1.schema.json` replaces the
|
|
669
|
+
jsDelivr URL in `generateSchema()` output and in `definitionMetaSchema.$id`.
|
|
670
|
+
The `v1` segment tracks the definition format, so it stays valid for every
|
|
671
|
+
package release that emits `schemaVersion: 1`, and it is permanent once
|
|
672
|
+
published. The `@kjanat/dreamcli/schema` subpath and the jsDelivr URL keep
|
|
673
|
+
serving the same bytes as mirrors. Documents pinned to the old URL still
|
|
674
|
+
validate against a local copy but no longer match the meta-schema's `$schema`
|
|
675
|
+
constant.
|
|
676
|
+
|
|
677
|
+
- **Breaking: a command flag spelled like a root-owned flag now throws
|
|
678
|
+
`RESERVED_FLAG` at build time**
|
|
679
|
+
([#84](https://github.com/kjanat/dreamcli/issues/84)). The root removes
|
|
680
|
+
`--json` and `--quiet`/`-q` from argv before dispatch, intercepts
|
|
681
|
+
`--version`/`-V` once a version is configured, and renders help for
|
|
682
|
+
`--help`/`-h` before a command's flags are parsed. A command declaring one of
|
|
683
|
+
those spellings used to build, run, and render help while its flag stayed
|
|
684
|
+
permanently at its default value. `.command()`, `.default()`, `.version()`,
|
|
685
|
+
`.manifest(data)`, and `createCLISchema()` now reject it with `CLIError` code
|
|
686
|
+
`RESERVED_FLAG`, checking each flag's canonical name, its aliases (hidden ones
|
|
687
|
+
included), and its custom negated spelling (`.negatable({ alias: 'quiet' })`)
|
|
688
|
+
through the whole nested subcommand tree. The error names the colliding flag
|
|
689
|
+
and the root flag that shadows it, and suggests renaming, or `out.status()`
|
|
690
|
+
for output that root `--quiet` suppresses. Near misses such as
|
|
691
|
+
`jsonOutput` or `quietMode` stay legal, the default `--no-<name>` spelling
|
|
692
|
+
never collides, and `version`/`V` stay available to a CLI that declares no
|
|
693
|
+
version.
|
|
694
|
+
|
|
695
|
+
- **`--completions` collision detection now covers negated spellings and the
|
|
696
|
+
definition path.** `.negatable({ alias: 'completions' })` and a
|
|
697
|
+
`createCLISchema()` definition carrying `completionsFlag` both used to build a
|
|
698
|
+
CLI whose command flag the planner intercepted. Both now throw `CLIError` code
|
|
699
|
+
`RESERVED_FLAG`, matching what `.completions({ as: 'flag' })` already rejected
|
|
700
|
+
on the builder.
|
|
701
|
+
|
|
702
|
+
### Removed
|
|
703
|
+
|
|
704
|
+
- **Breaking: `.packageJson()`** — deprecated since 2.5. Use `.manifest()`,
|
|
705
|
+
which defaults to `files: ['package.json']` and accepts the same pre-loaded
|
|
706
|
+
data object.
|
|
707
|
+
|
|
708
|
+
- **Breaking: `.denoJson()`** — deprecated since 2.5. Use
|
|
709
|
+
`.manifest({ files: ['deno.json', 'deno.jsonc', 'jsr.json'] })`.
|
|
710
|
+
|
|
711
|
+
- **Breaking: `ManifestPresetSettings`** — the settings type of the two removed
|
|
712
|
+
presets. Use `ManifestSettings`, which adds `files`.
|
|
713
|
+
|
|
714
|
+
- **Breaking: `PackageJsonSettings`** — the deprecated alias for
|
|
715
|
+
`ResolvedManifestSettings`, the shape stored in
|
|
716
|
+
`CLISchema.packageJsonSettings`. The schema field itself is unchanged.
|
|
717
|
+
|
|
718
|
+
- **Breaking: `discoverPackageJson()`** — deprecated since 2.5. Use
|
|
719
|
+
`discoverManifest(adapter, { startDir, files: ['package.json'] })`; `files`
|
|
720
|
+
already defaults to `['package.json']`.
|
|
721
|
+
|
|
722
|
+
### Fixed
|
|
723
|
+
|
|
724
|
+
- **A variadic argument could not take the prompt its flag twin takes.** The
|
|
725
|
+
argument prompt gate read the kind discriminator alone, so
|
|
726
|
+
`arg.string().variadic().prompt({ kind: 'multiselect' })` was rejected with
|
|
727
|
+
`Prompt kind 'multiselect' is not compatible with string argument <files>`
|
|
728
|
+
while `flag.array(flag.string()).prompt({ kind: 'multiselect' })` resolved,
|
|
729
|
+
and the scalar `input` and `select` kinds the flag surface rejects were
|
|
730
|
+
accepted, resolving a one-element array. The gate now reads the cardinality:
|
|
731
|
+
an argument that collects several values takes `multiselect`, and names itself
|
|
732
|
+
`variadic string argument <files>` when it reports a mismatch.
|
|
733
|
+
`AllowedArgPromptConfig<C>` follows the same rule, so the compiler agrees.
|
|
734
|
+
|
|
735
|
+
- **A collection given a config value of the wrong shape said less on the
|
|
736
|
+
argument surface.** `flag.array(...).config('p')` over `{ p: 5 }` reported
|
|
737
|
+
`Invalid array value from config p for flag --tags`; the positional twin
|
|
738
|
+
reported `Invalid value '<redacted>' from config p for argument <tags>`,
|
|
739
|
+
naming neither the shape nor a value it actually held. Both surfaces now word
|
|
740
|
+
it `Invalid array value` / `Invalid object value`, so the byte-for-byte
|
|
741
|
+
wording rule in [Diagnostics and redaction](https://dreamcli.kjanat.dev/guide/semantics#diagnostics-and-redaction)
|
|
742
|
+
holds for the collection faults too.
|
|
743
|
+
|
|
744
|
+
- **A builder could produce a schema its own factory refuses.** Each modifier
|
|
745
|
+
states the kinds it belongs to through a `this` constraint, which the compiler
|
|
746
|
+
enforces and a JavaScript caller does not see, so `flag.string().separator(',')`
|
|
747
|
+
built a string flag carrying a CLI delimiter and emitted a definition document
|
|
748
|
+
`createFlagSchema()` then rejected with `INVALID_SCHEMA`. Twelve modifiers on
|
|
749
|
+
the flag surface and eleven on the argument surface behaved this way. Every
|
|
750
|
+
builder modifier now runs the same check `createFlagSchema()` /
|
|
751
|
+
`createArgSchema()` run, so what a builder produces is always a definition the
|
|
752
|
+
framework reads back. A test calling such a modifier through `@ts-expect-error`
|
|
753
|
+
and expecting it to build needs `expect(...).toThrow()`.
|
|
754
|
+
|
|
755
|
+
- **The normalization factories accepted a kind they have no arm for.**
|
|
756
|
+
`createFlagSchema('nope')` and `createArgSchema('count')` built a schema whose
|
|
757
|
+
discriminator is outside `FLAG_KINDS` / `ARG_KINDS`, which every exhaustive
|
|
758
|
+
`switch (schema.kind)` downstream falls through. The types forbid the call,
|
|
759
|
+
but a JavaScript caller reached it, and the keyValue prompt gate showed such a
|
|
760
|
+
schema can reach a shipped diagnostic. Both factories now throw
|
|
761
|
+
`INVALID_SCHEMA` with `Unknown flag kind 'nope'` / `Unknown arg kind 'count'`,
|
|
762
|
+
listing the allowed kinds in `details.allowed`, on the two-argument path, the
|
|
763
|
+
definition path, and a nested `elementSchema`.
|
|
764
|
+
|
|
765
|
+
- **`flag.array()` with no element threw a raw `TypeError`.** The factory read
|
|
766
|
+
`.schema` off the element it was handed, so a JavaScript caller omitting it
|
|
767
|
+
got `Cannot read properties of undefined` instead of a framework error. It now
|
|
768
|
+
throws `INVALID_SCHEMA` with `flag.array() requires an element builder`.
|
|
769
|
+
`flag.keyValue()` and `arg.keyValue()`, whose element is optional, apply the
|
|
770
|
+
same check to an element that is supplied.
|
|
771
|
+
|
|
772
|
+
- **A positional cut a parse function's message at its last colon.** Off argv,
|
|
773
|
+
the argument surface rebuilt the reason for a failure by scanning the message
|
|
774
|
+
the flag surface had already written, keeping only the text after the final
|
|
775
|
+
`": "`. Anything a parse function put before a colon was lost, and a reason
|
|
776
|
+
whose own tail held a colon was dropped whole: `arg.url({ protocols: ['https'] })`
|
|
777
|
+
reported `Invalid value '<redacted>' from env ENDPOINT for argument <endpoint>: https`,
|
|
778
|
+
and `arg.date()` reported no reason at all. `arg.duration()`, `arg.bytes()`,
|
|
779
|
+
and every `arg.custom()` whose error text carries a colon were affected the
|
|
780
|
+
same way. Each surface now words its own diagnostic from the value layer's
|
|
781
|
+
verdict, so the reason reaches the argument surface whole.
|
|
782
|
+
|
|
783
|
+
A parse-function failure off argv is also worded the way the flag surface and
|
|
784
|
+
the command line already word it, so `Failed to parse env ENDPOINT for
|
|
785
|
+
argument <endpoint>: URL protocol 'http' is not allowed. Allowed: https`
|
|
786
|
+
replaces the `Invalid value '<redacted>' …` opening, which announced a
|
|
787
|
+
redaction in the same sentence that printed the parse function's own text.
|
|
788
|
+
A test asserting the old opening for a non-argv `arg.url()`, `arg.date()`,
|
|
789
|
+
`arg.duration()`, `arg.bytes()`, or `arg.custom()` message needs the new one.
|
|
790
|
+
|
|
791
|
+
- **A positional withheld what a type mismatch expected.** For a value no
|
|
792
|
+
boolean codec could read, the flag surface reported
|
|
793
|
+
`Invalid boolean value '<redacted>' …` and suggested
|
|
794
|
+
`Set VAR to true/false, 1/0, or yes/no`, while the argument surface reported
|
|
795
|
+
`Invalid value '<redacted>' …` and suggested only `Set VAR to a valid boolean`,
|
|
796
|
+
which is the question rather than the answer. A string a config object could
|
|
797
|
+
not fill carried no `expected` field and no suggestion at all on the argument
|
|
798
|
+
surface. Both now match the flag surface: the message names the type, the
|
|
799
|
+
details carry `expected`, and the suggestion names what the codec reads.
|
|
800
|
+
|
|
801
|
+
- **An argument kind with no compatible prompt was told to use `undefined`.**
|
|
802
|
+
`createArgSchema({ kind: 'keyValue', prompt: … })` reached the prompt gate,
|
|
803
|
+
which took the first allowed prompt kind from an empty list and reported
|
|
804
|
+
`Prompt kind 'input' is not compatible with keyValue argument <vars>. Use
|
|
805
|
+
'undefined' instead` with `Change the prompt to { kind: 'undefined' }`. The
|
|
806
|
+
flag surface already had a branch for a kind that is not promptable at all;
|
|
807
|
+
both surfaces now share it and report
|
|
808
|
+
`keyValue arguments are not promptable` with `Remove the prompt config for <vars>`.
|
|
809
|
+
|
|
810
|
+
- **A key-value input told the user to write an array.** A config value of the
|
|
811
|
+
wrong shape for `flag.keyValue()` or `arg.keyValue()` reported
|
|
812
|
+
`Invalid array value from config c for flag --vars` with `expected: 'array'`
|
|
813
|
+
and `Set c to an array in your config`, which is not what an entries input
|
|
814
|
+
accepts and, for a config value that already was an array, not even a change.
|
|
815
|
+
The fault now carries the shape the cardinality wants: an entries input reads
|
|
816
|
+
`Invalid object value …` with `expected: 'object'` and
|
|
817
|
+
`Set c to an object in your config` on the flag surface and
|
|
818
|
+
`Use KEY=VALUE for <vars>` on the argument surface. A list input is unchanged.
|
|
819
|
+
|
|
820
|
+
- **Five types the stability page classified as public were exported from
|
|
821
|
+
nowhere.** `NodeProcess`, `DenoNamespace`, and `GlobalForDetect` are the host
|
|
822
|
+
objects `createNodeAdapter()`, `createDenoAdapter()`, and `detectRuntime()`
|
|
823
|
+
accept, and the page attributes all three to `@kjanat/dreamcli/runtime`, which
|
|
824
|
+
exported none of them; a caller injecting a host could not name the parameter
|
|
825
|
+
type. `StringArgElementConfig` and `WithoutArgElementEligibility` sat in the
|
|
826
|
+
same sentence as `StringElementConfig`, which the root entrypoint does export.
|
|
827
|
+
All five are now exported, along with the flag-side
|
|
828
|
+
`WithoutElementEligibility` its argument twin mirrors.
|
|
829
|
+
|
|
830
|
+
- **A definition document, its input schema, and help all dropped a default the
|
|
831
|
+
schema still resolved.** `generateSchema()`, `generateInputSchema()`, and
|
|
832
|
+
`formatHelp()` each reported a default only for `presence: 'defaulted'`, but
|
|
833
|
+
resolution uses any `defaultValue` a schema carries, and
|
|
834
|
+
`createFlagSchema({ kind: 'string', defaultValue: 'dist' })` keeps
|
|
835
|
+
`presence: 'optional'`. A document emitted from such a schema decoded back to
|
|
836
|
+
a flag with no default, so a round trip through the format changed behavior;
|
|
837
|
+
the input schema omitted `default`, and help omitted `(default: dist)` for a
|
|
838
|
+
flag that does resolve one. All three now report the default whenever the
|
|
839
|
+
schema carries one, on both surfaces, whatever the presence.
|
|
840
|
+
Builder-authored schemas are unaffected, since `.default()` sets the
|
|
841
|
+
defaulted presence.
|
|
842
|
+
|
|
843
|
+
Help no longer calls such an input required either. A default binding always
|
|
844
|
+
produces a value, so neither `REQUIRED_FLAG` nor `REQUIRED_ARG` can fire for a
|
|
845
|
+
schema carrying a `defaultValue`, yet `flag.string().default('dist').required()`
|
|
846
|
+
rendered `[required]` and hid its own default while the positional twin
|
|
847
|
+
rendered `(default: prod)` and still demanded a token as `<target>`. A
|
|
848
|
+
`defaultValue` now suppresses the `[required]` marker and the angle brackets on
|
|
849
|
+
both surfaces; an input without one is unchanged.
|
|
850
|
+
|
|
851
|
+
- **A duplicate key leaked its text from every non-argv source.** Under
|
|
852
|
+
`.duplicateKeys('error')`, `Duplicate key 'DB_PASSWORD' from env VARS for flag
|
|
853
|
+
--vars` quoted the key in the message, in `details.key`, and in `suggest`,
|
|
854
|
+
whatever source carried it. A key is half of a `KEY=VALUE` pair, so it is
|
|
855
|
+
value text from that source, and the same pair reported `Invalid key-value
|
|
856
|
+
pair '<redacted>'` when it failed to split instead. The key is now quoted only
|
|
857
|
+
for occurrences the user typed on the command line; stdin, env, config, and
|
|
858
|
+
prompt read `Duplicate key '<redacted>'`, carry no `key` in `details`, and
|
|
859
|
+
suggest `Set the repeated key once`. Both surfaces follow the rule.
|
|
860
|
+
|
|
861
|
+
- **A flag reported a JSON shape fault in the wrong order.** `Invalid JSON
|
|
862
|
+
value, expected an object from env VARS for flag --vars` put the expectation
|
|
863
|
+
between the fault and the source that carried it. The flag surface now words
|
|
864
|
+
it as the argument surface already did: `Invalid JSON value from env VARS for
|
|
865
|
+
flag --vars, expected an object`.
|
|
866
|
+
|
|
867
|
+
- **`ArgElementFragmentV1` was documented as public but exported from nowhere.**
|
|
868
|
+
`stability.md` classifies it with the other version 1 fragment types and
|
|
869
|
+
`schema-export.md` names it as the shape of an arg `elementSchema`, but the
|
|
870
|
+
type never reached `@kjanat/dreamcli`. It is exported now, alongside its
|
|
871
|
+
siblings.
|
|
872
|
+
|
|
873
|
+
- **A default rejected on a vowel-initial kind read `a array`.** The
|
|
874
|
+
construction-time `INVALID_DEFAULT` message built its subject with a fixed
|
|
875
|
+
article, so `createFlagSchema('array', …)` and `createFlagSchema('enum', …)`
|
|
876
|
+
produced `Default value for a array flag` and `Default value for a enum flag`.
|
|
877
|
+
Both now read `an`.
|
|
878
|
+
|
|
879
|
+
- **A duplicate key the user typed said it came from stdin.** Under
|
|
880
|
+
`.duplicateKeys('error')`, a repeat among CLI occurrences was worded
|
|
881
|
+
`Duplicate key 'A' from stdin for flag --v`, naming a source the value never
|
|
882
|
+
had, on a command with no pipe at all. CLI occurrences now name no source
|
|
883
|
+
(`Duplicate key 'A' for flag --v`), and a key a `-` occurrence spliced in
|
|
884
|
+
still reads `from stdin`. Each occurrence carries its own source through
|
|
885
|
+
aggregation, so a collection filled from both names whichever one carried the
|
|
886
|
+
repeat. `details` no longer claims `source: 'stdin'` for a typed token, and
|
|
887
|
+
the arg surface follows the same rule with `for argument <vars>`.
|
|
888
|
+
|
|
889
|
+
- **`flag.count().stdin()` threw only on the definition path.** The builder
|
|
890
|
+
method is blocked by its `this` constraint at compile time and
|
|
891
|
+
`createFlagSchema('count', { stdin: {} })` throws `INVALID_SCHEMA`, but a
|
|
892
|
+
JavaScript caller reaching the builder got a count flag carrying a stdin
|
|
893
|
+
binding no stage would ever read. The builder now throws the same error, with
|
|
894
|
+
the same message and code. In 3.x neither path complained: `createSchema()`
|
|
895
|
+
stored `stdinMode: true` on a count flag and `.stdin()` did not exist on the
|
|
896
|
+
count builder at all.
|
|
897
|
+
|
|
898
|
+
- **Flags named after `Object.prototype` members were rejected as duplicates** —
|
|
899
|
+
`.flag('constructor')`, `.flag('toString')`, `.flag('valueOf')`, and every
|
|
900
|
+
other `Object.prototype` member name failed with a `FLAG_NAME_COLLISION`
|
|
901
|
+
claiming the command already declared the flag, on commands that declared no
|
|
902
|
+
flags at all. `collectPropagatedFlags()` read its descendant records the same
|
|
903
|
+
way, so a propagated flag with one of those names would have stopped at every
|
|
904
|
+
intermediate subcommand, and `resolveFlags()` read an `.interactive()`
|
|
905
|
+
resolver's override record the same way, so the inherited method reached the
|
|
906
|
+
prompt gate as a config and failed the command with `CONSTRAINT_VIOLATED`.
|
|
907
|
+
`.flag()` refused the name first, so no 3.x CLI ever got that far. Every one of
|
|
908
|
+
those reads now tests own keys only, so all eleven of those names behave like
|
|
909
|
+
any other and `createCommandSchema()` accepts the schemas `command()` produces.
|
|
910
|
+
`__proto__` is the one `Object.prototype` name still rejected, with
|
|
911
|
+
`INVALID_SCHEMA` on both construction paths, listed under Changed above.
|
|
912
|
+
|
|
913
|
+
- **An env var named after an `Object.prototype` member always read as set** —
|
|
914
|
+
`.env('toString')` on a flag, or on an arg, looked the name up on the env
|
|
915
|
+
record without checking own keys, so an unset variable resolved to the
|
|
916
|
+
inherited method and failed coercion instead of falling through to config,
|
|
917
|
+
prompt, or default. Both lookups now test own keys.
|
|
918
|
+
|
|
919
|
+
- **`.run()` never read stdin for an arg named after an `Object.prototype`
|
|
920
|
+
member** — the precheck that decides whether to read stdin looked the arg name
|
|
921
|
+
up on the parsed positionals without checking own keys, so an arg such as
|
|
922
|
+
`.arg('toString', arg.string().stdin())` looked already supplied. `.run()`
|
|
923
|
+
skipped the read and the command failed with `Missing required argument`
|
|
924
|
+
however much was piped to it. The lookup now tests own keys. `.execute()` and
|
|
925
|
+
the testkit take `stdinData` from the caller and were never affected.
|
|
926
|
+
|
|
927
|
+
- **`out.table()` printed a native method for a column key named after an
|
|
928
|
+
`Object.prototype` member** — a column keyed `toString`, `constructor`, or any
|
|
929
|
+
other member name read the row with a bare lookup, so a row that carried no
|
|
930
|
+
such key rendered `[Function: toString]` in place of the empty cell every
|
|
931
|
+
other missing key produces. Dynamic rows typed as `Record<string, unknown>`
|
|
932
|
+
are the reachable case, including columns inferred from a first row that does
|
|
933
|
+
carry the key. Both the text renderer and the JSON projection now treat a key
|
|
934
|
+
that only `Object.prototype` carries as absent. A key held anywhere earlier in
|
|
935
|
+
the row's prototype chain still renders, so a class getter and an
|
|
936
|
+
`Object.create(defaults)` fallback reach the table as before.
|
|
937
|
+
|
|
938
|
+
- **A Standard Schema validator ran against a native method on a failed
|
|
939
|
+
resolution** — when a required flag or arg was missing, `resolve()` still ran
|
|
940
|
+
the Standard Schema pass before rethrowing, over a values record the failed
|
|
941
|
+
resolver had left empty. The pass read each declared name without checking own
|
|
942
|
+
keys, so a flag or arg named after an `Object.prototype` member handed its
|
|
943
|
+
`flag.custom()` / `arg.custom()` validator the inherited method. The user saw a
|
|
944
|
+
second, invented `CONSTRAINT_VIOLATED` beside the real error. The pass now
|
|
945
|
+
tests own keys.
|
|
946
|
+
|
|
947
|
+
- **Quiet mode leaked spinner and progress output** — activity handles now
|
|
948
|
+
resolve to no-ops under quiet verbosity, including interactive TTYs and
|
|
949
|
+
explicit static fallbacks. Consumers can route informational rows through
|
|
950
|
+
`out.info()` and rely on DreamCLI to suppress the complete presentation
|
|
951
|
+
layer without reading private output policy state.
|
|
952
|
+
|
|
953
|
+
- **`--json=true` and `--quiet=true` failed as unknown flags**
|
|
954
|
+
([#85](https://github.com/kjanat/dreamcli/issues/85)). Both root flags now
|
|
955
|
+
take a value the way `flag.boolean()` does. `true` and `1` enable, `false`
|
|
956
|
+
and `0` disable, the last occurrence wins, and an invalid literal fails with
|
|
957
|
+
the parser's `INVALID_VALUE` error and exit code 2 instead of `Unknown flag`.
|
|
958
|
+
`--help`, `-h`, and `--version` still render ahead of that error, so a
|
|
959
|
+
mistyped value never hides the text that documents the flag. Short `-q` keeps
|
|
960
|
+
its presence-only form, matching short boolean flags at the command level.
|
|
961
|
+
`runCommand()` from `/testkit` reads the same layer, and tokens after `--`
|
|
962
|
+
still reach the command untouched.
|
|
963
|
+
|
|
10
964
|
## [3.0.1] - 2026-07-21
|
|
11
965
|
|
|
12
966
|
No library code changed; this release ships agent-facing material that was
|
|
@@ -1451,7 +2405,14 @@ sections that follow. Upgrading from 2.x is covered by the new
|
|
|
1451
2405
|
- MIT License.
|
|
1452
2406
|
- Markdownlint configuration.
|
|
1453
2407
|
|
|
1454
|
-
[Unreleased]: https://github.com/kjanat/dreamcli/compare/
|
|
2408
|
+
[Unreleased]: https://github.com/kjanat/dreamcli/compare/v4.0.0-rc.2...HEAD
|
|
2409
|
+
[4.0.0-rc.2]: https://github.com/kjanat/dreamcli/compare/v4.0.0-rc.1...v4.0.0-rc.2
|
|
2410
|
+
[4.0.0-rc.1]: https://github.com/kjanat/dreamcli/compare/v3.0.1...v4.0.0-rc.1
|
|
2411
|
+
[3.0.1]: https://github.com/kjanat/dreamcli/compare/v3.0.0...v3.0.1
|
|
2412
|
+
[3.0.0]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.20...v3.0.0
|
|
2413
|
+
[3.0.0-rc.20]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.19...v3.0.0-rc.20
|
|
2414
|
+
[3.0.0-rc.19]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.18...v3.0.0-rc.19
|
|
2415
|
+
[3.0.0-rc.18]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.17...v3.0.0-rc.18
|
|
1455
2416
|
[3.0.0-rc.17]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.16...v3.0.0-rc.17
|
|
1456
2417
|
[3.0.0-rc.16]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.15...v3.0.0-rc.16
|
|
1457
2418
|
[3.0.0-rc.15]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.14...v3.0.0-rc.15
|