@optique/core 1.2.11 → 1.2.13

package/dist/constructs.cjs

@@ -514,12 +514,16 @@ function analyzeNoMatchContext(parsers) {
 * construction. This is a programmer error, not a user error.
 */
 var DuplicateOptionError = class extends Error {
+	/** The option name shared by multiple fields. */
+	optionName;
+	/** The fields declaring the option. */
+	sources;
 	constructor(optionName$1, sources) {
 		const sourceNames = sources.map((s) => typeof s === "symbol" ? s.description ?? s.toString() : s);
 		super(`Duplicate option name "${optionName$1}" found in fields: ${sourceNames.join(", ")}. Each option name must be unique within a parser combinator.`);
+		this.name = "DuplicateOptionError";
 		this.optionName = optionName$1;
 		this.sources = sources;
-		this.name = "DuplicateOptionError";
 	}
 };
 /**
@@ -527,6 +531,8 @@ var DuplicateOptionError = class extends Error {
 * during parser construction. This is a programmer error, not a user error.
 */
 var DuplicateCommandNameError = class extends TypeError {
+	commandName;
+	sources;
 	constructor(commandName, sources) {
 		const sourceNames = sources.map((s) => typeof s === "symbol" ? s.description ?? s.toString() : s);
 		super(`Duplicate command name "${commandName}" found in parsers: ${sourceNames.join(", ")}. Each command name or alias must be unique within active parser alternatives.`);

package/dist/constructs.d.cts

@@ -103,7 +103,9 @@ interface OrErrorOptions {
  * construction. This is a programmer error, not a user error.
  */
 declare class DuplicateOptionError extends Error {
+  /** The option name shared by multiple fields. */
   readonly optionName: string;
+  /** The fields declaring the option. */
   readonly sources: readonly (string | symbol)[];
   constructor(optionName: string, sources: readonly (string | symbol)[]);
 }

package/dist/constructs.d.ts

@@ -103,7 +103,9 @@ interface OrErrorOptions {
  * construction. This is a programmer error, not a user error.
  */
 declare class DuplicateOptionError extends Error {
+  /** The option name shared by multiple fields. */
   readonly optionName: string;
+  /** The fields declaring the option. */
   readonly sources: readonly (string | symbol)[];
   constructor(optionName: string, sources: readonly (string | symbol)[]);
 }

package/dist/constructs.js

@@ -514,12 +514,16 @@ function analyzeNoMatchContext(parsers) {
 * construction. This is a programmer error, not a user error.
 */
 var DuplicateOptionError = class extends Error {
+	/** The option name shared by multiple fields. */
+	optionName;
+	/** The fields declaring the option. */
+	sources;
 	constructor(optionName$1, sources) {
 		const sourceNames = sources.map((s) => typeof s === "symbol" ? s.description ?? s.toString() : s);
 		super(`Duplicate option name "${optionName$1}" found in fields: ${sourceNames.join(", ")}. Each option name must be unique within a parser combinator.`);
+		this.name = "DuplicateOptionError";
 		this.optionName = optionName$1;
 		this.sources = sources;
-		this.name = "DuplicateOptionError";
 	}
 };
 /**
@@ -527,6 +531,8 @@ var DuplicateOptionError = class extends Error {
 * during parser construction. This is a programmer error, not a user error.
 */
 var DuplicateCommandNameError = class extends TypeError {
+	commandName;
+	sources;
 	constructor(commandName, sources) {
 		const sourceNames = sources.map((s) => typeof s === "symbol" ? s.description ?? s.toString() : s);
 		super(`Duplicate command name "${commandName}" found in parsers: ${sourceNames.join(", ")}. Each command name or alias must be unique within active parser alternatives.`);

package/dist/internal/joined-file-suggestion.cjs

@@ -0,0 +1,73 @@
+
+//#region src/internal/joined-file-suggestion.ts
+const joinedFiles = /* @__PURE__ */ new WeakMap();
+/**
+* Keeps a joined file fallback's origin available to the Bash encoder.
+* Other shells retain the existing literal representation.
+* @param prefix The option name and delimiter.
+* @param file The original file suggestion.
+* @param value The value prefix being completed.
+* @returns The literal fallback with private file metadata.
+* @internal
+*/
+function joinedFileSuggestion(prefix, file, value) {
+	const literal = {
+		kind: "literal",
+		text: prefix + (file.pattern ?? ""),
+		description: file.description
+	};
+	joinedFiles.set(literal, {
+		files: [{
+			prefix,
+			file: file.pattern === value && !/[?*]/.test(value) && !(file.prefix != null && file.prefix !== "" && value.startsWith(file.prefix)) ? {
+				...file,
+				pattern: void 0
+			} : file
+		}],
+		literal: false
+	});
+	return literal;
+}
+/**
+* Retrieves the originating file suggestion for a joined literal fallback.
+* @param suggestion The suggestion to inspect.
+* @returns Its private file metadata, if present.
+* @internal
+*/
+function getJoinedFileSuggestion(suggestion) {
+	return joinedFiles.get(suggestion);
+}
+/**
+* Preserves file origins when equal literal fallbacks are deduplicated.
+* @param target The retained suggestion.
+* @param source The duplicate suggestion.
+* @internal
+*/
+function mergeJoinedFileSuggestions(target, source) {
+	const a = joinedFiles.get(target);
+	const b = joinedFiles.get(source);
+	if (a === void 0 && b === void 0) return;
+	const files = [...a?.files ?? [], ...b?.files ?? []];
+	const seen = /* @__PURE__ */ new Set();
+	joinedFiles.set(target, {
+		literal: (a?.literal ?? true) || (b?.literal ?? true),
+		files: files.filter(({ prefix, file }) => {
+			const key = JSON.stringify([
+				prefix,
+				file.type,
+				file.pattern,
+				file.prefix,
+				file.includeHidden === true,
+				file.extensions?.toSorted()
+			]);
+			if (seen.has(key)) return false;
+			seen.add(key);
+			return true;
+		})
+	});
+}
+
+//#endregion
+exports.getJoinedFileSuggestion = getJoinedFileSuggestion;
+exports.joinedFileSuggestion = joinedFileSuggestion;
+exports.mergeJoinedFileSuggestions = mergeJoinedFileSuggestions;

package/dist/internal/joined-file-suggestion.js

@@ -0,0 +1,70 @@
+//#region src/internal/joined-file-suggestion.ts
+const joinedFiles = /* @__PURE__ */ new WeakMap();
+/**
+* Keeps a joined file fallback's origin available to the Bash encoder.
+* Other shells retain the existing literal representation.
+* @param prefix The option name and delimiter.
+* @param file The original file suggestion.
+* @param value The value prefix being completed.
+* @returns The literal fallback with private file metadata.
+* @internal
+*/
+function joinedFileSuggestion(prefix, file, value) {
+	const literal = {
+		kind: "literal",
+		text: prefix + (file.pattern ?? ""),
+		description: file.description
+	};
+	joinedFiles.set(literal, {
+		files: [{
+			prefix,
+			file: file.pattern === value && !/[?*]/.test(value) && !(file.prefix != null && file.prefix !== "" && value.startsWith(file.prefix)) ? {
+				...file,
+				pattern: void 0
+			} : file
+		}],
+		literal: false
+	});
+	return literal;
+}
+/**
+* Retrieves the originating file suggestion for a joined literal fallback.
+* @param suggestion The suggestion to inspect.
+* @returns Its private file metadata, if present.
+* @internal
+*/
+function getJoinedFileSuggestion(suggestion) {
+	return joinedFiles.get(suggestion);
+}
+/**
+* Preserves file origins when equal literal fallbacks are deduplicated.
+* @param target The retained suggestion.
+* @param source The duplicate suggestion.
+* @internal
+*/
+function mergeJoinedFileSuggestions(target, source) {
+	const a = joinedFiles.get(target);
+	const b = joinedFiles.get(source);
+	if (a === void 0 && b === void 0) return;
+	const files = [...a?.files ?? [], ...b?.files ?? []];
+	const seen = /* @__PURE__ */ new Set();
+	joinedFiles.set(target, {
+		literal: (a?.literal ?? true) || (b?.literal ?? true),
+		files: files.filter(({ prefix, file }) => {
+			const key = JSON.stringify([
+				prefix,
+				file.type,
+				file.pattern,
+				file.prefix,
+				file.includeHidden === true,
+				file.extensions?.toSorted()
+			]);
+			if (seen.has(key)) return false;
+			seen.add(key);
+			return true;
+		})
+	});
+}
+
+//#endregion
+export { getJoinedFileSuggestion, joinedFileSuggestion, mergeJoinedFileSuggestions };

package/dist/internal/parser.d.cts

@@ -630,6 +630,14 @@ type Suggestion = {
    * The current prefix/pattern for fallback when native completion is unavailable.
    */
   readonly pattern?: string;
+  /**
+   * Literal text at the start of `pattern` that is preserved on insertion
+   * but excluded from native filesystem matching, such as `output=`.
+   * Shell adapters ignore it if it does not lead both the pattern and
+   * the current word.  Regenerate installed scripts to use this field.
+   * @since 1.1.13
+   */
+  readonly prefix?: string;
   /**
    * The type of file system entries to complete.
    */

package/dist/internal/parser.d.ts

@@ -630,6 +630,14 @@ type Suggestion = {
    * The current prefix/pattern for fallback when native completion is unavailable.
    */
   readonly pattern?: string;
+  /**
+   * Literal text at the start of `pattern` that is preserved on insertion
+   * but excluded from native filesystem matching, such as `output=`.
+   * Shell adapters ignore it if it does not lead both the pattern and
+   * the current word.  Regenerate installed scripts to use this field.
+   * @since 1.1.13
+   */
+  readonly prefix?: string;
   /**
    * The type of file system entries to complete.
    */

package/dist/modifiers.cjs

@@ -3,6 +3,7 @@ const require_message = require('./message.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_internal_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
+const require_joined_file_suggestion = require('./internal/joined-file-suggestion.cjs');
 const require_command_doc_metadata = require('./internal/command-doc-metadata.cjs');
 const require_passthrough = require('./internal/passthrough.cjs');
 const require_execution_context = require('./execution-context.cjs');
@@ -1482,6 +1483,7 @@ function multiple(parser, options = {}) {
 					"file",
 					suggestion.type,
 					suggestion.pattern ?? "",
+					suggestion.prefix ?? "",
 					suggestion.includeHidden === true,
 					suggestion.extensions == null ? "" : suggestion.extensions.toSorted().join("\0"),
 					description
@@ -1489,14 +1491,16 @@ function multiple(parser, options = {}) {
 			};
 			return require_mode_dispatch.dispatchIterableByMode(parser.mode, function* () {
 				const selectedValues = collectSelectedValuesSync();
-				const emitted = /* @__PURE__ */ new Set();
+				const emitted = /* @__PURE__ */ new Map();
 				const yieldUnique = function* (suggestions) {
 					for (const s of suggestions) {
 						const key = suggestionKey(s);
-						if (shouldInclude(selectedValues, s) && !emitted.has(key)) {
-							emitted.add(key);
+						if (!shouldInclude(selectedValues, s)) continue;
+						const existing = emitted.get(key);
+						if (existing === void 0) {
+							emitted.set(key, s);
 							yield s;
-						}
+						} else require_joined_file_suggestion.mergeJoinedFileSuggestions(existing, s);
 					}
 				};
 				let shouldTryFallback = false;
@@ -1509,14 +1513,16 @@ function multiple(parser, options = {}) {
 				if (shouldTryFallback) yield* yieldUnique(syncParser.suggest(require_execution_context.withChildContext(context, itemIndex, suggestFallbackState), prefix));
 			}, async function* () {
 				const selectedValues = await collectSelectedValuesAsync();
-				const emitted = /* @__PURE__ */ new Set();
+				const emitted = /* @__PURE__ */ new Map();
 				const yieldUnique = async function* (suggestions) {
 					for await (const s of suggestions) {
 						const key = suggestionKey(s);
-						if (shouldInclude(selectedValues, s) && !emitted.has(key)) {
-							emitted.add(key);
+						if (!shouldInclude(selectedValues, s)) continue;
+						const existing = emitted.get(key);
+						if (existing === void 0) {
+							emitted.set(key, s);
 							yield s;
-						}
+						} else require_joined_file_suggestion.mergeJoinedFileSuggestions(existing, s);
 					}
 				};
 				let shouldTryFallback = false;

package/dist/modifiers.js

@@ -3,6 +3,7 @@ import { formatMessage, message, text } from "./message.js";
 import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
 import { defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getOwnParseLanes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
+import { mergeJoinedFileSuggestions } from "./internal/joined-file-suggestion.js";
 import { getCommandDocMetadata, withCommandDocMetadata } from "./internal/command-doc-metadata.js";
 import { defineKnownCompletionLookup, defineOptionMatch, definePassThroughPriority, getKnownCompletion, getOptionMatch, getPassThroughPriority } from "./internal/passthrough.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
@@ -1482,6 +1483,7 @@ function multiple(parser, options = {}) {
 					"file",
 					suggestion.type,
 					suggestion.pattern ?? "",
+					suggestion.prefix ?? "",
 					suggestion.includeHidden === true,
 					suggestion.extensions == null ? "" : suggestion.extensions.toSorted().join("\0"),
 					description
@@ -1489,14 +1491,16 @@ function multiple(parser, options = {}) {
 			};
 			return dispatchIterableByMode(parser.mode, function* () {
 				const selectedValues = collectSelectedValuesSync();
-				const emitted = /* @__PURE__ */ new Set();
+				const emitted = /* @__PURE__ */ new Map();
 				const yieldUnique = function* (suggestions) {
 					for (const s of suggestions) {
 						const key = suggestionKey(s);
-						if (shouldInclude(selectedValues, s) && !emitted.has(key)) {
-							emitted.add(key);
+						if (!shouldInclude(selectedValues, s)) continue;
+						const existing = emitted.get(key);
+						if (existing === void 0) {
+							emitted.set(key, s);
 							yield s;
-						}
+						} else mergeJoinedFileSuggestions(existing, s);
 					}
 				};
 				let shouldTryFallback = false;
@@ -1509,14 +1513,16 @@ function multiple(parser, options = {}) {
 				if (shouldTryFallback) yield* yieldUnique(syncParser.suggest(withChildContext(context, itemIndex, suggestFallbackState), prefix));
 			}, async function* () {
 				const selectedValues = await collectSelectedValuesAsync();
-				const emitted = /* @__PURE__ */ new Set();
+				const emitted = /* @__PURE__ */ new Map();
 				const yieldUnique = async function* (suggestions) {
 					for await (const s of suggestions) {
 						const key = suggestionKey(s);
-						if (shouldInclude(selectedValues, s) && !emitted.has(key)) {
-							emitted.add(key);
+						if (!shouldInclude(selectedValues, s)) continue;
+						const existing = emitted.get(key);
+						if (existing === void 0) {
+							emitted.set(key, s);
 							yield s;
-						}
+						} else mergeJoinedFileSuggestions(existing, s);
 					}
 				};
 				let shouldTryFallback = false;

package/dist/primitives.cjs

@@ -6,6 +6,7 @@ const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_internal_dependency = require('./internal/dependency.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
+const require_joined_file_suggestion = require('./internal/joined-file-suggestion.cjs');
 const require_command_doc_metadata = require('./internal/command-doc-metadata.cjs');
 const require_passthrough = require('./internal/passthrough.cjs');
 const require_command_alias = require('./internal/command-alias.cjs');
@@ -247,33 +248,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) return;
-	const equalsIndex = prefix.indexOf("=");
-	if (equalsIndex >= 0) {
-		const optionPart = prefix.slice(0, equalsIndex);
-		const valuePart = prefix.slice(equalsIndex + 1);
+	if (hidden || context.optionsTerminated) return;
+	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 require_joined_file_suggestion.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;
@@ -337,28 +338,24 @@ async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependenc
 * @internal
 */
 async function* suggestOptionAsync(optionNames$1, valueParser, hidden, description, context, prefix) {
-	if (hidden) return;
-	const equalsIndex = prefix.indexOf("=");
-	if (equalsIndex >= 0) {
-		const optionPart = prefix.slice(0, equalsIndex);
-		const valuePart = prefix.slice(equalsIndex + 1);
+	if (hidden || context.optionsTerminated) return;
+	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 require_joined_file_suggestion.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;
@@ -916,8 +913,8 @@ function flag(...args) {
 				error: require_message.message`${require_message.optionNames(optionNames$1)}: ${state.error}`
 			};
 		},
-		suggest(_context, prefix) {
-			if (require_usage.isSuggestionHidden(options.hidden)) return [];
+		suggest(context, prefix) {
+			if (require_usage.isSuggestionHidden(options.hidden) || context.optionsTerminated) return [];
 			const suggestions = [];
 			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+")) {
 				for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {

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 { replayDerivedParser, replayDerivedParserAsync } 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";
@@ -247,33 +248,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) return;
-	const equalsIndex = prefix.indexOf("=");
-	if (equalsIndex >= 0) {
-		const optionPart = prefix.slice(0, equalsIndex);
-		const valuePart = prefix.slice(equalsIndex + 1);
+	if (hidden || context.optionsTerminated) return;
+	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;
@@ -337,28 +338,24 @@ async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependenc
 * @internal
 */
 async function* suggestOptionAsync(optionNames$1, valueParser, hidden, description, context, prefix) {
-	if (hidden) return;
-	const equalsIndex = prefix.indexOf("=");
-	if (equalsIndex >= 0) {
-		const optionPart = prefix.slice(0, equalsIndex);
-		const valuePart = prefix.slice(equalsIndex + 1);
+	if (hidden || context.optionsTerminated) return;
+	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;
@@ -916,8 +913,8 @@ function flag(...args) {
 				error: message`${optionNames(optionNames$1)}: ${state.error}`
 			};
 		},
-		suggest(_context, prefix) {
-			if (isSuggestionHidden(options.hidden)) return [];
+		suggest(context, prefix) {
+			if (isSuggestionHidden(options.hidden) || context.optionsTerminated) return [];
 			const suggestions = [];
 			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+")) {
 				for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {

package/dist/suggestion.cjs

@@ -1,5 +1,6 @@
 const require_message = require('./message.cjs');
 const require_usage = require('./usage.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