@optique/core 1.3.0-dev.2581 → 1.3.0-dev.2583

package/dist/valueparser.js

@@ -2750,6 +2750,178 @@ function url(options = {}) {
 	};
 }
 /**
+* A host name that the WHATWG URL parser has canonicalized into a dotted-quad
+* IPv4 address.  Matching the canonical form is enough, because the parser
+* turns every other spelling (`0x7f.1`, `2130706433`, …) into it.
+*/
+const IPV4_PATTERN = /^\d{1,3}(?:\.\d{1,3}){3}$/u;
+/**
+* Creates a {@link ValueParser} for web origins.
+*
+* An origin is a scheme, a host, and an optional port, and nothing else.  The
+* parser returns a `URL` whose pathname is `/` and which carries no
+* credentials, query, or fragment.
+*
+* Input is canonicalized rather than rejected when it carries more than an
+* origin: the host is lowercased, internationalized names are converted to
+* punycode, and a default port is elided, so `HTTPS://Example.COM/`,
+* `https://example.com:443/path?query#fragment` all parse to
+* `https://example.com`.  Set `extraComponents: "reject"` to fail on a path,
+* query, or fragment instead.  Credentials are always rejected.  Schemes whose
+* origin is opaque (`mailto:`, `data:`, `file:`) are rejected, as is `blob:`,
+* whose origin belongs to the URL it wraps.
+*
+* By default a trailing root-zone dot is stripped, so `example.com.` becomes
+* `example.com`.  This differs from the WHATWG origin, which keeps the dot, so
+* the two strings are not interchangeable when an exact origin comparison
+* matters.  Use `trailingDot: "preserve"` for the WHATWG behavior or
+* `trailingDot: "append"` to force a fully-qualified name.
+*
+* @param options Configuration options for the origin parser.
+* @returns A {@link ValueParser} that converts string input to `URL` objects
+*          that name an origin.
+* @throws {TypeError} If any `allowedProtocols` entry is not a valid protocol
+*   string ending with a colon (e.g., `"https:"`).
+* @since 1.3.0
+*/
+function origin(options = {}) {
+	const metavar$1 = options.metavar ?? "ORIGIN";
+	ensureNonEmptyString(metavar$1);
+	checkEnumOption(options, "extraComponents", ["strip", "reject"]);
+	checkEnumOption(options, "trailingDot", [
+		"strip",
+		"preserve",
+		"append"
+	]);
+	const extraComponents = options.extraComponents ?? "strip";
+	const trailingDot = options.trailingDot ?? "strip";
+	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);
+		}
+		if (originalProtocolsList.length === 0) throw new TypeError("allowedProtocols must not be empty.");
+	}
+	const originalProtocols = options.allowedProtocols != null ? Object.freeze(originalProtocolsList) : void 0;
+	const allowedProtocols = options.allowedProtocols != null ? Object.freeze(normalizedProtocolsList) : void 0;
+	const invalidOrigin = options.errors?.invalidOrigin;
+	const disallowedProtocol = options.errors?.disallowedProtocol;
+	function invalidOriginError(input) {
+		return invalidOrigin ? typeof invalidOrigin === "function" ? invalidOrigin(input) : invalidOrigin : message`Invalid origin: ${input}.`;
+	}
+	function disallowedProtocolError(protocol) {
+		return disallowedProtocol ? typeof disallowedProtocol === "function" ? disallowedProtocol(protocol, originalProtocols) : disallowedProtocol : [
+			{
+				type: "text",
+				text: "URL protocol "
+			},
+			{
+				type: "value",
+				value: protocol
+			},
+			{
+				type: "text",
+				text: " is not allowed. Allowed protocols: "
+			},
+			...valueSet(originalProtocols, {
+				fallback: "",
+				locale: "en-US"
+			}),
+			{
+				type: "text",
+				text: "."
+			}
+		];
+	}
+	function withTrailingDot(url$1) {
+		if (trailingDot === "preserve") return url$1;
+		const { hostname: hostname$1 } = url$1;
+		if (hostname$1.startsWith("[") || IPV4_PATTERN.test(hostname$1)) return url$1;
+		if (trailingDot === "strip") {
+			const stripped = hostname$1.replace(/\.+$/u, "");
+			if (stripped !== "") url$1.hostname = stripped;
+		} else if (!hostname$1.endsWith(".")) url$1.hostname = `${hostname$1}.`;
+		return url$1;
+	}
+	function resolve(url$1, label) {
+		if (allowedProtocols != null && !allowedProtocols.includes(url$1.protocol)) return {
+			success: false,
+			error: disallowedProtocolError(url$1.protocol)
+		};
+		if (url$1.protocol === "blob:") return {
+			success: false,
+			error: message`The URL ${label} wraps another origin. Pass that origin instead.`
+		};
+		if (url$1.origin === "null") return {
+			success: false,
+			error: message`The URL ${label} has no origin.`
+		};
+		if (url$1.username !== "" || url$1.password !== "") return {
+			success: false,
+			error: message`An origin must not contain credentials: ${url$1.origin}`
+		};
+		if (extraComponents === "reject" && (url$1.pathname !== "/" || url$1.search !== "" || url$1.hash !== "")) return {
+			success: false,
+			error: message`Expected only an origin, but got: ${label}`
+		};
+		return {
+			success: true,
+			value: withTrailingDot(new URL(url$1.origin))
+		};
+	}
+	return {
+		mode: "sync",
+		metavar: metavar$1,
+		get placeholder() {
+			return new URL(`${allowedProtocols?.[0] ?? "http:"}//0.invalid`);
+		},
+		parse(input) {
+			if (!URL.canParse(input)) return {
+				success: false,
+				error: invalidOriginError(input)
+			};
+			return resolve(new URL(input), input);
+		},
+		validate(value) {
+			if (!(value instanceof URL)) return {
+				success: false,
+				error: invalidOriginError(String(value))
+			};
+			return resolve(value, value.href);
+		},
+		format(value) {
+			return value.origin;
+		},
+		normalize(value) {
+			if (!(value instanceof URL)) return value;
+			const result = resolve(value, value.href);
+			return result.success ? result.value : value;
+		},
+		*suggest(prefix) {
+			if (allowedProtocols && prefix.length > 0 && !prefix.includes(":")) for (const protocol of allowedProtocols) {
+				const cleanProtocol = protocol.replace(/:+$/, "");
+				if (cleanProtocol.startsWith(prefix.toLowerCase())) {
+					const suffix = SPECIAL_URL_SCHEMES.has(cleanProtocol) ? "://" : ":";
+					yield {
+						kind: "literal",
+						text: `${cleanProtocol}${suffix}`
+					};
+				}
+			}
+		}
+	};
+}
+/**
 * Creates a {@link ValueParser} for locale values.
 *
 * This parser validates that the input is a well-formed locale identifier
@@ -6667,4 +6839,4 @@ function plainObjectsEqual(a, b) {
 }
 
 //#endregion
-export { biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };
+export { biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0-dev.2581",
+  "version": "1.3.0-dev.2583",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.3.0-dev.2581+50dd484c",
+    "@optique/env": "1.3.0-dev.2583+d30dbb53",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -41,11 +41,11 @@ Core rules
     customize terminal output with `theme` or `messageFormatter`, preserving
     `initialWidth`, quoting, and width options. Keep canonical errors unthemed.
  -  Use value parsers such as `integer()`, `choice()`, `biject()`, `regExp()`,
-    `url()`, and `uuid()` instead of validating raw strings after parsing. Use
-    `regExp({ flags })` for user-supplied regular expression sources,
-    `biject()` for one-to-one string-to-value choices, and `transform()` when
-    an existing value parser describes the accepted CLI spelling but your app
-    needs a different result type. Use `path()` from
+    `url()`, `origin()`, and `uuid()` instead of validating raw strings after
+    parsing. Use `regExp({ flags })` for user-supplied sources, `biject()` for
+    one-to-one string-to-value choices, and `transform()` when an existing
+    value parser describes the accepted CLI spelling but your app needs a
+    different result type. Use `path()` from
     `@optique/run/valueparser` for file-system paths. Write a custom
     `{ mode, metavar, parse, format }` value parser only when the catalog does
     not cover the domain.