@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
@@ -0,0 +1,831 @@
1
+ import { A as Out, I as ResolutionProvenance, Jn as schemaBrand, Ln as HelpThemeFactory, Rn as ActivityEvent, U as Verbosity, b as CommandSchema, o as PromptEngine, y as CommandMeta } from "./index-BziI2aKc.mjs";
2
+ import { Colors } from "ansispeck";
3
+ //#region src/core/cli/builtins.d.ts
4
+ /** A built-in flag a consumer can take over. */
5
+ type BuiltinName = 'help' | 'json' | 'quiet';
6
+ /** Whether the root keeps a built-in or releases it to commands. */
7
+ type BuiltinMode = 'on' | 'off';
8
+ /**
9
+ * Built-in flag settings accepted by {@linkcode CLIBuilder.builtins} and the
10
+ * `builtins` field of {@link CLIDefinition}.
11
+ *
12
+ * `version` and `completions` are absent by design: `.version()` and
13
+ * `.completions()` are opt-in, so a CLI declines those two by not calling them.
14
+ */
15
+ interface BuiltinsConfig {
16
+ /**
17
+ * Root `--help`/`-h`, command-level `--help`/`-h`, and the bare `help` token.
18
+ * @defaultValue `'on'`
19
+ */
20
+ readonly help?: BuiltinMode;
21
+ /**
22
+ * Root `--json`.
23
+ * @defaultValue `'on'`
24
+ */
25
+ readonly json?: BuiltinMode;
26
+ /**
27
+ * Root `--quiet`/`-q`.
28
+ * @defaultValue `'on'`
29
+ */
30
+ readonly quiet?: BuiltinMode;
31
+ }
32
+ /**
33
+ * Normalized built-in flag state stored on {@link CLISchema}.
34
+ *
35
+ * Sealed by {@link createCLISchema}; every key is present after normalization.
36
+ */
37
+ interface Builtins {
38
+ /** Type-only seal produced by {@link createCLISchema}. */
39
+ readonly [schemaBrand]: 'builtins';
40
+ /** Whether the root owns `--help`/`-h` and the bare `help` token. */
41
+ readonly help: BuiltinMode;
42
+ /** Whether the root owns `--json`. */
43
+ readonly json: BuiltinMode;
44
+ /** Whether the root owns `--quiet`/`-q`. */
45
+ readonly quiet: BuiltinMode;
46
+ }
47
+ //#endregion
48
+ //#region src/core/errors/index.d.ts
49
+ /**
50
+ * Structured error types for DreamCLI.
51
+ *
52
+ * Base {@linkcode CLIError} carries stable code, exit code, suggestion, and structured
53
+ * details. {@linkcode ParseError} and {@linkcode ValidationError} derive from it with
54
+ * category-appropriate defaults.
55
+ *
56
+ * @module dreamcli/core/errors
57
+ */
58
+ /** Codes emitted during argv parsing. */
59
+ type ParseErrorCode = 'UNKNOWN_FLAG' | 'UNKNOWN_COMMAND' | 'MISSING_VALUE' | 'INVALID_VALUE' | 'INVALID_SCHEMA' | 'DUPLICATE_FLAG' | 'UNEXPECTED_POSITIONAL';
60
+ /** Codes emitted during post-parse validation / resolution. */
61
+ type ValidationErrorCode = 'REQUIRED_FLAG' | 'REQUIRED_ARG' | 'MISSING_STDIN' | 'INVALID_ENUM' | 'TYPE_MISMATCH' | 'CONSTRAINT_VIOLATED';
62
+ /** Any framework error code (extensible via `string & {}`). */
63
+ type ErrorCode = ParseErrorCode | ValidationErrorCode | (string & {});
64
+ /** Options accepted by the `CLIError` constructor. */
65
+ interface CLIErrorOptions {
66
+ /** Stable machine-readable identifier (e.g. `"UNKNOWN_FLAG"`). */
67
+ readonly code: ErrorCode;
68
+ /**
69
+ * Process exit code.
70
+ * @defaultValue `1`
71
+ */
72
+ readonly exitCode?: number;
73
+ /** One-liner actionable hint shown to the user. */
74
+ readonly suggest?: string;
75
+ /** Arbitrary structured payload (serialised in `--json` mode). */
76
+ readonly details?: Readonly<Record<string, unknown>>;
77
+ /** Original error, if this wraps another. */
78
+ readonly cause?: unknown;
79
+ }
80
+ /**
81
+ * Base structured error for DreamCLI.
82
+ *
83
+ * Every error surfaced by the framework extends this class, ensuring a
84
+ * consistent shape for rendering (TTY pretty-print, `--json`, test assertions).
85
+ */
86
+ declare class CLIError extends Error {
87
+ /** Error class name, always `'CLIError'` for the base class. @override */
88
+ readonly name: string;
89
+ /** Stable machine-readable identifier. */
90
+ readonly code: ErrorCode;
91
+ /** Process exit code (defaults to `1`). */
92
+ readonly exitCode: number;
93
+ /** One-liner actionable hint. */
94
+ readonly suggest: string | undefined;
95
+ /** Structured payload for machine output. */
96
+ readonly details: Readonly<Record<string, unknown>> | undefined;
97
+ /** Create a structured CLI error from a human message and machine-readable options. */
98
+ constructor(message: string, options: CLIErrorOptions);
99
+ /**
100
+ * Serialise to a plain object suitable for JSON output.
101
+ *
102
+ * `details` is projected onto JSON-representable values: bigints become
103
+ * decimal digits and entries JSON cannot carry are omitted. The error
104
+ * object itself keeps the runtime values.
105
+ *
106
+ * @sealed
107
+ */
108
+ toJSON(): CLIErrorJSON;
109
+ }
110
+ /** Shape returned by {@linkcode CLIError}.toJSON(). */
111
+ interface CLIErrorJSON {
112
+ /** Error class name (e.g. `'CLIError'`, `'ParseError'`). */
113
+ readonly name: string;
114
+ /** Stable machine-readable identifier for programmatic matching. */
115
+ readonly code: ErrorCode;
116
+ /** Human-readable description of what went wrong. */
117
+ readonly message: string;
118
+ /** Process exit code associated with this error. */
119
+ readonly exitCode: number;
120
+ /** Actionable hint shown to the user, when available. */
121
+ readonly suggest?: string;
122
+ /** Structured payload for machine consumers, when available. */
123
+ readonly details?: Readonly<Record<string, unknown>>;
124
+ }
125
+ /** Options for {@linkcode ParseError}. Code is narrowed to parse-specific codes. */
126
+ interface ParseErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
127
+ /** Parse-category error code (e.g. `'UNKNOWN_FLAG'`, `'MISSING_VALUE'`). */
128
+ readonly code: ParseErrorCode;
129
+ /**
130
+ * Process exit code for parse failures.
131
+ * @defaultValue `2`
132
+ */
133
+ readonly exitCode?: number;
134
+ }
135
+ /**
136
+ * Error thrown when argv tokenization / parsing fails.
137
+ *
138
+ * Exit code defaults to `2` (standard for CLI usage errors).
139
+ */
140
+ declare class ParseError extends CLIError {
141
+ /** Always `'ParseError'`. @override */
142
+ readonly name: "ParseError";
143
+ /** Narrowed to parse-category codes. */
144
+ readonly code: ParseErrorCode;
145
+ /** Create a parse error with exit code defaulting to `2`. */
146
+ constructor(message: string, options: ParseErrorOptions);
147
+ }
148
+ /** Options for {@linkcode ValidationError}. Code is narrowed to validation-specific codes. */
149
+ interface ValidationErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
150
+ /** Validation-category error code (e.g. `'REQUIRED_FLAG'`, `'INVALID_ENUM'`). */
151
+ readonly code: ValidationErrorCode;
152
+ /**
153
+ * Process exit code for validation failures.
154
+ * @defaultValue `2`
155
+ */
156
+ readonly exitCode?: number;
157
+ }
158
+ /**
159
+ * Error thrown when resolved values fail validation constraints.
160
+ *
161
+ * Exit code defaults to `2` (standard for CLI usage errors).
162
+ */
163
+ declare class ValidationError extends CLIError {
164
+ /** Always `'ValidationError'`. @override */
165
+ readonly name: "ValidationError";
166
+ /** Narrowed to validation-category codes. */
167
+ readonly code: ValidationErrorCode;
168
+ /** Create a validation error with exit code defaulting to `2`. */
169
+ constructor(message: string, options: ValidationErrorOptions);
170
+ }
171
+ /** Narrows an unknown value to `CLIError`. */
172
+ declare function isCLIError(value: unknown): value is CLIError;
173
+ /** Narrows an unknown value to `ParseError`. */
174
+ declare function isParseError(value: unknown): value is ParseError;
175
+ /** Narrows an unknown value to `ValidationError`. */
176
+ declare function isValidationError(value: unknown): value is ValidationError;
177
+ //#endregion
178
+ //#region src/core/parse/index.d.ts
179
+ /**
180
+ * Token discriminated union.
181
+ *
182
+ * The tokenizer produces these from raw argv strings. The parser then
183
+ * interprets them against a command schema.
184
+ */
185
+ type Token = {
186
+ readonly kind: 'long-flag';
187
+ readonly name: string;
188
+ readonly value: string | undefined;
189
+ } | {
190
+ readonly kind: 'short-flags';
191
+ readonly chars: string;
192
+ } | {
193
+ readonly kind: 'positional';
194
+ readonly value: string;
195
+ } | {
196
+ readonly kind: 'separator';
197
+ };
198
+ /**
199
+ * Tokenize raw argv into structured tokens.
200
+ *
201
+ * Low-level utility: most apps should use {@link parse}, `cli().run()`, or
202
+ * `runCommand()` instead of tokenizing manually. Reach for `tokenize()` when
203
+ * building custom tooling such as debuggers, inspectors, or parser tests.
204
+ *
205
+ * Rules:
206
+ * - `--` → separator (everything after is positional)
207
+ * - `--flag` → long flag, no inline value
208
+ * - `--flag=v` → long flag with inline value
209
+ * - `-abc` → short flags (expanded individually by parser)
210
+ * - `-` → positional (convention: stdin placeholder)
211
+ * - everything else → positional
212
+ *
213
+ * @param argv - Raw argument strings to tokenize
214
+ * @returns Ordered token array ready for {@link parse}
215
+ *
216
+ * @example
217
+ * ```ts
218
+ * tokenize(['deploy', '--force', '--region=eu', '-v']);
219
+ * ```
220
+ */
221
+ declare function tokenize(argv: readonly string[]): readonly Token[];
222
+ /**
223
+ * Whether `token` appears in argv before the `--` end-of-options separator.
224
+ *
225
+ * Everything at or after the first `--` is a literal positional, so root-level
226
+ * flag interception (`--help` / `--version` / `--json`) must use this instead of
227
+ * a naive `Array.includes()` — otherwise a post-separator literal (`-- --json`)
228
+ * is wrongly treated as the flag.
229
+ *
230
+ * @param argv - Raw argument strings.
231
+ * @param token - Exact flag token to look for (e.g. `--version`).
232
+ * @returns `true` if `token` occurs before any `--` separator.
233
+ */
234
+ declare function includesBeforeSeparator(argv: readonly string[], token: string): boolean;
235
+ /**
236
+ * Remove every occurrence of `token` that appears before the `--` end-of-options
237
+ * separator, leaving post-separator literals untouched.
238
+ *
239
+ * The strip counterpart to {@linkcode includesBeforeSeparator}: root-level flags
240
+ * (`--json`) are stripped before dispatch/parse so the command schema never sees
241
+ * them, but a literal after `--` (`-- --json`) must reach the command unchanged.
242
+ *
243
+ * @param argv - Raw argument strings.
244
+ * @param token - Exact flag token to strip (e.g. `--json`).
245
+ * @returns A new argv with pre-separator occurrences of `token` removed, or the
246
+ * original reference when `token` does not occur before the separator.
247
+ */
248
+ declare function stripBeforeSeparator(argv: readonly string[], token: string): readonly string[];
249
+ /**
250
+ * Raw parsed values before resolution (defaults, env, config, etc.).
251
+ *
252
+ * Flag values are `unknown` because type coercion happens here but the
253
+ * generic type info lives in the schema builders, not at runtime.
254
+ */
255
+ interface ParseResult {
256
+ /** Flag values keyed by canonical flag name. */
257
+ readonly flags: Readonly<Record<string, unknown>>;
258
+ /** Positional arg values keyed by arg name. */
259
+ readonly args: Readonly<Record<string, unknown>>;
260
+ }
261
+ /** Options accepted by {@link parse} and {@link buildFlagLookup}. */
262
+ interface ParseOptions {
263
+ /**
264
+ * Accept the kebab↔camel counterpart spelling of each flag name/alias
265
+ * (`--doThis` for a flag named `do-this`, and vice versa). Automatically
266
+ * disabled per spelling pair when a command explicitly defines both.
267
+ *
268
+ * @defaultValue `true`
269
+ */
270
+ readonly caseParity?: boolean;
271
+ }
272
+ /**
273
+ * Parse tokenized argv against a command schema.
274
+ *
275
+ * Low-level API: most apps should let `cli()` or `runCommand()` handle parsing
276
+ * automatically. Call `parse()` directly when you need raw parsed values before
277
+ * env/config/default resolution or when writing custom tooling around schemas.
278
+ *
279
+ * @param schema - The command schema to parse against
280
+ * @param argv - Raw argv strings (NOT including the command name itself)
281
+ * @param options - Parser behavior toggles (see {@link ParseOptions})
282
+ * @returns Parsed flag and arg values
283
+ * @throws ParseError for unknown flags, missing values, type mismatches
284
+ *
285
+ * @example
286
+ * ```ts
287
+ * const parsed = parse(deploy.schema, ['production', '--force']);
288
+ * // => { args: { target: 'production' }, flags: { force: true } }
289
+ * ```
290
+ */
291
+ declare function parse(schema: CommandSchema, argv: readonly string[], options?: ParseOptions): ParseResult;
292
+ //#endregion
293
+ //#region src/core/resolve/contracts.d.ts
294
+ /**
295
+ * External state the resolver may consult after parsing.
296
+ *
297
+ * The resolver never reaches into `process`, files, or terminal APIs directly;
298
+ * callers inject those facts through this contract.
299
+ */
300
+ interface ResolveOptions {
301
+ /** Pre-read stdin content, or `null` when stdin was not piped. */
302
+ readonly stdinData?: string | null;
303
+ /** Environment variable snapshot injected by the caller. */
304
+ readonly env?: Readonly<Record<string, string | undefined>>;
305
+ /** Parsed config file contents keyed by dotted path segments. */
306
+ readonly config?: Readonly<Record<string, unknown>>;
307
+ /** Interactive prompt engine; absent in non-TTY / CI contexts. */
308
+ readonly prompter?: PromptEngine;
309
+ /**
310
+ * Filesystem probe for `flag.path()` and `arg.path()` checks: what exists
311
+ * at the path, or `null` when nothing does. When absent, path checks are
312
+ * skipped.
313
+ */
314
+ readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
315
+ /**
316
+ * Recursive directory creation for `flag.path()` and `arg.path()` `create`
317
+ * checks. When absent, missing paths are not created and existence rules
318
+ * apply as-is.
319
+ */
320
+ readonly mkdir?: (path: string) => Promise<void>;
321
+ }
322
+ /** Structured deprecation notice emitted for explicitly sourced values. */
323
+ interface DeprecationWarning {
324
+ /** Whether this deprecation targets a flag or a positional arg. */
325
+ readonly kind: 'flag' | 'arg';
326
+ /** Name of the deprecated flag or arg. */
327
+ readonly name: string;
328
+ /** Custom deprecation message, or `true` for the generic warning. */
329
+ readonly message: string | true;
330
+ }
331
+ /**
332
+ * Which stage produced each resolved value of one command.
333
+ *
334
+ * The erased form of {@link InputSources}: same records, keyed by plain strings
335
+ * because `resolve()` takes a `CommandSchema` rather than typed builders.
336
+ */
337
+ interface ResolutionProvenanceRecord {
338
+ /** Provenance of every declared flag, keyed by flag name. */
339
+ readonly flags: Readonly<Record<string, ResolutionProvenance>>;
340
+ /** Provenance of every declared arg, keyed by arg name. */
341
+ readonly args: Readonly<Record<string, ResolutionProvenance>>;
342
+ }
343
+ /** Fully resolved command input handed to the executor layer. */
344
+ interface ResolveResult {
345
+ /** Fully resolved flag values keyed by flag name. */
346
+ readonly flags: Readonly<Record<string, unknown>>;
347
+ /** Fully resolved positional arg values keyed by arg name. */
348
+ readonly args: Readonly<Record<string, unknown>>;
349
+ /** Deprecation notices collected during resolution (may be empty). */
350
+ readonly deprecations: readonly DeprecationWarning[];
351
+ /**
352
+ * Which stage produced each value. Present only for inputs that resolved a
353
+ * value, so an unset optional input has no entry.
354
+ */
355
+ readonly provenance: ResolutionProvenanceRecord;
356
+ }
357
+ //#endregion
358
+ //#region src/core/resolve/index.d.ts
359
+ /**
360
+ * Resolve parsed values against a command schema.
361
+ *
362
+ * Low-level API: most applications should rely on `cli().run()`, `.execute()`,
363
+ * or `runCommand()`, which already call {@linkcode resolve} at the right time.
364
+ * Reach for this function when testing precedence rules directly or building
365
+ * custom execution flows around {@linkcode CommandSchema}.
366
+ *
367
+ * Resolution order:
368
+ * 1. CLI parsed value (from {@linkcode ParseResult})
369
+ * 2. Stdin (from {@linkcode ResolveOptions.stdinData}, if the input declares `stdin`)
370
+ * 3. Env variable (from {@linkcode ResolveOptions.env}, if the input declares `envVar`)
371
+ * 4. Config value (from {@linkcode ResolveOptions.config}, if the input declares `configPath`)
372
+ * 5. Prompt (from {@linkcode ResolveOptions.prompter}, if the input declares `prompt`)
373
+ * 6. Default value (from schema)
374
+ *
375
+ * After resolution, validates that all required flags and args have
376
+ * a value. Collects **all** validation errors before throwing, so the
377
+ * user sees every missing field at once.
378
+ *
379
+ * @param schema - The command schema defining flags and args
380
+ * @param parsed - Raw parsed values from the parser
381
+ * @param options - External state for the resolution chain
382
+ * @returns Fully resolved flag and arg values
383
+ * @throws {@linkcode ValidationError} if any required flag or arg is missing,
384
+ * or if an env/config value fails coercion
385
+ *
386
+ * @example
387
+ * ```ts
388
+ * const parsed = parse(deploy.schema, ['production']);
389
+ * const resolved = await resolve(deploy.schema, parsed, {
390
+ * env: { DEPLOY_REGION: 'eu' },
391
+ * });
392
+ * ```
393
+ */
394
+ declare function resolve(schema: CommandSchema, parsed: ParseResult, options?: ResolveOptions): Promise<ResolveResult>;
395
+ //#endregion
396
+ //#region src/core/cli/plugin.d.ts
397
+ /** Shared hook payload for a concrete command execution. */
398
+ interface PluginCommandContext {
399
+ /** Runtime command schema being executed. */
400
+ readonly command: CommandSchema;
401
+ /** CLI metadata for this execution. */
402
+ readonly meta: CommandMeta;
403
+ /** Output channel for this execution. */
404
+ readonly out: Out;
405
+ }
406
+ /** Payload for `beforeParse`. */
407
+ interface BeforeParseParams extends PluginCommandContext {
408
+ /** Raw argv that will be parsed for the leaf command. */
409
+ readonly argv: readonly string[];
410
+ }
411
+ /** Payload for hooks that observe resolved inputs. */
412
+ interface ResolvedCommandParams extends PluginCommandContext {
413
+ /** Fully resolved flag values. */
414
+ readonly flags: Readonly<Record<string, unknown>>;
415
+ /** Fully resolved argument values. */
416
+ readonly args: Readonly<Record<string, unknown>>;
417
+ /** Structured deprecation warnings collected during resolution. */
418
+ readonly deprecations: readonly DeprecationWarning[];
419
+ }
420
+ /**
421
+ * Individual lifecycle hooks that a plugin may implement.
422
+ *
423
+ * Hook order for a successful command run is:
424
+ * `beforeParse` → `afterResolve` → `beforeAction` → middleware/action → `afterAction`.
425
+ *
426
+ * Hooks are awaited serially and run in plugin registration order at each
427
+ * stage. Throwing from any hook aborts the command just like throwing from
428
+ * middleware or the action handler. `afterAction` runs only after the
429
+ * middleware chain and action complete successfully.
430
+ */
431
+ interface CLIPluginHooks {
432
+ /** Called immediately before leaf-command argv is parsed. */
433
+ readonly beforeParse?: (params: BeforeParseParams) => void | Promise<void>;
434
+ /** Called after parse + resolve, before middleware or action execution. */
435
+ readonly afterResolve?: (params: ResolvedCommandParams) => void | Promise<void>;
436
+ /** Called immediately before the middleware chain and action handler run. */
437
+ readonly beforeAction?: (params: ResolvedCommandParams) => void | Promise<void>;
438
+ /** Called after the middleware chain and action handler complete successfully. */
439
+ readonly afterAction?: (params: ResolvedCommandParams) => void | Promise<void>;
440
+ }
441
+ /**
442
+ * Immutable plugin definition registered via `CLIBuilder.plugin()`.
443
+ *
444
+ * Use {@link plugin} to construct values of this shape instead of manually
445
+ * assembling the object.
446
+ */
447
+ interface CLIPlugin {
448
+ /** Optional label for diagnostics and debugging. */
449
+ readonly name: string | undefined;
450
+ /** Lifecycle hooks implemented by the plugin. */
451
+ readonly hooks: CLIPluginHooks;
452
+ }
453
+ /**
454
+ * Create a CLI plugin from lifecycle hooks.
455
+ *
456
+ * @param hooks - Lifecycle hooks to register.
457
+ * @param name - Optional plugin name for diagnostics.
458
+ *
459
+ * @example
460
+ * ```ts
461
+ * import { cli, command, plugin } from '@kjanat/dreamcli';
462
+ *
463
+ * const deploy = command('deploy').action(({ out }) => {
464
+ * out.log('deploying');
465
+ * });
466
+ *
467
+ * const trace = plugin(
468
+ * {
469
+ * beforeParse: ({ argv, out }) => {
470
+ * out.info(`argv: ${argv.join(' ')}`);
471
+ * },
472
+ * afterResolve: ({ flags, args }) => {
473
+ * console.log({ flags, args });
474
+ * },
475
+ * },
476
+ * 'trace',
477
+ * );
478
+ *
479
+ * cli('mycli').plugin(trace).command(deploy).run();
480
+ * ```
481
+ *
482
+ * @returns A frozen {@link CLIPlugin} definition.
483
+ */
484
+ declare function plugin(hooks: CLIPluginHooks, name?: string): CLIPlugin;
485
+ //#endregion
486
+ //#region src/core/help/index.d.ts
487
+ /** Options for customising help output. */
488
+ interface HelpOptions {
489
+ /** Maximum line width (columns). Defaults to 80. */
490
+ readonly width?: number;
491
+ /** Binary/program name shown in the usage line. Defaults to command name. */
492
+ readonly binName?: string;
493
+ /** Program version passed to function-form examples as `meta.version`. */
494
+ readonly version?: string;
495
+ /**
496
+ * Order of flags in the `Flags:` table.
497
+ *
498
+ * - `'alphabetical'` — short-aliased flags first, then alphabetical by name.
499
+ * - `'declaration'` — the order `.flag()` was called.
500
+ *
501
+ * Ignored when {@link HelpOptions.sortFlags} is set.
502
+ *
503
+ * @defaultValue `'alphabetical'`
504
+ */
505
+ readonly flagOrder?: 'alphabetical' | 'declaration';
506
+ /**
507
+ * Custom comparator over flag long names for the `Flags:` table. When set,
508
+ * it wins over {@link HelpOptions.flagOrder}.
509
+ *
510
+ * @defaultValue `undefined` (use `flagOrder`)
511
+ */
512
+ readonly sortFlags?: (a: string, b: string) => number;
513
+ /**
514
+ * Emit OSC 8 hyperlinks where link metadata is available (currently the
515
+ * root-help header name/version configured via `CLIBuilder.links()`).
516
+ * Defaults to `false`; `CLIBuilder.execute()`/`.run()` enable it
517
+ * automatically when stdout is a TTY.
518
+ */
519
+ readonly hyperlinks?: boolean;
520
+ /**
521
+ * Render the default command's arguments and flags inline in root help.
522
+ *
523
+ * Only affects root-level help. When `false`, root help lists commands and
524
+ * defers default-command details to `<bin> --help`-style hints.
525
+ *
526
+ * @defaultValue `true`
527
+ */
528
+ readonly inlineDefault?: boolean;
529
+ /**
530
+ * List the default command in the root `Commands:` table.
531
+ *
532
+ * By default the default command is treated as the root surface and omitted
533
+ * from the command list (its args/flags render inline instead).
534
+ *
535
+ * @defaultValue `false`
536
+ */
537
+ readonly showDefaultInCommands?: boolean;
538
+ /**
539
+ * Show the `Run '<bin> <command> --help' for more information.` footer.
540
+ *
541
+ * Defaults to showing the hint only when visible subcommands exist; set
542
+ * explicitly to force it on or off.
543
+ */
544
+ readonly footer?: boolean;
545
+ /** @internal Whether this usage line is being rendered as merged root/default help. */
546
+ readonly isDefaultHelp?: boolean;
547
+ /**
548
+ * Gated ANSI palette used to style help output. Identity formatters mean
549
+ * plain text. `CLIBuilder.execute()`/`.run()` thread the output channel's
550
+ * `out.color` here automatically, so styling follows the same policy as
551
+ * handler output (TTY + color support, no `--json`, `NO_COLOR` honored).
552
+ *
553
+ * @defaultValue `undefined` (plain text)
554
+ */
555
+ readonly colors?: Colors;
556
+ /**
557
+ * Theme overrides merged over the built-in help theme. Receives the gated
558
+ * palette; never invoked when color is off, so overrides cannot leak
559
+ * escapes into piped output.
560
+ *
561
+ * @defaultValue `undefined` (built-in theme)
562
+ */
563
+ readonly theme?: HelpThemeFactory;
564
+ /**
565
+ * Theme overrides used only by function-form flag and argument descriptions.
566
+ * Merged over the resolved global theme, one role at a time.
567
+ *
568
+ * @defaultValue `undefined` (use the global theme)
569
+ */
570
+ readonly descriptionTheme?: HelpThemeFactory;
571
+ }
572
+ /**
573
+ * Generate help text from a command schema.
574
+ *
575
+ * Low-level formatter: most applications reach this through `--help`,
576
+ * `help <command>`, or root help rendering in `CLIBuilder`. Call
577
+ * `formatHelp()` directly when embedding DreamCLI help text into custom UIs,
578
+ * tests, or generated docs.
579
+ *
580
+ * Sections rendered (in order):
581
+ * 1. **Usage** line — `program <command> [flags] <args>`
582
+ * 2. **Description** — the command's `.description()` text
583
+ * 3. **Commands** — subcommands table (if any, skips hidden)
584
+ * 4. **Arguments** — positional args table (if any)
585
+ * 5. **Flags** — flags table with type hints and defaults
586
+ * 6. **Examples** — usage examples (if any)
587
+ *
588
+ * @param schema - The command schema to render help for.
589
+ * @param options - Formatting options (width, binary name).
590
+ * @returns The formatted help string.
591
+ *
592
+ * @example
593
+ * ```ts
594
+ * const text = formatHelp(deploy.schema, { binName: 'mycli' });
595
+ * ```
596
+ */
597
+ declare function formatHelp(schema: CommandSchema, options?: HelpOptions): string;
598
+ //#endregion
599
+ //#region src/core/prompt/test-prompter.d.ts
600
+ /**
601
+ * Sentinel value representing a cancelled/aborted prompt in the test
602
+ * prompter's answer queue.
603
+ *
604
+ * Uses `Symbol.for()` for cross-bundle safety — the same symbol is
605
+ * returned regardless of which copy of the module is loaded.
606
+ *
607
+ * @example
608
+ * ```ts
609
+ * const prompter = createTestPrompter([
610
+ * 'us', // first prompt answered 'us'
611
+ * PROMPT_CANCEL, // second prompt cancelled
612
+ * ]);
613
+ * ```
614
+ */
615
+ declare const PROMPT_CANCEL: unique symbol;
616
+ /**
617
+ * A queued answer consumed by {@link createTestPrompter}.
618
+ *
619
+ * The test prompter returns these values exactly as provided; it does not
620
+ * coerce them. The one exception mirrors the terminal prompter: a string answer
621
+ * to an `input` prompt is run through the prompt's `validate` function, and a
622
+ * failing answer is rejected as a cancellation (see {@link createTestPrompter}).
623
+ * The normal resolution pipeline performs any later type coercion, so tests can
624
+ * supply values in the same shapes real prompts would yield:
625
+ *
626
+ * - `string` for `input` and `select`
627
+ * - `boolean` for `confirm`
628
+ * - `string[]` for `multiselect`
629
+ * - `PROMPT_CANCEL` to simulate user cancellation
630
+ *
631
+ * Because the type is intentionally `unknown`, tests may also inject malformed
632
+ * answers to exercise downstream validation and error reporting.
633
+ */
634
+ type TestAnswer = unknown;
635
+ /**
636
+ * Options for `createTestPrompter`.
637
+ */
638
+ interface TestPrompterOptions {
639
+ /**
640
+ * Behavior when all answers have been consumed.
641
+ *
642
+ * - `'throw'` (default) — throws an error, making the test fail
643
+ * loudly if more prompts fire than expected.
644
+ * - `'cancel'` — returns `{ answered: false }`, simulating the
645
+ * user cancelling all subsequent prompts.
646
+ */
647
+ readonly onExhausted?: 'throw' | 'cancel';
648
+ }
649
+ /**
650
+ * Create a prompt engine that returns pre-configured answers.
651
+ *
652
+ * Each call to `promptOne` consumes the next answer from the queue.
653
+ * Pass `PROMPT_CANCEL` as an answer to simulate the user cancelling
654
+ * that prompt.
655
+ *
656
+ * For `input` prompts that declare a `validate` function, a string answer is
657
+ * validated just as the terminal prompter does. An answer that fails validation
658
+ * is rejected as a cancellation (`{ answered: false }`) — mirroring the terminal
659
+ * prompter exhausting its retries — so prompt validation is integration-testable
660
+ * via {@linkcode runCommand} rather than silently accepted as the resolved value.
661
+ *
662
+ * @param answers - Ordered queue of answers. Use `PROMPT_CANCEL` for
663
+ * cancellation.
664
+ * @param options - Controls behavior when the queue is exhausted.
665
+ * @returns A {@linkcode PromptEngine} suitable for testing.
666
+ *
667
+ * @example
668
+ * ```ts
669
+ * const prompter = createTestPrompter(['eu', true, PROMPT_CANCEL]);
670
+ *
671
+ * // First promptOne → { answered: true, value: 'eu' }
672
+ * // Second promptOne → { answered: true, value: true }
673
+ * // Third promptOne → { answered: false }
674
+ * ```
675
+ */
676
+ declare function createTestPrompter(answers: readonly TestAnswer[], options?: TestPrompterOptions): PromptEngine;
677
+ //#endregion
678
+ //#region src/core/schema/run.d.ts
679
+ /**
680
+ * Options accepted by `runCommand()` and internal command execution paths.
681
+ *
682
+ * Every field is optional — sensible defaults are applied. This is the
683
+ * primary process-free execution seam: inject env, config, prompt I/O, and
684
+ * dispatch-layer metadata without touching process state.
685
+ */
686
+ interface RunOptions {
687
+ /**
688
+ * Environment variables for flag and arg resolution.
689
+ *
690
+ * Inputs with `.env('VAR')` configured resolve from this record when CLI
691
+ * and stdin produce nothing
692
+ * (CLI → stdin → env → config → prompt → default).
693
+ */
694
+ readonly env?: Readonly<Record<string, string | undefined>>;
695
+ /**
696
+ * Configuration object for flag and arg resolution.
697
+ *
698
+ * Inputs with `.config('path')` configured resolve from this record when
699
+ * CLI, stdin, and env produce nothing
700
+ * (CLI → stdin → env → config → prompt → default).
701
+ * Config is plain JSON, so file loading is the caller's responsibility.
702
+ */
703
+ readonly config?: Readonly<Record<string, unknown>>;
704
+ /**
705
+ * Full stdin contents for flags and args configured with `.stdin()`.
706
+ *
707
+ * Lets tests inject piped input without a runtime adapter.
708
+ */
709
+ readonly stdinData?: string | null;
710
+ /**
711
+ * Prompt engine for interactive flag and arg resolution.
712
+ *
713
+ * When provided, inputs with `.prompt()` configured that have no value
714
+ * after CLI, stdin, env, and config resolution are prompted interactively.
715
+ *
716
+ * When absent (and `answers` is also absent), prompting is skipped
717
+ * and resolution falls through to default/required.
718
+ *
719
+ * Takes precedence over `answers` when both are provided.
720
+ */
721
+ readonly prompter?: PromptEngine;
722
+ /**
723
+ * Pre-configured prompt answers for testing convenience.
724
+ *
725
+ * When provided, a test prompter is created from these answers via
726
+ * `createTestPrompter(answers)`. Each entry is consumed in order —
727
+ * use `PROMPT_CANCEL` to simulate cancellation.
728
+ *
729
+ * Ignored when an explicit `prompter` is provided.
730
+ */
731
+ readonly answers?: readonly TestAnswer[];
732
+ /**
733
+ * Filesystem probe for `flag.path()` and `arg.path()` checks: reports what
734
+ * exists at a path (`'file'`, `'directory'`, or `null` for nothing).
735
+ *
736
+ * `CLIBuilder.run()` supplies the runtime adapter's probe automatically.
737
+ * When absent (process-free `.execute()` / `runCommand()` without an
738
+ * override), path checks are skipped.
739
+ */
740
+ readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
741
+ /**
742
+ * Recursive directory creation for `flag.path()` and `arg.path()` `create`
743
+ * checks.
744
+ *
745
+ * `CLIBuilder.run()` supplies the runtime adapter's implementation
746
+ * automatically. When absent, missing paths are not created.
747
+ */
748
+ readonly mkdir?: (path: string) => Promise<void>;
749
+ /**
750
+ * Verbosity level for the output channel.
751
+ * @defaultValue `'normal'`
752
+ */
753
+ readonly verbosity?: Verbosity;
754
+ /**
755
+ * Enable JSON output mode.
756
+ *
757
+ * When `true`, `log` and `info` messages are redirected to stderr
758
+ * so that stdout is reserved exclusively for structured {@linkcode Out.json | json()} output.
759
+ * Framework-rendered errors are emitted as structured JSON to stdout.
760
+ *
761
+ * @defaultValue `false`
762
+ */
763
+ readonly jsonMode?: boolean;
764
+ /**
765
+ * Whether stdout is connected to a TTY.
766
+ *
767
+ * Handlers can check {@linkcode Out.isTTY | out.isTTY} to decide whether to emit decorative
768
+ * output (spinners, progress bars, ANSI codes). Defaults to `false`
769
+ * (safe default for tests — non-TTY until proven otherwise).
770
+ *
771
+ * @defaultValue `false`
772
+ */
773
+ readonly isTTY?: boolean;
774
+ /**
775
+ * Help formatting options (width, binName).
776
+ * Used when `--help` is detected.
777
+ */
778
+ readonly help?: HelpOptions;
779
+ /**
780
+ * Flag-parsing behavior settings.
781
+ *
782
+ * `caseParity` accepts the kebab↔camel counterpart spelling of each flag
783
+ * name/alias (`--doThis` for `do-this`, and vice versa). The CLI layer
784
+ * threads `cli(name, { flags })` settings here automatically.
785
+ *
786
+ * @defaultValue `{ caseParity: true }`
787
+ */
788
+ readonly flags?: ParseOptions;
789
+ }
790
+ /**
791
+ * Structured result from {@linkcode runCommand}.
792
+ *
793
+ * Contains the exit code, captured stdout/stderr output, recorded
794
+ * {@linkcode ActivityEvent | activity events}, and an `error` field.
795
+ * `error` is `undefined` when execution completed without throwing, even if
796
+ * the handler requested a non-zero status via {@linkcode Out.setExitCode}.
797
+ *
798
+ * @example
799
+ * ```ts
800
+ * const result = await runCommand(greetCmd, ['World']);
801
+ *
802
+ * expect(result.exitCode).toBe(0);
803
+ * expect(result.stdout).toContain('Hello, World!');
804
+ * expect(result.error).toBeUndefined();
805
+ * ```
806
+ */
807
+ interface RunResult {
808
+ /** Process exit code. 0 = success. */
809
+ readonly exitCode: number;
810
+ /** Captured stdout lines (from `out.log` and `out.info`). */
811
+ readonly stdout: readonly string[];
812
+ /** Captured stderr lines (from `out.warn` and `out.error`). */
813
+ readonly stderr: readonly string[];
814
+ /**
815
+ * Captured spinner and progress lifecycle events.
816
+ *
817
+ * Recorded separately from stdout/stderr — handlers that call
818
+ * {@linkcode Out.spinner | out.spinner()} or {@linkcode Out.progress | out.progress()} produce events here, enabling
819
+ * targeted assertions on activity lifecycle without parsing text.
820
+ */
821
+ readonly activity: readonly ActivityEvent[];
822
+ /**
823
+ * The error that caused a failure, or `undefined` when execution completed.
824
+ * A non-zero `exitCode` can still have no error when a handler calls
825
+ * {@linkcode Out.setExitCode}. {@linkcode CLIError} instances are preserved;
826
+ * unknown errors are wrapped.
827
+ */
828
+ readonly error: CLIError | undefined;
829
+ }
830
+ //#endregion
831
+ export { ErrorCode as A, BuiltinMode as B, includesBeforeSeparator as C, CLIError as D, tokenize as E, ValidationErrorCode as F, Builtins as H, ValidationErrorOptions as I, isCLIError as L, ParseErrorCode as M, ParseErrorOptions as N, CLIErrorJSON as O, ValidationError as P, isParseError as R, Token as S, stripBeforeSeparator as T, BuiltinsConfig as U, BuiltinName as V, ResolutionProvenanceRecord as _, TestPrompterOptions as a, ParseOptions as b, formatHelp as c, CLIPluginHooks as d, PluginCommandContext as f, DeprecationWarning as g, resolve as h, TestAnswer as i, ParseError as j, CLIErrorOptions as k, BeforeParseParams as l, plugin as m, RunResult as n, createTestPrompter as o, ResolvedCommandParams as p, PROMPT_CANCEL as r, HelpOptions as s, RunOptions as t, CLIPlugin as u, ResolveOptions as v, parse as w, ParseResult as x, ResolveResult as y, isValidationError as z };