@kjanat/dreamcli 2.5.0 → 3.0.0-rc.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (202) hide show
  1. package/CHANGELOG.md +344 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/dispatch.d.mts +6 -5
  4. package/dist/core/cli/dispatch.mjs +205 -1
  5. package/dist/core/cli/help-links.d.mts +0 -1
  6. package/dist/core/cli/help-links.mjs +41 -1
  7. package/dist/core/cli/index.d.mts +185 -19
  8. package/dist/core/cli/index.mjs +945 -1
  9. package/dist/core/cli/planner.d.mts +32 -6
  10. package/dist/core/cli/planner.mjs +300 -1
  11. package/dist/core/cli/plugin.d.mts +1 -1
  12. package/dist/core/cli/plugin.mjs +41 -1
  13. package/dist/core/cli/propagate.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +57 -1
  15. package/dist/core/cli/root-help.d.mts +18 -3
  16. package/dist/core/cli/root-help.mjs +226 -6
  17. package/dist/core/cli/root-surface.d.mts +30 -4
  18. package/dist/core/cli/root-surface.mjs +28 -1
  19. package/dist/core/cli/runtime-preflight.d.mts +30 -3
  20. package/dist/core/cli/runtime-preflight.mjs +169 -1
  21. package/dist/core/completion/index.d.mts +32 -2
  22. package/dist/core/completion/index.mjs +90 -1
  23. package/dist/core/completion/shells/bash.d.mts +0 -1
  24. package/dist/core/completion/shells/bash.mjs +308 -3
  25. package/dist/core/completion/shells/fish.d.mts +0 -1
  26. package/dist/core/completion/shells/fish.mjs +162 -2
  27. package/dist/core/completion/shells/powershell.d.mts +0 -1
  28. package/dist/core/completion/shells/powershell.mjs +358 -2
  29. package/dist/core/completion/shells/shared.d.mts +23 -2
  30. package/dist/core/completion/shells/shared.mjs +176 -1
  31. package/dist/core/completion/shells/zsh.d.mts +0 -1
  32. package/dist/core/completion/shells/zsh.mjs +251 -2
  33. package/dist/core/config/index.d.mts +2 -3
  34. package/dist/core/config/index.mjs +246 -1
  35. package/dist/core/config/package-json.d.mts +27 -4
  36. package/dist/core/config/package-json.mjs +386 -3
  37. package/dist/core/errors/index.d.mts +3 -3
  38. package/dist/core/errors/index.mjs +87 -1
  39. package/dist/core/execution/index.d.mts +0 -1
  40. package/dist/core/execution/index.mjs +201 -1
  41. package/dist/core/help/ansi.d.mts +11 -5
  42. package/dist/core/help/ansi.mjs +121 -2
  43. package/dist/core/help/index.d.mts +65 -2
  44. package/dist/core/help/index.mjs +341 -7
  45. package/dist/core/help/theme.d.mts +68 -0
  46. package/dist/core/help/theme.mjs +46 -0
  47. package/dist/core/json-schema/index.d.mts +15 -2
  48. package/dist/core/json-schema/index.mjs +536 -12
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
  51. package/dist/core/output/activity.d.mts +0 -1
  52. package/dist/core/output/activity.mjs +452 -1
  53. package/dist/core/output/bind.mjs +56 -1
  54. package/dist/core/output/contracts.d.mts +4 -5
  55. package/dist/core/output/contracts.mjs +57 -1
  56. package/dist/core/output/display-value.mjs +32 -1
  57. package/dist/core/output/index.d.mts +21 -1
  58. package/dist/core/output/index.mjs +442 -2
  59. package/dist/core/output/renderers.d.mts +0 -1
  60. package/dist/core/output/renderers.mjs +46 -1
  61. package/dist/core/output/writer.mjs +12 -1
  62. package/dist/core/parse/index.d.mts +54 -7
  63. package/dist/core/parse/index.mjs +727 -1
  64. package/dist/core/prompt/index.d.mts +12 -4
  65. package/dist/core/prompt/index.mjs +348 -6
  66. package/dist/core/resolve/args.d.mts +1 -1
  67. package/dist/core/resolve/args.mjs +105 -1
  68. package/dist/core/resolve/coerce.d.mts +1 -1
  69. package/dist/core/resolve/coerce.mjs +336 -1
  70. package/dist/core/resolve/config.mjs +19 -1
  71. package/dist/core/resolve/contracts.d.mts +9 -4
  72. package/dist/core/resolve/errors.d.mts +0 -1
  73. package/dist/core/resolve/errors.mjs +140 -2
  74. package/dist/core/resolve/flags.d.mts +7 -2
  75. package/dist/core/resolve/flags.mjs +251 -1
  76. package/dist/core/resolve/index.d.mts +2 -2
  77. package/dist/core/resolve/index.mjs +85 -1
  78. package/dist/core/resolve/property.d.mts +6 -2
  79. package/dist/core/resolve/property.mjs +53 -1
  80. package/dist/core/schema/activity.d.mts +31 -11
  81. package/dist/core/schema/arg.d.mts +92 -13
  82. package/dist/core/schema/arg.mjs +463 -1
  83. package/dist/core/schema/command.d.mts +29 -7
  84. package/dist/core/schema/command.mjs +726 -1
  85. package/dist/core/schema/flag.d.mts +577 -21
  86. package/dist/core/schema/flag.mjs +705 -1
  87. package/dist/core/schema/index.d.mts +5 -2
  88. package/dist/core/schema/middleware.d.mts +4 -3
  89. package/dist/core/schema/middleware.mjs +41 -1
  90. package/dist/core/schema/number-constraints.d.mts +96 -0
  91. package/dist/core/schema/number-constraints.mjs +60 -0
  92. package/dist/core/schema/prompt.d.mts +21 -3
  93. package/dist/core/schema/run.d.mts +24 -5
  94. package/dist/core/schema/string-constraints.d.mts +97 -0
  95. package/dist/core/schema/string-constraints.mjs +69 -0
  96. package/dist/core/schema/value-parsers.d.mts +78 -0
  97. package/dist/core/schema/value-parsers.mjs +142 -0
  98. package/dist/core/schema-dsl/runtime.mjs +271 -2
  99. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  100. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  101. package/dist/core/testkit/index.d.mts +9 -36
  102. package/dist/core/testkit/index.mjs +83 -1
  103. package/dist/index.d.mts +12 -6
  104. package/dist/index.mjs +22 -1
  105. package/dist/runtime/adapter.d.mts +38 -2
  106. package/dist/runtime/adapter.mjs +87 -1
  107. package/dist/runtime/auto.d.mts +2 -3
  108. package/dist/runtime/auto.mjs +45 -1
  109. package/dist/runtime/deno.d.mts +24 -5
  110. package/dist/runtime/deno.mjs +262 -2
  111. package/dist/runtime/detect.mjs +45 -1
  112. package/dist/runtime/index.d.mts +3 -4
  113. package/dist/runtime/node.d.mts +8 -2
  114. package/dist/runtime/node.mjs +220 -2
  115. package/dist/runtime/paths.mjs +48 -1
  116. package/dist/runtime.d.mts +4 -4
  117. package/dist/runtime.mjs +6 -1
  118. package/dist/strings.mjs +22 -1
  119. package/dist/testkit.d.mts +1 -0
  120. package/dist/testkit.mjs +5 -1
  121. package/dist/version.d.mts +7 -3
  122. package/dist/version.mjs +7 -1
  123. package/dreamcli.schema.json +36 -7
  124. package/examples/basic.ts +5 -1
  125. package/examples/gh/package.json +2 -7
  126. package/examples/pwsh-demo/package.json +1 -7
  127. package/examples/pwsh-demo/src/main.test.ts +1 -4
  128. package/examples/pwsh-demo/src/main.ts +14 -4
  129. package/examples/transport-launcher.ts +85 -0
  130. package/package.json +43 -49
  131. package/dist/runtime/bun.d.mts +0 -28
  132. package/dist/runtime/bun.mjs +0 -1
  133. package/dist/runtime/support.d.mts +0 -42
  134. package/dist/runtime/support.mjs +0 -1
  135. package/src/core/cli/dispatch.ts +0 -349
  136. package/src/core/cli/help-links.ts +0 -82
  137. package/src/core/cli/index.ts +0 -1413
  138. package/src/core/cli/planner.ts +0 -487
  139. package/src/core/cli/plugin.ts +0 -117
  140. package/src/core/cli/propagate.ts +0 -97
  141. package/src/core/cli/root-help.ts +0 -252
  142. package/src/core/cli/root-surface.ts +0 -74
  143. package/src/core/cli/runtime-preflight.ts +0 -438
  144. package/src/core/completion/index.ts +0 -88
  145. package/src/core/completion/shells/bash.ts +0 -459
  146. package/src/core/completion/shells/fish.ts +0 -259
  147. package/src/core/completion/shells/powershell.ts +0 -439
  148. package/src/core/completion/shells/shared.ts +0 -283
  149. package/src/core/completion/shells/zsh.ts +0 -381
  150. package/src/core/config/index.ts +0 -417
  151. package/src/core/config/package-json.ts +0 -560
  152. package/src/core/errors/index.ts +0 -193
  153. package/src/core/execution/index.ts +0 -268
  154. package/src/core/help/ansi.ts +0 -144
  155. package/src/core/help/index.ts +0 -516
  156. package/src/core/json-schema/index.ts +0 -891
  157. package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
  158. package/src/core/output/activity.ts +0 -575
  159. package/src/core/output/bind.ts +0 -59
  160. package/src/core/output/contracts.ts +0 -194
  161. package/src/core/output/display-value.ts +0 -48
  162. package/src/core/output/index.ts +0 -704
  163. package/src/core/output/renderers.ts +0 -125
  164. package/src/core/output/writer.ts +0 -46
  165. package/src/core/parse/index.ts +0 -681
  166. package/src/core/prompt/index.ts +0 -583
  167. package/src/core/resolve/args.ts +0 -144
  168. package/src/core/resolve/coerce.ts +0 -432
  169. package/src/core/resolve/config.ts +0 -26
  170. package/src/core/resolve/contracts.ts +0 -135
  171. package/src/core/resolve/errors.ts +0 -227
  172. package/src/core/resolve/flags.ts +0 -255
  173. package/src/core/resolve/index.ts +0 -108
  174. package/src/core/resolve/property.ts +0 -99
  175. package/src/core/schema/activity.ts +0 -240
  176. package/src/core/schema/arg.ts +0 -719
  177. package/src/core/schema/command.ts +0 -1498
  178. package/src/core/schema/flag.ts +0 -801
  179. package/src/core/schema/index.ts +0 -91
  180. package/src/core/schema/middleware.ts +0 -171
  181. package/src/core/schema/prompt.ts +0 -156
  182. package/src/core/schema/run.ts +0 -198
  183. package/src/core/schema-dsl/index.ts +0 -109
  184. package/src/core/schema-dsl/parse.ts +0 -262
  185. package/src/core/schema-dsl/runtime.ts +0 -609
  186. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  187. package/src/core/testkit/index.ts +0 -123
  188. package/src/index.ts +0 -179
  189. package/src/runtime/adapter.ts +0 -303
  190. package/src/runtime/auto.ts +0 -110
  191. package/src/runtime/bun.ts +0 -55
  192. package/src/runtime/deno.ts +0 -369
  193. package/src/runtime/detect.ts +0 -105
  194. package/src/runtime/index.ts +0 -21
  195. package/src/runtime/node-builtins.d.ts +0 -27
  196. package/src/runtime/node.ts +0 -300
  197. package/src/runtime/paths.ts +0 -64
  198. package/src/runtime/support.ts +0 -135
  199. package/src/runtime.ts +0 -31
  200. package/src/strings.ts +0 -34
  201. package/src/testkit.ts +0 -25
  202. package/src/version.ts +0 -20
