@kjanat/dreamcli 3.0.0-rc.1 → 3.0.0-rc.10

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 (194) hide show
  1. package/CHANGELOG.md +217 -1
  2. package/dist/core/cli/dispatch.d.mts +6 -5
  3. package/dist/core/cli/dispatch.mjs +205 -1
  4. package/dist/core/cli/help-links.d.mts +0 -1
  5. package/dist/core/cli/help-links.mjs +41 -1
  6. package/dist/core/cli/index.d.mts +81 -8
  7. package/dist/core/cli/index.mjs +945 -1
  8. package/dist/core/cli/planner.d.mts +5 -1
  9. package/dist/core/cli/planner.mjs +300 -1
  10. package/dist/core/cli/plugin.d.mts +1 -1
  11. package/dist/core/cli/plugin.mjs +41 -1
  12. package/dist/core/cli/propagate.d.mts +1 -1
  13. package/dist/core/cli/propagate.mjs +57 -1
  14. package/dist/core/cli/root-help.d.mts +2 -1
  15. package/dist/core/cli/root-help.mjs +226 -4
  16. package/dist/core/cli/root-surface.d.mts +12 -1
  17. package/dist/core/cli/root-surface.mjs +28 -1
  18. package/dist/core/cli/runtime-preflight.d.mts +14 -2
  19. package/dist/core/cli/runtime-preflight.mjs +169 -1
  20. package/dist/core/completion/index.d.mts +0 -1
  21. package/dist/core/completion/index.mjs +90 -1
  22. package/dist/core/completion/shells/bash.d.mts +0 -1
  23. package/dist/core/completion/shells/bash.mjs +308 -3
  24. package/dist/core/completion/shells/fish.d.mts +0 -1
  25. package/dist/core/completion/shells/fish.mjs +162 -2
  26. package/dist/core/completion/shells/powershell.d.mts +0 -1
  27. package/dist/core/completion/shells/powershell.mjs +358 -2
  28. package/dist/core/completion/shells/shared.d.mts +13 -2
  29. package/dist/core/completion/shells/shared.mjs +176 -1
  30. package/dist/core/completion/shells/zsh.d.mts +0 -1
  31. package/dist/core/completion/shells/zsh.mjs +251 -2
  32. package/dist/core/config/index.d.mts +2 -3
  33. package/dist/core/config/index.mjs +246 -1
  34. package/dist/core/config/package-json.d.mts +27 -4
  35. package/dist/core/config/package-json.mjs +386 -3
  36. package/dist/core/errors/index.d.mts +3 -3
  37. package/dist/core/errors/index.mjs +87 -1
  38. package/dist/core/execution/index.d.mts +0 -1
  39. package/dist/core/execution/index.mjs +201 -1
  40. package/dist/core/help/ansi.d.mts +11 -5
  41. package/dist/core/help/ansi.mjs +121 -2
  42. package/dist/core/help/index.d.mts +22 -3
  43. package/dist/core/help/index.mjs +341 -7
  44. package/dist/core/help/theme.d.mts +68 -0
  45. package/dist/core/help/theme.mjs +46 -0
  46. package/dist/core/json-schema/index.d.mts +15 -2
  47. package/dist/core/json-schema/index.mjs +536 -12
  48. package/dist/core/json-schema/meta-descriptions.generated.d.mts +55 -38
  49. package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
  50. package/dist/core/output/activity.d.mts +0 -1
  51. package/dist/core/output/activity.mjs +452 -1
  52. package/dist/core/output/bind.mjs +56 -1
  53. package/dist/core/output/contracts.d.mts +4 -5
  54. package/dist/core/output/contracts.mjs +57 -1
  55. package/dist/core/output/display-value.mjs +32 -1
  56. package/dist/core/output/index.d.mts +21 -1
  57. package/dist/core/output/index.mjs +442 -2
  58. package/dist/core/output/renderers.d.mts +0 -1
  59. package/dist/core/output/renderers.mjs +46 -1
  60. package/dist/core/output/writer.mjs +12 -1
  61. package/dist/core/parse/index.d.mts +40 -7
  62. package/dist/core/parse/index.mjs +727 -1
  63. package/dist/core/prompt/index.d.mts +1 -1
  64. package/dist/core/prompt/index.mjs +348 -6
  65. package/dist/core/resolve/args.d.mts +1 -1
  66. package/dist/core/resolve/args.mjs +105 -1
  67. package/dist/core/resolve/coerce.d.mts +1 -1
  68. package/dist/core/resolve/coerce.mjs +336 -1
  69. package/dist/core/resolve/config.mjs +19 -1
  70. package/dist/core/resolve/contracts.d.mts +9 -4
  71. package/dist/core/resolve/errors.d.mts +0 -1
  72. package/dist/core/resolve/errors.mjs +140 -2
  73. package/dist/core/resolve/flags.d.mts +7 -2
  74. package/dist/core/resolve/flags.mjs +251 -1
  75. package/dist/core/resolve/index.d.mts +2 -2
  76. package/dist/core/resolve/index.mjs +85 -1
  77. package/dist/core/resolve/property.d.mts +4 -2
  78. package/dist/core/resolve/property.mjs +53 -1
  79. package/dist/core/schema/activity.d.mts +31 -11
  80. package/dist/core/schema/arg.d.mts +3 -4
  81. package/dist/core/schema/arg.mjs +463 -1
  82. package/dist/core/schema/command.d.mts +26 -6
  83. package/dist/core/schema/command.mjs +726 -1
  84. package/dist/core/schema/flag.d.mts +485 -19
  85. package/dist/core/schema/flag.mjs +705 -1
  86. package/dist/core/schema/index.d.mts +4 -2
  87. package/dist/core/schema/middleware.d.mts +4 -3
  88. package/dist/core/schema/middleware.mjs +41 -1
  89. package/dist/core/schema/number-constraints.mjs +60 -1
  90. package/dist/core/schema/prompt.d.mts +6 -3
  91. package/dist/core/schema/run.d.mts +20 -1
  92. package/dist/core/schema/string-constraints.d.mts +97 -0
  93. package/dist/core/schema/string-constraints.mjs +69 -0
  94. package/dist/core/schema/value-parsers.d.mts +78 -0
  95. package/dist/core/schema/value-parsers.mjs +142 -0
  96. package/dist/core/schema-dsl/runtime.mjs +271 -2
  97. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  98. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  99. package/dist/core/testkit/index.d.mts +0 -31
  100. package/dist/core/testkit/index.mjs +83 -1
  101. package/dist/index.d.mts +11 -6
  102. package/dist/index.mjs +22 -1
  103. package/dist/runtime/adapter.d.mts +38 -2
  104. package/dist/runtime/adapter.mjs +87 -1
  105. package/dist/runtime/auto.d.mts +2 -3
  106. package/dist/runtime/auto.mjs +45 -1
  107. package/dist/runtime/deno.d.mts +24 -5
  108. package/dist/runtime/deno.mjs +262 -2
  109. package/dist/runtime/detect.mjs +45 -1
  110. package/dist/runtime/index.d.mts +3 -4
  111. package/dist/runtime/node.d.mts +8 -2
  112. package/dist/runtime/node.mjs +220 -2
  113. package/dist/runtime/paths.mjs +48 -1
  114. package/dist/runtime.d.mts +4 -4
  115. package/dist/runtime.mjs +6 -1
  116. package/dist/strings.mjs +22 -1
  117. package/dist/testkit.d.mts +1 -0
  118. package/dist/testkit.mjs +5 -1
  119. package/dist/version.d.mts +7 -3
  120. package/dist/version.mjs +7 -1
  121. package/dreamcli.schema.json +36 -7
  122. package/package.json +45 -42
  123. package/dist/runtime/bun.d.mts +0 -28
  124. package/dist/runtime/bun.mjs +0 -1
  125. package/src/core/cli/dispatch.ts +0 -355
  126. package/src/core/cli/help-links.ts +0 -82
  127. package/src/core/cli/index.ts +0 -1614
  128. package/src/core/cli/planner.ts +0 -656
  129. package/src/core/cli/plugin.ts +0 -117
  130. package/src/core/cli/propagate.ts +0 -97
  131. package/src/core/cli/root-help.ts +0 -342
  132. package/src/core/cli/root-surface.ts +0 -87
  133. package/src/core/cli/runtime-preflight.ts +0 -456
  134. package/src/core/completion/index.ts +0 -138
  135. package/src/core/completion/shells/bash.ts +0 -459
  136. package/src/core/completion/shells/fish.ts +0 -259
  137. package/src/core/completion/shells/powershell.ts +0 -439
  138. package/src/core/completion/shells/shared.ts +0 -310
  139. package/src/core/completion/shells/zsh.ts +0 -381
  140. package/src/core/config/index.ts +0 -417
  141. package/src/core/config/package-json.ts +0 -560
  142. package/src/core/errors/index.ts +0 -193
  143. package/src/core/execution/index.ts +0 -265
  144. package/src/core/help/ansi.ts +0 -144
  145. package/src/core/help/index.ts +0 -563
  146. package/src/core/json-schema/index.ts +0 -910
  147. package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
  148. package/src/core/output/activity.ts +0 -575
  149. package/src/core/output/bind.ts +0 -59
  150. package/src/core/output/contracts.ts +0 -194
  151. package/src/core/output/display-value.ts +0 -48
  152. package/src/core/output/index.ts +0 -704
  153. package/src/core/output/renderers.ts +0 -125
  154. package/src/core/output/writer.ts +0 -46
  155. package/src/core/parse/index.ts +0 -742
  156. package/src/core/prompt/index.ts +0 -623
  157. package/src/core/resolve/args.ts +0 -144
  158. package/src/core/resolve/coerce.ts +0 -500
  159. package/src/core/resolve/config.ts +0 -26
  160. package/src/core/resolve/contracts.ts +0 -135
  161. package/src/core/resolve/errors.ts +0 -227
  162. package/src/core/resolve/flags.ts +0 -269
  163. package/src/core/resolve/index.ts +0 -108
  164. package/src/core/resolve/property.ts +0 -99
  165. package/src/core/schema/activity.ts +0 -240
  166. package/src/core/schema/arg.ts +0 -841
  167. package/src/core/schema/command.ts +0 -1500
  168. package/src/core/schema/flag.ts +0 -917
  169. package/src/core/schema/index.ts +0 -96
  170. package/src/core/schema/middleware.ts +0 -171
  171. package/src/core/schema/number-constraints.ts +0 -153
  172. package/src/core/schema/prompt.ts +0 -171
  173. package/src/core/schema/run.ts +0 -198
  174. package/src/core/schema-dsl/index.ts +0 -109
  175. package/src/core/schema-dsl/parse.ts +0 -262
  176. package/src/core/schema-dsl/runtime.ts +0 -609
  177. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  178. package/src/core/testkit/index.ts +0 -147
  179. package/src/index.ts +0 -181
  180. package/src/runtime/adapter.ts +0 -303
  181. package/src/runtime/auto.ts +0 -86
  182. package/src/runtime/bun.ts +0 -48
  183. package/src/runtime/deno.ts +0 -367
  184. package/src/runtime/detect.ts +0 -105
  185. package/src/runtime/index.ts +0 -21
  186. package/src/runtime/node-builtins.d.ts +0 -27
  187. package/src/runtime/node.ts +0 -289
  188. package/src/runtime/paths.ts +0 -64
  189. package/src/runtime/support.ts +0 -77
  190. package/src/runtime.ts +0 -31
  191. package/src/schema.ts +0 -16
  192. package/src/strings.ts +0 -34
  193. package/src/testkit.ts +0 -25
  194. package/src/version.ts +0 -20
