@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,432 @@
1
+ /**
2
+ * Internal resolver coercion helpers.
3
+ *
4
+ * @module dreamcli/core/resolve/coerce
5
+ * @internal
6
+ */
7
+
8
+ import type { ValidationErrorCode } from '#internals/core/errors/index.ts';
9
+ import { ValidationError } from '#internals/core/errors/index.ts';
10
+ import type { ArgSchema, FlagSchema } from '#internals/core/schema/index.ts';
11
+ import type { ArgDiagnosticSource, FlagDiagnosticSource } from './contracts.ts';
12
+ import type { SharedPropertySchema } from './property.ts';
13
+ import { toSharedArgPropertySchema, toSharedFlagPropertySchema } from './property.ts';
14
+
15
+ type CoerceSource = FlagDiagnosticSource;
16
+
17
+ /** Discriminated result of a value coercion attempt — success with the coerced value, or failure with a structured validation error. */
18
+ type CoerceResult =
19
+ | { readonly ok: true; readonly value: unknown }
20
+ | { readonly ok: false; readonly error: ValidationError };
21
+
22
+ function sourceLabel(source: CoerceSource): string {
23
+ switch (source.kind) {
24
+ case 'env':
25
+ return `from env ${source.envVar}`;
26
+ case 'config':
27
+ return `from config ${source.configPath}`;
28
+ case 'prompt':
29
+ return 'from prompt';
30
+ }
31
+ }
32
+
33
+ function sourceDetails(source: CoerceSource): Record<string, unknown> {
34
+ switch (source.kind) {
35
+ case 'env':
36
+ return { envVar: source.envVar };
37
+ case 'config':
38
+ return { configPath: source.configPath };
39
+ case 'prompt':
40
+ return { source: 'prompt' };
41
+ }
42
+ }
43
+
44
+ function coercionError(
45
+ flagName: string,
46
+ source: CoerceSource,
47
+ code: ValidationErrorCode,
48
+ expected: string,
49
+ raw: unknown,
50
+ messageSuffix: string,
51
+ suggest: string,
52
+ extraDetails?: Record<string, unknown>,
53
+ ): CoerceResult {
54
+ return {
55
+ ok: false,
56
+ error: new ValidationError(`${messageSuffix} ${sourceLabel(source)} for flag --${flagName}`, {
57
+ code,
58
+ details: { flag: flagName, ...sourceDetails(source), value: raw, expected, ...extraDetails },
59
+ suggest,
60
+ }),
61
+ };
62
+ }
63
+
64
+ /** Coerce a raw value from env/config/prompt into the type declared by a flag schema. */
65
+ function coerceValue(
66
+ flagName: string,
67
+ source: CoerceSource,
68
+ raw: unknown,
69
+ schema: FlagSchema,
70
+ ): CoerceResult {
71
+ const sharedSchema = toSharedFlagPropertySchema(schema);
72
+ if (sharedSchema !== undefined) {
73
+ return coerceSharedPropertyValue(flagName, source, raw, sharedSchema);
74
+ }
75
+
76
+ switch (schema.kind) {
77
+ case 'boolean': {
78
+ if (typeof raw === 'boolean') return { ok: true, value: raw };
79
+ if (typeof raw === 'string') {
80
+ const lower = raw.toLowerCase();
81
+ const truthy =
82
+ lower === 'true' ||
83
+ lower === '1' ||
84
+ lower === 'yes' ||
85
+ (source.kind === 'prompt' && lower === 'y');
86
+ if (truthy) return { ok: true, value: true };
87
+ const falsy =
88
+ lower === 'false' ||
89
+ lower === '0' ||
90
+ lower === 'no' ||
91
+ lower === '' ||
92
+ (source.kind === 'prompt' && lower === 'n');
93
+ if (falsy) return { ok: true, value: false };
94
+ }
95
+ return coercionError(
96
+ flagName,
97
+ source,
98
+ 'TYPE_MISMATCH',
99
+ 'boolean',
100
+ raw,
101
+ typeof raw === 'string' ? `Invalid boolean value '${raw}'` : 'Invalid boolean value',
102
+ source.kind === 'env'
103
+ ? `Set ${source.envVar} to true/false, 1/0, or yes/no`
104
+ : source.kind === 'config'
105
+ ? `Set ${source.configPath} to true or false in your config`
106
+ : `Answer yes or no for --${flagName}`,
107
+ );
108
+ }
109
+
110
+ case 'array': {
111
+ if (Array.isArray(raw)) {
112
+ if (schema.elementSchema) {
113
+ const coerced: unknown[] = [];
114
+ for (const element of raw) {
115
+ const result = coerceValue(flagName, source, element, schema.elementSchema);
116
+ if (!result.ok) return result;
117
+ coerced.push(result.value);
118
+ }
119
+ return { ok: true, value: coerced };
120
+ }
121
+ return { ok: true, value: raw };
122
+ }
123
+ if (typeof raw === 'string') {
124
+ if (raw === '') return { ok: true, value: [] };
125
+ const parts = raw.split(',');
126
+ if (schema.elementSchema) {
127
+ const coerced: unknown[] = [];
128
+ for (const part of parts) {
129
+ const element = source.kind === 'prompt' ? part.trim() : part;
130
+ const result = coerceValue(flagName, source, element, schema.elementSchema);
131
+ if (!result.ok) return result;
132
+ coerced.push(result.value);
133
+ }
134
+ return { ok: true, value: coerced };
135
+ }
136
+ return {
137
+ ok: true,
138
+ value: source.kind === 'prompt' ? parts.map((part) => part.trim()) : parts,
139
+ };
140
+ }
141
+ return coercionError(
142
+ flagName,
143
+ source,
144
+ 'TYPE_MISMATCH',
145
+ 'array',
146
+ raw,
147
+ 'Invalid array value',
148
+ source.kind === 'env'
149
+ ? `Set ${source.envVar} to comma-separated values`
150
+ : source.kind === 'config'
151
+ ? `Set ${source.configPath} to an array in your config`
152
+ : `Provide valid values for --${flagName}`,
153
+ );
154
+ }
155
+ }
156
+
157
+ throw new Error(`Unreachable flag coercion kind: ${schema.kind}`);
158
+ }
159
+
160
+ function coerceSharedPropertyValue(
161
+ flagName: string,
162
+ source: CoerceSource,
163
+ raw: unknown,
164
+ schema: SharedPropertySchema,
165
+ ): CoerceResult {
166
+ switch (schema.kind) {
167
+ case 'string': {
168
+ if (typeof raw === 'string') return { ok: true, value: raw };
169
+ if (source.kind === 'prompt') return { ok: true, value: String(raw) };
170
+ if (source.kind === 'config' && (typeof raw === 'number' || typeof raw === 'boolean')) {
171
+ return { ok: true, value: String(raw) };
172
+ }
173
+ return coercionError(
174
+ flagName,
175
+ source,
176
+ 'TYPE_MISMATCH',
177
+ 'string',
178
+ raw,
179
+ 'Invalid string value',
180
+ source.kind === 'config'
181
+ ? `Set ${source.configPath} to a string in your config`
182
+ : `Enter a valid string for --${flagName}`,
183
+ );
184
+ }
185
+
186
+ case 'number': {
187
+ if (typeof raw === 'number') {
188
+ if (Number.isNaN(raw)) {
189
+ return coercionError(
190
+ flagName,
191
+ source,
192
+ 'TYPE_MISMATCH',
193
+ 'number',
194
+ raw,
195
+ 'Invalid number value NaN',
196
+ source.kind === 'env'
197
+ ? `Set ${source.envVar} to a valid number`
198
+ : source.kind === 'config'
199
+ ? `Set ${source.configPath} to a valid number in your config`
200
+ : `Enter a valid number for --${flagName}`,
201
+ );
202
+ }
203
+ return { ok: true, value: raw };
204
+ }
205
+ if (typeof raw === 'string') {
206
+ const value = Number(raw);
207
+ if (!Number.isNaN(value)) return { ok: true, value };
208
+ }
209
+ return coercionError(
210
+ flagName,
211
+ source,
212
+ 'TYPE_MISMATCH',
213
+ 'number',
214
+ raw,
215
+ typeof raw === 'string' ? `Invalid number value '${raw}'` : 'Invalid number value',
216
+ source.kind === 'env'
217
+ ? `Set ${source.envVar} to a valid number`
218
+ : source.kind === 'config'
219
+ ? `Set ${source.configPath} to a valid number in your config`
220
+ : `Enter a valid number for --${flagName}`,
221
+ );
222
+ }
223
+
224
+ case 'enum': {
225
+ const allowed = schema.enumValues ?? [];
226
+ if (typeof raw === 'string' && allowed.includes(raw)) {
227
+ return { ok: true, value: raw };
228
+ }
229
+ return {
230
+ ok: false,
231
+ error: new ValidationError(
232
+ `Invalid value '${String(raw)}' ${sourceLabel(source)} for flag --${flagName}. Allowed: ${allowed.join(', ')}`,
233
+ {
234
+ code: 'INVALID_ENUM',
235
+ details: { flag: flagName, ...sourceDetails(source), value: raw, allowed },
236
+ suggest:
237
+ source.kind === 'env'
238
+ ? `Set ${source.envVar} to one of: ${allowed.join(', ')}`
239
+ : source.kind === 'config'
240
+ ? `Set ${source.configPath} to one of: ${allowed.join(', ')}`
241
+ : `Select one of: ${allowed.join(', ')}`,
242
+ },
243
+ ),
244
+ };
245
+ }
246
+
247
+ case 'custom': {
248
+ if (schema.parseFn === undefined) {
249
+ return { ok: true, value: raw };
250
+ }
251
+
252
+ try {
253
+ return { ok: true, value: schema.parseFn(raw) };
254
+ } catch (error) {
255
+ const message = error instanceof Error ? error.message : String(error);
256
+ const sourceRef =
257
+ source.kind === 'env'
258
+ ? `env ${source.envVar}`
259
+ : source.kind === 'config'
260
+ ? `config ${source.configPath}`
261
+ : 'prompt value';
262
+ return {
263
+ ok: false,
264
+ error: new ValidationError(
265
+ `Failed to parse ${sourceRef} for flag --${flagName}: ${message}`,
266
+ {
267
+ code: 'TYPE_MISMATCH',
268
+ details: {
269
+ flag: flagName,
270
+ ...sourceDetails(source),
271
+ value: raw,
272
+ expected: 'custom',
273
+ },
274
+ suggest:
275
+ source.kind === 'env'
276
+ ? `Set ${source.envVar} to a valid value for --${flagName}`
277
+ : source.kind === 'config'
278
+ ? `Set ${source.configPath} to a valid value for --${flagName} in your config`
279
+ : `Enter a valid value for --${flagName}`,
280
+ },
281
+ ),
282
+ };
283
+ }
284
+ }
285
+ }
286
+ }
287
+
288
+ type ArgStringSource = ArgDiagnosticSource;
289
+
290
+ function argSourceLabel(source: ArgStringSource): string {
291
+ return source.kind === 'env' ? `from env ${source.envVar}` : 'from stdin';
292
+ }
293
+
294
+ function argSourceDetails(source: ArgStringSource): Record<string, unknown> {
295
+ return source.kind === 'env' ? { envVar: source.envVar } : { source: 'stdin' };
296
+ }
297
+
298
+ function buildArgCoercionSuggest(
299
+ argName: string,
300
+ source: ArgStringSource,
301
+ expected: 'number' | 'custom',
302
+ ): string {
303
+ if (source.kind === 'env') {
304
+ return expected === 'number'
305
+ ? `Set ${source.envVar} to a valid number`
306
+ : `Set ${source.envVar} to a valid value for <${argName}>`;
307
+ }
308
+
309
+ return expected === 'number'
310
+ ? `Pipe a valid number to stdin for <${argName}>`
311
+ : `Pipe a valid value to stdin for <${argName}>`;
312
+ }
313
+
314
+ function argSourceToCoerceSource(source: ArgStringSource): CoerceSource {
315
+ return source.kind === 'env' ? { kind: 'env', envVar: source.envVar } : { kind: 'prompt' };
316
+ }
317
+
318
+ function redactArgCoercionMessage(
319
+ argName: string,
320
+ source: ArgStringSource,
321
+ schema: ArgSchema,
322
+ error: ValidationError,
323
+ ): string {
324
+ switch (schema.kind) {
325
+ case 'number':
326
+ return `Invalid number value '<redacted>' ${argSourceLabel(source)} for argument <${argName}>`;
327
+ case 'enum': {
328
+ const allowed = Array.isArray(error.details?.allowed)
329
+ ? error.details.allowed.filter((value): value is string => typeof value === 'string')
330
+ : [];
331
+ return `Invalid value '<redacted>' ${argSourceLabel(source)} for argument <${argName}>. Allowed: ${allowed.join(', ')}`;
332
+ }
333
+ case 'custom': {
334
+ const match = /: ([^:]+)$/.exec(error.message);
335
+ const suffix = match?.[1];
336
+ return suffix !== undefined
337
+ ? `Invalid value '<redacted>' ${argSourceLabel(source)} for argument <${argName}>: ${suffix}`
338
+ : `Invalid value '<redacted>' ${argSourceLabel(source)} for argument <${argName}>`;
339
+ }
340
+ case 'string':
341
+ return `Invalid value '<redacted>' ${argSourceLabel(source)} for argument <${argName}>`;
342
+ default: {
343
+ const exhaustive: never = schema.kind;
344
+ return exhaustive;
345
+ }
346
+ }
347
+ }
348
+
349
+ function redactArgCoercionDetails(
350
+ argName: string,
351
+ source: ArgStringSource,
352
+ schema: ArgSchema,
353
+ error: ValidationError,
354
+ ): Readonly<Record<string, unknown>> {
355
+ return {
356
+ arg: argName,
357
+ ...argSourceDetails(source),
358
+ ...(schema.kind === 'number' || schema.kind === 'custom' ? { expected: schema.kind } : {}),
359
+ ...(schema.kind === 'enum' && Array.isArray(error.details?.allowed)
360
+ ? {
361
+ allowed: error.details.allowed.filter(
362
+ (value): value is string => typeof value === 'string',
363
+ ),
364
+ }
365
+ : {}),
366
+ };
367
+ }
368
+
369
+ function redactArgCoercionSuggest(
370
+ argName: string,
371
+ source: ArgStringSource,
372
+ schema: ArgSchema,
373
+ error: ValidationError,
374
+ ): string | undefined {
375
+ if (schema.kind === 'number' || schema.kind === 'custom') {
376
+ return buildArgCoercionSuggest(argName, source, schema.kind);
377
+ }
378
+
379
+ if (schema.kind === 'enum') {
380
+ const allowed = Array.isArray(error.details?.allowed)
381
+ ? error.details.allowed.filter((value): value is string => typeof value === 'string')
382
+ : [];
383
+ const allowedList = allowed.join(', ');
384
+ return source.kind === 'env'
385
+ ? `Set ${source.envVar} to one of: ${allowedList}`
386
+ : `Provide one of: ${allowedList}`;
387
+ }
388
+
389
+ return undefined;
390
+ }
391
+
392
+ /** Coerce a string value from stdin/env into the type declared by an arg schema, redacting raw values in error diagnostics. */
393
+ function coerceArgStringValue(
394
+ argName: string,
395
+ source: ArgStringSource,
396
+ raw: string,
397
+ schema: ArgSchema,
398
+ ): CoerceResult {
399
+ const coerced = coerceSharedPropertyValue(
400
+ argName,
401
+ argSourceToCoerceSource(source),
402
+ raw,
403
+ toSharedArgPropertySchema(schema),
404
+ );
405
+ if (coerced.ok) {
406
+ return coerced;
407
+ }
408
+
409
+ const suggest = redactArgCoercionSuggest(argName, source, schema, coerced.error);
410
+ const options =
411
+ suggest === undefined
412
+ ? {
413
+ code: coerced.error.code,
414
+ details: redactArgCoercionDetails(argName, source, schema, coerced.error),
415
+ }
416
+ : {
417
+ code: coerced.error.code,
418
+ details: redactArgCoercionDetails(argName, source, schema, coerced.error),
419
+ suggest,
420
+ };
421
+
422
+ return {
423
+ ok: false,
424
+ error: new ValidationError(
425
+ redactArgCoercionMessage(argName, source, schema, coerced.error),
426
+ options,
427
+ ),
428
+ };
429
+ }
430
+
431
+ export type { CoerceResult };
432
+ export { coerceArgStringValue, coerceValue };
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Internal resolver config helpers.
3
+ *
4
+ * @module dreamcli/core/resolve/config
5
+ * @internal
6
+ */
7
+
8
+ function resolveConfigPath(config: Readonly<Record<string, unknown>>, path: string): unknown {
9
+ const segments = path.split('.');
10
+ let current: unknown = config;
11
+
12
+ for (const segment of segments) {
13
+ if (current === null || current === undefined || typeof current !== 'object') {
14
+ return undefined;
15
+ }
16
+ if (!Object.hasOwn(current, segment)) {
17
+ return undefined;
18
+ }
19
+ // Safe cast: guarded as a non-null object and verified to have `segment` above.
20
+ current = (current as Record<string, unknown>)[segment];
21
+ }
22
+
23
+ return current;
24
+ }
25
+
26
+ export { resolveConfigPath };
@@ -0,0 +1,135 @@
1
+ /**
2
+ * Internal resolver contract for precedence, diagnostics, and I/O shape.
3
+ *
4
+ * Captures the stable seam between parsed command input and resolved command
5
+ * values before the larger resolver module is split by concern.
6
+ *
7
+ * @module dreamcli/core/resolve/contracts
8
+ * @internal
9
+ */
10
+
11
+ import type { ParseResult } from '#internals/core/parse/index.ts';
12
+ import type { PromptEngine } from '#internals/core/prompt/index.ts';
13
+ import type { CommandSchema } from '#internals/core/schema/index.ts';
14
+
15
+ /** Ordered flag resolution stages owned by the resolver. */
16
+ const FLAG_RESOLUTION_ORDER = ['cli', 'env', 'config', 'prompt', 'default'] as const;
17
+
18
+ /** Ordered arg resolution stages owned by the resolver. */
19
+ const ARG_RESOLUTION_ORDER = ['cli', 'stdin', 'env', 'default'] as const;
20
+
21
+ /** Stable flag-source labels for precedence and diagnostics. */
22
+ type FlagResolutionStage = (typeof FLAG_RESOLUTION_ORDER)[number];
23
+
24
+ /** Stable arg-source labels for precedence and diagnostics. */
25
+ type ArgResolutionStage = (typeof ARG_RESOLUTION_ORDER)[number];
26
+
27
+ /**
28
+ * Source-aware diagnostic context for flag resolution failures.
29
+ *
30
+ * CLI/default failures currently surface as missing-value validation errors,
31
+ * so only env/config/prompt need explicit source payloads here.
32
+ */
33
+ type FlagDiagnosticSource =
34
+ | { readonly kind: 'env'; readonly envVar: string }
35
+ | { readonly kind: 'config'; readonly configPath: string }
36
+ | { readonly kind: 'prompt' };
37
+
38
+ /** Source-aware diagnostic context for arg resolution failures. */
39
+ type ArgDiagnosticSource =
40
+ | { readonly kind: 'env'; readonly envVar: string }
41
+ | { readonly kind: 'stdin' };
42
+
43
+ /**
44
+ * External state the resolver may consult after parsing.
45
+ *
46
+ * The resolver never reaches into `process`, files, or terminal APIs directly;
47
+ * callers inject those facts through this contract.
48
+ */
49
+ interface ResolveOptions {
50
+ /** Pre-read stdin content, or `null` when stdin was not piped. */
51
+ readonly stdinData?: string | null;
52
+ /** Environment variable snapshot injected by the caller. */
53
+ readonly env?: Readonly<Record<string, string | undefined>>;
54
+ /** Parsed config file contents keyed by dotted path segments. */
55
+ readonly config?: Readonly<Record<string, unknown>>;
56
+ /** Interactive prompt engine; absent in non-TTY / CI contexts. */
57
+ readonly prompter?: PromptEngine;
58
+ }
59
+
60
+ /** Structured deprecation notice emitted for explicitly sourced values. */
61
+ interface DeprecationWarning {
62
+ /** Whether this deprecation targets a flag or a positional arg. */
63
+ readonly kind: 'flag' | 'arg';
64
+ /** Name of the deprecated flag or arg. */
65
+ readonly name: string;
66
+ /** Custom deprecation message, or `true` for the generic warning. */
67
+ readonly message: string | true;
68
+ }
69
+
70
+ /** Fully resolved command input handed to the executor layer. */
71
+ interface ResolveResult {
72
+ /** Fully resolved flag values keyed by flag name. */
73
+ readonly flags: Readonly<Record<string, unknown>>;
74
+ /** Fully resolved positional arg values keyed by arg name. */
75
+ readonly args: Readonly<Record<string, unknown>>;
76
+ /** Deprecation notices collected during resolution (may be empty). */
77
+ readonly deprecations: readonly DeprecationWarning[];
78
+ }
79
+
80
+ /** Explicit invocation boundary between parser output and resolved values. */
81
+ interface ResolverInvocation {
82
+ /** Command schema that declares flags, args, and resolution metadata. */
83
+ readonly schema: CommandSchema;
84
+ /** Raw parse result from the tokenizer/parser layer. */
85
+ readonly parsed: ParseResult;
86
+ /** Optional external state (env, config, stdin, prompter). */
87
+ readonly options?: ResolveOptions;
88
+ }
89
+
90
+ /**
91
+ * Stable resolver facts the re-foundation workstream is treating as contract.
92
+ *
93
+ * These are intended to anchor focused contract tests before larger module
94
+ * extraction and diagnostic redesign work lands.
95
+ */
96
+ interface ResolverContract {
97
+ /** Ordered stages for flag resolution: cli -> env -> config -> prompt -> default. */
98
+ readonly flagPrecedence: readonly FlagResolutionStage[];
99
+ /** Ordered stages for arg resolution: cli -> stdin -> env -> default. */
100
+ readonly argPrecedence: readonly ArgResolutionStage[];
101
+ /** Prompt stage runs only after env and config have been attempted. */
102
+ readonly promptRunsAfterFlagConfig: true;
103
+ /** All validation errors are collected before throwing a single aggregate. */
104
+ readonly aggregatesValidationErrors: true;
105
+ /** Aggregate error details include per-issue structured summaries. */
106
+ readonly aggregateDiagnosticsIncludePerIssueSummary: true;
107
+ /** A coercion failure at env/config stops fallback to later stages for that flag. */
108
+ readonly hardCoercionErrorsStopFallback: true;
109
+ /** Deprecation warnings are emitted only when a value was actually sourced. */
110
+ readonly collectsDeprecationsFromExplicitSources: true;
111
+ }
112
+
113
+ /** Runtime-accessible resolution contract — documents the resolver's invariants for tests and diagnostics. */
114
+ const resolverContract = {
115
+ flagPrecedence: FLAG_RESOLUTION_ORDER,
116
+ argPrecedence: ARG_RESOLUTION_ORDER,
117
+ promptRunsAfterFlagConfig: true,
118
+ aggregatesValidationErrors: true,
119
+ aggregateDiagnosticsIncludePerIssueSummary: true,
120
+ hardCoercionErrorsStopFallback: true,
121
+ collectsDeprecationsFromExplicitSources: true,
122
+ } satisfies ResolverContract;
123
+
124
+ export type {
125
+ ArgDiagnosticSource,
126
+ ArgResolutionStage,
127
+ DeprecationWarning,
128
+ FlagDiagnosticSource,
129
+ FlagResolutionStage,
130
+ ResolveOptions,
131
+ ResolveResult,
132
+ ResolverContract,
133
+ ResolverInvocation,
134
+ };
135
+ export { ARG_RESOLUTION_ORDER, FLAG_RESOLUTION_ORDER, resolverContract };