@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.
Files changed (89) hide show
  1. package/CHANGELOG.md +128 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/index.d.mts +109 -16
  4. package/dist/core/cli/index.mjs +1 -1
  5. package/dist/core/cli/planner.d.mts +27 -5
  6. package/dist/core/cli/planner.mjs +1 -1
  7. package/dist/core/cli/root-help.d.mts +16 -2
  8. package/dist/core/cli/root-help.mjs +3 -5
  9. package/dist/core/cli/root-surface.d.mts +18 -3
  10. package/dist/core/cli/root-surface.mjs +1 -1
  11. package/dist/core/cli/runtime-preflight.d.mts +16 -1
  12. package/dist/core/cli/runtime-preflight.mjs +1 -1
  13. package/dist/core/completion/index.d.mts +32 -1
  14. package/dist/core/completion/index.mjs +1 -1
  15. package/dist/core/completion/shells/shared.d.mts +10 -0
  16. package/dist/core/completion/shells/shared.mjs +1 -1
  17. package/dist/core/help/index.d.mts +45 -1
  18. package/dist/core/help/index.mjs +6 -6
  19. package/dist/core/json-schema/index.mjs +1 -1
  20. package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
  21. package/dist/core/parse/index.d.mts +15 -1
  22. package/dist/core/parse/index.mjs +1 -1
  23. package/dist/core/prompt/index.d.mts +11 -3
  24. package/dist/core/prompt/index.mjs +3 -3
  25. package/dist/core/resolve/coerce.mjs +1 -1
  26. package/dist/core/resolve/flags.mjs +1 -1
  27. package/dist/core/resolve/property.d.mts +2 -0
  28. package/dist/core/resolve/property.mjs +1 -1
  29. package/dist/core/schema/arg.d.mts +90 -10
  30. package/dist/core/schema/arg.mjs +1 -1
  31. package/dist/core/schema/command.d.mts +3 -1
  32. package/dist/core/schema/flag.d.mts +92 -2
  33. package/dist/core/schema/flag.mjs +1 -1
  34. package/dist/core/schema/index.d.mts +2 -1
  35. package/dist/core/schema/number-constraints.d.mts +96 -0
  36. package/dist/core/schema/number-constraints.mjs +1 -0
  37. package/dist/core/schema/prompt.d.mts +15 -0
  38. package/dist/core/schema/run.d.mts +4 -4
  39. package/dist/core/testkit/index.d.mts +9 -5
  40. package/dist/core/testkit/index.mjs +1 -1
  41. package/dist/index.d.mts +2 -1
  42. package/dist/index.mjs +1 -1
  43. package/dist/runtime/auto.mjs +1 -1
  44. package/dist/runtime/bun.mjs +1 -1
  45. package/dist/runtime/deno.mjs +2 -2
  46. package/dist/runtime/node.mjs +2 -2
  47. package/dist/version.mjs +1 -1
  48. package/examples/basic.ts +5 -1
  49. package/examples/gh/package.json +2 -7
  50. package/examples/pwsh-demo/package.json +1 -7
  51. package/examples/pwsh-demo/src/main.test.ts +1 -4
  52. package/examples/pwsh-demo/src/main.ts +14 -4
  53. package/examples/transport-launcher.ts +85 -0
  54. package/package.json +15 -24
  55. package/src/core/cli/dispatch.ts +7 -1
  56. package/src/core/cli/index.ts +235 -34
  57. package/src/core/cli/planner.ts +192 -23
  58. package/src/core/cli/root-help.ts +195 -105
  59. package/src/core/cli/root-surface.ts +25 -12
  60. package/src/core/cli/runtime-preflight.ts +20 -2
  61. package/src/core/completion/index.ts +50 -0
  62. package/src/core/completion/shells/powershell.ts +2 -2
  63. package/src/core/completion/shells/shared.ts +30 -3
  64. package/src/core/execution/index.ts +1 -4
  65. package/src/core/help/index.ts +57 -10
  66. package/src/core/json-schema/index.ts +23 -4
  67. package/src/core/json-schema/meta-descriptions.generated.ts +115 -98
  68. package/src/core/parse/index.ts +62 -1
  69. package/src/core/prompt/index.ts +54 -14
  70. package/src/core/resolve/coerce.ts +73 -5
  71. package/src/core/resolve/flags.ts +14 -0
  72. package/src/core/resolve/property.ts +4 -4
  73. package/src/core/schema/arg.ts +125 -3
  74. package/src/core/schema/command.ts +3 -1
  75. package/src/core/schema/flag.ts +120 -4
  76. package/src/core/schema/index.ts +5 -0
  77. package/src/core/schema/number-constraints.ts +153 -0
  78. package/src/core/schema/prompt.ts +15 -0
  79. package/src/core/schema/run.ts +4 -4
  80. package/src/core/testkit/index.ts +32 -8
  81. package/src/index.ts +2 -0
  82. package/src/runtime/auto.ts +0 -24
  83. package/src/runtime/bun.ts +0 -7
  84. package/src/runtime/deno.ts +0 -2
  85. package/src/runtime/node.ts +0 -11
  86. package/src/runtime/support.ts +1 -59
  87. package/src/schema.ts +16 -0
  88. package/dist/runtime/support.d.mts +0 -42
  89. 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/v2.5.0...HEAD
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
- for (let i = 0; i < flags.times; i++) {
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
- Three subpath exports, each with a focused API surface:
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 registration is active. */
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 also registered as a normal subcommand (can be invoked
464
- * by name). Only one default command is allowed.
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 a built-in `completions` subcommand that generates shell
500
- * completion scripts.
584
+ * Register built-in shell completion.
501
585
  *
502
- * The generated command accepts a `--shell` flag (required, enum of
503
- * all {@link Shell} values) and writes the completion script to stdout
504
- * via `out.log()`. Unsupported shells throw a descriptive {@linkcode CLIError}
505
- * instead of a generic parse error.
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
- * Call this **after** registering all other commands so the completion
508
- * script includes the full command set. The captured schema is a
509
- * snapshot at call time — commands registered after `.completions()`
510
- * will not appear in the generated script. Completion options are also
511
- * captured at call time.
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 };
@@ -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`, bare `help` token),
137
- * dispatches into the command tree, falls back to the default command, and
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 r,flagExpectsValue as i,includesBeforeSeparator as a}from"../parse/index.mjs";import{dispatch as o,findClosestCommand as s}from"./dispatch.mjs";function c(e,t,n){return{name:e.name,bin:t.binName??e.name,version:e.version,command:n}}function l(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 u(t,n){let r=e(n);return Object.keys(r).length===0?t.schema:{...t.schema,flags:{...r,...t.schema.flags}}}function d(e){return{command:e.command,mergedSchema:u(e.command,e.commandPath),argv:e.argv,meta:e.meta,plugins:e.plugins,output:e.output,help:e.help}}function f(e,t,n,r,i,a){return{kind:`match`,plan:d({command:t,commandPath:n,argv:r,meta:c(e,i,t.schema.name),plugins:e.plugins,output:a,help:i})}}function p(e,t){return t===``||e.schema.args.length>0}function m(e,t){let n=r(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(`=`),a=r.slice(2,e===-1?void 0:e),o=n.get(a);if(o===void 0)return e===-1?r:`--${a}`;e===-1&&i(o[1])&&t++;continue}let a=r.slice(1);for(let e=0;e<a.length;e++){let r=a.charAt(e),o=n.get(r);if(o===void 0)return`-${r}`;if(i(o[1])){e===a.length-1&&t++;break}}}}function h(e){let i=e.argv.indexOf(`--`),c=i===-1?e.argv:e.argv.slice(0,i),u=i===-1?[]:e.argv.slice(i),d=c.includes(`--json`)?c.filter(e=>e!==`--json`):c,g=i===-1?d:[...d,...u];if(e.schema.version!==void 0&&(a(e.argv,`--version`)||a(e.argv,`-V`)))return{kind:`root-version`,version:e.schema.version};let _=g[0];if(_===`--help`||_===`-h`)return{kind:`root-help`,help:e.help};if(_===`help`&&!e.schema.commands.some(e=>e.schema.name===`help`||e.schema.aliases.includes(`help`))){let t=g.slice(1);return t.length===0?{kind:`root-help`,help:e.help}:h({...e,argv:[...t,`--help`]})}if(_===void 0&&e.schema.defaultCommand===void 0)return{kind:`root-help`,help:e.help};if(e.schema.commands.length===0)return{kind:`dispatch-error`,error:new t(`No commands registered`,{code:`NO_ACTION`,suggest:`Add commands via .command() before calling .run()`})};let v=e.schema.defaultCommand,y=v===void 0?void 0:r(v.schema.flags),b=o(g,l(e.schema.commands),[],y);switch(b.kind){case`unknown`:{if(v!==void 0&&b.parentPath.length===0){if((b.input===``?void 0:s(b.input,b.candidates))===void 0&&p(v,b.input))return f(e.schema,v,[v.schema],g,e.help,e.output);let t=m(g,v.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(b.input===``){let t=g.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=s(b.input,b.candidates),r=b.parentPath.length>0?`${e.schema.name} ${b.parentPath.map(e=>e.name).join(` `)}`:e.schema.name;return{kind:`dispatch-error`,error:new n(`Unknown command: ${b.input}`,{code:`UNKNOWN_COMMAND`,suggest:t===void 0?`Run '${r} --help' for available commands`:`Did you mean '${t}'?`})}}case`needs-subcommand`:{let t=b.commandPath.slice(0,-1).map(e=>e.name);return{kind:`needs-subcommand`,command:b.command,commandPath:b.commandPath,help:{...e.help,binName:[e.schema.name,...t].join(` `)}}}case`match`:return f(e.schema,b.command,b.commandPath,b.remainingArgv,e.help,e.output)}}export{h as planInvocation};
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
- * commands. When the default command is the only visible top-level
26
- * command, merges the root summary with that command's detailed help.
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 i}from"../help/index.mjs";function a(t,n){let r=n?.width??80,a=n?.hyperlinks===!0,s=e(t);if(s.hasSingleVisibleDefault){let e=s.visibleDefaultCommand;if(e!==void 0){let c=o(t,s.visibleCommands,s.visibleDefaultCommand,r,a),l=c.findIndex(e=>e.startsWith(`Usage: `)),d=[...i(e,{...n,binName:t.name,isDefaultHelp:!0})],f=d.shift();return l!==-1&&f!==void 0&&(c[l]=u(c[l]??``,f)),e.description!==void 0&&t.description!==void 0&&e.description===t.description&&d.shift(),c.push(...d),`${c.join(`
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`}}let l=o(t,s.visibleCommands,s.visibleDefaultCommand,r,a),d=c(s.visibleCommands,s.visibleDefaultCommand);return l.push(d.length>0?`Run '${t.name} ${d} --help' for more information.`:`Run '${t.name} --help' for more information.`),`${l.join(`
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
- readonly hasSingleVisibleDefault: boolean;
29
- readonly hasVisibleSiblingCommands: boolean;
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,hasSingleVisibleDefault:r!==void 0&&t.length===1&&t[0]?.name===r.name,hasVisibleSiblingCommands:r!==void 0&&t.some(e=>e.name!==r.name)}}export{e as resolveRootSurface};
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
  }