@kjanat/dreamcli 1.0.0 → 2.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 (217) hide show
  1. package/CHANGELOG.md +45 -6
  2. package/LICENSE +1 -1
  3. package/README.md +296 -164
  4. package/dist/core/cli/dispatch.d.mts +85 -0
  5. package/dist/core/cli/dispatch.mjs +1 -0
  6. package/dist/core/cli/index.d.mts +418 -0
  7. package/dist/core/cli/index.mjs +1 -0
  8. package/dist/core/cli/planner.d.mts +143 -0
  9. package/dist/core/cli/planner.mjs +1 -0
  10. package/dist/core/cli/plugin.d.mts +94 -0
  11. package/dist/core/cli/plugin.mjs +1 -0
  12. package/dist/core/cli/propagate.d.mts +39 -0
  13. package/dist/core/cli/propagate.mjs +1 -0
  14. package/dist/core/cli/root-help.d.mts +28 -0
  15. package/dist/core/cli/root-help.mjs +7 -0
  16. package/dist/core/cli/root-surface.d.mts +42 -0
  17. package/dist/core/cli/root-surface.mjs +1 -0
  18. package/dist/core/cli/runtime-preflight.d.mts +149 -0
  19. package/dist/core/cli/runtime-preflight.mjs +1 -0
  20. package/dist/core/completion/index.d.mts +46 -0
  21. package/dist/core/completion/index.mjs +1 -0
  22. package/dist/core/completion/shells/bash.d.mts +24 -0
  23. package/dist/core/completion/shells/bash.mjs +3 -0
  24. package/dist/core/completion/shells/fish.d.mts +20 -0
  25. package/dist/core/completion/shells/fish.mjs +2 -0
  26. package/dist/core/completion/shells/powershell.d.mts +14 -0
  27. package/dist/core/completion/shells/powershell.mjs +2 -0
  28. package/dist/core/completion/shells/shared.d.mts +139 -0
  29. package/dist/core/completion/shells/shared.mjs +1 -0
  30. package/dist/core/completion/shells/zsh.d.mts +24 -0
  31. package/dist/core/completion/shells/zsh.mjs +2 -0
  32. package/dist/core/config/index.d.mts +161 -0
  33. package/dist/core/config/index.mjs +1 -0
  34. package/dist/core/config/package-json.d.mts +68 -0
  35. package/dist/core/config/package-json.mjs +1 -0
  36. package/dist/core/errors/index.d.mts +126 -0
  37. package/dist/core/errors/index.mjs +1 -0
  38. package/dist/core/execution/index.d.mts +49 -0
  39. package/dist/core/execution/index.mjs +1 -0
  40. package/dist/core/help/index.d.mts +49 -0
  41. package/dist/core/help/index.mjs +8 -0
  42. package/dist/core/json-schema/index.d.mts +109 -0
  43. package/dist/core/json-schema/index.mjs +55 -0
  44. package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
  45. package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
  46. package/dist/core/output/activity.d.mts +194 -0
  47. package/dist/core/output/activity.mjs +1 -0
  48. package/dist/core/output/contracts.d.mts +88 -0
  49. package/dist/core/output/contracts.mjs +1 -0
  50. package/dist/core/output/display-value.d.mts +19 -0
  51. package/dist/core/output/display-value.mjs +1 -0
  52. package/dist/core/output/index.d.mts +280 -0
  53. package/dist/core/output/index.mjs +2 -0
  54. package/dist/core/output/renderers.d.mts +46 -0
  55. package/dist/core/output/renderers.mjs +1 -0
  56. package/dist/core/output/writer.d.mts +40 -0
  57. package/dist/core/output/writer.mjs +1 -0
  58. package/dist/core/parse/index.d.mts +79 -0
  59. package/dist/core/parse/index.mjs +1 -0
  60. package/dist/core/prompt/index.d.mts +205 -0
  61. package/dist/core/prompt/index.mjs +6 -0
  62. package/dist/core/resolve/args.d.mts +8 -0
  63. package/dist/core/resolve/args.mjs +1 -0
  64. package/dist/core/resolve/coerce.d.mts +22 -0
  65. package/dist/core/resolve/coerce.mjs +1 -0
  66. package/dist/core/resolve/config.d.mts +10 -0
  67. package/dist/core/resolve/config.mjs +1 -0
  68. package/dist/core/resolve/contracts.d.mts +112 -0
  69. package/dist/core/resolve/errors.d.mts +11 -0
  70. package/dist/core/resolve/errors.mjs +2 -0
  71. package/dist/core/resolve/flags.d.mts +10 -0
  72. package/dist/core/resolve/flags.mjs +1 -0
  73. package/dist/core/resolve/index.d.mts +42 -0
  74. package/dist/core/resolve/index.mjs +1 -0
  75. package/dist/core/resolve/property.d.mts +47 -0
  76. package/dist/core/resolve/property.mjs +1 -0
  77. package/dist/core/schema/activity.d.mts +169 -0
  78. package/dist/core/schema/arg.d.mts +559 -0
  79. package/dist/core/schema/arg.mjs +1 -0
  80. package/dist/core/schema/command.d.mts +960 -0
  81. package/dist/core/schema/command.mjs +1 -0
  82. package/dist/core/schema/flag.d.mts +491 -0
  83. package/dist/core/schema/flag.mjs +1 -0
  84. package/dist/core/schema/index.d.mts +8 -0
  85. package/dist/core/schema/middleware.d.mts +122 -0
  86. package/dist/core/schema/middleware.mjs +1 -0
  87. package/dist/core/schema/prompt.d.mts +117 -0
  88. package/dist/core/schema/run.d.mts +171 -0
  89. package/dist/core/schema-dsl/runtime.d.mts +144 -0
  90. package/dist/core/schema-dsl/runtime.mjs +2 -0
  91. package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
  92. package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
  93. package/dist/core/testkit/index.d.mts +54 -0
  94. package/dist/core/testkit/index.mjs +1 -0
  95. package/dist/index.d.mts +28 -920
  96. package/dist/index.mjs +1 -10
  97. package/dist/runtime/adapter.d.mts +212 -0
  98. package/dist/{adapter-B37d9oia.mjs → runtime/adapter.mjs} +1 -1
  99. package/dist/runtime/auto.d.mts +26 -0
  100. package/dist/runtime/auto.mjs +1 -0
  101. package/dist/runtime/bun.d.mts +28 -0
  102. package/dist/runtime/bun.mjs +1 -0
  103. package/dist/runtime/deno.d.mts +76 -0
  104. package/dist/runtime/deno.mjs +2 -0
  105. package/dist/runtime/detect.d.mts +86 -0
  106. package/dist/runtime/detect.mjs +1 -0
  107. package/dist/runtime/index.d.mts +7 -0
  108. package/dist/runtime/node.d.mts +65 -0
  109. package/dist/runtime/node.mjs +2 -0
  110. package/dist/runtime/paths.d.mts +31 -0
  111. package/dist/runtime/paths.mjs +1 -0
  112. package/dist/runtime/support.d.mts +42 -0
  113. package/dist/runtime/support.mjs +1 -0
  114. package/dist/runtime.d.mts +6 -252
  115. package/dist/runtime.mjs +1 -1
  116. package/dist/testkit.d.mts +5 -24
  117. package/dist/testkit.mjs +1 -1
  118. package/dist/version.d.mts +16 -0
  119. package/dist/version.mjs +1 -0
  120. package/dreamcli.schema.json +338 -0
  121. package/examples/basic.ts +2 -2
  122. package/examples/gh/package.json +7 -11
  123. package/examples/gh/src/commands/auth.ts +2 -2
  124. package/examples/gh/src/commands/issue.ts +4 -4
  125. package/examples/gh/src/commands/pr.ts +4 -4
  126. package/examples/gh/src/docs.ts +11 -0
  127. package/examples/gh/src/lib/auth.ts +1 -1
  128. package/examples/gh/src/main.test.ts +6 -5
  129. package/examples/gh/src/main.ts +8 -6
  130. package/examples/interactive.ts +3 -3
  131. package/examples/json-mode.ts +4 -6
  132. package/examples/middleware.ts +3 -3
  133. package/examples/multi-command.ts +3 -3
  134. package/examples/spinner-progress.ts +5 -5
  135. package/examples/testing.ts +8 -6
  136. package/package.json +70 -44
  137. package/src/core/cli/dispatch.ts +4 -0
  138. package/src/core/cli/index.ts +185 -632
  139. package/src/core/cli/planner.ts +413 -0
  140. package/src/core/cli/plugin.ts +7 -1
  141. package/src/core/cli/propagate.ts +1 -1
  142. package/src/core/cli/runtime-preflight.ts +409 -0
  143. package/src/core/completion/index.ts +15 -9
  144. package/src/core/completion/shells/bash.ts +6 -3
  145. package/src/core/completion/shells/fish.ts +245 -10
  146. package/src/core/completion/shells/powershell.ts +390 -9
  147. package/src/core/completion/shells/shared.ts +4 -4
  148. package/src/core/completion/shells/zsh.ts +12 -7
  149. package/src/core/config/index.ts +7 -4
  150. package/src/core/config/package-json.ts +6 -2
  151. package/src/core/errors/index.ts +23 -8
  152. package/src/core/execution/index.ts +270 -0
  153. package/src/core/help/index.ts +13 -15
  154. package/src/core/json-schema/index.ts +193 -7
  155. package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
  156. package/src/core/output/contracts.ts +194 -0
  157. package/src/core/output/index.ts +47 -82
  158. package/src/core/output/renderers.ts +125 -0
  159. package/src/core/parse/index.ts +39 -21
  160. package/src/core/prompt/index.ts +44 -27
  161. package/src/core/resolve/args.ts +144 -0
  162. package/src/core/resolve/coerce.ts +432 -0
  163. package/src/core/resolve/config.ts +26 -0
  164. package/src/core/resolve/contracts.ts +135 -0
  165. package/src/core/resolve/errors.ts +227 -0
  166. package/src/core/resolve/flags.ts +205 -0
  167. package/src/core/resolve/index.ts +41 -1264
  168. package/src/core/resolve/property.ts +99 -0
  169. package/src/core/schema/activity.ts +3 -0
  170. package/src/core/schema/arg.ts +26 -14
  171. package/src/core/schema/command.ts +265 -38
  172. package/src/core/schema/flag.ts +120 -15
  173. package/src/core/schema/index.ts +11 -2
  174. package/src/core/schema/middleware.ts +6 -6
  175. package/src/core/schema/prompt.ts +9 -1
  176. package/src/core/schema/run.ts +25 -17
  177. package/src/core/schema-dsl/index.ts +109 -0
  178. package/src/core/schema-dsl/parse.ts +262 -0
  179. package/src/core/schema-dsl/runtime.ts +609 -0
  180. package/src/core/schema-dsl/to-json-schema.ts +102 -0
  181. package/src/core/testkit/index.ts +55 -297
  182. package/src/index.ts +10 -4
  183. package/src/runtime/adapter.ts +13 -10
  184. package/src/runtime/auto.ts +3 -3
  185. package/src/runtime/bun.ts +4 -4
  186. package/src/runtime/deno.ts +43 -29
  187. package/src/runtime/detect.ts +4 -1
  188. package/src/runtime/index.ts +1 -1
  189. package/src/runtime/node.ts +43 -21
  190. package/src/runtime/paths.ts +9 -3
  191. package/src/runtime/support.ts +20 -4
  192. package/src/runtime.ts +1 -1
  193. package/src/testkit.ts +10 -8
  194. package/dist/adapter-CCSh5juX.cjs +0 -1
  195. package/dist/adapter-DIwO-q7K.d.mts +0 -3447
  196. package/dist/adapter-DQnxxLiE.d.cts +0 -3447
  197. package/dist/auto-5cjZaF9V.mjs +0 -3
  198. package/dist/auto-B0eSgoDw.cjs +0 -3
  199. package/dist/index.cjs +0 -10
  200. package/dist/index.d.cts +0 -920
  201. package/dist/runtime.cjs +0 -1
  202. package/dist/runtime.d.cts +0 -253
  203. package/dist/testkit-CEDYPvhF.mjs +0 -14
  204. package/dist/testkit-ClIKijxC.cjs +0 -14
  205. package/dist/testkit.cjs +0 -1
  206. package/dist/testkit.d.cts +0 -25
  207. package/examples/gh/tsconfig.json +0 -37
  208. package/examples/tsconfig.json +0 -17
  209. package/src/core/cli/AGENTS.md +0 -72
  210. package/src/core/completion/AGENTS.md +0 -72
  211. package/src/core/completion/completion-test-helpers.ts +0 -48
  212. package/src/core/output/AGENTS.md +0 -69
  213. package/src/core/resolve/AGENTS.md +0 -69
  214. package/src/core/schema/AGENTS.md +0 -61
  215. package/src/core/testkit/AGENTS.md +0 -55
  216. package/src/runtime/AGENTS.md +0 -74
  217. package/src/runtime/test-helpers.ts +0 -40
