@kjanat/dreamcli 2.4.1 → 3.0.0-rc.1

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 (94) hide show
  1. package/CHANGELOG.md +169 -1
  2. package/README.md +14 -7
  3. package/dist/core/cli/index.d.mts +283 -81
  4. package/dist/core/cli/index.mjs +1 -1
  5. package/dist/core/cli/planner.d.mts +27 -5
  6. package/dist/core/cli/planner.mjs +1 -1
  7. package/dist/core/cli/root-help.d.mts +16 -2
  8. package/dist/core/cli/root-help.mjs +3 -5
  9. package/dist/core/cli/root-surface.d.mts +18 -3
  10. package/dist/core/cli/root-surface.mjs +1 -1
  11. package/dist/core/cli/runtime-preflight.d.mts +31 -5
  12. package/dist/core/cli/runtime-preflight.mjs +1 -1
  13. package/dist/core/completion/index.d.mts +32 -1
  14. package/dist/core/completion/index.mjs +1 -1
  15. package/dist/core/completion/shells/shared.d.mts +10 -0
  16. package/dist/core/completion/shells/shared.mjs +1 -1
  17. package/dist/core/config/index.d.mts +2 -2
  18. package/dist/core/config/package-json.d.mts +93 -20
  19. package/dist/core/config/package-json.mjs +3 -1
  20. package/dist/core/help/index.d.mts +45 -1
  21. package/dist/core/help/index.mjs +6 -6
  22. package/dist/core/json-schema/index.mjs +1 -1
  23. package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
  24. package/dist/core/parse/index.d.mts +15 -1
  25. package/dist/core/parse/index.mjs +1 -1
  26. package/dist/core/prompt/index.d.mts +11 -3
  27. package/dist/core/prompt/index.mjs +3 -3
  28. package/dist/core/resolve/coerce.mjs +1 -1
  29. package/dist/core/resolve/flags.mjs +1 -1
  30. package/dist/core/resolve/property.d.mts +2 -0
  31. package/dist/core/resolve/property.mjs +1 -1
  32. package/dist/core/schema/arg.d.mts +90 -10
  33. package/dist/core/schema/arg.mjs +1 -1
  34. package/dist/core/schema/command.d.mts +3 -1
  35. package/dist/core/schema/flag.d.mts +92 -2
  36. package/dist/core/schema/flag.mjs +1 -1
  37. package/dist/core/schema/index.d.mts +2 -1
  38. package/dist/core/schema/number-constraints.d.mts +96 -0
  39. package/dist/core/schema/number-constraints.mjs +1 -0
  40. package/dist/core/schema/prompt.d.mts +15 -0
  41. package/dist/core/schema/run.d.mts +4 -4
  42. package/dist/core/testkit/index.d.mts +9 -5
  43. package/dist/core/testkit/index.mjs +1 -1
  44. package/dist/index.d.mts +4 -3
  45. package/dist/index.mjs +1 -1
  46. package/dist/runtime/auto.mjs +1 -1
  47. package/dist/runtime/bun.mjs +1 -1
  48. package/dist/runtime/deno.mjs +2 -2
  49. package/dist/runtime/node.mjs +2 -2
  50. package/dist/version.mjs +1 -1
  51. package/examples/basic.ts +5 -1
  52. package/examples/gh/package.json +2 -7
  53. package/examples/pwsh-demo/package.json +1 -7
  54. package/examples/pwsh-demo/src/main.test.ts +1 -4
  55. package/examples/pwsh-demo/src/main.ts +14 -4
  56. package/examples/transport-launcher.ts +85 -0
  57. package/package.json +15 -24
  58. package/src/core/cli/dispatch.ts +7 -1
  59. package/src/core/cli/index.ts +521 -122
  60. package/src/core/cli/planner.ts +192 -23
  61. package/src/core/cli/root-help.ts +195 -105
  62. package/src/core/cli/root-surface.ts +25 -12
  63. package/src/core/cli/runtime-preflight.ts +43 -8
  64. package/src/core/completion/index.ts +50 -0
  65. package/src/core/completion/shells/powershell.ts +2 -2
  66. package/src/core/completion/shells/shared.ts +30 -3
  67. package/src/core/config/index.ts +12 -2
  68. package/src/core/config/package-json.ts +250 -41
  69. package/src/core/execution/index.ts +1 -4
  70. package/src/core/help/index.ts +57 -10
  71. package/src/core/json-schema/index.ts +23 -4
  72. package/src/core/json-schema/meta-descriptions.generated.ts +115 -98
  73. package/src/core/parse/index.ts +62 -1
  74. package/src/core/prompt/index.ts +54 -14
  75. package/src/core/resolve/coerce.ts +73 -5
  76. package/src/core/resolve/flags.ts +14 -0
  77. package/src/core/resolve/property.ts +4 -4
  78. package/src/core/schema/arg.ts +125 -3
  79. package/src/core/schema/command.ts +3 -1
  80. package/src/core/schema/flag.ts +120 -4
  81. package/src/core/schema/index.ts +5 -0
  82. package/src/core/schema/number-constraints.ts +153 -0
  83. package/src/core/schema/prompt.ts +15 -0
  84. package/src/core/schema/run.ts +4 -4
  85. package/src/core/testkit/index.ts +32 -8
  86. package/src/index.ts +8 -0
  87. package/src/runtime/auto.ts +0 -24
  88. package/src/runtime/bun.ts +0 -7
  89. package/src/runtime/deno.ts +0 -2
  90. package/src/runtime/node.ts +0 -11
  91. package/src/runtime/support.ts +1 -59
  92. package/src/schema.ts +16 -0
  93. package/dist/runtime/support.d.mts +0 -42
  94. package/dist/runtime/support.mjs +0 -1
