@kjanat/dreamcli 1.0.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (217) hide show
  1. package/CHANGELOG.md +63 -6
  2. package/LICENSE +1 -1
  3. package/README.md +296 -164
  4. package/dist/core/cli/dispatch.d.mts +85 -0
  5. package/dist/core/cli/dispatch.mjs +1 -0
  6. package/dist/core/cli/index.d.mts +418 -0
  7. package/dist/core/cli/index.mjs +1 -0
  8. package/dist/core/cli/planner.d.mts +143 -0
  9. package/dist/core/cli/planner.mjs +1 -0
  10. package/dist/core/cli/plugin.d.mts +94 -0
  11. package/dist/core/cli/plugin.mjs +1 -0
  12. package/dist/core/cli/propagate.d.mts +39 -0
  13. package/dist/core/cli/propagate.mjs +1 -0
  14. package/dist/core/cli/root-help.d.mts +28 -0
  15. package/dist/core/cli/root-help.mjs +7 -0
  16. package/dist/core/cli/root-surface.d.mts +42 -0
  17. package/dist/core/cli/root-surface.mjs +1 -0
  18. package/dist/core/cli/runtime-preflight.d.mts +149 -0
  19. package/dist/core/cli/runtime-preflight.mjs +1 -0
  20. package/dist/core/completion/index.d.mts +46 -0
  21. package/dist/core/completion/index.mjs +1 -0
  22. package/dist/core/completion/shells/bash.d.mts +24 -0
  23. package/dist/core/completion/shells/bash.mjs +3 -0
  24. package/dist/core/completion/shells/fish.d.mts +20 -0
  25. package/dist/core/completion/shells/fish.mjs +2 -0
  26. package/dist/core/completion/shells/powershell.d.mts +14 -0
  27. package/dist/core/completion/shells/powershell.mjs +2 -0
  28. package/dist/core/completion/shells/shared.d.mts +139 -0
  29. package/dist/core/completion/shells/shared.mjs +1 -0
  30. package/dist/core/completion/shells/zsh.d.mts +24 -0
  31. package/dist/core/completion/shells/zsh.mjs +2 -0
  32. package/dist/core/config/index.d.mts +161 -0
  33. package/dist/core/config/index.mjs +1 -0
  34. package/dist/core/config/package-json.d.mts +68 -0
  35. package/dist/core/config/package-json.mjs +1 -0
  36. package/dist/core/errors/index.d.mts +126 -0
  37. package/dist/core/errors/index.mjs +1 -0
  38. package/dist/core/execution/index.d.mts +49 -0
  39. package/dist/core/execution/index.mjs +1 -0
  40. package/dist/core/help/index.d.mts +49 -0
  41. package/dist/core/help/index.mjs +8 -0
  42. package/dist/core/json-schema/index.d.mts +109 -0
  43. package/dist/core/json-schema/index.mjs +55 -0
  44. package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
  45. package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
  46. package/dist/core/output/activity.d.mts +194 -0
  47. package/dist/core/output/activity.mjs +1 -0
  48. package/dist/core/output/contracts.d.mts +88 -0
  49. package/dist/core/output/contracts.mjs +1 -0
  50. package/dist/core/output/display-value.d.mts +19 -0
  51. package/dist/core/output/display-value.mjs +1 -0
  52. package/dist/core/output/index.d.mts +280 -0
  53. package/dist/core/output/index.mjs +2 -0
  54. package/dist/core/output/renderers.d.mts +46 -0
  55. package/dist/core/output/renderers.mjs +1 -0
  56. package/dist/core/output/writer.d.mts +40 -0
  57. package/dist/core/output/writer.mjs +1 -0
  58. package/dist/core/parse/index.d.mts +79 -0
  59. package/dist/core/parse/index.mjs +1 -0
  60. package/dist/core/prompt/index.d.mts +205 -0
  61. package/dist/core/prompt/index.mjs +6 -0
  62. package/dist/core/resolve/args.d.mts +8 -0
  63. package/dist/core/resolve/args.mjs +1 -0
  64. package/dist/core/resolve/coerce.d.mts +22 -0
  65. package/dist/core/resolve/coerce.mjs +1 -0
  66. package/dist/core/resolve/config.d.mts +10 -0
  67. package/dist/core/resolve/config.mjs +1 -0
  68. package/dist/core/resolve/contracts.d.mts +112 -0
  69. package/dist/core/resolve/errors.d.mts +11 -0
  70. package/dist/core/resolve/errors.mjs +2 -0
  71. package/dist/core/resolve/flags.d.mts +10 -0
  72. package/dist/core/resolve/flags.mjs +1 -0
  73. package/dist/core/resolve/index.d.mts +42 -0
  74. package/dist/core/resolve/index.mjs +1 -0
  75. package/dist/core/resolve/property.d.mts +47 -0
  76. package/dist/core/resolve/property.mjs +1 -0
  77. package/dist/core/schema/activity.d.mts +169 -0
  78. package/dist/core/schema/arg.d.mts +559 -0
  79. package/dist/core/schema/arg.mjs +1 -0
  80. package/dist/core/schema/command.d.mts +960 -0
  81. package/dist/core/schema/command.mjs +1 -0
  82. package/dist/core/schema/flag.d.mts +491 -0
  83. package/dist/core/schema/flag.mjs +1 -0
  84. package/dist/core/schema/index.d.mts +8 -0
  85. package/dist/core/schema/middleware.d.mts +122 -0
  86. package/dist/core/schema/middleware.mjs +1 -0
  87. package/dist/core/schema/prompt.d.mts +117 -0
  88. package/dist/core/schema/run.d.mts +171 -0
  89. package/dist/core/schema-dsl/runtime.d.mts +144 -0
  90. package/dist/core/schema-dsl/runtime.mjs +2 -0
  91. package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
  92. package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
  93. package/dist/core/testkit/index.d.mts +54 -0
  94. package/dist/core/testkit/index.mjs +1 -0
  95. package/dist/index.d.mts +28 -920
  96. package/dist/index.mjs +1 -10
  97. package/dist/runtime/adapter.d.mts +212 -0
  98. package/dist/{adapter-B37d9oia.mjs → runtime/adapter.mjs} +1 -1
  99. package/dist/runtime/auto.d.mts +26 -0
  100. package/dist/runtime/auto.mjs +1 -0
  101. package/dist/runtime/bun.d.mts +28 -0
  102. package/dist/runtime/bun.mjs +1 -0
  103. package/dist/runtime/deno.d.mts +76 -0
  104. package/dist/runtime/deno.mjs +2 -0
  105. package/dist/runtime/detect.d.mts +86 -0
  106. package/dist/runtime/detect.mjs +1 -0
  107. package/dist/runtime/index.d.mts +7 -0
  108. package/dist/runtime/node.d.mts +65 -0
  109. package/dist/runtime/node.mjs +2 -0
  110. package/dist/runtime/paths.d.mts +31 -0
  111. package/dist/runtime/paths.mjs +1 -0
  112. package/dist/runtime/support.d.mts +42 -0
  113. package/dist/runtime/support.mjs +1 -0
  114. package/dist/runtime.d.mts +6 -252
  115. package/dist/runtime.mjs +1 -1
  116. package/dist/testkit.d.mts +5 -24
  117. package/dist/testkit.mjs +1 -1
  118. package/dist/version.d.mts +16 -0
  119. package/dist/version.mjs +1 -0
  120. package/dreamcli.schema.json +338 -0
  121. package/examples/basic.ts +2 -2
  122. package/examples/gh/package.json +7 -11
  123. package/examples/gh/src/commands/auth.ts +2 -2
  124. package/examples/gh/src/commands/issue.ts +4 -4
  125. package/examples/gh/src/commands/pr.ts +4 -4
  126. package/examples/gh/src/docs.ts +11 -0
  127. package/examples/gh/src/lib/auth.ts +1 -1
  128. package/examples/gh/src/main.test.ts +6 -5
  129. package/examples/gh/src/main.ts +8 -6
  130. package/examples/interactive.ts +3 -3
  131. package/examples/json-mode.ts +4 -6
  132. package/examples/middleware.ts +3 -3
  133. package/examples/multi-command.ts +3 -3
  134. package/examples/spinner-progress.ts +5 -5
  135. package/examples/testing.ts +8 -6
  136. package/package.json +70 -44
  137. package/src/core/cli/dispatch.ts +4 -0
  138. package/src/core/cli/index.ts +185 -632
  139. package/src/core/cli/planner.ts +413 -0
  140. package/src/core/cli/plugin.ts +7 -1
  141. package/src/core/cli/propagate.ts +1 -1
  142. package/src/core/cli/runtime-preflight.ts +409 -0
  143. package/src/core/completion/index.ts +15 -9
  144. package/src/core/completion/shells/bash.ts +6 -3
  145. package/src/core/completion/shells/fish.ts +245 -10
  146. package/src/core/completion/shells/powershell.ts +390 -9
  147. package/src/core/completion/shells/shared.ts +4 -4
  148. package/src/core/completion/shells/zsh.ts +12 -7
  149. package/src/core/config/index.ts +7 -4
  150. package/src/core/config/package-json.ts +6 -2
  151. package/src/core/errors/index.ts +23 -8
  152. package/src/core/execution/index.ts +270 -0
  153. package/src/core/help/index.ts +13 -15
  154. package/src/core/json-schema/index.ts +193 -7
  155. package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
  156. package/src/core/output/contracts.ts +194 -0
  157. package/src/core/output/index.ts +47 -82
  158. package/src/core/output/renderers.ts +125 -0
  159. package/src/core/parse/index.ts +39 -21
  160. package/src/core/prompt/index.ts +44 -27
  161. package/src/core/resolve/args.ts +144 -0
  162. package/src/core/resolve/coerce.ts +432 -0
  163. package/src/core/resolve/config.ts +26 -0
  164. package/src/core/resolve/contracts.ts +135 -0
  165. package/src/core/resolve/errors.ts +227 -0
  166. package/src/core/resolve/flags.ts +205 -0
  167. package/src/core/resolve/index.ts +41 -1264
  168. package/src/core/resolve/property.ts +99 -0
  169. package/src/core/schema/activity.ts +3 -0
  170. package/src/core/schema/arg.ts +26 -14
  171. package/src/core/schema/command.ts +265 -38
  172. package/src/core/schema/flag.ts +120 -15
  173. package/src/core/schema/index.ts +11 -2
  174. package/src/core/schema/middleware.ts +6 -6
  175. package/src/core/schema/prompt.ts +9 -1
  176. package/src/core/schema/run.ts +25 -17
  177. package/src/core/schema-dsl/index.ts +109 -0
  178. package/src/core/schema-dsl/parse.ts +262 -0
  179. package/src/core/schema-dsl/runtime.ts +609 -0
  180. package/src/core/schema-dsl/to-json-schema.ts +102 -0
  181. package/src/core/testkit/index.ts +55 -297
  182. package/src/index.ts +10 -4
  183. package/src/runtime/adapter.ts +13 -10
  184. package/src/runtime/auto.ts +3 -3
  185. package/src/runtime/bun.ts +4 -4
  186. package/src/runtime/deno.ts +43 -29
  187. package/src/runtime/detect.ts +4 -1
  188. package/src/runtime/index.ts +1 -1
  189. package/src/runtime/node.ts +43 -21
  190. package/src/runtime/paths.ts +9 -3
  191. package/src/runtime/support.ts +20 -4
  192. package/src/runtime.ts +1 -1
  193. package/src/testkit.ts +10 -8
  194. package/dist/adapter-CCSh5juX.cjs +0 -1
  195. package/dist/adapter-DIwO-q7K.d.mts +0 -3447
  196. package/dist/adapter-DQnxxLiE.d.cts +0 -3447
  197. package/dist/auto-5cjZaF9V.mjs +0 -3
  198. package/dist/auto-B0eSgoDw.cjs +0 -3
  199. package/dist/index.cjs +0 -10
  200. package/dist/index.d.cts +0 -920
  201. package/dist/runtime.cjs +0 -1
  202. package/dist/runtime.d.cts +0 -253
  203. package/dist/testkit-CEDYPvhF.mjs +0 -14
  204. package/dist/testkit-ClIKijxC.cjs +0 -14
  205. package/dist/testkit.cjs +0 -1
  206. package/dist/testkit.d.cts +0 -25
  207. package/examples/gh/tsconfig.json +0 -37
  208. package/examples/tsconfig.json +0 -17
  209. package/src/core/cli/AGENTS.md +0 -72
  210. package/src/core/completion/AGENTS.md +0 -72
  211. package/src/core/completion/completion-test-helpers.ts +0 -48
  212. package/src/core/output/AGENTS.md +0 -69
  213. package/src/core/resolve/AGENTS.md +0 -69
  214. package/src/core/schema/AGENTS.md +0 -61
  215. package/src/core/testkit/AGENTS.md +0 -55
  216. package/src/runtime/AGENTS.md +0 -74
  217. package/src/runtime/test-helpers.ts +0 -40
