@gunshi/plugin-completion 0.27.0-alpha.6 → 0.27.0-alpha.7

package/README.md

@@ -1,6 +1,13 @@
 # `@gunshi/plugin-completion`
 
-TODO(kazupon): more explanation
+> completion plugin for gunshi
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> ![WARNING]
+> This package is still work in progress
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
 
 ## ©️ License
 

package/lib/index.d.ts

@@ -1,11 +1,72 @@
-import { PluginWithoutExtension } from "@gunshi/plugin";
+import { PluginWithExtension } from "@gunshi/plugin";
+import { Handler } from "@bombsh/tab";
 
-//#region src/index.d.ts
+//#region ../shared/src/constants.d.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
+declare const BUILT_IN_PREFIX = "_";
+declare const PLUGIN_PREFIX = "g";
+declare const BUILT_IN_KEY_SEPARATOR = ":";
+//#endregion
+//#region ../shared/src/types.d.ts
 
+/**
+ * Generate a namespaced key.
+ */
+type GenerateNamespacedKey<Key extends string, Prefixed extends string = typeof BUILT_IN_PREFIX> = `${Prefixed}${typeof BUILT_IN_KEY_SEPARATOR}${Key}`;
+/**
+ * Command i18n built-in arguments keys.
+ */
+//#endregion
+//#region src/types.d.ts
+/**
+ * The unique identifier for the completion plugin.
+ */
+declare const pluginId: GenerateNamespacedKey<'completion', typeof PLUGIN_PREFIX>;
+/**
+ * Type representing the unique identifier for the completion plugin.
+ */
+type PluginId = typeof pluginId;
+/**
+ * Extended command context which provides utilities via completion plugin.
+ * These utilities are available via `CommandContext.extensions['g:completion']`.
+ */
 interface CompletionCommandContext {}
+/**
+ * Completion configuration, which structure is similar `bombsh/tab`'s `CompletionConfig`.
+ */
+interface CompletionConfig {
+  handler?: Handler;
+  args?: Record<string, {
+    handler: Handler;
+  }>;
+}
+/**
+ * Completion plugin options.
+ */
+interface CompletionOptions {
+  config?: {
+    /**
+     * The entry point completion configuration.
+     */
+    entry?: CompletionConfig;
+    /**
+     * The handlers for subcommands.
+     */
+    subCommands?: Record<string, CompletionConfig>;
+  };
+}
+//#endregion
+//#region src/index.d.ts
 /**
  * completion plugin for gunshi
  */
-declare function completion(): PluginWithoutExtension<CompletionCommandContext>;
+declare function completion(options?: CompletionOptions): PluginWithExtension<CompletionCommandContext>;
 //#endregion
-export { CompletionCommandContext, completion as default };
+export { CompletionCommandContext, CompletionConfig, CompletionOptions, PluginId, completion as default, pluginId };

package/lib/index.js

@@ -1,16 +1,1124 @@
 import { plugin } from "@gunshi/plugin";
 