package/CHANGELOG.md CHANGED
@@ -7,6 +7,172 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [3.0.0-rc.1] - 2026-07-02
11
+
12
+ ### Added
13
+
14
+ - **`.completions({ as: 'flag' })`** — expose shell completion as an eager
15
+ `--completions <shell>` flag on the CLI root instead of a `completions`
16
+ subcommand. The planner intercepts the flag before dispatch, prints the script,
17
+ and exits; root help advertises `--completions <bash|zsh|fish|powershell>` in its
18
+ `Flags:` section. `.completions()` still defaults to `{ as: 'command' }`. Because
19
+ the eager flag is intercepted before dispatch, the `--completions` name is
20
+ reserved in flag mode — declaring a command/default flag of that name throws at
21
+ build time.
22
+ - **Shell auto-detection** — `--completions` with no value (flag form) resolves the
23
+ target shell from the environment: `$SHELL` (parsed as an interpreter path) wins
24
+ when it names a supported shell, otherwise the presence of `$PSModulePath` selects
25
+ PowerShell — the reliable signal for `pwsh`, which never sets `$SHELL`.
26
+ - **`detectShell(env)` / `normalizeShell(raw)`** — exported helpers behind the
27
+ detection above; `normalizeShell` accepts bare names, `$SHELL` paths, and the
28
+ `pwsh`/`powershell` pair.
29
+ - **`.help(config)` builder + extended `HelpOptions`** — configure root-help
30
+ rendering: `inlineDefault`, `showDefaultInCommands`, and `footer` (plus the
31
+ existing `width` / `hyperlinks`). Builder config is merged under runtime
32
+ `options.help` (runtime wins).
33
+ - **Numeric constraints for number flags and args** — `flag.number()` and
34
+ `arg.number()` now accept `{ min?, max?, int?, finite? }` (bounds inclusive),
35
+ and the same constraints compose via chained `.int()` / `.min(n)` / `.max(n)` /
36
+ `.finite(allow?)` methods (a later call overrides an earlier value, including
37
+ one set in the options object). The chained methods are compile-time guarded
38
+ to number-kind builders only. Constraints are enforced identically across the
39
+ parse path and the env/config/prompt resolution path (order: finite → int →
40
+ min → max): parse-time (CLI) violations throw `INVALID_VALUE`, while
41
+ env/config/prompt coercion reports `CONSTRAINT_VIOLATED` (both exit code `2`).
42
+ They are also surfaced in the exported JSON Schema as `minimum` / `maximum` and
43
+ `type: "integer"` when `int` is set. `min` / `max` must be finite — a
44
+ non-finite bound (`Infinity` / `-Infinity` / `NaN`) throws at construction. The
45
+ resolved TypeScript value type stays `number`.
46
+ - **Prompt-level defaults for `confirm` and `input` prompts** — `confirm`
47
+ prompts accept `default?: boolean` (drives the `(Y/n)` vs `(y/N)` hint and the
48
+ empty-line result, so a confirm can default to **No**), and `input` prompts
49
+ accept `default?: string` (shown in the hint as `(default: <value>)` and used
50
+ when the user presses Enter, skipping `validate`). Precedence among defaults is
51
+ prompt-level `default` > flag `.default()`. Unset `confirm` default stays
52
+ backward compatible (`true`).
53
+
54
+ ### Changed
55
+
56
+ - **BREAKING — the default command is now the root _surface_, not a named
57
+ subcommand.** `.default(cmd)` registers the command only as the default; it is no
58
+ longer added to `schema.commands`. Consequences:
59
+ - It can no longer be invoked by its own name (`mycli mycmd` does not route to it;
60
+ the token is treated as input to the default command).
61
+ - It is omitted from the root `Commands:` list by default (re-enable with
62
+ `.help({ showDefaultInCommands: true })`).
63
+ - Root `--help` renders the default command's `Arguments:`/`Flags:` inline even
64
+ when sibling commands exist (previously only when it was the sole command), and a
65
+ sole default with no subcommands shows its own usage line directly instead of a
66
+ `[command]` placeholder.
67
+ - **`finite` defaults to `true` (behavior change)** — `flag.number()` /
68
+ `arg.number()` now **reject `Infinity` and `-Infinity`**, which previously
69
+ passed straight through to handlers (`Number("Infinity")` is not `NaN`). Pass
70
+ `{ finite: false }` (or `.finite(false)`) to opt back into accepting non-finite
71
+ values. `NaN` continues to be rejected as before.
72
+ - **BREAKING — the runtime no longer hard-fails the host CLI on its version.**
73
+ Adapter construction previously threw (a bare, uncaught `Error`) when the
74
+ detected Node/Bun/Deno version was below DreamCLI's declared minimum, crashing
75
+ the consumer's CLI — including on `--help`. That check is removed: as a
76
+ dependency the consumer's package manager already enforces the `engines` range
77
+ at install time (and more softly), and when DreamCLI is bundled/inlined the
78
+ consumer — not us — owns their CLI's supported-runtime policy. `SUPPORTED_RUNTIMES`
79
+ and the generated `engines` minimums are unchanged and remain the source of
80
+ truth for docs and packaging.
81
+
82
+ ### Fixed
83
+
84
+ - **Empty `input`-prompt answer no longer clobbers a flag's `.default()`** — a
85
+ flag declared with both `.default(...)` and an `input` prompt previously
86
+ resolved to `""` when the user submitted an empty line, because empty input was
87
+ treated as a real answer that short-circuited the default fallback. An empty or
88
+ blank `input` answer with no prompt-level `default` is now treated as "no
89
+ answer", so resolution falls through to the flag's `.default()` (or, for a
90
+ required flag, the standard missing-flag error).
91
+
92
+ ### Fixed
93
+
94
+ - **Root `--help` now matches consistently with `--version`** (#29) — previously
95
+ `--help` / `-h` were intercepted at the root only when they were the very first
96
+ token, while `--version` / `-V` matched anywhere before `--`. A help flag
97
+ preceded only by flags (e.g. `mycli --verbose --help`) now shows root help,
98
+ mirroring `mycli --verbose --version`. A help flag that follows a subcommand
99
+ token still scopes to that subcommand (`mycli deploy --help` → `deploy` help);
100
+ `--version` remains a global, position-independent flag by design (there is no
101
+ per-command version). The bare `help` token now triggers root help from the same
102
+ position as `--help`, and the `--` end-of-options separator is respected for both.
103
+ - **Generated `--help` now advertises the active built-in global flags** (#32) — root
104
+ help renders a `Global options:` block listing `--help, -h` and `--json` (always),
105
+ `--version, -V` (when a version is set), and `--config <path>` (when `.config()`
106
+ enabled config discovery). Previously these framework-provided flags were invisible
107
+ in help even though they worked. `--completions` is unchanged (still advertised via
108
+ the inline surface when active).
109
+ - **Root usage no longer prints the default command's name** — the merged/sole-default
110
+ usage line rendered `Usage: <bin> <default-name> …`, teaching an invocation that does
111
+ not route (`.default()` is not a named command, so the token is consumed as the
112
+ default's first positional). It now renders under the bin name only
113
+ (`Usage: <bin> [flags] <args>`).
114
+ - **`inlineDefault: false` no longer hides a sole default command's interface** — when
115
+ the default command is the only surface (no visible subcommands and no eager
116
+ `--completions` flag), root help would collapse to a bare `Usage: <bin> [options]`
117
+ with no discoverable args/flags. The default is now always rendered inline in that
118
+ case, since suppressing it leaves no other path to its interface.
119
+
120
+ ### Fixed
121
+
122
+ - **`runCommand()` now honors a CLI-level `--json` passed in `argv`** — the testkit
123
+ gained the same root-flag layer as the real CLI: a `--json` before the `--`
124
+ separator enables JSON mode and is stripped before parsing, instead of failing
125
+ with `Unknown flag --json` (exit 2). A literal `--json` after `--` still reaches
126
+ the command unchanged. The existing `{ jsonMode: true }` option keeps working —
127
+ either source enables JSON mode. Copying a real `mycli --json …` invocation into a
128
+ test now works verbatim.
129
+ - **`createTestPrompter()` now runs an `input` prompt's `validate`** — a queued
130
+ string answer to an `input` prompt is validated exactly as the terminal prompter
131
+ does; an answer that fails validation is rejected as a cancellation rather than
132
+ injected verbatim as the resolved value, so prompt validation is integration-testable
133
+ through `runCommand(cmd, argv, { answers })`. Non-string answers stay verbatim so
134
+ downstream coercion paths remain testable.
135
+
136
+ ## [2.5.0] - 2026-06-28
137
+
138
+ ### Added
139
+
140
+ - **`.manifest()` — runtime-agnostic manifest discovery** — discover CLI metadata
141
+ from any manifest file, not just `package.json`. Pass `files` to choose candidate
142
+ filenames in priority order (e.g. `['deno.json', 'jsr.json']`); discovery walks up
143
+ from `cwd` (or `from`) and the nearest manifest directory wins. Files are parsed as
144
+ JSON with a JSONC fallback, so `package.json`, `deno.json`, `jsr.json`, and
145
+ `deno.jsonc` all work — including manifests with `//` / block comments or trailing
146
+ commas (a dependency-free, string-aware strip that leaves `//` inside string values
147
+ such as URLs untouched).
148
+ - **`discoverManifest()`** — the generalized discovery helper behind `.manifest()`,
149
+ accepting `{ startDir, files }`.
150
+ - **Optional scope retention in name inference** — `inferName` now accepts
151
+ `{ scope: 'keep' | 'strip' }` (and `inferCliName(pkg, { stripScope })`) so a scoped
152
+ `name` like `@scope/mycli` can be kept verbatim instead of always stripping to
153
+ `mycli`. Relevant for `deno.json` / `jsr.json`, which have no `bin` field.
154
+ - **`.denoJson()`** — deprecated convenience preset for
155
+ `.manifest({ files: ['deno.json', 'deno.jsonc', 'jsr.json'] })` (see Deprecated below).
156
+
157
+ ### Changed
158
+
159
+ - **Manifest discovery now requires recognized metadata to count as a hit** — a
160
+ parseable but metadata-less manifest (`{}`, or one carrying only non-metadata
161
+ fields such as `dependencies` / `scripts` / `type`, or a config-only `deno.json`
162
+ with just `tasks` / `imports`) is no longer treated as a match. Discovery now
163
+ walks up to parent directories and tries the remaining candidate files instead
164
+ of halting. This also changes the deprecated `discoverPackageJson()` /
165
+ `.packageJson()`: where a metadata-less `package.json` previously halted the
166
+ walk-up and resolved to `{}`, the walk-up now continues, so an ancestor's
167
+ version can surface (relevant in monorepos). Pass pre-loaded `data` or an
168
+ explicit `from` / `startDir` to pin discovery to one directory.
169
+
170
+ ### Deprecated
171
+
172
+ - **`.packageJson()`, `.denoJson()`, and `discoverPackageJson()`** — superseded by
173
+ `.manifest()` / `discoverManifest()`, whose defaults (`['package.json']`) match the
174
+ old behavior. All still work, delegating to the generalized path.
175
+
10
176
  ## [2.4.1] - 2026-06-27
11
177
 
12
178
  ### Fixed
@@ -838,7 +1004,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
838
1004
  - MIT License.
839
1005
  - Markdownlint configuration.
840
1006
 
841
- [Unreleased]: https://github.com/kjanat/dreamcli/compare/v2.4.1...HEAD
1007
+ [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.1...HEAD
1008
+ [3.0.0-rc.1]: https://github.com/kjanat/dreamcli/compare/v2.5.0...v3.0.0-rc.1
1009
+ [2.5.0]: https://github.com/kjanat/dreamcli/compare/v2.4.1...v2.5.0
842
1010
  [2.4.1]: https://github.com/kjanat/dreamcli/compare/v2.4.0...v2.4.1
843
1011
  [2.4.0]: https://github.com/kjanat/dreamcli/compare/v2.3.0...v2.4.0
844
1012
  [2.3.0]: https://github.com/kjanat/dreamcli/compare/v2.2.1...v2.3.0
package/README.md CHANGED
@@ -76,7 +76,11 @@ const greet = command('greet')
76
76
  flag.number().default(1).describe('Repeat count'),
77
77
  )
78
78
  .action(({ args, flags, out }) => {
79
- for (let i = 0; i < flags.times; i++) {
79
+ const repeatCount = Number.isFinite(flags.times)
80
+ ? Math.max(0, Math.min(100, Math.floor(flags.times)))
81
+ : 1;
82
+
83
+ for (let i = 0; i < repeatCount; i++) {
80
84
  const msg = `Hello, ${args.name}!`;
81
85
  out.log(flags.loud ? msg.toUpperCase() : msg);
82
86
  }
@@ -531,7 +535,7 @@ expect(activity.activity).toContainEqual(
531
535
 
532
536
  ## Package structure
533
537
 
534
- Three subpath exports, each with a focused API surface:
538
+ The code lives behind three focused subpath exports:
535
539
 
536
540
  | Import | Purpose |
537
541
  | -------------------------- | -------------------------------------------------------------------------------------- |
@@ -539,15 +543,18 @@ Three subpath exports, each with a focused API surface:
539
543
  | `@kjanat/dreamcli/testkit` | `runCommand()`, `createCaptureOutput()`, `createTestPrompter()`, `createTestAdapter()` |
540
544
  | `@kjanat/dreamcli/runtime` | `createAdapter()`, `RuntimeAdapter`, runtime detection, platform adapters |
541
545
 
546
+ A fourth export, `@kjanat/dreamcli/schema`, ships the bundled JSON Schema (`dreamcli.schema.json`)
547
+ for editor and config validation.
548
+
542
549
  ESM-only. Source included in package (`src/`).
543
550
 
544
551
  ## Runtime support
545
552
 
546
- | Runtime | Status |
547
- | ------------------ | ----------------------------------- |
548
- | Node.js >= 22.22.2 | Supported |
549
- | Bun >= 1.3 | Supported |
550
- | Deno >= 2.6.0 | Supported (JSR: `@kjanat/dreamcli`) |
553
+ | Runtime | Status |
554
+ | ------------------ | ---------------------------------- |
555
+ | Node.js >= 22.22.2 | Supported |
556
+ | Bun >= 1.3 | Supported |
557
+ | Deno >= 2.6.0 | Supported (`jsr:@kjanat/dreamcli`) |
551
558
 
552
559
  Runtime detection is automatic.
553
560
  The core framework never imports platform-specific APIs directly — a thin `RuntimeAdapter` interface