@@ -1,14 +1,13 @@
1
1
  import { Fallback, TableOptions } from "../schema/activity.mjs";
2
-
3
2
  //#region src/core/output/contracts.d.ts
4
3
  /** Ordered output verbosity levels owned by the output policy layer. */
5
- declare const OUTPUT_VERBOSITY_LEVELS: readonly ['normal', 'quiet'];
4
+ declare const OUTPUT_VERBOSITY_LEVELS: readonly ["normal", "quiet"];
6
5
  /** Stable output text streams. */
7
- declare const OUTPUT_STREAMS: readonly ['stdout', 'stderr'];
6
+ declare const OUTPUT_STREAMS: readonly ["stdout", "stderr"];
8
7
  /** Stable activity rendering modes. */
9
- declare const ACTIVITY_RENDER_MODES: readonly ['noop', 'static', 'tty', 'capture'];
8
+ declare const ACTIVITY_RENDER_MODES: readonly ["noop", "static", "tty", "capture"];
10
9
  /** Stable activity cleanup actions. */
11
- declare const ACTIVITY_CLEANUP_KINDS: readonly ['none', 'stop', 'done'];
10
+ declare const ACTIVITY_CLEANUP_KINDS: readonly ["none", "stop", "done"];
12
11
  /** Stable text verbosity labels. */
