@kjanat/dreamcli 3.0.0-rc.6 → 3.0.0-rc.8
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 +94 -1
- package/dist/core/cli/dispatch.d.mts +6 -5
- package/dist/core/cli/dispatch.mjs +7 -5
- package/dist/core/cli/help-links.d.mts +0 -1
- package/dist/core/cli/index.d.mts +27 -2
- package/dist/core/cli/index.mjs +28 -14
- package/dist/core/cli/planner.d.mts +3 -1
- package/dist/core/cli/planner.mjs +12 -12
- package/dist/core/cli/plugin.d.mts +1 -1
- package/dist/core/cli/propagate.d.mts +1 -1
- package/dist/core/cli/root-help.d.mts +0 -1
- package/dist/core/cli/root-help.mjs +38 -21
- package/dist/core/cli/root-surface.d.mts +0 -1
- package/dist/core/cli/runtime-preflight.d.mts +12 -2
- package/dist/core/cli/runtime-preflight.mjs +5 -4
- package/dist/core/completion/index.d.mts +0 -1
- package/dist/core/completion/index.mjs +1 -1
- package/dist/core/completion/shells/bash.d.mts +0 -1
- package/dist/core/completion/shells/bash.mjs +8 -4
- package/dist/core/completion/shells/fish.d.mts +0 -1
- package/dist/core/completion/shells/fish.mjs +6 -3
- package/dist/core/completion/shells/powershell.d.mts +0 -1
- package/dist/core/completion/shells/powershell.mjs +10 -5
- package/dist/core/completion/shells/shared.d.mts +13 -2
- package/dist/core/completion/shells/shared.mjs +24 -2
- package/dist/core/completion/shells/zsh.d.mts +0 -1
- package/dist/core/completion/shells/zsh.mjs +11 -4
- package/dist/core/config/index.d.mts +2 -3
- package/dist/core/config/index.mjs +2 -2
- package/dist/core/config/package-json.d.mts +27 -4
- package/dist/core/config/package-json.mjs +20 -19
- package/dist/core/errors/index.d.mts +1 -1
- package/dist/core/execution/index.d.mts +0 -1
- package/dist/core/execution/index.mjs +8 -4
- package/dist/core/help/ansi.mjs +3 -2
- package/dist/core/help/index.d.mts +22 -3
- package/dist/core/help/index.mjs +65 -53
- 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 +1 -1
- package/dist/core/json-schema/index.mjs +39 -8
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
- package/dist/core/json-schema/meta-descriptions.generated.mjs +14 -5
- package/dist/core/output/activity.d.mts +0 -1
- package/dist/core/output/contracts.d.mts +0 -1
- package/dist/core/output/contracts.mjs +1 -1
- package/dist/core/output/index.d.mts +0 -1
- package/dist/core/output/index.mjs +1 -1
- package/dist/core/output/renderers.d.mts +0 -1
- package/dist/core/parse/index.d.mts +40 -7
- package/dist/core/parse/index.mjs +209 -40
- package/dist/core/prompt/index.d.mts +1 -0
- package/dist/core/resolve/args.d.mts +1 -1
- package/dist/core/resolve/coerce.d.mts +1 -1
- package/dist/core/resolve/coerce.mjs +71 -14
- package/dist/core/resolve/contracts.d.mts +7 -2
- package/dist/core/resolve/errors.d.mts +0 -1
- package/dist/core/resolve/flags.d.mts +7 -2
- package/dist/core/resolve/flags.mjs +61 -6
- package/dist/core/resolve/index.d.mts +2 -2
- package/dist/core/resolve/index.mjs +1 -1
- package/dist/core/resolve/property.d.mts +3 -0
- package/dist/core/resolve/property.mjs +11 -3
- package/dist/core/schema/activity.d.mts +31 -11
- package/dist/core/schema/arg.d.mts +1 -2
- package/dist/core/schema/command.d.mts +8 -6
- package/dist/core/schema/command.mjs +26 -12
- package/dist/core/schema/flag.d.mts +439 -10
- package/dist/core/schema/flag.mjs +255 -3
- package/dist/core/schema/index.d.mts +4 -2
- package/dist/core/schema/middleware.d.mts +4 -3
- package/dist/core/schema/prompt.d.mts +5 -2
- package/dist/core/schema/run.d.mts +20 -1
- 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/to-json-schema.d.mts +0 -1
- package/dist/core/testkit/index.d.mts +0 -31
- package/dist/core/testkit/index.mjs +1 -1
- package/dist/index.d.mts +8 -4
- package/dist/index.mjs +7 -7
- package/dist/runtime/adapter.d.mts +22 -1
- package/dist/runtime/adapter.mjs +3 -0
- package/dist/runtime/auto.d.mts +0 -1
- package/dist/runtime/deno.d.mts +15 -5
- package/dist/runtime/deno.mjs +9 -0
- package/dist/runtime/node.d.mts +2 -2
- package/dist/runtime/node.mjs +10 -0
- package/dist/runtime.d.mts +1 -0
- package/dist/testkit.d.mts +1 -0
- package/dist/version.mjs +2 -2
- package/dreamcli.schema.json +35 -6
- package/package.json +12 -13
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,97 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [3.0.0-rc.8] - 2026-07-11
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- **Themed help output** — root and per-command help render with a semantic
|
|
15
|
+
color theme (bold+underlined section titles, cyan literals, dimmed metadata,
|
|
16
|
+
yellow deprecations) whenever color is enabled, using the same gate as
|
|
17
|
+
`out.color` (TTY + color support, no `--json`, `NO_COLOR`/`FORCE_COLOR`
|
|
18
|
+
honored). Piped and JSON output stays byte-clean. Customize via
|
|
19
|
+
`.help({ theme: (c) => ({ sectionTitle: c.magenta }) })` — the factory
|
|
20
|
+
receives the gated ansispeck palette and is never invoked when color is off,
|
|
21
|
+
so custom themes cannot leak escapes. New public types: `HelpTheme`,
|
|
22
|
+
`HelpThemeFactory`.
|
|
23
|
+
- **Negatable booleans** — `flag.boolean().negatable()` accepts `--no-<name>`
|
|
24
|
+
as `false`. Both spellings are one logical flag (last CLI occurrence wins,
|
|
25
|
+
shared duplicate policy); the negated spelling is presence-only
|
|
26
|
+
(`--no-foo=x` errors) and renders as `--[no-]foo` in help. Custom spelling
|
|
27
|
+
via `{ alias }`, unadvertised via `{ hidden }`. Env/config/prompt/default
|
|
28
|
+
resolution is unchanged.
|
|
29
|
+
- **Duplicate policy** — `.duplicates('last' | 'first' | 'error')` on
|
|
30
|
+
singleton flags controls repeated CLI occurrences. `'error'` throws
|
|
31
|
+
`ParseError` code `DUPLICATE_FLAG` with `{ flag, count, values }` details;
|
|
32
|
+
`'first'` keeps the first value while still consuming later value tokens.
|
|
33
|
+
Counted per logical flag (aliases + negated + parity spellings); env/config
|
|
34
|
+
precedence is never a duplicate.
|
|
35
|
+
- **`packageRepositoryUrl(pkg, { require: true })`** — narrows the return
|
|
36
|
+
type to `string`, throwing a `CLIError` (code `INVALID_REPOSITORY`) at the
|
|
37
|
+
call site when the `repository` field is missing or not a recognisable
|
|
38
|
+
locator. Removes the `!` assertion for manifests known to carry a valid
|
|
39
|
+
repository, with the guarantee enforced at runtime rather than assumed.
|
|
40
|
+
- **Flag spelling parity (kebab ↔ camel)** — `--doThis` matches a flag named
|
|
41
|
+
`do-this` and vice versa, for names and long aliases, on by default.
|
|
42
|
+
Handler keys, help, completions, and suggestions stay canonical.
|
|
43
|
+
Automatically disabled per pair when both spellings are declared explicitly;
|
|
44
|
+
globally via `cli('mycli', { flags: { caseParity: false } })` (new
|
|
45
|
+
`cli(name, options)` overload) or `RunOptions.flags`.
|
|
46
|
+
|
|
47
|
+
### Fixed
|
|
48
|
+
|
|
49
|
+
- `execute(argv, { flags })` overrides now reach the planner's dispatch arity
|
|
50
|
+
scanning, not just command parsing.
|
|
51
|
+
- Generated meta-schema descriptions render `@defaultValue` tags as a
|
|
52
|
+
`Default: <value>` paragraph instead of silently dropping them.
|
|
53
|
+
|
|
54
|
+
## [3.0.0-rc.7] - 2026-07-10
|
|
55
|
+
|
|
56
|
+
### Added
|
|
57
|
+
|
|
58
|
+
- **`.derive()` handlers may omit the return** — a validation-only derive with
|
|
59
|
+
no `return` statement (sync or async) now typechecks; previously `void` /
|
|
60
|
+
`Promise<void>` failed the `Output` constraint and forced an explicit
|
|
61
|
+
`return undefined`.
|
|
62
|
+
- **String constraints** — `flag.string({ nonEmpty, minLength, maxLength, pattern })`
|
|
63
|
+
plus chained `.nonEmpty()` / `.minLength()` / `.maxLength()` / `.pattern()`,
|
|
64
|
+
mirroring the numeric-constraint model. Checked in fixed order
|
|
65
|
+
(nonEmpty → minLength → maxLength → pattern) at both the CLI parse boundary
|
|
66
|
+
(`INVALID_VALUE`) and env/config/prompt resolution (`CONSTRAINT_VIOLATED`),
|
|
67
|
+
and emitted into the exported JSON Schema as `minLength` / `maxLength` /
|
|
68
|
+
`pattern`.
|
|
69
|
+
- **`.separator()` and `.unique()` on array flags** — `.separator(',')` splits
|
|
70
|
+
each CLI occurrence before element coercion, so `--region us,eu --region ap`
|
|
71
|
+
works alongside repetition and errors name the offending element. Env/config
|
|
72
|
+
string values use the same separator (default remains `','`). `.unique()`
|
|
73
|
+
deduplicates the final resolved array (first-seen order) regardless of
|
|
74
|
+
source.
|
|
75
|
+
- **`flag.url()`** — parses into a `URL`, with optional
|
|
76
|
+
`{ protocols: ['https'] }` allowlist. Help shows `<url>`.
|
|
77
|
+
- **`flag.path()`** — path string with opt-in filesystem checks
|
|
78
|
+
(`{ mustExist: true }`, `{ type: 'file' | 'directory' }`) validated after
|
|
79
|
+
resolution through the runtime adapter, so CLI/env/config values are checked
|
|
80
|
+
identically. `RuntimeAdapter` gained a `stat()` primitive (Node/Bun via
|
|
81
|
+
`node:fs/promises`, Deno via `Deno.stat`; test adapters default to "nothing
|
|
82
|
+
exists"), and `RunOptions` / `ResolveOptions` accept a `stat` injection for
|
|
83
|
+
process-free execution — without one, checks are skipped.
|
|
84
|
+
- **`flag.date()`** — strict ISO-8601 → `Date` with optional inclusive
|
|
85
|
+
`min` / `max` bounds. Rejects lenient `Date.parse` inputs (`'0'`,
|
|
86
|
+
`'March 5'`) and calendar-invalid dates (`2026-02-31`).
|
|
87
|
+
- **`flag.duration()`** — `'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`,
|
|
88
|
+
compounds (`'1h30m'`), or bare milliseconds → milliseconds.
|
|
89
|
+
- **`flag.bytes()`** — `'512mb'`, `'1.5gb'`, `'64kb'` or bare bytes → bytes
|
|
90
|
+
(binary units, case-insensitive).
|
|
91
|
+
- **`flag.count()`** — occurrence counter (`-vvv` → `3`, absent → `0`,
|
|
92
|
+
explicit `--verbose=2` supported). Takes no value token, not promptable,
|
|
93
|
+
and joins boolean flags in help (no `<value>` placeholder) and shell
|
|
94
|
+
completions.
|
|
95
|
+
- **`flag.keyValue()`** — repeated `KEY=VALUE` merges into
|
|
96
|
+
`Record<string, string>` (split at the first `=`, later keys win, unset
|
|
97
|
+
resolves to `{}`). Env accepts comma-separated pairs; config accepts a plain
|
|
98
|
+
object. New `'empty-object'` optional fallback joins arrays' `[]` as the
|
|
99
|
+
kinds that resolve to a value when unset.
|
|
100
|
+
|
|
10
101
|
## [3.0.0-rc.6] - 2026-07-09
|
|
11
102
|
|
|
12
103
|
### Added
|
|
@@ -1083,7 +1174,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
1083
1174
|
- MIT License.
|
|
1084
1175
|
- Markdownlint configuration.
|
|
1085
1176
|
|
|
1086
|
-
[Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.
|
|
1177
|
+
[Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.8...HEAD
|
|
1178
|
+
[3.0.0-rc.8]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.7...v3.0.0-rc.8
|
|
1179
|
+
[3.0.0-rc.7]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.6...v3.0.0-rc.7
|
|
1087
1180
|
[3.0.0-rc.6]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.5...v3.0.0-rc.6
|
|
1088
1181
|
[3.0.0-rc.5]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.4...v3.0.0-rc.5
|
|
1089
1182
|
[3.0.0-rc.4]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.3...v3.0.0-rc.4
|
|
@@ -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
|
*
|
|
@@ -33,11 +33,13 @@ import { buildFlagLookup, flagExpectsValue } from "../parse/index.mjs";
|
|
|
33
33
|
* @param valueFlags - Lookup of flags valid at this level, used so a
|
|
34
34
|
* space-separated value-flag's value (`--region eu`) is not mistaken for a
|
|
35
35
|
* command name. Empty by default (arity-unaware, legacy behaviour).
|
|
36
|
+
* @param parseOptions - Parser toggles (case parity) applied to descent-level
|
|
37
|
+
* flag lookups built inside dispatch.
|
|
36
38
|
* @returns Discriminated dispatch result.
|
|
37
39
|
*
|
|
38
40
|
* @internal
|
|
39
41
|
*/
|
|
40
|
-
function dispatch(argv, commands, ancestorPath = [], valueFlags = /* @__PURE__ */ new Map()) {
|
|
42
|
+
function dispatch(argv, commands, ancestorPath = [], valueFlags = /* @__PURE__ */ new Map(), parseOptions) {
|
|
41
43
|
let cmdIdx = -1;
|
|
42
44
|
for (let i = 0; i < argv.length; i++) {
|
|
43
45
|
const token = argv[i];
|
|
@@ -76,7 +78,7 @@ function dispatch(argv, commands, ancestorPath = [], valueFlags = /* @__PURE__ *
|
|
|
76
78
|
const remaining = [...argv.slice(0, cmdIdx), ...argv.slice(cmdIdx + 1)];
|
|
77
79
|
const currentPath = [...ancestorPath, matched.schema];
|
|
78
80
|
if (matched.subcommands.size > 0) {
|
|
79
|
-
const subResult = dispatch(remaining, matched.subcommands, currentPath, buildFlagLookup(matched.schema.flags));
|
|
81
|
+
const subResult = dispatch(remaining, matched.subcommands, currentPath, buildFlagLookup(matched.schema.flags, parseOptions), parseOptions);
|
|
80
82
|
switch (subResult.kind) {
|
|
81
83
|
case "match": return subResult;
|
|
82
84
|
case "unknown":
|
|
@@ -130,13 +132,13 @@ function consumesFollowingToken(token, valueFlags) {
|
|
|
130
132
|
if (token.startsWith("--")) {
|
|
131
133
|
if (token.includes("=")) return false;
|
|
132
134
|
const entry = valueFlags.get(token.slice(2));
|
|
133
|
-
return entry !== void 0 && flagExpectsValue(entry
|
|
135
|
+
return entry !== void 0 && flagExpectsValue(entry.schema);
|
|
134
136
|
}
|
|
135
137
|
const chars = token.slice(1);
|
|
136
138
|
for (let i = 0; i < chars.length; i++) {
|
|
137
139
|
const entry = valueFlags.get(chars.charAt(i));
|
|
138
140
|
if (entry === void 0) return false;
|
|
139
|
-
if (!flagExpectsValue(entry
|
|
141
|
+
if (!flagExpectsValue(entry.schema)) continue;
|
|
140
142
|
return i === chars.length - 1;
|
|
141
143
|
}
|
|
142
144
|
return false;
|
|
@@ -211,4 +213,4 @@ function uniqueCommands(commands) {
|
|
|
211
213
|
return result;
|
|
212
214
|
}
|
|
213
215
|
//#endregion
|
|
214
|
-
export { dispatch, findClosestCommand };
|
|
216
|
+
export { consumesFollowingToken, dispatch, findClosestCommand, levenshtein, uniqueCommands };
|
|
@@ -1,8 +1,11 @@
|
|
|
1
1
|
import { ArgBuilder, ArgConfig } from "../schema/arg.mjs";
|
|
2
2
|
import { FlagBuilder, FlagConfig } from "../schema/flag.mjs";
|
|
3
3
|
import { BeforeParseParams, CLIPlugin, CLIPluginHooks, PluginCommandContext, ResolvedCommandParams, plugin } from "./plugin.mjs";
|
|
4
|
+
import { HelpThemeFactory } from "../help/theme.mjs";
|
|
5
|
+
import "../help/index.mjs";
|
|
4
6
|
import { RunOptions, RunResult } from "../schema/run.mjs";
|
|
5
7
|
import { CommandBuilder, ErasedCommand } from "../schema/command.mjs";
|
|
8
|
+
import { ParseOptions } from "../parse/index.mjs";
|
|
6
9
|
import { RuntimeAdapter } from "../../runtime/adapter.mjs";
|
|
7
10
|
import { PackageJsonData } from "../config/package-json.mjs";
|
|
8
11
|
import { HelpLinks } from "./help-links.mjs";
|
|
@@ -10,7 +13,6 @@ import { CompletionOptions } from "../completion/shells/shared.mjs";
|
|
|
10
13
|
import { Shell } from "../completion/index.mjs";
|
|
11
14
|
import { FormatLoader } from "../config/index.mjs";
|
|
12
15
|
import { formatRootHelp } from "./root-help.mjs";
|
|
13
|
-
|
|
14
16
|
//#region src/core/cli/index.d.ts
|
|
15
17
|
/**
|
|
16
18
|
* Runtime descriptor for the CLI program.
|
|
@@ -97,6 +99,12 @@ interface CLISchema {
|
|
|
97
99
|
* under runtime `options.help` (runtime wins) before rendering.
|
|
98
100
|
*/
|
|
99
101
|
readonly helpConfig: HelpConfig | undefined;
|
|
102
|
+
/**
|
|
103
|
+
* Flag-parsing behavior settings ({@link ParseOptions}).
|
|
104
|
+
*
|
|
105
|
+
* Set via the `cli(name, { flags })` / `cli({ flags })` factory forms.
|
|
106
|
+
*/
|
|
107
|
+
readonly flagSettings: ParseOptions | undefined;
|
|
100
108
|
/** Registered CLI plugins. */
|
|
101
109
|
readonly plugins: readonly CLIPlugin[];
|
|
102
110
|
}
|
|
@@ -145,6 +153,17 @@ interface HelpConfig {
|
|
|
145
153
|
readonly width?: number;
|
|
146
154
|
/** Emit OSC 8 hyperlinks in the header when supported. */
|
|
147
155
|
readonly hyperlinks?: boolean;
|
|
156
|
+
/**
|
|
157
|
+
* Theme overrides for help output, merged over the built-in theme.
|
|
158
|
+
*
|
|
159
|
+
* The factory receives the gated ansispeck palette (same instance as
|
|
160
|
+
* `out.color`), so overrides follow the output channel's color policy.
|
|
161
|
+
* It is never invoked when color is off — themed help cannot leak escapes
|
|
162
|
+
* into piped, `--json`, or `NO_COLOR` output.
|
|
163
|
+
*
|
|
164
|
+
* @defaultValue `undefined` (built-in theme)
|
|
165
|
+
*/
|
|
166
|
+
readonly theme?: HelpThemeFactory;
|
|
148
167
|
}
|
|
149
168
|
/**
|
|
150
169
|
* Config discovery settings for automatic config file loading.
|
|
@@ -754,6 +773,12 @@ interface CLIOptions {
|
|
|
754
773
|
* @defaultValue `false`
|
|
755
774
|
*/
|
|
756
775
|
readonly inherit?: boolean;
|
|
776
|
+
/**
|
|
777
|
+
* Flag-parsing behavior settings (e.g. `{ caseParity: false }` to accept
|
|
778
|
+
* only declared flag spellings). Shares the {@link ParseOptions} contract
|
|
779
|
+
* used by `parse()` and `RunOptions.flags`.
|
|
780
|
+
*/
|
|
781
|
+
readonly flags?: ParseOptions;
|
|
757
782
|
}
|
|
758
783
|
/**
|
|
759
784
|
* Create a new CLI program builder.
|
|
@@ -774,7 +799,7 @@ interface CLIOptions {
|
|
|
774
799
|
* .run();
|
|
775
800
|
* ```
|
|
776
801
|
*/
|
|
777
|
-
declare function cli(name: string): CLIBuilder;
|
|
802
|
+
declare function cli(name: string, options?: Omit<CLIOptions, 'name'>): CLIBuilder;
|
|
778
803
|
/** Create a new CLI program builder from an options object. */
|
|
779
804
|
declare function cli(options: CLIOptions): CLIBuilder;
|
|
780
805
|
//#endregion
|
package/dist/core/cli/index.mjs
CHANGED
|
@@ -1,18 +1,18 @@
|
|
|
1
|
-
import { getFlagAliasNames } from "../schema/flag.mjs";
|
|
2
1
|
import { CLIError } from "../errors/index.mjs";
|
|
3
|
-
import {
|
|
4
|
-
import { formatHelp } from "../help/index.mjs";
|
|
5
|
-
import { clearRequestedExitCode, createCaptureOutput, createOutput } from "../output/index.mjs";
|
|
2
|
+
import { getFlagAliasNames } from "../schema/flag.mjs";
|
|
6
3
|
import { arg } from "../schema/arg.mjs";
|
|
7
4
|
import { command } from "../schema/command.mjs";
|
|
8
5
|
import { includesBeforeSeparator } from "../parse/index.mjs";
|
|
6
|
+
import { SHELLS, detectShell, generateCompletion, normalizeShell } from "../completion/index.mjs";
|
|
7
|
+
import { formatHelp } from "../help/index.mjs";
|
|
8
|
+
import { clearRequestedExitCode, createCaptureOutput, createOutput } from "../output/index.mjs";
|
|
9
9
|
import { buildRunResult, executeCommand } from "../execution/index.mjs";
|
|
10
10
|
import { runCommand } from "../testkit/index.mjs";
|
|
11
11
|
import { stripTrailing } from "../../strings.mjs";
|
|
12
12
|
import { createAdapter } from "../../runtime/auto.mjs";
|
|
13
13
|
import { deriveHelpLinks } from "./help-links.mjs";
|
|
14
14
|
import { planInvocation } from "./planner.mjs";
|
|
15
|
-
import "./plugin.mjs";
|
|
15
|
+
import { plugin } from "./plugin.mjs";
|
|
16
16
|
import { formatRootHelp } from "./root-help.mjs";
|
|
17
17
|
import { prepareRuntimePreflight } from "./runtime-preflight.mjs";
|
|
18
18
|
//#region src/core/cli/index.ts
|
|
@@ -119,11 +119,13 @@ function buildCommandRunOptions(options, helpOptions, meta) {
|
|
|
119
119
|
...options?.stdinData !== void 0 ? { stdinData: options.stdinData } : {},
|
|
120
120
|
...options?.prompter !== void 0 ? { prompter: options.prompter } : {},
|
|
121
121
|
...options?.answers !== void 0 ? { answers: options.answers } : {},
|
|
122
|
+
...options?.stat !== void 0 ? { stat: options.stat } : {},
|
|
122
123
|
...options?.verbosity !== void 0 ? { verbosity: options.verbosity } : {},
|
|
123
124
|
...options?.jsonMode !== void 0 ? { jsonMode: options.jsonMode } : {},
|
|
124
125
|
...options?.isTTY !== void 0 ? { isTTY: options.isTTY } : {},
|
|
125
126
|
...options?.out !== void 0 ? { out: options.out } : {},
|
|
126
|
-
...options?.captured !== void 0 ? { captured: options.captured } : {}
|
|
127
|
+
...options?.captured !== void 0 ? { captured: options.captured } : {},
|
|
128
|
+
...options?.flags !== void 0 ? { flags: options.flags } : {}
|
|
127
129
|
};
|
|
128
130
|
}
|
|
129
131
|
/**
|
|
@@ -513,8 +515,9 @@ var CLIBuilder = class CLIBuilder {
|
|
|
513
515
|
});
|
|
514
516
|
else out.log(script);
|
|
515
517
|
});
|
|
518
|
+
const withCompletions = this.command(cmd);
|
|
516
519
|
return new CLIBuilder({
|
|
517
|
-
...
|
|
520
|
+
...withCompletions.schema,
|
|
518
521
|
hasBuiltInCompletions: true
|
|
519
522
|
});
|
|
520
523
|
}
|
|
@@ -551,12 +554,15 @@ var CLIBuilder = class CLIBuilder {
|
|
|
551
554
|
...this.schema.helpConfig,
|
|
552
555
|
...options?.help,
|
|
553
556
|
binName: options?.help?.binName ?? this.schema.name,
|
|
554
|
-
hyperlinks: options?.help?.hyperlinks ?? this.schema.helpConfig?.hyperlinks ?? out.isTTY
|
|
557
|
+
hyperlinks: options?.help?.hyperlinks ?? this.schema.helpConfig?.hyperlinks ?? out.isTTY,
|
|
558
|
+
colors: options?.help?.colors ?? out.color
|
|
555
559
|
};
|
|
560
|
+
const flagSettings = options?.flags ?? this.schema.flagSettings;
|
|
556
561
|
const effectiveOptions = {
|
|
557
562
|
...options,
|
|
558
563
|
plugins: this.schema.plugins,
|
|
559
|
-
...jsonMode ? { jsonMode } : {}
|
|
564
|
+
...jsonMode ? { jsonMode } : {},
|
|
565
|
+
...flagSettings !== void 0 ? { flags: flagSettings } : {}
|
|
560
566
|
};
|
|
561
567
|
const output = {
|
|
562
568
|
jsonMode,
|
|
@@ -564,7 +570,10 @@ var CLIBuilder = class CLIBuilder {
|
|
|
564
570
|
verbosity: options?.verbosity ?? "normal"
|
|
565
571
|
};
|
|
566
572
|
const planned = planInvocation({
|
|
567
|
-
schema:
|
|
573
|
+
schema: options?.flags !== void 0 ? {
|
|
574
|
+
...this.schema,
|
|
575
|
+
flagSettings
|
|
576
|
+
} : this.schema,
|
|
568
577
|
argv,
|
|
569
578
|
help: helpOptions,
|
|
570
579
|
output
|
|
@@ -904,10 +913,14 @@ function isPackageJsonData(value) {
|
|
|
904
913
|
if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
|
|
905
914
|
return "name" in value || "version" in value || "description" in value || "bin" in value || "homepage" in value || "repository" in value;
|
|
906
915
|
}
|
|
907
|
-
function cli(nameOrOptions) {
|
|
916
|
+
function cli(nameOrOptions, extraOptions) {
|
|
917
|
+
const options = typeof nameOrOptions === "string" ? {
|
|
918
|
+
name: nameOrOptions,
|
|
919
|
+
...extraOptions
|
|
920
|
+
} : nameOrOptions;
|
|
908
921
|
return new CLIBuilder({
|
|
909
|
-
name:
|
|
910
|
-
inheritName:
|
|
922
|
+
name: options.name ?? "cli",
|
|
923
|
+
inheritName: options.inherit ?? false,
|
|
911
924
|
version: void 0,
|
|
912
925
|
description: void 0,
|
|
913
926
|
commands: [],
|
|
@@ -919,8 +932,9 @@ function cli(nameOrOptions) {
|
|
|
919
932
|
hasBuiltInCompletions: false,
|
|
920
933
|
completionsFlag: void 0,
|
|
921
934
|
helpConfig: void 0,
|
|
935
|
+
flagSettings: options.flags,
|
|
922
936
|
plugins: []
|
|
923
937
|
});
|
|
924
938
|
}
|
|
925
939
|
//#endregion
|
|
926
|
-
export { CLIBuilder, cli };
|
|
940
|
+
export { CLIBuilder, cli, formatRootHelp, plugin };
|
|
@@ -3,9 +3,9 @@ import { CLIPlugin } from "./plugin.mjs";
|
|
|
3
3
|
import { CLIError } from "../errors/index.mjs";
|
|
4
4
|
import { HelpOptions } from "../help/index.mjs";
|
|
5
5
|
import { CommandMeta, CommandSchema, ErasedCommand } from "../schema/command.mjs";
|
|
6
|
+
import { ParseOptions } from "../parse/index.mjs";
|
|
6
7
|
import { CompletionOptions } from "../completion/shells/shared.mjs";
|
|
7
8
|
import { Shell } from "../completion/index.mjs";
|
|
8
|
-
|
|
9
9
|
//#region src/core/cli/planner.d.ts
|
|
10
10
|
/**
|
|
11
11
|
* Structural subset of CLISchema used by the planner.
|
|
@@ -33,6 +33,8 @@ interface PlannerSchemaLike {
|
|
|
33
33
|
readonly shells: readonly Shell[];
|
|
34
34
|
readonly options: CompletionOptions | undefined;
|
|
35
35
|
} | undefined;
|
|
36
|
+
/** Flag-parsing behavior settings (case parity) applied to flag lookups. */
|
|
37
|
+
readonly flagSettings?: ParseOptions | undefined;
|
|
36
38
|
/** Plugins forwarded into every matched execution plan. */
|
|
37
39
|
readonly plugins: readonly CLIPlugin[];
|
|
38
40
|
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import { collectPropagatedFlags } from "./propagate.mjs";
|
|
2
1
|
import { CLIError, ParseError } from "../errors/index.mjs";
|
|
3
|
-
import { normalizeShell } from "../completion/index.mjs";
|
|
4
2
|
import { buildFlagLookup, flagExpectsValue, includesBeforeSeparator } from "../parse/index.mjs";
|
|
3
|
+
import { collectPropagatedFlags } from "./propagate.mjs";
|
|
4
|
+
import { normalizeShell } from "../completion/index.mjs";
|
|
5
5
|
import { dispatch, findClosestCommand } from "./dispatch.mjs";
|
|
6
6
|
//#region src/core/cli/planner.ts
|
|
7
7
|
function buildMeta(schema, helpOptions, commandName) {
|
|
@@ -75,8 +75,8 @@ function buildPlannerMatchOutcome(schema, command, commandPath, argv, help, outp
|
|
|
75
75
|
function canDelegateUnknownRootToDefault(command, input) {
|
|
76
76
|
return input === "" || command.schema.args.length > 0;
|
|
77
77
|
}
|
|
78
|
-
function findUnknownFlagBeforePositional(argv, flags) {
|
|
79
|
-
const lookup = buildFlagLookup(flags);
|
|
78
|
+
function findUnknownFlagBeforePositional(argv, flags, parseOptions) {
|
|
79
|
+
const lookup = buildFlagLookup(flags, parseOptions);
|
|
80
80
|
for (let index = 0; index < argv.length; index++) {
|
|
81
81
|
const token = argv[index];
|
|
82
82
|
if (token === void 0 || token === "--") return void 0;
|
|
@@ -86,7 +86,7 @@ function findUnknownFlagBeforePositional(argv, flags) {
|
|
|
86
86
|
const name = token.slice(2, equalsIndex === -1 ? void 0 : equalsIndex);
|
|
87
87
|
const entry = lookup.get(name);
|
|
88
88
|
if (entry === void 0) return equalsIndex === -1 ? token : `--${name}`;
|
|
89
|
-
if (equalsIndex === -1 && flagExpectsValue(entry
|
|
89
|
+
if (equalsIndex === -1 && flagExpectsValue(entry.schema)) index++;
|
|
90
90
|
continue;
|
|
91
91
|
}
|
|
92
92
|
const chars = token.slice(1);
|
|
@@ -94,7 +94,7 @@ function findUnknownFlagBeforePositional(argv, flags) {
|
|
|
94
94
|
const char = chars.charAt(charIndex);
|
|
95
95
|
const entry = lookup.get(char);
|
|
96
96
|
if (entry === void 0) return `-${char}`;
|
|
97
|
-
if (!flagExpectsValue(entry
|
|
97
|
+
if (!flagExpectsValue(entry.schema)) continue;
|
|
98
98
|
if (charIndex === chars.length - 1) index++;
|
|
99
99
|
break;
|
|
100
100
|
}
|
|
@@ -128,13 +128,13 @@ function scanRootHead(head, valueFlags) {
|
|
|
128
128
|
const equalsIndex = token.indexOf("=");
|
|
129
129
|
const name = token.slice(2, equalsIndex === -1 ? void 0 : equalsIndex);
|
|
130
130
|
const entry = valueFlags?.get(name);
|
|
131
|
-
if (entry !== void 0 && equalsIndex === -1 && flagExpectsValue(entry
|
|
131
|
+
if (entry !== void 0 && equalsIndex === -1 && flagExpectsValue(entry.schema)) index++;
|
|
132
132
|
continue;
|
|
133
133
|
}
|
|
134
134
|
const chars = token.slice(1);
|
|
135
135
|
for (let charIndex = 0; charIndex < chars.length; charIndex++) {
|
|
136
136
|
const entry = valueFlags?.get(chars.charAt(charIndex));
|
|
137
|
-
if (entry === void 0 || !flagExpectsValue(entry
|
|
137
|
+
if (entry === void 0 || !flagExpectsValue(entry.schema)) continue;
|
|
138
138
|
if (charIndex === chars.length - 1) index++;
|
|
139
139
|
break;
|
|
140
140
|
}
|
|
@@ -205,7 +205,7 @@ function planInvocation(options) {
|
|
|
205
205
|
const filteredHead = head.includes("--json") ? head.filter((arg) => arg !== "--json") : head;
|
|
206
206
|
const filteredArgv = separatorIndex === -1 ? filteredHead : [...filteredHead, ...tail];
|
|
207
207
|
const defaultCommand = options.schema.defaultCommand;
|
|
208
|
-
const rootValueFlags = defaultCommand !== void 0 ? buildFlagLookup(defaultCommand.schema.flags) : void 0;
|
|
208
|
+
const rootValueFlags = defaultCommand !== void 0 ? buildFlagLookup(defaultCommand.schema.flags, options.schema.flagSettings) : void 0;
|
|
209
209
|
if (options.schema.version !== void 0 && (includesBeforeSeparator(options.argv, "--version") || includesBeforeSeparator(options.argv, "-V"))) return {
|
|
210
210
|
kind: "root-version",
|
|
211
211
|
version: options.schema.version
|
|
@@ -243,12 +243,12 @@ function planInvocation(options) {
|
|
|
243
243
|
kind: "root-help",
|
|
244
244
|
help: options.help
|
|
245
245
|
};
|
|
246
|
-
const result = dispatch(filteredArgv, buildRootCommandMap(defaultCommand !== void 0 && options.schema.defaultCommandRouted ? [...options.schema.commands, defaultCommand] : options.schema.commands), [], rootValueFlags);
|
|
246
|
+
const result = dispatch(filteredArgv, buildRootCommandMap(defaultCommand !== void 0 && options.schema.defaultCommandRouted ? [...options.schema.commands, defaultCommand] : options.schema.commands), [], rootValueFlags, options.schema.flagSettings);
|
|
247
247
|
switch (result.kind) {
|
|
248
248
|
case "unknown": {
|
|
249
249
|
if (defaultCommand !== void 0 && result.parentPath.length === 0) {
|
|
250
250
|
if ((result.input !== "" ? findClosestCommand(result.input, result.candidates) : void 0) === void 0 && canDelegateUnknownRootToDefault(defaultCommand, result.input)) return buildPlannerMatchOutcome(options.schema, defaultCommand, [defaultCommand.schema], filteredArgv, options.help, options.output);
|
|
251
|
-
const unknownFlag = findUnknownFlagBeforePositional(filteredArgv, defaultCommand.schema.flags);
|
|
251
|
+
const unknownFlag = findUnknownFlagBeforePositional(filteredArgv, defaultCommand.schema.flags, options.schema.flagSettings);
|
|
252
252
|
if (unknownFlag !== void 0) return {
|
|
253
253
|
kind: "dispatch-error",
|
|
254
254
|
error: new ParseError(`Unknown flag ${unknownFlag}`, {
|
|
@@ -297,4 +297,4 @@ function planInvocation(options) {
|
|
|
297
297
|
}
|
|
298
298
|
}
|
|
299
299
|
//#endregion
|
|
300
|
-
export { planInvocation };
|
|
300
|
+
export { buildCommandExecutionPlan, buildRootCommandMap, mergeCommandSchema, planInvocation };
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { DeprecationWarning } from "../resolve/contracts.mjs";
|
|
2
|
+
import "../resolve/index.mjs";
|
|
2
3
|
import { CommandMeta, CommandSchema, Out } from "../schema/command.mjs";
|
|
3
|
-
|
|
4
4
|
//#region src/core/cli/plugin.d.ts
|
|
5
5
|
/** Shared hook payload for a concrete command execution. */
|
|
6
6
|
interface PluginCommandContext {
|