@optique/core 0.10.7 → 1.0.0-dev.1116

package/dist/completion.js

@@ -5,16 +5,17 @@ import { formatMessage } from "./message.js";
 * A regular expression pattern for valid program names that can be safely
 * interpolated into shell scripts.
 *
-* This pattern allows:
+* The first character must be alphanumeric or underscore.  Subsequent
+* characters may also include hyphens and dots:
 * - Letters (a-z, A-Z)
 * - Numbers (0-9)
 * - Underscore (_)
-* - Hyphen (-)
-* - Dot (.)
+* - Hyphen (-) — not as the first character
+* - Dot (.) — not as the first character
 *
 * @internal
 */
-const SAFE_PROGRAM_NAME_PATTERN = /^[a-zA-Z0-9_.-]+$/;
+const SAFE_PROGRAM_NAME_PATTERN = /^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/;
 /**
 * Validates a program name for safe use in shell scripts.
 *
@@ -27,7 +28,17 @@ const SAFE_PROGRAM_NAME_PATTERN = /^[a-zA-Z0-9_.-]+$/;
 * @internal
 */
 function validateProgramName(programName) {
-	if (!SAFE_PROGRAM_NAME_PATTERN.test(programName)) throw new Error(`Invalid program name for shell completion: "${programName}". Program names must contain only alphanumeric characters, underscores, hyphens, and dots.`);
+	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");
 }
 /**
 * The Bash shell completion generator.
@@ -47,6 +58,47 @@ function _${programName} () {
     if [[ "$line" == __FILE__:* ]]; then
       # Parse file completion directive: __FILE__:type:extensions:pattern:hidden
       IFS=':' read -r _ type extensions pattern hidden <<< "$line"
+      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
+
+      # 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
 
       # Generate file completions based on type
       case "$type" in
@@ -55,21 +107,21 @@ function _${programName} () {
           if [[ -n "$extensions" ]]; then
             # Complete with extension filtering
             local ext_pattern="\${extensions//,/|}"
-            for file in "$current"*; do
-              [[ -e "$file" && "$file" =~ \\.($ext_pattern)$ ]] && COMPREPLY+=("$file")
+            for file in "$__glob_current"*; do
+              [[ -f "$file" && "$file" =~ \\.($ext_pattern)$ ]] && COMPREPLY+=("$file")
             done
           else
             # Complete files only, exclude directories
-            while IFS= read -r -d '' item; do
+            for item in "$__glob_current"*; do
               [[ -f "$item" ]] && COMPREPLY+=("$item")
-            done < <(compgen -f -z -- "$current")
+            done
           fi
           ;;
         directory)
           # Complete directories only
-          while IFS= read -r -d '' dir; do
-            COMPREPLY+=("$dir/")
-          done < <(compgen -d -z -- "$current")
+          for dir in "$__glob_current"*; do
+            [[ -d "$dir" ]] && COMPREPLY+=("$dir/")
+          done
           ;;
         any)
           # Complete both files and directories
@@ -77,31 +129,50 @@ function _${programName} () {
             # Files with extension filtering + directories
             # Files with extension filtering
             local ext_pattern="\${extensions//,/|}"
-            for item in "$current"*; do
+            for item in "$__glob_current"*; 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 "$__glob_current"*; 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
@@ -123,7 +194,8 @@ complete -F _${programName} ${programName}
 			else {
 				const extensions = suggestion.extensions?.join(",") || "";
 				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++;
 		}
@@ -175,15 +247,22 @@ 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
 
+        # 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
+
         # 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"
+              local ext_pattern="*.(\$\{extensions//,/|\})"
+              _files -g "\$ext_pattern"
             else
               _files -g "*"
             fi
@@ -194,16 +273,16 @@ 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 glob_dots to its previous state
+        if [[ "\$__was_glob_dots" == "1" ]]; then setopt glob_dots; else unsetopt glob_dots; fi
       else
         # Regular literal completion
         if [[ -n "\$value" ]]; then
@@ -241,7 +320,8 @@ compdef _${programName.replace(/[^a-zA-Z0-9]/g, "_")} ${programName}
 			const extensions = suggestion.extensions?.join(",") || "";
 			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 pattern = encodePattern(suggestion.pattern ?? "");
+			yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\0${description}\0`;
 		}
 	}
 };
@@ -273,10 +353,11 @@ ${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]
 
             # Generate file completions based on type
@@ -289,6 +370,21 @@ ${escapedArgs ? `    set -l output (${programName} ${escapedArgs} $prev $current
                             set -a items $item
                         end
                     end
+                    # Fish's * glob does not match dotfiles; add them
+                    # explicitly when the basename is empty (i.e., $current
+                    # 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"
+                        if test -z "$current"; or string match -q '*/' -- "$current"
+                            for item in $current.*
+                                if test -f $item
+                                    set -a items $item
+                                end
+                            end
+                        end
+                    end
                 case directory
                     # Complete directories only
                     for item in $current*
