@optique/core 1.0.0-dev.1109 → 1.0.0-dev.1122

package/dist/completion.cjs

@@ -41,6 +41,17 @@ function encodePattern(pattern) {
 	return pattern.replace(/%/g, "%25").replace(/:/g, "%3A");
 }
 /**
+* Replaces control characters that would corrupt shell completion protocols.
+* Shell completion formats use tabs as field delimiters and newlines as record
+* delimiters.  Null bytes are used as delimiters in zsh's format.
+* @param description The description string to sanitize.
+* @returns The sanitized description with control characters replaced by spaces.
+* @internal
+*/
+function sanitizeDescription(description) {
+	return description.replace(/[\t\n\r\0]/g, " ");
+}
+/**
 * The Bash shell completion generator.
 * @since 0.6.0
 */
@@ -250,6 +261,12 @@ function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
         pattern="\${pattern//%3A/:}"; pattern="\${pattern//%25/%}"
         has_file_completion=1
 
+        # Enable glob_dots when hidden files are requested so that
+        # _files and _directories include dot-prefixed entries
+        local __was_glob_dots=0
+        [[ -o glob_dots ]] && __was_glob_dots=1
+        if [[ "\$hidden" == "1" ]]; then setopt glob_dots; fi
+
         # Use zsh's native file completion
         case "\$type" in
           file)
@@ -275,8 +292,8 @@ function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
             ;;
         esac
 
-        # Note: zsh's _files and _directories handle hidden file filtering automatically
-        # based on the completion context and user settings
+        # Restore glob_dots to its previous state
+        if [[ "\$__was_glob_dots" == "1" ]]; then setopt glob_dots; else unsetopt glob_dots; fi
       else
         # Regular literal completion
         if [[ -n "\$value" ]]; then
@@ -308,12 +325,12 @@ compdef _${programName.replace(/[^a-zA-Z0-9]/g, "_")} ${programName}
 	},
 	*encodeSuggestions(suggestions) {
 		for (const suggestion of suggestions) if (suggestion.kind === "literal") {
-			const description = suggestion.description == null ? "" : require_message.formatMessage(suggestion.description, { colors: false });
+			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 hidden = suggestion.includeHidden ? "1" : "0";
-			const description = suggestion.description == null ? "" : require_message.formatMessage(suggestion.description, { colors: false });
+			const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
 			const pattern = encodePattern(suggestion.pattern ?? "");
 			yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\0${description}\0`;
 		}
@@ -476,12 +493,12 @@ complete -c ${programName} -f -a '(${functionName})'
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : require_message.formatMessage(suggestion.description, { colors: false });
+				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 hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : require_message.formatMessage(suggestion.description, { colors: false });
+				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
 			}
@@ -720,12 +737,12 @@ ${functionName}-external
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : require_message.formatMessage(suggestion.description, { colors: false });
+				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 hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : require_message.formatMessage(suggestion.description, { colors: false });
+				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
 			}
@@ -890,12 +907,12 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : require_message.formatMessage(suggestion.description, { colors: false });
+				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 hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : require_message.formatMessage(suggestion.description, { colors: false });
+				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t[file]\t${description}`;
 			}

package/dist/completion.js

@@ -41,6 +41,17 @@ function encodePattern(pattern) {
 	return pattern.replace(/%/g, "%25").replace(/:/g, "%3A");
 }
 /**
+* Replaces control characters that would corrupt shell completion protocols.
+* Shell completion formats use tabs as field delimiters and newlines as record
+* delimiters.  Null bytes are used as delimiters in zsh's format.
+* @param description The description string to sanitize.
+* @returns The sanitized description with control characters replaced by spaces.
+* @internal
+*/
+function sanitizeDescription(description) {
+	return description.replace(/[\t\n\r\0]/g, " ");
+}
+/**
 * The Bash shell completion generator.
 * @since 0.6.0
 */
@@ -250,6 +261,12 @@ function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
         pattern="\${pattern//%3A/:}"; pattern="\${pattern//%25/%}"
         has_file_completion=1
 
+        # Enable glob_dots when hidden files are requested so that
+        # _files and _directories include dot-prefixed entries
+        local __was_glob_dots=0
+        [[ -o glob_dots ]] && __was_glob_dots=1
+        if [[ "\$hidden" == "1" ]]; then setopt glob_dots; fi
+
         # Use zsh's native file completion
         case "\$type" in
           file)
@@ -275,8 +292,8 @@ function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
             ;;
         esac
 
-        # Note: zsh's _files and _directories handle hidden file filtering automatically
-        # based on the completion context and user settings
+        # Restore glob_dots to its previous state
+        if [[ "\$__was_glob_dots" == "1" ]]; then setopt glob_dots; else unsetopt glob_dots; fi
       else
         # Regular literal completion
         if [[ -n "\$value" ]]; then
