@kjanat/dreamcli 3.0.0-rc.1 → 3.0.0-rc.11

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 (194) hide show
  1. package/CHANGELOG.md +227 -1
  2. package/dist/core/cli/dispatch.d.mts +6 -5
  3. package/dist/core/cli/dispatch.mjs +205 -1
  4. package/dist/core/cli/help-links.d.mts +0 -1
  5. package/dist/core/cli/help-links.mjs +41 -1
  6. package/dist/core/cli/index.d.mts +81 -8
  7. package/dist/core/cli/index.mjs +945 -1
  8. package/dist/core/cli/planner.d.mts +5 -1
  9. package/dist/core/cli/planner.mjs +300 -1
  10. package/dist/core/cli/plugin.d.mts +1 -1
  11. package/dist/core/cli/plugin.mjs +41 -1
  12. package/dist/core/cli/propagate.d.mts +1 -1
  13. package/dist/core/cli/propagate.mjs +57 -1
  14. package/dist/core/cli/root-help.d.mts +2 -1
  15. package/dist/core/cli/root-help.mjs +226 -4
  16. package/dist/core/cli/root-surface.d.mts +12 -1
  17. package/dist/core/cli/root-surface.mjs +28 -1
  18. package/dist/core/cli/runtime-preflight.d.mts +14 -2
  19. package/dist/core/cli/runtime-preflight.mjs +169 -1
  20. package/dist/core/completion/index.d.mts +0 -1
  21. package/dist/core/completion/index.mjs +90 -1
  22. package/dist/core/completion/shells/bash.d.mts +0 -1
  23. package/dist/core/completion/shells/bash.mjs +308 -3
  24. package/dist/core/completion/shells/fish.d.mts +0 -1
  25. package/dist/core/completion/shells/fish.mjs +162 -2
  26. package/dist/core/completion/shells/powershell.d.mts +0 -1
  27. package/dist/core/completion/shells/powershell.mjs +358 -2
  28. package/dist/core/completion/shells/shared.d.mts +13 -2
  29. package/dist/core/completion/shells/shared.mjs +176 -1
  30. package/dist/core/completion/shells/zsh.d.mts +0 -1
  31. package/dist/core/completion/shells/zsh.mjs +251 -2
  32. package/dist/core/config/index.d.mts +2 -3
  33. package/dist/core/config/index.mjs +246 -1
  34. package/dist/core/config/package-json.d.mts +27 -4
  35. package/dist/core/config/package-json.mjs +386 -3
  36. package/dist/core/errors/index.d.mts +3 -3
  37. package/dist/core/errors/index.mjs +87 -1
  38. package/dist/core/execution/index.d.mts +0 -1
  39. package/dist/core/execution/index.mjs +201 -1
  40. package/dist/core/help/ansi.d.mts +11 -5
  41. package/dist/core/help/ansi.mjs +121 -2
  42. package/dist/core/help/index.d.mts +22 -3
  43. package/dist/core/help/index.mjs +341 -7
  44. package/dist/core/help/theme.d.mts +68 -0
  45. package/dist/core/help/theme.mjs +46 -0
  46. package/dist/core/json-schema/index.d.mts +15 -2
  47. package/dist/core/json-schema/index.mjs +536 -12
  48. package/dist/core/json-schema/meta-descriptions.generated.d.mts +55 -38
  49. package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
  50. package/dist/core/output/activity.d.mts +0 -1
  51. package/dist/core/output/activity.mjs +452 -1
  52. package/dist/core/output/bind.mjs +56 -1
  53. package/dist/core/output/contracts.d.mts +4 -5
  54. package/dist/core/output/contracts.mjs +57 -1
  55. package/dist/core/output/display-value.mjs +32 -1
  56. package/dist/core/output/index.d.mts +21 -1
  57. package/dist/core/output/index.mjs +442 -2
  58. package/dist/core/output/renderers.d.mts +0 -1
  59. package/dist/core/output/renderers.mjs +46 -1
  60. package/dist/core/output/writer.mjs +12 -1
  61. package/dist/core/parse/index.d.mts +40 -7
  62. package/dist/core/parse/index.mjs +727 -1
  63. package/dist/core/prompt/index.d.mts +1 -1
  64. package/dist/core/prompt/index.mjs +348 -6
  65. package/dist/core/resolve/args.d.mts +1 -1
  66. package/dist/core/resolve/args.mjs +105 -1
  67. package/dist/core/resolve/coerce.d.mts +1 -1
  68. package/dist/core/resolve/coerce.mjs +336 -1
  69. package/dist/core/resolve/config.mjs +19 -1
  70. package/dist/core/resolve/contracts.d.mts +9 -4
  71. package/dist/core/resolve/errors.d.mts +0 -1
  72. package/dist/core/resolve/errors.mjs +140 -2
  73. package/dist/core/resolve/flags.d.mts +7 -2
  74. package/dist/core/resolve/flags.mjs +251 -1
  75. package/dist/core/resolve/index.d.mts +2 -2
  76. package/dist/core/resolve/index.mjs +85 -1
  77. package/dist/core/resolve/property.d.mts +4 -2
  78. package/dist/core/resolve/property.mjs +53 -1
  79. package/dist/core/schema/activity.d.mts +31 -11
  80. package/dist/core/schema/arg.d.mts +3 -4
  81. package/dist/core/schema/arg.mjs +463 -1
  82. package/dist/core/schema/command.d.mts +26 -6
  83. package/dist/core/schema/command.mjs +726 -1
  84. package/dist/core/schema/flag.d.mts +485 -19
  85. package/dist/core/schema/flag.mjs +705 -1
  86. package/dist/core/schema/index.d.mts +4 -2
  87. package/dist/core/schema/middleware.d.mts +4 -3
  88. package/dist/core/schema/middleware.mjs +41 -1
  89. package/dist/core/schema/number-constraints.mjs +60 -1
  90. package/dist/core/schema/prompt.d.mts +6 -3
  91. package/dist/core/schema/run.d.mts +20 -1
  92. package/dist/core/schema/string-constraints.d.mts +97 -0
  93. package/dist/core/schema/string-constraints.mjs +69 -0
  94. package/dist/core/schema/value-parsers.d.mts +78 -0
  95. package/dist/core/schema/value-parsers.mjs +142 -0
  96. package/dist/core/schema-dsl/runtime.mjs +271 -2
  97. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  98. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  99. package/dist/core/testkit/index.d.mts +0 -31
  100. package/dist/core/testkit/index.mjs +83 -1
  101. package/dist/index.d.mts +11 -6
  102. package/dist/index.mjs +22 -1
  103. package/dist/runtime/adapter.d.mts +38 -2
  104. package/dist/runtime/adapter.mjs +87 -1
  105. package/dist/runtime/auto.d.mts +2 -3
  106. package/dist/runtime/auto.mjs +45 -1
  107. package/dist/runtime/deno.d.mts +24 -5
  108. package/dist/runtime/deno.mjs +262 -2
  109. package/dist/runtime/detect.mjs +45 -1
  110. package/dist/runtime/index.d.mts +3 -4
  111. package/dist/runtime/node.d.mts +8 -2
  112. package/dist/runtime/node.mjs +220 -2
  113. package/dist/runtime/paths.mjs +48 -1
  114. package/dist/runtime.d.mts +4 -4
  115. package/dist/runtime.mjs +6 -1
  116. package/dist/strings.mjs +22 -1
  117. package/dist/testkit.d.mts +1 -0
  118. package/dist/testkit.mjs +5 -1
  119. package/dist/version.d.mts +7 -3
  120. package/dist/version.mjs +7 -1
  121. package/dreamcli.schema.json +36 -7
  122. package/package.json +45 -42
  123. package/dist/runtime/bun.d.mts +0 -28
  124. package/dist/runtime/bun.mjs +0 -1
  125. package/src/core/cli/dispatch.ts +0 -355
  126. package/src/core/cli/help-links.ts +0 -82
  127. package/src/core/cli/index.ts +0 -1614
  128. package/src/core/cli/planner.ts +0 -656
  129. package/src/core/cli/plugin.ts +0 -117
  130. package/src/core/cli/propagate.ts +0 -97
  131. package/src/core/cli/root-help.ts +0 -342
  132. package/src/core/cli/root-surface.ts +0 -87
  133. package/src/core/cli/runtime-preflight.ts +0 -456
  134. package/src/core/completion/index.ts +0 -138
  135. package/src/core/completion/shells/bash.ts +0 -459
  136. package/src/core/completion/shells/fish.ts +0 -259
  137. package/src/core/completion/shells/powershell.ts +0 -439
  138. package/src/core/completion/shells/shared.ts +0 -310
  139. package/src/core/completion/shells/zsh.ts +0 -381
  140. package/src/core/config/index.ts +0 -417
  141. package/src/core/config/package-json.ts +0 -560
  142. package/src/core/errors/index.ts +0 -193
  143. package/src/core/execution/index.ts +0 -265
  144. package/src/core/help/ansi.ts +0 -144
  145. package/src/core/help/index.ts +0 -563
  146. package/src/core/json-schema/index.ts +0 -910
  147. package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
  148. package/src/core/output/activity.ts +0 -575
  149. package/src/core/output/bind.ts +0 -59
  150. package/src/core/output/contracts.ts +0 -194
  151. package/src/core/output/display-value.ts +0 -48
  152. package/src/core/output/index.ts +0 -704
  153. package/src/core/output/renderers.ts +0 -125
  154. package/src/core/output/writer.ts +0 -46
  155. package/src/core/parse/index.ts +0 -742
  156. package/src/core/prompt/index.ts +0 -623
  157. package/src/core/resolve/args.ts +0 -144
  158. package/src/core/resolve/coerce.ts +0 -500
  159. package/src/core/resolve/config.ts +0 -26
  160. package/src/core/resolve/contracts.ts +0 -135
  161. package/src/core/resolve/errors.ts +0 -227
  162. package/src/core/resolve/flags.ts +0 -269
  163. package/src/core/resolve/index.ts +0 -108
  164. package/src/core/resolve/property.ts +0 -99
  165. package/src/core/schema/activity.ts +0 -240
  166. package/src/core/schema/arg.ts +0 -841
  167. package/src/core/schema/command.ts +0 -1500
  168. package/src/core/schema/flag.ts +0 -917
  169. package/src/core/schema/index.ts +0 -96
  170. package/src/core/schema/middleware.ts +0 -171
  171. package/src/core/schema/number-constraints.ts +0 -153
  172. package/src/core/schema/prompt.ts +0 -171
  173. package/src/core/schema/run.ts +0 -198
  174. package/src/core/schema-dsl/index.ts +0 -109
  175. package/src/core/schema-dsl/parse.ts +0 -262
  176. package/src/core/schema-dsl/runtime.ts +0 -609
  177. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  178. package/src/core/testkit/index.ts +0 -147
  179. package/src/index.ts +0 -181
  180. package/src/runtime/adapter.ts +0 -303
  181. package/src/runtime/auto.ts +0 -86
  182. package/src/runtime/bun.ts +0 -48
  183. package/src/runtime/deno.ts +0 -367
  184. package/src/runtime/detect.ts +0 -105
  185. package/src/runtime/index.ts +0 -21
  186. package/src/runtime/node-builtins.d.ts +0 -27
  187. package/src/runtime/node.ts +0 -289
  188. package/src/runtime/paths.ts +0 -64
  189. package/src/runtime/support.ts +0 -77
  190. package/src/runtime.ts +0 -31
  191. package/src/schema.ts +0 -16
  192. package/src/strings.ts +0 -34
  193. package/src/testkit.ts +0 -25
  194. package/src/version.ts +0 -20
