@optique/valibot 1.0.0-dev.921 → 1.0.1

package/README.md

@@ -45,7 +45,9 @@ import * as v from "valibot";
 
 const cli = run(
   object({
-    email: option("--email", valibot(v.pipe(v.string(), v.email()))),
+    email: option("--email",
+      valibot(v.pipe(v.string(), v.email()), { placeholder: "" }),
+    ),
   }),
 );
 
@@ -73,7 +75,9 @@ import { option } from "@optique/core/primitives";
 import { valibot } from "@optique/valibot";
 import * as v from "valibot";
 
-const email = option("--email", valibot(v.pipe(v.string(), v.email())));
+const email = option("--email",
+  valibot(v.pipe(v.string(), v.email()), { placeholder: "" }),
+);
 ~~~~
 
 ### URL validation
@@ -83,7 +87,9 @@ import { option } from "@optique/core/primitives";
 import { valibot } from "@optique/valibot";
 import * as v from "valibot";
 
-const url = option("--url", valibot(v.pipe(v.string(), v.url())));
+const url = option("--url",
+  valibot(v.pipe(v.string(), v.url()), { placeholder: "" }),
+);
 ~~~~
 
 ### Port numbers with range validation
@@ -105,7 +111,7 @@ const port = option("-p", "--port",
     v.integer(),
     v.minValue(1024),
     v.maxValue(65535)
-  ))
+  ), { placeholder: 0 }),
 );
 ~~~~
 
@@ -117,7 +123,8 @@ import { valibot } from "@optique/valibot";
 import * as v from "valibot";
 
 const logLevel = option("--log-level",
-  valibot(v.picklist(["debug", "info", "warn", "error"]))
+  valibot(v.picklist(["debug", "info", "warn", "error"]),
+    { placeholder: "debug" }),
 );
 ~~~~
 
@@ -129,7 +136,8 @@ import { valibot } from "@optique/valibot";
 import * as v from "valibot";
 
 const startDate = argument(
-  valibot(v.pipe(v.string(), v.transform((s: string) => new Date(s))))
+  valibot(v.pipe(v.string(), v.transform((s: string) => new Date(s))),
+    { placeholder: new Date(0) }),
 );
 ~~~~
 