@@ -5,7 +5,7 @@
5
5
  * raw `console.log`. The channel respects TTY vs piped contexts and
6
6
  * supports verbosity levels (quiet mode suppresses `info`).
7
7
  *
8
- * The `Out` interface (the contract handlers depend on) lives in
8
+ * The {@linkcode Out} interface (the contract handlers depend on) lives in
9
9
  * `src/core/schema/command.ts`. This module provides the implementation.
10
10
  *
11
11
  * @module dreamcli/core/output
@@ -31,20 +31,25 @@ import {
31
31
  TTYProgressHandle,
32
32
  TTYSpinnerHandle,
33
33
  } from './activity.ts';
34
+ import type { OutputPolicy, Verbosity } from './contracts.ts';
35
+ import {
36
+ resolveOutputPolicy,
37
+ resolveProgressPolicy,
38
+ resolveSpinnerPolicy,
39
+ resolveTableFormat,
40
+ resolveTableTextStream,
41
+ resolveTextStream,
42
+ shouldEmitInfo,
43
+ } from './contracts.ts';
34
44
  import { formatDisplayValue } from './display-value.ts';
45
+ import {
46
+ createProgressHandleFromPolicy,
47
+ createSpinnerHandleFromPolicy,
48
+ resolveWriterForStream,
49
+ } from './renderers.ts';
35
50
  import type { WriteFn } from './writer.ts';
