politty 0.4.12 → 0.4.14
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/README.md +11 -8
- package/dist/{arg-registry-BlXeCM4p.d.cts → arg-registry-CkPDokIu.d.ts} +236 -13
- package/dist/arg-registry-CkPDokIu.d.ts.map +1 -0
- package/dist/{arg-registry-D0MimRYf.d.ts → arg-registry-r5wYN6qd.d.cts} +236 -13
- package/dist/arg-registry-r5wYN6qd.d.cts.map +1 -0
- package/dist/augment.d.cts +3 -2
- package/dist/augment.d.cts.map +1 -1
- package/dist/augment.d.ts +3 -2
- package/dist/augment.d.ts.map +1 -1
- package/dist/completion/index.cjs +1 -2
- package/dist/completion/index.d.cts +1 -1
- package/dist/completion/index.d.ts +1 -1
- package/dist/completion/index.js +1 -2
- package/dist/{completion-BADAzqT9.cjs → completion-CAekGYS4.cjs} +24 -14
- package/dist/completion-CAekGYS4.cjs.map +1 -0
- package/dist/{completion-Dj7ytbLu.js → completion-yHz8Pdr7.js} +23 -13
- package/dist/completion-yHz8Pdr7.js.map +1 -0
- package/dist/docs/index.cjs +50 -19
- package/dist/docs/index.cjs.map +1 -1
- package/dist/docs/index.d.cts +1 -2
- package/dist/docs/index.d.cts.map +1 -1
- package/dist/docs/index.d.ts +1 -2
- package/dist/docs/index.d.ts.map +1 -1
- package/dist/docs/index.js +50 -19
- package/dist/docs/index.js.map +1 -1
- package/dist/{index-CBGSQVm9.d.ts → index-BLySW_2k.d.ts} +7 -5
- package/dist/index-BLySW_2k.d.ts.map +1 -0
- package/dist/{index-f2-VIfCo.d.cts → index-DPswv0Vt.d.cts} +7 -5
- package/dist/index-DPswv0Vt.d.cts.map +1 -0
- package/dist/index.cjs +3 -3
- package/dist/index.d.cts +3 -4
- package/dist/index.d.cts.map +1 -1
- package/dist/index.d.ts +3 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -3
- package/dist/{lazy-B_E2X0KR.cjs → lazy-AGV9Pkt5.cjs} +40 -4
- package/dist/lazy-AGV9Pkt5.cjs.map +1 -0
- package/dist/{lazy-D6nL_iKJ.js → lazy-DiMJSDMB.js} +34 -4
- package/dist/lazy-DiMJSDMB.js.map +1 -0
- package/dist/prompt/clack/index.cjs +34 -0
- package/dist/prompt/clack/index.cjs.map +1 -0
- package/dist/prompt/clack/index.d.cts +18 -0
- package/dist/prompt/clack/index.d.cts.map +1 -0
- package/dist/prompt/clack/index.d.ts +18 -0
- package/dist/prompt/clack/index.d.ts.map +1 -0
- package/dist/prompt/clack/index.js +32 -0
- package/dist/prompt/clack/index.js.map +1 -0
- package/dist/prompt/index.cjs +7 -0
- package/dist/prompt/index.d.cts +108 -0
- package/dist/prompt/index.d.cts.map +1 -0
- package/dist/prompt/index.d.ts +108 -0
- package/dist/prompt/index.d.ts.map +1 -0
- package/dist/prompt/index.js +3 -0
- package/dist/prompt/inquirer/index.cjs +49 -0
- package/dist/prompt/inquirer/index.cjs.map +1 -0
- package/dist/prompt/inquirer/index.d.cts +18 -0
- package/dist/prompt/inquirer/index.d.cts.map +1 -0
- package/dist/prompt/inquirer/index.d.ts +18 -0
- package/dist/prompt/inquirer/index.d.ts.map +1 -0
- package/dist/prompt/inquirer/index.js +47 -0
- package/dist/prompt/inquirer/index.js.map +1 -0
- package/dist/prompt-BKHqGrFw.js +172 -0
- package/dist/prompt-BKHqGrFw.js.map +1 -0
- package/dist/prompt-aXfSf27y.cjs +196 -0
- package/dist/prompt-aXfSf27y.cjs.map +1 -0
- package/dist/{runner-U86FIDHT.cjs → runner-CY5fOsSh.cjs} +90 -38
- package/dist/runner-CY5fOsSh.cjs.map +1 -0
- package/dist/{runner-Bx2S6_Id.js → runner-DSZw1AsW.js} +90 -38
- package/dist/runner-DSZw1AsW.js.map +1 -0
- package/dist/{subcommand-router-Bu3YTw_f.js → subcommand-router--EUt6ftA.js} +2 -2
- package/dist/{subcommand-router-Bu3YTw_f.js.map → subcommand-router--EUt6ftA.js.map} +1 -1
- package/dist/{subcommand-router-BTOzDQnY.cjs → subcommand-router-C9ONv6Nq.cjs} +2 -2
- package/dist/{subcommand-router-BTOzDQnY.cjs.map → subcommand-router-C9ONv6Nq.cjs.map} +1 -1
- package/package.json +53 -11
- package/dist/arg-registry-BlXeCM4p.d.cts.map +0 -1
- package/dist/arg-registry-D0MimRYf.d.ts.map +0 -1
- package/dist/completion-BADAzqT9.cjs.map +0 -1
- package/dist/completion-Dj7ytbLu.js.map +0 -1
- package/dist/index-CBGSQVm9.d.ts.map +0 -1
- package/dist/index-f2-VIfCo.d.cts.map +0 -1
- package/dist/lazy-B_E2X0KR.cjs.map +0 -1
- package/dist/lazy-D6nL_iKJ.js.map +0 -1
- package/dist/runner-Bx2S6_Id.js.map +0 -1
- package/dist/runner-U86FIDHT.cjs.map +0 -1
- package/dist/schema-extractor-CAZi3kK1.d.ts +0 -117
- package/dist/schema-extractor-CAZi3kK1.d.ts.map +0 -1
- package/dist/schema-extractor-D-eGlm4W.d.cts +0 -117
- package/dist/schema-extractor-D-eGlm4W.d.cts.map +0 -1
package/README.md
CHANGED
|
@@ -13,6 +13,7 @@ From simple scripts to complex CLI tools with subcommands, validation, and auto-
|
|
|
13
13
|
- **Lifecycle Management**: Guaranteed `setup` → `run` → `cleanup` execution order
|
|
14
14
|
- **Signal Handling**: Proper SIGINT/SIGTERM handling with guaranteed cleanup execution
|
|
15
15
|
- **Auto Help Generation**: Automatically generate help text from definitions
|
|
16
|
+
- **Interactive Prompts**: Prompt for missing arguments with pluggable adapters (clack, inquirer)
|
|
16
17
|
- **Discriminated Union**: Support for mutually exclusive argument sets
|
|
17
18
|
|
|
18
19
|
## Requirements
|
|
@@ -278,14 +279,15 @@ if (result.success) {
|
|
|
278
279
|
|
|
279
280
|
Attach metadata to an argument.
|
|
280
281
|
|
|
281
|
-
| Metadata | Type
|
|
282
|
-
| ------------- |
|
|
283
|
-
| `positional` | `boolean?`
|
|
284
|
-
| `alias` | `string?`
|
|
285
|
-
| `description` | `string?`
|
|
286
|
-
| `placeholder` | `string?`
|
|
287
|
-
| `env` | `string?`
|
|
288
|
-
| `completion` | `object?`
|
|
282
|
+
| Metadata | Type | Description |
|
|
283
|
+
| ------------- | ------------- | ------------------------------------------------------------------------ |
|
|
284
|
+
| `positional` | `boolean?` | Treat as positional argument |
|
|
285
|
+
| `alias` | `string?` | Short alias (e.g., `-v`) |
|
|
286
|
+
| `description` | `string?` | Argument description |
|
|
287
|
+
| `placeholder` | `string?` | Placeholder shown in help |
|
|
288
|
+
| `env` | `string?` | Environment variable name (fallback) |
|
|
289
|
+
| `completion` | `object?` | Shell completion configuration |
|
|
290
|
+
| `prompt` | `PromptMeta?` | Interactive prompt configuration ([docs](./docs/interactive-prompts.md)) |
|
|
289
291
|
|
|
290
292
|
## Shell Completion
|
|
291
293
|
|
|
@@ -375,6 +377,7 @@ For detailed documentation, see the `docs/` directory:
|
|
|
375
377
|
- [Getting Started](./docs/getting-started.md) - Installation and creating your first command
|
|
376
378
|
- [Essentials](./docs/essentials.md) - Core concepts explained
|
|
377
379
|
- [Advanced Features](./docs/advanced-features.md) - Subcommands, Discriminated Union
|
|
380
|
+
- [Interactive Prompts](./docs/interactive-prompts.md) - Prompt for missing arguments interactively
|
|
378
381
|
- [Recipes](./docs/recipes.md) - Testing, configuration, error handling
|
|
379
382
|
- [API Reference](./docs/api-reference.md) - Detailed API reference
|
|
380
383
|
- [Doc Generation](./docs/doc-generation.md) - Automatic documentation generation
|
|
@@ -1,5 +1,128 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
2
|
|
|
3
|
+
//#region src/core/schema-extractor.d.ts
|
|
4
|
+
/**
|
|
5
|
+
* Resolved metadata for an argument field
|
|
6
|
+
*/
|
|
7
|
+
interface ResolvedFieldMeta {
|
|
8
|
+
/** Field name (camelCase, as defined in schema) */
|
|
9
|
+
name: string;
|
|
10
|
+
/** CLI option name (kebab-case, for command line usage) */
|
|
11
|
+
cliName: string;
|
|
12
|
+
/**
|
|
13
|
+
* Aliases for this option, normalized to an array.
|
|
14
|
+
* 1-char entries are short aliases (`-v`); multi-char entries are long
|
|
15
|
+
* aliases (`--to-be`).
|
|
16
|
+
*/
|
|
17
|
+
alias?: string[] | undefined;
|
|
18
|
+
/**
|
|
19
|
+
* Aliases that are accepted at parse time but hidden from help,
|
|
20
|
+
* generated docs, and shell completion.
|
|
21
|
+
*/
|
|
22
|
+
hiddenAlias?: string[] | undefined;
|
|
23
|
+
/** Argument description */
|
|
24
|
+
description?: string | undefined;
|
|
25
|
+
/** Whether this is a positional argument */
|
|
26
|
+
positional: boolean;
|
|
27
|
+
/** Placeholder for help display */
|
|
28
|
+
placeholder?: string | undefined;
|
|
29
|
+
/**
|
|
30
|
+
* Environment variable name(s) to read value from.
|
|
31
|
+
* If an array, earlier entries take priority.
|
|
32
|
+
*/
|
|
33
|
+
env?: string | string[] | undefined;
|
|
34
|
+
/** Whether this argument is required */
|
|
35
|
+
required: boolean;
|
|
36
|
+
/** Default value if any */
|
|
37
|
+
defaultValue?: unknown;
|
|
38
|
+
/** Detected type from schema */
|
|
39
|
+
type: "string" | "number" | "boolean" | "array" | "unknown";
|
|
40
|
+
/** Original Zod schema */
|
|
41
|
+
schema: z.ZodType;
|
|
42
|
+
/** True if this overrides built-in aliases (-h, -H) */
|
|
43
|
+
overrideBuiltinAlias?: true;
|
|
44
|
+
/** Enum values if detected from schema (z.enum) */
|
|
45
|
+
enumValues?: string[] | undefined;
|
|
46
|
+
/** Completion metadata from arg() */
|
|
47
|
+
completion?: CompletionMeta | undefined;
|
|
48
|
+
/** Prompt metadata from arg() for interactive input */
|
|
49
|
+
prompt?: PromptMeta | undefined;
|
|
50
|
+
/** Side-effect callback from arg() metadata */
|
|
51
|
+
effect?: ((value: unknown, context: EffectContext) => void | PromiseLike<void>) | undefined;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Extracted fields from a schema
|
|
55
|
+
*/
|
|
56
|
+
interface ExtractedFields {
|
|
57
|
+
/** All field definitions */
|
|
58
|
+
fields: ResolvedFieldMeta[];
|
|
59
|
+
/** Original schema for validation */
|
|
60
|
+
schema: ArgsSchema;
|
|
61
|
+
/** Schema type */
|
|
62
|
+
schemaType: "object" | "discriminatedUnion" | "union" | "xor" | "intersection";
|
|
63
|
+
/** Discriminator key (for discriminatedUnion) */
|
|
64
|
+
discriminator?: string;
|
|
65
|
+
/** Variants (for discriminatedUnion) */
|
|
66
|
+
variants?: Array<{
|
|
67
|
+
discriminatorValue: string;
|
|
68
|
+
fields: ResolvedFieldMeta[];
|
|
69
|
+
description?: string;
|
|
70
|
+
}>;
|
|
71
|
+
/** Options (for union) */
|
|
72
|
+
unionOptions?: ExtractedFields[];
|
|
73
|
+
/** Schema description */
|
|
74
|
+
description?: string;
|
|
75
|
+
/**
|
|
76
|
+
* Unknown keys handling mode
|
|
77
|
+
* - "strict": Unknown keys cause validation errors (z.strictObject or z.object().strict())
|
|
78
|
+
* - "strip": Unknown keys trigger warnings (default, z.object())
|
|
79
|
+
* - "passthrough": Unknown keys are silently ignored (z.looseObject or z.object().passthrough())
|
|
80
|
+
*/
|
|
81
|
+
unknownKeysMode: UnknownKeysMode;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Unknown keys handling mode for object schemas
|
|
85
|
+
* - "strict": Unknown keys cause validation errors
|
|
86
|
+
* - "strip": Unknown keys are silently ignored (default)
|
|
87
|
+
* - "passthrough": Unknown keys are passed through
|
|
88
|
+
*/
|
|
89
|
+
type UnknownKeysMode = "strict" | "strip" | "passthrough";
|
|
90
|
+
/**
|
|
91
|
+
* Detect unknown keys handling mode from a Zod object schema
|
|
92
|
+
*
|
|
93
|
+
* In Zod v4:
|
|
94
|
+
* - Default (strip): _def.catchall is undefined
|
|
95
|
+
* - strict: _def.catchall is ZodNever (type = "never")
|
|
96
|
+
* - passthrough: _def.catchall is ZodUnknown (type = "unknown")
|
|
97
|
+
*/
|
|
98
|
+
declare function getUnknownKeysMode(schema: z.ZodType): UnknownKeysMode;
|
|
99
|
+
/**
|
|
100
|
+
* Convert camelCase to kebab-case
|
|
101
|
+
* @example toKebabCase("dryRun") => "dry-run"
|
|
102
|
+
* @example toKebabCase("outputDir") => "output-dir"
|
|
103
|
+
* @example toKebabCase("XMLParser") => "xml-parser"
|
|
104
|
+
*/
|
|
105
|
+
declare function toKebabCase(str: string): string;
|
|
106
|
+
/**
|
|
107
|
+
* Convert hyphen-separated sequences to camelCase.
|
|
108
|
+
*
|
|
109
|
+
* Replaces `-x` (hyphen followed by a lowercase letter) with the uppercase
|
|
110
|
+
* variant. Non-hyphenated input (e.g., already camelCase) is returned as-is.
|
|
111
|
+
*
|
|
112
|
+
* @param str - A string that may contain hyphens
|
|
113
|
+
* @example toCamelCase("dry-run") => "dryRun"
|
|
114
|
+
* @example toCamelCase("output-dir") => "outputDir"
|
|
115
|
+
* @example toCamelCase("dryRun") => "dryRun"
|
|
116
|
+
*/
|
|
117
|
+
declare function toCamelCase(str: string): string;
|
|
118
|
+
/**
|
|
119
|
+
* Extract all fields from a schema
|
|
120
|
+
*
|
|
121
|
+
* @param schema - The args schema (ZodObject, ZodDiscriminatedUnion, etc.)
|
|
122
|
+
* @returns Extracted field information
|
|
123
|
+
*/
|
|
124
|
+
declare function extractFields(schema: ArgsSchema): ExtractedFields;
|
|
125
|
+
//#endregion
|
|
3
126
|
//#region src/lazy.d.ts
|
|
4
127
|
/**
|
|
5
128
|
* A lazily-loaded command that carries synchronous metadata for
|
|
@@ -184,6 +307,12 @@ type SubCommandValue = AnyCommand | (() => Promise<AnyCommand>) | LazyCommand;
|
|
|
184
307
|
* Record of subcommands indexed by name
|
|
185
308
|
*/
|
|
186
309
|
type SubCommandsRecord = Record<string, SubCommandValue>;
|
|
310
|
+
/**
|
|
311
|
+
* Async callback to resolve missing argument values interactively.
|
|
312
|
+
* Called after env fallback, before Zod validation.
|
|
313
|
+
* Provided by adapter subpath modules (e.g. `politty/prompt/clack`).
|
|
314
|
+
*/
|
|
315
|
+
type PromptResolver = (rawArgs: Record<string, unknown>, extracted: ExtractedFields) => Promise<Record<string, unknown>>;
|
|
187
316
|
/**
|
|
188
317
|
* Options for runMain (CLI entry point)
|
|
189
318
|
*/
|
|
@@ -206,6 +335,8 @@ interface MainOptions {
|
|
|
206
335
|
cleanup?: ((context: GlobalCleanupContext) => void | Promise<void>) | undefined;
|
|
207
336
|
/** Whether to display errors to stderr before process.exit (default: true) */
|
|
208
337
|
displayErrors?: boolean;
|
|
338
|
+
/** Prompt resolver for interactive missing-arg prompts (e.g. from `politty/prompt/clack`). */
|
|
339
|
+
prompt?: PromptResolver | undefined;
|
|
209
340
|
}
|
|
210
341
|
/**
|
|
211
342
|
* Options for runCommand (programmatic/test usage)
|
|
@@ -225,6 +356,8 @@ interface RunCommandOptions {
|
|
|
225
356
|
setup?: ((context: GlobalSetupContext) => void | Promise<void>) | undefined;
|
|
226
357
|
/** Global cleanup hook (runs after command execution, always executes even on error) */
|
|
227
358
|
cleanup?: ((context: GlobalCleanupContext) => void | Promise<void>) | undefined;
|
|
359
|
+
/** Prompt resolver for interactive missing-arg prompts (e.g. from `politty/prompt/clack`). */
|
|
360
|
+
prompt?: PromptResolver | undefined;
|
|
228
361
|
}
|
|
229
362
|
/**
|
|
230
363
|
* Log level type
|
|
@@ -344,6 +477,52 @@ type CompletionMeta = {
|
|
|
344
477
|
/** Glob patterns for file matching (only applies when type is "file") */matcher?: string[];
|
|
345
478
|
extensions?: never;
|
|
346
479
|
});
|
|
480
|
+
/**
|
|
481
|
+
* Prompt input type for interactive prompts
|
|
482
|
+
*
|
|
483
|
+
* - "text": free-form text input (default for string schemas)
|
|
484
|
+
* - "password": masked text input
|
|
485
|
+
* - "confirm": yes/no prompt (default for boolean schemas)
|
|
486
|
+
* - "select": single selection from choices (default for enum schemas)
|
|
487
|
+
* - "file": file path input (inherited from completion type)
|
|
488
|
+
* - "directory": directory path input (inherited from completion type)
|
|
489
|
+
*/
|
|
490
|
+
type PromptType = "text" | "password" | "confirm" | "select" | "file" | "directory";
|
|
491
|
+
/**
|
|
492
|
+
* Prompt metadata for interactive input when a value is missing.
|
|
493
|
+
* Used by the `politty/prompt` module to request user input for unresolved arguments.
|
|
494
|
+
*
|
|
495
|
+
* @example
|
|
496
|
+
* ```ts
|
|
497
|
+
* // Custom prompt message
|
|
498
|
+
* name: arg(z.string(), {
|
|
499
|
+
* prompt: { message: "What is your name?" }
|
|
500
|
+
* })
|
|
501
|
+
*
|
|
502
|
+
* // Password input (masked)
|
|
503
|
+
* token: arg(z.string(), {
|
|
504
|
+
* prompt: { type: "password", message: "Enter API token" }
|
|
505
|
+
* })
|
|
506
|
+
*
|
|
507
|
+
* // Select with custom choices
|
|
508
|
+
* region: arg(z.string(), {
|
|
509
|
+
* prompt: { choices: ["us-east-1", "eu-west-1", "ap-northeast-1"] }
|
|
510
|
+
* })
|
|
511
|
+
* ```
|
|
512
|
+
*/
|
|
513
|
+
interface PromptMeta {
|
|
514
|
+
/** Prompt message shown to the user. Defaults to the field's description or name. */
|
|
515
|
+
message?: string;
|
|
516
|
+
/** Explicit prompt type. Overrides auto-detection from schema/completion. */
|
|
517
|
+
type?: PromptType;
|
|
518
|
+
/** Choices for select prompt. Overrides enum values from schema. */
|
|
519
|
+
choices?: Array<string | {
|
|
520
|
+
label: string;
|
|
521
|
+
value: string;
|
|
522
|
+
}>;
|
|
523
|
+
/** Whether to enable prompting for this field (default: true when prompt is set) */
|
|
524
|
+
enabled?: boolean;
|
|
525
|
+
}
|
|
347
526
|
/**
|
|
348
527
|
* Context provided to effect callbacks.
|
|
349
528
|
* When GlobalArgs is extended via declaration merging, `globalArgs` is typed accordingly.
|
|
@@ -383,6 +562,20 @@ interface BaseArgMeta<TValue = unknown> {
|
|
|
383
562
|
env?: string | string[];
|
|
384
563
|
/** Completion configuration for shell tab-completion */
|
|
385
564
|
completion?: CompletionMeta;
|
|
565
|
+
/**
|
|
566
|
+
* Interactive prompt configuration for missing values.
|
|
567
|
+
* When set, the `politty/prompt` module will prompt the user interactively
|
|
568
|
+
* if this argument is not provided via CLI args or environment variables.
|
|
569
|
+
*
|
|
570
|
+
* @example
|
|
571
|
+
* ```ts
|
|
572
|
+
* name: arg(z.string(), {
|
|
573
|
+
* description: "User name",
|
|
574
|
+
* prompt: { message: "What is your name?" },
|
|
575
|
+
* })
|
|
576
|
+
* ```
|
|
577
|
+
*/
|
|
578
|
+
prompt?: PromptMeta;
|
|
386
579
|
/**
|
|
387
580
|
* Side-effect callback executed after argument parsing and validation.
|
|
388
581
|
* Runs before the command lifecycle (setup/run/cleanup).
|
|
@@ -402,17 +595,34 @@ interface BaseArgMeta<TValue = unknown> {
|
|
|
402
595
|
}
|
|
403
596
|
/**
|
|
404
597
|
* Metadata for regular arguments (non-builtin aliases)
|
|
598
|
+
*
|
|
599
|
+
* `alias` accepts either a single string or an array of strings.
|
|
600
|
+
* Single-character entries become short options (e.g. `-v`); multi-character
|
|
601
|
+
* entries become additional long options (e.g. `--to-be` for `--tobe`).
|
|
405
602
|
*/
|
|
406
603
|
interface RegularArgMeta<TValue = unknown> extends BaseArgMeta<TValue> {
|
|
407
|
-
/**
|
|
408
|
-
|
|
604
|
+
/**
|
|
605
|
+
* Alias name(s) for this option.
|
|
606
|
+
* - 1-char string → short alias (`-v`)
|
|
607
|
+
* - >1-char string → long alias (`--long-name`)
|
|
608
|
+
* - array → multiple aliases of either kind
|
|
609
|
+
*/
|
|
610
|
+
alias?: string | string[] | readonly string[];
|
|
611
|
+
/**
|
|
612
|
+
* Alias name(s) that are accepted by the parser but hidden from help,
|
|
613
|
+
* generated docs, and shell completion. Useful for legacy or deprecated
|
|
614
|
+
* names that should still work without being advertised.
|
|
615
|
+
*/
|
|
616
|
+
hiddenAlias?: string | string[] | readonly string[];
|
|
409
617
|
}
|
|
410
618
|
/**
|
|
411
619
|
* Metadata for overriding built-in aliases (-h, -H)
|
|
412
620
|
*/
|
|
413
621
|
interface BuiltinOverrideArgMeta<TValue = unknown> extends BaseArgMeta<TValue> {
|
|
414
|
-
/** Built-in alias to override ('h' or 'H') */
|
|
415
|
-
alias: "h" | "H"
|
|
622
|
+
/** Built-in alias to override ('h' or 'H'), optionally combined with extra aliases */
|
|
623
|
+
alias: "h" | "H" | Array<"h" | "H" | string> | ReadonlyArray<"h" | "H" | string>;
|
|
624
|
+
/** Hidden aliases (accepted but not surfaced in help/docs/completion) */
|
|
625
|
+
hiddenAlias?: string | string[] | readonly string[];
|
|
416
626
|
/** Must be true to override built-in aliases */
|
|
417
627
|
overrideBuiltinAlias: true;
|
|
418
628
|
}
|
|
@@ -444,18 +654,31 @@ type ArgMeta<TValue = unknown> = RegularArgMeta<TValue> | BuiltinOverrideArgMeta
|
|
|
444
654
|
* ```
|
|
445
655
|
*/
|
|
446
656
|
/**
|
|
447
|
-
*
|
|
448
|
-
*
|
|
657
|
+
* Detect whether `A` contains a reserved alias ("h" or "H"), for either a
|
|
658
|
+
* plain string or a tuple/array of strings. Uses `[A] extends [never]` to
|
|
659
|
+
* prevent distribution returning `never` for missing fields.
|
|
660
|
+
*/
|
|
661
|
+
type ContainsReservedAlias<A> = [A] extends [never] ? false : A extends "h" | "H" ? true : A extends readonly (infer E)[] ? [Extract<E, "h" | "H">] extends [never] ? false : true : false;
|
|
662
|
+
type ReservedAliasTypeError<M> = { [K in keyof M]: M[K] } & {
|
|
663
|
+
__typeError: "Alias 'h' or 'H' requires overrideBuiltinAlias: true";
|
|
664
|
+
};
|
|
665
|
+
type AliasFieldOf<M> = M extends {
|
|
666
|
+
alias: infer A;
|
|
667
|
+
} ? A : never;
|
|
668
|
+
type HiddenAliasFieldOf<M> = M extends {
|
|
669
|
+
hiddenAlias: infer H;
|
|
670
|
+
} ? H : never;
|
|
671
|
+
/**
|
|
672
|
+
* Type helper to validate ArgMeta.
|
|
673
|
+
* Forces a type error when a reserved alias ("h" / "H") is used without
|
|
674
|
+
* `overrideBuiltinAlias: true`, whether the alias is provided as a string
|
|
675
|
+
* or as part of an array, and whether it appears in `alias` or `hiddenAlias`.
|
|
449
676
|
*/
|
|
450
677
|
type ValidateArgMeta<M> = M extends {
|
|
451
|
-
alias: "h" | "H";
|
|
452
|
-
} ? M extends {
|
|
453
678
|
overrideBuiltinAlias: true;
|
|
454
|
-
} ? M :
|
|
455
|
-
__typeError: "Alias 'h' or 'H' requires overrideBuiltinAlias: true";
|
|
456
|
-
} : M;
|
|
679
|
+
} ? M : ContainsReservedAlias<AliasFieldOf<M>> extends true ? ReservedAliasTypeError<M> : ContainsReservedAlias<HiddenAliasFieldOf<M>> extends true ? ReservedAliasTypeError<M> : M;
|
|
457
680
|
declare function arg<T extends z.ZodType>(schema: T): T;
|
|
458
681
|
declare function arg<T extends z.ZodType, M extends ArgMeta<z.output<T>>>(schema: T, meta: ValidateArgMeta<M>): T;
|
|
459
682
|
//#endregion
|
|
460
|
-
export {
|
|
461
|
-
//# sourceMappingURL=arg-registry-
|
|
683
|
+
export { RunResultSuccess as A, UnknownKeysMode as B, Logger as C, RunCommandOptions as D, PromptResolver as E, LazyCommand as F, getUnknownKeysMode as H, isLazyCommand as I, lazy as L, SetupContext as M, SubCommandValue as N, RunResult as O, SubCommandsRecord as P, ExtractedFields as R, LogStream as S, NonRunnableCommand as T, toCamelCase as U, extractFields as V, toKebabCase as W, GlobalCleanupContext as _, EffectContext as a, LogEntry as b, arg as c, CleanupContext as d, CollectedLogs as f, GlobalArgs as g, Example as h, CustomCompletion as i, RunnableCommand as j, RunResultFailure as k, AnyCommand as l, CommandBase as m, CompletionMeta as n, PromptMeta as o, Command as p, CompletionType as r, PromptType as s, ArgMeta as t, ArgsSchema as u, GlobalSetupContext as v, MainOptions as w, LogLevel as x, IsEmpty as y, ResolvedFieldMeta as z };
|
|
684
|
+
//# sourceMappingURL=arg-registry-CkPDokIu.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"arg-registry-CkPDokIu.d.ts","names":[],"sources":["../src/core/schema-extractor.ts","../src/lazy.ts","../src/types.ts","../src/core/arg-registry.ts"],"mappings":"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"}
|