@kjanat/dreamcli 3.0.0-rc.1 → 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 (194) hide show
  1. package/CHANGELOG.md +217 -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
@@ -3,9 +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
+ import { ParseOptions } from "../parse/index.mjs";
6
7
  import { CompletionOptions } from "../completion/shells/shared.mjs";
7
8
  import { Shell } from "../completion/index.mjs";
8
-
9
9
  //#region src/core/cli/planner.d.ts
10
10
  /**
11
11
  * Structural subset of CLISchema used by the planner.
@@ -23,6 +23,8 @@ interface PlannerSchemaLike {
23
23
  readonly commands: readonly ErasedCommand[];
24
24
  /** Fallback command when no subcommand token matches. */
25
25
  readonly defaultCommand: ErasedCommand | undefined;
26
+ /** Whether the default command is also exposed as a named top-level route. */
27
+ readonly defaultCommandRouted: boolean;
26
28
  /**
27
29
  * Eager `--completions <shell>` flag configuration, when `.completions()`
28
30
  * was registered with `{ as: 'flag' }`. `undefined` disables interception.
@@ -31,6 +33,8 @@ interface PlannerSchemaLike {
31
33
  readonly shells: readonly Shell[];
32
34
  readonly options: CompletionOptions | undefined;
33
35
  } | undefined;
36
+ /** Flag-parsing behavior settings (case parity) applied to flag lookups. */
37
+ readonly flagSettings?: ParseOptions | undefined;
34
38
  /** Plugins forwarded into every matched execution plan. */
35
39
  readonly plugins: readonly CLIPlugin[];
36
40
  }
@@ -1 +1,300 @@
1
- import{collectPropagatedFlags as e}from"./propagate.mjs";import{CLIError as t,ParseError as n}from"../errors/index.mjs";import{normalizeShell as r}from"../completion/index.mjs";import{buildFlagLookup as i,flagExpectsValue as a,includesBeforeSeparator as o}from"../parse/index.mjs";import{dispatch as s,findClosestCommand as c}from"./dispatch.mjs";function l(e,t,n){return{name:e.name,bin:t.binName??e.name,version:e.version,command:n}}function u(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 d(t,n){let r=e(n);return Object.keys(r).length===0?t.schema:{...t.schema,flags:{...r,...t.schema.flags}}}function f(e){return{command:e.command,mergedSchema:d(e.command,e.commandPath),argv:e.argv,meta:e.meta,plugins:e.plugins,output:e.output,help:e.help}}function p(e,t,n,r,i,a){return{kind:`match`,plan:f({command:t,commandPath:n,argv:r,meta:l(e,i,t.schema.name),plugins:e.plugins,output:a,help:i})}}function m(e,t){return t===``||e.schema.args.length>0}function h(e,t){let n=i(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(`=`),i=r.slice(2,e===-1?void 0:e),o=n.get(i);if(o===void 0)return e===-1?r:`--${i}`;e===-1&&a(o[1])&&t++;continue}let i=r.slice(1);for(let e=0;e<i.length;e++){let r=i.charAt(e),o=n.get(r);if(o===void 0)return`-${r}`;if(a(o[1])){e===i.length-1&&t++;break}}}}function g(e,t){for(let n=0;n<e.length;n++){let r=e[n];if(r===void 0)continue;if(r===`--help`||r===`-h`)return{helpBeforeCommand:!0,firstCommandToken:void 0,commandTokenIndex:-1};if(r===`-`||!r.startsWith(`-`))return{helpBeforeCommand:!1,firstCommandToken:r,commandTokenIndex:n};if(r.startsWith(`--`)){let e=r.indexOf(`=`),i=r.slice(2,e===-1?void 0:e),o=t?.get(i);o!==void 0&&e===-1&&a(o[1])&&n++;continue}let i=r.slice(1);for(let e=0;e<i.length;e++){let r=t?.get(i.charAt(e));if(!(r===void 0||!a(r[1]))){e===i.length-1&&n++;break}}}return{helpBeforeCommand:!1,firstCommandToken:void 0,commandTokenIndex:-1}}function _(e,t){let i=e.indexOf(`--`),a=i===-1?e.length:i;for(let i=0;i<a;i++){let o=e[i];if(o===void 0)continue;let s;if(o===`--completions`){let t=i+1<a?e[i+1]:void 0;s=t!==void 0&&!t.startsWith(`-`)?t:void 0}else if(o.startsWith(`--completions=`))s=o.slice(14);else continue;if(s===void 0||s===``)return{kind:`root-completions`,shell:void 0,options:t.options};let c=r(s);return c===void 0||!t.shells.includes(c)?{kind:`dispatch-error`,error:new n(`Unknown shell '${s}'`,{code:`INVALID_VALUE`,suggest:`Valid shells: ${t.shells.join(`, `)}`})}:{kind:`root-completions`,shell:c,options:t.options}}}function v(e){let r=e.argv.indexOf(`--`),a=r===-1?e.argv:e.argv.slice(0,r),l=r===-1?[]:e.argv.slice(r),d=a.includes(`--json`)?a.filter(e=>e!==`--json`):a,f=r===-1?d:[...d,...l],y=e.schema.defaultCommand,b=y===void 0?void 0:i(y.schema.flags);if(e.schema.version!==void 0&&(o(e.argv,`--version`)||o(e.argv,`-V`)))return{kind:`root-version`,version:e.schema.version};if(e.schema.completionsFlag!==void 0){let t=_(e.argv,e.schema.completionsFlag);if(t!==void 0)return t}let x=g(d,b);if(x.helpBeforeCommand)return{kind:`root-help`,help:e.help};if(x.firstCommandToken===`help`&&!e.schema.commands.some(e=>e.schema.name===`help`||e.schema.aliases.includes(`help`))){let t=f.slice(x.commandTokenIndex+1);return t.length===0?{kind:`root-help`,help:e.help}:v({...e,argv:[...t,`--help`]})}if(e.schema.commands.length===0&&y===void 0)return{kind:`dispatch-error`,error:new t(`No commands registered`,{code:`NO_ACTION`,suggest:`Add commands via .command() or .default() before calling .run()`})};if(f.length===0&&y===void 0)return{kind:`root-help`,help:e.help};let S=s(f,u(e.schema.commands),[],b);switch(S.kind){case`unknown`:{if(y!==void 0&&S.parentPath.length===0){if((S.input===``?void 0:c(S.input,S.candidates))===void 0&&m(y,S.input))return p(e.schema,y,[y.schema],f,e.help,e.output);let t=h(f,y.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(S.input===``){let t=f.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=c(S.input,S.candidates),r=S.parentPath.length>0?`${e.schema.name} ${S.parentPath.map(e=>e.name).join(` `)}`:e.schema.name;return{kind:`dispatch-error`,error:new n(`Unknown command: ${S.input}`,{code:`UNKNOWN_COMMAND`,suggest:t===void 0?`Run '${r} --help' for available commands`:`Did you mean '${t}'?`})}}case`needs-subcommand`:{let t=S.commandPath.slice(0,-1).map(e=>e.name);return{kind:`needs-subcommand`,command:S.command,commandPath:S.commandPath,help:{...e.help,binName:[e.schema.name,...t].join(` `)}}}case`match`:return p(e.schema,S.command,S.commandPath,S.remainingArgv,e.help,e.output)}}export{v 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,6 +12,8 @@ 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;