@kjanat/dreamcli 0.0.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (205) hide show
  1. package/CHANGELOG.md +706 -0
  2. package/LICENSE +22 -0
  3. package/README.md +502 -0
  4. package/dist/core/cli/dispatch.d.mts +85 -0
  5. package/dist/core/cli/dispatch.mjs +1 -0
  6. package/dist/core/cli/index.d.mts +418 -0
  7. package/dist/core/cli/index.mjs +1 -0
  8. package/dist/core/cli/planner.d.mts +143 -0
  9. package/dist/core/cli/planner.mjs +1 -0
  10. package/dist/core/cli/plugin.d.mts +94 -0
  11. package/dist/core/cli/plugin.mjs +1 -0
  12. package/dist/core/cli/propagate.d.mts +39 -0
  13. package/dist/core/cli/propagate.mjs +1 -0
  14. package/dist/core/cli/root-help.d.mts +28 -0
  15. package/dist/core/cli/root-help.mjs +7 -0
  16. package/dist/core/cli/root-surface.d.mts +42 -0
  17. package/dist/core/cli/root-surface.mjs +1 -0
  18. package/dist/core/cli/runtime-preflight.d.mts +149 -0
  19. package/dist/core/cli/runtime-preflight.mjs +1 -0
  20. package/dist/core/completion/index.d.mts +46 -0
  21. package/dist/core/completion/index.mjs +1 -0
  22. package/dist/core/completion/shells/bash.d.mts +24 -0
  23. package/dist/core/completion/shells/bash.mjs +3 -0
  24. package/dist/core/completion/shells/fish.d.mts +20 -0
  25. package/dist/core/completion/shells/fish.mjs +2 -0
  26. package/dist/core/completion/shells/powershell.d.mts +14 -0
  27. package/dist/core/completion/shells/powershell.mjs +2 -0
  28. package/dist/core/completion/shells/shared.d.mts +139 -0
  29. package/dist/core/completion/shells/shared.mjs +1 -0
  30. package/dist/core/completion/shells/zsh.d.mts +24 -0
  31. package/dist/core/completion/shells/zsh.mjs +2 -0
  32. package/dist/core/config/index.d.mts +161 -0
  33. package/dist/core/config/index.mjs +1 -0
  34. package/dist/core/config/package-json.d.mts +68 -0
  35. package/dist/core/config/package-json.mjs +1 -0
  36. package/dist/core/errors/index.d.mts +126 -0
  37. package/dist/core/errors/index.mjs +1 -0
  38. package/dist/core/execution/index.d.mts +49 -0
  39. package/dist/core/execution/index.mjs +1 -0
  40. package/dist/core/help/index.d.mts +49 -0
  41. package/dist/core/help/index.mjs +8 -0
  42. package/dist/core/json-schema/index.d.mts +109 -0
  43. package/dist/core/json-schema/index.mjs +55 -0
  44. package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
  45. package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
  46. package/dist/core/output/activity.d.mts +194 -0
  47. package/dist/core/output/activity.mjs +1 -0
  48. package/dist/core/output/contracts.d.mts +88 -0
  49. package/dist/core/output/contracts.mjs +1 -0
  50. package/dist/core/output/display-value.d.mts +19 -0
  51. package/dist/core/output/display-value.mjs +1 -0
  52. package/dist/core/output/index.d.mts +280 -0
  53. package/dist/core/output/index.mjs +2 -0
  54. package/dist/core/output/renderers.d.mts +46 -0
  55. package/dist/core/output/renderers.mjs +1 -0
  56. package/dist/core/output/writer.d.mts +40 -0
  57. package/dist/core/output/writer.mjs +1 -0
  58. package/dist/core/parse/index.d.mts +79 -0
  59. package/dist/core/parse/index.mjs +1 -0
  60. package/dist/core/prompt/index.d.mts +205 -0
  61. package/dist/core/prompt/index.mjs +6 -0
  62. package/dist/core/resolve/args.d.mts +8 -0
  63. package/dist/core/resolve/args.mjs +1 -0
  64. package/dist/core/resolve/coerce.d.mts +22 -0
  65. package/dist/core/resolve/coerce.mjs +1 -0
  66. package/dist/core/resolve/config.d.mts +10 -0
  67. package/dist/core/resolve/config.mjs +1 -0
  68. package/dist/core/resolve/contracts.d.mts +112 -0
  69. package/dist/core/resolve/errors.d.mts +11 -0
  70. package/dist/core/resolve/errors.mjs +2 -0
  71. package/dist/core/resolve/flags.d.mts +10 -0
  72. package/dist/core/resolve/flags.mjs +1 -0
  73. package/dist/core/resolve/index.d.mts +42 -0
  74. package/dist/core/resolve/index.mjs +1 -0
  75. package/dist/core/resolve/property.d.mts +47 -0
  76. package/dist/core/resolve/property.mjs +1 -0
  77. package/dist/core/schema/activity.d.mts +169 -0
  78. package/dist/core/schema/arg.d.mts +559 -0
  79. package/dist/core/schema/arg.mjs +1 -0
  80. package/dist/core/schema/command.d.mts +960 -0
  81. package/dist/core/schema/command.mjs +1 -0
  82. package/dist/core/schema/flag.d.mts +491 -0
  83. package/dist/core/schema/flag.mjs +1 -0
  84. package/dist/core/schema/index.d.mts +8 -0
  85. package/dist/core/schema/middleware.d.mts +122 -0
  86. package/dist/core/schema/middleware.mjs +1 -0
  87. package/dist/core/schema/prompt.d.mts +117 -0
  88. package/dist/core/schema/run.d.mts +171 -0
  89. package/dist/core/schema-dsl/runtime.d.mts +144 -0
  90. package/dist/core/schema-dsl/runtime.mjs +2 -0
  91. package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
  92. package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
  93. package/dist/core/testkit/index.d.mts +54 -0
  94. package/dist/core/testkit/index.mjs +1 -0
  95. package/dist/index.d.mts +28 -0
  96. package/dist/index.mjs +1 -0
  97. package/dist/runtime/adapter.d.mts +212 -0
  98. package/dist/runtime/adapter.mjs +1 -0
  99. package/dist/runtime/auto.d.mts +26 -0
  100. package/dist/runtime/auto.mjs +1 -0
  101. package/dist/runtime/bun.d.mts +28 -0
  102. package/dist/runtime/bun.mjs +1 -0
  103. package/dist/runtime/deno.d.mts +76 -0
  104. package/dist/runtime/deno.mjs +2 -0
  105. package/dist/runtime/detect.d.mts +86 -0
  106. package/dist/runtime/detect.mjs +1 -0
  107. package/dist/runtime/index.d.mts +7 -0
  108. package/dist/runtime/node.d.mts +65 -0
  109. package/dist/runtime/node.mjs +2 -0
  110. package/dist/runtime/paths.d.mts +31 -0
  111. package/dist/runtime/paths.mjs +1 -0
  112. package/dist/runtime/support.d.mts +42 -0
  113. package/dist/runtime/support.mjs +1 -0
  114. package/dist/runtime.d.mts +7 -0
  115. package/dist/runtime.mjs +1 -0
  116. package/dist/testkit.d.mts +6 -0
  117. package/dist/testkit.mjs +1 -0
  118. package/dist/version.d.mts +16 -0
  119. package/dist/version.mjs +1 -0
  120. package/dreamcli.schema.json +338 -0
  121. package/examples/basic.ts +33 -0
  122. package/examples/gh/package.json +44 -0
  123. package/examples/gh/src/commands/auth.ts +66 -0
  124. package/examples/gh/src/commands/issue.ts +120 -0
  125. package/examples/gh/src/commands/pr.ts +125 -0
  126. package/examples/gh/src/data/issues.yaml +5 -0
  127. package/examples/gh/src/data/issues.yaml.d.ts +17 -0
  128. package/examples/gh/src/data/pull-requests.yaml +7 -0
  129. package/examples/gh/src/data/pull-requests.yaml.d.ts +18 -0
  130. package/examples/gh/src/docs.ts +11 -0
  131. package/examples/gh/src/lib/auth.ts +37 -0
  132. package/examples/gh/src/lib/utils.ts +17 -0
  133. package/examples/gh/src/main.test.ts +307 -0
  134. package/examples/gh/src/main.ts +40 -0
  135. package/examples/interactive.ts +66 -0
  136. package/examples/json-mode.ts +91 -0
  137. package/examples/middleware.ts +71 -0
  138. package/examples/multi-command.ts +66 -0
  139. package/examples/spinner-progress.ts +49 -0
  140. package/examples/testing.ts +147 -0
  141. package/package.json +149 -2
  142. package/src/core/cli/dispatch.ts +286 -0
  143. package/src/core/cli/index.ts +978 -0
  144. package/src/core/cli/planner.ts +413 -0
  145. package/src/core/cli/plugin.ts +117 -0
  146. package/src/core/cli/propagate.ts +97 -0
  147. package/src/core/cli/root-help.ts +269 -0
  148. package/src/core/cli/root-surface.ts +74 -0
  149. package/src/core/cli/runtime-preflight.ts +409 -0
  150. package/src/core/completion/index.ts +88 -0
  151. package/src/core/completion/shells/bash.ts +459 -0
  152. package/src/core/completion/shells/fish.ts +259 -0
  153. package/src/core/completion/shells/powershell.ts +405 -0
  154. package/src/core/completion/shells/shared.ts +283 -0
  155. package/src/core/completion/shells/zsh.ts +381 -0
  156. package/src/core/config/index.ts +407 -0
  157. package/src/core/config/package-json.ts +220 -0
  158. package/src/core/errors/index.ts +193 -0
  159. package/src/core/execution/index.ts +270 -0
  160. package/src/core/help/index.ts +557 -0
  161. package/src/core/json-schema/index.ts +891 -0
  162. package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
  163. package/src/core/output/activity.ts +568 -0
  164. package/src/core/output/contracts.ts +194 -0
  165. package/src/core/output/display-value.ts +48 -0
  166. package/src/core/output/index.ts +669 -0
  167. package/src/core/output/renderers.ts +125 -0
  168. package/src/core/output/writer.ts +46 -0
  169. package/src/core/parse/index.ts +661 -0
  170. package/src/core/prompt/index.ts +583 -0
  171. package/src/core/resolve/args.ts +144 -0
  172. package/src/core/resolve/coerce.ts +432 -0
  173. package/src/core/resolve/config.ts +26 -0
  174. package/src/core/resolve/contracts.ts +135 -0
  175. package/src/core/resolve/errors.ts +227 -0
  176. package/src/core/resolve/flags.ts +205 -0
  177. package/src/core/resolve/index.ts +108 -0
  178. package/src/core/resolve/property.ts +99 -0
  179. package/src/core/schema/activity.ts +240 -0
  180. package/src/core/schema/arg.ts +719 -0
  181. package/src/core/schema/command.ts +1490 -0
  182. package/src/core/schema/flag.ts +756 -0
  183. package/src/core/schema/index.ts +91 -0
  184. package/src/core/schema/middleware.ts +171 -0
  185. package/src/core/schema/prompt.ts +156 -0
  186. package/src/core/schema/run.ts +195 -0
  187. package/src/core/schema-dsl/index.ts +109 -0
  188. package/src/core/schema-dsl/parse.ts +262 -0
  189. package/src/core/schema-dsl/runtime.ts +609 -0
  190. package/src/core/schema-dsl/to-json-schema.ts +102 -0
  191. package/src/core/testkit/index.ts +123 -0
  192. package/src/index.ts +170 -0
  193. package/src/runtime/adapter.ts +303 -0
  194. package/src/runtime/auto.ts +110 -0
  195. package/src/runtime/bun.ts +55 -0
  196. package/src/runtime/deno.ts +369 -0
  197. package/src/runtime/detect.ts +105 -0
  198. package/src/runtime/index.ts +21 -0
  199. package/src/runtime/node-builtins.d.ts +23 -0
  200. package/src/runtime/node.ts +300 -0
  201. package/src/runtime/paths.ts +62 -0
  202. package/src/runtime/support.ts +135 -0
  203. package/src/runtime.ts +31 -0
  204. package/src/testkit.ts +25 -0
  205. package/src/version.ts +20 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,706 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
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).
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [2.0.0] - 2026-04-07
11
+
12
+ ### Added
13
+
14
+ - **String-literal schema DSL** — added a single-source schema surface that parses definitions at
15
+ compile time and runtime, then reuses the same model for JSON Schema generation.
16
+ - **Published definition schema export** — added `@kjanat/dreamcli/schema` so tooling and docs
17
+ consumers can import the generated definition schema locally instead of relying on the CDN URL.
18
+ - **Fish and PowerShell shell completions** — expanded completion support beyond Bash and Zsh.
19
+ - **Source-backed docs surfaces** — added generated API inventory pages, per-entrypoint symbol
20
+ routes, source-backed example pages with related symbol links, and reference guides for planner,
21
+ resolver, output, schema, support, migration, troubleshooting, and semantic deltas.
22
+ - **`gh-project` workflow helper** — added a DreamCLI-powered project tool for syncing the
23
+ re-foundation task board and PRD state.
24
+
25
+ ### Changed
26
+
27
+ - **Package identity and build pipeline** — the package is now published as `@kjanat/dreamcli`,
28
+ ships ESM-only, emits the definition schema during the tsdown prepare hook, tightens published
29
+ exports for runtime-specific consumers, and hardens npm, JSR, and docs release checks.
30
+ - **Docs app architecture** — VitePress now builds reference and example pages from data loaders
31
+ instead of static generated files, adds runtime/twoslash settings UI, improves mobile twoslash
32
+ UX, and copies root artifacts into deployed docs output.
33
+ - **Examples and walkthroughs** — the `gh` example grew into a multi-file workspace canary, and the
34
+ example set now doubles as richer docs source with broader JSDoc coverage and better walkthrough
35
+ material.
36
+
37
+ ### Fixed
38
+
39
+ - **Completion and alias handling** — hidden compatibility aliases now parse correctly, Bash and Zsh
40
+ completion behavior is safer and more consistent, and shell completion edge cases were tightened.
41
+ - **Aggregate validation diagnostics** — mixed flag and arg validation failures now surface clearer
42
+ per-issue labels plus value-source labels such as `env ...` and `stdin`.
43
+ - **Schema and docs integration** — schema URLs, generated meta descriptions, twoslash rendering,
44
+ and source-backed docs pages now build reliably across local, CI, and Cloudflare deploys.
45
+ - **CLI and runtime edge cases** — unresolved schema references now fail closed, runtime/support
46
+ checks were hardened, and several dispatch/output/runtime regressions were corrected.
47
+
48
+ ## [1.0.0] - 2026-04-02
49
+
50
+ ### Added
51
+
52
+ #### Release Automation
53
+
54
+ - **GitHub Actions npm publish workflow** (`.github/workflows/publish-npm.yml`) — publishes the
55
+ package to npm on GitHub release with provenance enabled, bringing npm release automation in line
56
+ with the existing JSR publish flow.
57
+
58
+ #### Canonical Semantics Guide
59
+
60
+ - **`docs/guide/semantics.md`** — centralized reference for parser and resolver behavior, including
61
+ repeated flags, short-flag stacking, `--` separator rules, `--no-*` alias behavior, value-source
62
+ precedence, non-interactive prompt skipping, propagated-flag masking, and default-command root
63
+ help/completion semantics.
64
+
65
+ #### Plugin Lifecycle Hooks
66
+
67
+ - **`plugin(hooks, name?)`** and **`.plugin(definition)`** expose a typed extension surface around
68
+ command execution.
69
+ - **Lifecycle phases** — `beforeParse`, `afterResolve`, `beforeAction`, and `afterAction` let
70
+ plugins observe or instrument execution without reaching into CLI internals.
71
+
72
+ #### `derive()` Command Context
73
+
74
+ - **`command(...).derive(handler)`** adds typed command-scoped pre-action context derived from fully
75
+ resolved flags and args.
76
+ - **Derived context merges into `ctx`** so commands can validate once and consume typed values in
77
+ the action handler.
78
+
79
+ #### Schema Export and Validation
80
+
81
+ - **`generateInputSchema()`** exports JSON Schema from CLI definitions for machine validation and
82
+ tooling.
83
+ - **Schema export docs and reference coverage** now document export formats, discriminator behavior,
84
+ and default/hidden command handling.
85
+
86
+ #### Runtime Surface and Execution Options
87
+
88
+ - **Runtime support matrix and version guards** added around adapter creation.
89
+ - **`run()` accepts `jsonMode`** in options, letting callers force structured output without
90
+ shell-level flags.
91
+ - **`out.table()` format and stream overrides** expose finer control over tabular output.
92
+
93
+ ### Changed
94
+
95
+ - **Docs navigation and entrypoints** — guide pages now link to the canonical semantics guide, the
96
+ API reference landing page includes quick import guidance and key factories per subpath export,
97
+ and the VitePress sidebar surfaces the semantics page under the Advanced guide section.
98
+ - **Public API surface tightened** — runtime exports were pruned and guarded, explicit `require`
99
+ conditions were added to package exports, and self-referencing package imports were hardened.
100
+ - **Docs and examples expanded** — JSDoc/reference coverage grew across exported symbols, schema
101
+ export/testing/runtime docs were added, and the `gh` walkthrough became a multi-file example
102
+ package.
103
+ - **CI and packaging hardened** — version-sync checks, supported Node pinning, preview publish
104
+ verification, and Bun-pack package validation were added around the release surface.
105
+
106
+ ### Fixed
107
+
108
+ - **Default-command UX** — single-command root help is merged correctly, root completions surface
109
+ default-command flags, unknown root flags are rejected cleanly, and schema discriminator handling
110
+ matches the actual default-command surface.
111
+ - **Stdin and runtime behavior** — stdin reads defer until dispatch needs them, empty pipes are
112
+ distinguished from no pipe, and test adapters now match real runtime behavior more closely.
113
+ - **Parser/help/completion/output edge cases** — optional array flags resolve to `[]`, variadic help
114
+ formatting is corrected, bash/zsh completion edge cases are hardened, non-finite JSON values are
115
+ rejected, and table options are preserved correctly.
116
+
117
+ ## [0.9.2] - 2026-03-30
118
+
119
+ ### Added
120
+
121
+ #### Stdin-Backed Positional Arguments
122
+
123
+ - **`ArgBuilder.stdin()`** lets positional args consume piped stdin when no CLI token is provided.
124
+ - **`RuntimeAdapter.readStdin()`** adds full stdin reads to the runtime contract across Node, Bun,
125
+ and Deno adapters.
126
+ - **`RunOptions.stdinData` and testkit plumbing** let in-process tests feed stdin-backed commands
127
+ without touching real process state.
128
+ - **Comprehensive stdin coverage** added across schema, resolver, runtime, and testkit tests.
129
+
130
+ ### Changed
131
+
132
+ - Positional-arg resolution for stdin-enabled args expanded from **CLI → env → default** to
133
+ **CLI → stdin → env → default**.
134
+ - Scripts now separate **`lint`** from **`format`**, so linting no longer doubles as a rewrite step.
135
+
136
+ ## [0.9.1] - 2026-03-30
137
+
138
+ ### Added
139
+
140
+ #### Default Command Support
141
+
142
+ - **`CLIBuilder.default(command)`** lets a CLI run a fallback command when no subcommand is
143
+ specified.
144
+ - **Root args and flags flow through the default command** while explicit subcommands still take
145
+ precedence.
146
+
147
+ #### Package.json Auto-Discovery
148
+
149
+ - **`CLIBuilder.packageJson(settings?)`** — opt-in builder method that enables automatic
150
+ `package.json` discovery at `.run()` time. Walks up from `cwd` to find the nearest `package.json`
151
+ and merges `version` and `description` into the CLI schema. Explicit `.version()` and
152
+ `.description()` calls always take precedence over discovered values.
153
+ - **`PackageJsonSettings.inferName`** — when `true`, infers the CLI binary name from the `bin` key
154
+ (first key of the object) or the package `name` field (scope stripped). Defaults to `false`.
155
+ - **`discoverPackageJson(adapter)`** — pure function that walks up from `adapter.cwd` to find and
156
+ parse the nearest `package.json`. Returns `PackageJsonData | null`. All I/O flows through the
157
+ adapter — fully testable with virtual filesystems.
158
+ - **`inferCliName(pkg)`** — resolves CLI name from `PackageJsonData` with priority: bin key → scoped
159
+ name (stripped) → `undefined`.
160
+ - **Silent error handling** — malformed JSON, non-object roots, and missing `package.json` all
161
+ return `null` (not errors). Deno permission denials degrade gracefully via the adapter's existing
162
+ `readFile` contract.
163
+ - **Completions skip** — package.json discovery is skipped for the `completions` subcommand,
164
+ matching the existing config discovery skip pattern.
165
+ - **43 new tests** — `package-json.test.ts` (24 unit tests: walk-up resolution, field extraction,
166
+ error resilience, Windows path termination) and `cli-package-json.test.ts` (19 integration tests:
167
+ version/description fill, name inference, precedence, walk-up, completions skip, combined with
168
+ config, error resilience).
169
+
170
+ #### `help` Virtual Subcommand
171
+
172
+ - **`BINARY help <command>`** produces the same output as `BINARY <command> --help`. Rewrites argv
173
+ via recursive `execute()` — no dispatch duplication.
174
+ - **Nested support** — `help db migrate` works like `db migrate --help`.
175
+ - **Bare `help`** shows root help.
176
+ - **Defers to real commands** — if the user registers a command named `help` (or aliased as `help`),
177
+ it takes priority over the virtual subcommand.
178
+ - **`--json` propagation** — `help --json <command>` correctly preserves json mode (help text routes
179
+ to stderr, stdout reserved for data).
180
+ - **10 new tests** across `cli.test.ts` (7), `cli-nesting.test.ts` (2), `cli-json.test.ts` (1).
181
+
182
+ #### Arg Environment Variable Resolution
183
+
184
+ - **`ArgBuilder.env(varName)`** binds a positional argument to an environment variable. When the CLI
185
+ value is absent, the resolver reads the env var and coerces the string to the arg's declared kind
186
+ (passthrough for strings, `Number()` with NaN guard for numbers, `parseFn` invocation for custom
187
+ args). Resolution order: **CLI → env → default**.
188
+ - **`ArgSchema.envVar`** field (`string | undefined`) stores the env var name on the runtime schema
189
+ descriptor.
190
+ - **Env coercion for args** via `coerceArgEnvValue()` in the resolver. Handles `string`
191
+ (passthrough), `number` (parse + NaN guard), and `custom` (delegates to `parseFn`, wraps thrown
192
+ errors).
193
+ - **`[env: VAR]` annotation** in help output for args with env bindings, matching the existing flag
194
+ annotation style.
195
+ - **Actionable required-arg error hints** — `buildRequiredArgSuggest()` generates suggestions
196
+ including the env var when configured (e.g. "Provide a value for \<target\> or set
197
+ DEPLOY_TARGET").
198
+ - **16 new tests** — `resolve-arg-env.test.ts` (15 tests covering string/number/custom coercion,
199
+ CLI > env > default precedence, deprecation warnings, error cases) and 1 help output test for the
200
+ `[env: VAR]` annotation.
201
+
202
+ #### Command Metadata
203
+
204
+ - **`CommandMeta`** added to action handlers and middleware, carrying the CLI name, invoked binary,
205
+ version, and resolved leaf command name.
206
+
207
+ #### Documentation Site, README, and Examples
208
+
209
+ - **README** added with project pitch, usage, install guidance, and comparison table.
210
+ - **Examples directory** added with seven implementation examples.
211
+ - **VitePress documentation site** added with concepts, guide, and reference sections.
212
+ - **GitHub Pages deploy workflow and sitemap** added for hosted docs.
213
+ - **Walkthrough guide** added for a GitHub CLI-style example application.
214
+
215
+ ### Changed
216
+
217
+ - Completion generation was reorganized into shell-specific generators and the package/tooling
218
+ surface was refreshed for the `0.9.1` milestone.
219
+ - Comprehensive public-facing JSDoc examples were added to the builder APIs.
220
+
221
+ ### Fixed
222
+
223
+ - Default commands no longer swallow nested unknown-command errors.
224
+
225
+ ## [0.9.0] - 2026-02-11
226
+
227
+ ### Added
228
+
229
+ #### Deno Adapter
230
+
231
+ - **`createDenoAdapter(ns?)`** — full `RuntimeAdapter` implementation for Deno. Reads argv from
232
+ `Deno.args` (prepends synthetic `['deno', 'run']` for parity), env from `Deno.env.toObject()`, cwd
233
+ from `Deno.cwd()`, stdout/stderr via `TextEncoder` → `Deno.stdout.write`/`Deno.stderr.write`,
234
+ stdin via `Deno.stdin.readable` stream with line-buffered reader, TTY detection via
235
+ `isTerminal()`, `readFile` via `Deno.readTextFile`, and homedir/configDir from env vars.
236
+ - **Permission-safe** — `PermissionDenied` errors gracefully degrade: env falls back to `{}`, cwd to
237
+ `/`, readFile to `null`. Non-permission errors propagate.
238
+ - **`deno-builtins.d.ts`** — ambient type declarations for `TextEncoder`, `TextDecoder`, and
239
+ `ReadableStream` (needed because `lib: ["ES2022"]` excludes web platform APIs).
240
+ - **`createAdapter()` auto-detection** now handles Deno runtime via `globalThis.Deno` feature
241
+ probing.
242
+ - Re-exported `createDenoAdapter` and `DenoNamespace` from `@kjanat/dreamcli/runtime` subpath.
243
+
244
+ #### Cross-Runtime CI
245
+
246
+ - **GitHub Actions CI workflow** (`.github/workflows/ci.yml`) — lint+typecheck (Bun), test matrix
247
+ (Node LTS + Bun stable), Deno smoke test, build with publint+attw.
248
+ - **Deno smoke test** (`scripts/deno-smoke-test.ts`) — runs on real Deno runtime after build,
249
+ exercising `createDenoAdapter()` against actual Deno APIs.
250
+
251
+ #### JSR Publishing
252
+
253
+ - **`deno.json`** with JSR package config (`@kjanat/dreamcli`), three subpath exports, publish
254
+ include/exclude rules.
255
+ - **GitHub Actions publish workflow** (`.github/workflows/publish-jsr.yml`) — publishes to JSR on
256
+ GitHub release with OIDC provenance.
257
+
258
+ ### Changed
259
+
260
+ - **`.ts` import extensions** — all import specifiers switched from `.js` to `.ts` via
261
+ `allowImportingTsExtensions`. tsconfig updated: `noEmit: true` +
262
+ `allowImportingTsExtensions: true` replace `declaration`/`declarationMap`/`sourceMap`/`outDir`
263
+ (all handled by tsdown). Removes the need for Deno's `unstable: ["sloppy-imports"]`.
264
+ - `detectRuntime()` updated with Deno detection via `globalThis.Deno?.version?.deno`.
265
+ - `createAdapter()` switch now covers `'deno'` case alongside `'node'` and `'bun'`.
266
+ - Completion generator: `typeof` check on `globalThis` narrowed to avoid Deno type errors.
267
+ - `runtime/deno.ts` expanded from empty stub (~5 lines) to full implementation (~318 lines).
268
+ - Test count: 1695 tests across 47 test files (up from 1658 in v0.8.0).
269
+
270
+ ## [0.8.0] - 2026-02-11
271
+
272
+ ### Breaking
273
+
274
+ - **Subpath exports** — single `"."` entry split into `"."`, `"./testkit"`, `"./runtime"`. Test
275
+ utilities (`runCommand`, `createCaptureOutput`, `createTestPrompter`, `createTestAdapter`,
276
+ `PROMPT_CANCEL`) moved to `@kjanat/dreamcli/testkit`. Runtime adapters (`createAdapter`,
277
+ `createNodeAdapter`, `createBunAdapter`, `detectRuntime`, `ExitError`, `RUNTIMES`,
278
+ `RuntimeAdapter`) moved to `@kjanat/dreamcli/runtime`. `createTestAdapter`/`TestAdapterOptions` exported
279
+ only from `@kjanat/dreamcli/testkit`.
280
+
281
+ ### Added
282
+
283
+ #### Spinner & Progress Bar
284
+
285
+ - **`out.spinner(text, options?)`** creates a spinner handle for indeterminate progress feedback.
286
+ Returns a `SpinnerHandle` with `update(text)`, `succeed(text?)`, `fail(text?)`, `stop()`, and
287
+ `wrap(promise, options?)` for auto-succeed/fail on promise settlement.
288
+ - **`out.progress(options)`** creates a progress bar handle. Pass `total` for determinate mode
289
+ (percentage bar); omit for indeterminate (pulsing animation). Returns a `ProgressHandle` with
290
+ `increment(n?)`, `update(value)`, `done(text?)`, and `fail(text?)`.
291
+ - **Four rendering modes** with automatic dispatch:
292
+ - **TTY** — animated braille spinner (80ms frames) and bar rendering with ANSI cursor control.
293
+ Hides cursor during animation, restores on terminal methods.
294
+ - **Static** (`fallback: 'static'`) — plain text at lifecycle boundaries (start, succeed, fail).
295
+ No ANSI codes. For CI and piped output.
296
+ - **Noop** (`fallback: 'silent'`, default) — all methods are no-ops. Silent in non-TTY.
297
+ - **JSON mode** — always noop (structured output only).
298
+ - **Active handle tracking** — at most one spinner or progress may be active at a time. Creating a
299
+ new one implicitly stops the previous to avoid garbled terminal output.
300
+ - **`ActivityEvent` discriminated union** — 10-variant DU capturing spinner and progress lifecycle
301
+ events (`spinner:start`, `spinner:update`, `spinner:succeed`, `spinner:fail`, `spinner:stop`,
302
+ `progress:start`, `progress:increment`, `progress:update`, `progress:done`, `progress:fail`).
303
+ - **Testkit capture handles** — `CaptureOutputChannel` subclass overrides `spinner()` and
304
+ `progress()` to record `ActivityEvent[]` for assertion. `CapturedOutput.activity` array added.
305
+ - **New public types** exported from barrel: `ActivityEvent`, `Fallback`, `SpinnerHandle`,
306
+ `SpinnerOptions`, `ProgressHandle`, `ProgressOptions`.
307
+ - **`out.stopActive()`** public method on `Out` to clean up active spinner/progress timers. Prevents
308
+ process hangs when a handler throws before reaching a terminal method (`stop`, `succeed`, `fail`,
309
+ `done`). `runCommand()` calls it automatically in a `finally` block; direct `createOutput()` users
310
+ call it themselves.
311
+ - **`progress:increment` activity event** — 10th `ActivityEvent` variant
312
+ `{ type: 'progress:increment', delta }`. `increment()` now emits this instead of reusing
313
+ `progress:update`, making capture events unambiguous for testing.
314
+
315
+ ### Changed
316
+
317
+ - `Out` interface extended with `spinner()` and `progress()` methods.
318
+ - `CapturedOutput` extended with `activity: ActivityEvent[]` field.
319
+ - `createCaptureOutput` now returns a `CaptureOutputChannel` that records activity events separately
320
+ from stdout/stderr.
321
+ - `FlagParseFn<T>` widened from `(raw: string) => T` to `(raw: unknown) => T`. Config files carry
322
+ structured JSON data — `parseFn` now receives the raw value directly and is responsible for
323
+ narrowing. CLI/env still pass strings; config passes the JSON value as-is.
324
+ - `Out` interface extended with `stopActive()` method for explicit timer cleanup.
325
+ - `ActivityEvent` union widened from 9 to 10 variants (added `progress:increment`).
326
+ - `OutputChannel` refactored: activity handle implementations extracted to `activity.ts` (~581
327
+ lines), `WriteFn` type and `writeLine` helper extracted to `writer.ts` (~30 lines). `index.ts`
328
+ reduced from 1156 to 589 lines. No public API changes.
329
+ - All activity handle output (static and TTY) now routes to stderr. Previously static mode used a
330
+ `StaticWriters` pair routing some output to stdout; the dual-writer abstraction is removed.
331
+ - `runCommand()` calls `out.stopActive()` in a `finally` block, ensuring timer cleanup on handler
332
+ exceptions.
333
+ - **Resolve coercion unified** — three near-identical functions (`coerceEnvValue` ~105 lines,
334
+ `coerceConfigValue` ~120 lines, `coercePromptValue` ~120 lines) replaced by single `coerceValue()`
335
+ using `CoerceSource` discriminated union (`'env' | 'config' | 'prompt'`). Error messages
336
+ parameterized via `sourceLabel()`/`sourceDetails()`/`coercionError()` helpers. `resolve/index.ts`
337
+ reduced from ~1115 to ~940 lines.
338
+ - **Activity types extracted** — 7 activity/output types (`Fallback`, `SpinnerOptions`,
339
+ `SpinnerHandle`, `ProgressOptions`, `ProgressHandle`, `ActivityEvent`, `TableColumn`) moved from
340
+ `schema/command.ts` to `schema/activity.ts` (~150 lines). `command.ts` reduced from 898 to 784
341
+ lines.
342
+ - **Root help extracted** — `formatRootHelp()` + `padEnd()` + `wrapText()` moved from `cli/index.ts`
343
+ to `cli/root-help.ts` (~133 lines). Uses structural `CLISchemaLike` interface to avoid circular
344
+ imports. `cli/index.ts` reduced from 901 to 793 lines.
345
+ - **`infer/` stub deleted** — removed empty `src/core/infer/index.ts`.
346
+ - **Source files in published package** — `"src"` added to `files` array in package.json.
347
+ - **Package manager migrated** — pnpm → bun. `packageManager` set to `bun@1.3.9`.
348
+ - **Build config** — `tsdown.config.ts` changed to multi-entry build with `minify: true`.
349
+ - Test count: 1658 tests across 46 test files (up from 1518 in v0.7.0).
350
+
351
+ ### Fixed
352
+
353
+ - `--config=<path>` equals form now correctly parsed and stripped from argv before dispatch.
354
+ - Zsh completion: multi-alias flags use all short aliases in the exclusion group, not just the
355
+ first.
356
+ - Bash completion: `escapeForSingleQuote()` sanitizes `compgen -W` words to prevent shell injection.
357
+ - Win32 `resolveConfigDir`: strip trailing separator from homedir to avoid doubled backslashes on
358
+ drive roots (e.g. `C:\`).
359
+ - Win32 `resolveConfigDir`: treat empty `APPDATA` as unset, falling back to homedir-based path.
360
+ - Win32 `homedir`: add `HOMEDRIVE`+`HOMEPATH` fallback; never use `HOMEPATH` alone.
361
+ - Levenshtein distance: replace 2D array with `Uint16Array` rolling buffer, drop defensive
362
+ `undefined` guards.
363
+ - Completions command detection via schema lookup instead of raw `argv[0]` string match.
364
+ - Child flag with `propagate: false` correctly masks ancestor's propagated flag of the same name.
365
+ - Dispatch: exhaustiveness guard on `subResult` switch in nested command resolution.
366
+ - Nested group help: `binName` built from full command path, not just root.
367
+ - Config loader: lowercase extensions in `buildExtensionList`/`buildLoaderMap` for case-insensitive
368
+ matching.
369
+ - Empty-string env var fallbacks in runtime adapter treated as unset.
370
+ - `ProgressHandle.increment()` was emitting `progress:update` events indistinguishable from
371
+ `update()` calls. Now emits `progress:increment` with `delta` field.
372
+ - **Prompt number coercion** — `coercePromptValue` was missing NaN guard for number flags; now
373
+ handled by unified `coerceValue()`.
374
+
375
+ ## [0.7.0] - 2026-02-10
376
+
377
+ ### Added
378
+
379
+ #### Subcommand Nesting
380
+
381
+ - **`CommandBuilder.command(sub)`** registers nested subcommands, building recursive command trees
382
+ of unlimited depth. Parent commands store children as type-erased `ErasedCommand` entries — the
383
+ parent doesn't need the child's generic types.
384
+ - **`group(name)`** factory as a semantic alias for `command()`. Communicates intent: groups
385
+ organise subcommands, leaf commands have actions. A group may also have its own `.action()` (e.g.
386
+ `git remote` lists remotes, `git remote add` dispatches to a child).
387
+ - **`flag.propagate()`** modifier marks a flag for automatic inheritance by all descendant commands.
388
+ Propagated flags are collected from the ancestor chain at dispatch time. Child commands override a
389
+ propagated flag by redeclaring the same name — child definition wins completely.
390
+ - **Recursive dispatch** in `CLIBuilder.execute()`. Walks argv segments matching command names at
391
+ each tree level. Handles hybrid commands (action + subcommands): subcommand match takes priority,
392
+ else falls through to the parent handler. Groups without handlers show help.
393
+ - **Nested help** — `formatHelp()` renders a "Commands:" section listing available subcommands for
394
+ group commands. Usage line adapts to show `<command>` placeholder when subcommands exist.
395
+ - **Nested completions** — bash and zsh generators traverse the full command tree depth. Propagated
396
+ flags included at each nesting level. Bash uses path-keyed case statements; zsh generates
397
+ per-group helper functions.
398
+ - **Scoped "did you mean?"** — typo suggestions search within the current command scope, not the
399
+ global command list. Help hint shows scoped path (e.g. `Run 'myapp db --help'`).
400
+
401
+ ### Changed
402
+
403
+ - `CommandSchema` extended with `commands: readonly CommandSchema[]` for nested subcommand schemas.
404
+ - `ErasedCommand` extended with `subcommands: ReadonlyMap<string, ErasedCommand>` for dispatch.
405
+ - `ErasedCommand` interface moved from `cli/index.ts` to `schema/command.ts` (shared location).
406
+ - `FlagSchema` extended with `propagate: boolean` (default `false`).
407
+ - `RunOptions` extended with `mergedSchema` internal field for propagated flag injection.
408
+ - Dispatch logic extracted to `cli/dispatch.ts` (~285 lines) and flag propagation to
409
+ `cli/propagate.ts` (~87 lines), reducing `cli/index.ts` by ~220 lines.
410
+ - Test count: 1518 tests across 43 test files (up from 1300 in v0.6.0).
411
+
412
+ ### Fixed
413
+
414
+ - Completion generator no longer recurses into hidden command subtrees.
415
+ - Dispatch respects `--` end-of-flags sentinel before command names.
416
+
417
+ ## [0.6.0] - 2026-02-10
418
+
419
+ ### Added
420
+
421
+ #### Config File Discovery
422
+
423
+ - **`CLIBuilder.config(appName)`** enables config file discovery with XDG-compliant search paths.
424
+ Searches `.{app}.json` and `{app}.config.json` in cwd, then `{configDir}/{app}/config.json`. JSON
425
+ loader built-in.
426
+ - **`--config <path>` global flag** overrides config file discovery path. Extracted from argv before
427
+ command dispatch.
428
+ - **`CLIBuilder.configLoader(loader)`** plugin hook for registering custom config format loaders
429
+ (YAML, TOML, etc.). `configFormat(extensions, parseFn)` convenience factory.
430
+
431
+ #### Schema Additions
432
+
433
+ - **`flag.custom(parseFn)`** — new flag kind accepting an arbitrary parse function with full
434
+ return-type inference from `parseFn`. Wired through parser coercion, all three resolve coercions
435
+ (env, config, prompt), and help formatter.
436
+ - **`.deprecated(message?)`** modifier on `FlagBuilder` and `ArgBuilder`. Emits structured
437
+ `DeprecationWarning` during resolution when a deprecated flag/arg is explicitly provided (CLI,
438
+ env, config, prompt — not for default fallthrough). Renders `[deprecated]` or
439
+ `[deprecated: <reason>]` in help text.
440
+
441
+ #### RuntimeAdapter Extensions
442
+
443
+ - **`readFile`** — async file read returning `null` for ENOENT, throws on other errors. Uses lazy
444
+ `import('node:fs/promises')`.
445
+ - **`homedir`** — computed from env vars (`HOME`/`USERPROFILE`) + `platform`; avoids `node:os`.
446
+ - **`configDir`** — `XDG_CONFIG_HOME` on Unix, `APPDATA` on Windows; falls back to `~/.config` or
447
+ `~\AppData\Roaming`.
448
+
449
+ ### Changed
450
+
451
+ - `RuntimeAdapter` interface extended with `readFile`, `homedir`, `configDir`.
452
+ - `NodeProcess` interface extended with `platform` field.
453
+ - `FlagSchema` extended with `parseFn: FlagParseFn<unknown> | undefined`.
454
+ - `FlagSchema` extended with `deprecated: string | true | undefined`.
455
+ - `ArgSchema` extended with `deprecated: string | true | undefined`.
456
+ - `ResolveResult` extended with `warnings: readonly DeprecationWarning[]`.
457
+ - `CLISchema` extended with `configSettings` for config file discovery.
458
+ - `FlagParseFn<T>`, `DeprecationWarning`, `ConfigResult`, `FormatLoader`, `configFormat` exported
459
+ from public API.
460
+ - Test count: ~1300 tests (up from 1198 in v0.5.0).
461
+
462
+ ## [0.5.0] - 2026-02-10
463
+
464
+ ### Added
465
+
466
+ #### Shell Completions
467
+
468
+ - **Bash completion generator** — produces self-contained bash scripts with
469
+ `COMP_WORDS`/`COMP_CWORD` scanning, per-command case branches with flag and enum value
470
+ completions, and `complete -F` registration.
471
+ - **Zsh completion generator** — produces `#compdef` scripts with `_arguments` flag specs,
472
+ `_describe` subcommand lists, and enum value completions via `->state` dispatch.
473
+ - **`CLIBuilder.completions()`** adds a built-in `completions --shell <bash|zsh>` subcommand that
474
+ outputs a ready-to-eval completion script. In `--json` mode, emits `{ script }` JSON object.
475
+ Fish/PowerShell accepted in the enum with descriptive "not yet supported" errors.
476
+
477
+ #### Runtime Portability
478
+
479
+ - **`detectRuntime()`** via `globalThis` feature detection — identifies Node, Bun, Deno, or unknown.
480
+ Exported `Runtime` type and `RUNTIMES` constant.
481
+ - **`createAdapter()`** auto-detecting adapter factory — calls `detectRuntime()` and returns the
482
+ appropriate `RuntimeAdapter`. `CLIBuilder.run()` uses it as default when no adapter is provided.
483
+ - **Bun adapter** implementing `RuntimeAdapter` by delegating to the Node adapter (Bun's
484
+ Node-compatible APIs).
485
+
486
+ ### Fixed
487
+
488
+ - Completion: cross-command enum collision — `collectEnumCases()` scoped per-command to prevent enum
489
+ values from one command leaking into another's completions.
490
+ - Completion: shell injection safety — `quoteShellArg()` escapes `schema.name` and enum values in
491
+ generated scripts.
492
+ - Completion: conditional `--version` — bash generator omits `--version` from completions when
493
+ `schema.version` is undefined, matching zsh behavior.
494
+ - CLI: `--json` mode completions output `{ script }` JSON instead of raw script text.
495
+ - CLI: guard against double `.completions()` call.
496
+ - Runtime: `NodeProcess` type exported from main barrel.
497
+ - Runtime: `@internal` removed from `GlobalForDetect` (contradicted public export).
498
+ - Runtime: `createAdapter()` switch uses `default: never` exhaustiveness guard.
499
+
500
+ ### Changed
501
+
502
+ - Shell completion types, generator stubs, and barrel exports added to `src/core/completion/`.
503
+ - Test count: 1198 tests across 35 test files (up from 1010 in v0.4.0).
504
+
505
+ ## [0.4.0] - 2026-02-09
506
+
507
+ ### Added
508
+
509
+ #### Typed Middleware
510
+
511
+ - **`middleware<Output>(handler)`** factory creating phantom-branded `Middleware<Output>` values.
512
+ Handler receives `{ args, flags, ctx, out, next }` — call `next(additions)` to continue the chain
513
+ with typed context, omit `next()` to short-circuit (auth guards), or await `next()` for
514
+ wrap-around patterns (timing, try/catch).
515
+ - **`CommandBuilder.middleware(m)`** registers middleware in execution order. Each call widens the
516
+ context type parameter `C` via `WidenContext<C, Output>` intersection — `Record<string, never>`
517
+ (the default) is replaced entirely on the first call, preventing `never` collapse. Adding
518
+ middleware drops the current handler (type signature changed).
519
+ - **Context type parameter `C`** on `CommandBuilder<F, A, C>`, `ActionParams<F, A, C>`, and
520
+ `ActionHandler<F, A, C>`. `ctx` in the action handler is `Readonly<C>` — property access is a type
521
+ error until middleware extends it.
522
+ - **Middleware chain execution** (`executeWithMiddleware`) in testkit. Builds a continuation chain
523
+ from back to front; context accumulates via `{ ...ctx, ...additions }` at each step. Replaces the
524
+ former `invokeHandler` bridge.
525
+
526
+ #### Structured Output
527
+
528
+ - **`out.json(value)`** emits `JSON.stringify(value)` to stdout. Always targets stdout regardless of
529
+ JSON mode. Handlers should prefer this over `out.log(JSON.stringify(...))`.
530
+ - **`out.table(rows, columns?)`** renders tabular data. In JSON mode: emits rows as JSON array. In
531
+ text mode: pretty-prints aligned columns with headers (auto-inferred from first row when `columns`
532
+ omitted). `TableColumn<T>` descriptor type with `key` and optional `header`.
533
+ - **`out.jsonMode`** and **`out.isTTY`** readonly properties on `Out` interface. Handlers check
534
+ these to skip decorative output (spinners, ANSI codes) when machine-readable output is expected or
535
+ stdout is piped.
536
+ - **`--json` global flag** detection in `CLIBuilder.execute()`. Strips `--json` from argv before
537
+ command dispatch. CLI-level dispatch errors (unknown command, no action) rendered as JSON when
538
+ active.
539
+ - **`jsonMode`** and **`isTTY`** options on `RunOptions`, `CLIRunOptions`, and `OutputOptions`.
540
+ `CLIBuilder.run()` auto-sources `isTTY` from `adapter.isTTY`.
541
+
542
+ ### Changed
543
+
544
+ - `ActionParams<F, A>` → `ActionParams<F, A, C>` with `ctx: Readonly<C>` (was
545
+ `Readonly<Record<string, unknown>>`).
546
+ - `CommandBuilder` carries third type parameter `C` (default `Record<string, never>`). All
547
+ metadata/builder methods preserve `C` in return type.
548
+ - `CommandSchema.middleware` added as `readonly ErasedMiddlewareHandler[]`.
549
+ - `Out` interface extended with `json()`, `table()`, `jsonMode`, and `isTTY`.
550
+ - `OutputChannel` constructor accepts `isTTY` and `jsonMode` from resolved options. `log`/`info`
551
+ redirect to stderr writer in JSON mode.
552
+ - `runCommand` and `CLIBuilder.execute` error paths render JSON when `jsonMode` active.
553
+ - `createCaptureOutput` accepts `jsonMode` and `isTTY` options.
554
+ - Test count: 1010 tests across 31 test files (up from 797 in v0.3.0).
555
+
556
+ ## [0.3.0] - 2026-02-09
557
+
558
+ ### Added
559
+
560
+ #### Interactive Prompting
561
+
562
+ - **Prompt type definitions** (`PromptConfig`) as a discriminated union with four kinds: `confirm`,
563
+ `input`, `select`, `multiselect`. Each kind has specialized fields — `InputPromptConfig` supports
564
+ `placeholder` and `validate`, select/multiselect support `SelectChoice` arrays with optional
565
+ labels and descriptions.
566
+ - **`FlagBuilder.prompt(config)`** metadata modifier for declaring prompt configuration on flags,
567
+ following the same immutable builder pattern as `.env()` and `.config()`.
568
+ - **Prompt engine interface** (`PromptEngine`) with `promptOne(config) → Promise<PromptResult>` as a
569
+ pluggable renderer seam. `ResolvedPromptConfig` variant guarantees non-empty choices for
570
+ select/multiselect after merging from `FlagSchema.enumValues`.
571
+ - **Built-in terminal prompter** (`createTerminalPrompter(read, write)`) with line-based I/O for
572
+ confirm (y/n), input (with validation and placeholder), select (numbered list), and multiselect
573
+ (comma-separated numbers with min/max). All prompts have a `MAX_RETRIES = 10` safety valve.
574
+ - **Test prompter** (`createTestPrompter(answers, options?)`) with queue-based answers for
575
+ deterministic testing. `PROMPT_CANCEL` symbol sentinel for simulating cancellation.
576
+ `onExhausted: 'throw' | 'cancel'` controls behavior when answer queue is empty.
577
+ - **Prompt resolution in the resolver**. Resolution chain expanded from CLI > env > config > default
578
+ to CLI > env > config > **prompt** > default. Flags with prompt config and no value from prior
579
+ sources trigger `prompter.promptOne()`. Cancelled prompts fall through to default/required.
580
+ Non-interactive mode (no prompter) skips prompts entirely.
581
+ - **`ReadFn`** (`() => Promise<string | null>`) as the minimal stdin abstraction. `null` signals
582
+ EOF/cancel. `RuntimeAdapter` extended with `stdin: ReadFn` and `stdinIsTTY: boolean`.
583
+ - **Node adapter stdin** wraps `process.stdin` via dynamic `import('node:readline')` with lazy
584
+ per-call readline interfaces. Minimal `node:readline` type declarations in `node-builtins.d.ts`
585
+ avoid `@types/node` dependency.
586
+ - **Automatic prompt gating** in `CLIBuilder.run()`: when `stdinIsTTY=true` and no explicit prompter
587
+ provided, auto-creates `createTerminalPrompter(adapter.stdin, adapter.stderr)`. Prompt output
588
+ routed to stderr to avoid interfering with piped stdout.
589
+ - **Command-level `.interactive(resolver)`** API on `CommandBuilder`. Resolver receives partially
590
+ resolved flags (after CLI/env/config), returns `Record<string, PromptConfig | false | undefined>`
591
+ controlling which flags get prompted. Truthy `PromptConfig` overrides per-flag prompt; `false`
592
+ explicitly suppresses; absent falls back to per-flag `.prompt()` config.
593
+ - **Testkit `answers` convenience** on `RunOptions`. Accepts `Record<string, TestAnswer>` to
594
+ auto-create a test prompter. `prompter` field also available for explicit engine injection.
595
+ `CLIRunOptions` mirrors both fields.
596
+
597
+ ### Changed
598
+
599
+ - `resolve()` is now **async** (`Promise<ResolveResult>`). All callers (`runCommand`,
600
+ `CLIBuilder.execute`, `CLIBuilder.run`) updated to await.
601
+ - Resolution chain expanded from CLI > env > config > default to CLI > env > config > prompt >
602
+ default.
603
+ - `ResolveOptions` extended with optional `prompter: PromptEngine` field.
604
+ - `RunOptions` extended with `prompter` and `answers` fields.
605
+ - `CLIRunOptions` extended with `prompter` and `answers` fields.
606
+ - `RuntimeAdapter` extended with `stdin: ReadFn` and `stdinIsTTY: boolean`.
607
+ - `createTestAdapter` defaults to EOF-returning stdin and `stdinIsTTY: false`.
608
+ - Test count: 797 tests across 21 test files (up from 599 in v0.2.0).
609
+
610
+ ## [0.2.0] - 2026-02-09
611
+
612
+ ### Added
613
+
614
+ #### Resolution Chain
615
+
616
+ - **Environment variable resolution** in the resolver. Flags with `.env('VAR')` now resolve from the
617
+ `env` record after CLI and before default. String, number, boolean (lenient:
618
+ `true/false/1/0/yes/no`), enum, and array (comma-separated) coercion. Invalid env values produce
619
+ `ValidationError` with `TYPE_MISMATCH` or `INVALID_ENUM` codes.
620
+ - **Config object resolution** in the resolver. Flags with `.config('dotted.path')` resolve from a
621
+ plain `Record<string, unknown>` after env and before default. `resolveConfigPath()` walks nested
622
+ objects segment-by-segment. Config values may already be typed from JSON — coercion is lenient for
623
+ matching types. Full chain: CLI > env > config > default.
624
+ - **Resolution source annotations** in help text. Flags with env or config declarations now display
625
+ `[env: VAR]` and `[config: path]` in `formatHelp()` output, ordered between description text and
626
+ presence indicators.
627
+ - **Actionable required-flag error hints**. When a required flag is missing after full resolution,
628
+ `ValidationError.suggest` lists all configured sources (e.g. "Provide --region, set DEPLOY_REGION,
629
+ or add deploy.region to config"). CI-friendly error messages with `envVar`/`configPath` in
630
+ details.
631
+ - **Env/config wiring through testkit and CLI builder**. `RunOptions` and `CLIRunOptions` accept
632
+ `env` and `config` fields. `runCommand()` threads them into `resolve()`. `CLIBuilder.run()`
633
+ auto-sources `adapter.env` when no explicit env option is provided.
634
+
635
+ ### Changed
636
+
637
+ - Resolution chain expanded from CLI > default (v0.1) to CLI > env > config > default.
638
+ - `resolve()` now accepts optional `ResolveOptions` parameter with `env` and `config` fields.
639
+ - `ResolveOptions` exported from public API surface.
640
+
641
+ ## [0.1.0] - 2026-02-09
642
+
643
+ ### Added
644
+
645
+ #### Core Framework
646
+
647
+ - **Structured errors** (`CLIError`, `ParseError`, `ValidationError`) with stable error codes,
648
+ `toJSON()` serialization, type guard functions (`isCLIError`, `isParseError`,
649
+ `isValidationError`), and actionable `suggest` hints.
650
+ - **Flag builder** (`flag`) with full type inference for boolean, string, number, enum, and array
651
+ kinds. Supports `.alias()`, `.default()`, `.required()`, `.describe()`, `.hidden()`,
652
+ `.deprecated()`, `.env()`, and `.config()` declarations.
653
+ - **Arg builder** (`arg`) with type inference for string, number, custom parse functions, and
654
+ variadic args. Supports `.default()`, `.required()`, `.optional()`, and `.describe()`.
655
+ - **Command builder** (`command`) with `.flag()`, `.arg()`, `.description()`, `.example()`,
656
+ `.hidden()`, `.alias()`, and `.action()`. Accumulates phantom types so handler receives fully
657
+ inferred `flags` and `args`.
658
+ - **Argv parser** with tokenizer (`tokenize`) and schema-aware parser (`parse`). Handles long/short
659
+ flags, `=` syntax, boolean negation (`--no-*`), flag stacking (`-abc`), `--` separator, and type
660
+ coercion against the schema.
661
+ - **Resolution chain** (CLI parsed value → schema default). Validates all required flags/args,
662
+ aggregates multiple errors into a single throw, and provides per-field suggestions.
663
+ - **Auto-generated help text** (`formatHelp`) from command schema, including usage line,
664
+ description, positional args, flags with types/defaults/aliases, examples section, and subcommand
665
+ listing.
666
+ - **Output channel** (`createOutput`) with `log`/`info`/`warn`/`error` methods, `WriteFn`
667
+ abstraction, verbosity levels (normal/quiet), and TTY detection. Includes `createCaptureOutput()`
668
+ test helper.
669
+ - **Test harness** (`runCommand`) for running commands as pure functions with injected argv, env,
670
+ and captured output. Returns `RunResult` with `exitCode`, `stdout`, `stderr`, and `error`.
671
+ - **CLI builder** (`cli`) with `.command()` registration, `.version()`, subcommand dispatch,
672
+ automatic `--help`/`--version` flag handling, and unknown-command error with suggestions.
673
+ - **RuntimeAdapter interface** defining the platform abstraction boundary (argv, env, cwd,
674
+ stdout/stderr, isTTY, exit). Includes `createTestAdapter()` for injectable test stubs and
675
+ `ExitError` for testable process exits.
676
+ - **Node.js adapter** (`createNodeAdapter`) wiring `process.argv`, `process.env`, `process.cwd()`,
677
+ `process.stdout`/`stderr`, and TTY detection.
678
+ - Stub files for Bun adapter, Deno adapter, runtime auto-detection, and shell completion generation.
679
+
680
+ #### Project Infrastructure
681
+
682
+ - Project scaffold with `src/` structure, TypeScript strict config, and ESM + CJS dual build via
683
+ tsdown.
684
+ - Vitest test framework with 464 passing tests across 12 test files.
685
+ - Biome linter and dprint formatter configuration.
686
+ - `@vitest/coverage-v8` for test coverage reporting.
687
+ - `@arethetypeswrong/cli` and `publint` for package quality checks.
688
+ - CI script (`pnpm run ci`) running typecheck, lint, test, and build in sequence.
689
+ - PRD.md with full product requirements document.
690
+ - MIT License.
691
+ - Markdownlint configuration.
692
+
693
+ [Unreleased]: https://github.com/kjanat/dreamcli/compare/v2.0.0...HEAD
694
+ [2.0.0]: https://github.com/kjanat/dreamcli/compare/v1.0.0...v2.0.0
695
+ [1.0.0]: https://github.com/kjanat/dreamcli/compare/5b86f72...v1.0.0
696
+ [0.9.2]: https://github.com/kjanat/dreamcli/compare/b26f2d8...5b86f72
697
+ [0.9.1]: https://github.com/kjanat/dreamcli/compare/v0.9.0...b26f2d8
698
+ [0.9.0]: https://github.com/kjanat/dreamcli/compare/v0.8.0...v0.9.0
699
+ [0.8.0]: https://github.com/kjanat/dreamcli/compare/v0.7.0...v0.8.0
700
+ [0.7.0]: https://github.com/kjanat/dreamcli/compare/v0.6.0...v0.7.0
701
+ [0.6.0]: https://github.com/kjanat/dreamcli/compare/v0.5.0...v0.6.0
702
+ [0.5.0]: https://github.com/kjanat/dreamcli/compare/v0.4.0...v0.5.0
703
+ [0.4.0]: https://github.com/kjanat/dreamcli/compare/v0.3.0...v0.4.0
704
+ [0.3.0]: https://github.com/kjanat/dreamcli/compare/v0.2.0...v0.3.0
705
+ [0.2.0]: https://github.com/kjanat/dreamcli/compare/v0.1.0...v0.2.0
706
+ [0.1.0]: https://github.com/kjanat/dreamcli/releases/tag/v0.1.0