@@ -1 +1,336 @@
1
- import{describeNumberConstraintViolation as e,validateNumberConstraints as t}from"../schema/number-constraints.mjs";import{ValidationError as n}from"../errors/index.mjs";import{toSharedArgPropertySchema as r,toSharedFlagPropertySchema as i}from"./property.mjs";function a(e){switch(e.kind){case`env`:return`from env ${e.envVar}`;case`config`:return`from config ${e.configPath}`;case`prompt`:return`from prompt`}}function o(e){switch(e.kind){case`env`:return{envVar:e.envVar};case`config`:return{configPath:e.configPath};case`prompt`:return{source:`prompt`}}}function s(e,t,r,i,s,c,l,u){return{ok:!1,error:new n(`${c} ${a(t)} for flag --${e}`,{code:r,details:{flag:e,...o(t),value:s,expected:i,...u},suggest:l})}}function c(r,i,s,c,l){let u=t(c,l);if(u===void 0)return{ok:!0,value:c};let d=e(u);return{ok:!1,error:new n(`Invalid number value '${String(s)}' ${a(i)} for flag --${r}: ${d}`,{code:`CONSTRAINT_VIOLATED`,details:{flag:r,...o(i),value:s,expected:`number`,constraint:u.kind,...`bound`in u?{bound:u.bound}:{}},suggest:i.kind===`env`?`Set ${i.envVar} to a valid number`:i.kind===`config`?`Set ${i.configPath} to a valid number in your config`:`Enter a valid number for --${r}`})}}function l(e,t,n,r){let a=i(r);if(a!==void 0)return u(e,t,n,a);switch(r.kind){case`boolean`:if(typeof n==`boolean`)return{ok:!0,value:n};if(typeof n==`string`){let e=n.toLowerCase();if(e===`true`||e===`1`||e===`yes`||t.kind===`prompt`&&e===`y`)return{ok:!0,value:!0};if(e===`false`||e===`0`||e===`no`||e===``||t.kind===`prompt`&&e===`n`)return{ok:!0,value:!1}}return s(e,t,`TYPE_MISMATCH`,`boolean`,n,typeof n==`string`?`Invalid boolean value '${n}'`:`Invalid boolean value`,t.kind===`env`?`Set ${t.envVar} to true/false, 1/0, or yes/no`:t.kind===`config`?`Set ${t.configPath} to true or false in your config`:`Answer yes or no for --${e}`);case`array`:if(Array.isArray(n)){if(r.elementSchema){let i=[];for(let a of n){let n=l(e,t,a,r.elementSchema);if(!n.ok)return n;i.push(n.value)}return{ok:!0,value:i}}return{ok:!0,value:n}}if(typeof n==`string`){if(n===``)return{ok:!0,value:[]};let i=n.split(`,`);if(r.elementSchema){let n=[];for(let a of i){let i=l(e,t,t.kind===`prompt`?a.trim():a,r.elementSchema);if(!i.ok)return i;n.push(i.value)}return{ok:!0,value:n}}return{ok:!0,value:t.kind===`prompt`?i.map(e=>e.trim()):i}}return s(e,t,`TYPE_MISMATCH`,`array`,n,`Invalid array value`,t.kind===`env`?`Set ${t.envVar} to comma-separated values`:t.kind===`config`?`Set ${t.configPath} to an array in your config`:`Provide valid values for --${e}`)}throw Error(`Unreachable flag coercion kind: ${r.kind}`)}function u(e,t,r,i){switch(i.kind){case`string`:return typeof r==`string`?{ok:!0,value:r}:t.kind===`prompt`||t.kind===`config`&&(typeof r==`number`||typeof r==`boolean`)?{ok:!0,value:String(r)}:s(e,t,`TYPE_MISMATCH`,`string`,r,`Invalid string value`,t.kind===`config`?`Set ${t.configPath} to a string in your config`:`Enter a valid string for --${e}`);case`number`:if(typeof r==`number`)return Number.isNaN(r)?s(e,t,`TYPE_MISMATCH`,`number`,r,`Invalid number value NaN`,t.kind===`env`?`Set ${t.envVar} to a valid number`:t.kind===`config`?`Set ${t.configPath} to a valid number in your config`:`Enter a valid number for --${e}`):c(e,t,r,r,i.numberConstraints);if(typeof r==`string`){let n=Number(r);if(!Number.isNaN(n))return c(e,t,r,n,i.numberConstraints)}return s(e,t,`TYPE_MISMATCH`,`number`,r,typeof r==`string`?`Invalid number value '${r}'`:`Invalid number value`,t.kind===`env`?`Set ${t.envVar} to a valid number`:t.kind===`config`?`Set ${t.configPath} to a valid number in your config`:`Enter a valid number for --${e}`);case`enum`:{let s=i.enumValues??[];return typeof r==`string`&&s.includes(r)?{ok:!0,value:r}:{ok:!1,error:new n(`Invalid value '${String(r)}' ${a(t)} for flag --${e}. Allowed: ${s.join(`, `)}`,{code:`INVALID_ENUM`,details:{flag:e,...o(t),value:r,allowed:s},suggest:t.kind===`env`?`Set ${t.envVar} to one of: ${s.join(`, `)}`:t.kind===`config`?`Set ${t.configPath} to one of: ${s.join(`, `)}`:`Select one of: ${s.join(`, `)}`})}}case`custom`:if(i.parseFn===void 0)return{ok:!0,value:r};try{return{ok:!0,value:i.parseFn(r)}}catch(i){let a=i instanceof Error?i.message:String(i);return{ok:!1,error:new n(`Failed to parse ${t.kind===`env`?`env ${t.envVar}`:t.kind===`config`?`config ${t.configPath}`:`prompt value`} for flag --${e}: ${a}`,{code:`TYPE_MISMATCH`,details:{flag:e,...o(t),value:r,expected:`custom`},suggest:t.kind===`env`?`Set ${t.envVar} to a valid value for --${e}`:t.kind===`config`?`Set ${t.configPath} to a valid value for --${e} in your config`:`Enter a valid value for --${e}`})}}}}function d(e){return e.kind===`env`?`from env ${e.envVar}`:`from stdin`}function f(e){return e.kind===`env`?{envVar:e.envVar}:{source:`stdin`}}function p(e,t,n){return t.kind===`env`?n===`number`?`Set ${t.envVar} to a valid number`:`Set ${t.envVar} to a valid value for <${e}>`:n===`number`?`Pipe a valid number to stdin for <${e}>`:`Pipe a valid value to stdin for <${e}>`}function m(e){return e.kind===`env`?{kind:`env`,envVar:e.envVar}:{kind:`prompt`}}function h(e,t,n,r){switch(n.kind){case`number`:{let n=`Invalid number value '<redacted>' ${d(t)} for argument <${e}>`;if(r.code!==`CONSTRAINT_VIOLATED`)return n;let i=/: ([^:]+)$/.exec(r.message)?.[1];return i===void 0?n:`${n}: ${i}`}case`enum`:{let n=Array.isArray(r.details?.allowed)?r.details.allowed.filter(e=>typeof e==`string`):[];return`Invalid value '<redacted>' ${d(t)} for argument <${e}>. Allowed: ${n.join(`, `)}`}case`custom`:{let n=/: ([^:]+)$/.exec(r.message)?.[1];return n===void 0?`Invalid value '<redacted>' ${d(t)} for argument <${e}>`:`Invalid value '<redacted>' ${d(t)} for argument <${e}>: ${n}`}case`string`:return`Invalid value '<redacted>' ${d(t)} for argument <${e}>`;default:return n.kind}}function g(e,t,n,r){return{arg:e,...f(t),...n.kind===`number`||n.kind===`custom`?{expected:n.kind}:{},...n.kind===`number`&&typeof r.details?.constraint==`string`?{constraint:r.details.constraint}:{},...n.kind===`number`&&typeof r.details?.bound==`number`?{bound:r.details.bound}:{},...n.kind===`enum`&&Array.isArray(r.details?.allowed)?{allowed:r.details.allowed.filter(e=>typeof e==`string`)}:{}}}function _(e,t,n,r){if(n.kind===`number`||n.kind===`custom`)return p(e,t,n.kind);if(n.kind===`enum`){let e=(Array.isArray(r.details?.allowed)?r.details.allowed.filter(e=>typeof e==`string`):[]).join(`, `);return t.kind===`env`?`Set ${t.envVar} to one of: ${e}`:`Provide one of: ${e}`}}function v(e,t,i,a){let o=u(e,m(t),i,r(a));if(o.ok)return o;let s=_(e,t,a,o.error),c=s===void 0?{code:o.error.code,details:g(e,t,a,o.error)}:{code:o.error.code,details:g(e,t,a,o.error),suggest:s};return{ok:!1,error:new n(h(e,t,a,o.error),c)}}export{v as coerceArgStringValue,l as coerceValue};
1
+ import { ValidationError } from "../errors/index.mjs";
2
+ import { describeNumberConstraintViolation, validateNumberConstraints } from "../schema/number-constraints.mjs";
3
+ import { describeStringConstraintViolation, validateStringConstraints } from "../schema/string-constraints.mjs";
4
+ import { toSharedArgPropertySchema, toSharedFlagPropertySchema } from "./property.mjs";
5
+ //#region src/core/resolve/coerce.ts
6
+ function sourceLabel(source) {
7
+ switch (source.kind) {
8
+ case "env": return `from env ${source.envVar}`;
9
+ case "config": return `from config ${source.configPath}`;
10
+ case "prompt": return "from prompt";
11
+ }
12
+ }
13
+ function sourceDetails(source) {
14
+ switch (source.kind) {
15
+ case "env": return { envVar: source.envVar };
16
+ case "config": return { configPath: source.configPath };
17
+ case "prompt": return { source: "prompt" };
18
+ }
19
+ }
20
+ function coercionError(flagName, source, code, expected, raw, messageSuffix, suggest, extraDetails) {
21
+ return {
22
+ ok: false,
23
+ error: new ValidationError(`${messageSuffix} ${sourceLabel(source)} for flag --${flagName}`, {
24
+ code,
25
+ details: {
26
+ flag: flagName,
27
+ ...sourceDetails(source),
28
+ value: raw,
29
+ expected,
30
+ ...extraDetails
31
+ },
32
+ suggest
33
+ })
34
+ };
35
+ }
36
+ /**
37
+ * Apply numeric constraints to an already-parsed number. Shares the single
38
+ * {@link validateNumberConstraints} check used by the parse path, so the two
39
+ * boundaries cannot drift. On violation, returns a `CONSTRAINT_VIOLATED`
40
+ * failure; the human-readable reason is also surfaced in `details.constraint`
41
+ * (the violation kind) and the message suffix.
42
+ */
43
+ function finalizeNumber(flagName, source, raw, value, constraints) {
44
+ const violation = validateNumberConstraints(value, constraints);
45
+ if (violation === void 0) return {
46
+ ok: true,
47
+ value
48
+ };
49
+ const reason = describeNumberConstraintViolation(violation);
50
+ return {
51
+ ok: false,
52
+ error: new ValidationError(`Invalid number value '${String(raw)}' ${sourceLabel(source)} for flag --${flagName}: ${reason}`, {
53
+ code: "CONSTRAINT_VIOLATED",
54
+ details: {
55
+ flag: flagName,
56
+ ...sourceDetails(source),
57
+ value: raw,
58
+ expected: "number",
59
+ constraint: violation.kind,
60
+ ..."bound" in violation ? { bound: violation.bound } : {}
61
+ },
62
+ suggest: source.kind === "env" ? `Set ${source.envVar} to a valid number` : source.kind === "config" ? `Set ${source.configPath} to a valid number in your config` : `Enter a valid number for --${flagName}`
63
+ })
64
+ };
65
+ }
66
+ /**
67
+ * Apply string constraints to an already-string value. Shares the single
68
+ * {@link validateStringConstraints} check used by the parse path, so the two
69
+ * boundaries cannot drift. On violation, returns a `CONSTRAINT_VIOLATED`
70
+ * failure mirroring {@link finalizeNumber}.
71
+ */
72
+ function finalizeString(flagName, source, value, constraints) {
73
+ const violation = validateStringConstraints(value, constraints);
74
+ if (violation === void 0) return {
75
+ ok: true,
76
+ value
77
+ };
78
+ const reason = describeStringConstraintViolation(violation);
79
+ return {
80
+ ok: false,
81
+ error: new ValidationError(`Invalid value '${value}' ${sourceLabel(source)} for flag --${flagName}: ${reason}`, {
82
+ code: "CONSTRAINT_VIOLATED",
83
+ details: {
84
+ flag: flagName,
85
+ ...sourceDetails(source),
86
+ value,
87
+ expected: "string",
88
+ constraint: violation.kind,
89
+ ..."bound" in violation ? { bound: violation.bound } : {},
90
+ ..."pattern" in violation ? { pattern: violation.pattern } : {}
91
+ },
92
+ suggest: source.kind === "env" ? `Set ${source.envVar} to a valid string` : source.kind === "config" ? `Set ${source.configPath} to a valid string in your config` : `Enter a valid value for --${flagName}`
93
+ })
94
+ };
95
+ }
96
+ /** Coerce a raw value from env/config/prompt into the type declared by a flag schema. */
97
+ function coerceValue(flagName, source, raw, schema) {
98
+ const sharedSchema = toSharedFlagPropertySchema(schema);
99
+ if (sharedSchema !== void 0) return coerceSharedPropertyValue(flagName, source, raw, sharedSchema);
100
+ switch (schema.kind) {
101
+ case "boolean":
102
+ if (typeof raw === "boolean") return {
103
+ ok: true,
104
+ value: raw
105
+ };
106
+ if (typeof raw === "string") {
107
+ const lower = raw.toLowerCase();
108
+ if (lower === "true" || lower === "1" || lower === "yes" || source.kind === "prompt" && lower === "y") return {
109
+ ok: true,
110
+ value: true
111
+ };
112
+ if (lower === "false" || lower === "0" || lower === "no" || lower === "" || source.kind === "prompt" && lower === "n") return {
113
+ ok: true,
114
+ value: false
115
+ };
116
+ }
117
+ return coercionError(flagName, source, "TYPE_MISMATCH", "boolean", raw, typeof raw === "string" ? `Invalid boolean value '${raw}'` : "Invalid boolean value", source.kind === "env" ? `Set ${source.envVar} to true/false, 1/0, or yes/no` : source.kind === "config" ? `Set ${source.configPath} to true or false in your config` : `Answer yes or no for --${flagName}`);
118
+ case "array":
119
+ if (Array.isArray(raw)) {
120
+ if (schema.elementSchema) {
121
+ const coerced = [];
122
+ for (const element of raw) {
123
+ const result = coerceValue(flagName, source, element, schema.elementSchema);
124
+ if (!result.ok) return result;
125
+ coerced.push(result.value);
126
+ }
127
+ return {
128
+ ok: true,
129
+ value: coerced
130
+ };
131
+ }
132
+ return {
133
+ ok: true,
134
+ value: raw
135
+ };
136
+ }
137
+ if (typeof raw === "string") {
138
+ if (raw === "") return {
139
+ ok: true,
140
+ value: []
141
+ };
142
+ const parts = raw.split(schema.separator ?? ",").filter((part) => part.length > 0);
143
+ if (schema.elementSchema) {
144
+ const coerced = [];
145
+ for (const part of parts) {
146
+ const result = coerceValue(flagName, source, source.kind === "prompt" ? part.trim() : part, schema.elementSchema);
147
+ if (!result.ok) return result;
148
+ coerced.push(result.value);
149
+ }
150
+ return {
151
+ ok: true,
152
+ value: coerced
153
+ };
154
+ }
155
+ return {
156
+ ok: true,
157
+ value: source.kind === "prompt" ? parts.map((part) => part.trim()) : parts
158
+ };
159
+ }
160
+ return coercionError(flagName, source, "TYPE_MISMATCH", "array", raw, "Invalid array value", source.kind === "env" ? `Set ${source.envVar} to comma-separated values` : source.kind === "config" ? `Set ${source.configPath} to an array in your config` : `Provide valid values for --${flagName}`);
161
+ case "count": {
162
+ const value = typeof raw === "string" ? raw.trim() === "" ? NaN : Number(raw) : raw;
163
+ if (typeof value === "number" && Number.isInteger(value) && value >= 0) return {
164
+ ok: true,
165
+ value
166
+ };
167
+ return coercionError(flagName, source, "TYPE_MISMATCH", "count", raw, typeof raw === "string" ? `Invalid count value '${raw}'` : "Invalid count value", source.kind === "env" ? `Set ${source.envVar} to a non-negative integer` : source.kind === "config" ? `Set ${source.configPath} to a non-negative integer in your config` : `Enter a non-negative integer for --${flagName}`);
168
+ }
169
+ case "keyValue":
170
+ if (isStringRecord(raw)) return {
171
+ ok: true,
172
+ value: { ...raw }
173
+ };
174
+ if (typeof raw === "string") {
175
+ if (raw === "") return {
176
+ ok: true,
177
+ value: {}
178
+ };
179
+ const pairs = [];
180
+ for (const pair of raw.split(",").filter((segment) => segment.length > 0)) {
181
+ const eq = pair.indexOf("=");
182
+ if (eq <= 0) return coercionError(flagName, source, "TYPE_MISMATCH", "key=value", raw, `Invalid key-value pair '${pair}'`, source.kind === "env" ? `Set ${source.envVar} to comma-separated KEY=VALUE pairs` : source.kind === "config" ? `Set ${source.configPath} to an object with string values` : `Use KEY=VALUE for --${flagName}`);
183
+ pairs.push([pair.slice(0, eq), pair.slice(eq + 1)]);
184
+ }
185
+ return {
186
+ ok: true,
187
+ value: Object.fromEntries(pairs)
188
+ };
189
+ }
190
+ return coercionError(flagName, source, "TYPE_MISMATCH", "key=value", raw, "Invalid key-value value", source.kind === "env" ? `Set ${source.envVar} to comma-separated KEY=VALUE pairs` : source.kind === "config" ? `Set ${source.configPath} to an object with string values` : `Use KEY=VALUE for --${flagName}`);
191
+ }
192
+ throw new Error(`Unreachable flag coercion kind: ${schema.kind}`);
193
+ }
194
+ /** Narrow config-sourced objects to plain string-valued records. */
195
+ function isStringRecord(value) {
196
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
197
+ return Object.values(value).every((entry) => typeof entry === "string");
198
+ }
199
+ function coerceSharedPropertyValue(flagName, source, raw, schema) {
200
+ switch (schema.kind) {
201
+ case "string":
202
+ if (typeof raw === "string") return finalizeString(flagName, source, raw, schema.stringConstraints);
203
+ if (source.kind === "prompt") return finalizeString(flagName, source, String(raw), schema.stringConstraints);
204
+ if (source.kind === "config" && (typeof raw === "number" || typeof raw === "boolean")) return finalizeString(flagName, source, String(raw), schema.stringConstraints);
205
+ return coercionError(flagName, source, "TYPE_MISMATCH", "string", raw, "Invalid string value", source.kind === "config" ? `Set ${source.configPath} to a string in your config` : `Enter a valid string for --${flagName}`);
206
+ case "number":
207
+ if (typeof raw === "number") {
208
+ if (Number.isNaN(raw)) return coercionError(flagName, source, "TYPE_MISMATCH", "number", raw, "Invalid number value NaN", source.kind === "env" ? `Set ${source.envVar} to a valid number` : source.kind === "config" ? `Set ${source.configPath} to a valid number in your config` : `Enter a valid number for --${flagName}`);
209
+ return finalizeNumber(flagName, source, raw, raw, schema.numberConstraints);
210
+ }
211
+ if (typeof raw === "string") {
212
+ const value = Number(raw);
213
+ if (!Number.isNaN(value)) return finalizeNumber(flagName, source, raw, value, schema.numberConstraints);
214
+ }
215
+ return coercionError(flagName, source, "TYPE_MISMATCH", "number", raw, typeof raw === "string" ? `Invalid number value '${raw}'` : "Invalid number value", source.kind === "env" ? `Set ${source.envVar} to a valid number` : source.kind === "config" ? `Set ${source.configPath} to a valid number in your config` : `Enter a valid number for --${flagName}`);
216
+ case "enum": {
217
+ const allowed = schema.enumValues ?? [];
218
+ if (typeof raw === "string" && allowed.includes(raw)) return {
219
+ ok: true,
220
+ value: raw
221
+ };
222
+ return {
223
+ ok: false,
224
+ error: new ValidationError(`Invalid value '${String(raw)}' ${sourceLabel(source)} for flag --${flagName}. Allowed: ${allowed.join(", ")}`, {
225
+ code: "INVALID_ENUM",
226
+ details: {
227
+ flag: flagName,
228
+ ...sourceDetails(source),
229
+ value: raw,
230
+ allowed
231
+ },
232
+ suggest: source.kind === "env" ? `Set ${source.envVar} to one of: ${allowed.join(", ")}` : source.kind === "config" ? `Set ${source.configPath} to one of: ${allowed.join(", ")}` : `Select one of: ${allowed.join(", ")}`
233
+ })
234
+ };
235
+ }
236
+ case "custom":
237
+ if (schema.parseFn === void 0) return {
238
+ ok: true,
239
+ value: raw
240
+ };
241
+ try {
242
+ return {
243
+ ok: true,
244
+ value: schema.parseFn(raw)
245
+ };
246
+ } catch (error) {
247
+ const message = error instanceof Error ? error.message : String(error);
248
+ return {
249
+ ok: false,
250
+ error: new ValidationError(`Failed to parse ${source.kind === "env" ? `env ${source.envVar}` : source.kind === "config" ? `config ${source.configPath}` : "prompt value"} for flag --${flagName}: ${message}`, {
251
+ code: "TYPE_MISMATCH",
252
+ details: {
253
+ flag: flagName,
254
+ ...sourceDetails(source),
255
+ value: raw,
256
+ expected: "custom"
257
+ },
258
+ suggest: source.kind === "env" ? `Set ${source.envVar} to a valid value for --${flagName}` : source.kind === "config" ? `Set ${source.configPath} to a valid value for --${flagName} in your config` : `Enter a valid value for --${flagName}`
259
+ })
260
+ };
261
+ }
262
+ }
263
+ }
264
+ function argSourceLabel(source) {
265
+ return source.kind === "env" ? `from env ${source.envVar}` : "from stdin";
266
+ }
267
+ function argSourceDetails(source) {
268
+ return source.kind === "env" ? { envVar: source.envVar } : { source: "stdin" };
269
+ }
270
+ function buildArgCoercionSuggest(argName, source, expected) {
271
+ if (source.kind === "env") return expected === "number" ? `Set ${source.envVar} to a valid number` : `Set ${source.envVar} to a valid value for <${argName}>`;
272
+ return expected === "number" ? `Pipe a valid number to stdin for <${argName}>` : `Pipe a valid value to stdin for <${argName}>`;
273
+ }
274
+ function argSourceToCoerceSource(source) {
275
+ return source.kind === "env" ? {
276
+ kind: "env",
277
+ envVar: source.envVar
278
+ } : { kind: "prompt" };
279
+ }
280
+ function redactArgCoercionMessage(argName, source, schema, error) {
281
+ switch (schema.kind) {
282
+ case "number": {
283
+ const base = `Invalid number value '<redacted>' ${argSourceLabel(source)} for argument <${argName}>`;
284
+ if (error.code !== "CONSTRAINT_VIOLATED") return base;
285
+ const suffix = /: ([^:]+)$/.exec(error.message)?.[1];
286
+ return suffix !== void 0 ? `${base}: ${suffix}` : base;
287
+ }
288
+ case "enum": {
289
+ const allowed = Array.isArray(error.details?.allowed) ? error.details.allowed.filter((value) => typeof value === "string") : [];
290
+ return `Invalid value '<redacted>' ${argSourceLabel(source)} for argument <${argName}>. Allowed: ${allowed.join(", ")}`;
291
+ }
292
+ case "custom": {
293
+ const suffix = /: ([^:]+)$/.exec(error.message)?.[1];
294
+ return suffix !== void 0 ? `Invalid value '<redacted>' ${argSourceLabel(source)} for argument <${argName}>: ${suffix}` : `Invalid value '<redacted>' ${argSourceLabel(source)} for argument <${argName}>`;
295
+ }
296
+ case "string": return `Invalid value '<redacted>' ${argSourceLabel(source)} for argument <${argName}>`;
297
+ default: return schema.kind;
298
+ }
299
+ }
300
+ function redactArgCoercionDetails(argName, source, schema, error) {
301
+ return {
302
+ arg: argName,
303
+ ...argSourceDetails(source),
304
+ ...schema.kind === "number" || schema.kind === "custom" ? { expected: schema.kind } : {},
305
+ ...schema.kind === "number" && typeof error.details?.constraint === "string" ? { constraint: error.details.constraint } : {},
306
+ ...schema.kind === "number" && typeof error.details?.bound === "number" ? { bound: error.details.bound } : {},
307
+ ...schema.kind === "enum" && Array.isArray(error.details?.allowed) ? { allowed: error.details.allowed.filter((value) => typeof value === "string") } : {}
308
+ };
309
+ }
310
+ function redactArgCoercionSuggest(argName, source, schema, error) {
311
+ if (schema.kind === "number" || schema.kind === "custom") return buildArgCoercionSuggest(argName, source, schema.kind);
312
+ if (schema.kind === "enum") {
313
+ const allowedList = (Array.isArray(error.details?.allowed) ? error.details.allowed.filter((value) => typeof value === "string") : []).join(", ");
314
+ return source.kind === "env" ? `Set ${source.envVar} to one of: ${allowedList}` : `Provide one of: ${allowedList}`;
315
+ }
316
+ }
317
+ /** Coerce a string value from stdin/env into the type declared by an arg schema, redacting raw values in error diagnostics. */
318
+ function coerceArgStringValue(argName, source, raw, schema) {
319
+ const coerced = coerceSharedPropertyValue(argName, argSourceToCoerceSource(source), raw, toSharedArgPropertySchema(schema));
320
+ if (coerced.ok) return coerced;
321
+ const suggest = redactArgCoercionSuggest(argName, source, schema, coerced.error);
322
+ const options = suggest === void 0 ? {
323
+ code: coerced.error.code,
324
+ details: redactArgCoercionDetails(argName, source, schema, coerced.error)
325
+ } : {
326
+ code: coerced.error.code,
327
+ details: redactArgCoercionDetails(argName, source, schema, coerced.error),
328
+ suggest
329
+ };
330
+ return {
331
+ ok: false,
332
+ error: new ValidationError(redactArgCoercionMessage(argName, source, schema, coerced.error), options)
333
+ };
334
+ }
335
+ //#endregion
336
+ export { coerceArgStringValue, coerceValue };
@@ -1 +1,19 @@
1
- function e(e,t){let n=t.split(`.`),r=e;for(let e of n){if(typeof r!=`object`||!r||!Object.hasOwn(r,e))return;r=r[e]}return r}export{e as resolveConfigPath};
1
+ //#region src/core/resolve/config.ts
2
+ /**
3
+ * Internal resolver config helpers.
4
+ *
5
+ * @module dreamcli/core/resolve/config
6
+ * @internal
7
+ */
8
+ function resolveConfigPath(config, path) {
9
+ const segments = path.split(".");
10
+ let current = config;
11
+ for (const segment of segments) {
12
+ if (current === null || current === void 0 || typeof current !== "object") return;
13
+ if (!Object.hasOwn(current, segment)) return;
14
+ current = current[segment];
15
+ }
16
+ return current;
17
+ }
18
+ //#endregion
19
+ export { resolveConfigPath };
@@ -1,12 +1,12 @@
1
- import { ParseResult } from "../parse/index.mjs";
2
1
  import { PromptEngine } from "../prompt/index.mjs";