36
51
  import { writeLine } from './writer.ts';
37
52
 
38
- // --- Verbosity
39
-
40
- /**
41
- * Controls which messages are emitted.
42
- *
43
- * - `'normal'` — all messages
44
- * - `'quiet'` — suppresses `info`; keeps `log`, `warn`, `error`
45
- */
46
- type Verbosity = 'normal' | 'quiet';
47
-
48
53
  // --- Options
49
54
 
50
55
  /**
@@ -124,13 +129,13 @@ function resolveOptions(options?: OutputOptions): ResolvedOutputOptions {
124
129
  // --- OutputChannel — the concrete Out implementation
125
130
 
126
131
  /**
127
- * Concrete implementation of the `Out` interface.
132
+ * Concrete implementation of the {@linkcode Out} interface.
128
133
  *
129
134
  * Routes messages to the appropriate writer (stdout vs stderr) and
130
135
  * respects the configured verbosity level.
131
136
  *
132
- * Handlers interact with this via the `Out` interface — they never see
133
- * `OutputChannel` directly, which keeps the coupling minimal.
137
+ * Handlers interact with this via the {@linkcode Out} interface — they never see
138
+ * {@linkcode OutputChannel} directly, which keeps the coupling minimal.
134
139
  * Prefer {@link createOutput} unless you are extending the output layer.
135
140
  *
136
141
  * @internal
@@ -139,6 +144,9 @@ class OutputChannel implements Out {
139
144
  /** @internal Resolved configuration. */
