@kjanat/dreamcli 2.5.0 → 3.0.0-rc.10

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 (202) hide show
  1. package/CHANGELOG.md +344 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/dispatch.d.mts +6 -5
  4. package/dist/core/cli/dispatch.mjs +205 -1
  5. package/dist/core/cli/help-links.d.mts +0 -1
  6. package/dist/core/cli/help-links.mjs +41 -1
  7. package/dist/core/cli/index.d.mts +185 -19
  8. package/dist/core/cli/index.mjs +945 -1
  9. package/dist/core/cli/planner.d.mts +32 -6
  10. package/dist/core/cli/planner.mjs +300 -1
  11. package/dist/core/cli/plugin.d.mts +1 -1
  12. package/dist/core/cli/plugin.mjs +41 -1
  13. package/dist/core/cli/propagate.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +57 -1
  15. package/dist/core/cli/root-help.d.mts +18 -3
  16. package/dist/core/cli/root-help.mjs +226 -6
  17. package/dist/core/cli/root-surface.d.mts +30 -4
  18. package/dist/core/cli/root-surface.mjs +28 -1
  19. package/dist/core/cli/runtime-preflight.d.mts +30 -3
  20. package/dist/core/cli/runtime-preflight.mjs +169 -1
  21. package/dist/core/completion/index.d.mts +32 -2
  22. package/dist/core/completion/index.mjs +90 -1
  23. package/dist/core/completion/shells/bash.d.mts +0 -1
  24. package/dist/core/completion/shells/bash.mjs +308 -3
  25. package/dist/core/completion/shells/fish.d.mts +0 -1
  26. package/dist/core/completion/shells/fish.mjs +162 -2
  27. package/dist/core/completion/shells/powershell.d.mts +0 -1
  28. package/dist/core/completion/shells/powershell.mjs +358 -2
  29. package/dist/core/completion/shells/shared.d.mts +23 -2
  30. package/dist/core/completion/shells/shared.mjs +176 -1
  31. package/dist/core/completion/shells/zsh.d.mts +0 -1
  32. package/dist/core/completion/shells/zsh.mjs +251 -2
  33. package/dist/core/config/index.d.mts +2 -3
  34. package/dist/core/config/index.mjs +246 -1
  35. package/dist/core/config/package-json.d.mts +27 -4
  36. package/dist/core/config/package-json.mjs +386 -3
  37. package/dist/core/errors/index.d.mts +3 -3
  38. package/dist/core/errors/index.mjs +87 -1
  39. package/dist/core/execution/index.d.mts +0 -1
  40. package/dist/core/execution/index.mjs +201 -1
  41. package/dist/core/help/ansi.d.mts +11 -5
  42. package/dist/core/help/ansi.mjs +121 -2
  43. package/dist/core/help/index.d.mts +65 -2
  44. package/dist/core/help/index.mjs +341 -7
  45. package/dist/core/help/theme.d.mts +68 -0
  46. package/dist/core/help/theme.mjs +46 -0
  47. package/dist/core/json-schema/index.d.mts +15 -2
  48. package/dist/core/json-schema/index.mjs +536 -12
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
  51. package/dist/core/output/activity.d.mts +0 -1
  52. package/dist/core/output/activity.mjs +452 -1
  53. package/dist/core/output/bind.mjs +56 -1
  54. package/dist/core/output/contracts.d.mts +4 -5
  55. package/dist/core/output/contracts.mjs +57 -1
  56. package/dist/core/output/display-value.mjs +32 -1
  57. package/dist/core/output/index.d.mts +21 -1
  58. package/dist/core/output/index.mjs +442 -2
  59. package/dist/core/output/renderers.d.mts +0 -1
  60. package/dist/core/output/renderers.mjs +46 -1
  61. package/dist/core/output/writer.mjs +12 -1
  62. package/dist/core/parse/index.d.mts +54 -7
  63. package/dist/core/parse/index.mjs +727 -1
  64. package/dist/core/prompt/index.d.mts +12 -4
  65. package/dist/core/prompt/index.mjs +348 -6
  66. package/dist/core/resolve/args.d.mts +1 -1
  67. package/dist/core/resolve/args.mjs +105 -1
  68. package/dist/core/resolve/coerce.d.mts +1 -1
  69. package/dist/core/resolve/coerce.mjs +336 -1
  70. package/dist/core/resolve/config.mjs +19 -1
  71. package/dist/core/resolve/contracts.d.mts +9 -4
  72. package/dist/core/resolve/errors.d.mts +0 -1
  73. package/dist/core/resolve/errors.mjs +140 -2
  74. package/dist/core/resolve/flags.d.mts +7 -2
  75. package/dist/core/resolve/flags.mjs +251 -1
  76. package/dist/core/resolve/index.d.mts +2 -2
  77. package/dist/core/resolve/index.mjs +85 -1
  78. package/dist/core/resolve/property.d.mts +6 -2
  79. package/dist/core/resolve/property.mjs +53 -1
  80. package/dist/core/schema/activity.d.mts +31 -11
  81. package/dist/core/schema/arg.d.mts +92 -13
  82. package/dist/core/schema/arg.mjs +463 -1
  83. package/dist/core/schema/command.d.mts +29 -7
  84. package/dist/core/schema/command.mjs +726 -1
  85. package/dist/core/schema/flag.d.mts +577 -21
  86. package/dist/core/schema/flag.mjs +705 -1
  87. package/dist/core/schema/index.d.mts +5 -2
  88. package/dist/core/schema/middleware.d.mts +4 -3
  89. package/dist/core/schema/middleware.mjs +41 -1
  90. package/dist/core/schema/number-constraints.d.mts +96 -0
  91. package/dist/core/schema/number-constraints.mjs +60 -0
  92. package/dist/core/schema/prompt.d.mts +21 -3
  93. package/dist/core/schema/run.d.mts +24 -5
  94. package/dist/core/schema/string-constraints.d.mts +97 -0
  95. package/dist/core/schema/string-constraints.mjs +69 -0
  96. package/dist/core/schema/value-parsers.d.mts +78 -0
  97. package/dist/core/schema/value-parsers.mjs +142 -0
  98. package/dist/core/schema-dsl/runtime.mjs +271 -2
  99. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  100. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  101. package/dist/core/testkit/index.d.mts +9 -36
  102. package/dist/core/testkit/index.mjs +83 -1
  103. package/dist/index.d.mts +12 -6
  104. package/dist/index.mjs +22 -1
  105. package/dist/runtime/adapter.d.mts +38 -2
  106. package/dist/runtime/adapter.mjs +87 -1
  107. package/dist/runtime/auto.d.mts +2 -3
  108. package/dist/runtime/auto.mjs +45 -1
  109. package/dist/runtime/deno.d.mts +24 -5
  110. package/dist/runtime/deno.mjs +262 -2
  111. package/dist/runtime/detect.mjs +45 -1
  112. package/dist/runtime/index.d.mts +3 -4
  113. package/dist/runtime/node.d.mts +8 -2
  114. package/dist/runtime/node.mjs +220 -2
  115. package/dist/runtime/paths.mjs +48 -1
  116. package/dist/runtime.d.mts +4 -4
  117. package/dist/runtime.mjs +6 -1
  118. package/dist/strings.mjs +22 -1
  119. package/dist/testkit.d.mts +1 -0
  120. package/dist/testkit.mjs +5 -1
  121. package/dist/version.d.mts +7 -3
  122. package/dist/version.mjs +7 -1
  123. package/dreamcli.schema.json +36 -7
  124. package/examples/basic.ts +5 -1
  125. package/examples/gh/package.json +2 -7
  126. package/examples/pwsh-demo/package.json +1 -7
  127. package/examples/pwsh-demo/src/main.test.ts +1 -4
  128. package/examples/pwsh-demo/src/main.ts +14 -4
  129. package/examples/transport-launcher.ts +85 -0
  130. package/package.json +43 -49
  131. package/dist/runtime/bun.d.mts +0 -28
  132. package/dist/runtime/bun.mjs +0 -1
  133. package/dist/runtime/support.d.mts +0 -42
  134. package/dist/runtime/support.mjs +0 -1
  135. package/src/core/cli/dispatch.ts +0 -349
  136. package/src/core/cli/help-links.ts +0 -82
  137. package/src/core/cli/index.ts +0 -1413
  138. package/src/core/cli/planner.ts +0 -487
  139. package/src/core/cli/plugin.ts +0 -117
  140. package/src/core/cli/propagate.ts +0 -97
  141. package/src/core/cli/root-help.ts +0 -252
  142. package/src/core/cli/root-surface.ts +0 -74
  143. package/src/core/cli/runtime-preflight.ts +0 -438
  144. package/src/core/completion/index.ts +0 -88
  145. package/src/core/completion/shells/bash.ts +0 -459
  146. package/src/core/completion/shells/fish.ts +0 -259
  147. package/src/core/completion/shells/powershell.ts +0 -439
  148. package/src/core/completion/shells/shared.ts +0 -283
  149. package/src/core/completion/shells/zsh.ts +0 -381
  150. package/src/core/config/index.ts +0 -417
  151. package/src/core/config/package-json.ts +0 -560
  152. package/src/core/errors/index.ts +0 -193
  153. package/src/core/execution/index.ts +0 -268
  154. package/src/core/help/ansi.ts +0 -144
  155. package/src/core/help/index.ts +0 -516
  156. package/src/core/json-schema/index.ts +0 -891
  157. package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
  158. package/src/core/output/activity.ts +0 -575
  159. package/src/core/output/bind.ts +0 -59
  160. package/src/core/output/contracts.ts +0 -194
  161. package/src/core/output/display-value.ts +0 -48
  162. package/src/core/output/index.ts +0 -704
  163. package/src/core/output/renderers.ts +0 -125
  164. package/src/core/output/writer.ts +0 -46
  165. package/src/core/parse/index.ts +0 -681
  166. package/src/core/prompt/index.ts +0 -583
  167. package/src/core/resolve/args.ts +0 -144
  168. package/src/core/resolve/coerce.ts +0 -432
  169. package/src/core/resolve/config.ts +0 -26
  170. package/src/core/resolve/contracts.ts +0 -135
  171. package/src/core/resolve/errors.ts +0 -227
  172. package/src/core/resolve/flags.ts +0 -255
  173. package/src/core/resolve/index.ts +0 -108
  174. package/src/core/resolve/property.ts +0 -99
  175. package/src/core/schema/activity.ts +0 -240
  176. package/src/core/schema/arg.ts +0 -719
  177. package/src/core/schema/command.ts +0 -1498
  178. package/src/core/schema/flag.ts +0 -801
  179. package/src/core/schema/index.ts +0 -91
  180. package/src/core/schema/middleware.ts +0 -171
  181. package/src/core/schema/prompt.ts +0 -156
  182. package/src/core/schema/run.ts +0 -198
  183. package/src/core/schema-dsl/index.ts +0 -109
  184. package/src/core/schema-dsl/parse.ts +0 -262
  185. package/src/core/schema-dsl/runtime.ts +0 -609
  186. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  187. package/src/core/testkit/index.ts +0 -123
  188. package/src/index.ts +0 -179
  189. package/src/runtime/adapter.ts +0 -303
  190. package/src/runtime/auto.ts +0 -110
  191. package/src/runtime/bun.ts +0 -55
  192. package/src/runtime/deno.ts +0 -369
  193. package/src/runtime/detect.ts +0 -105
  194. package/src/runtime/index.ts +0 -21
  195. package/src/runtime/node-builtins.d.ts +0 -27
  196. package/src/runtime/node.ts +0 -300
  197. package/src/runtime/paths.ts +0 -64
  198. package/src/runtime/support.ts +0 -135
  199. package/src/runtime.ts +0 -31
  200. package/src/strings.ts +0 -34
  201. package/src/testkit.ts +0 -25
  202. package/src/version.ts +0 -20