@@ -1,8 +1,11 @@
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";
@@ -10,7 +13,6 @@ import { CompletionOptions } from "../completion/shells/shared.mjs";
10
13
  import { Shell } from "../completion/index.mjs";
11
14
  import { FormatLoader } from "../config/index.mjs";
12
15
  import { formatRootHelp } from "./root-help.mjs";
13
-
14
16
  //#region src/core/cli/index.d.ts
15
17
  /**
16
18
  * Runtime descriptor for the CLI program.
@@ -43,6 +45,15 @@ interface CLISchema {
43
45
  * Set via the {@linkcode CLIBuilder.default | .default()} builder method.
44
46
  */
45
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;
46
57
  /**
47
58
  * Config discovery settings.
48
59
  *
@@ -88,6 +99,12 @@ interface CLISchema {
88
99
  * under runtime `options.help` (runtime wins) before rendering.
89
100
  */
90
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;
91
108
  /** Registered CLI plugins. */
92
109
  readonly plugins: readonly CLIPlugin[];
93
110
  }
@@ -136,6 +153,17 @@ interface HelpConfig {
136
153
  readonly width?: number;
137
154
  /** Emit OSC 8 hyperlinks in the header when supported. */
138
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;
139
167
  }
140
168
  /**
141
169
  * Config discovery settings for automatic config file loading.
@@ -241,6 +269,29 @@ interface CLIRunOptions extends Omit<RunOptions, 'meta' | 'mergedSchema'> {
241
269
  */