140
145
  readonly options: ResolvedOutputOptions;
141
146
 
147
+ /** Semantic output policy snapshot shared by routing helpers. */
148
+ readonly policy: OutputPolicy;
149
+
142
150
  /** Whether JSON output mode is active. */
143
151
  readonly jsonMode: boolean;
144
152
 
@@ -153,6 +161,7 @@ class OutputChannel implements Out {
153
161
 
154
162
  constructor(options: ResolvedOutputOptions) {
155
163
  this.options = options;
164
+ this.policy = resolveOutputPolicy(options);
156
165
  this.jsonMode = options.jsonMode;
157
166
  this.isTTY = options.isTTY;
158
167
  }
@@ -164,7 +173,7 @@ class OutputChannel implements Out {
164
173
  * structured `json()` output only.
165
174
  */
166
175
  log(message: string): void {
167
- const writer = this.options.jsonMode ? this.options.stderr : this.options.stdout;
176
+ const writer = resolveWriterForStream(this.options, resolveTextStream(this.policy));
168
177
  writeLine(writer, message);
169
178
  }
170
179
 
@@ -175,8 +184,8 @@ class OutputChannel implements Out {
175
184
  * In JSON mode, redirected to stderr.
176
185
  */
177
186
  info(message: string): void {
178
- if (this.options.verbosity === 'quiet') return;
179
- const writer = this.options.jsonMode ? this.options.stderr : this.options.stdout;
187
+ if (!shouldEmitInfo(this.policy)) return;
188
+ const writer = resolveWriterForStream(this.options, resolveTextStream(this.policy));
180
189
  writeLine(writer, message);
181
190
  }
182
191
 
@@ -222,7 +231,7 @@ class OutputChannel implements Out {
222
231
  options?: TableOptions,
223
232
  ): void {
224
233
  const { columns, options: tableOptions } = resolveTableArgs(columnsOrOptions, options);
225
- const format = resolveTableFormat(this.options.jsonMode, tableOptions);
234
+ const format = resolveTableFormat(this.policy, tableOptions);
226
235
  const resolved = columns ?? inferColumns(rows);
227
236
 
228
237
  if (format === 'json') {
@@ -233,7 +242,7 @@ class OutputChannel implements Out {
233
242
  const text = formatTable(rows, resolved);
234
243
  if (text.length === 0) return;
235
244
 
236
- writeLine(resolveTextTableWriter(this.options, format, tableOptions), text);
245
+ writeLine(resolveTextTableWriter(this.options, this.policy, format, tableOptions), text);
237
246
  }
238
247
 
239
248
  // ----- Active handle tracking -----
@@ -285,31 +294,17 @@ class OutputChannel implements Out {
285
294
  * @virtual
286
295
  */
287
296
  spinner(text: string, options?: SpinnerOptions): SpinnerHandle {
288
- const fallback = options?.fallback ?? 'silent';
297
+ const policy = resolveSpinnerPolicy(this.policy, options?.fallback ?? 'silent');
298
+ const rendered = createSpinnerHandleFromPolicy(policy, text, this.options.stderr);
289
299
 
290
- // JSON mode: always suppress activity indicators.
291
- if (this.options.jsonMode) {
292
- return noopSpinnerHandle;
293
- }
294
-
295
- // Non-TTY, silent fallback: noop.
296
- if (!this.options.isTTY && fallback === 'silent') {
297
- return noopSpinnerHandle;
300
+ if (rendered.cleanup === undefined) {
301
+ return rendered.handle;
298
302
  }
299
303
 
300
304
  // Stop any active handle before creating a new one.
301
305
  this.stopActive();
302
-
303
- if (this.options.isTTY) {
304
- const handle = new TTYSpinnerHandle(text, this.options.stderr);
305
- this.activeCleanup = () => handle.stop();
306
- return handle;
307
- }
308
-
309
- // Non-TTY, static fallback.
310
- const handle = new StaticSpinnerHandle(text, this.options.stderr);
311
- this.activeCleanup = () => handle.stop();
312
- return handle;
306
+ this.activeCleanup = rendered.cleanup;
307
+ return rendered.handle;
313
308
  }
314
309
 
315
310
  /**
@@ -330,31 +325,17 @@ class OutputChannel implements Out {
330
325
  * @virtual
331
326
  */
332
327
  progress(opts: ProgressOptions): ProgressHandle {
333
- const fallback = opts.fallback ?? 'silent';
334
-
335
- // JSON mode: always suppress activity indicators.
336
- if (this.options.jsonMode) {
337
- return noopProgressHandle;
338
- }
328
+ const policy = resolveProgressPolicy(this.policy, opts.fallback ?? 'silent');
329
+ const rendered = createProgressHandleFromPolicy(policy, opts, this.options.stderr);
339
330
 
340
- // Non-TTY, silent fallback: noop.
341
- if (!this.options.isTTY && fallback === 'silent') {
342
- return noopProgressHandle;
331
+ if (rendered.cleanup === undefined) {
332
+ return rendered.handle;
343
333
  }
344
334
 
345
335
  // Stop any active handle before creating a new one.
346
336
  this.stopActive();
347
-
348
- if (this.options.isTTY) {
349
- const handle = new TTYProgressHandle(opts, this.options.stderr);
350
- this.activeCleanup = () => handle.done();
351
- return handle;
352
- }
353
-
354
- // Non-TTY, static fallback.
355
- const handle = new StaticProgressHandle(opts.label, this.options.stderr);
356
- this.activeCleanup = () => handle.done();
357
- return handle;
337
+ this.activeCleanup = rendered.cleanup;
338
+ return rendered.handle;
358
339
  }
359
340
  }
360
341
 
@@ -363,8 +344,8 @@ class OutputChannel implements Out {
363
344
  /**
364
345
  * Output channel variant that returns capture handles for spinner/progress.
365
346
  *
366
- * Extends `OutputChannel` to override `spinner()` and `progress()`, routing
367
- * activity events into a shared `ActivityEvent[]` for testkit assertion.
347
+ * Extends {@linkcode OutputChannel} to override `spinner()` and `progress()`, routing
348
+ * activity events into a shared {@linkcode ActivityEvent | ActivityEvent[]} for testkit assertion.
368
349
  * Text output (log/info/warn/error) is handled by the parent class.
369
350
  *
370
351
  * @internal
@@ -477,23 +458,11 @@ function projectTableRows<T extends Record<string, unknown>>(
477
458
  * @param options - Per-call table options (may specify an explicit format).
478
459
  * @returns `'text'` or `'json'`.
479
460
  */
480
- function resolveTableFormat(jsonMode: boolean, options?: TableOptions): 'text' | 'json' {
481
- switch (options?.format) {
482
- case 'json':
483
- return 'json';
484
- case 'text':
485
- return 'text';
486
- case 'auto':
487
- case undefined:
488
- return jsonMode ? 'json' : 'text';
489
- }
490
- }
491
-
492
461
  /**
493
462
  * Pick the {@link WriteFn} for a text-mode table.
494
463
  *
495
464
  * Respects `tableOptions.stream` when present; otherwise falls back to
496
- * the channel's default (stderr in JSON mode, stdout otherwise).
465
+ * the channel's default policy-owned text stream.
497
466
  *
498
467
  * @param options - Resolved channel options.
499
468
  * @param format - Resolved table format.
@@ -502,19 +471,15 @@ function resolveTableFormat(jsonMode: boolean, options?: TableOptions): 'text' |
502
471
  */
503
472
  function resolveTextTableWriter(
504
473
  options: ResolvedOutputOptions,
474
+ policy: OutputPolicy,
505
475
  format: 'text' | 'json',
506
476
  tableOptions?: TableOptions,
507
477
  ): WriteFn {
508
- if (
509
- format === 'text' &&
510
- tableOptions !== undefined &&
511
- 'stream' in tableOptions &&
512
- tableOptions.stream !== undefined
513
- ) {
514
- return tableOptions.stream === 'stderr' ? options.stderr : options.stdout;
478
+ if (format === 'json') {
479
+ return options.stdout;
515
480
  }
516
481
 
517
- return options.jsonMode ? options.stderr : options.stdout;
482
+ return resolveWriterForStream(options, resolveTableTextStream(policy, tableOptions));
518
483
  }
519
484
 
520
485
  /**
@@ -0,0 +1,125 @@
1
+ /**
2
+ * Internal output renderer factories.
3
+ *
4
+ * Keeps concrete writer and activity-handle construction separate from the
5
+ * semantic output-policy layer.
6
+ *
7
+ * @module dreamcli/core/output/renderers
8
+ * @internal
9
+ */
10
+
11
+ import type {
12
+ ProgressHandle,
13
+ ProgressOptions,
14
+ SpinnerHandle,
15
+ } from '#internals/core/schema/activity.ts';
16
+ import {
17
+ noopProgressHandle,
18
+ noopSpinnerHandle,
19
+ StaticProgressHandle,
20
+ StaticSpinnerHandle,
21
+ TTYProgressHandle,
22
+ TTYSpinnerHandle,
23
+ } from './activity.ts';
24
+ import type { ActivityPolicy, OutputStream } from './contracts.ts';
25
+ import type { WriteFn } from './writer.ts';
26
+
27
+ /**
28
+ * Paired write functions for the two standard output streams.
29
+ *
30
+ * @internal
31
+ */
32
+ interface OutputWriters {
33
+ /** Write function targeting standard output. */
34
+ readonly stdout: WriteFn;
35
+ /** Write function targeting standard error. */
36
+ readonly stderr: WriteFn;
37
+ }
38
+
39
+ /**
40
+ * Spinner handle paired with its optional teardown function.
41
+ *
42
+ * @internal
43
+ */
44
+ interface SpinnerRenderResult {
45
+ /** The spinner handle exposed to command handlers. */
46
+ readonly handle: SpinnerHandle;
47
+ /** Defined only when the mode requires cleanup (TTY or static); `undefined` for noop. */
48
+ readonly cleanup: (() => void) | undefined;
49
+ }
50
+
51
+ /**
52
+ * Progress handle paired with its optional teardown function.
53
+ *
54
+ * @internal
55
+ */
56
+ interface ProgressRenderResult {
57
+ /** The progress handle exposed to command handlers. */
58
+ readonly handle: ProgressHandle;
59
+ /** Defined only when the mode requires cleanup (TTY or static); `undefined` for noop. */
60
+ readonly cleanup: (() => void) | undefined;
61
+ }
62
+
63
+ /** Select the concrete {@linkcode WriteFn} for a given stream label. @internal */
64
+ function resolveWriterForStream(writers: OutputWriters, stream: OutputStream): WriteFn {
65
+ return stream === 'stderr' ? writers.stderr : writers.stdout;
66
+ }
67
+
68
+ /** Create a spinner handle matching the resolved {@linkcode ActivityPolicy} mode. @internal */
69
+ function createSpinnerHandleFromPolicy(
70
+ policy: ActivityPolicy,
71
+ text: string,
72
+ stderr: WriteFn,
73
+ ): SpinnerRenderResult {
74
+ if (policy.mode === 'noop') {
75
+ return {
76
+ handle: noopSpinnerHandle,
77
+ cleanup: undefined,
78
+ };
79
+ }
80
+
81
+ if (policy.mode === 'tty') {
82
+ const handle = new TTYSpinnerHandle(text, stderr);
83
+ return {
84
+ handle,
85
+ cleanup: () => handle.stop(),
86
+ };
87
+ }
88
+
89
+ const handle = new StaticSpinnerHandle(text, stderr);
90
+ return {
91
+ handle,
92
+ cleanup: () => handle.stop(),
93
+ };
94
+ }
95
+
96
+ /** Create a progress handle matching the resolved {@linkcode ActivityPolicy} mode. @internal */
97
+ function createProgressHandleFromPolicy(
98
+ policy: ActivityPolicy,
99
+ options: ProgressOptions,
100
+ stderr: WriteFn,
101
+ ): ProgressRenderResult {
102
+ if (policy.mode === 'noop') {
103
+ return {
104
+ handle: noopProgressHandle,
105
+ cleanup: undefined,
106
+ };
107
+ }
108
+
109
+ if (policy.mode === 'tty') {
110
+ const handle = new TTYProgressHandle(options, stderr);
111
+ return {
112
+ handle,
113
+ cleanup: () => handle.done(),
114
+ };
115
+ }
116
+
117
+ const handle = new StaticProgressHandle(options.label, stderr);
118
+ return {
119
+ handle,
120
+ cleanup: () => handle.done(),
121
+ };
122
+ }
123
+
124
+ export type { OutputWriters, ProgressRenderResult, SpinnerRenderResult };
125
+ export { createProgressHandleFromPolicy, createSpinnerHandleFromPolicy, resolveWriterForStream };
@@ -6,14 +6,15 @@
6
6
  * 1. **Tokenize** — split raw argv into structured tokens (long flags, short
7
7
  * flags, positionals, separator). Schema-agnostic.
8
8
  *
9
- * 2. **Parse** — walk tokens against a `CommandSchema` to produce typed raw
10
- * values. Emits `ParseError` for unknown flags, type mismatches, missing
9
+ * 2. **Parse** — walk tokens against a {@linkcode CommandSchema} to produce typed raw
10
+ * values. Emits {@linkcode ParseError} for unknown flags, type mismatches, missing
11
11
  * values.
12
12
  *
13
13
  * @module dreamcli/core/parse
14
14
  */
15
15
 
16
16
  import { ParseError } from '#internals/core/errors/index.ts';
17
+ import { getFlagAliasNames } from '#internals/core/schema/flag.ts';
17
18
  import type {
18
19
  ArgSchema,
19
20
  CommandArgEntry,
@@ -131,7 +132,7 @@ function buildFlagLookup(
131
132
  const lookup = new Map<string, readonly [string, FlagSchema]>();
132
133
  for (const [name, schema] of Object.entries(flags)) {
133
134
  lookup.set(name, [name, schema]);
134
- for (const alias of schema.aliases) {
135
+ for (const alias of getFlagAliasNames(schema, { includeHidden: true })) {
135
136
  lookup.set(alias, [name, schema]);
136
137
  }
137
138
  }
@@ -159,7 +160,12 @@ function flagExpectsValue(schema: FlagSchema): boolean {
159
160
  * @returns Coerced value matching the schema's kind
160
161
  * @throws ParseError on type mismatch
161
162
  */
162
- function coerceFlagValue(flagName: string, raw: string, schema: FlagSchema): unknown {
163
+ function coerceFlagValue(
164
+ flagName: string,
165
+ raw: string,
166
+ schema: FlagSchema,
167
+ displayName = `--${flagName}`,
168
+ ): unknown {
163
169
  switch (schema.kind) {
164
170
  case 'string':
165
171
  return raw;
@@ -167,9 +173,9 @@ function coerceFlagValue(flagName: string, raw: string, schema: FlagSchema): unk
167
173
  case 'number': {
168
174
  const n = Number(raw);
169
175
  if (Number.isNaN(n)) {
170
- throw new ParseError(`Invalid number value '${raw}' for flag --${flagName}`, {
176
+ throw new ParseError(`Invalid number value '${raw}' for flag ${displayName}`, {
171
177
  code: 'INVALID_VALUE',
172
- details: { flag: flagName, value: raw, expected: 'number' },
178
+ details: { flag: flagName, input: displayName, value: raw, expected: 'number' },
173
179
  });
174
180
  }
175
181
  return n;
@@ -180,10 +186,10 @@ function coerceFlagValue(flagName: string, raw: string, schema: FlagSchema): unk
180
186
  if (raw === 'true' || raw === '1') return true;
181
187
  if (raw === 'false' || raw === '0') return false;
182
188
  throw new ParseError(
183
- `Invalid boolean value '${raw}' for flag --${flagName}. Use true/false or 1/0`,
189
+ `Invalid boolean value '${raw}' for flag ${displayName}. Use true/false or 1/0`,
184
190
  {
185
191
  code: 'INVALID_VALUE',
186
- details: { flag: flagName, value: raw, expected: 'boolean' },
192
+ details: { flag: flagName, input: displayName, value: raw, expected: 'boolean' },
187
193
  },
188
194
  );
189
195
 
@@ -200,10 +206,10 @@ function coerceFlagValue(flagName: string, raw: string, schema: FlagSchema): unk
200
206
  }
201
207
  if (!allowed.includes(raw)) {
202
208
  throw new ParseError(
203
- `Invalid value '${raw}' for flag --${flagName}. Allowed: ${allowed.join(', ')}`,
209
+ `Invalid value '${raw}' for flag ${displayName}. Allowed: ${allowed.join(', ')}`,
204
210
  {
205
211
  code: 'INVALID_VALUE',
206
- details: { flag: flagName, value: raw, allowed },
212
+ details: { flag: flagName, input: displayName, value: raw, allowed },
207
213
  },
208
214
  );
209
215
  }
@@ -226,9 +232,9 @@ function coerceFlagValue(flagName: string, raw: string, schema: FlagSchema): unk
226
232
  } catch (err) {
227
233
  if (err instanceof ParseError) throw err;
228
234
  const message = err instanceof Error ? err.message : String(err);
229
- throw new ParseError(`Failed to parse flag --${flagName}: ${message}`, {
235
+ throw new ParseError(`Failed to parse flag ${displayName}: ${message}`, {
230
236
  code: 'INVALID_VALUE',
231
- details: { flag: flagName, value: raw },
237
+ details: { flag: flagName, input: displayName, value: raw },
232
238
  cause: err,
233
239
  });
234
240
  }
@@ -399,7 +405,12 @@ function parseLongFlag(
399
405
  if (!flagExpectsValue(flagSchema)) {
400
406
  // Boolean flag
401
407
  if (token.value !== undefined) {
402
- flags[canonicalName] = coerceFlagValue(canonicalName, token.value, flagSchema);
408
+ flags[canonicalName] = coerceFlagValue(
409
+ canonicalName,
410
+ token.value,
411
+ flagSchema,
412
+ `--${token.name}`,
413
+ );
403
414
  } else {
404
415
  flags[canonicalName] = true;
405
416
  }
@@ -415,12 +426,12 @@ function parseLongFlag(
415
426
  // --flag value (next token is the value)
416
427
  const nextToken = tokens[startIdx + 1];
417
428
  if (!nextToken || nextToken.kind !== 'positional') {
418
- throw new ParseError(`Flag --${canonicalName} requires a value`, {
429
+ throw new ParseError(`Flag --${token.name} requires a value`, {
419
430
  code: 'MISSING_VALUE',
420
- details: { flag: canonicalName, kind: flagSchema.kind },
431
+ details: { flag: canonicalName, input: token.name, kind: flagSchema.kind },
421
432
  });
422
433
  }
423
- setFlagValue(flags, canonicalName, flagSchema, nextToken.value);
434
+ setFlagValue(flags, canonicalName, flagSchema, nextToken.value, `--${token.name}`);
424
435
  return startIdx + 2;
425
436
  }
426
437
 
@@ -468,7 +479,7 @@ function parseShortFlags(
468
479
  // Value-expecting flag in the middle of combined shorts:
469
480
  // -oFile → -o with value "File" (rest of chars is the value)
470
481
  const inlineValue = chars.slice(ci + 1);
471
- setFlagValue(flags, canonicalName, flagSchema, inlineValue);
482
+ setFlagValue(flags, canonicalName, flagSchema, inlineValue, `-${ch}`);
472
483
  break; // consumed all remaining chars
473
484
  }
474
485
 
@@ -477,10 +488,10 @@ function parseShortFlags(
477
488
  if (!nextToken || nextToken.kind !== 'positional') {
478
489
  throw new ParseError(`Flag -${ch} requires a value`, {
479
490
  code: 'MISSING_VALUE',
480
- details: { flag: ch, canonical: canonicalName, kind: flagSchema.kind },
491
+ details: { flag: canonicalName, input: ch, kind: flagSchema.kind },
481
492
  });
482
493
  }
483
- setFlagValue(flags, canonicalName, flagSchema, nextToken.value);
494
+ setFlagValue(flags, canonicalName, flagSchema, nextToken.value, `-${ch}`);
484
495
  nextIdx++;
485
496
  }
486
497
 
@@ -502,8 +513,9 @@ function setFlagValue(
502
513
  name: string,
503
514
  schema: FlagSchema,
504
515
  rawValue: string,
516
+ displayName = `--${name}`,
505
517
  ): void {
506
- const coerced = coerceFlagValue(name, rawValue, schema);
518
+ const coerced = coerceFlagValue(name, rawValue, schema, displayName);
507
519
 
508
520
  if (schema.kind === 'array') {
509
521
  const existing = flags[name];
@@ -584,8 +596,14 @@ function suggestFlag(
584
596
  const threshold = Math.max(2, Math.floor(input.length / 2));
585
597
 
586
598
  for (const key of lookup.keys()) {
587
- // Only suggest long names (not single-char aliases)
599
+ const entry = lookup.get(key);
600
+ if (entry === undefined) continue;
601
+ const [canonicalName, schema] = entry;
602
+ const alias = schema.aliases.find((candidate) => candidate.name === key);
603
+
604
+ // Only suggest canonical names or visible long aliases.
588
605
  if (key.length < 2) continue;
606
+ if (key !== canonicalName && alias?.hidden) continue;
589
607
 
590
608
  const dist = levenshtein(input, key);
591
609
  if (dist < bestDist && dist <= threshold) {