@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
|
@@ -1 +1,705 @@
|
|
|
1
|
-
|
|
1
|
+
import { assertNumberConstraints } from "./number-constraints.mjs";
|
|
2
|
+
import { assertStringConstraints } from "./string-constraints.mjs";
|
|
3
|
+
import { parseBytesValue, parseDateValue, parseDurationValue, parseUrlValue } from "./value-parsers.mjs";
|
|
4
|
+
//#region src/core/schema/flag.ts
|
|
5
|
+
/**
|
|
6
|
+
* Flag schema builder with full type inference.
|
|
7
|
+
*
|
|
8
|
+
* Each factory (`flag.string()`, `flag.boolean()`, etc.) returns an immutable
|
|
9
|
+
* {@linkcode FlagBuilder} whose generic parameter tracks the value type and presence
|
|
10
|
+
* state. Chained modifiers (`.default()`, `.required()`, `.alias()`, …) return
|
|
11
|
+
* new builders with updated type-level and runtime state.
|
|
12
|
+
*
|
|
13
|
+
* @module dreamcli/core/schema/flag
|
|
14
|
+
*/
|
|
15
|
+
/**
|
|
16
|
+
* Normalise an alias input into a full {@link FlagAlias} object.
|
|
17
|
+
*
|
|
18
|
+
* @param alias - Raw alias name or structured alias object.
|
|
19
|
+
* @returns Normalised alias record.
|
|
20
|
+
*/
|
|
21
|
+
function normalizeFlagAlias(alias) {
|
|
22
|
+
if (typeof alias === "string") return {
|
|
23
|
+
name: alias,
|
|
24
|
+
hidden: false
|
|
25
|
+
};
|
|
26
|
+
return {
|
|
27
|
+
name: alias.name,
|
|
28
|
+
hidden: alias.hidden
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Normalise alias input into immutable alias records.
|
|
33
|
+
*
|
|
34
|
+
* @param aliases - Alias input values.
|
|
35
|
+
* @returns Normalised alias objects.
|
|
36
|
+
*/
|
|
37
|
+
function normalizeFlagAliases(aliases) {
|
|
38
|
+
return aliases.map(normalizeFlagAlias);
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* List alias names for a flag schema.
|
|
42
|
+
*
|
|
43
|
+
* @param schema - Flag schema whose aliases should be listed.
|
|
44
|
+
* @param options - Visibility and length filtering.
|
|
45
|
+
* @returns Alias names in registration order.
|
|
46
|
+
*/
|
|
47
|
+
function getFlagAliasNames(schema, options) {
|
|
48
|
+
const includeHidden = options?.includeHidden ?? false;
|
|
49
|
+
const kind = options?.kind ?? "all";
|
|
50
|
+
return schema.aliases.filter((alias) => includeHidden || !alias.hidden).filter((alias) => {
|
|
51
|
+
if (kind === "short") return alias.name.length === 1;
|
|
52
|
+
if (kind === "long") return alias.name.length > 1;
|
|
53
|
+
return true;
|
|
54
|
+
}).map((alias) => alias.name);
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Effective negated spelling for a flag, or `undefined` when not negatable.
|
|
58
|
+
*
|
|
59
|
+
* The builder cannot know its flag name, so a default (`no-<name>`) is
|
|
60
|
+
* synthesized here — everywhere the canonical name is known (parser, help,
|
|
61
|
+
* completions, collision validation).
|
|
62
|
+
*
|
|
63
|
+
* @param name - Canonical flag name.
|
|
64
|
+
* @param schema - Flag schema (read for {@link FlagNegation}).
|
|
65
|
+
* @returns The negated spelling without the `--` prefix.
|
|
66
|
+
*/
|
|
67
|
+
function getFlagNegatedName(name, schema) {
|
|
68
|
+
if (schema.negation === void 0) return void 0;
|
|
69
|
+
return schema.negation.alias ?? `no-${name}`;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Create a raw {@link FlagSchema} object with sensible defaults.
|
|
73
|
+
*
|
|
74
|
+
* Most consumers should prefer the higher-level {@link flag} factory,
|
|
75
|
+
* which returns an immutable {@link FlagBuilder} with type inference and
|
|
76
|
+
* safe modifier chaining. `createSchema()` is the low-level escape hatch
|
|
77
|
+
* for advanced schema composition, tests, or custom factories that need to
|
|
78
|
+
* work directly with the runtime descriptor.
|
|
79
|
+
*
|
|
80
|
+
* `overrides` are shallow-merged on top of the default shape, so callers are
|
|
81
|
+
* responsible for keeping the resulting schema internally consistent.
|
|
82
|
+
*
|
|
83
|
+
* @param kind - Discriminator for the value type this flag accepts.
|
|
84
|
+
* @param overrides - Partial {@link FlagSchema} fields merged onto defaults.
|
|
85
|
+
* @returns A fully populated {@link FlagSchema}.
|
|
86
|
+
*
|
|
87
|
+
* @example
|
|
88
|
+
* ```ts
|
|
89
|
+
* const schema = createSchema('enum', {
|
|
90
|
+
* enumValues: ['us', 'eu', 'ap'],
|
|
91
|
+
* description: 'Deployment region',
|
|
92
|
+
* });
|
|
93
|
+
* ```
|
|
94
|
+
*/
|
|
95
|
+
function createSchema(kind, overrides) {
|
|
96
|
+
const aliases = overrides?.aliases !== void 0 ? normalizeFlagAliases(overrides.aliases) : [];
|
|
97
|
+
const { aliases: _ignoredAliases, ...rest } = overrides ?? {};
|
|
98
|
+
return {
|
|
99
|
+
kind,
|
|
100
|
+
presence: "optional",
|
|
101
|
+
defaultValue: void 0,
|
|
102
|
+
envVar: void 0,
|
|
103
|
+
configPath: void 0,
|
|
104
|
+
description: void 0,
|
|
105
|
+
enumValues: void 0,
|
|
106
|
+
numberConstraints: void 0,
|
|
107
|
+
stringConstraints: void 0,
|
|
108
|
+
elementSchema: void 0,
|
|
109
|
+
separator: void 0,
|
|
110
|
+
unique: false,
|
|
111
|
+
pathChecks: void 0,
|
|
112
|
+
valueHint: void 0,
|
|
113
|
+
prompt: void 0,
|
|
114
|
+
parseFn: void 0,
|
|
115
|
+
deprecated: void 0,
|
|
116
|
+
propagate: false,
|
|
117
|
+
negation: void 0,
|
|
118
|
+
duplicates: "last",
|
|
119
|
+
...rest,
|
|
120
|
+
aliases
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* Immutable flag schema builder.
|
|
125
|
+
*
|
|
126
|
+
* The type parameter `C` is a phantom that tracks the value type and presence
|
|
127
|
+
* through the fluent chain. Each modifier returns a **new** builder — the
|
|
128
|
+
* original is never mutated.
|
|
129
|
+
*
|
|
130
|
+
* @example
|
|
131
|
+
* ```ts
|
|
132
|
+
* const port = flag.number().default(8080);
|
|
133
|
+
* type Port = InferFlag<typeof port>; // number
|
|
134
|
+
*
|
|
135
|
+
* const region = flag.enum(['us', 'eu', 'ap']);
|
|
136
|
+
* type Region = InferFlag<typeof region>; // 'us' | 'eu' | 'ap' | undefined
|
|
137
|
+
* ```
|
|
138
|
+
*/
|
|
139
|
+
var FlagBuilder = class FlagBuilder {
|
|
140
|
+
/** @internal Runtime schema descriptor. */
|
|
141
|
+
schema;
|
|
142
|
+
/**
|
|
143
|
+
* Create a flag builder from a pre-built schema descriptor.
|
|
144
|
+
*
|
|
145
|
+
* @param schema - Runtime descriptor seeding this builder's state.
|
|
146
|
+
*/
|
|
147
|
+
constructor(schema) {
|
|
148
|
+
this.schema = schema;
|
|
149
|
+
}
|
|
150
|
+
/**
|
|
151
|
+
* Provide a default value. The flag becomes "always present" — handlers
|
|
152
|
+
* will never see `undefined`.
|
|
153
|
+
*
|
|
154
|
+
* The generic constraint `V extends C['valueType']` ensures the default
|
|
155
|
+
* matches the flag's declared type.
|
|
156
|
+
*
|
|
157
|
+
* @param value - Fallback value used when no source provides one.
|
|
158
|
+
* @returns The builder (for chaining).
|
|
159
|
+
*
|
|
160
|
+
* @example
|
|
161
|
+
* ```ts
|
|
162
|
+
* flag.number().default(8080).describe('Port to listen on')
|
|
163
|
+
*
|
|
164
|
+
* // $ mycli serve → port = 8080
|
|
165
|
+
* // $ mycli serve --port 443 → port = 443
|
|
166
|
+
* ```
|
|
167
|
+
*/
|
|
168
|
+
default(value) {
|
|
169
|
+
return new FlagBuilder({
|
|
170
|
+
...this.schema,
|
|
171
|
+
presence: "defaulted",
|
|
172
|
+
defaultValue: value
|
|
173
|
+
});
|
|
174
|
+
}
|
|
175
|
+
/**
|
|
176
|
+
* Mark the flag as required. If not resolved from any source the framework
|
|
177
|
+
* will emit a `ValidationError` before the action handler runs.
|
|
178
|
+
*
|
|
179
|
+
* @returns The builder (for chaining).
|
|
180
|
+
*
|
|
181
|
+
* @example
|
|
182
|
+
* ```ts
|
|
183
|
+
* flag.string().required().describe('Deploy target')
|
|
184
|
+
*
|
|
185
|
+
* // $ mycli deploy
|
|
186
|
+
* // # → Error: Missing required flag --target
|
|
187
|
+
* // $ mycli deploy --target staging
|
|
188
|
+
* // # → target = 'staging'
|
|
189
|
+
* ```
|
|
190
|
+
*/
|
|
191
|
+
required() {
|
|
192
|
+
return new FlagBuilder({
|
|
193
|
+
...this.schema,
|
|
194
|
+
presence: "required"
|
|
195
|
+
});
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* Add a short or long alias (e.g. `'f'` for `--force`, `'verbose'` as an
|
|
199
|
+
* alternative long name).
|
|
200
|
+
*
|
|
201
|
+
* @param name - Single-char short alias or alternative long name.
|
|
202
|
+
* @param options - Optional alias metadata. Hidden aliases remain parseable
|
|
203
|
+
* but are omitted from help, completions, and suggestions.
|
|
204
|
+
* @returns The builder (for chaining).
|
|
205
|
+
*
|
|
206
|
+
* @example
|
|
207
|
+
* ```ts
|
|
208
|
+
* flag.boolean().alias('v').describe('Enable verbose output')
|
|
209
|
+
*
|
|
210
|
+
* // $ mycli build -v → verbose = true
|
|
211
|
+
* // $ mycli build --verbose → verbose = true
|
|
212
|
+
* ```
|
|
213
|
+
*/
|
|
214
|
+
alias(name, options) {
|
|
215
|
+
return new FlagBuilder({
|
|
216
|
+
...this.schema,
|
|
217
|
+
aliases: [...this.schema.aliases, {
|
|
218
|
+
name,
|
|
219
|
+
hidden: options?.hidden ?? false
|
|
220
|
+
}]
|
|
221
|
+
});
|
|
222
|
+
}
|
|
223
|
+
/**
|
|
224
|
+
* Bind to an environment variable (resolved in v0.2+).
|
|
225
|
+
*
|
|
226
|
+
* @param varName - Environment variable name (e.g. `'PORT'`).
|
|
227
|
+
* @returns The builder (for chaining).
|
|
228
|
+
*
|
|
229
|
+
* @example
|
|
230
|
+
* ```ts
|
|
231
|
+
* flag.string().env('API_KEY').describe('Service API key')
|
|
232
|
+
*
|
|
233
|
+
* // $ API_KEY=sk-123 mycli request → apiKey = 'sk-123'
|
|
234
|
+
* // $ mycli request --api-key sk-456 → apiKey = 'sk-456' (CLI wins)
|
|
235
|
+
* ```
|
|
236
|
+
*/
|
|
237
|
+
env(varName) {
|
|
238
|
+
return new FlagBuilder({
|
|
239
|
+
...this.schema,
|
|
240
|
+
envVar: varName
|
|
241
|
+
});
|
|
242
|
+
}
|
|
243
|
+
/**
|
|
244
|
+
* Bind to a dotted config path (resolved in v0.2+).
|
|
245
|
+
*
|
|
246
|
+
* @param path - Dotted config key (e.g. `'deploy.region'`).
|
|
247
|
+
* @returns The builder (for chaining).
|
|
248
|
+
*
|
|
249
|
+
* @example
|
|
250
|
+
* ```ts
|
|
251
|
+
* flag.string().config('deploy.region').default('us-east-1')
|
|
252
|
+
* // Config file: { "deploy": { "region": "eu-west-1" } }
|
|
253
|
+
* // $ mycli deploy
|
|
254
|
+
* // # → region = 'eu-west-1' (from config)
|
|
255
|
+
* // $ mycli deploy --region ap-south-1
|
|
256
|
+
* // # → CLI flag wins
|
|
257
|
+
* ```
|
|
258
|
+
*/
|
|
259
|
+
config(path) {
|
|
260
|
+
return new FlagBuilder({
|
|
261
|
+
...this.schema,
|
|
262
|
+
configPath: path
|
|
263
|
+
});
|
|
264
|
+
}
|
|
265
|
+
/**
|
|
266
|
+
* Human-readable description shown in help output.
|
|
267
|
+
*
|
|
268
|
+
* @param description - Text displayed next to the flag in `--help`.
|
|
269
|
+
* @returns The builder (for chaining).
|
|
270
|
+
*/
|
|
271
|
+
describe(description) {
|
|
272
|
+
return new FlagBuilder({
|
|
273
|
+
...this.schema,
|
|
274
|
+
description
|
|
275
|
+
});
|
|
276
|
+
}
|
|
277
|
+
/**
|
|
278
|
+
* Attach interactive prompt configuration for v0.3+ resolution.
|
|
279
|
+
*
|
|
280
|
+
* When a flag value is not resolved from CLI, env, or config, the
|
|
281
|
+
* prompt engine uses this config to interactively ask the user.
|
|
282
|
+
* In non-interactive contexts (CI, piped stdin) prompts are skipped
|
|
283
|
+
* and resolution falls through to default or required validation.
|
|
284
|
+
*
|
|
285
|
+
* @param config - {@link PromptConfig} describing the interactive prompt.
|
|
286
|
+
* @returns The builder (for chaining).
|
|
287
|
+
*
|
|
288
|
+
* @example
|
|
289
|
+
* ```ts
|
|
290
|
+
* flag.string().prompt({ kind: 'input', message: 'Enter value:' })
|
|
291
|
+
*
|
|
292
|
+
* // $ mycli init → prompts "Enter value:" interactively
|
|
293
|
+
* // $ mycli init --name foo → skips prompt, uses CLI value
|
|
294
|
+
* ```
|
|
295
|
+
*/
|
|
296
|
+
prompt(config) {
|
|
297
|
+
return new FlagBuilder({
|
|
298
|
+
...this.schema,
|
|
299
|
+
prompt: config
|
|
300
|
+
});
|
|
301
|
+
}
|
|
302
|
+
/**
|
|
303
|
+
* Mark this flag as deprecated.
|
|
304
|
+
*
|
|
305
|
+
* When used, a warning is emitted to stderr. Help text shows
|
|
306
|
+
* `[deprecated]` or `[deprecated: <reason>]`.
|
|
307
|
+
*
|
|
308
|
+
* Does not change the flag's type-level config — it's metadata only.
|
|
309
|
+
*
|
|
310
|
+
* @param message - Optional migration reason/guidance.
|
|
311
|
+
* @returns The builder (for chaining).
|
|
312
|
+
*
|
|
313
|
+
* @example
|
|
314
|
+
* ```ts
|
|
315
|
+
* flag.string().deprecated('Use --target instead')
|
|
316
|
+
*
|
|
317
|
+
* // $ mycli deploy --dest staging
|
|
318
|
+
* // ⚠ --dest is deprecated: Use --target instead
|
|
319
|
+
* ```
|
|
320
|
+
*/
|
|
321
|
+
deprecated(message) {
|
|
322
|
+
return new FlagBuilder({
|
|
323
|
+
...this.schema,
|
|
324
|
+
deprecated: message ?? true
|
|
325
|
+
});
|
|
326
|
+
}
|
|
327
|
+
/**
|
|
328
|
+
* Mark this flag as propagated to subcommands.
|
|
329
|
+
*
|
|
330
|
+
* Propagated flags are automatically available to all descendant
|
|
331
|
+
* commands in a nested command tree. A child command that defines
|
|
332
|
+
* a flag with the same name shadows the propagated parent flag.
|
|
333
|
+
*
|
|
334
|
+
* Does not change the flag's type-level config — it's metadata only.
|
|
335
|
+
*
|
|
336
|
+
* @returns The builder (for chaining).
|
|
337
|
+
*
|
|
338
|
+
* @example
|
|
339
|
+
* ```ts
|
|
340
|
+
* flag.boolean().alias('v').propagate().describe('Enable verbose output')
|
|
341
|
+
*
|
|
342
|
+
* // $ mycli --verbose deploy staging
|
|
343
|
+
* // # → verbose = true in deploy handler
|
|
344
|
+
* // $ mycli deploy --verbose staging
|
|
345
|
+
* // # → same, inherited from parent
|
|
346
|
+
* ```
|
|
347
|
+
*/
|
|
348
|
+
propagate() {
|
|
349
|
+
return new FlagBuilder({
|
|
350
|
+
...this.schema,
|
|
351
|
+
propagate: true
|
|
352
|
+
});
|
|
353
|
+
}
|
|
354
|
+
/**
|
|
355
|
+
* Require an integer value. Composes with other numeric constraints.
|
|
356
|
+
*
|
|
357
|
+
* @param value - Whether to require an integer.
|
|
358
|
+
* @defaultValue `true`
|
|
359
|
+
* @returns The builder (for chaining).
|
|
360
|
+
*
|
|
361
|
+
* @example
|
|
362
|
+
* ```ts
|
|
363
|
+
* flag.number().int() // rejects 3.7, accepts 3
|
|
364
|
+
* flag.number({ int: true }).int(false) // re-allows non-integers
|
|
365
|
+
* ```
|
|
366
|
+
*/
|
|
367
|
+
int(value = true) {
|
|
368
|
+
return new FlagBuilder({
|
|
369
|
+
...this.schema,
|
|
370
|
+
numberConstraints: {
|
|
371
|
+
...this.schema.numberConstraints,
|
|
372
|
+
int: value
|
|
373
|
+
}
|
|
374
|
+
});
|
|
375
|
+
}
|
|
376
|
+
/**
|
|
377
|
+
* Set an inclusive lower bound. Composes with other numeric constraints;
|
|
378
|
+
* a later call overrides an earlier `min` (including one from the options
|
|
379
|
+
* object).
|
|
380
|
+
*
|
|
381
|
+
* @param value - Inclusive minimum.
|
|
382
|
+
* @returns The builder (for chaining).
|
|
383
|
+
*
|
|
384
|
+
* @example
|
|
385
|
+
* ```ts
|
|
386
|
+
* flag.number().min(0) // rejects -1, accepts 0
|
|
387
|
+
* flag.number({ min: 0 }).min(5) // effective min is 5
|
|
388
|
+
* ```
|
|
389
|
+
*/
|
|
390
|
+
min(value) {
|
|
391
|
+
const numberConstraints = {
|
|
392
|
+
...this.schema.numberConstraints,
|
|
393
|
+
min: value
|
|
394
|
+
};
|
|
395
|
+
assertNumberConstraints(numberConstraints);
|
|
396
|
+
return new FlagBuilder({
|
|
397
|
+
...this.schema,
|
|
398
|
+
numberConstraints
|
|
399
|
+
});
|
|
400
|
+
}
|
|
401
|
+
/**
|
|
402
|
+
* Set an inclusive upper bound. Composes with other numeric constraints;
|
|
403
|
+
* a later call overrides an earlier `max`.
|
|
404
|
+
*
|
|
405
|
+
* @param value - Inclusive maximum.
|
|
406
|
+
* @returns The builder (for chaining).
|
|
407
|
+
*
|
|
408
|
+
* @example
|
|
409
|
+
* ```ts
|
|
410
|
+
* flag.number().max(100) // rejects 101, accepts 100
|
|
411
|
+
* ```
|
|
412
|
+
*/
|
|
413
|
+
max(value) {
|
|
414
|
+
const numberConstraints = {
|
|
415
|
+
...this.schema.numberConstraints,
|
|
416
|
+
max: value
|
|
417
|
+
};
|
|
418
|
+
assertNumberConstraints(numberConstraints);
|
|
419
|
+
return new FlagBuilder({
|
|
420
|
+
...this.schema,
|
|
421
|
+
numberConstraints
|
|
422
|
+
});
|
|
423
|
+
}
|
|
424
|
+
/**
|
|
425
|
+
* Require (or, with `false`, allow) a finite value. Finiteness is enforced
|
|
426
|
+
* by default, so this is mainly used as `.finite(false)` to re-allow
|
|
427
|
+
* `Infinity` / `-Infinity`.
|
|
428
|
+
*
|
|
429
|
+
* @param allow - Whether to require a finite value.
|
|
430
|
+
* @defaultValue `true`
|
|
431
|
+
* @returns The builder (for chaining).
|
|
432
|
+
*
|
|
433
|
+
* @example
|
|
434
|
+
* ```ts
|
|
435
|
+
* flag.number().finite(false) // accepts Infinity
|
|
436
|
+
* ```
|
|
437
|
+
*/
|
|
438
|
+
finite(allow = true) {
|
|
439
|
+
return new FlagBuilder({
|
|
440
|
+
...this.schema,
|
|
441
|
+
numberConstraints: {
|
|
442
|
+
...this.schema.numberConstraints,
|
|
443
|
+
finite: allow
|
|
444
|
+
}
|
|
445
|
+
});
|
|
446
|
+
}
|
|
447
|
+
/**
|
|
448
|
+
* Reject empty strings. Composes with other string constraints.
|
|
449
|
+
*
|
|
450
|
+
* @param value - Whether to reject empty strings.
|
|
451
|
+
* @defaultValue `true`
|
|
452
|
+
* @returns The builder (for chaining).
|
|
453
|
+
*
|
|
454
|
+
* @example
|
|
455
|
+
* ```ts
|
|
456
|
+
* flag.string().nonEmpty() // rejects '', accepts 'x'
|
|
457
|
+
* ```
|
|
458
|
+
*/
|
|
459
|
+
nonEmpty(value = true) {
|
|
460
|
+
return new FlagBuilder({
|
|
461
|
+
...this.schema,
|
|
462
|
+
stringConstraints: {
|
|
463
|
+
...this.schema.stringConstraints,
|
|
464
|
+
nonEmpty: value
|
|
465
|
+
}
|
|
466
|
+
});
|
|
467
|
+
}
|
|
468
|
+
/**
|
|
469
|
+
* Set an inclusive minimum length (UTF-16 code units). Composes with other
|
|
470
|
+
* string constraints; a later call overrides an earlier `minLength`.
|
|
471
|
+
*
|
|
472
|
+
* @param value - Inclusive minimum length.
|
|
473
|
+
* @returns The builder (for chaining).
|
|
474
|
+
*
|
|
475
|
+
* @example
|
|
476
|
+
* ```ts
|
|
477
|
+
* flag.string().minLength(3) // rejects 'ab', accepts 'abc'
|
|
478
|
+
* ```
|
|
479
|
+
*/
|
|
480
|
+
minLength(value) {
|
|
481
|
+
const stringConstraints = {
|
|
482
|
+
...this.schema.stringConstraints,
|
|
483
|
+
minLength: value
|
|
484
|
+
};
|
|
485
|
+
assertStringConstraints(stringConstraints);
|
|
486
|
+
return new FlagBuilder({
|
|
487
|
+
...this.schema,
|
|
488
|
+
stringConstraints
|
|
489
|
+
});
|
|
490
|
+
}
|
|
491
|
+
/**
|
|
492
|
+
* Set an inclusive maximum length (UTF-16 code units). Composes with other
|
|
493
|
+
* string constraints; a later call overrides an earlier `maxLength`.
|
|
494
|
+
*
|
|
495
|
+
* @param value - Inclusive maximum length.
|
|
496
|
+
* @returns The builder (for chaining).
|
|
497
|
+
*
|
|
498
|
+
* @example
|
|
499
|
+
* ```ts
|
|
500
|
+
* flag.string().maxLength(8) // rejects 9+ chars
|
|
501
|
+
* ```
|
|
502
|
+
*/
|
|
503
|
+
maxLength(value) {
|
|
504
|
+
const stringConstraints = {
|
|
505
|
+
...this.schema.stringConstraints,
|
|
506
|
+
maxLength: value
|
|
507
|
+
};
|
|
508
|
+
assertStringConstraints(stringConstraints);
|
|
509
|
+
return new FlagBuilder({
|
|
510
|
+
...this.schema,
|
|
511
|
+
stringConstraints
|
|
512
|
+
});
|
|
513
|
+
}
|
|
514
|
+
/**
|
|
515
|
+
* Require the value to match a regular expression. Anchor with `^`/`$`
|
|
516
|
+
* for full-string matching. Composes with other string constraints.
|
|
517
|
+
*
|
|
518
|
+
* @param value - Pattern the value must match.
|
|
519
|
+
* @returns The builder (for chaining).
|
|
520
|
+
*
|
|
521
|
+
* @example
|
|
522
|
+
* ```ts
|
|
523
|
+
* flag.string().pattern(/^ghp_/) // rejects 'abc', accepts 'ghp_x'
|
|
524
|
+
* ```
|
|
525
|
+
*/
|
|
526
|
+
pattern(value) {
|
|
527
|
+
return new FlagBuilder({
|
|
528
|
+
...this.schema,
|
|
529
|
+
stringConstraints: {
|
|
530
|
+
...this.schema.stringConstraints,
|
|
531
|
+
pattern: value
|
|
532
|
+
}
|
|
533
|
+
});
|
|
534
|
+
}
|
|
535
|
+
/**
|
|
536
|
+
* Split each CLI occurrence on a separator before element coercion, so
|
|
537
|
+
* `--tag a,b --tag c` resolves to `['a', 'b', 'c']`. Elements are coerced
|
|
538
|
+
* (and rejected) individually with the element schema's own error format.
|
|
539
|
+
*
|
|
540
|
+
* Env and config string values are split on the same separator (their
|
|
541
|
+
* default split is `','` even without this modifier).
|
|
542
|
+
*
|
|
543
|
+
* @param value - Separator string (e.g. `','`).
|
|
544
|
+
* @returns The builder (for chaining).
|
|
545
|
+
*
|
|
546
|
+
* @example
|
|
547
|
+
* ```ts
|
|
548
|
+
* flag.array(flag.enum(['us', 'eu', 'ap'])).separator(',')
|
|
549
|
+
* // --region us,eu --region ap → ['us', 'eu', 'ap']
|
|
550
|
+
* ```
|
|
551
|
+
*/
|
|
552
|
+
separator(value) {
|
|
553
|
+
if (value.length === 0) throw new RangeError("array separator must not be empty");
|
|
554
|
+
return new FlagBuilder({
|
|
555
|
+
...this.schema,
|
|
556
|
+
separator: value
|
|
557
|
+
});
|
|
558
|
+
}
|
|
559
|
+
/**
|
|
560
|
+
* Deduplicate the resolved array, preserving first-seen order. Applied
|
|
561
|
+
* after all sources resolve, using `SameValueZero` semantics (like `Set`).
|
|
562
|
+
*
|
|
563
|
+
* @param value - Whether to deduplicate.
|
|
564
|
+
* @defaultValue `true`
|
|
565
|
+
* @returns The builder (for chaining).
|
|
566
|
+
*
|
|
567
|
+
* @example
|
|
568
|
+
* ```ts
|
|
569
|
+
* flag.array(flag.string()).separator(',').unique()
|
|
570
|
+
* // --tag a,a --tag a → ['a']
|
|
571
|
+
* ```
|
|
572
|
+
*/
|
|
573
|
+
unique(value = true) {
|
|
574
|
+
return new FlagBuilder({
|
|
575
|
+
...this.schema,
|
|
576
|
+
unique: value
|
|
577
|
+
});
|
|
578
|
+
}
|
|
579
|
+
/**
|
|
580
|
+
* Accept a negated spelling (`--no-<name>`) that sets the flag to `false`.
|
|
581
|
+
*
|
|
582
|
+
* Both spellings are ONE logical flag: the last CLI occurrence wins across
|
|
583
|
+
* them, and they share the duplicate policy. The negated spelling is
|
|
584
|
+
* presence-only — `--no-<name>=true` is rejected. Help renders the flag as
|
|
585
|
+
* `--[no-]<name>` (or lists a custom alias); env/config/prompt/default
|
|
586
|
+
* resolution is unaffected.
|
|
587
|
+
*
|
|
588
|
+
* @param options - Optional custom spelling (`alias`, without `--`) and
|
|
589
|
+
* `hidden` to keep the negated spelling parseable but unadvertised.
|
|
590
|
+
* @returns The builder (for chaining).
|
|
591
|
+
*
|
|
592
|
+
* @example
|
|
593
|
+
* ```ts
|
|
594
|
+
* flag.boolean().default(true).negatable()
|
|
595
|
+
* // $ mycli build --no-sandbox → sandbox = false
|
|
596
|
+
* // $ mycli build --sandbox → sandbox = true
|
|
597
|
+
* ```
|
|
598
|
+
*/
|
|
599
|
+
negatable(options) {
|
|
600
|
+
return new FlagBuilder({
|
|
601
|
+
...this.schema,
|
|
602
|
+
negation: {
|
|
603
|
+
alias: options?.alias,
|
|
604
|
+
hidden: options?.hidden ?? false
|
|
605
|
+
}
|
|
606
|
+
});
|
|
607
|
+
}
|
|
608
|
+
/**
|
|
609
|
+
* Set how repeated CLI occurrences of this flag combine.
|
|
610
|
+
*
|
|
611
|
+
* Counted per logical flag — aliases and the negated spelling all count
|
|
612
|
+
* toward the same flag. CLI tokens only: env/config/prompt/default
|
|
613
|
+
* resolution keeps its precedence semantics. Not available on `array`,
|
|
614
|
+
* `count`, or `keyValue` flags, which inherently accumulate.
|
|
615
|
+
*
|
|
616
|
+
* @param policy - `'last'` (default), `'first'`, or `'error'`.
|
|
617
|
+
* @returns The builder (for chaining).
|
|
618
|
+
*
|
|
619
|
+
* @example
|
|
620
|
+
* ```ts
|
|
621
|
+
* flag.enum(['session', 'same-dir', 'worktree']).duplicates('error')
|
|
622
|
+
* // $ mycli run --spawn session --spawn worktree
|
|
623
|
+
* // # → Error: Flag --spawn may only be specified once
|
|
624
|
+
* ```
|
|
625
|
+
*/
|
|
626
|
+
duplicates(policy) {
|
|
627
|
+
return new FlagBuilder({
|
|
628
|
+
...this.schema,
|
|
629
|
+
duplicates: policy
|
|
630
|
+
});
|
|
631
|
+
}
|
|
632
|
+
};
|
|
633
|
+
/**
|
|
634
|
+
* Flag schema factory. Call `flag.<kind>()` to create an immutable
|
|
635
|
+
* {@link FlagBuilder} with full type inference and safe modifier chaining.
|
|
636
|
+
*/
|
|
637
|
+
const flag = {
|
|
638
|
+
string(constraints) {
|
|
639
|
+
if (constraints !== void 0) assertStringConstraints(constraints);
|
|
640
|
+
return new FlagBuilder(createSchema("string", constraints !== void 0 ? { stringConstraints: constraints } : {}));
|
|
641
|
+
},
|
|
642
|
+
number(constraints) {
|
|
643
|
+
if (constraints !== void 0) assertNumberConstraints(constraints);
|
|
644
|
+
return new FlagBuilder(createSchema("number", constraints !== void 0 ? { numberConstraints: constraints } : {}));
|
|
645
|
+
},
|
|
646
|
+
boolean() {
|
|
647
|
+
return new FlagBuilder(createSchema("boolean", {
|
|
648
|
+
presence: "defaulted",
|
|
649
|
+
defaultValue: false
|
|
650
|
+
}));
|
|
651
|
+
},
|
|
652
|
+
enum(values) {
|
|
653
|
+
return new FlagBuilder(createSchema("enum", { enumValues: values }));
|
|
654
|
+
},
|
|
655
|
+
array(element) {
|
|
656
|
+
return new FlagBuilder(createSchema("array", { elementSchema: element.schema }));
|
|
657
|
+
},
|
|
658
|
+
custom(parseFn) {
|
|
659
|
+
return new FlagBuilder(createSchema("custom", { parseFn }));
|
|
660
|
+
},
|
|
661
|
+
url(options) {
|
|
662
|
+
return new FlagBuilder(createSchema("custom", {
|
|
663
|
+
parseFn: (raw) => parseUrlValue(raw, options),
|
|
664
|
+
valueHint: "url"
|
|
665
|
+
}));
|
|
666
|
+
},
|
|
667
|
+
path(options) {
|
|
668
|
+
return new FlagBuilder(createSchema("string", {
|
|
669
|
+
pathChecks: options?.mustExist === true || options?.type !== void 0 ? {
|
|
670
|
+
mustExist: options.mustExist ?? true,
|
|
671
|
+
type: options.type
|
|
672
|
+
} : void 0,
|
|
673
|
+
valueHint: "path"
|
|
674
|
+
}));
|
|
675
|
+
},
|
|
676
|
+
date(options) {
|
|
677
|
+
return new FlagBuilder(createSchema("custom", {
|
|
678
|
+
parseFn: (raw) => parseDateValue(raw, options),
|
|
679
|
+
valueHint: "date"
|
|
680
|
+
}));
|
|
681
|
+
},
|
|
682
|
+
duration() {
|
|
683
|
+
return new FlagBuilder(createSchema("custom", {
|
|
684
|
+
parseFn: parseDurationValue,
|
|
685
|
+
valueHint: "duration"
|
|
686
|
+
}));
|
|
687
|
+
},
|
|
688
|
+
bytes() {
|
|
689
|
+
return new FlagBuilder(createSchema("custom", {
|
|
690
|
+
parseFn: parseBytesValue,
|
|
691
|
+
valueHint: "size"
|
|
692
|
+
}));
|
|
693
|
+
},
|
|
694
|
+
count() {
|
|
695
|
+
return new FlagBuilder(createSchema("count", {
|
|
696
|
+
presence: "defaulted",
|
|
697
|
+
defaultValue: 0
|
|
698
|
+
}));
|
|
699
|
+
},
|
|
700
|
+
keyValue() {
|
|
701
|
+
return new FlagBuilder(createSchema("keyValue", { valueHint: "key=value" }));
|
|
702
|
+
}
|
|
703
|
+
};
|
|
704
|
+
//#endregion
|
|
705
|
+
export { FlagBuilder, createSchema, flag, getFlagAliasNames, getFlagNegatedName, normalizeFlagAlias, normalizeFlagAliases };
|