3
2
  import { CommandSchema } from "../schema/command.mjs";
4
-
3
+ import "../schema/index.mjs";
4
+ import { ParseResult } from "../parse/index.mjs";
5
5
  //#region src/core/resolve/contracts.d.ts
6
6
  /** Ordered flag resolution stages owned by the resolver. */
7
- declare const FLAG_RESOLUTION_ORDER: readonly ['cli', 'env', 'config', 'prompt', 'default'];
7
+ declare const FLAG_RESOLUTION_ORDER: readonly ["cli", "env", "config", "prompt", "default"];
8
8
  /** Ordered arg resolution stages owned by the resolver. */
9
- declare const ARG_RESOLUTION_ORDER: readonly ['cli', 'stdin', 'env', 'default'];
9
+ declare const ARG_RESOLUTION_ORDER: readonly ["cli", "stdin", "env", "default"];
10
10
  /** Stable flag-source labels for precedence and diagnostics. */
11
11
  type FlagResolutionStage = (typeof FLAG_RESOLUTION_ORDER)[number];
12
12
  /** Stable arg-source labels for precedence and diagnostics. */
@@ -48,6 +48,11 @@ interface ResolveOptions {
48
48
  readonly config?: Readonly<Record<string, unknown>>;
49
49
  /** Interactive prompt engine; absent in non-TTY / CI contexts. */
50
50
  readonly prompter?: PromptEngine;
51
+ /**
52
+ * Filesystem probe for `flag.path()` checks: what exists at the path, or
53
+ * `null` when nothing does. When absent, path checks are skipped.
54
+ */
55
+ readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
51
56
  }
