@optique/core 1.1.12 → 1.1.13-dev.2823

package/dist/completion.cjs

@@ -40,6 +40,12 @@ function validateProgramName(programName) {
 function encodePattern(pattern) {
 	return pattern.replace(/%/g, "%25").replace(/:/g, "%3A");
 }
+/** Encodes optional literal insertion metadata without changing old directives. */
+function encodeFilePrefix(suggestion) {
+	const prefix = suggestion.prefix ?? "";
+	if (prefix === "" || !(suggestion.pattern ?? "").startsWith(prefix) || sanitizeForTransport(prefix) !== prefix) return "";
+	return `:${encodePattern(prefix)}`;
+}
 function encodeExtensions(extensions) {
 	return extensions?.map((ext) => ext.replace(/^\./, "")).join(",") ?? "";
 }
@@ -69,13 +75,32 @@ function _${programName} () {
   COMPREPLY=()
   local current="\${COMP_WORDS[COMP_CWORD]}"
   local prev=("\${COMP_WORDS[@]:1:COMP_CWORD-1}")
+  local __prefix_aware=0
   while IFS= read -r line; do
     if [[ "$line" == __FILE__:* ]]; then
       # Parse file completion directive: __FILE__:type:extensions:pattern:hidden
-      IFS=':' read -r _ type extensions pattern hidden <<< "$line"
+      local insertion_prefix
+      IFS=':' read -r _ type extensions pattern hidden insertion_prefix <<< "$line"
       extensions="\${extensions//,\\./,}"; extensions="\${extensions#.}"
       pattern="\${pattern//%3A/:}"; pattern="\${pattern//%25/%}"
 
+      insertion_prefix="\${insertion_prefix//%3A/:}"; insertion_prefix="\${insertion_prefix//%25/%}"
+      local __saved_current="$current"
+      local -a __saved_reply=()
+      if [[ -n "$insertion_prefix" && "$pattern" == "$insertion_prefix"* && "$current" == "$insertion_prefix"* ]]; then
+        pattern="\${pattern#"$insertion_prefix"}"
+        current="\${current#"$insertion_prefix"}"
+        __prefix_aware=1
+      else
+        insertion_prefix=""
+      fi
+      # Inserted keys are not filesystem paths.  Once present, keep earlier
+      # replies out of later file filters; retain legacy-only aggregation.
+      if [[ "$__prefix_aware" == "1" ]]; then
+        __saved_reply=("\${COMPREPLY[@]}")
+        COMPREPLY=()
+      fi
+
       # Save and adjust glob/shell options for safe file completion
       local __dotglob_was_set=0 __failglob_was_set=0 __noglob_was_set=0
       local __globignore_was_set=0 __saved_globignore="\${GLOBIGNORE-}"
@@ -274,6 +299,16 @@ function _${programName} () {
         done
         COMPREPLY=("\${filtered[@]}")
       fi
+      if [[ -n "$insertion_prefix" ]]; then
+        local __prefix_index
+        for __prefix_index in "\${!COMPREPLY[@]}"; do
+          COMPREPLY[$__prefix_index]="$insertion_prefix\${COMPREPLY[$__prefix_index]}"
+        done
+      fi
+      if [[ "$__prefix_aware" == "1" ]]; then
+        COMPREPLY=("\${__saved_reply[@]}" "\${COMPREPLY[@]}")
+      fi
+      current="$__saved_current"
     else
       # Regular literal completion
       COMPREPLY+=("$line")
@@ -293,7 +328,7 @@ complete -F _${programName} -- ${programName}
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const pattern = encodePattern(suggestion.pattern ?? "");
-				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}`;
+				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}${encodeFilePrefix(suggestion)}`;
 			}
 			i++;
 		}
@@ -343,9 +378,20 @@ function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
 
       if [[ "\$value" == __FILE__:* ]]; then
         # Parse file completion directive: __FILE__:type:extensions:pattern:hidden
