@kjanat/dreamcli 0.0.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (205) hide show
  1. package/CHANGELOG.md +706 -0
  2. package/LICENSE +22 -0
  3. package/README.md +502 -0
  4. package/dist/core/cli/dispatch.d.mts +85 -0
  5. package/dist/core/cli/dispatch.mjs +1 -0
  6. package/dist/core/cli/index.d.mts +418 -0
  7. package/dist/core/cli/index.mjs +1 -0
  8. package/dist/core/cli/planner.d.mts +143 -0
  9. package/dist/core/cli/planner.mjs +1 -0
  10. package/dist/core/cli/plugin.d.mts +94 -0
  11. package/dist/core/cli/plugin.mjs +1 -0
  12. package/dist/core/cli/propagate.d.mts +39 -0
  13. package/dist/core/cli/propagate.mjs +1 -0
  14. package/dist/core/cli/root-help.d.mts +28 -0
  15. package/dist/core/cli/root-help.mjs +7 -0
  16. package/dist/core/cli/root-surface.d.mts +42 -0
  17. package/dist/core/cli/root-surface.mjs +1 -0
  18. package/dist/core/cli/runtime-preflight.d.mts +149 -0
  19. package/dist/core/cli/runtime-preflight.mjs +1 -0
  20. package/dist/core/completion/index.d.mts +46 -0
  21. package/dist/core/completion/index.mjs +1 -0
  22. package/dist/core/completion/shells/bash.d.mts +24 -0
  23. package/dist/core/completion/shells/bash.mjs +3 -0
  24. package/dist/core/completion/shells/fish.d.mts +20 -0
  25. package/dist/core/completion/shells/fish.mjs +2 -0
  26. package/dist/core/completion/shells/powershell.d.mts +14 -0
  27. package/dist/core/completion/shells/powershell.mjs +2 -0
  28. package/dist/core/completion/shells/shared.d.mts +139 -0
  29. package/dist/core/completion/shells/shared.mjs +1 -0
  30. package/dist/core/completion/shells/zsh.d.mts +24 -0
  31. package/dist/core/completion/shells/zsh.mjs +2 -0
  32. package/dist/core/config/index.d.mts +161 -0
  33. package/dist/core/config/index.mjs +1 -0
  34. package/dist/core/config/package-json.d.mts +68 -0
  35. package/dist/core/config/package-json.mjs +1 -0
  36. package/dist/core/errors/index.d.mts +126 -0
  37. package/dist/core/errors/index.mjs +1 -0
  38. package/dist/core/execution/index.d.mts +49 -0
  39. package/dist/core/execution/index.mjs +1 -0
  40. package/dist/core/help/index.d.mts +49 -0
  41. package/dist/core/help/index.mjs +8 -0
  42. package/dist/core/json-schema/index.d.mts +109 -0
  43. package/dist/core/json-schema/index.mjs +55 -0
  44. package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
  45. package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
  46. package/dist/core/output/activity.d.mts +194 -0
  47. package/dist/core/output/activity.mjs +1 -0
  48. package/dist/core/output/contracts.d.mts +88 -0
  49. package/dist/core/output/contracts.mjs +1 -0
  50. package/dist/core/output/display-value.d.mts +19 -0
  51. package/dist/core/output/display-value.mjs +1 -0
  52. package/dist/core/output/index.d.mts +280 -0
  53. package/dist/core/output/index.mjs +2 -0
  54. package/dist/core/output/renderers.d.mts +46 -0
  55. package/dist/core/output/renderers.mjs +1 -0
  56. package/dist/core/output/writer.d.mts +40 -0
  57. package/dist/core/output/writer.mjs +1 -0
  58. package/dist/core/parse/index.d.mts +79 -0
  59. package/dist/core/parse/index.mjs +1 -0
  60. package/dist/core/prompt/index.d.mts +205 -0
  61. package/dist/core/prompt/index.mjs +6 -0
  62. package/dist/core/resolve/args.d.mts +8 -0
  63. package/dist/core/resolve/args.mjs +1 -0
  64. package/dist/core/resolve/coerce.d.mts +22 -0
  65. package/dist/core/resolve/coerce.mjs +1 -0
  66. package/dist/core/resolve/config.d.mts +10 -0
  67. package/dist/core/resolve/config.mjs +1 -0
  68. package/dist/core/resolve/contracts.d.mts +112 -0
  69. package/dist/core/resolve/errors.d.mts +11 -0
  70. package/dist/core/resolve/errors.mjs +2 -0
  71. package/dist/core/resolve/flags.d.mts +10 -0
  72. package/dist/core/resolve/flags.mjs +1 -0
  73. package/dist/core/resolve/index.d.mts +42 -0
  74. package/dist/core/resolve/index.mjs +1 -0
  75. package/dist/core/resolve/property.d.mts +47 -0
  76. package/dist/core/resolve/property.mjs +1 -0
  77. package/dist/core/schema/activity.d.mts +169 -0
  78. package/dist/core/schema/arg.d.mts +559 -0
  79. package/dist/core/schema/arg.mjs +1 -0
  80. package/dist/core/schema/command.d.mts +960 -0
  81. package/dist/core/schema/command.mjs +1 -0
  82. package/dist/core/schema/flag.d.mts +491 -0
  83. package/dist/core/schema/flag.mjs +1 -0
  84. package/dist/core/schema/index.d.mts +8 -0
  85. package/dist/core/schema/middleware.d.mts +122 -0
  86. package/dist/core/schema/middleware.mjs +1 -0
  87. package/dist/core/schema/prompt.d.mts +117 -0
  88. package/dist/core/schema/run.d.mts +171 -0
  89. package/dist/core/schema-dsl/runtime.d.mts +144 -0
  90. package/dist/core/schema-dsl/runtime.mjs +2 -0
  91. package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
  92. package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
  93. package/dist/core/testkit/index.d.mts +54 -0
  94. package/dist/core/testkit/index.mjs +1 -0
  95. package/dist/index.d.mts +28 -0
  96. package/dist/index.mjs +1 -0
  97. package/dist/runtime/adapter.d.mts +212 -0
  98. package/dist/runtime/adapter.mjs +1 -0
  99. package/dist/runtime/auto.d.mts +26 -0
  100. package/dist/runtime/auto.mjs +1 -0
  101. package/dist/runtime/bun.d.mts +28 -0
  102. package/dist/runtime/bun.mjs +1 -0
  103. package/dist/runtime/deno.d.mts +76 -0
  104. package/dist/runtime/deno.mjs +2 -0
  105. package/dist/runtime/detect.d.mts +86 -0
  106. package/dist/runtime/detect.mjs +1 -0
  107. package/dist/runtime/index.d.mts +7 -0
  108. package/dist/runtime/node.d.mts +65 -0
  109. package/dist/runtime/node.mjs +2 -0
  110. package/dist/runtime/paths.d.mts +31 -0
  111. package/dist/runtime/paths.mjs +1 -0
  112. package/dist/runtime/support.d.mts +42 -0
  113. package/dist/runtime/support.mjs +1 -0
  114. package/dist/runtime.d.mts +7 -0
  115. package/dist/runtime.mjs +1 -0
  116. package/dist/testkit.d.mts +6 -0
  117. package/dist/testkit.mjs +1 -0
  118. package/dist/version.d.mts +16 -0
  119. package/dist/version.mjs +1 -0
  120. package/dreamcli.schema.json +338 -0
  121. package/examples/basic.ts +33 -0
  122. package/examples/gh/package.json +44 -0
  123. package/examples/gh/src/commands/auth.ts +66 -0
  124. package/examples/gh/src/commands/issue.ts +120 -0
  125. package/examples/gh/src/commands/pr.ts +125 -0
  126. package/examples/gh/src/data/issues.yaml +5 -0
  127. package/examples/gh/src/data/issues.yaml.d.ts +17 -0
  128. package/examples/gh/src/data/pull-requests.yaml +7 -0
  129. package/examples/gh/src/data/pull-requests.yaml.d.ts +18 -0
  130. package/examples/gh/src/docs.ts +11 -0
  131. package/examples/gh/src/lib/auth.ts +37 -0
  132. package/examples/gh/src/lib/utils.ts +17 -0
  133. package/examples/gh/src/main.test.ts +307 -0
  134. package/examples/gh/src/main.ts +40 -0
  135. package/examples/interactive.ts +66 -0
  136. package/examples/json-mode.ts +91 -0
  137. package/examples/middleware.ts +71 -0
  138. package/examples/multi-command.ts +66 -0
  139. package/examples/spinner-progress.ts +49 -0
  140. package/examples/testing.ts +147 -0
  141. package/package.json +149 -2
  142. package/src/core/cli/dispatch.ts +286 -0
  143. package/src/core/cli/index.ts +978 -0
  144. package/src/core/cli/planner.ts +413 -0
  145. package/src/core/cli/plugin.ts +117 -0
  146. package/src/core/cli/propagate.ts +97 -0
  147. package/src/core/cli/root-help.ts +269 -0
  148. package/src/core/cli/root-surface.ts +74 -0
  149. package/src/core/cli/runtime-preflight.ts +409 -0
  150. package/src/core/completion/index.ts +88 -0
  151. package/src/core/completion/shells/bash.ts +459 -0
  152. package/src/core/completion/shells/fish.ts +259 -0
  153. package/src/core/completion/shells/powershell.ts +405 -0
  154. package/src/core/completion/shells/shared.ts +283 -0
  155. package/src/core/completion/shells/zsh.ts +381 -0
  156. package/src/core/config/index.ts +407 -0
  157. package/src/core/config/package-json.ts +220 -0
  158. package/src/core/errors/index.ts +193 -0
  159. package/src/core/execution/index.ts +270 -0
  160. package/src/core/help/index.ts +557 -0
  161. package/src/core/json-schema/index.ts +891 -0
  162. package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
  163. package/src/core/output/activity.ts +568 -0
  164. package/src/core/output/contracts.ts +194 -0
  165. package/src/core/output/display-value.ts +48 -0
  166. package/src/core/output/index.ts +669 -0
  167. package/src/core/output/renderers.ts +125 -0
  168. package/src/core/output/writer.ts +46 -0
  169. package/src/core/parse/index.ts +661 -0
  170. package/src/core/prompt/index.ts +583 -0
  171. package/src/core/resolve/args.ts +144 -0
  172. package/src/core/resolve/coerce.ts +432 -0
  173. package/src/core/resolve/config.ts +26 -0
  174. package/src/core/resolve/contracts.ts +135 -0
  175. package/src/core/resolve/errors.ts +227 -0
  176. package/src/core/resolve/flags.ts +205 -0
  177. package/src/core/resolve/index.ts +108 -0
  178. package/src/core/resolve/property.ts +99 -0
  179. package/src/core/schema/activity.ts +240 -0
  180. package/src/core/schema/arg.ts +719 -0
  181. package/src/core/schema/command.ts +1490 -0
  182. package/src/core/schema/flag.ts +756 -0
  183. package/src/core/schema/index.ts +91 -0
  184. package/src/core/schema/middleware.ts +171 -0
  185. package/src/core/schema/prompt.ts +156 -0
  186. package/src/core/schema/run.ts +195 -0
  187. package/src/core/schema-dsl/index.ts +109 -0
  188. package/src/core/schema-dsl/parse.ts +262 -0
  189. package/src/core/schema-dsl/runtime.ts +609 -0
  190. package/src/core/schema-dsl/to-json-schema.ts +102 -0
  191. package/src/core/testkit/index.ts +123 -0
  192. package/src/index.ts +170 -0
  193. package/src/runtime/adapter.ts +303 -0
  194. package/src/runtime/auto.ts +110 -0
  195. package/src/runtime/bun.ts +55 -0
  196. package/src/runtime/deno.ts +369 -0
  197. package/src/runtime/detect.ts +105 -0
  198. package/src/runtime/index.ts +21 -0
  199. package/src/runtime/node-builtins.d.ts +23 -0
  200. package/src/runtime/node.ts +300 -0
  201. package/src/runtime/paths.ts +62 -0
  202. package/src/runtime/support.ts +135 -0
  203. package/src/runtime.ts +31 -0
  204. package/src/testkit.ts +25 -0
  205. package/src/version.ts +20 -0
