@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.
- package/CHANGELOG.md +26 -1
- package/dist/core/cli/dispatch.mjs +214 -1
- package/dist/core/cli/help-links.mjs +41 -1
- package/dist/core/cli/index.mjs +901 -1
- package/dist/core/cli/planner.mjs +300 -1
- package/dist/core/cli/plugin.mjs +41 -1
- package/dist/core/cli/propagate.mjs +57 -1
- package/dist/core/cli/root-help.mjs +208 -4
- package/dist/core/cli/root-surface.mjs +27 -1
- package/dist/core/cli/runtime-preflight.mjs +168 -1
- package/dist/core/completion/index.mjs +90 -1
- package/dist/core/completion/shells/bash.mjs +304 -3
- package/dist/core/completion/shells/fish.mjs +159 -2
- package/dist/core/completion/shells/powershell.mjs +353 -2
- package/dist/core/completion/shells/shared.mjs +154 -1
- package/dist/core/completion/shells/zsh.mjs +244 -2
- package/dist/core/config/index.mjs +246 -1
- package/dist/core/config/package-json.mjs +385 -3
- package/dist/core/errors/index.mjs +87 -1
- package/dist/core/execution/index.mjs +189 -1
- package/dist/core/help/ansi.mjs +122 -2
- package/dist/core/help/index.mjs +329 -7
- package/dist/core/json-schema/index.mjs +487 -9
- package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
- package/dist/core/output/activity.mjs +452 -1
- package/dist/core/output/bind.mjs +56 -1
- package/dist/core/output/contracts.mjs +57 -1
- package/dist/core/output/display-value.mjs +32 -1
- package/dist/core/output/index.d.mts +21 -0
- package/dist/core/output/index.mjs +442 -2
- package/dist/core/output/renderers.mjs +46 -1
- package/dist/core/output/writer.mjs +12 -1
- package/dist/core/parse/index.mjs +555 -1
- package/dist/core/prompt/index.d.mts +0 -1
- package/dist/core/prompt/index.mjs +348 -6
- package/dist/core/resolve/args.mjs +105 -1
- package/dist/core/resolve/coerce.mjs +279 -1
- package/dist/core/resolve/config.mjs +19 -1
- package/dist/core/resolve/errors.mjs +140 -2
- package/dist/core/resolve/flags.mjs +196 -1
- package/dist/core/resolve/index.mjs +85 -1
- package/dist/core/resolve/property.d.mts +0 -1
- package/dist/core/resolve/property.mjs +45 -1
- package/dist/core/schema/arg.mjs +463 -1
- package/dist/core/schema/command.d.mts +18 -0
- package/dist/core/schema/command.mjs +712 -1
- package/dist/core/schema/flag.mjs +453 -1
- package/dist/core/schema/middleware.mjs +41 -1
- package/dist/core/schema/number-constraints.mjs +60 -1
- package/dist/core/schema-dsl/runtime.mjs +271 -2
- package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
- package/dist/core/testkit/index.mjs +83 -1
- package/dist/index.d.mts +2 -1
- package/dist/index.mjs +22 -1
- package/dist/runtime/adapter.mjs +82 -1
- package/dist/runtime/auto.mjs +46 -1
- package/dist/runtime/bun.mjs +28 -1
- package/dist/runtime/deno.mjs +217 -2
- package/dist/runtime/detect.mjs +45 -1
- package/dist/runtime/node.mjs +169 -2
- package/dist/runtime/paths.mjs +48 -1
- package/dist/runtime.mjs +7 -1
- package/dist/strings.mjs +22 -1
- package/dist/testkit.mjs +5 -1
- package/dist/version.mjs +7 -1
- package/package.json +17 -26
- package/src/core/cli/dispatch.ts +0 -355
- package/src/core/cli/help-links.ts +0 -82
- package/src/core/cli/index.ts +0 -1614
- package/src/core/cli/planner.ts +0 -656
- package/src/core/cli/plugin.ts +0 -117
- package/src/core/cli/propagate.ts +0 -97
- package/src/core/cli/root-help.ts +0 -342
- package/src/core/cli/root-surface.ts +0 -87
- package/src/core/cli/runtime-preflight.ts +0 -456
- package/src/core/completion/index.ts +0 -138
- package/src/core/completion/shells/bash.ts +0 -459
- package/src/core/completion/shells/fish.ts +0 -259
- package/src/core/completion/shells/powershell.ts +0 -439
- package/src/core/completion/shells/shared.ts +0 -310
- package/src/core/completion/shells/zsh.ts +0 -381
- package/src/core/config/index.ts +0 -417
- package/src/core/config/package-json.ts +0 -560
- package/src/core/errors/index.ts +0 -193
- package/src/core/execution/index.ts +0 -265
- package/src/core/help/ansi.ts +0 -144
- package/src/core/help/index.ts +0 -563
- package/src/core/json-schema/index.ts +0 -910
- package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
- package/src/core/output/activity.ts +0 -575
- package/src/core/output/bind.ts +0 -59
- package/src/core/output/contracts.ts +0 -194
- package/src/core/output/display-value.ts +0 -48
- package/src/core/output/index.ts +0 -704
- package/src/core/output/renderers.ts +0 -125
- package/src/core/output/writer.ts +0 -46
- package/src/core/parse/index.ts +0 -742
- package/src/core/prompt/index.ts +0 -623
- package/src/core/resolve/args.ts +0 -144
- package/src/core/resolve/coerce.ts +0 -500
- package/src/core/resolve/config.ts +0 -26
- package/src/core/resolve/contracts.ts +0 -135
- package/src/core/resolve/errors.ts +0 -227
- package/src/core/resolve/flags.ts +0 -269
- package/src/core/resolve/index.ts +0 -108
- package/src/core/resolve/property.ts +0 -99
- package/src/core/schema/activity.ts +0 -240
- package/src/core/schema/arg.ts +0 -841
- package/src/core/schema/command.ts +0 -1500
- package/src/core/schema/flag.ts +0 -917
- package/src/core/schema/index.ts +0 -96
- package/src/core/schema/middleware.ts +0 -171
- package/src/core/schema/number-constraints.ts +0 -153
- package/src/core/schema/prompt.ts +0 -171
- package/src/core/schema/run.ts +0 -198
- package/src/core/schema-dsl/index.ts +0 -109
- package/src/core/schema-dsl/parse.ts +0 -262
- package/src/core/schema-dsl/runtime.ts +0 -609
- package/src/core/schema-dsl/to-json-schema.ts +0 -102
- package/src/core/testkit/index.ts +0 -147
- package/src/index.ts +0 -181
- package/src/runtime/adapter.ts +0 -303
- package/src/runtime/auto.ts +0 -86
- package/src/runtime/bun.ts +0 -48
- package/src/runtime/deno.ts +0 -367
- package/src/runtime/detect.ts +0 -105
- package/src/runtime/index.ts +0 -21
- package/src/runtime/node-builtins.d.ts +0 -27
- package/src/runtime/node.ts +0 -289
- package/src/runtime/paths.ts +0 -64
- package/src/runtime/support.ts +0 -77
- package/src/runtime.ts +0 -31
- package/src/schema.ts +0 -16
- package/src/strings.ts +0 -34
- package/src/testkit.ts +0 -25
- package/src/version.ts +0 -20
|
@@ -1 +1,300 @@
|
|
|
1
|
-
import
|
|
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 };
|
package/dist/core/cli/plugin.mjs
CHANGED
|
@@ -1 +1,41 @@
|
|
|
1
|
-
|
|
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
|
-
|
|
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
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
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
|
-
|
|
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 };
|