@kjanat/dreamcli 4.0.0-rc.3 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (212) hide show
  1. package/README.md +5 -7
  2. package/dist/{runtime/adapter.d.mts → adapter-YM5QGi3M.d.mts} +4 -4
  3. package/dist/completion-CUMeOnAz.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-CrlScpYX.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-DvXUolc_.mjs +17 -0
  10. package/dist/{core/json-schema/index.d.mts → index-3l8uj16E.d.mts} +43 -34
  11. package/dist/{core/cli/index.d.mts → index-BAj2y70U.d.mts} +116 -57
  12. package/dist/index-BziI2aKc.d.mts +5440 -0
  13. package/dist/index-Cap0MA2V.d.mts +277 -0
  14. package/dist/index-Cp9kt2t-.d.mts +370 -0
  15. package/dist/index-DWsnGZlx.d.mts +831 -0
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-DRlrz_IV.mjs +52 -0
  19. package/dist/json-schema.d.mts +2 -0
  20. package/dist/json-schema.mjs +1 -0
  21. package/dist/package-json-BgE9YjjQ.mjs +3 -0
  22. package/dist/prompt.d.mts +48 -0
  23. package/dist/prompt.mjs +1 -0
  24. package/dist/rolldown-runtime-G4Kt5YOX.mjs +1 -0
  25. package/dist/runtime.d.mts +2 -6
  26. package/dist/runtime.mjs +1 -6
  27. package/dist/terminal-C8KTXjv5.mjs +6 -0
  28. package/dist/test-prompter-v__jT2yG.mjs +1 -0
  29. package/dist/testkit.d.mts +54 -6
  30. package/dist/testkit.mjs +1 -5
  31. package/dist/version.mjs +1 -7
  32. package/dreamcli.schema.json +697 -538
  33. package/package.json +29 -7
  34. package/skills/cli-creation/SKILL.md +16 -11
  35. package/CHANGELOG.md +0 -1116
  36. package/dist/core/cli/builtins.d.mts +0 -117
  37. package/dist/core/cli/builtins.mjs +0 -135
  38. package/dist/core/cli/compiled.d.mts +0 -66
  39. package/dist/core/cli/compiled.mjs +0 -76
  40. package/dist/core/cli/dispatch.d.mts +0 -115
  41. package/dist/core/cli/dispatch.mjs +0 -205
  42. package/dist/core/cli/help-links.d.mts +0 -27
  43. package/dist/core/cli/help-links.mjs +0 -41
  44. package/dist/core/cli/index.mjs +0 -1271
  45. package/dist/core/cli/planner.d.mts +0 -174
  46. package/dist/core/cli/planner.mjs +0 -323
  47. package/dist/core/cli/plugin.d.mts +0 -94
  48. package/dist/core/cli/plugin.mjs +0 -41
  49. package/dist/core/cli/propagate.d.mts +0 -39
  50. package/dist/core/cli/propagate.mjs +0 -57
  51. package/dist/core/cli/reserved-flags.d.mts +0 -19
  52. package/dist/core/cli/reserved-flags.mjs +0 -158
  53. package/dist/core/cli/root-help.d.mts +0 -53
  54. package/dist/core/cli/root-help.mjs +0 -221
  55. package/dist/core/cli/root-output-flags.d.mts +0 -74
  56. package/dist/core/cli/root-output-flags.mjs +0 -169
  57. package/dist/core/cli/root-surface.d.mts +0 -64
  58. package/dist/core/cli/root-surface.mjs +0 -28
  59. package/dist/core/cli/runtime-preflight.d.mts +0 -213
  60. package/dist/core/cli/runtime-preflight.mjs +0 -221
  61. package/dist/core/completion/index.d.mts +0 -76
  62. package/dist/core/completion/index.mjs +0 -90
  63. package/dist/core/completion/shells/bash.d.mts +0 -23
  64. package/dist/core/completion/shells/bash.mjs +0 -312
  65. package/dist/core/completion/shells/fish.d.mts +0 -19
  66. package/dist/core/completion/shells/fish.mjs +0 -164
  67. package/dist/core/completion/shells/powershell.d.mts +0 -13
  68. package/dist/core/completion/shells/powershell.mjs +0 -360
  69. package/dist/core/completion/shells/shared.d.mts +0 -164
  70. package/dist/core/completion/shells/shared.mjs +0 -147
  71. package/dist/core/completion/shells/zsh.d.mts +0 -23
  72. package/dist/core/completion/shells/zsh.mjs +0 -256
  73. package/dist/core/config/index.d.mts +0 -191
  74. package/dist/core/config/index.mjs +0 -285
  75. package/dist/core/config/package-json.d.mts +0 -179
  76. package/dist/core/config/package-json.mjs +0 -353
  77. package/dist/core/errors/index.d.mts +0 -125
  78. package/dist/core/errors/index.mjs +0 -87
  79. package/dist/core/execution/index.d.mts +0 -61
  80. package/dist/core/execution/index.mjs +0 -220
  81. package/dist/core/help/ansi.d.mts +0 -84
  82. package/dist/core/help/ansi.mjs +0 -121
  83. package/dist/core/help/index.d.mts +0 -149
  84. package/dist/core/help/index.mjs +0 -418
  85. package/dist/core/help/theme.d.mts +0 -86
  86. package/dist/core/help/theme.mjs +0 -69
  87. package/dist/core/json-schema/index.mjs +0 -1008
  88. package/dist/core/json-schema/meta-descriptions.generated.d.mts +0 -274
  89. package/dist/core/json-schema/meta-descriptions.generated.mjs +0 -136
  90. package/dist/core/output/activity.d.mts +0 -193
  91. package/dist/core/output/activity.mjs +0 -452
  92. package/dist/core/output/bind.d.mts +0 -37
  93. package/dist/core/output/bind.mjs +0 -56
  94. package/dist/core/output/contracts.d.mts +0 -82
  95. package/dist/core/output/contracts.mjs +0 -57
  96. package/dist/core/output/display-value.d.mts +0 -19
  97. package/dist/core/output/display-value.mjs +0 -32
  98. package/dist/core/output/index.d.mts +0 -344
  99. package/dist/core/output/index.mjs +0 -514
  100. package/dist/core/output/renderers.d.mts +0 -45
  101. package/dist/core/output/renderers.mjs +0 -46
  102. package/dist/core/output/writer.d.mts +0 -39
  103. package/dist/core/output/writer.mjs +0 -12
  104. package/dist/core/parse/index.d.mts +0 -178
  105. package/dist/core/parse/index.mjs +0 -850
  106. package/dist/core/parse/occurrences.d.mts +0 -90
  107. package/dist/core/parse/occurrences.mjs +0 -114
  108. package/dist/core/prompt/index.d.mts +0 -213
  109. package/dist/core/prompt/index.mjs +0 -348
  110. package/dist/core/read-flags/index.d.mts +0 -150
  111. package/dist/core/read-flags/index.mjs +0 -217
  112. package/dist/core/resolve/args.d.mts +0 -39
  113. package/dist/core/resolve/args.mjs +0 -182
  114. package/dist/core/resolve/coerce.d.mts +0 -79
  115. package/dist/core/resolve/coerce.mjs +0 -900
  116. package/dist/core/resolve/config.d.mts +0 -10
  117. package/dist/core/resolve/config.mjs +0 -19
  118. package/dist/core/resolve/contracts.d.mts +0 -146
  119. package/dist/core/resolve/errors.d.mts +0 -10
  120. package/dist/core/resolve/errors.mjs +0 -148
  121. package/dist/core/resolve/flags.d.mts +0 -74
  122. package/dist/core/resolve/flags.mjs +0 -246
  123. package/dist/core/resolve/index.d.mts +0 -44
  124. package/dist/core/resolve/index.mjs +0 -123
  125. package/dist/core/resolve/path-checks.d.mts +0 -48
  126. package/dist/core/resolve/path-checks.mjs +0 -102
  127. package/dist/core/resolve/redaction.d.mts +0 -13
  128. package/dist/core/resolve/redaction.mjs +0 -14
  129. package/dist/core/resolve/stages.d.mts +0 -86
  130. package/dist/core/resolve/stages.mjs +0 -170
  131. package/dist/core/resolve/standard.d.mts +0 -26
  132. package/dist/core/resolve/standard.mjs +0 -212
  133. package/dist/core/schema/activity.d.mts +0 -189
  134. package/dist/core/schema/arg.d.mts +0 -1461
  135. package/dist/core/schema/arg.mjs +0 -1139
  136. package/dist/core/schema/brand.d.mts +0 -17
  137. package/dist/core/schema/cardinality.d.mts +0 -302
  138. package/dist/core/schema/cardinality.mjs +0 -514
  139. package/dist/core/schema/command.d.mts +0 -1132
  140. package/dist/core/schema/command.mjs +0 -999
  141. package/dist/core/schema/flag.d.mts +0 -1495
  142. package/dist/core/schema/flag.mjs +0 -1207
  143. package/dist/core/schema/index.d.mts +0 -15
  144. package/dist/core/schema/index.mjs +0 -10
  145. package/dist/core/schema/middleware.d.mts +0 -129
  146. package/dist/core/schema/middleware.mjs +0 -41
  147. package/dist/core/schema/number-constraints.d.mts +0 -96
  148. package/dist/core/schema/number-constraints.mjs +0 -60
  149. package/dist/core/schema/prompt.d.mts +0 -135
  150. package/dist/core/schema/provenance.d.mts +0 -99
  151. package/dist/core/schema/provenance.mjs +0 -28
  152. package/dist/core/schema/run.d.mts +0 -211
  153. package/dist/core/schema/source.d.mts +0 -180
  154. package/dist/core/schema/source.mjs +0 -206
  155. package/dist/core/schema/standard.d.mts +0 -100
  156. package/dist/core/schema/standard.mjs +0 -15
  157. package/dist/core/schema/stdin.d.mts +0 -97
  158. package/dist/core/schema/stdin.mjs +0 -91
  159. package/dist/core/schema/string-constraints.d.mts +0 -108
  160. package/dist/core/schema/string-constraints.mjs +0 -86
  161. package/dist/core/schema/value-parsers.d.mts +0 -150
  162. package/dist/core/schema/value-parsers.mjs +0 -160
  163. package/dist/core/schema/value.d.mts +0 -243
  164. package/dist/core/schema/value.mjs +0 -573
  165. package/dist/core/testkit/index.d.mts +0 -63
  166. package/dist/core/testkit/index.mjs +0 -102
  167. package/dist/runtime/adapter.mjs +0 -92
  168. package/dist/runtime/auto.d.mts +0 -25
  169. package/dist/runtime/auto.mjs +0 -45
  170. package/dist/runtime/deno.d.mts +0 -99
  171. package/dist/runtime/deno.mjs +0 -265
  172. package/dist/runtime/detect.d.mts +0 -86
  173. package/dist/runtime/detect.mjs +0 -45
  174. package/dist/runtime/index.d.mts +0 -6
  175. package/dist/runtime/node.d.mts +0 -71
  176. package/dist/runtime/node.mjs +0 -228
  177. package/dist/runtime/paths.d.mts +0 -31
  178. package/dist/runtime/paths.mjs +0 -48
  179. package/dist/strings.d.mts +0 -27
  180. package/dist/strings.mjs +0 -22
  181. package/examples/basic.ts +0 -37
  182. package/examples/flag-types.ts +0 -79
  183. package/examples/gh/package.json +0 -45
  184. package/examples/gh/src/commands/auth.ts +0 -66
  185. package/examples/gh/src/commands/issue.ts +0 -120
  186. package/examples/gh/src/commands/pr.ts +0 -125
  187. package/examples/gh/src/data/issues.yaml +0 -5
  188. package/examples/gh/src/data/issues.yaml.d.ts +0 -17
  189. package/examples/gh/src/data/pull-requests.yaml +0 -7
  190. package/examples/gh/src/data/pull-requests.yaml.d.ts +0 -18
  191. package/examples/gh/src/docs.ts +0 -11
  192. package/examples/gh/src/lib/auth.ts +0 -37
  193. package/examples/gh/src/lib/utils.ts +0 -17
  194. package/examples/gh/src/main.test.ts +0 -307
  195. package/examples/gh/src/main.ts +0 -46
  196. package/examples/help-config.ts +0 -43
  197. package/examples/interactive.ts +0 -67
  198. package/examples/json-mode.ts +0 -95
  199. package/examples/middleware.ts +0 -71
  200. package/examples/multi-command.ts +0 -66
  201. package/examples/output-extras.ts +0 -46
  202. package/examples/parser-control.ts +0 -40
  203. package/examples/pwsh-demo/README.md +0 -40
  204. package/examples/pwsh-demo/package.json +0 -41
  205. package/examples/pwsh-demo/pwsh-demo.cmd +0 -3
  206. package/examples/pwsh-demo/smoke-powershell.ps1 +0 -218
  207. package/examples/pwsh-demo/src/main.test.ts +0 -45
  208. package/examples/pwsh-demo/src/main.ts +0 -140
  209. package/examples/spinner-progress.ts +0 -49
  210. package/examples/standard-schema.ts +0 -45
  211. package/examples/testing.ts +0 -147
  212. package/examples/transport-launcher.ts +0 -85
