@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,90 +0,0 @@
1
- import { Cardinality } from "../schema/cardinality.mjs";
2
- import { STDIN_SENTINEL } from "../schema/source.mjs";
3
- //#region src/core/parse/occurrences.d.ts
4
- /**
5
- * One occurrence of an input on the command line.
6
- *
7
- * - `'value'`: one decoded value, or one element of a collection
8
- * - `'entry'`: one decoded `KEY=VALUE` pair
9
- * - `'stdin'`: the position a `-` selector holds
10
- * - `'negated'`: a `--no-x` spelling
11
- * - `'increment'`: one bare occurrence of a count flag
12
- * - `'aggregated'`: a value a caller aggregated before the resolver saw it
13
- */
14
- type Occurrence = {
15
- readonly kind: 'value';
16
- readonly value: unknown;
17
- } | {
18
- readonly kind: 'entry';
19
- readonly key: string;
20
- readonly value: unknown;
21
- } | {
22
- readonly kind: 'stdin';
23
- } | {
24
- readonly kind: 'negated';
25
- } | {
26
- readonly kind: 'increment';
27
- } | {
28
- readonly kind: 'aggregated';
29
- readonly value: unknown;
30
- };
31
- /** The sentinel occurrence, shared by every `-` position. */
32
- declare const STDIN_OCCURRENCE: Occurrence;
33
- /** The negated occurrence, shared by every `--no-x` spelling. */
34
- declare const NEGATED_OCCURRENCE: Occurrence;
35
- /** One bare occurrence of a count flag. */
36
- declare const INCREMENT_OCCURRENCE: Occurrence;
37
- /**
38
- * The value one occurrence stands for in a parse result.
39
- *
40
- * @param occurrence - The occurrence to read.
41
- * @returns What a parse result carries for it.
42
- */
43
- declare function occurrenceValue(occurrence: Occurrence): unknown;
44
- /**
45
- * Project one input's occurrences onto the value a parse result carries.
46
- *
47
- * A scalar keeps its last occurrence, a count folds its increments and its
48
- * explicit values, and a collection keeps every occurrence in order for the
49
- * resolver to aggregate.
50
- *
51
- * @param cardinality - How the input's values combine.
52
- * @param occurrences - Every occurrence of the input, in order.
53
- * @returns The parse result's value for it.
54
- */
55
- declare function projectOccurrences(cardinality: Cardinality, occurrences: readonly Occurrence[]): unknown;
56
- /**
57
- * Read what a parse result carries for a collection back as occurrences.
58
- *
59
- * A value the parser did not leave as a list is an aggregate a caller built by
60
- * hand, so it stays one opaque occurrence and reaches the resolved value
61
- * untouched.
62
- *
63
- * @param cardinality - The `many` or `entries` axis being filled.
64
- * @param value - What the parse result carries.
65
- * @param readsOnDash - Whether the input's stdin binding reacts to `-`.
66
- * @returns The occurrences behind that value.
67
- */
68
- declare function liftOccurrences(cardinality: Extract<Cardinality, {
69
- kind: 'many';
70
- } | {
71
- kind: 'entries';
72
- }>, value: unknown, readsOnDash: boolean): readonly Occurrence[];
73
- /**
74
- * The aggregate a caller supplied ready-made.
75
- *
76
- * @param occurrences - One input's occurrences.
77
- * @returns The aggregate, or `undefined` when the occurrences are the parser's.
78
- */
79
- declare function readAggregated(occurrences: readonly Occurrence[]): {
80
- readonly value: unknown;
81
- } | undefined;
82
- /**
83
- * The pairs an `entries` collection folds, in occurrence order.
84
- *
85
- * @param occurrences - The occurrences left after splicing.
86
- * @returns Every pair among them.
87
- */
88
- declare function entryPairsOf(occurrences: readonly Occurrence[]): readonly (readonly [string, unknown])[];
89
- //#endregion
90
- export { INCREMENT_OCCURRENCE, NEGATED_OCCURRENCE, type Occurrence, STDIN_OCCURRENCE, STDIN_SENTINEL, entryPairsOf, liftOccurrences, occurrenceValue, projectOccurrences, readAggregated };
@@ -1,114 +0,0 @@
1
- import "../schema/source.mjs";
2
- //#region src/core/parse/occurrences.ts
3
- /** The sentinel occurrence, shared by every `-` position. */
4
- const STDIN_OCCURRENCE = { kind: "stdin" };
5
- /** The negated occurrence, shared by every `--no-x` spelling. */
6
- const NEGATED_OCCURRENCE = { kind: "negated" };
7
- /** One bare occurrence of a count flag. */
8
- const INCREMENT_OCCURRENCE = { kind: "increment" };
9
- /**
10
- * The value one occurrence stands for in a parse result.
11
- *
12
- * @param occurrence - The occurrence to read.
13
- * @returns What a parse result carries for it.
14
- */
15
- function occurrenceValue(occurrence) {
16
- switch (occurrence.kind) {
17
- case "value": return occurrence.value;
18
- case "entry": return [occurrence.key, occurrence.value];
19
- case "stdin": return "-";
20
- case "negated": return false;
21
- case "increment": return 1;
22
- case "aggregated": return occurrence.value;
23
- }
24
- }
25
- /**
26
- * Project one input's occurrences onto the value a parse result carries.
27
- *
28
- * A scalar keeps its last occurrence, a count folds its increments and its
29
- * explicit values, and a collection keeps every occurrence in order for the
30
- * resolver to aggregate.
31
- *
32
- * @param cardinality - How the input's values combine.
33
- * @param occurrences - Every occurrence of the input, in order.
34
- * @returns The parse result's value for it.
35
- */
36
- function projectOccurrences(cardinality, occurrences) {
37
- if (cardinality.kind === "count") return projectCount(occurrences);
38
- if (cardinality.kind === "one") {
39
- const last = occurrences[occurrences.length - 1];
40
- return last === void 0 ? void 0 : occurrenceValue(last);
41
- }
42
- return occurrences.map(occurrenceValue);
43
- }
44
- /** Fold a count flag's increments and explicit values in occurrence order. */
45
- function projectCount(occurrences) {
46
- let count;
47
- for (const occurrence of occurrences) count = occurrence.kind === "increment" ? (typeof count === "number" ? count : 0) + 1 : occurrenceValue(occurrence);
48
- return count;
49
- }
50
- /**
51
- * Read what a parse result carries for a collection back as occurrences.
52
- *
53
- * A value the parser did not leave as a list is an aggregate a caller built by
54
- * hand, so it stays one opaque occurrence and reaches the resolved value
55
- * untouched.
56
- *
57
- * @param cardinality - The `many` or `entries` axis being filled.
58
- * @param value - What the parse result carries.
59
- * @param readsOnDash - Whether the input's stdin binding reacts to `-`.
60
- * @returns The occurrences behind that value.
61
- */
62
- function liftOccurrences(cardinality, value, readsOnDash) {
63
- if (!Array.isArray(value)) return [{
64
- kind: "aggregated",
65
- value
66
- }];
67
- return value.map((element) => liftElement(cardinality, element, readsOnDash));
68
- }
69
- /** Read one element of a parse result's collection as its occurrence. */
70
- function liftElement(cardinality, element, readsOnDash) {
71
- if (readsOnDash && element === "-") return STDIN_OCCURRENCE;
72
- if (cardinality.kind === "entries") {
73
- const pair = entryPairOf(element);
74
- if (pair !== void 0) return {
75
- kind: "entry",
76
- key: pair[0],
77
- value: pair[1]
78
- };
79
- }
80
- return {
81
- kind: "value",
82
- value: element
83
- };
84
- }
85
- /** Read one element as the `[key, value]` pair an entry occurrence carries. */
86
- function entryPairOf(element) {
87
- if (!Array.isArray(element) || element.length !== 2) return void 0;
88
- const key = element[0];
89
- const value = element[1];
90
- return typeof key === "string" ? [key, value] : void 0;
91
- }
92
- /**
93
- * The aggregate a caller supplied ready-made.
94
- *
95
- * @param occurrences - One input's occurrences.
96
- * @returns The aggregate, or `undefined` when the occurrences are the parser's.
97
- */
98
- function readAggregated(occurrences) {
99
- const only = occurrences.length === 1 ? occurrences[0] : void 0;
100
- return only?.kind === "aggregated" ? { value: only.value } : void 0;
101
- }
102
- /**
103
- * The pairs an `entries` collection folds, in occurrence order.
104
- *
105
- * @param occurrences - The occurrences left after splicing.
106
- * @returns Every pair among them.
107
- */
108
- function entryPairsOf(occurrences) {
109
- const pairs = [];
110
- for (const occurrence of occurrences) if (occurrence.kind === "entry") pairs.push([occurrence.key, occurrence.value]);
111
- return pairs;
112
- }
113
- //#endregion
114
- export { INCREMENT_OCCURRENCE, NEGATED_OCCURRENCE, STDIN_OCCURRENCE, entryPairsOf, liftOccurrences, occurrenceValue, projectOccurrences, readAggregated };
@@ -1,213 +0,0 @@
1
- import { ConfirmPromptConfig, InputPromptConfig, PromptConfig, PromptResult, SelectChoice } from "../schema/prompt.mjs";
2
- import { WriteFn } from "../output/writer.mjs";
3
- import "../output/index.mjs";
4
- //#region src/core/prompt/index.d.ts
5
- /**
6
- * A select prompt config with choices guaranteed non-empty.
7
- *
8
- * The resolution chain populates choices from `FlagSchema.enumValues`
9
- * when the user's {@linkcode PromptConfig} omits them.
10
- */
11
- interface ResolvedSelectPromptConfig {
12
- /** Discriminant — single-choice selection prompt. */
13
- readonly kind: 'select';
14
- /** User-facing question text. */
15
- readonly message: string;
16
- /** Non-empty list of selectable options (populated from flag enum values when omitted). */
17
- readonly choices: readonly [SelectChoice, ...SelectChoice[]];
18
- }
19
- /**
20
- * A multiselect prompt config with choices guaranteed non-empty.
21
- *
22
- * Same guarantee as {@linkcode ResolvedSelectPromptConfig} — choices are always
23
- * present and non-empty.
24
- */
25
- interface ResolvedMultiselectPromptConfig {
26
- /** Discriminant — multiple-choice selection prompt. */
27
- readonly kind: 'multiselect';
28
- /** User-facing question text. */
29
- readonly message: string;
30
- /** Non-empty list of selectable options (populated from flag enum values when omitted). */
31
- readonly choices: readonly [SelectChoice, ...SelectChoice[]];
32
- /** Minimum number of selections required (validated after input). */
33
- readonly min?: number;
34
- /** Maximum number of selections allowed (validated after input). */
35
- readonly max?: number;
36
- }
37
- /**
38
- * Prompt config variant where select/multiselect choices are guaranteed
39
- * present. The prompt engine receives this (not raw {@linkcode PromptConfig}),
40
- * so it never needs to merge enum values from `FlagSchema`.
41
- *
42
- * confirm and input configs pass through unchanged.
43
- */
44
- type ResolvedPromptConfig = ConfirmPromptConfig | InputPromptConfig | ResolvedSelectPromptConfig | ResolvedMultiselectPromptConfig;
45
- /**
46
- * Prompt engine interface.
47
- *
48
- * Implementations render a single prompt to the user and return the
49
- * result. The engine is stateless per call — each `promptOne` is
50
- * independent.
51
- *
52
- * The resolution chain calls `promptOne` for each flag that needs
53
- * interactive input. Engines do not need schema knowledge — all
54
- * relevant context (message, choices, validation) is in the config.
55
- *
56
- * @example
57
- * ```ts
58
- * // Custom engine (e.g. wrapping @clack/prompts)
59
- * const engine: PromptEngine = {
60
- * async promptOne(config) {
61
- * // ... render with your library
62
- * return { answered: true, value: userInput };
63
- * }
64
- * };
65
- * ```
66
- */
67
- interface PromptEngine {
68
- /**
69
- * Present a single prompt and return the user's response.
70
- *
71
- * @param config - The resolved prompt configuration (choices guaranteed
72
- * for select/multiselect).
73
- * @returns The user's answer, or `{ answered: false }` if cancelled.
74
- */
75
- promptOne(config: ResolvedPromptConfig): Promise<PromptResult>;
76
- }
77
- /**
78
- * A function that reads a single line of user input.
79
- *
80
- * Returns `null` on EOF (Ctrl+D on Unix, Ctrl+Z on Windows),
81
- * indicating the user closed the input stream (treated as cancel).
82
- *
83
- * The terminal prompter uses this as its sole input seam. The
84
- * resolution chain (prompt-adapter-1) will wire this to the
85
- * runtime adapter's stdin.
86
- */
87
- type ReadFn = () => Promise<string | null>;
88
- /**
89
- * Sentinel value representing a cancelled/aborted prompt in the test
90
- * prompter's answer queue.
91
- *
92
- * Uses `Symbol.for()` for cross-bundle safety — the same symbol is
93
- * returned regardless of which copy of the module is loaded.
94
- *
95
- * @example
96
- * ```ts
97
- * const prompter = createTestPrompter([
98
- * 'us', // first prompt answered 'us'
99
- * PROMPT_CANCEL, // second prompt cancelled
100
- * ]);
101
- * ```
102
- */
103
- declare const PROMPT_CANCEL: unique symbol;
104
- /**
105
- * A queued answer consumed by {@link createTestPrompter}.
106
- *
107
- * The test prompter returns these values exactly as provided; it does not
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:
113
- *
114
- * - `string` for `input` and `select`
115
- * - `boolean` for `confirm`
116
- * - `string[]` for `multiselect`
117
- * - `PROMPT_CANCEL` to simulate user cancellation
118
- *
119
- * Because the type is intentionally `unknown`, tests may also inject malformed
120
- * answers to exercise downstream validation and error reporting.
121
- */
122
- type TestAnswer = unknown;
123
- /**
124
- * Options for `createTestPrompter`.
125
- */
126
- interface TestPrompterOptions {
127
- /**
128
- * Behavior when all answers have been consumed.
129
- *
130
- * - `'throw'` (default) — throws an error, making the test fail
131
- * loudly if more prompts fire than expected.
132
- * - `'cancel'` — returns `{ answered: false }`, simulating the
133
- * user cancelling all subsequent prompts.
134
- */
135
- readonly onExhausted?: 'throw' | 'cancel';
136
- }
137
- /**
138
- * Create a prompt engine that returns pre-configured answers.
139
- *
140
- * Each call to `promptOne` consumes the next answer from the queue.
141
- * Pass `PROMPT_CANCEL` as an answer to simulate the user cancelling
142
- * that prompt.
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
- *
150
- * @param answers - Ordered queue of answers. Use `PROMPT_CANCEL` for
151
- * cancellation.
152
- * @param options - Controls behavior when the queue is exhausted.
153
- * @returns A {@linkcode PromptEngine} suitable for testing.
154
- *
155
- * @example
156
- * ```ts
157
- * const prompter = createTestPrompter(['eu', true, PROMPT_CANCEL]);
158
- *
159
- * // First promptOne → { answered: true, value: 'eu' }
160
- * // Second promptOne → { answered: true, value: true }
161
- * // Third promptOne → { answered: false }
162
- * ```
163
- */
164
- declare function createTestPrompter(answers: readonly TestAnswer[], options?: TestPrompterOptions): PromptEngine;
165
- /**
166
- * Create a prompt engine backed by line-based terminal I/O.
167
- *
168
- * Uses a {@linkcode ReadFn} for input and a {@linkcode WriteFn} for output. This is the
169
- * built-in renderer — sufficient for most CLI use cases. For richer
170
- * TUI experiences, users can implement {@linkcode PromptEngine} with a library
171
- * like `@clack/prompts` or `inquirer`.
172
- *
173
- * The prompter does **not** use raw mode — all input is line-based.
174
- * This keeps the implementation portable across Node, Bun, and Deno
175
- * without platform-specific stdin configuration.
176
- *
177
- * @param read - Line reader function (returns `null` on EOF)
178
- * @param write - Output writer function
179
- * @returns A {@linkcode PromptEngine} that prompts via terminal I/O
180
- *
181
- * @example
182
- * ```ts
183
- * import { createInterface } from 'readline';
184
- *
185
- * const rl = createInterface({ input: process.stdin, output: process.stdout });
186
- * const read = () => new Promise<string | null>((resolve) => {
187
- * rl.question('', (answer) => resolve(answer));
188
- * });
189
- * const write: WriteFn = (s) => process.stdout.write(s);
190
- *
191
- * const prompter = createTerminalPrompter(read, write);
192
- * ```
193
- */
194
- declare function createTerminalPrompter(read: ReadFn, write: WriteFn): PromptEngine;
195
- /**
196
- * Prepare a {@linkcode ResolvedPromptConfig} from a raw {@linkcode PromptConfig} and optional
197
- * enum values from the flag schema.
198
- *
199
- * For select/multiselect prompts without explicit choices, this merges
200
- * the flag's enum values into the choices list. Throws if no choices
201
- * are available.
202
- *
203
- * This function is called by the resolution chain (prompt-resolve-1),
204
- * not by the engine itself — keeping the engine free of schema knowledge.
205
- *
206
- * @param config - Raw prompt config from `FlagSchema.prompt`
207
- * @param enumValues - Optional enum values from `FlagSchema.enumValues`
208
- * @returns Resolved config with choices guaranteed for select kinds
209
- * @throws Error if select/multiselect has no choices and no enum values
210
- */
211
- declare function resolvePromptConfig(config: PromptConfig, enumValues: readonly string[] | undefined): ResolvedPromptConfig;
212
- //#endregion
213
- export { PROMPT_CANCEL, type PromptEngine, type ReadFn, type ResolvedMultiselectPromptConfig, type ResolvedPromptConfig, type ResolvedSelectPromptConfig, type TestAnswer, type TestPrompterOptions, createTerminalPrompter, createTestPrompter, resolvePromptConfig };