@kjanat/dreamcli 2.5.0 → 3.0.0-rc.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (202) hide show
  1. package/CHANGELOG.md +344 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/dispatch.d.mts +6 -5
  4. package/dist/core/cli/dispatch.mjs +205 -1
  5. package/dist/core/cli/help-links.d.mts +0 -1
  6. package/dist/core/cli/help-links.mjs +41 -1
  7. package/dist/core/cli/index.d.mts +185 -19
  8. package/dist/core/cli/index.mjs +945 -1
  9. package/dist/core/cli/planner.d.mts +32 -6
  10. package/dist/core/cli/planner.mjs +300 -1
  11. package/dist/core/cli/plugin.d.mts +1 -1
  12. package/dist/core/cli/plugin.mjs +41 -1
  13. package/dist/core/cli/propagate.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +57 -1
  15. package/dist/core/cli/root-help.d.mts +18 -3
  16. package/dist/core/cli/root-help.mjs +226 -6
  17. package/dist/core/cli/root-surface.d.mts +30 -4
  18. package/dist/core/cli/root-surface.mjs +28 -1
  19. package/dist/core/cli/runtime-preflight.d.mts +30 -3
  20. package/dist/core/cli/runtime-preflight.mjs +169 -1
  21. package/dist/core/completion/index.d.mts +32 -2
  22. package/dist/core/completion/index.mjs +90 -1
  23. package/dist/core/completion/shells/bash.d.mts +0 -1
  24. package/dist/core/completion/shells/bash.mjs +308 -3
  25. package/dist/core/completion/shells/fish.d.mts +0 -1
  26. package/dist/core/completion/shells/fish.mjs +162 -2
  27. package/dist/core/completion/shells/powershell.d.mts +0 -1
  28. package/dist/core/completion/shells/powershell.mjs +358 -2
  29. package/dist/core/completion/shells/shared.d.mts +23 -2
  30. package/dist/core/completion/shells/shared.mjs +176 -1
  31. package/dist/core/completion/shells/zsh.d.mts +0 -1
  32. package/dist/core/completion/shells/zsh.mjs +251 -2
  33. package/dist/core/config/index.d.mts +2 -3
  34. package/dist/core/config/index.mjs +246 -1
  35. package/dist/core/config/package-json.d.mts +27 -4
  36. package/dist/core/config/package-json.mjs +386 -3
  37. package/dist/core/errors/index.d.mts +3 -3
  38. package/dist/core/errors/index.mjs +87 -1
  39. package/dist/core/execution/index.d.mts +0 -1
  40. package/dist/core/execution/index.mjs +201 -1
  41. package/dist/core/help/ansi.d.mts +11 -5
  42. package/dist/core/help/ansi.mjs +121 -2
  43. package/dist/core/help/index.d.mts +65 -2
  44. package/dist/core/help/index.mjs +341 -7
  45. package/dist/core/help/theme.d.mts +68 -0
  46. package/dist/core/help/theme.mjs +46 -0
  47. package/dist/core/json-schema/index.d.mts +15 -2
  48. package/dist/core/json-schema/index.mjs +536 -12
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
  51. package/dist/core/output/activity.d.mts +0 -1
  52. package/dist/core/output/activity.mjs +452 -1
  53. package/dist/core/output/bind.mjs +56 -1
  54. package/dist/core/output/contracts.d.mts +4 -5
  55. package/dist/core/output/contracts.mjs +57 -1
  56. package/dist/core/output/display-value.mjs +32 -1
  57. package/dist/core/output/index.d.mts +21 -1
  58. package/dist/core/output/index.mjs +442 -2
  59. package/dist/core/output/renderers.d.mts +0 -1
  60. package/dist/core/output/renderers.mjs +46 -1
  61. package/dist/core/output/writer.mjs +12 -1
  62. package/dist/core/parse/index.d.mts +54 -7
  63. package/dist/core/parse/index.mjs +727 -1
  64. package/dist/core/prompt/index.d.mts +12 -4
  65. package/dist/core/prompt/index.mjs +348 -6
  66. package/dist/core/resolve/args.d.mts +1 -1
  67. package/dist/core/resolve/args.mjs +105 -1
  68. package/dist/core/resolve/coerce.d.mts +1 -1
  69. package/dist/core/resolve/coerce.mjs +336 -1
  70. package/dist/core/resolve/config.mjs +19 -1
  71. package/dist/core/resolve/contracts.d.mts +9 -4
  72. package/dist/core/resolve/errors.d.mts +0 -1
  73. package/dist/core/resolve/errors.mjs +140 -2
  74. package/dist/core/resolve/flags.d.mts +7 -2
  75. package/dist/core/resolve/flags.mjs +251 -1
  76. package/dist/core/resolve/index.d.mts +2 -2
  77. package/dist/core/resolve/index.mjs +85 -1
  78. package/dist/core/resolve/property.d.mts +6 -2
  79. package/dist/core/resolve/property.mjs +53 -1
  80. package/dist/core/schema/activity.d.mts +31 -11
  81. package/dist/core/schema/arg.d.mts +92 -13
  82. package/dist/core/schema/arg.mjs +463 -1
  83. package/dist/core/schema/command.d.mts +29 -7
  84. package/dist/core/schema/command.mjs +726 -1
  85. package/dist/core/schema/flag.d.mts +577 -21
  86. package/dist/core/schema/flag.mjs +705 -1
  87. package/dist/core/schema/index.d.mts +5 -2
  88. package/dist/core/schema/middleware.d.mts +4 -3
  89. package/dist/core/schema/middleware.mjs +41 -1
  90. package/dist/core/schema/number-constraints.d.mts +96 -0
  91. package/dist/core/schema/number-constraints.mjs +60 -0
  92. package/dist/core/schema/prompt.d.mts +21 -3
  93. package/dist/core/schema/run.d.mts +24 -5
  94. package/dist/core/schema/string-constraints.d.mts +97 -0
  95. package/dist/core/schema/string-constraints.mjs +69 -0
  96. package/dist/core/schema/value-parsers.d.mts +78 -0
  97. package/dist/core/schema/value-parsers.mjs +142 -0
  98. package/dist/core/schema-dsl/runtime.mjs +271 -2
  99. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  100. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  101. package/dist/core/testkit/index.d.mts +9 -36
  102. package/dist/core/testkit/index.mjs +83 -1
  103. package/dist/index.d.mts +12 -6
  104. package/dist/index.mjs +22 -1
  105. package/dist/runtime/adapter.d.mts +38 -2
  106. package/dist/runtime/adapter.mjs +87 -1
  107. package/dist/runtime/auto.d.mts +2 -3
  108. package/dist/runtime/auto.mjs +45 -1
  109. package/dist/runtime/deno.d.mts +24 -5
  110. package/dist/runtime/deno.mjs +262 -2
  111. package/dist/runtime/detect.mjs +45 -1
  112. package/dist/runtime/index.d.mts +3 -4
  113. package/dist/runtime/node.d.mts +8 -2
  114. package/dist/runtime/node.mjs +220 -2
  115. package/dist/runtime/paths.mjs +48 -1
  116. package/dist/runtime.d.mts +4 -4
  117. package/dist/runtime.mjs +6 -1
  118. package/dist/strings.mjs +22 -1
  119. package/dist/testkit.d.mts +1 -0
  120. package/dist/testkit.mjs +5 -1
  121. package/dist/version.d.mts +7 -3
  122. package/dist/version.mjs +7 -1
  123. package/dreamcli.schema.json +36 -7
  124. package/examples/basic.ts +5 -1
  125. package/examples/gh/package.json +2 -7
  126. package/examples/pwsh-demo/package.json +1 -7
  127. package/examples/pwsh-demo/src/main.test.ts +1 -4
  128. package/examples/pwsh-demo/src/main.ts +14 -4
  129. package/examples/transport-launcher.ts +85 -0
  130. package/package.json +43 -49
  131. package/dist/runtime/bun.d.mts +0 -28
  132. package/dist/runtime/bun.mjs +0 -1
  133. package/dist/runtime/support.d.mts +0 -42
  134. package/dist/runtime/support.mjs +0 -1
  135. package/src/core/cli/dispatch.ts +0 -349
  136. package/src/core/cli/help-links.ts +0 -82
  137. package/src/core/cli/index.ts +0 -1413
  138. package/src/core/cli/planner.ts +0 -487
  139. package/src/core/cli/plugin.ts +0 -117
  140. package/src/core/cli/propagate.ts +0 -97
  141. package/src/core/cli/root-help.ts +0 -252
  142. package/src/core/cli/root-surface.ts +0 -74
  143. package/src/core/cli/runtime-preflight.ts +0 -438
  144. package/src/core/completion/index.ts +0 -88
  145. package/src/core/completion/shells/bash.ts +0 -459
  146. package/src/core/completion/shells/fish.ts +0 -259
  147. package/src/core/completion/shells/powershell.ts +0 -439
  148. package/src/core/completion/shells/shared.ts +0 -283
  149. package/src/core/completion/shells/zsh.ts +0 -381
  150. package/src/core/config/index.ts +0 -417
  151. package/src/core/config/package-json.ts +0 -560
  152. package/src/core/errors/index.ts +0 -193
  153. package/src/core/execution/index.ts +0 -268
  154. package/src/core/help/ansi.ts +0 -144
  155. package/src/core/help/index.ts +0 -516
  156. package/src/core/json-schema/index.ts +0 -891
  157. package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
  158. package/src/core/output/activity.ts +0 -575
  159. package/src/core/output/bind.ts +0 -59
  160. package/src/core/output/contracts.ts +0 -194
  161. package/src/core/output/display-value.ts +0 -48
  162. package/src/core/output/index.ts +0 -704
  163. package/src/core/output/renderers.ts +0 -125
  164. package/src/core/output/writer.ts +0 -46
  165. package/src/core/parse/index.ts +0 -681
  166. package/src/core/prompt/index.ts +0 -583
  167. package/src/core/resolve/args.ts +0 -144
  168. package/src/core/resolve/coerce.ts +0 -432
  169. package/src/core/resolve/config.ts +0 -26
  170. package/src/core/resolve/contracts.ts +0 -135
  171. package/src/core/resolve/errors.ts +0 -227
  172. package/src/core/resolve/flags.ts +0 -255
  173. package/src/core/resolve/index.ts +0 -108
  174. package/src/core/resolve/property.ts +0 -99
  175. package/src/core/schema/activity.ts +0 -240
  176. package/src/core/schema/arg.ts +0 -719
  177. package/src/core/schema/command.ts +0 -1498
  178. package/src/core/schema/flag.ts +0 -801
  179. package/src/core/schema/index.ts +0 -91
  180. package/src/core/schema/middleware.ts +0 -171
  181. package/src/core/schema/prompt.ts +0 -156
  182. package/src/core/schema/run.ts +0 -198
  183. package/src/core/schema-dsl/index.ts +0 -109
  184. package/src/core/schema-dsl/parse.ts +0 -262
  185. package/src/core/schema-dsl/runtime.ts +0 -609
  186. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  187. package/src/core/testkit/index.ts +0 -123
  188. package/src/index.ts +0 -179
  189. package/src/runtime/adapter.ts +0 -303
  190. package/src/runtime/auto.ts +0 -110
  191. package/src/runtime/bun.ts +0 -55
  192. package/src/runtime/deno.ts +0 -369
  193. package/src/runtime/detect.ts +0 -105
  194. package/src/runtime/index.ts +0 -21
  195. package/src/runtime/node-builtins.d.ts +0 -27
  196. package/src/runtime/node.ts +0 -300
  197. package/src/runtime/paths.ts +0 -64
  198. package/src/runtime/support.ts +0 -135
  199. package/src/runtime.ts +0 -31
  200. package/src/strings.ts +0 -34
  201. package/src/testkit.ts +0 -25
  202. package/src/version.ts +0 -20
