@kjanat/dreamcli 0.0.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (205) hide show
  1. package/CHANGELOG.md +706 -0
  2. package/LICENSE +22 -0
  3. package/README.md +502 -0
  4. package/dist/core/cli/dispatch.d.mts +85 -0
  5. package/dist/core/cli/dispatch.mjs +1 -0
  6. package/dist/core/cli/index.d.mts +418 -0
  7. package/dist/core/cli/index.mjs +1 -0
  8. package/dist/core/cli/planner.d.mts +143 -0
  9. package/dist/core/cli/planner.mjs +1 -0
  10. package/dist/core/cli/plugin.d.mts +94 -0
  11. package/dist/core/cli/plugin.mjs +1 -0
  12. package/dist/core/cli/propagate.d.mts +39 -0
  13. package/dist/core/cli/propagate.mjs +1 -0
  14. package/dist/core/cli/root-help.d.mts +28 -0
  15. package/dist/core/cli/root-help.mjs +7 -0
  16. package/dist/core/cli/root-surface.d.mts +42 -0
  17. package/dist/core/cli/root-surface.mjs +1 -0
  18. package/dist/core/cli/runtime-preflight.d.mts +149 -0
  19. package/dist/core/cli/runtime-preflight.mjs +1 -0
  20. package/dist/core/completion/index.d.mts +46 -0
  21. package/dist/core/completion/index.mjs +1 -0
  22. package/dist/core/completion/shells/bash.d.mts +24 -0
  23. package/dist/core/completion/shells/bash.mjs +3 -0
  24. package/dist/core/completion/shells/fish.d.mts +20 -0
  25. package/dist/core/completion/shells/fish.mjs +2 -0
  26. package/dist/core/completion/shells/powershell.d.mts +14 -0
  27. package/dist/core/completion/shells/powershell.mjs +2 -0
  28. package/dist/core/completion/shells/shared.d.mts +139 -0
  29. package/dist/core/completion/shells/shared.mjs +1 -0
  30. package/dist/core/completion/shells/zsh.d.mts +24 -0
  31. package/dist/core/completion/shells/zsh.mjs +2 -0
  32. package/dist/core/config/index.d.mts +161 -0
  33. package/dist/core/config/index.mjs +1 -0
  34. package/dist/core/config/package-json.d.mts +68 -0
  35. package/dist/core/config/package-json.mjs +1 -0
  36. package/dist/core/errors/index.d.mts +126 -0
  37. package/dist/core/errors/index.mjs +1 -0
  38. package/dist/core/execution/index.d.mts +49 -0
  39. package/dist/core/execution/index.mjs +1 -0
  40. package/dist/core/help/index.d.mts +49 -0
  41. package/dist/core/help/index.mjs +8 -0
  42. package/dist/core/json-schema/index.d.mts +109 -0
  43. package/dist/core/json-schema/index.mjs +55 -0
  44. package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
  45. package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
  46. package/dist/core/output/activity.d.mts +194 -0
  47. package/dist/core/output/activity.mjs +1 -0
  48. package/dist/core/output/contracts.d.mts +88 -0
  49. package/dist/core/output/contracts.mjs +1 -0
  50. package/dist/core/output/display-value.d.mts +19 -0
  51. package/dist/core/output/display-value.mjs +1 -0
  52. package/dist/core/output/index.d.mts +280 -0
  53. package/dist/core/output/index.mjs +2 -0
  54. package/dist/core/output/renderers.d.mts +46 -0
  55. package/dist/core/output/renderers.mjs +1 -0
  56. package/dist/core/output/writer.d.mts +40 -0
  57. package/dist/core/output/writer.mjs +1 -0
  58. package/dist/core/parse/index.d.mts +79 -0
  59. package/dist/core/parse/index.mjs +1 -0
  60. package/dist/core/prompt/index.d.mts +205 -0
  61. package/dist/core/prompt/index.mjs +6 -0
  62. package/dist/core/resolve/args.d.mts +8 -0
  63. package/dist/core/resolve/args.mjs +1 -0
  64. package/dist/core/resolve/coerce.d.mts +22 -0
  65. package/dist/core/resolve/coerce.mjs +1 -0
  66. package/dist/core/resolve/config.d.mts +10 -0
  67. package/dist/core/resolve/config.mjs +1 -0
  68. package/dist/core/resolve/contracts.d.mts +112 -0
  69. package/dist/core/resolve/errors.d.mts +11 -0
  70. package/dist/core/resolve/errors.mjs +2 -0
  71. package/dist/core/resolve/flags.d.mts +10 -0
  72. package/dist/core/resolve/flags.mjs +1 -0
  73. package/dist/core/resolve/index.d.mts +42 -0
  74. package/dist/core/resolve/index.mjs +1 -0
  75. package/dist/core/resolve/property.d.mts +47 -0
  76. package/dist/core/resolve/property.mjs +1 -0
  77. package/dist/core/schema/activity.d.mts +169 -0
  78. package/dist/core/schema/arg.d.mts +559 -0
  79. package/dist/core/schema/arg.mjs +1 -0
  80. package/dist/core/schema/command.d.mts +960 -0
  81. package/dist/core/schema/command.mjs +1 -0
  82. package/dist/core/schema/flag.d.mts +491 -0
  83. package/dist/core/schema/flag.mjs +1 -0
  84. package/dist/core/schema/index.d.mts +8 -0
  85. package/dist/core/schema/middleware.d.mts +122 -0
  86. package/dist/core/schema/middleware.mjs +1 -0
  87. package/dist/core/schema/prompt.d.mts +117 -0
  88. package/dist/core/schema/run.d.mts +171 -0
  89. package/dist/core/schema-dsl/runtime.d.mts +144 -0
  90. package/dist/core/schema-dsl/runtime.mjs +2 -0
  91. package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
  92. package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
  93. package/dist/core/testkit/index.d.mts +54 -0
  94. package/dist/core/testkit/index.mjs +1 -0
  95. package/dist/index.d.mts +28 -0
  96. package/dist/index.mjs +1 -0
  97. package/dist/runtime/adapter.d.mts +212 -0
  98. package/dist/runtime/adapter.mjs +1 -0
  99. package/dist/runtime/auto.d.mts +26 -0
  100. package/dist/runtime/auto.mjs +1 -0
  101. package/dist/runtime/bun.d.mts +28 -0
  102. package/dist/runtime/bun.mjs +1 -0
  103. package/dist/runtime/deno.d.mts +76 -0
  104. package/dist/runtime/deno.mjs +2 -0
  105. package/dist/runtime/detect.d.mts +86 -0
  106. package/dist/runtime/detect.mjs +1 -0
  107. package/dist/runtime/index.d.mts +7 -0
  108. package/dist/runtime/node.d.mts +65 -0
  109. package/dist/runtime/node.mjs +2 -0
  110. package/dist/runtime/paths.d.mts +31 -0
  111. package/dist/runtime/paths.mjs +1 -0
  112. package/dist/runtime/support.d.mts +42 -0
  113. package/dist/runtime/support.mjs +1 -0
  114. package/dist/runtime.d.mts +7 -0
  115. package/dist/runtime.mjs +1 -0
  116. package/dist/testkit.d.mts +6 -0
  117. package/dist/testkit.mjs +1 -0
  118. package/dist/version.d.mts +16 -0
  119. package/dist/version.mjs +1 -0
  120. package/dreamcli.schema.json +338 -0
  121. package/examples/basic.ts +33 -0
  122. package/examples/gh/package.json +44 -0
  123. package/examples/gh/src/commands/auth.ts +66 -0
  124. package/examples/gh/src/commands/issue.ts +120 -0
  125. package/examples/gh/src/commands/pr.ts +125 -0
  126. package/examples/gh/src/data/issues.yaml +5 -0
  127. package/examples/gh/src/data/issues.yaml.d.ts +17 -0
  128. package/examples/gh/src/data/pull-requests.yaml +7 -0
  129. package/examples/gh/src/data/pull-requests.yaml.d.ts +18 -0
  130. package/examples/gh/src/docs.ts +11 -0
  131. package/examples/gh/src/lib/auth.ts +37 -0
  132. package/examples/gh/src/lib/utils.ts +17 -0
  133. package/examples/gh/src/main.test.ts +307 -0
  134. package/examples/gh/src/main.ts +40 -0
  135. package/examples/interactive.ts +66 -0
  136. package/examples/json-mode.ts +91 -0
  137. package/examples/middleware.ts +71 -0
  138. package/examples/multi-command.ts +66 -0
  139. package/examples/spinner-progress.ts +49 -0
  140. package/examples/testing.ts +147 -0
  141. package/package.json +149 -2
  142. package/src/core/cli/dispatch.ts +286 -0
  143. package/src/core/cli/index.ts +978 -0
  144. package/src/core/cli/planner.ts +413 -0
  145. package/src/core/cli/plugin.ts +117 -0
  146. package/src/core/cli/propagate.ts +97 -0
  147. package/src/core/cli/root-help.ts +269 -0
  148. package/src/core/cli/root-surface.ts +74 -0
  149. package/src/core/cli/runtime-preflight.ts +409 -0
  150. package/src/core/completion/index.ts +88 -0
  151. package/src/core/completion/shells/bash.ts +459 -0
  152. package/src/core/completion/shells/fish.ts +259 -0
  153. package/src/core/completion/shells/powershell.ts +405 -0
  154. package/src/core/completion/shells/shared.ts +283 -0
  155. package/src/core/completion/shells/zsh.ts +381 -0
  156. package/src/core/config/index.ts +407 -0
  157. package/src/core/config/package-json.ts +220 -0
  158. package/src/core/errors/index.ts +193 -0
  159. package/src/core/execution/index.ts +270 -0
  160. package/src/core/help/index.ts +557 -0
  161. package/src/core/json-schema/index.ts +891 -0
  162. package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
  163. package/src/core/output/activity.ts +568 -0
  164. package/src/core/output/contracts.ts +194 -0
  165. package/src/core/output/display-value.ts +48 -0
  166. package/src/core/output/index.ts +669 -0
  167. package/src/core/output/renderers.ts +125 -0
  168. package/src/core/output/writer.ts +46 -0
  169. package/src/core/parse/index.ts +661 -0
  170. package/src/core/prompt/index.ts +583 -0
  171. package/src/core/resolve/args.ts +144 -0
  172. package/src/core/resolve/coerce.ts +432 -0
  173. package/src/core/resolve/config.ts +26 -0
  174. package/src/core/resolve/contracts.ts +135 -0
  175. package/src/core/resolve/errors.ts +227 -0
  176. package/src/core/resolve/flags.ts +205 -0
  177. package/src/core/resolve/index.ts +108 -0
  178. package/src/core/resolve/property.ts +99 -0
  179. package/src/core/schema/activity.ts +240 -0
  180. package/src/core/schema/arg.ts +719 -0
  181. package/src/core/schema/command.ts +1490 -0
  182. package/src/core/schema/flag.ts +756 -0
  183. package/src/core/schema/index.ts +91 -0
  184. package/src/core/schema/middleware.ts +171 -0
  185. package/src/core/schema/prompt.ts +156 -0
  186. package/src/core/schema/run.ts +195 -0
  187. package/src/core/schema-dsl/index.ts +109 -0
  188. package/src/core/schema-dsl/parse.ts +262 -0
  189. package/src/core/schema-dsl/runtime.ts +609 -0
  190. package/src/core/schema-dsl/to-json-schema.ts +102 -0
  191. package/src/core/testkit/index.ts +123 -0
  192. package/src/index.ts +170 -0
  193. package/src/runtime/adapter.ts +303 -0
  194. package/src/runtime/auto.ts +110 -0
  195. package/src/runtime/bun.ts +55 -0
  196. package/src/runtime/deno.ts +369 -0
  197. package/src/runtime/detect.ts +105 -0
  198. package/src/runtime/index.ts +21 -0
  199. package/src/runtime/node-builtins.d.ts +23 -0
  200. package/src/runtime/node.ts +300 -0
  201. package/src/runtime/paths.ts +62 -0
  202. package/src/runtime/support.ts +135 -0
  203. package/src/runtime.ts +31 -0
  204. package/src/testkit.ts +25 -0
  205. package/src/version.ts +20 -0