@@ -7,11 +7,11 @@
7
7
  * - `createTerminalPrompter(read, write)` — line-based terminal I/O
8
8
  * - `createTestPrompter(answers)` — pre-configured answers for testing
9
9
  *
10
- * Custom engines implement the `PromptEngine` interface to swap in
10
+ * Custom engines implement the {@linkcode PromptEngine} interface to swap in
11
11
  * alternative UI (e.g. web-based, TUI library, etc.).
12
12
  *
13
- * The engine receives a `ResolvedPromptConfig` — a variant of
14
- * `PromptConfig` where select/multiselect choices are guaranteed
13
+ * The engine receives a {@linkcode ResolvedPromptConfig} — a variant of
14
+ * {@linkcode PromptConfig} where select/multiselect choices are guaranteed
15
15
  * non-empty. The resolution chain handles merging enum values from
16
16
  * `FlagSchema` into choices before calling the engine.
17
17
  *
@@ -33,31 +33,39 @@ import type {
33
33
  * A select prompt config with choices guaranteed non-empty.
34
34
  *
35
35
  * The resolution chain populates choices from `FlagSchema.enumValues`
36
- * when the user's `PromptConfig` omits them.
36
+ * when the user's {@linkcode PromptConfig} omits them.
37
37
  */
38
38
  interface ResolvedSelectPromptConfig {
39
+ /** Discriminant — single-choice selection prompt. */
39
40
  readonly kind: 'select';
41
+ /** User-facing question text. */
40
42
  readonly message: string;
43
+ /** Non-empty list of selectable options (populated from flag enum values when omitted). */
41
44
  readonly choices: readonly [SelectChoice, ...SelectChoice[]];
42
45
  }
43
46
 
44
47
  /**
45
48
  * A multiselect prompt config with choices guaranteed non-empty.
46
49
  *
47
- * Same guarantee as `ResolvedSelectPromptConfig` — choices are always
50
+ * Same guarantee as {@linkcode ResolvedSelectPromptConfig} — choices are always
48
51
  * present and non-empty.
49
52
  */
50
53
  interface ResolvedMultiselectPromptConfig {
54
+ /** Discriminant — multiple-choice selection prompt. */
51
55
  readonly kind: 'multiselect';
56
+ /** User-facing question text. */
52
57
  readonly message: string;
58
+ /** Non-empty list of selectable options (populated from flag enum values when omitted). */
53
59
  readonly choices: readonly [SelectChoice, ...SelectChoice[]];
60
+ /** Minimum number of selections required (validated after input). */
54
61
  readonly min?: number;
62
+ /** Maximum number of selections allowed (validated after input). */
55
63
  readonly max?: number;
56
64
  }
57
65
 
58
66
  /**
59
67
  * Prompt config variant where select/multiselect choices are guaranteed
60
- * present. The prompt engine receives this (not raw `PromptConfig`),
68
+ * present. The prompt engine receives this (not raw {@linkcode PromptConfig}),
61
69
  * so it never needs to merge enum values from `FlagSchema`.
62
70
  *
63
71
  * confirm and input configs pass through unchanged.
@@ -147,7 +155,7 @@ const PROMPT_CANCEL: unique symbol = Symbol.for('dreamcli.prompt.cancel') as typ
147
155
  * - `string` for `input` and `select`
148
156
  * - `boolean` for `confirm`
149
157
  * - `string[]` for `multiselect`
150
- * - {@link PROMPT_CANCEL} to simulate user cancellation
158
+ * - `PROMPT_CANCEL` to simulate user cancellation
151
159
  *
152
160
  * Because the type is intentionally `unknown`, tests may also inject malformed
153
161
  * answers to exercise downstream validation and error reporting.
@@ -181,7 +189,7 @@ interface TestPrompterOptions {
181
189
  * @param answers - Ordered queue of answers. Use `PROMPT_CANCEL` for
182
190
  * cancellation.
183
191
  * @param options - Controls behavior when the queue is exhausted.
184
- * @returns A `PromptEngine` suitable for testing.
192
+ * @returns A {@linkcode PromptEngine} suitable for testing.
185
193
  *
186
194
  * @example
187
195
  * ```ts
@@ -224,9 +232,9 @@ function createTestPrompter(
224
232
  /**
225
233
  * Create a prompt engine backed by line-based terminal I/O.
226
234
  *
227
- * Uses a `ReadFn` for input and a `WriteFn` for output. This is the
235
+ * Uses a {@linkcode ReadFn} for input and a {@linkcode WriteFn} for output. This is the
228
236
  * built-in renderer — sufficient for most CLI use cases. For richer
229
- * TUI experiences, users can implement `PromptEngine` with a library
237
+ * TUI experiences, users can implement {@linkcode PromptEngine} with a library
230
238
  * like `@clack/prompts` or `inquirer`.
231
239
  *
232
240
  * The prompter does **not** use raw mode — all input is line-based.
@@ -235,7 +243,7 @@ function createTestPrompter(
235
243
  *
236
244
  * @param read - Line reader function (returns `null` on EOF)
237
245
  * @param write - Output writer function
238
- * @returns A `PromptEngine` that prompts via terminal I/O
246
+ * @returns A {@linkcode PromptEngine} that prompts via terminal I/O
239
247
  *
240
248
  * @example
241
249
  * ```ts
@@ -275,7 +283,7 @@ const MAX_RETRIES = 10;
275
283
  /**
276
284
  * Confirm prompt: yes/no question.
277
285
  *
278
- * Displays `(Y/n)` or `(y/N)` depending on the default (if any).
286
+ * Displays `(Y/n)` because empty input defaults to yes.
279
287
  * Accepts: y, yes, n, no, empty (uses default). Case-insensitive.
280
288
  *
281
289
  * @param config - {@link ConfirmPromptConfig} with the question message
@@ -288,24 +296,33 @@ async function promptConfirm(
288
296
  read: ReadFn,
289
297
  write: WriteFn,
290
298
  ): Promise<PromptResult> {
291
- const hint = '(y/n)';
292
- write(`${config.message} ${hint} `);
299
+ const defaultValue = true;
300
+ let retries = 0;
293
301
 
294
- const line = await read();
295
- if (line === null) return { answered: false };
302
+ while (retries < MAX_RETRIES) {
303
+ const hint = defaultValue ? '(Y/n)' : '(y/N)';
304
+ write(`${config.message} ${hint} `);
296
305
 
297
- const lower = line.trim().toLowerCase();
298
- if (lower === '' || lower === 'y' || lower === 'yes') {
299
- return { answered: true, value: true };
300
- }
301
- if (lower === 'n' || lower === 'no') {
302
- return { answered: true, value: false };
306
+ const line = await read();
307
+ if (line === null) return { answered: false };
308
+
309
+ const lower = line.trim().toLowerCase();
310
+ if (lower === '') {
311
+ return { answered: true, value: defaultValue };
312
+ }
313
+ if (lower === 'y' || lower === 'yes') {
314
+ return { answered: true, value: true };
315
+ }
316
+ if (lower === 'n' || lower === 'no') {
317
+ return { answered: true, value: false };
318
+ }
319
+
320
+ write('Please answer y or n.\n');
321
+ retries += 1;
303
322
  }
304
323
 
305
- // Invalid input — treat as true for leniency (matches common CLI convention)
306
- // Note: the resolver will handle type coercion if needed
307
- write('Please answer y or n.\n');
308
- return promptConfirm(config, read, write);
324
+ write('Too many invalid attempts.\n');
325
+ return { answered: false };
309
326
  }
310
327
 
311
328
  /**
@@ -503,7 +520,7 @@ async function promptMultiselect(
503
520
  // --- Utility: prepare resolved prompt config from raw config + flag schema
504
521
 
505
522
  /**
506
- * Prepare a `ResolvedPromptConfig` from a raw `PromptConfig` and optional
523
+ * Prepare a {@linkcode ResolvedPromptConfig} from a raw {@linkcode PromptConfig} and optional
507
524
  * enum values from the flag schema.
508
525
  *
509
526
  * For select/multiselect prompts without explicit choices, this merges
@@ -0,0 +1,144 @@
1
+ /**
2
+ * Internal arg resolution helpers.
3
+ *
4
+ * @module dreamcli/core/resolve/args
5
+ * @internal
6
+ */
7
+
8
+ import { ValidationError } from '#internals/core/errors/index.ts';
9
+ import type { ArgSchema, CommandArgEntry } from '#internals/core/schema/index.ts';
10
+ import { coerceArgStringValue } from './coerce.ts';
11
+ import type { DeprecationWarning } from './contracts.ts';
12
+ import { isNonEmpty, throwAggregatedErrors } from './errors.ts';
13
+
14
+ /** Walk every declared arg through the resolution chain (cli -> stdin -> env -> default), collecting deprecations and throwing aggregated errors. */
15
+ function resolveArgs(
16
+ argEntries: readonly CommandArgEntry[],
17
+ parsedArgs: Readonly<Record<string, unknown>>,
18
+ stdinData: string | null | undefined,
19
+ env: Readonly<Record<string, string | undefined>>,
20
+ deprecations: DeprecationWarning[],
21
+ ): Readonly<Record<string, unknown>> {
22
+ const resolved: Record<string, unknown> = {};
23
+ const errors: ValidationError[] = [];
24
+
25
+ for (const entry of argEntries) {
26
+ const { name, schema } = entry;
27
+ const hasParsedValue = Object.hasOwn(parsedArgs, name);
28
+ const parsedValue = parsedArgs[name];
29
+ const usesCliValue =
30
+ hasParsedValue &&
31
+ parsedValue !== undefined &&
32
+ (!schema.stdinMode || parsedValue !== '-') &&
33
+ !(schema.variadic && Array.isArray(parsedValue) && parsedValue.length === 0);
34
+
35
+ if (usesCliValue) {
36
+ if (schema.deprecated !== undefined) {
37
+ deprecations.push({ kind: 'arg', name, message: schema.deprecated });
38
+ }
39
+ resolved[name] = parsedValue;
40
+ continue;
41
+ }
42
+
43
+ if (schema.stdinMode && (!hasParsedValue || parsedValue === undefined || parsedValue === '-')) {
44
+ if (stdinData !== undefined && stdinData !== null) {
45
+ const coerced = coerceArgStringValue(name, { kind: 'stdin' }, stdinData, schema);
46
+ if (coerced.ok) {
47
+ if (schema.deprecated !== undefined) {
48
+ deprecations.push({ kind: 'arg', name, message: schema.deprecated });
49
+ }
50
+ resolved[name] = coerced.value;
51
+ continue;
52
+ }
53
+ errors.push(coerced.error);
54
+ continue;
55
+ }
56
+ }
57
+
58
+ if (schema.envVar !== undefined) {
59
+ const envValue = env[schema.envVar];
60
+ if (envValue !== undefined) {
61
+ const coerced = coerceArgStringValue(
62
+ name,
63
+ { kind: 'env', envVar: schema.envVar },
64
+ envValue,
65
+ schema,
66
+ );
67
+ if (coerced.ok) {
68
+ if (schema.deprecated !== undefined) {
69
+ deprecations.push({ kind: 'arg', name, message: schema.deprecated });
70
+ }
71
+ resolved[name] = coerced.value;
72
+ continue;
73
+ }
74
+ errors.push(coerced.error);
75
+ continue;
76
+ }
77
+ }
78
+
79
+ if (schema.defaultValue !== undefined) {
80
+ resolved[name] = schema.defaultValue;
81
+ continue;
82
+ }
83
+
84
+ if (schema.variadic) {
85
+ if (schema.presence === 'required') {
86
+ errors.push(
87
+ new ValidationError(`Missing required argument <${name}>`, {
88
+ code: 'REQUIRED_ARG',
89
+ details: { arg: name, variadic: true },
90
+ suggest: buildRequiredArgSuggest(name, schema, true),
91
+ }),
92
+ );
93
+ continue;
94
+ }
95
+ resolved[name] = [];
96
+ continue;
97
+ }
98
+
99
+ if (schema.presence === 'required') {
100
+ errors.push(
101
+ new ValidationError(`Missing required argument <${name}>`, {
102
+ code: 'REQUIRED_ARG',
103
+ details: { arg: name },
104
+ suggest: buildRequiredArgSuggest(name, schema),
105
+ }),
106
+ );
107
+ continue;
108
+ }
109
+
110
+ resolved[name] = undefined;
111
+ }
112
+
113
+ if (isNonEmpty(errors)) {
114
+ throwAggregatedErrors(errors);
115
+ }
116
+
117
+ return resolved;
118
+ }
119
+
120
+ function buildRequiredArgSuggest(name: string, schema: ArgSchema, variadic?: boolean): string {
121
+ const sources: [string, ...string[]] = [
122
+ variadic ? `Provide at least one value for <${name}>` : `Provide a value for <${name}>`,
123
+ ];
124
+
125
+ if (schema.stdinMode) {
126
+ sources.push(`pipe a value to stdin or pass '-'`);
127
+ }
128
+
129
+ if (schema.envVar !== undefined) {
130
+ sources.push(`set ${schema.envVar}`);
131
+ }
132
+
133
+ if (sources.length === 1) {
134
+ return sources[0];
135
+ }
136
+
137
+ if (sources.length === 2) {
138
+ return `${sources[0]} or ${sources[1]}`;
139
+ }
140
+
141
+ return `${sources.slice(0, -1).join(', ')}, or ${sources[sources.length - 1]}`;
142
+ }
143
+
144
+ export { resolveArgs };