@@ -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 };
@@ -1,15 +1,18 @@
1
1
  import { ArgBuilder, ArgConfig } from "../schema/arg.mjs";
2
2
  import { FlagBuilder, FlagConfig } from "../schema/flag.mjs";
3
3
  import { BeforeParseParams, CLIPlugin, CLIPluginHooks, PluginCommandContext, ResolvedCommandParams, plugin } from "./plugin.mjs";
4
+ import { HelpThemeFactory } from "../help/theme.mjs";
5
+ import "../help/index.mjs";
4
6
  import { RunOptions, RunResult } from "../schema/run.mjs";
5
7
  import { CommandBuilder, ErasedCommand } from "../schema/command.mjs";
8
+ import { ParseOptions } from "../parse/index.mjs";
6
9
  import { RuntimeAdapter } from "../../runtime/adapter.mjs";
7
10
  import { PackageJsonData } from "../config/package-json.mjs";
8
11
  import { HelpLinks } from "./help-links.mjs";
9
12
  import { CompletionOptions } from "../completion/shells/shared.mjs";
13
+ import { Shell } from "../completion/index.mjs";
10
14
  import { FormatLoader } from "../config/index.mjs";
11
15
  import { formatRootHelp } from "./root-help.mjs";
12
-
13
16
  //#region src/core/cli/index.d.ts
