@kjanat/dreamcli 2.4.1 → 3.0.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +169 -1
- package/README.md +14 -7
- package/dist/core/cli/index.d.mts +283 -81
- package/dist/core/cli/index.mjs +1 -1
- package/dist/core/cli/planner.d.mts +27 -5
- package/dist/core/cli/planner.mjs +1 -1
- package/dist/core/cli/root-help.d.mts +16 -2
- package/dist/core/cli/root-help.mjs +3 -5
- package/dist/core/cli/root-surface.d.mts +18 -3
- package/dist/core/cli/root-surface.mjs +1 -1
- package/dist/core/cli/runtime-preflight.d.mts +31 -5
- package/dist/core/cli/runtime-preflight.mjs +1 -1
- package/dist/core/completion/index.d.mts +32 -1
- package/dist/core/completion/index.mjs +1 -1
- package/dist/core/completion/shells/shared.d.mts +10 -0
- package/dist/core/completion/shells/shared.mjs +1 -1
- package/dist/core/config/index.d.mts +2 -2
- package/dist/core/config/package-json.d.mts +93 -20
- package/dist/core/config/package-json.mjs +3 -1
- package/dist/core/help/index.d.mts +45 -1
- package/dist/core/help/index.mjs +6 -6
- package/dist/core/json-schema/index.mjs +1 -1
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
- package/dist/core/parse/index.d.mts +15 -1
- package/dist/core/parse/index.mjs +1 -1
- package/dist/core/prompt/index.d.mts +11 -3
- package/dist/core/prompt/index.mjs +3 -3
- package/dist/core/resolve/coerce.mjs +1 -1
- package/dist/core/resolve/flags.mjs +1 -1
- package/dist/core/resolve/property.d.mts +2 -0
- package/dist/core/resolve/property.mjs +1 -1
- package/dist/core/schema/arg.d.mts +90 -10
- package/dist/core/schema/arg.mjs +1 -1
- package/dist/core/schema/command.d.mts +3 -1
- package/dist/core/schema/flag.d.mts +92 -2
- package/dist/core/schema/flag.mjs +1 -1
- package/dist/core/schema/index.d.mts +2 -1
- package/dist/core/schema/number-constraints.d.mts +96 -0
- package/dist/core/schema/number-constraints.mjs +1 -0
- package/dist/core/schema/prompt.d.mts +15 -0
- package/dist/core/schema/run.d.mts +4 -4
- package/dist/core/testkit/index.d.mts +9 -5
- package/dist/core/testkit/index.mjs +1 -1
- package/dist/index.d.mts +4 -3
- package/dist/index.mjs +1 -1
- package/dist/runtime/auto.mjs +1 -1
- package/dist/runtime/bun.mjs +1 -1
- package/dist/runtime/deno.mjs +2 -2
- package/dist/runtime/node.mjs +2 -2
- package/dist/version.mjs +1 -1
- package/examples/basic.ts +5 -1
- package/examples/gh/package.json +2 -7
- package/examples/pwsh-demo/package.json +1 -7
- package/examples/pwsh-demo/src/main.test.ts +1 -4
- package/examples/pwsh-demo/src/main.ts +14 -4
- package/examples/transport-launcher.ts +85 -0
- package/package.json +15 -24
- package/src/core/cli/dispatch.ts +7 -1
- package/src/core/cli/index.ts +521 -122
- package/src/core/cli/planner.ts +192 -23
- package/src/core/cli/root-help.ts +195 -105
- package/src/core/cli/root-surface.ts +25 -12
- package/src/core/cli/runtime-preflight.ts +43 -8
- package/src/core/completion/index.ts +50 -0
- package/src/core/completion/shells/powershell.ts +2 -2
- package/src/core/completion/shells/shared.ts +30 -3
- package/src/core/config/index.ts +12 -2
- package/src/core/config/package-json.ts +250 -41
- package/src/core/execution/index.ts +1 -4
- package/src/core/help/index.ts +57 -10
- package/src/core/json-schema/index.ts +23 -4
- package/src/core/json-schema/meta-descriptions.generated.ts +115 -98
- package/src/core/parse/index.ts +62 -1
- package/src/core/prompt/index.ts +54 -14
- package/src/core/resolve/coerce.ts +73 -5
- package/src/core/resolve/flags.ts +14 -0
- package/src/core/resolve/property.ts +4 -4
- package/src/core/schema/arg.ts +125 -3
- package/src/core/schema/command.ts +3 -1
- package/src/core/schema/flag.ts +120 -4
- package/src/core/schema/index.ts +5 -0
- package/src/core/schema/number-constraints.ts +153 -0
- package/src/core/schema/prompt.ts +15 -0
- package/src/core/schema/run.ts +4 -4
- package/src/core/testkit/index.ts +32 -8
- package/src/index.ts +8 -0
- package/src/runtime/auto.ts +0 -24
- package/src/runtime/bun.ts +0 -7
- package/src/runtime/deno.ts +0 -2
- package/src/runtime/node.ts +0 -11
- package/src/runtime/support.ts +1 -59
- package/src/schema.ts +16 -0
- package/dist/runtime/support.d.mts +0 -42
- package/dist/runtime/support.mjs +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,172 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [3.0.0-rc.1] - 2026-07-02
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- **`.completions({ as: 'flag' })`** — expose shell completion as an eager
|
|
15
|
+
`--completions <shell>` flag on the CLI root instead of a `completions`
|
|
16
|
+
subcommand. The planner intercepts the flag before dispatch, prints the script,
|
|
17
|
+
and exits; root help advertises `--completions <bash|zsh|fish|powershell>` in its
|
|
18
|
+
`Flags:` section. `.completions()` still defaults to `{ as: 'command' }`. Because
|
|
19
|
+
the eager flag is intercepted before dispatch, the `--completions` name is
|
|
20
|
+
reserved in flag mode — declaring a command/default flag of that name throws at
|
|
21
|
+
build time.
|
|
22
|
+
- **Shell auto-detection** — `--completions` with no value (flag form) resolves the
|
|
23
|
+
target shell from the environment: `$SHELL` (parsed as an interpreter path) wins
|
|
24
|
+
when it names a supported shell, otherwise the presence of `$PSModulePath` selects
|
|
25
|
+
PowerShell — the reliable signal for `pwsh`, which never sets `$SHELL`.
|
|
26
|
+
- **`detectShell(env)` / `normalizeShell(raw)`** — exported helpers behind the
|
|
27
|
+
detection above; `normalizeShell` accepts bare names, `$SHELL` paths, and the
|
|
28
|
+
`pwsh`/`powershell` pair.
|
|
29
|
+
- **`.help(config)` builder + extended `HelpOptions`** — configure root-help
|
|
30
|
+
rendering: `inlineDefault`, `showDefaultInCommands`, and `footer` (plus the
|
|
31
|
+
existing `width` / `hyperlinks`). Builder config is merged under runtime
|
|
32
|
+
`options.help` (runtime wins).
|
|
33
|
+
- **Numeric constraints for number flags and args** — `flag.number()` and
|
|
34
|
+
`arg.number()` now accept `{ min?, max?, int?, finite? }` (bounds inclusive),
|
|
35
|
+
and the same constraints compose via chained `.int()` / `.min(n)` / `.max(n)` /
|
|
36
|
+
`.finite(allow?)` methods (a later call overrides an earlier value, including
|
|
37
|
+
one set in the options object). The chained methods are compile-time guarded
|
|
38
|
+
to number-kind builders only. Constraints are enforced identically across the
|
|
39
|
+
parse path and the env/config/prompt resolution path (order: finite → int →
|
|
40
|
+
min → max): parse-time (CLI) violations throw `INVALID_VALUE`, while
|
|
41
|
+
env/config/prompt coercion reports `CONSTRAINT_VIOLATED` (both exit code `2`).
|
|
42
|
+
They are also surfaced in the exported JSON Schema as `minimum` / `maximum` and
|
|
43
|
+
`type: "integer"` when `int` is set. `min` / `max` must be finite — a
|
|
44
|
+
non-finite bound (`Infinity` / `-Infinity` / `NaN`) throws at construction. The
|
|
45
|
+
resolved TypeScript value type stays `number`.
|
|
46
|
+
- **Prompt-level defaults for `confirm` and `input` prompts** — `confirm`
|
|
47
|
+
prompts accept `default?: boolean` (drives the `(Y/n)` vs `(y/N)` hint and the
|
|
48
|
+
empty-line result, so a confirm can default to **No**), and `input` prompts
|
|
49
|
+
accept `default?: string` (shown in the hint as `(default: <value>)` and used
|
|
50
|
+
when the user presses Enter, skipping `validate`). Precedence among defaults is
|
|
51
|
+
prompt-level `default` > flag `.default()`. Unset `confirm` default stays
|
|
52
|
+
backward compatible (`true`).
|
|
53
|
+
|
|
54
|
+
### Changed
|
|
55
|
+
|
|
56
|
+
- **BREAKING — the default command is now the root _surface_, not a named
|
|
57
|
+
subcommand.** `.default(cmd)` registers the command only as the default; it is no
|
|
58
|
+
longer added to `schema.commands`. Consequences:
|
|
59
|
+
- It can no longer be invoked by its own name (`mycli mycmd` does not route to it;
|
|
60
|
+
the token is treated as input to the default command).
|
|
61
|
+
- It is omitted from the root `Commands:` list by default (re-enable with
|
|
62
|
+
`.help({ showDefaultInCommands: true })`).
|
|
63
|
+
- Root `--help` renders the default command's `Arguments:`/`Flags:` inline even
|
|
64
|
+
when sibling commands exist (previously only when it was the sole command), and a
|
|
65
|
+
sole default with no subcommands shows its own usage line directly instead of a
|
|
66
|
+
`[command]` placeholder.
|
|
67
|
+
- **`finite` defaults to `true` (behavior change)** — `flag.number()` /
|
|
68
|
+
`arg.number()` now **reject `Infinity` and `-Infinity`**, which previously
|
|
69
|
+
passed straight through to handlers (`Number("Infinity")` is not `NaN`). Pass
|
|
70
|
+
`{ finite: false }` (or `.finite(false)`) to opt back into accepting non-finite
|
|
71
|
+
values. `NaN` continues to be rejected as before.
|
|
72
|
+
- **BREAKING — the runtime no longer hard-fails the host CLI on its version.**
|
|
73
|
+
Adapter construction previously threw (a bare, uncaught `Error`) when the
|
|
74
|
+
detected Node/Bun/Deno version was below DreamCLI's declared minimum, crashing
|
|
75
|
+
the consumer's CLI — including on `--help`. That check is removed: as a
|
|
76
|
+
dependency the consumer's package manager already enforces the `engines` range
|
|
77
|
+
at install time (and more softly), and when DreamCLI is bundled/inlined the
|
|
78
|
+
consumer — not us — owns their CLI's supported-runtime policy. `SUPPORTED_RUNTIMES`
|
|
79
|
+
and the generated `engines` minimums are unchanged and remain the source of
|
|
80
|
+
truth for docs and packaging.
|
|
81
|
+
|
|
82
|
+
### Fixed
|
|
83
|
+
|
|
84
|
+
- **Empty `input`-prompt answer no longer clobbers a flag's `.default()`** — a
|
|
85
|
+
flag declared with both `.default(...)` and an `input` prompt previously
|
|
86
|
+
resolved to `""` when the user submitted an empty line, because empty input was
|
|
87
|
+
treated as a real answer that short-circuited the default fallback. An empty or
|
|
88
|
+
blank `input` answer with no prompt-level `default` is now treated as "no
|
|
89
|
+
answer", so resolution falls through to the flag's `.default()` (or, for a
|
|
90
|
+
required flag, the standard missing-flag error).
|
|
91
|
+
|
|
92
|
+
### Fixed
|
|
93
|
+
|
|
94
|
+
- **Root `--help` now matches consistently with `--version`** (#29) — previously
|
|
95
|
+
`--help` / `-h` were intercepted at the root only when they were the very first
|
|
96
|
+
token, while `--version` / `-V` matched anywhere before `--`. A help flag
|
|
97
|
+
preceded only by flags (e.g. `mycli --verbose --help`) now shows root help,
|
|
98
|
+
mirroring `mycli --verbose --version`. A help flag that follows a subcommand
|
|
99
|
+
token still scopes to that subcommand (`mycli deploy --help` → `deploy` help);
|
|
100
|
+
`--version` remains a global, position-independent flag by design (there is no
|
|
101
|
+
per-command version). The bare `help` token now triggers root help from the same
|
|
102
|
+
position as `--help`, and the `--` end-of-options separator is respected for both.
|
|
103
|
+
- **Generated `--help` now advertises the active built-in global flags** (#32) — root
|
|
104
|
+
help renders a `Global options:` block listing `--help, -h` and `--json` (always),
|
|
105
|
+
`--version, -V` (when a version is set), and `--config <path>` (when `.config()`
|
|
106
|
+
enabled config discovery). Previously these framework-provided flags were invisible
|
|
107
|
+
in help even though they worked. `--completions` is unchanged (still advertised via
|
|
108
|
+
the inline surface when active).
|
|
109
|
+
- **Root usage no longer prints the default command's name** — the merged/sole-default
|
|
110
|
+
usage line rendered `Usage: <bin> <default-name> …`, teaching an invocation that does
|
|
111
|
+
not route (`.default()` is not a named command, so the token is consumed as the
|
|
112
|
+
default's first positional). It now renders under the bin name only
|
|
113
|
+
(`Usage: <bin> [flags] <args>`).
|
|
114
|
+
- **`inlineDefault: false` no longer hides a sole default command's interface** — when
|
|
115
|
+
the default command is the only surface (no visible subcommands and no eager
|
|
116
|
+
`--completions` flag), root help would collapse to a bare `Usage: <bin> [options]`
|
|
117
|
+
with no discoverable args/flags. The default is now always rendered inline in that
|
|
118
|
+
case, since suppressing it leaves no other path to its interface.
|
|
119
|
+
|
|
120
|
+
### Fixed
|
|
121
|
+
|
|
122
|
+
- **`runCommand()` now honors a CLI-level `--json` passed in `argv`** — the testkit
|
|
123
|
+
gained the same root-flag layer as the real CLI: a `--json` before the `--`
|
|
124
|
+
separator enables JSON mode and is stripped before parsing, instead of failing
|
|
125
|
+
with `Unknown flag --json` (exit 2). A literal `--json` after `--` still reaches
|
|
126
|
+
the command unchanged. The existing `{ jsonMode: true }` option keeps working —
|
|
127
|
+
either source enables JSON mode. Copying a real `mycli --json …` invocation into a
|
|
128
|
+
test now works verbatim.
|
|
129
|
+
- **`createTestPrompter()` now runs an `input` prompt's `validate`** — a queued
|
|
130
|
+
string answer to an `input` prompt is validated exactly as the terminal prompter
|
|
131
|
+
does; an answer that fails validation is rejected as a cancellation rather than
|
|
132
|
+
injected verbatim as the resolved value, so prompt validation is integration-testable
|
|
133
|
+
through `runCommand(cmd, argv, { answers })`. Non-string answers stay verbatim so
|
|
134
|
+
downstream coercion paths remain testable.
|
|
135
|
+
|
|
136
|
+
## [2.5.0] - 2026-06-28
|
|
137
|
+
|
|
138
|
+
### Added
|
|
139
|
+
|
|
140
|
+
- **`.manifest()` — runtime-agnostic manifest discovery** — discover CLI metadata
|
|
141
|
+
from any manifest file, not just `package.json`. Pass `files` to choose candidate
|
|
142
|
+
filenames in priority order (e.g. `['deno.json', 'jsr.json']`); discovery walks up
|
|
143
|
+
from `cwd` (or `from`) and the nearest manifest directory wins. Files are parsed as
|
|
144
|
+
JSON with a JSONC fallback, so `package.json`, `deno.json`, `jsr.json`, and
|
|
145
|
+
`deno.jsonc` all work — including manifests with `//` / block comments or trailing
|
|
146
|
+
commas (a dependency-free, string-aware strip that leaves `//` inside string values
|
|
147
|
+
such as URLs untouched).
|
|
148
|
+
- **`discoverManifest()`** — the generalized discovery helper behind `.manifest()`,
|
|
149
|
+
accepting `{ startDir, files }`.
|
|
150
|
+
- **Optional scope retention in name inference** — `inferName` now accepts
|
|
151
|
+
`{ scope: 'keep' | 'strip' }` (and `inferCliName(pkg, { stripScope })`) so a scoped
|
|
152
|
+
`name` like `@scope/mycli` can be kept verbatim instead of always stripping to
|
|
153
|
+
`mycli`. Relevant for `deno.json` / `jsr.json`, which have no `bin` field.
|
|
154
|
+
- **`.denoJson()`** — deprecated convenience preset for
|
|
155
|
+
`.manifest({ files: ['deno.json', 'deno.jsonc', 'jsr.json'] })` (see Deprecated below).
|
|
156
|
+
|
|
157
|
+
### Changed
|
|
158
|
+
|
|
159
|
+
- **Manifest discovery now requires recognized metadata to count as a hit** — a
|
|
160
|
+
parseable but metadata-less manifest (`{}`, or one carrying only non-metadata
|
|
161
|
+
fields such as `dependencies` / `scripts` / `type`, or a config-only `deno.json`
|
|
162
|
+
with just `tasks` / `imports`) is no longer treated as a match. Discovery now
|
|
163
|
+
walks up to parent directories and tries the remaining candidate files instead
|
|
164
|
+
of halting. This also changes the deprecated `discoverPackageJson()` /
|
|
165
|
+
`.packageJson()`: where a metadata-less `package.json` previously halted the
|
|
166
|
+
walk-up and resolved to `{}`, the walk-up now continues, so an ancestor's
|
|
167
|
+
version can surface (relevant in monorepos). Pass pre-loaded `data` or an
|
|
168
|
+
explicit `from` / `startDir` to pin discovery to one directory.
|
|
169
|
+
|
|
170
|
+
### Deprecated
|
|
171
|
+
|
|
172
|
+
- **`.packageJson()`, `.denoJson()`, and `discoverPackageJson()`** — superseded by
|
|
173
|
+
`.manifest()` / `discoverManifest()`, whose defaults (`['package.json']`) match the
|
|
174
|
+
old behavior. All still work, delegating to the generalized path.
|
|
175
|
+
|
|
10
176
|
## [2.4.1] - 2026-06-27
|
|
11
177
|
|
|
12
178
|
### Fixed
|
|
@@ -838,7 +1004,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
838
1004
|
- MIT License.
|
|
839
1005
|
- Markdownlint configuration.
|
|
840
1006
|
|
|
841
|
-
[Unreleased]: https://github.com/kjanat/dreamcli/compare/
|
|
1007
|
+
[Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.1...HEAD
|
|
1008
|
+
[3.0.0-rc.1]: https://github.com/kjanat/dreamcli/compare/v2.5.0...v3.0.0-rc.1
|
|
1009
|
+
[2.5.0]: https://github.com/kjanat/dreamcli/compare/v2.4.1...v2.5.0
|
|
842
1010
|
[2.4.1]: https://github.com/kjanat/dreamcli/compare/v2.4.0...v2.4.1
|
|
843
1011
|
[2.4.0]: https://github.com/kjanat/dreamcli/compare/v2.3.0...v2.4.0
|
|
844
1012
|
[2.3.0]: https://github.com/kjanat/dreamcli/compare/v2.2.1...v2.3.0
|
package/README.md
CHANGED
|
@@ -76,7 +76,11 @@ const greet = command('greet')
|
|
|
76
76
|
flag.number().default(1).describe('Repeat count'),
|
|
77
77
|
)
|
|
78
78
|
.action(({ args, flags, out }) => {
|
|
79
|
-
|
|
79
|
+
const repeatCount = Number.isFinite(flags.times)
|
|
80
|
+
? Math.max(0, Math.min(100, Math.floor(flags.times)))
|
|
81
|
+
: 1;
|
|
82
|
+
|
|
83
|
+
for (let i = 0; i < repeatCount; i++) {
|
|
80
84
|
const msg = `Hello, ${args.name}!`;
|
|
81
85
|
out.log(flags.loud ? msg.toUpperCase() : msg);
|
|
82
86
|
}
|
|
@@ -531,7 +535,7 @@ expect(activity.activity).toContainEqual(
|
|
|
531
535
|
|
|
532
536
|
## Package structure
|
|
533
537
|
|
|
534
|
-
|
|
538
|
+
The code lives behind three focused subpath exports:
|
|
535
539
|
|
|
536
540
|
| Import | Purpose |
|
|
537
541
|
| -------------------------- | -------------------------------------------------------------------------------------- |
|
|
@@ -539,15 +543,18 @@ Three subpath exports, each with a focused API surface:
|
|
|
539
543
|
| `@kjanat/dreamcli/testkit` | `runCommand()`, `createCaptureOutput()`, `createTestPrompter()`, `createTestAdapter()` |
|
|
540
544
|
| `@kjanat/dreamcli/runtime` | `createAdapter()`, `RuntimeAdapter`, runtime detection, platform adapters |
|
|
541
545
|
|
|
546
|
+
A fourth export, `@kjanat/dreamcli/schema`, ships the bundled JSON Schema (`dreamcli.schema.json`)
|
|
547
|
+
for editor and config validation.
|
|
548
|
+
|
|
542
549
|
ESM-only. Source included in package (`src/`).
|
|
543
550
|
|
|
544
551
|
## Runtime support
|
|
545
552
|
|
|
546
|
-
| Runtime | Status
|
|
547
|
-
| ------------------ |
|
|
548
|
-
| Node.js >= 22.22.2 | Supported
|
|
549
|
-
| Bun >= 1.3 | Supported
|
|
550
|
-
| Deno >= 2.6.0 | Supported (
|
|
553
|
+
| Runtime | Status |
|
|
554
|
+
| ------------------ | ---------------------------------- |
|
|
555
|
+
| Node.js >= 22.22.2 | Supported |
|
|
556
|
+
| Bun >= 1.3 | Supported |
|
|
557
|
+
| Deno >= 2.6.0 | Supported (`jsr:@kjanat/dreamcli`) |
|
|
551
558
|
|
|
552
559
|
Runtime detection is automatic.
|
|
553
560
|
The core framework never imports platform-specific APIs directly — a thin `RuntimeAdapter` interface
|