@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/completion.js

@@ -31,6 +31,31 @@ function validateProgramName(programName) {
 	if (!SAFE_PROGRAM_NAME_PATTERN.test(programName)) throw new Error(`Invalid program name for shell completion: "${programName}". Program names must start with an alphanumeric character or underscore, and contain only alphanumeric characters, underscores, hyphens, and dots.`);
 }
 /**
+* Percent-encodes colons and percent signs in a pattern string so that it
+* can be safely embedded in the colon-delimited `__FILE__` transport format.
+* @param pattern The raw pattern string.
+* @returns The encoded pattern string.
+* @internal
+*/
+function encodePattern(pattern) {
+	return pattern.replace(/%/g, "%25").replace(/:/g, "%3A");
+}
+function encodeExtensions(extensions) {
+	return extensions?.map((ext) => ext.replace(/^\./, "")).join(",") ?? "";
+}
+/**
+* Replaces control characters that would corrupt shell completion protocols.
+* Shell completion formats use tabs as field delimiters and newlines as record
+* delimiters.  Null bytes are used as delimiters in zsh's format.
+* This is used for both suggestion text and descriptions.
+* @param text The string to sanitize.
+* @returns The sanitized string with control characters replaced by spaces.
+* @internal
+*/
+function sanitizeForTransport(text) {
+	return text.replace(/[\t\n\r\0]/g, " ");
+}
+/**
 * The Bash shell completion generator.
 * @since 0.6.0
 */
