@kjanat/dreamcli 1.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 (217) hide show
  1. package/CHANGELOG.md +45 -6
  2. package/LICENSE +1 -1
  3. package/README.md +296 -164
  4. package/dist/core/cli/dispatch.d.mts +85 -0
  5. package/dist/core/cli/dispatch.mjs +1 -0
  6. package/dist/core/cli/index.d.mts +418 -0
  7. package/dist/core/cli/index.mjs +1 -0
  8. package/dist/core/cli/planner.d.mts +143 -0
  9. package/dist/core/cli/planner.mjs +1 -0
  10. package/dist/core/cli/plugin.d.mts +94 -0
  11. package/dist/core/cli/plugin.mjs +1 -0
  12. package/dist/core/cli/propagate.d.mts +39 -0
  13. package/dist/core/cli/propagate.mjs +1 -0
  14. package/dist/core/cli/root-help.d.mts +28 -0
  15. package/dist/core/cli/root-help.mjs +7 -0
  16. package/dist/core/cli/root-surface.d.mts +42 -0
  17. package/dist/core/cli/root-surface.mjs +1 -0
  18. package/dist/core/cli/runtime-preflight.d.mts +149 -0
  19. package/dist/core/cli/runtime-preflight.mjs +1 -0
  20. package/dist/core/completion/index.d.mts +46 -0
  21. package/dist/core/completion/index.mjs +1 -0
  22. package/dist/core/completion/shells/bash.d.mts +24 -0
  23. package/dist/core/completion/shells/bash.mjs +3 -0
  24. package/dist/core/completion/shells/fish.d.mts +20 -0
  25. package/dist/core/completion/shells/fish.mjs +2 -0
  26. package/dist/core/completion/shells/powershell.d.mts +14 -0
  27. package/dist/core/completion/shells/powershell.mjs +2 -0
  28. package/dist/core/completion/shells/shared.d.mts +139 -0
  29. package/dist/core/completion/shells/shared.mjs +1 -0
  30. package/dist/core/completion/shells/zsh.d.mts +24 -0
  31. package/dist/core/completion/shells/zsh.mjs +2 -0
  32. package/dist/core/config/index.d.mts +161 -0
  33. package/dist/core/config/index.mjs +1 -0
  34. package/dist/core/config/package-json.d.mts +68 -0
  35. package/dist/core/config/package-json.mjs +1 -0
  36. package/dist/core/errors/index.d.mts +126 -0
  37. package/dist/core/errors/index.mjs +1 -0
  38. package/dist/core/execution/index.d.mts +49 -0
  39. package/dist/core/execution/index.mjs +1 -0
  40. package/dist/core/help/index.d.mts +49 -0
  41. package/dist/core/help/index.mjs +8 -0
  42. package/dist/core/json-schema/index.d.mts +109 -0
  43. package/dist/core/json-schema/index.mjs +55 -0
  44. package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
  45. package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
  46. package/dist/core/output/activity.d.mts +194 -0
  47. package/dist/core/output/activity.mjs +1 -0
  48. package/dist/core/output/contracts.d.mts +88 -0
  49. package/dist/core/output/contracts.mjs +1 -0
  50. package/dist/core/output/display-value.d.mts +19 -0
  51. package/dist/core/output/display-value.mjs +1 -0
  52. package/dist/core/output/index.d.mts +280 -0
  53. package/dist/core/output/index.mjs +2 -0
  54. package/dist/core/output/renderers.d.mts +46 -0
  55. package/dist/core/output/renderers.mjs +1 -0
  56. package/dist/core/output/writer.d.mts +40 -0
  57. package/dist/core/output/writer.mjs +1 -0
  58. package/dist/core/parse/index.d.mts +79 -0
  59. package/dist/core/parse/index.mjs +1 -0
  60. package/dist/core/prompt/index.d.mts +205 -0
  61. package/dist/core/prompt/index.mjs +6 -0
  62. package/dist/core/resolve/args.d.mts +8 -0
  63. package/dist/core/resolve/args.mjs +1 -0
  64. package/dist/core/resolve/coerce.d.mts +22 -0
  65. package/dist/core/resolve/coerce.mjs +1 -0
  66. package/dist/core/resolve/config.d.mts +10 -0
  67. package/dist/core/resolve/config.mjs +1 -0
  68. package/dist/core/resolve/contracts.d.mts +112 -0
  69. package/dist/core/resolve/errors.d.mts +11 -0
  70. package/dist/core/resolve/errors.mjs +2 -0
  71. package/dist/core/resolve/flags.d.mts +10 -0
  72. package/dist/core/resolve/flags.mjs +1 -0
  73. package/dist/core/resolve/index.d.mts +42 -0
  74. package/dist/core/resolve/index.mjs +1 -0
  75. package/dist/core/resolve/property.d.mts +47 -0
  76. package/dist/core/resolve/property.mjs +1 -0
  77. package/dist/core/schema/activity.d.mts +169 -0
  78. package/dist/core/schema/arg.d.mts +559 -0
  79. package/dist/core/schema/arg.mjs +1 -0
  80. package/dist/core/schema/command.d.mts +960 -0
  81. package/dist/core/schema/command.mjs +1 -0
  82. package/dist/core/schema/flag.d.mts +491 -0
  83. package/dist/core/schema/flag.mjs +1 -0
  84. package/dist/core/schema/index.d.mts +8 -0
  85. package/dist/core/schema/middleware.d.mts +122 -0
  86. package/dist/core/schema/middleware.mjs +1 -0
  87. package/dist/core/schema/prompt.d.mts +117 -0
  88. package/dist/core/schema/run.d.mts +171 -0
  89. package/dist/core/schema-dsl/runtime.d.mts +144 -0
  90. package/dist/core/schema-dsl/runtime.mjs +2 -0
  91. package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
  92. package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
  93. package/dist/core/testkit/index.d.mts +54 -0
  94. package/dist/core/testkit/index.mjs +1 -0
  95. package/dist/index.d.mts +28 -920
  96. package/dist/index.mjs +1 -10
  97. package/dist/runtime/adapter.d.mts +212 -0
  98. package/dist/{adapter-B37d9oia.mjs → runtime/adapter.mjs} +1 -1
  99. package/dist/runtime/auto.d.mts +26 -0
  100. package/dist/runtime/auto.mjs +1 -0
  101. package/dist/runtime/bun.d.mts +28 -0
  102. package/dist/runtime/bun.mjs +1 -0
  103. package/dist/runtime/deno.d.mts +76 -0
  104. package/dist/runtime/deno.mjs +2 -0
  105. package/dist/runtime/detect.d.mts +86 -0
  106. package/dist/runtime/detect.mjs +1 -0
  107. package/dist/runtime/index.d.mts +7 -0
  108. package/dist/runtime/node.d.mts +65 -0
  109. package/dist/runtime/node.mjs +2 -0
  110. package/dist/runtime/paths.d.mts +31 -0
  111. package/dist/runtime/paths.mjs +1 -0
  112. package/dist/runtime/support.d.mts +42 -0
  113. package/dist/runtime/support.mjs +1 -0
  114. package/dist/runtime.d.mts +6 -252
  115. package/dist/runtime.mjs +1 -1
  116. package/dist/testkit.d.mts +5 -24
  117. package/dist/testkit.mjs +1 -1
  118. package/dist/version.d.mts +16 -0
  119. package/dist/version.mjs +1 -0
  120. package/dreamcli.schema.json +338 -0
  121. package/examples/basic.ts +2 -2
  122. package/examples/gh/package.json +7 -11
  123. package/examples/gh/src/commands/auth.ts +2 -2
  124. package/examples/gh/src/commands/issue.ts +4 -4
  125. package/examples/gh/src/commands/pr.ts +4 -4
  126. package/examples/gh/src/docs.ts +11 -0
  127. package/examples/gh/src/lib/auth.ts +1 -1
  128. package/examples/gh/src/main.test.ts +6 -5
  129. package/examples/gh/src/main.ts +8 -6
  130. package/examples/interactive.ts +3 -3
  131. package/examples/json-mode.ts +4 -6
  132. package/examples/middleware.ts +3 -3
  133. package/examples/multi-command.ts +3 -3
  134. package/examples/spinner-progress.ts +5 -5
  135. package/examples/testing.ts +8 -6
  136. package/package.json +70 -44
  137. package/src/core/cli/dispatch.ts +4 -0
  138. package/src/core/cli/index.ts +185 -632
  139. package/src/core/cli/planner.ts +413 -0
  140. package/src/core/cli/plugin.ts +7 -1
  141. package/src/core/cli/propagate.ts +1 -1
  142. package/src/core/cli/runtime-preflight.ts +409 -0
  143. package/src/core/completion/index.ts +15 -9
  144. package/src/core/completion/shells/bash.ts +6 -3
  145. package/src/core/completion/shells/fish.ts +245 -10
  146. package/src/core/completion/shells/powershell.ts +390 -9
  147. package/src/core/completion/shells/shared.ts +4 -4
  148. package/src/core/completion/shells/zsh.ts +12 -7
  149. package/src/core/config/index.ts +7 -4
  150. package/src/core/config/package-json.ts +6 -2
  151. package/src/core/errors/index.ts +23 -8
  152. package/src/core/execution/index.ts +270 -0
  153. package/src/core/help/index.ts +13 -15
  154. package/src/core/json-schema/index.ts +193 -7
  155. package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
  156. package/src/core/output/contracts.ts +194 -0
  157. package/src/core/output/index.ts +47 -82
  158. package/src/core/output/renderers.ts +125 -0
  159. package/src/core/parse/index.ts +39 -21
  160. package/src/core/prompt/index.ts +44 -27
  161. package/src/core/resolve/args.ts +144 -0
  162. package/src/core/resolve/coerce.ts +432 -0
  163. package/src/core/resolve/config.ts +26 -0
  164. package/src/core/resolve/contracts.ts +135 -0
  165. package/src/core/resolve/errors.ts +227 -0
  166. package/src/core/resolve/flags.ts +205 -0
  167. package/src/core/resolve/index.ts +41 -1264
  168. package/src/core/resolve/property.ts +99 -0
  169. package/src/core/schema/activity.ts +3 -0
  170. package/src/core/schema/arg.ts +26 -14
  171. package/src/core/schema/command.ts +265 -38
  172. package/src/core/schema/flag.ts +120 -15
  173. package/src/core/schema/index.ts +11 -2
  174. package/src/core/schema/middleware.ts +6 -6
  175. package/src/core/schema/prompt.ts +9 -1
  176. package/src/core/schema/run.ts +25 -17
  177. package/src/core/schema-dsl/index.ts +109 -0
  178. package/src/core/schema-dsl/parse.ts +262 -0
  179. package/src/core/schema-dsl/runtime.ts +609 -0
  180. package/src/core/schema-dsl/to-json-schema.ts +102 -0
  181. package/src/core/testkit/index.ts +55 -297
  182. package/src/index.ts +10 -4
  183. package/src/runtime/adapter.ts +13 -10
  184. package/src/runtime/auto.ts +3 -3
  185. package/src/runtime/bun.ts +4 -4
  186. package/src/runtime/deno.ts +43 -29
  187. package/src/runtime/detect.ts +4 -1
  188. package/src/runtime/index.ts +1 -1
  189. package/src/runtime/node.ts +43 -21
  190. package/src/runtime/paths.ts +9 -3
  191. package/src/runtime/support.ts +20 -4
  192. package/src/runtime.ts +1 -1
  193. package/src/testkit.ts +10 -8
  194. package/dist/adapter-CCSh5juX.cjs +0 -1
  195. package/dist/adapter-DIwO-q7K.d.mts +0 -3447
  196. package/dist/adapter-DQnxxLiE.d.cts +0 -3447
  197. package/dist/auto-5cjZaF9V.mjs +0 -3
  198. package/dist/auto-B0eSgoDw.cjs +0 -3
  199. package/dist/index.cjs +0 -10
  200. package/dist/index.d.cts +0 -920
  201. package/dist/runtime.cjs +0 -1
  202. package/dist/runtime.d.cts +0 -253
  203. package/dist/testkit-CEDYPvhF.mjs +0 -14
  204. package/dist/testkit-ClIKijxC.cjs +0 -14
  205. package/dist/testkit.cjs +0 -1
  206. package/dist/testkit.d.cts +0 -25
  207. package/examples/gh/tsconfig.json +0 -37
  208. package/examples/tsconfig.json +0 -17
  209. package/src/core/cli/AGENTS.md +0 -72
  210. package/src/core/completion/AGENTS.md +0 -72
  211. package/src/core/completion/completion-test-helpers.ts +0 -48
  212. package/src/core/output/AGENTS.md +0 -69
  213. package/src/core/resolve/AGENTS.md +0 -69
  214. package/src/core/schema/AGENTS.md +0 -61
  215. package/src/core/testkit/AGENTS.md +0 -55
  216. package/src/runtime/AGENTS.md +0 -74
  217. package/src/runtime/test-helpers.ts +0 -40