+//#region ../../node_modules/.pnpm/tab@https+++pkg.pr.new+bombshell-dev+tab@main/node_modules/tab/dist/zsh-Bm75fLuV.js
+function generate$3(name, exec) {
+	const nameForVar = name.replace(/[-:]/g, "_");
+	const ShellCompDirectiveError = ShellCompDirective.ShellCompDirectiveError;
+	const ShellCompDirectiveNoSpace = ShellCompDirective.ShellCompDirectiveNoSpace;
+	const ShellCompDirectiveNoFileComp = ShellCompDirective.ShellCompDirectiveNoFileComp;
+	const ShellCompDirectiveFilterFileExt = ShellCompDirective.ShellCompDirectiveFilterFileExt;
+	const ShellCompDirectiveFilterDirs = ShellCompDirective.ShellCompDirectiveFilterDirs;
+	const ShellCompDirectiveKeepOrder = ShellCompDirective.ShellCompDirectiveKeepOrder;
+	return `# bash completion for ${name}
+
+# Define shell completion directives
+readonly ShellCompDirectiveError=${ShellCompDirectiveError}
+readonly ShellCompDirectiveNoSpace=${ShellCompDirectiveNoSpace}
+readonly ShellCompDirectiveNoFileComp=${ShellCompDirectiveNoFileComp}
+readonly ShellCompDirectiveFilterFileExt=${ShellCompDirectiveFilterFileExt}
+readonly ShellCompDirectiveFilterDirs=${ShellCompDirectiveFilterDirs}
+readonly ShellCompDirectiveKeepOrder=${ShellCompDirectiveKeepOrder}
+
+# Function to debug completion
+__${nameForVar}_debug() {
+    if [[ -n \${BASH_COMP_DEBUG_FILE:-} ]]; then
+        echo "$*" >> "\${BASH_COMP_DEBUG_FILE}"
+    fi
+}
+
+# Function to handle completions
+__${nameForVar}_complete() {
+    local cur prev words cword
+    _get_comp_words_by_ref -n "=:" cur prev words cword
+
+    local requestComp out directive
+    
+    # Build the command to get completions
+    requestComp="${exec} complete -- \${words[@]:1}"
+    
+    # Add an empty parameter if the last parameter is complete
+    if [[ -z "$cur" ]]; then
+        requestComp="$requestComp ''"
+    fi
+    
+    # Get completions from the program
+    out=$(eval "$requestComp" 2>/dev/null)
+    
+    # Extract directive if present
+    directive=0
+    if [[ "$out" == *:* ]]; then
+        directive=\${out##*:}
+        out=\${out%:*}
+    fi
+    
+    # Process completions based on directive
+    if [[ $((directive & $ShellCompDirectiveError)) -ne 0 ]]; then
+        # Error, no completion
+        return
+    fi
+    
+    # Apply directives
+    if [[ $((directive & $ShellCompDirectiveNoSpace)) -ne 0 ]]; then
+        compopt -o nospace
+    fi
+    if [[ $((directive & $ShellCompDirectiveKeepOrder)) -ne 0 ]]; then
+        compopt -o nosort
+    fi
+    if [[ $((directive & $ShellCompDirectiveNoFileComp)) -ne 0 ]]; then
+        compopt +o default
+    fi
+    
+    # Handle file extension filtering
+    if [[ $((directive & $ShellCompDirectiveFilterFileExt)) -ne 0 ]]; then
+        local filter=""
+        for ext in $out; do
+            filter="$filter|$ext"
+        done
+        filter="\\.($filter)"
+        compopt -o filenames
+        COMPREPLY=( $(compgen -f -X "!$filter" -- "$cur") )
+        return
+    fi
+    
+    # Handle directory filtering
+    if [[ $((directive & $ShellCompDirectiveFilterDirs)) -ne 0 ]]; then
+        compopt -o dirnames
+        COMPREPLY=( $(compgen -d -- "$cur") )
+        return
+    fi
+    
+    # Process completions
+    local IFS=$'\\n'
+    local tab=$(printf '\\t')
+    
+    # Parse completions with descriptions
+    local completions=()
+    while read -r comp; do
+        if [[ "$comp" == *$tab* ]]; then
+            # Split completion and description
+            local value=\${comp%%$tab*}
+            local desc=\${comp#*$tab}
+            completions+=("$value")
+        else
+            completions+=("$comp")
+        fi
+    done <<< "$out"
+    
+    # Return completions
+    COMPREPLY=( $(compgen -W "\${completions[*]}" -- "$cur") )
+}
+
+# Register completion function
+complete -F __${nameForVar}_complete ${name}
+`;
+}
+function generate$2(name, exec) {
+	const nameForVar = name.replace(/[-:]/g, "_");
+	const ShellCompDirectiveError = ShellCompDirective.ShellCompDirectiveError;
+	const ShellCompDirectiveNoSpace = ShellCompDirective.ShellCompDirectiveNoSpace;
+	const ShellCompDirectiveNoFileComp = ShellCompDirective.ShellCompDirectiveNoFileComp;
+	const ShellCompDirectiveFilterFileExt = ShellCompDirective.ShellCompDirectiveFilterFileExt;
+	const ShellCompDirectiveFilterDirs = ShellCompDirective.ShellCompDirectiveFilterDirs;
+	const ShellCompDirectiveKeepOrder = ShellCompDirective.ShellCompDirectiveKeepOrder;
+	return `# fish completion for ${name} -*- shell-script -*-
+
+# Define shell completion directives
+set -l ShellCompDirectiveError ${ShellCompDirectiveError}
+set -l ShellCompDirectiveNoSpace ${ShellCompDirectiveNoSpace}
+set -l ShellCompDirectiveNoFileComp ${ShellCompDirectiveNoFileComp}
+set -l ShellCompDirectiveFilterFileExt ${ShellCompDirectiveFilterFileExt}
+set -l ShellCompDirectiveFilterDirs ${ShellCompDirectiveFilterDirs}
+set -l ShellCompDirectiveKeepOrder ${ShellCompDirectiveKeepOrder}
+
+function __${nameForVar}_debug
+    set -l file "$BASH_COMP_DEBUG_FILE"
+    if test -n "$file"
+        echo "$argv" >> $file
+    end
+end
+
+function __${nameForVar}_perform_completion
+    __${nameForVar}_debug "Starting __${nameForVar}_perform_completion"
+
+    # Extract all args except the completion flag
+    set -l args (string match -v -- "--completion=" (commandline -opc))
+    
+    # Extract the current token being completed
+    set -l current_token (commandline -ct)
+    
+    # Check if current token starts with a dash
+    set -l flag_prefix ""
+    if string match -q -- "-*" $current_token
+        set flag_prefix "--flag="
+    end
+    
+    __${nameForVar}_debug "Current token: $current_token"
+    __${nameForVar}_debug "All args: $args"
+
+    # Call the completion program and get the results
+    set -l requestComp "${exec} complete -- $args"
+    __${nameForVar}_debug "Calling $requestComp"
+    set -l results (eval $requestComp 2> /dev/null)
+    
+    # Some programs may output extra empty lines after the directive.
+    # Let's ignore them or else it will break completion.
+    # Ref: https://github.com/spf13/cobra/issues/1279
+    for line in $results[-1..1]
+        if test (string sub -s 1 -l 1 -- $line) = ":"
+            # The directive
+            set -l directive (string sub -s 2 -- $line)
+            set -l directive_num (math $directive)
+            break
+        end
+    end
+    
+    # No directive specified, use default
+    if not set -q directive_num
+        set directive_num 0
+    end
+    
+    __${nameForVar}_debug "Directive: $directive_num"
+
+    # Process completions based on directive
+    if test $directive_num -eq $ShellCompDirectiveError
+        # Error code. No completion.
+        __${nameForVar}_debug "Received error directive: aborting."
+        return 1
+    end
+
+    # Filter out the directive (last line)
+    if test (count $results) -gt 0 -a (string sub -s 1 -l 1 -- $results[-1]) = ":"
+        set results $results[1..-2]
+    end
+
+    # No completions, let fish handle file completions unless forbidden
+    if test (count $results) -eq 0
+        if test $directive_num -ne $ShellCompDirectiveNoFileComp
+            __${nameForVar}_debug "No completions, performing file completion"
+            return 1
+        end
+        __${nameForVar}_debug "No completions, but file completion forbidden"
+        return 0
+    end
+
+    # Filter file extensions
+    if test $directive_num -eq $ShellCompDirectiveFilterFileExt
+        __${nameForVar}_debug "File extension filtering"
+        set -l file_extensions
+        for item in $results
+            if test -n "$item" -a (string sub -s 1 -l 1 -- $item) != "-"
+                set -a file_extensions "*$item"
+            end
+        end
+        __${nameForVar}_debug "File extensions: $file_extensions"
+        
+        # Use the file extensions as completions
+        set -l completions
+        for ext in $file_extensions
+            # Get all files matching the extension
+            set -a completions (string replace -r '^.*/' '' -- $ext)
+        end
+        
+        for item in $completions
+            echo -e "$item\t"
+        end
+        return 0
+    end
+
+    # Filter directories
+    if test $directive_num -eq $ShellCompDirectiveFilterDirs
+        __${nameForVar}_debug "Directory filtering"
+        set -l dirs
+        for item in $results
+            if test -d "$item"
+                set -a dirs "$item/"
+            end
+        end
+        
+        for item in $dirs
+            echo -e "$item\t"
+        end
+        return 0
+    end
+
+    # Process remaining completions
+    for item in $results
+        if test -n "$item"
+            # Check if the item has a description
+            if string match -q "*\t*" -- "$item"
+                set -l completion_parts (string split \t -- "$item")
+                set -l comp $completion_parts[1]
+                set -l desc $completion_parts[2]
+                
+                # Add the completion and description
+                echo -e "$comp\t$desc"
+            else
+                # Add just the completion
+                echo -e "$item\t"
+            end
+        end
+    end
+    
+    # If directive contains NoSpace, tell fish not to add a space after completion
+    if test (math "$directive_num & $ShellCompDirectiveNoSpace") -ne 0
+        return 2
+    end
+    
+    return 0
+end
+
+# Set up the completion for the ${name} command
+complete -c ${name} -f -a "(eval __${nameForVar}_perform_completion)"
+`;
+}
+function generate$1(name, exec, includeDesc = false) {
+	const nameForVar = name.replace(/[-:]/g, "_");
+	const ShellCompDirectiveError = ShellCompDirective.ShellCompDirectiveError;
+	const ShellCompDirectiveNoSpace = ShellCompDirective.ShellCompDirectiveNoSpace;
+	const ShellCompDirectiveNoFileComp = ShellCompDirective.ShellCompDirectiveNoFileComp;
+	const ShellCompDirectiveFilterFileExt = ShellCompDirective.ShellCompDirectiveFilterFileExt;
+	const ShellCompDirectiveFilterDirs = ShellCompDirective.ShellCompDirectiveFilterDirs;
+	const ShellCompDirectiveKeepOrder = ShellCompDirective.ShellCompDirectiveKeepOrder;
+	return `# powershell completion for ${name} -*- shell-script -*-
+
+  [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+    function __${name}_debug {
+        if ($env:BASH_COMP_DEBUG_FILE) {
+            "$args" | Out-File -Append -FilePath "$env:BASH_COMP_DEBUG_FILE"
+        }
+    }
+
+    filter __${name}_escapeStringWithSpecialChars {
+        $_ -replace '\\s|#|@|\\$|;|,|''|\\{|\\}|\\(|\\)|"|\\||<|>|&','\`$&'
+    }
+
+[scriptblock]$__${nameForVar}CompleterBlock = {
+    param(
+            $WordToComplete,
+            $CommandAst,
+            $CursorPosition
+        )
+
+    # Get the current command line and convert into a string
+    $Command = $CommandAst.CommandElements
+    $Command = "$Command"
+
+    __${name}_debug ""
+    __${name}_debug "========= starting completion logic =========="
+    __${name}_debug "WordToComplete: $WordToComplete Command: $Command CursorPosition: $CursorPosition"
+
+    # The user could have moved the cursor backwards on the command-line.
+    # We need to trigger completion from the $CursorPosition location, so we need
+    # to truncate the command-line ($Command) up to the $CursorPosition location.
+    # Make sure the $Command is longer then the $CursorPosition before we truncate.
+    # This happens because the $Command does not include the last space.
+    if ($Command.Length -gt $CursorPosition) {
+        $Command = $Command.Substring(0, $CursorPosition)
+    }
+    __${name}_debug "Truncated command: $Command"
+
+    $ShellCompDirectiveError=${ShellCompDirectiveError}
+    $ShellCompDirectiveNoSpace=${ShellCompDirectiveNoSpace}
+    $ShellCompDirectiveNoFileComp=${ShellCompDirectiveNoFileComp}
+    $ShellCompDirectiveFilterFileExt=${ShellCompDirectiveFilterFileExt}
+    $ShellCompDirectiveFilterDirs=${ShellCompDirectiveFilterDirs}
+    $ShellCompDirectiveKeepOrder=${ShellCompDirectiveKeepOrder}
+
+    # Prepare the command to request completions for the program.
+    # Split the command at the first space to separate the program and arguments.
+    $Program, $Arguments = $Command.Split(" ", 2)
+
+    $RequestComp = "& ${exec} complete -- $Arguments"
+    __${name}_debug "RequestComp: $RequestComp"
+
+    # we cannot use $WordToComplete because it
+    # has the wrong values if the cursor was moved
+    # so use the last argument
+    if ($WordToComplete -ne "" ) {
+        $WordToComplete = $Arguments.Split(" ")[-1]
+    }
+    __${name}_debug "New WordToComplete: $WordToComplete"
+
+
+    # Check for flag with equal sign
+    $IsEqualFlag = ($WordToComplete -Like "--*=*" )
+    if ( $IsEqualFlag ) {
+        __${name}_debug "Completing equal sign flag"
+        # Remove the flag part
+        $Flag, $WordToComplete = $WordToComplete.Split("=", 2)
+    }
+
+    if ( $WordToComplete -eq "" -And ( -Not $IsEqualFlag )) {
+        # If the last parameter is complete (there is a space following it)
+        # We add an extra empty parameter so we can indicate this to the go method.
+        __${name}_debug "Adding extra empty parameter"
+        # PowerShell 7.2+ changed the way how the arguments are passed to executables,
+        # so for pre-7.2 or when Legacy argument passing is enabled we need to use
+        if ($PSVersionTable.PsVersion -lt [version]'7.2.0' -or
+            ($PSVersionTable.PsVersion -lt [version]'7.3.0' -and -not [ExperimentalFeature]::IsEnabled("PSNativeCommandArgumentPassing")) -or
+            (($PSVersionTable.PsVersion -ge [version]'7.3.0' -or [ExperimentalFeature]::IsEnabled("PSNativeCommandArgumentPassing")) -and
+              $PSNativeCommandArgumentPassing -eq 'Legacy')) {
+             $RequestComp="$RequestComp" + ' \`"\`"'
+        } else {
+             $RequestComp = "$RequestComp" + ' ""'
+        }
+    }
+
+    __${name}_debug "Calling $RequestComp"
+    # First disable ActiveHelp which is not supported for Powershell
+    $env:ActiveHelp = 0
+
+    # call the command store the output in $out and redirect stderr and stdout to null
+    # $Out is an array contains each line per element
+    Invoke-Expression -OutVariable out "$RequestComp" 2>&1 | Out-Null
+
+    # get directive from last line
+    [int]$Directive = $Out[-1].TrimStart(':')
+    if ($Directive -eq "") {
+        # There is no directive specified
+        $Directive = 0
+    }
+    __${name}_debug "The completion directive is: $Directive"
+
+    # remove directive (last element) from out
+    $Out = $Out | Where-Object { $_ -ne $Out[-1] }
+    __${name}_debug "The completions are: $Out"
+
+    if (($Directive -band $ShellCompDirectiveError) -ne 0 ) {
+        # Error code.  No completion.
+        __${name}_debug "Received error from custom completion go code"
+        return
+    }
+
+    $Longest = 0
+    [Array]$Values = $Out | ForEach-Object {
+        # Split the output in name and description
+        $Name, $Description = $_.Split("\`t", 2)
+        __${name}_debug "Name: $Name Description: $Description"
+
+        # Look for the longest completion so that we can format things nicely
+        if ($Longest -lt $Name.Length) {
+            $Longest = $Name.Length
+        }
+
+        # Set the description to a one space string if there is none set.
+        # This is needed because the CompletionResult does not accept an empty string as argument
+        if (-Not $Description) {
+            $Description = " "
+        }
+        @{ Name = "$Name"; Description = "$Description" }
+    }
+
+
+    $Space = " "
+    if (($Directive -band $ShellCompDirectiveNoSpace) -ne 0 ) {
+        # remove the space here
+        __${name}_debug "ShellCompDirectiveNoSpace is called"
+        $Space = ""
+    }
+
+    if ((($Directive -band $ShellCompDirectiveFilterFileExt) -ne 0 ) -or
+       (($Directive -band $ShellCompDirectiveFilterDirs) -ne 0 ))  {
+        __${name}_debug "ShellCompDirectiveFilterFileExt ShellCompDirectiveFilterDirs are not supported"
+
+        # return here to prevent the completion of the extensions
+        return
+    }
+
+    $Values = $Values | Where-Object {
+        # filter the result
+        $_.Name -like "$WordToComplete*"
+
+        # Join the flag back if we have an equal sign flag
+        if ( $IsEqualFlag ) {
+            __${name}_debug "Join the equal sign flag back to the completion value"
+            $_.Name = $Flag + "=" + $_.Name
+        }
+    }
+
+    # we sort the values in ascending order by name if keep order isn't passed
+    if (($Directive -band $ShellCompDirectiveKeepOrder) -eq 0 ) {
+        $Values = $Values | Sort-Object -Property Name
+    }
+
+    if (($Directive -band $ShellCompDirectiveNoFileComp) -ne 0 ) {
+        __${name}_debug "ShellCompDirectiveNoFileComp is called"
+
+        if ($Values.Length -eq 0) {
+            # Just print an empty string here so the
+            # shell does not start to complete paths.
+            # We cannot use CompletionResult here because
+            # it does not accept an empty string as argument.
+            ""
+            return
+        }
+    }
+
+    # Get the current mode
+    $Mode = (Get-PSReadLineKeyHandler | Where-Object { $_.Key -eq "Tab" }).Function
+    __${name}_debug "Mode: $Mode"
+
+    $Values | ForEach-Object {
+
+        # store temporary because switch will overwrite $_
+        $comp = $_
+
+        # PowerShell supports three different completion modes
+        # - TabCompleteNext (default windows style - on each key press the next option is displayed)
+        # - Complete (works like bash)
+        # - MenuComplete (works like zsh)
+        # You set the mode with Set-PSReadLineKeyHandler -Key Tab -Function <mode>
+
+        # CompletionResult Arguments:
+        # 1) CompletionText text to be used as the auto completion result
+        # 2) ListItemText   text to be displayed in the suggestion list
+        # 3) ResultType     type of completion result
+        # 4) ToolTip        text for the tooltip with details about the object
+
+        switch ($Mode) {
+
+            # bash like
+            "Complete" {
+
+                if ($Values.Length -eq 1) {
+                    __${name}_debug "Only one completion left"
+
+                    # insert space after value
+                    [System.Management.Automation.CompletionResult]::new($($comp.Name | __${name}_escapeStringWithSpecialChars) + $Space, "$($comp.Name)", 'ParameterValue', "$($comp.Description)")
+
+                } else {
+                    # Add the proper number of spaces to align the descriptions
+                    while($comp.Name.Length -lt $Longest) {
+                        $comp.Name = $comp.Name + " "
+                    }
+
+                    # Check for empty description and only add parentheses if needed
+                    if ($($comp.Description) -eq " " ) {
+                        $Description = ""
+                    } else {
+                        $Description = "  ($($comp.Description))"
+                    }
+
+                    [System.Management.Automation.CompletionResult]::new("$($comp.Name)$Description", "$($comp.Name)$Description", 'ParameterValue', "$($comp.Description)")
+                }
+             }
+
+            # zsh like
+            "MenuComplete" {
+                # insert space after value
+                # MenuComplete will automatically show the ToolTip of
+                # the highlighted value at the bottom of the suggestions.
+                [System.Management.Automation.CompletionResult]::new($($comp.Name | __${name}_escapeStringWithSpecialChars) + $Space, "$($comp.Name)", 'ParameterValue', "$($comp.Description)")
+            }
+
+            # TabCompleteNext and in case we get something unknown
+            Default {
+                # Like MenuComplete but we don't want to add a space here because
+                # the user need to press space anyway to get the completion.
+                # Description will not be shown because that's not possible with TabCompleteNext
+                [System.Management.Automation.CompletionResult]::new($($comp.Name | __${name}_escapeStringWithSpecialChars), "$($comp.Name)", 'ParameterValue', "$($comp.Description)")
+            }
+        }
+
+    }
+}
+
+Register-ArgumentCompleter -CommandName '${name}' -ScriptBlock $__${nameForVar}CompleterBlock
+`;
+}
+const ShellCompDirective = {
+	ShellCompDirectiveError: 1,
+	ShellCompDirectiveNoSpace: 2,
+	ShellCompDirectiveNoFileComp: 4,
+	ShellCompDirectiveFilterFileExt: 8,
+	ShellCompDirectiveFilterDirs: 16,
+	ShellCompDirectiveKeepOrder: 32,
+	shellCompDirectiveMaxValue: 64,
+	ShellCompDirectiveDefault: 0
+};
+var Completion = class {
+	commands = new Map();
+	completions = [];
+	directive = ShellCompDirective.ShellCompDirectiveDefault;
+	addCommand(name, description, args, handler, parent) {
+		const key = parent ? `${parent} ${name}` : name;
+		this.commands.set(key, {
+			name: key,
+			description,
+			args,
+			handler,
+			options: new Map(),
+			parent: parent ? this.commands.get(parent) : void 0
+		});
+		return key;
+	}
+	addOption(command, option, description, handler, alias) {
+		const cmd = this.commands.get(command);
+		if (!cmd) throw new Error(`Command ${command} not found.`);
+		cmd.options.set(option, {
+			description,
+			handler,
+			alias
+		});
+		return option;
+	}
+	stripOptions(args) {
+		const parts = [];
+		let option = false;
+		for (const k of args) {
+			if (k.startsWith("-")) {
+				option = true;
+				continue;
+			}
+			if (option) {
+				option = false;
+				continue;
+			}
+			parts.push(k);
+		}
+		return parts;
+	}
+	matchCommand(args) {
+		args = this.stripOptions(args);
+		const parts = [];
+		let remaining = [];
+		let matched = this.commands.get("");
+		for (let i = 0; i < args.length; i++) {
+			const k = args[i];
+			parts.push(k);
+			const potential = this.commands.get(parts.join(" "));
+			if (potential) matched = potential;
+			else {
+				remaining = args.slice(i, args.length);
+				break;
+			}
+		}
+		return [matched, remaining];
+	}
+	async parse(args) {
+		const endsWithSpace = args[args.length - 1] === "";
+		if (endsWithSpace) args.pop();
+		let toComplete = args[args.length - 1] || "";
+		const previousArgs = args.slice(0, -1);
+		if (endsWithSpace) {
+			previousArgs.push(toComplete);
+			toComplete = "";
+		}
+		const [matchedCommand] = this.matchCommand(previousArgs);
+		const lastPrevArg = previousArgs[previousArgs.length - 1];
+		if (this.shouldCompleteFlags(lastPrevArg, toComplete, endsWithSpace)) await this.handleFlagCompletion(matchedCommand, previousArgs, toComplete, endsWithSpace, lastPrevArg);
+		else {
+			if (this.shouldCompleteCommands(toComplete, endsWithSpace)) await this.handleCommandCompletion(previousArgs, toComplete);
+			if (matchedCommand && matchedCommand.args.length > 0) await this.handlePositionalCompletion(matchedCommand, previousArgs, toComplete, endsWithSpace);
+		}
+		this.complete(toComplete);
+	}
+	complete(toComplete) {
+		this.directive = ShellCompDirective.ShellCompDirectiveNoFileComp;
+		const seen = new Set();
+		this.completions.filter((comp) => {
+			if (seen.has(comp.value)) return false;
+			seen.add(comp.value);
+			return true;
+		}).filter((comp) => comp.value.startsWith(toComplete)).forEach((comp) => console.log(`${comp.value}\t${comp.description ?? ""}`));
+		console.log(`:${this.directive}`);
+	}
+	shouldCompleteFlags(lastPrevArg, toComplete, endsWithSpace) {
+		return lastPrevArg?.startsWith("--") || lastPrevArg?.startsWith("-") || toComplete.startsWith("--") || toComplete.startsWith("-");
+	}
+	shouldCompleteCommands(toComplete, endsWithSpace) {
+		return !toComplete.startsWith("-");
+	}
+	async handleFlagCompletion(command, previousArgs, toComplete, endsWithSpace, lastPrevArg) {
+		let flagName;
+		let valueToComplete = toComplete;
+		if (toComplete.includes("=")) {
+			const parts = toComplete.split("=");
+			flagName = parts[0];
+			valueToComplete = parts[1] || "";
+		} else if (lastPrevArg?.startsWith("-")) flagName = lastPrevArg;
+		if (flagName) {
+			let option = command.options.get(flagName);
+			if (!option) {
+				for (const [name, opt] of command.options) if (opt.alias && `-${opt.alias}` === flagName) {
+					option = opt;
+					flagName = name;
+					break;
+				}
+			}
+			if (option) {
+				const suggestions = await option.handler(previousArgs, valueToComplete, endsWithSpace);
+				if (toComplete.includes("=")) this.completions = suggestions.map((suggestion) => ({
+					value: `${flagName}=${suggestion.value}`,
+					description: suggestion.description
+				}));
+				else this.completions.push(...suggestions);
+			}
+			return;
+		}
+		if (toComplete.startsWith("-")) {
+			const isShortFlag = toComplete.startsWith("-") && !toComplete.startsWith("--");
+			for (const [name, option] of command.options) if (isShortFlag) {
+				if (option.alias && `-${option.alias}`.startsWith(toComplete)) this.completions.push({
+					value: `-${option.alias}`,
+					description: option.description
+				});
+			} else if (name.startsWith(toComplete)) this.completions.push({
+				value: name,
+				description: option.description
+			});
+		}
+	}
+	async handleCommandCompletion(previousArgs, toComplete) {
+		const commandParts = [...previousArgs].filter(Boolean);
+		for (const [k, command] of this.commands) {
+			if (k === "") continue;
+			const parts = k.split(" ");
+			let match = true;
+			let i = 0;
+			while (i < commandParts.length) {
+				if (parts[i] !== commandParts[i]) {
+					match = false;
+					break;
+				}
+				i++;
+			}
+			if (match && parts[i]?.startsWith(toComplete)) this.completions.push({
+				value: parts[i],
+				description: command.description
+			});
+		}
+	}
+	async handlePositionalCompletion(command, previousArgs, toComplete, endsWithSpace) {
+		const suggestions = await command.handler(previousArgs, toComplete, endsWithSpace);
+		this.completions.push(...suggestions);
+	}
+};
+function script(shell, name, x) {
+	switch (shell) {
+		case "zsh": {
+			const script$1 = generate(name, x);
+			console.log(script$1);
+			break;
+		}
+		case "bash": {
+			const script$1 = generate$3(name, x);
+			console.log(script$1);
+			break;
+		}
+		case "fish": {
+			const script$1 = generate$2(name, x);
+			console.log(script$1);
+			break;
+		}
+		case "powershell": {
+			const script$1 = generate$1(name, x);
+			console.log(script$1);
+			break;
+		}
+		default: throw new Error(`Unsupported shell: ${shell}`);
+	}
+}
+function generate(name, exec) {
+	return `#compdef ${name}
+compdef _${name} ${name}
+
+# zsh completion for ${name} -*- shell-script -*-
+
+__${name}_debug() {
+    local file="$BASH_COMP_DEBUG_FILE"
+    if [[ -n \${file} ]]; then
+        echo "$*" >> "\${file}"
+    fi
+}
+
+_${name}() {
+    local shellCompDirectiveError=${ShellCompDirective.ShellCompDirectiveError}
+    local shellCompDirectiveNoSpace=${ShellCompDirective.ShellCompDirectiveNoSpace}
+    local shellCompDirectiveNoFileComp=${ShellCompDirective.ShellCompDirectiveNoFileComp}
+    local shellCompDirectiveFilterFileExt=${ShellCompDirective.ShellCompDirectiveFilterFileExt}
+    local shellCompDirectiveFilterDirs=${ShellCompDirective.ShellCompDirectiveFilterDirs}
+    local shellCompDirectiveKeepOrder=${ShellCompDirective.ShellCompDirectiveKeepOrder}
+
+    local lastParam lastChar flagPrefix requestComp out directive comp lastComp noSpace keepOrder
+    local -a completions
+
+    __${name}_debug "\\n========= starting completion logic =========="
+    __${name}_debug "CURRENT: \${CURRENT}, words[*]: \${words[*]}"
+
+    # The user could have moved the cursor backwards on the command-line.
+    # We need to trigger completion from the $CURRENT location, so we need
+    # to truncate the command-line ($words) up to the $CURRENT location.
+    # (We cannot use $CURSOR as its value does not work when a command is an alias.)
+    words=( "\${=words[1,CURRENT]}" )
+    __${name}_debug "Truncated words[*]: \${words[*]},"
+
+    lastParam=\${words[-1]}
+    lastChar=\${lastParam[-1]}
+    __${name}_debug "lastParam: \${lastParam}, lastChar: \${lastChar}"
+
+    # For zsh, when completing a flag with an = (e.g., ${name} -n=<TAB>)
+    # completions must be prefixed with the flag
+    setopt local_options BASH_REMATCH
+    if [[ "\${lastParam}" =~ '-.*=' ]]; then
+        # We are dealing with a flag with an =
+        flagPrefix="-P \${BASH_REMATCH}"
+    fi
+
+    # Prepare the command to obtain completions, ensuring arguments are quoted for eval
+    local -a args_to_quote=("\${(@)words[2,-1]}")
+    if [ "\${lastChar}" = "" ]; then
+        # If the last parameter is complete (there is a space following it)
+        # We add an extra empty parameter so we can indicate this to the go completion code.
+        __${name}_debug "Adding extra empty parameter"
+        args_to_quote+=("")
+    fi
+
+    # Use Zsh's (q) flag to quote each argument safely for eval
+    local quoted_args=("\${(@q)args_to_quote}")
+
+    # Join the main command and the quoted arguments into a single string for eval
+    requestComp="${exec} complete -- \${quoted_args[*]}"
+
+    __${name}_debug "About to call: eval \${requestComp}"
+
+    # Use eval to handle any environment variables and such
+    out=$(eval \${requestComp} 2>/dev/null)
+    __${name}_debug "completion output: \${out}"
+
+    # Extract the directive integer following a : from the last line
+    local lastLine
+    while IFS='\n' read -r line; do
+        lastLine=\${line}
+    done < <(printf "%s\n" "\${out[@]}")
+    __${name}_debug "last line: \${lastLine}"
+
+    if [ "\${lastLine[1]}" = : ]; then
+        directive=\${lastLine[2,-1]}
+        # Remove the directive including the : and the newline
+        local suffix
+        (( suffix=\${#lastLine}+2))
+        out=\${out[1,-$suffix]}
+    else
+        # There is no directive specified.  Leave $out as is.
+        __${name}_debug "No directive found.  Setting to default"
+        directive=0
+    fi
+
+    __${name}_debug "directive: \${directive}"
+    __${name}_debug "completions: \${out}"
+    __${name}_debug "flagPrefix: \${flagPrefix}"
+
+    if [ $((directive & shellCompDirectiveError)) -ne 0 ]; then
+        __${name}_debug "Completion received error. Ignoring completions."
+        return
+    fi
+
+    local activeHelpMarker="%"
+    local endIndex=\${#activeHelpMarker}
+    local startIndex=$((\${#activeHelpMarker}+1))
+    local hasActiveHelp=0
+    while IFS='\n' read -r comp; do
+        # Check if this is an activeHelp statement (i.e., prefixed with $activeHelpMarker)
+        if [ "\${comp[1,$endIndex]}" = "$activeHelpMarker" ];then
+            __${name}_debug "ActiveHelp found: $comp"
+            comp="\${comp[$startIndex,-1]}"
+            if [ -n "$comp" ]; then
+                compadd -x "\${comp}"
+                __${name}_debug "ActiveHelp will need delimiter"
+                hasActiveHelp=1
+            fi
+            continue
+        fi
+
+        if [ -n "$comp" ]; then
+            # If requested, completions are returned with a description.
+            # The description is preceded by a TAB character.
+            # For zsh's _describe, we need to use a : instead of a TAB.
+            # We first need to escape any : as part of the completion itself.
+            comp=\${comp//:/\\:}
+
+            local tab="$(printf '\\t')"
+            comp=\${comp//$tab/:}
+
+            __${name}_debug "Adding completion: \${comp}"
+            completions+=\${comp}
+            lastComp=$comp
+        fi
+    done < <(printf "%s\n" "\${out[@]}")
+
+    # Add a delimiter after the activeHelp statements, but only if:
+    # - there are completions following the activeHelp statements, or
+    # - file completion will be performed (so there will be choices after the activeHelp)
+    if [ $hasActiveHelp -eq 1 ]; then
+        if [ \${#completions} -ne 0 ] || [ $((directive & shellCompDirectiveNoFileComp)) -eq 0 ]; then
+            __${name}_debug "Adding activeHelp delimiter"
+            compadd -x "--"
+            hasActiveHelp=0
+        fi
+    fi
+
+    if [ $((directive & shellCompDirectiveNoSpace)) -ne 0 ]; then
+        __${name}_debug "Activating nospace."
+        noSpace="-S ''"
+    fi
+
+    if [ $((directive & shellCompDirectiveKeepOrder)) -ne 0 ]; then
+        __${name}_debug "Activating keep order."
+        keepOrder="-V"
+    fi
+
+    if [ $((directive & shellCompDirectiveFilterFileExt)) -ne 0 ]; then
+        # File extension filtering
+        local filteringCmd
+        filteringCmd='_files'
+        for filter in \${completions[@]}; do
+            if [ \${filter[1]} != '*' ]; then
+                # zsh requires a glob pattern to do file filtering
+                filter="\\*.$filter"
+            fi
+            filteringCmd+=" -g $filter"
+        done
+        filteringCmd+=" \${flagPrefix}"
+
+        __${name}_debug "File filtering command: $filteringCmd"
+        _arguments '*:filename:'"$filteringCmd"
+    elif [ $((directive & shellCompDirectiveFilterDirs)) -ne 0 ]; then
+        # File completion for directories only
+        local subdir
+        subdir="\${completions[1]}"
+        if [ -n "$subdir" ]; then
+            __${name}_debug "Listing directories in $subdir"
+            pushd "\${subdir}" >/dev/null 2>&1
+        else
+            __${name}_debug "Listing directories in ."
+        fi
+
+        local result
+        _arguments '*:dirname:_files -/'" \${flagPrefix}"
+        result=$?
+        if [ -n "$subdir" ]; then
+            popd >/dev/null 2>&1
+        fi
+        return $result
+    else
+        __${name}_debug "Calling _describe"
+        if eval _describe $keepOrder "completions" completions -Q \${flagPrefix} \${noSpace}; then
+            __${name}_debug "_describe found some completions"
+
+            # Return the success of having called _describe
+            return 0
+        else
+            __${name}_debug "_describe did not find completions."
+            __${name}_debug "Checking if we should do file completion."
+            if [ $((directive & shellCompDirectiveNoFileComp)) -ne 0 ]; then
+                __${name}_debug "deactivating file completion"
+
+                # We must return an error code here to let zsh know that there were no
+                # completions found by _describe; this is what will trigger other
+                # matching algorithms to attempt to find completions.
+                # For example zsh can match letters in the middle of words.
+                return 1
+            else
+                # Perform file completion
+                __${name}_debug "Activating file completion"
+
+                # We must return the result of this command, so it must be the
+                # last command, or else we must store its result to return it.
+                _arguments '*:filename:_files'" \${flagPrefix}"
+            fi
+        fi
+    fi
+}
+
+# don't run the completion function when being sourced or eval-ed
+if [ "\${funcstack[1]}" = "_${name}" ]; then
+    _${name}
+fi
+`;
+}
+
+//#endregion
+//#region ../gunshi/src/utils.ts
+function isLazyCommand(cmd) {
+	return typeof cmd === "function" && "commandName" in cmd && !!cmd.commandName;
+}
+async function resolveLazyCommand(cmd, name, needRunResolving = false) {
+	let command;
+	if (isLazyCommand(cmd)) {
+		const baseCommand = {
+			name: cmd.commandName,
+			description: cmd.description,
+			args: cmd.args,
+			examples: cmd.examples,
+			internal: cmd.internal,
+			entry: cmd.entry
+		};
+		if ("resource" in cmd && cmd.resource) baseCommand.resource = cmd.resource;
+		command = Object.assign(create(), baseCommand);
+		if (needRunResolving) {
+			const loaded = await cmd();
+			if (typeof loaded === "function") command.run = loaded;
+			else if (typeof loaded === "object") {
+				if (loaded.run == null) throw new TypeError(`'run' is required in command: ${cmd.name || name}`);
+				command.run = loaded.run;
+				command.name = loaded.name;
+				command.description = loaded.description;
+				command.args = loaded.args;
+				command.examples = loaded.examples;
+				command.internal = loaded.internal;
+				command.entry = loaded.entry;
+				if ("resource" in loaded && loaded.resource) command.resource = loaded.resource;
+			} else throw new TypeError(`Cannot resolve command: ${cmd.name || name}`);
+		}
+	} else command = Object.assign(create(), cmd);
+	if (command.name == null && name) command.name = name;
+	return deepFreeze(command);
+}
+function create(obj = null) {
+	return Object.create(obj);
+}
+function deepFreeze(obj, ignores = []) {
+	if (obj === null || typeof obj !== "object") return obj;
+	for (const key of Object.keys(obj)) {
+		const value = obj[key];
+		if (ignores.includes(key)) continue;
+		if (typeof value === "object" && value !== null) deepFreeze(value, ignores);
+	}
+	return Object.freeze(obj);
+}
+
+//#endregion
+//#region ../shared/src/constants.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+const BUILT_IN_PREFIX = "_";
+const PLUGIN_PREFIX = "g";
+const ARG_PREFIX = "arg";
+const BUILT_IN_KEY_SEPARATOR = ":";
+const BUILD_IN_PREFIX_AND_KEY_SEPARATOR = `${BUILT_IN_PREFIX}${BUILT_IN_KEY_SEPARATOR}`;
+const ARG_PREFIX_AND_KEY_SEPARATOR = `${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}`;
+
+//#endregion
+//#region ../shared/src/utils.ts
+function namespacedId(id) {
+	return `${PLUGIN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${id}`;
+}
+
+//#endregion
+//#region src/types.ts
+/**
+* The unique identifier for the completion plugin.
+*/
+const pluginId = namespacedId("completion");
+
+//#endregion
+//#region src/utils.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+function detectRuntime() {
+	if (globalThis.process !== void 0 && globalThis.process.release?.name === "node") return "node";
+	if (globalThis.Deno !== void 0) return "deno";
+	if (globalThis.Bun !== void 0) return "bun";
+	return "unknown";
+}
+function quoteIfNeeded(path) {
+	return path.includes(" ") ? `'${path}'` : path;
+}
+function quoteExec() {
+	const runtime = detectRuntime();
+	switch (runtime) {
+		case "node": {
+			const execPath = globalThis.process.execPath;
+			const processArgs = globalThis.process.argv.slice(1);
+			const quotedExecPath = quoteIfNeeded(execPath);
+			const quotedProcessArgs = processArgs.map(quoteIfNeeded);
+			const quotedProcessExecArgs = globalThis.process.execArgv.map(quoteIfNeeded);
+			return `${quotedExecPath} ${quotedProcessExecArgs.join(" ")} ${quotedProcessArgs[0]}`;
+		}
+		case "deno": throw new Error("deno not implemented yet, welcome contributions :)");
+		case "bun": throw new Error("bun not implemented yet, welcome contributions :)");
+		default: throw new Error("Unsupported your javascript runtime for completion script generation.");
+	}
+}
+
+//#endregion
 //#region src/index.ts