@@ -146,6 +154,7 @@ import { message } from "@optique/core/message";
 import * as v from "valibot";
 
 const email = option("--email", valibot(v.pipe(v.string(), v.email()), {
+  placeholder: "",
   metavar: "EMAIL",
   errors: {
     valibotError: (issues, input) =>
@@ -169,7 +178,9 @@ import { valibot } from "@optique/valibot";
 import * as v from "valibot";
 
 // ✅ Correct
-const port = option("-p", valibot(v.pipe(v.string(), v.transform(Number))));
+const port = option("-p",
+  valibot(v.pipe(v.string(), v.transform(Number)), { placeholder: 0 }),
+);
 
 // ❌ Won't work (CLI arguments are always strings)
 // const port = option("-p", valibot(v.number()));
@@ -187,7 +198,9 @@ import * as v from "valibot";
 
 // ❌ Not supported
 const email = option("--email",
-  valibot(v.pipeAsync(v.string(), v.checkAsync(async (val) => await checkDB(val))))
+  valibot(v.pipeAsync(v.string(),
+    v.checkAsync(async (val) => await checkDB(val))),
+    { placeholder: "" }),
 );
 ~~~~
 

package/dist/index.cjs

@@ -22,10 +22,153 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 const __optique_core_message = __toESM(require("@optique/core/message"));
+const __optique_core_nonempty = __toESM(require("@optique/core/nonempty"));
 const valibot = __toESM(require("valibot"));
 
 //#region src/index.ts
 /**
+* Valibot transformation action types that are known to be non-rejecting and
+* type-preserving (they transform a string into a string without ever adding
+* issues).  All other transformation types (transform, raw_transform,
+* parse_json, to_number, to_boolean, etc.) may reject input or change the
+* value type.
+*/
+const SAFE_TRANSFORMATION_TYPES = new Set([
+	"trim",
+	"to_lower_case",
+	"to_upper_case",
+	"normalize",
+	"to_min_value",
+	"to_max_value",
+	"trim_start",
+	"trim_end",
+	"readonly",
+	"brand",
+	"flavor"
+]);
+/**
+* Checks whether a schema synchronously accepts every possible input value.
+* This includes:
+* - `v.unknown()`, `v.any()` (accept everything regardless of input type)
+* - Bare `v.string()` without a pipe (accepts every string)
+* - Any wrapper with a `wrapped` field pointing to a catch-all schema
+*   (e.g., `v.optional()`, `v.nullable()`, `v.nonOptional()`, etc.)
+*
+* Piped schemas are considered catch-all only when the base type is
+* `string`/`unknown`/`any` and every pipe action is a non-rejecting
+* transformation (not a validation or nested schema).
+*
+* @param afterTransform When true, only type-agnostic catch-alls
+*   (`v.unknown()`, `v.any()`) are recognized.  String-based catch-alls
+*   are not trusted since the input type may no longer be a string.
+*/
+function isCatchAllSchema(schema, afterTransform = false) {
+	const s = schema;
+	if (s.async) return false;
+	if ("fallback" in s) return true;
+	if (s.type === "unknown" || s.type === "any") {
+		if (!s.pipe) return true;
+		return s.pipe.slice(1).every((action) => {
+			const a = action;
+			if (a.kind === "validation") return false;
+			if (a.kind === "schema") return isCatchAllSchema(action, afterTransform);
+			return SAFE_TRANSFORMATION_TYPES.has(a.type ?? "");
+		});
+	}
+	if (!afterTransform && s.type === "string") {
+		if (!s.pipe) return true;
+		return s.pipe.slice(1).every((action) => {
+			const a = action;
+			if (a.kind === "validation") return false;
+			if (a.kind === "schema") return isCatchAllSchema(action, afterTransform);
+			return SAFE_TRANSFORMATION_TYPES.has(a.type ?? "");
+		});
+	}
+	if (s.wrapped && !s.pipe) return isCatchAllSchema(s.wrapped, afterTransform);
+	return false;
+}
+/**
+* Recursively checks whether a Valibot schema contains any async parts
+* (e.g., `pipeAsync`, `checkAsync`).  Wrapper schemas such as `optional()`,
+* `nullable()`, `nullish()`, and `union()` keep `async === false` on the
+* outer layer even when they wrap async inner schemas, so a shallow check
+* on the top-level `async` property is not sufficient.
+*
+* Known limitations:
+* - `v.variant()` arms are treated like union arms, but the catch-all
+*   detection does not recognize object-shaped variant arms.  Variant
+*   schemas with async arms after a broad discriminator will be
+*   conservatively rejected.
+* - `v.lazy()` schemas are not inspected because the getter depends on
+*   actual parse input, making static analysis unreliable.
+*
+* @param afterTransform When true, a preceding `v.transform()` may have
+*   changed the value type.  Container members become reachable and
+*   string-based union catch-all arms are no longer trusted.
+*/
+function containsAsyncSchema(schema, visited = /* @__PURE__ */ new WeakMap(), afterTransform = false) {
+	const prev = visited.get(schema);
+	if (prev !== void 0 && (prev || !afterTransform)) return false;
+	visited.set(schema, (prev ?? false) || afterTransform);
+	const s = schema;
+	if (s.async) return true;
+	if (s.wrapped && !s.pipe) return containsAsyncSchema(s.wrapped, visited, afterTransform);
+	if (s.options && Array.isArray(s.options)) {
+		if (s.type === "union") for (const option of s.options) {
+			if (typeof option !== "object" || option == null) continue;
+			if (isCatchAllSchema(option, afterTransform)) break;
+			if (containsAsyncSchema(option, visited, afterTransform)) return true;
+		}
+		else if (s.type === "variant") {
+			if (afterTransform) {
+				for (const option of s.options) if (typeof option === "object" && option != null) {
+					if (containsAsyncSchema(option, visited, true)) return true;
+				}
+			}
+		} else for (const option of s.options) if (typeof option === "object" && option != null) {
+			if (containsAsyncSchema(option, visited, afterTransform)) return true;
+		}
+	}
+	if (s.pipe && Array.isArray(s.pipe)) {
+		let seenTransform = afterTransform;
+		for (const action of s.pipe) {
+			if (action.async) return true;
+			const a = action;
+			if (a.kind === "transformation" && !SAFE_TRANSFORMATION_TYPES.has(a.type ?? "")) seenTransform = true;
+			if (a.kind === "schema") {
+				if (containsAsyncSchema(action, visited, seenTransform)) return true;
+				if (!seenTransform) {
+					const innerPipe = action.pipe;
+					if (innerPipe && Array.isArray(innerPipe)) for (const innerAction of innerPipe) {
+						const ia = innerAction;
+						if (ia.kind === "transformation" && !SAFE_TRANSFORMATION_TYPES.has(ia.type ?? "")) {
+							seenTransform = true;
+							break;
+						}
+					}
+				}
+			}
+		}
+	}
+	if (afterTransform) {
+		if (s.entries) {
+			for (const entry of Object.values(s.entries)) if (containsAsyncSchema(entry, visited, true)) return true;
+		}
+		if (s.item && containsAsyncSchema(s.item, visited, true)) return true;
+		if (s.items && Array.isArray(s.items)) {
+			for (const item of s.items) if (containsAsyncSchema(item, visited, true)) return true;
+		}
+		if (s.key && typeof s.key === "object" && containsAsyncSchema(s.key, visited, true)) return true;
+		if (s.value && containsAsyncSchema(s.value, visited, true)) return true;
+		if (s.rest && containsAsyncSchema(s.rest, visited, true)) return true;
+		if (s.type === "promise") {
+			const promiseInner = schema.message;
+			if (typeof promiseInner === "object" && promiseInner != null && "kind" in promiseInner && containsAsyncSchema(promiseInner, visited, true)) return true;
+		}
+	}
+	return false;
+}
+/**
 * Infers an appropriate metavar string from a Valibot schema.
 *
 * This function analyzes the Valibot schema's internal structure to determine
@@ -83,8 +226,15 @@ function inferMetavar(schema) {
 	if (schemaType === "boolean") return "BOOLEAN";
 	if (schemaType === "date") return "DATE";
 	if (schemaType === "picklist") return "CHOICE";
-	if (schemaType === "literal") return "VALUE";
-	if (schemaType === "union" || schemaType === "variant") return "VALUE";
+	if (schemaType === "literal") {
+		if (inferChoices(schema) != null) return "CHOICE";
+		return "VALUE";
+	}
+	if (schemaType === "union") {
+		if (inferChoices(schema) != null) return "CHOICE";
+		return "VALUE";
+	}
+	if (schemaType === "variant") return "VALUE";
 	if (schemaType === "optional" || schemaType === "nullable" || schemaType === "nullish") {
 		const wrapped = internalSchema.wrapped;
 		if (wrapped) return inferMetavar(wrapped);
@@ -92,6 +242,50 @@ function inferMetavar(schema) {
 	return "VALUE";
 }
 /**
+* Extracts valid choices from a Valibot schema that represents a fixed set of
+* values (picklist, literal, or union of literals).
+*
+* @param schema A Valibot schema to analyze.
+* @returns An array of string representations of valid choices, or `undefined`
+*          if the schema does not represent a fixed set of values.
+*/
+function inferChoices(schema) {
+	const internalSchema = schema;
+	const schemaType = internalSchema.type;
+	if (!schemaType) return void 0;
+	if (schemaType === "picklist") {
+		const options = internalSchema.options;
+		if (Array.isArray(options)) {
+			const result = [];
+			for (const opt of options) if (typeof opt === "string") result.push(opt);
+			else return void 0;
+			return result.length > 0 ? result : void 0;
+		}
+		return void 0;
+	}
+	if (schemaType === "literal") {
+		const value = internalSchema.literal;
+		if (typeof value === "string") return [value];
+		return void 0;
+	}
+	if (schemaType === "union") {
+		const options = internalSchema.options;
+		if (!Array.isArray(options)) return void 0;
+		const allChoices = /* @__PURE__ */ new Set();
+		for (const opt of options) if (typeof opt === "object" && opt != null && "type" in opt) {
+			const sub = inferChoices(opt);
+			if (sub == null) return void 0;
+			for (const choice of sub) allChoices.add(choice);
+		} else return void 0;
+		return allChoices.size > 0 ? [...allChoices] : void 0;
+	}
+	if (schemaType === "optional" || schemaType === "nullable" || schemaType === "nullish") {
+		const wrapped = internalSchema.wrapped;
+		if (wrapped) return inferChoices(wrapped);
+	}
+	return void 0;
+}
+/**
 * Creates a value parser from a Valibot schema.
 *
 * This parser validates CLI argument strings using Valibot schemas, enabling
@@ -108,7 +302,8 @@ function inferMetavar(schema) {
 *
 * @template T The output type of the Valibot schema.
 * @param schema A Valibot schema to validate input against.
-* @param options Optional configuration for the parser.
+* @param options Configuration for the parser, including a required
+*   `placeholder` value used during deferred prompt resolution.
 * @returns A value parser that validates inputs using the provided schema.
 *
 * @example Basic string validation
@@ -117,7 +312,9 @@ function inferMetavar(schema) {
 * import { valibot } from "@optique/valibot";
 * import { option } from "@optique/core/primitives";
 *
-* const email = option("--email", valibot(v.pipe(v.string(), v.email())));
+* const email = option("--email",
+*   valibot(v.pipe(v.string(), v.email()), { placeholder: "" }),
+* );
 * ```
 *
 * @example Number validation with pipeline
@@ -134,8 +331,8 @@ function inferMetavar(schema) {
 *     v.number(),
 *     v.integer(),
 *     v.minValue(1024),
-*     v.maxValue(65535)
-*   ))
+*     v.maxValue(65535),
+*   ), { placeholder: 1024 }),
 * );
 * ```
 *
@@ -146,7 +343,9 @@ function inferMetavar(schema) {
 * import { option } from "@optique/core/primitives";
 *
 * const logLevel = option("--log-level",
-*   valibot(v.picklist(["debug", "info", "warn", "error"]))
+*   valibot(v.picklist(["debug", "info", "warn", "error"]), {
+*     placeholder: "debug",
+*   }),
 * );
 * ```
 *
@@ -159,23 +358,46 @@ function inferMetavar(schema) {
 *
 * const email = option("--email",
 *   valibot(v.pipe(v.string(), v.email()), {
+*     placeholder: "",
 *     metavar: "EMAIL",
 *     errors: {
 *       valibotError: (issues, input) =>
 *         message`Please provide a valid email address, got ${input}.`
-*     }
-*   })
+*     },
+*   }),
 * );
 * ```
 *
+* @throws {TypeError} If `options` is missing, not an object, or does not
+*   include `placeholder`.
+* @throws {TypeError} If the resolved `metavar` is an empty string.
+* @throws {TypeError} If the schema contains async validations that cannot be
+*   executed synchronously.
 * @since 0.7.0
 */
-function valibot$1(schema, options = {}) {
-	return {
-		$mode: "sync",
-		metavar: options.metavar ?? inferMetavar(schema),
+function valibot$1(schema, options) {
+	if (options == null || typeof options !== "object") throw new TypeError("valibot() requires an options object with a placeholder property.");
+	if (!("placeholder" in options)) throw new TypeError("valibot() options must include a placeholder property.");
+	if (containsAsyncSchema(schema)) throw new TypeError("Async Valibot schemas (e.g., async validations) are not supported by valibot(). Use synchronous schemas instead.");
+	const choices = inferChoices(schema);
+	const metavar = options.metavar ?? inferMetavar(schema);
+	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
+	const parser = {
+		mode: "sync",
+		metavar,
+		placeholder: options.placeholder,
+		...choices != null && choices.length > 0 ? {
+			choices: Object.freeze(choices),
+			*suggest(prefix) {
+				for (const c of choices) if (c.startsWith(prefix)) yield {
+					kind: "literal",
+					text: c
+				};
+			}
+		} : {},
 		parse(input) {
 			const result = (0, valibot.safeParse)(schema, input);
+			if (typeof result.typed !== "boolean") throw new TypeError("Async Valibot schemas (e.g., async validations) are not supported by valibot(). Use synchronous schemas instead.");
 			if (result.success) return {
 				success: true,
 				value: result.output
@@ -191,9 +413,20 @@ function valibot$1(schema, options = {}) {
 			};
 		},
 		format(value) {
-			return String(value);
+			if (options.format) return options.format(value);
+			if (value instanceof Date) return Number.isNaN(value.getTime()) ? String(value) : value.toISOString();
+			if (typeof value !== "object" || value === null) return String(value);
+			if (Array.isArray(value)) return String(value);
+			const str = String(value);
+			if (str !== "[object Object]") return str;
+			const proto = Object.getPrototypeOf(value);
+			if (proto === Object.prototype || proto === null) try {
+				return JSON.stringify(value) ?? str;
+			} catch {}
+			return str;
 		}
 	};
+	return parser;
 }
 
 //#endregion

package/dist/index.d.cts

@@ -8,7 +8,7 @@ import * as v from "valibot";
  * Options for creating a Valibot value parser.
  * @since 0.7.0
  */
-interface ValibotParserOptions {
+interface ValibotParserOptions<T = unknown> {
   /**
    * The metavariable name for this parser. This is used in help messages to
    * indicate what kind of value this parser expects. Usually a single
@@ -16,6 +16,25 @@ interface ValibotParserOptions {
    * @default `"VALUE"`
    */
   readonly metavar?: NonEmptyString;
+  /**
+   * A phase-one stand-in value of type `T` used during deferred prompt
+   * resolution.  Because the output type of a Valibot schema cannot be
+   * inferred to a concrete default, callers must provide this explicitly.
+   * @since 1.0.0
+   */
+  readonly placeholder: T;
+  /**
+   * Custom formatter for displaying parsed values in help messages.
+   * When not provided, the default formatter is used: primitives use
+   * `String()`, valid `Date` values use `.toISOString()`, and plain
+   * objects use `JSON.stringify()`.  All other objects (arrays, class
+   * instances, etc.) use `String()`.
+   *
+   * @param value The parsed value to format.
+   * @returns A string representation of the value.
+   * @since 1.0.0
+   */
+  readonly format?: (value: T) => string;
   /**
    * Custom error messages for Valibot validation failures.
    */
@@ -46,7 +65,8 @@ interface ValibotParserOptions {
  *
  * @template T The output type of the Valibot schema.
  * @param schema A Valibot schema to validate input against.
- * @param options Optional configuration for the parser.
+ * @param options Configuration for the parser, including a required
+ *   `placeholder` value used during deferred prompt resolution.
  * @returns A value parser that validates inputs using the provided schema.
  *
  * @example Basic string validation
@@ -55,7 +75,9 @@ interface ValibotParserOptions {
  * import { valibot } from "@optique/valibot";
  * import { option } from "@optique/core/primitives";
  *
- * const email = option("--email", valibot(v.pipe(v.string(), v.email())));
+ * const email = option("--email",
+ *   valibot(v.pipe(v.string(), v.email()), { placeholder: "" }),
+ * );
  * ```
  *
  * @example Number validation with pipeline
@@ -72,8 +94,8 @@ interface ValibotParserOptions {
  *     v.number(),
  *     v.integer(),
  *     v.minValue(1024),
- *     v.maxValue(65535)
- *   ))
+ *     v.maxValue(65535),
+ *   ), { placeholder: 1024 }),
  * );
  * ```
  *
@@ -84,7 +106,9 @@ interface ValibotParserOptions {
  * import { option } from "@optique/core/primitives";
  *
  * const logLevel = option("--log-level",
- *   valibot(v.picklist(["debug", "info", "warn", "error"]))
+ *   valibot(v.picklist(["debug", "info", "warn", "error"]), {
+ *     placeholder: "debug",
+ *   }),
  * );
  * ```
  *
@@ -97,17 +121,23 @@ interface ValibotParserOptions {
  *
  * const email = option("--email",
  *   valibot(v.pipe(v.string(), v.email()), {
+ *     placeholder: "",
  *     metavar: "EMAIL",
  *     errors: {
  *       valibotError: (issues, input) =>
  *         message`Please provide a valid email address, got ${input}.`
- *     }
- *   })
+ *     },
+ *   }),
  * );
  * ```
  *
+ * @throws {TypeError} If `options` is missing, not an object, or does not
+ *   include `placeholder`.
+ * @throws {TypeError} If the resolved `metavar` is an empty string.
+ * @throws {TypeError} If the schema contains async validations that cannot be
+ *   executed synchronously.
  * @since 0.7.0
  */
-declare function valibot<T>(schema: v.BaseSchema<unknown, T, v.BaseIssue<unknown>>, options?: ValibotParserOptions): ValueParser<"sync", T>;
+declare function valibot<T>(schema: v.BaseSchema<unknown, T, v.BaseIssue<unknown>>, options: ValibotParserOptions<T>): ValueParser<"sync", T>;
 //#endregion
 export { ValibotParserOptions, valibot };

package/dist/index.d.ts

@@ -8,7 +8,7 @@ import { NonEmptyString, ValueParser } from "@optique/core/valueparser";
  * Options for creating a Valibot value parser.
  * @since 0.7.0
  */
-interface ValibotParserOptions {
+interface ValibotParserOptions<T = unknown> {
   /**
    * The metavariable name for this parser. This is used in help messages to
    * indicate what kind of value this parser expects. Usually a single
@@ -16,6 +16,25 @@ interface ValibotParserOptions {
    * @default `"VALUE"`
    */
   readonly metavar?: NonEmptyString;
+  /**
+   * A phase-one stand-in value of type `T` used during deferred prompt
+   * resolution.  Because the output type of a Valibot schema cannot be
+   * inferred to a concrete default, callers must provide this explicitly.
+   * @since 1.0.0
+   */
+  readonly placeholder: T;
+  /**
+   * Custom formatter for displaying parsed values in help messages.
+   * When not provided, the default formatter is used: primitives use
+   * `String()`, valid `Date` values use `.toISOString()`, and plain
+   * objects use `JSON.stringify()`.  All other objects (arrays, class
+   * instances, etc.) use `String()`.
+   *
+   * @param value The parsed value to format.
+   * @returns A string representation of the value.
+   * @since 1.0.0
+   */
+  readonly format?: (value: T) => string;
   /**
    * Custom error messages for Valibot validation failures.
    */
@@ -46,7 +65,8 @@ interface ValibotParserOptions {
  *
  * @template T The output type of the Valibot schema.
  * @param schema A Valibot schema to validate input against.
- * @param options Optional configuration for the parser.
+ * @param options Configuration for the parser, including a required
+ *   `placeholder` value used during deferred prompt resolution.
  * @returns A value parser that validates inputs using the provided schema.
  *
  * @example Basic string validation
@@ -55,7 +75,9 @@ interface ValibotParserOptions {
  * import { valibot } from "@optique/valibot";
  * import { option } from "@optique/core/primitives";
  *
- * const email = option("--email", valibot(v.pipe(v.string(), v.email())));
+ * const email = option("--email",
+ *   valibot(v.pipe(v.string(), v.email()), { placeholder: "" }),
+ * );
  * ```
  *
  * @example Number validation with pipeline
@@ -72,8 +94,8 @@ interface ValibotParserOptions {
  *     v.number(),
  *     v.integer(),
  *     v.minValue(1024),
- *     v.maxValue(65535)
- *   ))
+ *     v.maxValue(65535),
+ *   ), { placeholder: 1024 }),
  * );
  * ```
  *
@@ -84,7 +106,9 @@ interface ValibotParserOptions {
  * import { option } from "@optique/core/primitives";
  *
  * const logLevel = option("--log-level",
- *   valibot(v.picklist(["debug", "info", "warn", "error"]))
+ *   valibot(v.picklist(["debug", "info", "warn", "error"]), {
+ *     placeholder: "debug",
+ *   }),
  * );
  * ```
  *
@@ -97,17 +121,23 @@ interface ValibotParserOptions {
  *
  * const email = option("--email",
  *   valibot(v.pipe(v.string(), v.email()), {
+ *     placeholder: "",
  *     metavar: "EMAIL",
  *     errors: {
  *       valibotError: (issues, input) =>
  *         message`Please provide a valid email address, got ${input}.`
- *     }
- *   })
+ *     },
+ *   }),
  * );
  * ```
  *
+ * @throws {TypeError} If `options` is missing, not an object, or does not
+ *   include `placeholder`.
+ * @throws {TypeError} If the resolved `metavar` is an empty string.
+ * @throws {TypeError} If the schema contains async validations that cannot be
+ *   executed synchronously.
  * @since 0.7.0
  */
-declare function valibot<T>(schema: v.BaseSchema<unknown, T, v.BaseIssue<unknown>>, options?: ValibotParserOptions): ValueParser<"sync", T>;
+declare function valibot<T>(schema: v.BaseSchema<unknown, T, v.BaseIssue<unknown>>, options: ValibotParserOptions<T>): ValueParser<"sync", T>;
 //#endregion
 export { ValibotParserOptions, valibot };

package/dist/index.js

@@ -1,8 +1,151 @@
 import { message } from "@optique/core/message";
+import { ensureNonEmptyString } from "@optique/core/nonempty";
 import { safeParse } from "valibot";
 
 //#region src/index.ts
 /**
+* Valibot transformation action types that are known to be non-rejecting and
+* type-preserving (they transform a string into a string without ever adding
+* issues).  All other transformation types (transform, raw_transform,
+* parse_json, to_number, to_boolean, etc.) may reject input or change the
+* value type.
+*/
+const SAFE_TRANSFORMATION_TYPES = new Set([
+	"trim",
+	"to_lower_case",
+	"to_upper_case",
+	"normalize",
+	"to_min_value",
+	"to_max_value",
+	"trim_start",
+	"trim_end",
+	"readonly",
+	"brand",
+	"flavor"
+]);
+/**
+* Checks whether a schema synchronously accepts every possible input value.
+* This includes:
+* - `v.unknown()`, `v.any()` (accept everything regardless of input type)
+* - Bare `v.string()` without a pipe (accepts every string)
+* - Any wrapper with a `wrapped` field pointing to a catch-all schema
+*   (e.g., `v.optional()`, `v.nullable()`, `v.nonOptional()`, etc.)
+*
+* Piped schemas are considered catch-all only when the base type is
+* `string`/`unknown`/`any` and every pipe action is a non-rejecting
+* transformation (not a validation or nested schema).
+*
+* @param afterTransform When true, only type-agnostic catch-alls
+*   (`v.unknown()`, `v.any()`) are recognized.  String-based catch-alls
+*   are not trusted since the input type may no longer be a string.
+*/
+function isCatchAllSchema(schema, afterTransform = false) {
+	const s = schema;
+	if (s.async) return false;
+	if ("fallback" in s) return true;
+	if (s.type === "unknown" || s.type === "any") {
+		if (!s.pipe) return true;
+		return s.pipe.slice(1).every((action) => {
+			const a = action;
+			if (a.kind === "validation") return false;
+			if (a.kind === "schema") return isCatchAllSchema(action, afterTransform);
+			return SAFE_TRANSFORMATION_TYPES.has(a.type ?? "");
+		});
+	}
+	if (!afterTransform && s.type === "string") {
+		if (!s.pipe) return true;
+		return s.pipe.slice(1).every((action) => {
+			const a = action;
+			if (a.kind === "validation") return false;
+			if (a.kind === "schema") return isCatchAllSchema(action, afterTransform);
+			return SAFE_TRANSFORMATION_TYPES.has(a.type ?? "");
+		});
+	}
+	if (s.wrapped && !s.pipe) return isCatchAllSchema(s.wrapped, afterTransform);
+	return false;
+}
+/**
+* Recursively checks whether a Valibot schema contains any async parts
+* (e.g., `pipeAsync`, `checkAsync`).  Wrapper schemas such as `optional()`,
+* `nullable()`, `nullish()`, and `union()` keep `async === false` on the
+* outer layer even when they wrap async inner schemas, so a shallow check
+* on the top-level `async` property is not sufficient.
+*
+* Known limitations:
+* - `v.variant()` arms are treated like union arms, but the catch-all
+*   detection does not recognize object-shaped variant arms.  Variant
+*   schemas with async arms after a broad discriminator will be
+*   conservatively rejected.
+* - `v.lazy()` schemas are not inspected because the getter depends on
+*   actual parse input, making static analysis unreliable.
+*
+* @param afterTransform When true, a preceding `v.transform()` may have
+*   changed the value type.  Container members become reachable and
+*   string-based union catch-all arms are no longer trusted.
+*/
+function containsAsyncSchema(schema, visited = /* @__PURE__ */ new WeakMap(), afterTransform = false) {
+	const prev = visited.get(schema);
+	if (prev !== void 0 && (prev || !afterTransform)) return false;
+	visited.set(schema, (prev ?? false) || afterTransform);
+	const s = schema;
+	if (s.async) return true;
+	if (s.wrapped && !s.pipe) return containsAsyncSchema(s.wrapped, visited, afterTransform);
+	if (s.options && Array.isArray(s.options)) {
+		if (s.type === "union") for (const option of s.options) {
+			if (typeof option !== "object" || option == null) continue;
+			if (isCatchAllSchema(option, afterTransform)) break;
+			if (containsAsyncSchema(option, visited, afterTransform)) return true;
+		}
+		else if (s.type === "variant") {
+			if (afterTransform) {
+				for (const option of s.options) if (typeof option === "object" && option != null) {
+					if (containsAsyncSchema(option, visited, true)) return true;
+				}
+			}
+		} else for (const option of s.options) if (typeof option === "object" && option != null) {
+			if (containsAsyncSchema(option, visited, afterTransform)) return true;
+		}
+	}
+	if (s.pipe && Array.isArray(s.pipe)) {
+		let seenTransform = afterTransform;
+		for (const action of s.pipe) {
+			if (action.async) return true;
+			const a = action;
+			if (a.kind === "transformation" && !SAFE_TRANSFORMATION_TYPES.has(a.type ?? "")) seenTransform = true;
+			if (a.kind === "schema") {
+				if (containsAsyncSchema(action, visited, seenTransform)) return true;
+				if (!seenTransform) {
+					const innerPipe = action.pipe;
+					if (innerPipe && Array.isArray(innerPipe)) for (const innerAction of innerPipe) {
+						const ia = innerAction;
+						if (ia.kind === "transformation" && !SAFE_TRANSFORMATION_TYPES.has(ia.type ?? "")) {
+							seenTransform = true;
+							break;
+						}
+					}
+				}
+			}
+		}
+	}
+	if (afterTransform) {
+		if (s.entries) {
+			for (const entry of Object.values(s.entries)) if (containsAsyncSchema(entry, visited, true)) return true;
+		}
+		if (s.item && containsAsyncSchema(s.item, visited, true)) return true;
+		if (s.items && Array.isArray(s.items)) {
+			for (const item of s.items) if (containsAsyncSchema(item, visited, true)) return true;
+		}
+		if (s.key && typeof s.key === "object" && containsAsyncSchema(s.key, visited, true)) return true;
+		if (s.value && containsAsyncSchema(s.value, visited, true)) return true;
+		if (s.rest && containsAsyncSchema(s.rest, visited, true)) return true;
+		if (s.type === "promise") {
+			const promiseInner = schema.message;
+			if (typeof promiseInner === "object" && promiseInner != null && "kind" in promiseInner && containsAsyncSchema(promiseInner, visited, true)) return true;
+		}
+	}
+	return false;
+}
+/**
 * Infers an appropriate metavar string from a Valibot schema.
 *
 * This function analyzes the Valibot schema's internal structure to determine
@@ -60,8 +203,15 @@ function inferMetavar(schema) {
 	if (schemaType === "boolean") return "BOOLEAN";
 	if (schemaType === "date") return "DATE";
 	if (schemaType === "picklist") return "CHOICE";
-	if (schemaType === "literal") return "VALUE";
-	if (schemaType === "union" || schemaType === "variant") return "VALUE";
+	if (schemaType === "literal") {
+		if (inferChoices(schema) != null) return "CHOICE";
+		return "VALUE";
+	}
+	if (schemaType === "union") {
+		if (inferChoices(schema) != null) return "CHOICE";
+		return "VALUE";
+	}
+	if (schemaType === "variant") return "VALUE";
 	if (schemaType === "optional" || schemaType === "nullable" || schemaType === "nullish") {
 		const wrapped = internalSchema.wrapped;
 		if (wrapped) return inferMetavar(wrapped);
@@ -69,6 +219,50 @@ function inferMetavar(schema) {
 	return "VALUE";
 }
 /**
+* Extracts valid choices from a Valibot schema that represents a fixed set of
+* values (picklist, literal, or union of literals).
+*
+* @param schema A Valibot schema to analyze.
+* @returns An array of string representations of valid choices, or `undefined`
+*          if the schema does not represent a fixed set of values.
+*/
+function inferChoices(schema) {
+	const internalSchema = schema;
+	const schemaType = internalSchema.type;
+	if (!schemaType) return void 0;
+	if (schemaType === "picklist") {
+		const options = internalSchema.options;
+		if (Array.isArray(options)) {
+			const result = [];
+			for (const opt of options) if (typeof opt === "string") result.push(opt);
+			else return void 0;
+			return result.length > 0 ? result : void 0;
+		}
+		return void 0;
+	}
+	if (schemaType === "literal") {
+		const value = internalSchema.literal;
+		if (typeof value === "string") return [value];
+		return void 0;
+	}
+	if (schemaType === "union") {
+		const options = internalSchema.options;
+		if (!Array.isArray(options)) return void 0;
+		const allChoices = /* @__PURE__ */ new Set();
+		for (const opt of options) if (typeof opt === "object" && opt != null && "type" in opt) {
+			const sub = inferChoices(opt);
+			if (sub == null) return void 0;
+			for (const choice of sub) allChoices.add(choice);
+		} else return void 0;
+		return allChoices.size > 0 ? [...allChoices] : void 0;
+	}
+	if (schemaType === "optional" || schemaType === "nullable" || schemaType === "nullish") {
+		const wrapped = internalSchema.wrapped;
+		if (wrapped) return inferChoices(wrapped);
+	}
+	return void 0;
+}
+/**
 * Creates a value parser from a Valibot schema.
 *
 * This parser validates CLI argument strings using Valibot schemas, enabling
@@ -85,7 +279,8 @@ function inferMetavar(schema) {
 *
 * @template T The output type of the Valibot schema.
 * @param schema A Valibot schema to validate input against.
-* @param options Optional configuration for the parser.
+* @param options Configuration for the parser, including a required
+*   `placeholder` value used during deferred prompt resolution.
 * @returns A value parser that validates inputs using the provided schema.
 *
 * @example Basic string validation
@@ -94,7 +289,9 @@ function inferMetavar(schema) {
 * import { valibot } from "@optique/valibot";
 * import { option } from "@optique/core/primitives";
 *
-* const email = option("--email", valibot(v.pipe(v.string(), v.email())));
+* const email = option("--email",
+*   valibot(v.pipe(v.string(), v.email()), { placeholder: "" }),
+* );
 * ```
 *
 * @example Number validation with pipeline
@@ -111,8 +308,8 @@ function inferMetavar(schema) {
 *     v.number(),
 *     v.integer(),
 *     v.minValue(1024),
-*     v.maxValue(65535)
-*   ))
+*     v.maxValue(65535),
+*   ), { placeholder: 1024 }),
 * );
 * ```
 *
@@ -123,7 +320,9 @@ function inferMetavar(schema) {
 * import { option } from "@optique/core/primitives";
 *
 * const logLevel = option("--log-level",
-*   valibot(v.picklist(["debug", "info", "warn", "error"]))
+*   valibot(v.picklist(["debug", "info", "warn", "error"]), {
+*     placeholder: "debug",
+*   }),
 * );
 * ```
 *
@@ -136,23 +335,46 @@ function inferMetavar(schema) {
 *
 * const email = option("--email",
 *   valibot(v.pipe(v.string(), v.email()), {
+*     placeholder: "",
 *     metavar: "EMAIL",
 *     errors: {
 *       valibotError: (issues, input) =>
 *         message`Please provide a valid email address, got ${input}.`
-*     }
-*   })
+*     },
+*   }),
 * );
 * ```
 *
+* @throws {TypeError} If `options` is missing, not an object, or does not
+*   include `placeholder`.
+* @throws {TypeError} If the resolved `metavar` is an empty string.
+* @throws {TypeError} If the schema contains async validations that cannot be
+*   executed synchronously.
 * @since 0.7.0
 */
-function valibot(schema, options = {}) {
-	return {
-		$mode: "sync",
-		metavar: options.metavar ?? inferMetavar(schema),
+function valibot(schema, options) {
+	if (options == null || typeof options !== "object") throw new TypeError("valibot() requires an options object with a placeholder property.");
+	if (!("placeholder" in options)) throw new TypeError("valibot() options must include a placeholder property.");
+	if (containsAsyncSchema(schema)) throw new TypeError("Async Valibot schemas (e.g., async validations) are not supported by valibot(). Use synchronous schemas instead.");
+	const choices = inferChoices(schema);
+	const metavar = options.metavar ?? inferMetavar(schema);
+	ensureNonEmptyString(metavar);
+	const parser = {
+		mode: "sync",
+		metavar,
+		placeholder: options.placeholder,
+		...choices != null && choices.length > 0 ? {
+			choices: Object.freeze(choices),
+			*suggest(prefix) {
+				for (const c of choices) if (c.startsWith(prefix)) yield {
+					kind: "literal",
+					text: c
+				};
+			}
+		} : {},
 		parse(input) {
 			const result = safeParse(schema, input);
+			if (typeof result.typed !== "boolean") throw new TypeError("Async Valibot schemas (e.g., async validations) are not supported by valibot(). Use synchronous schemas instead.");
 			if (result.success) return {
 				success: true,
 				value: result.output
@@ -168,9 +390,20 @@ function valibot(schema, options = {}) {
 			};
 		},
 		format(value) {
-			return String(value);
+			if (options.format) return options.format(value);
+			if (value instanceof Date) return Number.isNaN(value.getTime()) ? String(value) : value.toISOString();
+			if (typeof value !== "object" || value === null) return String(value);
+			if (Array.isArray(value)) return String(value);
+			const str = String(value);
+			if (str !== "[object Object]") return str;
+			const proto = Object.getPrototypeOf(value);
+			if (proto === Object.prototype || proto === null) try {
+				return JSON.stringify(value) ?? str;
+			} catch {}
+			return str;
 		}
 	};
+	return parser;
 }
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/valibot",
-  "version": "1.0.0-dev.921+754748bd",
+  "version": "1.0.1",
   "description": "Valibot value parsers for Optique",
   "keywords": [
     "CLI",
@@ -57,7 +57,7 @@
     "valibot": "^1.2.0"
   },
   "dependencies": {
-    "@optique/core": "1.0.0-dev.921+754748bd"
+    "@optique/core": "1.0.1"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",