52
57
  /** Structured deprecation notice emitted for explicitly sourced values. */
53
58
  interface DeprecationWarning {
@@ -1,5 +1,4 @@
1
1
  import { ValidationError } from "../errors/index.mjs";
2
-
3
2
  //#region src/core/resolve/errors.d.ts
4
3
  /** Type-narrowing guard that asserts a readonly array has at least one element. */
5
4
  declare function isNonEmpty<T>(arr: readonly T[]): arr is readonly [T, ...T[]];
@@ -1,2 +1,140 @@
1
- import{ValidationError as e}from"../errors/index.mjs";function t(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function n(e,t){let n=Reflect.get(e,t);return typeof n==`string`?n:void 0}function r(e,t){return Object.hasOwn(e,t)}function i(e){let t=n(e,`source`);if(t===`stdin`)return{kind:`stdin`,label:`stdin`};if(t===`prompt`)return{kind:`prompt`,label:`prompt`};if(r(e,`value`)){let t=n(e,`envVar`);if(t!==void 0)return{kind:`env`,label:`env ${t}`};let r=n(e,`configPath`);if(r!==void 0)return{kind:`config`,label:`config ${r}`}}}function a(e){let r=e.details;if(!t(r))return{code:e.code,inputKind:`input`,label:`input`,message:e.message};let a=n(r,`flag`);if(a!==void 0){let t=i(r);return{code:e.code,inputKind:`flag`,name:a,label:`flag --${a}`,message:e.message,...t===void 0?{}:{sourceKind:t.kind,sourceLabel:t.label}}}let o=n(r,`arg`);if(o!==void 0){let t=i(r);return{code:e.code,inputKind:`arg`,name:o,label:`argument <${o}>`,message:e.message,...t===void 0?{}:{sourceKind:t.kind,sourceLabel:t.label}}}return{code:e.code,inputKind:`input`,label:`input`,message:e.message}}function o(e){let t=e.filter(e=>e.inputKind===`flag`).length,n=e.filter(e=>e.inputKind===`arg`).length,r=e.length-t-n,i=[];return t>0&&i.push(`${t} flag${t===1?``:`s`}`),n>0&&i.push(`${n} arg${n===1?``:`s`}`),r>0&&i.push(`${r} input${r===1?``:`s`}`),i.length===0?`Multiple validation errors (${e.length})`:`Multiple validation errors (${i.join(`, `)})`}function s(e){let t=e.sourceLabel===void 0?``:` [${e.sourceLabel}]`;return`${e.label}${t}: ${e.message}`}function c(e){return e.length>0}function l(e){return!(typeof e!=`object`||!e||!(`code`in e)||!(`message`in e)||!(`exitCode`in e)||typeof e.code!=`string`||typeof e.message!=`string`||typeof e.exitCode!=`number`||`suggest`in e&&e.suggest!==void 0&&typeof e.suggest!=`string`||`details`in e&&e.details!==void 0&&(e.details===null||typeof e.details!=`object`))}function u(t){let n=t.details?.errors;if(!Array.isArray(n))return[t];let r=[];for(let i of n){if(!l(i))return[t];r.push(new e(i.message,{code:i.code,exitCode:i.exitCode,...i.suggest===void 0?{}:{suggest:i.suggest},...i.details===void 0?{}:{details:i.details}}))}return r}function d(t){if(t.length===1)throw t[0];let n=t.map(a),r=n.map(s);throw new e(`${o(n)}:\n - ${r.join(`
2
- - `)}`,{code:t[0].code,details:{errors:t.map(e=>e.toJSON()),count:t.length,issues:n},suggest:`Fix the listed validation errors and retry`})}export{u as collectValidationErrors,c as isNonEmpty,d as throwAggregatedErrors};
1
+ import { ValidationError } from "../errors/index.mjs";
2
+ //#region src/core/resolve/errors.ts
3
+ function isRecord(value) {
4
+ return typeof value === "object" && value !== null && !Array.isArray(value);
5
+ }
6
+ function readStringProperty(record, key) {
7
+ const value = Reflect.get(record, key);
8
+ return typeof value === "string" ? value : void 0;
9
+ }
10
+ function hasValueProperty(record, key) {
11
+ return Object.hasOwn(record, key);
12
+ }
13
+ function describeIssueSource(details) {
14
+ const explicitSource = readStringProperty(details, "source");
15
+ if (explicitSource === "stdin") return {
16
+ kind: "stdin",
17
+ label: "stdin"
18
+ };
19
+ if (explicitSource === "prompt") return {
20
+ kind: "prompt",
21
+ label: "prompt"
22
+ };
23
+ if (hasValueProperty(details, "value")) {
24
+ const envVar = readStringProperty(details, "envVar");
25
+ if (envVar !== void 0) return {
26
+ kind: "env",
27
+ label: `env ${envVar}`
28
+ };
29
+ const configPath = readStringProperty(details, "configPath");
30
+ if (configPath !== void 0) return {
31
+ kind: "config",
32
+ label: `config ${configPath}`
33
+ };
34
+ }
35
+ }
36
+ function summarizeValidationError(error) {
37
+ const details = error.details;
38
+ if (!isRecord(details)) return {
39
+ code: error.code,
40
+ inputKind: "input",
41
+ label: "input",
42
+ message: error.message
43
+ };
44
+ const flag = readStringProperty(details, "flag");
45
+ if (flag !== void 0) {
46
+ const source = describeIssueSource(details);
47
+ return {
48
+ code: error.code,
49
+ inputKind: "flag",
50
+ name: flag,
51
+ label: `flag --${flag}`,
52
+ message: error.message,
53
+ ...source !== void 0 ? {
54
+ sourceKind: source.kind,
55
+ sourceLabel: source.label
56
+ } : {}
57
+ };
58
+ }
59
+ const arg = readStringProperty(details, "arg");
60
+ if (arg !== void 0) {
61
+ const source = describeIssueSource(details);
62
+ return {
63
+ code: error.code,
64
+ inputKind: "arg",
65
+ name: arg,
66
+ label: `argument <${arg}>`,
67
+ message: error.message,
68
+ ...source !== void 0 ? {
69
+ sourceKind: source.kind,
70
+ sourceLabel: source.label
71
+ } : {}
72
+ };
73
+ }
74
+ return {
75
+ code: error.code,
76
+ inputKind: "input",
77
+ label: "input",
78
+ message: error.message
79
+ };
80
+ }
81
+ function formatAggregateHeadline(issues) {
82
+ const flagCount = issues.filter((issue) => issue.inputKind === "flag").length;
83
+ const argCount = issues.filter((issue) => issue.inputKind === "arg").length;
84
+ const otherCount = issues.length - flagCount - argCount;
85
+ const counts = [];
86
+ if (flagCount > 0) counts.push(`${flagCount} flag${flagCount === 1 ? "" : "s"}`);
87
+ if (argCount > 0) counts.push(`${argCount} arg${argCount === 1 ? "" : "s"}`);
88
+ if (otherCount > 0) counts.push(`${otherCount} input${otherCount === 1 ? "" : "s"}`);
89
+ return counts.length === 0 ? `Multiple validation errors (${issues.length})` : `Multiple validation errors (${counts.join(", ")})`;
90
+ }
91
+ function formatAggregateLine(issue) {
92
+ const source = issue.sourceLabel !== void 0 ? ` [${issue.sourceLabel}]` : "";
93
+ return `${issue.label}${source}: ${issue.message}`;
94
+ }
95
+ /** Type-narrowing guard that asserts a readonly array has at least one element. */
96
+ function isNonEmpty(arr) {
97
+ return arr.length > 0;
98
+ }
99
+ function isValidationErrorJson(value) {
100
+ if (value === null || typeof value !== "object") return false;
101
+ if (!("code" in value) || !("message" in value) || !("exitCode" in value)) return false;
102
+ if (typeof value.code !== "string" || typeof value.message !== "string") return false;
103
+ if (typeof value.exitCode !== "number") return false;
104
+ if ("suggest" in value && value.suggest !== void 0 && typeof value.suggest !== "string") return false;
105
+ if ("details" in value && value.details !== void 0 && (value.details === null || typeof value.details !== "object")) return false;
106
+ return true;
107
+ }
108
+ /** Flatten an aggregate validation error's nested `details.errors` into individual errors, or return the original as a singleton. */
109
+ function collectValidationErrors(error) {
110
+ const nestedErrors = error.details?.errors;
111
+ if (!Array.isArray(nestedErrors)) return [error];
112
+ const flattened = [];
113
+ for (const entry of nestedErrors) {
114
+ if (!isValidationErrorJson(entry)) return [error];
115
+ flattened.push(new ValidationError(entry.message, {
116
+ code: entry.code,
117
+ exitCode: entry.exitCode,
118
+ ...entry.suggest !== void 0 ? { suggest: entry.suggest } : {},
119
+ ...entry.details !== void 0 ? { details: entry.details } : {}
120
+ }));
121
+ }
122
+ return flattened;
123
+ }
124
+ /** Throw a single error if one, or an aggregate with per-issue summaries if many. */
125
+ function throwAggregatedErrors(errors) {
126
+ if (errors.length === 1) throw errors[0];
127
+ const issues = errors.map(summarizeValidationError);
128
+ const lines = issues.map(formatAggregateLine);
129
+ throw new ValidationError(`${formatAggregateHeadline(issues)}:\n - ${lines.join("\n - ")}`, {
130
+ code: errors[0].code,
131
+ details: {
132
+ errors: errors.map((error) => error.toJSON()),
133
+ count: errors.length,
134
+ issues
135
+ },
136
+ suggest: "Fix the listed validation errors and retry"
137
+ });
138
+ }
139
+ //#endregion
140
+ export { collectValidationErrors, isNonEmpty, throwAggregatedErrors };
@@ -3,10 +3,15 @@ import { FlagKind, FlagSchema } from "../schema/flag.mjs";
3
3
  import { PromptEngine } from "../prompt/index.mjs";
4
4
  import { DeprecationWarning } from "./contracts.mjs";
5
5
  import { ErasedInteractiveResolver } from "../schema/command.mjs";
6
-
7
6
  //#region src/core/resolve/flags.d.ts
7
+ /**
8
+ * Filesystem probe injected by the caller for `flag.path()` checks.
9
+ *
10
+ * Returns what exists at the path, or `null` when nothing does.
11
+ */
12
+ type StatFn = (path: string) => Promise<'file' | 'directory' | null>;
8
13
  /** Walk every declared flag through the resolution chain (cli -> env -> config -> prompt -> default), collecting deprecations and throwing aggregated errors. */
9
- declare function resolveFlags(flagSchemas: Readonly<Record<string, FlagSchema>>, parsedFlags: Readonly<Record<string, unknown>>, env: Readonly<Record<string, string | undefined>>, config: Readonly<Record<string, unknown>>, prompter: PromptEngine | undefined, interactive: ErasedInteractiveResolver | undefined, deprecations: DeprecationWarning[]): Promise<Readonly<Record<string, unknown>>>;
14
+ declare function resolveFlags(flagSchemas: Readonly<Record<string, FlagSchema>>, parsedFlags: Readonly<Record<string, unknown>>, env: Readonly<Record<string, string | undefined>>, config: Readonly<Record<string, unknown>>, prompter: PromptEngine | undefined, interactive: ErasedInteractiveResolver | undefined, deprecations: DeprecationWarning[], stat: StatFn | undefined): Promise<Readonly<Record<string, unknown>>>;
10
15
  /** Maps each flag kind to the prompt kinds that produce compatible values. */
11
16
  declare const COMPATIBLE_PROMPT_KINDS: Record<FlagKind, readonly PromptKind[]>;
12
17
  //#endregion