@@ -0,0 +1,227 @@
1
+ /**
2
+ * Internal resolver error helpers.
3
+ *
4
+ * Keeps validation aggregation and nested-error flattening separate from
5
+ * resolution orchestration.
6
+ *
7
+ * @module dreamcli/core/resolve/errors
8
+ * @internal
9
+ */
10
+
11
+ import type { ValidationErrorCode } from '#internals/core/errors/index.ts';
12
+ import { ValidationError } from '#internals/core/errors/index.ts';
13
+
14
+ type AggregateIssueSourceKind = 'env' | 'config' | 'stdin' | 'prompt';
15
+
16
+ interface AggregateIssueSummary {
17
+ readonly code: ValidationErrorCode;
18
+ readonly inputKind: 'flag' | 'arg' | 'input';
19
+ readonly name?: string;
20
+ readonly label: string;
21
+ readonly message: string;
22
+ readonly sourceKind?: AggregateIssueSourceKind;
23
+ readonly sourceLabel?: string;
24
+ }
25
+
26
+ function isRecord(value: unknown): value is Record<string, unknown> {
27
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
28
+ }
29
+
30
+ function readStringProperty(record: object, key: string): string | undefined {
31
+ const value = Reflect.get(record, key);
32
+ return typeof value === 'string' ? value : undefined;
33
+ }
34
+
35
+ function hasValueProperty(record: object, key: string): boolean {
36
+ return Object.hasOwn(record, key);
37
+ }
38
+
39
+ function describeIssueSource(
40
+ details: object,
41
+ ): { readonly kind: AggregateIssueSourceKind; readonly label: string } | undefined {
42
+ const explicitSource = readStringProperty(details, 'source');
43
+ if (explicitSource === 'stdin') {
44
+ return { kind: 'stdin', label: 'stdin' };
45
+ }
46
+
47
+ if (explicitSource === 'prompt') {
48
+ return { kind: 'prompt', label: 'prompt' };
49
+ }
50
+
51
+ if (hasValueProperty(details, 'value')) {
52
+ const envVar = readStringProperty(details, 'envVar');
53
+ if (envVar !== undefined) {
54
+ return { kind: 'env', label: `env ${envVar}` };
55
+ }
56
+
57
+ const configPath = readStringProperty(details, 'configPath');
58
+ if (configPath !== undefined) {
59
+ return { kind: 'config', label: `config ${configPath}` };
60
+ }
61
+ }
62
+
63
+ return undefined;
64
+ }
65
+
66
+ function summarizeValidationError(error: ValidationError): AggregateIssueSummary {
67
+ const details = error.details;
68
+ if (!isRecord(details)) {
69
+ return {
70
+ code: error.code,
71
+ inputKind: 'input',
72
+ label: 'input',
73
+ message: error.message,
74
+ };
75
+ }
76
+
77
+ const flag = readStringProperty(details, 'flag');
78
+ if (flag !== undefined) {
79
+ const source = describeIssueSource(details);
80
+ return {
81
+ code: error.code,
82
+ inputKind: 'flag',
83
+ name: flag,
84
+ label: `flag --${flag}`,
85
+ message: error.message,
86
+ ...(source !== undefined ? { sourceKind: source.kind, sourceLabel: source.label } : {}),
87
+ };
88
+ }
89
+
90
+ const arg = readStringProperty(details, 'arg');
91
+ if (arg !== undefined) {
92
+ const source = describeIssueSource(details);
93
+ return {
94
+ code: error.code,
95
+ inputKind: 'arg',
96
+ name: arg,
97
+ label: `argument <${arg}>`,
98
+ message: error.message,
99
+ ...(source !== undefined ? { sourceKind: source.kind, sourceLabel: source.label } : {}),
100
+ };
101
+ }
102
+
103
+ return {
104
+ code: error.code,
105
+ inputKind: 'input',
106
+ label: 'input',
107
+ message: error.message,
108
+ };
109
+ }
110
+
111
+ function formatAggregateHeadline(issues: readonly AggregateIssueSummary[]): string {
112
+ const flagCount = issues.filter((issue) => issue.inputKind === 'flag').length;
113
+ const argCount = issues.filter((issue) => issue.inputKind === 'arg').length;
114
+ const otherCount = issues.length - flagCount - argCount;
115
+ const counts: string[] = [];
116
+
117
+ if (flagCount > 0) {
118
+ counts.push(`${flagCount} flag${flagCount === 1 ? '' : 's'}`);
119
+ }
120
+
121
+ if (argCount > 0) {
122
+ counts.push(`${argCount} arg${argCount === 1 ? '' : 's'}`);
123
+ }
124
+
125
+ if (otherCount > 0) {
126
+ counts.push(`${otherCount} input${otherCount === 1 ? '' : 's'}`);
127
+ }
128
+
129
+ return counts.length === 0
130
+ ? `Multiple validation errors (${issues.length})`
131
+ : `Multiple validation errors (${counts.join(', ')})`;
132
+ }
133
+
134
+ function formatAggregateLine(issue: AggregateIssueSummary): string {
135
+ const source = issue.sourceLabel !== undefined ? ` [${issue.sourceLabel}]` : '';
136
+ return `${issue.label}${source}: ${issue.message}`;
137
+ }
138
+
139
+ /** Type-narrowing guard that asserts a readonly array has at least one element. */
140
+ function isNonEmpty<T>(arr: readonly T[]): arr is readonly [T, ...T[]] {
141
+ return arr.length > 0;
142
+ }
143
+
144
+ function isValidationErrorJson(value: unknown): value is {
145
+ readonly code: ValidationErrorCode;
146
+ readonly message: string;
147
+ readonly exitCode: number;
148
+ readonly suggest?: string;
149
+ readonly details?: Readonly<Record<string, unknown>>;
150
+ } {
151
+ if (value === null || typeof value !== 'object') {
152
+ return false;
153
+ }
154
+
155
+ if (!('code' in value) || !('message' in value) || !('exitCode' in value)) {
156
+ return false;
157
+ }
158
+
159
+ if (typeof value.code !== 'string' || typeof value.message !== 'string') {
160
+ return false;
161
+ }
162
+
163
+ if (typeof value.exitCode !== 'number') {
164
+ return false;
165
+ }
166
+
167
+ if ('suggest' in value && value.suggest !== undefined && typeof value.suggest !== 'string') {
168
+ return false;
169
+ }
170
+
171
+ if (
172
+ 'details' in value &&
173
+ value.details !== undefined &&
174
+ (value.details === null || typeof value.details !== 'object')
175
+ ) {
176
+ return false;
177
+ }
178
+
179
+ return true;
180
+ }
181
+
182
+ /** Flatten an aggregate validation error's nested `details.errors` into individual errors, or return the original as a singleton. */
183
+ function collectValidationErrors(error: ValidationError): readonly ValidationError[] {
184
+ const nestedErrors = error.details?.errors;
185
+ if (!Array.isArray(nestedErrors)) {
186
+ return [error];
187
+ }
188
+
189
+ const flattened: ValidationError[] = [];
190
+ for (const entry of nestedErrors) {
191
+ if (!isValidationErrorJson(entry)) {
192
+ return [error];
193
+ }
194
+
195
+ flattened.push(
196
+ new ValidationError(entry.message, {
197
+ code: entry.code,
198
+ exitCode: entry.exitCode,
199
+ ...(entry.suggest !== undefined ? { suggest: entry.suggest } : {}),
200
+ ...(entry.details !== undefined ? { details: entry.details } : {}),
201
+ }),
202
+ );
203
+ }
204
+
205
+ return flattened;
206
+ }
207
+
208
+ /** Throw a single error if one, or an aggregate with per-issue summaries if many. */
209
+ function throwAggregatedErrors(errors: readonly [ValidationError, ...ValidationError[]]): never {
210
+ if (errors.length === 1) {
211
+ throw errors[0];
212
+ }
213
+
214
+ const issues = errors.map(summarizeValidationError);
215
+ const lines = issues.map(formatAggregateLine);
216
+ throw new ValidationError(`${formatAggregateHeadline(issues)}:\n - ${lines.join('\n - ')}`, {
217
+ code: errors[0].code,
218
+ details: {
219
+ errors: errors.map((error) => error.toJSON()),
220
+ count: errors.length,
221
+ issues,
222
+ },
223
+ suggest: 'Fix the listed validation errors and retry',
224
+ });
225
+ }
226
+
227
+ export { collectValidationErrors, isNonEmpty, throwAggregatedErrors };
@@ -0,0 +1,205 @@
1
+ /**
2
+ * Internal flag resolution helpers.
3
+ *
4
+ * @module dreamcli/core/resolve/flags
5
+ * @internal
6
+ */
7
+
8
+ import { ValidationError } from '#internals/core/errors/index.ts';
9
+ import type { PromptEngine } from '#internals/core/prompt/index.ts';
10
+ import { resolvePromptConfig } from '#internals/core/prompt/index.ts';
11
+ import type { ErasedInteractiveResolver, FlagSchema } from '#internals/core/schema/index.ts';
12
+ import type { PromptConfig } from '#internals/core/schema/prompt.ts';
13
+ import { coerceValue } from './coerce.ts';
14
+ import { resolveConfigPath } from './config.ts';
15
+ import type { DeprecationWarning } from './contracts.ts';
16
+ import { isNonEmpty, throwAggregatedErrors } from './errors.ts';
17
+
18
+ type PromptResolveResult =
19
+ | { readonly ok: true; readonly value: unknown }
20
+ | { readonly ok: false; readonly error: ValidationError | undefined };
21
+
22
+ /** Walk every declared flag through the resolution chain (cli -> env -> config -> prompt -> default), collecting deprecations and throwing aggregated errors. */
23
+ async function resolveFlags(
24
+ flagSchemas: Readonly<Record<string, FlagSchema>>,
25
+ parsedFlags: Readonly<Record<string, unknown>>,
26
+ env: Readonly<Record<string, string | undefined>>,
27
+ config: Readonly<Record<string, unknown>>,
28
+ prompter: PromptEngine | undefined,
29
+ interactive: ErasedInteractiveResolver | undefined,
30
+ deprecations: DeprecationWarning[],
31
+ ): Promise<Readonly<Record<string, unknown>>> {
32
+ const resolved: Record<string, unknown> = {};
33
+ const errors: ValidationError[] = [];
34
+ const hardErrorFlags = new Set<string>();
35
+
36
+ for (const [name, schema] of Object.entries(flagSchemas)) {
37
+ const hasParsedValue = Object.hasOwn(parsedFlags, name);
38
+ const parsedValue = parsedFlags[name];
39
+
40
+ if (hasParsedValue && parsedValue !== undefined) {
41
+ if (schema.deprecated !== undefined) {
42
+ deprecations.push({ kind: 'flag', name, message: schema.deprecated });
43
+ }
44
+ resolved[name] = parsedValue;
45
+ continue;
46
+ }
47
+
48
+ if (schema.envVar !== undefined) {
49
+ const envValue = env[schema.envVar];
50
+ if (envValue !== undefined) {
51
+ const coerced = coerceValue(name, { kind: 'env', envVar: schema.envVar }, envValue, schema);
52
+ if (coerced.ok) {
53
+ if (schema.deprecated !== undefined) {
54
+ deprecations.push({ kind: 'flag', name, message: schema.deprecated });
55
+ }
56
+ resolved[name] = coerced.value;
57
+ continue;
58
+ }
59
+ errors.push(coerced.error);
60
+ hardErrorFlags.add(name);
61
+ continue;
62
+ }
63
+ }
64
+
65
+ if (schema.configPath !== undefined) {
66
+ const configValue = resolveConfigPath(config, schema.configPath);
67
+ if (configValue !== undefined) {
68
+ const coerced = coerceValue(
69
+ name,
70
+ { kind: 'config', configPath: schema.configPath },
71
+ configValue,
72
+ schema,
73
+ );
74
+ if (coerced.ok) {
75
+ if (schema.deprecated !== undefined) {
76
+ deprecations.push({ kind: 'flag', name, message: schema.deprecated });
77
+ }
78
+ resolved[name] = coerced.value;
79
+ continue;
80
+ }
81
+ errors.push(coerced.error);
82
+ hardErrorFlags.add(name);
83
+ }
84
+ }
85
+ }
86
+
87
+ const interactiveConfigs =
88
+ interactive !== undefined ? interactive({ flags: resolved }) : undefined;
89
+
90
+ for (const [name, schema] of Object.entries(flagSchemas)) {
91
+ if (Object.hasOwn(resolved, name) || hardErrorFlags.has(name)) {
92
+ continue;
93
+ }
94
+
95
+ const interactiveConfig = interactiveConfigs?.[name];
96
+
97
+ let effectivePromptConfig: PromptConfig | undefined;
98
+ // `interactiveConfig === false` explicitly disables prompts for this flag.
99
+ // Other falsy values mean "no override", so we fall back to `schema.prompt`.
100
+ if (
101
+ interactiveConfig !== undefined &&
102
+ interactiveConfig !== null &&
103
+ interactiveConfig !== false &&
104
+ interactiveConfig !== 0 &&
105
+ interactiveConfig !== ''
106
+ ) {
107
+ effectivePromptConfig = interactiveConfig;
108
+ } else if (interactiveConfig === false) {
109
+ effectivePromptConfig = undefined;
110
+ } else {
111
+ effectivePromptConfig = schema.prompt;
112
+ }
113
+
114
+ if (effectivePromptConfig !== undefined && prompter !== undefined) {
115
+ const promptResult = await resolvePromptValueWithConfig(
116
+ name,
117
+ schema,
118
+ effectivePromptConfig,
119
+ prompter,
120
+ );
121
+ if (promptResult.ok) {
122
+ if (schema.deprecated !== undefined) {
123
+ deprecations.push({ kind: 'flag', name, message: schema.deprecated });
124
+ }
125
+ resolved[name] = promptResult.value;
126
+ continue;
127
+ }
128
+ if (promptResult.error !== undefined) {
129
+ errors.push(promptResult.error);
130
+ continue;
131
+ }
132
+ }
133
+
134
+ if (schema.defaultValue !== undefined) {
135
+ resolved[name] = schema.defaultValue;
136
+ continue;
137
+ }
138
+
139
+ if (schema.kind === 'array' && schema.presence !== 'required') {
140
+ resolved[name] = [];
141
+ continue;
142
+ }
143
+
144
+ if (schema.presence === 'required') {
145
+ const details: Record<string, unknown> = { flag: name, kind: schema.kind };
146
+ if (schema.envVar !== undefined) details.envVar = schema.envVar;
147
+ if (schema.configPath !== undefined) details.configPath = schema.configPath;
148
+ errors.push(
149
+ new ValidationError(`Missing required flag --${name}`, {
150
+ code: 'REQUIRED_FLAG',
151
+ details,
152
+ suggest: buildRequiredFlagSuggest(name, schema),
153
+ }),
154
+ );
155
+ continue;
156
+ }
157
+
158
+ resolved[name] = undefined;
159
+ }
160
+
161
+ if (isNonEmpty(errors)) {
162
+ throwAggregatedErrors(errors);
163
+ }
164
+
165
+ return resolved;
166
+ }
167
+
168
+ async function resolvePromptValueWithConfig(
169
+ flagName: string,
170
+ schema: FlagSchema,
171
+ promptConfig: PromptConfig,
172
+ prompter: PromptEngine,
173
+ ): Promise<PromptResolveResult> {
174
+ const resolvedConfig = resolvePromptConfig(promptConfig, schema.enumValues);
175
+ const result = await prompter.promptOne(resolvedConfig);
176
+
177
+ if (!result.answered) {
178
+ return { ok: false, error: undefined };
179
+ }
180
+
181
+ return coerceValue(flagName, { kind: 'prompt' }, result.value, schema);
182
+ }
183
+
184
+ function buildRequiredFlagSuggest(name: string, schema: FlagSchema): string {
185
+ const sources: string[] = [];
186
+ sources.push(`Provide --${name}${schema.kind !== 'boolean' ? ' <value>' : ''}`);
187
+
188
+ if (schema.envVar !== undefined) {
189
+ sources.push(`set ${schema.envVar}`);
190
+ }
191
+
192
+ if (schema.configPath !== undefined) {
193
+ sources.push(`add ${schema.configPath} to config`);
194
+ }
195
+
196
+ if (sources.length <= 1) {
197
+ return sources.join('');
198
+ }
199
+
200
+ const rest = sources.slice(0, -1);
201
+ const last = sources.slice(-1).join('');
202
+ return sources.length === 2 ? `${rest.join('')} or ${last}` : `${rest.join(', ')}, or ${last}`;
203
+ }
204
+
205
+ export { resolveFlags };