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