14
17
  /**
15
18
  * Runtime descriptor for the CLI program.
@@ -42,6 +45,15 @@ interface CLISchema {
42
45
  * Set via the {@linkcode CLIBuilder.default | .default()} builder method.
43
46
  */
44
47
  readonly defaultCommand: ErasedCommand | undefined;
48
+ /**
49
+ * Whether the default command is also exposed as a named top-level route.
50
+ *
51
+ * Set by `.default(cmd, { route: true })`. When `true`, `mycli <name>`
52
+ * dispatches to the default command (in addition to the bare/flags-only root
53
+ * surface behavior) and the command is listed in the root `Commands:`
54
+ * section. When `false` (the default), the default is the root surface only.
55
+ */
56
+ readonly defaultCommandRouted: boolean;
45
57
  /**
46
58
  * Config discovery settings.
47
59
  *
@@ -69,11 +81,90 @@ interface CLISchema {
69
81
  * CLIBuilder.manifest | .manifest()}) is active.
70
82
  */
71
83
  readonly helpLinks: HelpLinks | undefined;
72
- /** Whether built-in `.completions()` command registration is active. */
84
+ /** Whether built-in `.completions()` registration (command or flag) is active. */
73
85
  readonly hasBuiltInCompletions: boolean;
86
+ /**
87
+ * Eager `--completions <shell>` flag configuration.
88
+ *
89
+ * Set when `.completions({ as: 'flag' })` is used instead of the default
90
+ * `completions` subcommand. When defined, the planner intercepts
91
+ * `--completions <shell>` before dispatch, prints the script, and exits;
92
+ * root help advertises the flag in its `Flags:` section.
93
+ */
94
+ readonly completionsFlag: CompletionsFlagConfig | undefined;
95
+ /**
96
+ * Consumer-configured root-help defaults.
97
+ *
98
+ * Set via the {@linkcode CLIBuilder.help | .help()} builder method and merged
99
+ * under runtime `options.help` (runtime wins) before rendering.
100
+ */
101
+ readonly helpConfig: HelpConfig | undefined;
102
+ /**
103
+ * Flag-parsing behavior settings ({@link ParseOptions}).
104
+ *
105
+ * Set via the `cli(name, { flags })` / `cli({ flags })` factory forms.
106
+ */
107
+ readonly flagSettings: ParseOptions | undefined;
74
108
  /** Registered CLI plugins. */
