@kjanat/dreamcli 2.5.0 → 3.0.0-rc.10
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 +344 -1
- package/README.md +9 -2
- package/dist/core/cli/dispatch.d.mts +6 -5
- package/dist/core/cli/dispatch.mjs +205 -1
- package/dist/core/cli/help-links.d.mts +0 -1
- package/dist/core/cli/help-links.mjs +41 -1
- package/dist/core/cli/index.d.mts +185 -19
- package/dist/core/cli/index.mjs +945 -1
- package/dist/core/cli/planner.d.mts +32 -6
- package/dist/core/cli/planner.mjs +300 -1
- package/dist/core/cli/plugin.d.mts +1 -1
- package/dist/core/cli/plugin.mjs +41 -1
- package/dist/core/cli/propagate.d.mts +1 -1
- package/dist/core/cli/propagate.mjs +57 -1
- package/dist/core/cli/root-help.d.mts +18 -3
- package/dist/core/cli/root-help.mjs +226 -6
- package/dist/core/cli/root-surface.d.mts +30 -4
- package/dist/core/cli/root-surface.mjs +28 -1
- package/dist/core/cli/runtime-preflight.d.mts +30 -3
- package/dist/core/cli/runtime-preflight.mjs +169 -1
- package/dist/core/completion/index.d.mts +32 -2
- package/dist/core/completion/index.mjs +90 -1
- package/dist/core/completion/shells/bash.d.mts +0 -1
- package/dist/core/completion/shells/bash.mjs +308 -3
- package/dist/core/completion/shells/fish.d.mts +0 -1
- package/dist/core/completion/shells/fish.mjs +162 -2
- package/dist/core/completion/shells/powershell.d.mts +0 -1
- package/dist/core/completion/shells/powershell.mjs +358 -2
- package/dist/core/completion/shells/shared.d.mts +23 -2
- package/dist/core/completion/shells/shared.mjs +176 -1
- package/dist/core/completion/shells/zsh.d.mts +0 -1
- package/dist/core/completion/shells/zsh.mjs +251 -2
- package/dist/core/config/index.d.mts +2 -3
- package/dist/core/config/index.mjs +246 -1
- package/dist/core/config/package-json.d.mts +27 -4
- package/dist/core/config/package-json.mjs +386 -3
- package/dist/core/errors/index.d.mts +3 -3
- package/dist/core/errors/index.mjs +87 -1
- package/dist/core/execution/index.d.mts +0 -1
- package/dist/core/execution/index.mjs +201 -1
- package/dist/core/help/ansi.d.mts +11 -5
- package/dist/core/help/ansi.mjs +121 -2
- package/dist/core/help/index.d.mts +65 -2
- package/dist/core/help/index.mjs +341 -7
- package/dist/core/help/theme.d.mts +68 -0
- package/dist/core/help/theme.mjs +46 -0
- package/dist/core/json-schema/index.d.mts +15 -2
- package/dist/core/json-schema/index.mjs +536 -12
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
- package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
- package/dist/core/output/activity.d.mts +0 -1
- package/dist/core/output/activity.mjs +452 -1
- package/dist/core/output/bind.mjs +56 -1
- package/dist/core/output/contracts.d.mts +4 -5
- 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 -1
- package/dist/core/output/index.mjs +442 -2
- package/dist/core/output/renderers.d.mts +0 -1
- package/dist/core/output/renderers.mjs +46 -1
- package/dist/core/output/writer.mjs +12 -1
- package/dist/core/parse/index.d.mts +54 -7
- package/dist/core/parse/index.mjs +727 -1
- package/dist/core/prompt/index.d.mts +12 -4
- package/dist/core/prompt/index.mjs +348 -6
- package/dist/core/resolve/args.d.mts +1 -1
- package/dist/core/resolve/args.mjs +105 -1
- package/dist/core/resolve/coerce.d.mts +1 -1
- package/dist/core/resolve/coerce.mjs +336 -1
- package/dist/core/resolve/config.mjs +19 -1
- package/dist/core/resolve/contracts.d.mts +9 -4
- package/dist/core/resolve/errors.d.mts +0 -1
- package/dist/core/resolve/errors.mjs +140 -2
- package/dist/core/resolve/flags.d.mts +7 -2
- package/dist/core/resolve/flags.mjs +251 -1
- package/dist/core/resolve/index.d.mts +2 -2
- package/dist/core/resolve/index.mjs +85 -1
- package/dist/core/resolve/property.d.mts +6 -2
- package/dist/core/resolve/property.mjs +53 -1
- package/dist/core/schema/activity.d.mts +31 -11
- package/dist/core/schema/arg.d.mts +92 -13
- package/dist/core/schema/arg.mjs +463 -1
- package/dist/core/schema/command.d.mts +29 -7
- package/dist/core/schema/command.mjs +726 -1
- package/dist/core/schema/flag.d.mts +577 -21
- package/dist/core/schema/flag.mjs +705 -1
- package/dist/core/schema/index.d.mts +5 -2
- package/dist/core/schema/middleware.d.mts +4 -3
- 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 +21 -3
- package/dist/core/schema/run.d.mts +24 -5
- package/dist/core/schema/string-constraints.d.mts +97 -0
- package/dist/core/schema/string-constraints.mjs +69 -0
- package/dist/core/schema/value-parsers.d.mts +78 -0
- package/dist/core/schema/value-parsers.mjs +142 -0
- package/dist/core/schema-dsl/runtime.mjs +271 -2
- package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
- package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
- package/dist/core/testkit/index.d.mts +9 -36
- package/dist/core/testkit/index.mjs +83 -1
- package/dist/index.d.mts +12 -6
- package/dist/index.mjs +22 -1
- package/dist/runtime/adapter.d.mts +38 -2
- package/dist/runtime/adapter.mjs +87 -1
- package/dist/runtime/auto.d.mts +2 -3
- package/dist/runtime/auto.mjs +45 -1
- package/dist/runtime/deno.d.mts +24 -5
- package/dist/runtime/deno.mjs +262 -2
- package/dist/runtime/detect.mjs +45 -1
- package/dist/runtime/index.d.mts +3 -4
- package/dist/runtime/node.d.mts +8 -2
- package/dist/runtime/node.mjs +220 -2
- package/dist/runtime/paths.mjs +48 -1
- package/dist/runtime.d.mts +4 -4
- package/dist/runtime.mjs +6 -1
- package/dist/strings.mjs +22 -1
- package/dist/testkit.d.mts +1 -0
- package/dist/testkit.mjs +5 -1
- package/dist/version.d.mts +7 -3
- package/dist/version.mjs +7 -1
- package/dreamcli.schema.json +36 -7
- 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 +43 -49
- package/dist/runtime/bun.d.mts +0 -28
- package/dist/runtime/bun.mjs +0 -1
- 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,339 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [3.0.0-rc.10] - 2026-07-15
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
- **`osc8()` link text is optional** — it now defaults to the link target, so
|
|
15
|
+
`osc8('https://x.dev')` renders as a hyperlink displaying its own URL.
|
|
16
|
+
Terminals without OSC 8 support still show a usable address. Passing an
|
|
17
|
+
explicit label is unchanged.
|
|
18
|
+
- **`osc8()` now delegates to `ansispeck`'s hyperlink constructor** — it emits
|
|
19
|
+
the **ST** (`ESC \`) terminator instead of **BEL** (`\x07`). Both are valid
|
|
20
|
+
OSC 8 terminators supported by modern terminals; the rendered link is
|
|
21
|
+
unchanged. This removes dreamcli's last hand-rolled escape-sequence code.
|
|
22
|
+
|
|
23
|
+
## [3.0.0-rc.9] - 2026-07-11
|
|
24
|
+
|
|
25
|
+
### Added
|
|
26
|
+
|
|
27
|
+
- **JSON help** — `--help` with `--json` emits the CLI's definition document
|
|
28
|
+
(the `generateSchema()` shape, `$schema`-tagged) on stdout instead of help
|
|
29
|
+
text, for root help, `help <command>`, and `<command> --help` alike. New
|
|
30
|
+
`generateCommandSchema(schema)` export produces the per-command document.
|
|
31
|
+
|
|
32
|
+
### Changed
|
|
33
|
+
|
|
34
|
+
- **`generateSchema()` emits the default command's full definition** — the
|
|
35
|
+
`defaultCommand` field was a name-only string reference while the default
|
|
36
|
+
command's flags/args appeared nowhere in the document (it never lists in
|
|
37
|
+
`commands`). It is now the complete serialized command.
|
|
38
|
+
|
|
39
|
+
- **`flag.array()` rejects non-element builders at compile time** — the
|
|
40
|
+
element position now requires a builder carrying only value-shape settings
|
|
41
|
+
(kind, constraints, enum values, `parseFn`). Flag-level modifiers
|
|
42
|
+
(`.alias()`, `.env()`, `.default()`, `.prompt()`, `.describe()`, …) were
|
|
43
|
+
silently ignored on elements before; passing them is now a type error, as
|
|
44
|
+
is `flag.path()` / `flag.count()` / `flag.keyValue()` / nested arrays.
|
|
45
|
+
Type-level only — no runtime behavior change.
|
|
46
|
+
|
|
47
|
+
## [3.0.0-rc.8] - 2026-07-11
|
|
48
|
+
|
|
49
|
+
### Added
|
|
50
|
+
|
|
51
|
+
- **Themed help output** — root and per-command help render with a semantic
|
|
52
|
+
color theme (bold+underlined section titles, cyan literals, dimmed metadata,
|
|
53
|
+
yellow deprecations) whenever color is enabled, using the same gate as
|
|
54
|
+
`out.color` (TTY + color support, no `--json`, `NO_COLOR`/`FORCE_COLOR`
|
|
55
|
+
honored). Piped and JSON output stays byte-clean. Customize via
|
|
56
|
+
`.help({ theme: (c) => ({ sectionTitle: c.magenta }) })` — the factory
|
|
57
|
+
receives the gated ansispeck palette and is never invoked when color is off,
|
|
58
|
+
so custom themes cannot leak escapes. New public types: `HelpTheme`,
|
|
59
|
+
`HelpThemeFactory`.
|
|
60
|
+
- **Negatable booleans** — `flag.boolean().negatable()` accepts `--no-<name>`
|
|
61
|
+
as `false`. Both spellings are one logical flag (last CLI occurrence wins,
|
|
62
|
+
shared duplicate policy); the negated spelling is presence-only
|
|
63
|
+
(`--no-foo=x` errors) and renders as `--[no-]foo` in help. Custom spelling
|
|
64
|
+
via `{ alias }`, unadvertised via `{ hidden }`. Env/config/prompt/default
|
|
65
|
+
resolution is unchanged.
|
|
66
|
+
- **Duplicate policy** — `.duplicates('last' | 'first' | 'error')` on
|
|
67
|
+
singleton flags controls repeated CLI occurrences. `'error'` throws
|
|
68
|
+
`ParseError` code `DUPLICATE_FLAG` with `{ flag, count, values }` details;
|
|
69
|
+
`'first'` keeps the first value while still consuming later value tokens.
|
|
70
|
+
Counted per logical flag (aliases + negated + parity spellings); env/config
|
|
71
|
+
precedence is never a duplicate.
|
|
72
|
+
- **`packageRepositoryUrl(pkg, { require: true })`** — narrows the return
|
|
73
|
+
type to `string`, throwing a `CLIError` (code `INVALID_REPOSITORY`) at the
|
|
74
|
+
call site when the `repository` field is missing or not a recognisable
|
|
75
|
+
locator. Removes the `!` assertion for manifests known to carry a valid
|
|
76
|
+
repository, with the guarantee enforced at runtime rather than assumed.
|
|
77
|
+
- **Flag spelling parity (kebab ↔ camel)** — `--doThis` matches a flag named
|
|
78
|
+
`do-this` and vice versa, for names and long aliases, on by default.
|
|
79
|
+
Handler keys, help, completions, and suggestions stay canonical.
|
|
80
|
+
Automatically disabled per pair when both spellings are declared explicitly;
|
|
81
|
+
globally via `cli('mycli', { flags: { caseParity: false } })` (new
|
|
82
|
+
`cli(name, options)` overload) or `RunOptions.flags`.
|
|
83
|
+
|
|
84
|
+
### Fixed
|
|
85
|
+
|
|
86
|
+
- `execute(argv, { flags })` overrides now reach the planner's dispatch arity
|
|
87
|
+
scanning, not just command parsing.
|
|
88
|
+
- Generated meta-schema descriptions render `@defaultValue` tags as a
|
|
89
|
+
`Default: <value>` paragraph instead of silently dropping them.
|
|
90
|
+
|
|
91
|
+
## [3.0.0-rc.7] - 2026-07-10
|
|
92
|
+
|
|
93
|
+
### Added
|
|
94
|
+
|
|
95
|
+
- **`.derive()` handlers may omit the return** — a validation-only derive with
|
|
96
|
+
no `return` statement (sync or async) now typechecks; previously `void` /
|
|
97
|
+
`Promise<void>` failed the `Output` constraint and forced an explicit
|
|
98
|
+
`return undefined`.
|
|
99
|
+
- **String constraints** — `flag.string({ nonEmpty, minLength, maxLength, pattern })`
|
|
100
|
+
plus chained `.nonEmpty()` / `.minLength()` / `.maxLength()` / `.pattern()`,
|
|
101
|
+
mirroring the numeric-constraint model. Checked in fixed order
|
|
102
|
+
(nonEmpty → minLength → maxLength → pattern) at both the CLI parse boundary
|
|
103
|
+
(`INVALID_VALUE`) and env/config/prompt resolution (`CONSTRAINT_VIOLATED`),
|
|
104
|
+
and emitted into the exported JSON Schema as `minLength` / `maxLength` /
|
|
105
|
+
`pattern`.
|
|
106
|
+
- **`.separator()` and `.unique()` on array flags** — `.separator(',')` splits
|
|
107
|
+
each CLI occurrence before element coercion, so `--region us,eu --region ap`
|
|
108
|
+
works alongside repetition and errors name the offending element. Env/config
|
|
109
|
+
string values use the same separator (default remains `','`). `.unique()`
|
|
110
|
+
deduplicates the final resolved array (first-seen order) regardless of
|
|
111
|
+
source.
|
|
112
|
+
- **`flag.url()`** — parses into a `URL`, with optional
|
|
113
|
+
`{ protocols: ['https'] }` allowlist. Help shows `<url>`.
|
|
114
|
+
- **`flag.path()`** — path string with opt-in filesystem checks
|
|
115
|
+
(`{ mustExist: true }`, `{ type: 'file' | 'directory' }`) validated after
|
|
116
|
+
resolution through the runtime adapter, so CLI/env/config values are checked
|
|
117
|
+
identically. `RuntimeAdapter` gained a `stat()` primitive (Node/Bun via
|
|
118
|
+
`node:fs/promises`, Deno via `Deno.stat`; test adapters default to "nothing
|
|
119
|
+
exists"), and `RunOptions` / `ResolveOptions` accept a `stat` injection for
|
|
120
|
+
process-free execution — without one, checks are skipped.
|
|
121
|
+
- **`flag.date()`** — strict ISO-8601 → `Date` with optional inclusive
|
|
122
|
+
`min` / `max` bounds. Rejects lenient `Date.parse` inputs (`'0'`,
|
|
123
|
+
`'March 5'`) and calendar-invalid dates (`2026-02-31`).
|
|
124
|
+
- **`flag.duration()`** — `'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`,
|
|
125
|
+
compounds (`'1h30m'`), or bare milliseconds → milliseconds.
|
|
126
|
+
- **`flag.bytes()`** — `'512mb'`, `'1.5gb'`, `'64kb'` or bare bytes → bytes
|
|
127
|
+
(binary units, case-insensitive).
|
|
128
|
+
- **`flag.count()`** — occurrence counter (`-vvv` → `3`, absent → `0`,
|
|
129
|
+
explicit `--verbose=2` supported). Takes no value token, not promptable,
|
|
130
|
+
and joins boolean flags in help (no `<value>` placeholder) and shell
|
|
131
|
+
completions.
|
|
132
|
+
- **`flag.keyValue()`** — repeated `KEY=VALUE` merges into
|
|
133
|
+
`Record<string, string>` (split at the first `=`, later keys win, unset
|
|
134
|
+
resolves to `{}`). Env accepts comma-separated pairs; config accepts a plain
|
|
135
|
+
object. New `'empty-object'` optional fallback joins arrays' `[]` as the
|
|
136
|
+
kinds that resolve to a value when unset.
|
|
137
|
+
|
|
138
|
+
## [3.0.0-rc.6] - 2026-07-09
|
|
139
|
+
|
|
140
|
+
### Added
|
|
141
|
+
|
|
142
|
+
- **Runtime terminal sizing hooks** — `RuntimeAdapter` now exposes
|
|
143
|
+
`getTerminalSize()` and `onTerminalResize()`. Node/Bun read
|
|
144
|
+
`process.stdout.getWindowSize()` (falling back to `columns` / `rows`) and
|
|
145
|
+
subscribe to stdout `resize`; Deno uses native `Deno.consoleSize()` and
|
|
146
|
+
`SIGWINCH` on non-Windows platforms.
|
|
147
|
+
|
|
148
|
+
### Changed
|
|
149
|
+
|
|
150
|
+
- **Help output now fits the live terminal in `.run()`** — root and command help
|
|
151
|
+
use runtime terminal columns when no explicit `.help({ width })` or runtime
|
|
152
|
+
`help.width` is provided. Non-TTY or unavailable sizes still fall back to 80,
|
|
153
|
+
and `.execute()` remains deterministic for tests.
|
|
154
|
+
|
|
155
|
+
## [3.0.0-rc.5] - 2026-07-08
|
|
156
|
+
|
|
157
|
+
### Removed
|
|
158
|
+
|
|
159
|
+
- **`createBunAdapter` export** (from `@kjanat/dreamcli/runtime`). Bun exposes a
|
|
160
|
+
Node-compatible `process`, so the Bun adapter had been a pure passthrough to
|
|
161
|
+
the Node adapter since the runtime version hard-fail was dropped — it blessed
|
|
162
|
+
a runtime rather than abstracting distinct I/O. Auto-detection now maps Bun to
|
|
163
|
+
the Node adapter directly and `src/runtime/bun.ts` is gone. Runtime detection
|
|
164
|
+
is unchanged: `detectRuntime()` still reports `'bun'` and `RUNTIMES` still
|
|
165
|
+
lists it. Callers that selected the Bun adapter explicitly should use
|
|
166
|
+
`createNodeAdapter` (identical behavior) or rely on `createAdapter()`
|
|
167
|
+
auto-detection (#51).
|
|
168
|
+
|
|
169
|
+
## [3.0.0-rc.4] - 2026-07-06
|
|
170
|
+
|
|
171
|
+
### Added
|
|
172
|
+
|
|
173
|
+
- **`.default(cmd, { route: true })`** — expose a default command under its own
|
|
174
|
+
name as a routable top-level command, in addition to the bare/flags-only root
|
|
175
|
+
surface. `mycli` and `mycli <name>` then run the same command object, and it
|
|
176
|
+
is listed in the root `Commands:` section (tagged `(default)`) beside its
|
|
177
|
+
siblings. Lets CLIs keep both a short root shorthand and an explicit,
|
|
178
|
+
documented named command without duplicating the builder (#55). Opt-in only
|
|
179
|
+
— the surface-only default remains the default behavior. With `route: true`
|
|
180
|
+
the name wins over positional interpretation, so a positional value equal to
|
|
181
|
+
the command's own name must be passed after `--`.
|
|
182
|
+
|
|
183
|
+
## [3.0.0-rc.3] - 2026-07-06
|
|
184
|
+
|
|
185
|
+
### Added
|
|
186
|
+
|
|
187
|
+
- **`@kjanat/dreamcli/version` subpath** — exposes the framework's own build
|
|
188
|
+
identity as `DREAMCLI_VERSION` and `DREAMCLI_REVISION` (git short SHA) for
|
|
189
|
+
diagnostics and bug reports. Deliberately a subpath rather than root exports
|
|
190
|
+
so the constants stay out of root-import IDE completions; both report
|
|
191
|
+
`'dev'` when running unbundled source.
|
|
192
|
+
|
|
193
|
+
## [3.0.0-rc.2] - 2026-07-06
|
|
194
|
+
|
|
195
|
+
### Added
|
|
196
|
+
|
|
197
|
+
- **`out.color` — context-aware ANSI colors** — every handler's `out` now carries
|
|
198
|
+
a color palette powered by [`ansispeck`](https://github.com/kjanat/ansispeck).
|
|
199
|
+
Colors auto-enable only when stdout is a TTY, JSON mode is off, and the
|
|
200
|
+
environment supports color (`NO_COLOR`, `FORCE_COLOR`, `--no-color`, `--color`,
|
|
201
|
+
`CI` respected); otherwise every formatter is an identity function, so handlers
|
|
202
|
+
can write `out.log(out.color.green('✔ done'))` unconditionally.
|
|
203
|
+
`createOutput({ color })` forces the palette on/off (useful for asserting
|
|
204
|
+
colored output in tests), and the `Colors` type is re-exported from the root
|
|
205
|
+
entrypoint. First runtime dependency — kept external in `dist` (~1 kB gzipped
|
|
206
|
+
install).
|
|
207
|
+
|
|
208
|
+
### Changed
|
|
209
|
+
|
|
210
|
+
- **npm package now resolves built `dist` on every runtime** — the `bun`/`deno`
|
|
211
|
+
→ `src/*.ts` export conditions are gone and `src` is no longer published to
|
|
212
|
+
npm (JSR still ships source). Bun and Deno consumers previously loaded raw
|
|
213
|
+
source where build-time defines never ran, so `version` reported `'dev'`;
|
|
214
|
+
they now get the same tested output as Node, with the real version. The
|
|
215
|
+
export map is generated by tsdown at build time instead of hand-maintained.
|
|
216
|
+
|
|
217
|
+
## [3.0.0-rc.1] - 2026-07-02
|
|
218
|
+
|
|
219
|
+
### Added
|
|
220
|
+
|
|
221
|
+
- **`.completions({ as: 'flag' })`** — expose shell completion as an eager
|
|
222
|
+
`--completions <shell>` flag on the CLI root instead of a `completions`
|
|
223
|
+
subcommand. The planner intercepts the flag before dispatch, prints the script,
|
|
224
|
+
and exits; root help advertises `--completions <bash|zsh|fish|powershell>` in its
|
|
225
|
+
`Flags:` section. `.completions()` still defaults to `{ as: 'command' }`. Because
|
|
226
|
+
the eager flag is intercepted before dispatch, the `--completions` name is
|
|
227
|
+
reserved in flag mode — declaring a command/default flag of that name throws at
|
|
228
|
+
build time.
|
|
229
|
+
- **Shell auto-detection** — `--completions` with no value (flag form) resolves the
|
|
230
|
+
target shell from the environment: `$SHELL` (parsed as an interpreter path) wins
|
|
231
|
+
when it names a supported shell, otherwise the presence of `$PSModulePath` selects
|
|
232
|
+
PowerShell — the reliable signal for `pwsh`, which never sets `$SHELL`.
|
|
233
|
+
- **`detectShell(env)` / `normalizeShell(raw)`** — exported helpers behind the
|
|
234
|
+
detection above; `normalizeShell` accepts bare names, `$SHELL` paths, and the
|
|
235
|
+
`pwsh`/`powershell` pair.
|
|
236
|
+
- **`.help(config)` builder + extended `HelpOptions`** — configure root-help
|
|
237
|
+
rendering: `inlineDefault`, `showDefaultInCommands`, and `footer` (plus the
|
|
238
|
+
existing `width` / `hyperlinks`). Builder config is merged under runtime
|
|
239
|
+
`options.help` (runtime wins).
|
|
240
|
+
- **Numeric constraints for number flags and args** — `flag.number()` and
|
|
241
|
+
`arg.number()` now accept `{ min?, max?, int?, finite? }` (bounds inclusive),
|
|
242
|
+
and the same constraints compose via chained `.int()` / `.min(n)` / `.max(n)` /
|
|
243
|
+
`.finite(allow?)` methods (a later call overrides an earlier value, including
|
|
244
|
+
one set in the options object). The chained methods are compile-time guarded
|
|
245
|
+
to number-kind builders only. Constraints are enforced identically across the
|
|
246
|
+
parse path and the env/config/prompt resolution path (order: finite → int →
|
|
247
|
+
min → max): parse-time (CLI) violations throw `INVALID_VALUE`, while
|
|
248
|
+
env/config/prompt coercion reports `CONSTRAINT_VIOLATED` (both exit code `2`).
|
|
249
|
+
They are also surfaced in the exported JSON Schema as `minimum` / `maximum` and
|
|
250
|
+
`type: "integer"` when `int` is set. `min` / `max` must be finite — a
|
|
251
|
+
non-finite bound (`Infinity` / `-Infinity` / `NaN`) throws at construction. The
|
|
252
|
+
resolved TypeScript value type stays `number`.
|
|
253
|
+
- **Prompt-level defaults for `confirm` and `input` prompts** — `confirm`
|
|
254
|
+
prompts accept `default?: boolean` (drives the `(Y/n)` vs `(y/N)` hint and the
|
|
255
|
+
empty-line result, so a confirm can default to **No**), and `input` prompts
|
|
256
|
+
accept `default?: string` (shown in the hint as `(default: <value>)` and used
|
|
257
|
+
when the user presses Enter, skipping `validate`). Precedence among defaults is
|
|
258
|
+
prompt-level `default` > flag `.default()`. Unset `confirm` default stays
|
|
259
|
+
backward compatible (`true`).
|
|
260
|
+
|
|
261
|
+
### Changed
|
|
262
|
+
|
|
263
|
+
- **BREAKING — the default command is now the root _surface_, not a named
|
|
264
|
+
subcommand.** `.default(cmd)` registers the command only as the default; it is no
|
|
265
|
+
longer added to `schema.commands`. Consequences:
|
|
266
|
+
- It can no longer be invoked by its own name (`mycli mycmd` does not route to it;
|
|
267
|
+
the token is treated as input to the default command).
|
|
268
|
+
- It is omitted from the root `Commands:` list by default (re-enable with
|
|
269
|
+
`.help({ showDefaultInCommands: true })`).
|
|
270
|
+
- Root `--help` renders the default command's `Arguments:`/`Flags:` inline even
|
|
271
|
+
when sibling commands exist (previously only when it was the sole command), and a
|
|
272
|
+
sole default with no subcommands shows its own usage line directly instead of a
|
|
273
|
+
`[command]` placeholder.
|
|
274
|
+
- **`finite` defaults to `true` (behavior change)** — `flag.number()` /
|
|
275
|
+
`arg.number()` now **reject `Infinity` and `-Infinity`**, which previously
|
|
276
|
+
passed straight through to handlers (`Number("Infinity")` is not `NaN`). Pass
|
|
277
|
+
`{ finite: false }` (or `.finite(false)`) to opt back into accepting non-finite
|
|
278
|
+
values. `NaN` continues to be rejected as before.
|
|
279
|
+
- **BREAKING — the runtime no longer hard-fails the host CLI on its version.**
|
|
280
|
+
Adapter construction previously threw (a bare, uncaught `Error`) when the
|
|
281
|
+
detected Node/Bun/Deno version was below DreamCLI's declared minimum, crashing
|
|
282
|
+
the consumer's CLI — including on `--help`. That check is removed: as a
|
|
283
|
+
dependency the consumer's package manager already enforces the `engines` range
|
|
284
|
+
at install time (and more softly), and when DreamCLI is bundled/inlined the
|
|
285
|
+
consumer — not us — owns their CLI's supported-runtime policy. `SUPPORTED_RUNTIMES`
|
|
286
|
+
and the generated `engines` minimums are unchanged and remain the source of
|
|
287
|
+
truth for docs and packaging.
|
|
288
|
+
|
|
289
|
+
### Fixed
|
|
290
|
+
|
|
291
|
+
- **Empty `input`-prompt answer no longer clobbers a flag's `.default()`** — a
|
|
292
|
+
flag declared with both `.default(...)` and an `input` prompt previously
|
|
293
|
+
resolved to `""` when the user submitted an empty line, because empty input was
|
|
294
|
+
treated as a real answer that short-circuited the default fallback. An empty or
|
|
295
|
+
blank `input` answer with no prompt-level `default` is now treated as "no
|
|
296
|
+
answer", so resolution falls through to the flag's `.default()` (or, for a
|
|
297
|
+
required flag, the standard missing-flag error).
|
|
298
|
+
|
|
299
|
+
### Fixed
|
|
300
|
+
|
|
301
|
+
- **Root `--help` now matches consistently with `--version`** (#29) — previously
|
|
302
|
+
`--help` / `-h` were intercepted at the root only when they were the very first
|
|
303
|
+
token, while `--version` / `-V` matched anywhere before `--`. A help flag
|
|
304
|
+
preceded only by flags (e.g. `mycli --verbose --help`) now shows root help,
|
|
305
|
+
mirroring `mycli --verbose --version`. A help flag that follows a subcommand
|
|
306
|
+
token still scopes to that subcommand (`mycli deploy --help` → `deploy` help);
|
|
307
|
+
`--version` remains a global, position-independent flag by design (there is no
|
|
308
|
+
per-command version). The bare `help` token now triggers root help from the same
|
|
309
|
+
position as `--help`, and the `--` end-of-options separator is respected for both.
|
|
310
|
+
- **Generated `--help` now advertises the active built-in global flags** (#32) — root
|
|
311
|
+
help renders a `Global options:` block listing `--help, -h` and `--json` (always),
|
|
312
|
+
`--version, -V` (when a version is set), and `--config <path>` (when `.config()`
|
|
313
|
+
enabled config discovery). Previously these framework-provided flags were invisible
|
|
314
|
+
in help even though they worked. `--completions` is unchanged (still advertised via
|
|
315
|
+
the inline surface when active).
|
|
316
|
+
- **Root usage no longer prints the default command's name** — the merged/sole-default
|
|
317
|
+
usage line rendered `Usage: <bin> <default-name> …`, teaching an invocation that does
|
|
318
|
+
not route (`.default()` is not a named command, so the token is consumed as the
|
|
319
|
+
default's first positional). It now renders under the bin name only
|
|
320
|
+
(`Usage: <bin> [flags] <args>`).
|
|
321
|
+
- **`inlineDefault: false` no longer hides a sole default command's interface** — when
|
|
322
|
+
the default command is the only surface (no visible subcommands and no eager
|
|
323
|
+
`--completions` flag), root help would collapse to a bare `Usage: <bin> [options]`
|
|
324
|
+
with no discoverable args/flags. The default is now always rendered inline in that
|
|
325
|
+
case, since suppressing it leaves no other path to its interface.
|
|
326
|
+
|
|
327
|
+
### Fixed
|
|
328
|
+
|
|
329
|
+
- **`runCommand()` now honors a CLI-level `--json` passed in `argv`** — the testkit
|
|
330
|
+
gained the same root-flag layer as the real CLI: a `--json` before the `--`
|
|
331
|
+
separator enables JSON mode and is stripped before parsing, instead of failing
|
|
332
|
+
with `Unknown flag --json` (exit 2). A literal `--json` after `--` still reaches
|
|
333
|
+
the command unchanged. The existing `{ jsonMode: true }` option keeps working —
|
|
334
|
+
either source enables JSON mode. Copying a real `mycli --json …` invocation into a
|
|
335
|
+
test now works verbatim.
|
|
336
|
+
- **`createTestPrompter()` now runs an `input` prompt's `validate`** — a queued
|
|
337
|
+
string answer to an `input` prompt is validated exactly as the terminal prompter
|
|
338
|
+
does; an answer that fails validation is rejected as a cancellation rather than
|
|
339
|
+
injected verbatim as the resolved value, so prompt validation is integration-testable
|
|
340
|
+
through `runCommand(cmd, argv, { answers })`. Non-string answers stay verbatim so
|
|
341
|
+
downstream coercion paths remain testable.
|
|
342
|
+
|
|
10
343
|
## [2.5.0] - 2026-06-28
|
|
11
344
|
|
|
12
345
|
### Added
|
|
@@ -878,7 +1211,17 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
878
1211
|
- MIT License.
|
|
879
1212
|
- Markdownlint configuration.
|
|
880
1213
|
|
|
881
|
-
[Unreleased]: https://github.com/kjanat/dreamcli/compare/
|
|
1214
|
+
[Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.10...HEAD
|
|
1215
|
+
[3.0.0-rc.10]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.9...v3.0.0-rc.10
|
|
1216
|
+
[3.0.0-rc.9]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.8...v3.0.0-rc.9
|
|
1217
|
+
[3.0.0-rc.8]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.7...v3.0.0-rc.8
|
|
1218
|
+
[3.0.0-rc.7]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.6...v3.0.0-rc.7
|
|
1219
|
+
[3.0.0-rc.6]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.5...v3.0.0-rc.6
|
|
1220
|
+
[3.0.0-rc.5]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.4...v3.0.0-rc.5
|
|
1221
|
+
[3.0.0-rc.4]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.3...v3.0.0-rc.4
|
|
1222
|
+
[3.0.0-rc.3]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.2...v3.0.0-rc.3
|
|
1223
|
+
[3.0.0-rc.2]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.1...v3.0.0-rc.2
|
|
1224
|
+
[3.0.0-rc.1]: https://github.com/kjanat/dreamcli/compare/v2.5.0...v3.0.0-rc.1
|
|
882
1225
|
[2.5.0]: https://github.com/kjanat/dreamcli/compare/v2.4.1...v2.5.0
|
|
883
1226
|
[2.4.1]: https://github.com/kjanat/dreamcli/compare/v2.4.0...v2.4.1
|
|
884
1227
|
[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,15 +1,14 @@
|
|
|
1
|
-
import { FlagSchema } from "../schema/flag.mjs";
|
|
2
1
|
import { CommandSchema, ErasedCommand } from "../schema/command.mjs";
|
|
3
|
-
|
|
2
|
+
import { FlagLookupEntry, ParseOptions } from "../parse/index.mjs";
|
|
4
3
|
//#region src/core/cli/dispatch.d.ts
|
|
5
4
|
/**
|
|
6
|
-
* Flag lookup (
|
|
5
|
+
* Flag lookup (spelling → {@link FlagLookupEntry}) used to make the
|
|
7
6
|
* command-name scan aware of value-flag arity. Built from the flags valid at
|
|
8
7
|
* the current dispatch level via {@link buildFlagLookup}.
|
|
9
8
|
*
|
|
10
9
|
* @internal
|
|
11
10
|
*/
|
|
12
|
-
type ValueFlagLookup = ReadonlyMap<string,
|
|
11
|
+
type ValueFlagLookup = ReadonlyMap<string, FlagLookupEntry>;
|
|
13
12
|
/** Successful dispatch — target command found with argv path. */
|
|
14
13
|
interface DispatchMatch {
|
|
15
14
|
/** Discriminant — a command name in argv matched a registered command. */
|
|
@@ -65,11 +64,13 @@ type DispatchResult = DispatchMatch | DispatchNeedsSubcommand | DispatchUnknown;
|
|
|
65
64
|
* @param valueFlags - Lookup of flags valid at this level, used so a
|
|
66
65
|
* space-separated value-flag's value (`--region eu`) is not mistaken for a
|
|
67
66
|
* command name. Empty by default (arity-unaware, legacy behaviour).
|
|
67
|
+
* @param parseOptions - Parser toggles (case parity) applied to descent-level
|
|
68
|
+
* flag lookups built inside dispatch.
|
|
68
69
|
* @returns Discriminated dispatch result.
|
|
69
70
|
*
|
|
70
71
|
* @internal
|
|
71
72
|
*/
|
|
72
|
-
declare function dispatch(argv: readonly string[], commands: ReadonlyMap<string, ErasedCommand>, ancestorPath?: readonly CommandSchema[], valueFlags?: ValueFlagLookup): DispatchResult;
|
|
73
|
+
declare function dispatch(argv: readonly string[], commands: ReadonlyMap<string, ErasedCommand>, ancestorPath?: readonly CommandSchema[], valueFlags?: ValueFlagLookup, parseOptions?: ParseOptions): DispatchResult;
|
|
73
74
|
/**
|
|
74
75
|
* Whether a flag token consumes the following argv token as its value.
|
|
75
76
|
*
|
|
@@ -1 +1,205 @@
|
|
|
1
|
-
import{buildFlagLookup
|
|
1
|
+
import { buildFlagLookup, flagExpectsValue } from "../parse/index.mjs";
|
|
2
|
+
//#region src/core/cli/dispatch.ts
|
|
3
|
+
/**
|
|
4
|
+
* Recursively walk argv, consuming command name segments from the front.
|
|
5
|
+
*
|
|
6
|
+
* At each level, the first non-flag token is tested as a command name
|
|
7
|
+
* against the provided command map. If matched and the matched command
|
|
8
|
+
* has subcommands, dispatch recurses into the child level with the
|
|
9
|
+
* remaining argv.
|
|
10
|
+
*
|
|
11
|
+
* Ambiguity resolution for commands that have both an action handler AND
|
|
12
|
+
* subcommands (e.g. `git remote` lists remotes, `git remote add` dispatches):
|
|
13
|
+
* - If the next token matches a subcommand → descend
|
|
14
|
+
* - If the next token is unknown and the command has a handler → match here
|
|
15
|
+
* - If the next token is unknown and no handler → propagate unknown error
|
|
16
|
+
* - If no next token and command has a handler → match here
|
|
17
|
+
* - If no next token and no handler → needs-subcommand
|
|
18
|
+
*
|
|
19
|
+
* @param argv - Remaining argv tokens (command names + flags + args).
|
|
20
|
+
* @param commands - Command map at the current tree level.
|
|
21
|
+
* @param ancestorPath - Schema path from root to current level (exclusive).
|
|
22
|
+
* @param valueFlags - Lookup of flags valid at this level, used so a
|
|
23
|
+
* space-separated value-flag's value (`--region eu`) is not mistaken for a
|
|
24
|
+
* command name. Empty by default (arity-unaware, legacy behaviour).
|
|
25
|
+
* @param parseOptions - Parser toggles (case parity) applied to descent-level
|
|
26
|
+
* flag lookups built inside dispatch.
|
|
27
|
+
* @returns Discriminated dispatch result.
|
|
28
|
+
*
|
|
29
|
+
* @internal
|
|
30
|
+
*/
|
|
31
|
+
function dispatch(argv, commands, ancestorPath = [], valueFlags = /* @__PURE__ */ new Map(), parseOptions) {
|
|
32
|
+
let cmdIdx = -1;
|
|
33
|
+
for (let i = 0; i < argv.length; i++) {
|
|
34
|
+
const token = argv[i];
|
|
35
|
+
if (token === void 0) continue;
|
|
36
|
+
if (token === "--") {
|
|
37
|
+
if (i + 1 < argv.length) cmdIdx = i + 1;
|
|
38
|
+
break;
|
|
39
|
+
}
|
|
40
|
+
if (token.startsWith("-")) {
|
|
41
|
+
if (consumesFollowingToken(token, valueFlags)) i++;
|
|
42
|
+
continue;
|
|
43
|
+
}
|
|
44
|
+
cmdIdx = i;
|
|
45
|
+
break;
|
|
46
|
+
}
|
|
47
|
+
if (cmdIdx === -1) return {
|
|
48
|
+
kind: "unknown",
|
|
49
|
+
input: "",
|
|
50
|
+
candidates: uniqueCommands(commands),
|
|
51
|
+
parentPath: ancestorPath
|
|
52
|
+
};
|
|
53
|
+
const cmdName = argv[cmdIdx];
|
|
54
|
+
if (cmdName === void 0) return {
|
|
55
|
+
kind: "unknown",
|
|
56
|
+
input: "",
|
|
57
|
+
candidates: uniqueCommands(commands),
|
|
58
|
+
parentPath: ancestorPath
|
|
59
|
+
};
|
|
60
|
+
const matched = commands.get(cmdName);
|
|
61
|
+
if (matched === void 0) return {
|
|
62
|
+
kind: "unknown",
|
|
63
|
+
input: cmdName,
|
|
64
|
+
candidates: uniqueCommands(commands),
|
|
65
|
+
parentPath: ancestorPath
|
|
66
|
+
};
|
|
67
|
+
const remaining = [...argv.slice(0, cmdIdx), ...argv.slice(cmdIdx + 1)];
|
|
68
|
+
const currentPath = [...ancestorPath, matched.schema];
|
|
69
|
+
if (matched.subcommands.size > 0) {
|
|
70
|
+
const subResult = dispatch(remaining, matched.subcommands, currentPath, buildFlagLookup(matched.schema.flags, parseOptions), parseOptions);
|
|
71
|
+
switch (subResult.kind) {
|
|
72
|
+
case "match": return subResult;
|
|
73
|
+
case "unknown":
|
|
74
|
+
if (subResult.input === "") {
|
|
75
|
+
if (matched.schema.hasAction) return {
|
|
76
|
+
kind: "match",
|
|
77
|
+
command: matched,
|
|
78
|
+
commandPath: currentPath,
|
|
79
|
+
remainingArgv: remaining
|
|
80
|
+
};
|
|
81
|
+
return {
|
|
82
|
+
kind: "needs-subcommand",
|
|
83
|
+
command: matched,
|
|
84
|
+
commandPath: currentPath
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
if (matched.schema.hasAction) return {
|
|
88
|
+
kind: "match",
|
|
89
|
+
command: matched,
|
|
90
|
+
commandPath: currentPath,
|
|
91
|
+
remainingArgv: remaining
|
|
92
|
+
};
|
|
93
|
+
return subResult;
|
|
94
|
+
case "needs-subcommand": return subResult;
|
|
95
|
+
default: return subResult;
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
return {
|
|
99
|
+
kind: "match",
|
|
100
|
+
command: matched,
|
|
101
|
+
commandPath: currentPath,
|
|
102
|
+
remainingArgv: remaining
|
|
103
|
+
};
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* Whether a flag token consumes the following argv token as its value.
|
|
107
|
+
*
|
|
108
|
+
* Mirrors the parser's value-consumption rules (`parseLongFlag` /
|
|
109
|
+
* `parseShortFlags`) so the command-name scan skips exactly the tokens the
|
|
110
|
+
* parser would treat as flag values:
|
|
111
|
+
* - `--flag value` → consumes when `--flag` is a known value-flag.
|
|
112
|
+
* - `--flag=value` → self-contained, consumes nothing.
|
|
113
|
+
* - `-abc value` → consumes only when the trailing short flag is a value-flag;
|
|
114
|
+
* an earlier value-flag char takes the rest of the group as an inline value.
|
|
115
|
+
*
|
|
116
|
+
* Unknown flags conservatively consume nothing (the parser reports them later).
|
|
117
|
+
*
|
|
118
|
+
* @internal
|
|
119
|
+
*/
|
|
120
|
+
function consumesFollowingToken(token, valueFlags) {
|
|
121
|
+
if (token.startsWith("--")) {
|
|
122
|
+
if (token.includes("=")) return false;
|
|
123
|
+
const entry = valueFlags.get(token.slice(2));
|
|
124
|
+
return entry !== void 0 && flagExpectsValue(entry.schema);
|
|
125
|
+
}
|
|
126
|
+
const chars = token.slice(1);
|
|
127
|
+
for (let i = 0; i < chars.length; i++) {
|
|
128
|
+
const entry = valueFlags.get(chars.charAt(i));
|
|
129
|
+
if (entry === void 0) return false;
|
|
130
|
+
if (!flagExpectsValue(entry.schema)) continue;
|
|
131
|
+
return i === chars.length - 1;
|
|
132
|
+
}
|
|
133
|
+
return false;
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* Levenshtein distance between two strings.
|
|
137
|
+
* @internal
|
|
138
|
+
*/
|
|
139
|
+
function levenshtein(a, b) {
|
|
140
|
+
const m = a.length;
|
|
141
|
+
const n = b.length;
|
|
142
|
+
const w = n + 1;
|
|
143
|
+
let prev = new Uint16Array(w);
|
|
144
|
+
let curr = new Uint16Array(w);
|
|
145
|
+
for (let j = 0; j <= n; j++) prev[j] = j;
|
|
146
|
+
for (let i = 1; i <= m; i++) {
|
|
147
|
+
curr[0] = i;
|
|
148
|
+
for (let j = 1; j <= n; j++) {
|
|
149
|
+
const cost = a.charAt(i - 1) === b.charAt(j - 1) ? 0 : 1;
|
|
150
|
+
const del = prev[j] ?? 0;
|
|
151
|
+
const ins = curr[j - 1] ?? 0;
|
|
152
|
+
const sub = prev[j - 1] ?? 0;
|
|
153
|
+
curr[j] = Math.min(del + 1, ins + 1, sub + cost);
|
|
154
|
+
}
|
|
155
|
+
[prev, curr] = [curr, prev];
|
|
156
|
+
}
|
|
157
|
+
return prev[n] ?? Math.max(m, n);
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* Find the closest command name match for a "did you mean?" suggestion.
|
|
161
|
+
*
|
|
162
|
+
* Searches command names and aliases. Returns `undefined` if no
|
|
163
|
+
* sufficiently close match exists (threshold: 3).
|
|
164
|
+
*
|
|
165
|
+
* @internal
|
|
166
|
+
*/
|
|
167
|
+
function findClosestCommand(input, commands) {
|
|
168
|
+
const MAX_DISTANCE = 3;
|
|
169
|
+
let bestName;
|
|
170
|
+
let bestDist = 4;
|
|
171
|
+
for (const cmd of commands) {
|
|
172
|
+
const nameDist = levenshtein(input, cmd.schema.name);
|
|
173
|
+
if (nameDist < bestDist) {
|
|
174
|
+
bestDist = nameDist;
|
|
175
|
+
bestName = cmd.schema.name;
|
|
176
|
+
}
|
|
177
|
+
for (const alias of cmd.schema.aliases) {
|
|
178
|
+
const aliasDist = levenshtein(input, alias);
|
|
179
|
+
if (aliasDist < bestDist) {
|
|
180
|
+
bestDist = aliasDist;
|
|
181
|
+
bestName = cmd.schema.name;
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
return bestDist <= MAX_DISTANCE ? bestName : void 0;
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* Deduplicate commands from a name+alias map.
|
|
189
|
+
*
|
|
190
|
+
* A map keyed by name *and* alias contains duplicate entries for aliased
|
|
191
|
+
* commands. This returns unique commands (by schema identity).
|
|
192
|
+
*
|
|
193
|
+
* @internal
|
|
194
|
+
*/
|
|
195
|
+
function uniqueCommands(commands) {
|
|
196
|
+
const seen = /* @__PURE__ */ new Set();
|
|
197
|
+
const result = [];
|
|
198
|
+
for (const cmd of commands.values()) if (!seen.has(cmd)) {
|
|
199
|
+
seen.add(cmd);
|
|
200
|
+
result.push(cmd);
|
|
201
|
+
}
|
|
202
|
+
return result;
|
|
203
|
+
}
|
|
204
|
+
//#endregion
|
|
205
|
+
export { consumesFollowingToken, dispatch, findClosestCommand, levenshtein, uniqueCommands };
|