@kjanat/dreamcli 3.0.0-rc.1 → 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 (136) hide show
  1. package/CHANGELOG.md +26 -1
  2. package/dist/core/cli/dispatch.mjs +214 -1
  3. package/dist/core/cli/help-links.mjs +41 -1
  4. package/dist/core/cli/index.mjs +901 -1
  5. package/dist/core/cli/planner.mjs +300 -1
  6. package/dist/core/cli/plugin.mjs +41 -1
  7. package/dist/core/cli/propagate.mjs +57 -1
  8. package/dist/core/cli/root-help.mjs +208 -4
  9. package/dist/core/cli/root-surface.mjs +27 -1
  10. package/dist/core/cli/runtime-preflight.mjs +168 -1
  11. package/dist/core/completion/index.mjs +90 -1
  12. package/dist/core/completion/shells/bash.mjs +304 -3
  13. package/dist/core/completion/shells/fish.mjs +159 -2
  14. package/dist/core/completion/shells/powershell.mjs +353 -2
  15. package/dist/core/completion/shells/shared.mjs +154 -1
  16. package/dist/core/completion/shells/zsh.mjs +244 -2
  17. package/dist/core/config/index.mjs +246 -1
  18. package/dist/core/config/package-json.mjs +385 -3
  19. package/dist/core/errors/index.mjs +87 -1
  20. package/dist/core/execution/index.mjs +189 -1
  21. package/dist/core/help/ansi.mjs +122 -2
  22. package/dist/core/help/index.mjs +329 -7
  23. package/dist/core/json-schema/index.mjs +487 -9
  24. package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
  25. package/dist/core/output/activity.mjs +452 -1
  26. package/dist/core/output/bind.mjs +56 -1
  27. package/dist/core/output/contracts.mjs +57 -1
  28. package/dist/core/output/display-value.mjs +32 -1
  29. package/dist/core/output/index.d.mts +21 -0
  30. package/dist/core/output/index.mjs +442 -2
  31. package/dist/core/output/renderers.mjs +46 -1
  32. package/dist/core/output/writer.mjs +12 -1
  33. package/dist/core/parse/index.mjs +555 -1
  34. package/dist/core/prompt/index.d.mts +0 -1
  35. package/dist/core/prompt/index.mjs +348 -6
  36. package/dist/core/resolve/args.mjs +105 -1
  37. package/dist/core/resolve/coerce.mjs +279 -1
  38. package/dist/core/resolve/config.mjs +19 -1
  39. package/dist/core/resolve/errors.mjs +140 -2
  40. package/dist/core/resolve/flags.mjs +196 -1
  41. package/dist/core/resolve/index.mjs +85 -1
  42. package/dist/core/resolve/property.d.mts +0 -1
  43. package/dist/core/resolve/property.mjs +45 -1
  44. package/dist/core/schema/arg.mjs +463 -1
  45. package/dist/core/schema/command.d.mts +18 -0
  46. package/dist/core/schema/command.mjs +712 -1
  47. package/dist/core/schema/flag.mjs +453 -1
  48. package/dist/core/schema/middleware.mjs +41 -1
  49. package/dist/core/schema/number-constraints.mjs +60 -1
  50. package/dist/core/schema-dsl/runtime.mjs +271 -2
  51. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  52. package/dist/core/testkit/index.mjs +83 -1
  53. package/dist/index.d.mts +2 -1
  54. package/dist/index.mjs +22 -1
  55. package/dist/runtime/adapter.mjs +82 -1
  56. package/dist/runtime/auto.mjs +46 -1
  57. package/dist/runtime/bun.mjs +28 -1
  58. package/dist/runtime/deno.mjs +217 -2
  59. package/dist/runtime/detect.mjs +45 -1
  60. package/dist/runtime/node.mjs +169 -2
  61. package/dist/runtime/paths.mjs +48 -1
  62. package/dist/runtime.mjs +7 -1
  63. package/dist/strings.mjs +22 -1
  64. package/dist/testkit.mjs +5 -1
  65. package/dist/version.mjs +7 -1
  66. package/package.json +17 -26
  67. package/src/core/cli/dispatch.ts +0 -355
  68. package/src/core/cli/help-links.ts +0 -82
  69. package/src/core/cli/index.ts +0 -1614
  70. package/src/core/cli/planner.ts +0 -656
  71. package/src/core/cli/plugin.ts +0 -117
  72. package/src/core/cli/propagate.ts +0 -97
  73. package/src/core/cli/root-help.ts +0 -342
  74. package/src/core/cli/root-surface.ts +0 -87
  75. package/src/core/cli/runtime-preflight.ts +0 -456
  76. package/src/core/completion/index.ts +0 -138
  77. package/src/core/completion/shells/bash.ts +0 -459
  78. package/src/core/completion/shells/fish.ts +0 -259
  79. package/src/core/completion/shells/powershell.ts +0 -439
  80. package/src/core/completion/shells/shared.ts +0 -310
  81. package/src/core/completion/shells/zsh.ts +0 -381
  82. package/src/core/config/index.ts +0 -417
  83. package/src/core/config/package-json.ts +0 -560
  84. package/src/core/errors/index.ts +0 -193
  85. package/src/core/execution/index.ts +0 -265
  86. package/src/core/help/ansi.ts +0 -144
  87. package/src/core/help/index.ts +0 -563
  88. package/src/core/json-schema/index.ts +0 -910
  89. package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
  90. package/src/core/output/activity.ts +0 -575
  91. package/src/core/output/bind.ts +0 -59
  92. package/src/core/output/contracts.ts +0 -194
  93. package/src/core/output/display-value.ts +0 -48
  94. package/src/core/output/index.ts +0 -704
  95. package/src/core/output/renderers.ts +0 -125
  96. package/src/core/output/writer.ts +0 -46
  97. package/src/core/parse/index.ts +0 -742
  98. package/src/core/prompt/index.ts +0 -623
  99. package/src/core/resolve/args.ts +0 -144
  100. package/src/core/resolve/coerce.ts +0 -500
  101. package/src/core/resolve/config.ts +0 -26
  102. package/src/core/resolve/contracts.ts +0 -135
  103. package/src/core/resolve/errors.ts +0 -227
  104. package/src/core/resolve/flags.ts +0 -269
  105. package/src/core/resolve/index.ts +0 -108
  106. package/src/core/resolve/property.ts +0 -99
  107. package/src/core/schema/activity.ts +0 -240
  108. package/src/core/schema/arg.ts +0 -841
  109. package/src/core/schema/command.ts +0 -1500
  110. package/src/core/schema/flag.ts +0 -917
  111. package/src/core/schema/index.ts +0 -96
  112. package/src/core/schema/middleware.ts +0 -171
  113. package/src/core/schema/number-constraints.ts +0 -153
  114. package/src/core/schema/prompt.ts +0 -171
  115. package/src/core/schema/run.ts +0 -198
  116. package/src/core/schema-dsl/index.ts +0 -109
  117. package/src/core/schema-dsl/parse.ts +0 -262
  118. package/src/core/schema-dsl/runtime.ts +0 -609
  119. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  120. package/src/core/testkit/index.ts +0 -147
  121. package/src/index.ts +0 -181
  122. package/src/runtime/adapter.ts +0 -303
  123. package/src/runtime/auto.ts +0 -86
  124. package/src/runtime/bun.ts +0 -48
  125. package/src/runtime/deno.ts +0 -367
  126. package/src/runtime/detect.ts +0 -105
  127. package/src/runtime/index.ts +0 -21
  128. package/src/runtime/node-builtins.d.ts +0 -27
  129. package/src/runtime/node.ts +0 -289
  130. package/src/runtime/paths.ts +0 -64
  131. package/src/runtime/support.ts +0 -77
  132. package/src/runtime.ts +0 -31
  133. package/src/schema.ts +0 -16
  134. package/src/strings.ts +0 -34
  135. package/src/testkit.ts +0 -25
  136. package/src/version.ts +0 -20