-        local type extensions pattern hidden
-        IFS=':' read -r _ type extensions pattern hidden <<< "\$value"
-        pattern="\${pattern//%3A/:}"; pattern="\${pattern//%25/%}"
+        local type extensions pattern hidden insertion_prefix
+        IFS=':' read -r _ type extensions pattern hidden insertion_prefix <<< "\$value"
+        local __decoded_pattern="\$pattern"
+        __decoded_pattern="\${__decoded_pattern//\\%3A/:}"; __decoded_pattern="\${__decoded_pattern//\\%25/%}"
+        insertion_prefix="\${insertion_prefix//\\%3A/:}"; insertion_prefix="\${insertion_prefix//\\%25/%}"
+        local __saved_prefix="\$PREFIX" __saved_iprefix="\$IPREFIX"
+        if [[ -n "\$insertion_prefix" && "\$__decoded_pattern" == "\$insertion_prefix"* && "\$PREFIX" == "\$insertion_prefix"* ]]; then
+          pattern="\${__decoded_pattern#"\$insertion_prefix"}"
+          PREFIX="\${PREFIX#"\$insertion_prefix"}"
+          IPREFIX="\$IPREFIX\$insertion_prefix"
+        else
+          # Preserve legacy decoding for directives without active metadata.
+          pattern="\${pattern//%3A/:}"; pattern="\${pattern//%25/%}"
+        fi
         has_file_completion=1
 
         # Native completion helpers expect normal zsh glob grouping even if
@@ -364,7 +410,6 @@ function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
         # _directories enumerate the pattern's directory instead of the
         # current word.  If the user has already typed beyond the pattern,
         # keep PREFIX unchanged for incremental narrowing.
-        local __saved_prefix="\$PREFIX"
         if [[ -n "\$pattern" ]]; then
           # Normalize leading ./ so that ./src/ma matches pattern src/
           local __norm_prefix="\${PREFIX#./}"
@@ -421,6 +466,7 @@ function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
 
         # Restore PREFIX and glob_dots to their previous state
         PREFIX="\$__saved_prefix"
+        IPREFIX="\$__saved_iprefix"
         if [[ "\$__was_sh_glob" == "1" ]]; then setopt sh_glob; else unsetopt sh_glob; fi
         if [[ "\$__was_glob_dots" == "1" ]]; then setopt glob_dots; else unsetopt glob_dots; fi
       else
@@ -463,7 +509,7 @@ fi
 			const hidden = suggestion.includeHidden ? "1" : "0";
 			const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
 			const pattern = encodePattern(suggestion.pattern ?? "");
-			yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\0${description}\0`;
+			yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}${encodeFilePrefix(suggestion)}\0${description}\0`;
 		}
 	}
 };