242
270
  readonly adapter?: RuntimeAdapter;
243
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
+ }
244
295
  /**
245
296
  * Immutable CLI program builder.
246
297
  *
@@ -543,10 +594,17 @@ declare class CLIBuilder {
543
594
  * this command instead of showing root help.
544
595
  *
545
596
  * 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.
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.
550
608
  *
551
609
  * @example
552
610
  * ```ts
@@ -563,12 +621,21 @@ declare class CLIBuilder {
563
621
  * .default(deploy)
564
622
  * .command(status)
565
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();
566
631
  * ```
567
632
  *
568
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}).
569
636
  * @returns The builder (for chaining).
570
637
  */
571
- 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;
572
639
  /**
573
640
  * Register a CLI plugin.
574
641
  *
@@ -706,6 +773,12 @@ interface CLIOptions {
706
773
  * @defaultValue `false`
707
774
  */
708
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;
709
782
  }
710
783
  /**
711
784
  * Create a new CLI program builder.
@@ -726,8 +799,8 @@ interface CLIOptions {
726
799
  * .run();
727
800
  * ```
728
801
  */
729
- declare function cli(name: string): CLIBuilder;
802
+ declare function cli(name: string, options?: Omit<CLIOptions, 'name'>): CLIBuilder;
730
803
  /** Create a new CLI program builder from an options object. */
731
804
  declare function cli(options: CLIOptions): CLIBuilder;
732
805
  //#endregion
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 };
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 };