@kjanat/dreamcli 2.5.0 → 3.0.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (160) hide show
  1. package/CHANGELOG.md +153 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/dispatch.mjs +214 -1
  4. package/dist/core/cli/help-links.mjs +41 -1
  5. package/dist/core/cli/index.d.mts +109 -16
  6. package/dist/core/cli/index.mjs +901 -1
  7. package/dist/core/cli/planner.d.mts +27 -5
  8. package/dist/core/cli/planner.mjs +300 -1
  9. package/dist/core/cli/plugin.mjs +41 -1
  10. package/dist/core/cli/propagate.mjs +57 -1
  11. package/dist/core/cli/root-help.d.mts +16 -2
  12. package/dist/core/cli/root-help.mjs +208 -6
  13. package/dist/core/cli/root-surface.d.mts +18 -3
  14. package/dist/core/cli/root-surface.mjs +27 -1
  15. package/dist/core/cli/runtime-preflight.d.mts +16 -1
  16. package/dist/core/cli/runtime-preflight.mjs +168 -1
  17. package/dist/core/completion/index.d.mts +32 -1
  18. package/dist/core/completion/index.mjs +90 -1
  19. package/dist/core/completion/shells/bash.mjs +304 -3
  20. package/dist/core/completion/shells/fish.mjs +159 -2
  21. package/dist/core/completion/shells/powershell.mjs +353 -2
  22. package/dist/core/completion/shells/shared.d.mts +10 -0
  23. package/dist/core/completion/shells/shared.mjs +154 -1
  24. package/dist/core/completion/shells/zsh.mjs +244 -2
  25. package/dist/core/config/index.mjs +246 -1
  26. package/dist/core/config/package-json.mjs +385 -3
  27. package/dist/core/errors/index.mjs +87 -1
  28. package/dist/core/execution/index.mjs +189 -1
  29. package/dist/core/help/ansi.mjs +122 -2
  30. package/dist/core/help/index.d.mts +45 -1
  31. package/dist/core/help/index.mjs +329 -7
  32. package/dist/core/json-schema/index.mjs +487 -9
  33. package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
  34. package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
  35. package/dist/core/output/activity.mjs +452 -1
  36. package/dist/core/output/bind.mjs +56 -1
  37. package/dist/core/output/contracts.mjs +57 -1
  38. package/dist/core/output/display-value.mjs +32 -1
  39. package/dist/core/output/index.d.mts +21 -0
  40. package/dist/core/output/index.mjs +442 -2
  41. package/dist/core/output/renderers.mjs +46 -1
  42. package/dist/core/output/writer.mjs +12 -1
  43. package/dist/core/parse/index.d.mts +15 -1
  44. package/dist/core/parse/index.mjs +555 -1
  45. package/dist/core/prompt/index.d.mts +11 -4
  46. package/dist/core/prompt/index.mjs +348 -6
  47. package/dist/core/resolve/args.mjs +105 -1
  48. package/dist/core/resolve/coerce.mjs +279 -1
  49. package/dist/core/resolve/config.mjs +19 -1
  50. package/dist/core/resolve/errors.mjs +140 -2
  51. package/dist/core/resolve/flags.mjs +196 -1
  52. package/dist/core/resolve/index.mjs +85 -1
  53. package/dist/core/resolve/property.d.mts +2 -1
  54. package/dist/core/resolve/property.mjs +45 -1
  55. package/dist/core/schema/arg.d.mts +90 -10
  56. package/dist/core/schema/arg.mjs +463 -1
  57. package/dist/core/schema/command.d.mts +21 -1
  58. package/dist/core/schema/command.mjs +712 -1
  59. package/dist/core/schema/flag.d.mts +92 -2
  60. package/dist/core/schema/flag.mjs +453 -1
  61. package/dist/core/schema/index.d.mts +2 -1
  62. package/dist/core/schema/middleware.mjs +41 -1
  63. package/dist/core/schema/number-constraints.d.mts +96 -0
  64. package/dist/core/schema/number-constraints.mjs +60 -0
  65. package/dist/core/schema/prompt.d.mts +15 -0
  66. package/dist/core/schema/run.d.mts +4 -4
  67. package/dist/core/schema-dsl/runtime.mjs +271 -2
  68. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  69. package/dist/core/testkit/index.d.mts +9 -5
  70. package/dist/core/testkit/index.mjs +83 -1
  71. package/dist/index.d.mts +3 -1
  72. package/dist/index.mjs +22 -1
  73. package/dist/runtime/adapter.mjs +82 -1
  74. package/dist/runtime/auto.mjs +46 -1
  75. package/dist/runtime/bun.mjs +28 -1
  76. package/dist/runtime/deno.mjs +217 -2
  77. package/dist/runtime/detect.mjs +45 -1
  78. package/dist/runtime/node.mjs +169 -2
  79. package/dist/runtime/paths.mjs +48 -1
  80. package/dist/runtime.mjs +7 -1
  81. package/dist/strings.mjs +22 -1
  82. package/dist/testkit.mjs +5 -1
  83. package/dist/version.mjs +7 -1
  84. package/examples/basic.ts +5 -1
  85. package/examples/gh/package.json +2 -7
  86. package/examples/pwsh-demo/package.json +1 -7
  87. package/examples/pwsh-demo/src/main.test.ts +1 -4
  88. package/examples/pwsh-demo/src/main.ts +14 -4
  89. package/examples/transport-launcher.ts +85 -0
  90. package/package.json +23 -41
  91. package/dist/runtime/support.d.mts +0 -42
  92. package/dist/runtime/support.mjs +0 -1
  93. package/src/core/cli/dispatch.ts +0 -349
  94. package/src/core/cli/help-links.ts +0 -82
  95. package/src/core/cli/index.ts +0 -1413
  96. package/src/core/cli/planner.ts +0 -487
  97. package/src/core/cli/plugin.ts +0 -117
  98. package/src/core/cli/propagate.ts +0 -97
  99. package/src/core/cli/root-help.ts +0 -252
  100. package/src/core/cli/root-surface.ts +0 -74
  101. package/src/core/cli/runtime-preflight.ts +0 -438
  102. package/src/core/completion/index.ts +0 -88
  103. package/src/core/completion/shells/bash.ts +0 -459
  104. package/src/core/completion/shells/fish.ts +0 -259
  105. package/src/core/completion/shells/powershell.ts +0 -439
  106. package/src/core/completion/shells/shared.ts +0 -283
  107. package/src/core/completion/shells/zsh.ts +0 -381
  108. package/src/core/config/index.ts +0 -417
  109. package/src/core/config/package-json.ts +0 -560
  110. package/src/core/errors/index.ts +0 -193
  111. package/src/core/execution/index.ts +0 -268
  112. package/src/core/help/ansi.ts +0 -144
  113. package/src/core/help/index.ts +0 -516
  114. package/src/core/json-schema/index.ts +0 -891
  115. package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
  116. package/src/core/output/activity.ts +0 -575
  117. package/src/core/output/bind.ts +0 -59
  118. package/src/core/output/contracts.ts +0 -194
  119. package/src/core/output/display-value.ts +0 -48
  120. package/src/core/output/index.ts +0 -704
  121. package/src/core/output/renderers.ts +0 -125
  122. package/src/core/output/writer.ts +0 -46
  123. package/src/core/parse/index.ts +0 -681
  124. package/src/core/prompt/index.ts +0 -583
  125. package/src/core/resolve/args.ts +0 -144
  126. package/src/core/resolve/coerce.ts +0 -432
  127. package/src/core/resolve/config.ts +0 -26
  128. package/src/core/resolve/contracts.ts +0 -135
  129. package/src/core/resolve/errors.ts +0 -227
  130. package/src/core/resolve/flags.ts +0 -255
  131. package/src/core/resolve/index.ts +0 -108
  132. package/src/core/resolve/property.ts +0 -99
  133. package/src/core/schema/activity.ts +0 -240
  134. package/src/core/schema/arg.ts +0 -719
  135. package/src/core/schema/command.ts +0 -1498
  136. package/src/core/schema/flag.ts +0 -801
  137. package/src/core/schema/index.ts +0 -91
  138. package/src/core/schema/middleware.ts +0 -171
  139. package/src/core/schema/prompt.ts +0 -156
  140. package/src/core/schema/run.ts +0 -198
  141. package/src/core/schema-dsl/index.ts +0 -109
  142. package/src/core/schema-dsl/parse.ts +0 -262
  143. package/src/core/schema-dsl/runtime.ts +0 -609
  144. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  145. package/src/core/testkit/index.ts +0 -123
  146. package/src/index.ts +0 -179
  147. package/src/runtime/adapter.ts +0 -303
  148. package/src/runtime/auto.ts +0 -110
  149. package/src/runtime/bun.ts +0 -55
  150. package/src/runtime/deno.ts +0 -369
  151. package/src/runtime/detect.ts +0 -105
  152. package/src/runtime/index.ts +0 -21
  153. package/src/runtime/node-builtins.d.ts +0 -27
  154. package/src/runtime/node.ts +0 -300
  155. package/src/runtime/paths.ts +0 -64
  156. package/src/runtime/support.ts +0 -135
  157. package/src/runtime.ts +0 -31
  158. package/src/strings.ts +0 -34
  159. package/src/testkit.ts +0 -25
  160. package/src/version.ts +0 -20