13
12
  type Verbosity = (typeof OUTPUT_VERBOSITY_LEVELS)[number];
14
13
  /** Stable output stream labels. */
@@ -1 +1,57 @@
1
- function e(e){return{jsonMode:e.jsonMode,isTTY:e.isTTY,verbosity:e.verbosity}}function t(e){return e.jsonMode?`stderr`:`stdout`}function n(e){return e.verbosity!==`quiet`}function r(e,t){switch(t?.format){case`json`:return`json`;case`text`:return`text`;case`auto`:case void 0:return e.jsonMode?`json`:`text`}}function i(e,n){return n?.format===`text`&&`stream`in n&&n.stream!==void 0?n.stream:t(e)}function a(e,t){return e.jsonMode?`noop`:e.isTTY?`tty`:t===`static`?`static`:`noop`}function o(e,t){let n=a(e,t);return{mode:n,stream:`stderr`,cleanup:n===`noop`?`none`:`stop`}}function s(e,t){let n=a(e,t);return{mode:n,stream:`stderr`,cleanup:n===`noop`?`none`:`done`}}export{e as resolveOutputPolicy,s as resolveProgressPolicy,o as resolveSpinnerPolicy,r as resolveTableFormat,i as resolveTableTextStream,t as resolveTextStream,n as shouldEmitInfo};
1
+ //#region src/core/output/contracts.ts
2
+ /** Build the stable output-policy snapshot for one channel instance. */
3
+ function resolveOutputPolicy(options) {
4
+ return {
5
+ jsonMode: options.jsonMode,
6
+ isTTY: options.isTTY,
7
+ verbosity: options.verbosity
8
+ };
9
+ }
10
+ /** Resolve the default text stream for non-JSON structured output. */
11
+ function resolveTextStream(policy) {
12
+ return policy.jsonMode ? "stderr" : "stdout";
13
+ }
14
+ /** Whether `info()` messages should be emitted under the current policy. */
15
+ function shouldEmitInfo(policy) {
16
+ return policy.verbosity !== "quiet";
17
+ }
18
+ /** Resolve the concrete table format under the current policy. */
19
+ function resolveTableFormat(policy, options) {
20
+ switch (options?.format) {
21
+ case "json": return "json";
22
+ case "text": return "text";
23
+ case "auto":
24
+ case void 0: return policy.jsonMode ? "json" : "text";
25
+ }
26
+ }
27
+ /** Resolve the text-table stream after table-format selection. */
28
+ function resolveTableTextStream(policy, options) {
29
+ if (options?.format === "text" && "stream" in options && options.stream !== void 0) return options.stream;
30
+ return resolveTextStream(policy);
31
+ }
32
+ /** Resolve the non-capture activity mode shared by spinner and progress. */
33
+ function resolveActivityRenderMode(policy, fallback) {
34
+ if (policy.jsonMode) return "noop";
35
+ if (policy.isTTY) return "tty";
36
+ return fallback === "static" ? "static" : "noop";
37
+ }
38
+ /** Resolve spinner activity policy including cleanup ownership. */
39
+ function resolveSpinnerPolicy(policy, fallback) {
40
+ const mode = resolveActivityRenderMode(policy, fallback);
41
+ return {
42
+ mode,
43
+ stream: "stderr",
44
+ cleanup: mode === "noop" ? "none" : "stop"
45
+ };
46
+ }
47
+ /** Resolve progress activity policy including cleanup ownership. */
48
+ function resolveProgressPolicy(policy, fallback) {
49
+ const mode = resolveActivityRenderMode(policy, fallback);
50
+ return {
51
+ mode,
52
+ stream: "stderr",
53
+ cleanup: mode === "noop" ? "none" : "done"
54
+ };
55
+ }
56
+ //#endregion
57
+ export { resolveActivityRenderMode, resolveOutputPolicy, resolveProgressPolicy, resolveSpinnerPolicy, resolveTableFormat, resolveTableTextStream, resolveTextStream, shouldEmitInfo };
@@ -1 +1,32 @@
1
- function e(e){if(e==null)return``;if(typeof e==`string`||typeof e==`number`||typeof e==`boolean`||typeof e==`bigint`||typeof e==`symbol`)return String(e);if(e instanceof Date)return Number.isNaN(e.getTime())?`Invalid Date`:e.toISOString();if(typeof e==`function`)return e.name.length>0?`[Function: ${e.name}]`:`[Function]`;try{return JSON.stringify(e)??`[unserializable]`}catch{return`[unserializable]`}}export{e as formatDisplayValue};
1
+ //#region src/core/output/display-value.ts
2
+ /**
3
+ * Shared runtime-value formatting for human-readable output.
4
+ *
5
+ * Used by help text and table rendering so default values and structured cells
6
+ * stringify consistently across the CLI surface.
7
+ *
8
+ * @module dreamcli/core/output/display-value
9
+ * @internal
10
+ */
11
+ /**
12
+ * Format an unknown runtime value for human-readable output.
13
+ *
14
+ * @param value - The value to format (any type).
15
+ * @returns A string representation suitable for table cells and help text.
16
+ */
17
+ function formatDisplayValue(value) {
18
+ if (value === null || value === void 0) return "";
19
+ if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" || typeof value === "symbol") return String(value);
20
+ if (value instanceof Date) {
21
+ if (Number.isNaN(value.getTime())) return "Invalid Date";
22
+ return value.toISOString();
23
+ }
24
+ if (typeof value === "function") return value.name.length > 0 ? `[Function: ${value.name}]` : "[Function]";
25
+ try {
26
+ return JSON.stringify(value) ?? "[unserializable]";
27
+ } catch {
28
+ return "[unserializable]";
29
+ }
30
+ }
31
+ //#endregion
32
+ export { formatDisplayValue };
@@ -3,7 +3,7 @@ import { WriteFn, writeLine } from "./writer.mjs";
3
3
  import { CaptureProgressHandle, CaptureSpinnerHandle, StaticProgressHandle, StaticSpinnerHandle, TTYProgressHandle, TTYSpinnerHandle, noopProgressHandle, noopSpinnerHandle } from "./activity.mjs";
