@optique/core 1.3.6 → 1.3.7-dev.3001

package/dist/primitives.cjs

@@ -1803,16 +1803,29 @@ function command(name, parser, options = {}) {
 * // mycli --debug --foo bar
 * // → { debug: true, extra: ["--foo", "bar"] }
 *
-* // greedy format: captures all remaining tokens
-* const parser = command("exec", object({
-*   container: argument(string()),
-*   args: passThrough({ format: "greedy" }),
-* }));
+* // greedy format: require a program name before capturing the rest
+* const parser = command("exec", map(
+*   seq(
+*     argument(string({ metavar: "PROGRAM" })),
+*     passThrough({ format: "greedy" }),
+*   ),
+*   ([program, args]) => ({ program, args }),
+* ));
 *
-* // myproxy exec mycontainer --verbose -it bash
-* // → { container: "mycontainer", args: ["--verbose", "-it", "bash"] }
+* // myproxy exec my-program --help
+* // → { program: "my-program", args: ["--help"] }
 * ```
 *
+* With built-in help enabled, `myproxy exec --help` displays help because `seq()`
+* does not reach pass-through until the program name is parsed. After the
+* program name, greedy capture can consume remaining tokens, including
+* `--help`, so they can be forwarded. Putting this parser last in an `object()`
+* does not establish the same boundary: fields are tried by priority, not
+* declaration order.
+* An immediate `--` after the program name is consumed by `seq()` as an
+* options terminator before greedy capture starts. Once capture starts,
+* subsequent `--` tokens are kept.
+*
 * @since 0.8.0
 */
 function passThrough(options = {}) {

package/dist/primitives.d.cts

@@ -584,16 +584,29 @@ interface PassThroughOptions {
  * // mycli --debug --foo bar
  * // → { debug: true, extra: ["--foo", "bar"] }
  *
- * // greedy format: captures all remaining tokens
- * const parser = command("exec", object({
- *   container: argument(string()),
- *   args: passThrough({ format: "greedy" }),
- * }));
+ * // greedy format: require a program name before capturing the rest
+ * const parser = command("exec", map(
+ *   seq(
+ *     argument(string({ metavar: "PROGRAM" })),
+ *     passThrough({ format: "greedy" }),
+ *   ),
+ *   ([program, args]) => ({ program, args }),
+ * ));
  *
- * // myproxy exec mycontainer --verbose -it bash
- * // → { container: "mycontainer", args: ["--verbose", "-it", "bash"] }
+ * // myproxy exec my-program --help
+ * // → { program: "my-program", args: ["--help"] }
  * ```
  *
+ * With built-in help enabled, `myproxy exec --help` displays help because `seq()`
+ * does not reach pass-through until the program name is parsed. After the
+ * program name, greedy capture can consume remaining tokens, including
+ * `--help`, so they can be forwarded. Putting this parser last in an `object()`
+ * does not establish the same boundary: fields are tried by priority, not
+ * declaration order.
+ * An immediate `--` after the program name is consumed by `seq()` as an
+ * options terminator before greedy capture starts. Once capture starts,
+ * subsequent `--` tokens are kept.
+ *
  * @since 0.8.0
  */
 declare function passThrough(options?: PassThroughOptions): FluentParser<"sync", readonly string[], readonly string[]>;

package/dist/primitives.d.ts

@@ -584,16 +584,29 @@ interface PassThroughOptions {
  * // mycli --debug --foo bar
  * // → { debug: true, extra: ["--foo", "bar"] }
  *
- * // greedy format: captures all remaining tokens
- * const parser = command("exec", object({
- *   container: argument(string()),
- *   args: passThrough({ format: "greedy" }),
- * }));
+ * // greedy format: require a program name before capturing the rest
+ * const parser = command("exec", map(
+ *   seq(
+ *     argument(string({ metavar: "PROGRAM" })),
+ *     passThrough({ format: "greedy" }),
+ *   ),
+ *   ([program, args]) => ({ program, args }),
+ * ));
  *
- * // myproxy exec mycontainer --verbose -it bash
- * // → { container: "mycontainer", args: ["--verbose", "-it", "bash"] }
+ * // myproxy exec my-program --help
+ * // → { program: "my-program", args: ["--help"] }
  * ```
  *
+ * With built-in help enabled, `myproxy exec --help` displays help because `seq()`
+ * does not reach pass-through until the program name is parsed. After the
+ * program name, greedy capture can consume remaining tokens, including
+ * `--help`, so they can be forwarded. Putting this parser last in an `object()`
+ * does not establish the same boundary: fields are tried by priority, not
+ * declaration order.
+ * An immediate `--` after the program name is consumed by `seq()` as an
+ * options terminator before greedy capture starts. Once capture starts,
+ * subsequent `--` tokens are kept.
+ *
  * @since 0.8.0
  */
 declare function passThrough(options?: PassThroughOptions): FluentParser<"sync", readonly string[], readonly string[]>;

package/dist/primitives.js

@@ -1803,16 +1803,29 @@ function command(name, parser, options = {}) {
 * // mycli --debug --foo bar
 * // → { debug: true, extra: ["--foo", "bar"] }
 *
-* // greedy format: captures all remaining tokens
-* const parser = command("exec", object({
-*   container: argument(string()),
-*   args: passThrough({ format: "greedy" }),
-* }));
+* // greedy format: require a program name before capturing the rest
+* const parser = command("exec", map(
+*   seq(
+*     argument(string({ metavar: "PROGRAM" })),
+*     passThrough({ format: "greedy" }),
+*   ),
+*   ([program, args]) => ({ program, args }),
+* ));
 *
-* // myproxy exec mycontainer --verbose -it bash
-* // → { container: "mycontainer", args: ["--verbose", "-it", "bash"] }
+* // myproxy exec my-program --help
+* // → { program: "my-program", args: ["--help"] }
 * ```
 *
+* With built-in help enabled, `myproxy exec --help` displays help because `seq()`
+* does not reach pass-through until the program name is parsed. After the
+* program name, greedy capture can consume remaining tokens, including
+* `--help`, so they can be forwarded. Putting this parser last in an `object()`
+* does not establish the same boundary: fields are tried by priority, not
+* declaration order.
+* An immediate `--` after the program name is consumed by `seq()` as an
+* options terminator before greedy capture starts. Once capture starts,
+* subsequent `--` tokens are kept.
+*
 * @since 0.8.0
 */
 function passThrough(options = {}) {

package/package.json

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

package/skills/optique/SKILL.md

@@ -243,8 +243,8 @@ Common mistakes checklist
     `withDefault(..., false)` for ordinary optional flags.
  -  Do not expect `multiple(p)` to fail when absent; it returns `[]`. Wrap with
     `nonEmpty()` when at least one value is required.
- -  Do not confuse free-order parsing with `seq()`. Most constructs let child
-    parsers compete by priority; use `seq()` only for truly ordered grammars.
+ -  For ordered grammars, use `seq()`; `object()` fields compete by priority.
+    In wrappers, require the program name before greedy `passThrough()`.
  -  Do not concatenate plain strings for errors or descriptions. Use structured
     `message` values.
  -  Register contexts for `bindEnv()`, `bindConfig()`, `bindDerivedDefault()`,