@@ -3,6 +3,8 @@ 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 { CompletionOptions } from "../completion/shells/shared.mjs";
7
+ import { Shell } from "../completion/index.mjs";
6
8
 
7
9
  //#region src/core/cli/planner.d.ts
8
10
  /**
@@ -21,6 +23,14 @@ interface PlannerSchemaLike {
21
23
  readonly commands: readonly ErasedCommand[];
22
24
  /** Fallback command when no subcommand token matches. */
23
25
  readonly defaultCommand: ErasedCommand | undefined;
26
+ /**
27
+ * Eager `--completions <shell>` flag configuration, when `.completions()`
28
+ * was registered with `{ as: 'flag' }`. `undefined` disables interception.
29
+ */
30
+ readonly completionsFlag: {
31
+ readonly shells: readonly Shell[];
32
+ readonly options: CompletionOptions | undefined;
33
+ } | undefined;
24
34
  /** Plugins forwarded into every matched execution plan. */
25
35
  readonly plugins: readonly CLIPlugin[];
26
36
  }
@@ -38,6 +48,18 @@ interface RootVersionOutcome {
38
48
  /** Resolved version string to render. */
39
49
  readonly version: string;
40
50
  }
51
+ /** Root-level `--completions [shell]` interception outcome. */
52
+ interface RootCompletionsOutcome {
53
+ /** Discriminant — argv matched the eager `--completions [shell]` flag. */
54
+ readonly kind: 'root-completions';
55
+ /**
56
+ * Resolved, validated target shell, or `undefined` when the flag was given
57
+ * without a value and the shell should be auto-detected from the environment.
58
+ */
59
+ readonly shell: Shell | undefined;
60
+ /** Generator options captured at build time. */
61
+ readonly options: CompletionOptions | undefined;
62
+ }
41
63
  /** CLI-level dispatch failure before command execution starts. */
