@optique/core 1.2.0-dev.2298 → 1.2.0-dev.2302

package/skills/optique/SKILL.md

@@ -40,8 +40,11 @@ Core rules
  -  Use `message` from *@optique/core/message* for descriptions, help text, and
     custom errors. Prefer semantic message helpers such as `optionName()` and
     `metavar()` over string concatenation when naming CLI elements.
- -  Use value parsers such as `integer()`, `choice()`, `url()`, and `uuid()`
-    instead of validating raw strings after parsing. Use `path()` from
+ -  Use value parsers such as `integer()`, `choice()`, `biject()`, `url()`,
+    and `uuid()` instead of validating raw strings after parsing. Use
+    `biject()` for one-to-one string-to-value choices, and use `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.
@@ -55,6 +58,8 @@ Core rules
     apps. Do not hand-write completion scripts from parser metadata.
  -  Use `showUsage: false` in runner options when full help should show the
     brief and command or option sections without the `Usage:` synopsis.
+    For deeply nested command trees, add `commandList: "top-level"` when root
+    help should list only first-level command groups.
 
 
 Canonical app shape
@@ -136,9 +141,32 @@ if (result.success) {
 Custom value parsers
 --------------------
 
-Prefer the built-in catalog first. When a custom domain is needed, keep the
-validation in a value parser so help, errors, defaults, prompts, and completion
-all see the same typed value.
+Prefer the built-in catalog first. If a one-to-one dictionary can describe the
+input tokens and domain values, use `biject()`. If an existing parser already
+accepts the right input syntax, wrap it with `transform()` before writing a
+custom parser:
+
+~~~~ typescript
+import { biject, choice, transform } from "@optique/core/valueparser";
+
+const exitCode = biject({
+  ok: 0,
+  warning: 1,
+  error: 2,
+});
+
+const logLevel = transform(choice(["debug", "info", "warn", "error"] as const), {
+  map(value) {
+    return value.toUpperCase() as "DEBUG" | "INFO" | "WARN" | "ERROR";
+  },
+  unmap(value) {
+    return value.toLowerCase() as "debug" | "info" | "warn" | "error";
+  },
+});
+~~~~
+
+When a custom domain is needed, keep the validation in a value parser so help,
+errors, defaults, prompts, and completion all see the same typed value.
 
 ~~~~ typescript
 import { message } from "@optique/core/message";