@@ -296,6 +392,15 @@ ${escapedArgs ? `    set -l output (${programName} ${escapedArgs} $prev $current
                             set -a items $item/
                         end
                     end
+                    if test "$hidden" = "1"
+                        if test -z "$current"; or string match -q '*/' -- "$current"
+                            for item in $current.*
+                                if test -d $item
+                                    set -a items $item/
+                                end
+                            end
+                        end
+                    end
                 case any
                     # Complete both files and directories
                     for item in $current*
@@ -305,6 +410,17 @@ ${escapedArgs ? `    set -l output (${programName} ${escapedArgs} $prev $current
                             set -a items $item
                         end
                     end
+                    if test "$hidden" = "1"
+                        if test -z "$current"; or string match -q '*/' -- "$current"
+                            for item in $current.*
+                                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
@@ -372,7 +488,8 @@ complete -c ${programName} -f -a '(${functionName})'
 				const extensions = suggestion.extensions?.join(",") || "";
 				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 pattern = encodePattern(suggestion.pattern ?? "");
+				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
 			}
 			i++;
 		}
@@ -478,10 +595,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
@@ -493,31 +611,33 @@ ${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 + "*" }
+      # Note: into glob is required so that ls expands wildcards from a variable
+      let ls_pattern = if ($prefix | is-empty) { "." } else { ($prefix + "*" | into glob) }
 
+      # 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
             } else {
               let ext_list = ($extensions | split row ',')
-              ls $ls_pattern | where type == file | where {|f|
+              (if $hidden { ls -a $ls_pattern } else { ls $ls_pattern }) | where type == file | where {|f|
                 let ext = ($f.name | path parse | get extension)
                 $ext in $ext_list
               }
             }
           },
           "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 dirs = (if $hidden { ls -a $ls_pattern } else { ls $ls_pattern }) | where type == dir
+              let files = (if $hidden { ls -a $ls_pattern } else { ls $ls_pattern }) | where type == file | where {|f|
                 let ext = ($f.name | path parse | get extension)
                 $ext in $ext_list
               }
@@ -539,12 +659,22 @@ ${escapedArgs ? `    ^${programName} ${escapedArgs} ...$final_args | complete |
         }
       }
 
+      # Extract directory prefix to preserve in completion text
+      let dir_prefix = if ($prefix | is-empty) {
+        ""
+      } else if ($prefix | str ends-with "/") {
+        $prefix
+      } else {
+        let parsed = ($prefix | 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 }
       }
@@ -602,7 +732,8 @@ ${functionName}-external
 				const extensions = suggestion.extensions?.join(",") || "";
 				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 pattern = encodePattern(suggestion.pattern ?? "");
+				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
 			}
 			i++;
 		}
@@ -668,15 +799,19 @@ ${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 { '' }
 
+                # Use -Force to include hidden files when requested
+                \$forceParam = if (\$hidden) { @{Force = \$true} } else { @{} }
+
                 # Get file system items based on type
                 \$items = @()
                 switch (\$type) {
@@ -684,31 +819,31 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
                         if (\$extensions) {
                             # Filter by extensions
                             \$extList = \$extensions -split ','
-                            \$items = Get-ChildItem -File -Path "\${prefix}*" -ErrorAction SilentlyContinue |
+                            \$items = Get-ChildItem @forceParam -File -Path "\${prefix}*" -ErrorAction SilentlyContinue |
                                 Where-Object {
                                     \$ext = \$_.Extension
                                     \$extList | ForEach-Object { if (\$ext -eq ".\$_") { return \$true } }
                                 }
                         } else {
-                            \$items = Get-ChildItem -File -Path "\${prefix}*" -ErrorAction SilentlyContinue
+                            \$items = Get-ChildItem @forceParam -File -Path "\${prefix}*" -ErrorAction SilentlyContinue
                         }
                     }
                     'directory' {
-                        \$items = Get-ChildItem -Directory -Path "\${prefix}*" -ErrorAction SilentlyContinue
+                        \$items = Get-ChildItem @forceParam -Directory -Path "\${prefix}*" -ErrorAction SilentlyContinue
                     }
                     'any' {
                         if (\$extensions) {
                             # Get directories and filtered files
-                            \$dirs = Get-ChildItem -Directory -Path "\${prefix}*" -ErrorAction SilentlyContinue
+                            \$dirs = Get-ChildItem @forceParam -Directory -Path "\${prefix}*" -ErrorAction SilentlyContinue
                             \$extList = \$extensions -split ','
-                            \$files = Get-ChildItem -File -Path "\${prefix}*" -ErrorAction SilentlyContinue |
+                            \$files = Get-ChildItem @forceParam -File -Path "\${prefix}*" -ErrorAction SilentlyContinue |
                                 Where-Object {
                                     \$ext = \$_.Extension
                                     \$extList | ForEach-Object { if (\$ext -eq ".\$_") { return \$true } }
                                 }
                             \$items = \$dirs + \$files
                         } else {
-                            \$items = Get-ChildItem -Path "\${prefix}*" -ErrorAction SilentlyContinue
+                            \$items = Get-ChildItem @forceParam -Path "\${prefix}*" -ErrorAction SilentlyContinue
                         }
                     }
                 }
@@ -718,9 +853,15 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
                     \$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,
@@ -761,7 +902,8 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
 				const extensions = suggestion.extensions?.join(",") || "";
 				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 pattern = encodePattern(suggestion.pattern ?? "");
+				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t[file]\t${description}`;
 			}
 			i++;
 		}