@kjanat/dreamcli 2.5.0 → 3.0.0-rc.2

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 (160) hide show
  1. package/CHANGELOG.md +153 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/dispatch.mjs +214 -1
  4. package/dist/core/cli/help-links.mjs +41 -1
  5. package/dist/core/cli/index.d.mts +109 -16
  6. package/dist/core/cli/index.mjs +901 -1
  7. package/dist/core/cli/planner.d.mts +27 -5
  8. package/dist/core/cli/planner.mjs +300 -1
  9. package/dist/core/cli/plugin.mjs +41 -1
  10. package/dist/core/cli/propagate.mjs +57 -1
  11. package/dist/core/cli/root-help.d.mts +16 -2
  12. package/dist/core/cli/root-help.mjs +208 -6
  13. package/dist/core/cli/root-surface.d.mts +18 -3
  14. package/dist/core/cli/root-surface.mjs +27 -1
  15. package/dist/core/cli/runtime-preflight.d.mts +16 -1
  16. package/dist/core/cli/runtime-preflight.mjs +168 -1
  17. package/dist/core/completion/index.d.mts +32 -1
  18. package/dist/core/completion/index.mjs +90 -1
  19. package/dist/core/completion/shells/bash.mjs +304 -3
  20. package/dist/core/completion/shells/fish.mjs +159 -2
  21. package/dist/core/completion/shells/powershell.mjs +353 -2
  22. package/dist/core/completion/shells/shared.d.mts +10 -0
  23. package/dist/core/completion/shells/shared.mjs +154 -1
  24. package/dist/core/completion/shells/zsh.mjs +244 -2
  25. package/dist/core/config/index.mjs +246 -1
  26. package/dist/core/config/package-json.mjs +385 -3
  27. package/dist/core/errors/index.mjs +87 -1
  28. package/dist/core/execution/index.mjs +189 -1
  29. package/dist/core/help/ansi.mjs +122 -2
  30. package/dist/core/help/index.d.mts +45 -1
  31. package/dist/core/help/index.mjs +329 -7
  32. package/dist/core/json-schema/index.mjs +487 -9
  33. package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
  34. package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
  35. package/dist/core/output/activity.mjs +452 -1
  36. package/dist/core/output/bind.mjs +56 -1
  37. package/dist/core/output/contracts.mjs +57 -1
  38. package/dist/core/output/display-value.mjs +32 -1
  39. package/dist/core/output/index.d.mts +21 -0
  40. package/dist/core/output/index.mjs +442 -2
  41. package/dist/core/output/renderers.mjs +46 -1
  42. package/dist/core/output/writer.mjs +12 -1
  43. package/dist/core/parse/index.d.mts +15 -1
  44. package/dist/core/parse/index.mjs +555 -1
  45. package/dist/core/prompt/index.d.mts +11 -4
  46. package/dist/core/prompt/index.mjs +348 -6
  47. package/dist/core/resolve/args.mjs +105 -1
  48. package/dist/core/resolve/coerce.mjs +279 -1
  49. package/dist/core/resolve/config.mjs +19 -1
  50. package/dist/core/resolve/errors.mjs +140 -2
  51. package/dist/core/resolve/flags.mjs +196 -1
  52. package/dist/core/resolve/index.mjs +85 -1
  53. package/dist/core/resolve/property.d.mts +2 -1
  54. package/dist/core/resolve/property.mjs +45 -1
  55. package/dist/core/schema/arg.d.mts +90 -10
  56. package/dist/core/schema/arg.mjs +463 -1
  57. package/dist/core/schema/command.d.mts +21 -1
  58. package/dist/core/schema/command.mjs +712 -1
  59. package/dist/core/schema/flag.d.mts +92 -2
  60. package/dist/core/schema/flag.mjs +453 -1
  61. package/dist/core/schema/index.d.mts +2 -1
  62. package/dist/core/schema/middleware.mjs +41 -1
  63. package/dist/core/schema/number-constraints.d.mts +96 -0
  64. package/dist/core/schema/number-constraints.mjs +60 -0
  65. package/dist/core/schema/prompt.d.mts +15 -0
  66. package/dist/core/schema/run.d.mts +4 -4
  67. package/dist/core/schema-dsl/runtime.mjs +271 -2
  68. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  69. package/dist/core/testkit/index.d.mts +9 -5
  70. package/dist/core/testkit/index.mjs +83 -1
  71. package/dist/index.d.mts +3 -1
  72. package/dist/index.mjs +22 -1
  73. package/dist/runtime/adapter.mjs +82 -1
  74. package/dist/runtime/auto.mjs +46 -1
  75. package/dist/runtime/bun.mjs +28 -1
  76. package/dist/runtime/deno.mjs +217 -2
  77. package/dist/runtime/detect.mjs +45 -1
  78. package/dist/runtime/node.mjs +169 -2
  79. package/dist/runtime/paths.mjs +48 -1
  80. package/dist/runtime.mjs +7 -1
  81. package/dist/strings.mjs +22 -1
  82. package/dist/testkit.mjs +5 -1
  83. package/dist/version.mjs +7 -1
  84. package/examples/basic.ts +5 -1
  85. package/examples/gh/package.json +2 -7
  86. package/examples/pwsh-demo/package.json +1 -7
  87. package/examples/pwsh-demo/src/main.test.ts +1 -4
  88. package/examples/pwsh-demo/src/main.ts +14 -4
  89. package/examples/transport-launcher.ts +85 -0
  90. package/package.json +23 -41
  91. package/dist/runtime/support.d.mts +0 -42
  92. package/dist/runtime/support.mjs +0 -1
  93. package/src/core/cli/dispatch.ts +0 -349
  94. package/src/core/cli/help-links.ts +0 -82
  95. package/src/core/cli/index.ts +0 -1413
  96. package/src/core/cli/planner.ts +0 -487
  97. package/src/core/cli/plugin.ts +0 -117
  98. package/src/core/cli/propagate.ts +0 -97
  99. package/src/core/cli/root-help.ts +0 -252
  100. package/src/core/cli/root-surface.ts +0 -74
  101. package/src/core/cli/runtime-preflight.ts +0 -438
  102. package/src/core/completion/index.ts +0 -88
  103. package/src/core/completion/shells/bash.ts +0 -459
  104. package/src/core/completion/shells/fish.ts +0 -259
  105. package/src/core/completion/shells/powershell.ts +0 -439
  106. package/src/core/completion/shells/shared.ts +0 -283
  107. package/src/core/completion/shells/zsh.ts +0 -381
  108. package/src/core/config/index.ts +0 -417
  109. package/src/core/config/package-json.ts +0 -560
  110. package/src/core/errors/index.ts +0 -193
  111. package/src/core/execution/index.ts +0 -268
  112. package/src/core/help/ansi.ts +0 -144
  113. package/src/core/help/index.ts +0 -516
  114. package/src/core/json-schema/index.ts +0 -891
  115. package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
  116. package/src/core/output/activity.ts +0 -575
  117. package/src/core/output/bind.ts +0 -59
  118. package/src/core/output/contracts.ts +0 -194
  119. package/src/core/output/display-value.ts +0 -48
  120. package/src/core/output/index.ts +0 -704
  121. package/src/core/output/renderers.ts +0 -125
  122. package/src/core/output/writer.ts +0 -46
  123. package/src/core/parse/index.ts +0 -681
  124. package/src/core/prompt/index.ts +0 -583
  125. package/src/core/resolve/args.ts +0 -144
  126. package/src/core/resolve/coerce.ts +0 -432
  127. package/src/core/resolve/config.ts +0 -26
  128. package/src/core/resolve/contracts.ts +0 -135
  129. package/src/core/resolve/errors.ts +0 -227
  130. package/src/core/resolve/flags.ts +0 -255
  131. package/src/core/resolve/index.ts +0 -108
  132. package/src/core/resolve/property.ts +0 -99
  133. package/src/core/schema/activity.ts +0 -240
  134. package/src/core/schema/arg.ts +0 -719
  135. package/src/core/schema/command.ts +0 -1498
  136. package/src/core/schema/flag.ts +0 -801
  137. package/src/core/schema/index.ts +0 -91
  138. package/src/core/schema/middleware.ts +0 -171
  139. package/src/core/schema/prompt.ts +0 -156
  140. package/src/core/schema/run.ts +0 -198
  141. package/src/core/schema-dsl/index.ts +0 -109
  142. package/src/core/schema-dsl/parse.ts +0 -262
  143. package/src/core/schema-dsl/runtime.ts +0 -609
  144. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  145. package/src/core/testkit/index.ts +0 -123
  146. package/src/index.ts +0 -179
  147. package/src/runtime/adapter.ts +0 -303
  148. package/src/runtime/auto.ts +0 -110
  149. package/src/runtime/bun.ts +0 -55
  150. package/src/runtime/deno.ts +0 -369
  151. package/src/runtime/detect.ts +0 -105
  152. package/src/runtime/index.ts +0 -21
  153. package/src/runtime/node-builtins.d.ts +0 -27
  154. package/src/runtime/node.ts +0 -300
  155. package/src/runtime/paths.ts +0 -64
  156. package/src/runtime/support.ts +0 -135
  157. package/src/runtime.ts +0 -31
  158. package/src/strings.ts +0 -34
  159. package/src/testkit.ts +0 -25
  160. package/src/version.ts +0 -20