@@ -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 { 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 };
@@ -1,4 +1,208 @@
1
- import{resolveRootSurface as e}from"./root-surface.mjs";import{osc8 as t,padEnd as n,wrapText as r}from"../help/ansi.mjs";import{formatFlagEntriesBlock as i,formatHelpSections as a}from"../help/index.mjs";import{command as o}from"../schema/command.mjs";function s(t,n){let r=n?.width??80,i=n?.binName??t.name,o=n?.hyperlinks===!0,s=n?.inlineDefault??!0,l=n?.showDefaultInCommands??!1,m=e(t),h=m.visibleDefaultCommand,g=!m.hasVisibleSubcommands&&t.completionsFlag===void 0,_=s||g?h:void 0,v=c(t,_),y=v!==void 0,b=[u(t,o)];t.description!==void 0&&b.push(t.description);let x=m.hasVisibleSubcommands?h===void 0?`<command>`:`[command]`:``,S=x.length>0?`Usage: ${i} ${x} [options]`:`Usage: ${i} [options]`,C=[];y&&v!==void 0&&(C=[...a(v,{...n,binName:i,isDefaultHelp:!0})]);let w=C.shift();y&&w!==void 0&&_!==void 0?b.push(m.hasVisibleSubcommands?p(S,w):w):b.push(S);let T=l&&h!==void 0?[...m.visibleSubcommands,h]:m.visibleSubcommands;T.length>0&&b.push(d(T,l?h?.name:void 0,r)),y&&v!==void 0&&(v.description!==void 0&&v.description===t.description&&C[0]===v.description&&C.shift(),b.push(...C));let E=f(t,r);if(E.length>0&&b.push(E),n?.footer??m.hasVisibleSubcommands){let e=m.hasVisibleSubcommands?h===void 0?` <command>`:` [command]`:``;b.push(`Run '${i}${e} --help' for more information.`)}return`${b.join(`
2
-
3
- `)}\n`}function c(e,t){if(e.completionsFlag===void 0)return t;let n=t??o(e.name).schema;return{...n,flags:{completions:l(e.completionsFlag.shells),...n.flags}}}function l(e){return{kind:`enum`,presence:`optional`,defaultValue:void 0,aliases:[],envVar:void 0,configPath:void 0,description:`Print a shell completion script and exit`,enumValues:e,elementSchema:void 0,numberConstraints:void 0,prompt:void 0,parseFn:void 0,deprecated:void 0,propagate:!1}}function u(e,n){let r=n?e.helpLinks:void 0,i=r?.name===void 0?e.name:t(r.name,e.name);if(e.version===void 0)return i;let a=`v${e.version}`;return`${i} ${r?.version===void 0?a:t(r.version,a)}`}function d(e,t,i){let a=[`Commands:`],o=0;for(let n of e){let e=n.name===t?10:0,r=n.name.length+e;r>o&&(o=r)}let s=2+o+2;for(let o of e){let e=n(` ${o.name===t?`${o.name} (default)`:o.name}`,s),c=o.description??``;c.length===0?a.push(e.trimEnd()):a.push(`${e}${r(c,i,s)}`)}return a.join(`
4
- `)}function f(e,t){let n=[{left:`-h, --help`,description:`Show this help message and exit`}];return e.version!==void 0&&n.push({left:`-V, --version`,description:`Print the version number and exit`}),n.push({left:`--json`,description:`Emit machine-readable JSON output`}),e.configSettings!==void 0&&n.push({left:`--config <path>`,description:`Load configuration from the given file`}),i(`Global options:`,n,t)}function p(e,t){let n=t.startsWith(`Usage: `)?t.slice(7):t;return`${e}\n${` `.repeat(7)}${n}`}export{s as formatRootHelp};
1
+ import { resolveRootSurface } from "./root-surface.mjs";
2
+ import { osc8, padEnd, wrapText } from "../help/ansi.mjs";
3
+ import { formatFlagEntriesBlock, formatHelpSections } from "../help/index.mjs";
4
+ import { command } from "../schema/command.mjs";
5
+ //#region src/core/cli/root-help.ts
6
+ /**
7
+ * Root-level help formatter for the CLI program.
8
+ *
9
+ * Separate from `help/formatHelp()` which renders per-command help —
10
+ * different concerns, different format.
11
+ *
12
+ * @module dreamcli/core/cli/root-help
13
+ * @internal
14
+ */
15
+ /**
16
+ * Generate root-level help text for the CLI program.
17
+ *
18
+ * Shows program name, version, description, usage line, and available
19
+ * subcommands. The default command is the CLI's root *surface*: its arguments
20
+ * and flags are rendered inline (unless `inlineDefault` is `false`) and it is
21
+ * omitted from the `Commands:` list unless `showDefaultInCommands` is set. When
22
+ * `.completions({ as: 'flag' })` is active, the eager `--completions <shell>`
23
+ * flag is advertised in the `Flags:` section.
24
+ *
25
+ * @internal
26
+ */
27
+ function formatRootHelp(schema, options) {
28
+ const width = options?.width ?? 80;
29
+ const binName = options?.binName ?? schema.name;
30
+ const hyperlinks = options?.hyperlinks === true;
31
+ const inlineDefault = options?.inlineDefault ?? true;
32
+ const showDefaultInCommands = options?.showDefaultInCommands ?? false;
33
+ const surface = resolveRootSurface(schema);
34
+ const defaultCommand = surface.visibleDefaultCommand;
35
+ const defaultIsSoleSurface = !surface.hasVisibleSubcommands && schema.completionsFlag === void 0;
36
+ const inlineDefaultCommand = inlineDefault || defaultIsSoleSurface ? defaultCommand : void 0;
37
+ const surfaceCommand = resolveSurfaceCommand(schema, inlineDefaultCommand);
38
+ const inline = surfaceCommand !== void 0;
39
+ const sections = [formatHeader(schema, hyperlinks)];
40
+ if (schema.description !== void 0) sections.push(schema.description);
41
+ const placeholder = surface.hasVisibleSubcommands ? defaultCommand !== void 0 ? "[command]" : "<command>" : "";
42
+ const rootUsage = placeholder.length > 0 ? `Usage: ${binName} ${placeholder} [options]` : `Usage: ${binName} [options]`;
43
+ let surfaceSections = [];
44
+ if (inline && surfaceCommand !== void 0) surfaceSections = [...formatHelpSections(surfaceCommand, {
45
+ ...options,
46
+ binName,
47
+ isDefaultHelp: true
48
+ })];
49
+ const surfaceUsage = surfaceSections.shift();
50
+ if (inline && surfaceUsage !== void 0 && inlineDefaultCommand !== void 0) sections.push(surface.hasVisibleSubcommands ? mergeUsageSections(rootUsage, surfaceUsage) : surfaceUsage);
51
+ else sections.push(rootUsage);
52
+ const listedCommands = showDefaultInCommands && defaultCommand !== void 0 ? [...surface.visibleSubcommands, defaultCommand] : surface.visibleSubcommands;
53
+ if (listedCommands.length > 0) sections.push(formatRootCommandsSection(listedCommands, showDefaultInCommands ? defaultCommand?.name : void 0, width));
54
+ if (inline && surfaceCommand !== void 0) {
55
+ if (surfaceCommand.description !== void 0 && surfaceCommand.description === schema.description && surfaceSections[0] === surfaceCommand.description) surfaceSections.shift();
56
+ sections.push(...surfaceSections);
57
+ }
58
+ const globalOptions = formatGlobalOptionsSection(schema, width);
59
+ if (globalOptions.length > 0) sections.push(globalOptions);
60
+ if (options?.footer ?? surface.hasVisibleSubcommands) {
61
+ const footerPlaceholder = surface.hasVisibleSubcommands ? defaultCommand !== void 0 ? " [command]" : " <command>" : "";
62
+ sections.push(`Run '${binName}${footerPlaceholder} --help' for more information.`);
63
+ }
64
+ return `${sections.join("\n\n")}\n`;
65
+ }
66
+ /**
67
+ * Resolve the command rendered inline as the CLI's root surface.
68
+ *
69
+ * Returns the default command, augmented with the eager `--completions <shell>`
70
+ * flag when `.completions({ as: 'flag' })` is active. When there is no default
71
+ * command but the completions flag is configured, a synthetic surface carrying
72
+ * just that flag is returned so the flag is still advertised. Returns
73
+ * `undefined` when there is nothing to render inline.
74
+ *
75
+ * @internal
76
+ */
77
+ function resolveSurfaceCommand(schema, defaultCommand) {
78
+ if (schema.completionsFlag === void 0) return defaultCommand;
79
+ const base = defaultCommand ?? command(schema.name).schema;
80
+ return {
81
+ ...base,
82
+ flags: {
83
+ completions: completionsFlagSchema(schema.completionsFlag.shells),
84
+ ...base.flags
85
+ }
86
+ };
87
+ }
88
+ /**
89
+ * Build the synthetic, render-only flag schema for the eager `--completions`
90
+ * flag. It never participates in parsing (the planner intercepts the flag
91
+ * directly); it exists purely so root help can list
92
+ * `--completions <bash|zsh|…>` in its `Flags:` section.
93
+ *
94
+ * @internal
95
+ */
96
+ function completionsFlagSchema(shells) {
97
+ return {
98
+ kind: "enum",
99
+ presence: "optional",
100
+ defaultValue: void 0,
101
+ aliases: [],
102
+ envVar: void 0,
103
+ configPath: void 0,
104
+ description: "Print a shell completion script and exit",
105
+ enumValues: shells,
106
+ elementSchema: void 0,
107
+ numberConstraints: void 0,
108
+ prompt: void 0,
109
+ parseFn: void 0,
110
+ deprecated: void 0,
111
+ propagate: false
112
+ };
113
+ }
114
+ /**
115
+ * Render the header line (`name vX.Y.Z`).
116
+ *
117
+ * When `hyperlinks` is enabled and the schema carries link URLs (via
118
+ * `CLIBuilder.links()`, possibly derived from package.json metadata), the
119
+ * name and version are wrapped in OSC 8 hyperlinks. The header is the only
120
+ * place links are emitted — usage lines, hints, and the commands table stay
121
+ * plain.
122
+ *
123
+ * @param schema - The CLI schema.
124
+ * @param hyperlinks - Whether OSC 8 hyperlinks may be emitted.
125
+ * @returns The header line.
126
+ * @internal
127
+ */
128
+ function formatHeader(schema, hyperlinks) {
129
+ const links = hyperlinks ? schema.helpLinks : void 0;
130
+ const name = links?.name !== void 0 ? osc8(links.name, schema.name) : schema.name;
131
+ if (schema.version === void 0) return name;
132
+ const version = `v${schema.version}`;
133
+ return `${name} ${links?.version !== void 0 ? osc8(links.version, version) : version}`;
134
+ }
135
+ /**
136
+ * Format the "Commands:" section with aligned names and descriptions.
137
+ *
138
+ * @param visibleCommands - Non-hidden top-level commands.
139
+ * @param defaultName - Name of the default command (appends " (default)" tag).
140
+ * @param width - Terminal width for description wrapping.
141
+ * @returns Formatted commands block.
142
+ * @internal
143
+ */
144
+ function formatRootCommandsSection(visibleCommands, defaultName, width) {
145
+ const lines = ["Commands:"];
146
+ const GAP = 2;
147
+ const DEFAULT_TAG = " (default)";
148
+ let maxNameLen = 0;
149
+ for (const cmd of visibleCommands) {
150
+ const tagLen = cmd.name === defaultName ? 10 : 0;
151
+ const nameLen = cmd.name.length + tagLen;
152
+ if (nameLen > maxNameLen) maxNameLen = nameLen;
153
+ }
154
+ const descCol = 2 + maxNameLen + GAP;
155
+ for (const cmd of visibleCommands) {
156
+ const padded = padEnd(` ${cmd.name === defaultName ? `${cmd.name}${DEFAULT_TAG}` : cmd.name}`, descCol);
157
+ const desc = cmd.description ?? "";
158
+ if (desc.length === 0) lines.push(padded.trimEnd());
159
+ else lines.push(`${padded}${wrapText(desc, width, descCol)}`);
160
+ }
161
+ return lines.join("\n");
162
+ }
163
+ /**
164
+ * Build the `Global options:` section advertising the active built-in flags.
165
+ *
166
+ * `--help, -h` and `--json` are always available; `--version, -V` is shown only
167
+ * when the program declares a version; `--config <path>` only when `.config()`
168
+ * enabled config discovery. The eager `--completions` flag is intentionally
169
+ * omitted — it is advertised via the inline surface when active.
170
+ *
171
+ * @param schema - The CLI schema (read for `version` and `configSettings`).
172
+ * @param width - Terminal width for description wrapping.
173
+ * @returns Formatted `Global options:` block (always non-empty).
174
+ * @internal
175
+ */
176
+ function formatGlobalOptionsSection(schema, width) {
177
+ const entries = [{
178
+ left: "-h, --help",
179
+ description: "Show this help message and exit"
180
+ }];
181
+ if (schema.version !== void 0) entries.push({
182
+ left: "-V, --version",
183
+ description: "Print the version number and exit"
184
+ });
185
+ entries.push({
186
+ left: "--json",
187
+ description: "Emit machine-readable JSON output"
188
+ });
189
+ if (schema.configSettings !== void 0) entries.push({
190
+ left: "--config <path>",
191
+ description: "Load configuration from the given file"
192
+ });
193
+ return formatFlagEntriesBlock("Global options:", entries, width);
194
+ }
195
+ /**
196
+ * Merge root and default-command usage lines into a single block.
197
+ *
198
+ * @param rootUsage - The root usage line (e.g. `Usage: mycli [command] [options]`).
199
+ * @param commandUsage - The default command's usage line.
200
+ * @returns Combined usage block with aligned continuation.
201
+ * @internal
202
+ */
203
+ function mergeUsageSections(rootUsage, commandUsage) {
204
+ const commandSuffix = commandUsage.startsWith("Usage: ") ? commandUsage.slice(7) : commandUsage;
205
+ return `${rootUsage}\n${" ".repeat(7)}${commandSuffix}`;
206
+ }
207
+ //#endregion
208
+ export { formatRootHelp };
@@ -1 +1,27 @@
1
- function e(e){let t=e.commands.map(e=>e.schema).filter(e=>!e.hidden),n=e.defaultCommand?.schema,r=n!==void 0&&!n.hidden?n:void 0,i=r===void 0?t:t.filter(e=>e.name!==r.name);return{visibleCommands:t,visibleSubcommands:i,visibleDefaultCommand:r,hasVisibleDefault:r!==void 0,hasVisibleSubcommands:i.length>0}}export{e as resolveRootSurface};
1
+ //#region src/core/cli/root-surface.ts
2
+ /**
3
+ * Resolve the visible shape of the CLI root.
4
+ *
5
+ * Hidden commands are excluded from the visible command list. Hidden
6
+ * default commands remain executable, but are not surfaced through
7
+ * help or completions. The default command is reported separately from the
8
+ * real subcommands so help and completion can render it as the root surface
9
+ * instead of echoing it as a pseudo-subcommand.
10
+ *
11
+ * @internal
12
+ */
13
+ function resolveRootSurface(schema) {
14
+ const visibleCommands = schema.commands.map((command) => command.schema).filter((command) => !command.hidden);
15
+ const rawDefaultCommand = schema.defaultCommand?.schema;
16
+ const visibleDefaultCommand = rawDefaultCommand !== void 0 && !rawDefaultCommand.hidden ? rawDefaultCommand : void 0;
17
+ const visibleSubcommands = visibleDefaultCommand !== void 0 ? visibleCommands.filter((command) => command.name !== visibleDefaultCommand.name) : visibleCommands;
18
+ return {
19
+ visibleCommands,
20
+ visibleSubcommands,
21
+ visibleDefaultCommand,
22
+ hasVisibleDefault: visibleDefaultCommand !== void 0,
23
+ hasVisibleSubcommands: visibleSubcommands.length > 0
24
+ };
25
+ }
26
+ //#endregion
27
+ export { resolveRootSurface };