@@ -48,29 +73,153 @@ function _${programName} () {
     if [[ "$line" == __FILE__:* ]]; then
       # Parse file completion directive: __FILE__:type:extensions:pattern:hidden
       IFS=':' read -r _ type extensions pattern hidden <<< "$line"
+      extensions="\${extensions//,\\./,}"; extensions="\${extensions#.}"
+      pattern="\${pattern//%3A/:}"; pattern="\${pattern//%25/%}"
+
+      # 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-}"
+      [[ \${GLOBIGNORE+x} == x ]] && __globignore_was_set=1
+      shopt -q dotglob && __dotglob_was_set=1
+      shopt -q failglob && __failglob_was_set=1
+      [[ $- == *f* ]] && __noglob_was_set=1
+      # Unset GLOBIGNORE before enabling dotglob because unsetting
+      # GLOBIGNORE implicitly clears dotglob in Bash
+      shopt -u failglob 2>/dev/null
+      set +f
+      unset GLOBIGNORE
+
+      # Expand tilde prefix for file globbing
+      local __glob_current="$current" __tilde_prefix="" __tilde_expanded=""
+      if [[ "$current" =~ ^(~[a-zA-Z0-9_.+-]*)(/.*)$ ]]; then
+        __tilde_prefix="\${BASH_REMATCH[1]}"
+        eval "__tilde_expanded=\$__tilde_prefix" 2>/dev/null || true
+        if [[ -n "$__tilde_expanded" && "$__tilde_expanded" != "$__tilde_prefix" ]]; then
+          __glob_current="\${__tilde_expanded}\${current#\$__tilde_prefix}"
+        else
+          __tilde_prefix=""
+        fi
+      fi
+
+      # When a pattern is specified, use it as the glob base instead of the
+      # current word so that completions enumerate the pattern's directory.
+      # However, if the user has already typed beyond the pattern (e.g.,
+      # pattern="src/" and current="src/ma"), preserve the typed suffix
+      # for incremental filtering.
+      local __from_pattern=0
+      if [[ -n "$pattern" ]]; then
+        # Normalize leading ./ so that ./src/ma matches pattern src/
+        local __norm_current="\${current#./}"
+        local __norm_pattern="\${pattern#./}"
+        # For wildcard patterns, compare only the directory prefix before
+        # any wildcards so that typing src/ma narrows src/*.ts correctly
+        local __compare_pattern="$__norm_pattern"
+        if [[ "$__compare_pattern" == *[\*\?]* ]]; then
+          __compare_pattern="\${__compare_pattern%%[\*\?]*}"
+          [[ "$__compare_pattern" == */* ]] && __compare_pattern="\${__compare_pattern%/*}/" || __compare_pattern=""
+        fi
+        if [[ ( -n "$__compare_pattern" || -n "$__norm_current" ) && \${#__norm_current} -ge \${#__compare_pattern} && "\${__norm_current:0:\${#__compare_pattern}}" == "$__compare_pattern" && "$current" != "$pattern" ]]; then
+          # User has typed beyond or an equivalent form of the pattern
+          true
+        else
+          __from_pattern=1
+          # Reset tilde state from the current-word expansion so that a
+          # non-tilde pattern is not rewritten through stale tilde state
+          __tilde_prefix=""
+          __tilde_expanded=""
+          __glob_current="$pattern"
+          if [[ "$pattern" =~ ^(~[a-zA-Z0-9_.+-]*)(/.*)?$ ]]; then
+            __tilde_prefix="\${BASH_REMATCH[1]}"
+            eval "__tilde_expanded=\$__tilde_prefix" 2>/dev/null || true
+            if [[ -n "$__tilde_expanded" && "$__tilde_expanded" != "$__tilde_prefix" ]]; then
+              __glob_current="\${__tilde_expanded}\${pattern#\$__tilde_prefix}"
+            else
+              __tilde_prefix=""
+            fi
+          fi
+          # If the glob base is a directory without a trailing slash,
+          # append one so that the glob enumerates its contents
+          if [[ -d "$__glob_current" && "$__glob_current" != */ ]]; then
+            __glob_current="$__glob_current/"
+          fi
+        fi
+      fi
+
+      # Enable dotglob when hidden files are requested, or when the user
+      # is already navigating inside a hidden directory (e.g., ~/.config/nvim/)
+      # This runs after tilde expansion so that paths like ~/.config/ are
+      # checked against the expanded path, not the literal ~ string.
+      local __inside_hidden_path=0
+      case "/\${__glob_current%/}/" in
+        */.[!.]*/*|*/..?*/*) __inside_hidden_path=1 ;;
+      esac
+      # Also check if the current prefix explicitly targets hidden entries
+      # (e.g., user typed "." or ".e" to complete .env)
+      local __prefix_targets_hidden=0
+      local __prefix_base="\${__glob_current##*/}"
+      [[ "$__prefix_base" == .* ]] && __prefix_targets_hidden=1
+      if [[ "$hidden" == "1" || "$__inside_hidden_path" == "1" || "$__prefix_targets_hidden" == "1" ]]; then shopt -s dotglob; fi
+
+      # Pre-expand file candidates.  When the glob base came from the
+      # program's pattern and contains wildcard characters (* or ?),
+      # use it as-is via compgen -G (safe — no command substitution).
+      # Otherwise append * to treat it as a prefix.
+      # Note: [ is NOT treated as a glob indicator because it commonly
+      # appears in literal filenames like [draft] or foo[1].txt.
+      local -a __candidates=()
+      if [[ "$__from_pattern" == "1" && "$__glob_current" == *[\*\?]* ]]; then
+        mapfile -t __candidates < <(compgen -G "$__glob_current" 2>/dev/null)
+        # For file/any modes, also include directories from the base
+        # directory for navigation even when the glob itself does not
+        # match directory names.  Skip this for directory mode so that
+        # the pattern's basename filter is respected.
+        if [[ "$type" != "directory" ]]; then
+          local __glob_dir="\${__glob_current%/*}"
+          [[ "$__glob_dir" == "$__glob_current" ]] && __glob_dir="."
+          local __d
+          for __d in "$__glob_dir"/*/; do
+            [[ -d "$__d" ]] && __candidates+=("\${__d%/}")
+          done
+        fi
+      else
+        __candidates=("$__glob_current"*)
+        # Remove no-match sentinel (bash returns the literal pattern).
+        # Also check -L for dangling symlinks which are valid candidates.
+        if [[ \${#__candidates[@]} -eq 1 && ! -e "\${__candidates[0]}" && ! -L "\${__candidates[0]}" ]]; then
+          __candidates=()
+        fi
+      fi
 
       # Generate file completions based on type
       case "$type" in
         file)
-          # Complete files only
+          # Complete files and directories (directories for navigation)
           if [[ -n "$extensions" ]]; then
-            # Complete with extension filtering
+            # Files with extension filtering + directories
             local ext_pattern="\${extensions//,/|}"
-            for file in "$current"*; do
-              [[ -e "$file" && "$file" =~ \\.($ext_pattern)$ ]] && COMPREPLY+=("$file")
+            for item in "\${__candidates[@]}"; do
+              if [[ -d "$item" ]]; then
+                COMPREPLY+=("$item/")
+              elif [[ -f "$item" && "$item" =~ \\.($ext_pattern)$ ]]; then
+                COMPREPLY+=("$item")
+              fi
             done
           else
-            # Complete files only, exclude directories
-            while IFS= read -r -d '' item; do
-              [[ -f "$item" ]] && COMPREPLY+=("$item")
-            done < <(compgen -f -z -- "$current")
+            # Complete files and directories for navigation
+            for item in "\${__candidates[@]}"; do
+              if [[ -d "$item" ]]; then
+                COMPREPLY+=("$item/")
+              elif [[ -f "$item" ]]; then
+                COMPREPLY+=("$item")
+              fi
+            done
           fi
           ;;
         directory)
           # Complete directories only
-          while IFS= read -r -d '' dir; do
-            COMPREPLY+=("$dir/")
-          done < <(compgen -d -z -- "$current")
+          for dir in "\${__candidates[@]}"; do
+            [[ -d "$dir" ]] && COMPREPLY+=("$dir/")
+          done
           ;;
         any)
           # Complete both files and directories
@@ -78,31 +227,50 @@ function _${programName} () {
             # Files with extension filtering + directories
             # Files with extension filtering
             local ext_pattern="\${extensions//,/|}"
-            for item in "$current"*; do
+            for item in "\${__candidates[@]}"; do
               if [[ -d "$item" ]]; then
                 COMPREPLY+=("$item/")
-              elif [[ -f "$item" && "$item" =~ \\.($ext_pattern)$ ]]; then
+              elif [[ ( -e "$item" || -L "$item" ) && "$item" =~ \\.($ext_pattern)$ ]]; then
                 COMPREPLY+=("$item")
               fi
             done
           else
             # Complete files and directories, add slash to directories
-            while IFS= read -r -d '' item; do
+            for item in "\${__candidates[@]}"; do
               if [[ -d "$item" ]]; then
                 COMPREPLY+=("$item/")
-              else
+              # Use -e || -L to include non-regular files (sockets, FIFOs, dangling symlinks)
+              elif [[ -e "$item" || -L "$item" ]]; then
                 COMPREPLY+=("$item")
               fi
-            done < <(compgen -f -z -- "$current")
+            done
           fi
           ;;
       esac
 
+      # Restore tilde prefix in completion results
+      if [[ -n "$__tilde_prefix" ]]; then
+        local __i
+        for __i in "\${!COMPREPLY[@]}"; do
+          COMPREPLY[\$__i]="\${COMPREPLY[\$__i]/#\$__tilde_expanded/\$__tilde_prefix}"
+        done
+      fi
+
+      # Restore glob/shell options
+      # Restore GLOBIGNORE before dotglob because assigning GLOBIGNORE
+      # implicitly enables dotglob in Bash
+      if [[ "$__globignore_was_set" == "1" ]]; then GLOBIGNORE="$__saved_globignore"; fi
+      if [[ "$__dotglob_was_set" == "0" ]]; then shopt -u dotglob; else shopt -s dotglob; fi
+      if [[ "$__failglob_was_set" == "1" ]]; then shopt -s failglob; fi
+      if [[ "$__noglob_was_set" == "1" ]]; then set -f; fi
+
       # Filter out hidden files unless requested
-      if [[ "$hidden" != "1" && "$current" != .* ]]; then
+      if [[ "$hidden" != "1" && "$__inside_hidden_path" == "0" && "$__prefix_targets_hidden" == "0" ]]; then
         local filtered=()
+        local __name
         for item in "\${COMPREPLY[@]}"; do
-          [[ "$(basename "$item")" != .* ]] && filtered+=("$item")
+          __name="\${item%/}"; __name="\${__name##*/}"
+          [[ "$__name" != .* ]] && filtered+=("$item")
         done
         COMPREPLY=("\${filtered[@]}")
       fi
