@optique/core 1.3.5 → 1.3.7-dev.3001

package/dist/primitives.js

@@ -6,6 +6,7 @@ import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./internal/
 import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./internal/dependency.js";
 import { effectfulSchedulingNodesKey, exclusiveSourceScopeKey, includeSourceFailureChain, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, sourceCollectionExpansionKey } from "./dependency-runtime.js";
 import { getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedInitialState, normalizeInjectedAnnotationState } from "./annotation-state.js";
+import { joinedFileSuggestion } from "./internal/joined-file-suggestion.js";
 import { getCommandDocMetadata, withCommandDocMetadata } from "./internal/command-doc-metadata.js";
 import { defineKnownCompletion, defineOptionMatch, definePassThroughPriority, getOptionMatch, getPassThroughFailure, getPassThroughPriority } from "./internal/passthrough.js";
 import { hiddenCommandAliasesKey } from "./internal/command-alias.js";
@@ -253,33 +254,33 @@ function* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry,
 	}
 	yield* valueParser.suggest(prefix);
 }
+/** Returns the joined prefix accepted by option parsing. */
+function joinedOptionPrefix(names, input) {
+	return names.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2).map((name) => name + (name.startsWith("/") ? ":" : "=")).find((prefix) => input.startsWith(prefix));
+}
 /**
 * Internal sync helper for option suggest functionality.
 * @internal
 */
 function* suggestOptionSync(optionNames$1, valueParser, hidden, description, context, prefix) {
 	if (hidden || context.optionsTerminated) return;
-	const equalsIndex = prefix.indexOf("=");
-	if (equalsIndex >= 0) {
-		const optionPart = prefix.slice(0, equalsIndex);
-		const valuePart = prefix.slice(equalsIndex + 1);
+	const expectingValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
+	const joinedPrefix = joinedOptionPrefix(optionNames$1, prefix);
+	if (joinedPrefix !== void 0 && !expectingValue) {
+		const optionPart = joinedPrefix.slice(0, -1);
+		const valuePart = prefix.slice(joinedPrefix.length);
 		if (optionNames$1.includes(optionPart)) {
 			if (valueParser && valueParser.suggest) {
 				const valueSuggestions = getSuggestionsWithDependency(valueParser, valuePart, context.dependencyRegistry, context.exec);
 				for (const suggestion of valueSuggestions) if (suggestion.kind === "literal") yield {
 					kind: "literal",
-					text: `${optionPart}=${suggestion.text}`,
-					description: suggestion.description
-				};
-				else yield {
-					kind: "literal",
-					text: `${optionPart}=${suggestion.pattern || ""}`,
+					text: `${joinedPrefix}${suggestion.text}`,
 					description: suggestion.description
 				};
+				else yield joinedFileSuggestion(joinedPrefix, suggestion, valuePart);
 			}
 		}
 	} else {
-		const expectingValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
 		if (!expectingValue && (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+"))) {
 			for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
 				if (prefix === "-" && optionName$1.length !== 2) continue;
@@ -344,27 +345,23 @@ async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependenc
 */
 async function* suggestOptionAsync(optionNames$1, valueParser, hidden, description, context, prefix) {
 	if (hidden || context.optionsTerminated) return;
-	const equalsIndex = prefix.indexOf("=");
-	if (equalsIndex >= 0) {
-		const optionPart = prefix.slice(0, equalsIndex);
-		const valuePart = prefix.slice(equalsIndex + 1);
+	const expectingValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
+	const joinedPrefix = joinedOptionPrefix(optionNames$1, prefix);
+	if (joinedPrefix !== void 0 && !expectingValue) {
+		const optionPart = joinedPrefix.slice(0, -1);
+		const valuePart = prefix.slice(joinedPrefix.length);
 		if (optionNames$1.includes(optionPart)) {
 			if (valueParser && valueParser.suggest) {
 				const valueSuggestions = getSuggestionsWithDependencyAsync(valueParser, valuePart, context.dependencyRegistry, context.exec);
 				for await (const suggestion of valueSuggestions) if (suggestion.kind === "literal") yield {
 					kind: "literal",
-					text: `${optionPart}=${suggestion.text}`,
-					description: suggestion.description
-				};
-				else yield {
-					kind: "literal",
-					text: `${optionPart}=${suggestion.pattern || ""}`,
+					text: `${joinedPrefix}${suggestion.text}`,
 					description: suggestion.description
 				};
+				else yield joinedFileSuggestion(joinedPrefix, suggestion, valuePart);
 			}
 		}
 	} else {
-		const expectingValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
 		if (!expectingValue && (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+"))) {
 			for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
 				if (prefix === "-" && optionName$1.length !== 2) continue;
@@ -1806,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/suggestion.cjs

@@ -1,5 +1,6 @@
 const require_usage = require('./usage.cjs');
 const require_message = require('./message.cjs');
+const require_joined_file_suggestion = require('./internal/joined-file-suggestion.cjs');
 
 //#region src/suggestion.ts
 /**
@@ -322,22 +323,27 @@ function appendValueHint(base, input, candidates, options) {
 *
 * For literal suggestions, the text itself is used as the key.
 * For file suggestions, a composite key is created from the type,
-* extensions, and pattern.
+* extensions, pattern, and insertion prefix.
 *
 * @param suggestion The suggestion to create a key for
 * @returns A string key that uniquely identifies this suggestion
 * @internal
 */
 function getSuggestionKey(suggestion) {
-	if (suggestion.kind === "literal") return suggestion.text;
-	return `__FILE__:${suggestion.type}:${suggestion.extensions?.toSorted().join(",") ?? ""}:${suggestion.pattern ?? ""}`;
+	if (suggestion.kind === "literal") return `literal:${suggestion.text}`;
+	return `file:${JSON.stringify([
+		suggestion.type,
+		suggestion.extensions?.toSorted().join(",") ?? "",
+		suggestion.pattern ?? "",
+		suggestion.prefix ?? ""
+	])}`;
 }
 /**
 * Removes duplicate suggestions from an array while preserving order.
 *
 * Suggestions are considered duplicates if they have the same key:
 * - Literal suggestions: same text
-* - File suggestions: same type, extensions, and pattern
+* - File suggestions: same type, extensions, pattern, and insertion prefix
 *
 * The first occurrence of each unique suggestion is kept.  For file
 * suggestions, `includeHidden` is merged across duplicates: if any
@@ -370,7 +376,8 @@ function deduplicateSuggestions(suggestions) {
 		if (existing == null) {
 			entries.set(key, suggestion);
 			order.push(key);
-		} else if (suggestion.kind === "file" && existing.kind === "file" && suggestion.includeHidden === true && existing.includeHidden !== true) entries.set(key, {
+		} else if (suggestion.kind === "literal" && existing.kind === "literal") require_joined_file_suggestion.mergeJoinedFileSuggestions(existing, suggestion);
+		else if (suggestion.kind === "file" && existing.kind === "file" && suggestion.includeHidden === true && existing.includeHidden !== true) entries.set(key, {
 			...existing,
 			includeHidden: true
 		});

package/dist/suggestion.d.cts

@@ -202,7 +202,7 @@ declare function appendValueHint(base: Message, input: string, candidates: reado
  *
  * Suggestions are considered duplicates if they have the same key:
  * - Literal suggestions: same text
- * - File suggestions: same type, extensions, and pattern
+ * - File suggestions: same type, extensions, pattern, and insertion prefix
  *
  * The first occurrence of each unique suggestion is kept.  For file
  * suggestions, `includeHidden` is merged across duplicates: if any

package/dist/suggestion.d.ts

@@ -202,7 +202,7 @@ declare function appendValueHint(base: Message, input: string, candidates: reado
  *
  * Suggestions are considered duplicates if they have the same key:
  * - Literal suggestions: same text
- * - File suggestions: same type, extensions, and pattern
+ * - File suggestions: same type, extensions, pattern, and insertion prefix
  *
  * The first occurrence of each unique suggestion is kept.  For file
  * suggestions, `includeHidden` is merged across duplicates: if any

package/dist/suggestion.js

@@ -1,5 +1,6 @@
 import { extractCommandNames, extractOptionNames, isSuggestionHidden } from "./usage.js";
 import { lineBreak, message, optionName, text, value } from "./message.js";
+import { mergeJoinedFileSuggestions } from "./internal/joined-file-suggestion.js";
 
 //#region src/suggestion.ts
 /**
@@ -322,22 +323,27 @@ function appendValueHint(base, input, candidates, options) {
 *
 * For literal suggestions, the text itself is used as the key.
 * For file suggestions, a composite key is created from the type,
-* extensions, and pattern.
+* extensions, pattern, and insertion prefix.
 *
 * @param suggestion The suggestion to create a key for
 * @returns A string key that uniquely identifies this suggestion
 * @internal
 */
 function getSuggestionKey(suggestion) {
-	if (suggestion.kind === "literal") return suggestion.text;
-	return `__FILE__:${suggestion.type}:${suggestion.extensions?.toSorted().join(",") ?? ""}:${suggestion.pattern ?? ""}`;
+	if (suggestion.kind === "literal") return `literal:${suggestion.text}`;
+	return `file:${JSON.stringify([
+		suggestion.type,
+		suggestion.extensions?.toSorted().join(",") ?? "",
+		suggestion.pattern ?? "",
+		suggestion.prefix ?? ""
+	])}`;
 }
 /**
 * Removes duplicate suggestions from an array while preserving order.
 *
 * Suggestions are considered duplicates if they have the same key:
 * - Literal suggestions: same text
-* - File suggestions: same type, extensions, and pattern
+* - File suggestions: same type, extensions, pattern, and insertion prefix
 *
 * The first occurrence of each unique suggestion is kept.  For file
 * suggestions, `includeHidden` is merged across duplicates: if any
@@ -370,7 +376,8 @@ function deduplicateSuggestions(suggestions) {
 		if (existing == null) {
 			entries.set(key, suggestion);
 			order.push(key);
-		} else if (suggestion.kind === "file" && existing.kind === "file" && suggestion.includeHidden === true && existing.includeHidden !== true) entries.set(key, {
+		} else if (suggestion.kind === "literal" && existing.kind === "literal") mergeJoinedFileSuggestions(existing, suggestion);
+		else if (suggestion.kind === "file" && existing.kind === "file" && suggestion.includeHidden === true && existing.includeHidden !== true) entries.set(key, {
 			...existing,
 			includeHidden: true
 		});

package/dist/valueparser.cjs

@@ -960,7 +960,8 @@ function prefixKeyValueSuggestion(suggestion, prefix, suffix = "") {
 	const text$1 = `${prefix}${textValue}${suffix}`;
 	if (suggestion.kind === "file" && suffix === "") return {
 		...suggestion,
-		pattern: text$1
+		pattern: text$1,
+		prefix: `${prefix}${suggestion.prefix ?? ""}`
 	};
 	return suggestion.description == null ? {
 		kind: "literal",

package/dist/valueparser.js

@@ -960,7 +960,8 @@ function prefixKeyValueSuggestion(suggestion, prefix, suffix = "") {
 	const text$1 = `${prefix}${textValue}${suffix}`;
 	if (suggestion.kind === "file" && suffix === "") return {
 		...suggestion,
-		pattern: text$1
+		pattern: text$1,
+		prefix: `${prefix}${suggestion.prefix ?? ""}`
 	};
 	return suggestion.description == null ? {
 		kind: "literal",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.5",
+  "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.5",
+    "@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()`,