@kjanat/dreamcli 3.0.0 → 4.0.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +967 -1
- package/README.md +9 -3
- package/dist/core/cli/builtins.d.mts +47 -0
- package/dist/core/cli/builtins.mjs +135 -0
- package/dist/core/cli/compiled.d.mts +29 -0
- package/dist/core/cli/compiled.mjs +76 -0
- package/dist/core/cli/dispatch.d.mts +9 -85
- package/dist/core/cli/help-links.d.mts +2 -14
- package/dist/core/cli/index.d.mts +282 -101
- package/dist/core/cli/index.mjs +497 -264
- package/dist/core/cli/planner.d.mts +13 -86
- package/dist/core/cli/planner.mjs +47 -30
- package/dist/core/cli/plugin.d.mts +1 -1
- package/dist/core/cli/propagate.mjs +1 -1
- package/dist/core/cli/reserved-flags.d.mts +1 -0
- package/dist/core/cli/reserved-flags.mjs +158 -0
- package/dist/core/cli/root-help.d.mts +1 -47
- package/dist/core/cli/root-help.mjs +37 -47
- package/dist/core/cli/root-output-flags.d.mts +1 -0
- package/dist/core/cli/root-output-flags.mjs +169 -0
- package/dist/core/cli/root-surface.d.mts +1 -68
- package/dist/core/cli/root-surface.mjs +2 -2
- package/dist/core/cli/runtime-preflight.d.mts +1 -199
- package/dist/core/cli/runtime-preflight.mjs +67 -17
- package/dist/core/completion/index.d.mts +2 -2
- package/dist/core/completion/shells/bash.d.mts +0 -1
- package/dist/core/completion/shells/bash.mjs +2 -1
- package/dist/core/completion/shells/fish.d.mts +0 -1
- package/dist/core/completion/shells/fish.mjs +2 -1
- package/dist/core/completion/shells/powershell.d.mts +0 -1
- package/dist/core/completion/shells/powershell.mjs +2 -1
- package/dist/core/completion/shells/shared.d.mts +3 -114
- package/dist/core/completion/shells/shared.mjs +9 -39
- package/dist/core/completion/shells/zsh.d.mts +0 -1
- package/dist/core/completion/shells/zsh.mjs +2 -1
- package/dist/core/config/index.d.mts +3 -3
- package/dist/core/config/index.mjs +2 -2
- package/dist/core/config/package-json.d.mts +2 -33
- package/dist/core/config/package-json.mjs +1 -34
- package/dist/core/errors/index.d.mts +7 -7
- package/dist/core/execution/index.d.mts +1 -48
- package/dist/core/execution/index.mjs +42 -27
- package/dist/core/help/ansi.d.mts +0 -11
- package/dist/core/help/index.d.mts +3 -35
- package/dist/core/help/index.mjs +29 -6
- package/dist/core/help/theme.d.mts +1 -21
- package/dist/core/json-schema/index.d.mts +279 -10
- package/dist/core/json-schema/index.mjs +482 -237
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
- package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
- package/dist/core/output/activity.d.mts +1 -193
- package/dist/core/output/activity.mjs +1 -1
- package/dist/core/output/bind.d.mts +1 -37
- package/dist/core/output/contracts.d.mts +7 -13
- package/dist/core/output/contracts.mjs +1 -1
- package/dist/core/output/display-value.d.mts +1 -19
- package/dist/core/output/index.d.mts +5 -187
- package/dist/core/output/index.mjs +44 -9
- package/dist/core/output/renderers.d.mts +1 -45
- package/dist/core/output/writer.d.mts +0 -1
- package/dist/core/parse/index.d.mts +27 -5
- package/dist/core/parse/index.mjs +350 -227
- package/dist/core/parse/occurrences.d.mts +89 -0
- package/dist/core/parse/occurrences.mjs +114 -0
- package/dist/core/prompt/index.d.mts +3 -3
- package/dist/core/read-flags/index.d.mts +150 -0
- package/dist/core/read-flags/index.mjs +217 -0
- package/dist/core/resolve/args.d.mts +35 -4
- package/dist/core/resolve/args.mjs +132 -55
- package/dist/core/resolve/coerce.d.mts +66 -9
- package/dist/core/resolve/coerce.mjs +834 -270
- package/dist/core/resolve/config.d.mts +1 -10
- package/dist/core/resolve/contracts.d.mts +67 -44
- package/dist/core/resolve/errors.mjs +29 -21
- package/dist/core/resolve/flags.d.mts +36 -9
- package/dist/core/resolve/flags.mjs +129 -151
- package/dist/core/resolve/index.d.mts +8 -6
- package/dist/core/resolve/index.mjs +51 -18
- package/dist/core/resolve/path-checks.d.mts +47 -0
- package/dist/core/resolve/path-checks.mjs +102 -0
- package/dist/core/resolve/redaction.d.mts +12 -0
- package/dist/core/resolve/redaction.mjs +14 -0
- package/dist/core/resolve/stages.d.mts +85 -0
- package/dist/core/resolve/stages.mjs +170 -0
- package/dist/core/resolve/standard.d.mts +1 -24
- package/dist/core/resolve/standard.mjs +141 -43
- package/dist/core/schema/activity.d.mts +16 -16
- package/dist/core/schema/arg.d.mts +849 -71
- package/dist/core/schema/arg.mjs +727 -54
- package/dist/core/schema/brand.d.mts +17 -0
- package/dist/core/schema/cardinality.d.mts +301 -0
- package/dist/core/schema/cardinality.mjs +514 -0
- package/dist/core/schema/command.d.mts +181 -112
- package/dist/core/schema/command.mjs +305 -42
- package/dist/core/schema/flag.d.mts +515 -173
- package/dist/core/schema/flag.mjs +576 -78
- package/dist/core/schema/index.d.mts +11 -8
- package/dist/core/schema/index.mjs +10 -0
- package/dist/core/schema/middleware.d.mts +15 -12
- package/dist/core/schema/number-constraints.d.mts +5 -5
- package/dist/core/schema/prompt.d.mts +4 -4
- package/dist/core/schema/provenance.d.mts +99 -0
- package/dist/core/schema/provenance.mjs +28 -0
- package/dist/core/schema/run.d.mts +21 -60
- package/dist/core/schema/source.d.mts +179 -0
- package/dist/core/schema/source.mjs +206 -0
- package/dist/core/schema/standard.d.mts +12 -19
- package/dist/core/schema/stdin.d.mts +87 -0
- package/dist/core/schema/stdin.mjs +91 -0
- package/dist/core/schema/string-constraints.d.mts +16 -5
- package/dist/core/schema/string-constraints.mjs +18 -1
- package/dist/core/schema/value-parsers.d.mts +81 -9
- package/dist/core/schema/value-parsers.mjs +19 -1
- package/dist/core/schema/value.d.mts +242 -0
- package/dist/core/schema/value.mjs +573 -0
- package/dist/core/testkit/index.d.mts +28 -3
- package/dist/core/testkit/index.mjs +40 -26
- package/dist/index.d.mts +21 -16
- package/dist/index.mjs +10 -6
- package/dist/runtime/adapter.d.mts +3 -3
- package/dist/runtime/deno.d.mts +3 -3
- package/dist/runtime/detect.d.mts +2 -2
- package/dist/runtime/node.d.mts +3 -3
- package/dist/runtime/paths.d.mts +1 -31
- package/dist/runtime.d.mts +4 -4
- package/dist/strings.d.mts +1 -16
- package/dist/testkit.d.mts +2 -2
- package/dist/testkit.mjs +1 -1
- package/dist/version.d.mts +0 -13
- package/dist/version.mjs +2 -2
- package/dreamcli.schema.json +368 -78
- package/examples/interactive.ts +6 -5
- package/package.json +10 -9
- package/skills/cli-creation/SKILL.md +196 -0
- package/skills/cli-creation/agents/openai.yaml +4 -0
- package/skills/cli-creation/assets/templates/multi-command.bun-test.ts.tpl +20 -0
- package/skills/cli-creation/assets/templates/multi-command.test.ts.tpl +20 -0
- package/skills/cli-creation/assets/templates/multi-command.ts.tpl +89 -0
- package/skills/cli-creation/assets/templates/single-command.bun-test.ts.tpl +29 -0
- package/skills/cli-creation/assets/templates/single-command.test.ts.tpl +29 -0
- package/skills/cli-creation/assets/templates/single-command.ts.tpl +47 -0
- package/skills/cli-creation/references/consumer-workflow.md +65 -0
- package/skills/cli-creation/references/pattern-cookbook.md +451 -0
- package/skills/cli-creation/references/runtime-notes.md +29 -0
- package/skills/cli-creation/scripts/scaffold_cli.py +360 -0
- package/dist/core/resolve/property.d.mts +0 -51
- package/dist/core/resolve/property.mjs +0 -53
|
@@ -1,5 +1,11 @@
|
|
|
1
|
+
import { schemaBrand } from "./brand.mjs";
|
|
1
2
|
import { NumberConstraints } from "./number-constraints.mjs";
|
|
3
|
+
import { ConfirmPromptConfig, InputPromptConfig, MultiselectPromptConfig, PromptConfig, SelectPromptConfig } from "./prompt.mjs";
|
|
2
4
|
import { InferStandardOutput, StandardSchemaV1 } from "./standard.mjs";
|
|
5
|
+
import { StdinBinding, StdinConsume, StdinOptions, StdinWhen } from "./stdin.mjs";
|
|
6
|
+
import { StringConstraints } from "./string-constraints.mjs";
|
|
7
|
+
import { DateFlagOptions, PathChecks, PathFlagOptions, UrlFlagOptions } from "./value-parsers.mjs";
|
|
8
|
+
import { DuplicateKeys, SourceSplitBinding, SplitBinding, SplitFormat, SplitOptions, SplitPolicy, SplitSetting } from "./cardinality.mjs";
|
|
3
9
|
//#region src/core/schema/arg.d.ts
|
|
4
10
|
/** All arg presence states as a runtime array. */
|
|
5
11
|
declare const ARG_PRESENCES: readonly ["required", "optional", "defaulted"];
|
|
@@ -24,26 +30,62 @@ interface ArgConfig {
|
|
|
24
30
|
readonly variadic: boolean;
|
|
25
31
|
/** The runtime kind discriminator, mirroring {@link ArgKind}. */
|
|
26
32
|
readonly argKind: ArgKind;
|
|
33
|
+
/**
|
|
34
|
+
* Whether this builder may still be passed to `arg.keyValue()` as its entry
|
|
35
|
+
* value. Factories start `true`; the modifiers that describe the positional
|
|
36
|
+
* itself (`.env()`, `.prompt()`, `.optional()`, `.stdin()`, …) flip it to
|
|
37
|
+
* `false`, since an entry value is never read for those settings.
|
|
38
|
+
*/
|
|
39
|
+
readonly elementEligible: boolean;
|
|
27
40
|
}
|
|
28
41
|
/**
|
|
29
42
|
* Advanced type helper used by {@linkcode ArgBuilder} modifiers to replace presence.
|
|
30
43
|
* Most consumers rely on inference and never reference this directly.
|
|
31
44
|
*/
|
|
32
45
|
type WithArgPresence<C extends ArgConfig, P extends ArgPresence> = {
|
|
33
|
-
readonly valueType: C[
|
|
46
|
+
readonly valueType: C["valueType"];
|
|
34
47
|
readonly presence: P;
|
|
35
|
-
readonly variadic: C[
|
|
36
|
-
readonly argKind: C[
|
|
48
|
+
readonly variadic: C["variadic"];
|
|
49
|
+
readonly argKind: C["argKind"];
|
|
50
|
+
readonly elementEligible: false;
|
|
37
51
|
};
|
|
38
52
|
/**
|
|
39
53
|
* Advanced type helper used by {@linkcode ArgBuilder.variadic | ArgBuilder.variadic()}.
|
|
40
54
|
* Most consumers rely on inference and never reference this directly.
|
|
41
55
|
*/
|
|
42
56
|
type WithVariadic<C extends ArgConfig> = {
|
|
43
|
-
readonly valueType: C[
|
|
44
|
-
readonly presence: C[
|
|
57
|
+
readonly valueType: C["valueType"];
|
|
58
|
+
readonly presence: C["presence"];
|
|
45
59
|
readonly variadic: true;
|
|
46
|
-
readonly argKind: C[
|
|
60
|
+
readonly argKind: C["argKind"];
|
|
61
|
+
readonly elementEligible: false;
|
|
62
|
+
};
|
|
63
|
+
/**
|
|
64
|
+
* Advanced type helper: marks a builder as no longer usable as an entry value
|
|
65
|
+
* (returned by the modifiers whose settings an entry value ignores).
|
|
66
|
+
*/
|
|
67
|
+
type WithoutArgElementEligibility<C extends ArgConfig> = {
|
|
68
|
+
readonly valueType: C["valueType"];
|
|
69
|
+
readonly presence: C["presence"];
|
|
70
|
+
readonly variadic: C["variadic"];
|
|
71
|
+
readonly argKind: C["argKind"];
|
|
72
|
+
readonly elementEligible: false;
|
|
73
|
+
};
|
|
74
|
+
/**
|
|
75
|
+
* The element config `arg.keyValue()` assumes when given no element builder: an
|
|
76
|
+
* unconstrained string.
|
|
77
|
+
*/
|
|
78
|
+
type StringArgElementConfig = {
|
|
79
|
+
/** Element value type. */
|
|
80
|
+
readonly valueType: string;
|
|
81
|
+
/** Elements carry no presence of their own. */
|
|
82
|
+
readonly presence: "required";
|
|
83
|
+
/** Elements are never variadic on their own. */
|
|
84
|
+
readonly variadic: false;
|
|
85
|
+
/** Element kind discriminator. */
|
|
86
|
+
readonly argKind: "string";
|
|
87
|
+
/** Elements are element-eligible by construction. */
|
|
88
|
+
readonly elementEligible: true;
|
|
47
89
|
};
|
|
48
90
|
/**
|
|
49
91
|
* Compute the final value type from config — this is what handlers receive.
|
|
@@ -51,18 +93,53 @@ type WithVariadic<C extends ArgConfig> = {
|
|
|
51
93
|
* Advanced type helper: this powers {@link InferArg} and action-handler
|
|
52
94
|
* inference. Most apps do not need to mention it explicitly.
|
|
53
95
|
*
|
|
54
|
-
*
|
|
96
|
+
* A `keyValue` arg always produces a record, variadic or not, because it
|
|
97
|
+
* aggregates entries rather than a list. Variadic args of every other kind
|
|
98
|
+
* produce an array. Non-variadic:
|
|
55
99
|
* - `'optional'` → `T | undefined`
|
|
56
100
|
* - `'required'` → `T`
|
|
57
101
|
* - `'defaulted'` → `T`
|
|
58
102
|
*/
|
|
59
|
-
type ResolvedArgValue<C extends ArgConfig> = C[
|
|
103
|
+
type ResolvedArgValue<C extends ArgConfig> = C["argKind"] extends "keyValue" ? C["valueType"] : C["variadic"] extends true ? C["valueType"][] : C["presence"] extends "optional" ? C["valueType"] | undefined : C["valueType"];
|
|
104
|
+
/**
|
|
105
|
+
* The value `.default()` accepts for an arg.
|
|
106
|
+
*
|
|
107
|
+
* A default stands in for what the arg resolves to, so an arg that aggregates
|
|
108
|
+
* takes the completed array or record and every other arg takes one value.
|
|
109
|
+
*/
|
|
110
|
+
type ArgDefaultValue<C extends ArgConfig> = C["argKind"] extends "keyValue" ? C["valueType"] : C["variadic"] extends true ? readonly C["valueType"][] : C["valueType"];
|
|
111
|
+
/**
|
|
112
|
+
* Maps an {@linkcode ArgKind} to the prompt config types compatible with it,
|
|
113
|
+
* mirroring the flag table for the kinds args have.
|
|
114
|
+
*
|
|
115
|
+
* - `'string'` → {@link InputPromptConfig} | {@link SelectPromptConfig}
|
|
116
|
+
* - `'number'` → {@link InputPromptConfig}
|
|
117
|
+
* - `'boolean'` → {@link ConfirmPromptConfig}
|
|
118
|
+
* - `'enum'` → {@link SelectPromptConfig} | {@link InputPromptConfig}
|
|
119
|
+
* - `'custom'` → all prompt kinds ({@link PromptConfig})
|
|
120
|
+
* - `'keyValue'` → `never` (not promptable)
|
|
121
|
+
*/
|
|
122
|
+
type PromptConfigByArgKind = {
|
|
123
|
+
readonly string: InputPromptConfig | SelectPromptConfig;
|
|
124
|
+
readonly number: InputPromptConfig;
|
|
125
|
+
readonly boolean: ConfirmPromptConfig;
|
|
126
|
+
readonly enum: SelectPromptConfig | InputPromptConfig;
|
|
127
|
+
readonly custom: PromptConfig;
|
|
128
|
+
readonly keyValue: never;
|
|
129
|
+
};
|
|
130
|
+
/**
|
|
131
|
+
* Prompt configuration compatible with an {@link ArgConfig}.
|
|
132
|
+
*
|
|
133
|
+
* A variadic arg collects several values, so it takes the multiselect a
|
|
134
|
+
* `flag.array()` takes; every other arg takes what its kind takes.
|
|
135
|
+
*/
|
|
136
|
+
type AllowedArgPromptConfig<C extends ArgConfig> = C["argKind"] extends "keyValue" ? never : C["variadic"] extends true ? MultiselectPromptConfig : PromptConfigByArgKind[C["argKind"]];
|
|
60
137
|
/** Extract the resolved value type from an {@linkcode ArgBuilder}. */
|
|
61
138
|
type InferArg<B> = B extends ArgBuilder<infer C extends ArgConfig> ? ResolvedArgValue<C> : never;
|
|
62
139
|
/** Extract resolved value types from a record of builders. */
|
|
63
140
|
type InferArgs<T extends Record<string, ArgBuilder<ArgConfig>>> = { [K in keyof T]: InferArg<T[K]>; };
|
|
64
141
|
/** All arg kind discriminators as a runtime array. */
|
|
65
|
-
declare const ARG_KINDS: readonly ["string", "number", "enum", "custom"];
|
|
142
|
+
declare const ARG_KINDS: readonly ["string", "number", "boolean", "enum", "custom", "keyValue"];
|
|
66
143
|
/** Discriminator for the kind of value an arg accepts. */
|
|
67
144
|
type ArgKind = (typeof ARG_KINDS)[number];
|
|
68
145
|
/** Custom parse function for `arg.custom()`. */
|
|
@@ -72,18 +149,20 @@ type ArgParseFn<T> = (raw: string) => T;
|
|
|
72
149
|
* help generator) read this to understand the arg's shape without touching
|
|
73
150
|
* generics.
|
|
74
151
|
*/
|
|
75
|
-
interface ArgSchema {
|
|
152
|
+
interface ArgSchema<K extends ArgKind = ArgKind> {
|
|
153
|
+
/** Type-only seal produced by {@link createArgSchema}. */
|
|
154
|
+
readonly [schemaBrand]: "arg";
|
|
76
155
|
/** What kind of value this arg accepts. */
|
|
77
|
-
readonly kind:
|
|
156
|
+
readonly kind: K;
|
|
78
157
|
/** Current presence state. */
|
|
79
158
|
readonly presence: ArgPresence;
|
|
80
159
|
/** Whether this arg consumes all remaining positionals. */
|
|
81
160
|
readonly variadic: boolean;
|
|
82
161
|
/**
|
|
83
|
-
*
|
|
84
|
-
* @
|
|
162
|
+
* Stdin binding set by `.stdin()` (`undefined` when the arg never reads
|
|
163
|
+
* stdin). See {@link StdinBinding}.
|
|
85
164
|
*/
|
|
86
|
-
readonly
|
|
165
|
+
readonly stdin: StdinBinding | undefined;
|
|
87
166
|
/** Runtime default value (if any). */
|
|
88
167
|
readonly defaultValue: unknown;
|
|
89
168
|
/** Human-readable description for help text. */
|
|
@@ -97,8 +176,27 @@ interface ArgSchema {
|
|
|
97
176
|
* @see {@link ArgBuilder.env} for the builder method.
|
|
98
177
|
*/
|
|
99
178
|
readonly envVar: string | undefined;
|
|
179
|
+
/**
|
|
180
|
+
* Dotted config path for config resolution (e.g. `'deploy.region'`).
|
|
181
|
+
*
|
|
182
|
+
* @see {@link ArgBuilder.config} for the builder method.
|
|
183
|
+
*/
|
|
184
|
+
readonly configPath: string | undefined;
|
|
185
|
+
/**
|
|
186
|
+
* Interactive prompt configuration.
|
|
187
|
+
*
|
|
188
|
+
* @see {@link ArgBuilder.prompt} for the builder method.
|
|
189
|
+
*/
|
|
190
|
+
readonly prompt: PromptConfig | undefined;
|
|
100
191
|
/** Allowed literal values when `kind === 'enum'`. */
|
|
101
192
|
readonly enumValues: readonly string[] | undefined;
|
|
193
|
+
/**
|
|
194
|
+
* Element schema when `kind === 'keyValue'`.
|
|
195
|
+
*
|
|
196
|
+
* Describes the value of each entry, so `arg.keyValue(arg.number())` decodes
|
|
197
|
+
* `A=1` to the number `1`. `undefined` leaves entry values as strings.
|
|
198
|
+
*/
|
|
199
|
+
readonly elementSchema: ArgSchema | undefined;
|
|
102
200
|
/**
|
|
103
201
|
* Numeric constraints when `kind === 'number'` (`undefined` otherwise).
|
|
104
202
|
*
|
|
@@ -106,17 +204,75 @@ interface ArgSchema {
|
|
|
106
204
|
* `true`, so `Infinity` is rejected even when no constraints object is set.
|
|
107
205
|
*/
|
|
108
206
|
readonly numberConstraints: NumberConstraints | undefined;
|
|
207
|
+
/**
|
|
208
|
+
* String constraints when `kind === 'string'` (`undefined` otherwise).
|
|
209
|
+
*
|
|
210
|
+
* Enforced at the parse and resolution boundaries, in fixed order:
|
|
211
|
+
* nonEmpty → minLength → maxLength → pattern. A `defaultValue` is a typed
|
|
212
|
+
* value, so it is validated against them when the schema is built.
|
|
213
|
+
*/
|
|
214
|
+
readonly stringConstraints: StringConstraints | undefined;
|
|
215
|
+
/**
|
|
216
|
+
* Filesystem checks for path-valued args (set by `arg.path()`).
|
|
217
|
+
*
|
|
218
|
+
* Validated after resolution through the runtime adapter, so CLI, stdin,
|
|
219
|
+
* env, and defaulted values are all checked. Only meaningful when
|
|
220
|
+
* `kind === 'string'`.
|
|
221
|
+
*/
|
|
222
|
+
readonly pathChecks: PathChecks | undefined;
|
|
223
|
+
/**
|
|
224
|
+
* Help placeholder label (e.g. `'url'`).
|
|
225
|
+
*
|
|
226
|
+
* Set by the sugar factories (`arg.url()`, `arg.date()`, …) so tooling
|
|
227
|
+
* reading the schema knows the expected value shape. Help renders a
|
|
228
|
+
* positional by its own name, so this does not change the usage line.
|
|
229
|
+
*/
|
|
230
|
+
readonly valueHint: string | undefined;
|
|
109
231
|
/** Custom parse function (only when `kind === 'custom'`). */
|
|
110
232
|
readonly parseFn: ArgParseFn<unknown> | undefined;
|
|
111
233
|
/**
|
|
112
|
-
*
|
|
234
|
+
* CLI value separator for a collection (`undefined` otherwise).
|
|
235
|
+
*
|
|
236
|
+
* When set, each positional token is split on this separator before element
|
|
237
|
+
* coercion. Other sources decode through {@link ArgSchema.split}.
|
|
238
|
+
*/
|
|
239
|
+
readonly separator: string | undefined;
|
|
240
|
+
/**
|
|
241
|
+
* Env and stdin split policies for a collection (`undefined` otherwise).
|
|
242
|
+
*
|
|
243
|
+
* A source the binding leaves out takes its default: comma-delimited for env,
|
|
244
|
+
* line-delimited for stdin.
|
|
245
|
+
*/
|
|
246
|
+
readonly split: SourceSplitBinding | undefined;
|
|
247
|
+
/**
|
|
248
|
+
* How a repeated key combines when `kind === 'keyValue'`.
|
|
249
|
+
*
|
|
250
|
+
* @defaultValue `'last'`
|
|
251
|
+
*/
|
|
252
|
+
readonly duplicateKeys: DuplicateKeys;
|
|
253
|
+
/**
|
|
254
|
+
* Deduplicate the resolved values of a variadic arg.
|
|
255
|
+
*
|
|
256
|
+
* Applied after all sources resolve, preserving first-seen order. Uses
|
|
257
|
+
* `SameValueZero` semantics (like `Set`).
|
|
258
|
+
*/
|
|
259
|
+
readonly unique: boolean;
|
|
260
|
+
/**
|
|
261
|
+
* Standard Schema v1 validator applied to each resolved value.
|
|
113
262
|
*
|
|
114
263
|
* When set, the value from any source (CLI, env, stdin, default) is
|
|
115
264
|
* validated after resolution via `~standard.validate`. Sync and async
|
|
116
265
|
* validators are both awaited; issues surface as a `CONSTRAINT_VIOLATED`
|
|
117
|
-
* {@link ValidationError}.
|
|
266
|
+
* {@link ValidationError}. A variadic arg validates every element with it.
|
|
118
267
|
*/
|
|
119
268
|
readonly standard: StandardSchemaV1 | undefined;
|
|
269
|
+
/**
|
|
270
|
+
* Standard Schema v1 validator applied to the completed collection.
|
|
271
|
+
*
|
|
272
|
+
* Set by `.standard()` on a builder that already aggregates, so the array or
|
|
273
|
+
* record is validated as a whole after every element passed.
|
|
274
|
+
*/
|
|
275
|
+
readonly aggregateStandard: StandardSchemaV1 | undefined;
|
|
120
276
|
/**
|
|
121
277
|
* Deprecation marker.
|
|
122
278
|
*
|
|
@@ -129,6 +285,169 @@ interface ArgSchema {
|
|
|
129
285
|
*/
|
|
130
286
|
readonly deprecated: string | true | undefined;
|
|
131
287
|
}
|
|
288
|
+
/** Definition fields accepted by every arg kind. */
|
|
289
|
+
interface ArgDefinitionBase {
|
|
290
|
+
/**
|
|
291
|
+
* Presence state.
|
|
292
|
+
* @defaultValue `'required'`
|
|
293
|
+
*/
|
|
294
|
+
readonly presence?: ArgPresence | undefined;
|
|
295
|
+
/**
|
|
296
|
+
* Whether this arg consumes all remaining positionals.
|
|
297
|
+
* @defaultValue `false`
|
|
298
|
+
*/
|
|
299
|
+
readonly variadic?: boolean | undefined;
|
|
300
|
+
/**
|
|
301
|
+
* Stdin binding. See {@link StdinOptions}.
|
|
302
|
+
* @defaultValue `undefined`
|
|
303
|
+
*/
|
|
304
|
+
readonly stdin?: StdinOptions | undefined;
|
|
305
|
+
/**
|
|
306
|
+
* Runtime default value.
|
|
307
|
+
* @defaultValue `undefined`
|
|
308
|
+
*/
|
|
309
|
+
readonly defaultValue?: unknown;
|
|
310
|
+
/**
|
|
311
|
+
* Human-readable description for help text.
|
|
312
|
+
* @defaultValue `undefined`
|
|
313
|
+
*/
|
|
314
|
+
readonly description?: string | undefined;
|
|
315
|
+
/**
|
|
316
|
+
* Environment variable name for env resolution.
|
|
317
|
+
* @defaultValue `undefined`
|
|
318
|
+
*/
|
|
319
|
+
readonly envVar?: string | undefined;
|
|
320
|
+
/**
|
|
321
|
+
* Dotted config path for config resolution (e.g. `'deploy.region'`).
|
|
322
|
+
* @defaultValue `undefined`
|
|
323
|
+
*/
|
|
324
|
+
readonly configPath?: string | undefined;
|
|
325
|
+
/**
|
|
326
|
+
* Interactive prompt configuration.
|
|
327
|
+
* @defaultValue `undefined`
|
|
328
|
+
*/
|
|
329
|
+
readonly prompt?: PromptConfig | undefined;
|
|
330
|
+
/**
|
|
331
|
+
* Help placeholder label (`'url'`, `'path'`, …).
|
|
332
|
+
* @defaultValue `undefined`
|
|
333
|
+
*/
|
|
334
|
+
readonly valueHint?: string | undefined;
|
|
335
|
+
/**
|
|
336
|
+
* CLI value separator each positional token is split on.
|
|
337
|
+
* @defaultValue `undefined`
|
|
338
|
+
*/
|
|
339
|
+
readonly separator?: string | undefined;
|
|
340
|
+
/**
|
|
341
|
+
* Env and stdin split policies.
|
|
342
|
+
* @defaultValue `undefined`
|
|
343
|
+
*/
|
|
344
|
+
readonly split?: SourceSplitBinding | undefined;
|
|
345
|
+
/**
|
|
346
|
+
* Deduplicate the resolved values of a variadic arg.
|
|
347
|
+
* @defaultValue `false`
|
|
348
|
+
*/
|
|
349
|
+
readonly unique?: boolean | undefined;
|
|
350
|
+
/**
|
|
351
|
+
* Standard Schema v1 validator applied to each resolved value.
|
|
352
|
+
* @defaultValue `undefined`
|
|
353
|
+
*/
|
|
354
|
+
readonly standard?: StandardSchemaV1 | undefined;
|
|
355
|
+
/**
|
|
356
|
+
* Standard Schema v1 validator applied to a completed collection.
|
|
357
|
+
* @defaultValue `undefined`
|
|
358
|
+
*/
|
|
359
|
+
readonly aggregateStandard?: StandardSchemaV1 | undefined;
|
|
360
|
+
/**
|
|
361
|
+
* Deprecation marker. `true` deprecates without a message, a string carries
|
|
362
|
+
* the migration guidance.
|
|
363
|
+
* @defaultValue `undefined`
|
|
364
|
+
*/
|
|
365
|
+
readonly deprecated?: string | true | undefined;
|
|
366
|
+
}
|
|
367
|
+
/** Definition of a `string` arg. */
|
|
368
|
+
interface StringArgDefinition extends ArgDefinitionBase {
|
|
369
|
+
/** Kind discriminator. */
|
|
370
|
+
readonly kind: "string";
|
|
371
|
+
/**
|
|
372
|
+
* String constraints enforced at the parse and resolution boundaries.
|
|
373
|
+
* @defaultValue `undefined`
|
|
374
|
+
*/
|
|
375
|
+
readonly stringConstraints?: StringConstraints | undefined;
|
|
376
|
+
/**
|
|
377
|
+
* Filesystem checks applied after resolution.
|
|
378
|
+
* @defaultValue `undefined`
|
|
379
|
+
*/
|
|
380
|
+
readonly pathChecks?: PathChecks | undefined;
|
|
381
|
+
}
|
|
382
|
+
/** Definition of a `number` arg. */
|
|
383
|
+
interface NumberArgDefinition extends ArgDefinitionBase {
|
|
384
|
+
/** Kind discriminator. */
|
|
385
|
+
readonly kind: "number";
|
|
386
|
+
/**
|
|
387
|
+
* Numeric constraints enforced at the parse and resolution boundaries.
|
|
388
|
+
* @defaultValue `undefined`
|
|
389
|
+
*/
|
|
390
|
+
readonly numberConstraints?: NumberConstraints | undefined;
|
|
391
|
+
}
|
|
392
|
+
/** Definition of an `enum` arg. */
|
|
393
|
+
interface EnumArgDefinition extends ArgDefinitionBase {
|
|
394
|
+
/** Kind discriminator. */
|
|
395
|
+
readonly kind: "enum";
|
|
396
|
+
/** Allowed literal values. */
|
|
397
|
+
readonly enumValues: readonly string[];
|
|
398
|
+
}
|
|
399
|
+
/** Definition of a `custom` arg. */
|
|
400
|
+
interface CustomArgDefinition extends ArgDefinitionBase {
|
|
401
|
+
/** Kind discriminator. */
|
|
402
|
+
readonly kind: "custom";
|
|
403
|
+
/**
|
|
404
|
+
* Parse function applied to the raw value.
|
|
405
|
+
* @defaultValue `undefined`
|
|
406
|
+
*/
|
|
407
|
+
readonly parseFn?: ArgParseFn<unknown> | undefined;
|
|
408
|
+
}
|
|
409
|
+
/** Definition of a `boolean` arg. */
|
|
410
|
+
interface BooleanArgDefinition extends ArgDefinitionBase {
|
|
411
|
+
/** Kind discriminator. */
|
|
412
|
+
readonly kind: "boolean";
|
|
413
|
+
}
|
|
414
|
+
/** Definition of a `keyValue` arg. */
|
|
415
|
+
interface KeyValueArgDefinition extends ArgDefinitionBase {
|
|
416
|
+
/** Kind discriminator. */
|
|
417
|
+
readonly kind: "keyValue";
|
|
418
|
+
/**
|
|
419
|
+
* How a repeated key combines. See {@link DuplicateKeys}.
|
|
420
|
+
* @defaultValue `'last'`
|
|
421
|
+
*/
|
|
422
|
+
readonly duplicateKeys?: DuplicateKeys | undefined;
|
|
423
|
+
/**
|
|
424
|
+
* Schema describing the value of each entry, as a definition or an already
|
|
425
|
+
* built {@link ArgSchema}.
|
|
426
|
+
* @defaultValue `undefined`, which leaves entry values as strings
|
|
427
|
+
*/
|
|
428
|
+
readonly elementSchema?: ArgDefinition | ArgSchema | undefined;
|
|
429
|
+
}
|
|
430
|
+
/** Maps each {@link ArgKind} to its definition shape. */
|
|
431
|
+
interface ArgDefinitionByKind {
|
|
432
|
+
/** Definition shape for `string` args. */
|
|
433
|
+
readonly string: StringArgDefinition;
|
|
434
|
+
/** Definition shape for `number` args. */
|
|
435
|
+
readonly number: NumberArgDefinition;
|
|
436
|
+
/** Definition shape for `boolean` args. */
|
|
437
|
+
readonly boolean: BooleanArgDefinition;
|
|
438
|
+
/** Definition shape for `enum` args. */
|
|
439
|
+
readonly enum: EnumArgDefinition;
|
|
440
|
+
/** Definition shape for `custom` args. */
|
|
441
|
+
readonly custom: CustomArgDefinition;
|
|
442
|
+
/** Definition shape for `keyValue` args. */
|
|
443
|
+
readonly keyValue: KeyValueArgDefinition;
|
|
444
|
+
}
|
|
445
|
+
/** Definition of an arg of kind `K`, including the kind discriminator. */
|
|
446
|
+
type ArgDefinition<K extends ArgKind = ArgKind> = ArgDefinitionByKind[K];
|
|
447
|
+
/** Definition of an arg of kind `K` with the kind discriminator removed. */
|
|
448
|
+
type ArgDefinitionOverrides<K extends ArgKind = ArgKind> = Omit<ArgDefinitionByKind[K], "kind">;
|
|
449
|
+
/** Positional factory arguments, requiring fields that the selected kind requires. */
|
|
450
|
+
type ArgDefinitionArguments<K extends ArgKind> = K extends "enum" ? [overrides: ArgDefinitionOverrides<K>] : [overrides?: ArgDefinitionOverrides<K>];
|
|
132
451
|
/**
|
|
133
452
|
* Create a raw {@link ArgSchema} object with sensible defaults.
|
|
134
453
|
*
|
|
@@ -137,13 +456,14 @@ interface ArgSchema {
|
|
|
137
456
|
* modifiers. `createArgSchema()` exists for advanced schema composition,
|
|
138
457
|
* targeted tests, or custom builders that need the plain runtime descriptor.
|
|
139
458
|
*
|
|
140
|
-
*
|
|
141
|
-
* responsible for preserving invariants such as variadic ordering
|
|
142
|
-
* compatible `parseFn` / `kind` combinations.
|
|
459
|
+
* Fields are shallow-merged on top of the default shape, so callers are
|
|
460
|
+
* responsible for preserving invariants such as variadic ordering.
|
|
143
461
|
*
|
|
144
462
|
* @param kind - Discriminator for the value type this arg accepts.
|
|
145
|
-
* @param overrides -
|
|
463
|
+
* @param overrides - Definition fields for `kind`, shallow-merged onto defaults.
|
|
146
464
|
* @returns A fully populated {@link ArgSchema}.
|
|
465
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` when a field belongs to a
|
|
466
|
+
* different {@link ArgKind}.
|
|
147
467
|
*
|
|
148
468
|
* @example
|
|
149
469
|
* ```ts
|
|
@@ -153,7 +473,28 @@ interface ArgSchema {
|
|
|
153
473
|
* });
|
|
154
474
|
* ```
|
|
155
475
|
*/
|
|
156
|
-
declare function createArgSchema(kind:
|
|
476
|
+
declare function createArgSchema<K extends ArgKind>(kind: K, ...overrides: ArgDefinitionArguments<K>): ArgSchema<K>;
|
|
477
|
+
/**
|
|
478
|
+
* Create a raw {@link ArgSchema} object from a single definition object.
|
|
479
|
+
*
|
|
480
|
+
* An already-built {@link ArgSchema} is accepted and re-normalized into a
|
|
481
|
+
* deep-equal schema.
|
|
482
|
+
*
|
|
483
|
+
* @param definition - Kind discriminator plus the fields valid for that kind.
|
|
484
|
+
* @returns A fully populated {@link ArgSchema}.
|
|
485
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` when a field belongs to a
|
|
486
|
+
* different {@link ArgKind}.
|
|
487
|
+
*
|
|
488
|
+
* @example
|
|
489
|
+
* ```ts
|
|
490
|
+
* const schema = createArgSchema({
|
|
491
|
+
* kind: 'enum',
|
|
492
|
+
* enumValues: ['us', 'eu', 'ap'],
|
|
493
|
+
* description: 'Target region',
|
|
494
|
+
* });
|
|
495
|
+
* ```
|
|
496
|
+
*/
|
|
497
|
+
declare function createArgSchema<K extends ArgKind>(definition: ArgDefinition<K> | ArgSchema<K>): ArgSchema<K>;
|
|
157
498
|
/**
|
|
158
499
|
* Immutable positional argument schema builder.
|
|
159
500
|
*
|
|
@@ -199,13 +540,6 @@ declare function createArgSchema(kind: ArgKind, overrides?: Partial<ArgSchema>):
|
|
|
199
540
|
* ```
|
|
200
541
|
*/
|
|
201
542
|
declare class ArgBuilder<C extends ArgConfig> {
|
|
202
|
-
/** @internal Runtime schema descriptor. */
|
|
203
|
-
readonly schema: ArgSchema;
|
|
204
|
-
/**
|
|
205
|
-
* @internal Type brand — exists only in the type system (`declare`
|
|
206
|
-
* produces no runtime property). Used by {@linkcode InferArg} / {@linkcode InferArgs}.
|
|
207
|
-
*/
|
|
208
|
-
readonly _config: C;
|
|
209
543
|
/**
|
|
210
544
|
* Create an arg builder from a pre-built schema descriptor.
|
|
211
545
|
*
|
|
@@ -215,7 +549,7 @@ declare class ArgBuilder<C extends ArgConfig> {
|
|
|
215
549
|
/**
|
|
216
550
|
* Mark the arg as required (this is the default for positional args).
|
|
217
551
|
* Produces an error if no value resolves from any configured source
|
|
218
|
-
* (CLI → stdin → env → default).
|
|
552
|
+
* (CLI → stdin → env → config → prompt → default).
|
|
219
553
|
*
|
|
220
554
|
* @example
|
|
221
555
|
* ```ts
|
|
@@ -230,7 +564,7 @@ declare class ArgBuilder<C extends ArgConfig> {
|
|
|
230
564
|
*
|
|
231
565
|
* @returns The builder (for chaining).
|
|
232
566
|
*/
|
|
233
|
-
required(): ArgBuilder<WithArgPresence<C,
|
|
567
|
+
required(): ArgBuilder<WithArgPresence<C, "required">>;
|
|
234
568
|
/**
|
|
235
569
|
* Mark the arg as optional. Handlers receive `undefined` when absent.
|
|
236
570
|
*
|
|
@@ -250,23 +584,28 @@ declare class ArgBuilder<C extends ArgConfig> {
|
|
|
250
584
|
*
|
|
251
585
|
* @returns The builder (for chaining).
|
|
252
586
|
*/
|
|
253
|
-
optional(): ArgBuilder<WithArgPresence<C,
|
|
587
|
+
optional(): ArgBuilder<WithArgPresence<C, "optional">>;
|
|
254
588
|
/**
|
|
255
589
|
* Provide a default value. The arg becomes "always present" — handlers
|
|
256
590
|
* will never see `undefined`.
|
|
257
591
|
*
|
|
258
|
-
* The generic constraint
|
|
259
|
-
*
|
|
592
|
+
* The generic constraint {@link ArgDefaultValue} ensures the default matches
|
|
593
|
+
* what the arg resolves to: an array for a variadic arg, a record for a
|
|
594
|
+
* `keyValue` one, and a single value otherwise.
|
|
260
595
|
*
|
|
261
|
-
* Resolution order when extra sources are configured:
|
|
596
|
+
* Resolution order when extra sources are configured:
|
|
597
|
+
* CLI → stdin → env → config → prompt → **default**.
|
|
262
598
|
*
|
|
263
599
|
* @param value - Fallback used when no CLI value or env var resolves.
|
|
264
600
|
* @returns The builder (for chaining).
|
|
601
|
+
* @throws {CLIError} With code `'INVALID_DEFAULT'` when the value is one the
|
|
602
|
+
* arg could never hold.
|
|
265
603
|
*
|
|
266
604
|
* @example
|
|
267
605
|
* ```ts
|
|
268
606
|
* arg.string().default('production')
|
|
269
607
|
* arg.number().default(3000)
|
|
608
|
+
* arg.string().variadic().default(['a', 'b'])
|
|
270
609
|
*
|
|
271
610
|
* // In a command — default kicks in when CLI and env are both absent:
|
|
272
611
|
* command('deploy')
|
|
@@ -282,12 +621,14 @@ declare class ArgBuilder<C extends ArgConfig> {
|
|
|
282
621
|
* // $ mycli deploy production → 'production' (CLI)
|
|
283
622
|
* ```
|
|
284
623
|
*/
|
|
285
|
-
default<V extends C
|
|
624
|
+
default<V extends ArgDefaultValue<C>>(value: V): ArgBuilder<WithArgPresence<C, "defaulted">>;
|
|
286
625
|
/**
|
|
287
626
|
* Mark this arg as variadic — it consumes all remaining positional
|
|
288
627
|
* arguments. The inferred type becomes `T[]`.
|
|
289
628
|
*
|
|
290
|
-
* A variadic arg
|
|
629
|
+
* A variadic arg is the last positional a command can declare. Registering
|
|
630
|
+
* another positional after it throws `INVALID_BUILDER_STATE` from `.arg()`
|
|
631
|
+
* and from `createCommandSchema()`.
|
|
291
632
|
*
|
|
292
633
|
* @example
|
|
293
634
|
* ```ts
|
|
@@ -309,30 +650,162 @@ declare class ArgBuilder<C extends ArgConfig> {
|
|
|
309
650
|
*/
|
|
310
651
|
variadic(): ArgBuilder<WithVariadic<C>>;
|
|
311
652
|
/**
|
|
312
|
-
*
|
|
653
|
+
* Split each positional token on a separator before element coercion, so
|
|
654
|
+
* `mycli build a,b c` collects `['a', 'b', 'c']` into a variadic arg.
|
|
655
|
+
*
|
|
656
|
+
* The separator is the CLI policy alone. Env values split on `','` and the
|
|
657
|
+
* stdin buffer on line terminators unless `.split()` says otherwise.
|
|
658
|
+
*
|
|
659
|
+
* Available on an arg that aggregates, so call it after `.variadic()` or on
|
|
660
|
+
* `arg.keyValue()`.
|
|
661
|
+
*
|
|
662
|
+
* @param value - Separator string (e.g. `','`).
|
|
663
|
+
* @returns The builder (for chaining).
|
|
664
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` on an arg carrying a single
|
|
665
|
+
* value.
|
|
666
|
+
*/
|
|
667
|
+
separator(this: ArgBuilder<C & {
|
|
668
|
+
readonly variadic: true;
|
|
669
|
+
}> | ArgBuilder<C & {
|
|
670
|
+
readonly argKind: "keyValue";
|
|
671
|
+
}>, value: string): ArgBuilder<C>;
|
|
672
|
+
/**
|
|
673
|
+
* Set how each source decodes into elements.
|
|
674
|
+
*
|
|
675
|
+
* CLI tokens accept `'whole'` and a delimiter; env values also accept
|
|
676
|
+
* `'json'`; the stdin buffer accepts every format, including `'lines'`. The
|
|
677
|
+
* strings `'whole'`, `'lines'`, and `'json'` name their format, and every
|
|
678
|
+
* other string is the delimiter to split on. A source left out keeps what it
|
|
679
|
+
* already had, or its default: whole CLI tokens, comma-delimited env values,
|
|
680
|
+
* line-delimited stdin. For stdin, `'whole'` passes the complete buffer to a
|
|
681
|
+
* string element, including its final line terminator.
|
|
682
|
+
*
|
|
683
|
+
* Available on an arg that aggregates, so call it after `.variadic()` or on
|
|
684
|
+
* `arg.keyValue()`.
|
|
685
|
+
*
|
|
686
|
+
* @param options - Per-source split settings.
|
|
687
|
+
* @returns The builder (for chaining).
|
|
688
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` on a format the source does
|
|
689
|
+
* not accept, an empty delimiter, or an arg carrying a single value.
|
|
690
|
+
*
|
|
691
|
+
* @example
|
|
692
|
+
* ```ts
|
|
693
|
+
* arg.string().variadic().split({ env: { format: 'json' } })
|
|
694
|
+
* // FILES='["a.ts","b.ts"]' → ['a.ts', 'b.ts']
|
|
695
|
+
* ```
|
|
696
|
+
*/
|
|
697
|
+
split(this: ArgBuilder<C & {
|
|
698
|
+
readonly variadic: true;
|
|
699
|
+
}> | ArgBuilder<C & {
|
|
700
|
+
readonly argKind: "keyValue";
|
|
701
|
+
}>, options: SplitOptions): ArgBuilder<C>;
|
|
702
|
+
/**
|
|
703
|
+
* Deduplicate the resolved values of a variadic arg, preserving first-seen
|
|
704
|
+
* order. Applied after all sources resolve, using `SameValueZero` semantics.
|
|
705
|
+
*
|
|
706
|
+
* Available on a variadic arg of a list kind, so call it after `.variadic()`.
|
|
707
|
+
*
|
|
708
|
+
* @param value - Whether to deduplicate.
|
|
709
|
+
* @defaultValue `true`
|
|
710
|
+
* @returns The builder (for chaining).
|
|
711
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` on an arg that resolves to
|
|
712
|
+
* one value or to a record.
|
|
713
|
+
*/
|
|
714
|
+
unique(this: ArgBuilder<C & {
|
|
715
|
+
readonly variadic: true;
|
|
716
|
+
readonly argKind: ListArgKind;
|
|
717
|
+
}>, value?: boolean): ArgBuilder<C>;
|
|
718
|
+
/**
|
|
719
|
+
* Set how a repeated key combines.
|
|
720
|
+
*
|
|
721
|
+
* @param policy - `'last'` (default), `'first'`, or `'error'`.
|
|
722
|
+
* @returns The builder (for chaining).
|
|
723
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` on an arg that is not
|
|
724
|
+
* `arg.keyValue()`.
|
|
725
|
+
*
|
|
726
|
+
* @example
|
|
727
|
+
* ```ts
|
|
728
|
+
* arg.keyValue().variadic().duplicateKeys('error').env('VARS')
|
|
729
|
+
* // $ VARS='A=1,A=2' mycli run
|
|
730
|
+
* // # → Duplicate key '<redacted>' from env VARS for argument <vars> (CONSTRAINT_VIOLATED)
|
|
731
|
+
* ```
|
|
732
|
+
*/
|
|
733
|
+
duplicateKeys(this: ArgBuilder<C & {
|
|
734
|
+
readonly argKind: "keyValue";
|
|
735
|
+
}>, policy: DuplicateKeys): ArgBuilder<C>;
|
|
736
|
+
/**
|
|
737
|
+
* Validate the resolved value with a Standard Schema v1 validator.
|
|
313
738
|
*
|
|
314
|
-
*
|
|
315
|
-
*
|
|
739
|
+
* On a single-value builder the validator sees each value; on a builder that
|
|
740
|
+
* already aggregates (`.variadic()` or `arg.keyValue()`) it sees the
|
|
741
|
+
* completed array or record, after every element passed its own validator.
|
|
316
742
|
*
|
|
743
|
+
* The builder this is called on is what decides, so where the call sits
|
|
744
|
+
* relative to `.variadic()` chooses between the two.
|
|
745
|
+
*
|
|
746
|
+
* @param schema - A Standard Schema v1 validator.
|
|
747
|
+
* @returns The builder (for chaining).
|
|
748
|
+
*
|
|
749
|
+
* @example
|
|
750
|
+
* ```ts
|
|
751
|
+
* import { z } from 'zod';
|
|
752
|
+
* arg.string().standard(z.string().min(1)).variadic() // each element
|
|
753
|
+
* arg.string().variadic().standard(z.array(z.string())) // the whole array
|
|
754
|
+
* ```
|
|
755
|
+
*/
|
|
756
|
+
standard(schema: StandardSchemaV1): ArgBuilder<C>;
|
|
757
|
+
/**
|
|
758
|
+
* Let this arg read its value from piped stdin.
|
|
759
|
+
*
|
|
760
|
+
* An explicit `-` in the arg's slot is CLI-sourced with bytes from stdin and
|
|
761
|
+
* keeps CLI precedence. An absent positional takes the stdin fallback stage,
|
|
762
|
+
* which sits between CLI and env, so an arg set in the environment still
|
|
763
|
+
* reads stdin and stdin wins. The whole buffer becomes the value, byte for
|
|
764
|
+
* byte for a string arg; every other kind drops the single line terminator a
|
|
765
|
+
* pipe appends before decoding, and `{ trim: true }` drops it for a string
|
|
766
|
+
* arg too.
|
|
767
|
+
*
|
|
768
|
+
* On an arg that aggregates, a `-` among the tail tokens splices what the
|
|
769
|
+
* buffer decodes to into that position, so `mycli build a - b` over
|
|
770
|
+
* `'x\ny\n'` collects `['a', 'x', 'y', 'b']`. Each `-` stands for the whole
|
|
771
|
+
* source, so two of them splice the buffer twice. A `-` typed beside other
|
|
772
|
+
* tokens with nothing piped fails with `MISSING_STDIN`; a tail of nothing but
|
|
773
|
+
* `-` falls through to the later sources.
|
|
774
|
+
*
|
|
775
|
+
* A stdin-enabled arg cannot receive a literal `-` as its value, since the
|
|
776
|
+
* token names the source.
|
|
777
|
+
*
|
|
778
|
+
* One command may declare a single exclusive stdin consumer; pass
|
|
779
|
+
* `{ consume: 'broadcast' }` on every input that should share the buffer.
|
|
780
|
+
*
|
|
781
|
+
* @param options - When to read stdin, how to share it, and whether to trim.
|
|
317
782
|
* @returns The builder (for chaining).
|
|
318
783
|
*
|
|
319
784
|
* @example
|
|
320
785
|
* ```ts
|
|
321
786
|
* arg.string().describe('Input text').stdin()
|
|
322
|
-
* // $ echo "hello" | mycli transform → input = 'hello' (from stdin)
|
|
787
|
+
* // $ echo "hello" | mycli transform → input = 'hello\n' (from stdin)
|
|
788
|
+
* // $ mycli transform - → input reads stdin
|
|
323
789
|
* // $ mycli transform "hello" → input = 'hello' (from CLI)
|
|
790
|
+
*
|
|
791
|
+
* arg.string().stdin({ when: 'dash' })
|
|
792
|
+
* // only an explicit `-` reads stdin
|
|
793
|
+
*
|
|
794
|
+
* arg.path({ mustExist: true }).stdin({ trim: true })
|
|
795
|
+
* // $ echo ./dist | mycli clean → path = './dist', checked on disk
|
|
324
796
|
* ```
|
|
325
797
|
*/
|
|
326
|
-
stdin(): ArgBuilder<C
|
|
798
|
+
stdin(options?: StdinOptions): ArgBuilder<WithoutArgElementEligibility<C>>;
|
|
327
799
|
/**
|
|
328
800
|
* Bind to an environment variable.
|
|
329
801
|
*
|
|
330
|
-
* When the arg is not provided on the CLI, the resolver checks
|
|
331
|
-
* env var before
|
|
332
|
-
* coerced to the arg's declared kind (passthrough for strings, parsed
|
|
802
|
+
* When the arg is not provided on the CLI or by stdin, the resolver checks
|
|
803
|
+
* this env var before config, prompt, and the default value. The env string
|
|
804
|
+
* is coerced to the arg's declared kind (passthrough for strings, parsed
|
|
333
805
|
* for numbers, run through `parseFn` for custom args).
|
|
334
806
|
*
|
|
335
|
-
* Resolution order when extra sources are configured:
|
|
807
|
+
* Resolution order when extra sources are configured:
|
|
808
|
+
* **CLI → stdin → env → config → prompt → default**.
|
|
336
809
|
*
|
|
337
810
|
* Help output shows `[env: VAR]` next to the arg description.
|
|
338
811
|
*
|
|
@@ -350,7 +823,50 @@ declare class ArgBuilder<C extends ArgConfig> {
|
|
|
350
823
|
* });
|
|
351
824
|
* ```
|
|
352
825
|
*/
|
|
353
|
-
env(varName: string): ArgBuilder<C
|
|
826
|
+
env(varName: string): ArgBuilder<WithoutArgElementEligibility<C>>;
|
|
827
|
+
/**
|
|
828
|
+
* Bind to a dotted config path.
|
|
829
|
+
*
|
|
830
|
+
* The config value is read after CLI, stdin, and env, and is coerced to the
|
|
831
|
+
* arg's declared kind the same way a flag's config value is.
|
|
832
|
+
*
|
|
833
|
+
* @param path - Dotted config key (e.g. `'deploy.region'`).
|
|
834
|
+
* @returns The builder (for chaining).
|
|
835
|
+
*
|
|
836
|
+
* @example
|
|
837
|
+
* ```ts
|
|
838
|
+
* arg.string().config('deploy.region').default('us-east-1')
|
|
839
|
+
* // Config file: { "deploy": { "region": "eu-west-1" } }
|
|
840
|
+
* // $ mycli deploy → region = 'eu-west-1'
|
|
841
|
+
* // $ mycli deploy ap-south-1 → CLI positional wins
|
|
842
|
+
* ```
|
|
843
|
+
*/
|
|
844
|
+
config(path: string): ArgBuilder<WithoutArgElementEligibility<C>>;
|
|
845
|
+
/**
|
|
846
|
+
* Attach interactive prompt configuration.
|
|
847
|
+
*
|
|
848
|
+
* When CLI, stdin, env, and config all produce nothing, the prompt engine
|
|
849
|
+
* uses this config to ask the user. In non-interactive contexts the prompt
|
|
850
|
+
* is skipped and resolution falls through to the default or the missing-arg
|
|
851
|
+
* error.
|
|
852
|
+
*
|
|
853
|
+
* The compatible kinds follow the value and the cardinality: a variadic arg
|
|
854
|
+
* takes the `multiselect` a `flag.array()` takes, and every other arg takes
|
|
855
|
+
* what its kind takes on the flag surface.
|
|
856
|
+
*
|
|
857
|
+
* @param config - {@link PromptConfig} describing the interactive prompt.
|
|
858
|
+
* @returns The builder (for chaining).
|
|
859
|
+
*
|
|
860
|
+
* @example
|
|
861
|
+
* ```ts
|
|
862
|
+
* arg.string().prompt({ kind: 'input', message: 'Target:' })
|
|
863
|
+
* // $ mycli deploy → prompts "Target:"
|
|
864
|
+
* // $ mycli deploy production → skips the prompt
|
|
865
|
+
*
|
|
866
|
+
* arg.string().variadic().prompt({ kind: 'multiselect', message: 'Targets:' })
|
|
867
|
+
* ```
|
|
868
|
+
*/
|
|
869
|
+
prompt(config: AllowedArgPromptConfig<C>): ArgBuilder<WithoutArgElementEligibility<C>>;
|
|
354
870
|
/**
|
|
355
871
|
* Human-readable description shown in help output.
|
|
356
872
|
*
|
|
@@ -366,7 +882,7 @@ declare class ArgBuilder<C extends ArgConfig> {
|
|
|
366
882
|
* // <target> Deploy target
|
|
367
883
|
* ```
|
|
368
884
|
*/
|
|
369
|
-
describe(description: string): ArgBuilder<C
|
|
885
|
+
describe(description: string): ArgBuilder<WithoutArgElementEligibility<C>>;
|
|
370
886
|
/**
|
|
371
887
|
* Mark this arg as deprecated.
|
|
372
888
|
*
|
|
@@ -388,7 +904,7 @@ declare class ArgBuilder<C extends ArgConfig> {
|
|
|
388
904
|
* // <target> Deploy target [deprecated: use --target flag instead]
|
|
389
905
|
* ```
|
|
390
906
|
*/
|
|
391
|
-
deprecated(message?: string): ArgBuilder<C
|
|
907
|
+
deprecated(message?: string): ArgBuilder<WithoutArgElementEligibility<C>>;
|
|
392
908
|
/**
|
|
393
909
|
* Require an integer value. Composes with other numeric constraints.
|
|
394
910
|
*
|
|
@@ -403,7 +919,7 @@ declare class ArgBuilder<C extends ArgConfig> {
|
|
|
403
919
|
* ```
|
|
404
920
|
*/
|
|
405
921
|
int(this: ArgBuilder<C & {
|
|
406
|
-
readonly argKind:
|
|
922
|
+
readonly argKind: "number";
|
|
407
923
|
}>, value?: boolean): ArgBuilder<C>;
|
|
408
924
|
/**
|
|
409
925
|
* Set an inclusive lower bound. Composes with other numeric constraints;
|
|
@@ -420,7 +936,7 @@ declare class ArgBuilder<C extends ArgConfig> {
|
|
|
420
936
|
* ```
|
|
421
937
|
*/
|
|
422
938
|
min(this: ArgBuilder<C & {
|
|
423
|
-
readonly argKind:
|
|
939
|
+
readonly argKind: "number";
|
|
424
940
|
}>, value: number): ArgBuilder<C>;
|
|
425
941
|
/**
|
|
426
942
|
* Set an inclusive upper bound. Composes with other numeric constraints;
|
|
@@ -435,7 +951,7 @@ declare class ArgBuilder<C extends ArgConfig> {
|
|
|
435
951
|
* ```
|
|
436
952
|
*/
|
|
437
953
|
max(this: ArgBuilder<C & {
|
|
438
|
-
readonly argKind:
|
|
954
|
+
readonly argKind: "number";
|
|
439
955
|
}>, value: number): ArgBuilder<C>;
|
|
440
956
|
/**
|
|
441
957
|
* Require (or, with `false`, allow) a finite value. Finiteness is enforced
|
|
@@ -452,20 +968,81 @@ declare class ArgBuilder<C extends ArgConfig> {
|
|
|
452
968
|
* ```
|
|
453
969
|
*/
|
|
454
970
|
finite(this: ArgBuilder<C & {
|
|
455
|
-
readonly argKind:
|
|
971
|
+
readonly argKind: "number";
|
|
456
972
|
}>, allow?: boolean): ArgBuilder<C>;
|
|
973
|
+
/**
|
|
974
|
+
* Reject empty strings. Composes with other string constraints.
|
|
975
|
+
*
|
|
976
|
+
* @param value - Whether to reject empty strings.
|
|
977
|
+
* @defaultValue `true`
|
|
978
|
+
* @returns The builder (for chaining).
|
|
979
|
+
*
|
|
980
|
+
* @example
|
|
981
|
+
* ```ts
|
|
982
|
+
* arg.string().nonEmpty() // rejects '', accepts 'x'
|
|
983
|
+
* ```
|
|
984
|
+
*/
|
|
985
|
+
nonEmpty(this: ArgBuilder<C & {
|
|
986
|
+
readonly argKind: "string";
|
|
987
|
+
}>, value?: boolean): ArgBuilder<C>;
|
|
988
|
+
/**
|
|
989
|
+
* Set an inclusive minimum length (UTF-16 code units). Composes with other
|
|
990
|
+
* string constraints; a later call overrides an earlier `minLength`.
|
|
991
|
+
*
|
|
992
|
+
* @param value - Inclusive minimum length.
|
|
993
|
+
* @returns The builder (for chaining).
|
|
994
|
+
*
|
|
995
|
+
* @example
|
|
996
|
+
* ```ts
|
|
997
|
+
* arg.string().minLength(3) // rejects 'ab', accepts 'abc'
|
|
998
|
+
* ```
|
|
999
|
+
*/
|
|
1000
|
+
minLength(this: ArgBuilder<C & {
|
|
1001
|
+
readonly argKind: "string";
|
|
1002
|
+
}>, value: number): ArgBuilder<C>;
|
|
1003
|
+
/**
|
|
1004
|
+
* Set an inclusive maximum length (UTF-16 code units). Composes with other
|
|
1005
|
+
* string constraints; a later call overrides an earlier `maxLength`.
|
|
1006
|
+
*
|
|
1007
|
+
* @param value - Inclusive maximum length.
|
|
1008
|
+
* @returns The builder (for chaining).
|
|
1009
|
+
*
|
|
1010
|
+
* @example
|
|
1011
|
+
* ```ts
|
|
1012
|
+
* arg.string().maxLength(8) // rejects 9+ chars
|
|
1013
|
+
* ```
|
|
1014
|
+
*/
|
|
1015
|
+
maxLength(this: ArgBuilder<C & {
|
|
1016
|
+
readonly argKind: "string";
|
|
1017
|
+
}>, value: number): ArgBuilder<C>;
|
|
1018
|
+
/**
|
|
1019
|
+
* Require the value to match a regular expression. Anchor with `^`/`$`
|
|
1020
|
+
* for full-string matching. Composes with other string constraints.
|
|
1021
|
+
*
|
|
1022
|
+
* @param value - Pattern the value must match.
|
|
1023
|
+
* @returns The builder (for chaining).
|
|
1024
|
+
*
|
|
1025
|
+
* @example
|
|
1026
|
+
* ```ts
|
|
1027
|
+
* arg.string().pattern(/^ghp_/) // rejects 'abc', accepts 'ghp_x'
|
|
1028
|
+
* ```
|
|
1029
|
+
*/
|
|
1030
|
+
pattern(this: ArgBuilder<C & {
|
|
1031
|
+
readonly argKind: "string";
|
|
1032
|
+
}>, value: RegExp): ArgBuilder<C>;
|
|
457
1033
|
}
|
|
458
1034
|
/**
|
|
459
1035
|
* Arg factory functions — the public API for creating positional arguments.
|
|
460
1036
|
*
|
|
461
1037
|
* Each method returns an {@linkcode ArgBuilder} seeded with the correct {@linkcode ArgKind}
|
|
462
1038
|
* and initial type-level config. Chain modifiers (`.optional()`, `.env()`,
|
|
463
|
-
* `.
|
|
1039
|
+
* `.config()`, `.prompt()`, `.default()`, `.variadic()`, `.stdin()`,
|
|
1040
|
+
* `.describe()`, `.deprecated()`) to refine.
|
|
464
1041
|
*
|
|
465
1042
|
* All args are **required** by default. Resolution order when extra
|
|
466
|
-
* sources are configured: **CLI → stdin → env → default**.
|
|
1043
|
+
* sources are configured: **CLI → stdin → env → config → prompt → default**.
|
|
467
1044
|
*
|
|
468
|
-
* @example Overview
|
|
1045
|
+
* @example Overview of common kinds with common modifier patterns
|
|
469
1046
|
* ```ts
|
|
470
1047
|
* command('process')
|
|
471
1048
|
* // String arg with env fallback
|
|
@@ -497,7 +1074,18 @@ declare class ArgBuilder<C extends ArgConfig> {
|
|
|
497
1074
|
*/
|
|
498
1075
|
interface ArgFactory {
|
|
499
1076
|
/**
|
|
500
|
-
* String-valued positional argument
|
|
1077
|
+
* String-valued positional argument, with optional string constraints.
|
|
1078
|
+
* Required by default.
|
|
1079
|
+
*
|
|
1080
|
+
* Constraints are enforced at the parse and resolution boundaries, in
|
|
1081
|
+
* fixed order: nonEmpty → minLength → maxLength → pattern. A `.default()`
|
|
1082
|
+
* value is validated against them where the chain declares it. They also
|
|
1083
|
+
* compose via chained methods (`.nonEmpty()`, `.minLength()`,
|
|
1084
|
+
* `.maxLength()`, `.pattern()`), which override values set here.
|
|
1085
|
+
*
|
|
1086
|
+
* @param constraints - Optional string constraints.
|
|
1087
|
+
* @defaultValue `undefined` (no constraints)
|
|
1088
|
+
* @returns A required string {@link ArgBuilder}.
|
|
501
1089
|
*
|
|
502
1090
|
* @example
|
|
503
1091
|
* ```ts
|
|
@@ -505,19 +1093,20 @@ interface ArgFactory {
|
|
|
505
1093
|
* arg.string().optional() // string | undefined
|
|
506
1094
|
* arg.string().env('TARGET') // falls back to $TARGET
|
|
507
1095
|
* arg.string().default('production') // always present
|
|
1096
|
+
* arg.string({ nonEmpty: true }) // rejects ''
|
|
1097
|
+
* arg.string({ pattern: /^ghp_/ }) // token shapes
|
|
508
1098
|
*
|
|
509
1099
|
* // In a command:
|
|
510
1100
|
* command('deploy')
|
|
511
1101
|
* .arg('target', arg.string().env('DEPLOY_TARGET').describe('Deploy target'))
|
|
512
1102
|
* ```
|
|
513
|
-
*
|
|
514
|
-
* @returns A required string {@link ArgBuilder}.
|
|
515
1103
|
*/
|
|
516
|
-
string(): ArgBuilder<{
|
|
1104
|
+
string(constraints?: StringConstraints): ArgBuilder<{
|
|
517
1105
|
readonly valueType: string;
|
|
518
|
-
readonly presence:
|
|
1106
|
+
readonly presence: "required";
|
|
519
1107
|
readonly variadic: false;
|
|
520
|
-
readonly argKind:
|
|
1108
|
+
readonly argKind: "string";
|
|
1109
|
+
readonly elementEligible: true;
|
|
521
1110
|
}>;
|
|
522
1111
|
/**
|
|
523
1112
|
* Number-valued positional argument. Required by default.
|
|
@@ -550,9 +1139,69 @@ interface ArgFactory {
|
|
|
550
1139
|
*/
|
|
551
1140
|
number(constraints?: NumberConstraints): ArgBuilder<{
|
|
552
1141
|
readonly valueType: number;
|
|
553
|
-
readonly presence:
|
|
1142
|
+
readonly presence: "required";
|
|
1143
|
+
readonly variadic: false;
|
|
1144
|
+
readonly argKind: "number";
|
|
1145
|
+
readonly elementEligible: true;
|
|
1146
|
+
}>;
|
|
1147
|
+
/**
|
|
1148
|
+
* Boolean positional argument. Required by default.
|
|
1149
|
+
*
|
|
1150
|
+
* A positional carries no presence semantics, so the token spells the value
|
|
1151
|
+
* out: `true`/`false` or `1`/`0` from argv, and also `yes`/`no` or an empty
|
|
1152
|
+
* string from env, config, stdin, and a prompt.
|
|
1153
|
+
*
|
|
1154
|
+
* @returns A required boolean {@link ArgBuilder}.
|
|
1155
|
+
*
|
|
1156
|
+
* @example
|
|
1157
|
+
* ```ts
|
|
1158
|
+
* command('feature')
|
|
1159
|
+
* .arg('enabled', arg.boolean().describe('Whether the feature is on'))
|
|
1160
|
+
* // $ mycli feature true → enabled = true
|
|
1161
|
+
* // $ mycli feature nope → ParseError: Invalid boolean value 'nope'
|
|
1162
|
+
* ```
|
|
1163
|
+
*/
|
|
1164
|
+
boolean(): ArgBuilder<{
|
|
1165
|
+
readonly valueType: boolean;
|
|
1166
|
+
readonly presence: "required";
|
|
554
1167
|
readonly variadic: false;
|
|
555
|
-
readonly argKind:
|
|
1168
|
+
readonly argKind: "boolean";
|
|
1169
|
+
readonly elementEligible: true;
|
|
1170
|
+
}>;
|
|
1171
|
+
/**
|
|
1172
|
+
* Key-value positional argument. Required by default.
|
|
1173
|
+
*
|
|
1174
|
+
* Consumes `KEY=VALUE` tokens and resolves to a record, split at the
|
|
1175
|
+
* **first** `=`. The non-variadic form reads one token, the variadic form
|
|
1176
|
+
* aggregates the whole tail. Later occurrences of the same key win, which
|
|
1177
|
+
* `.duplicateKeys()` changes. Not promptable.
|
|
1178
|
+
*
|
|
1179
|
+
* An element builder gives each entry value its own codec, constraints, and
|
|
1180
|
+
* checks, so `arg.keyValue(arg.path())` checks every value on disk.
|
|
1181
|
+
*
|
|
1182
|
+
* @param element - {@link ArgBuilder} describing the value of each entry.
|
|
1183
|
+
* @defaultValue an unconstrained string element
|
|
1184
|
+
* @returns A required key-value {@link ArgBuilder} for records of the element type.
|
|
1185
|
+
*
|
|
1186
|
+
* @example
|
|
1187
|
+
* ```ts
|
|
1188
|
+
* command('run')
|
|
1189
|
+
* .arg('vars', arg.keyValue().variadic().describe('Template variables'))
|
|
1190
|
+
* // $ mycli run A=1 B=2 → vars = { A: '1', B: '2' }
|
|
1191
|
+
*
|
|
1192
|
+
* command('scale')
|
|
1193
|
+
* .arg('replicas', arg.keyValue(arg.number().int().min(0)).variadic())
|
|
1194
|
+
* // $ mycli scale web=3 api=2 → replicas = { web: 3, api: 2 }
|
|
1195
|
+
* ```
|
|
1196
|
+
*/
|
|
1197
|
+
keyValue<E extends ArgConfig & {
|
|
1198
|
+
readonly elementEligible: true;
|
|
1199
|
+
} = StringArgElementConfig>(element?: ArgBuilder<E>): ArgBuilder<{
|
|
1200
|
+
readonly valueType: Record<string, E["valueType"]>;
|
|
1201
|
+
readonly presence: "required";
|
|
1202
|
+
readonly variadic: false;
|
|
1203
|
+
readonly argKind: "keyValue";
|
|
1204
|
+
readonly elementEligible: false;
|
|
556
1205
|
}>;
|
|
557
1206
|
/**
|
|
558
1207
|
* Enum-valued positional argument. Required by default.
|
|
@@ -579,9 +1228,10 @@ interface ArgFactory {
|
|
|
579
1228
|
*/
|
|
580
1229
|
enum<const T extends readonly [string, ...string[]]>(values: T): ArgBuilder<{
|
|
581
1230
|
readonly valueType: T[number];
|
|
582
|
-
readonly presence:
|
|
1231
|
+
readonly presence: "required";
|
|
583
1232
|
readonly variadic: false;
|
|
584
|
-
readonly argKind:
|
|
1233
|
+
readonly argKind: "enum";
|
|
1234
|
+
readonly elementEligible: true;
|
|
585
1235
|
}>;
|
|
586
1236
|
/**
|
|
587
1237
|
* Custom positional argument validated by a Standard Schema v1 validator
|
|
@@ -604,9 +1254,10 @@ interface ArgFactory {
|
|
|
604
1254
|
*/
|
|
605
1255
|
custom<S extends StandardSchemaV1>(schema: S): ArgBuilder<{
|
|
606
1256
|
readonly valueType: InferStandardOutput<S>;
|
|
607
|
-
readonly presence:
|
|
1257
|
+
readonly presence: "required";
|
|
608
1258
|
readonly variadic: false;
|
|
609
|
-
readonly argKind:
|
|
1259
|
+
readonly argKind: "custom";
|
|
1260
|
+
readonly elementEligible: true;
|
|
610
1261
|
}>;
|
|
611
1262
|
/**
|
|
612
1263
|
* Custom-parsed positional argument. Required by default.
|
|
@@ -635,9 +1286,127 @@ interface ArgFactory {
|
|
|
635
1286
|
*/
|
|
636
1287
|
custom<T>(parseFn: ArgParseFn<T>): ArgBuilder<{
|
|
637
1288
|
readonly valueType: T;
|
|
638
|
-
readonly presence:
|
|
1289
|
+
readonly presence: "required";
|
|
1290
|
+
readonly variadic: false;
|
|
1291
|
+
readonly argKind: "custom";
|
|
1292
|
+
readonly elementEligible: true;
|
|
1293
|
+
}>;
|
|
1294
|
+
/**
|
|
1295
|
+
* URL-valued positional argument. Parses into a `URL`; invalid URLs are
|
|
1296
|
+
* rejected with an `INVALID_VALUE` error naming the argument.
|
|
1297
|
+
*
|
|
1298
|
+
* @param options - Optional protocol allowlist (without trailing colon).
|
|
1299
|
+
* @returns A required `URL` {@link ArgBuilder}.
|
|
1300
|
+
*
|
|
1301
|
+
* @example
|
|
1302
|
+
* ```ts
|
|
1303
|
+
* arg.url() // any URL
|
|
1304
|
+
* arg.url({ protocols: ['https'] }) // https only
|
|
1305
|
+
*
|
|
1306
|
+
* // In a command:
|
|
1307
|
+
* command('fetch')
|
|
1308
|
+
* .arg('endpoint', arg.url().env('API_URL').describe('Service endpoint'))
|
|
1309
|
+
* ```
|
|
1310
|
+
*/
|
|
1311
|
+
url(options?: UrlFlagOptions): ArgBuilder<{
|
|
1312
|
+
readonly valueType: URL;
|
|
1313
|
+
readonly presence: "required";
|
|
1314
|
+
readonly variadic: false;
|
|
1315
|
+
readonly argKind: "custom";
|
|
1316
|
+
readonly elementEligible: true;
|
|
1317
|
+
}>;
|
|
1318
|
+
/**
|
|
1319
|
+
* Path-valued positional argument. The value stays a `string`; optional
|
|
1320
|
+
* filesystem checks run **after resolution** through the runtime adapter,
|
|
1321
|
+
* so CLI, stdin, env, and defaulted values are all validated.
|
|
1322
|
+
*
|
|
1323
|
+
* A variadic path arg checks every value it collects. Help renders a
|
|
1324
|
+
* positional by its own name, so the `'path'` value hint on the schema does
|
|
1325
|
+
* not reach the usage line.
|
|
1326
|
+
*
|
|
1327
|
+
* @param options - Optional existence/type checks. `type` implies
|
|
1328
|
+
* existence unless `mustExist` is explicitly `false`.
|
|
1329
|
+
* @returns A required path-string {@link ArgBuilder}.
|
|
1330
|
+
*
|
|
1331
|
+
* @example
|
|
1332
|
+
* ```ts
|
|
1333
|
+
* arg.path() // any string
|
|
1334
|
+
* arg.path({ mustExist: true }) // rejects missing paths
|
|
1335
|
+
* arg.path({ type: 'directory' }) // must exist and be a directory
|
|
1336
|
+
* arg.path({ type: 'directory', create: true })
|
|
1337
|
+
* // created recursively when missing
|
|
1338
|
+
* ```
|
|
1339
|
+
*/
|
|
1340
|
+
path(options?: PathFlagOptions): ArgBuilder<{
|
|
1341
|
+
readonly valueType: string;
|
|
1342
|
+
readonly presence: "required";
|
|
639
1343
|
readonly variadic: false;
|
|
640
|
-
readonly argKind:
|
|
1344
|
+
readonly argKind: "string";
|
|
1345
|
+
readonly elementEligible: true;
|
|
1346
|
+
}>;
|
|
1347
|
+
/**
|
|
1348
|
+
* Date-valued positional argument. Accepts strict ISO-8601 (`2026-07-10`,
|
|
1349
|
+
* `2026-07-10T14:30:00Z`) and parses into a `Date`. Lenient `Date.parse`
|
|
1350
|
+
* inputs (`'0'`, `'March 5'`) and calendar-invalid dates (`2026-02-31`)
|
|
1351
|
+
* are rejected.
|
|
1352
|
+
*
|
|
1353
|
+
* Returns `Date` (not `Temporal`) because the supported runtimes do not
|
|
1354
|
+
* all ship Temporal yet; use `arg.custom()` with `Temporal.PlainDate.from`
|
|
1355
|
+
* where the target runtime has it.
|
|
1356
|
+
*
|
|
1357
|
+
* @param options - Optional inclusive `min`/`max` date bounds.
|
|
1358
|
+
* @returns A required `Date` {@link ArgBuilder}.
|
|
1359
|
+
*
|
|
1360
|
+
* @example
|
|
1361
|
+
* ```ts
|
|
1362
|
+
* arg.date()
|
|
1363
|
+
* arg.date({ min: new Date('2020-01-01') })
|
|
1364
|
+
* ```
|
|
1365
|
+
*/
|
|
1366
|
+
date(options?: DateFlagOptions): ArgBuilder<{
|
|
1367
|
+
readonly valueType: Date;
|
|
1368
|
+
readonly presence: "required";
|
|
1369
|
+
readonly variadic: false;
|
|
1370
|
+
readonly argKind: "custom";
|
|
1371
|
+
readonly elementEligible: true;
|
|
1372
|
+
}>;
|
|
1373
|
+
/**
|
|
1374
|
+
* Duration positional argument. Accepts `'30s'`, `'5m'`, `'1.5h'`,
|
|
1375
|
+
* `'250ms'`, `'2d'`, compounds like `'1h30m'`, or a bare millisecond
|
|
1376
|
+
* count, and resolves to **milliseconds**.
|
|
1377
|
+
*
|
|
1378
|
+
* @returns A required duration {@link ArgBuilder} in milliseconds.
|
|
1379
|
+
*
|
|
1380
|
+
* @example
|
|
1381
|
+
* ```ts
|
|
1382
|
+
* arg.duration().default(30_000) // `mycli wait 45s` → 45000
|
|
1383
|
+
* ```
|
|
1384
|
+
*/
|
|
1385
|
+
duration(): ArgBuilder<{
|
|
1386
|
+
readonly valueType: number;
|
|
1387
|
+
readonly presence: "required";
|
|
1388
|
+
readonly variadic: false;
|
|
1389
|
+
readonly argKind: "custom";
|
|
1390
|
+
readonly elementEligible: true;
|
|
1391
|
+
}>;
|
|
1392
|
+
/**
|
|
1393
|
+
* Byte-size positional argument. Accepts `'512mb'`, `'1.5gb'`, `'64kb'`,
|
|
1394
|
+
* `'100b'` or a bare byte count, and resolves to **bytes**. Units are
|
|
1395
|
+
* binary (`1kb` = 1024) and case-insensitive.
|
|
1396
|
+
*
|
|
1397
|
+
* @returns A required size {@link ArgBuilder} in bytes.
|
|
1398
|
+
*
|
|
1399
|
+
* @example
|
|
1400
|
+
* ```ts
|
|
1401
|
+
* arg.bytes().default(10 * 1024 ** 2) // `mycli split 512kb` → 524288
|
|
1402
|
+
* ```
|
|
1403
|
+
*/
|
|
1404
|
+
bytes(): ArgBuilder<{
|
|
1405
|
+
readonly valueType: number;
|
|
1406
|
+
readonly presence: "required";
|
|
1407
|
+
readonly variadic: false;
|
|
1408
|
+
readonly argKind: "custom";
|
|
1409
|
+
readonly elementEligible: true;
|
|
641
1410
|
}>;
|
|
642
1411
|
}
|
|
643
1412
|
/**
|
|
@@ -647,12 +1416,21 @@ interface ArgFactory {
|
|
|
647
1416
|
* an {@linkcode ArgBuilder}, then chain modifiers and pass the result to
|
|
648
1417
|
* `command().arg(name, builder)`.
|
|
649
1418
|
*
|
|
650
|
-
*
|
|
1419
|
+
* Six base kinds are available:
|
|
651
1420
|
* - `arg.string()` — raw string (most common)
|
|
652
1421
|
* - `arg.number()` — parsed to number, errors on NaN
|
|
1422
|
+
* - `arg.boolean()` reads an explicit true/false token
|
|
653
1423
|
* - `arg.enum(values)` — constrained to listed literals
|
|
1424
|
+
* - `arg.keyValue()` merges `KEY=VALUE` tokens into a record
|
|
654
1425
|
* - `arg.custom(fn)` — arbitrary parse function, infers return type
|
|
655
1426
|
*
|
|
1427
|
+
* Five sugar factories build on them, mirroring their flag counterparts:
|
|
1428
|
+
* - `arg.url()` parses to `URL`, with an optional protocol allowlist
|
|
1429
|
+
* - `arg.path()` keeps the string and adds optional filesystem checks
|
|
1430
|
+
* - `arg.date()` parses strict ISO-8601 to `Date`
|
|
1431
|
+
* - `arg.duration()` resolves `'1h30m'` and friends to milliseconds
|
|
1432
|
+
* - `arg.bytes()` resolves `'512mb'` and friends to bytes
|
|
1433
|
+
*
|
|
656
1434
|
* @example
|
|
657
1435
|
* ```ts
|
|
658
1436
|
* import { command, arg } from '@kjanat/dreamcli';
|
|
@@ -670,4 +1448,4 @@ interface ArgFactory {
|
|
|
670
1448
|
*/
|
|
671
1449
|
declare const arg: ArgFactory;
|
|
672
1450
|
//#endregion
|
|
673
|
-
export { ARG_KINDS, ARG_PRESENCES, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type InferArg, type InferArgs, type ResolvedArgValue, type WithArgPresence, type WithVariadic, arg, createArgSchema };
|
|
1451
|
+
export { ARG_KINDS, ARG_PRESENCES, type AllowedArgPromptConfig, ArgBuilder, type ArgConfig, type ArgDefaultValue, type ArgDefinition, type ArgDefinitionBase, type ArgDefinitionByKind, type ArgDefinitionOverrides, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type BooleanArgDefinition, type CustomArgDefinition, type DuplicateKeys, type EnumArgDefinition, type InferArg, type InferArgs, type KeyValueArgDefinition, type NumberArgDefinition, type PromptConfigByArgKind, type ResolvedArgValue, type SourceSplitBinding, type SplitBinding, type SplitFormat, type SplitOptions, type SplitPolicy, type SplitSetting, type StdinBinding, type StdinConsume, type StdinOptions, type StdinWhen, type StringArgDefinition, type StringArgElementConfig, type WithArgPresence, type WithVariadic, type WithoutArgElementEligibility, arg, createArgSchema };
|