@kjanat/dreamcli 3.0.0-rc.6 → 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.
Files changed (94) hide show
  1. package/CHANGELOG.md +94 -1
  2. package/dist/core/cli/dispatch.d.mts +6 -5
  3. package/dist/core/cli/dispatch.mjs +7 -5
  4. package/dist/core/cli/help-links.d.mts +0 -1
  5. package/dist/core/cli/index.d.mts +27 -2
  6. package/dist/core/cli/index.mjs +28 -14
  7. package/dist/core/cli/planner.d.mts +3 -1
  8. package/dist/core/cli/planner.mjs +12 -12
  9. package/dist/core/cli/plugin.d.mts +1 -1
  10. package/dist/core/cli/propagate.d.mts +1 -1
  11. package/dist/core/cli/root-help.d.mts +0 -1
  12. package/dist/core/cli/root-help.mjs +38 -21
  13. package/dist/core/cli/root-surface.d.mts +0 -1
  14. package/dist/core/cli/runtime-preflight.d.mts +12 -2
  15. package/dist/core/cli/runtime-preflight.mjs +5 -4
  16. package/dist/core/completion/index.d.mts +0 -1
  17. package/dist/core/completion/index.mjs +1 -1
  18. package/dist/core/completion/shells/bash.d.mts +0 -1
  19. package/dist/core/completion/shells/bash.mjs +8 -4
  20. package/dist/core/completion/shells/fish.d.mts +0 -1
  21. package/dist/core/completion/shells/fish.mjs +6 -3
  22. package/dist/core/completion/shells/powershell.d.mts +0 -1
  23. package/dist/core/completion/shells/powershell.mjs +10 -5
  24. package/dist/core/completion/shells/shared.d.mts +13 -2
  25. package/dist/core/completion/shells/shared.mjs +24 -2
  26. package/dist/core/completion/shells/zsh.d.mts +0 -1
  27. package/dist/core/completion/shells/zsh.mjs +11 -4
  28. package/dist/core/config/index.d.mts +2 -3
  29. package/dist/core/config/index.mjs +2 -2
  30. package/dist/core/config/package-json.d.mts +27 -4
  31. package/dist/core/config/package-json.mjs +20 -19
  32. package/dist/core/errors/index.d.mts +1 -1
  33. package/dist/core/execution/index.d.mts +0 -1
  34. package/dist/core/execution/index.mjs +8 -4
  35. package/dist/core/help/ansi.mjs +3 -2
  36. package/dist/core/help/index.d.mts +22 -3
  37. package/dist/core/help/index.mjs +65 -53
  38. package/dist/core/help/theme.d.mts +68 -0
  39. package/dist/core/help/theme.mjs +46 -0
  40. package/dist/core/json-schema/index.d.mts +1 -1
  41. package/dist/core/json-schema/index.mjs +39 -8
  42. package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
  43. package/dist/core/json-schema/meta-descriptions.generated.mjs +14 -5
  44. package/dist/core/output/activity.d.mts +0 -1
  45. package/dist/core/output/contracts.d.mts +0 -1
  46. package/dist/core/output/contracts.mjs +1 -1
  47. package/dist/core/output/index.d.mts +0 -1
  48. package/dist/core/output/index.mjs +1 -1
  49. package/dist/core/output/renderers.d.mts +0 -1
  50. package/dist/core/parse/index.d.mts +40 -7
  51. package/dist/core/parse/index.mjs +209 -40
  52. package/dist/core/prompt/index.d.mts +1 -0
  53. package/dist/core/resolve/args.d.mts +1 -1
  54. package/dist/core/resolve/coerce.d.mts +1 -1
  55. package/dist/core/resolve/coerce.mjs +71 -14
  56. package/dist/core/resolve/contracts.d.mts +7 -2
  57. package/dist/core/resolve/errors.d.mts +0 -1
  58. package/dist/core/resolve/flags.d.mts +7 -2
  59. package/dist/core/resolve/flags.mjs +61 -6
  60. package/dist/core/resolve/index.d.mts +2 -2
  61. package/dist/core/resolve/index.mjs +1 -1
  62. package/dist/core/resolve/property.d.mts +3 -0
  63. package/dist/core/resolve/property.mjs +11 -3
  64. package/dist/core/schema/activity.d.mts +31 -11
  65. package/dist/core/schema/arg.d.mts +1 -2
  66. package/dist/core/schema/command.d.mts +8 -6
  67. package/dist/core/schema/command.mjs +26 -12
  68. package/dist/core/schema/flag.d.mts +439 -10
  69. package/dist/core/schema/flag.mjs +255 -3
  70. package/dist/core/schema/index.d.mts +4 -2
  71. package/dist/core/schema/middleware.d.mts +4 -3
  72. package/dist/core/schema/prompt.d.mts +5 -2
  73. package/dist/core/schema/run.d.mts +20 -1
  74. package/dist/core/schema/string-constraints.d.mts +97 -0
  75. package/dist/core/schema/string-constraints.mjs +69 -0
  76. package/dist/core/schema/value-parsers.d.mts +78 -0
  77. package/dist/core/schema/value-parsers.mjs +142 -0
  78. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  79. package/dist/core/testkit/index.d.mts +0 -31
  80. package/dist/core/testkit/index.mjs +1 -1
  81. package/dist/index.d.mts +8 -4
  82. package/dist/index.mjs +7 -7
  83. package/dist/runtime/adapter.d.mts +22 -1
  84. package/dist/runtime/adapter.mjs +3 -0
  85. package/dist/runtime/auto.d.mts +0 -1
  86. package/dist/runtime/deno.d.mts +15 -5
  87. package/dist/runtime/deno.mjs +9 -0
  88. package/dist/runtime/node.d.mts +2 -2
  89. package/dist/runtime/node.mjs +10 -0
  90. package/dist/runtime.d.mts +1 -0
  91. package/dist/testkit.d.mts +1 -0
  92. package/dist/version.mjs +2 -2
  93. package/dreamcli.schema.json +35 -6
  94. package/package.json +12 -13