75
109
  readonly plugins: readonly CLIPlugin[];
76
110
  }
111
+ /**
112
+ * Configuration for the eager `--completions <shell>` flag.
113
+ *
114
+ * Stored in {@link CLISchema} when `.completions({ as: 'flag' })` is used.
115
+ *
116
+ * @internal
117
+ */
118
+ interface CompletionsFlagConfig {
119
+ /** Shell targets the flag accepts (mirrors {@link SHELLS}). */
120
+ readonly shells: readonly Shell[];
121
+ /** Generator options captured at build time (e.g. `functionPrefix`, `rootMode`). */
122
+ readonly options: CompletionOptions | undefined;
123
+ }
124
+ /**
125
+ * Consumer-facing root-help configuration set via {@linkcode CLIBuilder.help}.
126
+ *
127
+ * Every field is optional; unset fields fall back to built-in defaults and may
128
+ * be overridden per call through runtime `options.help`.
129
+ */
130
+ interface HelpConfig {
131
+ /**
132
+ * Render the default command's arguments and flags inline at the root.
133
+ *
134
+ * @defaultValue `true`
135
+ */
136
+ readonly inlineDefault?: boolean;
137
+ /**
138
+ * Also list the default command in the root `Commands:` table.
139
+ *
140
+ * By default the default command is the root surface and is omitted from the
141
+ * command list (its args/flags render inline instead).
142
+ *
143
+ * @defaultValue `false`
144
+ */
145
+ readonly showDefaultInCommands?: boolean;
146
+ /**
147
+ * Show the `Run '<bin> <command> --help' for more information.` hint.
148
+ *
149
+ * Defaults to showing the hint only when visible subcommands exist.
150
+ */
151
+ readonly footer?: boolean;
152
+ /** Maximum line width (columns). */
153
+ readonly width?: number;
154
+ /** Emit OSC 8 hyperlinks in the header when supported. */
155
+ readonly hyperlinks?: boolean;
156
+ /**
157
+ * Theme overrides for help output, merged over the built-in theme.
158
+ *
159
+ * The factory receives the gated ansispeck palette (same instance as
160
+ * `out.color`), so overrides follow the output channel's color policy.
161
+ * It is never invoked when color is off — themed help cannot leak escapes
162
+ * into piped, `--json`, or `NO_COLOR` output.
163
+ *
164
+ * @defaultValue `undefined` (built-in theme)
165
+ */
166
+ readonly theme?: HelpThemeFactory;
167
+ }
77
168
  /**
78
169
  * Config discovery settings for automatic config file loading.
79
170
  *
@@ -178,6 +269,29 @@ interface CLIRunOptions extends Omit<RunOptions, 'meta' | 'mergedSchema'> {
178
269
  */
