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