@@ -0,0 +1,280 @@
1
+ import { ActivityEvent, ProgressHandle, ProgressOptions, SpinnerHandle, SpinnerOptions, TableColumn, TableOptions } from "../schema/activity.mjs";
2
+ import { WriteFn, writeLine } from "./writer.mjs";
3
+ import { CaptureProgressHandle, CaptureSpinnerHandle, StaticProgressHandle, StaticSpinnerHandle, TTYProgressHandle, TTYSpinnerHandle, noopProgressHandle, noopSpinnerHandle } from "./activity.mjs";
4
+ import { OutputPolicy, Verbosity } from "./contracts.mjs";
5
+ import { Out } from "../schema/command.mjs";
6
+
7
+ //#region src/core/output/index.d.ts
8
+ /**
9
+ * Configuration for creating an output channel.
10
+ *
11
+ * Every field is optional — sensible defaults are applied when omitted.
12
+ */
13
+ interface OutputOptions {
14
+ /**
15
+ * Writer for stdout-bound messages (`log`, `info`, `json`).
16
+ * Defaults to `process.stdout.write` when running in Node/Bun.
17
+ */
18
+ readonly stdout?: WriteFn;
19
+ /**
20
+ * Writer for stderr-bound messages (`warn`, `error`).
21
+ * In JSON mode, `log` and `info` are also redirected here so that
22
+ * stdout contains only structured JSON output.
23
+ * Defaults to `process.stderr.write` when running in Node/Bun.
24
+ */
25
+ readonly stderr?: WriteFn;
26
+ /**
27
+ * Whether stdout is connected to a TTY.
28
+ * When `false`, output may omit ANSI codes and decorations.
29
+ * Defaults to `false` (safe default — non-TTY until proven otherwise).
30
+ */
31
+ readonly isTTY?: boolean;
32
+ /**
33
+ * Verbosity level.
34
+ * - `'normal'` (default) — emit all messages
35
+ * - `'quiet'` — suppress `info` messages
36
+ */
37
+ readonly verbosity?: Verbosity;
38
+ /**
39
+ * Enable JSON output mode.
40
+ *
41
+ * When `true`, `log` and `info` messages are redirected to stderr
42
+ * so that stdout is reserved exclusively for structured `json()` output.
43
+ * `warn` and `error` continue to write to stderr as normal.
44
+ *
45
+ * @defaultValue `false`
46
+ */
47
+ readonly jsonMode?: boolean;
48
+ }
49
+ /** Fully resolved output options with no optional fields. */
50
+ interface ResolvedOutputOptions {
51
+ readonly stdout: WriteFn;
52
+ readonly stderr: WriteFn;
53
+ readonly isTTY: boolean;
54
+ readonly verbosity: Verbosity;
55
+ readonly jsonMode: boolean;
56
+ }
57
+ /**
58
+ * Concrete implementation of the {@linkcode Out} interface.
59
+ *
60
+ * Routes messages to the appropriate writer (stdout vs stderr) and
61
+ * respects the configured verbosity level.
62
+ *
63
+ * Handlers interact with this via the {@linkcode Out} interface — they never see
64
+ * {@linkcode OutputChannel} directly, which keeps the coupling minimal.
65
+ * Prefer {@link createOutput} unless you are extending the output layer.
66
+ *
67
+ * @internal
68
+ */
69
+ declare class OutputChannel implements Out {
70
+ /** @internal Resolved configuration. */
71
+ readonly options: ResolvedOutputOptions;
72
+ /** Semantic output policy snapshot shared by routing helpers. */
73
+ readonly policy: OutputPolicy;
74
+ /** Whether JSON output mode is active. */
75
+ readonly jsonMode: boolean;
76
+ /**
77
+ * Whether stdout is connected to a TTY.
78
+ *
79
+ * When `jsonMode` is active, this reflects the underlying TTY status
80
+ * but decorative output should still be suppressed (jsonMode takes
81
+ * precedence).
82
+ */
83
+ readonly isTTY: boolean;
84
+ constructor(options: ResolvedOutputOptions);
85
+ /**
86
+ * Write to stdout (normal output). Always emitted.
87
+ *
88
+ * In JSON mode, redirected to stderr so stdout is reserved for
89
+ * structured `json()` output only.
90
+ */
91
+ log(message: string): void;
92
+ /**
93
+ * Informational message to stdout.
94
+ * Suppressed when verbosity is `'quiet'`.
95
+ *
96
+ * In JSON mode, redirected to stderr.
97
+ */
98
+ info(message: string): void;
99
+ /** Warning to stderr. Always emitted. */
100
+ warn(message: string): void;
101
+ /** Error to stderr. Always emitted. */
102
+ error(message: string): void;
103
+ /**
104
+ * Emit a structured JSON value to stdout.
105
+ *
106
+ * Serialises `value` with `JSON.stringify` and writes to stdout
107
+ * regardless of JSON mode — `json()` always targets stdout.
108
+ */
109
+ json(value: unknown): void;
110
+ /**
111
+ * Render tabular data.
112
+ *
113
+ * Default behavior matches the current output mode:
114
+ * - normal mode → text table to stdout
115
+ * - jsonMode → JSON array to stdout
116
+ *
117
+ * Per-call options can force text/json rendering and route text tables to
118
+ * stdout or stderr.
119
+ */
120
+ table<T extends Record<string, unknown>>(rows: readonly T[], options: TableOptions): void;
121
+ table<T extends Record<string, unknown>>(rows: readonly T[], columns?: readonly TableColumn<T>[], options?: TableOptions): void;
122
+ /**
123
+ * Cleanup callback for the currently active spinner/progress handle.
124
+ *
125
+ * Set to `undefined` when no handle is active. The callback calls the
126
+ * appropriate terminal method (`.stop()` for spinners, `.done()` for
127
+ * progress) on the previous handle.
128
+ *
129
+ * @internal
130
+ */
131
+ private activeCleanup;
132
+ /**
133
+ * Stop the currently active spinner/progress handle (if any).
134
+ *
135
+ * Called internally before creating a new handle to prevent overlap,
136
+ * and externally after handler execution to clean up leaked timers.
137
+ * Idempotent (safe to call when no handle is active).
138
+ */
139
+ stopActive(): void;
140
+ /**
141
+ * Create a spinner handle.
142
+ *
143
+ * Mode dispatch:
144
+ * - `jsonMode` → noop (structured output only, spinners suppressed)
145
+ * - `isTTY` → animated TTY spinner (braille frames, ANSI overwrite)
146
+ * - `!isTTY && fallback: 'static'` → plain text at lifecycle boundaries
147
+ * - `!isTTY && fallback: 'silent'` (default) → noop
148
+ *
149
+ * All activity output (transient frames, terminal messages) routes to
150
+ * stderr so stdout remains clean for structured data and piping.
151
+ *
152
+ * If another spinner or progress handle is active, it is implicitly
153
+ * stopped before the new one starts.
154
+ *
155
+ * @virtual
156
+ */
157
+ spinner(text: string, options?: SpinnerOptions): SpinnerHandle;
158
+ /**
159
+ * Create a progress handle.
160
+ *
161
+ * Mode dispatch:
162
+ * - `jsonMode` → noop (structured output only, progress suppressed)
163
+ * - `isTTY` → animated TTY progress bar (determinate or indeterminate)
164
+ * - `!isTTY && fallback: 'static'` → plain text at lifecycle boundaries
165
+ * - `!isTTY && fallback: 'silent'` (default) → noop
166
+ *
167
+ * All activity output (transient frames, terminal messages) routes to
168
+ * stderr so stdout remains clean for structured data and piping.
169
+ *
170
+ * If another spinner or progress handle is active, it is implicitly
171
+ * stopped before the new one starts.
172
+ *
173
+ * @virtual
174
+ */
175
+ progress(opts: ProgressOptions): ProgressHandle;
176
+ }
177
+ /**
178
+ * Output channel variant that returns capture handles for spinner/progress.
179
+ *
180
+ * Extends {@linkcode OutputChannel} to override `spinner()` and `progress()`, routing
181
+ * activity events into a shared {@linkcode ActivityEvent | ActivityEvent[]} for testkit assertion.
182
+ * Text output (log/info/warn/error) is handled by the parent class.
183
+ *
184
+ * @internal
185
+ */
186
+ declare class CaptureOutputChannel extends OutputChannel {
187
+ private readonly activity;
188
+ constructor(options: ResolvedOutputOptions, activity: ActivityEvent[]);
189
+ /**
190
+ * Return a {@link CaptureSpinnerHandle} that records events into the activity log.
191
+ * @override
192
+ */
193
+ spinner(text: string, _options?: SpinnerOptions): SpinnerHandle;
194
+ /**
195
+ * Return a {@link CaptureProgressHandle} that records events into the activity log.
196
+ * @override
197
+ */
198
+ progress(opts: ProgressOptions): ProgressHandle;
199
+ }
200
+ /**
201
+ * Create an output channel.
202
+ *
203
+ * Low-level factory: action handlers already receive `out` automatically from
204
+ * `cli()`, `.execute()`, and `runCommand()`. Call `createOutput()` when you
205
+ * are embedding DreamCLI primitives into a custom runtime or need a standalone
206
+ * output implementation outside the normal command pipeline.
207
+ *
208
+ * @param options - Optional configuration. When omitted, output is
209
+ * discarded (useful for silent test runs). Pass `stdout`/`stderr`
210
+ * writers to direct output somewhere useful.
211
+ *
212
+ * @returns An {@link Out} instance backed by an {@link OutputChannel}.
213
+ *
214
+ * @example
215
+ * ```ts
216
+ * // Production (wired by the runtime adapter)
217
+ * const out = createOutput({
218
+ * stdout: (s) => process.stdout.write(s),
219
+ * stderr: (s) => process.stderr.write(s),
220
+ * isTTY: process.stdout.isTTY === true,
221
+ * });
222
+ *
223
+ * // Test (capture output)
224
+ * const lines: string[] = [];
225
+ * const out = createOutput({
226
+ * stdout: (s) => lines.push(s),
227
+ * stderr: (s) => lines.push(s),
228
+ * });
229
+ * ```
230
+ */
231
+ declare function createOutput(options?: OutputOptions): Out;
232
+ /** Captured output from a `createCaptureOutput` instance. */
233
+ interface CapturedOutput {
234
+ /**
235
+ * Lines written to stdout.
236
+ *
237
+ * In normal mode: `log`, `info`, and `json` output.
238
+ * In JSON mode: only `json` output (log/info redirected to stderr).
239
+ */
240
+ readonly stdout: string[];
241
+ /**
242
+ * Lines written to stderr.
243
+ *
244
+ * In normal mode: `warn` and `error` output.
245
+ * In JSON mode: `warn`, `error`, `log`, and `info` output.
246
+ */
247
+ readonly stderr: string[];
248
+ /**
249
+ * Activity events from spinner and progress handles.
250
+ *
251
+ * Captured separately from stdout/stderr to allow targeted assertions
252
+ * on activity lifecycle without parsing text output. Events are
253
+ * recorded in chronological order.
254
+ */
255
+ readonly activity: ActivityEvent[];
256
+ }
257
+ /**
258
+ * Create an output channel that captures all output into arrays.
259
+ *
260
+ * Useful in tests to assert on what a handler wrote without touching
261
+ * real I/O.
262
+ *
263
+ * @param options - Optional {@link OutputOptions} (minus `stdout`/`stderr`,
264
+ * which are wired to the capture buffers automatically).
265
+ *
266
+ * @returns A tuple of `[out, captured]` — the {@link Out} channel and the
267
+ * {@link CapturedOutput} buffers.
268
+ *
269
+ * @example
270
+ * ```ts
271
+ * const [out, captured] = createCaptureOutput();
272
+ * out.log('hello');
273
+ * out.warn('danger');
274
+ * expect(captured.stdout).toEqual(['hello\n']);
275
+ * expect(captured.stderr).toEqual(['danger\n']);
276
+ * ```
277
+ */
278
+ declare function createCaptureOutput(options?: Omit<OutputOptions, 'stdout' | 'stderr'>): [out: Out, captured: CapturedOutput];
279
+ //#endregion
280
+ export { CaptureOutputChannel, CaptureProgressHandle, CaptureSpinnerHandle, type CapturedOutput, OutputChannel, type OutputOptions, StaticProgressHandle, StaticSpinnerHandle, TTYProgressHandle, TTYSpinnerHandle, type Verbosity, type WriteFn, createCaptureOutput, createOutput, noopProgressHandle, noopSpinnerHandle, writeLine };
@@ -0,0 +1,2 @@
1
+ import{formatDisplayValue as e}from"./display-value.mjs";import{writeLine as t}from"./writer.mjs";import{CaptureProgressHandle as n,CaptureSpinnerHandle as r}from"./activity.mjs";import{resolveOutputPolicy as i,resolveProgressPolicy as a,resolveSpinnerPolicy as o,resolveTableFormat as s,resolveTableTextStream as c,resolveTextStream as l,shouldEmitInfo as u}from"./contracts.mjs";import{createProgressHandleFromPolicy as d,createSpinnerHandleFromPolicy as f,resolveWriterForStream as p}from"./renderers.mjs";const m=()=>{};function h(e){return{stdout:e?.stdout??m,stderr:e?.stderr??m,isTTY:e?.isTTY??!1,verbosity:e?.verbosity??`normal`,jsonMode:e?.jsonMode??!1}}var g=class{options;policy;jsonMode;isTTY;constructor(e){this.options=e,this.policy=i(e),this.jsonMode=e.jsonMode,this.isTTY=e.isTTY}log(e){t(p(this.options,l(this.policy)),e)}info(e){u(this.policy)&&t(p(this.options,l(this.policy)),e)}warn(e){t(this.options.stderr,e)}error(e){t(this.options.stderr,e)}json(e){t(this.options.stdout,JSON.stringify(e))}table(e,n,r){let{columns:i,options:a}=b(n,r),o=s(this.policy,a),c=i??v(e);if(o===`json`){this.json(x(e,c));return}let l=w(e,c);l.length!==0&&t(S(this.options,this.policy,o,a),l)}activeCleanup;stopActive(){this.activeCleanup!==void 0&&(this.activeCleanup(),this.activeCleanup=void 0)}spinner(e,t){let n=f(o(this.policy,t?.fallback??`silent`),e,this.options.stderr);return n.cleanup===void 0?n.handle:(this.stopActive(),this.activeCleanup=n.cleanup,n.handle)}progress(e){let t=d(a(this.policy,e.fallback??`silent`),e,this.options.stderr);return t.cleanup===void 0?t.handle:(this.stopActive(),this.activeCleanup=t.cleanup,t.handle)}},_=class extends g{constructor(e,t){super(e),this.activity=t}spinner(e,t){return new r(e,this.activity)}progress(e){return new n(e,this.activity)}};function v(e){let t=e[0];return t===void 0?[]:Object.keys(t).map(e=>({key:e}))}function y(e){return Array.isArray(e)}function b(e,t){return t===void 0?y(e)?{columns:e,options:t}:{columns:void 0,options:e}:{columns:y(e)?e:void 0,options:t}}function x(e,t){return e.map(e=>Object.fromEntries(t.map(t=>[t.key,e[t.key]])))}function S(e,t,n,r){return n===`json`?e.stdout:p(e,c(t,r))}function C(t){return e(t)}function w(e,t){if(e.length===0||t.length===0)return``;let n=t.map(e=>e.header??e.key),r=e.map(e=>t.map(t=>C(e[t.key]))),i=n.map((e,t)=>{let n=e.length;for(let e of r){let r=e[t];r!==void 0&&r.length>n&&(n=r.length)}return n});return[n.map((e,t)=>e.padEnd(i[t]??0)).join(` `),i.map(e=>`-`.repeat(e)).join(` `),...r.map(e=>e.map((e,t)=>e.padEnd(i[t]??0)).join(` `))].join(`
2
+ `)}function T(e){return new g(h(e))}function E(e){let t={stdout:[],stderr:[],activity:[]};return[new _(h({...e,stdout:e=>t.stdout.push(e),stderr:e=>t.stderr.push(e)}),t.activity),t]}export{E as createCaptureOutput,T as createOutput};
@@ -0,0 +1,46 @@
1
+ import { ProgressHandle, ProgressOptions, SpinnerHandle } from "../schema/activity.mjs";
2
+ import { WriteFn } from "./writer.mjs";
3
+ import { ActivityPolicy, OutputStream } from "./contracts.mjs";
4
+
5
+ //#region src/core/output/renderers.d.ts
6
+ /**
7
+ * Paired write functions for the two standard output streams.
8
+ *
9
+ * @internal
10
+ */
11
+ interface OutputWriters {
12
+ /** Write function targeting standard output. */
13
+ readonly stdout: WriteFn;
14
+ /** Write function targeting standard error. */
15
+ readonly stderr: WriteFn;
16
+ }
17
+ /**
18
+ * Spinner handle paired with its optional teardown function.
19
+ *
20
+ * @internal
21
+ */
22
+ interface SpinnerRenderResult {
23
+ /** The spinner handle exposed to command handlers. */
24
+ readonly handle: SpinnerHandle;
25
+ /** Defined only when the mode requires cleanup (TTY or static); `undefined` for noop. */
26
+ readonly cleanup: (() => void) | undefined;
27
+ }
28
+ /**
29
+ * Progress handle paired with its optional teardown function.
30
+ *
31
+ * @internal
32
+ */
33
+ interface ProgressRenderResult {
34
+ /** The progress handle exposed to command handlers. */
35
+ readonly handle: ProgressHandle;
36
+ /** Defined only when the mode requires cleanup (TTY or static); `undefined` for noop. */
37
+ readonly cleanup: (() => void) | undefined;
38
+ }
39
+ /** Select the concrete {@linkcode WriteFn} for a given stream label. @internal */
40
+ declare function resolveWriterForStream(writers: OutputWriters, stream: OutputStream): WriteFn;
41
+ /** Create a spinner handle matching the resolved {@linkcode ActivityPolicy} mode. @internal */
42
+ declare function createSpinnerHandleFromPolicy(policy: ActivityPolicy, text: string, stderr: WriteFn): SpinnerRenderResult;
43
+ /** Create a progress handle matching the resolved {@linkcode ActivityPolicy} mode. @internal */
44
+ declare function createProgressHandleFromPolicy(policy: ActivityPolicy, options: ProgressOptions, stderr: WriteFn): ProgressRenderResult;
45
+ //#endregion
46
+ export { type OutputWriters, type ProgressRenderResult, type SpinnerRenderResult, createProgressHandleFromPolicy, createSpinnerHandleFromPolicy, resolveWriterForStream };
@@ -0,0 +1 @@
1
+ import{StaticProgressHandle as e,StaticSpinnerHandle as t,TTYProgressHandle as n,TTYSpinnerHandle as r,noopProgressHandle as i,noopSpinnerHandle as a}from"./activity.mjs";function o(e,t){return t===`stderr`?e.stderr:e.stdout}function s(e,n,i){if(e.mode===`noop`)return{handle:a,cleanup:void 0};if(e.mode===`tty`){let e=new r(n,i);return{handle:e,cleanup:()=>e.stop()}}let o=new t(n,i);return{handle:o,cleanup:()=>o.stop()}}function c(t,r,a){if(t.mode===`noop`)return{handle:i,cleanup:void 0};if(t.mode===`tty`){let e=new n(r,a);return{handle:e,cleanup:()=>e.done()}}let o=new e(r.label,a);return{handle:o,cleanup:()=>o.done()}}export{c as createProgressHandleFromPolicy,s as createSpinnerHandleFromPolicy,o as resolveWriterForStream};
@@ -0,0 +1,40 @@
1
+ //#region src/core/output/writer.d.ts
2
+ /**
3
+ * Minimal I/O seam — the only write primitive the output module depends on.
4
+ *
5
+ * Extracted to its own file so that both `index.ts` (OutputChannel) and
6
+ * `activity.ts` (handle classes) can import it without a circular dependency.
7
+ *
8
+ * @module dreamcli/core/output/writer
9
+ * @internal
10
+ */
11
+ /**
12
+ * A function that writes a string somewhere.
13
+ *
14
+ * This is the only write primitive the output layer depends on.
15
+ * In production it usually wraps `process.stdout.write` or
16
+ * `process.stderr.write`; in tests it is often a simple string accumulator.
17
+ *
18
+ * The contract is intentionally tiny:
19
+ * - writes are synchronous fire-and-forget
20
+ * - callers decide whether to append a trailing newline
21
+ * - there is no backpressure or flush signal
22
+ *
23
+ * @example
24
+ * ```ts
25
+ * const lines: string[] = [];
26
+ * const write: WriteFn = (data) => {
27
+ * lines.push(data);
28
+ * };
29
+ * ```
30
+ */
31
+ type WriteFn = (data: string) => void;
32
+ /**
33
+ * Write a message followed by a newline.
34
+ *
35
+ * @param write - The underlying write function.
36
+ * @param message - The text to write.
37
+ */
38
+ declare function writeLine(write: WriteFn, message: string): void;
39
+ //#endregion
40
+ export { type WriteFn, writeLine };
@@ -0,0 +1 @@
1
+ function e(e,t){e(`${t}\n`)}export{e as writeLine};
@@ -0,0 +1,79 @@
1
+ import { CommandSchema } from "../schema/command.mjs";
2
+
3
+ //#region src/core/parse/index.d.ts
4
+ /**
5
+ * Token discriminated union.
6
+ *
7
+ * The tokenizer produces these from raw argv strings. The parser then
8
+ * interprets them against a command schema.
9
+ */
10
+ type Token = {
11
+ readonly kind: 'long-flag';
12
+ readonly name: string;
13
+ readonly value: string | undefined;
14
+ } | {
15
+ readonly kind: 'short-flags';
16
+ readonly chars: string;
17
+ } | {
18
+ readonly kind: 'positional';
19
+ readonly value: string;
20
+ } | {
21
+ readonly kind: 'separator';
22
+ };
23
+ /**
24
+ * Tokenize raw argv into structured tokens.
25
+ *
26
+ * Low-level utility: most apps should use {@link parse}, `cli().run()`, or
27
+ * `runCommand()` instead of tokenizing manually. Reach for `tokenize()` when
28
+ * building custom tooling such as debuggers, inspectors, or parser tests.
29
+ *
30
+ * Rules:
31
+ * - `--` → separator (everything after is positional)
32
+ * - `--flag` → long flag, no inline value
33
+ * - `--flag=v` → long flag with inline value
34
+ * - `-abc` → short flags (expanded individually by parser)
35
+ * - `-` → positional (convention: stdin placeholder)
36
+ * - everything else → positional
37
+ *
38
+ * @param argv - Raw argument strings to tokenize
39
+ * @returns Ordered token array ready for {@link parse}
40
+ *
41
+ * @example
42
+ * ```ts
43
+ * tokenize(['deploy', '--force', '--region=eu', '-v']);
44
+ * ```
45
+ */
46
+ declare function tokenize(argv: readonly string[]): readonly Token[];
47
+ /**
48
+ * Raw parsed values before resolution (defaults, env, config, etc.).
49
+ *
50
+ * Flag values are `unknown` because type coercion happens here but the
51
+ * generic type info lives in the schema builders, not at runtime.
52
+ */
53
+ interface ParseResult {
54
+ /** Flag values keyed by canonical flag name. */
55
+ readonly flags: Readonly<Record<string, unknown>>;
56
+ /** Positional arg values keyed by arg name. */
57
+ readonly args: Readonly<Record<string, unknown>>;
58
+ }
59
+ /**
60
+ * Parse tokenized argv against a command schema.
61
+ *
62
+ * Low-level API: most apps should let `cli()` or `runCommand()` handle parsing
63
+ * automatically. Call `parse()` directly when you need raw parsed values before
64
+ * env/config/default resolution or when writing custom tooling around schemas.
65
+ *
66
+ * @param schema - The command schema to parse against
67
+ * @param argv - Raw argv strings (NOT including the command name itself)
68
+ * @returns Parsed flag and arg values
69
+ * @throws ParseError for unknown flags, missing values, type mismatches
70
+ *
71
+ * @example
72
+ * ```ts
73
+ * const parsed = parse(deploy.schema, ['production', '--force']);
74
+ * // => { args: { target: 'production' }, flags: { force: true } }
75
+ * ```
76
+ */
77
+ declare function parse(schema: CommandSchema, argv: readonly string[]): ParseResult;
78
+ //#endregion
79
+ export { type ParseResult, type Token, parse, tokenize };
@@ -0,0 +1 @@
1
+ import{getFlagAliasNames as e}from"../schema/flag.mjs";import{ParseError as t}from"../errors/index.mjs";function n(e){let t=[],n=!1;for(let r of e){if(n){t.push({kind:`positional`,value:r});continue}if(r===`--`){t.push({kind:`separator`}),n=!0;continue}if(r.startsWith(`--`)){let e=r.indexOf(`=`);e===-1?t.push({kind:`long-flag`,name:r.slice(2),value:void 0}):t.push({kind:`long-flag`,name:r.slice(2,e),value:r.slice(e+1)});continue}if(r.startsWith(`-`)&&r.length>1){t.push({kind:`short-flags`,chars:r.slice(1)});continue}t.push({kind:`positional`,value:r})}return t}function r(t){let n=new Map;for(let[r,i]of Object.entries(t)){n.set(r,[r,i]);for(let t of e(i,{includeHidden:!0}))n.set(t,[r,i])}return n}function i(e){return e.kind!==`boolean`}function a(e,n,r,i=`--${e}`){switch(r.kind){case`string`:return n;case`number`:{let r=Number(n);if(Number.isNaN(r))throw new t(`Invalid number value '${n}' for flag ${i}`,{code:`INVALID_VALUE`,details:{flag:e,input:i,value:n,expected:`number`}});return r}case`boolean`:if(n===`true`||n===`1`)return!0;if(n===`false`||n===`0`)return!1;throw new t(`Invalid boolean value '${n}' for flag ${i}. Use true/false or 1/0`,{code:`INVALID_VALUE`,details:{flag:e,input:i,value:n,expected:`boolean`}});case`enum`:{let a=r.enumValues;if(a===void 0)throw new t(`Enum flag --${e} is misconfigured: no allowed values declared`,{code:`INVALID_SCHEMA`,details:{flag:e,kind:`enum`,missing:`enumValues`}});if(!a.includes(n))throw new t(`Invalid value '${n}' for flag ${i}. Allowed: ${a.join(`, `)}`,{code:`INVALID_VALUE`,details:{flag:e,input:i,value:n,allowed:a}});return n}case`array`:return r.elementSchema?a(e,n,r.elementSchema):n;case`custom`:if(!r.parseFn)return n;try{return r.parseFn(n)}catch(r){throw r instanceof t?r:new t(`Failed to parse flag ${i}: ${r instanceof Error?r.message:String(r)}`,{code:`INVALID_VALUE`,details:{flag:e,input:i,value:n},cause:r})}}}function o(e,n,r){switch(r.kind){case`string`:return n;case`number`:{let r=Number(n);if(Number.isNaN(r))throw new t(`Invalid number value '${n}' for argument <${e}>`,{code:`INVALID_VALUE`,details:{arg:e,value:n,expected:`number`}});return r}case`enum`:{let i=r.enumValues;if(i===void 0)throw new t(`Enum argument <${e}> is misconfigured: no allowed values declared`,{code:`INVALID_SCHEMA`,details:{arg:e,kind:`enum`,missing:`enumValues`}});if(!i.includes(n))throw new t(`Invalid value '${n}' for argument <${e}>. Allowed: ${i.join(`, `)}`,{code:`INVALID_VALUE`,details:{arg:e,value:n,allowed:i}});return n}case`custom`:if(!r.parseFn)return n;try{return r.parseFn(n)}catch(r){throw r instanceof t?r:new t(`Failed to parse argument <${e}>: ${r instanceof Error?r.message:String(r)}`,{code:`INVALID_VALUE`,details:{arg:e,value:n},cause:r})}}}function s(e,t){let i=n(t),a=r(e.flags),o={},s=[],u=0;for(;u<i.length;){let e=i[u];if(e===void 0)break;if(e.kind===`separator`){u++;continue}if(e.kind===`positional`){s.push(e.value),u++;continue}if(e.kind===`long-flag`){u=c(e,i,u,a,o);continue}u=l(e,i,u,a,o)}return{flags:o,args:d(e.args,s)}}function c(e,n,r,o,s){let c=o.get(e.name);if(!c){let n=f(e.name,o);throw new t(`Unknown flag --${e.name}${n?`. Did you mean --${n}?`:``}`,{code:`UNKNOWN_FLAG`,details:{flag:e.name,...n?{suggestion:n}:{}},...n?{suggest:`--${n}`}:{}})}let[l,d]=c;if(!i(d))return e.value===void 0?s[l]=!0:s[l]=a(l,e.value,d,`--${e.name}`),r+1;if(e.value!==void 0)return u(s,l,d,e.value),r+1;let p=n[r+1];if(!p||p.kind!==`positional`)throw new t(`Flag --${e.name} requires a value`,{code:`MISSING_VALUE`,details:{flag:l,input:e.name,kind:d.kind}});return u(s,l,d,p.value,`--${e.name}`),r+2}function l(e,n,r,a,o){let{chars:s}=e,c=r+1;for(let e=0;e<s.length;e++){let r=s.charAt(e),l=a.get(r);if(!l)throw new t(`Unknown flag -${r}`,{code:`UNKNOWN_FLAG`,details:{flag:r}});let[d,f]=l;if(!i(f)){o[d]=!0;continue}if(e<s.length-1){u(o,d,f,s.slice(e+1),`-${r}`);break}let p=n[c];if(!p||p.kind!==`positional`)throw new t(`Flag -${r} requires a value`,{code:`MISSING_VALUE`,details:{flag:d,input:r,kind:f.kind}});u(o,d,f,p.value,`-${r}`),c++}return c}function u(e,t,n,r,i=`--${t}`){let o=a(t,r,n,i);if(n.kind===`array`){let n=e[t];Array.isArray(n)?n.push(o):e[t]=[o]}else e[t]=o}function d(e,n){let r={},i=0;for(let t of e){if(t.schema.variadic){let e=n.slice(i);r[t.name]=e.map(e=>o(t.name,e,t.schema)),i=n.length;break}let e=n[i];e!==void 0&&(r[t.name]=o(t.name,e,t.schema),i++)}if(i<n.length){let r=n.slice(i);throw new t(`Unexpected positional argument${r.length>1?`s`:``}: ${r.join(`, `)}`,{code:`UNEXPECTED_POSITIONAL`,details:{excess:r,expected:e.length}})}return r}function f(e,t){let n,r=1/0,i=Math.max(2,Math.floor(e.length/2));for(let a of t.keys()){let o=t.get(a);if(o===void 0)continue;let[s,c]=o,l=c.aliases.find(e=>e.name===a);if(a.length<2||a!==s&&l?.hidden)continue;let u=p(e,a);u<r&&u<=i&&(r=u,n=a)}return n}function p(e,t){if(e===t)return 0;if(e.length===0)return t.length;if(t.length===0)return e.length;let n=e.length<=t.length?e:t,r=e.length<=t.length?t:e,i=n.length,a=r.length,o=Array.from({length:i+1},(e,t)=>t);for(let e=1;e<=a;e++){let t=o[0]??0;o[0]=e;for(let a=1;a<=i;a++){let i=n.charAt(a-1)===r.charAt(e-1)?0:1,s=Math.min((o[a]??0)+1,(o[a-1]??0)+1,t+i);t=o[a]??0,o[a]=s}}return o[i]??0}export{s as parse,n as tokenize};
@@ -0,0 +1,205 @@
1
+ import { ConfirmPromptConfig, InputPromptConfig, PromptConfig, PromptResult, SelectChoice } from "../schema/prompt.mjs";
2
+ import { WriteFn } from "../output/writer.mjs";
3
+
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 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:
111
+ *
112
+ * - `string` for `input` and `select`
113
+ * - `boolean` for `confirm`
114
+ * - `string[]` for `multiselect`
115
+ * - `PROMPT_CANCEL` to simulate user cancellation
116
+ *
117
+ * Because the type is intentionally `unknown`, tests may also inject malformed
118
+ * answers to exercise downstream validation and error reporting.
119
+ */
120
+ type TestAnswer = unknown;
121
+ /**
122
+ * Options for `createTestPrompter`.
123
+ */
124
+ interface TestPrompterOptions {
125
+ /**
126
+ * Behavior when all answers have been consumed.
127
+ *
128
+ * - `'throw'` (default) — throws an error, making the test fail
129
+ * loudly if more prompts fire than expected.
130
+ * - `'cancel'` — returns `{ answered: false }`, simulating the
131
+ * user cancelling all subsequent prompts.
132
+ */
133
+ readonly onExhausted?: 'throw' | 'cancel';
134
+ }
135
+ /**
136
+ * Create a prompt engine that returns pre-configured answers.
137
+ *
138
+ * Each call to `promptOne` consumes the next answer from the queue.
139
+ * Pass `PROMPT_CANCEL` as an answer to simulate the user cancelling
140
+ * that prompt.
141
+ *
142
+ * @param answers - Ordered queue of answers. Use `PROMPT_CANCEL` for
143
+ * cancellation.
144
+ * @param options - Controls behavior when the queue is exhausted.
145
+ * @returns A {@linkcode PromptEngine} suitable for testing.
146
+ *
147
+ * @example
148
+ * ```ts
149
+ * const prompter = createTestPrompter(['eu', true, PROMPT_CANCEL]);
150
+ *
151
+ * // First promptOne → { answered: true, value: 'eu' }
152
+ * // Second promptOne → { answered: true, value: true }
153
+ * // Third promptOne → { answered: false }
154
+ * ```
155
+ */
156
+ declare function createTestPrompter(answers: readonly TestAnswer[], options?: TestPrompterOptions): PromptEngine;
157
+ /**
158
+ * Create a prompt engine backed by line-based terminal I/O.
159
+ *
160
+ * Uses a {@linkcode ReadFn} for input and a {@linkcode WriteFn} for output. This is the
161
+ * built-in renderer — sufficient for most CLI use cases. For richer
162
+ * TUI experiences, users can implement {@linkcode PromptEngine} with a library
163
+ * like `@clack/prompts` or `inquirer`.
164
+ *
165
+ * The prompter does **not** use raw mode — all input is line-based.
166
+ * This keeps the implementation portable across Node, Bun, and Deno
167
+ * without platform-specific stdin configuration.
168
+ *
169
+ * @param read - Line reader function (returns `null` on EOF)
170
+ * @param write - Output writer function
171
+ * @returns A {@linkcode PromptEngine} that prompts via terminal I/O
172
+ *
173
+ * @example
174
+ * ```ts
175
+ * import { createInterface } from 'readline';
176
+ *
177
+ * const rl = createInterface({ input: process.stdin, output: process.stdout });
178
+ * const read = () => new Promise<string | null>((resolve) => {
179
+ * rl.question('', (answer) => resolve(answer));
180
+ * });
181
+ * const write: WriteFn = (s) => process.stdout.write(s);
182
+ *
183
+ * const prompter = createTerminalPrompter(read, write);
184
+ * ```
185
+ */
186
+ declare function createTerminalPrompter(read: ReadFn, write: WriteFn): PromptEngine;
187
+ /**
188
+ * Prepare a {@linkcode ResolvedPromptConfig} from a raw {@linkcode PromptConfig} and optional
189
+ * enum values from the flag schema.
190
+ *
191
+ * For select/multiselect prompts without explicit choices, this merges
192
+ * the flag's enum values into the choices list. Throws if no choices
193
+ * are available.
194
+ *
195
+ * This function is called by the resolution chain (prompt-resolve-1),
196
+ * not by the engine itself — keeping the engine free of schema knowledge.
197
+ *
198
+ * @param config - Raw prompt config from `FlagSchema.prompt`
199
+ * @param enumValues - Optional enum values from `FlagSchema.enumValues`
200
+ * @returns Resolved config with choices guaranteed for select kinds
201
+ * @throws Error if select/multiselect has no choices and no enum values
202
+ */
203
+ declare function resolvePromptConfig(config: PromptConfig, enumValues: readonly string[] | undefined): ResolvedPromptConfig;
204
+ //#endregion
205
+ export { PROMPT_CANCEL, type PromptEngine, type ReadFn, type ResolvedMultiselectPromptConfig, type ResolvedPromptConfig, type ResolvedSelectPromptConfig, type TestAnswer, type TestPrompterOptions, createTerminalPrompter, createTestPrompter, resolvePromptConfig };