179
270
  readonly adapter?: RuntimeAdapter;
180
271
  }
272
+ /**
273
+ * Options for {@linkcode CLIBuilder.default | .default()}.
274
+ */
275
+ interface DefaultCommandOptions {
276
+ /**
277
+ * Also expose the default command under its own name as a routable
278
+ * top-level command.
279
+ *
280
+ * By default a default command is the root *surface* only — `mycli` (bare or
281
+ * flags-only) runs it, but `mycli <its-name>` does not route to it (the token
282
+ * is consumed as the default's first positional). Set `route: true` for CLIs
283
+ * that intentionally expose both forms: `mycli` and `mycli <its-name>` become
284
+ * the same command, and it is listed in the root `Commands:` section beside
285
+ * its siblings.
286
+ *
287
+ * The name wins over positional interpretation: with `route: true`, a
288
+ * positional value equal to the command's own name is consumed as the route,
289
+ * so pass such a value after `--` (`mycli -- <name>`).
290
+ *
291
+ * @defaultValue `false`
292
+ */
293
+ readonly route?: boolean;
294
+ }
181
295
  /**
182
296
  * Immutable CLI program builder.
183
297
  *
@@ -266,6 +380,25 @@ declare class CLIBuilder {
266
380
  readonly name?: string | URL;
267
381
  readonly version?: string | URL;
268
382
  }): CLIBuilder;
383
+ /**
384
+ * Configure root-help rendering defaults.
385
+ *
386
+ * Stored on the schema and merged **under** any runtime `options.help`
387
+ * (runtime wins). Call multiple times to set fields incrementally.
388
+ *
389
+ * @param config - Help rendering options (see {@link HelpConfig}).
390
+ * @returns The builder (for chaining).
391
+ *
392
+ * @example
393
+ * ```ts
394
+ * // Echo the default command under Commands and never show the footer:
395
+ * cli('mycli')
396
+ * .help({ showDefaultInCommands: true, footer: false })
397
+ * .default(serve)
398
+ * .run();
399
+ * ```
400
+ */
401
+ help(config: HelpConfig): CLIBuilder;
269
402
  /**
270
403
  * Enable automatic config file discovery.
271
404
  *
@@ -460,8 +593,18 @@ declare class CLIBuilder {
460
593
  * dispatch normally, but empty argv or flags-only argv falls through to
461
594
  * this command instead of showing root help.
462
595
  *
463
- * The command is also registered as a normal subcommand (can be invoked
464
- * by name). Only one default command is allowed.
596
+ * The default command is the CLI's root *surface*: its flags and arguments
597
+ * are rendered inline in root help. By default it is **not** a named
598
+ * subcommand — it cannot be invoked by its own name (`mycli mycmd` does not
599
+ * route to it) and it is omitted from the root `Commands:` list (re-enable
600
+ * listing with `.help({ showDefaultInCommands: true })`). Only one default is
601
+ * allowed.
602
+ *
603
+ * Pass `{ route: true }` to *also* expose the command under its own name as a
604
+ * routable top-level command: `mycli` and `mycli <name>` then run the same
605
+ * command object, and it is listed in `Commands:` beside its siblings. This
606
+ * avoids duplicating the command just to keep both forms equivalent during a
607
+ * v3 migration.
465
608
  *
466
609
  * @example
467
610
  * ```ts
@@ -478,12 +621,21 @@ declare class CLIBuilder {
478
621
  * .default(deploy)
479
622
  * .command(status)
480
623
  * .run();
624
+ *
625
+ * // Default that is also a named route — `mytool` and `mytool status` are
626
+ * // the same surface, and `status` is listed beside `logs`:
627
+ * cli('mytool')
628
+ * .default(status, { route: true })
629
+ * .command(logs)
630
+ * .run();
481
631
  * ```
482
632
  *
483
633
  * @param cmd - {@link CommandBuilder} to register as the default.
634
+ * @param options - Default-command options. `{ route: true }` also exposes
635
+ * the command under its own name (see {@link DefaultCommandOptions}).
484
636
  * @returns The builder (for chaining).
485
637
  */
