@optique/core 1.3.0-dev.2515 → 1.3.0-dev.2521

package/dist/facade.cjs

@@ -516,10 +516,14 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = []) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
-	const callOnError = (code) => onError(code);
+	const callOnError = (code, error) => onError(code, error);
 	const callOnCompletion = (code) => onCompletion(code);
 	if (!shellName) {
-		stderr("Error: Missing shell name for completion.\n");
+		const error = require_message.message`Missing shell name for completion.`;
+		stderr(`Error: ${require_message.formatMessage(error, {
+			colors,
+			quotes: !colors
+		})}\n`);
 		if (completionParser) {
 			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 			const doc = require_internal_parser.getDocPage(completionParser, [displayName]);
@@ -532,10 +536,10 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			}));
 		}
 		return require_mode_dispatch.dispatchByMode(parser.mode, () => {
-			const result = callOnError(1);
+			const result = callOnError(1, error);
 			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
 			return result;
-		}, async () => callOnError(1));
+		}, async () => callOnError(1, error));
 	}
 	const shell = availableShells[shellName];
 	if (!shell) {
@@ -544,15 +548,16 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			if (available.length > 0) available.push(require_message.text(", "));
 			available.push(require_message.value(name));
 		}
-		stderr(require_message.formatMessage(require_message.message`Error: Unsupported shell ${shellName}. Available shells: ${available}.`, {
+		const error = require_message.message`Unsupported shell ${shellName}. Available shells: ${available}.`;
+		stderr(`Error: ${require_message.formatMessage(error, {
 			colors,
 			quotes: !colors
-		}));
+		})}`);
 		return require_mode_dispatch.dispatchByMode(parser.mode, () => {
-			const result = callOnError(1);
+			const result = callOnError(1, error);
 			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
 			return result;
-		}, async () => callOnError(1));
+		}, async () => callOnError(1, error));
 	}
 	if (args.length === 0) {
 		const completionArg = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
@@ -870,7 +875,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	const completionOptionConfig = norm(options.completion?.option);
 	const onCompletion = options.completion?.onShow ?? (() => ({}));
 	const onCompletionResult = (code) => onCompletion(code);
-	const onErrorResult = (code) => onError(code);
+	const onErrorResult = (code, error) => onError(code, error);
 	if (helpOptionConfig?.names) require_validate.validateOptionNames(helpOptionConfig.names, "Help option");
 	if (helpCommandConfig?.names) require_validate.validateCommandNames(helpCommandConfig.names, "Help command");
 	if (versionOptionConfig?.names) require_validate.validateOptionNames(versionOptionConfig.names, "Version option");
@@ -1022,7 +1027,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						quotes: !colors
 					});
 					stderr(`Error: ${errorMessage}`);
-					return onError(1);
+					return onError(1, validationError);
 				};
 				const displayHelp = (doc) => {
 					if (doc != null) {
@@ -1133,7 +1138,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						quotes: !colors
 					});
 					stderr(`Error: ${errorMessage}`);