@@ -501,6 +547,21 @@ ${escapedArgs ? `    set -l output (${programName} ${escapedArgs} $prev $current
             set -l extensions $parts[3]
             set -l pattern (string replace -a '%25' '%' -- (string replace -a '%3A' ':' -- $parts[4]))
             set -l hidden $parts[5]
+            set -l insertion_prefix ""
+            if test (count $parts) -ge 6
+                set insertion_prefix (string replace -a '%25' '%' -- (string replace -a '%3A' ':' -- $parts[6]))
+            end
+            set -l saved_current "$current"
+            set -l prefix_length (string length -- "$insertion_prefix")
+            if test $prefix_length -gt 0
+                and test (string sub -l $prefix_length -- "$pattern") = "$insertion_prefix"
+                and test (string sub -l $prefix_length -- "$current") = "$insertion_prefix"
+                set -l start (math $prefix_length + 1)
+                set pattern (string sub -s $start -- "$pattern")
+                set current (string sub -s $start -- "$current")
+            else
+                set insertion_prefix ""
+            end
 
             # When a pattern is specified, use it as the glob base instead
             # of the current word.  If the user has already typed beyond the
@@ -722,8 +783,9 @@ ${escapedArgs ? `    set -l output (${programName} ${escapedArgs} $prev $current
 
             # Output file completions
             for item in $items
-                echo $item
+                echo "$insertion_prefix$item"
             end
+            set current "$saved_current"
         else
             # Regular literal completion - split by tab
             set -l parts (string split \\t -- $line)
@@ -753,7 +815,7 @@ complete -c ${programName} -f -a '(${functionName})'
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
-				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
+				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}${encodeFilePrefix(suggestion)}\t${description}`;
 			}
 			i++;
 		}
@@ -866,6 +928,10 @@ ${escapedArgs ? `    ^${programName} ${escapedArgs} ...$final_args | complete |
       let pattern = ($parts | get 3 | str replace -a '%3A' ':' | str replace -a '%25' '%')
       let hidden = ($parts | get 4) == '1'
 
+      let insertion_prefix = if ($parts | length) > 5 {
+        $parts | get 5 | str replace -a '%3A' ':' | str replace -a '%25' '%'
+      } else { "" }
+
       # Extract prefix from the last argument if it exists
       let prefix = if ($final_args | length) > 0 {
         $final_args | last
@@ -873,6 +939,11 @@ ${escapedArgs ? `    ^${programName} ${escapedArgs} ...$final_args | complete |
         ""
       }
 
+      let insertion_prefix = if ($insertion_prefix | is-not-empty) and ($pattern | str starts-with $insertion_prefix) and ($prefix | str starts-with $insertion_prefix) { $insertion_prefix } else { "" }
+      let prefix_length = ($insertion_prefix | str length)
+      let pattern = if $prefix_length > 0 { $pattern | str substring $prefix_length.. } else { $pattern }
+      let prefix = if $prefix_length > 0 { $prefix | str substring $prefix_length.. } else { $prefix }
+
       # When a pattern is specified, use it as the glob base instead of
       # the user-typed prefix.  If the user has already typed beyond the
       # pattern (e.g., pattern="src/" and prefix="src/ma"), keep the
@@ -1018,7 +1089,7 @@ ${escapedArgs ? `    ^${programName} ${escapedArgs} ...$final_args | complete |
         } else {
           $dir_prefix + ($item.name | path basename)
         }
-        { value: $name }
+        { value: ($insertion_prefix + $name) }
       }
     } else {
       # Regular literal completion - split by tab
@@ -1075,7 +1146,7 @@ ${functionName}-external
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
-				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
+				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}${encodeFilePrefix(suggestion)}\t${description}`;
 			}
 			i++;
 		}
@@ -1142,11 +1213,17 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
             if (\$line -match '^__FILE__:') {
                 # Parse file completion directive: __FILE__:type:extensions:pattern:hidden
                 \$directive = (\$line -split "\`t")[0]
-                \$parts = \$directive -split ':', 5
+                \$parts = \$directive -split ':', 6
                 \$type = \$parts[1]
                 \$extensions = \$parts[2]
                 \$pattern = \$parts[3] -replace '%3A', ':' -replace '%25', '%'
                 \$hidden = \$parts[4] -eq '1'
+                \$insertionPrefix = if (\$parts.Length -gt 5) { \$parts[5] -replace '%3A', ':' -replace '%25', '%' } else { '' }
+                \$matchingWord = \$wordToComplete
+                if (\$insertionPrefix -and \$pattern.StartsWith(\$insertionPrefix, [System.StringComparison]::Ordinal) -and \$matchingWord.StartsWith(\$insertionPrefix, [System.StringComparison]::Ordinal)) {
+                    \$pattern = \$pattern.Substring(\$insertionPrefix.Length)
+                    \$matchingWord = \$matchingWord.Substring(\$insertionPrefix.Length)
+                } else { \$insertionPrefix = '' }
 
                 # When a pattern is specified, use it as the file matching
                 # prefix instead of the current word.  If the user has
@@ -1155,7 +1232,7 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
                 # comparing so that Windows backslashes match forward slashes
                 # in the transported pattern.
                 \$normalizedPattern = if (\$pattern) { \$pattern.Replace('\\', '/') -replace '^\\./','' } else { '' }
-                \$normalizedWord = if (\$wordToComplete) { \$wordToComplete.Replace('\\', '/') -replace '^\\./','' } else { '' }
+                \$normalizedWord = if (\$matchingWord) { \$matchingWord.Replace('\\', '/') -replace '^\\./','' } else { '' }
                 \$comparison = if (\$IsWindows) { [System.StringComparison]::OrdinalIgnoreCase } else { [System.StringComparison]::Ordinal }
                 # For wildcard patterns, compare only the directory prefix
                 \$comparePattern = \$normalizedPattern
@@ -1167,12 +1244,12 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
                         \$comparePattern = ''
                     }
                 }
-                \$prefix = if ((\$comparePattern -or \$normalizedWord) -and \$normalizedWord -and \$normalizedWord.StartsWith(\$comparePattern, \$comparison) -and \$normalizedWord.Length -ge \$comparePattern.Length -and \$wordToComplete -ne \$pattern) {
-                    \$wordToComplete
+                \$prefix = if ((\$comparePattern -or \$normalizedWord) -and \$normalizedWord -and \$normalizedWord.StartsWith(\$comparePattern, \$comparison) -and \$normalizedWord.Length -ge \$comparePattern.Length -and \$matchingWord -ne \$pattern) {
+                    \$matchingWord
                 } elseif (\$pattern) {
                     \$pattern
-                } elseif (\$wordToComplete) {
-                    \$wordToComplete
+                } elseif (\$matchingWord) {
+                    \$matchingWord
                 } else { '' }
 
                 # Use -Force to include hidden files when requested, or when
@@ -1247,7 +1324,7 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
                     \$completionText = if (\$_.PSIsContainer) { "\$dirPrefix\$(\$_.Name)/" } else { "\$dirPrefix\$(\$_.Name)" }
                     \$itemType = if (\$_.PSIsContainer) { 'Directory' } else { 'File' }
                     [System.Management.Automation.CompletionResult]::new(
-                        \$completionText,
+                        (\$insertionPrefix + \$completionText),
                         \$completionText,
                         'ParameterValue',
                         \$itemType
@@ -1287,7 +1364,7 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
-				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t[file]\t${description}`;
+				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}${encodeFilePrefix(suggestion)}\t[file]\t${description}`;
 			}
 			i++;
 		}

package/dist/completion.js

@@ -40,6 +40,12 @@ function validateProgramName(programName) {
 function encodePattern(pattern) {
 	return pattern.replace(/%/g, "%25").replace(/:/g, "%3A");
 }
+/** Encodes optional literal insertion metadata without changing old directives. */
+function encodeFilePrefix(suggestion) {
+	const prefix = suggestion.prefix ?? "";
+	if (prefix === "" || !(suggestion.pattern ?? "").startsWith(prefix) || sanitizeForTransport(prefix) !== prefix) return "";
+	return `:${encodePattern(prefix)}`;
+}
 function encodeExtensions(extensions) {
 	return extensions?.map((ext) => ext.replace(/^\./, "")).join(",") ?? "";
 }
@@ -69,13 +75,32 @@ function _${programName} () {
   COMPREPLY=()
   local current="\${COMP_WORDS[COMP_CWORD]}"
   local prev=("\${COMP_WORDS[@]:1:COMP_CWORD-1}")
+  local __prefix_aware=0
   while IFS= read -r line; do
     if [[ "$line" == __FILE__:* ]]; then
       # Parse file completion directive: __FILE__:type:extensions:pattern:hidden
-      IFS=':' read -r _ type extensions pattern hidden <<< "$line"
+      local insertion_prefix
+      IFS=':' read -r _ type extensions pattern hidden insertion_prefix <<< "$line"
       extensions="\${extensions//,\\./,}"; extensions="\${extensions#.}"
       pattern="\${pattern//%3A/:}"; pattern="\${pattern//%25/%}"
 
+      insertion_prefix="\${insertion_prefix//%3A/:}"; insertion_prefix="\${insertion_prefix//%25/%}"
+      local __saved_current="$current"
+      local -a __saved_reply=()
+      if [[ -n "$insertion_prefix" && "$pattern" == "$insertion_prefix"* && "$current" == "$insertion_prefix"* ]]; then
+        pattern="\${pattern#"$insertion_prefix"}"
+        current="\${current#"$insertion_prefix"}"
+        __prefix_aware=1
+      else
+        insertion_prefix=""
+      fi
+      # Inserted keys are not filesystem paths.  Once present, keep earlier
+      # replies out of later file filters; retain legacy-only aggregation.
+      if [[ "$__prefix_aware" == "1" ]]; then
+        __saved_reply=("\${COMPREPLY[@]}")
+        COMPREPLY=()
+      fi
+
       # Save and adjust glob/shell options for safe file completion
       local __dotglob_was_set=0 __failglob_was_set=0 __noglob_was_set=0
       local __globignore_was_set=0 __saved_globignore="\${GLOBIGNORE-}"
@@ -274,6 +299,16 @@ function _${programName} () {
         done
         COMPREPLY=("\${filtered[@]}")
       fi
+      if [[ -n "$insertion_prefix" ]]; then
+        local __prefix_index
+        for __prefix_index in "\${!COMPREPLY[@]}"; do
+          COMPREPLY[$__prefix_index]="$insertion_prefix\${COMPREPLY[$__prefix_index]}"
+        done
+      fi
+      if [[ "$__prefix_aware" == "1" ]]; then
+        COMPREPLY=("\${__saved_reply[@]}" "\${COMPREPLY[@]}")
+      fi
+      current="$__saved_current"
     else
       # Regular literal completion
       COMPREPLY+=("$line")
@@ -293,7 +328,7 @@ complete -F _${programName} -- ${programName}
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const pattern = encodePattern(suggestion.pattern ?? "");
-				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}`;
+				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}${encodeFilePrefix(suggestion)}`;
 			}
 			i++;
 		}
@@ -343,9 +378,20 @@ function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
 
       if [[ "\$value" == __FILE__:* ]]; then
         # Parse file completion directive: __FILE__:type:extensions:pattern:hidden
-        local type extensions pattern hidden
-        IFS=':' read -r _ type extensions pattern hidden <<< "\$value"
-        pattern="\${pattern//%3A/:}"; pattern="\${pattern//%25/%}"
+        local type extensions pattern hidden insertion_prefix
+        IFS=':' read -r _ type extensions pattern hidden insertion_prefix <<< "\$value"
+        local __decoded_pattern="\$pattern"
+        __decoded_pattern="\${__decoded_pattern//\\%3A/:}"; __decoded_pattern="\${__decoded_pattern//\\%25/%}"
+        insertion_prefix="\${insertion_prefix//\\%3A/:}"; insertion_prefix="\${insertion_prefix//\\%25/%}"
+        local __saved_prefix="\$PREFIX" __saved_iprefix="\$IPREFIX"
+        if [[ -n "\$insertion_prefix" && "\$__decoded_pattern" == "\$insertion_prefix"* && "\$PREFIX" == "\$insertion_prefix"* ]]; then
+          pattern="\${__decoded_pattern#"\$insertion_prefix"}"
+          PREFIX="\${PREFIX#"\$insertion_prefix"}"
+          IPREFIX="\$IPREFIX\$insertion_prefix"
+        else
+          # Preserve legacy decoding for directives without active metadata.
+          pattern="\${pattern//%3A/:}"; pattern="\${pattern//%25/%}"
+        fi
         has_file_completion=1
 
         # Native completion helpers expect normal zsh glob grouping even if
@@ -364,7 +410,6 @@ function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
         # _directories enumerate the pattern's directory instead of the
         # current word.  If the user has already typed beyond the pattern,
         # keep PREFIX unchanged for incremental narrowing.
-        local __saved_prefix="\$PREFIX"
         if [[ -n "\$pattern" ]]; then
           # Normalize leading ./ so that ./src/ma matches pattern src/
           local __norm_prefix="\${PREFIX#./}"
@@ -421,6 +466,7 @@ function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
 
         # Restore PREFIX and glob_dots to their previous state
         PREFIX="\$__saved_prefix"
+        IPREFIX="\$__saved_iprefix"
         if [[ "\$__was_sh_glob" == "1" ]]; then setopt sh_glob; else unsetopt sh_glob; fi
         if [[ "\$__was_glob_dots" == "1" ]]; then setopt glob_dots; else unsetopt glob_dots; fi
       else
@@ -463,7 +509,7 @@ fi
 			const hidden = suggestion.includeHidden ? "1" : "0";
 			const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
 			const pattern = encodePattern(suggestion.pattern ?? "");
-			yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\0${description}\0`;
+			yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}${encodeFilePrefix(suggestion)}\0${description}\0`;
 		}
 	}
 };
@@ -501,6 +547,21 @@ ${escapedArgs ? `    set -l output (${programName} ${escapedArgs} $prev $current
             set -l extensions $parts[3]
             set -l pattern (string replace -a '%25' '%' -- (string replace -a '%3A' ':' -- $parts[4]))
             set -l hidden $parts[5]
+            set -l insertion_prefix ""
+            if test (count $parts) -ge 6
+                set insertion_prefix (string replace -a '%25' '%' -- (string replace -a '%3A' ':' -- $parts[6]))
+            end
+            set -l saved_current "$current"
+            set -l prefix_length (string length -- "$insertion_prefix")
+            if test $prefix_length -gt 0
+                and test (string sub -l $prefix_length -- "$pattern") = "$insertion_prefix"
+                and test (string sub -l $prefix_length -- "$current") = "$insertion_prefix"
+                set -l start (math $prefix_length + 1)
+                set pattern (string sub -s $start -- "$pattern")
+                set current (string sub -s $start -- "$current")
+            else
+                set insertion_prefix ""
+            end
 
             # When a pattern is specified, use it as the glob base instead
             # of the current word.  If the user has already typed beyond the
@@ -722,8 +783,9 @@ ${escapedArgs ? `    set -l output (${programName} ${escapedArgs} $prev $current
 
             # Output file completions
             for item in $items
-                echo $item
+                echo "$insertion_prefix$item"
             end
+            set current "$saved_current"
         else
             # Regular literal completion - split by tab
             set -l parts (string split \\t -- $line)
@@ -753,7 +815,7 @@ complete -c ${programName} -f -a '(${functionName})'
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
-				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
+				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}${encodeFilePrefix(suggestion)}\t${description}`;
 			}
 			i++;
 		}
