@kjanat/dreamcli 3.0.0-rc.7 → 3.0.0-rc.9
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 +71 -1
- package/dist/core/cli/dispatch.d.mts +6 -4
- package/dist/core/cli/dispatch.mjs +6 -4
- package/dist/core/cli/index.d.mts +27 -1
- package/dist/core/cli/index.mjs +32 -15
- package/dist/core/cli/planner.d.mts +3 -0
- package/dist/core/cli/planner.mjs +9 -9
- package/dist/core/cli/propagate.d.mts +1 -1
- package/dist/core/cli/root-help.mjs +32 -20
- package/dist/core/cli/runtime-preflight.d.mts +7 -1
- package/dist/core/cli/runtime-preflight.mjs +3 -3
- package/dist/core/completion/shells/bash.mjs +5 -2
- package/dist/core/completion/shells/fish.mjs +3 -1
- package/dist/core/completion/shells/powershell.mjs +8 -4
- package/dist/core/completion/shells/shared.d.mts +13 -2
- package/dist/core/completion/shells/shared.mjs +19 -2
- package/dist/core/completion/shells/zsh.mjs +8 -2
- package/dist/core/config/index.d.mts +2 -2
- package/dist/core/config/package-json.d.mts +27 -3
- package/dist/core/config/package-json.mjs +20 -19
- package/dist/core/errors/index.d.mts +1 -1
- package/dist/core/execution/index.mjs +13 -2
- package/dist/core/help/index.d.mts +22 -3
- package/dist/core/help/index.mjs +55 -49
- package/dist/core/help/theme.d.mts +68 -0
- package/dist/core/help/theme.mjs +46 -0
- package/dist/core/json-schema/index.d.mts +15 -2
- package/dist/core/json-schema/index.mjs +32 -4
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
- package/dist/core/json-schema/meta-descriptions.generated.mjs +14 -5
- package/dist/core/parse/index.d.mts +40 -7
- package/dist/core/parse/index.mjs +137 -34
- package/dist/core/resolve/args.d.mts +1 -1
- package/dist/core/resolve/coerce.d.mts +1 -1
- package/dist/core/resolve/contracts.d.mts +2 -2
- package/dist/core/resolve/index.d.mts +2 -2
- package/dist/core/schema/command.d.mts +2 -2
- package/dist/core/schema/command.mjs +23 -11
- package/dist/core/schema/flag.d.mts +148 -9
- package/dist/core/schema/flag.mjs +71 -1
- package/dist/core/schema/index.d.mts +2 -2
- package/dist/core/schema/run.d.mts +11 -0
- package/dist/index.d.mts +7 -6
- package/dist/index.mjs +3 -3
- package/dist/version.mjs +2 -2
- package/dreamcli.schema.json +33 -6
- package/package.json +1 -1
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import { Colors, Formatter } from "ansispeck";
|
|
2
|
+
//#region src/core/help/theme.d.ts
|
|
3
|
+
/**
|
|
4
|
+
* Semantic styling roles for help output.
|
|
5
|
+
*
|
|
6
|
+
* Roles that appear inside wrap-eligible description text (`defaultValue`,
|
|
7
|
+
* `annotation`, `deprecated`) should stick to foreground colors and `dim` —
|
|
8
|
+
* a styled span may cross a soft-wrap boundary, and while color/dim carry
|
|
9
|
+
* invisibly across the continuation indent, `underline`/`inverse`/background
|
|
10
|
+
* styles would visibly paint it.
|
|
11
|
+
*/
|
|
12
|
+
interface HelpTheme {
|
|
13
|
+
/** Section headings: `Usage:`, `Arguments:`, `Flags:`, `Commands:`, `Examples:`, `Global options:`. */
|
|
14
|
+
readonly sectionTitle: Formatter;
|
|
15
|
+
/** Binary / command path in the usage line. */
|
|
16
|
+
readonly usageBin: Formatter;
|
|
17
|
+
/** Flag forms in the flags table: `-f, --force`. */
|
|
18
|
+
readonly flag: Formatter;
|
|
19
|
+
/** Grammar tokens: `<string>`, `<command>`, `[flags]`, value hints. */
|
|
20
|
+
readonly placeholder: Formatter;
|
|
21
|
+
/** Command names in `Commands:` tables. */
|
|
22
|
+
readonly command: Formatter;
|
|
23
|
+
/** Positional arg tokens: `<file>`, `[out]...`. */
|
|
24
|
+
readonly arg: Formatter;
|
|
25
|
+
/** Default-value annotations: `(default: 8080)`. */
|
|
26
|
+
readonly defaultValue: Formatter;
|
|
27
|
+
/** Metadata annotations: `[env: X]`, `[config: a.b]`, `[prompt]`, `[required]`, ` (default)`. */
|
|
28
|
+
readonly annotation: Formatter;
|
|
29
|
+
/** Deprecation labels: `[deprecated]`, `[deprecated: use --x]`. */
|
|
30
|
+
readonly deprecated: Formatter;
|
|
31
|
+
/** Program name in the root-help header. */
|
|
32
|
+
readonly headerName: Formatter;
|
|
33
|
+
/** Version (`vX.Y.Z`) in the root-help header. */
|
|
34
|
+
readonly headerVersion: Formatter;
|
|
35
|
+
/** The `$` prompt marker in `Examples:`. */
|
|
36
|
+
readonly examplePrompt: Formatter;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* User theme customization: receives the gated palette and returns role
|
|
40
|
+
* overrides merged over the default theme.
|
|
41
|
+
*
|
|
42
|
+
* The palette formatters are identity functions when color is disabled, and
|
|
43
|
+
* the factory itself is only invoked when color is enabled — style
|
|
44
|
+
* unconditionally, gating is the framework's job.
|
|
45
|
+
*/
|
|
46
|
+
type HelpThemeFactory = (colors: Colors) => Partial<HelpTheme>;
|
|
47
|
+
/**
|
|
48
|
+
* The built-in help theme (clap/cargo conventions).
|
|
49
|
+
*
|
|
50
|
+
* @param c - Palette to build formatters from (typically the gated `out.color`).
|
|
51
|
+
* @internal
|
|
52
|
+
*/
|
|
53
|
+
declare function defaultHelpTheme(c: Colors): HelpTheme;
|
|
54
|
+
/**
|
|
55
|
+
* Resolve the effective help theme from a palette and optional user factory.
|
|
56
|
+
*
|
|
57
|
+
* When the palette renders no styling (color disabled — its formatters are
|
|
58
|
+
* identity functions), the user factory is **never invoked**: even a factory
|
|
59
|
+
* that emits raw escapes cannot leak them into color-off output. When color
|
|
60
|
+
* is enabled, factory overrides merge over {@linkcode defaultHelpTheme}.
|
|
61
|
+
*
|
|
62
|
+
* @param colors - Gated palette, or `undefined` for a color-off theme.
|
|
63
|
+
* @param theme - Optional user overrides factory.
|
|
64
|
+
* @internal
|
|
65
|
+
*/
|
|
66
|
+
declare function resolveHelpTheme(colors: Colors | undefined, theme: HelpThemeFactory | undefined): HelpTheme;
|
|
67
|
+
//#endregion
|
|
68
|
+
export { type HelpTheme, type HelpThemeFactory, defaultHelpTheme, resolveHelpTheme };
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { createColors } from "ansispeck";
|
|
2
|
+
//#region src/core/help/theme.ts
|
|
3
|
+
/**
|
|
4
|
+
* The built-in help theme (clap/cargo conventions).
|
|
5
|
+
*
|
|
6
|
+
* @param c - Palette to build formatters from (typically the gated `out.color`).
|
|
7
|
+
* @internal
|
|
8
|
+
*/
|
|
9
|
+
function defaultHelpTheme(c) {
|
|
10
|
+
return {
|
|
11
|
+
sectionTitle: (input) => c.bold(c.underline(input)),
|
|
12
|
+
usageBin: c.bold,
|
|
13
|
+
flag: c.cyan,
|
|
14
|
+
placeholder: c.dim,
|
|
15
|
+
command: c.cyan,
|
|
16
|
+
arg: c.cyan,
|
|
17
|
+
defaultValue: c.dim,
|
|
18
|
+
annotation: c.dim,
|
|
19
|
+
deprecated: c.yellow,
|
|
20
|
+
headerName: c.bold,
|
|
21
|
+
headerVersion: c.dim,
|
|
22
|
+
examplePrompt: c.dim
|
|
23
|
+
};
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Resolve the effective help theme from a palette and optional user factory.
|
|
27
|
+
*
|
|
28
|
+
* When the palette renders no styling (color disabled — its formatters are
|
|
29
|
+
* identity functions), the user factory is **never invoked**: even a factory
|
|
30
|
+
* that emits raw escapes cannot leak them into color-off output. When color
|
|
31
|
+
* is enabled, factory overrides merge over {@linkcode defaultHelpTheme}.
|
|
32
|
+
*
|
|
33
|
+
* @param colors - Gated palette, or `undefined` for a color-off theme.
|
|
34
|
+
* @param theme - Optional user overrides factory.
|
|
35
|
+
* @internal
|
|
36
|
+
*/
|
|
37
|
+
function resolveHelpTheme(colors, theme) {
|
|
38
|
+
const palette = colors ?? createColors(false);
|
|
39
|
+
if (!(palette.bold("x") !== "x") || theme === void 0) return defaultHelpTheme(palette);
|
|
40
|
+
return {
|
|
41
|
+
...defaultHelpTheme(palette),
|
|
42
|
+
...theme(palette)
|
|
43
|
+
};
|
|
44
|
+
}
|
|
45
|
+
//#endregion
|
|
46
|
+
export { defaultHelpTheme, resolveHelpTheme };
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import "../schema/index.mjs";
|
|
2
1
|
import { CommandSchema } from "../schema/command.mjs";
|
|
2
|
+
import "../schema/index.mjs";
|
|
3
3
|
import { CLISchema } from "../cli/index.mjs";
|
|
4
4
|
//#region src/core/json-schema/index.d.ts
|
|
5
5
|
/**
|
|
@@ -53,6 +53,19 @@ interface JsonSchemaOptions {
|
|
|
53
53
|
* ```
|
|
54
54
|
*/
|
|
55
55
|
declare function generateSchema(schema: CLISchema, options?: JsonSchemaOptions): Record<string, unknown>;
|
|
56
|
+
/**
|
|
57
|
+
* Generate the definition metadata document for a single command.
|
|
58
|
+
*
|
|
59
|
+
* The per-command counterpart of {@link generateSchema}: the same
|
|
60
|
+
* JSON-serializable shape as one entry of its `commands` array (flags, args,
|
|
61
|
+
* subcommands, examples). Powers `--help` in `--json` mode and is useful for
|
|
62
|
+
* embedding one command's definition into custom tooling.
|
|
63
|
+
*
|
|
64
|
+
* @param schema - The command schema to serialize.
|
|
65
|
+
* @param options - Generation options.
|
|
66
|
+
* @returns A plain object suitable for `JSON.stringify()`.
|
|
67
|
+
*/
|
|
68
|
+
declare function generateCommandSchema(schema: CommandSchema, options?: JsonSchemaOptions): Record<string, unknown>;
|
|
56
69
|
/**
|
|
57
70
|
* Generate a JSON Schema (draft 2020-12) for validating CLI input as JSON.
|
|
58
71
|
*
|
|
@@ -106,4 +119,4 @@ declare function generateInputSchema(schema: CLISchema | CommandSchema, options?
|
|
|
106
119
|
*/
|
|
107
120
|
declare const definitionMetaSchema: Record<string, unknown>;
|
|
108
121
|
//#endregion
|
|
109
|
-
export { type JsonSchemaOptions, definitionMetaSchema, generateInputSchema, generateSchema };
|
|
122
|
+
export { type JsonSchemaOptions, definitionMetaSchema, generateCommandSchema, generateInputSchema, generateSchema };
|
|
@@ -55,11 +55,26 @@ function generateSchema(schema, options) {
|
|
|
55
55
|
};
|
|
56
56
|
if (schema.version !== void 0) result.version = schema.version;
|
|
57
57
|
if (schema.description !== void 0) result.description = schema.description;
|
|
58
|
-
if (schema.defaultCommand !== void 0 && (opts.includeHidden || !schema.defaultCommand.schema.hidden)) result.defaultCommand = schema.defaultCommand.schema
|
|
58
|
+
if (schema.defaultCommand !== void 0 && (opts.includeHidden || !schema.defaultCommand.schema.hidden)) result.defaultCommand = serializeCommand(schema.defaultCommand.schema, opts);
|
|
59
59
|
result.commands = schema.commands.filter((cmd) => opts.includeHidden || !cmd.schema.hidden).map((cmd) => serializeCommand(cmd.schema, opts));
|
|
60
60
|
return result;
|
|
61
61
|
}
|
|
62
62
|
/**
|
|
63
|
+
* Generate the definition metadata document for a single command.
|
|
64
|
+
*
|
|
65
|
+
* The per-command counterpart of {@link generateSchema}: the same
|
|
66
|
+
* JSON-serializable shape as one entry of its `commands` array (flags, args,
|
|
67
|
+
* subcommands, examples). Powers `--help` in `--json` mode and is useful for
|
|
68
|
+
* embedding one command's definition into custom tooling.
|
|
69
|
+
*
|
|
70
|
+
* @param schema - The command schema to serialize.
|
|
71
|
+
* @param options - Generation options.
|
|
72
|
+
* @returns A plain object suitable for `JSON.stringify()`.
|
|
73
|
+
*/
|
|
74
|
+
function generateCommandSchema(schema, options) {
|
|
75
|
+
return serializeCommand(schema, resolveOptions(options));
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
63
78
|
* Serialize a single {@link CommandSchema} into a plain object.
|
|
64
79
|
*
|
|
65
80
|
* @param schema - The command schema to serialize.
|
|
@@ -102,6 +117,13 @@ function serializeFlag(schema, opts) {
|
|
|
102
117
|
if (opts.includePrompts && schema.prompt !== void 0) result.prompt = serializePrompt(schema.prompt);
|
|
103
118
|
if (schema.deprecated !== void 0) result.deprecated = schema.deprecated;
|
|
104
119
|
if (schema.propagate) result.propagate = true;
|
|
120
|
+
if (schema.negation !== void 0) {
|
|
121
|
+
const negation = {};
|
|
122
|
+
if (schema.negation.alias !== void 0) negation.alias = schema.negation.alias;
|
|
123
|
+
if (schema.negation.hidden) negation.hidden = true;
|
|
124
|
+
result.negation = negation;
|
|
125
|
+
}
|
|
126
|
+
if (schema.duplicates !== "last") result.duplicates = schema.duplicates;
|
|
105
127
|
return result;
|
|
106
128
|
}
|
|
107
129
|
/**
|
|
@@ -488,7 +510,7 @@ const definitionMetaSchema = withDefinitionMetaSchemaDescriptions({
|
|
|
488
510
|
name: string;
|
|
489
511
|
version?: string;
|
|
490
512
|
description?: string;
|
|
491
|
-
defaultCommand?:
|
|
513
|
+
defaultCommand?: @command;
|
|
492
514
|
commands: @command[]
|
|
493
515
|
}`),
|
|
494
516
|
$defs: {
|
|
@@ -514,7 +536,13 @@ const definitionMetaSchema = withDefinitionMetaSchemaDescriptions({
|
|
|
514
536
|
elementSchema?: @flag;
|
|
515
537
|
prompt?: @prompt;
|
|
516
538
|
deprecated?: string | true;
|
|
517
|
-
propagate?: true
|
|
539
|
+
propagate?: true;
|
|
540
|
+
negation?: @negation;
|
|
541
|
+
duplicates?: 'last' | 'first' | 'error'
|
|
542
|
+
}`),
|
|
543
|
+
negation: def(`{
|
|
544
|
+
alias?: string;
|
|
545
|
+
hidden?: true
|
|
518
546
|
}`),
|
|
519
547
|
arg: def(`{
|
|
520
548
|
name: string;
|
|
@@ -548,4 +576,4 @@ const definitionMetaSchema = withDefinitionMetaSchemaDescriptions({
|
|
|
548
576
|
}
|
|
549
577
|
}, definitionMetaSchemaDescriptions);
|
|
550
578
|
//#endregion
|
|
551
|
-
export { definitionMetaSchema, generateInputSchema, generateSchema };
|
|
579
|
+
export { definitionMetaSchema, generateCommandSchema, generateInputSchema, generateSchema };
|
|
@@ -92,7 +92,24 @@ declare const definitionMetaSchemaDescriptions: {
|
|
|
92
92
|
readonly description: 'Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated flag is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`.';
|
|
93
93
|
};
|
|
94
94
|
readonly propagate: {
|
|
95
|
-
readonly description: 'Whether this flag propagates to subcommands in nested command trees.\n\nWhen `true`, the flag is automatically available to all descendant\ncommands. A child command that defines a flag with the same name\nshadows the propagated parent flag
|
|
95
|
+
readonly description: 'Whether this flag propagates to subcommands in nested command trees.\n\nWhen `true`, the flag is automatically available to all descendant\ncommands. A child command that defines a flag with the same name\nshadows the propagated parent flag.\n\nDefault: `false`';
|
|
96
|
+
};
|
|
97
|
+
readonly negation: {
|
|
98
|
+
readonly description: "Negation settings when `kind === 'boolean'` and `.negatable()` was\ncalled (`undefined` otherwise). See FlagNegation.";
|
|
99
|
+
};
|
|
100
|
+
readonly duplicates: {
|
|
101
|
+
readonly description: "How repeated CLI occurrences of a singleton flag combine.\n\n- `'last'` — last occurrence wins (matches historic behavior)\n- `'first'` — first occurrence wins; later ones parse but are ignored\n- `'error'` — a second occurrence is a `ParseError` (`DUPLICATE_FLAG`)\n\nApplies to CLI token occurrences only — env/config/prompt/default\nresolution keeps its precedence semantics and never raises duplicates.\nOccurrences are counted per *logical* flag: aliases and the negated\nspelling all count toward the same flag.\n\nDefault: `'last'`";
|
|
102
|
+
};
|
|
103
|
+
};
|
|
104
|
+
};
|
|
105
|
+
readonly negation: {
|
|
106
|
+
readonly description: 'Negation settings for a boolean flag (set by `.negatable()`).\n\nThe negated spelling and the positive form are two spellings of ONE\nlogical flag: they share duplicate policy, and the last CLI occurrence\nwins across both. The negated spelling is presence-only — `--no-foo=x`\nis rejected.';
|
|
107
|
+
readonly properties: {
|
|
108
|
+
readonly alias: {
|
|
109
|
+
readonly description: "Explicit negated spelling without the `--` prefix (e.g. `'no-sandbox'`).\n`undefined` synthesizes `no-<flagName>` wherever the flag name is known.";
|
|
110
|
+
};
|
|
111
|
+
readonly hidden: {
|
|
112
|
+
readonly description: 'Hide the negated spelling from help, completions, and suggestions.';
|
|
96
113
|
};
|
|
97
114
|
};
|
|
98
115
|
};
|
|
@@ -112,7 +129,7 @@ declare const definitionMetaSchemaDescriptions: {
|
|
|
112
129
|
readonly description: 'Whether this arg consumes all remaining positionals.';
|
|
113
130
|
};
|
|
114
131
|
readonly stdinMode: {
|
|
115
|
-
readonly description: 'Whether this arg may read from stdin during resolution
|
|
132
|
+
readonly description: 'Whether this arg may read from stdin during resolution.\n\nDefault: `false`';
|
|
116
133
|
};
|
|
117
134
|
readonly defaultValue: {
|
|
118
135
|
readonly description: 'Runtime default value (if any).';
|
|
@@ -147,10 +164,10 @@ declare const definitionMetaSchemaDescriptions: {
|
|
|
147
164
|
readonly description: 'Available choices. When omitted for `enum` flags, the enum values\nfrom the flag schema are used automatically.';
|
|
148
165
|
};
|
|
149
166
|
readonly min: {
|
|
150
|
-
readonly description: 'Minimum number of selections required
|
|
167
|
+
readonly description: 'Minimum number of selections required.\n\nDefault: `0`';
|
|
151
168
|
};
|
|
152
169
|
readonly max: {
|
|
153
|
-
readonly description: 'Maximum number of selections allowed
|
|
170
|
+
readonly description: 'Maximum number of selections allowed.\n\nDefault: `Infinity`';
|
|
154
171
|
};
|
|
155
172
|
};
|
|
156
173
|
};
|
|
@@ -161,7 +178,7 @@ declare const definitionMetaSchemaDescriptions: {
|
|
|
161
178
|
readonly description: 'The value returned when this choice is selected.';
|
|
162
179
|
};
|
|
163
180
|
readonly label: {
|
|
164
|
-
readonly description: 'Display label shown to the user
|
|
181
|
+
readonly description: 'Display label shown to the user.\n\nDefault: value';
|
|
165
182
|
};
|
|
166
183
|
readonly description: {
|
|
167
184
|
readonly description: 'Optional description shown alongside the choice.';
|
|
@@ -43,7 +43,16 @@ const definitionMetaSchemaDescriptions = {
|
|
|
43
43
|
elementSchema: { description: "Element schema when `kind === 'array'`." },
|
|
44
44
|
prompt: { description: "Interactive prompt configuration for v0.3+ resolution." },
|
|
45
45
|
deprecated: { description: "Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated flag is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`." },
|
|
46
|
-
propagate: { description: "Whether this flag propagates to subcommands in nested command trees.\n\nWhen `true`, the flag is automatically available to all descendant\ncommands. A child command that defines a flag with the same name\nshadows the propagated parent flag
|
|
46
|
+
propagate: { description: "Whether this flag propagates to subcommands in nested command trees.\n\nWhen `true`, the flag is automatically available to all descendant\ncommands. A child command that defines a flag with the same name\nshadows the propagated parent flag.\n\nDefault: `false`" },
|
|
47
|
+
negation: { description: "Negation settings when `kind === 'boolean'` and `.negatable()` was\ncalled (`undefined` otherwise). See FlagNegation." },
|
|
48
|
+
duplicates: { description: "How repeated CLI occurrences of a singleton flag combine.\n\n- `'last'` — last occurrence wins (matches historic behavior)\n- `'first'` — first occurrence wins; later ones parse but are ignored\n- `'error'` — a second occurrence is a `ParseError` (`DUPLICATE_FLAG`)\n\nApplies to CLI token occurrences only — env/config/prompt/default\nresolution keeps its precedence semantics and never raises duplicates.\nOccurrences are counted per *logical* flag: aliases and the negated\nspelling all count toward the same flag.\n\nDefault: `'last'`" }
|
|
49
|
+
}
|
|
50
|
+
},
|
|
51
|
+
negation: {
|
|
52
|
+
description: "Negation settings for a boolean flag (set by `.negatable()`).\n\nThe negated spelling and the positive form are two spellings of ONE\nlogical flag: they share duplicate policy, and the last CLI occurrence\nwins across both. The negated spelling is presence-only — `--no-foo=x`\nis rejected.",
|
|
53
|
+
properties: {
|
|
54
|
+
alias: { description: "Explicit negated spelling without the `--` prefix (e.g. `'no-sandbox'`).\n`undefined` synthesizes `no-<flagName>` wherever the flag name is known." },
|
|
55
|
+
hidden: { description: "Hide the negated spelling from help, completions, and suggestions." }
|
|
47
56
|
}
|
|
48
57
|
},
|
|
49
58
|
arg: {
|
|
@@ -53,7 +62,7 @@ const definitionMetaSchemaDescriptions = {
|
|
|
53
62
|
kind: { description: "What kind of value this arg accepts." },
|
|
54
63
|
presence: { description: "Presence describes whether a positional arg is guaranteed to exist when the\naction handler runs:\n\n- `'required'` — must be supplied; error if missing (default)\n- `'optional'` — may be `undefined` if not supplied\n- `'defaulted'` — always present (falls back to default value)" },
|
|
55
64
|
variadic: { description: "Whether this arg consumes all remaining positionals." },
|
|
56
|
-
stdinMode: { description: "Whether this arg may read from stdin during resolution
|
|
65
|
+
stdinMode: { description: "Whether this arg may read from stdin during resolution.\n\nDefault: `false`" },
|
|
57
66
|
defaultValue: { description: "Runtime default value (if any)." },
|
|
58
67
|
description: { description: "Human-readable description for help text." },
|
|
59
68
|
envVar: { description: "Environment variable name for env resolution.\n\nWhen set and the CLI value is absent, the resolver reads this env var\nand coerces the string to the arg's declared kind." },
|
|
@@ -68,15 +77,15 @@ const definitionMetaSchemaDescriptions = {
|
|
|
68
77
|
message: { description: "The question displayed to the user." },
|
|
69
78
|
placeholder: { description: "Placeholder text shown before user types (informational only)." },
|
|
70
79
|
choices: { description: "Available choices. When omitted for `enum` flags, the enum values\nfrom the flag schema are used automatically." },
|
|
71
|
-
min: { description: "Minimum number of selections required
|
|
72
|
-
max: { description: "Maximum number of selections allowed
|
|
80
|
+
min: { description: "Minimum number of selections required.\n\nDefault: `0`" },
|
|
81
|
+
max: { description: "Maximum number of selections allowed.\n\nDefault: `Infinity`" }
|
|
73
82
|
}
|
|
74
83
|
},
|
|
75
84
|
choice: {
|
|
76
85
|
description: "A selectable option for SelectPromptConfig and MultiselectPromptConfig prompts.",
|
|
77
86
|
properties: {
|
|
78
87
|
value: { description: "The value returned when this choice is selected." },
|
|
79
|
-
label: { description: "Display label shown to the user
|
|
88
|
+
label: { description: "Display label shown to the user.\n\nDefault: value" },
|
|
80
89
|
description: { description: "Optional description shown alongside the choice." }
|
|
81
90
|
}
|
|
82
91
|
},
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { FlagSchema } from "../schema/flag.mjs";
|
|
2
|
-
import "../schema/index.mjs";
|
|
3
2
|
import { CommandSchema } from "../schema/command.mjs";
|
|
3
|
+
import "../schema/index.mjs";
|
|
4
4
|
//#region src/core/parse/index.d.ts
|
|
5
5
|
/**
|
|
6
6
|
* Token discriminated union.
|
|
@@ -84,15 +84,47 @@ interface ParseResult {
|
|
|
84
84
|
/** Positional arg values keyed by arg name. */
|
|
85
85
|
readonly args: Readonly<Record<string, unknown>>;
|
|
86
86
|
}
|
|
87
|
+
/** Options accepted by {@link parse} and {@link buildFlagLookup}. */
|
|
88
|
+
interface ParseOptions {
|
|
89
|
+
/**
|
|
90
|
+
* Accept the kebab↔camel counterpart spelling of each flag name/alias
|
|
91
|
+
* (`--doThis` for a flag named `do-this`, and vice versa). Automatically
|
|
92
|
+
* disabled per spelling pair when a command explicitly defines both.
|
|
93
|
+
*
|
|
94
|
+
* @defaultValue `true`
|
|
95
|
+
*/
|
|
96
|
+
readonly caseParity?: boolean;
|
|
97
|
+
}
|
|
98
|
+
/** `do-this` → `doThis`. Returns the input unchanged when nothing converts. */
|
|
99
|
+
declare function kebabToCamel(name: string): string;
|
|
100
|
+
/** `doThis` → `do-this`. Returns the input unchanged when nothing converts. */
|
|
101
|
+
declare function camelToKebab(name: string): string;
|
|
102
|
+
/** One resolvable spelling in the flag lookup map. */
|
|
103
|
+
interface FlagLookupEntry {
|
|
104
|
+
/** Canonical flag name (the key in the command's flag record). */
|
|
105
|
+
readonly name: string;
|
|
106
|
+
/** The flag's schema. */
|
|
107
|
+
readonly schema: FlagSchema;
|
|
108
|
+
/** This spelling is the flag's negated form (`--no-foo`) — parses to `false`. */
|
|
109
|
+
readonly negated: boolean;
|
|
110
|
+
/** This spelling is a case-parity counterpart, not a declared spelling. */
|
|
111
|
+
readonly parity: boolean;
|
|
112
|
+
}
|
|
87
113
|
/**
|
|
88
|
-
* Build a map from flag
|
|
114
|
+
* Build a map from flag spelling → {@link FlagLookupEntry}.
|
|
89
115
|
*
|
|
90
|
-
*
|
|
116
|
+
* Covers canonical names, aliases (long + single-char), negated spellings of
|
|
117
|
+
* `.negatable()` booleans, and — unless `caseParity` is `false` — the
|
|
118
|
+
* kebab↔camel counterpart of every declared spelling. Counterparts never
|
|
119
|
+
* override declared spellings: when a command defines both `do-this` and
|
|
120
|
+
* `doThis` explicitly, each spelling exact-matches its own flag and no
|
|
121
|
+
* parity entries are added for the pair.
|
|
91
122
|
*
|
|
92
123
|
* @param flags - Flag schemas keyed by canonical name
|
|
93
|
-
* @
|
|
124
|
+
* @param options - Parity toggle (see {@link ParseOptions})
|
|
125
|
+
* @returns Lookup map covering all resolvable spellings
|
|
94
126
|
*/
|
|
95
|
-
declare function buildFlagLookup(flags: Readonly<Record<string, FlagSchema
|
|
127
|
+
declare function buildFlagLookup(flags: Readonly<Record<string, FlagSchema>>, options?: ParseOptions): ReadonlyMap<string, FlagLookupEntry>;
|
|
96
128
|
/**
|
|
97
129
|
* Whether a flag kind expects a value argument (vs. being a bare boolean).
|
|
98
130
|
*
|
|
@@ -109,6 +141,7 @@ declare function flagExpectsValue(schema: FlagSchema): boolean;
|
|
|
109
141
|
*
|
|
110
142
|
* @param schema - The command schema to parse against
|
|
111
143
|
* @param argv - Raw argv strings (NOT including the command name itself)
|
|
144
|
+
* @param options - Parser behavior toggles (see {@link ParseOptions})
|
|
112
145
|
* @returns Parsed flag and arg values
|
|
113
146
|
* @throws ParseError for unknown flags, missing values, type mismatches
|
|
114
147
|
*
|
|
@@ -118,6 +151,6 @@ declare function flagExpectsValue(schema: FlagSchema): boolean;
|
|
|
118
151
|
* // => { args: { target: 'production' }, flags: { force: true } }
|
|
119
152
|
* ```
|
|
120
153
|
*/
|
|
121
|
-
declare function parse(schema: CommandSchema, argv: readonly string[]): ParseResult;
|
|
154
|
+
declare function parse(schema: CommandSchema, argv: readonly string[], options?: ParseOptions): ParseResult;
|
|
122
155
|
//#endregion
|
|
123
|
-
export { type ParseResult, type Token, buildFlagLookup, flagExpectsValue, includesBeforeSeparator, parse, stripBeforeSeparator, tokenize };
|
|
156
|
+
export { type FlagLookupEntry, type ParseOptions, type ParseResult, type Token, buildFlagLookup, camelToKebab, flagExpectsValue, includesBeforeSeparator, kebabToCamel, parse, stripBeforeSeparator, tokenize };
|