@kjanat/dreamcli 5.0.0 → 5.1.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/dist/completion-B4oRc2Ae.mjs +59 -0
- package/dist/completion.d.mts +11 -1
- package/dist/completion.mjs +1 -1
- package/dist/config-DSh3QJpX.mjs +1 -0
- package/dist/config.d.mts +11 -1
- package/dist/config.mjs +1 -1
- package/dist/core-BZx351-p.mjs +21 -0
- package/dist/dynamic-BK2lQF2M.mjs +1 -0
- package/dist/{index-BidVVmln.d.mts → index-CLtWJqwn.d.mts} +8 -5
- package/dist/{index-BIMjOsR6.d.mts → index-CuhI1Ynv.d.mts} +394 -4
- package/dist/{index-DpslpOVV.d.mts → index-DDhRLoTu.d.mts} +7 -1
- package/dist/{index-jq_FJRKt.d.mts → index-DIWRV_wp.d.mts} +1 -1
- package/dist/{index-hzYPRc_O.d.mts → index-Vjl2_m23.d.mts} +5 -5
- package/dist/{index-AIC5Gler.d.mts → index-aTmg9yfl.d.mts} +1 -1
- package/dist/index.d.mts +30 -7
- package/dist/index.mjs +1 -1
- package/dist/json-schema-CYgq_hFu.mjs +59 -0
- package/dist/json-schema.d.mts +9 -1
- package/dist/json-schema.mjs +1 -1
- package/dist/{package-json-fYhxDdWD.mjs → package-json-hqUWeazy.mjs} +1 -1
- package/dist/prompt.d.mts +12 -1
- package/dist/prompt.mjs +1 -1
- package/dist/rolldown-runtime-DOYBPklu.mjs +1 -0
- package/dist/runtime.d.mts +20 -2
- package/dist/runtime.mjs +1 -1
- package/dist/session-BEKj0yLA.mjs +1 -0
- package/dist/{terminal-DRsRn4sc.mjs → terminal-Dws_b5UK.mjs} +1 -1
- package/dist/test-prompter-euLYzWWO.mjs +1 -0
- package/dist/testkit.d.mts +17 -4
- package/dist/testkit.mjs +1 -1
- package/dist/version.mjs +1 -1
- package/dreamcli.schema.json +11 -0
- package/package.json +7 -7
- package/skills/cli-creation/SKILL.md +1 -1
- package/dist/adapter-DBeedKmD.d.mts +0 -283
- package/dist/completion-Bh-qywmB.mjs +0 -6
- package/dist/config-DruA8aFV.mjs +0 -1
- package/dist/core-B9YNSJeA.mjs +0 -19
- package/dist/json-schema-DF5fXdKQ.mjs +0 -59
- package/dist/rolldown-runtime-G4Kt5YOX.mjs +0 -1
- package/dist/session-Crtzt7LY.mjs +0 -1
- package/dist/test-prompter-BLNGCOA_.mjs +0 -1
|
@@ -30,6 +30,8 @@ declare const schemaBrand: unique symbol;
|
|
|
30
30
|
type Fallback = 'silent' | 'static';
|
|
31
31
|
/** Options for {@link Out.spinner}. */
|
|
32
32
|
interface SpinnerOptions {
|
|
33
|
+
/** Render alongside other concurrent activities instead of replacing them. */
|
|
34
|
+
readonly concurrent?: boolean;
|
|
33
35
|
/**
|
|
34
36
|
* Fallback strategy when `!isTTY` or `jsonMode`.
|
|
35
37
|
* @defaultValue `'silent'`
|
|
@@ -57,12 +59,14 @@ interface SpinnerHandle {
|
|
|
57
59
|
* @returns The resolved value of the wrapped promise.
|
|
58
60
|
*/
|
|
59
61
|
wrap<T>(promise: Promise<T>, options?: {
|
|
60
|
-
readonly succeed?: string;
|
|
61
|
-
readonly fail?: string;
|
|
62
|
+
readonly succeed?: string | ((value: T) => string);
|
|
63
|
+
readonly fail?: string | ((error: unknown) => string);
|
|
62
64
|
}): Promise<T>;
|
|
63
65
|
}
|
|
64
66
|
/** Options for {@link Out.progress}. */
|
|
65
67
|
interface ProgressOptions {
|
|
68
|
+
/** Render alongside other concurrent activities instead of replacing them. */
|
|
69
|
+
readonly concurrent?: boolean;
|
|
66
70
|
/**
|
|
67
71
|
* Total units of work. When provided, the bar shows a determinate
|
|
68
72
|
* percentage. When omitted, the bar pulses in indeterminate mode.
|
|
@@ -246,6 +250,29 @@ type HelpDescription = string | ((theme: HelpTheme) => string);
|
|
|
246
250
|
* unconditionally, gating is the framework's job.
|
|
247
251
|
*/
|
|
248
252
|
type HelpThemeFactory = (colors: Colors) => Partial<HelpTheme>;
|
|
253
|
+
/**
|
|
254
|
+
* Runtime value completion callbacks.
|
|
255
|
+
*
|
|
256
|
+
* @module dreamcli/core/schema/completion
|
|
257
|
+
*/
|
|
258
|
+
/** The input and partial command line being completed. */
|
|
259
|
+
interface CompletionContext {
|
|
260
|
+
/** The value prefix typed before the cursor. */
|
|
261
|
+
readonly prefix: string;
|
|
262
|
+
/** Canonical command names, excluding the executable. Empty for a default command. */
|
|
263
|
+
readonly commandPath: readonly string[];
|
|
264
|
+
/** The input whose value is being completed. */
|
|
265
|
+
readonly input: {
|
|
266
|
+
readonly kind: 'flag' | 'arg';
|
|
267
|
+
readonly name: string;
|
|
268
|
+
};
|
|
269
|
+
/** Arguments before the cursor, including the current partial token. */
|
|
270
|
+
readonly argv: readonly string[];
|
|
271
|
+
/** Environment supplied to this execution. */
|
|
272
|
+
readonly env: Readonly<Record<string, string | undefined>>;
|
|
273
|
+
}
|
|
274
|
+
/** Return complete candidate values. DreamCLI filters them by prefix. */
|
|
275
|
+
type CompletionHandler = (context: CompletionContext) => readonly string[] | Promise<readonly string[]>;
|
|
249
276
|
/**
|
|
250
277
|
* An indexed env family whose entries are single values.
|
|
251
278
|
*
|
|
@@ -643,6 +670,8 @@ declare const STDIN_CONSUMES: readonly ["exclusive", "broadcast"];
|
|
|
643
670
|
type StdinConsume = (typeof STDIN_CONSUMES)[number];
|
|
644
671
|
/** The normalized stdin axis of a flag or an arg. */
|
|
645
672
|
interface StdinBinding {
|
|
673
|
+
/** False when this input has no command-line form. Omitted means true. */
|
|
674
|
+
readonly argv?: false;
|
|
646
675
|
/** When this input reads the stdin stream. */
|
|
647
676
|
readonly when: StdinWhen;
|
|
648
677
|
/** Whether this input consumes the stream alone. */
|
|
@@ -652,6 +681,13 @@ interface StdinBinding {
|
|
|
652
681
|
}
|
|
653
682
|
/** Stdin settings accepted by `.stdin()` and by the schema definitions. */
|
|
654
683
|
interface StdinOptions {
|
|
684
|
+
/**
|
|
685
|
+
* Accept this input on the command line. Set false to omit its flag spellings
|
|
686
|
+
* or positional slot from parsing, help, and completion. Other sources still apply.
|
|
687
|
+
* Cannot be combined with `when: 'dash'`.
|
|
688
|
+
* @defaultValue `true`
|
|
689
|
+
*/
|
|
690
|
+
readonly argv?: boolean | undefined;
|
|
655
691
|
/**
|
|
656
692
|
* When this input reads the stdin stream.
|
|
657
693
|
* @defaultValue `'dash-or-missing'`
|
|
@@ -1013,6 +1049,8 @@ type DuplicatePolicy = 'last' | 'first' | 'error';
|
|
|
1013
1049
|
interface FlagSchema<K extends FlagKind = FlagKind> {
|
|
1014
1050
|
/** Type-only seal produced by {@link createFlagSchema}. */
|
|
1015
1051
|
readonly [schemaBrand]: 'flag';
|
|
1052
|
+
/** Callback used to complete this input's values. */
|
|
1053
|
+
readonly completion?: CompletionHandler | undefined;
|
|
1016
1054
|
/** What kind of value this flag accepts. */
|
|
1017
1055
|
readonly kind: K;
|
|
1018
1056
|
/** Current presence state. */
|
|
@@ -1175,6 +1213,8 @@ interface FlagSchema<K extends FlagKind = FlagKind> {
|
|
|
1175
1213
|
}
|
|
1176
1214
|
/** Definition fields accepted by every flag kind. */
|
|
1177
1215
|
interface FlagDefinitionBase {
|
|
1216
|
+
/** Callback used to complete this input's values. */
|
|
1217
|
+
readonly completion?: CompletionHandler | undefined;
|
|
1178
1218
|
/**
|
|
1179
1219
|
* Presence state.
|
|
1180
1220
|
* @defaultValue `'optional'`
|
|
@@ -1500,6 +1540,17 @@ declare class FlagBuilder<C extends FlagConfig> {
|
|
|
1500
1540
|
* @param schema - Runtime descriptor seeding this builder's state.
|
|
1501
1541
|
*/
|
|
1502
1542
|
constructor(schema: FlagSchema);
|
|
1543
|
+
/**
|
|
1544
|
+
* Compute value candidates when the user requests shell completion.
|
|
1545
|
+
*
|
|
1546
|
+
* The callback runs without the command action, middleware, prompts, or
|
|
1547
|
+
* config discovery. Return complete values; DreamCLI filters by prefix.
|
|
1548
|
+
* Candidates containing control characters are omitted.
|
|
1549
|
+
*
|
|
1550
|
+
* @param handler - Callback receiving the input and partial command line.
|
|
1551
|
+
* @returns A new builder with the completion callback.
|
|
1552
|
+
*/
|
|
1553
|
+
complete(handler: CompletionHandler): FlagBuilder<WithoutElementEligibility<C>>;
|
|
1503
1554
|
/**
|
|
1504
1555
|
* Provide a default value. The flag becomes "always present" — handlers
|
|
1505
1556
|
* will never see `undefined`.
|
|
@@ -2641,6 +2692,8 @@ type ArgParseFn<T> = (raw: string) => T;
|
|
|
2641
2692
|
interface ArgSchema<K extends ArgKind = ArgKind> {
|
|
2642
2693
|
/** Type-only seal produced by {@link createArgSchema}. */
|
|
2643
2694
|
readonly [schemaBrand]: 'arg';
|
|
2695
|
+
/** Callback used to complete this input's values. */
|
|
2696
|
+
readonly completion?: CompletionHandler | undefined;
|
|
2644
2697
|
/** What kind of value this arg accepts. */
|
|
2645
2698
|
readonly kind: K;
|
|
2646
2699
|
/** Current presence state. */
|
|
@@ -2805,6 +2858,8 @@ interface ArgSchema<K extends ArgKind = ArgKind> {
|
|
|
2805
2858
|
}
|
|
2806
2859
|
/** Definition fields accepted by every arg kind. */
|
|
2807
2860
|
interface ArgDefinitionBase {
|
|
2861
|
+
/** Callback used to complete this input's values. */
|
|
2862
|
+
readonly completion?: CompletionHandler | undefined;
|
|
2808
2863
|
/**
|
|
2809
2864
|
* Presence state.
|
|
2810
2865
|
* @defaultValue `'required'`
|
|
@@ -3100,6 +3155,17 @@ declare class ArgBuilder<C extends ArgConfig> {
|
|
|
3100
3155
|
* @param schema - Runtime descriptor for this positional argument.
|
|
3101
3156
|
*/
|
|
3102
3157
|
constructor(schema: ArgSchema);
|
|
3158
|
+
/**
|
|
3159
|
+
* Compute value candidates when the user requests shell completion.
|
|
3160
|
+
*
|
|
3161
|
+
* The callback runs without the command action, middleware, prompts, or
|
|
3162
|
+
* config discovery. Return complete values; DreamCLI filters by prefix.
|
|
3163
|
+
* Candidates containing control characters are omitted.
|
|
3164
|
+
*
|
|
3165
|
+
* @param handler - Callback receiving the input and partial command line.
|
|
3166
|
+
* @returns A new builder with the completion callback.
|
|
3167
|
+
*/
|
|
3168
|
+
complete(handler: CompletionHandler): ArgBuilder<WithoutArgElementEligibility<C>>;
|
|
3103
3169
|
/**
|
|
3104
3170
|
* Mark the arg as required (this is the default for positional args).
|
|
3105
3171
|
* Produces an error if no value resolves from any configured source
|
|
@@ -4755,6 +4821,8 @@ interface CommandSchema {
|
|
|
4755
4821
|
readonly name: string;
|
|
4756
4822
|
/** Human-readable description for help text. */
|
|
4757
4823
|
readonly description: string | undefined;
|
|
4824
|
+
/** Longer explanation shown only in this command's help, with paragraphs wrapped to its width. */
|
|
4825
|
+
readonly details?: HelpDescription | undefined;
|
|
4758
4826
|
/** Alternative names for this command. */
|
|
4759
4827
|
readonly aliases: readonly string[];
|
|
4760
4828
|
/** Whether this command is hidden from help listings. */
|
|
@@ -4823,6 +4891,8 @@ interface CommandDefinition {
|
|
|
4823
4891
|
* @defaultValue `undefined`
|
|
4824
4892
|
*/
|
|
4825
4893
|
readonly description?: string | undefined;
|
|
4894
|
+
/** Longer explanation shown only in this command's help. */
|
|
4895
|
+
readonly details?: HelpDescription | undefined;
|
|
4826
4896
|
/**
|
|
4827
4897
|
* Alternative names for this command.
|
|
4828
4898
|
* @defaultValue `[]`
|
|
@@ -4921,6 +4991,10 @@ declare function createCommandSchema(definition: CommandDefinition): CommandSche
|
|
|
4921
4991
|
*
|
|
4922
4992
|
*/
|
|
4923
4993
|
type AnyCommandBuilder = CommandBuilder<Record<string, FlagBuilder<FlagConfig>>, Record<string, ArgBuilder<ArgConfig>>, Record<string, unknown>>;
|
|
4994
|
+
/** Retain declared flag names for duplicate checks alongside an index signature. */
|
|
4995
|
+
type KnownFlags<F> = { [K in keyof F as string extends K ? never : number extends K ? never : K]: F[K]; };
|
|
4996
|
+
/** Generated names can carry any registered builder, while declared names keep their types. */
|
|
4997
|
+
type MergeFlags<F extends Record<string, FlagBuilder<FlagConfig>>, R extends Record<string, FlagBuilder<FlagConfig>>> = string extends keyof F | keyof R ? KnownFlags<F> & KnownFlags<R> & Record<string, F[keyof F] | R[keyof R]> : F & R;
|
|
4924
4998
|
/**
|
|
4925
4999
|
* Immutable command schema builder.
|
|
4926
5000
|
*
|
|
@@ -5133,6 +5207,16 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
|
|
|
5133
5207
|
* @returns The builder (for chaining).
|
|
5134
5208
|
*/
|
|
5135
5209
|
description(text: string): CommandBuilder<F, A, C>;
|
|
5210
|
+
/**
|
|
5211
|
+
* Add a longer explanation to this command's help.
|
|
5212
|
+
*
|
|
5213
|
+
* Paragraphs wrap to the help width. Parent command listings use only
|
|
5214
|
+
* `.description()`. A function receives the current help description theme.
|
|
5215
|
+
*
|
|
5216
|
+
* @param text - Literal text or a function that styles the explanation.
|
|
5217
|
+
* @returns A new builder with the explanation.
|
|
5218
|
+
*/
|
|
5219
|
+
details(text: HelpDescription): CommandBuilder<F, A, C>;
|
|
5136
5220
|
/**
|
|
5137
5221
|
* Add an alternative name for this command.
|
|
5138
5222
|
*
|
|
@@ -5262,7 +5346,26 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
|
|
|
5262
5346
|
* @throws {@link CLIError} `PROPAGATED_FLAG_COLLISION` when a spelling
|
|
5263
5347
|
* collides with one propagated to a registered subcommand.
|
|
5264
5348
|
*/
|
|
5265
|
-
flag<N extends string, B extends FlagBuilder<FlagConfig>>(name: N & Exclude<N, keyof F
|
|
5349
|
+
flag<N extends string, B extends FlagBuilder<FlagConfig>>(name: N & Exclude<N, keyof KnownFlags<F>>, builder: B): CommandBuilder<MergeFlags<F, Record<N, B>>, A, C>;
|
|
5350
|
+
/**
|
|
5351
|
+
* Register a record of flags, preserving each key and inferred value type.
|
|
5352
|
+
*
|
|
5353
|
+
* Names and aliases must not collide with existing flags or other entries.
|
|
5354
|
+
* Literal names are checked by the compiler. Generated names are checked
|
|
5355
|
+
* at runtime, and their values include the registered flag value types.
|
|
5356
|
+
* Adding flags clears any previously registered action, like `.flag()`.
|
|
5357
|
+
*
|
|
5358
|
+
* @param record - Named flag builders to add to this command.
|
|
5359
|
+
* @returns A new builder with the added flags.
|
|
5360
|
+
*
|
|
5361
|
+
* @example
|
|
5362
|
+
* ```ts
|
|
5363
|
+
* command('serve')
|
|
5364
|
+
* .flags({ port: flag.number().default(3000), host: flag.string() })
|
|
5365
|
+
* .action(({ flags }) => { flags.port; flags.host; });
|
|
5366
|
+
* ```
|
|
5367
|
+
*/
|
|
5368
|
+
flags<const R extends Record<string, FlagBuilder<FlagConfig>>>(record: R & { [K in (keyof KnownFlags<R> & keyof KnownFlags<F>) | Extract<keyof R, symbol>]: never; }): CommandBuilder<MergeFlags<F, R>, A, C>;
|
|
5266
5369
|
/**
|
|
5267
5370
|
* Register a named positional argument on this command.
|
|
5268
5371
|
*
|
|
@@ -5528,6 +5631,287 @@ type ReadFn = () => Promise<string | null>;
|
|
|
5528
5631
|
* @throws Error if select/multiselect has no choices and no enum values
|
|
5529
5632
|
*/
|
|
5530
5633
|
declare function resolvePromptConfig(config: PromptConfig, enumValues: readonly string[] | undefined): ResolvedPromptConfig;
|
|
5634
|
+
/**
|
|
5635
|
+
* Runtime adapter interface.
|
|
5636
|
+
*
|
|
5637
|
+
* Defines the minimal contract between the platform-agnostic core and
|
|
5638
|
+
* the host runtime (Node.js, Bun, Deno). Every platform-dependent
|
|
5639
|
+
* operation flows through this interface — the core never calls
|
|
5640
|
+
* `process.*`, `Deno.*`, or `Bun.*` directly.
|
|
5641
|
+
*
|
|
5642
|
+
* Adapters are designed to be:
|
|
5643
|
+
* - **Immutable in shape:** all properties are readonly
|
|
5644
|
+
* - **Minimal:** only the operations the framework actually needs
|
|
5645
|
+
* - **Testable:** easily stubbed in tests via {@linkcode createTestAdapter | createTestAdapter()}
|
|
5646
|
+
*
|
|
5647
|
+
* @example
|
|
5648
|
+
* ```ts
|
|
5649
|
+
* // Production: auto-detected
|
|
5650
|
+
* cli('mycli').run(); // uses Node/Bun/Deno adapter
|
|
5651
|
+
*
|
|
5652
|
+
* // Test: explicit adapter
|
|
5653
|
+
* cli('mycli').run({ adapter: createTestAdapter({ argv: ['deploy'] }) });
|
|
5654
|
+
* ```
|
|
5655
|
+
*/
|
|
5656
|
+
interface RuntimeAdapter {
|
|
5657
|
+
/** Raw argv array (including binary + script path, e.g. `['node', 'cli.js', 'deploy']`). */
|
|
5658
|
+
readonly argv: readonly string[];
|
|
5659
|
+
/**
|
|
5660
|
+
* Environment variables.
|
|
5661
|
+
* Values are `string | undefined` — mirrors Node's `process.env` semantics.
|
|
5662
|
+
*/
|
|
5663
|
+
readonly env: Readonly<Record<string, string | undefined>>;
|
|
5664
|
+
/** Current working directory (absolute path). */
|
|
5665
|
+
readonly cwd: string;
|
|
5666
|
+
/** Writer for stdout. Framework routes `out.log`/`out.info` through this. */
|
|
5667
|
+
readonly stdout: WriteFn;
|
|
5668
|
+
/** Writer for stderr. Framework routes `out.warn`/`out.error` through this. */
|
|
5669
|
+
readonly stderr: WriteFn;
|
|
5670
|
+
/** Wait for pending output writes to settle, rejecting with a recorded output failure. */
|
|
5671
|
+
readonly flush?: () => Promise<void>;
|
|
5672
|
+
/**
|
|
5673
|
+
* Line reader for stdin. Used by the prompt engine for interactive input.
|
|
5674
|
+
*
|
|
5675
|
+
* Returns `null` on EOF (Ctrl+D on Unix, Ctrl+Z on Windows),
|
|
5676
|
+
* indicating the user closed the input stream (treated as cancel).
|
|
5677
|
+
*/
|
|
5678
|
+
readonly stdin: ReadFn;
|
|
5679
|
+
/** Hidden terminal input. Absent when echo suppression is unsupported. */
|
|
5680
|
+
readonly readSecret?: ReadFn;
|
|
5681
|
+
/**
|
|
5682
|
+
* Read all of stdin as a single string (for piped data).
|
|
5683
|
+
*
|
|
5684
|
+
* Returns the full stdin contents when data is piped (`stdinIsTTY` is
|
|
5685
|
+
* false), or `null` when stdin is a TTY (no piped data available).
|
|
5686
|
+
*
|
|
5687
|
+
* Used by the resolve chain for args with `.stdin()` configured.
|
|
5688
|
+
* Unlike {@link stdin} (which reads one line for prompts), this
|
|
5689
|
+
* consumes the entire stream to EOF.
|
|
5690
|
+
*
|
|
5691
|
+
* @returns Full stdin contents as a string, or `null` if stdin is a TTY.
|
|
5692
|
+
*/
|
|
5693
|
+
readonly readStdin: () => Promise<string | null>;
|
|
5694
|
+
/** Whether stdout is connected to a TTY. */
|
|
5695
|
+
readonly isTTY: boolean;
|
|
5696
|
+
/** Whether stdin is connected to a TTY (used for prompt gating). */
|
|
5697
|
+
readonly stdinIsTTY: boolean;
|
|
5698
|
+
/** Read current terminal dimensions for stdout, if available. */
|
|
5699
|
+
readonly getTerminalSize: () => TerminalSize | undefined;
|
|
5700
|
+
/** Subscribe to terminal resize events when the runtime supports them. */
|
|
5701
|
+
readonly onTerminalResize: (listener: () => void) => (() => void) | undefined;
|
|
5702
|
+
/**
|
|
5703
|
+
* Exit the process with the given code.
|
|
5704
|
+
* Must not return (divergent function).
|
|
5705
|
+
*/
|
|
5706
|
+
readonly exit: (code: number) => never;
|
|
5707
|
+
/**
|
|
5708
|
+
* Read a file as UTF-8 text.
|
|
5709
|
+
*
|
|
5710
|
+
* Returns file contents on success, `null` if the file does not exist
|
|
5711
|
+
* (ENOENT/NotFound). Throws on other I/O errors (permission denied,
|
|
5712
|
+
* is-directory, etc.) — those indicate unexpected failures, not
|
|
5713
|
+
* "try the next path".
|
|
5714
|
+
*
|
|
5715
|
+
* Used by config file discovery to probe multiple candidate paths.
|
|
5716
|
+
*/
|
|
5717
|
+
readonly readFile: (path: string) => Promise<string | null>;
|
|
5718
|
+
/**
|
|
5719
|
+
* Probe what exists at a filesystem path.
|
|
5720
|
+
*
|
|
5721
|
+
* Returns `'file'` or `'directory'` for existing paths (other kinds such
|
|
5722
|
+
* as sockets report `'file'`), or `null` when nothing exists there.
|
|
5723
|
+
*
|
|
5724
|
+
* Used by `flag.path()` existence/type checks after resolution.
|
|
5725
|
+
*/
|
|
5726
|
+
readonly stat: (path: string) => Promise<'file' | 'directory' | null>;
|
|
5727
|
+
/**
|
|
5728
|
+
* Create a directory, including missing parents.
|
|
5729
|
+
*
|
|
5730
|
+
* Succeeds when the directory already exists. Throws on other I/O errors
|
|
5731
|
+
* (permission denied, existing file at the path, etc.).
|
|
5732
|
+
*
|
|
5733
|
+
* Used by `flag.path()` `create` checks after resolution.
|
|
5734
|
+
*/
|
|
5735
|
+
readonly mkdir: (path: string) => Promise<void>;
|
|
5736
|
+
/**
|
|
5737
|
+
* User home directory (absolute path).
|
|
5738
|
+
*
|
|
5739
|
+
* - Node/Bun: derived from `HOME` / `USERPROFILE` env
|
|
5740
|
+
* - Deno: `Deno.env.get('HOME')` / `Deno.env.get('USERPROFILE')`
|
|
5741
|
+
*/
|
|
5742
|
+
readonly homedir: string;
|
|
5743
|
+
/**
|
|
5744
|
+
* Platform-specific user configuration directory (absolute path).
|
|
5745
|
+
*
|
|
5746
|
+
* - Unix: `$XDG_CONFIG_HOME` or `~/.config`
|
|
5747
|
+
* - Windows: `%APPDATA%` or `~\AppData\Roaming`
|
|
5748
|
+
*
|
|
5749
|
+
* Config discovery appends the app-specific subdirectory.
|
|
5750
|
+
*/
|
|
5751
|
+
readonly configDir: string;
|
|
5752
|
+
/**
|
|
5753
|
+
* User-scope config roots for discovery, highest priority first.
|
|
5754
|
+
*
|
|
5755
|
+
* - Unix: `[configDir]`
|
|
5756
|
+
* - macOS: `[configDir, ~/Library/Application Support]`
|
|
5757
|
+
* - Windows: `[configDir]`
|
|
5758
|
+
*
|
|
5759
|
+
* When absent, discovery falls back to `[configDir]`.
|
|
5760
|
+
*/
|
|
5761
|
+
readonly userConfigDirs?: readonly string[];
|
|
5762
|
+
/**
|
|
5763
|
+
* System-scope config roots for discovery (`['/etc']` on Linux and
|
|
5764
|
+
* macOS, `[]` on Windows). When absent, discovery probes none.
|
|
5765
|
+
*/
|
|
5766
|
+
readonly systemConfigDirs?: readonly string[];
|
|
5767
|
+
}
|
|
5768
|
+
/** Current terminal dimensions in columns and rows. */
|
|
5769
|
+
interface TerminalSize {
|
|
5770
|
+
/** Terminal width in columns. */
|
|
5771
|
+
readonly columns: number;
|
|
5772
|
+
/** Terminal height in rows. */
|
|
5773
|
+
readonly rows: number;
|
|
5774
|
+
}
|
|
5775
|
+
/**
|
|
5776
|
+
* Options for creating a test adapter.
|
|
5777
|
+
*
|
|
5778
|
+
* All fields are optional — sensible defaults are applied for testing
|
|
5779
|
+
* scenarios (empty argv, empty env, noop stdout/stderr, non-TTY, exit
|
|
5780
|
+
* throws instead of killing the process).
|
|
5781
|
+
*/
|
|
5782
|
+
interface TestAdapterOptions {
|
|
5783
|
+
/** Raw argv (defaults to `['node', 'test']`). */
|
|
5784
|
+
readonly argv?: readonly string[];
|
|
5785
|
+
/** Environment variables (defaults to `{}`). */
|
|
5786
|
+
readonly env?: Readonly<Record<string, string | undefined>>;
|
|
5787
|
+
/** Working directory (defaults to `'/test'`). */
|
|
5788
|
+
readonly cwd?: string;
|
|
5789
|
+
/** Stdout writer (defaults to noop). */
|
|
5790
|
+
readonly stdout?: WriteFn;
|
|
5791
|
+
/** Stderr writer (defaults to noop). */
|
|
5792
|
+
readonly stderr?: WriteFn;
|
|
5793
|
+
/**
|
|
5794
|
+
* Stdin line reader (defaults to returning `null` — immediate EOF).
|
|
5795
|
+
*
|
|
5796
|
+
* Use a custom {@linkcode ReadFn} to simulate user input in tests.
|
|
5797
|
+
*/
|
|
5798
|
+
readonly stdin?: ReadFn;
|
|
5799
|
+
/** Hidden reader stub; omitted adapters report unsupported hidden input. */
|
|
5800
|
+
readonly readSecret?: ReadFn;
|
|
5801
|
+
/**
|
|
5802
|
+
* Piped stdin data for testing args with `.stdin()` configured.
|
|
5803
|
+
*
|
|
5804
|
+
* When provided and `stdinIsTTY` is `false`, `readStdin()` returns this
|
|
5805
|
+
* string once, then `null` on subsequent reads. When absent, or when
|
|
5806
|
+
* `stdinIsTTY` is `true`, `readStdin()` returns `null`.
|
|
5807
|
+
*
|
|
5808
|
+
* @example
|
|
5809
|
+
* ```ts
|
|
5810
|
+
* createTestAdapter({
|
|
5811
|
+
* stdinData: '{"key": "value"}',
|
|
5812
|
+
* })
|
|
5813
|
+
* ```
|
|
5814
|
+
*/
|
|
5815
|
+
readonly stdinData?: string;
|
|
5816
|
+
/** TTY flag for stdout (defaults to `false`). */
|
|
5817
|
+
readonly isTTY?: boolean;
|
|
5818
|
+
/** TTY flag for stdin (defaults to `false`). */
|
|
5819
|
+
readonly stdinIsTTY?: boolean;
|
|
5820
|
+
/** Terminal dimensions returned by `getTerminalSize()`. */
|
|
5821
|
+
readonly terminalSize?: TerminalSize;
|
|
5822
|
+
/** Resize subscription hook returned by `onTerminalResize()`. */
|
|
5823
|
+
readonly onTerminalResize?: (listener: () => void) => (() => void) | undefined;
|
|
5824
|
+
/**
|
|
5825
|
+
* Exit function (defaults to throwing {@linkcode ExitError}).
|
|
5826
|
+
* The default throw-based exit allows tests to catch the exit code.
|
|
5827
|
+
*/
|
|
5828
|
+
readonly exit?: (code: number) => never;
|
|
5829
|
+
/**
|
|
5830
|
+
* File reader stub (defaults to returning `null` — all files not found).
|
|
5831
|
+
*
|
|
5832
|
+
* Supply a custom function to simulate a virtual filesystem in tests:
|
|
5833
|
+
* ```ts
|
|
5834
|
+
* createTestAdapter({
|
|
5835
|
+
* readFile: (path) => Promise.resolve(
|
|
5836
|
+
* path === '/home/test/.config/myapp/config.json'
|
|
5837
|
+
* ? '{"region":"eu"}'
|
|
5838
|
+
* : null
|
|
5839
|
+
* ),
|
|
5840
|
+
* })
|
|
5841
|
+
* ```
|
|
5842
|
+
*/
|
|
5843
|
+
readonly readFile?: (path: string) => Promise<string | null>;
|
|
5844
|
+
/**
|
|
5845
|
+
* Filesystem probe stub for `flag.path()` checks (defaults to returning
|
|
5846
|
+
* `null` — nothing exists).
|
|
5847
|
+
*
|
|
5848
|
+
* Supply a custom function to simulate a virtual filesystem in tests:
|
|
5849
|
+
* ```ts
|
|
5850
|
+
* createTestAdapter({
|
|
5851
|
+
* stat: (path) => Promise.resolve(path === '/data' ? 'directory' : null),
|
|
5852
|
+
* })
|
|
5853
|
+
* ```
|
|
5854
|
+
*/
|
|
5855
|
+
readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
|
|
5856
|
+
/**
|
|
5857
|
+
* Directory creation stub for `flag.path()` `create` checks (defaults to
|
|
5858
|
+
* a noop that resolves without creating anything).
|
|
5859
|
+
*/
|
|
5860
|
+
readonly mkdir?: (path: string) => Promise<void>;
|
|
5861
|
+
/** Home directory (defaults to `'/home/test'`). */
|
|
5862
|
+
readonly homedir?: string;
|
|
5863
|
+
/** Config directory (defaults to `'/home/test/.config'`). */
|
|
5864
|
+
readonly configDir?: string;
|
|
5865
|
+
/** User-scope config roots for discovery (defaults to `[configDir]`). */
|
|
5866
|
+
readonly userConfigDirs?: readonly string[];
|
|
5867
|
+
/** System-scope config roots for discovery (defaults to `[]`). */
|
|
5868
|
+
readonly systemConfigDirs?: readonly string[];
|
|
5869
|
+
}
|
|
5870
|
+
/**
|
|
5871
|
+
* Error thrown by adapter implementations that model process exit as an
|
|
5872
|
+
* exception instead of terminating immediately.
|
|
5873
|
+
*
|
|
5874
|
+
* Runtime and CLI dispatch layers can catch this to perform real process
|
|
5875
|
+
* termination, while tests can assert on exit codes without killing the
|
|
5876
|
+
* runner:
|
|
5877
|
+
*
|
|
5878
|
+
* ```ts
|
|
5879
|
+
* try {
|
|
5880
|
+
* await cli.run({ adapter: createTestAdapter() });
|
|
5881
|
+
* } catch (e) {
|
|
5882
|
+
* if (e instanceof ExitError) expect(e.code).toBe(0);
|
|
5883
|
+
* }
|
|
5884
|
+
* ```
|
|
5885
|
+
*/
|
|
5886
|
+
declare class ExitError extends Error {
|
|
5887
|
+
/** Error name — always `'ExitError'` for `instanceof` checks. */
|
|
5888
|
+
readonly name = "ExitError";
|
|
5889
|
+
/** The exit code passed to `exit()`. */
|
|
5890
|
+
readonly code: number;
|
|
5891
|
+
/** Create an ExitError for the given process exit code. */
|
|
5892
|
+
constructor(code: number);
|
|
5893
|
+
}
|
|
5894
|
+
/**
|
|
5895
|
+
* Create a test runtime adapter with injectable process state.
|
|
5896
|
+
*
|
|
5897
|
+
* Use this in `@kjanat/dreamcli/testkit` tests when you need to simulate argv,
|
|
5898
|
+
* environment variables, TTY state, stdin, or config-file reads without
|
|
5899
|
+
* touching the host process.
|
|
5900
|
+
*
|
|
5901
|
+
* @param options - Optional overrides for any adapter field.
|
|
5902
|
+
* @returns A {@linkcode RuntimeAdapter} suitable for test scenarios.
|
|
5903
|
+
*
|
|
5904
|
+
* @example
|
|
5905
|
+
* ```ts
|
|
5906
|
+
* const adapter = createTestAdapter({
|
|
5907
|
+
* argv: ['node', 'cli.js', 'deploy', '--force'],
|
|
5908
|
+
* env: { DEPLOY_REGION: 'us' },
|
|
5909
|
+
* });
|
|
5910
|
+
*
|
|
5911
|
+
* const result = await cli('mycli').run({ adapter });
|
|
5912
|
+
* ```
|
|
5913
|
+
*/
|
|
5914
|
+
declare function createTestAdapter(options?: TestAdapterOptions): RuntimeAdapter;
|
|
5531
5915
|
/**
|
|
5532
5916
|
* Minimal I/O seam — the only write primitive the output module depends on.
|
|
5533
5917
|
*
|
|
@@ -5581,6 +5965,12 @@ interface OutputOptions {
|
|
|
5581
5965
|
* Defaults to `false` (safe default — non-TTY until proven otherwise).
|
|
5582
5966
|
*/
|
|
5583
5967
|
readonly isTTY?: boolean;
|
|
5968
|
+
/**
|
|
5969
|
+
* Read the terminal's current dimensions before concurrent activity redraws.
|
|
5970
|
+
* `.run()` supplies the runtime adapter's getter. Without usable dimensions,
|
|
5971
|
+
* concurrent activities emit static start and completion messages.
|
|
5972
|
+
*/
|
|
5973
|
+
readonly getTerminalSize?: () => TerminalSize | undefined;
|
|
5584
5974
|
/**
|
|
5585
5975
|
* Verbosity level.
|
|
5586
5976
|
* - `'normal'` (default) — emit all messages
|
|
@@ -5700,4 +6090,4 @@ interface CapturedOutput {
|
|
|
5700
6090
|
* ```
|
|
5701
6091
|
*/
|
|
5702
6092
|
declare function createCaptureOutput(options?: Omit<OutputOptions, 'stdout' | 'stderr'>): [out: Out, captured: CapturedOutput];
|
|
5703
|
-
export {
|
|
6093
|
+
export { ArgConfig as $, ActivityEvent as $n, InferFlag as $t, ExampleMeta as A, StandardSchemaV1SuccessResult as An, SplitFormat as At, InputSources as B, SelectChoice as Bn, EnumFlagDefinition as Bt, CommandExample as C, StandardSchemaV1 as Cn, arg as Ct, DeriveParams as D, StandardSchemaV1PathSegment as Dn, SPLIT_FORMATS as Dt, DeriveHandler as E, StandardSchemaV1Options as En, DuplicateKeys as Et, Out as F, PasswordPromptConfig as Fn, BooleanFlagDefinition as Ft, MiddlewareHandler as G, IndexedEnvBinding as Gn, FlagDefinitionByKind as Gt, SourcesOf as H, NumberConstraintViolation as Hn, FlagConfig as Ht, command as I, PromptConfig as In, CountFlagDefinition as It, Ask as J, CompletionContext as Jn, FlagKind as Jt, MiddlewareParams as K, IndexedRecordEnvBinding as Kn, FlagDefinitionOverrides as Kt, createCommandSchema as L, PromptConfigBase as Ln, CustomFlagDefinition as Lt, InteractiveParams as M, ConfirmPromptConfig as Mn, SplitPolicy as Mt, InteractiveResolver as N, InputPromptConfig as Nn, SplitSetting as Nt, ErasedActionHandler as O, StandardSchemaV1Props as On, SourceSplitBinding as Ot, InteractiveResult as P, MultiselectPromptConfig as Pn, ArrayFlagDefinition as Pt, ArgBuilder as Q, HelpThemeFactory as Qn, FlagSchema as Qt, group as R, PromptKind as Rn, DefaultValueOptions as Rt, CommandDefinition as S, InferStandardOutput as Sn, WithoutArgElementEligibility as St, CommandSchema as T, StandardSchemaV1Issue as Tn, DUPLICATE_KEYS as Tt, wasExplicit as U, NumberConstraints as Un, FlagDefinition as Ut, ResolutionProvenance as V, SelectPromptConfig as Vn, FlagBuilder as Vt, Middleware as W, EnvOptions as Wn, FlagDefinitionBase as Wt, prompt as X, HelpDescription as Xn, FlagParseFn as Xt, InferPrompt as Y, CompletionHandler as Yn, FlagNegation as Yt, Verbosity as Z, HelpTheme as Zn, FlagPresence as Zt, ActionHandler as _, StdinBinding as _n, ResolvedArgValue as _t, WriteFn as a, StringFlagDefinition as an, TableColumn as ar, ArgFactory as at, CommandArgEntryDefinition as b, StdinWhen as bn, WithArgPresence as bt, TerminalSize as c, createFlagSchema as cn, TableStream as cr, ArgPresence as ct, PromptEngine as d, DateFlagOptions as dn, CustomArgDefinition as dt, InferFlags as en, Fallback as er, ArgDefaultValue as et, ReadFn as f, PathChecks as fn, EnumArgDefinition as ft, resolvePromptConfig as g, StringConstraints as gn, NumberArgDefinition as gt, ResolvedSelectPromptConfig as h, StringConstraintViolation as hn, KeyValueArgDefinition as ht, createOutput as i, StringElementConfig as in, SpinnerOptions as ir, ArgDefinitionOverrides as it, ExecutionStep as j, StandardSchemaV1Types as jn, SplitOptions as jt, ExampleCommand as k, StandardSchemaV1Result as kn, SplitBinding as kt, TestAdapterOptions as l, flag as ln, schemaBrand as lr, ArgSchema as lt, ResolvedPromptConfig as m, UrlFlagOptions as mn, InferArgs as mt, OutputOptions as n, NumberFlagDefinition as nn, ProgressOptions as nr, ArgDefinitionBase as nt, ExitError as o, WithPresence as on, TableFormat as or, ArgKind as ot, ResolvedMultiselectPromptConfig as p, PathFlagOptions as pn, InferArg as pt, middleware as q, IndexedValueEnvBinding as qn, FlagFactory as qt, createCaptureOutput as r, ResolvedValue as rn, SpinnerHandle as rr, ArgDefinitionByKind as rt, RuntimeAdapter as s, WithoutElementEligibility as sn, TableOptions as sr, ArgParseFn as st, CapturedOutput as t, KeyValueFlagDefinition as tn, ProgressHandle as tr, ArgDefinition as tt, createTestAdapter as u, getFlagNegatedName as un, BooleanArgDefinition as ut, ActionParams as v, StdinConsume as vn, StringArgDefinition as vt, CommandMeta as w, StandardSchemaV1FailureResult as wn, createArgSchema as wt, CommandBuilder as x, InferStandardInput as xn, WithVariadic as xt, CommandArgEntry as y, StdinOptions as yn, StringArgElementConfig as yt, resolveExampleCommand as z, PromptResult as zn, DuplicatePolicy as zt };
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { $n as ActivityEvent, F as Out, Qn as HelpThemeFactory, T as CommandSchema, V as ResolutionProvenance, Z as Verbosity, d as PromptEngine, fn as PathChecks, lr as schemaBrand, w as CommandMeta } from "./index-CuhI1Ynv.mjs";
|
|
2
2
|
import { t as CLIError } from "./index-D683D09G.mjs";
|
|
3
3
|
import { Colors } from "ansispeck";
|
|
4
4
|
/** A built-in flag a consumer can take over. */
|
|
@@ -767,6 +767,12 @@ interface RunOptions {
|
|
|
767
767
|
* @defaultValue `false`
|
|
768
768
|
*/
|
|
769
769
|
readonly isTTY?: boolean;
|
|
770
|
+
/**
|
|
771
|
+
* Explicitly enable or disable ANSI color, overriding automatic selection.
|
|
772
|
+
* Otherwise, `env.NO_COLOR` disables color and `env.FORCE_COLOR` enables it
|
|
773
|
+
* unless set to `'0'`. With neither set, color follows `isTTY` outside JSON mode.
|
|
774
|
+
*/
|
|
775
|
+
readonly color?: boolean;
|
|
770
776
|
/**
|
|
771
777
|
* Help formatting options (width, binName).
|
|
772
778
|
* Used when `--help` is detected.
|
|
@@ -1,7 +1,6 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
4
|
-
import { h as PackageJsonData, s as FormatLoader } from "./index-jq_FJRKt.mjs";
|
|
1
|
+
import { A as Builtins, j as BuiltinsConfig, n as RunResult, t as RunOptions, u as CLIPlugin, x as ParseOptions } from "./index-DDhRLoTu.mjs";
|
|
2
|
+
import { h as PackageJsonData, s as FormatLoader } from "./index-DIWRV_wp.mjs";
|
|
3
|
+
import { $ as ArgConfig, Ht as FlagConfig, O as ErasedActionHandler, Q as ArgBuilder, Qn as HelpThemeFactory, S as CommandDefinition, T as CommandSchema, Vt as FlagBuilder, Z as Verbosity, j as ExecutionStep, lr as schemaBrand, s as RuntimeAdapter, x as CommandBuilder } from "./index-CuhI1Ynv.mjs";
|
|
5
4
|
import { Colors } from "ansispeck";
|
|
6
5
|
/**
|
|
7
6
|
* Options for completion script generation.
|
|
@@ -589,7 +588,8 @@ interface RenderContextOptions {
|
|
|
589
588
|
*/
|
|
590
589
|
readonly color?: boolean;
|
|
591
590
|
/**
|
|
592
|
-
* Environment variables consulted for `
|
|
591
|
+
* Environment variables consulted for `NO_COLOR`/`FORCE_COLOR` and
|
|
592
|
+
* `NO_HYPERLINKS`/`FORCE_HYPERLINKS`
|
|
593
593
|
* (e.g. `process.env`).
|
|
594
594
|
*
|
|
595
595
|
* @defaultValue `{}`
|