@@ -1,6 +1,6 @@
1
1
  import { ConfirmPromptConfig, InputPromptConfig, PromptConfig, PromptResult, SelectChoice } from "../schema/prompt.mjs";
2
2
  import { WriteFn } from "../output/writer.mjs";
3
-
3
+ import "../output/index.mjs";
4
4
  //#region src/core/prompt/index.d.ts
5
5
  /**
6
6
  * A select prompt config with choices guaranteed non-empty.
@@ -105,9 +105,11 @@ declare const PROMPT_CANCEL: unique symbol;
105
105
  * A queued answer consumed by {@link createTestPrompter}.
106
106
  *
107
107
  * The test prompter returns these values exactly as provided; it does not
108
- * coerce or validate them. The normal resolution pipeline performs any later
109
- * type coercion, so tests can supply values in the same shapes real prompts
110
- * would yield:
108
+ * coerce them. The one exception mirrors the terminal prompter: a string answer
109
+ * to an `input` prompt is run through the prompt's `validate` function, and a
110
+ * failing answer is rejected as a cancellation (see {@link createTestPrompter}).
111
+ * The normal resolution pipeline performs any later type coercion, so tests can
112
+ * supply values in the same shapes real prompts would yield:
111
113
  *
112
114
  * - `string` for `input` and `select`
113
115
  * - `boolean` for `confirm`
@@ -139,6 +141,12 @@ interface TestPrompterOptions {
139
141
  * Pass `PROMPT_CANCEL` as an answer to simulate the user cancelling
140
142
  * that prompt.
141
143
  *
144
+ * For `input` prompts that declare a `validate` function, a string answer is
145
+ * validated just as the terminal prompter does. An answer that fails validation
146
+ * is rejected as a cancellation (`{ answered: false }`) — mirroring the terminal
147
+ * prompter exhausting its retries — so prompt validation is integration-testable
148
+ * via {@linkcode runCommand} rather than silently accepted as the resolved value.
149
+ *
142
150
  * @param answers - Ordered queue of answers. Use `PROMPT_CANCEL` for
143
151
  * cancellation.
144
152
  * @param options - Controls behavior when the queue is exhausted.
@@ -1,6 +1,348 @@
1
- const e=Symbol.for(`dreamcli.prompt.cancel`);function t(t,n){let r=0;return{promptOne(){if(r>=t.length)return n?.onExhausted===`cancel`?Promise.resolve({answered:!1}):Promise.reject(Error(`Test prompter exhausted: expected at most ${t.length} prompts, got prompt #${r+1}`));let i=t[r];return r+=1,i===e?Promise.resolve({answered:!1}):Promise.resolve({answered:!0,value:i})}}}function n(e,t){return{promptOne(n){switch(n.kind){case`confirm`:return r(n,e,t);case`input`:return i(n,e,t);case`select`:return a(n,e,t);case`multiselect`:return o(n,e,t)}}}}async function r(e,t,n){let r=0;for(;r<10;){n(`${e.message} (Y/n) `);let i=await t();if(i===null)return{answered:!1};let a=i.trim().toLowerCase();if(a===``||a===`y`||a===`yes`)return{answered:!0,value:!0};if(a===`n`||a===`no`)return{answered:!0,value:!1};n(`Please answer y or n.
2
- `),r+=1}return n(`Too many invalid attempts.
3
- `),{answered:!1}}async function i(e,t,n){let r=0;for(;r<10;){let i=e.placeholder===void 0?``:` (${e.placeholder})`;n(`${e.message}${i}: `);let a=await t();if(a===null)return{answered:!1};let o=a.trim();if(e.validate!==void 0){let t=e.validate(o);if(t!==!0){n(`${t}\n`),r+=1;continue}}return{answered:!0,value:o}}return n(`Too many invalid attempts.
4
- `),{answered:!1}}async function a(e,t,n){let r=0;for(;r<10;){n(`${e.message}\n`);for(let t=0;t<e.choices.length;t+=1){let r=e.choices[t];if(r===void 0)continue;let i=r.label??r.value,a=r.description===void 0?``:` - ${r.description}`;n(` ${t+1}) ${i}${a}\n`)}n(`Enter number: `);let i=await t();if(i===null)return{answered:!1};let a=Number(i.trim());if(Number.isNaN(a)||!Number.isInteger(a)||a<1||a>e.choices.length){n(`Please enter a number between 1 and ${e.choices.length}.\n`),r+=1;continue}let o=e.choices[a-1];if(o===void 0){r+=1;continue}return{answered:!0,value:o.value}}return n(`Too many invalid attempts.
5
- `),{answered:!1}}async function o(e,t,n){let r=0;for(;r<10;){n(`${e.message}\n`);for(let t=0;t<e.choices.length;t+=1){let r=e.choices[t];if(r===void 0)continue;let i=r.label??r.value,a=r.description===void 0?``:` - ${r.description}`;n(` ${t+1}) ${i}${a}\n`)}n(`Enter numbers separated by commas (e.g. 1,3${e.min===void 0?``:`, min: ${e.min}`}${e.max===void 0?``:`, max: ${e.max}`}): `);let i=await t();if(i===null)return{answered:!1};let a=i.trim();if(a===``){if(e.min!==void 0&&e.min>0){n(`Please select at least ${e.min}.\n`),r+=1;continue}return{answered:!0,value:[]}}let o=a.split(`,`).map(e=>e.trim()),s=[],c=!0;for(let t of o){let r=Number(t);if(Number.isNaN(r)||!Number.isInteger(r)||r<1||r>e.choices.length){n(`Invalid selection '${t}'. Use numbers between 1 and ${e.choices.length}.\n`),c=!1;break}s.push(r)}if(!c){r+=1;continue}let l=[...new Set(s)];if(e.min!==void 0&&l.length<e.min){n(`Please select at least ${e.min}.\n`),r+=1;continue}if(e.max!==void 0&&l.length>e.max){n(`Please select at most ${e.max}.\n`),r+=1;continue}return{answered:!0,value:l.map(t=>e.choices[t-1]?.value??``)}}return n(`Too many invalid attempts.
6
- `),{answered:!1}}function s(e,t){if(e.kind===`confirm`||e.kind===`input`)return e;let n=e.choices??t?.map(e=>({value:e}))??[];if(n.length===0)throw Error(`Prompt config (${e.kind}) requires choices but none were provided and no enum values are available`);let r=n;return e.kind===`select`?{kind:`select`,message:e.message,choices:r}:{kind:`multiselect`,message:e.message,choices:r,...e.min===void 0?{}:{min:e.min},...e.max===void 0?{}:{max:e.max}}}export{e as PROMPT_CANCEL,n as createTerminalPrompter,t as createTestPrompter,s as resolvePromptConfig};
1
+ //#region src/core/prompt/index.ts
2
+ /**
3
+ * Sentinel value representing a cancelled/aborted prompt in the test
4
+ * prompter's answer queue.
5
+ *
6
+ * Uses `Symbol.for()` for cross-bundle safety — the same symbol is
7
+ * returned regardless of which copy of the module is loaded.
8
+ *
9
+ * @example
10
+ * ```ts
11
+ * const prompter = createTestPrompter([
12
+ * 'us', // first prompt answered 'us'
13
+ * PROMPT_CANCEL, // second prompt cancelled
14
+ * ]);
15
+ * ```
16
+ */
17
+ const PROMPT_CANCEL = Symbol.for("dreamcli.prompt.cancel");
18
+ /**
19
+ * Create a prompt engine that returns pre-configured answers.
20
+ *
21
+ * Each call to `promptOne` consumes the next answer from the queue.
22
+ * Pass `PROMPT_CANCEL` as an answer to simulate the user cancelling
23
+ * that prompt.
24
+ *
25
+ * For `input` prompts that declare a `validate` function, a string answer is
26
+ * validated just as the terminal prompter does. An answer that fails validation
27
+ * is rejected as a cancellation (`{ answered: false }`) — mirroring the terminal
28
+ * prompter exhausting its retries — so prompt validation is integration-testable
29
+ * via {@linkcode runCommand} rather than silently accepted as the resolved value.
30
+ *
31
+ * @param answers - Ordered queue of answers. Use `PROMPT_CANCEL` for
32
+ * cancellation.
33
+ * @param options - Controls behavior when the queue is exhausted.
34
+ * @returns A {@linkcode PromptEngine} suitable for testing.
35
+ *
36
+ * @example
37
+ * ```ts
38
+ * const prompter = createTestPrompter(['eu', true, PROMPT_CANCEL]);
39
+ *
40
+ * // First promptOne → { answered: true, value: 'eu' }
41
+ * // Second promptOne → { answered: true, value: true }
42
+ * // Third promptOne → { answered: false }
43
+ * ```
44
+ */
45
+ function createTestPrompter(answers, options) {
46
+ let index = 0;
47
+ return { promptOne(config) {
48
+ if (index >= answers.length) {
49
+ if (options?.onExhausted === "cancel") return Promise.resolve({ answered: false });
50
+ return Promise.reject(/* @__PURE__ */ new Error(`Test prompter exhausted: expected at most ${answers.length} prompts, got prompt #${index + 1}`));
51
+ }
52
+ const answer = answers[index];
53
+ index += 1;
54
+ if (answer === PROMPT_CANCEL) return Promise.resolve({ answered: false });
55
+ if (config.kind === "input" && config.validate !== void 0 && typeof answer === "string") {
56
+ if (config.validate(answer) !== true) return Promise.resolve({ answered: false });
57
+ }
58
+ return Promise.resolve({
59
+ answered: true,
60
+ value: answer
61
+ });
62
+ } };
63
+ }
64
+ /**
65
+ * Create a prompt engine backed by line-based terminal I/O.
66
+ *
67
+ * Uses a {@linkcode ReadFn} for input and a {@linkcode WriteFn} for output. This is the
68
+ * built-in renderer — sufficient for most CLI use cases. For richer
69
+ * TUI experiences, users can implement {@linkcode PromptEngine} with a library
70
+ * like `@clack/prompts` or `inquirer`.
71
+ *
72
+ * The prompter does **not** use raw mode — all input is line-based.
73
+ * This keeps the implementation portable across Node, Bun, and Deno
74
+ * without platform-specific stdin configuration.
75
+ *
76
+ * @param read - Line reader function (returns `null` on EOF)
77
+ * @param write - Output writer function
78
+ * @returns A {@linkcode PromptEngine} that prompts via terminal I/O
79
+ *
80
+ * @example
81
+ * ```ts
82
+ * import { createInterface } from 'readline';
83
+ *
84
+ * const rl = createInterface({ input: process.stdin, output: process.stdout });
85
+ * const read = () => new Promise<string | null>((resolve) => {
86
+ * rl.question('', (answer) => resolve(answer));
87
+ * });
88
+ * const write: WriteFn = (s) => process.stdout.write(s);
89
+ *
90
+ * const prompter = createTerminalPrompter(read, write);
91
+ * ```
92
+ */
93
+ function createTerminalPrompter(read, write) {
94
+ return { promptOne(config) {
95
+ switch (config.kind) {
96
+ case "confirm": return promptConfirm(config, read, write);
97
+ case "input": return promptInput(config, read, write);
98
+ case "select": return promptSelect(config, read, write);
99
+ case "multiselect": return promptMultiselect(config, read, write);
100
+ }
101
+ } };
102
+ }
103
+ /** Maximum retries for invalid input before treating as cancel. */
104
+ const MAX_RETRIES = 10;
105
+ /**
106
+ * Confirm prompt: yes/no question.
107
+ *
108
+ * The hint reflects {@link ConfirmPromptConfig.default}: `(Y/n)` when the
109
+ * default is `true` (or unset), `(y/N)` when `false`. An empty submission
110
+ * resolves to that default. Accepts: y, yes, n, no, empty. Case-insensitive.
111
+ *
112
+ * @param config - {@link ConfirmPromptConfig} with the question message and optional default
113
+ * @param read - {@link ReadFn} for reading a line of user input
114
+ * @param write - {@link WriteFn} for rendering prompt text
115
+ * @returns Resolved {@link PromptResult} — `true`/`false` value, or cancelled on EOF
116
+ */
117
+ async function promptConfirm(config, read, write) {
118
+ const defaultValue = config.default ?? true;
119
+ let retries = 0;
120
+ while (retries < MAX_RETRIES) {
121
+ const hint = defaultValue ? "(Y/n)" : "(y/N)";
122
+ write(`${config.message} ${hint} `);
123
+ const line = await read();
124
+ if (line === null) return { answered: false };
125
+ const lower = line.trim().toLowerCase();
126
+ if (lower === "") return {
127
+ answered: true,
128
+ value: defaultValue
129
+ };
130
+ if (lower === "y" || lower === "yes") return {
131
+ answered: true,
132
+ value: true
133
+ };
134
+ if (lower === "n" || lower === "no") return {
135
+ answered: true,
136
+ value: false
137
+ };
138
+ write("Please answer y or n.\n");
139
+ retries += 1;
140
+ }
141
+ write("Too many invalid attempts.\n");
142
+ return { answered: false };
143
+ }
144
+ /**
145
+ * Input prompt: free-text string entry.
146
+ *
147
+ * Displays the message and a hint listing the placeholder and/or
148
+ * {@link InputPromptConfig.default | default}, reads a line, and optionally
149
+ * validates via {@link InputPromptConfig.validate | validate}. When a default
150
+ * is configured, an empty submission resolves to it without running validation;
151
+ * otherwise an empty submission is returned verbatim (and treated as "no answer"
152
+ * by the resolver). Loops on invalid input up to `MAX_RETRIES`.
153
+ *
154
+ * @param config - {@link InputPromptConfig} with message, optional placeholder, default, and validator
155
+ * @param read - {@link ReadFn} for reading a line of user input
156
+ * @param write - {@link WriteFn} for rendering prompt text and validation errors
157
+ * @returns Resolved {@link PromptResult} — trimmed string value (or default), or cancelled on EOF/exhausted retries
158
+ */
159
+ async function promptInput(config, read, write) {
160
+ let retries = 0;
161
+ const hints = [];
162
+ if (config.placeholder !== void 0) hints.push(config.placeholder);
163
+ if (config.default !== void 0) hints.push(`default: ${config.default}`);
164
+ const hint = hints.length > 0 ? ` (${hints.join(", ")})` : "";
165
+ while (retries < MAX_RETRIES) {
166
+ write(`${config.message}${hint}: `);
167
+ const line = await read();
168
+ if (line === null) return { answered: false };
169
+ const trimmed = line.trim();
170
+ if (trimmed === "") return config.default !== void 0 ? {
171
+ answered: true,
172
+ value: config.default
173
+ } : {
174
+ answered: true,
175
+ value: ""
176
+ };
177
+ if (config.validate !== void 0) {
178
+ const result = config.validate(trimmed);
179
+ if (result !== true) {
180
+ write(`${result}\n`);
181
+ retries += 1;
182
+ continue;
183
+ }
184
+ }
185
+ return {
186
+ answered: true,
187
+ value: trimmed
188
+ };
189
+ }
190
+ write("Too many invalid attempts.\n");
191
+ return { answered: false };
192
+ }
193
+ /**
194
+ * Select prompt: single choice from a numbered list.
195
+ *
196
+ * Displays choices with 1-based indices. User enters the number of
197
+ * their selection.
198
+ *
199
+ * @param config - {@link ResolvedSelectPromptConfig} with message and guaranteed non-empty choices
200
+ * @param read - {@link ReadFn} for reading a line of user input
201
+ * @param write - {@link WriteFn} for rendering the choice list and validation errors
202
+ * @returns Resolved {@link PromptResult} — selected {@link SelectChoice.value}, or cancelled on EOF/exhausted retries
203
+ */
204
+ async function promptSelect(config, read, write) {
205
+ let retries = 0;
206
+ while (retries < MAX_RETRIES) {
207
+ write(`${config.message}\n`);
208
+ for (let i = 0; i < config.choices.length; i += 1) {
209
+ const choice = config.choices[i];
210
+ if (choice === void 0) continue;
211
+ const label = choice.label ?? choice.value;
212
+ const desc = choice.description !== void 0 ? ` - ${choice.description}` : "";
213
+ write(` ${i + 1}) ${label}${desc}\n`);
214
+ }
215
+ write("Enter number: ");
216
+ const line = await read();
217
+ if (line === null) return { answered: false };
218
+ const num = Number(line.trim());
219
+ if (Number.isNaN(num) || !Number.isInteger(num) || num < 1 || num > config.choices.length) {
220
+ write(`Please enter a number between 1 and ${config.choices.length}.\n`);
221
+ retries += 1;
222
+ continue;
223
+ }
224
+ const selected = config.choices[num - 1];
225
+ if (selected === void 0) {
226
+ retries += 1;
227
+ continue;
228
+ }
229
+ return {
230
+ answered: true,
231
+ value: selected.value
232
+ };
233
+ }
234
+ write("Too many invalid attempts.\n");
235
+ return { answered: false };
236
+ }
237
+ /**
238
+ * Multiselect prompt: multiple choices from a numbered list.
239
+ *
240
+ * Displays choices with 1-based indices. User enters comma-separated
241
+ * numbers of their selections (e.g. `1,3,5`).
242
+ *
243
+ * Validates against `min`/`max` constraints if configured.
244
+ *
245
+ * @param config - {@link ResolvedMultiselectPromptConfig} with message, guaranteed non-empty choices, and optional min/max
246
+ * @param read - {@link ReadFn} for reading a line of user input
247
+ * @param write - {@link WriteFn} for rendering the choice list, hints, and validation errors
248
+ * @returns Resolved {@link PromptResult} — array of selected {@link SelectChoice.value} strings, or cancelled on EOF/exhausted retries
249
+ */
250
+ async function promptMultiselect(config, read, write) {
251
+ let retries = 0;
252
+ while (retries < MAX_RETRIES) {
253
+ write(`${config.message}\n`);
254
+ for (let i = 0; i < config.choices.length; i += 1) {
255
+ const choice = config.choices[i];
256
+ if (choice === void 0) continue;
257
+ const label = choice.label ?? choice.value;
258
+ const desc = choice.description !== void 0 ? ` - ${choice.description}` : "";
259
+ write(` ${i + 1}) ${label}${desc}\n`);
260
+ }
261
+ write(`Enter numbers separated by commas (e.g. 1,3${config.min !== void 0 ? `, min: ${config.min}` : ""}${config.max !== void 0 ? `, max: ${config.max}` : ""}): `);
262
+ const line = await read();
263
+ if (line === null) return { answered: false };
264
+ const trimmed = line.trim();
265
+ if (trimmed === "") {
266
+ if (config.min !== void 0 && config.min > 0) {
267
+ write(`Please select at least ${config.min}.\n`);
268
+ retries += 1;
269
+ continue;
270
+ }
271
+ return {
272
+ answered: true,
273
+ value: []
274
+ };
275
+ }
276
+ const parts = trimmed.split(",").map((s) => s.trim());
277
+ const indices = [];
278
+ let valid = true;
279
+ for (const part of parts) {
280
+ const num = Number(part);
281
+ if (Number.isNaN(num) || !Number.isInteger(num) || num < 1 || num > config.choices.length) {
282
+ write(`Invalid selection '${part}'. Use numbers between 1 and ${config.choices.length}.\n`);
283
+ valid = false;
284
+ break;
285
+ }
286
+ indices.push(num);
287
+ }
288
+ if (!valid) {
289
+ retries += 1;
290
+ continue;
291
+ }
292
+ const unique = [...new Set(indices)];
293
+ if (config.min !== void 0 && unique.length < config.min) {
294
+ write(`Please select at least ${config.min}.\n`);
295
+ retries += 1;
296
+ continue;
297
+ }
298
+ if (config.max !== void 0 && unique.length > config.max) {
299
+ write(`Please select at most ${config.max}.\n`);
300
+ retries += 1;
301
+ continue;
302
+ }
303
+ return {
304
+ answered: true,
305
+ value: unique.map((n) => {
306
+ return config.choices[n - 1]?.value ?? "";
307
+ })
308
+ };
309
+ }
310
+ write("Too many invalid attempts.\n");
311
+ return { answered: false };
312
+ }
313
+ /**
314
+ * Prepare a {@linkcode ResolvedPromptConfig} from a raw {@linkcode PromptConfig} and optional
315
+ * enum values from the flag schema.
316
+ *
317
+ * For select/multiselect prompts without explicit choices, this merges
318
+ * the flag's enum values into the choices list. Throws if no choices
319
+ * are available.
320
+ *
321
+ * This function is called by the resolution chain (prompt-resolve-1),
322
+ * not by the engine itself — keeping the engine free of schema knowledge.
323
+ *
324
+ * @param config - Raw prompt config from `FlagSchema.prompt`
325
+ * @param enumValues - Optional enum values from `FlagSchema.enumValues`
326
+ * @returns Resolved config with choices guaranteed for select kinds
327
+ * @throws Error if select/multiselect has no choices and no enum values
328
+ */
329
+ function resolvePromptConfig(config, enumValues) {
330
+ if (config.kind === "confirm" || config.kind === "input") return config;
331
+ const rawChoices = config.choices ?? enumValues?.map((v) => ({ value: v })) ?? [];
332
+ if (rawChoices.length === 0) throw new Error(`Prompt config (${config.kind}) requires choices but none were provided and no enum values are available`);
333
+ const choices = rawChoices;
334
+ if (config.kind === "select") return {
335
+ kind: "select",
336
+ message: config.message,
337
+ choices
338
+ };
339
+ return {
340
+ kind: "multiselect",
341
+ message: config.message,
342
+ choices,
343
+ ...config.min !== void 0 ? { min: config.min } : {},
344
+ ...config.max !== void 0 ? { max: config.max } : {}
345
+ };
346
+ }
347
+ //#endregion
348
+ export { PROMPT_CANCEL, createTerminalPrompter, createTestPrompter, resolvePromptConfig };
@@ -1,6 +1,6 @@
1
1
  import { DeprecationWarning } from "./contracts.mjs";
