@kjanat/dreamcli 2.5.0 → 3.0.0-rc.1
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 +128 -1
- package/README.md +9 -2
- package/dist/core/cli/index.d.mts +109 -16
- package/dist/core/cli/index.mjs +1 -1
- package/dist/core/cli/planner.d.mts +27 -5
- package/dist/core/cli/planner.mjs +1 -1
- package/dist/core/cli/root-help.d.mts +16 -2
- package/dist/core/cli/root-help.mjs +3 -5
- package/dist/core/cli/root-surface.d.mts +18 -3
- package/dist/core/cli/root-surface.mjs +1 -1
- package/dist/core/cli/runtime-preflight.d.mts +16 -1
- package/dist/core/cli/runtime-preflight.mjs +1 -1
- package/dist/core/completion/index.d.mts +32 -1
- package/dist/core/completion/index.mjs +1 -1
- package/dist/core/completion/shells/shared.d.mts +10 -0
- package/dist/core/completion/shells/shared.mjs +1 -1
- package/dist/core/help/index.d.mts +45 -1
- package/dist/core/help/index.mjs +6 -6
- package/dist/core/json-schema/index.mjs +1 -1
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
- package/dist/core/parse/index.d.mts +15 -1
- package/dist/core/parse/index.mjs +1 -1
- package/dist/core/prompt/index.d.mts +11 -3
- package/dist/core/prompt/index.mjs +3 -3
- package/dist/core/resolve/coerce.mjs +1 -1
- package/dist/core/resolve/flags.mjs +1 -1
- package/dist/core/resolve/property.d.mts +2 -0
- package/dist/core/resolve/property.mjs +1 -1
- package/dist/core/schema/arg.d.mts +90 -10
- package/dist/core/schema/arg.mjs +1 -1
- package/dist/core/schema/command.d.mts +3 -1
- package/dist/core/schema/flag.d.mts +92 -2
- package/dist/core/schema/flag.mjs +1 -1
- package/dist/core/schema/index.d.mts +2 -1
- package/dist/core/schema/number-constraints.d.mts +96 -0
- package/dist/core/schema/number-constraints.mjs +1 -0
- package/dist/core/schema/prompt.d.mts +15 -0
- package/dist/core/schema/run.d.mts +4 -4
- package/dist/core/testkit/index.d.mts +9 -5
- package/dist/core/testkit/index.mjs +1 -1
- package/dist/index.d.mts +2 -1
- package/dist/index.mjs +1 -1
- package/dist/runtime/auto.mjs +1 -1
- package/dist/runtime/bun.mjs +1 -1
- package/dist/runtime/deno.mjs +2 -2
- package/dist/runtime/node.mjs +2 -2
- package/dist/version.mjs +1 -1
- 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 +15 -24
- package/src/core/cli/dispatch.ts +7 -1
- package/src/core/cli/index.ts +235 -34
- package/src/core/cli/planner.ts +192 -23
- package/src/core/cli/root-help.ts +195 -105
- package/src/core/cli/root-surface.ts +25 -12
- package/src/core/cli/runtime-preflight.ts +20 -2
- package/src/core/completion/index.ts +50 -0
- package/src/core/completion/shells/powershell.ts +2 -2
- package/src/core/completion/shells/shared.ts +30 -3
- package/src/core/execution/index.ts +1 -4
- package/src/core/help/index.ts +57 -10
- package/src/core/json-schema/index.ts +23 -4
- package/src/core/json-schema/meta-descriptions.generated.ts +115 -98
- package/src/core/parse/index.ts +62 -1
- package/src/core/prompt/index.ts +54 -14
- package/src/core/resolve/coerce.ts +73 -5
- package/src/core/resolve/flags.ts +14 -0
- package/src/core/resolve/property.ts +4 -4
- package/src/core/schema/arg.ts +125 -3
- package/src/core/schema/command.ts +3 -1
- package/src/core/schema/flag.ts +120 -4
- package/src/core/schema/index.ts +5 -0
- package/src/core/schema/number-constraints.ts +153 -0
- package/src/core/schema/prompt.ts +15 -0
- package/src/core/schema/run.ts +4 -4
- package/src/core/testkit/index.ts +32 -8
- package/src/index.ts +2 -0
- package/src/runtime/auto.ts +0 -24
- package/src/runtime/bun.ts +0 -7
- package/src/runtime/deno.ts +0 -2
- package/src/runtime/node.ts +0 -11
- package/src/runtime/support.ts +1 -59
- package/src/schema.ts +16 -0
- package/dist/runtime/support.d.mts +0 -42
- package/dist/runtime/support.mjs +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,132 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [3.0.0-rc.1] - 2026-07-02
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- **`.completions({ as: 'flag' })`** — expose shell completion as an eager
|
|
15
|
+
`--completions <shell>` flag on the CLI root instead of a `completions`
|
|
16
|
+
subcommand. The planner intercepts the flag before dispatch, prints the script,
|
|
17
|
+
and exits; root help advertises `--completions <bash|zsh|fish|powershell>` in its
|
|
18
|
+
`Flags:` section. `.completions()` still defaults to `{ as: 'command' }`. Because
|
|
19
|
+
the eager flag is intercepted before dispatch, the `--completions` name is
|
|
20
|
+
reserved in flag mode — declaring a command/default flag of that name throws at
|
|
21
|
+
build time.
|
|
22
|
+
- **Shell auto-detection** — `--completions` with no value (flag form) resolves the
|
|
23
|
+
target shell from the environment: `$SHELL` (parsed as an interpreter path) wins
|
|
24
|
+
when it names a supported shell, otherwise the presence of `$PSModulePath` selects
|
|
25
|
+
PowerShell — the reliable signal for `pwsh`, which never sets `$SHELL`.
|
|
26
|
+
- **`detectShell(env)` / `normalizeShell(raw)`** — exported helpers behind the
|
|
27
|
+
detection above; `normalizeShell` accepts bare names, `$SHELL` paths, and the
|
|
28
|
+
`pwsh`/`powershell` pair.
|
|
29
|
+
- **`.help(config)` builder + extended `HelpOptions`** — configure root-help
|
|
30
|
+
rendering: `inlineDefault`, `showDefaultInCommands`, and `footer` (plus the
|
|
31
|
+
existing `width` / `hyperlinks`). Builder config is merged under runtime
|
|
32
|
+
`options.help` (runtime wins).
|
|
33
|
+
- **Numeric constraints for number flags and args** — `flag.number()` and
|
|
34
|
+
`arg.number()` now accept `{ min?, max?, int?, finite? }` (bounds inclusive),
|
|
35
|
+
and the same constraints compose via chained `.int()` / `.min(n)` / `.max(n)` /
|
|
36
|
+
`.finite(allow?)` methods (a later call overrides an earlier value, including
|
|
37
|
+
one set in the options object). The chained methods are compile-time guarded
|
|
38
|
+
to number-kind builders only. Constraints are enforced identically across the
|
|
39
|
+
parse path and the env/config/prompt resolution path (order: finite → int →
|
|
40
|
+
min → max): parse-time (CLI) violations throw `INVALID_VALUE`, while
|
|
41
|
+
env/config/prompt coercion reports `CONSTRAINT_VIOLATED` (both exit code `2`).
|
|
42
|
+
They are also surfaced in the exported JSON Schema as `minimum` / `maximum` and
|
|
43
|
+
`type: "integer"` when `int` is set. `min` / `max` must be finite — a
|
|
44
|
+
non-finite bound (`Infinity` / `-Infinity` / `NaN`) throws at construction. The
|
|
45
|
+
resolved TypeScript value type stays `number`.
|
|
46
|
+
- **Prompt-level defaults for `confirm` and `input` prompts** — `confirm`
|
|
47
|
+
prompts accept `default?: boolean` (drives the `(Y/n)` vs `(y/N)` hint and the
|
|
48
|
+
empty-line result, so a confirm can default to **No**), and `input` prompts
|
|
49
|
+
accept `default?: string` (shown in the hint as `(default: <value>)` and used
|
|
50
|
+
when the user presses Enter, skipping `validate`). Precedence among defaults is
|
|
51
|
+
prompt-level `default` > flag `.default()`. Unset `confirm` default stays
|
|
52
|
+
backward compatible (`true`).
|
|
53
|
+
|
|
54
|
+
### Changed
|
|
55
|
+
|
|
56
|
+
- **BREAKING — the default command is now the root _surface_, not a named
|
|
57
|
+
subcommand.** `.default(cmd)` registers the command only as the default; it is no
|
|
58
|
+
longer added to `schema.commands`. Consequences:
|
|
59
|
+
- It can no longer be invoked by its own name (`mycli mycmd` does not route to it;
|
|
60
|
+
the token is treated as input to the default command).
|
|
61
|
+
- It is omitted from the root `Commands:` list by default (re-enable with
|
|
62
|
+
`.help({ showDefaultInCommands: true })`).
|
|
63
|
+
- Root `--help` renders the default command's `Arguments:`/`Flags:` inline even
|
|
64
|
+
when sibling commands exist (previously only when it was the sole command), and a
|
|
65
|
+
sole default with no subcommands shows its own usage line directly instead of a
|
|
66
|
+
`[command]` placeholder.
|
|
67
|
+
- **`finite` defaults to `true` (behavior change)** — `flag.number()` /
|
|
68
|
+
`arg.number()` now **reject `Infinity` and `-Infinity`**, which previously
|
|
69
|
+
passed straight through to handlers (`Number("Infinity")` is not `NaN`). Pass
|
|
70
|
+
`{ finite: false }` (or `.finite(false)`) to opt back into accepting non-finite
|
|
71
|
+
values. `NaN` continues to be rejected as before.
|
|
72
|
+
- **BREAKING — the runtime no longer hard-fails the host CLI on its version.**
|
|
73
|
+
Adapter construction previously threw (a bare, uncaught `Error`) when the
|
|
74
|
+
detected Node/Bun/Deno version was below DreamCLI's declared minimum, crashing
|
|
75
|
+
the consumer's CLI — including on `--help`. That check is removed: as a
|
|
76
|
+
dependency the consumer's package manager already enforces the `engines` range
|
|
77
|
+
at install time (and more softly), and when DreamCLI is bundled/inlined the
|
|
78
|
+
consumer — not us — owns their CLI's supported-runtime policy. `SUPPORTED_RUNTIMES`
|
|
79
|
+
and the generated `engines` minimums are unchanged and remain the source of
|
|
80
|
+
truth for docs and packaging.
|
|
81
|
+
|
|
82
|
+
### Fixed
|
|
83
|
+
|
|
84
|
+
- **Empty `input`-prompt answer no longer clobbers a flag's `.default()`** — a
|
|
85
|
+
flag declared with both `.default(...)` and an `input` prompt previously
|
|
86
|
+
resolved to `""` when the user submitted an empty line, because empty input was
|
|
87
|
+
treated as a real answer that short-circuited the default fallback. An empty or
|
|
88
|
+
blank `input` answer with no prompt-level `default` is now treated as "no
|
|
89
|
+
answer", so resolution falls through to the flag's `.default()` (or, for a
|
|
90
|
+
required flag, the standard missing-flag error).
|
|
91
|
+
|
|
92
|
+
### Fixed
|
|
93
|
+
|
|
94
|
+
- **Root `--help` now matches consistently with `--version`** (#29) — previously
|
|
95
|
+
`--help` / `-h` were intercepted at the root only when they were the very first
|
|
96
|
+
token, while `--version` / `-V` matched anywhere before `--`. A help flag
|
|
97
|
+
preceded only by flags (e.g. `mycli --verbose --help`) now shows root help,
|
|
98
|
+
mirroring `mycli --verbose --version`. A help flag that follows a subcommand
|
|
99
|
+
token still scopes to that subcommand (`mycli deploy --help` → `deploy` help);
|
|
100
|
+
`--version` remains a global, position-independent flag by design (there is no
|
|
101
|
+
per-command version). The bare `help` token now triggers root help from the same
|
|
102
|
+
position as `--help`, and the `--` end-of-options separator is respected for both.
|
|
103
|
+
- **Generated `--help` now advertises the active built-in global flags** (#32) — root
|
|
104
|
+
help renders a `Global options:` block listing `--help, -h` and `--json` (always),
|
|
105
|
+
`--version, -V` (when a version is set), and `--config <path>` (when `.config()`
|
|
106
|
+
enabled config discovery). Previously these framework-provided flags were invisible
|
|
107
|
+
in help even though they worked. `--completions` is unchanged (still advertised via
|
|
108
|
+
the inline surface when active).
|
|
109
|
+
- **Root usage no longer prints the default command's name** — the merged/sole-default
|
|
110
|
+
usage line rendered `Usage: <bin> <default-name> …`, teaching an invocation that does
|
|
111
|
+
not route (`.default()` is not a named command, so the token is consumed as the
|
|
112
|
+
default's first positional). It now renders under the bin name only
|
|
113
|
+
(`Usage: <bin> [flags] <args>`).
|
|
114
|
+
- **`inlineDefault: false` no longer hides a sole default command's interface** — when
|
|
115
|
+
the default command is the only surface (no visible subcommands and no eager
|
|
116
|
+
`--completions` flag), root help would collapse to a bare `Usage: <bin> [options]`
|
|
117
|
+
with no discoverable args/flags. The default is now always rendered inline in that
|
|
118
|
+
case, since suppressing it leaves no other path to its interface.
|
|
119
|
+
|
|
120
|
+
### Fixed
|
|
121
|
+
|
|
122
|
+
- **`runCommand()` now honors a CLI-level `--json` passed in `argv`** — the testkit
|
|
123
|
+
gained the same root-flag layer as the real CLI: a `--json` before the `--`
|
|
124
|
+
separator enables JSON mode and is stripped before parsing, instead of failing
|
|
125
|
+
with `Unknown flag --json` (exit 2). A literal `--json` after `--` still reaches
|
|
126
|
+
the command unchanged. The existing `{ jsonMode: true }` option keeps working —
|
|
127
|
+
either source enables JSON mode. Copying a real `mycli --json …` invocation into a
|
|
128
|
+
test now works verbatim.
|
|
129
|
+
- **`createTestPrompter()` now runs an `input` prompt's `validate`** — a queued
|
|
130
|
+
string answer to an `input` prompt is validated exactly as the terminal prompter
|
|
131
|
+
does; an answer that fails validation is rejected as a cancellation rather than
|
|
132
|
+
injected verbatim as the resolved value, so prompt validation is integration-testable
|
|
133
|
+
through `runCommand(cmd, argv, { answers })`. Non-string answers stay verbatim so
|
|
134
|
+
downstream coercion paths remain testable.
|
|
135
|
+
|
|
10
136
|
## [2.5.0] - 2026-06-28
|
|
11
137
|
|
|
12
138
|
### Added
|
|
@@ -878,7 +1004,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
878
1004
|
- MIT License.
|
|
879
1005
|
- Markdownlint configuration.
|
|
880
1006
|
|
|
881
|
-
[Unreleased]: https://github.com/kjanat/dreamcli/compare/
|
|
1007
|
+
[Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.1...HEAD
|
|
1008
|
+
[3.0.0-rc.1]: https://github.com/kjanat/dreamcli/compare/v2.5.0...v3.0.0-rc.1
|
|
882
1009
|
[2.5.0]: https://github.com/kjanat/dreamcli/compare/v2.4.1...v2.5.0
|
|
883
1010
|
[2.4.1]: https://github.com/kjanat/dreamcli/compare/v2.4.0...v2.4.1
|
|
884
1011
|
[2.4.0]: https://github.com/kjanat/dreamcli/compare/v2.3.0...v2.4.0
|
package/README.md
CHANGED
|
@@ -76,7 +76,11 @@ const greet = command('greet')
|
|
|
76
76
|
flag.number().default(1).describe('Repeat count'),
|
|
77
77
|
)
|
|
78
78
|
.action(({ args, flags, out }) => {
|
|
79
|
-
|
|
79
|
+
const repeatCount = Number.isFinite(flags.times)
|
|
80
|
+
? Math.max(0, Math.min(100, Math.floor(flags.times)))
|
|
81
|
+
: 1;
|
|
82
|
+
|
|
83
|
+
for (let i = 0; i < repeatCount; i++) {
|
|
80
84
|
const msg = `Hello, ${args.name}!`;
|
|
81
85
|
out.log(flags.loud ? msg.toUpperCase() : msg);
|
|
82
86
|
}
|
|
@@ -531,7 +535,7 @@ expect(activity.activity).toContainEqual(
|
|
|
531
535
|
|
|
532
536
|
## Package structure
|
|
533
537
|
|
|
534
|
-
|
|
538
|
+
The code lives behind three focused subpath exports:
|
|
535
539
|
|
|
536
540
|
| Import | Purpose |
|
|
537
541
|
| -------------------------- | -------------------------------------------------------------------------------------- |
|
|
@@ -539,6 +543,9 @@ Three subpath exports, each with a focused API surface:
|
|
|
539
543
|
| `@kjanat/dreamcli/testkit` | `runCommand()`, `createCaptureOutput()`, `createTestPrompter()`, `createTestAdapter()` |
|
|
540
544
|
| `@kjanat/dreamcli/runtime` | `createAdapter()`, `RuntimeAdapter`, runtime detection, platform adapters |
|
|
541
545
|
|
|
546
|
+
A fourth export, `@kjanat/dreamcli/schema`, ships the bundled JSON Schema (`dreamcli.schema.json`)
|
|
547
|
+
for editor and config validation.
|
|
548
|
+
|
|
542
549
|
ESM-only. Source included in package (`src/`).
|
|
543
550
|
|
|
544
551
|
## Runtime support
|
|
@@ -7,6 +7,7 @@ import { RuntimeAdapter } from "../../runtime/adapter.mjs";
|
|
|
7
7
|
import { PackageJsonData } from "../config/package-json.mjs";
|
|
8
8
|
import { HelpLinks } from "./help-links.mjs";
|
|
9
9
|
import { CompletionOptions } from "../completion/shells/shared.mjs";
|
|
10
|
+
import { Shell } from "../completion/index.mjs";
|
|
10
11
|
import { FormatLoader } from "../config/index.mjs";
|
|
11
12
|
import { formatRootHelp } from "./root-help.mjs";
|
|
12
13
|
|
|
@@ -69,11 +70,73 @@ interface CLISchema {
|
|
|
69
70
|
* CLIBuilder.manifest | .manifest()}) is active.
|
|
70
71
|
*/
|
|
71
72
|
readonly helpLinks: HelpLinks | undefined;
|
|
72
|
-
/** Whether built-in `.completions()` command
|
|
73
|
+
/** Whether built-in `.completions()` registration (command or flag) is active. */
|
|
73
74
|
readonly hasBuiltInCompletions: boolean;
|
|
75
|
+
/**
|
|
76
|
+
* Eager `--completions <shell>` flag configuration.
|
|
77
|
+
*
|
|
78
|
+
* Set when `.completions({ as: 'flag' })` is used instead of the default
|
|
79
|
+
* `completions` subcommand. When defined, the planner intercepts
|
|
80
|
+
* `--completions <shell>` before dispatch, prints the script, and exits;
|
|
81
|
+
* root help advertises the flag in its `Flags:` section.
|
|
82
|
+
*/
|
|
83
|
+
readonly completionsFlag: CompletionsFlagConfig | undefined;
|
|
84
|
+
/**
|
|
85
|
+
* Consumer-configured root-help defaults.
|
|
86
|
+
*
|
|
87
|
+
* Set via the {@linkcode CLIBuilder.help | .help()} builder method and merged
|
|
88
|
+
* under runtime `options.help` (runtime wins) before rendering.
|
|
89
|
+
*/
|
|
90
|
+
readonly helpConfig: HelpConfig | undefined;
|
|
74
91
|
/** Registered CLI plugins. */
|
|
75
92
|
readonly plugins: readonly CLIPlugin[];
|
|
76
93
|
}
|
|
94
|
+
/**
|
|
95
|
+
* Configuration for the eager `--completions <shell>` flag.
|
|
96
|
+
*
|
|
97
|
+
* Stored in {@link CLISchema} when `.completions({ as: 'flag' })` is used.
|
|
98
|
+
*
|
|
99
|
+
* @internal
|
|
100
|
+
*/
|
|
101
|
+
interface CompletionsFlagConfig {
|
|
102
|
+
/** Shell targets the flag accepts (mirrors {@link SHELLS}). */
|
|
103
|
+
readonly shells: readonly Shell[];
|
|
104
|
+
/** Generator options captured at build time (e.g. `functionPrefix`, `rootMode`). */
|
|
105
|
+
readonly options: CompletionOptions | undefined;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* Consumer-facing root-help configuration set via {@linkcode CLIBuilder.help}.
|
|
109
|
+
*
|
|
110
|
+
* Every field is optional; unset fields fall back to built-in defaults and may
|
|
111
|
+
* be overridden per call through runtime `options.help`.
|
|
112
|
+
*/
|
|
113
|
+
interface HelpConfig {
|
|
114
|
+
/**
|
|
115
|
+
* Render the default command's arguments and flags inline at the root.
|
|
116
|
+
*
|
|
117
|
+
* @defaultValue `true`
|
|
118
|
+
*/
|
|
119
|
+
readonly inlineDefault?: boolean;
|
|
120
|
+
/**
|
|
121
|
+
* Also list the default command in the root `Commands:` table.
|
|
122
|
+
*
|
|
123
|
+
* By default the default command is the root surface and is omitted from the
|
|
124
|
+
* command list (its args/flags render inline instead).
|
|
125
|
+
*
|
|
126
|
+
* @defaultValue `false`
|
|
127
|
+
*/
|
|
128
|
+
readonly showDefaultInCommands?: boolean;
|
|
129
|
+
/**
|
|
130
|
+
* Show the `Run '<bin> <command> --help' for more information.` hint.
|
|
131
|
+
*
|
|
132
|
+
* Defaults to showing the hint only when visible subcommands exist.
|
|
133
|
+
*/
|
|
134
|
+
readonly footer?: boolean;
|
|
135
|
+
/** Maximum line width (columns). */
|
|
136
|
+
readonly width?: number;
|
|
137
|
+
/** Emit OSC 8 hyperlinks in the header when supported. */
|
|
138
|
+
readonly hyperlinks?: boolean;
|
|
139
|
+
}
|
|
77
140
|
/**
|
|
78
141
|
* Config discovery settings for automatic config file loading.
|
|
79
142
|
*
|
|
@@ -266,6 +329,25 @@ declare class CLIBuilder {
|
|
|
266
329
|
readonly name?: string | URL;
|
|
267
330
|
readonly version?: string | URL;
|
|
268
331
|
}): CLIBuilder;
|
|
332
|
+
/**
|
|
333
|
+
* Configure root-help rendering defaults.
|
|
334
|
+
*
|
|
335
|
+
* Stored on the schema and merged **under** any runtime `options.help`
|
|
336
|
+
* (runtime wins). Call multiple times to set fields incrementally.
|
|
337
|
+
*
|
|
338
|
+
* @param config - Help rendering options (see {@link HelpConfig}).
|
|
339
|
+
* @returns The builder (for chaining).
|
|
340
|
+
*
|
|
341
|
+
* @example
|
|
342
|
+
* ```ts
|
|
343
|
+
* // Echo the default command under Commands and never show the footer:
|
|
344
|
+
* cli('mycli')
|
|
345
|
+
* .help({ showDefaultInCommands: true, footer: false })
|
|
346
|
+
* .default(serve)
|
|
347
|
+
* .run();
|
|
348
|
+
* ```
|
|
349
|
+
*/
|
|
350
|
+
help(config: HelpConfig): CLIBuilder;
|
|
269
351
|
/**
|
|
270
352
|
* Enable automatic config file discovery.
|
|
271
353
|
*
|
|
@@ -460,8 +542,11 @@ declare class CLIBuilder {
|
|
|
460
542
|
* dispatch normally, but empty argv or flags-only argv falls through to
|
|
461
543
|
* this command instead of showing root help.
|
|
462
544
|
*
|
|
463
|
-
* The command is
|
|
464
|
-
*
|
|
545
|
+
* The default command is the CLI's root *surface*: its flags and arguments
|
|
546
|
+
* are rendered inline in root help. It is **not** a named subcommand — it
|
|
547
|
+
* cannot be invoked by its own name (`mycli mycmd` does not route to it) and
|
|
548
|
+
* it is omitted from the root `Commands:` list by default (re-enable with
|
|
549
|
+
* `.help({ showDefaultInCommands: true })`). Only one default is allowed.
|
|
465
550
|
*
|
|
466
551
|
* @example
|
|
467
552
|
* ```ts
|
|
@@ -496,28 +581,36 @@ declare class CLIBuilder {
|
|
|
496
581
|
*/
|
|
497
582
|
plugin(definition: CLIPlugin): CLIBuilder;
|
|
498
583
|
/**
|
|
499
|
-
* Register
|
|
500
|
-
* completion scripts.
|
|
584
|
+
* Register built-in shell completion.
|
|
501
585
|
*
|
|
502
|
-
*
|
|
503
|
-
*
|
|
504
|
-
*
|
|
505
|
-
*
|
|
586
|
+
* By default (`{ as: 'command' }`) this registers a `completions` subcommand
|
|
587
|
+
* that accepts a `shell` argument and writes the script to stdout. With
|
|
588
|
+
* `{ as: 'flag' }` it instead exposes an eager `--completions <shell>` flag on
|
|
589
|
+
* the CLI root — no subcommand is registered, so a default command stays the
|
|
590
|
+
* lone root surface. The flag may be given without a value to auto-detect the
|
|
591
|
+
* shell from `$SHELL` / `$PSModulePath`.
|
|
506
592
|
*
|
|
507
|
-
*
|
|
508
|
-
* script includes the full command set
|
|
509
|
-
*
|
|
510
|
-
* will not appear in
|
|
511
|
-
*
|
|
593
|
+
* In subcommand mode, call this **after** registering all other commands so
|
|
594
|
+
* the completion script includes the full command set: that path snapshots the
|
|
595
|
+
* schema (and completion options) at call time, so commands registered
|
|
596
|
+
* afterwards will not appear in that subcommand's generated script. In flag
|
|
597
|
+
* mode, generation runs at execution time from the final builder schema, so
|
|
598
|
+
* registration order does not matter.
|
|
512
599
|
*
|
|
513
600
|
* @example
|
|
514
601
|
* ```ts
|
|
602
|
+
* // Subcommand form (default):
|
|
515
603
|
* cli('mycli')
|
|
516
604
|
* .version('1.0.0')
|
|
517
605
|
* .command(deploy)
|
|
518
|
-
* .command(login)
|
|
519
606
|
* .completions({ rootMode: 'surface' })
|
|
520
607
|
* .run();
|
|
608
|
+
*
|
|
609
|
+
* // Eager-flag form, ideal for single-command CLIs:
|
|
610
|
+
* cli('mycli')
|
|
611
|
+
* .completions({ as: 'flag' })
|
|
612
|
+
* .default(serve)
|
|
613
|
+
* .run();
|
|
521
614
|
* ```
|
|
522
615
|
*/
|
|
523
616
|
completions(options?: CompletionOptions): CLIBuilder;
|
|
@@ -637,4 +730,4 @@ declare function cli(name: string): CLIBuilder;
|
|
|
637
730
|
/** Create a new CLI program builder from an options object. */
|
|
638
731
|
declare function cli(options: CLIOptions): CLIBuilder;
|
|
639
732
|
//#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 };
|
|
733
|
+
export { type BeforeParseParams, CLIBuilder, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type CompletionsFlagConfig, type ConfigSettings, type HelpConfig, type HelpLinks, type InferNameOption, type ManifestPresetSettings, type ManifestSettings, type PackageJsonSettings, type PluginCommandContext, type ResolvedCommandParams, type ResolvedManifestSettings, cli, formatRootHelp, plugin };
|
package/dist/core/cli/index.mjs
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
import{CLIError as e}from"../errors/index.mjs";import{SHELLS as t,generateCompletion as n}from"../completion/index.mjs";import{formatHelp as r}from"../help/index.mjs";import{clearRequestedExitCode as i,createCaptureOutput as a,createOutput as o}from"../output/index.mjs";import{includesBeforeSeparator as s}from"../parse/index.mjs";import{buildRunResult as c,executeCommand as l}from"../execution/index.mjs";import{arg as u}from"../schema/arg.mjs";import{command as d}from"../schema/command.mjs";import{runCommand as f}from"../testkit/index.mjs";import{stripTrailing as p}from"../../strings.mjs";import{createAdapter as m}from"../../runtime/auto.mjs";import{deriveHelpLinks as h}from"./help-links.mjs";import{planInvocation as g}from"./planner.mjs";import"./plugin.mjs";import{formatRootHelp as _}from"./root-help.mjs";import{prepareRuntimePreflight as v}from"./runtime-preflight.mjs";function y(e){return[e.name,...e.aliases]}function b(t,n,r,i){let a=n.get(r);if(a!==void 0)throw new e(`Duplicate command route '${r}' under '${t}' (${a} and ${i})`,{code:`DUPLICATE_COMMAND`,suggest:`Ensure sibling command names and aliases are unique`});n.set(r,i)}function x(t,n){let r=new Map;for(let e of t)for(let t of y(e.schema))b(`root`,r,t,e.schema.name);for(let t of y(n)){let i=r.get(t);if(i!==void 0)throw new e(`Command route '${t}' is already registered by '${i}'`,{code:`DUPLICATE_COMMAND`,suggest:i===n.name?`Ensure command '${n.name}' does not reuse route '${t}'`:`Rename '${n.name}' or remove route '${t}' from '${i}'`});r.set(t,n.name)}}function S(e){let t=new Map,n=new Map;for(let r of e._subcommands){let i=y(r.schema);for(let t of i)b(e.schema.name,n,t,r.schema.name);let a=S(r);for(let e of i)t.set(e,a)}return{schema:e.schema,subcommands:t,_command:e,_execute(t,n){return f(e,t,n)}}}function C(e,t,n){return{help:t,...n===void 0?{}:{meta:n},...e?.plugins===void 0?{}:{plugins:e.plugins},...e?.env===void 0?{}:{env:e.env},...e?.config===void 0?{}:{config:e.config},...e?.stdinData===void 0?{}:{stdinData:e.stdinData},...e?.prompter===void 0?{}:{prompter:e.prompter},...e?.answers===void 0?{}:{answers:e.answers},...e?.verbosity===void 0?{}:{verbosity:e.verbosity},...e?.jsonMode===void 0?{}:{jsonMode:e.jsonMode},...e?.isTTY===void 0?{}:{isTTY:e.isTTY},...e?.out===void 0?{}:{out:e.out},...e?.captured===void 0?{}:{captured:e.captured}}}var w=class f{schema;constructor(e){this.schema=e}version(e){return new f({...this.schema,version:e})}description(e){return new f({...this.schema,description:e})}links(e){return new f({...this.schema,helpLinks:{name:k(e?.name),version:k(e?.version)}})}config(e,t){return new f({...this.schema,configSettings:{appName:e,loaders:t}})}configLoader(t){if(this.schema.configSettings===void 0)throw new e(`.configLoader() requires .config() to be called first`,{code:`INVALID_BUILDER_STATE`,suggest:`Call .config(appName) before .configLoader()`});let n=this.schema.configSettings.loaders??[];return new f({...this.schema,configSettings:{...this.schema.configSettings,loaders:[...n,t]}})}manifest(e){return new f(P(this.schema,e,j,!1))}packageJson(e){return new f(P(this.schema,e,j,!0))}denoJson(e){return new f(P(this.schema,e,M,!0))}command(e){return x(this.schema.commands,e.schema),new f({...this.schema,commands:[...this.schema.commands,S(e)]})}default(t){if(this.schema.defaultCommand!==void 0)throw new e(`Only one default command is allowed`,{code:`DUPLICATE_DEFAULT`,suggest:`Call .default() only once when building the CLI`});x(this.schema.commands,t.schema);let n=S(t);return new f({...this.schema,commands:[...this.schema.commands,n],defaultCommand:n})}plugin(e){return new f({...this.schema,plugins:[...this.schema.plugins,e]})}completions(r){if(this.schema.hasBuiltInCompletions)throw new e(`.completions() has already been called`,{code:`DUPLICATE_COMMAND`,suggest:`Call .completions() only once when building the CLI`});let i=this.schema,a=r,o=new Map;for(let e of t)o.set(e,e);o.set(`pwsh`,`powershell`);let s=d(`completions`).alias(`completion`).description(`Generate shell completion script`).arg(`shell`,u.custom(e=>{let n=e.split(/[\\/]/),r=(n[n.length-1]??e).replace(/\.(?:exe|cmd|bat)$/i,``),i=o.get(r);if(i===void 0)throw Error(`Unknown shell '${r}'. Valid shells: ${t.join(`, `)}`);return i}).env(`SHELL`).describe(`Target shell (${t.join(`, `)})`)).action(({args:e,meta:t,out:r})=>{let o=n(t.bin===i.name?i:{...i,name:t.bin},e.shell,a);r.jsonMode?r.json({shell:e.shell,script:o}):r.log(o)});return new f({...this.command(s).schema,hasBuiltInCompletions:!0})}async execute(e,t){let n=s(e,`--json`)||t?.jsonMode===!0,o={...t?.verbosity===void 0?{}:{verbosity:t.verbosity},...n?{jsonMode:n}:{},...t?.isTTY===void 0?{}:{isTTY:t.isTTY}},u,d;t?.out===void 0?[u,d]=a(Object.keys(o).length>0?o:void 0):(u=t.out,d=t.captured??{stdout:[],stderr:[],activity:[]}),i(u);let f={...t?.help,binName:t?.help?.binName??this.schema.name,hyperlinks:t?.help?.hyperlinks??u.isTTY},p={...t,plugins:this.schema.plugins,...n?{jsonMode:n}:{}},m={jsonMode:n,isTTY:u.isTTY,verbosity:t?.verbosity??`normal`},h=g({schema:this.schema,argv:e,help:f,output:m});switch(h.kind){case`root-version`:return u.log(h.version),c({exitCode:0,error:void 0},d);case`root-help`:{let e=_(A(this.schema),h.help);return u.log(e),c({exitCode:0,error:void 0},d)}case`dispatch-error`:return n?u.json({error:h.error.toJSON()}):(u.error(h.error.message),h.error.suggest!==void 0&&h.error.code!==`NO_ACTION`&&u.error(`Suggestion: ${h.error.suggest}`)),c({exitCode:h.error.exitCode,error:h.error},d);case`needs-subcommand`:{let e=r(h.command.schema,h.help);return u.log(e),c({exitCode:0,error:void 0},d)}case`match`:{let e=C(p,h.plan.help??f,h.plan.meta);return h.plan.command._command===void 0?h.plan.command._execute(h.plan.argv,{...e,mergedSchema:h.plan.mergedSchema}):c(await l({command:h.plan.command._command,argv:h.plan.argv,out:u,schema:h.plan.mergedSchema,meta:h.plan.meta,options:e}),d)}}}async run(e){let t=e?.adapter??m(),n=this.schema.inheritName?O(t.argv):void 0,r=await v({schema:this.schema,adapter:t,options:e,inheritedName:n});if(r.kind===`config-error`)return r.jsonMode?t.stdout(`${JSON.stringify({error:r.error.toJSON()})}\n`):(t.stderr(`Error: ${r.error.message}\n`),r.error.suggest!==void 0&&t.stderr(`Suggestion: ${r.error.suggest}\n`)),t.exit(r.error.exitCode);let i=r.schema===this.schema?this:new f(r.schema),a={...e,...r.inputs,out:o({stdout:t.stdout,stderr:t.stderr,jsonMode:r.inputs.jsonMode,isTTY:r.inputs.isTTY,...r.inputs.verbosity===`normal`?{}:{verbosity:r.inputs.verbosity}})},s=await i.execute(r.filteredArgv,a);for(let e of s.stdout)t.stdout(e);for(let e of s.stderr)t.stderr(e);return t.exit(s.exitCode)}};const T=new Set([`bun`,`deno`,`node`,`tsx`]);function E(e){let t=p(e,[47,92]);if(t.length===0)return;let n=Math.max(t.lastIndexOf(`/`),t.lastIndexOf(`\\`)),r=n>=0?t.slice(n+1):t;return r.length>0?r:void 0}function D(e){let t=e.toLowerCase().replace(/\.exe$/i,``);return T.has(t)}function O(e){let t=e[0],n=e[1],r=t===void 0?void 0:E(t);if(r!==void 0&&D(r)){if(r===`bun`&&n===`run`){let t=e[2];return t===void 0||t.startsWith(`-`)?void 0:E(t)}return r===`deno`&&n===`run`||n===void 0||n.startsWith(`-`)?void 0:E(n)}return t===void 0?void 0:E(t)}function k(e){if(e!==void 0)return e instanceof URL?e.href:e}function A(e){return e.helpLinks===void 0?e:{...e,helpLinks:h(e.helpLinks,e.packageJsonSettings?.data,e.version)}}const j=[`package.json`],M=[`deno.json`,`deno.jsonc`,`jsr.json`];function N(e){return e===void 0||e===!1?{inferName:!1,stripScope:!0}:e===!0?{inferName:!0,stripScope:!0}:{inferName:!0,stripScope:e.scope!==`keep`}}function P(e,t,n,r){if(I(t))return{...e,...e.version===void 0&&t.version!==void 0?{version:t.version}:{},...e.description===void 0&&t.description!==void 0?{description:t.description}:{},packageJsonSettings:{inferName:!1,stripScope:!0,from:void 0,files:n,data:t}};let{inferName:i,stripScope:a}=N(t?.inferName),o=r?n:t?.files??n;return{...e,packageJsonSettings:{inferName:i,stripScope:a,from:F(t?.from),files:o,data:void 0}}}function F(e){if(e===void 0)return;if(e instanceof URL){if(e.protocol!==`file:`)return e.href}else if(!e.startsWith(`file:`))return e;let t=decodeURIComponent(new URL(e).pathname);return/^\/[A-Za-z]:/.test(t)?t.slice(1).replace(/\//g,`\\`):t}function I(e){return typeof e!=`object`||!e||Array.isArray(e)?!1:`name`in e||`version`in e||`description`in e||`bin`in e||`homepage`in e||`repository`in e}function L(e){return new w({name:typeof e==`string`?e:e.name??`cli`,inheritName:typeof e==`string`?!1:e.inherit??!1,version:void 0,description:void 0,commands:[],defaultCommand:void 0,configSettings:void 0,packageJsonSettings:void 0,helpLinks:void 0,hasBuiltInCompletions:!1,plugins:[]})}export{w as CLIBuilder,L as cli};
|
|
1
|
+
import{getFlagAliasNames as e}from"../schema/flag.mjs";import{CLIError as t}from"../errors/index.mjs";import{SHELLS as n,detectShell as r,generateCompletion as i,normalizeShell as a}from"../completion/index.mjs";import{formatHelp as o}from"../help/index.mjs";import{clearRequestedExitCode as s,createCaptureOutput as c,createOutput as l}from"../output/index.mjs";import{arg as u}from"../schema/arg.mjs";import{command as d}from"../schema/command.mjs";import{includesBeforeSeparator as f}from"../parse/index.mjs";import{buildRunResult as p,executeCommand as m}from"../execution/index.mjs";import{runCommand as h}from"../testkit/index.mjs";import{stripTrailing as g}from"../../strings.mjs";import{createAdapter as _}from"../../runtime/auto.mjs";import{deriveHelpLinks as v}from"./help-links.mjs";import{planInvocation as y}from"./planner.mjs";import"./plugin.mjs";import{formatRootHelp as b}from"./root-help.mjs";import{prepareRuntimePreflight as x}from"./runtime-preflight.mjs";const S=`completions`;function C(t){if(Object.hasOwn(t.flags,S))return!0;for(let n of Object.values(t.flags))if(e(n,{kind:`long`,includeHidden:!0}).includes(S))return!0;return t.commands.some(C)}function w(e){if(C(e))throw new t(`Command '${e.name}' defines a '--${S}' flag, which is reserved by .completions({ as: 'flag' })`,{code:`RESERVED_FLAG`,suggest:`Rename the flag, or register completions as a subcommand with .completions() instead of { as: 'flag' }`})}function T(e){return[e.name,...e.aliases]}function E(e,n,r,i){let a=n.get(r);if(a!==void 0)throw new t(`Duplicate command route '${r}' under '${e}' (${a} and ${i})`,{code:`DUPLICATE_COMMAND`,suggest:`Ensure sibling command names and aliases are unique`});n.set(r,i)}function D(e,n,r){let i=new Map,a=r===void 0?e:[...e,r];for(let e of a)for(let t of T(e.schema))E(`root`,i,t,e.schema.name);for(let e of T(n)){let r=i.get(e);if(r!==void 0)throw new t(`Command route '${e}' is already registered by '${r}'`,{code:`DUPLICATE_COMMAND`,suggest:r===n.name?`Ensure command '${n.name}' does not reuse route '${e}'`:`Rename '${n.name}' or remove route '${e}' from '${r}'`});i.set(e,n.name)}}function O(e){let t=new Map,n=new Map;for(let r of e._subcommands){let i=T(r.schema);for(let t of i)E(e.schema.name,n,t,r.schema.name);let a=O(r);for(let e of i)t.set(e,a)}return{schema:e.schema,subcommands:t,_command:e,_execute(t,n){return h(e,t,n)}}}function k(e,t,n){return{help:t,...n===void 0?{}:{meta:n},...e?.plugins===void 0?{}:{plugins:e.plugins},...e?.env===void 0?{}:{env:e.env},...e?.config===void 0?{}:{config:e.config},...e?.stdinData===void 0?{}:{stdinData:e.stdinData},...e?.prompter===void 0?{}:{prompter:e.prompter},...e?.answers===void 0?{}:{answers:e.answers},...e?.verbosity===void 0?{}:{verbosity:e.verbosity},...e?.jsonMode===void 0?{}:{jsonMode:e.jsonMode},...e?.isTTY===void 0?{}:{isTTY:e.isTTY},...e?.out===void 0?{}:{out:e.out},...e?.captured===void 0?{}:{captured:e.captured}}}var A=class e{schema;constructor(e){this.schema=e}version(t){return new e({...this.schema,version:t})}description(t){return new e({...this.schema,description:t})}links(t){return new e({...this.schema,helpLinks:{name:F(t?.name),version:F(t?.version)}})}help(t){return new e({...this.schema,helpConfig:{...this.schema.helpConfig,...t}})}config(t,n){return new e({...this.schema,configSettings:{appName:t,loaders:n}})}configLoader(n){if(this.schema.configSettings===void 0)throw new t(`.configLoader() requires .config() to be called first`,{code:`INVALID_BUILDER_STATE`,suggest:`Call .config(appName) before .configLoader()`});let r=this.schema.configSettings.loaders??[];return new e({...this.schema,configSettings:{...this.schema.configSettings,loaders:[...r,n]}})}manifest(t){return new e(B(this.schema,t,L,!1))}packageJson(t){return new e(B(this.schema,t,L,!0))}denoJson(t){return new e(B(this.schema,t,R,!0))}command(t){return D(this.schema.commands,t.schema,this.schema.defaultCommand),this.schema.completionsFlag!==void 0&&w(t.schema),new e({...this.schema,commands:[...this.schema.commands,O(t)]})}default(n){if(this.schema.defaultCommand!==void 0)throw new t(`Only one default command is allowed`,{code:`DUPLICATE_DEFAULT`,suggest:`Call .default() only once when building the CLI`});D(this.schema.commands,n.schema),this.schema.completionsFlag!==void 0&&w(n.schema);let r=O(n);return new e({...this.schema,defaultCommand:r})}plugin(t){return new e({...this.schema,plugins:[...this.schema.plugins,t]})}completions(r){if(this.schema.hasBuiltInCompletions)throw new t(`.completions() has already been called`,{code:`DUPLICATE_COMMAND`,suggest:`Call .completions() only once when building the CLI`});if(r?.as===`flag`){this.schema.defaultCommand!==void 0&&w(this.schema.defaultCommand.schema);for(let e of this.schema.commands)w(e.schema);return new e({...this.schema,hasBuiltInCompletions:!0,completionsFlag:{shells:n,options:r}})}let o=this.schema,s=r,c=d(`completions`).alias(`completion`).description(`Generate shell completion script`).arg(`shell`,u.custom(e=>{let t=a(e);if(t===void 0)throw Error(`Unknown shell '${e}'. Valid shells: ${n.join(`, `)}`);return t}).env(`SHELL`).describe(`Target shell (${n.join(`, `)})`)).action(({args:e,meta:t,out:n})=>{let r=i(t.bin===o.name?o:{...o,name:t.bin},e.shell,s);n.jsonMode?n.json({shell:e.shell,script:r}):n.log(r)});return new e({...this.command(c).schema,hasBuiltInCompletions:!0})}async execute(e,n){let a=f(e,`--json`)||n?.jsonMode===!0,l={...n?.verbosity===void 0?{}:{verbosity:n.verbosity},...a?{jsonMode:a}:{},...n?.isTTY===void 0?{}:{isTTY:n.isTTY}},u,d;n?.out===void 0?[u,d]=c(Object.keys(l).length>0?l:void 0):(u=n.out,d=n.captured??{stdout:[],stderr:[],activity:[]}),s(u);let h={...this.schema.helpConfig,...n?.help,binName:n?.help?.binName??this.schema.name,hyperlinks:n?.help?.hyperlinks??this.schema.helpConfig?.hyperlinks??u.isTTY},g={...n,plugins:this.schema.plugins,...a?{jsonMode:a}:{}},_={jsonMode:a,isTTY:u.isTTY,verbosity:n?.verbosity??`normal`},v=y({schema:this.schema,argv:e,help:h,output:_});switch(v.kind){case`root-version`:return u.log(v.version),p({exitCode:0,error:void 0},d);case`root-completions`:{let e=v.shell??r(n?.env??{});if(e===void 0){let e=new t(`Could not detect shell`,{code:`MISSING_VALUE`,suggest:`Pass one explicitly, e.g. '${h.binName} --completions zsh'`});return a?u.json({error:e.toJSON()}):(u.error(e.message),u.error(`Suggestion: ${e.suggest}`)),p({exitCode:e.exitCode,error:e},d)}let o=i(h.binName===void 0||h.binName===this.schema.name?this.schema:{...this.schema,name:h.binName},e,v.options);return a?u.json({shell:e,script:o}):u.log(o),p({exitCode:0,error:void 0},d)}case`root-help`:{let e=b(I(this.schema),v.help);return u.log(e),p({exitCode:0,error:void 0},d)}case`dispatch-error`:return a?u.json({error:v.error.toJSON()}):(u.error(v.error.message),v.error.suggest!==void 0&&v.error.code!==`NO_ACTION`&&u.error(`Suggestion: ${v.error.suggest}`)),p({exitCode:v.error.exitCode,error:v.error},d);case`needs-subcommand`:{let e=o(v.command.schema,v.help);return u.log(e),p({exitCode:0,error:void 0},d)}case`match`:{let e=k(g,v.plan.help??h,v.plan.meta);return v.plan.command._command===void 0?v.plan.command._execute(v.plan.argv,{...e,mergedSchema:v.plan.mergedSchema}):p(await m({command:v.plan.command._command,argv:v.plan.argv,out:u,schema:v.plan.mergedSchema,meta:v.plan.meta,options:e}),d)}}}async run(t){let n=t?.adapter??_(),r=this.schema.inheritName?P(n.argv):void 0,i=await x({schema:this.schema,adapter:n,options:t,inheritedName:r});if(i.kind===`config-error`)return i.jsonMode?n.stdout(`${JSON.stringify({error:i.error.toJSON()})}\n`):(n.stderr(`Error: ${i.error.message}\n`),i.error.suggest!==void 0&&n.stderr(`Suggestion: ${i.error.suggest}\n`)),n.exit(i.error.exitCode);let a=i.schema===this.schema?this:new e(i.schema),o={...t,...i.inputs,out:l({stdout:n.stdout,stderr:n.stderr,jsonMode:i.inputs.jsonMode,isTTY:i.inputs.isTTY,...i.inputs.verbosity===`normal`?{}:{verbosity:i.inputs.verbosity}})},s=await a.execute(i.filteredArgv,o);for(let e of s.stdout)n.stdout(e);for(let e of s.stderr)n.stderr(e);return n.exit(s.exitCode)}};const j=new Set([`bun`,`deno`,`node`,`tsx`]);function M(e){let t=g(e,[47,92]);if(t.length===0)return;let n=Math.max(t.lastIndexOf(`/`),t.lastIndexOf(`\\`)),r=n>=0?t.slice(n+1):t;return r.length>0?r:void 0}function N(e){let t=e.toLowerCase().replace(/\.exe$/i,``);return j.has(t)}function P(e){let t=e[0],n=e[1],r=t===void 0?void 0:M(t);if(r!==void 0&&N(r)){if(r===`bun`&&n===`run`){let t=e[2];return t===void 0||t.startsWith(`-`)?void 0:M(t)}return r===`deno`&&n===`run`||n===void 0||n.startsWith(`-`)?void 0:M(n)}return t===void 0?void 0:M(t)}function F(e){if(e!==void 0)return e instanceof URL?e.href:e}function I(e){return e.helpLinks===void 0?e:{...e,helpLinks:v(e.helpLinks,e.packageJsonSettings?.data,e.version)}}const L=[`package.json`],R=[`deno.json`,`deno.jsonc`,`jsr.json`];function z(e){return e===void 0||e===!1?{inferName:!1,stripScope:!0}:e===!0?{inferName:!0,stripScope:!0}:{inferName:!0,stripScope:e.scope!==`keep`}}function B(e,t,n,r){if(H(t))return{...e,...e.version===void 0&&t.version!==void 0?{version:t.version}:{},...e.description===void 0&&t.description!==void 0?{description:t.description}:{},packageJsonSettings:{inferName:!1,stripScope:!0,from:void 0,files:n,data:t}};let{inferName:i,stripScope:a}=z(t?.inferName),o=r?n:t?.files??n;return{...e,packageJsonSettings:{inferName:i,stripScope:a,from:V(t?.from),files:o,data:void 0}}}function V(e){if(e===void 0)return;if(e instanceof URL){if(e.protocol!==`file:`)return e.href}else if(!e.startsWith(`file:`))return e;let t=decodeURIComponent(new URL(e).pathname);return/^\/[A-Za-z]:/.test(t)?t.slice(1).replace(/\//g,`\\`):t}function H(e){return typeof e!=`object`||!e||Array.isArray(e)?!1:`name`in e||`version`in e||`description`in e||`bin`in e||`homepage`in e||`repository`in e}function U(e){return new A({name:typeof e==`string`?e:e.name??`cli`,inheritName:typeof e==`string`?!1:e.inherit??!1,version:void 0,description:void 0,commands:[],defaultCommand:void 0,configSettings:void 0,packageJsonSettings:void 0,helpLinks:void 0,hasBuiltInCompletions:!1,completionsFlag:void 0,helpConfig:void 0,plugins:[]})}export{A as CLIBuilder,U as cli};
|
|
@@ -3,6 +3,8 @@ import { CLIPlugin } from "./plugin.mjs";
|
|
|
3
3
|
import { CLIError } from "../errors/index.mjs";
|
|
4
4
|
import { HelpOptions } from "../help/index.mjs";
|
|
5
5
|
import { CommandMeta, CommandSchema, ErasedCommand } from "../schema/command.mjs";
|
|
6
|
+
import { CompletionOptions } from "../completion/shells/shared.mjs";
|
|
7
|
+
import { Shell } from "../completion/index.mjs";
|
|
6
8
|
|
|
7
9
|
//#region src/core/cli/planner.d.ts
|
|
8
10
|
/**
|
|
@@ -21,6 +23,14 @@ interface PlannerSchemaLike {
|
|
|
21
23
|
readonly commands: readonly ErasedCommand[];
|
|
22
24
|
/** Fallback command when no subcommand token matches. */
|
|
23
25
|
readonly defaultCommand: ErasedCommand | undefined;
|
|
26
|
+
/**
|
|
27
|
+
* Eager `--completions <shell>` flag configuration, when `.completions()`
|
|
28
|
+
* was registered with `{ as: 'flag' }`. `undefined` disables interception.
|
|
29
|
+
*/
|
|
30
|
+
readonly completionsFlag: {
|
|
31
|
+
readonly shells: readonly Shell[];
|
|
32
|
+
readonly options: CompletionOptions | undefined;
|
|
33
|
+
} | undefined;
|
|
24
34
|
/** Plugins forwarded into every matched execution plan. */
|
|
25
35
|
readonly plugins: readonly CLIPlugin[];
|
|
26
36
|
}
|
|
@@ -38,6 +48,18 @@ interface RootVersionOutcome {
|
|
|
38
48
|
/** Resolved version string to render. */
|
|
39
49
|
readonly version: string;
|
|
40
50
|
}
|
|
51
|
+
/** Root-level `--completions [shell]` interception outcome. */
|
|
52
|
+
interface RootCompletionsOutcome {
|
|
53
|
+
/** Discriminant — argv matched the eager `--completions [shell]` flag. */
|
|
54
|
+
readonly kind: 'root-completions';
|
|
55
|
+
/**
|
|
56
|
+
* Resolved, validated target shell, or `undefined` when the flag was given
|
|
57
|
+
* without a value and the shell should be auto-detected from the environment.
|
|
58
|
+
*/
|
|
59
|
+
readonly shell: Shell | undefined;
|
|
60
|
+
/** Generator options captured at build time. */
|
|
61
|
+
readonly options: CompletionOptions | undefined;
|
|
62
|
+
}
|
|
41
63
|
/** CLI-level dispatch failure before command execution starts. */
|
|
42
64
|
interface DispatchErrorOutcome {
|
|
43
65
|
/** Discriminant — dispatch could not resolve a command from argv. */
|
|
@@ -58,7 +80,7 @@ interface PlannerMatchOutcome {
|
|
|
58
80
|
* `CLIBuilder.execute()` still renders and executes these outcomes, but
|
|
59
81
|
* planning itself is intentionally bounded to this union.
|
|
60
82
|
*/
|
|
61
|
-
type DispatchOutcome = RootHelpOutcome | RootVersionOutcome | DispatchErrorOutcome | PlannerMatchOutcome;
|
|
83
|
+
type DispatchOutcome = RootHelpOutcome | RootVersionOutcome | RootCompletionsOutcome | DispatchErrorOutcome | PlannerMatchOutcome;
|
|
62
84
|
/**
|
|
63
85
|
* Concrete execution handoff produced by a successful planner match.
|
|
64
86
|
*
|
|
@@ -133,11 +155,11 @@ declare function buildCommandExecutionPlan(options: BuildCommandExecutionPlanOpt
|
|
|
133
155
|
/**
|
|
134
156
|
* Decide what to do with an argv invocation before any command executes.
|
|
135
157
|
*
|
|
136
|
-
* Handles root interception (`--help`, `--version`,
|
|
137
|
-
* dispatches into the command tree, falls back to the
|
|
138
|
-
* produces structured errors for unknown commands/flags.
|
|
158
|
+
* Handles root interception (`--help`, `--version`, `--completions <shell>`,
|
|
159
|
+
* bare `help` token), dispatches into the command tree, falls back to the
|
|
160
|
+
* default command, and produces structured errors for unknown commands/flags.
|
|
139
161
|
* @internal
|
|
140
162
|
*/
|
|
141
163
|
declare function planInvocation(options: PlanInvocationOptions): InvocationPlan;
|
|
142
164
|
//#endregion
|
|
143
|
-
export { type CommandExecutionPlan, type DispatchErrorOutcome, type DispatchOutcome, type InvocationPlan, type NeedsSubcommandOutcome, type OutputPolicy, type PlanInvocationOptions, type PlannerMatchOutcome, type PlannerSchemaLike, type RootHelpOutcome, type RootVersionOutcome, buildCommandExecutionPlan, buildRootCommandMap, mergeCommandSchema, planInvocation };
|
|
165
|
+
export { type CommandExecutionPlan, type DispatchErrorOutcome, type DispatchOutcome, type InvocationPlan, type NeedsSubcommandOutcome, type OutputPolicy, type PlanInvocationOptions, type PlannerMatchOutcome, type PlannerSchemaLike, type RootCompletionsOutcome, type RootHelpOutcome, type RootVersionOutcome, buildCommandExecutionPlan, buildRootCommandMap, mergeCommandSchema, planInvocation };
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{collectPropagatedFlags as e}from"./propagate.mjs";import{CLIError as t,ParseError as n}from"../errors/index.mjs";import{buildFlagLookup as
|
|
1
|
+
import{collectPropagatedFlags as e}from"./propagate.mjs";import{CLIError as t,ParseError as n}from"../errors/index.mjs";import{normalizeShell as r}from"../completion/index.mjs";import{buildFlagLookup as i,flagExpectsValue as a,includesBeforeSeparator as o}from"../parse/index.mjs";import{dispatch as s,findClosestCommand as c}from"./dispatch.mjs";function l(e,t,n){return{name:e.name,bin:t.binName??e.name,version:e.version,command:n}}function u(e){let n=new Map,r=(e,r)=>{let i=n.get(e);if(i!==void 0)throw new t(`Duplicate root command route '${e}' (${i.schema.name} and ${r.schema.name})`,{code:`DUPLICATE_COMMAND`,suggest:`Ensure root command names and aliases are unique`});n.set(e,r)};for(let t of e){r(t.schema.name,t);for(let e of t.schema.aliases)r(e,t)}return n}function d(t,n){let r=e(n);return Object.keys(r).length===0?t.schema:{...t.schema,flags:{...r,...t.schema.flags}}}function f(e){return{command:e.command,mergedSchema:d(e.command,e.commandPath),argv:e.argv,meta:e.meta,plugins:e.plugins,output:e.output,help:e.help}}function p(e,t,n,r,i,a){return{kind:`match`,plan:f({command:t,commandPath:n,argv:r,meta:l(e,i,t.schema.name),plugins:e.plugins,output:a,help:i})}}function m(e,t){return t===``||e.schema.args.length>0}function h(e,t){let n=i(t);for(let t=0;t<e.length;t++){let r=e[t];if(r===void 0||r===`--`||r===`-`||!r.startsWith(`-`))return;if(r.startsWith(`--`)){let e=r.indexOf(`=`),i=r.slice(2,e===-1?void 0:e),o=n.get(i);if(o===void 0)return e===-1?r:`--${i}`;e===-1&&a(o[1])&&t++;continue}let i=r.slice(1);for(let e=0;e<i.length;e++){let r=i.charAt(e),o=n.get(r);if(o===void 0)return`-${r}`;if(a(o[1])){e===i.length-1&&t++;break}}}}function g(e,t){for(let n=0;n<e.length;n++){let r=e[n];if(r===void 0)continue;if(r===`--help`||r===`-h`)return{helpBeforeCommand:!0,firstCommandToken:void 0,commandTokenIndex:-1};if(r===`-`||!r.startsWith(`-`))return{helpBeforeCommand:!1,firstCommandToken:r,commandTokenIndex:n};if(r.startsWith(`--`)){let e=r.indexOf(`=`),i=r.slice(2,e===-1?void 0:e),o=t?.get(i);o!==void 0&&e===-1&&a(o[1])&&n++;continue}let i=r.slice(1);for(let e=0;e<i.length;e++){let r=t?.get(i.charAt(e));if(!(r===void 0||!a(r[1]))){e===i.length-1&&n++;break}}}return{helpBeforeCommand:!1,firstCommandToken:void 0,commandTokenIndex:-1}}function _(e,t){let i=e.indexOf(`--`),a=i===-1?e.length:i;for(let i=0;i<a;i++){let o=e[i];if(o===void 0)continue;let s;if(o===`--completions`){let t=i+1<a?e[i+1]:void 0;s=t!==void 0&&!t.startsWith(`-`)?t:void 0}else if(o.startsWith(`--completions=`))s=o.slice(14);else continue;if(s===void 0||s===``)return{kind:`root-completions`,shell:void 0,options:t.options};let c=r(s);return c===void 0||!t.shells.includes(c)?{kind:`dispatch-error`,error:new n(`Unknown shell '${s}'`,{code:`INVALID_VALUE`,suggest:`Valid shells: ${t.shells.join(`, `)}`})}:{kind:`root-completions`,shell:c,options:t.options}}}function v(e){let r=e.argv.indexOf(`--`),a=r===-1?e.argv:e.argv.slice(0,r),l=r===-1?[]:e.argv.slice(r),d=a.includes(`--json`)?a.filter(e=>e!==`--json`):a,f=r===-1?d:[...d,...l],y=e.schema.defaultCommand,b=y===void 0?void 0:i(y.schema.flags);if(e.schema.version!==void 0&&(o(e.argv,`--version`)||o(e.argv,`-V`)))return{kind:`root-version`,version:e.schema.version};if(e.schema.completionsFlag!==void 0){let t=_(e.argv,e.schema.completionsFlag);if(t!==void 0)return t}let x=g(d,b);if(x.helpBeforeCommand)return{kind:`root-help`,help:e.help};if(x.firstCommandToken===`help`&&!e.schema.commands.some(e=>e.schema.name===`help`||e.schema.aliases.includes(`help`))){let t=f.slice(x.commandTokenIndex+1);return t.length===0?{kind:`root-help`,help:e.help}:v({...e,argv:[...t,`--help`]})}if(e.schema.commands.length===0&&y===void 0)return{kind:`dispatch-error`,error:new t(`No commands registered`,{code:`NO_ACTION`,suggest:`Add commands via .command() or .default() before calling .run()`})};if(f.length===0&&y===void 0)return{kind:`root-help`,help:e.help};let S=s(f,u(e.schema.commands),[],b);switch(S.kind){case`unknown`:{if(y!==void 0&&S.parentPath.length===0){if((S.input===``?void 0:c(S.input,S.candidates))===void 0&&m(y,S.input))return p(e.schema,y,[y.schema],f,e.help,e.output);let t=h(f,y.schema.flags);if(t!==void 0)return{kind:`dispatch-error`,error:new n(`Unknown flag ${t}`,{code:`UNKNOWN_FLAG`,suggest:`Run '${e.schema.name} --help' for available commands`})}}if(S.input===``){let t=f.find(e=>e.startsWith(`-`));return t===void 0?{kind:`root-help`,help:e.help}:{kind:`dispatch-error`,error:new n(`Unknown flag ${t}`,{code:`UNKNOWN_FLAG`,suggest:`Run '${e.schema.name} --help' for available commands`})}}let t=c(S.input,S.candidates),r=S.parentPath.length>0?`${e.schema.name} ${S.parentPath.map(e=>e.name).join(` `)}`:e.schema.name;return{kind:`dispatch-error`,error:new n(`Unknown command: ${S.input}`,{code:`UNKNOWN_COMMAND`,suggest:t===void 0?`Run '${r} --help' for available commands`:`Did you mean '${t}'?`})}}case`needs-subcommand`:{let t=S.commandPath.slice(0,-1).map(e=>e.name);return{kind:`needs-subcommand`,command:S.command,commandPath:S.commandPath,help:{...e.help,binName:[e.schema.name,...t].join(` `)}}}case`match`:return p(e.schema,S.command,S.commandPath,S.remainingArgv,e.help,e.output)}}export{v as planInvocation};
|
|
@@ -17,13 +17,27 @@ interface CLISchemaLike {
|
|
|
17
17
|
readonly name: string | undefined;
|
|
18
18
|
readonly version: string | undefined;
|
|
19
19
|
} | undefined;
|
|
20
|
+
readonly completionsFlag?: {
|
|
21
|
+
readonly shells: readonly string[];
|
|
22
|
+
} | undefined;
|
|
23
|
+
/**
|
|
24
|
+
* Config discovery settings. Only its presence is read — defined means
|
|
25
|
+
* `.config()` enabled the built-in `--config <path>` flag, so root help
|
|
26
|
+
* advertises it in `Global options:`.
|
|
27
|
+
*/
|
|
28
|
+
readonly configSettings?: {
|
|
29
|
+
readonly appName: string;
|
|
30
|
+
} | undefined;
|
|
20
31
|
}
|
|
21
32
|
/**
|
|
22
33
|
* Generate root-level help text for the CLI program.
|
|
23
34
|
*
|
|
24
35
|
* Shows program name, version, description, usage line, and available
|
|
25
|
-
*
|
|
26
|
-
*
|
|
36
|
+
* subcommands. The default command is the CLI's root *surface*: its arguments
|
|
37
|
+
* and flags are rendered inline (unless `inlineDefault` is `false`) and it is
|
|
38
|
+
* omitted from the `Commands:` list unless `showDefaultInCommands` is set. When
|
|
39
|
+
* `.completions({ as: 'flag' })` is active, the eager `--completions <shell>`
|
|
40
|
+
* flag is advertised in the `Flags:` section.
|
|
27
41
|
*
|
|
28
42
|
* @internal
|
|
29
43
|
*/
|
|
@@ -1,6 +1,4 @@
|
|
|
1
|
-
import{resolveRootSurface as e}from"./root-surface.mjs";import{osc8 as t,padEnd as n,wrapText as r}from"../help/ansi.mjs";import{formatHelpSections as
|
|
1
|
+
import{resolveRootSurface as e}from"./root-surface.mjs";import{osc8 as t,padEnd as n,wrapText as r}from"../help/ansi.mjs";import{formatFlagEntriesBlock as i,formatHelpSections as a}from"../help/index.mjs";import{command as o}from"../schema/command.mjs";function s(t,n){let r=n?.width??80,i=n?.binName??t.name,o=n?.hyperlinks===!0,s=n?.inlineDefault??!0,l=n?.showDefaultInCommands??!1,m=e(t),h=m.visibleDefaultCommand,g=!m.hasVisibleSubcommands&&t.completionsFlag===void 0,_=s||g?h:void 0,v=c(t,_),y=v!==void 0,b=[u(t,o)];t.description!==void 0&&b.push(t.description);let x=m.hasVisibleSubcommands?h===void 0?`<command>`:`[command]`:``,S=x.length>0?`Usage: ${i} ${x} [options]`:`Usage: ${i} [options]`,C=[];y&&v!==void 0&&(C=[...a(v,{...n,binName:i,isDefaultHelp:!0})]);let w=C.shift();y&&w!==void 0&&_!==void 0?b.push(m.hasVisibleSubcommands?p(S,w):w):b.push(S);let T=l&&h!==void 0?[...m.visibleSubcommands,h]:m.visibleSubcommands;T.length>0&&b.push(d(T,l?h?.name:void 0,r)),y&&v!==void 0&&(v.description!==void 0&&v.description===t.description&&C[0]===v.description&&C.shift(),b.push(...C));let E=f(t,r);if(E.length>0&&b.push(E),n?.footer??m.hasVisibleSubcommands){let e=m.hasVisibleSubcommands?h===void 0?` <command>`:` [command]`:``;b.push(`Run '${i}${e} --help' for more information.`)}return`${b.join(`
|
|
2
2
|
|
|
3
|
-
`)}\n`}
|
|
4
|
-
|
|
5
|
-
`)}\n`}function o(e,t,n,r,i){let a=[];a.push(s(e,i)),e.description!==void 0&&a.push(e.description);let o=c(t,n);return a.push(o.length>0?`Usage: ${e.name} ${o} [options]`:`Usage: ${e.name} [options]`),t.length>0&&a.push(l(t,n?.name,r)),a}function s(e,n){let r=n?e.helpLinks:void 0,i=r?.name===void 0?e.name:t(r.name,e.name);if(e.version===void 0)return i;let a=`v${e.version}`;return`${i} ${r?.version===void 0?a:t(r.version,a)}`}function c(e,t){return e.length===0&&t===void 0?``:t===void 0?`<command>`:`[command]`}function l(e,t,i){let a=[`Commands:`],o=0;for(let n of e){let e=n.name===t?10:0,r=n.name.length+e;r>o&&(o=r)}let s=2+o+2;for(let o of e){let e=n(` ${o.name===t?`${o.name} (default)`:o.name}`,s),c=o.description??``;c.length===0?a.push(e.trimEnd()):a.push(`${e}${r(c,i,s)}`)}return a.join(`
|
|
6
|
-
`)}function u(e,t){let n=t.startsWith(`Usage: `)?t.slice(7):t;return`${e}\n${` `.repeat(7)}${n}`}export{a as formatRootHelp};
|
|
3
|
+
`)}\n`}function c(e,t){if(e.completionsFlag===void 0)return t;let n=t??o(e.name).schema;return{...n,flags:{completions:l(e.completionsFlag.shells),...n.flags}}}function l(e){return{kind:`enum`,presence:`optional`,defaultValue:void 0,aliases:[],envVar:void 0,configPath:void 0,description:`Print a shell completion script and exit`,enumValues:e,elementSchema:void 0,numberConstraints:void 0,prompt:void 0,parseFn:void 0,deprecated:void 0,propagate:!1}}function u(e,n){let r=n?e.helpLinks:void 0,i=r?.name===void 0?e.name:t(r.name,e.name);if(e.version===void 0)return i;let a=`v${e.version}`;return`${i} ${r?.version===void 0?a:t(r.version,a)}`}function d(e,t,i){let a=[`Commands:`],o=0;for(let n of e){let e=n.name===t?10:0,r=n.name.length+e;r>o&&(o=r)}let s=2+o+2;for(let o of e){let e=n(` ${o.name===t?`${o.name} (default)`:o.name}`,s),c=o.description??``;c.length===0?a.push(e.trimEnd()):a.push(`${e}${r(c,i,s)}`)}return a.join(`
|
|
4
|
+
`)}function f(e,t){let n=[{left:`-h, --help`,description:`Show this help message and exit`}];return e.version!==void 0&&n.push({left:`-V, --version`,description:`Print the version number and exit`}),n.push({left:`--json`,description:`Emit machine-readable JSON output`}),e.configSettings!==void 0&&n.push({left:`--config <path>`,description:`Load configuration from the given file`}),i(`Global options:`,n,t)}function p(e,t){let n=t.startsWith(`Usage: `)?t.slice(7):t;return`${e}\n${` `.repeat(7)}${n}`}export{s as formatRootHelp};
|
|
@@ -20,20 +20,35 @@ interface RootSurfaceSchemaLike {
|
|
|
20
20
|
/**
|
|
21
21
|
* Normalized root shape shared by help and completion logic.
|
|
22
22
|
*
|
|
23
|
+
* Since v0.3 the default command is a distinct root *surface* rather than a
|
|
24
|
+
* named subcommand: `.default()` no longer registers it under
|
|
25
|
+
* {@link RootSurfaceSchemaLike.commands}. To stay robust against callers that
|
|
26
|
+
* still place the default in the command list (e.g. hand-built test schemas),
|
|
27
|
+
* {@link resolveRootSurface} always derives {@link RootSurface.visibleSubcommands}
|
|
28
|
+
* by excluding the default command from the visible command list.
|
|
29
|
+
*
|
|
23
30
|
* @internal
|
|
24
31
|
*/
|
|
25
32
|
interface RootSurface {
|
|
33
|
+
/** All visible top-level commands as declared in `schema.commands`. */
|
|
26
34
|
readonly visibleCommands: readonly CommandSchema[];
|
|
35
|
+
/** Visible real subcommands — `visibleCommands` minus the default command. */
|
|
36
|
+
readonly visibleSubcommands: readonly CommandSchema[];
|
|
37
|
+
/** The visible default command, or `undefined` when none exists or it is hidden. */
|
|
27
38
|
readonly visibleDefaultCommand: CommandSchema | undefined;
|
|
28
|
-
|
|
29
|
-
readonly
|
|
39
|
+
/** Whether a visible default command exists. */
|
|
40
|
+
readonly hasVisibleDefault: boolean;
|
|
41
|
+
/** Whether any visible real subcommands exist (the default does not count). */
|
|
42
|
+
readonly hasVisibleSubcommands: boolean;
|
|
30
43
|
}
|
|
31
44
|
/**
|
|
32
45
|
* Resolve the visible shape of the CLI root.
|
|
33
46
|
*
|
|
34
47
|
* Hidden commands are excluded from the visible command list. Hidden
|
|
35
48
|
* default commands remain executable, but are not surfaced through
|
|
36
|
-
* help or completions.
|
|
49
|
+
* help or completions. The default command is reported separately from the
|
|
50
|
+
* real subcommands so help and completion can render it as the root surface
|
|
51
|
+
* instead of echoing it as a pseudo-subcommand.
|
|
37
52
|
*
|
|
38
53
|
* @internal
|
|
39
54
|
*/
|
|
@@ -1 +1 @@
|
|
|
1
|
-
function e(e){let t=e.commands.map(e=>e.schema).filter(e=>!e.hidden),n=e.defaultCommand?.schema,r=n!==void 0&&!n.hidden?n:void 0;return{visibleCommands:t,visibleDefaultCommand:r,
|
|
1
|
+
function e(e){let t=e.commands.map(e=>e.schema).filter(e=>!e.hidden),n=e.defaultCommand?.schema,r=n!==void 0&&!n.hidden?n:void 0,i=r===void 0?t:t.filter(e=>e.name!==r.name);return{visibleCommands:t,visibleSubcommands:i,visibleDefaultCommand:r,hasVisibleDefault:r!==void 0,hasVisibleSubcommands:i.length>0}}export{e as resolveRootSurface};
|
|
@@ -6,6 +6,8 @@ import { CommandSchema, ErasedCommand } from "../schema/command.mjs";
|
|
|
6
6
|
import { RuntimeAdapter } from "../../runtime/adapter.mjs";
|
|
7
7
|
import { PackageJsonData } from "../config/package-json.mjs";
|
|
8
8
|
import { HelpLinks } from "./help-links.mjs";
|
|
9
|
+
import { CompletionOptions } from "../completion/shells/shared.mjs";
|
|
10
|
+
import { Shell } from "../completion/index.mjs";
|
|
9
11
|
import { FormatLoader } from "../config/index.mjs";
|
|
10
12
|
|
|
11
13
|
//#region src/core/cli/runtime-preflight.d.ts
|
|
@@ -62,8 +64,21 @@ interface RuntimePreflightSchemaLike {
|
|
|
62
64
|
readonly packageJsonSettings: RuntimeManifestSettings | undefined;
|
|
63
65
|
/** Root-help header link targets; `undefined` fields may be derived from package.json. */
|
|
64
66
|
readonly helpLinks: HelpLinks | undefined;
|
|
65
|
-
/** Whether `.completions()` registered the built-in completions command. */
|
|
67
|
+
/** Whether `.completions()` registered the built-in completions command/flag. */
|
|
66
68
|
readonly hasBuiltInCompletions: boolean;
|
|
69
|
+
/** Eager `--completions <shell>` flag config; `undefined` disables interception. */
|
|
70
|
+
readonly completionsFlag: {
|
|
71
|
+
readonly shells: readonly Shell[];
|
|
72
|
+
readonly options: CompletionOptions | undefined;
|
|
73
|
+
} | undefined;
|
|
74
|
+
/** Consumer-configured root-help defaults. */
|
|
75
|
+
readonly helpConfig: {
|
|
76
|
+
readonly inlineDefault?: boolean;
|
|
77
|
+
readonly showDefaultInCommands?: boolean;
|
|
78
|
+
readonly footer?: boolean;
|
|
79
|
+
readonly width?: number;
|
|
80
|
+
readonly hyperlinks?: boolean;
|
|
81
|
+
} | undefined;
|
|
67
82
|
/** Plugins forwarded into the execution pipeline. */
|
|
68
83
|
readonly plugins: readonly CLIPlugin[];
|
|
69
84
|
}
|