@kjanat/dreamcli 2.5.0 → 3.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 +153 -1
- package/README.md +9 -2
- package/dist/core/cli/dispatch.mjs +214 -1
- package/dist/core/cli/help-links.mjs +41 -1
- package/dist/core/cli/index.d.mts +109 -16
- package/dist/core/cli/index.mjs +901 -1
- package/dist/core/cli/planner.d.mts +27 -5
- package/dist/core/cli/planner.mjs +300 -1
- package/dist/core/cli/plugin.mjs +41 -1
- package/dist/core/cli/propagate.mjs +57 -1
- package/dist/core/cli/root-help.d.mts +16 -2
- package/dist/core/cli/root-help.mjs +208 -6
- package/dist/core/cli/root-surface.d.mts +18 -3
- package/dist/core/cli/root-surface.mjs +27 -1
- package/dist/core/cli/runtime-preflight.d.mts +16 -1
- package/dist/core/cli/runtime-preflight.mjs +168 -1
- package/dist/core/completion/index.d.mts +32 -1
- package/dist/core/completion/index.mjs +90 -1
- package/dist/core/completion/shells/bash.mjs +304 -3
- package/dist/core/completion/shells/fish.mjs +159 -2
- package/dist/core/completion/shells/powershell.mjs +353 -2
- package/dist/core/completion/shells/shared.d.mts +10 -0
- package/dist/core/completion/shells/shared.mjs +154 -1
- package/dist/core/completion/shells/zsh.mjs +244 -2
- package/dist/core/config/index.mjs +246 -1
- package/dist/core/config/package-json.mjs +385 -3
- package/dist/core/errors/index.mjs +87 -1
- package/dist/core/execution/index.mjs +189 -1
- package/dist/core/help/ansi.mjs +122 -2
- package/dist/core/help/index.d.mts +45 -1
- package/dist/core/help/index.mjs +329 -7
- package/dist/core/json-schema/index.mjs +487 -9
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
- package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
- package/dist/core/output/activity.mjs +452 -1
- package/dist/core/output/bind.mjs +56 -1
- package/dist/core/output/contracts.mjs +57 -1
- package/dist/core/output/display-value.mjs +32 -1
- package/dist/core/output/index.d.mts +21 -0
- package/dist/core/output/index.mjs +442 -2
- package/dist/core/output/renderers.mjs +46 -1
- package/dist/core/output/writer.mjs +12 -1
- package/dist/core/parse/index.d.mts +15 -1
- package/dist/core/parse/index.mjs +555 -1
- package/dist/core/prompt/index.d.mts +11 -4
- package/dist/core/prompt/index.mjs +348 -6
- package/dist/core/resolve/args.mjs +105 -1
- package/dist/core/resolve/coerce.mjs +279 -1
- package/dist/core/resolve/config.mjs +19 -1
- package/dist/core/resolve/errors.mjs +140 -2
- package/dist/core/resolve/flags.mjs +196 -1
- package/dist/core/resolve/index.mjs +85 -1
- package/dist/core/resolve/property.d.mts +2 -1
- package/dist/core/resolve/property.mjs +45 -1
- package/dist/core/schema/arg.d.mts +90 -10
- package/dist/core/schema/arg.mjs +463 -1
- package/dist/core/schema/command.d.mts +21 -1
- package/dist/core/schema/command.mjs +712 -1
- package/dist/core/schema/flag.d.mts +92 -2
- package/dist/core/schema/flag.mjs +453 -1
- package/dist/core/schema/index.d.mts +2 -1
- package/dist/core/schema/middleware.mjs +41 -1
- package/dist/core/schema/number-constraints.d.mts +96 -0
- package/dist/core/schema/number-constraints.mjs +60 -0
- package/dist/core/schema/prompt.d.mts +15 -0
- package/dist/core/schema/run.d.mts +4 -4
- package/dist/core/schema-dsl/runtime.mjs +271 -2
- package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
- package/dist/core/testkit/index.d.mts +9 -5
- package/dist/core/testkit/index.mjs +83 -1
- package/dist/index.d.mts +3 -1
- package/dist/index.mjs +22 -1
- package/dist/runtime/adapter.mjs +82 -1
- package/dist/runtime/auto.mjs +46 -1
- package/dist/runtime/bun.mjs +28 -1
- package/dist/runtime/deno.mjs +217 -2
- package/dist/runtime/detect.mjs +45 -1
- package/dist/runtime/node.mjs +169 -2
- package/dist/runtime/paths.mjs +48 -1
- package/dist/runtime.mjs +7 -1
- package/dist/strings.mjs +22 -1
- package/dist/testkit.mjs +5 -1
- package/dist/version.mjs +7 -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 +23 -41
- package/dist/runtime/support.d.mts +0 -42
- package/dist/runtime/support.mjs +0 -1
- package/src/core/cli/dispatch.ts +0 -349
- package/src/core/cli/help-links.ts +0 -82
- package/src/core/cli/index.ts +0 -1413
- package/src/core/cli/planner.ts +0 -487
- package/src/core/cli/plugin.ts +0 -117
- package/src/core/cli/propagate.ts +0 -97
- package/src/core/cli/root-help.ts +0 -252
- package/src/core/cli/root-surface.ts +0 -74
- package/src/core/cli/runtime-preflight.ts +0 -438
- package/src/core/completion/index.ts +0 -88
- package/src/core/completion/shells/bash.ts +0 -459
- package/src/core/completion/shells/fish.ts +0 -259
- package/src/core/completion/shells/powershell.ts +0 -439
- package/src/core/completion/shells/shared.ts +0 -283
- package/src/core/completion/shells/zsh.ts +0 -381
- package/src/core/config/index.ts +0 -417
- package/src/core/config/package-json.ts +0 -560
- package/src/core/errors/index.ts +0 -193
- package/src/core/execution/index.ts +0 -268
- package/src/core/help/ansi.ts +0 -144
- package/src/core/help/index.ts +0 -516
- package/src/core/json-schema/index.ts +0 -891
- package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
- package/src/core/output/activity.ts +0 -575
- package/src/core/output/bind.ts +0 -59
- package/src/core/output/contracts.ts +0 -194
- package/src/core/output/display-value.ts +0 -48
- package/src/core/output/index.ts +0 -704
- package/src/core/output/renderers.ts +0 -125
- package/src/core/output/writer.ts +0 -46
- package/src/core/parse/index.ts +0 -681
- package/src/core/prompt/index.ts +0 -583
- package/src/core/resolve/args.ts +0 -144
- package/src/core/resolve/coerce.ts +0 -432
- package/src/core/resolve/config.ts +0 -26
- package/src/core/resolve/contracts.ts +0 -135
- package/src/core/resolve/errors.ts +0 -227
- package/src/core/resolve/flags.ts +0 -255
- package/src/core/resolve/index.ts +0 -108
- package/src/core/resolve/property.ts +0 -99
- package/src/core/schema/activity.ts +0 -240
- package/src/core/schema/arg.ts +0 -719
- package/src/core/schema/command.ts +0 -1498
- package/src/core/schema/flag.ts +0 -801
- package/src/core/schema/index.ts +0 -91
- package/src/core/schema/middleware.ts +0 -171
- package/src/core/schema/prompt.ts +0 -156
- package/src/core/schema/run.ts +0 -198
- package/src/core/schema-dsl/index.ts +0 -109
- package/src/core/schema-dsl/parse.ts +0 -262
- package/src/core/schema-dsl/runtime.ts +0 -609
- package/src/core/schema-dsl/to-json-schema.ts +0 -102
- package/src/core/testkit/index.ts +0 -123
- package/src/index.ts +0 -179
- package/src/runtime/adapter.ts +0 -303
- package/src/runtime/auto.ts +0 -110
- package/src/runtime/bun.ts +0 -55
- package/src/runtime/deno.ts +0 -369
- package/src/runtime/detect.ts +0 -105
- package/src/runtime/index.ts +0 -21
- package/src/runtime/node-builtins.d.ts +0 -27
- package/src/runtime/node.ts +0 -300
- package/src/runtime/paths.ts +0 -64
- package/src/runtime/support.ts +0 -135
- package/src/runtime.ts +0 -31
- package/src/strings.ts +0 -34
- package/src/testkit.ts +0 -25
- package/src/version.ts +0 -20
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,156 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [3.0.0-rc.2] - 2026-07-06
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- **`out.color` — context-aware ANSI colors** — every handler's `out` now carries
|
|
15
|
+
a color palette powered by [`ansispeck`](https://github.com/kjanat/ansispeck).
|
|
16
|
+
Colors auto-enable only when stdout is a TTY, JSON mode is off, and the
|
|
17
|
+
environment supports color (`NO_COLOR`, `FORCE_COLOR`, `--no-color`, `--color`,
|
|
18
|
+
`CI` respected); otherwise every formatter is an identity function, so handlers
|
|
19
|
+
can write `out.log(out.color.green('✔ done'))` unconditionally.
|
|
20
|
+
`createOutput({ color })` forces the palette on/off (useful for asserting
|
|
21
|
+
colored output in tests), and the `Colors` type is re-exported from the root
|
|
22
|
+
entrypoint. First runtime dependency — kept external in `dist` (~1 kB gzipped
|
|
23
|
+
install).
|
|
24
|
+
|
|
25
|
+
### Changed
|
|
26
|
+
|
|
27
|
+
- **npm package now resolves built `dist` on every runtime** — the `bun`/`deno`
|
|
28
|
+
→ `src/*.ts` export conditions are gone and `src` is no longer published to
|
|
29
|
+
npm (JSR still ships source). Bun and Deno consumers previously loaded raw
|
|
30
|
+
source where build-time defines never ran, so `version` reported `'dev'`;
|
|
31
|
+
they now get the same tested output as Node, with the real version. The
|
|
32
|
+
export map is generated by tsdown at build time instead of hand-maintained.
|
|
33
|
+
|
|
34
|
+
## [3.0.0-rc.1] - 2026-07-02
|
|
35
|
+
|
|
36
|
+
### Added
|
|
37
|
+
|
|
38
|
+
- **`.completions({ as: 'flag' })`** — expose shell completion as an eager
|
|
39
|
+
`--completions <shell>` flag on the CLI root instead of a `completions`
|
|
40
|
+
subcommand. The planner intercepts the flag before dispatch, prints the script,
|
|
41
|
+
and exits; root help advertises `--completions <bash|zsh|fish|powershell>` in its
|
|
42
|
+
`Flags:` section. `.completions()` still defaults to `{ as: 'command' }`. Because
|
|
43
|
+
the eager flag is intercepted before dispatch, the `--completions` name is
|
|
44
|
+
reserved in flag mode — declaring a command/default flag of that name throws at
|
|
45
|
+
build time.
|
|
46
|
+
- **Shell auto-detection** — `--completions` with no value (flag form) resolves the
|
|
47
|
+
target shell from the environment: `$SHELL` (parsed as an interpreter path) wins
|
|
48
|
+
when it names a supported shell, otherwise the presence of `$PSModulePath` selects
|
|
49
|
+
PowerShell — the reliable signal for `pwsh`, which never sets `$SHELL`.
|
|
50
|
+
- **`detectShell(env)` / `normalizeShell(raw)`** — exported helpers behind the
|
|
51
|
+
detection above; `normalizeShell` accepts bare names, `$SHELL` paths, and the
|
|
52
|
+
`pwsh`/`powershell` pair.
|
|
53
|
+
- **`.help(config)` builder + extended `HelpOptions`** — configure root-help
|
|
54
|
+
rendering: `inlineDefault`, `showDefaultInCommands`, and `footer` (plus the
|
|
55
|
+
existing `width` / `hyperlinks`). Builder config is merged under runtime
|
|
56
|
+
`options.help` (runtime wins).
|
|
57
|
+
- **Numeric constraints for number flags and args** — `flag.number()` and
|
|
58
|
+
`arg.number()` now accept `{ min?, max?, int?, finite? }` (bounds inclusive),
|
|
59
|
+
and the same constraints compose via chained `.int()` / `.min(n)` / `.max(n)` /
|
|
60
|
+
`.finite(allow?)` methods (a later call overrides an earlier value, including
|
|
61
|
+
one set in the options object). The chained methods are compile-time guarded
|
|
62
|
+
to number-kind builders only. Constraints are enforced identically across the
|
|
63
|
+
parse path and the env/config/prompt resolution path (order: finite → int →
|
|
64
|
+
min → max): parse-time (CLI) violations throw `INVALID_VALUE`, while
|
|
65
|
+
env/config/prompt coercion reports `CONSTRAINT_VIOLATED` (both exit code `2`).
|
|
66
|
+
They are also surfaced in the exported JSON Schema as `minimum` / `maximum` and
|
|
67
|
+
`type: "integer"` when `int` is set. `min` / `max` must be finite — a
|
|
68
|
+
non-finite bound (`Infinity` / `-Infinity` / `NaN`) throws at construction. The
|
|
69
|
+
resolved TypeScript value type stays `number`.
|
|
70
|
+
- **Prompt-level defaults for `confirm` and `input` prompts** — `confirm`
|
|
71
|
+
prompts accept `default?: boolean` (drives the `(Y/n)` vs `(y/N)` hint and the
|
|
72
|
+
empty-line result, so a confirm can default to **No**), and `input` prompts
|
|
73
|
+
accept `default?: string` (shown in the hint as `(default: <value>)` and used
|
|
74
|
+
when the user presses Enter, skipping `validate`). Precedence among defaults is
|
|
75
|
+
prompt-level `default` > flag `.default()`. Unset `confirm` default stays
|
|
76
|
+
backward compatible (`true`).
|
|
77
|
+
|
|
78
|
+
### Changed
|
|
79
|
+
|
|
80
|
+
- **BREAKING — the default command is now the root _surface_, not a named
|
|
81
|
+
subcommand.** `.default(cmd)` registers the command only as the default; it is no
|
|
82
|
+
longer added to `schema.commands`. Consequences:
|
|
83
|
+
- It can no longer be invoked by its own name (`mycli mycmd` does not route to it;
|
|
84
|
+
the token is treated as input to the default command).
|
|
85
|
+
- It is omitted from the root `Commands:` list by default (re-enable with
|
|
86
|
+
`.help({ showDefaultInCommands: true })`).
|
|
87
|
+
- Root `--help` renders the default command's `Arguments:`/`Flags:` inline even
|
|
88
|
+
when sibling commands exist (previously only when it was the sole command), and a
|
|
89
|
+
sole default with no subcommands shows its own usage line directly instead of a
|
|
90
|
+
`[command]` placeholder.
|
|
91
|
+
- **`finite` defaults to `true` (behavior change)** — `flag.number()` /
|
|
92
|
+
`arg.number()` now **reject `Infinity` and `-Infinity`**, which previously
|
|
93
|
+
passed straight through to handlers (`Number("Infinity")` is not `NaN`). Pass
|
|
94
|
+
`{ finite: false }` (or `.finite(false)`) to opt back into accepting non-finite
|
|
95
|
+
values. `NaN` continues to be rejected as before.
|
|
96
|
+
- **BREAKING — the runtime no longer hard-fails the host CLI on its version.**
|
|
97
|
+
Adapter construction previously threw (a bare, uncaught `Error`) when the
|
|
98
|
+
detected Node/Bun/Deno version was below DreamCLI's declared minimum, crashing
|
|
99
|
+
the consumer's CLI — including on `--help`. That check is removed: as a
|
|
100
|
+
dependency the consumer's package manager already enforces the `engines` range
|
|
101
|
+
at install time (and more softly), and when DreamCLI is bundled/inlined the
|
|
102
|
+
consumer — not us — owns their CLI's supported-runtime policy. `SUPPORTED_RUNTIMES`
|
|
103
|
+
and the generated `engines` minimums are unchanged and remain the source of
|
|
104
|
+
truth for docs and packaging.
|
|
105
|
+
|
|
106
|
+
### Fixed
|
|
107
|
+
|
|
108
|
+
- **Empty `input`-prompt answer no longer clobbers a flag's `.default()`** — a
|
|
109
|
+
flag declared with both `.default(...)` and an `input` prompt previously
|
|
110
|
+
resolved to `""` when the user submitted an empty line, because empty input was
|
|
111
|
+
treated as a real answer that short-circuited the default fallback. An empty or
|
|
112
|
+
blank `input` answer with no prompt-level `default` is now treated as "no
|
|
113
|
+
answer", so resolution falls through to the flag's `.default()` (or, for a
|
|
114
|
+
required flag, the standard missing-flag error).
|
|
115
|
+
|
|
116
|
+
### Fixed
|
|
117
|
+
|
|
118
|
+
- **Root `--help` now matches consistently with `--version`** (#29) — previously
|
|
119
|
+
`--help` / `-h` were intercepted at the root only when they were the very first
|
|
120
|
+
token, while `--version` / `-V` matched anywhere before `--`. A help flag
|
|
121
|
+
preceded only by flags (e.g. `mycli --verbose --help`) now shows root help,
|
|
122
|
+
mirroring `mycli --verbose --version`. A help flag that follows a subcommand
|
|
123
|
+
token still scopes to that subcommand (`mycli deploy --help` → `deploy` help);
|
|
124
|
+
`--version` remains a global, position-independent flag by design (there is no
|
|
125
|
+
per-command version). The bare `help` token now triggers root help from the same
|
|
126
|
+
position as `--help`, and the `--` end-of-options separator is respected for both.
|
|
127
|
+
- **Generated `--help` now advertises the active built-in global flags** (#32) — root
|
|
128
|
+
help renders a `Global options:` block listing `--help, -h` and `--json` (always),
|
|
129
|
+
`--version, -V` (when a version is set), and `--config <path>` (when `.config()`
|
|
130
|
+
enabled config discovery). Previously these framework-provided flags were invisible
|
|
131
|
+
in help even though they worked. `--completions` is unchanged (still advertised via
|
|
132
|
+
the inline surface when active).
|
|
133
|
+
- **Root usage no longer prints the default command's name** — the merged/sole-default
|
|
134
|
+
usage line rendered `Usage: <bin> <default-name> …`, teaching an invocation that does
|
|
135
|
+
not route (`.default()` is not a named command, so the token is consumed as the
|
|
136
|
+
default's first positional). It now renders under the bin name only
|
|
137
|
+
(`Usage: <bin> [flags] <args>`).
|
|
138
|
+
- **`inlineDefault: false` no longer hides a sole default command's interface** — when
|
|
139
|
+
the default command is the only surface (no visible subcommands and no eager
|
|
140
|
+
`--completions` flag), root help would collapse to a bare `Usage: <bin> [options]`
|
|
141
|
+
with no discoverable args/flags. The default is now always rendered inline in that
|
|
142
|
+
case, since suppressing it leaves no other path to its interface.
|
|
143
|
+
|
|
144
|
+
### Fixed
|
|
145
|
+
|
|
146
|
+
- **`runCommand()` now honors a CLI-level `--json` passed in `argv`** — the testkit
|
|
147
|
+
gained the same root-flag layer as the real CLI: a `--json` before the `--`
|
|
148
|
+
separator enables JSON mode and is stripped before parsing, instead of failing
|
|
149
|
+
with `Unknown flag --json` (exit 2). A literal `--json` after `--` still reaches
|
|
150
|
+
the command unchanged. The existing `{ jsonMode: true }` option keeps working —
|
|
151
|
+
either source enables JSON mode. Copying a real `mycli --json …` invocation into a
|
|
152
|
+
test now works verbatim.
|
|
153
|
+
- **`createTestPrompter()` now runs an `input` prompt's `validate`** — a queued
|
|
154
|
+
string answer to an `input` prompt is validated exactly as the terminal prompter
|
|
155
|
+
does; an answer that fails validation is rejected as a cancellation rather than
|
|
156
|
+
injected verbatim as the resolved value, so prompt validation is integration-testable
|
|
157
|
+
through `runCommand(cmd, argv, { answers })`. Non-string answers stay verbatim so
|
|
158
|
+
downstream coercion paths remain testable.
|
|
159
|
+
|
|
10
160
|
## [2.5.0] - 2026-06-28
|
|
11
161
|
|
|
12
162
|
### Added
|
|
@@ -878,7 +1028,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
878
1028
|
- MIT License.
|
|
879
1029
|
- Markdownlint configuration.
|
|
880
1030
|
|
|
881
|
-
[Unreleased]: https://github.com/kjanat/dreamcli/compare/
|
|
1031
|
+
[Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.2...HEAD
|
|
1032
|
+
[3.0.0-rc.2]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.1...v3.0.0-rc.2
|
|
1033
|
+
[3.0.0-rc.1]: https://github.com/kjanat/dreamcli/compare/v2.5.0...v3.0.0-rc.1
|
|
882
1034
|
[2.5.0]: https://github.com/kjanat/dreamcli/compare/v2.4.1...v2.5.0
|
|
883
1035
|
[2.4.1]: https://github.com/kjanat/dreamcli/compare/v2.4.0...v2.4.1
|
|
884
1036
|
[2.4.0]: https://github.com/kjanat/dreamcli/compare/v2.3.0...v2.4.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,6 +543,9 @@ 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
|
|
@@ -1 +1,214 @@
|
|
|
1
|
-
import{buildFlagLookup
|
|
1
|
+
import { buildFlagLookup, flagExpectsValue } from "../parse/index.mjs";
|
|
2
|
+
//#region src/core/cli/dispatch.ts
|
|
3
|
+
/**
|
|
4
|
+
* Recursive command dispatch for nested command trees.
|
|
5
|
+
*
|
|
6
|
+
* Walks argv segments, matching command names at each level of the tree.
|
|
7
|
+
* Returns a discriminated union describing the dispatch outcome: a matched
|
|
8
|
+
* command with its ancestor path, a group that needs a subcommand, or an
|
|
9
|
+
* unknown command with suggestion candidates.
|
|
10
|
+
*
|
|
11
|
+
* @module dreamcli/core/cli/dispatch
|
|
12
|
+
* @internal
|
|
13
|
+
*/
|
|
14
|
+
/**
|
|
15
|
+
* Recursively walk argv, consuming command name segments from the front.
|
|
16
|
+
*
|
|
17
|
+
* At each level, the first non-flag token is tested as a command name
|
|
18
|
+
* against the provided command map. If matched and the matched command
|
|
19
|
+
* has subcommands, dispatch recurses into the child level with the
|
|
20
|
+
* remaining argv.
|
|
21
|
+
*
|
|
22
|
+
* Ambiguity resolution for commands that have both an action handler AND
|
|
23
|
+
* subcommands (e.g. `git remote` lists remotes, `git remote add` dispatches):
|
|
24
|
+
* - If the next token matches a subcommand → descend
|
|
25
|
+
* - If the next token is unknown and the command has a handler → match here
|
|
26
|
+
* - If the next token is unknown and no handler → propagate unknown error
|
|
27
|
+
* - If no next token and command has a handler → match here
|
|
28
|
+
* - If no next token and no handler → needs-subcommand
|
|
29
|
+
*
|
|
30
|
+
* @param argv - Remaining argv tokens (command names + flags + args).
|
|
31
|
+
* @param commands - Command map at the current tree level.
|
|
32
|
+
* @param ancestorPath - Schema path from root to current level (exclusive).
|
|
33
|
+
* @param valueFlags - Lookup of flags valid at this level, used so a
|
|
34
|
+
* space-separated value-flag's value (`--region eu`) is not mistaken for a
|
|
35
|
+
* command name. Empty by default (arity-unaware, legacy behaviour).
|
|
36
|
+
* @returns Discriminated dispatch result.
|
|
37
|
+
*
|
|
38
|
+
* @internal
|
|
39
|
+
*/
|
|
40
|
+
function dispatch(argv, commands, ancestorPath = [], valueFlags = /* @__PURE__ */ new Map()) {
|
|
41
|
+
let cmdIdx = -1;
|
|
42
|
+
for (let i = 0; i < argv.length; i++) {
|
|
43
|
+
const token = argv[i];
|
|
44
|
+
if (token === void 0) continue;
|
|
45
|
+
if (token === "--") {
|
|
46
|
+
if (i + 1 < argv.length) cmdIdx = i + 1;
|
|
47
|
+
break;
|
|
48
|
+
}
|
|
49
|
+
if (token.startsWith("-")) {
|
|
50
|
+
if (consumesFollowingToken(token, valueFlags)) i++;
|
|
51
|
+
continue;
|
|
52
|
+
}
|
|
53
|
+
cmdIdx = i;
|
|
54
|
+
break;
|
|
55
|
+
}
|
|
56
|
+
if (cmdIdx === -1) return {
|
|
57
|
+
kind: "unknown",
|
|
58
|
+
input: "",
|
|
59
|
+
candidates: uniqueCommands(commands),
|
|
60
|
+
parentPath: ancestorPath
|
|
61
|
+
};
|
|
62
|
+
const cmdName = argv[cmdIdx];
|
|
63
|
+
if (cmdName === void 0) return {
|
|
64
|
+
kind: "unknown",
|
|
65
|
+
input: "",
|
|
66
|
+
candidates: uniqueCommands(commands),
|
|
67
|
+
parentPath: ancestorPath
|
|
68
|
+
};
|
|
69
|
+
const matched = commands.get(cmdName);
|
|
70
|
+
if (matched === void 0) return {
|
|
71
|
+
kind: "unknown",
|
|
72
|
+
input: cmdName,
|
|
73
|
+
candidates: uniqueCommands(commands),
|
|
74
|
+
parentPath: ancestorPath
|
|
75
|
+
};
|
|
76
|
+
const remaining = [...argv.slice(0, cmdIdx), ...argv.slice(cmdIdx + 1)];
|
|
77
|
+
const currentPath = [...ancestorPath, matched.schema];
|
|
78
|
+
if (matched.subcommands.size > 0) {
|
|
79
|
+
const subResult = dispatch(remaining, matched.subcommands, currentPath, buildFlagLookup(matched.schema.flags));
|
|
80
|
+
switch (subResult.kind) {
|
|
81
|
+
case "match": return subResult;
|
|
82
|
+
case "unknown":
|
|
83
|
+
if (subResult.input === "") {
|
|
84
|
+
if (matched.schema.hasAction) return {
|
|
85
|
+
kind: "match",
|
|
86
|
+
command: matched,
|
|
87
|
+
commandPath: currentPath,
|
|
88
|
+
remainingArgv: remaining
|
|
89
|
+
};
|
|
90
|
+
return {
|
|
91
|
+
kind: "needs-subcommand",
|
|
92
|
+
command: matched,
|
|
93
|
+
commandPath: currentPath
|
|
94
|
+
};
|
|
95
|
+
}
|
|
96
|
+
if (matched.schema.hasAction) return {
|
|
97
|
+
kind: "match",
|
|
98
|
+
command: matched,
|
|
99
|
+
commandPath: currentPath,
|
|
100
|
+
remainingArgv: remaining
|
|
101
|
+
};
|
|
102
|
+
return subResult;
|
|
103
|
+
case "needs-subcommand": return subResult;
|
|
104
|
+
default: return subResult;
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
return {
|
|
108
|
+
kind: "match",
|
|
109
|
+
command: matched,
|
|
110
|
+
commandPath: currentPath,
|
|
111
|
+
remainingArgv: remaining
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Whether a flag token consumes the following argv token as its value.
|
|
116
|
+
*
|
|
117
|
+
* Mirrors the parser's value-consumption rules (`parseLongFlag` /
|
|
118
|
+
* `parseShortFlags`) so the command-name scan skips exactly the tokens the
|
|
119
|
+
* parser would treat as flag values:
|
|
120
|
+
* - `--flag value` → consumes when `--flag` is a known value-flag.
|
|
121
|
+
* - `--flag=value` → self-contained, consumes nothing.
|
|
122
|
+
* - `-abc value` → consumes only when the trailing short flag is a value-flag;
|
|
123
|
+
* an earlier value-flag char takes the rest of the group as an inline value.
|
|
124
|
+
*
|
|
125
|
+
* Unknown flags conservatively consume nothing (the parser reports them later).
|
|
126
|
+
*
|
|
127
|
+
* @internal
|
|
128
|
+
*/
|
|
129
|
+
function consumesFollowingToken(token, valueFlags) {
|
|
130
|
+
if (token.startsWith("--")) {
|
|
131
|
+
if (token.includes("=")) return false;
|
|
132
|
+
const entry = valueFlags.get(token.slice(2));
|
|
133
|
+
return entry !== void 0 && flagExpectsValue(entry[1]);
|
|
134
|
+
}
|
|
135
|
+
const chars = token.slice(1);
|
|
136
|
+
for (let i = 0; i < chars.length; i++) {
|
|
137
|
+
const entry = valueFlags.get(chars.charAt(i));
|
|
138
|
+
if (entry === void 0) return false;
|
|
139
|
+
if (!flagExpectsValue(entry[1])) continue;
|
|
140
|
+
return i === chars.length - 1;
|
|
141
|
+
}
|
|
142
|
+
return false;
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* Levenshtein distance between two strings.
|
|
146
|
+
* @internal
|
|
147
|
+
*/
|
|
148
|
+
function levenshtein(a, b) {
|
|
149
|
+
const m = a.length;
|
|
150
|
+
const n = b.length;
|
|
151
|
+
const w = n + 1;
|
|
152
|
+
let prev = new Uint16Array(w);
|
|
153
|
+
let curr = new Uint16Array(w);
|
|
154
|
+
for (let j = 0; j <= n; j++) prev[j] = j;
|
|
155
|
+
for (let i = 1; i <= m; i++) {
|
|
156
|
+
curr[0] = i;
|
|
157
|
+
for (let j = 1; j <= n; j++) {
|
|
158
|
+
const cost = a.charAt(i - 1) === b.charAt(j - 1) ? 0 : 1;
|
|
159
|
+
const del = prev[j] ?? 0;
|
|
160
|
+
const ins = curr[j - 1] ?? 0;
|
|
161
|
+
const sub = prev[j - 1] ?? 0;
|
|
162
|
+
curr[j] = Math.min(del + 1, ins + 1, sub + cost);
|
|
163
|
+
}
|
|
164
|
+
[prev, curr] = [curr, prev];
|
|
165
|
+
}
|
|
166
|
+
return prev[n] ?? Math.max(m, n);
|
|
167
|
+
}
|
|
168
|
+
/**
|
|
169
|
+
* Find the closest command name match for a "did you mean?" suggestion.
|
|
170
|
+
*
|
|
171
|
+
* Searches command names and aliases. Returns `undefined` if no
|
|
172
|
+
* sufficiently close match exists (threshold: 3).
|
|
173
|
+
*
|
|
174
|
+
* @internal
|
|
175
|
+
*/
|
|
176
|
+
function findClosestCommand(input, commands) {
|
|
177
|
+
const MAX_DISTANCE = 3;
|
|
178
|
+
let bestName;
|
|
179
|
+
let bestDist = 4;
|
|
180
|
+
for (const cmd of commands) {
|
|
181
|
+
const nameDist = levenshtein(input, cmd.schema.name);
|
|
182
|
+
if (nameDist < bestDist) {
|
|
183
|
+
bestDist = nameDist;
|
|
184
|
+
bestName = cmd.schema.name;
|
|
185
|
+
}
|
|
186
|
+
for (const alias of cmd.schema.aliases) {
|
|
187
|
+
const aliasDist = levenshtein(input, alias);
|
|
188
|
+
if (aliasDist < bestDist) {
|
|
189
|
+
bestDist = aliasDist;
|
|
190
|
+
bestName = cmd.schema.name;
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
return bestDist <= MAX_DISTANCE ? bestName : void 0;
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* Deduplicate commands from a name+alias map.
|
|
198
|
+
*
|
|
199
|
+
* A map keyed by name *and* alias contains duplicate entries for aliased
|
|
200
|
+
* commands. This returns unique commands (by schema identity).
|
|
201
|
+
*
|
|
202
|
+
* @internal
|
|
203
|
+
*/
|
|
204
|
+
function uniqueCommands(commands) {
|
|
205
|
+
const seen = /* @__PURE__ */ new Set();
|
|
206
|
+
const result = [];
|
|
207
|
+
for (const cmd of commands.values()) if (!seen.has(cmd)) {
|
|
208
|
+
seen.add(cmd);
|
|
209
|
+
result.push(cmd);
|
|
210
|
+
}
|
|
211
|
+
return result;
|
|
212
|
+
}
|
|
213
|
+
//#endregion
|
|
214
|
+
export { dispatch, findClosestCommand };
|
|
@@ -1 +1,41 @@
|
|
|
1
|
-
import{packageRepositoryUrl
|
|
1
|
+
import { packageRepositoryUrl } from "../config/package-json.mjs";
|
|
2
|
+
//#region src/core/cli/help-links.ts
|
|
3
|
+
/**
|
|
4
|
+
* Build the release-tag URL for a version on a known forge.
|
|
5
|
+
*
|
|
6
|
+
* GitHub and GitLab have stable release-tag routes; other hosts return
|
|
7
|
+
* `undefined` rather than guessing.
|
|
8
|
+
*
|
|
9
|
+
* @internal
|
|
10
|
+
*/
|
|
11
|
+
function releaseTagUrl(repoUrl, version) {
|
|
12
|
+
let hostname;
|
|
13
|
+
try {
|
|
14
|
+
hostname = new URL(repoUrl).hostname;
|
|
15
|
+
} catch {
|
|
16
|
+
return;
|
|
17
|
+
}
|
|
18
|
+
if (hostname === "github.com") return `${repoUrl}/releases/tag/v${version}`;
|
|
19
|
+
if (hostname === "gitlab.com") return `${repoUrl}/-/releases/v${version}`;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Fill `undefined` link fields from package.json metadata.
|
|
23
|
+
*
|
|
24
|
+
* Explicit URLs always win. The name falls back to the normalized
|
|
25
|
+
* `repository` URL, then `homepage`; the version falls back to the forge
|
|
26
|
+
* release-tag URL when both a repository and a version are known.
|
|
27
|
+
* Idempotent — already-resolved fields pass through unchanged.
|
|
28
|
+
*
|
|
29
|
+
* @internal
|
|
30
|
+
*/
|
|
31
|
+
function deriveHelpLinks(links, pkg, version) {
|
|
32
|
+
if (links === void 0) return void 0;
|
|
33
|
+
if (pkg === void 0 || links.name !== void 0 && links.version !== void 0) return links;
|
|
34
|
+
const repoUrl = packageRepositoryUrl(pkg);
|
|
35
|
+
return {
|
|
36
|
+
name: links.name ?? repoUrl ?? pkg.homepage,
|
|
37
|
+
version: links.version ?? (repoUrl !== void 0 && version !== void 0 ? releaseTagUrl(repoUrl, version) : void 0)
|
|
38
|
+
};
|
|
39
|
+
}
|
|
40
|
+
//#endregion
|
|
41
|
+
export { deriveHelpLinks };
|
|
@@ -7,6 +7,7 @@ import { RuntimeAdapter } from "../../runtime/adapter.mjs";
|
|
|
7
7
|
import { PackageJsonData } from "../config/package-json.mjs";
|
|
8
8
|
import { HelpLinks } from "./help-links.mjs";
|
|
9
9
|
import { CompletionOptions } from "../completion/shells/shared.mjs";
|
|
10
|
+
import { Shell } from "../completion/index.mjs";
|
|
10
11
|
import { FormatLoader } from "../config/index.mjs";
|
|
11
12
|
import { formatRootHelp } from "./root-help.mjs";
|
|
12
13
|
|
|
@@ -69,11 +70,73 @@ interface CLISchema {
|
|
|
69
70
|
* CLIBuilder.manifest | .manifest()}) is active.
|
|
70
71
|
*/
|
|
71
72
|
readonly helpLinks: HelpLinks | undefined;
|
|
72
|
-
/** Whether built-in `.completions()` command
|
|
73
|
+
/** Whether built-in `.completions()` registration (command or flag) is active. */
|
|
73
74
|
readonly hasBuiltInCompletions: boolean;
|
|
75
|
+
/**
|
|
76
|
+
* Eager `--completions <shell>` flag configuration.
|
|
77
|
+
*
|
|
78
|
+
* Set when `.completions({ as: 'flag' })` is used instead of the default
|
|
79
|
+
* `completions` subcommand. When defined, the planner intercepts
|
|
80
|
+
* `--completions <shell>` before dispatch, prints the script, and exits;
|
|
81
|
+
* root help advertises the flag in its `Flags:` section.
|
|
82
|
+
*/
|
|
83
|
+
readonly completionsFlag: CompletionsFlagConfig | undefined;
|
|
84
|
+
/**
|
|
85
|
+
* Consumer-configured root-help defaults.
|
|
86
|
+
*
|
|
87
|
+
* Set via the {@linkcode CLIBuilder.help | .help()} builder method and merged
|
|
88
|
+
* under runtime `options.help` (runtime wins) before rendering.
|
|
89
|
+
*/
|
|
90
|
+
readonly helpConfig: HelpConfig | undefined;
|
|
74
91
|
/** Registered CLI plugins. */
|
|
75
92
|
readonly plugins: readonly CLIPlugin[];
|
|
76
93
|
}
|
|
94
|
+
/**
|
|
95
|
+
* Configuration for the eager `--completions <shell>` flag.
|
|
96
|
+
*
|
|
97
|
+
* Stored in {@link CLISchema} when `.completions({ as: 'flag' })` is used.
|
|
98
|
+
*
|
|
99
|
+
* @internal
|
|
100
|
+
*/
|
|
101
|
+
interface CompletionsFlagConfig {
|
|
102
|
+
/** Shell targets the flag accepts (mirrors {@link SHELLS}). */
|
|
103
|
+
readonly shells: readonly Shell[];
|
|
104
|
+
/** Generator options captured at build time (e.g. `functionPrefix`, `rootMode`). */
|
|
105
|
+
readonly options: CompletionOptions | undefined;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* Consumer-facing root-help configuration set via {@linkcode CLIBuilder.help}.
|
|
109
|
+
*
|
|
110
|
+
* Every field is optional; unset fields fall back to built-in defaults and may
|
|
111
|
+
* be overridden per call through runtime `options.help`.
|
|
112
|
+
*/
|
|
113
|
+
interface HelpConfig {
|
|
114
|
+
/**
|
|
115
|
+
* Render the default command's arguments and flags inline at the root.
|
|
116
|
+
*
|
|
117
|
+
* @defaultValue `true`
|
|
118
|
+
*/
|
|
119
|
+
readonly inlineDefault?: boolean;
|
|
120
|
+
/**
|
|
121
|
+
* Also list the default command in the root `Commands:` table.
|
|
122
|
+
*
|
|
123
|
+
* By default the default command is the root surface and is omitted from the
|
|
124
|
+
* command list (its args/flags render inline instead).
|
|
125
|
+
*
|
|
126
|
+
* @defaultValue `false`
|
|
127
|
+
*/
|
|
128
|
+
readonly showDefaultInCommands?: boolean;
|
|
129
|
+
/**
|
|
130
|
+
* Show the `Run '<bin> <command> --help' for more information.` hint.
|
|
131
|
+
*
|
|
132
|
+
* Defaults to showing the hint only when visible subcommands exist.
|
|
133
|
+
*/
|
|
134
|
+
readonly footer?: boolean;
|
|
135
|
+
/** Maximum line width (columns). */
|
|
136
|
+
readonly width?: number;
|
|
137
|
+
/** Emit OSC 8 hyperlinks in the header when supported. */
|
|
138
|
+
readonly hyperlinks?: boolean;
|
|
139
|
+
}
|
|
77
140
|
/**
|
|
78
141
|
* Config discovery settings for automatic config file loading.
|
|
79
142
|
*
|
|
@@ -266,6 +329,25 @@ declare class CLIBuilder {
|
|
|
266
329
|
readonly name?: string | URL;
|
|
267
330
|
readonly version?: string | URL;
|
|
268
331
|
}): CLIBuilder;
|
|
332
|
+
/**
|
|
333
|
+
* Configure root-help rendering defaults.
|
|
334
|
+
*
|
|
335
|
+
* Stored on the schema and merged **under** any runtime `options.help`
|
|
336
|
+
* (runtime wins). Call multiple times to set fields incrementally.
|
|
337
|
+
*
|
|
338
|
+
* @param config - Help rendering options (see {@link HelpConfig}).
|
|
339
|
+
* @returns The builder (for chaining).
|
|
340
|
+
*
|
|
341
|
+
* @example
|
|
342
|
+
* ```ts
|
|
343
|
+
* // Echo the default command under Commands and never show the footer:
|
|
344
|
+
* cli('mycli')
|
|
345
|
+
* .help({ showDefaultInCommands: true, footer: false })
|
|
346
|
+
* .default(serve)
|
|
347
|
+
* .run();
|
|
348
|
+
* ```
|
|
349
|
+
*/
|
|
350
|
+
help(config: HelpConfig): CLIBuilder;
|
|
269
351
|
/**
|
|
270
352
|
* Enable automatic config file discovery.
|
|
271
353
|
*
|
|
@@ -460,8 +542,11 @@ declare class CLIBuilder {
|
|
|
460
542
|
* dispatch normally, but empty argv or flags-only argv falls through to
|
|
461
543
|
* this command instead of showing root help.
|
|
462
544
|
*
|
|
463
|
-
* The command is
|
|
464
|
-
*
|
|
545
|
+
* The default command is the CLI's root *surface*: its flags and arguments
|
|
546
|
+
* are rendered inline in root help. It is **not** a named subcommand — it
|
|
547
|
+
* cannot be invoked by its own name (`mycli mycmd` does not route to it) and
|
|
548
|
+
* it is omitted from the root `Commands:` list by default (re-enable with
|
|
549
|
+
* `.help({ showDefaultInCommands: true })`). Only one default is allowed.
|
|
465
550
|
*
|
|
466
551
|
* @example
|
|
467
552
|
* ```ts
|
|
@@ -496,28 +581,36 @@ declare class CLIBuilder {
|
|
|
496
581
|
*/
|
|
497
582
|
plugin(definition: CLIPlugin): CLIBuilder;
|
|
498
583
|
/**
|
|
499
|
-
* Register
|
|
500
|
-
* completion scripts.
|
|
584
|
+
* Register built-in shell completion.
|
|
501
585
|
*
|
|
502
|
-
*
|
|
503
|
-
*
|
|
504
|
-
*
|
|
505
|
-
*
|
|
586
|
+
* By default (`{ as: 'command' }`) this registers a `completions` subcommand
|
|
587
|
+
* that accepts a `shell` argument and writes the script to stdout. With
|
|
588
|
+
* `{ as: 'flag' }` it instead exposes an eager `--completions <shell>` flag on
|
|
589
|
+
* the CLI root — no subcommand is registered, so a default command stays the
|
|
590
|
+
* lone root surface. The flag may be given without a value to auto-detect the
|
|
591
|
+
* shell from `$SHELL` / `$PSModulePath`.
|
|
506
592
|
*
|
|
507
|
-
*
|
|
508
|
-
* script includes the full command set
|
|
509
|
-
*
|
|
510
|
-
* will not appear in
|
|
511
|
-
*
|
|
593
|
+
* In subcommand mode, call this **after** registering all other commands so
|
|
594
|
+
* the completion script includes the full command set: that path snapshots the
|
|
595
|
+
* schema (and completion options) at call time, so commands registered
|
|
596
|
+
* afterwards will not appear in that subcommand's generated script. In flag
|
|
597
|
+
* mode, generation runs at execution time from the final builder schema, so
|
|
598
|
+
* registration order does not matter.
|
|
512
599
|
*
|
|
513
600
|
* @example
|
|
514
601
|
* ```ts
|
|
602
|
+
* // Subcommand form (default):
|
|
515
603
|
* cli('mycli')
|
|
516
604
|
* .version('1.0.0')
|
|
517
605
|
* .command(deploy)
|
|
518
|
-
* .command(login)
|
|
519
606
|
* .completions({ rootMode: 'surface' })
|
|
520
607
|
* .run();
|
|
608
|
+
*
|
|
609
|
+
* // Eager-flag form, ideal for single-command CLIs:
|
|
610
|
+
* cli('mycli')
|
|
611
|
+
* .completions({ as: 'flag' })
|
|
612
|
+
* .default(serve)
|
|
613
|
+
* .run();
|
|
521
614
|
* ```
|
|
522
615
|
*/
|
|
523
616
|
completions(options?: CompletionOptions): CLIBuilder;
|
|
@@ -637,4 +730,4 @@ declare function cli(name: string): CLIBuilder;
|
|
|
637
730
|
/** Create a new CLI program builder from an options object. */
|
|
638
731
|
declare function cli(options: CLIOptions): CLIBuilder;
|
|
639
732
|
//#endregion
|
|
640
|
-
export { type BeforeParseParams, CLIBuilder, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type ConfigSettings, type HelpLinks, type InferNameOption, type ManifestPresetSettings, type ManifestSettings, type PackageJsonSettings, type PluginCommandContext, type ResolvedCommandParams, type ResolvedManifestSettings, cli, formatRootHelp, plugin };
|
|
733
|
+
export { type BeforeParseParams, CLIBuilder, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type CompletionsFlagConfig, type ConfigSettings, type HelpConfig, type HelpLinks, type InferNameOption, type ManifestPresetSettings, type ManifestSettings, type PackageJsonSettings, type PluginCommandContext, type ResolvedCommandParams, type ResolvedManifestSettings, cli, formatRootHelp, plugin };
|