@kjanat/dreamcli 4.0.0-rc.3 → 4.0.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.
Files changed (212) hide show
  1. package/README.md +5 -7
  2. package/dist/{runtime/adapter.d.mts → adapter-D0hbBNVB.d.mts} +2 -4
  3. package/dist/completion-D4mz6axB.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-B9ddC-Kb.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-Cp2w8vRq.mjs +17 -0
  10. package/dist/index-BziI2aKc.d.mts +5440 -0
  11. package/dist/index-DOfClfYR.d.mts +370 -0
  12. package/dist/index-DWsnGZlx.d.mts +831 -0
  13. package/dist/{core/cli/index.d.mts → index-DXROeDPC.d.mts} +116 -57
  14. package/dist/index-DndPmT8J.d.mts +275 -0
  15. package/dist/{core/json-schema/index.d.mts → index-DyoaS234.d.mts} +43 -34
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-C9SzZ7jY.mjs +52 -0
  19. package/dist/json-schema.d.mts +2 -0
  20. package/dist/json-schema.mjs +1 -0
  21. package/dist/package-json-BgE9YjjQ.mjs +3 -0
  22. package/dist/prompt.d.mts +48 -0
  23. package/dist/prompt.mjs +1 -0
  24. package/dist/rolldown-runtime-G4Kt5YOX.mjs +1 -0
  25. package/dist/runtime.d.mts +2 -6
  26. package/dist/runtime.mjs +1 -6
  27. package/dist/terminal-C8KTXjv5.mjs +6 -0
  28. package/dist/test-prompter-v__jT2yG.mjs +1 -0
  29. package/dist/testkit.d.mts +54 -6
  30. package/dist/testkit.mjs +1 -5
  31. package/dist/version.mjs +1 -7
  32. package/dreamcli.schema.json +697 -538
  33. package/package.json +29 -7
  34. package/skills/cli-creation/SKILL.md +16 -11
  35. package/CHANGELOG.md +0 -1116
  36. package/dist/core/cli/builtins.d.mts +0 -117
  37. package/dist/core/cli/builtins.mjs +0 -135
  38. package/dist/core/cli/compiled.d.mts +0 -66
  39. package/dist/core/cli/compiled.mjs +0 -76
  40. package/dist/core/cli/dispatch.d.mts +0 -115
  41. package/dist/core/cli/dispatch.mjs +0 -205
  42. package/dist/core/cli/help-links.d.mts +0 -27
  43. package/dist/core/cli/help-links.mjs +0 -41
  44. package/dist/core/cli/index.mjs +0 -1271
  45. package/dist/core/cli/planner.d.mts +0 -174
  46. package/dist/core/cli/planner.mjs +0 -323
  47. package/dist/core/cli/plugin.d.mts +0 -94
  48. package/dist/core/cli/plugin.mjs +0 -41
  49. package/dist/core/cli/propagate.d.mts +0 -39
  50. package/dist/core/cli/propagate.mjs +0 -57
  51. package/dist/core/cli/reserved-flags.d.mts +0 -19
  52. package/dist/core/cli/reserved-flags.mjs +0 -158
  53. package/dist/core/cli/root-help.d.mts +0 -53
  54. package/dist/core/cli/root-help.mjs +0 -221
  55. package/dist/core/cli/root-output-flags.d.mts +0 -74
  56. package/dist/core/cli/root-output-flags.mjs +0 -169
  57. package/dist/core/cli/root-surface.d.mts +0 -64
  58. package/dist/core/cli/root-surface.mjs +0 -28
  59. package/dist/core/cli/runtime-preflight.d.mts +0 -213
  60. package/dist/core/cli/runtime-preflight.mjs +0 -221
  61. package/dist/core/completion/index.d.mts +0 -76
  62. package/dist/core/completion/index.mjs +0 -90
  63. package/dist/core/completion/shells/bash.d.mts +0 -23
  64. package/dist/core/completion/shells/bash.mjs +0 -312
  65. package/dist/core/completion/shells/fish.d.mts +0 -19
  66. package/dist/core/completion/shells/fish.mjs +0 -164
  67. package/dist/core/completion/shells/powershell.d.mts +0 -13
  68. package/dist/core/completion/shells/powershell.mjs +0 -360
  69. package/dist/core/completion/shells/shared.d.mts +0 -164
  70. package/dist/core/completion/shells/shared.mjs +0 -147
  71. package/dist/core/completion/shells/zsh.d.mts +0 -23
  72. package/dist/core/completion/shells/zsh.mjs +0 -256
  73. package/dist/core/config/index.d.mts +0 -191
  74. package/dist/core/config/index.mjs +0 -285
  75. package/dist/core/config/package-json.d.mts +0 -179
  76. package/dist/core/config/package-json.mjs +0 -353
  77. package/dist/core/errors/index.d.mts +0 -125
  78. package/dist/core/errors/index.mjs +0 -87
  79. package/dist/core/execution/index.d.mts +0 -61
  80. package/dist/core/execution/index.mjs +0 -220
  81. package/dist/core/help/ansi.d.mts +0 -84
  82. package/dist/core/help/ansi.mjs +0 -121
  83. package/dist/core/help/index.d.mts +0 -149
  84. package/dist/core/help/index.mjs +0 -418
  85. package/dist/core/help/theme.d.mts +0 -86
  86. package/dist/core/help/theme.mjs +0 -69
  87. package/dist/core/json-schema/index.mjs +0 -1008
  88. package/dist/core/json-schema/meta-descriptions.generated.d.mts +0 -274
  89. package/dist/core/json-schema/meta-descriptions.generated.mjs +0 -136
  90. package/dist/core/output/activity.d.mts +0 -193
  91. package/dist/core/output/activity.mjs +0 -452
  92. package/dist/core/output/bind.d.mts +0 -37
  93. package/dist/core/output/bind.mjs +0 -56
  94. package/dist/core/output/contracts.d.mts +0 -82
  95. package/dist/core/output/contracts.mjs +0 -57
  96. package/dist/core/output/display-value.d.mts +0 -19
  97. package/dist/core/output/display-value.mjs +0 -32
  98. package/dist/core/output/index.d.mts +0 -344
  99. package/dist/core/output/index.mjs +0 -514
  100. package/dist/core/output/renderers.d.mts +0 -45
  101. package/dist/core/output/renderers.mjs +0 -46
  102. package/dist/core/output/writer.d.mts +0 -39
  103. package/dist/core/output/writer.mjs +0 -12
  104. package/dist/core/parse/index.d.mts +0 -178
  105. package/dist/core/parse/index.mjs +0 -850
  106. package/dist/core/parse/occurrences.d.mts +0 -90
  107. package/dist/core/parse/occurrences.mjs +0 -114
  108. package/dist/core/prompt/index.d.mts +0 -213
  109. package/dist/core/prompt/index.mjs +0 -348
  110. package/dist/core/read-flags/index.d.mts +0 -150
  111. package/dist/core/read-flags/index.mjs +0 -217
  112. package/dist/core/resolve/args.d.mts +0 -39
  113. package/dist/core/resolve/args.mjs +0 -182
  114. package/dist/core/resolve/coerce.d.mts +0 -79
  115. package/dist/core/resolve/coerce.mjs +0 -900
  116. package/dist/core/resolve/config.d.mts +0 -10
  117. package/dist/core/resolve/config.mjs +0 -19
  118. package/dist/core/resolve/contracts.d.mts +0 -146
  119. package/dist/core/resolve/errors.d.mts +0 -10
  120. package/dist/core/resolve/errors.mjs +0 -148
  121. package/dist/core/resolve/flags.d.mts +0 -74
  122. package/dist/core/resolve/flags.mjs +0 -246
  123. package/dist/core/resolve/index.d.mts +0 -44
  124. package/dist/core/resolve/index.mjs +0 -123
  125. package/dist/core/resolve/path-checks.d.mts +0 -48
  126. package/dist/core/resolve/path-checks.mjs +0 -102
  127. package/dist/core/resolve/redaction.d.mts +0 -13
  128. package/dist/core/resolve/redaction.mjs +0 -14
  129. package/dist/core/resolve/stages.d.mts +0 -86
  130. package/dist/core/resolve/stages.mjs +0 -170
  131. package/dist/core/resolve/standard.d.mts +0 -26
  132. package/dist/core/resolve/standard.mjs +0 -212
  133. package/dist/core/schema/activity.d.mts +0 -189
  134. package/dist/core/schema/arg.d.mts +0 -1461
  135. package/dist/core/schema/arg.mjs +0 -1139
  136. package/dist/core/schema/brand.d.mts +0 -17
  137. package/dist/core/schema/cardinality.d.mts +0 -302
  138. package/dist/core/schema/cardinality.mjs +0 -514
  139. package/dist/core/schema/command.d.mts +0 -1132
  140. package/dist/core/schema/command.mjs +0 -999
  141. package/dist/core/schema/flag.d.mts +0 -1495
  142. package/dist/core/schema/flag.mjs +0 -1207
  143. package/dist/core/schema/index.d.mts +0 -15
  144. package/dist/core/schema/index.mjs +0 -10
  145. package/dist/core/schema/middleware.d.mts +0 -129
  146. package/dist/core/schema/middleware.mjs +0 -41
  147. package/dist/core/schema/number-constraints.d.mts +0 -96
  148. package/dist/core/schema/number-constraints.mjs +0 -60
  149. package/dist/core/schema/prompt.d.mts +0 -135
  150. package/dist/core/schema/provenance.d.mts +0 -99
  151. package/dist/core/schema/provenance.mjs +0 -28
  152. package/dist/core/schema/run.d.mts +0 -211
  153. package/dist/core/schema/source.d.mts +0 -180
  154. package/dist/core/schema/source.mjs +0 -206
  155. package/dist/core/schema/standard.d.mts +0 -100
  156. package/dist/core/schema/standard.mjs +0 -15
  157. package/dist/core/schema/stdin.d.mts +0 -97
  158. package/dist/core/schema/stdin.mjs +0 -91
  159. package/dist/core/schema/string-constraints.d.mts +0 -108
  160. package/dist/core/schema/string-constraints.mjs +0 -86
  161. package/dist/core/schema/value-parsers.d.mts +0 -150
  162. package/dist/core/schema/value-parsers.mjs +0 -160
  163. package/dist/core/schema/value.d.mts +0 -243
  164. package/dist/core/schema/value.mjs +0 -573
  165. package/dist/core/testkit/index.d.mts +0 -63
  166. package/dist/core/testkit/index.mjs +0 -102
  167. package/dist/runtime/adapter.mjs +0 -92
  168. package/dist/runtime/auto.d.mts +0 -25
  169. package/dist/runtime/auto.mjs +0 -45
  170. package/dist/runtime/deno.d.mts +0 -99
  171. package/dist/runtime/deno.mjs +0 -265
  172. package/dist/runtime/detect.d.mts +0 -86
  173. package/dist/runtime/detect.mjs +0 -45
  174. package/dist/runtime/index.d.mts +0 -6
  175. package/dist/runtime/node.d.mts +0 -71
  176. package/dist/runtime/node.mjs +0 -228
  177. package/dist/runtime/paths.d.mts +0 -31
  178. package/dist/runtime/paths.mjs +0 -48
  179. package/dist/strings.d.mts +0 -27
  180. package/dist/strings.mjs +0 -22
  181. package/examples/basic.ts +0 -37
  182. package/examples/flag-types.ts +0 -79
  183. package/examples/gh/package.json +0 -45
  184. package/examples/gh/src/commands/auth.ts +0 -66
  185. package/examples/gh/src/commands/issue.ts +0 -120
  186. package/examples/gh/src/commands/pr.ts +0 -125
  187. package/examples/gh/src/data/issues.yaml +0 -5
  188. package/examples/gh/src/data/issues.yaml.d.ts +0 -17
  189. package/examples/gh/src/data/pull-requests.yaml +0 -7
  190. package/examples/gh/src/data/pull-requests.yaml.d.ts +0 -18
  191. package/examples/gh/src/docs.ts +0 -11
  192. package/examples/gh/src/lib/auth.ts +0 -37
  193. package/examples/gh/src/lib/utils.ts +0 -17
  194. package/examples/gh/src/main.test.ts +0 -307
  195. package/examples/gh/src/main.ts +0 -46
  196. package/examples/help-config.ts +0 -43
  197. package/examples/interactive.ts +0 -67
  198. package/examples/json-mode.ts +0 -95
  199. package/examples/middleware.ts +0 -71
  200. package/examples/multi-command.ts +0 -66
  201. package/examples/output-extras.ts +0 -46
  202. package/examples/parser-control.ts +0 -40
  203. package/examples/pwsh-demo/README.md +0 -40
  204. package/examples/pwsh-demo/package.json +0 -41
  205. package/examples/pwsh-demo/pwsh-demo.cmd +0 -3
  206. package/examples/pwsh-demo/smoke-powershell.ps1 +0 -218
  207. package/examples/pwsh-demo/src/main.test.ts +0 -45
  208. package/examples/pwsh-demo/src/main.ts +0 -140
  209. package/examples/spinner-progress.ts +0 -49
  210. package/examples/standard-schema.ts +0 -45
  211. package/examples/testing.ts +0 -147
  212. 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 };