package/CHANGELOG.md CHANGED
@@ -7,6 +7,156 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [3.0.0-rc.2] - 2026-07-06
11
+
12
+ ### Added
13
+
14
+ - **`out.color` — context-aware ANSI colors** — every handler's `out` now carries
15
+ a color palette powered by [`ansispeck`](https://github.com/kjanat/ansispeck).
16
+ Colors auto-enable only when stdout is a TTY, JSON mode is off, and the
17
+ environment supports color (`NO_COLOR`, `FORCE_COLOR`, `--no-color`, `--color`,
18
+ `CI` respected); otherwise every formatter is an identity function, so handlers
19
+ can write `out.log(out.color.green('✔ done'))` unconditionally.
20
+ `createOutput({ color })` forces the palette on/off (useful for asserting
21
+ colored output in tests), and the `Colors` type is re-exported from the root
22
+ entrypoint. First runtime dependency — kept external in `dist` (~1 kB gzipped
23
+ install).
24
+
25
+ ### Changed
26
+
27
+ - **npm package now resolves built `dist` on every runtime** — the `bun`/`deno`
28
+ → `src/*.ts` export conditions are gone and `src` is no longer published to
29
+ npm (JSR still ships source). Bun and Deno consumers previously loaded raw
30
+ source where build-time defines never ran, so `version` reported `'dev'`;
31
+ they now get the same tested output as Node, with the real version. The
32
+ export map is generated by tsdown at build time instead of hand-maintained.
33
+
34
+ ## [3.0.0-rc.1] - 2026-07-02
35
+
36
+ ### Added
37
+
38
+ - **`.completions({ as: 'flag' })`** — expose shell completion as an eager
39
+ `--completions <shell>` flag on the CLI root instead of a `completions`
40
+ subcommand. The planner intercepts the flag before dispatch, prints the script,
41
+ and exits; root help advertises `--completions <bash|zsh|fish|powershell>` in its
42
+ `Flags:` section. `.completions()` still defaults to `{ as: 'command' }`. Because
43
+ the eager flag is intercepted before dispatch, the `--completions` name is
44
+ reserved in flag mode — declaring a command/default flag of that name throws at
45
+ build time.
46
+ - **Shell auto-detection** — `--completions` with no value (flag form) resolves the
47
+ target shell from the environment: `$SHELL` (parsed as an interpreter path) wins
48
+ when it names a supported shell, otherwise the presence of `$PSModulePath` selects
49
+ PowerShell — the reliable signal for `pwsh`, which never sets `$SHELL`.
50
+ - **`detectShell(env)` / `normalizeShell(raw)`** — exported helpers behind the
51
+ detection above; `normalizeShell` accepts bare names, `$SHELL` paths, and the
52
+ `pwsh`/`powershell` pair.
53
+ - **`.help(config)` builder + extended `HelpOptions`** — configure root-help
54
+ rendering: `inlineDefault`, `showDefaultInCommands`, and `footer` (plus the
55
+ existing `width` / `hyperlinks`). Builder config is merged under runtime
56
+ `options.help` (runtime wins).
57
+ - **Numeric constraints for number flags and args** — `flag.number()` and
58
+ `arg.number()` now accept `{ min?, max?, int?, finite? }` (bounds inclusive),
59
+ and the same constraints compose via chained `.int()` / `.min(n)` / `.max(n)` /
60
+ `.finite(allow?)` methods (a later call overrides an earlier value, including
61
+ one set in the options object). The chained methods are compile-time guarded
62
+ to number-kind builders only. Constraints are enforced identically across the
63
+ parse path and the env/config/prompt resolution path (order: finite → int →
64
+ min → max): parse-time (CLI) violations throw `INVALID_VALUE`, while
65
+ env/config/prompt coercion reports `CONSTRAINT_VIOLATED` (both exit code `2`).
66
+ They are also surfaced in the exported JSON Schema as `minimum` / `maximum` and
67
+ `type: "integer"` when `int` is set. `min` / `max` must be finite — a
68
+ non-finite bound (`Infinity` / `-Infinity` / `NaN`) throws at construction. The
69
+ resolved TypeScript value type stays `number`.
70
+ - **Prompt-level defaults for `confirm` and `input` prompts** — `confirm`
71
+ prompts accept `default?: boolean` (drives the `(Y/n)` vs `(y/N)` hint and the
72
+ empty-line result, so a confirm can default to **No**), and `input` prompts
73
+ accept `default?: string` (shown in the hint as `(default: <value>)` and used
74
+ when the user presses Enter, skipping `validate`). Precedence among defaults is
75
+ prompt-level `default` > flag `.default()`. Unset `confirm` default stays
76
+ backward compatible (`true`).
77
+
78
+ ### Changed
79
+
80
+ - **BREAKING — the default command is now the root _surface_, not a named
81
+ subcommand.** `.default(cmd)` registers the command only as the default; it is no
82
+ longer added to `schema.commands`. Consequences:
83
+ - It can no longer be invoked by its own name (`mycli mycmd` does not route to it;
84
+ the token is treated as input to the default command).
85
+ - It is omitted from the root `Commands:` list by default (re-enable with
86
+ `.help({ showDefaultInCommands: true })`).
87
+ - Root `--help` renders the default command's `Arguments:`/`Flags:` inline even
88
+ when sibling commands exist (previously only when it was the sole command), and a
89
+ sole default with no subcommands shows its own usage line directly instead of a
90
+ `[command]` placeholder.
91
+ - **`finite` defaults to `true` (behavior change)** — `flag.number()` /
92
+ `arg.number()` now **reject `Infinity` and `-Infinity`**, which previously
93
+ passed straight through to handlers (`Number("Infinity")` is not `NaN`). Pass
94
+ `{ finite: false }` (or `.finite(false)`) to opt back into accepting non-finite
95
+ values. `NaN` continues to be rejected as before.
96
+ - **BREAKING — the runtime no longer hard-fails the host CLI on its version.**
97
+ Adapter construction previously threw (a bare, uncaught `Error`) when the
98
+ detected Node/Bun/Deno version was below DreamCLI's declared minimum, crashing
99
+ the consumer's CLI — including on `--help`. That check is removed: as a
100
+ dependency the consumer's package manager already enforces the `engines` range
101
+ at install time (and more softly), and when DreamCLI is bundled/inlined the
102
+ consumer — not us — owns their CLI's supported-runtime policy. `SUPPORTED_RUNTIMES`
103
+ and the generated `engines` minimums are unchanged and remain the source of
104
+ truth for docs and packaging.
105
+
106
+ ### Fixed
107
+
108
+ - **Empty `input`-prompt answer no longer clobbers a flag's `.default()`** — a
109
+ flag declared with both `.default(...)` and an `input` prompt previously
110
+ resolved to `""` when the user submitted an empty line, because empty input was
111
+ treated as a real answer that short-circuited the default fallback. An empty or
112
+ blank `input` answer with no prompt-level `default` is now treated as "no
113
+ answer", so resolution falls through to the flag's `.default()` (or, for a
114
+ required flag, the standard missing-flag error).
115
+
116
+ ### Fixed
117
+
118
+ - **Root `--help` now matches consistently with `--version`** (#29) — previously
119
+ `--help` / `-h` were intercepted at the root only when they were the very first
120
+ token, while `--version` / `-V` matched anywhere before `--`. A help flag
121
+ preceded only by flags (e.g. `mycli --verbose --help`) now shows root help,
122
+ mirroring `mycli --verbose --version`. A help flag that follows a subcommand
123
+ token still scopes to that subcommand (`mycli deploy --help` → `deploy` help);
124
+ `--version` remains a global, position-independent flag by design (there is no
125
+ per-command version). The bare `help` token now triggers root help from the same
126
+ position as `--help`, and the `--` end-of-options separator is respected for both.
127
+ - **Generated `--help` now advertises the active built-in global flags** (#32) — root
128
+ help renders a `Global options:` block listing `--help, -h` and `--json` (always),
129
+ `--version, -V` (when a version is set), and `--config <path>` (when `.config()`
130
+ enabled config discovery). Previously these framework-provided flags were invisible
131
+ in help even though they worked. `--completions` is unchanged (still advertised via
132
+ the inline surface when active).
133
+ - **Root usage no longer prints the default command's name** — the merged/sole-default
134
+ usage line rendered `Usage: <bin> <default-name> …`, teaching an invocation that does
135
+ not route (`.default()` is not a named command, so the token is consumed as the
136
+ default's first positional). It now renders under the bin name only
137
+ (`Usage: <bin> [flags] <args>`).
138
+ - **`inlineDefault: false` no longer hides a sole default command's interface** — when
139
+ the default command is the only surface (no visible subcommands and no eager
140
+ `--completions` flag), root help would collapse to a bare `Usage: <bin> [options]`
141
+ with no discoverable args/flags. The default is now always rendered inline in that
142
+ case, since suppressing it leaves no other path to its interface.
143
+
144
+ ### Fixed
145
+
146
+ - **`runCommand()` now honors a CLI-level `--json` passed in `argv`** — the testkit
147
+ gained the same root-flag layer as the real CLI: a `--json` before the `--`
148
+ separator enables JSON mode and is stripped before parsing, instead of failing
149
+ with `Unknown flag --json` (exit 2). A literal `--json` after `--` still reaches
150
+ the command unchanged. The existing `{ jsonMode: true }` option keeps working —
151
+ either source enables JSON mode. Copying a real `mycli --json …` invocation into a
152
+ test now works verbatim.
153
+ - **`createTestPrompter()` now runs an `input` prompt's `validate`** — a queued
154
+ string answer to an `input` prompt is validated exactly as the terminal prompter
155
+ does; an answer that fails validation is rejected as a cancellation rather than
156
+ injected verbatim as the resolved value, so prompt validation is integration-testable
157
+ through `runCommand(cmd, argv, { answers })`. Non-string answers stay verbatim so
158
+ downstream coercion paths remain testable.
159
+
10
160
  ## [2.5.0] - 2026-06-28
11
161
 
12
162
  ### Added
@@ -878,7 +1028,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
878
1028
  - MIT License.
879
1029
  - Markdownlint configuration.
880
1030
 
881
- [Unreleased]: https://github.com/kjanat/dreamcli/compare/v2.5.0...HEAD
1031
+ [Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.2...HEAD
1032
+ [3.0.0-rc.2]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.1...v3.0.0-rc.2
1033
+ [3.0.0-rc.1]: https://github.com/kjanat/dreamcli/compare/v2.5.0...v3.0.0-rc.1
882
1034
  [2.5.0]: https://github.com/kjanat/dreamcli/compare/v2.4.1...v2.5.0
883
1035
  [2.4.1]: https://github.com/kjanat/dreamcli/compare/v2.4.0...v2.4.1
884
1036
  [2.4.0]: https://github.com/kjanat/dreamcli/compare/v2.3.0...v2.4.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,6 +543,9 @@ 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
@@ -1 +1,214 @@
1
- import{buildFlagLookup as e,flagExpectsValue as t}from"../parse/index.mjs";function n(t,i,a=[],s=new Map){let c=-1;for(let e=0;e<t.length;e++){let n=t[e];if(n!==void 0){if(n===`--`){e+1<t.length&&(c=e+1);break}if(n.startsWith(`-`)){r(n,s)&&e++;continue}c=e;break}}if(c===-1)return{kind:`unknown`,input:``,candidates:o(i),parentPath:a};let l=t[c];if(l===void 0)return{kind:`unknown`,input:``,candidates:o(i),parentPath:a};let u=i.get(l);if(u===void 0)return{kind:`unknown`,input:l,candidates:o(i),parentPath:a};let d=[...t.slice(0,c),...t.slice(c+1)],f=[...a,u.schema];if(u.subcommands.size>0){let t=n(d,u.subcommands,f,e(u.schema.flags));switch(t.kind){case`match`:return t;case`unknown`:return t.input===``?u.schema.hasAction?{kind:`match`,command:u,commandPath:f,remainingArgv:d}:{kind:`needs-subcommand`,command:u,commandPath:f}:u.schema.hasAction?{kind:`match`,command:u,commandPath:f,remainingArgv:d}:t;case`needs-subcommand`:return t;default:return t}}return{kind:`match`,command:u,commandPath:f,remainingArgv:d}}function r(e,n){if(e.startsWith(`--`)){if(e.includes(`=`))return!1;let r=n.get(e.slice(2));return r!==void 0&&t(r[1])}let r=e.slice(1);for(let e=0;e<r.length;e++){let i=n.get(r.charAt(e));if(i===void 0)return!1;if(t(i[1]))return e===r.length-1}return!1}function i(e,t){let n=e.length,r=t.length,i=r+1,a=new Uint16Array(i),o=new Uint16Array(i);for(let e=0;e<=r;e++)a[e]=e;for(let i=1;i<=n;i++){o[0]=i;for(let n=1;n<=r;n++){let r=e.charAt(i-1)===t.charAt(n-1)?0:1,s=a[n]??0,c=o[n-1]??0,l=a[n-1]??0;o[n]=Math.min(s+1,c+1,l+r)}[a,o]=[o,a]}return a[r]??Math.max(n,r)}function a(e,t){let n,r=4;for(let a of t){let t=i(e,a.schema.name);t<r&&(r=t,n=a.schema.name);for(let t of a.schema.aliases){let o=i(e,t);o<r&&(r=o,n=a.schema.name)}}return r<=3?n:void 0}function o(e){let t=new Set,n=[];for(let r of e.values())t.has(r)||(t.add(r),n.push(r));return n}export{n as dispatch,a as findClosestCommand};
1
+ import { buildFlagLookup, flagExpectsValue } from "../parse/index.mjs";
2
+ //#region src/core/cli/dispatch.ts
3
+ /**
4
+ * Recursive command dispatch for nested command trees.
5
+ *
6
+ * Walks argv segments, matching command names at each level of the tree.
7
+ * Returns a discriminated union describing the dispatch outcome: a matched
8
+ * command with its ancestor path, a group that needs a subcommand, or an
9
+ * unknown command with suggestion candidates.
10
+ *
11
+ * @module dreamcli/core/cli/dispatch
12
+ * @internal
13
+ */
14
+ /**
15
+ * Recursively walk argv, consuming command name segments from the front.
16
+ *
17
+ * At each level, the first non-flag token is tested as a command name
18
+ * against the provided command map. If matched and the matched command
19
+ * has subcommands, dispatch recurses into the child level with the
20
+ * remaining argv.
21
+ *
22
+ * Ambiguity resolution for commands that have both an action handler AND
23
+ * subcommands (e.g. `git remote` lists remotes, `git remote add` dispatches):
24
+ * - If the next token matches a subcommand → descend
25
+ * - If the next token is unknown and the command has a handler → match here
26
+ * - If the next token is unknown and no handler → propagate unknown error
27
+ * - If no next token and command has a handler → match here
28
+ * - If no next token and no handler → needs-subcommand
29
+ *
30
+ * @param argv - Remaining argv tokens (command names + flags + args).
31
+ * @param commands - Command map at the current tree level.
32
+ * @param ancestorPath - Schema path from root to current level (exclusive).
33
+ * @param valueFlags - Lookup of flags valid at this level, used so a
34
+ * space-separated value-flag's value (`--region eu`) is not mistaken for a
35
+ * command name. Empty by default (arity-unaware, legacy behaviour).
36
+ * @returns Discriminated dispatch result.
37
+ *
38
+ * @internal
39
+ */
40
+ function dispatch(argv, commands, ancestorPath = [], valueFlags = /* @__PURE__ */ new Map()) {
41
+ let cmdIdx = -1;
42
+ for (let i = 0; i < argv.length; i++) {
43
+ const token = argv[i];
44
+ if (token === void 0) continue;
45
+ if (token === "--") {
46
+ if (i + 1 < argv.length) cmdIdx = i + 1;
47
+ break;
48
+ }
49
+ if (token.startsWith("-")) {
50
+ if (consumesFollowingToken(token, valueFlags)) i++;
51
+ continue;
52
+ }
53
+ cmdIdx = i;
54
+ break;
55
+ }
56
+ if (cmdIdx === -1) return {
57
+ kind: "unknown",
58
+ input: "",
59
+ candidates: uniqueCommands(commands),
60
+ parentPath: ancestorPath
61
+ };
62
+ const cmdName = argv[cmdIdx];
63
+ if (cmdName === void 0) return {
64
+ kind: "unknown",
65
+ input: "",
66
+ candidates: uniqueCommands(commands),
67
+ parentPath: ancestorPath
68
+ };
69
+ const matched = commands.get(cmdName);
70
+ if (matched === void 0) return {
71
+ kind: "unknown",
72
+ input: cmdName,
73
+ candidates: uniqueCommands(commands),
74
+ parentPath: ancestorPath
75
+ };
76
+ const remaining = [...argv.slice(0, cmdIdx), ...argv.slice(cmdIdx + 1)];
77
+ const currentPath = [...ancestorPath, matched.schema];
78
+ if (matched.subcommands.size > 0) {
79
+ const subResult = dispatch(remaining, matched.subcommands, currentPath, buildFlagLookup(matched.schema.flags));
80
+ switch (subResult.kind) {
81
+ case "match": return subResult;
82
+ case "unknown":
83
+ if (subResult.input === "") {
84
+ if (matched.schema.hasAction) return {
85
+ kind: "match",
86
+ command: matched,
87
+ commandPath: currentPath,
88
+ remainingArgv: remaining
89
+ };
90
+ return {
91
+ kind: "needs-subcommand",
92
+ command: matched,
93
+ commandPath: currentPath
94
+ };
95
+ }
96
+ if (matched.schema.hasAction) return {
97
+ kind: "match",
98
+ command: matched,
99
+ commandPath: currentPath,
100
+ remainingArgv: remaining
101
+ };
102
+ return subResult;
103
+ case "needs-subcommand": return subResult;
104
+ default: return subResult;
105
+ }
106
+ }
107
+ return {
108
+ kind: "match",
109
+ command: matched,
110
+ commandPath: currentPath,
111
+ remainingArgv: remaining
112
+ };
113
+ }
114
+ /**
115
+ * Whether a flag token consumes the following argv token as its value.
116
+ *
117
+ * Mirrors the parser's value-consumption rules (`parseLongFlag` /
118
+ * `parseShortFlags`) so the command-name scan skips exactly the tokens the
119
+ * parser would treat as flag values:
120
+ * - `--flag value` → consumes when `--flag` is a known value-flag.
121
+ * - `--flag=value` → self-contained, consumes nothing.
122
+ * - `-abc value` → consumes only when the trailing short flag is a value-flag;
123
+ * an earlier value-flag char takes the rest of the group as an inline value.
124
+ *
125
+ * Unknown flags conservatively consume nothing (the parser reports them later).
126
+ *
127
+ * @internal
128
+ */
129
+ function consumesFollowingToken(token, valueFlags) {
130
+ if (token.startsWith("--")) {
131
+ if (token.includes("=")) return false;
132
+ const entry = valueFlags.get(token.slice(2));
133
+ return entry !== void 0 && flagExpectsValue(entry[1]);
134
+ }
135
+ const chars = token.slice(1);
136
+ for (let i = 0; i < chars.length; i++) {
137
+ const entry = valueFlags.get(chars.charAt(i));
138
+ if (entry === void 0) return false;
139
+ if (!flagExpectsValue(entry[1])) continue;
140
+ return i === chars.length - 1;
141
+ }
142
+ return false;
143
+ }
144
+ /**
145
+ * Levenshtein distance between two strings.
146
+ * @internal
147
+ */
148
+ function levenshtein(a, b) {
149
+ const m = a.length;
150
+ const n = b.length;
151
+ const w = n + 1;
152
+ let prev = new Uint16Array(w);
153
+ let curr = new Uint16Array(w);
154
+ for (let j = 0; j <= n; j++) prev[j] = j;
155
+ for (let i = 1; i <= m; i++) {
156
+ curr[0] = i;
157
+ for (let j = 1; j <= n; j++) {
158
+ const cost = a.charAt(i - 1) === b.charAt(j - 1) ? 0 : 1;
159
+ const del = prev[j] ?? 0;
160
+ const ins = curr[j - 1] ?? 0;
161
+ const sub = prev[j - 1] ?? 0;
162
+ curr[j] = Math.min(del + 1, ins + 1, sub + cost);
163
+ }
164
+ [prev, curr] = [curr, prev];
165
+ }
166
+ return prev[n] ?? Math.max(m, n);
167
+ }
168
+ /**
169
+ * Find the closest command name match for a "did you mean?" suggestion.
170
+ *
171
+ * Searches command names and aliases. Returns `undefined` if no
172
+ * sufficiently close match exists (threshold: 3).
173
+ *
174
+ * @internal
175
+ */
176
+ function findClosestCommand(input, commands) {
177
+ const MAX_DISTANCE = 3;
178
+ let bestName;
179
+ let bestDist = 4;
180
+ for (const cmd of commands) {
181
+ const nameDist = levenshtein(input, cmd.schema.name);
182
+ if (nameDist < bestDist) {
183
+ bestDist = nameDist;
184
+ bestName = cmd.schema.name;
185
+ }
186
+ for (const alias of cmd.schema.aliases) {
187
+ const aliasDist = levenshtein(input, alias);
188
+ if (aliasDist < bestDist) {
189
+ bestDist = aliasDist;
190
+ bestName = cmd.schema.name;
191
+ }
192
+ }
193
+ }
194
+ return bestDist <= MAX_DISTANCE ? bestName : void 0;
195
+ }
196
+ /**
197
+ * Deduplicate commands from a name+alias map.
198
+ *
199
+ * A map keyed by name *and* alias contains duplicate entries for aliased
200
+ * commands. This returns unique commands (by schema identity).
201
+ *
202
+ * @internal
203
+ */
204
+ function uniqueCommands(commands) {
205
+ const seen = /* @__PURE__ */ new Set();
206
+ const result = [];
207
+ for (const cmd of commands.values()) if (!seen.has(cmd)) {
208
+ seen.add(cmd);
209
+ result.push(cmd);
210
+ }
211
+ return result;
212
+ }
213
+ //#endregion
214
+ export { dispatch, findClosestCommand };
@@ -1 +1,41 @@
1
- import{packageRepositoryUrl as e}from"../config/package-json.mjs";function t(e,t){let n;try{n=new URL(e).hostname}catch{return}if(n===`github.com`)return`${e}/releases/tag/v${t}`;if(n===`gitlab.com`)return`${e}/-/releases/v${t}`}function n(n,r,i){if(n===void 0)return;if(r===void 0||n.name!==void 0&&n.version!==void 0)return n;let a=e(r);return{name:n.name??a??r.homepage,version:n.version??(a!==void 0&&i!==void 0?t(a,i):void 0)}}export{n as deriveHelpLinks};
1
+ import { packageRepositoryUrl } from "../config/package-json.mjs";
2
+ //#region src/core/cli/help-links.ts
3
+ /**
4
+ * Build the release-tag URL for a version on a known forge.
5
+ *
6
+ * GitHub and GitLab have stable release-tag routes; other hosts return
7
+ * `undefined` rather than guessing.
8
+ *
9
+ * @internal
10
+ */
11
+ function releaseTagUrl(repoUrl, version) {
12
+ let hostname;
13
+ try {
14
+ hostname = new URL(repoUrl).hostname;
15
+ } catch {
16
+ return;
17
+ }
18
+ if (hostname === "github.com") return `${repoUrl}/releases/tag/v${version}`;
19
+ if (hostname === "gitlab.com") return `${repoUrl}/-/releases/v${version}`;
20
+ }
21
+ /**
22
+ * Fill `undefined` link fields from package.json metadata.
23
+ *
24
+ * Explicit URLs always win. The name falls back to the normalized
25
+ * `repository` URL, then `homepage`; the version falls back to the forge
26
+ * release-tag URL when both a repository and a version are known.
27
+ * Idempotent — already-resolved fields pass through unchanged.
28
+ *
29
+ * @internal
30
+ */
31
+ function deriveHelpLinks(links, pkg, version) {
32
+ if (links === void 0) return void 0;
33
+ if (pkg === void 0 || links.name !== void 0 && links.version !== void 0) return links;
34
+ const repoUrl = packageRepositoryUrl(pkg);
35
+ return {
36
+ name: links.name ?? repoUrl ?? pkg.homepage,
37
+ version: links.version ?? (repoUrl !== void 0 && version !== void 0 ? releaseTagUrl(repoUrl, version) : void 0)
38
+ };
39
+ }
40
+ //#endregion
41
+ export { deriveHelpLinks };
@@ -7,6 +7,7 @@ import { RuntimeAdapter } from "../../runtime/adapter.mjs";
7
7
  import { PackageJsonData } from "../config/package-json.mjs";
8
8
  import { HelpLinks } from "./help-links.mjs";
9
9
  import { CompletionOptions } from "../completion/shells/shared.mjs";
10
+ import { Shell } from "../completion/index.mjs";
10
11
  import { FormatLoader } from "../config/index.mjs";
11
12
  import { formatRootHelp } from "./root-help.mjs";
12
13
 
@@ -69,11 +70,73 @@ interface CLISchema {
69
70
  * CLIBuilder.manifest | .manifest()}) is active.
70
71
  */
71
72
  readonly helpLinks: HelpLinks | undefined;
72
- /** Whether built-in `.completions()` command registration is active. */
73
+ /** Whether built-in `.completions()` registration (command or flag) is active. */
73
74
  readonly hasBuiltInCompletions: boolean;
75
+ /**
76
+ * Eager `--completions <shell>` flag configuration.
77
+ *
78
+ * Set when `.completions({ as: 'flag' })` is used instead of the default
79
+ * `completions` subcommand. When defined, the planner intercepts
80
+ * `--completions <shell>` before dispatch, prints the script, and exits;
81
+ * root help advertises the flag in its `Flags:` section.
82
+ */
83
+ readonly completionsFlag: CompletionsFlagConfig | undefined;
84
+ /**
85
+ * Consumer-configured root-help defaults.
86
+ *
87
+ * Set via the {@linkcode CLIBuilder.help | .help()} builder method and merged
88
+ * under runtime `options.help` (runtime wins) before rendering.
89
+ */
90
+ readonly helpConfig: HelpConfig | undefined;
74
91
  /** Registered CLI plugins. */
75
92
  readonly plugins: readonly CLIPlugin[];
76
93
  }
94
+ /**
95
+ * Configuration for the eager `--completions <shell>` flag.
96
+ *
97
+ * Stored in {@link CLISchema} when `.completions({ as: 'flag' })` is used.
98
+ *
99
+ * @internal
100
+ */
101
+ interface CompletionsFlagConfig {
102
+ /** Shell targets the flag accepts (mirrors {@link SHELLS}). */
103
+ readonly shells: readonly Shell[];
104
+ /** Generator options captured at build time (e.g. `functionPrefix`, `rootMode`). */
105
+ readonly options: CompletionOptions | undefined;
106
+ }
107
+ /**
108
+ * Consumer-facing root-help configuration set via {@linkcode CLIBuilder.help}.
109
+ *
110
+ * Every field is optional; unset fields fall back to built-in defaults and may
111
+ * be overridden per call through runtime `options.help`.
112
+ */
113
+ interface HelpConfig {
114
+ /**
115
+ * Render the default command's arguments and flags inline at the root.
116
+ *
117
+ * @defaultValue `true`
118
+ */
119
+ readonly inlineDefault?: boolean;
120
+ /**
121
+ * Also list the default command in the root `Commands:` table.
122
+ *
123
+ * By default the default command is the root surface and is omitted from the
124
+ * command list (its args/flags render inline instead).
125
+ *
126
+ * @defaultValue `false`
127
+ */
128
+ readonly showDefaultInCommands?: boolean;
129
+ /**
130
+ * Show the `Run '<bin> <command> --help' for more information.` hint.
131
+ *
132
+ * Defaults to showing the hint only when visible subcommands exist.
133
+ */
134
+ readonly footer?: boolean;
135
+ /** Maximum line width (columns). */
136
+ readonly width?: number;
137
+ /** Emit OSC 8 hyperlinks in the header when supported. */
138
+ readonly hyperlinks?: boolean;
139
+ }
77
140
  /**
78
141
  * Config discovery settings for automatic config file loading.
79
142
  *
@@ -266,6 +329,25 @@ declare class CLIBuilder {
266
329
  readonly name?: string | URL;
267
330
  readonly version?: string | URL;
268
331
  }): CLIBuilder;
332
+ /**
333
+ * Configure root-help rendering defaults.
334
+ *
335
+ * Stored on the schema and merged **under** any runtime `options.help`
336
+ * (runtime wins). Call multiple times to set fields incrementally.
337
+ *
338
+ * @param config - Help rendering options (see {@link HelpConfig}).
339
+ * @returns The builder (for chaining).
340
+ *
341
+ * @example
342
+ * ```ts
343
+ * // Echo the default command under Commands and never show the footer:
344
+ * cli('mycli')
345
+ * .help({ showDefaultInCommands: true, footer: false })
346
+ * .default(serve)
347
+ * .run();
348
+ * ```
349
+ */
350
+ help(config: HelpConfig): CLIBuilder;
269
351
  /**
270
352
  * Enable automatic config file discovery.
271
353
  *
@@ -460,8 +542,11 @@ declare class CLIBuilder {
460
542
  * dispatch normally, but empty argv or flags-only argv falls through to
461
543
  * this command instead of showing root help.
462
544
  *
463
- * The command is also registered as a normal subcommand (can be invoked
464
- * by name). Only one default command is allowed.
545
+ * The default command is the CLI's root *surface*: its flags and arguments
546
+ * are rendered inline in root help. It is **not** a named subcommand — it
547
+ * cannot be invoked by its own name (`mycli mycmd` does not route to it) and
548
+ * it is omitted from the root `Commands:` list by default (re-enable with
549
+ * `.help({ showDefaultInCommands: true })`). Only one default is allowed.
465
550
  *
466
551
  * @example
467
552
  * ```ts
@@ -496,28 +581,36 @@ declare class CLIBuilder {
496
581
  */
497
582
  plugin(definition: CLIPlugin): CLIBuilder;
498
583
  /**
499
- * Register a built-in `completions` subcommand that generates shell
500
- * completion scripts.
584
+ * Register built-in shell completion.
501
585
  *
502
- * The generated command accepts a `--shell` flag (required, enum of
503
- * all {@link Shell} values) and writes the completion script to stdout
504
- * via `out.log()`. Unsupported shells throw a descriptive {@linkcode CLIError}
505
- * instead of a generic parse error.
586
+ * By default (`{ as: 'command' }`) this registers a `completions` subcommand
587
+ * that accepts a `shell` argument and writes the script to stdout. With
588
+ * `{ as: 'flag' }` it instead exposes an eager `--completions <shell>` flag on
589
+ * the CLI root — no subcommand is registered, so a default command stays the
590
+ * lone root surface. The flag may be given without a value to auto-detect the
591
+ * shell from `$SHELL` / `$PSModulePath`.
506
592
  *
507
- * Call this **after** registering all other commands so the completion
508
- * script includes the full command set. The captured schema is a
509
- * snapshot at call time — commands registered after `.completions()`
510
- * will not appear in the generated script. Completion options are also
511
- * captured at call time.
593
+ * In subcommand mode, call this **after** registering all other commands so
594
+ * the completion script includes the full command set: that path snapshots the
595
+ * schema (and completion options) at call time, so commands registered
596
+ * afterwards will not appear in that subcommand's generated script. In flag
597
+ * mode, generation runs at execution time from the final builder schema, so
598
+ * registration order does not matter.
512
599
  *
513
600
  * @example
514
601
  * ```ts
602
+ * // Subcommand form (default):
515
603
  * cli('mycli')
516
604
  * .version('1.0.0')
517
605
  * .command(deploy)
518
- * .command(login)
519
606
  * .completions({ rootMode: 'surface' })
520
607
  * .run();
608
+ *
609
+ * // Eager-flag form, ideal for single-command CLIs:
610
+ * cli('mycli')
611
+ * .completions({ as: 'flag' })
612
+ * .default(serve)
613
+ * .run();
521
614
  * ```
522
615
  */
523
616
  completions(options?: CompletionOptions): CLIBuilder;
@@ -637,4 +730,4 @@ declare function cli(name: string): CLIBuilder;
637
730
  /** Create a new CLI program builder from an options object. */
638
731
  declare function cli(options: CLIOptions): CLIBuilder;
639
732
  //#endregion
640
- export { type BeforeParseParams, CLIBuilder, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type ConfigSettings, type HelpLinks, type InferNameOption, type ManifestPresetSettings, type ManifestSettings, type PackageJsonSettings, type PluginCommandContext, type ResolvedCommandParams, type ResolvedManifestSettings, cli, formatRootHelp, plugin };
733
+ export { type BeforeParseParams, CLIBuilder, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type CompletionsFlagConfig, type ConfigSettings, type HelpConfig, type HelpLinks, type InferNameOption, type ManifestPresetSettings, type ManifestSettings, type PackageJsonSettings, type PluginCommandContext, type ResolvedCommandParams, type ResolvedManifestSettings, cli, formatRootHelp, plugin };