@@ -866,6 +928,10 @@ ${escapedArgs ? `    ^${programName} ${escapedArgs} ...$final_args | complete |
       let pattern = ($parts | get 3 | str replace -a '%3A' ':' | str replace -a '%25' '%')
       let hidden = ($parts | get 4) == '1'
 
+      let insertion_prefix = if ($parts | length) > 5 {
+        $parts | get 5 | str replace -a '%3A' ':' | str replace -a '%25' '%'
+      } else { "" }
+
       # Extract prefix from the last argument if it exists
       let prefix = if ($final_args | length) > 0 {
         $final_args | last
@@ -873,6 +939,11 @@ ${escapedArgs ? `    ^${programName} ${escapedArgs} ...$final_args | complete |
         ""
       }
 
+      let insertion_prefix = if ($insertion_prefix | is-not-empty) and ($pattern | str starts-with $insertion_prefix) and ($prefix | str starts-with $insertion_prefix) { $insertion_prefix } else { "" }
+      let prefix_length = ($insertion_prefix | str length)
+      let pattern = if $prefix_length > 0 { $pattern | str substring $prefix_length.. } else { $pattern }
+      let prefix = if $prefix_length > 0 { $prefix | str substring $prefix_length.. } else { $prefix }
+
       # When a pattern is specified, use it as the glob base instead of
       # the user-typed prefix.  If the user has already typed beyond the
       # pattern (e.g., pattern="src/" and prefix="src/ma"), keep the