@@ -308,12 +325,12 @@ compdef _${programName.replace(/[^a-zA-Z0-9]/g, "_")} ${programName}
 	},
 	*encodeSuggestions(suggestions) {
 		for (const suggestion of suggestions) if (suggestion.kind === "literal") {
-			const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
+			const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
 			yield `${suggestion.text}\0${description}\0`;
 		} else {
 			const extensions = suggestion.extensions?.join(",") || "";
 			const hidden = suggestion.includeHidden ? "1" : "0";
-			const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
+			const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
 			const pattern = encodePattern(suggestion.pattern ?? "");
 			yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\0${description}\0`;
 		}
@@ -476,12 +493,12 @@ complete -c ${programName} -f -a '(${functionName})'
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
+				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
 				yield `${suggestion.text}\t${description}`;
 			} else {
 				const extensions = suggestion.extensions?.join(",") || "";
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
+				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
 			}
@@ -720,12 +737,12 @@ ${functionName}-external
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
+				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
 				yield `${suggestion.text}\t${description}`;
 			} else {
 				const extensions = suggestion.extensions?.join(",") || "";
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
+				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
 			}
@@ -890,12 +907,12 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
+				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 hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
+				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t[file]\t${description}`;
 			}

package/dist/valueparser.cjs

@@ -1832,6 +1832,9 @@ function macAddress(options) {
 * @returns A parser that accepts valid domain names as strings.
 * @throws {RangeError} If `maxLength` is not a positive integer.
 * @throws {RangeError} If `minLabels` is not a positive integer.
+* @throws {TypeError} If any `allowedTlds` entry is not a string, is empty,
+*   contains dots, has leading/trailing whitespace, or is not a valid DNS
+*   label.
 * @throws {TypeError} If `allowSubdomains` is `false` and `minLabels` is
 *   greater than 2, since non-subdomain domains have exactly 2 labels.
 *
@@ -1847,7 +1850,7 @@ function macAddress(options) {
 * option("--root", domain({ allowSubdomains: false }))
 *
 * // Restrict to specific TLDs
-* option("--domain", domain({ allowedTLDs: ["com", "org", "net"] }))
+* option("--domain", domain({ allowedTlds: ["com", "org", "net"] }))
 *
 * // Normalize to lowercase
 * option("--domain", domain({ lowercase: true }))
@@ -1858,7 +1861,19 @@ function macAddress(options) {
 function domain(options) {
 	const metavar = options?.metavar ?? "DOMAIN";
 	const allowSubdomains = options?.allowSubdomains ?? true;
-	const allowedTLDs = options?.allowedTLDs != null ? Object.freeze([...options.allowedTLDs]) : void 0;
+	const allowedTlds = options?.allowedTlds != null ? Object.freeze([...options.allowedTlds]) : void 0;
+	const labelRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/;
+	if (allowedTlds !== void 0) for (const [i, tld] of allowedTlds.entries()) {
+		if (typeof tld !== "string") {
+			const actualType = Array.isArray(tld) ? "array" : typeof tld;
+			throw new TypeError(`allowedTlds[${i}] must be a string, but got ${actualType}.`);
+		}
+		if (tld.length === 0) throw new TypeError(`allowedTlds[${i}] must not be an empty string.`);
+		if (tld.includes(".")) throw new TypeError(`allowedTlds[${i}] must not contain dots: ${JSON.stringify(tld)}.`);
+		if (tld !== tld.trim()) throw new TypeError(`allowedTlds[${i}] must not have leading or trailing whitespace: ${JSON.stringify(tld)}.`);
+		if (!labelRegex.test(tld)) throw new TypeError(`allowedTlds[${i}] is not a valid DNS label: ${JSON.stringify(tld)}.`);
+	}
+	const allowedTldsLower = allowedTlds != null ? Object.freeze(allowedTlds.map((t) => t.toLowerCase())) : void 0;
 	const minLabels = options?.minLabels ?? 2;
 	const maxLength = options?.maxLength ?? 253;
 	const lowercase = options?.lowercase ?? false;
@@ -1870,7 +1885,6 @@ function domain(options) {
 	const tooFewLabels = options?.errors?.tooFewLabels;
 	const subdomainsNotAllowed = options?.errors?.subdomainsNotAllowed;
 	const tldNotAllowed = options?.errors?.tldNotAllowed;
-	const labelRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/;
 	return {
 		$mode: "sync",
 		metavar,
@@ -2034,15 +2048,14 @@ function domain(options) {
 					error: msg
 				};
 			}
-			if (allowedTLDs !== void 0) {
+			if (allowedTlds !== void 0 && allowedTldsLower !== void 0) {
 				const tld = labels[labels.length - 1];
 				const tldLower = tld.toLowerCase();
-				const allowedTLDsLower = allowedTLDs.map((t) => t.toLowerCase());
-				if (!allowedTLDsLower.includes(tldLower)) {
+				if (!allowedTldsLower.includes(tldLower)) {
 					const errorMsg = tldNotAllowed;
 					if (typeof errorMsg === "function") return {
 						success: false,
-						error: errorMsg(tld, allowedTLDs)
+						error: errorMsg(tld, allowedTlds)
 					};
 					const msg = errorMsg ?? [
 						{
@@ -2055,7 +2068,7 @@ function domain(options) {
 						},
 						{
 							type: "text",
-							text: ` is not allowed. Allowed TLDs: ${allowedTLDs.join(", ")}.`
+							text: ` is not allowed. Allowed TLDs: ${allowedTlds.join(", ")}.`
 						}
 					];
 					return {

package/dist/valueparser.d.cts

@@ -1479,7 +1479,7 @@ interface DomainOptions {
    * List of allowed top-level domains (e.g., ["com", "org", "net"]).
    * If specified, only domains with these TLDs are accepted.
    */
-  readonly allowedTLDs?: readonly string[];
+  readonly allowedTlds?: readonly string[];
   /**
    * Minimum number of domain labels (parts separated by dots).
    *
@@ -1517,7 +1517,7 @@ interface DomainOptions {
      * Can be a static message or a function that receives the TLD
      * and allowed TLDs.
      */
-    tldNotAllowed?: Message | ((tld: string, allowedTLDs: readonly string[]) => Message);
+    tldNotAllowed?: Message | ((tld: string, allowedTlds: readonly string[]) => Message);
     /**
      * Custom error message when domain has too few labels.
      * Can be a static message or a function that receives the domain
@@ -1544,6 +1544,9 @@ interface DomainOptions {
  * @returns A parser that accepts valid domain names as strings.
  * @throws {RangeError} If `maxLength` is not a positive integer.
  * @throws {RangeError} If `minLabels` is not a positive integer.
+ * @throws {TypeError} If any `allowedTlds` entry is not a string, is empty,
+ *   contains dots, has leading/trailing whitespace, or is not a valid DNS
+ *   label.
  * @throws {TypeError} If `allowSubdomains` is `false` and `minLabels` is
  *   greater than 2, since non-subdomain domains have exactly 2 labels.
  *
@@ -1559,7 +1562,7 @@ interface DomainOptions {
  * option("--root", domain({ allowSubdomains: false }))
  *
  * // Restrict to specific TLDs
- * option("--domain", domain({ allowedTLDs: ["com", "org", "net"] }))
+ * option("--domain", domain({ allowedTlds: ["com", "org", "net"] }))
  *
  * // Normalize to lowercase
  * option("--domain", domain({ lowercase: true }))

package/dist/valueparser.d.ts

@@ -1479,7 +1479,7 @@ interface DomainOptions {
    * List of allowed top-level domains (e.g., ["com", "org", "net"]).
    * If specified, only domains with these TLDs are accepted.
    */
-  readonly allowedTLDs?: readonly string[];
+  readonly allowedTlds?: readonly string[];
   /**
    * Minimum number of domain labels (parts separated by dots).
    *
@@ -1517,7 +1517,7 @@ interface DomainOptions {
      * Can be a static message or a function that receives the TLD
      * and allowed TLDs.
      */
-    tldNotAllowed?: Message | ((tld: string, allowedTLDs: readonly string[]) => Message);
+    tldNotAllowed?: Message | ((tld: string, allowedTlds: readonly string[]) => Message);
     /**
      * Custom error message when domain has too few labels.
      * Can be a static message or a function that receives the domain
@@ -1544,6 +1544,9 @@ interface DomainOptions {
  * @returns A parser that accepts valid domain names as strings.
  * @throws {RangeError} If `maxLength` is not a positive integer.
  * @throws {RangeError} If `minLabels` is not a positive integer.
+ * @throws {TypeError} If any `allowedTlds` entry is not a string, is empty,
+ *   contains dots, has leading/trailing whitespace, or is not a valid DNS
+ *   label.
  * @throws {TypeError} If `allowSubdomains` is `false` and `minLabels` is
  *   greater than 2, since non-subdomain domains have exactly 2 labels.
  *
@@ -1559,7 +1562,7 @@ interface DomainOptions {
  * option("--root", domain({ allowSubdomains: false }))
  *
  * // Restrict to specific TLDs
- * option("--domain", domain({ allowedTLDs: ["com", "org", "net"] }))
+ * option("--domain", domain({ allowedTlds: ["com", "org", "net"] }))
  *
  * // Normalize to lowercase
  * option("--domain", domain({ lowercase: true }))

package/dist/valueparser.js

@@ -1832,6 +1832,9 @@ function macAddress(options) {
 * @returns A parser that accepts valid domain names as strings.
 * @throws {RangeError} If `maxLength` is not a positive integer.
 * @throws {RangeError} If `minLabels` is not a positive integer.
+* @throws {TypeError} If any `allowedTlds` entry is not a string, is empty,
+*   contains dots, has leading/trailing whitespace, or is not a valid DNS
+*   label.
 * @throws {TypeError} If `allowSubdomains` is `false` and `minLabels` is
 *   greater than 2, since non-subdomain domains have exactly 2 labels.
 *
@@ -1847,7 +1850,7 @@ function macAddress(options) {
 * option("--root", domain({ allowSubdomains: false }))
 *
 * // Restrict to specific TLDs
-* option("--domain", domain({ allowedTLDs: ["com", "org", "net"] }))
+* option("--domain", domain({ allowedTlds: ["com", "org", "net"] }))
 *
 * // Normalize to lowercase
 * option("--domain", domain({ lowercase: true }))
@@ -1858,7 +1861,19 @@ function macAddress(options) {
 function domain(options) {
 	const metavar = options?.metavar ?? "DOMAIN";
 	const allowSubdomains = options?.allowSubdomains ?? true;
-	const allowedTLDs = options?.allowedTLDs != null ? Object.freeze([...options.allowedTLDs]) : void 0;
+	const allowedTlds = options?.allowedTlds != null ? Object.freeze([...options.allowedTlds]) : void 0;
+	const labelRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/;
+	if (allowedTlds !== void 0) for (const [i, tld] of allowedTlds.entries()) {
+		if (typeof tld !== "string") {
+			const actualType = Array.isArray(tld) ? "array" : typeof tld;
+			throw new TypeError(`allowedTlds[${i}] must be a string, but got ${actualType}.`);
+		}
+		if (tld.length === 0) throw new TypeError(`allowedTlds[${i}] must not be an empty string.`);
+		if (tld.includes(".")) throw new TypeError(`allowedTlds[${i}] must not contain dots: ${JSON.stringify(tld)}.`);
+		if (tld !== tld.trim()) throw new TypeError(`allowedTlds[${i}] must not have leading or trailing whitespace: ${JSON.stringify(tld)}.`);
+		if (!labelRegex.test(tld)) throw new TypeError(`allowedTlds[${i}] is not a valid DNS label: ${JSON.stringify(tld)}.`);
+	}
+	const allowedTldsLower = allowedTlds != null ? Object.freeze(allowedTlds.map((t) => t.toLowerCase())) : void 0;
 	const minLabels = options?.minLabels ?? 2;
 	const maxLength = options?.maxLength ?? 253;
 	const lowercase = options?.lowercase ?? false;
@@ -1870,7 +1885,6 @@ function domain(options) {
 	const tooFewLabels = options?.errors?.tooFewLabels;
 	const subdomainsNotAllowed = options?.errors?.subdomainsNotAllowed;
 	const tldNotAllowed = options?.errors?.tldNotAllowed;
-	const labelRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/;
 	return {
 		$mode: "sync",
 		metavar,
@@ -2034,15 +2048,14 @@ function domain(options) {
 					error: msg
 				};
 			}
-			if (allowedTLDs !== void 0) {
+			if (allowedTlds !== void 0 && allowedTldsLower !== void 0) {
 				const tld = labels[labels.length - 1];
 				const tldLower = tld.toLowerCase();
-				const allowedTLDsLower = allowedTLDs.map((t) => t.toLowerCase());
-				if (!allowedTLDsLower.includes(tldLower)) {
+				if (!allowedTldsLower.includes(tldLower)) {
 					const errorMsg = tldNotAllowed;
 					if (typeof errorMsg === "function") return {
 						success: false,
-						error: errorMsg(tld, allowedTLDs)
+						error: errorMsg(tld, allowedTlds)
 					};
 					const msg = errorMsg ?? [
 						{
@@ -2055,7 +2068,7 @@ function domain(options) {
 						},
 						{
 							type: "text",
-							text: ` is not allowed. Allowed TLDs: ${allowedTLDs.join(", ")}.`
+							text: ` is not allowed. Allowed TLDs: ${allowedTlds.join(", ")}.`
 						}
 					];
 					return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1109+fa132665",
+  "version": "1.0.0-dev.1122+85e536cf",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",