@optique/core 1.4.0-dev.2627 → 1.4.0-dev.2630

package/dist/primitives.cjs

@@ -885,11 +885,12 @@ function flag(...args) {
 			}
 			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2 && !/^-[^-]$/u.test(name)).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
 			for (const prefix of prefixes) if (context.buffer[0].startsWith(prefix)) {
+				const optionName$1 = prefix.slice(0, -1);
 				const value = context.buffer[0].slice(prefix.length);
 				return {
 					success: false,
 					consumed: 1,
-					error: require_message.message`Flag ${require_message.optionName(prefix.slice(0, -1))} does not accept a value, but got: ${value}.`
+					error: options.errors?.unexpectedValue ? typeof options.errors.unexpectedValue === "function" ? options.errors.unexpectedValue(optionName$1, value) : options.errors.unexpectedValue : require_message.message`Flag ${require_message.optionName(optionName$1)} does not accept a value, but got: ${value}.`
 				};
 			}
 			const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/u));

package/dist/primitives.d.cts

@@ -196,6 +196,14 @@ interface FlagErrorOptions {
    * Can be a static message or a function that receives the token.
    */
   duplicate?: Message | ((token: string) => Message);
+  /**
+   * Custom error message when a flag receives an unexpected value.
+   * Can be a static message or a function that receives the matched option
+   * name and the value after the separator, including an empty value.
+   *
+   * @since 1.4.0
+   */
+  readonly unexpectedValue?: Message | ((optionName: string, value: string) => Message);
   /**
    * Custom error message when no matching flag is found.
    * Can be a static message or a function that receives:

package/dist/primitives.d.ts

@@ -196,6 +196,14 @@ interface FlagErrorOptions {
    * Can be a static message or a function that receives the token.
    */
   duplicate?: Message | ((token: string) => Message);
+  /**
+   * Custom error message when a flag receives an unexpected value.
+   * Can be a static message or a function that receives the matched option
+   * name and the value after the separator, including an empty value.
+   *
+   * @since 1.4.0
+   */
+  readonly unexpectedValue?: Message | ((optionName: string, value: string) => Message);
   /**
    * Custom error message when no matching flag is found.
    * Can be a static message or a function that receives:

package/dist/primitives.js

@@ -885,11 +885,12 @@ function flag(...args) {
 			}
 			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2 && !/^-[^-]$/u.test(name)).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
 			for (const prefix of prefixes) if (context.buffer[0].startsWith(prefix)) {
+				const optionName$1 = prefix.slice(0, -1);
 				const value = context.buffer[0].slice(prefix.length);
 				return {
 					success: false,
 					consumed: 1,
-					error: message`Flag ${optionName(prefix.slice(0, -1))} does not accept a value, but got: ${value}.`
+					error: options.errors?.unexpectedValue ? typeof options.errors.unexpectedValue === "function" ? options.errors.unexpectedValue(optionName$1, value) : options.errors.unexpectedValue : message`Flag ${optionName(optionName$1)} does not accept a value, but got: ${value}.`
 				};
 			}
 			const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/u));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2627",
+  "version": "1.4.0-dev.2630",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2627+4dd892c0",
+    "@optique/env": "1.4.0-dev.2630+2e4e647b",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -34,12 +34,12 @@ Core rules
     It groups untitled entries only on pages with visible commands. See
     <https://optique.dev/cookbook.md#command-and-option-headings-in-help>.
  -  Let TypeScript infer results unless another API needs a separate interface.
- -  Parsers are usually required. `optional(p)` yields `undefined`, and
-    `withDefault(p, value)` supplies a fallback. Use
-    `withDefault(flag("--name"), false)` for optional Boolean flags.
+ -  Parsers usually require input. `optional(p)` yields `undefined`; use
+    `withDefault(p, value)` or `withDefault(flag("-v"), false)` for fallbacks.
  -  Use semantic `message` helpers for descriptions and errors. Since 1.3.0,
     customize terminal output with `theme` or `messageFormatter`, preserving
     `initialWidth`, quoting, and width options. Keep canonical errors unthemed.
+    `flag()` supports static/callback `errors.unexpectedValue` since 1.4.0.
  -  Use value parsers such as `integer()`, `choice()`, `biject()`, `regExp()`,
     `url()`, `origin()`, and `uuid()` instead of validating raw strings after
     parsing. Use `regExp({ flags })` for user-supplied sources, `biject()` for