@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
@@ -3,7 +3,9 @@ import { CLIPlugin } from "./plugin.mjs";
3
3
  import { CLIError } from "../errors/index.mjs";
4
4
  import { HelpOptions } from "../help/index.mjs";
5
5
  import { CommandMeta, CommandSchema, ErasedCommand } from "../schema/command.mjs";
6
-
6
+ import { ParseOptions } from "../parse/index.mjs";
7
+ import { CompletionOptions } from "../completion/shells/shared.mjs";
8
+ import { Shell } from "../completion/index.mjs";
7
9
  //#region src/core/cli/planner.d.ts
8
10
  /**
9
11
  * Structural subset of CLISchema used by the planner.
@@ -21,6 +23,18 @@ interface PlannerSchemaLike {
21
23
  readonly commands: readonly ErasedCommand[];
22
24
  /** Fallback command when no subcommand token matches. */
23
25
  readonly defaultCommand: ErasedCommand | undefined;
26
+ /** Whether the default command is also exposed as a named top-level route. */
27
+ readonly defaultCommandRouted: boolean;
28
+ /**
29
+ * Eager `--completions <shell>` flag configuration, when `.completions()`
30
+ * was registered with `{ as: 'flag' }`. `undefined` disables interception.
31
+ */
32
+ readonly completionsFlag: {
33
+ readonly shells: readonly Shell[];
34
+ readonly options: CompletionOptions | undefined;
35
+ } | undefined;
36
+ /** Flag-parsing behavior settings (case parity) applied to flag lookups. */
37
+ readonly flagSettings?: ParseOptions | undefined;
24
38
  /** Plugins forwarded into every matched execution plan. */
25
39
  readonly plugins: readonly CLIPlugin[];
26
40
  }
@@ -38,6 +52,18 @@ interface RootVersionOutcome {
38
52
  /** Resolved version string to render. */
39
53
  readonly version: string;
40
54
  }
55
+ /** Root-level `--completions [shell]` interception outcome. */
56
+ interface RootCompletionsOutcome {
57
+ /** Discriminant — argv matched the eager `--completions [shell]` flag. */
58
+ readonly kind: 'root-completions';
59
+ /**
60
+ * Resolved, validated target shell, or `undefined` when the flag was given
61
+ * without a value and the shell should be auto-detected from the environment.
62
+ */
63
+ readonly shell: Shell | undefined;
64
+ /** Generator options captured at build time. */
65
+ readonly options: CompletionOptions | undefined;
66
+ }
41
67
  /** CLI-level dispatch failure before command execution starts. */
