@kjanat/dreamcli 4.0.0-rc.3 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (212) hide show
  1. package/README.md +5 -7
  2. package/dist/{runtime/adapter.d.mts → adapter-YM5QGi3M.d.mts} +4 -4
  3. package/dist/completion-CUMeOnAz.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-CrlScpYX.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-DvXUolc_.mjs +17 -0
  10. package/dist/{core/json-schema/index.d.mts → index-3l8uj16E.d.mts} +43 -34
  11. package/dist/{core/cli/index.d.mts → index-BAj2y70U.d.mts} +116 -57
  12. package/dist/index-BziI2aKc.d.mts +5440 -0
  13. package/dist/index-Cap0MA2V.d.mts +277 -0
  14. package/dist/index-Cp9kt2t-.d.mts +370 -0
  15. package/dist/index-DWsnGZlx.d.mts +831 -0
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-DRlrz_IV.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,348 +0,0 @@
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,150 +0,0 @@
1
- import { FlagBuilder, FlagConfig, InferFlags } from "../schema/flag.mjs";
2
- import { SourcesOf } from "../schema/provenance.mjs";
3
- import { ParseOptions } from "../parse/index.mjs";
4
- import { DeprecationWarning, ResolveOptions } from "../resolve/contracts.mjs";
5
- import "../resolve/index.mjs";
6
- import { RuntimeAdapter } from "../../runtime/adapter.mjs";
7
- //#region src/core/read-flags/index.d.ts
8
- /**
9
- * A record of flag definitions keyed by canonical flag name.
10
- *
11
- * The object key is the `--name` spelling and the key on the resolved record.
12
- */
13
- type FlagMap = Readonly<Record<string, FlagBuilder<FlagConfig>>>;
14
- /**
15
- * External state and behavior toggles accepted by {@linkcode readFlags}.
16
- *
17
- * Extends {@linkcode ResolveOptions}, so `env`, `config`, `prompter`, `stat`,
18
- * and `mkdir` carry the meaning they have during command resolution.
19
- */
20
- interface ReadFlagsOptions<F extends FlagMap = FlagMap> extends ResolveOptions {
21
- /**
22
- * User arguments only, without the binary and script entries.
23
- * @defaultValue the runtime adapter's argv past its binary and script entries
24
- */
25
- readonly argv?: readonly string[];
26
- /**
27
- * Runtime source for argv, environment, and filesystem primitives.
28
- * @defaultValue {@linkcode createAdapter | createAdapter()}, built on the
29
- * first fact the caller left out
30
- */
31
- readonly adapter?: RuntimeAdapter;
32
- /**
33
- * Parser behavior such as kebab/camel case parity.
34
- * @defaultValue `undefined`, which keeps the parser defaults
35
- */
36
- readonly parse?: ParseOptions;
37
- /**
38
- * Reject argv content the definitions do not declare.
39
- *
40
- * `false` drops undeclared input from argv before parsing: unknown long
41
- * flags together with their inline `=value`, unknown characters inside a
42
- * short group, positional arguments, and the `--` separator, which can only
43
- * introduce positionals here. A value token of a declared flag is kept by
44
- * walking the same consumption rules the parser applies. Misuse of a
45
- * declared flag still fails: a missing value, a bad coercion, or a violated
46
- * duplicate policy throws in either mode.
47
- * @defaultValue `true`
48
- */
49
- readonly strict?: boolean;
50
- /**
51
- * The built-in `--help`/`-h` handling.
52
- *
53
- * While `'on'`, a pre-separator `--help` or `-h` prints generated help for
54
- * the definitions to the adapter's stdout and exits the process with
55
- * code 0. The built-in yields automatically when any definition claims the
56
- * `help` or `h` spelling through its name, an alias, a negated form, or a
57
- * case-parity counterpart; those spellings then parse as the definition's
58
- * own. `'off'` removes the built-in, and the spellings parse like any other
59
- * token.
60
- * @defaultValue `'on'`
61
- */
62
- readonly help?: 'on' | 'off';
63
- /**
64
- * Receiver for notices produced by `.deprecated()` flags.
65
- * @defaultValue `undefined`, which drops the notices
66
- */
67
- readonly onDeprecation?: (warning: DeprecationWarning) => void;
68
- /**
69
- * Receiver for the provenance of the resolved values, keyed by flag name.
70
- *
71
- * Called once with the whole record, before {@linkcode readFlags} returns the
72
- * values. A flag that resolved no value has no record, so the same reader
73
- * works for optional flags.
74
- * @defaultValue `undefined`, which drops the record
75
- */
76
- readonly onSources?: (sources: SourcesOf<F>) => void;
77
- }
78
- /**
79
- * Evaluate a record of flag definitions and return the resolved values.
80
- *
81
- * The record is compiled into an anonymous command schema with no positional
82
- * arguments, parsed once, and run through the CLI, env, config, prompt, default
83
- * resolution chain. Aliases, negated spellings, duplicate policy, case parity,
84
- * unknown-flag rejection, coercion, constraints, Standard Schema validators, and
85
- * `flag.path()` checks behave exactly as they do inside a command.
86
- *
87
- * A pre-separator `--help` or `-h` prints generated help to the adapter's
88
- * stdout and exits with code 0, unless {@linkcode ReadFlagsOptions.help} is
89
- * `'off'` or a definition claims either spelling. With
90
- * {@linkcode ReadFlagsOptions.strict} set to `false`, undeclared argv content
91
- * is dropped instead of rejected, so a script can read its own flags out of an
92
- * argv it shares with another consumer.
93
- *
94
- * Anything the caller leaves out comes from the runtime adapter, which is built
95
- * on first use, so a call given `argv` and `env` reads nothing from the host
96
- * unless a `flag.path()` check needs the adapter's filesystem primitives.
97
- * `config` has no application name to discover a file from and stays
98
- * caller-supplied. `prompter` stays caller-supplied as well, so a `.prompt()`
99
- * flag with no prompter falls through to its default.
100
- *
101
- * @param definitions - Flag builders keyed by canonical flag name.
102
- * @param options - Injected runtime state and behavior toggles.
103
- * @returns The resolved flag values, typed from the definitions.
104
- * @throws {ParseError} For unknown flags, missing values, and bad input.
105
- * @throws {ValidationError} For missing required flags and failed validators.
106
- * @throws {CLIError} With code `'FLAG_NAME_COLLISION'` when two definitions share
107
- * a name, an alias, or a negated spelling.
108
- * @throws {CLIError} With code `'INVALID_SCHEMA'` for the definition key
109
- * `__proto__`, which JavaScript cannot carry as a plain record key, and for a
110
- * definitions record whose prototype is replaced, which hides the entries a
111
- * key check would read.
112
- *
113
- * @example
114
- * ```ts
115
- * import { flag, readFlags } from '@kjanat/dreamcli';
116
- *
117
- * const options = await readFlags({
118
- * watch: flag.boolean().alias('w').env('WATCH').default(false),
119
- * minify: flag.boolean().env('MINIFY').default(true),
120
- * target: flag.enum(['node', 'browser']).env('TARGET').default('node'),
121
- * });
122
- *
123
- * options.watch; // boolean
124
- * options.minify; // boolean
125
- * options.target; // 'node' | 'browser'
126
- * ```
127
- *
128
- * @example
129
- * ```ts
130
- * const values = await readFlags(
131
- * { watch: flag.boolean().alias('w').env('WATCH') },
132
- * { argv: [], env: { WATCH: 'true' } },
133
- * );
134
- *
135
- * values.watch; // true
136
- * ```
137
- *
138
- * @example
139
- * ```ts
140
- * const values = await readFlags(
141
- * { watch: flag.boolean() },
142
- * { argv: ['build', '--watch', '--unknown'], env: {}, strict: false },
143
- * );
144
- *
145
- * values.watch; // true, with 'build' and '--unknown' dropped
146
- * ```
147
- */
148
- declare function readFlags<const F extends FlagMap>(definitions: F, options?: ReadFlagsOptions<F>): Promise<InferFlags<F>>;
149
- //#endregion
150
- export { type FlagMap, type ReadFlagsOptions, readFlags };