@kjanat/dreamcli 3.0.0-rc.1 → 3.0.0-rc.3
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 +37 -1
- package/dist/core/cli/dispatch.mjs +214 -1
- package/dist/core/cli/help-links.mjs +41 -1
- package/dist/core/cli/index.mjs +901 -1
- package/dist/core/cli/planner.mjs +300 -1
- package/dist/core/cli/plugin.mjs +41 -1
- package/dist/core/cli/propagate.mjs +57 -1
- package/dist/core/cli/root-help.mjs +208 -4
- package/dist/core/cli/root-surface.mjs +27 -1
- package/dist/core/cli/runtime-preflight.mjs +168 -1
- package/dist/core/completion/index.mjs +90 -1
- package/dist/core/completion/shells/bash.mjs +304 -3
- package/dist/core/completion/shells/fish.mjs +159 -2
- package/dist/core/completion/shells/powershell.mjs +353 -2
- package/dist/core/completion/shells/shared.mjs +154 -1
- package/dist/core/completion/shells/zsh.mjs +244 -2
- package/dist/core/config/index.mjs +246 -1
- package/dist/core/config/package-json.mjs +385 -3
- package/dist/core/errors/index.mjs +87 -1
- package/dist/core/execution/index.mjs +189 -1
- package/dist/core/help/ansi.mjs +122 -2
- package/dist/core/help/index.mjs +329 -7
- package/dist/core/json-schema/index.mjs +487 -9
- package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
- package/dist/core/output/activity.mjs +452 -1
- package/dist/core/output/bind.mjs +56 -1
- package/dist/core/output/contracts.mjs +57 -1
- package/dist/core/output/display-value.mjs +32 -1
- package/dist/core/output/index.d.mts +21 -0
- package/dist/core/output/index.mjs +442 -2
- package/dist/core/output/renderers.mjs +46 -1
- package/dist/core/output/writer.mjs +12 -1
- package/dist/core/parse/index.mjs +555 -1
- package/dist/core/prompt/index.d.mts +0 -1
- package/dist/core/prompt/index.mjs +348 -6
- package/dist/core/resolve/args.mjs +105 -1
- package/dist/core/resolve/coerce.mjs +279 -1
- package/dist/core/resolve/config.mjs +19 -1
- package/dist/core/resolve/errors.mjs +140 -2
- package/dist/core/resolve/flags.mjs +196 -1
- package/dist/core/resolve/index.mjs +85 -1
- package/dist/core/resolve/property.d.mts +0 -1
- package/dist/core/resolve/property.mjs +45 -1
- package/dist/core/schema/arg.mjs +463 -1
- package/dist/core/schema/command.d.mts +18 -0
- package/dist/core/schema/command.mjs +712 -1
- package/dist/core/schema/flag.mjs +453 -1
- package/dist/core/schema/middleware.mjs +41 -1
- package/dist/core/schema/number-constraints.mjs +60 -1
- package/dist/core/schema-dsl/runtime.mjs +271 -2
- package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
- package/dist/core/testkit/index.mjs +83 -1
- package/dist/index.d.mts +2 -1
- package/dist/index.mjs +22 -1
- package/dist/runtime/adapter.mjs +82 -1
- package/dist/runtime/auto.mjs +46 -1
- package/dist/runtime/bun.mjs +28 -1
- package/dist/runtime/deno.mjs +217 -2
- package/dist/runtime/detect.mjs +45 -1
- package/dist/runtime/node.mjs +169 -2
- package/dist/runtime/paths.mjs +48 -1
- package/dist/runtime.mjs +7 -1
- package/dist/strings.mjs +22 -1
- package/dist/testkit.mjs +5 -1
- package/dist/version.d.mts +7 -3
- package/dist/version.mjs +7 -1
- package/package.json +21 -26
- package/src/core/cli/dispatch.ts +0 -355
- package/src/core/cli/help-links.ts +0 -82
- package/src/core/cli/index.ts +0 -1614
- package/src/core/cli/planner.ts +0 -656
- package/src/core/cli/plugin.ts +0 -117
- package/src/core/cli/propagate.ts +0 -97
- package/src/core/cli/root-help.ts +0 -342
- package/src/core/cli/root-surface.ts +0 -87
- package/src/core/cli/runtime-preflight.ts +0 -456
- package/src/core/completion/index.ts +0 -138
- package/src/core/completion/shells/bash.ts +0 -459
- package/src/core/completion/shells/fish.ts +0 -259
- package/src/core/completion/shells/powershell.ts +0 -439
- package/src/core/completion/shells/shared.ts +0 -310
- package/src/core/completion/shells/zsh.ts +0 -381
- package/src/core/config/index.ts +0 -417
- package/src/core/config/package-json.ts +0 -560
- package/src/core/errors/index.ts +0 -193
- package/src/core/execution/index.ts +0 -265
- package/src/core/help/ansi.ts +0 -144
- package/src/core/help/index.ts +0 -563
- package/src/core/json-schema/index.ts +0 -910
- package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
- package/src/core/output/activity.ts +0 -575
- package/src/core/output/bind.ts +0 -59
- package/src/core/output/contracts.ts +0 -194
- package/src/core/output/display-value.ts +0 -48
- package/src/core/output/index.ts +0 -704
- package/src/core/output/renderers.ts +0 -125
- package/src/core/output/writer.ts +0 -46
- package/src/core/parse/index.ts +0 -742
- package/src/core/prompt/index.ts +0 -623
- package/src/core/resolve/args.ts +0 -144
- package/src/core/resolve/coerce.ts +0 -500
- package/src/core/resolve/config.ts +0 -26
- package/src/core/resolve/contracts.ts +0 -135
- package/src/core/resolve/errors.ts +0 -227
- package/src/core/resolve/flags.ts +0 -269
- package/src/core/resolve/index.ts +0 -108
- package/src/core/resolve/property.ts +0 -99
- package/src/core/schema/activity.ts +0 -240
- package/src/core/schema/arg.ts +0 -841
- package/src/core/schema/command.ts +0 -1500
- package/src/core/schema/flag.ts +0 -917
- package/src/core/schema/index.ts +0 -96
- package/src/core/schema/middleware.ts +0 -171
- package/src/core/schema/number-constraints.ts +0 -153
- package/src/core/schema/prompt.ts +0 -171
- package/src/core/schema/run.ts +0 -198
- package/src/core/schema-dsl/index.ts +0 -109
- package/src/core/schema-dsl/parse.ts +0 -262
- package/src/core/schema-dsl/runtime.ts +0 -609
- package/src/core/schema-dsl/to-json-schema.ts +0 -102
- package/src/core/testkit/index.ts +0 -147
- package/src/index.ts +0 -181
- package/src/runtime/adapter.ts +0 -303
- package/src/runtime/auto.ts +0 -86
- package/src/runtime/bun.ts +0 -48
- package/src/runtime/deno.ts +0 -367
- package/src/runtime/detect.ts +0 -105
- package/src/runtime/index.ts +0 -21
- package/src/runtime/node-builtins.d.ts +0 -27
- package/src/runtime/node.ts +0 -289
- package/src/runtime/paths.ts +0 -64
- package/src/runtime/support.ts +0 -77
- package/src/runtime.ts +0 -31
- package/src/schema.ts +0 -16
- package/src/strings.ts +0 -34
- package/src/testkit.ts +0 -25
- package/src/version.ts +0 -20
|
@@ -1,456 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Runtime preflight helpers for CLIBuilder.run().
|
|
3
|
-
*
|
|
4
|
-
* Separates adapter-driven sourcing work from planner and executor logic:
|
|
5
|
-
* config discovery, package metadata discovery, invocation-scoped stdin reads,
|
|
6
|
-
* prompt auto-wiring, and runtime-derived schema overrides.
|
|
7
|
-
*
|
|
8
|
-
* @module dreamcli/core/cli/runtime-preflight
|
|
9
|
-
* @internal
|
|
10
|
-
*/
|
|
11
|
-
|
|
12
|
-
import type { CompletionOptions, Shell } from '#internals/core/completion/index.ts';
|
|
13
|
-
import type { FormatLoader } from '#internals/core/config/index.ts';
|
|
14
|
-
import { discoverConfig } from '#internals/core/config/index.ts';
|
|
15
|
-
import type { PackageJsonData } from '#internals/core/config/package-json.ts';
|
|
16
|
-
import { discoverManifest, inferCliName } from '#internals/core/config/package-json.ts';
|
|
17
|
-
import { CLIError, ParseError } from '#internals/core/errors/index.ts';
|
|
18
|
-
import type { Verbosity } from '#internals/core/output/index.ts';
|
|
19
|
-
import { parse } from '#internals/core/parse/index.ts';
|
|
20
|
-
import type { PromptEngine } from '#internals/core/prompt/index.ts';
|
|
21
|
-
import { createTerminalPrompter } from '#internals/core/prompt/index.ts';
|
|
22
|
-
import type { CommandSchema, ErasedCommand } from '#internals/core/schema/command.ts';
|
|
23
|
-
import type { RuntimeAdapter } from '#internals/runtime/adapter.ts';
|
|
24
|
-
import type { HelpLinks } from './help-links.ts';
|
|
25
|
-
import { deriveHelpLinks } from './help-links.ts';
|
|
26
|
-
import { planInvocation } from './planner.ts';
|
|
27
|
-
import type { CLIPlugin } from './plugin.ts';
|
|
28
|
-
|
|
29
|
-
/** Config discovery settings extracted from CLISchema for preflight use. @internal */
|
|
30
|
-
interface RuntimeConfigSettings {
|
|
31
|
-
/** Application name used to locate config files (e.g. `~/.config/<appName>/`). */
|
|
32
|
-
readonly appName: string;
|
|
33
|
-
/** Optional format loaders (JSON/YAML/TOML); `undefined` uses built-in JSON. */
|
|
34
|
-
readonly loaders: readonly FormatLoader[] | undefined;
|
|
35
|
-
}
|
|
36
|
-
|
|
37
|
-
/**
|
|
38
|
-
* Manifest discovery settings extracted from CLISchema for preflight use.
|
|
39
|
-
*
|
|
40
|
-
* Mirrors the public `ResolvedManifestSettings` shape (consumed structurally),
|
|
41
|
-
* named with the `Runtime` prefix to match its {@link RuntimeConfigSettings}
|
|
42
|
-
* sibling and avoid colliding with the exported public type.
|
|
43
|
-
* @internal
|
|
44
|
-
*/
|
|
45
|
-
interface RuntimeManifestSettings {
|
|
46
|
-
/** Whether to infer the CLI binary name from `bin` keys or `name`. */
|
|
47
|
-
readonly inferName: boolean;
|
|
48
|
-
/** Strip a leading `@scope/` from the inferred `name` fallback. */
|
|
49
|
-
readonly stripScope: boolean;
|
|
50
|
-
/** Explicit anchor (resolved path) for discovery; `undefined` falls back to `adapter.cwd`. */
|
|
51
|
-
readonly from: string | undefined;
|
|
52
|
-
/** Candidate manifest filenames in priority order. */
|
|
53
|
-
readonly files: readonly string[];
|
|
54
|
-
/** Pre-loaded data; when set, discovery is skipped entirely. */
|
|
55
|
-
readonly data: PackageJsonData | undefined;
|
|
56
|
-
}
|
|
57
|
-
|
|
58
|
-
/**
|
|
59
|
-
* Structural subset of CLISchema used by runtime preflight.
|
|
60
|
-
*
|
|
61
|
-
* Decouples adapter-driven sourcing (config, package.json, stdin) from the
|
|
62
|
-
* full CLIBuilder surface so preflight can be tested independently.
|
|
63
|
-
* @internal
|
|
64
|
-
*/
|
|
65
|
-
interface RuntimePreflightSchemaLike {
|
|
66
|
-
/** CLI program name; may be overridden by package.json discovery or inheritance. */
|
|
67
|
-
readonly name: string;
|
|
68
|
-
/** Whether this CLI inherits its name from a parent (nested CLI embedding). */
|
|
69
|
-
readonly inheritName: boolean;
|
|
70
|
-
/** Declared version; `undefined` means version will be inferred from package.json if available. */
|
|
71
|
-
readonly version: string | undefined;
|
|
72
|
-
/** Declared description; `undefined` allows package.json inference. */
|
|
73
|
-
readonly description: string | undefined;
|
|
74
|
-
/** Registered top-level commands for dispatch planning during stdin detection. */
|
|
75
|
-
readonly commands: readonly ErasedCommand[];
|
|
76
|
-
/** Fallback command when no subcommand token matches. */
|
|
77
|
-
readonly defaultCommand: ErasedCommand | undefined;
|
|
78
|
-
/** Config file discovery settings; `undefined` disables config loading. */
|
|
79
|
-
readonly configSettings: RuntimeConfigSettings | undefined;
|
|
80
|
-
/** Package.json discovery settings; `undefined` disables package.json inference. */
|
|
81
|
-
readonly packageJsonSettings: RuntimeManifestSettings | undefined;
|
|
82
|
-
/** Root-help header link targets; `undefined` fields may be derived from package.json. */
|
|
83
|
-
readonly helpLinks: HelpLinks | undefined;
|
|
84
|
-
/** Whether `.completions()` registered the built-in completions command/flag. */
|
|
85
|
-
readonly hasBuiltInCompletions: boolean;
|
|
86
|
-
/** Eager `--completions <shell>` flag config; `undefined` disables interception. */
|
|
87
|
-
readonly completionsFlag:
|
|
88
|
-
| { readonly shells: readonly Shell[]; readonly options: CompletionOptions | undefined }
|
|
89
|
-
| undefined;
|
|
90
|
-
/** Consumer-configured root-help defaults. */
|
|
91
|
-
readonly helpConfig:
|
|
92
|
-
| {
|
|
93
|
-
readonly inlineDefault?: boolean;
|
|
94
|
-
readonly showDefaultInCommands?: boolean;
|
|
95
|
-
readonly footer?: boolean;
|
|
96
|
-
readonly width?: number;
|
|
97
|
-
readonly hyperlinks?: boolean;
|
|
98
|
-
}
|
|
99
|
-
| undefined;
|
|
100
|
-
/** Plugins forwarded into the execution pipeline. */
|
|
101
|
-
readonly plugins: readonly CLIPlugin[];
|
|
102
|
-
}
|
|
103
|
-
|
|
104
|
-
/**
|
|
105
|
-
* Caller-supplied overrides for runtime preflight.
|
|
106
|
-
*
|
|
107
|
-
* When provided, these bypass adapter auto-detection (useful for testing
|
|
108
|
-
* and the `CLIRunOptions` public surface).
|
|
109
|
-
* @internal
|
|
110
|
-
*/
|
|
111
|
-
interface RuntimePreflightOptions {
|
|
112
|
-
/** Environment variables override; bypasses adapter env when set. */
|
|
113
|
-
readonly env?: Readonly<Record<string, string | undefined>>;
|
|
114
|
-
/** Pre-loaded config object; skips config file discovery when set. */
|
|
115
|
-
readonly config?: Readonly<Record<string, unknown>>;
|
|
116
|
-
/** Pre-read stdin data; `null` means stdin was explicitly empty. */
|
|
117
|
-
readonly stdinData?: string | null;
|
|
118
|
-
/** Custom prompt engine; bypasses terminal prompter auto-creation. */
|
|
119
|
-
readonly prompter?: PromptEngine;
|
|
120
|
-
/** Output verbosity level override. */
|
|
121
|
-
readonly verbosity?: Verbosity;
|
|
122
|
-
/** Force JSON output mode regardless of `--json` flag presence. */
|
|
123
|
-
readonly jsonMode?: boolean;
|
|
124
|
-
/** TTY detection override; bypasses adapter TTY check. */
|
|
125
|
-
readonly isTTY?: boolean;
|
|
126
|
-
}
|
|
127
|
-
|
|
128
|
-
/**
|
|
129
|
-
* Fully resolved runtime inputs ready for the execution pipeline.
|
|
130
|
-
*
|
|
131
|
-
* All adapter vs. caller-override decisions are settled by the time this
|
|
132
|
-
* is constructed; the executor treats these as final truth.
|
|
133
|
-
* @internal
|
|
134
|
-
*/
|
|
135
|
-
interface RuntimeExecutionInputs {
|
|
136
|
-
/** Resolved environment variables (from adapter or caller override). */
|
|
137
|
-
readonly env: Readonly<Record<string, string | undefined>>;
|
|
138
|
-
/** Whether stdout is a TTY (controls color, spinners, interactive prompts). */
|
|
139
|
-
readonly isTTY: boolean;
|
|
140
|
-
/** Whether structured JSON output mode is active. */
|
|
141
|
-
readonly jsonMode: boolean;
|
|
142
|
-
/** Output verbosity level. */
|
|
143
|
-
readonly verbosity: Verbosity;
|
|
144
|
-
/** Pre-read stdin data if the invocation declared stdin-mode args. */
|
|
145
|
-
readonly stdinData?: string | null;
|
|
146
|
-
/** Prompt engine for interactive flag resolution; absent in non-TTY. */
|
|
147
|
-
readonly prompter?: PromptEngine;
|
|
148
|
-
/** Loaded config data for the config resolution step. */
|
|
149
|
-
readonly config?: Readonly<Record<string, unknown>>;
|
|
150
|
-
}
|
|
151
|
-
|
|
152
|
-
/** Preflight succeeded — all runtime inputs are resolved and ready for execution. @internal */
|
|
153
|
-
interface ReadyRuntimePreflight {
|
|
154
|
-
/** Discriminant — preflight completed without errors. */
|
|
155
|
-
readonly kind: 'ready';
|
|
156
|
-
/** Schema after package.json discovery and name inheritance applied. */
|
|
157
|
-
readonly schema: RuntimePreflightSchemaLike;
|
|
158
|
-
/** Argv with valid runtime `--config` tokens stripped out. */
|
|
159
|
-
readonly filteredArgv: readonly string[];
|
|
160
|
-
/** Fully resolved runtime inputs for the execution pipeline. */
|
|
161
|
-
readonly inputs: RuntimeExecutionInputs;
|
|
162
|
-
}
|
|
163
|
-
|
|
164
|
-
/** Preflight failed during config file discovery/loading. @internal */
|
|
165
|
-
interface RuntimeConfigErrorPreflight {
|
|
166
|
-
/** Discriminant — config loading produced a structured error. */
|
|
167
|
-
readonly kind: 'config-error';
|
|
168
|
-
/** The config discovery/parse error to render. */
|
|
169
|
-
readonly error: CLIError;
|
|
170
|
-
/** Whether JSON output was requested (needed to choose error rendering). */
|
|
171
|
-
readonly jsonMode: boolean;
|
|
172
|
-
}
|
|
173
|
-
|
|
174
|
-
/** Discriminated union of preflight outcomes — either ready or config-error. @internal */
|
|
175
|
-
type RuntimePreflightResult = ReadyRuntimePreflight | RuntimeConfigErrorPreflight;
|
|
176
|
-
|
|
177
|
-
/** Options bag for {@linkcode prepareRuntimePreflight}. @internal */
|
|
178
|
-
interface PrepareRuntimePreflightOptions {
|
|
179
|
-
/** CLI schema subset driving preflight decisions. */
|
|
180
|
-
readonly schema: RuntimePreflightSchemaLike;
|
|
181
|
-
/** Runtime adapter providing argv, env, stdin, and filesystem access. */
|
|
182
|
-
readonly adapter: RuntimeAdapter;
|
|
183
|
-
/** Caller-supplied overrides; `undefined` means auto-detect everything. */
|
|
184
|
-
readonly options: RuntimePreflightOptions | undefined;
|
|
185
|
-
/** Name inherited from a parent CLI (nested embedding); `undefined` for standalone. */
|
|
186
|
-
readonly inheritedName: string | undefined;
|
|
187
|
-
}
|
|
188
|
-
|
|
189
|
-
const PRECHECK_OUTPUT = {
|
|
190
|
-
jsonMode: false,
|
|
191
|
-
isTTY: false,
|
|
192
|
-
verbosity: 'normal' as const,
|
|
193
|
-
};
|
|
194
|
-
|
|
195
|
-
/** Extract and strip valid runtime `--config` forms from argv, returning path + filtered tokens. @internal */
|
|
196
|
-
function extractConfigFlag(argv: readonly string[]): {
|
|
197
|
-
readonly configPath: string | undefined;
|
|
198
|
-
readonly filteredArgv: readonly string[];
|
|
199
|
-
} {
|
|
200
|
-
const filteredArgv: string[] = [];
|
|
201
|
-
let configPath: string | undefined;
|
|
202
|
-
|
|
203
|
-
for (let i = 0; i < argv.length; i += 1) {
|
|
204
|
-
const arg = argv[i];
|
|
205
|
-
if (arg === undefined) {
|
|
206
|
-
continue;
|
|
207
|
-
}
|
|
208
|
-
|
|
209
|
-
if (arg === '--') {
|
|
210
|
-
filteredArgv.push(...argv.slice(i));
|
|
211
|
-
break;
|
|
212
|
-
}
|
|
213
|
-
|
|
214
|
-
if (configPath === undefined && arg.startsWith('--config=')) {
|
|
215
|
-
const value = arg.slice('--config='.length);
|
|
216
|
-
if (value.length > 0) {
|
|
217
|
-
configPath = value;
|
|
218
|
-
continue;
|
|
219
|
-
}
|
|
220
|
-
|
|
221
|
-
filteredArgv.push(arg);
|
|
222
|
-
continue;
|
|
223
|
-
}
|
|
224
|
-
|
|
225
|
-
if (configPath === undefined && arg === '--config') {
|
|
226
|
-
const nextArg = argv[i + 1];
|
|
227
|
-
if (nextArg !== undefined && !nextArg.startsWith('-') && nextArg !== '--') {
|
|
228
|
-
configPath = nextArg;
|
|
229
|
-
i += 1;
|
|
230
|
-
continue;
|
|
231
|
-
}
|
|
232
|
-
|
|
233
|
-
filteredArgv.push(arg);
|
|
234
|
-
continue;
|
|
235
|
-
}
|
|
236
|
-
|
|
237
|
-
filteredArgv.push(arg);
|
|
238
|
-
}
|
|
239
|
-
|
|
240
|
-
return { configPath, filteredArgv };
|
|
241
|
-
}
|
|
242
|
-
|
|
243
|
-
/** Check whether a single command's args declare stdin-mode and argv leaves them unresolved. @internal */
|
|
244
|
-
function commandInvocationNeedsStdin(schema: CommandSchema, argv: readonly string[]): boolean {
|
|
245
|
-
if (argv.includes('--help') || argv.includes('-h')) {
|
|
246
|
-
return false;
|
|
247
|
-
}
|
|
248
|
-
|
|
249
|
-
try {
|
|
250
|
-
const parsed = parse(schema, argv);
|
|
251
|
-
return schema.args.some(({ name, schema: argSchema }) => {
|
|
252
|
-
const parsedValue = parsed.args[name];
|
|
253
|
-
return argSchema.stdinMode && (parsedValue === undefined || parsedValue === '-');
|
|
254
|
-
});
|
|
255
|
-
} catch (error: unknown) {
|
|
256
|
-
if (error instanceof ParseError) {
|
|
257
|
-
return false;
|
|
258
|
-
}
|
|
259
|
-
throw error;
|
|
260
|
-
}
|
|
261
|
-
}
|
|
262
|
-
|
|
263
|
-
/** Plan the invocation and check whether the matched command needs stdin data. @internal */
|
|
264
|
-
function invocationNeedsStdin(
|
|
265
|
-
schema: RuntimePreflightSchemaLike,
|
|
266
|
-
argv: readonly string[],
|
|
267
|
-
): boolean {
|
|
268
|
-
const plan = planInvocation({
|
|
269
|
-
schema,
|
|
270
|
-
argv,
|
|
271
|
-
help: { binName: schema.name },
|
|
272
|
-
output: PRECHECK_OUTPUT,
|
|
273
|
-
});
|
|
274
|
-
|
|
275
|
-
switch (plan.kind) {
|
|
276
|
-
case 'match':
|
|
277
|
-
return commandInvocationNeedsStdin(plan.plan.mergedSchema, plan.plan.argv);
|
|
278
|
-
case 'dispatch-error':
|
|
279
|
-
case 'needs-subcommand':
|
|
280
|
-
case 'root-help':
|
|
281
|
-
case 'root-version':
|
|
282
|
-
case 'root-completions':
|
|
283
|
-
return false;
|
|
284
|
-
}
|
|
285
|
-
}
|
|
286
|
-
|
|
287
|
-
function isCompletionsInvocation(
|
|
288
|
-
schema: RuntimePreflightSchemaLike,
|
|
289
|
-
argv: readonly string[],
|
|
290
|
-
): boolean {
|
|
291
|
-
if (!schema.hasBuiltInCompletions) {
|
|
292
|
-
return false;
|
|
293
|
-
}
|
|
294
|
-
|
|
295
|
-
const plan = planInvocation({
|
|
296
|
-
schema,
|
|
297
|
-
argv,
|
|
298
|
-
help: { binName: schema.name },
|
|
299
|
-
output: PRECHECK_OUTPUT,
|
|
300
|
-
});
|
|
301
|
-
|
|
302
|
-
return plan.kind === 'match' && plan.plan.command.schema.name === 'completions';
|
|
303
|
-
}
|
|
304
|
-
|
|
305
|
-
async function applyPackageJsonDiscovery(
|
|
306
|
-
schema: RuntimePreflightSchemaLike,
|
|
307
|
-
adapter: RuntimeAdapter,
|
|
308
|
-
inheritedName: string | undefined,
|
|
309
|
-
isCompletions: boolean,
|
|
310
|
-
): Promise<RuntimePreflightSchemaLike> {
|
|
311
|
-
const packageJsonSettings = schema.packageJsonSettings;
|
|
312
|
-
const packageSchema =
|
|
313
|
-
packageJsonSettings !== undefined && !isCompletions
|
|
314
|
-
? await (async (): Promise<RuntimePreflightSchemaLike> => {
|
|
315
|
-
// Pre-loaded data short-circuits filesystem discovery entirely.
|
|
316
|
-
const pkg =
|
|
317
|
-
packageJsonSettings.data ??
|
|
318
|
-
(await discoverManifest(adapter, {
|
|
319
|
-
...(packageJsonSettings.from !== undefined
|
|
320
|
-
? { startDir: packageJsonSettings.from }
|
|
321
|
-
: {}),
|
|
322
|
-
files: packageJsonSettings.files,
|
|
323
|
-
}));
|
|
324
|
-
if (pkg === null) return schema;
|
|
325
|
-
|
|
326
|
-
const inferredName = packageJsonSettings.inferName
|
|
327
|
-
? inferCliName(pkg, { stripScope: packageJsonSettings.stripScope })
|
|
328
|
-
: undefined;
|
|
329
|
-
return {
|
|
330
|
-
...schema,
|
|
331
|
-
...(schema.version === undefined && pkg.version !== undefined
|
|
332
|
-
? { version: pkg.version }
|
|
333
|
-
: {}),
|
|
334
|
-
...(schema.description === undefined && pkg.description !== undefined
|
|
335
|
-
? { description: pkg.description }
|
|
336
|
-
: {}),
|
|
337
|
-
...(inferredName !== undefined ? { name: inferredName } : {}),
|
|
338
|
-
helpLinks: deriveHelpLinks(schema.helpLinks, pkg, schema.version ?? pkg.version),
|
|
339
|
-
};
|
|
340
|
-
})()
|
|
341
|
-
: schema;
|
|
342
|
-
|
|
343
|
-
return inheritedName !== undefined ? { ...packageSchema, name: inheritedName } : packageSchema;
|
|
344
|
-
}
|
|
345
|
-
|
|
346
|
-
async function loadRuntimeConfig(
|
|
347
|
-
schema: RuntimePreflightSchemaLike,
|
|
348
|
-
adapter: RuntimeAdapter,
|
|
349
|
-
configPath: string | undefined,
|
|
350
|
-
isCompletions: boolean,
|
|
351
|
-
existingConfig: Readonly<Record<string, unknown>> | undefined,
|
|
352
|
-
): Promise<Readonly<Record<string, unknown>> | CLIError | undefined> {
|
|
353
|
-
if (schema.configSettings === undefined || isCompletions || existingConfig !== undefined) {
|
|
354
|
-
return existingConfig;
|
|
355
|
-
}
|
|
356
|
-
|
|
357
|
-
try {
|
|
358
|
-
const result = await discoverConfig(schema.configSettings.appName, adapter, {
|
|
359
|
-
...(configPath !== undefined ? { configPath } : {}),
|
|
360
|
-
...(schema.configSettings.loaders !== undefined
|
|
361
|
-
? { loaders: schema.configSettings.loaders }
|
|
362
|
-
: {}),
|
|
363
|
-
});
|
|
364
|
-
return result.found ? result.data : undefined;
|
|
365
|
-
} catch (error: unknown) {
|
|
366
|
-
if (error instanceof CLIError) {
|
|
367
|
-
return error;
|
|
368
|
-
}
|
|
369
|
-
throw error;
|
|
370
|
-
}
|
|
371
|
-
}
|
|
372
|
-
|
|
373
|
-
/**
|
|
374
|
-
* Run all adapter-driven sourcing work before command execution.
|
|
375
|
-
*
|
|
376
|
-
* Discovers config files, reads package.json metadata, detects stdin needs,
|
|
377
|
-
* wires up the prompt engine, and resolves output policy overrides into a
|
|
378
|
-
* single {@linkcode RuntimePreflightResult}.
|
|
379
|
-
* @internal
|
|
380
|
-
*/
|
|
381
|
-
async function prepareRuntimePreflight(
|
|
382
|
-
options: PrepareRuntimePreflightOptions,
|
|
383
|
-
): Promise<RuntimePreflightResult> {
|
|
384
|
-
const rawArgv = options.adapter.argv.slice(2);
|
|
385
|
-
const { configPath, filteredArgv } =
|
|
386
|
-
options.schema.configSettings !== undefined
|
|
387
|
-
? extractConfigFlag(rawArgv)
|
|
388
|
-
: { configPath: undefined, filteredArgv: rawArgv };
|
|
389
|
-
const hasJsonFlag = filteredArgv.includes('--json');
|
|
390
|
-
const jsonMode = hasJsonFlag || options.options?.jsonMode === true;
|
|
391
|
-
const isCompletions = isCompletionsInvocation(options.schema, filteredArgv);
|
|
392
|
-
const schema = await applyPackageJsonDiscovery(
|
|
393
|
-
options.schema,
|
|
394
|
-
options.adapter,
|
|
395
|
-
options.inheritedName,
|
|
396
|
-
isCompletions,
|
|
397
|
-
);
|
|
398
|
-
const loadedConfig = await loadRuntimeConfig(
|
|
399
|
-
schema,
|
|
400
|
-
options.adapter,
|
|
401
|
-
configPath,
|
|
402
|
-
isCompletions,
|
|
403
|
-
options.options?.config,
|
|
404
|
-
);
|
|
405
|
-
|
|
406
|
-
if (loadedConfig instanceof CLIError) {
|
|
407
|
-
return {
|
|
408
|
-
kind: 'config-error',
|
|
409
|
-
error: loadedConfig,
|
|
410
|
-
jsonMode,
|
|
411
|
-
};
|
|
412
|
-
}
|
|
413
|
-
|
|
414
|
-
const autoPrompter =
|
|
415
|
-
options.options?.prompter === undefined && options.adapter.stdinIsTTY
|
|
416
|
-
? createTerminalPrompter(options.adapter.stdin, options.adapter.stderr)
|
|
417
|
-
: undefined;
|
|
418
|
-
const stdinData =
|
|
419
|
-
options.options?.stdinData === undefined && invocationNeedsStdin(schema, filteredArgv)
|
|
420
|
-
? await options.adapter.readStdin()
|
|
421
|
-
: options.options?.stdinData;
|
|
422
|
-
|
|
423
|
-
return {
|
|
424
|
-
kind: 'ready',
|
|
425
|
-
schema,
|
|
426
|
-
filteredArgv,
|
|
427
|
-
inputs: {
|
|
428
|
-
env: options.options?.env ?? options.adapter.env,
|
|
429
|
-
isTTY: options.options?.isTTY ?? options.adapter.isTTY,
|
|
430
|
-
jsonMode,
|
|
431
|
-
verbosity: options.options?.verbosity ?? 'normal',
|
|
432
|
-
...(stdinData !== undefined ? { stdinData } : {}),
|
|
433
|
-
...(options.options?.prompter !== undefined
|
|
434
|
-
? { prompter: options.options.prompter }
|
|
435
|
-
: autoPrompter !== undefined
|
|
436
|
-
? { prompter: autoPrompter }
|
|
437
|
-
: {}),
|
|
438
|
-
...(loadedConfig !== undefined ? { config: loadedConfig } : {}),
|
|
439
|
-
},
|
|
440
|
-
};
|
|
441
|
-
}
|
|
442
|
-
|
|
443
|
-
export type {
|
|
444
|
-
PrepareRuntimePreflightOptions,
|
|
445
|
-
ReadyRuntimePreflight,
|
|
446
|
-
RuntimeExecutionInputs,
|
|
447
|
-
RuntimePreflightOptions,
|
|
448
|
-
RuntimePreflightResult,
|
|
449
|
-
RuntimePreflightSchemaLike,
|
|
450
|
-
};
|
|
451
|
-
export {
|
|
452
|
-
commandInvocationNeedsStdin,
|
|
453
|
-
extractConfigFlag,
|
|
454
|
-
invocationNeedsStdin,
|
|
455
|
-
prepareRuntimePreflight,
|
|
456
|
-
};
|
|
@@ -1,138 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Shell completion script generation from command schemas.
|
|
3
|
-
*
|
|
4
|
-
* Each shell has a dedicated generator in `shells/` that takes a
|
|
5
|
-
* {@link CLISchema} and returns a complete shell-specific completion
|
|
6
|
-
* script as a string. Generators walk the full command tree depth,
|
|
7
|
-
* including propagated flags from ancestor commands at each nesting level.
|
|
8
|
-
*
|
|
9
|
-
* @module dreamcli/core/completion
|
|
10
|
-
*/
|
|
11
|
-
|
|
12
|
-
import type { CLISchema } from '#internals/core/cli/index.ts';
|
|
13
|
-
import { generateBashCompletion } from './shells/bash.ts';
|
|
14
|
-
import { generateFishCompletion } from './shells/fish.ts';
|
|
15
|
-
import { generatePowerShellCompletion } from './shells/powershell.ts';
|
|
16
|
-
import type { CompletionOptions } from './shells/shared.ts';
|
|
17
|
-
import { generateZshCompletion } from './shells/zsh.ts';
|
|
18
|
-
|
|
19
|
-
// --- Shell type — supported completion targets
|
|
20
|
-
|
|
21
|
-
/**
|
|
22
|
-
* Supported shell targets for completion script generation.
|
|
23
|
-
*
|
|
24
|
-
* `bash`, `zsh`, `fish`, and `powershell` are implemented today.
|
|
25
|
-
*/
|
|
26
|
-
type Shell = 'bash' | 'zsh' | 'fish' | 'powershell';
|
|
27
|
-
|
|
28
|
-
/**
|
|
29
|
-
* Implemented shell values as a frozen readonly non-empty tuple.
|
|
30
|
-
*
|
|
31
|
-
* Use this tuple for user-facing validation and shell selection UIs.
|
|
32
|
-
* It intentionally matches the shipped {@link Shell} union exactly so docs,
|
|
33
|
-
* help output, and completion generation advertise the same support surface.
|
|
34
|
-
*
|
|
35
|
-
* @see {@link Shell} for the union type matching these entries.
|
|
36
|
-
*/
|
|
37
|
-
const SHELLS: Readonly<readonly ['bash', 'zsh', 'fish', 'powershell']> = Object.freeze([
|
|
38
|
-
'bash',
|
|
39
|
-
'zsh',
|
|
40
|
-
'fish',
|
|
41
|
-
'powershell',
|
|
42
|
-
] as const satisfies readonly ['bash', 'zsh', 'fish', 'powershell']);
|
|
43
|
-
|
|
44
|
-
// --- Shell token normalization
|
|
45
|
-
|
|
46
|
-
/**
|
|
47
|
-
* Normalize a raw shell token — a bare name (`zsh`), a `$SHELL` path
|
|
48
|
-
* (`/bin/zsh`), or a Windows executable (`…\pwsh.exe`) — to a supported
|
|
49
|
-
* {@link Shell}, or `undefined` when it does not map to one.
|
|
50
|
-
*
|
|
51
|
-
* Mirrors the matching used by the `completions` subcommand so the subcommand
|
|
52
|
-
* and the eager `--completions <shell>` flag accept exactly the same inputs.
|
|
53
|
-
*
|
|
54
|
-
* @param raw - User-supplied shell token or interpreter path.
|
|
55
|
-
* @returns The resolved {@link Shell}, or `undefined` if unrecognized.
|
|
56
|
-
*/
|
|
57
|
-
function normalizeShell(raw: string): Shell | undefined {
|
|
58
|
-
const segments = raw.split(/[\\/]/);
|
|
59
|
-
const basename = segments[segments.length - 1] ?? raw;
|
|
60
|
-
const name = basename.replace(/\.(?:exe|cmd|bat)$/i, '');
|
|
61
|
-
if (name === 'pwsh') return 'powershell';
|
|
62
|
-
return (SHELLS as readonly string[]).includes(name) ? (name as Shell) : undefined;
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
/**
|
|
66
|
-
* Auto-detect the current shell from environment variables.
|
|
67
|
-
*
|
|
68
|
-
* Resolution order:
|
|
69
|
-
* 1. `$SHELL` parsed as an interpreter path (`/bin/zsh` → `zsh`). It wins when
|
|
70
|
-
* it names a shell we support — a pwsh session launched from bash inherits
|
|
71
|
-
* `SHELL=/bin/bash`, and the login shell the user opted into should be
|
|
72
|
-
* honored over the fallback.
|
|
73
|
-
* 2. Otherwise, the presence of `$PSModulePath` signals PowerShell. PowerShell
|
|
74
|
-
* never sets `$SHELL` on any platform but always exports `PSModulePath` for
|
|
75
|
-
* module discovery, so it is the reliable pwsh signal.
|
|
76
|
-
*
|
|
77
|
-
* Returns `undefined` when no signal resolves, leaving the caller to ask the
|
|
78
|
-
* user for an explicit shell.
|
|
79
|
-
*
|
|
80
|
-
* @param env - Environment record (e.g. `process.env` or an adapter's env).
|
|
81
|
-
* @returns The detected {@link Shell}, or `undefined`.
|
|
82
|
-
*/
|
|
83
|
-
function detectShell(env: Readonly<Record<string, string | undefined>>): Shell | undefined {
|
|
84
|
-
const shellVar = env.SHELL;
|
|
85
|
-
const fromShell =
|
|
86
|
-
shellVar !== undefined && shellVar !== '' ? normalizeShell(shellVar) : undefined;
|
|
87
|
-
if (fromShell !== undefined) return fromShell;
|
|
88
|
-
if (env.PSModulePath !== undefined) return 'powershell';
|
|
89
|
-
return undefined;
|
|
90
|
-
}
|
|
91
|
-
|
|
92
|
-
// --- Shell-agnostic dispatch
|
|
93
|
-
|
|
94
|
-
/**
|
|
95
|
-
* Generate a completion script for the given shell.
|
|
96
|
-
*
|
|
97
|
-
* This is the primary completion entrypoint for most consumers. Pass a CLI
|
|
98
|
-
* schema and target shell, then write the returned script to a file or source
|
|
99
|
-
* it directly from the command line.
|
|
100
|
-
*
|
|
101
|
-
* @param schema - The CLI schema describing commands, flags, and args.
|
|
102
|
-
* @param shell - Target shell.
|
|
103
|
-
* @param options - Optional generator configuration such as function naming
|
|
104
|
-
* and root default-command completion behavior.
|
|
105
|
-
* @returns A complete shell completion script as a string.
|
|
106
|
-
*
|
|
107
|
-
* @example
|
|
108
|
-
* ```ts
|
|
109
|
-
* const script = generateCompletion(app.schema, 'bash');
|
|
110
|
-
* // e.g. source <(mycli completions bash)
|
|
111
|
-
* ```
|
|
112
|
-
*/
|
|
113
|
-
function generateCompletion(schema: CLISchema, shell: Shell, options?: CompletionOptions): string {
|
|
114
|
-
switch (shell) {
|
|
115
|
-
case 'bash':
|
|
116
|
-
return generateBashCompletion(schema, options);
|
|
117
|
-
case 'zsh':
|
|
118
|
-
return generateZshCompletion(schema, options);
|
|
119
|
-
case 'fish':
|
|
120
|
-
return generateFishCompletion(schema, options);
|
|
121
|
-
case 'powershell':
|
|
122
|
-
return generatePowerShellCompletion(schema, options);
|
|
123
|
-
}
|
|
124
|
-
}
|
|
125
|
-
|
|
126
|
-
// --- Exports
|
|
127
|
-
|
|
128
|
-
export type { CompletionOptions, Shell };
|
|
129
|
-
export {
|
|
130
|
-
generateBashCompletion,
|
|
131
|
-
generateCompletion,
|
|
132
|
-
generateFishCompletion,
|
|
133
|
-
generatePowerShellCompletion,
|
|
134
|
-
generateZshCompletion,
|
|
135
|
-
detectShell,
|
|
136
|
-
normalizeShell,
|
|
137
|
-
SHELLS,
|
|
138
|
-
};
|