@@ -1,212 +0,0 @@
1
- import { ValidationError } from "../errors/index.mjs";
2
- import { argAggregateStandard, argValueSchema, flagAggregateStandard, flagValueSchema } from "../schema/value.mjs";
3
- import { argCardinality, flagCardinality, isCollection } from "../schema/cardinality.mjs";
4
- import { echoesValue } from "./redaction.mjs";
5
- //#region src/core/resolve/standard.ts
6
- /**
7
- * Standard Schema v1 validation pass.
8
- *
9
- * Runs after CLI/env/config/prompt/default resolution so a validator attached
10
- * via `flag.custom()` / `arg.custom()` sees the final value regardless of its
11
- * source. `~standard.validate` may be sync or async; both are awaited here.
12
- * Issues become `CONSTRAINT_VIOLATED` validation errors; a successful result
13
- * replaces the value with the validator's (possibly transformed) output.
14
- *
15
- * @module dreamcli/core/resolve/standard
16
- */
17
- /** Render an issue path (e.g. `['a', 0]` → `a.0`), or `undefined` when empty. */
18
- function formatIssuePath(path) {
19
- if (path === void 0 || path.length === 0) return;
20
- return path.map((segment) => {
21
- const key = typeof segment === "object" ? segment.key : segment;
22
- return typeof key === "symbol" ? key.toString() : String(key);
23
- }).join(".");
24
- }
25
- /** Build a `CONSTRAINT_VIOLATED` message from a validator's issues. */
26
- function issuesMessage(label, issues) {
27
- return `${label} failed validation: ${issues.map((issue) => {
28
- const path = formatIssuePath(issue.path);
29
- return path === void 0 ? issue.message : `${path}: ${issue.message}`;
30
- }).join("; ")}`;
31
- }
32
- /**
33
- * Read one input's provenance by name.
34
- *
35
- * @param record - Provenance of one surface, keyed by input name.
36
- * @param name - Flag or arg name to read.
37
- * @returns The record, or `undefined` when that input resolved nothing.
38
- */
39
- function provenanceOf(record, name) {
40
- return Object.hasOwn(record, name) ? record[name] : void 0;
41
- }
42
- /** Await a validator against a single value, mapping failure to a typed error. */
43
- async function validateValue(label, value, validator, echo) {
44
- let result;
45
- try {
46
- result = await validator["~standard"].validate(value);
47
- } catch (cause) {
48
- const message = cause instanceof Error ? cause.message : String(cause);
49
- return {
50
- ok: false,
51
- error: new ValidationError(`${label} validator threw: ${message}`, {
52
- code: "CONSTRAINT_VIOLATED",
53
- details: {
54
- value,
55
- cause: message
56
- },
57
- suggest: `Fix the validator for ${label}, or provide a value it can process`
58
- })
59
- };
60
- }
61
- if (result.issues !== void 0) return {
62
- ok: false,
63
- error: new ValidationError(issuesMessage(label, result.issues), {
64
- code: "CONSTRAINT_VIOLATED",
65
- details: {
66
- ...echo ? { value } : {},
67
- issues: result.issues.map((issue) => issue.message)
68
- },
69
- suggest: `Provide a value for ${label} that satisfies its validator`
70
- })
71
- };
72
- return {
73
- ok: true,
74
- value: result.value
75
- };
76
- }
77
- /**
78
- * Read one resolved value by name.
79
- *
80
- * `resolve()` runs this pass even after a resolver threw, so the record may be
81
- * missing a declared name, and a name such as `toString` reads back the
82
- * inherited `Object.prototype` method from a bare lookup.
83
- *
84
- * @param values - Resolved flag or arg record.
85
- * @param name - Flag or arg name to read.
86
- * @returns The resolved value, or `undefined` when the record does not carry it.
87
- */
88
- function resolvedValue(values, name) {
89
- return Object.hasOwn(values, name) ? values[name] : void 0;
90
- }
91
- /**
92
- * Validate resolved flag and arg values against any attached Standard Schema
93
- * validators. Values without a validator, or resolved to `undefined`, pass
94
- * through untouched.
95
- *
96
- * @param schema - The command schema carrying per-flag/arg validators.
97
- * @param flags - Resolved flag values, keyed by flag name.
98
- * @param args - Resolved arg values, keyed by arg name.
99
- * @param provenance - Which stage produced each value, read for redaction.
100
- * @returns The (possibly transformed) values and any constraint violations.
101
- * @internal
102
- */
103
- async function applyStandardValidators(schema, flags, args, provenance) {
104
- const errors = [];
105
- const nextFlags = { ...flags };
106
- for (const [name, flagSchema] of Object.entries(schema.flags)) {
107
- const value = resolvedValue(flags, name);
108
- if (value === void 0) continue;
109
- const validated = await validateInput(`--${name}`, value, isCollection(flagCardinality(flagSchema)), flagValueSchema(flagSchema).standard, flagAggregateStandard(flagSchema), errors, echoesValue(provenanceOf(provenance.flags, name)));
110
- if (validated.changed) nextFlags[name] = validated.value;
111
- }
112
- const nextArgs = { ...args };
113
- for (const entry of schema.args) {
114
- const value = resolvedValue(args, entry.name);
115
- if (value === void 0) continue;
116
- const validated = await validateInput(`<${entry.name}>`, value, isCollection(argCardinality(entry.schema)), argValueSchema(entry.schema).standard, argAggregateStandard(entry.schema), errors, echoesValue(provenanceOf(provenance.args, entry.name)));
117
- if (validated.changed) nextArgs[entry.name] = validated.value;
118
- }
119
- return {
120
- flags: nextFlags,
121
- args: nextArgs,
122
- errors
123
- };
124
- }
125
- /**
126
- * Run the element pass and then the aggregate pass over one resolved value.
127
- *
128
- * A collection validates every element before the completed array or record
129
- * reaches the aggregate validator, so an element issue names the element.
130
- *
131
- * @param label - How the input is spelled in diagnostics.
132
- * @param value - The resolved value.
133
- * @param collection - Whether the input's cardinality aggregates values.
134
- * @param element - Validator for each element, or for the value itself.
135
- * @param aggregate - Validator for the completed collection.
136
- * @param errors - Collector for the issues found.
137
- * @param echo - Whether a diagnostic may record the value.
138
- * @returns The value to store, and whether validation replaced it.
139
- */
140
- async function validateInput(label, value, collection, element, aggregate, errors, echo) {
141
- let current = value;
142
- let changed = false;
143
- const errorCount = errors.length;
144
- if (element !== void 0) {
145
- const validated = collection ? await validateElements(label, current, element, errors, echo) : await validateOne(label, current, element, errors, echo);
146
- current = validated.value;
147
- changed = changed || validated.changed;
148
- }
149
- if (aggregate !== void 0 && errors.length === errorCount) {
150
- const result = await validateValue(label, current, aggregate, echo);
151
- if (result.ok) {
152
- current = result.value;
153
- changed = true;
154
- } else errors.push(result.error);
155
- }
156
- return {
157
- changed,
158
- value: current
159
- };
160
- }
161
- /** Apply the element validator to a value, entry by entry when it is a collection. */
162
- async function validateElements(label, value, validator, errors, echo) {
163
- if (Array.isArray(value)) {
164
- const next = [];
165
- for (const [index, element] of value.entries()) {
166
- const result = await validateValue(`${label}[${index}]`, element, validator, echo);
167
- if (result.ok) next.push(result.value);
168
- else {
169
- next.push(element);
170
- errors.push(result.error);
171
- }
172
- }
173
- return {
174
- changed: true,
175
- value: next
176
- };
177
- }
178
- if (isPlainRecord(value)) {
179
- const next = /* @__PURE__ */ new Map();
180
- for (const [key, entry] of Object.entries(value)) {
181
- const result = await validateValue(`${label}.${key}`, entry, validator, echo);
182
- next.set(key, result.ok ? result.value : entry);
183
- if (!result.ok) errors.push(result.error);
184
- }
185
- return {
186
- changed: true,
187
- value: Object.fromEntries(next)
188
- };
189
- }
190
- return validateOne(label, value, validator, errors, echo);
191
- }
192
- /** Apply a validator to one value. */
193
- async function validateOne(label, value, validator, errors, echo) {
194
- const result = await validateValue(label, value, validator, echo);
195
- if (result.ok) return {
196
- changed: true,
197
- value: result.value
198
- };
199
- errors.push(result.error);
200
- return {
201
- changed: false,
202
- value
203
- };
204
- }
205
- /** Whether a resolved value is the record an entries collection produces. */
206
- function isPlainRecord(value) {
207
- if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
208
- const prototype = Object.getPrototypeOf(value);
209
- return prototype === Object.prototype || prototype === null;
210
- }
211
- //#endregion
212
- export { applyStandardValidators };
@@ -1,189 +0,0 @@
1
- //#region src/core/schema/activity.d.ts
2
- /**
3
- * Activity types — spinner and progress bar handles, options, events.
4
- *
5
- * These types define the contract for `Out.spinner()` and `Out.progress()`
6
- * lifecycle management. Implementations live in `core/output/activity.ts`.
7
- *
8
- * @module dreamcli/core/schema/activity
9
- */
10
- /**
11
- * Non-TTY fallback strategy for spinners and progress bars.
12
- *
13
- * - `'silent'` — no output at all (default). Ideal for CI where decorative
14
- * output is noise.
15
- * - `'static'` — emit plain text via `out.log()` / `out.error()` at
16
- * lifecycle boundaries (start, succeed, fail). No animation.
17
- */
18
- type Fallback = 'silent' | 'static';
19
- /** Options for {@link Out.spinner}. */
20
- interface SpinnerOptions {
21
- /**
22
- * Fallback strategy when `!isTTY` or `jsonMode`.
23
- * @defaultValue `'silent'`
24
- */
25
- readonly fallback?: Fallback;
26
- }
27
- /**
28
- * Handle returned by {@link Out.spinner} for lifecycle control.
29
- *
30
- * Terminal methods (`succeed`, `fail`, `stop`) are idempotent — calling any
31
- * of them after the handle is already stopped is a no-op, not an error.
32
- */
33
- interface SpinnerHandle {
34
- /** Update the spinner text (no-op if stopped). */
35
- update(text: string): void;
36
- /** Stop with a success symbol and optional final text. */
37
- succeed(text?: string): void;
38
- /** Stop with a failure symbol and optional final text. */
39
- fail(text?: string): void;
40
- /** Stop the spinner without a status symbol. */
41
- stop(): void;
42
- /**
43
- * Wrap a promise: auto-succeed on resolve, auto-fail on reject.
44
- *
45
- * @returns The resolved value of the wrapped promise.
46
- */
47
- wrap<T>(promise: Promise<T>, options?: {
48
- readonly succeed?: string;
49
- readonly fail?: string;
50
- }): Promise<T>;
51
- }
52
- /** Options for {@link Out.progress}. */
53
- interface ProgressOptions {
54
- /**
55
- * Total units of work. When provided, the bar shows a determinate
56
- * percentage. When omitted, the bar pulses in indeterminate mode.
57
- */
58
- readonly total?: number;
59
- /** Label displayed alongside the progress bar. */
60
- readonly label?: string;
61
- /**
62
- * Fallback strategy when `!isTTY` or `jsonMode`.
63
- * @defaultValue `'silent'`
64
- */
65
- readonly fallback?: Fallback;
66
- }
67
- /**
68
- * Handle returned by {@link Out.progress} for lifecycle control.
69
- *
70
- * Terminal methods (`done`, `fail`) are idempotent — calling any
71
- * of them after the handle is already stopped is a no-op.
72
- */
73
- interface ProgressHandle {
74
- /** Advance progress by `n` units (default 1). */
75
- increment(n?: number): void;
76
- /** Set progress to an absolute value. */
77
- update(value: number): void;
78
- /** Mark progress as complete with an optional final message. */
79
- done(text?: string): void;
80
- /** Mark progress as failed with an optional final message. */
81
- fail(text?: string): void;
82
- }
83
- /**
84
- * Discriminated union of spinner and progress lifecycle events.
85
- *
86
- * Captured by testkit in {@link RunResult.activity} for assertion
87
- * without polluting stdout/stderr arrays.
88
- */
89
- type ActivityEvent = {
90
- /** Spinner created and started. */
91
- readonly type: 'spinner:start';
92
- /** Initial spinner text. */
93
- readonly text: string;
94
- } | {
95
- /** Spinner text changed. */
96
- readonly type: 'spinner:update';
97
- /** Updated spinner text. */
98
- readonly text: string;
99
- } | {
100
- /** Spinner completed successfully. */
101
- readonly type: 'spinner:succeed';
102
- /** Success message. */
103
- readonly text: string;
104
- } | {
105
- /** Spinner stopped with an error. */
106
- readonly type: 'spinner:fail';
107
- /** Failure message. */
108
- readonly text: string;
109
- } | {
110
- /** Spinner stopped without a final status. */
111
- readonly type: 'spinner:stop';
112
- } | {
113
- /** Progress bar created and started. */
114
- readonly type: 'progress:start';
115
- /** Bar label. */
116
- readonly label: string;
117
- /** Known total, or `undefined` for indeterminate. */
118
- readonly total: number | undefined;
119
- } | {
120
- /** Progress bar advanced. */
121
- readonly type: 'progress:increment';
122
- /** Amount advanced. */
123
- readonly delta: number;
124
- } | {
125
- /** Progress bar set to an absolute value. */
126
- readonly type: 'progress:update';
127
- /** New absolute value. */
128
- readonly value: number;
129
- } | {
130
- /** Progress bar completed. */
131
- readonly type: 'progress:done';
132
- /** Completion message, if any. */
133
- readonly text: string | undefined;
134
- } | {
135
- /** Progress bar stopped with an error. */
136
- readonly type: 'progress:fail';
137
- /** Failure message, if any. */
138
- readonly text: string | undefined;
139
- };
140
- /**
141
- * Describes a single column in table output.
142
- *
143
- * @typeParam T - The row object type (inferred from the rows array).
144
- */
145
- interface TableColumn<T extends Record<string, unknown>> {
146
- /** Property key on the row objects to display in this column. */
147
- readonly key: keyof T & string;
148
- /**
149
- * Header label for the column.
150
- * @defaultValue the {@link TableColumn.key | key} value
151
- */
152
- readonly header?: string;
153
- }
154
- /** Render format override for {@link Out.table}. */
155
- type TableFormat = 'auto' | 'text' | 'json';
156
- /** Output stream override for text table rendering. */
157
- type TableStream = 'stdout' | 'stderr';
158
- /**
159
- * Per-call table output options.
160
- *
161
- * `format: 'auto'` preserves the current mode-dependent behavior.
162
- * `format: 'json'` always emits a JSON array to stdout.
163
- * `format: 'text'` always renders a human-readable table; when `stream` is
164
- * omitted, text defaults to stdout in normal mode and stderr in jsonMode.
165
- */
166
- /** Preserve the mode-dependent default — text tables in normal mode, JSON in `jsonMode`. */
167
- interface TableOptionsAuto {
168
- /**
169
- * Follow the current output mode (text in normal, JSON in jsonMode).
170
- * @defaultValue `'auto'`
171
- */
172
- readonly format?: 'auto';
173
- }
174
- /** Force JSON array output to stdout regardless of output mode. */
175
- interface TableOptionsJson {
176
- /** Always emit a JSON array to stdout. */
177
- readonly format: 'json';
178
- }
179
- /** Force human-readable text table output, optionally routed to a specific {@link TableStream}. */
180
- interface TableOptionsText {
181
- /** Always render a human-readable text table. */
182
- readonly format: 'text';
183
- /** Target stream for text output. Falls back to stdout (stderr in jsonMode). */
184
- readonly stream?: TableStream;
185
- }
186
- /** Per-call rendering options for {@link Out.table}. */
187
- type TableOptions = TableOptionsAuto | TableOptionsJson | TableOptionsText;
188
- //#endregion
189
- export type { ActivityEvent, Fallback, ProgressHandle, ProgressOptions, SpinnerHandle, SpinnerOptions, TableColumn, TableFormat, TableOptions, TableOptionsAuto, TableOptionsJson, TableOptionsText, TableStream };