@kjanat/dreamcli 1.0.0 → 2.0.0
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 +45 -6
- package/LICENSE +1 -1
- package/README.md +296 -164
- package/dist/core/cli/dispatch.d.mts +85 -0
- package/dist/core/cli/dispatch.mjs +1 -0
- package/dist/core/cli/index.d.mts +418 -0
- package/dist/core/cli/index.mjs +1 -0
- package/dist/core/cli/planner.d.mts +143 -0
- package/dist/core/cli/planner.mjs +1 -0
- package/dist/core/cli/plugin.d.mts +94 -0
- package/dist/core/cli/plugin.mjs +1 -0
- package/dist/core/cli/propagate.d.mts +39 -0
- package/dist/core/cli/propagate.mjs +1 -0
- package/dist/core/cli/root-help.d.mts +28 -0
- package/dist/core/cli/root-help.mjs +7 -0
- package/dist/core/cli/root-surface.d.mts +42 -0
- package/dist/core/cli/root-surface.mjs +1 -0
- package/dist/core/cli/runtime-preflight.d.mts +149 -0
- package/dist/core/cli/runtime-preflight.mjs +1 -0
- package/dist/core/completion/index.d.mts +46 -0
- package/dist/core/completion/index.mjs +1 -0
- package/dist/core/completion/shells/bash.d.mts +24 -0
- package/dist/core/completion/shells/bash.mjs +3 -0
- package/dist/core/completion/shells/fish.d.mts +20 -0
- package/dist/core/completion/shells/fish.mjs +2 -0
- package/dist/core/completion/shells/powershell.d.mts +14 -0
- package/dist/core/completion/shells/powershell.mjs +2 -0
- package/dist/core/completion/shells/shared.d.mts +139 -0
- package/dist/core/completion/shells/shared.mjs +1 -0
- package/dist/core/completion/shells/zsh.d.mts +24 -0
- package/dist/core/completion/shells/zsh.mjs +2 -0
- package/dist/core/config/index.d.mts +161 -0
- package/dist/core/config/index.mjs +1 -0
- package/dist/core/config/package-json.d.mts +68 -0
- package/dist/core/config/package-json.mjs +1 -0
- package/dist/core/errors/index.d.mts +126 -0
- package/dist/core/errors/index.mjs +1 -0
- package/dist/core/execution/index.d.mts +49 -0
- package/dist/core/execution/index.mjs +1 -0
- package/dist/core/help/index.d.mts +49 -0
- package/dist/core/help/index.mjs +8 -0
- package/dist/core/json-schema/index.d.mts +109 -0
- package/dist/core/json-schema/index.mjs +55 -0
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
- package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
- package/dist/core/output/activity.d.mts +194 -0
- package/dist/core/output/activity.mjs +1 -0
- package/dist/core/output/contracts.d.mts +88 -0
- package/dist/core/output/contracts.mjs +1 -0
- package/dist/core/output/display-value.d.mts +19 -0
- package/dist/core/output/display-value.mjs +1 -0
- package/dist/core/output/index.d.mts +280 -0
- package/dist/core/output/index.mjs +2 -0
- package/dist/core/output/renderers.d.mts +46 -0
- package/dist/core/output/renderers.mjs +1 -0
- package/dist/core/output/writer.d.mts +40 -0
- package/dist/core/output/writer.mjs +1 -0
- package/dist/core/parse/index.d.mts +79 -0
- package/dist/core/parse/index.mjs +1 -0
- package/dist/core/prompt/index.d.mts +205 -0
- package/dist/core/prompt/index.mjs +6 -0
- package/dist/core/resolve/args.d.mts +8 -0
- package/dist/core/resolve/args.mjs +1 -0
- package/dist/core/resolve/coerce.d.mts +22 -0
- package/dist/core/resolve/coerce.mjs +1 -0
- package/dist/core/resolve/config.d.mts +10 -0
- package/dist/core/resolve/config.mjs +1 -0
- package/dist/core/resolve/contracts.d.mts +112 -0
- package/dist/core/resolve/errors.d.mts +11 -0
- package/dist/core/resolve/errors.mjs +2 -0
- package/dist/core/resolve/flags.d.mts +10 -0
- package/dist/core/resolve/flags.mjs +1 -0
- package/dist/core/resolve/index.d.mts +42 -0
- package/dist/core/resolve/index.mjs +1 -0
- package/dist/core/resolve/property.d.mts +47 -0
- package/dist/core/resolve/property.mjs +1 -0
- package/dist/core/schema/activity.d.mts +169 -0
- package/dist/core/schema/arg.d.mts +559 -0
- package/dist/core/schema/arg.mjs +1 -0
- package/dist/core/schema/command.d.mts +960 -0
- package/dist/core/schema/command.mjs +1 -0
- package/dist/core/schema/flag.d.mts +491 -0
- package/dist/core/schema/flag.mjs +1 -0
- package/dist/core/schema/index.d.mts +8 -0
- package/dist/core/schema/middleware.d.mts +122 -0
- package/dist/core/schema/middleware.mjs +1 -0
- package/dist/core/schema/prompt.d.mts +117 -0
- package/dist/core/schema/run.d.mts +171 -0
- package/dist/core/schema-dsl/runtime.d.mts +144 -0
- package/dist/core/schema-dsl/runtime.mjs +2 -0
- package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
- package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
- package/dist/core/testkit/index.d.mts +54 -0
- package/dist/core/testkit/index.mjs +1 -0
- package/dist/index.d.mts +28 -920
- package/dist/index.mjs +1 -10
- package/dist/runtime/adapter.d.mts +212 -0
- package/dist/{adapter-B37d9oia.mjs → runtime/adapter.mjs} +1 -1
- package/dist/runtime/auto.d.mts +26 -0
- package/dist/runtime/auto.mjs +1 -0
- package/dist/runtime/bun.d.mts +28 -0
- package/dist/runtime/bun.mjs +1 -0
- package/dist/runtime/deno.d.mts +76 -0
- package/dist/runtime/deno.mjs +2 -0
- package/dist/runtime/detect.d.mts +86 -0
- package/dist/runtime/detect.mjs +1 -0
- package/dist/runtime/index.d.mts +7 -0
- package/dist/runtime/node.d.mts +65 -0
- package/dist/runtime/node.mjs +2 -0
- package/dist/runtime/paths.d.mts +31 -0
- package/dist/runtime/paths.mjs +1 -0
- package/dist/runtime/support.d.mts +42 -0
- package/dist/runtime/support.mjs +1 -0
- package/dist/runtime.d.mts +6 -252
- package/dist/runtime.mjs +1 -1
- package/dist/testkit.d.mts +5 -24
- package/dist/testkit.mjs +1 -1
- package/dist/version.d.mts +16 -0
- package/dist/version.mjs +1 -0
- package/dreamcli.schema.json +338 -0
- package/examples/basic.ts +2 -2
- package/examples/gh/package.json +7 -11
- package/examples/gh/src/commands/auth.ts +2 -2
- package/examples/gh/src/commands/issue.ts +4 -4
- package/examples/gh/src/commands/pr.ts +4 -4
- package/examples/gh/src/docs.ts +11 -0
- package/examples/gh/src/lib/auth.ts +1 -1
- package/examples/gh/src/main.test.ts +6 -5
- package/examples/gh/src/main.ts +8 -6
- package/examples/interactive.ts +3 -3
- package/examples/json-mode.ts +4 -6
- package/examples/middleware.ts +3 -3
- package/examples/multi-command.ts +3 -3
- package/examples/spinner-progress.ts +5 -5
- package/examples/testing.ts +8 -6
- package/package.json +70 -44
- package/src/core/cli/dispatch.ts +4 -0
- package/src/core/cli/index.ts +185 -632
- package/src/core/cli/planner.ts +413 -0
- package/src/core/cli/plugin.ts +7 -1
- package/src/core/cli/propagate.ts +1 -1
- package/src/core/cli/runtime-preflight.ts +409 -0
- package/src/core/completion/index.ts +15 -9
- package/src/core/completion/shells/bash.ts +6 -3
- package/src/core/completion/shells/fish.ts +245 -10
- package/src/core/completion/shells/powershell.ts +390 -9
- package/src/core/completion/shells/shared.ts +4 -4
- package/src/core/completion/shells/zsh.ts +12 -7
- package/src/core/config/index.ts +7 -4
- package/src/core/config/package-json.ts +6 -2
- package/src/core/errors/index.ts +23 -8
- package/src/core/execution/index.ts +270 -0
- package/src/core/help/index.ts +13 -15
- package/src/core/json-schema/index.ts +193 -7
- package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
- package/src/core/output/contracts.ts +194 -0
- package/src/core/output/index.ts +47 -82
- package/src/core/output/renderers.ts +125 -0
- package/src/core/parse/index.ts +39 -21
- package/src/core/prompt/index.ts +44 -27
- package/src/core/resolve/args.ts +144 -0
- package/src/core/resolve/coerce.ts +432 -0
- package/src/core/resolve/config.ts +26 -0
- package/src/core/resolve/contracts.ts +135 -0
- package/src/core/resolve/errors.ts +227 -0
- package/src/core/resolve/flags.ts +205 -0
- package/src/core/resolve/index.ts +41 -1264
- package/src/core/resolve/property.ts +99 -0
- package/src/core/schema/activity.ts +3 -0
- package/src/core/schema/arg.ts +26 -14
- package/src/core/schema/command.ts +265 -38
- package/src/core/schema/flag.ts +120 -15
- package/src/core/schema/index.ts +11 -2
- package/src/core/schema/middleware.ts +6 -6
- package/src/core/schema/prompt.ts +9 -1
- package/src/core/schema/run.ts +25 -17
- package/src/core/schema-dsl/index.ts +109 -0
- package/src/core/schema-dsl/parse.ts +262 -0
- package/src/core/schema-dsl/runtime.ts +609 -0
- package/src/core/schema-dsl/to-json-schema.ts +102 -0
- package/src/core/testkit/index.ts +55 -297
- package/src/index.ts +10 -4
- package/src/runtime/adapter.ts +13 -10
- package/src/runtime/auto.ts +3 -3
- package/src/runtime/bun.ts +4 -4
- package/src/runtime/deno.ts +43 -29
- package/src/runtime/detect.ts +4 -1
- package/src/runtime/index.ts +1 -1
- package/src/runtime/node.ts +43 -21
- package/src/runtime/paths.ts +9 -3
- package/src/runtime/support.ts +20 -4
- package/src/runtime.ts +1 -1
- package/src/testkit.ts +10 -8
- package/dist/adapter-CCSh5juX.cjs +0 -1
- package/dist/adapter-DIwO-q7K.d.mts +0 -3447
- package/dist/adapter-DQnxxLiE.d.cts +0 -3447
- package/dist/auto-5cjZaF9V.mjs +0 -3
- package/dist/auto-B0eSgoDw.cjs +0 -3
- package/dist/index.cjs +0 -10
- package/dist/index.d.cts +0 -920
- package/dist/runtime.cjs +0 -1
- package/dist/runtime.d.cts +0 -253
- package/dist/testkit-CEDYPvhF.mjs +0 -14
- package/dist/testkit-ClIKijxC.cjs +0 -14
- package/dist/testkit.cjs +0 -1
- package/dist/testkit.d.cts +0 -25
- package/examples/gh/tsconfig.json +0 -37
- package/examples/tsconfig.json +0 -17
- package/src/core/cli/AGENTS.md +0 -72
- package/src/core/completion/AGENTS.md +0 -72
- package/src/core/completion/completion-test-helpers.ts +0 -48
- package/src/core/output/AGENTS.md +0 -69
- package/src/core/resolve/AGENTS.md +0 -69
- package/src/core/schema/AGENTS.md +0 -61
- package/src/core/testkit/AGENTS.md +0 -55
- package/src/runtime/AGENTS.md +0 -74
- package/src/runtime/test-helpers.ts +0 -40
package/dist/index.d.cts
DELETED
|
@@ -1,920 +0,0 @@
|
|
|
1
|
-
import { $ as ResolvedMultiselectPromptConfig, $t as WithArgPresence, A as ErrorCode, At as ResolvedValue, B as BeforeParseParams, Bt as PromptResult, Ct as FlagFactory, D as CLIError, Dt as FlagSchema, E as formatHelp, Et as FlagPresence, F as ValidationErrorCode, Ft as InputPromptConfig, G as plugin, Gt as ArgFactory, H as CLIPluginHooks, Ht as SelectPromptConfig, I as ValidationErrorOptions, It as MultiselectPromptConfig, J as ResolveResult, Jt as ArgPresence, K as DeprecationWarning, Kt as ArgKind, L as isCLIError, Lt as PromptConfig, M as ParseErrorCode, Mt as createSchema, N as ParseErrorOptions, Nt as flag, O as CLIErrorJSON, Ot as InferFlag, P as ValidationError, Pt as ConfirmPromptConfig, Q as ReadFn, Qt as ResolvedArgValue, R as isParseError, Rt as PromptConfigBase, S as group, St as FlagConfig, T as HelpOptions, Tt as FlagParseFn, U as PluginCommandContext, Ut as ArgBuilder, V as CLIPlugin, Vt as SelectChoice, W as ResolvedCommandParams, Wt as ArgConfig, Xt as InferArg, Y as resolve, Yt as ArgSchema, Z as PromptEngine, Zt as InferArgs, _ as InteractiveParams, _t as Middleware, a as ActionHandler, an as ProgressHandle, b as Out, bt as middleware, c as CommandArgEntry, cn as SpinnerOptions, ct as OutputOptions, d as CommandExample, dn as TableOptions, dt as createOutput, en as WithVariadic, et as ResolvedPromptConfig, f as CommandMeta, fn as TableStream, ft as WriteFn, g as ErasedCommand, gt as tokenize, h as DeriveParams, ht as parse, in as Fallback, it as createTerminalPrompter, j as ParseError, jt as WithPresence, k as CLIErrorOptions, kt as InferFlags, l as CommandBuilder, ln as TableColumn, lt as Verbosity, m as DeriveHandler, mt as Token, n as RuntimeAdapter, nn as createArgSchema, nt as TestAnswer, o as ActionParams, on as ProgressOptions, ot as resolvePromptConfig, p as CommandSchema, pt as ParseResult, q as ResolveOptions, qt as ArgParseFn, rn as ActivityEvent, s as AnyCommandBuilder, sn as SpinnerHandle, st as CapturedOutput, tn as arg, tt as ResolvedSelectPromptConfig, u as CommandConfig, un as TableFormat, v as InteractiveResolver, vt as MiddlewareHandler, w as RunResult, wt as FlagKind, x as command, xt as FlagBuilder, y as InteractiveResult, yt as MiddlewareParams, z as isValidationError, zt as PromptKind } from "./adapter-DQnxxLiE.cjs";
|
|
2
|
-
|
|
3
|
-
//#region src/core/completion/shells/shared.d.ts
|
|
4
|
-
/**
|
|
5
|
-
* Options for completion script generation.
|
|
6
|
-
*
|
|
7
|
-
* Passed to individual shell generators alongside the CLI schema.
|
|
8
|
-
*
|
|
9
|
-
* These options affect the generated script text, not runtime completion
|
|
10
|
-
* behavior after installation.
|
|
11
|
-
*/
|
|
12
|
-
interface CompletionOptions {
|
|
13
|
-
/**
|
|
14
|
-
* Override the generated shell function name prefix.
|
|
15
|
-
*
|
|
16
|
-
* Defaults to the CLI name from the schema. This is mainly useful when
|
|
17
|
-
* embedding multiple generated scripts in the same environment and you want
|
|
18
|
-
* deterministic, collision-free helper names.
|
|
19
|
-
*
|
|
20
|
-
* @example
|
|
21
|
-
* ```ts
|
|
22
|
-
* generateCompletion(schema, 'bash', { functionPrefix: 'acme' });
|
|
23
|
-
* ```
|
|
24
|
-
*/
|
|
25
|
-
readonly functionPrefix?: string;
|
|
26
|
-
/**
|
|
27
|
-
* Controls which root-level surface shell completion exposes when a
|
|
28
|
-
* default command exists.
|
|
29
|
-
*
|
|
30
|
-
* - `'subcommands'` keeps hybrid CLIs command-centric at the root while
|
|
31
|
-
* still exposing default-command flags for a single visible default
|
|
32
|
-
* command.
|
|
33
|
-
* - `'surface'` exposes the default command's root-usable flags at the
|
|
34
|
-
* root whenever a visible default command exists.
|
|
35
|
-
*
|
|
36
|
-
* @defaultValue `'subcommands'`
|
|
37
|
-
*/
|
|
38
|
-
readonly rootMode?: 'subcommands' | 'surface';
|
|
39
|
-
}
|
|
40
|
-
/**
|
|
41
|
-
* Normalized root completion surface consumed by shell generators.
|
|
42
|
-
*
|
|
43
|
-
* @internal
|
|
44
|
-
*/
|
|
45
|
-
//#endregion
|
|
46
|
-
//#region src/core/completion/shells/bash.d.ts
|
|
47
|
-
/**
|
|
48
|
-
* Generate a bash completion script for the CLI.
|
|
49
|
-
*
|
|
50
|
-
* Use this when you want a bash-specific script directly rather than routing
|
|
51
|
-
* through {@link generateCompletion}. The generated script expects the
|
|
52
|
-
* `bash-completion` package because it relies on `_init_completion`.
|
|
53
|
-
*
|
|
54
|
-
* @param schema - The CLI schema.
|
|
55
|
-
* @param options - Optional generator configuration.
|
|
56
|
-
* @returns A complete bash completion script.
|
|
57
|
-
*
|
|
58
|
-
* @example
|
|
59
|
-
* ```ts
|
|
60
|
-
* const script = generateBashCompletion(app.schema);
|
|
61
|
-
* // install with: mycli completions bash > /etc/bash_completion.d/mycli
|
|
62
|
-
* ```
|
|
63
|
-
*/
|
|
64
|
-
declare function generateBashCompletion(schema: CLISchema, options?: CompletionOptions): string;
|
|
65
|
-
//#endregion
|
|
66
|
-
//#region src/core/completion/shells/zsh.d.ts
|
|
67
|
-
/**
|
|
68
|
-
* Generate a zsh completion script for the CLI.
|
|
69
|
-
*
|
|
70
|
-
* Use this when you want a zsh-specific script directly rather than routing
|
|
71
|
-
* through {@link generateCompletion}. The generated script is compatible with
|
|
72
|
-
* zsh's normal `#compdef` / `fpath` loading flow.
|
|
73
|
-
*
|
|
74
|
-
* @param schema - The CLI schema.
|
|
75
|
-
* @param options - Optional generator configuration.
|
|
76
|
-
* @returns A complete zsh completion script.
|
|
77
|
-
*
|
|
78
|
-
* @example
|
|
79
|
-
* ```ts
|
|
80
|
-
* const script = generateZshCompletion(app.schema);
|
|
81
|
-
* // install with: mycli completions zsh > "${fpath[1]}/_mycli"
|
|
82
|
-
* ```
|
|
83
|
-
*/
|
|
84
|
-
declare function generateZshCompletion(schema: CLISchema, options?: CompletionOptions): string;
|
|
85
|
-
//#endregion
|
|
86
|
-
//#region src/core/completion/index.d.ts
|
|
87
|
-
/**
|
|
88
|
-
* Supported shell targets for completion script generation.
|
|
89
|
-
*
|
|
90
|
-
* `bash` and `zsh` are implemented first; `fish` and `powershell` are
|
|
91
|
-
* declared for forward compatibility but currently throw on generation.
|
|
92
|
-
*/
|
|
93
|
-
type Shell = 'bash' | 'zsh' | 'fish' | 'powershell';
|
|
94
|
-
/**
|
|
95
|
-
* Implemented shell values as a frozen readonly non-empty tuple.
|
|
96
|
-
*
|
|
97
|
-
* Use this tuple for user-facing validation and shell selection UIs.
|
|
98
|
-
* Unimplemented planned shells remain part of the broader {@link Shell} union
|
|
99
|
-
* for direct generator calls and future expansion, but they are intentionally
|
|
100
|
-
* omitted here so user-facing CLIs do not advertise unsupported targets.
|
|
101
|
-
*
|
|
102
|
-
* @see {@link Shell} for the union type matching these entries.
|
|
103
|
-
*/
|
|
104
|
-
declare const SHELLS: Readonly<readonly ['bash', 'zsh']>;
|
|
105
|
-
/**
|
|
106
|
-
* Generate a completion script for the given shell.
|
|
107
|
-
*
|
|
108
|
-
* This is the primary completion entrypoint for most consumers. Pass a CLI
|
|
109
|
-
* schema and target shell, then write the returned script to a file or source
|
|
110
|
-
* it directly from the command line.
|
|
111
|
-
*
|
|
112
|
-
* @param schema - The CLI schema describing commands, flags, and args.
|
|
113
|
-
* @param shell - Target shell.
|
|
114
|
-
* @param options - Optional generator configuration such as function naming
|
|
115
|
-
* and root default-command completion behavior.
|
|
116
|
-
* @returns A complete shell completion script as a string.
|
|
117
|
-
* @throws {CLIError} If the shell is not yet supported.
|
|
118
|
-
*
|
|
119
|
-
* @example
|
|
120
|
-
* ```ts
|
|
121
|
-
* const script = generateCompletion(app.schema, 'bash');
|
|
122
|
-
* // e.g. source <(mycli completions bash)
|
|
123
|
-
* ```
|
|
124
|
-
*/
|
|
125
|
-
declare function generateCompletion(schema: CLISchema, shell: Shell, options?: CompletionOptions): string;
|
|
126
|
-
//#endregion
|
|
127
|
-
//#region src/core/config/package-json.d.ts
|
|
128
|
-
/**
|
|
129
|
-
* Subset of package.json fields relevant to CLI metadata.
|
|
130
|
-
*
|
|
131
|
-
* All fields are optional — a valid package.json may omit any of them.
|
|
132
|
-
*/
|
|
133
|
-
interface PackageJsonData {
|
|
134
|
-
readonly name?: string;
|
|
135
|
-
readonly version?: string;
|
|
136
|
-
readonly description?: string;
|
|
137
|
-
readonly bin?: string | Readonly<Record<string, string>>;
|
|
138
|
-
}
|
|
139
|
-
/**
|
|
140
|
-
* The subset of {@link RuntimeAdapter} needed for package.json discovery.
|
|
141
|
-
*
|
|
142
|
-
* Using a narrow pick keeps the function easy to test and makes the
|
|
143
|
-
* dependency explicit.
|
|
144
|
-
*/
|
|
145
|
-
type PackageJsonAdapter = Pick<RuntimeAdapter, 'readFile' | 'cwd'>;
|
|
146
|
-
/**
|
|
147
|
-
* Discover the nearest `package.json` by walking up from `adapter.cwd`.
|
|
148
|
-
*
|
|
149
|
-
* Convenience helper behind `CLIBuilder.packageJson()`. Most apps should let
|
|
150
|
-
* the CLI runtime discover package metadata automatically; call this directly
|
|
151
|
-
* when testing metadata inference or embedding the behavior in custom tooling.
|
|
152
|
-
*
|
|
153
|
-
* Returns the parsed metadata on success, `null` when no `package.json`
|
|
154
|
-
* is found (not an error). Malformed JSON and non-object roots also
|
|
155
|
-
* return `null` — the feature is a convenience, not a hard requirement.
|
|
156
|
-
*
|
|
157
|
-
* @example
|
|
158
|
-
* ```ts
|
|
159
|
-
* import { discoverPackageJson } from 'dreamcli';
|
|
160
|
-
*
|
|
161
|
-
* const pkg = await discoverPackageJson(adapter);
|
|
162
|
-
* if (pkg !== null) {
|
|
163
|
-
* console.log(pkg.version); // '1.2.3'
|
|
164
|
-
* }
|
|
165
|
-
* ```
|
|
166
|
-
*/
|
|
167
|
-
declare function discoverPackageJson(adapter: PackageJsonAdapter): Promise<PackageJsonData | null>;
|
|
168
|
-
/**
|
|
169
|
-
* Infer the CLI binary name from package.json data.
|
|
170
|
-
*
|
|
171
|
-
* Resolution order:
|
|
172
|
-
* 1. First key of `bin` object (e.g. `{"mycli": "./dist/cli.js"}` → `"mycli"`)
|
|
173
|
-
* 2. Package `name` with scope stripped (e.g. `"@scope/mycli"` → `"mycli"`)
|
|
174
|
-
* 3. `undefined` if neither exists
|
|
175
|
-
*
|
|
176
|
-
* @example
|
|
177
|
-
* ```ts
|
|
178
|
-
* import { inferCliName } from 'dreamcli';
|
|
179
|
-
*
|
|
180
|
-
* inferCliName({ bin: { mycli: './dist/cli.js' } }); // 'mycli'
|
|
181
|
-
* inferCliName({ name: '@scope/mycli' }); // 'mycli'
|
|
182
|
-
* inferCliName({ name: 'mycli' }); // 'mycli'
|
|
183
|
-
* inferCliName({}); // undefined
|
|
184
|
-
* ```
|
|
185
|
-
*/
|
|
186
|
-
declare function inferCliName(pkg: PackageJsonData): string | undefined;
|
|
187
|
-
//#endregion
|
|
188
|
-
//#region src/core/config/index.d.ts
|
|
189
|
-
/**
|
|
190
|
-
* Format loader — parses file content into a config object.
|
|
191
|
-
*
|
|
192
|
-
* Register custom config formats by providing file extensions and a parser.
|
|
193
|
-
* Parsers may return any parsed value; {@link discoverConfig} validates that
|
|
194
|
-
* the result is a plain object before feeding it into the resolution chain.
|
|
195
|
-
*
|
|
196
|
-
* Implementations should throw on syntax or shape errors; the caller wraps
|
|
197
|
-
* those failures as {@link CLIError} with code `CONFIG_PARSE_ERROR`.
|
|
198
|
-
*/
|
|
199
|
-
interface FormatLoader {
|
|
200
|
-
/** File extensions this loader handles (without leading dot, e.g. `'toml'`). */
|
|
201
|
-
readonly extensions: readonly string[];
|
|
202
|
-
/**
|
|
203
|
-
* Parse file content into a config value.
|
|
204
|
-
*
|
|
205
|
-
* Arrays, primitives, and `null` are allowed at this boundary so generic
|
|
206
|
-
* parsers like `Bun.YAML.parse` can be passed directly. Those values are
|
|
207
|
-
* still rejected by {@link discoverConfig}, which requires a plain object.
|
|
208
|
-
*/
|
|
209
|
-
readonly parse: (content: string) => unknown;
|
|
210
|
-
}
|
|
211
|
-
/** Options for {@link discoverConfig}. */
|
|
212
|
-
interface ConfigDiscoveryOptions {
|
|
213
|
-
/**
|
|
214
|
-
* Explicit config file path (`--config` override).
|
|
215
|
-
* When provided, skips search — loads only this path.
|
|
216
|
-
*/
|
|
217
|
-
readonly configPath?: string;
|
|
218
|
-
/**
|
|
219
|
-
* Additional format loaders (JSON is built-in).
|
|
220
|
-
* Later loaders for the same extension win (allows override).
|
|
221
|
-
*/
|
|
222
|
-
readonly loaders?: readonly FormatLoader[];
|
|
223
|
-
/**
|
|
224
|
-
* Custom search paths (absolute).
|
|
225
|
-
* Replaces the default search paths when provided.
|
|
226
|
-
* Probed in order; first found wins.
|
|
227
|
-
*/
|
|
228
|
-
readonly searchPaths?: readonly string[];
|
|
229
|
-
}
|
|
230
|
-
/** Successful config discovery — file found and parsed. */
|
|
231
|
-
interface ConfigFound {
|
|
232
|
-
readonly found: true;
|
|
233
|
-
/** Absolute path to the config file that was loaded. */
|
|
234
|
-
readonly path: string;
|
|
235
|
-
/** Parsed config data. */
|
|
236
|
-
readonly data: Readonly<Record<string, unknown>>;
|
|
237
|
-
/** File extension that determined the loader (e.g. `'json'`). */
|
|
238
|
-
readonly format: string;
|
|
239
|
-
}
|
|
240
|
-
/** No config file found at any candidate path (not an error). */
|
|
241
|
-
interface ConfigNotFound {
|
|
242
|
-
readonly found: false;
|
|
243
|
-
}
|
|
244
|
-
/** Discriminated result of config discovery. */
|
|
245
|
-
type ConfigDiscoveryResult = ConfigFound | ConfigNotFound;
|
|
246
|
-
/**
|
|
247
|
-
* Build the default config search paths for an app.
|
|
248
|
-
*
|
|
249
|
-
* Advanced helper used by DreamCLI's config discovery. Most apps should call
|
|
250
|
-
* `.config()` or {@link discoverConfig} instead of constructing search paths
|
|
251
|
-
* manually. Exported for debugging, custom discovery flows, and help text.
|
|
252
|
-
*
|
|
253
|
-
* Search order (first match wins):
|
|
254
|
-
* 1. `$CWD/.{appName}.json` — dotfile in project root
|
|
255
|
-
* 2. `$CWD/{appName}.config.json` — explicit config in project root
|
|
256
|
-
* 3. `$CONFIG_DIR/{appName}/config.json` — XDG / AppData standard
|
|
257
|
-
* (`$XDG_CONFIG_HOME` / `~/.config` on Unix,
|
|
258
|
-
* `%APPDATA%` / `%USERPROFILE%\\AppData\\Roaming` on Windows)
|
|
259
|
-
*
|
|
260
|
-
* When custom {@link ConfigDiscoveryOptions.loaders | loaders} are registered,
|
|
261
|
-
* each path pattern is repeated per supported extension (JSON always first).
|
|
262
|
-
*
|
|
263
|
-
* @param appName - CLI application name used to derive config filenames.
|
|
264
|
-
* @param cwd - Current working directory (project-root search location).
|
|
265
|
-
* @param configDir - Platform config directory (XDG / AppData).
|
|
266
|
-
* @param loaders - Optional custom {@link FormatLoader}s whose extensions expand the search set.
|
|
267
|
-
* @returns Ordered list of candidate config file paths (first match wins).
|
|
268
|
-
*
|
|
269
|
-
* @example
|
|
270
|
-
* ```ts
|
|
271
|
-
* const paths = buildConfigSearchPaths('mycli', '/repo', '/home/me/.config');
|
|
272
|
-
* ```
|
|
273
|
-
*/
|
|
274
|
-
declare function buildConfigSearchPaths(appName: string, cwd: string, configDir: string, loaders?: readonly FormatLoader[]): readonly string[];
|
|
275
|
-
/**
|
|
276
|
-
* The subset of {@link RuntimeAdapter} needed for config discovery.
|
|
277
|
-
*
|
|
278
|
-
* Exported so custom hosts and tests can type the minimal adapter required by
|
|
279
|
-
* {@link discoverConfig} without depending on the full runtime adapter shape.
|
|
280
|
-
*/
|
|
281
|
-
type ConfigAdapter = Pick<RuntimeAdapter, 'readFile' | 'cwd' | 'configDir'>;
|
|
282
|
-
/**
|
|
283
|
-
* Discover and load a config file.
|
|
284
|
-
*
|
|
285
|
-
* Low-level discovery helper behind `CLIBuilder.config()`. Most apps should
|
|
286
|
-
* let the CLI runtime call this automatically; call it directly when testing
|
|
287
|
-
* config behavior or building custom bootstrapping around `RuntimeAdapter`.
|
|
288
|
-
*
|
|
289
|
-
* Pure function — all filesystem I/O flows through `adapter.readFile`.
|
|
290
|
-
* Returns a discriminated union: `{ found: true, ... }` when a config
|
|
291
|
-
* file was found and parsed, `{ found: false }` when no file exists.
|
|
292
|
-
*
|
|
293
|
-
* @throws {CLIError} code `CONFIG_NOT_FOUND` — explicit `configPath` doesn't exist
|
|
294
|
-
* @throws {CLIError} code `CONFIG_PARSE_ERROR` — file exists but fails to parse
|
|
295
|
-
* @throws {CLIError} code `CONFIG_UNKNOWN_FORMAT` — no loader for the file extension
|
|
296
|
-
*
|
|
297
|
-
* @example
|
|
298
|
-
* ```ts
|
|
299
|
-
* const result = await discoverConfig('mycli', adapter, {
|
|
300
|
-
* loaders: [
|
|
301
|
-
* configFormat(['yaml', 'yml'], Bun.YAML.parse),
|
|
302
|
-
* configFormat(['toml'], Bun.TOML.parse),
|
|
303
|
-
* ],
|
|
304
|
-
* });
|
|
305
|
-
* ```
|
|
306
|
-
*/
|
|
307
|
-
declare function discoverConfig(appName: string, adapter: ConfigAdapter, options?: ConfigDiscoveryOptions): Promise<ConfigDiscoveryResult>;
|
|
308
|
-
/**
|
|
309
|
-
* Create a {@link FormatLoader} from extensions and a parse function.
|
|
310
|
-
*
|
|
311
|
-
* Convenience factory for config loading. It avoids manually constructing the
|
|
312
|
-
* `{ extensions, parse }` object and makes intent clearer at call sites.
|
|
313
|
-
*
|
|
314
|
-
* Later loaders registered for the same extension override earlier ones. Any
|
|
315
|
-
* error thrown by `parse` is wrapped by {@link discoverConfig} as
|
|
316
|
-
* `CONFIG_PARSE_ERROR`.
|
|
317
|
-
*
|
|
318
|
-
* @param extensions - File extensions this loader handles (without dot, e.g. `'yaml'`).
|
|
319
|
-
* @param parse - Parse function: takes file content string and returns a parsed config value.
|
|
320
|
-
* @returns A {@link FormatLoader} ready to pass to {@link ConfigDiscoveryOptions.loaders}.
|
|
321
|
-
*
|
|
322
|
-
* @example
|
|
323
|
-
* ```ts
|
|
324
|
-
* import { configFormat } from 'dreamcli';
|
|
325
|
-
* import { parse as parseYaml } from 'yaml';
|
|
326
|
-
* import { parse as parseTOML } from '@iarna/toml';
|
|
327
|
-
*
|
|
328
|
-
* const yamlLoader = configFormat(['yaml', 'yml'], Bun.YAML.parse);
|
|
329
|
-
* const yamlPackageLoader = configFormat(['yaml', 'yml'], parseYaml);
|
|
330
|
-
* const tomlLoader = configFormat(['toml'], Bun.TOML.parse);
|
|
331
|
-
* const tomlPackageLoader = configFormat(['toml'], parseTOML);
|
|
332
|
-
*
|
|
333
|
-
* cli('myapp')
|
|
334
|
-
* .config('myapp')
|
|
335
|
-
* .configLoader(yamlLoader)
|
|
336
|
-
* .configLoader(tomlLoader)
|
|
337
|
-
* .run();
|
|
338
|
-
* ```
|
|
339
|
-
*/
|
|
340
|
-
declare function configFormat(extensions: readonly string[], parse: (content: string) => unknown): FormatLoader;
|
|
341
|
-
//#endregion
|
|
342
|
-
//#region src/core/cli/index.d.ts
|
|
343
|
-
/**
|
|
344
|
-
* Runtime descriptor for the CLI program.
|
|
345
|
-
*
|
|
346
|
-
* Stores the program name, version, description, and registered commands.
|
|
347
|
-
* Built incrementally by `CLIBuilder`.
|
|
348
|
-
*/
|
|
349
|
-
interface CLISchema {
|
|
350
|
-
/** Program name (used in help text, usage lines, and completion scripts). */
|
|
351
|
-
readonly name: string;
|
|
352
|
-
/**
|
|
353
|
-
* Whether `.run()` should replace `name` with the invoked program name.
|
|
354
|
-
*
|
|
355
|
-
* Set via the `cli({ inherit: true })` factory form.
|
|
356
|
-
*/
|
|
357
|
-
readonly inheritName: boolean;
|
|
358
|
-
/** Program version (shown by `--version`). */
|
|
359
|
-
readonly version: string | undefined;
|
|
360
|
-
/** Program description (shown in root help). */
|
|
361
|
-
readonly description: string | undefined;
|
|
362
|
-
/** Registered commands (type-erased for heterogeneous storage). */
|
|
363
|
-
readonly commands: readonly ErasedCommand[];
|
|
364
|
-
/**
|
|
365
|
-
* Default command dispatched when no subcommand matches.
|
|
366
|
-
*
|
|
367
|
-
* When set, the CLI root behaves like a hybrid command group: subcommands
|
|
368
|
-
* dispatch by name as usual, but empty argv or flags-only argv falls
|
|
369
|
-
* through to this command instead of showing root help.
|
|
370
|
-
*
|
|
371
|
-
* Set via the `.default()` builder method.
|
|
372
|
-
*/
|
|
373
|
-
readonly defaultCommand: ErasedCommand | undefined;
|
|
374
|
-
/**
|
|
375
|
-
* Config discovery settings. When defined, `.run()` auto-discovers and
|
|
376
|
-
* loads a config file before command dispatch.
|
|
377
|
-
*
|
|
378
|
-
* Set via the `.config()` builder method.
|
|
379
|
-
*/
|
|
380
|
-
readonly configSettings: ConfigSettings | undefined;
|
|
381
|
-
/**
|
|
382
|
-
* Package.json auto-discovery settings. When defined, `.run()` discovers
|
|
383
|
-
* the nearest `package.json` and merges metadata before dispatch.
|
|
384
|
-
*
|
|
385
|
-
* Set via the `.packageJson()` builder method.
|
|
386
|
-
*/
|
|
387
|
-
readonly packageJsonSettings: PackageJsonSettings | undefined;
|
|
388
|
-
/** Registered CLI plugins. */
|
|
389
|
-
readonly plugins: readonly CLIPlugin[];
|
|
390
|
-
}
|
|
391
|
-
/**
|
|
392
|
-
* Config discovery settings for automatic config file loading.
|
|
393
|
-
*
|
|
394
|
-
* Stored in {@link CLISchema} and consumed by `CLIBuilder.run()` to
|
|
395
|
-
* call {@link discoverConfig} before dispatching to a command.
|
|
396
|
-
*/
|
|
397
|
-
interface ConfigSettings {
|
|
398
|
-
/**
|
|
399
|
-
* Application name used to build config search paths.
|
|
400
|
-
*
|
|
401
|
-
* Search paths: `.{appName}.json` (cwd), `{appName}.config.json` (cwd),
|
|
402
|
-
* and `{configDir}/{appName}/config.json` where `configDir` is
|
|
403
|
-
* `$XDG_CONFIG_HOME` / `~/.config` on Unix or `%APPDATA%` /
|
|
404
|
-
* `%USERPROFILE%\\AppData\\Roaming` on Windows.
|
|
405
|
-
*/
|
|
406
|
-
readonly appName: string;
|
|
407
|
-
/** Additional format loaders beyond the built-in JSON loader. */
|
|
408
|
-
readonly loaders: readonly FormatLoader[] | undefined;
|
|
409
|
-
}
|
|
410
|
-
/**
|
|
411
|
-
* Package.json auto-discovery settings.
|
|
412
|
-
*
|
|
413
|
-
* Stored in {@link CLISchema} and consumed by `CLIBuilder.run()` to
|
|
414
|
-
* call {@link discoverPackageJson} before dispatching to a command.
|
|
415
|
-
*/
|
|
416
|
-
interface PackageJsonSettings {
|
|
417
|
-
/**
|
|
418
|
-
* Infer CLI name from package.json `bin` keys or `name` field.
|
|
419
|
-
*
|
|
420
|
-
* When `true`, the discovered name replaces the `cli(name)` value.
|
|
421
|
-
* Explicit `.version()`/`.description()` calls still take precedence
|
|
422
|
-
* over discovered values.
|
|
423
|
-
*
|
|
424
|
-
* @defaultValue `false`
|
|
425
|
-
*/
|
|
426
|
-
readonly inferName: boolean;
|
|
427
|
-
}
|
|
428
|
-
/**
|
|
429
|
-
* Options for `CLIBuilder.execute()` and `CLIBuilder.run()`.
|
|
430
|
-
*
|
|
431
|
-
* Mirrors `RunOptions` from testkit but adds CLI-level concerns
|
|
432
|
-
* (version display, root help formatting, runtime adapter).
|
|
433
|
-
*/
|
|
434
|
-
interface CLIRunOptions {
|
|
435
|
-
/**
|
|
436
|
-
* CLI plugins to apply for this execution.
|
|
437
|
-
*
|
|
438
|
-
* @internal — populated from `CLIBuilder.schema.plugins` during dispatch.
|
|
439
|
-
*/
|
|
440
|
-
readonly plugins?: readonly CLIPlugin[];
|
|
441
|
-
/**
|
|
442
|
-
* Runtime adapter providing platform-specific I/O, argv, env, etc.
|
|
443
|
-
*
|
|
444
|
-
* When provided to `.run()`, replaces the default Node adapter.
|
|
445
|
-
* Ignored by `.execute()` (which is process-free by design).
|
|
446
|
-
*/
|
|
447
|
-
readonly adapter?: RuntimeAdapter;
|
|
448
|
-
/**
|
|
449
|
-
* Environment variables for flag resolution.
|
|
450
|
-
*
|
|
451
|
-
* Flags with `.env('VAR')` configured resolve from this record
|
|
452
|
-
* when no CLI value is provided (CLI → env → config → default).
|
|
453
|
-
*/
|
|
454
|
-
readonly env?: Readonly<Record<string, string | undefined>>;
|
|
455
|
-
/**
|
|
456
|
-
* Configuration object for flag resolution.
|
|
457
|
-
*
|
|
458
|
-
* Flags with `.config('path')` configured resolve from this record
|
|
459
|
-
* when no CLI or env value is provided (CLI → env → config → prompt → default).
|
|
460
|
-
* Config is plain JSON — file loading is the caller's responsibility.
|
|
461
|
-
*/
|
|
462
|
-
readonly config?: Readonly<Record<string, unknown>>;
|
|
463
|
-
/**
|
|
464
|
-
* Full stdin contents for args configured with `.stdin()`.
|
|
465
|
-
*
|
|
466
|
-
* `run()` populates this from `adapter.readStdin()` only when the selected
|
|
467
|
-
* invocation needs stdin. `execute()` accepts it directly so tests can
|
|
468
|
-
* simulate piped input without a runtime adapter.
|
|
469
|
-
*/
|
|
470
|
-
readonly stdinData?: string | null;
|
|
471
|
-
/**
|
|
472
|
-
* Prompt engine for interactive flag resolution.
|
|
473
|
-
*
|
|
474
|
-
* When provided, flags with `.prompt()` configured that have no value
|
|
475
|
-
* after CLI/env/config resolution will be prompted interactively.
|
|
476
|
-
* When absent (and `answers` is also absent), prompting is skipped.
|
|
477
|
-
*
|
|
478
|
-
* Takes precedence over `answers` when both are provided.
|
|
479
|
-
*/
|
|
480
|
-
readonly prompter?: PromptEngine;
|
|
481
|
-
/**
|
|
482
|
-
* Pre-configured prompt answers for testing convenience.
|
|
483
|
-
*
|
|
484
|
-
* When provided, a test prompter is created from these answers via
|
|
485
|
-
* `createTestPrompter(answers)`. Each entry is consumed in order —
|
|
486
|
-
* use `PROMPT_CANCEL` to simulate cancellation.
|
|
487
|
-
*
|
|
488
|
-
* Ignored when an explicit `prompter` is provided.
|
|
489
|
-
*/
|
|
490
|
-
readonly answers?: readonly TestAnswer[];
|
|
491
|
-
/**
|
|
492
|
-
* Verbosity level for the output channel.
|
|
493
|
-
* @defaultValue `'normal'`
|
|
494
|
-
*/
|
|
495
|
-
readonly verbosity?: Verbosity;
|
|
496
|
-
/**
|
|
497
|
-
* Enable JSON output mode.
|
|
498
|
-
*
|
|
499
|
-
* When `true`, `log` and `info` messages are redirected to stderr
|
|
500
|
-
* so that stdout is reserved exclusively for structured `json()` output.
|
|
501
|
-
* Errors are also rendered as JSON to stderr.
|
|
502
|
-
*
|
|
503
|
-
* @defaultValue `false`
|
|
504
|
-
*/
|
|
505
|
-
readonly jsonMode?: boolean;
|
|
506
|
-
/**
|
|
507
|
-
* Whether stdout is connected to a TTY.
|
|
508
|
-
*
|
|
509
|
-
* When provided, propagated to the output channel's `isTTY` field.
|
|
510
|
-
* In `.run()`, automatically sourced from `adapter.isTTY` when not
|
|
511
|
-
* explicitly set.
|
|
512
|
-
*
|
|
513
|
-
* @defaultValue `false`
|
|
514
|
-
*/
|
|
515
|
-
readonly isTTY?: boolean;
|
|
516
|
-
/**
|
|
517
|
-
* Output channel override used by `run()` for live terminal rendering.
|
|
518
|
-
*
|
|
519
|
-
* @internal — `execute()` remains capture-first by default.
|
|
520
|
-
*/
|
|
521
|
-
readonly out?: Out;
|
|
522
|
-
/**
|
|
523
|
-
* Capture buffers paired with `out`.
|
|
524
|
-
*
|
|
525
|
-
* @internal — `run()` omits this and accepts empty buffers in the returned
|
|
526
|
-
* `RunResult` because output is already written to the real adapter streams.
|
|
527
|
-
*/
|
|
528
|
-
readonly captured?: CapturedOutput;
|
|
529
|
-
/**
|
|
530
|
-
* Help formatting options (width, binName).
|
|
531
|
-
* `binName` defaults to the CLI program name.
|
|
532
|
-
*/
|
|
533
|
-
readonly help?: HelpOptions;
|
|
534
|
-
}
|
|
535
|
-
/**
|
|
536
|
-
* Immutable CLI program builder.
|
|
537
|
-
*
|
|
538
|
-
* Registers commands, handles root-level `--help`/`--version`, and
|
|
539
|
-
* dispatches to the matched command based on argv.
|
|
540
|
-
*
|
|
541
|
-
* Two execution paths:
|
|
542
|
-
* - `.execute(argv, options?)` — testable, returns `RunResult`
|
|
543
|
-
* - `.run(options?)` — production entry, reads `process.argv`, exits process
|
|
544
|
-
*
|
|
545
|
-
* @example
|
|
546
|
-
* ```ts
|
|
547
|
-
* import { cli, command, flag, arg } from 'dreamcli';
|
|
548
|
-
*
|
|
549
|
-
* const deploy = command('deploy')
|
|
550
|
-
* .arg('target', arg.string())
|
|
551
|
-
* .flag('force', flag.boolean().alias('f'))
|
|
552
|
-
* .action(({ args, flags, out }) => {
|
|
553
|
-
* out.log(`Deploying ${args.target}...`);
|
|
554
|
-
* });
|
|
555
|
-
*
|
|
556
|
-
* cli('mycli')
|
|
557
|
-
* .version('1.0.0')
|
|
558
|
-
* .command(deploy)
|
|
559
|
-
* .run();
|
|
560
|
-
* ```
|
|
561
|
-
*/
|
|
562
|
-
declare class CLIBuilder {
|
|
563
|
-
/** @internal Runtime schema descriptor. */
|
|
564
|
-
readonly schema: CLISchema;
|
|
565
|
-
constructor(schema: CLISchema);
|
|
566
|
-
/**
|
|
567
|
-
* Set the program version (shown by `--version`).
|
|
568
|
-
*
|
|
569
|
-
* @param v - Semantic version string.
|
|
570
|
-
* @returns The builder (for chaining).
|
|
571
|
-
*/
|
|
572
|
-
version(v: string): CLIBuilder;
|
|
573
|
-
/**
|
|
574
|
-
* Set the program description (shown in root help).
|
|
575
|
-
*
|
|
576
|
-
* @param text - Short description displayed in root help output.
|
|
577
|
-
* @returns The builder (for chaining).
|
|
578
|
-
*/
|
|
579
|
-
description(text: string): CLIBuilder;
|
|
580
|
-
/**
|
|
581
|
-
* Enable automatic config file discovery.
|
|
582
|
-
*
|
|
583
|
-
* When enabled, `.run()` probes standard paths before dispatching:
|
|
584
|
-
* 1. `$CWD/.{appName}.json`
|
|
585
|
-
* 2. `$CWD/{appName}.config.json`
|
|
586
|
-
* 3. `$CONFIG_DIR/{appName}/config.json`
|
|
587
|
-
* (`$XDG_CONFIG_HOME` / `~/.config` on Unix,
|
|
588
|
-
* `%APPDATA%` / `%USERPROFILE%\\AppData\\Roaming` on Windows)
|
|
589
|
-
*
|
|
590
|
-
* The user can override the path via `--config <path>` or `--config=<path>`.
|
|
591
|
-
*
|
|
592
|
-
* Loaded config feeds into the resolution chain
|
|
593
|
-
* (CLI → env → **config** → prompt → default) for flags that
|
|
594
|
-
* declare `.config('dotted.path')`.
|
|
595
|
-
*
|
|
596
|
-
* Has no effect in `.execute()` (which receives config via
|
|
597
|
-
* `options.config` directly).
|
|
598
|
-
*
|
|
599
|
-
* @param appName - Name used to build search paths.
|
|
600
|
-
* @param loaders - Additional {@link FormatLoader}s (JSON is built-in).
|
|
601
|
-
* @returns The builder (for chaining).
|
|
602
|
-
*/
|
|
603
|
-
config(appName: string, loaders?: readonly FormatLoader[]): CLIBuilder;
|
|
604
|
-
/**
|
|
605
|
-
* Register a custom config format loader.
|
|
606
|
-
*
|
|
607
|
-
* Adds a {@link FormatLoader} incrementally — call multiple times to
|
|
608
|
-
* register multiple formats. Loaders registered later for the same
|
|
609
|
-
* extension override earlier ones.
|
|
610
|
-
*
|
|
611
|
-
* Requires `.config()` to have been called first (sets the app name).
|
|
612
|
-
*
|
|
613
|
-
* @param loader - Format loader (or extensions + parse function).
|
|
614
|
-
* @returns The builder (for chaining).
|
|
615
|
-
*
|
|
616
|
-
* @example Bun built-in parsers
|
|
617
|
-
* ```ts
|
|
618
|
-
* import { configFormat } from 'dreamcli';
|
|
619
|
-
*
|
|
620
|
-
* cli('myapp')
|
|
621
|
-
* .config('myapp')
|
|
622
|
-
* .configLoader(configFormat(['yaml', 'yml'], Bun.YAML.parse))
|
|
623
|
-
* .configLoader(configFormat(['toml'], Bun.TOML.parse))
|
|
624
|
-
* .run();
|
|
625
|
-
* ```
|
|
626
|
-
*
|
|
627
|
-
* @example npm package parsers
|
|
628
|
-
* ```ts
|
|
629
|
-
* import { configFormat } from 'dreamcli';
|
|
630
|
-
* import { parse as parseYaml } from 'yaml';
|
|
631
|
-
* import { parse as parseTOML } from '@iarna/toml';
|
|
632
|
-
*
|
|
633
|
-
* cli('myapp')
|
|
634
|
-
* .config('myapp')
|
|
635
|
-
* .configLoader(configFormat(['yaml', 'yml'], parseYaml))
|
|
636
|
-
* .configLoader(configFormat(['toml'], parseTOML))
|
|
637
|
-
* .run();
|
|
638
|
-
* ```
|
|
639
|
-
*/
|
|
640
|
-
configLoader(loader: FormatLoader): CLIBuilder;
|
|
641
|
-
/**
|
|
642
|
-
* Enable automatic package.json metadata discovery.
|
|
643
|
-
*
|
|
644
|
-
* When enabled, `.run()` walks up from `cwd` to find the nearest
|
|
645
|
-
* `package.json` and merges its `version` and `description` fields
|
|
646
|
-
* into the CLI schema. Explicit `.version()` and `.description()`
|
|
647
|
-
* calls always take precedence over discovered values.
|
|
648
|
-
*
|
|
649
|
-
* Has no effect in `.execute()` (which is filesystem-free by design).
|
|
650
|
-
*
|
|
651
|
-
* @param settings - Optional settings. Pass `{ inferName: true }` to
|
|
652
|
-
* also infer the CLI name from `bin` keys or the package `name` field.
|
|
653
|
-
*
|
|
654
|
-
* @example
|
|
655
|
-
* ```ts
|
|
656
|
-
* // Auto-fill version + description from nearest package.json:
|
|
657
|
-
* cli('mycli')
|
|
658
|
-
* .packageJson()
|
|
659
|
-
* .command(deploy)
|
|
660
|
-
* .run();
|
|
661
|
-
*
|
|
662
|
-
* // Also infer CLI name from bin key / package name:
|
|
663
|
-
* cli('mycli')
|
|
664
|
-
* .packageJson({ inferName: true })
|
|
665
|
-
* .command(deploy)
|
|
666
|
-
* .run();
|
|
667
|
-
*
|
|
668
|
-
* // Explicit values always win:
|
|
669
|
-
* cli('mycli')
|
|
670
|
-
* .packageJson()
|
|
671
|
-
* .version('2.0.0-beta') // wins over package.json
|
|
672
|
-
* .run();
|
|
673
|
-
* ```
|
|
674
|
-
*/
|
|
675
|
-
packageJson(settings?: {
|
|
676
|
-
readonly inferName?: boolean;
|
|
677
|
-
}): CLIBuilder;
|
|
678
|
-
/**
|
|
679
|
-
* Register a command with the CLI program.
|
|
680
|
-
*
|
|
681
|
-
* The command's type parameters are erased for heterogeneous storage.
|
|
682
|
-
* Type safety is preserved inside the closure that delegates to
|
|
683
|
-
* `runCommand()`.
|
|
684
|
-
*
|
|
685
|
-
* @param cmd - {@link CommandBuilder} to register.
|
|
686
|
-
* @returns The builder (for chaining).
|
|
687
|
-
*/
|
|
688
|
-
command<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown>>(cmd: CommandBuilder<F, A, C>): CLIBuilder;
|
|
689
|
-
/**
|
|
690
|
-
* Register a command as the default — dispatched when no subcommand is given.
|
|
691
|
-
*
|
|
692
|
-
* The CLI root behaves like a hybrid command group: named subcommands
|
|
693
|
-
* dispatch normally, but empty argv or flags-only argv falls through to
|
|
694
|
-
* this command instead of showing root help.
|
|
695
|
-
*
|
|
696
|
-
* The command is also registered as a normal subcommand (can be invoked
|
|
697
|
-
* by name). Only one default command is allowed.
|
|
698
|
-
*
|
|
699
|
-
* @example
|
|
700
|
-
* ```ts
|
|
701
|
-
* // Single-command CLI — no subcommand name needed:
|
|
702
|
-
* // mytool --force production
|
|
703
|
-
* cli('mytool')
|
|
704
|
-
* .default(deploy)
|
|
705
|
-
* .run();
|
|
706
|
-
*
|
|
707
|
-
* // Multi-command CLI with a default:
|
|
708
|
-
* // mytool production → runs deploy
|
|
709
|
-
* // mytool status → runs status
|
|
710
|
-
* cli('mytool')
|
|
711
|
-
* .default(deploy)
|
|
712
|
-
* .command(status)
|
|
713
|
-
* .run();
|
|
714
|
-
* ```
|
|
715
|
-
*
|
|
716
|
-
* @param cmd - {@link CommandBuilder} to register as the default.
|
|
717
|
-
* @returns The builder (for chaining).
|
|
718
|
-
*/
|
|
719
|
-
default<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown>>(cmd: CommandBuilder<F, A, C>): CLIBuilder;
|
|
720
|
-
/**
|
|
721
|
-
* Register a CLI plugin.
|
|
722
|
-
*
|
|
723
|
-
* Plugins run in registration order. At each lifecycle stage, all hooks for
|
|
724
|
-
* the first plugin run before hooks for the second plugin, and so on.
|
|
725
|
-
*
|
|
726
|
-
* @param definition - A frozen {@link CLIPlugin} created by {@link plugin}.
|
|
727
|
-
* @returns The builder (for chaining).
|
|
728
|
-
* @see {@link plugin} to construct plugin definitions.
|
|
729
|
-
*/
|
|
730
|
-
plugin(definition: CLIPlugin): CLIBuilder;
|
|
731
|
-
/**
|
|
732
|
-
* Register a built-in `completions` subcommand that generates shell
|
|
733
|
-
* completion scripts.
|
|
734
|
-
*
|
|
735
|
-
* The generated command accepts a `--shell` flag (required, enum of
|
|
736
|
-
* all {@link Shell} values) and writes the completion script to stdout
|
|
737
|
-
* via `out.log()`. Unsupported shells throw a descriptive `CLIError`
|
|
738
|
-
* instead of a generic parse error.
|
|
739
|
-
*
|
|
740
|
-
* Call this **after** registering all other commands so the completion
|
|
741
|
-
* script includes the full command set. The captured schema is a
|
|
742
|
-
* snapshot at call time — commands registered after `.completions()`
|
|
743
|
-
* will not appear in the generated script. Completion options are also
|
|
744
|
-
* captured at call time.
|
|
745
|
-
*
|
|
746
|
-
* @example
|
|
747
|
-
* ```ts
|
|
748
|
-
* cli('mycli')
|
|
749
|
-
* .version('1.0.0')
|
|
750
|
-
* .command(deploy)
|
|
751
|
-
* .command(login)
|
|
752
|
-
* .completions({ rootMode: 'surface' })
|
|
753
|
-
* .run();
|
|
754
|
-
* ```
|
|
755
|
-
*/
|
|
756
|
-
completions(options?: CompletionOptions): CLIBuilder;
|
|
757
|
-
/**
|
|
758
|
-
* Execute the CLI program against explicit argv.
|
|
759
|
-
*
|
|
760
|
-
* This is the testable execution path — no process state is touched.
|
|
761
|
-
* Returns a structured `RunResult` with exit code and captured output.
|
|
762
|
-
*
|
|
763
|
-
* @param argv - Raw argv tokens (NOT including the binary/script path,
|
|
764
|
-
* i.e. equivalent to `process.argv.slice(2)`).
|
|
765
|
-
* @param options - Injectable runtime state.
|
|
766
|
-
* @returns Structured result with exit code and captured output.
|
|
767
|
-
*/
|
|
768
|
-
execute(argv: readonly string[], options?: CLIRunOptions): Promise<RunResult>;
|
|
769
|
-
/**
|
|
770
|
-
* Run the CLI program as a production entry point.
|
|
771
|
-
*
|
|
772
|
-
* Reads argv from the runtime adapter, dispatches to the matched
|
|
773
|
-
* command, writes output to real streams, and exits the process.
|
|
774
|
-
*
|
|
775
|
-
* This is the **only** place that touches process state (via the
|
|
776
|
-
* adapter). For testing, use `.execute()` instead — or provide a
|
|
777
|
-
* test adapter via `options.adapter`.
|
|
778
|
-
*
|
|
779
|
-
* Defaults to `createAdapter()` when no adapter is provided,
|
|
780
|
-
* which auto-detects the runtime (Node.js, Bun) and creates
|
|
781
|
-
* the appropriate adapter.
|
|
782
|
-
*
|
|
783
|
-
* @param options - Optional runtime configuration including adapter.
|
|
784
|
-
*/
|
|
785
|
-
run(options?: CLIRunOptions): Promise<never>;
|
|
786
|
-
}
|
|
787
|
-
/**
|
|
788
|
-
* Options for the `cli({...})` factory form.
|
|
789
|
-
*
|
|
790
|
-
* This form is useful when the displayed CLI name should be inferred from the
|
|
791
|
-
* current runtime invocation instead of always being hard-coded.
|
|
792
|
-
*/
|
|
793
|
-
interface CLIOptions {
|
|
794
|
-
/**
|
|
795
|
-
* Explicit fallback CLI name.
|
|
796
|
-
*
|
|
797
|
-
* Used by `.execute()`, and by `.run()` when runtime name inheritance is
|
|
798
|
-
* disabled or the invocation name cannot be inferred.
|
|
799
|
-
*
|
|
800
|
-
* @defaultValue `'cli'`
|
|
801
|
-
*/
|
|
802
|
-
readonly name?: string;
|
|
803
|
-
/**
|
|
804
|
-
* Replace `name` with the invoked program basename during `.run()`.
|
|
805
|
-
*
|
|
806
|
-
* Examples:
|
|
807
|
-
* - `node ./bin/mycli.ts` → `mycli.ts`
|
|
808
|
-
* - `/usr/local/bin/mycli` → `mycli`
|
|
809
|
-
*
|
|
810
|
-
* @defaultValue `false`
|
|
811
|
-
*/
|
|
812
|
-
readonly inherit?: boolean;
|
|
813
|
-
}
|
|
814
|
-
/**
|
|
815
|
-
* Create a new CLI program builder.
|
|
816
|
-
*
|
|
817
|
-
* The CLI name is used in help text, usage lines, and generated completion scripts.
|
|
818
|
-
*
|
|
819
|
-
* @param nameOrOptions - Either the explicit CLI name or factory options.
|
|
820
|
-
*
|
|
821
|
-
* @example
|
|
822
|
-
* ```ts
|
|
823
|
-
* cli('mycli')
|
|
824
|
-
* .version('1.0.0')
|
|
825
|
-
* .description('My awesome tool')
|
|
826
|
-
* .command(deploy)
|
|
827
|
-
* .command(login)
|
|
828
|
-
* .run();
|
|
829
|
-
*
|
|
830
|
-
* cli({ inherit: true })
|
|
831
|
-
* .command(deploy)
|
|
832
|
-
* .run();
|
|
833
|
-
* ```
|
|
834
|
-
*/
|
|
835
|
-
declare function cli(name: string): CLIBuilder;
|
|
836
|
-
declare function cli(options: CLIOptions): CLIBuilder;
|
|
837
|
-
//#endregion
|
|
838
|
-
//#region src/core/json-schema/index.d.ts
|
|
839
|
-
/**
|
|
840
|
-
* Options for JSON Schema generation.
|
|
841
|
-
*
|
|
842
|
-
* Both {@link generateSchema} and {@link generateInputSchema} accept these
|
|
843
|
-
* options to control which parts of the CLI schema are included in the output.
|
|
844
|
-
*/
|
|
845
|
-
interface JsonSchemaOptions {
|
|
846
|
-
/**
|
|
847
|
-
* Include commands marked as hidden.
|
|
848
|
-
*
|
|
849
|
-
* When `true` (default), hidden commands appear in the output with
|
|
850
|
-
* `hidden: true` (definition schema) or as valid branches (input schema).
|
|
851
|
-
* When `false`, hidden commands and their entire subtrees are excluded.
|
|
852
|
-
*
|
|
853
|
-
* @defaultValue `true`
|
|
854
|
-
*/
|
|
855
|
-
readonly includeHidden?: boolean;
|
|
856
|
-
/**
|
|
857
|
-
* Include prompt configuration on flags.
|
|
858
|
-
*
|
|
859
|
-
* When `false`, prompt configs are omitted even if defined on flags.
|
|
860
|
-
* Useful for producing a schema focused on the non-interactive CLI
|
|
861
|
-
* surface only.
|
|
862
|
-
*
|
|
863
|
-
* Only affects {@link generateSchema} output — prompt configs are never
|
|
864
|
-
* included in {@link generateInputSchema} output.
|
|
865
|
-
*
|
|
866
|
-
* @defaultValue `true`
|
|
867
|
-
*/
|
|
868
|
-
readonly includePrompts?: boolean;
|
|
869
|
-
}
|
|
870
|
-
/**
|
|
871
|
-
* Generate a definition metadata document describing the CLI's structure.
|
|
872
|
-
*
|
|
873
|
-
* Walks the full command tree and produces a plain JSON-serializable object
|
|
874
|
-
* representing all commands, subcommands, flags, args, and metadata.
|
|
875
|
-
* Non-serializable runtime values (parse functions, middleware handlers,
|
|
876
|
-
* interactive resolvers) are omitted.
|
|
877
|
-
*
|
|
878
|
-
* @param schema - The CLI schema from `CLIBuilder.schema`.
|
|
879
|
-
* @param options - Generation options.
|
|
880
|
-
* @returns A plain object suitable for `JSON.stringify()`.
|
|
881
|
-
*
|
|
882
|
-
* @example
|
|
883
|
-
* ```ts
|
|
884
|
-
* const app = cli('myapp').version('1.0.0').command(deploy);
|
|
885
|
-
* const definition = generateSchema(app.schema);
|
|
886
|
-
* writeFileSync('cli-schema.json', JSON.stringify(definition, null, 2));
|
|
887
|
-
* ```
|
|
888
|
-
*/
|
|
889
|
-
declare function generateSchema(schema: CLISchema, options?: JsonSchemaOptions): Record<string, unknown>;
|
|
890
|
-
/**
|
|
891
|
-
* Generate a JSON Schema (draft 2020-12) for validating CLI input as JSON.
|
|
892
|
-
*
|
|
893
|
-
* Accepts either a full {@link CLISchema} (producing a discriminated union
|
|
894
|
-
* across all commands) or a single {@link CommandSchema} (producing a flat
|
|
895
|
-
* object schema for that command's flags and args).
|
|
896
|
-
*
|
|
897
|
-
* **Single command** — produces an object schema where flag/arg names are
|
|
898
|
-
* properties with appropriate JSON Schema types.
|
|
899
|
-
*
|
|
900
|
-
* **Multi-command CLI** — produces a `oneOf` discriminated union with a
|
|
901
|
-
* `command` property identifying each branch. Nested subcommands use
|
|
902
|
-
* dot-delimited paths (e.g. `"deploy.rollback"`).
|
|
903
|
-
*
|
|
904
|
-
* Only commands with action handlers are included (group commands without
|
|
905
|
-
* actions are not directly invocable and are skipped).
|
|
906
|
-
*
|
|
907
|
-
* @param schema - A CLI schema or a single command schema.
|
|
908
|
-
* @param options - Generation options.
|
|
909
|
-
* @returns A JSON Schema object suitable for `JSON.stringify()`.
|
|
910
|
-
*
|
|
911
|
-
* @example
|
|
912
|
-
* ```ts
|
|
913
|
-
* // Validate a config file against the CLI's input shape
|
|
914
|
-
* const inputSchema = generateInputSchema(app.schema);
|
|
915
|
-
* writeFileSync('input-schema.json', JSON.stringify(inputSchema, null, 2));
|
|
916
|
-
* ```
|
|
917
|
-
*/
|
|
918
|
-
declare function generateInputSchema(schema: CLISchema | CommandSchema, options?: JsonSchemaOptions): Record<string, unknown>;
|
|
919
|
-
//#endregion
|
|
920
|
-
export { type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type BeforeParseParams, CLIBuilder, CLIError, type CLIErrorJSON, type CLIErrorOptions, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type CompletionOptions, type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type ConfigSettings, type ConfirmPromptConfig, type DeprecationWarning, type DeriveHandler, type DeriveParams, type ErrorCode, type Fallback, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FormatLoader, type HelpOptions, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type JsonSchemaOptions, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type Out, type OutputOptions, type PackageJsonAdapter, type PackageJsonData, type PackageJsonSettings, ParseError, type ParseErrorCode, type ParseErrorOptions, type ParseResult, type PluginCommandContext, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptEngine, type PromptKind, type PromptResult, type ReadFn, type ResolveOptions, type ResolveResult, type ResolvedArgValue, type ResolvedCommandParams, type ResolvedMultiselectPromptConfig, type ResolvedPromptConfig, type ResolvedSelectPromptConfig, type ResolvedValue, type RunResult, SHELLS, type SelectChoice, type SelectPromptConfig, type Shell, type SpinnerHandle, type SpinnerOptions, type TableColumn, type TableFormat, type TableOptions, type TableStream, type Token, ValidationError, type ValidationErrorCode, type ValidationErrorOptions, type Verbosity, type WithArgPresence, type WithPresence, type WithVariadic, type WriteFn, arg, buildConfigSearchPaths, cli, command, configFormat, createArgSchema, createOutput, createSchema, createTerminalPrompter, discoverConfig, discoverPackageJson, flag, formatHelp, generateBashCompletion, generateCompletion, generateInputSchema, generateSchema, generateZshCompletion, group, inferCliName, isCLIError, isParseError, isValidationError, middleware, parse, plugin, resolve, resolvePromptConfig, tokenize };
|