@@ -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,5 @@
1
1
  import { ActivityEvent, ProgressHandle, ProgressOptions, SpinnerHandle } from "../schema/activity.mjs";
2
2
  import { WriteFn } from "./writer.mjs";
3
-
4
3
  //#region src/core/output/activity.d.ts
5
4
  /**
6
5
  * Noop spinner handle singleton.
@@ -1,5 +1,4 @@
1
1
  import { Fallback, TableOptions } from "../schema/activity.mjs";
2
-
3
2
  //#region src/core/output/contracts.d.ts
4
3
  /** Ordered output verbosity levels owned by the output policy layer. */
5
4
  declare const OUTPUT_VERBOSITY_LEVELS: readonly ['normal', 'quiet'];
@@ -54,4 +54,4 @@ function resolveProgressPolicy(policy, fallback) {
54
54
  };
55
55
  }
56
56
  //#endregion
57
- export { resolveOutputPolicy, resolveProgressPolicy, resolveSpinnerPolicy, resolveTableFormat, resolveTableTextStream, resolveTextStream, shouldEmitInfo };
57
+ export { resolveActivityRenderMode, resolveOutputPolicy, resolveProgressPolicy, resolveSpinnerPolicy, resolveTableFormat, resolveTableTextStream, resolveTextStream, shouldEmitInfo };
@@ -4,7 +4,6 @@ import { CaptureProgressHandle, CaptureSpinnerHandle, StaticProgressHandle, Stat
4
4
  import { OutputPolicy, Verbosity } from "./contracts.mjs";
5
5
  import { Out } from "../schema/command.mjs";
6
6
  import { Colors } from "ansispeck";
7
-
8
7
  //#region src/core/output/index.d.ts
9
8
  /**
10
9
  * Configuration for creating an output channel.
@@ -439,4 +439,4 @@ function createCaptureOutput(options) {
439
439
  }), captured.activity), captured];
440
440
  }
441
441
  //#endregion
442
- export { clearRequestedExitCode, createCaptureOutput, createOutput, getRequestedExitCode };
442
+ export { CaptureOutputChannel, CaptureProgressHandle, CaptureSpinnerHandle, OutputChannel, clearRequestedExitCode, createCaptureOutput, createOutput, getRequestedExitCode, setRequestedExitCode, writeLine };
@@ -1,7 +1,6 @@
1
1
  import { ProgressHandle, ProgressOptions, SpinnerHandle } from "../schema/activity.mjs";
2
2
  import { WriteFn } from "./writer.mjs";
3
3
  import { ActivityPolicy, OutputStream } from "./contracts.mjs";
4
-
5
4
  //#region src/core/output/renderers.d.ts
6
5
  /**
7
6
  * Paired write functions for the two standard output streams.
@@ -1,6 +1,6 @@
1
1
  import { FlagSchema } from "../schema/flag.mjs";
2
2
  import { CommandSchema } from "../schema/command.mjs";
3
-
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 };
@@ -1,6 +1,7 @@
1
- import { describeNumberConstraintViolation, validateNumberConstraints } from "../schema/number-constraints.mjs";
2
- import { getFlagAliasNames } from "../schema/flag.mjs";
3
1
  import { ParseError } from "../errors/index.mjs";
2
+ import { describeNumberConstraintViolation, validateNumberConstraints } from "../schema/number-constraints.mjs";
3
+ import { describeStringConstraintViolation, validateStringConstraints } from "../schema/string-constraints.mjs";
4
+ import { getFlagAliasNames, getFlagNegatedName } from "../schema/flag.mjs";
4
5
  //#region src/core/parse/index.ts
5
6
  /**
6
7
  * Argv tokenization and parsing against command schemas.
@@ -122,30 +123,114 @@ function stripBeforeSeparator(argv, token) {
122
123
  const filteredHead = head.filter((arg) => arg !== token);
123
124
  return separatorIndex === -1 ? filteredHead : [...filteredHead, ...argv.slice(separatorIndex)];
124
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
+ }
134
+ /**
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
+ }
125
147
  /**
126
- * Build a map from flag name/alias → [canonicalName, {@link FlagSchema}].
148
+ * Build a map from flag spelling → {@link FlagLookupEntry}.
127
149
  *
128
- * Supports both long names and single-char aliases for short flag expansion.
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.
129
156
  *
130
157
  * @param flags - Flag schemas keyed by canonical name
131
- * @returns Lookup map covering all names and aliases
158
+ * @param options - Parity toggle (see {@link ParseOptions})
159
+ * @returns Lookup map covering all resolvable spellings
132
160
  */
133
- function buildFlagLookup(flags) {
161
+ function buildFlagLookup(flags, options) {
134
162
  const lookup = /* @__PURE__ */ new Map();
135
163
  for (const [name, schema] of Object.entries(flags)) {
136
- lookup.set(name, [name, schema]);
137
- for (const alias of getFlagAliasNames(schema, { includeHidden: true })) lookup.set(alias, [name, schema]);
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
+ });
138
190
  }
139
191
  return lookup;
140
192
  }
