@kjanat/dreamcli 4.0.0-rc.2 → 4.0.0-rc.3

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 (501) hide show
  1. package/CHANGELOG.md +510 -1847
  2. package/dist/core/cli/builtins.d.mts +74 -4
  3. package/dist/core/cli/compiled.d.mts +39 -2
  4. package/dist/core/cli/dispatch.d.mts +81 -4
  5. package/dist/core/cli/help-links.d.mts +13 -1
  6. package/dist/core/cli/index.d.mts +77 -12
  7. package/dist/core/cli/index.mjs +9 -3
  8. package/dist/core/cli/planner.d.mts +86 -8
  9. package/dist/core/cli/reserved-flags.d.mts +19 -1
  10. package/dist/core/cli/root-help.d.mts +53 -1
  11. package/dist/core/cli/root-help.mjs +1 -1
  12. package/dist/core/cli/root-output-flags.d.mts +74 -1
  13. package/dist/core/cli/root-surface.d.mts +64 -1
  14. package/dist/core/cli/runtime-preflight.d.mts +213 -1
  15. package/dist/core/completion/index.d.mts +2 -2
  16. package/dist/core/completion/shells/bash.d.mts +1 -0
  17. package/dist/core/completion/shells/bash.mjs +4 -1
  18. package/dist/core/completion/shells/fish.d.mts +1 -0
  19. package/dist/core/completion/shells/fish.mjs +2 -1
  20. package/dist/core/completion/shells/powershell.d.mts +1 -0
  21. package/dist/core/completion/shells/powershell.mjs +2 -1
  22. package/dist/core/completion/shells/shared.d.mts +118 -3
  23. package/dist/core/completion/shells/shared.mjs +1 -1
  24. package/dist/core/completion/shells/zsh.d.mts +1 -0
  25. package/dist/core/completion/shells/zsh.mjs +6 -2
  26. package/dist/core/config/index.d.mts +1 -1
  27. package/dist/core/config/package-json.d.mts +1 -1
  28. package/dist/core/errors/index.d.mts +17 -18
  29. package/dist/core/execution/index.d.mts +61 -1
  30. package/dist/core/help/ansi.d.mts +11 -0
  31. package/dist/core/help/index.d.mts +42 -3
  32. package/dist/core/help/index.mjs +14 -10
  33. package/dist/core/help/theme.d.mts +39 -1
  34. package/dist/core/help/theme.mjs +24 -1
  35. package/dist/core/json-schema/index.d.mts +11 -11
  36. package/dist/core/json-schema/index.mjs +7 -6
  37. package/dist/core/output/activity.d.mts +193 -1
  38. package/dist/core/output/bind.d.mts +37 -1
  39. package/dist/core/output/contracts.d.mts +5 -4
  40. package/dist/core/output/display-value.d.mts +19 -1
  41. package/dist/core/output/index.d.mts +191 -7
  42. package/dist/core/output/index.mjs +6 -4
  43. package/dist/core/output/renderers.d.mts +45 -1
  44. package/dist/core/parse/index.d.mts +4 -4
  45. package/dist/core/parse/occurrences.d.mts +9 -8
  46. package/dist/core/prompt/index.d.mts +3 -3
  47. package/dist/core/read-flags/index.d.mts +1 -1
  48. package/dist/core/resolve/coerce.d.mts +4 -4
  49. package/dist/core/resolve/config.d.mts +10 -1
  50. package/dist/core/resolve/contracts.d.mts +9 -8
  51. package/dist/core/resolve/flags.d.mts +28 -1
  52. package/dist/core/resolve/path-checks.d.mts +4 -3
  53. package/dist/core/resolve/redaction.d.mts +1 -0
  54. package/dist/core/resolve/stages.d.mts +7 -6
  55. package/dist/core/resolve/standard.d.mts +26 -1
  56. package/dist/core/schema/activity.d.mts +16 -16
  57. package/dist/core/schema/arg.d.mts +76 -66
  58. package/dist/core/schema/brand.d.mts +1 -1
  59. package/dist/core/schema/cardinality.d.mts +18 -17
  60. package/dist/core/schema/command.d.mts +55 -9
  61. package/dist/core/schema/flag.d.mts +98 -90
  62. package/dist/core/schema/index.d.mts +1 -1
  63. package/dist/core/schema/middleware.d.mts +4 -1
  64. package/dist/core/schema/number-constraints.d.mts +5 -5
  65. package/dist/core/schema/prompt.d.mts +4 -4
  66. package/dist/core/schema/provenance.d.mts +11 -11
  67. package/dist/core/schema/run.d.mts +58 -8
  68. package/dist/core/schema/source.d.mts +13 -12
  69. package/dist/core/schema/standard.d.mts +31 -24
  70. package/dist/core/schema/stdin.d.mts +12 -2
  71. package/dist/core/schema/string-constraints.d.mts +4 -4
  72. package/dist/core/schema/value-parsers.d.mts +3 -3
  73. package/dist/core/schema/value.d.mts +15 -14
  74. package/dist/core/testkit/index.d.mts +10 -3
  75. package/dist/index.d.mts +6 -6
  76. package/dist/runtime/adapter.d.mts +3 -3
  77. package/dist/runtime/deno.d.mts +3 -3
  78. package/dist/runtime/detect.d.mts +2 -2
  79. package/dist/runtime/node.d.mts +3 -3
  80. package/dist/runtime/paths.d.mts +31 -1
  81. package/dist/strings.d.mts +16 -1
  82. package/dist/version.d.mts +16 -4
  83. package/dist/version.mjs +2 -2
  84. package/package.json +11 -8
  85. package/skills/cli-creation/SKILL.md +1 -1
  86. package/examples/gh/node_modules/typescript/LICENSE +0 -55
  87. package/examples/gh/node_modules/typescript/NOTICE.txt +0 -436
  88. package/examples/gh/node_modules/typescript/README.md +0 -49
  89. package/examples/gh/node_modules/typescript/bin/tsc +0 -2
  90. package/examples/gh/node_modules/typescript/dist/api/async/api.d.ts +0 -529
  91. package/examples/gh/node_modules/typescript/dist/api/async/api.d.ts.map +0 -1
  92. package/examples/gh/node_modules/typescript/dist/api/async/api.js +0 -1657
  93. package/examples/gh/node_modules/typescript/dist/api/async/api.js.map +0 -1
  94. package/examples/gh/node_modules/typescript/dist/api/async/client.d.ts +0 -39
  95. package/examples/gh/node_modules/typescript/dist/api/async/client.d.ts.map +0 -1
  96. package/examples/gh/node_modules/typescript/dist/api/async/client.js +0 -211
  97. package/examples/gh/node_modules/typescript/dist/api/async/client.js.map +0 -1
  98. package/examples/gh/node_modules/typescript/dist/api/async/types.d.ts +0 -310
  99. package/examples/gh/node_modules/typescript/dist/api/async/types.d.ts.map +0 -1
  100. package/examples/gh/node_modules/typescript/dist/api/async/types.js +0 -2
  101. package/examples/gh/node_modules/typescript/dist/api/async/types.js.map +0 -1
  102. package/examples/gh/node_modules/typescript/dist/api/compilerOptions.d.ts +0 -109
  103. package/examples/gh/node_modules/typescript/dist/api/compilerOptions.d.ts.map +0 -1
  104. package/examples/gh/node_modules/typescript/dist/api/compilerOptions.js +0 -2
  105. package/examples/gh/node_modules/typescript/dist/api/compilerOptions.js.map +0 -1
  106. package/examples/gh/node_modules/typescript/dist/api/fs.d.ts +0 -23
  107. package/examples/gh/node_modules/typescript/dist/api/fs.d.ts.map +0 -1
  108. package/examples/gh/node_modules/typescript/dist/api/fs.js +0 -109
  109. package/examples/gh/node_modules/typescript/dist/api/fs.js.map +0 -1
  110. package/examples/gh/node_modules/typescript/dist/api/node/encoder.d.ts +0 -15
  111. package/examples/gh/node_modules/typescript/dist/api/node/encoder.d.ts.map +0 -1
  112. package/examples/gh/node_modules/typescript/dist/api/node/encoder.generated.d.ts +0 -5
  113. package/examples/gh/node_modules/typescript/dist/api/node/encoder.generated.d.ts.map +0 -1
  114. package/examples/gh/node_modules/typescript/dist/api/node/encoder.generated.js +0 -74
  115. package/examples/gh/node_modules/typescript/dist/api/node/encoder.generated.js.map +0 -1
  116. package/examples/gh/node_modules/typescript/dist/api/node/encoder.js +0 -287
  117. package/examples/gh/node_modules/typescript/dist/api/node/encoder.js.map +0 -1
  118. package/examples/gh/node_modules/typescript/dist/api/node/msgpack.d.ts +0 -32
  119. package/examples/gh/node_modules/typescript/dist/api/node/msgpack.d.ts.map +0 -1
  120. package/examples/gh/node_modules/typescript/dist/api/node/msgpack.js +0 -213
  121. package/examples/gh/node_modules/typescript/dist/api/node/msgpack.js.map +0 -1
  122. package/examples/gh/node_modules/typescript/dist/api/node/node.d.ts +0 -76
  123. package/examples/gh/node_modules/typescript/dist/api/node/node.d.ts.map +0 -1
  124. package/examples/gh/node_modules/typescript/dist/api/node/node.generated.d.ts +0 -182
  125. package/examples/gh/node_modules/typescript/dist/api/node/node.generated.d.ts.map +0 -1
  126. package/examples/gh/node_modules/typescript/dist/api/node/node.generated.js +0 -835
  127. package/examples/gh/node_modules/typescript/dist/api/node/node.generated.js.map +0 -1
  128. package/examples/gh/node_modules/typescript/dist/api/node/node.infrastructure.d.ts +0 -62
  129. package/examples/gh/node_modules/typescript/dist/api/node/node.infrastructure.d.ts.map +0 -1
  130. package/examples/gh/node_modules/typescript/dist/api/node/node.infrastructure.js +0 -122
  131. package/examples/gh/node_modules/typescript/dist/api/node/node.infrastructure.js.map +0 -1
  132. package/examples/gh/node_modules/typescript/dist/api/node/node.js +0 -298
  133. package/examples/gh/node_modules/typescript/dist/api/node/node.js.map +0 -1
  134. package/examples/gh/node_modules/typescript/dist/api/node/protocol.d.ts +0 -29
  135. package/examples/gh/node_modules/typescript/dist/api/node/protocol.d.ts.map +0 -1
  136. package/examples/gh/node_modules/typescript/dist/api/node/protocol.generated.d.ts +0 -4
  137. package/examples/gh/node_modules/typescript/dist/api/node/protocol.generated.d.ts.map +0 -1
  138. package/examples/gh/node_modules/typescript/dist/api/node/protocol.generated.js +0 -241
  139. package/examples/gh/node_modules/typescript/dist/api/node/protocol.generated.js.map +0 -1
  140. package/examples/gh/node_modules/typescript/dist/api/node/protocol.js +0 -30
  141. package/examples/gh/node_modules/typescript/dist/api/node/protocol.js.map +0 -1
  142. package/examples/gh/node_modules/typescript/dist/api/node/wtf8.d.ts +0 -6
  143. package/examples/gh/node_modules/typescript/dist/api/node/wtf8.d.ts.map +0 -1
  144. package/examples/gh/node_modules/typescript/dist/api/node/wtf8.js +0 -61
  145. package/examples/gh/node_modules/typescript/dist/api/node/wtf8.js.map +0 -1
  146. package/examples/gh/node_modules/typescript/dist/api/options.d.ts +0 -32
  147. package/examples/gh/node_modules/typescript/dist/api/options.d.ts.map +0 -1
  148. package/examples/gh/node_modules/typescript/dist/api/options.js +0 -11
  149. package/examples/gh/node_modules/typescript/dist/api/options.js.map +0 -1
  150. package/examples/gh/node_modules/typescript/dist/api/path.d.ts +0 -110
  151. package/examples/gh/node_modules/typescript/dist/api/path.d.ts.map +0 -1
  152. package/examples/gh/node_modules/typescript/dist/api/path.js +0 -508
  153. package/examples/gh/node_modules/typescript/dist/api/path.js.map +0 -1
  154. package/examples/gh/node_modules/typescript/dist/api/proto.d.ts +0 -239
  155. package/examples/gh/node_modules/typescript/dist/api/proto.d.ts.map +0 -1
  156. package/examples/gh/node_modules/typescript/dist/api/proto.js +0 -37
  157. package/examples/gh/node_modules/typescript/dist/api/proto.js.map +0 -1
  158. package/examples/gh/node_modules/typescript/dist/api/sourceFileCache.d.ts +0 -79
  159. package/examples/gh/node_modules/typescript/dist/api/sourceFileCache.d.ts.map +0 -1
  160. package/examples/gh/node_modules/typescript/dist/api/sourceFileCache.js +0 -169
  161. package/examples/gh/node_modules/typescript/dist/api/sourceFileCache.js.map +0 -1
  162. package/examples/gh/node_modules/typescript/dist/api/sync/api.d.ts +0 -529
  163. package/examples/gh/node_modules/typescript/dist/api/sync/api.d.ts.map +0 -1
  164. package/examples/gh/node_modules/typescript/dist/api/sync/api.js +0 -1665
  165. package/examples/gh/node_modules/typescript/dist/api/sync/api.js.map +0 -1
  166. package/examples/gh/node_modules/typescript/dist/api/sync/client.d.ts +0 -30
  167. package/examples/gh/node_modules/typescript/dist/api/sync/client.d.ts.map +0 -1
  168. package/examples/gh/node_modules/typescript/dist/api/sync/client.js +0 -124
  169. package/examples/gh/node_modules/typescript/dist/api/sync/client.js.map +0 -1
  170. package/examples/gh/node_modules/typescript/dist/api/sync/types.d.ts +0 -310
  171. package/examples/gh/node_modules/typescript/dist/api/sync/types.d.ts.map +0 -1
  172. package/examples/gh/node_modules/typescript/dist/api/sync/types.js +0 -2
  173. package/examples/gh/node_modules/typescript/dist/api/sync/types.js.map +0 -1
  174. package/examples/gh/node_modules/typescript/dist/api/syncChannel.d.ts +0 -114
  175. package/examples/gh/node_modules/typescript/dist/api/syncChannel.d.ts.map +0 -1
  176. package/examples/gh/node_modules/typescript/dist/api/syncChannel.js +0 -508
  177. package/examples/gh/node_modules/typescript/dist/api/syncChannel.js.map +0 -1
  178. package/examples/gh/node_modules/typescript/dist/api/timing.d.ts +0 -175
  179. package/examples/gh/node_modules/typescript/dist/api/timing.d.ts.map +0 -1
  180. package/examples/gh/node_modules/typescript/dist/api/timing.js +0 -149
  181. package/examples/gh/node_modules/typescript/dist/api/timing.js.map +0 -1
  182. package/examples/gh/node_modules/typescript/dist/ast/ast.d.ts +0 -100
  183. package/examples/gh/node_modules/typescript/dist/ast/ast.d.ts.map +0 -1
  184. package/examples/gh/node_modules/typescript/dist/ast/ast.generated.d.ts +0 -1161
  185. package/examples/gh/node_modules/typescript/dist/ast/ast.generated.d.ts.map +0 -1
  186. package/examples/gh/node_modules/typescript/dist/ast/ast.generated.js +0 -4
  187. package/examples/gh/node_modules/typescript/dist/ast/ast.generated.js.map +0 -1
  188. package/examples/gh/node_modules/typescript/dist/ast/ast.js +0 -7
  189. package/examples/gh/node_modules/typescript/dist/ast/ast.js.map +0 -1
  190. package/examples/gh/node_modules/typescript/dist/ast/astnav.d.ts +0 -19
  191. package/examples/gh/node_modules/typescript/dist/ast/astnav.d.ts.map +0 -1
  192. package/examples/gh/node_modules/typescript/dist/ast/astnav.js +0 -596
  193. package/examples/gh/node_modules/typescript/dist/ast/astnav.js.map +0 -1
  194. package/examples/gh/node_modules/typescript/dist/ast/clone.d.ts +0 -16
  195. package/examples/gh/node_modules/typescript/dist/ast/clone.d.ts.map +0 -1
  196. package/examples/gh/node_modules/typescript/dist/ast/clone.js +0 -104
  197. package/examples/gh/node_modules/typescript/dist/ast/clone.js.map +0 -1
  198. package/examples/gh/node_modules/typescript/dist/ast/factory.generated.d.ts +0 -520
  199. package/examples/gh/node_modules/typescript/dist/ast/factory.generated.d.ts.map +0 -1
  200. package/examples/gh/node_modules/typescript/dist/ast/factory.generated.js +0 -3057
  201. package/examples/gh/node_modules/typescript/dist/ast/factory.generated.js.map +0 -1
  202. package/examples/gh/node_modules/typescript/dist/ast/index.d.ts +0 -20
  203. package/examples/gh/node_modules/typescript/dist/ast/index.d.ts.map +0 -1
  204. package/examples/gh/node_modules/typescript/dist/ast/index.js +0 -20
  205. package/examples/gh/node_modules/typescript/dist/ast/index.js.map +0 -1
  206. package/examples/gh/node_modules/typescript/dist/ast/is.d.ts +0 -35
  207. package/examples/gh/node_modules/typescript/dist/ast/is.d.ts.map +0 -1
  208. package/examples/gh/node_modules/typescript/dist/ast/is.generated.d.ts +0 -329
  209. package/examples/gh/node_modules/typescript/dist/ast/is.generated.d.ts.map +0 -1
  210. package/examples/gh/node_modules/typescript/dist/ast/is.generated.js +0 -1103
  211. package/examples/gh/node_modules/typescript/dist/ast/is.generated.js.map +0 -1
  212. package/examples/gh/node_modules/typescript/dist/ast/is.js +0 -233
  213. package/examples/gh/node_modules/typescript/dist/ast/is.js.map +0 -1
  214. package/examples/gh/node_modules/typescript/dist/ast/jsdoc.d.ts +0 -11
  215. package/examples/gh/node_modules/typescript/dist/ast/jsdoc.d.ts.map +0 -1
  216. package/examples/gh/node_modules/typescript/dist/ast/jsdoc.js +0 -202
  217. package/examples/gh/node_modules/typescript/dist/ast/jsdoc.js.map +0 -1
  218. package/examples/gh/node_modules/typescript/dist/ast/scanner.d.ts +0 -97
  219. package/examples/gh/node_modules/typescript/dist/ast/scanner.d.ts.map +0 -1
  220. package/examples/gh/node_modules/typescript/dist/ast/scanner.js +0 -2230
  221. package/examples/gh/node_modules/typescript/dist/ast/scanner.js.map +0 -1
  222. package/examples/gh/node_modules/typescript/dist/ast/utils.d.ts +0 -17
  223. package/examples/gh/node_modules/typescript/dist/ast/utils.d.ts.map +0 -1
  224. package/examples/gh/node_modules/typescript/dist/ast/utils.js +0 -67
  225. package/examples/gh/node_modules/typescript/dist/ast/utils.js.map +0 -1
  226. package/examples/gh/node_modules/typescript/dist/ast/visitor.d.ts +0 -14
  227. package/examples/gh/node_modules/typescript/dist/ast/visitor.d.ts.map +0 -1
  228. package/examples/gh/node_modules/typescript/dist/ast/visitor.generated.d.ts +0 -50
  229. package/examples/gh/node_modules/typescript/dist/ast/visitor.generated.d.ts.map +0 -1
  230. package/examples/gh/node_modules/typescript/dist/ast/visitor.generated.js +0 -978
  231. package/examples/gh/node_modules/typescript/dist/ast/visitor.generated.js.map +0 -1
  232. package/examples/gh/node_modules/typescript/dist/ast/visitor.js +0 -47
  233. package/examples/gh/node_modules/typescript/dist/ast/visitor.js.map +0 -1
  234. package/examples/gh/node_modules/typescript/dist/enums/characterCodes.d.ts +0 -2
  235. package/examples/gh/node_modules/typescript/dist/enums/characterCodes.d.ts.map +0 -1
  236. package/examples/gh/node_modules/typescript/dist/enums/characterCodes.enum.d.ts +0 -129
  237. package/examples/gh/node_modules/typescript/dist/enums/characterCodes.enum.d.ts.map +0 -1
  238. package/examples/gh/node_modules/typescript/dist/enums/characterCodes.enum.js +0 -132
  239. package/examples/gh/node_modules/typescript/dist/enums/characterCodes.enum.js.map +0 -1
  240. package/examples/gh/node_modules/typescript/dist/enums/characterCodes.js +0 -130
  241. package/examples/gh/node_modules/typescript/dist/enums/characterCodes.js.map +0 -1
  242. package/examples/gh/node_modules/typescript/dist/enums/commentDirectiveType.d.ts +0 -2
  243. package/examples/gh/node_modules/typescript/dist/enums/commentDirectiveType.d.ts.map +0 -1
  244. package/examples/gh/node_modules/typescript/dist/enums/commentDirectiveType.enum.d.ts +0 -5
  245. package/examples/gh/node_modules/typescript/dist/enums/commentDirectiveType.enum.d.ts.map +0 -1
  246. package/examples/gh/node_modules/typescript/dist/enums/commentDirectiveType.enum.js +0 -6
  247. package/examples/gh/node_modules/typescript/dist/enums/commentDirectiveType.enum.js.map +0 -1
  248. package/examples/gh/node_modules/typescript/dist/enums/commentDirectiveType.js +0 -6
  249. package/examples/gh/node_modules/typescript/dist/enums/commentDirectiveType.js.map +0 -1
  250. package/examples/gh/node_modules/typescript/dist/enums/completionItemKind.d.ts +0 -2
  251. package/examples/gh/node_modules/typescript/dist/enums/completionItemKind.d.ts.map +0 -1
  252. package/examples/gh/node_modules/typescript/dist/enums/completionItemKind.enum.d.ts +0 -28
  253. package/examples/gh/node_modules/typescript/dist/enums/completionItemKind.enum.d.ts.map +0 -1
  254. package/examples/gh/node_modules/typescript/dist/enums/completionItemKind.enum.js +0 -30
  255. package/examples/gh/node_modules/typescript/dist/enums/completionItemKind.enum.js.map +0 -1
  256. package/examples/gh/node_modules/typescript/dist/enums/completionItemKind.js +0 -30
  257. package/examples/gh/node_modules/typescript/dist/enums/completionItemKind.js.map +0 -1
  258. package/examples/gh/node_modules/typescript/dist/enums/diagnosticCategory.d.ts +0 -2
  259. package/examples/gh/node_modules/typescript/dist/enums/diagnosticCategory.d.ts.map +0 -1
  260. package/examples/gh/node_modules/typescript/dist/enums/diagnosticCategory.enum.d.ts +0 -7
  261. package/examples/gh/node_modules/typescript/dist/enums/diagnosticCategory.enum.d.ts.map +0 -1
  262. package/examples/gh/node_modules/typescript/dist/enums/diagnosticCategory.enum.js +0 -9
  263. package/examples/gh/node_modules/typescript/dist/enums/diagnosticCategory.enum.js.map +0 -1
  264. package/examples/gh/node_modules/typescript/dist/enums/diagnosticCategory.js +0 -9
  265. package/examples/gh/node_modules/typescript/dist/enums/diagnosticCategory.js.map +0 -1
  266. package/examples/gh/node_modules/typescript/dist/enums/elementFlags.d.ts +0 -2
  267. package/examples/gh/node_modules/typescript/dist/enums/elementFlags.d.ts.map +0 -1
  268. package/examples/gh/node_modules/typescript/dist/enums/elementFlags.enum.d.ts +0 -12
  269. package/examples/gh/node_modules/typescript/dist/enums/elementFlags.enum.d.ts.map +0 -1
  270. package/examples/gh/node_modules/typescript/dist/enums/elementFlags.enum.js +0 -14
  271. package/examples/gh/node_modules/typescript/dist/enums/elementFlags.enum.js.map +0 -1
  272. package/examples/gh/node_modules/typescript/dist/enums/elementFlags.js +0 -14
  273. package/examples/gh/node_modules/typescript/dist/enums/elementFlags.js.map +0 -1
  274. package/examples/gh/node_modules/typescript/dist/enums/internalSymbolName.d.ts +0 -2
  275. package/examples/gh/node_modules/typescript/dist/enums/internalSymbolName.d.ts.map +0 -1
  276. package/examples/gh/node_modules/typescript/dist/enums/internalSymbolName.enum.d.ts +0 -23
  277. package/examples/gh/node_modules/typescript/dist/enums/internalSymbolName.enum.d.ts.map +0 -1
  278. package/examples/gh/node_modules/typescript/dist/enums/internalSymbolName.enum.js +0 -25
  279. package/examples/gh/node_modules/typescript/dist/enums/internalSymbolName.enum.js.map +0 -1
  280. package/examples/gh/node_modules/typescript/dist/enums/internalSymbolName.js +0 -25
  281. package/examples/gh/node_modules/typescript/dist/enums/internalSymbolName.js.map +0 -1
  282. package/examples/gh/node_modules/typescript/dist/enums/jsxEmit.d.ts +0 -2
  283. package/examples/gh/node_modules/typescript/dist/enums/jsxEmit.d.ts.map +0 -1
  284. package/examples/gh/node_modules/typescript/dist/enums/jsxEmit.enum.d.ts +0 -9
  285. package/examples/gh/node_modules/typescript/dist/enums/jsxEmit.enum.d.ts.map +0 -1
  286. package/examples/gh/node_modules/typescript/dist/enums/jsxEmit.enum.js +0 -11
  287. package/examples/gh/node_modules/typescript/dist/enums/jsxEmit.enum.js.map +0 -1
  288. package/examples/gh/node_modules/typescript/dist/enums/jsxEmit.js +0 -11
  289. package/examples/gh/node_modules/typescript/dist/enums/jsxEmit.js.map +0 -1
  290. package/examples/gh/node_modules/typescript/dist/enums/languageVariant.d.ts +0 -2
  291. package/examples/gh/node_modules/typescript/dist/enums/languageVariant.d.ts.map +0 -1
  292. package/examples/gh/node_modules/typescript/dist/enums/languageVariant.enum.d.ts +0 -5
  293. package/examples/gh/node_modules/typescript/dist/enums/languageVariant.enum.d.ts.map +0 -1
  294. package/examples/gh/node_modules/typescript/dist/enums/languageVariant.enum.js +0 -6
  295. package/examples/gh/node_modules/typescript/dist/enums/languageVariant.enum.js.map +0 -1
  296. package/examples/gh/node_modules/typescript/dist/enums/languageVariant.js +0 -6
  297. package/examples/gh/node_modules/typescript/dist/enums/languageVariant.js.map +0 -1
  298. package/examples/gh/node_modules/typescript/dist/enums/modifierFlags.d.ts +0 -2
  299. package/examples/gh/node_modules/typescript/dist/enums/modifierFlags.d.ts.map +0 -1
  300. package/examples/gh/node_modules/typescript/dist/enums/modifierFlags.enum.d.ts +0 -42
  301. package/examples/gh/node_modules/typescript/dist/enums/modifierFlags.enum.d.ts.map +0 -1
  302. package/examples/gh/node_modules/typescript/dist/enums/modifierFlags.enum.js +0 -44
  303. package/examples/gh/node_modules/typescript/dist/enums/modifierFlags.enum.js.map +0 -1
  304. package/examples/gh/node_modules/typescript/dist/enums/modifierFlags.js +0 -44
  305. package/examples/gh/node_modules/typescript/dist/enums/modifierFlags.js.map +0 -1
  306. package/examples/gh/node_modules/typescript/dist/enums/moduleDetectionKind.d.ts +0 -2
  307. package/examples/gh/node_modules/typescript/dist/enums/moduleDetectionKind.d.ts.map +0 -1
  308. package/examples/gh/node_modules/typescript/dist/enums/moduleDetectionKind.enum.d.ts +0 -7
  309. package/examples/gh/node_modules/typescript/dist/enums/moduleDetectionKind.enum.d.ts.map +0 -1
  310. package/examples/gh/node_modules/typescript/dist/enums/moduleDetectionKind.enum.js +0 -9
  311. package/examples/gh/node_modules/typescript/dist/enums/moduleDetectionKind.enum.js.map +0 -1
  312. package/examples/gh/node_modules/typescript/dist/enums/moduleDetectionKind.js +0 -9
  313. package/examples/gh/node_modules/typescript/dist/enums/moduleDetectionKind.js.map +0 -1
  314. package/examples/gh/node_modules/typescript/dist/enums/moduleKind.d.ts +0 -2
  315. package/examples/gh/node_modules/typescript/dist/enums/moduleKind.d.ts.map +0 -1
  316. package/examples/gh/node_modules/typescript/dist/enums/moduleKind.enum.d.ts +0 -17
  317. package/examples/gh/node_modules/typescript/dist/enums/moduleKind.enum.d.ts.map +0 -1
  318. package/examples/gh/node_modules/typescript/dist/enums/moduleKind.enum.js +0 -19
  319. package/examples/gh/node_modules/typescript/dist/enums/moduleKind.enum.js.map +0 -1
  320. package/examples/gh/node_modules/typescript/dist/enums/moduleKind.js +0 -19
  321. package/examples/gh/node_modules/typescript/dist/enums/moduleKind.js.map +0 -1
  322. package/examples/gh/node_modules/typescript/dist/enums/moduleResolutionKind.d.ts +0 -2
  323. package/examples/gh/node_modules/typescript/dist/enums/moduleResolutionKind.d.ts.map +0 -1
  324. package/examples/gh/node_modules/typescript/dist/enums/moduleResolutionKind.enum.d.ts +0 -9
  325. package/examples/gh/node_modules/typescript/dist/enums/moduleResolutionKind.enum.d.ts.map +0 -1
  326. package/examples/gh/node_modules/typescript/dist/enums/moduleResolutionKind.enum.js +0 -11
  327. package/examples/gh/node_modules/typescript/dist/enums/moduleResolutionKind.enum.js.map +0 -1
  328. package/examples/gh/node_modules/typescript/dist/enums/moduleResolutionKind.js +0 -11
  329. package/examples/gh/node_modules/typescript/dist/enums/moduleResolutionKind.js.map +0 -1
  330. package/examples/gh/node_modules/typescript/dist/enums/newLineKind.d.ts +0 -2
  331. package/examples/gh/node_modules/typescript/dist/enums/newLineKind.d.ts.map +0 -1
  332. package/examples/gh/node_modules/typescript/dist/enums/newLineKind.enum.d.ts +0 -6
  333. package/examples/gh/node_modules/typescript/dist/enums/newLineKind.enum.d.ts.map +0 -1
  334. package/examples/gh/node_modules/typescript/dist/enums/newLineKind.enum.js +0 -8
  335. package/examples/gh/node_modules/typescript/dist/enums/newLineKind.enum.js.map +0 -1
  336. package/examples/gh/node_modules/typescript/dist/enums/newLineKind.js +0 -8
  337. package/examples/gh/node_modules/typescript/dist/enums/newLineKind.js.map +0 -1
  338. package/examples/gh/node_modules/typescript/dist/enums/nodeBuilderFlags.d.ts +0 -2
  339. package/examples/gh/node_modules/typescript/dist/enums/nodeBuilderFlags.d.ts.map +0 -1
  340. package/examples/gh/node_modules/typescript/dist/enums/nodeBuilderFlags.enum.d.ts +0 -36
  341. package/examples/gh/node_modules/typescript/dist/enums/nodeBuilderFlags.enum.d.ts.map +0 -1
  342. package/examples/gh/node_modules/typescript/dist/enums/nodeBuilderFlags.enum.js +0 -38
  343. package/examples/gh/node_modules/typescript/dist/enums/nodeBuilderFlags.enum.js.map +0 -1
  344. package/examples/gh/node_modules/typescript/dist/enums/nodeBuilderFlags.js +0 -38
  345. package/examples/gh/node_modules/typescript/dist/enums/nodeBuilderFlags.js.map +0 -1
  346. package/examples/gh/node_modules/typescript/dist/enums/nodeFlags.d.ts +0 -2
  347. package/examples/gh/node_modules/typescript/dist/enums/nodeFlags.d.ts.map +0 -1
  348. package/examples/gh/node_modules/typescript/dist/enums/nodeFlags.enum.d.ts +0 -44
  349. package/examples/gh/node_modules/typescript/dist/enums/nodeFlags.enum.d.ts.map +0 -1
  350. package/examples/gh/node_modules/typescript/dist/enums/nodeFlags.enum.js +0 -46
  351. package/examples/gh/node_modules/typescript/dist/enums/nodeFlags.enum.js.map +0 -1
  352. package/examples/gh/node_modules/typescript/dist/enums/nodeFlags.js +0 -46
  353. package/examples/gh/node_modules/typescript/dist/enums/nodeFlags.js.map +0 -1
  354. package/examples/gh/node_modules/typescript/dist/enums/objectFlags.d.ts +0 -2
  355. package/examples/gh/node_modules/typescript/dist/enums/objectFlags.d.ts.map +0 -1
  356. package/examples/gh/node_modules/typescript/dist/enums/objectFlags.enum.d.ts +0 -50
  357. package/examples/gh/node_modules/typescript/dist/enums/objectFlags.enum.d.ts.map +0 -1
  358. package/examples/gh/node_modules/typescript/dist/enums/objectFlags.enum.js +0 -52
  359. package/examples/gh/node_modules/typescript/dist/enums/objectFlags.enum.js.map +0 -1
  360. package/examples/gh/node_modules/typescript/dist/enums/objectFlags.js +0 -52
  361. package/examples/gh/node_modules/typescript/dist/enums/objectFlags.js.map +0 -1
  362. package/examples/gh/node_modules/typescript/dist/enums/outerExpressionKinds.d.ts +0 -2
  363. package/examples/gh/node_modules/typescript/dist/enums/outerExpressionKinds.d.ts.map +0 -1
  364. package/examples/gh/node_modules/typescript/dist/enums/outerExpressionKinds.enum.d.ts +0 -16
  365. package/examples/gh/node_modules/typescript/dist/enums/outerExpressionKinds.enum.d.ts.map +0 -1
  366. package/examples/gh/node_modules/typescript/dist/enums/outerExpressionKinds.enum.js +0 -18
  367. package/examples/gh/node_modules/typescript/dist/enums/outerExpressionKinds.enum.js.map +0 -1
  368. package/examples/gh/node_modules/typescript/dist/enums/outerExpressionKinds.js +0 -18
  369. package/examples/gh/node_modules/typescript/dist/enums/outerExpressionKinds.js.map +0 -1
  370. package/examples/gh/node_modules/typescript/dist/enums/regularExpressionFlags.d.ts +0 -2
  371. package/examples/gh/node_modules/typescript/dist/enums/regularExpressionFlags.d.ts.map +0 -1
  372. package/examples/gh/node_modules/typescript/dist/enums/regularExpressionFlags.enum.d.ts +0 -13
  373. package/examples/gh/node_modules/typescript/dist/enums/regularExpressionFlags.enum.d.ts.map +0 -1
  374. package/examples/gh/node_modules/typescript/dist/enums/regularExpressionFlags.enum.js +0 -14
  375. package/examples/gh/node_modules/typescript/dist/enums/regularExpressionFlags.enum.js.map +0 -1
  376. package/examples/gh/node_modules/typescript/dist/enums/regularExpressionFlags.js +0 -14
  377. package/examples/gh/node_modules/typescript/dist/enums/regularExpressionFlags.js.map +0 -1
  378. package/examples/gh/node_modules/typescript/dist/enums/scriptKind.d.ts +0 -2
  379. package/examples/gh/node_modules/typescript/dist/enums/scriptKind.d.ts.map +0 -1
  380. package/examples/gh/node_modules/typescript/dist/enums/scriptKind.enum.d.ts +0 -11
  381. package/examples/gh/node_modules/typescript/dist/enums/scriptKind.enum.d.ts.map +0 -1
  382. package/examples/gh/node_modules/typescript/dist/enums/scriptKind.enum.js +0 -12
  383. package/examples/gh/node_modules/typescript/dist/enums/scriptKind.enum.js.map +0 -1
  384. package/examples/gh/node_modules/typescript/dist/enums/scriptKind.js +0 -12
  385. package/examples/gh/node_modules/typescript/dist/enums/scriptKind.js.map +0 -1
  386. package/examples/gh/node_modules/typescript/dist/enums/scriptTarget.d.ts +0 -2
  387. package/examples/gh/node_modules/typescript/dist/enums/scriptTarget.d.ts.map +0 -1
  388. package/examples/gh/node_modules/typescript/dist/enums/scriptTarget.enum.d.ts +0 -17
  389. package/examples/gh/node_modules/typescript/dist/enums/scriptTarget.enum.d.ts.map +0 -1
  390. package/examples/gh/node_modules/typescript/dist/enums/scriptTarget.enum.js +0 -18
  391. package/examples/gh/node_modules/typescript/dist/enums/scriptTarget.enum.js.map +0 -1
  392. package/examples/gh/node_modules/typescript/dist/enums/scriptTarget.js +0 -18
  393. package/examples/gh/node_modules/typescript/dist/enums/scriptTarget.js.map +0 -1
  394. package/examples/gh/node_modules/typescript/dist/enums/signatureFlags.d.ts +0 -2
  395. package/examples/gh/node_modules/typescript/dist/enums/signatureFlags.d.ts.map +0 -1
  396. package/examples/gh/node_modules/typescript/dist/enums/signatureFlags.enum.d.ts +0 -15
  397. package/examples/gh/node_modules/typescript/dist/enums/signatureFlags.enum.d.ts.map +0 -1
  398. package/examples/gh/node_modules/typescript/dist/enums/signatureFlags.enum.js +0 -17
  399. package/examples/gh/node_modules/typescript/dist/enums/signatureFlags.enum.js.map +0 -1
  400. package/examples/gh/node_modules/typescript/dist/enums/signatureFlags.js +0 -17
  401. package/examples/gh/node_modules/typescript/dist/enums/signatureFlags.js.map +0 -1
  402. package/examples/gh/node_modules/typescript/dist/enums/signatureKind.d.ts +0 -2
  403. package/examples/gh/node_modules/typescript/dist/enums/signatureKind.d.ts.map +0 -1
  404. package/examples/gh/node_modules/typescript/dist/enums/signatureKind.enum.d.ts +0 -5
  405. package/examples/gh/node_modules/typescript/dist/enums/signatureKind.enum.d.ts.map +0 -1
  406. package/examples/gh/node_modules/typescript/dist/enums/signatureKind.enum.js +0 -7
  407. package/examples/gh/node_modules/typescript/dist/enums/signatureKind.enum.js.map +0 -1
  408. package/examples/gh/node_modules/typescript/dist/enums/signatureKind.js +0 -7
  409. package/examples/gh/node_modules/typescript/dist/enums/signatureKind.js.map +0 -1
  410. package/examples/gh/node_modules/typescript/dist/enums/symbolFlags.d.ts +0 -2
  411. package/examples/gh/node_modules/typescript/dist/enums/symbolFlags.d.ts.map +0 -1
  412. package/examples/gh/node_modules/typescript/dist/enums/symbolFlags.enum.d.ts +0 -71
  413. package/examples/gh/node_modules/typescript/dist/enums/symbolFlags.enum.d.ts.map +0 -1
  414. package/examples/gh/node_modules/typescript/dist/enums/symbolFlags.enum.js +0 -73
  415. package/examples/gh/node_modules/typescript/dist/enums/symbolFlags.enum.js.map +0 -1
  416. package/examples/gh/node_modules/typescript/dist/enums/symbolFlags.js +0 -73
  417. package/examples/gh/node_modules/typescript/dist/enums/symbolFlags.js.map +0 -1
  418. package/examples/gh/node_modules/typescript/dist/enums/syntaxKind.d.ts +0 -2
  419. package/examples/gh/node_modules/typescript/dist/enums/syntaxKind.d.ts.map +0 -1
  420. package/examples/gh/node_modules/typescript/dist/enums/syntaxKind.enum.d.ts +0 -389
  421. package/examples/gh/node_modules/typescript/dist/enums/syntaxKind.enum.d.ts.map +0 -1
  422. package/examples/gh/node_modules/typescript/dist/enums/syntaxKind.enum.js +0 -391
  423. package/examples/gh/node_modules/typescript/dist/enums/syntaxKind.enum.js.map +0 -1
  424. package/examples/gh/node_modules/typescript/dist/enums/syntaxKind.js +0 -391
  425. package/examples/gh/node_modules/typescript/dist/enums/syntaxKind.js.map +0 -1
  426. package/examples/gh/node_modules/typescript/dist/enums/tokenFlags.d.ts +0 -2
  427. package/examples/gh/node_modules/typescript/dist/enums/tokenFlags.d.ts.map +0 -1
  428. package/examples/gh/node_modules/typescript/dist/enums/tokenFlags.enum.d.ts +0 -30
  429. package/examples/gh/node_modules/typescript/dist/enums/tokenFlags.enum.d.ts.map +0 -1
  430. package/examples/gh/node_modules/typescript/dist/enums/tokenFlags.enum.js +0 -32
  431. package/examples/gh/node_modules/typescript/dist/enums/tokenFlags.enum.js.map +0 -1
  432. package/examples/gh/node_modules/typescript/dist/enums/tokenFlags.js +0 -32
  433. package/examples/gh/node_modules/typescript/dist/enums/tokenFlags.js.map +0 -1
  434. package/examples/gh/node_modules/typescript/dist/enums/typeFlags.d.ts +0 -2
  435. package/examples/gh/node_modules/typescript/dist/enums/typeFlags.d.ts.map +0 -1
  436. package/examples/gh/node_modules/typescript/dist/enums/typeFlags.enum.d.ts +0 -76
  437. package/examples/gh/node_modules/typescript/dist/enums/typeFlags.enum.d.ts.map +0 -1
  438. package/examples/gh/node_modules/typescript/dist/enums/typeFlags.enum.js +0 -78
  439. package/examples/gh/node_modules/typescript/dist/enums/typeFlags.enum.js.map +0 -1
  440. package/examples/gh/node_modules/typescript/dist/enums/typeFlags.js +0 -78
  441. package/examples/gh/node_modules/typescript/dist/enums/typeFlags.js.map +0 -1
  442. package/examples/gh/node_modules/typescript/dist/enums/typePredicateKind.d.ts +0 -2
  443. package/examples/gh/node_modules/typescript/dist/enums/typePredicateKind.d.ts.map +0 -1
  444. package/examples/gh/node_modules/typescript/dist/enums/typePredicateKind.enum.d.ts +0 -7
  445. package/examples/gh/node_modules/typescript/dist/enums/typePredicateKind.enum.d.ts.map +0 -1
  446. package/examples/gh/node_modules/typescript/dist/enums/typePredicateKind.enum.js +0 -9
  447. package/examples/gh/node_modules/typescript/dist/enums/typePredicateKind.enum.js.map +0 -1
  448. package/examples/gh/node_modules/typescript/dist/enums/typePredicateKind.js +0 -9
  449. package/examples/gh/node_modules/typescript/dist/enums/typePredicateKind.js.map +0 -1
  450. package/examples/gh/node_modules/typescript/dist/internal/utils.d.ts +0 -23
  451. package/examples/gh/node_modules/typescript/dist/internal/utils.d.ts.map +0 -1
  452. package/examples/gh/node_modules/typescript/dist/internal/utils.js +0 -25
  453. package/examples/gh/node_modules/typescript/dist/internal/utils.js.map +0 -1
  454. package/examples/gh/node_modules/typescript/lib/getExePath.d.ts +0 -2
  455. package/examples/gh/node_modules/typescript/lib/getExePath.js +0 -70
  456. package/examples/gh/node_modules/typescript/lib/tsc.js +0 -28
  457. package/examples/gh/node_modules/typescript/lib/version.cjs +0 -3
  458. package/examples/gh/node_modules/typescript/lib/version.d.cts +0 -2
  459. package/examples/gh/node_modules/typescript/package.json +0 -87
  460. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/License.txt +0 -11
  461. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/README.md +0 -54
  462. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/browser/main.d.ts +0 -17
  463. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/browser/main.js +0 -83
  464. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/browser/ril.d.ts +0 -22
  465. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/browser/ril.js +0 -210
  466. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/api.d.ts +0 -14
  467. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/api.js +0 -87
  468. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/cancellation.d.ts +0 -32
  469. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/cancellation.js +0 -132
  470. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/connection.d.ts +0 -367
  471. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/connection.js +0 -1271
  472. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/disposable.d.ts +0 -9
  473. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/disposable.js +0 -16
  474. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/encoding.d.ts +0 -52
  475. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/encoding.js +0 -70
  476. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/events.d.ts +0 -39
  477. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/events.js +0 -135
  478. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/is.d.ts +0 -7
  479. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/is.js +0 -34
  480. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/linkedMap.d.ts +0 -55
  481. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/linkedMap.js +0 -412
  482. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/messageBuffer.d.ts +0 -18
  483. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/messageBuffer.js +0 -155
  484. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/messageReader.d.ts +0 -77
  485. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/messageReader.js +0 -246
  486. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/messageWriter.d.ts +0 -60
  487. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/messageWriter.js +0 -157
  488. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/messages.d.ts +0 -369
  489. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/messages.js +0 -436
  490. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/ral.d.ts +0 -74
  491. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/ral.js +0 -23
  492. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/semaphore.d.ts +0 -10
  493. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/semaphore.js +0 -74
  494. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/sharedArrayCancellation.d.ts +0 -15
  495. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/common/sharedArrayCancellation.js +0 -77
  496. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/node/main.d.ts +0 -58
  497. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/node/main.js +0 -289
  498. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/node/ril.d.ts +0 -12
  499. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/lib/node/ril.js +0 -163
  500. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/package.json +0 -54
  501. package/examples/gh/node_modules/typescript/vendor/vscode-jsonrpc/typings/thenable.d.ts +0 -5
package/CHANGELOG.md CHANGED
@@ -2,199 +2,81 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
- The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
6
- adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
6
 
8
7
  ## [Unreleased]
9
8
 
10
9
  ### Release checklist
11
10
 
12
- - [ ] Set the intended version in `package.json` and `deno.json`, add the dated
13
- changelog section, and update every comparison link.
14
- - [ ] Update first-party DreamCLI pins in documentation and import-map
15
- configuration; do not rewrite versions that belong to transitive lockfile
16
- metadata.
11
+ - [ ] Set the intended version in `package.json` and `deno.json`, add the dated changelog section, and update every comparison link.
12
+ - [ ] Update first-party DreamCLI pins in documentation and import-map configuration; do not rewrite versions that belong to transitive lockfile metadata.
17
13
  - [ ] Run `runner run -s schema:emit version:check ci smoke`.
18
- - [ ] Pack with `bun pm pack --quiet --ignore-scripts` and inspect the tarball's
19
- files and version.
14
+ - [ ] Pack with `bun pm pack --quiet --ignore-scripts` and inspect the tarball's files and version.
20
15
  - [ ] Confirm generators and formatters leave no unexpected worktree changes.
21
- - [ ] Commit and push the release preparation, then verify the target commit is
22
- signed, `master` matches the remote, and every required check is green.
23
- - [ ] Confirm the exact `v<version>` tag does not already exist and npm and JSR
24
- do not already contain that version before publishing the GitHub release.
16
+ - [ ] Commit and push the release preparation, then verify the target commit is signed, `master` matches the remote, and every required check is green.
17
+ - [ ] Confirm the exact `v<version>` tag does not already exist and npm and JSR do not already contain that version before publishing the GitHub release.
18
+
19
+ ## [4.0.0-rc.3] - 2026-09-05
20
+
21
+ ### Added
22
+
23
+ - Let `flag.*().describe()` and `arg.*().describe()` accept a function that receives the resolved help theme, keeping semantic highlighting inside prose on the framework's color gate. Add `.help({ descriptionTheme })` for scoped role overrides that merge over the global theme (https://github.com/kjanat/dreamcli/issues/93).
24
+
25
+ ### Fixed
26
+
27
+ - **Published archives exclude generated workspace dependencies and Python bytecode.**\
28
+ npm tarballs no longer include nested `node_modules` trees or `__pycache__` files from packaged examples and skills.
29
+ - **Completion scripts no longer offer surface-only defaults as named commands** (https://github.com/kjanat/dreamcli/pull/127).\
30
+ A command registered with `.default(command)` now exposes its flags only at the root instead of also suggesting a command name that cannot be invoked. Defaults registered with `.default(command, { route: true })` remain available by name in Bash, Zsh, Fish, and PowerShell completions.
31
+ - **Explicit hyperlink flags override environment defaults** (https://github.com/kjanat/dreamcli/issues/126).\
32
+ `--hyperlinks` now overrides `NO_HYPERLINKS`, while `--no-hyperlinks` overrides `FORCE_HYPERLINKS`. Without an explicit flag, `NO_HYPERLINKS` still wins over `FORCE_HYPERLINKS`.
25
33
 
26
34
  ## [4.0.0-rc.2] - 2026-08-17
27
35
 
28
36
  ### Fixed
29
37
 
30
- - **Published testkit declarations accept command builders again**
31
- (https://github.com/kjanat/dreamcli/issues/122). `runCommand()` now exposes a declaration-safe
32
- generic `CommandBuilder` parameter while keeping its execution pipeline type-erased internally.
33
- Package builds also compile the public testing example against the emitted declarations so
34
- internal-member stripping cannot silently break this contract again.
38
+ - **Published testkit declarations accept command builders again** (https://github.com/kjanat/dreamcli/issues/122).\
39
+ `runCommand()` now exposes a declaration-safe generic `CommandBuilder` parameter while keeping its execution pipeline type-erased internally. Package builds also compile the public testing example against the emitted declarations so internal-member stripping cannot silently break this contract again.
35
40
 
36
41
  ## [4.0.0-rc.1] - 2026-08-12
37
42
 
38
43
  ### Added
39
44
 
40
- - **Handlers can see where each value came from**
41
- ([#90](https://github.com/kjanat/dreamcli/issues/90)). `ActionParams`,
42
- `DeriveParams`, and `MiddlewareParams` gain `sources`, keyed like `flags` and
43
- `args`, holding the full record resolution already produced:
44
- `{ stage: 'cli' }`, `{ stage: 'cli', via: 'stdin', trigger: 'dash' }`,
45
- `{ stage: 'stdin', via: 'stdin', trigger: 'fallback' }`,
46
- `{ stage: 'env', envVar }`, `{ stage: 'config', configPath }`,
47
- `{ stage: 'prompt' }`, or `{ stage: 'default' }`. An input that resolved no
48
- value has no record. `wasExplicit(record)` derives the explicit-versus-defaulted
49
- question from it without dropping `.default()`, which would also drop
50
- `defaultValue` from the definition document. `ResolveResult.provenance` carries
51
- the same records for a direct `resolve()` caller, and `readFlags()` hands them
52
- to a new `onSources` receiver, typed against the definitions record.
53
- `ResolutionProvenance`, `ResolutionProvenanceRecord`, `InputSources`,
54
- `SourcesOf`, and `wasExplicit` are exported from the package root. The existing
55
- `ResolutionProvenance` name continues to describe one input's winning stage;
56
- `ResolutionProvenanceRecord` names the complete `ResolveResult.provenance`
57
- object.
58
-
59
- - **`arg.keyValue()` takes an element builder**
60
- ([#87](https://github.com/kjanat/dreamcli/issues/87)). Entry values used to be
61
- strings on the positional surface while `flag.keyValue(element)` gave them a
62
- codec. `arg.keyValue(arg.number().int().min(0))` now resolves
63
- `mycli scale web=3` to `{ web: 3 }`, with the element's constraints, path
64
- checks, and Standard Schema validator applied to every entry, from every
65
- source. The element is guarded the same way flags guard theirs: `ArgConfig`
66
- gains `elementEligible`, so a builder already described as a positional
67
- (`.optional()`, `.env()`, `.stdin()`, `.describe()`, …) is refused in element
68
- position at compile time. `ArgSchema` gains `elementSchema`, which serializes
69
- into definition documents under the new `ArgElementFragmentV1` shape and the
70
- `$defs.argElement` meta-schema definition.
71
-
72
- - **Help names the stdin source.** An input that declares `.stdin()` renders
73
- `[stdin]` beside the existing `[env: X]`, `[config: y]`, and `[prompt]`
74
- annotations, on the flag table and the argument table alike. The narrower
75
- triggers say which one applies: `[stdin: '-']` for `{ when: 'dash' }` and
76
- `[stdin: when omitted]` for `{ when: 'missing' }`. Completion scripts are
77
- unchanged; they carry the plain description.
78
-
79
- - **A dedicated error code for a dash with nothing piped.**
80
- `ValidationErrorCode` gains `MISSING_STDIN`, which replaces the borrowed
81
- `REQUIRED_FLAG` / `REQUIRED_ARG` on the one failure that is neither: a `-`
82
- typed beside other occurrences of a collection when the stream is empty. Those
83
- two keep their own meaning, a required input no source filled.
84
-
85
- - **A variadic argument reads stdin from its tail.** `.stdin()` and
86
- `.variadic()` now compose. A `-` among the tail tokens stands for the whole
87
- stdin source at that position, so
88
- `printf 'x\ny\n' | mycli build a - b` collects `['a', 'x', 'y', 'b']`, and an
89
- empty tail under a binding that covers a missing input takes the whole buffer.
90
- `arg.keyValue().variadic().stdin()` aggregates entries across the typed tokens
91
- and the pipe under its `.duplicateKeys()` policy. Each `-` stands for all of
92
- the buffer, so two of them splice it twice, and the stream is still read at
93
- most once per invocation. The preflight that decides whether to read stdin
94
- counts an empty tail as an absent input, which is what makes
95
- `printf 'x\ny\n' | mycli build` reach the fallback stage under `.run()`.
96
-
97
- - **`.stdin({ trim: true })` drops the terminator a pipe appends.** Codecs that
98
- preserve text terminators, including `string` and `path`, keep the buffer byte
99
- for byte by default. `trim` drops one trailing `\n`, `\r\n`, or `\r` from a
100
- single value before anything decodes or checks it, so
101
- `echo ./dist | mycli clean` satisfies `arg.path({ mustExist: true })`. It
102
- applies to both surfaces, to an explicit `-` and to the implicit fallback, and
103
- to `readFlags()` and `runCommand()`. Other decoding codecs already remove one
104
- framing terminator and are unaffected, so no value ever loses two. A collection's
105
- terminators separate its elements, so `.split({ stdin })` still decides those.
106
- The binding serializes as `stdin.trim` in definition documents, alongside
107
- `when` and `consume`.
108
-
109
- - **Stability policy and a 4.0 upgrade guide** — the
110
- [stability page](https://dreamcli.kjanat.dev/reference/stability) now places
111
- every export of the root, `/testkit`, `/runtime`, and `/version` entrypoints
112
- in one of thirteen categories, each with the rules it carries into a minor
113
- release: sealed framework values, consumer input options, transparent input
114
- definitions, implementer ports, externally governed protocols, structural
115
- consumer configuration, closed unions and discriminated results, open unions,
116
- framework-produced callback payloads, closed constructible DTOs, serialized
117
- formats, classes and functions, and internal surface.
118
- [Upgrading From 3.x To 4.0](https://dreamcli.kjanat.dev/guide/upgrading-v4)
119
- walks the breaking changes below with before and after code.
120
-
121
- - **Definition types and normalization factories for flags, args, commands, and
122
- the CLI** — `createFlagSchema()`, `createCommandSchema()`, and
123
- `createCLISchema()` join the existing `createArgSchema()`. The flag and arg
124
- factories take a plain definition object, or a kind plus that kind's fields;
125
- the command and CLI factories take complete definition objects. Each returns
126
- the normalized schema; feeding a built schema back in produces a deep-equal
127
- schema, and a field belonging to another kind throws `INVALID_SCHEMA`.
128
- `createCommandSchema()` normalizes nested flags, args, and subcommands, and
129
- `createCLISchema()` normalizes commands and config settings for a description
130
- of a program with no execution graph attached. Each level ships its definition
131
- types: `FlagDefinition`,
132
- `FlagDefinitionBase`, `FlagDefinitionByKind`, `FlagDefinitionOverrides`, and
133
- the per-kind members `StringFlagDefinition`, `NumberFlagDefinition`,
134
- `BooleanFlagDefinition`, `EnumFlagDefinition`, `ArrayFlagDefinition`,
135
- `CustomFlagDefinition`, `CountFlagDefinition`, `KeyValueFlagDefinition`;
136
- `ArgDefinition`, `ArgDefinitionBase`, `ArgDefinitionByKind`,
137
- `ArgDefinitionOverrides`, `StringArgDefinition`, `NumberArgDefinition`,
138
- `EnumArgDefinition`, `CustomArgDefinition`; `CommandDefinition` with
139
- `CommandArgEntryDefinition`; and `CLIDefinition` with
140
- `ConfigSettingsDefinition`. All of them are exported from the package root.
141
-
142
- - **`.builtins()` takes `--help`, `--json`, or `--quiet` over to the commands**
143
- ([#86](https://github.com/kjanat/dreamcli/issues/86)). A CLI whose `--json`
144
- names the document it operates on, whose `-q` means something domain-specific,
145
- or whose `--help` is a routable topic browser can now claim the token.
146
- `cli('mycli').builtins({ json: 'off' })` releases every spelling that built-in
147
- answers to. The root stops reading and stripping it from argv, root help stops
148
- listing it under `Global options:`, the `RESERVED_FLAG` guard stops reserving
149
- it, and a command may declare it as an ordinary flag that parses and reaches
150
- the handler. Releasing `help` also disables command-level `--help`/`-h`, the
151
- bare `help` token, the `--help` footer hint, the
152
- `Run '<bin> --help' for available commands` suggestion on dispatch errors, and
153
- the synthetic `--help` in generated completion scripts. `version` and
154
- `completions` have no entry, since `.version()` and `.completions()` are
155
- opt-in and a CLI declines those by omission. Every built-in defaults to
156
- `'on'`, repeated calls merge with the last mode per built-in winning, and
157
- `RunOptions.jsonMode` / `RunOptions.verbosity` keep working regardless, since
158
- only argv-driven activation is disabled. The state is normalized onto
159
- `CLISchema.builtins` by both `.builtins()` and the `builtins` field of
160
- `createCLISchema()`, an invalid mode throws `INVALID_SCHEMA`, and
161
- `BuiltinsConfig`, `Builtins`, `BuiltinName`, and `BuiltinMode` are exported
162
- from the package root. `runCommand()` from `/testkit` takes the same
163
- `builtins` option so a command owning a released flag can be tested; its
164
- options type is now `RunCommandOptions`. The `RESERVED_FLAG` error offers
165
- `.builtins({ <name>: 'off' })` alongside renaming, and a version discovered by
166
- `.manifest()` filesystem walking now runs the same guard at `.run()` time
167
- instead of silently shadowing a command's `version` flag. That startup failure
168
- is reported the way every other `.run()` startup failure is: the message and
169
- its suggestion go to stderr, `--json` puts the serialized error on stdout, and
170
- the process exits with the error's exit code rather than rejecting the
171
- `.run()` promise.
172
-
173
- - **Definition format v1 — versioned, typed documents** — `generateSchema()`
174
- and `generateCommandSchema()` now emit `schemaVersion: 1`, so a consumer can
175
- tell which format it is reading before parsing the rest. Both return typed
176
- documents instead of `Record<string, unknown>`: `DefinitionDocumentV1` for a
177
- whole CLI, `CommandDefinitionDocumentV1` for a single command, with
178
- `DefinitionDocument` and `CommandDefinitionDocument` aliasing the current
179
- version. Documents are distinct from the fragments nested inside them.
180
- `CommandDefinitionFragmentV1`, `FlagDefinitionFragmentV1`,
181
- `ArgDefinitionFragmentV1`, `ExampleDefinitionFragmentV1`,
182
- `PromptDefinitionFragmentV1`, `PromptChoiceFragmentV1`,
183
- `FlagNegationFragmentV1`, `FlagStringConstraintsFragmentV1`, and
184
- `FlagPathChecksFragmentV1` carry no `schemaVersion` and take the version of
185
- the document they sit in. `generateInputSchema()` is standard JSON Schema and
186
- stays outside the family, typed as `InputSchemaDocument` with
187
- `InputSchemaBranch` and `InputSchemaProperty`. Every one of these is exported
188
- from the package root, and the returned documents remain assignable to
189
- `Record<string, unknown>`. `--help` in `--json` mode serializes through
190
- `generateCommandSchema()`, so that output gains `schemaVersion: 1` as its
191
- first key.
192
-
193
- - **`readFlags()` evaluates a record of flag builders outside a CLI**
194
- ([#107](https://github.com/kjanat/dreamcli/issues/107)). A build script or a
195
- small tool that wants typed options without commands, handlers, or output
196
- channels hands its flags straight to `readFlags()` and awaits the resolved
197
- values, typed by `InferFlags`:
45
+ - **Handlers can see where each value came from** (https://github.com/kjanat/dreamcli/issues/90).\
46
+ `ActionParams`, `DeriveParams`, and `MiddlewareParams` gain `sources`, keyed like `flags` and `args`, holding the full record resolution already produced: `{ stage: 'cli' }`, `{ stage: 'cli', via: 'stdin', trigger: 'dash' }`, `{ stage: 'stdin', via: 'stdin', trigger: 'fallback' }`, `{ stage: 'env', envVar }`, `{ stage: 'config', configPath }`, `{ stage: 'prompt' }`, or `{ stage: 'default' }`. An input that resolved no value has no record. `wasExplicit(record)` derives the explicit-versus-defaulted question from it without dropping `.default()`, which would also drop `defaultValue` from the definition document. `ResolveResult.provenance` carries the same records for a direct `resolve()` caller, and `readFlags()` hands them to a new `onSources` receiver, typed against the definitions record. `ResolutionProvenance`, `ResolutionProvenanceRecord`, `InputSources`, `SourcesOf`, and `wasExplicit` are exported from the package root. The existing `ResolutionProvenance` name continues to describe one input's winning stage; `ResolutionProvenanceRecord` names the complete `ResolveResult.provenance` object.
47
+
48
+ - **`arg.keyValue()` takes an element builder** (https://github.com/kjanat/dreamcli/issues/87).\
49
+ Entry values used to be strings on the positional surface while `flag.keyValue(element)` gave them a codec. `arg.keyValue(arg.number().int().min(0))` now resolves `mycli scale web=3` to `{ web: 3 }`, with the element's constraints, path checks, and Standard Schema validator applied to every entry, from every source. The element is guarded the same way flags guard theirs: `ArgConfig` gains `elementEligible`, so a builder already described as a positional (`.optional()`, `.env()`, `.stdin()`, `.describe()`, …) is refused in element position at compile time. `ArgSchema` gains `elementSchema`, which serializes into definition documents under the new `ArgElementFragmentV1` shape and the `$defs.argElement` meta-schema definition.
50
+
51
+ - **Help names the stdin source.**\
52
+ An input that declares `.stdin()` renders `[stdin]` beside the existing `[env: X]`, `[config: y]`, and `[prompt]` annotations, on the flag table and the argument table alike. The narrower triggers say which one applies: `[stdin: '-']` for `{ when: 'dash' }` and `[stdin: when omitted]` for `{ when: 'missing' }`. Completion scripts are unchanged; they carry the plain description.
53
+
54
+ - **A dedicated error code for a dash with nothing piped.**\
55
+ `ValidationErrorCode` gains `MISSING_STDIN`, which replaces the borrowed `REQUIRED_FLAG` / `REQUIRED_ARG` on the one failure that is neither: a `-` typed beside other occurrences of a collection when the stream is empty. Those two keep their own meaning, a required input no source filled.
56
+
57
+ - **A variadic argument reads stdin from its tail.**\
58
+ `.stdin()` and `.variadic()` now compose. A `-` among the tail tokens stands for the whole stdin source at that position, so `printf 'x\ny\n' | mycli build a - b` collects `['a', 'x', 'y', 'b']`, and an empty tail under a binding that covers a missing input takes the whole buffer. `arg.keyValue().variadic().stdin()` aggregates entries across the typed tokens and the pipe under its `.duplicateKeys()` policy. Each `-` stands for all of the buffer, so two of them splice it twice, and the stream is still read at most once per invocation. The preflight that decides whether to read stdin counts an empty tail as an absent input, which is what makes `printf 'x\ny\n' | mycli build` reach the fallback stage under `.run()`.
59
+
60
+ - **`.stdin({ trim: true })` drops the terminator a pipe appends.**\
61
+ Codecs that preserve text terminators, including `string` and `path`, keep the buffer byte for byte by default. `trim` drops one trailing `\n`, `\r\n`, or `\r` from a single value before anything decodes or checks it, so `echo ./dist | mycli clean` satisfies `arg.path({ mustExist: true })`. It applies to both surfaces, to an explicit `-` and to the implicit fallback, and to `readFlags()` and `runCommand()`. Other decoding codecs already remove one framing terminator and are unaffected, so no value ever loses two. A collection's terminators separate its elements, so `.split({ stdin })` still decides those. The binding serializes as `stdin.trim` in definition documents, alongside `when` and `consume`.
62
+
63
+ - **Stability policy and a 4.0 upgrade guide**\
64
+ The [stability page](https://dreamcli.kjanat.dev/reference/stability) now places every export of the root, `/testkit`, `/runtime`, and `/version` entrypoints in one of thirteen categories, each with the rules it carries into a minor release: sealed framework values, consumer input options, transparent input definitions, implementer ports, externally governed protocols, structural consumer configuration, closed unions and discriminated results, open unions, framework-produced callback payloads, closed constructible DTOs, serialized formats, classes and functions, and internal surface.\
65
+ [Upgrading From 3.x To 4.0](https://dreamcli.kjanat.dev/guide/upgrading-v4) walks the breaking changes below with before and after code.
66
+
67
+ - **Definition types and normalization factories for flags, args, commands, and the CLI**\
68
+ `createFlagSchema()`, `createCommandSchema()`, and `createCLISchema()` join the existing `createArgSchema()`. The flag and arg factories take a plain definition object, or a kind plus that kind's fields; the command and CLI factories take complete definition objects. Each returns the normalized schema; feeding a built schema back in produces a deep-equal schema, and a field belonging to another kind throws `INVALID_SCHEMA`. `createCommandSchema()` normalizes nested flags, args, and subcommands, and `createCLISchema()` normalizes commands and config settings for a description of a program with no execution graph attached.\
69
+ Each level ships its definition types: `FlagDefinition`, `FlagDefinitionBase`, `FlagDefinitionByKind`, `FlagDefinitionOverrides`, and the per-kind members `StringFlagDefinition`, `NumberFlagDefinition`, `BooleanFlagDefinition`, `EnumFlagDefinition`, `ArrayFlagDefinition`, `CustomFlagDefinition`, `CountFlagDefinition`, `KeyValueFlagDefinition`; `ArgDefinition`, `ArgDefinitionBase`, `ArgDefinitionByKind`, `ArgDefinitionOverrides`, `StringArgDefinition`, `NumberArgDefinition`, `EnumArgDefinition`, `CustomArgDefinition`; `CommandDefinition` with `CommandArgEntryDefinition`; and `CLIDefinition` with `ConfigSettingsDefinition`.\
70
+ All of them are exported from the package root.
71
+
72
+ - **`.builtins()` takes `--help`, `--json`, or `--quiet` over to the commands** (https://github.com/kjanat/dreamcli/issues/86).\
73
+ A CLI whose `--json` names the document it operates on, whose `-q` means something domain-specific, or whose `--help` is a routable topic browser can now claim the token. `cli('mycli').builtins({ json: 'off' })` releases every spelling that built-in answers to. The root stops reading and stripping it from argv, root help stops listing it under `Global options:`, the `RESERVED_FLAG` guard stops reserving it, and a command may declare it as an ordinary flag that parses and reaches the handler. Releasing `help` also disables command-level `--help`/`-h`, the bare `help` token, the `--help` footer hint, the `Run '<bin> --help' for available commands` suggestion on dispatch errors, and the synthetic `--help` in generated completion scripts. `version` and `completions` have no entry, since `.version()` and `.completions()` are opt-in and a CLI declines those by omission. Every built-in defaults to `'on'`, repeated calls merge with the last mode per built-in winning, and `RunOptions.jsonMode` / `RunOptions.verbosity` keep working regardless, since only argv-driven activation is disabled. The state is normalized onto `CLISchema.builtins` by both `.builtins()` and the `builtins` field of `createCLISchema()`, an invalid mode throws `INVALID_SCHEMA`, and `BuiltinsConfig`, `Builtins`, `BuiltinName`, and `BuiltinMode` are exported from the package root. `runCommand()` from `/testkit` takes the same `builtins` option so a command owning a released flag can be tested; its options type is now `RunCommandOptions`. The `RESERVED_FLAG` error offers `.builtins({ <name>: 'off' })` alongside renaming, and a version discovered by `.manifest()` filesystem walking now runs the same guard at `.run()` time instead of silently shadowing a command's `version` flag. That startup failure is reported the way every other `.run()` startup failure is: the message and its suggestion go to stderr, `--json` puts the serialized error on stdout, and the process exits with the error's exit code rather than rejecting the `.run()` promise.
74
+
75
+ - **Definition format v1 — versioned, typed documents**\
76
+ `generateSchema()` and `generateCommandSchema()` now emit `schemaVersion: 1`, so a consumer can tell which format it is reading before parsing the rest. Both return typed documents instead of `Record<string, unknown>`: `DefinitionDocumentV1` for a whole CLI, `CommandDefinitionDocumentV1` for a single command, with `DefinitionDocument` and `CommandDefinitionDocument` aliasing the current version. Documents are distinct from the fragments nested inside them. `CommandDefinitionFragmentV1`, `FlagDefinitionFragmentV1`, `ArgDefinitionFragmentV1`, `ExampleDefinitionFragmentV1`, `PromptDefinitionFragmentV1`, `PromptChoiceFragmentV1`, `FlagNegationFragmentV1`, `FlagStringConstraintsFragmentV1`, and `FlagPathChecksFragmentV1` carry no `schemaVersion` and take the version of the document they sit in. `generateInputSchema()` is standard JSON Schema and stays outside the family, typed as `InputSchemaDocument` with `InputSchemaBranch` and `InputSchemaProperty`. Every one of these is exported from the package root, and the returned documents remain assignable to `Record<string, unknown>`. `--help` in `--json` mode serializes through `generateCommandSchema()`, so that output gains `schemaVersion: 1` as its first key.
77
+
78
+ - **`readFlags()` evaluates a record of flag builders outside a CLI** (https://github.com/kjanat/dreamcli/issues/107).\
79
+ A build script or a small tool that wants typed options without commands, handlers, or output channels hands its flags straight to `readFlags()` and awaits the resolved values, typed by `InferFlags`:
198
80
 
199
81
  ```ts
200
82
  const options = await readFlags({
@@ -207,1558 +89,565 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
207
89
  options.target; // 'node' | 'browser'
208
90
  ```
209
91
 
210
- Each object key is the canonical flag name, and evaluation runs through the
211
- same command schema, parser, coercion, resolver, and validation a command
212
- uses. Aliases, negated spellings, duplicate policy, case parity, unknown-flag
213
- rejection, collisions between names, aliases and negated forms, the CLI,
214
- stdin, env, config, prompt, default precedence, constraints, Standard Schema
215
- validators, and `flag.path()` checks all behave as they do inside `.action()`.
216
- `argv`, `env`, `stdinData`, `stat`, and `mkdir` fall back to the detected
217
- `RuntimeAdapter`, while
218
- `config` and `prompter` stay caller-supplied, since standalone flag reading
219
- has no application name to discover a file from and opens no terminal session.
220
- `ReadFlagsOptions` extends `ResolveOptions` with `argv`, `adapter`, `parse`,
221
- `strict`, `help`, and `onDeprecation`. The adapter is built on the first fact
222
- the caller left
223
- out, so a call given `argv` and `env` reads nothing from the host unless a
224
- `flag.path()` check needs the adapter's filesystem primitives. Failures throw
225
- `ParseError` and `ValidationError` instead of exiting, a colliding record, the
226
- definition key `__proto__`, and a record whose prototype is replaced (an
227
- object-literal `__proto__` key, or `Object.create(base)`, whose inherited
228
- definitions are never read) each throw `CLIError` before argv is read, and
229
- `.deprecated()` notices reach `onDeprecation` rather than a warning stream,
230
- since there is no output channel on this path.
231
-
232
- A pre-separator `--help` or `-h` prints generated help for the record to the
233
- adapter's stdout and exits with code 0, with the script named from the
234
- adapter's argv in the usage line. The built-in yields to a definition that
235
- claims the `help` or `h` spelling through a name, alias, negated form, or
236
- case-parity counterpart, and `help: 'off'` removes it entirely; `json` and
237
- `quiet` are never reserved, so a record may declare them as ordinary flags.
238
- `strict: false` drops undeclared argv content instead of rejecting it: unknown
239
- long flags with their inline `=value`, unknown short-group characters,
240
- positional arguments, and the `--` separator, while value tokens of declared
241
- flags survive under the parser's own consumption rules and misuse of a
242
- declared flag keeps its diagnostics.
243
-
244
- Positional arguments are not part of this API, and there is no
245
- synchronous variant: prompts, async validators, and filesystem checks make the
246
- result a promise. `readFlags`, `ReadFlagsOptions`, and `FlagMap` are exported
247
- from the package root, and
248
- [Standalone Flag Evaluation](https://dreamcli.kjanat.dev/guide/read-flags)
249
- walks the API with the build-script case it was added for.
250
-
251
- - **Purpose-built positional argument kinds and string constraints**
252
- ([#87](https://github.com/kjanat/dreamcli/issues/87)). A base URL, an input
253
- file, or a cutoff date reads naturally as a positional, and until now the only
254
- route was `arg.custom()` re-implementing what `flag.url()` already did.
255
- `arg.url(options?)`, `arg.path(options?)`, `arg.date(options?)`,
256
- `arg.duration()`, and `arg.bytes()` mirror their flag counterparts: same value
257
- types, same option objects (`UrlFlagOptions`, `PathFlagOptions`,
258
- `DateFlagOptions`), same parsers. `arg.string()` takes a `StringConstraints`
259
- object, and string-kind `ArgBuilder`s carry `.nonEmpty()`, `.minLength()`,
260
- `.maxLength()`, and `.pattern()` alongside the numeric `.int()`, `.min()`,
261
- `.max()`, and `.finite()` they already had. Both factories run the same parse
262
- functions and the same constraint validator, so a value a flag accepts an
263
- argument accepts, and a rejection carries the same code and the same reason,
264
- differing in the subject: `for flag --x` versus `for argument <x>`.
265
-
266
- String constraints are enforced on CLI parse (`INVALID_VALUE`) and on stdin,
267
- env, config, and prompt resolution (`CONSTRAINT_VIOLATED`), both exit code
268
- `2`; as with flags, a `.default()` value is checked where it is declared and a
269
- violation throws `INVALID_DEFAULT`. `arg.path()`
270
- checks run after resolution through the runtime adapter's `stat`/`mkdir`, the
271
- same seam `flag.path()` uses, so a piped, env-sourced, config-sourced,
272
- prompted, or defaulted path is checked like one typed on the command line. A
273
- variadic argument validates every value it collects, path checks included.
274
- Argument values sourced from anywhere but argv stay redacted in the message,
275
- as in `Invalid value '<redacted>' from stdin for argument <x>` and
276
- `Invalid number value '<redacted>' from config deploy.port for argument <x>`,
277
- so the flag and argument messages are equivalent apart from their subjects.
278
-
279
- `ArgSchema` and the arg definition types carry `stringConstraints`,
280
- `pathChecks`, and `valueHint`. The first two are string-kind gated the way the
281
- flag schema gates them. Args serialize `numberConstraints`,
282
- `stringConstraints`, `pathChecks`, and `valueHint` into the definition
283
- document, which previously emitted none of them, and `generateInputSchema()`
284
- now surfaces arg string constraints as `minLength` / `maxLength` / `pattern`.
285
- The meta-schema hoists the `numberConstraints`, `stringConstraints`, and
286
- `pathChecks` fragments into `$defs` so the flag and arg definitions reference
287
- one copy. All of it is additive at `schemaVersion: 1`. Help still renders a
288
- positional by its own name rather than its `valueHint`, so
289
- `mycli copy <src> <dst>` does not collapse into `<path> <path>`.
290
-
291
- The flag-only surface stays flag-only, and
292
- [the arguments guide](https://dreamcli.kjanat.dev/guide/arguments#flag-only-surface)
293
- lists it with the reason for each entry. `boolean`, `count`, `negatable`,
294
- `alias`, `duplicates`, `separator`, `unique`, and `propagate` are bound to
295
- flag syntax; `array` is served by `.variadic()`. `keyValue` merges repeated
296
- occurrences into one record, which a positional slot cannot express, and
297
- `arg.custom()` with a Standard Schema validator is the documented route.
298
- `.config()` and `.prompt()` are no longer among them: both surfaces now
299
- declare the same sources, described in the unified source model entry below.
300
-
301
- - **A unified source model — every input uses the same source order** — flags and
302
- args now declare sources from the same set and resolve declared sources through
303
- one ordered chain:
304
- `CLI -> stdin -> env -> config -> prompt -> default`. `arg.config(path)` and
305
- `arg.prompt(config)` join `arg.env()`, so a positional reads a dotted config
306
- key and asks the user exactly as a flag does; the arg prompt table mirrors the
307
- flag one (`PromptConfigByArgKind`, `AllowedArgPromptConfig`), and an
308
- incompatible pairing throws `CONSTRAINT_VIOLATED` naming `<arg>`. Help
309
- annotates a positional with `[config: PATH]` and `[prompt]` beside the
310
- `[env: VAR]` it already showed.
311
- `flag.string().stdin()` becomes legal on `string`, `number`, `boolean`,
312
- `enum`, and `custom` flags, giving `echo hi | mycli send` and
313
- `mycli send --body -` the meaning `arg.stdin()` already had. `.stdin()` takes
314
- `{ when: 'dash' | 'missing' | 'dash-or-missing', consume: 'exclusive' |
315
- 'broadcast' }` on both surfaces, defaulting to `dash-or-missing` and
316
- `exclusive`. `StdinBinding`, `StdinOptions`, `StdinWhen`, and `StdinConsume`
317
- are exported from the package root, and `StdinBindingFragmentV1` names the
318
- serialized form.
319
-
320
- An explicit `-` is CLI-sourced with bytes from stdin and keeps CLI precedence;
321
- an absent input takes the stdin fallback stage, which sits ahead of env, so a
322
- flag set in the environment still reads a pipe and the pipe wins. The `-`
323
- sentinel now survives the parse boundary for every kind, so
324
- `flag.number().stdin()` accepts `--port -` where it used to reject `-` as a
325
- malformed number. `readFlags()` carries the same contract and reads stdin only
326
- through the adapter, only when a declared `.stdin()` flag would actually
327
- select it; `runCommand()` feeds the identical path from its `stdinData`
328
- option. Stdin is read at most once per invocation, and only when resolution
329
- will select it: `when: 'dash'` reads on `-` alone, `when: 'missing'` reads on
330
- an absent input alone, and env, config, prompt, and a default never suppress
331
- the read.
332
-
333
- One command has one exclusive stdin consumer. Declaring a second stdin input
334
- of any kind, flag or arg, throws `DUPLICATE_STDIN_INPUT` on both construction
335
- paths; `{ consume: 'broadcast' }` on every stdin input opts into sharing one
336
- buffer among them. The definition document carries the binding as
337
- `stdin: { when, consume }` on flags and args, with a `stdin` entry in the
338
- meta-schema `$defs`, and the arg fragment gains `configPath` and `prompt`.
339
-
340
- - **Cardinality is its own axis, with per-source splitting.** How many values an
341
- input carries (`one`, `many`, `entries`, `count`) is now decided separately
342
- from what each value means, so every source fills a collection by the same
343
- rules. `.split({ cli, env, stdin })` on `flag.array()`, `flag.keyValue()`, and
344
- the arg builders sets each source's decoding independently: a delimiter or
345
- `'whole'` for CLI tokens, a delimiter, `'whole'`, or `{ format: 'json' }` for
346
- env values, and `'lines'`, `'whole'`, a delimiter, or `{ format: 'json' }` for
347
- the stdin buffer. Defaults are whole CLI tokens (or the `.separator()`
348
- delimiter), comma-delimited env values, and line-delimited stdin; a config
349
- value stays a native array or object, and a config string decodes under the
350
- env policy. JSON is never guessed. `SplitOptions`, `SplitSetting`,
351
- `SplitPolicy`, `SplitBinding`, `SourceSplitBinding`, and `SplitFormat` are
352
- exported from the package root, and the definition document carries `split` on
353
- flag and arg fragments as `SourceSplitFragmentV1` / `SplitPolicyFragmentV1`.
354
-
355
- - **Collections read stdin, and `-` splices into occurrence order.**
356
- `flag.array()` and `flag.keyValue()` accept `.stdin()`, and a `-` occurrence
357
- stands for the whole stdin source at the position it holds:
358
- `--tag before --tag - --tag after` over `a\nb\n` resolves to
359
- `['before', 'a', 'b', 'after']`. An explicit `-` and the implicit fallback
360
- decode identically, entries splice the same way, and the duplicate-key policy
361
- applies across the whole spliced order. Broadcast consumers each decode the
362
- one shared buffer under their own binding, so a line-split array flag and a
363
- JSON key-value flag can read the same pipe.
364
-
365
- - **`.duplicateKeys()` on key-value inputs.** `'last'` (the default), `'first'`,
366
- or `'error'` decides what a repeated key means, on every source rather than
367
- only on repeated CLI occurrences. A repeat under `'error'` reports
368
- `CONSTRAINT_VIOLATED` naming the key. `DuplicateKeys` is exported from the
369
- package root and the policy is serialized as `duplicateKeys`.
370
-
371
- - **`arg.boolean()` and `arg.keyValue()`.** A positional carries no presence
372
- semantics, so `arg.boolean()` consumes an explicit `true`/`false` (or `1`/`0`)
373
- token through the shared boolean codec, widening to `yes`/`no` and an empty
374
- string only for env, config, stdin, and prompt values. `arg.keyValue()`
375
- consumes `KEY=VALUE` tokens and resolves to `Record<string, string>`, splitting
376
- at the first `=`; the variadic form aggregates the whole tail into one record.
377
- `BooleanArgDefinition` and `KeyValueArgDefinition` join the definition types,
378
- and `ArgKind` gains `'boolean'` and `'keyValue'`.
379
-
380
- - **Element-level sugar inside collections.** Path checks and constraints belong
381
- to the element, so `flag.array(flag.path({ mustExist: true }))` checks every
382
- collected element and `flag.keyValue(flag.path())` checks every entry value.
383
- `flag.keyValue()` takes an optional element builder, and `flag.path()` is now
384
- element-eligible.
385
-
386
- - **`.standard()` on both builders, split into element and aggregate
387
- validation.** A validator declared on an element builder
388
- (`flag.array(flag.string().standard(s))`) validates each item or entry value;
389
- one declared on a builder that already aggregates
390
- (`flag.array(flag.string()).standard(s)`, `arg.string().variadic().standard(s)`)
391
- validates the completed array or record after every element passed. Element
392
- issues name the element (`--tag[1]`, `--vars.KEY`). Sync and async validators
393
- are both awaited, and every source runs the same pipeline.
394
-
395
- - **`.unique()` and `.separator()` on args.** A variadic arg deduplicates with
396
- the same `SameValueZero` semantics an array flag uses, and splits each
397
- positional token on the CLI separator it declares.
92
+ Each object key is the canonical flag name, and evaluation runs through the same command schema, parser, coercion, resolver, and validation a command uses. Aliases, negated spellings, duplicate policy, case parity, unknown-flag rejection, collisions between names, aliases and negated forms, the CLI, stdin, env, config, prompt, default precedence, constraints, Standard Schema validators, and `flag.path()` checks all behave as they do inside `.action()`. `argv`, `env`, `stdinData`, `stat`, and `mkdir` fall back to the detected `RuntimeAdapter`, while `config` and `prompter` stay caller-supplied, since standalone flag reading has no application name to discover a file from and opens no terminal session. `ReadFlagsOptions` extends `ResolveOptions` with `argv`, `adapter`, `parse`, `strict`, `help`, and `onDeprecation`. The adapter is built on the first fact the caller left out, so a call given `argv` and `env` reads nothing from the host unless a `flag.path()` check needs the adapter's filesystem primitives. Failures throw `ParseError` and `ValidationError` instead of exiting, a colliding record, the definition key `__proto__`, and a record whose prototype is replaced (an object-literal `__proto__` key, or `Object.create(base)`, whose inherited definitions are never read) each throw `CLIError` before argv is read, and `.deprecated()` notices reach `onDeprecation` rather than a warning stream, since there is no output channel on this path.
93
+
94
+ A pre-separator `--help` or `-h` prints generated help for the record to the adapter's stdout and exits with code 0, with the script named from the adapter's argv in the usage line. The built-in yields to a definition that claims the `help` or `h` spelling through a name, alias, negated form, or case-parity counterpart, and `help: 'off'` removes it entirely; `json` and `quiet` are never reserved, so a record may declare them as ordinary flags. `strict: false` drops undeclared argv content instead of rejecting it: unknown long flags with their inline `=value`, unknown short-group characters, positional arguments, and the `--` separator, while value tokens of declared flags survive under the parser's own consumption rules and misuse of a declared flag keeps its diagnostics.
95
+
96
+ Positional arguments are not part of this API, and there is no synchronous variant: prompts, async validators, and filesystem checks make the result a promise. `readFlags`, `ReadFlagsOptions`, and `FlagMap` are exported from the package root, and [Standalone Flag Evaluation](https://dreamcli.kjanat.dev/guide/read-flags) walks the API with the build-script case it was added for.
97
+
98
+ - **Purpose-built positional argument kinds and string constraints** (https://github.com/kjanat/dreamcli/issues/87).\
99
+ A base URL, an input file, or a cutoff date reads naturally as a positional, and until now the only route was `arg.custom()` re-implementing what `flag.url()` already did. `arg.url(options?)`, `arg.path(options?)`, `arg.date(options?)`, `arg.duration()`, and `arg.bytes()` mirror their flag counterparts: same value types, same option objects (`UrlFlagOptions`, `PathFlagOptions`, `DateFlagOptions`), same parsers. `arg.string()` takes a `StringConstraints` object, and string-kind `ArgBuilder`s carry `.nonEmpty()`, `.minLength()`, `.maxLength()`, and `.pattern()` alongside the numeric `.int()`, `.min()`, `.max()`, and `.finite()` they already had. Both factories run the same parse functions and the same constraint validator, so a value a flag accepts an argument accepts, and a rejection carries the same code and the same reason, differing in the subject: `for flag --x` versus `for argument <x>`.
100
+
101
+ String constraints are enforced on CLI parse (`INVALID_VALUE`) and on stdin, env, config, and prompt resolution (`CONSTRAINT_VIOLATED`), both exit code `2`; as with flags, a `.default()` value is checked where it is declared and a violation throws `INVALID_DEFAULT`. `arg.path()` checks run after resolution through the runtime adapter's `stat`/`mkdir`, the same seam `flag.path()` uses, so a piped, env-sourced, config-sourced, prompted, or defaulted path is checked like one typed on the command line. A variadic argument validates every value it collects, path checks included. Argument values sourced from anywhere but argv stay redacted in the message, as in `Invalid value '<redacted>' from stdin for argument <x>` and `Invalid number value '<redacted>' from config deploy.port for argument <x>`, so the flag and argument messages are equivalent apart from their subjects.
102
+
103
+ `ArgSchema` and the arg definition types carry `stringConstraints`, `pathChecks`, and `valueHint`. The first two are string-kind gated the way the flag schema gates them. Args serialize `numberConstraints`, `stringConstraints`, `pathChecks`, and `valueHint` into the definition document, which previously emitted none of them, and `generateInputSchema()` now surfaces arg string constraints as `minLength` / `maxLength` / `pattern`. The meta-schema hoists the `numberConstraints`, `stringConstraints`, and `pathChecks` fragments into `$defs` so the flag and arg definitions reference one copy. All of it is additive at `schemaVersion: 1`. Help still renders a positional by its own name rather than its `valueHint`, so `mycli copy <src> <dst>` does not collapse into `<path> <path>`.
104
+
105
+ The flag-only surface stays flag-only, and [the arguments guide](https://dreamcli.kjanat.dev/guide/arguments#flag-only-surface) lists it with the reason for each entry. `boolean`, `count`, `negatable`, `alias`, `duplicates`, `separator`, `unique`, and `propagate` are bound to flag syntax; `array` is served by `.variadic()`. `keyValue` merges repeated occurrences into one record, which a positional slot cannot express, and `arg.custom()` with a Standard Schema validator is the documented route. `.config()` and `.prompt()` are no longer among them: both surfaces now declare the same sources, described in the unified source model entry below.
106
+
107
+ - **A unified source model — every input uses the same source order**\
108
+ Flags and args now declare sources from the same set and resolve declared sources through one ordered chain: `CLI -> stdin -> env -> config -> prompt -> default`. `arg.config(path)` and `arg.prompt(config)` join `arg.env()`, so a positional reads a dotted config key and asks the user exactly as a flag does; the arg prompt table mirrors the flag one (`PromptConfigByArgKind`, `AllowedArgPromptConfig`), and an incompatible pairing throws `CONSTRAINT_VIOLATED` naming `<arg>`. Help annotates a positional with `[config: PATH]` and `[prompt]` beside the `[env: VAR]` it already showed. `flag.string().stdin()` becomes legal on `string`, `number`, `boolean`, `enum`, and `custom` flags, giving `echo hi | mycli send` and `mycli send --body -` the meaning `arg.stdin()` already had. `.stdin()` takes `{ when: 'dash' | 'missing' | 'dash-or-missing', consume: 'exclusive' | 'broadcast' }` on both surfaces, defaulting to `dash-or-missing` and `exclusive`. `StdinBinding`, `StdinOptions`, `StdinWhen`, and `StdinConsume` are exported from the package root, and `StdinBindingFragmentV1` names the serialized form.
109
+
110
+ An explicit `-` is CLI-sourced with bytes from stdin and keeps CLI precedence; an absent input takes the stdin fallback stage, which sits ahead of env, so a flag set in the environment still reads a pipe and the pipe wins. The `-` sentinel now survives the parse boundary for every kind, so `flag.number().stdin()` accepts `--port -` where it used to reject `-` as a malformed number. `readFlags()` carries the same contract and reads stdin only through the adapter, only when a declared `.stdin()` flag would actually select it; `runCommand()` feeds the identical path from its `stdinData` option. Stdin is read at most once per invocation, and only when resolution will select it: `when: 'dash'` reads on `-` alone, `when: 'missing'` reads on an absent input alone, and env, config, prompt, and a default never suppress the read.
111
+
112
+ One command has one exclusive stdin consumer. Declaring a second stdin input of any kind, flag or arg, throws `DUPLICATE_STDIN_INPUT` on both construction paths; `{ consume: 'broadcast' }` on every stdin input opts into sharing one buffer among them. The definition document carries the binding as `stdin: { when, consume }` on flags and args, with a `stdin` entry in the meta-schema `$defs`, and the arg fragment gains `configPath` and `prompt`.
113
+
114
+ - **Cardinality is its own axis, with per-source splitting.**\
115
+ How many values an input carries (`one`, `many`, `entries`, `count`) is now decided separately from what each value means, so every source fills a collection by the same rules. `.split({ cli, env, stdin })` on `flag.array()`, `flag.keyValue()`, and the arg builders sets each source's decoding independently: a delimiter or `'whole'` for CLI tokens, a delimiter, `'whole'`, or `{ format: 'json' }` for env values, and `'lines'`, `'whole'`, a delimiter, or `{ format: 'json' }` for the stdin buffer. Defaults are whole CLI tokens (or the `.separator()` delimiter), comma-delimited env values, and line-delimited stdin; a config value stays a native array or object, and a config string decodes under the env policy. JSON is never guessed. `SplitOptions`, `SplitSetting`, `SplitPolicy`, `SplitBinding`, `SourceSplitBinding`, and `SplitFormat` are exported from the package root, and the definition document carries `split` on flag and arg fragments as `SourceSplitFragmentV1` / `SplitPolicyFragmentV1`.
116
+
117
+ - **Collections read stdin, and `-` splices into occurrence order.**\
118
+ `flag.array()` and `flag.keyValue()` accept `.stdin()`, and a `-` occurrence stands for the whole stdin source at the position it holds: `--tag before --tag - --tag after` over `a\nb\n` resolves to `['before', 'a', 'b', 'after']`. An explicit `-` and the implicit fallback decode identically, entries splice the same way, and the duplicate-key policy applies across the whole spliced order. Broadcast consumers each decode the one shared buffer under their own binding, so a line-split array flag and a JSON key-value flag can read the same pipe.
119
+
120
+ - **`.duplicateKeys()` on key-value inputs.**\
121
+ `'last'` (the default), `'first'`, or `'error'` decides what a repeated key means, on every source rather than only on repeated CLI occurrences. A repeat under `'error'` reports `CONSTRAINT_VIOLATED` naming the key. `DuplicateKeys` is exported from the package root and the policy is serialized as `duplicateKeys`.
122
+
123
+ - **`arg.boolean()` and `arg.keyValue()`.**\
124
+ A positional carries no presence semantics, so `arg.boolean()` consumes an explicit `true`/`false` (or `1`/`0`) token through the shared boolean codec, widening to `yes`/`no` and an empty string only for env, config, stdin, and prompt values. `arg.keyValue()` consumes `KEY=VALUE` tokens and resolves to `Record<string, string>`, splitting at the first `=`; the variadic form aggregates the whole tail into one record. `BooleanArgDefinition` and `KeyValueArgDefinition` join the definition types, and `ArgKind` gains `'boolean'` and `'keyValue'`.
125
+
126
+ - **Element-level sugar inside collections.**\
127
+ Path checks and constraints belong to the element, so `flag.array(flag.path({ mustExist: true }))` checks every collected element and `flag.keyValue(flag.path())` checks every entry value. `flag.keyValue()` takes an optional element builder, and `flag.path()` is now element-eligible.
128
+
129
+ - **`.standard()` on both builders, split into element and aggregate validation.**\
130
+ A validator declared on an element builder (`flag.array(flag.string().standard(s))`) validates each item or entry value; one declared on a builder that already aggregates (`flag.array(flag.string()).standard(s)`, `arg.string().variadic().standard(s)`) validates the completed array or record after every element passed. Element issues name the element (`--tag[1]`, `--vars.KEY`). Sync and async validators are both awaited, and every source runs the same pipeline.
131
+
132
+ - **`.unique()` and `.separator()` on args.**\
133
+ A variadic arg deduplicates with the same `SameValueZero` semantics an array flag uses, and splits each positional token on the CLI separator it declares.
398
134
 
399
135
  ### Changed
400
136
 
401
- - **Breaking: flag diagnostics redact every value resolved outside a literal
402
- CLI value.** A
403
- stdin, environment, config, or prompt value that failed to coerce used to be
404
- printed and stored under `details.value` on the flag surface, while the
405
- argument surface already redacted it. Both surfaces now report
406
- `Invalid value '<redacted>' from env API_TOKEN for flag --token: must match
407
- /^ghp_/` and omit `value` from `details`. Everything that identifies the
408
- failure stays: the input name, the source, the expected type, the constraint
409
- that failed with its bound or pattern, the allowed enum values, and a custom
410
- parse function's own message. A Standard Schema validator's
411
- `CONSTRAINT_VIOLATED` failure follows
412
- the same rule: `details.value` is recorded only for a value typed on the
413
- command line, and omitted for one a pipe, an explicit `-`, the environment, a
414
- config file, or a prompt supplied. A literal CLI value is untouched, since it
415
- is already on the user's screen. Every coercion failure now also carries
416
- `source: 'env' | 'config' | 'stdin' | 'prompt'` in `details`, which is what
417
- labels an issue `[env API_TOKEN]` in an aggregate error and what now gives the
418
- argument surface the same label the flag surface had. The `flag.path()` and
419
- `arg.path()` filesystem checks read the same rule, so a path a pipe, an
420
- explicit `-`, the environment, a config file, a prompt, or a declared default
421
- supplied reports `Path '<redacted>' for flag --key does not exist` and omits
422
- `value` from `details`; a path typed on the command line is still quoted in
423
- full. Every element of a collection of paths is checked and redacted
424
- individually.
425
-
426
- - **Breaking: a positional declared after a variadic one is a build error.** A
427
- variadic argument consumes every remaining positional, so anything registered
428
- behind it could never be filled and a second variadic one had nothing left to
429
- collect. Both silently produced an argument that stayed empty. `.arg()` and
430
- `createCommandSchema()` now throw `INVALID_BUILDER_STATE`
431
- (`Argument <target> comes after variadic argument <files>, which consumes
432
- every remaining positional`), with the command under `command`, the offending
433
- argument under `arg`, and the greedy one under `variadicArg`, so a definition
434
- tree names the nested command that declared the pair. Move the variadic
435
- argument last.
436
-
437
- - **Breaking: an explicit `-` with nothing piped is an error inside a
438
- collection.** `--tag a --tag - --tag b` with an empty pipe used to resolve to
439
- `['a', 'b']`, dropping the occurrence the user typed. It now fails with
440
- `MISSING_STDIN` and the message
441
- `No piped stdin for the '-' occurrence of flag --tag`. Occurrences of nothing
442
- but `-` are unchanged: they are the whole value, so they still fall through to
443
- env, config, prompt, and the default, exactly as an absent input does, and the
444
- implicit `when: 'missing'` fallback that simply does not fire stays silent. A
445
- scalar `-` falls through for the same reason. Only a collection could be
446
- silently shortened, so only a collection errors.
447
-
448
- - **Breaking: the arg collection modifiers require a collection.**
449
- `createArgSchema('string', { unique: true })` and its siblings used to build,
450
- storing a field nothing would read. They now state their requirement to the
451
- compiler and throw `INVALID_SCHEMA` from `createArgSchema()`: `separator` and
452
- `split` want a variadic argument or `arg.keyValue()`, `unique` a variadic
453
- argument of a list kind, and `duplicateKeys` `arg.keyValue()`. The values a
454
- schema already stores as its own default, `unique: false` and
455
- `duplicateKeys: 'last'`, stay accepted on any kind, so a built `ArgSchema` fed
456
- back through the factory round-trips. This mirrors the `array | keyValue`
457
- restriction the flag surface already had. Drop the field, or add
458
- `variadic: true` alongside it. The matching builder methods are new in 4.0, so
459
- only definitions composed as data change.
460
-
461
- - **Breaking: `.stdin()` and `.variadic()` on one argument is now legal.** The
462
- pairing threw `INVALID_BUILDER_STATE`; the tail-splicing entry under Added
463
- describes what it does instead. Code that relied on the throw has nothing to
464
- catch.
465
-
466
- - **Breaking: declared defaults are validated.** A `.default()` value is
467
- already the typed value, so it is validated rather than decoded: the codec's
468
- own domain, string and number constraints, element and aggregate Standard
469
- Schema validators, the shape the cardinality requires, and the collection rules
470
- all apply to it. Purely synchronous violations throw `INVALID_DEFAULT` where
471
- the chain declares them, so `flag.string({ minLength: 3 }).default('ab')` and
472
- `flag.number().default(Number.POSITIVE_INFINITY)` now fail at construction
473
- instead of reaching a handler; a constraint added after the default
474
- (`flag.string().default('ab').minLength(3)`) is checked too, as is a validator
475
- (`.standard()`). On the definition path, where no compiler stands in the way,
476
- the domain check also rejects a default of the wrong primitive type and an
477
- `enum` default outside `enumValues`. Asynchronous
478
- validators and `flag.path()` filesystem checks stay at resolution time, where
479
- command resolution awaits the validator or probes the path. Code relying on a default that violates
480
- its own declaration either fixes the default or widens the constraint
481
- (`flag.number({ finite: false })` still accepts `Infinity`).
482
-
483
- - **Breaking: `.separator()` sets the CLI delimiter alone.** Env and config
484
- string values used to inherit it, so `.separator('|')` silently changed how an
485
- env var decoded. Env values split on `','` unless `.split({ env })` says
486
- otherwise. The stdin buffer splits on line terminators by default;
487
- `.split({ stdin })` can select `'whole'`, `'json'`, or a delimiter instead.
488
- Config arrays and objects remain native; config strings use the env split policy.
489
- `.separator('|')` becomes `.split({ cli: '|', env: '|' })` where the old
490
- coupling was intended.
491
-
492
- - **Breaking: `FlagSchema` and `ArgSchema` carry the cardinality axis.**
493
- `FlagSchema` gains `split`, `duplicateKeys`, and `aggregateStandard`;
494
- `ArgSchema` gains `separator`, `split`, `duplicateKeys`, `unique`, and
495
- `aggregateStandard`. `elementSchema` and `separator` are valid on `keyValue`
496
- as well as `array` flags, `standard` is valid on every kind, `aggregateStandard`
497
- only on a kind that aggregates, and `stdin` is valid on scalar and collection kinds.
498
- Definition documents serialize the new fields additively at `schemaVersion: 1`,
499
- which has not shipped, with `split` and `splitPolicy` entries in the
500
- meta-schema `$defs`.
501
-
502
- - **Breaking: `.default()` on a variadic arg takes the array.** The type
503
- parameter followed the element type, so the only value that compiled was a
504
- single element, which is not what a variadic arg resolves to. It now follows
505
- `ArgDefaultValue`, the value the arg actually produces:
506
- `arg.string().variadic().default(['a', 'b'])`, and a record for
507
- `arg.keyValue()`. `ArgDefaultValue` is exported from the package root.
508
-
509
- - **Breaking: `ArgSchema.stdinMode` is now `ArgSchema.stdin`** — the boolean
510
- carried no room for the trigger and sharing modes the unified source model
511
- needs, so it is replaced by `stdin: StdinBinding | undefined`. `.stdin()` is
512
- unchanged for callers who pass no options and keeps its exact resolution
513
- behavior. Code reading the schema directly reads `schema.stdin !== undefined`
514
- where `schema.stdinMode` used to be, and a definition passed to
515
- `createArgSchema()` or `createCommandSchema()` writes `stdin: {}` instead of
516
- `stdinMode: true`. The definition document changes to match: the arg fragment
517
- emits `stdin: { when, consume }` in place of `stdinMode: true`, at
518
- `schemaVersion: 1`, which has not shipped.
519
-
520
- - **Breaking: `DUPLICATE_STDIN_ARG` is now `DUPLICATE_STDIN_INPUT`** — the rule
521
- covers flags as well as args, and a flag-versus-flag conflict reporting an
522
- arg-shaped code would be a lie. The message reads `Only one input may consume
523
- stdin exclusively; <name> already consumes stdin`, naming the input that was
524
- declared first. `details` names the offending input under `flag` or `arg` and
525
- the existing one under `existingFlag` or `existingArg`.
526
-
527
- - **Breaking: stdin values reach non-string codecs without their trailing line
528
- terminator** — the stdin source hands the whole buffer over byte for byte, so
529
- `echo hi | mycli` still gives a `string` input `'hi\n'`. Every other codec
530
- interprets the text, where a terminator a pipe appended is framing rather than
531
- value, so one trailing `\n`, `\r\n`, or `\r` is dropped before decoding.
532
- `echo true | mycli` now resolves a boolean input to `true`, `echo 1h30m` to a
533
- duration, and `echo eu` to an enum member; all three used to fail. A number
534
- input is unaffected, since `Number()` already ignored the terminator. Stdin
535
- also stops borrowing the prompt widening table: it accepts exactly what an env
536
- value accepts, so the prompt-only `y` and `n` boolean spellings are rejected.
537
-
538
- - **Breaking: a number input rejects blank text instead of reading it as zero.**
539
- `Number('')` and `Number(' ')` are both `0`, so `PORT= mycli serve`,
540
- `printf '\n' | mycli serve`, and a config key holding `""` all resolved a
541
- number input to `0` without a word. All three now fail with `TYPE_MISMATCH`
542
- and the same `Invalid number value '<redacted>' from …` diagnostic any other
543
- unreadable value gets, and `mycli serve --port ''` fails at the parse boundary
544
- where it quotes the token. Whitespace around a real number is still ignored,
545
- so `' 42 '` and `'42\n'` are unaffected. A `count` flag already guarded this;
546
- the number codec now does too. Set the variable, or drop it and let the
547
- default apply.
548
-
549
- - **Breaking: `CLISchema.commands` and `CLISchema.defaultCommand` hold
550
- `CommandSchema`** — both used to hold `ErasedCommand` wrappers carrying the
551
- action handler and an `_execute` function. The execution graph now lives
552
- beside the schema instead of inside it, so `app.schema.commands[0]` is the
553
- command schema itself: read `app.schema.commands[0].name` where
554
- `app.schema.commands[0].schema.name` used to be needed. `ErasedCommand` is
555
- gone.
556
-
557
- - **Breaking: `CLISchema.plugins` removed** — plugins are execution state, not
558
- a description of the program, and `.plugin()` no longer writes to the schema.
559
- Registration, order, and hook behavior are unchanged.
560
-
561
- - **Breaking: `CLIBuilder` is factory-only** — its constructor is private, so
562
- `new CLIBuilder(schema)` no longer compiles. Call `cli(name)` or
563
- `cli({ ... })`; every builder method still returns a new builder.
564
-
565
- - **Breaking: `CommandSchema.middleware` removed** — the executor builds the
566
- handler chain from the builder's ordered execution steps, so registration
567
- order, handler identity, and runtime behavior are unchanged.
568
- `CommandDefinition` no longer accepts a `middleware` key, and
569
- `createCommandSchema()` no longer emits one.
570
-
571
- - **Breaking: `FlagSchema`, `ArgSchema`, and `CommandSchema` are sealed** — all
572
- three carry a private brand, so an object literal assembled by hand no longer
573
- type-checks where a schema is expected. Call `createFlagSchema()`,
574
- `createArgSchema()`, or `createCommandSchema()` with a definition object to
575
- obtain one; spreading a built schema keeps the brand, so
576
- `{ ...schema, description }` still type-checks. `createSchema()` was renamed
577
- to `createFlagSchema()`, which validates its fields against the kind and
578
- normalizes a nested `elementSchema`.
579
-
580
- - **Breaking: `createCommandSchema()` validates what the builder validates** — a
581
- definition whose flags share a name, an alias, or a negated spelling on one
582
- command now throws `FLAG_NAME_COLLISION`, and a flag spelled the same way as
583
- one propagated from an ancestor command throws `PROPAGATED_FLAG_COLLISION`.
584
- The whole tree is checked, nested subcommands included. Commands built with
585
- `command()` already refused these at `.flag()` and `.command()`; a definition
586
- composed as data used to build without complaint and then answer the shared
587
- spelling with one flag only. Two flags both aliased `v` still parsed under
588
- `--verbose` and `--version`, help listed `-v` on both, and `-v` set the
589
- second. The arg invariants moved with them, so a definition declaring a
590
- positional after a variadic one throws `INVALID_BUILDER_STATE`, and a second
591
- stdin-backed input throws `DUPLICATE_STDIN_INPUT`, matching `.arg()`.
592
- Previously, both combinations built without complaint. Two stdin-backed args
593
- each resolved to the
594
- whole of stdin, and a positional behind a variadic one silently never filled. Every arg error names the
595
- command in `details`, since a definition tree reaches them at any depth and
596
- the arg name alone does not say which command declared it. A flag or arg
597
- named `__proto__` now throws `INVALID_SCHEMA` from both the factory and the
598
- builder, the check `readFlags()` already applied to its definitions record.
599
- The factory and `.arg()` used to accept the key, which sets a prototype rather
600
- than an entry, so the flag or the value the user typed disappeared; `.flag()`
601
- used to report `FLAG_NAME_COLLISION` against a flag the command never
602
- declared. A flag record whose prototype is replaced throws `INVALID_SCHEMA`
603
- too, since only its own keys are read: an object-literal `__proto__` key lands
604
- there, and so does `Object.create(base)`, whose inherited flags the factory
605
- silently dropped. `createCLISchema()` normalizes its commands through the same
606
- factory and inherits every check, and `readFlags()` reports the same errors it
607
- always did.
608
-
609
- - **Breaking: `CLISchema` and `ConfigSettings` are sealed** — both carry a
610
- private brand, so an object literal assembled by hand no longer type-checks
611
- where either is expected. Call `cli()` for an executable program or
612
- `createCLISchema()` for a description; spreading a built schema keeps the
613
- brand, so `{ ...app.schema, name }` still type-checks. `createCLISchema()`
614
- throws `INVALID_SCHEMA` on an empty name, which `cli('')` now does too.
615
-
616
- - **Breaking: `createArgSchema()` validates its fields against the kind** — the
617
- second parameter is now `ArgDefinitionOverrides<K>` rather than
618
- `Partial<ArgSchema>`, so `enumValues` on a `string` arg (and the other
619
- kind-scoped fields) stops compiling and throws `INVALID_SCHEMA` at runtime.
620
- `enumValues` is required on an `enum` arg. A single definition object
621
- (`createArgSchema({ kind: 'enum', enumValues })`) is accepted as well.
622
-
623
- - **Breaking: `Out` gained a required `verbosity` member** — action handlers
624
- can read `out.verbosity`, and `resolveRenderContext()` exposes the same
625
- `verbosity` decision for custom content built before `.run()` (including
626
- `--`-aware `--quiet`/`-q` detection). A hand-rolled `Out` object literal
627
- stops compiling until it declares one; migrate to a real channel from the
628
- testkit and spy on it instead:
137
+ - **Breaking: flag diagnostics redact every value resolved outside a literal CLI value.**\
138
+ A stdin, environment, config, or prompt value that failed to coerce used to be printed and stored under `details.value` on the flag surface, while the argument surface already redacted it. Both surfaces now report `Invalid value '<redacted>' from env API_TOKEN for flag --token: must match /^ghp_/` and omit `value` from `details`. Everything that identifies the failure stays: the input name, the source, the expected type, the constraint that failed with its bound or pattern, the allowed enum values, and a custom parse function's own message. A Standard Schema validator's `CONSTRAINT_VIOLATED` failure follows the same rule: `details.value` is recorded only for a value typed on the command line, and omitted for one a pipe, an explicit `-`, the environment, a config file, or a prompt supplied. A literal CLI value is untouched, since it is already on the user's screen. Every coercion failure now also carries `source: 'env' | 'config' | 'stdin' | 'prompt'` in `details`, which is what labels an issue `[env API_TOKEN]` in an aggregate error and what now gives the argument surface the same label the flag surface had. The `flag.path()` and `arg.path()` filesystem checks read the same rule, so a path a pipe, an explicit `-`, the environment, a config file, a prompt, or a declared default supplied reports `Path '<redacted>' for flag --key does not exist` and omits `value` from `details`; a path typed on the command line is still quoted in full. Every element of a collection of paths is checked and redacted individually.
139
+
140
+ - **Breaking: a positional declared after a variadic one is a build error.**\
141
+ A variadic argument consumes every remaining positional, so anything registered behind it could never be filled and a second variadic one had nothing left to collect. Both silently produced an argument that stayed empty. `.arg()` and `createCommandSchema()` now throw `INVALID_BUILDER_STATE` (`Argument <target> comes after variadic argument <files>, which consumes every remaining positional`), with the command under `command`, the offending argument under `arg`, and the greedy one under `variadicArg`, so a definition tree names the nested command that declared the pair. Move the variadic argument last.
142
+
143
+ - **Breaking: an explicit `-` with nothing piped is an error inside a collection.**\
144
+ `--tag a --tag - --tag b` with an empty pipe used to resolve to `['a', 'b']`, dropping the occurrence the user typed. It now fails with `MISSING_STDIN` and the message `No piped stdin for the '-' occurrence of flag --tag`. Occurrences of nothing but `-` are unchanged: they are the whole value, so they still fall through to env, config, prompt, and the default, exactly as an absent input does, and the implicit `when: 'missing'` fallback that simply does not fire stays silent. A scalar `-` falls through for the same reason. Only a collection could be silently shortened, so only a collection errors.
145
+
146
+ - **Breaking: the arg collection modifiers require a collection.**\
147
+ `createArgSchema('string', { unique: true })` and its siblings used to build, storing a field nothing would read. They now state their requirement to the compiler and throw `INVALID_SCHEMA` from `createArgSchema()`: `separator` and `split` want a variadic argument or `arg.keyValue()`, `unique` a variadic argument of a list kind, and `duplicateKeys` `arg.keyValue()`. The values a schema already stores as its own default, `unique: false` and `duplicateKeys: 'last'`, stay accepted on any kind, so a built `ArgSchema` fed back through the factory round-trips. This mirrors the `array | keyValue` restriction the flag surface already had. Drop the field, or add `variadic: true` alongside it. The matching builder methods are new in 4.0, so only definitions composed as data change.
148
+
149
+ - **Breaking: `.stdin()` and `.variadic()` on one argument is now legal.**\
150
+ The pairing threw `INVALID_BUILDER_STATE`; the tail-splicing entry under Added describes what it does instead. Code that relied on the throw has nothing to catch.
151
+
152
+ - **Breaking: declared defaults are validated.**\
153
+ A `.default()` value is already the typed value, so it is validated rather than decoded: the codec's own domain, string and number constraints, element and aggregate Standard Schema validators, the shape the cardinality requires, and the collection rules all apply to it. Purely synchronous violations throw `INVALID_DEFAULT` where the chain declares them, so `flag.string({ minLength: 3 }).default('ab')` and `flag.number().default(Number.POSITIVE_INFINITY)` now fail at construction instead of reaching a handler; a constraint added after the default (`flag.string().default('ab').minLength(3)`) is checked too, as is a validator (`.standard()`). On the definition path, where no compiler stands in the way, the domain check also rejects a default of the wrong primitive type and an `enum` default outside `enumValues`. Asynchronous validators and `flag.path()` filesystem checks stay at resolution time, where command resolution awaits the validator or probes the path. Code relying on a default that violates its own declaration either fixes the default or widens the constraint (`flag.number({ finite: false })` still accepts `Infinity`).
154
+
155
+ - **Breaking: `.separator()` sets the CLI delimiter alone.**\
156
+ Env and config string values used to inherit it, so `.separator('|')` silently changed how an env var decoded. Env values split on `','` unless `.split({ env })` says otherwise. The stdin buffer splits on line terminators by default; `.split({ stdin })` can select `'whole'`, `'json'`, or a delimiter instead. Config arrays and objects remain native; config strings use the env split policy. `.separator('|')` becomes `.split({ cli: '|', env: '|' })` where the old coupling was intended.
157
+
158
+ - **Breaking: `FlagSchema` and `ArgSchema` carry the cardinality axis.**\
159
+ `FlagSchema` gains `split`, `duplicateKeys`, and `aggregateStandard`; `ArgSchema` gains `separator`, `split`, `duplicateKeys`, `unique`, and `aggregateStandard`. `elementSchema` and `separator` are valid on `keyValue` as well as `array` flags, `standard` is valid on every kind, `aggregateStandard` only on a kind that aggregates, and `stdin` is valid on scalar and collection kinds. Definition documents serialize the new fields additively at `schemaVersion: 1`, which has not shipped, with `split` and `splitPolicy` entries in the meta-schema `$defs`.
160
+
161
+ - **Breaking: `.default()` on a variadic arg takes the array.**\
162
+ The type parameter followed the element type, so the only value that compiled was a single element, which is not what a variadic arg resolves to. It now follows `ArgDefaultValue`, the value the arg actually produces: `arg.string().variadic().default(['a', 'b'])`, and a record for `arg.keyValue()`. `ArgDefaultValue` is exported from the package root.
163
+
164
+ - **Breaking: `ArgSchema.stdinMode` is now `ArgSchema.stdin`**\
165
+ The boolean carried no room for the trigger and sharing modes the unified source model needs, so it is replaced by `stdin: StdinBinding | undefined`. `.stdin()` is unchanged for callers who pass no options and keeps its exact resolution behavior. Code reading the schema directly reads `schema.stdin !== undefined` where `schema.stdinMode` used to be, and a definition passed to `createArgSchema()` or `createCommandSchema()` writes `stdin: {}` instead of `stdinMode: true`. The definition document changes to match: the arg fragment emits `stdin: { when, consume }` in place of `stdinMode: true`, at `schemaVersion: 1`, which has not shipped.
166
+
167
+ - **Breaking: `DUPLICATE_STDIN_ARG` is now `DUPLICATE_STDIN_INPUT`**\
168
+ The rule covers flags as well as args, and a flag-versus-flag conflict reporting an arg-shaped code would be a lie. The message reads `Only one input may consume stdin exclusively; <name> already consumes stdin`, naming the input that was declared first. `details` names the offending input under `flag` or `arg` and the existing one under `existingFlag` or `existingArg`.
169
+
170
+ - **Breaking: stdin values reach non-string codecs without their trailing line terminator**\
171
+ The stdin source hands the whole buffer over byte for byte, so `echo hi | mycli` still gives a `string` input `'hi\n'`. Every other codec interprets the text, where a terminator a pipe appended is framing rather than value, so one trailing `\n`, `\r\n`, or `\r` is dropped before decoding. `echo true | mycli` now resolves a boolean input to `true`, `echo 1h30m` to a duration, and `echo eu` to an enum member; all three used to fail. A number input is unaffected, since `Number()` already ignored the terminator. Stdin also stops borrowing the prompt widening table: it accepts exactly what an env value accepts, so the prompt-only `y` and `n` boolean spellings are rejected.
172
+
173
+ - **Breaking: a number input rejects blank text instead of reading it as zero.**\
174
+ `Number('')` and `Number(' ')` are both `0`, so `PORT= mycli serve`, `printf '\n' | mycli serve`, and a config key holding `""` all resolved a number input to `0` without a word. All three now fail with `TYPE_MISMATCH` and the same `Invalid number value '<redacted>' from …` diagnostic any other unreadable value gets, and `mycli serve --port ''` fails at the parse boundary where it quotes the token. Whitespace around a real number is still ignored, so `' 42 '` and `'42\n'` are unaffected. A `count` flag already guarded this; the number codec now does too. Set the variable, or drop it and let the default apply.
175
+
176
+ - **Breaking: `CLISchema.commands` and `CLISchema.defaultCommand` hold `CommandSchema`**\
177
+ Both used to hold `ErasedCommand` wrappers carrying the action handler and an `_execute` function. The execution graph now lives beside the schema instead of inside it, so `app.schema.commands[0]` is the command schema itself: read `app.schema.commands[0].name` where `app.schema.commands[0].schema.name` used to be needed. `ErasedCommand` is gone.
178
+
179
+ - **Breaking: `CLISchema.plugins` removed**\
180
+ Plugins are execution state, not a description of the program, and `.plugin()` no longer writes to the schema. Registration, order, and hook behavior are unchanged.
181
+
182
+ - **Breaking: `CLIBuilder` is factory-only**\
183
+ Its constructor is private, so `new CLIBuilder(schema)` no longer compiles. Call `cli(name)` or `cli({ ... })`; every builder method still returns a new builder.
184
+
185
+ - **Breaking: `CommandSchema.middleware` removed** — the executor builds the handler chain from the builder's ordered execution steps, so registration order, handler identity, and runtime behavior are unchanged. `CommandDefinition` no longer accepts a `middleware` key, and `createCommandSchema()` no longer emits one.
186
+
187
+ - **Breaking: `FlagSchema`, `ArgSchema`, and `CommandSchema` are sealed** — all three carry a private brand, so an object literal assembled by hand no longer type-checks where a schema is expected. Call `createFlagSchema()`, `createArgSchema()`, or `createCommandSchema()` with a definition object to obtain one; spreading a built schema keeps the brand, so `{ ...schema, description }` still type-checks. `createSchema()` was renamed to `createFlagSchema()`, which validates its fields against the kind and normalizes a nested `elementSchema`.
188
+
189
+ - **Breaking: `createCommandSchema()` validates what the builder validates** — a definition whose flags share a name, an alias, or a negated spelling on one command now throws `FLAG_NAME_COLLISION`, and a flag spelled the same way as one propagated from an ancestor command throws `PROPAGATED_FLAG_COLLISION`. The whole tree is checked, nested subcommands included. Commands built with `command()` already refused these at `.flag()` and `.command()`; a definition composed as data used to build without complaint and then answer the shared spelling with one flag only. Two flags both aliased `v` still parsed under `--verbose` and `--version`, help listed `-v` on both, and `-v` set the second. The arg invariants moved with them, so a definition declaring a positional after a variadic one throws `INVALID_BUILDER_STATE`, and a second stdin-backed input throws `DUPLICATE_STDIN_INPUT`, matching `.arg()`. Previously, both combinations built without complaint. Two stdin-backed args each resolved to the whole of stdin, and a positional behind a variadic one silently never filled. Every arg error names the command in `details`, since a definition tree reaches them at any depth and the arg name alone does not say which command declared it. A flag or arg named `__proto__` now throws `INVALID_SCHEMA` from both the factory and the builder, the check `readFlags()` already applied to its definitions record. The factory and `.arg()` used to accept the key, which sets a prototype rather than an entry, so the flag or the value the user typed disappeared; `.flag()` used to report `FLAG_NAME_COLLISION` against a flag the command never declared. A flag record whose prototype is replaced throws `INVALID_SCHEMA` too, since only its own keys are read: an object-literal `__proto__` key lands there, and so does `Object.create(base)`, whose inherited flags the factory silently dropped. `createCLISchema()` normalizes its commands through the same factory and inherits every check, and `readFlags()` reports the same errors it always did.
190
+
191
+ - **Breaking: `CLISchema` and `ConfigSettings` are sealed** — both carry a private brand, so an object literal assembled by hand no longer type-checks where either is expected. Call `cli()` for an executable program or `createCLISchema()` for a description; spreading a built schema keeps the brand, so `{ ...app.schema, name }` still type-checks. `createCLISchema()` throws `INVALID_SCHEMA` on an empty name, which `cli('')` now does too.
192
+
193
+ - **Breaking: `createArgSchema()` validates its fields against the kind** — the second parameter is now `ArgDefinitionOverrides<K>` rather than `Partial<ArgSchema>`, so `enumValues` on a `string` arg (and the other kind-scoped fields) stops compiling and throws `INVALID_SCHEMA` at runtime. `enumValues` is required on an `enum` arg. A single definition object (`createArgSchema({ kind: 'enum', enumValues })`) is accepted as well.
194
+
195
+ - **Breaking: `Out` gained a required `verbosity` member** — action handlers can read `out.verbosity`, and `resolveRenderContext()` exposes the same `verbosity` decision for custom content built before `.run()` (including `--`-aware `--quiet`/`-q` detection). A hand-rolled `Out` object literal stops compiling until it declares one; migrate to a real channel from the testkit and spy on it instead:
629
196
 
630
197
  ```ts
631
198
  const [out] = createCaptureOutput();
632
199
  vi.spyOn(out, 'info');
633
200
  ```
634
201
 
635
- Do not spread a channel (`{ ...out, info: vi.fn() }`) — its methods are
636
- non-enumerable bound copies, so the spread result has none of them.
637
-
638
- - **Breaking: `Out` and `RenderContext` are sealed** — both interfaces now
639
- carry a private brand, so implementing or structurally constructing them
640
- outside the framework no longer type-checks. They are framework-created,
641
- non-exhaustive values: obtain instances from action parameters,
642
- `createOutput()`, `createCaptureOutput()`, or `resolveRenderContext()`, and
643
- expect new readonly members in minor releases. Helpers that only need a
644
- subset can accept `Pick<Out, 'info' | 'status'>`-style capability types.
645
-
646
- - **Breaking: internal execution fields left `RunOptions` and
647
- `CLIRunOptions`** — `out`, `captured`, `mergedSchema`, `meta`, and `plugins`
648
- were framework-populated fields marked `@internal` yet shipped on the public
649
- option types. They now live on unexported internal execution options; code
650
- passing them to `runCommand()` or `.execute()` stops compiling. Inject
651
- writers via `createCaptureOutput()` options or `OutputOptions.stdout`/
652
- `stderr` instead of replacing the channel wholesale.
653
-
654
- - **Breaking: `.execute()` takes `CLIExecuteOptions`**. The new root export
655
- carries the process-free option surface and has no `adapter` member; passing
656
- one to `.execute()` stops compiling. `CLIRunOptions` now extends
657
- `CLIExecuteOptions` with `adapter`, and `.run()` remains the only method that
658
- accepts it.
659
-
660
- - **Breaking: `CommandConfig` and the root `AnyCommandBuilder` export removed**.
661
- `CommandConfig` described the builder's type-level accumulator shape but no
662
- signature referenced it. `AnyCommandBuilder` is `@internal` erasure machinery
663
- that appears only on `CommandBuilder`'s underscore members, so the package
664
- root no longer exports the name.
665
-
666
- - **Breaking: the canonical `$schema`/`$id` for definition documents is
667
- self-hosted and format-versioned** —
668
- `https://dreamcli.kjanat.dev/schemas/definition/v1.schema.json` replaces the
669
- jsDelivr URL in `generateSchema()` output and in `definitionMetaSchema.$id`.
670
- The `v1` segment tracks the definition format, so it stays valid for every
671
- package release that emits `schemaVersion: 1`, and it is permanent once
672
- published. The `@kjanat/dreamcli/schema` subpath and the jsDelivr URL keep
673
- serving the same bytes as mirrors. Documents pinned to the old URL still
674
- validate against a local copy but no longer match the meta-schema's `$schema`
675
- constant.
676
-
677
- - **Breaking: a command flag spelled like a root-owned flag now throws
678
- `RESERVED_FLAG` at build time**
679
- ([#84](https://github.com/kjanat/dreamcli/issues/84)). The root removes
680
- `--json` and `--quiet`/`-q` from argv before dispatch, intercepts
681
- `--version`/`-V` once a version is configured, and renders help for
682
- `--help`/`-h` before a command's flags are parsed. A command declaring one of
683
- those spellings used to build, run, and render help while its flag stayed
684
- permanently at its default value. `.command()`, `.default()`, `.version()`,
685
- `.manifest(data)`, and `createCLISchema()` now reject it with `CLIError` code
686
- `RESERVED_FLAG`, checking each flag's canonical name, its aliases (hidden ones
687
- included), and its custom negated spelling (`.negatable({ alias: 'quiet' })`)
688
- through the whole nested subcommand tree. The error names the colliding flag
689
- and the root flag that shadows it, and suggests renaming, or `out.status()`
690
- for output that root `--quiet` suppresses. Near misses such as
691
- `jsonOutput` or `quietMode` stay legal, the default `--no-<name>` spelling
692
- never collides, and `version`/`V` stay available to a CLI that declares no
693
- version.
694
-
695
- - **`--completions` collision detection now covers negated spellings and the
696
- definition path.** `.negatable({ alias: 'completions' })` and a
697
- `createCLISchema()` definition carrying `completionsFlag` both used to build a
698
- CLI whose command flag the planner intercepted. Both now throw `CLIError` code
699
- `RESERVED_FLAG`, matching what `.completions({ as: 'flag' })` already rejected
700
- on the builder.
202
+ Do not spread a channel (`{ ...out, info: vi.fn() }`) — its methods are non-enumerable bound copies, so the spread result has none of them.
203
+
204
+ - **Breaking: `Out` and `RenderContext` are sealed** — both interfaces now carry a private brand, so implementing or structurally constructing them outside the framework no longer type-checks. They are framework-created, non-exhaustive values: obtain instances from action parameters, `createOutput()`, `createCaptureOutput()`, or `resolveRenderContext()`, and expect new readonly members in minor releases. Helpers that only need a subset can accept `Pick<Out, 'info' | 'status'>`-style capability types.
205
+
206
+ - **Breaking: internal execution fields left `RunOptions` and `CLIRunOptions`** — `out`, `captured`, `mergedSchema`, `meta`, and `plugins` were framework-populated fields marked `@internal` yet shipped on the public option types. They now live on unexported internal execution options; code passing them to `runCommand()` or `.execute()` stops compiling. Inject writers via `createCaptureOutput()` options or `OutputOptions.stdout`/ `stderr` instead of replacing the channel wholesale.
207
+
208
+ - **Breaking: `.execute()` takes `CLIExecuteOptions`**. The new root export carries the process-free option surface and has no `adapter` member; passing one to `.execute()` stops compiling. `CLIRunOptions` now extends `CLIExecuteOptions` with `adapter`, and `.run()` remains the only method that accepts it.
209
+
210
+ - **Breaking: `CommandConfig` and the root `AnyCommandBuilder` export removed**. `CommandConfig` described the builder's type-level accumulator shape but no signature referenced it. `AnyCommandBuilder` is `@internal` erasure machinery that appears only on `CommandBuilder`'s underscore members, so the package root no longer exports the name.
211
+
212
+ - **Breaking: the canonical `$schema`/`$id` for definition documents is self-hosted and format-versioned**\
213
+ <https://dreamcli.kjanat.dev/schemas/definition/v1.schema.json> replaces the jsDelivr URL in `generateSchema()` output and in `definitionMetaSchema.$id`. The `v1` segment tracks the definition format, so it stays valid for every package release that emits `schemaVersion: 1`, and it is permanent once published. The `@kjanat/dreamcli/schema` subpath and the jsDelivr URL keep serving the same bytes as mirrors. Documents pinned to the old URL still validate against a local copy but no longer match the meta-schema's `$schema` constant.
214
+
215
+ - **Breaking: a command flag spelled like a root-owned flag now throws `RESERVED_FLAG` at build time** (https://github.com/kjanat/dreamcli/issues/84).\
216
+ The root removes `--json` and `--quiet`/`-q` from argv before dispatch, intercepts `--version`/`-V` once a version is configured, and renders help for `--help`/`-h` before a command's flags are parsed. A command declaring one of those spellings used to build, run, and render help while its flag stayed permanently at its default value. `.command()`, `.default()`, `.version()`, `.manifest(data)`, and `createCLISchema()` now reject it with `CLIError` code `RESERVED_FLAG`, checking each flag's canonical name, its aliases (hidden ones included), and its custom negated spelling (`.negatable({ alias: 'quiet' })`) through the whole nested subcommand tree. The error names the colliding flag and the root flag that shadows it, and suggests renaming, or `out.status()` for output that root `--quiet` suppresses. Near misses such as `jsonOutput` or `quietMode` stay legal, the default `--no-<name>` spelling never collides, and `version`/`V` stay available to a CLI that declares no version.
217
+
218
+ - **`--completions` collision detection now covers negated spellings and the definition path.**\
219
+ `.negatable({ alias: 'completions' })` and a `createCLISchema()` definition carrying `completionsFlag` both used to build a CLI whose command flag the planner intercepted. Both now throw `CLIError` code `RESERVED_FLAG`, matching what `.completions({ as: 'flag' })` already rejected on the builder.
701
220
 
702
221
  ### Removed
703
222
 
704
- - **Breaking: `.packageJson()`** — deprecated since 2.5. Use `.manifest()`,
705
- which defaults to `files: ['package.json']` and accepts the same pre-loaded
706
- data object.
223
+ - **Breaking: `.packageJson()`** — deprecated since [2.5](#250---2026-06-28).\
224
+ Use `.manifest()`, which defaults to `files: ['package.json']` and accepts the same pre-loaded data object.
707
225
 
708
- - **Breaking: `.denoJson()`** — deprecated since 2.5. Use
709
- `.manifest({ files: ['deno.json', 'deno.jsonc', 'jsr.json'] })`.
226
+ - **Breaking: `.denoJson()`** — deprecated since [2.5](#250---2026-06-28).\
227
+ Use `.manifest({ files: ['deno.json', 'deno.jsonc', 'jsr.json'] })`.
710
228
 
711
- - **Breaking: `ManifestPresetSettings`** — the settings type of the two removed
712
- presets. Use `ManifestSettings`, which adds `files`.
229
+ - **Breaking: `ManifestPresetSettings`**\
230
+ The settings type of the two removed presets. Use `ManifestSettings`, which adds `files`.
713
231
 
714
- - **Breaking: `PackageJsonSettings`** — the deprecated alias for
715
- `ResolvedManifestSettings`, the shape stored in
716
- `CLISchema.packageJsonSettings`. The schema field itself is unchanged.
232
+ - **Breaking: `PackageJsonSettings`**\
233
+ The deprecated alias for `ResolvedManifestSettings`, the shape stored in `CLISchema.packageJsonSettings`. The schema field itself is unchanged.
717
234
 
718
- - **Breaking: `discoverPackageJson()`** — deprecated since 2.5. Use
719
- `discoverManifest(adapter, { startDir, files: ['package.json'] })`; `files`
720
- already defaults to `['package.json']`.
235
+ - **Breaking: `discoverPackageJson()`** — deprecated since [2.5](#250---2026-06-28).\
236
+ Use `discoverManifest(adapter, { startDir, files: ['package.json'] })`; `files` already defaults to `['package.json']`.
721
237
 
722
238
  ### Fixed
723
239
 
724
- - **A variadic argument could not take the prompt its flag twin takes.** The
725
- argument prompt gate read the kind discriminator alone, so
726
- `arg.string().variadic().prompt({ kind: 'multiselect' })` was rejected with
727
- `Prompt kind 'multiselect' is not compatible with string argument <files>`
728
- while `flag.array(flag.string()).prompt({ kind: 'multiselect' })` resolved,
729
- and the scalar `input` and `select` kinds the flag surface rejects were
730
- accepted, resolving a one-element array. The gate now reads the cardinality:
731
- an argument that collects several values takes `multiselect`, and names itself
732
- `variadic string argument <files>` when it reports a mismatch.
733
- `AllowedArgPromptConfig<C>` follows the same rule, so the compiler agrees.
734
-
735
- - **A collection given a config value of the wrong shape said less on the
736
- argument surface.** `flag.array(...).config('p')` over `{ p: 5 }` reported
737
- `Invalid array value from config p for flag --tags`; the positional twin
738
- reported `Invalid value '<redacted>' from config p for argument <tags>`,
739
- naming neither the shape nor a value it actually held. Both surfaces now word
740
- it `Invalid array value` / `Invalid object value`, so the byte-for-byte
741
- wording rule in [Diagnostics and redaction](https://dreamcli.kjanat.dev/guide/semantics#diagnostics-and-redaction)
742
- holds for the collection faults too.
743
-
744
- - **A builder could produce a schema its own factory refuses.** Each modifier
745
- states the kinds it belongs to through a `this` constraint, which the compiler
746
- enforces and a JavaScript caller does not see, so `flag.string().separator(',')`
747
- built a string flag carrying a CLI delimiter and emitted a definition document
748
- `createFlagSchema()` then rejected with `INVALID_SCHEMA`. Twelve modifiers on
749
- the flag surface and eleven on the argument surface behaved this way. Every
750
- builder modifier now runs the same check `createFlagSchema()` /
751
- `createArgSchema()` run, so what a builder produces is always a definition the
752
- framework reads back. A test calling such a modifier through `@ts-expect-error`
753
- and expecting it to build needs `expect(...).toThrow()`.
754
-
755
- - **The normalization factories accepted a kind they have no arm for.**
756
- `createFlagSchema('nope')` and `createArgSchema('count')` built a schema whose
757
- discriminator is outside `FLAG_KINDS` / `ARG_KINDS`, which every exhaustive
758
- `switch (schema.kind)` downstream falls through. The types forbid the call,
759
- but a JavaScript caller reached it, and the keyValue prompt gate showed such a
760
- schema can reach a shipped diagnostic. Both factories now throw
761
- `INVALID_SCHEMA` with `Unknown flag kind 'nope'` / `Unknown arg kind 'count'`,
762
- listing the allowed kinds in `details.allowed`, on the two-argument path, the
763
- definition path, and a nested `elementSchema`.
764
-
765
- - **`flag.array()` with no element threw a raw `TypeError`.** The factory read
766
- `.schema` off the element it was handed, so a JavaScript caller omitting it
767
- got `Cannot read properties of undefined` instead of a framework error. It now
768
- throws `INVALID_SCHEMA` with `flag.array() requires an element builder`.
769
- `flag.keyValue()` and `arg.keyValue()`, whose element is optional, apply the
770
- same check to an element that is supplied.
771
-
772
- - **A positional cut a parse function's message at its last colon.** Off argv,
773
- the argument surface rebuilt the reason for a failure by scanning the message
774
- the flag surface had already written, keeping only the text after the final
775
- `": "`. Anything a parse function put before a colon was lost, and a reason
776
- whose own tail held a colon was dropped whole: `arg.url({ protocols: ['https'] })`
777
- reported `Invalid value '<redacted>' from env ENDPOINT for argument <endpoint>: https`,
778
- and `arg.date()` reported no reason at all. `arg.duration()`, `arg.bytes()`,
779
- and every `arg.custom()` whose error text carries a colon were affected the
780
- same way. Each surface now words its own diagnostic from the value layer's
781
- verdict, so the reason reaches the argument surface whole.
782
-
783
- A parse-function failure off argv is also worded the way the flag surface and
784
- the command line already word it, so `Failed to parse env ENDPOINT for
785
- argument <endpoint>: URL protocol 'http' is not allowed. Allowed: https`
786
- replaces the `Invalid value '<redacted>' …` opening, which announced a
787
- redaction in the same sentence that printed the parse function's own text.
788
- A test asserting the old opening for a non-argv `arg.url()`, `arg.date()`,
789
- `arg.duration()`, `arg.bytes()`, or `arg.custom()` message needs the new one.
790
-
791
- - **A positional withheld what a type mismatch expected.** For a value no
792
- boolean codec could read, the flag surface reported
793
- `Invalid boolean value '<redacted>' …` and suggested
794
- `Set VAR to true/false, 1/0, or yes/no`, while the argument surface reported
795
- `Invalid value '<redacted>' …` and suggested only `Set VAR to a valid boolean`,
796
- which is the question rather than the answer. A string a config object could
797
- not fill carried no `expected` field and no suggestion at all on the argument
798
- surface. Both now match the flag surface: the message names the type, the
799
- details carry `expected`, and the suggestion names what the codec reads.
800
-
801
- - **An argument kind with no compatible prompt was told to use `undefined`.**
802
- `createArgSchema({ kind: 'keyValue', prompt: … })` reached the prompt gate,
803
- which took the first allowed prompt kind from an empty list and reported
804
- `Prompt kind 'input' is not compatible with keyValue argument <vars>. Use
805
- 'undefined' instead` with `Change the prompt to { kind: 'undefined' }`. The
806
- flag surface already had a branch for a kind that is not promptable at all;
807
- both surfaces now share it and report
808
- `keyValue arguments are not promptable` with `Remove the prompt config for <vars>`.
809
-
810
- - **A key-value input told the user to write an array.** A config value of the
811
- wrong shape for `flag.keyValue()` or `arg.keyValue()` reported
812
- `Invalid array value from config c for flag --vars` with `expected: 'array'`
813
- and `Set c to an array in your config`, which is not what an entries input
814
- accepts and, for a config value that already was an array, not even a change.
815
- The fault now carries the shape the cardinality wants: an entries input reads
816
- `Invalid object value …` with `expected: 'object'` and
817
- `Set c to an object in your config` on the flag surface and
818
- `Use KEY=VALUE for <vars>` on the argument surface. A list input is unchanged.
819
-
820
- - **Five types the stability page classified as public were exported from
821
- nowhere.** `NodeProcess`, `DenoNamespace`, and `GlobalForDetect` are the host
822
- objects `createNodeAdapter()`, `createDenoAdapter()`, and `detectRuntime()`
823
- accept, and the page attributes all three to `@kjanat/dreamcli/runtime`, which
824
- exported none of them; a caller injecting a host could not name the parameter
825
- type. `StringArgElementConfig` and `WithoutArgElementEligibility` sat in the
826
- same sentence as `StringElementConfig`, which the root entrypoint does export.
827
- All five are now exported, along with the flag-side
828
- `WithoutElementEligibility` its argument twin mirrors.
829
-
830
- - **A definition document, its input schema, and help all dropped a default the
831
- schema still resolved.** `generateSchema()`, `generateInputSchema()`, and
832
- `formatHelp()` each reported a default only for `presence: 'defaulted'`, but
833
- resolution uses any `defaultValue` a schema carries, and
834
- `createFlagSchema({ kind: 'string', defaultValue: 'dist' })` keeps
835
- `presence: 'optional'`. A document emitted from such a schema decoded back to
836
- a flag with no default, so a round trip through the format changed behavior;
837
- the input schema omitted `default`, and help omitted `(default: dist)` for a
838
- flag that does resolve one. All three now report the default whenever the
839
- schema carries one, on both surfaces, whatever the presence.
840
- Builder-authored schemas are unaffected, since `.default()` sets the
841
- defaulted presence.
842
-
843
- Help no longer calls such an input required either. A default binding always
844
- produces a value, so neither `REQUIRED_FLAG` nor `REQUIRED_ARG` can fire for a
845
- schema carrying a `defaultValue`, yet `flag.string().default('dist').required()`
846
- rendered `[required]` and hid its own default while the positional twin
847
- rendered `(default: prod)` and still demanded a token as `<target>`. A
848
- `defaultValue` now suppresses the `[required]` marker and the angle brackets on
849
- both surfaces; an input without one is unchanged.
850
-
851
- - **A duplicate key leaked its text from every non-argv source.** Under
852
- `.duplicateKeys('error')`, `Duplicate key 'DB_PASSWORD' from env VARS for flag
853
- --vars` quoted the key in the message, in `details.key`, and in `suggest`,
854
- whatever source carried it. A key is half of a `KEY=VALUE` pair, so it is
855
- value text from that source, and the same pair reported `Invalid key-value
856
- pair '<redacted>'` when it failed to split instead. The key is now quoted only
857
- for occurrences the user typed on the command line; stdin, env, config, and
858
- prompt read `Duplicate key '<redacted>'`, carry no `key` in `details`, and
859
- suggest `Set the repeated key once`. Both surfaces follow the rule.
860
-
861
- - **A flag reported a JSON shape fault in the wrong order.** `Invalid JSON
862
- value, expected an object from env VARS for flag --vars` put the expectation
863
- between the fault and the source that carried it. The flag surface now words
864
- it as the argument surface already did: `Invalid JSON value from env VARS for
865
- flag --vars, expected an object`.
866
-
867
- - **`ArgElementFragmentV1` was documented as public but exported from nowhere.**
868
- `stability.md` classifies it with the other version 1 fragment types and
869
- `schema-export.md` names it as the shape of an arg `elementSchema`, but the
870
- type never reached `@kjanat/dreamcli`. It is exported now, alongside its
871
- siblings.
872
-
873
- - **A default rejected on a vowel-initial kind read `a array`.** The
874
- construction-time `INVALID_DEFAULT` message built its subject with a fixed
875
- article, so `createFlagSchema('array', …)` and `createFlagSchema('enum', …)`
876
- produced `Default value for a array flag` and `Default value for a enum flag`.
877
- Both now read `an`.
878
-
879
- - **A duplicate key the user typed said it came from stdin.** Under
880
- `.duplicateKeys('error')`, a repeat among CLI occurrences was worded
881
- `Duplicate key 'A' from stdin for flag --v`, naming a source the value never
882
- had, on a command with no pipe at all. CLI occurrences now name no source
883
- (`Duplicate key 'A' for flag --v`), and a key a `-` occurrence spliced in
884
- still reads `from stdin`. Each occurrence carries its own source through
885
- aggregation, so a collection filled from both names whichever one carried the
886
- repeat. `details` no longer claims `source: 'stdin'` for a typed token, and
887
- the arg surface follows the same rule with `for argument <vars>`.
888
-
889
- - **`flag.count().stdin()` threw only on the definition path.** The builder
890
- method is blocked by its `this` constraint at compile time and
891
- `createFlagSchema('count', { stdin: {} })` throws `INVALID_SCHEMA`, but a
892
- JavaScript caller reaching the builder got a count flag carrying a stdin
893
- binding no stage would ever read. The builder now throws the same error, with
894
- the same message and code. In 3.x neither path complained: `createSchema()`
895
- stored `stdinMode: true` on a count flag and `.stdin()` did not exist on the
896
- count builder at all.
897
-
898
- - **Flags named after `Object.prototype` members were rejected as duplicates** —
899
- `.flag('constructor')`, `.flag('toString')`, `.flag('valueOf')`, and every
900
- other `Object.prototype` member name failed with a `FLAG_NAME_COLLISION`
901
- claiming the command already declared the flag, on commands that declared no
902
- flags at all. `collectPropagatedFlags()` read its descendant records the same
903
- way, so a propagated flag with one of those names would have stopped at every
904
- intermediate subcommand, and `resolveFlags()` read an `.interactive()`
905
- resolver's override record the same way, so the inherited method reached the
906
- prompt gate as a config and failed the command with `CONSTRAINT_VIOLATED`.
907
- `.flag()` refused the name first, so no 3.x CLI ever got that far. Every one of
908
- those reads now tests own keys only, so all eleven of those names behave like
909
- any other and `createCommandSchema()` accepts the schemas `command()` produces.
910
- `__proto__` is the one `Object.prototype` name still rejected, with
911
- `INVALID_SCHEMA` on both construction paths, listed under Changed above.
912
-
913
- - **An env var named after an `Object.prototype` member always read as set** —
914
- `.env('toString')` on a flag, or on an arg, looked the name up on the env
915
- record without checking own keys, so an unset variable resolved to the
916
- inherited method and failed coercion instead of falling through to config,
917
- prompt, or default. Both lookups now test own keys.
918
-
919
- - **`.run()` never read stdin for an arg named after an `Object.prototype`
920
- member** — the precheck that decides whether to read stdin looked the arg name
921
- up on the parsed positionals without checking own keys, so an arg such as
922
- `.arg('toString', arg.string().stdin())` looked already supplied. `.run()`
923
- skipped the read and the command failed with `Missing required argument`
924
- however much was piped to it. The lookup now tests own keys. `.execute()` and
925
- the testkit take `stdinData` from the caller and were never affected.
926
-
927
- - **`out.table()` printed a native method for a column key named after an
928
- `Object.prototype` member** — a column keyed `toString`, `constructor`, or any
929
- other member name read the row with a bare lookup, so a row that carried no
930
- such key rendered `[Function: toString]` in place of the empty cell every
931
- other missing key produces. Dynamic rows typed as `Record<string, unknown>`
932
- are the reachable case, including columns inferred from a first row that does
933
- carry the key. Both the text renderer and the JSON projection now treat a key
934
- that only `Object.prototype` carries as absent. A key held anywhere earlier in
935
- the row's prototype chain still renders, so a class getter and an
936
- `Object.create(defaults)` fallback reach the table as before.
937
-
938
- - **A Standard Schema validator ran against a native method on a failed
939
- resolution** — when a required flag or arg was missing, `resolve()` still ran
940
- the Standard Schema pass before rethrowing, over a values record the failed
941
- resolver had left empty. The pass read each declared name without checking own
942
- keys, so a flag or arg named after an `Object.prototype` member handed its
943
- `flag.custom()` / `arg.custom()` validator the inherited method. The user saw a
944
- second, invented `CONSTRAINT_VIOLATED` beside the real error. The pass now
945
- tests own keys.
946
-
947
- - **Quiet mode leaked spinner and progress output** — activity handles now
948
- resolve to no-ops under quiet verbosity, including interactive TTYs and
949
- explicit static fallbacks. Consumers can route informational rows through
950
- `out.info()` and rely on DreamCLI to suppress the complete presentation
951
- layer without reading private output policy state.
952
-
953
- - **`--json=true` and `--quiet=true` failed as unknown flags**
954
- ([#85](https://github.com/kjanat/dreamcli/issues/85)). Both root flags now
955
- take a value the way `flag.boolean()` does. `true` and `1` enable, `false`
956
- and `0` disable, the last occurrence wins, and an invalid literal fails with
957
- the parser's `INVALID_VALUE` error and exit code 2 instead of `Unknown flag`.
958
- `--help`, `-h`, and `--version` still render ahead of that error, so a
959
- mistyped value never hides the text that documents the flag. Short `-q` keeps
960
- its presence-only form, matching short boolean flags at the command level.
961
- `runCommand()` from `/testkit` reads the same layer, and tokens after `--`
962
- still reach the command untouched.
240
+ - **A variadic argument could not take the prompt its flag twin takes.** The argument prompt gate read the kind discriminator alone, so `arg.string().variadic().prompt({ kind: 'multiselect' })` was rejected with `Prompt kind 'multiselect' is not compatible with string argument <files>` while `flag.array(flag.string()).prompt({ kind: 'multiselect' })` resolved, and the scalar `input` and `select` kinds the flag surface rejects were accepted, resolving a one-element array. The gate now reads the cardinality: an argument that collects several values takes `multiselect`, and names itself `variadic string argument <files>` when it reports a mismatch. `AllowedArgPromptConfig<C>` follows the same rule, so the compiler agrees.
241
+
242
+ - **A collection given a config value of the wrong shape said less on the argument surface.** `flag.array(...).config('p')` over `{ p: 5 }` reported `Invalid array value from config p for flag --tags`; the positional twin reported `Invalid value '<redacted>' from config p for argument <tags>`, naming neither the shape nor a value it actually held. Both surfaces now word it `Invalid array value` / `Invalid object value`, so the byte-for-byte wording rule in [Diagnostics and redaction](https://dreamcli.kjanat.dev/guide/semantics#diagnostics-and-redaction) holds for the collection faults too.
243
+
244
+ - **A builder could produce a schema its own factory refuses.** Each modifier states the kinds it belongs to through a `this` constraint, which the compiler enforces and a JavaScript caller does not see, so `flag.string().separator(',')` built a string flag carrying a CLI delimiter and emitted a definition document `createFlagSchema()` then rejected with `INVALID_SCHEMA`. Twelve modifiers on the flag surface and eleven on the argument surface behaved this way. Every builder modifier now runs the same check `createFlagSchema()` / `createArgSchema()` run, so what a builder produces is always a definition the framework reads back. A test calling such a modifier through `@ts-expect-error` and expecting it to build needs `expect(...).toThrow()`.
245
+
246
+ - **The normalization factories accepted a kind they have no arm for.** `createFlagSchema('nope')` and `createArgSchema('count')` built a schema whose discriminator is outside `FLAG_KINDS` / `ARG_KINDS`, which every exhaustive `switch (schema.kind)` downstream falls through. The types forbid the call, but a JavaScript caller reached it, and the keyValue prompt gate showed such a schema can reach a shipped diagnostic. Both factories now throw `INVALID_SCHEMA` with `Unknown flag kind 'nope'` / `Unknown arg kind 'count'`, listing the allowed kinds in `details.allowed`, on the two-argument path, the definition path, and a nested `elementSchema`.
247
+
248
+ - **`flag.array()` with no element threw a raw `TypeError`.** The factory read `.schema` off the element it was handed, so a JavaScript caller omitting it got `Cannot read properties of undefined` instead of a framework error. It now throws `INVALID_SCHEMA` with `flag.array() requires an element builder`. `flag.keyValue()` and `arg.keyValue()`, whose element is optional, apply the same check to an element that is supplied.
249
+
250
+ - **A positional cut a parse function's message at its last colon.** Off argv, the argument surface rebuilt the reason for a failure by scanning the message the flag surface had already written, keeping only the text after the final `": "`. Anything a parse function put before a colon was lost, and a reason whose own tail held a colon was dropped whole: `arg.url({ protocols: ['https'] })` reported `Invalid value '<redacted>' from env ENDPOINT for argument <endpoint>: https`, and `arg.date()` reported no reason at all. `arg.duration()`, `arg.bytes()`, and every `arg.custom()` whose error text carries a colon were affected the same way. Each surface now words its own diagnostic from the value layer's verdict, so the reason reaches the argument surface whole.
251
+
252
+ A parse-function failure off argv is also worded the way the flag surface and the command line already word it, so `Failed to parse env ENDPOINT for argument <endpoint>: URL protocol 'http' is not allowed. Allowed: https` replaces the `Invalid value '<redacted>' …` opening, which announced a redaction in the same sentence that printed the parse function's own text. A test asserting the old opening for a non-argv `arg.url()`, `arg.date()`, `arg.duration()`, `arg.bytes()`, or `arg.custom()` message needs the new one.
253
+
254
+ - **A positional withheld what a type mismatch expected.** For a value no boolean codec could read, the flag surface reported `Invalid boolean value '<redacted>' …` and suggested `Set VAR to true/false, 1/0, or yes/no`, while the argument surface reported `Invalid value '<redacted>' …` and suggested only `Set VAR to a valid boolean`, which is the question rather than the answer. A string a config object could not fill carried no `expected` field and no suggestion at all on the argument surface. Both now match the flag surface: the message names the type, the details carry `expected`, and the suggestion names what the codec reads.
255
+
256
+ - **An argument kind with no compatible prompt was told to use `undefined`.** `createArgSchema({ kind: 'keyValue', prompt: … })` reached the prompt gate, which took the first allowed prompt kind from an empty list and reported `Prompt kind 'input' is not compatible with keyValue argument <vars>. Use 'undefined' instead` with `Change the prompt to { kind: 'undefined' }`. The flag surface already had a branch for a kind that is not promptable at all; both surfaces now share it and report `keyValue arguments are not promptable` with `Remove the prompt config for <vars>`.
257
+
258
+ - **A key-value input told the user to write an array.** A config value of the wrong shape for `flag.keyValue()` or `arg.keyValue()` reported `Invalid array value from config c for flag --vars` with `expected: 'array'` and `Set c to an array in your config`, which is not what an entries input accepts and, for a config value that already was an array, not even a change. The fault now carries the shape the cardinality wants: an entries input reads `Invalid object value …` with `expected: 'object'` and `Set c to an object in your config` on the flag surface and `Use KEY=VALUE for <vars>` on the argument surface. A list input is unchanged.
259
+
260
+ - **Five types the stability page classified as public were exported from nowhere.** `NodeProcess`, `DenoNamespace`, and `GlobalForDetect` are the host objects `createNodeAdapter()`, `createDenoAdapter()`, and `detectRuntime()` accept, and the page attributes all three to `@kjanat/dreamcli/runtime`, which exported none of them; a caller injecting a host could not name the parameter type. `StringArgElementConfig` and `WithoutArgElementEligibility` sat in the same sentence as `StringElementConfig`, which the root entrypoint does export. All five are now exported, along with the flag-side `WithoutElementEligibility` its argument twin mirrors.
261
+
262
+ - **A definition document, its input schema, and help all dropped a default the schema still resolved.** `generateSchema()`, `generateInputSchema()`, and `formatHelp()` each reported a default only for `presence: 'defaulted'`, but resolution uses any `defaultValue` a schema carries, and `createFlagSchema({ kind: 'string', defaultValue: 'dist' })` keeps `presence: 'optional'`. A document emitted from such a schema decoded back to a flag with no default, so a round trip through the format changed behavior; the input schema omitted `default`, and help omitted `(default: dist)` for a flag that does resolve one. All three now report the default whenever the schema carries one, on both surfaces, whatever the presence. Builder-authored schemas are unaffected, since `.default()` sets the defaulted presence.
263
+
264
+ Help no longer calls such an input required either. A default binding always produces a value, so neither `REQUIRED_FLAG` nor `REQUIRED_ARG` can fire for a schema carrying a `defaultValue`, yet `flag.string().default('dist').required()` rendered `[required]` and hid its own default while the positional twin rendered `(default: prod)` and still demanded a token as `<target>`. A `defaultValue` now suppresses the `[required]` marker and the angle brackets on both surfaces; an input without one is unchanged.
265
+
266
+ - **A duplicate key leaked its text from every non-argv source.** Under `.duplicateKeys('error')`, `Duplicate key 'DB_PASSWORD' from env VARS for flag --vars` quoted the key in the message, in `details.key`, and in `suggest`, whatever source carried it. A key is half of a `KEY=VALUE` pair, so it is value text from that source, and the same pair reported `Invalid key-value pair '<redacted>'` when it failed to split instead. The key is now quoted only for occurrences the user typed on the command line; stdin, env, config, and prompt read `Duplicate key '<redacted>'`, carry no `key` in `details`, and suggest `Set the repeated key once`. Both surfaces follow the rule.
267
+
268
+ - **A flag reported a JSON shape fault in the wrong order.** `Invalid JSON value, expected an object from env VARS for flag --vars` put the expectation between the fault and the source that carried it. The flag surface now words it as the argument surface already did: `Invalid JSON value from env VARS for flag --vars, expected an object`.
269
+
270
+ - **`ArgElementFragmentV1` was documented as public but exported from nowhere.** `stability.md` classifies it with the other version 1 fragment types and `schema-export.md` names it as the shape of an arg `elementSchema`, but the type never reached `@kjanat/dreamcli`. It is exported now, alongside its siblings.
271
+
272
+ - **A default rejected on a vowel-initial kind read `a array`.** The construction-time `INVALID_DEFAULT` message built its subject with a fixed article, so `createFlagSchema('array', …)` and `createFlagSchema('enum', …)` produced `Default value for a array flag` and `Default value for a enum flag`. Both now read `an`.
273
+
274
+ - **A duplicate key the user typed said it came from stdin.** Under `.duplicateKeys('error')`, a repeat among CLI occurrences was worded `Duplicate key 'A' from stdin for flag --v`, naming a source the value never had, on a command with no pipe at all. CLI occurrences now name no source (`Duplicate key 'A' for flag --v`), and a key a `-` occurrence spliced in still reads `from stdin`. Each occurrence carries its own source through aggregation, so a collection filled from both names whichever one carried the repeat. `details` no longer claims `source: 'stdin'` for a typed token, and the arg surface follows the same rule with `for argument <vars>`.
275
+
276
+ - **`flag.count().stdin()` threw only on the definition path.** The builder method is blocked by its `this` constraint at compile time and `createFlagSchema('count', { stdin: {} })` throws `INVALID_SCHEMA`, but a JavaScript caller reaching the builder got a count flag carrying a stdin binding no stage would ever read. The builder now throws the same error, with the same message and code. In 3.x neither path complained: `createSchema()` stored `stdinMode: true` on a count flag and `.stdin()` did not exist on the count builder at all.
277
+
278
+ - **Flags named after `Object.prototype` members were rejected as duplicates** — `.flag('constructor')`, `.flag('toString')`, `.flag('valueOf')`, and every other `Object.prototype` member name failed with a `FLAG_NAME_COLLISION` claiming the command already declared the flag, on commands that declared no flags at all. `collectPropagatedFlags()` read its descendant records the same way, so a propagated flag with one of those names would have stopped at every intermediate subcommand, and `resolveFlags()` read an `.interactive()` resolver's override record the same way, so the inherited method reached the prompt gate as a config and failed the command with `CONSTRAINT_VIOLATED`. `.flag()` refused the name first, so no 3.x CLI ever got that far. Every one of those reads now tests own keys only, so all eleven of those names behave like any other and `createCommandSchema()` accepts the schemas `command()` produces. `__proto__` is the one `Object.prototype` name still rejected, with `INVALID_SCHEMA` on both construction paths, listed under Changed above.
279
+
280
+ - **An env var named after an `Object.prototype` member always read as set** — `.env('toString')` on a flag, or on an arg, looked the name up on the env record without checking own keys, so an unset variable resolved to the inherited method and failed coercion instead of falling through to config, prompt, or default. Both lookups now test own keys.
281
+
282
+ - **`.run()` never read stdin for an arg named after an `Object.prototype` member** — the precheck that decides whether to read stdin looked the arg name up on the parsed positionals without checking own keys, so an arg such as `.arg('toString', arg.string().stdin())` looked already supplied. `.run()` skipped the read and the command failed with `Missing required argument` however much was piped to it. The lookup now tests own keys. `.execute()` and the testkit take `stdinData` from the caller and were never affected.
283
+
284
+ - **`out.table()` printed a native method for a column key named after an `Object.prototype` member** — a column keyed `toString`, `constructor`, or any other member name read the row with a bare lookup, so a row that carried no such key rendered `[Function: toString]` in place of the empty cell every other missing key produces. Dynamic rows typed as `Record<string, unknown>` are the reachable case, including columns inferred from a first row that does carry the key. Both the text renderer and the JSON projection now treat a key that only `Object.prototype` carries as absent. A key held anywhere earlier in the row's prototype chain still renders, so a class getter and an `Object.create(defaults)` fallback reach the table as before.
285
+
286
+ - **A Standard Schema validator ran against a native method on a failed resolution** — when a required flag or arg was missing, `resolve()` still ran the Standard Schema pass before rethrowing, over a values record the failed resolver had left empty. The pass read each declared name without checking own keys, so a flag or arg named after an `Object.prototype` member handed its `flag.custom()` / `arg.custom()` validator the inherited method. The user saw a second, invented `CONSTRAINT_VIOLATED` beside the real error. The pass now tests own keys.
287
+
288
+ - **Quiet mode leaked spinner and progress output** — activity handles now resolve to no-ops under quiet verbosity, including interactive TTYs and explicit static fallbacks. Consumers can route informational rows through `out.info()` and rely on DreamCLI to suppress the complete presentation layer without reading private output policy state.
289
+
290
+ - **`--json=true` and `--quiet=true` failed as unknown flags** (https://github.com/kjanat/dreamcli/issues/85). Both root flags now take a value the way `flag.boolean()` does. `true` and `1` enable, `false` and `0` disable, the last occurrence wins, and an invalid literal fails with the parser's `INVALID_VALUE` error and exit code 2 instead of `Unknown flag`. `--help`, `-h`, and `--version` still render ahead of that error, so a mistyped value never hides the text that documents the flag. Short `-q` keeps its presence-only form, matching short boolean flags at the command level. `runCommand()` from `/testkit` reads the same layer, and tokens after `--` still reach the command untouched.
963
291
 
964
292
  ## [3.0.1] - 2026-07-21
965
293
 
966
- No library code changed; this release ships agent-facing material that was
967
- being built but never published.
294
+ No library code changed; this release ships agent-facing material that was being built but never published.
968
295
 
969
296
  ### Added
970
297
 
971
- - **The `cli-creation` skill now ships in the package** — `skills/` was absent
972
- from npm's `files` and JSR's `publish.include`, so consumers installing from
973
- either registry never received it.
974
- - **Documentation lookup paths in the `cli-creation` skill** — `deno doc`
975
- against JSR (works whether the consumer installed from npm or JSR, including
976
- subpaths, `--json`, and `--filter`), plus the site's `llms.txt`,
977
- `llms-full.txt`, and `/raw/` markdown endpoints, so API shapes are read from
978
- the published package rather than recalled.
298
+ - **The `cli-creation` skill now ships in the package** — `skills/` was absent from npm's `files` and JSR's `publish.include`, so consumers installing from either registry never received it.
299
+ - **Documentation lookup paths in the `cli-creation` skill** — `deno doc` against JSR (works whether the consumer installed from npm or JSR, including subpaths, `--json`, and `--filter`), plus the site's `llms.txt`, `llms-full.txt`, and `/raw/` markdown endpoints, so API shapes are read from the published package rather than recalled.
979
300
 
980
301
  ## [3.0.0] - 2026-07-21
981
302
 
982
- The stable 3.0.0 release. It ships the code of 3.0.0-rc.20 plus the fix and
983
- documentation below; the complete v3 feature record lives in the rc.1 - rc.20
984
- sections that follow. Upgrading from 2.x is covered by the new
985
- [upgrade guide](https://dreamcli.kjanat.dev/guide/upgrading-v3).
303
+ The stable 3.0.0 release. It ships the code of 3.0.0-rc.20 plus the fix and documentation below; the complete v3 feature record lives in the rc.1 - rc.20 sections that follow. Upgrading from 2.x is covered by the new [upgrade guide](https://dreamcli.kjanat.dev/guide/upgrading-v3).
986
304
 
987
305
  ### Fixed
988
306
 
989
- - **`runCommand()` rejected `--quiet`/`-q`** — the testkit gained the root-flag
990
- layer for `--json` in rc.1, but `--quiet` (added in rc.17) was never taught to
991
- it, so copying a real `mycli --quiet …` invocation into a test failed with
992
- `Unknown flag` (exit 2). Both spellings are now detected before the `--`
993
- separator, set quiet verbosity, and are stripped before parsing; a literal
994
- post-separator `--quiet` still reaches the command.
995
- - **Mobile documentation hovers** — the twoslash bottom sheet collapsed to a
996
- 2px sliver (a transformed popper ancestor became the containing block for the
997
- fixed sheet), its backdrop stayed over the page after dismissal, and closing a
998
- popup disabled it permanently via an inline `display: none`.
307
+ - **`runCommand()` rejected `--quiet`/`-q`** — the testkit gained the root-flag layer for `--json` in rc.1, but `--quiet` (added in rc.17) was never taught to it, so copying a real `mycli --quiet …` invocation into a test failed with `Unknown flag` (exit 2). Both spellings are now detected before the `--` separator, set quiet verbosity, and are stripped before parsing; a literal post-separator `--quiet` still reaches the command.
308
+ - **Mobile documentation hovers** — the twoslash bottom sheet collapsed to a 2px sliver (a transformed popper ancestor became the containing block for the fixed sheet), its backdrop stayed over the page after dismissal, and closing a popup disabled it permanently via an inline `display: none`.
999
309
 
1000
310
  ### Added
1001
311
 
1002
- - **Upgrade guide** — `docs/guide/upgrading-v3.md` documents every 2.5.0 →
1003
- 3.0.0 breaking and behavioral change with before/after code.
1004
- - **Five new examples** covering the v3 surface: `flag-types.ts` (url, path
1005
- with `create`, date, duration, bytes, count, keyValue, constraints, array
1006
- separator/unique), `parser-control.ts` (negatable, duplicates, spelling
1007
- parity), `standard-schema.ts` (Standard Schema v1 interop),
1008
- `help-config.ts` (themes, `flagOrder`, routable default, JSON help),
1009
- `output-extras.ts` (`out.color`, hyperlink gating, `setExitCode`).
312
+ - **Upgrade guide** — `docs/guide/upgrading-v3.md` documents every 2.5.0 → 3.0.0 breaking and behavioral change with before/after code.
313
+ - **Five new examples** covering the v3 surface: `flag-types.ts` (url, path with `create`, date, duration, bytes, count, keyValue, constraints, array separator/unique), `parser-control.ts` (negatable, duplicates, spelling parity), `standard-schema.ts` (Standard Schema v1 interop), `help-config.ts` (themes, `flagOrder`, routable default, JSON help), `output-extras.ts` (`out.color`, hyperlink gating, `setExitCode`).
1010
314
 
1011
315
  ### Changed
1012
316
 
1013
- - **Examples modernized** — `basic.ts` uses function-form `.example()`,
1014
- `json-mode.ts` and `middleware.ts` use `out.status()` and document
1015
- `--quiet`, `transport-launcher.ts` replaces its hand-rolled port check
1016
- with declarative numeric constraints.
1017
- - **`skills/cli-creation` rewritten for v3** — corrected stale grounding paths
1018
- (`examples/standalone/`, `apps/docs/` no longer exist), rebuilt the pattern
1019
- cookbook around the v3 surface with every snippet type-checked against the
1020
- published types, and modernized the scaffolder templates (function-form
1021
- examples, declarative numeric constraints instead of hand-clamping,
1022
- `out.status()`, a `--quiet` test).
1023
- - **README refreshed** — the flag-types block lists the full v3 family
1024
- (dropping the `flag.custom` URL sample that `flag.url()` superseded), the
1025
- output sample shows `out.status()` / `out.setExitCode()` / `--quiet`, the
1026
- completions sample covers the eager-flag form and fixes a
1027
- `completion`/`completions` typo.
317
+ - **Examples modernized** — `basic.ts` uses function-form `.example()`, `json-mode.ts` and `middleware.ts` use `out.status()` and document `--quiet`, `transport-launcher.ts` replaces its hand-rolled port check with declarative numeric constraints.
318
+ - **`skills/cli-creation` rewritten for v3** — corrected stale grounding paths (`examples/standalone/`, `apps/docs/` no longer exist), rebuilt the pattern cookbook around the v3 surface with every snippet type-checked against the published types, and modernized the scaffolder templates (function-form examples, declarative numeric constraints instead of hand-clamping, `out.status()`, a `--quiet` test).
319
+ - **README refreshed** — the flag-types block lists the full v3 family (dropping the `flag.custom` URL sample that `flag.url()` superseded), the output sample shows `out.status()` / `out.setExitCode()` / `--quiet`, the completions sample covers the eager-flag form and fixes a `completion`/`completions` typo.
1028
320
 
1029
321
  ## [3.0.0-rc.20] - 2026-07-21
1030
322
 
1031
323
  ### Changed
1032
324
 
1033
- - **ansispeck `^0.4.1`** — bumped from `^0.2.0` (npm dependency and JSR
1034
- import map).
325
+ - **ansispeck `^0.4.1`** — bumped from `^0.2.0` (npm dependency and JSR import map).
1035
326
 
1036
327
  ## [3.0.0-rc.19] - 2026-07-21
1037
328
 
1038
329
  ### Added
1039
330
 
1040
- - **Expanded config discovery** (#61) — the default search now covers three
1041
- scopes, first match wins, no merging:
1042
- 1. **Project**: the base directory (default `cwd`) and every ancestor up
1043
- to the filesystem root, nearest first, each probed for
1044
- `.{appName}.{ext}`, `{appName}.config.{ext}`, and the new
1045
- `.config/{appName}.{ext}` convention.
1046
- 2. **User**: XDG / AppData as before, plus
1047
- `~/Library/Application Support/{appName}/config.{ext}` on macOS.
331
+ - **Expanded config discovery** (#61) — the default search now covers three scopes, first match wins, no merging:
332
+ 1. **Project**: the base directory (default `cwd`) and every ancestor up to the filesystem root, nearest first, each probed for `.{appName}.{ext}`, `{appName}.config.{ext}`, and the new `.config/{appName}.{ext}` convention.
333
+ 2. **User**: XDG / AppData as before, plus `~/Library/Application Support/{appName}/config.{ext}` on macOS.
1048
334
  3. **System**: `/etc/{appName}/config.{ext}` on Linux and macOS.
1049
- - **`baseDir` discovery option** — `discoverConfig()` accepts a base
1050
- directory to anchor the project-scope walk somewhere other than `cwd`.
1051
- - **`RuntimeAdapter.userConfigDirs` / `systemConfigDirs`** — optional
1052
- ordered config roots supplied by the runtime adapters; discovery falls
1053
- back to `[configDir]` / `[]` when a custom adapter omits them.
335
+ - **`baseDir` discovery option** — `discoverConfig()` accepts a base directory to anchor the project-scope walk somewhere other than `cwd`.
336
+ - **`RuntimeAdapter.userConfigDirs` / `systemConfigDirs`** — optional ordered config roots supplied by the runtime adapters; discovery falls back to `[configDir]` / `[]` when a custom adapter omits them.
1054
337
 
1055
338
  ### Changed
1056
339
 
1057
- - **Breaking**: `buildConfigSearchPaths(appName, options)` replaces the
1058
- positional `(appName, cwd, configDir, loaders?)` signature; options carry
1059
- `baseDir`, `userConfigDirs`, `systemConfigDirs`, and `loaders`.
340
+ - **Breaking**: `buildConfigSearchPaths(appName, options)` replaces the positional `(appName, cwd, configDir, loaders?)` signature; options carry `baseDir`, `userConfigDirs`, `systemConfigDirs`, and `loaders`.
1060
341
 
1061
342
  ## [3.0.0-rc.18] - 2026-07-21
1062
343
 
1063
344
  ### Added
1064
345
 
1065
- - **`flag.path({ type: 'directory', create: true })`** — creates the directory
1066
- (recursively) at resolution time when nothing exists at the path. Only
1067
- available with `type: 'directory'`, enforced at the type level. Creation
1068
- runs through a new `mkdir` seam: `RuntimeAdapter.mkdir`, overridable via
1069
- run options, noop in the test adapter, so `src/core` stays process-free.
346
+ - **`flag.path({ type: 'directory', create: true })`** — creates the directory (recursively) at resolution time when nothing exists at the path. Only available with `type: 'directory'`, enforced at the type level. Creation runs through a new `mkdir` seam: `RuntimeAdapter.mkdir`, overridable via run options, noop in the test adapter, so `src/core` stays process-free.
1070
347
 
1071
348
  ### Fixed
1072
349
 
1073
- - **`flag.path({ type, mustExist: false })` rejected missing paths** — the
1074
- builder recorded the explicit `mustExist: false`, but resolution errored on
1075
- any missing path whenever path checks were active, making an optional
1076
- to-be-created path (e.g. an `--outdir` that the command itself creates)
1077
- impossible to declare. A missing path now passes when `mustExist` is
1078
- `false`; an existing path is still type-checked.
350
+ - **`flag.path({ type, mustExist: false })` rejected missing paths** — the builder recorded the explicit `mustExist: false`, but resolution errored on any missing path whenever path checks were active, making an optional to-be-created path (e.g. an `--outdir` that the command itself creates) impossible to declare. A missing path now passes when `mustExist` is `false`; an existing path is still type-checked.
1079
351
 
1080
352
  ## [3.0.0-rc.17] - 2026-07-20
1081
353
 
1082
354
  ### Added
1083
355
 
1084
- - **`out.status()`** — a success/status line channel that writes to **stderr**
1085
- (stdout stays clean for piping) and is suppressed under quiet verbosity.
1086
- `info` remains stdout-bound; `warn`/`error` remain always-emitted.
1087
- - **Global `--quiet`/`-q` flag** — sets quiet verbosity on every CLI, wired
1088
- like `--json`: detected and stripped at the root before dispatch (command
1089
- schemas never see it), honoring the `--` separator so a literal `-q`
1090
- positional reaches the command unchanged. Listed under root help's
1091
- `Global options:`.
356
+ - **`out.status()`** — a success/status line channel that writes to **stderr** (stdout stays clean for piping) and is suppressed under quiet verbosity. `info` remains stdout-bound; `warn`/`error` remain always-emitted.
357
+ - **Global `--quiet`/`-q` flag** — sets quiet verbosity on every CLI, wired like `--json`: detected and stripped at the root before dispatch (command schemas never see it), honoring the `--` separator so a literal `-q` positional reaches the command unchanged. Listed under root help's `Global options:`.
1092
358
 
1093
359
  ### Fixed
1094
360
 
1095
- - **`.run()` misread a post-separator `--json`** — runtime preflight used a
1096
- naive `includes('--json')`, so `mycli cmd -- --json` entered JSON mode via
1097
- the adapter path even though `.execute()` correctly treats it as a
1098
- positional. Preflight now uses the `--`-aware detection.
361
+ - **`.run()` misread a post-separator `--json`** — runtime preflight used a naive `includes('--json')`, so `mycli cmd -- --json` entered JSON mode via the adapter path even though `.execute()` correctly treats it as a positional. Preflight now uses the `--`-aware detection.
1099
362
 
1100
363
  ## [3.0.0-rc.16] - 2026-07-20
1101
364
 
1102
365
  ### Added
1103
366
 
1104
- - **`resolveRenderContext(argv, options?)`** — pre-`run()` probe returning the
1105
- output decisions the framework will make for a given argv: `jsonMode`
1106
- (`--`-aware `--json` detection), `isTTY`, the gated `color` palette, and
1107
- `isHyperlinkSupported`. Computed with the same composition `.execute()`/
1108
- `.run()` feed into the output channel, so content styled before `run()` —
1109
- banners, hand-rendered help — matches the channel that will actually render,
1110
- with zero argv re-parsing.
1111
- - **`includesBeforeSeparator` / `stripBeforeSeparator`** exported from the
1112
- package root — the `--`-aware root-flag primitives, for consumers who only
1113
- need correct flag detection.
367
+ - **`resolveRenderContext(argv, options?)`** — pre-`run()` probe returning the output decisions the framework will make for a given argv: `jsonMode` (`--`-aware `--json` detection), `isTTY`, the gated `color` palette, and `isHyperlinkSupported`. Computed with the same composition `.execute()`/ `.run()` feed into the output channel, so content styled before `run()` — banners, hand-rendered help — matches the channel that will actually render, with zero argv re-parsing.
368
+ - **`includesBeforeSeparator` / `stripBeforeSeparator`** exported from the package root — the `--`-aware root-flag primitives, for consumers who only need correct flag detection.
1114
369
 
1115
370
  ## [3.0.0-rc.15] - 2026-07-20
1116
371
 
1117
372
  ### Added
1118
373
 
1119
- - **Configurable flag order in help** — `.help({ flagOrder })` controls the
1120
- `Flags:` table order: `'alphabetical'` (default, short-aliased flags first
1121
- then alphabetical) or `'declaration'` (the order `.flag()` was called). For
1122
- full control, `.help({ sortFlags: (a, b) => number })` supplies a custom
1123
- comparator over flag names that wins over `flagOrder`. Both are also
1124
- accepted at runtime via `execute`/`run` `help` options.
374
+ - **Configurable flag order in help** — `.help({ flagOrder })` controls the `Flags:` table order: `'alphabetical'` (default, short-aliased flags first then alphabetical) or `'declaration'` (the order `.flag()` was called). For full control, `.help({ sortFlags: (a, b) => number })` supplies a custom comparator over flag names that wins over `flagOrder`. Both are also accepted at runtime via `execute`/`run` `help` options.
1125
375
 
1126
376
  ## [3.0.0-rc.14] - 2026-07-20
1127
377
 
1128
378
  ### Added
1129
379
 
1130
- - **Function-form examples** — `.example()` now accepts a
1131
- `(meta) => string` builder alongside the literal string. `meta` carries the
1132
- invoked program `name` (`help.binName`, falling back to the command name) and
1133
- `version`, resolved at render time, so examples reference the real program
1134
- name instead of hardcoding it and stay truthful under symlinks, `inheritName`,
1135
- and `npx x` vs a global install. The thunk resolves in both `--help` text
1136
- (composing with example highlighting) and `--json`/definition-schema output.
1137
- - **`ExampleMeta`** and **`ExampleCommand`** public types for annotating
1138
- function-form example builders.
380
+ - **Function-form examples** — `.example()` now accepts a `(meta) => string` builder alongside the literal string. `meta` carries the invoked program `name` (`help.binName`, falling back to the command name) and `version`, resolved at render time, so examples reference the real program name instead of hardcoding it and stay truthful under symlinks, `inheritName`, and `npx x` vs a global install. The thunk resolves in both `--help` text (composing with example highlighting) and `--json`/definition-schema output.
381
+ - **`ExampleMeta`** and **`ExampleCommand`** public types for annotating function-form example builders.
1139
382
 
1140
383
  ## [3.0.0-rc.13] - 2026-07-20
1141
384
 
1142
385
  ### Changed
1143
386
 
1144
- - **Syntax-highlighted example commands** — the `Examples:` help section now
1145
- highlights each command per token: the leading binary via `usageBin` (bold)
1146
- and flag tokens (`-x`, `--long`) via `flag` (cyan), with values left plain.
1147
- Tokenizing is quote-aware so `--scope './a b'` stays one token, and the
1148
- existing color gate is respected (identity formatters when `NO_COLOR` or
1149
- non-TTY), so `stripAnsi(colored)` still equals the plain rendering.
387
+ - **Syntax-highlighted example commands** — the `Examples:` help section now highlights each command per token: the leading binary via `usageBin` (bold) and flag tokens (`-x`, `--long`) via `flag` (cyan), with values left plain. Tokenizing is quote-aware so `--scope './a b'` stays one token, and the existing color gate is respected (identity formatters when `NO_COLOR` or non-TTY), so `stripAnsi(colored)` still equals the plain rendering.
1150
388
 
1151
389
  ## [3.0.0-rc.12] - 2026-07-20
1152
390
 
1153
391
  ### Added
1154
392
 
1155
- - **`out.isHyperlinkSupported`** — resolved OSC 8 hyperlink gate on the output
1156
- channel. Honors `NO_HYPERLINKS`/`FORCE_HYPERLINKS` and the
1157
- `--no-hyperlinks`/`--hyperlinks` flags, falling back to `isTTY`. Consumers
1158
- rendering their own `out.color.link(...)` output can gate on it to keep OSC 8
1159
- escapes out of piped or opted-out contexts.
1160
- - **Standard Schema v1 validation** — `flag.custom(schema)` and
1161
- `arg.custom(schema)` accept any conforming validator (including callable,
1162
- sync, and async schemas) with inferred output types and no runtime
1163
- dependency. Validation runs after source resolution, so argv, env, config,
1164
- prompt, stdin, and default values behave consistently; array flags and
1165
- variadic args validate each element.
1166
- - **`isMainModule(import.meta)`**: Compatibility helper for consumers whose
1167
- ambient `ImportMeta` interface omits `main`. Projects with normal Node, Bun,
1168
- or Deno runtime typings can keep using the conventional
1169
- `if (import.meta.main)` guard directly.
393
+ - **`out.isHyperlinkSupported`** — resolved OSC 8 hyperlink gate on the output channel. Honors `NO_HYPERLINKS`/`FORCE_HYPERLINKS` and the `--no-hyperlinks`/`--hyperlinks` flags, falling back to `isTTY`. Consumers rendering their own `out.color.link(...)` output can gate on it to keep OSC 8 escapes out of piped or opted-out contexts.
394
+ - **Standard Schema v1 validation** — `flag.custom(schema)` and `arg.custom(schema)` accept any conforming validator (including callable, sync, and async schemas) with inferred output types and no runtime dependency. Validation runs after source resolution, so argv, env, config, prompt, stdin, and default values behave consistently; array flags and variadic args validate each element.
395
+ - **`isMainModule(import.meta)`**: Compatibility helper for consumers whose ambient `ImportMeta` interface omits `main`. Projects with normal Node, Bun, or Deno runtime typings can keep using the conventional `if (import.meta.main)` guard directly.
1170
396
 
1171
397
  ### Changed
1172
398
 
1173
- - **`.manifest({ from: import.meta })` compatibility form**: Anchored manifest
1174
- discovery now also accepts the calling module's complete `import.meta`
1175
- object and extracts its URL internally. The conventional
1176
- `{ from: import.meta.url }` form remains supported and preferred when runtime
1177
- typings expose `url`. Together with `isMainModule(import.meta)`, the new forms
1178
- avoid global `ImportMeta` augmentation, allowing consumers with an empty
1179
- ambient `ImportMeta` interface to pass both TypeScript/Deno checks and JSR
1180
- publish validation.
399
+ - **`.manifest({ from: import.meta })` compatibility form**: Anchored manifest discovery now also accepts the calling module's complete `import.meta` object and extracts its URL internally. The conventional `{ from: import.meta.url }` form remains supported and preferred when runtime typings expose `url`. Together with `isMainModule(import.meta)`, the new forms avoid global `ImportMeta` augmentation, allowing consumers with an empty ambient `ImportMeta` interface to pass both TypeScript/Deno checks and JSR publish validation.
1181
400
 
1182
401
  ### Removed
1183
402
 
1184
- - **Internal schema DSL** — the private template-literal parser, validator, and
1185
- JSON Schema converter were replaced by direct definition-schema objects,
1186
- removing roughly 1,500 lines without changing the generated schema.
403
+ - **Internal schema DSL** — the private template-literal parser, validator, and JSON Schema converter were replaced by direct definition-schema objects, removing roughly 1,500 lines without changing the generated schema.
1187
404
 
1188
405
  ### Fixed
1189
406
 
1190
- - **`NO_HYPERLINKS` ignored in the help header** — root-help header hyperlinks
1191
- gated on raw TTY status, so `NO_HYPERLINKS=1` (and `--no-hyperlinks`) still
1192
- emitted OSC 8 links in the header. The gate now consults
1193
- `out.isHyperlinkSupported`, which respects the standard hyperlink overrides.
407
+ - **`NO_HYPERLINKS` ignored in the help header** — root-help header hyperlinks gated on raw TTY status, so `NO_HYPERLINKS=1` (and `--no-hyperlinks`) still emitted OSC 8 links in the header. The gate now consults `out.isHyperlinkSupported`, which respects the standard hyperlink overrides.
1194
408
 
1195
409
  ## [3.0.0-rc.11] - 2026-07-15
1196
410
 
1197
411
  ### Fixed
1198
412
 
1199
- - **JSR publish** — the Deno import map pinned `ansispeck` below `0.2.0`,
1200
- so the JSR build resolved an ansispeck whose `createColors` rejected
1201
- `osc8`'s two-argument call and failed type checking. The map now tracks
1202
- `^0.2.0` alongside the npm dependency. (rc.10 published to npm only.)
413
+ - **JSR publish** — the Deno import map pinned `ansispeck` below `0.2.0`, so the JSR build resolved an ansispeck whose `createColors` rejected `osc8`'s two-argument call and failed type checking. The map now tracks `^0.2.0` alongside the npm dependency. (rc.10 published to npm only.)
1203
414
 
1204
415
  ## [3.0.0-rc.10] - 2026-07-15
1205
416
 
1206
417
  ### Changed
1207
418
 
1208
- - **`osc8()` link text is optional** — it now defaults to the link target, so
1209
- `osc8('https://x.dev')` renders as a hyperlink displaying its own URL.
1210
- Terminals without OSC 8 support still show a usable address. Passing an
1211
- explicit label is unchanged.
1212
- - **`osc8()` now delegates to `ansispeck`'s hyperlink constructor** — it emits
1213
- the **ST** (`ESC \`) terminator instead of **BEL** (`\x07`). Both are valid
1214
- OSC 8 terminators supported by modern terminals; the rendered link is
1215
- unchanged. This removes dreamcli's last hand-rolled escape-sequence code.
419
+ - **`osc8()` link text is optional** — it now defaults to the link target, so `osc8('https://x.dev')` renders as a hyperlink displaying its own URL. Terminals without OSC 8 support still show a usable address. Passing an explicit label is unchanged.
420
+ - **`osc8()` now delegates to `ansispeck`'s hyperlink constructor** — it emits the **ST** (`ESC \`) terminator instead of **BEL** (`\x07`). Both are valid OSC 8 terminators supported by modern terminals; the rendered link is unchanged. This removes dreamcli's last hand-rolled escape-sequence code.
1216
421
 
1217
422
  ## [3.0.0-rc.9] - 2026-07-11
1218
423
 
1219
424
  ### Added
1220
425
 
1221
- - **JSON help** — `--help` with `--json` emits the CLI's definition document
1222
- (the `generateSchema()` shape, `$schema`-tagged) on stdout instead of help
1223
- text, for root help, `help <command>`, and `<command> --help` alike. New
1224
- `generateCommandSchema(schema)` export produces the per-command document.
426
+ - **JSON help** — `--help` with `--json` emits the CLI's definition document (the `generateSchema()` shape, `$schema`-tagged) on stdout instead of help text, for root help, `help <command>`, and `<command> --help` alike. New `generateCommandSchema(schema)` export produces the per-command document.
1225
427
 
1226
428
  ### Changed
1227
429
 
1228
- - **`generateSchema()` emits the default command's full definition** — the
1229
- `defaultCommand` field was a name-only string reference while the default
1230
- command's flags/args appeared nowhere in the document (it never lists in
1231
- `commands`). It is now the complete serialized command.
430
+ - **`generateSchema()` emits the default command's full definition** — the `defaultCommand` field was a name-only string reference while the default command's flags/args appeared nowhere in the document (it never lists in `commands`). It is now the complete serialized command.
1232
431
 
1233
- - **`flag.array()` rejects non-element builders at compile time** — the
1234
- element position now requires a builder carrying only value-shape settings
1235
- (kind, constraints, enum values, `parseFn`). Flag-level modifiers
1236
- (`.alias()`, `.env()`, `.default()`, `.prompt()`, `.describe()`, …) were
1237
- silently ignored on elements before; passing them is now a type error, as
1238
- is `flag.path()` / `flag.count()` / `flag.keyValue()` / nested arrays.
1239
- Type-level only — no runtime behavior change.
432
+ - **`flag.array()` rejects non-element builders at compile time** — the element position now requires a builder carrying only value-shape settings (kind, constraints, enum values, `parseFn`). Flag-level modifiers (`.alias()`, `.env()`, `.default()`, `.prompt()`, `.describe()`, …) were silently ignored on elements before; passing them is now a type error, as is `flag.path()` / `flag.count()` / `flag.keyValue()` / nested arrays. Type-level only — no runtime behavior change.
1240
433
 
1241
434
  ## [3.0.0-rc.8] - 2026-07-11
1242
435
 
1243
436
  ### Added
1244
437
 
1245
- - **Themed help output** — root and per-command help render with a semantic
1246
- color theme (bold+underlined section titles, cyan literals, dimmed metadata,
1247
- yellow deprecations) whenever color is enabled, using the same gate as
1248
- `out.color` (TTY + color support, no `--json`, `NO_COLOR`/`FORCE_COLOR`
1249
- honored). Piped and JSON output stays byte-clean. Customize via
1250
- `.help({ theme: (c) => ({ sectionTitle: c.magenta }) })` — the factory
1251
- receives the gated ansispeck palette and is never invoked when color is off,
1252
- so custom themes cannot leak escapes. New public types: `HelpTheme`,
1253
- `HelpThemeFactory`.
1254
- - **Negatable booleans** — `flag.boolean().negatable()` accepts `--no-<name>`
1255
- as `false`. Both spellings are one logical flag (last CLI occurrence wins,
1256
- shared duplicate policy); the negated spelling is presence-only
1257
- (`--no-foo=x` errors) and renders as `--[no-]foo` in help. Custom spelling
1258
- via `{ alias }`, unadvertised via `{ hidden }`. Env/config/prompt/default
1259
- resolution is unchanged.
1260
- - **Duplicate policy** — `.duplicates('last' | 'first' | 'error')` on
1261
- singleton flags controls repeated CLI occurrences. `'error'` throws
1262
- `ParseError` code `DUPLICATE_FLAG` with `{ flag, count, values }` details;
1263
- `'first'` keeps the first value while still consuming later value tokens.
1264
- Counted per logical flag (aliases + negated + parity spellings); env/config
1265
- precedence is never a duplicate.
1266
- - **`packageRepositoryUrl(pkg, { require: true })`** — narrows the return
1267
- type to `string`, throwing a `CLIError` (code `INVALID_REPOSITORY`) at the
1268
- call site when the `repository` field is missing or not a recognisable
1269
- locator. Removes the `!` assertion for manifests known to carry a valid
1270
- repository, with the guarantee enforced at runtime rather than assumed.
1271
- - **Flag spelling parity (kebab ↔ camel)** — `--doThis` matches a flag named
1272
- `do-this` and vice versa, for names and long aliases, on by default.
1273
- Handler keys, help, completions, and suggestions stay canonical.
1274
- Automatically disabled per pair when both spellings are declared explicitly;
1275
- globally via `cli('mycli', { flags: { caseParity: false } })` (new
1276
- `cli(name, options)` overload) or `RunOptions.flags`.
438
+ - **Themed help output** — root and per-command help render with a semantic color theme (bold+underlined section titles, cyan literals, dimmed metadata, yellow deprecations) whenever color is enabled, using the same gate as `out.color` (TTY + color support, no `--json`, `NO_COLOR`/`FORCE_COLOR` honored). Piped and JSON output stays byte-clean. Customize via `.help({ theme: (c) => ({ sectionTitle: c.magenta }) })` — the factory receives the gated ansispeck palette and is never invoked when color is off, so custom themes cannot leak escapes. New public types: `HelpTheme`, `HelpThemeFactory`.
439
+ - **Negatable booleans** — `flag.boolean().negatable()` accepts `--no-<name>` as `false`. Both spellings are one logical flag (last CLI occurrence wins, shared duplicate policy); the negated spelling is presence-only (`--no-foo=x` errors) and renders as `--[no-]foo` in help. Custom spelling via `{ alias }`, unadvertised via `{ hidden }`. Env/config/prompt/default resolution is unchanged.
440
+ - **Duplicate policy** — `.duplicates('last' | 'first' | 'error')` on singleton flags controls repeated CLI occurrences. `'error'` throws `ParseError` code `DUPLICATE_FLAG` with `{ flag, count, values }` details; `'first'` keeps the first value while still consuming later value tokens. Counted per logical flag (aliases + negated + parity spellings); env/config precedence is never a duplicate.
441
+ - **`packageRepositoryUrl(pkg, { require: true })`** — narrows the return type to `string`, throwing a `CLIError` (code `INVALID_REPOSITORY`) at the call site when the `repository` field is missing or not a recognisable locator. Removes the `!` assertion for manifests known to carry a valid repository, with the guarantee enforced at runtime rather than assumed.
442
+ - **Flag spelling parity (kebab ↔ camel)** — `--doThis` matches a flag named `do-this` and vice versa, for names and long aliases, on by default. Handler keys, help, completions, and suggestions stay canonical. Automatically disabled per pair when both spellings are declared explicitly; globally via `cli('mycli', { flags: { caseParity: false } })` (new `cli(name, options)` overload) or `RunOptions.flags`.
1277
443
 
1278
444
  ### Fixed
1279
445
 
1280
- - `execute(argv, { flags })` overrides now reach the planner's dispatch arity
1281
- scanning, not just command parsing.
1282
- - Generated meta-schema descriptions render `@defaultValue` tags as a
1283
- `Default: <value>` paragraph instead of silently dropping them.
446
+ - `execute(argv, { flags })` overrides now reach the planner's dispatch arity scanning, not just command parsing.
447
+ - Generated meta-schema descriptions render `@defaultValue` tags as a `Default: <value>` paragraph instead of silently dropping them.
1284
448
 
1285
449
  ## [3.0.0-rc.7] - 2026-07-10
1286
450
 
1287
451
  ### Added
1288
452
 
1289
- - **`.derive()` handlers may omit the return** — a validation-only derive with
1290
- no `return` statement (sync or async) now typechecks; previously `void` /
1291
- `Promise<void>` failed the `Output` constraint and forced an explicit
1292
- `return undefined`.
1293
- - **String constraints** — `flag.string({ nonEmpty, minLength, maxLength, pattern })`
1294
- plus chained `.nonEmpty()` / `.minLength()` / `.maxLength()` / `.pattern()`,
1295
- mirroring the numeric-constraint model. Checked in fixed order
1296
- (nonEmpty → minLength → maxLength → pattern) at both the CLI parse boundary
1297
- (`INVALID_VALUE`) and env/config/prompt resolution (`CONSTRAINT_VIOLATED`),
1298
- and emitted into the exported JSON Schema as `minLength` / `maxLength` /
1299
- `pattern`.
1300
- - **`.separator()` and `.unique()` on array flags** — `.separator(',')` splits
1301
- each CLI occurrence before element coercion, so `--region us,eu --region ap`
1302
- works alongside repetition and errors name the offending element. Env/config
1303
- string values use the same separator (default remains `','`). `.unique()`
1304
- deduplicates the final resolved array (first-seen order) regardless of
1305
- source.
1306
- - **`flag.url()`** — parses into a `URL`, with optional
1307
- `{ protocols: ['https'] }` allowlist. Help shows `<url>`.
1308
- - **`flag.path()`** — path string with opt-in filesystem checks
1309
- (`{ mustExist: true }`, `{ type: 'file' | 'directory' }`) validated after
1310
- resolution through the runtime adapter, so CLI/env/config values are checked
1311
- identically. `RuntimeAdapter` gained a `stat()` primitive (Node/Bun via
1312
- `node:fs/promises`, Deno via `Deno.stat`; test adapters default to "nothing
1313
- exists"), and `RunOptions` / `ResolveOptions` accept a `stat` injection for
1314
- process-free execution — without one, checks are skipped.
1315
- - **`flag.date()`** — strict ISO-8601 → `Date` with optional inclusive
1316
- `min` / `max` bounds. Rejects lenient `Date.parse` inputs (`'0'`,
1317
- `'March 5'`) and calendar-invalid dates (`2026-02-31`).
1318
- - **`flag.duration()`** — `'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`,
1319
- compounds (`'1h30m'`), or bare milliseconds → milliseconds.
1320
- - **`flag.bytes()`** — `'512mb'`, `'1.5gb'`, `'64kb'` or bare bytes → bytes
1321
- (binary units, case-insensitive).
1322
- - **`flag.count()`** — occurrence counter (`-vvv` → `3`, absent → `0`,
1323
- explicit `--verbose=2` supported). Takes no value token, not promptable,
1324
- and joins boolean flags in help (no `<value>` placeholder) and shell
1325
- completions.
1326
- - **`flag.keyValue()`** — repeated `KEY=VALUE` merges into
1327
- `Record<string, string>` (split at the first `=`, later keys win, unset
1328
- resolves to `{}`). Env accepts comma-separated pairs; config accepts a plain
1329
- object. New `'empty-object'` optional fallback joins arrays' `[]` as the
1330
- kinds that resolve to a value when unset.
453
+ - **`.derive()` handlers may omit the return** — a validation-only derive with no `return` statement (sync or async) now typechecks; previously `void` / `Promise<void>` failed the `Output` constraint and forced an explicit `return undefined`.
454
+ - **String constraints** — `flag.string({ nonEmpty, minLength, maxLength, pattern })` plus chained `.nonEmpty()` / `.minLength()` / `.maxLength()` / `.pattern()`, mirroring the numeric-constraint model. Checked in fixed order (nonEmpty → minLength → maxLength → pattern) at both the CLI parse boundary (`INVALID_VALUE`) and env/config/prompt resolution (`CONSTRAINT_VIOLATED`), and emitted into the exported JSON Schema as `minLength` / `maxLength` / `pattern`.
455
+ - **`.separator()` and `.unique()` on array flags** — `.separator(',')` splits each CLI occurrence before element coercion, so `--region us,eu --region ap` works alongside repetition and errors name the offending element. Env/config string values use the same separator (default remains `','`). `.unique()` deduplicates the final resolved array (first-seen order) regardless of source.
456
+ - **`flag.url()`** — parses into a `URL`, with optional `{ protocols: ['https'] }` allowlist. Help shows `<url>`.
457
+ - **`flag.path()`** — path string with opt-in filesystem checks (`{ mustExist: true }`, `{ type: 'file' | 'directory' }`) validated after resolution through the runtime adapter, so CLI/env/config values are checked identically. `RuntimeAdapter` gained a `stat()` primitive (Node/Bun via `node:fs/promises`, Deno via `Deno.stat`; test adapters default to "nothing exists"), and `RunOptions` / `ResolveOptions` accept a `stat` injection for process-free execution — without one, checks are skipped.
458
+ - **`flag.date()`** — strict ISO-8601 → `Date` with optional inclusive `min` / `max` bounds. Rejects lenient `Date.parse` inputs (`'0'`, `'March 5'`) and calendar-invalid dates (`2026-02-31`).
459
+ - **`flag.duration()`** — `'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`, compounds (`'1h30m'`), or bare milliseconds → milliseconds.
460
+ - **`flag.bytes()`** — `'512mb'`, `'1.5gb'`, `'64kb'` or bare bytes → bytes (binary units, case-insensitive).
461
+ - **`flag.count()`** — occurrence counter (`-vvv` → `3`, absent → `0`, explicit `--verbose=2` supported). Takes no value token, not promptable, and joins boolean flags in help (no `<value>` placeholder) and shell completions.
462
+ - **`flag.keyValue()`** — repeated `KEY=VALUE` merges into `Record<string, string>` (split at the first `=`, later keys win, unset resolves to `{}`). Env accepts comma-separated pairs; config accepts a plain object. New `'empty-object'` optional fallback joins arrays' `[]` as the kinds that resolve to a value when unset.
1331
463
 
1332
464
  ## [3.0.0-rc.6] - 2026-07-09
1333
465
 
1334
466
  ### Added
1335
467
 
1336
- - **Runtime terminal sizing hooks** — `RuntimeAdapter` now exposes
1337
- `getTerminalSize()` and `onTerminalResize()`. Node/Bun read
1338
- `process.stdout.getWindowSize()` (falling back to `columns` / `rows`) and
1339
- subscribe to stdout `resize`; Deno uses native `Deno.consoleSize()` and
1340
- `SIGWINCH` on non-Windows platforms.
468
+ - **Runtime terminal sizing hooks** — `RuntimeAdapter` now exposes `getTerminalSize()` and `onTerminalResize()`. Node/Bun read `process.stdout.getWindowSize()` (falling back to `columns` / `rows`) and subscribe to stdout `resize`; Deno uses native `Deno.consoleSize()` and `SIGWINCH` on non-Windows platforms.
1341
469
 
1342
470
  ### Changed
1343
471
 
1344
- - **Help output now fits the live terminal in `.run()`** — root and command help
1345
- use runtime terminal columns when no explicit `.help({ width })` or runtime
1346
- `help.width` is provided. Non-TTY or unavailable sizes still fall back to 80,
1347
- and `.execute()` remains deterministic for tests.
472
+ - **Help output now fits the live terminal in `.run()`** — root and command help use runtime terminal columns when no explicit `.help({ width })` or runtime `help.width` is provided. Non-TTY or unavailable sizes still fall back to 80, and `.execute()` remains deterministic for tests.
1348
473
 
1349
474
  ## [3.0.0-rc.5] - 2026-07-08
1350
475
 
1351
476
  ### Removed
1352
477
 
1353
- - **`createBunAdapter` export** (from `@kjanat/dreamcli/runtime`). Bun exposes a
1354
- Node-compatible `process`, so the Bun adapter had been a pure passthrough to
1355
- the Node adapter since the runtime version hard-fail was dropped — it blessed
1356
- a runtime rather than abstracting distinct I/O. Auto-detection now maps Bun to
1357
- the Node adapter directly and `src/runtime/bun.ts` is gone. Runtime detection
1358
- is unchanged: `detectRuntime()` still reports `'bun'` and `RUNTIMES` still
1359
- lists it. Callers that selected the Bun adapter explicitly should use
1360
- `createNodeAdapter` (identical behavior) or rely on `createAdapter()`
1361
- auto-detection (#51).
478
+ - **`createBunAdapter` export** (from `@kjanat/dreamcli/runtime`). Bun exposes a Node-compatible `process`, so the Bun adapter had been a pure passthrough to the Node adapter since the runtime version hard-fail was dropped — it blessed a runtime rather than abstracting distinct I/O. Auto-detection now maps Bun to the Node adapter directly and `src/runtime/bun.ts` is gone. Runtime detection is unchanged: `detectRuntime()` still reports `'bun'` and `RUNTIMES` still lists it. Callers that selected the Bun adapter explicitly should use `createNodeAdapter` (identical behavior) or rely on `createAdapter()` auto-detection (#51).
1362
479
 
1363
480
  ## [3.0.0-rc.4] - 2026-07-06
1364
481
 
1365
482
  ### Added
1366
483
 
1367
- - **`.default(cmd, { route: true })`** — expose a default command under its own
1368
- name as a routable top-level command, in addition to the bare/flags-only root
1369
- surface. `mycli` and `mycli <name>` then run the same command object, and it
1370
- is listed in the root `Commands:` section (tagged `(default)`) beside its
1371
- siblings. Lets CLIs keep both a short root shorthand and an explicit,
1372
- documented named command without duplicating the builder (#55). Opt-in only
1373
- — the surface-only default remains the default behavior. With `route: true`
1374
- the name wins over positional interpretation, so a positional value equal to
1375
- the command's own name must be passed after `--`.
484
+ - **`.default(cmd, { route: true })`** — expose a default command under its own name as a routable top-level command, in addition to the bare/flags-only root surface. `mycli` and `mycli <name>` then run the same command object, and it is listed in the root `Commands:` section (tagged `(default)`) beside its siblings. Lets CLIs keep both a short root shorthand and an explicit, documented named command without duplicating the builder (#55). Opt-in only — the surface-only default remains the default behavior. With `route: true` the name wins over positional interpretation, so a positional value equal to the command's own name must be passed after `--`.
1376
485
 
1377
486
  ## [3.0.0-rc.3] - 2026-07-06
1378
487
 
1379
488
  ### Added
1380
489
 
1381
- - **`@kjanat/dreamcli/version` subpath** — exposes the framework's own build
1382
- identity as `DREAMCLI_VERSION` and `DREAMCLI_REVISION` (git short SHA) for
1383
- diagnostics and bug reports. Deliberately a subpath rather than root exports
1384
- so the constants stay out of root-import IDE completions; both report
1385
- `'dev'` when running unbundled source.
490
+ - **`@kjanat/dreamcli/version` subpath** — exposes the framework's own build identity as `DREAMCLI_VERSION` and `DREAMCLI_REVISION` (git short SHA) for diagnostics and bug reports. Deliberately a subpath rather than root exports so the constants stay out of root-import IDE completions; both report `'dev'` when running unbundled source.
1386
491
 
1387
492
  ## [3.0.0-rc.2] - 2026-07-06
1388
493
 
1389
494
  ### Added
1390
495
 
1391
- - **`out.color` — context-aware ANSI colors** — every handler's `out` now carries
1392
- a color palette powered by [`ansispeck`](https://github.com/kjanat/ansispeck).
1393
- Colors auto-enable only when stdout is a TTY, JSON mode is off, and the
1394
- environment supports color (`NO_COLOR`, `FORCE_COLOR`, `--no-color`, `--color`,
1395
- `CI` respected); otherwise every formatter is an identity function, so handlers
1396
- can write `out.log(out.color.green('✔ done'))` unconditionally.
1397
- `createOutput({ color })` forces the palette on/off (useful for asserting
1398
- colored output in tests), and the `Colors` type is re-exported from the root
1399
- entrypoint. First runtime dependency — kept external in `dist` (~1 kB gzipped
1400
- install).
496
+ - **`out.color` — context-aware ANSI colors** — every handler's `out` now carries a color palette powered by [`ansispeck`](https://github.com/kjanat/ansispeck). Colors auto-enable only when stdout is a TTY, JSON mode is off, and the environment supports color (`NO_COLOR`, `FORCE_COLOR`, `--no-color`, `--color`, `CI` respected); otherwise every formatter is an identity function, so handlers can write `out.log(out.color.green('✔ done'))` unconditionally. `createOutput({ color })` forces the palette on/off (useful for asserting colored output in tests), and the `Colors` type is re-exported from the root entrypoint. First runtime dependency — kept external in `dist` (~1 kB gzipped install).
1401
497
 
1402
498
  ### Changed
1403
499
 
1404
- - **npm package now resolves built `dist` on every runtime** — the `bun`/`deno`
1405
- → `src/*.ts` export conditions are gone and `src` is no longer published to
1406
- npm (JSR still ships source). Bun and Deno consumers previously loaded raw
1407
- source where build-time defines never ran, so `version` reported `'dev'`;
1408
- they now get the same tested output as Node, with the real version. The
1409
- export map is generated by tsdown at build time instead of hand-maintained.
500
+ - **npm package now resolves built `dist` on every runtime** — the `bun`/`deno` → `src/*.ts` export conditions are gone and `src` is no longer published to npm (JSR still ships source). Bun and Deno consumers previously loaded raw source where build-time defines never ran, so `version` reported `'dev'`; they now get the same tested output as Node, with the real version. The export map is generated by tsdown at build time instead of hand-maintained.
1410
501
 
1411
502
  ## [3.0.0-rc.1] - 2026-07-02
1412
503
 
1413
504
  ### Added
1414
505
 
1415
- - **`.completions({ as: 'flag' })`** — expose shell completion as an eager
1416
- `--completions <shell>` flag on the CLI root instead of a `completions`
1417
- subcommand. The planner intercepts the flag before dispatch, prints the script,
1418
- and exits; root help advertises `--completions <bash|zsh|fish|powershell>` in its
1419
- `Flags:` section. `.completions()` still defaults to `{ as: 'command' }`. Because
1420
- the eager flag is intercepted before dispatch, the `--completions` name is
1421
- reserved in flag mode — declaring a command/default flag of that name throws at
1422
- build time.
1423
- - **Shell auto-detection** — `--completions` with no value (flag form) resolves the
1424
- target shell from the environment: `$SHELL` (parsed as an interpreter path) wins
1425
- when it names a supported shell, otherwise the presence of `$PSModulePath` selects
1426
- PowerShell — the reliable signal for `pwsh`, which never sets `$SHELL`.
1427
- - **`detectShell(env)` / `normalizeShell(raw)`** — exported helpers behind the
1428
- detection above; `normalizeShell` accepts bare names, `$SHELL` paths, and the
1429
- `pwsh`/`powershell` pair.
1430
- - **`.help(config)` builder + extended `HelpOptions`** — configure root-help
1431
- rendering: `inlineDefault`, `showDefaultInCommands`, and `footer` (plus the
1432
- existing `width` / `hyperlinks`). Builder config is merged under runtime
1433
- `options.help` (runtime wins).
1434
- - **Numeric constraints for number flags and args** — `flag.number()` and
1435
- `arg.number()` now accept `{ min?, max?, int?, finite? }` (bounds inclusive),
1436
- and the same constraints compose via chained `.int()` / `.min(n)` / `.max(n)` /
1437
- `.finite(allow?)` methods (a later call overrides an earlier value, including
1438
- one set in the options object). The chained methods are compile-time guarded
1439
- to number-kind builders only. Constraints are enforced identically across the
1440
- parse path and the env/config/prompt resolution path (order: finite → int →
1441
- min → max): parse-time (CLI) violations throw `INVALID_VALUE`, while
1442
- env/config/prompt coercion reports `CONSTRAINT_VIOLATED` (both exit code `2`).
1443
- They are also surfaced in the exported JSON Schema as `minimum` / `maximum` and
1444
- `type: "integer"` when `int` is set. `min` / `max` must be finite — a
1445
- non-finite bound (`Infinity` / `-Infinity` / `NaN`) throws at construction. The
1446
- resolved TypeScript value type stays `number`.
1447
- - **Prompt-level defaults for `confirm` and `input` prompts** — `confirm`
1448
- prompts accept `default?: boolean` (drives the `(Y/n)` vs `(y/N)` hint and the
1449
- empty-line result, so a confirm can default to **No**), and `input` prompts
1450
- accept `default?: string` (shown in the hint as `(default: <value>)` and used
1451
- when the user presses Enter, skipping `validate`). Precedence among defaults is
1452
- prompt-level `default` > flag `.default()`. Unset `confirm` default stays
1453
- backward compatible (`true`).
506
+ - **`.completions({ as: 'flag' })`**\
507
+ Expose shell completion as an eager `--completions <shell>` flag on the CLI root instead of a `completions` subcommand. The planner intercepts the flag before dispatch, prints the script, and exits; root help advertises `--completions <bash|zsh|fish|powershell>` in its `Flags:` section. `.completions()` still defaults to `{ as: 'command' }`. Because the eager flag is intercepted before dispatch, the `--completions` name is reserved in flag mode — declaring a command/default flag of that name throws at build time.
508
+ - **Shell auto-detection** — `--completions` with no value (flag form) resolves the target shell from the environment: `$SHELL` (parsed as an interpreter path) wins when it names a supported shell, otherwise the presence of `$PSModulePath` selects PowerShell — the reliable signal for `pwsh`, which never sets `$SHELL`.
509
+ - **`detectShell(env)` / `normalizeShell(raw)`** — exported helpers behind the detection above; `normalizeShell` accepts bare names, `$SHELL` paths, and the `pwsh`/`powershell` pair.
510
+ - **`.help(config)` builder + extended `HelpOptions`** — configure root-help rendering: `inlineDefault`, `showDefaultInCommands`, and `footer` (plus the existing `width` / `hyperlinks`). Builder config is merged under runtime `options.help` (runtime wins).
511
+ - **Numeric constraints for number flags and args** — `flag.number()` and `arg.number()` now accept `{ min?, max?, int?, finite? }` (bounds inclusive), and the same constraints compose via chained `.int()` / `.min(n)` / `.max(n)` / `.finite(allow?)` methods (a later call overrides an earlier value, including one set in the options object). The chained methods are compile-time guarded to number-kind builders only. Constraints are enforced identically across the parse path and the env/config/prompt resolution path (order: finite → int → min → max): parse-time (CLI) violations throw `INVALID_VALUE`, while env/config/prompt coercion reports `CONSTRAINT_VIOLATED` (both exit code `2`). They are also surfaced in the exported JSON Schema as `minimum` / `maximum` and `type: "integer"` when `int` is set. `min` / `max` must be finite — a non-finite bound (`Infinity` / `-Infinity` / `NaN`) throws at construction. The resolved TypeScript value type stays `number`.
512
+ - **Prompt-level defaults for `confirm` and `input` prompts** — `confirm` prompts accept `default?: boolean` (drives the `(Y/n)` vs `(y/N)` hint and the empty-line result, so a confirm can default to **No**), and `input` prompts accept `default?: string` (shown in the hint as `(default: <value>)` and used when the user presses Enter, skipping `validate`). Precedence among defaults is prompt-level `default` > flag `.default()`. Unset `confirm` default stays backward compatible (`true`).
1454
513
 
1455
514
  ### Changed
1456
515
 
1457
- - **BREAKING — the default command is now the root _surface_, not a named
1458
- subcommand.** `.default(cmd)` registers the command only as the default; it is no
1459
- longer added to `schema.commands`. Consequences:
1460
- - It can no longer be invoked by its own name (`mycli mycmd` does not route to it;
1461
- the token is treated as input to the default command).
1462
- - It is omitted from the root `Commands:` list by default (re-enable with
1463
- `.help({ showDefaultInCommands: true })`).
1464
- - Root `--help` renders the default command's `Arguments:`/`Flags:` inline even
1465
- when sibling commands exist (previously only when it was the sole command), and a
1466
- sole default with no subcommands shows its own usage line directly instead of a
1467
- `[command]` placeholder.
1468
- - **`finite` defaults to `true` (behavior change)** — `flag.number()` /
1469
- `arg.number()` now **reject `Infinity` and `-Infinity`**, which previously
1470
- passed straight through to handlers (`Number("Infinity")` is not `NaN`). Pass
1471
- `{ finite: false }` (or `.finite(false)`) to opt back into accepting non-finite
1472
- values. `NaN` continues to be rejected as before.
1473
- - **BREAKING — the runtime no longer hard-fails the host CLI on its version.**
1474
- Adapter construction previously threw (a bare, uncaught `Error`) when the
1475
- detected Node/Bun/Deno version was below DreamCLI's declared minimum, crashing
1476
- the consumer's CLI — including on `--help`. That check is removed: as a
1477
- dependency the consumer's package manager already enforces the `engines` range
1478
- at install time (and more softly), and when DreamCLI is bundled/inlined the
1479
- consumer — not us — owns their CLI's supported-runtime policy. `SUPPORTED_RUNTIMES`
1480
- and the generated `engines` minimums are unchanged and remain the source of
1481
- truth for docs and packaging.
516
+ - **BREAKING — the default command is now the root _surface_, not a named subcommand.** `.default(cmd)` registers the command only as the default; it is no longer added to `schema.commands`. Consequences:
517
+ - It can no longer be invoked by its own name (`mycli mycmd` does not route to it; the token is treated as input to the default command).
518
+ - It is omitted from the root `Commands:` list by default (re-enable with `.help({ showDefaultInCommands: true })`).
519
+ - Root `--help` renders the default command's `Arguments:`/`Flags:` inline even when sibling commands exist (previously only when it was the sole command), and a sole default with no subcommands shows its own usage line directly instead of a `[command]` placeholder.
520
+ - **`finite` defaults to `true` (behavior change)** — `flag.number()` / `arg.number()` now **reject `Infinity` and `-Infinity`**, which previously passed straight through to handlers (`Number("Infinity")` is not `NaN`). Pass `{ finite: false }` (or `.finite(false)`) to opt back into accepting non-finite values. `NaN` continues to be rejected as before.
521
+ - **BREAKING — the runtime no longer hard-fails the host CLI on its version.** Adapter construction previously threw (a bare, uncaught `Error`) when the detected Node/Bun/Deno version was below DreamCLI's declared minimum, crashing the consumer's CLI — including on `--help`. That check is removed: as a dependency the consumer's package manager already enforces the `engines` range at install time (and more softly), and when DreamCLI is bundled/inlined the consumer — not us — owns their CLI's supported-runtime policy. `SUPPORTED_RUNTIMES` and the generated `engines` minimums are unchanged and remain the source of truth for docs and packaging.
1482
522
 
1483
523
  ### Fixed
1484
524
 
1485
- - **Empty `input`-prompt answer no longer clobbers a flag's `.default()`** — a
1486
- flag declared with both `.default(...)` and an `input` prompt previously
1487
- resolved to `""` when the user submitted an empty line, because empty input was
1488
- treated as a real answer that short-circuited the default fallback. An empty or
1489
- blank `input` answer with no prompt-level `default` is now treated as "no
1490
- answer", so resolution falls through to the flag's `.default()` (or, for a
1491
- required flag, the standard missing-flag error).
525
+ - **Empty `input`-prompt answer no longer clobbers a flag's `.default()`** — a flag declared with both `.default(...)` and an `input` prompt previously resolved to `""` when the user submitted an empty line, because empty input was treated as a real answer that short-circuited the default fallback. An empty or blank `input` answer with no prompt-level `default` is now treated as "no answer", so resolution falls through to the flag's `.default()` (or, for a required flag, the standard missing-flag error).
1492
526
 
1493
527
  ### Fixed
1494
528
 
1495
- - **Root `--help` now matches consistently with `--version`** (#29) — previously
1496
- `--help` / `-h` were intercepted at the root only when they were the very first
1497
- token, while `--version` / `-V` matched anywhere before `--`. A help flag
1498
- preceded only by flags (e.g. `mycli --verbose --help`) now shows root help,
1499
- mirroring `mycli --verbose --version`. A help flag that follows a subcommand
1500
- token still scopes to that subcommand (`mycli deploy --help` → `deploy` help);
1501
- `--version` remains a global, position-independent flag by design (there is no
1502
- per-command version). The bare `help` token now triggers root help from the same
1503
- position as `--help`, and the `--` end-of-options separator is respected for both.
1504
- - **Generated `--help` now advertises the active built-in global flags** (#32) — root
1505
- help renders a `Global options:` block listing `--help, -h` and `--json` (always),
1506
- `--version, -V` (when a version is set), and `--config <path>` (when `.config()`
1507
- enabled config discovery). Previously these framework-provided flags were invisible
1508
- in help even though they worked. `--completions` is unchanged (still advertised via
1509
- the inline surface when active).
1510
- - **Root usage no longer prints the default command's name** — the merged/sole-default
1511
- usage line rendered `Usage: <bin> <default-name> …`, teaching an invocation that does
1512
- not route (`.default()` is not a named command, so the token is consumed as the
1513
- default's first positional). It now renders under the bin name only
1514
- (`Usage: <bin> [flags] <args>`).
1515
- - **`inlineDefault: false` no longer hides a sole default command's interface** — when
1516
- the default command is the only surface (no visible subcommands and no eager
1517
- `--completions` flag), root help would collapse to a bare `Usage: <bin> [options]`
1518
- with no discoverable args/flags. The default is now always rendered inline in that
1519
- case, since suppressing it leaves no other path to its interface.
529
+ - **Root `--help` now matches consistently with `--version`** (#29) — previously `--help` / `-h` were intercepted at the root only when they were the very first token, while `--version` / `-V` matched anywhere before `--`. A help flag preceded only by flags (e.g. `mycli --verbose --help`) now shows root help, mirroring `mycli --verbose --version`. A help flag that follows a subcommand token still scopes to that subcommand (`mycli deploy --help` → `deploy` help); `--version` remains a global, position-independent flag by design (there is no per-command version). The bare `help` token now triggers root help from the same position as `--help`, and the `--` end-of-options separator is respected for both.
530
+ - **Generated `--help` now advertises the active built-in global flags** (#32) — root help renders a `Global options:` block listing `--help, -h` and `--json` (always), `--version, -V` (when a version is set), and `--config <path>` (when `.config()` enabled config discovery). Previously these framework-provided flags were invisible in help even though they worked. `--completions` is unchanged (still advertised via the inline surface when active).
531
+ - **Root usage no longer prints the default command's name** — the merged/sole-default usage line rendered `Usage: <bin> <default-name> …`, teaching an invocation that does not route (`.default()` is not a named command, so the token is consumed as the default's first positional). It now renders under the bin name only (`Usage: <bin> [flags] <args>`).
532
+ - **`inlineDefault: false` no longer hides a sole default command's interface** — when the default command is the only surface (no visible subcommands and no eager `--completions` flag), root help would collapse to a bare `Usage: <bin> [options]` with no discoverable args/flags. The default is now always rendered inline in that case, since suppressing it leaves no other path to its interface.
1520
533
 
1521
534
  ### Fixed
1522
535
 
1523
- - **`runCommand()` now honors a CLI-level `--json` passed in `argv`** — the testkit
1524
- gained the same root-flag layer as the real CLI: a `--json` before the `--`
1525
- separator enables JSON mode and is stripped before parsing, instead of failing
1526
- with `Unknown flag --json` (exit 2). A literal `--json` after `--` still reaches
1527
- the command unchanged. The existing `{ jsonMode: true }` option keeps working —
1528
- either source enables JSON mode. Copying a real `mycli --json …` invocation into a
1529
- test now works verbatim.
1530
- - **`createTestPrompter()` now runs an `input` prompt's `validate`** — a queued
1531
- string answer to an `input` prompt is validated exactly as the terminal prompter
1532
- does; an answer that fails validation is rejected as a cancellation rather than
1533
- injected verbatim as the resolved value, so prompt validation is integration-testable
1534
- through `runCommand(cmd, argv, { answers })`. Non-string answers stay verbatim so
1535
- downstream coercion paths remain testable.
536
+ - **`runCommand()` now honors a CLI-level `--json` passed in `argv`** — the testkit gained the same root-flag layer as the real CLI: a `--json` before the `--` separator enables JSON mode and is stripped before parsing, instead of failing with `Unknown flag --json` (exit 2). A literal `--json` after `--` still reaches the command unchanged. The existing `{ jsonMode: true }` option keeps working — either source enables JSON mode. Copying a real `mycli --json …` invocation into a test now works verbatim.
537
+ - **`createTestPrompter()` now runs an `input` prompt's `validate`** — a queued string answer to an `input` prompt is validated exactly as the terminal prompter does; an answer that fails validation is rejected as a cancellation rather than injected verbatim as the resolved value, so prompt validation is integration-testable through `runCommand(cmd, argv, { answers })`. Non-string answers stay verbatim so downstream coercion paths remain testable.
1536
538
 
1537
539
  ## [2.5.0] - 2026-06-28
1538
540
 
1539
541
  ### Added
1540
542
 
1541
- - **`.manifest()` — runtime-agnostic manifest discovery** — discover CLI metadata
1542
- from any manifest file, not just `package.json`. Pass `files` to choose candidate
1543
- filenames in priority order (e.g. `['deno.json', 'jsr.json']`); discovery walks up
1544
- from `cwd` (or `from`) and the nearest manifest directory wins. Files are parsed as
1545
- JSON with a JSONC fallback, so `package.json`, `deno.json`, `jsr.json`, and
1546
- `deno.jsonc` all work — including manifests with `//` / block comments or trailing
1547
- commas (a dependency-free, string-aware strip that leaves `//` inside string values
1548
- such as URLs untouched).
1549
- - **`discoverManifest()`** — the generalized discovery helper behind `.manifest()`,
1550
- accepting `{ startDir, files }`.
1551
- - **Optional scope retention in name inference** — `inferName` now accepts
1552
- `{ scope: 'keep' | 'strip' }` (and `inferCliName(pkg, { stripScope })`) so a scoped
1553
- `name` like `@scope/mycli` can be kept verbatim instead of always stripping to
1554
- `mycli`. Relevant for `deno.json` / `jsr.json`, which have no `bin` field.
1555
- - **`.denoJson()`** — deprecated convenience preset for
1556
- `.manifest({ files: ['deno.json', 'deno.jsonc', 'jsr.json'] })` (see Deprecated below).
543
+ - **`.manifest()` — runtime-agnostic manifest discovery** — discover CLI metadata from any manifest file, not just `package.json`. Pass `files` to choose candidate filenames in priority order (e.g. `['deno.json', 'jsr.json']`); discovery walks up from `cwd` (or `from`) and the nearest manifest directory wins. Files are parsed as JSON with a JSONC fallback, so `package.json`, `deno.json`, `jsr.json`, and `deno.jsonc` all work — including manifests with `//` / block comments or trailing commas (a dependency-free, string-aware strip that leaves `//` inside string values such as URLs untouched).
544
+ - **`discoverManifest()`** — the generalized discovery helper behind `.manifest()`, accepting `{ startDir, files }`.
545
+ - **Optional scope retention in name inference** — `inferName` now accepts `{ scope: 'keep' | 'strip' }` (and `inferCliName(pkg, { stripScope })`) so a scoped `name` like `@scope/mycli` can be kept verbatim instead of always stripping to `mycli`. Relevant for `deno.json` / `jsr.json`, which have no `bin` field.
546
+ - **`.denoJson()`** — deprecated convenience preset for `.manifest({ files: ['deno.json', 'deno.jsonc', 'jsr.json'] })` (see Deprecated below).
1557
547
 
1558
548
  ### Changed
1559
549
 
1560
- - **Manifest discovery now requires recognized metadata to count as a hit** — a
1561
- parseable but metadata-less manifest (`{}`, or one carrying only non-metadata
1562
- fields such as `dependencies` / `scripts` / `type`, or a config-only `deno.json`
1563
- with just `tasks` / `imports`) is no longer treated as a match. Discovery now
1564
- walks up to parent directories and tries the remaining candidate files instead
1565
- of halting. This also changes the deprecated `discoverPackageJson()` /
1566
- `.packageJson()`: where a metadata-less `package.json` previously halted the
1567
- walk-up and resolved to `{}`, the walk-up now continues, so an ancestor's
1568
- version can surface (relevant in monorepos). Pass pre-loaded `data` or an
1569
- explicit `from` / `startDir` to pin discovery to one directory.
550
+ - **Manifest discovery now requires recognized metadata to count as a hit** — a parseable but metadata-less manifest (`{}`, or one carrying only non-metadata fields such as `dependencies` / `scripts` / `type`, or a config-only `deno.json` with just `tasks` / `imports`) is no longer treated as a match. Discovery now walks up to parent directories and tries the remaining candidate files instead of halting. This also changes the deprecated `discoverPackageJson()` / `.packageJson()`: where a metadata-less `package.json` previously halted the walk-up and resolved to `{}`, the walk-up now continues, so an ancestor's version can surface (relevant in monorepos). Pass pre-loaded `data` or an explicit `from` / `startDir` to pin discovery to one directory.
1570
551
 
1571
552
  ### Deprecated
1572
553
 
1573
- - **`.packageJson()`, `.denoJson()`, and `discoverPackageJson()`** — superseded by
1574
- `.manifest()` / `discoverManifest()`, whose defaults (`['package.json']`) match the
1575
- old behavior. All still work, delegating to the generalized path.
554
+ - **`.packageJson()`, `.denoJson()`, and `discoverPackageJson()`** — superseded by `.manifest()` / `discoverManifest()`, whose defaults (`['package.json']`) match the old behavior. All still work, delegating to the generalized path.
1576
555
 
1577
556
  ## [2.4.1] - 2026-06-27
1578
557
 
1579
558
  ### Fixed
1580
559
 
1581
- - **Destructuring `out` and activity handles** — `Out` methods and the spinner/progress activity
1582
- handle methods are now bound to their instance, so pulling them off via destructuring (e.g.
1583
- `const { done } = handle`) no longer breaks `this`-dependent behaviour and cleanup
1584
- (https://github.com/kjanat/dreamcli/pull/40).
560
+ - **Destructuring `out` and activity handles** — `Out` methods and the spinner/progress activity handle methods are now bound to their instance, so pulling them off via destructuring (e.g. `const { done } = handle`) no longer breaks `this`-dependent behaviour and cleanup (https://github.com/kjanat/dreamcli/pull/40).
1585
561
 
1586
562
  ## [2.4.0] - 2026-06-23
1587
563
 
1588
564
  ### Added
1589
565
 
1590
- - **`out.setExitCode(code)` for normal-output status exits** — command handlers can now request a
1591
- process exit code without throwing or emitting error-shaped output, covering status/check CLIs that
1592
- should print their normal report while still signalling degraded state to scripts
1593
- (https://github.com/kjanat/dreamcli/issues/27).
566
+ - **`out.setExitCode(code)` for normal-output status exits** — command handlers can now request a process exit code without throwing or emitting error-shaped output, covering status/check CLIs that should print their normal report while still signalling degraded state to scripts (https://github.com/kjanat/dreamcli/issues/27).
1594
567
 
1595
568
  ### Fixed
1596
569
 
1597
- - **Unknown root commands under no-arg defaults now report `UNKNOWN_COMMAND`** — when a CLI has a
1598
- `.default()` command with no positional args, an unknown root token no longer falls through to the
1599
- default parser as an unexpected positional. Defaults that declare positional args still receive
1600
- those root tokens as before (https://github.com/kjanat/dreamcli/issues/26).
570
+ - **Unknown root commands under no-arg defaults now report `UNKNOWN_COMMAND`** — when a CLI has a `.default()` command with no positional args, an unknown root token no longer falls through to the default parser as an unexpected positional. Defaults that declare positional args still receive those root tokens as before (https://github.com/kjanat/dreamcli/issues/26).
1601
571
 
1602
572
  ### Security
1603
573
 
1604
- - **Hardened trailing-separator trimming against polynomial ReDoS** — the home/config path
1605
- resolution, `package.json` repository-URL normalization, and runtime-binary `basename` helpers
1606
- previously stripped trailing slashes with backtracking regexes (`/[\\/]+$/`, `/\/+$/`) that CodeQL
1607
- flagged as polynomial regular expressions (`js/polynomial-redos`). They now route through a shared
1608
- linear-time `stripTrailing` scan, so adversarial slash-heavy input can no longer trigger quadratic
1609
- matching. No behavior change for valid inputs.
574
+ - **Hardened trailing-separator trimming against polynomial ReDoS** — the home/config path resolution, `package.json` repository-URL normalization, and runtime-binary `basename` helpers previously stripped trailing slashes with backtracking regexes (`/[\\/]+$/`, `/\/+$/`) that CodeQL flagged as polynomial regular expressions (`js/polynomial-redos`). They now route through a shared linear-time `stripTrailing` scan, so adversarial slash-heavy input can no longer trigger quadratic matching. No behavior change for valid inputs.
1610
575
 
1611
576
  ## [2.3.0] - 2026-06-20
1612
577
 
1613
578
  ### Fixed
1614
579
 
1615
- - **Command dispatch now respects flag value-arity** — a space-separated value-flag value (e.g.
1616
- `--source anthropic`) is no longer mistaken for a command name when it collides with a registered
1617
- command, so the default-command fallback runs as intended
1618
- (https://github.com/kjanat/dreamcli/issues/25). The command-name scan now skips the token a
1619
- space-separated value-flag consumes (mirroring the parser's own value-consumption rules); the
1620
- inline `--source=anthropic` form already worked, and both forms are now consistent.
1621
- - **Root `--version`/`--json` interception now respects the `--` end-of-options separator**
1622
- (https://github.com/kjanat/dreamcli/issues/28). A `--version` or `--json` token after `--` is
1623
- treated as a literal positional instead of triggering version output or JSON mode.
580
+ - **Command dispatch now respects flag value-arity** — a space-separated value-flag value (e.g. `--source anthropic`) is no longer mistaken for a command name when it collides with a registered command, so the default-command fallback runs as intended (https://github.com/kjanat/dreamcli/issues/25). The command-name scan now skips the token a space-separated value-flag consumes (mirroring the parser's own value-consumption rules); the inline `--source=anthropic` form already worked, and both forms are now consistent.
581
+ - **Root `--version`/`--json` interception now respects the `--` end-of-options separator** (https://github.com/kjanat/dreamcli/issues/28). A `--version` or `--json` token after `--` is treated as a literal positional instead of triggering version output or JSON mode.
1624
582
 
1625
583
  ## [2.2.1] - 2026-06-10
1626
584
 
1627
585
  ### Added
1628
586
 
1629
- - **`.links()` — OSC 8 hyperlinks in the root-help header** — the program name and version on the
1630
- first line of root `--help` output can now carry
1631
- [OSC 8 hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) in
1632
- supporting terminals ([#20](https://github.com/kjanat/dreamcli/issues/20)). Pass explicit URLs
1633
- (`.links({ name, version })`) or call `.links()` with no arguments to derive them from
1634
- `package.json` metadata when `.packageJson()` is active: the name links to the normalized
1635
- `repository` URL (falling back to `homepage`), and the version links to the forge release tag
1636
- (`{repo}/releases/tag/v{version}` on GitHub, `{repo}/-/releases/v{version}` on GitLab). Escapes
1637
- are emitted only when stdout is a TTY (overridable via the new `help.hyperlinks` option) and only
1638
- on the header line — usage lines, the `--help` hint, the commands table, `--version` output, and
1639
- completion scripts stay plain.
1640
- - **ANSI/OSC-aware help width helpers** — help padding and wrapping now measure _visible_ width:
1641
- the shared `padEnd()`/`wrapText()` helpers strip ANSI CSI (colors) and OSC (hyperlink) escape
1642
- sequences before counting columns, so escape-bearing text no longer mangles `--help` alignment.
1643
- New public exports `osc8(url, text)` (wrap text in an OSC 8 hyperlink) and `visibleWidth(text)`
1644
- (escape-aware width measurement) support custom help rendering.
1645
- - **`packageRepositoryUrl(pkg)`** — new public helper that normalizes a package's `repository`
1646
- field to a browsable `https://` URL, handling the locator formats npm accepts (`{ type, url }`
1647
- object form, `git+`/`.git` affixes, scp-style `git@host:u/r.git`, and the
1648
- `github:`/`gitlab:`/`bitbucket:`/bare `u/r` shorthands). `PackageJsonData` now also parses the
1649
- `homepage` and `repository` fields.
587
+ - **`.links()` — OSC 8 hyperlinks in the root-help header** — the program name and version on the first line of root `--help` output can now carry [OSC 8 hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) in supporting terminals (https://github.com/kjanat/dreamcli/issues/20). Pass explicit URLs (`.links({ name, version })`) or call `.links()` with no arguments to derive them from `package.json` metadata when `.packageJson()` is active: the name links to the normalized `repository` URL (falling back to `homepage`), and the version links to the forge release tag (`{repo}/releases/tag/v{version}` on GitHub, `{repo}/-/releases/v{version}` on GitLab). Escapes are emitted only when stdout is a TTY (overridable via the new `help.hyperlinks` option) and only on the header line — usage lines, the `--help` hint, the commands table, `--version` output, and completion scripts stay plain.
588
+ - **ANSI/OSC-aware help width helpers** — help padding and wrapping now measure _visible_ width: the shared `padEnd()`/`wrapText()` helpers strip ANSI CSI (colors) and OSC (hyperlink) escape sequences before counting columns, so escape-bearing text no longer mangles `--help` alignment. New public exports `osc8(url, text)` (wrap text in an OSC 8 hyperlink) and `visibleWidth(text)` (escape-aware width measurement) support custom help rendering.
589
+ - **`packageRepositoryUrl(pkg)`** — new public helper that normalizes a package's `repository` field to a browsable `https://` URL, handling the locator formats npm accepts (`{ type, url }` object form, `git+`/`.git` affixes, scp-style `git@host:u/r.git`, and the `github:`/`gitlab:`/`bitbucket:`/bare `u/r` shorthands). `PackageJsonData` now also parses the `homepage` and `repository` fields.
1650
590
 
1651
591
  ## [2.2.0] - 2026-06-09
1652
592
 
1653
593
  ### Added
1654
594
 
1655
- - **`.packageJson(data)` — pre-loaded metadata** — `CLIBuilder.packageJson()` now accepts an
1656
- already-imported `package.json` object (e.g. `import pkg from './package.json' with { type: 'json' }`),
1657
- skipping filesystem discovery entirely. The data is detected via field shape (`name`/`version`/
1658
- `description`/`bin`), and its `version`/`description` are merged into the CLI schema at builder time
1659
- so the data form works in **both** `.run()` and `.execute()` (the filesystem-free path that
1660
- previously couldn't consume `.packageJson()` at all). Explicit `.version()`/`.description()` still
1661
- win; an empty `{}` or a settings-shaped object falls through to the settings overload, so this is a
1662
- non-breaking addition.
1663
- - **`.packageJson({ from })` — anchored discovery** — discovery can now be anchored to an explicit
1664
- location instead of the runtime cwd. Pass `{ from: import.meta.url }` (also accepts path strings,
1665
- `file:` URL strings, or `URL` instances) so installable CLIs (`npm i -g`, `bunx`, `npx`) report
1666
- their OWN version from any working directory. `discoverPackageJson(adapter, startDir?)` gained a
1667
- matching optional anchor parameter.
595
+ - **`.packageJson(data)` — pre-loaded metadata** — `CLIBuilder.packageJson()` now accepts an already-imported `package.json` object (e.g. `import pkg from './package.json' with { type: 'json' }`), skipping filesystem discovery entirely. The data is detected via field shape (`name`/`version`/ `description`/`bin`), and its `version`/`description` are merged into the CLI schema at builder time so the data form works in **both** `.run()` and `.execute()` (the filesystem-free path that previously couldn't consume `.packageJson()` at all). Explicit `.version()`/`.description()` still win; an empty `{}` or a settings-shaped object falls through to the settings overload, so this is a non-breaking addition.
596
+ - **`.packageJson({ from })` — anchored discovery** — discovery can now be anchored to an explicit location instead of the runtime cwd. Pass `{ from: import.meta.url }` (also accepts path strings, `file:` URL strings, or `URL` instances) so installable CLIs (`npm i -g`, `bunx`, `npx`) report their OWN version from any working directory. `discoverPackageJson(adapter, startDir?)` gained a matching optional anchor parameter.
1668
597
 
1669
598
  ## [2.1.0] - 2026-04-16
1670
599
 
1671
600
  ### Added
1672
601
 
1673
- - **Prompt — flag kind compatibility validation** — `FlagBuilder.prompt()` now rejects incompatible
1674
- prompt/flag combinations at compile time via `AllowedPromptConfig<C>` (e.g.,
1675
- `flag.enum([…]).prompt({ kind: 'multiselect' })` is a TypeScript error). A runtime validation gate
1676
- in `resolvePromptValueWithConfig()` catches mismatches before the prompter is invoked, throwing a
1677
- `CONSTRAINT_VIOLATED` `ValidationError` with an actionable `suggest` message.
1678
- - **`flagKind` phantom discriminator** — `FlagConfig` now carries a `flagKind` field (phantom — never
1679
- read at runtime) so the type system can distinguish all six flag kinds. `AllowedPromptConfig` uses
1680
- an indexed-access map (`PromptConfigByFlagKind`) for union-safe resolution.
1681
- - **PowerShell completion playground** — added a Windows-friendly `pwsh-demo` workspace with a
1682
- `.cmd` launcher, native `Register-ArgumentCompleter` registration, README install steps, and an
1683
- end-to-end smoke test so PowerShell completions can be exercised outside unit tests.
602
+ - **Prompt — flag kind compatibility validation** — `FlagBuilder.prompt()` now rejects incompatible prompt/flag combinations at compile time via `AllowedPromptConfig<C>` (e.g., `flag.enum([…]).prompt({ kind: 'multiselect' })` is a TypeScript error). A runtime validation gate in `resolvePromptValueWithConfig()` catches mismatches before the prompter is invoked, throwing a `CONSTRAINT_VIOLATED` `ValidationError` with an actionable `suggest` message.
603
+ - **`flagKind` phantom discriminator** — `FlagConfig` now carries a `flagKind` field (phantom — never read at runtime) so the type system can distinguish all six flag kinds. `AllowedPromptConfig` uses an indexed-access map (`PromptConfigByFlagKind`) for union-safe resolution.
604
+ - **PowerShell completion playground** — added a Windows-friendly `pwsh-demo` workspace with a `.cmd` launcher, native `Register-ArgumentCompleter` registration, README install steps, and an end-to-end smoke test so PowerShell completions can be exercised outside unit tests.
1684
605
 
1685
606
  ### Changed
1686
607
 
1687
- - **Meta-descriptions build** — `scripts/build-meta-descriptions.ts` pipes generated source through
1688
- `dprint fmt --stdin ts` instead of writing/reading a temp file and formatting in-place.
1689
- - **PowerShell install guidance** — current-session docs and generated script headers now use
1690
- `Out-String | Invoke-Expression`, matching the PowerShell flow that reliably evaluates multiline
1691
- completion output.
1692
- - **Bun support floor** — relaxed the documented and enforced Bun minimum from `>= 1.3.11` to
1693
- `>= 1.3` across package metadata, runtime support checks, examples, and docs.
608
+ - **Meta-descriptions build** — `scripts/build-meta-descriptions.ts` pipes generated source through `dprint fmt --stdin ts` instead of writing/reading a temp file and formatting in-place.
609
+ - **PowerShell install guidance** — current-session docs and generated script headers now use `Out-String | Invoke-Expression`, matching the PowerShell flow that reliably evaluates multiline completion output.
610
+ - **Bun support floor** — relaxed the documented and enforced Bun minimum from `>= 1.3.11` to `>= 1.3` across package metadata, runtime support checks, examples, and docs.
1694
611
 
1695
612
  ### Fixed
1696
613
 
1697
- - **PowerShell completions** — enum values now complete while the active token is still in progress,
1698
- stop suggesting flags after `--`, and quote accepted values when spaces or quotes would otherwise
1699
- produce invalid PowerShell input.
1700
- - **PowerShell playground launcher** — fixed the Windows `pwsh-demo.cmd` shim so the example runs
1701
- reliably from PowerShell and Command Prompt.
1702
- - **Package metadata** — moved `vite` from `optionalDependencies` to `devDependencies` so consumer
1703
- installs do not see it as a runtime dependency.
1704
- - **Docs deploy** — remove dead Workers runtime vars (`BUN_VERSION`, `NODE_OPTIONS`) that had no
1705
- effect on the static assets Worker, and add `html_handling: "drop-trailing-slash"` so clean URLs
1706
- resolve correctly instead of 404ing on trailing slashes.
614
+ - **PowerShell completions** — enum values now complete while the active token is still in progress, stop suggesting flags after `--`, and quote accepted values when spaces or quotes would otherwise produce invalid PowerShell input.
615
+ - **PowerShell playground launcher** — fixed the Windows `pwsh-demo.cmd` shim so the example runs reliably from PowerShell and Command Prompt.
616
+ - **Package metadata** — moved `vite` from `optionalDependencies` to `devDependencies` so consumer installs do not see it as a runtime dependency.
617
+ - **Docs deploy** — remove dead Workers runtime vars (`BUN_VERSION`, `NODE_OPTIONS`) that had no effect on the static assets Worker, and add `html_handling: "drop-trailing-slash"` so clean URLs resolve correctly instead of 404ing on trailing slashes.
1707
618
 
1708
619
  ## [2.0.1] - 2026-04-07
1709
620
 
1710
621
  ### Fixed
1711
622
 
1712
- - **Schema URL resolution** — `$schema` in emitted definition documents now points at
1713
- `dreamcli.schema.json` instead of the `/schema` subpath export, which doesn't resolve on the
1714
- jsdelivr CDN.
1715
- - **GitHub Pages deploy** — use `env` import from `node:process` for env access and set VitePress
1716
- `base` to `/dreamcli/` so assets and links resolve correctly on GitHub Pages.\
623
+ - **Schema URL resolution** — `$schema` in emitted definition documents now points at `dreamcli.schema.json` instead of the `/schema` subpath export, which doesn't resolve on the jsdelivr CDN.
624
+ - **GitHub Pages deploy** — use `env` import from `node:process` for env access and set VitePress `base` to `/dreamcli/` so assets and links resolve correctly on GitHub Pages.\
1717
625
  This allows for the old github pages deploy to work as an alternative to the cf workers.
1718
- - **Publish pipeline** — split build and publish into separate jobs, run build before pack with
1719
- `--ignore-scripts` to prevent prepack output from breaking `GITHUB_OUTPUT` parsing, hardcode the
1720
- npm CDN schema URL instead of the unreliable jsr.io esm.sh path, replace `actions/setup-node`
1721
- with bun's native registry auth, and switch internal imports to `#dreamcli/*` subpath imports.
1722
- - **Package exports map** — moved conditional exports from `publishConfig` into top-level `exports`
1723
- so local resolution matches what consumers see after install.
626
+ - **Publish pipeline** — split build and publish into separate jobs, run build before pack with `--ignore-scripts` to prevent prepack output from breaking `GITHUB_OUTPUT` parsing, hardcode the npm CDN schema URL instead of the unreliable jsr.io esm.sh path, replace `actions/setup-node` with bun's native registry auth, and switch internal imports to `#dreamcli/*` subpath imports.
627
+ - **Package exports map** — moved conditional exports from `publishConfig` into top-level `exports` so local resolution matches what consumers see after install.
1724
628
 
1725
629
  ## [2.0.0] - 2026-04-07
1726
630
 
1727
631
  ### Added
1728
632
 
1729
- - **String-literal schema DSL** — added a single-source schema surface that parses definitions at
1730
- compile time and runtime, then reuses the same model for JSON Schema generation.
1731
- - **Published definition schema export** — added `@kjanat/dreamcli/schema` so tooling and docs
1732
- consumers can import the generated definition schema locally instead of relying on the CDN URL.
633
+ - **String-literal schema DSL** — added a single-source schema surface that parses definitions at compile time and runtime, then reuses the same model for JSON Schema generation.
634
+ - **Published definition schema export** — added `@kjanat/dreamcli/schema` so tooling and docs consumers can import the generated definition schema locally instead of relying on the CDN URL.
1733
635
  - **Fish and PowerShell shell completions** — expanded completion support beyond Bash and Zsh.
1734
- - **Source-backed docs surfaces** — added generated API inventory pages, per-entrypoint symbol
1735
- routes, source-backed example pages with related symbol links, and reference guides for planner,
1736
- resolver, output, schema, support, migration, troubleshooting, and semantic deltas.
1737
- - **`gh-project` workflow helper** — added a DreamCLI-powered project tool for syncing the
1738
- re-foundation task board and PRD state.
636
+ - **Source-backed docs surfaces** — added generated API inventory pages, per-entrypoint symbol routes, source-backed example pages with related symbol links, and reference guides for planner, resolver, output, schema, support, migration, troubleshooting, and semantic deltas.
637
+ - **`gh-project` workflow helper** — added a DreamCLI-powered project tool for syncing the re-foundation task board and PRD state.
1739
638
 
1740
639
  ### Changed
1741
640
 
1742
- - **Package identity and build pipeline** — the package is now published as `@kjanat/dreamcli`,
1743
- ships ESM-only, emits the definition schema during the tsdown prepare hook, tightens published
1744
- exports for runtime-specific consumers, and hardens npm, JSR, and docs release checks.
1745
- - **Docs app architecture** — VitePress now builds reference and example pages from data loaders
1746
- instead of static generated files, adds runtime/twoslash settings UI, improves mobile twoslash
1747
- UX, and copies root artifacts into deployed docs output.
1748
- - **Examples and walkthroughs** — the `gh` example grew into a multi-file workspace canary, and the
1749
- example set now doubles as richer docs source with broader JSDoc coverage and better walkthrough
1750
- material.
641
+ - **Package identity and build pipeline** — the package is now published as `@kjanat/dreamcli`, ships ESM-only, emits the definition schema during the tsdown prepare hook, tightens published exports for runtime-specific consumers, and hardens npm, JSR, and docs release checks.
642
+ - **Docs app architecture** — VitePress now builds reference and example pages from data loaders instead of static generated files, adds runtime/twoslash settings UI, improves mobile twoslash UX, and copies root artifacts into deployed docs output.
643
+ - **Examples and walkthroughs** — the `gh` example grew into a multi-file workspace canary, and the example set now doubles as richer docs source with broader JSDoc coverage and better walkthrough material.
1751
644
 
1752
645
  ### Fixed
1753
646
 
1754
- - **Completion and alias handling** — hidden compatibility aliases now parse correctly, Bash and Zsh
1755
- completion behavior is safer and more consistent, and shell completion edge cases were tightened.
1756
- - **Aggregate validation diagnostics** — mixed flag and arg validation failures now surface clearer
1757
- per-issue labels plus value-source labels such as `env ...` and `stdin`.
1758
- - **Schema and docs integration** — schema URLs, generated meta descriptions, twoslash rendering,
1759
- and source-backed docs pages now build reliably across local, CI, and Cloudflare deploys.
1760
- - **CLI and runtime edge cases** — unresolved schema references now fail closed, runtime/support
1761
- checks were hardened, and several dispatch/output/runtime regressions were corrected.
647
+ - **Completion and alias handling** — hidden compatibility aliases now parse correctly, Bash and Zsh completion behavior is safer and more consistent, and shell completion edge cases were tightened.
648
+ - **Aggregate validation diagnostics** — mixed flag and arg validation failures now surface clearer per-issue labels plus value-source labels such as `env ...` and `stdin`.
649
+ - **Schema and docs integration** — schema URLs, generated meta descriptions, twoslash rendering, and source-backed docs pages now build reliably across local, CI, and Cloudflare deploys.
650
+ - **CLI and runtime edge cases** — unresolved schema references now fail closed, runtime/support checks were hardened, and several dispatch/output/runtime regressions were corrected.
1762
651
 
1763
652
  ## [1.0.0] - 2026-04-02
1764
653
 
@@ -1766,68 +655,45 @@ sections that follow. Upgrading from 2.x is covered by the new
1766
655
 
1767
656
  #### Release Automation
1768
657
 
1769
- - **GitHub Actions npm publish workflow** (`.github/workflows/publish-npm.yml`) — publishes the
1770
- package to npm on GitHub release with provenance enabled, bringing npm release automation in line
1771
- with the existing JSR publish flow.
658
+ - **GitHub Actions npm publish workflow** (`.github/workflows/publish-npm.yml`) — publishes the package to npm on GitHub release with provenance enabled, bringing npm release automation in line with the existing JSR publish flow.
1772
659
 
1773
660
  #### Canonical Semantics Guide
1774
661
 
1775
- - **`docs/guide/semantics.md`** — centralized reference for parser and resolver behavior, including
1776
- repeated flags, short-flag stacking, `--` separator rules, `--no-*` alias behavior, value-source
1777
- precedence, non-interactive prompt skipping, propagated-flag masking, and default-command root
1778
- help/completion semantics.
662
+ - **`docs/guide/semantics.md`** — centralized reference for parser and resolver behavior, including repeated flags, short-flag stacking, `--` separator rules, `--no-*` alias behavior, value-source precedence, non-interactive prompt skipping, propagated-flag masking, and default-command root help/completion semantics.
1779
663
 
1780
664
  #### Plugin Lifecycle Hooks
1781
665
 
1782
- - **`plugin(hooks, name?)`** and **`.plugin(definition)`** expose a typed extension surface around
1783
- command execution.
1784
- - **Lifecycle phases** — `beforeParse`, `afterResolve`, `beforeAction`, and `afterAction` let
1785
- plugins observe or instrument execution without reaching into CLI internals.
666
+ - **`plugin(hooks, name?)`** and **`.plugin(definition)`** expose a typed extension surface around command execution.
667
+ - **Lifecycle phases** — `beforeParse`, `afterResolve`, `beforeAction`, and `afterAction` let plugins observe or instrument execution without reaching into CLI internals.
1786
668
 
1787
669
  #### `derive()` Command Context
1788
670
 
1789
- - **`command(...).derive(handler)`** adds typed command-scoped pre-action context derived from fully
1790
- resolved flags and args.
1791
- - **Derived context merges into `ctx`** so commands can validate once and consume typed values in
1792
- the action handler.
671
+ - **`command(...).derive(handler)`** adds typed command-scoped pre-action context derived from fully resolved flags and args.
672
+ - **Derived context merges into `ctx`** so commands can validate once and consume typed values in the action handler.
1793
673
 
1794
674
  #### Schema Export and Validation
1795
675
 
1796
- - **`generateInputSchema()`** exports JSON Schema from CLI definitions for machine validation and
1797
- tooling.
1798
- - **Schema export docs and reference coverage** now document export formats, discriminator behavior,
1799
- and default/hidden command handling.
676
+ - **`generateInputSchema()`** exports JSON Schema from CLI definitions for machine validation and tooling.
677
+ - **Schema export docs and reference coverage** now document export formats, discriminator behavior, and default/hidden command handling.
1800
678
 
1801
679
  #### Runtime Surface and Execution Options
1802
680
 
1803
681
  - **Runtime support matrix and version guards** added around adapter creation.
1804
- - **`run()` accepts `jsonMode`** in options, letting callers force structured output without
1805
- shell-level flags.
682
+ - **`run()` accepts `jsonMode`** in options, letting callers force structured output without shell-level flags.
1806
683
  - **`out.table()` format and stream overrides** expose finer control over tabular output.
1807
684
 
1808
685
  ### Changed
1809
686
 
1810
- - **Docs navigation and entrypoints** — guide pages now link to the canonical semantics guide, the
1811
- API reference landing page includes quick import guidance and key factories per subpath export,
1812
- and the VitePress sidebar surfaces the semantics page under the Advanced guide section.
1813
- - **Public API surface tightened** — runtime exports were pruned and guarded, explicit `require`
1814
- conditions were added to package exports, and self-referencing package imports were hardened.
1815
- - **Docs and examples expanded** — JSDoc/reference coverage grew across exported symbols, schema
1816
- export/testing/runtime docs were added, and the `gh` walkthrough became a multi-file example
1817
- package.
1818
- - **CI and packaging hardened** — version-sync checks, supported Node pinning, preview publish
1819
- verification, and Bun-pack package validation were added around the release surface.
687
+ - **Docs navigation and entrypoints** — guide pages now link to the canonical semantics guide, the API reference landing page includes quick import guidance and key factories per subpath export, and the VitePress sidebar surfaces the semantics page under the Advanced guide section.
688
+ - **Public API surface tightened** — runtime exports were pruned and guarded, explicit `require` conditions were added to package exports, and self-referencing package imports were hardened.
689
+ - **Docs and examples expanded** — JSDoc/reference coverage grew across exported symbols, schema export/testing/runtime docs were added, and the `gh` walkthrough became a multi-file example package.
690
+ - **CI and packaging hardened** — version-sync checks, supported Node pinning, preview publish verification, and Bun-pack package validation were added around the release surface.
1820
691
 
1821
692
  ### Fixed
1822
693
 
1823
- - **Default-command UX** — single-command root help is merged correctly, root completions surface
1824
- default-command flags, unknown root flags are rejected cleanly, and schema discriminator handling
1825
- matches the actual default-command surface.
1826
- - **Stdin and runtime behavior** — stdin reads defer until dispatch needs them, empty pipes are
1827
- distinguished from no pipe, and test adapters now match real runtime behavior more closely.
1828
- - **Parser/help/completion/output edge cases** — optional array flags resolve to `[]`, variadic help
1829
- formatting is corrected, bash/zsh completion edge cases are hardened, non-finite JSON values are
1830
- rejected, and table options are preserved correctly.
694
+ - **Default-command UX** — single-command root help is merged correctly, root completions surface default-command flags, unknown root flags are rejected cleanly, and schema discriminator handling matches the actual default-command surface.
695
+ - **Stdin and runtime behavior** — stdin reads defer until dispatch needs them, empty pipes are distinguished from no pipe, and test adapters now match real runtime behavior more closely.
696
+ - **Parser/help/completion/output edge cases** — optional array flags resolve to `[]`, variadic help formatting is corrected, bash/zsh completion edge cases are hardened, non-finite JSON values are rejected, and table options are preserved correctly.
1831
697
 
1832
698
  ## [0.9.2] - 2026-03-30
1833
699
 
@@ -1836,16 +702,13 @@ sections that follow. Upgrading from 2.x is covered by the new
1836
702
  #### Stdin-Backed Positional Arguments
1837
703
 
1838
704
  - **`ArgBuilder.stdin()`** lets positional args consume piped stdin when no CLI token is provided.
1839
- - **`RuntimeAdapter.readStdin()`** adds full stdin reads to the runtime contract across Node, Bun,
1840
- and Deno adapters.
1841
- - **`RunOptions.stdinData` and testkit plumbing** let in-process tests feed stdin-backed commands
1842
- without touching real process state.
705
+ - **`RuntimeAdapter.readStdin()`** adds full stdin reads to the runtime contract across Node, Bun, and Deno adapters.
706
+ - **`RunOptions.stdinData` and testkit plumbing** let in-process tests feed stdin-backed commands without touching real process state.
1843
707
  - **Comprehensive stdin coverage** added across schema, resolver, runtime, and testkit tests.
1844
708
 
1845
709
  ### Changed
1846
710
 
1847
- - Positional-arg resolution for stdin-enabled args expanded from **CLI → env → default** to
1848
- **CLI → stdin → env → default**.
711
+ - Positional-arg resolution for stdin-enabled args expanded from **CLI → env → default** to **CLI → stdin → env → default**.
1849
712
  - Scripts now separate **`lint`** from **`format`**, so linting no longer doubles as a rewrite step.
1850
713
 
1851
714
  ## [0.9.1] - 2026-03-30
@@ -1854,70 +717,40 @@ sections that follow. Upgrading from 2.x is covered by the new
1854
717
 
1855
718
  #### Default Command Support
1856
719
 
1857
- - **`CLIBuilder.default(command)`** lets a CLI run a fallback command when no subcommand is
1858
- specified.
1859
- - **Root args and flags flow through the default command** while explicit subcommands still take
1860
- precedence.
720
+ - **`CLIBuilder.default(command)`** lets a CLI run a fallback command when no subcommand is specified.
721
+ - **Root args and flags flow through the default command** while explicit subcommands still take precedence.
1861
722
 
1862
723
  #### Package.json Auto-Discovery
1863
724
 
1864
- - **`CLIBuilder.packageJson(settings?)`** — opt-in builder method that enables automatic
1865
- `package.json` discovery at `.run()` time. Walks up from `cwd` to find the nearest `package.json`
1866
- and merges `version` and `description` into the CLI schema. Explicit `.version()` and
1867
- `.description()` calls always take precedence over discovered values.
1868
- - **`PackageJsonSettings.inferName`** — when `true`, infers the CLI binary name from the `bin` key
1869
- (first key of the object) or the package `name` field (scope stripped). Defaults to `false`.
1870
- - **`discoverPackageJson(adapter)`** — pure function that walks up from `adapter.cwd` to find and
1871
- parse the nearest `package.json`. Returns `PackageJsonData | null`. All I/O flows through the
1872
- adapter — fully testable with virtual filesystems.
1873
- - **`inferCliName(pkg)`** — resolves CLI name from `PackageJsonData` with priority: bin key → scoped
1874
- name (stripped) → `undefined`.
1875
- - **Silent error handling** — malformed JSON, non-object roots, and missing `package.json` all
1876
- return `null` (not errors). Deno permission denials degrade gracefully via the adapter's existing
1877
- `readFile` contract.
1878
- - **Completions skip** — package.json discovery is skipped for the `completions` subcommand,
1879
- matching the existing config discovery skip pattern.
1880
- - **43 new tests** — `package-json.test.ts` (24 unit tests: walk-up resolution, field extraction,
1881
- error resilience, Windows path termination) and `cli-package-json.test.ts` (19 integration tests:
1882
- version/description fill, name inference, precedence, walk-up, completions skip, combined with
1883
- config, error resilience).
725
+ - **`CLIBuilder.packageJson(settings?)`** — opt-in builder method that enables automatic `package.json` discovery at `.run()` time. Walks up from `cwd` to find the nearest `package.json` and merges `version` and `description` into the CLI schema. Explicit `.version()` and `.description()` calls always take precedence over discovered values.
726
+ - **`PackageJsonSettings.inferName`** — when `true`, infers the CLI binary name from the `bin` key (first key of the object) or the package `name` field (scope stripped). Defaults to `false`.
727
+ - **`discoverPackageJson(adapter)`** — pure function that walks up from `adapter.cwd` to find and parse the nearest `package.json`. Returns `PackageJsonData | null`. All I/O flows through the adapter — fully testable with virtual filesystems.
728
+ - **`inferCliName(pkg)`** — resolves CLI name from `PackageJsonData` with priority: bin key → scoped name (stripped) → `undefined`.
729
+ - **Silent error handling** — malformed JSON, non-object roots, and missing `package.json` all return `null` (not errors). Deno permission denials degrade gracefully via the adapter's existing `readFile` contract.
730
+ - **Completions skip** — package.json discovery is skipped for the `completions` subcommand, matching the existing config discovery skip pattern.
731
+ - **43 new tests** — `package-json.test.ts` (24 unit tests: walk-up resolution, field extraction, error resilience, Windows path termination) and `cli-package-json.test.ts` (19 integration tests: version/description fill, name inference, precedence, walk-up, completions skip, combined with config, error resilience).
1884
732
 
1885
733
  #### `help` Virtual Subcommand
1886
734
 
1887
- - **`BINARY help <command>`** produces the same output as `BINARY <command> --help`. Rewrites argv
1888
- via recursive `execute()` — no dispatch duplication.
735
+ - **`BINARY help <command>`** produces the same output as `BINARY <command> --help`. Rewrites argv via recursive `execute()` — no dispatch duplication.
1889
736
  - **Nested support** — `help db migrate` works like `db migrate --help`.
1890
737
  - **Bare `help`** shows root help.
1891
- - **Defers to real commands** — if the user registers a command named `help` (or aliased as `help`),
1892
- it takes priority over the virtual subcommand.
1893
- - **`--json` propagation** — `help --json <command>` correctly preserves json mode (help text routes
1894
- to stderr, stdout reserved for data).
738
+ - **Defers to real commands** — if the user registers a command named `help` (or aliased as `help`), it takes priority over the virtual subcommand.
739
+ - **`--json` propagation** — `help --json <command>` correctly preserves json mode (help text routes to stderr, stdout reserved for data).
1895
740
  - **10 new tests** across `cli.test.ts` (7), `cli-nesting.test.ts` (2), `cli-json.test.ts` (1).
1896
741
 
1897
742
  #### Arg Environment Variable Resolution
1898
743
 
1899
- - **`ArgBuilder.env(varName)`** binds a positional argument to an environment variable. When the CLI
1900
- value is absent, the resolver reads the env var and coerces the string to the arg's declared kind
1901
- (passthrough for strings, `Number()` with NaN guard for numbers, `parseFn` invocation for custom
1902
- args). Resolution order: **CLI → env → default**.
1903
- - **`ArgSchema.envVar`** field (`string | undefined`) stores the env var name on the runtime schema
1904
- descriptor.
1905
- - **Env coercion for args** via `coerceArgEnvValue()` in the resolver. Handles `string`
1906
- (passthrough), `number` (parse + NaN guard), and `custom` (delegates to `parseFn`, wraps thrown
1907
- errors).
1908
- - **`[env: VAR]` annotation** in help output for args with env bindings, matching the existing flag
1909
- annotation style.
1910
- - **Actionable required-arg error hints** — `buildRequiredArgSuggest()` generates suggestions
1911
- including the env var when configured (e.g. "Provide a value for \<target\> or set
1912
- DEPLOY_TARGET").
1913
- - **16 new tests** — `resolve-arg-env.test.ts` (15 tests covering string/number/custom coercion,
1914
- CLI > env > default precedence, deprecation warnings, error cases) and 1 help output test for the
1915
- `[env: VAR]` annotation.
744
+ - **`ArgBuilder.env(varName)`** binds a positional argument to an environment variable. When the CLI value is absent, the resolver reads the env var and coerces the string to the arg's declared kind (passthrough for strings, `Number()` with NaN guard for numbers, `parseFn` invocation for custom args). Resolution order: **CLI → env → default**.
745
+ - **`ArgSchema.envVar`** field (`string | undefined`) stores the env var name on the runtime schema descriptor.
746
+ - **Env coercion for args** via `coerceArgEnvValue()` in the resolver. Handles `string` (passthrough), `number` (parse + NaN guard), and `custom` (delegates to `parseFn`, wraps thrown errors).
747
+ - **`[env: VAR]` annotation** in help output for args with env bindings, matching the existing flag annotation style.
748
+ - **Actionable required-arg error hints** — `buildRequiredArgSuggest()` generates suggestions including the env var when configured (e.g. "Provide a value for \<target\> or set DEPLOY_TARGET").
749
+ - **16 new tests** — `resolve-arg-env.test.ts` (15 tests covering string/number/custom coercion, CLI > env > default precedence, deprecation warnings, error cases) and 1 help output test for the `[env: VAR]` annotation.
1916
750
 
1917
751
  #### Command Metadata
1918
752
 
1919
- - **`CommandMeta`** added to action handlers and middleware, carrying the CLI name, invoked binary,
1920
- version, and resolved leaf command name.
753
+ - **`CommandMeta`** added to action handlers and middleware, carrying the CLI name, invoked binary, version, and resolved leaf command name.
1921
754
 
1922
755
  #### Documentation Site, README, and Examples
1923
756
 
@@ -1929,8 +762,7 @@ sections that follow. Upgrading from 2.x is covered by the new
1929
762
 
1930
763
  ### Changed
1931
764
 
1932
- - Completion generation was reorganized into shell-specific generators and the package/tooling
1933
- surface was refreshed for the `0.9.1` milestone.
765
+ - Completion generation was reorganized into shell-specific generators and the package/tooling surface was refreshed for the `0.9.1` milestone.
1934
766
  - Comprehensive public-facing JSDoc examples were added to the builder APIs.
1935
767
 
1936
768
  ### Fixed
@@ -1943,39 +775,25 @@ sections that follow. Upgrading from 2.x is covered by the new
1943
775
 
1944
776
  #### Deno Adapter
1945
777
 
1946
- - **`createDenoAdapter(ns?)`** — full `RuntimeAdapter` implementation for Deno. Reads argv from
1947
- `Deno.args` (prepends synthetic `['deno', 'run']` for parity), env from `Deno.env.toObject()`, cwd
1948
- from `Deno.cwd()`, stdout/stderr via `TextEncoder` → `Deno.stdout.write`/`Deno.stderr.write`,
1949
- stdin via `Deno.stdin.readable` stream with line-buffered reader, TTY detection via
1950
- `isTerminal()`, `readFile` via `Deno.readTextFile`, and homedir/configDir from env vars.
1951
- - **Permission-safe** — `PermissionDenied` errors gracefully degrade: env falls back to `{}`, cwd to
1952
- `/`, readFile to `null`. Non-permission errors propagate.
1953
- - **`deno-builtins.d.ts`** — ambient type declarations for `TextEncoder`, `TextDecoder`, and
1954
- `ReadableStream` (needed because `lib: ["ES2022"]` excludes web platform APIs).
1955
- - **`createAdapter()` auto-detection** now handles Deno runtime via `globalThis.Deno` feature
1956
- probing.
778
+ - **`createDenoAdapter(ns?)`** — full `RuntimeAdapter` implementation for Deno. Reads argv from `Deno.args` (prepends synthetic `['deno', 'run']` for parity), env from `Deno.env.toObject()`, cwd from `Deno.cwd()`, stdout/stderr via `TextEncoder` → `Deno.stdout.write`/`Deno.stderr.write`, stdin via `Deno.stdin.readable` stream with line-buffered reader, TTY detection via `isTerminal()`, `readFile` via `Deno.readTextFile`, and homedir/configDir from env vars.
779
+ - **Permission-safe** — `PermissionDenied` errors gracefully degrade: env falls back to `{}`, cwd to `/`, readFile to `null`. Non-permission errors propagate.
780
+ - **`deno-builtins.d.ts`** — ambient type declarations for `TextEncoder`, `TextDecoder`, and `ReadableStream` (needed because `lib: ["ES2022"]` excludes web platform APIs).
781
+ - **`createAdapter()` auto-detection** now handles Deno runtime via `globalThis.Deno` feature probing.
1957
782
  - Re-exported `createDenoAdapter` and `DenoNamespace` from `@kjanat/dreamcli/runtime` subpath.
1958
783
 
1959
784
  #### Cross-Runtime CI
1960
785
 
1961
- - **GitHub Actions CI workflow** (`.github/workflows/ci.yml`) — lint+typecheck (Bun), test matrix
1962
- (Node LTS + Bun stable), Deno smoke test, build with publint+attw.
1963
- - **Deno smoke test** (`scripts/deno-smoke-test.ts`) — runs on real Deno runtime after build,
1964
- exercising `createDenoAdapter()` against actual Deno APIs.
786
+ - **GitHub Actions CI workflow** (`.github/workflows/ci.yml`) — lint+typecheck (Bun), test matrix (Node LTS + Bun stable), Deno smoke test, build with publint+attw.
787
+ - **Deno smoke test** (`scripts/deno-smoke-test.ts`) — runs on real Deno runtime after build, exercising `createDenoAdapter()` against actual Deno APIs.
1965
788
 
1966
789
  #### JSR Publishing
1967
790
 
1968
- - **`deno.json`** with JSR package config (`@kjanat/dreamcli`), three subpath exports, publish
1969
- include/exclude rules.
1970
- - **GitHub Actions publish workflow** (`.github/workflows/publish-jsr.yml`) — publishes to JSR on
1971
- GitHub release with OIDC provenance.
791
+ - **`deno.json`** with JSR package config (`@kjanat/dreamcli`), three subpath exports, publish include/exclude rules.
792
+ - **GitHub Actions publish workflow** (`.github/workflows/publish-jsr.yml`) — publishes to JSR on GitHub release with OIDC provenance.
1972
793
 
1973
794
  ### Changed
1974
795
 
1975
- - **`.ts` import extensions** — all import specifiers switched from `.js` to `.ts` via
1976
- `allowImportingTsExtensions`. tsconfig updated: `noEmit: true` +
1977
- `allowImportingTsExtensions: true` replace `declaration`/`declarationMap`/`sourceMap`/`outDir`
1978
- (all handled by tsdown). Removes the need for Deno's `unstable: ["sloppy-imports"]`.
796
+ - **`.ts` import extensions** — all import specifiers switched from `.js` to `.ts` via `allowImportingTsExtensions`. tsconfig updated: `noEmit: true` + `allowImportingTsExtensions: true` replace `declaration`/`declarationMap`/`sourceMap`/`outDir` (all handled by tsdown). Removes the need for Deno's `unstable: ["sloppy-imports"]`.
1979
797
  - `detectRuntime()` updated with Deno detection via `globalThis.Deno?.version?.deno`.
1980
798
  - `createAdapter()` switch now covers `'deno'` case alongside `'node'` and `'bun'`.
1981
799
  - Completion generator: `typeof` check on `globalThis` narrowed to avoid Deno type errors.
@@ -1986,77 +804,40 @@ sections that follow. Upgrading from 2.x is covered by the new
1986
804
 
1987
805
  ### Breaking
1988
806
 
1989
- - **Subpath exports** — single `"."` entry split into `"."`, `"./testkit"`, `"./runtime"`. Test
1990
- utilities (`runCommand`, `createCaptureOutput`, `createTestPrompter`, `createTestAdapter`,
1991
- `PROMPT_CANCEL`) moved to `@kjanat/dreamcli/testkit`. Runtime adapters (`createAdapter`,
1992
- `createNodeAdapter`, `createBunAdapter`, `detectRuntime`, `ExitError`, `RUNTIMES`,
1993
- `RuntimeAdapter`) moved to `@kjanat/dreamcli/runtime`. `createTestAdapter`/`TestAdapterOptions` exported
1994
- only from `@kjanat/dreamcli/testkit`.
807
+ - **Subpath exports** — single `"."` entry split into `"."`, `"./testkit"`, `"./runtime"`. Test utilities (`runCommand`, `createCaptureOutput`, `createTestPrompter`, `createTestAdapter`, `PROMPT_CANCEL`) moved to `@kjanat/dreamcli/testkit`. Runtime adapters (`createAdapter`, `createNodeAdapter`, `createBunAdapter`, `detectRuntime`, `ExitError`, `RUNTIMES`, `RuntimeAdapter`) moved to `@kjanat/dreamcli/runtime`. `createTestAdapter`/`TestAdapterOptions` exported only from `@kjanat/dreamcli/testkit`.
1995
808
 
1996
809
  ### Added
1997
810
 
1998
811
  #### Spinner & Progress Bar
1999
812
 
2000
- - **`out.spinner(text, options?)`** creates a spinner handle for indeterminate progress feedback.
2001
- Returns a `SpinnerHandle` with `update(text)`, `succeed(text?)`, `fail(text?)`, `stop()`, and
2002
- `wrap(promise, options?)` for auto-succeed/fail on promise settlement.
2003
- - **`out.progress(options)`** creates a progress bar handle. Pass `total` for determinate mode
2004
- (percentage bar); omit for indeterminate (pulsing animation). Returns a `ProgressHandle` with
2005
- `increment(n?)`, `update(value)`, `done(text?)`, and `fail(text?)`.
813
+ - **`out.spinner(text, options?)`** creates a spinner handle for indeterminate progress feedback. Returns a `SpinnerHandle` with `update(text)`, `succeed(text?)`, `fail(text?)`, `stop()`, and `wrap(promise, options?)` for auto-succeed/fail on promise settlement.
814
+ - **`out.progress(options)`** creates a progress bar handle. Pass `total` for determinate mode (percentage bar); omit for indeterminate (pulsing animation). Returns a `ProgressHandle` with `increment(n?)`, `update(value)`, `done(text?)`, and `fail(text?)`.
2006
815
  - **Four rendering modes** with automatic dispatch:
2007
- - **TTY** — animated braille spinner (80ms frames) and bar rendering with ANSI cursor control.
2008
- Hides cursor during animation, restores on terminal methods.
2009
- - **Static** (`fallback: 'static'`) — plain text at lifecycle boundaries (start, succeed, fail).
2010
- No ANSI codes. For CI and piped output.
816
+ - **TTY** — animated braille spinner (80ms frames) and bar rendering with ANSI cursor control. Hides cursor during animation, restores on terminal methods.
817
+ - **Static** (`fallback: 'static'`) — plain text at lifecycle boundaries (start, succeed, fail). No ANSI codes. For CI and piped output.
2011
818
  - **Noop** (`fallback: 'silent'`, default) — all methods are no-ops. Silent in non-TTY.
2012
819
  - **JSON mode** — always noop (structured output only).
2013
- - **Active handle tracking** — at most one spinner or progress may be active at a time. Creating a
2014
- new one implicitly stops the previous to avoid garbled terminal output.
2015
- - **`ActivityEvent` discriminated union** — 10-variant DU capturing spinner and progress lifecycle
2016
- events (`spinner:start`, `spinner:update`, `spinner:succeed`, `spinner:fail`, `spinner:stop`,
2017
- `progress:start`, `progress:increment`, `progress:update`, `progress:done`, `progress:fail`).
2018
- - **Testkit capture handles** — `CaptureOutputChannel` subclass overrides `spinner()` and
2019
- `progress()` to record `ActivityEvent[]` for assertion. `CapturedOutput.activity` array added.
2020
- - **New public types** exported from barrel: `ActivityEvent`, `Fallback`, `SpinnerHandle`,
2021
- `SpinnerOptions`, `ProgressHandle`, `ProgressOptions`.
2022
- - **`out.stopActive()`** public method on `Out` to clean up active spinner/progress timers. Prevents
2023
- process hangs when a handler throws before reaching a terminal method (`stop`, `succeed`, `fail`,
2024
- `done`). `runCommand()` calls it automatically in a `finally` block; direct `createOutput()` users
2025
- call it themselves.
2026
- - **`progress:increment` activity event** — 10th `ActivityEvent` variant
2027
- `{ type: 'progress:increment', delta }`. `increment()` now emits this instead of reusing
2028
- `progress:update`, making capture events unambiguous for testing.
820
+ - **Active handle tracking** — at most one spinner or progress may be active at a time. Creating a new one implicitly stops the previous to avoid garbled terminal output.
821
+ - **`ActivityEvent` discriminated union** — 10-variant DU capturing spinner and progress lifecycle events (`spinner:start`, `spinner:update`, `spinner:succeed`, `spinner:fail`, `spinner:stop`, `progress:start`, `progress:increment`, `progress:update`, `progress:done`, `progress:fail`).
822
+ - **Testkit capture handles** — `CaptureOutputChannel` subclass overrides `spinner()` and `progress()` to record `ActivityEvent[]` for assertion. `CapturedOutput.activity` array added.
823
+ - **New public types** exported from barrel: `ActivityEvent`, `Fallback`, `SpinnerHandle`, `SpinnerOptions`, `ProgressHandle`, `ProgressOptions`.
824
+ - **`out.stopActive()`** public method on `Out` to clean up active spinner/progress timers. Prevents process hangs when a handler throws before reaching a terminal method (`stop`, `succeed`, `fail`, `done`). `runCommand()` calls it automatically in a `finally` block; direct `createOutput()` users call it themselves.
825
+ - **`progress:increment` activity event** — 10th `ActivityEvent` variant `{ type: 'progress:increment', delta }`. `increment()` now emits this instead of reusing `progress:update`, making capture events unambiguous for testing.
2029
826
 
2030
827
  ### Changed
2031
828
 
2032
829
  - `Out` interface extended with `spinner()` and `progress()` methods.
2033
830
  - `CapturedOutput` extended with `activity: ActivityEvent[]` field.
2034
- - `createCaptureOutput` now returns a `CaptureOutputChannel` that records activity events separately
2035
- from stdout/stderr.
2036
- - `FlagParseFn<T>` widened from `(raw: string) => T` to `(raw: unknown) => T`. Config files carry
2037
- structured JSON data — `parseFn` now receives the raw value directly and is responsible for
2038
- narrowing. CLI/env still pass strings; config passes the JSON value as-is.
831
+ - `createCaptureOutput` now returns a `CaptureOutputChannel` that records activity events separately from stdout/stderr.
832
+ - `FlagParseFn<T>` widened from `(raw: string) => T` to `(raw: unknown) => T`. Config files carry structured JSON data — `parseFn` now receives the raw value directly and is responsible for narrowing. CLI/env still pass strings; config passes the JSON value as-is.
2039
833
  - `Out` interface extended with `stopActive()` method for explicit timer cleanup.
2040
834
  - `ActivityEvent` union widened from 9 to 10 variants (added `progress:increment`).
2041
- - `OutputChannel` refactored: activity handle implementations extracted to `activity.ts` (~581
2042
- lines), `WriteFn` type and `writeLine` helper extracted to `writer.ts` (~30 lines). `index.ts`
2043
- reduced from 1156 to 589 lines. No public API changes.
2044
- - All activity handle output (static and TTY) now routes to stderr. Previously static mode used a
2045
- `StaticWriters` pair routing some output to stdout; the dual-writer abstraction is removed.
2046
- - `runCommand()` calls `out.stopActive()` in a `finally` block, ensuring timer cleanup on handler
2047
- exceptions.
2048
- - **Resolve coercion unified** — three near-identical functions (`coerceEnvValue` ~105 lines,
2049
- `coerceConfigValue` ~120 lines, `coercePromptValue` ~120 lines) replaced by single `coerceValue()`
2050
- using `CoerceSource` discriminated union (`'env' | 'config' | 'prompt'`). Error messages
2051
- parameterized via `sourceLabel()`/`sourceDetails()`/`coercionError()` helpers. `resolve/index.ts`
2052
- reduced from ~1115 to ~940 lines.
2053
- - **Activity types extracted** — 7 activity/output types (`Fallback`, `SpinnerOptions`,
2054
- `SpinnerHandle`, `ProgressOptions`, `ProgressHandle`, `ActivityEvent`, `TableColumn`) moved from
2055
- `schema/command.ts` to `schema/activity.ts` (~150 lines). `command.ts` reduced from 898 to 784
2056
- lines.
2057
- - **Root help extracted** — `formatRootHelp()` + `padEnd()` + `wrapText()` moved from `cli/index.ts`
2058
- to `cli/root-help.ts` (~133 lines). Uses structural `CLISchemaLike` interface to avoid circular
2059
- imports. `cli/index.ts` reduced from 901 to 793 lines.
835
+ - `OutputChannel` refactored: activity handle implementations extracted to `activity.ts` (~581 lines), `WriteFn` type and `writeLine` helper extracted to `writer.ts` (~30 lines). `index.ts` reduced from 1156 to 589 lines. No public API changes.
836
+ - All activity handle output (static and TTY) now routes to stderr. Previously static mode used a `StaticWriters` pair routing some output to stdout; the dual-writer abstraction is removed.
837
+ - `runCommand()` calls `out.stopActive()` in a `finally` block, ensuring timer cleanup on handler exceptions.
838
+ - **Resolve coercion unified** — three near-identical functions (`coerceEnvValue` ~105 lines, `coerceConfigValue` ~120 lines, `coercePromptValue` ~120 lines) replaced by single `coerceValue()` using `CoerceSource` discriminated union (`'env' | 'config' | 'prompt'`). Error messages parameterized via `sourceLabel()`/`sourceDetails()`/`coercionError()` helpers. `resolve/index.ts` reduced from ~1115 to ~940 lines.
839
+ - **Activity types extracted** — 7 activity/output types (`Fallback`, `SpinnerOptions`, `SpinnerHandle`, `ProgressOptions`, `ProgressHandle`, `ActivityEvent`, `TableColumn`) moved from `schema/command.ts` to `schema/activity.ts` (~150 lines). `command.ts` reduced from 898 to 784 lines.
840
+ - **Root help extracted** — `formatRootHelp()` + `padEnd()` + `wrapText()` moved from `cli/index.ts` to `cli/root-help.ts` (~133 lines). Uses structural `CLISchemaLike` interface to avoid circular imports. `cli/index.ts` reduced from 901 to 793 lines.
2060
841
  - **`infer/` stub deleted** — removed empty `src/core/infer/index.ts`.
2061
842
  - **Source files in published package** — `"src"` added to `files` array in package.json.
2062
843
  - **Package manager migrated** — pnpm → bun. `packageManager` set to `bun@1.3.9`.
@@ -2066,26 +847,20 @@ sections that follow. Upgrading from 2.x is covered by the new
2066
847
  ### Fixed
2067
848
 
2068
849
  - `--config=<path>` equals form now correctly parsed and stripped from argv before dispatch.
2069
- - Zsh completion: multi-alias flags use all short aliases in the exclusion group, not just the
2070
- first.
850
+ - Zsh completion: multi-alias flags use all short aliases in the exclusion group, not just the first.
2071
851
  - Bash completion: `escapeForSingleQuote()` sanitizes `compgen -W` words to prevent shell injection.
2072
- - Win32 `resolveConfigDir`: strip trailing separator from homedir to avoid doubled backslashes on
2073
- drive roots (e.g. `C:\`).
852
+ - Win32 `resolveConfigDir`: strip trailing separator from homedir to avoid doubled backslashes on drive roots (e.g. `C:\`).
2074
853
  - Win32 `resolveConfigDir`: treat empty `APPDATA` as unset, falling back to homedir-based path.
2075
854
  - Win32 `homedir`: add `HOMEDRIVE`+`HOMEPATH` fallback; never use `HOMEPATH` alone.
2076
- - Levenshtein distance: replace 2D array with `Uint16Array` rolling buffer, drop defensive
2077
- `undefined` guards.
855
+ - Levenshtein distance: replace 2D array with `Uint16Array` rolling buffer, drop defensive `undefined` guards.
2078
856
  - Completions command detection via schema lookup instead of raw `argv[0]` string match.
2079
857
  - Child flag with `propagate: false` correctly masks ancestor's propagated flag of the same name.
2080
858
  - Dispatch: exhaustiveness guard on `subResult` switch in nested command resolution.
2081
859
  - Nested group help: `binName` built from full command path, not just root.
2082
- - Config loader: lowercase extensions in `buildExtensionList`/`buildLoaderMap` for case-insensitive
2083
- matching.
860
+ - Config loader: lowercase extensions in `buildExtensionList`/`buildLoaderMap` for case-insensitive matching.
2084
861
  - Empty-string env var fallbacks in runtime adapter treated as unset.
2085
- - `ProgressHandle.increment()` was emitting `progress:update` events indistinguishable from
2086
- `update()` calls. Now emits `progress:increment` with `delta` field.
2087
- - **Prompt number coercion** — `coercePromptValue` was missing NaN guard for number flags; now
2088
- handled by unified `coerceValue()`.
862
+ - `ProgressHandle.increment()` was emitting `progress:update` events indistinguishable from `update()` calls. Now emits `progress:increment` with `delta` field.
863
+ - **Prompt number coercion** — `coercePromptValue` was missing NaN guard for number flags; now handled by unified `coerceValue()`.
2089
864
 
2090
865
  ## [0.7.0] - 2026-02-10
2091
866
 
@@ -2093,25 +868,13 @@ sections that follow. Upgrading from 2.x is covered by the new
2093
868
 
2094
869
  #### Subcommand Nesting
2095
870
 
2096
- - **`CommandBuilder.command(sub)`** registers nested subcommands, building recursive command trees
2097
- of unlimited depth. Parent commands store children as type-erased `ErasedCommand` entries — the
2098
- parent doesn't need the child's generic types.
2099
- - **`group(name)`** factory as a semantic alias for `command()`. Communicates intent: groups
2100
- organise subcommands, leaf commands have actions. A group may also have its own `.action()` (e.g.
2101
- `git remote` lists remotes, `git remote add` dispatches to a child).
2102
- - **`flag.propagate()`** modifier marks a flag for automatic inheritance by all descendant commands.
2103
- Propagated flags are collected from the ancestor chain at dispatch time. Child commands override a
2104
- propagated flag by redeclaring the same name — child definition wins completely.
2105
- - **Recursive dispatch** in `CLIBuilder.execute()`. Walks argv segments matching command names at
2106
- each tree level. Handles hybrid commands (action + subcommands): subcommand match takes priority,
2107
- else falls through to the parent handler. Groups without handlers show help.
2108
- - **Nested help** — `formatHelp()` renders a "Commands:" section listing available subcommands for
2109
- group commands. Usage line adapts to show `<command>` placeholder when subcommands exist.
2110
- - **Nested completions** — bash and zsh generators traverse the full command tree depth. Propagated
2111
- flags included at each nesting level. Bash uses path-keyed case statements; zsh generates
2112
- per-group helper functions.
2113
- - **Scoped "did you mean?"** — typo suggestions search within the current command scope, not the
2114
- global command list. Help hint shows scoped path (e.g. `Run 'myapp db --help'`).
871
+ - **`CommandBuilder.command(sub)`** registers nested subcommands, building recursive command trees of unlimited depth. Parent commands store children as type-erased `ErasedCommand` entries — the parent doesn't need the child's generic types.
872
+ - **`group(name)`** factory as a semantic alias for `command()`. Communicates intent: groups organise subcommands, leaf commands have actions. A group may also have its own `.action()` (e.g. `git remote` lists remotes, `git remote add` dispatches to a child).
873
+ - **`flag.propagate()`** modifier marks a flag for automatic inheritance by all descendant commands. Propagated flags are collected from the ancestor chain at dispatch time. Child commands override a propagated flag by redeclaring the same name — child definition wins completely.
874
+ - **Recursive dispatch** in `CLIBuilder.execute()`. Walks argv segments matching command names at each tree level. Handles hybrid commands (action + subcommands): subcommand match takes priority, else falls through to the parent handler. Groups without handlers show help.
875
+ - **Nested help** — `formatHelp()` renders a "Commands:" section listing available subcommands for group commands. Usage line adapts to show `<command>` placeholder when subcommands exist.
876
+ - **Nested completions** — bash and zsh generators traverse the full command tree depth. Propagated flags included at each nesting level. Bash uses path-keyed case statements; zsh generates per-group helper functions.
877
+ - **Scoped "did you mean?"** — typo suggestions search within the current command scope, not the global command list. Help hint shows scoped path (e.g. `Run 'myapp db --help'`).
2115
878
 
2116
879
  ### Changed
2117
880
 
@@ -2120,8 +883,7 @@ sections that follow. Upgrading from 2.x is covered by the new
2120
883
  - `ErasedCommand` interface moved from `cli/index.ts` to `schema/command.ts` (shared location).
2121
884
  - `FlagSchema` extended with `propagate: boolean` (default `false`).
2122
885
  - `RunOptions` extended with `mergedSchema` internal field for propagated flag injection.
2123
- - Dispatch logic extracted to `cli/dispatch.ts` (~285 lines) and flag propagation to
2124
- `cli/propagate.ts` (~87 lines), reducing `cli/index.ts` by ~220 lines.
886
+ - Dispatch logic extracted to `cli/dispatch.ts` (~285 lines) and flag propagation to `cli/propagate.ts` (~87 lines), reducing `cli/index.ts` by ~220 lines.
2125
887
  - Test count: 1518 tests across 43 test files (up from 1300 in v0.6.0).
2126
888
 
2127
889
  ### Fixed
@@ -2135,31 +897,20 @@ sections that follow. Upgrading from 2.x is covered by the new
2135
897
 
2136
898
  #### Config File Discovery
2137
899
 
2138
- - **`CLIBuilder.config(appName)`** enables config file discovery with XDG-compliant search paths.
2139
- Searches `.{app}.json` and `{app}.config.json` in cwd, then `{configDir}/{app}/config.json`. JSON
2140
- loader built-in.
2141
- - **`--config <path>` global flag** overrides config file discovery path. Extracted from argv before
2142
- command dispatch.
2143
- - **`CLIBuilder.configLoader(loader)`** plugin hook for registering custom config format loaders
2144
- (YAML, TOML, etc.). `configFormat(extensions, parseFn)` convenience factory.
900
+ - **`CLIBuilder.config(appName)`** enables config file discovery with XDG-compliant search paths. Searches `.{app}.json` and `{app}.config.json` in cwd, then `{configDir}/{app}/config.json`. JSON loader built-in.
901
+ - **`--config <path>` global flag** overrides config file discovery path. Extracted from argv before command dispatch.
902
+ - **`CLIBuilder.configLoader(loader)`** plugin hook for registering custom config format loaders (YAML, TOML, etc.). `configFormat(extensions, parseFn)` convenience factory.
2145
903
 
2146
904
  #### Schema Additions
2147
905
 
2148
- - **`flag.custom(parseFn)`** — new flag kind accepting an arbitrary parse function with full
2149
- return-type inference from `parseFn`. Wired through parser coercion, all three resolve coercions
2150
- (env, config, prompt), and help formatter.
2151
- - **`.deprecated(message?)`** modifier on `FlagBuilder` and `ArgBuilder`. Emits structured
2152
- `DeprecationWarning` during resolution when a deprecated flag/arg is explicitly provided (CLI,
2153
- env, config, prompt — not for default fallthrough). Renders `[deprecated]` or
2154
- `[deprecated: <reason>]` in help text.
906
+ - **`flag.custom(parseFn)`** — new flag kind accepting an arbitrary parse function with full return-type inference from `parseFn`. Wired through parser coercion, all three resolve coercions (env, config, prompt), and help formatter.
907
+ - **`.deprecated(message?)`** modifier on `FlagBuilder` and `ArgBuilder`. Emits structured `DeprecationWarning` during resolution when a deprecated flag/arg is explicitly provided (CLI, env, config, prompt — not for default fallthrough). Renders `[deprecated]` or `[deprecated: <reason>]` in help text.
2155
908
 
2156
909
  #### RuntimeAdapter Extensions
2157
910
 
2158
- - **`readFile`** — async file read returning `null` for ENOENT, throws on other errors. Uses lazy
2159
- `import('node:fs/promises')`.
911
+ - **`readFile`** — async file read returning `null` for ENOENT, throws on other errors. Uses lazy `import('node:fs/promises')`.
2160
912
  - **`homedir`** — computed from env vars (`HOME`/`USERPROFILE`) + `platform`; avoids `node:os`.
2161
- - **`configDir`** — `XDG_CONFIG_HOME` on Unix, `APPDATA` on Windows; falls back to `~/.config` or
2162
- `~\AppData\Roaming`.
913
+ - **`configDir`** — `XDG_CONFIG_HOME` on Unix, `APPDATA` on Windows; falls back to `~/.config` or `~\AppData\Roaming`.
2163
914
 
2164
915
  ### Changed
2165
916
 
@@ -2170,8 +921,7 @@ sections that follow. Upgrading from 2.x is covered by the new
2170
921
  - `ArgSchema` extended with `deprecated: string | true | undefined`.
2171
922
  - `ResolveResult` extended with `warnings: readonly DeprecationWarning[]`.
2172
923
  - `CLISchema` extended with `configSettings` for config file discovery.
2173
- - `FlagParseFn<T>`, `DeprecationWarning`, `ConfigResult`, `FormatLoader`, `configFormat` exported
2174
- from public API.
924
+ - `FlagParseFn<T>`, `DeprecationWarning`, `ConfigResult`, `FormatLoader`, `configFormat` exported from public API.
2175
925
  - Test count: ~1300 tests (up from 1198 in v0.5.0).
2176
926
 
2177
927
  ## [0.5.0] - 2026-02-10
@@ -2180,32 +930,21 @@ sections that follow. Upgrading from 2.x is covered by the new
2180
930
 
2181
931
  #### Shell Completions
2182
932
 
2183
- - **Bash completion generator** — produces self-contained bash scripts with
2184
- `COMP_WORDS`/`COMP_CWORD` scanning, per-command case branches with flag and enum value
2185
- completions, and `complete -F` registration.
2186
- - **Zsh completion generator** — produces `#compdef` scripts with `_arguments` flag specs,
2187
- `_describe` subcommand lists, and enum value completions via `->state` dispatch.
2188
- - **`CLIBuilder.completions()`** adds a built-in `completions --shell <bash|zsh>` subcommand that
2189
- outputs a ready-to-eval completion script. In `--json` mode, emits `{ script }` JSON object.
2190
- Fish/PowerShell accepted in the enum with descriptive "not yet supported" errors.
933
+ - **Bash completion generator** — produces self-contained bash scripts with `COMP_WORDS`/`COMP_CWORD` scanning, per-command case branches with flag and enum value completions, and `complete -F` registration.
934
+ - **Zsh completion generator** — produces `#compdef` scripts with `_arguments` flag specs, `_describe` subcommand lists, and enum value completions via `->state` dispatch.
935
+ - **`CLIBuilder.completions()`** adds a built-in `completions --shell <bash|zsh>` subcommand that outputs a ready-to-eval completion script. In `--json` mode, emits `{ script }` JSON object. Fish/PowerShell accepted in the enum with descriptive "not yet supported" errors.
2191
936
 
2192
937
  #### Runtime Portability
2193
938
 
2194
- - **`detectRuntime()`** via `globalThis` feature detection — identifies Node, Bun, Deno, or unknown.
2195
- Exported `Runtime` type and `RUNTIMES` constant.
2196
- - **`createAdapter()`** auto-detecting adapter factory — calls `detectRuntime()` and returns the
2197
- appropriate `RuntimeAdapter`. `CLIBuilder.run()` uses it as default when no adapter is provided.
2198
- - **Bun adapter** implementing `RuntimeAdapter` by delegating to the Node adapter (Bun's
2199
- Node-compatible APIs).
939
+ - **`detectRuntime()`** via `globalThis` feature detection — identifies Node, Bun, Deno, or unknown. Exported `Runtime` type and `RUNTIMES` constant.
940
+ - **`createAdapter()`** auto-detecting adapter factory — calls `detectRuntime()` and returns the appropriate `RuntimeAdapter`. `CLIBuilder.run()` uses it as default when no adapter is provided.
941
+ - **Bun adapter** implementing `RuntimeAdapter` by delegating to the Node adapter (Bun's Node-compatible APIs).
2200
942
 
2201
943
  ### Fixed
2202
944
 
2203
- - Completion: cross-command enum collision — `collectEnumCases()` scoped per-command to prevent enum
2204
- values from one command leaking into another's completions.
2205
- - Completion: shell injection safety — `quoteShellArg()` escapes `schema.name` and enum values in
2206
- generated scripts.
2207
- - Completion: conditional `--version` — bash generator omits `--version` from completions when
2208
- `schema.version` is undefined, matching zsh behavior.
945
+ - Completion: cross-command enum collision — `collectEnumCases()` scoped per-command to prevent enum values from one command leaking into another's completions.
946
+ - Completion: shell injection safety — `quoteShellArg()` escapes `schema.name` and enum values in generated scripts.
947
+ - Completion: conditional `--version` — bash generator omits `--version` from completions when `schema.version` is undefined, matching zsh behavior.
2209
948
  - CLI: `--json` mode completions output `{ script }` JSON instead of raw script text.
2210
949
  - CLI: guard against double `.completions()` call.
2211
950
  - Runtime: `NodeProcess` type exported from main barrel.
@@ -2223,47 +962,26 @@ sections that follow. Upgrading from 2.x is covered by the new
2223
962
 
2224
963
  #### Typed Middleware
2225
964
 
2226
- - **`middleware<Output>(handler)`** factory creating phantom-branded `Middleware<Output>` values.
2227
- Handler receives `{ args, flags, ctx, out, next }` — call `next(additions)` to continue the chain
2228
- with typed context, omit `next()` to short-circuit (auth guards), or await `next()` for
2229
- wrap-around patterns (timing, try/catch).
2230
- - **`CommandBuilder.middleware(m)`** registers middleware in execution order. Each call widens the
2231
- context type parameter `C` via `WidenContext<C, Output>` intersection — `Record<string, never>`
2232
- (the default) is replaced entirely on the first call, preventing `never` collapse. Adding
2233
- middleware drops the current handler (type signature changed).
2234
- - **Context type parameter `C`** on `CommandBuilder<F, A, C>`, `ActionParams<F, A, C>`, and
2235
- `ActionHandler<F, A, C>`. `ctx` in the action handler is `Readonly<C>` — property access is a type
2236
- error until middleware extends it.
2237
- - **Middleware chain execution** (`executeWithMiddleware`) in testkit. Builds a continuation chain
2238
- from back to front; context accumulates via `{ ...ctx, ...additions }` at each step. Replaces the
2239
- former `invokeHandler` bridge.
965
+ - **`middleware<Output>(handler)`** factory creating phantom-branded `Middleware<Output>` values. Handler receives `{ args, flags, ctx, out, next }` — call `next(additions)` to continue the chain with typed context, omit `next()` to short-circuit (auth guards), or await `next()` for wrap-around patterns (timing, try/catch).
966
+ - **`CommandBuilder.middleware(m)`** registers middleware in execution order. Each call widens the context type parameter `C` via `WidenContext<C, Output>` intersection — `Record<string, never>` (the default) is replaced entirely on the first call, preventing `never` collapse. Adding middleware drops the current handler (type signature changed).
967
+ - **Context type parameter `C`** on `CommandBuilder<F, A, C>`, `ActionParams<F, A, C>`, and `ActionHandler<F, A, C>`. `ctx` in the action handler is `Readonly<C>` — property access is a type error until middleware extends it.
968
+ - **Middleware chain execution** (`executeWithMiddleware`) in testkit. Builds a continuation chain from back to front; context accumulates via `{ ...ctx, ...additions }` at each step. Replaces the former `invokeHandler` bridge.
2240
969
 
2241
970
  #### Structured Output
2242
971
 
2243
- - **`out.json(value)`** emits `JSON.stringify(value)` to stdout. Always targets stdout regardless of
2244
- JSON mode. Handlers should prefer this over `out.log(JSON.stringify(...))`.
2245
- - **`out.table(rows, columns?)`** renders tabular data. In JSON mode: emits rows as JSON array. In
2246
- text mode: pretty-prints aligned columns with headers (auto-inferred from first row when `columns`
2247
- omitted). `TableColumn<T>` descriptor type with `key` and optional `header`.
2248
- - **`out.jsonMode`** and **`out.isTTY`** readonly properties on `Out` interface. Handlers check
2249
- these to skip decorative output (spinners, ANSI codes) when machine-readable output is expected or
2250
- stdout is piped.
2251
- - **`--json` global flag** detection in `CLIBuilder.execute()`. Strips `--json` from argv before
2252
- command dispatch. CLI-level dispatch errors (unknown command, no action) rendered as JSON when
2253
- active.
2254
- - **`jsonMode`** and **`isTTY`** options on `RunOptions`, `CLIRunOptions`, and `OutputOptions`.
2255
- `CLIBuilder.run()` auto-sources `isTTY` from `adapter.isTTY`.
972
+ - **`out.json(value)`** emits `JSON.stringify(value)` to stdout. Always targets stdout regardless of JSON mode. Handlers should prefer this over `out.log(JSON.stringify(...))`.
973
+ - **`out.table(rows, columns?)`** renders tabular data. In JSON mode: emits rows as JSON array. In text mode: pretty-prints aligned columns with headers (auto-inferred from first row when `columns` omitted). `TableColumn<T>` descriptor type with `key` and optional `header`.
974
+ - **`out.jsonMode`** and **`out.isTTY`** readonly properties on `Out` interface. Handlers check these to skip decorative output (spinners, ANSI codes) when machine-readable output is expected or stdout is piped.
975
+ - **`--json` global flag** detection in `CLIBuilder.execute()`. Strips `--json` from argv before command dispatch. CLI-level dispatch errors (unknown command, no action) rendered as JSON when active.
976
+ - **`jsonMode`** and **`isTTY`** options on `RunOptions`, `CLIRunOptions`, and `OutputOptions`. `CLIBuilder.run()` auto-sources `isTTY` from `adapter.isTTY`.
2256
977
 
2257
978
  ### Changed
2258
979
 
2259
- - `ActionParams<F, A>` → `ActionParams<F, A, C>` with `ctx: Readonly<C>` (was
2260
- `Readonly<Record<string, unknown>>`).
2261
- - `CommandBuilder` carries third type parameter `C` (default `Record<string, never>`). All
2262
- metadata/builder methods preserve `C` in return type.
980
+ - `ActionParams<F, A>` → `ActionParams<F, A, C>` with `ctx: Readonly<C>` (was `Readonly<Record<string, unknown>>`).
981
+ - `CommandBuilder` carries third type parameter `C` (default `Record<string, never>`). All metadata/builder methods preserve `C` in return type.
2263
982
  - `CommandSchema.middleware` added as `readonly ErasedMiddlewareHandler[]`.
2264
983
  - `Out` interface extended with `json()`, `table()`, `jsonMode`, and `isTTY`.
2265
- - `OutputChannel` constructor accepts `isTTY` and `jsonMode` from resolved options. `log`/`info`
2266
- redirect to stderr writer in JSON mode.
984
+ - `OutputChannel` constructor accepts `isTTY` and `jsonMode` from resolved options. `log`/`info` redirect to stderr writer in JSON mode.
2267
985
  - `runCommand` and `CLIBuilder.execute` error paths render JSON when `jsonMode` active.
2268
986
  - `createCaptureOutput` accepts `jsonMode` and `isTTY` options.
2269
987
  - Test count: 1010 tests across 31 test files (up from 797 in v0.3.0).
@@ -2274,47 +992,22 @@ sections that follow. Upgrading from 2.x is covered by the new
2274
992
 
2275
993
  #### Interactive Prompting
2276
994
 
2277
- - **Prompt type definitions** (`PromptConfig`) as a discriminated union with four kinds: `confirm`,
2278
- `input`, `select`, `multiselect`. Each kind has specialized fields — `InputPromptConfig` supports
2279
- `placeholder` and `validate`, select/multiselect support `SelectChoice` arrays with optional
2280
- labels and descriptions.
2281
- - **`FlagBuilder.prompt(config)`** metadata modifier for declaring prompt configuration on flags,
2282
- following the same immutable builder pattern as `.env()` and `.config()`.
2283
- - **Prompt engine interface** (`PromptEngine`) with `promptOne(config) → Promise<PromptResult>` as a
2284
- pluggable renderer seam. `ResolvedPromptConfig` variant guarantees non-empty choices for
2285
- select/multiselect after merging from `FlagSchema.enumValues`.
2286
- - **Built-in terminal prompter** (`createTerminalPrompter(read, write)`) with line-based I/O for
2287
- confirm (y/n), input (with validation and placeholder), select (numbered list), and multiselect
2288
- (comma-separated numbers with min/max). All prompts have a `MAX_RETRIES = 10` safety valve.
2289
- - **Test prompter** (`createTestPrompter(answers, options?)`) with queue-based answers for
2290
- deterministic testing. `PROMPT_CANCEL` symbol sentinel for simulating cancellation.
2291
- `onExhausted: 'throw' | 'cancel'` controls behavior when answer queue is empty.
2292
- - **Prompt resolution in the resolver**. Resolution chain expanded from CLI > env > config > default
2293
- to CLI > env > config > **prompt** > default. Flags with prompt config and no value from prior
2294
- sources trigger `prompter.promptOne()`. Cancelled prompts fall through to default/required.
2295
- Non-interactive mode (no prompter) skips prompts entirely.
2296
- - **`ReadFn`** (`() => Promise<string | null>`) as the minimal stdin abstraction. `null` signals
2297
- EOF/cancel. `RuntimeAdapter` extended with `stdin: ReadFn` and `stdinIsTTY: boolean`.
2298
- - **Node adapter stdin** wraps `process.stdin` via dynamic `import('node:readline')` with lazy
2299
- per-call readline interfaces. Minimal `node:readline` type declarations in `node-builtins.d.ts`
2300
- avoid `@types/node` dependency.
2301
- - **Automatic prompt gating** in `CLIBuilder.run()`: when `stdinIsTTY=true` and no explicit prompter
2302
- provided, auto-creates `createTerminalPrompter(adapter.stdin, adapter.stderr)`. Prompt output
2303
- routed to stderr to avoid interfering with piped stdout.
2304
- - **Command-level `.interactive(resolver)`** API on `CommandBuilder`. Resolver receives partially
2305
- resolved flags (after CLI/env/config), returns `Record<string, PromptConfig | false | undefined>`
2306
- controlling which flags get prompted. Truthy `PromptConfig` overrides per-flag prompt; `false`
2307
- explicitly suppresses; absent falls back to per-flag `.prompt()` config.
2308
- - **Testkit `answers` convenience** on `RunOptions`. Accepts `Record<string, TestAnswer>` to
2309
- auto-create a test prompter. `prompter` field also available for explicit engine injection.
2310
- `CLIRunOptions` mirrors both fields.
995
+ - **Prompt type definitions** (`PromptConfig`) as a discriminated union with four kinds: `confirm`, `input`, `select`, `multiselect`. Each kind has specialized fields — `InputPromptConfig` supports `placeholder` and `validate`, select/multiselect support `SelectChoice` arrays with optional labels and descriptions.
996
+ - **`FlagBuilder.prompt(config)`** metadata modifier for declaring prompt configuration on flags, following the same immutable builder pattern as `.env()` and `.config()`.
997
+ - **Prompt engine interface** (`PromptEngine`) with `promptOne(config) → Promise<PromptResult>` as a pluggable renderer seam. `ResolvedPromptConfig` variant guarantees non-empty choices for select/multiselect after merging from `FlagSchema.enumValues`.
998
+ - **Built-in terminal prompter** (`createTerminalPrompter(read, write)`) with line-based I/O for confirm (y/n), input (with validation and placeholder), select (numbered list), and multiselect (comma-separated numbers with min/max). All prompts have a `MAX_RETRIES = 10` safety valve.
999
+ - **Test prompter** (`createTestPrompter(answers, options?)`) with queue-based answers for deterministic testing. `PROMPT_CANCEL` symbol sentinel for simulating cancellation. `onExhausted: 'throw' | 'cancel'` controls behavior when answer queue is empty.
1000
+ - **Prompt resolution in the resolver**. Resolution chain expanded from CLI > env > config > default to CLI > env > config > **prompt** > default. Flags with prompt config and no value from prior sources trigger `prompter.promptOne()`. Cancelled prompts fall through to default/required. Non-interactive mode (no prompter) skips prompts entirely.
1001
+ - **`ReadFn`** (`() => Promise<string | null>`) as the minimal stdin abstraction. `null` signals EOF/cancel. `RuntimeAdapter` extended with `stdin: ReadFn` and `stdinIsTTY: boolean`.
1002
+ - **Node adapter stdin** wraps `process.stdin` via dynamic `import('node:readline')` with lazy per-call readline interfaces. Minimal `node:readline` type declarations in `node-builtins.d.ts` avoid `@types/node` dependency.
1003
+ - **Automatic prompt gating** in `CLIBuilder.run()`: when `stdinIsTTY=true` and no explicit prompter provided, auto-creates `createTerminalPrompter(adapter.stdin, adapter.stderr)`. Prompt output routed to stderr to avoid interfering with piped stdout.
1004
+ - **Command-level `.interactive(resolver)`** API on `CommandBuilder`. Resolver receives partially resolved flags (after CLI/env/config), returns `Record<string, PromptConfig | false | undefined>` controlling which flags get prompted. Truthy `PromptConfig` overrides per-flag prompt; `false` explicitly suppresses; absent falls back to per-flag `.prompt()` config.
1005
+ - **Testkit `answers` convenience** on `RunOptions`. Accepts `Record<string, TestAnswer>` to auto-create a test prompter. `prompter` field also available for explicit engine injection. `CLIRunOptions` mirrors both fields.
2311
1006
 
2312
1007
  ### Changed
2313
1008
 
2314
- - `resolve()` is now **async** (`Promise<ResolveResult>`). All callers (`runCommand`,
2315
- `CLIBuilder.execute`, `CLIBuilder.run`) updated to await.
2316
- - Resolution chain expanded from CLI > env > config > default to CLI > env > config > prompt >
2317
- default.
1009
+ - `resolve()` is now **async** (`Promise<ResolveResult>`). All callers (`runCommand`, `CLIBuilder.execute`, `CLIBuilder.run`) updated to await.
1010
+ - Resolution chain expanded from CLI > env > config > default to CLI > env > config > prompt > default.
2318
1011
  - `ResolveOptions` extended with optional `prompter: PromptEngine` field.
2319
1012
  - `RunOptions` extended with `prompter` and `answers` fields.
2320
1013
  - `CLIRunOptions` extended with `prompter` and `answers` fields.
@@ -2328,24 +1021,11 @@ sections that follow. Upgrading from 2.x is covered by the new
2328
1021
 
2329
1022
  #### Resolution Chain
2330
1023
 
2331
- - **Environment variable resolution** in the resolver. Flags with `.env('VAR')` now resolve from the
2332
- `env` record after CLI and before default. String, number, boolean (lenient:
2333
- `true/false/1/0/yes/no`), enum, and array (comma-separated) coercion. Invalid env values produce
2334
- `ValidationError` with `TYPE_MISMATCH` or `INVALID_ENUM` codes.
2335
- - **Config object resolution** in the resolver. Flags with `.config('dotted.path')` resolve from a
2336
- plain `Record<string, unknown>` after env and before default. `resolveConfigPath()` walks nested
2337
- objects segment-by-segment. Config values may already be typed from JSON — coercion is lenient for
2338
- matching types. Full chain: CLI > env > config > default.
2339
- - **Resolution source annotations** in help text. Flags with env or config declarations now display
2340
- `[env: VAR]` and `[config: path]` in `formatHelp()` output, ordered between description text and
2341
- presence indicators.
2342
- - **Actionable required-flag error hints**. When a required flag is missing after full resolution,
2343
- `ValidationError.suggest` lists all configured sources (e.g. "Provide --region, set DEPLOY_REGION,
2344
- or add deploy.region to config"). CI-friendly error messages with `envVar`/`configPath` in
2345
- details.
2346
- - **Env/config wiring through testkit and CLI builder**. `RunOptions` and `CLIRunOptions` accept
2347
- `env` and `config` fields. `runCommand()` threads them into `resolve()`. `CLIBuilder.run()`
2348
- auto-sources `adapter.env` when no explicit env option is provided.
1024
+ - **Environment variable resolution** in the resolver. Flags with `.env('VAR')` now resolve from the `env` record after CLI and before default. String, number, boolean (lenient: `true/false/1/0/yes/no`), enum, and array (comma-separated) coercion. Invalid env values produce `ValidationError` with `TYPE_MISMATCH` or `INVALID_ENUM` codes.
1025
+ - **Config object resolution** in the resolver. Flags with `.config('dotted.path')` resolve from a plain `Record<string, unknown>` after env and before default. `resolveConfigPath()` walks nested objects segment-by-segment. Config values may already be typed from JSON — coercion is lenient for matching types. Full chain: CLI > env > config > default.
1026
+ - **Resolution source annotations** in help text. Flags with env or config declarations now display `[env: VAR]` and `[config: path]` in `formatHelp()` output, ordered between description text and presence indicators.
1027
+ - **Actionable required-flag error hints**. When a required flag is missing after full resolution, `ValidationError.suggest` lists all configured sources (e.g. "Provide --region, set DEPLOY_REGION, or add deploy.region to config"). CI-friendly error messages with `envVar`/`configPath` in details.
1028
+ - **Env/config wiring through testkit and CLI builder**. `RunOptions` and `CLIRunOptions` accept `env` and `config` fields. `runCommand()` threads them into `resolve()`. `CLIBuilder.run()` auto-sources `adapter.env` when no explicit env option is provided.
2349
1029
 
2350
1030
  ### Changed
2351
1031
 
@@ -2359,43 +1039,23 @@ sections that follow. Upgrading from 2.x is covered by the new
2359
1039
 
2360
1040
  #### Core Framework
2361
1041
 
2362
- - **Structured errors** (`CLIError`, `ParseError`, `ValidationError`) with stable error codes,
2363
- `toJSON()` serialization, type guard functions (`isCLIError`, `isParseError`,
2364
- `isValidationError`), and actionable `suggest` hints.
2365
- - **Flag builder** (`flag`) with full type inference for boolean, string, number, enum, and array
2366
- kinds. Supports `.alias()`, `.default()`, `.required()`, `.describe()`, `.hidden()`,
2367
- `.deprecated()`, `.env()`, and `.config()` declarations.
2368
- - **Arg builder** (`arg`) with type inference for string, number, custom parse functions, and
2369
- variadic args. Supports `.default()`, `.required()`, `.optional()`, and `.describe()`.
2370
- - **Command builder** (`command`) with `.flag()`, `.arg()`, `.description()`, `.example()`,
2371
- `.hidden()`, `.alias()`, and `.action()`. Accumulates phantom types so handler receives fully
2372
- inferred `flags` and `args`.
2373
- - **Argv parser** with tokenizer (`tokenize`) and schema-aware parser (`parse`). Handles long/short
2374
- flags, `=` syntax, boolean negation (`--no-*`), flag stacking (`-abc`), `--` separator, and type
2375
- coercion against the schema.
2376
- - **Resolution chain** (CLI parsed value → schema default). Validates all required flags/args,
2377
- aggregates multiple errors into a single throw, and provides per-field suggestions.
2378
- - **Auto-generated help text** (`formatHelp`) from command schema, including usage line,
2379
- description, positional args, flags with types/defaults/aliases, examples section, and subcommand
2380
- listing.
2381
- - **Output channel** (`createOutput`) with `log`/`info`/`warn`/`error` methods, `WriteFn`
2382
- abstraction, verbosity levels (normal/quiet), and TTY detection. Includes `createCaptureOutput()`
2383
- test helper.
2384
- - **Test harness** (`runCommand`) for running commands as pure functions with injected argv, env,
2385
- and captured output. Returns `RunResult` with `exitCode`, `stdout`, `stderr`, and `error`.
2386
- - **CLI builder** (`cli`) with `.command()` registration, `.version()`, subcommand dispatch,
2387
- automatic `--help`/`--version` flag handling, and unknown-command error with suggestions.
2388
- - **RuntimeAdapter interface** defining the platform abstraction boundary (argv, env, cwd,
2389
- stdout/stderr, isTTY, exit). Includes `createTestAdapter()` for injectable test stubs and
2390
- `ExitError` for testable process exits.
2391
- - **Node.js adapter** (`createNodeAdapter`) wiring `process.argv`, `process.env`, `process.cwd()`,
2392
- `process.stdout`/`stderr`, and TTY detection.
1042
+ - **Structured errors** (`CLIError`, `ParseError`, `ValidationError`) with stable error codes, `toJSON()` serialization, type guard functions (`isCLIError`, `isParseError`, `isValidationError`), and actionable `suggest` hints.
1043
+ - **Flag builder** (`flag`) with full type inference for boolean, string, number, enum, and array kinds. Supports `.alias()`, `.default()`, `.required()`, `.describe()`, `.hidden()`, `.deprecated()`, `.env()`, and `.config()` declarations.
1044
+ - **Arg builder** (`arg`) with type inference for string, number, custom parse functions, and variadic args. Supports `.default()`, `.required()`, `.optional()`, and `.describe()`.
1045
+ - **Command builder** (`command`) with `.flag()`, `.arg()`, `.description()`, `.example()`, `.hidden()`, `.alias()`, and `.action()`. Accumulates phantom types so handler receives fully inferred `flags` and `args`.
1046
+ - **Argv parser** with tokenizer (`tokenize`) and schema-aware parser (`parse`). Handles long/short flags, `=` syntax, boolean negation (`--no-*`), flag stacking (`-abc`), `--` separator, and type coercion against the schema.
1047
+ - **Resolution chain** (CLI parsed value → schema default). Validates all required flags/args, aggregates multiple errors into a single throw, and provides per-field suggestions.
1048
+ - **Auto-generated help text** (`formatHelp`) from command schema, including usage line, description, positional args, flags with types/defaults/aliases, examples section, and subcommand listing.
1049
+ - **Output channel** (`createOutput`) with `log`/`info`/`warn`/`error` methods, `WriteFn` abstraction, verbosity levels (normal/quiet), and TTY detection. Includes `createCaptureOutput()` test helper.
1050
+ - **Test harness** (`runCommand`) for running commands as pure functions with injected argv, env, and captured output. Returns `RunResult` with `exitCode`, `stdout`, `stderr`, and `error`.
1051
+ - **CLI builder** (`cli`) with `.command()` registration, `.version()`, subcommand dispatch, automatic `--help`/`--version` flag handling, and unknown-command error with suggestions.
1052
+ - **RuntimeAdapter interface** defining the platform abstraction boundary (argv, env, cwd, stdout/stderr, isTTY, exit). Includes `createTestAdapter()` for injectable test stubs and `ExitError` for testable process exits.
1053
+ - **Node.js adapter** (`createNodeAdapter`) wiring `process.argv`, `process.env`, `process.cwd()`, `process.stdout`/`stderr`, and TTY detection.
2393
1054
  - Stub files for Bun adapter, Deno adapter, runtime auto-detection, and shell completion generation.
2394
1055
 
2395
1056
  #### Project Infrastructure
2396
1057
 
2397
- - Project scaffold with `src/` structure, TypeScript strict config, and ESM + CJS dual build via
2398
- tsdown.
1058
+ - Project scaffold with `src/` structure, TypeScript strict config, and ESM + CJS dual build via tsdown.
2399
1059
  - Vitest test framework with 464 passing tests across 12 test files.
2400
1060
  - Biome linter and dprint formatter configuration.
2401
1061
  - `@vitest/coverage-v8` for test coverage reporting.
@@ -2405,7 +1065,8 @@ sections that follow. Upgrading from 2.x is covered by the new
2405
1065
  - MIT License.
2406
1066
  - Markdownlint configuration.
2407
1067
 
2408
- [Unreleased]: https://github.com/kjanat/dreamcli/compare/v4.0.0-rc.2...HEAD
1068
+ [Unreleased]: https://github.com/kjanat/dreamcli/compare/v4.0.0-rc.3...HEAD
1069
+ [4.0.0-rc.3]: https://github.com/kjanat/dreamcli/compare/v4.0.0-rc.2...v4.0.0-rc.3
2409
1070
  [4.0.0-rc.2]: https://github.com/kjanat/dreamcli/compare/v4.0.0-rc.1...v4.0.0-rc.2
2410
1071
  [4.0.0-rc.1]: https://github.com/kjanat/dreamcli/compare/v3.0.1...v4.0.0-rc.1
2411
1072
  [3.0.1]: https://github.com/kjanat/dreamcli/compare/v3.0.0...v3.0.1
@@ -2451,3 +1112,5 @@ sections that follow. Upgrading from 2.x is covered by the new
2451
1112
  [0.3.0]: https://github.com/kjanat/dreamcli/compare/v0.2.0...v0.3.0
2452
1113
  [0.2.0]: https://github.com/kjanat/dreamcli/compare/v0.1.0...v0.2.0
2453
1114
  [0.1.0]: https://github.com/kjanat/dreamcli/releases/tag/v0.1.0
1115
+
1116
+ <!-- markdownlint-disable-file line-length no-duplicate-heading no-bare-urls -->