42
68
  interface DispatchErrorOutcome {
43
69
  /** Discriminant — dispatch could not resolve a command from argv. */
@@ -58,7 +84,7 @@ interface PlannerMatchOutcome {
58
84
  * `CLIBuilder.execute()` still renders and executes these outcomes, but
59
85
  * planning itself is intentionally bounded to this union.
60
86
  */
61
- type DispatchOutcome = RootHelpOutcome | RootVersionOutcome | DispatchErrorOutcome | PlannerMatchOutcome;
87
+ type DispatchOutcome = RootHelpOutcome | RootVersionOutcome | RootCompletionsOutcome | DispatchErrorOutcome | PlannerMatchOutcome;
62
88
  /**
63
89
  * Concrete execution handoff produced by a successful planner match.
64
90
  *
@@ -133,11 +159,11 @@ declare function buildCommandExecutionPlan(options: BuildCommandExecutionPlanOpt
133
159
  /**
134
160
  * Decide what to do with an argv invocation before any command executes.
135
161
  *
136
- * Handles root interception (`--help`, `--version`, bare `help` token),
137
- * dispatches into the command tree, falls back to the default command, and
138
- * produces structured errors for unknown commands/flags.
162
+ * Handles root interception (`--help`, `--version`, `--completions <shell>`,
163
+ * bare `help` token), dispatches into the command tree, falls back to the
164
+ * default command, and produces structured errors for unknown commands/flags.
139
165
  * @internal
140
166
  */
141
167
  declare function planInvocation(options: PlanInvocationOptions): InvocationPlan;
142
168
  //#endregion
143
- export { type CommandExecutionPlan, type DispatchErrorOutcome, type DispatchOutcome, type InvocationPlan, type NeedsSubcommandOutcome, type OutputPolicy, type PlanInvocationOptions, type PlannerMatchOutcome, type PlannerSchemaLike, type RootHelpOutcome, type RootVersionOutcome, buildCommandExecutionPlan, buildRootCommandMap, mergeCommandSchema, planInvocation };
169
+ export { type CommandExecutionPlan, type DispatchErrorOutcome, type DispatchOutcome, type InvocationPlan, type NeedsSubcommandOutcome, type OutputPolicy, type PlanInvocationOptions, type PlannerMatchOutcome, type PlannerSchemaLike, type RootCompletionsOutcome, type RootHelpOutcome, type RootVersionOutcome, buildCommandExecutionPlan, buildRootCommandMap, mergeCommandSchema, planInvocation };
@@ -1 +1,300 @@
1
- import{collectPropagatedFlags as e}from"./propagate.mjs";import{CLIError as t,ParseError as n}from"../errors/index.mjs";import{buildFlagLookup as r,flagExpectsValue as i,includesBeforeSeparator as a}from"../parse/index.mjs";import{dispatch as o,findClosestCommand as s}from"./dispatch.mjs";function c(e,t,n){return{name:e.name,bin:t.binName??e.name,version:e.version,command:n}}function l(e){let n=new Map,r=(e,r)=>{let i=n.get(e);if(i!==void 0)throw new t(`Duplicate root command route '${e}' (${i.schema.name} and ${r.schema.name})`,{code:`DUPLICATE_COMMAND`,suggest:`Ensure root command names and aliases are unique`});n.set(e,r)};for(let t of e){r(t.schema.name,t);for(let e of t.schema.aliases)r(e,t)}return n}function u(t,n){let r=e(n);return Object.keys(r).length===0?t.schema:{...t.schema,flags:{...r,...t.schema.flags}}}function d(e){return{command:e.command,mergedSchema:u(e.command,e.commandPath),argv:e.argv,meta:e.meta,plugins:e.plugins,output:e.output,help:e.help}}function f(e,t,n,r,i,a){return{kind:`match`,plan:d({command:t,commandPath:n,argv:r,meta:c(e,i,t.schema.name),plugins:e.plugins,output:a,help:i})}}function p(e,t){return t===``||e.schema.args.length>0}function m(e,t){let n=r(t);for(let t=0;t<e.length;t++){let r=e[t];if(r===void 0||r===`--`||r===`-`||!r.startsWith(`-`))return;if(r.startsWith(`--`)){let e=r.indexOf(`=`),a=r.slice(2,e===-1?void 0:e),o=n.get(a);if(o===void 0)return e===-1?r:`--${a}`;e===-1&&i(o[1])&&t++;continue}let a=r.slice(1);for(let e=0;e<a.length;e++){let r=a.charAt(e),o=n.get(r);if(o===void 0)return`-${r}`;if(i(o[1])){e===a.length-1&&t++;break}}}}function h(e){let i=e.argv.indexOf(`--`),c=i===-1?e.argv:e.argv.slice(0,i),u=i===-1?[]:e.argv.slice(i),d=c.includes(`--json`)?c.filter(e=>e!==`--json`):c,g=i===-1?d:[...d,...u];if(e.schema.version!==void 0&&(a(e.argv,`--version`)||a(e.argv,`-V`)))return{kind:`root-version`,version:e.schema.version};let _=g[0];if(_===`--help`||_===`-h`)return{kind:`root-help`,help:e.help};if(_===`help`&&!e.schema.commands.some(e=>e.schema.name===`help`||e.schema.aliases.includes(`help`))){let t=g.slice(1);return t.length===0?{kind:`root-help`,help:e.help}:h({...e,argv:[...t,`--help`]})}if(_===void 0&&e.schema.defaultCommand===void 0)return{kind:`root-help`,help:e.help};if(e.schema.commands.length===0)return{kind:`dispatch-error`,error:new t(`No commands registered`,{code:`NO_ACTION`,suggest:`Add commands via .command() before calling .run()`})};let v=e.schema.defaultCommand,y=v===void 0?void 0:r(v.schema.flags),b=o(g,l(e.schema.commands),[],y);switch(b.kind){case`unknown`:{if(v!==void 0&&b.parentPath.length===0){if((b.input===``?void 0:s(b.input,b.candidates))===void 0&&p(v,b.input))return f(e.schema,v,[v.schema],g,e.help,e.output);let t=m(g,v.schema.flags);if(t!==void 0)return{kind:`dispatch-error`,error:new n(`Unknown flag ${t}`,{code:`UNKNOWN_FLAG`,suggest:`Run '${e.schema.name} --help' for available commands`})}}if(b.input===``){let t=g.find(e=>e.startsWith(`-`));return t===void 0?{kind:`root-help`,help:e.help}:{kind:`dispatch-error`,error:new n(`Unknown flag ${t}`,{code:`UNKNOWN_FLAG`,suggest:`Run '${e.schema.name} --help' for available commands`})}}let t=s(b.input,b.candidates),r=b.parentPath.length>0?`${e.schema.name} ${b.parentPath.map(e=>e.name).join(` `)}`:e.schema.name;return{kind:`dispatch-error`,error:new n(`Unknown command: ${b.input}`,{code:`UNKNOWN_COMMAND`,suggest:t===void 0?`Run '${r} --help' for available commands`:`Did you mean '${t}'?`})}}case`needs-subcommand`:{let t=b.commandPath.slice(0,-1).map(e=>e.name);return{kind:`needs-subcommand`,command:b.command,commandPath:b.commandPath,help:{...e.help,binName:[e.schema.name,...t].join(` `)}}}case`match`:return f(e.schema,b.command,b.commandPath,b.remainingArgv,e.help,e.output)}}export{h as planInvocation};
1
+ import { CLIError, ParseError } from "../errors/index.mjs";
2
+ import { buildFlagLookup, flagExpectsValue, includesBeforeSeparator } from "../parse/index.mjs";
3
+ import { collectPropagatedFlags } from "./propagate.mjs";
4
+ import { normalizeShell } from "../completion/index.mjs";
5
+ import { dispatch, findClosestCommand } from "./dispatch.mjs";
6
+ //#region src/core/cli/planner.ts
7
+ function buildMeta(schema, helpOptions, commandName) {
8
+ return {
9
+ name: schema.name,
10
+ bin: helpOptions.binName ?? schema.name,
11
+ version: schema.version,
12
+ command: commandName
13
+ };
14
+ }
15
+ /** Build a name+alias lookup map for top-level commands. @internal */
16
+ function buildRootCommandMap(commands) {
17
+ const rootCommands = /* @__PURE__ */ new Map();
18
+ const addRoute = (route, command) => {
19
+ const existing = rootCommands.get(route);
20
+ if (existing !== void 0) throw new CLIError(`Duplicate root command route '${route}' (${existing.schema.name} and ${command.schema.name})`, {
21
+ code: "DUPLICATE_COMMAND",
22
+ suggest: "Ensure root command names and aliases are unique"
23
+ });
24
+ rootCommands.set(route, command);
25
+ };
26
+ for (const cmd of commands) {
27
+ addRoute(cmd.schema.name, cmd);
28
+ for (const alias of cmd.schema.aliases) addRoute(alias, cmd);
29
+ }
30
+ return rootCommands;
31
+ }
32
+ /**
33
+ * Merge propagated ancestor flags into the matched command schema.
34
+ *
35
+ * Child flag definitions win when names collide, matching current CLI
36
+ * dispatch semantics and the future planner contract.
37
+ */
38
+ function mergeCommandSchema(command, commandPath) {
39
+ const propagated = collectPropagatedFlags(commandPath);
40
+ if (Object.keys(propagated).length === 0) return command.schema;
41
+ return {
42
+ ...command.schema,
43
+ flags: {
44
+ ...propagated,
45
+ ...command.schema.flags
46
+ }
47
+ };
48
+ }
49
+ /** Build the planner handoff for a matched command invocation. */
50
+ function buildCommandExecutionPlan(options) {
51
+ return {
52
+ command: options.command,
53
+ mergedSchema: mergeCommandSchema(options.command, options.commandPath),
54
+ argv: options.argv,
55
+ meta: options.meta,
56
+ plugins: options.plugins,
57
+ output: options.output,
58
+ help: options.help
59
+ };
60
+ }
61
+ function buildPlannerMatchOutcome(schema, command, commandPath, argv, help, output) {
62
+ return {
63
+ kind: "match",
64
+ plan: buildCommandExecutionPlan({
65
+ command,
66
+ commandPath,
67
+ argv,
68
+ meta: buildMeta(schema, help, command.schema.name),
69
+ plugins: schema.plugins,
70
+ output,
71
+ help
72
+ })
73
+ };
74
+ }
75
+ function canDelegateUnknownRootToDefault(command, input) {
76
+ return input === "" || command.schema.args.length > 0;
77
+ }
78
+ function findUnknownFlagBeforePositional(argv, flags, parseOptions) {
79
+ const lookup = buildFlagLookup(flags, parseOptions);
80
+ for (let index = 0; index < argv.length; index++) {
81
+ const token = argv[index];
82
+ if (token === void 0 || token === "--") return void 0;
83
+ if (token === "-" || !token.startsWith("-")) return void 0;
84
+ if (token.startsWith("--")) {
85
+ const equalsIndex = token.indexOf("=");
86
+ const name = token.slice(2, equalsIndex === -1 ? void 0 : equalsIndex);
87
+ const entry = lookup.get(name);
88
+ if (entry === void 0) return equalsIndex === -1 ? token : `--${name}`;
89
+ if (equalsIndex === -1 && flagExpectsValue(entry.schema)) index++;
90
+ continue;
91
+ }
92
+ const chars = token.slice(1);
93
+ for (let charIndex = 0; charIndex < chars.length; charIndex++) {
94
+ const char = chars.charAt(charIndex);
95
+ const entry = lookup.get(char);
96
+ if (entry === void 0) return `-${char}`;
97
+ if (!flagExpectsValue(entry.schema)) continue;
98
+ if (charIndex === chars.length - 1) index++;
99
+ break;
100
+ }
101
+ }
102
+ }
103
+ /**
104
+ * Scan the pre-`--`, `--json`-stripped head to locate the first command-dispatch
105
+ * token and detect a root-level `--help` / `-h` ahead of it.
106
+ *
107
+ * Value-flag arity is honoured (via `valueFlags`) so a flag value that happens
108
+ * to look like a command name is not mistaken for one — matching how
109
+ * {@linkcode dispatch} reads the same argv.
110
+ *
111
+ * @internal
112
+ */
113
+ function scanRootHead(head, valueFlags) {
114
+ for (let index = 0; index < head.length; index++) {
115
+ const token = head[index];
116
+ if (token === void 0) continue;
117
+ if (token === "--help" || token === "-h") return {
118
+ helpBeforeCommand: true,
119
+ firstCommandToken: void 0,
120
+ commandTokenIndex: -1
121
+ };
122
+ if (token === "-" || !token.startsWith("-")) return {
123
+ helpBeforeCommand: false,
124
+ firstCommandToken: token,
125
+ commandTokenIndex: index
126
+ };
127
+ if (token.startsWith("--")) {
128
+ const equalsIndex = token.indexOf("=");
129
+ const name = token.slice(2, equalsIndex === -1 ? void 0 : equalsIndex);
130
+ const entry = valueFlags?.get(name);
131
+ if (entry !== void 0 && equalsIndex === -1 && flagExpectsValue(entry.schema)) index++;
132
+ continue;
133
+ }
134
+ const chars = token.slice(1);
135
+ for (let charIndex = 0; charIndex < chars.length; charIndex++) {
136
+ const entry = valueFlags?.get(chars.charAt(charIndex));
137
+ if (entry === void 0 || !flagExpectsValue(entry.schema)) continue;
138
+ if (charIndex === chars.length - 1) index++;
139
+ break;
140
+ }
141
+ }
142
+ return {
143
+ helpBeforeCommand: false,
144
+ firstCommandToken: void 0,
145
+ commandTokenIndex: -1
146
+ };
147
+ }
148
+ /**
149
+ * Detect and resolve the eager `--completions [shell]` flag before dispatch.
150
+ *
151
+ * Accepts `--completions <shell>` and `--completions=<shell>`. When no value is
152
+ * given (`--completions` alone, or followed by another flag), the shell is left
153
+ * `undefined` so the caller can auto-detect it from the environment. Scans only
154
+ * before a `--` separator so a literal positional survives.
155
+ *
156
+ * Returns `undefined` when the flag is absent, a `root-completions` outcome
157
+ * otherwise, or a `dispatch-error` when an explicit value names an unknown shell.
158
+ *
159
+ * @internal
160
+ */
161
+ function planCompletionsFlag(argv, config) {
162
+ const separatorIndex = argv.indexOf("--");
163
+ const scanEnd = separatorIndex === -1 ? argv.length : separatorIndex;
164
+ for (let index = 0; index < scanEnd; index++) {
165
+ const token = argv[index];
166
+ if (token === void 0) continue;
167
+ let rawShell;
168
+ if (token === "--completions") {
169
+ const next = index + 1 < scanEnd ? argv[index + 1] : void 0;
170
+ rawShell = next !== void 0 && !next.startsWith("-") ? next : void 0;
171
+ } else if (token.startsWith("--completions=")) rawShell = token.slice(14);
172
+ else continue;
173
+ if (rawShell === void 0 || rawShell === "") return {
174
+ kind: "root-completions",
175
+ shell: void 0,
176
+ options: config.options
177
+ };
178
+ const shell = normalizeShell(rawShell);
179
+ if (shell === void 0 || !config.shells.includes(shell)) return {
180
+ kind: "dispatch-error",
181
+ error: new ParseError(`Unknown shell '${rawShell}'`, {
182
+ code: "INVALID_VALUE",
183
+ suggest: `Valid shells: ${config.shells.join(", ")}`
184
+ })
185
+ };
186
+ return {
187
+ kind: "root-completions",
188
+ shell,
189
+ options: config.options
190
+ };
191
+ }
192
+ }
193
+ /**
194
+ * Decide what to do with an argv invocation before any command executes.
195
+ *
196
+ * Handles root interception (`--help`, `--version`, `--completions <shell>`,
197
+ * bare `help` token), dispatches into the command tree, falls back to the
198
+ * default command, and produces structured errors for unknown commands/flags.
199
+ * @internal
200
+ */
201
+ function planInvocation(options) {
202
+ const separatorIndex = options.argv.indexOf("--");
203
+ const head = separatorIndex === -1 ? options.argv : options.argv.slice(0, separatorIndex);
204
+ const tail = separatorIndex === -1 ? [] : options.argv.slice(separatorIndex);
205
+ const filteredHead = head.includes("--json") ? head.filter((arg) => arg !== "--json") : head;
206
+ const filteredArgv = separatorIndex === -1 ? filteredHead : [...filteredHead, ...tail];
207
+ const defaultCommand = options.schema.defaultCommand;
208
+ const rootValueFlags = defaultCommand !== void 0 ? buildFlagLookup(defaultCommand.schema.flags, options.schema.flagSettings) : void 0;
209
+ if (options.schema.version !== void 0 && (includesBeforeSeparator(options.argv, "--version") || includesBeforeSeparator(options.argv, "-V"))) return {
210
+ kind: "root-version",
211
+ version: options.schema.version
212
+ };
213
+ if (options.schema.completionsFlag !== void 0) {
214
+ const completionsOutcome = planCompletionsFlag(options.argv, options.schema.completionsFlag);
215
+ if (completionsOutcome !== void 0) return completionsOutcome;
216
+ }
217
+ const headScan = scanRootHead(filteredHead, rootValueFlags);
218
+ if (headScan.helpBeforeCommand) return {
219
+ kind: "root-help",
220
+ help: options.help
221
+ };
222
+ if (headScan.firstCommandToken === "help") {
223
+ if (!options.schema.commands.some((command) => command.schema.name === "help" || command.schema.aliases.includes("help"))) {
224
+ const rest = filteredArgv.slice(headScan.commandTokenIndex + 1);
225
+ if (rest.length === 0) return {
226
+ kind: "root-help",
227
+ help: options.help
228
+ };
229
+ return planInvocation({
230
+ ...options,
231
+ argv: [...rest, "--help"]
232
+ });
233
+ }
234
+ }
235
+ if (options.schema.commands.length === 0 && defaultCommand === void 0) return {
236
+ kind: "dispatch-error",
237
+ error: new CLIError("No commands registered", {
238
+ code: "NO_ACTION",
239
+ suggest: "Add commands via .command() or .default() before calling .run()"
240
+ })
241
+ };
242
+ if (filteredArgv.length === 0 && defaultCommand === void 0) return {
243
+ kind: "root-help",
244
+ help: options.help
245
+ };
246
+ const result = dispatch(filteredArgv, buildRootCommandMap(defaultCommand !== void 0 && options.schema.defaultCommandRouted ? [...options.schema.commands, defaultCommand] : options.schema.commands), [], rootValueFlags, options.schema.flagSettings);
247
+ switch (result.kind) {
248
+ case "unknown": {
249
+ if (defaultCommand !== void 0 && result.parentPath.length === 0) {
250
+ if ((result.input !== "" ? findClosestCommand(result.input, result.candidates) : void 0) === void 0 && canDelegateUnknownRootToDefault(defaultCommand, result.input)) return buildPlannerMatchOutcome(options.schema, defaultCommand, [defaultCommand.schema], filteredArgv, options.help, options.output);
251
+ const unknownFlag = findUnknownFlagBeforePositional(filteredArgv, defaultCommand.schema.flags, options.schema.flagSettings);
252
+ if (unknownFlag !== void 0) return {
253
+ kind: "dispatch-error",
254
+ error: new ParseError(`Unknown flag ${unknownFlag}`, {
255
+ code: "UNKNOWN_FLAG",
256
+ suggest: `Run '${options.schema.name} --help' for available commands`
257
+ })
258
+ };
259
+ }
260
+ if (result.input === "") {
261
+ const unknownFlag = filteredArgv.find((token) => token.startsWith("-"));
262
+ if (unknownFlag === void 0) return {
263
+ kind: "root-help",
264
+ help: options.help
265
+ };
266
+ return {
267
+ kind: "dispatch-error",
268
+ error: new ParseError(`Unknown flag ${unknownFlag}`, {
269
+ code: "UNKNOWN_FLAG",
270
+ suggest: `Run '${options.schema.name} --help' for available commands`
271
+ })
272
+ };
273
+ }
274
+ const suggestion = findClosestCommand(result.input, result.candidates);
275
+ const scopePath = result.parentPath.length > 0 ? `${options.schema.name} ${result.parentPath.map((schema) => schema.name).join(" ")}` : options.schema.name;
276
+ return {
277
+ kind: "dispatch-error",
278
+ error: new ParseError(`Unknown command: ${result.input}`, {
279
+ code: "UNKNOWN_COMMAND",
280
+ suggest: suggestion !== void 0 ? `Did you mean '${suggestion}'?` : `Run '${scopePath} --help' for available commands`
281
+ })
282
+ };
283
+ }
284
+ case "needs-subcommand": {
285
+ const ancestorNames = result.commandPath.slice(0, -1).map((schema) => schema.name);
286
+ return {
287
+ kind: "needs-subcommand",
288
+ command: result.command,
289
+ commandPath: result.commandPath,
290
+ help: {
291
+ ...options.help,
292
+ binName: [options.schema.name, ...ancestorNames].join(" ")
293
+ }
294
+ };
295
+ }
296
+ case "match": return buildPlannerMatchOutcome(options.schema, result.command, result.commandPath, result.remainingArgv, options.help, options.output);
297
+ }
298
+ }
299
+ //#endregion
300
+ export { buildCommandExecutionPlan, buildRootCommandMap, mergeCommandSchema, planInvocation };
@@ -1,6 +1,6 @@
1
1
  import { DeprecationWarning } from "../resolve/contracts.mjs";
2
+ import "../resolve/index.mjs";
2
3
  import { CommandMeta, CommandSchema, Out } from "../schema/command.mjs";
3
-
4
4
  //#region src/core/cli/plugin.d.ts
5
5
  /** Shared hook payload for a concrete command execution. */
6
6
  interface PluginCommandContext {
@@ -1 +1,41 @@
1
- function e(e,t){let n=Object.freeze({...e});return Object.freeze({hooks:n,name:t})}export{e as plugin};
1
+ //#region src/core/cli/plugin.ts
2
+ /**
3
+ * Create a CLI plugin from lifecycle hooks.
4
+ *
5
+ * @param hooks - Lifecycle hooks to register.
6
+ * @param name - Optional plugin name for diagnostics.
7
+ *
8
+ * @example
9
+ * ```ts
10
+ * import { cli, command, plugin } from '@kjanat/dreamcli';
11
+ *
12
+ * const deploy = command('deploy').action(({ out }) => {
13
+ * out.log('deploying');
14
+ * });
15
+ *
16
+ * const trace = plugin(
17
+ * {
18
+ * beforeParse: ({ argv, out }) => {
19
+ * out.info(`argv: ${argv.join(' ')}`);
20
+ * },
21
+ * afterResolve: ({ flags, args }) => {
22
+ * console.log({ flags, args });
23
+ * },
24
+ * },
25
+ * 'trace',
26
+ * );
27
+ *
28
+ * cli('mycli').plugin(trace).command(deploy).run();
29
+ * ```
30
+ *
31
+ * @returns A frozen {@link CLIPlugin} definition.
32
+ */
33
+ function plugin(hooks, name) {
34
+ const frozenHooks = Object.freeze({ ...hooks });
35
+ return Object.freeze({
36
+ hooks: frozenHooks,
37
+ name
38
+ });
39
+ }
40
+ //#endregion
41
+ export { plugin };
@@ -1,6 +1,6 @@
1
1
  import { FlagSchema } from "../schema/flag.mjs";
2
2
  import { CommandSchema } from "../schema/command.mjs";
3
-
3
+ import "../schema/index.mjs";
4
4
  //#region src/core/cli/propagate.d.ts
5
5
  /**
6
6
  * Collect propagated flags from a command path.
@@ -1 +1,57 @@
1
- function e(e){if(e.length<=1)return{};let t={};for(let n=0;n<e.length-1;n++){let r=e[n];if(r!==void 0){for(let[i,a]of Object.entries(r.flags))if(a.propagate){let r=!1;for(let t=n+1;t<e.length-1;t++){let n=e[t];if(n!==void 0&&i in n.flags){r=!0;break}}r||(t[i]=a)}}}let n=e[e.length-1];if(n!==void 0)for(let e of Object.keys(n.flags))delete t[e];return t}export{e as collectPropagatedFlags};
1
+ //#region src/core/cli/propagate.ts
2
+ /**
3
+ * Collect propagated flags from a command path.
4
+ *
5
+ * The command path is an ordered array of {@linkcode CommandSchema} from the root
6
+ * ancestor to the target command that will actually execute. Each ancestor's
7
+ * flags marked `propagate: true` are accumulated. If a descendant (including
8
+ * the target) defines a flag with the same name — regardless of whether the
9
+ * descendant's flag has `propagate: true` — it shadows the ancestor's flag.
10
+ *
11
+ * The target command's own flags are **not** included in the result. This
12
+ * function returns only the *inherited* propagated flags that should be merged
13
+ * into the target command's flag set before resolution.
14
+ *
15
+ * @param commandPath - Ordered schemas from root ancestor to target (inclusive).
16
+ * Must contain at least one element (the target itself). When the path has
17
+ * only one element, no ancestors exist and the result is empty.
18
+ *
19
+ * @returns A record of propagated flag schemas keyed by flag name. Empty when
20
+ * the path has no ancestors or no ancestor flags have `propagate: true`.
21
+ *
22
+ * @example
23
+ * ```ts
24
+ * // Given: root (--verbose [propagate]) → db → migrate
25
+ * // Where migrate does NOT define --verbose
26
+ * const inherited = collectPropagatedFlags([rootSchema, dbSchema, migrateSchema]);
27
+ * // inherited = { verbose: <FlagSchema from root> }
28
+ *
29
+ * // If db also defines --verbose (shadowing root):
30
+ * const inherited2 = collectPropagatedFlags([rootSchema, dbSchemaWithVerbose, migrateSchema]);
31
+ * // inherited2 = { verbose: <FlagSchema from db> }
32
+ * ```
33
+ */
34
+ function collectPropagatedFlags(commandPath) {
35
+ if (commandPath.length <= 1) return {};
36
+ const accumulated = {};
37
+ for (let i = 0; i < commandPath.length - 1; i++) {
38
+ const ancestor = commandPath[i];
39
+ if (ancestor === void 0) continue;
40
+ for (const [name, flagSchema] of Object.entries(ancestor.flags)) if (flagSchema.propagate) {
41
+ let shadowedByDescendant = false;
42
+ for (let j = i + 1; j < commandPath.length - 1; j++) {
43
+ const descendant = commandPath[j];
44
+ if (descendant !== void 0 && name in descendant.flags) {
45
+ shadowedByDescendant = true;
46
+ break;
47
+ }
48
+ }
49
+ if (!shadowedByDescendant) accumulated[name] = flagSchema;
50
+ }
51
+ }
52
+ const target = commandPath[commandPath.length - 1];
53
+ if (target !== void 0) for (const name of Object.keys(target.flags)) delete accumulated[name];
54
+ return accumulated;
55
+ }
56
+ //#endregion
57
+ export { collectPropagatedFlags };
@@ -1,6 +1,5 @@
1
1
  import { HelpOptions } from "../help/index.mjs";
2
2
  import { CommandSchema } from "../schema/command.mjs";
3
-
4
3
  //#region src/core/cli/root-help.d.ts
5
4
  /** Structural subset of `CLISchema` — avoids circular imports through the barrel. */
6
5
  interface CLISchemaLike {
@@ -13,17 +12,33 @@ interface CLISchemaLike {
13
12
  readonly defaultCommand: {
14
13
  readonly schema: CommandSchema;
15
14
  } | undefined;
15
+ /** Whether the default is also a named route — listed in `Commands:` when so. */
16
+ readonly defaultCommandRouted?: boolean | undefined;
16
17
  readonly helpLinks?: {
17
18
  readonly name: string | undefined;
18
19
  readonly version: string | undefined;
19
20
  } | undefined;
21
+ readonly completionsFlag?: {
22
+ readonly shells: readonly string[];
23
+ } | undefined;
24
+ /**
25
+ * Config discovery settings. Only its presence is read — defined means
26
+ * `.config()` enabled the built-in `--config <path>` flag, so root help
27
+ * advertises it in `Global options:`.
28
+ */
29
+ readonly configSettings?: {
30
+ readonly appName: string;
31
+ } | undefined;
20
32
  }
21
33
  /**
22
34
  * Generate root-level help text for the CLI program.
23
35
  *
24
36
  * Shows program name, version, description, usage line, and available
25
- * commands. When the default command is the only visible top-level
26
- * command, merges the root summary with that command's detailed help.
37
+ * subcommands. The default command is the CLI's root *surface*: its arguments
38
+ * and flags are rendered inline (unless `inlineDefault` is `false`) and it is
39
+ * omitted from the `Commands:` list unless `showDefaultInCommands` is set. When
40
+ * `.completions({ as: 'flag' })` is active, the eager `--completions <shell>`
41
+ * flag is advertised in the `Flags:` section.
27
42
  *
28
43
  * @internal
29
44
  */