@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 +1,41 @@
|
|
|
1
|
-
import{packageRepositoryUrl
|
|
1
|
+
import { packageRepositoryUrl } from "../config/package-json.mjs";
|
|
2
|
+
//#region src/core/cli/help-links.ts
|
|
3
|
+
/**
|
|
4
|
+
* Build the release-tag URL for a version on a known forge.
|
|
5
|
+
*
|
|
6
|
+
* GitHub and GitLab have stable release-tag routes; other hosts return
|
|
7
|
+
* `undefined` rather than guessing.
|
|
8
|
+
*
|
|
9
|
+
* @internal
|
|
10
|
+
*/
|
|
11
|
+
function releaseTagUrl(repoUrl, version) {
|
|
12
|
+
let hostname;
|
|
13
|
+
try {
|
|
14
|
+
hostname = new URL(repoUrl).hostname;
|
|
15
|
+
} catch {
|
|
16
|
+
return;
|
|
17
|
+
}
|
|
18
|
+
if (hostname === "github.com") return `${repoUrl}/releases/tag/v${version}`;
|
|
19
|
+
if (hostname === "gitlab.com") return `${repoUrl}/-/releases/v${version}`;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Fill `undefined` link fields from package.json metadata.
|
|
23
|
+
*
|
|
24
|
+
* Explicit URLs always win. The name falls back to the normalized
|
|
25
|
+
* `repository` URL, then `homepage`; the version falls back to the forge
|
|
26
|
+
* release-tag URL when both a repository and a version are known.
|
|
27
|
+
* Idempotent — already-resolved fields pass through unchanged.
|
|
28
|
+
*
|
|
29
|
+
* @internal
|
|
30
|
+
*/
|
|
31
|
+
function deriveHelpLinks(links, pkg, version) {
|
|
32
|
+
if (links === void 0) return void 0;
|
|
33
|
+
if (pkg === void 0 || links.name !== void 0 && links.version !== void 0) return links;
|
|
34
|
+
const repoUrl = packageRepositoryUrl(pkg);
|
|
35
|
+
return {
|
|
36
|
+
name: links.name ?? repoUrl ?? pkg.homepage,
|
|
37
|
+
version: links.version ?? (repoUrl !== void 0 && version !== void 0 ? releaseTagUrl(repoUrl, version) : void 0)
|
|
38
|
+
};
|
|
39
|
+
}
|
|
40
|
+
//#endregion
|
|
41
|
+
export { deriveHelpLinks };
|
|
@@ -1,15 +1,18 @@
|
|
|
1
1
|
import { ArgBuilder, ArgConfig } from "../schema/arg.mjs";
|
|
2
2
|
import { FlagBuilder, FlagConfig } from "../schema/flag.mjs";
|
|
3
3
|
import { BeforeParseParams, CLIPlugin, CLIPluginHooks, PluginCommandContext, ResolvedCommandParams, plugin } from "./plugin.mjs";
|
|
4
|
+
import { HelpThemeFactory } from "../help/theme.mjs";
|
|
5
|
+
import "../help/index.mjs";
|
|
4
6
|
import { RunOptions, RunResult } from "../schema/run.mjs";
|
|
5
7
|
import { CommandBuilder, ErasedCommand } from "../schema/command.mjs";
|
|
8
|
+
import { ParseOptions } from "../parse/index.mjs";
|
|
6
9
|
import { RuntimeAdapter } from "../../runtime/adapter.mjs";
|
|
7
10
|
import { PackageJsonData } from "../config/package-json.mjs";
|
|
8
11
|
import { HelpLinks } from "./help-links.mjs";
|
|
9
12
|
import { CompletionOptions } from "../completion/shells/shared.mjs";
|
|
13
|
+
import { Shell } from "../completion/index.mjs";
|
|
10
14
|
import { FormatLoader } from "../config/index.mjs";
|
|
11
15
|
import { formatRootHelp } from "./root-help.mjs";
|
|
12
|
-
|
|
13
16
|
//#region src/core/cli/index.d.ts
|
|
14
17
|
/**
|
|
15
18
|
* Runtime descriptor for the CLI program.
|
|
@@ -42,6 +45,15 @@ interface CLISchema {
|
|
|
42
45
|
* Set via the {@linkcode CLIBuilder.default | .default()} builder method.
|
|
43
46
|
*/
|
|
44
47
|
readonly defaultCommand: ErasedCommand | undefined;
|
|
48
|
+
/**
|
|
49
|
+
* Whether the default command is also exposed as a named top-level route.
|
|
50
|
+
*
|
|
51
|
+
* Set by `.default(cmd, { route: true })`. When `true`, `mycli <name>`
|
|
52
|
+
* dispatches to the default command (in addition to the bare/flags-only root
|
|
53
|
+
* surface behavior) and the command is listed in the root `Commands:`
|
|
54
|
+
* section. When `false` (the default), the default is the root surface only.
|
|
55
|
+
*/
|
|
56
|
+
readonly defaultCommandRouted: boolean;
|
|
45
57
|
/**
|
|
46
58
|
* Config discovery settings.
|
|
47
59
|
*
|
|
@@ -69,11 +81,90 @@ interface CLISchema {
|
|
|
69
81
|
* CLIBuilder.manifest | .manifest()}) is active.
|
|
70
82
|
*/
|
|
71
83
|
readonly helpLinks: HelpLinks | undefined;
|
|
72
|
-
/** Whether built-in `.completions()` command
|
|
84
|
+
/** Whether built-in `.completions()` registration (command or flag) is active. */
|
|
73
85
|
readonly hasBuiltInCompletions: boolean;
|
|
86
|
+
/**
|
|
87
|
+
* Eager `--completions <shell>` flag configuration.
|
|
88
|
+
*
|
|
89
|
+
* Set when `.completions({ as: 'flag' })` is used instead of the default
|
|
90
|
+
* `completions` subcommand. When defined, the planner intercepts
|
|
91
|
+
* `--completions <shell>` before dispatch, prints the script, and exits;
|
|
92
|
+
* root help advertises the flag in its `Flags:` section.
|
|
93
|
+
*/
|
|
94
|
+
readonly completionsFlag: CompletionsFlagConfig | undefined;
|
|
95
|
+
/**
|
|
96
|
+
* Consumer-configured root-help defaults.
|
|
97
|
+
*
|
|
98
|
+
* Set via the {@linkcode CLIBuilder.help | .help()} builder method and merged
|
|
99
|
+
* under runtime `options.help` (runtime wins) before rendering.
|
|
100
|
+
*/
|
|
101
|
+
readonly helpConfig: HelpConfig | undefined;
|
|
102
|
+
/**
|
|
103
|
+
* Flag-parsing behavior settings ({@link ParseOptions}).
|
|
104
|
+
*
|
|
105
|
+
* Set via the `cli(name, { flags })` / `cli({ flags })` factory forms.
|
|
106
|
+
*/
|
|
107
|
+
readonly flagSettings: ParseOptions | undefined;
|
|
74
108
|
/** Registered CLI plugins. */
|
|
75
109
|
readonly plugins: readonly CLIPlugin[];
|
|
76
110
|
}
|
|
111
|
+
/**
|
|
112
|
+
* Configuration for the eager `--completions <shell>` flag.
|
|
113
|
+
*
|
|
114
|
+
* Stored in {@link CLISchema} when `.completions({ as: 'flag' })` is used.
|
|
115
|
+
*
|
|
116
|
+
* @internal
|
|
117
|
+
*/
|
|
118
|
+
interface CompletionsFlagConfig {
|
|
119
|
+
/** Shell targets the flag accepts (mirrors {@link SHELLS}). */
|
|
120
|
+
readonly shells: readonly Shell[];
|
|
121
|
+
/** Generator options captured at build time (e.g. `functionPrefix`, `rootMode`). */
|
|
122
|
+
readonly options: CompletionOptions | undefined;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Consumer-facing root-help configuration set via {@linkcode CLIBuilder.help}.
|
|
126
|
+
*
|
|
127
|
+
* Every field is optional; unset fields fall back to built-in defaults and may
|
|
128
|
+
* be overridden per call through runtime `options.help`.
|
|
129
|
+
*/
|
|
130
|
+
interface HelpConfig {
|
|
131
|
+
/**
|
|
132
|
+
* Render the default command's arguments and flags inline at the root.
|
|
133
|
+
*
|
|
134
|
+
* @defaultValue `true`
|
|
135
|
+
*/
|
|
136
|
+
readonly inlineDefault?: boolean;
|
|
137
|
+
/**
|
|
138
|
+
* Also list the default command in the root `Commands:` table.
|
|
139
|
+
*
|
|
140
|
+
* By default the default command is the root surface and is omitted from the
|
|
141
|
+
* command list (its args/flags render inline instead).
|
|
142
|
+
*
|
|
143
|
+
* @defaultValue `false`
|
|
144
|
+
*/
|
|
145
|
+
readonly showDefaultInCommands?: boolean;
|
|
146
|
+
/**
|
|
147
|
+
* Show the `Run '<bin> <command> --help' for more information.` hint.
|
|
148
|
+
*
|
|
149
|
+
* Defaults to showing the hint only when visible subcommands exist.
|
|
150
|
+
*/
|
|
151
|
+
readonly footer?: boolean;
|
|
152
|
+
/** Maximum line width (columns). */
|
|
153
|
+
readonly width?: number;
|
|
154
|
+
/** Emit OSC 8 hyperlinks in the header when supported. */
|
|
155
|
+
readonly hyperlinks?: boolean;
|
|
156
|
+
/**
|
|
157
|
+
* Theme overrides for help output, merged over the built-in theme.
|
|
158
|
+
*
|
|
159
|
+
* The factory receives the gated ansispeck palette (same instance as
|
|
160
|
+
* `out.color`), so overrides follow the output channel's color policy.
|
|
161
|
+
* It is never invoked when color is off — themed help cannot leak escapes
|
|
162
|
+
* into piped, `--json`, or `NO_COLOR` output.
|
|
163
|
+
*
|
|
164
|
+
* @defaultValue `undefined` (built-in theme)
|
|
165
|
+
*/
|
|
166
|
+
readonly theme?: HelpThemeFactory;
|
|
167
|
+
}
|
|
77
168
|
/**
|
|
78
169
|
* Config discovery settings for automatic config file loading.
|
|
79
170
|
*
|
|
@@ -178,6 +269,29 @@ interface CLIRunOptions extends Omit<RunOptions, 'meta' | 'mergedSchema'> {
|
|
|
178
269
|
*/
|
|
179
270
|
readonly adapter?: RuntimeAdapter;
|
|
180
271
|
}
|
|
272
|
+
/**
|
|
273
|
+
* Options for {@linkcode CLIBuilder.default | .default()}.
|
|
274
|
+
*/
|
|
275
|
+
interface DefaultCommandOptions {
|
|
276
|
+
/**
|
|
277
|
+
* Also expose the default command under its own name as a routable
|
|
278
|
+
* top-level command.
|
|
279
|
+
*
|
|
280
|
+
* By default a default command is the root *surface* only — `mycli` (bare or
|
|
281
|
+
* flags-only) runs it, but `mycli <its-name>` does not route to it (the token
|
|
282
|
+
* is consumed as the default's first positional). Set `route: true` for CLIs
|
|
283
|
+
* that intentionally expose both forms: `mycli` and `mycli <its-name>` become
|
|
284
|
+
* the same command, and it is listed in the root `Commands:` section beside
|
|
285
|
+
* its siblings.
|
|
286
|
+
*
|
|
287
|
+
* The name wins over positional interpretation: with `route: true`, a
|
|
288
|
+
* positional value equal to the command's own name is consumed as the route,
|
|
289
|
+
* so pass such a value after `--` (`mycli -- <name>`).
|
|
290
|
+
*
|
|
291
|
+
* @defaultValue `false`
|
|
292
|
+
*/
|
|
293
|
+
readonly route?: boolean;
|
|
294
|
+
}
|
|
181
295
|
/**
|
|
182
296
|
* Immutable CLI program builder.
|
|
183
297
|
*
|
|
@@ -266,6 +380,25 @@ declare class CLIBuilder {
|
|
|
266
380
|
readonly name?: string | URL;
|
|
267
381
|
readonly version?: string | URL;
|
|
268
382
|
}): CLIBuilder;
|
|
383
|
+
/**
|
|
384
|
+
* Configure root-help rendering defaults.
|
|
385
|
+
*
|
|
386
|
+
* Stored on the schema and merged **under** any runtime `options.help`
|
|
387
|
+
* (runtime wins). Call multiple times to set fields incrementally.
|
|
388
|
+
*
|
|
389
|
+
* @param config - Help rendering options (see {@link HelpConfig}).
|
|
390
|
+
* @returns The builder (for chaining).
|
|
391
|
+
*
|
|
392
|
+
* @example
|
|
393
|
+
* ```ts
|
|
394
|
+
* // Echo the default command under Commands and never show the footer:
|
|
395
|
+
* cli('mycli')
|
|
396
|
+
* .help({ showDefaultInCommands: true, footer: false })
|
|
397
|
+
* .default(serve)
|
|
398
|
+
* .run();
|
|
399
|
+
* ```
|
|
400
|
+
*/
|
|
401
|
+
help(config: HelpConfig): CLIBuilder;
|
|
269
402
|
/**
|
|
270
403
|
* Enable automatic config file discovery.
|
|
271
404
|
*
|
|
@@ -460,8 +593,18 @@ declare class CLIBuilder {
|
|
|
460
593
|
* dispatch normally, but empty argv or flags-only argv falls through to
|
|
461
594
|
* this command instead of showing root help.
|
|
462
595
|
*
|
|
463
|
-
* The command is
|
|
464
|
-
*
|
|
596
|
+
* The default command is the CLI's root *surface*: its flags and arguments
|
|
597
|
+
* are rendered inline in root help. By default it is **not** a named
|
|
598
|
+
* subcommand — it cannot be invoked by its own name (`mycli mycmd` does not
|
|
599
|
+
* route to it) and it is omitted from the root `Commands:` list (re-enable
|
|
600
|
+
* listing with `.help({ showDefaultInCommands: true })`). Only one default is
|
|
601
|
+
* allowed.
|
|
602
|
+
*
|
|
603
|
+
* Pass `{ route: true }` to *also* expose the command under its own name as a
|
|
604
|
+
* routable top-level command: `mycli` and `mycli <name>` then run the same
|
|
605
|
+
* command object, and it is listed in `Commands:` beside its siblings. This
|
|
606
|
+
* avoids duplicating the command just to keep both forms equivalent during a
|
|
607
|
+
* v3 migration.
|
|
465
608
|
*
|
|
466
609
|
* @example
|
|
467
610
|
* ```ts
|
|
@@ -478,12 +621,21 @@ declare class CLIBuilder {
|
|
|
478
621
|
* .default(deploy)
|
|
479
622
|
* .command(status)
|
|
480
623
|
* .run();
|
|
624
|
+
*
|
|
625
|
+
* // Default that is also a named route — `mytool` and `mytool status` are
|
|
626
|
+
* // the same surface, and `status` is listed beside `logs`:
|
|
627
|
+
* cli('mytool')
|
|
628
|
+
* .default(status, { route: true })
|
|
629
|
+
* .command(logs)
|
|
630
|
+
* .run();
|
|
481
631
|
* ```
|
|
482
632
|
*
|
|
483
633
|
* @param cmd - {@link CommandBuilder} to register as the default.
|
|
634
|
+
* @param options - Default-command options. `{ route: true }` also exposes
|
|
635
|
+
* the command under its own name (see {@link DefaultCommandOptions}).
|
|
484
636
|
* @returns The builder (for chaining).
|
|
485
637
|
*/
|
|
486
|
-
default<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown>>(cmd: CommandBuilder<F, A, C
|
|
638
|
+
default<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown>>(cmd: CommandBuilder<F, A, C>, options?: DefaultCommandOptions): CLIBuilder;
|
|
487
639
|
/**
|
|
488
640
|
* Register a CLI plugin.
|
|
489
641
|
*
|
|
@@ -496,28 +648,36 @@ declare class CLIBuilder {
|
|
|
496
648
|
*/
|
|
497
649
|
plugin(definition: CLIPlugin): CLIBuilder;
|
|
498
650
|
/**
|
|
499
|
-
* Register
|
|
500
|
-
* completion scripts.
|
|
651
|
+
* Register built-in shell completion.
|
|
501
652
|
*
|
|
502
|
-
*
|
|
503
|
-
*
|
|
504
|
-
*
|
|
505
|
-
*
|
|
653
|
+
* By default (`{ as: 'command' }`) this registers a `completions` subcommand
|
|
654
|
+
* that accepts a `shell` argument and writes the script to stdout. With
|
|
655
|
+
* `{ as: 'flag' }` it instead exposes an eager `--completions <shell>` flag on
|
|
656
|
+
* the CLI root — no subcommand is registered, so a default command stays the
|
|
657
|
+
* lone root surface. The flag may be given without a value to auto-detect the
|
|
658
|
+
* shell from `$SHELL` / `$PSModulePath`.
|
|
506
659
|
*
|
|
507
|
-
*
|
|
508
|
-
* script includes the full command set
|
|
509
|
-
*
|
|
510
|
-
* will not appear in
|
|
511
|
-
*
|
|
660
|
+
* In subcommand mode, call this **after** registering all other commands so
|
|
661
|
+
* the completion script includes the full command set: that path snapshots the
|
|
662
|
+
* schema (and completion options) at call time, so commands registered
|
|
663
|
+
* afterwards will not appear in that subcommand's generated script. In flag
|
|
664
|
+
* mode, generation runs at execution time from the final builder schema, so
|
|
665
|
+
* registration order does not matter.
|
|
512
666
|
*
|
|
513
667
|
* @example
|
|
514
668
|
* ```ts
|
|
669
|
+
* // Subcommand form (default):
|
|
515
670
|
* cli('mycli')
|
|
516
671
|
* .version('1.0.0')
|
|
517
672
|
* .command(deploy)
|
|
518
|
-
* .command(login)
|
|
519
673
|
* .completions({ rootMode: 'surface' })
|
|
520
674
|
* .run();
|
|
675
|
+
*
|
|
676
|
+
* // Eager-flag form, ideal for single-command CLIs:
|
|
677
|
+
* cli('mycli')
|
|
678
|
+
* .completions({ as: 'flag' })
|
|
679
|
+
* .default(serve)
|
|
680
|
+
* .run();
|
|
521
681
|
* ```
|
|
522
682
|
*/
|
|
523
683
|
completions(options?: CompletionOptions): CLIBuilder;
|
|
@@ -613,6 +773,12 @@ interface CLIOptions {
|
|
|
613
773
|
* @defaultValue `false`
|
|
614
774
|
*/
|
|
615
775
|
readonly inherit?: boolean;
|
|
776
|
+
/**
|
|
777
|
+
* Flag-parsing behavior settings (e.g. `{ caseParity: false }` to accept
|
|
778
|
+
* only declared flag spellings). Shares the {@link ParseOptions} contract
|
|
779
|
+
* used by `parse()` and `RunOptions.flags`.
|
|
780
|
+
*/
|
|
781
|
+
readonly flags?: ParseOptions;
|
|
616
782
|
}
|
|
617
783
|
/**
|
|
618
784
|
* Create a new CLI program builder.
|
|
@@ -633,8 +799,8 @@ interface CLIOptions {
|
|
|
633
799
|
* .run();
|
|
634
800
|
* ```
|
|
635
801
|
*/
|
|
636
|
-
declare function cli(name: string): CLIBuilder;
|
|
802
|
+
declare function cli(name: string, options?: Omit<CLIOptions, 'name'>): CLIBuilder;
|
|
637
803
|
/** Create a new CLI program builder from an options object. */
|
|
638
804
|
declare function cli(options: CLIOptions): CLIBuilder;
|
|
639
805
|
//#endregion
|
|
640
|
-
export { type BeforeParseParams, CLIBuilder, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type ConfigSettings, type HelpLinks, type InferNameOption, type ManifestPresetSettings, type ManifestSettings, type PackageJsonSettings, type PluginCommandContext, type ResolvedCommandParams, type ResolvedManifestSettings, cli, formatRootHelp, plugin };
|
|
806
|
+
export { type BeforeParseParams, CLIBuilder, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type CompletionsFlagConfig, type ConfigSettings, type DefaultCommandOptions, type HelpConfig, type HelpLinks, type InferNameOption, type ManifestPresetSettings, type ManifestSettings, type PackageJsonSettings, type PluginCommandContext, type ResolvedCommandParams, type ResolvedManifestSettings, cli, formatRootHelp, plugin };
|