@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.
Files changed (47) hide show
  1. package/CHANGELOG.md +71 -1
  2. package/dist/core/cli/dispatch.d.mts +6 -4
  3. package/dist/core/cli/dispatch.mjs +6 -4
  4. package/dist/core/cli/index.d.mts +27 -1
  5. package/dist/core/cli/index.mjs +32 -15
  6. package/dist/core/cli/planner.d.mts +3 -0
  7. package/dist/core/cli/planner.mjs +9 -9
  8. package/dist/core/cli/propagate.d.mts +1 -1
  9. package/dist/core/cli/root-help.mjs +32 -20
  10. package/dist/core/cli/runtime-preflight.d.mts +7 -1
  11. package/dist/core/cli/runtime-preflight.mjs +3 -3
  12. package/dist/core/completion/shells/bash.mjs +5 -2
  13. package/dist/core/completion/shells/fish.mjs +3 -1
  14. package/dist/core/completion/shells/powershell.mjs +8 -4
  15. package/dist/core/completion/shells/shared.d.mts +13 -2
  16. package/dist/core/completion/shells/shared.mjs +19 -2
  17. package/dist/core/completion/shells/zsh.mjs +8 -2
  18. package/dist/core/config/index.d.mts +2 -2
  19. package/dist/core/config/package-json.d.mts +27 -3
  20. package/dist/core/config/package-json.mjs +20 -19
  21. package/dist/core/errors/index.d.mts +1 -1
  22. package/dist/core/execution/index.mjs +13 -2
  23. package/dist/core/help/index.d.mts +22 -3
  24. package/dist/core/help/index.mjs +55 -49
  25. package/dist/core/help/theme.d.mts +68 -0
  26. package/dist/core/help/theme.mjs +46 -0
  27. package/dist/core/json-schema/index.d.mts +15 -2
  28. package/dist/core/json-schema/index.mjs +32 -4
  29. package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
  30. package/dist/core/json-schema/meta-descriptions.generated.mjs +14 -5
  31. package/dist/core/parse/index.d.mts +40 -7
  32. package/dist/core/parse/index.mjs +137 -34
  33. package/dist/core/resolve/args.d.mts +1 -1
  34. package/dist/core/resolve/coerce.d.mts +1 -1
  35. package/dist/core/resolve/contracts.d.mts +2 -2
  36. package/dist/core/resolve/index.d.mts +2 -2
  37. package/dist/core/schema/command.d.mts +2 -2
  38. package/dist/core/schema/command.mjs +23 -11
  39. package/dist/core/schema/flag.d.mts +148 -9
  40. package/dist/core/schema/flag.mjs +71 -1
  41. package/dist/core/schema/index.d.mts +2 -2
  42. package/dist/core/schema/run.d.mts +11 -0
  43. package/dist/index.d.mts +7 -6
  44. package/dist/index.mjs +3 -3
  45. package/dist/version.mjs +2 -2
  46. package/dreamcli.schema.json +33 -6
  47. 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.name;
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?: string;
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 name/alias → [canonicalName, {@link FlagSchema}].
114
+ * Build a map from flag spelling → {@link FlagLookupEntry}.
89
115
  *
90
- * Supports both long names and single-char aliases for short flag expansion.
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
- * @returns Lookup map covering all names and aliases
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>>): ReadonlyMap<string, readonly [name: string, schema: 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 };