@optique/core 1.4.0-dev.2606 → 1.4.0-dev.2608

package/dist/facade.cjs

@@ -517,7 +517,7 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = [], messageFormatter, theme, automaticWidth = false) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = [], messageFormatter, theme, automaticWidth = false, errors) {
 	const errorOptions = (format) => automaticWidth ? require_terminal_width.withAutomaticWidth(format, (width) => {
 		maxWidth = width;
 	}) : format;
@@ -526,7 +526,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 	const callOnError = (code, error) => onError(code, error);
 	const callOnCompletion = (code) => onCompletion(code);
 	if (!shellName) {
-		const error = require_message.message`Missing shell name for completion.`;
+		const error = errors?.missingShell ?? require_message.message`Missing shell name for completion.`;
 		const writeError = () => stderr(require_message_renderer.renderErrorMessage(error, errorOptions({
 			messageFormatter,
 			theme,
@@ -568,7 +568,8 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			if (available.length > 0) available.push(require_message.text(", "));
 			available.push(require_message.value(name));
 		}
-		const error = require_message.message`Unsupported shell ${shellName}. Available shells: ${available}.`;
+		const unsupportedShell = errors?.unsupportedShell;
+		const error = typeof unsupportedShell === "function" ? unsupportedShell(shellName, Object.keys(availableShells)) : unsupportedShell ?? require_message.message`Unsupported shell ${shellName}. Available shells: ${available}.`;
 		stderr(require_message_renderer.renderErrorMessage(error, errorOptions({
 			messageFormatter,
 			theme,
@@ -1037,7 +1038,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				classified.shell,
 				...classified.commandPath ?? [],
 				...classified.args
-			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, termWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions, messageFormatter, theme, automaticWidth);
+			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, termWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions, messageFormatter, theme, automaticWidth, options.completion?.errors);
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;

package/dist/facade.d.cts

@@ -243,6 +243,24 @@ interface RunOptions<THelp, TError> {
      * @default `{ bash, fish, nu, pwsh, zsh }`
      */
     readonly shells?: Record<string, ShellCompletion>;
+    /**
+     * Custom messages for completion shell errors.  Unspecified errors use
+     * the default messages.
+     * @since 1.4.0
+     */
+    readonly errors?: {
+      /**
+       * Message shown when no shell name is provided.
+       * @since 1.4.0
+       */
+      readonly missingShell?: Message;
+      /**
+       * Message shown for an unsupported shell.  A callback receives the
+       * shell name and the available shell names, including custom shells.
+       * @since 1.4.0
+       */
+      readonly unsupportedShell?: Message | ((shell: string, availableShells: readonly string[]) => Message);
+    };
     /** Callback invoked when completion is requested. */
     readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
   } & ({
@@ -265,6 +283,7 @@ interface RunOptions<THelp, TError> {
    * 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.
+   * Completion errors use `completion.errors` overrides when configured.
    * The message does not include the runner's `Error: ` prefix or usage/help
    * output.  The runner preserves any formatting terms in the original message.
    *

package/dist/facade.d.ts

@@ -243,6 +243,24 @@ interface RunOptions<THelp, TError> {
      * @default `{ bash, fish, nu, pwsh, zsh }`
      */
     readonly shells?: Record<string, ShellCompletion>;
+    /**
+     * Custom messages for completion shell errors.  Unspecified errors use
+     * the default messages.
+     * @since 1.4.0
+     */
+    readonly errors?: {
+      /**
+       * Message shown when no shell name is provided.
+       * @since 1.4.0
+       */
+      readonly missingShell?: Message;
+      /**
+       * Message shown for an unsupported shell.  A callback receives the
+       * shell name and the available shell names, including custom shells.
+       * @since 1.4.0
+       */
+      readonly unsupportedShell?: Message | ((shell: string, availableShells: readonly string[]) => Message);
+    };
     /** Callback invoked when completion is requested. */
     readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
   } & ({
@@ -265,6 +283,7 @@ interface RunOptions<THelp, TError> {
    * 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.
+   * Completion errors use `completion.errors` overrides when configured.
    * The message does not include the runner's `Error: ` prefix or usage/help
    * output.  The runner preserves any formatting terms in the original message.
    *

package/dist/facade.js

@@ -517,7 +517,7 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = [], messageFormatter, theme, automaticWidth = false) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = [], messageFormatter, theme, automaticWidth = false, errors) {
 	const errorOptions = (format) => automaticWidth ? withAutomaticWidth(format, (width) => {
 		maxWidth = width;
 	}) : format;
@@ -526,7 +526,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 	const callOnError = (code, error) => onError(code, error);
 	const callOnCompletion = (code) => onCompletion(code);
 	if (!shellName) {
-		const error = message`Missing shell name for completion.`;
+		const error = errors?.missingShell ?? message`Missing shell name for completion.`;
 		const writeError = () => stderr(renderErrorMessage(error, errorOptions({
 			messageFormatter,
 			theme,
@@ -568,7 +568,8 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			if (available.length > 0) available.push(text(", "));
 			available.push(value(name));
 		}
-		const error = message`Unsupported shell ${shellName}. Available shells: ${available}.`;
+		const unsupportedShell = errors?.unsupportedShell;
+		const error = typeof unsupportedShell === "function" ? unsupportedShell(shellName, Object.keys(availableShells)) : unsupportedShell ?? message`Unsupported shell ${shellName}. Available shells: ${available}.`;
 		stderr(renderErrorMessage(error, errorOptions({
 			messageFormatter,
 			theme,
@@ -1037,7 +1038,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				classified.shell,
 				...classified.commandPath ?? [],
 				...classified.args
-			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, termWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions, messageFormatter, theme, automaticWidth);
+			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, termWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions, messageFormatter, theme, automaticWidth, options.completion?.errors);
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;

package/package.json

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

package/skills/optique/SKILL.md

@@ -77,8 +77,8 @@ Core rules
  -  Build subcommands with `command()` combined by `or()`. Put a literal field
     such as `command: constant("serve")` in each branch when you want a
     discriminated union.
- -  Enable completion through `run(parser, { completion: "both" })` for CLI
-    apps. Do not hand-write completion scripts from parser metadata.
+ -  Use `run(parser, { completion: "both" })` for completion, or the object form
+    with `completion.errors` for custom shell errors. Do not hand-write scripts.
  -  Use `usageLine: [{ type: "ellipsis" }]` in runner options when a large root
     synopsis should become a compact `Usage: myapp ...` line. This applies only
     to root full help; use `command()`'s `usageLine` for subcommand help.