@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
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
import { ConfirmPromptConfig, InputPromptConfig, PromptConfig, PromptResult, SelectChoice } from "../schema/prompt.mjs";
|
|
2
|
+
import { WriteFn } from "../output/writer.mjs";
|
|
3
|
+
|
|
4
|
+
//#region src/core/prompt/index.d.ts
|
|
5
|
+
/**
|
|
6
|
+
* A select prompt config with choices guaranteed non-empty.
|
|
7
|
+
*
|
|
8
|
+
* The resolution chain populates choices from `FlagSchema.enumValues`
|
|
9
|
+
* when the user's {@linkcode PromptConfig} omits them.
|
|
10
|
+
*/
|
|
11
|
+
interface ResolvedSelectPromptConfig {
|
|
12
|
+
/** Discriminant — single-choice selection prompt. */
|
|
13
|
+
readonly kind: 'select';
|
|
14
|
+
/** User-facing question text. */
|
|
15
|
+
readonly message: string;
|
|
16
|
+
/** Non-empty list of selectable options (populated from flag enum values when omitted). */
|
|
17
|
+
readonly choices: readonly [SelectChoice, ...SelectChoice[]];
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* A multiselect prompt config with choices guaranteed non-empty.
|
|
21
|
+
*
|
|
22
|
+
* Same guarantee as {@linkcode ResolvedSelectPromptConfig} — choices are always
|
|
23
|
+
* present and non-empty.
|
|
24
|
+
*/
|
|
25
|
+
interface ResolvedMultiselectPromptConfig {
|
|
26
|
+
/** Discriminant — multiple-choice selection prompt. */
|
|
27
|
+
readonly kind: 'multiselect';
|
|
28
|
+
/** User-facing question text. */
|
|
29
|
+
readonly message: string;
|
|
30
|
+
/** Non-empty list of selectable options (populated from flag enum values when omitted). */
|
|
31
|
+
readonly choices: readonly [SelectChoice, ...SelectChoice[]];
|
|
32
|
+
/** Minimum number of selections required (validated after input). */
|
|
33
|
+
readonly min?: number;
|
|
34
|
+
/** Maximum number of selections allowed (validated after input). */
|
|
35
|
+
readonly max?: number;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Prompt config variant where select/multiselect choices are guaranteed
|
|
39
|
+
* present. The prompt engine receives this (not raw {@linkcode PromptConfig}),
|
|
40
|
+
* so it never needs to merge enum values from `FlagSchema`.
|
|
41
|
+
*
|
|
42
|
+
* confirm and input configs pass through unchanged.
|
|
43
|
+
*/
|
|
44
|
+
type ResolvedPromptConfig = ConfirmPromptConfig | InputPromptConfig | ResolvedSelectPromptConfig | ResolvedMultiselectPromptConfig;
|
|
45
|
+
/**
|
|
46
|
+
* Prompt engine interface.
|
|
47
|
+
*
|
|
48
|
+
* Implementations render a single prompt to the user and return the
|
|
49
|
+
* result. The engine is stateless per call — each `promptOne` is
|
|
50
|
+
* independent.
|
|
51
|
+
*
|
|
52
|
+
* The resolution chain calls `promptOne` for each flag that needs
|
|
53
|
+
* interactive input. Engines do not need schema knowledge — all
|
|
54
|
+
* relevant context (message, choices, validation) is in the config.
|
|
55
|
+
*
|
|
56
|
+
* @example
|
|
57
|
+
* ```ts
|
|
58
|
+
* // Custom engine (e.g. wrapping @clack/prompts)
|
|
59
|
+
* const engine: PromptEngine = {
|
|
60
|
+
* async promptOne(config) {
|
|
61
|
+
* // ... render with your library
|
|
62
|
+
* return { answered: true, value: userInput };
|
|
63
|
+
* }
|
|
64
|
+
* };
|
|
65
|
+
* ```
|
|
66
|
+
*/
|
|
67
|
+
interface PromptEngine {
|
|
68
|
+
/**
|
|
69
|
+
* Present a single prompt and return the user's response.
|
|
70
|
+
*
|
|
71
|
+
* @param config - The resolved prompt configuration (choices guaranteed
|
|
72
|
+
* for select/multiselect).
|
|
73
|
+
* @returns The user's answer, or `{ answered: false }` if cancelled.
|
|
74
|
+
*/
|
|
75
|
+
promptOne(config: ResolvedPromptConfig): Promise<PromptResult>;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* A function that reads a single line of user input.
|
|
79
|
+
*
|
|
80
|
+
* Returns `null` on EOF (Ctrl+D on Unix, Ctrl+Z on Windows),
|
|
81
|
+
* indicating the user closed the input stream (treated as cancel).
|
|
82
|
+
*
|
|
83
|
+
* The terminal prompter uses this as its sole input seam. The
|
|
84
|
+
* resolution chain (prompt-adapter-1) will wire this to the
|
|
85
|
+
* runtime adapter's stdin.
|
|
86
|
+
*/
|
|
87
|
+
type ReadFn = () => Promise<string | null>;
|
|
88
|
+
/**
|
|
89
|
+
* Sentinel value representing a cancelled/aborted prompt in the test
|
|
90
|
+
* prompter's answer queue.
|
|
91
|
+
*
|
|
92
|
+
* Uses `Symbol.for()` for cross-bundle safety — the same symbol is
|
|
93
|
+
* returned regardless of which copy of the module is loaded.
|
|
94
|
+
*
|
|
95
|
+
* @example
|
|
96
|
+
* ```ts
|
|
97
|
+
* const prompter = createTestPrompter([
|
|
98
|
+
* 'us', // first prompt answered 'us'
|
|
99
|
+
* PROMPT_CANCEL, // second prompt cancelled
|
|
100
|
+
* ]);
|
|
101
|
+
* ```
|
|
102
|
+
*/
|
|
103
|
+
declare const PROMPT_CANCEL: unique symbol;
|
|
104
|
+
/**
|
|
105
|
+
* A queued answer consumed by {@link createTestPrompter}.
|
|
106
|
+
*
|
|
107
|
+
* The test prompter returns these values exactly as provided; it does not
|
|
108
|
+
* coerce or validate them. The normal resolution pipeline performs any later
|
|
109
|
+
* type coercion, so tests can supply values in the same shapes real prompts
|
|
110
|
+
* would yield:
|
|
111
|
+
*
|
|
112
|
+
* - `string` for `input` and `select`
|
|
113
|
+
* - `boolean` for `confirm`
|
|
114
|
+
* - `string[]` for `multiselect`
|
|
115
|
+
* - `PROMPT_CANCEL` to simulate user cancellation
|
|
116
|
+
*
|
|
117
|
+
* Because the type is intentionally `unknown`, tests may also inject malformed
|
|
118
|
+
* answers to exercise downstream validation and error reporting.
|
|
119
|
+
*/
|
|
120
|
+
type TestAnswer = unknown;
|
|
121
|
+
/**
|
|
122
|
+
* Options for `createTestPrompter`.
|
|
123
|
+
*/
|
|
124
|
+
interface TestPrompterOptions {
|
|
125
|
+
/**
|
|
126
|
+
* Behavior when all answers have been consumed.
|
|
127
|
+
*
|
|
128
|
+
* - `'throw'` (default) — throws an error, making the test fail
|
|
129
|
+
* loudly if more prompts fire than expected.
|
|
130
|
+
* - `'cancel'` — returns `{ answered: false }`, simulating the
|
|
131
|
+
* user cancelling all subsequent prompts.
|
|
132
|
+
*/
|
|
133
|
+
readonly onExhausted?: 'throw' | 'cancel';
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* Create a prompt engine that returns pre-configured answers.
|
|
137
|
+
*
|
|
138
|
+
* Each call to `promptOne` consumes the next answer from the queue.
|
|
139
|
+
* Pass `PROMPT_CANCEL` as an answer to simulate the user cancelling
|
|
140
|
+
* that prompt.
|
|
141
|
+
*
|
|
142
|
+
* @param answers - Ordered queue of answers. Use `PROMPT_CANCEL` for
|
|
143
|
+
* cancellation.
|
|
144
|
+
* @param options - Controls behavior when the queue is exhausted.
|
|
145
|
+
* @returns A {@linkcode PromptEngine} suitable for testing.
|
|
146
|
+
*
|
|
147
|
+
* @example
|
|
148
|
+
* ```ts
|
|
149
|
+
* const prompter = createTestPrompter(['eu', true, PROMPT_CANCEL]);
|
|
150
|
+
*
|
|
151
|
+
* // First promptOne → { answered: true, value: 'eu' }
|
|
152
|
+
* // Second promptOne → { answered: true, value: true }
|
|
153
|
+
* // Third promptOne → { answered: false }
|
|
154
|
+
* ```
|
|
155
|
+
*/
|
|
156
|
+
declare function createTestPrompter(answers: readonly TestAnswer[], options?: TestPrompterOptions): PromptEngine;
|
|
157
|
+
/**
|
|
158
|
+
* Create a prompt engine backed by line-based terminal I/O.
|
|
159
|
+
*
|
|
160
|
+
* Uses a {@linkcode ReadFn} for input and a {@linkcode WriteFn} for output. This is the
|
|
161
|
+
* built-in renderer — sufficient for most CLI use cases. For richer
|
|
162
|
+
* TUI experiences, users can implement {@linkcode PromptEngine} with a library
|
|
163
|
+
* like `@clack/prompts` or `inquirer`.
|
|
164
|
+
*
|
|
165
|
+
* The prompter does **not** use raw mode — all input is line-based.
|
|
166
|
+
* This keeps the implementation portable across Node, Bun, and Deno
|
|
167
|
+
* without platform-specific stdin configuration.
|
|
168
|
+
*
|
|
169
|
+
* @param read - Line reader function (returns `null` on EOF)
|
|
170
|
+
* @param write - Output writer function
|
|
171
|
+
* @returns A {@linkcode PromptEngine} that prompts via terminal I/O
|
|
172
|
+
*
|
|
173
|
+
* @example
|
|
174
|
+
* ```ts
|
|
175
|
+
* import { createInterface } from 'readline';
|
|
176
|
+
*
|
|
177
|
+
* const rl = createInterface({ input: process.stdin, output: process.stdout });
|
|
178
|
+
* const read = () => new Promise<string | null>((resolve) => {
|
|
179
|
+
* rl.question('', (answer) => resolve(answer));
|
|
180
|
+
* });
|
|
181
|
+
* const write: WriteFn = (s) => process.stdout.write(s);
|
|
182
|
+
*
|
|
183
|
+
* const prompter = createTerminalPrompter(read, write);
|
|
184
|
+
* ```
|
|
185
|
+
*/
|
|
186
|
+
declare function createTerminalPrompter(read: ReadFn, write: WriteFn): PromptEngine;
|
|
187
|
+
/**
|
|
188
|
+
* Prepare a {@linkcode ResolvedPromptConfig} from a raw {@linkcode PromptConfig} and optional
|
|
189
|
+
* enum values from the flag schema.
|
|
190
|
+
*
|
|
191
|
+
* For select/multiselect prompts without explicit choices, this merges
|
|
192
|
+
* the flag's enum values into the choices list. Throws if no choices
|
|
193
|
+
* are available.
|
|
194
|
+
*
|
|
195
|
+
* This function is called by the resolution chain (prompt-resolve-1),
|
|
196
|
+
* not by the engine itself — keeping the engine free of schema knowledge.
|
|
197
|
+
*
|
|
198
|
+
* @param config - Raw prompt config from `FlagSchema.prompt`
|
|
199
|
+
* @param enumValues - Optional enum values from `FlagSchema.enumValues`
|
|
200
|
+
* @returns Resolved config with choices guaranteed for select kinds
|
|
201
|
+
* @throws Error if select/multiselect has no choices and no enum values
|
|
202
|
+
*/
|
|
203
|
+
declare function resolvePromptConfig(config: PromptConfig, enumValues: readonly string[] | undefined): ResolvedPromptConfig;
|
|
204
|
+
//#endregion
|
|
205
|
+
export { PROMPT_CANCEL, type PromptEngine, type ReadFn, type ResolvedMultiselectPromptConfig, type ResolvedPromptConfig, type ResolvedSelectPromptConfig, type TestAnswer, type TestPrompterOptions, createTerminalPrompter, createTestPrompter, resolvePromptConfig };
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
const e=Symbol.for(`dreamcli.prompt.cancel`);function t(t,n){let r=0;return{promptOne(){if(r>=t.length)return n?.onExhausted===`cancel`?Promise.resolve({answered:!1}):Promise.reject(Error(`Test prompter exhausted: expected at most ${t.length} prompts, got prompt #${r+1}`));let i=t[r];return r+=1,i===e?Promise.resolve({answered:!1}):Promise.resolve({answered:!0,value:i})}}}function n(e,t){return{promptOne(n){switch(n.kind){case`confirm`:return r(n,e,t);case`input`:return i(n,e,t);case`select`:return a(n,e,t);case`multiselect`:return o(n,e,t)}}}}async function r(e,t,n){let r=0;for(;r<10;){n(`${e.message} (Y/n) `);let i=await t();if(i===null)return{answered:!1};let a=i.trim().toLowerCase();if(a===``||a===`y`||a===`yes`)return{answered:!0,value:!0};if(a===`n`||a===`no`)return{answered:!0,value:!1};n(`Please answer y or n.
|
|
2
|
+
`),r+=1}return n(`Too many invalid attempts.
|
|
3
|
+
`),{answered:!1}}async function i(e,t,n){let r=0;for(;r<10;){let i=e.placeholder===void 0?``:` (${e.placeholder})`;n(`${e.message}${i}: `);let a=await t();if(a===null)return{answered:!1};let o=a.trim();if(e.validate!==void 0){let t=e.validate(o);if(t!==!0){n(`${t}\n`),r+=1;continue}}return{answered:!0,value:o}}return n(`Too many invalid attempts.
|
|
4
|
+
`),{answered:!1}}async function a(e,t,n){let r=0;for(;r<10;){n(`${e.message}\n`);for(let t=0;t<e.choices.length;t+=1){let r=e.choices[t];if(r===void 0)continue;let i=r.label??r.value,a=r.description===void 0?``:` - ${r.description}`;n(` ${t+1}) ${i}${a}\n`)}n(`Enter number: `);let i=await t();if(i===null)return{answered:!1};let a=Number(i.trim());if(Number.isNaN(a)||!Number.isInteger(a)||a<1||a>e.choices.length){n(`Please enter a number between 1 and ${e.choices.length}.\n`),r+=1;continue}let o=e.choices[a-1];if(o===void 0){r+=1;continue}return{answered:!0,value:o.value}}return n(`Too many invalid attempts.
|
|
5
|
+
`),{answered:!1}}async function o(e,t,n){let r=0;for(;r<10;){n(`${e.message}\n`);for(let t=0;t<e.choices.length;t+=1){let r=e.choices[t];if(r===void 0)continue;let i=r.label??r.value,a=r.description===void 0?``:` - ${r.description}`;n(` ${t+1}) ${i}${a}\n`)}n(`Enter numbers separated by commas (e.g. 1,3${e.min===void 0?``:`, min: ${e.min}`}${e.max===void 0?``:`, max: ${e.max}`}): `);let i=await t();if(i===null)return{answered:!1};let a=i.trim();if(a===``){if(e.min!==void 0&&e.min>0){n(`Please select at least ${e.min}.\n`),r+=1;continue}return{answered:!0,value:[]}}let o=a.split(`,`).map(e=>e.trim()),s=[],c=!0;for(let t of o){let r=Number(t);if(Number.isNaN(r)||!Number.isInteger(r)||r<1||r>e.choices.length){n(`Invalid selection '${t}'. Use numbers between 1 and ${e.choices.length}.\n`),c=!1;break}s.push(r)}if(!c){r+=1;continue}let l=[...new Set(s)];if(e.min!==void 0&&l.length<e.min){n(`Please select at least ${e.min}.\n`),r+=1;continue}if(e.max!==void 0&&l.length>e.max){n(`Please select at most ${e.max}.\n`),r+=1;continue}return{answered:!0,value:l.map(t=>e.choices[t-1]?.value??``)}}return n(`Too many invalid attempts.
|
|
6
|
+
`),{answered:!1}}function s(e,t){if(e.kind===`confirm`||e.kind===`input`)return e;let n=e.choices??t?.map(e=>({value:e}))??[];if(n.length===0)throw Error(`Prompt config (${e.kind}) requires choices but none were provided and no enum values are available`);let r=n;return e.kind===`select`?{kind:`select`,message:e.message,choices:r}:{kind:`multiselect`,message:e.message,choices:r,...e.min===void 0?{}:{min:e.min},...e.max===void 0?{}:{max:e.max}}}export{e as PROMPT_CANCEL,n as createTerminalPrompter,t as createTestPrompter,s as resolvePromptConfig};
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { DeprecationWarning } from "./contracts.mjs";
|
|
2
|
+
import { CommandArgEntry } from "../schema/command.mjs";
|
|
3
|
+
|
|
4
|
+
//#region src/core/resolve/args.d.ts
|
|
5
|
+
/** Walk every declared arg through the resolution chain (cli -> stdin -> env -> default), collecting deprecations and throwing aggregated errors. */
|
|
6
|
+
declare function resolveArgs(argEntries: readonly CommandArgEntry[], parsedArgs: Readonly<Record<string, unknown>>, stdinData: string | null | undefined, env: Readonly<Record<string, string | undefined>>, deprecations: DeprecationWarning[]): Readonly<Record<string, unknown>>;
|
|
7
|
+
//#endregion
|
|
8
|
+
export { resolveArgs };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{ValidationError as e}from"../errors/index.mjs";import{coerceArgStringValue as t}from"./coerce.mjs";import{isNonEmpty as n,throwAggregatedErrors as r}from"./errors.mjs";function i(i,o,s,c,l){let u={},d=[];for(let n of i){let{name:r,schema:i}=n,f=Object.hasOwn(o,r),p=o[r];if(f&&p!==void 0&&(!i.stdinMode||p!==`-`)&&!(i.variadic&&Array.isArray(p)&&p.length===0)){i.deprecated!==void 0&&l.push({kind:`arg`,name:r,message:i.deprecated}),u[r]=p;continue}if(i.stdinMode&&(!f||p===void 0||p===`-`)&&s!=null){let e=t(r,{kind:`stdin`},s,i);if(e.ok){i.deprecated!==void 0&&l.push({kind:`arg`,name:r,message:i.deprecated}),u[r]=e.value;continue}d.push(e.error);continue}if(i.envVar!==void 0){let e=c[i.envVar];if(e!==void 0){let n=t(r,{kind:`env`,envVar:i.envVar},e,i);if(n.ok){i.deprecated!==void 0&&l.push({kind:`arg`,name:r,message:i.deprecated}),u[r]=n.value;continue}d.push(n.error);continue}}if(i.defaultValue!==void 0){u[r]=i.defaultValue;continue}if(i.variadic){if(i.presence===`required`){d.push(new e(`Missing required argument <${r}>`,{code:`REQUIRED_ARG`,details:{arg:r,variadic:!0},suggest:a(r,i,!0)}));continue}u[r]=[];continue}if(i.presence===`required`){d.push(new e(`Missing required argument <${r}>`,{code:`REQUIRED_ARG`,details:{arg:r},suggest:a(r,i)}));continue}u[r]=void 0}return n(d)&&r(d),u}function a(e,t,n){let r=[n?`Provide at least one value for <${e}>`:`Provide a value for <${e}>`];return t.stdinMode&&r.push(`pipe a value to stdin or pass '-'`),t.envVar!==void 0&&r.push(`set ${t.envVar}`),r.length===1?r[0]:r.length===2?`${r[0]} or ${r[1]}`:`${r.slice(0,-1).join(`, `)}, or ${r[r.length-1]}`}export{i as resolveArgs};
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { ArgSchema } from "../schema/arg.mjs";
|
|
2
|
+
import { FlagSchema } from "../schema/flag.mjs";
|
|
3
|
+
import { ArgDiagnosticSource, FlagDiagnosticSource } from "./contracts.mjs";
|
|
4
|
+
import { ValidationError } from "../errors/index.mjs";
|
|
5
|
+
|
|
6
|
+
//#region src/core/resolve/coerce.d.ts
|
|
7
|
+
type CoerceSource = FlagDiagnosticSource;
|
|
8
|
+
/** Discriminated result of a value coercion attempt — success with the coerced value, or failure with a structured validation error. */
|
|
9
|
+
type CoerceResult = {
|
|
10
|
+
readonly ok: true;
|
|
11
|
+
readonly value: unknown;
|
|
12
|
+
} | {
|
|
13
|
+
readonly ok: false;
|
|
14
|
+
readonly error: ValidationError;
|
|
15
|
+
};
|
|
16
|
+
/** Coerce a raw value from env/config/prompt into the type declared by a flag schema. */
|
|
17
|
+
declare function coerceValue(flagName: string, source: CoerceSource, raw: unknown, schema: FlagSchema): CoerceResult;
|
|
18
|
+
type ArgStringSource = ArgDiagnosticSource;
|
|
19
|
+
/** Coerce a string value from stdin/env into the type declared by an arg schema, redacting raw values in error diagnostics. */
|
|
20
|
+
declare function coerceArgStringValue(argName: string, source: ArgStringSource, raw: string, schema: ArgSchema): CoerceResult;
|
|
21
|
+
//#endregion
|
|
22
|
+
export { type CoerceResult, coerceArgStringValue, coerceValue };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{ValidationError as e}from"../errors/index.mjs";import{toSharedArgPropertySchema as t,toSharedFlagPropertySchema as n}from"./property.mjs";function r(e){switch(e.kind){case`env`:return`from env ${e.envVar}`;case`config`:return`from config ${e.configPath}`;case`prompt`:return`from prompt`}}function i(e){switch(e.kind){case`env`:return{envVar:e.envVar};case`config`:return{configPath:e.configPath};case`prompt`:return{source:`prompt`}}}function a(t,n,a,o,s,c,l,u){return{ok:!1,error:new e(`${c} ${r(n)} for flag --${t}`,{code:a,details:{flag:t,...i(n),value:s,expected:o,...u},suggest:l})}}function o(e,t,r,i){let c=n(i);if(c!==void 0)return s(e,t,r,c);switch(i.kind){case`boolean`:if(typeof r==`boolean`)return{ok:!0,value:r};if(typeof r==`string`){let e=r.toLowerCase();if(e===`true`||e===`1`||e===`yes`||t.kind===`prompt`&&e===`y`)return{ok:!0,value:!0};if(e===`false`||e===`0`||e===`no`||e===``||t.kind===`prompt`&&e===`n`)return{ok:!0,value:!1}}return a(e,t,`TYPE_MISMATCH`,`boolean`,r,typeof r==`string`?`Invalid boolean value '${r}'`:`Invalid boolean value`,t.kind===`env`?`Set ${t.envVar} to true/false, 1/0, or yes/no`:t.kind===`config`?`Set ${t.configPath} to true or false in your config`:`Answer yes or no for --${e}`);case`array`:if(Array.isArray(r)){if(i.elementSchema){let n=[];for(let a of r){let r=o(e,t,a,i.elementSchema);if(!r.ok)return r;n.push(r.value)}return{ok:!0,value:n}}return{ok:!0,value:r}}if(typeof r==`string`){if(r===``)return{ok:!0,value:[]};let n=r.split(`,`);if(i.elementSchema){let r=[];for(let a of n){let n=o(e,t,t.kind===`prompt`?a.trim():a,i.elementSchema);if(!n.ok)return n;r.push(n.value)}return{ok:!0,value:r}}return{ok:!0,value:t.kind===`prompt`?n.map(e=>e.trim()):n}}return a(e,t,`TYPE_MISMATCH`,`array`,r,`Invalid array value`,t.kind===`env`?`Set ${t.envVar} to comma-separated values`:t.kind===`config`?`Set ${t.configPath} to an array in your config`:`Provide valid values for --${e}`)}throw Error(`Unreachable flag coercion kind: ${i.kind}`)}function s(t,n,o,s){switch(s.kind){case`string`:return typeof o==`string`?{ok:!0,value:o}:n.kind===`prompt`||n.kind===`config`&&(typeof o==`number`||typeof o==`boolean`)?{ok:!0,value:String(o)}:a(t,n,`TYPE_MISMATCH`,`string`,o,`Invalid string value`,n.kind===`config`?`Set ${n.configPath} to a string in your config`:`Enter a valid string for --${t}`);case`number`:if(typeof o==`number`)return Number.isNaN(o)?a(t,n,`TYPE_MISMATCH`,`number`,o,`Invalid number value NaN`,n.kind===`env`?`Set ${n.envVar} to a valid number`:n.kind===`config`?`Set ${n.configPath} to a valid number in your config`:`Enter a valid number for --${t}`):{ok:!0,value:o};if(typeof o==`string`){let e=Number(o);if(!Number.isNaN(e))return{ok:!0,value:e}}return a(t,n,`TYPE_MISMATCH`,`number`,o,typeof o==`string`?`Invalid number value '${o}'`:`Invalid number value`,n.kind===`env`?`Set ${n.envVar} to a valid number`:n.kind===`config`?`Set ${n.configPath} to a valid number in your config`:`Enter a valid number for --${t}`);case`enum`:{let a=s.enumValues??[];return typeof o==`string`&&a.includes(o)?{ok:!0,value:o}:{ok:!1,error:new e(`Invalid value '${String(o)}' ${r(n)} for flag --${t}. Allowed: ${a.join(`, `)}`,{code:`INVALID_ENUM`,details:{flag:t,...i(n),value:o,allowed:a},suggest:n.kind===`env`?`Set ${n.envVar} to one of: ${a.join(`, `)}`:n.kind===`config`?`Set ${n.configPath} to one of: ${a.join(`, `)}`:`Select one of: ${a.join(`, `)}`})}}case`custom`:if(s.parseFn===void 0)return{ok:!0,value:o};try{return{ok:!0,value:s.parseFn(o)}}catch(r){let a=r instanceof Error?r.message:String(r);return{ok:!1,error:new e(`Failed to parse ${n.kind===`env`?`env ${n.envVar}`:n.kind===`config`?`config ${n.configPath}`:`prompt value`} for flag --${t}: ${a}`,{code:`TYPE_MISMATCH`,details:{flag:t,...i(n),value:o,expected:`custom`},suggest:n.kind===`env`?`Set ${n.envVar} to a valid value for --${t}`:n.kind===`config`?`Set ${n.configPath} to a valid value for --${t} in your config`:`Enter a valid value for --${t}`})}}}}function c(e){return e.kind===`env`?`from env ${e.envVar}`:`from stdin`}function l(e){return e.kind===`env`?{envVar:e.envVar}:{source:`stdin`}}function u(e,t,n){return t.kind===`env`?n===`number`?`Set ${t.envVar} to a valid number`:`Set ${t.envVar} to a valid value for <${e}>`:n===`number`?`Pipe a valid number to stdin for <${e}>`:`Pipe a valid value to stdin for <${e}>`}function d(e){return e.kind===`env`?{kind:`env`,envVar:e.envVar}:{kind:`prompt`}}function f(e,t,n,r){switch(n.kind){case`number`:return`Invalid number value '<redacted>' ${c(t)} for argument <${e}>`;case`enum`:{let n=Array.isArray(r.details?.allowed)?r.details.allowed.filter(e=>typeof e==`string`):[];return`Invalid value '<redacted>' ${c(t)} for argument <${e}>. Allowed: ${n.join(`, `)}`}case`custom`:{let n=/: ([^:]+)$/.exec(r.message)?.[1];return n===void 0?`Invalid value '<redacted>' ${c(t)} for argument <${e}>`:`Invalid value '<redacted>' ${c(t)} for argument <${e}>: ${n}`}case`string`:return`Invalid value '<redacted>' ${c(t)} for argument <${e}>`;default:return n.kind}}function p(e,t,n,r){return{arg:e,...l(t),...n.kind===`number`||n.kind===`custom`?{expected:n.kind}:{},...n.kind===`enum`&&Array.isArray(r.details?.allowed)?{allowed:r.details.allowed.filter(e=>typeof e==`string`)}:{}}}function m(e,t,n,r){if(n.kind===`number`||n.kind===`custom`)return u(e,t,n.kind);if(n.kind===`enum`){let e=(Array.isArray(r.details?.allowed)?r.details.allowed.filter(e=>typeof e==`string`):[]).join(`, `);return t.kind===`env`?`Set ${t.envVar} to one of: ${e}`:`Provide one of: ${e}`}}function h(n,r,i,a){let o=s(n,d(r),i,t(a));if(o.ok)return o;let c=m(n,r,a,o.error),l=c===void 0?{code:o.error.code,details:p(n,r,a,o.error)}:{code:o.error.code,details:p(n,r,a,o.error),suggest:c};return{ok:!1,error:new e(f(n,r,a,o.error),l)}}export{h as coerceArgStringValue,o as coerceValue};
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
//#region src/core/resolve/config.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* Internal resolver config helpers.
|
|
4
|
+
*
|
|
5
|
+
* @module dreamcli/core/resolve/config
|
|
6
|
+
* @internal
|
|
7
|
+
*/
|
|
8
|
+
declare function resolveConfigPath(config: Readonly<Record<string, unknown>>, path: string): unknown;
|
|
9
|
+
//#endregion
|
|
10
|
+
export { resolveConfigPath };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
function e(e,t){let n=t.split(`.`),r=e;for(let e of n){if(typeof r!=`object`||!r||!Object.hasOwn(r,e))return;r=r[e]}return r}export{e as resolveConfigPath};
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
import { ParseResult } from "../parse/index.mjs";
|
|
2
|
+
import { PromptEngine } from "../prompt/index.mjs";
|
|
3
|
+
import { CommandSchema } from "../schema/command.mjs";
|
|
4
|
+
|
|
5
|
+
//#region src/core/resolve/contracts.d.ts
|
|
6
|
+
/** Ordered flag resolution stages owned by the resolver. */
|
|
7
|
+
declare const FLAG_RESOLUTION_ORDER: readonly ['cli', 'env', 'config', 'prompt', 'default'];
|
|
8
|
+
/** Ordered arg resolution stages owned by the resolver. */
|
|
9
|
+
declare const ARG_RESOLUTION_ORDER: readonly ['cli', 'stdin', 'env', 'default'];
|
|
10
|
+
/** Stable flag-source labels for precedence and diagnostics. */
|
|
11
|
+
type FlagResolutionStage = (typeof FLAG_RESOLUTION_ORDER)[number];
|
|
12
|
+
/** Stable arg-source labels for precedence and diagnostics. */
|
|
13
|
+
type ArgResolutionStage = (typeof ARG_RESOLUTION_ORDER)[number];
|
|
14
|
+
/**
|
|
15
|
+
* Source-aware diagnostic context for flag resolution failures.
|
|
16
|
+
*
|
|
17
|
+
* CLI/default failures currently surface as missing-value validation errors,
|
|
18
|
+
* so only env/config/prompt need explicit source payloads here.
|
|
19
|
+
*/
|
|
20
|
+
type FlagDiagnosticSource = {
|
|
21
|
+
readonly kind: 'env';
|
|
22
|
+
readonly envVar: string;
|
|
23
|
+
} | {
|
|
24
|
+
readonly kind: 'config';
|
|
25
|
+
readonly configPath: string;
|
|
26
|
+
} | {
|
|
27
|
+
readonly kind: 'prompt';
|
|
28
|
+
};
|
|
29
|
+
/** Source-aware diagnostic context for arg resolution failures. */
|
|
30
|
+
type ArgDiagnosticSource = {
|
|
31
|
+
readonly kind: 'env';
|
|
32
|
+
readonly envVar: string;
|
|
33
|
+
} | {
|
|
34
|
+
readonly kind: 'stdin';
|
|
35
|
+
};
|
|
36
|
+
/**
|
|
37
|
+
* External state the resolver may consult after parsing.
|
|
38
|
+
*
|
|
39
|
+
* The resolver never reaches into `process`, files, or terminal APIs directly;
|
|
40
|
+
* callers inject those facts through this contract.
|
|
41
|
+
*/
|
|
42
|
+
interface ResolveOptions {
|
|
43
|
+
/** Pre-read stdin content, or `null` when stdin was not piped. */
|
|
44
|
+
readonly stdinData?: string | null;
|
|
45
|
+
/** Environment variable snapshot injected by the caller. */
|
|
46
|
+
readonly env?: Readonly<Record<string, string | undefined>>;
|
|
47
|
+
/** Parsed config file contents keyed by dotted path segments. */
|
|
48
|
+
readonly config?: Readonly<Record<string, unknown>>;
|
|
49
|
+
/** Interactive prompt engine; absent in non-TTY / CI contexts. */
|
|
50
|
+
readonly prompter?: PromptEngine;
|
|
51
|
+
}
|
|
52
|
+
/** Structured deprecation notice emitted for explicitly sourced values. */
|
|
53
|
+
interface DeprecationWarning {
|
|
54
|
+
/** Whether this deprecation targets a flag or a positional arg. */
|
|
55
|
+
readonly kind: 'flag' | 'arg';
|
|
56
|
+
/** Name of the deprecated flag or arg. */
|
|
57
|
+
readonly name: string;
|
|
58
|
+
/** Custom deprecation message, or `true` for the generic warning. */
|
|
59
|
+
readonly message: string | true;
|
|
60
|
+
}
|
|
61
|
+
/** Fully resolved command input handed to the executor layer. */
|
|
62
|
+
interface ResolveResult {
|
|
63
|
+
/** Fully resolved flag values keyed by flag name. */
|
|
64
|
+
readonly flags: Readonly<Record<string, unknown>>;
|
|
65
|
+
/** Fully resolved positional arg values keyed by arg name. */
|
|
66
|
+
readonly args: Readonly<Record<string, unknown>>;
|
|
67
|
+
/** Deprecation notices collected during resolution (may be empty). */
|
|
68
|
+
readonly deprecations: readonly DeprecationWarning[];
|
|
69
|
+
}
|
|
70
|
+
/** Explicit invocation boundary between parser output and resolved values. */
|
|
71
|
+
interface ResolverInvocation {
|
|
72
|
+
/** Command schema that declares flags, args, and resolution metadata. */
|
|
73
|
+
readonly schema: CommandSchema;
|
|
74
|
+
/** Raw parse result from the tokenizer/parser layer. */
|
|
75
|
+
readonly parsed: ParseResult;
|
|
76
|
+
/** Optional external state (env, config, stdin, prompter). */
|
|
77
|
+
readonly options?: ResolveOptions;
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Stable resolver facts the re-foundation workstream is treating as contract.
|
|
81
|
+
*
|
|
82
|
+
* These are intended to anchor focused contract tests before larger module
|
|
83
|
+
* extraction and diagnostic redesign work lands.
|
|
84
|
+
*/
|
|
85
|
+
interface ResolverContract {
|
|
86
|
+
/** Ordered stages for flag resolution: cli -> env -> config -> prompt -> default. */
|
|
87
|
+
readonly flagPrecedence: readonly FlagResolutionStage[];
|
|
88
|
+
/** Ordered stages for arg resolution: cli -> stdin -> env -> default. */
|
|
89
|
+
readonly argPrecedence: readonly ArgResolutionStage[];
|
|
90
|
+
/** Prompt stage runs only after env and config have been attempted. */
|
|
91
|
+
readonly promptRunsAfterFlagConfig: true;
|
|
92
|
+
/** All validation errors are collected before throwing a single aggregate. */
|
|
93
|
+
readonly aggregatesValidationErrors: true;
|
|
94
|
+
/** Aggregate error details include per-issue structured summaries. */
|
|
95
|
+
readonly aggregateDiagnosticsIncludePerIssueSummary: true;
|
|
96
|
+
/** A coercion failure at env/config stops fallback to later stages for that flag. */
|
|
97
|
+
readonly hardCoercionErrorsStopFallback: true;
|
|
98
|
+
/** Deprecation warnings are emitted only when a value was actually sourced. */
|
|
99
|
+
readonly collectsDeprecationsFromExplicitSources: true;
|
|
100
|
+
}
|
|
101
|
+
/** Runtime-accessible resolution contract — documents the resolver's invariants for tests and diagnostics. */
|
|
102
|
+
declare const resolverContract: {
|
|
103
|
+
flagPrecedence: readonly ["cli", "env", "config", "prompt", "default"];
|
|
104
|
+
argPrecedence: readonly ["cli", "stdin", "env", "default"];
|
|
105
|
+
promptRunsAfterFlagConfig: true;
|
|
106
|
+
aggregatesValidationErrors: true;
|
|
107
|
+
aggregateDiagnosticsIncludePerIssueSummary: true;
|
|
108
|
+
hardCoercionErrorsStopFallback: true;
|
|
109
|
+
collectsDeprecationsFromExplicitSources: true;
|
|
110
|
+
};
|
|
111
|
+
//#endregion
|
|
112
|
+
export { ARG_RESOLUTION_ORDER, type ArgDiagnosticSource, type ArgResolutionStage, type DeprecationWarning, FLAG_RESOLUTION_ORDER, type FlagDiagnosticSource, type FlagResolutionStage, type ResolveOptions, type ResolveResult, type ResolverContract, type ResolverInvocation, resolverContract };
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { ValidationError } from "../errors/index.mjs";
|
|
2
|
+
|
|
3
|
+
//#region src/core/resolve/errors.d.ts
|
|
4
|
+
/** Type-narrowing guard that asserts a readonly array has at least one element. */
|
|
5
|
+
declare function isNonEmpty<T>(arr: readonly T[]): arr is readonly [T, ...T[]];
|
|
6
|
+
/** Flatten an aggregate validation error's nested `details.errors` into individual errors, or return the original as a singleton. */
|
|
7
|
+
declare function collectValidationErrors(error: ValidationError): readonly ValidationError[];
|
|
8
|
+
/** Throw a single error if one, or an aggregate with per-issue summaries if many. */
|
|
9
|
+
declare function throwAggregatedErrors(errors: readonly [ValidationError, ...ValidationError[]]): never;
|
|
10
|
+
//#endregion
|
|
11
|
+
export { collectValidationErrors, isNonEmpty, throwAggregatedErrors };
|
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
import{ValidationError as e}from"../errors/index.mjs";function t(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function n(e,t){let n=Reflect.get(e,t);return typeof n==`string`?n:void 0}function r(e,t){return Object.hasOwn(e,t)}function i(e){let t=n(e,`source`);if(t===`stdin`)return{kind:`stdin`,label:`stdin`};if(t===`prompt`)return{kind:`prompt`,label:`prompt`};if(r(e,`value`)){let t=n(e,`envVar`);if(t!==void 0)return{kind:`env`,label:`env ${t}`};let r=n(e,`configPath`);if(r!==void 0)return{kind:`config`,label:`config ${r}`}}}function a(e){let r=e.details;if(!t(r))return{code:e.code,inputKind:`input`,label:`input`,message:e.message};let a=n(r,`flag`);if(a!==void 0){let t=i(r);return{code:e.code,inputKind:`flag`,name:a,label:`flag --${a}`,message:e.message,...t===void 0?{}:{sourceKind:t.kind,sourceLabel:t.label}}}let o=n(r,`arg`);if(o!==void 0){let t=i(r);return{code:e.code,inputKind:`arg`,name:o,label:`argument <${o}>`,message:e.message,...t===void 0?{}:{sourceKind:t.kind,sourceLabel:t.label}}}return{code:e.code,inputKind:`input`,label:`input`,message:e.message}}function o(e){let t=e.filter(e=>e.inputKind===`flag`).length,n=e.filter(e=>e.inputKind===`arg`).length,r=e.length-t-n,i=[];return t>0&&i.push(`${t} flag${t===1?``:`s`}`),n>0&&i.push(`${n} arg${n===1?``:`s`}`),r>0&&i.push(`${r} input${r===1?``:`s`}`),i.length===0?`Multiple validation errors (${e.length})`:`Multiple validation errors (${i.join(`, `)})`}function s(e){let t=e.sourceLabel===void 0?``:` [${e.sourceLabel}]`;return`${e.label}${t}: ${e.message}`}function c(e){return e.length>0}function l(e){return!(typeof e!=`object`||!e||!(`code`in e)||!(`message`in e)||!(`exitCode`in e)||typeof e.code!=`string`||typeof e.message!=`string`||typeof e.exitCode!=`number`||`suggest`in e&&e.suggest!==void 0&&typeof e.suggest!=`string`||`details`in e&&e.details!==void 0&&(e.details===null||typeof e.details!=`object`))}function u(t){let n=t.details?.errors;if(!Array.isArray(n))return[t];let r=[];for(let i of n){if(!l(i))return[t];r.push(new e(i.message,{code:i.code,exitCode:i.exitCode,...i.suggest===void 0?{}:{suggest:i.suggest},...i.details===void 0?{}:{details:i.details}}))}return r}function d(t){if(t.length===1)throw t[0];let n=t.map(a),r=n.map(s);throw new e(`${o(n)}:\n - ${r.join(`
|
|
2
|
+
- `)}`,{code:t[0].code,details:{errors:t.map(e=>e.toJSON()),count:t.length,issues:n},suggest:`Fix the listed validation errors and retry`})}export{u as collectValidationErrors,c as isNonEmpty,d as throwAggregatedErrors};
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { FlagSchema } from "../schema/flag.mjs";
|
|
2
|
+
import { PromptEngine } from "../prompt/index.mjs";
|
|
3
|
+
import { DeprecationWarning } from "./contracts.mjs";
|
|
4
|
+
import { ErasedInteractiveResolver } from "../schema/command.mjs";
|
|
5
|
+
|
|
6
|
+
//#region src/core/resolve/flags.d.ts
|
|
7
|
+
/** Walk every declared flag through the resolution chain (cli -> env -> config -> prompt -> default), collecting deprecations and throwing aggregated errors. */
|
|
8
|
+
declare function resolveFlags(flagSchemas: Readonly<Record<string, FlagSchema>>, parsedFlags: Readonly<Record<string, unknown>>, env: Readonly<Record<string, string | undefined>>, config: Readonly<Record<string, unknown>>, prompter: PromptEngine | undefined, interactive: ErasedInteractiveResolver | undefined, deprecations: DeprecationWarning[]): Promise<Readonly<Record<string, unknown>>>;
|
|
9
|
+
//#endregion
|
|
10
|
+
export { resolveFlags };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{ValidationError as e}from"../errors/index.mjs";import{resolvePromptConfig as t}from"../prompt/index.mjs";import{coerceValue as n}from"./coerce.mjs";import{isNonEmpty as r,throwAggregatedErrors as i}from"./errors.mjs";import{resolveConfigPath as a}from"./config.mjs";async function o(t,o,l,u,d,f,p){let m={},h=[],g=new Set;for(let[e,r]of Object.entries(t)){let t=Object.hasOwn(o,e),i=o[e];if(t&&i!==void 0){r.deprecated!==void 0&&p.push({kind:`flag`,name:e,message:r.deprecated}),m[e]=i;continue}if(r.envVar!==void 0){let t=l[r.envVar];if(t!==void 0){let i=n(e,{kind:`env`,envVar:r.envVar},t,r);if(i.ok){r.deprecated!==void 0&&p.push({kind:`flag`,name:e,message:r.deprecated}),m[e]=i.value;continue}h.push(i.error),g.add(e);continue}}if(r.configPath!==void 0){let t=a(u,r.configPath);if(t!==void 0){let i=n(e,{kind:`config`,configPath:r.configPath},t,r);if(i.ok){r.deprecated!==void 0&&p.push({kind:`flag`,name:e,message:r.deprecated}),m[e]=i.value;continue}h.push(i.error),g.add(e)}}}let _=f===void 0?void 0:f({flags:m});for(let[n,r]of Object.entries(t)){if(Object.hasOwn(m,n)||g.has(n))continue;let t=_?.[n],i;if(i=t!=null&&t!==!1&&t!==0&&t!==``?t:t===!1?void 0:r.prompt,i!==void 0&&d!==void 0){let e=await s(n,r,i,d);if(e.ok){r.deprecated!==void 0&&p.push({kind:`flag`,name:n,message:r.deprecated}),m[n]=e.value;continue}if(e.error!==void 0){h.push(e.error);continue}}if(r.defaultValue!==void 0){m[n]=r.defaultValue;continue}if(r.kind===`array`&&r.presence!==`required`){m[n]=[];continue}if(r.presence===`required`){let t={flag:n,kind:r.kind};r.envVar!==void 0&&(t.envVar=r.envVar),r.configPath!==void 0&&(t.configPath=r.configPath),h.push(new e(`Missing required flag --${n}`,{code:`REQUIRED_FLAG`,details:t,suggest:c(n,r)}));continue}m[n]=void 0}return r(h)&&i(h),m}async function s(e,r,i,a){let o=t(i,r.enumValues),s=await a.promptOne(o);return s.answered?n(e,{kind:`prompt`},s.value,r):{ok:!1,error:void 0}}function c(e,t){let n=[];if(n.push(`Provide --${e}${t.kind===`boolean`?``:` <value>`}`),t.envVar!==void 0&&n.push(`set ${t.envVar}`),t.configPath!==void 0&&n.push(`add ${t.configPath} to config`),n.length<=1)return n.join(``);let r=n.slice(0,-1),i=n.slice(-1).join(``);return n.length===2?`${r.join(``)} or ${i}`:`${r.join(`, `)}, or ${i}`}export{o as resolveFlags};
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import { ParseResult } from "../parse/index.mjs";
|
|
2
|
+
import { DeprecationWarning, ResolveOptions, ResolveResult } from "./contracts.mjs";
|
|
3
|
+
import { CommandSchema } from "../schema/command.mjs";
|
|
4
|
+
|
|
5
|
+
//#region src/core/resolve/index.d.ts
|
|
6
|
+
/**
|
|
7
|
+
* Resolve parsed values against a command schema.
|
|
8
|
+
*
|
|
9
|
+
* Low-level API: most applications should rely on `cli().run()`, `.execute()`,
|
|
10
|
+
* or `runCommand()`, which already call {@linkcode resolve} at the right time.
|
|
11
|
+
* Reach for this function when testing precedence rules directly or building
|
|
12
|
+
* custom execution flows around {@linkcode CommandSchema}.
|
|
13
|
+
*
|
|
14
|
+
* Resolution order:
|
|
15
|
+
* 1. CLI parsed value (from {@linkcode ParseResult})
|
|
16
|
+
* 2. Env variable (from {@linkcode ResolveOptions.env}, if flag declares `envVar`)
|
|
17
|
+
* 3. Config value (from {@linkcode ResolveOptions.config}, if flag declares `configPath`)
|
|
18
|
+
* 4. Prompt (from {@linkcode ResolveOptions.prompter}, if flag declares `prompt`)
|
|
19
|
+
* 5. Default value (from schema)
|
|
20
|
+
*
|
|
21
|
+
* After resolution, validates that all required flags and args have
|
|
22
|
+
* a value. Collects **all** validation errors before throwing, so the
|
|
23
|
+
* user sees every missing field at once.
|
|
24
|
+
*
|
|
25
|
+
* @param schema - The command schema defining flags and args
|
|
26
|
+
* @param parsed - Raw parsed values from the parser
|
|
27
|
+
* @param options - External state for the resolution chain
|
|
28
|
+
* @returns Fully resolved flag and arg values
|
|
29
|
+
* @throws {@linkcode ValidationError} if any required flag or arg is missing,
|
|
30
|
+
* or if an env/config value fails coercion
|
|
31
|
+
*
|
|
32
|
+
* @example
|
|
33
|
+
* ```ts
|
|
34
|
+
* const parsed = parse(deploy.schema, ['production']);
|
|
35
|
+
* const resolved = await resolve(deploy.schema, parsed, {
|
|
36
|
+
* env: { DEPLOY_REGION: 'eu' },
|
|
37
|
+
* });
|
|
38
|
+
* ```
|
|
39
|
+
*/
|
|
40
|
+
declare function resolve(schema: CommandSchema, parsed: ParseResult, options?: ResolveOptions): Promise<ResolveResult>;
|
|
41
|
+
//#endregion
|
|
42
|
+
export { type DeprecationWarning, type ResolveOptions, type ResolveResult, resolve };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{isValidationError as e}from"../errors/index.mjs";import{collectValidationErrors as t,isNonEmpty as n,throwAggregatedErrors as r}from"./errors.mjs";import{resolveArgs as i}from"./args.mjs";import{resolveFlags as a}from"./flags.mjs";async function o(o,s,c){let l=c?.stdinData,u=c?.env??{},d=c?.config??{},f=c?.prompter,p=[],m={},h={},g=[];try{m=await a(o.flags,s.flags,u,d,f,o.interactive,p)}catch(n){if(!e(n))throw n;g.push(...t(n))}try{h=i(o.args,s.args,l,u,p)}catch(n){if(!e(n))throw n;g.push(...t(n))}return n(g)&&r(g),{flags:m,args:h,deprecations:p}}export{o as resolve};
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { ArgSchema } from "../schema/arg.mjs";
|
|
2
|
+
import { FlagSchema } from "../schema/flag.mjs";
|
|
3
|
+
|
|
4
|
+
//#region src/core/resolve/property.d.ts
|
|
5
|
+
/** Flag/arg kinds that share a common coercion path. */
|
|
6
|
+
declare const SHARED_PROPERTY_MODEL_KINDS: readonly ['string', 'number', 'enum', 'custom'];
|
|
7
|
+
/** Union of kind discriminants that participate in shared coercion. */
|
|
8
|
+
type SharedPropertyKind = (typeof SHARED_PROPERTY_MODEL_KINDS)[number];
|
|
9
|
+
/** Minimal coercion-relevant slice of a flag or arg schema, discriminated by kind. */
|
|
10
|
+
type SharedPropertySchema = {
|
|
11
|
+
readonly kind: 'string';
|
|
12
|
+
} | {
|
|
13
|
+
readonly kind: 'number';
|
|
14
|
+
} | {
|
|
15
|
+
readonly kind: 'enum';
|
|
16
|
+
readonly enumValues: readonly string[] | undefined;
|
|
17
|
+
} | {
|
|
18
|
+
readonly kind: 'custom';
|
|
19
|
+
readonly parseFn?: (raw: unknown) => unknown;
|
|
20
|
+
};
|
|
21
|
+
/** Contract asserting which concerns are shared vs. kept separate between flags and args. */
|
|
22
|
+
interface SharedPropertyModelContract {
|
|
23
|
+
/** Only coercion logic is shared; resolution orchestration is not. */
|
|
24
|
+
readonly scope: 'coercion';
|
|
25
|
+
/** The kind discriminants that participate in shared coercion. */
|
|
26
|
+
readonly sharedKinds: readonly SharedPropertyKind[];
|
|
27
|
+
/** Flag and arg precedence chains remain independent. */
|
|
28
|
+
readonly keepsFlagAndArgPrecedenceSeparate: true;
|
|
29
|
+
/** Fallback-on-coercion-error rules remain independent. */
|
|
30
|
+
readonly keepsFallbackRulesSeparate: true;
|
|
31
|
+
/** Required-value validation remains independent. */
|
|
32
|
+
readonly keepsRequiredValueRulesSeparate: true;
|
|
33
|
+
}
|
|
34
|
+
/** Runtime-accessible contract instance for property model tests. */
|
|
35
|
+
declare const sharedPropertyModelContract: {
|
|
36
|
+
scope: "coercion";
|
|
37
|
+
sharedKinds: readonly ["string", "number", "enum", "custom"];
|
|
38
|
+
keepsFlagAndArgPrecedenceSeparate: true;
|
|
39
|
+
keepsFallbackRulesSeparate: true;
|
|
40
|
+
keepsRequiredValueRulesSeparate: true;
|
|
41
|
+
};
|
|
42
|
+
/** Extract the shared coercion slice from a flag schema, or `undefined` for boolean/array (handled separately). */
|
|
43
|
+
declare function toSharedFlagPropertySchema(schema: FlagSchema): SharedPropertySchema | undefined;
|
|
44
|
+
/** Extract the shared coercion slice from an arg schema (all arg kinds are shared). */
|
|
45
|
+
declare function toSharedArgPropertySchema(schema: ArgSchema): SharedPropertySchema;
|
|
46
|
+
//#endregion
|
|
47
|
+
export { SHARED_PROPERTY_MODEL_KINDS, type SharedPropertyKind, type SharedPropertyModelContract, type SharedPropertySchema, sharedPropertyModelContract, toSharedArgPropertySchema, toSharedFlagPropertySchema };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
function e(e){switch(e.kind){case`string`:return{kind:`string`};case`number`:return{kind:`number`};case`enum`:return{kind:`enum`,enumValues:e.enumValues};case`custom`:return e.parseFn===void 0?{kind:`custom`}:{kind:`custom`,parseFn:e.parseFn};case`boolean`:case`array`:return}}function t(e){switch(e.kind){case`string`:return{kind:`string`};case`number`:return{kind:`number`};case`enum`:return{kind:`enum`,enumValues:e.enumValues};case`custom`:{if(e.parseFn===void 0)return{kind:`custom`};let t=e.parseFn;return{kind:`custom`,parseFn:e=>t(typeof e==`string`?e:String(e))}}}}export{t as toSharedArgPropertySchema,e as toSharedFlagPropertySchema};
|