@@ -113,18 +281,19 @@ function _${programName} () {
   done < <(${programName} ${escapedArgs} "\${prev[@]}" "$current" 2>/dev/null)
 }
 
-complete -F _${programName} ${programName}
+complete -F _${programName} -- ${programName}
     `;
 	},
 	*encodeSuggestions(suggestions) {
 		let i = 0;
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
-			if (suggestion.kind === "literal") yield `${suggestion.text}`;
+			if (suggestion.kind === "literal") yield sanitizeForTransport(suggestion.text);
 			else {
-				const extensions = suggestion.extensions?.join(",") || "";
+				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				yield `__FILE__:${suggestion.type}:${extensions}:${suggestion.pattern || ""}:${hidden}`;
+				const pattern = encodePattern(suggestion.pattern ?? "");
+				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}`;
 			}
 			i++;
 		}
@@ -139,7 +308,7 @@ const zsh = {
 	generateScript(programName, args = []) {
 		validateProgramName(programName);
 		const escapedArgs = args.map((arg) => `'${arg.replace(/'/g, "'\\''")}'`).join(" ");
-		return `
+		return `#compdef ${programName}
 function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
   local current="\$words[CURRENT]"
   local -a prev
@@ -176,17 +345,52 @@ function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
         # 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/%}"
         has_file_completion=1
 
+        # Native completion helpers expect normal zsh glob grouping even if
+        # the caller enabled SH_GLOB in their shell options.
+        local __was_sh_glob=0
+        [[ -o sh_glob ]] && __was_sh_glob=1
+        unsetopt sh_glob
+
+        # Enable glob_dots when hidden files are requested so that
+        # _files and _directories include dot-prefixed entries
+        local __was_glob_dots=0
+        [[ -o glob_dots ]] && __was_glob_dots=1
+        if [[ "\$hidden" == "1" ]]; then setopt glob_dots; fi
+
+        # When a pattern is specified, override PREFIX so that _files and
+        # _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#./}"
+          local __norm_pattern="\${pattern#./}"
+          local __compare_pattern="\$__norm_pattern"
+          if [[ "\$__compare_pattern" == *[\*\?]* ]]; then
+            __compare_pattern="\${__compare_pattern%%[\*\?]*}"
+            [[ "\$__compare_pattern" == */* ]] && __compare_pattern="\${__compare_pattern%/*}/" || __compare_pattern=""
+          fi
+          if [[ ( -n "\$__compare_pattern" || -n "\$__norm_prefix" ) && \${#__norm_prefix} -ge \${#__compare_pattern} && "\${__norm_prefix[1,\${#__compare_pattern}]}" == "\$__compare_pattern" && "\$PREFIX" != "\$pattern" ]]; then
+            # User typed an equivalent or extended form — keep PREFIX
+            true
+          else
+            PREFIX="\$pattern"
+          fi
+        fi
+
         # Use zsh's native file completion
         case "\$type" in
           file)
             if [[ -n "\$extensions" ]]; then
-              # Complete files with extension filtering
-              local ext_pattern="*.(\\$\{extensions//,/|\})"
-              _files -g "\\$ext_pattern"
+              # Complete files with extension filtering + directories for navigation
+              local ext_pattern="*.(\$\{extensions//,/|\})"
+              _files -g "\$ext_pattern"; _directories
             else
-              _files -g "*"
+              _files
             fi
             ;;
           directory)
@@ -195,16 +399,18 @@ function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
           any)
             if [[ -n "\$extensions" ]]; then
               # Complete both files and directories, with extension filtering for files
-              local ext_pattern="*.(\\$\{extensions//,/|\})"
-              _files -g "\\$ext_pattern" && _directories
+              local ext_pattern="*.(\$\{extensions//,/|\})"
+              _files -g "\$ext_pattern"; _directories
             else
               _files
             fi
             ;;
         esac
 
-        # Note: zsh's _files and _directories handle hidden file filtering automatically
-        # based on the completion context and user settings
+        # Restore PREFIX and glob_dots to their previous state
+        PREFIX="\$__saved_prefix"
+        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
         # Regular literal completion
         if [[ -n "\$value" ]]; then
@@ -236,13 +442,14 @@ compdef _${programName.replace(/[^a-zA-Z0-9]/g, "_")} ${programName}
 	},
 	*encodeSuggestions(suggestions) {
 		for (const suggestion of suggestions) if (suggestion.kind === "literal") {
-			const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
-			yield `${suggestion.text}\0${description}\0`;
+			const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
+			yield `${sanitizeForTransport(suggestion.text)}\0${description}\0`;
 		} else {
-			const extensions = suggestion.extensions?.join(",") || "";
+			const extensions = encodeExtensions(suggestion.extensions);
 			const hidden = suggestion.includeHidden ? "1" : "0";
-			const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
-			yield `__FILE__:${suggestion.type}:${extensions}:${suggestion.pattern || ""}:${hidden}\0${description}\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`;
 		}
 	}
 };
@@ -274,44 +481,190 @@ ${escapedArgs ? `    set -l output (${programName} ${escapedArgs} $prev $current
     for line in $output
         if string match -q '__FILE__:*' -- $line
             # Parse file completion directive: __FILE__:type:extensions:pattern:hidden
-            set -l parts (string split ':' -- $line)
+            set -l directive (string split \\t -- $line)[1]
+            set -l parts (string split ':' -- $directive)
             set -l type $parts[2]
             set -l extensions $parts[3]
-            set -l pattern $parts[4]
+            set -l pattern (string replace -a '%25' '%' -- (string replace -a '%3A' ':' -- $parts[4]))
             set -l hidden $parts[5]
 
+            # When a pattern is specified, use it as the glob base instead
+            # of the current word.  If the user has already typed beyond the
+            # pattern (e.g., pattern="src/" and current="src/ma"), keep the
+            # current word for incremental narrowing.
+            set -l glob_base $current
+            set -l __tilde_prefix ""
+            set -l __from_pattern 0
+            if test -n "$pattern"
+                # Normalize leading ./ so that ./src/ma matches pattern src/
+                set -l __norm_current (string replace -r '^\\./' '' -- "$current")
+                set -l __norm_pattern (string replace -r '^\\./' '' -- "$pattern")
+                # For wildcard patterns, compare only the directory prefix
+                set -l __compare_pattern "$__norm_pattern"
+                if string match -q '*[*?]*' -- "$__compare_pattern"
+                    set __compare_pattern (string replace -r '[*?].*' '' -- "$__compare_pattern")
+                    if string match -q '*/*' -- "$__compare_pattern"
+                        set __compare_pattern (string replace -r '/[^/]*$' '/' -- "$__compare_pattern")
+                    else
+                        set __compare_pattern ""
+                    end
+                end
+                set -l __cp_len (string length -- "$__compare_pattern")
+                set -l __nc_len (string length -- "$__norm_current")
+                if begin; test -n "$__compare_pattern"; or test -n "$__norm_current"; end
+                    and test $__nc_len -ge $__cp_len
+                    and test (string sub -l $__cp_len -- "$__norm_current") = "$__compare_pattern"
+                    and test "$current" != "$pattern"
+                    set glob_base $current
+                else
+                    set glob_base $pattern
+                    set __from_pattern 1
+                end
+            end
+
+            # Expand tilde prefix for globbing — fish does not expand ~
+            # inside variable substitutions, so replace it with $HOME
+            if string match -q '~/*' -- "$glob_base"
+                set __tilde_prefix "~"
+                set glob_base (string replace -r '^~' "$HOME" -- "$glob_base")
+            else if string match -q '~' -- "$glob_base"
+                set __tilde_prefix "~"
+                set glob_base "$HOME/"
+            end
+
+            # If the glob base is a directory without a trailing slash,
+            # append one so that the glob enumerates its contents
+            if test -d "$glob_base"; and not string match -q '*/' -- "$glob_base"
+                set glob_base "$glob_base/"
+            end
+
+            # Pre-expand file candidates.  When the glob base came from
+            # the program's pattern and contains * or ?, use it as the
+            # complete glob expression.  Otherwise append * as a prefix.
+            # Note: [ is NOT treated as a glob because it commonly
+            # appears in literal filenames like [draft] or foo[1].txt.
+            set -l __has_glob 0
+            if test $__from_pattern -eq 1
+                and string match -q '*[*?]*' -- "$glob_base"
+                set __has_glob 1
+            end
+            set -l __candidates
+            if test $__has_glob -eq 1
+                # Safe glob expansion without eval: split the pattern into
+                # directory and filter parts, list the directory, then use
+                # string match for wildcard filtering
+                set -l __glob_dir (string replace -r '/[^/]*$' '' -- "$glob_base")
+                set -l __glob_filter (string replace -r '.*/' '' -- "$glob_base")
+                if test -z "$__glob_dir"; or test "$__glob_dir" = "$glob_base"
+                    set __glob_dir "."
+                end
+                # Match files by the glob filter.  Fish's * does not match
+                # dotfiles, so also scan .* when the filter targets them.
+                for __item in $__glob_dir/*
+                    if test -e "$__item"
+                        set -l __bn (basename "$__item")
+                        if string match -q "$__glob_filter" -- "$__bn"
+                            set -a __candidates "$__item"
+                        end
+                    end
+                end
+                if string match -q '.*' -- "$__glob_filter"
+                    for __item in $__glob_dir/.*
+                        if test -e "$__item"
+                            set -l __bn (basename "$__item")
+                            if test "$__bn" = "." -o "$__bn" = ".."
+                                continue
+                            end
+                            if string match -q "$__glob_filter" -- "$__bn"
+                                set -a __candidates "$__item"
+                            end
+                        end
+                    end
+                end
+                # For file/any modes, also include directories for navigation.
+                # Skip for directory mode so the pattern filter is respected.
+                if test "$type" != "directory"
+                    for __item in $__glob_dir/*/
+                        if test -d "$__item"
+                            set -a __candidates (string replace -r '/$' '' -- "$__item")
+                        end
+                    end
+                end
+            else
+                set __candidates $glob_base*
+            end
+
             # Generate file completions based on type
             set -l items
             switch $type
                 case file
-                    # Complete files only
-                    for item in $current*
-                        if test -f $item
+                    # Complete files and directories (directories for navigation)
+                    for item in $__candidates
+                        if test -d $item
+                            set -a items $item/
+                        else if test -f $item
                             set -a items $item
                         end
                     end
+                    # Fish's * glob does not match dotfiles; add them
+                    # explicitly when the basename is empty (i.e., $glob_base
+                    # is "" or ends with "/"), because only then are * and
+                    # .* complementary.  When a non-empty basename is present
+                    # (e.g., "foo"), foo* already covers foo.txt, so foo.*
+                    # would just produce duplicates.
+                    if test "$hidden" = "1" -a $__has_glob -eq 0
+                        if test -z "$glob_base"; or string match -q '*/' -- "$glob_base"
+                            for item in $glob_base.*
+                                if test -d $item
+                                    set -a items $item/
+                                else if test -f $item
+                                    set -a items $item
+                                end
+                            end
+                        end
+                    end
                 case directory
                     # Complete directories only
-                    for item in $current*
+                    for item in $__candidates
                         if test -d $item
                             set -a items $item/
                         end
                     end
+                    if test "$hidden" = "1" -a $__has_glob -eq 0
+                        if test -z "$glob_base"; or string match -q '*/' -- "$glob_base"
+                            for item in $glob_base.*
+                                if test -d $item
+                                    set -a items $item/
+                                end
+                            end
+                        end
+                    end
                 case any
                     # Complete both files and directories
-                    for item in $current*
+                    for item in $__candidates
                         if test -d $item
                             set -a items $item/
                         else if test -f $item
                             set -a items $item
                         end
                     end
+                    if test "$hidden" = "1" -a $__has_glob -eq 0
+                        if test -z "$glob_base"; or string match -q '*/' -- "$glob_base"
+                            for item in $glob_base.*
+                                if test -d $item
+                                    set -a items $item/
+                                else if test -f $item
+                                    set -a items $item
+                                end
+                            end
+                        end
+                    end
             end
 
             # Filter by extensions if specified
             if test -n "$extensions" -a "$type" != directory
                 set -l filtered
-                set -l ext_list (string split ',' -- $extensions)
+                set -l ext_list (string replace -r '^\\.' '' -- (string split ',' -- $extensions))
                 for item in $items
                     # Skip directories, they don't have extensions
                     if string match -q '*/' -- $item
@@ -329,8 +682,11 @@ ${escapedArgs ? `    set -l output (${programName} ${escapedArgs} $prev $current
                 set items $filtered
             end
 
-            # Filter out hidden files unless requested
-            if test "$hidden" != "1" -a (string sub -l 1 -- $current) != "."
+            # Filter out hidden files unless requested.
+            # Check the basename of glob_base so that patterns like
+            # "src/.e" correctly target hidden entries.
+            set -l __glob_basename (string replace -r '.*/(.*)' '$1' -- $glob_base)
+            if test "$hidden" != "1" -a (string sub -l 1 -- $__glob_basename) != "."
                 set -l filtered
                 for item in $items
                     set -l basename (basename $item)
@@ -341,6 +697,15 @@ ${escapedArgs ? `    set -l output (${programName} ${escapedArgs} $prev $current
                 set items $filtered
             end
 
+            # Restore tilde prefix in completion results
+            if test -n "$__tilde_prefix"
+                set -l restored
+                for item in $items
+                    set -a restored (string replace "$HOME" "~" -- $item)
+                end
+                set items $restored
+            end
+
             # Output file completions
             for item in $items
                 echo $item
@@ -367,13 +732,14 @@ complete -c ${programName} -f -a '(${functionName})'
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
-				yield `${suggestion.text}\t${description}`;
+				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
+				yield `${sanitizeForTransport(suggestion.text)}\t${description}`;
 			} else {
-				const extensions = suggestion.extensions?.join(",") || "";
+				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
-				yield `__FILE__:${suggestion.type}:${extensions}:${suggestion.pattern || ""}:${hidden}\t${description}`;
+				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}`;
 			}
 			i++;
 		}
@@ -479,10 +845,11 @@ ${escapedArgs ? `    ^${programName} ${escapedArgs} ...$final_args | complete |
   $output | lines | each {|line|
     if ($line | str starts-with '__FILE__:') {
       # Parse file completion directive: __FILE__:type:extensions:pattern:hidden
-      let parts = ($line | split row ':')
+      let directive = ($line | split row "\t" | first)
+      let parts = ($directive | split row ':')
       let type = ($parts | get 1)
       let extensions = ($parts | get 2)
-      let pattern = ($parts | get 3)
+      let pattern = ($parts | get 3 | str replace -a '%3A' ':' | str replace -a '%25' '%')
       let hidden = ($parts | get 4) == '1'
 
       # Extract prefix from the last argument if it exists
@@ -492,33 +859,96 @@ ${escapedArgs ? `    ^${programName} ${escapedArgs} ...$final_args | complete |
         ""
       }
 
-      # Generate file completions based on type
-      # Use current directory if prefix is empty
-      let ls_pattern = if ($prefix | is-empty) { "." } 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
+      # prefix for incremental narrowing.  Normalize path separators
+      # before comparing so that Windows backslashes match forward slashes
+      # in the transported pattern.
+      let glob_base = if ($pattern | is-not-empty) {
+        # Normalize separators and leading ./; downcase only on Windows
+        # where filesystems are typically case-insensitive
+        let norm_prefix_raw = ($prefix | str replace -a '\\' '/' | str replace -r '^\\./' '')
+        let norm_pattern_raw = ($pattern | str replace -a '\\' '/' | str replace -r '^\\./' '')
+        let is_win = (($nu.os-info.name | str downcase) == "windows")
+        let norm_prefix = (if $is_win { $norm_prefix_raw | str downcase } else { $norm_prefix_raw })
+        let norm_pattern = (if $is_win { $norm_pattern_raw | str downcase } else { $norm_pattern_raw })
+        # For wildcard patterns, compare only the directory prefix
+        let compare_pattern = if ($norm_pattern =~ '[*?]') {
+          let before_wild = ($norm_pattern | str replace -r '[*?].*' '')
+          if ($before_wild =~ '/') { $before_wild | str replace -r '/[^/]*$' '/' } else { "" }
+        } else {
+          $norm_pattern
+        }
+        if (($compare_pattern | is-not-empty) or ($norm_prefix | is-not-empty)) and ($norm_prefix | str starts-with $compare_pattern) and (($norm_prefix | str length) >= ($compare_pattern | str length)) and ($prefix != $pattern) {
+          $prefix
+        } else {
+          $pattern
+        }
+      } else {
+        $prefix
+      }
+
+      # If the glob base is a directory without a trailing slash (e.g., "src"),
+      # append one so that ls enumerates its contents instead of matching
+      # siblings like "src-old"
+      let glob_base = if ($glob_base | is-not-empty) and ($glob_base | path type) == "dir" and (not ($glob_base | str ends-with "/")) {
+        $glob_base + "/"
+      } else {
+        $glob_base
+      }
+
+      # Generate file completions based on type.
+      # When the glob base contains wildcard characters, use it as-is;
+      # otherwise append * to treat it as a prefix.
+      # Note: into glob is required so that ls expands wildcards from a variable
+      let has_glob = ($glob_base =~ '[*?]')
+      let ls_pattern = if ($glob_base | is-empty) {
+        "."
+      } else if $has_glob {
+        ($glob_base | into glob)
+      } else {
+        ($glob_base + "*" | into glob)
+      }
 
+      # When using a glob pattern, also compute a directory listing pattern
+      # so that file/any modes can include directories for navigation
+      let glob_dir_pattern = if $has_glob {
+        let dir_part = ($glob_base | path dirname)
+        let dir = if ($dir_part | is-empty) or ($dir_part == $glob_base) { "." } else { $dir_part }
+        ($dir + "/*" | into glob)
+      } else {
+        null
+      }
+
+      # Use ls -a to include hidden files when requested
       let items = try {
         match $type {
           "file" => {
             if ($extensions | is-empty) {
-              ls $ls_pattern | where type == file
+              (if $hidden { ls -a $ls_pattern } else { ls $ls_pattern }) | where type == file or type == dir
             } else {
-              let ext_list = ($extensions | split row ',')
-              ls $ls_pattern | where type == file | where {|f|
+              let ext_list = ($extensions | split row ',' | each {|e| $e | str replace -r '^\\.' '' })
+              let all_items = (if $hidden { ls -a $ls_pattern } else { ls $ls_pattern })
+              let dirs = $all_items | where type == dir
+              let files = $all_items | where type == file | where {|f|
                 let ext = ($f.name | path parse | get extension)
                 $ext in $ext_list
               }
+              $dirs | append $files
             }
           },
           "directory" => {
-            ls $ls_pattern | where type == dir
+            (if $hidden { ls -a $ls_pattern } else { ls $ls_pattern }) | where type == dir
           },
           "any" => {
             if ($extensions | is-empty) {
-              ls $ls_pattern
+              if $hidden { ls -a $ls_pattern } else { ls $ls_pattern }
             } else {
-              let ext_list = ($extensions | split row ',')
-              let dirs = ls $ls_pattern | where type == dir
-              let files = ls $ls_pattern | where type == file | where {|f|
+              let ext_list = ($extensions | split row ',' | each {|e| $e | str replace -r '^\\.' '' })
+              let all_items = (if $hidden { ls -a $ls_pattern } else { ls $ls_pattern })
+              let dirs = $all_items | where type == dir
+              let files = $all_items | where type == file | where {|f|
                 let ext = ($f.name | path parse | get extension)
                 $ext in $ext_list
               }
@@ -530,8 +960,25 @@ ${escapedArgs ? `    ^${programName} ${escapedArgs} ...$final_args | complete |
         []
       }
 
-      # Filter out hidden files unless requested
-      let filtered = if $hidden or ($prefix | str starts-with '.') {
+      # When using a glob pattern, also add directories from the base
+      # directory for navigation (file/any modes should list directories
+      # even when the glob itself does not match directory names)
+      let items = if ($glob_dir_pattern != null) and ($type != "directory") {
+        let extra_dirs = try {
+          (if $hidden { ls -a $glob_dir_pattern } else { ls $glob_dir_pattern }) | where type == dir
+        } catch {
+          []
+        }
+        $items | append $extra_dirs | uniq-by name
+      } else {
+        $items
+      }
+
+      # Filter out hidden files unless requested.
+      # Check the basename of glob_base so that patterns like "src/.e"
+      # correctly target hidden entries.
+      let glob_basename = ($glob_base | path basename)
+      let filtered = if $hidden or ($glob_basename | str starts-with '.') {
         $items
       } else {
         $items | where {|item|
@@ -540,12 +987,22 @@ ${escapedArgs ? `    ^${programName} ${escapedArgs} ...$final_args | complete |
         }
       }
 
+      # Extract directory prefix to preserve in completion text
+      let dir_prefix = if ($glob_base | is-empty) {
+        ""
+      } else if ($glob_base | str ends-with "/") {
+        $glob_base
+      } else {
+        let parsed = ($glob_base | path parse)
+        if ($parsed.parent | is-empty) { "" } else if ($parsed.parent | str ends-with "/") { $parsed.parent } else { $parsed.parent + "/" }
+      }
+
       # Format file completions
       $filtered | each {|item|
         let name = if $item.type == dir {
-          ($item.name | path basename) + "/"
+          $dir_prefix + ($item.name | path basename) + "/"
         } else {
-          $item.name | path basename
+          $dir_prefix + ($item.name | path basename)
         }
         { value: $name }
       }
@@ -597,13 +1054,14 @@ ${functionName}-external
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
-				yield `${suggestion.text}\t${description}`;
+				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
+				yield `${sanitizeForTransport(suggestion.text)}\t${description}`;
 			} else {
-				const extensions = suggestion.extensions?.join(",") || "";
+				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
-				yield `__FILE__:${suggestion.type}:${extensions}:${suggestion.pattern || ""}:${hidden}\t${description}`;
+				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}`;
 			}
 			i++;
 		}
@@ -669,59 +1127,110 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
 
             if (\$line -match '^__FILE__:') {
                 # Parse file completion directive: __FILE__:type:extensions:pattern:hidden
-                \$parts = \$line -split ':', 5
+                \$directive = (\$line -split "\`t")[0]
+                \$parts = \$directive -split ':', 5
                 \$type = \$parts[1]
                 \$extensions = \$parts[2]
-                \$pattern = \$parts[3]
+                \$pattern = \$parts[3] -replace '%3A', ':' -replace '%25', '%'
                 \$hidden = \$parts[4] -eq '1'
 
-                # Determine current prefix for file matching
-                \$prefix = if (\$wordToComplete) { \$wordToComplete } else { '' }
+                # When a pattern is specified, use it as the file matching
+                # prefix instead of the current word.  If the user has
+                # already typed beyond the pattern, keep their input for
+                # incremental narrowing.  Normalize path separators before
+                # 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 { '' }
+                \$comparison = if (\$IsWindows) { [System.StringComparison]::OrdinalIgnoreCase } else { [System.StringComparison]::Ordinal }
+                # For wildcard patterns, compare only the directory prefix
+                \$comparePattern = \$normalizedPattern
+                if (\$comparePattern -match '[\*\?]') {
+                    \$beforeWild = \$comparePattern -replace '[\*\?].*', ''
+                    if (\$beforeWild.Contains('/')) {
+                        \$comparePattern = \$beforeWild.Substring(0, \$beforeWild.LastIndexOf('/') + 1)
+                    } else {
+                        \$comparePattern = ''
+                    }
+                }
+                \$prefix = if ((\$comparePattern -or \$normalizedWord) -and \$normalizedWord -and \$normalizedWord.StartsWith(\$comparePattern, \$comparison) -and \$normalizedWord.Length -ge \$comparePattern.Length -and \$wordToComplete -ne \$pattern) {
+                    \$wordToComplete
+                } elseif (\$pattern) {
+                    \$pattern
+                } elseif (\$wordToComplete) {
+                    \$wordToComplete
+                } else { '' }
+
+                # Use -Force to include hidden files when requested, or when
+                # the prefix basename targets dotfiles (e.g., src/.e)
+                \$prefixBasename = if (\$prefix) { Split-Path -Leaf \$prefix } else { '' }
+                \$forceParam = if (\$hidden -or (\$prefixBasename -and \$prefixBasename.StartsWith('.'))) { @{Force = \$true} } else { @{} }
+
+                # If prefix is a directory without trailing slash, append
+                # one so Get-ChildItem lists its contents
+                if (\$prefix -and (Test-Path -Path \$prefix -PathType Container) -and -not \$prefix.EndsWith('/') -and -not \$prefix.EndsWith('\\')) {
+                    \$prefix = \$prefix + '/'
+                }
+
+                # Build the glob path — when the prefix contains wildcard
+                # characters, use it as-is; otherwise append *
+                \$globPath = if (\$prefix -match '[\*\?]') { \$prefix } else { "\${prefix}*" }
 
                 # Get file system items based on type
                 \$items = @()
                 switch (\$type) {
                     'file' {
                         if (\$extensions) {
-                            # Filter by extensions
-                            \$extList = \$extensions -split ','
-                            \$items = Get-ChildItem -File -Path "\${prefix}*" -ErrorAction SilentlyContinue |
+                            # Filter by extensions, always include directories
+                            \$extList = (\$extensions -split ',') -replace '^\\.',''
+                            \$items = Get-ChildItem @forceParam -Path \$globPath -ErrorAction SilentlyContinue |
                                 Where-Object {
-                                    \$ext = \$_.Extension
-                                    \$extList | ForEach-Object { if (\$ext -eq ".\$_") { return \$true } }
+                                    \$_.PSIsContainer -or ((\$_.Extension -replace '^\\.','' ) -in \$extList)
                                 }
                         } else {
-                            \$items = Get-ChildItem -File -Path "\${prefix}*" -ErrorAction SilentlyContinue
+                            \$items = Get-ChildItem @forceParam -Path \$globPath -ErrorAction SilentlyContinue
                         }
                     }
                     'directory' {
-                        \$items = Get-ChildItem -Directory -Path "\${prefix}*" -ErrorAction SilentlyContinue
+                        \$items = Get-ChildItem @forceParam -Directory -Path \$globPath -ErrorAction SilentlyContinue
                     }
                     'any' {
                         if (\$extensions) {
-                            # Get directories and filtered files
-                            \$dirs = Get-ChildItem -Directory -Path "\${prefix}*" -ErrorAction SilentlyContinue
-                            \$extList = \$extensions -split ','
-                            \$files = Get-ChildItem -File -Path "\${prefix}*" -ErrorAction SilentlyContinue |
+                            # Filter by extensions, always include directories
+                            \$extList = (\$extensions -split ',') -replace '^\\.',''
+                            \$items = Get-ChildItem @forceParam -Path \$globPath -ErrorAction SilentlyContinue |
                                 Where-Object {
-                                    \$ext = \$_.Extension
-                                    \$extList | ForEach-Object { if (\$ext -eq ".\$_") { return \$true } }
+                                    \$_.PSIsContainer -or ((\$_.Extension -replace '^\\.','' ) -in \$extList)
                                 }
-                            \$items = \$dirs + \$files
                         } else {
-                            \$items = Get-ChildItem -Path "\${prefix}*" -ErrorAction SilentlyContinue
+                            \$items = Get-ChildItem @forceParam -Path \$globPath -ErrorAction SilentlyContinue
                         }
                     }
                 }
 
-                # Filter hidden files unless requested
-                if (-not \$hidden) {
+                # For file/any modes with glob patterns, also add directories
+                # from the base directory for navigation
+                if (\$prefix -match '[\*\?]' -and \$type -ne 'directory') {
+                    \$globDir = Split-Path -Parent \$prefix
+                    if (-not \$globDir) { \$globDir = '.' }
+                    \$extraDirs = Get-ChildItem @forceParam -Directory -Path "\$globDir/*" -ErrorAction SilentlyContinue
+                    if (\$extraDirs) { \$items = @(\$items) + @(\$extraDirs) | Select-Object -Unique }
+                }
+
+                # Filter hidden files unless requested or the prefix targets dotfiles
+                if (-not \$hidden -and -not (\$prefixBasename -and \$prefixBasename.StartsWith('.'))) {
                     \$items = \$items | Where-Object { -not \$_.Attributes.HasFlag([System.IO.FileAttributes]::Hidden) }
                 }
 
+                # Extract directory prefix to preserve in completion text
+                \$dirPrefix = if (\$prefix -and (\$prefix.Contains('/') -or \$prefix.Contains('\\'))) {
+                    \$slashIdx = [Math]::Max(\$prefix.LastIndexOf('/'), \$prefix.LastIndexOf('\\'))
+                    \$prefix.Substring(0, \$slashIdx + 1)
+                } else { '' }
+
                 # Create completion results for files
                 \$items | ForEach-Object {
-                    \$completionText = if (\$_.PSIsContainer) { "\$(\$_.Name)/" } else { \$_.Name }
+                    \$completionText = if (\$_.PSIsContainer) { "\$dirPrefix\$(\$_.Name)/" } else { "\$dirPrefix\$(\$_.Name)" }
                     \$itemType = if (\$_.PSIsContainer) { 'Directory' } else { 'File' }
                     [System.Management.Automation.CompletionResult]::new(
                         \$completionText,
@@ -756,13 +1265,15 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
-				yield `${suggestion.text}\t${suggestion.text}\t${description}`;
+				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
+				const text = sanitizeForTransport(suggestion.text);
+				yield `${text}\t${text}\t${description}`;
 			} else {
-				const extensions = suggestion.extensions?.join(",") || "";
+				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : formatMessage(suggestion.description, { colors: false });
-				yield `__FILE__:${suggestion.type}:${extensions}:${suggestion.pattern || ""}:${hidden}\t[file]\t${description}`;
+				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}`;
 			}
 			i++;
 		}