2
2
  import { CommandArgEntry } from "../schema/command.mjs";
3
-
3
+ import "../schema/index.mjs";
4
4
  //#region src/core/resolve/args.d.ts
5
5
  /** Walk every declared arg through the resolution chain (cli -> stdin -> env -> default), collecting deprecations and throwing aggregated errors. */
6
6
  declare function resolveArgs(argEntries: readonly CommandArgEntry[], parsedArgs: Readonly<Record<string, unknown>>, stdinData: string | null | undefined, env: Readonly<Record<string, string | undefined>>, deprecations: DeprecationWarning[]): Readonly<Record<string, unknown>>;
@@ -1 +1,105 @@
1
- import{ValidationError as e}from"../errors/index.mjs";import{coerceArgStringValue as t}from"./coerce.mjs";import{isNonEmpty as n,throwAggregatedErrors as r}from"./errors.mjs";function i(i,o,s,c,l){let u={},d=[];for(let n of i){let{name:r,schema:i}=n,f=Object.hasOwn(o,r),p=o[r];if(f&&p!==void 0&&(!i.stdinMode||p!==`-`)&&!(i.variadic&&Array.isArray(p)&&p.length===0)){i.deprecated!==void 0&&l.push({kind:`arg`,name:r,message:i.deprecated}),u[r]=p;continue}if(i.stdinMode&&(!f||p===void 0||p===`-`)&&s!=null){let e=t(r,{kind:`stdin`},s,i);if(e.ok){i.deprecated!==void 0&&l.push({kind:`arg`,name:r,message:i.deprecated}),u[r]=e.value;continue}d.push(e.error);continue}if(i.envVar!==void 0){let e=c[i.envVar];if(e!==void 0){let n=t(r,{kind:`env`,envVar:i.envVar},e,i);if(n.ok){i.deprecated!==void 0&&l.push({kind:`arg`,name:r,message:i.deprecated}),u[r]=n.value;continue}d.push(n.error);continue}}if(i.defaultValue!==void 0){u[r]=i.defaultValue;continue}if(i.variadic){if(i.presence===`required`){d.push(new e(`Missing required argument <${r}>`,{code:`REQUIRED_ARG`,details:{arg:r,variadic:!0},suggest:a(r,i,!0)}));continue}u[r]=[];continue}if(i.presence===`required`){d.push(new e(`Missing required argument <${r}>`,{code:`REQUIRED_ARG`,details:{arg:r},suggest:a(r,i)}));continue}u[r]=void 0}return n(d)&&r(d),u}function a(e,t,n){let r=[n?`Provide at least one value for <${e}>`:`Provide a value for <${e}>`];return t.stdinMode&&r.push(`pipe a value to stdin or pass '-'`),t.envVar!==void 0&&r.push(`set ${t.envVar}`),r.length===1?r[0]:r.length===2?`${r[0]} or ${r[1]}`:`${r.slice(0,-1).join(`, `)}, or ${r[r.length-1]}`}export{i as resolveArgs};
1
+ import { ValidationError } from "../errors/index.mjs";
2
+ import { coerceArgStringValue } from "./coerce.mjs";
3
+ import { isNonEmpty, throwAggregatedErrors } from "./errors.mjs";
4
+ //#region src/core/resolve/args.ts
5
+ /**
6
+ * Internal arg resolution helpers.
7
+ *
8
+ * @module dreamcli/core/resolve/args
9
+ * @internal
10
+ */
11
+ /** Walk every declared arg through the resolution chain (cli -> stdin -> env -> default), collecting deprecations and throwing aggregated errors. */
12
+ function resolveArgs(argEntries, parsedArgs, stdinData, env, deprecations) {
13
+ const resolved = {};
14
+ const errors = [];
15
+ for (const entry of argEntries) {
16
+ const { name, schema } = entry;
17
+ const hasParsedValue = Object.hasOwn(parsedArgs, name);
18
+ const parsedValue = parsedArgs[name];
19
+ if (hasParsedValue && parsedValue !== void 0 && (!schema.stdinMode || parsedValue !== "-") && !(schema.variadic && Array.isArray(parsedValue) && parsedValue.length === 0)) {
20
+ if (schema.deprecated !== void 0) deprecations.push({
21
+ kind: "arg",
22
+ name,
23
+ message: schema.deprecated
24
+ });
25
+ resolved[name] = parsedValue;
26
+ continue;
27
+ }
28
+ if (schema.stdinMode && (!hasParsedValue || parsedValue === void 0 || parsedValue === "-")) {
29
+ if (stdinData !== void 0 && stdinData !== null) {
30
+ const coerced = coerceArgStringValue(name, { kind: "stdin" }, stdinData, schema);
31
+ if (coerced.ok) {
32
+ if (schema.deprecated !== void 0) deprecations.push({
33
+ kind: "arg",
34
+ name,
35
+ message: schema.deprecated
36
+ });
37
+ resolved[name] = coerced.value;
38
+ continue;
39
+ }
40
+ errors.push(coerced.error);
41
+ continue;
42
+ }
43
+ }
44
+ if (schema.envVar !== void 0) {
45
+ const envValue = env[schema.envVar];
46
+ if (envValue !== void 0) {
47
+ const coerced = coerceArgStringValue(name, {
48
+ kind: "env",
49
+ envVar: schema.envVar
50
+ }, envValue, schema);
51
+ if (coerced.ok) {
52
+ if (schema.deprecated !== void 0) deprecations.push({
53
+ kind: "arg",
54
+ name,
55
+ message: schema.deprecated
56
+ });
57
+ resolved[name] = coerced.value;
58
+ continue;
59
+ }
60
+ errors.push(coerced.error);
61
+ continue;
62
+ }
63
+ }
64
+ if (schema.defaultValue !== void 0) {
65
+ resolved[name] = schema.defaultValue;
66
+ continue;
67
+ }
68
+ if (schema.variadic) {
69
+ if (schema.presence === "required") {
70
+ errors.push(new ValidationError(`Missing required argument <${name}>`, {
71
+ code: "REQUIRED_ARG",
72
+ details: {
73
+ arg: name,
74
+ variadic: true
75
+ },
76
+ suggest: buildRequiredArgSuggest(name, schema, true)
77
+ }));
78
+ continue;
79
+ }
80
+ resolved[name] = [];
81
+ continue;
82
+ }
83
+ if (schema.presence === "required") {
84
+ errors.push(new ValidationError(`Missing required argument <${name}>`, {
85
+ code: "REQUIRED_ARG",
86
+ details: { arg: name },
87
+ suggest: buildRequiredArgSuggest(name, schema)
88
+ }));
89
+ continue;
90
+ }
91
+ resolved[name] = void 0;
92
+ }
93
+ if (isNonEmpty(errors)) throwAggregatedErrors(errors);
94
+ return resolved;
95
+ }
96
+ function buildRequiredArgSuggest(name, schema, variadic) {
97
+ const sources = [variadic ? `Provide at least one value for <${name}>` : `Provide a value for <${name}>`];
98
+ if (schema.stdinMode) sources.push(`pipe a value to stdin or pass '-'`);
99
+ if (schema.envVar !== void 0) sources.push(`set ${schema.envVar}`);
100
+ if (sources.length === 1) return sources[0];
101
+ if (sources.length === 2) return `${sources[0]} or ${sources[1]}`;
102
+ return `${sources.slice(0, -1).join(", ")}, or ${sources[sources.length - 1]}`;
103
+ }
104
+ //#endregion
105
+ export { resolveArgs };
@@ -2,7 +2,7 @@ import { ArgSchema } from "../schema/arg.mjs";
2
2
  import { FlagSchema } from "../schema/flag.mjs";
3
3
  import { ArgDiagnosticSource, FlagDiagnosticSource } from "./contracts.mjs";
4
4
  import { ValidationError } from "../errors/index.mjs";
5
-
5
+ import "../schema/index.mjs";
6
6
  //#region src/core/resolve/coerce.d.ts
7
7
  type CoerceSource = FlagDiagnosticSource;
8
8
  /** Discriminated result of a value coercion attempt — success with the coerced value, or failure with a structured validation error. */