@kjanat/dreamcli 3.0.0-rc.7 → 3.0.0-rc.8
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 +46 -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 +19 -7
- 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 +5 -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 +1 -1
- package/dist/core/json-schema/index.mjs +14 -1
- 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 +103 -1
- 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 +6 -5
- package/dist/index.mjs +2 -2
- package/dist/version.mjs +2 -2
- package/dreamcli.schema.json +32 -5
- package/package.json +1 -1
|
@@ -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 };
|
|
@@ -102,6 +102,13 @@ function serializeFlag(schema, opts) {
|
|
|
102
102
|
if (opts.includePrompts && schema.prompt !== void 0) result.prompt = serializePrompt(schema.prompt);
|
|
103
103
|
if (schema.deprecated !== void 0) result.deprecated = schema.deprecated;
|
|
104
104
|
if (schema.propagate) result.propagate = true;
|
|
105
|
+
if (schema.negation !== void 0) {
|
|
106
|
+
const negation = {};
|
|
107
|
+
if (schema.negation.alias !== void 0) negation.alias = schema.negation.alias;
|
|
108
|
+
if (schema.negation.hidden) negation.hidden = true;
|
|
109
|
+
result.negation = negation;
|
|
110
|
+
}
|
|
111
|
+
if (schema.duplicates !== "last") result.duplicates = schema.duplicates;
|
|
105
112
|
return result;
|
|
106
113
|
}
|
|
107
114
|
/**
|
|
@@ -514,7 +521,13 @@ const definitionMetaSchema = withDefinitionMetaSchemaDescriptions({
|
|
|
514
521
|
elementSchema?: @flag;
|
|
515
522
|
prompt?: @prompt;
|
|
516
523
|
deprecated?: string | true;
|
|
517
|
-
propagate?: true
|
|
524
|
+
propagate?: true;
|
|
525
|
+
negation?: @negation;
|
|
526
|
+
duplicates?: 'last' | 'first' | 'error'
|
|
527
|
+
}`),
|
|
528
|
+
negation: def(`{
|
|
529
|
+
alias?: string;
|
|
530
|
+
hidden?: true
|
|
518
531
|
}`),
|
|
519
532
|
arg: def(`{
|
|
520
533
|
name: string;
|
|
@@ -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 };
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { ParseError } from "../errors/index.mjs";
|
|
2
2
|
import { describeNumberConstraintViolation, validateNumberConstraints } from "../schema/number-constraints.mjs";
|
|
3
3
|
import { describeStringConstraintViolation, validateStringConstraints } from "../schema/string-constraints.mjs";
|
|
4
|
-
import { getFlagAliasNames } from "../schema/flag.mjs";
|
|
4
|
+
import { getFlagAliasNames, getFlagNegatedName } from "../schema/flag.mjs";
|
|
5
5
|
//#region src/core/parse/index.ts
|
|
6
6
|
/**
|
|
7
7
|
* Argv tokenization and parsing against command schemas.
|
|
@@ -123,23 +123,107 @@ function stripBeforeSeparator(argv, token) {
|
|
|
123
123
|
const filteredHead = head.filter((arg) => arg !== token);
|
|
124
124
|
return separatorIndex === -1 ? filteredHead : [...filteredHead, ...argv.slice(separatorIndex)];
|
|
125
125
|
}
|
|
126
|
+
/** `do-this` → `doThis`. Returns the input unchanged when nothing converts. */
|
|
127
|
+
function kebabToCamel(name) {
|
|
128
|
+
return name.replace(/-+([a-z0-9])/g, (_match, char) => char.toUpperCase());
|
|
129
|
+
}
|
|
130
|
+
/** `doThis` → `do-this`. Returns the input unchanged when nothing converts. */
|
|
131
|
+
function camelToKebab(name) {
|
|
132
|
+
return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
|
|
133
|
+
}
|
|
126
134
|
/**
|
|
127
|
-
*
|
|
135
|
+
* The kebab↔camel counterpart spelling of a flag name, or `undefined` when
|
|
136
|
+
* the name has none (single-char aliases, single lowercase words).
|
|
137
|
+
*/
|
|
138
|
+
function counterpartSpelling(name) {
|
|
139
|
+
if (name.length < 2) return void 0;
|
|
140
|
+
if (name.includes("-")) {
|
|
141
|
+
const camel = kebabToCamel(name);
|
|
142
|
+
return camel !== name ? camel : void 0;
|
|
143
|
+
}
|
|
144
|
+
const kebab = camelToKebab(name);
|
|
145
|
+
return kebab !== name ? kebab : void 0;
|
|
146
|
+
}
|
|
147
|
+
/**
|
|
148
|
+
* Build a map from flag spelling → {@link FlagLookupEntry}.
|
|
128
149
|
*
|
|
129
|
-
*
|
|
150
|
+
* Covers canonical names, aliases (long + single-char), negated spellings of
|
|
151
|
+
* `.negatable()` booleans, and — unless `caseParity` is `false` — the
|
|
152
|
+
* kebab↔camel counterpart of every declared spelling. Counterparts never
|
|
153
|
+
* override declared spellings: when a command defines both `do-this` and
|
|
154
|
+
* `doThis` explicitly, each spelling exact-matches its own flag and no
|
|
155
|
+
* parity entries are added for the pair.
|
|
130
156
|
*
|
|
131
157
|
* @param flags - Flag schemas keyed by canonical name
|
|
132
|
-
* @
|
|
158
|
+
* @param options - Parity toggle (see {@link ParseOptions})
|
|
159
|
+
* @returns Lookup map covering all resolvable spellings
|
|
133
160
|
*/
|
|
134
|
-
function buildFlagLookup(flags) {
|
|
161
|
+
function buildFlagLookup(flags, options) {
|
|
135
162
|
const lookup = /* @__PURE__ */ new Map();
|
|
136
163
|
for (const [name, schema] of Object.entries(flags)) {
|
|
137
|
-
lookup.set(name,
|
|
138
|
-
|
|
164
|
+
lookup.set(name, {
|
|
165
|
+
name,
|
|
166
|
+
schema,
|
|
167
|
+
negated: false,
|
|
168
|
+
parity: false
|
|
169
|
+
});
|
|
170
|
+
for (const alias of getFlagAliasNames(schema, { includeHidden: true })) lookup.set(alias, {
|
|
171
|
+
name,
|
|
172
|
+
schema,
|
|
173
|
+
negated: false,
|
|
174
|
+
parity: false
|
|
175
|
+
});
|
|
176
|
+
const negatedName = getFlagNegatedName(name, schema);
|
|
177
|
+
if (negatedName !== void 0) lookup.set(negatedName, {
|
|
178
|
+
name,
|
|
179
|
+
schema,
|
|
180
|
+
negated: true,
|
|
181
|
+
parity: false
|
|
182
|
+
});
|
|
183
|
+
}
|
|
184
|
+
if (options?.caseParity !== false) for (const [spelling, entry] of [...lookup]) {
|
|
185
|
+
const counterpart = counterpartSpelling(spelling);
|
|
186
|
+
if (counterpart !== void 0 && !lookup.has(counterpart)) lookup.set(counterpart, {
|
|
187
|
+
...entry,
|
|
188
|
+
parity: true
|
|
189
|
+
});
|
|
139
190
|
}
|
|
140
191
|
return lookup;
|
|
141
192
|
}
|
|
142
193
|
/**
|
|
194
|
+
* Record one CLI occurrence of a logical flag and enforce its duplicate
|
|
195
|
+
* policy.
|
|
196
|
+
*
|
|
197
|
+
* @param occurrences - Per-parse accumulator keyed by canonical name
|
|
198
|
+
* @param name - Canonical flag name
|
|
199
|
+
* @param schema - Flag schema (read for {@link FlagSchema.duplicates})
|
|
200
|
+
* @param value - The occurrence's raw value (or the boolean it implies)
|
|
201
|
+
* @param displayName - User-facing spelling for error messages
|
|
202
|
+
* @returns `true` when the occurrence should be applied; `false` when the
|
|
203
|
+
* `'first'` policy suppresses it (the token is still consumed)
|
|
204
|
+
* @throws ParseError `DUPLICATE_FLAG` on a repeat under the `'error'` policy
|
|
205
|
+
*/
|
|
206
|
+
function recordFlagOccurrence(occurrences, name, schema, value, displayName) {
|
|
207
|
+
const record = occurrences.get(name) ?? {
|
|
208
|
+
count: 0,
|
|
209
|
+
values: []
|
|
210
|
+
};
|
|
211
|
+
record.count += 1;
|
|
212
|
+
record.values.push(value);
|
|
213
|
+
occurrences.set(name, record);
|
|
214
|
+
if (record.count === 1) return true;
|
|
215
|
+
if (schema.duplicates === "error") throw new ParseError(`Flag --${name} may only be specified once`, {
|
|
216
|
+
code: "DUPLICATE_FLAG",
|
|
217
|
+
details: {
|
|
218
|
+
flag: name,
|
|
219
|
+
input: displayName,
|
|
220
|
+
count: record.count,
|
|
221
|
+
values: [...record.values]
|
|
222
|
+
}
|
|
223
|
+
});
|
|
224
|
+
return schema.duplicates !== "first";
|
|
225
|
+
}
|
|
226
|
+
/**
|
|
143
227
|
* Whether a flag kind expects a value argument (vs. being a bare boolean).
|
|
144
228
|
*
|
|
145
229
|
* @param schema - Flag schema to check
|
|
@@ -349,6 +433,7 @@ function coerceArgValue(argName, raw, schema) {
|
|
|
349
433
|
*
|
|
350
434
|
* @param schema - The command schema to parse against
|
|
351
435
|
* @param argv - Raw argv strings (NOT including the command name itself)
|
|
436
|
+
* @param options - Parser behavior toggles (see {@link ParseOptions})
|
|
352
437
|
* @returns Parsed flag and arg values
|
|
353
438
|
* @throws ParseError for unknown flags, missing values, type mismatches
|
|
354
439
|
*
|
|
@@ -358,11 +443,12 @@ function coerceArgValue(argName, raw, schema) {
|
|
|
358
443
|
* // => { args: { target: 'production' }, flags: { force: true } }
|
|
359
444
|
* ```
|
|
360
445
|
*/
|
|
361
|
-
function parse(schema, argv) {
|
|
446
|
+
function parse(schema, argv, options) {
|
|
362
447
|
const tokens = tokenize(argv);
|
|
363
|
-
const flagLookup = buildFlagLookup(schema.flags);
|
|
448
|
+
const flagLookup = buildFlagLookup(schema.flags, options);
|
|
364
449
|
const flags = {};
|
|
365
450
|
const positionals = [];
|
|
451
|
+
const occurrences = /* @__PURE__ */ new Map();
|
|
366
452
|
let i = 0;
|
|
367
453
|
while (i < tokens.length) {
|
|
368
454
|
const token = tokens[i];
|
|
@@ -377,10 +463,10 @@ function parse(schema, argv) {
|
|
|
377
463
|
continue;
|
|
378
464
|
}
|
|
379
465
|
if (token.kind === "long-flag") {
|
|
380
|
-
i = parseLongFlag(token, tokens, i, flagLookup, flags);
|
|
466
|
+
i = parseLongFlag(token, tokens, i, flagLookup, flags, occurrences);
|
|
381
467
|
continue;
|
|
382
468
|
}
|
|
383
|
-
i = parseShortFlags(token, tokens, i, flagLookup, flags);
|
|
469
|
+
i = parseShortFlags(token, tokens, i, flagLookup, flags, occurrences);
|
|
384
470
|
}
|
|
385
471
|
return {
|
|
386
472
|
flags,
|
|
@@ -393,11 +479,12 @@ function parse(schema, argv) {
|
|
|
393
479
|
* @param token - Long-flag token to process
|
|
394
480
|
* @param tokens - Full token array (for lookahead)
|
|
395
481
|
* @param startIdx - Current index of `token` in the array
|
|
396
|
-
* @param flagLookup -
|
|
482
|
+
* @param flagLookup - Spelling → {@link FlagLookupEntry} map from {@link buildFlagLookup}
|
|
397
483
|
* @param flags - Mutable accumulator for resolved flag values
|
|
484
|
+
* @param occurrences - Per-parse duplicate-occurrence accumulator
|
|
398
485
|
* @returns Next index to continue parsing from
|
|
399
486
|
*/
|
|
400
|
-
function parseLongFlag(token, tokens, startIdx, flagLookup, flags) {
|
|
487
|
+
function parseLongFlag(token, tokens, startIdx, flagLookup, flags, occurrences) {
|
|
401
488
|
const entry = flagLookup.get(token.name);
|
|
402
489
|
if (!entry) {
|
|
403
490
|
const suggestion = suggestFlag(token.name, flagLookup);
|
|
@@ -410,21 +497,36 @@ function parseLongFlag(token, tokens, startIdx, flagLookup, flags) {
|
|
|
410
497
|
...suggestion ? { suggest: `--${suggestion}` } : {}
|
|
411
498
|
});
|
|
412
499
|
}
|
|
413
|
-
const
|
|
500
|
+
const { name: canonicalName, schema: flagSchema, negated } = entry;
|
|
501
|
+
const displayName = `--${token.name}`;
|
|
502
|
+
if (negated) {
|
|
503
|
+
if (token.value !== void 0) throw new ParseError(`Flag ${displayName} does not take a value`, {
|
|
504
|
+
code: "INVALID_VALUE",
|
|
505
|
+
details: {
|
|
506
|
+
flag: canonicalName,
|
|
507
|
+
input: token.name,
|
|
508
|
+
value: token.value
|
|
509
|
+
}
|
|
510
|
+
});
|
|
511
|
+
if (recordFlagOccurrence(occurrences, canonicalName, flagSchema, false, displayName)) flags[canonicalName] = false;
|
|
512
|
+
return startIdx + 1;
|
|
513
|
+
}
|
|
414
514
|
if (!flagExpectsValue(flagSchema)) {
|
|
415
|
-
if (token.value !== void 0)
|
|
416
|
-
|
|
515
|
+
if (token.value !== void 0) {
|
|
516
|
+
const coerced = coerceFlagValue(canonicalName, token.value, flagSchema, displayName);
|
|
517
|
+
if (recordFlagOccurrence(occurrences, canonicalName, flagSchema, coerced, displayName)) flags[canonicalName] = coerced;
|
|
518
|
+
} else if (flagSchema.kind === "count") {
|
|
417
519
|
const existing = flags[canonicalName];
|
|
418
520
|
flags[canonicalName] = (typeof existing === "number" ? existing : 0) + 1;
|
|
419
|
-
} else flags[canonicalName] = true;
|
|
521
|
+
} else if (recordFlagOccurrence(occurrences, canonicalName, flagSchema, true, displayName)) flags[canonicalName] = true;
|
|
420
522
|
return startIdx + 1;
|
|
421
523
|
}
|
|
422
524
|
if (token.value !== void 0) {
|
|
423
|
-
setFlagValue(flags, canonicalName, flagSchema, token.value);
|
|
525
|
+
if (recordFlagOccurrence(occurrences, canonicalName, flagSchema, token.value, displayName)) setFlagValue(flags, canonicalName, flagSchema, token.value);
|
|
424
526
|
return startIdx + 1;
|
|
425
527
|
}
|
|
426
528
|
const nextToken = tokens[startIdx + 1];
|
|
427
|
-
if (nextToken?.kind !== "positional") throw new ParseError(`Flag
|
|
529
|
+
if (nextToken?.kind !== "positional") throw new ParseError(`Flag ${displayName} requires a value`, {
|
|
428
530
|
code: "MISSING_VALUE",
|
|
429
531
|
details: {
|
|
430
532
|
flag: canonicalName,
|
|
@@ -432,7 +534,7 @@ function parseLongFlag(token, tokens, startIdx, flagLookup, flags) {
|
|
|
432
534
|
kind: flagSchema.kind
|
|
433
535
|
}
|
|
434
536
|
});
|
|
435
|
-
setFlagValue(flags, canonicalName, flagSchema, nextToken.value,
|
|
537
|
+
if (recordFlagOccurrence(occurrences, canonicalName, flagSchema, nextToken.value, displayName)) setFlagValue(flags, canonicalName, flagSchema, nextToken.value, displayName);
|
|
436
538
|
return startIdx + 2;
|
|
437
539
|
}
|
|
438
540
|
/**
|
|
@@ -441,11 +543,12 @@ function parseLongFlag(token, tokens, startIdx, flagLookup, flags) {
|
|
|
441
543
|
* @param token - Short-flags token to expand
|
|
442
544
|
* @param tokens - Full token array (for lookahead)
|
|
443
545
|
* @param startIdx - Current index of `token` in the array
|
|
444
|
-
* @param flagLookup -
|
|
546
|
+
* @param flagLookup - Spelling → {@link FlagLookupEntry} map from {@link buildFlagLookup}
|
|
445
547
|
* @param flags - Mutable accumulator for resolved flag values
|
|
548
|
+
* @param occurrences - Per-parse duplicate-occurrence accumulator
|
|
446
549
|
* @returns Next index to continue parsing from
|
|
447
550
|
*/
|
|
448
|
-
function parseShortFlags(token, tokens, startIdx, flagLookup, flags) {
|
|
551
|
+
function parseShortFlags(token, tokens, startIdx, flagLookup, flags, occurrences) {
|
|
449
552
|
const { chars } = token;
|
|
450
553
|
let nextIdx = startIdx + 1;
|
|
451
554
|
for (let ci = 0; ci < chars.length; ci++) {
|
|
@@ -455,16 +558,18 @@ function parseShortFlags(token, tokens, startIdx, flagLookup, flags) {
|
|
|
455
558
|
code: "UNKNOWN_FLAG",
|
|
456
559
|
details: { flag: ch }
|
|
457
560
|
});
|
|
458
|
-
const
|
|
561
|
+
const { name: canonicalName, schema: flagSchema } = entry;
|
|
562
|
+
const displayName = `-${ch}`;
|
|
459
563
|
if (!flagExpectsValue(flagSchema)) {
|
|
460
564
|
if (flagSchema.kind === "count") {
|
|
461
565
|
const existing = flags[canonicalName];
|
|
462
566
|
flags[canonicalName] = (typeof existing === "number" ? existing : 0) + 1;
|
|
463
|
-
} else flags[canonicalName] = true;
|
|
567
|
+
} else if (recordFlagOccurrence(occurrences, canonicalName, flagSchema, true, displayName)) flags[canonicalName] = true;
|
|
464
568
|
continue;
|
|
465
569
|
}
|
|
466
570
|
if (ci < chars.length - 1) {
|
|
467
|
-
|
|
571
|
+
const inlineValue = chars.slice(ci + 1);
|
|
572
|
+
if (recordFlagOccurrence(occurrences, canonicalName, flagSchema, inlineValue, displayName)) setFlagValue(flags, canonicalName, flagSchema, inlineValue, displayName);
|
|
468
573
|
break;
|
|
469
574
|
}
|
|
470
575
|
const nextToken = tokens[nextIdx];
|
|
@@ -476,7 +581,7 @@ function parseShortFlags(token, tokens, startIdx, flagLookup, flags) {
|
|
|
476
581
|
kind: flagSchema.kind
|
|
477
582
|
}
|
|
478
583
|
});
|
|
479
|
-
setFlagValue(flags, canonicalName, flagSchema, nextToken.value,
|
|
584
|
+
if (recordFlagOccurrence(occurrences, canonicalName, flagSchema, nextToken.value, displayName)) setFlagValue(flags, canonicalName, flagSchema, nextToken.value, displayName);
|
|
480
585
|
nextIdx++;
|
|
481
586
|
}
|
|
482
587
|
return nextIdx;
|
|
@@ -574,13 +679,11 @@ function suggestFlag(input, lookup) {
|
|
|
574
679
|
let bestName;
|
|
575
680
|
let bestDist = Number.POSITIVE_INFINITY;
|
|
576
681
|
const threshold = Math.max(2, Math.floor(input.length / 2));
|
|
577
|
-
for (const key of lookup
|
|
578
|
-
|
|
579
|
-
if (entry ===
|
|
580
|
-
const
|
|
581
|
-
|
|
582
|
-
if (key.length < 2) continue;
|
|
583
|
-
if (key !== canonicalName && alias?.hidden) continue;
|
|
682
|
+
for (const [key, entry] of lookup) {
|
|
683
|
+
if (key.length < 2 || entry.parity) continue;
|
|
684
|
+
if (entry.negated && entry.schema.negation?.hidden === true) continue;
|
|
685
|
+
const alias = entry.schema.aliases.find((candidate) => candidate.name === key);
|
|
686
|
+
if (key !== entry.name && !entry.negated && alias?.hidden) continue;
|
|
584
687
|
const dist = levenshtein(input, key);
|
|
585
688
|
if (dist < bestDist && dist <= threshold) {
|
|
586
689
|
bestDist = dist;
|
|
@@ -618,4 +721,4 @@ function levenshtein(a, b) {
|
|
|
618
721
|
return row[aLen] ?? 0;
|
|
619
722
|
}
|
|
620
723
|
//#endregion
|
|
621
|
-
export { buildFlagLookup, flagExpectsValue, includesBeforeSeparator, parse, stripBeforeSeparator, tokenize };
|
|
724
|
+
export { buildFlagLookup, camelToKebab, flagExpectsValue, includesBeforeSeparator, kebabToCamel, parse, stripBeforeSeparator, tokenize };
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import "../schema/index.mjs";
|
|
2
1
|
import { DeprecationWarning } from "./contracts.mjs";
|
|
3
2
|
import { CommandArgEntry } from "../schema/command.mjs";
|
|
3
|
+
import "../schema/index.mjs";
|
|
4
4
|
//#region src/core/resolve/args.d.ts
|
|
5
5
|
/** Walk every declared arg through the resolution chain (cli -> stdin -> env -> default), collecting deprecations and throwing aggregated errors. */
|
|
6
6
|
declare function resolveArgs(argEntries: readonly CommandArgEntry[], parsedArgs: Readonly<Record<string, unknown>>, stdinData: string | null | undefined, env: Readonly<Record<string, string | undefined>>, deprecations: DeprecationWarning[]): Readonly<Record<string, unknown>>;
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { ArgSchema } from "../schema/arg.mjs";
|
|
2
2
|
import { FlagSchema } from "../schema/flag.mjs";
|
|
3
|
-
import "../schema/index.mjs";
|
|
4
3
|
import { ArgDiagnosticSource, FlagDiagnosticSource } from "./contracts.mjs";
|
|
5
4
|
import { ValidationError } from "../errors/index.mjs";
|
|
5
|
+
import "../schema/index.mjs";
|
|
6
6
|
//#region src/core/resolve/coerce.d.ts
|
|
7
7
|
type CoerceSource = FlagDiagnosticSource;
|
|
8
8
|
/** Discriminated result of a value coercion attempt — success with the coerced value, or failure with a structured validation error. */
|
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import "../schema/index.mjs";
|
|
2
|
-
import { ParseResult } from "../parse/index.mjs";
|
|
3
1
|
import { PromptEngine } from "../prompt/index.mjs";
|
|
4
2
|
import { CommandSchema } from "../schema/command.mjs";
|
|
3
|
+
import "../schema/index.mjs";
|
|
4
|
+
import { ParseResult } from "../parse/index.mjs";
|
|
5
5
|
//#region src/core/resolve/contracts.d.ts
|
|
6
6
|
/** Ordered flag resolution stages owned by the resolver. */
|
|
7
7
|
declare const FLAG_RESOLUTION_ORDER: readonly ['cli', 'env', 'config', 'prompt', 'default'];
|
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import "../schema/index.mjs";
|
|
2
|
-
import { ParseResult } from "../parse/index.mjs";
|
|
3
1
|
import { DeprecationWarning, ResolveOptions, ResolveResult } from "./contracts.mjs";
|
|
4
2
|
import { CommandSchema } from "../schema/command.mjs";
|
|
3
|
+
import "../schema/index.mjs";
|
|
4
|
+
import { ParseResult } from "../parse/index.mjs";
|
|
5
5
|
//#region src/core/resolve/index.d.ts
|
|
6
6
|
/**
|
|
7
7
|
* Resolve parsed values against a command schema.
|
|
@@ -336,7 +336,7 @@ type DeriveParams<F extends Record<string, FlagBuilder<FlagConfig>>, A extends R
|
|
|
336
336
|
* Handlers may be async; the resolved value follows the same rules.
|
|
337
337
|
* They cannot wrap downstream execution; use {@linkcode middleware} for that.
|
|
338
338
|
*/
|
|
339
|
-
type DeriveHandler<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown> = Record<string, never>, Output extends Record<string, unknown> | undefined
|
|
339
|
+
type DeriveHandler<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown> = Record<string, never>, Output extends Record<string, unknown> | undefined = undefined> = (params: DeriveParams<F, A, C>) => Output | Promise<Output> | void | Promise<void>;
|
|
340
340
|
/**
|
|
341
341
|
* Type-erased derive handler stored on the command builder.
|
|
342
342
|
*
|
|
@@ -631,7 +631,7 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
|
|
|
631
631
|
* @param handler - Derive function receiving typed args/flags/ctx.
|
|
632
632
|
* @returns The builder (for chaining).
|
|
633
633
|
*/
|
|
634
|
-
derive<Output extends Record<string, unknown> | undefined
|
|
634
|
+
derive<Output extends Record<string, unknown> | undefined = undefined>(handler: DeriveHandler<F, A, C, Output>): CommandBuilder<F, A, WidenDerivedContext<C, Output>>;
|
|
635
635
|
/**
|
|
636
636
|
* Register middleware to run before the action handler.
|
|
637
637
|
*
|