@optique/core 1.0.0-dev.1136 → 1.0.0-dev.1155

package/dist/completion.cjs

@@ -40,6 +40,9 @@ function validateProgramName(programName) {
 function encodePattern(pattern) {
 	return pattern.replace(/%/g, "%25").replace(/:/g, "%3A");
 }
+function encodeExtensions(extensions) {
+	return extensions?.map((ext) => ext.replace(/^\./, "")).join(",") ?? "";
+}
 /**
 * Replaces control characters that would corrupt shell completion protocols.
 * Shell completion formats use tabs as field delimiters and newlines as record
@@ -211,7 +214,7 @@ complete -F _${programName} -- ${programName}
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") yield `${suggestion.text}`;
 			else {
-				const extensions = suggestion.extensions?.join(",") || "";
+				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}`;
@@ -336,7 +339,7 @@ compdef _${programName.replace(/[^a-zA-Z0-9]/g, "_")} ${programName}
 			const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
 			yield `${suggestion.text}\0${description}\0`;
 		} else {
-			const extensions = suggestion.extensions?.join(",") || "";
+			const extensions = encodeExtensions(suggestion.extensions);
 			const hidden = suggestion.includeHidden ? "1" : "0";
 			const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
 			const pattern = encodePattern(suggestion.pattern ?? "");
@@ -508,7 +511,7 @@ complete -c ${programName} -f -a '(${functionName})'
 				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
 				yield `${suggestion.text}\t${description}`;
 			} else {
-				const extensions = suggestion.extensions?.join(",") || "";
+				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
@@ -756,7 +759,7 @@ ${functionName}-external
 				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
 				yield `${suggestion.text}\t${description}`;
 			} else {
-				const extensions = suggestion.extensions?.join(",") || "";
+				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
@@ -926,7 +929,7 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
 				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
 				yield `${suggestion.text}\t${suggestion.text}\t${description}`;
 			} else {
-				const extensions = suggestion.extensions?.join(",") || "";
+				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");

package/dist/completion.js

@@ -40,6 +40,9 @@ function validateProgramName(programName) {
 function encodePattern(pattern) {
 	return pattern.replace(/%/g, "%25").replace(/:/g, "%3A");
 }
+function encodeExtensions(extensions) {
+	return extensions?.map((ext) => ext.replace(/^\./, "")).join(",") ?? "";
+}
 /**
 * Replaces control characters that would corrupt shell completion protocols.
 * Shell completion formats use tabs as field delimiters and newlines as record
@@ -211,7 +214,7 @@ complete -F _${programName} -- ${programName}
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") yield `${suggestion.text}`;
 			else {
-				const extensions = suggestion.extensions?.join(",") || "";
+				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}`;
@@ -336,7 +339,7 @@ compdef _${programName.replace(/[^a-zA-Z0-9]/g, "_")} ${programName}
 			const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
 			yield `${suggestion.text}\0${description}\0`;
 		} else {
-			const extensions = suggestion.extensions?.join(",") || "";
+			const extensions = encodeExtensions(suggestion.extensions);
 			const hidden = suggestion.includeHidden ? "1" : "0";
 			const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
 			const pattern = encodePattern(suggestion.pattern ?? "");
@@ -508,7 +511,7 @@ complete -c ${programName} -f -a '(${functionName})'
 				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
 				yield `${suggestion.text}\t${description}`;
 			} else {
-				const extensions = suggestion.extensions?.join(",") || "";
+				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
@@ -756,7 +759,7 @@ ${functionName}-external
 				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
 				yield `${suggestion.text}\t${description}`;
 			} else {
-				const extensions = suggestion.extensions?.join(",") || "";
+				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
@@ -926,7 +929,7 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
 				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
 				yield `${suggestion.text}\t${suggestion.text}\t${description}`;
 			} else {
-				const extensions = suggestion.extensions?.join(",") || "";
+				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");

package/dist/facade.cjs

@@ -727,6 +727,61 @@ function validateVersionValue(value$1) {
 	if (/[\x00-\x1f\x7f]/.test(value$1)) throw new TypeError("Version value must not contain control characters.");
 	return value$1;
 }
+/**
+* Escapes control characters in a string for display in error messages.
+*
+* @param value The string to escape.
+* @returns The escaped string with control characters replaced by escape
+*          sequences.
+*/
+function escapeControlChars(value$1) {
+	return value$1.replace(/[\x00-\x1f\x7f]/g, (ch) => {
+		const code = ch.charCodeAt(0);
+		switch (code) {
+			case 9: return "\\t";
+			case 10: return "\\n";
+			case 13: return "\\r";
+			default: return `\\x${code.toString(16).padStart(2, "0")}`;
+		}
+	});
+}
+/**
+* Validates meta option names at runtime.
+*
+* @param names The option names to validate.
+* @param label A human-readable label for error messages (e.g.,
+*              `"Help option"`).
+* @throws {TypeError} If the names array is empty, or any name is empty,
+*         lacks a valid prefix, or contains whitespace or control characters.
+*/
+function validateOptionNames(names, label) {
+	if (names.length === 0) throw new TypeError(`Expected at least one ${label.toLowerCase()} name.`);
+	for (const name of names) {
+		if (name === "") throw new TypeError(`${label} name must not be empty.`);
+		if (/^\s+$/.test(name)) throw new TypeError(`${label} name must not be whitespace-only: "${escapeControlChars(name)}".`);
+		if (/[\x00-\x1f\x7f]/.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
+		if (/\s/.test(name)) throw new TypeError(`${label} name must not contain whitespace: "${escapeControlChars(name)}".`);
+		if (!/^(--|[-/+])/.test(name)) throw new TypeError(`${label} name must start with "--", "-", "/", or "+": "${name}".`);
+	}
+}
+/**
+* Validates meta command names at runtime.
+*
+* @param names The command names to validate.
+* @param label A human-readable label for error messages (e.g.,
+*              `"Help command"`).
+* @throws {TypeError} If the names array is empty, or any name is empty,
+*         whitespace-only, or contains whitespace or control characters.
+*/
+function validateCommandNames(names, label) {
+	if (names.length === 0) throw new TypeError(`Expected at least one ${label.toLowerCase()} name.`);
+	for (const name of names) {
+		if (name === "") throw new TypeError(`${label} name must not be empty.`);
+		if (/^\s+$/.test(name)) throw new TypeError(`${label} name must not be whitespace-only: "${escapeControlChars(name)}".`);
+		if (/[\x00-\x1f\x7f]/.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
+		if (/\s/.test(name)) throw new TypeError(`${label} name must not contain whitespace: "${escapeControlChars(name)}".`);
+	}
+}
 function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsParam) {
 	const isProgram = typeof programNameOrArgs !== "string";
 	let parser;
@@ -770,6 +825,12 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	const onCompletion = options.completion?.onShow ?? (() => ({}));
 	const onCompletionResult = (code) => onCompletion(code);
 	const onErrorResult = (code) => onError(code);
+	if (helpOptionConfig?.names) validateOptionNames(helpOptionConfig.names, "Help option");
+	if (helpCommandConfig?.names) validateCommandNames(helpCommandConfig.names, "Help command");
+	if (versionOptionConfig?.names) validateOptionNames(versionOptionConfig.names, "Version option");
+	if (versionCommandConfig?.names) validateCommandNames(versionCommandConfig.names, "Version command");
+	if (completionOptionConfig?.names) validateOptionNames(completionOptionConfig.names, "Completion option");
+	if (completionCommandConfig?.names) validateCommandNames(completionCommandConfig.names, "Completion command");
 	const helpOptionNames = helpOptionConfig?.names ?? ["--help"];
 	const helpCommandNames = helpCommandConfig?.names ?? ["help"];
 	const versionOptionNames = versionOptionConfig?.names ?? ["--version"];

package/dist/facade.d.cts

@@ -273,7 +273,10 @@ interface RunOptions<THelp, TError> {
  * @returns The parsed result value, or the return value of `onHelp`/`onError`
  *          callbacks.
  * @throws {TypeError} If `options.version.value` is not a non-empty string
- *          without ASCII control characters.
+ *          without ASCII control characters, or if any meta command/option
+ *          name is empty, whitespace-only, contains whitespace or control
+ *          characters, or (for option names) lacks a valid prefix (`--`,
+ *          `-`, `/`, or `+`).
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
  * @since 0.10.0 Added support for {@link Program} objects.

package/dist/facade.d.ts

@@ -273,7 +273,10 @@ interface RunOptions<THelp, TError> {
  * @returns The parsed result value, or the return value of `onHelp`/`onError`
  *          callbacks.
  * @throws {TypeError} If `options.version.value` is not a non-empty string
- *          without ASCII control characters.
+ *          without ASCII control characters, or if any meta command/option
+ *          name is empty, whitespace-only, contains whitespace or control
+ *          characters, or (for option names) lacks a valid prefix (`--`,
+ *          `-`, `/`, or `+`).
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
  * @since 0.10.0 Added support for {@link Program} objects.

package/dist/facade.js

@@ -727,6 +727,61 @@ function validateVersionValue(value$1) {
 	if (/[\x00-\x1f\x7f]/.test(value$1)) throw new TypeError("Version value must not contain control characters.");
 	return value$1;
 }
+/**
+* Escapes control characters in a string for display in error messages.
+*
+* @param value The string to escape.
+* @returns The escaped string with control characters replaced by escape
+*          sequences.
+*/
+function escapeControlChars(value$1) {
+	return value$1.replace(/[\x00-\x1f\x7f]/g, (ch) => {
+		const code = ch.charCodeAt(0);
+		switch (code) {
+			case 9: return "\\t";
+			case 10: return "\\n";
+			case 13: return "\\r";
+			default: return `\\x${code.toString(16).padStart(2, "0")}`;
+		}
+	});
+}
+/**
+* Validates meta option names at runtime.
+*
+* @param names The option names to validate.
+* @param label A human-readable label for error messages (e.g.,
+*              `"Help option"`).
+* @throws {TypeError} If the names array is empty, or any name is empty,
+*         lacks a valid prefix, or contains whitespace or control characters.
+*/
+function validateOptionNames(names, label) {
+	if (names.length === 0) throw new TypeError(`Expected at least one ${label.toLowerCase()} name.`);
+	for (const name of names) {
+		if (name === "") throw new TypeError(`${label} name must not be empty.`);
+		if (/^\s+$/.test(name)) throw new TypeError(`${label} name must not be whitespace-only: "${escapeControlChars(name)}".`);
+		if (/[\x00-\x1f\x7f]/.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
+		if (/\s/.test(name)) throw new TypeError(`${label} name must not contain whitespace: "${escapeControlChars(name)}".`);
+		if (!/^(--|[-/+])/.test(name)) throw new TypeError(`${label} name must start with "--", "-", "/", or "+": "${name}".`);
+	}
+}
+/**
+* Validates meta command names at runtime.
+*
+* @param names The command names to validate.
+* @param label A human-readable label for error messages (e.g.,
+*              `"Help command"`).
+* @throws {TypeError} If the names array is empty, or any name is empty,
+*         whitespace-only, or contains whitespace or control characters.
+*/
+function validateCommandNames(names, label) {
+	if (names.length === 0) throw new TypeError(`Expected at least one ${label.toLowerCase()} name.`);
+	for (const name of names) {
+		if (name === "") throw new TypeError(`${label} name must not be empty.`);
+		if (/^\s+$/.test(name)) throw new TypeError(`${label} name must not be whitespace-only: "${escapeControlChars(name)}".`);
+		if (/[\x00-\x1f\x7f]/.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
+		if (/\s/.test(name)) throw new TypeError(`${label} name must not contain whitespace: "${escapeControlChars(name)}".`);
+	}
+}
 function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsParam) {
 	const isProgram = typeof programNameOrArgs !== "string";
 	let parser;
@@ -770,6 +825,12 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	const onCompletion = options.completion?.onShow ?? (() => ({}));
 	const onCompletionResult = (code) => onCompletion(code);
 	const onErrorResult = (code) => onError(code);
+	if (helpOptionConfig?.names) validateOptionNames(helpOptionConfig.names, "Help option");
+	if (helpCommandConfig?.names) validateCommandNames(helpCommandConfig.names, "Help command");
+	if (versionOptionConfig?.names) validateOptionNames(versionOptionConfig.names, "Version option");
+	if (versionCommandConfig?.names) validateCommandNames(versionCommandConfig.names, "Version command");
+	if (completionOptionConfig?.names) validateOptionNames(completionOptionConfig.names, "Completion option");
+	if (completionCommandConfig?.names) validateCommandNames(completionCommandConfig.names, "Completion command");
 	const helpOptionNames = helpOptionConfig?.names ?? ["--help"];
 	const helpCommandNames = helpCommandConfig?.names ?? ["help"];
 	const versionOptionNames = versionOptionConfig?.names ?? ["--version"];

package/dist/valueparser.cjs

@@ -453,10 +453,28 @@ function float(options = {}) {
 * object.
 * @param options Configuration options for the URL parser.
 * @returns A {@link ValueParser} that converts string input to `URL` objects.
+* @throws {TypeError} If any `allowedProtocols` entry is not a valid protocol
+*   string ending with a colon (e.g., `"https:"`).
 */
 function url(options = {}) {
-	const originalProtocols = options.allowedProtocols != null ? Object.freeze([...options.allowedProtocols]) : void 0;
-	const allowedProtocols = options.allowedProtocols != null ? Object.freeze(options.allowedProtocols.map((p) => p.toLowerCase())) : void 0;
+	const originalProtocolsList = [];
+	const normalizedProtocolsList = [];
+	if (options.allowedProtocols != null) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const protocol of options.allowedProtocols) {
+			if (typeof protocol !== "string" || !/^[a-z][a-z0-9+\-.]*:$/i.test(protocol)) {
+				const rendered = typeof protocol === "string" ? JSON.stringify(protocol) : String(protocol);
+				throw new TypeError(`Each allowed protocol must be a valid protocol ending with a colon (e.g., "https:"), got: ${rendered}.`);
+			}
+			const normalized = protocol.toLowerCase();
+			if (seen.has(normalized)) continue;
+			seen.add(normalized);
+			originalProtocolsList.push(protocol);
+			normalizedProtocolsList.push(normalized);
+		}
+	}
+	const originalProtocols = options.allowedProtocols != null ? Object.freeze(originalProtocolsList) : void 0;
+	const allowedProtocols = options.allowedProtocols != null ? Object.freeze(normalizedProtocolsList) : void 0;
 	const metavar = options.metavar ?? "URL";
 	require_nonempty.ensureNonEmptyString(metavar);
 	const invalidUrl = options.errors?.invalidUrl;

package/dist/valueparser.d.cts

@@ -491,6 +491,8 @@ interface UrlOptions {
  * object.
  * @param options Configuration options for the URL parser.
  * @returns A {@link ValueParser} that converts string input to `URL` objects.
+ * @throws {TypeError} If any `allowedProtocols` entry is not a valid protocol
+ *   string ending with a colon (e.g., `"https:"`).
  */
 declare function url(options?: UrlOptions): ValueParser<"sync", URL>;
 /**

package/dist/valueparser.d.ts

@@ -491,6 +491,8 @@ interface UrlOptions {
  * object.
  * @param options Configuration options for the URL parser.
  * @returns A {@link ValueParser} that converts string input to `URL` objects.
+ * @throws {TypeError} If any `allowedProtocols` entry is not a valid protocol
+ *   string ending with a colon (e.g., `"https:"`).
  */
 declare function url(options?: UrlOptions): ValueParser<"sync", URL>;
 /**

package/dist/valueparser.js

@@ -453,10 +453,28 @@ function float(options = {}) {
 * object.
 * @param options Configuration options for the URL parser.
 * @returns A {@link ValueParser} that converts string input to `URL` objects.
+* @throws {TypeError} If any `allowedProtocols` entry is not a valid protocol
+*   string ending with a colon (e.g., `"https:"`).
 */
 function url(options = {}) {
-	const originalProtocols = options.allowedProtocols != null ? Object.freeze([...options.allowedProtocols]) : void 0;
-	const allowedProtocols = options.allowedProtocols != null ? Object.freeze(options.allowedProtocols.map((p) => p.toLowerCase())) : void 0;
+	const originalProtocolsList = [];
+	const normalizedProtocolsList = [];
+	if (options.allowedProtocols != null) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const protocol of options.allowedProtocols) {
+			if (typeof protocol !== "string" || !/^[a-z][a-z0-9+\-.]*:$/i.test(protocol)) {
+				const rendered = typeof protocol === "string" ? JSON.stringify(protocol) : String(protocol);
+				throw new TypeError(`Each allowed protocol must be a valid protocol ending with a colon (e.g., "https:"), got: ${rendered}.`);
+			}
+			const normalized = protocol.toLowerCase();
+			if (seen.has(normalized)) continue;
+			seen.add(normalized);
+			originalProtocolsList.push(protocol);
+			normalizedProtocolsList.push(normalized);
+		}
+	}
+	const originalProtocols = options.allowedProtocols != null ? Object.freeze(originalProtocolsList) : void 0;
+	const allowedProtocols = options.allowedProtocols != null ? Object.freeze(normalizedProtocolsList) : void 0;
 	const metavar = options.metavar ?? "URL";
 	ensureNonEmptyString(metavar);
 	const invalidUrl = options.errors?.invalidUrl;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1136+00dc9aa5",
+  "version": "1.0.0-dev.1155+7532f28d",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",