486
- default<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown>>(cmd: CommandBuilder<F, A, C>): CLIBuilder;
638
+ default<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown>>(cmd: CommandBuilder<F, A, C>, options?: DefaultCommandOptions): CLIBuilder;
487
639
  /**
488
640
  * Register a CLI plugin.
489
641
  *
@@ -496,28 +648,36 @@ declare class CLIBuilder {
496
648
  */
497
649
  plugin(definition: CLIPlugin): CLIBuilder;
498
650
  /**
499
- * Register a built-in `completions` subcommand that generates shell
500
- * completion scripts.
651
+ * Register built-in shell completion.
501
652
  *
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.
653
+ * By default (`{ as: 'command' }`) this registers a `completions` subcommand
654
+ * that accepts a `shell` argument and writes the script to stdout. With
655
+ * `{ as: 'flag' }` it instead exposes an eager `--completions <shell>` flag on
656
+ * the CLI root — no subcommand is registered, so a default command stays the
657
+ * lone root surface. The flag may be given without a value to auto-detect the
658
+ * shell from `$SHELL` / `$PSModulePath`.
506
659
  *
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.
660
+ * In subcommand mode, call this **after** registering all other commands so
661
+ * the completion script includes the full command set: that path snapshots the
662
+ * schema (and completion options) at call time, so commands registered
663
+ * afterwards will not appear in that subcommand's generated script. In flag
664
+ * mode, generation runs at execution time from the final builder schema, so
665
+ * registration order does not matter.
512
666
  *
513
667
  * @example
514
668
  * ```ts
669
+ * // Subcommand form (default):
515
670
  * cli('mycli')
516
671
  * .version('1.0.0')
517
672
  * .command(deploy)
518
- * .command(login)
519
673
  * .completions({ rootMode: 'surface' })
520
674
  * .run();
675
+ *
676
+ * // Eager-flag form, ideal for single-command CLIs:
677
+ * cli('mycli')
678
+ * .completions({ as: 'flag' })
679
+ * .default(serve)
680
+ * .run();
521
681
  * ```
522
682
  */
523
683
  completions(options?: CompletionOptions): CLIBuilder;
@@ -613,6 +773,12 @@ interface CLIOptions {
613
773
  * @defaultValue `false`
614
774
  */
615
775
  readonly inherit?: boolean;
776
+ /**
777
+ * Flag-parsing behavior settings (e.g. `{ caseParity: false }` to accept
778
+ * only declared flag spellings). Shares the {@link ParseOptions} contract
779
+ * used by `parse()` and `RunOptions.flags`.
780
+ */
781
+ readonly flags?: ParseOptions;
616
782
  }
617
783
  /**
618
784
  * Create a new CLI program builder.
@@ -633,8 +799,8 @@ interface CLIOptions {
633
799
  * .run();
634
800
  * ```
635
801
  */
636
- declare function cli(name: string): CLIBuilder;
802
+ declare function cli(name: string, options?: Omit<CLIOptions, 'name'>): CLIBuilder;
637
803
  /** Create a new CLI program builder from an options object. */
638
804
  declare function cli(options: CLIOptions): CLIBuilder;
639
805
  //#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 };
806
+ export { type BeforeParseParams, CLIBuilder, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type CompletionsFlagConfig, type ConfigSettings, type DefaultCommandOptions, type HelpConfig, type HelpLinks, type InferNameOption, type ManifestPresetSettings, type ManifestSettings, type PackageJsonSettings, type PluginCommandContext, type ResolvedCommandParams, type ResolvedManifestSettings, cli, formatRootHelp, plugin };