141
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
+ /**
142
227
  * Whether a flag kind expects a value argument (vs. being a bare boolean).
143
228
  *
144
229
  * @param schema - Flag schema to check
145
230
  * @returns `true` if the flag expects a value token after it
146
231
  */
147
232
  function flagExpectsValue(schema) {
148
- return schema.kind !== "boolean";
233
+ return schema.kind !== "boolean" && schema.kind !== "count";
149
234
  }
150
235
  /**
151
236
  * Coerce a raw string to the flag's declared kind.
@@ -158,7 +243,22 @@ function flagExpectsValue(schema) {
158
243
  */
159
244
  function coerceFlagValue(flagName, raw, schema, displayName = `--${flagName}`) {
160
245
  switch (schema.kind) {
161
- case "string": return raw;
246
+ case "string": {
247
+ const violation = validateStringConstraints(raw, schema.stringConstraints);
248
+ if (violation !== void 0) throw new ParseError(`Invalid value '${raw}' for flag ${displayName}: ${describeStringConstraintViolation(violation)}`, {
249
+ code: "INVALID_VALUE",
250
+ details: {
251
+ flag: flagName,
252
+ input: displayName,
253
+ value: raw,
254
+ expected: "string",
255
+ constraint: violation.kind,
256
+ ..."bound" in violation ? { bound: violation.bound } : {},
257
+ ..."pattern" in violation ? { pattern: violation.pattern } : {}
258
+ }
259
+ });
260
+ return raw;
261
+ }
162
262
  case "number": {
163
263
  const n = Number(raw);
164
264
  if (Number.isNaN(n)) throw new ParseError(`Invalid number value '${raw}' for flag ${displayName}`, {
@@ -236,6 +336,20 @@ function coerceFlagValue(flagName, raw, schema, displayName = `--${flagName}`) {
236
336
  cause: err
237
337
  });
238
338
  }
339
+ case "count": {
340
+ const n = raw.trim() === "" ? NaN : Number(raw);
341
+ if (!Number.isInteger(n) || n < 0) throw new ParseError(`Invalid count value '${raw}' for flag ${displayName}. Use a non-negative integer`, {
342
+ code: "INVALID_VALUE",
343
+ details: {
344
+ flag: flagName,
345
+ input: displayName,
346
+ value: raw,
347
+ expected: "count"
348
+ }
349
+ });
350
+ return n;
351
+ }
352
+ case "keyValue": return parseKeyValuePair(flagName, raw, displayName);
239
353
  }
240
354
  }
241
355
  /**
@@ -319,6 +433,7 @@ function coerceArgValue(argName, raw, schema) {
319
433
  *
320
434
  * @param schema - The command schema to parse against
321
435
  * @param argv - Raw argv strings (NOT including the command name itself)
436
+ * @param options - Parser behavior toggles (see {@link ParseOptions})
322
437
  * @returns Parsed flag and arg values
323
438
  * @throws ParseError for unknown flags, missing values, type mismatches
324
439
  *
@@ -328,11 +443,12 @@ function coerceArgValue(argName, raw, schema) {
328
443
  * // => { args: { target: 'production' }, flags: { force: true } }
329
444
  * ```
330
445
  */
331
- function parse(schema, argv) {
446
+ function parse(schema, argv, options) {
332
447
  const tokens = tokenize(argv);
333
- const flagLookup = buildFlagLookup(schema.flags);
448
+ const flagLookup = buildFlagLookup(schema.flags, options);
334
449
  const flags = {};
335
450
  const positionals = [];
451
+ const occurrences = /* @__PURE__ */ new Map();
336
452
  let i = 0;
337
453
  while (i < tokens.length) {
338
454
  const token = tokens[i];
@@ -347,10 +463,10 @@ function parse(schema, argv) {
347
463
  continue;
348
464
  }
349
465
  if (token.kind === "long-flag") {
350
- i = parseLongFlag(token, tokens, i, flagLookup, flags);
466
+ i = parseLongFlag(token, tokens, i, flagLookup, flags, occurrences);
351
467
  continue;
352
468
  }
353
- i = parseShortFlags(token, tokens, i, flagLookup, flags);
469
+ i = parseShortFlags(token, tokens, i, flagLookup, flags, occurrences);
354
470
  }
355
471
  return {
356
472
  flags,
@@ -363,11 +479,12 @@ function parse(schema, argv) {
363
479
  * @param token - Long-flag token to process
364
480
  * @param tokens - Full token array (for lookahead)
365
481
  * @param startIdx - Current index of `token` in the array
366
- * @param flagLookup - Name/alias → [canonical, schema] map from {@link buildFlagLookup}
482
+ * @param flagLookup - Spelling → {@link FlagLookupEntry} map from {@link buildFlagLookup}
367
483
  * @param flags - Mutable accumulator for resolved flag values
484
+ * @param occurrences - Per-parse duplicate-occurrence accumulator
368
485
  * @returns Next index to continue parsing from
369
486
  */
370
- function parseLongFlag(token, tokens, startIdx, flagLookup, flags) {
487
+ function parseLongFlag(token, tokens, startIdx, flagLookup, flags, occurrences) {
371
488
  const entry = flagLookup.get(token.name);
372
489
  if (!entry) {
373
490
  const suggestion = suggestFlag(token.name, flagLookup);
@@ -380,18 +497,36 @@ function parseLongFlag(token, tokens, startIdx, flagLookup, flags) {
380
497
  ...suggestion ? { suggest: `--${suggestion}` } : {}
381
498
  });
382
499
  }
383
- const [canonicalName, flagSchema] = entry;
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
+ }
384
514
  if (!flagExpectsValue(flagSchema)) {
385
- if (token.value !== void 0) flags[canonicalName] = coerceFlagValue(canonicalName, token.value, flagSchema, `--${token.name}`);
386
- else flags[canonicalName] = true;
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") {
519
+ const existing = flags[canonicalName];
520
+ flags[canonicalName] = (typeof existing === "number" ? existing : 0) + 1;
521
+ } else if (recordFlagOccurrence(occurrences, canonicalName, flagSchema, true, displayName)) flags[canonicalName] = true;
387
522
  return startIdx + 1;
388
523
  }
389
524
  if (token.value !== void 0) {
390
- setFlagValue(flags, canonicalName, flagSchema, token.value);
525
+ if (recordFlagOccurrence(occurrences, canonicalName, flagSchema, token.value, displayName)) setFlagValue(flags, canonicalName, flagSchema, token.value);
391
526
  return startIdx + 1;
392
527
  }
393
528
  const nextToken = tokens[startIdx + 1];
394
- if (nextToken?.kind !== "positional") throw new ParseError(`Flag --${token.name} requires a value`, {
529
+ if (nextToken?.kind !== "positional") throw new ParseError(`Flag ${displayName} requires a value`, {
395
530
  code: "MISSING_VALUE",
396
531
  details: {
397
532
  flag: canonicalName,
@@ -399,7 +534,7 @@ function parseLongFlag(token, tokens, startIdx, flagLookup, flags) {
399
534
  kind: flagSchema.kind
400
535
  }
401
536
  });
402
- setFlagValue(flags, canonicalName, flagSchema, nextToken.value, `--${token.name}`);
537
+ if (recordFlagOccurrence(occurrences, canonicalName, flagSchema, nextToken.value, displayName)) setFlagValue(flags, canonicalName, flagSchema, nextToken.value, displayName);
403
538
  return startIdx + 2;
404
539
  }
405
540
  /**
@@ -408,11 +543,12 @@ function parseLongFlag(token, tokens, startIdx, flagLookup, flags) {
408
543
  * @param token - Short-flags token to expand
409
544
  * @param tokens - Full token array (for lookahead)
410
545
  * @param startIdx - Current index of `token` in the array
411
- * @param flagLookup - Name/alias → [canonical, schema] map from {@link buildFlagLookup}
546
+ * @param flagLookup - Spelling → {@link FlagLookupEntry} map from {@link buildFlagLookup}
412
547
  * @param flags - Mutable accumulator for resolved flag values
548
+ * @param occurrences - Per-parse duplicate-occurrence accumulator
413
549
  * @returns Next index to continue parsing from
414
550
  */
415
- function parseShortFlags(token, tokens, startIdx, flagLookup, flags) {
551
+ function parseShortFlags(token, tokens, startIdx, flagLookup, flags, occurrences) {
416
552
  const { chars } = token;
417
553
  let nextIdx = startIdx + 1;
418
554
  for (let ci = 0; ci < chars.length; ci++) {
@@ -422,13 +558,18 @@ function parseShortFlags(token, tokens, startIdx, flagLookup, flags) {
422
558
  code: "UNKNOWN_FLAG",
423
559
  details: { flag: ch }
424
560
  });
425
- const [canonicalName, flagSchema] = entry;
561
+ const { name: canonicalName, schema: flagSchema } = entry;
562
+ const displayName = `-${ch}`;
426
563
  if (!flagExpectsValue(flagSchema)) {
427
- flags[canonicalName] = true;
564
+ if (flagSchema.kind === "count") {
565
+ const existing = flags[canonicalName];
566
+ flags[canonicalName] = (typeof existing === "number" ? existing : 0) + 1;
567
+ } else if (recordFlagOccurrence(occurrences, canonicalName, flagSchema, true, displayName)) flags[canonicalName] = true;
428
568
  continue;
429
569
  }
430
570
  if (ci < chars.length - 1) {
431
- setFlagValue(flags, canonicalName, flagSchema, chars.slice(ci + 1), `-${ch}`);
571
+ const inlineValue = chars.slice(ci + 1);
572
+ if (recordFlagOccurrence(occurrences, canonicalName, flagSchema, inlineValue, displayName)) setFlagValue(flags, canonicalName, flagSchema, inlineValue, displayName);
432
573
  break;
433
574
  }
434
575
  const nextToken = tokens[nextIdx];
@@ -440,7 +581,7 @@ function parseShortFlags(token, tokens, startIdx, flagLookup, flags) {
440
581
  kind: flagSchema.kind
441
582
  }
442
583
  });
443
- setFlagValue(flags, canonicalName, flagSchema, nextToken.value, `-${ch}`);
584
+ if (recordFlagOccurrence(occurrences, canonicalName, flagSchema, nextToken.value, displayName)) setFlagValue(flags, canonicalName, flagSchema, nextToken.value, displayName);
444
585
  nextIdx++;
445
586
  }
446
587
  return nextIdx;
@@ -454,12 +595,42 @@ function parseShortFlags(token, tokens, startIdx, flagLookup, flags) {
454
595
  * @param rawValue - Raw string value from argv
455
596
  */
456
597
  function setFlagValue(flags, name, schema, rawValue, displayName = `--${name}`) {
457
- const coerced = coerceFlagValue(name, rawValue, schema, displayName);
458
598
  if (schema.kind === "array") {
599
+ const coercedParts = (schema.separator !== void 0 ? rawValue.split(schema.separator) : [rawValue]).filter((part) => schema.separator === void 0 || part.length > 0).map((part) => coerceFlagValue(name, part, schema, displayName));
459
600
  const existing = flags[name];
460
- if (Array.isArray(existing)) existing.push(coerced);
461
- else flags[name] = [coerced];
462
- } else flags[name] = coerced;
601
+ if (Array.isArray(existing)) existing.push(...coercedParts);
602
+ else flags[name] = coercedParts;
603
+ return;
604
+ }
605
+ if (schema.kind === "keyValue") {
606
+ const pair = parseKeyValuePair(name, rawValue, displayName);
607
+ const existing = flags[name];
608
+ flags[name] = Object.fromEntries([...isPlainRecord(existing) ? Object.entries(existing) : [], pair]);
609
+ return;
610
+ }
611
+ flags[name] = coerceFlagValue(name, rawValue, schema, displayName);
612
+ }
613
+ /** Narrow to a mutable string-record accumulator (keyValue flags only ever store these). */
614
+ function isPlainRecord(value) {
615
+ return typeof value === "object" && value !== null && !Array.isArray(value);
616
+ }
617
+ /**
618
+ * Split a `KEY=VALUE` token at the first `=`.
619
+ *
620
+ * @throws ParseError when the token has no `=` or an empty key.
621
+ */
622
+ function parseKeyValuePair(flagName, raw, displayName = `--${flagName}`) {
623
+ const eq = raw.indexOf("=");
624
+ if (eq <= 0) throw new ParseError(`Invalid value '${raw}' for flag ${displayName}. Use KEY=VALUE`, {
625
+ code: "INVALID_VALUE",
626
+ details: {
627
+ flag: flagName,
628
+ input: displayName,
629
+ value: raw,
630
+ expected: "key=value"
631
+ }
632
+ });
633
+ return [raw.slice(0, eq), raw.slice(eq + 1)];
463
634
  }
464
635
  /**
465
636
  * Map positional values to named args based on schema ordering.
@@ -508,13 +679,11 @@ function suggestFlag(input, lookup) {
508
679
  let bestName;
509
680
  let bestDist = Number.POSITIVE_INFINITY;
510
681
  const threshold = Math.max(2, Math.floor(input.length / 2));
511
- for (const key of lookup.keys()) {
512
- const entry = lookup.get(key);
513
- if (entry === void 0) continue;
514
- const [canonicalName, schema] = entry;
515
- const alias = schema.aliases.find((candidate) => candidate.name === key);
516
- if (key.length < 2) continue;
517
- 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;
518
687
  const dist = levenshtein(input, key);
519
688
  if (dist < bestDist && dist <= threshold) {
520
689
  bestDist = dist;
@@ -552,4 +721,4 @@ function levenshtein(a, b) {
552
721
  return row[aLen] ?? 0;
553
722
  }
554
723
  //#endregion
555
- export { buildFlagLookup, flagExpectsValue, includesBeforeSeparator, parse, stripBeforeSeparator, tokenize };
724
+ export { buildFlagLookup, camelToKebab, flagExpectsValue, includesBeforeSeparator, kebabToCamel, parse, stripBeforeSeparator, tokenize };
@@ -1,5 +1,6 @@
1
1
  import { ConfirmPromptConfig, InputPromptConfig, PromptConfig, PromptResult, SelectChoice } from "../schema/prompt.mjs";
2
2
  import { WriteFn } from "../output/writer.mjs";
3
+ import "../output/index.mjs";
3
4
  //#region src/core/prompt/index.d.ts
4
5
  /**
5
6
  * A select prompt config with choices guaranteed non-empty.
@@ -1,6 +1,6 @@
1
1
  import { DeprecationWarning } from "./contracts.mjs";
2
2
  import { CommandArgEntry } from "../schema/command.mjs";
3
-
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>>;
@@ -2,7 +2,7 @@ import { ArgSchema } from "../schema/arg.mjs";
2
2
  import { FlagSchema } from "../schema/flag.mjs";
3
3
  import { ArgDiagnosticSource, FlagDiagnosticSource } from "./contracts.mjs";
4
4
  import { ValidationError } from "../errors/index.mjs";
5
-
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. */