@@ -1018,7 +1089,7 @@ ${escapedArgs ? `    ^${programName} ${escapedArgs} ...$final_args | complete |
         } else {
           $dir_prefix + ($item.name | path basename)
         }
-        { value: $name }
+        { value: ($insertion_prefix + $name) }
       }
     } else {
       # Regular literal completion - split by tab
@@ -1075,7 +1146,7 @@ ${functionName}-external
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
-				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
+				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}${encodeFilePrefix(suggestion)}\t${description}`;
 			}
 			i++;
 		}
@@ -1142,11 +1213,17 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
             if (\$line -match '^__FILE__:') {
                 # Parse file completion directive: __FILE__:type:extensions:pattern:hidden
                 \$directive = (\$line -split "\`t")[0]
-                \$parts = \$directive -split ':', 5
+                \$parts = \$directive -split ':', 6
                 \$type = \$parts[1]
                 \$extensions = \$parts[2]
                 \$pattern = \$parts[3] -replace '%3A', ':' -replace '%25', '%'
                 \$hidden = \$parts[4] -eq '1'
+                \$insertionPrefix = if (\$parts.Length -gt 5) { \$parts[5] -replace '%3A', ':' -replace '%25', '%' } else { '' }
+                \$matchingWord = \$wordToComplete
+                if (\$insertionPrefix -and \$pattern.StartsWith(\$insertionPrefix, [System.StringComparison]::Ordinal) -and \$matchingWord.StartsWith(\$insertionPrefix, [System.StringComparison]::Ordinal)) {
+                    \$pattern = \$pattern.Substring(\$insertionPrefix.Length)
+                    \$matchingWord = \$matchingWord.Substring(\$insertionPrefix.Length)
+                } else { \$insertionPrefix = '' }
 
                 # When a pattern is specified, use it as the file matching
                 # prefix instead of the current word.  If the user has
@@ -1155,7 +1232,7 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
                 # comparing so that Windows backslashes match forward slashes
                 # in the transported pattern.
                 \$normalizedPattern = if (\$pattern) { \$pattern.Replace('\\', '/') -replace '^\\./','' } else { '' }
-                \$normalizedWord = if (\$wordToComplete) { \$wordToComplete.Replace('\\', '/') -replace '^\\./','' } else { '' }
+                \$normalizedWord = if (\$matchingWord) { \$matchingWord.Replace('\\', '/') -replace '^\\./','' } else { '' }
                 \$comparison = if (\$IsWindows) { [System.StringComparison]::OrdinalIgnoreCase } else { [System.StringComparison]::Ordinal }
                 # For wildcard patterns, compare only the directory prefix
                 \$comparePattern = \$normalizedPattern
@@ -1167,12 +1244,12 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
                         \$comparePattern = ''
                     }
                 }