+const TERMINATOR = "--";
+const NOOP_HANDLER = () => {
+	return [];
+};
 /**
 * completion plugin for gunshi
 */
-function completion() {
+function completion(options = {}) {
+	const config = options.config || {};
+	const completion$1 = new Completion();
 	return plugin({
-		id: "g:completion",
+		id: pluginId,
 		name: "completion",
-		setup(_ctx) {}
+		async setup(ctx) {
+			/**
+			* add command for completion script generation
+			*/
+			const completeName = "complete";
+			ctx.addCommand(completeName, {
+				name: completeName,
+				description: "Generate shell completion script",
+				run: async (cmdCtx) => {
+					if (!cmdCtx.env.name) throw new Error("your cli name is not defined.");
+					let shell = cmdCtx._[1];
+					if (shell === TERMINATOR) shell = void 0;
+					if (shell === void 0) {
+						const extra = cmdCtx._.slice(cmdCtx._.indexOf(TERMINATOR) + 1);
+						await completion$1.parse(extra);
+					} else script(shell, cmdCtx.env.name, quoteExec());
+				}
+			});
+			/**
+			* disable header renderer
+			*/
+			ctx.decorateHeaderRenderer(async (_baseRenderer, _cmdCtx) => "");
+		},
+		extension: (_ctx, _cmd) => {
+			return {};
+		},
+		onExtension: async (ctx, _cmd) => {
+			const subCommands = ctx.env.subCommands;
+			const entry = [...subCommands].map(([_, cmd]) => cmd).find((cmd) => cmd.entry);
+			if (!entry) throw new Error("entry command not found.");
+			const isPositional = hasPositional(await resolveLazyCommand(entry));
+			const root = "";
+			completion$1.addCommand(root, entry.description || "", isPositional ? [false] : [], NOOP_HANDLER);
+			const args = entry.args || Object.create(null);
+			for (const [key, schema] of Object.entries(args)) {
+				if (schema.type === "positional") continue;
+				completion$1.addOption(root, `--${key}`, schema.description || "", config.entry?.args?.[key]?.handler || NOOP_HANDLER, schema.short);
+			}
+			await handleSubCommands(completion$1, subCommands, config.subCommands);
+		}
 	});
 }
+async function handleSubCommands(completion$1, subCommands, configs = {}) {
+	for (const [name, cmd] of subCommands) {
+		if (cmd.internal || cmd.entry || name === "complete") continue;
+		const resolvedCmd = await resolveLazyCommand(cmd);
+		const isPositional = hasPositional(resolvedCmd);
+		const commandName = completion$1.addCommand(name, resolvedCmd.description || "", isPositional ? [false] : [], configs?.[name]?.handler || NOOP_HANDLER);
+		const args = resolvedCmd.args || Object.create(null);
+		for (const [key, schema] of Object.entries(args)) {
+			if (schema.type === "positional") continue;
+			completion$1.addOption(commandName, `--${key}`, schema.description || "", configs[commandName]?.args?.[key]?.handler || NOOP_HANDLER, schema.short);
+		}
+	}
+}
+function hasPositional(cmd) {
+	return cmd.args && Object.values(cmd.args).some((arg) => arg.type === "positional");
+}
 
 //#endregion
-export { completion as default };
+export { completion as default, pluginId };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin-completion",
   "description": "completion plugin for gunshi",
-  "version": "0.27.0-alpha.6",
+  "version": "0.27.0-alpha.7",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -52,18 +52,21 @@
     }
   },
   "dependencies": {
-    "@gunshi/plugin": "0.27.0-alpha.6"
+    "@bombsh/tab": "https://pkg.pr.new/bombshell-dev/tab@main",
+    "@gunshi/plugin": "0.27.0-alpha.7"
   },
   "devDependencies": {
+    "@types/node": "^22.16.0",
     "deno": "^2.4.0",
     "jsr": "^0.13.5",
     "jsr-exports-lint": "^0.4.1",
     "publint": "^0.3.12",
-    "tsdown": "^0.12.9"
+    "tsdown": "^0.12.9",
+    "@gunshi/shared": "0.27.0-alpha.7"
   },
   "scripts": {
     "build": "tsdown",
     "lint:jsr": "jsr publish --dry-run --allow-dirty",
-    "typecheck:deno": "deno check ./src"
+    "typecheck:deno": "deno check --import-map=../../importmap.json ./src"
   }
 }