@kjanat/dreamcli 0.0.0 → 1.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 +667 -0
- package/LICENSE +22 -0
- package/README.md +370 -0
- package/dist/adapter-B37d9oia.mjs +1 -0
- package/dist/adapter-CCSh5juX.cjs +1 -0
- package/dist/adapter-DIwO-q7K.d.mts +3447 -0
- package/dist/adapter-DQnxxLiE.d.cts +3447 -0
- package/dist/auto-5cjZaF9V.mjs +3 -0
- package/dist/auto-B0eSgoDw.cjs +3 -0
- package/dist/index.cjs +10 -0
- package/dist/index.d.cts +920 -0
- package/dist/index.d.mts +920 -0
- package/dist/index.mjs +10 -0
- package/dist/runtime.cjs +1 -0
- package/dist/runtime.d.cts +253 -0
- package/dist/runtime.d.mts +253 -0
- package/dist/runtime.mjs +1 -0
- package/dist/testkit-CEDYPvhF.mjs +14 -0
- package/dist/testkit-ClIKijxC.cjs +14 -0
- package/dist/testkit.cjs +1 -0
- package/dist/testkit.d.cts +25 -0
- package/dist/testkit.d.mts +25 -0
- package/dist/testkit.mjs +1 -0
- package/examples/basic.ts +33 -0
- package/examples/gh/package.json +48 -0
- package/examples/gh/src/commands/auth.ts +66 -0
- package/examples/gh/src/commands/issue.ts +120 -0
- package/examples/gh/src/commands/pr.ts +125 -0
- package/examples/gh/src/data/issues.yaml +5 -0
- package/examples/gh/src/data/issues.yaml.d.ts +17 -0
- package/examples/gh/src/data/pull-requests.yaml +7 -0
- package/examples/gh/src/data/pull-requests.yaml.d.ts +18 -0
- package/examples/gh/src/lib/auth.ts +37 -0
- package/examples/gh/src/lib/utils.ts +17 -0
- package/examples/gh/src/main.test.ts +306 -0
- package/examples/gh/src/main.ts +38 -0
- package/examples/gh/tsconfig.json +37 -0
- package/examples/interactive.ts +66 -0
- package/examples/json-mode.ts +93 -0
- package/examples/middleware.ts +71 -0
- package/examples/multi-command.ts +66 -0
- package/examples/spinner-progress.ts +49 -0
- package/examples/testing.ts +145 -0
- package/examples/tsconfig.json +17 -0
- package/package.json +123 -2
- package/src/core/cli/AGENTS.md +72 -0
- package/src/core/cli/dispatch.ts +282 -0
- package/src/core/cli/index.ts +1425 -0
- package/src/core/cli/plugin.ts +111 -0
- package/src/core/cli/propagate.ts +97 -0
- package/src/core/cli/root-help.ts +269 -0
- package/src/core/cli/root-surface.ts +74 -0
- package/src/core/completion/AGENTS.md +72 -0
- package/src/core/completion/completion-test-helpers.ts +48 -0
- package/src/core/completion/index.ts +82 -0
- package/src/core/completion/shells/bash.ts +456 -0
- package/src/core/completion/shells/fish.ts +24 -0
- package/src/core/completion/shells/powershell.ts +24 -0
- package/src/core/completion/shells/shared.ts +283 -0
- package/src/core/completion/shells/zsh.ts +376 -0
- package/src/core/config/index.ts +404 -0
- package/src/core/config/package-json.ts +216 -0
- package/src/core/errors/index.ts +178 -0
- package/src/core/help/index.ts +559 -0
- package/src/core/json-schema/index.ts +705 -0
- package/src/core/output/AGENTS.md +69 -0
- package/src/core/output/activity.ts +568 -0
- package/src/core/output/display-value.ts +48 -0
- package/src/core/output/index.ts +704 -0
- package/src/core/output/writer.ts +46 -0
- package/src/core/parse/index.ts +643 -0
- package/src/core/prompt/index.ts +566 -0
- package/src/core/resolve/AGENTS.md +69 -0
- package/src/core/resolve/index.ts +1331 -0
- package/src/core/schema/AGENTS.md +61 -0
- package/src/core/schema/activity.ts +237 -0
- package/src/core/schema/arg.ts +707 -0
- package/src/core/schema/command.ts +1263 -0
- package/src/core/schema/flag.ts +651 -0
- package/src/core/schema/index.ts +82 -0
- package/src/core/schema/middleware.ts +171 -0
- package/src/core/schema/prompt.ts +148 -0
- package/src/core/schema/run.ts +187 -0
- package/src/core/testkit/AGENTS.md +55 -0
- package/src/core/testkit/index.ts +365 -0
- package/src/index.ts +164 -0
- package/src/runtime/AGENTS.md +74 -0
- package/src/runtime/adapter.ts +300 -0
- package/src/runtime/auto.ts +110 -0
- package/src/runtime/bun.ts +55 -0
- package/src/runtime/deno.ts +355 -0
- package/src/runtime/detect.ts +102 -0
- package/src/runtime/index.ts +21 -0
- package/src/runtime/node-builtins.d.ts +23 -0
- package/src/runtime/node.ts +278 -0
- package/src/runtime/paths.ts +56 -0
- package/src/runtime/support.ts +119 -0
- package/src/runtime/test-helpers.ts +40 -0
- package/src/runtime.ts +31 -0
- package/src/testkit.ts +23 -0
- package/src/version.ts +20 -0
|
@@ -0,0 +1,651 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Flag schema builder with full type inference.
|
|
3
|
+
*
|
|
4
|
+
* Each factory (`flag.string()`, `flag.boolean()`, etc.) returns an immutable
|
|
5
|
+
* `FlagBuilder` whose generic parameter tracks the value type and presence
|
|
6
|
+
* state. Chained modifiers (`.default()`, `.required()`, `.alias()`, …) return
|
|
7
|
+
* new builders with updated type-level and runtime state.
|
|
8
|
+
*
|
|
9
|
+
* @module dreamcli/core/schema/flag
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import type { PromptConfig } from './prompt.ts';
|
|
13
|
+
|
|
14
|
+
// --- Type-level configuration (phantom state tracked through the chain)
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Presence describes whether a flag value is guaranteed to exist when the
|
|
18
|
+
* action handler runs:
|
|
19
|
+
*
|
|
20
|
+
* - `'optional'` — not required; unresolved value follows the kind-specific
|
|
21
|
+
* optional fallback (`undefined` for most flags, `[]` for arrays)
|
|
22
|
+
* - `'required'` — must be supplied; error if missing
|
|
23
|
+
* - `'defaulted'` — always present (falls back to default value)
|
|
24
|
+
*/
|
|
25
|
+
type FlagPresence = 'optional' | 'required' | 'defaulted';
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Fallback behavior when an optional flag resolves no value from any source.
|
|
29
|
+
*
|
|
30
|
+
* Most optional flags resolve to `undefined`; array flags instead resolve to
|
|
31
|
+
* an empty array `[]`.
|
|
32
|
+
*/
|
|
33
|
+
type OptionalFallback = 'undefined' | 'empty-array';
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Compile-time state carried through the builder chain.
|
|
37
|
+
*
|
|
38
|
+
* Adding new tracked properties only requires extending this interface — no
|
|
39
|
+
* builder signature changes.
|
|
40
|
+
*/
|
|
41
|
+
interface FlagConfig {
|
|
42
|
+
/** The resolved value type (e.g. `string`, `number`, `'us' | 'eu'`). */
|
|
43
|
+
readonly valueType: unknown;
|
|
44
|
+
/** Whether the flag is optional, required, or has a default. */
|
|
45
|
+
readonly presence: FlagPresence;
|
|
46
|
+
/** What an unresolved optional flag becomes at the action boundary. */
|
|
47
|
+
readonly optionalFallback: OptionalFallback;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
// --- Type-level helpers
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* Advanced type helper used by `FlagBuilder` modifiers to replace presence.
|
|
54
|
+
* Most consumers rely on inference and never reference this directly.
|
|
55
|
+
*/
|
|
56
|
+
type WithPresence<C extends FlagConfig, P extends FlagPresence> = {
|
|
57
|
+
readonly valueType: C['valueType'];
|
|
58
|
+
readonly presence: P;
|
|
59
|
+
readonly optionalFallback: C['optionalFallback'];
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Compute the final value type from config — this is what handlers receive.
|
|
64
|
+
*
|
|
65
|
+
* Advanced type helper: this powers {@link InferFlag} and action-handler
|
|
66
|
+
* inference. Most apps do not need to mention it explicitly.
|
|
67
|
+
*
|
|
68
|
+
* - `'optional'` + `'undefined'` fallback → `T | undefined`
|
|
69
|
+
* - `'optional'` + `'empty-array'` fallback → `T`
|
|
70
|
+
* - `'required'` → `T`
|
|
71
|
+
* - `'defaulted'` → `T`
|
|
72
|
+
*/
|
|
73
|
+
type ResolvedValue<C extends FlagConfig> = C['presence'] extends 'optional'
|
|
74
|
+
? C['optionalFallback'] extends 'empty-array'
|
|
75
|
+
? C['valueType']
|
|
76
|
+
: C['valueType'] | undefined
|
|
77
|
+
: C['valueType'];
|
|
78
|
+
|
|
79
|
+
/** Extract the resolved value type from a `FlagBuilder`. */
|
|
80
|
+
type InferFlag<B> = B extends FlagBuilder<infer C extends FlagConfig> ? ResolvedValue<C> : never;
|
|
81
|
+
|
|
82
|
+
/** Extract resolved value types from a record of builders. */
|
|
83
|
+
type InferFlags<T extends Record<string, FlagBuilder<FlagConfig>>> = {
|
|
84
|
+
[K in keyof T]: InferFlag<T[K]>;
|
|
85
|
+
};
|
|
86
|
+
|
|
87
|
+
// --- Runtime schema data
|
|
88
|
+
|
|
89
|
+
/** Discriminator for the kind of value a flag accepts. */
|
|
90
|
+
type FlagKind = 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'custom';
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* Custom parse function for `flag.custom()`.
|
|
94
|
+
*
|
|
95
|
+
* Receives `string` from CLI argv and env vars, or any JSON-representable
|
|
96
|
+
* value from config files. Narrow inside the function as needed.
|
|
97
|
+
*/
|
|
98
|
+
type FlagParseFn<T> = (raw: unknown) => T;
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* The runtime descriptor stored inside every `FlagBuilder`. Consumers (parser,
|
|
102
|
+
* help generator, resolution chain) read this to understand the flag's shape
|
|
103
|
+
* without touching generics.
|
|
104
|
+
*/
|
|
105
|
+
interface FlagSchema {
|
|
106
|
+
/** What kind of value this flag accepts. */
|
|
107
|
+
readonly kind: FlagKind;
|
|
108
|
+
/** Current presence state. */
|
|
109
|
+
readonly presence: FlagPresence;
|
|
110
|
+
/** Runtime default value (if any). */
|
|
111
|
+
readonly defaultValue: unknown;
|
|
112
|
+
/** Short/long aliases (e.g. `['f']` for `--force`). */
|
|
113
|
+
readonly aliases: readonly string[];
|
|
114
|
+
/** Environment variable name for v0.2+ resolution. */
|
|
115
|
+
readonly envVar: string | undefined;
|
|
116
|
+
/** Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`). */
|
|
117
|
+
readonly configPath: string | undefined;
|
|
118
|
+
/** Human-readable description for help text. */
|
|
119
|
+
readonly description: string | undefined;
|
|
120
|
+
/** Allowed literal values when `kind === 'enum'`. */
|
|
121
|
+
readonly enumValues: readonly string[] | undefined;
|
|
122
|
+
/** Element schema when `kind === 'array'`. */
|
|
123
|
+
readonly elementSchema: FlagSchema | undefined;
|
|
124
|
+
/** Interactive prompt configuration for v0.3+ resolution. */
|
|
125
|
+
readonly prompt: PromptConfig | undefined;
|
|
126
|
+
/** Custom parse function (only when `kind === 'custom'`). */
|
|
127
|
+
readonly parseFn: FlagParseFn<unknown> | undefined;
|
|
128
|
+
/**
|
|
129
|
+
* Deprecation marker.
|
|
130
|
+
*
|
|
131
|
+
* - `undefined` — not deprecated (default)
|
|
132
|
+
* - `true` — deprecated with no migration message
|
|
133
|
+
* - `string` — deprecated with a reason/migration message
|
|
134
|
+
*
|
|
135
|
+
* When a deprecated flag is used, a warning is emitted to stderr.
|
|
136
|
+
* Help text shows `[deprecated]` or `[deprecated: <reason>]`.
|
|
137
|
+
*/
|
|
138
|
+
readonly deprecated: string | true | undefined;
|
|
139
|
+
/**
|
|
140
|
+
* Whether this flag propagates to subcommands in nested command trees.
|
|
141
|
+
*
|
|
142
|
+
* When `true`, the flag is automatically available to all descendant
|
|
143
|
+
* commands. A child command that defines a flag with the same name
|
|
144
|
+
* shadows the propagated parent flag.
|
|
145
|
+
*
|
|
146
|
+
* @defaultValue `false`
|
|
147
|
+
*/
|
|
148
|
+
readonly propagate: boolean;
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* Create a raw {@link FlagSchema} object with sensible defaults.
|
|
153
|
+
*
|
|
154
|
+
* Most consumers should prefer the higher-level {@link flag} factory,
|
|
155
|
+
* which returns an immutable {@link FlagBuilder} with type inference and
|
|
156
|
+
* safe modifier chaining. `createSchema()` is the low-level escape hatch
|
|
157
|
+
* for advanced schema composition, tests, or custom factories that need to
|
|
158
|
+
* work directly with the runtime descriptor.
|
|
159
|
+
*
|
|
160
|
+
* `overrides` are shallow-merged on top of the default shape, so callers are
|
|
161
|
+
* responsible for keeping the resulting schema internally consistent.
|
|
162
|
+
*
|
|
163
|
+
* @param kind - Discriminator for the value type this flag accepts.
|
|
164
|
+
* @param overrides - Partial {@link FlagSchema} fields merged onto defaults.
|
|
165
|
+
* @returns A fully populated {@link FlagSchema}.
|
|
166
|
+
*
|
|
167
|
+
* @example
|
|
168
|
+
* ```ts
|
|
169
|
+
* const schema = createSchema('enum', {
|
|
170
|
+
* enumValues: ['us', 'eu', 'ap'],
|
|
171
|
+
* description: 'Deployment region',
|
|
172
|
+
* });
|
|
173
|
+
* ```
|
|
174
|
+
*/
|
|
175
|
+
function createSchema(kind: FlagKind, overrides?: Partial<FlagSchema>): FlagSchema {
|
|
176
|
+
return {
|
|
177
|
+
kind,
|
|
178
|
+
presence: 'optional',
|
|
179
|
+
defaultValue: undefined,
|
|
180
|
+
aliases: [],
|
|
181
|
+
envVar: undefined,
|
|
182
|
+
configPath: undefined,
|
|
183
|
+
description: undefined,
|
|
184
|
+
enumValues: undefined,
|
|
185
|
+
elementSchema: undefined,
|
|
186
|
+
prompt: undefined,
|
|
187
|
+
parseFn: undefined,
|
|
188
|
+
deprecated: undefined,
|
|
189
|
+
propagate: false,
|
|
190
|
+
...overrides,
|
|
191
|
+
};
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
// --- FlagBuilder — immutable builder with type-level tracking
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* Immutable flag schema builder.
|
|
198
|
+
*
|
|
199
|
+
* The type parameter `C` is a phantom that tracks the value type and presence
|
|
200
|
+
* through the fluent chain. Each modifier returns a **new** builder — the
|
|
201
|
+
* original is never mutated.
|
|
202
|
+
*
|
|
203
|
+
* @example
|
|
204
|
+
* ```ts
|
|
205
|
+
* const port = flag.number().default(8080);
|
|
206
|
+
* type Port = InferFlag<typeof port>; // number
|
|
207
|
+
*
|
|
208
|
+
* const region = flag.enum(['us', 'eu', 'ap']);
|
|
209
|
+
* type Region = InferFlag<typeof region>; // 'us' | 'eu' | 'ap' | undefined
|
|
210
|
+
* ```
|
|
211
|
+
*/
|
|
212
|
+
class FlagBuilder<C extends FlagConfig> {
|
|
213
|
+
/** @internal Runtime schema descriptor. */
|
|
214
|
+
readonly schema: FlagSchema;
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* @internal Type brand — exists only in the type system (`declare`
|
|
218
|
+
* produces no runtime property). Used by `InferFlag` / `InferFlags`.
|
|
219
|
+
*/
|
|
220
|
+
declare readonly _config: C;
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* @param schema - Runtime descriptor seeding this builder's state.
|
|
224
|
+
*/
|
|
225
|
+
constructor(schema: FlagSchema) {
|
|
226
|
+
this.schema = schema;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
// -- Presence modifiers --------------------------------------------------
|
|
230
|
+
|
|
231
|
+
/**
|
|
232
|
+
* Provide a default value. The flag becomes "always present" — handlers
|
|
233
|
+
* will never see `undefined`.
|
|
234
|
+
*
|
|
235
|
+
* The generic constraint `V extends C['valueType']` ensures the default
|
|
236
|
+
* matches the flag's declared type.
|
|
237
|
+
*
|
|
238
|
+
* @param value - Fallback value used when no source provides one.
|
|
239
|
+
* @returns The builder (for chaining).
|
|
240
|
+
*
|
|
241
|
+
* @example
|
|
242
|
+
* ```ts
|
|
243
|
+
* flag.number().default(8080).describe('Port to listen on')
|
|
244
|
+
*
|
|
245
|
+
* // $ mycli serve → port = 8080
|
|
246
|
+
* // $ mycli serve --port 443 → port = 443
|
|
247
|
+
* ```
|
|
248
|
+
*/
|
|
249
|
+
default<V extends C['valueType']>(value: V): FlagBuilder<WithPresence<C, 'defaulted'>> {
|
|
250
|
+
return new FlagBuilder({
|
|
251
|
+
...this.schema,
|
|
252
|
+
presence: 'defaulted',
|
|
253
|
+
defaultValue: value,
|
|
254
|
+
});
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
/**
|
|
258
|
+
* Mark the flag as required. If not resolved from any source the framework
|
|
259
|
+
* will emit a `ValidationError` before the action handler runs.
|
|
260
|
+
*
|
|
261
|
+
* @returns The builder (for chaining).
|
|
262
|
+
*
|
|
263
|
+
* @example
|
|
264
|
+
* ```ts
|
|
265
|
+
* flag.string().required().describe('Deploy target')
|
|
266
|
+
*
|
|
267
|
+
* // $ mycli deploy
|
|
268
|
+
* // # → Error: Missing required flag --target
|
|
269
|
+
* // $ mycli deploy --target staging
|
|
270
|
+
* // # → target = 'staging'
|
|
271
|
+
* ```
|
|
272
|
+
*/
|
|
273
|
+
required(): FlagBuilder<WithPresence<C, 'required'>> {
|
|
274
|
+
return new FlagBuilder({
|
|
275
|
+
...this.schema,
|
|
276
|
+
presence: 'required',
|
|
277
|
+
});
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
// -- Metadata modifiers --------------------------------------------------
|
|
281
|
+
|
|
282
|
+
/**
|
|
283
|
+
* Add a short or long alias (e.g. `'f'` for `--force`, `'verbose'` as an
|
|
284
|
+
* alternative long name).
|
|
285
|
+
*
|
|
286
|
+
* @param name - Single-char short alias or alternative long name.
|
|
287
|
+
* @returns The builder (for chaining).
|
|
288
|
+
*
|
|
289
|
+
* @example
|
|
290
|
+
* ```ts
|
|
291
|
+
* flag.boolean().alias('v').describe('Enable verbose output')
|
|
292
|
+
*
|
|
293
|
+
* // $ mycli build -v → verbose = true
|
|
294
|
+
* // $ mycli build --verbose → verbose = true
|
|
295
|
+
* ```
|
|
296
|
+
*/
|
|
297
|
+
alias(name: string): FlagBuilder<C> {
|
|
298
|
+
return new FlagBuilder({
|
|
299
|
+
...this.schema,
|
|
300
|
+
aliases: [...this.schema.aliases, name],
|
|
301
|
+
});
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
/**
|
|
305
|
+
* Bind to an environment variable (resolved in v0.2+).
|
|
306
|
+
*
|
|
307
|
+
* @param varName - Environment variable name (e.g. `'PORT'`).
|
|
308
|
+
* @returns The builder (for chaining).
|
|
309
|
+
*
|
|
310
|
+
* @example
|
|
311
|
+
* ```ts
|
|
312
|
+
* flag.string().env('API_KEY').describe('Service API key')
|
|
313
|
+
*
|
|
314
|
+
* // $ API_KEY=sk-123 mycli request → apiKey = 'sk-123'
|
|
315
|
+
* // $ mycli request --api-key sk-456 → apiKey = 'sk-456' (CLI wins)
|
|
316
|
+
* ```
|
|
317
|
+
*/
|
|
318
|
+
env(varName: string): FlagBuilder<C> {
|
|
319
|
+
return new FlagBuilder({
|
|
320
|
+
...this.schema,
|
|
321
|
+
envVar: varName,
|
|
322
|
+
});
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
/**
|
|
326
|
+
* Bind to a dotted config path (resolved in v0.2+).
|
|
327
|
+
*
|
|
328
|
+
* @param path - Dotted config key (e.g. `'deploy.region'`).
|
|
329
|
+
* @returns The builder (for chaining).
|
|
330
|
+
*
|
|
331
|
+
* @example
|
|
332
|
+
* ```ts
|
|
333
|
+
* flag.string().config('deploy.region').default('us-east-1')
|
|
334
|
+
* // Config file: { "deploy": { "region": "eu-west-1" } }
|
|
335
|
+
* // $ mycli deploy
|
|
336
|
+
* // # → region = 'eu-west-1' (from config)
|
|
337
|
+
* // $ mycli deploy --region ap-south-1
|
|
338
|
+
* // # → CLI flag wins
|
|
339
|
+
* ```
|
|
340
|
+
*/
|
|
341
|
+
config(path: string): FlagBuilder<C> {
|
|
342
|
+
return new FlagBuilder({
|
|
343
|
+
...this.schema,
|
|
344
|
+
configPath: path,
|
|
345
|
+
});
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
/**
|
|
349
|
+
* Human-readable description shown in help output.
|
|
350
|
+
*
|
|
351
|
+
* @param description - Text displayed next to the flag in `--help`.
|
|
352
|
+
* @returns The builder (for chaining).
|
|
353
|
+
*/
|
|
354
|
+
describe(description: string): FlagBuilder<C> {
|
|
355
|
+
return new FlagBuilder({
|
|
356
|
+
...this.schema,
|
|
357
|
+
description,
|
|
358
|
+
});
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
/**
|
|
362
|
+
* Attach interactive prompt configuration for v0.3+ resolution.
|
|
363
|
+
*
|
|
364
|
+
* When a flag value is not resolved from CLI, env, or config, the
|
|
365
|
+
* prompt engine uses this config to interactively ask the user.
|
|
366
|
+
* In non-interactive contexts (CI, piped stdin) prompts are skipped
|
|
367
|
+
* and resolution falls through to default or required validation.
|
|
368
|
+
*
|
|
369
|
+
* @param config - {@link PromptConfig} describing the interactive prompt.
|
|
370
|
+
* @returns The builder (for chaining).
|
|
371
|
+
*
|
|
372
|
+
* @example
|
|
373
|
+
* ```ts
|
|
374
|
+
* flag.string().prompt({ kind: 'input', message: 'Enter value:' })
|
|
375
|
+
*
|
|
376
|
+
* // $ mycli init → prompts "Enter value:" interactively
|
|
377
|
+
* // $ mycli init --name foo → skips prompt, uses CLI value
|
|
378
|
+
* ```
|
|
379
|
+
*/
|
|
380
|
+
prompt(config: PromptConfig): FlagBuilder<C> {
|
|
381
|
+
return new FlagBuilder({
|
|
382
|
+
...this.schema,
|
|
383
|
+
prompt: config,
|
|
384
|
+
});
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
/**
|
|
388
|
+
* Mark this flag as deprecated.
|
|
389
|
+
*
|
|
390
|
+
* When used, a warning is emitted to stderr. Help text shows
|
|
391
|
+
* `[deprecated]` or `[deprecated: <reason>]`.
|
|
392
|
+
*
|
|
393
|
+
* Does not change the flag's type-level config — it's metadata only.
|
|
394
|
+
*
|
|
395
|
+
* @param message - Optional migration reason/guidance.
|
|
396
|
+
* @returns The builder (for chaining).
|
|
397
|
+
*
|
|
398
|
+
* @example
|
|
399
|
+
* ```ts
|
|
400
|
+
* flag.string().deprecated('Use --target instead')
|
|
401
|
+
*
|
|
402
|
+
* // $ mycli deploy --dest staging
|
|
403
|
+
* // ⚠ --dest is deprecated: Use --target instead
|
|
404
|
+
* ```
|
|
405
|
+
*/
|
|
406
|
+
deprecated(message?: string): FlagBuilder<C> {
|
|
407
|
+
return new FlagBuilder({
|
|
408
|
+
...this.schema,
|
|
409
|
+
deprecated: message ?? true,
|
|
410
|
+
});
|
|
411
|
+
}
|
|
412
|
+
|
|
413
|
+
/**
|
|
414
|
+
* Mark this flag as propagated to subcommands.
|
|
415
|
+
*
|
|
416
|
+
* Propagated flags are automatically available to all descendant
|
|
417
|
+
* commands in a nested command tree. A child command that defines
|
|
418
|
+
* a flag with the same name shadows the propagated parent flag.
|
|
419
|
+
*
|
|
420
|
+
* Does not change the flag's type-level config — it's metadata only.
|
|
421
|
+
*
|
|
422
|
+
* @returns The builder (for chaining).
|
|
423
|
+
*
|
|
424
|
+
* @example
|
|
425
|
+
* ```ts
|
|
426
|
+
* flag.boolean().alias('v').propagate().describe('Enable verbose output')
|
|
427
|
+
*
|
|
428
|
+
* // $ mycli --verbose deploy staging
|
|
429
|
+
* // # → verbose = true in deploy handler
|
|
430
|
+
* // $ mycli deploy --verbose staging
|
|
431
|
+
* // # → same, inherited from parent
|
|
432
|
+
* ```
|
|
433
|
+
*/
|
|
434
|
+
propagate(): FlagBuilder<C> {
|
|
435
|
+
return new FlagBuilder({
|
|
436
|
+
...this.schema,
|
|
437
|
+
propagate: true,
|
|
438
|
+
});
|
|
439
|
+
}
|
|
440
|
+
}
|
|
441
|
+
|
|
442
|
+
// --- Factory namespace
|
|
443
|
+
|
|
444
|
+
/**
|
|
445
|
+
* Factory that creates {@link FlagBuilder} instances seeded with the correct
|
|
446
|
+
* {@link FlagKind} and initial type-level config.
|
|
447
|
+
*/
|
|
448
|
+
interface FlagFactory {
|
|
449
|
+
/**
|
|
450
|
+
* String-valued flag.
|
|
451
|
+
*
|
|
452
|
+
* @returns A {@link FlagBuilder} for `string` values.
|
|
453
|
+
*/
|
|
454
|
+
string(): FlagBuilder<{
|
|
455
|
+
readonly valueType: string;
|
|
456
|
+
readonly presence: 'optional';
|
|
457
|
+
readonly optionalFallback: 'undefined';
|
|
458
|
+
}>;
|
|
459
|
+
|
|
460
|
+
/**
|
|
461
|
+
* Number-valued flag.
|
|
462
|
+
*
|
|
463
|
+
* @returns A {@link FlagBuilder} for `number` values.
|
|
464
|
+
*/
|
|
465
|
+
number(): FlagBuilder<{
|
|
466
|
+
readonly valueType: number;
|
|
467
|
+
readonly presence: 'optional';
|
|
468
|
+
readonly optionalFallback: 'undefined';
|
|
469
|
+
}>;
|
|
470
|
+
|
|
471
|
+
/**
|
|
472
|
+
* Boolean flag. Implicitly defaults to `false` — the only flag kind where
|
|
473
|
+
* the absence of a value is still meaningful (not `undefined`).
|
|
474
|
+
*
|
|
475
|
+
* @returns A {@link FlagBuilder} for `boolean` values (defaulted to `false`).
|
|
476
|
+
*/
|
|
477
|
+
boolean(): FlagBuilder<{
|
|
478
|
+
readonly valueType: boolean;
|
|
479
|
+
readonly presence: 'defaulted';
|
|
480
|
+
readonly optionalFallback: 'undefined';
|
|
481
|
+
}>;
|
|
482
|
+
|
|
483
|
+
/**
|
|
484
|
+
* Enum flag with literal type inference.
|
|
485
|
+
*
|
|
486
|
+
* Requires a **non-empty** readonly tuple so that `T[number]` produces a
|
|
487
|
+
* union of string literals rather than just `string`.
|
|
488
|
+
*
|
|
489
|
+
* @example
|
|
490
|
+
* ```ts
|
|
491
|
+
* flag.enum(['us', 'eu', 'ap'])
|
|
492
|
+
* // inferred type: 'us' | 'eu' | 'ap'
|
|
493
|
+
* ```
|
|
494
|
+
*
|
|
495
|
+
* @param values - Non-empty tuple of allowed string literals.
|
|
496
|
+
* @returns A {@link FlagBuilder} whose value type is the union of `values`.
|
|
497
|
+
*/
|
|
498
|
+
enum<const T extends readonly [string, ...string[]]>(
|
|
499
|
+
values: T,
|
|
500
|
+
): FlagBuilder<{
|
|
501
|
+
readonly valueType: T[number];
|
|
502
|
+
readonly presence: 'optional';
|
|
503
|
+
readonly optionalFallback: 'undefined';
|
|
504
|
+
}>;
|
|
505
|
+
|
|
506
|
+
/**
|
|
507
|
+
* Array flag — collects multiple values of the same element type.
|
|
508
|
+
*
|
|
509
|
+
* @example
|
|
510
|
+
* ```ts
|
|
511
|
+
* flag.array(flag.string())
|
|
512
|
+
* // inferred type: string[]
|
|
513
|
+
* ```
|
|
514
|
+
*
|
|
515
|
+
* @param element - {@link FlagBuilder} describing the element type.
|
|
516
|
+
* @returns A {@link FlagBuilder} for arrays of the element type.
|
|
517
|
+
*/
|
|
518
|
+
array<E extends FlagConfig>(
|
|
519
|
+
element: FlagBuilder<E>,
|
|
520
|
+
): FlagBuilder<{
|
|
521
|
+
readonly valueType: E['valueType'][];
|
|
522
|
+
readonly presence: 'optional';
|
|
523
|
+
readonly optionalFallback: 'empty-array';
|
|
524
|
+
}>;
|
|
525
|
+
|
|
526
|
+
/**
|
|
527
|
+
* Custom-parsed flag. The parse function receives the raw value and must
|
|
528
|
+
* return a value of type `T`. The return type is inferred from `parseFn`.
|
|
529
|
+
*
|
|
530
|
+
* The input is `string` from CLI argv and env vars, or any JSON value
|
|
531
|
+
* from config files. Narrow inside the function as needed:
|
|
532
|
+
*
|
|
533
|
+
* ```ts
|
|
534
|
+
* flag.custom((raw: unknown): string[] => {
|
|
535
|
+
* if (Array.isArray(raw)) return raw.map(String);
|
|
536
|
+
* if (typeof raw === 'string') return raw.split(',');
|
|
537
|
+
* throw new Error(`Expected string or array, got ${typeof raw}`);
|
|
538
|
+
* })
|
|
539
|
+
* ```
|
|
540
|
+
*
|
|
541
|
+
* Throw an `Error` (or `ParseError`) to signal invalid input — it will
|
|
542
|
+
* be wrapped with context and re-thrown as a `ParseError`.
|
|
543
|
+
*
|
|
544
|
+
* @see `coerceConfigValue` `'custom'` case in `core/resolve/index.ts`
|
|
545
|
+
*
|
|
546
|
+
* @example
|
|
547
|
+
* ```ts
|
|
548
|
+
* flag.custom((raw) => new URL(String(raw)))
|
|
549
|
+
* // inferred type: URL | undefined
|
|
550
|
+
* ```
|
|
551
|
+
*
|
|
552
|
+
* @param parseFn - Converts the raw input into a value of type `T`.
|
|
553
|
+
* @returns A {@link FlagBuilder} whose value type is inferred from `parseFn`.
|
|
554
|
+
*/
|
|
555
|
+
custom<T>(parseFn: FlagParseFn<T>): FlagBuilder<{
|
|
556
|
+
readonly valueType: T;
|
|
557
|
+
readonly presence: 'optional';
|
|
558
|
+
readonly optionalFallback: 'undefined';
|
|
559
|
+
}>;
|
|
560
|
+
}
|
|
561
|
+
|
|
562
|
+
/**
|
|
563
|
+
* Flag schema factory. Call `flag.<kind>()` to create an immutable
|
|
564
|
+
* {@link FlagBuilder} with full type inference and safe modifier chaining.
|
|
565
|
+
*/
|
|
566
|
+
const flag: FlagFactory = {
|
|
567
|
+
string(): FlagBuilder<{
|
|
568
|
+
readonly valueType: string;
|
|
569
|
+
readonly presence: 'optional';
|
|
570
|
+
readonly optionalFallback: 'undefined';
|
|
571
|
+
}> {
|
|
572
|
+
return new FlagBuilder(createSchema('string'));
|
|
573
|
+
},
|
|
574
|
+
|
|
575
|
+
number(): FlagBuilder<{
|
|
576
|
+
readonly valueType: number;
|
|
577
|
+
readonly presence: 'optional';
|
|
578
|
+
readonly optionalFallback: 'undefined';
|
|
579
|
+
}> {
|
|
580
|
+
return new FlagBuilder(createSchema('number'));
|
|
581
|
+
},
|
|
582
|
+
|
|
583
|
+
boolean(): FlagBuilder<{
|
|
584
|
+
readonly valueType: boolean;
|
|
585
|
+
readonly presence: 'defaulted';
|
|
586
|
+
readonly optionalFallback: 'undefined';
|
|
587
|
+
}> {
|
|
588
|
+
return new FlagBuilder(
|
|
589
|
+
createSchema('boolean', {
|
|
590
|
+
presence: 'defaulted',
|
|
591
|
+
defaultValue: false,
|
|
592
|
+
}),
|
|
593
|
+
);
|
|
594
|
+
},
|
|
595
|
+
|
|
596
|
+
enum<const T extends readonly [string, ...string[]]>(
|
|
597
|
+
values: T,
|
|
598
|
+
): FlagBuilder<{
|
|
599
|
+
readonly valueType: T[number];
|
|
600
|
+
readonly presence: 'optional';
|
|
601
|
+
readonly optionalFallback: 'undefined';
|
|
602
|
+
}> {
|
|
603
|
+
return new FlagBuilder(createSchema('enum', { enumValues: values }));
|
|
604
|
+
},
|
|
605
|
+
|
|
606
|
+
array<E extends FlagConfig>(
|
|
607
|
+
element: FlagBuilder<E>,
|
|
608
|
+
): FlagBuilder<{
|
|
609
|
+
readonly valueType: E['valueType'][];
|
|
610
|
+
readonly presence: 'optional';
|
|
611
|
+
readonly optionalFallback: 'empty-array';
|
|
612
|
+
}> {
|
|
613
|
+
return new FlagBuilder(createSchema('array', { elementSchema: element.schema }));
|
|
614
|
+
},
|
|
615
|
+
|
|
616
|
+
custom<T>(parseFn: FlagParseFn<T>): FlagBuilder<{
|
|
617
|
+
readonly valueType: T;
|
|
618
|
+
readonly presence: 'optional';
|
|
619
|
+
readonly optionalFallback: 'undefined';
|
|
620
|
+
}> {
|
|
621
|
+
return new FlagBuilder(createSchema('custom', { parseFn: parseFn as FlagParseFn<unknown> }));
|
|
622
|
+
},
|
|
623
|
+
};
|
|
624
|
+
|
|
625
|
+
// --- Exports
|
|
626
|
+
|
|
627
|
+
// Re-export prompt types for consumers
|
|
628
|
+
export type {
|
|
629
|
+
ConfirmPromptConfig,
|
|
630
|
+
InputPromptConfig,
|
|
631
|
+
MultiselectPromptConfig,
|
|
632
|
+
PromptConfig,
|
|
633
|
+
PromptConfigBase,
|
|
634
|
+
PromptKind,
|
|
635
|
+
PromptResult,
|
|
636
|
+
SelectChoice,
|
|
637
|
+
SelectPromptConfig,
|
|
638
|
+
} from './prompt.ts';
|
|
639
|
+
export type {
|
|
640
|
+
FlagConfig,
|
|
641
|
+
FlagFactory,
|
|
642
|
+
FlagKind,
|
|
643
|
+
FlagParseFn,
|
|
644
|
+
FlagPresence,
|
|
645
|
+
FlagSchema,
|
|
646
|
+
InferFlag,
|
|
647
|
+
InferFlags,
|
|
648
|
+
ResolvedValue,
|
|
649
|
+
WithPresence,
|
|
650
|
+
};
|
|
651
|
+
export { createSchema, FlagBuilder, flag };
|