42
64
  interface DispatchErrorOutcome {
43
65
  /** Discriminant — dispatch could not resolve a command from argv. */
@@ -58,7 +80,7 @@ interface PlannerMatchOutcome {
58
80
  * `CLIBuilder.execute()` still renders and executes these outcomes, but
59
81
  * planning itself is intentionally bounded to this union.
60
82
  */
61
- type DispatchOutcome = RootHelpOutcome | RootVersionOutcome | DispatchErrorOutcome | PlannerMatchOutcome;
83
+ type DispatchOutcome = RootHelpOutcome | RootVersionOutcome | RootCompletionsOutcome | DispatchErrorOutcome | PlannerMatchOutcome;
62
84
  /**
63
85
  * Concrete execution handoff produced by a successful planner match.
64
86
  *
@@ -133,11 +155,11 @@ declare function buildCommandExecutionPlan(options: BuildCommandExecutionPlanOpt
133
155
  /**
134
156
  * Decide what to do with an argv invocation before any command executes.
135
157
  *
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.
158
+ * Handles root interception (`--help`, `--version`, `--completions <shell>`,
159
+ * bare `help` token), dispatches into the command tree, falls back to the
160
+ * default command, and produces structured errors for unknown commands/flags.
139
161
  * @internal
140
162
  */
141
163
  declare function planInvocation(options: PlanInvocationOptions): InvocationPlan;
142
164
  //#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 };
165
+ 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 { collectPropagatedFlags } from "./propagate.mjs";
2
+ import { CLIError, ParseError } from "../errors/index.mjs";
3
+ import { normalizeShell } from "../completion/index.mjs";
4
+ import { buildFlagLookup, flagExpectsValue, includesBeforeSeparator } from "../parse/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) {
79
+ const lookup = buildFlagLookup(flags);
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[1])) 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[1])) 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[1])) 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[1])) 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) : 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(options.schema.commands), [], rootValueFlags);
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);
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 { planInvocation };
@@ -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 +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 };
@@ -17,13 +17,27 @@ interface CLISchemaLike {
17
17
  readonly name: string | undefined;
18
18
  readonly version: string | undefined;
19
19
  } | undefined;
20
+ readonly completionsFlag?: {
21
+ readonly shells: readonly string[];
22
+ } | undefined;
23
+ /**
24
+ * Config discovery settings. Only its presence is read — defined means
25
+ * `.config()` enabled the built-in `--config <path>` flag, so root help
26
+ * advertises it in `Global options:`.
27
+ */
28
+ readonly configSettings?: {
29
+ readonly appName: string;
30
+ } | undefined;
20
31
  }
21
32
  /**
22
33
  * Generate root-level help text for the CLI program.
23
34
  *
24
35
  * 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.
36
+ * subcommands. The default command is the CLI's root *surface*: its arguments
37
+ * and flags are rendered inline (unless `inlineDefault` is `false`) and it is
38
+ * omitted from the `Commands:` list unless `showDefaultInCommands` is set. When
39
+ * `.completions({ as: 'flag' })` is active, the eager `--completions <shell>`
40
+ * flag is advertised in the `Flags:` section.
27
41
  *
28
42
  * @internal
29
43
  */