@kjanat/dreamcli 2.5.0 → 3.0.0-rc.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +344 -1
- package/README.md +9 -2
- package/dist/core/cli/dispatch.d.mts +6 -5
- package/dist/core/cli/dispatch.mjs +205 -1
- package/dist/core/cli/help-links.d.mts +0 -1
- package/dist/core/cli/help-links.mjs +41 -1
- package/dist/core/cli/index.d.mts +185 -19
- package/dist/core/cli/index.mjs +945 -1
- package/dist/core/cli/planner.d.mts +32 -6
- package/dist/core/cli/planner.mjs +300 -1
- package/dist/core/cli/plugin.d.mts +1 -1
- package/dist/core/cli/plugin.mjs +41 -1
- package/dist/core/cli/propagate.d.mts +1 -1
- package/dist/core/cli/propagate.mjs +57 -1
- package/dist/core/cli/root-help.d.mts +18 -3
- package/dist/core/cli/root-help.mjs +226 -6
- package/dist/core/cli/root-surface.d.mts +30 -4
- package/dist/core/cli/root-surface.mjs +28 -1
- package/dist/core/cli/runtime-preflight.d.mts +30 -3
- package/dist/core/cli/runtime-preflight.mjs +169 -1
- package/dist/core/completion/index.d.mts +32 -2
- package/dist/core/completion/index.mjs +90 -1
- package/dist/core/completion/shells/bash.d.mts +0 -1
- package/dist/core/completion/shells/bash.mjs +308 -3
- package/dist/core/completion/shells/fish.d.mts +0 -1
- package/dist/core/completion/shells/fish.mjs +162 -2
- package/dist/core/completion/shells/powershell.d.mts +0 -1
- package/dist/core/completion/shells/powershell.mjs +358 -2
- package/dist/core/completion/shells/shared.d.mts +23 -2
- package/dist/core/completion/shells/shared.mjs +176 -1
- package/dist/core/completion/shells/zsh.d.mts +0 -1
- package/dist/core/completion/shells/zsh.mjs +251 -2
- package/dist/core/config/index.d.mts +2 -3
- package/dist/core/config/index.mjs +246 -1
- package/dist/core/config/package-json.d.mts +27 -4
- package/dist/core/config/package-json.mjs +386 -3
- package/dist/core/errors/index.d.mts +3 -3
- package/dist/core/errors/index.mjs +87 -1
- package/dist/core/execution/index.d.mts +0 -1
- package/dist/core/execution/index.mjs +201 -1
- package/dist/core/help/ansi.d.mts +11 -5
- package/dist/core/help/ansi.mjs +121 -2
- package/dist/core/help/index.d.mts +65 -2
- package/dist/core/help/index.mjs +341 -7
- package/dist/core/help/theme.d.mts +68 -0
- package/dist/core/help/theme.mjs +46 -0
- package/dist/core/json-schema/index.d.mts +15 -2
- package/dist/core/json-schema/index.mjs +536 -12
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
- package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
- package/dist/core/output/activity.d.mts +0 -1
- package/dist/core/output/activity.mjs +452 -1
- package/dist/core/output/bind.mjs +56 -1
- package/dist/core/output/contracts.d.mts +4 -5
- 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 -1
- package/dist/core/output/index.mjs +442 -2
- package/dist/core/output/renderers.d.mts +0 -1
- package/dist/core/output/renderers.mjs +46 -1
- package/dist/core/output/writer.mjs +12 -1
- package/dist/core/parse/index.d.mts +54 -7
- package/dist/core/parse/index.mjs +727 -1
- package/dist/core/prompt/index.d.mts +12 -4
- package/dist/core/prompt/index.mjs +348 -6
- package/dist/core/resolve/args.d.mts +1 -1
- package/dist/core/resolve/args.mjs +105 -1
- package/dist/core/resolve/coerce.d.mts +1 -1
- package/dist/core/resolve/coerce.mjs +336 -1
- package/dist/core/resolve/config.mjs +19 -1
- package/dist/core/resolve/contracts.d.mts +9 -4
- package/dist/core/resolve/errors.d.mts +0 -1
- package/dist/core/resolve/errors.mjs +140 -2
- package/dist/core/resolve/flags.d.mts +7 -2
- package/dist/core/resolve/flags.mjs +251 -1
- package/dist/core/resolve/index.d.mts +2 -2
- package/dist/core/resolve/index.mjs +85 -1
- package/dist/core/resolve/property.d.mts +6 -2
- package/dist/core/resolve/property.mjs +53 -1
- package/dist/core/schema/activity.d.mts +31 -11
- package/dist/core/schema/arg.d.mts +92 -13
- package/dist/core/schema/arg.mjs +463 -1
- package/dist/core/schema/command.d.mts +29 -7
- package/dist/core/schema/command.mjs +726 -1
- package/dist/core/schema/flag.d.mts +577 -21
- package/dist/core/schema/flag.mjs +705 -1
- package/dist/core/schema/index.d.mts +5 -2
- package/dist/core/schema/middleware.d.mts +4 -3
- package/dist/core/schema/middleware.mjs +41 -1
- package/dist/core/schema/number-constraints.d.mts +96 -0
- package/dist/core/schema/number-constraints.mjs +60 -0
- package/dist/core/schema/prompt.d.mts +21 -3
- package/dist/core/schema/run.d.mts +24 -5
- package/dist/core/schema/string-constraints.d.mts +97 -0
- package/dist/core/schema/string-constraints.mjs +69 -0
- package/dist/core/schema/value-parsers.d.mts +78 -0
- package/dist/core/schema/value-parsers.mjs +142 -0
- package/dist/core/schema-dsl/runtime.mjs +271 -2
- package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
- package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
- package/dist/core/testkit/index.d.mts +9 -36
- package/dist/core/testkit/index.mjs +83 -1
- package/dist/index.d.mts +12 -6
- package/dist/index.mjs +22 -1
- package/dist/runtime/adapter.d.mts +38 -2
- package/dist/runtime/adapter.mjs +87 -1
- package/dist/runtime/auto.d.mts +2 -3
- package/dist/runtime/auto.mjs +45 -1
- package/dist/runtime/deno.d.mts +24 -5
- package/dist/runtime/deno.mjs +262 -2
- package/dist/runtime/detect.mjs +45 -1
- package/dist/runtime/index.d.mts +3 -4
- package/dist/runtime/node.d.mts +8 -2
- package/dist/runtime/node.mjs +220 -2
- package/dist/runtime/paths.mjs +48 -1
- package/dist/runtime.d.mts +4 -4
- package/dist/runtime.mjs +6 -1
- package/dist/strings.mjs +22 -1
- package/dist/testkit.d.mts +1 -0
- package/dist/testkit.mjs +5 -1
- package/dist/version.d.mts +7 -3
- package/dist/version.mjs +7 -1
- package/dreamcli.schema.json +36 -7
- package/examples/basic.ts +5 -1
- package/examples/gh/package.json +2 -7
- package/examples/pwsh-demo/package.json +1 -7
- package/examples/pwsh-demo/src/main.test.ts +1 -4
- package/examples/pwsh-demo/src/main.ts +14 -4
- package/examples/transport-launcher.ts +85 -0
- package/package.json +43 -49
- package/dist/runtime/bun.d.mts +0 -28
- package/dist/runtime/bun.mjs +0 -1
- package/dist/runtime/support.d.mts +0 -42
- package/dist/runtime/support.mjs +0 -1
- package/src/core/cli/dispatch.ts +0 -349
- package/src/core/cli/help-links.ts +0 -82
- package/src/core/cli/index.ts +0 -1413
- package/src/core/cli/planner.ts +0 -487
- package/src/core/cli/plugin.ts +0 -117
- package/src/core/cli/propagate.ts +0 -97
- package/src/core/cli/root-help.ts +0 -252
- package/src/core/cli/root-surface.ts +0 -74
- package/src/core/cli/runtime-preflight.ts +0 -438
- package/src/core/completion/index.ts +0 -88
- 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 -283
- 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 -268
- package/src/core/help/ansi.ts +0 -144
- package/src/core/help/index.ts +0 -516
- package/src/core/json-schema/index.ts +0 -891
- package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
- 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 -681
- package/src/core/prompt/index.ts +0 -583
- package/src/core/resolve/args.ts +0 -144
- package/src/core/resolve/coerce.ts +0 -432
- 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 -255
- 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 -719
- package/src/core/schema/command.ts +0 -1498
- package/src/core/schema/flag.ts +0 -801
- package/src/core/schema/index.ts +0 -91
- package/src/core/schema/middleware.ts +0 -171
- package/src/core/schema/prompt.ts +0 -156
- 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 -123
- package/src/index.ts +0 -179
- package/src/runtime/adapter.ts +0 -303
- package/src/runtime/auto.ts +0 -110
- package/src/runtime/bun.ts +0 -55
- package/src/runtime/deno.ts +0 -369
- 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 -300
- package/src/runtime/paths.ts +0 -64
- package/src/runtime/support.ts +0 -135
- package/src/runtime.ts +0 -31
- package/src/strings.ts +0 -34
- package/src/testkit.ts +0 -25
- package/src/version.ts +0 -20
|
@@ -1,6 +1,226 @@
|
|
|
1
|
-
import{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
1
|
+
import { command } from "../schema/command.mjs";
|
|
2
|
+
import { resolveRootSurface } from "./root-surface.mjs";
|
|
3
|
+
import { osc8, padEnd, wrapText } from "../help/ansi.mjs";
|
|
4
|
+
import { resolveHelpTheme } from "../help/theme.mjs";
|
|
5
|
+
import { formatFlagEntriesBlock, formatHelpSections } from "../help/index.mjs";
|
|
6
|
+
//#region src/core/cli/root-help.ts
|
|
7
|
+
/**
|
|
8
|
+
* Root-level help formatter for the CLI program.
|
|
9
|
+
*
|
|
10
|
+
* Separate from `help/formatHelp()` which renders per-command help —
|
|
11
|
+
* different concerns, different format.
|
|
12
|
+
*
|
|
13
|
+
* @module dreamcli/core/cli/root-help
|
|
14
|
+
* @internal
|
|
15
|
+
*/
|
|
16
|
+
/**
|
|
17
|
+
* Generate root-level help text for the CLI program.
|
|
18
|
+
*
|
|
19
|
+
* Shows program name, version, description, usage line, and available
|
|
20
|
+
* subcommands. The default command is the CLI's root *surface*: its arguments
|
|
21
|
+
* and flags are rendered inline (unless `inlineDefault` is `false`) and it is
|
|
22
|
+
* omitted from the `Commands:` list unless `showDefaultInCommands` is set. When
|
|
23
|
+
* `.completions({ as: 'flag' })` is active, the eager `--completions <shell>`
|
|
24
|
+
* flag is advertised in the `Flags:` section.
|
|
25
|
+
*
|
|
26
|
+
* @internal
|
|
27
|
+
*/
|
|
28
|
+
function formatRootHelp(schema, options) {
|
|
29
|
+
const width = options?.width ?? 80;
|
|
30
|
+
const binName = options?.binName ?? schema.name;
|
|
31
|
+
const hyperlinks = options?.hyperlinks === true;
|
|
32
|
+
const inlineDefault = options?.inlineDefault ?? true;
|
|
33
|
+
const showDefaultInCommands = options?.showDefaultInCommands ?? false;
|
|
34
|
+
const theme = resolveHelpTheme(options?.colors, options?.theme);
|
|
35
|
+
const surface = resolveRootSurface(schema);
|
|
36
|
+
const defaultCommand = surface.visibleDefaultCommand;
|
|
37
|
+
const defaultIsSoleSurface = !surface.hasVisibleSubcommands && schema.completionsFlag === void 0;
|
|
38
|
+
const inlineDefaultCommand = inlineDefault || defaultIsSoleSurface ? defaultCommand : void 0;
|
|
39
|
+
const surfaceCommand = resolveSurfaceCommand(schema, inlineDefaultCommand);
|
|
40
|
+
const inline = surfaceCommand !== void 0;
|
|
41
|
+
const sections = [formatHeader(schema, hyperlinks, theme)];
|
|
42
|
+
if (schema.description !== void 0) sections.push(schema.description);
|
|
43
|
+
const placeholder = surface.hasVisibleSubcommands ? defaultCommand !== void 0 ? "[command]" : "<command>" : "";
|
|
44
|
+
const usageTitle = theme.sectionTitle("Usage:");
|
|
45
|
+
const rootUsage = placeholder.length > 0 ? `${usageTitle} ${theme.usageBin(binName)} ${theme.placeholder(placeholder)} ${theme.placeholder("[options]")}` : `${usageTitle} ${theme.usageBin(binName)} ${theme.placeholder("[options]")}`;
|
|
46
|
+
let surfaceSections = [];
|
|
47
|
+
if (inline && surfaceCommand !== void 0) surfaceSections = [...formatHelpSections(surfaceCommand, {
|
|
48
|
+
...options,
|
|
49
|
+
binName,
|
|
50
|
+
isDefaultHelp: true
|
|
51
|
+
})];
|
|
52
|
+
const surfaceUsage = surfaceSections.shift();
|
|
53
|
+
if (inline && surfaceUsage !== void 0 && inlineDefaultCommand !== void 0) sections.push(surface.hasVisibleSubcommands ? mergeUsageSections(rootUsage, surfaceUsage, usageTitle) : surfaceUsage);
|
|
54
|
+
else sections.push(rootUsage);
|
|
55
|
+
const listDefaultInCommands = defaultCommand !== void 0 && (surface.defaultRouted || showDefaultInCommands);
|
|
56
|
+
const listedCommands = listDefaultInCommands ? [...surface.visibleSubcommands, defaultCommand] : surface.visibleSubcommands;
|
|
57
|
+
if (listedCommands.length > 0) sections.push(formatRootCommandsSection(listedCommands, listDefaultInCommands ? defaultCommand?.name : void 0, width, theme));
|
|
58
|
+
if (inline && surfaceCommand !== void 0) {
|
|
59
|
+
if (surfaceCommand.description !== void 0 && surfaceCommand.description === schema.description && surfaceSections[0] === surfaceCommand.description) surfaceSections.shift();
|
|
60
|
+
sections.push(...surfaceSections);
|
|
61
|
+
}
|
|
62
|
+
const globalOptions = formatGlobalOptionsSection(schema, width, theme);
|
|
63
|
+
if (globalOptions.length > 0) sections.push(globalOptions);
|
|
64
|
+
if (options?.footer ?? surface.hasVisibleSubcommands) {
|
|
65
|
+
const footerPlaceholder = surface.hasVisibleSubcommands ? defaultCommand !== void 0 ? " [command]" : " <command>" : "";
|
|
66
|
+
sections.push(`Run '${binName}${footerPlaceholder} --help' for more information.`);
|
|
67
|
+
}
|
|
68
|
+
return `${sections.join("\n\n")}\n`;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Resolve the command rendered inline as the CLI's root surface.
|
|
72
|
+
*
|
|
73
|
+
* Returns the default command, augmented with the eager `--completions <shell>`
|
|
74
|
+
* flag when `.completions({ as: 'flag' })` is active. When there is no default
|
|
75
|
+
* command but the completions flag is configured, a synthetic surface carrying
|
|
76
|
+
* just that flag is returned so the flag is still advertised. Returns
|
|
77
|
+
* `undefined` when there is nothing to render inline.
|
|
78
|
+
*
|
|
79
|
+
* @internal
|
|
80
|
+
*/
|
|
81
|
+
function resolveSurfaceCommand(schema, defaultCommand) {
|
|
82
|
+
if (schema.completionsFlag === void 0) return defaultCommand;
|
|
83
|
+
const base = defaultCommand ?? command(schema.name).schema;
|
|
84
|
+
return {
|
|
85
|
+
...base,
|
|
86
|
+
flags: {
|
|
87
|
+
completions: completionsFlagSchema(schema.completionsFlag.shells),
|
|
88
|
+
...base.flags
|
|
89
|
+
}
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Build the synthetic, render-only flag schema for the eager `--completions`
|
|
94
|
+
* flag. It never participates in parsing (the planner intercepts the flag
|
|
95
|
+
* directly); it exists purely so root help can list
|
|
96
|
+
* `--completions <bash|zsh|…>` in its `Flags:` section.
|
|
97
|
+
*
|
|
98
|
+
* @internal
|
|
99
|
+
*/
|
|
100
|
+
function completionsFlagSchema(shells) {
|
|
101
|
+
return {
|
|
102
|
+
kind: "enum",
|
|
103
|
+
presence: "optional",
|
|
104
|
+
defaultValue: void 0,
|
|
105
|
+
aliases: [],
|
|
106
|
+
envVar: void 0,
|
|
107
|
+
configPath: void 0,
|
|
108
|
+
description: "Print a shell completion script and exit",
|
|
109
|
+
enumValues: shells,
|
|
110
|
+
elementSchema: void 0,
|
|
111
|
+
separator: void 0,
|
|
112
|
+
unique: false,
|
|
113
|
+
numberConstraints: void 0,
|
|
114
|
+
stringConstraints: void 0,
|
|
115
|
+
pathChecks: void 0,
|
|
116
|
+
valueHint: void 0,
|
|
117
|
+
prompt: void 0,
|
|
118
|
+
parseFn: void 0,
|
|
119
|
+
deprecated: void 0,
|
|
120
|
+
propagate: false,
|
|
121
|
+
negation: void 0,
|
|
122
|
+
duplicates: "last"
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Render the header line (`name vX.Y.Z`).
|
|
127
|
+
*
|
|
128
|
+
* When `hyperlinks` is enabled and the schema carries link URLs (via
|
|
129
|
+
* `CLIBuilder.links()`, possibly derived from package.json metadata), the
|
|
130
|
+
* name and version are wrapped in OSC 8 hyperlinks. The header is the only
|
|
131
|
+
* place links are emitted — usage lines, hints, and the commands table stay
|
|
132
|
+
* plain.
|
|
133
|
+
*
|
|
134
|
+
* @param schema - The CLI schema.
|
|
135
|
+
* @param hyperlinks - Whether OSC 8 hyperlinks may be emitted.
|
|
136
|
+
* @param theme - Theme applied to the name and version (inside any hyperlink).
|
|
137
|
+
* @returns The header line.
|
|
138
|
+
* @internal
|
|
139
|
+
*/
|
|
140
|
+
function formatHeader(schema, hyperlinks, theme) {
|
|
141
|
+
const links = hyperlinks ? schema.helpLinks : void 0;
|
|
142
|
+
const styledName = theme.headerName(schema.name);
|
|
143
|
+
const name = links?.name !== void 0 ? osc8(links.name, styledName) : styledName;
|
|
144
|
+
if (schema.version === void 0) return name;
|
|
145
|
+
const version = theme.headerVersion(`v${schema.version}`);
|
|
146
|
+
return `${name} ${links?.version !== void 0 ? osc8(links.version, version) : version}`;
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Format the "Commands:" section with aligned names and descriptions.
|
|
150
|
+
*
|
|
151
|
+
* @param visibleCommands - Non-hidden top-level commands.
|
|
152
|
+
* @param defaultName - Name of the default command (appends " (default)" tag).
|
|
153
|
+
* @param width - Terminal width for description wrapping.
|
|
154
|
+
* @param theme - Theme applied to the title, command names, and default tag.
|
|
155
|
+
* @returns Formatted commands block.
|
|
156
|
+
* @internal
|
|
157
|
+
*/
|
|
158
|
+
function formatRootCommandsSection(visibleCommands, defaultName, width, theme) {
|
|
159
|
+
const lines = [theme.sectionTitle("Commands:")];
|
|
160
|
+
const GAP = 2;
|
|
161
|
+
const DEFAULT_TAG = " (default)";
|
|
162
|
+
let maxNameLen = 0;
|
|
163
|
+
for (const cmd of visibleCommands) {
|
|
164
|
+
const tagLen = cmd.name === defaultName ? 10 : 0;
|
|
165
|
+
const nameLen = cmd.name.length + tagLen;
|
|
166
|
+
if (nameLen > maxNameLen) maxNameLen = nameLen;
|
|
167
|
+
}
|
|
168
|
+
const descCol = 2 + maxNameLen + GAP;
|
|
169
|
+
for (const cmd of visibleCommands) {
|
|
170
|
+
const padded = padEnd(` ${cmd.name === defaultName ? `${theme.command(cmd.name)}${theme.annotation(DEFAULT_TAG)}` : theme.command(cmd.name)}`, descCol);
|
|
171
|
+
const desc = cmd.description ?? "";
|
|
172
|
+
if (desc.length === 0) lines.push(padded.trimEnd());
|
|
173
|
+
else lines.push(`${padded}${wrapText(desc, width, descCol)}`);
|
|
174
|
+
}
|
|
175
|
+
return lines.join("\n");
|
|
176
|
+
}
|
|
177
|
+
/**
|
|
178
|
+
* Build the `Global options:` section advertising the active built-in flags.
|
|
179
|
+
*
|
|
180
|
+
* `--help, -h` and `--json` are always available; `--version, -V` is shown only
|
|
181
|
+
* when the program declares a version; `--config <path>` only when `.config()`
|
|
182
|
+
* enabled config discovery. The eager `--completions` flag is intentionally
|
|
183
|
+
* omitted — it is advertised via the inline surface when active.
|
|
184
|
+
*
|
|
185
|
+
* @param schema - The CLI schema (read for `version` and `configSettings`).
|
|
186
|
+
* @param width - Terminal width for description wrapping.
|
|
187
|
+
* @param theme - Theme applied to the title and flag forms.
|
|
188
|
+
* @returns Formatted `Global options:` block (always non-empty).
|
|
189
|
+
* @internal
|
|
190
|
+
*/
|
|
191
|
+
function formatGlobalOptionsSection(schema, width, theme) {
|
|
192
|
+
const entries = [{
|
|
193
|
+
left: theme.flag("-h, --help"),
|
|
194
|
+
description: "Show this help message and exit"
|
|
195
|
+
}];
|
|
196
|
+
if (schema.version !== void 0) entries.push({
|
|
197
|
+
left: theme.flag("-V, --version"),
|
|
198
|
+
description: "Print the version number and exit"
|
|
199
|
+
});
|
|
200
|
+
entries.push({
|
|
201
|
+
left: theme.flag("--json"),
|
|
202
|
+
description: "Emit machine-readable JSON output"
|
|
203
|
+
});
|
|
204
|
+
if (schema.configSettings !== void 0) entries.push({
|
|
205
|
+
left: `${theme.flag("--config")} ${theme.placeholder("<path>")}`,
|
|
206
|
+
description: "Load configuration from the given file"
|
|
207
|
+
});
|
|
208
|
+
return formatFlagEntriesBlock(theme.sectionTitle("Global options:"), entries, width);
|
|
209
|
+
}
|
|
210
|
+
/**
|
|
211
|
+
* Merge root and default-command usage lines into a single block.
|
|
212
|
+
*
|
|
213
|
+
* @param rootUsage - The root usage line (e.g. `Usage: mycli [command] [options]`).
|
|
214
|
+
* @param commandUsage - The default command's usage line.
|
|
215
|
+
* @param usageTitle - The themed `Usage:` title — byte-identical in both lines
|
|
216
|
+
* within one render, so the styled prefix strips cleanly.
|
|
217
|
+
* @returns Combined usage block with aligned continuation.
|
|
218
|
+
* @internal
|
|
219
|
+
*/
|
|
220
|
+
function mergeUsageSections(rootUsage, commandUsage, usageTitle) {
|
|
221
|
+
const usagePrefix = `${usageTitle} `;
|
|
222
|
+
const commandSuffix = commandUsage.startsWith(usagePrefix) ? commandUsage.slice(usagePrefix.length) : commandUsage;
|
|
223
|
+
return `${rootUsage}\n${" ".repeat(7)}${commandSuffix}`;
|
|
224
|
+
}
|
|
225
|
+
//#endregion
|
|
226
|
+
export { formatRootHelp };
|
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
import { CommandSchema } from "../schema/command.mjs";
|
|
2
|
-
|
|
3
2
|
//#region src/core/cli/root-surface.d.ts
|
|
4
3
|
/**
|
|
5
4
|
* Structural CLI shape needed for root-surface analysis.
|
|
@@ -16,24 +15,51 @@ interface RootSurfaceSchemaLike {
|
|
|
16
15
|
readonly defaultCommand: {
|
|
17
16
|
readonly schema: CommandSchema;
|
|
18
17
|
} | undefined;
|
|
18
|
+
/**
|
|
19
|
+
* Whether the default command is also exposed as a named route
|
|
20
|
+
* (`.default(cmd, { route: true })`). Optional so hand-built schema-like
|
|
21
|
+
* objects default to the surface-only behavior.
|
|
22
|
+
*/
|
|
23
|
+
readonly defaultCommandRouted?: boolean | undefined;
|
|
19
24
|
}
|
|
20
25
|
/**
|
|
21
26
|
* Normalized root shape shared by help and completion logic.
|
|
22
27
|
*
|
|
28
|
+
* Since v0.3 the default command is a distinct root *surface* rather than a
|
|
29
|
+
* named subcommand: `.default()` no longer registers it under
|
|
30
|
+
* {@link RootSurfaceSchemaLike.commands}. To stay robust against callers that
|
|
31
|
+
* still place the default in the command list (e.g. hand-built test schemas),
|
|
32
|
+
* {@link resolveRootSurface} always derives {@link RootSurface.visibleSubcommands}
|
|
33
|
+
* by excluding the default command from the visible command list.
|
|
34
|
+
*
|
|
23
35
|
* @internal
|
|
24
36
|
*/
|
|
25
37
|
interface RootSurface {
|
|
38
|
+
/** All visible top-level commands as declared in `schema.commands`. */
|
|
26
39
|
readonly visibleCommands: readonly CommandSchema[];
|
|
40
|
+
/** Visible real subcommands — `visibleCommands` minus the default command. */
|
|
41
|
+
readonly visibleSubcommands: readonly CommandSchema[];
|
|
42
|
+
/** The visible default command, or `undefined` when none exists or it is hidden. */
|
|
27
43
|
readonly visibleDefaultCommand: CommandSchema | undefined;
|
|
28
|
-
|
|
29
|
-
readonly
|
|
44
|
+
/** Whether a visible default command exists. */
|
|
45
|
+
readonly hasVisibleDefault: boolean;
|
|
46
|
+
/** Whether any visible real subcommands exist (the default does not count). */
|
|
47
|
+
readonly hasVisibleSubcommands: boolean;
|
|
48
|
+
/**
|
|
49
|
+
* Whether the visible default is also a named route (`.default(cmd, { route:
|
|
50
|
+
* true })`), meaning it should be listed in `Commands:` beside its siblings
|
|
51
|
+
* in addition to being rendered as the root surface.
|
|
52
|
+
*/
|
|
53
|
+
readonly defaultRouted: boolean;
|
|
30
54
|
}
|
|
31
55
|
/**
|
|
32
56
|
* Resolve the visible shape of the CLI root.
|
|
33
57
|
*
|
|
34
58
|
* Hidden commands are excluded from the visible command list. Hidden
|
|
35
59
|
* default commands remain executable, but are not surfaced through
|
|
36
|
-
* help or completions.
|
|
60
|
+
* help or completions. The default command is reported separately from the
|
|
61
|
+
* real subcommands so help and completion can render it as the root surface
|
|
62
|
+
* instead of echoing it as a pseudo-subcommand.
|
|
37
63
|
*
|
|
38
64
|
* @internal
|
|
39
65
|
*/
|
|
@@ -1 +1,28 @@
|
|
|
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
|
+
defaultRouted: visibleDefaultCommand !== void 0 && schema.defaultCommandRouted === true
|
|
25
|
+
};
|
|
26
|
+
}
|
|
27
|
+
//#endregion
|
|
28
|
+
export { resolveRootSurface };
|
|
@@ -1,13 +1,18 @@
|
|
|
1
1
|
import { Verbosity } from "../output/contracts.mjs";
|
|
2
|
+
import "../output/index.mjs";
|
|
2
3
|
import { PromptEngine } from "../prompt/index.mjs";
|
|
3
4
|
import { CLIPlugin } from "./plugin.mjs";
|
|
4
5
|
import { CLIError } from "../errors/index.mjs";
|
|
6
|
+
import { HelpThemeFactory } from "../help/theme.mjs";
|
|
7
|
+
import "../help/index.mjs";
|
|
5
8
|
import { CommandSchema, ErasedCommand } from "../schema/command.mjs";
|
|
9
|
+
import { ParseOptions } from "../parse/index.mjs";
|
|
6
10
|
import { RuntimeAdapter } from "../../runtime/adapter.mjs";
|
|
7
11
|
import { PackageJsonData } from "../config/package-json.mjs";
|
|
8
12
|
import { HelpLinks } from "./help-links.mjs";
|
|
13
|
+
import { CompletionOptions } from "../completion/shells/shared.mjs";
|
|
14
|
+
import { Shell } from "../completion/index.mjs";
|
|
9
15
|
import { FormatLoader } from "../config/index.mjs";
|
|
10
|
-
|
|
11
16
|
//#region src/core/cli/runtime-preflight.d.ts
|
|
12
17
|
/** Config discovery settings extracted from CLISchema for preflight use. @internal */
|
|
13
18
|
interface RuntimeConfigSettings {
|
|
@@ -56,14 +61,32 @@ interface RuntimePreflightSchemaLike {
|
|
|
56
61
|
readonly commands: readonly ErasedCommand[];
|
|
57
62
|
/** Fallback command when no subcommand token matches. */
|
|
58
63
|
readonly defaultCommand: ErasedCommand | undefined;
|
|
64
|
+
/** Whether the default command is also exposed as a named top-level route. */
|
|
65
|
+
readonly defaultCommandRouted: boolean;
|
|
59
66
|
/** Config file discovery settings; `undefined` disables config loading. */
|
|
60
67
|
readonly configSettings: RuntimeConfigSettings | undefined;
|
|
61
68
|
/** Package.json discovery settings; `undefined` disables package.json inference. */
|
|
62
69
|
readonly packageJsonSettings: RuntimeManifestSettings | undefined;
|
|
63
70
|
/** Root-help header link targets; `undefined` fields may be derived from package.json. */
|
|
64
71
|
readonly helpLinks: HelpLinks | undefined;
|
|
65
|
-
/** Whether `.completions()` registered the built-in completions command. */
|
|
72
|
+
/** Whether `.completions()` registered the built-in completions command/flag. */
|
|
66
73
|
readonly hasBuiltInCompletions: boolean;
|
|
74
|
+
/** Eager `--completions <shell>` flag config; `undefined` disables interception. */
|
|
75
|
+
readonly completionsFlag: {
|
|
76
|
+
readonly shells: readonly Shell[];
|
|
77
|
+
readonly options: CompletionOptions | undefined;
|
|
78
|
+
} | undefined;
|
|
79
|
+
/** Consumer-configured root-help defaults. */
|
|
80
|
+
readonly helpConfig: {
|
|
81
|
+
readonly inlineDefault?: boolean;
|
|
82
|
+
readonly showDefaultInCommands?: boolean;
|
|
83
|
+
readonly footer?: boolean;
|
|
84
|
+
readonly width?: number;
|
|
85
|
+
readonly hyperlinks?: boolean;
|
|
86
|
+
readonly theme?: HelpThemeFactory;
|
|
87
|
+
} | undefined;
|
|
88
|
+
/** Flag-parsing behavior settings (e.g. case parity). */
|
|
89
|
+
readonly flagSettings: ParseOptions | undefined;
|
|
67
90
|
/** Plugins forwarded into the execution pipeline. */
|
|
68
91
|
readonly plugins: readonly CLIPlugin[];
|
|
69
92
|
}
|
|
@@ -89,6 +112,8 @@ interface RuntimePreflightOptions {
|
|
|
89
112
|
readonly jsonMode?: boolean;
|
|
90
113
|
/** TTY detection override; bypasses adapter TTY check. */
|
|
91
114
|
readonly isTTY?: boolean;
|
|
115
|
+
/** Filesystem probe override for `flag.path()` checks; bypasses the adapter probe. */
|
|
116
|
+
readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
|
|
92
117
|
}
|
|
93
118
|
/**
|
|
94
119
|
* Fully resolved runtime inputs ready for the execution pipeline.
|
|
@@ -112,6 +137,8 @@ interface RuntimeExecutionInputs {
|
|
|
112
137
|
readonly prompter?: PromptEngine;
|
|
113
138
|
/** Loaded config data for the config resolution step. */
|
|
114
139
|
readonly config?: Readonly<Record<string, unknown>>;
|
|
140
|
+
/** Filesystem probe (from the adapter) for `flag.path()` checks. */
|
|
141
|
+
readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
|
|
115
142
|
}
|
|
116
143
|
/** Preflight succeeded — all runtime inputs are resolved and ready for execution. @internal */
|
|
117
144
|
interface ReadyRuntimePreflight {
|
|
@@ -152,7 +179,7 @@ declare function extractConfigFlag(argv: readonly string[]): {
|
|
|
152
179
|
readonly filteredArgv: readonly string[];
|
|
153
180
|
};
|
|
154
181
|
/** Check whether a single command's args declare stdin-mode and argv leaves them unresolved. @internal */
|
|
155
|
-
declare function commandInvocationNeedsStdin(schema: CommandSchema, argv: readonly string[]): boolean;
|
|
182
|
+
declare function commandInvocationNeedsStdin(schema: CommandSchema, argv: readonly string[], flagSettings?: ParseOptions): boolean;
|
|
156
183
|
/** Plan the invocation and check whether the matched command needs stdin data. @internal */
|
|
157
184
|
declare function invocationNeedsStdin(schema: RuntimePreflightSchemaLike, argv: readonly string[]): boolean;
|
|
158
185
|
/**
|
|
@@ -1 +1,169 @@
|
|
|
1
|
-
import
|
|
1
|
+
import { CLIError, ParseError } from "../errors/index.mjs";
|
|
2
|
+
import { parse } from "../parse/index.mjs";
|
|
3
|
+
import { createTerminalPrompter } from "../prompt/index.mjs";
|
|
4
|
+
import { discoverManifest, inferCliName } from "../config/package-json.mjs";
|
|
5
|
+
import { deriveHelpLinks } from "./help-links.mjs";
|
|
6
|
+
import { planInvocation } from "./planner.mjs";
|
|
7
|
+
import { discoverConfig } from "../config/index.mjs";
|
|
8
|
+
//#region src/core/cli/runtime-preflight.ts
|
|
9
|
+
const PRECHECK_OUTPUT = {
|
|
10
|
+
jsonMode: false,
|
|
11
|
+
isTTY: false,
|
|
12
|
+
verbosity: "normal"
|
|
13
|
+
};
|
|
14
|
+
/** Extract and strip valid runtime `--config` forms from argv, returning path + filtered tokens. @internal */
|
|
15
|
+
function extractConfigFlag(argv) {
|
|
16
|
+
const filteredArgv = [];
|
|
17
|
+
let configPath;
|
|
18
|
+
for (let i = 0; i < argv.length; i += 1) {
|
|
19
|
+
const arg = argv[i];
|
|
20
|
+
if (arg === void 0) continue;
|
|
21
|
+
if (arg === "--") {
|
|
22
|
+
filteredArgv.push(...argv.slice(i));
|
|
23
|
+
break;
|
|
24
|
+
}
|
|
25
|
+
if (configPath === void 0 && arg.startsWith("--config=")) {
|
|
26
|
+
const value = arg.slice(9);
|
|
27
|
+
if (value.length > 0) {
|
|
28
|
+
configPath = value;
|
|
29
|
+
continue;
|
|
30
|
+
}
|
|
31
|
+
filteredArgv.push(arg);
|
|
32
|
+
continue;
|
|
33
|
+
}
|
|
34
|
+
if (configPath === void 0 && arg === "--config") {
|
|
35
|
+
const nextArg = argv[i + 1];
|
|
36
|
+
if (nextArg !== void 0 && !nextArg.startsWith("-") && nextArg !== "--") {
|
|
37
|
+
configPath = nextArg;
|
|
38
|
+
i += 1;
|
|
39
|
+
continue;
|
|
40
|
+
}
|
|
41
|
+
filteredArgv.push(arg);
|
|
42
|
+
continue;
|
|
43
|
+
}
|
|
44
|
+
filteredArgv.push(arg);
|
|
45
|
+
}
|
|
46
|
+
return {
|
|
47
|
+
configPath,
|
|
48
|
+
filteredArgv
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
/** Check whether a single command's args declare stdin-mode and argv leaves them unresolved. @internal */
|
|
52
|
+
function commandInvocationNeedsStdin(schema, argv, flagSettings) {
|
|
53
|
+
if (argv.includes("--help") || argv.includes("-h")) return false;
|
|
54
|
+
try {
|
|
55
|
+
const parsed = parse(schema, argv, flagSettings);
|
|
56
|
+
return schema.args.some(({ name, schema: argSchema }) => {
|
|
57
|
+
const parsedValue = parsed.args[name];
|
|
58
|
+
return argSchema.stdinMode && (parsedValue === void 0 || parsedValue === "-");
|
|
59
|
+
});
|
|
60
|
+
} catch (error) {
|
|
61
|
+
if (error instanceof ParseError) return false;
|
|
62
|
+
throw error;
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
/** Plan the invocation and check whether the matched command needs stdin data. @internal */
|
|
66
|
+
function invocationNeedsStdin(schema, argv) {
|
|
67
|
+
const plan = planInvocation({
|
|
68
|
+
schema,
|
|
69
|
+
argv,
|
|
70
|
+
help: { binName: schema.name },
|
|
71
|
+
output: PRECHECK_OUTPUT
|
|
72
|
+
});
|
|
73
|
+
switch (plan.kind) {
|
|
74
|
+
case "match": return commandInvocationNeedsStdin(plan.plan.mergedSchema, plan.plan.argv, schema.flagSettings);
|
|
75
|
+
case "dispatch-error":
|
|
76
|
+
case "needs-subcommand":
|
|
77
|
+
case "root-help":
|
|
78
|
+
case "root-version":
|
|
79
|
+
case "root-completions": return false;
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
function isCompletionsInvocation(schema, argv) {
|
|
83
|
+
if (!schema.hasBuiltInCompletions) return false;
|
|
84
|
+
const plan = planInvocation({
|
|
85
|
+
schema,
|
|
86
|
+
argv,
|
|
87
|
+
help: { binName: schema.name },
|
|
88
|
+
output: PRECHECK_OUTPUT
|
|
89
|
+
});
|
|
90
|
+
return plan.kind === "match" && plan.plan.command.schema.name === "completions";
|
|
91
|
+
}
|
|
92
|
+
async function applyPackageJsonDiscovery(schema, adapter, inheritedName, isCompletions) {
|
|
93
|
+
const packageJsonSettings = schema.packageJsonSettings;
|
|
94
|
+
const packageSchema = packageJsonSettings !== void 0 && !isCompletions ? await (async () => {
|
|
95
|
+
const pkg = packageJsonSettings.data ?? await discoverManifest(adapter, {
|
|
96
|
+
...packageJsonSettings.from !== void 0 ? { startDir: packageJsonSettings.from } : {},
|
|
97
|
+
files: packageJsonSettings.files
|
|
98
|
+
});
|
|
99
|
+
if (pkg === null) return schema;
|
|
100
|
+
const inferredName = packageJsonSettings.inferName ? inferCliName(pkg, { stripScope: packageJsonSettings.stripScope }) : void 0;
|
|
101
|
+
return {
|
|
102
|
+
...schema,
|
|
103
|
+
...schema.version === void 0 && pkg.version !== void 0 ? { version: pkg.version } : {},
|
|
104
|
+
...schema.description === void 0 && pkg.description !== void 0 ? { description: pkg.description } : {},
|
|
105
|
+
...inferredName !== void 0 ? { name: inferredName } : {},
|
|
106
|
+
helpLinks: deriveHelpLinks(schema.helpLinks, pkg, schema.version ?? pkg.version)
|
|
107
|
+
};
|
|
108
|
+
})() : schema;
|
|
109
|
+
return inheritedName !== void 0 ? {
|
|
110
|
+
...packageSchema,
|
|
111
|
+
name: inheritedName
|
|
112
|
+
} : packageSchema;
|
|
113
|
+
}
|
|
114
|
+
async function loadRuntimeConfig(schema, adapter, configPath, isCompletions, existingConfig) {
|
|
115
|
+
if (schema.configSettings === void 0 || isCompletions || existingConfig !== void 0) return existingConfig;
|
|
116
|
+
try {
|
|
117
|
+
const result = await discoverConfig(schema.configSettings.appName, adapter, {
|
|
118
|
+
...configPath !== void 0 ? { configPath } : {},
|
|
119
|
+
...schema.configSettings.loaders !== void 0 ? { loaders: schema.configSettings.loaders } : {}
|
|
120
|
+
});
|
|
121
|
+
return result.found ? result.data : void 0;
|
|
122
|
+
} catch (error) {
|
|
123
|
+
if (error instanceof CLIError) return error;
|
|
124
|
+
throw error;
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* Run all adapter-driven sourcing work before command execution.
|
|
129
|
+
*
|
|
130
|
+
* Discovers config files, reads package.json metadata, detects stdin needs,
|
|
131
|
+
* wires up the prompt engine, and resolves output policy overrides into a
|
|
132
|
+
* single {@linkcode RuntimePreflightResult}.
|
|
133
|
+
* @internal
|
|
134
|
+
*/
|
|
135
|
+
async function prepareRuntimePreflight(options) {
|
|
136
|
+
const rawArgv = options.adapter.argv.slice(2);
|
|
137
|
+
const { configPath, filteredArgv } = options.schema.configSettings !== void 0 ? extractConfigFlag(rawArgv) : {
|
|
138
|
+
configPath: void 0,
|
|
139
|
+
filteredArgv: rawArgv
|
|
140
|
+
};
|
|
141
|
+
const jsonMode = filteredArgv.includes("--json") || options.options?.jsonMode === true;
|
|
142
|
+
const isCompletions = isCompletionsInvocation(options.schema, filteredArgv);
|
|
143
|
+
const schema = await applyPackageJsonDiscovery(options.schema, options.adapter, options.inheritedName, isCompletions);
|
|
144
|
+
const loadedConfig = await loadRuntimeConfig(schema, options.adapter, configPath, isCompletions, options.options?.config);
|
|
145
|
+
if (loadedConfig instanceof CLIError) return {
|
|
146
|
+
kind: "config-error",
|
|
147
|
+
error: loadedConfig,
|
|
148
|
+
jsonMode
|
|
149
|
+
};
|
|
150
|
+
const autoPrompter = options.options?.prompter === void 0 && options.adapter.stdinIsTTY ? createTerminalPrompter(options.adapter.stdin, options.adapter.stderr) : void 0;
|
|
151
|
+
const stdinData = options.options?.stdinData === void 0 && invocationNeedsStdin(schema, filteredArgv) ? await options.adapter.readStdin() : options.options?.stdinData;
|
|
152
|
+
return {
|
|
153
|
+
kind: "ready",
|
|
154
|
+
schema,
|
|
155
|
+
filteredArgv,
|
|
156
|
+
inputs: {
|
|
157
|
+
env: options.options?.env ?? options.adapter.env,
|
|
158
|
+
isTTY: options.options?.isTTY ?? options.adapter.isTTY,
|
|
159
|
+
jsonMode,
|
|
160
|
+
verbosity: options.options?.verbosity ?? "normal",
|
|
161
|
+
stat: options.options?.stat ?? options.adapter.stat,
|
|
162
|
+
...stdinData !== void 0 ? { stdinData } : {},
|
|
163
|
+
...options.options?.prompter !== void 0 ? { prompter: options.options.prompter } : autoPrompter !== void 0 ? { prompter: autoPrompter } : {},
|
|
164
|
+
...loadedConfig !== void 0 ? { config: loadedConfig } : {}
|
|
165
|
+
}
|
|
166
|
+
};
|
|
167
|
+
}
|
|
168
|
+
//#endregion
|
|
169
|
+
export { commandInvocationNeedsStdin, extractConfigFlag, invocationNeedsStdin, prepareRuntimePreflight };
|
|
@@ -4,7 +4,6 @@ import { generateFishCompletion } from "./shells/fish.mjs";
|
|
|
4
4
|
import { generatePowerShellCompletion } from "./shells/powershell.mjs";
|
|
5
5
|
import { generateZshCompletion } from "./shells/zsh.mjs";
|
|
6
6
|
import { CLISchema } from "../cli/index.mjs";
|
|
7
|
-
|
|
8
7
|
//#region src/core/completion/index.d.ts
|
|
9
8
|
/**
|
|
10
9
|
* Supported shell targets for completion script generation.
|
|
@@ -22,6 +21,37 @@ type Shell = 'bash' | 'zsh' | 'fish' | 'powershell';
|
|
|
22
21
|
* @see {@link Shell} for the union type matching these entries.
|
|
23
22
|
*/
|
|
24
23
|
declare const SHELLS: Readonly<readonly ['bash', 'zsh', 'fish', 'powershell']>;
|
|
24
|
+
/**
|
|
25
|
+
* Normalize a raw shell token — a bare name (`zsh`), a `$SHELL` path
|
|
26
|
+
* (`/bin/zsh`), or a Windows executable (`…\pwsh.exe`) — to a supported
|
|
27
|
+
* {@link Shell}, or `undefined` when it does not map to one.
|
|
28
|
+
*
|
|
29
|
+
* Mirrors the matching used by the `completions` subcommand so the subcommand
|
|
30
|
+
* and the eager `--completions <shell>` flag accept exactly the same inputs.
|
|
31
|
+
*
|
|
32
|
+
* @param raw - User-supplied shell token or interpreter path.
|
|
33
|
+
* @returns The resolved {@link Shell}, or `undefined` if unrecognized.
|
|
34
|
+
*/
|
|
35
|
+
declare function normalizeShell(raw: string): Shell | undefined;
|
|
36
|
+
/**
|
|
37
|
+
* Auto-detect the current shell from environment variables.
|
|
38
|
+
*
|
|
39
|
+
* Resolution order:
|
|
40
|
+
* 1. `$SHELL` parsed as an interpreter path (`/bin/zsh` → `zsh`). It wins when
|
|
41
|
+
* it names a shell we support — a pwsh session launched from bash inherits
|
|
42
|
+
* `SHELL=/bin/bash`, and the login shell the user opted into should be
|
|
43
|
+
* honored over the fallback.
|
|
44
|
+
* 2. Otherwise, the presence of `$PSModulePath` signals PowerShell. PowerShell
|
|
45
|
+
* never sets `$SHELL` on any platform but always exports `PSModulePath` for
|
|
46
|
+
* module discovery, so it is the reliable pwsh signal.
|
|
47
|
+
*
|
|
48
|
+
* Returns `undefined` when no signal resolves, leaving the caller to ask the
|
|
49
|
+
* user for an explicit shell.
|
|
50
|
+
*
|
|
51
|
+
* @param env - Environment record (e.g. `process.env` or an adapter's env).
|
|
52
|
+
* @returns The detected {@link Shell}, or `undefined`.
|
|
53
|
+
*/
|
|
54
|
+
declare function detectShell(env: Readonly<Record<string, string | undefined>>): Shell | undefined;
|
|
25
55
|
/**
|
|
26
56
|
* Generate a completion script for the given shell.
|
|
27
57
|
*
|
|
@@ -43,4 +73,4 @@ declare const SHELLS: Readonly<readonly ['bash', 'zsh', 'fish', 'powershell']>;
|
|
|
43
73
|
*/
|
|
44
74
|
declare function generateCompletion(schema: CLISchema, shell: Shell, options?: CompletionOptions): string;
|
|
45
75
|
//#endregion
|
|
46
|
-
export { type CompletionOptions, SHELLS, type Shell, generateBashCompletion, generateCompletion, generateFishCompletion, generatePowerShellCompletion, generateZshCompletion };
|
|
76
|
+
export { type CompletionOptions, SHELLS, type Shell, detectShell, generateBashCompletion, generateCompletion, generateFishCompletion, generatePowerShellCompletion, generateZshCompletion, normalizeShell };
|