-                \$prefix = if ((\$comparePattern -or \$normalizedWord) -and \$normalizedWord -and \$normalizedWord.StartsWith(\$comparePattern, \$comparison) -and \$normalizedWord.Length -ge \$comparePattern.Length -and \$wordToComplete -ne \$pattern) {
-                    \$wordToComplete
+                \$prefix = if ((\$comparePattern -or \$normalizedWord) -and \$normalizedWord -and \$normalizedWord.StartsWith(\$comparePattern, \$comparison) -and \$normalizedWord.Length -ge \$comparePattern.Length -and \$matchingWord -ne \$pattern) {
+                    \$matchingWord
                 } elseif (\$pattern) {
                     \$pattern
-                } elseif (\$wordToComplete) {
-                    \$wordToComplete
+                } elseif (\$matchingWord) {
+                    \$matchingWord
                 } else { '' }
 
                 # Use -Force to include hidden files when requested, or when
@@ -1247,7 +1324,7 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
                     \$completionText = if (\$_.PSIsContainer) { "\$dirPrefix\$(\$_.Name)/" } else { "\$dirPrefix\$(\$_.Name)" }
                     \$itemType = if (\$_.PSIsContainer) { 'Directory' } else { 'File' }
                     [System.Management.Automation.CompletionResult]::new(
-                        \$completionText,
+                        (\$insertionPrefix + \$completionText),
                         \$completionText,
                         'ParameterValue',
                         \$itemType
@@ -1287,7 +1364,7 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
 				const hidden = suggestion.includeHidden ? "1" : "0";
 				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
-				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t[file]\t${description}`;
+				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}${encodeFilePrefix(suggestion)}\t[file]\t${description}`;
 			}
 			i++;
 		}