4
4
  import { OutputPolicy, Verbosity } from "./contracts.mjs";
5
5
  import { Out } from "../schema/command.mjs";
6
-
6
+ import { Colors } from "ansispeck";
7
7
  //#region src/core/output/index.d.ts
8
8
  /**
9
9
  * Configuration for creating an output channel.
@@ -45,6 +45,18 @@ interface OutputOptions {
45
45
  * @defaultValue `false`
46
46
  */
47
47
  readonly jsonMode?: boolean;
48
+ /**
49
+ * Explicitly enable or disable ANSI colors on `out.color`.
50
+ *
51
+ * When set, this wins over the auto-gate — use it to force colors in
52
+ * captured test output or when embedding into a host that manages its
53
+ * own color policy.
54
+ *
55
+ * @defaultValue auto — enabled when `isTTY` is `true`, `jsonMode` is
56
+ * `false`, and the environment supports color (`NO_COLOR`,
57
+ * `FORCE_COLOR`, `--no-color`, `--color`, `CI` are respected).
58
+ */
59
+ readonly color?: boolean;
48
60
  }
49
61
  /** Fully resolved output options with no optional fields. */
50
62
  interface ResolvedOutputOptions {
@@ -53,6 +65,7 @@ interface ResolvedOutputOptions {
53
65
  readonly isTTY: boolean;
54
66
  readonly verbosity: Verbosity;
55
67
  readonly jsonMode: boolean;
68
+ readonly color: boolean;
56
69
  }
57
70
  declare function setRequestedExitCode(out: Out, code: number): void;
58
71
  declare function getRequestedExitCode(out: Out): number | undefined;
@@ -84,6 +97,13 @@ declare class OutputChannel implements Out {
84
97
  * precedence).
85
98
  */
86
99
  readonly isTTY: boolean;
100
+ /**
101
+ * Context-aware ANSI color palette.
102
+ *
103
+ * Enabled per the resolved `color` option — identity functions when
104
+ * colors are off, so handlers can style unconditionally.
105
+ */
106
+ readonly color: Colors;
87
107
  constructor(options: ResolvedOutputOptions);
88
108
  /**
89
109
  * Write to stdout (normal output). Always emitted.
@@ -1,2 +1,442 @@
1
- import{formatDisplayValue as e}from"./display-value.mjs";import{bindMethods as t}from"./bind.mjs";import{writeLine as n}from"./writer.mjs";import{CaptureProgressHandle as r,CaptureSpinnerHandle as i}from"./activity.mjs";import{resolveOutputPolicy as a,resolveProgressPolicy as o,resolveSpinnerPolicy as s,resolveTableFormat as c,resolveTableTextStream as l,resolveTextStream as u,shouldEmitInfo as d}from"./contracts.mjs";import{createProgressHandleFromPolicy as f,createSpinnerHandleFromPolicy as p,resolveWriterForStream as m}from"./renderers.mjs";const h=()=>{},g=new WeakMap;function _(e){if(!Number.isInteger(e)||e<0||e>255)throw RangeError(`Exit code must be an integer from 0 to 255`);return e}function v(e,t){g.set(e,_(t))}function y(e){return g.get(e)}function b(e){g.delete(e)}function x(e){return{stdout:e?.stdout??h,stderr:e?.stderr??h,isTTY:e?.isTTY??!1,verbosity:e?.verbosity??`normal`,jsonMode:e?.jsonMode??!1}}var S=class{options;policy;jsonMode;isTTY;constructor(e){this.options=e,this.policy=a(e),this.jsonMode=e.jsonMode,this.isTTY=e.isTTY,t(this)}log(e){n(m(this.options,u(this.policy)),e)}info(e){d(this.policy)&&n(m(this.options,u(this.policy)),e)}warn(e){n(this.options.stderr,e)}error(e){n(this.options.stderr,e)}setExitCode(e){v(this,e)}json(e){n(this.options.stdout,JSON.stringify(e))}table(e,t,r){let{columns:i,options:a}=E(t,r),o=c(this.policy,a),s=i??w(e);if(o===`json`){this.json(D(e,s));return}let l=A(e,s);l.length!==0&&n(O(this.options,this.policy,o,a),l)}activeCleanup;stopActive(){this.activeCleanup!==void 0&&(this.activeCleanup(),this.activeCleanup=void 0)}spinner(e,t){let n=p(s(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=f(o(this.policy,e.fallback??`silent`),e,this.options.stderr);return t.cleanup===void 0?t.handle:(this.stopActive(),this.activeCleanup=t.cleanup,t.handle)}},C=class extends S{activity;constructor(e,t){super(e),this.activity=t}spinner(e,t){return new i(e,this.activity)}progress(e){return new r(e,this.activity)}};function w(e){let t=e[0];return t===void 0?[]:Object.keys(t).map(e=>({key:e}))}function T(e){return Array.isArray(e)}function E(e,t){return t===void 0?T(e)?{columns:e,options:t}:{columns:void 0,options:e}:{columns:T(e)?e:void 0,options:t}}function D(e,t){return e.map(e=>Object.fromEntries(t.map(t=>[t.key,e[t.key]])))}function O(e,t,n,r){return n===`json`?e.stdout:m(e,l(t,r))}function k(t){return e(t)}function A(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=>k(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 j(e){return new S(x(e))}function M(e){let t={stdout:[],stderr:[],activity:[]};return[new C(x({...e,stdout:e=>t.stdout.push(e),stderr:e=>t.stderr.push(e)}),t.activity),t]}export{b as clearRequestedExitCode,M as createCaptureOutput,j as createOutput,y as getRequestedExitCode};
1
+ import { formatDisplayValue } from "./display-value.mjs";
2
+ import { bindMethods } from "./bind.mjs";
3
+ import { writeLine } from "./writer.mjs";
4
+ import { CaptureProgressHandle, CaptureSpinnerHandle } from "./activity.mjs";
5
+ import { resolveOutputPolicy, resolveProgressPolicy, resolveSpinnerPolicy, resolveTableFormat, resolveTableTextStream, resolveTextStream, shouldEmitInfo } from "./contracts.mjs";
6
+ import { createProgressHandleFromPolicy, createSpinnerHandleFromPolicy, resolveWriterForStream } from "./renderers.mjs";
7
+ import { createColors, isColorSupported } from "ansispeck";
8
+ //#region src/core/output/index.ts
9
+ /**
10
+ * Output channel (out object) for command handlers.
11
+ *
12
+ * Provides a structured output abstraction that handlers use instead of
13
+ * raw `console.log`. The channel respects TTY vs piped contexts and
14
+ * supports verbosity levels (quiet mode suppresses `info`).
15
+ *
16
+ * The {@linkcode Out} interface (the contract handlers depend on) lives in
17
+ * `src/core/schema/command.ts`. This module provides the implementation.
18
+ *
19
+ * @module dreamcli/core/output
20
+ */
21
+ /**
22
+ * A noop writer used as fallback when no writer is provided and
23
+ * platform defaults aren't available. Silently discards output.
24
+ */
25
+ const noopWrite = () => {};
26
+ const requestedExitCodes = /* @__PURE__ */ new WeakMap();
27
+ function validateExitCode(code) {
28
+ if (!Number.isInteger(code) || code < 0 || code > 255) throw new RangeError("Exit code must be an integer from 0 to 255");
29
+ return code;
30
+ }
31
+ function setRequestedExitCode(out, code) {
32
+ requestedExitCodes.set(out, validateExitCode(code));
33
+ }
34
+ function getRequestedExitCode(out) {
35
+ return requestedExitCodes.get(out);
36
+ }
37
+ function clearRequestedExitCode(out) {
38
+ requestedExitCodes.delete(out);
39
+ }
40
+ /** Merge user-supplied options with defaults. */
41
+ function resolveOptions(options) {
42
+ const isTTY = options?.isTTY ?? false;
43
+ const jsonMode = options?.jsonMode ?? false;
44
+ return {
45
+ stdout: options?.stdout ?? noopWrite,
46
+ stderr: options?.stderr ?? noopWrite,
47
+ isTTY,
48
+ verbosity: options?.verbosity ?? "normal",
49
+ jsonMode,
50
+ color: options?.color ?? (isTTY && !jsonMode && isColorSupported)
51
+ };
52
+ }
53
+ /**
54
+ * Concrete implementation of the {@linkcode Out} interface.
55
+ *
56
+ * Routes messages to the appropriate writer (stdout vs stderr) and
57
+ * respects the configured verbosity level.
58
+ *
59
+ * Handlers interact with this via the {@linkcode Out} interface — they never see
60
+ * {@linkcode OutputChannel} directly, which keeps the coupling minimal.
61
+ * Prefer {@link createOutput} unless you are extending the output layer.
62
+ *
63
+ * @internal
64
+ */
65
+ var OutputChannel = class {
66
+ /** @internal Resolved configuration. */
67
+ options;
68
+ /** Semantic output policy snapshot shared by routing helpers. */
69
+ policy;
70
+ /** Whether JSON output mode is active. */
71
+ jsonMode;
72
+ /**
73
+ * Whether stdout is connected to a TTY.
74
+ *
75
+ * When `jsonMode` is active, this reflects the underlying TTY status
76
+ * but decorative output should still be suppressed (jsonMode takes
77
+ * precedence).
78
+ */
79
+ isTTY;
80
+ /**
81
+ * Context-aware ANSI color palette.
82
+ *
83
+ * Enabled per the resolved `color` option — identity functions when
84
+ * colors are off, so handlers can style unconditionally.
85
+ */
86
+ color;
87
+ constructor(options) {
88
+ this.options = options;
89
+ this.policy = resolveOutputPolicy(options);
90
+ this.jsonMode = options.jsonMode;
91
+ this.isTTY = options.isTTY;
92
+ this.color = createColors(options.color);
93
+ bindMethods(this);
94
+ }
95
+ /**
96
+ * Write to stdout (normal output). Always emitted.
97
+ *
98
+ * In JSON mode, redirected to stderr so stdout is reserved for
99
+ * structured `json()` output only.
100
+ */
101
+ log(message) {
102
+ writeLine(resolveWriterForStream(this.options, resolveTextStream(this.policy)), message);
103
+ }
104
+ /**
105
+ * Informational message to stdout.
106
+ * Suppressed when verbosity is `'quiet'`.
107
+ *
108
+ * In JSON mode, redirected to stderr.
109
+ */
110
+ info(message) {
111
+ if (!shouldEmitInfo(this.policy)) return;
112
+ writeLine(resolveWriterForStream(this.options, resolveTextStream(this.policy)), message);
113
+ }
114
+ /** Warning to stderr. Always emitted. */
115
+ warn(message) {
116
+ writeLine(this.options.stderr, message);
117
+ }
118
+ /** Error to stderr. Always emitted. */
119
+ error(message) {
120
+ writeLine(this.options.stderr, message);
121
+ }
122
+ /** Request a successful-process exit code without writing error output. */
123
+ setExitCode(code) {
124
+ setRequestedExitCode(this, code);
125
+ }
126
+ /**
127
+ * Emit a structured JSON value to stdout.
128
+ *
129
+ * Serialises `value` with `JSON.stringify` and writes to stdout
130
+ * regardless of JSON mode — `json()` always targets stdout.
131
+ */
132
+ json(value) {
133
+ writeLine(this.options.stdout, JSON.stringify(value));
134
+ }
135
+ table(rows, columnsOrOptions, options) {
136
+ const { columns, options: tableOptions } = resolveTableArgs(columnsOrOptions, options);
137
+ const format = resolveTableFormat(this.policy, tableOptions);
138
+ const resolved = columns ?? inferColumns(rows);
139
+ if (format === "json") {
140
+ this.json(projectTableRows(rows, resolved));
141
+ return;
142
+ }
143
+ const text = formatTable(rows, resolved);
144
+ if (text.length === 0) return;
145
+ writeLine(resolveTextTableWriter(this.options, this.policy, format, tableOptions), text);
146
+ }
147
+ /**
148
+ * Cleanup callback for the currently active spinner/progress handle.
149
+ *
150
+ * Set to `undefined` when no handle is active. The callback calls the
151
+ * appropriate terminal method (`.stop()` for spinners, `.done()` for
152
+ * progress) on the previous handle.
153
+ *
154
+ * @internal
155
+ */
156
+ activeCleanup;
157
+ /**
158
+ * Stop the currently active spinner/progress handle (if any).
159
+ *
160
+ * Called internally before creating a new handle to prevent overlap,
161
+ * and externally after handler execution to clean up leaked timers.
162
+ * Idempotent (safe to call when no handle is active).
163
+ */
164
+ stopActive() {
165
+ if (this.activeCleanup !== void 0) {
166
+ this.activeCleanup();
167
+ this.activeCleanup = void 0;
168
+ }
169
+ }
170
+ /**
171
+ * Create a spinner handle.
172
+ *
173
+ * Mode dispatch:
174
+ * - `jsonMode` → noop (structured output only, spinners suppressed)
175
+ * - `isTTY` → animated TTY spinner (braille frames, ANSI overwrite)
176
+ * - `!isTTY && fallback: 'static'` → plain text at lifecycle boundaries
177
+ * - `!isTTY && fallback: 'silent'` (default) → noop
178
+ *
179
+ * All activity output (transient frames, terminal messages) routes to
180
+ * stderr so stdout remains clean for structured data and piping.
181
+ *
182
+ * If another spinner or progress handle is active, it is implicitly
183
+ * stopped before the new one starts.
184
+ *
185
+ * @virtual
186
+ */
187
+ spinner(text, options) {
188
+ const rendered = createSpinnerHandleFromPolicy(resolveSpinnerPolicy(this.policy, options?.fallback ?? "silent"), text, this.options.stderr);
189
+ if (rendered.cleanup === void 0) return rendered.handle;
190
+ this.stopActive();
191
+ this.activeCleanup = rendered.cleanup;
192
+ return rendered.handle;
193
+ }
194
+ /**
195
+ * Create a progress handle.
196
+ *
197
+ * Mode dispatch:
198
+ * - `jsonMode` → noop (structured output only, progress suppressed)
199
+ * - `isTTY` → animated TTY progress bar (determinate or indeterminate)
200
+ * - `!isTTY && fallback: 'static'` → plain text at lifecycle boundaries
201
+ * - `!isTTY && fallback: 'silent'` (default) → noop
202
+ *
203
+ * All activity output (transient frames, terminal messages) routes to
204
+ * stderr so stdout remains clean for structured data and piping.
205
+ *
206
+ * If another spinner or progress handle is active, it is implicitly
207
+ * stopped before the new one starts.
208
+ *
209
+ * @virtual
210
+ */
211
+ progress(opts) {
212
+ const rendered = createProgressHandleFromPolicy(resolveProgressPolicy(this.policy, opts.fallback ?? "silent"), opts, this.options.stderr);
213
+ if (rendered.cleanup === void 0) return rendered.handle;
214
+ this.stopActive();
215
+ this.activeCleanup = rendered.cleanup;
216
+ return rendered.handle;
217
+ }
218
+ };
219
+ /**
220
+ * Output channel variant that returns capture handles for spinner/progress.
221
+ *
222
+ * Extends {@linkcode OutputChannel} to override `spinner()` and `progress()`, routing
223
+ * activity events into a shared {@linkcode ActivityEvent | ActivityEvent[]} for testkit assertion.
224
+ * Text output (log/info/warn/error) is handled by the parent class.
225
+ *
226
+ * @internal
227
+ */
228
+ var CaptureOutputChannel = class extends OutputChannel {
229
+ activity;
230
+ constructor(options, activity) {
231
+ super(options);
232
+ this.activity = activity;
233
+ }
234
+ /**
235
+ * Return a {@link CaptureSpinnerHandle} that records events into the activity log.
236
+ * @override
237
+ */
238
+ spinner(text, _options) {
239
+ return new CaptureSpinnerHandle(text, this.activity);
240
+ }
241
+ /**
242
+ * Return a {@link CaptureProgressHandle} that records events into the activity log.
243
+ * @override
244
+ */
245
+ progress(opts) {
246
+ return new CaptureProgressHandle(opts, this.activity);
247
+ }
248
+ };
249
+ /**
250
+ * Infer column descriptors from the keys of the first row.
251
+ *
252
+ * When no explicit columns are provided, all keys from the first row
253
+ * become columns in insertion order. This is a convenience — callers
254
+ * who need stable ordering should provide explicit columns.
255
+ *
256
+ * @param rows - Data rows to derive columns from.
257
+ * @returns Column descriptors, one per key of the first row (empty if `rows` is empty).
258
+ */
259
+ function inferColumns(rows) {
260
+ const first = rows[0];
261
+ if (first === void 0) return [];
262
+ return Object.keys(first).map((key) => ({ key }));
263
+ }
264
+ /**
265
+ * Type guard: is `value` a {@link TableColumn} array (not {@link TableOptions})?
266
+ *
267
+ * @param value - The ambiguous argument to discriminate.
268
+ * @returns `true` when `value` is a column descriptor array.
269
+ */
270
+ function isTableColumns(value) {
271
+ return Array.isArray(value);
272
+ }
273
+ /**
274
+ * Disambiguate the overloaded `table()` arguments.
275
+ *
276
+ * @param columnsOrOptions - Either column descriptors or table options (from the 2-arg overload).
277
+ * @param options - Explicit table options (from the 3-arg overload).
278
+ * @returns Separated `columns` and `options`, each possibly `undefined`.
279
+ */
280
+ function resolveTableArgs(columnsOrOptions, options) {
281
+ if (options !== void 0) return {
282
+ columns: isTableColumns(columnsOrOptions) ? columnsOrOptions : void 0,
283
+ options
284
+ };
285
+ if (isTableColumns(columnsOrOptions)) return {
286
+ columns: columnsOrOptions,
287
+ options
288
+ };
289
+ return {
290
+ columns: void 0,
291
+ options: columnsOrOptions
292
+ };
293
+ }
294
+ /**
295
+ * Keep only the keys listed in `columns`, preserving column order.
296
+ *
297
+ * @param rows - Source data rows.
298
+ * @param columns - Column descriptors controlling which keys to retain.
299
+ * @returns Projected rows containing only the specified keys.
300
+ */
301
+ function projectTableRows(rows, columns) {
302
+ return rows.map((row) => Object.fromEntries(columns.map((c) => [c.key, row[c.key]])));
303
+ }
304
+ /**
305
+ * Determine the concrete table format (`'text'` or `'json'`).
306
+ *
307
+ * Resolves `'auto'` / `undefined` by falling back to the channel's `jsonMode`.
308
+ *
309
+ * @param jsonMode - Whether the channel is in JSON output mode.
310
+ * @param options - Per-call table options (may specify an explicit format).
311
+ * @returns `'text'` or `'json'`.
312
+ */
313
+ /**
314
+ * Pick the {@link WriteFn} for a text-mode table.
315
+ *
316
+ * Respects `tableOptions.stream` when present; otherwise falls back to
317
+ * the channel's default policy-owned text stream.
318
+ *
319
+ * @param options - Resolved channel options.
320
+ * @param format - Resolved table format.
321
+ * @param tableOptions - Per-call table options (may specify a stream override).
322
+ * @returns The writer to use.
323
+ */
324
+ function resolveTextTableWriter(options, policy, format, tableOptions) {
325
+ if (format === "json") return options.stdout;
326
+ return resolveWriterForStream(options, resolveTableTextStream(policy, tableOptions));
327
+ }
328
+ /**
329
+ * Convert a cell value to a display string.
330
+ *
331
+ * - `null` / `undefined` → `''`
332
+ * - Primitives → `String(value)`
333
+ * - Objects / arrays → JSON
334
+ *
335
+ * @param value - The raw cell value.
336
+ * @returns Display string for the cell.
337
+ */
338
+ function cellToString(value) {
339
+ return formatDisplayValue(value);
340
+ }
341
+ /**
342
+ * Format rows as an aligned text table.
343
+ *
344
+ * Returns the full table string (without trailing newline — the caller
345
+ * adds that via `writeLine`). Returns `''` when rows is empty.
346
+ *
347
+ * Column widths are computed as the max of header and all cell values.
348
+ * Cells are left-aligned, padded with spaces. Columns are separated by
349
+ * two spaces.
350
+ *
351
+ * @param rows - Data rows to render.
352
+ * @param columns - Column descriptors controlling key, header, and order.
353
+ * @returns The formatted table string, or `''` when there is nothing to render.
354
+ */
355
+ function formatTable(rows, columns) {
356
+ if (rows.length === 0 || columns.length === 0) return "";
357
+ const SEPARATOR = " ";
358
+ const headers = columns.map((c) => c.header ?? c.key);
359
+ const cellGrid = rows.map((row) => columns.map((c) => cellToString(row[c.key])));
360
+ const widths = headers.map((h, i) => {
361
+ let max = h.length;
362
+ for (const row of cellGrid) {
363
+ const cell = row[i];
364
+ if (cell !== void 0 && cell.length > max) max = cell.length;
365
+ }
366
+ return max;
367
+ });
368
+ return [
369
+ headers.map((h, i) => h.padEnd(widths[i] ?? 0)).join(SEPARATOR),
370
+ widths.map((w) => "-".repeat(w)).join(SEPARATOR),
371
+ ...cellGrid.map((row) => row.map((cell, i) => cell.padEnd(widths[i] ?? 0)).join(SEPARATOR))
372
+ ].join("\n");
373
+ }
374
+ /**
375
+ * Create an output channel.
376
+ *
377
+ * Low-level factory: action handlers already receive `out` automatically from
378
+ * `cli()`, `.execute()`, and `runCommand()`. Call `createOutput()` when you
379
+ * are embedding DreamCLI primitives into a custom runtime or need a standalone
380
+ * output implementation outside the normal command pipeline.
381
+ *
382
+ * @param options - Optional configuration. When omitted, output is
383
+ * discarded (useful for silent test runs). Pass `stdout`/`stderr`
384
+ * writers to direct output somewhere useful.
385
+ *
386
+ * @returns An {@link Out} instance backed by an {@link OutputChannel}.
387
+ *
388
+ * @example
389
+ * ```ts
390
+ * // Production (wired by the runtime adapter)
391
+ * const out = createOutput({
392
+ * stdout: (s) => process.stdout.write(s),
393
+ * stderr: (s) => process.stderr.write(s),
394
+ * isTTY: process.stdout.isTTY === true,
395
+ * });
396
+ *
397
+ * // Test (capture output)
398
+ * const lines: string[] = [];
399
+ * const out = createOutput({
400
+ * stdout: (s) => lines.push(s),
401
+ * stderr: (s) => lines.push(s),
402
+ * });
403
+ * ```
404
+ */
405
+ function createOutput(options) {
406
+ return new OutputChannel(resolveOptions(options));
407
+ }
408
+ /**
409
+ * Create an output channel that captures all output into arrays.
410
+ *
411
+ * Useful in tests to assert on what a handler wrote without touching
412
+ * real I/O.
413
+ *
414
+ * @param options - Optional {@link OutputOptions} (minus `stdout`/`stderr`,
415
+ * which are wired to the capture buffers automatically).
416
+ *
417
+ * @returns A tuple of `[out, captured]` — the {@link Out} channel and the
418
+ * {@link CapturedOutput} buffers.
419
+ *
420
+ * @example
421
+ * ```ts
422
+ * const [out, captured] = createCaptureOutput();
423
+ * out.log('hello');
424
+ * out.warn('danger');
425
+ * expect(captured.stdout).toEqual(['hello\n']);
426
+ * expect(captured.stderr).toEqual(['danger\n']);
427
+ * ```
428
+ */
429
+ function createCaptureOutput(options) {
430
+ const captured = {
431
+ stdout: [],
432
+ stderr: [],
433
+ activity: []
434
+ };
435
+ return [new CaptureOutputChannel(resolveOptions({
436
+ ...options,
437
+ stdout: (s) => captured.stdout.push(s),
438
+ stderr: (s) => captured.stderr.push(s)
439
+ }), captured.activity), captured];
440
+ }
441
+ //#endregion
442
+ export { CaptureOutputChannel, CaptureProgressHandle, CaptureSpinnerHandle, OutputChannel, clearRequestedExitCode, createCaptureOutput, createOutput, getRequestedExitCode, setRequestedExitCode, writeLine };
@@ -1,7 +1,6 @@
1
1
  import { ProgressHandle, ProgressOptions, SpinnerHandle } from "../schema/activity.mjs";
2
2
  import { WriteFn } from "./writer.mjs";
3
3
  import { ActivityPolicy, OutputStream } from "./contracts.mjs";
4
-
5
4
  //#region src/core/output/renderers.d.ts
6
5
  /**
7
6
  * Paired write functions for the two standard output streams.
@@ -1 +1,46 @@
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};
1
+ import { StaticProgressHandle, StaticSpinnerHandle, TTYProgressHandle, TTYSpinnerHandle, noopProgressHandle, noopSpinnerHandle } from "./activity.mjs";
2
+ //#region src/core/output/renderers.ts
3
+ /** Select the concrete {@linkcode WriteFn} for a given stream label. @internal */
4
+ function resolveWriterForStream(writers, stream) {
5
+ return stream === "stderr" ? writers.stderr : writers.stdout;
6
+ }
7
+ /** Create a spinner handle matching the resolved {@linkcode ActivityPolicy} mode. @internal */
8
+ function createSpinnerHandleFromPolicy(policy, text, stderr) {
9
+ if (policy.mode === "noop") return {
10
+ handle: noopSpinnerHandle,
11
+ cleanup: void 0
12
+ };
13
+ if (policy.mode === "tty") {
14
+ const handle = new TTYSpinnerHandle(text, stderr);
15
+ return {
16
+ handle,
17
+ cleanup: () => handle.stop()
18
+ };
19
+ }
20
+ const handle = new StaticSpinnerHandle(text, stderr);
21
+ return {
22
+ handle,
23
+ cleanup: () => handle.stop()
24
+ };
25
+ }
26
+ /** Create a progress handle matching the resolved {@linkcode ActivityPolicy} mode. @internal */
27
+ function createProgressHandleFromPolicy(policy, options, stderr) {
28
+ if (policy.mode === "noop") return {
29
+ handle: noopProgressHandle,
30
+ cleanup: void 0
31
+ };
32
+ if (policy.mode === "tty") {
33
+ const handle = new TTYProgressHandle(options, stderr);
34
+ return {
35
+ handle,
36
+ cleanup: () => handle.done()
37
+ };
38
+ }
39
+ const handle = new StaticProgressHandle(options.label, stderr);
40
+ return {
41
+ handle,
42
+ cleanup: () => handle.done()
43
+ };
44
+ }
45
+ //#endregion
46
+ export { createProgressHandleFromPolicy, createSpinnerHandleFromPolicy, resolveWriterForStream };
@@ -1 +1,12 @@
1
- function e(e,t){e(`${t}\n`)}export{e as writeLine};
1
+ //#region src/core/output/writer.ts
2
+ /**
3
+ * Write a message followed by a newline.
4
+ *
5
+ * @param write - The underlying write function.
6
+ * @param message - The text to write.
7
+ */
8
+ function writeLine(write, message) {
9
+ write(`${message}\n`);
10
+ }
11
+ //#endregion
12
+ export { writeLine };