@@ -0,0 +1,91 @@
1
+ /**
2
+ * Command, flag, and arg schema builders with full type inference.
3
+ *
4
+ * @module dreamcli/core/schema
5
+ */
6
+
7
+ export type {
8
+ ActivityEvent,
9
+ Fallback,
10
+ ProgressHandle,
11
+ ProgressOptions,
12
+ SpinnerHandle,
13
+ SpinnerOptions,
14
+ TableColumn,
15
+ TableFormat,
16
+ TableOptions,
17
+ TableStream,
18
+ } from './activity.ts';
19
+ export type {
20
+ ArgConfig,
21
+ ArgFactory,
22
+ ArgKind,
23
+ ArgParseFn,
24
+ ArgPresence,
25
+ ArgSchema,
26
+ InferArg,
27
+ InferArgs,
28
+ ResolvedArgValue,
29
+ WithArgPresence,
30
+ WithVariadic,
31
+ } from './arg.ts';
32
+ export { ARG_KINDS, ARG_PRESENCES, ArgBuilder, arg, createArgSchema } from './arg.ts';
33
+ export type {
34
+ ActionHandler,
35
+ ActionParams,
36
+ AnyCommandBuilder,
37
+ CommandArgEntry,
38
+ CommandConfig,
39
+ CommandExample,
40
+ CommandMeta,
41
+ CommandSchema,
42
+ DeriveHandler,
43
+ DeriveParams,
44
+ ErasedCommand,
45
+ ErasedDeriveHandler,
46
+ ErasedInteractiveResolver,
47
+ InteractiveParams,
48
+ InteractiveResolver,
49
+ InteractiveResult,
50
+ Out,
51
+ } from './command.ts';
52
+ export { CommandBuilder, command, group } from './command.ts';
53
+ export type {
54
+ ConfirmPromptConfig,
55
+ FlagAlias,
56
+ FlagConfig,
57
+ FlagFactory,
58
+ FlagKind,
59
+ FlagParseFn,
60
+ FlagPresence,
61
+ FlagSchema,
62
+ FlagSchemaOverrides,
63
+ InferFlag,
64
+ InferFlags,
65
+ InputPromptConfig,
66
+ MultiselectPromptConfig,
67
+ PromptConfig,
68
+ PromptConfigBase,
69
+ PromptKind,
70
+ PromptResult,
71
+ ResolvedValue,
72
+ SelectChoice,
73
+ SelectPromptConfig,
74
+ WithPresence,
75
+ } from './flag.ts';
76
+ export {
77
+ createSchema,
78
+ FLAG_KINDS,
79
+ FLAG_PRESENCES,
80
+ FlagBuilder,
81
+ flag,
82
+ PROMPT_KINDS,
83
+ } from './flag.ts';
84
+ export type {
85
+ ErasedMiddlewareHandler,
86
+ Middleware,
87
+ MiddlewareHandler,
88
+ MiddlewareParams,
89
+ } from './middleware.ts';
90
+ export { middleware } from './middleware.ts';
91
+ export type { RunOptions, RunResult } from './run.ts';
@@ -0,0 +1,171 @@
1
+ /**
2
+ * Middleware type definitions and factory function.
3
+ *
4
+ * Middleware runs before the action handler and can:
5
+ * - Add typed context via `next({ key: value })`
6
+ * - Short-circuit by throwing `CLIError` (or not calling `next`)
7
+ * - Wrap downstream execution (timing, logging) by awaiting `next()`
8
+ *
9
+ * The {@linkcode Middleware} type uses a phantom generic to track what
10
+ * context properties this middleware adds. At runtime, middleware is
11
+ * type-erased — the phantom type is only used for compile-time inference
12
+ * when `.middleware()` is chained on `CommandBuilder`.
13
+ *
14
+ * @module dreamcli/core/schema/middleware
15
+ */
16
+
17
+ import type { CommandMeta, Out } from './command.ts';
18
+
19
+ // --- Middleware parameter types
20
+
21
+ /**
22
+ * Parameters received by a middleware function at runtime.
23
+ *
24
+ * Middleware receives erased args/flags (since it's defined independently
25
+ * of commands) plus the accumulated context from prior middleware and a
26
+ * `next` function to continue the chain.
27
+ */
28
+ interface MiddlewareParams {
29
+ /** Fully resolved positional arguments (type-erased). */
30
+ readonly args: Readonly<Record<string, unknown>>;
31
+ /** Fully resolved flags (type-erased). */
32
+ readonly flags: Readonly<Record<string, unknown>>;
33
+ /** Context accumulated from previous middleware in the chain. */
34
+ readonly ctx: Readonly<Record<string, unknown>>;
35
+ /** Output channel. */
36
+ readonly out: Out;
37
+ /** CLI program metadata (name, bin, version, command). */
38
+ readonly meta: CommandMeta;
39
+ /**
40
+ * Continue to the next middleware or action handler.
41
+ *
42
+ * Call with context additions that merge into `ctx` for downstream.
43
+ * Returns when the entire downstream chain completes — enabling
44
+ * wrap-around patterns (timing, try/catch, cleanup).
45
+ */
46
+ readonly next: (additions: Record<string, unknown>) => Promise<void>;
47
+ }
48
+
49
+ // --- Handler types
50
+
51
+ /**
52
+ * Type-erased middleware handler stored on `CommandSchema`.
53
+ *
54
+ * At runtime, all middleware handlers have this signature. The phantom
55
+ * `Output` type on {@linkcode Middleware} is erased.
56
+ *
57
+ * @internal
58
+ */
59
+ type ErasedMiddlewareHandler = (params: MiddlewareParams) => void | Promise<void>;
60
+
61
+ /**
62
+ * Middleware handler function with typed `next()` parameter.
63
+ *
64
+ * The `Output` generic constrains what properties must be passed to
65
+ * {@linkcode MiddlewareParams.next | next()}, ensuring type-safe context additions at the call site.
66
+ */
67
+ type MiddlewareHandler<Output extends Record<string, unknown>> = (params: {
68
+ readonly args: Readonly<Record<string, unknown>>;
69
+ readonly flags: Readonly<Record<string, unknown>>;
70
+ readonly ctx: Readonly<Record<string, unknown>>;
71
+ readonly out: Out;
72
+ readonly meta: CommandMeta;
73
+ /** Pass context additions downstream. Must include all `Output` properties. */
74
+ readonly next: (additions: Output) => Promise<void>;
75
+ }) => void | Promise<void>;
76
+
77
+ // --- Middleware type — phantom-branded
78
+
79
+ /**
80
+ * Internal runtime representation of middleware.
81
+ * @internal
82
+ */
83
+ interface MiddlewareImpl {
84
+ readonly _handler: ErasedMiddlewareHandler;
85
+ }
86
+
87
+ /**
88
+ * Middleware with phantom output type.
89
+ *
90
+ * The `Output` parameter tracks what this middleware adds to context at
91
+ * compile time. The `_output` brand is phantom — it exists only in the
92
+ * type system for inference, not at runtime.
93
+ *
94
+ * Created via the {@linkcode middleware} factory. Attached to commands via
95
+ * `CommandBuilder.middleware()`.
96
+ *
97
+ * @example
98
+ * ```ts
99
+ * interface User { id: string; name: string }
100
+ *
101
+ * const auth = middleware<{ user: User }>(async ({ next }) => {
102
+ * const user = await getUser();
103
+ * if (!user) throw new CLIError('Not authenticated', { code: 'AUTH_REQUIRED' });
104
+ * return next({ user });
105
+ * });
106
+ * ```
107
+ */
108
+ type Middleware<Output extends Record<string, unknown>> = MiddlewareImpl & {
109
+ /** @internal Phantom type brand — compile-time only. */
110
+ readonly _output: Output;
111
+ };
112
+
113
+ // --- Factory
114
+
115
+ /**
116
+ * Create a middleware definition.
117
+ *
118
+ * Middleware runs before the action handler and can add typed context,
119
+ * short-circuit execution, or wrap downstream processing.
120
+ *
121
+ * @param handler - Function receiving `{ args, flags, ctx, out, meta, next }`.
122
+ * Call `next(additions)` to continue the chain with added context.
123
+ * Omitting the `next()` call short-circuits (e.g., for auth guards).
124
+ * @returns {@linkcode Middleware} to attach via `CommandBuilder.middleware()`.
125
+ *
126
+ * @example
127
+ * ```ts
128
+ * // Auth guard — adds user to context or throws
129
+ * const auth = middleware(async ({ next }) => {
130
+ * const user = await getUser();
131
+ * if (!user) throw new CLIError('Not authenticated', { code: 'AUTH_REQUIRED' });
132
+ * return next({ user });
133
+ * });
134
+ *
135
+ * // Timing wrapper — measures downstream execution
136
+ * const timing = middleware(async ({ out, next }) => {
137
+ * const start = Date.now();
138
+ * await next({});
139
+ * out.info(`Done in ${Date.now() - start}ms`);
140
+ * });
141
+ *
142
+ * command('deploy')
143
+ * .middleware(timing)
144
+ * .middleware(auth)
145
+ * .action(({ ctx }) => {
146
+ * console.log(ctx.user.name); // typed!
147
+ * });
148
+ * ```
149
+ */
150
+ function middleware<Output extends Record<string, unknown>>(
151
+ handler: MiddlewareHandler<Output>,
152
+ ): Middleware<Output> {
153
+ // Runtime representation is just { _handler }.
154
+ // The type assertion establishes the phantom _output brand —
155
+ // no runtime property is created. handler's Output-constrained
156
+ // next() is compatible with the erased (Record<string, unknown>)
157
+ // signature at runtime.
158
+ const impl: MiddlewareImpl = { _handler: handler as ErasedMiddlewareHandler };
159
+ return impl as Middleware<Output>;
160
+ }
161
+
162
+ // --- Exports
163
+
164
+ export type {
165
+ ErasedMiddlewareHandler,
166
+ Middleware,
167
+ MiddlewareHandler,
168
+ MiddlewareImpl,
169
+ MiddlewareParams,
170
+ };
171
+ export { middleware };
@@ -0,0 +1,156 @@
1
+ /**
2
+ * Prompt type definitions for interactive flag resolution.
3
+ *
4
+ * Prompt configuration is stored on `FlagSchema.prompt` and consumed by the
5
+ * resolution chain (v0.3+) when a flag value is missing after CLI/env/config
6
+ * resolution. The prompt engine reads this config to present the appropriate
7
+ * UI to the user.
8
+ *
9
+ * @module dreamcli/core/schema/prompt
10
+ */
11
+
12
+ // --- Prompt kind discriminator
13
+
14
+ /** All prompt kind discriminators as a runtime array. */
15
+ const PROMPT_KINDS = ['confirm', 'input', 'select', 'multiselect'] as const;
16
+
17
+ /**
18
+ * The kind of interactive prompt to present.
19
+ *
20
+ * - `'confirm'` — yes/no boolean question
21
+ * - `'input'` — free-text string input
22
+ * - `'select'` — single selection from a list
23
+ * - `'multiselect'` — multiple selections from a list
24
+ */
25
+ type PromptKind = (typeof PROMPT_KINDS)[number];
26
+
27
+ // --- Per-kind prompt configuration (discriminated union)
28
+
29
+ /** Shared fields across all prompt kinds. */
30
+ interface PromptConfigBase {
31
+ /** The question displayed to the user. */
32
+ readonly message: string;
33
+ }
34
+
35
+ /** Yes/no confirmation prompt — maps to `boolean` flags. Part of {@link PromptConfig}. */
36
+ interface ConfirmPromptConfig extends PromptConfigBase {
37
+ /** Discriminator identifying this as a yes/no confirmation prompt. */
38
+ readonly kind: 'confirm';
39
+ }
40
+
41
+ /** Free-text input prompt — maps to `string` and `number` flags. Part of {@link PromptConfig}. */
42
+ interface InputPromptConfig extends PromptConfigBase {
43
+ /** Discriminator identifying this as a free-text input prompt. */
44
+ readonly kind: 'input';
45
+ /** Placeholder text shown before user types (informational only). */
46
+ readonly placeholder?: string;
47
+ /**
48
+ * Inline validation function. Return `true` if valid, or a string
49
+ * error message if invalid. Called before coercion to flag kind.
50
+ */
51
+ readonly validate?: (value: string) => true | string;
52
+ }
53
+
54
+ /** Single-selection prompt — maps to `enum` flags or any flag with {@link SelectChoice choices}. Part of {@link PromptConfig}. */
55
+ interface SelectPromptConfig extends PromptConfigBase {
56
+ /** Discriminator identifying this as a single-selection prompt. */
57
+ readonly kind: 'select';
58
+ /**
59
+ * Available choices. When omitted for `enum` flags, the enum values
60
+ * from the flag schema are used automatically.
61
+ */
62
+ readonly choices?: readonly SelectChoice[];
63
+ }
64
+
65
+ /**
66
+ * Multi-selection prompt — maps to `array` flags.
67
+ * Returns an array of selected {@link SelectChoice} values. Part of {@link PromptConfig}.
68
+ */
69
+ interface MultiselectPromptConfig extends PromptConfigBase {
70
+ /** Discriminator identifying this as a multi-selection prompt. */
71
+ readonly kind: 'multiselect';
72
+ /**
73
+ * Available choices. When omitted for `array` flags with enum elements,
74
+ * the enum values from the element schema are used automatically.
75
+ */
76
+ readonly choices?: readonly SelectChoice[];
77
+ /**
78
+ * Minimum number of selections required.
79
+ * @defaultValue `0`
80
+ */
81
+ readonly min?: number;
82
+ /**
83
+ * Maximum number of selections allowed.
84
+ * @defaultValue `Infinity`
85
+ */
86
+ readonly max?: number;
87
+ }
88
+
89
+ // --- Supporting types
90
+
91
+ /** A selectable option for {@link SelectPromptConfig} and {@link MultiselectPromptConfig} prompts. */
92
+ interface SelectChoice {
93
+ /** The value returned when this choice is selected. */
94
+ readonly value: string;
95
+ /**
96
+ * Display label shown to the user.
97
+ * @defaultValue {@link SelectChoice.value | value}
98
+ */
99
+ readonly label?: string;
100
+ /** Optional description shown alongside the choice. */
101
+ readonly description?: string;
102
+ }
103
+
104
+ /**
105
+ * Discriminated union of all prompt configurations.
106
+ *
107
+ * Use the `kind` field to narrow:
108
+ * ```ts
109
+ * if (config.kind === 'select') {
110
+ * config.choices // readonly SelectChoice[] | undefined
111
+ * }
112
+ * ```
113
+ */
114
+ type PromptConfig =
115
+ | ConfirmPromptConfig
116
+ | InputPromptConfig
117
+ | SelectPromptConfig
118
+ | MultiselectPromptConfig;
119
+
120
+ // --- Prompt result
121
+
122
+ /**
123
+ * The raw result returned by a prompt engine for a single prompt.
124
+ *
125
+ * - `answered: true` — user provided a value
126
+ * - `answered: false` — user cancelled/aborted (Ctrl+C, ESC, etc.)
127
+ *
128
+ * Coercion to the flag's kind is the resolver's responsibility, not the
129
+ * prompt engine's.
130
+ */
131
+ type PromptResult =
132
+ | {
133
+ /** User provided a value. */
134
+ readonly answered: true;
135
+ /** The raw value from the prompt engine (not yet coerced). */
136
+ readonly value: unknown;
137
+ }
138
+ | {
139
+ /** User cancelled or aborted (Ctrl+C, ESC, etc.). */
140
+ readonly answered: false;
141
+ };
142
+
143
+ // --- Exports
144
+
145
+ export type {
146
+ ConfirmPromptConfig,
147
+ InputPromptConfig,
148
+ MultiselectPromptConfig,
149
+ PromptConfig,
150
+ PromptConfigBase,
151
+ PromptKind,
152
+ PromptResult,
153
+ SelectChoice,
154
+ SelectPromptConfig,
155
+ };
156
+ export { PROMPT_KINDS };
@@ -0,0 +1,195 @@
1
+ /**
2
+ * Run result type — structured output from command execution.
3
+ *
4
+ * Lives in schema (not testkit) because it describes the execution contract
5
+ * that `ErasedCommand._execute` returns. Both schema and testkit layers
6
+ * reference it without dependency inversion.
7
+ *
8
+ * @module dreamcli/core/schema/run
9
+ */
10
+
11
+ import type { CLIPlugin } from '#internals/core/cli/plugin.ts';
12
+ import type { CLIError } from '#internals/core/errors/index.ts';
13
+ import type { HelpOptions } from '#internals/core/help/index.ts';
14
+ import type { CapturedOutput, Verbosity } from '#internals/core/output/index.ts';
15
+ import type { PromptEngine, TestAnswer } from '#internals/core/prompt/index.ts';
16
+ import type { ActivityEvent } from './activity.ts';
17
+ import type { CommandMeta, CommandSchema, Out } from './command.ts';
18
+
19
+ /**
20
+ * Options accepted by `runCommand()` and internal command execution paths.
21
+ *
22
+ * Every field is optional — sensible defaults are applied. This is the
23
+ * primary process-free execution seam: inject env, config, prompt I/O, and
24
+ * dispatch-layer metadata without touching process state.
25
+ */
26
+ export interface RunOptions {
27
+ /**
28
+ * Environment variables for flag resolution.
29
+ *
30
+ * Flags with `.env('VAR')` configured resolve from this record
31
+ * when no CLI value is provided (CLI → env → config → prompt → default).
32
+ */
33
+ readonly env?: Readonly<Record<string, string | undefined>>;
34
+
35
+ /**
36
+ * Configuration object for flag resolution.
37
+ *
38
+ * Flags with `.config('path')` configured resolve from this record
39
+ * when no CLI or env value is provided (CLI → env → config → prompt → default).
40
+ * Config is plain JSON — file loading is the caller's responsibility.
41
+ */
42
+ readonly config?: Readonly<Record<string, unknown>>;
43
+
44
+ /**
45
+ * Full stdin contents for args configured with `.stdin()`.
46
+ *
47
+ * Lets tests inject piped input without a runtime adapter.
48
+ */
49
+ readonly stdinData?: string | null;
50
+
51
+ /**
52
+ * Prompt engine for interactive flag resolution.
53
+ *
54
+ * When provided, flags with `.prompt()` configured that have no value
55
+ * after CLI/env/config resolution will be prompted interactively.
56
+ *
57
+ * When absent (and `answers` is also absent), prompting is skipped
58
+ * and resolution falls through to default/required.
59
+ *
60
+ * Takes precedence over `answers` when both are provided.
61
+ */
62
+ readonly prompter?: PromptEngine;
63
+
64
+ /**
65
+ * Pre-configured prompt answers for testing convenience.
66
+ *
67
+ * When provided, a test prompter is created from these answers via
68
+ * `createTestPrompter(answers)`. Each entry is consumed in order —
69
+ * use `PROMPT_CANCEL` to simulate cancellation.
70
+ *
71
+ * Ignored when an explicit `prompter` is provided.
72
+ */
73
+ readonly answers?: readonly TestAnswer[];
74
+
75
+ /**
76
+ * Verbosity level for the output channel.
77
+ * @defaultValue `'normal'`
78
+ */
79
+ readonly verbosity?: Verbosity;
80
+
81
+ /**
82
+ * Enable JSON output mode.
83
+ *
84
+ * When `true`, `log` and `info` messages are redirected to stderr
85
+ * so that stdout is reserved exclusively for structured {@linkcode Out.json | json()} output.
86
+ * Framework-rendered errors are emitted as structured JSON to stdout.
87
+ *
88
+ * @defaultValue `false`
89
+ */
90
+ readonly jsonMode?: boolean;
91
+
92
+ /**
93
+ * Whether stdout is connected to a TTY.
94
+ *
95
+ * Handlers can check {@linkcode Out.isTTY | out.isTTY} to decide whether to emit decorative
96
+ * output (spinners, progress bars, ANSI codes). Defaults to `false`
97
+ * (safe default for tests — non-TTY until proven otherwise).
98
+ *
99
+ * @defaultValue `false`
100
+ */
101
+ readonly isTTY?: boolean;
102
+
103
+ /**
104
+ * Output channel override used by live CLI execution.
105
+ *
106
+ * @internal — `CLIBuilder.run()` passes a real output channel so activity renders to
107
+ * the terminal instead of being captured.
108
+ */
109
+ readonly out?: Out;
110
+
111
+ /**
112
+ * Capture buffers override paired with `out`.
113
+ *
114
+ * @internal — when omitted, `runCommand()` creates empty buffers for the
115
+ * returned {@linkcode RunResult} while writing directly to the provided `out`.
116
+ */
117
+ readonly captured?: CapturedOutput;
118
+
119
+ /**
120
+ * Help formatting options (width, binName).
121
+ * Used when `--help` is detected.
122
+ */
123
+ readonly help?: HelpOptions;
124
+
125
+ /**
126
+ * Command schema with propagated flags merged in.
127
+ *
128
+ * When provided, used for parsing and resolution instead of `cmd.schema`.
129
+ * Set by the CLI dispatch layer after collecting propagated flags from
130
+ * the command ancestry path.
131
+ *
132
+ * @internal — set by dispatch layer, not for public use.
133
+ */
134
+ readonly mergedSchema?: CommandSchema;
135
+
136
+ /**
137
+ * CLI program metadata passed to action handlers and middleware.
138
+ *
139
+ * When provided (by CLI dispatch layer), handlers receive this as `meta`.
140
+ * When absent (standalone `runCommand()`), a minimal meta is constructed
141
+ * from the command's own schema.
142
+ *
143
+ * @internal — populated by CLI dispatch, not for public use.
144
+ */
145
+ readonly meta?: CommandMeta;
146
+
147
+ /**
148
+ * CLI plugins registered on the parent `CLIBuilder`.
149
+ *
150
+ * @internal — threaded through from CLI dispatch.
151
+ */
152
+ readonly plugins?: readonly CLIPlugin[];
153
+ }
154
+
155
+ /**
156
+ * Structured result from {@linkcode runCommand}.
157
+ *
158
+ * Contains the exit code, captured stdout/stderr output, recorded
159
+ * {@linkcode ActivityEvent | activity events}, and an `error` field
160
+ * that is `undefined` on success and a {@linkcode CLIError} on failure.
161
+ *
162
+ * @example
163
+ * ```ts
164
+ * const result = await runCommand(greetCmd, ['World']);
165
+ *
166
+ * expect(result.exitCode).toBe(0);
167
+ * expect(result.stdout).toContain('Hello, World!');
168
+ * expect(result.error).toBeUndefined();
169
+ * ```
170
+ */
171
+ export interface RunResult {
172
+ /** Process exit code. 0 = success. */
173
+ readonly exitCode: number;
174
+
175
+ /** Captured stdout lines (from `out.log` and `out.info`). */
176
+ readonly stdout: readonly string[];
177
+
178
+ /** Captured stderr lines (from `out.warn` and `out.error`). */
179
+ readonly stderr: readonly string[];
180
+
181
+ /**
182
+ * Captured spinner and progress lifecycle events.
183
+ *
184
+ * Recorded separately from stdout/stderr — handlers that call
185
+ * {@linkcode Out.spinner | out.spinner()} or {@linkcode Out.progress | out.progress()} produce events here, enabling
186
+ * targeted assertions on activity lifecycle without parsing text.
187
+ */
188
+ readonly activity: readonly ActivityEvent[];
189
+
190
+ /**
191
+ * The error that caused a non-zero exit, or `undefined` on success.
192
+ * {@linkcode CLIError} instances are preserved; unknown errors are wrapped.
193
+ */
194
+ readonly error: CLIError | undefined;
195
+ }