package/dist/internal/parser.d.cts

@@ -637,6 +637,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

@@ -637,6 +637,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

@@ -1311,6 +1311,7 @@ function multiple(parser, options = {}) {
 					"file",
 					suggestion.type,
 					suggestion.pattern ?? "",
+					suggestion.prefix ?? "",
 					suggestion.includeHidden === true,
 					suggestion.extensions == null ? "" : suggestion.extensions.toSorted().join("\0"),
 					description

package/dist/modifiers.js

@@ -1311,6 +1311,7 @@ function multiple(parser, options = {}) {
 					"file",
 					suggestion.type,
 					suggestion.pattern ?? "",
+					suggestion.prefix ?? "",
 					suggestion.includeHidden === true,
 					suggestion.extensions == null ? "" : suggestion.extensions.toSorted().join("\0"),
 					description

package/dist/suggestion.cjs

@@ -257,22 +257,27 @@ function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both
 *
 * 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

package/dist/suggestion.d.cts

@@ -159,7 +159,7 @@ declare function createErrorWithSuggestions(baseError: Message, invalidInput: st
  *
  * 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

@@ -159,7 +159,7 @@ declare function createErrorWithSuggestions(baseError: Message, invalidInput: st
  *
  * 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

@@ -257,22 +257,27 @@ function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both
 *
 * 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

package/dist/valueparser.cjs

@@ -602,7 +602,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

@@ -602,7 +602,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.1.12",
+  "version": "1.1.13-dev.2823",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -196,7 +196,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.1.12",
+    "@optique/env": "1.1.13-dev.2823+d4c34d2f",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",