-					return onError(1);
+					return onError(1, classified.error);
 				};
 				if (aboveError === "help") {
 					const parserForDoc = args.length < 1 ? augmentedParser : parser;

package/dist/facade.d.cts

@@ -240,14 +240,21 @@ interface RunOptions<THelp, TError> {
    */
   readonly aboveError?: "usage" | "help" | "none";
   /**
-   * Callback function invoked when parsing fails. The function can
-   * optionally receive an exit code parameter.
+   * Callback invoked after error output for a parse failure, an invalid
+   * command path before help, or a missing or unsupported completion shell.
+   * Receives the exit code and the structured error message used for output.
+   * The message does not include the runner's `Error: ` prefix or usage/help
+   * output.  The runner preserves any formatting terms in the original message.
+   *
+   * Handlers may ignore either argument.  Wrappers that invoke this callback
+   * themselves must forward both the exit code and the message.
    *
    * You usually want to pass `process.exit` on Node.js or Bun and `Deno.exit`
    * on Deno to this option.
    * @default Throws a {@link RunParserError}.
+   * @since 1.3.0 Added the `error` parameter.
    */
-  readonly onError?: (() => TError) | ((exitCode: number) => TError);
+  readonly onError?: (exitCode: number, error: Message) => TError;
   /**
    * Function used to output error messages.  Assumes it prints the ending
    * newline.

package/dist/facade.d.ts

@@ -240,14 +240,21 @@ interface RunOptions<THelp, TError> {
    */
   readonly aboveError?: "usage" | "help" | "none";
   /**
-   * Callback function invoked when parsing fails. The function can
-   * optionally receive an exit code parameter.
+   * Callback invoked after error output for a parse failure, an invalid
+   * command path before help, or a missing or unsupported completion shell.
+   * Receives the exit code and the structured error message used for output.
+   * The message does not include the runner's `Error: ` prefix or usage/help
+   * output.  The runner preserves any formatting terms in the original message.
+   *
+   * Handlers may ignore either argument.  Wrappers that invoke this callback
+   * themselves must forward both the exit code and the message.
    *
    * You usually want to pass `process.exit` on Node.js or Bun and `Deno.exit`
    * on Deno to this option.
    * @default Throws a {@link RunParserError}.
+   * @since 1.3.0 Added the `error` parameter.
    */
-  readonly onError?: (() => TError) | ((exitCode: number) => TError);
+  readonly onError?: (exitCode: number, error: Message) => TError;
   /**
    * Function used to output error messages.  Assumes it prints the ending
    * newline.

package/dist/facade.js

@@ -516,10 +516,14 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = []) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
-	const callOnError = (code) => onError(code);
+	const callOnError = (code, error) => onError(code, error);
 	const callOnCompletion = (code) => onCompletion(code);
 	if (!shellName) {
-		stderr("Error: Missing shell name for completion.\n");
+		const error = message`Missing shell name for completion.`;
+		stderr(`Error: ${formatMessage(error, {
+			colors,
+			quotes: !colors
+		})}\n`);
 		if (completionParser) {
 			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 			const doc = getDocPage(completionParser, [displayName]);
@@ -532,10 +536,10 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			}));
 		}
 		return dispatchByMode(parser.mode, () => {
-			const result = callOnError(1);
+			const result = callOnError(1, error);
 			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
 			return result;
-		}, async () => callOnError(1));
+		}, async () => callOnError(1, error));
 	}
 	const shell = availableShells[shellName];
 	if (!shell) {
@@ -544,15 +548,16 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			if (available.length > 0) available.push(text(", "));
 			available.push(value(name));
 		}
-		stderr(formatMessage(message`Error: Unsupported shell ${shellName}. Available shells: ${available}.`, {
+		const error = message`Unsupported shell ${shellName}. Available shells: ${available}.`;
+		stderr(`Error: ${formatMessage(error, {
 			colors,
 			quotes: !colors
-		}));
+		})}`);
 		return dispatchByMode(parser.mode, () => {
-			const result = callOnError(1);
+			const result = callOnError(1, error);
 			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
 			return result;
-		}, async () => callOnError(1));
+		}, async () => callOnError(1, error));
 	}
 	if (args.length === 0) {
 		const completionArg = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
@@ -870,7 +875,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	const completionOptionConfig = norm(options.completion?.option);
 	const onCompletion = options.completion?.onShow ?? (() => ({}));
 	const onCompletionResult = (code) => onCompletion(code);
-	const onErrorResult = (code) => onError(code);
+	const onErrorResult = (code, error) => onError(code, error);
 	if (helpOptionConfig?.names) validateOptionNames(helpOptionConfig.names, "Help option");
 	if (helpCommandConfig?.names) validateCommandNames(helpCommandConfig.names, "Help command");
 	if (versionOptionConfig?.names) validateOptionNames(versionOptionConfig.names, "Version option");
@@ -1022,7 +1027,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						quotes: !colors
 					});
 					stderr(`Error: ${errorMessage}`);
-					return onError(1);
+					return onError(1, validationError);
 				};
 				const displayHelp = (doc) => {
 					if (doc != null) {
@@ -1133,7 +1138,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						quotes: !colors
 					});
 					stderr(`Error: ${errorMessage}`);
-					return onError(1);
+					return onError(1, classified.error);
 				};
 				if (aboveError === "help") {
 					const parserForDoc = args.length < 1 ? augmentedParser : parser;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0-dev.2515",
+  "version": "1.3.0-dev.2521",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -221,7 +221,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.3.0-dev.2515+8ed62336",
+    "@optique/env": "1.3.0-dev.2521+47f58fcf",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -11,19 +11,19 @@ description: >
 license: MIT
 ---
 
-Optique is a type-safe combinatorial CLI parser. Use it by describing the CLI
-grammar with parsers and combinators, not by manually walking `argv`.
+Build CLI grammars by composing Optique parsers instead of walking `argv`.
 
-If web access is available, start from <https://optique.dev/llms.txt> for the
-maintained documentation index. Keep the rules below in mind even when offline;
-they cover the parts agents most often get wrong.
+If online, start at <https://optique.dev/llms.txt> for maintained docs. These
+rules also cover common pitfalls when offline.
 
 
 Core rules
 ----------
 
  -  Use `run()` from *@optique/run* for applications; use `parse()` or
-    `runParser()` for embedded and custom runtimes.
+    `runParser()` for embedded and custom runtimes. With `runParser()`,
+    `onError(exitCode, error)` receives a structured `Message` after stderr
+    output; use that argument instead of parsing rendered error text.
  -  In tests, use `parseArgs()`/`parseArgsSync()` from *@optique/testing/parser*
     for parser results, `captureRun()` from *@optique/testing/run* for runner
     output/exits, `captureProgramRun()` from *@optique/testing/discover* for